fix(bridge): keep wire heartbeats during adapter-only progress

Fixes #521. Rebased onto dev and verified with local targeted bridge test, typecheck, privacy scan, full pre-push gate, Sol independent audit, and hosted cross-platform CI.

Author: Wibias

src/bridge.ts

@@ -189,17 +189,19 @@ export function bridgeToResponsesSSE(
   };
   // RC3 keep-alive: Codex's idle timer is timeout(idle_timeout, stream.next()) over an
   // eventsource_stream; ANY received event re-arms it, while an unknown type is ignored
-  // (responses.rs `_ => Ok(None)`). We emit a real, parser-ignored `response.heartbeat` only during
-  // upstream silence so a stalled routed provider never trips "idle timeout waiting for SSE".
-  let activity = false;
+  // (responses.rs `_ => Ok(None)`). Emit a parser-ignored `response.heartbeat` whenever the
+  // *wire* has been silent, even if invisible adapter heartbeats are still flowing (web-search
+  // buffering + raw-byte progress). Upstream activity only resets the stall watchdog.
+  let upstreamActivity = false;
+  let wireActivity = false;
   let beat: ReturnType<typeof setInterval> | undefined;
   let controller: ReadableStreamDefaultController<Uint8Array>;
   let emittedFrames = 0;
   let gated = false;
   let stepping = false;
   const emit = (name: string, data: Record<string, unknown>) => {
         if (closed) return;
-        activity = true;
+        wireActivity = true;
         try {
           controller.enqueue(encoder.encode(sseEvent(name, { type: name, sequence_number: seq++, ...data })));
           emittedFrames++;
@@ -482,7 +484,9 @@ export function bridgeToResponsesSSE(
           if (next.done) { upstreamDone = true; break; }
           const event = next.value;
           let terminalEvent = false;
-          activity = true;
+          // Invisible adapter heartbeats (and buffered web-search progress) count as upstream
+          // liveness only — they must not suppress wire keepalives that re-arm Codex idle timers.
+          upstreamActivity = true;
           stallTicks = 0;
           reportFirstOutput(event);
           // Compaction turns emit ONLY the synthetic compaction item + response.completed. The
@@ -846,8 +850,10 @@ export function bridgeToResponsesSSE(
         gated = true;
         beat = setInterval(() => {
           if (closed || gated) return;
-          if (activity) { activity = false; stallTicks = 0; return; }
-          if (++stallTicks >= maxStallTicks) {
+          if (upstreamActivity) {
+            upstreamActivity = false;
+            stallTicks = 0;
+          } else if (++stallTicks >= maxStallTicks) {
             if (currentMsg) closeCurrentMessage();
             if (currentReasoning) closeCurrentReasoning();
             if (currentRawReasoning) closeCurrentRawReasoning();
@@ -871,6 +877,11 @@ export function bridgeToResponsesSSE(
             closed = true;
             return;
           }
+          // Wire silence is independent of upstream adapter heartbeats.
+          if (wireActivity) {
+            wireActivity = false;
+            return;
+          }
           try {
             controller.enqueue(heartbeatFrame);
             emittedFrames++;

tests/bridge.test.ts

@@ -682,7 +682,8 @@ describe("Responses bridge reasoning and usage parity", () => {
   test("heartbeat events reset the stall watchdog and emit no protocol frame", async () => {
     // Regression for the Cursor parallel-tool-call stall: while the upstream silently assembles tool
     // calls, the adapter emits `heartbeat` events. They must keep the stall watchdog alive (no
-    // upstream_stall_timeout) without producing any Responses protocol event of their own.
+    // upstream_stall_timeout). Adapter heartbeats themselves are not translated into Responses
+    // protocol items; wire keepalives use a separate `response.heartbeat` frame (see next test).
     async function* heartbeatsThenDone(): AsyncGenerator<AdapterEvent> {
       // More heartbeats than maxStallTicks would allow if they did NOT reset the counter.
       for (let i = 0; i < 6; i++) {
@@ -699,9 +700,29 @@ describe("Responses bridge reasoning and usage parity", () => {
     ));
     expect(frames.some(f => (f.data.response as Record<string, unknown> | undefined)?.incomplete_details)).toBe(false);
     expect(frames.some(f => f.event === "response.completed")).toBe(true);
-    // No protocol frame is produced by a heartbeat itself (only created/text/completed appear).
+    // Adapter heartbeats must not be mis-translated into a rich protocol event of their own.
     expect(frames.some(f => f.event === "response.heartbeat" && f.data.type === "heartbeat" && Object.keys(f.data).length > 2)).toBe(false);
   });
+
+  test("wire response.heartbeat keeps firing while only adapter heartbeats flow", async () => {
+    // Issue #521: web-search buffers semantic events and yields invisible adapter heartbeats from
+    // raw-byte progress. Those must not suppress wire keepalives, or Codex Desktop idle-timeouts
+    // (~5 min) while OCX still considers the upstream alive.
+    async function* adapterHeartbeatsOnly(): AsyncGenerator<AdapterEvent> {
+      for (let i = 0; i < 8; i++) {
+        yield { type: "heartbeat" };
+        await new Promise(r => setTimeout(r, 15));
+      }
+      yield { type: "text_delta", text: "ok" };
+      yield { type: "done" };
+    }
+    const frames = await collectSse(bridgeToResponsesSSE(
+      adapterHeartbeatsOnly(), "model", undefined, undefined, undefined, undefined, 10, { stallTimeoutSec: 1 },
+    ));
+    expect(frames.some(f => f.event === "response.heartbeat" && f.data.type === "response.heartbeat")).toBe(true);
+    expect(frames.some(f => f.event === "response.completed")).toBe(true);
+    expect(frames.some(f => (f.data.response as Record<string, unknown> | undefined)?.incomplete_details)).toBe(false);
+  });
 });
 
 describe("Responses bridge web_search_call native item", () => {