UNPKG

@bitkyc08/opencodex

Version:

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

401 lines (373 loc) • 18.3 kB
/** * Full restart of the Codex desktop app (the Electron shell) on macOS, Linux and * Windows. * * WHY THIS EXISTS AT ALL. `--restart-codex` used to signal only `codex app-server` / * `codex-code-mode-host` processes, and on every platform that turns out not to * refresh the model picker. The app-server it signals is a CHILD of the desktop app * (measured: pid 16733 under pid 15901 on macOS, 3285204 under 3284901 on Linux), so * the app simply respawns it while the renderer keeps the roster it built at launch. * The matcher was never the problem; the only thing that reliably refreshes the * picker is restarting the shell that owns it. * * WHY THE CONSENT CHANGED. This capability was deliberately kept behind a separate * Windows-only `--restart-desktop-app` flag, because quitting the app ends live * conversations and that is a larger consent than restarting a background helper. * That reasoning was sound and has been superseded by an explicit maintainer * decision: `--restart-codex` now means the app is fully stopped and started again. * The narrow behaviour did not disappear, it moved to `--restart-app-server-only`. * * WHAT IS SHARED AND WHAT IS NOT. The ladder below — discover, enumerate, find * shells, check self-ancestry, graceful, wait, re-verify identity, force, wait, * refuse-or-relaunch — is identical on all three platforms. Only identity, * discovery, membership, the two stop primitives and relaunch differ, and those live * behind DesktopAppAdapter. Re-deriving the PID-reuse and fail-closed reasoning once * per operating system is how two of the three end up subtly wrong. * * EVERYTHING FAILS CLOSED. A failed discovery, a failed enumeration, an unreadable * process identity or an unreadable ancestry chain never authorises a kill and is * never reported as "nothing to do". A stale picker is a much smaller problem than a * wrongly killed process. * * Design and audit history: devlog/_fin/260913_cross_platform_desktop_app_restart/. */ import { acquireDesktopRestartLock, releaseDesktopRestartLock, type DesktopRestartLockIo, } from "./desktop-app/lock"; import { rootShells, type DesktopAppAdapter, type DesktopExec, type DesktopProcess } from "./desktop-app/types"; import { darwinDesktopAppAdapter, darwinDefaultExec } from "./desktop-app/darwin"; import { linuxDesktopAppAdapter, linuxDefaultExec } from "./desktop-app/linux"; import { windowsDesktopAppAdapter, windowsDefaultExec } from "./desktop-app/windows"; import { isTestHomeGuardArmed } from "../lib/test-home-guard"; import { beginCodexCliSelectionParentWrite, withCodexCliSelectionParentWriteAsync, CodexCliSelectionMutationBusyError } from "./cli-update-selection-gate"; export type { DesktopAppExecOptions } from "./desktop-app/types"; /** How long a graceful close is given before the forced pass. */ const GRACEFUL_EXIT_TIMEOUT_MS = 15_000; /** How long a forced kill is given before the target counts as surviving. */ const FORCED_EXIT_TIMEOUT_MS = 5_000; export interface DesktopAppRestartHandoff { helperPid: number; logPath: string; } export interface DesktopAppRestartIo { platform?: NodeJS.Platform; /** Overrides the adapter chosen from `platform`. Tests drive every branch through this. */ adapter?: DesktopAppAdapter; execFile?: DesktopExec; /** Process ancestry of the current process, innermost first. Used for the self-kill guard. */ ancestryPids?: () => number[]; isAlive?: (pid: number) => boolean; sleep?: (ms: number) => void; now?: () => number; lock?: DesktopRestartLockIo; /** * Hand the restart to a detached helper when this process is inside the tree. * Supplied by wp5; absent here means the ladder refuses instead, which is the * behaviour that shipped before the handoff existed. */ startHandoff?: () => DesktopAppRestartHandoff | null; /** * False forbids a handoff. The helper passes it so recursion is structurally * impossible, and the management service passes it because it runs inside a proxy * that never exits — a handoff waiting for the caller to exit would always time out * after telling the operator it had been handed off. */ allowHandoff?: boolean; } export type DesktopAppRestartReason = | "unsupported_platform" | "test_environment" | "package_discovery_failed" | "process_probe_failed" | "no_targets" | "self_ancestry" | "restart_in_flight" | "handoff_started" | "relaunch_context_failed" | "selection_mutation_busy" | "targets_survived" | "relaunch_failed"; export interface DesktopAppRestartResult { attempted: boolean; stopped: number[]; surviving: number[]; relaunch: "started" | "skipped"; reason?: DesktopAppRestartReason; handoff?: DesktopAppRestartHandoff; } const ADAPTERS: Partial<Record<NodeJS.Platform, { adapter: DesktopAppAdapter; exec: DesktopExec }>> = { darwin: { adapter: darwinDesktopAppAdapter, exec: darwinDefaultExec }, linux: { adapter: linuxDesktopAppAdapter, exec: linuxDefaultExec }, win32: { adapter: windowsDesktopAppAdapter, exec: windowsDefaultExec }, }; function defaultIsAlive(pid: number): boolean { try { process.kill(pid, 0); return true; } catch { return false; } } function defaultSleep(ms: number): void { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } /** * True when the pid still names the process we verified. * * Between listing and signalling there is a graceful-close window long enough for the * OS to recycle a pid, and the next step is a hard kill. A pid alone is not an * identity across that window; the start-time token is what distinguishes a process * from its replacement. */ type IdentityCheck = "same" | "gone" | "unknown"; function checkIdentity( adapter: DesktopAppAdapter, exec: DesktopExec, install: Parameters<DesktopAppAdapter["listProcesses"]>[1], target: DesktopProcess, ): IdentityCheck { const processes = adapter.listProcesses(exec, install); // THREE outcomes, not two. Collapsing them into a boolean is what made this ladder // claim a restart it never performed: a re-probe that could not RUN looked identical // to a process that had exited, and the caller recorded the pid as stopped, skipped // the forced pass, and relaunched into an app that was still running - reporting // success the whole way. Measured on a real Windows host, where the app kept its // original pid and start time through a restart that said it had stopped it. if (processes === null) return "unknown"; const current = processes.find(entry => entry.pid === target.pid); if (current === undefined) return "gone"; // Same pid, different start time: the pid was recycled and now belongs to somebody // else. Treated as gone, because the process we meant to stop no longer exists and // signalling this pid would hit an unrelated process. return current.createdAt === target.createdAt ? "same" : "gone"; } /** * Pids of the running desktop-app tree, or null when discovery or the probe failed. * * Read-only. Used by the CLI to exclude app-servers the desktop restart is about to * take anyway, so an operator\u2019s in-flight turn is not interrupted twice in one command. */ /** * Poll the platform's own process list until it stops listing this process. * * A single post-kill enumeration is not enough. Measured on Windows: `taskkill /T /F` * succeeds, the process is genuinely dead a moment later, and yet the very next * `Win32_Process` query still lists it. Checking once turned that lag into a reported * survivor, which blocked the relaunch and left the machine with no app at all - the * failure mode is the mirror of claiming a stop that never happened, and just as bad. * * Liveness is polled first because it is cheap; the enumeration is what decides. A probe * that cannot run keeps the loop going rather than deciding either way, and if the * deadline passes without a clean "gone" the caller treats it as a survivor. */ function waitUntilGone( adapter: DesktopAppAdapter, exec: DesktopExec, install: Parameters<DesktopAppAdapter["listProcesses"]>[1], target: DesktopProcess, timeoutMs: number, isAlive: (pid: number) => boolean, sleep: (ms: number) => void, now: () => number, ): boolean { const deadline = now() + timeoutMs; for (;;) { if (!isAlive(target.pid) && checkIdentity(adapter, exec, install, target) === "gone") return true; if (now() >= deadline) break; sleep(250); } // One last look after the deadline, so a process that exited during the final sleep is // not reported as surviving purely because of poll timing. return checkIdentity(adapter, exec, install, target) === "gone"; } export function listCodexDesktopAppPids(io: DesktopAppRestartIo = {}): number[] | null { const platform = io.platform ?? process.platform; const selected = ADAPTERS[platform]; const adapter = io.adapter ?? selected?.adapter; if (!adapter) return null; const exec = io.execFile ?? selected?.exec; if (!exec) return null; const install = adapter.discover(exec); if (!install) return null; const processes = adapter.listProcesses(exec, install); return processes === null ? null : processes.map(entry => entry.pid); } /** * Pids of the running desktop-app ROOT shells, or null when discovery or the probe failed. * * Read-only. The shell is the process whose renderer built the model picker, so its start * time is what tells `performCodexRestart` whether the picker predates the catalog (#4761). * `[]` means the probe ran and the app is not running. */ export function listCodexDesktopShellPids(io: DesktopAppRestartIo = {}): number[] | null { const platform = io.platform ?? process.platform; const selected = ADAPTERS[platform]; const adapter = io.adapter ?? selected?.adapter; if (!adapter) return null; const exec = io.execFile ?? selected?.exec; if (!exec) return null; const install = adapter.discover(exec); if (!install) return null; const processes = adapter.listProcesses(exec, install); if (processes === null) return null; return rootShells(processes, install, adapter).map(entry => entry.pid); } export function restartCodexDesktopApp(io: DesktopAppRestartIo = {}): DesktopAppRestartResult { const skipped = (reason: DesktopAppRestartReason): DesktopAppRestartResult => ({ attempted: false, stopped: [], surviving: [], relaunch: "skipped", reason, }); const platform = io.platform ?? process.platform; const selected = ADAPTERS[platform]; const adapter = io.adapter ?? selected?.adapter; const exec = io.execFile ?? selected?.exec; if (!adapter || !exec) return skipped("unsupported_platform"); // In an armed test process a call without an injected exec would reach the real OS (an injected // adapter still execs through the platform default): on a developer Mac, `performCodexRestart` // tests quit the user's ChatGPT (Codex) app and relaunched it through `/usr/bin/open` with the // runner's sandbox HOME, logged out. Armed means the test preload's flag, not NODE_ENV, for the // reason test-home-guard gives: a real `NODE_ENV=test ocx ...` must still restart the app. if (!io.execFile && isTestHomeGuardArmed()) return skipped("test_environment"); // Step 0. Two restarts at once are destructive rather than merely wasteful: the // first quits and relaunches, the second sees the freshly started shell as a target // and kills it. Own-pid reentrancy means the wp5 helper runs this same step and // finds the lock its caller made out to it. // A cli-update worker holds this gate from its final process scan through // installer termination and readback, so no new shell may appear inside. The // admission check runs BEFORE the restart lock and every mutation this // function performs: a busy refusal must leave the app, the lock and any // handoff all untouched. Held through relaunch or a failed attempt's // cleanup; a handoff helper's own delayed descendants stay the documented // pre-existing residual. const selectionWrite = beginCodexCliSelectionParentWrite(); if (!selectionWrite.entered) return skipped("selection_mutation_busy"); let handedOff = false; // The lock attempt sits inside the protected scope too: a throw from the // lock's own mkdir/write before the try would otherwise leak this // process-wide gate for the rest of the process. lockHeld distinguishes // "acquisition threw/refused" from "lock taken" so a failed attempt never // releases a lock this call does not hold. let lockHeld = false; try { const acquisition = acquireDesktopRestartLock(io.lock); if (!acquisition.acquired) return skipped("restart_in_flight"); lockHeld = true; const install = adapter.discover(exec); if (!install) return skipped("package_discovery_failed"); const processes = adapter.listProcesses(exec, install); // A probe that could not run is not evidence of absence. Reporting it as no_targets // told users the app was not running and silently skipped the restart they asked // for (#2557). if (processes === null) return skipped("process_probe_failed"); const shells = rootShells(processes, install, adapter); if (shells.length === 0) return skipped("no_targets"); const ancestryPids = io.ancestryPids ? io.ancestryPids() : adapter.ancestryPids(exec); // An empty chain means "could not establish that we are outside the tree", which // covers both an unreadable hop and a walk that hit its bound. const insideTree = ancestryPids.length === 0 || processes.some(entry => ancestryPids.includes(entry.pid)); if (insideTree) { if (io.allowHandoff === false || !io.startHandoff) return skipped("self_ancestry"); const handoff = io.startHandoff(); if (!handoff) return skipped("self_ancestry"); handedOff = true; return { attempted: false, stopped: [], surviving: [], relaunch: "skipped", reason: "handoff_started", handoff, }; } // Captured while the tree is still ALIVE. On Linux the relaunch needs the // graphical session variables, and after termination there is nothing to read them // from. Ordering this wrongly works on macOS and Windows and produces a Linux app // that cannot reach the compositor. let context: Record<string, string>; try { context = adapter.captureRelaunchContext(exec, install, processes); } catch { return skipped("relaunch_context_failed"); } const isAlive = io.isAlive ?? defaultIsAlive; const sleep = io.sleep ?? defaultSleep; const now = io.now ?? (() => Date.now()); const stopped: number[] = []; const surviving: number[] = []; for (const shell of shells) { const pid = shell.pid; // The listing is already one probe old. const before = checkIdentity(adapter, exec, install, shell); if (before === "gone") { stopped.push(pid); continue; } if (before === "unknown") { // We could not look, so we cannot claim this exited and we must not signal a // process we failed to re-verify. Reporting it as surviving is the honest answer: // it blocks the relaunch, which is exactly right when the tree state is unknown. surviving.push(pid); continue; } try { adapter.requestQuit(exec, install, shell); } catch { /* a refused graceful close still gets the forced pass below */ } // Liveness AND enumeration have to agree before a stop is claimed. A pid-based // liveness probe is a weaker instrument than the platform's own process list, and // on a packaged app the two disagree in BOTH directions. if (waitUntilGone(adapter, exec, install, shell, GRACEFUL_EXIT_TIMEOUT_MS, isAlive, sleep, now)) { stopped.push(pid); continue; } // The wait window is long enough for a pid to be recycled, and the next step is a // hard kill. Confirm it is still the process we verified, or leave it alone. const afterGraceful = checkIdentity(adapter, exec, install, shell); if (afterGraceful === "gone") { stopped.push(pid); continue; } if (afterGraceful === "unknown") { surviving.push(pid); continue; } try { adapter.forceStop(exec, shell); } catch { /* the process state decides, not the exit code */ } // Same rule after the forced pass: only an enumeration that no longer contains this // process proves it stopped. Everything else is a survivor, and a survivor blocks // the relaunch rather than producing a second shell beside a live one. if (waitUntilGone(adapter, exec, install, shell, FORCED_EXIT_TIMEOUT_MS, isAlive, sleep, now)) { stopped.push(pid); } else { surviving.push(pid); } } if (surviving.length > 0) { // Launching a second shell beside a stuck one is worse than leaving the operator // to restart it. return { attempted: true, stopped, surviving, relaunch: "skipped", reason: "targets_survived" }; } try { adapter.relaunch(exec, install, context); } catch { // Distinct from targets_survived on purpose. Everything DID die and the relaunch // is what failed; the old code reported the two as one and sent operators looking // for processes that were not there. return { attempted: true, stopped, surviving, relaunch: "skipped", reason: "relaunch_failed" }; } return { attempted: true, stopped, surviving: [], relaunch: "started" }; } finally { // On the handoff path ownership was transferred to the helper, so releasing here // would drop a lock that is still protecting a restart about to happen. selectionWrite.exit(); if (lockHeld && !handedOff) releaseDesktopRestartLock(io.lock); } } export async function restartCodexDesktopAppAsync(io: DesktopAppRestartIo = {}): Promise<DesktopAppRestartResult> { try { return await withCodexCliSelectionParentWriteAsync(() => restartCodexDesktopApp(io)); } catch (error) { if (error instanceof CodexCliSelectionMutationBusyError) return { attempted: false, stopped: [], surviving: [], relaunch: "skipped", reason: "selection_mutation_busy", }; throw error; } }