[diegosouzapw]

Summary

• Opt-in coalescing of Claude content_block_delta events (SSE_COALESCE_MS, plus per-type SSE_COALESCE_THINKING_MS / SSE_COALESCE_TEXT_MS / SSE_COALESCE_INPUT_JSON_MS). Fast Anthropic-compatible upstreams send one delta per token, and clients that render one UI update per SSE event (the Claude Code VS Code extension) fall behind. Consecutive deltas with the same block index and delta type are merged losslessly. This covers both the translate lane and the claude→claude passthrough lane.
• Opt-in SSE frame batching (SSE_FRAME_COALESCE_MS): frames forwarded inside the window go to the client as one enqueue. The first frame and terminal frames are never held back.
• Opt-in interval stall watchdog (SSE_STALL_WATCHDOG=interval): pipeWithDisconnect stamps the last chunk time and checks it from one unref'd interval per stream, so it no longer re-arms a timer on every upstream chunk.

Everything is OFF by default. With no env set, the stream is byte-identical and makes the same enqueue and timer calls as before. sseOutputSink.wrap() returns the transformer untouched, forward() takes the legacy fast path, and the watchdog stays in timer mode.

Attribution

Thanks to @WYSTAF for the original delta-coalescing implementation, and to @wallerjenifernk530-hash for the original frame-coalescing and stall-watchdog analysis.

Changes

• open-sse/utils/sseDeltaCoalesce.ts (new): a frame-level coalescer.
  • It parses only complete [event: content_block_delta\n]data: {...}\n\n frames whose delta type is text_delta, thinking_delta or input_json_delta.
  • Anything else flushes the pending group first and then passes through untouched, so order is preserved. That includes signature_delta, boundary events, comments and multi-frame chunks.
  • A group of one frame is re-emitted byte-for-byte.
  • The window timer is not restarted by later deltas, so a long burst is flushed once per window.
• open-sse/utils/sseOutputSink.ts (new): forward() moves here. The sink composes the delta stage (Claude clients only) with the frame batcher. Batching is capped at 64 KiB and terminal frames are detected ([DONE], message_stop, error, response.completed|failed|incomplete). wrap() makes the transformer's flush() drain pending output and its cancel() dispose the timers. An enqueue that throws on a closed or errored stream makes the sink inert instead of throwing from a timer.
• open-sse/utils/stream.ts: forward now comes from the sink, and the transformer is wrapped with outputSink.wrap({...}). The file is net −2 lines and stays under its frozen file-size ceiling.
• open-sse/utils/streamStallWatchdog.ts (new) + open-sse/utils/streamHandler.ts: armStall/clearStall now come from createStallWatchdog. timer mode (the default) keeps the legacy per-chunk clearTimeout+setTimeout. In interval mode the period is clamp(stall/4, 1s, 5s). armActive, the content-stall watcher and the upstream tap are untouched.
• .env.example + docs/reference/ENVIRONMENT.md: the six new variables are documented.

Deviations from the original upstream changes:

• The frame-batching knob is named SSE_FRAME_COALESCE_MS and defaults to off. Upstream used SSE_COALESCE_MS with a 2 ms default, which collides with the delta-coalescing variable of the same name.
• The extra upstream tap is kept, because here it hosts the content-stall watcher.
• Delta coalescing operates on the formatted frames at the single exit point. As a result, clientPayloadCollector and the request logger still record the per-token events. The merged text is identical, but the event counts differ when coalescing is on.

Test plan

• New tests failed before the port: with the base stream.ts swapped in, 5 integration tests fail (claude passthrough: SSE_COALESCE_MS merges deltas…, translate lane … is coalesced too, SSE_FRAME_COALESCE_MS batches a burst…, … never delays the first frame or a terminal frame, delta coalescing and frame batching compose losslessly). On the base, the module-level tests cannot even import their module.
• node --import tsx/esm --test tests/unit/sse-delta-coalesce.test.ts → ℹ pass 13 ℹ fail 0
• node --import tsx/esm --test tests/unit/sse-output-coalescing.test.ts → ℹ pass 7 ℹ fail 0
• I ran 87 test files with the test:unit:ci preamble: every test file that imports stream.ts, streamHandler.ts or pipeWithDisconnect, plus the 3 new ones and tests/integration/sse-correctness.test.ts. Result: ℹ tests 636 ℹ pass 635 ℹ fail 1. The single failure is kiro-content-stall-15260 › fragmented prelude…. It is a 100 ms content-stall timing test and also fails on the base stream.ts/streamHandler.ts on this loaded host (2 failures there), so it is not caused by this change.
• npm run typecheck:core → exit 0
• npx eslint --suppressions-location config/quality/eslint-suppressions.json <changed files> → exit 0; npx prettier --check on the changed files → clean
• node scripts/check/check-env-doc-sync.mjs → ✓ Env / docs contract is in sync.; npm run check:docs-all → exit 0
• GITHUB_BASE_REF=release/v3.8.52 node scripts/check/check-pr-test-policy.mjs → Result: PASS; npm run check:test-masking → OK — 0 modificado(s) … sem enfraquecimento
• node scripts/check/check-file-size.mjs: stream.ts 3326→3324 (ceiling 3326) and streamHandler.ts at 1193 (cap 1200). The 4 remaining violations are in files this PR does not touch (responseSanitizer.ts, error.ts, and two test files).

⚠️ base-red inherited: #15306 — unit/vitest/integration/package-artifact gates on release/v3.8.52

[github-actions]

CI Coverage Report

• Coverage job: skipped
• PR test policy: success

Coverage artifact was not available for this run.