@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,889 lines • 99 kB
text/typescript
import { createSteeringSettingsNormalizer } from "./native-steering-policy";
import { nativeResponseControlEligible } from "./native-response-control";
import { NativeInjectionReplay } from "./native-injection-replay";
import { NativeSteeringReplay } from "./native-steering-replay";
import type {
ResponsesRequestContext,
ResponsesAdmissionState,
PassthroughAdmissionState,
} from "./core-options";
import type { PreparedResponsesRequest } from "./request-prepare";
import type { ResponsesTransport } from "./request-transport";
import type { ResponsesEffects } from "./response-effects";
import type { ResponsesSendBudget } from "./request-send-budget";
import { transientSendCapFor } from "./request-send-budget";
import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
import { isLocalUpstream } from "../../lib/local-upstream";
import { codexSafetyBufferingFilterOptions, terminalStatusFromParsed } from "../relay";
import { imageGenToolCallAliases } from "../responses-image-gen-repair";
import { rememberResponseState, isBodyNonPersistable } from "../../responses/state";
import {
currentTurnWireToolCatalogBody,
hasExplicitWireToolCatalog,
collectDeclaredWireToolNames,
collectDeclaredBareWireToolNames,
collectDeclaredBareCustomWireToolNames,
collectDeclaredNamelessClientCallTypes,
collectProviderExecutedCallTypes,
undeclaredToolCallName,
undeclaredToolCallNameInResponse,
normalizeDefaultNamespaceInResponse,
} from "../responses-undeclared-tool-guard";
import { collectSelfNamedNamespaceScrubAuthorization } from "../responses-self-named-namespace-scrub";
import type { ProviderExecutedCallType } from "../responses-undeclared-tool-guard";
import {
releaseCodexAuthContextProbeLease,
unwrapUpstreamRetryEvidenceError,
codexProbeLeaseId,
codexProbeQuotaScope,
codexTransientProbeGrant,
createCodexReserveDispatchGuard,
} from "../../codex/auth-context";
import {
NamespaceToolCollisionError,
restoreRoutedNamespaceCalls,
} from "../../responses/namespace-tool-compat";
import { restoreRoutedCustomCalls, RoutedCustomToolCompatError } from "../../responses/custom-tool-compat";
import { XaiToolSchemaCompatibilityError } from "../../adapters/xai-tool-schema";
import { MuseToolChoiceCompatibilityError } from "../../adapters/openai-responses/muse-tool-choice";
import { formatErrorResponse } from "../../bridge";
import { redactSecretString } from "../../lib/redact";
import {
collectFunctionCallRepairSchemas,
repairFunctionCallsInJson,
} from "../../responses/function-call-compat";
import type { RoutedNamespaceToolAliases } from "../../responses/namespace-tool-compat";
import { hasResponsesSnapshotRepair, repairResponsesSnapshotJson } from "../responses-snapshot-repair";
import { backfillResponsesFieldsJson } from "./responses-field-backfill";
import type { AdapterRequest } from "../../adapters/base";
import { isXaiResponsesDestination, resolveProviderTransport } from "../../providers/xai-transport";
import { CODE_MODE_EXEC_TOOL_NAME } from "../../types";
import type { ResponsesTerminalStatus } from "../../bridge";
import { hasPassiveAccountQuota, recordPassiveAccountQuota } from "../../providers/quota";
import {
isMuseSubscriptionUsagePayload,
parseMuseSubscriptionUsage,
} from "../../providers/muse-subscription-usage";
import { restoreMuseToolNames } from "../../responses/muse-tool-name-alias";
import { restorePlaintextV2AgentMessageCalls } from "../../responses/plaintext-v2-agent-messages";
import {
recordAdapterReasoning,
recordAdapterTier,
sealRequestAttemptIdentity,
recordAttemptCredentialSource,
} from "../request-log";
import { noteAttemptRecoveryWithheld } from "../request-log";
import {
upstreamHostHealthKey,
normalizeUpstreamHostCircuitThreshold,
disableUpstreamHostCircuitForKey,
acquireUpstreamHostAdmission,
resetUpstreamHostHealth,
releaseUpstreamHostAdmission,
recordUpstreamHostFailure,
} from "../../codex/upstream-host-health";
import {
safeOriginLabel,
fetchWithHeaderTimeout,
providerFetch,
safeHostLabel,
storedPoolReplayDispatchNotifier,
} from "./fetch-helpers";
import { classifyPoolRecoveryDispatch } from "../../routing/probe-lease";
import { clientCancelledResponse } from "./core-errors";
import {
upstreamHostCircuitOpenResponse,
usesCodexForwardPoolAuth,
codexWsQuotaObserver,
isFixedCodexAccount,
codexPoolAccountModel400Denial,
shouldRetryCodexPoolAccountQuota,
shouldRetryCodexPoolAccountTransient,
retryCodexPoolOnAlternateAccount,
} from "./core-codex-account";
import {
clearCodexModelDenialEvidence,
recordCodexModelDenialEvidence,
} from "../../codex/model-entitlements";
import { codexWsSocketDeathStage, isCodexWsUpstreamResponse, readCodexWsStage } from "./codex-ws-wire";
import { linkAbortSignal } from "./core-lifetime";
import type { CodexAuthContext } from "../../codex/auth-context";
import { checkOutboundBodySize, describeOutboundBodyRefusal } from "./outbound-body-guard";
import { streamingContextOverflowResponse } from "./context-overflow";
import {
SendBudgetExhaustedError,
fetchWithTransientRetry,
applyUpstreamRecoveryInit,
isNonReplayableResponse,
isConnectionResetError,
settleOperatorReplacement,
refetchAfterProtocolSafeReset,
replayRefusalResponse,
prepareSameTarget429Wait,
sleepWithAbort,
} from "../../lib/upstream-retry";
import { mapCodexAuthContextErrorToResponse } from "./codex-auth-error";
import { classifyTransportFailureKind, transportErrorCode } from "../../lib/upstream-reachability";
import { recordCodexUpstreamOutcome } from "../../codex/routing";
import { describeUpstreamConnectFailure } from "./upstream-error";
import type { OpaqueBlobRecoveryGuard } from "./core-opaque-recovery";
import {
rateLimitRetryPolicyFor,
rateLimitRetryDelayMs,
transientRetryPolicyFor,
} from "../../providers/key-failover";
import type { AttemptRecoveryKind } from "../../usage/log";
import { resolveWireProtocolOverride } from "../adapter-resolve";
import { refreshPoolForwardAuth, refreshNativeMainForwardAuth, withClaudeNativeSession } from "./core-auth";
import { bindRouteReasoningReplayScope } from "./core-replay";
import type { OAuthAccessSnapshot } from "../../oauth";
import { OAuthAccountPausedError, OAuthLoginRequiredError, publicOAuthAuthenticationErrorMessage } from "../../oauth";
import { AnthropicAccountCooldownError } from "../../oauth/anthropic-routing";
import { resolveCopilotApiBaseUrl } from "../../oauth/github-copilot";
import {
hasEligibleGenericOAuthFailoverTarget,
isGenericOAuthFailoverEnabled,
rotateGenericOAuthAccountOn429,
failoverAccountSnapshot,
} from "../../oauth/generic-account-failover";
import { captureCodexAffinityDiagnostic } from "../../codex/affinity-debug";
import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "../../codex/catalog/native-models";
import {
attemptOpaqueBlobRecovery,
isEncryptedFunctionOutputRejection,
outboundResponsesBodyCarriesEncryptedFunctionOutput,
resetStreamedOpaqueBlobLogContext,
consoleGoUploadRejectionBody,
CONSOLE_GO_UPLOAD_RETRY_DELAY_MS,
reasoningEffortRejectionText,
} from "./core-opaque-recovery";
import type { RequestLogContext } from "../request-log";
import { deferProtocolSafeResetRecovery, preflightComboStreamResponse } from "./combo-stream-preflight";
import { authorizeResendForRecovery } from "../../lib/request-resend-gate";
import { ambiguousResendAllowanceFor, selfContainedResponsesBody } from "./reset-replay";
import { upstreamErrorMessageFromPayload, ENCRYPTED_FUNCTION_OUTPUT_REJECTION } from "../../lib/errors";
import { isTransientConsoleGoUploadRejection } from "../../providers/opencode-zen-rate-limit";
import { planReasoningEffortDowngrade } from "../../providers/reasoning-metadata";
/** Prepares and recovers one native Responses exchange before client commitment. */
export async function preparePassthroughExchange(
requestContext: Pick<ResponsesRequestContext, "config" | "logCtx" | "options" | "req">,
admissionState: ResponsesAdmissionState,
nativeHostState: PassthroughAdmissionState,
requestState: Pick<
PreparedResponsesRequest,
| "route"
| "toolBridgeMaps"
| "parsed"
| "translatorBudget"
| "responseStateOptions"
| "selectedForwardHeaders"
| "clientRequestedStream"
| "inboundWire"
| "substituteMainCredential"
| "callerAuthHeaders"
| "subagentFallbackAccountId"
>,
transportState: Pick<
ResponsesTransport,
| "adapter"
| "genericFailoverAccountId"
| "passiveQuotaWriterGeneration"
| "oauthDispatch"
| "resolveSelectionAdapter"
| "isOAuth401ReplayProvider"
| "sentOAuthSnapshot"
| "refreshResolvedOAuthSelection"
| "replayOAuthCredentialSnapshot"
| "genericFailovers"
| "genericFailoverLimit"
| "applyFailoverSnapshot"
| "noteRoutedAttemptSend"
| "selectionIsCurrent"
| "requestBindings"
>,
responseEffects: Pick<
ResponsesEffects,
| "refreshRequestToolAliases"
| "routedMuseToolNameAliases"
| "plaintextV2AgentMessageToolNames"
| "routedNamespaceToolAliases"
| "plaintextV2AgentMessageAliasedToolNames"
| "notifyResponseComplete"
>,
sendBudgetState: Pick<
ResponsesSendBudget,
| "remainingTransientSendBudget"
| "noteTransientSends"
| "recoverySendAllowance"
| "recoveryClassFor"
| "sendBudgetExhausted"
| "claimAmbiguousResend"
| "ambiguousResendSpent"
| "reserveCredentialHop"
| "pendingHopPermit"
| "workflowRootId"
| "sendsUsed"
>,
) {
const { config, logCtx, options, req } = requestContext;
const {
route,
toolBridgeMaps,
parsed,
translatorBudget,
responseStateOptions,
clientRequestedStream,
inboundWire,
substituteMainCredential,
callerAuthHeaders,
} = requestState;
const {
passiveQuotaWriterGeneration,
oauthDispatch,
resolveSelectionAdapter,
isOAuth401ReplayProvider,
refreshResolvedOAuthSelection,
applyFailoverSnapshot,
} = transportState;
const { refreshRequestToolAliases, notifyResponseComplete } = responseEffects;
const {
remainingTransientSendBudget,
noteTransientSends,
recoverySendAllowance,
recoveryClassFor,
sendBudgetExhausted,
claimAmbiguousResend,
reserveCredentialHop,
workflowRootId,
} = sendBudgetState;
const codexSafetyBufferingOptions = isCanonicalOpenAiForwardProvider(route.provider)
? codexSafetyBufferingFilterOptions(config)
: undefined;
// The canonical ChatGPT adapter coerces only its final outbound copy to `stream:true` so the
// separately captured client preference can still select JSON delivery. Recovery runs before
// delivery, though, and must classify the bytes the upstream was actually asked to send:
// ChatGPT may omit Content-Type, so consulting `parsed.stream` here would mistake its SSE body
// for non-streaming JSON and skip both opaque-state and safe-reset recovery.
const upstreamRequestsStream = parsed.stream === true
|| isCanonicalOpenAiForwardProvider(route.provider);
// A JSON client still needs the canonical destination's HTTP/SSE response so delivery can
// validate and fold it. Letting the forced `stream:true` body select the WebSocket transport
// bypasses manual HTTP redirects and can turn a real 3xx into a connect timeout.
const canonicalBufferedJson = clientRequestedStream !== true
&& isCanonicalOpenAiForwardProvider(route.provider);
const imageGenCallAliases = route.provider.authMode === "forward"
? new Map<string, { namespace: string; name: string }>()
: imageGenToolCallAliases(toolBridgeMaps.toolNsMap, parsed._rawBody, translatorBudget);
const routedCustomToolNames = new Set<string>();
const routedCustomToolRepairNames = new Set<string>();
const routedToolSearchNames = new Set<string>();
// Local continuation cache for the ChatGPT passthrough. Codex WS turns chain with
// previous_response_id, ocx converts them to internal HTTP requests, and the ChatGPT Codex
// REST backend rejects the parameter — the adapter strips it in forward mode, so the ONLY
// way a chained turn keeps its earlier context is the local replay expansion. Record
// completed passthrough responses (force bypasses Codex's blanket store:false) so the next
// turn's expansion hits. Never record a body whose own previous_response_id failed to
// expand: its input is a delta, and storing it would replay a truncated conversation.
// Compaction turns are excluded: _rawBody still carries the full pre-compaction history and
// recording it would let a later expansion rehydrate the chain Codex just replaced.
const passthroughRecordEligible = parsed._compactionRequest !== true
&& (!parsed.previousResponseId || parsed._previousResponseInputExpanded === true);
const rememberPassthroughResponse = passthroughRecordEligible
? (response: { id?: unknown; output?: unknown; status?: unknown }) =>
rememberResponseState(parsed._rawBody, response, undefined, responseStateOptions(true))
: undefined;
if (options.nativeControl && nativeResponseControlEligible(route.provider, options.nativeControl)
&& options.inboundTransport === "websocket" && !options.comboAttempt) {
const body = parsed._rawBody as Record<string, unknown>;
if (options.nativeControl.kind === "steering") {
options.nativeControl.normalizeContinuation = createSteeringSettingsNormalizer(parsed, route, config, req.headers);
}
const Replay = options.nativeControl.kind === "injection" ? NativeInjectionReplay : NativeSteeringReplay;
options.nativeControl.replayFactory = () => new Replay(body.input, (input, response) => {
if (passthroughRecordEligible && !isBodyNonPersistable(body)) {
rememberResponseState({ ...body, input }, response, undefined, responseStateOptions(true));
}
});
}
if (parsed.previousResponseId && !parsed._previousResponseInputExpanded) {
console.warn(
`[responses] previous_response_id ${parsed.previousResponseId} not found in local replay state `
+ `(model ${parsed.modelId}); forwarding without it — earlier turns may be missing from this request`,
);
}
// Preserve the caller's readable catalog boundary before provider-specific normalization can
// remove an unsupported final entry (for example xAI cached-only web search).
const replayedInputPrefixLength = parsed._replayPrefixLen ?? 0;
const clientToolAuthorizationBody = currentTurnWireToolCatalogBody(
parsed._rawBody,
replayedInputPrefixLength,
);
const selfNamedNamespaceScrubAuthorization = collectSelfNamedNamespaceScrubAuthorization(
clientToolAuthorizationBody,
toolBridgeMaps.bareCustomToolNames,
toolBridgeMaps.bareFunctionToolNames,
);
const clientExplicitWireToolCatalog = hasExplicitWireToolCatalog(clientToolAuthorizationBody);
const clientDeclaredWireToolNames = collectDeclaredWireToolNames(clientToolAuthorizationBody);
const clientDeclaredBareWireToolNames = collectDeclaredBareWireToolNames(clientToolAuthorizationBody);
const clientDeclaredBareCustomWireToolNames = collectDeclaredBareCustomWireToolNames(clientToolAuthorizationBody);
const clientDeclaredNamelessCallTypes = collectDeclaredNamelessClientCallTypes(
clientToolAuthorizationBody,
);
// Hosted calls the PROVIDER runs itself. Gated on the destination actually being xAI, so a
// declaration alone cannot buy the exemption on some other upstream that never serves it.
// Provider-executed declarations are authorized from the actual outbound body, after the
// adapter has applied destination-specific injection and normalization. Client-executed tool
// authority remains bounded to the caller-owned catalog above.
const providerExecutedCallTypes = new Set<ProviderExecutedCallType>();
let request: Awaited<ReturnType<typeof transportState.adapter.buildRequest>>;
try {
request = await transportState.adapter.buildRequest(parsed, {
headers: requestState.selectedForwardHeaders,
providerName: route.providerName,
translatorBudget,
});
} catch (error) {
releaseCodexAuthContextProbeLease(admissionState.authCtx);
// A tool catalog this proxy cannot lower onto one wire namespace is a client input error, and
// the rotation-rebuild and bridged paths already answer 400 for the identical throw. Rethrowing
// it here escaped every catch up to the Bun handler, so the same request produced an
// unstructured 500 — and no request log — depending only on whether a rotation ran first.
// Same shape for a tool_choice this proxy cannot honor: the destination rejects a schema the
// catalog had to drop, so the selector naming it is a client input error, not a 500.
if (
error instanceof NamespaceToolCollisionError
|| error instanceof XaiToolSchemaCompatibilityError
|| error instanceof RoutedCustomToolCompatError
|| error instanceof MuseToolChoiceCompatibilityError
) {
return formatErrorResponse(400, "invalid_request_error", redactSecretString(error.message));
}
throw error;
}
const functionRepairSchemas = isCanonicalOpenAiForwardProvider(route.provider)
? new Map()
: collectFunctionCallRepairSchemas(clientToolAuthorizationBody);
if (!isCanonicalOpenAiForwardProvider(route.provider)) {
for (const name of request.convertedRoutedCustomToolNames ?? []) {
if (
toolBridgeMaps.freeformToolNames.has(name)
|| toolBridgeMaps.toolNsMap.get(name)?.freeform === true
) routedCustomToolNames.add(name);
}
for (const name of request.routedCustomToolRepairNames ?? []) {
if (
toolBridgeMaps.freeformToolNames.has(name)
|| toolBridgeMaps.toolNsMap.get(name)?.freeform === true
) routedCustomToolRepairNames.add(name);
}
}
// Only grant direct MCP recovery when this delivery actually restores converted custom
// calls. Native forward and injection paths have no such rewrite.
const recoverableBareCustomWireToolNames = new Set(
[...clientDeclaredBareCustomWireToolNames].filter(name => routedCustomToolNames.has(name)),
);
for (const name of request.convertedRoutedToolSearchNames ?? []) {
// The adapter already keeps this set empty when tool_choice forbids the private search.
// Its wire name may be collision-aliased, so comparing it to the caller-facing name here
// would incorrectly disable restoration for the exact ambiguous-name case the alias fixes.
routedToolSearchNames.add(name);
}
refreshRequestToolAliases(request);
// #1700: the bridged paths refuse a call to a tool the request never declared
// (`declaredToolNames`, src/bridge.ts). The passthrough had no equivalent, so a routed
// provider's top-level `apply_patch` — which under Codex code mode exists only as a nested
// `tools.apply_patch(...)` helper inside `exec`, never as a wire tool — reached Codex as a
// call it cannot execute, and the turn showed a bare `aborted` with the file untouched.
// Forward auth is the canonical ChatGPT backend speaking Codex's own protocol rather than a
// routed provider, so it keeps passing through unguarded, as it does for the rewrites above.
// The guard needs a catalog to compare against, so it stands down when the request omits one.
// An explicit empty catalog is still authoritative: it declares that no client tools may be
// called. A passthrough request can legitimately omit `tools` entirely and still receive a call
// the client understands — `tests/providers/github-copilot/github-copilot-stream-contract.test.ts` sends
// `{model, input, stream}` with no tools and Copilot answers with a `custom_tool_call` for
// `apply_patch`. Policing an absent catalog truncates that turn. An unreadable body lands there
// too because the proxy cannot establish the caller's declared authorization boundary.
const parseOutboundRequestBody = (bodyText: string): Record<string, unknown> | undefined => {
try {
const body = JSON.parse(bodyText) as unknown;
return body && typeof body === "object" && !Array.isArray(body)
? body as Record<string, unknown>
: undefined;
} catch {
return undefined;
}
};
let outboundRequestBody: Record<string, unknown> | undefined;
const declaredWireToolNames = new Set<string>();
const declaredBareWireToolNames = new Set<string>();
const declaredNamelessClientCallTypes = new Set<string>();
// `buildToolBridgeMaps` adds each eligible bare alias to `declaredToolNames` and `toolNsMap`
// (one authorized identity claims the bare name). `refreshUndeclaredToolGuard` normally copies
// those entries into `declaredWireToolNames`, but passthrough restoration runs before the
// undeclared-tool guard, so restore that request-bounded identity here, before authorization
// checks. `exec` uses separate handling: its bridge alias is copied into the declared set only
// when the client itself declared bare `exec`, because otherwise code-mode normalization could
// authorize the unrelated code-mode helper names.
const authorizedBareNamespaceToolAliases: RoutedNamespaceToolAliases = new Map(
[...toolBridgeMaps.toolNsMap].flatMap(([alias, identity]) =>
alias === identity.name
? [[alias, {
namespace: identity.namespace,
name: identity.name,
kind: identity.freeform ? "custom" as const : "function" as const,
}] as const]
: []
),
);
const restoreAuthorizedBareNamespaceToolCalls = (value: unknown): unknown =>
restoreRoutedNamespaceCalls(value, authorizedBareNamespaceToolAliases).value;
const normalizeFunctionCompletionJson = (text: string): string => {
const snapshot = hasResponsesSnapshotRepair(route.provider.responsesSnapshotRepair)
? repairResponsesSnapshotJson(text, outboundRequestBody)
: text;
// Sparse gateways need completion status inferred before schema repair can
// distinguish completed arguments from in-progress placeholders.
return repairFunctionCallsInJson(backfillResponsesFieldsJson(snapshot), functionRepairSchemas);
};
let undeclaredToolGuardActive = false;
const refreshUndeclaredToolGuard = (builtRequest: AdapterRequest): void => {
outboundRequestBody = parseOutboundRequestBody(builtRequest.body);
providerExecutedCallTypes.clear();
if (isXaiResponsesDestination(route.provider)) {
// Preserve the caller-declared authorization recognized by the original classifier, then
// add adapter-injected declarations from the actual current-turn outbound catalog.
for (const callType of collectProviderExecutedCallTypes(clientToolAuthorizationBody)) {
providerExecutedCallTypes.add(callType);
}
const currentOutboundCatalog = currentTurnWireToolCatalogBody(
outboundRequestBody,
replayedInputPrefixLength,
);
for (const callType of collectProviderExecutedCallTypes(currentOutboundCatalog)) {
providerExecutedCallTypes.add(callType);
}
}
declaredWireToolNames.clear();
// With no replay prefix the full outbound body belongs to this turn and its normalized
// aliases are authoritative. A continuation's outbound body still contains historical
// catalogs (and may promote historical tool-search definitions), so it can never widen the
// current caller snapshot captured above.
declaredBareWireToolNames.clear();
if (replayedInputPrefixLength === 0) {
for (const name of collectDeclaredWireToolNames(outboundRequestBody)) {
declaredWireToolNames.add(name);
}
for (const name of collectDeclaredBareWireToolNames(outboundRequestBody)) {
declaredBareWireToolNames.add(name);
}
}
for (const name of clientDeclaredWireToolNames) declaredWireToolNames.add(name);
for (const name of clientDeclaredBareWireToolNames) declaredBareWireToolNames.add(name);
declaredNamelessClientCallTypes.clear();
if (replayedInputPrefixLength === 0) {
for (const callType of collectDeclaredNamelessClientCallTypes(outboundRequestBody)) {
declaredNamelessClientCallTypes.add(callType);
}
}
for (const callType of clientDeclaredNamelessCallTypes) {
declaredNamelessClientCallTypes.add(callType);
}
// On an ordinary request these maps capture caller-catalog identities that normalization may
// replace on the outbound wire (for example a client image tool becoming hosted). On replay,
// however, the parsed maps also contain historical catalog entries, so only the bounded
// current-turn wire snapshot above may authorize a call.
if (replayedInputPrefixLength === 0) {
for (const name of toolBridgeMaps.declaredToolNames) {
// `buildToolBridgeMaps` also aliases a namespaced tool under its bare name when the
// caller's `tool_choice` selected it unambiguously, which the bridge needs to route the
// call back. For `exec` alone that alias would also switch on nested-helper
// normalization and re-authorize `exec_command`/`shell_command`/`apply_patch`/`view_image`, so it is
// admitted here only when the caller's own catalog declared a bare `exec`. Selecting an
// MCP `exec` is not a declaration of the code-mode shell tool.
if (
name === CODE_MODE_EXEC_TOOL_NAME
&& !clientDeclaredWireToolNames.has(CODE_MODE_EXEC_TOOL_NAME)
) continue;
declaredWireToolNames.add(name);
}
}
undeclaredToolGuardActive = (
declaredWireToolNames.size > 0
|| clientDeclaredNamelessCallTypes.size > 0
|| clientExplicitWireToolCatalog
) && route.provider.authMode !== "forward";
options.nativeControl?.configureToolAuthorization?.(
undeclaredToolGuardActive,
declaredWireToolNames,
declaredBareWireToolNames,
declaredNamelessClientCallTypes,
providerExecutedCallTypes,
);
};
refreshUndeclaredToolGuard(request);
// A refused turn must not seed `previous_response_id` replay. The inspection branch reads the
// untouched upstream stream, so it can still observe a `response.completed` the client never
// received; checking the payload itself rather than a flag shared with the client relay keeps
// this free of tee ordering races.
//
// Checking only the terminal snapshot is not enough. An upstream can announce the undeclared
// call in `response.output_item.added`, which trips the client guard, and then close with a
// `response.completed` whose `output` is empty. The client gets `response.failed`, the terminal
// check sees nothing undeclared, and the refused turn enters continuation state anyway. So the
// rejection is sticky for the whole turn, set from every parsed payload on the inspection side.
let inspectionSawUndeclaredTool = false;
let inspectedTerminal: ResponsesTerminalStatus | null = null;
let inspectedCompletionSeen = false;
let firstTerminalAllowsRecall = false;
const passiveQuotaObserved = hasPassiveAccountQuota(route.providerName)
&& route.provider.authMode === "oauth";
const noteInspectedPayload = (payload: unknown) => {
// First terminal stays authoritative even in metadata-only inspection, which
// intentionally continues parsing after a failed/incomplete terminal.
const terminal = terminalStatusFromParsed(payload);
if (inspectedTerminal === null && terminal !== null) {
inspectedTerminal = terminal;
// The client boundary accepts a terminal by event type, even without a
// response object. Such a terminal must permanently decline recall.
if (terminal === "completed" && payload && typeof payload === "object"
&& "response" in payload && payload.response && typeof payload.response === "object"
&& !Array.isArray(payload.response) && "model" in payload.response) {
firstTerminalAllowsRecall = typeof payload.response.model === "string"
&& payload.response.model.trim().length > 0;
}
}
// Meta reports subscription usage ONLY as an in-stream event; there is no endpoint
// to poll (003 §E probed 17 paths, all 404). Observed here rather than behind a
// dedicated inspector handler because onParsedPayload already reaches every
// passthrough shape -- eager relay and both tee consumers -- through this one
// function.
//
// Placed BEFORE the undeclared-tool early return below, which is load-bearing: that
// guard latches for the rest of the turn once it fires, and a turn that tripped it
// still legitimately reports usage.
if (passiveQuotaObserved && isMuseSubscriptionUsagePayload(payload)) {
const quota = parseMuseSubscriptionUsage(payload);
// Read at EVENT time, not at handler construction: failover rebinds this, and the
// quota belongs to the account that actually served the turn.
const servingAccountId = transportState.genericFailoverAccountId;
if (quota && servingAccountId) {
recordPassiveAccountQuota(route.providerName, servingAccountId, quota, passiveQuotaWriterGeneration);
}
}
// Gated on the same flag as the guard itself: with no readable catalog (or a forward-auth
// provider) every name looks undeclared, and flipping this would stop recording continuation
// state for exactly the passthrough traffic the guard deliberately stands down for.
if (undeclaredToolGuardActive && !inspectionSawUndeclaredTool && undeclaredToolCallName(
restoreAuthorizedBareNamespaceToolCalls(
restoreMuseToolNames(payload, responseEffects.routedMuseToolNameAliases).value,
),
declaredWireToolNames,
declaredNamelessClientCallTypes,
providerExecutedCallTypes,
declaredBareWireToolNames,
recoverableBareCustomWireToolNames,
) !== undefined) {
inspectionSawUndeclaredTool = true;
}
// The snapshot callback opts the inspector into output reconstruction. Compaction
// has no continuation cache, so use the parsed terminal here without adding retention.
if (responseEffects.plaintextV2AgentMessageToolNames.size === 0 && !rememberPassthroughResponse && payload && typeof payload === "object"
&& "type" in payload && payload.type === "response.completed"
&& "response" in payload && payload.response && typeof payload.response === "object"
&& !Array.isArray(payload.response)) {
rememberPassthroughResponseChecked(payload.response as Record<string, unknown>);
}
};
const rememberPassthroughResponseChecked = (
response: { id?: unknown; output?: unknown; status?: unknown; model?: unknown },
) => {
if (inspectionSawUndeclaredTool) return;
const restored = restoreRoutedCustomCalls(
restoreAuthorizedBareNamespaceToolCalls(
restoreRoutedNamespaceCalls(
restoreMuseToolNames(response, responseEffects.routedMuseToolNameAliases).value,
responseEffects.routedNamespaceToolAliases,
).value,
),
routedCustomToolNames,
routedCustomToolRepairNames,
declaredWireToolNames,
).value;
const normalizedResponse = (functionRepairSchemas.size > 0
? JSON.parse(normalizeFunctionCompletionJson(JSON.stringify(restored)))
: restored) as { id?: unknown; output?: unknown; status?: unknown };
const plaintextRestore = restorePlaintextV2AgentMessageCalls(
normalizedResponse, responseEffects.plaintextV2AgentMessageToolNames, responseEffects.plaintextV2AgentMessageAliasedToolNames,
);
if (plaintextRestore.overflowed) return;
const restoredResponse = plaintextRestore.value as typeof normalizedResponse;
// Replay overlap compares the items the client echoes, including visible reasoning shape.
const replayResponse = restoredResponse;
if (
undeclaredToolGuardActive
&& undeclaredToolCallNameInResponse(
restoredResponse,
declaredWireToolNames,
declaredNamelessClientCallTypes,
providerExecutedCallTypes,
declaredBareWireToolNames,
recoverableBareCustomWireToolNames,
) !== undefined
) {
return;
}
const normalizedReplayResponse = (undeclaredToolGuardActive
? normalizeDefaultNamespaceInResponse(
replayResponse,
declaredWireToolNames,
declaredBareWireToolNames,
).value
: replayResponse) as typeof replayResponse;
rememberPassthroughResponse?.(normalizedReplayResponse);
const firstCompletion = !inspectedCompletionSeen;
inspectedCompletionSeen = true;
if (firstCompletion && (inspectedTerminal === null || firstTerminalAllowsRecall)) {
// A model-less first completion permanently declines recall; later terminal
// frames are hidden by the client boundary and cannot supply its identity.
// Native inspection sees the pre-rewrite model. Only an actual terminal
// model can seed recall; an absent model never falls back to the pick.
if (typeof response.model === "string" && response.model.trim()) {
notifyResponseComplete({
status: response.status,
model: parsed._responseModelId !== undefined && parsed._responseModelId !== parsed.modelId
? parsed._responseModelId : response.model,
});
}
}
};
recordAdapterReasoning(logCtx, request);
recordAdapterTier(logCtx, request);
const actualHostKey = upstreamHostHealthKey(
route.providerName,
safeOriginLabel(request.url),
);
const hostKey = route.provider.authMode === "forward"
? actualHostKey
: null;
const hostCircuitEnabled = hostKey !== null
&& normalizeUpstreamHostCircuitThreshold(config.upstreamHostCircuitThreshold) > 0;
if (hostKey !== null && !hostCircuitEnabled) {
disableUpstreamHostCircuitForKey(actualHostKey);
}
if (nativeHostState.lease && nativeHostState.lease.key !== hostKey) {
return formatErrorResponse(502, "upstream_error", "Provider host changed after circuit admission");
}
if (options.abortSignal?.aborted) {
releaseCodexAuthContextProbeLease(admissionState.authCtx);
return clientCancelledResponse();
}
if (!nativeHostState.lease && hostCircuitEnabled) {
const admission = acquireUpstreamHostAdmission(
hostKey!,
config.upstreamHostCircuitThreshold,
);
if (admission.kind === "blocked") {
releaseCodexAuthContextProbeLease(admissionState.authCtx);
return upstreamHostCircuitOpenResponse(admission.retryAfterSeconds);
}
nativeHostState.lease = admission.lease;
}
const settleObservedHostResponse = (): void => {
if (hostCircuitEnabled) {
resetUpstreamHostHealth(actualHostKey, nativeHostState.lease);
} else {
resetUpstreamHostHealth(actualHostKey);
}
nativeHostState.lease = null;
};
/**
* #4191: a Codex WS exchange pins its content-free stage record on the
* Response it resolves (markCodexWsStage). Adopting the record here, at
* the single funnel every physical upstream response passes through,
* binds it to the attempt that actually served it — including the 502/504
* pre-response JSON settles that never reach the SSE relay.
*/
const adoptCodexWsStage = (response: Response): void => {
const stage = readCodexWsStage(response);
if (stage && logCtx.activeAttempt) logCtx.activeAttempt.codexWsStage = stage;
};
const adoptObservedResponse = <T extends Response>(response: T): T => {
settleObservedHostResponse();
adoptCodexWsStage(response);
return response;
};
let passthroughEstimate = typeof request.usageLog?.inputTokens === "number"
? request.usageLog.inputTokens
: undefined;
if (passthroughEstimate !== undefined) {
logCtx.usageLogInputTokens = passthroughEstimate;
}
// Abort the upstream if the client disconnects. A directly-relayed body does not propagate the
// consumer's cancel to a signalled fetch, so we pass the signal and relay through relayWithAbort,
// whose cancel() aborts the upstream — preventing leaked connections (RC2, passthrough path).
const upstream = new AbortController();
linkAbortSignal(upstream, options.abortSignal);
const connectMs = config.connectTimeoutMs ?? 200_000;
let upstreamResponse: Response;
/**
* This leg's transient-5xx ladder cap, from the provider's own `transientRetryOn5xx`.
*
* The lane used to pass `TRANSIENT_RETRY_MAX_ATTEMPTS` at every call site, so an operator who
* configured the option on a key-auth `openai-responses` provider changed nothing in either
* direction, while the same provider on `openai-chat` was tuned normally. That asymmetry is
* #4893. The gate in `transientRetryPolicyFor` returns null for OAuth and forward providers,
* so the ChatGPT pool keeps exactly the ladder it has always had.
*
* Read per call rather than captured once, for two reasons. `route.provider` is reassigned
* inside the recovery loop by credential rotation and transport resolution, so a hoisted
* policy could outlive the provider row it came from. And the configured value is a total for
* the whole request, so it has to be measured against what the request has already sent at
* the moment each leg asks.
*
* Still bounded by the request: every site feeds this to `remainingTransientSendBudget` or
* `recoverySendAllowance`, which intersect it with the request-wide base allowance. So a
* provider can narrow this request's sends exactly and cannot widen the bound that exists to
* stop per-request amplification (#4546).
*/
const transientSendPolicy = () => transientRetryPolicyFor(route.provider);
const transientSendAttempts = (): number => transientSendCapFor(
transientSendPolicy()?.attempts,
sendBudgetState.sendsUsed,
);
const configuredTransientSendBudgetExhausted = (): boolean =>
transientSendPolicy() !== null && transientSendAttempts() === 0;
/**
* Judged once. The inbound body does not change between legs, and every rebuild this lane
* performs only ever REMOVES a hazard -- `previous_response_id` is expanded, hosted tools
* are lowered into client execution -- so a body that was replaceable stays replaceable.
* Memoized rather than recomputed because it walks the input array, and a provider that
* never opted in must not pay for it at all.
*/
let selfContainedJudgment: boolean | undefined;
const requestIsSelfContained = (): boolean =>
selfContainedJudgment ??= selfContainedResponsesBody(parsed._rawBody);
/**
* The operator's replacement grant for THIS logical request.
*
* Read per leg because `route.provider` is reassigned by credential rotation and transport
* resolution inside the recovery loop, exactly like `transientSendPolicy`. The counter it
* claims from is not per leg: it lives on the request's execution budget, which a combo
* child shares, so every ambiguous stage of this request draws on the same grant.
*/
const ambiguousResend = () =>
ambiguousResendAllowanceFor(route.provider, requestIsSelfContained, claimAmbiguousResend);
/**
* The pre-header row of the stage table, asked through the one gate.
*
* `fetchWithResetRetry` takes a plain callback because it is a leaf that must not import
* the server tree; routing the answer through `authorizeResendForRecovery` here is what
* keeps the decision derived from the table rather than restated as a boolean.
*/
const claimPreHeaderResend = (): boolean =>
authorizeResendForRecovery("pre-header", "connection-reset", ambiguousResend()).allowed;
/**
* The one replacement send the ambiguous rows at the end of the recovery loop may buy: an SSE
* body that died before any output, and a Codex WebSocket that died under its create frame
* (#4191).
*
* HTTP-only for both. A replacement HTTP body must not open a fresh WebSocket exchange: the SSE
* row replaces an HTTP stream, which a WS create frame is not, and the WebSocket row replaces
* the transport that just failed.
*/
const sendAmbiguousReplacement = (
signal: AbortSignal = upstream.signal,
): Promise<Response> => fetchWithHeaderTimeout(
request.url,
applyUpstreamRecoveryInit({
method: request.method,
headers: request.headers,
body: request.body,
}, "connection-reset"),
signal,
connectMs,
true,
providerFetch(route.provider, options.codexWsRuntimeIdentity, {
httpOnly: true,
providerName: route.providerName,
modelId: route.modelId,
dispatchOverride: oauthDispatch(request),
beforeDispatch: headers => {
if (signal.aborted) throw signal.reason;
if (!transportState.selectionIsCurrent(transportState.requestBindings.get(request))) {
throw new Error("Credential selection changed before pre-output stream recovery");
}
if (isCanonicalOpenAiForwardProvider(route.provider)) {
createCodexReserveDispatchGuard(
admissionState.authCtx,
options.codexAuthPolicy ?? config,
route.modelId,
options.admission,
options.visionDescribeTerminal === true,
)?.(headers);
}
// Recorded with the kind the gate derived its cause from, at the moment the
// send actually leaves. One authorisation, one recorded reason, one send.
transportState.noteRoutedAttemptSend(passthroughEstimate, "connection-reset");
// Charged to the SAME request counter every other send goes through. The
// replacement is bought here rather than by a nested retry helper, so there is
// one charge for one send and no per-layer counter to reconcile.
noteTransientSends(1);
},
}),
route.provider.authMode === "forward",
);
/**
* Refuse a built body that exceeds the operator's configured ceiling, before it is sent.
*
* Unconfigured this measures nothing and returns undefined, so an unset proxy behaves
* exactly as it does today. Runs at every point a body is built or rebuilt, because a
* rebuild can produce a payload the initial check never saw.
*/
const refuseOversizedOutboundBody = (
builtRequest: AdapterRequest,
refusalAuthCtx: CodexAuthContext = admissionState.authCtx,
): Response | undefined => {
const result = checkOutboundBodySize(builtRequest.body, config.maxUpstreamBodyBytes);
if (result.admitted) return undefined;
// This returns before the surrounding fetch/finally owns the observation, so release
// it here or one refused body holds translator budget for the process lifetime.
builtRequest.releaseBodyObservation?.();
upstream.abort();
releaseUpstreamHostAdmission(nativeHostState.lease);
nativeHostState.lease = null;
releaseCodexAuthContextProbeLease(refusalAuthCtx);
logCtx.errorCode = "outbound_body_too_large";
console.warn(
`[responses] refused an oversized outbound body: bytes=${result.bytes} limit=${result.limit} `
+ `input_images=${result.imageCount} image_bytes=${result.imageBytes} `
+ `model=${JSON.stringify(parsed.modelId)}`,
);
// A streaming client treats HTTP 413 as a retryable transport error and resends the same
// oversized body — the reconnect loop #3177 exists to stop. Terminal overflow is the
// honest shape, and it is what the upstream-413 path already returns.
if (clientRequestedStream) {
return streamingContextOverflowResponse(
parsed._responseModelId ?? parsed.modelId,
translatorBudget,
);
}
return formatErrorResponse(
413,
"outbound_body_too_large",
describeOutboundBodyRefusal(result),
);
};
const transportFailureResponse = (err: unknown): Response => {
upstream.abort();
if (options.abortSignal?.aborted) {
releaseUpstreamHostAdmission(nativeHostState.lease);
nativeHostState.lease = null;
releaseCodexAuthContextProbeLease(admissionState.authCtx);
return clientCancelledResponse();
}
// A budget refusal is a proxy decision, not an upstream fault. Reporting it as
// 502 upstream_error would blame the provider for a limit this process applied, and
// would record a fake reachability failure against the account's health.
if (err instanceof SendBudgetExhaustedError) {
releaseUpstreamHostAdmission(nativeHostState.lease);
nativeHostState.lease = null;
releaseCodexAuthContextProbeLease(admissionState.authCtx);
return formatErrorResponse(429, "request_send_budget_exhausted", err.message);
}
const refusal = unwrapUpstreamRetryEvidenceError(err);
// Pacing may outlive the selected account's admission. No fetch occurred, so do
// not turn an operator pause into a 502 or charge it to host/account health.
if (refusal instanceof OAuthAccountPausedError || refusal instanceof OAuthLoginRequiredError || refusal instanceof AnthropicAccountCooldownError) {
releaseUpstreamHostAdmission(nativeHostState.lease);
nativeHostState.lease = null;
releaseCodexAuthContextProbeLease(admissionState.authCtx);
if (refusal instanceof OAuthLoginRequiredError) {
return formatErrorResponse(401, "authentication_error", publicOAuthAuthenticationErrorMessage(refusal));
}
if (refusal instanceof AnthropicAccountCooldownError) {
return formatErrorResponse(429, "rate_limit_error", refusal.message,
refusal.retryAfterSeconds === null ? undefined : { retryAfter: String(refusal.retryAfterSeconds) });
}
return formatErrorResponse(403, "permission_error", publicOAuthAuthenticationErrorMessage(refusal));
}
const localRefusal = mapCodexAuthContextErrorToResponse(refusal, {
now: Date.now(), accountSelector: route.codexAccountNamespace,
});
if (localRefusal) {
releaseUpstreamHostAdmission(nativeHostState.lease);
nativeHostState.lease = null;
releaseCodexAuthContextProbeLease(admissionState.authCtx);
return localRefusal;
}
const outcome = classifyTransportFailureKind(err);
// Host-level evidence stands regardless of pool membership: a direct
// forward send has no pool accounting, but the reachability failure is
// still host-wide, not account evidence (#914 review).
if (outcome === "connect_neutral") {
if (hostCircuitEnabled) {
recordUpstreamHostFailure(actualHostKey, {
code: transportErrorCode(err),
threshold: config.upstreamHostCircuitThreshold,
lease: nativeHostState.lease,
});
} else {
recordUpstreamHostFailure(actualHostKey, { code: transportErrorCode(err) });
}
nativeHostState.lease = null;
} else {
releaseUpstreamHostAdmission(nativeHostState.lease);
nativeHostState.lease = null;
}
if (usesCodexForwardPoolAuth(admissionState.authCtx, route.provider)) {
recordCodexUpstreamOutcome(config, admissionState.authCtx.accountId, outcome, {
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,
});
}
const msg = outcome === "timeout"
? `Provider connect timeout after ${connectMs}ms`
: describeUpstreamConnectFailure(err, connectMs);
return formatErrorResponse(502, "upstream_error", msg);
};
const initialBodyRefusal = refuseOversizedOutboundBody(request);
if (initialBodyRefusal) return initialBodyRefusal;
try {
// Transient-5xx pre-stream retry (devlog/_plan/260716_claudecode_hardening/010):
// the ChatGPT backend emits transient 502/520s that an immediate retry absorbs.
// Body is a replayable string; nothing has streamed to the client yet.
upstreamResponse = await fetchWithTransientRetry(
recovery => {
// The pool-wide recovery window measures recovery traffic against observed demand,
// and this is where demand is observed: `recovery === undefined` is a new request's
// first send, everything after it is the same request trying again. Without this the
// ratio has no denominator and the window collapses to its quiet-pool floor, which
// would throttle recovery on a busy proxy exactly as hard as on an idle one (#4701).
if (recovery === undefined) classifyPoolRecoveryDispatch("initial");
transportState.noteRoutedAttemptSend(passthroughEstimate, recovery);
return fetchWithHeaderTimeout(request.url, applyUpstreamRecoveryInit({
method: request.method,
headers: request.headers,
body: request.body,
}, recovery), upstream.signal, connectMs, upstreamRequestsStream,
providerFetch(route.provider, options.codexWsRuntimeIdentity, {
httpOnly: canonicalBufferedJson,
nativeControl: nativeResponseControlEligible(route.provider, options.nativeControl) && options.inboundTransport === "websocket" && !options.comboAttempt
&& responseEffects.plaintextV2AgentMessageToolNames.size === 0
? options.nativeControl : undefined,
dispatchOverride: oauthDispatch(request),
providerName: route.providerName,
modelId: route.modelId,
onCodexWsQuota: codexWsQuotaObserver(admissionState.authCtx, route.provider, route.modelId),
beforeDispatch: isCanonicalOpenAiForwardProvider(route.provider)
? createCodexReserveDispatchGuard(admissionState.authCtx, options.codexAuthPolicy ?? config, route.modelId, options.admission, options.visionDescribeTerminal === true) : undefined,
}),
route.provider.authMode === "forward")
// Every real attempt response — including an intermediate 5xx the
// retry wrapper replaces — proves the host was reached (#914 review).
.then(adoptObservedResponse);
},
{ abortSignal: upstream.signal, label: safeHostLabel(request.url),
attempts: remainingTransientSendBudget(transientSendAttempts()), onSendsConsumed: noteTransientSends,
claimAmbiguousResend: claimPreHeaderResend,
},
);
} catch (err) {
return transportFailureResponse(err);
} finally {
request.releaseBodyObservation?.();
}
const opaqueBlobRecoveryGuard: OpaqueBlobRecoveryGuard = { attempted: false };
// At most one reasoning-effort downgrade per request.
const reasoningEffortDowngradeGuard: { attempted: boolean } = { attempted: false };
let oauth401ReplayAttempted = false;
let codex401ReplayKind: "main" | "stored" | null = null;
// Console Go answers a transient 400 "Invalid upload request." for bodies it accepts
// moments later; at most one byte-identical replay is allowed per request.
const consoleGoUploadRetryGuard: { attempted: boolean } = { attempted: false };
const rateLimitPolicy = rateLimitRetryPolicyFor(route.provider);
let rateLimitRetries = 0;
const rebuildAndRefetch = async (
recovery: AttemptRecoveryKind,
): Promise<Response | { failed: Response }> => {
const retryAdapter = resolveSelectionAdapter(
resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, inboundWire, route.staticPolicy),
config.cacheRetention,
);
if (!("passthrough" in retryAdapter) || !retryAdapter.passthrough) {
upstream.abort();
return { failed: formatErrorResponse(502, "upstream_error", "Recovery changed the provider wire unexpectedly") };
}
try {
if (recovery !== "console-go-upload-retry") {
request = await retryAdapter.buildRequest(parsed, {
headers: requestState.selectedForwardHeaders,
providerName: route.providerName,
translatorBudget,
});
}
refreshRequestToolAliases(request);
recordAdapterReasoning(logCtx, request);
recordAdapterTier(logCtx, request);
} catch (err) {
upstream.abort();
if (options.abortSignal?.aborted) return { failed: clientCancelledResponse() };
const msg = err instanceof Error ? err.message : String(err);
return { failed: formatErrorResponse(400, "invalid_request_error", redactSecretString(msg)) };
}
passthroughEstimate = typeof request.usageLog?.inputTokens === "number"
? request.usageLog.inputTokens
: undefined;
if (passthroughEstimate !== undefined) logCtx.usageLogInputTokens = passthroughEstimate;
refreshUndeclaredToolGuard(request);
logCtx.providerAdapter = retryAdapter.name;
sealRequestAttemptIdentity(
logCtx.activeAttempt,
logCtx.provider,
retryAdapter.name,
logCtx.accountLogLabel,
);
recordAttemptCredentialSource(logCtx.activeAttempt, route.providerName, route.provider, retryAdapter.name);
const rebuiltBodyRefusal = refuseOversizedOutboundBody(request);
if (rebuiltBodyRefusal) return { failed: rebuiltBodyRefusal };
// The base allowance is spent first. An unconfigured provider may then draw the one shared
// final-recovery reserve, which keeps a validated sanitized rebuild after a 5xx streak alive
// at four total sends instead of dying at three. An explicit provider total cannot widen.
// Reserve outside the try so the finally can hand it back if the leg never reaches its send.
const allowance = recoverySendAllowance(
transientSendAttempts(),
recoveryClassFor(recovery),
`${route.providerName}|${route.modelId}|${recovery}`,
{ allowFinalRecoveryReserve: transientSendPolicy() === null },
);
try {
return await fetchWithTransientRetry(
innerRecovery => {
// Gated on the return, not fire-and-forget: a consumed permit means this leg
// already sent once, and letting the second call through would be a free send.
if (allowance.permit && !allowance.permit.use()) {
throw new SendBudgetExhaustedError(safeHostLabel(request.url));
}
transportState.noteRoutedAttemptSend(passthroughEstimate, innerRecovery ?? recovery);
return fetchWithHeaderTimeout(request.url, applyUpstreamRecoveryInit({
method: request.method,
headers: request.headers,
body: request.body,
}, innerRecovery), upstream.signal, connectMs, upstreamRequestsStream,
providerFetch(route.provider, options.codexWsRuntimeIdentity, {
httpOnly: canonicalBufferedJson,
nativeControl: nativeResponseControlEligible(route.provider, options.nativeControl) && options.inboundTransport === "websocket" && !options.comboAttempt
&& responseEffects.plaintextV2AgentMessageToolNames.size === 0
? options.nativeControl : undefined,
dispatchOverride: oauthDispatch(request),
providerName: route.providerName,
modelId: route.modelId,
onCodexWsQuota: codexWsQuotaObserver(admissionState.authCtx, route.provider, route.modelId),
beforeDispatch: isCanonicalOpenAiForwardProvider(route.provider)
? createCodexReserveDispatchGuard(admissionState.authCtx, options.codexAuthPolicy ?? config, route.modelId, options.admission, options.visionDescribeTerminal === true) : undefined,
}),
route.provider.authMode === "forward")
.then(adoptObservedResponse);
},
{ abortSignal: upstream.signal, label: safeHostLabel(request.url), attempts: allowance.attempts,
onSendsConsumed: noteTransientSends, claimAmbiguousResend: claimPreHeaderResend },
);
} catch (err) {
return { failed: transportFailureResponse(err) };
} finally {
// A no-op once the permit was used or once onSendsConsumed settled it; it only refunds
// a reservation whose send never happened.
allowance.permit?.release();
request.releaseBodyObservation?.();
}
};
// Keep recovery kinds in sync with the generic `recovery:` loop below.
passthroughRecovery: for (;;) {
if (
upstreamResponse.status === 401
&& (admissionState.authCtx.kind === "main-pool" || admissionState.authCtx.kind === "pool")
&& usesCodexForwardPoolAuth(admissionState.authCtx, route.provider)
&& codex401ReplayKind === null
) {
codex401ReplayKind = admissionState.authCtx.kind === "pool" ? "stored" : "main";
try { void upstreamResponse.body?.cancel().catch(() => {}); } catch { /* already consumed */ }
const poolAuthCtx = admissionState.authCtx.kind === "pool" ? admissionState.authCtx : undefined;
const poolReplay = poolAuthCtx
? await refreshPoolForwardAuth({ req, config, route, authCtx: poolAuthCtx, substituteMainCredential, options, logCtx })
: undefined;
const replay = poolReplay
?? await refreshNativeMainForwardAuth({ req, config, route, authCtx: admissionState.authCtx, substituteMainCredential, options });
if (!replay.ok) {
// Compact already records this; core historically returned without recording,
// so a dead grant stayed selectable and every request repeated the same doomed
// refresh. Fenced by the generation the 401 belongs to (#2887).
if (poolAuthCtx && poolReplay && !poolReplay.ok && poolReplay.quarantine) {
recordCodexUpstreamOutcome(config, poolAuthCtx.accountId, 401, {
threadId: poolAuthCtx.affinityKey,
fixedAccount: poolAuthCtx.fixedAccount,
modelId: route.modelId,
writerGeneration: poolAuthCtx.writerGeneration,
credentialGeneration: poolReplay.quarantineGeneration ?? poolAuthCtx.generation,
});
}
upstream.abort();
releaseCodexAuthContextProbeLease(admissionState.authCtx);
return replay.response;
}
admissionState.authCtx = replay.authCtx;
route.provider = replay.provider;
requestState.selectedForwardHeaders = withClaudeNativeSession(replay.headers, replay.provider, options.claudeNativeSessionId);
const replayAdapter = resolveSelectionAdapter(
resolveWireProtocolOverride(route.providerName, route.modelId, replay.provider, inboundWire, route.staticPolicy),
config.cacheRetention,
);
if (!("passthrough" in replayAdapter) || !replayAdapter.passthrough) {
upstream.abort();
return formatErrorResponse(502, "upstream_error", "Native main refresh changed the provider wire unexpectedly");
}
bindRouteReasoningReplayScope({
parsed,
providerName: route.providerName,
provider: replay.provider,
adapterName: replayAdapter.name,
codexAuthContext: admissionState.authCtx,
forwardHeaders: requestState.selectedForwardHeaders,
});
logCtx.providerAdapter = replayAdapter.name;
sealRequestAttemptIdentity(logCtx.activeAttempt, logCtx.provider, replayAdapter.name, logCtx.accountLogLabel);
recordAttemptCredentialSource(logCtx.activeAttempt, route.providerName, route.provider, replayAdapter.name);
try {
request = await replayAdapter.buildRequest(parsed, {
headers: requestState.selectedForwardHeaders,
providerName: route.providerName,
translatorBudget,
});
refreshRequestToolAliases(request);
recordAdapterReasoning(logCtx, request);
recordAdapterTier(logCtx, request);
refreshUndeclaredToolGuard(request);
// The 401 replay rebuilds the body before sending, so it needs the same ceiling as
// every other build site; a replay is exactly when a grown payload reappears.
const replayBodyRefusal = refuseOversizedOutboundBody(request);
if (replayBodyRefusal) return replayBodyRefusal;
// The replay-dispatched signal is what bounds the rest of this logical request, so it
// has to describe a send that actually happened. fetchWithHeaderTimeout awaits pacing
// admission BEFORE calling the executor, so signalling at the call site would spend the
// budget even when a rejected pacing wait means nothing reaches the network. Wrapping
// the executor moves the signal to the last moment before the send, where a throw from
// here on is a genuine transport attempt. The notifier is built once for the whole leg:
// it fires on the first dispatch, and a replacement is another send of the same replay
// rather than a second one to announce.
const oauthReplayExecutor = storedPoolReplayDispatchNotifier(
providerFetch(route.provider, options.codexWsRuntimeIdentity, {
httpOnly: canonicalBufferedJson,
nativeControl: nativeResponseControlEligible(route.provider, options.nativeControl) && options.inboundTransport === "websocket" && !options.comboAttempt
&& responseEffects.plaintextV2AgentMessageToolNames.size === 0
? options.nativeControl : undefined,
dispatchOverride: oauthDispatch(request),
providerName: route.providerName,
modelId: route.modelId,
onCodexWsQuota: codexWsQuotaObserver(admissionState.authCtx, route.provider, route.modelId),
beforeDispatch: isCanonicalOpenAiForwardProvider(route.provider)
? createCodexReserveDispatchGuard(admissionState.authCtx, options.codexAuthPolicy ?? config, route.modelId, options.admission, options.visionDescribeTerminal === true) : undefined,
}),
codex401ReplayKind === "stored" ? options.onStoredPool401ReplayDispatched : undefined,
);
// Routed through the shared helper so an ambiguous reset on THIS leg answers with the
// same refusal every other leg gives. A bare fetch here rejected instead, and the
// caller's transport-failure path turns a rejection into a client-retryable 502 --
// which invites the whole turn to be sent again, on a leg whose first send may already
// have run it.
upstreamResponse = await fetchWithTransientRetry(
recovery => {
transportState.noteRoutedAttemptSend(passthroughEstimate, recovery ?? "oauth-401");
return fetchWithHeaderTimeout(
request.url,
applyUpstreamRecoveryInit({
method: request.method,
headers: request.headers,
body: request.body,
}, recovery),
upstream.signal,
connectMs,
upstreamRequestsStream,
oauthReplayExecutor,
route.provider.authMode === "forward",
).then(adoptObservedResponse);
},
{ abortSignal: upstream.signal, label: safeHostLabel(request.url),
attempts: remainingTransientSendBudget(transientSendAttempts()),
onSendsConsumed: noteTransientSends, claimAmbiguousResend: claimPreHeaderResend },
);
} catch (err) {
return transportFailureResponse(err);
} finally {
request.releaseBodyObservation?.();
}
continue passthroughRecovery;
}
if (codex401ReplayKind !== null && upstreamResponse.status === 401) break;
// Native Responses providers return before the generic adapter recovery loop below. Keep
// their OAuth contract identical: one pre-stream 401 forces a credential refresh and one
// rebuilt replay. xAI's current subscription models use this branch now that their official
// Grok CLI catalog declares the Responses backend.
if (
upstreamResponse.status === 401
&& isOAuth401ReplayProvider
&& transportState.sentOAuthSnapshot
&& !oauth401ReplayAttempted
// Refused here, before the 401 body is cancelled: once it is gone the request can only
// answer with a synthetic 502, which would report a proxy budget decision as an upstream
// fault and throw away the credential evidence the client needs.
&& !sendBudgetExhausted(transientSendAttempts())
) {
oauth401ReplayAttempted = true;
try { void upstreamResponse.body?.cancel().catch(() => {}); } catch { /* already consumed/closed */ }
let refreshed: OAuthAccessSnapshot;
try {
refreshed = await refreshResolvedOAuthSelection(transportState.sentOAuthSnapshot);
} catch (err) {
upstream.abort();
releaseCodexAuthContextProbeLease(admissionState.authCtx);
return formatErrorResponse(401, "authentication_error", publicOAuthAuthenticationErrorMessage(err));
}
if (route.provider.googleMode === "cloud-code-assist" && !refreshed.projectId) {
upstream.abort();
releaseCodexAuthContextProbeLease(admissionState.authCtx);
return formatErrorResponse(401, "authentication_error", publicOAuthAuthenticationErrorMessage(new Error("Cloud Code Assist project is required")));
}
transportState.sentOAuthSnapshot = refreshed;
transportState.replayOAuthCredentialSnapshot = {
accountId: refreshed.accountId,
generation: refreshed.generation,
};
if (route.providerName === "kiro") {
parsed._kiroAuthContext = { ...(refreshed.kiro ?? {}) };
}
const refreshedProvider = resolveProviderTransport(
route.providerName,
{
...route.provider,
apiKey: refreshed.accessToken,
...(refreshed.projectId ? { project: refreshed.projectId } : {}),
},
parsed.options.promptCacheKey,
route.providerName === "github-copilot"
? resolveCopilotApiBaseUrl(refreshed.apiBaseUrl)
: undefined,
);
route.provider = refreshedProvider;
const refreshedAdapter = resolveSelectionAdapter(
resolveWireProtocolOverride(route.providerName, route.modelId, refreshedProvider, inboundWire, route.staticPolicy),
config.cacheRetention,
);
if (!("passthrough" in refreshedAdapter) || !refreshedAdapter.passthrough) {
upstream.abort();
return formatErrorResponse(502, "upstream_error", "OAuth refresh changed the provider wire unexpectedly");
}
bindRouteReasoningReplayScope({
parsed,
providerName: route.providerName,
provider: refreshedProvider,
adapterName: refreshedAdapter.name,
oauthCredentialSnapshot: transportState.replayOAuthCredentialSnapshot,
});
logCtx.providerAdapter = refreshedAdapter.name;
sealRequestAttemptIdentity(
logCtx.activeAttempt,
logCtx.provider,
refreshedAdapter.name,
logCtx.accountLogLabel,
);
recordAttemptCredentialSource(logCtx.activeAttempt, route.providerName, route.provider, refreshedAdapter.name);
try {
request = await refreshedAdapter.buildRequest(parsed, {
headers: requestState.selectedForwardHeaders,
providerName: route.providerName,
translatorBudget,
});
refreshRequestToolAliases(request);
recordAdapterReasoning(logCtx, request);
recordAdapterTier(logCtx, request);
} catch (err) {
upstream.abort();
if (options.abortSignal?.aborted) return clientCancelledResponse();
const msg = err instanceof Error ? err.message : String(err);
return formatErrorResponse(400, "invalid_request_error", redactSecretString(msg));
}
refreshUndeclaredToolGuard(request);
const refreshedBodyRefusal = refuseOversizedOutboundBody(request);
if (refreshedBodyRefusal) return refreshedBodyRefusal;
try {
upstreamResponse = await fetchWithTransientRetry(
recovery => {
transportState.noteRoutedAttemptSend(passthroughEstimate, recovery ?? "oauth-401");
return fetchWithHeaderTimeout(request.url, applyUpstreamRecoveryInit({
method: request.method,
headers: request.headers,
body: request.body,
}, recovery), upstream.signal, connectMs, upstreamRequestsStream,
providerFetch(route.provider, options.codexWsRuntimeIdentity, {
httpOnly: canonicalBufferedJson,
nativeControl: nativeResponseControlEligible(route.provider, options.nativeControl) && options.inboundTransport === "websocket" && !options.comboAttempt
&& responseEffects.plaintextV2AgentMessageToolNames.size === 0
? options.nativeControl : undefined,
dispatchOverride: oauthDispatch(request),
providerName: route.providerName,
modelId: route.modelId,
onCodexWsQuota: codexWsQuotaObserver(admissionState.authCtx, route.provider, route.modelId),
beforeDispatch: isCanonicalOpenAiForwardProvider(route.provider)
? createCodexReserveDispatchGuard(admissionState.authCtx, options.codexAuthPolicy ?? config, route.modelId, options.admission, options.visionDescribeTerminal === true) : undefined,
}),
route.provider.authMode === "forward")
.then(adoptObservedResponse);
},
{ abortSignal: upstream.signal, label: safeHostLabel(request.url), attempts: remainingTransientSendBudget(transientSendAttempts()),
onSendsConsumed: noteTransientSends, claimAmbiguousResend: claimPreHeaderResend },
);
} catch (err) {
return transportFailureResponse(err);
} finally {
request.releaseBodyObservation?.();
}
}
// Native Responses returns before the generic adapter's OAuth rotation loop. Keep
// the same quorum, cooldown and request budget here, before any client bytes flow.
if (
upstreamResponse.status === 429
// Not a provider rate limit when this proxy synthesized it for a refused reset
// replay; rotating accounts on it would re-send an inference that may already
// have run and would cool down an account that refused nothing.
&& !isNonReplayableResponse(upstreamResponse)
&& transportState.genericFailoverAccountId
&& transportState.genericFailovers < transportState.genericFailoverLimit
&& isGenericOAuthFailoverEnabled(config, route.providerName)
) {
// The roster cap above is one half of the bound; the request's shared budget is the
// other. A refused hop leaves the real 429 -- body, Retry-After and any quota evidence
// -- exactly as upstream sent it.
const hop = reserveCredentialHop(
"auth-recovery",
`${route.providerName}|${route.modelId}|oauth-account-429`,
true,
);
if (hop.allowed) {
const nextAccountId = rotateGenericOAuthAccountOn429(
config, route.providerName, transportState.genericFailoverAccountId,
upstreamResponse.headers.get("retry-after"),
Date.now(),
route.modelId,
);
let snapshot: OAuthAccessSnapshot | undefined;
if (nextAccountId) {
try { snapshot = await failoverAccountSnapshot(route.providerName, nextAccountId); }
catch { /* Keep the original 429 body readable when the next credential is unavailable. */ }
}
if (snapshot && await applyFailoverSnapshot(snapshot)) {
transportState.genericFailovers += 1;
route.provider = resolveProviderTransport(
route.providerName, route.provider, parsed.options.promptCacheKey, transportState.sentOAuthSnapshot?.apiBaseUrl,
);
bindRouteReasoningReplayScope({
parsed, providerName: route.providerName, provider: route.provider,
adapterName: "openai-responses", oauthCredentialSnapshot: transportState.replayOAuthCredentialSnapshot,
});
try { void upstreamResponse.body?.cancel().catch(() => {}); } catch { /* already closed */ }
// The replay IS this hop's send, so the rebuild spends the reservation instead of
// asking for one of its own.
sendBudgetState.pendingHopPermit = hop.permit;
const result = await rebuildAndRefetch("oauth-account-429");
sendBudgetState.pendingHopPermit = undefined;
if ("failed" in result) return result.failed;
upstreamResponse = result;
continue passthroughRecovery;
}
// No credential moved, so the reservation costs nothing.
hop.permit?.release();
} else {
// The activation quorum ignores cooldowns; prove that the selector has a live alternate
// before describing this as a recovery that only the shared request budget withheld.
if (hasEligibleGenericOAuthFailoverTarget(
route.providerName, transportState.genericFailoverAccountId, Date.now(), route.modelId,
)) noteAttemptRecoveryWithheld(logCtx.activeAttempt, "rotation-send-budget");
}
}
// Same-target 429 wait-and-retry (opt-in `retryOn429`) for key-auth providers on the
// passthrough wire. This branch returns before the recovery loop below, so Responses-shaped
// key-auth gateways (e.g. the built-in DeepSeek preset) would otherwise surface 429
// immediately with no same-key replay. Pre-stream only — nothing has been relayed yet, so
// the replay is lossless (same invariant as the recovery loop). Forward/OAuth providers
// keep their pool logic below (rateLimitRetryPolicyFor returns null for them).
while (
upstreamResponse.status === 429
&& !isNonReplayableResponse(upstreamResponse)
&& rateLimitPolicy !== null
&& rateLimitRetries < rateLimitPolicy.attempts
// Checked here rather than inside the helper: prepareSameTarget429Wait releases the 429
// body, so a refusal discovered after the wait can no longer return the real rate-limit
// answer and would surface a synthetic 502 instead.
&& !sendBudgetExhausted(transientSendAttempts())
) {
rateLimitRetries += 1;
// Release unread body + deliberate wait via the shared same-target helper.
const retryAfterHeader = upstreamResponse.headers.get("retry-after");
try {
for await (const _ of prepareSameTarget429Wait({
body: upstreamResponse.body,
signal: options.abortSignal,
delayMs: rateLimitRetryDelayMs(rateLimitPolicy, retryAfterHeader, Date.now()),
})) {
// pre-stream: no stall watchdog to feed
}
} catch {
upstream.abort();
return clientCancelledResponse();
}
// Client cancellation wins over any stale timer edge: re-check before dispatching the
// replay so the wire never starts work for a request the client already abandoned.
if (options.abortSignal?.aborted || upstream.signal.aborted) {
upstream.abort();
return clientCancelledResponse();
}
try {
upstreamResponse = await fetchWithTransientRetry(
recovery => {
// The first send of every replay is itself a rate-limit retry; inner transient-5xx
// recoveries keep their own label (recovery is provided for those).
transportState.noteRoutedAttemptSend(passthroughEstimate, recovery ?? "rate-limit-429");
return fetchWithHeaderTimeout(request.url, applyUpstreamRecoveryInit({
method: request.method,
headers: request.headers,
body: request.body,
}, recovery), upstream.signal, connectMs, upstreamRequestsStream,
providerFetch(route.provider, options.codexWsRuntimeIdentity, {
httpOnly: canonicalBufferedJson,
nativeControl: nativeResponseControlEligible(route.provider, options.nativeControl) && options.inboundTransport === "websocket" && !options.comboAttempt
&& responseEffects.plaintextV2AgentMessageToolNames.size === 0
? options.nativeControl : undefined,
dispatchOverride: oauthDispatch(request),
providerName: route.providerName,
modelId: route.modelId,
onCodexWsQuota: codexWsQuotaObserver(admissionState.authCtx, route.provider, route.modelId),
beforeDispatch: isCanonicalOpenAiForwardProvider(route.provider)
? createCodexReserveDispatchGuard(admissionState.authCtx, options.codexAuthPolicy ?? config, route.modelId, options.admission, options.visionDescribeTerminal === true) : undefined,
}),
route.provider.authMode === "forward")
.then(adoptObservedResponse);
},
{ abortSignal: upstream.signal, label: safeHostLabel(request.url), attempts: remainingTransientSendBudget(transientSendAttempts()),
onSendsConsumed: noteTransientSends, claimAmbiguousResend: claimPreHeaderResend },
);
} catch (err) {
return transportFailureResponse(err);
}
}
const captureAffinityResponse = (
response: Response,
captureAuthCtx: CodexAuthContext = admissionState.authCtx,
captureRequest: Awaited<ReturnType<typeof transportState.adapter.buildRequest>> = request,
credentialSubstituted = substituteMainCredential
|| captureAuthCtx.kind === "pool"
|| captureAuthCtx.kind === "main-pool",
): void => {
if (!isCanonicalOpenAiForwardProvider(route.provider)) return;
captureCodexAffinityDiagnostic({
inboundHeaders: req.headers,
outboundHeaders: captureRequest.headers,
authKind: captureAuthCtx.kind,
accountMode: route.codexAccountMode,
fixedAccount: isFixedCodexAccount(captureAuthCtx),
credentialSubstituted,
accountGatedModel: ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(route.modelId),
wireModelNormalized: parsed.modelId !== route.modelId,
status: response.status,
});
};
captureAffinityResponse(upstreamResponse);
if (usesCodexForwardPoolAuth(admissionState.authCtx, route.provider)) {
let poolRetryOutcome: number | undefined;
// A success is the freshest evidence there is about this pair, and it outranks any earlier
// refusal: whatever the entitlement was when upstream declined, it is not that now. Both
// ids are cleared because the wire model can differ from the routed one.
if (upstreamResponse.ok) {
clearCodexModelDenialEvidence(
admissionState.authCtx.accountId,
route.modelId,
admissionState.authCtx.kind === "pool" ? admissionState.authCtx.generation : undefined,
);
clearCodexModelDenialEvidence(
admissionState.authCtx.accountId,
parsed.modelId,
admissionState.authCtx.kind === "pool" ? admissionState.authCtx.generation : undefined,
);
}
const model400Denial = await codexPoolAccountModel400Denial(
upstreamResponse,
route.modelId,
options.abortSignal,
parsed.modelId,
);
if (model400Denial !== undefined) {
// Spend this refusal on more than one retry. It is the account's own authenticated
// answer about this model, and the roster cache that selection otherwise reads expires
// five minutes after a catalog sync fills it -- so without remembering this, the next
// request selects the same account on quota alone and takes the same 400 (#4906).
recordCodexModelDenialEvidence(
admissionState.authCtx.accountId,
model400Denial,
admissionState.authCtx.kind === "pool" ? admissionState.authCtx.generation : undefined,
);
poolRetryOutcome = 400;
} else if (!admissionState.authCtx.fixedAccount && await shouldRetryCodexPoolAccountQuota(
upstreamResponse,
options.abortSignal,
)) {
// Pre-stream only: once SSE has begun, mid-stream quota stays terminal.
// ChatGPT sometimes wraps quota exhaustion in a generic 5xx. Normalize only
// body-confirmed cases to quota evidence so cooldown and rotation both apply.
poolRetryOutcome = upstreamResponse.status >= 500 ? 429 : upstreamResponse.status;
} else if (!admissionState.authCtx.fixedAccount && shouldRetryCodexPoolAccountTransient(upstreamResponse)) {
// A plain transient 5xx the same-account retry layer could not absorb. Keep the real
// status so it records as transient rather than quota.
poolRetryOutcome = upstreamResponse.status;
}
if (poolRetryOutcome !== undefined) {
// A stored Pool 401 spent this request's account budget on its own refresh and replay, so
// nothing afterwards may be paid for out of a DIFFERENT account. One flag carries that,
// rather than a status check here as well: a quota failure has no same-account move, so
// `sameAccountOnly` makes it terminal by refusing the alternate; the gated-model 400
// ladder does have one — retrying the account the refreshed roster still grants — and
// keeps it. An earlier revision also broke here on a non-400 outcome, which no test could
// justify because this flag already produced the identical result.
const storedReplaySpent = codex401ReplayKind === "stored";
const retry = await retryCodexPoolOnAlternateAccount({
callerAuthHeaders,
config,
route,
parsed,
logCtx,
options: { ...options, workflowRootId },
firstAuthCtx: admissionState.authCtx,
firstResponse: upstreamResponse,
outcomeStatus: poolRetryOutcome,
sameAccountOnly: storedReplaySpent,
upstream,
connectMs,
passthroughEstimate,
stream: upstreamRequestsStream,
httpOnly: canonicalBufferedJson,
onResponse: (response, retryAuthCtx, retryRequest) => {
adoptCodexWsStage(response);
captureAffinityResponse(
response,
retryAuthCtx,
retryRequest,
retryAuthCtx.kind !== "main",
);
},
});
if (retry.kind === "transport") {
admissionState.authCtx = retry.authCtx;
return transportFailureResponse(retry.error);
}
if (retry.kind === "retried") {
admissionState.authCtx = retry.authCtx;
request = retry.request;
refreshRequestToolAliases(request);
refreshUndeclaredToolGuard(request);
upstreamResponse = retry.upstreamResponse;
requestState.selectedForwardHeaders = retry.selectedForwardHeaders;
// Keep subagent quota-failure health keyed to the account that actually served.
requestState.subagentFallbackAccountId = retry.authCtx.accountId;
}
}
}
// The deterministic route record cannot classify history it never observed (restart, expiry,
// eviction, or an older transcript). Inspect only a bounded clone of a 4xx whose exact outbound
// Responses body still carries opaque state, then rebuild once through the ordinary adapter
// sanitation path. A second rejection falls through unchanged because the guard stays armed.
if (!configuredTransientSendBudgetExhausted()) {
const opaqueBlobRecovery = await attemptOpaqueBlobRecovery({
response: upstreamResponse,
outboundBody: request.body,
adapterName: transportState.adapter.name,
parsed,
guard: opaqueBlobRecoveryGuard,
signal: upstream.signal,
}, rebuildAndRefetch);
if (opaqueBlobRecovery.kind === "failed") return opaqueBlobRecovery.response;
if (opaqueBlobRecovery.kind === "recovered") {
upstreamResponse = opaqueBlobRecovery.response;
continue passthroughRecovery;
}
}
const recoveryContentType = upstreamResponse.headers.get("content-type")?.toLowerCase() ?? "";
const streamedFunctionOutputCandidate = upstreamResponse.ok
&& !!upstreamResponse.body
&& (recoveryContentType.includes("text/event-stream") || (!recoveryContentType && upstreamRequestsStream))
&& !opaqueBlobRecoveryGuard.attempted
&& !configuredTransientSendBudgetExhausted()
&& outboundResponsesBodyCarriesEncryptedFunctionOutput(request.body);
if (streamedFunctionOutputCandidate) {
const preflightLog: RequestLogContext = { model: logCtx.model, provider: logCtx.provider };
const preflight = await preflightComboStreamResponse(upstreamResponse, preflightLog,
payload => {
if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
const type = (payload as { type?: unknown }).type;
const decryptRejection = (type === "error" || type === "response.failed" || type === "response.incomplete")
&& isEncryptedFunctionOutputRejection(JSON.stringify(payload));
// `detail` is a real WebSocket error shape but the generic preflight failure projector
// intentionally understands only Responses error/message fields. Preserve only this
// exact identity so the projected 502 can enter the existing single-shot recovery.
if (decryptRejection) preflightLog.upstreamError = ENCRYPTED_FUNCTION_OUTPUT_REJECTION;
return decryptRejection;
}, {
allowMissingContentType: !recoveryContentType && upstreamRequestsStream,
replayReadErrors: true,
});
if (options.abortSignal?.aborted) return transportFailureResponse(options.abortSignal.reason);
upstreamResponse = preflight.response;
if (preflight.kind === "failed") {
// A zero-output failure does not undo an ambiguous replacement already sent.
if (!configuredTransientSendBudgetExhausted() && !sendBudgetState.ambiguousResendSpent) {
const streamedOpaqueRecovery = await attemptOpaqueBlobRecovery({
response: upstreamResponse,
outboundBody: request.body,
adapterName: transportState.adapter.name,
parsed,
guard: opaqueBlobRecoveryGuard,
signal: upstream.signal,
}, rebuildAndRefetch);
if (streamedOpaqueRecovery.kind === "failed") return streamedOpaqueRecovery.response;
if (streamedOpaqueRecovery.kind === "recovered") {
resetStreamedOpaqueBlobLogContext(logCtx);
upstreamResponse = streamedOpaqueRecovery.response;
continue passthroughRecovery;
}
}
logCtx.upstreamError = preflightLog.upstreamError;
logCtx.terminalHttpStatus = preflightLog.terminalHttpStatus;
logCtx.terminalErrorCode = preflightLog.terminalErrorCode;
logCtx.terminalIncompleteReason = preflightLog.terminalIncompleteReason;
// The projected failure must not invite another send after the replacement was spent.
if (sendBudgetState.ambiguousResendSpent) upstreamResponse = settleOperatorReplacement(upstreamResponse);
}
}
// Console Go (opencode-zen / opencode-go) intermittently rejects a body it accepts seconds
// later with 400 invalid_request_error / "Invalid upload request." Replay the byte-identical
// request once after the exact gateway rejection. Single-shot guard.
// This recovery reuses the captured request; other recovery kinds still rebuild.
if (!consoleGoUploadRetryGuard.attempted) {
const uploadRejectionBody = await consoleGoUploadRejectionBody(
upstreamResponse,
consoleGoUploadRetryGuard.attempted,
upstream.signal,
);
if (uploadRejectionBody !== undefined
&& !configuredTransientSendBudgetExhausted()
&& isTransientConsoleGoUploadRejection({
status: upstreamResponse.status,
errorBody: uploadRejectionBody,
outboundUrl: request.url,
})) {
consoleGoUploadRetryGuard.attempted = true;
try { void upstreamResponse.body?.cancel().catch(() => {}); } catch { /* already consumed/closed */ }
if (!upstream.signal.aborted) {
try {
await sleepWithAbort(CONSOLE_GO_UPLOAD_RETRY_DELAY_MS, upstream.signal);
} catch { return clientCancelledResponse(); }
}
if (upstream.signal.aborted) return clientCancelledResponse();
const result = await rebuildAndRefetch("console-go-upload-retry");
if ("failed" in result) return result.failed;
upstreamResponse = result;
continue passthroughRecovery;
}
}
// Reasoning-effort downgrade: a rung the catalog still advertises can be refused upstream --
// the metadata records the model's ladder, not this account's entitlement (a Muse Code
// subscription gates max on muse-spark-1.3-contributor, for example). Learn the refusal so
// later turns clamp before dispatch, then replay once at the next lower published rung
// instead of failing the turn; requestedEffort/effectiveEffort keep both values in usage.
if (!reasoningEffortDowngradeGuard.attempted) {
const rejectionText = await reasoningEffortRejectionText(
upstreamResponse,
reasoningEffortDowngradeGuard.attempted,
upstream.signal,
);
const downgrade = rejectionText === undefined
? undefined
: planReasoningEffortDowngrade({
provider: route.provider,
modelId: parsed.modelId,
requested: parsed.options.reasoning,
rejectionText,
});
if (downgrade && !configuredTransientSendBudgetExhausted()) {
reasoningEffortDowngradeGuard.attempted = true;
parsed.options.reasoning = downgrade.effort;
try { void upstreamResponse.body?.cancel().catch(() => {}); } catch { /* already consumed/closed */ }
const result = await rebuildAndRefetch("reasoning-effort-downgrade");
if ("failed" in result) return result.failed;
upstreamResponse = result;
continue passthroughRecovery;
}
}
// The WebSocket row of the same table (#4191). A Codex socket that closed or failed under its
// create frame, before any Responses event, settled as a non-replayable 502 and every leg above
// let it through. Whether the turn ran upstream is as unknown as after a reset before the head,
// so the same grant decides, asked with the stage the exchange reached. The replacement's answer
// then goes round the loop like any other, and once the grant is spent nothing may send the
// turn a third time.
const socketDeathStage = codexWsSocketDeathStage(upstreamResponse);
if (
socketDeathStage
&& !upstream.signal.aborted
// Asked before the gate, which claims last: a replacement the budget cannot fund must not
// spend the request's one grant.
&& remainingTransientSendBudget(transientSendAttempts()) > 0
&& authorizeResendForRecovery(socketDeathStage, "connection-reset", ambiguousResend()).allowed
) {
try { void upstreamResponse.body?.cancel().catch(() => {}); } catch { /* already consumed/closed */ }
console.warn(`[upstream-retry] codex websocket died before any Responses event (${safeHostLabel(request.url)}); `
+ "using one replacement over HTTP");
let replacement: Response | undefined;
while (!replacement) {
try {
replacement = await sendAmbiguousReplacement().then(adoptObservedResponse);
} catch (err) {
if (upstream.signal.aborted) return transportFailureResponse(err);
// A replacement that reset before its head is the pre-header row again: a configured
// second grant (and a send the budget can still fund) may buy one more send. The gate
// claims from the request's finite allowance, so this loop is bounded by it.
if (
isConnectionResetError(err)
&& remainingTransientSendBudget(transientSendAttempts()) > 0
&& claimPreHeaderResend()
) continue;
break;
}
}
// The first send may already have run the turn, so a replacement that failed settles as
// the refusal rather than as a transport error the client would retry.
upstreamResponse = replacement ? settleOperatorReplacement(replacement) : replayRefusalResponse();
continue passthroughRecovery;
}
// The post-header row of the same table. A native SSE body can die after the head with the
// caller having observed nothing, which is the identical question the pre-header helper
// answers -- and the identical grant, because both claim from this request's one allowance.
const streamRecoveryContentType = upstreamResponse.headers.get("content-type")?.toLowerCase() ?? "";
const protocolRecoveryCandidate = upstreamResponse.ok
&& !!upstreamResponse.body
&& !isNonReplayableResponse(upstreamResponse)
// The WebSocket transport settles its own ambiguous failures and marks them
// non-replayable; re-reading its body here would be a second owner of one exchange.
&& !isCodexWsUpstreamResponse(upstreamResponse)
// A downstream WebSocket turn that fell back to HTTP must relay response.created
// immediately so the client can address the turn and receive explicit control refusal.
// This preflight retains that event until output commits, so the two contracts cannot
// share one body owner.
&& !(options.nativeControl && options.inboundTransport === "websocket")
&& ambiguousResend() !== undefined
&& remainingTransientSendBudget(transientSendAttempts()) > 0
&& (streamRecoveryContentType.includes("text/event-stream") || (!streamRecoveryContentType && upstreamRequestsStream));
if (protocolRecoveryCandidate) {
upstreamResponse = deferProtocolSafeResetRecovery(
upstreamResponse,
{ model: logCtx.model, provider: logCtx.provider },
(error, stage) => refetchAfterProtocolSafeReset(
(signal = upstream.signal) => sendAmbiguousReplacement(signal).then(adoptObservedResponse),
error,
{
abortSignal: upstream.signal,
label: safeHostLabel(request.url),
attempts: remainingTransientSendBudget(transientSendAttempts()),
// The whole decision, including the stage the preflight observed and the grant the
// pre-header helper shares. A committed stage refuses here without touching the
// allowance, which is what keeps a turn that already emitted output from draining
// the replacement a later ambiguous reset would have been entitled to.
authorize: () => authorizeResendForRecovery(stage, "connection-reset", ambiguousResend()).allowed,
acceptResponse: candidate => {
const type = candidate.headers.get("content-type")?.toLowerCase() ?? "";
return type.includes("text/event-stream") || (!type && upstreamRequestsStream);
},
},
),
{ allowMissingContentType: !streamRecoveryContentType && upstreamRequestsStream },
);
}
break;
}
// Where this relay dials upstream. Local infrastructure (loopback / private / `.local` / `.lan`)
// is operator-trusted and its silent phases are normal, so an unset stall budget resolves to
// disabled for it. Provider rotation above keeps the same endpoint origin, so the routed
// provider's baseUrl is the stable classification source.
const localUpstream = isLocalUpstream(route.provider.baseUrl);
return {
codexSafetyBufferingOptions,
imageGenCallAliases,
routedCustomToolNames,
routedCustomToolRepairNames,
routedToolSearchNames,
rememberPassthroughResponse,
selfNamedNamespaceScrubAuthorization,
providerExecutedCallTypes,
get request(): Awaited<ReturnType<typeof transportState.adapter.buildRequest>> {
return request;
},
set request(value: Awaited<ReturnType<typeof transportState.adapter.buildRequest>>) {
request = value;
},
functionRepairSchemas,
get outboundRequestBody(): Record<string, unknown> | undefined {
return outboundRequestBody;
},
set outboundRequestBody(value: Record<string, unknown> | undefined) {
outboundRequestBody = value;
},
declaredWireToolNames,
declaredBareWireToolNames,
recoverableBareCustomWireToolNames,
declaredNamelessClientCallTypes,
authorizedBareNamespaceToolAliases,
normalizeFunctionCompletionJson,
get undeclaredToolGuardActive(): typeof undeclaredToolGuardActive {
return undeclaredToolGuardActive;
},
set undeclaredToolGuardActive(value: typeof undeclaredToolGuardActive) {
undeclaredToolGuardActive = value;
},
noteInspectedPayload,
rememberPassthroughResponseChecked,
upstream,
connectMs,
localUpstream,
upstreamResponse,
};
}
export type PassthroughExchange = Exclude<Awaited<ReturnType<typeof preparePassthroughExchange>>, Response>;