fix(sse): refactor stall detection to reduce false positives on slow streams

[diegosouzapw]

Summary

Ported from upstream PR decolua/9router#1243 by @zakirkun. Refactors stream stall detection in pipeWithDisconnect to track raw upstream byte activity instead of post-transform output, preventing false stalls on slow-but-progressing streams (reasoning models like Claude thinking via Kiro, EventStream binary frames buffering partial frames).

Why

The prior watchdog (in OmniRoute's createSSEStream / buildSseTransformStream) reset its idle timer only when post-transform output flowed. Reasoning streams emit many raw upstream bytes per single emitted SSE event — so the watchdog could false-fire even while upstream was actively progressing, surfacing a confusing failed to pipe response / disconnect to the client.

The new layer in pipeWithDisconnect:

• inserts an inert TransformStream tap between the provider body and the SSE transform that resets the stall timer on every upstream chunk;
• wraps the stream controller so every termination path (complete / error / disconnect / abort) clears the timer — no stale abort can fire after the request has ended;
• on stall, errors the pipeline so the downstream reader unblocks and the request surfaces a sanitized SSE error event (via the existing buildStreamErrorChunks path), then abort()s the underlying fetch so upstream releases the connection;
• inherits STREAM_IDLE_TIMEOUT_MS as its default budget (single env knob still governs upstream silence tolerance); tests inject an explicit budget via the new opts.stallTimeoutMs arg.

TDD

Three new tests in tests/unit/stream-handler.test.ts:

1. No false positive — upstream emits 3 chunks 30ms apart, transform is silent (swallowing); stall budget 200ms → watchdog must NOT fire, downstream receives the final flush cleanly.
2. True stall — upstream emits one byte then goes silent; stall budget 80ms → watchdog fires, onError callback receives the stall, downstream gets a sanitized SSE error chunk with finish_reason:"error".
3. Late-fire guard — upstream completes cleanly under the budget; the timer must be cleared on completion so no late stall error surfaces.

RED → GREEN confirmed (test #2 timed out at 5s pre-fix; passes in ~85ms post-fix). All 18 existing tests in the file still pass.

Test plan

• node --test tests/unit/stream-handler.test.ts — 18/18 green
• node --test tests/unit/stream-utilities.test.ts — 8/8 green (sibling pipeWithDisconnect coverage)
• npm run typecheck:core — clean
• ESLint on touched files — clean
• File-size gate — clean (streamHandler.ts 532 < cap 800)

Notes

• File-size: open-sse/utils/streamHandler.ts 409 → 532 (well below the 800-line new-file cap; not in the frozen baseline so no rebaseline needed).
• The previous STREAM_IDLE_TIMEOUT_MS watchdog in open-sse/utils/stream.ts is intentionally left in place — it is a complementary check at a different layer (SSE transform output). The new watchdog is upstream-byte-side, exactly the false-positive fix the upstream PR targets.
• The opts.stallTimeoutMs: 0 opt-out preserves legacy behavior verbatim for any caller that needs to disable the watchdog.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.