@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
text/typescript
/**
* 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;
}
}