Skip to content

chore: sync CLI to OpenAPI spec#101

Merged
yorkable merged 2 commits into
mainfrom
spec-sync-smart-turn-timeout
Jun 5, 2026
Merged

chore: sync CLI to OpenAPI spec#101
yorkable merged 2 commits into
mainfrom
spec-sync-smart-turn-timeout

Conversation

@yorkable

@yorkable yorkable commented Jun 5, 2026

Copy link
Copy Markdown
Contributor

Spec sync — BridgePhrasesConfig.smart_turn_timeout_seconds

Automated reconciliation of the embedded OpenAPI spec against upstream
(asksyllable/syllable-sdk-typescript@main).

diff_specs.py report

## CHANGED SCHEMAS — field-level diffs (1)

~ BridgePhrasesConfig
  + smart_turn_timeout_seconds: anyOf

## SUMMARY
  Paths:   +0 added, -0 removed, ~0 changed
  Schemas: +0 added, -0 removed, ~1 changed
  Enums:   ~0 changed (0 with removed values — breaking)

The new field:

"smart_turn_timeout_seconds": {
  "anyOf": [ { "type": "number", "maximum": 30.0, "minimum": 0.25 }, { "type": "null" } ],
  "title": "Smart Turn Timeout Seconds",
  "description": "Seconds of caller silence before injecting the first bridge phrase. Subsequent sleep intervals are 2x, 3x, 4x this base. When unset, the service-wide default applies."
}

Code impact

None required. BridgePhrasesConfig is consumed only by conversation-config bridges-update, which accepts an arbitrary JSON body via --file (no per-field flags), so the new optional field passes through transparently. The field is not surfaced anywhere else in cmd/*.go.

The remaining lines in the spec diff are auto-rolling example timestamps (20260604.920260605.9, etc.) that change daily upstream — cosmetic, no structural effect.

Changes

  • scripts/syllable-cli/internal/spec/openapi.json — verbatim upstream copy
  • AGENTS.md — note the new field in the Conversation Config section

Breaking changes

None. Purely additive: one new optional nullable field on an existing schema. No removed paths/commands/flags, no changed/removed enum values, no newly-required fields, no narrowed types.

Release notes

conversation-config bridges-update now accepts a smart_turn_timeout_seconds
field in the bridge-phrases JSON body — tunes how long an agent waits on caller
silence before the first bridge phrase (0.25–30s; subsequent intervals scale
2x/3x/4x). Optional; the service-wide default applies when unset.

Tests

go test ./... passes (cmd, integration, internal/spec, client, output).

🤖 Generated with Claude Code

yorkable and others added 2 commits June 5, 2026 06:12
@yorkable yorkable added the spec-sync Reconciliation PR — run the live integration check label Jun 5, 2026
@yorkable

yorkable commented Jun 5, 2026

Copy link
Copy Markdown
Contributor Author

Two-pass review

Self-review — APPROVE

  • Spec diff: only structural change is the new optional nullable field smart_turn_timeout_seconds on BridgePhrasesConfig. All other lines are auto-rolling example timestamps. Verified with diff_specs.py (1 changed schema, 0 paths, 0 enums) and by filtering the raw git diff.
  • Method + path: no new/changed paths. conversation-config bridges (GET) and bridges-update (PUT) target /api/v1/conversation-config/bridges — item-style path, no trailing slash, unchanged. No 307/header-drop risk introduced.
  • Flag ↔ schema parity: bridges-update is file-based (--file → arbitrary JSON body → PUT). No per-field flags exist, so the new optional field passes through with no code change. grep confirms BridgePhrasesConfig is not referenced in any cmd/*.go.
  • Required / type / enum: field is optional and nullable; nothing newly required, no narrowed type, no removed/changed enum value.
  • Integration test: no new command added, so no new live test is required; existing conversation-config coverage is unaffected.
  • Tests: cd scripts/syllable-cli && go test ./... passes (cmd, integration, internal/spec, client, output).

Codex review — APPROVE

Independent pass confirmed: (1) spec diff is purely additive after stripping example timestamps — no removed paths/enums/fields, field is nullable with no required entry; (2) bridges-update is file-based, no per-field flags, no code change needed; (3) classification PURELY ADDITIVE. Codex could not run go test inside its sandbox (a temp-dir permission restriction, not a code failure) — tests were run and pass locally, covering that gap.

Additive-vs-breaking classification — PURELY ADDITIVE

One new optional, nullable field on an existing schema. No removed paths/commands/flags, no removed/changed enum values, no newly-required fields, no narrowed types or changed semantics. Both passes independently confirm this. Opened as a normal (non-draft) PR.

@yorkable

yorkable commented Jun 5, 2026

Copy link
Copy Markdown
Contributor Author

Independent verifier verdict — ✅ verified, ⏸️ holding the merge/publish for a human

I re-derived everything from source (not from this PR's narrative). Result: purely additive, all gates green, ready to merge + release as a patch. But I'm not self-merging — see the rollout-conflict note at the bottom.

Diff (re-derived independently)

diff_specs.py between origin/main and the PR head:

  • One schema changed: BridgePhrasesConfig — one added field smart_turn_timeout_seconds (anyOf: number 0.25–30 | null).
  • Mechanical confirmation: the schema is byte-identical after removing that field, and required is unchanged (the field is optional + nullable, not newly required).
  • 0 added/removed/changed paths, 0 added/removed schemas, 0 enum changes, 0 removed/changed fields.
  • The remaining JSON line churn is the rolling example timestamps — cosmetic.

Classification: purely additive. No removed paths/commands/flags, no removed enum values, no newly-required fields, no narrowed types.

Gates (read mechanically from check JSON)

  • testSUCCESS (×2)
  • live-checkSUCCESS (ran against the cli-test org; not skipped)
  • Not a draft; mergeStateStatus: CLEAN.
  • No new command/path is added, so Stage-1 new-command coverage is N/A — the field rides through the existing conversation-config bridges-update command, which already has a test.

Code spot-check

bridges-update unmarshals an arbitrary JSON --file body into interface{} and PUTs it to /api/v1/conversation-config/bridges. The new optional field passes through transparently — zero code change required, which matches the PR. AGENTS.md documents the field correctly.

Recommended action

Merge --squash --delete-branch, then cut a patch release v1.7.2 (additive field only → patch; latest is v1.7.1), with release notes taken from this PR's Release notes section, then merge the Homebrew cask PR. Closing #102 on merge (PR body lacks a Closes #N).


⏸️ Why I'm not merging this myself

There's a rollout-configuration conflict I won't resolve autonomously for an irreversible publish:

  • The scheduled task that invoked this run (syllable-cli-merge) carries the phased "Phase A — review only, do not merge" prompt.
  • My notes + the repo's canonical routines/merger.md describe the full verify→merge→publish cycle.

Live evidence (the running routine's own prompt) says review-only, so I'm treating this as Phase A: verify + report, no merge/tag/cask. @joshyork — this is the watched first cycle. If full-cycle is intended, either merge+tag this (one command) or repoint the routine at merger.md; if review-only is intended, this verdict is your green light to merge by hand.

@yorkable
yorkable merged commit 322a958 into main Jun 5, 2026
3 checks passed
@yorkable
yorkable deleted the spec-sync-smart-turn-timeout branch June 5, 2026 16:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

spec-sync Reconciliation PR — run the live integration check

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant