UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

772 lines (732 loc) • 35.4 kB
import { parseResetCooldownMs } from "../codex/routing"; import { classifyError, isCyberPolicyCode } from "../lib/errors"; import { isNonReplayableUpstreamCode } from "../lib/upstream-retry"; import type { OcxComboTarget } from "../types"; import { targetKey } from "./types"; import { captureConfigGeneration, sweepExpiredOnWrite, type GenerationContext, } from "../lib/state-store-sweeper"; interface TargetCooldown { cooldownUntil: number; } const DEFAULT_COOLDOWN_MS = 60_000; const MAX_COOLDOWN_MS = 10 * 60_000; const MAX_SERVER_DELAY_MS = 24 * 60 * 60_000; /** Short cooldown for request-rate 429s (for example provider code 1302) that omit Retry-After. */ export const COMBO_REQUEST_RATE_COOLDOWN_MS = 5_000; const QUOTA_LIMIT_CODES = new Set([ "1308", "1310", "1316", "1317", "1318", "1319", "1320", "1321", "insufficient_quota", ]); const TRANSIENT_REQUEST_RATE_CODES = new Set(["1302", "1305"]); const IMF_FIXDATE_RE = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (\d{2}) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/i; const RFC850_DATE_RE = /^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (\d{2})-(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-(\d{2}) (\d{2}):(\d{2}):(\d{2}) GMT$/i; const ASCTIME_DATE_RE = /^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) ( \d|\d{2}) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/i; const HTTP_MONTH_INDEX: Record<string, number> = { jan: 0, feb: 1, mar: 2, apr: 3, may: 4, jun: 5, jul: 6, aug: 7, sep: 8, oct: 9, nov: 10, dec: 11, }; /** Map<`${comboId}\0${provider/model}`, TargetCooldown> */ const targetCooldowns = new Map<string, TargetCooldown>(); let lastReconciledGeneration = 0; let liveComboTargets = new Set<string>(); function cooldownMapKey( comboId: string, target: Pick<OcxComboTarget, "provider" | "model">, ): string { return `${comboId}\0${targetKey(target)}`; } function parseUtcDateParts( year: number, monthName: string, day: number, hour: number, minute: number, second: number, ): number | undefined { const month = HTTP_MONTH_INDEX[monthName.toLowerCase()]; if (month === undefined) return undefined; const timestamp = Date.UTC(year, month, day, hour, minute, second); const parsed = new Date(timestamp); return parsed.getUTCFullYear() === year && parsed.getUTCMonth() === month && parsed.getUTCDate() === day && parsed.getUTCHours() === hour && parsed.getUTCMinutes() === minute && parsed.getUTCSeconds() === second ? timestamp : undefined; } function parseHttpDate(value: string, now: number): number | undefined { const imf = IMF_FIXDATE_RE.exec(value); if (imf) { return parseUtcDateParts( Number(imf[3]), imf[2]!, Number(imf[1]), Number(imf[4]), Number(imf[5]), Number(imf[6]), ); } const rfc850 = RFC850_DATE_RE.exec(value); if (rfc850) { const current = new Date(now); const currentYear = current.getUTCFullYear(); const month = HTTP_MONTH_INDEX[rfc850[2]!.toLowerCase()]; if (month === undefined) return undefined; let year = Math.floor(currentYear / 100) * 100 + Number(rfc850[3]); const yearDelta = year - currentYear; const candidateTimeOfYear = Date.UTC( 2000, month, Number(rfc850[1]), Number(rfc850[4]), Number(rfc850[5]), Number(rfc850[6]), ); const currentTimeOfYear = Date.UTC( 2000, current.getUTCMonth(), current.getUTCDate(), current.getUTCHours(), current.getUTCMinutes(), current.getUTCSeconds(), current.getUTCMilliseconds(), ); if (yearDelta < -50 || (yearDelta === -50 && candidateTimeOfYear < currentTimeOfYear)) { year += 100; } else if (yearDelta > 50 || (yearDelta === 50 && candidateTimeOfYear > currentTimeOfYear)) { year -= 100; } return parseUtcDateParts( year, rfc850[2]!, Number(rfc850[1]), Number(rfc850[4]), Number(rfc850[5]), Number(rfc850[6]), ); } const asctime = ASCTIME_DATE_RE.exec(value); if (!asctime) return undefined; return parseUtcDateParts( Number(asctime[6]), asctime[1]!, Number(asctime[2]), Number(asctime[3]), Number(asctime[4]), Number(asctime[5]), ); } /** Parse a Retry-After delay, optionally retaining an upstream delay up to one day. */ export function parseRetryAfterMs( value: string | null | undefined, now = Date.now(), options?: { preserveImmediate?: boolean; preserveServerDelay?: boolean }, ): number | undefined { const text = value?.trim(); if (!text) return undefined; // Keep legacy bounded parsing for other callers. Combo cooldowns preserve // multi-hour upstream delays, but never quarantine a target beyond one day. const maximum = options?.preserveServerDelay === true ? MAX_SERVER_DELAY_MS : MAX_COOLDOWN_MS; if (/^\d+(?:\.\d+)?$/.test(text)) { const seconds = Number(text); if ( Number.isFinite(seconds) && (seconds > 0 || (options?.preserveImmediate && seconds === 0)) ) { return Math.min(Math.max(Math.ceil(seconds * 1000), 1), maximum); } } const timestamp = parseHttpDate(text, now); if (timestamp === undefined) return undefined; const delay = timestamp - now; if (delay > 0) return Math.min(delay, maximum); return options?.preserveImmediate ? 1 : undefined; } export function isComboTargetInCooldown( comboId: string, target: Pick<OcxComboTarget, "provider" | "model">, now = Date.now(), ): boolean { const key = cooldownMapKey(comboId, target); const entry = targetCooldowns.get(key); if (!entry) return false; if (entry.cooldownUntil <= now) { targetCooldowns.delete(key); return false; } return true; } export function isTransientRequestRateLimit(input: { status?: number; code?: string | null; message?: string; }): boolean { if (isProviderScopedQuotaCap(input.status, input.message ?? "", input.code)) return false; const code = (input.code ?? "").trim().toLowerCase().replaceAll("-", "_"); if (QUOTA_LIMIT_CODES.has(code)) return false; if (TRANSIENT_REQUEST_RATE_CODES.has(code)) return true; const text = (input.message ?? "").toLowerCase(); if ( text.includes("usage limit reached") || text.includes("insufficient_quota") || text.includes("quota exhausted") ) { return false; } return text.includes("rate limit reached for requests"); } export function remainingComboCooldownMs(comboId: string, now = Date.now()): number | undefined { const prefix = `${comboId}\0`; let soonest: number | undefined; for (const [key, cooldown] of targetCooldowns) { if (!key.startsWith(prefix)) continue; const remaining = cooldown.cooldownUntil - now; if (remaining <= 0) { targetCooldowns.delete(key); continue; } if (soonest === undefined || remaining < soonest) soonest = remaining; } return soonest; } export function comboCooldownRetryAfterSeconds(comboId: string, now = Date.now()): string | undefined { const remainingMs = remainingComboCooldownMs(comboId, now); if (remainingMs === undefined) return undefined; return String(Math.max(1, Math.ceil(remainingMs / 1000))); } /** Record a combo target cooldown, preferring bounded upstream retry evidence. */ export function coolComboTarget( comboId: string, target: Pick<OcxComboTarget, "provider" | "model">, options?: { retryAfter?: string | null; resetAt?: unknown | unknown[]; now?: number; cooldownMs?: number; writerGeneration?: number; status?: number; code?: string | null; message?: string; }, ): boolean { const now = options?.now ?? Date.now(); const writerGeneration = options?.writerGeneration ?? captureConfigGeneration(); const ownerKey = `${comboId}::${targetKey(target)}`; if (writerGeneration < lastReconciledGeneration && !liveComboTargets.has(ownerKey)) return false; // A server-provided Retry-After is authoritative, including an immediate `0` directive. // A quota reset is the next-most-specific signal (#3256); configured and default cooldowns // are only fallbacks when upstream supplied neither usable value. const serverDelayMs = parseRetryAfterMs(options?.retryAfter, now, { preserveImmediate: true, preserveServerDelay: true, }); const cooldownMs = serverDelayMs ?? parseResetCooldownMs(options?.resetAt, now) ?? options?.cooldownMs // A spent account window or an unpaid/rejected credential does not turn over in a minute, // so the 60s default would re-offer a target that cannot succeed. Only the duration // changes; the scope and hop decisions are untouched. ?? (isAccountWindowExhausted(options?.message ?? "", options?.code) || PROVIDER_SCOPED_FAILURE_CODES.has(normalizedFailureCode(options?.code)) ? MAX_COOLDOWN_MS : isTransientRequestRateLimit({ status: options?.status, code: options?.code, message: options?.message, }) ? COMBO_REQUEST_RATE_COOLDOWN_MS : DEFAULT_COOLDOWN_MS); targetCooldowns.set(cooldownMapKey(comboId, target), { // Local fallbacks are capped at ten minutes; explicit server delays at one day. cooldownUntil: now + (serverDelayMs ?? Math.min(Math.max(cooldownMs, 1), MAX_COOLDOWN_MS)), }); sweepExpiredOnWrite(now); return true; } export function earliestComboCooldown( comboId: string, targets: Iterable<Pick<OcxComboTarget, "provider" | "model">>, now = Date.now(), ): { expiry: number; target: Pick<OcxComboTarget, "provider" | "model"> } | undefined { let earliest: { expiry: number; target: Pick<OcxComboTarget, "provider" | "model"> } | undefined; for (const target of targets) { const key = cooldownMapKey(comboId, target); const entry = targetCooldowns.get(key); if (!entry || entry.cooldownUntil <= now) continue; if (earliest === undefined || entry.cooldownUntil < earliest.expiry) { earliest = { expiry: entry.cooldownUntil, target }; } } return earliest; } /** Public convenience wrapper returning only the earliest cooldown expiry. */ export function earliestComboCooldownExpiry( comboId: string, targets: Iterable<Pick<OcxComboTarget, "provider" | "model">>, now = Date.now(), ): number | undefined { return earliestComboCooldown(comboId, targets, now)?.expiry; } export function reconcileComboTargetCooldowns(context: GenerationContext): number { if (context.generation <= lastReconciledGeneration) return 0; liveComboTargets = new Set(context.comboTargets); lastReconciledGeneration = context.generation; return 0; } export function sweepExpiredComboTargetCooldowns(now = Date.now()): number { let removed = 0; for (const [key, cooldown] of targetCooldowns) { if (cooldown.cooldownUntil > now) continue; targetCooldowns.delete(key); removed += 1; } return removed; } export function clearComboTargetCooldowns(comboId?: string): void { if (comboId === undefined) { targetCooldowns.clear(); liveComboTargets.clear(); lastReconciledGeneration = 0; return; } const prefix = `${comboId}\0`; for (const key of targetCooldowns.keys()) { if (key.startsWith(prefix)) targetCooldowns.delete(key); } } export type ComboFailureDecision = "hop" | "stop"; export type ComboFailureCooldownScope = "none" | "target" | "provider"; function normalizedFailureCode(code?: string | null): string { return code?.trim().toLowerCase().replaceAll("-", "_") ?? ""; } /** * A spent account window, by structured code or upstream prose. Status is deliberately not * consulted: the ChatGPT Codex backend reports a depleted plan window as HTTP 502 * `upstream_server_error` carrying `The usage limit has been reached`, never the documented 429, * so any status gate misses it. Read in exactly ONE place -- the cooldown DURATION fallback. A * status-blind prose match is safe for choosing how long to wait; it is not safe for choosing * what to black out, so `isProviderScopedQuotaCap` and the scope/decision paths stay untouched * and a Codex 502 still resolves `target` scope and `hop` through `status >= 500`. */ // `1308` is the vendor code for a spent five-hour window and carries no prose of its own when the // upstream reports it bare, so it belongs here too. The rest of QUOTA_LIMIT_CODES stays out: those // are quota-limit codes whose window length this gateway has no evidence for, and guessing long on // them would hold a target that may clear sooner. const ACCOUNT_EXHAUSTION_CODES = new Set(["usage_limit_exceeded", "usage_limit_reached", "1308"]); // Token-plan windows (Alibaba's DeepSeek/Qwen plans) report "Your token-plan 1-week quota has been // exhausted" (#5494). The match is anchored to that phrasing: a looser "quota ... exhausted" would // also catch per-minute limits, and this arm outranks the transient rate-limit duration. const ACCOUNT_EXHAUSTION_TEXT = /usage limit (?:has been )?reached|token-plan\s+\S+\s+quota has been exhausted/; function isAccountWindowExhausted(message: string, code?: string | null): boolean { return ACCOUNT_EXHAUSTION_CODES.has(normalizedFailureCode(code)) || ACCOUNT_EXHAUSTION_TEXT.test(message.toLowerCase()); } function isProviderScopedQuotaCap( status: number | undefined, message: string, code?: string | null, ): boolean { const normalizedCode = normalizedFailureCode(code); const text = message.toLowerCase(); if ( status === 429 && (normalizedCode === "gousagelimiterror" || text.includes("monthly usage limit reached")) ) { return true; } return text.includes("err_free_prompt_cap") || (text.includes("free tier") && text.includes("single request")); } /** * A free-tier cap the upstream evaluates PER REQUEST rather than per account window. These * needles used to reach only `isProviderScopedQuotaCap`, so a single oversized free-tier prompt * cooled the whole provider for every other combo — including the shorter requests that same * provider would still have served. `free_rate_limited` also left the provider-scoped predicate * for the same reason; it stays a hop signal, but stops recording provider-wide evidence. */ function isRequestLocalFreePromptCap( status: number | undefined, message: string, code?: string | null, ): boolean { if (status !== 400) return false; const text = message.toLowerCase(); if (normalizedFailureCode(code) === "free_rate_limited") return true; if (text.includes("err_free_prompt_cap")) return true; return text.includes("free tier") && (text.includes("single request") || text.includes("prompt")); } /** * Failures that describe the SHAPE of this request rather than the health of the target. * Cooling anything for these is wrong twice over: the target is fine, and the next request * (shorter prompt, smaller tool catalog) would have succeeded against it. */ const REQUEST_SHAPE_FAILURE_CODES = new Set([ "input_admission_refused", "context_length_exceeded", "tool_catalog_too_large", "cursor_root_envelope_limit", "target_incompatible", ]); /** Credential/billing failures that every target sharing the provider inherits. */ const PROVIDER_SCOPED_FAILURE_CODES = new Set([ "invalid_api_key", "insufficient_quota", "subscription_required", "payment_required", "billing_error", "insufficient_balance", ]); /** * Precise target-local request incompatibilities are request-local, not terminal for a combo. * Require a bounded, intact provider envelope; never infer compatibility from echoed prompt text. * Only OpenCodex's exact error wrapper may be unwrapped, with a fixed depth budget. Unknown or * conflicting codes fail closed. No fields are removed here and no same-target replay is added. * Image rejection requires `param: input` and an exact model-scoped prefix. */ function isRequestLocalTargetIncompatibility(status: number, message: string, code?: string | null): boolean { if (status !== 400 || message.length > 16_384) return false; const genericCodes = new Set(["", "invalid_request_error", "unsupported_parameter", "unsupported_value"]); if (!genericCodes.has(normalizedFailureCode(code))) return false; let text = message.trim(); for (let depth = 0; depth < 3; depth += 1) { if (text.startsWith("Provider error 400: ")) text = text.slice("Provider error 400: ".length); let payload: unknown; try { payload = JSON.parse(text); } catch { return false; } if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false; const error = (payload as Record<string, unknown>).error; if (!error || typeof error !== "object" || Array.isArray(error)) return false; const e = error as Record<string, unknown>; if (e.code !== undefined && e.code !== null && typeof e.code !== "string") return false; const errorCode = normalizedFailureCode(typeof e.code === "string" ? e.code : undefined); if (!genericCodes.has(errorCode) || typeof e.message !== "string") return false; if (e.type !== "invalid_request_error" && e.type !== "upstream_error") return false; if (e.message.startsWith("Provider error 400: ") && e.param === undefined && (errorCode === "" || errorCode === "invalid_request_error")) { text = e.message; continue; } if (e.type !== "invalid_request_error") return false; if (e.message === "Unsupported parameter: user") { return (e.param === undefined || e.param === "user") && errorCode !== "unsupported_value"; } if (errorCode === "unsupported_value" && (e.param === "reasoning.effort" || e.param === "reasoning_effort") && e.message.startsWith("Unsupported value:") && e.message.includes("not supported")) return true; if (e.code === null && e.param === "reasoning_effort" && /^Function tools with reasoning_effort are not supported for gpt-6-astra(?:-\d{4}-\d{2}-\d{2})? in \/v1\/chat\/completions\. To use function tools, use \/v1\/responses or set reasoning_effort to 'none'\.$/.test(e.message)) return true; return e.param === "input" && (errorCode === "" || errorCode === "invalid_request_error") && /^Model '[^']{1,256}' does not support image inputs\./.test(e.message); } return false; } /** * Codes a gateway uses when it declines a request field it cannot serve. * * Wider than the set {@link isRequestLocalTargetIncompatibility} accepts, by exactly one member: * Alibaba's gateway reports `invalid_parameter_error`. It is kept in its own set rather than * added to the shared one, because that set also governs the `user` parameter and image-input * branches and widening it there would admit shapes those branches were reasoned about without. */ const RESPONSE_FORMAT_REFUSAL_CODES = new Set([ "", "invalid_request_error", "invalid_parameter_error", "unsupported_parameter", "unsupported_value", ]); /** * Does this message say the target cannot PROVIDE `response_format`, rather than that the * request's `response_format` was malformed? * * That distinction is the whole point of #4903 and it is why neither obvious option was taken. * Hopping on every 400 would replay a genuinely malformed request against every remaining * target. Dropping `response_format` would silently change the output contract the caller * asked for, on a path whose entire purpose is a structured result. * * So both halves are required: the message must name the field, AND it must say the field is * unavailable or unsupported. "Invalid schema for response_format" names the field and claims * nothing about capability, so it stays terminal. * * `param` may be absent or explicitly null -- the reported gateway sends `param: null` -- but a * param naming a DIFFERENT field contradicts the message and fails closed. */ function namesResponseFormatIncapability(message: string, param: unknown): boolean { if (param !== undefined && param !== null && param !== "response_format") return false; const text = message.toLowerCase(); if (!text.includes("response_format")) return false; return /(unavailable|not available|unsupported|not supported|does not support|doesn't support|cannot be used|is not enabled)/u .test(text); } /** * A `response_format` capability gap is target-local: this model cannot produce the requested * output shape, which says nothing about the next target in the combo. * * Reported against a shadow title-generation call, where a combo's first target rejects * `response_format` and the chain stops instead of trying the target behind it (#4903). * * The next target receives the SAME request, `response_format` included, so a target that can * honour the contract honours it and one that cannot is skipped in turn. Traversal stays finite * because combo excludes each attempted target and policy tries each candidate once. * * The envelope is bounded exactly like {@link isRequestLocalTargetIncompatibility}: an intact * provider JSON object, a depth budget, `type: "invalid_request_error"`, and a code from a * closed set. Nothing is inferred from echoed prompt text and no field is removed. */ function isResponseFormatCapabilityRefusal( status: number, message: string, code?: string | null, ): boolean { if (status !== 400 || message.length > 16_384) return false; if (!RESPONSE_FORMAT_REFUSAL_CODES.has(normalizedFailureCode(code))) return false; let text = message.trim(); for (let depth = 0; depth < 3; depth += 1) { if (text.startsWith("Provider error 400: ")) { text = text.slice("Provider error 400: ".length).trim(); } // A chat gateway can report the refusal inside a single SSE frame, and the combo consumer // keeps the raw text when that frame stops the error object from being extracted -- which is // why the reported classification text reads `data: {"error":...}` and why the structured // code arrives undefined. Exactly one `data:` prefix is removed, and only when the body is // one line: this unwraps a single frame rather than parsing a stream, so a multi-event body // is left alone and still fails closed. if (text.startsWith("data:") && !text.includes("\n")) { text = text.slice("data:".length).trim(); } let payload: unknown; try { payload = JSON.parse(text); } catch { return false; } if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false; const error = (payload as Record<string, unknown>).error; if (!error || typeof error !== "object" || Array.isArray(error)) return false; const e = error as Record<string, unknown>; if (e.code !== undefined && e.code !== null && typeof e.code !== "string") return false; if (typeof e.message !== "string") return false; // Our own wrapper, re-wrapped by a downstream hop. Peel it and look again, within budget. if (e.message.startsWith("Provider error 400: ") && e.param === undefined) { text = e.message; continue; } if (e.type !== "invalid_request_error") return false; const errorCode = normalizedFailureCode(typeof e.code === "string" ? e.code : undefined); if (!RESPONSE_FORMAT_REFUSAL_CODES.has(errorCode)) return false; return namesResponseFormatIncapability(e.message, e.param); } return false; } export function comboFailureCooldownScope( status: number, message: string, options?: { code?: string | null }, ): ComboFailureCooldownScope { const code = normalizedFailureCode(options?.code); // Request-shape refusals first: an oversized request must not cool a healthy target. // A native transport can surface a zero-output model overflow as a generic // upstream_server_error carrying precise context-window prose, so consult the bounded // message classifier too: that target is healthy, the turn was simply too large for it. if ( status === 413 || REQUEST_SHAPE_FAILURE_CODES.has(code) || isRequestLocalFreePromptCap(status, message, options?.code) || isProviderTargetContextOverflow(status, message, options?.code) || isDefiniteContextOverflow(status, message) || isRequestLocalTargetIncompatibility(status, message, options?.code) // A capability gap says the target is healthy and the request did not fit it, which is the // same reason every other entry here refuses to cool a target. || isResponseFormatCapabilityRefusal(status, message, options?.code) ) return "none"; if (isProviderScopedQuotaCap(status, message, options?.code)) return "provider"; // A rejected or unpaid credential is provider-wide evidence: every target that routes // through the same provider row carries the same key and will fail identically. if (status === 401 || status === 402 || status === 403) return "provider"; if (PROVIDER_SCOPED_FAILURE_CODES.has(code)) return "provider"; return "target"; } function isModelLifecycleGone( status: number, message: string, code?: string | null, ): boolean { if (status !== 410) return false; const normalizedCode = code?.trim().toLowerCase().replaceAll("-", "_"); if ([ "model_deprecated", "model_end_of_life", "model_eol", "model_not_found", "model_retired", ].includes(normalizedCode ?? "")) return true; const text = message.toLowerCase(); return /\bmodel\b/.test(text) && ( /\bend[ -]of[ -]life\b/.test(text) || /\bno longer available\b/.test(text) || /\b(?:deprecated|retired|retirement|sunset|decommissioned)\b/.test(text) ); } function isProviderTargetContextOverflow( status: number, message: string, code?: string | null, ): boolean { if (status !== 400) return false; const normalizedCode = normalizedFailureCode(code); const text = message.toLowerCase(); if (text.includes("invalid_request_prompt_too_long")) return true; return normalizedCode === "5059" && /\bprompt\s+\d+\s*>\s*\d+\s+maximum context length\b/i.test(message); } /** A status can carry a verdict about the REQUEST; 401/403/429 speak about the credential. */ const CONTEXT_VERDICT_STATUSES: ReadonlySet<number> = new Set([400, 413, 422]); /** * Phrases a provider emits when the INPUT does not fit this model's context window. Matched * against the innermost provider message only, so an unrelated refusal that merely quotes one * of these tokens in a code field cannot authorize a replay. */ const DEFINITE_CONTEXT_OVERFLOW_PHRASES = [ "exceeds the context window", "exceed the context window", "context window exceeded", "context length exceeded", "maximum context length", "maximum context window", "too many tokens", ]; /** Wrapper envelopes unwrapped before the leaf message is read. */ const MAX_CONTEXT_OVERFLOW_ENVELOPES = 4; function isDefiniteContextOverflowMessage(text: string): boolean { const normalized = text.toLowerCase(); return normalized === "context_length_exceeded" || DEFINITE_CONTEXT_OVERFLOW_PHRASES.some(phrase => normalized.includes(phrase)); } /** * Confirm a context overflow from the provider MESSAGE rather than from a code token that * merely appears somewhere in the envelope. An upstream controls both fields and can emit a * contradictory pair -- `context_length_exceeded` beside `Unsupported parameter: user` -- and * that is not evidence the turn is too large for this model. `classifyError` reads the whole * blob, which is exactly the looseness this must not inherit. * * A JSON-shaped body that fails to parse is truncated or corrupt, not prose: `classificationText` * is capped at 500 characters by `normalizeUpstreamErrorText` before it reaches this function, so * a long envelope arrives here as a JSON prefix. Reading that prefix as plain text would let an * arbitrary field that happens to sit in the first 500 bytes authorize a hop, so it fails closed. * * Only the exact proxy wrapper is unwrapped, within a fixed envelope budget and 16,384 characters. */ function isDefiniteContextOverflow(status: number, message: string): boolean { if (!CONTEXT_VERDICT_STATUSES.has(status) && status < 500) return false; if (message.length > 16_384) return false; let text = message.trim(); // One pass per unwrapped envelope, plus one for the leaf the last envelope yields. for (let unwrapped = 0; unwrapped <= MAX_CONTEXT_OVERFLOW_ENVELOPES; unwrapped += 1) { const providerPrefix = /^Provider error \d{3}:\s*/.exec(text); if (providerPrefix) text = text.slice(providerPrefix[0].length).trim(); if (!text.startsWith("{")) return isDefiniteContextOverflowMessage(text); if (unwrapped === MAX_CONTEXT_OVERFLOW_ENVELOPES) return false; let payload: unknown; try { payload = JSON.parse(text); } catch { return false; } if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false; const record = payload as Record<string, unknown>; const response = record.response && typeof record.response === "object" && !Array.isArray(record.response) ? record.response as Record<string, unknown> : undefined; const source = [record.error, response?.error, response?.last_error, record.last_error, record] .find((candidate): candidate is Record<string, unknown> => !!candidate && typeof candidate === "object" && !Array.isArray(candidate) && typeof (candidate as Record<string, unknown>).message === "string"); if (!source) return false; text = (source.message as string).trim(); } return false; } export function comboFailureDecision( status: number, message: string, options?: { code?: string | null }, ): ComboFailureDecision { if (status === 499) return "stop"; if (message.toLowerCase().includes("origin_rejected")) return "stop"; // Structured form of the same hard refusal. The prose test above misses it when the origin // reports the code out of band, and every hop rule below -- including the context-overflow // one -- must stay subordinate to it. if (normalizedFailureCode(options?.code) === "origin_rejected") return "stop"; // The origin may already be executing this turn (the Codex WebSocket relay sent the create // frame and never saw a response event). Hopping would send the same request to a second // target while the first may still be generating; the honest status goes to the client. if (isNonReplayableUpstreamCode(options?.code)) return "stop"; // Cyber policy is a hard non-retryable refusal — honor structured code even when // classificationText was truncated before the JSON code field. if (isCyberPolicyCode(options?.code)) return "stop"; // HTTP 410 is normally terminal. A model-specific lifecycle verdict is target-local, // however: another provider/model in the declared combo can still serve the request. // Require structured lifecycle code or explicit model+lifecycle prose so unrelated // application-level 410 responses remain fail-closed. if (isModelLifecycleGone(status, message, options?.code)) return "hop"; const error = classifyError(status, "upstream_error", message); if (isCyberPolicyCode(error.code)) return "stop"; // A provider can expose its own target hard cap with a non-semantic vendor code // (for example 5059 + invalid_request_prompt_too_long). That is evidence that this // target is too small, not that every later combo target is incapable of serving it. if (isProviderTargetContextOverflow(status, message, options?.code)) return "hop"; // A definite context-window refusal is target-local inside a heterogeneous combo: this model // cannot hold the turn, but a later target may have a larger window. Two boundaries keep this // safe. It is reached only after cancellation, structured origin/cyber refusals and // non-replayable post-send codes have already stopped. And it only ever classifies a failure // the combo stream preflight already proved emitted no output: `comboStreamPayloadCommitsOutput` // commits the child on any text, tool call or unknown event, and only a zero-output terminal // becomes a failure response at all, so a turn whose text the client already saw is never // reclassified here. if (isDefiniteContextOverflow(status, message)) return "hop"; // A local input-admission refusal (#1524) says "this candidate cannot fit the request", // not "the request is impossible": the next candidate may have a larger context window. // // This MUST be tested before the generic stop list below. Our own refusal message says // "context window" -- that is what it refuses on -- and the classifier remaps that phrase, // so checking the stop list first swallowed the signal and ended the chain. An UPSTREAM // `context_length_exceeded` carries no admission code and still falls through to stop. // // Matched on the STRUCTURED code only, which classifyError now preserves for our own // refusal. A raw substring test would additionally let any upstream override a terminal // verdict by echoing the token in prose we do not control. // // Precise about what this is NOT: an upstream can still SET this code deliberately, since // both extractors read the upstream error object. That is bounded rather than dangerous -- // an upstream already controls other hop signals (429, 5xx), and traversal is finite: policy // tries each candidate once via `tried`, and combo excludes each attempted target. So this is // structured-code-only, not provably local. if (options?.code === "input_admission_refused" || error.code === "input_admission_refused") { return "hop"; } if (isProviderScopedQuotaCap(status, message, options?.code || error.code)) { return "hop"; } // A model-scoped rejection is target-local: this provider does not serve THIS model, which // says nothing about the next combo target. Structured code only, plus the explicit prose // form upstreams emit when they carry no code, so an unrelated 400 stays terminal. const failureCode = normalizedFailureCode(options?.code || error.code); if (["model_not_found", "model_unavailable", "unsupported_model"].includes(failureCode)) { return "hop"; } // `free_rate_limited` no longer routes through `isProviderScopedQuotaCap` (it is a // per-request cap, not provider-wide evidence), so keep its hop verdict explicit here. if (failureCode === "free_rate_limited") return "hop"; if (isRequestLocalTargetIncompatibility(status, message, options?.code)) return "hop"; // Must precede the generic `invalid_request_error` stop below, which is where this refusal // ended the chain: the gateway reports `type: "invalid_request_error"`, so the classifier // reaches that list and returns terminal before anything can ask whether the next target // could have served the request (#4903). if (isResponseFormatCapabilityRefusal(status, message, options?.code)) return "hop"; if (["origin_rejected", "context_length_exceeded", "invalid_request_error"].includes(error.code ?? "")) { return "stop"; } // 402 (payment required) and 425 (too early) are provider-state signals, not verdicts about // the request: another combo target can still serve it. if ([401, 402, 403, 404, 408, 425, 429].includes(status) || status >= 500) return "hop"; if ([ "permission_denied", "subscription_required", "invalid_api_key", "insufficient_quota", "payment_required", "billing_error", "insufficient_balance", "rate_limit_exceeded", "server_is_overloaded", "upstream_server_error", ].includes(error.code ?? "")) { return "hop"; } return "stop"; }