feat(codex): add exact account routing

Author: chrisae9

src/codex/auth-context.ts

@@ -5,6 +5,7 @@ import {
   isCodexAccountGenerationLive,
 } from "./account-store";
 import { markAccountNeedsReauth } from "./account-runtime-state";
+import { isCodexAccountPaused } from "./account-pause";
 import { isCodexAccountUsable } from "./account-usability";
 import { reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
 import { MAIN_CODEX_ACCOUNT_ID, getMainAccountToken } from "./main-account";
@@ -33,6 +34,8 @@ export type CodexAuthContext =
       generation: number;
       accessToken: string;
       chatgptAccountId: string;
+      /** Prevent pool selection, affinity, and active-account mutation for an exact selector. */
+      fixedAccount?: boolean;
       /**
        * Set when this request was admitted through an active quota cooldown as
        * the account's single probe. Must be echoed into the upstream outcome so
@@ -51,6 +54,8 @@ export type CodexAuthContext =
       accountId: string;
       accessToken: string;
       chatgptAccountId: string;
+      /** Prevent pool selection, affinity, and active-account mutation for an exact selector. */
+      fixedAccount?: boolean;
       /** See `pool.probeLeaseId`. */
       probeLeaseId?: string;
       quotaScope?: CodexQuotaScope;
@@ -148,22 +153,31 @@ export function cooldownAccountLabel(accountId: string): string {
  * as HTTP. The bare "cooling down" string left users with no route but commenting out the
  * injected `openai_base_url` in config.toml.
  */
-export function cooldownErrorMessage(err: CodexAccountCooldownError): string {
+export function cooldownErrorMessage(err: CodexAccountCooldownError, accountSelector?: string): string {
   const until = new Date(err.cooldownUntil).toISOString();
   const scope = err.quotaScope === "spark"
     ? "Spark quota"
     : err.quotaScope === "shared"
       ? "shared native quota"
       : null;
-  return `Selected Codex account (${cooldownAccountLabel(err.accountId)})${scope ? ` ${scope} is` : " is"} cooling down until ${until}`
-    + ` (source: ${err.cooldownSource ?? "default"}).`
-    + ` Run 'ocx account list openai' to find the id, then`
-    + ` 'ocx account clear-cooldown openai <id>' to lift it, or switch accounts with 'ocx account use openai <id>'.`;
+  const selected = accountSelector
+    ? `Selected Codex account selector (${accountSelector})`
+    : `Selected Codex account (${cooldownAccountLabel(err.accountId)})`;
+  const recovery = accountSelector
+    ? " This request is pinned to that selector and will not switch accounts; choose another account-qualified model or retry later."
+    : " Run 'ocx account list openai' to find the id, then"
+      + " 'ocx account clear-cooldown openai <id>' to lift it, or switch accounts with 'ocx account use openai <id>'.";
+  return `${selected}${scope ? ` ${scope} is` : " is"} cooling down until ${until}`
+    + ` (source: ${err.cooldownSource ?? "default"}).${recovery}`;
 }
 
 /** HTTP form of {@link cooldownErrorMessage}, carrying Retry-After for well-behaved clients. */
-export function cooldownErrorResponse(err: CodexAccountCooldownError, now = Date.now()): Response {
-  const res = formatErrorResponse(429, "rate_limit_error", cooldownErrorMessage(err));
+export function cooldownErrorResponse(
+  err: CodexAccountCooldownError,
+  now = Date.now(),
+  accountSelector?: string,
+): Response {
+  const res = formatErrorResponse(429, "rate_limit_error", cooldownErrorMessage(err, accountSelector));
   const headers = new Headers(res.headers);
   headers.set("Retry-After", String(Math.max(1, Math.ceil((err.cooldownUntil - now) / 1000))));
   return new Response(res.body, { status: res.status, headers });
@@ -185,6 +199,8 @@ export function shouldMarkAccountNeedsReauthForCodexAuthFailure(cause: unknown):
 
 export interface ResolveCodexAuthContextOptions {
   excludeAccountId?: string;
+  /** Resolve exactly this account without consulting or mutating Pool selection. */
+  accountId?: string;
   /** Final native model selected for this request, used to select its quota group. */
   modelId?: string;
 }
@@ -195,14 +211,22 @@ export async function resolveCodexAuthContext(
   mode: CodexAccountMode,
   options: ResolveCodexAuthContextOptions = {},
 ): Promise<CodexAuthContext> {
-  if (mode === "direct") {
+  const fixedAccountId = options.accountId;
+  if (fixedAccountId !== undefined && options.excludeAccountId !== undefined) {
+    throw new Error("Codex auth context cannot select and exclude an account simultaneously");
+  }
+  // An explicit namespace binding is stronger than the provider's default mode. It must use the
+  // selected stored credential even while the canonical OpenAI provider is globally Direct.
+  if (mode === "direct" && fixedAccountId === undefined) {
     if (!hasCallerCodexBearer(headers)) throw new CodexDirectAuthenticationError();
     return { kind: "main", accountId: null };
   }
   reconcileMainCodexAccountRuntimeState();
   const threadId = headers.get("x-codex-parent-thread-id");
   const quotaScope = codexQuotaScopeForModel(options.modelId);
-  const resolution = options.excludeAccountId
+  const resolution = fixedAccountId !== undefined
+    ? { status: "selected" as const, accountId: fixedAccountId }
+    : options.excludeAccountId
     ? (() => {
         const accountId = pickAlternateCodexAccount(config, options.excludeAccountId!, Date.now(), quotaScope);
         return accountId
@@ -213,12 +237,16 @@ export async function resolveCodexAuthContext(
   if (resolution.status === "expired") throw new CodexThreadAffinityExpiredError(resolution.accountId);
   let accountId = resolution.status === "selected" ? resolution.accountId : null;
   if (!accountId) throw new CodexPoolAuthenticationError();
+  if (fixedAccountId !== undefined
+    && (isCodexAccountPaused(config, accountId) || !isCodexAccountUsable(config, accountId))) {
+    throw new CodexPoolAuthenticationError();
+  }
   // Lazy prime: if the selected account has no quota yet, the pool is likely
   // unprimed (dashboard never opened, or startup prime was blocked). Kick a
   // best-effort prime so the NEXT routing decision has real scores. This never
   // blocks the current request, and the helper's single-flight guard collapses
   // repeated triggers into one pass.
-  if (!getAccountQuota(accountId)) {
+  if (fixedAccountId === undefined && !getAccountQuota(accountId)) {
     import("./auth-api")
       .then(({ primeCodexPoolQuotas }) => primeCodexPoolQuotas(config, "pre-route"))
       .catch(() => {});
@@ -233,6 +261,11 @@ export async function resolveCodexAuthContext(
   let probeLeaseId: string | undefined;
   let probeQuotaScope: CodexQuotaScope | undefined;
   if (cooldownUntil) {
+    // Exact bindings are not Pool recovery traffic. Fail closed instead of consuming the Pool's
+    // one probe lease or selecting another account.
+    if (fixedAccountId !== undefined) {
+      throw new CodexAccountCooldownError(accountId, cooldownUntil, cooldown?.cooldownSource, cooldown?.quotaScope);
+    }
     probeQuotaScope = cooldown?.quotaScope;
     probeLeaseId = probeQuotaScope
       ? tryAcquireCodexQuotaScopeProbeLease(accountId, probeQuotaScope) ?? undefined
@@ -256,6 +289,7 @@ export async function resolveCodexAuthContext(
       accountId,
       accessToken: token.accessToken,
       chatgptAccountId: token.chatgptAccountId,
+      ...(fixedAccountId !== undefined ? { fixedAccount: true } : {}),
       ...(quotaScope ? { quotaScope } : {}),
       ...(probeLeaseId ? { probeLeaseId } : {}),
       ...(probeQuotaScope ? { probeQuotaScope } : {}),
@@ -270,6 +304,7 @@ export async function resolveCodexAuthContext(
       generation: token.generation,
       accessToken: token.accessToken,
       chatgptAccountId: token.chatgptAccountId,
+      ...(fixedAccountId !== undefined ? { fixedAccount: true } : {}),
       ...(quotaScope ? { quotaScope } : {}),
       ...(probeLeaseId ? { probeLeaseId } : {}),
       ...(probeQuotaScope ? { probeQuotaScope } : {}),

src/codex/routing.ts

@@ -171,6 +171,8 @@ export type CodexUpstreamOutcomeMeta = {
   modelId?: string;
   /** When set, clears affinity for this thread immediately on transient failure. */
   threadId?: string | null;
+  /** Suppress Pool selection and affinity mutations for an account-qualified request. */
+  fixedAccount?: boolean;
   /**
    * Probe lease held by this request, when it was admitted through an active
    * quota cooldown. Only the outcome carrying the current lease may clear the
@@ -1276,7 +1278,7 @@ export function recordCodexUpstreamOutcome(
     });
     quotaScopedHealth.delete(accountId);
     markAccountNeedsReauth(accountId);
-    clearThreadAccountMapForAccount(accountId);
+    if (!meta.fixedAccount) clearThreadAccountMapForAccount(accountId);
     return;
   }
 
@@ -1309,7 +1311,7 @@ export function recordCodexUpstreamOutcome(
       // The shared native scope is the existing account-wide native behavior:
       // threads must leave it and new requests should prefer an eligible account.
       // Spark remains isolated so a same-account Terra/Luna combo fallback can run.
-      if (quotaScope === "shared") {
+      if (quotaScope === "shared" && !meta.fixedAccount) {
         clearThreadAccountMapForAccount(accountId);
         notePoolRotationFailure(POOL_KEY_CODEX, accountId);
         if (getEffectiveActiveCodexAccountId(config) === accountId) {
@@ -1354,17 +1356,19 @@ export function recordCodexUpstreamOutcome(
           ...(prior?.lastProbeAt !== undefined ? { lastProbeAt: prior.lastProbeAt } : {}),
         }),
     });
-    clearThreadAccountMapForAccount(accountId);
-    notePoolRotationFailure(POOL_KEY_CODEX, accountId);
-    const effectiveActive = getEffectiveActiveCodexAccountId(config);
-    if (effectiveActive === accountId) {
-      // Same-request 429 retry already picked via excludeAccountId — reuse it so
-      // round-robin does not advance the ring a second time.
-      const reused = meta.promoteAccountId && meta.promoteAccountId !== accountId
-        ? meta.promoteAccountId
-        : null;
-      const fallback = reused ?? pickAlternateCodexAccount(config, accountId, now);
-      if (fallback) promoteActiveCodexAccount(config, fallback);
+    if (!meta.fixedAccount) {
+      clearThreadAccountMapForAccount(accountId);
+      notePoolRotationFailure(POOL_KEY_CODEX, accountId);
+      const effectiveActive = getEffectiveActiveCodexAccountId(config);
+      if (effectiveActive === accountId) {
+        // Same-request 429 retry already picked via excludeAccountId — reuse it so
+        // round-robin does not advance the ring a second time.
+        const reused = meta.promoteAccountId && meta.promoteAccountId !== accountId
+          ? meta.promoteAccountId
+          : null;
+        const fallback = reused ?? pickAlternateCodexAccount(config, accountId, now);
+        if (fallback) promoteActiveCodexAccount(config, fallback);
+      }
     }
     return;
   }
@@ -1409,15 +1413,17 @@ export function recordCodexUpstreamOutcome(
   // thread is still pinned to the FAILING account — a late failure from account A
   // must not delete a newer healthy binding to account B (race: T→A, A fails,
   // T→B, late A failure must not delete B's mapping).
-  if (failoverReady && meta.threadId) {
+  if (!meta.fixedAccount && failoverReady && meta.threadId) {
     deleteThreadAffinitiesForAccount(meta.threadId, accountId);
   }
   // Once the account is past the failover streak, clear every thread still pinned
   // to it — matching 429 affinity behavior so "continue" cannot stay on a bad peer.
-  if (shouldFailover(config, accountId, now)) {
+  if (!meta.fixedAccount && shouldFailover(config, accountId, now)) {
     clearThreadAccountMapForAccount(accountId);
   }
-  if (getEffectiveActiveCodexAccountId(config) === accountId) applyFailureFailover(config, accountId, now);
+  if (!meta.fixedAccount && getEffectiveActiveCodexAccountId(config) === accountId) {
+    applyFailureFailover(config, accountId, now);
+  }
 }
 
 export function formatCodexProviderForLog(providerName: string, accountId: string | null, config: OcxConfig): string {

src/router.ts

@@ -4,15 +4,26 @@ import { hasOwnProvider, resolveEnvValue } from "./config";
 import { assertProviderDestinationAllowed } from "./lib/destination-policy";
 import { redactSecretString, redactUrlForLog } from "./lib/redact";
 import { PROVIDER_REGISTRY, providerCodexAccountMode } from "./providers/registry";
-import { LEGACY_CHATGPT_PROVIDER_ID, LEGACY_OPENAI_MULTI_PROVIDER_ID, OPENAI_API_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID } from "./providers/openai-tiers";
+import {
+  isCanonicalOpenAiForwardProvider,
+  LEGACY_CHATGPT_PROVIDER_ID,
+  LEGACY_OPENAI_MULTI_PROVIDER_ID,
+  OPENAI_API_PROVIDER_ID,
+  OPENAI_CODEX_PROVIDER_ID,
+} from "./providers/openai-tiers";
 import { decodeRoutedModelId, encodeRoutedModelId } from "./providers/slug-codec";
 import { getStaleCached } from "./codex/model-cache";
+import { codexAccountNamespaceEntries } from "./codex/account-namespaces";
 
 export interface RouteResult {
   providerName: string;
   provider: OcxProviderConfig;
   modelId: string;
   codexAccountMode?: CodexAccountMode;
+  /** Exact account selected by an account-qualified native model. */
+  codexAccountId?: string;
+  /** Public namespace used by the account-qualified selector. */
+  codexAccountNamespace?: string;
   combo?: ComboPick;
 }
 
@@ -313,6 +324,31 @@ function routeResult(providerName: string, provider: OcxProviderConfig, modelId:
 }
 
 function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: boolean): RouteResult {
+  const slash = modelId.indexOf("/");
+  if (slash > 0) {
+    const namespace = modelId.slice(0, slash);
+    const binding = codexAccountNamespaceEntries(config)
+      .find(([candidate]) => candidate === namespace);
+    if (binding) {
+      const nativeModelId = modelId.slice(slash + 1);
+      if (!isBareOpenAiFamilyModel(nativeModelId)) {
+        throw new Error(`Codex account namespace ${namespace} only supports native OpenAI model ids`);
+      }
+      const provider = config.providers[OPENAI_CODEX_PROVIDER_ID];
+      if (!provider || provider.disabled === true || !isCanonicalOpenAiForwardProvider(provider)) {
+        throw new NoEnabledOpenAiProviderError(nativeModelId);
+      }
+      return {
+        ...routeResult(OPENAI_CODEX_PROVIDER_ID, provider, nativeModelId),
+        // Exact account injection uses the pool credential machinery even when the canonical
+        // provider is globally Direct. The fixed id bypasses pool selection entirely.
+        codexAccountMode: "pool",
+        codexAccountId: binding[1],
+        codexAccountNamespace: namespace,
+      };
+    }
+  }
+
   if (!bypassCombos && !preservesPhysicalComboProvider(config)) {
     const combo = tryPickComboModel(config, modelId);
     if (combo) {
@@ -328,7 +364,6 @@ function routeModelInternal(config: OcxConfig, modelId: string, bypassCombos: bo
   //    Only triggers when the prefix matches a CONFIGURED provider, so genuine
   //    slash-containing model ids (e.g. "anthropic/claude-...") fall through when
   //    no such provider exists.
-  const slash = modelId.indexOf("/");
   if (slash > 0) {
     const provName = modelId.slice(0, slash);
     if (provName === LEGACY_CHATGPT_PROVIDER_ID || provName === LEGACY_OPENAI_MULTI_PROVIDER_ID) {

src/server/responses/compact.ts

@@ -186,7 +186,9 @@ export async function handleResponsesCompact(
   const selectedModelId = route.modelId;
   logCtx.requestedModel = raw.model;
   logCtx.model = selectedModelId;
-  logCtx.provider = route.providerName;
+  logCtx.provider = route.codexAccountNamespace
+    ? `${route.providerName}-${route.codexAccountNamespace}`
+    : route.providerName;
   logCtx.providerAdapter = route.provider.adapter;
   const virtual = resolveOpenAiCompactModel(route.providerName, selectedModelId);
   if (virtual) {
@@ -218,7 +220,10 @@ export async function handleResponsesCompact(
     const headers = new Headers({ "content-type": "application/json" });
     try {
       if (route.codexAccountMode) {
-        authCtx = await resolveCodexAuthContext(req.headers, config, route.codexAccountMode, { modelId: selectedModelId });
+        authCtx = await resolveCodexAuthContext(req.headers, config, route.codexAccountMode, {
+          accountId: route.codexAccountId,
+          modelId: selectedModelId,
+        });
         const selected = headersForCodexAuthContext(req.headers, authCtx);
         compactProvider = applyCodexAuthContextToProvider(route.provider, authCtx, route.codexAccountMode);
         for (const name of FORWARD_HEADERS) {
@@ -233,7 +238,7 @@ export async function handleResponsesCompact(
       }
     } catch (err) {
       if (err instanceof CodexAccountCooldownError) {
-        return cooldownErrorResponse(err);
+        return cooldownErrorResponse(err, Date.now(), route.codexAccountNamespace);
       }
       if (err instanceof CodexThreadAffinityExpiredError) {
         return formatErrorResponse(409, "invalid_request_error", "Codex thread account affinity expired; start a new session");
@@ -264,6 +269,7 @@ export async function handleResponsesCompact(
       recordCodexUpstreamOutcome(config, authCtx.accountId, outcome, {
         ...meta,
         threadId: compactThreadId,
+        fixedAccount: authCtx.fixedAccount,
         modelId: selectedModelId,
         probeLeaseId: codexProbeLeaseId(authCtx),
         probeQuotaScope: codexProbeQuotaScope(authCtx),