Skip to content

feat: sync CLI to OpenAPI spec#162

Draft
yorkable wants to merge 3 commits into
mainfrom
spec-sync-sessions-timeline
Draft

feat: sync CLI to OpenAPI spec#162
yorkable wants to merge 3 commits into
mainfrom
spec-sync-sessions-timeline

Conversation

@yorkable

@yorkable yorkable commented Jun 25, 2026

Copy link
Copy Markdown
Contributor

Syncs the CLI to the latest upstream OpenAPI spec. Purely additive — adds one new read-only command and supporting schemas; nothing removed, narrowed, or newly required.

What changed

Adds syllable sessions timeline <session-id> for the new endpoint GET /api/v1/sessions/timeline/{session_id}. It returns a single consolidated, time-ordered stream of a session's transcript turns, tool calls, and latency events, each with an offset from session start. Mirrors the existing transcript command (read-only GET, JSON or table output).

A live integration test (TestSessionsTimeline) lists one session — with --include-test so a throwaway CI org still has a session to exercise — fetches its timeline, and asserts valid JSON. It skips cleanly when the org has no sessions.

diff_specs.py report

## NEW PATHS (1)
+ /api/v1/sessions/timeline/{session_id}
  GET — Get Session Timeline By Id ['sessions.timeline']

## NEW SCHEMAS (3)
+ SessionTimelineResponse
+ TimelineEvent
+ TimelineEventKind

## CHANGED SCHEMAS — field-level diffs (1)
~ SessionAction
  + duration_ms: anyOf   (new optional response field; no flag/body change)

## CHANGED ENUMS — member diffs (1)
~ TimelineEventKind   (new enum: transcript, tool, latency)

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

Breaking changes

None. No removed commands/flags, no removed enum values, no newly-required fields, no narrowed types. SessionAction.duration_ms is a new optional response field (the latency command prints raw JSON, so it flows through with no code change).

Release notes

  • New: syllable sessions timeline <session-id> — a consolidated, time-ordered view of a session combining transcript turns, tool calls, and latency events with offsets from the session start.

No spec-drift issue is open at reconcile time (the daily detector hasn't filed one for this change), so there is no issue to Closes. It self-heals: once this merges, the embedded spec matches upstream and the detector files nothing.

🤖 Generated with Claude Code

yorkable and others added 3 commits June 25, 2026 06:16
@yorkable @claude
chore: update embedded OpenAPI spec (sessions timeline)
ca765bc 
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
@yorkable @claude
feat: add 'sessions timeline' command
007834a 
Adds GET /api/v1/sessions/timeline/{session_id} as 'syllable sessions
timeline <id>' — a consolidated, time-ordered stream of transcript turns,
tool calls, and latency events. Read-only, mirrors the transcript command.
Includes a live integration test (skips when the org has no sessions).

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
@yorkable @claude
docs: document 'sessions timeline' subcommand
c089252 
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
@yorkable yorkable added the spec-sync Reconciliation PR — run the live integration check label Jun 25, 2026
@yorkable

yorkable commented Jun 25, 2026

Copy link
Copy Markdown
Contributor Author

🤖 spec-sync routine — blocked on a red gate, leaving for a human.

This PR is purely additive and the test gate is green. But live-check is RED, so the routine will not auto-merge.

The failure is not this PR's change. It's the known pre-existing backend bug:

TestAgentsCRUD: agents create → 404 {"detail":"Voice (redi) channel not found"}
--- FAIL: TestAgentsCRUD

This is the same redi voice-default backend issue that has failed the daily live-check since ~2026-06-17, unrelated to the CLI. It blocks every spec-sync PR's live gate until the backend is fixed (or TestAgentsCRUD is adjusted to not depend on the redi default).

This PR's own new test passed/skipped cleanly:

--- SKIP: TestSessionsTimeline (no sessions in the CI org; skips by design)

The new sessions timeline command therefore isn't exercised live yet (the throwaway CI org has no sessions, even with --include-test) — flagging per the skill's "say so explicitly" rule.

Recommended action: confirm the live-check red is solely the pre-existing redi/TestAgentsCRUD failure (it is, per the log above), then merge manually — or fix the backend redi default so the gate goes green. Do not expect the routine to self-merge while live-check stays red.

@yorkable

@yorkable yorkable self-assigned this Jun 25, 2026
@yorkable yorkable mentioned this pull request Jun 30, 2026
Open
@yorkable

yorkable commented Jun 30, 2026

Copy link
Copy Markdown
Contributor Author

Converted to draft — holding the release: the sessions timeline endpoint isn't deployed on prod yet.

The spec→code sync here is correct and purely additive, and CI is now green (the earlier red live-check was the unrelated agent-create backend bug, since fixed). But a live probe against cli-test shows prod hasn't deployed GET /api/v1/sessions/timeline/{session_id}, so syllable sessions timeline would be dead on arrival — a bare 404 {"detail":"Not Found"} for every id.

Evidence (same nonexistent id, --debug, CLI built from this branch):

  • sessions latency <id> (deployed sibling) → 404 {"detail":"Session not found: 00000000-..."} — handler-generated, route is live.
  • sessions timeline <id> → 404 {"detail":"Not Found"} — framework default for an unmatched route, i.e. not deployed.

Drafted so the spec-sync routine treats this as human-flagged (case C) and doesn't auto-merge/release a broken command. Prod gap tracked in #165.

To ship: once the backend deploys the route, re-run the probe to confirm, then gh pr ready this PR — it will merge and release on the next routine fire. Until then, spec-drift #164 stays open intentionally (we're deliberately behind upstream because prod can't serve this endpoint).

@yorkable
yorkable marked this pull request as draft June 30, 2026 04:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@yorkable yorkable

Labels

spec-sync Reconciliation PR — run the live integration check

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@yorkable