@openchambery/web 1.19.7-beta.9 → 1.19.7

package/server/lib/event-stream/DOCUMENTATION.md

@@ -10,9 +10,11 @@ This module contains the OpenChamber message-stream WebSocket protocol and runti
 - `packages/web/server/lib/event-stream/directory-ws-bridge.js`: browser-facing per-directory WS bridge that owns one scoped upstream reader per connection.
 - `packages/web/server/lib/event-stream/protocol.js`: path constants, SSE envelope parsing, and WebSocket frame serialization helpers.
 - `packages/web/server/lib/event-stream/diff-summary.js`: pure outbound FileDiff helpers. L1 message/session `summary.diffs` keep a slim file list `{ file, status?, additions, deletions }` plus additive `diffCount`/`hasDiffs` (never patch/before/after/from/to). `session.diff` event frames still keep file/status/additions/deletions and drop patch bodies. `summarizeFileDiff(s)` remains for explicit L2-style file lists.
+- `packages/web/server/lib/event-stream/reasoning-projection.js`: OpenChamber outbound reasoning projection (`includeReasoning=false`). Shared pure snapshot helpers + per-connection stateful stream filter for HTTP parts, WS send/replay, and SSE proxy parse-filter paths. Never mutates hub/replay objects; never forwards the query param to OpenCode.
 - `packages/web/server/lib/event-stream/upstream-reader.js`: reusable upstream SSE reader with event-id tracking, stall recovery, and reconnect handling.
 - `packages/web/server/lib/event-stream/runtime.js`: thin WebSocket server runtime for upgrade handling and path dispatch to the global/directory bridges.
 - `packages/web/server/lib/event-stream/protocol.test.js`: unit tests for protocol helpers.
+- `packages/web/server/lib/event-stream/reasoning-projection.test.js`: unit + 10k-delta performance guards for reasoning projection.
 - `packages/web/server/lib/event-stream/upstream-reader.test.js`: unit tests for upstream SSE reader behavior.
 - `packages/web/server/lib/event-stream/runtime.test.js`: unit tests for runtime-side broadcaster behavior.
 
@@ -26,7 +28,14 @@ The following APIs are exported by their owning modules. `event-stream/index.js`
 - `MESSAGE_STREAM_WS_HEARTBEAT_INTERVAL_MS`: heartbeat interval for browser-facing WS connections.
 - `parseSseEventEnvelope(block)`: parses an SSE block into `{ eventId, directory, payload }`.
 - `sendMessageStreamWsFrame(socket, payload)`: serializes and sends a JSON WS frame.
-- `sendMessageStreamWsEvent(socket, payload, options)`: sends an event frame with optional `eventId` and `directory`. Outbound `session.diff` keeps file/status/additions/deletions only (no full patch bodies). Message/session `summary.diffs` are L1-projected to a slim file list plus additive `diffCount`/`hasDiffs` (patch bodies never leave the host).
+- `sendMessageStreamWsEvent(socket, payload, options)`: sends an event frame with optional `eventId`, `directory`, and per-connection `reasoningFilter`. Outbound `session.diff` keeps file/status/additions/deletions only (no full patch bodies). Message/session `summary.diffs` are L1-projected to a slim file list plus additive `diffCount`/`hasDiffs` (patch bodies never leave the host). When `reasoningFilter.projectEvent` returns `null`, the frame is dropped (still counts as a successful send so slow-client tracking is unchanged).
+
+### Reasoning projection helpers (`reasoning-projection.js`)
+Import from the module file (not the event-stream barrel). Public surface:
+- `shouldIncludeReasoning` / `readIncludeReasoningQuery` / `readIncludeReasoningFromUrl` / `stripIncludeReasoningParam`
+- `projectMessagesPayloadForReasoning` / `projectMessagesPayloadWithoutReasoning` — array / `{ records }` / `{ record }` / `{ parts }` only
+- `createReasoningOutboundFilter` — per-connection stream filter (version-suffix-aware type match; preserves original `type` on kept events)
+- `filterSseBlock` / `createSseBlockSplitter` — SSE disabled path (CR-safe chunk boundaries)
 
 ### Runtime helpers
 - `createGlobalMessageStreamHub(...)`: creates a shared `/global/event` upstream SSE hub with event/status subscribers and bounded event-id replay.
