@iislee/opencodex 2.11.0 → 2.35.0

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

@@ -0,0 +1,333 @@
+import type { AdapterEvent, OcxConfig, OcxUsage } from "../../types";
+
+/**
+ * Empty-completion guard for Responses turns (port of codex-router's
+ * empty-completion-guard + single retry, PR #145).
+ *
+ * Failure mode: the upstream answers 200 and completes the turn but never
+ * produced output text or a tool call (a reasoning-only stream that ends with
+ * nothing is the canonical shape). The client has no code path for "the model
+ * said nothing", so it silently records the turn as done — the "random stop"
+ * nobody can explain. The guard holds pre-content events (reasoning deltas
+ * are deliberately NOT content), and when a terminal event arrives with no
+ * content it suppresses the terminal and retries the IDENTICAL turn once
+ * (same request bytes, same headers). If the retry is also empty — or fails
+ * upstream — the client sees a stated failure instead of a second silent
+ * success.
+ *
+ * The retry is explicitly enabled by top-level config. The environment switch
+ * is a disable-only emergency override: OCX_EMPTY_COMPLETION_RETRY=0 restores
+ * the previous relay behavior without editing the persisted config.
+ */
+export const EMPTY_COMPLETION_RETRY_ENV = "OCX_EMPTY_COMPLETION_RETRY";
+
+/** Retained pre-content events are bounded independently by count and encoded size. */
+export const EMPTY_COMPLETION_MAX_BUFFERED_EVENTS = 1_024;
+export const EMPTY_COMPLETION_MAX_BUFFERED_BYTES = 1_048_576;
+
+export function emptyCompletionRetryEnabled(
+  config: Pick<OcxConfig, "emptyCompletionRetry">,
+  env: Record<string, string | undefined> = process.env,
+): boolean {
+  return config.emptyCompletionRetry === true && env[EMPTY_COMPLETION_RETRY_ENV] !== "0";
+}
+
+/** 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
+ * silent empty success this guard exists to catch, and retrying the identical
+ * request would burn tokens for the same truncated result.
+ */
+const VISIBLE_INCOMPLETE_STOP_REASONS = new Set(["max_tokens", "content_filter"]);
+const UTF8_ENCODER = new TextEncoder();
+
+function retainedEventBytes(event: AdapterEvent): number {
+  return UTF8_ENCODER.encode(JSON.stringify(event)).byteLength;
+}
+
+function isReasoningEvent(event: AdapterEvent): boolean {
+  return event.type === "thinking_delta"
+    || event.type === "thinking_signature"
+    || event.type === "redacted_thinking"
+    || event.type === "kiro_redacted_reasoning"
+    || event.type === "reasoning_raw_delta";
+}
+
+function isTerminalEvent(
+  event: AdapterEvent,
+): event is Extract<AdapterEvent, { type: "done" | "incomplete" | "error" }> {
+  return event.type === "done" || event.type === "incomplete" || event.type === "error";
+}
+
+/**
+ * Content means something the client can act on: output text or a tool call
+ * (web-search cells included). Reasoning deltas are deliberately not content —
+ * a turn that streams only reasoning and then completes with nothing is
+ * exactly the empty completion this guard exists to catch. Empty text deltas
+ * (some batch adapters always carry `""`) are not content either.
+ */
+export function isContentEvent(event: AdapterEvent): boolean {
+  switch (event.type) {
+    case "text_delta":
+      return event.text.length > 0;
+    case "tool_call_start":
+    case "tool_call_delta":
+    case "tool_call_end":
+    case "web_search_call_begin":
+    case "web_search_call_end":
+      return true;
+    default:
+      return false;
+  }
+}
+
+export function emptyCompletionRetryFailedEvent(
+  usage?: OcxUsage,
+  retryFailedUpstream = false,
+): Extract<AdapterEvent, { type: "error" }> {
+  return {
+    type: "error",
+    status: 502,
+    errorType: "upstream_error",
+    code: EMPTY_COMPLETION_RETRY_FAILED_CODE,
+    message: retryFailedUpstream
+      ? "The model returned an empty completion and the retry failed upstream."
+      : "The model returned an empty completion. opencodex retried once and the completion was empty again.",
+    ...(usage ? { usage } : {}),
+  };
+}
+
+/**
+ * Sum two usage snapshots. Same semantics as terminal-guard's mergeUsage and
+ * request-log's aggregateAttemptUsage: token totals add across the attempts;
+ * `estimated` wins when either attempt only estimated.
+ */
+export function mergeUsage(
+  first: OcxUsage | undefined,
+  second: OcxUsage | undefined,
+): OcxUsage | undefined {
+  if (!first) return second;
+  if (!second) return first;
+  const sumOptional = (key: keyof OcxUsage): number | undefined => {
+    const left = first[key];
+    const right = second[key];
+    return typeof left === "number" || typeof right === "number"
+      ? (typeof left === "number" ? left : 0) + (typeof right === "number" ? right : 0)
+      : undefined;
+  };
+  const cachedInputTokens = sumOptional("cachedInputTokens");
+  const cacheReadInputTokens = sumOptional("cacheReadInputTokens");
+  const cacheCreationInputTokens = sumOptional("cacheCreationInputTokens");
+  const reasoningOutputTokens = sumOptional("reasoningOutputTokens");
+  const contextTotalTokens = second.contextTotalTokens ?? first.contextTotalTokens;
+  const inputTokens = first.inputTokens + second.inputTokens;
+  const outputTokens = first.outputTokens + second.outputTokens;
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens: inputTokens + outputTokens,
+    ...(contextTotalTokens !== undefined ? { contextTotalTokens } : {}),
+    ...(cachedInputTokens !== undefined ? { cachedInputTokens } : {}),
+    ...(cacheReadInputTokens !== undefined ? { cacheReadInputTokens } : {}),
+    ...(cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens } : {}),
+    ...(reasoningOutputTokens !== undefined ? { reasoningOutputTokens } : {}),
+    ...(first.estimated || second.estimated ? { estimated: true } : {}),
+  };
+}
+
+export interface EmptyCompletionGuardOptions {
+  firstEvents: AsyncIterable<AdapterEvent>;
+  /**
+   * Re-run the IDENTICAL turn: same request body, same headers, same signal.
+   * Receives no arguments — the request must not be modified between attempts.
+   */
+  continuation: () => AsyncIterable<AdapterEvent> | Promise<AsyncIterable<AdapterEvent>>;
+  /** How many times an empty completion is retried; default 1 (the router's single retry). */
+  maxRetries?: number;
+}
+
+/**
+ * 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 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
+ * upstream_stall_timeout failures on slow reasoning-only turns.
+ */
+export async function* guardEmptyCompletionEventStream(
+  options: EmptyCompletionGuardOptions,
+): AsyncGenerator<AdapterEvent> {
+  const maxRetries = Math.max(0, Math.floor(options.maxRetries ?? 1));
+  let source = options.firstEvents;
+  let held: AdapterEvent[] = [];
+  let heldBytes = 0;
+  let sawContent = false;
+  let passthrough = false;
+  let retries = 0;
+  let usage: OcxUsage | undefined;
+
+  const withUsage = (event: AdapterEvent & { usage?: OcxUsage }): AdapterEvent => {
+    const merged = mergeUsage(usage, event.usage);
+    return merged ? { ...event, ...(merged ? { usage: merged } : {}) } : event;
+  };
+  const releaseHeld = (): AdapterEvent[] => {
+    const released = held;
+    held = [];
+    heldBytes = 0;
+    return released;
+  };
+
+  while (true) {
+    let terminalSeen = false;
+    for await (const event of source) {
+      if (event.type === "heartbeat") {
+        yield event;
+        continue;
+      }
+      if (sawContent || passthrough) {
+        // Buffered content is already flowing; everything downstream passes
+        // through. Every terminal carries usage merged across every attempt.
+        if (isTerminalEvent(event)) {
+          yield withUsage(event);
+          return;
+        }
+        yield event;
+        continue;
+      }
+      if (isContentEvent(event)) {
+        sawContent = true;
+        yield* releaseHeld();
+        yield event;
+        continue;
+      }
+      if (event.type === "done") {
+        usage = mergeUsage(usage, event.usage);
+        if (event.stopReason !== undefined && VISIBLE_INCOMPLETE_STOP_REASONS.has(event.stopReason)) {
+          // Rendered as response.incomplete: a stated failure, not the silent
+          // empty success this guard exists to catch.
+          yield* releaseHeld();
+          yield { ...event, ...(usage ? { usage } : {}) };
+          return;
+        }
+        if (retries < maxRetries) {
+          // Suppress the terminal: the client must never see a completed event
+          // for a turn that produced nothing. Retry the identical turn.
+          retries += 1;
+          try {
+            source = await options.continuation();
+          } catch {
+            yield emptyCompletionRetryFailedEvent(usage, true);
+            return;
+          }
+          terminalSeen = true;
+          break;
+        }
+        // The retry was also empty: a stated failure, not a second silent
+        // success.
+        yield emptyCompletionRetryFailedEvent(usage);
+        return;
+      }
+      if (event.type === "error") {
+        if (retries > 0 && event.status !== 499) {
+          // The retry failed upstream. Its body cannot reach the client (the
+          // 200 head went out with the first attempt), so state the failure in
+          // the stream's own error framing — same move as the router's
+          // empty_completion_retry_failed. Client cancels (499) pass through.
+          yield emptyCompletionRetryFailedEvent(mergeUsage(usage, event.usage), true);
+          return;
+        }
+        yield* releaseHeld();
+        yield withUsage(event);
+        return;
+      }
+      if (event.type === "incomplete") {
+        // A structured incomplete is already a visible failure; never convert
+        // it into an empty completion.
+        yield* releaseHeld();
+        yield withUsage(event);
+        return;
+      }
+      const eventBytes = retainedEventBytes(event);
+      if (held.length + 1 > EMPTY_COMPLETION_MAX_BUFFERED_EVENTS
+        || heldBytes + eventBytes > EMPTY_COMPLETION_MAX_BUFFERED_BYTES) {
+        // Preserve data rather than retaining without bound: release the prefix,
+        // emit this event, and stop attempting an empty-completion retry for the turn.
+        yield* releaseHeld();
+        yield event;
+        passthrough = true;
+        continue;
+      }
+      held.push(event);
+      heldBytes += eventBytes;
+      // The bridge watchdog sees only yielded events. Feed it while reasoning is
+      // held so a long reasoning-only prefix remains live without exposing it early.
+      if (isReasoningEvent(event)) yield { type: "heartbeat" };
+    }
+    if (!terminalSeen) {
+      // 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/encrypted-payload.ts

@@ -145,6 +145,10 @@ function isStructurallyValidFernetToken(token: string): boolean {
   return ciphertextLength >= 16 && ciphertextLength % 16 === 0;
 }
 
+export function structurallyValidFernetTokens(payload: string): string[] {
+  return fernetTokenRuns(payload).map(run => run.token);
+}
+
 /** Maximal, boundary-delimited and structurally valid Fernet runs embedded in a slot. */
 function fernetTokenRuns(payload: string): FernetTokenRun[] {
   const runs: FernetTokenRun[] = [];
@@ -261,48 +265,67 @@ export function hasEncryptedContentPart(content: unknown): boolean {
 export function sanitizeEncryptedContentInPlace(input: unknown): number {
   if (!Array.isArray(input)) return 0;
   let rewritten = 0;
-  const visit = (node: unknown): number => {
-    const before = rewritten;
-    if (Array.isArray(node)) {
-      for (let i = 0; i < node.length; i += 1) {
-        const child = node[i] as unknown;
-        if (
-          child && typeof child === "object"
-          && (child as { type?: unknown }).type === "encrypted_content"
-          && typeof (child as { encrypted_content?: unknown }).encrypted_content === "string"
-        ) {
-          const payload = (child as { encrypted_content: string }).encrypted_content;
-          if (!looksLikeBackendCiphertext(payload)) {
-            const parts = encryptedSlotParts(payload);
-            node.splice(i, 1, ...parts);
-            i += parts.length - 1;
-            rewritten += 1;
-            continue;
-          }
-        }
-        const childRewrites = visit(child);
-        if (
-          childRewrites > 0
-          && child && typeof child === "object"
-          && (child as { type?: unknown }).type === "agent_message"
-          && !hasEncryptedContentPart((child as { content?: unknown }).content)
-        ) {
-          const message = child as { type: string; role?: string; id?: unknown; author?: unknown; recipient?: unknown };
-          message.type = "message";
-          message.role = "user";
-          delete message.id;
-          delete message.author;
-          delete message.recipient;
+  type VisitFrame =
+    | { kind: "visit"; node: unknown }
+    | { kind: "array"; node: unknown[]; index: number }
+    | { kind: "object"; values: unknown[]; index: number }
+    | { kind: "agent"; message: Record<string, unknown>; rewrittenBefore: number };
+  const stack: VisitFrame[] = [{ kind: "visit", node: input }];
+
+  while (stack.length > 0) {
+    const frame = stack.pop()!;
+    if (frame.kind === "visit") {
+      if (Array.isArray(frame.node)) {
+        stack.push({ kind: "array", node: frame.node, index: 0 });
+      } else if (frame.node && typeof frame.node === "object") {
+        stack.push({ kind: "object", values: Object.values(frame.node), index: 0 });
+      }
+      continue;
+    }
+
+    if (frame.kind === "array") {
+      if (frame.index >= frame.node.length) continue;
+      const child = frame.node[frame.index] as unknown;
+      if (
+        child && typeof child === "object"
+        && (child as { type?: unknown }).type === "encrypted_content"
+        && typeof (child as { encrypted_content?: unknown }).encrypted_content === "string"
+      ) {
+        const payload = (child as { encrypted_content: string }).encrypted_content;
+        if (!looksLikeBackendCiphertext(payload)) {
+          const parts = encryptedSlotParts(payload);
+          frame.node.splice(frame.index, 1, ...parts);
+          rewritten += 1;
+          stack.push({ kind: "array", node: frame.node, index: frame.index + parts.length });
+          continue;
         }
       }
-      return rewritten - before;
+      stack.push({ kind: "array", node: frame.node, index: frame.index + 1 });
+      if (child && typeof child === "object" && (child as { type?: unknown }).type === "agent_message") {
+        stack.push({ kind: "agent", message: child as Record<string, unknown>, rewrittenBefore: rewritten });
+      }
+      stack.push({ kind: "visit", node: child });
+      continue;
     }
-    if (node && typeof node === "object") {
-      for (const value of Object.values(node)) visit(value);
+
+    if (frame.kind === "object") {
+      if (frame.index >= frame.values.length) continue;
+      stack.push({ kind: "object", values: frame.values, index: frame.index + 1 });
+      stack.push({ kind: "visit", node: frame.values[frame.index] });
+      continue;
     }
-    return rewritten - before;
-  };
-  visit(input);
+
+    if (
+      rewritten > frame.rewrittenBefore
+      && frame.message.type === "agent_message"
+      && !hasEncryptedContentPart(frame.message.content)
+    ) {
+      frame.message.type = "message";
+      frame.message.role = "user";
+      delete frame.message.id;
+      delete frame.message.author;
+      delete frame.message.recipient;
+    }
+  }
   return rewritten;
 }
-

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

@@ -1,102 +1,16 @@
 import type { Server } from "bun";
-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";
+  codexWsUpstreamFetch,
+  currentBunRuntimeIdentity,
+  shouldUseCodexWsUpstream,
+  type BunRuntimeGateInput,
+} from "./ws-upstream";
+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 };
 
 export function disableResponsesRequestTimeout(req: Request, server: Pick<Server<WsData>, "timeout"> | undefined): boolean {
   if (!server) return false;
@@ -118,10 +32,78 @@ export function safeHostLabel(url: string): string {
   }
 }
 
+/** Canonical origin (scheme + host) for failure-attribution keys: http and
+ * https for the same host must not share one ledger entry (#914 review). */
+export function safeOriginLabel(url: string): string {
+  try {
+    return new URL(url).origin.toLowerCase();
+  } catch {
+    return "upstream";
+  }
+}
+
 
 
-export function providerFetch(provider: OcxProviderConfig): typeof globalThis.fetch {
-  return (provider as OcxProviderConfig & { fetch?: typeof globalThis.fetch }).fetch ?? globalThis.fetch;
+export interface PaceAwareFetch {
+  waitForPacing?: (signal?: AbortSignal) => Promise<void>;
+  unpacedFetch?: typeof globalThis.fetch;
+}
+
+export type ProviderFetch = typeof globalThis.fetch & PaceAwareFetch;
+
+export interface ProviderFetchOptions {
+  providerName?: string;
+  modelId?: string;
+  /** One pacing slot was acquired immediately before this fetch wrapper was created. */
+  pacingSlotAcquired?: boolean;
+}
+
+export function providerFetch(
+  provider: OcxProviderConfig,
+  runtime: BunRuntimeGateInput = currentBunRuntimeIdentity(),
+  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)) {
+      // 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 httpFetch(input, init);
+  };
+  let pacingSlotAcquired = options.pacingSlotAcquired === true;
+  const waitForPacing = (signal?: AbortSignal) => {
+    if (pacingSlotAcquired) {
+      pacingSlotAcquired = false;
+      return Promise.resolve();
+    }
+    return options.providerName
+      ? waitForProviderRequestSlot(options.providerName, provider, options.modelId, signal)
+      : Promise.resolve();
+  };
+  const wrapped = async (input: Parameters<typeof globalThis.fetch>[0], init?: RequestInit) => {
+    await waitForPacing(init?.signal ?? undefined);
+    return unpaced(input, init);
+  };
+  return Object.assign(wrapped, {
+    preconnect,
+    waitForPacing,
+    unpacedFetch: Object.assign(unpaced, { preconnect }),
+  });
 }
 
 
@@ -133,7 +115,11 @@ export async function fetchWithHeaderTimeout(
   timeoutMs: number,
   preferIdentityEncoding = false,
   executor: typeof globalThis.fetch = globalThis.fetch,
+  manualRedirect = false,
 ): Promise<Response> {
+  const pacing = executor as ProviderFetch;
+  await pacing.waitForPacing?.(abortSignal);
+  const fetchExecutor = pacing.unpacedFetch ?? executor;
   const timeout = new AbortController();
   const timer = setTimeout(() => {
     if (!timeout.signal.aborted) timeout.abort(new DOMException("Timeout elapsed", "TimeoutError"));
@@ -145,13 +131,17 @@ export async function fetchWithHeaderTimeout(
     headers.set("accept-encoding", "identity");
   }
   try {
-    return await executor(url, {
+    return await fetchExecutor(url, {
       ...init,
       headers,
+      // Credential-bearing sends opt into manual redirects so a 3xx is relayed
+      // as a Response instead of being followed into a rejection that is
+      // indistinguishable from a pre-connection failure (#914).
+      ...(manualRedirect ? { redirect: "manual" as const } : {}),
       signal: AbortSignal.any([abortSignal, timeout.signal]),
+      timeout: 0,
     });
   } finally {
     clearTimeout(timer);
   }
 }
-