UNPKG

@bitkyc08/opencodex

Version:

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

950 lines (904 loc) • 41.8 kB
import { getEffectiveCodexAutoSwitchThreshold } from "../account-auto-switch"; import { codexAccountUsesCreditsAfterLimit, isCodexAccountHeldForCredits } from "../account-credit-use"; import { isCodexAccountPaused } from "../account-pause"; import { pinnedCodexAccountId } from "../account-priority"; import { codexSelectionPriorityLookup } from "../account-preservation"; import { isSelectableCodexPoolAccount } from "../account-id"; import { isAccountNeedsReauth } from "../account-runtime-state"; import { isCodexAccountUsable, type CodexAccountUsabilityOptions } from "../account-usability"; import { isCodexPoolRefreshCooling } from "../pool-refresh-backoff"; import { normalizeAccountPoolStickyLimit, normalizeCodexAccountPoolStrategy, notePoolRotationSuccess, peekRoundRobinAccount, pickRoundRobinAccount, selectPriorityTier, } from "../pool-rotation"; import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota, resetAtToMs } from "../quota"; import { codexPlanKey } from "../plan"; import { MAIN_CODEX_ACCOUNT_ID, getMainAccountPlan } from "../main-account"; import type { OcxConfig } from "../../types"; import { CODEX_FAILURE_WINDOW_MS, computeCodexUsageScore } from "./cooldown-math"; import { failureWindowSteersNewThreads } from "./failure-window"; import { codexPoolKeyForScope, dropSpentCredentialFailure, getAccountHealth, getCodexQuotaHealthSnapshot, hasUnrecoveredCodexQuotaRefusal, isCodexAccountSoftAvoided, isCodexQuotaAvoided, isIndependentCodexQuotaScope, type CodexQuotaScope, } from "./health-store"; import { bindThreadAffinity, type CodexAffinityReason } from "./thread-affinity"; import { resetNearWeightOf } from "../../routing/machine-weighted-routing"; import { codexQuotaUsageObservedAt } from "../quota-observation-freshness"; import { getEffectiveActiveCodexAccountId, manualPreferenceBlocks, promoteActiveCodexAccount, rememberActiveCodexAccount, setActiveCodexAccount, unspentManualPreference, } from "./active-account"; /** * Plan keys the operator excluded from automatic rotation. Absent or empty means no policy, so an * existing install rotates exactly as before. Compared with `codexPlanKey` because the stored plan * is an unrestricted provider string whose casing this repository does not control. */ function excludedCodexPoolPlanKeys(config: OcxConfig): ReadonlySet<string> | undefined { const configured = config.codexPool?.excludedPlans; if (!configured?.length) return undefined; const keys = configured .map(plan => codexPlanKey(plan)) .filter((key): key is string => key !== undefined); return keys.length > 0 ? new Set(keys) : undefined; } /** * Whether the operator's plan policy removes this account from automatic selection. * * Modelled on pause rather than usability: an excluded account keeps its credential, quota history, * and affinity, stays visible on the account surface, and is still reachable by explicit account * selection. Only automatic rotation skips it, which is the distinction #4211 asked for. * * It is checked in the same two places pause is checked, and that is not redundancy. The eligible * list is consulted only when routing picks a NEW account; an already-active or already-affined * account is served straight from {@link isCodexAccountSelectable}. A lapsed subscription leaves * behind exactly that account, so a policy that filtered only the eligible list would miss the case * it exists for. * * `__main__` is exempt. {@link getPoolAccountPlanForSelection} withholds the main plan during a * selection-only drain so routing never reads the fenced native credential for it, so a rule that * covered main would disagree with itself between drain and ordinary routing. */ export function isCodexAccountPlanExcluded( config: OcxConfig, accountId: string, precomputed?: ReadonlySet<string>, ): boolean { if (accountId === MAIN_CODEX_ACCOUNT_ID) return false; // Callers that test a whole list pass the set once rather than rebuilding it per row. const excluded = precomputed ?? excludedCodexPoolPlanKeys(config); if (!excluded) return false; const plan = codexPlanKey(getPoolAccountPlan(config, accountId)); return plan !== undefined && excluded.has(plan); } /** * Whether the operator turned credits off for this account and one of its usage windows is full * now (#6334). Checked wherever plan exclusion is checked, for the reason given there: an account * that is already active or bound is served without passing through the eligible list. */ export function isCodexAccountHeldAtUsageLimit( config: OcxConfig, accountId: string, now: number, selectionOptions?: CodexAccountUsabilityOptions, ): boolean { return isCodexAccountHeldForCredits( config, accountId, getAccountQuota(accountId), getPoolAccountPlanForSelection(config, accountId, selectionOptions), now, ); } /** The automatic-rotation policies that also bind the legacy keep-the-active-account fallback. */ export function isCodexAccountRotationExcluded( config: OcxConfig, accountId: string, now: number, selectionOptions?: CodexAccountUsabilityOptions, ): boolean { return isCodexAccountPlanExcluded(config, accountId) || isCodexAccountHeldAtUsageLimit(config, accountId, now, selectionOptions); } export function isCodexAccountSelectable( config: OcxConfig, accountId: string, now: number, quotaScope?: CodexQuotaScope, selectionOptions?: CodexAccountUsabilityOptions, ): boolean { return !isCodexAccountPaused(config, accountId) && !isCodexAccountPlanExcluded(config, accountId) && !isCodexAccountHeldAtUsageLimit(config, accountId, now, selectionOptions) && getCodexQuotaHealthSnapshot(accountId, quotaScope, now) === null && !isCodexQuotaAvoided(accountId, quotaScope, now) && !isCodexAccountSoftAvoided(accountId, now) && !isCodexPoolRefreshCooling(accountId, now) && isCodexAccountUsable(config, accountId, selectionOptions); } /** * Which guard in {@link isCodexAccountSelectable} refused this account, if any. * * Deliberately the same predicates in the same order as that function, because the point is to * REPORT the guard that actually fired rather than to re-derive a plausible-looking cause. An * earlier version of the release reason checked only a subset and let a paused, plan-excluded, * cooled-down or quota-avoided release fall through to a quota fallback, which named something * routing never used -- a diagnostic that is confidently wrong in exactly the cases an operator * would consult it for (#4598). */ export function codexAccountBlockReason( config: OcxConfig, accountId: string, now: number, quotaScope?: CodexQuotaScope, selectionOptions?: CodexAccountUsabilityOptions, ): CodexAffinityReason | undefined { if (isCodexAccountPaused(config, accountId)) return "paused"; if (isCodexAccountPlanExcluded(config, accountId)) return "plan_excluded"; if (isCodexAccountHeldAtUsageLimit(config, accountId, now, selectionOptions)) return "credits_off"; if (getCodexQuotaHealthSnapshot(accountId, quotaScope, now) !== null) return "cooldown"; if (isCodexQuotaAvoided(accountId, quotaScope, now)) return "quota_avoided"; if (isCodexAccountSoftAvoided(accountId, now)) return "transient"; if (isCodexPoolRefreshCooling(accountId, now)) return "transient"; if (!isCodexAccountUsable(config, accountId, selectionOptions)) return "unusable"; return undefined; } /** * Drop accounts a confirmed roster says cannot serve this model, unless that leaves nothing. * * The restore-on-empty is the whole safety argument, not a defensive afterthought. Roster * evidence can be wrong in the direction that matters: a shard that has not caught up reports a * denial for a model the account genuinely owns, and #3022 is what happens when absence is * allowed to remove a model outright. Because this can only ever return a non-empty subset of a * list the caller already computed, no pool that would have found a working account can be left * without one — the worst case is the selection that ships today. * * It is an ordering rule rather than an eligibility one for the same reason. Nothing below * reports `model_not_entitled`, nothing refuses before dispatch, and the existing bounded * alternate-account retry on an exact unsupported-model 400 stays exactly where it is as the * safety net. This only stops the pool from CHOOSING an account that has already told us it * cannot serve the model (#4768). * * An operator's manual pin is never dropped. Roster evidence orders the pool's own discretion; * it does not overrule an explicit human choice, and removing the pinned account here would do * more than demote it -- `selectPriorityTier` reads the pin to lower the tier ceiling, so a pin * filtered out beforehand stops acting as a ceiling at all and silently re-enables tiers the * operator had excluded. An operator who pins an account upstream will refuse still gets the * alternate-account retry; what they do not get is the pool quietly deciding they were wrong. */ export function withoutModelDeniedAccounts( ids: readonly string[], denied: ReadonlySet<string> | undefined, pinned?: string, ): readonly string[] { if (denied === undefined || ids.length === 0) return ids; const remaining = ids.filter(id => !denied.has(id) || id === pinned); return remaining.length > 0 ? remaining : ids; } export function getEligiblePoolAccounts( config: OcxConfig, excludeId?: string, now = Date.now(), quotaScope?: CodexQuotaScope, selectionOptions?: CodexAccountUsabilityOptions, skipFailoverReadyCandidates = false, ): readonly string[] { const excludedPlans = excludedCodexPoolPlanKeys(config); const ids = (config.codexAccounts ?? []) .filter(account => isSelectableCodexPoolAccount(account) && account.id !== excludeId && !isCodexAccountPaused(config, account.id) && !isCodexAccountPlanExcluded(config, account.id, excludedPlans) && !isCodexAccountHeldAtUsageLimit(config, account.id, now, selectionOptions) && !isAccountNeedsReauth(account.id) && (!skipFailoverReadyCandidates || !shouldFailover(config, account.id, now))) .filter(account => getCodexQuotaHealthSnapshot(account.id, quotaScope, now) === null) .filter(account => !isCodexAccountSoftAvoided(account.id, now)) .filter(account => !failureWindowSteersNewThreads(config, account.id, now)) .filter(account => !isCodexQuotaAvoided(account.id, quotaScope, now)) .filter(account => !isCodexPoolRefreshCooling(account.id, now)) .filter(account => isCodexAccountUsable(config, account.id, selectionOptions)) .map(account => account.id); // The main Codex account is not stored in config.codexAccounts; include it as a // first-class rotation candidate when its read-only token is usable (Option A). if ( excludeId !== MAIN_CODEX_ACCOUNT_ID && !isCodexAccountPaused(config, MAIN_CODEX_ACCOUNT_ID) && getCodexQuotaHealthSnapshot(MAIN_CODEX_ACCOUNT_ID, quotaScope, now) === null && !isCodexAccountSoftAvoided(MAIN_CODEX_ACCOUNT_ID, now) && !failureWindowSteersNewThreads(config, MAIN_CODEX_ACCOUNT_ID, now) // The main login is not in `config.codexAccounts`, so it never passes through the // filters above and this is the only place an avoidance window can exclude it. Without // this the window a refusal announced applies to the pool but not to the account that // earned it: the cooldown caps at fifteen minutes, the window runs up to six hours, and // in between the main account returns as a first-class candidate. && !isCodexQuotaAvoided(MAIN_CODEX_ACCOUNT_ID, quotaScope, now) && !isCodexPoolRefreshCooling(MAIN_CODEX_ACCOUNT_ID, now) && !isCodexAccountHeldAtUsageLimit(config, MAIN_CODEX_ACCOUNT_ID, now, selectionOptions) && (!skipFailoverReadyCandidates || !shouldFailover(config, MAIN_CODEX_ACCOUNT_ID, now)) && isCodexAccountUsable(config, MAIN_CODEX_ACCOUNT_ID, selectionOptions) ) { ids.unshift(MAIN_CODEX_ACCOUNT_ID); } // Single choke point for selection order: every strategy, failover, and preview // reaches the pool through here, so tiering applies once rather than per picker. // Eligibility above is unchanged — this only narrows an already-eligible list. // // Model entitlement is applied BEFORE the priority tier, because a tier is a quota-ordering // question and an account that cannot serve the model at all should not be the reason a tier // is selected. Both steps narrow an already-eligible list and neither can empty it. const pinned = pinnedCodexAccountId(config); return selectPriorityTier( withoutModelDeniedAccounts(ids, selectionOptions?.deniedModelAccountIds, pinned), codexSelectionPriorityLookup(config), id => hasCodexQuotaHeadroom(config, id, selectionOptions, now), pinned, ); } function listEligibleCodexAccountIds( config: OcxConfig, now: number, quotaScope?: CodexQuotaScope, selectionOptions?: CodexAccountUsabilityOptions, ): readonly string[] { return getEligiblePoolAccounts(config, undefined, now, quotaScope, selectionOptions); } /** Shared reset timestamps are not evidence for independent model-quota groups. */ export function accountPoolStrategyForScope(config: OcxConfig, quotaScope?: CodexQuotaScope) { const strategy = normalizeCodexAccountPoolStrategy(config.accountPoolStrategy); if (!isIndependentCodexQuotaScope(quotaScope)) return strategy; if (strategy === "reset-first") return "quota"; return strategy === "reset-near-weighted" ? "round-robin" : strategy; } function codexResetNearWeightOf(eligible: readonly string[], now: number) { return resetNearWeightOf(eligible, id => { const quota = getAccountQuota(id); if (quota?.shortWindowSeconds !== 5 * 60 * 60) return null; return { weeklyPercent: quota.weeklyPercent, weeklyResetAt: quota.weeklyResetAt, weeklyObservedAt: codexQuotaUsageObservedAt(quota, "weeklyPercent"), fiveHourPercent: quota.shortPercent, fiveHourResetAt: quota.shortResetAt, fiveHourObservedAt: codexQuotaUsageObservedAt(quota, "shortPercent"), }; }, now); } function stickyLimitForConfig(config: OcxConfig): number { return normalizeAccountPoolStickyLimit(config.accountPoolStickyLimit); } /** * Whether an account still has quota to give under the auto-switch threshold. * * Fill-first and the priority tier filter share this predicate, and share both of * its escape hatches. A disabled threshold means only health, pause, and reauth * may drain an account; unknown usage is a guess, so it must neither force * fill-first off the active account nor drain a tier that was simply never * primed. A genuinely exhausted account 429s into cooldown and leaves * eligibility on its own. */ export function hasCodexQuotaHeadroom( config: OcxConfig, accountId: string, selectionOptions?: CodexAccountUsabilityOptions, now: number = Date.now(), ): boolean { const threshold = getEffectiveCodexAutoSwitchThreshold(config, accountId); if (threshold <= 0) return true; const usage = computeCodexUsageScore( getAccountQuota(accountId), getPoolAccountPlanForSelection(config, accountId, selectionOptions), now, codexAccountUsesCreditsAfterLimit(config, accountId), ); if (isUnknownUsage(usage)) return true; return usage < threshold; } /** * Where round-robin may place a NEW conversation: the eligible accounts that still have headroom * under their own threshold, or the whole eligible list when none does. * * Rotation by count alone put a fresh conversation on an account already at 95%. The conversation * binds there, and when the account runs out it has to move to another account with a cold prompt * cache. Preferring headroom at placement avoids that hop without touching anything already bound: * live bindings never reach this function, and failover ({@link pickAlternateCodexAccount}) keeps * plain ring order because leaving a failing account is not a placement. * * The score is {@link hasCodexQuotaHeadroom}, the one fill-first and the priority tier already use, * so a threshold of 0 or unknown usage counts as headroom. It is a preference, never eligibility: * when every account is at or over its threshold the ring sees the full list, exactly as before. * * An operator's unspent manual selection for this scope stays in the list whatever its usage. * Manual selection seeds the ring so the next placement lands on the chosen account, and a * preference must not overrule a person's explicit choice: dropping it here would clear that seed. * Once a dispatch on it succeeds the selection is spent and the account is treated like any other. */ function roundRobinPlacementCandidates( config: OcxConfig, eligible: readonly string[], now: number, quotaScope?: CodexQuotaScope, selectionOptions?: CodexAccountUsabilityOptions, ): readonly string[] { const operatorChoice = unspentManualPreference(codexPoolKeyForScope(quotaScope)); const withHeadroom = eligible.filter(id => id === operatorChoice || hasCodexQuotaHeadroom(config, id, selectionOptions, now)); return withHeadroom.length > 0 ? withHeadroom : eligible; } /** * Is a live binding held for its prompt cache? * * Unset means yes. Cache affinity shipped as an opt-in flag (#4292) and then #4546 measured * what the default costs: a pool whose accounts all sit in the 80-99% band hands a bound * conversation from account to account, and because provider prompt caches are account-isolated * every hop re-sends the entire prefix. An install that has never heard of this flag is exactly * the install that gets hurt by it, so the protection cannot be something you have to find. * * `false` restores capacity-first routing byte-for-byte. It is a real choice -- a pinned thread * on a busy account pays latency -- and it stays available; it is just no longer the default. */ export function isCacheAffinityEnabled(config: OcxConfig): boolean { return config.pool?.cacheAffinity !== false; } /** * Whether quota may retire shared state while cache affinity is active. * * A threshold crossing is a hint that an account is getting busy, not evidence it cannot * serve — the same bar {@link mayRebindAffinityForQuota} applies to a live binding. Shared * state held across a model detour gets that exhaustion boundary for the same reason: the * detour is request-scoped, so retiring the binding over a hint pays a cold prefix for * nothing. New/unbound selection still reads {@link hasCodexQuotaHeadroom}; only * preservation of an existing shared selection or thread binding qualifies here. Like the * live-binding rule, the configured threshold plays no role once retention applies: a * genuinely exhausted (>=100%) account releases even with threshold switching disabled, * while the fallback above keeps a disabled threshold's "never drained on quota alone". */ export function hasCodexSharedStateQuotaHeadroom( config: OcxConfig, accountId: string, quotaScope: CodexQuotaScope | undefined, selectionOptions?: CodexAccountUsabilityOptions, now: number = Date.now(), ): boolean { if ( !isCacheAffinityEnabled(config) || accountPoolStrategyForScope(config, quotaScope) !== "quota" ) { return hasCodexQuotaHeadroom(config, accountId, selectionOptions, now); } const usage = computeCodexUsageScore( getAccountQuota(accountId), getPoolAccountPlanForSelection(config, accountId, selectionOptions), now, codexAccountUsesCreditsAfterLimit(config, accountId), ); return isUnknownUsage(usage) || usage < 100; } /** Earliest future shared short/weekly reset; missing evidence and ties use usage order. */ export function pickResetFirstCodexAccount( config: OcxConfig, ids: readonly string[], now: number, selectionOptions?: CodexAccountUsabilityOptions, ): string | null { const available = ids.filter(id => hasCodexQuotaHeadroom(config, id, selectionOptions, now)); if (available.length === 0) return pickLowestUsageAmong(config, ids, selectionOptions, now); let earliest = Number.POSITIVE_INFINITY; let candidates: string[] = []; for (const id of available) { const quota = getAccountQuota(id); const resets = [quota?.shortResetAt, quota?.weeklyResetAt] .filter((reset): reset is number => typeof reset === "number" && Number.isFinite(reset)) .map(resetAtToMs) .filter(reset => reset > now); const next = Math.min(...resets); if (next < earliest) { earliest = next; candidates = [id]; } else if (next === earliest) candidates.push(id); } return pickLowestUsageAmong(config, candidates, selectionOptions, now); } /** * Fill-first: keep selectable active under threshold; otherwise advance to the next * eligible id in stable sorted order after the current active (wrapping). */ function pickFillFirstCodexAccount( config: OcxConfig, now: number, quotaScope?: CodexQuotaScope, selectionOptions?: CodexAccountUsabilityOptions, ): string | null { const eligible = listEligibleCodexAccountIds(config, now, quotaScope, selectionOptions); if (eligible.length === 0) return null; const active = getEffectiveActiveCodexAccountId(config); if (active && eligible.includes(active) && hasCodexQuotaHeadroom(config, active, selectionOptions, now)) { return active; } return pickNextFillFirstCodexAccount(config, active ?? null, eligible, now, selectionOptions); } /** Next eligible account in stable order after `afterId` (wrapping). */ function pickNextFillFirstCodexAccount( config: OcxConfig, afterId: string | null, eligible: readonly string[] = listEligibleCodexAccountIds(config, Date.now()), now = Date.now(), selectionOptions?: CodexAccountUsabilityOptions, ): string | null { if (eligible.length === 0) return null; const ordered = [...eligible].sort((a, b) => a.localeCompare(b)); if (!afterId) { // Prefer an under-threshold account when starting with no active cursor. for (const id of ordered) { if (hasCodexQuotaHeadroom(config, id, selectionOptions, now)) return id; } return ordered[0] ?? null; } const allConfigured = [ ...(isCodexAccountUsable(config, MAIN_CODEX_ACCOUNT_ID, selectionOptions) || afterId === MAIN_CODEX_ACCOUNT_ID ? [MAIN_CODEX_ACCOUNT_ID] : []), ...(config.codexAccounts ?? []).filter(account => !account.isMain).map(account => account.id), ]; const stableAll = [...new Set(allConfigured)].sort((a, b) => a.localeCompare(b)); const startIdx = stableAll.indexOf(afterId); if (startIdx < 0) { for (const id of ordered) { if (hasCodexQuotaHeadroom(config, id, selectionOptions, now)) return id; } return ordered[0] ?? null; } // Skip successors that are also at/above threshold (known drained usage). let fallback: string | null = null; for (let step = 1; step <= stableAll.length; step++) { const candidate = stableAll[(startIdx + step) % stableAll.length]!; if (!eligible.includes(candidate)) continue; if (!fallback) fallback = candidate; if (hasCodexQuotaHeadroom(config, candidate, selectionOptions, now)) return candidate; } return fallback ?? ordered[0] ?? null; } /** * Unbound new-session pick for round-robin / fill-first. Returns null to fall through * to the legacy quota path (or when the strategy is quota). * * When `commit` is true (resolve path), advances RR state. `commitSharedActive` * and `commitAffinity` independently control the two cross-request side effects: * model-scoped entitlement selection can bind a new task without replacing an * existing task binding or global active choice. Preview remains a dry-run peek. * * Automatic strategy picks never sync-write config; only manual selection persists active. * * Known limitation (follow-up): when a subagent preview peeks an RR account and the request * then falls back to a non-Codex provider, the ring is not reserved/committed. Prefer seeding * the peeked account if that path becomes load-bearing. */ export function pickUnboundStrategyAccount( config: OcxConfig, threadId: string | null, now: number, commit: boolean, quotaScope?: CodexQuotaScope, selectionOptions?: CodexAccountUsabilityOptions, commitSharedActive = commit, commitAffinity = commit, ): string | null { const strategy = accountPoolStrategyForScope(config, quotaScope); if (strategy === "quota") return null; const poolKey = codexPoolKeyForScope(quotaScope); let picked: string | null = null; const resetNearWeighted = strategy === "reset-near-weighted"; if (strategy === "round-robin" || resetNearWeighted) { const eligible = roundRobinPlacementCandidates( config, listEligibleCodexAccountIds(config, now, quotaScope, selectionOptions), now, quotaScope, selectionOptions, ); const weightOf = resetNearWeighted ? codexResetNearWeightOf(eligible, now) : undefined; const limit = stickyLimitForConfig(config); if (!commit) { return peekRoundRobinAccount(poolKey, eligible, limit, weightOf); } picked = pickRoundRobinAccount(poolKey, eligible, limit, weightOf); if (!picked) return null; if (commitSharedActive && sharesActiveSelection(picked, selectionOptions)) { if (!isIndependentCodexQuotaScope(quotaScope) && !manualPreferenceBlocks(codexPoolKeyForScope(quotaScope), picked)) { rememberActiveCodexAccount(config, picked); } } if (commitAffinity && threadId) bindThreadAffinity(threadId, picked, now, quotaScope); notePoolRotationSuccess(poolKey, picked, limit); return picked; } if (strategy === "fill-first" || strategy === "reset-first") { picked = strategy === "reset-first" ? pickResetFirstCodexAccount(config, listEligibleCodexAccountIds(config, now, quotaScope, selectionOptions), now, selectionOptions) : pickFillFirstCodexAccount(config, now, quotaScope, selectionOptions); if (!picked) return null; if (commitSharedActive && sharesActiveSelection(picked, selectionOptions)) { if (!isIndependentCodexQuotaScope(quotaScope) && !manualPreferenceBlocks(codexPoolKeyForScope(quotaScope), picked)) { rememberActiveCodexAccount(config, picked); } } if (commitAffinity && threadId) bindThreadAffinity(threadId, picked, now, quotaScope); return picked; } return null; } export function getPoolAccountPlan(config: OcxConfig, accountId: string): string | undefined { if (accountId === MAIN_CODEX_ACCOUNT_ID) return getMainAccountPlan(); return (config.codexAccounts ?? []) .find(account => isSelectableCodexPoolAccount(account) && account.id === accountId)?.plan; } /** * Selection-only main routing must not lazily read the fenced native credential for its plan, and * neither may a request whose main candidacy comes from its own bearer (#5019): that request is * forbidden to read the physical main credential, so main is ranked without a plan. */ export function getPoolAccountPlanForSelection( config: OcxConfig, accountId: string, selectionOptions?: CodexAccountUsabilityOptions, ): string | undefined { if ( accountId === MAIN_CODEX_ACCOUNT_ID && (selectionOptions?.nativeMainSelectionOnly === true || selectionOptions?.requestOwnedMainCredential === true) ) { return undefined; } return getPoolAccountPlan(config, accountId); } /** Shared routing state must ignore a request-scoped entitlement roster. */ export function sharedStateSelectionOptions( selectionOptions?: CodexAccountUsabilityOptions, ): Pick< CodexAccountUsabilityOptions, "nativeMainSelectionOnly" | "isMainAccountTokenLive" | "requestOwnedMainCredential" > | undefined { if (!selectionOptions) return undefined; return { ...(selectionOptions.nativeMainSelectionOnly !== undefined ? { nativeMainSelectionOnly: selectionOptions.nativeMainSelectionOnly } : {}), ...(selectionOptions.isMainAccountTokenLive ? { isMainAccountTokenLive: selectionOptions.isMainAccountTokenLive } : {}), ...(selectionOptions.requestOwnedMainCredential !== undefined ? { requestOwnedMainCredential: selectionOptions.requestOwnedMainCredential } : {}), }; } /** * A main that is live only through this request's own credential serves this request alone. * Recording it as the shared active account would route later requests through a credential * they do not carry (see CodexAccountUsabilityOptions.requestOwnedMainCredential). */ export function sharesActiveSelection( accountId: string, selectionOptions?: CodexAccountUsabilityOptions, ): boolean { return !(accountId === MAIN_CODEX_ACCOUNT_ID && selectionOptions?.requestOwnedMainCredential === true); } export function pickLowerUsageAccount( config: OcxConfig, active: string, activeUsage: number, now: number, quotaScope?: CodexQuotaScope, selectionOptions?: CodexAccountUsabilityOptions, skipFailoverReadyCandidates = false, ): string { let best = active; let bestUsage = activeUsage; for (const id of getEligiblePoolAccounts( config, active, now, quotaScope, selectionOptions, skipFailoverReadyCandidates, )) { const usage = computeCodexUsageScore( getAccountQuota(id), getPoolAccountPlanForSelection(config, id, selectionOptions), now, codexAccountUsesCreditsAfterLimit(config, id), ); if (usage < bestUsage) { best = id; bestUsage = usage; } } return best; } /** Coolest account in an already-selected candidate list; first index wins ties. */ export function pickLowestUsageAmong( config: OcxConfig, ids: readonly string[], selectionOptions?: CodexAccountUsabilityOptions, now: number = Date.now(), ): string | null { let best: string | null = null; let bestUsage = Number.POSITIVE_INFINITY; for (const id of ids) { const usage = computeCodexUsageScore( getAccountQuota(id), getPoolAccountPlanForSelection(config, id, selectionOptions), now, codexAccountUsesCreditsAfterLimit(config, id), ); if (usage < bestUsage) { best = id; bestUsage = usage; } } return best; } export function pickLowestUsageCodexAccount( config: OcxConfig, excludeId?: string, now = Date.now(), quotaScope?: CodexQuotaScope, selectionOptions?: CodexAccountUsabilityOptions, ): string | null { return pickLowestUsageAmong( config, getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions), selectionOptions, now, ); } /** * Strategy-aware alternate after a cooled/excluded account (same-request 429 retry * and active promotion). Quota keeps lowest-usage; fill-first advances stable order; * round-robin takes the next ring pick (caller should have noted the failure). */ export function pickAlternateCodexAccount( config: OcxConfig, excludeId: string, now = Date.now(), quotaScope?: CodexQuotaScope, selectionOptions?: CodexAccountUsabilityOptions, ): string | null { const strategy = accountPoolStrategyForScope(config, quotaScope); // The exclusion is passed into eligibility rather than post-filtered off its // result: when the excluded account is the only healthy member of the top // tier, the tier walk must be free to descend instead of selecting that tier // and then handing back an empty list. if (strategy === "round-robin" || strategy === "reset-near-weighted") { const eligible = getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions); const weightOf = strategy === "reset-near-weighted" ? codexResetNearWeightOf(eligible, now) : undefined; return pickRoundRobinAccount(codexPoolKeyForScope(quotaScope), eligible, stickyLimitForConfig(config), weightOf); } if (strategy === "fill-first") { const eligible = getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions); return pickNextFillFirstCodexAccount(config, excludeId, eligible, now, selectionOptions); } if (strategy === "reset-first") { return pickResetFirstCodexAccount(config, getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions), now, selectionOptions); } return pickLowestUsageCodexAccount(config, excludeId, now, quotaScope, selectionOptions); } /** * The account {@link pickAlternateCodexAccount} WOULD return, without returning it. * * Only the round-robin branch has a side effect -- `pickRoundRobinAccount` commits the pick and * advances the ring -- so every other strategy delegates rather than growing a second copy of * the selection rule that could drift from it. * * This exists because preview and resolve have to agree on the FIRST transient detour, not just * on later ones. Preview feeds subagent model-availability scoring, so a preview that reported * the bound account while resolve was about to serve from a cool sibling could retire a model * over usage the request would never have touched. */ export function peekAlternateCodexAccount( config: OcxConfig, excludeId: string, now: number, quotaScope?: CodexQuotaScope, selectionOptions?: CodexAccountUsabilityOptions, ): string | null { const strategy = accountPoolStrategyForScope(config, quotaScope); if (strategy === "round-robin" || strategy === "reset-near-weighted") { const eligible = getEligiblePoolAccounts(config, excludeId, now, quotaScope, selectionOptions); const weightOf = strategy === "reset-near-weighted" ? codexResetNearWeightOf(eligible, now) : undefined; return peekRoundRobinAccount(codexPoolKeyForScope(quotaScope), eligible, stickyLimitForConfig(config), weightOf); } return pickAlternateCodexAccount(config, excludeId, now, quotaScope, selectionOptions); } export function isUnknownUsage(usage: number): boolean { return usage >= CODEX_UNKNOWN_USAGE_SCORE; } /** * Correct a shared cursor that names an account this model's own roster denies (#4768). * * {@link getEligiblePoolAccounts} is not the only door into selection. An account that is already * ACTIVE is served straight from {@link isCodexAccountSelectable} and never passes through the * eligible list, so ordering that list alone left the exact case the issue reports: once the Free * account becomes the cursor, every Sol/Astra request keeps going to it and keeps taking the * upstream unsupported-model 400. {@link pickPriorityPreemption} does not cover it either -- it * refuses to move toward a tier that does not strictly outrank the active one, which is the usual * shape here. * * Three properties keep this inside "order the already-eligible set" rather than widening it. * It admits nothing: the replacement comes from {@link getEligiblePoolAccounts}, so every * eligibility guard has already passed on it. It cannot fail: with no entitled alternative the * active account is returned unchanged, so this can never turn a served request into `none`. * And it changes nothing without evidence: absent `deniedModelAccountIds`, or an active account * nobody denied, it is the identity function. * * The caller must NOT persist the result. This is one request's correction for one model, in the * same spirit as a model detour; the operator's cursor is theirs. A pinned active account is * exempt outright, for the reason {@link withoutModelDeniedAccounts} gives. */ export function preferModelEntitledAccount( config: OcxConfig, active: string, now: number, quotaScope?: CodexQuotaScope, selectionOptions?: CodexAccountUsabilityOptions, ): string { const denied = selectionOptions?.deniedModelAccountIds; if (denied === undefined || !denied.has(active)) return active; if (pinnedCodexAccountId(config) === active) return active; // The eligible list restores denied members when filtering would empty it, so re-filter here: // moving from one denied account to another buys nothing and costs the warm prefix. const entitled = getEligiblePoolAccounts(config, active, now, quotaScope, selectionOptions) .filter(id => !denied.has(id)); return pickLowestUsageAmong(config, entitled, selectionOptions, now) ?? active; } /** * Move an unbound request back up when a higher tier regains headroom — the * weekly-reset case. Returns null when nothing should change. * * Downward moves are deliberately left to {@link applyQuotaAutoSwitch}: this only * fires when the tier filter has already excluded `active`, and only toward a * tier that strictly outranks it. Bound threads reach it only through explicit priority failback. */ export function pickPriorityPreemption( config: OcxConfig, active: string, now: number, quotaScope?: CodexQuotaScope, selectionOptions?: CodexAccountUsabilityOptions, ): string | null { const eligible = getEligiblePoolAccounts(config, undefined, now, quotaScope, selectionOptions); if (eligible.length === 0 || eligible.includes(active)) return null; const pinned = pinnedCodexAccountId(config); // A live pin already lowered the tier ceiling; never preempt past an explicit // operator choice. Same liveness test the tier filter applies, so preview and // resolve agree even before the pin is garbage-collected. if ( pinned !== undefined && eligible.includes(pinned) && hasCodexQuotaHeadroom(config, pinned, selectionOptions, now) ) return null; const priorityOf = codexSelectionPriorityLookup(config); if (priorityOf(eligible[0]!) <= priorityOf(active)) return null; // Members without headroom are in the tier only because a sibling has some; // picking one would hand the request straight back to a drained account. return pickLowestUsageAmong( config, eligible.filter(id => hasCodexQuotaHeadroom(config, id, selectionOptions, now)), selectionOptions, now, ); } export function applyQuotaAutoSwitch( config: OcxConfig, active: string, now: number, quotaScope?: CodexQuotaScope, selectionOptions?: CodexAccountUsabilityOptions, commitSharedSelection = true, ): string { const threshold = getEffectiveCodexAutoSwitchThreshold(config, active); if (threshold <= 0) return active; const quota = getAccountQuota(active); const activeUsage = computeCodexUsageScore( quota, getPoolAccountPlanForSelection(config, active, selectionOptions), now, codexAccountUsesCreditsAfterLimit(config, active), ); // Unknown usage is not evidence that a user's explicit selection crossed the // threshold. Wait for quota priming instead of rotating among guesses. if (isUnknownUsage(activeUsage)) return active; if (activeUsage < threshold) return active; const best = pickLowerUsageAccount(config, active, activeUsage, now, quotaScope, selectionOptions); if (best !== active) { if (commitSharedSelection && !isIndependentCodexQuotaScope(quotaScope) && sharesActiveSelection(best, selectionOptions)) { setActiveCodexAccount(config, best); } return best; } return active; } export function shouldFailover(config: OcxConfig, accountId: string, now: number): boolean { const threshold = config.upstreamFailoverThreshold ?? 3; if (threshold <= 0) return false; dropSpentCredentialFailure(accountId); const health = getAccountHealth(accountId); if (health?.lastFailureAt && now - health.lastFailureAt > CODEX_FAILURE_WINDOW_MS) return false; return !!health && health.consecutiveFailures >= threshold; } export function isHealthySharedCodexSelection( config: OcxConfig, accountId: string, now: number, quotaScope: CodexQuotaScope | undefined, selectionOptions: CodexAccountUsabilityOptions | undefined, ): boolean { return isCodexAccountSelectable(config, accountId, now, quotaScope, selectionOptions) && hasCodexSharedStateQuotaHeadroom(config, accountId, quotaScope, selectionOptions, now) && !hasUnrecoveredCodexQuotaRefusal(accountId, quotaScope) && !shouldFailover(config, accountId, now); } export function strategySelectionOptionsForModelDetour( config: OcxConfig, now: number, quotaScope: CodexQuotaScope | undefined, selectionOptions: CodexAccountUsabilityOptions | undefined, ): CodexAccountUsabilityOptions | undefined { if (selectionOptions?.modelEligibleAccountIds === undefined) return selectionOptions; const sharedSelectionOptions = sharedStateSelectionOptions(selectionOptions) ?? {}; return { ...selectionOptions, modelEligibleAccountIds: new Set( [...selectionOptions.modelEligibleAccountIds].filter(accountId => isHealthySharedCodexSelection( config, accountId, now, quotaScope, sharedSelectionOptions, ) ), ), }; } export function applyFailureFailover( config: OcxConfig, active: string, now: number, quotaScope?: CodexQuotaScope, selectionOptions?: CodexAccountUsabilityOptions, commitSharedSelection = true, ): string { if (!shouldFailover(config, active, now) && !failureWindowSteersNewThreads(config, active, now)) return active; const best = pickAlternateCodexAccount(config, active, now, quotaScope, selectionOptions); if (best) { // The scope still routes away from the failing account — that is this request's // own decision — but an independent one must not persist a new shared active // account. recordCodexUpstreamOutcome only suppresses the promotion it makes at // the moment of the failure; the streak outlives the soft avoid, so a later // scoped resolve reaches here with the streak still tripped and would otherwise // move the shared cursor after all. if (commitSharedSelection && !isIndependentCodexQuotaScope(quotaScope) && sharesActiveSelection(best, selectionOptions)) { promoteActiveCodexAccount(config, best); } return best; } return active; }