fix(chat): relay translated heartbeats

src/chat/outbound.ts

@@ -552,8 +552,16 @@ export function responsesSseToChatCompletionsSse(
         }
         switch (eventName) {
           case "response.created":
+            ensureRole();
+            break;
           case "response.heartbeat":
             ensureRole();
+            // A typed Responses heartbeat carries transport liveness, not Chat content. Preserve
+            // that signal as an SSE comment so idle-sensitive Chat clients receive bytes without
+            // inventing a semantic chunk that parsers, usage counters, or progress watchdogs could
+            // mistake for model output.
+            enqueueLiveFrame(encoder.encode(": opencodex heartbeat\n\n"));
+            emittedFrames++;
             break;
           case "response.output_text.delta": {
             if (typeof data.delta === "string") emitContent(data.delta);

structure/data-planes/inbound-compat.md

@@ -112,6 +112,10 @@ attempt telemetry only.
 
 Combo/policy routes and requests that need Responses-only hosted tools, continuation, background,
 or storage semantics retain the existing Chat -> Responses -> Chat bridge.
+On its streaming return path, typed `response.heartbeat` events become SSE comment-line
+keepalives. They preserve connection liveness without adding a Chat completion chunk, changing
+usage, or claiming semantic progress; see the
+[heartbeat contract](../transports/streaming-health.md#heartbeat-and-stall-deadline).
 Chat-to-Responses traffic that lands on `api.meta.ai` inherits the same 64-character tool-name
 aliasing as native Responses; see [`responses.md`](../transports/responses.md).
 

structure/decisions/ADR-5805-chat-completions-heartbeat-relay.md

@@ -0,0 +1,22 @@
+# ADR-5805 — decision recorded under "Heartbeat and stall deadline"
+
+- Contract owner: [transports/streaming-health.md](../transports/streaming-health.md#heartbeat-and-stall-deadline)
+
+## Decision record
+
+- Purpose and intent: Keep translated Chat Completions streams transport-alive while the Responses bridge
+  is receiving typed heartbeats during long reasoning or held output.
+- Existing behavior and constraints: The converter used a heartbeat only to ensure the initial assistant role;
+  every later heartbeat produced no downstream byte. A keepalive must remain valid SSE, preserve
+  backpressure and translator accounting, and must not look like model content or tool progress.
+- Alternatives considered: Drop typed heartbeats; emit an empty `chat.completion.chunk`; emit an SSE
+  comment; add a separate nonstandard Chat event type.
+- Chosen approach: Emit one bounded `: opencodex heartbeat` SSE comment for each typed Responses
+  heartbeat after ensuring the initial role chunk.
+- Why this approach: SSE comments refresh transport-idle timers while every
+  compliant event parser discards them. Empty or nonstandard data events can be miscounted as
+  semantic output and would widen the Chat wire contract.
+- Benefits, drawbacks, and impact: Long silent Chat translations now deliver regular transport bytes without
+  changing content, tools, usage, terminal behavior, cancellation, or upstream stall detection. A
+  client's separate semantic-progress watchdog may still expire, which is intentional because a
+  keepalive proves connection liveness rather than model progress.

structure/transports/streaming-health.md

@@ -33,6 +33,13 @@ configurable via `stallTimeoutSec`, checked on the 2 s heartbeat tick) closes th
 adapter events arrive. Adapter-yielded `{ type: "heartbeat" }` events DO reset the watchdog.
 The Anthropic adapter maps both SSE comments and `ping` events to that heartbeat (#5707), so an
 upstream that only pings while a long thinking block is silent still counts as live.
+When the Responses-to-Chat converter receives that typed heartbeat, it emits the same bounded SSE
+comment after ensuring the initial assistant-role chunk. Chat clients therefore keep receiving
+transport bytes during long reasoning without a fabricated content/tool/usage event. The comment
+does not reset a semantic-progress watchdog, and it does not alter the bridge's upstream stall or
+cancellation decisions.
+
+> Decision record: [ADR-5805](../decisions/ADR-5805-chat-completions-heartbeat-relay.md)
 
 Top-level `emptyCompletionRetry: true` opts Responses turns into one identical replay when an
 upstream turn produces neither output text nor a tool call, including a stream that ends before a

tests/responses/chat-completions-endpoint.test.ts

@@ -522,10 +522,11 @@ test("chatCompletionsUsage always emits detail objects with zero defaults", () =
   });
 });
 
-test("responsesSseToChatCompletionsSse consumes response.heartbeat without forwarding a raw frame", async () => {
+test("responsesSseToChatCompletionsSse relays response.heartbeat as Chat-compatible SSE comments", async () => {
   // Upstream responses SSE may contain heartbeat events (SSE comment keep-alive in
   // bridge.ts, but some upstreams emit them as typed frames). The chat-completions
-  // converter must drop them rather than forwarding raw Responses-vocab frames.
+  // converter must preserve their transport liveness without forwarding raw Responses-vocab
+  // frames or manufacturing semantic Chat chunks.
   const { responsesSseToChatCompletionsSse } = budgetedChatOutbound(await import("../../src/chat/outbound"));
   const upstream = new Response([
     `event: response.heartbeat\ndata: ${JSON.stringify({ type: "response.heartbeat" })}\n\n`,
@@ -536,6 +537,7 @@ test("responsesSseToChatCompletionsSse consumes response.heartbeat without forwa
   const stream = responsesSseToChatCompletionsSse(upstream.body!, "routed/model");
   const text = await new Response(stream).text();
   expect(text).not.toContain("response.heartbeat");
+  expect(text.split(": opencodex heartbeat\n\n")).toHaveLength(3);
   expect(text).toContain('"content":"hi"');
   expect(text).toContain("data: [DONE]");
   // Every data frame must be a chat.completion.chunk — no Responses-vocab leaks.