feat(chat): add GET /api/chat/{chatId}/stream to resume an in-progress response

Merged
SW
4mo ago
+567-35

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

FileRole
app/api/chat/[chatId]/stream/route.tsGET + OPTIONS. maxDuration = 800 to match POST /api/chat — a resumed stream lives as long as the turn it follows.
lib/chat/handleResumeChatStream.ts200 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.tsThe documented integer, minimum 0.
lib/chat/validateChatOwnership.tsExtracted 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 the main baseline (203).
  • eslint clean.

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 with x-workflow-run-id and best-effort x-workflow-stream-tail-index; 204 when nothing to resume (clears stale active_stream_id); 502 on run-status read failures.
    • Headless runs claim chats.active_stream_id on start so GET /api/chat/{chatId}/stream can watch their output live.
    • Reuses the existing stream watcher; maxDuration = 800; adds CORS OPTIONS.
  • Bug Fixes

    • Honors account_id query override for org/admin keys in both GET /api/chat/{chatId}/stream and POST /api/chat/{chatId}/stop, via shared validateChatOwnership for consistent auth and ownership checks.

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.