@iislee/opencodex 2.31.0 → 2.35.0

package/src/server/responses/empty-completion-guard.ts

@@ -35,6 +35,41 @@ export function emptyCompletionRetryEnabled(
 /** Surfaced when the single retry was also empty or failed upstream. */
 export const EMPTY_COMPLETION_RETRY_FAILED_CODE = "empty_completion_retry_failed";
 
+/**
+ * Observe an event stream for the empty-completion shape WITHOUT changing it (#2472).
+ *
+ * The guard above is opt-in, so with the default configuration a turn that completes with no
+ * output text and no tool call passes through untouched and the client records a silent
+ * success. That is the reported symptom: an empty result nobody can explain, with no trace
+ * that the proxy saw anything unusual.
+ *
+ * This is deliberately a passthrough observer, not a second guard. Retrying by default would
+ * re-send a turn that may have already had billable side effects; the honest default is to
+ * leave the stream alone and make the occurrence visible, so a user can correlate it and
+ * decide whether to enable the retry.
+ */
+export async function* observeEmptyCompletion(
+  events: AsyncIterable<AdapterEvent>,
+  onEmptyTurn: () => void,
+): AsyncGenerator<AdapterEvent> {
+  let sawContent = false;
+  let sawTerminal = false;
+  for await (const event of events) {
+    // Reasoning is deliberately NOT content, matching the guard: a reasoning-only stream that
+    // ends with nothing is the canonical shape of this failure.
+    if (isContentEvent(event)) sawContent = true;
+    if (isTerminalEvent(event)) {
+      sawTerminal = true;
+      // Only a successful terminal is the silent failure. `error` and `incomplete` are already
+      // a stated outcome the client can render, so flagging them would be noise.
+      if (!sawContent && event.type === "done") onEmptyTurn();
+    }
+    yield event;
+  }
+  // A stream that ends before any terminal is the pre-output EOF variant of the same failure.
+  if (!sawContent && !sawTerminal) onEmptyTurn();
+}
+
 /**
  * Terminal stop reasons the bridge renders as a visible `response.incomplete`
  * (max_tokens / content_filter). Those are already a stated failure, not the
@@ -153,9 +188,10 @@ export interface EmptyCompletionGuardOptions {
  * Watch an adapter event stream for the empty-completion failure mode. Events
  * are held until the turn produces content or ends: reasoning and other
  * pre-content events stay buffered (released in order on first content), the
- * terminal is withheld, and an empty terminal triggers one identical-turn
- * retry through `continuation`. Usage is merged across attempts so the bridge
- * and request log meter the whole turn, not just the attempt that succeeded.
+ * terminal is withheld, and an empty terminal or pre-output EOF triggers one
+ * identical-turn retry through `continuation`. Usage is merged across attempts
+ * so the bridge and request log meter the whole turn, not just the attempt that
+ * succeeded.
  *
  * Heartbeats always pass through untouched: they feed the bridge's stall
  * watchdog, so holding them behind the content gate would trip false
@@ -194,7 +230,11 @@ export async function* guardEmptyCompletionEventStream(
       if (sawContent || passthrough) {
         // Buffered content is already flowing; everything downstream passes
         // through. Every terminal carries usage merged across every attempt.
-        yield isTerminalEvent(event) ? withUsage(event) : event;
+        if (isTerminalEvent(event)) {
+          yield withUsage(event);
+          return;
+        }
+        yield event;
         continue;
       }
       if (isContentEvent(event)) {
@@ -267,8 +307,25 @@ export async function* guardEmptyCompletionEventStream(
       if (isReasoningEvent(event)) yield { type: "heartbeat" };
     }
     if (!terminalSeen) {
-      // The source ended without a terminal event (truncated stream). Release
-      // what was held so the bridge can mark the stream incomplete.
+      // A terminal-less EOF before text or a tool call is replay-safe: nothing
+      // actionable reached the client. Retry once, then surface a stated error
+      // instead of letting the bridge reduce the turn to adapter_eof.
+      if (!sawContent && !passthrough && retries < maxRetries) {
+        retries += 1;
+        try {
+          source = await options.continuation();
+        } catch {
+          yield emptyCompletionRetryFailedEvent(usage, true);
+          return;
+        }
+        continue;
+      }
+      if (!sawContent && retries > 0) {
+        yield emptyCompletionRetryFailedEvent(usage, true);
+        return;
+      }
+      // Post-output EOF remains incomplete; replaying could duplicate text or
+      // executable tool calls.
       yield* releaseHeld();
       return;
     }

package/src/server/responses/fetch-helpers.ts

@@ -5,107 +5,12 @@ import {
   shouldUseCodexWsUpstream,
   type BunRuntimeGateInput,
 } from "./ws-upstream";
-import { bridgeToResponsesSSE, buildResponseJSON, formatErrorResponse, type ResponsesTerminalStatus } from "../../bridge";
-import {
-  getConfigPath,
-  multiAgentGuidanceEnabled,
-  resolveEnvValue,
-} from "../../config";
-import { parseRequest } from "../../responses/parser";
-import { buildCompactV1Output, COMPACT_PROMPT, decodeCompactionSummary, extractCompactUserMessages } from "../../responses/compaction";
-import { FORWARD_HEADERS, sanitizeReasoningInputContent } from "../../adapters/openai-responses";
-import { expandPreviousResponseInput, previousResponseProviderState, rememberResponseState } from "../../responses/state";
-import { routeModel } from "../../router";
-import {
-  advanceComboAfterFailure,
-  comboDefaultEffort,
-  comboFailureDecision,
-  comboIdFromRawBody,
-  concreteComboRequestBody,
-  getCombo,
-  isComboTargetInCooldown,
-  NoAvailableComboTargetsError,
-  noteComboSuccess,
-  parseRetryAfterMs,
-  pickComboTarget,
-  targetKey,
-} from "../../combos";
-import { isInjectionDebugEnabled } from "../../lib/debug-settings";
-import { injectionDebugLog } from "../../lib/injection-debug-log";
-import { modelInList, namespacedToolName } from "../../types";
-import type { AdapterEvent, OcxConfig, OcxParsedRequest, OcxProviderConfig, OcxProviderContinuationState, OcxUsage } from "../../types";
-import {
-  forceRefreshOAuthAccessSnapshot,
-  getOAuthCredentialApiBaseUrl,
-  getOAuthCredentialProjectId,
-  getValidAccessTokenSnapshot,
-  type OAuthAccessSnapshot,
-  UnsupportedOAuthProviderError,
-} from "../../oauth";
-import { buildWebSearchTool, planWebSearch, runWithWebSearch, shouldResolveOpenAiWebSearchSidecar } from "../../web-search";
-import { describeImagesInPlace, planVisionSidecar, shouldResolveOpenAiVisionSidecar, stripImagesInPlace } from "../../vision";
-import { createAdapterEventQueue, preflightAdapterEvents } from "../../adapters/run-turn-queue";
-import {
-  applyCodexAuthContextToProvider,
-  CodexAccountCooldownError,
-  CodexAuthContextError,
-  CodexDirectAuthenticationError,
-  CodexPoolAuthenticationError,
-  CodexThreadAffinityExpiredError,
-  headersForCodexAuthContext,
-  isCodexAuthContextUsable,
-  resolveCodexAuthContext,
-  type CodexAuthContext,
-} from "../../codex/auth-context";
-import {
-  formatCodexProviderForLog,
-  recordCodexUpstreamOutcome,
-  type CodexUpstreamOutcome,
-} from "../../codex/routing";
-import { fetchWithResetRetry, fetchWithTransientRetry, applyUpstreamRecoveryInit } from "../../lib/upstream-retry";
-import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "../auth-cors";
-import { listOpenAiForwardSidecarCandidates, resolveFirstUsableOpenAiSidecar, type ResolvedOpenAiForwardSidecar } from "../../providers/openai-sidecar";
-import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
-import { slugsEquivalent } from "../../providers/slug-codec";
-import { applyOpenAiVirtualModel, resolveOpenAiCompactModel } from "../../providers/openai-virtual-models";
-import { isUsageDebugEnabled } from "../../usage/debug";
-import { readJsonRequestBody, DecompressedBodyTooLargeError, UnsupportedContentEncodingError } from "../request-decompress";
-import { resolveAdapter, resolveWireProtocolOverride } from "../adapter-resolve";
-import { hasKeyPoolFailover, rotateProviderTransportOn429 } from "../../providers/key-failover";
-import { shouldAttemptImageTierRetry } from "../image-retry";
-import { resolveProviderTransport } from "../../providers/xai-transport";
+import type { OcxProviderConfig } from "../../types";
 import type { WsData } from "../ws-bridge";
-import { registerTurn, trackStreamLifetime, unregisterTurn } from "../lifecycle";
-import { redactSecretString } from "../../lib/redact";
-import { readBoundedResponseBody } from "../../lib/bounded-body";
-import { supportedLadderFor } from "../effort-policy";
-import {
-  beginRequestAttempt,
-  catalogModelSupportsServiceTier,
-  finishRequestAttempt,
-  inspectResponseLogJson,
-  noteAttemptSend,
-  readConfiguredCodexServiceTier,
-  requestLogSpeedLabel,
-  sealRequestAttemptIdentity,
-  usageFromResponsesPayload,
-  type RequestLogContext,
-} from "../request-log";
-import type { AttemptRecoveryKind } from "../../usage/log";
-import {
-  consumeForInspection,
-  consumeForResponseLogMetadata,
-  markNativePassthroughSseResponse,
-  relaySseWithFailedTail,
-  relayWithAbort,
-  sanitizePassthroughHeaders,
-} from "../relay";
-import { hasResponsesItemIdRepair, relaySseWithResponsesItemIdRepair } from "../responses-item-id-repair";
-import type { EffectiveSubagentRoster, SpawnAgentSurface } from "../../codex/catalog";
 import { waitForProviderRequestSlot } from "../../providers/request-pacing";
 import { withUpstreamHttpVersion } from "../../lib/upstream-http-version";
 
-export { withUpstreamHttpVersion } from "../../lib/upstream-http-version";
+export { withUpstreamHttpVersion };
 
 export function disableResponsesRequestTimeout(req: Request, server: Pick<Server<WsData>, "timeout"> | undefined): boolean {
   if (!server) return false;
@@ -159,14 +64,26 @@ export function providerFetch(
   options: ProviderFetchOptions = {},
 ): ProviderFetch {
   const base = (provider as OcxProviderConfig & { fetch?: typeof globalThis.fetch }).fetch ?? globalThis.fetch;
+  const preconnect = (...args: Parameters<typeof globalThis.fetch.preconnect>): void => {
+    base.preconnect?.(...args);
+  };
+  const httpFetch = Object.assign(
+    (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) =>
+      base(input, { ...withUpstreamHttpVersion(input, init, provider), timeout: 0 }),
+    { preconnect },
+  ) as typeof globalThis.fetch;
   // ChatGPT Codex backend: streaming turns ride the responses_websockets
   // transport (measured ~3s faster TTFT than the SSE POST queue); everything
   // else keeps the provider's HTTP fetch. See ws-upstream.ts for the details.
   const unpaced = async (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => {
     if (typeof input === "string" && init && shouldUseCodexWsUpstream(input, init, runtime)) {
-      return codexWsUpstreamFetch(input, init, base, runtime);
+      // The fallback has to be the same HTTP fetch the non-WS branch would have
+      // used, protocol pin included: a WS turn that falls back is serving the
+      // request over HTTP, and dropping the provider's `upstreamHttpVersion`
+      // there would silently negotiate a transport the operator ruled out.
+      return codexWsUpstreamFetch(input, init, httpFetch, runtime);
     }
-    return base(input, withUpstreamHttpVersion(input, init, provider));
+    return httpFetch(input, init);
   };
   let pacingSlotAcquired = options.pacingSlotAcquired === true;
   const waitForPacing = (signal?: AbortSignal) => {
@@ -182,9 +99,6 @@ export function providerFetch(
     await waitForPacing(init?.signal ?? undefined);
     return unpaced(input, init);
   };
-  const preconnect = (...args: Parameters<typeof globalThis.fetch.preconnect>): void => {
-    base.preconnect?.(...args);
-  };
   return Object.assign(wrapped, {
     preconnect,
     waitForPacing,
@@ -225,6 +139,7 @@ export async function fetchWithHeaderTimeout(
       // indistinguishable from a pre-connection failure (#914).
       ...(manualRedirect ? { redirect: "manual" as const } : {}),
       signal: AbortSignal.any([abortSignal, timeout.signal]),
+      timeout: 0,
     });
   } finally {
     clearTimeout(timer);

package/src/server/responses/input-admission.ts

@@ -68,7 +68,9 @@ function imageTokens(imageUrl: string): number {
 }
 
 function contentPartTokens(part: OcxContentPart, modelId: string): number {
-  return part.type === "image" ? imageTokens(part.imageUrl) : estimateTokens(part.text, modelId);
+  if (part.type === "image") return imageTokens(part.imageUrl);
+  if (part.type === "video") return imageTokens(part.videoUrl);
+  return estimateTokens(part.text, modelId);
 }
 
 function contentTokens(content: string | readonly OcxContentPart[], modelId: string): number {

package/src/server/responses/passthrough-error.ts

@@ -1,9 +1,29 @@
 import { formatErrorResponse } from "../../bridge";
+import { isCyberPolicyCode, isCyberPolicyMessage } from "../../lib/errors";
 import {
   resolveClientRetryAfter,
   validateClientRetryAfterHeader,
 } from "../../lib/retry-after";
 
+function isCyberPolicyBody(body: string): boolean {
+  if (isCyberPolicyMessage(body)) return true;
+  try {
+    const parsed = JSON.parse(body) as Record<string, unknown>;
+    const response = parsed.response && typeof parsed.response === "object" && !Array.isArray(parsed.response)
+      ? parsed.response as Record<string, unknown>
+      : undefined;
+    for (const candidate of [parsed.error, response?.error, response?.last_error, parsed.last_error, parsed]) {
+      if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) continue;
+      const record = candidate as Record<string, unknown>;
+      if (isCyberPolicyCode(typeof record.code === "string" ? record.code : undefined)) return true;
+      if (typeof record.message === "string" && isCyberPolicyMessage(record.message)) return true;
+    }
+  } catch {
+    /* non-JSON body — message detection above is the only safe fallback */
+  }
+  return false;
+}
+
 /**
  * Passthrough adapters historically relayed upstream non-2xx bodies verbatim.
  * Codex maps an *empty* body to the literal client string "Unknown error"
@@ -32,18 +52,22 @@ export function formatPassthroughUpstreamError(
   const now = options?.now ?? Date.now();
   const upstreamRetryAfter = options?.headers?.get("retry-after")?.trim() || undefined;
   const originalValid = validateClientRetryAfterHeader(upstreamRetryAfter, now);
-  const resolved = resolveClientRetryAfter({
-    status,
-    message: trimmed || `Provider error ${status}: (empty body)`,
-    upstreamRetryAfter,
-    now,
-  });
+  const cyberPolicyFailure = isCyberPolicyBody(trimmed);
+  const resolved = cyberPolicyFailure
+    ? undefined
+    : resolveClientRetryAfter({
+      status,
+      message: trimmed || `Provider error ${status}: (empty body)`,
+      upstreamRetryAfter,
+      now,
+    });
 
   if (trimmed) {
     const needsSet = resolved !== undefined && upstreamRetryAfter !== resolved;
-    const needsDelete = resolved === undefined
-      && upstreamRetryAfter !== undefined
-      && originalValid === undefined;
+    const needsDelete = (cyberPolicyFailure && upstreamRetryAfter !== undefined)
+      || (resolved === undefined
+        && upstreamRetryAfter !== undefined
+        && originalValid === undefined);
 
     if (!needsSet && !needsDelete) {
       return new Response(bodyText, {

package/src/server/responses/responses-field-backfill.ts

@@ -91,6 +91,29 @@ function nextSyntheticItemSlot(): ItemIdSlot {
   return { kind: "fallback", ordinal: syntheticItemOrdinal };
 }
 
+/**
+ * Backfill `status` on a message output item if missing.
+ *
+ * The Responses API spec defines `status` as a required field on
+ * `OutputMessage`. Some upstream relays omit it, which causes strict
+ * deserializers (e.g. grok-build's serde types) to fail with
+ * `missing field 'status'`. Only message items carry this field in the
+ * Responses schema; reasoning, function_call, and other item types do not.
+ *
+ * The value is inferred from the event context: `output_item.added` and
+ * `response.created` / `response.in_progress` mean the message is still
+ * being generated (`in_progress`); `output_item.done` and
+ * `response.completed` / `response.incomplete` mean the message is
+ * finalized (`completed` / `incomplete` respectively).
+ *
+ * Returns the same object reference if no change is needed.
+ */
+function backfillItemStatus(item: Record<string, unknown>, inferredStatus: string): Record<string, unknown> {
+  if (item.type !== "message") return item;
+  if ("status" in item) return item;
+  return { ...item, status: inferredStatus };
+}
+
 /**
  * Backfill annotations: [] on an output_text content part if missing.
  * Returns the same object reference if no change is needed.
@@ -122,10 +145,10 @@ function backfillContentArray(content: unknown): unknown {
 
 /**
  * Walk an output item and backfill output_text parts in its content.
- * Also backfills a missing required id on the item itself.
+ * Also backfills a missing required id and status on the item itself.
  * Returns the same object reference if nothing changed.
  */