@@ -45,6 +54,7 @@ The following APIs are exported by their owning modules. `event-stream/index.js`
 - The web server creates one shared global message-stream hub. OpenCode watcher side effects and global WS clients subscribe to that hub, so there is one upstream `/global/event` SSE reader for both server-side processing and browser fan-out.
 - The global hub keeps a bounded replay buffer keyed by SSE `eventId` so reconnecting browser clients can receive buffered events after their requested `Last-Event-ID`.
 - Outbound FileDiff payloads are summarized before hub fan-out/replay and again at WS send, so Relay never carries full patch frames larger than 64KB.
+- **Reasoning projection (`includeReasoning=false`)**: per HTTP request or WS/SSE connection. The shared hub and internal subscribers always see full upstream events. Filtering runs only at the browser send boundary (live fan-out **and** replay) and on the direct SSE proxy parse path. HTTP turn-page / reconcile / exact message / official `session.messages` list / transcript-cache reads apply the same part strip. `tokens.reasoning` totals stay. The query param is OpenChamber-only and is stripped before OpenCode upstream calls.
 - Global WS reconnect protocol is **replay events → ready barrier**. On initial connect and on each first-ready for a client, the bridge synchronously sends any `replayAfter(lastEventId)` frames first, then emits `{ type: 'ready', scope: 'global' }`. Clients must not start HTTP compensation until they observe ready, so buffered history can merge first.
 - Directory WS clients still attach one upstream `/event?directory=...` SSE reader per connection because directory streams are scoped.
 - If an upstream SSE connection delays response headers or an attached stream stalls, the reader aborts that upstream fetch and reconnects upstream with `Last-Event-ID`, keeping the browser WS alive when recovery is fast.
@@ -66,6 +76,7 @@ The following APIs are exported by their owning modules. `event-stream/index.js`
 
 ## Testing
 - Run `vitest run packages/web/server/lib/event-stream/protocol.test.js`
+- Run `vitest run packages/web/server/lib/event-stream/reasoning-projection.test.js`
 - Run `vitest run packages/web/server/lib/event-stream/upstream-reader.test.js`
 - Run `vitest run packages/web/server/lib/event-stream/runtime.test.js`
 - Run repo validation before finalizing: `bun run type-check`, `bun run lint`, `bun run build`

package/server/lib/event-stream/directory-ws-bridge.js

