UNPKG

@bitkyc08/opencodex

Version:

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

465 lines (447 loc) • 22.7 kB
/** * The injection plan: every byte the artifact commit will write, plus the * journal baseline, derived from one native config.toml text. * * This is pure transformation and read-only preflight — no filesystem * mutation — so the caller derives once at admission time for the write * witness and pre-lock checks, and then AGAIN under the write lock when the * v1-surface reconcile changes config.toml there. Re-deriving from the * post-transition bytes is what keeps the committed file from re-enabling the * flag the reconcile just turned off. */ import { existsSync, readFileSync } from "node:fs"; import { websocketsEnabled } from "../../config"; import { hasPaginatedOpenaiThreads, HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE, HISTORY_RELABEL_STANDS_DOWN, preflightCodexHistoryInjection, } from "../history-provider"; import { journaledInjectedRootValues, journaledInjectedRootWebSearch, journaledInjectedSubagentDefaults, journaledOwnedCatalogBinding, journaledReplacedRootWebSearch, } from "../journal"; import { REALTIME_WS_BASE_URL_KEY, stripJournaledOpenaiBaseUrl } from "../injected-marker"; import { CODEX_CONFIG_PATH, CODEX_PROFILE_PATH, codexCatalogBindingForPath, resolveCodexStateDbPath } from "../paths"; import { transformManagedSubagentDefaults, type WrittenSubagentDefaults } from "../subagent-defaults"; import type { OcxConfig } from "../../types"; import type { CodexWriteCandidate } from "../write-coordination"; import { applyEol, buildProfileFileForTarget, buildProviderTableBlockForTarget, chooseCatalogPathForInjection, dominantEol, ensureFastModeFeature, ensureRootWebSearchDisabled, normalizeServiceTier, preserveUnmanagedProfileKeys, removeProfileSection, setRootModelProvider, setRootOpenaiBaseUrlForTarget, setRootRealtimeWsBaseUrl, stripExistingModelProvider, stripInjectedOpenaiBaseUrl, updateRootModelCatalogPath, } from "./config-toml"; import { hasOcxProviderTable, removeOcxSection } from "./remove"; import { configuredManagedSubagentDefaults, usesProviderTable, type CodexRoutingTarget, } from "./routing-target"; import { applyPaginatedOpenaiCompat, codexLocksResumeProvider } from "./paginated-openai-compat"; /** Everything the plan needs that is not the config.toml input text. */ export interface CodexInjectionPlanContext { readonly config: OcxConfig | undefined; readonly routingTarget: CodexRoutingTarget; /** The caller's catalog path option — the RESOLVED path lands on the plan. */ readonly catalogPathOption: string | null | undefined; /** Journal reads stay read-only while a client guard owns the write channel. */ readonly journalReadOnly: boolean; /** * The resolved Codex version from a passive read, or null when unknown. From 0.166 a paginated * openai-tagged row can no longer resume under opencodex, so the table transition is refused * instead of retaining the root override (#8191). */ readonly codexVersion?: string | null; } /** The ok-variant of the plan: every derived artifact and reportable warning. */ export interface CodexInjectionPlanOk { kind: "ok"; /** The input with marker-owned residue removed — what writeJournal snapshots. */ baselineContent: string; /** The exact string about to replace config.toml. */ content: string; /** The exact string about to replace the profile file. */ profileContent: string; /** * The profile bytes `profileContent` preserved keys from (null when absent). * Re-checked under the write lock so an edit landing meanwhile is not overwritten. */ profileSource: string | null; /** The resolved catalog path, never the raw option. */ catalogPath: string | null; injectedCatalogBinding: string | null; providerTableMode: boolean; keepRootOverrideAlongsideTable: boolean; keptUserBaseUrl: boolean; keptUserRealtimeWsBaseUrl: boolean; /** The root `web_search` value this plan writes, or null when it writes none. */ injectedRootWebSearch: string | null; /** The user-owned root `web_search` line this plan removed, for the journal to carry. */ replacedRootWebSearch: string | null; /** The marker-owned `[agents]` defaults this plan writes, for the journal to carry; null when none. */ injectedSubagentDefaults: WrittenSubagentDefaults | null; nativeSubagentDefaultsWarning: string | undefined; managedDefaultsMessage: string; /** * Mutable: the artifact commit re-observes the history store mid-write and * records the outcome here so the caller's message reflects it. */ historyRelabelRefusal: string | null; /** Read-only history preflight bound to this plan's candidate bytes. */ historyPreflight(): string | null; /** The witness candidate: the bytes this plan commits. */ candidate: CodexWriteCandidate; } export type CodexInjectionPlan = | { kind: "refused"; message: string; historyPreflightFailureReason?: string; } | CodexInjectionPlanOk; function websocketsForRoutingTarget( config: OcxConfig | undefined, routingTarget: CodexRoutingTarget, ): boolean { // A link client reaches the hub through an HTTP-only tunnel. Its local Codex target is // deliberately distinct from the tunnel origin, so force the injected websocket setting off // even when the operator enabled the global websocket option. Hub mode can also use a local // HTTP target with admission, so the explicit discriminator is required here. return (routingTarget as CodexRoutingTarget & { link?: boolean }).link === true ? false : websocketsEnabled(config ?? {}); } export function deriveCodexInjectionPlan( source: string, ctx: CodexInjectionPlanContext, ): CodexInjectionPlan { const { config, routingTarget } = ctx; const preflightTableMode = usesProviderTable(routingTarget); const compactionOnly = routingTarget.clientCompaction === true && routingTarget.desktopAuthless !== true && routingTarget.requiresAdmissionToken !== true; // Marker-owned native defaults are OpenCodex residue, never part of the // user's journal baseline. Clean them before either snapshotting or adding a // root routing key: inserting that key ahead of a marker-owned first table // would otherwise separate the table marker from its header. Ambiguous // markers fail closed without writing config, profile, or journal state. // A marked value that no longer matches the journaled write was edited by the // user (#7425); it is adopted into the baseline instead of being cleaned. const nativeDefaultsBaseline = transformManagedSubagentDefaults( source, null, journaledInjectedSubagentDefaults({ readOnly: ctx.journalReadOnly }), ); if (!nativeDefaultsBaseline.ok) { return { kind: "refused", message: `Codex config injection refused: existing OpenCodex-managed native sub-agent defaults are ambiguous: ${nativeDefaultsBaseline.error}. ` + `No files were changed; inspect ${CODEX_CONFIG_PATH}.`, }; } const baselineContent = nativeDefaultsBaseline.content; /* * The journal write happens inside the write lock, after this plan is * derived. The lock's witness hashes the CANDIDATE BYTES, and those are not * final until `profileContent` and the EOL-applied `content` exist. * Opening the lock before them would leave nothing to hash; keeping the * journal outside the lock would leave the first artifact-creating write * unserialized. * * The split is safe because derivation performs no filesystem mutation — its * only touch is `existsSync` on the catalog paths * (`chooseCatalogPathForInjection`) — and because `writeJournal` is called * with `configContent`, so it snapshots the baseline it is handed rather * than rereading config.toml underneath the transforms. */ // EOL boundary: transforms below are LF-pure; preserve the file's dominant ending on write. const eol = dominantEol(source); let content = applyEol(baselineContent, "\n"); // Idempotent clean-up of any prior injection: drop the provider table (marker-based) and every // stray/mis-nested model_provider line, so re-injecting can't duplicate keys or leave the buggy // table-nested key behind. // Design B form FIRST: removeOcxSection also keys on the marker line, so a root-level // marker + openai_base_url pair must be gone before it scans or it would swallow root keys. content = stripInjectedOpenaiBaseUrl(content); // #1798: after a Codex app rewrite the markers are gone but the values we recorded writing // are still ours. Consume them by value here, BEFORE the routing form is chosen, so a // Design B -> provider-table transition (hostname change, authless opt-in) cannot leave our // own root URLs behind as if they were the user's, and so re-inject never journals them as // not-ours (which would make them unrestorable). // Every URL an injection under this journal wrote counts, not only the latest: the Codex app can // write back an earlier one from its own copy of the file. for (const url of journaledInjectedRootValues("openai_base_url", { readOnly: ctx.journalReadOnly })) { content = stripJournaledOpenaiBaseUrl(content, url, null); } for (const url of journaledInjectedRootValues(REALTIME_WS_BASE_URL_KEY, { readOnly: ctx.journalReadOnly })) { content = stripJournaledOpenaiBaseUrl(content, null, url); } // Whether this home already published the provider id that its thread rows may reference. // Design B strips the table below; it may only stay stripped if those rows can be relabeled. const hadOcxProviderTableOnDisk = hasOcxProviderTable(content); if (hadOcxProviderTableOnDisk) { content = removeOcxSection(content); } content = removeProfileSection(content); content = stripExistingModelProvider(content); // A root `model_context_window` is never written by OpenCodex, so it is the user's choice and // survives injection (#7425). Codex applies it to every model ahead of the catalog's windows. content = normalizeServiceTier(content); content = ensureFastModeFeature(content, config?.fastMode); // Codex's own web-search switch follows the sidecar's master switch. While the sidecar is off, // the client must not keep offering a native `web_search` tool that an MCP search server is // meant to replace. The journal carries both halves of an earlier pass — the value we wrote, // because the marker comment does not survive a Codex app reserialize, and the operator line we // had to remove, because the sidecar coming back on is what returns it. const webSearch = ensureRootWebSearchDisabled( content, config?.webSearchSidecar?.enabled === false, { injectedValue: journaledInjectedRootWebSearch({ readOnly: ctx.journalReadOnly }), replacedUserLine: journaledReplacedRootWebSearch({ readOnly: ctx.journalReadOnly }), }, ); content = webSearch.content; const catalogOwner = { journaledPath: journaledOwnedCatalogBinding({ readOnly: ctx.journalReadOnly }) }; const catalogPath = chooseCatalogPathForInjection(content, ctx.catalogPathOption, catalogOwner); const catalog = updateRootModelCatalogPath( content, catalogPath && codexCatalogBindingForPath(CODEX_CONFIG_PATH, catalogPath), catalogOwner, ); content = catalog.content; // Provider-table form: non-loopback admission or an explicit Desktop policy. const providerTableMode = usesProviderTable(routingTarget); // Client compaction is the one table form that must not orphan existing threads. It changes // the DEFAULT provider to `opencodex`, but a thread already tagged `openai` keeps resolving // to Codex's built-in entry, and without the root override that entry is api.openai.com — // the thread would resume outside this proxy and outside configured routing. Keeping the // marker-owned root override alongside the table fixes that at the source: codex builds its // provider map as merge_configured_model_providers(built_in_model_providers(openai_base_url), // model_providers), so the override lands on the built-in `openai` entry when the map is // built, independent of which id is the default, and the merge leaves that entry alone for // every id except the two Amazon Bedrock ones. With the managed override in place both // entries point at this proxy. That is a guarantee about the line we own: when the user owns // the root line we inject nothing, and the built-in entry keeps whatever destination they // chose, so an `openai`-tagged thread follows their configuration rather than this proxy. // // Re-tagging history was the alternative and it cannot be made durable: the length-preserving // first-line repair cannot grow "openai" into "opencodex" without pre-existing padding, and // codex re-appends that stale first line whenever it writes git or memory-mode metadata. // // Authless is excluded on purpose: its whole point is a provider that carries // requires_openai_auth = false, and admission-token forms cannot use the root key at all. // Those two forms therefore keep their existing behaviour, forward-tagging resume history with // originals backed up, and that includes the case where a user enables authless and client // compaction together. Only the compaction-only form skips the history unit. let keepRootOverrideAlongsideTable = providerTableMode && routingTarget.clientCompaction === true && routingTarget.desktopAuthless !== true && routingTarget.requiresAdmissionToken !== true; let keptUserBaseUrl = false; let keptUserRealtimeWsBaseUrl = false; if (providerTableMode) { // Legacy (non-loopback) injection: the built-in openai provider cannot carry the // x-opencodex-api-key env header, so keep the opencodex provider table + root re-tag. // The authless opt-in needs the same table because only a dedicated provider can carry // requires_openai_auth = false. // 1) Root key BEFORE the first table header (must be a global, not nested under a table). content = setRootModelProvider(content); // 2) Provider table appended at EOF (position-independent). content = content.trimEnd() + "\n" + buildProviderTableBlockForTarget(routingTarget, websocketsForRoutingTarget(config, routingTarget), config?.codexProviderDisplayName); // 3) Keep existing `openai`-tagged threads reaching the proxy (see above). Ownership rules // are the Design B ones: a user's own root line is never replaced. if (keepRootOverrideAlongsideTable) { content = stripInjectedOpenaiBaseUrl(content); const rootFallback = setRootOpenaiBaseUrlForTarget(content, routingTarget); content = rootFallback.content; keptUserBaseUrl = rootFallback.keptUserBaseUrl; } } else { // Design B (loopback): a single root override; codex keeps its native `openai` provider id // so thread history is never remapped. Any legacy form was already stripped above. content = stripInjectedOpenaiBaseUrl(content); // normalize before idempotent re-insert const result = setRootOpenaiBaseUrlForTarget(content, routingTarget); content = result.content; keptUserBaseUrl = result.keptUserBaseUrl; // Voice sideband override rides on the routing override: same value, same ownership rule, // and never when the user owns the routing line (we inject nothing in that case). if (!keptUserBaseUrl) { const realtime = setRootRealtimeWsBaseUrl(content, routingTarget); content = realtime.content; keptUserRealtimeWsBaseUrl = realtime.keptUserRealtimeWsBaseUrl; } } const desiredSubagentDefaults = configuredManagedSubagentDefaults(config); const routingOwnershipWarning = keptUserBaseUrl && desiredSubagentDefaults ? "Native Codex sub-agent defaults were not injected: a user-owned root openai_base_url prevents OpenCodex from managing active Codex routing." : undefined; const managedDefaults = transformManagedSubagentDefaults( content, keptUserBaseUrl ? null : desiredSubagentDefaults, ); let nativeSubagentDefaultsWarning = routingOwnershipWarning; let managedDefaultsMessage = routingOwnershipWarning ? ` ⚠️ ${routingOwnershipWarning}\n` : ""; let injectedSubagentDefaults: WrittenSubagentDefaults | null = null; if (managedDefaults.ok) { content = managedDefaults.content; if (desiredSubagentDefaults && managedDefaults.conflicts.length > 0) { const keys = managedDefaults.conflicts .map((conflict) => `agents.${conflict.key}`) .join(", "); nativeSubagentDefaultsWarning = `Native Codex sub-agent defaults were not injected: user-owned ${keys} preserved.`; managedDefaultsMessage = ` ⚠️ ${nativeSubagentDefaultsWarning}\n`; } else if (desiredSubagentDefaults && !keptUserBaseUrl) { injectedSubagentDefaults = { default_subagent_model: desiredSubagentDefaults.model, ...(desiredSubagentDefaults.reasoningEffort !== undefined ? { default_subagent_reasoning_effort: desiredSubagentDefaults.reasoningEffort } : {}), }; } } else { const action = desiredSubagentDefaults && !keptUserBaseUrl ? "were not injected" : "could not be safely removed"; nativeSubagentDefaultsWarning = `Native Codex sub-agent defaults ${action}: ${managedDefaults.error}.`; managedDefaultsMessage = ` ⚠️ ${nativeSubagentDefaultsWarning}\n`; } const profileSource = readCodexProfileSource(); const profileContent = preserveUnmanagedProfileKeys( profileSource, buildProfileFileForTarget( routingTarget, catalogPath && codexCatalogBindingForPath(CODEX_PROFILE_PATH, catalogPath), websocketsForRoutingTarget(config, routingTarget), config?.fastMode, config?.codexProviderDisplayName, ), ); content = applyEol(content, eol); // Resolve storage from the normalized candidate. Owned duplicate catalog keys // are repairable above and must not make this read-only preflight throw. const historyPreflight = (): string | null => { try { return preflightCodexHistoryInjection( preflightTableMode, config?.syncResumeHistory !== false && !compactionOnly, resolveCodexStateDbPath({ readConfig: () => content }), ); } catch { return "history_injection_preflight_unavailable"; } }; /* * ONE refusal stands the relabel unit down instead of vetoing the config transition, and * only because it is permanent. Codex allocates paginated rollout ordinals in its own * writer, so `assertLegacyHistoryRecord` refuses every rollout on a current install and no * amount of retrying changes that. While it vetoed the write, `model_catalog_json` never * reached config.toml, so the app and the CLI both fell back to their built-in model list * while `ocx sync` still reported success. * * Every other reason — an unreadable state database, a rollout whose identity changed, a * preflight that could not run — describes a store that may well be relabelable on the next * attempt. Treating those as a stand-down would record the transition as converged and * suppress the relabel permanently, so they keep the hard refusal and the rollback. */ /* * Re-observed inside the artifact transaction. A store that migrates to paginated history * mid-write can retire the relabel unit while its already-admitted candidate leaves * existing provider references resolvable. Existing provider definitions are retained * before the witness; no post-commit compensation may overwrite a newer native write. */ // Client compaction relabels nothing, so its preflight scans no rows, yet it still makes // `opencodex` the default provider. On a Codex that locks resume to the creating provider // (#8191), probe the store read-only so the same refusal applies; older or unknown versions // keep the retained override and add no read. let preflight = historyPreflight(); if (preflight === null && compactionOnly && preflightTableMode && config?.syncResumeHistory !== false && codexLocksResumeProvider(ctx.codexVersion) && hasPaginatedOpenaiThreads(resolveCodexStateDbPath({ readConfig: () => content })) === true) { preflight = HISTORY_PAGINATED_OPENAI_NEEDS_ROOT_OVERRIDE; } const compat = applyPaginatedOpenaiCompat(preflight, routingTarget, content, eol, ctx.codexVersion); content = compat.content; keepRootOverrideAlongsideTable ||= compat.retainedRootOverride; const observedHistoryRefusal = compat.refusal; if (observedHistoryRefusal && observedHistoryRefusal !== HISTORY_RELABEL_STANDS_DOWN) { return { kind: "refused", historyPreflightFailureReason: observedHistoryRefusal, message: compat.message, }; } /* * Rows this home may have tagged `opencodex` resolve only through a provider table. Design B * selects built-in `openai` for new work, but background relabel and native publication are * not atomic. Codex can paginate after the final check or when the worker starts. Retain * an existing definition BEFORE the witness regardless of preflight, so worker failure * cannot orphan old references. Explicit restoration keeps its removal and history guards. */ if (hadOcxProviderTableOnDisk && !providerTableMode) { content = applyEol( content.trimEnd() + "\n" + buildProviderTableBlockForTarget(routingTarget, websocketsForRoutingTarget(config, routingTarget), config?.codexProviderDisplayName), eol, ); } return { kind: "ok", baselineContent, content, profileContent, profileSource, catalogPath, injectedCatalogBinding: catalog.injectedBinding, providerTableMode, keepRootOverrideAlongsideTable, keptUserBaseUrl, keptUserRealtimeWsBaseUrl, injectedRootWebSearch: webSearch.wroteValue, replacedRootWebSearch: webSearch.replacedUserLine, injectedSubagentDefaults, nativeSubagentDefaultsWarning, managedDefaultsMessage, historyRelabelRefusal: observedHistoryRefusal, historyPreflight, candidate: { configBytes: content, profileBytes: profileContent, catalogPath, }, }; } /** * Current profile bytes, or null when absent. Read directly: a profile removed between an * existence check and the read is simply absent. If it reappears before the write lock, the * lock-time comparison refuses retryably; other read errors propagate. */ export function readCodexProfileSource(): string | null { try { return readFileSync(CODEX_PROFILE_PATH, "utf-8"); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; return null; } }