import { isNativeControlResponse } from "./native-response-control";
import { createOutboundCredentialMask, createTerminalErrorRedactionBlockRewrite } from "./terminal-error-redaction";
import type { ResponsesRequestContext, ResponsesAdmissionState } from "./core-options";
import type { PreparedResponsesRequest } from "./request-prepare";
import type { ResponsesTransport } from "./request-transport";
import type { ResponsesSidecarAuth } from "./request-sidecar-auth";
import type { ResponsesEffects } from "./response-effects";
import type { PassthroughExchange } from "./passthrough-dispatch";
import {
  sanitizePassthroughHeaders,
  createSseInspector,
  markEagerRelaySseResponse,
  markNativePassthroughSseResponse,
  markPreinspectedJsonResponse,
  consumeForInspection,
  consumeForResponseLogMetadata,
  relaySseWithFailedTail,
  relayWithAbort,
} from "../relay";
import { isUsageDebugEnabled } from "../../usage/debug";
import { isReplayRefusalResponse } from "../../lib/upstream-retry";
import { teeWithBoundedInspection } from "../inspection-tee";
import {
  codexForwardTerminalOutcomeRecorder,
  usesCodexForwardPoolAuth,
  codexQuotaOutcomeMeta,
  codexDenialOutcomeMeta,
  isFixedCodexAccount,
  shouldDeferCodexResetDerivedCooldown,
} from "./core-codex-account";
import type { ResponsesTerminalStatus } from "../../bridge";
import { isCodexWsQuotaObservedResponse, isCodexWsUpstreamResponse } from "./ws-upstream";
import { recordSubagentQuotaFailureForThreadSpawn } from "../../codex/subagent-model-fallback";
import { recordCodexUpstreamOutcome } from "../../codex/routing";
import { codexProbeLeaseId, codexProbeQuotaScope, codexTransientProbeGrant, releaseCodexAuthContextProbeLease } from "../../codex/auth-context";
import { consumeComboFailure } from "./core-combo-failure";
import { clientCancelledResponse, readDisplaySafeErrorText } from "./core-errors";
import { streamingContextOverflowResponse, jsonContextOverflowResponse } from "./context-overflow";
import { formatPassthroughUpstreamError } from "./passthrough-error";
import { rewriteUpstreamPolicyRefusal } from "./policy-refusal";
import {
  resolvePassthroughWebSearchBridgeAuth,
  planPassthroughWebSearchBridge,
  createPassthroughWebSearchBridgeStream,
  createPassthroughWebSearchBridgeExecutor,
} from "../../web-search/passthrough-bridge";
import { bridgeSearchReplayScope } from "../../responses/bridge-search-replay-cache";
import { fetchWithHeaderTimeout, providerFetch } from "./fetch-helpers";
import { providerApiKeySelectionIsCurrent } from "../../providers/api-key-selection";
import { requiresVisionPreprocessing } from "../../vision";
import { checkOutboundBodySize, describeOutboundBodyRefusal } from "./outbound-body-guard";
import { relayResponsesSseWithTerminalRepair } from "../responses-terminal-repair";
import {
  hasResponsesSnapshotRepair,
  createResponsesSnapshotBlockRewrite,
} from "../responses-snapshot-repair";
import { createResponsesModelPayloadRewrite, rewriteResponsesModelJson } from "../responses-model-rewrite";
import { createImageGenCallRestoreRewrite, restoreImageGenCallsInJson } from "../responses-image-gen-repair";
import {
  createSelfNamedToolCallNamespaceScrubRewrite,
  scrubSelfNamedToolCallNamespaceInJson,
} from "../responses-self-named-namespace-scrub";
import {
  createMuseToolNameRestoreRewrite,
  restoreMuseToolNamesInJson,
} from "../../responses/muse-tool-name-alias";
import {
  createRoutedNamespaceCallRestoreRewrite,
  restoreRoutedNamespaceCallsInJson,
} from "../../responses/namespace-tool-compat";
import {
  hasResponsesItemIdRepair,
  createResponsesItemIdPayloadRewrite,
  repairResponsesJsonItemIds,
} from "../responses-item-id-repair";
import {
  payloadRewriteAsBlockRewrite,
  composeSsePayloadRewrites,
  composeSseBlockRewrites,
  relaySseWithBlockRewrite,
} from "../sse-payload-rewrite";
import { createRoutedCustomToolRestoreBlockRewrite } from "../responses-custom-tool-repair";
import { createRoutedToolSearchRestoreBlockRewrite } from "../responses-tool-search-repair";
import { createGithubCopilotResponsesBlockRewrite } from "../github-copilot-responses-repair";
import {
  createGrokResponsesControlFrameBlockRewrite,
  createGrokResponsesTimestampBlockRewrite,
} from "../grok-responses-control-frame";
import { createGrokResponsesSparseTerminalBlockRewrite } from "../grok-responses-snapshot-repair";
import { isXaiResponsesDestination } from "../../providers/xai-transport";
import {
  createGrokUpstreamEnvelopeEchoBlockRewrite,
  responsesRequestMayReplayToolOutput,
  stripGrokUpstreamEnvelopeEchoFromResponsesJson,
} from "../grok-upstream-envelope-echo";
import {
  createPlaintextV2AgentMessageCallRestoreRewrite,
  restorePlaintextV2AgentMessageCallsInJsonResult,
  PLAINTEXT_V2_AGENT_MESSAGE_RESTORE_OVERFLOW_MESSAGE,
} from "../../responses/plaintext-v2-agent-messages";
import { createResponsesFieldBackfillBlockRewrite } from "./responses-field-backfill";
import { createResponsesFunctionToolRepairBlockRewrite } from "../responses-function-tool-repair";
import {
  createUndeclaredToolCallGuardBlockRewrite,
  currentTurnWireToolCatalogBody,
  undeclaredToolCallNameInResponse,
  undeclaredToolCallMessage,
  normalizeDefaultNamespaceInJson,
} from "../responses-undeclared-tool-guard";
import { isWin32EagerRewrite, selectEagerPath } from "../../lib/bun-stream-caps";

/**
 * Platform override for the two relay-path policy calls below. Tests only.
 *
 * The eager relay is reachable only on win32 and darwin, so a Linux shard cannot exercise it
 * without claiming to be one of them. Overwriting `process.platform` globally does that, and a
 * great deal more: every filesystem, ACL and state-directory decision in the process follows it,
 * and the spend-ledger owner lowercases its home on win32, which on a case-sensitive filesystem
 * names a DIFFERENT directory. A row that did that stopped being able to reserve its send and
 * delivered no terminal at all, reporting as a relay defect. This narrows the claim to the two
 * calls that actually choose the relay path.
 */
let relayPlatformForTests: NodeJS.Platform | undefined;

/** Internal test contract, not operator configuration: no config key reaches this. */
export function setRelayPlatformForTests(platform: NodeJS.Platform | undefined): void {
  relayPlatformForTests = platform;
}
import { linkAbortSignal, UPSTREAM_JSON_BODY_READ_OPTIONS } from "./core-lifetime";
import { registerTurn, unregisterTurn, trackStreamLifetime } from "../lifecycle";
import { relaySseEagerBounded } from "../relay-eager";
import { readBoundedResponseBody } from "../../lib/bounded-body";
import { idleDeadline } from "../../lib/abort";
import { resolveStallTimeoutMs } from "../../stall-timeout";
import { formatErrorResponse } from "../../bridge";
import {
  httpStatusFromTerminalError,
  inspectResponseLogJson,
  inspectResponseLogSsePayloadParsed,
} from "../request-log";
import { restoreRoutedCustomCallsInJson } from "../../responses/custom-tool-compat";
import { restoreRoutedToolSearchCallsInJson } from "../../responses/tool-search-compat";
import { responsesJsonToSseStream } from "../responses-json-events";
import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
import {
  bufferedResponsesReadOptions,
  collectBufferedResponsesSse,
  type BufferedResponsesSseFailure,
  type BufferedResponsesSseResult,
} from "./buffered-sse-json";

const PLAINTEXT_V2_SSE_PREFIX_LIMIT = 4096;

/** Replay retained SSE in small views so the rewrite decoder never receives one 32 MiB chunk. */
function replayBufferedSse(bytes: Uint8Array): ReadableStream<Uint8Array> {
  let offset = 0;
  return new ReadableStream({
    pull(controller) {
      if (offset >= bytes.byteLength) {
        controller.close();
        return;
      }
      const end = Math.min(bytes.byteLength, offset + 64 * 1024);
      controller.enqueue(bytes.subarray(offset, end));
      offset = end;
    },
  });
}

