UNPKG

@bitkyc08/opencodex

Version:

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

306 lines (286 loc) • 14.8 kB
/** * Shared commit fence and selection gate for the Codex CLI update worker. * * The update's last synchronous turn (final process scan, prefix/preimage/ * selection guards, installer spawn) runs inside a Worker realm now, so the * old same-event-loop-turn argument no longer excludes the parent's own * selection-mutating operations or its session-spawn paths. Two shared-memory * primitives carry that exclusion across realms: * * - FENCE (one per dispatched job): the parent's only cancellation word is * PREPARING -> CANCELLED, and the worker's only commit word is * PREPARING -> COMMITTED. Exactly one compareExchange wins. A cancel that * lands first is observed by the worker's isCancelled checkpoints and by * the commit CAS losing; a commit that lands first means the npm spawn * already happened and a late cancel is deferred to readback. * * - GATE (one process-wide holder plus generation counter): PARENT_WRITE belongs to the five * parent selection writers (runtime pin persist/clear, shim install/ * auto-restore/uninstall) and the two parent session-spawn paths (remote * workspace child, desktop relaunch). A unique worker generation is taken by the * update worker through installer termination and post-install readback. * Writers report busy rather than wait: a synchronous parent writer * must never park the event loop behind it. The gate is intentionally one * cell for the whole process rather than per-configDir: alias/junction/case * spellings of the same target must not split the exclusion, so a writer on * a different configDir can also see busy until the installation settles. * * This module claims nothing about processes it does not own: an external * installer, a late descendant of an earlier child, or an OS snapshot race * stays the documented residual it always was. */ import { codexCliUpdateRecoveryBlocksAdmission, codexCliUpdateRecoveryBlocksAdmissionAsync } from "./cli-update-recovery"; import type { CodexCliUpdateNativeChildIdentity, CodexCliUpdateNativeRecoveryProof } from "./cli-update-recovery"; import { getConfigDir } from "../config/paths"; import { resolve } from "node:path"; export const CODEX_CLI_UPDATE_FENCE_PREPARING = 0; export const CODEX_CLI_UPDATE_FENCE_CANCELLED = 1; export const CODEX_CLI_UPDATE_FENCE_COMMITTED = 2; export const CODEX_CLI_UPDATE_FENCE_RECOVERING = 3; export const CODEX_CLI_UPDATE_GATE_FREE = 0; export const CODEX_CLI_UPDATE_GATE_PARENT_WRITE = 1; export const CODEX_CLI_UPDATE_GATE_WORKER_COMMIT = 2; /** Bounded wait for a parent writer's window; the worker then refuses busy. */ const WORKER_COMMIT_WAIT_DEADLINE_MS = 30_000; export class CodexCliSelectionMutationBusyError extends Error { constructor(message = "codex_cli_selection_busy") { super(message); this.name = "CodexCliSelectionMutationBusyError"; } } let selectionGate: SharedArrayBuffer | null = null; let asyncParentOwner: { buffer: SharedArrayBuffer; owner: number } | null = null; // This scope exists only during one synchronous commit turn. It is never kept // across an await, so unrelated parent requests cannot borrow its admission. let parentCommitScope: { buffer: SharedArrayBuffer; owner: number; configDir: string } | null = null; /** One process-wide holder and monotonic generation counter shared across realms. */ export function codexCliUpdateSelectionGate(): SharedArrayBuffer { selectionGate ??= new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * 2); return selectionGate; } /** Diagnostic classification does not grant or release gate ownership. */ export function codexCliSelectionGateState(): "free" | "parent_write" | "worker_commit" | "unrecognized" { const buffer = codexCliUpdateSelectionGate(), owner = Atomics.load(new Int32Array(buffer), 0); if (owner === CODEX_CLI_UPDATE_GATE_FREE) return "free"; if (owner === CODEX_CLI_UPDATE_GATE_PARENT_WRITE || (asyncParentOwner?.buffer === buffer && asyncParentOwner.owner === owner)) return "parent_write"; return owner >= CODEX_CLI_UPDATE_GATE_WORKER_COMMIT ? "worker_commit" : "unrecognized"; } /** Test seam: drop the cell so each case starts from FREE on a fresh buffer. */ export function resetCodexCliSelectionGatesForTests(): void { selectionGate = null; asyncParentOwner = null; } /** Per-job fence: decision, current child pgid (0 = unpublished), terminal proof. */ export function createCodexCliUpdateFence(): SharedArrayBuffer { return new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * 3); } /** The holder word IS the generation: one CAS releases exactly one owner. */ export function allocateCodexCliUpdateGateOwner(buffer: SharedArrayBuffer): number { const view = new Int32Array(buffer); for (;;) { const sequence = Atomics.load(view, 1); if (sequence >= 0x7ffffffd) throw new Error("cli_update_gate_generation_exhausted"); if (Atomics.compareExchange(view, 1, sequence, sequence + 1) === sequence) { return sequence + CODEX_CLI_UPDATE_GATE_WORKER_COMMIT; } } } export function releaseCodexCliUpdateGateOwner(buffer: SharedArrayBuffer, owner: number): void { Atomics.compareExchange(new Int32Array(buffer), 0, owner, CODEX_CLI_UPDATE_GATE_FREE); } /** Parent cancel word. True only when this CAS took PREPARING -> CANCELLED. */ export function cancelCodexCliUpdateFence(fence: SharedArrayBuffer): boolean { return Atomics.compareExchange(new Int32Array(fence), 0, CODEX_CLI_UPDATE_FENCE_PREPARING, CODEX_CLI_UPDATE_FENCE_CANCELLED) === CODEX_CLI_UPDATE_FENCE_PREPARING; } /** * The worker-side cancellation checkpoint fed to apply's isCancelled hook. * COMMITTED is deliberately not "cancelled": once the commit CAS lands the * installer is a live child whose close must be observed, not a cancel. */ export function codexCliUpdateIsCancelled(fence: SharedArrayBuffer): () => boolean { const view = new Int32Array(fence); return () => Atomics.load(view, 0) === CODEX_CLI_UPDATE_FENCE_CANCELLED; } export interface CodexCliSelectionParentWrite { readonly entered: boolean; /** Idempotent release; safe to call from both branches of a spawn attempt. */ exit(): void; } /** * Non-blocking acquisition for the parent selection writers and session-spawn * paths. entered === false means a commit window (or another writer) is in * flight and the caller must surface busy immediately, never wait. */ export function beginCodexCliSelectionParentWrite(configDir = getConfigDir()): CodexCliSelectionParentWrite { if (parentCommitScope) { const entered = resolve(configDir) === parentCommitScope.configDir && Atomics.load(new Int32Array(parentCommitScope.buffer), 0) === parentCommitScope.owner; return Object.freeze({ entered, exit() {} }); } if (codexCliUpdateRecoveryBlocksAdmission(configDir)) return Object.freeze({ entered: false, exit() {} }); const view = new Int32Array(codexCliUpdateSelectionGate()); if (Atomics.compareExchange(view, 0, CODEX_CLI_UPDATE_GATE_FREE, CODEX_CLI_UPDATE_GATE_PARENT_WRITE) !== CODEX_CLI_UPDATE_GATE_FREE) { return Object.freeze({ entered: false, exit() { /* nothing held */ } }); } let held = true; return Object.freeze({ entered: true, exit() { if (!held) return; held = false; Atomics.compareExchange(view, 0, CODEX_CLI_UPDATE_GATE_PARENT_WRITE, CODEX_CLI_UPDATE_GATE_FREE); }, }); } type SynchronousParentCommit<T> = () => T & (T extends PromiseLike<unknown> ? never : unknown); export interface CodexCliSelectionAsyncParentWrite extends CodexCliSelectionParentWrite { /** Run existing synchronous writers under this exact fresh admission. Never await inside. */ commit<T>(run: SynchronousParentCommit<T>): T; } interface ParentAdmissionOptions { configDir?: string; signal?: AbortSignal; /** Test seam; production always uses the fresh async recovery protocol. */ recoveryBlocksAdmission?: (configDir?: string) => Promise<boolean>; } /** Reserve before inspection, keep the generation across awaits, and release only that owner. */ export async function beginCodexCliSelectionParentWriteAsync(options: ParentAdmissionOptions = {}): Promise<CodexCliSelectionAsyncParentWrite> { const refused = Object.freeze({ entered: false, exit() {}, commit<T>(_run: SynchronousParentCommit<T>): T { throw new CodexCliSelectionMutationBusyError(); } }); if (options.signal?.aborted) return refused; const configDir = resolve(options.configDir ?? getConfigDir()); const buffer = codexCliUpdateSelectionGate(), view = new Int32Array(buffer); const owner = allocateCodexCliUpdateGateOwner(buffer); if (Atomics.compareExchange(view, 0, CODEX_CLI_UPDATE_GATE_FREE, owner) !== CODEX_CLI_UPDATE_GATE_FREE) return refused; const parent = { buffer, owner }; asyncParentOwner = parent; let held = true; const exit = () => { if (!held) return; held = false; releaseCodexCliUpdateGateOwner(buffer, owner); if (asyncParentOwner === parent) asyncParentOwner = null; }; try { if (await (options.recoveryBlocksAdmission ?? codexCliUpdateRecoveryBlocksAdmissionAsync)(configDir) || options.signal?.aborted || Atomics.load(view, 0) !== owner) { exit(); return refused; } } catch { exit(); return refused; } return Object.freeze({ entered: true, exit, commit<T>(run: SynchronousParentCommit<T>): T { if (!held || options.signal?.aborted || Atomics.load(view, 0) !== owner) throw new CodexCliSelectionMutationBusyError(); const previous = parentCommitScope; parentCommitScope = { buffer, owner, configDir }; try { return run(); } finally { parentCommitScope = previous; } }, }); } /** The callback is synchronous: config critical sections retain their original no-await contract. */ export async function withCodexCliSelectionParentWriteAsync<T>(run: SynchronousParentCommit<T>, options: ParentAdmissionOptions = {}): Promise<T> { const admission = await beginCodexCliSelectionParentWriteAsync(options); if (!admission.entered) throw new CodexCliSelectionMutationBusyError(); try { return admission.commit<T>(run); } finally { admission.exit(); } } /** * The worker's installation window. tryEnter covers the uncontended same-turn * case; waitEnter is the bounded retry for a held parent write. commit() is * the fence CAS issued in the same event-loop turn as the installer spawn; * exit() releases the gate after terminal installer evidence and readback. * Unknown installer/verifier lifetime intentionally leaves admission closed. */ export interface CodexCliUpdateCommitWindow { tryEnter(): boolean; waitEnter(): Promise<boolean>; commit(): boolean; childStarting?(jobName?: string): CodexCliUpdateNativeRecoveryProof | void; childStarted?(pid: number, identity?: CodexCliUpdateNativeChildIdentity): void; exit(): void; } export function createWorkerCommitWindow(options: { readonly gate: SharedArrayBuffer; readonly fence: SharedArrayBuffer; readonly owner?: number; readonly recovery?: { arm(jobName?: string): CodexCliUpdateNativeRecoveryProof | void; child(pid: number, identity?: CodexCliUpdateNativeChildIdentity): void; terminal(): void }; readonly deadlineMs?: number; /** Test seam: observe/back-off without real sleeps. */ readonly sleep?: (ms: number) => Promise<void>; }): CodexCliUpdateCommitWindow { const gate = new Int32Array(options.gate); const fence = new Int32Array(options.fence); const owner = options.owner ?? allocateCodexCliUpdateGateOwner(options.gate); const deadlineMs = options.deadlineMs ?? WORKER_COMMIT_WAIT_DEADLINE_MS; const sleep = options.sleep ?? (ms => new Promise<void>(resolve => setTimeout(resolve, ms))); const cancelled = () => Atomics.load(fence, 0) === CODEX_CLI_UPDATE_FENCE_CANCELLED; let held = false; let cleanupRetry: ReturnType<typeof setInterval> | undefined; const release = () => { try { options.recovery?.terminal(); } catch { return false; } held = false; releaseCodexCliUpdateGateOwner(options.gate, owner); return true; }; return Object.freeze({ tryEnter() { if (cancelled()) return false; if (!held && Atomics.compareExchange(gate, 0, CODEX_CLI_UPDATE_GATE_FREE, owner) === CODEX_CLI_UPDATE_GATE_FREE) { held = true; } if (held && cancelled()) { held = false; releaseCodexCliUpdateGateOwner(options.gate, owner); } return held; }, async waitEnter() { const deadline = Date.now() + deadlineMs; while (!held && !cancelled()) { if (Atomics.compareExchange(gate, 0, CODEX_CLI_UPDATE_GATE_FREE, owner) === CODEX_CLI_UPDATE_GATE_FREE) { held = true; if (cancelled()) { held = false; releaseCodexCliUpdateGateOwner(options.gate, owner); } break; } if (Date.now() >= deadline) break; await sleep(1); } return held; }, commit() { if (!held || Atomics.load(gate, 0) !== owner || cancelled()) return false; options.recovery?.arm(); // durable uncertainty precedes any possible spawn return Atomics.compareExchange(fence, 0, CODEX_CLI_UPDATE_FENCE_PREPARING, CODEX_CLI_UPDATE_FENCE_COMMITTED) === CODEX_CLI_UPDATE_FENCE_PREPARING; }, childStarting(jobName?: string) { Atomics.store(fence, 1, 0); // Publish uncertainty BEFORE competing with parent recovery's seal. // A close notification may precede full thread exit; no next child can // start after the parent has sealed COMMITTED for recovery. if (Atomics.compareExchange(fence, 0, CODEX_CLI_UPDATE_FENCE_COMMITTED, CODEX_CLI_UPDATE_FENCE_COMMITTED) !== CODEX_CLI_UPDATE_FENCE_COMMITTED) throw new Error("cli_update_owner_recovering"); const proof = options.recovery?.arm(jobName); // Close may seal RECOVERING while durable arming is in progress. No native // successor may start after that seal, even if arming observed a marker. if (Atomics.load(fence, 0) !== CODEX_CLI_UPDATE_FENCE_COMMITTED || Atomics.load(gate, 0) !== owner) { throw new Error("cli_update_owner_recovering"); } return proof; }, childStarted(pid: number, identity?: CodexCliUpdateNativeChildIdentity) { // Publication follows spawn in the same turn. Death in the gap stays unknown. options.recovery?.child(pid, identity); Atomics.store(fence, 1, pid); }, exit() { if (!held) return; // Caller has proven no child remains. Publish that proof even if the // durable receipt temporarily cannot be written; parent close can retry. Atomics.store(fence, 2, 1); if (release() || cleanupRetry) return; cleanupRetry = setInterval(() => { if (release()) clearInterval(cleanupRetry); }, 250); }, }); }