UNPKG

@bitkyc08/opencodex

Version:

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

791 lines (742 loc) • 33.3 kB
import { execFileSync } from "node:child_process"; import { createHash } from "node:crypto"; import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs"; import { delimiter, dirname, join, resolve } from "node:path"; import { atomicWriteFile, expandUserPath, getConfigDir, websocketsEnabled } from "../../config"; import { CODEX_CONFIG_PATH, CODEX_MODELS_CACHE_PATH, DEFAULT_CATALOG_PATH, readRootTomlString, resolveCodexConfigPath } from "../paths"; import { clearModelCache, DEFAULT_MODEL_CACHE_TTL_MS, getFreshCached, getStaleCached, isModelsFetchCoolingDown, markModelsFetchFailure, setCached } from "../model-cache"; import { buildModelsRequest, resolveModelsAuthToken } from "../../oauth"; import type { OcxConfig, OcxProviderConfig } from "../../types"; import { modelInList } from "../../types"; import { CODEX_REASONING_LEVELS, codexEffortRank, configuredReasoningEfforts, modelRecordValue, sanitizeCodexReasoningEfforts } from "../../reasoning-effort"; import { getModelMetadata, getModelMetadataCaseInsensitive, listModelMetadata, resolveMetadataProvider } from "../../generated/model-metadata"; import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../../providers/derive"; import { getProviderRegistryEntry } from "../../providers/registry"; import { applyProviderContextCap, providerContextCap } from "../../providers/context-cap"; import { routedSlug, slugEquals, slugsEquivalent } from "../../providers/slug-codec"; import { CODEX_GPT5_IDENTITY_LINE } from "../../adapters/identity"; import { filterCursorConfiguredModelsByLiveDiscovery } from "../../adapters/cursor/discovery"; import { fetchCursorUsableModels } from "../../adapters/cursor/live-models"; import { isCanonicalOpenAiForwardProvider, OPENAI_API_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers"; import { COMBO_NAMESPACE, comboModelId, getCombo, listComboIds, targetKey, } from "../../combos"; import type { NormalizedComboConfig } from "../../combos/types"; import { providerDestinationResolvedError } from "../../lib/destination-policy"; import { redactSecretString } from "../../lib/redact"; import { isPassiveRead } from "../../lib/passive-read"; import upstreamModelsSnapshot from "../data/upstream-models.json"; import { decodeOverlayState } from "../shim-state-file"; import { activeCodexModelsCachePath, catalogBackupPathFor, ensureStrictCatalogFields, findNativeTemplate, findSupportedNativeTemplate, isDefaultCatalogPath, legacyCatalogBackupPath, parseCatalogJson, readCatalog, readCatalogBackup, readCodexCatalogPath } from "./parsing"; import { retainedNativeInheritanceTemplate } from "./native-template"; import type { RawCatalog, RawEntry } from "./parsing"; import { isSpawnableCodexCandidate } from "../exec-invocation"; import { validatedCodexExecInvocation, validatedCodexExecInvocationAsync } from "../exec-boundary"; import { macCodexAppCommands } from "../mac-app-bundle"; import { isPlainObject } from "../../lib/plain-data"; import { parsePersistedCodexRuntime, peekCodexRuntimeProcessCache, resolveAndPersistCodexRuntime, resolveAndPersistCodexRuntimeAsync, codexRuntimeSelectionIdentity, codexRuntimeStateEpoch, execCodexFileAsync, codexRuntimeIsUnresolved, } from "../runtime"; import type { DeepReadonly, EffortClampDiagnostic, ResolveCodexRuntimeResult, ResolvedCodexRuntime, } from "../runtime"; import type { CatalogGatherEvidenceSession, CatalogGatherReadableSourceRole, } from "./filesystem-evidence"; export { isSpawnableCodexCandidate, codexExecInvocation } from "../exec-invocation"; export type { CatalogGatherEvidenceSession, CatalogGatherReadableSourceRole, } from "./filesystem-evidence"; export const BUNDLED_CATALOG_CACHE_MS = 60_000; export type ReadonlyRawCatalog = DeepReadonly<RawCatalog>; interface BundledCatalogMemo { /** Selected runtime identity; must change when doctor/sync picks a different binary. */ readonly key: string; readonly inputs: string; readonly expiresAt: number; readonly refreshAt: number; readonly epoch: number; readonly valueIdentity: string; readonly value: ReadonlyRawCatalog | null; } export interface BundledCatalogCacheState { readonly epoch: number; readonly valueIdentity: string | null; } let bundledCatalogEpoch = 0; let bundledCatalogCache: BundledCatalogMemo | null = null; let bundledCatalogRetry: { inputs: string; epoch: number; after: number } | null = null; let bundledCatalogFlight: { inputs: string; epoch: number; controller: AbortController; promise: Promise<ReadonlyRawCatalog | null> } | null = null; const catalogAlwaysCurrent = () => true; 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 bundledRuntimeKey( runtime: Pick<ResolvedCodexRuntime, "command" | "version">, opencodexHome: string = process.env.OPENCODEX_HOME ?? "", ): string { return [runtime.command, runtime.version ?? "", opencodexHome].join("\0"); } function publishBundledCatalogCache( key: string, expiresAt: number, value: RawCatalog | null, ): void { const epoch = ++bundledCatalogEpoch; bundledCatalogCache = { key, inputs: codexRuntimeSelectionIdentity({ discoverAlternatives: false }), expiresAt, refreshAt: Math.min(expiresAt, Date.now() + 15_000), epoch, valueIdentity: `bundled:${epoch}`, value: value === null ? null : cloneAndDeepFreeze(value), }; bundledCatalogRetry = null; } function clearBundledCatalogCache(): void { bundledCatalogFlight?.controller.abort(); bundledCatalogEpoch += 1; bundledCatalogCache = null; } export function bundledCatalogCacheState(): Readonly<BundledCatalogCacheState> { return Object.freeze({ epoch: bundledCatalogEpoch, valueIdentity: bundledCatalogCache?.valueIdentity ?? null, }); } /** Test-only: clear the bundled-catalog cache (owned here; sync.ts calls this instead of assigning the import). */ export function resetBundledCatalogCacheForTests(): void { clearBundledCatalogCache(); } /** Drop the process-local bundled catalog memo (e.g. after runtime selection changes). */ export function invalidateBundledCatalogCache(): void { clearBundledCatalogCache(); } /** Test-only owner mutation seam; input is cloned and frozen before publication. */ export function setBundledCatalogCacheForTests( runtime: Pick<ResolvedCodexRuntime, "command" | "version">, value: RawCatalog | null, options: Readonly<{ expiresAt?: number; opencodexHome?: string }> = {}, ): void { publishBundledCatalogCache( bundledRuntimeKey(runtime, options.opencodexHome), options.expiresAt ?? Date.now() + BUNDLED_CATALOG_CACHE_MS, value, ); } export type ExecFile = ( file: string, args: string[], options: { encoding: "utf8"; stdio: ["ignore", "pipe", "ignore"]; timeout: number; windowsHide: boolean; shell?: boolean; windowsVerbatimArguments?: boolean; signal?: AbortSignal; maxBuffer?: number; }, ) => string; export interface BundledCatalogDeps { /** Already-observed source for server clamping; null never triggers a probe. */ observedCatalog?: ReadonlyRawCatalog | null; commandCandidates?: () => string[]; /** * The resolver selection `commandCandidates` came from, when the caller resolved first. Only an * unresolved selection lets the macOS probe add the ChatGPT.app CLI (#8360); without it, injected * candidates are probed as given. */ selectedRuntime?: Pick<ResolvedCodexRuntime, "source" | "version">; execFileSync?: ExecFile; execFile?: (...args: Parameters<ExecFile>) => Promise<string>; onEffortClamp?: (diagnostic: EffortClampDiagnostic) => void; configDir?: string; env?: NodeJS.ProcessEnv; platform?: NodeJS.Platform; existsSync?: (path: string) => boolean; readFileSync?: (path: string, encoding: "utf8") => string; /** Exec-boundary bundle trust for sync drivers (resolve + debug exec). */ macBundleTrustReason?: (bundleRoot: string, binary: string) => string | null; /** Exec-boundary bundle trust for async drivers; injected checks bypass the runtime memo. */ macBundleTrustReasonAsync?: (bundleRoot: string, binary: string, signal?: AbortSignal) => Promise<string | null>; /** Exec-boundary spawnability predicate (regular file + X_OK). */ executable?: (path: string) => boolean; /** Exec-boundary canonicalizer; returns null when the path cannot be resolved. */ realpath?: (path: string) => string | null; now?: () => number; discoverAlternatives?: boolean; } export function unique(values: string[]): string[] { return [...new Set(values.filter(Boolean))]; } export function codexCommandCandidates(): string[] { const envPath = process.env.CODEX_CLI_PATH?.trim(); const candidates = envPath ? [envPath] : []; candidates.push(...codexShimCommandCandidates()); if (process.platform === "win32") { for (const dir of (process.env.PATH ?? "").split(delimiter).filter(Boolean)) { candidates.push(join(dir, "codex.exe"), join(dir, "codex.cmd")); } } candidates.push("codex"); return unique(candidates); } export function codexShimCommandCandidates(): string[] { try { const configDir = getConfigDir(); const state = JSON.parse(readFileSync(join(configDir, "codex-shim.json"), "utf8")) as { schema?: unknown; mode?: unknown; wrapperPath?: unknown; originalPath?: unknown; backupPath?: unknown; wrappers?: Array<{ wrapperPath?: unknown; originalPath?: unknown; backupPath?: unknown }>; }; const overlay = decodeOverlayState(state, configDir); if ((state.schema !== undefined || state.mode !== undefined) && !overlay) return []; const files = Array.isArray(state.wrappers) && state.wrappers.length > 0 ? state.wrappers : [state]; const out: string[] = overlay && isSpawnableCodexCandidate(overlay.launcherPath) ? [overlay.launcherPath] : []; 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)) continue; out.push(value); } } return out; } catch { return []; } } export function runCodexDebugModels<T>( command: string, execFile: (...args: Parameters<ExecFile>) => T, deps: Pick<BundledCatalogDeps, "env" | "platform" | "existsSync" | "executable" | "realpath" | "macBundleTrustReason"> = {}, ): T { const args = ["debug", "models", "--bundled"]; const invocation = validatedCodexExecInvocation(command, args, { env: deps.env, platform: deps.platform, exists: deps.existsSync, executable: deps.executable, realpath: deps.realpath, macBundleTrustReason: deps.macBundleTrustReason, }); return execFile(invocation.file, invocation.args, { encoding: "utf8" as const, stdio: ["ignore", "pipe", "ignore"] as ["ignore", "pipe", "ignore"], timeout: 10_000, maxBuffer: 64 * 1024 * 1024, windowsHide: true, ...invocation.options, }); } /** Async twin of runCodexDebugModels: same args/options, bundle trust checked off the event loop. */ export async function runCodexDebugModelsAsync<T>( command: string, execFile: (...args: Parameters<ExecFile>) => Promise<T>, deps: Pick<BundledCatalogDeps, "env" | "platform" | "existsSync" | "executable" | "realpath" | "macBundleTrustReasonAsync"> = {}, signal?: AbortSignal, ): Promise<T> { const args = ["debug", "models", "--bundled"]; const invocation = await validatedCodexExecInvocationAsync(command, args, { env: deps.env, platform: deps.platform, exists: deps.existsSync, executable: deps.executable, realpath: deps.realpath, macBundleTrustReasonAsync: deps.macBundleTrustReasonAsync, signal, }); return execFile(invocation.file, invocation.args, { encoding: "utf8" as const, stdio: ["ignore", "pipe", "ignore"] as ["ignore", "pipe", "ignore"], timeout: 10_000, maxBuffer: 64 * 1024 * 1024, windowsHide: true, ...invocation.options, }); } function bundledRuntimeDeps(deps: BundledCatalogDeps) { return { // Forward an INJECTED execFileSync only. Passing the real one unconditionally made // resolveCacheKey() bail out (it refuses to memoize injected-dep resolves), so every // catalog read re-ran the ~1s `codex --version` probe even on a warm cache hit. ...(deps.execFileSync ? { execFileSync: deps.execFileSync } : {}), ...(deps.execFile ? { execFile: deps.execFile } : {}), configDir: deps.configDir, env: deps.env, platform: deps.platform, existsSync: deps.existsSync, readFileSync: deps.readFileSync, // Exec-boundary trust deps forwarded so the runtime's own --version probes // use the same injected checks as the catalog exec below. ...(deps.macBundleTrustReason ? { macBundleTrustReason: deps.macBundleTrustReason } : {}), ...(deps.macBundleTrustReasonAsync ? { macBundleTrustReasonAsync: deps.macBundleTrustReasonAsync } : {}), ...(deps.executable ? { executable: deps.executable } : {}), ...(deps.realpath ? { realpath: deps.realpath } : {}), now: deps.now, // Catalog loading only consumes `resolved.runtime.command`, never `newerAvailable`. // Full PATH discovery probes every candidate launcher (100+ on a dev machine, ~1.2s), // which alone can exceed the 3s budget `ocx claude` allows /api/claude-code. Priority // selection is identical either way; callers wanting discovery diagnostics opt in. discoverAlternatives: deps.discoverAlternatives ?? false, }; } /** * Candidates for the bundled-catalog probe. * * When discovery finds no Codex CLI it answers with the bare `codex` sentinel, so the probe * asks a command that does not exist while a real CLI sits inside ChatGPT.app. Discovery only * offers that app candidate after classifying the bundle's XML `Info.plist` identity, so a * bundle it cannot classify (a binary plist, or an identity assertion that moved with an app * update) left `ocx connect status` reporting `unverified` on a macOS Child whose only Codex * was the bundled CLI (#8360). * * The known app locations are therefore added after a bare sentinel. This list grants no * trust: every execution still passes the app-bundle signature and ownership gate in * `exec-boundary.ts`, so an unverifiable bundle yields `null` rather than an invented ladder. * Windows needs no entry here because its Codex App install root under LOCALAPPDATA is already * enumerated by `installedCodexCandidates` in `runtime.ts`. */ function bundledCatalogCandidates( deps: BundledCatalogDeps, resolved: ResolveCodexRuntimeResult | null, ): string[] { const candidates = deps.commandCandidates?.() ?? [resolved!.runtime.command]; // An explicit empty list asks for no probe at all. if (candidates.length === 0) return candidates; if ((deps.platform ?? process.platform) !== "darwin") return candidates; // Decide from the resolver's own result, not from the command's shape: a bare command that ran // (a PATH fallback or a bare CODEX_CLI_PATH) is the operator's runtime, and borrowing the app's // catalog for it would report a ladder that runtime may reject. const selection = resolved?.runtime ?? deps.selectedRuntime; if (!selection || !codexRuntimeIsUnresolved(selection)) return candidates; const exists = deps.existsSync ?? existsSync; return [...candidates, ...macCodexAppCommands(deps).filter(command => exists(command))]; } function* bundledCatalogSteps( candidates: string[], cacheKey: string | null, current: () => boolean = () => true, publishFailure = true, ): Generator<string, ReadonlyRawCatalog | null, string | null> { if (cacheKey && bundledCatalogCache?.key === cacheKey && current()) { // The driver validated this same command/version under the new pin/env inputs. // Re-stamp the memo even if its TTL is due, so failed refresh keeps confirmed rows. bundledCatalogCache = { ...bundledCatalogCache, inputs: codexRuntimeSelectionIdentity({ discoverAlternatives: false }) }; } if ( cacheKey && bundledCatalogCache && bundledCatalogCache.key === cacheKey && bundledCatalogCache.inputs === codexRuntimeSelectionIdentity({ discoverAlternatives: false }) && bundledCatalogCache.expiresAt > Date.now() ) { if (!current()) return null; bundledCatalogCache = { ...bundledCatalogCache, refreshAt: Date.now() + 15_000 }; return bundledCatalogCache.value === null ? null : cloneAndDeepFreeze(bundledCatalogCache.value); } for (const command of unique(candidates)) { if (!current()) return null; const output = yield command; if (!current()) return null; const catalog = output === null ? null : parseCatalogJson(output); if (catalog && catalog.models?.every(row => row !== null && typeof row === "object" && !Array.isArray(row)) && findNativeTemplate(catalog)) { if (cacheKey) { publishBundledCatalogCache( cacheKey, Date.now() + BUNDLED_CATALOG_CACHE_MS, catalog, ); return cloneAndDeepFreeze(bundledCatalogCache!.value!); } return cloneAndDeepFreeze(catalog); } } if (cacheKey && (publishFailure || bundledCatalogCache?.key !== cacheKey || !bundledCatalogCache?.value) && current()) { publishBundledCatalogCache( cacheKey, Date.now() + BUNDLED_CATALOG_CACHE_MS, null, ); } return null; } /** Explicit synchronous CLI driver; request readers use the snapshot below. */ export function loadBundledCodexCatalog(deps: BundledCatalogDeps = {}): ReadonlyRawCatalog | null { const useCache = !deps.commandCandidates && !deps.execFileSync && !deps.execFile && !deps.configDir && !deps.env; const resolved = deps.commandCandidates ? null : resolveAndPersistCodexRuntime(bundledRuntimeDeps(deps)); const inputs = codexRuntimeSelectionIdentity(bundledRuntimeDeps(deps)); const steps = bundledCatalogSteps(bundledCatalogCandidates(deps, resolved), useCache ? bundledRuntimeKey(resolved!.runtime) : null, () => inputs === codexRuntimeSelectionIdentity(bundledRuntimeDeps(deps))); let step = steps.next(); while (!step.done) { let output: string | null = null; try { output = runCodexDebugModels(step.value, deps.execFileSync ?? (execFileSync as unknown as ExecFile), deps); } catch { /* try next candidate */ } step = steps.next(output); } return step.value; } /** Same candidate/parser authority, with version and bundled-model execs off the event loop. */ export function loadBundledCodexCatalogAsync( deps: BundledCatalogDeps = {}, isCurrent: () => boolean = catalogAlwaysCurrent, signal?: AbortSignal, ): Promise<ReadonlyRawCatalog | null> { if (signal?.aborted || !isCurrent()) return Promise.resolve(null); const view = (promise: Promise<ReadonlyRawCatalog | null>) => { if (!signal) return promise.then(value => isCurrent() ? value : null); let abort: (() => void) | undefined; return Promise.race([promise, new Promise<null>(resolve => { abort = () => resolve(null); signal.addEventListener("abort", abort, { once: true }); if (signal.aborted) abort(); })]).then(value => isCurrent() && !signal.aborted ? value : null) .finally(() => { if (abort) signal.removeEventListener("abort", abort); }); }; const runtimeDeps = bundledRuntimeDeps(deps); const inputs = codexRuntimeSelectionIdentity(runtimeDeps); const epoch = bundledCatalogEpoch; const useCache = !deps.commandCandidates && !deps.execFileSync && !deps.execFile && !deps.configDir && !deps.env; if (useCache && bundledCatalogFlight?.inputs === inputs && bundledCatalogFlight.epoch === epoch) { return view(bundledCatalogFlight.promise); } // A passive read (a Remote Link Child's, #6959) runs no Codex binary and persists no runtime. if (isPassiveRead()) return Promise.resolve(null); const controller = new AbortController(); const flight = { inputs, epoch, controller, promise: Promise.resolve<ReadonlyRawCatalog | null>(null) }; if (useCache && !signal && isCurrent === catalogAlwaysCurrent) { bundledCatalogFlight?.controller.abort(); bundledCatalogFlight = flight; } const abort = () => controller.abort(); signal?.addEventListener("abort", abort, { once: true }); if (signal?.aborted) abort(); let timer: ReturnType<typeof setTimeout> | undefined; let deadlineReached = false; const work = (async () => { const active = () => !controller.signal.aborted && isCurrent() && bundledCatalogEpoch === epoch; const resolved = deps.commandCandidates ? null : await resolveAndPersistCodexRuntimeAsync({ ...runtimeDeps, signal: controller.signal }, () => active() && codexRuntimeSelectionIdentity(runtimeDeps) === inputs); if (!active() || (!deps.commandCandidates && !resolved)) return null; flight.inputs = codexRuntimeSelectionIdentity(runtimeDeps); const runtimeEpoch = codexRuntimeStateEpoch(); const current = () => active() && runtimeEpoch === codexRuntimeStateEpoch() && flight.inputs === codexRuntimeSelectionIdentity(runtimeDeps); const steps = bundledCatalogSteps(bundledCatalogCandidates(deps, resolved), useCache ? bundledRuntimeKey(resolved!.runtime) : null, current, false); let step = steps.next(); while (!step.done) { let output: string | null = null; try { output = await runCodexDebugModelsAsync(step.value, (file, args, options) => (deps.execFile ?? execCodexFileAsync)(file, args, { ...options, signal: controller.signal }), deps, controller.signal); } catch { /* preserve last confirmed evidence on failure */ } step = steps.next(output); } return step.value; })().catch(() => null); flight.promise = Promise.race([work, new Promise<null>(resolve => { timer = setTimeout(() => { deadlineReached = true; controller.abort(); resolve(null); }, 45_000); timer.unref?.(); })]).then(value => { if (useCache && value === null && (!controller.signal.aborted || deadlineReached) && isCurrent() && bundledCatalogEpoch === epoch && flight.inputs === codexRuntimeSelectionIdentity(runtimeDeps)) { bundledCatalogRetry = { inputs: flight.inputs, epoch, after: Date.now() + BUNDLED_CATALOG_CACHE_MS }; } return value; }).finally(() => { clearTimeout(timer); signal?.removeEventListener("abort", abort); controller.abort(); if (bundledCatalogFlight === flight) bundledCatalogFlight = null; }); return view(flight.promise); } /** Serve only the same selection's last confirmed catalog; refresh never holds a request. */ export function bundledCodexCatalogSnapshot(): ReadonlyRawCatalog | null { const inputs = codexRuntimeSelectionIdentity({ discoverAlternatives: false }); const memo = bundledCatalogCache?.inputs === inputs ? bundledCatalogCache : null; const cooling = bundledCatalogRetry?.inputs === inputs && bundledCatalogRetry.epoch === bundledCatalogEpoch && bundledCatalogRetry.after > Date.now(); if ((!memo || memo.refreshAt <= Date.now()) && !cooling) void loadBundledCodexCatalogAsync().catch(() => { /* bounded retry */ }); return memo?.value ? cloneAndDeepFreeze(memo.value) : null; } export type CatalogGatherProcessLocalObservation = | Readonly<{ state: "unused" }> | Readonly<{ state: "used"; epoch: number; valueIdentity: string }>; export type CodexRuntimeForCatalogGather = | Readonly<{ kind: "available"; origin: "process-cache" | "persisted"; runtime: DeepReadonly<ResolvedCodexRuntime>; processLocal: CatalogGatherProcessLocalObservation; }> | Readonly<{ kind: "runtime-unavailable"; processLocal: Readonly<{ state: "unused" }>; }>; export type CatalogSourceForGather = | Readonly<{ kind: "available"; source: | "bundled-catalog-template" | "active-catalog-merge" | "hashed-backup-fallback" | "legacy-backup-fallback" | "models-cache-fallback"; catalog: ReadonlyRawCatalog; runtimeSupport: | Readonly<{ kind: "available"; catalog: ReadonlyRawCatalog }> | Readonly<{ kind: "unavailable" }>; processLocal: Readonly<{ runtime: CatalogGatherProcessLocalObservation; bundledCatalog: CatalogGatherProcessLocalObservation; }>; }> | Readonly<{ kind: "catalog-unavailable"; processLocal: Readonly<{ runtime: Readonly<{ state: "unused" }>; bundledCatalog: Readonly<{ state: "unused" }>; }>; }>; export type CatalogGatherPathKind = "default" | "custom"; const UNUSED_PROCESS_LOCAL = Object.freeze({ state: "unused" as const }); function sameRuntimeIdentity( left: Pick<ResolvedCodexRuntime, "command" | "version">, right: Pick<ResolvedCodexRuntime, "command" | "version">, ): boolean { return left.command === right.command && (left.version ?? null) === (right.version ?? null); } /** * Observe an already-resolved runtime only. The evidence owner supplies the * exact persisted bytes (or observed absence); this path never probes or writes. */ export function peekCodexRuntimeForCatalogGather( evidenceSession: CatalogGatherEvidenceSession, ): CodexRuntimeForCatalogGather { const persistedBytes = evidenceSession.readSource("runtime-selection"); const persisted = persistedBytes === null ? null : parsePersistedCodexRuntime(persistedBytes); const processMemo = peekCodexRuntimeProcessCache(); if (processMemo.kind === "available") { const runtime = processMemo.value.runtime; if (persistedBytes === null || (persisted && sameRuntimeIdentity(runtime, { command: persisted.command, version: persisted.selectedVersion ?? null, }))) { return cloneAndDeepFreeze({ kind: "available" as const, origin: "process-cache" as const, runtime, processLocal: { state: "used" as const, epoch: processMemo.epoch, valueIdentity: processMemo.valueIdentity, }, }); } } if (persisted) { return cloneAndDeepFreeze({ kind: "available" as const, origin: "persisted" as const, runtime: { command: persisted.command, version: persisted.selectedVersion ?? null, source: persisted.source, }, processLocal: UNUSED_PROCESS_LOCAL, }); } return Object.freeze({ kind: "runtime-unavailable" as const, processLocal: UNUSED_PROCESS_LOCAL, }); } /** * Resolve only already-observed catalog sources. A cold process cache falls * through to evidence-owned persisted sources and never becomes probe authority. */ export function resolveCatalogSourceForGather( evidenceSession: CatalogGatherEvidenceSession, pathKind: CatalogGatherPathKind, ): CatalogSourceForGather { const bundledMemo = bundledCatalogCache; let runtimeSupport: | Readonly<{ kind: "available"; catalog: ReadonlyRawCatalog }> | Readonly<{ kind: "unavailable" }> = Object.freeze({ kind: "unavailable" }); let processLocal: Readonly<{ runtime: CatalogGatherProcessLocalObservation; bundledCatalog: CatalogGatherProcessLocalObservation; }> = { runtime: UNUSED_PROCESS_LOCAL, bundledCatalog: UNUSED_PROCESS_LOCAL, }; if (bundledMemo?.value && bundledMemo.expiresAt > Date.now()) { const runtime = peekCodexRuntimeForCatalogGather(evidenceSession); if (runtime.kind === "available" && bundledMemo.key === bundledRuntimeKey(runtime.runtime)) { runtimeSupport = Object.freeze({ kind: "available" as const, catalog: bundledMemo.value, }); processLocal = { runtime: runtime.processLocal, bundledCatalog: { state: "used" as const, epoch: bundledMemo.epoch, valueIdentity: bundledMemo.valueIdentity, }, }; if (pathKind === "default") { return cloneAndDeepFreeze({ kind: "available" as const, source: "bundled-catalog-template" as const, catalog: bundledMemo.value, runtimeSupport, processLocal, }); } } } const roles = pathKind === "default" ? [ "active-catalog-merge", "hashed-backup-fallback", "legacy-backup-fallback", "models-cache-fallback", ] as const : [ "active-catalog-merge", "hashed-backup-fallback", "models-cache-fallback", ] as const; for (const role of roles) { const bytes = evidenceSession.readSource(role); if (bytes === null) continue; const catalog = parseCatalogJson(Buffer.from(bytes).toString("utf8")); if (!catalog) continue; // Custom catalogs may intentionally contain only routed rows. Keep their existing source // priority (active, then backup/cache) without imposing the default catalog's native-template // requirement; a valid active custom file therefore remains authoritative over stale fallbacks. if (pathKind === "default" && !findNativeTemplate(catalog)) continue; return cloneAndDeepFreeze({ kind: "available" as const, source: role, catalog, runtimeSupport, processLocal, }); } return Object.freeze({ kind: "catalog-unavailable" as const, processLocal: Object.freeze({ runtime: UNUSED_PROCESS_LOCAL, bundledCatalog: UNUSED_PROCESS_LOCAL, }), }); } export function materializeBundledCodexCatalog(path: string, deps: BundledCatalogDeps = {}): RawCatalog | null { const catalog = loadBundledCodexCatalog(deps); if (!catalog) return null; try { mkdirSync(dirname(path), { recursive: true }); atomicWriteFile(path, JSON.stringify(catalog, null, 2) + "\n"); } catch { return null; } return JSON.parse(JSON.stringify(catalog)) as RawCatalog; } export function loadCatalogForSync(path: string): RawCatalog | null { const bundled = isDefaultCatalogPath(path) ? loadBundledCodexCatalog() : null; if (bundled) return JSON.parse(JSON.stringify(bundled)) as RawCatalog; const catalog = readCatalog(path); if (catalog && findNativeTemplate(catalog)) return catalog; return readCatalog(catalogBackupPathFor(path)) ?? (isDefaultCatalogPath(path) ? readCatalog(legacyCatalogBackupPath()) : null) ?? readCatalog(activeCodexModelsCachePath()) ?? materializeBundledCodexCatalog(path) ?? catalog; } export function readCurrentCatalogOrCache(): RawCatalog | null { const path = readCodexCatalogPath(); const bundled = isDefaultCatalogPath(path) ? bundledCodexCatalogSnapshot() : null; if (bundled) return JSON.parse(JSON.stringify(bundled)) as RawCatalog; return readCatalog(path) ?? readCatalog(activeCodexModelsCachePath()); } /** * Read the user-owned Codex catalog surfaces without substituting the bundled catalog. * * The bundled catalog is intentionally the authority for static native metadata on the default * path. Account-qualified discovery needs the opposite view: an exact model id that Codex has * observed in the user's catalog/cache may be account-scoped even when this release does not know * it statically yet. */ export function readCurrentCodexCatalog(): RawCatalog | null { return readCatalog(readCodexCatalogPath()); } export function readCurrentCodexModelsCache(): RawCatalog | null { return readCatalog(activeCodexModelsCachePath()); } export function loadCatalogTemplate(): RawEntry | null { const catalogPath = readCodexCatalogPath(); const bundled = bundledCodexCatalogSnapshot(); const fromRows = (catalog: RawCatalog | null) => { const template = findSupportedNativeTemplate(catalog ? { ...catalog, models: (catalog.models ?? []).filter(isPlainObject) } : null); // An emitted native has already passed strict normalization. Match that read surface, // including property insertion order, when the native survives only as source evidence. return template && template === retainedNativeInheritanceTemplate(catalog) ? ensureStrictCatalogFields(structuredClone(template)) : template; }; // Template inheritance only. The validity gates in this file keep `findNativeTemplate` // so a catalog carrying only a newly launched native row stays valid (#2813). const native = fromRows(readCatalog(catalogPath)) ?? fromRows(readCatalogBackup(catalogPath)) ?? fromRows(readCatalog(activeCodexModelsCachePath())) ?? fromRows(bundled ? JSON.parse(JSON.stringify(bundled)) as RawCatalog : null); return native ? JSON.parse(JSON.stringify(native)) : null; }