UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

874 lines (850 loc) • 43.6 kB
import { completeIncrementalFrame, recordIncrementalDispatch, type IncrementalPlan } from "./codex-ws-incremental"; import { NativeSteeringError } from "./native-steering"; import { NativeContinuationRefusalError } from "./native-continuation-refusal"; import { mergeSteeringContinuation } from "./native-steering-settings"; import { markNativeControlResponse } from "./native-response-control"; import type { NativeResponseControl } from "./native-response-control"; import { MAX_CLIENT_SSE_FRAME_BYTES } from "../sse-frame-buffer"; import { isSafeResponseHeader, type ResponseMetadataContext } from "../safe-response-headers"; import { CodexWsMetadata, type CodexWsQuotaObserver } from "./codex-ws-metadata"; import { CODEX_RESPONSES_HTTP_URL, type PreparedCodexWsRequest } from "./codex-ws-request"; import { CodexWsCorrelation } from "./codex-ws-correlation"; import type { CodexWsSession } from "./codex-ws-session"; import { UPGRADE_DEADLINE_MS, CODEX_WS_LIVENESS_PING_INTERVAL_MS, CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS, CODEX_WS_COMMITTED_SILENT_INTERVALS, MAX_CODEX_WS_FRAME_BYTES, MAX_CODEX_WS_QUEUE_BYTES, markCodexWsResponse, markCodexWsPreludeProjection, normalizeResponsesWsRelayEvent, closedBeforeTerminalMessage, codexWsCreateFrameExceedsLimit, codexWsFailureDetail, codexWsPreResponseFailure, markCodexWsStage, codexWsOcxVersion, markCodexWsSocketDeath, codexWsWrapperStatus, isCodexWsTerminalEvent, type CodexWsFailureStage, type CodexWsStageRecord, type CodexWsTerminalEvent, codexWsPreOutputRefusalStatus, isEmptyCodexWsLifecycleEvent, codexWsFrameResponseIds, markCodexWsPreOutputRefusal, responsesFrameIsReplayUnsafe, type CodexWsPreOutputRefusalHold } from "./codex-ws-wire"; interface ExchangeOptions { incrementalPlan?: IncrementalPlan; nativeControl?: NativeResponseControl; beforeContinuation?: () => Promise<void>; session: CodexWsSession; url: string; init: RequestInit; prepared: PreparedCodexWsRequest; sseFallback: typeof globalThis.fetch; onQuota?: CodexWsQuotaObserver; beforeDispatch?: (headers: Headers) => void; /** * Physical-send admission, handed the frame text that actually leaves on this send: the delta * frame for an incremental send, the full create for its cache-miss recovery (#8453 replay guard). */ onPhysicalDispatch?: (frameText: string) => void; recoverPhysicalSend?: (send: () => Promise<void>) => Promise<boolean>; onContinuationDispatch?: (frame: { body: Record<string, unknown>; text: string }) => void; /** Bun version string the caller gated on; stamped onto the stage record. */ bunVersion?: string; /** * Opt-in (#6969): how long empty lifecycle frames may be held so an authoritative upstream * refusal that follows them, before any output, can settle as a replayable gateway status instead * of a committed 200. Absent or zero keeps the exchange exactly as it was. Ignored on native * control exchanges and on transports without the metadata channel. */ preOutputRefusalHold?: CodexWsPreOutputRefusalHold; /** Turn-state binding and known models for the metadata this exchange relays. */ metadataContext?: ResponseMetadataContext; } const HTTP_HEADER_TOKEN = /^[!#$%&'*+.^_`|~0-9a-z-]+$/i; function record(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value); } /** Rebuild only permitted metadata: upstream framing describes a different body. */ function rejectionHeaders(source: Record<string, unknown>, prelude: Headers, context: ResponseMetadataContext): Headers { const connectionHeaders = new Set<string>(); for (const [name, value] of Object.entries(source)) { if (name.toLowerCase() !== "connection" || typeof value !== "string") continue; for (const token of value.split(",")) { const lower = token.trim().toLowerCase(); if (HTTP_HEADER_TOKEN.test(lower)) connectionHeaders.add(lower); } } // Reuse the metadata owner's count/value/family budgets and window freshness // rules, without publishing quota twice. Pool bookkeeping consumes the HTTP // projection; plain-main publication belongs only to the WS observer. const projected = new CodexWsMetadata(undefined, context); try { for (const values of [Object.fromEntries(prelude), source]) { const headers = Object.fromEntries(Object.entries(values).filter(([name, value]) => { if (!HTTP_HEADER_TOKEN.test(name) || !isSafeResponseHeader(name) || connectionHeaders.has(name.toLowerCase())) return false; if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") return false; return !(typeof value === "number" && !Number.isFinite(value)) && !/[\r\n\0]/.test(String(value)); })); if (Object.keys(headers).length === 0) continue; const event = { type: "codex.response.metadata", headers }; // Bound the combined serialized seed and updates, even for replacements. projected.consume(event, Buffer.byteLength(JSON.stringify(event))); } const headers = projected.snapshot(); headers.set("content-type", "application/json"); headers.set("cache-control", "no-store"); return headers; } finally { projected.finish(); } } /** * Carry #3740's refused-create status back to the HTTP recovery path. Codex's * responses_websocket.rs accepts status/status_code and scalar header values; * unlike its native client, this relay converts only precommit 4xx. Returning a * post-send 5xx or fetch rejection could cause the outer retry wrapper to resend. * The one 5xx exception is the opt-in pre-output refusal below (#6969): a structured upstream * refusal with nothing relayed but empty lifecycle frames, which the caller may replay. */ function wrappedRejectionResponse(payload: Record<string, unknown>, prelude: Headers, context: ResponseMetadataContext): Response | null { if (payload.type !== "error" || payload.stream_id !== undefined) return null; // The native typed wrapper has one aliased field, not two competing statuses. if (Object.hasOwn(payload, "status_code") && Object.hasOwn(payload, "status")) return null; const status = Object.hasOwn(payload, "status_code") ? payload.status_code : payload.status; if (typeof status !== "number" || !Number.isInteger(status) || status < 400 || status > 499) return null; const error = payload.error; if (error != null && (!record(error) || [error.code, error.message].some(value => value != null && typeof value !== "string"))) return null; if (payload.headers != null && !record(payload.headers)) return null; const headers = rejectionHeaders(record(payload.headers) ? payload.headers : {}, prelude, context); return new Response(JSON.stringify({ error: error ?? { type: "upstream_error", message: "Upstream rejected the request" }, }), { status, headers }); } /** The client-facing error of a pre-output refusal projection, from the refusal's own error object. */ function refusalErrorBody(source: unknown): Record<string, string> { const error = record(source) ? source : {}; return { type: typeof error.type === "string" ? error.type : "server_error", ...(typeof error.code === "string" ? { code: error.code } : {}), message: typeof error.message === "string" ? error.message : "Upstream declined the request before any output", }; } /** The sole SSE exchange state machine for both one-shot and retained sockets. */ export function codexWsExchange(options: ExchangeOptions): Promise<Response> { const { session, url, init, prepared, sseFallback, onQuota, beforeDispatch, bunVersion, nativeControl, beforeContinuation, preOutputRefusalHold } = options; const metadataContext = options.metadataContext ?? {}; const { headers } = prepared; let frameText = prepared.frameText; let incrementalPlan = options.incrementalPlan; let recoveryAdmissionPending = false; const signal = init.signal ?? undefined; return new Promise<Response>((resolve, reject) => { const ws = session.socket; let opened = session.opened; let settledPreOpen = false; let sent = false; let received = false; let responseCommitted = false; let terminal = false; // #4191: the counters behind the failure classification. A user whose long // thread died here could not tell an unanswered socket from one that carried // only quota frames, because both arrived as the same one-line message. let upstreamFrames = 0; let controlFrames = 0; let relayedEvents = 0; let pings = 0; let pongs = 0; let sentAt: number | null = null; let firstFrameAt: number | null = null; let firstResponseAt: number | null = null; // Numeric close code for the durable stage record; the reason string stays // out of it on purpose (#4191 content-free contract). let closeCode: number | null = null; // #6740: which terminal frame the upstream itself sent, before any synthetic tail. let terminalEvent: CodexWsTerminalEvent | null = null; let terminalErrorStatus: number | null = null; let controller: ReadableStreamDefaultController<Uint8Array> | null = null; const encoder = new TextEncoder(); const metadata = url === CODEX_RESPONSES_HTTP_URL ? new CodexWsMetadata(onQuota, metadataContext) : null; const correlation = session.retainable ? new CodexWsCorrelation(session.reused, id => session.hasCompleted(id)) : null; let detachOwner = () => {}; let detachSteering = () => {}; let continuationBase: Record<string, unknown> | undefined; // Liveness while waiting for the first response event (metadata path only): the // silence timer is re-armed by every inbound frame or pong; the pinger runs on a fixed // interval so a peer that answers pings can never trip the silence bound while alive. // After the commit, each ping tick checks whether any frame or pong arrived since the last. let silenceTimer: ReturnType<typeof setTimeout> | undefined; let pingTimer: ReturnType<typeof setTimeout> | undefined; let inboundAtLastTick = 0; let silentIntervals = 0; // The resolved 200, retained so a later body failure can replace its // success-shaped stage record with the failure-shaped one (#4191). let committedResponse: Response | null = null; // #6969: the pre-output refusal hold. While it is open, empty lifecycle frames are queued on the // not-yet-exposed stream without resolving it. Every settle other than an eligible refusal // commits first (deferredCommit), so the outcome is exactly what the exchange produced before. const holdEnabled = (preOutputRefusalHold?.maxMs ?? 0) > 0 && metadata !== null && !nativeControl; // Drops for good on any identity the exchange cannot tie to one response: a stream id, two // different ids in one frame, or an id that differs from the first one seen. Independent of // socket reuse, so a cold one-shot socket is held to the same rule as a pooled one. let refusalEligible = holdEnabled; let refusalResponseId: string | null = null; let heldHeaders: Headers | null = null; let deferredCommit = false; let holdTimer: ReturnType<typeof setTimeout> | undefined; const stream = new ReadableStream<Uint8Array>({ start(c) { controller = c; }, cancel() { if (terminal) return; terminal = true; cleanup(); session.dispose(); }, }, new ByteLengthQueuingStrategy({ highWaterMark: MAX_CODEX_WS_QUEUE_BYTES })); const cleanup = () => { clearTimeout(upgradeTimer); clearTimeout(silenceTimer); clearTimeout(pingTimer); clearTimeout(holdTimer); signal?.removeEventListener("abort", onAbort); metadata?.finish(); correlation?.finish(); detachOwner(); detachSteering(); ws.removeEventListener("open", onOpen); ws.removeEventListener("message", onMessage); ws.removeEventListener("close", onClose); ws.removeEventListener("error", onError); ws.removeEventListener("pong", onPong); }; /** * Snapshot the stage for a failure message. Measuring the frame is deferred * to here so the happy path never pays for it: a full-replay thread's frame * runs to megabytes, and this is the only place its size is worth knowing. */ const failureStage = (): CodexWsFailureStage => ({ requestBytes: Buffer.byteLength(frameText, "utf8"), sent, upstreamFrames, controlFrames, relayedEvents, firstFrameMs: sentAt !== null && firstFrameAt !== null ? Math.max(0, firstFrameAt - sentAt) : null, firstResponseMs: sentAt !== null && firstResponseAt !== null ? Math.max(0, firstResponseAt - sentAt) : null, elapsedMs: sentAt !== null ? Math.max(0, Date.now() - sentAt) : null, pings, pongs, }); /** * The durable twin of failureStage (#4191). `requestBytes` is an explicit * parameter so the committed-success path can pass null instead of paying * the UTF-8 walk of a megabyte replay frame; failure callers pass * `failureStage().requestBytes`, which measures exactly once. */ const stageRecord = (requestBytes: number | null): CodexWsStageRecord => ({ requestBytes, sent, upstreamFrames, controlFrames, relayedEvents, firstFrameMs: sentAt !== null && firstFrameAt !== null ? Math.max(0, firstFrameAt - sentAt) : null, firstResponseMs: sentAt !== null && firstResponseAt !== null ? Math.max(0, firstResponseAt - sentAt) : null, elapsedMs: sentAt !== null ? Math.max(0, Date.now() - sentAt) : null, pings, pongs, closeCode, reused: session.reused, ocxVersion: codexWsOcxVersion(), bunVersion: bunVersion ?? "unknown", terminalEvent, terminalErrorStatus, }); const commitResponse = () => { if (responseCommitted) return; responseCommitted = true; deferredCommit = false; clearTimeout(holdTimer); clearTimeout(silenceTimer); clearTimeout(pingTimer); // A held preamble froze the prelude headers at the first Responses event, which is the moment // they were frozen before the hold existed. const responseHeaders = heldHeaders ? new Headers(heldHeaders) : metadata?.snapshot() ?? new Headers(); responseHeaders.set("content-type", "text/event-stream; charset=utf-8"); const response = new Response(stream, { status: 200, headers: responseHeaders }); metadata?.commit(); markCodexWsResponse(response, Boolean(metadata && onQuota)); if (nativeControl) markNativeControlResponse(response); markCodexWsStage(response, stageRecord(null)); committedResponse = response; resolve(response); startCommittedLiveness(); }; /** * Open the hold at the first empty lifecycle frame: freeze the prelude and bound the wait by * both the hold's own maximum and its absolute end. False when no time is left, so the frame * commits exactly as it would without the hold. */ const beginHold = (): boolean => { if (heldHeaders) return true; if (!metadata || !preOutputRefusalHold) return false; const waitMs = Math.min(preOutputRefusalHold.maxMs, preOutputRefusalHold.until - Date.now()); if (waitMs <= 0) return false; heldHeaders = metadata.snapshot(); metadata.commit(); holdTimer = setTimeout(() => { if (!terminal && !responseCommitted) commitResponse(); }, waitMs); return true; }; const noteRefusalIdentity = (payload: Record<string, unknown>) => { const ids = codexWsFrameResponseIds(payload); if (payload.stream_id !== undefined || ids === null || ids.length > 1) { refusalEligible = false; return; } const id = ids[0]; if (id === undefined) return; if (refusalResponseId === null) refusalResponseId = id; else if (id !== refusalResponseId) refusalEligible = false; }; /** * Settle an authoritative pre-output refusal (#6969) as the gateway status the upstream stated, * without the non-replayable marker: nothing but empty lifecycle frames was relayed, and the * upstream ended that response itself. The caller's transient ladder and pool move may send the * turn again; if neither does, the registered restore hands the client the original stream, * which is already complete on `stream`. */ const resolveRefusal = (status: number, payload: Record<string, unknown>, headers: Headers, prelude: Headers) => { responseCommitted = true; deferredCommit = false; clearTimeout(holdTimer); const stage = stageRecord(null); const source = payload.type === "error" ? payload.error : record(payload.response) ? payload.response.error : undefined; const projection = new Response(JSON.stringify({ error: refusalErrorBody(source) }), { status, headers }); markCodexWsPreludeProjection(projection); markCodexWsStage(projection, stage); const observed = Boolean(metadata && onQuota); markCodexWsPreOutputRefusal(projection, () => { const restoredHeaders = new Headers(prelude); restoredHeaders.set("content-type", "text/event-stream; charset=utf-8"); const restored = new Response(stream, { status: 200, headers: restoredHeaders }); markCodexWsResponse(restored, observed); // The same record object, so the attempt that adopted it keeps reading one stage. markCodexWsStage(restored, stage); return restored; }); resolve(projection); }; const failStream = (error: unknown, status: 502 | 504 = 502, { socketDied = false } = {}) => { if (terminal) return; terminal = true; // A held preamble or refusal was a commit deferred, not avoided: settle as the committed // body failure it would have been, never as a new pre-response gateway status. if (deferredCommit) commitResponse(); if (sent && !responseCommitted && metadata) { // Nothing has been promised to the client yet, so the honest answer is a gateway // status, not a 200 whose body then fails. The frame may already be executing // upstream: the response is marked non-replayable so no retry layer of this process // sends it again, and the client applies its own retry policy as it would on the direct // path. Same settle order as a refused create: snapshot, detach, close, dispose. const prelude = metadata.snapshot(); // Claim the commit slot so no later path can resolve a second, 200 Response. responseCommitted = true; cleanup(); try { controller?.close(); } catch { /* unused stream already closed */ } session.dispose(); const message = error instanceof Error ? error.message : String(error); const failureResponse = codexWsPreResponseFailure(status, message, prelude); const stage = failureStage(); markCodexWsStage(failureResponse, stageRecord(stage.requestBytes)); // #4191: a socket that died under the send is the one settle the dispatch may replace, // once, and only under the operator's `retryOnReset` grant. Native steering and injection // are left out: their channel may already have sent continuation frames on this socket, so // the create frame alone no longer describes the turn. if (socketDied && !nativeControl) markCodexWsSocketDeath(failureResponse, stage); markCodexWsPreludeProjection(failureResponse); resolve(failureResponse); return; } // A response is already flowing (or this transport has no metadata channel and // committed at send). Settle as a body failure, never a fetch rejection/5xx that the // pre-stream wrapper could resend. if (sent) commitResponse(); cleanup(); try { controller?.error(typeof error === "string" ? new Error(error) : error); } catch { /* stream already done */ } session.dispose(); // A body failure replaces the success-shaped record commitResponse wrote: // this settle is a failure, and the frame size is evidence again. if (committedResponse) { markCodexWsStage(committedResponse, stageRecord(Buffer.byteLength(frameText, "utf8"))); } }; /** (Re)start the silence bound; every inbound frame or pong is proof of life. */ const armSilence = () => { clearTimeout(silenceTimer); if (responseCommitted || terminal) return; silenceTimer = setTimeout( () => failStream(`codex websocket response prelude timed out${codexWsFailureDetail(failureStage())}`, 504), CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS, ); }; const pingable = () => typeof (ws as WebSocket & { ping?: unknown }).ping === "function"; /** False when ping() threw. It may also close the socket and settle the exchange. */ const sendPing = (): boolean => { if (!pingable()) return false; try { (ws as WebSocket & { ping: (data?: string) => void }).ping(); } catch { return false; } pings += 1; return true; }; /** Ping on a fixed interval for the life of the exchange; a socket without ping() is never pinged. */ const schedulePing = () => { if (!pingable() || terminal) return; pingTimer = setTimeout(() => { if (terminal) return; if (responseCommitted && pongs > 0) { const inbound = upstreamFrames + pongs; silentIntervals = inbound === inboundAtLastTick ? silentIntervals + 1 : 0; inboundAtLastTick = inbound; if (silentIntervals >= CODEX_WS_COMMITTED_SILENT_INTERVALS) { failStream(`codex websocket stopped answering after the response started${codexWsFailureDetail(failureStage())}`); return; } } sendPing(); if (!terminal) schedulePing(); }, CODEX_WS_LIVENESS_PING_INTERVAL_MS); }; /** Only a peer that has ponged is judged by its silence, so probe again if none has yet. */ const startCommittedLiveness = () => { if (!metadata || terminal || !pingable()) return; inboundAtLastTick = upstreamFrames + pongs; silentIntervals = 0; if (pongs === 0) sendPing(); if (!terminal) schedulePing(); }; const onPong = () => { if (terminal) return; pongs += 1; if (!responseCommitted) armSilence(); }; const upgradeTimer = setTimeout(() => { if (opened || settledPreOpen) return; settledPreOpen = true; cleanup(); session.dispose(); resolve(sseFallback(url, init)); }, UPGRADE_DEADLINE_MS); const cancelExchange = (reason: unknown) => { if (terminal || settledPreOpen) return; if (!sent) { settledPreOpen = true; terminal = true; cleanup(); session.dispose(); reject(reason); return; } if (!responseCommitted && metadata && !deferredCommit) { // Sent, unacknowledged. The proxy's own connect deadline is an origin-silence // verdict and settles like one; a caller abort is the caller's decision, so the // exchange rejects with that reason and disposing the socket cancels the turn. // Both arrive on the same composite signal (fetchWithHeaderTimeout joins the // caller's controller with its own), so the reason is the only discriminator: the // deadline aborts with a TimeoutError DOMException, and every caller abort in this // process (upstream.abort() in core.ts) carries the default AbortError. A future // proxy-side deadline that aborts with TimeoutError would still be honestly a 504. if ((reason as { name?: unknown } | null)?.name === "TimeoutError") { failStream(`codex websocket response did not start before the connect deadline${codexWsFailureDetail(failureStage())}`, 504); return; } terminal = true; cleanup(); session.dispose(); reject(reason); return; } failStream(reason); }; const onAbort = () => cancelExchange(signal?.reason ?? new DOMException("The operation was aborted.", "AbortError")); signal?.addEventListener("abort", onAbort, { once: true }); const onOpen = () => { if (settledPreOpen) return; clearTimeout(upgradeTimer); opened = true; try { beforeDispatch?.(new Headers(headers)); } catch (error) { // Settle and detach before close: a synchronous close event must not resend over SSE. settledPreOpen = true; terminal = true; cleanup(); ws.removeEventListener("open", onOpen); ws.removeEventListener("message", onMessage); ws.removeEventListener("close", onClose); ws.removeEventListener("error", onError); ws.removeEventListener("pong", onPong); session.dispose(); reject(error); return; } if (terminal || settledPreOpen || signal?.aborted) return; // New sockets have just validated their upgrade; retained sockets carry the // same connection signal into a fresh exchange, never its predecessor's frames. metadata?.seed(session.upgradeHeaders()); sent = true; try { if (nativeControl) { // Parsed once: the base body is immutable for this exchange, and a // full-replay frame runs to megabytes. It seeds continuationBase on // the first create frame. let base: Record<string, unknown> | undefined; detachSteering = nativeControl.attach(frame => { // Build, serialize and bound-check the reconstructed frame synchronously in the // channel callback: a typed refusal must reach the channel's synchronous rollback // (continuation slot released, journal unwritten) rather than the asynchronous // failStream path, so a corrected continuation can still retry on this channel. const prepare = () => { let outgoing = frame; if (frame.type === "response.create") { // Generation overrides have passed route policy; identity/tools remain pinned. // Keep the last explicit wire settings for later explicit and automatic successors. base ??= JSON.parse(frameText) as Record<string, unknown>; continuationBase ??= base; outgoing = nativeControl.kind === "steering" ? mergeSteeringContinuation(continuationBase, frame) : { ...continuationBase, input: frame.input, previous_response_id: frame.previous_response_id }; } const text = JSON.stringify(outgoing); nativeControl.assertOutboundFrame?.(text); if (codexWsCreateFrameExceedsLimit(text)) { throw new Error("Native steering frame exceeds the transport byte limit"); } return { outgoing, text }; }; const prepared = prepare(); const sendControl = () => { if (terminal || signal?.aborted || session.closed || ws.readyState !== WebSocket.OPEN) { throw new Error("Native steering connection is no longer available"); } beforeDispatch?.(new Headers(headers)); if (frame.type === "response.create") { // The exact serialized successor and its body, so admission can price the // reconstructed input and the successor's own output ceiling — never the // opening request's stale estimate. options.onContinuationDispatch?.({ body: prepared.outgoing, text: prepared.text }); continuationBase = prepared.outgoing; } try { ws.send(prepared.text); } catch { // A send failure has unknown delivery. Never replay or fall back. failStream("Native steering send failed; delivery is unknown"); throw new Error("Native steering send failed; delivery is unknown"); } }; if (frame.type === "response.create") { // Explicit tool-result continuations are physical request starts; // they keep provider pacing and revalidate auth AFTER the wait. // A typed pre-send refusal (e.g. the configured upstream body limit) is a // known non-delivery and keeps its own message; every other failure keeps // the unknown-delivery wording. // Keep known refusals on this stream even when no pacing hook is installed. void Promise.resolve().then(beforeContinuation).then(sendControl).catch(error => failStream( error instanceof NativeSteeringError || error instanceof NativeContinuationRefusalError ? error : new Error("Native steering continuation could not be dispatched; do not automatically replay queued input"), )); } else sendControl(); }, error => failStream(error)); } } catch (error) { // An attach failure is an ownership conflict, not a failed send: no frame // left the process, but the channel can never bind, so resolving the HTTP // fallback here would silently degrade a multi-agent turn into an ordinary // one. Fail the turn visibly instead. failStream(error); return; } try { options.onPhysicalDispatch?.(frameText); } catch (error) { // Admission refused before the frame left. This is a pre-open rejection, // not a transport failure and not an authorization to replay over SSE. settledPreOpen = true; sent = false; terminal = true; cleanup(); session.dispose(); reject(error); return; } try { ws.send(frameText); if (incrementalPlan) recordIncrementalDispatch(incrementalPlan); sentAt = Date.now(); } catch { if (received || responseCommitted) { if (terminal) session.dispose(); failStream("codex websocket send failed after response activity"); return; } // 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; sent = false; cleanup(); session.dispose(); resolve(sseFallback(url, init)); return; } if (!metadata) commitResponse(); else if (!responseCommitted && !terminal) { armSilence(); // Probe now, not one interval in: the path can die seconds after the send, before a // held commit, and the committed check needs a pong from before that. sendPing(); if (!terminal) schedulePing(); } }; const onMessage = (event: MessageEvent) => { if (!controller || terminal) return; if (recoveryAdmissionPending) { failStream("codex websocket received data during cache-miss recovery admission"); return; } received = true; if (!responseCommitted) armSilence(); upstreamFrames += 1; if (firstFrameAt === null) firstFrameAt = Date.now(); 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 rawEncodedText = encoder.encode(text); if (rawEncodedText.byteLength > MAX_CODEX_WS_FRAME_BYTES) { failStream("codex websocket frame exceeds the response size limit"); return; } let replayUnsafe = false; const normalized = normalizeResponsesWsRelayEvent(text, (refusalEligible || incrementalPlan?.delta) && sent && !responseCommitted ? payload => { replayUnsafe = responsesFrameIsReplayUnsafe(payload); } : undefined); if (!normalized) { if (replayUnsafe) commitResponse(); return; } const { type } = normalized; let relayText = normalized.text; let controlFrame = false; if (metadata) { try { const sanitized = metadata.consume(normalized.payload, rawEncodedText.byteLength); if (sanitized !== null) { relayText = sanitized; controlFrame = true; controlFrames += 1; } } catch (error) { failStream(error); return; } } const encodedText = relayText === text ? rawEncodedText : encoder.encode(relayText); if (encodedText.byteLength > MAX_CODEX_WS_FRAME_BYTES) { failStream("codex websocket frame exceeds the response size limit"); return; } if (!controlFrame && !type.startsWith("response.") && type !== "error") { if (replayUnsafe) commitResponse(); return; } let steeringEnded = false; let refusalStatus: number | undefined; let refusalHeaders: Headers | undefined; let refusalPrelude: Headers | undefined; if (controlFrame) { if (replayUnsafe) commitResponse(); } else { firstResponseAt ??= Date.now(); try { if (nativeControl) steeringEnded = nativeControl.observe(normalized.payload); else correlation?.accept(normalized.payload); } catch (error) { failStream(error); return; } if (replayUnsafe) commitResponse(); // An authoritative refusal before any response activity means the synthesized ID was // not accepted. The retained full create belongs to this exchange's admitted caller. // Never replay caller-owned IDs, committed output, foreign identities or unknown sends. const cacheMissStatus = codexWsWrapperStatus(normalized.payload); if (incrementalPlan?.delta && sent && !responseCommitted && !deferredCommit && relayedEvents === 0 && type === "error" && normalized.payload.stream_id === undefined && normalized.payload.response_id === undefined && normalized.payload.response === undefined && record(normalized.payload.error) && normalized.payload.error.code === "previous_response_not_found" && ((!Object.hasOwn(normalized.payload, "status") && !Object.hasOwn(normalized.payload, "status_code")) || (cacheMissStatus !== undefined && cacheMissStatus >= 400 && cacheMissStatus < 500))) { frameText = incrementalPlan.fullFrameText; incrementalPlan = { ...incrementalPlan, frameText, delta: false, sentBytes: incrementalPlan.fullBytes }; if (signal?.aborted) { onAbort(); return; } recoveryAdmissionPending = true; void (async () => { await beforeContinuation?.(); if (terminal || responseCommitted) return; if (signal?.aborted) { onAbort(); return; } const send = async () => { if (codexWsCreateFrameExceedsLimit(frameText)) { terminal = true; cleanup(); session.dispose(); try { controller!.close(); } catch { /* unused stream already closed */ } // Await the physical HTTP admission before committing its result. resolve(await sseFallback(url, init)); return; } beforeDispatch?.(new Headers(headers)); if (signal?.aborted) { onAbort(); return; } // The recovery is the full create, so that is the frame the replay guard records. options.onPhysicalDispatch?.(frameText); if (terminal || signal?.aborted) return; recoveryAdmissionPending = false; ws.send(frameText); recordIncrementalDispatch(incrementalPlan!); sentAt = Date.now(); }; const allowed = options.recoverPhysicalSend ? await options.recoverPhysicalSend(send) : (await send(), true); if (!allowed) { terminal = true; cleanup(); session.dispose(); try { controller.close(); } catch { /* unused stream already closed */ } const rejection = wrappedRejectionResponse({ type: "error", status: cacheMissStatus ?? 400, error: normalized.payload.error, headers: normalized.payload.headers }, metadata?.snapshot() ?? new Headers(), metadataContext); if (!rejection) throw new Error("Invalid cache-miss refusal"); markCodexWsPreludeProjection(rejection); resolve(rejection); } })().catch(error => { if (terminal && !responseCommitted) reject(error); else failStream(error); }); return; } const holdOpen = refusalEligible && sent && !responseCommitted; if (holdOpen) noteRefusalIdentity(normalized.payload); // Correlation must run first: a reused socket's foreign-stream error settles as a // non-replayable 502 above, never as the refused-create 4xx projection below, which // is the one status family that could authorize an account replay. // Only before anything was held: after an empty preamble a 4xx frame keeps today's // in-body delivery, so a held 429 can never become a quota rotation it was not before. if (metadata && sent && !responseCommitted && !deferredCommit && type === "error") { let rejection: Response | null; try { rejection = wrappedRejectionResponse(normalized.payload, metadata.snapshot(), metadataContext); } catch (error) { failStream(error); return; } if (rejection) { terminal = true; cleanup(); try { controller.close(); } catch { /* unused stream already closed */ } session.dispose(); markCodexWsPreludeProjection(rejection); resolve(rejection); return; } } let holdFrame = false; if (holdOpen && refusalEligible) { refusalStatus = codexWsPreOutputRefusalStatus(normalized.payload); if (refusalStatus !== undefined) { // Built before anything settles: a refusal whose metadata cannot be projected within the // header bounds is delivered the way it was before, in the committed body. try { refusalPrelude = heldHeaders ?? metadata?.snapshot() ?? new Headers(); const declared = normalized.payload.headers; refusalHeaders = rejectionHeaders(record(declared) ? declared : {}, refusalPrelude, metadataContext); } catch { refusalStatus = undefined; } } holdFrame = refusalStatus === undefined && isEmptyCodexWsLifecycleEvent(normalized.payload) && beginHold(); } if (refusalStatus === undefined && !holdFrame) commitResponse(); else deferredCommit = true; // Record the terminal the upstream sent as soon as it is accepted, before the relay-size and // queue checks below: a body failure that follows is still an exchange that received it. if (!nativeControl && isCodexWsTerminalEvent(type)) { terminalEvent = type; terminalErrorStatus = type === "error" ? (codexWsWrapperStatus(normalized.payload) ?? null) : null; } } const prefix = encoder.encode(`event: ${type}\ndata: `); const suffix = encoder.encode("\n\n"); const frameBytes = prefix.byteLength + encodedText.byteLength + suffix.byteLength; 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); try { controller.enqueue(sseFrame); } catch { failStream("codex websocket response stream closed while enqueueing"); return; } if (!controlFrame) relayedEvents += 1; if (nativeControl ? steeringEnded : (type === "response.completed" || type === "response.failed" || type === "response.incomplete" || type === "error")) { const completedId = correlation?.completed(normalized.payload) ?? null; terminal = true; cleanup(); try { controller.close(); } catch { /* already closed */ } // Refresh the success record with the final counters: the commit-time // snapshot predates every relayed event, and the record is more useful // when it says what the exchange actually delivered. Still no byte // count — the happy path never pays it. if (committedResponse) { markCodexWsStage(committedResponse, stageRecord(null)); } if (completedId && incrementalPlan && type === "response.completed") { completeIncrementalFrame(incrementalPlan, (normalized.payload as { response?: unknown }).response); } session.release(completedId); if (refusalStatus !== undefined && refusalHeaders && refusalPrelude && !responseCommitted) { resolveRefusal(refusalStatus, normalized.payload, refusalHeaders, refusalPrelude); } } }; const onClose = (event: unknown) => { cleanup(); const code = (event as { code?: unknown } | null)?.code; if (typeof code === "number") closeCode = code; if (!opened) { if (settledPreOpen) return; settledPreOpen = true; // 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 (sent && !terminal) { failStream(closedBeforeTerminalMessage(event, failureStage()), 502, { socketDied: true }); } }; const onError = () => { if (terminal || settledPreOpen) return; if (!opened && !sent) { settledPreOpen = true; terminal = true; cleanup(); session.dispose(); resolve(sseFallback(url, init)); } else { const message = `codex websocket transport error${codexWsFailureDetail(failureStage())}`; failStream(message, 502, { socketDied: true }); } }; detachOwner = session.bindOwner(reason => cancelExchange(reason)); ws.addEventListener("open", onOpen); ws.addEventListener("message", onMessage); ws.addEventListener("close", onClose); ws.addEventListener("error", onError); ws.addEventListener("pong", onPong); if (signal?.aborted) onAbort(); else if (session.opened) onOpen(); }); }