Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

feat(openai-codex): read tool_mode from the Codex /models endpoint

Jack Rudenko9f7a1e41a99f
diff --git a/packages/cli/src/providers/codex-models-discovery.ts b/packages/cli/src/providers/codex-models-discovery.ts
new file mode 100644
index 00000000..2543413d
--- /dev/null
+++ b/packages/cli/src/providers/codex-models-discovery.ts
@@ -0,0 +1,341 @@
+/**
+ * Codex `/models` discovery — the per-model dispatch flags the ChatGPT Codex
+ * backend publishes for ONE account.
+ *
+ * `GET https://chatgpt.com/backend-api/codex/models?client_version=<v>`
+ * (the official client's own call, captured live in R1) returns, per model:
+ * `tool_mode` (`code_mode_only`), `use_responses_lite`,
+ * `default_reasoning_level`, `default_verbosity` and `truncation_policy`.
+ * claudish reads those as RULES from discovery; nothing here pins a model id,
+ * a mode or a limit.
+ *
+ * The answer is a dynamic models catalog for one credential:
+ * - memoised in this process only, keyed by `accountKey`
+ * (`code-mode/ids.ts`), 1 h TTL, single-flight per account;
+ * - never persisted;
+ * - stale-while-error: a failed refetch keeps the last good value (logged).
+ *
+ * Discovery is NOT an auth site. It never decides a status and never throws:
+ * every failure, timeout or unrecognised body resolves to `undefined`
+ * ("discovery-unknown"), and the caller stays on its non-code-mode default.
+ *
+ * Fallback, read-only: `~/.codex/models_cache.json`, the official Codex CLI's
+ * own cache of the same endpoint (already read by
+ * `auth/quota/sources/codex.ts`). It is consulted only while this process has
+ * no good live answer for the account, and it also supplies `client_version`.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { log } from "../logger.js";
+import type { AuthBinding } from "./transport/types.js";
+
+/** One model's dispatch flags, as `/models` publishes them. */
+export interface CodexModelInfo {
+ slug: string;
+ toolMode?: string;
+ useResponsesLite?: boolean;
+ defaultReasoningLevel?: string;
+ defaultVerbosity?: string;
+ truncationPolicy?: { mode: string; limit: number };
+}
+
+/**
+ * A request default the Codex /models endpoint justifies. Empty today: the
+ * B experiment found no request factor with a significant effect
+ * (`ai-docs/reports/codex-parallel-wrapper-degeneration-2026-10.md`, Fisher
+ * p = 1.000 for each). Plug point, should one ever be used:
+ * `wireChoicesFromClaudeRequest` in composed-handler, as a default only when
+ * Claude Code sent none, still clamped by step 5w. No call site ships.
+ */
+export interface CodexDiscoveryRules {
+ /** From `defaultReasoningLevel`. */
+ defaultEffort?: string;
+}
+
+/**
+ * The `client_version` sent when `~/.codex/models_cache.json` names none: the
+ * codex-cli version whose `/models` call R1 captured (0.161.0). The backend
+ * filters models by `minimal_client_version`, so the value must be a real
+ * client version; it is a protocol constant, not model data.
+ */
+export const CODEX_DISCOVERY_CLIENT_VERSION = "0.161.0";
+
+/** How long a good answer is served before a refetch. */
+export const CODEX_DISCOVERY_TTL_MS = 60 * 60 * 1000;
+/** Ceiling on one `/models` fetch. */
+export const CODEX_DISCOVERY_FETCH_TIMEOUT_MS = 10_000;
+/** How long a request with an empty memo waits for the fetch before going on. */
+export const CODEX_DISCOVERY_DEFAULT_WAIT_MS = 2_000;
+/**
+ * After a failed fetch with no good answer to keep, the next fetch waits this
+ * long, so an unreachable endpoint costs one attempt per minute rather than
+ * one (and a 2 s wait) per request.
+ */
+const FAILURE_RETRY_AFTER_MS = 60 * 1000;
+
+type ModelTable = Map<string, CodexModelInfo>;
+
+interface MemoEntry {
+ /** The last good live answer, and when it was fetched. */
+ good?: { models: ModelTable; fetchedAt: number };
+ /** The fetch in flight for this account (single-flight). */
+ inflight?: Promise<ModelTable | undefined>;
+ /** When the last fetch failed, while `good` was absent. */
+ failedAt?: number;
+}
+
+/** Per-process memo, keyed by accountKey. Never written to disk. */
+const memo = new Map<string, MemoEntry>();
+
+export interface CodexDiscoveryOptions {
+ /** Longest wait for a first fetch when the memo is empty. Default 2 s. */
+ waitMs?: number;
+ /** Test seam: default the global `fetch`. */
+ fetchImpl?: typeof fetch;
+ /** Test seam: default `Date.now`. */
+ now?: () => number;
+ /** Test seam: the Codex CLI home holding `models_cache.json`. Default `~/.codex`. */
+ codexHome?: string;
+}
+
+/** Drop every memoised answer (tests; a changed login keys a new entry anyway). */
+export function clearCodexModelsMemo(): void {
+ memo.clear();
+}
+
+/**
+ * The discovery URL for a binding: the binding's Responses endpoint with its
+ * trailing `/responses` replaced by `/models?client_version=<v>`. Undefined
+ * when the binding has no endpoint or the endpoint has no such suffix.
+ */
+export function codexModelsUrl(
+ binding: AuthBinding | undefined,
+ clientVersion: string
+): string | undefined {
+ const endpoint = binding?.auth?.endpoint;
+ if (!endpoint) return undefined;
+ const base = endpoint.replace(/\/+$/, "");
+ if (!base.endsWith("/responses")) return undefined;
+ const root = base.slice(0, -"/responses".length);
+ return `${root}/models?client_version=${encodeURIComponent(clientVersion)}`;
+}
+
+function readModelsCache(codexHome: string | undefined): unknown {
+ try {
+ const path = join(codexHome ?? join(homedir(), ".codex"), "models_cache.json");
+ if (!existsSync(path)) return undefined;
+ return JSON.parse(readFileSync(path, "utf-8"));
+ } catch {
+ return undefined;
+ }
+}
+
+function clientVersionFrom(cache: unknown): string {
+ const v = (cache as { client_version?: unknown } | undefined)?.client_version;
+ return typeof v === "string" && /^\d+\.\d+\.\d+/.test(v) ? v : CODEX_DISCOVERY_CLIENT_VERSION;
+}
+
+/** Map one raw `/models` entry to the fields claudish reads; undefined without a slug. */
+function toModelInfo(raw: unknown): CodexModelInfo | undefined {
+ if (!raw || typeof raw !== "object") return undefined;
+ const m = raw as Record<string, unknown>;
+ const slug = typeof m.slug === "string" ? m.slug : undefined;
+ if (!slug) return undefined;
+ const info: CodexModelInfo = { slug };
+ if (typeof m.tool_mode === "string") info.toolMode = m.tool_mode;
+ if (typeof m.use_responses_lite === "boolean") info.useResponsesLite = m.use_responses_lite;
+ if (typeof m.default_reasoning_level === "string") {
+ info.defaultReasoningLevel = m.default_reasoning_level;
+ }
+ if (typeof m.default_verbosity === "string") info.defaultVerbosity = m.default_verbosity;
+ const tp = m.truncation_policy as { mode?: unknown; limit?: unknown } | null | undefined;
+ if (tp && typeof tp.mode === "string" && typeof tp.limit === "number") {
+ info.truncationPolicy = { mode: tp.mode, limit: tp.limit };
+ }
+ return info;
+}
+
+/** `{models:[…]}` → slug-keyed table; undefined when the body is not that shape. */
+function toModelTable(body: unknown): ModelTable | undefined {
+ const models = (body as { models?: unknown } | undefined)?.models;
+ if (!Array.isArray(models)) return undefined;
+ const table: ModelTable = new Map();
+ for (const raw of models) {
+ const info = toModelInfo(raw);
+ if (info) table.set(info.slug.toLowerCase(), info);
+ }
+ return table;
+}
+
+/** The binding's headers with `accept: application/json` (any other-case Accept dropped). */
+function discoveryHeaders(binding: AuthBinding): Record<string, string> {
+ const headers: Record<string, string> = {};
+ for (const [name, value] of Object.entries(binding.auth?.headers ?? {})) {
+ if (name.toLowerCase() === "accept") continue;
+ headers[name] = value;
+ }
+ headers.accept = "application/json";
+ return headers;
+}
+
+async function fetchModelTable(
+ binding: AuthBinding,
+ opts: CodexDiscoveryOptions
+): Promise<ModelTable | undefined> {
+ const url = codexModelsUrl(binding, clientVersionFrom(readModelsCache(opts.codexHome)));
+ if (!url) {
+ log("[CodexDiscovery] endpoint has no /responses suffix; tool_mode unknown");
+ return undefined;
+ }
+ try {
+ const doFetch = opts.fetchImpl ?? fetch;
+ const response = await doFetch(url, {
+ method: "GET",
+ headers: discoveryHeaders(binding),
+ signal: AbortSignal.timeout(CODEX_DISCOVERY_FETCH_TIMEOUT_MS),
+ });
+ if (!response.ok) {
+ await response.body?.cancel().catch(() => {});
+ log(`[CodexDiscovery] GET /models answered HTTP ${response.status}`);
+ return undefined;
+ }
+ const table = toModelTable(await response.json());
+ if (!table) {
+ log("[CodexDiscovery] GET /models body has no models array");
+ return undefined;
+ }
+ log(`[CodexDiscovery] GET /models: ${table.size} model(s)`);
+ return table;
+ } catch (err) {
+ log(`[CodexDiscovery] GET /models failed: ${err}`);
+ return undefined;
+ }
+}
+
+/** Start (or join) the account's fetch; settles the memo entry when it ends. */
+function startFetch(
+ entry: MemoEntry,
+ binding: AuthBinding,
+ opts: CodexDiscoveryOptions,
+ now: () => number
+): Promise<ModelTable | undefined> {
+ if (entry.inflight) return entry.inflight;
+ const p = fetchModelTable(binding, opts).then((table) => {
+ if (table) {
+ entry.good = { models: table, fetchedAt: now() };
+ entry.failedAt = undefined;
+ } else if (entry.good) {
+ log("[CodexDiscovery] refetch failed; keeping the last good answer");
+ } else {
+ entry.failedAt = now();
+ }
+ return table ?? entry.good?.models;
+ });
+ entry.inflight = p.finally(() => {
+ entry.inflight = undefined;
+ });
+ return entry.inflight;
+}
+
+/** `p`'s value, or `"timeout"` after `ms`; the timer never outlives the race. */
+async function waitAtMost<T>(p: Promise<T>, ms: number): Promise<T | "timeout"> {
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const timedOut = new Promise<"timeout">((resolve) => {
+ timer = setTimeout(() => resolve("timeout"), ms);
+ });
+ try {
+ return await Promise.race([p, timedOut]);
+ } finally {
+ if (timer) clearTimeout(timer);
+ }
+}
+
+/**
+ * The empty-memo path: start (or join) the fetch and wait at most `waitMs`,
+ * unless a recent failure is still backing off. Without a live answer in time,
+ * the Codex CLI's cache.
+ */
+async function firstAnswer(
+ entry: MemoEntry,
+ slug: string,
+ binding: AuthBinding,
+ opts: CodexDiscoveryOptions,
+ now: () => number
+): Promise<CodexModelInfo | undefined> {
+ const backingOff =
+ entry.failedAt !== undefined && now() - entry.failedAt < FAILURE_RETRY_AFTER_MS;
+ if (!backingOff || entry.inflight) {
+ const waitMs = Math.max(0, opts.waitMs ?? CODEX_DISCOVERY_DEFAULT_WAIT_MS);
+ const result = await waitAtMost(startFetch(entry, binding, opts, now), waitMs);
+ // A live answer is authoritative: a model it does not list is unknown,
+ // never filled in from the CLI's cache.
+ if (result !== "timeout" && result) return result.get(slug.toLowerCase());
+ if (result === "timeout" && slug) {
+ log(`[CodexDiscovery] ${slug}: /models not answered within ${waitMs} ms`);
+ }
+ }
+ return slug ? fromModelsCache(slug, opts.codexHome) : undefined;
+}
+
+/** The Codex CLI's cached answer for `slug`, when this process has no live one. */
+function fromModelsCache(slug: string, codexHome: string | undefined): CodexModelInfo | undefined {
+ const info = toModelTable(readModelsCache(codexHome))?.get(slug.toLowerCase());
+ if (info) log(`[CodexDiscovery] ${slug}: using ~/.codex/models_cache.json`);
+ return info;
+}
+
+/**
+ * Start the account's `/models` fetch without waiting for it, so a later
+ * tool-bearing request finds the memo warm. Meant for right after step 5b of an
+ * `openai-codex` OAuth request (Claude Code's first request is usually
+ * tool-less). Never throws.
+ */
+export function prefetchCodexModels(
+ binding: AuthBinding,
+ accountKey: string,
+ opts: CodexDiscoveryOptions = {}
+): void {
+ void getCodexModelInfo("", binding, accountKey, { ...opts, waitMs: 0 }).catch(() => {});
+}
+
+/**
+ * The `/models` entry for `slug` on the account `accountKey` names, fetched
+ * with `binding` (this request's OAuth artifact).
+ *
+ * - fresh memo → answered from it;
+ * - stale memo → answered from it while one refetch runs (stale-while-error
+ * keeps it if that refetch fails);
+ * - empty memo → the fetch is started (or joined) and awaited at most
+ * `waitMs` (default 2 s); past that, `undefined` now and the memo fills
+ * for the next request.
+ * With no good live answer, `~/.codex/models_cache.json` is consulted.
+ * `undefined` = unknown. Never throws.
+ */
+export async function getCodexModelInfo(
+ slug: string,
+ binding: AuthBinding,
+ accountKey: string,
+ opts: CodexDiscoveryOptions = {}
+): Promise<CodexModelInfo | undefined> {
+ try {
+ const now = opts.now ?? Date.now;
+ let entry = memo.get(accountKey);
+ if (!entry) {
+ entry = {};
+ memo.set(accountKey, entry);
+ }
+
+ if (entry.good) {
+ if (now() - entry.good.fetchedAt >= CODEX_DISCOVERY_TTL_MS) {
+ void startFetch(entry, binding, opts, now);
+ }
+ return entry.good.models.get(slug.toLowerCase());
+ }
+ return await firstAnswer(entry, slug, binding, opts, now);
+ } catch (err) {
+ log(`[CodexDiscovery] lookup failed: ${err}`);
+ return undefined;
+ }
+}