@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
452 lines (424 loc) • 20.5 kB
text/typescript
/**
* The parent half of the history unit: derive the operation, dispatch the
* Worker, and never let its failure become the caller's stall.
*
* The operation is DERIVED here from what the caller already decided — its
* config and the direction its native mutation just took — and then handed down
* as a fixed value. It is not a request field the Worker trusts, because the
* distinctions are real: `syncResumeHistory: false` means leave history alone,
* apply targets opencodex only in legacy mode, and legacy recovery must not
* touch the manifest that generic restore consumes.
*
* Every exit is typed. A Worker that errors, dies, or overruns its watchdog
* produces an outcome the caller can record, because the alternative — an
* exception crossing back into a route that already persisted its mutation — is
* how a successful change gets reported as a 500.
*
* Design record: devlog/_fin/260804_codex_write_substrate/020_history_isolation.md.
*/
import { randomUUID } from "node:crypto";
import { homedir } from "node:os";
import type {
CodexHistoryWorkerOperation,
HistoryWorkerResult,
} from "./history-worker";
import { currentHistoryDbBusyTimeoutMs, resolveExistingHistoryBackupPath } from "./history-provider";
import { spawnWorker } from "../lib/worker-embed";
import type { CodexHistoryFailureReason, CodexHistoryVerifiedNoopProof } from "./history-provider";
import { getCodexHome, resolveCodexStateDbPath } from "./paths";
/**
* Resolve the paths a history job needs, at CALL time.
*
* The SQLite root can differ from CODEX_HOME and both environment/config inputs
* can change between invocations. The parent resolves one exact target and hands
* those resolved paths to the Worker rather than asking the Worker to infer a
* possibly different environment.
*/
export function resolveCodexHistoryJobTarget(): {
readonly canonicalCodexHome: string;
readonly canonicalStateDbPath: string;
readonly canonicalBackupPath: string;
} {
const home = getCodexHome();
const stateDb = resolveCodexStateDbPath({ codexHome: home });
return {
canonicalCodexHome: home,
canonicalStateDbPath: stateDb,
// Resolve through the provider's canonical-first compatibility rule. Passing
// only the newly normalized name would hide a pre-#4442 Windows manifest from
// the Worker and make an upgrade look like an empty backup.
canonicalBackupPath: resolveExistingHistoryBackupPath(stateDb),
};
}
/** How long a history unit may run before the parent stops waiting on it. */
const WORKER_TIMEOUT_MS = 30_000;
/** A terminated Worker must close before its caller can cross the file boundary. */
const WORKER_CLOSE_TIMEOUT_MS = 5_000;
function historyWorkerOsJoinSettleMs(platform = process.platform): number {
if (platform === "win32") return 1_500;
if (platform === "darwin" || platform === "linux") return 250;
return 0;
}
async function terminateAndJoinHistoryWorker(
worker: Worker,
closed: Promise<void>,
): Promise<boolean> {
let timedOut = false;
let timeout: ReturnType<typeof setTimeout> | undefined;
const closeTimeout = new Promise<void>(resolve => {
timeout = setTimeout(() => {
timedOut = true;
resolve();
}, WORKER_CLOSE_TIMEOUT_MS);
});
try {
worker.terminate();
} catch {
// A Worker that already closed still resolves through the close listener.
}
try {
await Promise.race([closed, closeTimeout]);
} finally {
if (timeout) clearTimeout(timeout);
}
const settleMs = historyWorkerOsJoinSettleMs();
if (settleMs > 0) {
await Bun.sleep(0);
await Bun.sleep(settleMs);
}
return !timedOut;
}
export interface CodexHistoryJobRequest {
readonly canonicalCodexHome: string;
readonly canonicalStateDbPath: string;
readonly canonicalBackupPath: string;
readonly operation: CodexHistoryWorkerOperation;
readonly expectedDesiredEnabled?: boolean;
}
export type CodexHistoryJobOutcome =
| { readonly kind: "converged"; readonly rows: number; readonly files: number; readonly proof?: CodexHistoryVerifiedNoopProof }
| { readonly kind: "skipped" }
| { readonly kind: "blocked"; readonly reason: "busy" | "database" | "unsafe-path" | "desired_disabled" | "desired_enabled" }
| { readonly kind: "failed"; readonly reason: "worker-error" | "worker-died" | "timeout";
readonly message: string; readonly historyFailureReason?: CodexHistoryFailureReason;
/** Specific integrity condition when `historyFailureReason` is `"integrity"`. */
readonly historyIntegrityCode?: string;
readonly rows?: number; readonly files?: number };
/**
* Derive the durable history operation from admitted intent.
*
* `resumeHistory === false` is the user's explicit opt-out and outranks the
* direction entirely — an apply that quietly migrated history anyway would be
* the setting failing silently. `legacyMode` is the only case that routes
* history TO opencodex; the ordinary apply migrates to native so a later restore
* has nothing to undo.
*/
/**
* Test seam: the boundary suite exercises the validator without standing up a
* Worker whose malformed message it cannot easily emit from inside a test.
*/
export function isPlausibleWorkerResultForTests(
message: Record<string, unknown>,
requestId: string,
jobId: string,
target?: Pick<CodexHistoryJobRequest, "canonicalStateDbPath" | "canonicalBackupPath" | "operation">,
): boolean {
return isPlausibleWorkerResult(message, requestId, jobId, target);
}
/**
* Reject a message that names a recognized type but lacks its payload.
*
* Without this, `{requestId, type:"done"}` reached an unchecked cast and read
* as `converged` with undefined fields — a success report for work that may not
* have happened. Each type is checked for the fields it actually carries, and
* the ids are matched against the request in flight, not merely present.
*/
function isPlausibleWorkerResult(
message: Record<string, unknown>,
requestId: string,
jobId: string,
target?: Pick<CodexHistoryJobRequest, "canonicalStateDbPath" | "canonicalBackupPath" | "operation">,
): boolean {
if (message.requestId !== requestId || message.jobId !== jobId) return false;
switch (message.type) {
case "done":
if (!((message.outcome === "converged" || message.outcome === "skipped")
&& typeof message.rows === "number"
&& typeof message.files === "number")) return false;
if (message.proof === undefined) return true;
if (!target || !message.proof || typeof message.proof !== "object" || Array.isArray(message.proof)) return false;
{
const proof = message.proof as Record<string, unknown>;
return target.operation === "migrate-openai"
&& message.outcome === "converged"
&& message.rows === 0
&& message.files === 0
&& proof.kind === "verified-noop"
&& proof.pendingRows === 0
&& proof.backupEntries === 0
&& proof.canonicalStateDbPath === target.canonicalStateDbPath
&& proof.stateDbPresent === true
&& proof.canonicalBackupPath === target.canonicalBackupPath
&& typeof proof.backupPresent === "boolean";
}
case "blocked":
return message.reason === "busy" || message.reason === "database" || message.reason === "unsafe-path"
|| message.reason === "desired_disabled" || message.reason === "desired_enabled";
case "error":
return typeof message.message === "string"
&& (message.rows === undefined || (Number.isSafeInteger(message.rows) && Number(message.rows) >= 0))
&& (message.files === undefined || (Number.isSafeInteger(message.files) && Number(message.files) >= 0))
&& ((message.rows === undefined && message.files === undefined)
|| (message.rows !== undefined && message.files !== undefined))
&& (message.reason === undefined
|| message.reason === "busy"
|| message.reason === "permission"
|| message.reason === "integrity");
default:
return false;
}
}
export function deriveCodexHistoryOperation(intent: {
readonly direction: "apply" | "restore";
readonly resumeHistory: boolean;
readonly legacyMode: boolean;
}): CodexHistoryWorkerOperation {
if (!intent.resumeHistory) return "skip";
if (intent.direction === "restore") return "restore-openai";
return intent.legacyMode ? "apply-opencodex" : "migrate-openai";
}
/**
* The honest failure clause for one history job outcome.
*
* The caller adds its own framing ("sync SKIPPED", "could NOT be restored").
* The point of the surface argument is that a genuine lock keeps today's
* actionable wording, while every other reason stops blaming the Codex app:
* an unsafe-path refusal, an unavailable coordinator database, a permission
* denial, or a dead worker is a different problem with a different remedy.
*/
export function describeHistoryJobFailure(
outcome: CodexHistoryJobOutcome,
surface: "apply" | "restore" | "recover-legacy",
legacyMode = false,
): string {
// Callers only invoke this after observing a failure flag, but that flag is
// derived from "not converged", which also covers "skipped". Naming those
// two kinds keeps a widened or miscast call site from printing `undefined`.
if (outcome.kind === "skipped") {
return "the history operation was skipped; no failure was recorded.";
}
if (outcome.kind === "converged") {
return "the history job reported no failure; run 'ocx doctor' if this is unexpected.";
}
// A busy database reaches here two ways: the lock itself was contended
// (blocked/busy), or the lock was acquired and the worker then found SQLite
// busy (failed with historyFailureReason "busy"). Both are the same user
// situation and deserve the same surface-specific guidance.
const busyText = surface === "apply"
? legacyMode
? "the history DB is locked (Codex app/IDE open?). Close it and rerun 'ocx start'."
: "the history DB is locked (Codex app/IDE open?). It is retried automatically (while the proxy runs and on every 'ocx start'); to force it now, close the Codex app and run 'ocx sync'."
: surface === "recover-legacy"
? "the Codex history DB is locked (Codex app/IDE open?). Close it and rerun this command."
: "the Codex app appears to be holding the history database. Close Codex and run `ocx restore` again.";
const busyStateText = "Codex history state is busy (database, backup manifest, or rollout file); this is not enough evidence to blame the Codex app. It is retried automatically while the proxy runs; run 'ocx doctor' before forcing another attempt.";
if (outcome.kind === "blocked") {
if (outcome.reason === "busy") return busyText;
switch (outcome.reason) {
case "unsafe-path":
return "opencodex refused its history lock path (unsafe coordinator namespace); this is not a Codex app lock. Run 'ocx doctor' and check the opencodex runtime directory.";
case "database":
return "the history coordinator database is unavailable; this is not a Codex app lock. Run 'ocx doctor'.";
case "desired_disabled":
return "Codex integration is disabled, so the history operation was skipped.";
case "desired_enabled":
return "Codex integration is enabled, so the history operation was skipped.";
}
}
const partiallyChanged = (outcome.rows ?? 0) > 0 || (outcome.files ?? 0) > 0;
if (partiallyChanged && outcome.historyFailureReason === "busy") {
return "Codex history metadata changed but did not converge because manifest finalization remained busy; the manifest was retained for review and safe retry. Run 'ocx doctor'.";
}
if (partiallyChanged && outcome.historyFailureReason === "permission") {
return "Codex history metadata changed but did not converge because permission was denied while finalizing the manifest; the manifest was retained for review and safe retry. Run 'ocx doctor'.";
}
if (outcome.historyFailureReason === "busy") return busyStateText;
if (outcome.historyFailureReason === "permission") {
return "permission was denied while writing Codex history; this is not a Codex app lock. Run 'ocx doctor'.";
}
if (outcome.historyFailureReason === "integrity") {
// Not every integrity stop is a retry. An ambiguous reroute means two histories
// produced the same row and no durable fact separates them, so retrying reaches the
// same refusal - the manifest needs a person, and saying "run doctor" sends them the
// wrong way.
if (outcome.historyIntegrityCode === "history_apply_ambiguous_reroute") {
return "a Codex history entry could not be re-routed because its manifest cannot prove whether an earlier relabel was undone; nothing was changed and the manifest was kept. Resolve it manually rather than retrying.";
}
return partiallyChanged
? "the history backup or its restore target changed after a partial restore; the manifest was retained for review and safe retry. Run 'ocx doctor'."
: "the history backup or its restore target failed integrity checks; no unverified provider metadata was applied. Run 'ocx doctor'.";
}
switch (outcome.reason) {
case "worker-error":
return `the history worker failed (${outcome.message}). Run 'ocx doctor'.`;
case "worker-died":
return "the history worker exited unexpectedly; this is not a Codex app lock. Run 'ocx doctor'.";
case "timeout":
return "the history worker timed out; this is not a Codex app lock. Run 'ocx doctor'.";
}
}
/**
* Worker exceptions travel into user-facing CLI output, and a raw filesystem
* error carries absolute paths — on every platform that includes the account
* name (`/Users/x`, `/home/x`, `C:\Users\x`). Folding the home directory to
* `~` keeps the diagnostic value and drops the identifier.
*/
function redactWorkerMessage(message: string): string {
const home = homedir();
if (home.length <= 1) return message;
// Windows spellings vary in case and separator; an exact match would leave
// the account name in the message.
if (process.platform === "win32") {
const escaped = home.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\\\\/g, "[\\\\/]");
return message.replace(new RegExp(escaped, "gi"), "~");
}
return message.split(home).join("~");
}
function classifyWorkerResult(result: HistoryWorkerResult): CodexHistoryJobOutcome {
if (result.type === "blocked") return { kind: "blocked", reason: result.reason };
if (result.type === "error") {
return {
kind: "failed",
reason: "worker-error",
message: redactWorkerMessage(result.message),
...(result.reason ? { historyFailureReason: result.reason } : {}),
...(result.integrityCode ? { historyIntegrityCode: result.integrityCode } : {}),
...(result.rows !== undefined && result.files !== undefined
? { rows: result.rows, files: result.files }
: {}),
};
}
return result.outcome === "skipped"
? { kind: "skipped" }
: { kind: "converged", rows: result.rows, files: result.files, ...(result.proof ? { proof: result.proof } : {}) };
}
/** Test seam for the parent-side Worker result classification contract. */
export function classifyWorkerResultForTests(result: HistoryWorkerResult): CodexHistoryJobOutcome {
return classifyWorkerResult(result);
}
/**
* Run one history unit in a Worker and join it before returning.
*
* The join is not optional politeness: returning while the thread may still be
* mutating CODEX_HOME would let a caller's next step observe a half-applied
* transition, and would let a test suite reach its next file with a worker still
* exiting behind it.
*/
export async function runCodexHistoryJob(
request: CodexHistoryJobRequest,
options: { readonly timeoutMs?: number } = {},
): Promise<CodexHistoryJobOutcome> {
const requestId = randomUUID();
const jobId = randomUUID();
const timeoutMs = options.timeoutMs ?? WORKER_TIMEOUT_MS;
// `skip` writes nothing, so spawning a thread to decide that would be pure
// cost. It still returns a recorded outcome rather than silence.
if (request.operation === "skip") return { kind: "skipped" };
let worker: Worker;
try {
worker = spawnWorker(new URL("./history-worker.ts", import.meta.url).href, "history-worker");
} catch (error) {
return {
kind: "failed",
reason: "worker-died",
message: error instanceof Error ? error.message : "history_worker_spawn_failed",
};
}
return new Promise<CodexHistoryJobOutcome>(resolve => {
let settled = false;
let resolveWorkerClosed!: () => void;
const workerClosed = new Promise<void>(closed => {
resolveWorkerClosed = closed;
});
const finish = (outcome: CodexHistoryJobOutcome) => {
if (settled) return;
settled = true;
clearTimeout(timer);
// Bun 1.3.14 returns void from terminate(); resolving on that return lets
// the Worker outlive this job and, under `bun test --isolate`, its file.
void terminateAndJoinHistoryWorker(worker, workerClosed).then(joined => {
resolve(joined
? outcome
: { kind: "failed", reason: "worker-died", message: "history_worker_close_timeout" });
}, () => {
resolve({ kind: "failed", reason: "worker-died", message: "history_worker_join_failed" });
});
};
const timer = setTimeout(() => {
finish({ kind: "failed", reason: "timeout", message: "history_worker_timeout" });
}, timeoutMs);
const died = (detail: string): void => {
finish({ kind: "failed", reason: "worker-died", message: detail });
};
worker.onmessage = (event: MessageEvent<unknown>) => {
const data = event.data;
if (!data || typeof data !== "object") {
// Not the shape at all: this is a death signal, not silence. Ignoring it
// would let the watchdog call a dead Worker a timeout.
died("history_worker_malformed_message");
return;
}
const message = data as Record<string, unknown>;
// A reply for a different request is somebody else's; ignoring it is not
// the same as accepting it.
if (message.requestId !== requestId) return;
if (message.type !== "done" && message.type !== "blocked" && message.type !== "error") {
died("history_worker_unknown_message_type");
return;
}
if (!isPlausibleWorkerResult(message, requestId, jobId, request)) {
// A recognized type with a missing payload read as `converged` with
// undefined fields once — success for work that may not have happened.
died("history_worker_malformed_payload");
return;
}
finish(classifyWorkerResult(message as unknown as HistoryWorkerResult));
};
/*
* A Worker that exits early — without erroring — is not an error event, so
* without these it surfaced as `timeout` after the full wait. Both are death
* signals. Neither can overturn a settled success: `finish` is idempotent,
* and the Worker always closes after posting its result.
*/
worker.addEventListener("messageerror", () => died("history_worker_unserializable_message"));
worker.addEventListener("close", () => {
resolveWorkerClosed();
died("history_worker_closed_early");
}, { once: true });
worker.onerror = (event: ErrorEvent) => {
finish({
kind: "failed",
reason: "worker-died",
message: event.message || "history_worker_failed",
});
};
worker.postMessage({
type: "run",
requestId,
jobId,
operation: request.operation,
canonicalCodexHome: request.canonicalCodexHome,
canonicalStateDbPath: request.canonicalStateDbPath,
canonicalBackupPath: request.canonicalBackupPath,
...(request.expectedDesiredEnabled === undefined ? {} : { expectedDesiredEnabled: request.expectedDesiredEnabled }),
// A Worker is a fresh module realm: it would otherwise open state_5.sqlite with this
// module's default rather than the timeout this process resolved. Production sends the
// same codex-rs-matching 5s the Worker would have used on its own.
busyTimeoutMs: currentHistoryDbBusyTimeoutMs(),
env: {
...(process.env.CODEX_HOME ? { CODEX_HOME: process.env.CODEX_HOME } : {}),
...(process.env.OPENCODEX_HOME ? { OPENCODEX_HOME: process.env.OPENCODEX_HOME } : {}),
},
});
});
}