@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
932 lines (893 loc) • 43.3 kB
text/typescript
import { closeSync, existsSync, openSync, readFileSync, statSync } from "node:fs";
import { dirname } from "node:path";
import {
atomicWriteFile,
loadConfig,
observeConfigGeneration,
readConfigAdmissionSnapshot,
withConfigMutationLockSync,
} from "../config";
import { CodexWriteLockSkipped, withCodexWriteLock } from "./codex-write-lock";
import {
localClientSkipMessage,
localClientSkipReason,
shouldSyncCodexOnStart,
type LocalClientSkipReason,
} from "./desired-state";
import { siblingOfLivePort, siblingSkipMessage } from "./sibling-start";
import { resolveCodexHistoryTransition } from "./history-transition";
import {
buildInjectWitness,
captureCodexPreImages,
codexInjectLockOutcome,
codexWriteCoordinationEligibility,
CodexPartialWriteError,
CodexWriteConflictError,
DEFAULT_INJECT_LOCK_TIMEOUT_MS,
recomputeInjectWitness,
recordCodexNativeTransactionProvenance,
restoreCodexPreImages,
} from "./inject-coordination";
import { readIntegrationRecord } from "./integration-record";
import { classifyNativeRoutedResidue } from "./native-residue";
import {
resolveCodexCoordinatorDatabasePath,
resolveEffectiveUserIdentity,
} from "./user-identity";
import {
hasUnverifiedJournalBaseline,
markJournalInjectedState,
journaledInjectedOpenaiBaseUrl,
journaledInjectedRealtimeWsBaseUrl,
removeJournal,
writeJournal,
} from "./journal";
import { HISTORY_RELABEL_STANDS_DOWN } from "./history-provider";
import {
describeHistoryJobFailure,
deriveCodexHistoryOperation,
resolveCodexHistoryJobTarget,
runCodexHistoryJob,
type CodexHistoryJobOutcome,
} from "./history-job";
import {
REALTIME_WS_BASE_URL_KEY,
hasInjectedCodexRouting,
hasInjectedOpenaiBaseUrl,
rootTomlString,
} from "./injected-marker";
import {
CODEX_CONFIG_PATH,
CODEX_PROFILE_PATH,
getCodexHome,
tomlString,
} from "./paths";
import type { OcxConfig } from "../types";
import {
configuredManagedSubagentDefaults,
remoteThreadListCompatibilityWarning,
standaloneCodexRoutingTarget,
validateCodexRoutingTarget,
type CodexRoutingTarget,
} from "./inject/routing-target";
import {
externalCodexModelProvider,
} from "./inject/config-toml";
import { prepareInjectedV1SurfaceReconcile } from "./inject/multi-agent-v2";
import {
deriveCodexInjectionPlan,
type CodexInjectionPlanContext,
type CodexInjectionPlanOk,
} from "./inject/plan";
export { effectiveLoopbackListenerPort, isLoopbackHostname, shouldInjectApiAuthHeader } from "./loopback-target";
// Ownership predicates live in `./injected-marker` so `journal.ts` can reach them
// without importing this module back. Re-exported for existing external callers.
export { hasInjectedCodexRouting, hasInjectedOpenaiBaseUrl };
/**
* Design B (2026-07-06): loopback installs no longer re-tag the provider. Instead of
* `model_provider = "opencodex"` + a `[model_providers.opencodex]` table, we set the official
* built-in override `openai_base_url` (codex-rs config_toml.rs) so codex's own `openai`
* provider points at the proxy. Threads keep `model_provider = "openai"`, so history never
* needs remapping or restore. Non-loopback binds keep the legacy table injection because the
* built-in provider cannot carry the `x-opencodex-api-key` env header.
*/
export interface InjectCodexOptions {
/**
* Absolute or CODEX_HOME-relative catalog path to advertise to Codex. Pass `null` only when the
* opencodex catalog could not be materialized; Codex will then keep its native catalog instead of
* failing on a missing model_catalog_json file.
*/
catalogPath?: string | null;
/**
* How long to wait for the Codex write lock before reporting contention.
*
* Bounded by default so a stuck holder cannot wedge `ocx start`; an explicit
* caller that is willing to wait can raise it.
*/
lockTimeoutMs?: number;
/**
* Validate the same config transformations and write-coordination eligibility without
* changing the journal, config, profile, catalog, cache, or history. Sync uses this before
* provider discovery so a deterministic config refusal cannot degrade an existing catalog.
*/
validateOnly?: boolean;
/** Explicit remote routing target. Absence preserves byte-compatible standalone output. */
routingTarget?: CodexRoutingTarget;
journalOwner?: { kind: "process" } | { kind: "client"; apiKeyId: string };
/** Synchronous read-only client ownership guard, evaluated at the artifact commit boundary. */
beforeClientWrite?: () => void;
}
function runClientWriteGuard(guard: InjectCodexOptions["beforeClientWrite"]): void {
const result: unknown = guard?.();
if (result !== null && (typeof result === "object" || typeof result === "function")
&& typeof (result as { then?: unknown }).then === "function") {
// Reject async guards without leaving their eventual rejection unhandled.
void Promise.resolve(result).catch(() => {});
throw new Error("Connected client write guard must be synchronous");
}
}
export interface CodexInjectResult {
success: boolean;
message: string;
/** False when injection intentionally preserves configuration owned by another provider. */
configApplied?: false;
/**
* Structured read-only history preflight refusal; never parsed from display text.
*
* On the apply direction this reports that the conversation-history relabel unit stood
* down while the config was still written, so a caller must not read it as a failure.
* The restore and remove directions still refuse outright and say so in `message`.
*/
historyPreflightFailureReason?: string;
status?: "skipped";
/** Busy write lock, emitted by `codexInjectLockOutcome` and undeclared here until #4809. */
retryable?: boolean;
/** `hub-gated` is the hub-role gate (#4236), distinct from the user's own OFF switch. */
skippedReason?: LocalClientSkipReason | "desired_enabled";
nativeSubagentDefaultsWarning?: string;
}
class CodexHistoryPreflightRefusal extends Error {}
/**
* A refusal raised inside the write boundary. The caller's catch has already
* restored the captured preimages — a landed v1-surface reconcile included —
* so the carried result is returned verbatim by the outer wrapper.
*/
class CodexInjectRefusal extends Error {
constructor(readonly result: CodexInjectResult) {
super(result.message);
this.name = "CodexInjectRefusal";
}
}
let historyArtifactStageForTests: ((stage: string) => void) | undefined;
export function setHistoryArtifactStageForTests(hook: typeof historyArtifactStageForTests): void {
historyArtifactStageForTests = hook;
}
let beforeHistoryArtifactCommitForTests: ((kind: string) => void) | undefined;
export function setBeforeHistoryArtifactCommitForTests(hook: typeof beforeHistoryArtifactCommitForTests): void {
beforeHistoryArtifactCommitForTests = hook;
}
let publishCurrentTxIdForTests: (() => string) | undefined;
/** Test seam: supply a stale coordinator predecessor after the v1 toggle has run. */
export function setInjectPublishCurrentTxIdForTests(hook: typeof publishCurrentTxIdForTests): void {
publishCurrentTxIdForTests = hook;
}
export async function injectCodexConfig(
port: number,
config?: OcxConfig,
options: InjectCodexOptions = {},
): Promise<CodexInjectResult> {
// First, before the external-provider branch below removes the SHARED journal: a sibling owns
// none of this home's routing, not even the courtesy cleanup.
if (siblingOfLivePort() !== null) {
return { success: true, status: "skipped", skippedReason: "sibling", message: siblingSkipMessage() };
}
try { return await injectCodexConfigImpl(port, config, options); }
catch (error) {
if (error instanceof CodexHistoryPreflightRefusal) return { success: false, historyPreflightFailureReason: error.message, message: `Codex config injection refused: ${error.message}. Existing configuration and history were preserved.` };
if (error instanceof CodexInjectRefusal) return error.result;
throw error;
}
}
async function injectCodexConfigImpl(
port: number,
config?: OcxConfig,
options: InjectCodexOptions = {},
): Promise<CodexInjectResult> {
// Point Codex at the unauthenticated loopback listener when it is enabled (#1102).
//
// Resolved here rather than at the call sites because every caller already passes the proxy
// port and the config together: startup sync, `ocx sync`, and the ensure path would each
// need the same two-line change, and a caller that missed it would silently emit a base_url
// requiring a credential the directly-spawned app-server does not have.
//
// The listener port is fixed in config, never OS-assigned, so this value survives restarts
// and matches what an already-running app-server read at startup.
let routingTarget: CodexRoutingTarget;
try {
routingTarget = options.routingTarget
? validateCodexRoutingTarget(options.routingTarget)
: standaloneCodexRoutingTarget(port, config);
} catch (error) {
return { success: false, message: error instanceof Error ? error.message : "Invalid Codex routing target" };
}
const missingConfig = !existsSync(CODEX_CONFIG_PATH)
? missingCodexConfigAdmission()
: null;
if (missingConfig && !missingConfig.ok) return { success: false, message: missingConfig.message };
// An absent config.toml in an existing home is planned as an empty file. The file itself
// is created only inside the write boundary, after the pre-images are captured, so any
// later refusal or failure rolls it back to absent (issue 5422).
const rawContent = missingConfig ? "" : readFileSync(CODEX_CONFIG_PATH, "utf-8");
const activeProvider = externalCodexModelProvider(rawContent);
if (activeProvider) {
// A launcher may have journaled before the provider manager took ownership. Never let shutdown
// replay that stale snapshot over externally managed config.
if (!options.validateOnly) {
if (options.beforeClientWrite) {
withConfigMutationLockSync(() => {
runClientWriteGuard(options.beforeClientWrite);
removeJournal();
});
} else removeJournal();
}
const nativeSubagentDefaultsWarning = configuredManagedSubagentDefaults(
config,
)
? `Native Codex sub-agent defaults were not injected: external model_provider ${tomlString(activeProvider)} owns config.toml.`
: undefined;
return {
success: true,
configApplied: false,
...(nativeSubagentDefaultsWarning
? { nativeSubagentDefaultsWarning }
: {}),
message:
`⚠️ Codex routing NOT injected: config.toml selects the external model_provider ${tomlString(activeProvider)}.\n` +
` OpenCodex preserves external provider configuration so existing ${tomlString(activeProvider)} session history stays visible.\n` +
` Configure that provider for Responses passthrough at ${routingTarget.baseUrl}` +
`${routingTarget.requiresAdmissionToken ? ` with x-opencodex-api-key from ${routingTarget.tokenEnv}` : ""}.\n` +
` For direct injection, switch to the built-in openai provider, remove any user-owned root openai_base_url, and rerun 'ocx start'.`,
};
}
/*
* The v1-surface reconcile mutates config.toml through the native
* `codex features` transition, so it runs INSIDE the coordinated write
* boundary below — under the same lock and preimage as the artifact commit.
* Run here, a later ambiguous-baseline, journal, or lock refusal left
* config.toml changed while the rest of the injection failed, and a
* competing writer could land between the transition and the commit.
* Its dependencies are resolved now because the commit callback is
* synchronous and cannot await them there.
*/
const v1Reconcile = await prepareInjectedV1SurfaceReconcile(config, options);
/*
* The plan against the admitted input. When the reconcile transitions the
* file under the lock, the committed bytes are re-derived from the
* post-transition input by reconcileAndDerivePlan. Admission compares the
* original candidate for stale input; publication fingerprints the rederived
* candidate so the transition describes the bytes actually committed.
*/
const planContext: CodexInjectionPlanContext = {
config,
routingTarget,
catalogPathOption: options.catalogPath,
journalReadOnly: !!options.beforeClientWrite,
};
const admittedPlan = deriveCodexInjectionPlan(rawContent, planContext);
if (admittedPlan.kind === "refused") {
return {
success: false,
...(admittedPlan.historyPreflightFailureReason
? { historyPreflightFailureReason: admittedPlan.historyPreflightFailureReason }
: {}),
message: admittedPlan.message,
};
}
/*
* The admission witness hashes the planned bytes before the native toggle.
* Its evidence is re-read under the lock to reject stale input. Publication
* uses a separate witness after the toggle, if the plan was rederived;
* ownership rides along as recorded context because it is not re-observed
* there — see `write-coordination.ts`.
*/
const persisted = readConfigAdmissionSnapshot();
const persistedIdentity =
persisted.kind === "read" ? persisted.contentSha256 : "unreadable";
const observedGeneration = observeConfigGeneration();
const generation =
observedGeneration.kind === "ready"
? { present: true, value: observedGeneration.generation.value }
: { present: false, value: 0 };
const witness = buildInjectWitness(
admittedPlan.candidate,
rawContent,
persistedIdentity,
generation,
"unknown",
);
/*
* THE COORDINATED SECTION.
*
* This is the write lock's first production caller. Everything above is
* classification and pure transformation; everything from here to the end of
* the callback replaces files, and two processes doing it at once is the
* interruption hazard this substrate exists to close.
*
* The witness hashes the bytes about to be written rather than the inputs that
* produced them, so two operations intending different output cannot share an
* id no matter which input differed.
*/
/*
* Eligibility BEFORE acquisition, never "try and fall back".
*
* A home routed before this substrate existed cannot have its first
* coordinator row created — the guard that refuses is correct — and that
* describes every pre-substrate install. Attempting the lock there would enter
* a refusal path on the entire installed base, so the decision happens first
* and those homes keep the write sequence they have always used.
*/
const eligibility = codexWriteCoordinationEligibility({
coordinatorPath: () =>
resolveCodexCoordinatorDatabasePath(
resolveEffectiveUserIdentity(),
getCodexHome(),
),
residue: () => classifyNativeRoutedResidue(),
integrationRecord: () => readIntegrationRecord(),
});
if (eligibility.kind === "refused") {
return {
success: false,
message: `Codex configuration was not written: ${eligibility.reason}.`,
};
}
const journalBaselineIsNative = (nativeInput: string): boolean => {
// Value evidence survives an app rewrite that removes the ownership comments.
const journaledBaseUrl = journaledInjectedOpenaiBaseUrl({ readOnly: true });
const journaledRealtimeWsBaseUrl = journaledInjectedRealtimeWsBaseUrl({ readOnly: true });
const looksInjectedByValue =
(journaledBaseUrl !== null && rootTomlString(nativeInput, "openai_base_url") === journaledBaseUrl)
|| (journaledRealtimeWsBaseUrl !== null
&& rootTomlString(nativeInput, REALTIME_WS_BASE_URL_KEY) === journaledRealtimeWsBaseUrl);
return !hasInjectedCodexRouting(nativeInput) && !looksInjectedByValue;
};
const readCurrentProfile = (): string | null => existsSync(CODEX_PROFILE_PATH)
? readFileSync(CODEX_PROFILE_PATH, "utf-8")
: null;
const unverifiedJournalMessage = "Codex configuration was not written: the journal has no verified baseline for the current config/profile. Current files and the journal were preserved.";
// When the reconcile will rewrite config.toml under the lock, the baseline it
// must be journaled against does not exist yet — this check runs inside the
// boundary on the post-transition plan instead. Otherwise the admitted bytes
// are final and the early refusal saves acquiring the lock just to say no.
if (v1Reconcile?.enabledAtPrepare !== true
&& !journalBaselineIsNative(rawContent)
&& hasUnverifiedJournalBaseline(admittedPlan.baselineContent, readCurrentProfile())) {
return {
success: false,
message: unverifiedJournalMessage,
};
}
if (options.validateOnly) {
return {
success: true,
...(admittedPlan.historyRelabelRefusal ? { historyPreflightFailureReason: admittedPlan.historyRelabelRefusal } : {}),
message: "Codex config injection preflight passed; no files were changed.",
};
}
/*
* 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.
*/
const observeHistoryRefusalOrThrow = (plan: CodexInjectionPlanOk): string | null => {
if (plan.historyRelabelRefusal) return plan.historyRelabelRefusal;
const observed = plan.historyPreflight();
if (observed && observed !== HISTORY_RELABEL_STANDS_DOWN) throw new CodexHistoryPreflightRefusal(observed);
return observed;
};
/*
* The half of the injection that only exists inside the write boundary: the
* v1-surface reconcile first, then the plan re-derived from whatever bytes
* the transition left so the committed file cannot re-enable the flag the
* reconcile just turned off. Every refusal here is thrown as
* CodexInjectRefusal so the caller's catch restores the preimage — the flag
* flip included — before the result is reported.
*/
const reconcileAndDerivePlan = (): { plan: CodexInjectionPlanOk; nativeInput: string } => {
if (missingConfig) createEmptyCodexConfigInBoundary();
let nativeInput = rawContent;
let plan = admittedPlan;
if (v1Reconcile) {
const reconciled = v1Reconcile.run();
if (!reconciled.ok) {
throw new CodexInjectRefusal({ success: false, message: reconciled.message });
}
nativeInput = reconciled.content;
if (reconciled.content !== rawContent) {
const rederived = deriveCodexInjectionPlan(reconciled.content, planContext);
if (rederived.kind === "refused") {
throw new CodexInjectRefusal({
success: false,
...(rederived.historyPreflightFailureReason
? { historyPreflightFailureReason: rederived.historyPreflightFailureReason }
: {}),
message: rederived.message,
});
}
plan = rederived;
}
// Seam for the mutual-exclusion regression: the feature transition has
// landed and the artifact commit has not — the window a competing writer
// must be unable to enter.
historyArtifactStageForTests?.("after-v1-reconcile");
}
if (!journalBaselineIsNative(nativeInput)
&& hasUnverifiedJournalBaseline(plan.baselineContent, readCurrentProfile())) {
throw new CodexInjectRefusal({ success: false, message: unverifiedJournalMessage });
}
return { plan, nativeInput };
};
const applyNativeArtifacts = (plan: CodexInjectionPlanOk, nativeInput: string): void => {
beforeHistoryArtifactCommitForTests?.(eligibility.kind);
plan.historyRelabelRefusal = observeHistoryRefusalOrThrow(plan);
historyArtifactStageForTests?.("after-preflight");
writeJournal({
currentStateIsNative: journalBaselineIsNative(nativeInput),
configContent: plan.baselineContent,
owner: options.journalOwner,
});
// A native snapshot may have been refreshed above. An older hashless routed snapshot
// must not gain the new injection's hash and later overwrite preserved user edits.
if (hasUnverifiedJournalBaseline(plan.baselineContent, readCurrentProfile())) throw new Error(unverifiedJournalMessage);
atomicWriteFile(CODEX_CONFIG_PATH, plan.content);
historyArtifactStageForTests?.("after-config");
atomicWriteFile(CODEX_PROFILE_PATH, plan.profileContent);
markJournalInjectedState(plan.content, plan.profileContent, {
// A root override is ours whenever we wrote one and no user-owned value won. That is
// loopback Design B, the client-compaction form, and a table form that retained the
// root line for paginated history. Journaling it matters because the marker comment
// is not durable: the Codex app can reserialize config.toml and drop comments, and
// restore then has only the journaled value to distinguish our line from a user's.
// Other table forms record null.
injectedOpenaiBaseUrl: (plan.providerTableMode && !plan.keepRootOverrideAlongsideTable) || plan.keptUserBaseUrl
? null
: rootTomlString(plan.content, "openai_base_url"),
// The sideband override is ours only when we wrote it this pass (never in legacy mode,
// never when the user owns either key).
injectedRealtimeWsBaseUrl: plan.providerTableMode || plan.keptUserBaseUrl || plan.keptUserRealtimeWsBaseUrl
? null
: rootTomlString(plan.content, REALTIME_WS_BASE_URL_KEY),
// The web-search pair follows the sidecar's master switch, and it is the one root value we
// REPLACE rather than only add: the operator's own mode has to leave the file while the
// switch is off. Both halves are recorded here — the value we wrote (the marker comment is
// not durable) and the line we removed (so re-enabling the sidecar can return it).
injectedRootWebSearch: plan.injectedRootWebSearch,
replacedRootWebSearch: plan.replacedRootWebSearch,
// This is the catalog artifact selected for this injection, even when config.toml
// already points at that path and therefore needs no textual rewrite.
injectedCatalogPath: plan.catalogPath,
});
historyArtifactStageForTests?.("after-artifacts");
// Detect migration throughout the artifact transaction, not just at entry.
plan.historyRelabelRefusal = observeHistoryRefusalOrThrow(plan);
};
/*
* Set only on the coordinated path: the generation/txId the transition just
* committed. The terminal history update CASes against this, so a job that
* was overtaken cannot overwrite the winner. Stays undefined for a
* legacy-uncoordinated home, which publishes no transition to resolve.
*/
let transitionReceipt: { nativeGeneration: number; currentTxId: string } | undefined;
/*
* The plan the committed write actually used: the admitted plan, or the
* re-derivation from the post-reconcile bytes when the feature transition
* rewrote config.toml under the lock. Every reader below the boundary takes
* this plan so the report describes the bytes that were committed.
*/
let effectivePlan: CodexInjectionPlanOk = admittedPlan;
if (eligibility.kind === "legacy-uncoordinated") {
const applyLegacy = (): CodexInjectResult | undefined => {
const legacyGateSnapshot = loadConfig();
if (!shouldSyncCodexOnStart(legacyGateSnapshot)) {
return {
success: true,
status: "skipped",
skippedReason: localClientSkipReason(legacyGateSnapshot),
message: localClientSkipMessage(
legacyGateSnapshot,
"Codex integration is OFF; no Codex config, catalog, cache, or history was changed.",
"No Codex config, catalog, cache, or history was changed.",
),
};
}
runClientWriteGuard(options.beforeClientWrite);
/*
* One preimage covers the reconcile and the artifact commit together: a
* refusal after the feature transition hands back the exact bytes the
* home started with, flag included.
*/
const preImages = captureCodexPreImages();
try {
const resolved = reconcileAndDerivePlan();
applyNativeArtifacts(resolved.plan, resolved.nativeInput);
effectivePlan = resolved.plan;
} catch (error) {
const restored = restoreCodexPreImages(preImages);
if (!restored.complete) throw new CodexPartialWriteError(restored.unrestored);
throw error;
}
return undefined;
};
// Only connected guarded writes add C here. A concurrent disconnect claim
// either follows this commit or is observed by the guard before any write.
const skipped = options.beforeClientWrite
? withConfigMutationLockSync(applyLegacy)
: applyLegacy();
if (skipped) return skipped;
} else {
let coordinatedPreImages: ReturnType<typeof captureCodexPreImages> | undefined;
const coordinated = await withCodexWriteLock(
{
timeoutMs: options.lockTimeoutMs ?? DEFAULT_INJECT_LOCK_TIMEOUT_MS,
...(eligibility.kind === "adopt" ? { adoption: { direction: "apply" as const } } : {}),
onPostCallbackFailure: () => {
if (!coordinatedPreImages) throw new Error("Codex injection preimages were not captured.");
const restored = restoreCodexPreImages(coordinatedPreImages);
if (!restored.complete) throw new CodexPartialWriteError(restored.unrestored);
},
admitted: { authoritySnapshotId: witness.comparisonId },
readAdmissionUnderLock: () => ({
authoritySnapshotId: recomputeInjectWitness({
candidate: witness.candidate,
canonicalTargets: witness.evidence.canonicalTargets,
persistedIdentity,
generation,
observedOwnership: witness.observedOwnership,
}).comparisonId,
}),
},
(ctx) => {
const gateSnapshot = loadConfig();
if (!shouldSyncCodexOnStart(gateSnapshot)) {
// Carry WHY under the lock: "the hub does not write its own clients" and "the user
// turned Codex off" produce the same no-write and must not produce the same sentence.
throw new CodexWriteLockSkipped(localClientSkipReason(gateSnapshot));
}
// N and C are held here. Reject stale client work before publishing a
// transition or capturing preimages; rejection must not compensate over
// a disconnect's restored files.
runClientWriteGuard(options.beforeClientWrite);
/*
* Exact pre-images, captured under the lock and used for compensation.
*
* A rolled-back coordinator row is not a rolled-back filesystem: each
* `atomicWriteFile` is atomic alone, never across the three together, so a
* failure partway leaves earlier replacements in place. `restoreJournalState`
* cannot be the undo — it restores whichever journal occupies the path,
* which need not be the one this operation wrote.
*
* The capture precedes the v1-surface reconcile on purpose: one verified
* preimage covers the feature transition and the artifact commit, so a
* later refusal restores the flag the transition flipped along with the
* files the commit replaced.
*/
const preImages = captureCodexPreImages();
coordinatedPreImages = preImages;
let resolved: { plan: CodexInjectionPlanOk; nativeInput: string };
try {
resolved = reconcileAndDerivePlan();
// The admission id compared pre-toggle bytes. Once the native toggle
// has run, publish the rederived candidate and its actual input as the
// committed-byte witness before writing the remaining artifacts.
const committedWitness = buildInjectWitness(
resolved.plan.candidate,
resolved.nativeInput,
persistedIdentity,
generation,
witness.observedOwnership,
);
const published = ctx.coordinator.beginTransition(
{
nativeGeneration: ctx.expectation.nativeBefore,
currentTxId: publishCurrentTxIdForTests?.() ?? ctx.currentTxId,
},
{
txId: ctx.expectation.txId,
direction: "apply",
authoritySnapshotId: committedWitness.comparisonId,
nextRetryAt: new Date().toISOString(),
},
);
if (published.kind !== "updated") {
throw new CodexWriteConflictError(
`The Codex transition could not be published: ${published.kind}.`,
);
}
applyNativeArtifacts(resolved.plan, resolved.nativeInput);
} catch (error) {
// Compensate, then ALWAYS throw. Returning a partial result would let the
// lock commit a row describing an apply that did not finish.
const restored = restoreCodexPreImages(preImages);
if (!restored.complete) {
throw new CodexPartialWriteError(restored.unrestored);
}
throw error;
}
return {
kind: "applied" as const,
preImages,
plan: resolved.plan,
/*
* The receipt the terminal update matches on. The transition commits
* when the callback returns, so this pair is what the post-job
* `updateCodexHistoryTransition` CASes against — an overtaken job
* cannot overwrite a winner.
*/
receipt: {
nativeGeneration: ctx.expectation.nativeAfter,
currentTxId: ctx.expectation.txId,
},
};
},
);
if (coordinated.status !== "acquired") {
return codexInjectLockOutcome(coordinated);
}
effectivePlan = coordinated.value.plan;
recordCodexNativeTransactionProvenance(
coordinated.value.preImages,
coordinated.value.receipt.currentTxId,
);
transitionReceipt = coordinated.value.receipt;
}
// Legacy mode still forward-tags history so re-tagged threads stay listable. Design B needs
// the opposite: a one-time migration of previously re-tagged threads BACK to openai (restore
// machinery; cheap no-op when there is nothing to migrate). The client-compaction opt-in keeps
// the root override alongside its table precisely so it does NOT have to touch history: an
// existing `openai`-tagged thread still reaches this proxy through the built-in entry. So it
// skips this unit, and future-only means what it says — no provider metadata is rewritten and
// no `ocx1:` payload is touched.
// History runs in a Worker under H, not on this thread.
//
// The three surfaces it touches — the SQLite rows, the backup manifest, and the
// rollout files — do not share a transaction, so a busy timeout only ever
// serialized one of them and an opposite-direction process could overtake
// through the other two. The operation is derived from admitted intent here and
// handed down fixed; the Worker never takes a direction from its caller.
// A stood-down relabel unit spawns no Worker: the preflight it would run first has
// already refused, and the config half is committed either way.
historyArtifactStageForTests?.("before-history-worker");
const historyOutcome: CodexHistoryJobOutcome = effectivePlan.historyRelabelRefusal
? { kind: "skipped" }
: await runCodexHistoryJob({
...resolveCodexHistoryJobTarget(),
expectedDesiredEnabled: true,
operation: deriveCodexHistoryOperation({
direction: "apply",
resumeHistory: config?.syncResumeHistory !== false && !effectivePlan.keepRootOverrideAlongsideTable,
legacyMode: effectivePlan.providerTableMode,
}),
});
// A blocked or failed unit is reported, not silently counted as zero work:
// `failed` is what makes the caller's message say so.
const history: { rows: number; files: number; failed?: true } =
historyOutcome.kind === "converged"
? { rows: historyOutcome.rows, files: historyOutcome.files }
: historyOutcome.kind === "skipped"
? { rows: 0, files: 0 }
: { rows: 0, files: 0, failed: true };
/*
* Resolve the transition this job belongs to, on the coordinated path only.
*
* `updateCodexHistoryTransition` had no production caller since it was
* written, so every completed or skipped job left the row permanently
* `pending` — the transition was published and never resolved. This is the
* first time the durable row reflects what actually happened. The CAS on the
* receipt means an overtaken job's late write loses and is not overwritten.
*/
if (transitionReceipt) {
resolveCodexHistoryTransition(transitionReceipt, historyOutcome);
}
const catalogMessage = effectivePlan.catalogPath
? ` Codex model catalog: ${effectivePlan.catalogPath}\n`
: ` Codex model catalog not injected because no opencodex catalog file exists yet.\n`;
const remoteHistoryMessage = remoteThreadListCompatibilityWarning(routingTarget);
const ejected = (history as { ejectedRows?: number }).ejectedRows ?? 0;
const migratedRows = (history.rows ?? 0) + ejected;
const historyMessage =
effectivePlan.keepRootOverrideAlongsideTable
? (effectivePlan.keptUserBaseUrl
? ` Codex resume history: left unchanged; threads already tagged openai follow your configured root openai_base_url.\n`
: ` Codex resume history: left unchanged; existing threads keep reaching the proxy through the retained openai_base_url override.\n`)
: effectivePlan.historyRelabelRefusal
? ` ⚠️ Codex resume history: left to Codex's native writer (${effectivePlan.historyRelabelRefusal}); existing threads keep the provider they are tagged with. Routing and the model catalog were still installed, so new threads reach the proxy.\n`
: config?.syncResumeHistory === false
? ` Codex resume history: left unchanged (syncResumeHistory=false).\n`
: history.failed
? formatApplyHistoryFailure(historyOutcome, effectivePlan.providerTableMode)
: effectivePlan.providerTableMode
? ` Codex resume history: ${history.rows} thread(s) made visible for opencodex; originals backed up for restore.\n`
: migratedRows > 0
? ` Codex resume history: restored original provider metadata for ${migratedRows} manifest-backed thread(s) (one-time).\n`
: ` Codex resume history: no backed-up metadata pending; untracked routed history left unchanged.\n`;
// A user-owned root openai_base_url means we did NOT install root routing — say so honestly
// instead of claiming the proxy route is active (catalog/fast_mode were still written).
//
// The client-compaction form writes a provider table as well, so "nothing was injected" would
// misdescribe the file it just produced: new threads do use the injected table. Report that
// mixed result on its own terms, and never tell the operator to delete a setting of theirs.
// Ownership alone says nothing about destination: their line may already target this proxy.
if (effectivePlan.keptUserBaseUrl && effectivePlan.keepRootOverrideAlongsideTable) {
return {
success: true,
...(effectivePlan.nativeSubagentDefaultsWarning ? { nativeSubagentDefaultsWarning: effectivePlan.nativeSubagentDefaultsWarning } : {}),
...(effectivePlan.historyRelabelRefusal ? { historyPreflightFailureReason: effectivePlan.historyRelabelRefusal } : {}),
message:
`Injected opencodex as default provider into Codex config (client-side compaction mode; ChatGPT auth remains required).\n` +
` Your root openai_base_url was left exactly as you set it, so opencodex did not add its own.\n` +
catalogMessage +
historyMessage +
remoteHistoryMessage +
effectivePlan.managedDefaultsMessage +
` New threads use the injected opencodex provider and route through the proxy.\n` +
` Threads already tagged openai resolve through Codex's built-in provider, which your root openai_base_url points at.\n` +
` No root URL change is required to enable client-side compaction for new threads.\n` +
` Fallback: codex --profile opencodex (same behavior)`,
};
}
if (effectivePlan.keptUserBaseUrl) {
return {
success: true,
...(effectivePlan.nativeSubagentDefaultsWarning
? { nativeSubagentDefaultsWarning: effectivePlan.nativeSubagentDefaultsWarning }
: {}),
...(effectivePlan.historyRelabelRefusal ? { historyPreflightFailureReason: effectivePlan.historyRelabelRefusal } : {}),
message:
`⚠️ Codex routing NOT injected: your config already sets a root openai_base_url, and opencodex never overwrites a user-owned override.\n` +
catalogMessage +
historyMessage +
effectivePlan.managedDefaultsMessage +
` To route plain codex through the proxy, remove your openai_base_url line from ~/.codex/config.toml and rerun 'ocx start'.\n` +
` Reference config: ${CODEX_PROFILE_PATH}`,
};
}
const headline = routingTarget.desktopAuthless === true
? `Injected opencodex as default provider into Codex config (authless Desktop mode: requires_openai_auth = false).\n`
: routingTarget.clientCompaction === true
? `Injected opencodex as default provider into Codex config (client-side compaction mode; ChatGPT auth remains required).\n`
: effectivePlan.providerTableMode
? `Injected opencodex as default provider into Codex config.\n`
: `Pointed Codex's built-in openai provider at the opencodex proxy (openai_base_url + realtime sideband override).\n`;
return {
success: true,
...(effectivePlan.nativeSubagentDefaultsWarning ? { nativeSubagentDefaultsWarning: effectivePlan.nativeSubagentDefaultsWarning } : {}),
...(effectivePlan.historyRelabelRefusal ? { historyPreflightFailureReason: effectivePlan.historyRelabelRefusal } : {}),
message:
headline +
catalogMessage +
historyMessage +
remoteHistoryMessage +
effectivePlan.managedDefaultsMessage +
` All models now route through opencodex proxy (like OpenRouter).\n` +
` OpenAI models (gpt-5.5, etc.) are passed through to OpenAI.\n` +
` Custom models route to their configured providers.\n` +
(effectivePlan.providerTableMode
? ` Fallback: codex --profile opencodex (same behavior)`
: ` Fallback reference: ${CODEX_PROFILE_PATH}`),
};
}
export function getCodexConfigPath(): string {
return CODEX_CONFIG_PATH;
}
/**
* Frame one failed apply history job honestly.
*
* A genuine lock keeps the established deferred/SKIPPED wording; any other
* reason names itself instead of blaming the Codex app/IDE.
*/
export function formatApplyHistoryFailure(outcome: CodexHistoryJobOutcome, legacyMode: boolean): string {
// A busy database is a deferral no matter which half observed it: the lock
// contended (blocked/busy), or the worker acquired the lock and then found
// SQLite busy (failed with a busy history reason). Only those keep the
// deferred headline; every other failure is a real "NOT changed".
const busy =
(outcome.kind === "blocked" && outcome.reason === "busy") ||
(outcome.kind === "failed" && outcome.historyFailureReason === "busy");
const partiallyChanged = outcome.kind === "failed"
&& ((outcome.rows ?? 0) > 0 || (outcome.files ?? 0) > 0);
const headline = partiallyChanged
? "Codex resume history changed but did not converge"
: legacyMode
? "Codex resume history sync SKIPPED"
: busy
? "Codex resume history metadata restore deferred"
: "Codex resume history NOT changed";
return ` ⚠️ ${headline}: ${describeHistoryJobFailure(outcome, "apply", legacyMode)}\n`;
}
export {
providerBaseHost,
standaloneCodexRoutingTarget,
} from "./inject/routing-target";
export type { CodexRoutingTarget } from "./inject/routing-target";
export {
applyEol,
buildOpenaiBaseUrlLine,
buildProfileFile,
buildProviderTableBlock,
buildRealtimeWsBaseUrlLine,
chooseCatalogPathForInjection,
currentExternalCodexModelProvider,
dominantEol,
externalCodexModelProvider,
setRootOpenaiBaseUrl,
setRootRealtimeWsBaseUrl,
stripInjectedOpenaiBaseUrl,
stripRootContextWindowOverrides,
} from "./inject/config-toml";
export {
classifyCodexRouting,
getCodexRoutingKind,
isCodexRoutingInjected,
} from "./inject/routing-classify";
export type { CodexRoutingKind } from "./inject/routing-classify";
export {
removeCodexConfig,
stripOpencodexConfig,
} from "./inject/remove";
export type {
CodexNativeRestoreResult,
CodexRestoreArtifactState,
CodexRestoreCatalogResult,
CodexRestoreConfigResult,
CodexRestoreHistoryResult,
} from "./inject/restore";
export {
failedHistoryRestoreFromOutcome,
restoreNativeCodex,
restoreNativeCodexAsync,
setBeforeRestoreConfigForTests,
skippedRestoreEnvelope,
} from "./inject/restore";
type MissingCodexConfig = { ok: true } | { ok: false; message: string };
/**
* A fresh Codex install can have its home directory but no config.toml yet: Codex writes
* that file lazily, and a user who never signed in to OpenAI (authless Desktop with a
* third-party provider, issue 5422) may never get one. A missing optional file is not
* evidence that Codex is absent, so injection plans against an empty config.toml and
* creates it inside the write boundary. A missing home DIRECTORY is different: that is
* either an uninitialized install or the wrong home, and guessing would write provider
* state where Codex is not looking.
*/
function missingCodexConfigAdmission(): MissingCodexConfig {
const home = dirname(CODEX_CONFIG_PATH);
let homeIsDirectory = false;
try {
homeIsDirectory = statSync(home).isDirectory();
} catch {
homeIsDirectory = false;
}
if (homeIsDirectory) return { ok: true };
return {
ok: false,
message: `Codex home ${home} does not exist yet, so there is no config.toml to route. Start Codex once so it creates its home, then rerun 'ocx sync'. If Codex uses a different home, set CODEX_HOME to it.`,
};
}
/**
* Create the planned empty config.toml under the write boundary. It runs after the
* pre-images were captured (config absent), so compensation removes it again. The create is
* exclusive: a file that appeared since admission belongs to another writer, and this plan,
* derived from an absent file, must not replace it.
*/
function createEmptyCodexConfigInBoundary(): void {
try {
closeSync(openSync(CODEX_CONFIG_PATH, "wx", 0o600));
} catch (error) {
const appeared = (error as NodeJS.ErrnoException | null)?.code === "EEXIST";
throw new CodexInjectRefusal({
success: false,
message: appeared
? `Codex config ${CODEX_CONFIG_PATH} appeared while injection was planned against its absence; nothing was changed. Rerun 'ocx sync'.`
: `Codex config not found at ${CODEX_CONFIG_PATH}, and creating it failed: ${error instanceof Error ? error.message : String(error)}`,
});
}
}