-function backfillOutputItem(item: unknown, slot: ItemIdSlot): unknown {
+function backfillOutputItem(item: unknown, slot: ItemIdSlot, inferredStatus: string): unknown {
   if (!isPlainObject(item)) return item;
   // The compact wire family is the `/v1/responses/compact` format, not a Responses output item.
   // Those items have no `id` in that contract, so synthesizing one changes a response body the
@@ -136,34 +159,92 @@ function backfillOutputItem(item: unknown, slot: ItemIdSlot): unknown {
   const content = item.content;
   const repaired = backfillContentArray(content);
   const withId = backfillItemId(item, slot);
-  if (repaired === content && withId === item) return item;
-  return { ...withId, ...(repaired === content ? {} : { content: repaired }) };
+  const withStatus = backfillItemStatus(withId, inferredStatus);
+  if (repaired === content && withStatus === item) return item;
+  return { ...withStatus, ...(repaired === content ? {} : { content: repaired }) };
 }
 
 /**
  * Walk a response object's output[] and backfill output_text parts.
+ *
+ * `inferredItemStatus` is the status to backfill on message items that lack
+ * one — derived from the event type so `output_item.added` / `response.created`
+ * gets `in_progress` while `output_item.done` / `response.completed` gets
+ * `completed`.
+ *
+ * Deliberately does NOT backfill `created_at`. #2639 proposed it for the same
+ * strict-decoder reason as `status`, but the proxy also relays some upstream
+ * responses verbatim, and `tests/server-combo-failover-e2e.test.ts` asserts a
+ * combo backup response is returned byte-exact. Injecting a field the upstream
+ * never sent breaks that contract. Both cannot hold for the same body, so the
+ * `created_at` half needs its own decision about which contract yields; it is
+ * not a detail to slip in beside `status`.
+ *
  * Returns the same object reference if nothing changed.
  */
-function backfillResponseOutput(response: unknown): unknown {
+function backfillResponseOutput(response: unknown, inferredItemStatus: string): unknown {
   if (!isPlainObject(response)) return response;
   const output = response.output;
   if (!Array.isArray(output)) return response;
   let changed = false;
   const repaired = output.map((item, idx) => {
     if (!isPlainObject(item)) return item;
-    const next = backfillOutputItem(item, { kind: "index", index: idx });
+    const next = backfillOutputItem(item, { kind: "index", index: idx }, inferredItemStatus);
     if (next !== item) changed = true;
     return next;
   });
   return changed ? { ...response, output: repaired } : response;
 }
 
+/**
+ * Infer the status to backfill on a message item from the event type.
+ *
+ * `output_item.added` means the item is still being generated (`in_progress`);
+ * `output_item.done` means it is finalized (`completed`). Response-level events
+ * infer from the response's own status field — which is authoritative when present.
+ * If the response status is also absent, the event type itself determines the phase:
+ * `response.created` / `response.in_progress` → `in_progress`,
+ * `response.completed` → `completed`, `response.incomplete` → `incomplete`.
+ */
+function inferredStatusForEventType(eventType: string): string {
+  if (eventType === "response.output_item.added") return "in_progress";
+  if (eventType === "response.output_item.done") return "completed";
+  if (eventType === "response.created" || eventType === "response.in_progress") return "in_progress";
+  // `queued` is a real Responses lifecycle status: the response exists but has not
+  // started generating. Without this row it falls through to the `completed`
+  // default below, which would mark an unstarted message as finished.
+  if (eventType === "response.queued") return "in_progress";
+  if (eventType === "response.incomplete" || eventType === "response.failed") return "incomplete";
+  return "completed";
+}
+
+/**
+ * Map a response-level lifecycle status to a valid OutputMessage status.
+ *
+ * `OutputMessage.status` accepts only `in_progress`, `completed`, or
+ * `incomplete`. Response-level statuses like `failed` or `cancelled` have no
+ * direct message-level equivalent, but `incomplete` is the correct semantic
+ * mapping: the message did not finish generating. Writing `completed` would
+ * assert something the upstream never claimed — a client branching on
+ * `status === "completed"` would treat a truncated message as whole.
+ */
+function messageStatusFromResponseStatus(status: string): string | null {
+  if (status === "in_progress" || status === "completed" || status === "incomplete") return status;
+  // A queued response has not begun generating, so its message items are
+  // in_progress — never completed. Returning null here would fall back to the
+  // event-type inference, whose default is `completed`.
+  if (status === "queued") return "in_progress";
+  if (status === "failed" || status === "cancelled") return "incomplete";
+  return null;
+}
+
 /**
  * Statelessly rewrite one SSE event: backfill annotations
  * on any output_text content part found in the event payload.
  */
 function rewriteEvent(event: Record<string, unknown>): Record<string, unknown> {
   const type = typeof event.type === "string" ? event.type : "";
+  const inferredItemStatus = inferredStatusForEventType(type);
   let next = event;
   let changed = false;
 
@@ -177,8 +258,8 @@ function rewriteEvent(event: Record<string, unknown>): Record<string, unknown> {
     // is not recoverable in that case, but a unique id is what strict decoders require, and a
     // well-formed stream still gets the stable index-derived id.
     const item = typeof rawIndex === "number" && Number.isInteger(rawIndex) && rawIndex >= 0
-      ? backfillOutputItem(event.item, { kind: "index", index: rawIndex })
-      : backfillOutputItem(event.item, nextSyntheticItemSlot());
+      ? backfillOutputItem(event.item, { kind: "index", index: rawIndex }, inferredItemStatus)
+      : backfillOutputItem(event.item, nextSyntheticItemSlot(), inferredItemStatus);
     if (item !== event.item) {
       next = { ...next, item };
       changed = true;
@@ -198,7 +279,13 @@ function rewriteEvent(event: Record<string, unknown>): Record<string, unknown> {
   // response.created / in_progress / completed / incomplete / failed:
   // response.output[].content[] -> output_text parts
   if (isPlainObject(event.response)) {
-    const response = backfillResponseOutput(event.response);
+    // For response-level events, prefer the response's own status when it is a valid
+    // OutputMessage status. Response lifecycle statuses like "failed" or "cancelled"
+    // have no message-level equivalent — fall back to the event-type inference instead.
+    const responseStatus = typeof event.response.status === "string"
+      ? messageStatusFromResponseStatus(event.response.status) ?? inferredItemStatus
+      : inferredItemStatus;
+    const response = backfillResponseOutput(event.response, responseStatus);
     if (response !== event.response) {
       next = { ...next, response };
       changed = true;
@@ -210,9 +297,9 @@ function rewriteEvent(event: Record<string, unknown>): Record<string, unknown> {
 
 /**
  * Create a stateless SSE block rewrite that backfills annotations and
- * on output_text content parts. Unconditional: the field is a required
- * canonical Responses field, so adding it when absent is safe for all
- * clients.
+ * message status on output_text content parts and message items.
+ * Unconditional: both are required canonical Responses fields, so adding
+ * them when absent is safe for all clients.
  */
 export function createResponsesFieldBackfillBlockRewrite(): SseBlockRewrite {
   const rewrite: SseBlockRewrite = (block: string): readonly string[] => {
@@ -245,7 +332,12 @@ export function backfillResponsesFieldsJson(payload: string): string {
     return payload;
   }
   if (!isPlainObject(response)) return payload;
-  const repaired = backfillResponseOutput(response);
+  // For a non-streaming response, derive the item status from the response's own
+  // status field when it is a valid OutputMessage status; fall back to "completed".
+  const inferredItemStatus = typeof response.status === "string"
+    ? messageStatusFromResponseStatus(response.status) ?? "completed"
+    : "completed";
+  const repaired = backfillResponseOutput(response, inferredItemStatus);
   if (repaired === response) return payload;
   return JSON.stringify(repaired);
 }

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

@@ -28,6 +28,25 @@ const UPGRADE_DEADLINE_MS = 10_000;
 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";
+// 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;
 
 export type BunRuntimeIdentity = {
   version: string;
@@ -102,6 +121,52 @@ export function shouldUseCodexWsUpstream(
   }
 }
 
+const CLOSED_BEFORE_TERMINAL = "codex websocket closed before a Responses terminal event";
+
+/**
+ * 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.
+ */
+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;
+}
+
 export function codexWsUpstreamFetch(
   url: string,
   init: RequestInit,
@@ -127,6 +192,14 @@ export function codexWsUpstreamFetch(
     return sseFallback(url, init);
   }
 
+  // Decide before dialing. Once the socket is open the caller already holds a
+  // streaming Response, so the oversized close can only be surfaced as a stream
+  // error — and a resend at that point could double-generate. Measuring the
+  // frame we are about to send keeps the whole failure mode unreachable.
+  if (codexWsCreateFrameExceedsLimit(frameText)) {
+    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.
@@ -279,7 +352,7 @@ export function codexWsUpstreamFetch(
       }
     });
 
-    ws.addEventListener("close", () => {
+    ws.addEventListener("close", (event: unknown) => {
       signal?.removeEventListener("abort", onAbort);
       if (!opened) {
         if (settledPreOpen) return;
@@ -297,7 +370,7 @@ export function codexWsUpstreamFetch(
         // 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 */ }
+        try { controller.error(new Error(closedBeforeTerminalMessage(event))); } catch { /* stream already done */ }
       }
     });