@bitkyc08/opencodex 2.1.7 → 2.1.9

package/src/codex-auth-api.ts

@@ -0,0 +1,446 @@
+import { loadConfig, saveConfig } from "./config";
+import { withCodexAccountLogLabel } from "./codex-account-label";
+import {
+  getCodexAccountCredential,
+  getValidCodexToken,
+  saveCodexAccountCredential,
+  CodexCredentialGenerationConflictError,
+  CodexCredentialRefreshLockTimeoutError,
+  TokenRefreshError,
+} from "./codex-account-store";
+import { deleteCodexAccount } from "./codex-account-lifecycle";
+import { checkAccountIdCollision, readCodexTokens } from "./codex-auth-collision";
+export { checkAccountIdCollision, getMainChatgptAccountId } from "./codex-auth-collision";
+export { clearAccountNeedsReauth, isAccountNeedsReauth, markAccountNeedsReauth } from "./codex-account-runtime-state";
+import { clearAccountNeedsReauth, isAccountNeedsReauth } from "./codex-account-runtime-state";
+import {
+  clearAccountQuota,
+  getAccountQuota,
+  listAccountQuotas,
+  parseUsageQuota,
+  updateAccountQuota,
+  type StoredAccountQuota,
+  type WhamUsageResponse,
+} from "./codex-quota";
+export { clearAccountQuota, getAccountQuota, parseUsageQuota, updateAccountQuota } from "./codex-quota";
+import { extractAccountId, decodeJwtPayload } from "./oauth/chatgpt";
+import { maskEmail } from "./privacy";
+export { maskEmail } from "./privacy";
+import type { OcxConfig } from "./types";
+
+function jsonResponse(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+const ACCOUNT_ID_RE = /^[a-zA-Z0-9._-]{1,64}$/;
+const MANUAL_IMPORT_ENV = "OPENCODEX_ENABLE_UNVERIFIED_CODEX_IMPORT";
+
+const codexAuthLoginState = new Map<string, { status: string; accountId?: string; email?: string; error?: string; doneAt?: number }>();
+
+export function isUnverifiedCodexImportEnabled(): boolean {
+  return process.env[MANUAL_IMPORT_ENV] === "1";
+}
+
+function manualImportDisabledResponse(): Response {
+  return jsonResponse({
+    error: "Manual Codex account import is disabled. Use OAuth login to add a pool account.",
+    code: "manual_import_disabled",
+  }, 403);
+}
+
+function expireCodexAuthFlow(flowId: string | null, error = "Login cancelled"): void {
+  if (!flowId) return;
+  codexAuthLoginState.set(flowId, { status: "error", error, doneAt: Date.now() });
+  setTimeout(() => codexAuthLoginState.delete(flowId), 30_000);
+}
+
+let mainAccountCache: { email: string | null; plan: string | null; quota: Omit<StoredAccountQuota, "updatedAt"> | null; ts: number } | null = null;
+const MAIN_CACHE_TTL = 5 * 60_000;
+const POOL_CACHE_TTL = 5 * 60_000;
+const POOL_QUOTA_REFRESH_CONCURRENCY = 4;
+
+function isRuntimeConfig(config: OcxConfig): boolean {
+  return !!config && typeof config === "object" && !!config.providers;
+}
+
+function getRuntimeConfig(config: OcxConfig): OcxConfig {
+  return isRuntimeConfig(config) ? config : loadConfig();
+}
+
+function saveRuntimeConfig(sourceConfig: OcxConfig, nextConfig: OcxConfig): void {
+  saveConfig(nextConfig);
+  if (sourceConfig === nextConfig || !isRuntimeConfig(sourceConfig)) return;
+  for (const key of Object.keys(sourceConfig) as Array<keyof OcxConfig>) {
+    delete sourceConfig[key];
+  }
+  Object.assign(sourceConfig, nextConfig);
+}
+
+async function mapWithConcurrency<T, R>(
+  items: T[],
+  concurrency: number,
+  mapper: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const results = new Array<R>(items.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await mapper(items[index]!);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+async function fetchMainAccountInfo(forceRefresh = false): Promise<{ email: string | null; plan: string | null; quota: Omit<StoredAccountQuota, "updatedAt"> | null }> {
+  if (!forceRefresh && mainAccountCache && Date.now() - mainAccountCache.ts < MAIN_CACHE_TTL) {
+    return mainAccountCache;
+  }
+  const tokens = readCodexTokens();
+  if (!tokens) return { email: null, plan: null, quota: null };
+  try {
+    const resp = await fetch("https://chatgpt.com/backend-api/wham/usage", {
+      headers: { Authorization: `Bearer ${tokens.access_token}`, "ChatGPT-Account-Id": tokens.account_id },
+      signal: AbortSignal.timeout(8000),
+    });
+    if (!resp.ok) return { email: null, plan: null, quota: null };
+    const data = (await resp.json()) as WhamUsageResponse;
+    const result = {
+      email: data.email ?? null,
+      plan: data.plan_type ?? null,
+      quota: parseUsageQuota(data),
+      ts: Date.now(),
+    };
+    mainAccountCache = result;
+    return result;
+  } catch {
+    return { email: null, plan: null, quota: null };
+  }
+}
+
+interface PoolQuotaResult {
+  quota: StoredAccountQuota | null;
+  needsReauth: boolean;
+}
+
+async function fetchPoolAccountQuota(accountId: string, forceRefresh = false): Promise<PoolQuotaResult> {
+  const existing = getAccountQuota(accountId);
+  if (!forceRefresh && existing && Date.now() - existing.updatedAt < POOL_CACHE_TTL) {
+    return { quota: existing, needsReauth: false };
+  }
+  try {
+    const { accessToken, chatgptAccountId } = await getValidCodexToken(accountId);
+    const resp = await fetch("https://chatgpt.com/backend-api/wham/usage", {
+      headers: { Authorization: `Bearer ${accessToken}`, "ChatGPT-Account-Id": chatgptAccountId },
+      signal: AbortSignal.timeout(8000),
+    });
+    if (!resp.ok) return { quota: existing ?? null, needsReauth: resp.status === 401 };
+    const data = (await resp.json()) as WhamUsageResponse;
+    const quota = parseUsageQuota(data);
+    if (!quota) return { quota: existing ?? null, needsReauth: false };
+    updateAccountQuota(
+      accountId,
+      quota.weeklyPercent,
+      quota.fiveHourPercent,
+      quota.weeklyResetAt,
+      quota.fiveHourResetAt,
+      quota.monthlyPercent,
+      quota.monthlyResetAt,
+    );
+    return { quota: getAccountQuota(accountId), needsReauth: false };
+  } catch (e) {
+    if (e instanceof CodexCredentialGenerationConflictError || e instanceof CodexCredentialRefreshLockTimeoutError) return { quota: existing ?? null, needsReauth: false };
+    if (e instanceof TokenRefreshError) return { quota: existing ?? null, needsReauth: true };
+    return { quota: existing ?? null, needsReauth: false };
+  }
+}
+
+export async function handleCodexAuthAPI(
+  req: Request,
+  url: URL,
+  config: OcxConfig,
+): Promise<Response | null> {
+
+  if (url.pathname === "/api/codex-auth/accounts" && req.method === "GET") {
+    const forceRefresh = url.searchParams.get("refresh") === "1" || url.searchParams.get("refresh") === "true";
+    const runtimeConfig = getRuntimeConfig(config);
+    const poolAccounts = (runtimeConfig.codexAccounts ?? []).filter(a => !a.isMain);
+    const mainInfo = await fetchMainAccountInfo(forceRefresh);
+    const withQuota = await mapWithConcurrency(poolAccounts, POOL_QUOTA_REFRESH_CONCURRENCY, async a => {
+      const cred = getCodexAccountCredential(a.id);
+      const quotaResult = cred
+        ? await fetchPoolAccountQuota(a.id, forceRefresh)
+        : { quota: null, needsReauth: true };
+      return {
+        ...a,
+        email: maskEmail(a.email) ?? a.email,
+        quota: quotaResult.quota ? { ...quotaResult.quota } : null,
+        needsReauth: !cred || quotaResult.needsReauth || isAccountNeedsReauth(a.id),
+        hasCredential: !!cred,
+      };
+    });
+    const main = {
+      id: "__main__",
+      email: maskEmail(mainInfo.email) ?? "Codex App login",
+      plan: mainInfo.plan,
+      isMain: true,
+      hasCredential: true,
+      quota: mainInfo.quota ? { ...mainInfo.quota, updatedAt: Date.now() } : null,
+    };
+    return jsonResponse({ accounts: [main, ...withQuota] });
+  }
+
+  if (url.pathname === "/api/codex-auth/accounts" && req.method === "POST") {
+    if (!isUnverifiedCodexImportEnabled()) return manualImportDisabledResponse();
+
+    let body: { id: string; email: string; plan?: string; accessToken: string; refreshToken: string; chatgptAccountId: string };
+    try { body = (await req.json()) as typeof body; } catch { return jsonResponse({ error: "Invalid JSON" }, 400); }
+    if (!body.id || !body.email || !body.accessToken || !body.refreshToken || !body.chatgptAccountId) {
+      return jsonResponse({ error: "Missing required fields" }, 400);
+    }
+    if (!ACCOUNT_ID_RE.test(body.id)) {
+      return jsonResponse({ error: "Invalid account id format" }, 400);
+    }
+    if (body.accessToken.length > 10_000 || body.refreshToken.length > 10_000) {
+      return jsonResponse({ error: "Input too large" }, 400);
+    }
+    const runtimeConfig = getRuntimeConfig(config);
+    const accounts = runtimeConfig.codexAccounts ?? [];
+    if (accounts.some(a => a.id === body.id) || getCodexAccountCredential(body.id)) {
+      return jsonResponse({ error: `Account id already exists: ${body.id}` }, 400);
+    }
+    // 1.1: JWT-derived account ID is authoritative; collision check
+    const derivedAccountId = extractAccountId(undefined, body.accessToken) ?? body.chatgptAccountId;
+    const collision = checkAccountIdCollision(derivedAccountId, body.email);
+    if (collision.collision) {
+      return jsonResponse({ error: collision.reason }, 400);
+    }
+    // 4.2: use JWT exp for expiresAt instead of hardcoded 1 hour
+    const payload = decodeJwtPayload(body.accessToken);
+    const exp = typeof payload?.exp === "number" ? payload.exp * 1000 : Date.now() + 3600_000;
+    saveCodexAccountCredential(body.id, {
+      accessToken: body.accessToken,
+      refreshToken: body.refreshToken,
+      expiresAt: exp,
+      chatgptAccountId: derivedAccountId,
+    });
+    clearAccountNeedsReauth(body.id);
+    accounts.push(withCodexAccountLogLabel({ id: body.id, email: body.email, plan: body.plan, isMain: false }, accounts));
+    runtimeConfig.codexAccounts = accounts;
+    saveRuntimeConfig(config, runtimeConfig);
+    return jsonResponse({ ok: true });
+  }
+
+  if (url.pathname === "/api/codex-auth/accounts" && req.method === "DELETE") {
+    const id = url.searchParams.get("id");
+    if (!id) return jsonResponse({ error: "Missing id" }, 400);
+    const runtimeConfig = getRuntimeConfig(config);
+    deleteCodexAccount(runtimeConfig, id);
+    saveRuntimeConfig(config, runtimeConfig);
+    return jsonResponse({ ok: true });
+  }
+
+  if (url.pathname === "/api/codex-auth/active" && req.method === "PUT") {
+    let body: { accountId: string | null };
+    try { body = (await req.json()) as typeof body; } catch { return jsonResponse({ error: "Invalid JSON" }, 400); }
+    const runtimeConfig = getRuntimeConfig(config);
+    if (body.accountId != null) {
+      const exists = (runtimeConfig.codexAccounts ?? []).some(a => a.id === body.accountId);
+      if (!exists) return jsonResponse({ error: "Account not found" }, 400);
+    }
+    runtimeConfig.activeCodexAccountId = body.accountId ?? undefined;
+    saveRuntimeConfig(config, runtimeConfig);
+    return jsonResponse({ ok: true, activeCodexAccountId: body.accountId });
+  }
+
+  if (url.pathname === "/api/codex-auth/active" && req.method === "GET") {
+    const runtimeConfig = getRuntimeConfig(config);
+    return jsonResponse({
+      activeCodexAccountId: runtimeConfig.activeCodexAccountId ?? null,
+      autoSwitchThreshold: runtimeConfig.autoSwitchThreshold ?? 80,
+      upstreamFailoverThreshold: runtimeConfig.upstreamFailoverThreshold ?? 3,
+    });
+  }
+
+  if (url.pathname === "/api/codex-auth/auto-switch" && req.method === "PUT") {
+    let body: { threshold: number };
+    try { body = (await req.json()) as typeof body; } catch { return jsonResponse({ error: "Invalid JSON" }, 400); }
+    if (typeof body.threshold !== "number" || !Number.isInteger(body.threshold) || body.threshold < 0 || body.threshold > 100) {
+      return jsonResponse({ error: "Threshold must be an integer 0-100" }, 400);
+    }
+    const runtimeConfig = getRuntimeConfig(config);
+    runtimeConfig.autoSwitchThreshold = body.threshold;
+    saveRuntimeConfig(config, runtimeConfig);
+    return jsonResponse({ ok: true });
+  }
+
+  if (url.pathname === "/api/codex-auth/failover" && req.method === "PUT") {
+    let body: { threshold: number };
+    try { body = (await req.json()) as typeof body; } catch { return jsonResponse({ error: "Invalid JSON" }, 400); }
+    if (typeof body.threshold !== "number" || !Number.isInteger(body.threshold) || body.threshold < 0 || body.threshold > 20) {
+      return jsonResponse({ error: "Threshold must be an integer 0-20" }, 400);
+    }
+    const runtimeConfig = getRuntimeConfig(config);
+    runtimeConfig.upstreamFailoverThreshold = body.threshold;
+    saveRuntimeConfig(config, runtimeConfig);
+    return jsonResponse({ ok: true });
+  }
+
+  if (url.pathname === "/api/codex-auth/quota" && req.method === "GET") {
+    const quotas: Record<string, unknown> = {};
+    for (const [id, q] of listAccountQuotas()) quotas[id] = q;
+    return jsonResponse({ quotas });
+  }
+
+  if (url.pathname === "/api/codex-auth/login" && req.method === "POST") {
+    const body = (await req.json().catch(() => ({}))) as { id?: string };
+    const requestedAccountId = body.id?.trim();
+    if (requestedAccountId && !ACCOUNT_ID_RE.test(requestedAccountId)) {
+      return jsonResponse({ error: "Invalid account id format" }, 400);
+    }
+    const accountId = requestedAccountId || `chatgpt-${Date.now()}`;
+    const runtimeConfig = getRuntimeConfig(config);
+    if ((runtimeConfig.codexAccounts ?? []).some(a => a.id === accountId) || getCodexAccountCredential(accountId)) {
+      return jsonResponse({ error: `Account id already exists: ${accountId}` }, 400);
+    }
+    const flowId = `flow-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    try {
+      const { startLoginFlow, getLoginStatus } = await import("./oauth/index");
+      const result = await startLoginFlow("chatgpt", { forceLogin: true });
+
+      (async () => {
+        let completed = false;
+        for (let i = 0; i < 150; i++) {
+          await new Promise(r => setTimeout(r, 2000));
+          const st = getLoginStatus("chatgpt");
+          if (st.done && st.loggedIn) {
+            const { getCredential } = await import("./oauth/store");
+            const cred = getCredential("chatgpt");
+            if (cred) {
+              // 1.2: account-ID-based collision check (JWT-derived, not email)
+              const oauthAccountId = cred.accountId;
+              if (!oauthAccountId) {
+                codexAuthLoginState.set(flowId, {
+                  status: "error",
+                  error: "Could not determine account identity from OAuth tokens. Please retry OAuth login.",
+                  doneAt: Date.now(),
+                });
+                completed = true;
+                break;
+              }
+              const collision = checkAccountIdCollision(oauthAccountId, cred.email);
+              if (collision.collision) {
+                codexAuthLoginState.set(flowId, {
+                  status: "error", error: collision.reason, doneAt: Date.now(),
+                });
+                completed = true;
+                break;
+              }
+
+              let email = cred.email || accountId;
+              let plan: string | undefined;
+              let quota: Omit<StoredAccountQuota, "updatedAt"> | null = null;
+              try {
+                const tokens = { access_token: cred.access, account_id: oauthAccountId };
+                const resp = await fetch("https://chatgpt.com/backend-api/wham/usage", {
+                  headers: { Authorization: `Bearer ${tokens.access_token}`, "ChatGPT-Account-Id": tokens.account_id },
+                  signal: AbortSignal.timeout(8000),
+                });
+                if (resp.ok) {
+                  const data = (await resp.json()) as WhamUsageResponse;
+                  email = data.email ?? email;
+                  plan = data.plan_type ?? undefined;
+                  quota = parseUsageQuota(data);
+                }
+              } catch { /* wham fetch is non-blocking */ }
+
+              saveCodexAccountCredential(accountId, {
+                accessToken: cred.access,
+                refreshToken: cred.refresh,
+                expiresAt: cred.expires,
+                chatgptAccountId: oauthAccountId,
+              });
+              clearAccountNeedsReauth(accountId);
+              if (quota) {
+                updateAccountQuota(
+                  accountId,
+                  quota.weeklyPercent,
+                  quota.fiveHourPercent,
+                  quota.weeklyResetAt,
+                  quota.fiveHourResetAt,
+                  quota.monthlyPercent,
+                  quota.monthlyResetAt,
+                );
+              }
+
+              const latestConfig = getRuntimeConfig(config);
+              const accounts = latestConfig.codexAccounts ?? [];
+              if (!accounts.find(a => a.id === accountId)) {
+                accounts.push(withCodexAccountLogLabel({ id: accountId, email, plan, isMain: false }, accounts));
+                latestConfig.codexAccounts = accounts;
+                saveRuntimeConfig(config, latestConfig);
+              }
+              codexAuthLoginState.set(flowId, { status: "done", accountId, email, doneAt: Date.now() });
+              completed = true;
+            }
+            break;
+          }
+          if (st.done && st.error) {
+            codexAuthLoginState.set(flowId, { status: "error", error: st.error, doneAt: Date.now() });
+            completed = true;
+            break;
+          }
+        }
+        if (!completed) {
+          codexAuthLoginState.set(flowId, {
+            status: "error",
+            error: "Login timed out before OAuth completed.",
+            doneAt: Date.now(),
+          });
+        }
+        // TTL: keep completed flow state available for clients that miss a short polling window.
+        setTimeout(() => codexAuthLoginState.delete(flowId), 300_000);
+      })();
+
+      codexAuthLoginState.set(flowId, { status: "pending" });
+      return jsonResponse({ ok: true, flowId, url: result.url, instructions: result.instructions });
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      if (msg.includes("already in progress")) {
+        return jsonResponse({ error: msg, status: "pending" }, 409);
+      }
+      return jsonResponse({ error: msg }, 500);
+    }
+  }
+
+  if (url.pathname === "/api/codex-auth/login/cancel" && req.method === "POST") {
+    const body = (await req.json().catch(() => ({}))) as { flowId?: string };
+    const { cancelLoginFlow } = await import("./oauth/index");
+    const cancelled = cancelLoginFlow("chatgpt");
+    expireCodexAuthFlow(body.flowId ?? null);
+    return jsonResponse({ ok: true, cancelled });
+  }
+
+  if (url.pathname === "/api/codex-auth/login-status" && req.method === "GET") {
+    const flowId = url.searchParams.get("flowId");
+    const accountId = url.searchParams.get("accountId")?.trim();
+    if (flowId) {
+      const st = codexAuthLoginState.get(flowId);
+      if (!st && accountId && getCodexAccountCredential(accountId)) {
+        return jsonResponse({ status: "done", accountId });
+      }
+      return jsonResponse(st ? { ...st, email: maskEmail(st.email) ?? undefined } : { status: "expired" });
+    }
+    // Legacy fallback: return latest pending flow
+    for (const [, st] of codexAuthLoginState) {
+      if (st.status === "pending") return jsonResponse({ ...st, email: maskEmail(st.email) ?? undefined });
+    }
+    return jsonResponse({ status: "idle" });
+  }
+
+  return null;
+}

package/src/codex-auth-collision.ts

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import os from "node:os";
+import { getCodexAccountCredential, listCodexAccountIds } from "./codex-account-store";
+import { loadConfig } from "./config";
+import { extractAccountId, extractEmail } from "./oauth/chatgpt";
+
+export function readCodexTokens(): { access_token: string; account_id: string; id_token?: string } | null {
+  try {
+    const codexHome = process.env["CODEX_HOME"] || join(os.homedir(), ".codex");
+    const authPath = join(codexHome, "auth.json");
+    if (!existsSync(authPath)) return null;
+    const j = JSON.parse(readFileSync(authPath, "utf-8")) as {
+      tokens?: { access_token?: string; account_id?: string; id_token?: string };
+    };
+    if (!j?.tokens?.access_token) return null;
+    return {
+      access_token: j.tokens.access_token,
+      account_id: j.tokens.account_id ?? "",
+      id_token: j.tokens.id_token,
+    };
+  } catch { return null; }
+}
+
+export function getMainChatgptAccountId(): string | null {
+  const tokens = readCodexTokens();
+  if (!tokens) return null;
+  return extractAccountId(tokens.id_token, tokens.access_token) ?? (tokens.account_id || null);
+}
+
+function getMainChatgptEmail(): string | null {
+  const tokens = readCodexTokens();
+  if (!tokens) return null;
+  return extractEmail(tokens.id_token, tokens.access_token) ?? null;
+}
+
+function normalizedEmail(email: string | undefined | null): string | null {
+  const trimmed = email?.trim().toLowerCase();
+  return trimmed || null;
+}
+
+function poolEmailForId(id: string): string | null {
+  const account = (loadConfig().codexAccounts ?? []).find(a => a.id === id);
+  return normalizedEmail(account?.email);
+}
+
+// Business/Team members can share chatgpt_account_id, so require email match too.
+export function checkAccountIdCollision(
+  chatgptAccountId: string,
+  email?: string | null,
+): { collision: true; reason: string } | { collision: false } {
+  const candidateEmail = normalizedEmail(email);
+  const mainId = getMainChatgptAccountId();
+  const mainEmail = getMainChatgptEmail();
+  if (mainId && mainId === chatgptAccountId && (!candidateEmail || !mainEmail || mainEmail === candidateEmail)) {
+    return { collision: true, reason: "This account is your main Codex login. Use a different account for the pool." };
+  }
+  for (const poolId of listCodexAccountIds()) {
+    const cred = getCodexAccountCredential(poolId);
+    const poolEmail = poolEmailForId(poolId);
+    if (cred && cred.chatgptAccountId === chatgptAccountId && (!candidateEmail || !poolEmail || poolEmail === candidateEmail)) {
+      return { collision: true, reason: `Account is already in the pool (${poolId}).` };
+    }
+  }
+  return { collision: false };
+}

package/src/codex-auth-context.ts

@@ -0,0 +1,136 @@
+import {
+  CodexCredentialGenerationConflictError,
+  CodexCredentialRefreshLockTimeoutError,
+  getValidCodexToken,
+  isCodexAccountGenerationLive,
+} from "./codex-account-store";
+import { markAccountNeedsReauth } from "./codex-account-runtime-state";
+import { isCodexAccountUsable } from "./codex-account-usability";
+import { getCodexAccountCooldownUntil, resolveCodexAccountForThreadDetailed } from "./codex-routing";
+import type { OcxConfig, OcxProviderConfig } from "./types";
+import { FORWARD_HEADERS } from "./adapters/openai-responses";
+
+export type CodexAuthContext =
+  | { kind: "main"; accountId: null }
+  | {
+      kind: "pool";
+      accountId: string;
+      generation: number;
+      accessToken: string;
+      chatgptAccountId: string;
+    };
+
+export type OcxRuntimeProviderConfig = OcxProviderConfig & {
+  _codexAccountOverride?: { accessToken: string; chatgptAccountId: string };
+  _codexAccountRequired?: boolean;
+};
+
+export class CodexAuthContextError extends Error {
+  accountId: string;
+
+  constructor(accountId: string, cause: unknown) {
+    super("Codex pool account auth failed", { cause });
+    this.name = "CodexAuthContextError";
+    this.accountId = accountId;
+  }
+}
+
+export class CodexAccountCooldownError extends Error {
+  accountId: string;
+  cooldownUntil: number;
+
+  constructor(accountId: string, cooldownUntil: number) {
+    super("Selected Codex account is cooling down");
+    this.name = "CodexAccountCooldownError";
+    this.accountId = accountId;
+    this.cooldownUntil = cooldownUntil;
+  }
+}
+
+export class CodexThreadAffinityExpiredError extends Error {
+  accountId: string;
+
+  constructor(accountId: string) {
+    super("Codex thread account affinity expired");
+    this.name = "CodexThreadAffinityExpiredError";
+    this.accountId = accountId;
+  }
+}
+
+export function shouldMarkAccountNeedsReauthForCodexAuthFailure(cause: unknown): boolean {
+  return !(cause instanceof CodexCredentialGenerationConflictError) && !(cause instanceof CodexCredentialRefreshLockTimeoutError);
+}
+
+export async function resolveCodexAuthContext(headers: Headers, config: OcxConfig): Promise<CodexAuthContext> {
+  const threadId = headers.get("x-codex-parent-thread-id");
+  const resolution = resolveCodexAccountForThreadDetailed(threadId, config);
+  if (resolution.status === "expired") throw new CodexThreadAffinityExpiredError(resolution.accountId);
+  const accountId = resolution.status === "selected" ? resolution.accountId : null;
+  if (!accountId) return { kind: "main", accountId: null };
+  const cooldownUntil = getCodexAccountCooldownUntil(accountId);
+  if (cooldownUntil) throw new CodexAccountCooldownError(accountId, cooldownUntil);
+
+  try {
+    const token = await getValidCodexToken(accountId);
+    return {
+      kind: "pool",
+      accountId,
+      generation: token.generation,
+      accessToken: token.accessToken,
+      chatgptAccountId: token.chatgptAccountId,
+    };
+  } catch (cause) {
+    if (shouldMarkAccountNeedsReauthForCodexAuthFailure(cause)) {
+      markAccountNeedsReauth(accountId);
+    }
+    throw new CodexAuthContextError(accountId, cause);
+  }
+}
+
+export function assertCodexAuthContextNotCooled(ctx: CodexAuthContext | undefined): void {
+  if (ctx?.kind !== "pool") return;
+  const cooldownUntil = getCodexAccountCooldownUntil(ctx.accountId);
+  if (cooldownUntil) throw new CodexAccountCooldownError(ctx.accountId, cooldownUntil);
+}
+
+export function applyCodexAuthContextToProvider(
+  provider: OcxProviderConfig,
+  ctx: CodexAuthContext,
+): OcxRuntimeProviderConfig {
+  if (ctx.kind !== "pool" || provider.authMode !== "forward") return provider;
+  return {
+    ...provider,
+    _codexAccountOverride: {
+      accessToken: ctx.accessToken,
+      chatgptAccountId: ctx.chatgptAccountId,
+    },
+    _codexAccountRequired: true,
+  };
+}
+
+export function headersForCodexAuthContext(headers: Headers, ctx: CodexAuthContext): Headers {
+  const selected = new Headers();
+  for (const name of FORWARD_HEADERS) {
+    const value = headers.get(name);
+    if (value) selected.set(name, value);
+  }
+  if (ctx.kind === "pool") {
+    selected.set("authorization", `Bearer ${ctx.accessToken}`);
+    selected.set("chatgpt-account-id", ctx.chatgptAccountId);
+  }
+  return selected;
+}
+
+export function isCodexAuthContextUsable(ctx: CodexAuthContext, config: OcxConfig): boolean {
+  if (ctx.kind === "main") return true;
+  return isCodexAccountUsable(config, ctx.accountId) && isCodexAccountGenerationLive(ctx.accountId, ctx.generation);
+}
+
+export function stripCodexRuntimeProviderFields(provider: OcxProviderConfig): OcxProviderConfig {
+  const {
+    _codexAccountOverride: _override,
+    _codexAccountRequired: _required,
+    ...safeProvider
+  } = provider as OcxRuntimeProviderConfig;
+  return safeProvider;
+}

package/src/codex-catalog.ts

@@ -419,13 +419,16 @@ async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs:
   if (prov.authMode === "forward") return []; // ChatGPT backend has no /models
   const apiKey = await resolveModelsAuthToken(name, prov);
   if (prov.authMode === "oauth" && !apiKey) return []; // not logged in → skip
-  const fresh = getFreshCached(name, ttlMs);
-  if (fresh) return applyConfigHintsToCachedModels(name, prov, fresh); // dedups Codex's frequent /v1/models polling within the TTL
   const configured: CatalogModel[] = (prov.models ?? []).map(id => ({
     id,
     provider: name,
     ...catalogHintsFromProviderConfig(name, prov, id),
   }));
+  if (prov.liveModels === false) {
+    return configured;
+  }
+  const fresh = getFreshCached(name, ttlMs);
+  if (fresh) return applyConfigHintsToCachedModels(name, prov, fresh); // dedups Codex's frequent /v1/models polling within the TTL
   const { url, headers } = buildModelsRequest(prov, apiKey);
   try {
     const res = await fetch(url, { headers, signal: AbortSignal.timeout(8000) });
@@ -475,6 +478,7 @@ export function augmentRoutedModelsWithJawcodeMetadata(models: CatalogModel[], p
   const seen = new Set(out.map(m => `${m.provider}/${m.id}`));
   for (const provider of providerNames) {
     if (!JAWCODE_CATALOG_AUGMENT_PROVIDERS.has(provider)) continue;
+    if (providers?.[provider]?.liveModels === false) continue;
     const jawcodeProvider = resolveJawcodeProvider(provider);
     if (!jawcodeProvider) continue;
     for (const meta of listJawcodeModelMetadata(jawcodeProvider)) {
@@ -592,7 +596,13 @@ export function invalidateCodexModelsCache(): void {
   try {
     const catalogPath = readCodexCatalogPath();
     if (!existsSync(catalogPath)) return;
-    const catalog = readFileSync(catalogPath, "utf8");
-    atomicWriteFile(CODEX_MODELS_CACHE_PATH, catalog.endsWith("\n") ? catalog : `${catalog}\n`);
+    const catalog = JSON.parse(readFileSync(catalogPath, "utf8"));
+    const models = catalog.models ?? catalog;
+    const wrapper = {
+      fetched_at: "2000-01-01T00:00:00Z",
+      client_version: "0.0.0",
+      models,
+    };
+    atomicWriteFile(CODEX_MODELS_CACHE_PATH, JSON.stringify(wrapper, null, 2) + "\n");
   } catch { /* best-effort */ }
 }