@@ -17,6 +17,7 @@ export function acceptDirectoryMessageStreamWsConnection({
   socket,
   requestedLastEventId,
   requestedDirectory,
+  reasoningFilter = null,
   buildOpenCodeUrl,
   getOpenCodeAuthHeaders,
   processForwardedEventPayload,
@@ -37,6 +38,7 @@ export function acceptDirectoryMessageStreamWsConnection({
       controller.abort();
     }
     reader?.stop();
+    reasoningFilter?.dispose?.();
     wsClients.delete(socket);
   };
 
@@ -56,7 +58,10 @@ export function acceptDirectoryMessageStreamWsConnection({
       return;
     }
 
-    sendMessageStreamWsEvent(socket, { type: 'openchamber:heartbeat', timestamp: Date.now() }, { directory: 'global' });
+    sendMessageStreamWsEvent(socket, { type: 'openchamber:heartbeat', timestamp: Date.now() }, {
+      directory: 'global',
+      reasoningFilter,
+    });
   }, heartbeatIntervalMs);
 
   socket.on('close', () => {
@@ -77,10 +82,14 @@ export function acceptDirectoryMessageStreamWsConnection({
       sendMessageStreamWsEvent(socket, payload, {
         directory,
         eventId: typeof envelope?.eventId === 'string' && envelope.eventId.length > 0 ? envelope.eventId : undefined,
+        reasoningFilter,
       });
 
       processForwardedEventPayload(payload, (syntheticPayload) => {
-        sendMessageStreamWsEvent(socket, syntheticPayload, { directory: 'global' });
+        sendMessageStreamWsEvent(socket, syntheticPayload, {
+          directory: 'global',
+          reasoningFilter,
+        });
       });
     };
 

package/server/lib/event-stream/global-ws-bridge.js

@@ -22,9 +22,13 @@ export function createGlobalMessageStreamWsBridge({
 }) {
   const clients = new Set();
   const clientLastEventIds = new Map();
+  const clientReasoningFilters = new Map();
   const readyClients = new Set();
 
   const removeClient = (socket) => {
+    const filter = clientReasoningFilters.get(socket);
+    filter?.dispose?.();
+    clientReasoningFilters.delete(socket);
     clients.delete(socket);
     clientLastEventIds.delete(socket);
     readyClients.delete(socket);
@@ -32,10 +36,12 @@ export function createGlobalMessageStreamWsBridge({
   };
 
   const replayEvents = (socket, requestedLastEventId) => {
+    const reasoningFilter = clientReasoningFilters.get(socket);
     for (const entry of globalHub.replayAfter(requestedLastEventId)) {
       const sent = sendMessageStreamWsEvent(socket, entry.payload, {
         directory: entry.directory,
         eventId: entry.eventId,
+        reasoningFilter,
       });
       if (!sent) {
         removeClient(socket);
@@ -104,6 +110,7 @@ export function createGlobalMessageStreamWsBridge({
       const sent = sendMessageStreamWsEvent(socket, payload, {
         directory,
         eventId,
+        reasoningFilter: clientReasoningFilters.get(socket),
       });
       if (!sent) {
         removeClient(socket);
@@ -115,7 +122,10 @@ export function createGlobalMessageStreamWsBridge({
         if (!readyClients.has(socket)) {
           continue;
         }
-        const sent = sendMessageStreamWsEvent(socket, syntheticPayload, { directory: 'global' });
+        const sent = sendMessageStreamWsEvent(socket, syntheticPayload, {
+          directory: 'global',
+          reasoningFilter: clientReasoningFilters.get(socket),
+        });
         if (!sent) {
           removeClient(socket);
         }
@@ -168,7 +178,7 @@ export function createGlobalMessageStreamWsBridge({
     }
   });
 
-  const accept = (socket, { requestedLastEventId = '' } = {}) => {
+  const accept = (socket, { requestedLastEventId = '', reasoningFilter = null } = {}) => {
     const pingInterval = setInterval(() => {
       if (socket.readyState !== 1) {
         return;
@@ -185,7 +195,10 @@ export function createGlobalMessageStreamWsBridge({
         return;
       }
 
-      sendMessageStreamWsEvent(socket, { type: 'openchamber:heartbeat', timestamp: Date.now() }, { directory: 'global' });
+      sendMessageStreamWsEvent(socket, { type: 'openchamber:heartbeat', timestamp: Date.now() }, {
+        directory: 'global',
+        reasoningFilter: clientReasoningFilters.get(socket),
+      });
     }, heartbeatIntervalMs);
 
     socket.on('close', () => {
@@ -201,6 +214,9 @@ export function createGlobalMessageStreamWsBridge({
 
     clients.add(socket);
     clientLastEventIds.set(socket, requestedLastEventId);
+    if (reasoningFilter) {
+      clientReasoningFilters.set(socket, reasoningFilter);
+    }
     globalHub.start();
     if (globalHub.isConnected()) {
       markReady(socket, requestedLastEventId);

package/server/lib/event-stream/protocol.js

@@ -126,9 +126,19 @@ export function sendMessageStreamWsFrame(socket, payload) {
 }
 
 export function sendMessageStreamWsEvent(socket, payload, options = {}) {
+  // Optional per-connection reasoning projector (includeReasoning=false).
+  // null from projectEvent means drop this frame entirely.
+  let candidate = payload;
+  if (options.reasoningFilter && typeof options.reasoningFilter.projectEvent === 'function') {
+    candidate = options.reasoningFilter.projectEvent(payload);
+    if (candidate == null) {
+      return true;
+    }
+  }
+
   // Summarize FileDiff bodies before fan-out so Relay/WS never carries full
   // patch frames. Identity is preserved for non-diff and already-summary events.
-  const outbound = summarizeOutboundEventPayload(payload);
+  const outbound = summarizeOutboundEventPayload(candidate);
   return sendMessageStreamWsFrame(socket, {
     type: 'event',
     payload: outbound,

package/server/lib/event-stream/reasoning-projection.js

@@ -0,0 +1,425 @@
+/**
+ * OpenChamber outbound reasoning projection.
+ *
+ * `includeReasoning=false` (strict string only) strips reasoning from Host→client
+ * HTTP/SSE/WS payloads. Missing/other values keep current behavior. OpenChamber
+ * projection only — never forward the param to OpenCode. Hub/upstream stay full.
+ *
+ * Shared by HTTP snapshots and stateful stream filters:
+ * drop type=reasoning parts, their deltas, session.next.reasoning.* events.
+ * Keep tokens.reasoning totals, tools, text, status, permissions/errors.
+ * Never mutate hub/replay objects.
+ */
+
+const REASONING_DELTA_FIELDS = new Set([
+  'reasoning',
+  'reasoning_content',
+  'reasoning_details',
+]);
+
+/** Match UI opencode-event-normalizer: strip terminal `.N` version suffix for dispatch. */
+const VERSIONED_TYPE = /^(.*)\.(\d+)$/;
+
+const PART_TYPE_CACHE_LIMIT = 8192;
+
+const isPlainObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+/** @param {string} type */
+const baseEventType = (type) => {
+  const match = VERSIONED_TYPE.exec(type);
+  return match?.[1] ?? type;
+};
+
+/**
+ * Strict: only string `'false'` disables. Missing / other keep include.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function shouldIncludeReasoning(value) {
+  if (Array.isArray(value) && value.length > 0) return value[0] !== 'false';
+  return value !== 'false';
+}
+
+/** @param {unknown} query */
+export function readIncludeReasoningQuery(query) {
+  if (!query || typeof query !== 'object') return true;
+  return shouldIncludeReasoning(/** @type {Record<string, unknown>} */ (query).includeReasoning);
+}
+
+/** @param {string} rawUrl */
+export function readIncludeReasoningFromUrl(rawUrl) {
+  if (typeof rawUrl !== 'string' || !rawUrl.includes('includeReasoning=')) return true;
+  try {
+    return shouldIncludeReasoning(new URL(rawUrl, 'http://openchamber.local').searchParams.get('includeReasoning'));
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Strip OpenChamber-only `includeReasoning` before OpenCode upstream.
+ * @param {string} requestUrl
+ */
+export function stripIncludeReasoningParam(requestUrl) {
+  if (typeof requestUrl !== 'string' || !requestUrl.includes('includeReasoning=')) return requestUrl;
+  try {
+    const url = new URL(requestUrl, 'http://openchamber.local');
+    if (!url.searchParams.has('includeReasoning')) return requestUrl;
+    url.searchParams.delete('includeReasoning');
+    const search = url.searchParams.toString();
+    if (requestUrl.startsWith('http://') || requestUrl.startsWith('https://')) {
+      return `${url.origin}${url.pathname}${search ? `?${search}` : ''}${url.hash || ''}`;
+    }
+    return `${url.pathname}${search ? `?${search}` : ''}${url.hash || ''}`;
+  } catch {
+    return requestUrl;
+  }
+}
+
+/** @param {unknown} parts */
+function projectParts(parts) {
+  if (!Array.isArray(parts) || parts.length === 0) return parts;
+  let changed = false;
+  const next = [];
+  for (const part of parts) {
+    if (isPlainObject(part) && part.type === 'reasoning') {
+      changed = true;
+      continue;
+    }
+    next.push(part);
+  }
+  return changed ? next : parts;
+}
+
+/**
+ * One message record: `{ info, parts }` (turn-page / exact / cache / session.messages).
+ * @param {unknown} record
+ */
+function projectRecord(record) {
+  if (!isPlainObject(record) || !Array.isArray(record.parts)) return record;
+  const parts = projectParts(record.parts);
+  return parts === record.parts ? record : { ...record, parts };
+}
+
+/**
+ * Real Host payload shapes only:
+ * - bare array of records
+ * - `{ records: [...] }` (turn-page / reconcile / cache session)
+ * - `{ record }` (cache message)
+ * - `{ info, parts }` (exact message)
+ *
+ * @param {unknown} payload
+ */
+export function projectMessagesPayloadWithoutReasoning(payload) {
+  if (Array.isArray(payload)) {
+    let changed = false;
+    const next = payload.map((entry) => {
+      const projected = projectRecord(entry);
+      if (projected !== entry) changed = true;
+      return projected;
+    });
+    return changed ? next : payload;
+  }
+
+  if (!isPlainObject(payload)) return payload;
+
+  let next = payload;
+  let changed = false;
+
+  if (Array.isArray(payload.records)) {
+    const records = projectMessagesPayloadWithoutReasoning(payload.records);
+    if (records !== payload.records) {
+      next = { ...next, records };
+      changed = true;
+    }
+  }
+
+  if (isPlainObject(payload.record)) {
+    const record = projectRecord(payload.record);
+    if (record !== payload.record) {
+      next = { ...next, record };
+      changed = true;
+    }
+  }
+
+  // Exact message / single record body: top-level parts.
+  if (Array.isArray(payload.parts)) {
+    const projected = projectRecord(next);
+    if (projected !== next) {
+      next = projected;
+      changed = true;
+    }
+  }
+
+  return changed ? next : payload;
+}
+
+/**
+ * @param {unknown} payload
+ * @param {boolean} includeReasoning
+ */
+export function projectMessagesPayloadForReasoning(payload, includeReasoning) {
+  if (includeReasoning) return payload;
+  return projectMessagesPayloadWithoutReasoning(payload);
+}
+
+const eventBodyKeys = /** @type {const} */ (['properties', 'data']);
+
+/** @param {unknown} payload */
+function eventBodyOf(payload) {
+  if (!isPlainObject(payload)) return null;
+  for (const key of eventBodyKeys) {
+    const body = payload[key];
+    if (isPlainObject(body)) return body;
+  }
+  return null;
+}
+
+/**
+ * Stateful per-connection outbound filter. Classification map is bounded.
+ * @returns {{ projectEvent: (payload: unknown) => unknown | null, knownPartCount: () => number, dispose: () => void }}
+ */
+export function createReasoningOutboundFilter() {
+  /** @type {Map<string, string>} */
+  const partTypes = new Map();
+
+  const partKey = (messageID, partID) => `${messageID}\0${partID}`;
+
+  const rememberPartType = (messageID, partID, type) => {
+    if (typeof messageID !== 'string' || !messageID) return;
+    if (typeof partID !== 'string' || !partID) return;
+    if (typeof type !== 'string' || !type) return;
+    const key = partKey(messageID, partID);
+    if (partTypes.size >= PART_TYPE_CACHE_LIMIT && !partTypes.has(key)) {
+      const oldest = partTypes.keys().next().value;
+      if (oldest !== undefined) partTypes.delete(oldest);
+    }
+    partTypes.set(key, type);
+  };
+
+  const forgetPart = (messageID, partID) => {
+    if (typeof messageID === 'string' && typeof partID === 'string') {
+      partTypes.delete(partKey(messageID, partID));
+    }
+  };
+
+  const forgetMessage = (messageID) => {
+    if (typeof messageID !== 'string' || !messageID) return;
+    const prefix = `${messageID}\0`;
+    for (const key of Array.from(partTypes.keys())) {
+      if (key.startsWith(prefix)) partTypes.delete(key);
+    }
+  };
+
+  /**
+   * @param {unknown} payload
+   * @returns {unknown | null} null = drop; otherwise original or shallow-cloned payload (type string preserved)
+   */
+  const projectEvent = (payload) => {
+    if (!isPlainObject(payload)) return payload;
+
+    const rawType = typeof payload.type === 'string' ? payload.type : '';
+    const type = baseEventType(rawType);
+
+    // session.next.reasoning.* (incl. versioned …reasoning.delta.1)
+    if (type.startsWith('session.next.reasoning.')) return null;
+
+    if (type === 'message.part.updated') {
+      const body = eventBodyOf(payload);
+      const part = body && isPlainObject(body.part) ? body.part : null;
+      if (part) {
+        const messageID =
+          (typeof part.messageID === 'string' && part.messageID)
+          || (typeof body.messageID === 'string' && body.messageID)
+          || '';
+        const partID = typeof part.id === 'string' ? part.id : '';
+        if (typeof part.type === 'string') rememberPartType(messageID, partID, part.type);
+        if (part.type === 'reasoning') return null;
+      }
+      return payload;
+    }
+
+    if (type === 'message.part.delta') {
+      const body = eventBodyOf(payload);
+      if (!body) return null;
+
+      const messageID = typeof body.messageID === 'string' ? body.messageID : '';
+      const partID = typeof body.partID === 'string' ? body.partID : '';
+      const field = typeof body.field === 'string' ? body.field : '';
+
+      if (REASONING_DELTA_FIELDS.has(field)) return null;
+
+      const learned = messageID && partID ? partTypes.get(partKey(messageID, partID)) : undefined;
+      if (learned === 'reasoning' || learned === undefined) return null;
+      return payload;
+    }
+
+    if (type === 'message.part.removed') {
+      const body = eventBodyOf(payload);
+      if (body) {
+        forgetPart(
+          typeof body.messageID === 'string' ? body.messageID : '',
+          typeof body.partID === 'string' ? body.partID : '',
+        );
+      }
+      return payload;
+    }
+
+    if (type === 'message.removed') {
+      const body = eventBodyOf(payload);
+      if (body) {
+        const messageID =
+          (typeof body.messageID === 'string' && body.messageID)
+          || (isPlainObject(body.info) && typeof body.info.id === 'string' && body.info.id)
+          || '';
+        forgetMessage(messageID);
+      }
+      return payload;
+    }
+
+    // message.updated / message.created may embed parts on properties or data.
+    if (type === 'message.updated' || type === 'message.created') {
+      let next = payload;
+      let changed = false;
+      for (const key of eventBodyKeys) {
+        const body = next[key];
+        if (!isPlainObject(body) || !Array.isArray(body.parts)) continue;
+        const parts = projectParts(body.parts);
+        if (parts === body.parts) continue;
+        next = { ...next, [key]: { ...body, parts } };
+        changed = true;
+      }
+      return changed ? next : payload;
+    }
+
+    return payload;
+  };
+
+  return {
+    projectEvent,
+    knownPartCount: () => partTypes.size,
+    dispose: () => {
+      partTypes.clear();
+    },
+  };
+}
+
+/**
+ * Project SSE data JSON; preserve GlobalEvent `{ directory, payload }` wrap.
+ * @param {unknown} dataJson
+ * @param {{ projectEvent: (payload: unknown) => unknown | null }} filter
+ */
+function projectSseDataJson(dataJson, filter) {
+  if (!isPlainObject(dataJson)) {
+    return { action: 'keep', value: dataJson, changed: false };
+  }
+
+  if (isPlainObject(dataJson.payload) && typeof dataJson.payload.type === 'string') {
+    const projected = filter.projectEvent(dataJson.payload);
+    if (projected == null) return { action: 'drop' };
+    if (projected === dataJson.payload) return { action: 'keep', value: dataJson, changed: false };
+    return { action: 'keep', value: { ...dataJson, payload: projected }, changed: true };
+  }
+
+  const projected = filter.projectEvent(dataJson);
+  if (projected == null) return { action: 'drop' };
+  if (projected === dataJson) return { action: 'keep', value: dataJson, changed: false };
+  return { action: 'keep', value: projected, changed: true };
+}
+
+/**
+ * Filter one SSE block (no trailing separator). null = drop.
+ * @param {string} block
+ * @param {{ projectEvent: (payload: unknown) => unknown | null }} filter
+ * @returns {string | null}
+ */
+export function filterSseBlock(block, filter) {
+  if (typeof block !== 'string' || block.trim().length === 0) return null;
+  if (!block.includes('data:')) return `${block}\n\n`;
+
+  const lines = block.split('\n');
+  const dataLines = [];
+  const otherLines = [];
+  for (const line of lines) {
+    if (line.startsWith('data:')) dataLines.push(line.slice(5).replace(/^\s/, ''));
+    else otherLines.push(line);
+  }
+  if (dataLines.length === 0) return `${block}\n\n`;
+
+  const payloadText = dataLines.join('\n').trim();
+  if (!payloadText) return `${block}\n\n`;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(payloadText);
+  } catch {
+    return `${block}\n\n`;
+  }
+
+  const result = projectSseDataJson(parsed, filter);
+  if (result.action === 'drop') return null;
+  if (!result.changed) return `${block}\n\n`;
+  return [...otherLines, `data: ${JSON.stringify(result.value)}`, '', ''].join('\n');
+}
+
+/**
+ * Incremental SSE block splitter. Holds a trailing CR so `\r` + `\n` across
+ * chunks never invents a false blank line (which would split one event in two).
+ */
+export function createSseBlockSplitter() {
+  const decoder = new TextDecoder();
+  let buffer = '';
+  /** @type {string} trailing CR held until the next chunk clarifies `\r\n` vs lone `\r` */
+  let carryCr = '';
+
+  const appendNormalized = (text) => {
+    if (!text && !carryCr) return;
+    let input = carryCr + (text || '');
+    carryCr = '';
+    if (input.endsWith('\r')) {
+      carryCr = '\r';
+      input = input.slice(0, -1);
+    }
+    // Complete CRLF pairs first, then any remaining lone CR → LF.
+    buffer += input.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  };
+
+  const drainBlocks = () => {
+    const blocks = [];
+    while (true) {
+      const idx = buffer.indexOf('\n\n');
+      if (idx === -1) break;
+      const block = buffer.slice(0, idx);
+      buffer = buffer.slice(idx + 2);
+      if (block.trim().length > 0) blocks.push(block);
+    }
+    return blocks;
+  };
+
+  return {
+    /**
+     * @param {Uint8Array | string} chunk
+     * @returns {string[]}
+     */
+    push(chunk) {
+      const text = typeof chunk === 'string'
+        ? chunk
+        : decoder.decode(chunk, { stream: true });
+      if (!text) return [];
+      appendNormalized(text);
+      return drainBlocks();
+    },
+    /** @returns {string[]} */
+    finish() {
+      const tail = decoder.decode();
+      if (tail) appendNormalized(tail);
+      if (carryCr) {
+        buffer += '\n';
+        carryCr = '';
+      }
+      const remaining = buffer;
+      buffer = '';
+      return remaining.trim().length > 0 ? [remaining] : [];
+    },
+  };
+}