@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,972 lines • 104 kB
text/typescript
import { advisorPlanRootConfig } from "./advisor-plan-slot";
import { admitsHostedAdvisor, scopedAnthropicServerTools } from "../messages-native-scope";
import { selectResponseReplayOwner } from "./replay-owner";
import { isPlaintextV2AgentMessagesEnabled } from "../../config/multi-agent-surface";
import { comboLogLabel, comboTargetLogLabel } from "../../combos/resolve";
import { clientFacingModelLabel, clientFacingModelText } from "../../lib/error-destination";
import { carryLocalFailureState, projectLocalModelRefusalLog, upstreamErrorIsLocal } from "../request-log-failure-detail";
import { carryProxyErrorContext, hasProxyErrorMessage, isPausedTurn, markProxyError, rememberPausedTurn } from "../../lib/client-error-body";
import { isXaiPrivacyModeRefusal } from "../../providers/xai-privacy-mode";
import { classifyUpstreamCondition } from "../../lib/upstream-condition";
import { effectiveAzureOutputBudget } from "../../adapters/azure";
import { resolveOutputCeiling } from "./input-admission";
import { buildResponsesTransport } from "../../adapters/openai-responses/transport";
import { isMetaAiResponsesDestination } from "../../responses/muse-tool-name-alias";
import { chatCanPreserveMandatoryToolChoice, hasMandatoryToolChoice } from "./combo-required-tool-contract";
import { isComboVisionDescriptionRefusal, isPolicyCandidateRefusal, isMandatoryToolChoiceRefusal } from "./policy-request-scope";
import { isCodexAccountCooldownResponse } from "../../codex/account-cooldown-response";
import { resolveWireProtocolOverride } from "../adapter-resolve";
import { parseSyntheticRowId } from "../fast-row";
import { resolveOpenAiVirtualModel } from "../../providers/openai-virtual-models";
import { comboCooldownRetryAfterSeconds, isDefiniteContextOverflow, type CodexAccountModelRefusal } from "../../combos/failover";
import { fallbackTriggerForStatus, guardFallbackHop } from "../../routing/fallback-policy";
import {
isCodexReasoningEffort,
isDeclaredReasoningEffort,
resolveEffortAtOrBelow,
} from "../../reasoning-effort";
import { admissionMayUseMeteredComboTargets, admissionModelDeniedResponse, AdmissionModelDeniedError, intersectAdmissionModelScopes, projectAdmissionModelDeniedLog, resolveAdmissionModelScope, routeAllowedByScope } from "../admission-model-scope";
import { recordAttemptRequestedEffort } from "../request-log";
import { bindLinkTurnChild, failLinkTurnExpansion, markLinkTurnMissing, observeLinkTurnExpansion } from "../link-turn";
import {
CODEX_TEXT_GUARDED_BUDGET_POLICY,
deriveRequestExecutionBudget,
isRequestExecutionBudget,
} from "../../lib/request-execution-budget";
import type {
RequestExecutionBudgetPolicy,
RequestExecutionBudget,
} from "../../lib/request-execution-budget";
import type { OcxComboDefaultEffort, OcxConfig, OcxUsage } from "../../types";
import type { RequestLogContext } from "../request-log";
import type { HandleResponsesOptions, ResponsesDispatchers, ConsumedComboFailure } from "./core-options";
import type { TranslatorBudget } from "../../lib/translator-budget";
import {
getCombo,
comboRequestHasImageInput,
pickComboTarget,
pickComboTargetWithWait,
targetKey,
concreteComboRequestBody,
isComboTargetInCooldown,
snapshotComboQuotaCooldowns,
comboExclusion,
comboUnavailableDiagnostics,
comboTargetUnavailableCause,
comboTargetSkipTrigger,
noteComboSuccess,
settleComboReprobeSuccess,
comboFailureDecision,
advanceComboAfterFailure,
comboFailureCooldownScope,
JEV_PROVIDER_ID,
jevDecisionBackendFor,
resolveJevComboDecision,
type ComboPick,
type JevCandidate,
type JevDecision,
} from "../../combos";
import { formatErrorResponse } from "../../bridge";
import { SEND_BUDGET_EXHAUSTED_CODE } from "../../lib/errors";
import {
expandPreviousResponseInput,
previousResponseRestoredPrefixLength,
previousResponseReplayFailure,
previousResponseProviderState,
} from "../../responses/state";
import { hasUnreadableEncryptedAgentTask } from "./encrypted-payload";
import { eagerCodexToolCatalogSurface, warnEagerCodexToolCatalog } from "./codex-tool-catalog";
import { clampComboCallerEffort, comboCapabilityGate } from "../../combos/request-capability";
import { comboAdvertisesEffortUnion } from "../../combos/capability-policy";
import { requestStartComboConfig, snapshotComboAdmission, snapshotComboAdmissionProvider } from "./combo-admission-snapshot";
import { canDescribeComboImages } from "./request-sidecar-auth";
import { captureRouteStaticPolicy, routeConcreteModel, comboRouteDecisionTrace } from "../../router";
import { memoryModelRouteReason } from "./memory-models";
import { baseProviderLabel, poolAccountProviderLabel } from "../../providers/label";
import { getAccountSet } from "../../oauth/store";
import { anthropicRefusalCredentialIsCurrent } from "../../oauth/anthropic-account-refusal";
import { configuredAnthropicInstance } from "../../providers/anthropic-instance";
import { isAnthropicBillingFailure } from "../../providers/anthropic-billing-refusal";
import {
anthropicRoutingFor,
formatAnthropicProviderForLog,
} from "../../oauth/anthropic-routing";
import { codexAccountLogLabel, oauthAccountLogLabel } from "../../codex/account-label";
import { isGenericFailoverProvider, rotateGenericOAuthAccountOn429 } from "../../oauth/generic-account-failover";
import { codexQuotaScopeForModel, getCodexQuotaHealthSnapshot } from "../../codex/routing";
import { MAIN_CODEX_ACCOUNT_ID } from "../../codex/account-id";
import { providerCodexAccountMode } from "../../providers/registry";
import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
import type { AgentTaskRecoveryFailureReason } from "./agent-task-recovery";
import {
agentTaskRecoveryConfig,
discardEncryptedAgentTaskRecovery,
recoverEncryptedAgentTaskWithResult,
} from "./agent-task-recovery";
import { isThreadSpawnRequest, supportedLadderFor } from "../effort-policy";
import { jevChoiceEfforts } from "./jev-combo-choice";
import { applyDroidResponsesReasoningDefault } from "../droid-reasoning-default";
import { isPlainObject } from "../../lib/plain-data";
import {
clientCancelledResponse,
comboUnavailable,
comboUnavailableResponse,
targetIncompatibleResponse,
unreadableEncryptedAgentTaskResponse,
} from "./core-errors";
import {
buildComboChildHeaders,
createChildPassthroughCallbackGate,
consumeComboFailure,
isLateAttributionRefusal,
} from "./core-combo-failure";
import {
linkRequestSessionLane,
reasoningReplayConversationIdFromResponsesRequest,
sessionIdHeaderFromRequest,
sessionLaneIdFromRequest,
} from "../request-log-conversation";
import type { CodexAuthContext } from "../../codex/auth-context";
import type { ResponsesTerminalStatus } from "../../bridge";
import { beginRequestAttempt, sealRequestAttemptIdentity, finishRequestAttempt } from "../request-log";
import { sealedCredentialRefusals } from "../request-log-attempt-recovery";
import { recallComboTurnEffortForLane, rememberComboForLane, type ComboTurnEffort } from "./combo-session-recall";
import { COMBO_TOOL_LOOP_PIN_REASON, toolLoopPinnedPick } from "./combo-tool-loop-pin";
import { JEV_SESSION_PIN_ROUTE_REASON, jevSessionPinScope } from "./jev-session-pin";
import { runTurnAdapterSseResponses } from "./core-lifetime";
import { normalizePersistedJevDecision } from "../../usage/jev-stats";
import {
isNativePassthroughSseResponse,
isEagerRelaySseResponse,
markNativePassthroughSseResponse,
markEagerRelaySseResponse,
} from "../relay";
import { preflightComboStreamResponse } from "./combo-stream-preflight";
import { requiredToolContractOf } from "./combo-required-tool-contract";
import {
streamingContextOverflowResponse,
jsonContextOverflowResponse,
lateAttributionLimitResponse,
jsonIncompleteResponse,
streamingIncompleteResponse,
} from "./context-overflow";
import { mandatoryResponsesReasoningReplayUnavailable } from "./core-replay";
import { isReplayRefusalResponse, settleOperatorReplacement, UPSTREAM_RESET_REPLAY_REFUSED_CODE } from "../../lib/upstream-retry";
import { attributeFinalRequest } from "../request-log-failure-attribution";
import { createComboProtocolLanes, dispatchNativeComboChild } from "./core-combo-native";
import { createJevModelInvoker } from "./jev-model-invoke";
import { comboRequestedEffortLabel } from "./combo-requested-effort";
import { clientWireOf } from "../inference/client-wire";
import { resolveContextPrincipal } from "../auth-cors";
/**
* Sends one combo target may run on its own before the ladder moves on. A target is a whole
* request as far as its own provider is concerned, so this is the guarded profile's base
* allowance rather than a separate number to keep in sync.
*/
export const COMBO_TARGET_BASE_SENDS = CODEX_TEXT_GUARDED_BUDGET_POLICY.baseSendAllowance;
/**
* OCX-11: where a combo target physically dispatches, after provider aliases and
* blockedModelRedirects. A target that does not resolve keeps its configured selector; its
* dispatch fails on its own.
*/
function resolvedComboDestination(config: OcxConfig, target: { provider: string; model: string }): { provider: string; model: string } {
try {
const route = routeConcreteModel(config, `${target.provider}/${target.model}`);
return { provider: route.providerName, model: route.modelId };
} catch {
return { provider: target.provider, model: target.model };
}
}
export function cooledPoolAccountLabel(config: OcxConfig, providerName: string, modelId: string, label: string | undefined): string | undefined {
if (!label) return undefined;
const instance = configuredAnthropicInstance(config, providerName);
if (instance && config.providers[providerName]?.authMode === "oauth") {
const matches = getAccountSet(instance)?.accounts.filter(account =>
formatAnthropicProviderForLog(instance, account.id) === label) ?? [];
return matches.length === 1 && anthropicRoutingFor(instance).getAnthropicAccountHealthSnapshot(matches[0]!.id) ? label : undefined;
}
const provider = config.providers[providerName];
if (!provider || !isCanonicalOpenAiForwardProvider(provider)) return undefined;
const quotaScope = codexQuotaScopeForModel(modelId);
// The main account logs as `<provider>-main` and is not a `codexAccounts` entry (#8880). In pool
// mode the pool rotates past a cooled main itself, so its 429 is account evidence exactly like a
// pool account's, and parking the target would black out the siblings and main's own recovery for
// the upstream Retry-After (up to 24h). Direct mode serves main without that check, so there the
// target cooldown stays the only guard against re-sending to a spent account.
if (label === `${providerName}-main`) {
return providerCodexAccountMode(providerName, provider) === "pool"
&& getCodexQuotaHealthSnapshot(MAIN_CODEX_ACCOUNT_ID, quotaScope) ? label : undefined;
}
const matches = (config.codexAccounts ?? []).filter(account =>
`${providerName}-${codexAccountLogLabel(account)}` === label);
return matches.length === 1
&& getCodexQuotaHealthSnapshot(matches[0]!.id, quotaScope)
? label : undefined;
}
/**
* The generic OAuth pool's counterpart of `cooledPoolAccountLabel`. Its 429 names one account
* through `accountLogLabel`, but the per-request account budget can end the pool's own rotation
* before the last refused account is recorded. Hand that account to the pool's rotator, which
* cools it under the pool's own Retry-After policy, and spare the target only when the pool still
* has an eligible sibling. The rotator only peeks round-robin here: nothing is sent to that sibling.
* A lone account or an all-cooled pool returns null and cools the target.
*/
function cooledGenericOAuthAccountLabel(
config: OcxConfig, providerName: string, modelId: string, label: string | undefined, retryAfter: string | undefined,
): string | undefined {
const provider = config.providers[providerName];
if (!label || !provider || !isGenericFailoverProvider(providerName, provider)) return undefined;
const base = baseProviderLabel(providerName);
const matches = getAccountSet(providerName)?.accounts.filter(account =>
oauthAccountLogLabel(account.id, base) === label) ?? [];
return matches.length === 1
&& rotateGenericOAuthAccountOn429(config, providerName, matches[0]!.id, retryAfter, Date.now(), modelId, false)
? label : undefined;
}
/**
* A 402 credit-balance refusal names one Anthropic OAuth account -- the evidence the pool already
* accepts on a 403 -- but the pool rotates only on 401/403/429, so the 402 reaches the combo with
* that account still selectable. Cool it under the pool's entitlement backoff and spare the target
* only while a sibling is eligible; a lone account or an exhausted pool still cools the target.
*/
function creditRefusedAnthropicAccountLabel(
config: OcxConfig, providerName: string, modelId: string, label: string | undefined,
message: string, code: string | null | undefined, response: Response,
): string | undefined {
const instance = configuredAnthropicInstance(config, providerName);
if (!label || !instance || config.providers[providerName]?.authMode !== "oauth"
|| !isAnthropicBillingFailure(402, message, code)) return undefined;
const routing = anthropicRoutingFor(instance);
const matches = getAccountSet(instance)?.accounts.filter(account =>
formatAnthropicProviderForLog(instance, account.id) === label) ?? [];
return matches.length === 1
&& anthropicRefusalCredentialIsCurrent(response, instance, matches[0]!.id)
&& routing.recordAnthropicAccountRefusal(config, matches[0]!.id, 403, null)
&& routing.getEligibleAnthropicAccounts(Date.now(), modelId).length > 0
? label : undefined;
}
/**
* True only for the Anthropic OAuth pool's OWN "all accounts cooled" 429. Its Retry-After is the
* earliest per-account cooldown restated (`getAnthropicPoolRetryAfterSeconds`), which the pool
* keeps enforcing locally, so it must not also park the combo target: an account added, resumed or
* cleared a minute later would otherwise sit ignored until the target expired, up to the 24h
* server-delay ceiling.
*
* Provenance, not just current state: the target must be the OAuth pool, no account may have been
* identified for the failure, and the pool must be holding the wait right now. An upstream 429 on
* a pool account always cools and names that account, and an API-key provider never qualifies, so
* a genuine upstream Retry-After still parks the target in full.
*/
export function isAnthropicPoolLocalRefusal(
config: OcxConfig,
providerName: string,
status: number,
failedAccount: string | undefined,
now = Date.now(),
): boolean {
const instance = configuredAnthropicInstance(config, providerName);
return instance !== undefined
&& config.providers[providerName]?.authMode === "oauth"
&& status === 429
&& failedAccount === undefined
&& anthropicRoutingFor(instance).getEligibleAnthropicAccounts(now).length === 0
&& anthropicRoutingFor(instance).getAnthropicPoolRetryAfterSeconds(now) !== null;
}
/**
* A combo's execution policy is DECLARED by the combo, not inherited from the single-target
* profile.
*
* `maxTargetTransitions: 1` and `maxAlternateTargetSends: 1` describe an account move, and
* applying them to a combo would refuse the second hop of a three-target combo -- which is why
* combo was left off `reserveDispatch` when the per-request split landed. The transitions a
* combo may make are exactly the targets it declares minus the one it starts on. What stays
* capped is the TOTAL: the first target's full ladder, one send for every further declared
* target, and the one shared final-recovery reserve. A one-target combo reduces to the guarded
* profile exactly, and a three-target combo whose every target fails hard reaches upstream six
* times instead of the twelve #4546 measured.
*/
export function comboExecutionBudgetPolicy(declaredTargets: number): RequestExecutionBudgetPolicy {
const targets = Math.max(1, Math.trunc(declaredTargets));
const hops = targets - 1;
const reserve = CODEX_TEXT_GUARDED_BUDGET_POLICY.finalRecoveryAllowance;
const total = COMBO_TARGET_BASE_SENDS + hops + reserve;
return {
maxTotalModelSends: total,
baseSendAllowance: total - reserve,
finalRecoveryAllowance: reserve,
maxAlternateTargetSends: Math.max(1, hops),
maxTargetTransitions: Math.max(1, hops),
};
}
/**
* A budget scope that keeps its own recovery ledgers but spends the SAME request-wide counter.
*
* The sharing has to happen inside the factory. Redefining `used` as an accessor onto the parent
* only shared what callers read from the outside: `remainingBaseSends`, the total check and the
* reserve test all consult the factory's own private counter, which an overridden property
* cannot reach. Each derived scope therefore admitted dispatches as though the request had spent
* nothing, and the per-target holdback below -- expressed against `maxTotalModelSends` -- had
* nothing to hold back from.
*
* `deriveRequestExecutionBudget` binds the scope to the parent's real ledger, including pending
* externally-counted bookings and the durable-spend observer, all of which must travel together.
* A pending booking is a send already counted in the total and waiting for its reporter, and the
* observer books by watching that same counter move (#4707) -- so a scope that spent the counter
* without carrying the observer would move it without booking, and this combo's child sends
* would go missing from the spend ledger. The reserve, alternate-target and transition ledgers
* stay per-scope on purpose: a combo target's account failover is its own recovery decision,
* while the request total still bounds every target together.
*/
export function deriveSendBudgetScope(
parent: RequestExecutionBudget,
policy: RequestExecutionBudgetPolicy,
): RequestExecutionBudget {
return deriveRequestExecutionBudget(parent, policy);
}
/**
* The ladder one combo target may run, expressed as an allowance on the request-wide counter.
*
* `used + COMBO_TARGET_BASE_SENDS` gives this target its own ladder from wherever the request
* already stands, and the clamp holds back one send for each target still declared after it: a
* first target that 5xx-streaks must not eat the send the last declared target is entitled to.
* That guarantee is the difference between a per-target policy and a shared pool the first
* target drains.
*/
export function comboTargetSendBudget(
comboScope: RequestExecutionBudget,
targetsDeclaredAfterThisOne: number,
): RequestExecutionBudget {
const policy = comboScope.policy;
const heldForLaterTargets = Math.max(0, targetsDeclaredAfterThisOne);
const ceiling = Math.max(1, policy.maxTotalModelSends - heldForLaterTargets);
return deriveSendBudgetScope(comboScope, {
maxTotalModelSends: policy.maxTotalModelSends,
baseSendAllowance: Math.min(ceiling, comboScope.used + COMBO_TARGET_BASE_SENDS),
finalRecoveryAllowance: policy.finalRecoveryAllowance,
// Within one target the account-move shape is unchanged: three same-account sends plus one
// alternate is the recovery live traffic depends on, and a combo does not widen it.
maxAlternateTargetSends: CODEX_TEXT_GUARDED_BUDGET_POLICY.maxAlternateTargetSends,
maxTargetTransitions: CODEX_TEXT_GUARDED_BUDGET_POLICY.maxTargetTransitions,
});
}
interface JevComboChoice {
pick: ComboPick;
candidate: JevCandidate;
}
/** Enumerate this request's eligible targets without reserving another recovery pass. */
function eligibleJevComboChoices(
config: OcxConfig,
comboId: string,
eligible: (target: NonNullable<ReturnType<typeof getCombo>>["targets"][number]) => boolean,
now: number,
cooldownReprobeTargets?: ComboPick["cooldownReprobeTargets"],
): JevComboChoice[] {
const combo = getCombo(config, comboId);
if (!combo) return [];
const excluded = new Set<string>();
const choices: JevComboChoice[] = [];
const reserved = cooldownReprobeTargets ? Object.entries(cooldownReprobeTargets) : undefined;
while (excluded.size < combo.targets.length) {
const pick = pickComboTarget(config, comboId, {
exclude: excluded, eligible, now, allowCooldownReprobe: false, cooldownReprobeTargets: reserved,
});
if (!pick) break;
const key = targetKey(pick.target);
excluded.add(key);
// The TypeSafe row owns a decision credential, not an inference transport.
if (pick.target.provider === JEV_PROVIDER_ID) continue;
const identity = jevChoiceEfforts(config, pick.target, combo.decisionQuotaSignals === true);
if (!identity) continue;
choices.push({
pick: { ...pick, attempted: [key] },
candidate: {
key,
provider: pick.target.provider,
model: pick.target.model,
...identity,
modelProfile: pick.target.modelProfile,
},
});
}
// #5691: the synchronous pick above does not defer emergency-only targets, so apply the
// same rule here — withhold them from JEV while any normal target is offered, never when
// they are all that remains.
if (combo.cooldownWaitPolicy === "before-last-resort" && choices.some(choice => !choice.pick.target.lastResort)) {
return choices.filter(choice => !choice.pick.target.lastResort);
}
return choices;
}
/** Dispatch a Responses combo within its shared send budget and preserve terminal child failures. */
export async function executeComboResponses(
req: Request,
rawBody: unknown,
comboId: string,
config: OcxConfig,
logCtx: RequestLogContext,
options: HandleResponsesOptions & { translatorBudget: TranslatorBudget },
requestDispatchers: ResponsesDispatchers,
): Promise<Response> {
const clientModelLabel = options.clientModelLabel ?? clientFacingModelLabel(undefined);
const responseModel = clientFacingModelText(clientModelLabel);
const requestedModel = options.mainHardLockFallbackOverride?.sourceModel
?? (typeof (rawBody as { model?: unknown } | null)?.model === "string"
? (rawBody as { model: string }).model
: `combo/${comboId}`);
if (requestedModel !== responseModel) options = { ...options, clientResponseModelLabel: clientModelLabel };
Object.assign(logCtx, {
requestedModel: responseModel,
model: responseModel,
provider: "combo",
comboId,
});
const combo = getCombo(config, comboId);
if (!combo) {
return formatErrorResponse(404, "invalid_request_error", "Unknown combo");
}
// Admission reads one detached copy of the request-start config. Mid-request edits to
// capabilities, sidecars, protocols or the roster apply to the next request. Only spend
// authority is read live, from the root config that management writes replace.
const admissionSnapshot = snapshotComboAdmission(config, comboId);
// Every image probe and the child it admits plan with these request-start sidecar settings.
const comboVisionSidecar = { settings: admissionSnapshot.vision };
const liveConfig = advisorPlanRootConfig(config);
// Resolve against the original request once; every bridge candidate receives the same trusted
// result after its provisional Authorization is removed, including an explicitly keyless result.
const replayPrincipal = options.replayPrincipal
?? { clientPrincipalId: resolveContextPrincipal(req, config, options.admission) };
// The caller's model scope, resolved once from the request options. A capability-authenticated
// internal request carries the caller's captured scope on options.admissionScope even though
// its own admission is the host's broad key; recomputing from options.admission would lose it.
const admissionScope = options.admissionScope ?? resolveAdmissionModelScope(config, options.admission);
// Every paid send also needs the key's current scope: a narrowed key never widens back.
const currentAdmissionScope = () => intersectAdmissionModelScopes(admissionScope,
resolveAdmissionModelScope(liveConfig, options.admission));
// Present only when an opted-in ingress supplied a native source; otherwise every child
// takes the bridge below exactly as before.
const protocolLanes = createComboProtocolLanes({
source: options.protocolSource,
req,
config,
logCtx,
admissionScope,
droidDefaultEffort: options.droidDefaultEffort,
comboId,
targets: combo.targets,
});
// The ladder's own scope, derived from what this combo DECLARES. It shares the request-wide
// counter with the holder that arrived on options -- a combo child already inherited that
// counter, but nothing read it as a limit across targets -- while its transition and
// alternate-target ledgers come from the target list rather than from the single-target
// account-move profile (#4546).
const comboSendScope = isRequestExecutionBudget(options.sendBudget)
? deriveSendBudgetScope(options.sendBudget, comboExecutionBudgetPolicy(combo.targets.length))
: undefined;
// Expand previous_response_id before image policy and child dispatch so a
// continuation that only references prior images still fails closed when
// imageInput is disabled (and so targets see the full replayed input).
const inboundClientThreadId = req.headers.get("x-codex-parent-thread-id")?.trim() || undefined;
const inboundOwnThreadId = req.headers.get("thread-id")?.trim() || undefined;
const strictReplay = options.plaintextV2Decision ?? isPlaintextV2AgentMessagesEnabled(config);
const { replayOwnerKey, replayConnectionScope } = selectResponseReplayOwner(strictReplay, replayPrincipal.clientPrincipalId, inboundOwnThreadId, options);
const body = expandPreviousResponseInput(rawBody, strictReplay ? inboundOwnThreadId : inboundClientThreadId, replayOwnerKey);
const replayFailure = previousResponseReplayFailure(body);
if (replayFailure?.reason === "scope_mismatch") {
console.warn("[opencodex] refusing continuation because the client task scope does not match replay state");
}
// Local replay failures require full client replay.
if (replayFailure) {
failLinkTurnExpansion(options.linkTurn, req, logCtx, body, replayFailure.reason);
return formatErrorResponse(
400,
"previous_response_not_found",
"Continuation state is unavailable or corrupt; resend the full conversation without previous_response_id.",
);
}
// Missing state returns the original body without a failure marker. Reject
// that unresolved continuation for image-disabled combos so a target cannot
// resolve prior images out of band. A successful expansion yields a new
// object (still carrying previous_response_id) and must not be treated as
// unresolved — text-only stored continuations remain allowed.
const requestedPreviousId = typeof (rawBody as { previous_response_id?: unknown } | null)?.previous_response_id === "string"
? (rawBody as { previous_response_id: string }).previous_response_id
: "";
const unresolvedPrevious = requestedPreviousId.trim().length > 0 && body === rawBody;
// Remote Link (design T4 5 and 9.1): the combo's own expansion is the request's one capture point; its
// children replay a snapshot and skip theirs.
observeLinkTurnExpansion(options.linkTurn, req, logCtx, body,
requestedPreviousId.trim().length > 0 ? (unresolvedPrevious ? "unexpanded" : "chained") : "none");
// Live metered consent, checked before every paid send.
const maySpendOnTarget = (target: (typeof combo.targets)[number]): boolean =>
!target.metered || admissionMayUseMeteredComboTargets(liveConfig, options.admission, liveConfig.combos?.[comboId]);
const mayUseTarget = (target: (typeof combo.targets)[number]): boolean =>
maySpendOnTarget(target) && (combo.strategy !== "jev" || target.provider !== JEV_PROVIDER_ID);
// The combo ladder owns the whole logical request, so the catalog diagnostic is counted here for
// combo-routed turns; children run as concrete selections and would otherwise never report it.
// Counting after the replay expansion keeps restored history out of the tally.
if ((options.inboundWire ?? "responses") === "responses") {
warnEagerCodexToolCatalog(body, req.headers, {
surface: eagerCodexToolCatalogSurface(body, options.compactionRecoveryKind),
replayPrefixLength: previousResponseRestoredPrefixLength(body),
logicalRequest: logCtx,
});
}
const comboReplaySnapshot = {
sourceBody: body,
previousResponseInputExpanded: body !== rawBody
&& typeof (body as { previous_response_id?: unknown }).previous_response_id === "string",
providerContinuation: body !== rawBody && requestedPreviousId
? previousResponseProviderState(requestedPreviousId)
: undefined,
recoveredPlaintext: false,
};
const reasoningReplayConversationId = reasoningReplayConversationIdFromResponsesRequest({
clientThreadId: inboundClientThreadId,
threadIdHeader: req.headers.get("thread-id"),
sessionIdHeader: sessionIdHeaderFromRequest(req.headers),
});
const reasoningReplayEligible = (target: (typeof combo.targets)[number]): boolean => {
try {
const route = routeConcreteModel(config, `${target.provider}/${target.model}`);
const unavailable = mandatoryResponsesReasoningReplayUnavailable({
body,
clientThreadId: reasoningReplayConversationId,
clientPrincipalId: replayPrincipal.clientPrincipalId,
providerName: route.providerName,
provider: route.provider,
adapterName: route.provider.adapter,
modelId: route.modelId,
});
return !unavailable;
} catch {
// Routing failures are not evidence of replay incompatibility. Keep the target eligible so
// the existing selection and dispatch path preserves its original routing failure surface.
return true;
}
};
const adoptFailedChildLog = (childLog: RequestLogContext): void => {
// Attempts remain the complete physical history; the logical row mirrors the failed
// target whose response is returned, including an earlier quota refusal on exhaustion.
// The ingress finalizer cannot stamp this child once activeAttempt is cleared below.
if (childLog.activeAttempt) {
attributeFinalRequest({
status: childLog.activeAttempt.status,
terminalSource: childLog.terminalSource,
transportPhase: childLog.transportPhase,
causeHint: childLog.causeHint,
outputObserved: childLog.firstOutputMs !== undefined,
locallyAnswered: childLog.localTerminalReason !== undefined,
attempt: childLog.activeAttempt,
});
}
carryProxyErrorContext(childLog, logCtx);
Object.assign(logCtx, childLog, {
client: logCtx.client,
requestedModel: responseModel,
model: responseModel,
provider: "combo",
comboId,
routeDecision: logCtx.routeDecision,
attempts: logCtx.attempts,
activeAttempt: undefined,
activeAttemptStartedAt: undefined,
});
carryLocalFailureState(childLog, logCtx);
if (requestedModel !== responseModel) {
projectLocalModelRefusalLog(logCtx, clientModelLabel);
logCtx.model = responseModel; logCtx.requestedModel = responseModel;
if (options.clientModelLabel) logCtx.jevDecision = undefined;
}
};
const unreadableEncryptedAgentTask = hasUnreadableEncryptedAgentTask(
(body as { input?: unknown } | undefined)?.input,
);
const canDecryptUnreadableAgentTask = (target: (typeof combo.targets)[number]): boolean => {
const provider = config.providers[target.provider];
if (!provider || provider.disabled === true) return false;
try {
const route = routeConcreteModel(config, `${target.provider}/${target.model}`);
return isCanonicalOpenAiForwardProvider(route.provider);
} catch {
return false;
}
};
let comboPayloadReadable = false;
const payloadEligible = (target: (typeof combo.targets)[number]): boolean =>
comboPayloadReadable || !unreadableEncryptedAgentTask || canDecryptUnreadableAgentTask(target);
const museToolEligible = (target: (typeof combo.targets)[number]): boolean => {
if (!hasMandatoryToolChoice(body)) return true;
try {
const selector = `${target.provider}/${target.model}`, { fastRow, effortRow } = parseSyntheticRowId(selector, config);
const route = routeConcreteModel(config, fastRow?.baseId ?? effortRow?.baseId ?? selector);
const modelId = resolveOpenAiVirtualModel(route.providerName, route.modelId)?.wireModelId ?? route.modelId;
const inboundWire = options.inboundWire ?? "responses";
const policy = captureRouteStaticPolicy(route.providerName, modelId, route.provider,
route.staticPolicy.effectiveAlias, inboundWire);
const provider = resolveWireProtocolOverride(route.providerName, modelId, route.provider, inboundWire, policy);
// Copilot's Auto account may settle on a different wire; the child checks that result.
if (route.providerName === "github-copilot" && provider.authMode !== "forward") return true;
return provider.adapter === "openai-chat" ? chatCanPreserveMandatoryToolChoice(body, provider, modelId)
: provider.adapter !== "openai-responses" || !isMetaAiResponsesDestination(buildResponsesTransport(provider, { headers: req.headers }).url);
} catch {
return true;
}
};
const onlyMuseToolIncompatible = (): boolean => {
const enabled = combo.targets.filter(target => config.providers[target.provider]?.disabled !== true);
return enabled.length > 0 && enabled.every(target => !museToolEligible(target));
};
// A mandatory tool_choice no target preserves is unsupported (#7965), but shared exclusion evidence
// (provider state, quota, live cooldowns) keeps precedence, exactly as in the readable reasons.
const unsupportedToolChoice = (attempted: number) => comboUnavailableDiagnostics(combo.targets.length, attempted,
combo.targets.map(target => comboTargetUnavailableCause(config, comboId, target, museToolEligible) ?? "unsupported"));
const capabilityCandidate = (target: (typeof combo.targets)[number]): boolean =>
mayUseTarget(target)
&& museToolEligible(target)
&& reasoningReplayEligible(target)
&& (protocolLanes?.pickable(target) ?? true);
const unservableImageResponse = (): Response =>
markProxyError(formatErrorResponse(400, "invalid_request_error", "No target of this combo can accept image input"));
const warnComboImageOmission = (): void =>
console.warn("[opencodex] combo has no image-capable target; images will be omitted");
const resolveCapabilityRoute = (target: Pick<(typeof combo.targets)[number], "provider" | "model">) => {
try {
const route = routeConcreteModel(config, `${target.provider}/${target.model}`);
const provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, options.inboundWire);
return { ...route, provider };
} catch { return undefined; }
};
const admitCombo = async () => {
if (combo.imageInput === "disabled" && unresolvedPrevious) {
markLinkTurnMissing(logCtx);
return formatErrorResponse(
400,
"previous_response_not_found",
"Continuation state is unavailable or corrupt; resend the full conversation without previous_response_id.",
);
}
if (combo.imageInput === "disabled" && comboRequestHasImageInput(body)) {
return formatErrorResponse(400, "invalid_request_error", "This combo does not accept image input");
}
const metadata = {
providers: admissionSnapshot.providers,
customModels: admissionSnapshot.customModels,
providerContextCaps: admissionSnapshot.providerContextCaps,
visionSidecar: admissionSnapshot.vision,
};
const capability = await comboCapabilityGate(metadata, combo, body,
target => {
const route = resolveCapabilityRoute(target);
return route && {
providerName: route.providerName, modelId: route.modelId, codexAccountId: route.codexAccountId,
provider: snapshotComboAdmissionProvider(route.provider),
};
},
(target, route, parsed) => capabilityCandidate(target)
&& (!admissionScope || !!route && routeAllowedByScope(admissionScope, route))
&& (options.anthropicHostedAdvisorSelection !== "selected" || !!route && admitsHostedAdvisor(
route.provider, scopedAnthropicServerTools(admissionScope, route, options.anthropicServerTools), parsed?.context.tools,
)),
(route, parsed) => canDescribeComboImages(
{ config, req, options: { ...options, admissionScope, comboVisionSidecar } }, route, parsed));
if (capability.unservable === "audio") {
return formatErrorResponse(400, "invalid_request_error", "No target of this combo can accept audio input");
}
if (capability.unservable && combo.onUnservable === "reject") {
return capability.unservable === "context"
? formatErrorResponse(400, "invalid_request_error", "No target of this combo has a context window large enough for this request")
: unservableImageResponse();
}
return capability;
};
const capability = await admitCombo();
if (capability instanceof Response) return capability;
if (capability.unservable === "image") warnComboImageOmission();
if (capability.unservable === "context") console.warn("[opencodex] combo has no target whose context window fits; sending to the largest");
const visionRejectedTargets = new Set<string>();
let omittingImages = capability.unservable === "image";
const useImageDegradation = (target: (typeof combo.targets)[number]): boolean =>
payloadEligible(target) && capabilityCandidate(target) && capability.imageDegradationEligible(target);
// Recovery can replace unreadable encrypted input, but cannot relax other admission checks.
const recoveryEligible = (target: (typeof combo.targets)[number]): boolean =>
capabilityCandidate(target) && (omittingImages && capability.unservable !== "image"
? capability.imageDegradationEligible(target)
: !visionRejectedTargets.has(targetKey(target)) && capability.eligible(target));
const targetEligible = (target: (typeof combo.targets)[number]): boolean =>
payloadEligible(target) && recoveryEligible(target);
const onlyReplayIncompatibleTargetsRemain = (excluded: Iterable<string> = []): boolean => {
const excludedKeys = new Set(excluded);
const remaining = combo.targets.filter(target => {
const provider = config.providers[target.provider];
return provider?.disabled !== true
&& !excludedKeys.has(targetKey(target))
&& payloadEligible(target);
});
return remaining.length > 0 && remaining.every(target => !reasoningReplayEligible(target));
};
let encryptedTaskRecoveryAttempted = false;
let recoveryFailureReason: AgentTaskRecoveryFailureReason | undefined;
let storedPool401ReplayDispatched = false;
const recovery = agentTaskRecoveryConfig(config);
const encryptedTaskRecoveryAdmitted = (options.inboundWire ?? "responses") === "responses"
&& isThreadSpawnRequest(req.headers) && !!recovery && !options.comboAttempt;
const recoverUnreadableEncryptedTask = async (): Promise<boolean> => {
if (encryptedTaskRecoveryAttempted) return false;
encryptedTaskRecoveryAttempted = true;
if (!encryptedTaskRecoveryAdmitted || !recovery) {
discardEncryptedAgentTaskRecovery(
req,
(body as { input?: unknown } | undefined)?.input,
config,
{ parentThreadId: inboundClientThreadId },
);
return false;
}
let recovered = false;
try {
const result = await recoverEncryptedAgentTaskWithResult(
req,
(body as { input?: unknown } | undefined)?.input,
recovery,
config,
{ parentThreadId: inboundClientThreadId, abortSignal: options.abortSignal },
);
recovered = result.recovered;
recoveryFailureReason = result.recovered ? undefined : result.reason;
} catch {
recovered = false;
recoveryFailureReason = undefined;
}
// Recovery has the same in-place input mutation contract as the direct routed path.
if (
!recovered
|| hasUnreadableEncryptedAgentTask((body as { input?: unknown } | undefined)?.input)
) {
discardEncryptedAgentTaskRecovery(
req,
(body as { input?: unknown } | undefined)?.input,
config,
{ parentThreadId: inboundClientThreadId },
);
return false;
}
comboPayloadReadable = true;
comboReplaySnapshot.recoveredPlaintext = true;
return true;
};
const initialNow = Date.now();
const pickWithWait = (pickOptions: {
exclude?: Iterable<string>;
eligible?: (target: NonNullable<typeof combo>["targets"][number]) => boolean;
allowCooldownReprobe?: boolean;
/** This request's own cooldown-reprobe reservation, carried through its failover hops. */
cooldownReprobeTargets?: Iterable<readonly [string, number]>;
now?: number;
}) => pickComboTargetWithWait(config, comboId, {
...pickOptions,
// Every pick, including the recovery picks that skip `targetEligible`, keeps metered
// targets away from callers that may not spend on them.
eligible: target => maySpendOnTarget(target) && (pickOptions.eligible?.(target) ?? true),
waitForCooldownMs: combo.waitForCooldownMs,
abortSignal: options.abortSignal,
});
// An in-flight tool loop stays on the target that issued its calls while that target is still
// selectable (#7298). Override routes never record a lane target, so they never pin either.
const toolLoopPin = options.compactionRoutingOverride || options.mainHardLockFallbackOverride
? undefined
: toolLoopPinnedPick({
config,
comboId,
lane: sessionLaneIdFromRequest(req.headers),
body,
eligible: target => maySpendOnTarget(target) && targetEligible(target),
now: initialNow,
});
let pick = toolLoopPin ?? await pickWithWait({
eligible: targetEligible,
now: initialNow,
});
// Opt-in JEV session pin (#7525); override routes neither read nor write it, like the lane recall.
const jevPin = options.compactionRoutingOverride || options.mainHardLockFallbackOverride
? undefined
: jevSessionPinScope({ combo, comboId, admission: options.admission, lane: sessionLaneIdFromRequest(req.headers) });
// A tool-loop continuation never asks JEV again, so under `decide` it keeps the effort the
// decision set for its turn while the target still offers it. Without this the rest of the
// turn ran at the caller's effort and only the first request at the decided one.
let toolLoopTurnEffort: ComboTurnEffort | undefined;
if (toolLoopPin && combo.strategy === "jev" && combo.jevEffortMode !== "client") {
const carried = recallComboTurnEffortForLane(sessionLaneIdFromRequest(req.headers), comboId, toolLoopPin.target);
const offered = carried ? jevChoiceEfforts(config, toolLoopPin.target, false)?.reasoningEfforts : undefined;
if (carried && offered && (carried.effort === null ? offered.length === 0 : offered.includes(carried.effort))) {
toolLoopTurnEffort = carried;
}
}
if (unreadableEncryptedAgentTask && !pick) {
pick = await pickWithWait({
eligible: recoveryEligible,
allowCooldownReprobe: encryptedTaskRecoveryAdmitted,
now: initialNow,
});
if (!pick) {
discardEncryptedAgentTaskRecovery(
req,
(body as { input?: unknown } | undefined)?.input,
config,
{ parentThreadId: inboundClientThreadId },
);
if (!options.abortSignal?.aborted && onlyMuseToolIncompatible()) {
return comboUnavailableResponse("No available targets for combo; targets cannot preserve mandatory tool_choice",
{ diagnostics: unsupportedToolChoice(0) });
}
return options.abortSignal?.aborted
? clientCancelledResponse()
: comboUnavailable(comboId, undefined,
comboExclusion(config, comboId, recoveryEligible));
}
if (!(await recoverUnreadableEncryptedTask())) {
return options.abortSignal?.aborted
? clientCancelledResponse()
: unreadableEncryptedAgentTaskResponse(recoveryFailureReason);
}
}
if (!pick) {
// Every enabled candidate skipped as unrepresentable: the ingress refusal, with no send.
const protocolRefusal = protocolLanes?.refusal();
if (protocolRefusal) return protocolRefusal;
if (onlyReplayIncompatibleTargetsRemain()) return targetIncompatibleResponse();
if (!options.abortSignal?.aborted && onlyMuseToolIncompatible()) {
return comboUnavailableResponse("No available targets for combo; targets cannot preserve mandatory tool_choice",
{ diagnostics: unsupportedToolChoice(0) });
}
return options.abortSignal?.aborted
? clientCancelledResponse()
: comboUnavailable(comboId, undefined, comboExclusion(config, comboId, targetEligible));
}
// OCX-11: an ordered failover combo that starts on a later target than its first one, for any
// reason (cooling down, provider disabled, cached quota spent, ineligible for this request),
// makes a proactive hop, so the fallback policy decides before anything is sent. Both ends are
// the resolved destinations, after provider aliases and blockedModelRedirects.
const primaryTarget = combo.targets[0];
// An allowed hop is recorded only once its dispatch is admitted below.
let pendingHopCommit: (() => void) | undefined;
if (!toolLoopPin && (combo.strategy ?? "failover") === "failover" && primaryTarget
&& targetKey(primaryTarget) !== targetKey(pick.target)) {
const primaryCooling = isComboTargetInCooldown(comboId, primaryTarget, initialNow);
const proactive = guardFallbackHop(config, {
site: "combo",
route: `combo/${comboId}`,
aliases: [requestedModel],
from: resolvedComboDestination(config, primaryTarget),
to: resolvedComboDestination(config, pick.target),
trigger: primaryCooling ? "cooldown" : comboTargetSkipTrigger(config, primaryTarget, initialNow),
admission: options.admission,
retryAfter: primaryCooling ? comboCooldownRetryAfterSeconds(comboId, initialNow) ?? null : null,
now: initialNow,
});
if (!proactive.ok) return proactive.response;
pendingHopCommit = proactive.commit;
}
let jevDecision: JevDecision | undefined;
let failedPinEffortDecision: JevDecision | undefined;
if (combo.strategy === "jev" && !toolLoopPin) {
// Live spend authority only: consent and the key's current scope.
const spendAllowed = (scope: typeof admissionScope) => (target: (typeof combo.targets)[number]): boolean => {
if (!maySpendOnTarget(target)) return false;
if (!scope) return true;
try {
return routeAllowedByScope(scope, routeConcreteModel(config, `${target.provider}/${target.model}`));
} catch {
return false;
}
};
// The decision call is a paid send: offer only members that live consent and scope still admit.
const decisionScope = currentAdmissionScope();
const choices = eligibleJevComboChoices(config, comboId,
target => targetEligible(target) && spendAllowed(decisionScope)(target), Date.now(), pick.cooldownReprobeTargets);
const first = choices[0];
if (!first) {
return comboUnavailable(comboId, undefined, comboExclusion(config, comboId, target =>
targetEligible(target) && target.provider !== JEV_PROVIDER_ID && jevChoiceEfforts(config, target, false) !== undefined));
}
const fallbackFor = (choice: JevComboChoice): Pick<JevDecision, "targetKey" | "effort"> => {
const effort = resolveEffortAtOrBelow("medium", choice.candidate.reasoningEfforts);
return {
targetKey: choice.candidate.key,
effort: effort && isCodexReasoningEffort(effort) ? effort as OcxComboDefaultEffort : null,
};
};
const fallback = fallbackFor(first);
const decisionStartedAt = Date.now();
const pinReuse = jevPin?.reuse(
choices.map(choice => choice.candidate),
combo.decisionQuotaSignals === true ? { config, tiers: combo.decisionQuotaTiers } : undefined,
);
const decide = (candidates: JevCandidate[], fallbackDecision: Pick<JevDecision, "targetKey" | "effort">) =>
resolveJevComboDecision({
body,
candidates,
fallback: fallbackDecision,
config,
isDestinationAllowed: (providerName, modelId) => routeAllowedByScope(
decisionScope, { providerName, modelId },
),
...(combo.decisionQuotaSignals === true ? { decisionQuotaSignals: true, decisionQuotaTiers: combo.decisionQuotaTiers } : {}),
...(combo.decisionProvider ? { decisionProvider: combo.decisionProvider } : {}),
...(combo.decisionModel
? {
decisionModel: combo.decisionModel,
invokeModel: createJevModelInvoker({
req,
config,
options: { ...options, admissionScope: decisionScope },
handleResponses: requestDispatchers.handleResponses,
}),
}
: {}),
...(combo.decisionTimeoutMs !== undefined ? { timeoutMs: combo.decisionTimeoutMs } : {}),
signal: options.abortSignal,
});
let decision: JevDecision;
let awaitedPinEffort = false;
if (pinReuse?.decision) {
const pinned = pinReuse.decision;
decision = pinned;
// `effort: "per-turn"` keeps the pinned target and asks only for its effort, offering the
// pinned target alone. Anything but an applied answer for that target keeps the pinned effort.
const pinnedChoice = combo.sessionPin?.effort === "per-turn" && combo.jevEffortMode !== "client"
? choices.find(choice => choice.candidate.key === pinned.targetKey)
: undefined;
if (pinnedChoice && pinnedChoice.candidate.reasoningEfforts.length > 1) {
awaitedPinEffort = true;
decision = { ...pinned, pinReason: "session_effort" };
const fallback = { targetKey: pinned.targetKey, effort: pinned.effort };
try {
const effortDecision = await decide([pinnedChoice.candidate], fallback);
if (effortDecision.gate === "apply" && effortDecision.targetKey === pinned.targetKey) {
decision = { ...effortDecision, pinned: true, pinReason: "session_effort" };
} else {
failedPinEffortDecision = {
...effortDecision, ...fallback,
gate: effortDecision.gate === "apply" ? "invalid" : effortDecision.gate,
};
}
} catch {
if (options.abortSignal?.aborted) return clientCancelledResponse();
failedPinEffortDecision = {
...fallback, backend: jevDecisionBackendFor(combo), gate: "network",
latencyMs: Math.max(0, Date.now() - decisionStartedAt),
};
}
}
} else try {
decision = await decide(choices.map(choice => choice.candidate), fallback);
} catch (error) {
if (options.abortSignal?.aborted) return clientCancelledResponse();
decision = {
backend: jevDecisionBackendFor(combo),
...fallback,
gate: "network",
latencyMs: Math.max(0, Date.now() - decisionStartedAt),
};
}
let selected = choices.find(choice => choice.candidate.key === decision.targetKey) ?? first;
const recordDecision = (observedDecision: JevDecision) => logCtx.jevDecision = !options.clientModelLabel || requestedModel === responseModel ? normalizePersistedJevDecision({
version: 1,
comboId,
selected: {
provider: selected.pick.target.provider,
model: selected.pick.target.model,
effort: decision.effort,
},
gate: observedDecision.gate,
latencyMs: observedDecision.latencyMs,
backend: observedDecision.backend,
...(observedDecision.confidence !== undefined ? { confidence: observedDecision.confidence } : {}),
...(observedDecision.chosenProbability !== undefined
? { chosenProbability: observedDecision.chosenProbability }
: {}),
...(observedDecision.usage ? { usage: observedDecision.usage } : {}),
...(observedDecision.quota ? { quota: observedDecision.quota } : {}),
...(decision.pinned ? { pinned: true } : {}),
...(decision.pinReason ? { pinReason: decision.pinReason } : {}),
}) : undefined;
let selectionUnavailable = false;
if ((!pinReuse?.decision || pick.cooldownReprobeTargets || awaitedPinEffort) && !options.abortSignal?.aborted) {
// Record the paid decision before anything below can refuse or throw.
recordDecision(failedPinEffortDecision ?? decision);
// The decided choices were admitted against the request-start snapshot. Recheck only what
// can change their spend: availability (cooldowns, reprobe reservations), live consent and
// the key's current scope. Capability edits made meanwhile apply to the next request.
let currentChoices: typeof choices;
try {
const available = new Set(eligibleJevComboChoices(requestStartComboConfig(config, comboId, admissionSnapshot.rawCombo),
comboId, spendAllowed(currentAdmissionScope()), Date.now(), pick.cooldownReprobeTargets)
.map(choice => choice.candidate.key));
currentChoices = choices.filter(choice => available.has(choice.candidate.key));
} catch {
return options.abortSignal?.aborted ? clientCancelledResponse() : comboUnavailable(comboId);
}
const current = currentChoices.find(choice => choice.candidate.key === decision.targetKey
&& (decision.effort === null ? choice.candidate.reasoningEfforts.length === 0
: choice.candidate.reasoningEfforts.includes(decision.effort)));
const available = current ?? currentChoices[0];
if (available) selected = available;
else selectionUnavailable = true;
if (!current) {
// Keep completed decision usage even when no target remains. Old scores and quota
// selection describe neither a fail-open replacement nor a rejected selection.
decision = {
backend: decision.backend,
...(available ? fallbackFor(available) : { targetKey: decision.targetKey, effort: decision.effort }),
gate: decision.gate === "apply" ? "invalid" : decision.gate,
latencyMs: decision.latencyMs,
...(decision.usage ? { usage: decision.usage } : {}),
};
}
}
if (pinReuse?.released) decision = { ...decision, pinReason: pinReuse.released };
jevDecision = decision;
pick = { ...selected.pick, attempted: [targetKey(selected.pick.target)] };
// Keep effort-call telemetry and take pin attribution from the final selection.
const observedDecision = failedPinEffortDecision ?? decision;
recordDecision(observedDecision);
console.debug("[combo] JEV decision", {
backend: observedDecision.backend,
target: comboTargetLogLabel(config, comboId, pick.target),
effort: decision.effort,
gate: observedDecision.gate,
latencyMs: observedDecision.latencyMs,
...(decision.pinReason ? { pinReason: decision.pinReason } : {}),
...(observedDecision.confidence !== undefined ? { confidence: observedDecision.confidence } : {}),
...(observedDecision.chosenProbability !== undefined
? { chosenProbability: observedDecision.chosenProbability }
: {}),
...(observedDecision.usage ? { usage: observedDecision.usage } : {}),
});
// A completed decision belongs to the parent log even if no model can be dispatched.
if (selectionUnavailable) {
return comboUnavailable(comboId, undefined, comboExclusion(config, comboId, target =>
targetEligible(target) && target.provider !== JEV_PROVIDER_ID && jevChoiceEfforts(config, target, false) !== undefined));
}
}
// One immutable combo selection trace, before any child dispatch; child
// adoption below must never replace it with a concrete child route trace.
const decision = comboRouteDecisionTrace(config, comboId, pick, responseModel);
const selectedReason = options.memoryModelPhase
? memoryModelRouteReason(options.memoryModelPhase)
: toolLoopPin ? COMBO_TOOL_LOOP_PIN_REASON : jevDecision?.pinned ? JEV_SESSION_PIN_ROUTE_REASON : undefined;
logCtx.routeDecision = selectedReason
? { ...decision, selected: { ...decision.selected, reason: selectedReason } }
: decision;
const originalReasoning = body && typeof body === "object" && !Array.isArray(body)
? (body as { reasoning?: unknown }).reasoning
: undefined;
const originalRequestedEffortValue = originalReasoning && typeof originalReasoning === "object" && !Array.isArray(originalReasoning)
? (originalReasoning as { effort?: unknown }).effort
: undefined;
const originalRequestedEffort = typeof originalRequestedEffortValue === "string"
&& isDeclaredReasoningEffort(originalRequestedEffortValue)
? originalRequestedEffortValue
: undefined;
const restoreOriginalRequestedEffort = (childLog: RequestLogContext, forcedEffort?: string | null): void => {
if (originalRequestedEffort === undefined) return;
childLog.requestedEffort = comboRequestedEffortLabel(originalRequestedEffort, childLog.requestedEffort, forcedEffort);
recordAttemptRequestedEffort(childLog);
};
let lastFailure: Response | null = null;
// Dispatched targets, not attempted picks: it indexes the declared target list so the clamp
// below can tell how many targets are still entitled to a send.
let comboTargetsDispatched = 0;
// The child log behind `lastFailure`. The natural end of the ladder adopts it inside the
// no-more-targets branch; a budget refusal ends the ladder one iteration later, where that
// iteration's own `childLog` is already out of scope.
let lastFailedChildLog: RequestLogContext | undefined;
// The target behind `lastFailure`, so the next dispatch can tell a hop from a same-target retry.
let lastFailedTarget: { provider: string; model: string } | undefined;
let lastFailedRetryAfter: string | undefined;
// The exhausted-combo mapping below runs outside the loop, where `failure.upstreamCode`
// is gone, so carry the loop's own classification decision instead of re-deriving a
// weaker one from the status alone (#4149).
let lastFailureClassifiesOverflow = false;
let zeroOutputLimitFailure: { childLog: RequestLogContext; usage?: OcxUsage } | undefined;
let lastFailureUpstreamCode: string | undefined;
const wantsStream = (rawBody as { stream?: unknown } | null)?.stream === true || (body as { stream?: unknown } | null)?.stream === true;
// Local input admission refusals (#1524), while every failed target so far was one: such a
// target sent nothing, so an exhausted ladder must not be reported as a provider rejection.
let localAdmissionRefusals: string[] | undefined = [];
let toolChoiceRefusalsOnly: boolean | undefined;
// The first quota/rate-limit refusal of the ladder. A fallback that then refuses its own
// credential or plan (401/403, or a 400 the ladder hopped past) says nothing about why the
// request failed: the primary target ran out. Returning that fallback refusal told clients
// "OpenAI account pool has no usable account credential" while every Claude account was spent.
let quotaFailure: Response | undefined;
let quotaFailedChildLog: RequestLogContext | undefined;
let contextFailure: { response: Response; childLog: RequestLogContext } | undefined;
let xaiPrivacyFailure: { response: Response; childLog: RequestLogContext } | undefined;
// Snapshotted before dispatch: a 401/403 inside this ladder cools its own provider, and that
// fresh cooldown is not a reason the request found no target.
const quotaCooldownSnapshot = snapshotComboQuotaCooldowns(config, comboId);
const exhaustedFailure = (targetsExhausted = false): Response => {
const finalize = (response: Response, childLog = lastFailedChildLog): Response => {
if (childLog) adoptFailedChildLog(childLog);
return response;
};
if (contextFailure) {
return finalize(contextFailure.response, contextFailure.childLog);
}
if (lastFailure && lastFailureUpstreamCode === "zero_output_token_limit" && zeroOutputLimitFailure) {
adoptFailedChildLog(zeroOutputLimitFailure.childLog);
// The terminal builder normalizes wire usage even when the child supplied none.
logCtx.clientResponseUsage = "synthetic";
return wantsStream
? streamingIncompleteResponse(responseModel, zeroOutputLimitFailure.usage, "max_output_tokens", options.translatorBudget)
: jsonIncompleteResponse(responseModel, zeroOutputLimitFailure.usage, "max_output_tokens");
}
if (targetsExhausted && toolChoiceRefusalsOnly === true) return finalize(comboUnavailableResponse("No available targets for combo; attempted targets cannot preserve mandatory tool_choice", { diagnostics: unsupportedToolChoice(comboTargetsDispatched) }));
if (lastFailure?.status === 429 || lastFailure?.status === 402) return finalize(lastFailure);
const privacyOrLastFailure = () => xaiPrivacyFailure
? finalize(xaiPrivacyFailure.response, xaiPrivacyFailure.childLog)
: finalize(lastFailure!);
if (!lastFailure || ![400, 401, 403].includes(lastFailure.status)) return privacyOrLastFailure();
if (quotaFailure) return finalize(quotaFailure, quotaFailedChildLog);
// The quota-refused target was cooled before this request picked, so the ladder never saw
// its refusal. The cooldown, with its Retry-After, is still the honest answer.
let quotaCooldownUntil: number | undefined;
let quotaCooledTargets = 0;
const now = Date.now();
for (const { target, cooldownUntil } of quotaCooldownSnapshot) {
if (cooldownUntil <= now) continue;
try {
if (!targetEligible(target)) continue;
} catch {
// An eligibility check can exhaust the translator budget; it is not quota evidence.
continue;
}
quotaCooldownUntil = Math.min(quotaCooldownUntil ?? cooldownUntil, cooldownUntil);
quotaCooledTargets += 1;
}
const remainingQuotaCooldownMs = quotaCooldownUntil === undefined ? 0 : quotaCooldownUntil - Date.now();
return remainingQuotaCooldownMs > 0
? finalize(comboUnavailableResponse("No available targets for combo", {
retryAfter: String(Math.max(1, Math.ceil(remainingQuotaCooldownMs / 1000))),
// Only quota-cooled eligible targets can produce this answer, so its class is quota.
diagnostics: comboUnavailableDiagnostics(combo.targets.length, comboTargetsDispatched,
Array.from({ length: quotaCooledTargets }, () => "quota" as const)),
})) : privacyOrLastFailure();
};
// The caller's output ceiling, captured once so a floor applied to one target never
// leaks into the next. An established parent estimate wins; otherwise (combo dispatch
// precedes request preparation) the caller's own positive cap is reserved.
const callerBudget = isPlainObject(body) ? body.max_output_tokens : undefined;
const callerOutputCeilingTokens = logCtx.spendOutputCeilingTokens
?? (typeof callerBudget === "number" && Number.isFinite(callerBudget) && callerBudget > 0
? Math.trunc(callerBudget) : undefined);
while (pick) {
if (options.abortSignal?.aborted) return clientCancelledResponse();
const firstComboTarget = comboTargetsDispatched === 0;
// The physical destination after provider aliases and blockedModelRedirects: hops are
// classified by where the request really goes, not by the selector the combo names.
const targetRoute = routeConcreteModel(config, `${pick.target.provider}/${pick.target.model}`);
// Every child send rechecks live metered consent and the key's current scope; a member that
// fails either is skipped and an eligible sibling may still run.
const dispatchScope = currentAdmissionScope();
const scopeAllowed = routeAllowedByScope(dispatchScope, targetRoute);
if (!scopeAllowed || !maySpendOnTarget(pick.target)) {
const skipped: ComboPick = pick;
pick = await pickWithWait({
exclude: skipped.attempted,
eligible: targetEligible,
allowCooldownReprobe: false,
cooldownReprobeTargets: Object.entries(skipped.cooldownReprobeTargets ?? {}),
});
if (options.abortSignal?.aborted) return clientCancelledResponse();
if (!pick) {
// A scope refusal keeps the child's own 403; a consent refusal ends like any exhausted ladder.
if (!scopeAllowed) {
return admissionModelDeniedResponse(projectAdmissionModelDeniedLog(
new AdmissionModelDeniedError(clientModelLabel, targetRoute), logCtx));
}
return lastFailure ? exhaustedFailure() : comboUnavailable(comboId);
}
jevDecision = undefined;
toolLoopTurnEffort = undefined;
continue;
}
// Selection-free hard-lock preflight grants no hop. Enforce this actual first destination
// against the locked source, after aliases and redirects resolve.
if (firstComboTarget && options.mainHardLockFallbackOverride) {
const hop = guardFallbackHop(config, {
site: "combo",
route: `combo/${comboId}`,
aliases: [requestedModel],
from: { provider: OPENAI_CODEX_PROVIDER_ID, model: options.mainHardLockFallbackOverride.sourceModel },
to: { provider: targetRoute.providerName, model: targetRoute.modelId },
trigger: "hard_lock",
admission: options.admission,
});
if (!hop.ok) return hop.response;
const declaredCommit = pendingHopCommit;
pendingHopCommit = declaredCommit ? () => { declaredCommit(); hop.commit(); } : hop.commit;
}
// OCX-11: every later dispatch after a failure is a hop when the target changed. One check
// here covers the ordinary failover pick and the recovery picks alike.
if (!firstComboTarget && lastFailure && lastFailedTarget) {
const hop = guardFallbackHop(config, {
site: "combo",
route: `combo/${comboId}`,
aliases: [requestedModel],
from: lastFailedTarget,
to: { provider: targetRoute.providerName, model: targetRoute.modelId },
trigger: fallbackTriggerForStatus(lastFailure.status),
admission: options.admission,
failureStatus: lastFailure.status,
retryAfter: lastFailedRetryAfter ?? null,
});
if (!hop.ok) {
if (lastFailedChildLog) adoptFailedChildLog(lastFailedChildLog);
return hop.response;
}
pendingHopCommit = hop.commit;
}
// The inherited spend tracker observes this parent log, before the child has its own label.
logCtx.spendPoolId = targetRoute.providerName;
// Combo prepays before its child normalizes the route; the parent tracker must
// already see this target's effective cap rather than a previous target's cap.
const spendProvider = resolveWireProtocolOverride(targetRoute.providerName, targetRoute.modelId,
targetRoute.provider, options.inboundWire ?? "responses", targetRoute.staticPolicy);
const outputBudget = effectiveAzureOutputBudget(spendProvider, callerBudget);
if (outputBudget !== callerBudget && typeof outputBudget === "number" && outputBudget > 0) {
logCtx.spendOutputCeilingTokens = Math.trunc(outputBudget);
} else if (callerOutputCeilingTokens === undefined) {
delete logCtx.spendOutputCeilingTokens;
} else {
logCtx.spendOutputCeilingTokens = callerOutputCeilingTokens;
}
// Derive the target's allowance before booking its initial send; the booking occupies it.
const targetSendBudget = comboSendScope
? comboTargetSendBudget(comboSendScope, combo.targets.length - 1 - comboTargetsDispatched)
: options.sendBudget;
// Every target prepays one send. Only its child may consume that booking; later targets
// remain bounded by the shared total, transition ledger and per-target holdback.
// `countedExternally` is required: the child charges its own physical sends against this
// booking through the exact permit, and charging here as well would halve the cap.
const hopDecision = comboSendScope?.reserveDispatch({
sendClass: firstComboTarget ? "initial" : "combo-failover",
targetKey: `${pick.target.provider}/${pick.target.model}`,
countedExternally: true,
});
if (hopDecision && !hopDecision.allowed && firstComboTarget) {
// A refused initial reservation authorizes no child send and has no upstream failure to return.
return formatErrorResponse(429, SEND_BUDGET_EXHAUSTED_CODE, "request send budget exhausted before combo dispatch");
}
else if (hopDecision && !hopDecision.allowed) {
// Out of budget is not this target's failure. The established exhaustion contract is to
// return the last real upstream answer with its status, headers and any quota body
// intact rather than to mint a synthetic error, and a later target only exists because
// an earlier one already recorded one.
return exhaustedFailure();
}
// Admitted: only now is a guarded hop to this target recorded as taken.
pendingHopCommit?.();
pendingHopCommit = undefined;
const initialSend = hopDecision?.allowed ? { permit: hopDecision.permit, producerOwned: false } : undefined;
try {
comboTargetsDispatched += 1;
const targetOutputCeiling = resolveOutputCeiling(
targetRoute.provider,
targetRoute.providerName,
targetRoute.modelId,
);
const childLog: RequestLogContext = {
model: pick.target.model,
provider: pick.target.provider,
comboTarget: pick.target,
comboWriterGeneration: pick.writerGeneration,
comboTargetOutputCeiling: targetOutputCeiling,
...(logCtx.conversationId ? { conversationId: logCtx.conversationId, conversationIdIsHermesFallback: logCtx.conversationIdIsHermesFallback } : {}),
...(logCtx.affinityLane ? { affinityLane: logCtx.affinityLane } : {}),
...(logCtx.surface ? { surface: logCtx.surface } : {}),
};
// A link turn's child reads its upstream only as the client drains, as the parent would (#8601).
bindLinkTurnChild(logCtx, childLog);
const targetReasoningEfforts = supportedLadderFor({
provider: targetRoute.provider,
modelId: targetRoute.modelId,
});
const initialJevDecision = firstComboTarget ? jevDecision : undefined;
// The effort a decision owns on this dispatch: its own first request, or the turn a
// tool-loop continuation resumes. Failover targets keep ordinary Combo policy either way.
const turnEffort: ComboTurnEffort | undefined = initialJevDecision
?? (firstComboTarget ? toolLoopTurnEffort : undefined);
// `client` keeps the decision's target but not its tier: the caller and the target ladder
// own the wire effort, so a provider whose effort swaps the upstream model id is never
// re-tiered mid-session and its prompt cache survives the turn.
const jevEffortApplies = turnEffort !== undefined && combo.jevEffortMode !== "client";
const childInput = options.droidDefaultEffort && isPlainObject(body) ? { ...body } : body;
applyDroidResponsesReasoningDefault(childInput, options.droidDefaultEffort, {
provider: targetRoute.provider,
modelId: targetRoute.modelId,
});
const childBody = concreteComboRequestBody(
childInput,
pick.target,
jevEffortApplies ? turnEffort.effort : combo.defaultEffort,
jevEffortApplies && turnEffort.effort === null ? [] : targetReasoningEfforts,
combo.reasoningEffortMode,
jevEffortApplies
? (turnEffort.effort === null ? "fallback" : "force")
: combo.defaultEffortMode,
);
if (comboAdvertisesEffortUnion(combo.capabilityPolicy, combo.reasoningEffortMode)) {
clampComboCallerEffort(childBody, targetReasoningEfforts, pick.target);
}
if (turnEffort) {
if (jevEffortApplies) delete childBody.service_tier;
if (jevEffortApplies && turnEffort.effort !== null) {
const childReasoning = childBody.reasoning;
const preservedReasoning = childReasoning && typeof childReasoning === "object" && !Array.isArray(childReasoning)
? childReasoning as Record<string, unknown>
: {};
childBody.reasoning = { ...preservedReasoning, effort: turnEffort.effort };
delete childBody.reasoning_effort;
delete childBody.thinking_budget;
delete childBody.thinking;
}
}
const childHeaders = buildComboChildHeaders(req.headers);
const childRequest = new Request(req.url, {
method: req.method,
headers: childHeaders,
body: JSON.stringify(childBody),
});
linkRequestSessionLane(req, childRequest);
let resolvedAuth: CodexAuthContext | undefined;
let terminalRecorder: ((status: ResponsesTerminalStatus, httpStatusOverride?: number) => void) | undefined;
const started = Date.now();
const attempt = beginRequestAttempt(
(logCtx.attempts?.length ?? 0) + 1,
pick.target.provider,
// The id the child wire will actually send, not the selector the combo named. A target may
// be an alias, and `routeConcreteModel` above is where it becomes the provider's native id;
// recording the alias here would describe a request that never left (the adapter resolves
// the id before it reads any per-model list).
targetRoute.modelId,
config.providers[pick.target.provider]!.adapter,
);
childLog.activeAttempt = attempt;
if (originalRequestedEffort !== undefined) {
childLog.requestedEffort = originalRequestedEffort;
recordAttemptRequestedEffort(childLog);
}
childLog.activeAttemptStartedAt = started;
childLog.attempts = logCtx.attempts ??= [];
childLog.attempts.push(attempt);
// A key or account rotation inside this target seals the previous segment as its own attempt
// and moves `childLog.activeAttemptStartedAt` forward (noteProviderAttemptSend). Timing the
// live segment from the target's start would count every sealed segment a second time.
const segmentStartedAt = (): number => childLog.activeAttemptStartedAt ?? started;
let attemptRetained = false;
const retainCancelledAttempt = (): void => {
if (attemptRetained) return;
sealRequestAttemptIdentity(
attempt,
childLog.provider,
childLog.providerAdapter ?? attempt.adapter,
childLog.accountLogLabel,
);
finishRequestAttempt(attempt, 499, Date.now() - segmentStartedAt(), childLog.usage);
attemptRetained = true;
};
// The row is written from `logCtx`, which copies `childLog` only when the child commits. A
// bridge child binds its usage later, at the terminal frame, so the binding is forwarded here
// after that point. Left on `childLog`, the row would re-read the bridged wire instead of the
// adapter's usage, and that wire has no providerCredits and a context-derived input count.
// A binding that arrives before the commit waits for it, and a child that never commits
// forwards nothing: both flags belong to this target only.
let childCommitted = false;
let childUsageBound = false;
const forwardChildUsage = (): void => {
if (!childCommitted || !childUsageBound) return;
logCtx.usageFromBridge = true;
if (childLog.usage) logCtx.usage = childLog.usage;
if (isPausedTurn(childLog)) rememberPausedTurn(logCtx);
};
const completedTarget = { provider: pick.target.provider, model: pick.target.model };
const writerGeneration = pick.writerGeneration;
const servingPick = pick;
let comboSuccessSettled = false;
const settleServingSuccess = (): void => {
if (comboSuccessSettled) return;
comboSuccessSettled = true;
noteComboSuccess(comboId, combo, servingPick.target, writerGeneration);
settleComboReprobeSuccess(servingPick);
};
let hostedWebSearchStream = false;
let consumedChildFailure: ConsumedComboFailure | undefined;
let preflightModelRefusal: CodexAccountModelRefusal | undefined;
const callbackGate = createChildPassthroughCallbackGate({
...options,
onResponseComplete: model => {
if (isPausedTurn(childLog)) rememberPausedTurn(logCtx);
if (hostedWebSearchStream) settleServingSuccess();
// The live config can change while the child is streaming. Never retain credentials.
const currentCombo = getCombo(config, comboId);
const provider = config.providers[completedTarget.provider];
if (!options.compactionRoutingOverride && !options.mainHardLockFallbackOverride
&& Object.hasOwn(config.providers, completedTarget.provider)
&& provider && provider.disabled !== true
&& currentCombo?.targets.some(target => targetKey(target) === targetKey(completedTarget))) {
rememberComboForLane(
sessionLaneIdFromRequest(req.headers), comboId, completedTarget, model, writerGeneration,
jevEffortApplies ? turnEffort : undefined,
);
// A failed effort decision only refreshes the live pin, which another turn may have updated.
jevPin?.complete(targetKey(completedTarget), failedPinEffortDecision ? undefined : initialJevDecision, writerGeneration);
}
options.onResponseComplete?.(model);
},
onNativePassthroughTerminal: status => {
// A committed stream can acquire terminal metadata after preflight copied
// the child log. Publish it before the outer logger finalizes, but only
// through the gate: discarded attempts must never affect the parent.
// Undefined child fields must preserve metadata already inspected by WS.
if (childLog.terminalHttpStatus !== undefined) logCtx.terminalHttpStatus = childLog.terminalHttpStatus;
if (childLog.terminalIncompleteReason !== undefined) logCtx.terminalIncompleteReason = childLog.terminalIncompleteReason;
if (childLog.committedIncompleteReason !== undefined) logCtx.committedIncompleteReason = childLog.committedIncompleteReason;
if (childLog.terminalErrorCode !== undefined) logCtx.terminalErrorCode = childLog.terminalErrorCode;
if (childLog.observedTerminalStatus !== undefined) logCtx.observedTerminalStatus = childLog.observedTerminalStatus;
if (childLog.upstreamError !== undefined) logCtx.upstreamError = childLog.upstreamError;
// Raw usage may arrive after the commit copy. Publish it before spend is finalized.
if (childLog.usage !== undefined) {
logCtx.usage = childLog.usage;
logCtx.usageWireParsed = childLog.usageWireParsed;
}
if (isPausedTurn(childLog)) rememberPausedTurn(logCtx);
// A committed stream that ends failed is a target failure too; incomplete is an answer.
if (status === "failed") jevPin?.forget();
else settleServingSuccess();
options.onNativePassthroughTerminal?.(status);
},
});
let response: Response;
try {
const currentTargetProvider = pick.target.provider;
const remainingTargets = combo.strategy === "jev"
? combo.targets.filter(target => !pick!.attempted.includes(targetKey(target)))
: combo.targets.slice(pick.targetIndex + 1);
const deferCodexResetDerivedCooldown = (combo.strategy === "failover" || combo.strategy === "jev")
&& remainingTargets.some(target =>
target.provider === currentTargetProvider
&& targetEligible(target)
&& !isComboTargetInCooldown(comboId, target),
);
const nativeChild = protocolLanes?.nativeChild(pick.target, targetRoute, targetSendBudget, turnEffort, jevEffortApplies);
response = nativeChild ? await dispatchNativeComboChild({
source: options.protocolSource!,
plan: nativeChild,
comboDispatchPermit: hopDecision?.allowed ? hopDecision.permit : undefined,
logCtx,
childLog,
attempt,
startedAt: started,
...(options.turnAdmissionLease ? { turnAdmissionLease: options.turnAdmissionLease } : {}),
// Attempt-relative TTFT, recorded here for the same reason as the bridge child below.
onFirstOutput: () => {
if (!sealedCredentialRefusals.has(attempt) && attempt.firstOutputMs === undefined) {
attempt.firstOutputMs = Math.max(0, Date.now() - segmentStartedAt());
}
options.onFirstOutput?.();
},
callbacks: {
onTerminal: callbackGate.onTerminal,
onCancel: callbackGate.onCancel,
onResponseComplete: callbackGate.onResponseComplete,
},
}) : await requestDispatchers.handleResponses(childRequest, config, childLog, {
...options,
admissionScope: dispatchScope,
plaintextV2Decision: strictReplay,
replayPrincipal,
// A bridge child is a concrete route; the native source belongs to this loop only.
...(options.protocolSource ? { protocolSource: undefined } : {}),
// After the spread: the child must run on THIS target's ladder, not on the holder the
// parent arrived with.
sendBudget: targetSendBudget,
comboAttempt: true,
comboVisionSidecar,
...(omittingImages ? { comboOmitImages: true }
: capability.requiresVisionPlan(pick.target) ? { comboRequiresVisionPlan: true } : {}),
...(capability.unservable === "context" ? { comboContextDegraded: true } : {}),
comboInitialSend: initialSend,
comboDispatchPermit: hopDecision?.allowed ? hopDecision.permit : undefined,
comboReplaySnapshot,
deferCodexResetDerivedCooldown,
onBridgeUsageBound: () => {
childUsageBound = true;
forwardChildUsage();
},
onHostedWebSearchStream: () => { hostedWebSearchStream = true; },
onWebSearchLocalFailure: () => {
if (childCommitted) carryLocalFailureState(childLog, logCtx);
},
// Attempt-relative TTFT is recorded HERE (not via childLog.firstOutputMs — a later
// Object.assign(logCtx, childLog) would overwrite the request-relative value).
onFirstOutput: () => {
if (!sealedCredentialRefusals.has(attempt) && attempt.firstOutputMs === undefined) {
attempt.firstOutputMs = Math.max(0, Date.now() - segmentStartedAt());
}
options.onFirstOutput?.();
},
onCodexAuthContextResolved: value => { resolvedAuth = value; },
setTerminalOutcomeRecorder: value => { terminalRecorder = value; },
onConsumedComboFailure: value => { consumedChildFailure = value; },
onStoredPool401ReplayDispatched: () => { storedPool401ReplayDispatched = true; },
onNativePassthroughTerminal: callbackGate.onTerminal,
onNativePassthroughCancel: callbackGate.onCancel,
onResponseComplete: callbackGate.onResponseComplete,
});
// Both lanes applied the initial choice before provider pins/caps; retain those transitions.
restoreOriginalRequestedEffort(childLog, jevEffortApplies ? turnEffort?.effort : undefined);
} catch (error) {
callbackGate.discard();
if (options.abortSignal?.aborted) {
retainCancelledAttempt();
return clientCancelledResponse();
}
jevPin?.forget();
finishRequestAttempt(attempt, 502, Date.now() - segmentStartedAt(), childLog.usage);
throw error;
}
if (options.abortSignal?.aborted) {
callbackGate.discard();
retainCancelledAttempt();
return clientCancelledResponse();
}
// A native Chat child reports a pre-stream failure by status before any byte, so its body
// is never peeked; a non-OK one takes the ordinary failure path below.
if (response.ok && !runTurnAdapterSseResponses.has(response) && clientWireOf(response) === undefined) {
const nativePassthrough = isNativePassthroughSseResponse(response);
const eagerRelay = isEagerRelaySseResponse(response);
let preflight;
try {
preflight = await preflightComboStreamResponse(response, childLog, undefined, {
signal: options.abortSignal,
requiredToolPrelude: childLog.providerAdapter === "openai-responses" && requiredToolContractOf(rawBody) !== undefined,
degeneratePrelude: true,
});
} catch (error) {
callbackGate.discard();
if (options.abortSignal?.aborted) {
retainCancelledAttempt();
return clientCancelledResponse();
}
jevPin?.forget();
finishRequestAttempt(attempt, 502, Date.now() - segmentStartedAt(), childLog.usage);
throw error;
}
if (preflight.kind === "failed") {
callbackGate.discard();
terminalRecorder?.("failed", preflight.response.status);
response = preflight.response;
preflightModelRefusal = preflight.codexModelRefusal;
} else {
response = preflight.response;
if (nativePassthrough) markNativePassthroughSseResponse(response);
if (eagerRelay) markEagerRelaySseResponse(response);
}
}
if (options.abortSignal?.aborted) {
callbackGate.discard();
await response.body?.cancel().catch(() => undefined);
retainCancelledAttempt();
return clientCancelledResponse();
}
if (response.ok) {
sealRequestAttemptIdentity(
attempt,
childLog.provider,
childLog.providerAdapter ?? attempt.adapter,
childLog.accountLogLabel,
);
attemptRetained = true;
// Native SSE can carry a failed verdict after HTTP acceptance, including after preflight.
// A hosted web-search stream settles only when the loop reports a completed response.
if (!isNativePassthroughSseResponse(response) && !hostedWebSearchStream) settleServingSuccess();
carryProxyErrorContext(childLog, logCtx);
Object.assign(logCtx, childLog, {
client: logCtx.client,
requestedModel: responseModel,
model: responseModel,
provider: "combo",
comboId,
comboTarget: pick.target,
comboWriterGeneration: pick.writerGeneration,
comboTargetOutputCeiling: targetOutputCeiling,
routeDecision: logCtx.routeDecision,
attempts: logCtx.attempts,
activeAttempt: attempt,
activeAttemptStartedAt: segmentStartedAt(),
resolvedModel: childLog.resolvedModel ?? childLog.model,
});
carryLocalFailureState(childLog, logCtx);
options.onCodexAuthContextResolved?.(resolvedAuth);
options.setTerminalOutcomeRecorder?.((status, httpStatusOverride) => {
if (isPausedTurn(childLog)) rememberPausedTurn(logCtx);
if (status !== "failed" && !hostedWebSearchStream) settleServingSuccess();
terminalRecorder?.(status, httpStatusOverride);
});
callbackGate.commit();
childCommitted = true;
forwardChildUsage();
return response;
}
callbackGate.discard();
if (response.status === 499) {
retainCancelledAttempt();
return clientCancelledResponse();
}
let failure: ConsumedComboFailure;
try {
failure = consumedChildFailure
?? await consumeComboFailure(response, options.abortSignal, Date.now(), childLog);
if (hasProxyErrorMessage(childLog, failure.upstreamMessage ?? "", { type: failure.upstreamType, code: failure.upstreamCode })) markProxyError(failure.response);
if (preflightModelRefusal !== undefined) failure = { ...failure, codexModelRefusal: preflightModelRefusal };
} catch (error) {
if (options.abortSignal?.aborted) {
retainCancelledAttempt();
return clientCancelledResponse();
}
jevPin?.forget();
finishRequestAttempt(attempt, 502, Date.now() - segmentStartedAt(), childLog.usage);
throw error;
}
if (options.abortSignal?.aborted) {
retainCancelledAttempt();
return clientCancelledResponse();
}
// A member's local late-attribution refusal reaches the client only as the literal constant
// envelope: swap the response, keep every classification input, and skip the overflow rewrite.
const lateAttributionRefusal = isLateAttributionRefusal(failure);
if (lateAttributionRefusal) failure = { ...failure, response: lateAttributionLimitResponse() };
sealRequestAttemptIdentity(
attempt,
childLog.provider,
childLog.providerAdapter ?? attempt.adapter,
childLog.accountLogLabel,
);
finishRequestAttempt(
attempt,
failure.response.status,
Date.now() - segmentStartedAt(),
failure.usage ?? childLog.usage,
);
const visionDescriptionRefused = isComboVisionDescriptionRefusal(failure.response);
if (visionDescriptionRefused) visionRejectedTargets.add(targetKey(pick.target));
const replayRefusal = isReplayRefusalResponse(failure.response);
if (replayRefusal) {
// Numeric 429 is a client replay policy here, not an upstream quota observation.
childLog.causeHint = "transport-ambiguous";
childLog.terminalSource = "synthetic";
childLog.errorCode = UPSTREAM_RESET_REPLAY_REFUSED_CODE;
if (!sealedCredentialRefusals.has(attempt)) attempt.errorCode = childLog.errorCode;
}
if (failure.upstreamCode === "input_admission_refused" && attempt.sendCount === 0) {
attempt.errorCode = failure.upstreamCode;
localAdmissionRefusals?.push(failure.upstreamMessage ?? "");
} else {
localAdmissionRefusals = undefined;
}
attemptRetained = true;
lastFailure = failure.response;
lastFailureUpstreamCode = failure.upstreamCode;
toolChoiceRefusalsOnly = (toolChoiceRefusalsOnly ?? true) && isMandatoryToolChoiceRefusal(failure.response);
const localDeadline = failure.response.status === 504 && upstreamErrorIsLocal(childLog);
// A real target failure ends the session pin (#7525).
if (!localDeadline) jevPin?.forget();
if (!quotaFailure && !replayRefusal && (lastFailure.status === 429 || lastFailure.status === 402)) {
quotaFailure = lastFailure;
quotaFailedChildLog = childLog;
}
lastFailedChildLog = childLog;
// The failed child's resolved destination, so the next hop compares physical targets.
lastFailedTarget = { provider: targetRoute.providerName, model: targetRoute.modelId };
lastFailedRetryAfter = failure.retryAfter;
// A replacement that answers 200 is unmarked, and its zero-output failure only exists once
// preflight has rebuilt the stream as a fresh Response. A spent grant never hops: a status the
// client would resend becomes the refusal, and anything else reaches the client as it is.
const spentReplacement = !failure.nonReplayable && comboSendScope?.ambiguousResendSpent === true;
if (spentReplacement) {
const settled = settleOperatorReplacement(failure.response);
if (settled !== failure.response) {
adoptFailedChildLog(childLog);
return settled;
}
}
// A non-replayable failure can come from a committed provider terminal or a send whose
// outcome is ambiguous. Neither permits another target, regardless of the HTTP status.
const failureDecision = failure.nonReplayable || spentReplacement
? "stop"
: localDeadline || isPolicyCandidateRefusal(failure.response) ? "hop"
: comboFailureDecision(failure.response.status, failure.classificationText, {
code: failure.upstreamCode,
rootCode: failure.upstreamRootCode,
codexModelRefusal: failure.codexModelRefusal,
verifiedPlanRefusal: failure.verifiedPlanRefusal,
malformedResponseFormat: failure.malformedResponseFormat,
openRouterOpaque400: failure.openRouterOpaque400,
unofferedToolCallRefusal: failure.unofferedToolCallRefusal,
providerModerationRefusal: failure.providerModerationRefusal,
providerIntakeRefusal: failure.providerIntakeRefusal,
// The adapter the failed leg actually resolved: a configured `kiro` provider can route a
// model through another wire via `modelAdapters`, and an unresolved leg grants no hop.
failedAdapter: childLog.providerAdapter,
});
const wantsStream = (rawBody as { stream?: unknown } | null)?.stream === true;
// Local byte admission has its own diagnostic; do not relabel it as an upstream refusal.
const classifyOverflow = failure.response.status === 413 && !lateAttributionRefusal
&& (wantsStream || (failure.upstreamCode !== "outbound_body_too_large"
&& failure.upstreamCode !== "translation_buffer_limit"));
lastFailureClassifiesOverflow = classifyOverflow;
if (storedPool401ReplayDispatched) {
if (failureDecision === "hop" && unreadableEncryptedAgentTask && !comboPayloadReadable) {
const recoveredTarget = await pickWithWait({
exclude: pick.attempted,
eligible: target => {
if (!recoveryEligible(target)) return false;
try {
const route = routeConcreteModel(config, `${target.provider}/${target.model}`);
return route.codexAccountMode === undefined
&& !isCanonicalOpenAiForwardProvider(route.provider);
} catch {
return false;
}
},
});
if (options.abortSignal?.aborted) return clientCancelledResponse();
if (recoveredTarget && await recoverUnreadableEncryptedTask()) {
pick = recoveredTarget;
continue;
}
if (options.abortSignal?.aborted) return clientCancelledResponse();
}
// Keep the spent Pool budget sticky even after a recovered routed child:
// no later failure may reopen ordinary combo/native account hopping.
adoptFailedChildLog(childLog);
if (classifyOverflow && failureDecision === "stop") {
return wantsStream
? streamingContextOverflowResponse(responseModel, options.translatorBudget)
: jsonContextOverflowResponse();
}
return lastFailure;
}
if (failureDecision === "stop") {
adoptFailedChildLog(childLog);
if (classifyOverflow) {
return wantsStream
? streamingContextOverflowResponse(responseModel, options.translatorBudget)
: jsonContextOverflowResponse();
}
return lastFailure;
}
const xaiPrivacyRefusal = isXaiPrivacyModeRefusal(failure.response);
if (xaiPrivacyRefusal) xaiPrivacyFailure = { response: failure.response, childLog };
// Retain a confirmed target context refusal when later retryable failures exhaust the ladder.
// Hard stops above still return their own verdict, and every attempt keeps its own usage.
if (!contextFailure && failure.response.status === 400 && isDefiniteContextOverflow(400, failure.classificationText)) {
contextFailure = { childLog, response: formatErrorResponse(400, "invalid_request_error",
failure.upstreamMessage ?? failure.classificationText, { code: "context_length_exceeded", classified: true }) };
}
if (failure.upstreamCode === "zero_output_token_limit") {
zeroOutputLimitFailure = {
childLog,
usage: failure.usage ?? childLog.usage,
};
}
// A bare status made a revoked credential read as a provider outage. Log the classified
// condition (a closed member), never upstream-authored code or message text.
const failureReason = localDeadline ? undefined : classifyUpstreamCondition({
status: failure.response.status, code: failure.upstreamCode, type: failure.upstreamType, message: failure.upstreamMessage,
});
console.warn(
`[combo] ${comboLogLabel(config, comboId)}: ${comboTargetLogLabel(config, comboId, pick.target)} failed with ${failure.response.status}`
+ ` after ${Date.now() - started}ms${failureReason ? `: ${failureReason}` : ""}`,
);
const failureNow = Date.now();
const attemptedTargets = pick.attempted;
// Legacy privacy mode is specific to the serving account.
const failureCooldownScope = localDeadline || xaiPrivacyRefusal || isPolicyCandidateRefusal(failure.response) ? "none" : comboFailureCooldownScope(failure.response.status, failure.classificationText, {
code: failure.upstreamCode,
malformedResponseFormat: failure.malformedResponseFormat,
openRouterOpaque400: failure.openRouterOpaque400,
unofferedToolCallRefusal: failure.unofferedToolCallRefusal,
providerModerationRefusal: failure.providerModerationRefusal,
});
const failedTargetKey = targetKey(pick.target);
let failedTargetCooldownRecorded = false;
// The dispatch rewrote this to name the pool account that actually served the turn.
// The pool logs its main account under the bare provider name and carries "main" only as the
// account label, which is stamped for pool and main-pool contexts alone (#8880).
const poolAccountLabel = poolAccountProviderLabel(childLog.provider, pick.target.provider)
?? (childLog.accountLogLabel === "main" ? `${pick.target.provider}-main` : undefined);
const failedAccount = failure.response.status === 402
? creditRefusedAnthropicAccountLabel(
config, pick.target.provider, pick.target.model, poolAccountLabel, failure.classificationText, failure.upstreamCode,
failure.response,
)
: cooledPoolAccountLabel(config, pick.target.provider, pick.target.model, poolAccountLabel)
?? (failure.response.status === 429 && failureCooldownScope === "target"
? cooledGenericOAuthAccountLabel(config, pick.target.provider, pick.target.model, childLog.accountLogLabel, failure.retryAfter)
: undefined);
// The target still cools on the pool's own refusal (the anti-hammer guard), but for the local
// fallback rather than the pool's restated per-account Retry-After.
const poolLocalRefusal = isAnthropicPoolLocalRefusal(
config, pick.target.provider, failure.response.status, failedAccount, failureNow,
);
const codexLocalRefusal = isCodexAccountCooldownResponse(failure.response);
const nextPick = advanceComboAfterFailure(config, pick, {
retryAfter: poolLocalRefusal || codexLocalRefusal ? undefined : failure.retryAfter,
resetAt: codexLocalRefusal ? undefined : failure.resetAt,
cooldownMs: combo.cooldownMs,
now: failureNow,
recordFailure: !localDeadline, cooldownScope: failureCooldownScope,
eligible: targetEligible,
status: failure.response.status,
code: failure.upstreamCode,
message: failure.classificationText,
failedAccount,
onCooldownRecorded: target => {
failedTargetCooldownRecorded ||= targetKey(target) === failedTargetKey;
},
});
// A sibling cooldown is not this failure's write: stale-generation removal can
// refuse recording even for a cooldown-producing classification. Require both.
const failedTargetCooled = failureCooldownScope !== "none"
&& failedTargetCooldownRecorded
&& isComboTargetInCooldown(comboId, pick.target, failureNow);
// Drop exclusions for the single-target retry, but wait for normal cooldown
// expiry: an in-flight request cannot reserve a fresh recovery pass, though the
// reservation it already owns still applies to entries unchanged since it was made.
const carriedReprobe: ComboPick["cooldownReprobeTargets"] = pick.cooldownReprobeTargets;
const retryAfterCooldown = (): Promise<ComboPick | null> =>
pickWithWait({
allowCooldownReprobe: false,
cooldownReprobeTargets: carriedReprobe ? Object.entries(carriedReprobe) : undefined,
eligible: targetEligible,
now: failureNow,
});
if (nextPick) {
pick = nextPick;
} else {
pick = await pickWithWait({
exclude: pick.attempted,
eligible: targetEligible,
cooldownReprobeTargets: carriedReprobe ? Object.entries(carriedReprobe) : undefined,
now: failureNow,
});
// A single-target combo with waitForCooldownMs has no alternate target to fail over to,
// but can recover if it waits for its brief cooldown. The initial attempt accumulated into
// pick.attempted, so the first pickWithWait above excluded it. retryAfterCooldown below is
// the same selector with `exclude` deliberately dropped, so the single cooled target
// becomes eligible again once its cooldown expires.
// Termination is double-guarded:
// 1) comboSendScope?.reserveDispatch refuses a second failover hop via comboExecutionBudgetPolicy
// (maxAlternateTargetSends: 1 for a single declared target).
// 2) comboTargetsDispatched <= 1 bounds it locally so the retry never loops or waits unnecessarily
// even if sendBudget scope is absent.
if (
!pick
&& combo.targets.length === 1
&& combo.waitForCooldownMs > 0
&& comboTargetsDispatched <= 1
&& failedTargetCooled
&& !options.abortSignal?.aborted
) {
pick = await retryAfterCooldown();
}
}
if (!pick) {
if (options.abortSignal?.aborted) return clientCancelledResponse();
if (onlyReplayIncompatibleTargetsRemain(attemptedTargets)) {
if (contextFailure || xaiPrivacyFailure) return exhaustedFailure();
adoptFailedChildLog(childLog);
return targetIncompatibleResponse();
}
if (unreadableEncryptedAgentTask && !comboPayloadReadable) {
const recoveredTarget = await pickWithWait({
exclude: attemptedTargets,
eligible: recoveryEligible,
cooldownReprobeTargets: carriedReprobe ? Object.entries(carriedReprobe) : undefined,
now: failureNow,
});
if (recoveredTarget && await recoverUnreadableEncryptedTask()) {
pick = recoveredTarget;
continue;
}
}
// Waiting or recovery may have observed cancellation after the check above.
if (options.abortSignal?.aborted) return clientCancelledResponse();
if (visionRejectedTargets.size > 0 && !omittingImages) {
if (combo.onUnservable !== "reject") {
// These children refused before sending the primary turn, so they can still serve it
// with omission. Keep exclusions for every target that did attempt the primary turn.
pick = await pickWithWait({
exclude: attemptedTargets.filter(key => !visionRejectedTargets.has(key)),
eligible: useImageDegradation,
cooldownReprobeTargets: carriedReprobe ? Object.entries(carriedReprobe) : undefined,
});
if (options.abortSignal?.aborted) return clientCancelledResponse();
if (pick) {
omittingImages = true;
warnComboImageOmission();
}
}
if (!pick && visionDescriptionRefused) return unservableImageResponse();
}
}
} finally {
// External receipts make release a no-op after real work. runTurn owns its asynchronous
// producer; core transfers cleanup there before returning a streaming response.
if (!initialSend?.producerOwned) initialSend?.permit.release();
}
}
const failure = exhaustedFailure(true);
if (
failure === lastFailure && lastFailure?.status === 413
&& lastFailureClassifiesOverflow
) {
if (localAdmissionRefusals?.length) logCtx.errorCode = "input_admission_refused";
const localMessage = localAdmissionRefusals?.length
? `opencodex refused this turn locally; nothing was sent upstream. No target of this combo `
+ `that was tried can fit its input: ${localAdmissionRefusals.join(" ")} Compact the conversation before retrying.`
: undefined;
return (rawBody as { stream?: unknown } | null)?.stream === true
? streamingContextOverflowResponse(responseModel, options.translatorBudget, localMessage)
: jsonContextOverflowResponse(localMessage);
}
return failure;
}