@bitkyc08/opencodex 2.42.0 → 2.43.0

package/src/server/responses/codex-ws-metadata.ts

@@ -0,0 +1,134 @@
+import { isSafeResponseHeader, safeResponseHeaders } from "../safe-response-headers";
+
+export const CODEX_WS_METADATA_MAX_BYTES = 32 * 1024;
+export const CODEX_WS_METADATA_MAX_FAMILIES = 16;
+export const CODEX_WS_METADATA_MAX_HEADERS = 128;
+export const CODEX_WS_METADATA_MAX_VALUE_BYTES = 4096;
+
+export type CodexWsQuotaObserver = (headers: Headers) => void;
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function finiteNonnegative(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function nativeLimitFamily(event: Record<string, unknown>): string | null {
+  const raw = event.metered_limit_name ?? event.limit_name ?? "codex";
+  if (typeof raw !== "string") return null;
+  const name = raw.trim().toLowerCase().replaceAll("_", "-");
+  return name.length <= 64 && /^codex(?:-[a-z0-9-]+)?$/.test(name) ? name : null;
+}
+
+function writeWindow(headers: Headers, prefix: string, value: unknown): void {
+  if (!record(value) || !finiteNonnegative(value.used_percent)) return;
+  headers.set(`${prefix}-used-percent`, String(value.used_percent));
+  for (const [field, suffix] of [["window_minutes", "window-minutes"], ["reset_at", "reset-at"]]) {
+    const number = value[field!];
+    if (finiteNonnegative(number) && Number.isSafeInteger(number)) headers.set(`${prefix}-${suffix}`, String(number));
+  }
+}
+
+function quotaHeaders(event: Record<string, unknown>): Headers {
+  const headers = new Headers();
+  const family = nativeLimitFamily(event);
+  if (family && record(event.rate_limits)) {
+    writeWindow(headers, `x-${family}-primary`, event.rate_limits.primary);
+    writeWindow(headers, `x-${family}-secondary`, event.rate_limits.secondary);
+  }
+  if (record(event.credits)) {
+    for (const [field, suffix] of [["has_credits", "has-credits"], ["unlimited", "unlimited"]]) {
+      const value = event.credits[field!];
+      if (typeof value === "boolean") headers.set(`x-codex-credits-${suffix}`, String(value));
+    }
+    if (typeof event.credits.balance === "string") setMetadataHeader(headers, "x-codex-credits-balance", event.credits.balance);
+  }
+  return headers;
+}
+
+function setMetadataHeader(headers: Headers, name: string, value: string): void {
+  if (Buffer.byteLength(value) > CODEX_WS_METADATA_MAX_VALUE_BYTES) throw new Error("codex websocket metadata value exceeds the size limit");
+  if (/[\r\n\0]/.test(value)) return;
+  try { headers.set(name, value); } catch { /* invalid provider header is not HTTP authority */ }
+}
+
+function responseHeaders(value: unknown): Headers {
+  const headers = new Headers();
+  if (!record(value)) return headers;
+  for (const [name, field] of Object.entries(value)) {
+    if (!isSafeResponseHeader(name)) continue;
+    if (typeof field !== "string" && typeof field !== "number" && typeof field !== "boolean") continue;
+    setMetadataHeader(headers, name, String(field));
+  }
+  return headers;
+}
+
+function assertMetadataBounds(headers: Headers): void {
+  let bytes = 0;
+  let count = 0;
+  const families = new Set<string>();
+  for (const [name, value] of headers) {
+    bytes += Buffer.byteLength(name) + Buffer.byteLength(value);
+    count++;
+    const family = /^(x-codex(?:-[a-z0-9-]+)?)-(?:(?:primary|secondary|tertiary)-(?:used-percent|window-minutes|reset-at)|limit-name)$/.exec(name);
+    if (family) families.add(family[1]!);
+  }
+  if (bytes > CODEX_WS_METADATA_MAX_BYTES || count > CODEX_WS_METADATA_MAX_HEADERS || families.size > CODEX_WS_METADATA_MAX_FAMILIES) {
+    throw new Error("codex websocket metadata exceeds the bounded header budget");
+  }
+}
+
+/** One exchange's metadata. The Response owns its final snapshot, not a global history ledger. */
+export class CodexWsMetadata {
+  private headers = new Headers();
+  private ended = false;
+  private preludeBytes = 0;
+  private committed = false;
+
+  constructor(private observer?: CodexWsQuotaObserver) {}
+
+  snapshot(): Headers { return new Headers(this.headers); }
+
+  private publishQuota(headers: Headers): void {
+    // Observation is auxiliary bookkeeping; a consumer exception cannot turn
+    // a valid provider frame into a retryable transport failure.
+    try { this.observer?.(new Headers(headers)); } catch { /* quota observation is best-effort */ }
+  }
+
+  commit(): void {
+    this.committed = true;
+  }
+
+  /** Returns a sanitized control frame, or null for an ordinary Responses event. */
+  consume(event: Record<string, unknown>, bytes: number): string | null {
+    if (this.ended) return null;
+    if (event.type !== "codex.rate_limits" && event.type !== "codex.response.metadata") return null;
+    if (bytes > CODEX_WS_METADATA_MAX_BYTES) throw new Error("codex websocket metadata frame exceeds the size limit");
+    if (!this.committed) this.preludeBytes += bytes;
+    if (this.preludeBytes > CODEX_WS_METADATA_MAX_BYTES) throw new Error("codex websocket metadata prelude exceeds the size limit");
+    const updates = event.type === "codex.rate_limits" ? quotaHeaders(event) : responseHeaders(event.headers);
+    const next = this.snapshot();
+    for (const name of updates.keys()) {
+      if (!name.endsWith("-used-percent")) continue;
+      const prefix = name.slice(0, -"used-percent".length);
+      next.delete(`${prefix}window-minutes`);
+      next.delete(`${prefix}reset-at`);
+    }
+    for (const [name, value] of updates) next.set(name, value);
+    assertMetadataBounds(next);
+    this.headers = next;
+    if (["primary", "secondary", "tertiary"].some(window => updates.has(`x-codex-${window}-used-percent`))) {
+      this.publishQuota(updates);
+    }
+    return event.type === "codex.response.metadata"
+      ? JSON.stringify({ type: event.type, headers: safeResponseHeaders(updates) })
+      : JSON.stringify(event);
+  }
+
+  finish(): void {
+    this.ended = true;
+    this.observer = undefined;
+  }
+}

package/src/server/responses/codex-ws-pool.ts

@@ -0,0 +1,162 @@
+import { createHmac, randomBytes } from "node:crypto";
+import { registerOptionalShutdownHook } from "../../lib/optional-shutdown-hooks";
+import { CODEX_RESPONSES_HTTP_URL } from "./codex-ws-request";
+import { CODEX_WS_ID_MAX_BYTES } from "./codex-ws-correlation";
+import { CodexWsSession } from "./codex-ws-session";
+
+export const CODEX_WS_POOL_MAX_SESSIONS = 32;
+export const CODEX_WS_POOL_IDLE_MS = 30_000;
+export const CODEX_WS_POOL_MAX_AGE_MS = 5 * 60_000;
+const MUTABLE_HEADERS = new Set(["x-codex-turn-state", "x-codex-turn-metadata"]);
+let processKey: Buffer | undefined;
+let poolSequence = 0;
+
+export interface CodexWsReuseIdentity { key: string; scope: string }
+function value(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0
+    && !/[\u0000-\u001f\u007f]/.test(value) && Buffer.byteLength(value) <= CODEX_WS_ID_MAX_BYTES;
+}
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function digest(input: unknown): string {
+  processKey ??= randomBytes(32);
+  return createHmac("sha256", processKey).update(JSON.stringify(input)).digest("hex");
+}
+
+/** Identity comes from the selected outgoing request, never a model label or caller hint. */
+export function codexWsReuseIdentity(url: string, headers: Record<string, string>, frameText: string): CodexWsReuseIdentity | null {
+  if (url !== CODEX_RESPONSES_HTTP_URL) return null;
+  let body: unknown;
+  try { body = JSON.parse(frameText); } catch { return null; }
+  if (!record(body) || !record(body.client_metadata)) return null;
+  // Reuse complete HTTP creates only. Cache-dependent continuation, warmup and
+  // named WS lanes need a different lifecycle/recovery contract.
+  if (body.previous_response_id != null || Object.hasOwn(body, "stream_id")
+    || Object.hasOwn(body, "generate") || body.background === true) return null;
+  const metadata = body.client_metadata;
+  const bodyThread = metadata.thread_id;
+  const headerThread = headers["thread-id"];
+  if (bodyThread !== undefined && !value(bodyThread)) return null;
+  if (headerThread !== undefined && !value(headerThread)) return null;
+  if (bodyThread !== undefined && headerThread !== undefined && bodyThread !== headerThread) return null;
+  const thread = bodyThread ?? headerThread;
+  const turn = metadata.turn_id;
+  const account = headers["chatgpt-account-id"];
+  const authorization = headers.authorization;
+  if (![thread, turn, account, authorization, body.model].every(value)) return null;
+  if (body.service_tier !== undefined && !value(body.service_tier)) return null;
+  const immutable = Object.entries(headers).filter(([name]) => !MUTABLE_HEADERS.has(name)).sort(([a], [b]) => a.localeCompare(b));
+  if (immutable.length > 128 || immutable.some(([, field]) => !value(field))
+    || immutable.reduce((bytes, [name, field]) => bytes + Buffer.byteLength(name) + Buffer.byteLength(field), 0) > 32 * 1024) return null;
+  const scope = digest([url, account, thread, turn]);
+  const lite = metadata.ws_request_header_x_openai_internal_codex_responses_lite;
+  if (lite !== undefined && lite !== "true" && lite !== "false") return null;
+  return { scope, key: digest([scope, authorization, body.model, body.service_tier ?? null, lite ?? null, immutable]) };
+}
+
+interface Entry { identity: CodexWsReuseIdentity; session: CodexWsSession; createdAt: number; idleAt: number; retired: boolean }
+interface PoolOptions { now?: () => number; maxSessions?: number; idleMs?: number; maxAgeMs?: number }
+
+/** Bounded retained sockets only. Busy/capacity misses keep the existing one-shot path. */
+export class CodexWsPool {
+  private readonly entries = new Map<string, Entry>();
+  private timer?: ReturnType<typeof setTimeout>;
+  private detachShutdown?: () => void;
+  private readonly hookKey = `codex-upstream-ws-pool-${++poolSequence}`;
+  private readonly now: () => number;
+  private readonly maxSessions: number;
+  private readonly idleMs: number;
+  private readonly maxAgeMs: number;
+  constructor(options: PoolOptions = {}) {
+    this.now = options.now ?? Date.now;
+    this.maxSessions = options.maxSessions ?? CODEX_WS_POOL_MAX_SESSIONS;
+    this.idleMs = options.idleMs ?? CODEX_WS_POOL_IDLE_MS;
+    this.maxAgeMs = options.maxAgeMs ?? CODEX_WS_POOL_MAX_AGE_MS;
+  }
+
+  acquire(identity: CodexWsReuseIdentity, url: string, headers: Record<string, string>): CodexWsSession | null {
+    this.sweep();
+    for (const entry of this.entries.values()) {
+      if (entry.identity.scope !== identity.scope || entry.identity.key === identity.key) continue;
+      entry.retired = true;
+      if (!entry.session.busy) this.remove(entry);
+    }
+    const existing = this.entries.get(identity.key);
+    if (existing) {
+      if (existing.retired || existing.session.busy) return null;
+      if (existing.session.reserve()) { this.arm(); return existing.session; }
+      this.remove(existing);
+    }
+    if (this.entries.size >= this.maxSessions) {
+      const oldest = [...this.entries.values()].filter(entry => !entry.session.busy).sort((a, b) => a.idleAt - b.idleAt)[0];
+      if (!oldest) return null;
+      this.remove(oldest);
+    }
+    const createdAt = this.now();
+    const session = new CodexWsSession(url, headers, true, () => this.changed(entry));
+    const entry: Entry = { identity, session, createdAt, idleAt: createdAt, retired: false };
+    session.reserve();
+    this.entries.set(identity.key, entry);
+    this.detachShutdown ??= registerOptionalShutdownHook(this.hookKey, () => this.dispose());
+    return session;
+  }
+
+  private changed(entry: Entry): void {
+    if (this.entries.get(entry.identity.key) !== entry) return;
+    if (entry.session.closed) this.entries.delete(entry.identity.key);
+    else if (!entry.session.busy) {
+      entry.idleAt = this.now();
+      if (entry.retired || entry.idleAt - entry.createdAt >= this.maxAgeMs) this.remove(entry);
+    }
+    this.arm();
+  }
+
+  private remove(entry: Entry): void {
+    if (this.entries.get(entry.identity.key) === entry) this.entries.delete(entry.identity.key);
+    entry.session.dispose(new Error("codex websocket retained session expired"));
+    this.arm();
+  }
+
+  sweep(): void {
+    const now = this.now();
+    for (const entry of this.entries.values()) {
+      if (!entry.session.busy && (entry.session.closed || entry.retired
+        || now - entry.idleAt >= this.idleMs || now - entry.createdAt >= this.maxAgeMs)) this.remove(entry);
+    }
+    this.arm();
+  }
+
+  private arm(): void {
+    clearTimeout(this.timer);
+    this.timer = undefined;
+    if (!this.entries.size) {
+      this.detachShutdown?.();
+      this.detachShutdown = undefined;
+      return;
+    }
+    let deadline = Infinity;
+    for (const entry of this.entries.values()) if (!entry.session.busy) {
+      deadline = Math.min(deadline, entry.idleAt + this.idleMs, entry.createdAt + this.maxAgeMs);
+    }
+    if (!Number.isFinite(deadline)) return;
+    this.timer = setTimeout(() => { this.timer = undefined; this.sweep(); }, Math.max(1, deadline - this.now()));
+    this.timer.unref?.();
+  }
+
+  dispose(): void {
+    clearTimeout(this.timer);
+    this.timer = undefined;
+    this.detachShutdown?.();
+    this.detachShutdown = undefined;
+    const entries = [...this.entries.values()];
+    this.entries.clear();
+    for (const entry of entries) entry.session.dispose(new DOMException("codex websocket pool shutdown", "AbortError"));
+  }
+
+  snapshot(): { size: number; active: number; timer: boolean } {
+    return { size: this.entries.size, active: [...this.entries.values()].filter(entry => entry.session.busy).length, timer: this.timer !== undefined };
+  }
+}
+
+export const codexWsPool = new CodexWsPool();

package/src/server/responses/codex-ws-request.ts

@@ -0,0 +1,87 @@
+import {
+  applyCodexRoutingHint,
+  CODEX_RESPONSES_LITE_HEADER,
+  CODEX_RESPONSES_LITE_METADATA_KEY,
+} from "../../codex/forward-transport-headers";
+
+export const CODEX_RESPONSES_HTTP_URL = "https://chatgpt.com/backend-api/codex/responses";
+export const CODEX_RESPONSES_WS_URL = "wss://chatgpt.com/backend-api/codex/responses";
+export const WS_BETA = "responses_websockets=2026-02-06";
+
+export interface PreparedCodexWsRequest {
+  /** Fully synthesized frame; the transport measures this exact text before dialing. */
+  frameText: string;
+  headers: Record<string, string>;
+  /** Original HTTP body/framing/options with only the canonical routing hint re-derived. */
+  httpInit: RequestInit;
+  canonical: boolean;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function applyLiteMetadata(body: Record<string, unknown>, headers: Headers): boolean {
+  const metadata = body.client_metadata;
+  // Native client metadata is a string map. Do not spread malformed input or
+  // turn boolean/number values into plausible but invented protocol strings.
+  if (metadata !== undefined && (!isRecord(metadata)
+    || Object.values(metadata).some(value => typeof value !== "string"))) return false;
+  const lite = headers.get(CODEX_RESPONSES_LITE_HEADER);
+  if (lite === "true" || lite === "false") {
+    body.client_metadata = { ...(metadata as Record<string, string> | undefined),
+      [CODEX_RESPONSES_LITE_METADATA_KEY]: lite };
+  }
+  for (const name of ["x-codex-turn-state", "x-codex-turn-metadata"]) {
+    const value = headers.get(name);
+    const current = body.client_metadata as Record<string, string> | undefined;
+    if (value !== null && !Object.hasOwn(current ?? {}, name)) {
+      body.client_metadata = { ...current, [name]: value };
+    }
+  }
+  return true;
+}
+
+/** Pure preparation; null keeps malformed requests on the existing HTTP fallback path. */
+export function prepareCodexHttpInit(url: string, init: RequestInit): RequestInit {
+  if (url !== CODEX_RESPONSES_HTTP_URL || typeof init.body !== "string") return init;
+  const headers = new Headers(init.headers);
+  let body: unknown;
+  try { body = JSON.parse(init.body); } catch { /* malformed body cannot authorize a hint */ }
+  applyCodexRoutingHint(headers, body);
+  return { ...init, headers };
+}
+
+/** Null refuses only WS conversion; canonical HTTP normalization is independently reusable. */
+export function prepareCodexWsRequest(url: string, init: RequestInit): PreparedCodexWsRequest | null {
+  if (typeof init.body !== "string") return null;
+  try {
+    const parsed: unknown = JSON.parse(init.body);
+    if (!isRecord(parsed)) return null;
+    const body = { ...parsed };
+    const canonical = url === CODEX_RESPONSES_HTTP_URL;
+    const httpHeaders = new Headers(init.headers);
+    if (canonical) {
+      if (!applyLiteMetadata(body, httpHeaders)) return null;
+      applyCodexRoutingHint(httpHeaders, body);
+    }
+    const httpInit = { ...init, headers: httpHeaders };
+    // WS is implicitly streaming; retain every other caller field except type.
+    delete body.stream;
+    const frameText = JSON.stringify({ ...body, type: "response.create" });
+    const headers: Record<string, string> = {};
+    httpHeaders.forEach((value, key) => {
+      if (key === "content-type" || key === "content-length" || key === "accept" || key === "accept-encoding") return;
+      headers[key] = value;
+    });
+    // Preserve the existing beta composition for both canonical and opted-in gateways.
+    headers["openai-beta"] = headers["openai-beta"]
+      ? headers["openai-beta"].includes("responses_websockets")
+        ? headers["openai-beta"]
+        : `${headers["openai-beta"]}, ${WS_BETA}`
+      : WS_BETA;
+    return { frameText, headers, httpInit, canonical };
+  } catch {
+    return null;
+  }
+}

package/src/server/responses/codex-ws-session.ts

@@ -0,0 +1,93 @@
+export const MAX_CODEX_WS_SESSION_EXCHANGES = 32;
+
+/** Owns one physical socket; request listeners belong to the exchange, not this object. */
+export class CodexWsSession {
+  readonly socket: WebSocket;
+  opened = false;
+  closed = false;
+  busy = false;
+  private owner?: (reason: Error) => void;
+  private readonly completedIds = new Set<string>();
+
+  constructor(url: string, headers: Record<string, string>, readonly retainable = false,
+    private readonly changed: () => void = () => {}) {
+    this.socket = new WebSocket(url, { headers } as unknown as string[]);
+    this.socket.addEventListener("open", this.onOpen);
+    this.socket.addEventListener("message", this.onIdleMessage);
+    this.socket.addEventListener("close", this.onClose);
+    this.socket.addEventListener("error", this.onIdleError);
+  }
+
+  get reused(): boolean { return this.completedIds.size > 0; }
+  hasCompleted(id: string): boolean { return this.completedIds.has(id); }
+
+  reserve(): boolean {
+    if (this.closed || this.busy || (this.opened && this.socket.readyState !== undefined && this.socket.readyState !== 1)) return false;
+    this.busy = true;
+    const socket = this.socket as WebSocket & { ref?: () => void };
+    try { socket.ref?.(); } catch { /* optional keepalive hint */ }
+    return true;
+  }
+
+  bindOwner(owner: (reason: Error) => void): () => void {
+    if (!this.busy || this.closed || this.owner) throw new Error("codex websocket lease is unavailable");
+    this.owner = owner;
+    return () => { if (this.owner === owner) this.owner = undefined; };
+  }
+
+  release(completedId: string | null): void {
+    this.owner = undefined;
+    if (this.closed) return;
+    if (!this.retainable || !completedId || !this.opened
+      || (this.socket.readyState !== undefined && this.socket.readyState !== 1)) {
+      this.dispose();
+      return;
+    }
+    this.completedIds.add(completedId);
+    if (this.completedIds.size >= MAX_CODEX_WS_SESSION_EXCHANGES) {
+      this.dispose();
+      return;
+    }
+    this.busy = false;
+    const socket = this.socket as WebSocket & { unref?: () => void };
+    try { socket.unref?.(); } catch { /* optional hint; shutdown/expiry still owns cleanup */ }
+    this.changed();
+  }
+
+  dispose(reason = new Error("codex websocket session disposed")): void {
+    if (this.closed) return;
+    this.closed = true;
+    const owner = this.owner;
+    this.owner = undefined;
+    this.detach();
+    try { owner?.(reason); } finally {
+      this.busy = false;
+      this.completedIds.clear();
+      try { this.socket.close(); } catch { /* already closing */ }
+      if (this.retainable) {
+        try { (this.socket as WebSocket & { terminate?: () => void }).terminate?.(); } catch { /* already closed */ }
+      }
+      this.changed();
+    }
+  }
+
+  private onOpen = (): void => { this.opened = true; };
+  private onIdleMessage = (): void => {
+    if (!this.busy) this.dispose(new Error("codex websocket received unsolicited idle data"));
+  };
+  private onIdleError = (): void => { if (!this.busy) this.dispose(); };
+  private onClose = (): void => {
+    this.closed = true;
+    this.busy = false;
+    this.completedIds.clear();
+    this.detach();
+    this.changed();
+    // The active exchange's close listener retains pre-send fallback semantics.
+  };
+  private detach(): void {
+    this.socket.removeEventListener("open", this.onOpen);
+    this.socket.removeEventListener("message", this.onIdleMessage);
+    this.socket.removeEventListener("close", this.onClose);
+    this.socket.removeEventListener("error", this.onIdleError);
+  }
+}

package/src/server/responses/codex-ws-wire.ts

@@ -0,0 +1,144 @@
+import { MAX_CLIENT_SSE_FRAME_BYTES } from "../sse-frame-buffer";
+// If the 101 never arrives (network black hole), give SSE a chance well before
+// the caller's connect timeout (default 200s) would fire.
+export const UPGRADE_DEADLINE_MS = 10_000;
+export const CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS = 30_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;
+// The backend drops any inbound message of 16 MiB or more: it closes the socket
+// (1009) without a Responses terminal event, which reaches clients as a bare
+// 502 upstream_server_error. Measured against the live endpoint 2026-08-23:
+// 16,777,000 B completed, 16,777,300 B closed in ~1s, every time. The same
+// request body succeeds over HTTP SSE, so the ceiling belongs to this transport
+// alone (see #2426). A full-replay thread reaches it with ~11 pasted
+// screenshots, and then never recovers, because each retry resends the frame.
+export const MAX_CODEX_WS_CREATE_FRAME_BYTES = 16 * 1024 * 1024;
+// Bun frames the payload it is handed, so the send-side budget is the JSON text
+// itself, and nothing is appended between the check and the send. The margin is
+// a conservative cushion, not a computed requirement: it covers RFC 6455 frame
+// overhead in case the backend counts it (14 bytes at this payload size — an
+// 8-byte extended length plus a 4-byte client mask, leaving ~65.5 KiB spare),
+// and it leaves room for a future caller that appends to the frame.
+const CODEX_WS_CREATE_FRAME_MARGIN_BYTES = 64 * 1024;
+export const CODEX_WS_CREATE_FRAME_LIMIT_BYTES =
+  MAX_CODEX_WS_CREATE_FRAME_BYTES - CODEX_WS_CREATE_FRAME_MARGIN_BYTES;
+/** Close code the backend uses for an oversized message (RFC 6455 "message too big"). */
+const WS_CLOSE_MESSAGE_TOO_BIG = 1009;
+
+const codexWsUpstreamResponses = new WeakSet<Response>();
+const quotaObservedResponses = new WeakSet<Response>();
+
+/** Quota arrived directly at its captured account; do not replay old HTTP prelude headers. */
+export function isCodexWsQuotaObservedResponse(response: Response): boolean {
+  return quotaObservedResponses.has(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 markCodexWsResponse(response: Response, observed: boolean): void {
+  codexWsUpstreamResponses.add(response);
+  if (observed) quotaObservedResponses.add(response);
+}
+
+const CLOSED_BEFORE_TERMINAL = "codex websocket closed before a Responses terminal event";
+
+export type ResponsesWsRelayEvent = {
+  type: string;
+  text: string;
+  payload: Record<string, unknown>;
+};
+
+/**
+ * Responses WebSocket uses `response.done` as its terminal event, while the
+ * SSE Responses surface uses status-specific terminal events. Normalize the
+ * WS-only discriminator before relaying so the existing SSE consumers can
+ * settle the turn and the socket close cannot be mistaken for a drop. Unknown
+ * or missing status values fail closed instead of being reported as success.
+ */
+export function normalizeResponsesWsRelayEvent(text: string): ResponsesWsRelayEvent | null {
+  let payload: unknown;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  const record = payload as Record<string, unknown>;
+  if (typeof record.type !== "string") return null;
+  // A native error may be pretty-printed JSON. SSE prefixes one data line;
+  // embedded physical newlines would otherwise truncate the JSON for readers.
+  if (record.type !== "response.done") return {
+    type: record.type, text: /[\r\n]/.test(text) ? JSON.stringify(record) : text, payload: record,
+  };
+
+  const response = record.response;
+  const status = response && typeof response === "object" && !Array.isArray(response)
+    ? (response as Record<string, unknown>).status
+    : undefined;
+  const type = status === "completed"
+    ? "response.completed"
+    : status === "failed"
+      ? "response.failed"
+      : status === "incomplete" || status === "cancelled"
+        ? "response.incomplete"
+        : "response.failed";
+  const normalizedRecord: Record<string, unknown> = { ...record, type };
+  if (type === "response.failed" && status !== "failed") {
+    normalizedRecord.response = response && typeof response === "object" && !Array.isArray(response)
+      ? { ...(response as Record<string, unknown>), status: "failed" }
+      : { status: "failed" };
+  }
+  return { type, text: JSON.stringify(normalizedRecord), payload: normalizedRecord };
+}
+
+/**
+ * The close code is the only thing that separates "the backend refused this
+ * payload" from "the network dropped", and both used to reach the caller as the
+ * same bare 502. Naming the oversized case here puts that distinction in the
+ * message the client receives.
+ *
+ * It does NOT reach the request log as a typed code. The eager relay turns any
+ * stream error into a generic `upstream_reset` synthetic terminal
+ * (`relay.ts`, `relay-eager.ts`) without feeding that frame back through the
+ * inspector, so `/api/logs` keeps neither this message nor a specific code —
+ * only `streamAborted`. Machine-readable typing would mean changing the error
+ * taxonomy, which is deliberately out of scope for this transport fix.
+ */
+export function closedBeforeTerminalMessage(event: unknown): string {
+  const detail = event as { code?: unknown; reason?: unknown } | null | undefined;
+  const code = typeof detail?.code === "number" ? detail.code : null;
+  const reason = typeof detail?.reason === "string" ? detail.reason.trim() : "";
+  if (code === null) return CLOSED_BEFORE_TERMINAL;
+  const suffix = reason ? ` ${code} ${reason}` : ` ${code}`;
+  if (code === WS_CLOSE_MESSAGE_TOO_BIG) {
+    return `codex websocket rejected the request frame as too large (close${suffix});`
+      + ` requests at or above ${MAX_CODEX_WS_CREATE_FRAME_BYTES} bytes must use the HTTP SSE transport`;
+  }
+  return `${CLOSED_BEFORE_TERMINAL} (close${suffix})`;
+}
+
+/**
+ * True when the `response.create` frame is at or above the backend's inbound
+ * message ceiling, so this turn must take the HTTP SSE path instead.
+ *
+ * Sizing a 16 MiB string should not cost a 16 MiB copy. UTF-8 never encodes
+ * below one byte per UTF-16 code unit and never above three, so both tails are
+ * settled from the string length alone; only the narrow band between them pays
+ * for a real byte count, and `Buffer.byteLength` measures without allocating.
+ */
+export function codexWsCreateFrameExceedsLimit(
+  frameText: string,
+  limitBytes: number = CODEX_WS_CREATE_FRAME_LIMIT_BYTES,
+): boolean {
+  if (frameText.length >= limitBytes) return true;
+  if (frameText.length * 3 < limitBytes) return false;
+  return Buffer.byteLength(frameText, "utf8") >= limitBytes;
+}