fix(networking): expose the workflow stream headers to cross-origin JS

Merged
SW
4mo ago
+32-0

Row 5 of chat#1923. One line, but it fixes a contract we have not been honouring.

The gap

getCorsHeaders sets Access-Control-Allow-Headers โ€” which governs request headers โ€” but never Access-Control-Expose-Headers. Browsers hide every non-safelisted response header from cross-origin JS unless it is named there.

Two live consequences:

  1. x-workflow-run-id has never been readable by the chat client. It is documented as part of the 200 on POST /api/chat and GET /api/chat/{chatId}/stream, and has been since the workflow cutover. Every browser caller has been unable to see it.
  2. x-workflow-stream-tail-index reads as null. Confirmed on preview 2026-08-03 while verifying chat#1924: the header was present on the wire, invisible to JS.

The second is the sharper one going forward. The AI SDK's WorkflowChatTransport reads that header to anchor relative resume positions; against us today it would fail silently, falling back to startIndex: 0 and replaying the entire stream rather than erroring.

Why chat#1924 still worked

It counts SSE frames off the wire instead of trusting the header โ€” a choice forced by a different constraint (headers are sent before the body, so no header can report where a stream ended). So this is not a regression in that PR; it unblocks the follow-up work that does need the header.

Scope

Applies to every endpoint using getCorsHeaders, which is the intended blast radius: exposing these two response headers leaks nothing โ€” both are already sent on the wire, and this only lets the browser's JS layer read what the network already delivered.

Tests

RED before GREEN. 2 cases: the existing allow-* headers are untouched, and both workflow headers are exposed.

  • Full api suite: 4,331 tests passing.
  • tsc --noEmit clean in the touched file; eslint clean.

Merge order

Independent of docs#287, which documents the header itself. Unblocks the negative-startIndex refresh row in chat#1923.

Refs chat#1923

๐Ÿค– Generated with Claude Code


Summary by cubic

Expose workflow stream response headers to cross-origin JS so browser clients can read x-workflow-run-id and x-workflow-stream-tail-index and resume streams correctly.

  • Bug Fixes
    • Add Access-Control-Expose-Headers in getCorsHeaders for x-workflow-run-id and x-workflow-stream-tail-index (applies to all endpoints using it).
    • Prevents silent full replays by transports that rely on the tail index.
    • Tests cover unchanged allow-* headers and exposure of both workflow headers.