UNPKG

@bitkyc08/opencodex

Version:

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

1,120 lines (1,049 loc) • 43.6 kB
import { codexAccountUsesCreditsAfterLimit } from "./account-credit-use"; /** * Quota-aware subagent model fallback (issue #374). * * codex-rs spawns children with the agent-role TOML `model` pinned; when that model's * provider quota is exhausted the child fails immediately. This module rewrites thread_spawn * requests at the proxy choke point to the next healthy model in a configured fallback chain. */ import { existsSync, readdirSync, readFileSync } from "node:fs"; import { join } from "node:path"; import { hasOwnProvider } from "../config"; import { isRateLimitOrQuotaFailureMessage } from "../lib/errors"; import type { OcxParsedRequest, OcxConfig } from "../types"; import { slugsEquivalent } from "../providers/slug-codec"; import { CODEX_HOME, getCodexHome } from "./paths"; import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota } from "./quota"; import { canAcquireCodexQuotaProbeLease, canAcquireCodexQuotaScopeProbeLease, codexQuotaScopeForModel, computeCodexUsageScore, getCodexQuotaHealthSnapshot, getEffectiveActiveCodexAccountId, getPoolAccountPlan, } from "./routing"; import { isCodexAccountUsable, type CodexAccountUsabilityOptions, } from "./account-usability"; import { isCodexAccountPaused } from "./account-pause"; import { getEffectiveCodexAutoSwitchThreshold } from "./account-auto-switch"; import { slugEquals } from "../providers/slug-codec"; import { isThreadSpawnRequest } from "../server/effort-policy"; import { PROVIDER_REGISTRY } from "../providers/registry"; import { CODEX_FORWARD_BASE_URL, OPENAI_CODEX_PROVIDER_ID, isCanonicalOpenAiForwardProvider, } from "../providers/openai-tiers"; import { routeModel, type RouteResult } from "../router"; import { guardFallbackHop, type FallbackAdmission } from "../routing/fallback-policy"; import { sweepExpiredOnWrite } from "../lib/state-store-sweeper"; import { codexAccountNamespaceForModel } from "./account-namespace-match"; import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS, NATIVE_MAIN_DRAIN_SENTINEL_MODELS } from "./catalog/native-models"; import { MAIN_CODEX_ACCOUNT_ID } from "./main-account"; import { decodeTomlBasicString } from "./prompt-layers/encoding"; import { getUpstreamHostHealth, normalizeUpstreamHostCircuitThreshold, upstreamHostHealthKey, } from "./upstream-host-health"; export const DEFAULT_SUBAGENT_MODEL_FALLBACK_POLL_MS = 60_000; const CODEX_FORWARD_ORIGIN = new URL(CODEX_FORWARD_BASE_URL).origin.toLowerCase(); type SubagentQuotaPrimeFn = (config: OcxConfig, reason: string) => Promise<void>; /** Side-effect-free Pool account preview for one resolved fallback candidate. */ export type SubagentPoolAccountPreview = ( modelId: string | undefined, now: number, modelEligibleAccountIds?: ReadonlySet<string>, ) => string | null; export type SubagentModelEligibleAccountIds = ( modelId: string | undefined, ) => ReadonlySet<string> | undefined; /** Additional resolved routes that a restricted fallback caller has independently approved. */ export type SubagentFallbackRouteEligibility = (route: RouteResult) => boolean; let subagentQuotaPrimeForTests: SubagentQuotaPrimeFn | null = null; let quotaPrimeInFlight: Promise<void> | null = null; type ModelHealth = { unavailableUntil: number; reason: string; }; const modelHealth = new Map<string, ModelHealth>(); const quotaPrimedAt = new Map<string, number>(); const knownProviderIdSet = new Set(PROVIDER_REGISTRY.map(entry => entry.id.toLowerCase())); function tryRouteFallbackModel(config: OcxConfig, model: string): RouteResult | null { try { return routeModel(config, model); } catch { return null; } } function isPoolCodexRoute(route: RouteResult): boolean { return route.codexAccountMode === "pool"; } function healthKey(model: string, accountId: string | null, poolScoped: boolean): string { const scopedAccountId = poolScoped ? accountId : null; return `${scopedAccountId ?? "none"}::${model.toLowerCase()}`; } function isDisabledFallbackModel(model: string, config: OcxConfig): boolean { const disabled = config.disabledModels ?? []; if (disabled.length === 0) return false; if (!model.includes("/")) { return disabled.some(stored => stored === model || slugEquals(stored, "openai", model)); } const slash = model.indexOf("/"); const provider = model.slice(0, slash); const modelId = model.slice(slash + 1); if (codexAccountNamespaceForModel(config.codexAccountNamespaces, model)) { return disabled.some(stored => stored === model || stored === modelId || slugEquals(stored, "openai", modelId) ); } return disabled.some(stored => stored === model || slugEquals(stored, provider, modelId)); } function pollIntervalMs(config: OcxConfig): number { const configured = config.subagentModelFallbackPollMs; if (typeof configured !== "number" || !Number.isFinite(configured) || configured < 1_000) { return DEFAULT_SUBAGENT_MODEL_FALLBACK_POLL_MS; } return configured; } function fallbackChainKey(model: string, namespaces: unknown): string { const selector = codexAccountNamespaceForModel(namespaces, model); if (!selector) return JSON.stringify(["model", model.toLowerCase()]); const slash = model.indexOf("/"); // Selector keys are exact-case account boundaries. Keep that segment distinct while // retaining legacy case-insensitive de-duplication for the native model suffix. return JSON.stringify(["account", selector, model.slice(slash + 1).toLowerCase()]); } function normalizedChain( primary: string, config: OcxConfig, extra: readonly string[] = [], trailing: readonly string[] = [], ): string[] { const chain: string[] = []; const seen = new Set<string>(); const push = (model: string | undefined) => { if (!model || model.trim() === "") return; const trimmed = model.trim(); const key = fallbackChainKey(trimmed, config.codexAccountNamespaces); if (seen.has(key)) return; seen.add(key); chain.push(trimmed); }; push(primary); for (const model of extra) push(model); for (const model of config.subagentModelFallback ?? []) push(model); for (const model of trailing) push(model); return chain; } export function buildSubagentModelChain( primary: string, config: OcxConfig, extraFallback: readonly string[] = [], ): string[] { return normalizedChain(primary, config, extraFallback); } function quotaThreshold(config: OcxConfig, accountId: string): number { const threshold = getEffectiveCodexAutoSwitchThreshold(config, accountId); return threshold > 0 ? threshold : Number.POSITIVE_INFINITY; } /** * The account routing would actually use, not just the persisted operator * selection: round-robin, fill-first, failover, and priority preemption all * move the cursor in memory only, so reading the raw field would check quota * against an account this request is not going to touch. */ function activeCodexAccountId(config: OcxConfig): string | null { return getEffectiveActiveCodexAccountId(config) ?? null; } /** * Resolve the account id used for pool-scoped quota/health checks. * Explicit `null` means the pre-fallback preview found no usable account — do not * substitute `activeCodexAccountId` (that active id may itself be unusable). */ function resolvePoolFallbackAccountId( config: OcxConfig, accountId?: string | null, ): string | null { if (typeof accountId === "string") return accountId; if (accountId === null) return null; return activeCodexAccountId(config); } function resolveRouteFallbackAccountId( route: RouteResult | null, config: OcxConfig, accountId?: string | null, now = Date.now(), poolAccountPreview?: SubagentPoolAccountPreview, modelEligibleAccountIds?: ReadonlySet<string>, ): string | null { if (route?.codexAccountId !== undefined) return route.codexAccountId; if (route && isPoolCodexRoute(route) && poolAccountPreview) { return poolAccountPreview(route.modelId, now, modelEligibleAccountIds); } return resolvePoolFallbackAccountId(config, accountId); } function isRoutableFallbackModel(model: string, config: OcxConfig): boolean { const slash = model.indexOf("/"); if (slash > 0) { if (codexAccountNamespaceForModel(config.codexAccountNamespaces, model)) return true; const providerName = model.slice(0, slash); if (!hasOwnProvider(config.providers, providerName)) { // Allow well-known "vendor/model" ids (e.g. anthropic/claude-*) to flow as // raw model ids through the default provider, but reject stale/typo prefixes. return knownProviderIdSet.has(providerName.toLowerCase()); } const provider = config.providers[providerName]; if (provider?.disabled === true) return false; } return true; } export function isNativeModelQuotaExhausted( model: string, config: OcxConfig, accountId?: string | null, now = Date.now(), ): boolean { const route = tryRouteFallbackModel(config, model); if (!route || !isPoolCodexRoute(route)) return false; const resolvedAccountId = resolveRouteFallbackAccountId(route, config, accountId); if (!resolvedAccountId) return false; const quota = getAccountQuota(resolvedAccountId); // Subagent fallback reads the same score, so a stale terminal reading would push // subagents off a native model whose window has already reset. Thread the caller's clock // rather than letting the scorer read wall time - the two would silently diverge. const usage = computeCodexUsageScore(quota, getPoolAccountPlan(config, resolvedAccountId), now, codexAccountUsesCreditsAfterLimit(config, resolvedAccountId)); if (usage >= CODEX_UNKNOWN_USAGE_SCORE) return false; return usage >= quotaThreshold(config, resolvedAccountId); } export function isModelHealthBlocked( model: string, config: OcxConfig, accountId?: string | null, now = Date.now(), ): boolean { const route = tryRouteFallbackModel(config, model); const poolScoped = !!route && isPoolCodexRoute(route); const health = modelHealth.get( healthKey( model, resolveRouteFallbackAccountId(route, config, accountId), poolScoped, ), ); return !!health && health.unavailableUntil > now; } export function isSubagentModelUnavailable( model: string, config: OcxConfig, accountId?: string | null, now = Date.now(), accountUsabilityOptions?: CodexAccountUsabilityOptions, poolAccountPreview?: SubagentPoolAccountPreview, modelEligibleAccountIdsForModel?: SubagentModelEligibleAccountIds, ): boolean { if (isDisabledFallbackModel(model, config)) return true; if (!isRoutableFallbackModel(model, config)) return true; const route = tryRouteFallbackModel(config, model); if (!route || route.provider.disabled === true) return true; const modelEligibleAccountIds = modelEligibleAccountIdsForModel?.(route.modelId); const candidateAccountUsabilityOptions = modelEligibleAccountIds !== undefined ? { ...accountUsabilityOptions, modelEligibleAccountIds, } : accountUsabilityOptions; const resolvedAccountId = resolveRouteFallbackAccountId( route, config, accountId, now, poolAccountPreview, candidateAccountUsabilityOptions?.modelEligibleAccountIds, ); const accountUnavailable = ( candidateAccountId: string | null, usabilityOptions: CodexAccountUsabilityOptions | undefined, includeQuotaExhaustion: boolean, ): boolean => { if (isModelHealthBlocked(model, config, candidateAccountId, now)) return true; if (!isPoolCodexRoute(route)) return false; // Pool candidates need a usable account. Derive requirement from the resolved // route (canonical openai defaults to pool even when codexAccountMode is omitted). if (!candidateAccountId) return true; if (isCodexAccountPaused(config, candidateAccountId)) return true; // An account-qualified route is an explicit selector, outside the pool-only policy (#7410). if (!isCodexAccountUsable(config, candidateAccountId, route.codexAccountId !== undefined ? { ...usabilityOptions, explicitAccountSelector: true } : usabilityOptions)) return true; if (route.codexAccountId !== undefined) { // An account-qualified route is pinned and cannot consume Pool's recovery-probe // escape hatch. Honor both account-wide and model-scoped cooldowns so fallback // advances instead of selecting a candidate that exact auth will reject. const quotaScope = codexQuotaScopeForModel(route.modelId); if (getCodexQuotaHealthSnapshot(candidateAccountId, quotaScope, now) !== null) return true; } else { const quotaScope = codexQuotaScopeForModel(route.modelId); const cooldown = getCodexQuotaHealthSnapshot(candidateAccountId, quotaScope, now); if (cooldown !== null) { const probeAvailable = cooldown.quotaScope ? canAcquireCodexQuotaScopeProbeLease(candidateAccountId, cooldown.quotaScope, now) : canAcquireCodexQuotaProbeLease(candidateAccountId, now); if (!probeAvailable) return true; } } if ( !includeQuotaExhaustion || ( candidateAccountId === MAIN_CODEX_ACCOUNT_ID && usabilityOptions?.nativeMainSelectionOnly === true ) ) return false; return isNativeModelQuotaExhausted(model, config, candidateAccountId, now); }; // Prefer a genuinely usable entitled pool account. Preview can deliberately return // the configured active account even when no selectable candidate exists, so a // null/main-only check is not enough to detect the temporary-drain case. if (!accountUnavailable(resolvedAccountId, candidateAccountUsabilityOptions, true)) return false; // During a temporary native-main drain, entitlement discovery excludes main to // preserve the credential fence. If no non-main candidate can serve an unqualified // gated model, retain main only as a read-free sentinel: final auth owns the atomic // claim and returns maintenance instead of letting a routed fallback bypass it. // // The predicate is its OWN set, not the account-gated one. The sentinel protects the atomic // main claim during a drain, which has nothing to do with entitlement; it read the gated set // only because the two happened to hold the same slugs. Ungating the flagships (2026-09-04) // would have flipped this false and let a drain silently rewrite the operator's configured // subagent model instead of reporting maintenance -- a different model answering than was // chosen. The set is explicit rather than every supported native, so gpt-5.5 and friends keep // their existing fall-back-and-answer behaviour. const preserveDrainingMainCandidate = route.codexAccountId === undefined && candidateAccountUsabilityOptions?.nativeMainSelectionOnly === true && NATIVE_MAIN_DRAIN_SENTINEL_MODELS.has(route.modelId); if (!preserveDrainingMainCandidate) return true; const drainingMainUsabilityOptions: CodexAccountUsabilityOptions = { ...candidateAccountUsabilityOptions, modelEligibleAccountIds: new Set([ ...(modelEligibleAccountIds ?? []), MAIN_CODEX_ACCOUNT_ID, ]), }; // Quota scoring main would lazily read the native credential/plan. Cached health, // pause, reauth, and cooldown state are safe; defer physical scoring to final auth. return accountUnavailable(MAIN_CODEX_ACCOUNT_ID, drainingMainUsabilityOptions, false); } export function selectAvailableSubagentModel( primary: string, config: OcxConfig, extraFallback: readonly string[] = [], accountId?: string | null, now = Date.now(), nativeFallbackOnly = false, accountUsabilityOptions?: CodexAccountUsabilityOptions, trailingFallback: readonly string[] = [], poolAccountPreview?: SubagentPoolAccountPreview, modelEligibleAccountIdsForModel?: SubagentModelEligibleAccountIds, resolvedChain?: readonly string[], restrictedRouteEligible?: SubagentFallbackRouteEligibility, ): { model: string; rewritten: boolean; skipped: string[] } { const chain = resolvedChain ?? normalizedChain(primary, config, extraFallback, trailingFallback); const skipped: string[] = []; for (const candidate of chain) { if (nativeFallbackOnly) { const route = tryRouteFallbackModel(config, candidate); if ( !route || route.combo !== undefined || ( !isCanonicalOpenAiForwardProvider(route.provider) && restrictedRouteEligible?.(route) !== true ) ) { skipped.push(candidate); continue; } } if (isSubagentModelUnavailable( candidate, config, accountId, now, accountUsabilityOptions, poolAccountPreview, modelEligibleAccountIdsForModel, )) { skipped.push(candidate); continue; } return { model: candidate, rewritten: !slugsEquivalent(candidate, primary), skipped }; } return { model: primary, rewritten: false, skipped }; } export function noteSubagentModelFailure( model: string, message: string, config: OcxConfig, accountId?: string | null, now = Date.now(), ttlMs?: number, ): void { const interval = ttlMs ?? DEFAULT_SUBAGENT_MODEL_FALLBACK_POLL_MS; if (!isRateLimitOrQuotaFailureMessage(message)) return; const route = tryRouteFallbackModel(config, model); const poolScoped = !!route && isPoolCodexRoute(route); modelHealth.set( healthKey( model, resolveRouteFallbackAccountId(route, config, accountId), poolScoped, ), { unavailableUntil: now + interval, reason: "quota_exhausted", }, ); sweepExpiredOnWrite(now); } export function sweepExpiredSubagentModelHealth(now = Date.now()): number { let removed = 0; for (const [key, health] of modelHealth) { if (health.unavailableUntil > now) continue; modelHealth.delete(key); removed += 1; } return removed; } export function resetSubagentModelFallbackStateForTests(): void { modelHealth.clear(); quotaPrimedAt.clear(); quotaPrimeInFlight = null; subagentQuotaPrimeForTests = null; } /** Test-only: inject the quota prime implementation used by {@link maybePrimeSubagentQuota}. */ export function setSubagentQuotaPrimeForTests(fn: SubagentQuotaPrimeFn | null): void { subagentQuotaPrimeForTests = fn; } /** Test-only: inspect shared prime TTL / in-flight state. */ export function getSubagentQuotaPrimeStateForTests(): { primedAt: number; inFlight: boolean; } { return { primedAt: quotaPrimedAt.get("global") ?? 0, inFlight: quotaPrimeInFlight !== null, }; } function rewriteParsedModel(parsed: OcxParsedRequest, model: string): void { parsed.modelId = model; if (parsed._rawBody && typeof parsed._rawBody === "object") { (parsed._rawBody as { model?: string }).model = model; } } const TOML_MODEL = /^(model)\s*=\s*("(?:\\.|[^"\\])*")\s*$/; function parseTomlQuotedString(raw: string): string { const trimmed = raw.trim(); if ((trimmed.startsWith("\"") && trimmed.endsWith("\"")) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) { return trimmed.slice(1, -1).replace(/\\"/g, "\""); } return trimmed; } function readAgentModel(filePath: string): string | null { try { const content = readFileSync(filePath, "utf8"); for (const line of content.split(/\r?\n/)) { const match = line.match(TOML_MODEL); if (!match) continue; const model = parseTomlQuotedString(match[2] ?? ""); return model.trim() === "" ? null : model.trim(); } } catch { return null; } return null; } export function readCodexAgentModel(role: string, codexHome = CODEX_HOME): string | null { const file = join(codexHome, "agents", `${role}.toml`); if (!existsSync(file)) return null; return readAgentModel(file); } export function resolveAgentModelFallbackForPrimary( primary: string, codexHome = CODEX_HOME, namespaces?: unknown, ): string[] { const merged: string[] = []; const seen = new Set<string>(); const push = (model: string | null | undefined) => { if (!model || model.trim() === "") return; const trimmed = model.trim(); // Match global-chain de-dupe: keep account-selector prefixes case-sensitive when // those selectors are configured, while ordinary provider/model ids stay case-insensitive. const key = fallbackChainKey(trimmed, namespaces); if (seen.has(key)) return; seen.add(key); merged.push(trimmed); }; for (const role of listCodexAgentRoles(codexHome)) { const model = readCodexAgentModel(role, codexHome); if (!model || !slugsEquivalent(model, primary)) continue; for (const fallback of readCodexAgentModelFallback(role, codexHome)) push(fallback); } return merged; } function subagentQuotaPrimeBlockedByHostCircuit(config: OcxConfig): boolean { if (normalizeUpstreamHostCircuitThreshold(config.upstreamHostCircuitThreshold) === 0) return false; const key = upstreamHostHealthKey(OPENAI_CODEX_PROVIDER_ID, CODEX_FORWARD_ORIGIN); return getUpstreamHostHealth(key)?.cooldownUntil !== undefined; } /** * Per-primary-model fallback chains from opencodex config (#1190). * * Storing `model_fallback` inside `$CODEX_HOME/agents/*.toml` makes Codex >= 0.146 * reject the whole role file as an unknown field. The config-keyed map is the * supported home for that metadata; keys match the requested primary model id, * using the same raw/encoded slug tolerance as the TOML role lookup. */ export function resolveConfiguredModelFallbackForPrimary( primary: string, config: OcxConfig, ): string[] { const byModel = config.subagentModelFallbackByModel; if (!byModel || typeof byModel !== "object") return []; const entries: string[] = []; const seen = new Set<string>(); const push = (model: string) => { const trimmed = model.trim(); if (trimmed === "") return; const key = fallbackChainKey(trimmed, config.codexAccountNamespaces); if (seen.has(key)) return; seen.add(key); entries.push(trimmed); }; for (const [key, chain] of Object.entries(byModel)) { if (!slugsEquivalent(key, primary)) continue; for (const model of chain) push(model); } return entries; } /** * Best-effort quota refresh before subagent model selection. * Concurrent callers share one in-flight promise. The success TTL is updated only * after a successful refresh so failures remain retryable. Errors are swallowed so * spawn routing can continue. When the canonical ChatGPT origin is circuit-blocked, * cached quota is used instead of sending credential-bearing usage probes to the * same origin before the request's final host admission check. */ export function maybePrimeSubagentQuota( config: OcxConfig, now = Date.now(), options: { nativeMainReadsForbidden?: boolean } = {}, ): Promise<void> { if (options.nativeMainReadsForbidden) return Promise.resolve(); if (subagentQuotaPrimeBlockedByHostCircuit(config)) return Promise.resolve(); if (quotaPrimeInFlight) return quotaPrimeInFlight; if (!shouldPrimeSubagentQuota(config, now)) return Promise.resolve(); quotaPrimeInFlight = (async () => { try { // Re-check after claiming single-flight ownership so a circuit opened by // a concurrent request cannot race us into a fresh usage-probe pass. if (subagentQuotaPrimeBlockedByHostCircuit(config)) return; if (subagentQuotaPrimeForTests) { await subagentQuotaPrimeForTests(config, "subagent-spawn"); } else { const { primeCodexPoolQuotas } = await import("./auth-api/pool-mode-gate"); await primeCodexPoolQuotas(config, "subagent-spawn"); } quotaPrimedAt.set("global", Date.now()); } catch { // Owning boundary: do not fail the spawn path when priming is unavailable. // Leave quotaPrimedAt untouched so a later spawn can retry. } finally { quotaPrimeInFlight = null; } })(); return quotaPrimeInFlight; } export function recordSubagentQuotaFailureForThreadSpawn( headers: Headers, model: string, message: string | number, config: OcxConfig, accountId?: string | null, now = Date.now(), ): void { if (!isThreadSpawnRequest(headers)) return; noteSubagentModelFailure(model, String(message), config, accountId, now, pollIntervalMs(config)); } export function applySubagentModelFallback( parsed: OcxParsedRequest, headers: Headers, config: OcxConfig, accountId?: string | null, now = Date.now(), nativeFallbackOnly = false, accountUsabilityOptions?: CodexAccountUsabilityOptions, poolAccountPreview?: SubagentPoolAccountPreview, modelEligibleAccountIdsForModel?: SubagentModelEligibleAccountIds, resolvedFallbackChain?: readonly string[] | null, restrictedRouteEligible?: SubagentFallbackRouteEligibility, admission?: FallbackAdmission, ): { from?: string; to?: string; skipped?: string[]; refusal?: Response } | null { if (!isThreadSpawnRequest(headers)) return null; const fallbackChain = resolvedFallbackChain === undefined ? resolveSubagentFallbackChain(parsed, config) : resolvedFallbackChain; if (!fallbackChain) return null; const selection = selectAvailableSubagentModel( parsed.modelId, config, [], accountId, now, nativeFallbackOnly, accountUsabilityOptions, [], poolAccountPreview, modelEligibleAccountIdsForModel, fallbackChain, restrictedRouteEligible, ); if (!selection.rewritten) return selection.skipped.length > 0 ? { from: parsed.modelId, to: parsed.modelId, skipped: selection.skipped } : null; const from = parsed.modelId; // OCX-11: the rewrite is a proactive hop away from an unavailable primary. Refused, the spawn // keeps its model and the caller answers with the refusal instead of sending anything. const hop = guardFallbackHop(config, { site: "subagent", route: from, from: fallbackTargetOf(config, from), to: fallbackTargetOf(config, selection.model), trigger: "unavailable", admission, now, }); if (!hop.ok) return { from, to: from, skipped: selection.skipped, refusal: hop.response }; // The rewrite is this site's admission: the spawn now carries the fallback model. hop.commit(); rewriteParsedModel(parsed, selection.model); return { from, to: selection.model, skipped: selection.skipped }; } function fallbackTargetOf(config: OcxConfig, model: string): { provider: string; model: string } { const route = tryRouteFallbackModel(config, model); if (route) return { provider: route.providerName, model: route.modelId }; const slash = model.indexOf("/"); return slash > 0 ? { provider: model.slice(0, slash), model: model.slice(slash + 1) } : { provider: "", model }; } /** Resolve the effective fallback chain once for one logical spawn request. */ export function resolveSubagentFallbackChain( parsed: OcxParsedRequest, config: OcxConfig, ): readonly string[] | null { const tomlRoleFallback = resolveAgentModelFallbackForPrimary( parsed.modelId, getCodexHome(), config.codexAccountNamespaces, ); // Config-keyed chains are the supported per-role home (#1190); TOML `model_fallback` // stays readable for backwards compatibility with homes written before Codex 0.146. const configuredFallback = resolveConfiguredModelFallbackForPrimary(parsed.modelId, config); const globalFallback = config.subagentModelFallback ?? []; if (globalFallback.length === 0 && configuredFallback.length === 0 && tomlRoleFallback.length === 0) return null; return normalizedChain(parsed.modelId, config, configuredFallback, tomlRoleFallback); } /** Whether the effective fallback chain crosses an account-gated native Pool model. */ export function subagentFallbackNeedsModelEntitlements( fallbackChain: readonly string[] | null, config: OcxConfig, ): boolean { return fallbackChain?.some((candidate) => { const route = tryRouteFallbackModel(config, candidate); return !!route && isPoolCodexRoute(route) && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(route.modelId); }) === true; } export function subagentFallbackGuidanceText(config: OcxConfig): string { const chain = config.subagentModelFallback ?? []; if (chain.length === 0) return ""; const quoted = chain.map(model => `"${model}"`).join(", "); return ` Subagent model fallback chain (priority order): ${quoted}. When the primary model is quota-exhausted, opencodex rewrites thread_spawn requests to the next available model automatically.`; } const TOML_MODEL_FALLBACK_KEY = /^\s*(?:model_fallback|"model_fallback"|'model_fallback')\s*=/; type TomlModelFallbackField = { present: false; value: null } | { present: true; value: string[] | null }; type TomlScanState = { inMultilineString: '"""' | "'''" | null; arrayDepth: number; }; /** Track TOML strings, comments, and array brackets on one line. */ function scanTomlLine(line: string, state: TomlScanState): void { let i = 0; while (i < line.length) { const ch = line[i]!; if (ch === "#") return; if (ch === '"' || ch === "'") { const delimiter = ch.repeat(3); if (line.startsWith(delimiter, i)) { const end = findTomlMultilineStringEnd(line, i + 3, ch); if (end === -1) { state.inMultilineString = delimiter as '"""' | "'''"; return; } i = end + 3; continue; } i++; while (i < line.length) { if (ch === '"' && line[i] === "\\") { i += 2; continue; } if (line[i] === ch) break; i++; } i++; continue; } if (ch === "[") state.arrayDepth++; else if (ch === "]") state.arrayDepth = Math.max(0, state.arrayDepth - 1); i++; } } /** Parse a TOML string starting at `start`; returns the decoded value and end offset. */ function parseTomlStringAt(text: string, start: number): { value: string; end: number } | null { const quote = text[start]!; const delimiter = quote.repeat(3); if (text.startsWith(delimiter, start)) { const end = findTomlMultilineStringEnd(text, start + 3, quote); if (end === -1) return null; let value = text.slice(start + 3, end).trim(); if (quote === '"') value = value.replace(/\\"/g, '"').replace(/\\\\/g, "\\"); return { value, end: end + 3 }; } let i = start + 1; let value = ""; while (i < text.length) { const ch = text[i]!; if (quote === '"' && ch === "\\") { const next = text[i + 1]; if (next === '"' || next === "\\") { value += next; i += 2; continue; } } if (ch === quote) return { value, end: i + 1 }; value += ch; i++; } return null; } function findTomlMultilineStringEnd(text: string, from: number, quote: string): number { const delimiter = quote.repeat(3); let index = text.indexOf(delimiter, from); while (index !== -1) { let backslashes = 0; if (quote === '"') for (let j = index - 1; j >= 0 && text[j] === "\\"; j--) backslashes += 1; if (backslashes % 2 === 0) { // TOML lets one or two quotes sit right before the closing delimiter, so """a""""" ends on its last three. let extra = 0; while (extra < 2 && text[index + 3 + extra] === quote) extra += 1; return index + extra; } index = text.indexOf(delimiter, index + 1); } return -1; } /** After an array close, only horizontal whitespace, an inline comment, or the line end is valid. */ function isValidTomlArrayTail(text: string, from: number): boolean { let i = from; while (i < text.length && (text[i] === " " || text[i] === "\t")) i += 1; if (i >= text.length || text[i] === "\n" || text[i] === "\r") return true; if (text[i] === "#") { while (i < text.length && text[i] !== "\n") i += 1; return true; } return false; } /** Parse a TOML string-array value; null when the value is not a well-formed array of strings. */ function parseTomlStringArrayValue(text: string): string[] | null { const values: string[] = []; let i = 0; const skipIgnored = () => { while (i < text.length) { const ch = text[i]!; if (ch === "#") { while (i < text.length && text[i] !== "\n") i += 1; continue; } if (/\s/.test(ch)) { i += 1; continue; } break; } }; skipIgnored(); if (text[i] !== "[") return null; i += 1; let expectValue = true; for (;;) { skipIgnored(); if (i >= text.length) return null; const ch = text[i]!; if (ch === "]") { if (!isValidTomlArrayTail(text, i + 1)) return null; return values; } if (ch === ",") { if (expectValue) return null; // leading or doubled comma expectValue = true; i += 1; continue; } if (ch === '"' || ch === "'") { if (!expectValue) return null; // adjacent strings must be comma-separated const parsed = parseTomlStringAt(text, i); if (!parsed) return null; values.push(parsed.value); i = parsed.end; expectValue = false; continue; } return null; } } /** * TOML-aware, presence-aware parse of the `model_fallback` field. Quoted keys * are recognized, and text inside strings (including multiline strings) is * never treated as a key. `present` is true whenever the key exists, even when * the value is not a readable string array; `value` is null in that case. */ function parseTomlModelFallbackField(content: string): TomlModelFallbackField { const lines = content.split(/\r?\n/); const state: TomlScanState = { inMultilineString: null, arrayDepth: 0 }; for (let i = 0; i < lines.length; i += 1) { const line = lines[i]!; if (state.inMultilineString) { const end = findTomlMultilineStringEnd(line, 0, state.inMultilineString[0]!); if (end === -1) continue; state.inMultilineString = null; scanTomlLine(line.slice(end + 3), state); continue; } if (state.arrayDepth === 0) { const key = line.match(TOML_MODEL_FALLBACK_KEY); if (key) { const rest = `${line.slice(key[0].length)}\n${lines.slice(i + 1).join("\n")}`; return { present: true, value: parseTomlStringArrayValue(rest) }; } } scanTomlLine(line, state); } return { present: false, value: null }; } export function readAgentModelFallback(filePath: string): string[] | null { try { const content = readFileSync(filePath, "utf8"); const parsed = parseTomlModelFallbackField(content); return parsed.present ? parsed.value : null; } catch { return null; } } export function readCodexAgentModelFallback(role: string, codexHome = CODEX_HOME): string[] { const file = join(codexHome, "agents", `${role}.toml`); if (!existsSync(file)) return []; return readAgentModelFallback(file) ?? []; } /** * True when the role TOML carries a `model_fallback` key, even an empty array. * Presence is what matters for the doctor scan: Codex >= 0.146 rejects the * field as unknown and skips the whole role regardless of its value. Uses the * same TOML-aware parse as the fallback-reading path, so quoted keys count and * text inside string literals does not. */ export function hasCodexAgentModelFallbackField(role: string, codexHome = CODEX_HOME): boolean { const file = join(codexHome, "agents", `${role}.toml`); if (!existsSync(file)) return false; try { const content = readFileSync(file, "utf8"); return parseTomlModelFallbackField(content).present; } catch { return false; } } /** Roles whose TOML still carries `model_fallback`, including empty arrays. */ export function scanCodexAgentRolesWithTomlModelFallback( codexHome = CODEX_HOME, onListError?: (cause: unknown) => void, ): string[] { try { return listCodexAgentRoles(codexHome).filter(role => hasCodexAgentModelFallbackField(role, codexHome)); } catch (cause) { onListError?.(cause); return []; } } const TOML_ROOT_KEY = /^\s*(?:([A-Za-z0-9_-]+)|("(?:\\.|[^"\\])*")|'([^'\n]*)')\s*=/; const TOML_TABLE_HEADER = /^\s*\[/; function tomlKeyName(match: RegExpMatchArray): string | undefined { if (match[1] !== undefined) return match[1]; if (match[3] !== undefined) return match[3]; return decodeTomlBasicString(match[2]!) ?? undefined; } export interface TomlModelKeyLocation { /** Index into `content.split("\n")`; a trailing `\r` stays on the line. */ readonly line: number; readonly inRootTable: boolean; /** Column span of the quoted value on `line`; null when it is not a one-line string. */ readonly span: { readonly start: number; readonly end: number } | null; readonly value: string | null; } /** * Locate the first `model` key outside multiline strings and arrays. * * The one scan behind both the read ({@link parseTomlModelPin}) and the dashboard's write of a * role's model, so the line the writer edits is the line the reader reports. */ export function locateTomlModelKey(content: string): TomlModelKeyLocation | null { return locateTomlStringKey(content, "model"); } /** The same scan for a role's root model_reasoning_effort, which the dashboard edits beside the pin. */ export function locateTomlReasoningEffortKey(content: string): TomlModelKeyLocation | null { return locateTomlStringKey(content, "model_reasoning_effort"); } function locateTomlStringKey(content: string, keyName: string): TomlModelKeyLocation | null { const lines = content.split(/\r?\n/); const state: TomlScanState = { inMultilineString: null, arrayDepth: 0 }; let inRootTable = true; let undecodedRootKeyLine: number | null = null; for (let i = 0; i < lines.length; i += 1) { const line = lines[i]!; if (state.inMultilineString) { const end = findTomlMultilineStringEnd(line, 0, state.inMultilineString[0]!); if (end === -1) continue; state.inMultilineString = null; scanTomlLine(line.slice(end + 3), state); continue; } if (state.arrayDepth === 0) { if (TOML_TABLE_HEADER.test(line)) inRootTable = false; const key = line.match(TOML_ROOT_KEY); const name = key ? tomlKeyName(key) : null; if (key && name === undefined && inRootTable) undecodedRootKeyLine ??= i; if (key && name === keyName) { const rest = `${line.slice(key[0].length)}\n${lines.slice(i + 1).join("\n")}`; let at = 0; while (at < rest.length && (rest[at] === " " || rest[at] === "\t")) at += 1; if (rest[at] !== '"' && rest[at] !== "'") return { line: i, inRootTable, span: null, value: null }; const parsed = parseTomlStringAt(rest, at); const value = parsed?.value.trim() ?? ""; const onLine = parsed !== null && parsed.end <= line.length - key[0].length; return { line: i, inRootTable, span: onLine ? { start: key[0].length + at, end: key[0].length + parsed.end } : null, value: value === "" ? null : value, }; } } scanTomlLine(line, state); } // A root key that might spell the wanted key cannot be ruled out, so a writer must not add a second one. return undecodedRootKeyLine === null ? null : { line: undecodedRootKeyLine, inRootTable: true, span: null, value: null }; } /** * TOML-aware read of the root `model` pin, or null when there is none. * * Distinct from {@link readCodexAgentModel}, which matches one exact unindented double-quoted * line. That is fine for resolving a fallback chain opencodex itself wrote, but it is the wrong * question for a diagnostic: the file being judged was written by somebody else, so `model = 'x'`, * an indented key, or a trailing comment are all valid TOML that Codex honours and that a * stricter matcher would report as unpinned. * * It shares the scanner used for `model_fallback` for the reason that matters here: an imported * role file keeps its instructions in a multiline string, and that string contains the very words * this scan looks for. A line matcher would read a key out of prose. * * The scan reports whether the key sits in the root table, and this read ignores that flag on * purpose: a `model` key under a later table header still counts as a pin, because for a warning * the conservative direction is to stay quiet. The role listing and the writer in * `src/codex/agent-role-models.ts` do gate on it, since they show and edit only the root value. */ function parseTomlModelPin(content: string): string | null { return locateTomlModelKey(content)?.value ?? null; } /** Filename prefix opencodex gives the Claude agents it generates. */ const OPENCODEX_DERIVED_ROLE_PREFIX = "ocx-"; /** * Body markers that survive the Codex desktop external-agent import. * * The import carries the generated Claude agent's instructions across, so both the provenance * marker and the routing directive end up inside the role TOML. `ocx-route:` is matched without * its `<!--` comment prefix on purpose: the same import text-replaces "Claude Code" with "Codex" * inside that body, so anything around the directive should be assumed rewritten. */ const OPENCODEX_DERIVED_ROLE_MARKERS = ["generated-by: opencodex", "ocx-route:"] as const; /** * Roles that look opencodex-derived but pin no model, so Codex runs them on the parent model. * * opencodex does not create, repair, or remove Codex role TOMLs. Its one write into them is the * root `model` value, and only when a user picks a model for that role in the dashboard or with * `ocx agent roles set` (`src/codex/agent-role-models.ts`). These arrive when the Codex desktop external-agent * import converts `~/.claude/agents/ocx-*.md` into `$CODEX_HOME/agents/ocx-*.toml`, dropping the * `model:` frontmatter because a `claude-ocx-native--` id is not a Codex model and keeping only the * instructions. The surviving `ocx-route` directive cannot make up the difference: it is honoured * only on the Claude `/v1/messages` path and is inert on `/v1/responses`. So the role file names * one model while every spawn runs on another, which is invisible until someone diffs * `session_meta.agent_role` against `turn_context.model` (#4790). * * Detection is a heuristic for a warning, deliberately not an ownership claim. Nothing here * authorizes writing to, repairing, or removing these files, and the marker-based ownership rules * that govern the files opencodex does write are unchanged. */ export function scanOpencodexDerivedCodexAgentRolesWithoutModelPin( codexHome = CODEX_HOME, onListError?: (cause: unknown) => void, ): string[] { const findings: string[] = []; let roles: string[]; try { roles = listCodexAgentRoles(codexHome); } catch (cause) { onListError?.(cause); return []; } for (const role of roles) { let content: string; try { content = readFileSync(join(codexHome, "agents", `${role}.toml`), "utf8"); } catch { // An unreadable file is not evidence of a missing pin. continue; } const derived = role.startsWith(OPENCODEX_DERIVED_ROLE_PREFIX) || OPENCODEX_DERIVED_ROLE_MARKERS.some(marker => content.includes(marker)); if (!derived) continue; if (parseTomlModelPin(content) !== null) continue; findings.push(role); } return findings.sort(); } export function listCodexAgentRoles(codexHome = CODEX_HOME): string[] { const dir = join(codexHome, "agents"); if (!existsSync(dir)) return []; return readdirSync(dir) .filter(name => name.endsWith(".toml")) .map(name => name.slice(0, -".toml".length)); } /** True when a new quota prime should start (no success within the poll interval). */ export function shouldPrimeSubagentQuota(config: OcxConfig, now = Date.now()): boolean { const last = quotaPrimedAt.get("global") ?? 0; return now - last >= pollIntervalMs(config); }