@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
392 lines (389 loc) • 24 kB
text/typescript
import { spawn } from "node:child_process";
import { accessSync, constants, lstatSync, mkdirSync,
realpathSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { inspectCodexCliInstall, observeCodexCliSelectedCommand, codexCliMutationEvidence, codexCliMutationSelectionMatches,
type CodexCliInstallProvenanceDeps, type CodexCliInstallReport } from "./cli-install-provenance";
import { createCodexCliUpdatePlan, createNpmConfigIsolation, isolatedNpmTarget,
type CodexCliUpdatePlanDeps } from "./cli-update-plan";
import { codexCliPlatformBacking } from "./cli-install-provenance";
import { verifyCodexCliArchive,
verifiedCodexCliContent, type CodexCliArtifact } from "./cli-update-artifacts";
import { acquireCodexCliApplyLease } from "./cli-update-lease";
import { scanCodexSessionProcessesAsync } from "./app-server-processes";
import { observeCodexCliFileSet, observeCodexCliPreimage, sameCodexCliPreimage, codexCliExpectedFiles, sameCodexCliFiles } from "./cli-update-files";
import type { CodexCliUpdateCommitWindow } from "./cli-update-selection-gate";
import { createCodexCliApplyStaging, observeCodexCliMutationPaths, sameCodexCliMutationPaths } from "./cli-update-paths";
import { codexCliUpdateGroupGone } from "./cli-update-recovery";
export interface CodexCliApplyResult {
readonly outcome: "refused" | "applied" | "not_applied" | "ambiguous";
readonly reason: string;
readonly planId: string;
readonly installedVersion: string | null;
readonly targetVersion: string | null;
readonly installerExitCode: number | null;
readonly leaseRetained: boolean;
readonly verificationPid: number | null;
readonly cleanupErrors: readonly CodexCliApplyCleanupError[];
}
export type CodexCliApplyCleanupError = "lease_release_unverified" | "lease_release_exception" | "staging_cleanup_failed" | "child_cleanup_failed";
/** Every cleanup phase is attempted even if another fails. Preserve the
* computed readback outcome and expose path-free cleanup uncertainty separately.
*/
export function cleanupCodexCliApply(lease: { release(): boolean } | null, staging?: string) {
const cleanupErrors: CodexCliApplyCleanupError[] = [];
let leaseRetained = false;
try { if (lease && !lease.release()) { leaseRetained = true; cleanupErrors.push("lease_release_unverified"); } }
catch { leaseRetained = true; cleanupErrors.push("lease_release_exception"); }
try { if (staging) rmSync(staging, { recursive: true }); }
catch { cleanupErrors.push("staging_cleanup_failed"); }
return Object.freeze({ leaseRetained, cleanupErrors: Object.freeze(cleanupErrors) });
}
interface VersionResult { readonly terminal: boolean; readonly ok: boolean; readonly pid: number | null }
export interface CodexCliApplyDeps extends CodexCliUpdatePlanDeps {
/** Internal Worker lifetime root, never accepted from a request DTO. */
readonly retainExecution?: (owner: object) => { release(): void };
/** Trusted native fault-injection seam; never supplied by a request DTO. */
readonly startWindowsChild?: typeof import("./windows-cli-child").startWindowsCliChild;
readonly signal?: AbortSignal;
/**
* Shared-fence cancellation checkpoint. Unlike signal.aborted this can flip
* DURING a synchronous section: the commit fence lives in shared memory the
* parent CASes, so a cancel landing mid-hash is seen at the next checkpoint
* rather than only on the next event-loop turn.
*/
readonly isCancelled?: () => boolean;
/**
* The worker holds admission from the final process scan through terminal
* installer evidence and readback. commit()'s fence CAS is the last check
* before spawn. Unknown lifetime retains admission until terminal recovery.
* Absent preserves the ungated in-process behavior tests rely on.
*/
readonly commitWindow?: CodexCliUpdateCommitWindow;
readonly temporaryRoot?: string;
readonly fetchArtifact?: (artifact: CodexCliArtifact, signal?: AbortSignal) => Promise<Buffer>;
readonly install?: (invocation: { bin: string; args: readonly string[]; cwd: string; env: NodeJS.ProcessEnv }) => Promise<{ terminal: boolean; exitCode: number | null; recovery?: Promise<void> }>;
readonly acquireLease?: typeof acquireCodexCliApplyLease;
readonly verifyVersion?: typeof verifyInstalledCodexVersion;
}
/** Only this owned verification child may be stopped. A deadline/kill request
* is not terminal evidence: without close the installation lease stays held.
* A new POSIX process group contains the launcher and its native child.
* CODEX_HOME/HOME/TMPDIR isolate even --version's state writes in staging.
*/
export function verifyInstalledCodexVersion(command: string, version: string, cwd: string, env: NodeJS.ProcessEnv,
recovered?: () => void, spawned?: (pid: number) => void): Promise<VersionResult> {
const home = join(cwd, "version-home");
// A setup failure before any child exists is terminal evidence, not an
// unknown lifetime: return it so the caller's lease stays releasable.
try {
mkdirSync(home, { mode: 0o700 });
} catch {
return Promise.resolve({ terminal: true, ok: false, pid: null });
}
return new Promise(resolve => {
let settled = false, failed = false, stopping = false, output = "";
let deadline: ReturnType<typeof setTimeout> | undefined, reap: ReturnType<typeof setTimeout> | undefined;
let recovery: ReturnType<typeof setInterval> | undefined;
// A synchronous spawn throw created no child, so it is the same terminal
// setup evidence; asynchronous spawn errors still arrive as error+close.
let child: ReturnType<typeof spawn>;
try {
child = spawn(command, ["--version"], { cwd, env: { ...env, CODEX_HOME: home, HOME: home, TMPDIR: home,
XDG_CONFIG_HOME: home, XDG_CACHE_HOME: home, XDG_DATA_HOME: home },
stdio: ["ignore", "pipe", "ignore"], windowsHide: true, detached: process.platform !== "win32" });
} catch {
resolve({ terminal: true, ok: false, pid: null });
return;
}
if (child.pid) spawned?.(child.pid);
const groupGone = () => {
if (process.platform === "win32" || !child.pid) return true;
try { process.kill(-child.pid, 0); return false; }
catch (error) { return (error as NodeJS.ErrnoException).code === "ESRCH"; }
};
const finish = (closed: boolean, code: number | null) => {
clearTimeout(deadline); clearTimeout(reap);
const gone = closed && groupGone();
if (settled) { if (gone) { clearInterval(recovery); recovered?.(); } return; }
settled = true;
// Keep observing after the bounded result. A referenced observer lets the
// worker drain only after recovery; close alone still needs group evidence.
if (!gone) recovery = setInterval(() => {
if ((closed || (process.platform !== "win32" && child.pid !== undefined)) && groupGone()) {
clearInterval(recovery); recovered?.();
}
}, 250);
resolve({ terminal: gone, ok: gone && !failed && code === 0 && output.trim() === `codex-cli ${version}`,
pid: gone ? null : child.pid ?? null });
};
const stop = () => {
if (stopping) return;
stopping = true; failed = true;
// Kill only this invocation's new group, never an existing Codex session.
try { if (process.platform !== "win32" && child.pid) process.kill(-child.pid, "SIGKILL"); else child.kill("SIGKILL"); }
catch { /* close/group observation remains the exit proof */ }
child.stdout?.destroy();
reap = setTimeout(() => finish(false, null), 1_000);
};
child.stdout?.on("data", bytes => {
if (Buffer.byteLength(output) + bytes.length > 16 * 1024) stop();
else if (!failed) output += bytes.toString();
});
child.once("error", () => { failed = true; });
child.once("close", code => finish(true, code));
deadline = setTimeout(stop, 8_000);
});
}
/** A close event, not a timeout/error alone, settles a spawned npm child's
* lifetime. Abort during a running child is intentionally deferred: do not
* kill it or release its lease/staging before terminal readback.
*/
function runNpm(invocation: { bin: string; args: readonly string[]; cwd: string; env: NodeJS.ProcessEnv }, capture = false,
spawned?: (pid: number) => void) {
return new Promise<{ terminal: boolean; exitCode: number | null; stdout: string; recovery?: Promise<void> }>(resolve => {
let child: ReturnType<typeof spawn>;
try {
child = spawn(invocation.bin, [...invocation.args], { cwd: invocation.cwd, env: invocation.env,
stdio: ["ignore", capture ? "pipe" : "ignore", "ignore"], windowsHide: true,
detached: !!spawned && process.platform !== "win32" });
} catch { resolve({ terminal: true, exitCode: null, stdout: "" }); return; }
let stdout = "";
let overflow = false;
child.stdout?.on("data", chunk => {
if (stdout.length + chunk.length > 1024 * 1024) overflow = true;
else if (!overflow) stdout += chunk.toString();
});
child.on("error", () => { /* close follows even when spawning failed */ });
child.once("close", code => {
const terminal = !spawned || !child.pid || process.platform === "win32" || codexCliUpdateGroupGone(child.pid);
const recovery = terminal ? undefined : new Promise<void>(done => {
const observer = setInterval(() => { if (codexCliUpdateGroupGone(child.pid!)) { clearInterval(observer); done(); } }, 250);
});
resolve({ terminal, exitCode: overflow ? null : code, stdout, recovery });
});
if (child.pid) spawned?.(child.pid);
});
}
async function packArtifact(artifact: CodexCliArtifact, dir: string, env?: NodeJS.ProcessEnv): Promise<string> {
const isolation = createNpmConfigIsolation(dir, env);
const invocation = isolatedNpmTarget(["pack", `${artifact.name}@${artifact.version}`, "--json", "--ignore-scripts",
"--pack-destination", dir, "--fetch-retries=0", "--fetch-timeout=120000"], isolation);
if (!invocation) throw new Error("npm_unavailable");
const packed = await runNpm({ bin: invocation.bin, args: invocation.args, cwd: isolation.dir, env: isolation.env }, true);
if (packed.exitCode !== 0) throw new Error("artifact_pack_failed");
const files = JSON.parse(packed.stdout);
if (!Array.isArray(files) || files.length !== 1 || typeof files[0]?.filename !== "string"
|| !/^[A-Za-z0-9][A-Za-z0-9._-]*\.tgz$/.test(files[0].filename)) throw new Error("artifact_pack_unverified");
const path = join(dir, files[0].filename);
if (realpathSync.native(path) !== path) throw new Error("artifact_pack_unverified");
return path;
}
function freshInspection(deps: CodexCliApplyDeps): CodexCliInstallProvenanceDeps {
const inspection = { ...(deps.inspectionDeps ?? {}), platform: deps.platform ?? deps.inspectionDeps?.platform,
observeInstallContent: true };
return { ...inspection, selectedCommand: observeCodexCliSelectedCommand(inspection) };
}
/** POSIX non-shim transaction; Windows dispatches to its separately owned native transaction. */
export async function applyCodexCliUpdate(planId: string, deps: CodexCliApplyDeps = {}): Promise<CodexCliApplyResult> {
let installedVersion: string | null = null;
let targetVersion: string | null = null;
let exitCode: number | null = null;
let lease: { release(): boolean } | null = null;
let keepLease = false;
let staging: string | undefined;
let started = false;
let verificationPid: number | null = null;
let output: CodexCliApplyResult | undefined;
let windowHeld = false;
const recover = () => {
cleanupCodexCliApply(lease, staging);
if (windowHeld) deps.commitWindow?.exit();
};
const result = (outcome: CodexCliApplyResult["outcome"], reason: string): CodexCliApplyResult =>
output = { outcome, reason, planId, installedVersion, targetVersion, installerExitCode: exitCode, leaseRetained: keepLease, verificationPid, cleanupErrors: [] };
// Both cancellation channels are consulted at every checkpoint: the plain
// AbortSignal for in-process callers and the shared-fence isCancelled for a
// worker whose cancel lands mid-synchronous-section on the parent's loop.
const cancelled = (): boolean => deps.signal?.aborted === true || deps.isCancelled?.() === true;
try {
if (!/^[0-9a-f]{32}$/.test(planId)) return result("refused", "invalid_plan_id");
if ((deps.platform ?? process.platform) === "win32") {
const { applyWindowsCodexCliUpdate } = await import("./cli-update-windows-apply");
return applyWindowsCodexCliUpdate(planId, deps);
}
if (cancelled()) return result("refused", "cancelled");
const inspect = deps.inspect ?? inspectCodexCliInstall;
const first = await inspect(freshInspection(deps));
installedVersion = first.packageVersion;
const evidence = codexCliMutationEvidence(first);
if (!first.managed || !evidence || first.shim.status !== "not-tracked") return result("refused", "mutation_evidence_unverified");
const prefix = realpathSync.native(evidence.prefix);
if (prefix !== evidence.prefix) return result("refused", "installation_prefix_changed");
const prefixIdentity = lstatSync(prefix);
const acquired = (deps.acquireLease ?? acquireCodexCliApplyLease)(prefix);
if (acquired.kind === "prefix_unsupported") return result("refused", "installation_prefix_unsupported");
if (acquired.kind === "busy") return result("refused", "installation_busy");
if (acquired.kind !== "acquired") return result("refused", "installation_lease_unavailable");
lease = acquired;
let mutationPaths;
try { mutationPaths = observeCodexCliMutationPaths(prefix); }
catch { return result("refused", "installation_paths_untrusted"); }
const freshPlan = () => createCodexCliUpdatePlan({ ...deps, inspectionDeps: freshInspection(deps) });
const plan = await freshPlan();
targetVersion = plan.targetVersion;
if (!plan.applicable) return result("refused", plan.refusal ?? "plan_refused");
if (plan.planId !== planId) return result("refused", "plan_changed");
const artifacts = plan.targetArtifacts;
if (!artifacts || artifacts.platform !== (deps.platform ?? process.platform)
|| artifacts.arch !== (deps.inspectionDeps?.arch ?? process.arch)) return result("refused", "target_artifacts_unverified");
try { staging = createCodexCliApplyStaging(deps.temporaryRoot ?? tmpdir()); }
catch { return result("refused", "staging_path_untrusted"); }
const stagingIdentity = lstatSync(staging);
const paths: string[] = [];
for (const [index, artifact] of [artifacts.main, artifacts.backing].entries()) {
let path: string;
if (deps.fetchArtifact) {
const bytes = await deps.fetchArtifact(artifact, deps.signal);
path = join(staging, `${index}.tgz`);
writeFileSync(path, bytes, { flag: "wx", mode: 0o400 });
} else path = await packArtifact(artifact, staging, deps.inspectionDeps?.env);
paths.push(path);
}
if (cancelled()) return result("refused", "cancelled");
const main = await verifyCodexCliArchive(paths[0]!, artifacts.main);
const backing = await verifyCodexCliArchive(paths[1]!, artifacts.backing);
const expectedContent = verifiedCodexCliContent(artifacts, main, backing);
const targetMainRoot = join(prefix, "lib", "node_modules", ...artifacts.main.installName.split("/"));
const backingRoot = join(prefix, "lib", "node_modules", ...artifacts.backing.installName.split("/"));
const originalRoots = [evidence.packageRoot, ...(evidence.backingRoot ? [evidence.backingRoot] : []), targetMainRoot, backingRoot];
const original = observeCodexCliPreimage(originalRoots);
// Metadata, content, selection and process observation are renewed after
// potentially slow downloads; the awaited process scan is the last yield
// before install, and a synchronous identity/preimage/selection guard runs
// in the same event-loop turn as the spawn.
const finalPlan = await freshPlan();
if (!finalPlan.applicable) return result("refused", finalPlan.refusal ?? "plan_refused");
if (finalPlan.planId !== planId) return result("refused", "plan_changed");
const beforeInstall = await inspect(freshInspection(deps));
const selected = codexCliMutationEvidence(beforeInstall);
const currentPrefix = lstatSync(prefix);
if (!selected || selected.prefix !== prefix || selected.launcher !== evidence.launcher
|| selected.canonicalLauncher !== evidence.canonicalLauncher || selected.packageRoot !== evidence.packageRoot
|| beforeInstall.installContentDigest !== plan.installContentDigest || !beforeInstall.managed
|| realpathSync.native(prefix) !== prefix || currentPrefix.dev !== prefixIdentity.dev
|| currentPrefix.ino !== prefixIdentity.ino) return result("refused", "installation_changed");
if (cancelled()) return result("refused", "cancelled");
const isolation = createNpmConfigIsolation(staging, deps.inspectionDeps?.env);
isolation.env.TMPDIR = isolation.env.TEMP = isolation.env.TMP = staging;
const args = ["install", "-g", "--prefix", prefix, "--offline", "--ignore-scripts", "--omit=optional",
"--no-audit", "--no-fund", "--package-lock=false", "--update-notifier=false",
`${artifacts.main.installName}@file:${paths[0]}`, `${artifacts.backing.installName}@file:${paths[1]}`];
const invocation = isolatedNpmTarget(args, isolation);
if (!invocation) return result("refused", "npm_unavailable");
// The shared selection gate serializes this commit window against the
// parent's own selection writers and session-spawn paths, which a worker
// realm can no longer exclude just by occupying its own event-loop turn.
// waitEnter can yield while a parent writer holds the gate, so the final
// process observation is taken only after the window is held; a gate that
// stays busy or a cancel that lands first refuses before the spawn.
const commitWindow = deps.commitWindow;
if (commitWindow) {
windowHeld = commitWindow.tryEnter() || await commitWindow.waitEnter();
if (!windowHeld) return result("refused", cancelled() ? "cancelled" : "installation_busy");
}
const lastScan = deps.scanProcessesAsync
? await deps.scanProcessesAsync(deps.processIo ?? {})
: deps.scanProcesses
? deps.scanProcesses(deps.processIo ?? {})
: await scanCodexSessionProcessesAsync(deps.processIo ?? {});
if (lastScan.kind !== "observed") return result("refused", "blocked_process_state_unknown");
if (lastScan.processes.length) return result("refused", "blocked_active_session");
// Every earlier await could have yielded the event loop to a mutation of
// the install tree, the prefix or the selected command, so the last turn
// before spawn re-verifies them synchronously: prefix identity, the
// byte-level preimage taken before the downloads, the launcher's live
// canonical selection and the signal. Nothing can interleave between
// this block and the install invocation on the same event-loop turn,
// and the held gate keeps the gated parent operations out of the window.
if (cancelled()) return result("refused", "cancelled");
try {
if (!sameCodexCliMutationPaths(mutationPaths, observeCodexCliMutationPaths(prefix))) {
return result("refused", "installation_paths_untrusted");
}
} catch { return result("refused", "installation_paths_untrusted"); }
try {
observeCodexCliMutationPaths(staging);
const stage = lstatSync(staging);
if (stage.dev !== stagingIdentity.dev || stage.ino !== stagingIdentity.ino) {
return result("refused", "staging_path_untrusted");
}
} catch { return result("refused", "staging_path_untrusted"); }
const lastPrefix = lstatSync(prefix);
if (realpathSync.native(prefix) !== prefix || lastPrefix.dev !== prefixIdentity.dev
|| lastPrefix.ino !== prefixIdentity.ino
|| !sameCodexCliPreimage(original, observeCodexCliPreimage(originalRoots))
|| !codexCliMutationSelectionMatches(evidence, freshInspection(deps))) {
return result("refused", "installation_changed");
}
// The commit CAS is the final synchronous guard: a cancel already
// landed wins and no spawn happens; once COMMITTED, a later cancel is
// deferred to the live installer's close and readback.
if (commitWindow && !commitWindow.commit()) return result("refused", "cancelled");
started = true;
keepLease = true;
// Admission remains exclusive through installer termination AND readback.
// Unknown child lifetime retains both the lease and this process gate.
const invocationArgs = { bin: invocation.bin, args: invocation.args, cwd: isolation.dir, env: isolation.env };
const installPromise = deps.install ? deps.install(invocationArgs)
: runNpm(invocationArgs, false, pid => deps.commitWindow?.childStarted?.(pid));
const installed = await installPromise;
exitCode = installed.exitCode;
if (!installed.terminal) {
if ("recovery" in installed) void installed.recovery?.then(recover);
return result("ambiguous", "installer_state_unknown");
}
keepLease = false;
// Readback outranks exit code. Partial or unreadable installs are never retried.
const after: CodexCliInstallReport = await inspect(freshInspection(deps));
const afterEvidence = codexCliMutationEvidence(after);
installedVersion = after.packageVersion;
const prefixAfter = lstatSync(prefix);
if (realpathSync.native(prefix) !== prefix || prefixAfter.dev !== prefixIdentity.dev || prefixAfter.ino !== prefixIdentity.ino) {
return result("ambiguous", "installation_prefix_changed");
}
if (after.managed && afterEvidence?.prefix === prefix && afterEvidence.launcher === evidence.launcher
&& after.packageVersion === targetVersion && after.installContentDigest === expectedContent
&& sameCodexCliFiles(codexCliExpectedFiles([[afterEvidence.packageRoot, main], [backingRoot, backing]]),
observeCodexCliFileSet([afterEvidence.packageRoot, backingRoot]))
&& codexCliMutationSelectionMatches(afterEvidence, freshInspection(deps))) {
const layout = codexCliPlatformBacking(artifacts.platform, artifacts.arch)!;
accessSync(afterEvidence.launcher, constants.X_OK);
accessSync(join(backingRoot, "vendor", layout.triple, "bin", "codex"), constants.X_OK);
deps.commitWindow?.childStarting?.();
keepLease = true;
const version = await (deps.verifyVersion ?? verifyInstalledCodexVersion)(afterEvidence.launcher, targetVersion!, staging, isolation.env,
recover, pid => deps.commitWindow?.childStarted?.(pid));
verificationPid = version.pid;
if (!version.terminal) return result("ambiguous", "version_process_state_unknown");
keepLease = false;
if (!version.ok || !codexCliMutationSelectionMatches(afterEvidence, freshInspection(deps))) return result("ambiguous", "version_readback_unverified");
return result("applied", "verified_target");
}
if (afterEvidence?.prefix === prefix && after.managed && after.packageVersion === first.packageVersion
&& after.installContentDigest === plan.installContentDigest
&& sameCodexCliPreimage(original, observeCodexCliPreimage(originalRoots))
&& codexCliMutationSelectionMatches(afterEvidence, freshInspection(deps))) return result("not_applied", "original_install_unchanged");
return result("ambiguous", "installation_readback_unverified");
} catch {
return result(started ? "ambiguous" : "refused", started ? "installer_or_readback_error" : "preparation_failed");
} finally {
if (!keepLease) {
const cleanup = cleanupCodexCliApply(lease, staging);
if (output) Object.assign(output, cleanup);
if (windowHeld) deps.commitWindow?.exit();
}
if (output) { Object.freeze(output.cleanupErrors); Object.freeze(output); }
}
}