feat(chat): add GET /api/chat/{chatId}/stream to resume an in-progress response
Implements the resume route for chat#1923. Contract: docs#286.
Why
The endpoint was already documented and never implemented. api-reference/chat/workflow-stream.mdx ("Resume Chat Stream") and a full spec block have shipped since the workflow cutover, cross-referenced from POST /api/chat, POST /api/chat/runs and GET /api/chat/runs/{runId} — but app/api/chat/[chatId]/ contained only stop/. Documented-but-missing drift.
It matters now because a long turn's SSE stream can end before the run does. Reproduced on prod 2026-08-02 (wrun_01KZ04KVHBVA405WDFVYCEADE8): the stream closed at ~123 s with a clean data: [DONE] and no finish chunk while the workflow ran on to completion. The client rendered 6 of 13 iterations and froze — no stop button, composer idle — while everything after was generated and persisted but never delivered. Our only recovery path, maybeResumeChatStream, runs inside POST /api/chat, which is why a page refresh recovered and sitting still did not.
What
| File | Role |
|---|---|
app/api/chat/[chatId]/stream/route.ts | GET + OPTIONS. maxDuration = 800 to match POST /api/chat — a resumed stream lives as long as the turn it follows. |
lib/chat/handleResumeChatStream.ts | 200 SSE + x-workflow-run-id when live; 204 when nothing to resume (clearing a stale active_stream_id); 502 when the status lookup throws. |
lib/chat/parseStreamStartIndex.ts | The documented integer, minimum 0. |
lib/chat/validateChatOwnership.ts | Extracted from validateStopChatWorkflowRequest so /stop and /stream share one auth + ownership rule. |
Reuses the existing wrapWorkflowStreamWatcher, so a resumed stream gets the same tool-call reconciliation and cancel-propagation as the primary one.
Two deliberate calls
Negative startIndex is rejected (400) even though the SDK accepts it. The SDK reads negative values relative to the end of a live stream, which resolves to a different absolute position on every call — it cannot give a client a gap-free resume, and the docs warn about exactly this. The published contract is minimum: 0.
A failed status read returns 502, not 204. Reporting "nothing to resume" on a transient workflow-api blip would tell a client with a live run to stop reconnecting — precisely the silent truncation this route exists to prevent. This mirrors reconcileExistingActiveStream, which already prefers conflict over clearing a slot it cannot confidently read.
Tests — RED before GREEN, per unit
parseStreamStartIndex (6): absent → undefined; valid 0 and 42; 400 for non-numeric, negative, fractional, and present-but-empty.
handleResumeChatStream (8): 204 with no active stream (and no getRun call); 204 + stale-id clear on a terminal run; 200 with x-workflow-run-id and text/event-stream; startIndex forwarded to getReadable; undefined forwarded when absent; 400 on malformed startIndex without touching the run; validator responses (401/403/404) propagated unchanged; 502 rather than 204 when the status lookup throws.
Both files confirmed failing first (module-not-found), then implemented to green.
- Full api suite: 4,321 tests / 796 files passing.
tsc --noEmit: 203 errors, zero in any file this PR touches — identical to themainbaseline (203).eslintclean.
Verification still owed
Preview verification against a live in-flight run is not done yet and is the gate here: start a long turn, reconnect mid-run with a startIndex, and confirm the resumed stream continues without duplicating or skipping chunks, plus the 204 / 400 / 403 paths against real ids. Results will be posted as a comment.
Merge order
docs#286 → this → chat client reconnect. The docs PR publishes the startIndex parameter this implements.
🤖 Generated with Claude Code
Summary by cubic
Adds GET /api/chat/{chatId}/stream to resume an in-progress chat response and make headless runs watchable live. Also honors the account_id admin override and returns a stream tail index for precise reconnects.
-
New Features
- Resume route with
startIndex(>= 0). Returns 200 SSE withx-workflow-run-idand best-effortx-workflow-stream-tail-index; 204 when nothing to resume (clears staleactive_stream_id); 502 on run-status read failures. - Headless runs claim
chats.active_stream_idon start soGET /api/chat/{chatId}/streamcan watch their output live. - Reuses the existing stream watcher;
maxDuration = 800; adds CORSOPTIONS.
- Resume route with
-
Bug Fixes
- Honors
account_idquery override for org/admin keys in bothGET /api/chat/{chatId}/streamandPOST /api/chat/{chatId}/stop, via sharedvalidateChatOwnershipfor consistent auth and ownership checks.
- Honors
Summary by CodeRabbit
-
New Features
- Added the ability to reconnect to in-progress chat responses.
- Chat stream requests now support resuming from a specified position.
- Added cross-origin request support for chat streaming.
-
Bug Fixes
- Improved validation for chat access, identifiers, and resume positions.
- Stale or completed streams now close cleanly with appropriate responses.
- Improved error handling when chat workflow status cannot be retrieved.
-
Refactor
- Unified chat ownership and access validation across chat workflow operations.