const BUFFERED_CONTEXT_ERROR_CODES = new Set([
  "context_length_exceeded", "context_window_exceeded", "input_too_long",
]);
const BUFFERED_QUOTA_ERROR_CODES = new Set([
  "usage_limit_exceeded", "usage_limit_reached", "rate_limit_exceeded", "insufficient_quota",
]);
const BUFFERED_OVERLOAD_ERROR_CODES = new Set(["server_is_overloaded"]);

function bufferedErrorDefaults(status: number): { type: string; code: string } {
  switch (status) {
    case 400: return { type: "invalid_request_error", code: "invalid_request_error" };
    case 401: return { type: "authentication_error", code: "invalid_api_key" };
    case 403: return { type: "permission_error", code: "permission_denied" };
    case 429: return { type: "rate_limit_error", code: "rate_limit_exceeded" };
    case 499: return { type: "client_closed_request", code: "client_closed_request" };
    case 503: return { type: "server_error", code: "server_is_overloaded" };
    default: return { type: "upstream_error", code: "upstream_server_error" };
  }
}

/** Preserve only explicit, recognized bare-error classes; diagnostic wording never sets status. */
function bufferedBareErrorPresentation(
  failure: BufferedResponsesSseFailure,
  message: string,
): { status: number; error: { type: string; code: string; message: string } } {
  if (failure.upstreamRefusalCode !== undefined) {
    return {
      status: 400,
      error: { type: "invalid_request_error", code: failure.upstreamRefusalCode, message },
    };
  }
  const explicitCode = failure.upstreamErrorCode;
  const status = explicitCode !== undefined
    ? BUFFERED_CONTEXT_ERROR_CODES.has(explicitCode) ? 400
      : BUFFERED_QUOTA_ERROR_CODES.has(explicitCode) ? 429
        : BUFFERED_OVERLOAD_ERROR_CODES.has(explicitCode) ? 503
        : httpStatusFromTerminalError({ code: explicitCode })
    : httpStatusFromTerminalError({ type: failure.upstreamErrorType });
  const defaults = bufferedErrorDefaults(status);
  if (status === 502) return { status, error: { ...defaults, message } };
  const explicitType = failure.upstreamErrorType;
  const typeMatchesStatus = explicitType !== undefined
    && (httpStatusFromTerminalError({ type: explicitType }) === status
      || (explicitType === "server_error" && status === 503));
  return {
    status,
    error: {
      type: typeMatchesStatus ? explicitType! : defaults.type,
      code: explicitCode ?? defaults.code,
      message,
    },
  };
}

/** Prefix-probe budget: bounds one silent gap and the whole probe alike. */
interface PlaintextV2SseProbeOptions {
  timeoutMs: number;
  signal?: AbortSignal;
}

function classifyPlaintextV2SsePrefix(prefix: string): "sse" | "unknown" | "more" {
  const lastLineEnd = prefix.lastIndexOf("\n");
  if (lastLineEnd < 0) return "more";
  for (const rawLine of prefix.slice(0, lastLineEnd + 1).split("\n")) {
    const line = rawLine.replace(/\r$/, "").trim();
    if (!line || line.startsWith(":")) continue;
    if (/^(id|retry):/.test(line)) continue;
    if (line.startsWith("event:")) {
      return /^event:\s*(?:response\.[\w.-]+|error)$/.test(line) ? "sse" : "unknown";
    }
    if (line.startsWith("data:")) {
      try {
        const value = JSON.parse(line.slice(5).trim()) as { type?: unknown };
        return typeof value.type === "string" && /^(?:response\.[\w.-]+|error)$/.test(value.type)
          ? "sse" : "unknown";
      } catch {
        return "unknown";
      }
    }
    return "unknown";
  }
  return "more";
}

/**
 * Confirm an unlabeled successful body is Responses SSE before alias restoration.
 *
 * The probe waits at most `timeoutMs` for a first recognized event, then hands the body to the
 * client with no deadline of its own: a stall in the prefix is a probe failure, and a stall after
 * it belongs to the delivered stream.
 */
async function classifyPlaintextV2SseResponse(
  response: Response,
  probe: PlaintextV2SseProbeOptions,
): Promise<Response> {
  if (!response.body) return response;
  const reader = response.body.getReader();
  // A non-conforming stream can throw synchronously from cancel(); neither that nor a
  // rejected cancel may escape past the probe's own deadline.
  const cancelReader = (reason?: unknown): void => {
    try {
      void reader.cancel(reason).catch(() => undefined);
    } catch {
      // Some stream implementations throw synchronously from cancel().
    }
  };
  const unrecognized = (): Response => new Response(null, {
    status: response.status,
    statusText: response.statusText,
    headers: response.headers,
  });
  const { timeoutMs, signal } = probe;
  const stalled = new DOMException("Plaintext V2 SSE prefix probe stalled", "TimeoutError");
  let rejectProbe: ((reason: unknown) => void) | undefined;
  const failed = new Promise<never>((_resolve, reject) => { rejectProbe = reject; });
  // The race below always observes this rejection; this covers a deadline that fires after the
  // race already settled with a chunk, which would otherwise be an unhandled rejection.
  void failed.catch(() => undefined);
  const inactivity = idleDeadline(timeoutMs, () => rejectProbe?.(stalled));
  // A drip-fed body can restart the inactivity window forever, so the probe also carries one
  // total budget that starts when the probe begins.
  const totalTimer = timeoutMs > 0 ? setTimeout(() => rejectProbe?.(stalled), timeoutMs) : undefined;
  const onAbort = (): void => rejectProbe?.(signal?.reason);
  signal?.addEventListener("abort", onAbort, { once: true });
  if (signal?.aborted) onAbort();
  const decoder = new TextDecoder();
  const buffered: Uint8Array[] = [];
  let prefix = "";
  let inspectedBytes = 0;
  try {
    while (inspectedBytes < PLAINTEXT_V2_SSE_PREFIX_LIMIT) {
      if (signal?.aborted) throw signal.reason;
      // Armed for every read, so a chunk that arrives restarts the window at the next iteration.
      inactivity.reset();
      const read = reader.read();
      // Observe a late read rejection when the deadline or the client wins the race.
      void read.catch(() => undefined);
      const next = await Promise.race([read, failed]);
      if (signal?.aborted) throw signal.reason;
      if (next.done) break;
      buffered.push(next.value);
      const inspected = next.value.subarray(0, PLAINTEXT_V2_SSE_PREFIX_LIMIT - inspectedBytes);
      inspectedBytes += inspected.byteLength;
      prefix += decoder.decode(inspected, { stream: true });
      const kind = classifyPlaintextV2SsePrefix(prefix);
      if (kind === "sse") {
        let bufferedIndex = 0;
        const body = new ReadableStream<Uint8Array>({
          async pull(controller) {
            if (bufferedIndex < buffered.length) {
              controller.enqueue(buffered[bufferedIndex++]!);
              return;
            }
            try {
              const result = await reader.read();
              if (result.done) controller.close();
              else controller.enqueue(result.value);
            } catch (error) {
              controller.error(error);
            }
          },
          cancel(reason) { return reader.cancel(reason); },
        });
        const headers = new Headers(response.headers);
        headers.set("content-type", "text/event-stream");
        return new Response(body, { status: response.status, statusText: response.statusText, headers });
      }
      if (kind === "unknown") break;
    }
  } catch (error) {
    // Timeout, client abort, or a failed read fails closed through the unrecognized-body exit,
    // which the caller already answers as the unsupported-content-type 502.
    cancelReader(error);
    return unrecognized();
  } finally {
    inactivity.cancel();
    if (totalTimer !== undefined) clearTimeout(totalTimer);
    signal?.removeEventListener("abort", onAbort);
  }
  cancelReader();
  return unrecognized();
}

