@coseung2/opencodex 2.8.0-cs.13 → 2.8.0-cs.14

package/src/server/responses/ws-upstream.ts

@@ -0,0 +1,318 @@
+// Upstream WebSocket transport for the ChatGPT Codex backend.
+//
+// Why this exists: the Codex backend serves the responses_websockets path from
+// a measurably faster queue than the plain SSE POST path. Measured 2026-08-12
+// KST (same account, same payload, strictly sequential): gpt-5.6-luna TTFT p50
+// ~1.0s over WS vs ~3.9s over SSE. Codex CLI itself defaults to the WS
+// transport; opencodex previously always POSTed SSE, which is where its extra
+// 2-3s of TTFT came from.
+//
+// The wrapper only swaps the transport. It dials wss:// with the same headers,
+// sends the JSON body as a single `response.create` frame, and re-encodes the
+// returned event frames as an SSE byte stream, so every downstream consumer
+// (passthrough relay, adapter parsers, usage sniffing) is unchanged.
+
+import { MAX_CLIENT_SSE_FRAME_BYTES } from "../sse-frame-buffer";
+import { compareBunVersions } from "../../lib/bun-stream-caps";
+
+const CODEX_RESPONSES_HTTP_URL = "https://chatgpt.com/backend-api/codex/responses";
+const CODEX_RESPONSES_WS_URL = "wss://chatgpt.com/backend-api/codex/responses";
+const WS_BETA = "responses_websockets=2026-02-06";
+// If the 101 never arrives (network black hole), give SSE a chance well before
+// the caller's connect timeout (default 200s) would fire.
+const UPGRADE_DEADLINE_MS = 10_000;
+// Keep the push-based WS transport inside the same memory envelope as the
+// bounded SSE relays that consume this response. Unlike fetch response bodies,
+// a WebSocket cannot be paused when a ReadableStream applies backpressure, so
+// an upstream that outruns the consumer must be disconnected.
+export const MAX_CODEX_WS_FRAME_BYTES = MAX_CLIENT_SSE_FRAME_BYTES;
+export const MAX_CODEX_WS_QUEUE_BYTES = 8 * 1024 * 1024;
+export const MIN_BOUNDED_CODEX_WS_BUN_VERSION = "1.4.0";
+
+export type BunRuntimeIdentity = {
+  version: string;
+  versionWithSha: string;
+};
+
+export type BunRuntimeGateInput = string | BunRuntimeIdentity;
+
+const codexWsUpstreamResponses = new WeakSet<Response>();
+
+/** True only for a successful Codex WebSocket upgrade, never an HTTP fallback. */
+export function isCodexWsUpstreamResponse(response: Response): boolean {
+  return codexWsUpstreamResponses.has(response);
+}
+
+export function currentBunRuntimeIdentity(): BunRuntimeIdentity {
+  return {
+    version: Bun.version,
+    versionWithSha: Bun.version_with_sha,
+  };
+}
+
+function boundedRelayVersion(input: BunRuntimeGateInput): string | null {
+  if (typeof input === "string") return input.trim() || null;
+  const numericVersion = input.version.trim();
+  const numericMatch = /^(\d+\.\d+\.\d+)$/.exec(numericVersion);
+  const detailedMatch = /^v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\s+\([0-9a-fA-F]+\)$/.exec(
+    input.versionWithSha.trim(),
+  );
+  if (!numericMatch || !detailedMatch) return null;
+  const detailedNumeric = /^(\d+\.\d+\.\d+)/.exec(detailedMatch[1])?.[1];
+  return detailedNumeric === numericMatch[1] ? detailedMatch[1] : null;
+}
+
+/**
+ * Bun 1.3.14 does not propagate a stalled HTTP response socket back to a JS
+ * ReadableStream producer on Windows. A real raw-TCP slow-client probe drained
+ * the entire upstream despite the eager relay queue; Bun 1.4.0-canary.1 stopped
+ * below one MiB. Prereleases still fail closed; release builds before 1.4.0
+ * fall back to HTTP SSE.
+ */
+export function bunSupportsBoundedCodexWsRelay(
+  runtime: BunRuntimeGateInput = currentBunRuntimeIdentity(),
+): boolean {
+  const version = boundedRelayVersion(runtime);
+  if (!version) return false;
+  if (/^\d+\.\d+\.\d+-/.test(version.trim())) return false;
+  const comparison = compareBunVersions(version, MIN_BOUNDED_CODEX_WS_BUN_VERSION);
+  return comparison !== null && comparison >= 0;
+}
+
+export function shouldUseCodexWsUpstream(
+  url: string,
+  init?: RequestInit,
+  runtime: BunRuntimeGateInput = currentBunRuntimeIdentity(),
+): boolean {
+  if (!bunSupportsBoundedCodexWsRelay(runtime)) return false;
+  if (url !== CODEX_RESPONSES_HTTP_URL) return false;
+  if ((init?.method ?? "GET").toUpperCase() !== "POST") return false;
+  const body = init?.body;
+  if (typeof body !== "string") return false;
+  // Only root-level stream:true selects WS: JSON-mode calls keep the HTTP path
+  // because the WS path only speaks the event protocol, and a nested
+  // {"metadata":{"stream":true}} must not flip the transport. Parsing (not
+  // substring matching) also keeps whitespace-formatted bodies routable.
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+      && (parsed as Record<string, unknown>).stream === true;
+  } catch {
+    return false;
+  }
+}
+
+export function codexWsUpstreamFetch(
+  url: string,
+  init: RequestInit,
+  sseFallback: typeof globalThis.fetch,
+  runtime: BunRuntimeGateInput = currentBunRuntimeIdentity(),
+): Promise<Response> {
+  if (!bunSupportsBoundedCodexWsRelay(runtime)) {
+    return sseFallback(url, init);
+  }
+  const signal = init.signal ?? undefined;
+  if (signal?.aborted) {
+    return Promise.reject(signal.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+  }
+
+  let frameText: string;
+  try {
+    const body = JSON.parse(init.body as string) as Record<string, unknown>;
+    // The WS create frame is implicitly streaming; the backend rejects the
+    // HTTP-only `stream` flag inside a frame.
+    delete body.stream;
+    frameText = JSON.stringify({ ...body, type: "response.create" });
+  } catch {
+    return sseFallback(url, init);
+  }
+
+  const headers: Record<string, string> = {};
+  new Headers(init.headers ?? {}).forEach((value, key) => {
+    // HTTP-body framing headers do not apply to a WS handshake.
+    if (key === "content-type" || key === "content-length" || key === "accept" || key === "accept-encoding") return;
+    headers[key] = value;
+  });
+  headers["openai-beta"] = headers["openai-beta"]
+    ? headers["openai-beta"].includes("responses_websockets")
+      ? headers["openai-beta"]
+      : `${headers["openai-beta"]}, ${WS_BETA}`
+    : WS_BETA;
+  // A genuine caller `originator` is already in these headers via the forward
+  // set. Never fabricate one here: pool/forward traffic must not impersonate
+  // Codex CLI, per the metadata-integrity contract. (The backend's fast lane
+  // keys on WS + originator, so callers without the tag simply keep their own
+  // provenance and scheduling.)
+
+  return new Promise<Response>((resolve, reject) => {
+    let ws: WebSocket;
+    try {
+      // Bun accepts per-handshake headers; the DOM lib types only list protocol arrays.
+      ws = new WebSocket(CODEX_RESPONSES_WS_URL, { headers } as unknown as string[]);
+    } catch {
+      resolve(sseFallback(url, init));
+      return;
+    }
+
+    let opened = false;
+    let settledPreOpen = false;
+    let terminal = false;
+    let controller: ReadableStreamDefaultController<Uint8Array> | null = null;
+    const encoder = new TextEncoder();
+
+    const failStream = (message: string) => {
+      if (terminal) return;
+      terminal = true;
+      try { controller?.error(new Error(message)); } catch { /* stream already done */ }
+      try { ws.close(); } catch { /* already closing */ }
+    };
+
+    const upgradeTimer = setTimeout(() => {
+      if (opened || settledPreOpen) return;
+      settledPreOpen = true;
+      try { ws.close(); } catch { /* already closing */ }
+      resolve(sseFallback(url, init));
+    }, UPGRADE_DEADLINE_MS);
+
+    const onAbort = () => {
+      if (!opened) {
+        if (settledPreOpen) return;
+        // Settle BEFORE close(): the close handler treats a pre-open close as
+        // an upgrade rejection and would dial the SSE fallback for a request
+        // the caller just cancelled.
+        settledPreOpen = true;
+        clearTimeout(upgradeTimer);
+        try { ws.close(); } catch { /* already closing */ }
+        reject(signal?.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+        return;
+      }
+      if (controller && !terminal) {
+        terminal = true;
+        // Mirror an aborted fetch: the body read rejects with the abort reason.
+        try { controller.error(signal?.reason ?? new DOMException("The operation was aborted.", "AbortError")); } catch { /* stream already done */ }
+      }
+      // Error the body before close(): test doubles and some runtimes dispatch
+      // close synchronously, and the caller's abort reason must stay authoritative.
+      try { ws.close(); } catch { /* already closing */ }
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    ws.addEventListener("open", () => {
+      if (settledPreOpen) return;
+      clearTimeout(upgradeTimer);
+      try {
+        ws.send(frameText);
+      } catch {
+        // send() throwing means the frame never left, so no upstream turn
+        // started and the SSE resend cannot double-generate. Falling back
+        // (instead of erroring a synthetic 200 body) keeps the pre-stream
+        // HTTP error/refresh/failover machinery in charge.
+        settledPreOpen = true;
+        try { ws.close(); } catch { /* already closing */ }
+        resolve(sseFallback(url, init));
+        return;
+      }
+      opened = true;
+      const stream = new ReadableStream<Uint8Array>({
+        start(c) { controller = c; },
+        cancel() { try { ws.close(); } catch { /* already closing */ } },
+      }, new ByteLengthQueuingStrategy({ highWaterMark: MAX_CODEX_WS_QUEUE_BYTES }));
+      const response = new Response(stream, {
+        status: 200,
+        // The 101 response headers (x-codex-*-reset-at quota hints) are not
+        // exposed by Bun's WebSocket; the periodic quota poller covers those.
+        headers: { "content-type": "text/event-stream; charset=utf-8" },
+      });
+      codexWsUpstreamResponses.add(response);
+      resolve(response);
+    });
+
+    ws.addEventListener("message", (event) => {
+      if (!controller || terminal) return;
+      const text = typeof event.data === "string" ? event.data : "";
+      if (!text) return;
+      // UTF-8 byte length is always at least the JS string length. Reject this
+      // cheap lower bound before parsing so an obviously oversized frame does
+      // not create another large object graph.
+      if (text.length > MAX_CODEX_WS_FRAME_BYTES) {
+        failStream("codex websocket frame exceeds the response size limit");
+        return;
+      }
+      const encodedText = encoder.encode(text);
+      if (encodedText.byteLength > MAX_CODEX_WS_FRAME_BYTES) {
+        failStream("codex websocket frame exceeds the response size limit");
+        return;
+      }
+      let type: unknown;
+      try { type = (JSON.parse(text) as { type?: unknown }).type; } catch { return; }
+      if (typeof type !== "string") return;
+      // Relay only the event surface the SSE path produces today. WS-only
+      // frames (codex.rate_limits, responsesapi.websocket_timing) are dropped
+      // so downstream clients see exactly the stream shape they always got.
+      if (!type.startsWith("response.") && type !== "error") return;
+      const prefix = encoder.encode(`event: ${type}\ndata: `);
+      const suffix = encoder.encode("\n\n");
+      const isTerminal = type === "response.completed" || type === "response.failed"
+        || type === "response.incomplete" || type === "error";
+      // The HTTP SSE transport ends with [DONE]. The WebSocket protocol does
+      // not send that sentinel, so append it to the terminal frame to keep
+      // the existing Codex-facing stream contract unchanged in this fork.
+      const done = isTerminal ? encoder.encode("data: [DONE]\n\n") : undefined;
+      const frameBytes = prefix.byteLength + encodedText.byteLength + suffix.byteLength
+        + (done?.byteLength ?? 0);
+      if (frameBytes > MAX_CLIENT_SSE_FRAME_BYTES) {
+        failStream("codex websocket frame exceeds the response size limit");
+        return;
+      }
+      const availableBytes = controller.desiredSize ?? 0;
+      if (frameBytes > availableBytes) {
+        failStream("codex websocket response exceeded the buffered queue limit");
+        return;
+      }
+      const sseFrame = new Uint8Array(frameBytes);
+      sseFrame.set(prefix);
+      sseFrame.set(encodedText, prefix.byteLength);
+      sseFrame.set(suffix, prefix.byteLength + encodedText.byteLength);
+      if (done) {
+        sseFrame.set(done, prefix.byteLength + encodedText.byteLength + suffix.byteLength);
+      }
+      try {
+        controller.enqueue(sseFrame);
+      } catch {
+        failStream("codex websocket response stream closed while enqueueing");
+        return;
+      }
+      if (isTerminal) {
+        terminal = true;
+        try { controller.close(); } catch { /* already closed */ }
+        try { ws.close(); } catch { /* already closing */ }
+      }
+    });
+
+    ws.addEventListener("close", () => {
+      signal?.removeEventListener("abort", onAbort);
+      if (!opened) {
+        if (settledPreOpen) return;
+        settledPreOpen = true;
+        clearTimeout(upgradeTimer);
+        // Upgrade rejected (401/403/429/5xx). Retry over plain SSE so the real
+        // HTTP status reaches the existing refresh/rotation handlers. No turn
+        // started upstream, so the resend cannot double-generate.
+        resolve(sseFallback(url, init));
+        return;
+      }
+      if (controller && !terminal) {
+        terminal = true;
+        // Connection dropped before a Responses terminal event. A clean EOF
+        // here would reach clients with no response.completed/failed at all —
+        // relaySseWithFailedTail() only synthesizes a failed terminal when the
+        // body read THROWS. Error the stream like a reset TCP socket.
+        try { controller.error(new Error("codex websocket closed before a Responses terminal event")); } catch { /* stream already done */ }
+      }
+    });
+
+    ws.addEventListener("error", () => {
+      /* Bun always follows error with close; the close handler settles. */
+    });
+  });
+}

package/src/server/sse-frame-buffer.ts

@@ -0,0 +1,292 @@
+export const MAX_CLIENT_SSE_FRAME_BYTES = 4 * 1024 * 1024;
+
+const LF_LF = Uint8Array.of(10, 10);
+const LF_CR_LF = Uint8Array.of(10, 13, 10);
+const CR_LF_LF = Uint8Array.of(13, 10, 10);
+const CR_LF_CR_LF = Uint8Array.of(13, 10, 13, 10);
+
+export class SseFrameTooLargeError extends Error {
+  readonly maxBytes: number;
+
+  constructor(maxBytes: number) {
+    super(`upstream SSE frame exceeded ${maxBytes} bytes`);
+    this.name = "SseFrameTooLargeError";
+    this.maxBytes = maxBytes;
+  }
+}
+
+export class SseFrameCountLimitError extends Error {
+  readonly maxFrames: number;
+
+  constructor(maxFrames: number) {
+    super(`upstream SSE chunk exceeded ${maxFrames} frame limit`);
+    this.name = "SseFrameCountLimitError";
+    this.maxFrames = maxFrames;
+  }
+}
+
+export type BoundedSseFrame = {
+  block: Uint8Array;
+  delimiter: Uint8Array;
+};
+
+/**
+ * Classify the bytes at `index` as an SSE block delimiter.
+ *
+ * Returns the delimiter length in bytes, `0` when `index` does not start a
+ * delimiter, and `undefined` when more bytes are required to decide.
+ */
+function delimiterLengthAt(
+  index: number,
+  length: number,
+  byteAt: (index: number) => number,
+): number | undefined {
+  const first = byteAt(index);
+  if (first === 10) {
+    if (index + 1 >= length) return undefined;
+    const second = byteAt(index + 1);
+    if (second === 10) return 2;
+    if (second !== 13) return 0;
+    if (index + 2 >= length) return undefined;
+    return byteAt(index + 2) === 10 ? 3 : 0;
+  }
+  if (first !== 13) return 0;
+  if (index + 1 >= length) return undefined;
+  if (byteAt(index + 1) !== 10) return 0;
+  if (index + 2 >= length) return undefined;
+  const third = byteAt(index + 2);
+  if (third === 10) return 3;
+  if (third !== 13) return 0;
+  if (index + 3 >= length) return undefined;
+  return byteAt(index + 3) === 10 ? 4 : 0;
+}
+
+function delimiterBytesAt(
+  index: number,
+  delimiterLength: number,
+  byteAt: (index: number) => number,
+): Uint8Array {
+  if (delimiterLength === 2) return LF_LF;
+  if (delimiterLength === 4) return CR_LF_CR_LF;
+  return byteAt(index) === 10 ? LF_CR_LF : CR_LF_LF;
+}
+
+function copyRange(
+  start: number,
+  end: number,
+  tailLength: number,
+  previousTail: Uint8Array,
+  chunk: Uint8Array,
+): Uint8Array {
+  const out = new Uint8Array(end - start);
+  for (let index = start; index < end; index += 1) {
+    out[index - start] = index < tailLength
+      ? previousTail[index]!
+      : chunk[index - tailLength]!;
+  }
+  return out;
+}
+
+/**
+ * True when a complete SSE block already commits a Responses terminal event.
+ *
+ * Framing errors in bytes *after* such a block must not retroactively turn an
+ * already-completed/failed/incomplete model turn into a transport failure. This
+ * helper is used only on the exceptional path, so decoding/JSON parsing has no
+ * cost on ordinary framing.
+ */
+function isResponsesTerminalFrame(block: Uint8Array): boolean {
+  const data: string[] = [];
+  for (const line of new TextDecoder().decode(block).split(/\r?\n/)) {
+    if (!line.startsWith("data:")) continue;
+    const value = line.slice(5);
+    data.push(value.startsWith(" ") ? value.slice(1) : value);
+  }
+  if (data.length === 0) return false;
+  const payload = data.join("\n");
+  if (payload === "[DONE]") return false;
+  try {
+    const parsed = JSON.parse(payload) as { type?: unknown };
+    return parsed.type === "response.completed"
+      || parsed.type === "response.failed"
+      || parsed.type === "response.incomplete";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Byte-bounded SSE block framer for client-facing protocol paths.
+ *
+ * The delimiter scanner works on raw bytes, so fragmented UTF-8 cannot change
+ * accounting and a hostile upstream cannot grow an unterminated JS string
+ * without limit. Candidate bytes live in one geometrically grown buffer rather
+ * than one allocation per upstream chunk, bounding both bytes and object count.
+ * Complete blocks are returned without their delimiter; the exact delimiter
+ * bytes are returned separately so callers can relay bytes unchanged.
+ */
+export class BoundedSseFrameBuffer {
+  private readonly maxFrameBytes: number;
+  private readonly maxFramesPerFeed: number;
+  private delimiterTail: Uint8Array = new Uint8Array(0);
+  private candidate: Uint8Array = new Uint8Array(0);
+  private candidateBytes = 0;
+  private disposed = false;
+
+  constructor(maxFrameBytes = MAX_CLIENT_SSE_FRAME_BYTES) {
+    if (!Number.isSafeInteger(maxFrameBytes) || maxFrameBytes <= 0) {
+      throw new RangeError("maxFrameBytes must be a positive safe integer");
+    }
+    this.maxFrameBytes = maxFrameBytes;
+    // Delimiter-only input otherwise creates an object-amplification path that
+    // is independent of candidate bytes. Keep frame count proportional to the
+    // configured byte budget while leaving ample room for real Responses events.
+    this.maxFramesPerFeed = Math.max(1, Math.ceil(maxFrameBytes / 1024));
+  }
+
+  private clear(): void {
+    this.delimiterTail = new Uint8Array(0);
+    this.candidate = new Uint8Array(0);
+    this.candidateBytes = 0;
+  }
+
+  private ensureCapacity(requiredBytes: number): void {
+    if (this.candidate.byteLength >= requiredBytes) return;
+    if (requiredBytes > this.maxFrameBytes) {
+      throw new SseFrameTooLargeError(this.maxFrameBytes);
+    }
+    let capacity = this.candidate.byteLength === 0
+      ? Math.min(this.maxFrameBytes, Math.max(requiredBytes, 4096))
+      : this.candidate.byteLength;
+    while (capacity < requiredBytes) {
+      capacity = Math.min(this.maxFrameBytes, Math.max(requiredBytes, capacity * 2));
+    }
+    const grown = new Uint8Array(capacity);
+    if (this.candidateBytes > 0) {
+      grown.set(this.candidate.subarray(0, this.candidateBytes));
+    }
+    this.candidate = grown;
+  }
+
+  private retain(slice: Uint8Array): void {
+    if (slice.byteLength === 0) return;
+    const nextBytes = this.candidateBytes + slice.byteLength;
+    if (nextBytes > this.maxFrameBytes) {
+      this.clear();
+      this.disposed = true;
+      throw new SseFrameTooLargeError(this.maxFrameBytes);
+    }
+    this.ensureCapacity(nextBytes);
+    this.candidate.set(slice, this.candidateBytes);
+    this.candidateBytes = nextBytes;
+  }
+
+  private takeCandidate(): Uint8Array {
+    if (this.candidateBytes === 0) return new Uint8Array(0);
+    const block = this.candidate.slice(0, this.candidateBytes);
+    // Release the working allocation after each complete frame. This avoids
+    // retaining a rare multi-MiB frame allocation for the rest of a long-lived
+    // stream; normal small-frame allocation remains bounded by feed's frame cap.
+    this.candidate = new Uint8Array(0);
+    this.candidateBytes = 0;
+    return block;
+  }
+
+  feed(chunk: Uint8Array): BoundedSseFrame[] {
+    if (this.disposed) return [];
+    if (chunk.byteLength === 0) return [];
+
+    const frames: BoundedSseFrame[] = [];
+    const previousTail = this.delimiterTail;
+    this.delimiterTail = new Uint8Array(0);
+    const tailLength = previousTail.byteLength;
+    const totalLength = tailLength + chunk.byteLength;
+    const byteAt = (index: number): number => index < tailLength
+      ? previousTail[index]!
+      : chunk[index - tailLength]!;
+    const retainRange = (start: number, end: number): void => {
+      if (end <= start) return;
+      if (start < tailLength) {
+        this.retain(previousTail.subarray(start, Math.min(end, tailLength)));
+      }
+      if (end > tailLength) {
+        this.retain(chunk.subarray(Math.max(0, start - tailLength), end - tailLength));
+      }
+    };
+
+    try {
+      let index = 0;
+      let retainedThrough = 0;
+      while (index < totalLength) {
+        const delimiterLength = delimiterLengthAt(index, totalLength, byteAt);
+        if (delimiterLength === undefined) break;
+        if (delimiterLength > 0) {
+          if (frames.length >= this.maxFramesPerFeed) {
+            this.clear();
+            this.disposed = true;
+            throw new SseFrameCountLimitError(this.maxFramesPerFeed);
+          }
+          retainRange(retainedThrough, index);
+          const block = this.takeCandidate();
+          const delimiter = delimiterBytesAt(index, delimiterLength, byteAt);
+          frames.push({ block, delimiter });
+          index += delimiterLength;
+          retainedThrough = index;
+          continue;
+        }
+        index += 1;
+      }
+
+      retainRange(retainedThrough, index);
+      if (index < totalLength) {
+        this.delimiterTail = copyRange(index, totalLength, tailLength, previousTail, chunk);
+      }
+      return frames;
+    } catch (err) {
+      const framingError = err instanceof SseFrameTooLargeError
+        || err instanceof SseFrameCountLimitError;
+      if (framingError && frames.some(frame => isResponsesTerminalFrame(frame.block))) {
+        // A terminal frame is the Responses protocol boundary. Ignore malformed
+        // or oversized bytes that occur later in the same upstream chunk rather
+        // than retroactively replacing the committed terminal with a 502.
+        this.clear();
+        this.disposed = true;
+        return frames;
+      }
+      throw err;
+    }
+  }
+
+  /** Return the final unterminated block bytes and release all retained state. */
+  finish(): Uint8Array {
+    if (this.disposed) return new Uint8Array(0);
+    try {
+      this.retain(this.delimiterTail);
+      this.delimiterTail = new Uint8Array(0);
+      return this.takeCandidate();
+    } finally {
+      this.clear();
+      this.disposed = true;
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.clear();
+    this.disposed = true;
+  }
+}
+
+export function joinSseFrameBytes(parts: readonly Uint8Array[]): Uint8Array {
+  let byteLength = 0;
+  for (const part of parts) byteLength += part.byteLength;
+  if (byteLength === 0) return new Uint8Array(0);
+  if (parts.length === 1 && parts[0]!.byteLength === byteLength) return parts[0]!;
+  const joined = new Uint8Array(byteLength);
+  let offset = 0;
+  for (const part of parts) {
+    joined.set(part, offset);
+    offset += part.byteLength;
+  }
+  return joined;
+}

package/src/server/ws-bridge.ts

@@ -5,6 +5,7 @@ import { headersForCodexAuthContext } from "../codex/auth-context";
 import type { ResponsesTerminalStatus } from "../bridge";
 import type { DataPlaneAdmission } from "./auth-cors";
 import type { AdmissionReservation } from "../lib/admission";
+import { BoundedSseFrameBuffer } from "./sse-frame-buffer";
 
 const OPEN = 1;
 type ResponsesTerminalReporter = (status: ResponsesTerminalStatus) => void;
@@ -224,7 +225,7 @@ export async function pumpResponsesSseToWebSocket(
   ws.data.cancel = cancel;
 
   const decoder = new TextDecoder();
-  let buffer = "";
+  const framer = new BoundedSseFrameBuffer();
   let terminalSeen = false;
 
   const handlePayload = (payload: string): boolean => {
@@ -259,17 +260,14 @@ export async function pumpResponsesSseToWebSocket(
     while (!terminalSeen) {
       const { done, value } = await reader.read();
       if (done) break;
-      buffer += decoder.decode(value, { stream: true });
-      let next: { block: string; rest: string } | null;
-      while ((next = nextSseBlock(buffer))) {
-        buffer = next.rest;
-        const payload = parseSseBlock(next.block);
+      for (const frame of framer.feed(value)) {
+        const payload = parseSseBlock(decoder.decode(frame.block));
         if (payload && handlePayload(payload)) break;
       }
     }
-    buffer += decoder.decode();
-    if (!terminalSeen && buffer.trim()) {
-      const payload = parseSseBlock(buffer);
+    const tail = framer.finish();
+    if (!terminalSeen && tail.byteLength > 0) {
+      const payload = parseSseBlock(decoder.decode(tail));
       if (payload) handlePayload(payload);
     }
     if (!terminalSeen && isCurrent() && !clientCancelled) {
@@ -277,11 +275,19 @@ export async function pumpResponsesSseToWebSocket(
       sendProtocolError(ws, 502, "Upstream stream ended before response terminal event");
     }
   } catch (err) {
+    framer.dispose();
+    if (err instanceof WsSendDroppedError) throw err;
     if (!terminalSeen && isCurrent() && ws.readyState === OPEN) {
-      if (!(err instanceof WsSendDroppedError)) reportTerminal("incomplete");
-      sendProtocolError(ws, 502, err instanceof Error ? err.message : String(err));
+      reportTerminal("incomplete");
+      try {
+        sendProtocolError(ws, 502, err instanceof Error ? err.message : String(err));
+      } catch (sendErr) {
+        if (!(sendErr instanceof WsSendDroppedError)) throw sendErr;
+      }
     }
   } finally {
+    framer.dispose();
+    void reader.cancel().catch(() => {});
     if (ws.data.cancel === cancel) ws.data.cancel = undefined;
   }
 }