@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,144 lines (1,059 loc) • 47.7 kB
text/typescript
import { execFile, execFileSync } from "node:child_process";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import { delimiter, join } from "node:path";
import { atomicWriteFile, getConfigDir } from "../config";
import { codexExecInvocation, isSpawnableCodexCandidate } from "./exec-invocation";
import { resolveCodexHomeDir } from "./home";
import { redactSecretString, redactUserPath } from "../lib/redact";
export type CodexRuntimeSource =
| "environment"
| "configured"
| "shim"
| "installed"
| "path"
| "fallback";
export type DeepReadonly<T> =
T extends (...args: never[]) => unknown ? T
: T extends readonly (infer U)[] ? readonly DeepReadonly<U>[]
: T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
: T;
export interface ResolvedCodexRuntime {
readonly command: string;
readonly version: string | null;
readonly source: CodexRuntimeSource;
}
export interface RuntimeProbeFailure {
readonly command: string;
readonly source: CodexRuntimeSource;
readonly reason: string;
}
export interface EffortClampDiagnostic {
readonly runtimePath: string;
readonly runtimeVersion: string | null;
readonly removedEfforts: readonly string[];
readonly affectedModels: readonly string[];
}
export interface ResolveCodexRuntimeResult {
readonly runtime: ResolvedCodexRuntime;
readonly failures: readonly RuntimeProbeFailure[];
readonly replacedConfigured?: Readonly<{ from: ResolvedCodexRuntime; reason: string }>;
/**
* Set when an unpinned, still-runnable persisted discovery is handed over to a
* strictly newer valid candidate. Distinct from replacedConfigured, which means
* the configured runtime became invalid; conflating "gone" with "superseded"
* would make the doctor output lie.
*/
readonly supersededDiscovered?: Readonly<{ from: ResolvedCodexRuntime; to: ResolvedCodexRuntime; reason: string }>;
readonly newerAvailable?: ResolvedCodexRuntime;
/** Set when the selected runtime could not be written to codex-runtime.json. */
readonly persistError?: string;
}
export type RuntimeExecFile = (
file: string,
args: string[],
options: {
encoding: "utf8";
stdio: ["ignore", "pipe", "ignore"];
timeout: number;
windowsHide: boolean;
shell?: boolean;
windowsVerbatimArguments?: boolean;
env?: NodeJS.ProcessEnv;
},
) => string;
/** Async twin of RuntimeExecFile, used by resolveCodexRuntimeAsync; resolves with stdout. */
export type RuntimeExecFileAsync = (
...args: Parameters<RuntimeExecFile>
) => Promise<string>;
export interface ResolveCodexRuntimeDeps {
env?: NodeJS.ProcessEnv;
platform?: NodeJS.Platform;
configDir?: string;
execFileSync?: RuntimeExecFile;
/** Probe exec for resolveCodexRuntimeAsync. Injected impls bypass the process memo like execFileSync. */
execFile?: RuntimeExecFileAsync;
existsSync?: (path: string) => boolean;
readFileSync?: (path: string, encoding: "utf8") => string;
now?: () => number;
/**
* When false, stop after the first valid priority candidate (skip PATH-wide
* newerAvailable discovery). Use for hot UI/status paths.
*/
discoverAlternatives?: boolean;
/**
* When false, select a spawnable candidate without running `codex --version`.
* The prompt probe needs a command it can spawn, not a version, and paying
* ~1s of blocking exec per candidate on a UI path is what made it report an
* absent candidate instead of the Windows Codex App install (issue 4458).
*/
probeVersion?: boolean;
/**
* Directory listing used by Windows App-root discovery. Injected so tests can
* exercise the LOCALAPPDATA OpenAI/Codex/bin layout without a real Windows
* filesystem. Must be listed in resolveCacheKey's injection guard: an injected
* listing that leaked into the process memo would pin every later test in this
* file to a fake install.
*/
readdirSync?: (path: string) => string[];
/**
* Stat used to order Windows App version directories by mtime. Same injection
* contract as readdirSync: a test-supplied impl must not populate the process
* memo.
*/
statSync?: (path: string) => { mtimeMs: number; isDirectory(): boolean };
}
/**
* How a `codex-runtime.json` record got onto disk.
*
* "pinned" is an intentional operator selection (doctor --fix). "discovered" is
* automatic resolve-and-persist. Absent is the pre-field shape and is treated
* as discovered, not pinned: every such file was written by
* resolveAndPersistCodexRuntime, so reading it as a pin would leave issue 4204
* unfixed on exactly the installs that have it.
*/
export type CodexRuntimePinOrigin = "pinned" | "discovered";
export interface PersistedCodexRuntimeState {
readonly version: 1;
readonly command: string;
readonly source: CodexRuntimeSource;
readonly selectedVersion?: string | null;
readonly updatedAt: string;
readonly origin?: CodexRuntimePinOrigin;
}
const PERSIST_FILE = "codex-runtime.json";
const CLAMP_PERSIST_FILE = "codex-runtime-clamp.json";
/** Probe rejection for an absolute candidate whose file is gone. Matched when retiring a dead pin (#4035). */
const PATH_MISSING_REASON = "path does not exist";
/**
* Probe rejection when the selected command cannot even be spawned. Distinct
* from PATH_MISSING_REASON (the absolute path was gone before spawn) and from
* the generic `failed --version (...)` string (the binary ran and failed).
* Exported because the prompt probe classifies this as program-not-found, so a
* PATH fallback that is simply not installed must not look like an execution
* failure (issue 4458).
*/
export const CODEX_PROGRAM_NOT_FOUND_REASON = "program not found (ENOENT)";
function cloneAndDeepFreeze<T>(value: T): DeepReadonly<T> {
const clone = (current: unknown): unknown => {
if (Array.isArray(current)) return current.map(clone);
if (current && typeof current === "object") {
const out: Record<string, unknown> = {};
for (const [key, child] of Object.entries(current)) out[key] = clone(child);
return out;
}
return current;
};
const freeze = (current: unknown): unknown => {
if (!current || typeof current !== "object" || Object.isFrozen(current)) return current;
for (const child of Object.values(current)) freeze(child);
return Object.freeze(current);
};
return freeze(clone(value)) as DeepReadonly<T>;
}
function isCodexRuntimeSource(value: unknown): value is CodexRuntimeSource {
return value === "environment"
|| value === "configured"
|| value === "shim"
|| value === "installed"
|| value === "path"
|| value === "fallback";
}
function isCodexRuntimePinOrigin(value: unknown): value is CodexRuntimePinOrigin {
return value === "pinned" || value === "discovered";
}
export function codexRuntimeStatePath(configDir: string = getConfigDir()): string {
return join(configDir, PERSIST_FILE);
}
export function codexRuntimeClampStatePath(configDir: string = getConfigDir()): string {
return join(configDir, CLAMP_PERSIST_FILE);
}
interface PersistedClampState extends EffortClampDiagnostic {
version: 1;
updatedAt: string;
}
interface LoadedEffortClampDiagnostic {
runtimePath: string;
runtimeVersion: string | null;
removedEfforts: string[];
affectedModels: string[];
}
export function loadLastEffortClamp(
deps: ResolveCodexRuntimeDeps = {},
): LoadedEffortClampDiagnostic | null {
const configDir = deps.configDir ?? getConfigDir();
const read = deps.readFileSync ?? ((path, encoding) => readFileSync(path, encoding));
try {
const raw = JSON.parse(read(codexRuntimeClampStatePath(configDir), "utf8")) as PersistedClampState;
if (raw?.version !== 1 || !Array.isArray(raw.removedEfforts)) return null;
return {
runtimePath: typeof raw.runtimePath === "string" ? raw.runtimePath : "codex",
runtimeVersion: typeof raw.runtimeVersion === "string" ? raw.runtimeVersion : null,
removedEfforts: raw.removedEfforts.filter((item): item is string => typeof item === "string"),
affectedModels: Array.isArray(raw.affectedModels)
? raw.affectedModels.filter((item): item is string => typeof item === "string")
: [],
};
} catch {
return null;
}
}
export function persistEffortClamp(
diagnostic: EffortClampDiagnostic | null,
deps: ResolveCodexRuntimeDeps = {},
): void {
const configDir = deps.configDir ?? getConfigDir();
const path = codexRuntimeClampStatePath(configDir);
if (!diagnostic || diagnostic.removedEfforts.length === 0) {
try {
unlinkSync(path);
} catch {
/* absent is fine */
}
return;
}
const payload: PersistedClampState = {
version: 1,
updatedAt: new Date((deps.now ?? Date.now)()).toISOString(),
runtimePath: diagnostic.runtimePath,
runtimeVersion: diagnostic.runtimeVersion,
removedEfforts: diagnostic.removedEfforts,
affectedModels: diagnostic.affectedModels,
};
mkdirSync(configDir, { recursive: true, mode: 0o700 });
atomicWriteFile(path, `${JSON.stringify(payload, null, 2)}\n`);
}
export function displayCodexRuntimePath(command: string): string {
if (command === "codex") return "codex";
return redactUserPath(command);
}
export function parseCodexVersionOutput(raw: string): string | null {
const text = String(raw || "").trim();
if (!text) return null;
const match = text.match(/\b(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\b/);
return match?.[1] ?? null;
}
/** Compare dotted Codex versions. Returns negative if a < b. */
export function compareCodexVersions(a: string | null, b: string | null): number {
if (!a && !b) return 0;
if (!a) return -1;
if (!b) return 1;
const parse = (value: string) => {
const dash = value.indexOf("-");
const core = dash < 0 ? value : value.slice(0, dash);
const pre = dash < 0 ? "" : value.slice(dash + 1);
const parts = core.split(".").map(part => Number.parseInt(part, 10) || 0);
// SemVer prerelease identifiers are '.'-separated; keep hyphenated ids intact.
const preParts = pre
? pre.split(".").map(part => (/^\d+$/.test(part) ? Number.parseInt(part, 10) : part))
: [];
return { parts, preParts };
};
const left = parse(a);
const right = parse(b);
const len = Math.max(left.parts.length, right.parts.length);
for (let i = 0; i < len; i += 1) {
const diff = (left.parts[i] ?? 0) - (right.parts[i] ?? 0);
if (diff !== 0) return diff;
}
if (left.preParts.length === 0 && right.preParts.length > 0) return 1;
if (left.preParts.length > 0 && right.preParts.length === 0) return -1;
const preLen = Math.max(left.preParts.length, right.preParts.length);
for (let i = 0; i < preLen; i += 1) {
const lp = left.preParts[i];
const rp = right.preParts[i];
if (lp === undefined) return -1;
if (rp === undefined) return 1;
if (typeof lp === "number" && typeof rp === "number") {
if (lp !== rp) return lp - rp;
continue;
}
if (typeof lp === "number") return -1; // numeric < non-numeric (SemVer)
if (typeof rp === "number") return 1;
if (lp < rp) return -1;
if (lp > rp) return 1;
}
return 0;
}
/** Parse already-observed runtime-selection bytes without consulting the filesystem. */
export function parsePersistedCodexRuntime(
bytes: string | Uint8Array,
): DeepReadonly<PersistedCodexRuntimeState> | null {
try {
const text = typeof bytes === "string" ? bytes : Buffer.from(bytes).toString("utf8");
const raw = JSON.parse(text) as Partial<PersistedCodexRuntimeState>;
if (raw.version !== 1 || typeof raw.command !== "string" || !raw.command.trim()) return null;
if (!isCodexRuntimeSource(raw.source) || typeof raw.updatedAt !== "string") return null;
if (raw.selectedVersion !== undefined
&& raw.selectedVersion !== null
&& typeof raw.selectedVersion !== "string") return null;
// Absent origin is legal (pre-field files). A present value that is neither
// literal makes the whole record invalid, same as every other field.
if (raw.origin !== undefined && !isCodexRuntimePinOrigin(raw.origin)) return null;
return cloneAndDeepFreeze(raw as PersistedCodexRuntimeState);
} catch {
return null;
}
}
export function loadPersistedCodexRuntime(
deps: ResolveCodexRuntimeDeps = {},
): DeepReadonly<PersistedCodexRuntimeState> | null {
const configDir = deps.configDir ?? getConfigDir();
const read = deps.readFileSync ?? ((path, encoding) => readFileSync(path, encoding));
try {
return parsePersistedCodexRuntime(read(codexRuntimeStatePath(configDir), "utf8"));
} catch {
return null;
}
}
/**
* True only when the operator intentionally pinned this runtime.
*
* A record with no origin is NOT pinned: every such file predates this field
* and was written by resolveAndPersistCodexRuntime, which is auto-discovery.
* Reading a missing origin as an intentional pin would leave issue 4204
* unfixed on exactly the installs that have it — the still-runnable 0.135.0
* CLI that kept winning over a 0.153.4 Desktop runtime sitting right there.
*/
export function persistedCodexRuntimeIsPinned(
state: DeepReadonly<PersistedCodexRuntimeState> | null | undefined,
): boolean {
return state?.origin === "pinned";
}
/**
* Persist the selected Codex runtime.
*
* `origin` defaults to "pinned" ON PURPOSE: a direct call is a deliberate
* selection. src/cli/doctor.ts calls this from `doctor --fix`. The automatic
* discovery path is resolveAndPersistCodexRuntime, which passes "discovered"
* explicitly. Flipping the default would make doctor --fix look like an
* accident, and a later resolve would silently replace the operator's choice
* (issue 4204).
*/
export function persistCodexRuntime(
runtime: ResolvedCodexRuntime,
deps: ResolveCodexRuntimeDeps = {},
origin: CodexRuntimePinOrigin = "pinned",
): void {
const configDir = deps.configDir ?? getConfigDir();
mkdirSync(configDir, { recursive: true, mode: 0o700 });
const payload: PersistedCodexRuntimeState = {
version: 1,
command: runtime.command,
source: runtime.source,
selectedVersion: runtime.version,
updatedAt: new Date((deps.now ?? Date.now)()).toISOString(),
origin,
};
// Invalidate process authority before the persisted replacement is visible.
clearCodexRuntimeResolveCache();
atomicWriteFile(codexRuntimeStatePath(configDir), `${JSON.stringify(payload, null, 2)}\n`);
}
/**
* Delete `codex-runtime.json`. Used to retire a pin whose path no longer exists, so a
* later resolve stops re-probing it (#4035).
*
* Invalidates the process resolve memo the same way `persistCodexRuntime` does: the memo
* folds the persisted `updatedAt` into its key, and a removed file has no stamp to fold.
*/
export function clearPersistedCodexRuntime(deps: ResolveCodexRuntimeDeps = {}): void {
const configDir = deps.configDir ?? getConfigDir();
clearCodexRuntimeResolveCache();
try {
unlinkSync(codexRuntimeStatePath(configDir));
} catch (error) {
// An already-missing file is the success case: the pin is gone, which is the point.
// Anything else means the pin SURVIVES and stays authoritative, so every later
// resolve re-probes the same dead path — #4035 unfixed, silently. Say so once.
const code = (error as NodeJS.ErrnoException | null)?.code;
if (code === "ENOENT") return;
console.warn(
`[opencodex] Could not remove the stale Codex runtime pin at ${displayCodexRuntimePath(codexRuntimeStatePath(configDir))}`
+ ` (${code ?? "unknown error"}). It will be re-probed until the file is removed.`,
);
}
}
type VersionProbeResult = { ok: true; version: string | null } | { ok: false; reason: string };
/** Checks that need no exec; a non-null answer settles the candidate without running `--version`. */
function versionProbePrecheck(command: string, deps: ResolveCodexRuntimeDeps): VersionProbeResult | null {
const platform = deps.platform ?? process.platform;
if (command.includes("/") || command.includes("\\") || /^[A-Za-z]:/.test(command)) {
const exists = deps.existsSync ?? existsSync;
if (!exists(command)) return { ok: false, reason: PATH_MISSING_REASON };
if (!isSpawnableCodexCandidate(command, platform)) {
return { ok: false, reason: "not a spawnable Codex launcher on this platform" };
}
}
// The prompt probe needs a spawnable candidate, not a version. Running
// `codex --version` here is ~1s of blocking exec per candidate; on the
// dashboard probe that cost made Windows report Codex as missing even when
// the App install was sitting under LOCALAPPDATA/OpenAI/Codex/bin (issue 4458).
if (deps.probeVersion === false) return { ok: true, version: null };
return null;
}
function versionProbeInvocation(command: string, deps: ResolveCodexRuntimeDeps, probeHome: string) {
const invocation = codexExecInvocation(command, ["--version"], deps.platform ?? process.platform, {
env: deps.env,
exists: deps.existsSync,
});
return {
file: invocation.file,
args: invocation.args,
options: {
encoding: "utf8" as const,
stdio: ["ignore", "pipe", "ignore"] as ["ignore", "pipe", "ignore"],
timeout: 8_000,
windowsHide: true,
env: { ...(deps.env ?? process.env), CODEX_HOME: probeHome },
...invocation.options,
},
};
}
function versionProbeOutput(output: string): VersionProbeResult {
const version = parseCodexVersionOutput(output);
if (!version) return { ok: false, reason: "unrecognized --version output" };
return { ok: true, version };
}
function versionProbeError(error: unknown, probeHome: string | undefined): VersionProbeResult {
if (!probeHome) return { ok: false, reason: "probe sandbox unavailable" };
if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
return { ok: false, reason: CODEX_PROGRAM_NOT_FOUND_REASON };
}
const message = error instanceof Error ? error.message : String(error);
const redacted = redactUserPath(redactSecretString(message)).slice(0, 160);
return { ok: false, reason: `failed --version (${redacted})` };
}
function removeProbeHome(probeHome: string | undefined): void {
if (!probeHome) return;
// Nested catch: a transient Windows EBUSY must never mask the probe result.
try { rmSync(probeHome, { recursive: true, force: true }); } catch { /* best effort */ }
}
function probeVersion(command: string, deps: ResolveCodexRuntimeDeps): VersionProbeResult {
const settled = versionProbePrecheck(command, deps);
if (settled) return settled;
const exec = deps.execFileSync ?? (execFileSync as unknown as RuntimeExecFile);
// Sandbox the probe's CODEX_HOME: a real Codex CLI creates state (tmp/, logs) under
// CODEX_HOME even for `--version`, and the probe inherits the caller's env — so a
// read-only `ocx status` would dirty the user's CODEX_HOME. Redirect it to a
// throwaway dir; if the sandbox cannot be created, skip the probe rather than
// probe with the inherited env (keeps probeVersion total: it never throws).
let probeHome: string | undefined;
try {
probeHome = mkdtempSync(join(tmpdir(), "ocx-codex-probe-"));
const { file, args, options } = versionProbeInvocation(command, deps, probeHome);
return versionProbeOutput(exec(file, args, options));
} catch (error) {
return versionProbeError(error, probeHome);
} finally {
removeProbeHome(probeHome);
}
}
const defaultExecFileAsync: RuntimeExecFileAsync = (file, args, options) =>
new Promise((resolve, reject) => {
// execFile always pipes stdout/stderr; it takes no stdio option.
const { stdio: _stdio, ...execOptions } = options;
execFile(file, args, execOptions, (error, stdout) => (error ? reject(error) : resolve(String(stdout))));
});
/** probeVersion with the same sandbox and outcomes, but the exec never holds the event loop. */
async function probeVersionAsync(command: string, deps: ResolveCodexRuntimeDeps): Promise<VersionProbeResult> {
const settled = versionProbePrecheck(command, deps);
if (settled) return settled;
const exec = deps.execFile ?? defaultExecFileAsync;
let probeHome: string | undefined;
try {
probeHome = mkdtempSync(join(tmpdir(), "ocx-codex-probe-"));
const { file, args, options } = versionProbeInvocation(command, deps, probeHome);
return versionProbeOutput(await exec(file, args, options));
} catch (error) {
return versionProbeError(error, probeHome);
} finally {
removeProbeHome(probeHome);
}
}
function shimCandidates(deps: ResolveCodexRuntimeDeps): string[] {
const configDir = deps.configDir ?? getConfigDir();
const read = deps.readFileSync ?? ((path, encoding) => readFileSync(path, encoding));
const platform = deps.platform ?? process.platform;
try {
const state = JSON.parse(read(join(configDir, "codex-shim.json"), "utf8")) as {
wrapperPath?: unknown;
originalPath?: unknown;
backupPath?: unknown;
wrappers?: Array<{ wrapperPath?: unknown; originalPath?: unknown; backupPath?: unknown }>;
};
const files = Array.isArray(state.wrappers) && state.wrappers.length > 0 ? state.wrappers : [state];
const out: string[] = [];
for (const file of files) {
for (const value of [file.backupPath, file.originalPath, file.wrapperPath]) {
if (typeof value !== "string" || value.length === 0) continue;
if (!isSpawnableCodexCandidate(value, platform)) continue;
out.push(value);
}
}
return [...new Set(out)];
} catch {
return [];
}
}
function pathCandidates(deps: ResolveCodexRuntimeDeps): string[] {
const env = deps.env ?? process.env;
const platform = deps.platform ?? process.platform;
const out: string[] = [];
for (const dir of (env.PATH ?? "").split(delimiter).filter(Boolean)) {
if (platform === "win32") {
out.push(join(dir, "codex.exe"), join(dir, "codex.cmd"));
} else {
out.push(join(dir, "codex"));
}
}
return [...new Set(out)];
}
/**
* Codex installs that PATH does not necessarily expose.
*
* The Windows Codex App writes codex.exe under
* LOCALAPPDATA/OpenAI/Codex/bin/<changing-version>/, which never appears on
* the service process PATH. The prompt probe used to hardcode four POSIX
* paths and miss that layout, then report an absent candidate (issue 4458).
* POSIX keeps those four paths so an install that resolved before this source
* existed still resolves.
*/
function installedCodexCandidates(deps: ResolveCodexRuntimeDeps): string[] {
const platform = deps.platform ?? process.platform;
const env = deps.env ?? process.env;
const readDir = deps.readdirSync ?? ((path: string) => readdirSync(path));
const stat = deps.statSync ?? ((path: string) => statSync(path));
/** Version directories directly under root, newest first; unreadable roots yield nothing. */
const versionDirectories = (root: string): string[] => {
try {
const dirs: Array<{ name: string; directory: string; mtimeMs: number }> = [];
for (const name of readDir(root)) {
const directory = join(root, name);
try {
const st = stat(directory);
if (!st.isDirectory()) continue;
dirs.push({ name, directory, mtimeMs: st.mtimeMs });
} catch {
continue;
}
}
dirs.sort((a, b) => b.mtimeMs - a.mtimeMs || a.name.localeCompare(b.name));
return dirs.map(entry => entry.directory);
} catch {
return [];
}
};
if (platform === "win32") {
const localAppData = env.LOCALAPPDATA?.trim();
if (!localAppData) return [];
return versionDirectories(join(localAppData, "OpenAI", "Codex", "bin"))
.map(directory => join(directory, "codex.exe"));
}
const home = env.HOME?.trim() || env.USERPROFILE?.trim() || homedir();
const posix = [
join(home, ".codex", "packages", "standalone", "current", "bin", "codex"),
join(home, ".local", "bin", "codex"),
"/usr/local/bin/codex",
"/opt/homebrew/bin/codex",
];
if (platform !== "linux") return posix;
// Windows Codex Desktop in WSL app-server mode ships its Linux binary under the
// effective Codex home as bin/wsl/<version-hash>/codex, and a Desktop update replaces
// that hash directory. The service PATH usually has no codex (issue 5635), so these
// rank after PATH and the ordinary locations and are re-enumerated on every resolve
// rather than trusted from a remembered hash.
let codexHome: string;
try {
codexHome = resolveCodexHomeDir({ env });
} catch {
return posix;
}
const desktopWsl = versionDirectories(join(codexHome, "bin", "wsl"))
.map(directory => join(directory, "codex"));
return [...posix, ...desktopWsl];
}
interface RankedCandidate {
command: string;
source: CodexRuntimeSource;
}
function sameRuntimeCommand(a: string, b: string): boolean {
return a.trim().toLowerCase() === b.trim().toLowerCase();
}
/**
* Rungs OpenCodex no longer lets the observed-runtime intersection remove, so a persisted
* diagnostic naming only these describes a policy that is gone rather than a live restriction.
* This is the single copy of the exemption: `catalog/effort.ts` imports it for the clamp
* predicate, and a leftover file written before the exemption must not keep warning about
* rungs the next sync will stop removing.
*/
export const UNCLAMPABLE_REASONING_EFFORTS: ReadonlySet<string> = new Set(["max", "ultra"]);
/** Removals that still describe a real restriction, ignoring rungs nothing clamps any more. */
export function liveRemovedEfforts(
diagnostic: EffortClampDiagnostic | null | undefined,
): readonly string[] {
if (!diagnostic) return [];
return diagnostic.removedEfforts.filter(effort => !UNCLAMPABLE_REASONING_EFFORTS.has(effort));
}
/**
* True when a persisted clamp diagnostic still applies to the currently selected runtime.
*
* Two ways a stored diagnostic stops describing reality:
*
* 1. Every rung it names is one nothing clamps any more, so the file is inert until the next
* sync unlinks it.
* 2. The binary at that path was upgraded in place. Windows updates Codex without moving the
* executable, so path equality alone kept a 0.135.0 observation "current" for a 0.154.0
* runtime whose own bundled catalog carried the rungs the diagnostic claimed were missing.
* A known version mismatch therefore wins over a path match; an unknown version on either
* side stays conservative, because absence of a version is not evidence of an upgrade.
*/
export function effortClampAppliesToRuntime(
diagnostic: EffortClampDiagnostic | null | undefined,
runtime: Pick<ResolvedCodexRuntime, "command" | "version">,
): boolean {
if (!diagnostic || liveRemovedEfforts(diagnostic).length === 0) return false;
if (sameRuntimeCommand(diagnostic.runtimePath, runtime.command)) {
if (diagnostic.runtimeVersion && runtime.version) {
return diagnostic.runtimeVersion === runtime.version;
}
return true;
}
return Boolean(
diagnostic.runtimeVersion
&& runtime.version
&& diagnostic.runtimeVersion === runtime.version,
);
}
const RESOLVE_CACHE_MS = 15_000;
interface ResolveCacheMemo {
readonly key: string;
readonly at: number;
readonly epoch: number;
readonly valueIdentity: string;
readonly value: DeepReadonly<ResolveCodexRuntimeResult>;
}
export type CodexRuntimeProcessCachePeek =
| Readonly<{
kind: "available";
epoch: number;
valueIdentity: string;
value: DeepReadonly<ResolveCodexRuntimeResult>;
}>
| Readonly<{ kind: "unavailable"; epoch: number }>;
let resolveCacheEpoch = 0;
let resolveCache: ResolveCacheMemo | null = null;
/**
* Memo for probeVersion === false resolves. Kept separate from resolveCache
* because peekCodexRuntimeProcessCache is read by convergence and the bundled
* catalog as "what runtime are we on". Publishing a null version there would
* be read as "unknown version" and become process authority (issue 4458).
*/
interface DeferredResolveCacheMemo {
readonly key: string;
readonly at: number;
readonly value: DeepReadonly<ResolveCodexRuntimeResult>;
}
let deferredResolveCache: DeferredResolveCacheMemo | null = null;
/**
* Bumped whenever persisted runtime state is replaced or process authority is cleared.
*
* Consumers that memoize anything derived from `codex-runtime.json` — entitlement's client
* version, for one — read this instead of a timestamp, so a runtime switch invalidates them at
* the moment of the write rather than after a delay window. Exposed because the alternative was
* a time-based guess that could answer under the previous version after the file had changed.
*/
export function codexRuntimeStateEpoch(): number {
return resolveCacheEpoch;
}
function publishResolveCache(key: string, at: number, value: ResolveCodexRuntimeResult): void {
const epoch = ++resolveCacheEpoch;
resolveCache = {
key,
at,
epoch,
valueIdentity: `runtime:${epoch}`,
value: cloneAndDeepFreeze(value),
};
}
function clearResolveCache(): void {
resolveCacheEpoch += 1;
resolveCache = null;
deferredResolveCache = null;
}
/** Clear process-local runtime authority without resolving a replacement. */
export function clearCodexRuntimeResolveCache(): void {
clearResolveCache();
}
/**
* Observe the successful process memo; never resolves or probes.
*
* An expired memo stays observable while an async refresh for the same inputs is in flight
* and nothing has invalidated it since. The sync resolver used to hold the event loop for the
* whole probe, so nothing could read in that window; with the refresh off the loop, dropping
* the memo there would send catalog gather to the persisted runtime (or none) and have
* convergence reject its process-local candidate every expiry. A published result or a clear
* still retires it; the deferred selection never enters this memo (#4458).
*/
export function peekCodexRuntimeProcessCache(): CodexRuntimeProcessCachePeek {
const memo = resolveCache;
const refreshing = memo !== null
&& asyncResolveInflight !== null
&& asyncResolveInflight.key === memo.key
&& asyncResolveInflight.epoch === resolveCacheEpoch
// An expired memo only stands in for a refresh of the same selection; an out-of-process
// runtime switch changes the key without bumping the epoch.
&& resolveCacheKey({}) === memo.key;
if (!memo || (Date.now() - memo.at >= RESOLVE_CACHE_MS && !refreshing)) {
return Object.freeze({ kind: "unavailable" as const, epoch: resolveCacheEpoch });
}
return Object.freeze({
kind: "available" as const,
epoch: memo.epoch,
valueIdentity: memo.valueIdentity,
value: cloneAndDeepFreeze(memo.value),
});
}
function persistedRuntimeCacheStamp(deps: ResolveCodexRuntimeDeps): string {
// Include on-disk selection so doctor --fix in another process busts this memo.
const configDir = deps.configDir ?? getConfigDir();
const read = deps.readFileSync ?? ((path, encoding) => readFileSync(path, encoding));
try {
const raw = parsePersistedCodexRuntime(read(codexRuntimeStatePath(configDir), "utf8"));
if (!raw) return "";
return `${raw.command}|${raw.selectedVersion ?? ""}|${raw.updatedAt ?? ""}`;
} catch {
return "";
}
}
function resolveCacheKey(deps: ResolveCodexRuntimeDeps): string | null {
// Only memoize uninjected process-env resolves (settings/status hot paths).
if (
deps.execFileSync
|| deps.execFile
|| deps.existsSync
|| deps.readFileSync
|| deps.readdirSync
|| deps.statSync
|| deps.configDir
|| deps.now
) {
return null;
}
const env = deps.env ?? process.env;
return JSON.stringify({
cli: env.CODEX_CLI_PATH ?? "",
path: env.PATH ?? "",
platform: deps.platform ?? process.platform,
discover: deps.discoverAlternatives !== false,
probeVersion: deps.probeVersion !== false,
localAppData: env.LOCALAPPDATA?.trim() ?? "",
homeDir: env.HOME?.trim() ?? "",
userProfile: env.USERPROFILE?.trim() ?? "",
// Linux discovery enumerates <CODEX_HOME>/bin/wsl, so the home is part of the key.
codexHome: env.CODEX_HOME?.trim() ?? "",
home: process.env.OPENCODEX_HOME ?? "",
persisted: persistedRuntimeCacheStamp(deps),
});
}
/**
* Resolve the single Codex runtime OpenCodex should use for sync, clamp, and probes.
*/
export function resolveCodexRuntime(deps: ResolveCodexRuntimeDeps = {}): ResolveCodexRuntimeResult {
const cacheKey = resolveCacheKey(deps);
// A deferred selection has no validated version and must not publish into
// runtime authority. peekCodexRuntimeProcessCache would otherwise report
// "available" with version null, which catalog/convergence read as unknown.
if (deps.probeVersion === false) {
if (cacheKey
&& deferredResolveCache
&& deferredResolveCache.key === cacheKey
&& Date.now() - deferredResolveCache.at < RESOLVE_CACHE_MS) {
return cloneAndDeepFreeze(deferredResolveCache.value);
}
const deferred = resolveCodexRuntimeUncached(deps);
if (!cacheKey) return cloneAndDeepFreeze(deferred);
deferredResolveCache = {
key: cacheKey,
at: Date.now(),
value: cloneAndDeepFreeze(deferred),
};
return cloneAndDeepFreeze(deferredResolveCache.value);
}
if (cacheKey && resolveCache && resolveCache.key === cacheKey && Date.now() - resolveCache.at < RESOLVE_CACHE_MS) {
return cloneAndDeepFreeze(resolveCache.value);
}
const result = resolveCodexRuntimeUncached(deps);
if (cacheKey) {
publishResolveCache(cacheKey, Date.now(), result);
return cloneAndDeepFreeze(resolveCache!.value);
}
return cloneAndDeepFreeze(result);
}
let asyncResolveInflight: { key: string; epoch: number; promise: Promise<ResolveCodexRuntimeResult> } | null = null;
/**
* resolveCodexRuntime for server request paths: same selection and process memo, but every
* `codex --version` runs through async exec. The sync resolver blocked the whole proxy for
* ~0.6s per memo expiry while the dashboard polled settings, stalling unrelated requests.
*/
export async function resolveCodexRuntimeAsync(
deps: ResolveCodexRuntimeDeps = {},
): Promise<ResolveCodexRuntimeResult> {
// A deferred selection never execs, so the sync path is already nonblocking.
if (deps.probeVersion === false) return resolveCodexRuntime(deps);
const cacheKey = resolveCacheKey(deps);
if (cacheKey && resolveCache && resolveCache.key === cacheKey && Date.now() - resolveCache.at < RESOLVE_CACHE_MS) {
return cloneAndDeepFreeze(resolveCache.value);
}
if (!cacheKey) return cloneAndDeepFreeze(await resolveCodexRuntimeUncachedAsync(deps));
const startedEpoch = resolveCacheEpoch;
if (asyncResolveInflight?.key === cacheKey && asyncResolveInflight.epoch === startedEpoch) {
return cloneAndDeepFreeze(await asyncResolveInflight.promise);
}
const promise = resolveCodexRuntimeUncachedAsync(deps).then(result => {
// A persist or clear while the probes ran makes this answer the previous selection's;
// publishing it would resurrect authority the write just revoked. Another process can also
// rewrite codex-runtime.json without touching this epoch, so the key is read again too.
if (resolveCacheEpoch === startedEpoch && resolveCacheKey(deps) === cacheKey) {
publishResolveCache(cacheKey, Date.now(), result);
}
return result;
}).finally(() => {
if (asyncResolveInflight?.promise === promise) asyncResolveInflight = null;
});
asyncResolveInflight = { key: cacheKey, epoch: startedEpoch, promise };
return cloneAndDeepFreeze(await promise);
}
/**
* Stale-while-revalidate runtime read for hot UI paths; never waits on a probe.
*
* Returns the process memo when fresh, otherwise the last memo for the same inputs, and kicks
* resolveCodexRuntimeAsync to refresh it. With no memo yet (cold start, or right after a runtime
* switch cleared it) the answer is the exec-free deferred selection, so a version and
* newerAvailable appear once the first background refresh lands.
*/
export function getCodexRuntimeSnapshot(): ResolveCodexRuntimeResult {
const cacheKey = resolveCacheKey({});
const memo = resolveCache?.key === cacheKey ? resolveCache : null;
if (memo && Date.now() - memo.at < RESOLVE_CACHE_MS) return cloneAndDeepFreeze(memo.value);
resolveCodexRuntimeAsync().catch(() => { /* the next read retries */ });
if (memo) return cloneAndDeepFreeze(memo.value);
return resolveCodexRuntime({ discoverAlternatives: false, probeVersion: false });
}
/** Test-only: drop the short-lived process resolve cache. */
export function resetCodexRuntimeResolveCacheForTests(): void {
clearCodexRuntimeResolveCache();
}
/** Test-only owner mutation seam; input is cloned and frozen before publication. */
export function setCodexRuntimeResolveCacheForTests(
value: ResolveCodexRuntimeResult,
deps: ResolveCodexRuntimeDeps = {},
): void {
const key = resolveCacheKey(deps);
if (!key) throw new TypeError("Injected runtime dependencies cannot populate the process memo.");
publishResolveCache(key, Date.now(), value);
}
/**
* Candidate ranking and selection, written once for both drivers: each yield hands a candidate to
* the caller, which sends back its `--version` outcome. The sync driver keeps CLI behavior; the
* async one lets a server path resolve without blocking every other request on the probes.
*/
function* resolveCodexRuntimeSteps(
deps: ResolveCodexRuntimeDeps,
): Generator<RankedCandidate, ResolveCodexRuntimeResult, VersionProbeResult> {
const env = deps.env ?? process.env;
const failures: RuntimeProbeFailure[] = [];
const ordered: RankedCandidate[] = [];
const envPath = env.CODEX_CLI_PATH?.trim();
if (envPath) ordered.push({ command: envPath, source: "environment" });
const persisted = loadPersistedCodexRuntime(deps);
if (persisted?.command) {
ordered.push({ command: persisted.command, source: "configured" });
}
for (const command of shimCandidates(deps)) {
ordered.push({ command, source: "shim" });
}
for (const command of pathCandidates(deps)) {
ordered.push({ command, source: "path" });
}
for (const command of installedCodexCandidates(deps)) {
ordered.push({ command, source: "installed" });
}
ordered.push({ command: "codex", source: "fallback" });
const seen = new Set<string>();
const valid: ResolvedCodexRuntime[] = [];
// A caller that declined PATH-wide discovery normally gets the first valid
// candidate and nothing else, which is right for a hot path and wrong for
// exactly one arrangement: an unpinned persisted selection sitting in front of
// a Codex App runtime that PATH never exposes.
//
// That arrangement is issue 4204. The catalog's bundled loader passes
// discoverAlternatives: false, so it stopped at a still-runnable codex-cli
// 0.135.0 and derived the reasoning ladder from it while the Desktop app was
// running 0.153.4 out of LOCALAPPDATA. Nothing downstream could notice,
// because the newer runtime was never probed.
//
// So the early stop keeps skipping PATH — which is the expensive part, 100+
// launcher probes on a dev machine — but still probes the `installed` roots,
// a bounded set with one entry per Codex App version directory. A pinned
// record skips even that: the operator's choice is not up for revision, and
// there is then nothing to compare it against.
const persistedIsUnpinned = Boolean(persisted?.command) && !persistedCodexRuntimeIsPinned(persisted);
for (const candidate of ordered) {
const key = candidate.command.toLowerCase();
if (seen.has(key)) continue;
seen.add(key);
if (
deps.discoverAlternatives === false
&& valid.length > 0
&& !(persistedIsUnpinned && candidate.source === "installed")
) {
continue;
}
const probed: VersionProbeResult = yield candidate;
if (!probed.ok) {
failures.push({ command: candidate.command, source: candidate.source, reason: probed.reason });
continue;
}
valid.push({ command: candidate.command, version: probed.version, source: candidate.source });
}
if (valid.length === 0) {
return {
runtime: { command: "codex", version: null, source: "fallback" },
failures,
};
}
// Prefer first valid in priority order (environment → configured → shim → path → installed → fallback).
let selected = valid[0]!;
let replacedConfigured: ResolveCodexRuntimeResult["replacedConfigured"];
let supersededDiscovered: ResolveCodexRuntimeResult["supersededDiscovered"];
const envValid = envPath
? valid.find(item => sameRuntimeCommand(item.command, envPath) && item.source === "environment")
: undefined;
if (envValid) selected = envValid;
if (persisted?.command) {
const configuredStillValid = valid.some(item => sameRuntimeCommand(item.command, persisted.command));
// Only emit replacement diagnostics when we actually searched alternatives or
// the preferred configured runtime was probed and rejected.
const configuredRejected = failures.some(item => sameRuntimeCommand(item.command, persisted.command));
if (!configuredStillValid && (configuredRejected || deps.discoverAlternatives !== false) && !envValid) {
replacedConfigured = {
from: {
command: persisted.command,
version: persisted.selectedVersion ?? null,
source: "configured",
},
reason: failures.find(item => sameRuntimeCommand(item.command, persisted.command))?.reason
?? "configured runtime is no longer valid",
};
// Keep priority-selected replacement (already in `selected`).
} else if (!envValid && configuredStillValid) {
// Stick to configured even when a later PATH entry is also valid.
selected = valid.find(item => sameRuntimeCommand(item.command, persisted.command)) ?? selected;
// An explicit pin is the user's decision and this change must never
// silently replace it — issue 4204 says so in as many words. Stick.
// An unpinned record (missing origin, or origin "discovered") may hand
// over to a strictly newer valid candidate. Unknown (null) versions on
// either side are not evidence of an upgrade: compareCodexVersions treats
// null as less-than, which would otherwise make any known alternative
// look newer than a deferred probe. probeVersion === false yields null
// everywhere, so the comparison cannot fire there; equal versions stick.
if (!persistedCodexRuntimeIsPinned(persisted)) {
const newerDiscovered = valid
.filter(item =>
!sameRuntimeCommand(item.command, selected.command)
&& typeof item.version === "string"
&& typeof selected.version === "string"
&& compareCodexVersions(item.version, selected.version) > 0)
.sort((a, b) => compareCodexVersions(b.version, a.version))[0];
if (newerDiscovered) {
supersededDiscovered = {
from: selected,
to: newerDiscovered,
reason: `discovered runtime ${selected.version} superseded by newer runtime ${newerDiscovered.version}`,
};
selected = newerDiscovered;
}
}
}
}
const newerAvailable = valid
.filter(item => !sameRuntimeCommand(item.command, selected.command))
.sort((a, b) => compareCodexVersions(b.version, a.version))[0];
const newer =
newerAvailable && compareCodexVersions(newerAvailable.version, selected.version) > 0
? newerAvailable
: undefined;
return {
runtime: selected,
failures,
replacedConfigured,
supersededDiscovered,
newerAvailable: newer,
};
}
function resolveCodexRuntimeUncached(deps: ResolveCodexRuntimeDeps = {}): ResolveCodexRuntimeResult {
const steps = resolveCodexRuntimeSteps(deps);
let step = steps.next();
while (!step.done) step = steps.next(probeVersion(step.value.command, deps));
return step.value;
}
async function resolveCodexRuntimeUncachedAsync(deps: ResolveCodexRuntimeDeps): Promise<ResolveCodexRuntimeResult> {
const steps = resolveCodexRuntimeSteps(deps);
let step = steps.next();
while (!step.done) step = steps.next(await probeVersionAsync(step.value.command, deps));
return step.value;
}
/** Resolve and persist a successful selection (unless source is ephemeral fallback-only with no path). */
export function resolveAndPersistCodexRuntime(
deps: ResolveCodexRuntimeDeps = {},
): ResolveCodexRuntimeResult {
const result = resolveCodexRuntime(deps);
// Only WRITE when the selection actually changed. persistCodexRuntime() clears the
// in-process resolve memo and persistedRuntimeCacheStamp() folds `updatedAt` into the
// cache key, so an unconditional rewrite made every caller re-run the ~1s
// `codex --version` probe even when the resolved runtime was byte-identical.
const persistedRuntime = loadPersistedCodexRuntime(deps);
const selectionUnchanged = persistedRuntime !== null
&& persistedRuntime.command === result.runtime.command
&& persistedRuntime.source === result.runtime.source
&& (persistedRuntime.selectedVersion ?? null) === (result.runtime.version ?? null);
if (result.runtime.command && result.runtime.source !== "fallback" && !selectionUnchanged) {
try {
persistCodexRuntime(result.runtime, deps, "discovered");
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
const persistError = redactUserPath(redactSecretString(message)).slice(0, 200);
console.warn(`[opencodex] Failed to persist Codex runtime selection: ${persistError}`);
return cloneAndDeepFreeze({ ...result, persistError });
}
}
// A pin whose path has vanished must be RETIRED, not merely skipped. A Codex App update
// replaces the hashed plugin directory the pin names, the probe rejects it with
// "path does not exist", nothing else resolves, and the selection degrades to `fallback` —
// which the write guard above declines. The dead entry then survived every later resolve
// and each one re-probed a path that cannot exist (#4035). Bound narrowly: only when the
// degraded result is `fallback`, only for the persisted command, and only for the
// path-does-not-exist rejection, so a present-but-unusable binary is left for the operator.
else if (result.runtime.source === "fallback" && persistedRuntime?.command) {
const pinVanished = result.failures.some(
// Exact comparison, not `sameRuntimeCommand`: that helper lowercases, and on a
// case-sensitive filesystem `/plugins/Codex` and `/plugins/codex` are different
// files. A missing lowercase path must not retire a live uppercase pin.
failure => failure.command.trim() === persistedRuntime.command.trim()
&& failure.reason === PATH_MISSING_REASON,
);
if (pinVanished) clearPersistedCodexRuntime(deps);
}
return result;
}
export function formatRuntimeLogLine(runtime: ResolvedCodexRuntime): string {
const path = displayCodexRuntimePath(runtime.command);
return `[opencodex] Codex runtime: ${path} (version=${runtime.version ?? "unknown"}, source=${runtime.source})`;
}
export function formatClampLogLines(diagnostic: EffortClampDiagnostic): string[] {
const efforts = diagnostic.removedEfforts.join(", ");
return [
`[opencodex] Removed unsupported reasoning efforts: ${efforts}`,
"[opencodex] Run ocx doctor for diagnosis and recovery.",
];
}