/** One responsibility of the Responses request pipeline; state owners are explicit. */
export async function deliverPassthroughResponse(
  requestContext: Pick<ResponsesRequestContext, "logCtx" | "config" | "options" | "req">,
  admissionState: ResponsesAdmissionState,
  requestState: Pick<
    PreparedResponsesRequest,
    | "parsed"
    | "route"
    | "subagentQuotaFailureModel"
    | "subagentFallbackAccountId"
    | "clientRequestedStream"
    | "translatorBudget"
  >,
  transportState: Pick<ResponsesTransport, "requestBindings">,
  sidecarState: Pick<ResponsesSidecarAuth, "openAiSidecar">,
  responseEffects: Pick<
    ResponsesEffects,
    | "plaintextV2AgentMessageToolNames"
    | "commitReasoningReplayServingRoute"
    | "routedMuseToolNameAliases"
    | "routedNamespaceToolAliases"
    | "plaintextV2AgentMessageAliasedToolNames"
    | "recordTerminalOutcomes"
    | "responseCompletionCancelled"
  >,
  nativeExchange: Pick<
    PassthroughExchange,
    | "upstreamResponse"
    | "codexSafetyBufferingOptions"
    | "upstream"
    | "request"
    | "connectMs"
    | "imageGenCallAliases"
    | "selfNamedNamespaceScrubAuthorization"
    | "authorizedBareNamespaceToolAliases"
    | "rememberPassthroughResponseChecked"
    | "routedCustomToolNames"
    | "routedCustomToolRepairNames"
    | "declaredWireToolNames"
    | "routedToolSearchNames"
    | "outboundRequestBody"
    | "functionRepairSchemas"
    | "undeclaredToolGuardActive"
    | "declaredNamelessClientCallTypes"
    | "providerExecutedCallTypes"
    | "declaredBareWireToolNames"
    | "recoverableBareCustomWireToolNames"
    | "rememberPassthroughResponse"
    | "noteInspectedPayload"
    | "normalizeFunctionCompletionJson"
    | "localUpstream"
  >,
): Promise<Response> {
  const { logCtx, config, options, req } = requestContext;
  const {
    codexSafetyBufferingOptions,
    upstream,
    connectMs,
    imageGenCallAliases,
    selfNamedNamespaceScrubAuthorization,
    authorizedBareNamespaceToolAliases,
    rememberPassthroughResponseChecked,
    routedCustomToolNames,
    routedCustomToolRepairNames,
    declaredWireToolNames,
    routedToolSearchNames,
    functionRepairSchemas,
    declaredNamelessClientCallTypes,
    providerExecutedCallTypes,
    declaredBareWireToolNames,
    recoverableBareCustomWireToolNames,
    rememberPassthroughResponse,
    noteInspectedPayload,
    normalizeFunctionCompletionJson,
  } = nativeExchange;
  const { commitReasoningReplayServingRoute, recordTerminalOutcomes } = responseEffects;
  const { parsed, route, subagentQuotaFailureModel, clientRequestedStream, translatorBudget } = requestState;
  const { openAiSidecar } = sidecarState;
  const { requestBindings } = transportState;

  let upstreamResponse = nativeExchange.upstreamResponse;
  const canonicalBufferedJson = clientRequestedStream !== true
    && isCanonicalOpenAiForwardProvider(route.provider);
  const originalContentType = upstreamResponse.headers.get("content-type");
  if (isUsageDebugEnabled() && originalContentType) logCtx.usageDebugContentType = originalContentType;
  if (responseEffects.plaintextV2AgentMessageToolNames.size > 0
    && upstreamResponse.ok && upstreamResponse.body && (parsed.stream || canonicalBufferedJson)
    && !originalContentType?.toLowerCase().includes("text/event-stream")
    && !originalContentType?.toLowerCase().includes("application/json")
    && !isCodexWsUpstreamResponse(upstreamResponse)
    && !(options.nativeControl && isNativeControlResponse(upstreamResponse))) {
    upstreamResponse = await classifyPlaintextV2SseResponse(upstreamResponse, {
      timeoutMs: resolveStallTimeoutMs(config.stallTimeoutSec, { localUpstream: nativeExchange.localUpstream }),
      signal: options.abortSignal ?? req.signal,
    });
  }

    const headers = sanitizePassthroughHeaders(upstreamResponse.headers, codexSafetyBufferingOptions);
    const resolvedModel = headers.get("openai-model")?.trim();
    if (resolvedModel) {
      logCtx.servedModel = resolvedModel;
      if (!logCtx.preserveResolvedModelFromRoute) logCtx.resolvedModel = resolvedModel;
    }
    // ChatGPT may omit Content-Type on SSE responses. Plaintext V2 responses
    // reach this fallback only after their first Responses event is confirmed.
    const passthroughCt = headers.get("content-type")?.toLowerCase();
    const isEventStream = passthroughCt?.includes("text/event-stream")
      || (responseEffects.plaintextV2AgentMessageToolNames.size === 0
        && upstreamResponse.ok
        && !!upstreamResponse.body
        && !passthroughCt
        && (parsed.stream || canonicalBufferedJson));
    const recordTerminalOutcome = codexForwardTerminalOutcomeRecorder(
      config,
      admissionState.authCtx,
      route.provider,
      route.modelId,
      logCtx,
    );
    let terminalOutcomeRecorded = false;
    const terminalRecorder = recordTerminalOutcome
      ? (status: ResponsesTerminalStatus, httpStatusOverride?: number): void => {
        if (terminalOutcomeRecorded) return;
        terminalOutcomeRecorded = true;
        recordTerminalOutcome(status, httpStatusOverride);
      }
      : undefined;
    const terminalBodyWillRecord = !!terminalRecorder && upstreamResponse.ok && isEventStream;
    // Capture quota from upstream response for multi-account tracking
   if (usesCodexForwardPoolAuth(admissionState.authCtx, route.provider)) {
      // primary was the 5h window; it now carries weekly data for GPT plans.
      // Prefer primary when present, fall back to secondary for compatibility.
      const quotaMeta = { ...codexQuotaOutcomeMeta(upstreamResponse), ...(await codexDenialOutcomeMeta(upstreamResponse)) };
      const { applyAccountQuotaFromUpstreamHeaders } = await import("../../codex/auth-api");
      if (!isCodexWsQuotaObservedResponse(upstreamResponse)) {
        applyAccountQuotaFromUpstreamHeaders(admissionState.authCtx.accountId, upstreamResponse.headers,
          admissionState.authCtx.writerGeneration, admissionState.authCtx.kind === "main-pool" ? admissionState.authCtx.mainQuotaWriter : undefined,
          { modelId: route.modelId, poolWriter: admissionState.authCtx.kind === "pool" ? admissionState.authCtx.poolQuotaWriter : undefined,
            poolResponse: admissionState.authCtx.kind === "pool" });
      }
      if (terminalBodyWillRecord) {
        options.setTerminalOutcomeRecorder?.((status, httpStatusOverride) => {
          terminalRecorder(status, httpStatusOverride);
          if (status === "failed" || status === "incomplete") {
            const quotaFailureMessage = [httpStatusOverride, logCtx.terminalHttpStatus]
              .find(value => value === 429 || value === 402);
            if (!isFixedCodexAccount(admissionState.authCtx) && quotaFailureMessage !== undefined) {
              recordSubagentQuotaFailureForThreadSpawn(
                req.headers,
                subagentQuotaFailureModel,
                quotaFailureMessage,
                config,
                requestState.subagentFallbackAccountId,
              );
            }
          }
          options.onNativePassthroughTerminal?.(status);
        });
      } else if (!shouldDeferCodexResetDerivedCooldown(
        upstreamResponse,
        options.deferCodexResetDerivedCooldown,
      ) && !isReplayRefusalResponse(upstreamResponse)) {
        // A refusal this proxy made is not evidence about the account. Recording it would
        // classify the synthetic 429 as quota exhaustion and write a default cooldown against
        // a credential the request may never have reached, and that false signal outlives the
        // request. The sibling recorders on this path already decline: the terminal recorder
        // needs an ok streaming body, and the quota-header snapshot finds no quota headers.
        recordCodexUpstreamOutcome(config, admissionState.authCtx.accountId, upstreamResponse.status, {
          ...quotaMeta,
          threadId: admissionState.authCtx.affinityKey,
          fixedAccount: admissionState.authCtx.fixedAccount,
          modelId: route.modelId,
          probeLeaseId: codexProbeLeaseId(admissionState.authCtx),
          probeQuotaScope: codexProbeQuotaScope(admissionState.authCtx),
          transientProbe: codexTransientProbeGrant(admissionState.authCtx),
          writerGeneration: admissionState.authCtx.writerGeneration,
          // Includes a replay's second 401, which is the case that actually retires the
          // account — fence it on the credential the request was holding.
          ...(admissionState.authCtx.kind === "pool" ? { credentialGeneration: admissionState.authCtx.generation } : {}),
        });
      }
    }

    // Non-2xx passthrough failures must never reach Codex as an empty body —
    // Codex renders that as the opaque "Unknown error" (#452). Combo attempts
    // keep their typed failure envelope. Except for the classified 413 below,
    // non-empty bodies are relayed verbatim
    // (headers included) so pool-retry Activation B/D and client diagnostics stay intact.
    // Manual-redirect policy (#914): a 3xx is relayed as-is (Location preserved
    // through sanitizePassthroughHeaders) so a redirect to a dead host can never
    // masquerade as a pre-connection failure after the credential was seen.
    // The numeric outcome above already classified it neutral — no streak.
    if (upstreamResponse.status >= 300 && upstreamResponse.status < 400) {
      return new Response(upstreamResponse.body, {
        status: upstreamResponse.status,
        statusText: upstreamResponse.statusText,
        headers: sanitizePassthroughHeaders(upstreamResponse.headers, codexSafetyBufferingOptions),
      });
    }
    if (!upstreamResponse.ok) {
      if (options.comboAttempt) {
        // No pre-read guard here: `consumeComboFailure` -> `readBoundedResponseBody` reads
        // `response.body` itself and already threads the abort signal through its own read,
        // and the combo contract is that this body's getter is touched exactly once (pinned by
        // "captures passthrough failed usage from its original bounded body exactly once").
        // Attaching a guard would be a second `.body` access and break that contract for no
        // gain, since the bounded reader owns settlement on this path.
        const failure = await consumeComboFailure(upstreamResponse, options.abortSignal);
        options.onConsumedComboFailure?.(failure);
        return failure.response;
      }
      // The bounded reader owns the original body, deadline, abort settlement, and lock.
      // Unsafe partial data falls back to #452's non-empty status-only JSON.
      const errorText = await readDisplaySafeErrorText(upstreamResponse, upstream.signal, "");
      if (upstreamResponse.status === 413) {
        return clientRequestedStream
          ? streamingContextOverflowResponse(parsed._responseModelId ?? parsed.modelId, translatorBudget)
          : jsonContextOverflowResponse();
      }
      const policyRefusal = rewriteUpstreamPolicyRefusal({
        status: upstreamResponse.status,
        errorText,
        stream: clientRequestedStream,
        modelId: parsed._responseModelId ?? parsed.modelId,
        destinationIsXai: isXaiResponsesDestination(route.provider),
        translatorBudget,
        turnAdmissionLease: options.turnAdmissionLease,
      });
      if (policyRefusal) return policyRefusal;
      return formatPassthroughUpstreamError(upstreamResponse.status, errorText, {
        statusText: upstreamResponse.statusText,
        headers,
        // Provenance, not inference: `errorText` is empty when the bounded read finds nothing
        // display-safe, and an empty body is exactly what the retryable-429 default fires on.
        replayRefusal: isReplayRefusalResponse(upstreamResponse),
      });
    }

    if (options.nativeControl && isNativeControlResponse(upstreamResponse) && upstreamResponse.body) {
      // A native chain carries several response terminals. Ordinary SSE repair,
      // cancellation-on-terminal and local previous-response replay are single-response
      // contracts and would truncate it. Keep the bounded upstream as the sole reader.
      options.nativeControl.relayActive = true;
      commitReasoningReplayServingRoute(nativeExchange.request.headers);
      const body = trackStreamLifetime(upstreamResponse.body, upstream, undefined, options.turnAdmissionLease);
      return new Response(body, { status: upstreamResponse.status, headers });
    }

    // Bun#32111 workaround: passthrough SSE uses tee()+native relay to avoid the
    // async-pull segfault on Windows. Branch[0] goes directly to the Response (Bun
    // native relay, never enters JS Sink.write); branch[1] is consumed in the
    // background for terminal-outcome/quota inspection only.
    // #314 alternative shape: win32 no-rewrite traffic follows the runtime/config
    // gate; darwin no-rewrite traffic joins it only for explicit
    // `streamMode: "eager-relay"` opt-in. Darwin `auto` always stays tee. The
    // eager shape skips tee and uses one bounded reader with inline inspection
    // (src/server/relay-eager.ts; policy:
    // devlog/_fin/260731_macos_rss_retention/100_darwin_eager_optin.md).
    // The bundled known-bad runtime remains on tee by default on both platforms.
    const grokUpstreamEchoEnabled = isXaiResponsesDestination(route.provider)
      && responsesRequestMayReplayToolOutput(parsed._rawBody);
    if (isEventStream && upstreamResponse.body) {
      // Streaming clients commit the serving route once the upstream accepted the turn; retaining
      // request state until their body ends would change the existing relay contract. The canonical
      // non-streaming fold below is different: nothing is published yet, so it defers this mutation
      // until both the raw and rewritten terminal snapshots validate.
      if (!canonicalBufferedJson) {
        commitReasoningReplayServingRoute(nativeExchange.request.headers);
      }
      const terminalRepairPolicy = route.staticPolicy.model.responsesTerminalRepair;
      // #3761: opt-in hosted-web-search bridge. Codex always declares the hosted web_search tool,
      // and this branch relays that declaration on the assumption the destination executes it.
      // A KEY-auth gateway that does not (Ollama Cloud GLM) answers with a function_call named
      // web_search that nothing runs, and the undeclared-tool guard below ends the turn. When the
      // provider opts in, the bridge intercepts that one call, runs the search, continues the
      // conversation upstream, and hands back ordinary Responses SSE — so every rewrite below,
      // including the guard itself, still inspects the client-facing stream. Default OFF: without
      // the opt-in this is one planner call and the relay is byte-identical to before.
      const webSearchBridgeAuth = resolvePassthroughWebSearchBridgeAuth(
        route.provider.webSearchBridge?.backend,
        config,
        openAiSidecar,
      );
      const webSearchBridgePlan = planPassthroughWebSearchBridge(parsed, route.provider, {
        providerName: route.providerName,
        isPassthrough: true,
        stream: parsed.stream === true,
        auth: webSearchBridgeAuth,
      });
      // Capture the binding that actually served the first leg, after its permitted reselection.
      const webSearchBridgeBinding = requestBindings.get(nativeExchange.request);
      // Repair must observe the raw first leg before the bridge suppresses an intercepted search
      // lifecycle. Otherwise a provider that leaves that complete call open never arms repair's
      // grace timer, so the bridge cannot execute the search or begin its continuation.
      let passthroughSseBody = terminalRepairPolicy
        ? relayResponsesSseWithTerminalRepair(
          upstreamResponse.body,
          upstream,
          terminalRepairPolicy,
          translatorBudget,
          options.responsesTerminalRepairScheduler,
        )
        : upstreamResponse.body;
      passthroughSseBody = webSearchBridgePlan
        ? createPassthroughWebSearchBridgeStream({
          plan: webSearchBridgePlan,
          firstLeg: passthroughSseBody,
          requestBody: nativeExchange.request.body,
          // Continuation legs replay the same built request with the executed search appended.
          // The first leg already passed the recovery ladder, the outbound size ceiling, and the
          // host circuit; a KEY-auth destination has no OAuth refresh to replay on a later leg.
          send: async (continuationBody: string) => {
            const continuation = await fetchWithHeaderTimeout(
              nativeExchange.request.url,
              { method: nativeExchange.request.method, headers: nativeExchange.request.headers, body: continuationBody },
              upstream.signal,
              connectMs,
              true,
              providerFetch(route.provider, options.codexWsRuntimeIdentity, {
                // Pacing can outlive a manual selection change. A continuation must retain the
                // first leg's key and appended search result, never rebuild from the original turn.
                beforeDispatch: () => {
                  if (webSearchBridgeBinding?.kind !== "api-key"
                    || !providerApiKeySelectionIsCurrent(config, route.providerName, webSearchBridgeBinding.provider)) {
                    throw new Error("API key selection changed during a web-search continuation");
                  }
                },
                providerName: route.providerName,
                modelId: route.modelId,
              }),
              false,
            );
            // The same provider can leave a complete continuation open without a terminal, which
            // stalls the bridge's decide loop exactly like the first leg — so every leg gets the
            // same repair, not only the intercepted first one.
            if (!terminalRepairPolicy || !continuation.ok || !continuation.body) return continuation;
            return new Response(
              relayResponsesSseWithTerminalRepair(
                continuation.body,
                upstream,
                terminalRepairPolicy,
                translatorBudget,
                options.responsesTerminalRepairScheduler,
              ),
              continuation,
            );
          },
          execute: createPassthroughWebSearchBridgeExecutor(webSearchBridgePlan, {
            providerApiKey: route.provider.apiKey ?? "",
            auth: webSearchBridgeAuth,
            hostedTool: parsed._webSearch,
            describeImages: requiresVisionPreprocessing(config, route.provider, route.modelId, route.providerName),
            sidecar: config.webSearchSidecar,
          }),
          // Snapshot the bound conversation, provider, model, destination, and credential. The
          // next turn must match every dimension before its hosted cell can recover this result.
          destinationScope: bridgeSearchReplayScope(parsed._reasoningReplayScope),
          // Appending a search result can push the continuation past the ceiling the first leg
          // was admitted under, so the same limit is re-applied before every later send.
          checkOutboundBody: (continuationBody: string) => {
            const result = checkOutboundBodySize(continuationBody, config.maxUpstreamBodyBytes);
            return result.admitted ? undefined : describeOutboundBodyRefusal(result);
          },
          // Resolution can acquire the account's sole cooldown-recovery probe before the routed
          // provider reveals whether it will request search. Hand an unused lease back on every
          // terminal path; after an executed search, the outcome recorder has already settled it.
          onFinalize: () => releaseCodexAuthContextProbeLease(openAiSidecar?.authContext),
          signal: upstream.signal,
        })
        : passthroughSseBody;
      const repairConfig = route.provider.responsesItemIdRepair;
      // Grok Build renders deltas live but reconstructs its durable assistant
      // turn from the completed response snapshot. Native Responses streams
      // may instead carry the complete items in output_item.done, so the
      // explicit Grok compatibility marker enables strict client compatibility rewrites.
      // The provider's broader snapshot/lifecycle repair remains opt-in.
      const grokClientCompatibilityEnabled = logCtx.surface === "grok";
      const snapshotRepairEnabled = hasResponsesSnapshotRepair(route.provider.responsesSnapshotRepair);
      const githubCopilotRepairEnabled = route.providerName === "github-copilot";
      const responseModelRewrite = parsed._responseModelId !== undefined
        && parsed._responseModelId !== parsed.modelId
        ? createResponsesModelPayloadRewrite(parsed._responseModelId)
        : undefined;
      // Compose opt-in payload rewrites into one parse/stringify pass (image-gen restore first).
      const payloadRewrites = [
        createImageGenCallRestoreRewrite(imageGenCallAliases),
        // #3217: a call whose namespace repeats its own name is unroutable in codex-rs.
        createSelfNamedToolCallNamespaceScrubRewrite(selfNamedNamespaceScrubAuthorization),
        responseEffects.routedMuseToolNameAliases.size > 0
          ? createMuseToolNameRestoreRewrite(responseEffects.routedMuseToolNameAliases)
          : undefined,
        responseEffects.routedNamespaceToolAliases.size > 0
          ? createRoutedNamespaceCallRestoreRewrite(responseEffects.routedNamespaceToolAliases)
          : undefined,
        authorizedBareNamespaceToolAliases.size > 0
          ? createRoutedNamespaceCallRestoreRewrite(authorizedBareNamespaceToolAliases)
          : undefined,
        hasResponsesItemIdRepair(repairConfig)
          ? createResponsesItemIdPayloadRewrite(repairConfig!, translatorBudget)
          : undefined,
        responseModelRewrite,
      ].filter((rewrite): rewrite is NonNullable<typeof rewrite> => rewrite !== undefined);
      // #893: sparse-snapshot gateways get field backfills AND lifecycle event
      // injection at the block level, after payload rewrites. Defaults come
      // from the finalized OUTBOUND body — the normalized internal tool shapes
      // are not the Responses wire shapes the snapshot must mirror.
      // Only validated client blocks may publish plaintext continuation state.
      // Raw inspection precedes rewriting on eager relays, so it cannot own this write.
      const plaintextInspector = !canonicalBufferedJson
        && !grokUpstreamEchoEnabled
        && responseEffects.plaintextV2AgentMessageToolNames.size > 0
        ? createSseInspector({ onCompletedResponse: rememberPassthroughResponseChecked })
        : undefined;
      const plaintextEncoder = plaintextInspector ? new TextEncoder() : undefined;
      const rememberPlaintextBlock = plaintextInspector
        ? Object.assign((block: string): readonly string[] => {
          plaintextInspector.feed(plaintextEncoder!.encode(`${block}\n\n`));
          return [block];
        }, { dispose: () => plaintextInspector.dispose() })
        : undefined;
      const maskCredential = createOutboundCredentialMask(nativeExchange.request.headers);
      const blockRewrites = [
        payloadRewrites.length > 0
          ? payloadRewriteAsBlockRewrite(composeSsePayloadRewrites(...payloadRewrites))
          : undefined,
        routedCustomToolNames.size > 0 || routedCustomToolRepairNames.size > 0
          ? createRoutedCustomToolRestoreBlockRewrite(
            routedCustomToolNames,
            translatorBudget,
            routedCustomToolRepairNames,
            declaredWireToolNames,
          )
          : undefined,
        routedToolSearchNames.size > 0
          ? createRoutedToolSearchRestoreBlockRewrite(routedToolSearchNames, translatorBudget)
          : undefined,
        githubCopilotRepairEnabled
          ? createGithubCopilotResponsesBlockRewrite(translatorBudget)
          : undefined,
        grokClientCompatibilityEnabled
          ? createGrokResponsesControlFrameBlockRewrite()
          : undefined,
        grokClientCompatibilityEnabled
          ? createGrokResponsesTimestampBlockRewrite()
          : undefined,
        grokClientCompatibilityEnabled
          ? createGrokResponsesSparseTerminalBlockRewrite(
            translatorBudget,
            nativeExchange.outboundRequestBody,
            {
              clientToolAuthorizationBody: currentTurnWireToolCatalogBody(
                parsed._rawBody,
                parsed._replayPrefixLen ?? 0,
              ),
              routedNamespaceToolAliases: responseEffects.routedNamespaceToolAliases,
              routedMuseToolNameAliases: responseEffects.routedMuseToolNameAliases,
              convertedRoutedCustomToolNames: routedCustomToolNames,
            },
          )
          : undefined,
        snapshotRepairEnabled
          ? createResponsesSnapshotBlockRewrite(nativeExchange.outboundRequestBody, translatorBudget)
          : undefined,
        responseEffects.plaintextV2AgentMessageToolNames.size > 0
          ? payloadRewriteAsBlockRewrite(createPlaintextV2AgentMessageCallRestoreRewrite(
            responseEffects.plaintextV2AgentMessageToolNames, responseEffects.plaintextV2AgentMessageAliasedToolNames,
          ))
          : undefined,
        createResponsesFieldBackfillBlockRewrite(),
        functionRepairSchemas.size > 0
          ? createResponsesFunctionToolRepairBlockRewrite(functionRepairSchemas, translatorBudget)
          : undefined,
        // Last: every rewrite above can still rename or reshape a call item, so the guard must
        // compare the names the client will actually receive against the declared catalog.
        nativeExchange.undeclaredToolGuardActive
          ? createUndeclaredToolCallGuardBlockRewrite(
            declaredWireToolNames,
            declaredNamelessClientCallTypes,
            providerExecutedCallTypes,
            declaredBareWireToolNames,
            recoverableBareCustomWireToolNames,
          )
          : undefined,
        grokUpstreamEchoEnabled
          ? createGrokUpstreamEnvelopeEchoBlockRewrite(
            rememberPassthroughResponse ? rememberPassthroughResponseChecked : undefined,
          )
          : undefined,
        createTerminalErrorRedactionBlockRewrite(nativeExchange.request.headers, maskCredential),
        rememberPlaintextBlock,
      ].filter((rewrite): rewrite is NonNullable<typeof rewrite> => rewrite !== undefined);
      const clientBlockRewrite = blockRewrites.length > 0
        ? composeSseBlockRewrites(...blockRewrites)
        : undefined;
      const needsClientRewrite = clientBlockRewrite !== undefined;

      if (canonicalBufferedJson) {
        const signal = options.abortSignal ?? req.signal;
        const bufferedRead = bufferedResponsesReadOptions(resolveStallTimeoutMs(
          config.stallTimeoutSec,
          { localUpstream: nativeExchange.localUpstream },
        ));
        const failBufferedTurn = (
          message: string,
          failure?: BufferedResponsesSseFailure,
        ): Response => {
          upstream.abort(new Error(message));
          const upstreamError = failure?.upstreamError;
          const upstreamRefusalCode = failure?.upstreamRefusalCode;
          const rawPresentation = upstreamError === undefined || failure === undefined
            ? undefined
            : bufferedBareErrorPresentation(failure, upstreamError);
          const presentation = rawPresentation === undefined ? undefined : {
            status: rawPresentation.status,
            error: {
              type: maskCredential(rawPresentation.error.type),
              code: maskCredential(rawPresentation.error.code),
              message: maskCredential(rawPresentation.error.message),
            },
          };
          if (upstreamError !== undefined) {
            // The streaming relay turns a bare `error` event into a terminal failure. Mirror that
            // verdict for JSON callers before recording/formatting it, or a provider refusal is
            // misreported as a retryable generic 502 and clients can replay a rejected turn.
            const error = presentation!.error;
            const terminalPayload = {
              type: "response.failed",
              response: { status: "failed", error, last_error: error },
            };
            // Classification comes only from the bounded structured type/code above. A bare
            // transport reset can contain misleading copy such as "invalid api key"; letting the
            // log's message fallback reinterpret it would retire a healthy credential.
            logCtx.terminalHttpStatus = presentation!.status;
            noteInspectedPayload(terminalPayload);
            inspectResponseLogSsePayloadParsed(
              logCtx,
              JSON.stringify(terminalPayload),
              terminalPayload,
            );
          }
          const failureStatus = logCtx.terminalHttpStatus ?? 502;
          if (recordTerminalOutcomes) {
            logCtx.transportPhase = "mid_stream";
            logCtx.terminalSource = "synthetic";
            if (logCtx.activeAttempt) logCtx.activeAttempt.streamAborted = true;
            terminalRecorder?.("failed", failureStatus);
            options.onNativePassthroughTerminal?.("failed");
          }
          if (upstreamError !== undefined) {
            const failureHeaders = new Headers(headers);
            failureHeaders.set("content-type", "application/json");
            failureHeaders.delete("content-length");
            failureHeaders.delete("content-encoding");
            if (upstreamRefusalCode !== undefined) failureHeaders.delete("retry-after");
            const error = presentation!.error;
            return formatPassthroughUpstreamError(
              failureStatus,
              JSON.stringify({ error, ...(upstreamRefusalCode === undefined ? {} : { retryable: false }) }),
              {
                headers: failureHeaders,
                suppressRetryAfter: upstreamRefusalCode !== undefined,
              },
            );
          }
          return formatErrorResponse(502, "upstream_error", message);
        };
        let raw: BufferedResponsesSseResult | undefined = await collectBufferedResponsesSse(
          passthroughSseBody,
          upstream,
          { signal, terminalBoundary: codexSafetyBufferingOptions, read: bufferedRead, retainTranscript: true },
        );
        if (!raw.ok) {
          if (raw.kind === "aborted" || signal.aborted) {
            responseEffects.responseCompletionCancelled = true;
            options.onNativePassthroughCancel?.();
            return clientCancelledResponse();
          }
          const message = raw.kind === "oversized"
            ? "upstream SSE response exceeded the safe body limit"
            : raw.kind === "timeout"
              ? "upstream SSE response stalled before completing"
              : raw.kind === "malformed" || raw.kind === "missing_terminal"
                ? "upstream SSE response ended without one valid terminal response"
                : "upstream SSE response failed before a valid terminal response";
          return failBufferedTurn(message, raw);
        }
        if (!raw.bytes) return failBufferedTurn("upstream SSE transcript was not retained for rewriting");
        let rawBytes: Uint8Array | undefined = raw.bytes;
        raw = undefined; // Release the raw reconstruction graph before building the client copy.

        // Reuse the ordinary client rewrite chain against the bounded transcript. The raw pass
        // above validates before any continuation or outcome side effect; this second validation
        // means a rewrite failure cannot publish a turn the non-streaming caller never received.
        let bufferedClientBody: ReadableStream<Uint8Array> | undefined = clientBlockRewrite
          ? relaySseWithBlockRewrite(
            replayBufferedSse(rawBytes),
            clientBlockRewrite,
            translatorBudget,
          )
          : replayBufferedSse(rawBytes);
        const client = await collectBufferedResponsesSse(bufferedClientBody, upstream, {
          signal,
          read: bufferedRead,
          retainTranscript: false,
        });
        bufferedClientBody = undefined;
        if (!client.ok) {
          if (client.kind === "aborted" || signal.aborted) {
            responseEffects.responseCompletionCancelled = true;
            options.onNativePassthroughCancel?.();
            return clientCancelledResponse();
          }
          const message = client.kind === "oversized"
            ? "rewritten SSE response exceeded the safe body limit"
            : client.kind === "timeout"
              ? "rewritten SSE response stalled before completing"
              : "rewritten SSE response did not contain one valid terminal response";
          return failBufferedTurn(message, client);
        }
        if (Date.now() >= bufferedRead.deadlineAt) {
          return failBufferedTurn("buffered Responses turn exceeded the safe total deadline");
        }

        const cancelAfterValidation = (): Response => {
          responseEffects.responseCompletionCancelled = true;
          options.onNativePassthroughCancel?.();
          return clientCancelledResponse();
        };
        if (signal.aborted) return cancelAfterValidation();

        // Effects intentionally run only after both bounded validations. They inspect the same
        // upstream-facing transcript as the streaming relay and fire once; continuation storage
        // receives the final client-visible response once after all restorations succeeded.
        const reportNativeTerminal = recordTerminalOutcomes
          ? (status: ResponsesTerminalStatus, httpStatusOverride?: number) => {
            if (signal.aborted) return;
            terminalRecorder?.(status, httpStatusOverride);
            if (status === "failed" || status === "incomplete") {
              const quotaFailureMessage = [httpStatusOverride, logCtx.terminalHttpStatus]
                .find(value => value === 429 || value === 402);
              if (!isFixedCodexAccount(admissionState.authCtx) && quotaFailureMessage !== undefined) {
                recordSubagentQuotaFailureForThreadSpawn(
                  req.headers,
                  subagentQuotaFailureModel,
                  quotaFailureMessage,
                  config,
                  requestState.subagentFallbackAccountId,
                );
              }
            }
            options.onNativePassthroughTerminal?.(status);
          }
          : undefined;
        const effectInspector = createSseInspector({
          onTerminal: reportNativeTerminal,
          logCtx,
          onParsedPayload: noteInspectedPayload,
          onFirstOutput: options.onFirstOutput,
          pinCompletedResponseIdToFirstSeen: githubCopilotRepairEnabled,
        });
        try {
          // The deferred effects pass must not turn a bounded 32 MiB transcript into one long
          // event-loop monopoly. Keep decoder input small and yield between MiB groups; the
          // aggregate frame cap was already enforced by both validation passes.
          for (let offset = 0; offset < rawBytes.byteLength; offset += 64 * 1024) {
            if (signal.aborted) return cancelAfterValidation();
            effectInspector.feed(rawBytes.subarray(offset, Math.min(rawBytes.byteLength, offset + 64 * 1024)));
            if (offset > 0 && offset % (1024 * 1024) === 0) {
              await new Promise<void>(resolve => setTimeout(resolve, 0));
              if (signal.aborted) return cancelAfterValidation();
            }
          }
          if (signal.aborted) return cancelAfterValidation();
          effectInspector.finish();
        } finally {
          effectInspector.dispose();
        }
        if (signal.aborted) return cancelAfterValidation();
        commitReasoningReplayServingRoute(nativeExchange.request.headers);
        rawBytes = undefined;
        if (client.terminal.status === "completed") {
          rememberPassthroughResponseChecked(client.terminal.response);
        }

        const jsonHeaders = sanitizePassthroughHeaders(headers, codexSafetyBufferingOptions);
        jsonHeaders.set("content-type", "application/json");
        return markPreinspectedJsonResponse(new Response(JSON.stringify(client.terminal.response), {
          status: upstreamResponse.status,
          statusText: upstreamResponse.statusText,
          headers: jsonHeaders,
        }));
      }

      const relayPlatform = relayPlatformForTests ?? process.platform;
      // #864: win32 rewrite traffic must never enter the tee()+JS-pull chain
      // (Bun#32111 JS-sink segfault — text frames pass, the terminal block is
      // lost). The eager single reader applies the same rewrites inline.
      const win32EagerRewrite = isWin32EagerRewrite(relayPlatform, needsClientRewrite);
      const eagerPath = selectEagerPath(
        relayPlatform,
        needsClientRewrite,
        config.streamMode ?? "auto",
      );
      // A successful Codex WS upgrade is a push source. If it entered tee(),
      // the inspection branch could drain continuously while the slow client
      // branch retained bytes without a bound. Force the existing bounded,
      // single-reader relay before tee; HTTP fallback responses stay unmarked.
      const forceCodexWsEagerRelay = isCodexWsUpstreamResponse(upstreamResponse);
      const inlineEagerRewrite = needsClientRewrite
        && (forceCodexWsEagerRelay || win32EagerRewrite || eagerPath?.useEagerRelay === true);
      if (forceCodexWsEagerRelay || eagerPath?.useEagerRelay || win32EagerRewrite) {
        const turnAc = new AbortController();
        linkAbortSignal(upstream, turnAc.signal);
        registerTurn(turnAc, options.turnAdmissionLease);
        const reportNativeTerminal = recordTerminalOutcomes
          ? (status: ResponsesTerminalStatus, httpStatusOverride?: number) => {
            terminalRecorder?.(status, httpStatusOverride);
            if (status === "failed" || status === "incomplete") {
              const quotaFailureMessage = [httpStatusOverride, logCtx.terminalHttpStatus]
                .find(value => value === 429 || value === 402);
              if (!isFixedCodexAccount(admissionState.authCtx) && quotaFailureMessage !== undefined) {
                recordSubagentQuotaFailureForThreadSpawn(
                  req.headers,
                  subagentQuotaFailureModel,
                  quotaFailureMessage,
                  config,
                  requestState.subagentFallbackAccountId,
                );
              }
            }
            options.onNativePassthroughTerminal?.(status);
          }
          : undefined;
        const inspector = createSseInspector({
          onTerminal: reportNativeTerminal,
          logCtx,
          onCompletedResponse: rememberPassthroughResponse && !grokUpstreamEchoEnabled && responseEffects.plaintextV2AgentMessageToolNames.size === 0 ? rememberPassthroughResponseChecked : undefined,
          onParsedPayload: noteInspectedPayload,
          onFirstOutput: options.onFirstOutput,
          pinCompletedResponseIdToFirstSeen: githubCopilotRepairEnabled,
        });
        const eagerBody = relaySseEagerBounded(passthroughSseBody, turnAc, {
          inspectChunk: chunk => inspector.feed(chunk),
          finishInspection: () => inspector.finish(),
          disposeInspection: () => inspector.dispose(),
          // Stream lifetime follows the protocol terminal even when this request
          // has no outcome callback configured (reported() would stay false).
          sawTerminal: () => inspector.terminalSeen(),
          ...(clientBlockRewrite
            ? { rewriteBlocks: clientBlockRewrite }
            : {}),
          onSynthetic: (kind, reason) => {
            if (!reportNativeTerminal) return;
            if (kind === "incomplete") {
              logCtx.terminalSource = "synthetic";
              reportNativeTerminal("incomplete");
            } else if (reason === "upstream_error") {
              logCtx.terminalSource = "synthetic";
              reportNativeTerminal("failed", logCtx.terminalHttpStatus ?? 502);
            } else {
              logCtx.transportPhase = "mid_stream";
              logCtx.terminalSource = "synthetic";
              if (logCtx.activeAttempt) logCtx.activeAttempt.streamAborted = true;
              reportNativeTerminal("failed", 502);
            }
          },
          onClientCancel: () => {
            responseEffects.responseCompletionCancelled = true;
            options.onNativePassthroughCancel?.();
          },
          onDone: () => unregisterTurn(turnAc),
        }, {
          clientGoneSignal: options.abortSignal,
          terminalBoundary: codexSafetyBufferingOptions,
          maskCredential,
          ...(inlineEagerRewrite ? { rewriteBudget: translatorBudget } : {}),
          ...(logCtx.upstreamError === undefined ? {} : { upstreamError: logCtx.upstreamError }),
        });
        // When selected, this relay closes response.completed even if upstream
        // keeps the connection alive. Marked Codex WS traffic, Windows
        // forced-rewrite traffic, and Darwin explicit eager traffic apply
        // client rewrites inline rather than via the tee()+JS-pull chain.
        if (!headers.has("content-type")) headers.set("content-type", "text/event-stream");
        return markEagerRelaySseResponse(
          markNativePassthroughSseResponse(new Response(eagerBody, {
            status: upstreamResponse.status,
            headers,
          })),
        );
      }
      const turnAc = new AbortController();
      const clientGone = new AbortController();
      const clientGoneSignal = options.abortSignal
        ? AbortSignal.any([clientGone.signal, options.abortSignal])
        : clientGone.signal;
      // Pace against raw bytes before rewrites, without detaching terminal ownership.
      const [nativeBody, inspectBody] = teeWithBoundedInspection(passthroughSseBody, { clientGoneSignal });
      linkAbortSignal(upstream, turnAc.signal);
      registerTurn(turnAc, options.turnAdmissionLease);
      const inspectionConsumerOptions = {
        // Request abort can reject the fetch body before the response cancel hook runs.
        clientGoneSignal,
        drainBounds: { ms: 15_000, bytes: 32 * 1024 * 1024 },
        upstream,
        pinCompletedResponseIdToFirstSeen: githubCopilotRepairEnabled,
        onParsedPayload: noteInspectedPayload,
      };
      if (recordTerminalOutcomes) {
        // A real terminal was parsed from the (teed) inspection stream — record it as the outcome
        // even if the client has already disconnected: the turn genuinely reached that terminal, so
        // it must log as completed/failed, not be dropped or downgraded to a cancel (#44). A pure
        // client-cancel (no terminal seen) is finalized separately via consumeForInspection's onCancel.
        const reportNativeTerminal = (status: ResponsesTerminalStatus, httpStatusOverride?: number) => {
          terminalRecorder?.(status, httpStatusOverride);
          if (status === "failed" || status === "incomplete") {
            const quotaFailureMessage = [httpStatusOverride, logCtx.terminalHttpStatus]
              .find(value => value === 429 || value === 402);
            if (!isFixedCodexAccount(admissionState.authCtx) && quotaFailureMessage !== undefined) {
              recordSubagentQuotaFailureForThreadSpawn(
                req.headers,
                subagentQuotaFailureModel,
                quotaFailureMessage,
                config,
                requestState.subagentFallbackAccountId,
              );
            }
          }
          options.onNativePassthroughTerminal?.(status);
        };
        consumeForInspection(
          inspectBody,
          reportNativeTerminal,
          turnAc.signal,
          () => unregisterTurn(turnAc),
          logCtx,
          () => {
            responseEffects.responseCompletionCancelled = true;
            options.onNativePassthroughCancel?.();
          },
          rememberPassthroughResponse && !grokUpstreamEchoEnabled && responseEffects.plaintextV2AgentMessageToolNames.size === 0 ? rememberPassthroughResponseChecked : undefined,
          options.onFirstOutput,
          inspectionConsumerOptions,
        );
      } else {
        consumeForResponseLogMetadata(
          inspectBody,
          logCtx,
          turnAc.signal,
          () => unregisterTurn(turnAc),
          rememberPassthroughResponse && !grokUpstreamEchoEnabled && responseEffects.plaintextV2AgentMessageToolNames.size === 0 ? rememberPassthroughResponseChecked : undefined,
          options.onFirstOutput,
          inspectionConsumerOptions,
        );
      }
      if (!headers.has("content-type")) headers.set("content-type", "text/event-stream");
      // Windows was handled by the eager terminal-aware branch above. Remaining
      // tee traffic can use the JS relay to close on a protocol terminal and to
      // convert a mid-stream reset into a clean response.failed event.
      const rewrittenBody = clientBlockRewrite !== undefined
        ? relaySseWithBlockRewrite(nativeBody, clientBlockRewrite, translatorBudget)
        : nativeBody;
      const clientBody = relaySseWithFailedTail(
        rewrittenBody,
        upstream,
        reason => {
          responseEffects.responseCompletionCancelled = true;
          clientGone.abort(reason);
        },
        { upstreamError: logCtx.upstreamError, terminalBoundary: codexSafetyBufferingOptions, maskCredential },
      );
      return markNativePassthroughSseResponse(new Response(clientBody, {
        status: upstreamResponse.status,
        headers,
      }));
    }
    if (headers.get("content-type")?.toLowerCase().includes("application/json")) {
      // Bounded whole-body read: a non-streaming upstream JSON body is fully materialized
      // here (and again by the request-log finalizer and the WebSocket bridge's reframing),
      // so an unbounded .text() would let a hostile or stuck upstream grow proxy memory
      // without limit. This path is no longer rare — WebSocket turns for models whose
      // streaming terminal event is unreliable are deliberately answered with bounded JSON.
      // Oversize and stall deadlines both fail closed; a partial body is never parsed.
      const bounded = await readBoundedResponseBody(upstreamResponse, UPSTREAM_JSON_BODY_READ_OPTIONS);
      if (bounded.oversized) {
        return formatErrorResponse(502, "upstream_error", "upstream JSON response exceeded the safe body limit");
      }
      if (bounded.truncated) {
        return formatErrorResponse(502, "upstream_error", "upstream JSON response stalled before completing");
      }
      const text = bounded.text;
      inspectResponseLogJson(logCtx, text);
      let plaintextV2RestoreFailed = false;
      let clientJson = (() => {
        const restoredNamespace = restoreRoutedNamespaceCallsInJson(
          scrubSelfNamedToolCallNamespaceInJson(
            restoreMuseToolNamesInJson(
              restoreImageGenCallsInJson(text, imageGenCallAliases),
              responseEffects.routedMuseToolNameAliases,
            ),
            selfNamedNamespaceScrubAuthorization,
          ),
          responseEffects.routedNamespaceToolAliases,
        );
        const restoredAuthorizedBareNamespace = restoreRoutedNamespaceCallsInJson(
          restoredNamespace,
          authorizedBareNamespaceToolAliases,
        );
        const restored = restoreRoutedCustomCallsInJson(
          restoredAuthorizedBareNamespace,
          routedCustomToolNames,
          routedCustomToolRepairNames,
          declaredWireToolNames,
        );
        const restoredToolSearch = restoreRoutedToolSearchCallsInJson(
          restored,
          routedToolSearchNames,
        );
        const normalizedJson = normalizeFunctionCompletionJson(restoredToolSearch);
        const plaintextRestore = restorePlaintextV2AgentMessageCallsInJsonResult(
          normalizedJson, responseEffects.plaintextV2AgentMessageToolNames, responseEffects.plaintextV2AgentMessageAliasedToolNames,
        );
        plaintextV2RestoreFailed = plaintextRestore.overflowed;
        const repaired = plaintextRestore.value;
        const modelRewritten = parsed._responseModelId !== undefined && parsed._responseModelId !== parsed.modelId
          ? rewriteResponsesModelJson(repaired, parsed._responseModelId)
          : repaired;
        return modelRewritten;
      })();
      if (plaintextV2RestoreFailed) {
        return formatErrorResponse(502, "upstream_error", PLAINTEXT_V2_AGENT_MESSAGE_RESTORE_OVERFLOW_MESSAGE);
      }
      if (grokUpstreamEchoEnabled) {
        clientJson = stripGrokUpstreamEnvelopeEchoFromResponsesJson(clientJson);
      }
      // #1700: same fail-closed policy as the SSE relay above. Both the plain JSON answer and
      // the reframed-SSE branch below are built from this body, so one check covers them. This
      // runs BEFORE the continuation cache write below: a refused turn must not become state a
      // later `previous_response_id` replay can expand from.
      if (nativeExchange.undeclaredToolGuardActive) {
        const undeclared = (() => {
          try {
            return undeclaredToolCallNameInResponse(
              JSON.parse(clientJson),
              declaredWireToolNames,
              declaredNamelessClientCallTypes,
              providerExecutedCallTypes,
              declaredBareWireToolNames,
              recoverableBareCustomWireToolNames,
            );
          } catch {
            return undefined;
          }
        })();
        if (undeclared !== undefined) {
          return formatErrorResponse(502, "upstream_error", undeclaredToolCallMessage(undeclared));
        }
        clientJson = normalizeDefaultNamespaceInJson(
          clientJson,
          declaredWireToolNames,
          declaredBareWireToolNames,
        );
      }
      commitReasoningReplayServingRoute(nativeExchange.request.headers);
      try {
        rememberPassthroughResponseChecked(
          JSON.parse(grokUpstreamEchoEnabled ? clientJson : text) as { id?: unknown; output?: unknown; status?: unknown; model?: unknown },
        );
      } catch { /* non-JSON despite content-type; recording is best-effort */ }
      // #875: the transport-neutral reliability policy forced a bounded JSON
      // upstream for a client that asked for SSE. Reframe the completed JSON
      // as the canonical terminal SSE sequence (created → output_item.done →
      // terminal → [DONE]) so Codex commits the turn instead of hanging on a
      // stream that never closes. Non-streaming clients keep the plain JSON.
      if (clientRequestedStream === true
        && options.inboundTransport !== "websocket"
        && route.staticPolicy.model.responsesUpstreamStreaming === false
        && route.provider.adapter === "openai-responses") {
        let completed: Record<string, unknown> | undefined;
        try {
          const parsedCompleted = JSON.parse(clientJson) as unknown;
          if (!parsedCompleted || typeof parsedCompleted !== "object" || Array.isArray(parsedCompleted)) {
            throw new TypeError("bounded Responses JSON is not an object");
          }
          let candidate = parsedCompleted as Record<string, unknown>;
          // The bounded-JSON answer bypasses the SSE relay, so it also bypasses
          // the SSE item-id rewrite. Apply the same client-facing normalization
          // here or this policy would silently disable id repair for the very
          // providers that need it (raw record already happened above).
          if (hasResponsesItemIdRepair(route.provider.responsesItemIdRepair)) {
            candidate = repairResponsesJsonItemIds(candidate, route.provider.responsesItemIdRepair!, translatorBudget);
          }
          completed = candidate;
        } catch {
          // Non-JSON despite content-type: fall through to the plain relay.
        }
        if (completed) {
          let stream: ReadableStream<Uint8Array>;
          try {
            stream = responsesJsonToSseStream(completed);
          } catch (error) {
            if (error instanceof RangeError) {
              return formatErrorResponse(
                502,
                "upstream_error",
                "upstream JSON response exceeded the synthesized SSE item limit",
              );
            }
            throw error;
          }
          const sseHeaders = sanitizePassthroughHeaders(headers, codexSafetyBufferingOptions);
          sseHeaders.set("content-type", "text/event-stream");
          sseHeaders.set("cache-control", "no-store");
          return new Response(stream, {
            status: upstreamResponse.status,
            statusText: upstreamResponse.statusText,
            headers: sseHeaders,
          });
        }
      }
      // WS turns reframe this JSON into events in the bridge, which is the
      // other relay-free path — normalize ids so both bounded-JSON paths agree.
      const outboundJson = options.inboundTransport === "websocket"
        && route.staticPolicy.model.responsesUpstreamStreaming === false
        && hasResponsesItemIdRepair(route.provider.responsesItemIdRepair)
        ? (() => {
          try {
            return JSON.stringify(repairResponsesJsonItemIds(
              JSON.parse(clientJson) as Record<string, unknown>,
              route.provider.responsesItemIdRepair!,
              translatorBudget,
            ));
          } catch {
            return clientJson;
          }
        })()
        : clientJson;
      return new Response(outboundJson, {
        status: upstreamResponse.status,
        statusText: upstreamResponse.statusText,
        headers,
      });
    }
    if (responseEffects.plaintextV2AgentMessageToolNames.size > 0) {
      try { void upstreamResponse.body?.cancel().catch(() => {}); } catch { /* already closed */ }
      return formatErrorResponse(502, "upstream_error", "plaintext V2 agent-message response used an unsupported content type");
    }
    // An unclassified passthrough body is relayed directly and has no bounded completion observer;
    // use the same non-error-status success boundary as SSE instead of retaining per-stream state.
    commitReasoningReplayServingRoute(nativeExchange.request.headers);
    const body = relayWithAbort(upstreamResponse.body, upstream);
    const turnAc = new AbortController();
    const tracked = body ? trackStreamLifetime(body, turnAc, undefined, options.turnAdmissionLease) : null;
    return new Response(tracked, {
      status: upstreamResponse.status,
      headers,
    });
}
