@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
414 lines (388 loc) • 21.4 kB
text/typescript
/**
* Cold start for `ocx ensure` when OpenCodex Desktop owns or runs the proxy (#6971).
*
* The Codex launcher shim runs `ocx ensure` before every Codex launch. Without this policy,
* ensure spawned a detached CLI proxy whenever nothing answered on the port. That is wrong in two
* Desktop situations: during the Desktop supervisor's restart backoff, and after Desktop quit
* while its durable ownership claim remains. In both, the CLI proxy took the port and Desktop came
* back as a guest without supervision. That is why the dashboard used to disable the shim under
* Desktop.
*
* Rules, in order:
* - Facts re-observed after the asynchronous recovery inspection keep first refusal:
* ownership or the process list that cannot be read is not evidence of absence.
* - Verified native intent wins over every other signal: an independently verified recovery
* keeps its replacement, including without a claim, while a verified stop refuses. The
* current bundled CLI (or protected system installation) anchors the executable; the
* accepted socket, process incarnation and fresh native intent bind the recovery proof.
* - Conflicting native evidence — drift, contradiction or an unprovable observation on a
* platform that can verify — refuses even under a durable claim. A claim outranks only
* the structurally unsupported verdict of a platform with no live-image binding.
* - An unclaimed start cannot be authorized or suppressed by a name, locator file or
* unverifiable observation: unknown still refuses; otherwise the ordinary CLI cold start
* runs. Unsupported per-user installations do not acquire authority from their
* self-reported identity; use their bundled CLI.
* - A running Desktop app with a durable Desktop claim is the supervisor. Wait for its proxy;
* never start a competing one. A process name alone is not ownership evidence. A durable
* Desktop claim with no running app: start Desktop (hidden, by the path its own login
* registration recorded — LaunchServices never picks the bundle) where that is verifiable,
* then wait. Elsewhere, fail with guidance. A missing Desktop process never authorizes a
* CLI proxy by itself; an unsupported verdict beside an absent observation is
* contradictory and refuses. Handing ownership to the CLI stays an explicit
* `ocx service install` consent step.
*
* Concurrent shim launches share one Desktop launch through a lease file held by a live process;
* every caller then waits on the same readiness probe.
*/
import { execFileSync } from "node:child_process";
import { randomUUID } from "node:crypto";
import { accessSync, constants, existsSync, linkSync, readdirSync, readFileSync, readlinkSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { basename, dirname, join, posix, win32 } from "node:path";
import { getConfigDir } from "../config/paths";
import { resolveServiceOwnership } from "../service/state";
import { inspectDesktopRecovery, type DesktopRecoveryEvidence } from "../service/desktop-recovery";
export type DesktopProcessState = "running" | "absent" | "unknown";
export type DesktopOwnershipState = "desktop" | "other" | "unknown";
export type EnsureColdStartPlan =
| { kind: "spawn-cli" }
| { kind: "wait-desktop" }
| { kind: "launch-desktop" }
| { kind: "refuse"; reason: "desktop-unlaunchable" | "desktop-stopped" | "unverified" };
export function planEnsureColdStart(facts: {
ownership: DesktopOwnershipState;
desktopProcess: DesktopProcessState;
platform: NodeJS.Platform;
recovery?: DesktopRecoveryEvidence;
}): EnsureColdStartPlan {
if (facts.ownership === "unknown" || facts.desktopProcess === "unknown") return { kind: "refuse", reason: "unverified" };
if (facts.recovery?.kind === "recovering") return { kind: "wait-desktop" };
if (facts.recovery?.kind === "stopped") return { kind: "refuse", reason: "desktop-stopped" };
// Drifted or contradictory native evidence refuses even under a durable claim; the claim
// outranks only the structurally unsupported verdict of a platform with no image binding.
if (facts.recovery?.kind === "unknown" && facts.recovery.unsupported !== true) return { kind: "refuse", reason: "unverified" };
if (facts.ownership === "other") {
// An unclaimed start cannot be authorized or suppressed by an unverifiable observation.
return facts.recovery?.kind === "unknown" ? { kind: "refuse", reason: "unverified" } : { kind: "spawn-cli" };
}
if (facts.desktopProcess === "running") return { kind: "wait-desktop" };
// A matched native process beside an absent observation is contradictory; refuse rather
// than launch a new app or guess at the supervisor's state.
if (facts.recovery?.kind === "unknown") return { kind: "refuse", reason: "unverified" };
return facts.platform === "darwin" ? { kind: "launch-desktop" } : { kind: "refuse", reason: "desktop-unlaunchable" };
}
/** Desktop restart backoff tops out at 30 s; the budget covers it plus a cold sidecar start. */
export const DESKTOP_COLD_START_TIMEOUT_MS = 40_000;
export type DesktopColdStartResult<T> =
| { kind: "cli" }
| { kind: "live"; live: T }
| { kind: "failed"; message: string };
export interface DesktopColdStartDeps<T> {
platform: NodeJS.Platform;
ownership: () => DesktopOwnershipState;
desktopProcess: () => DesktopProcessState;
desktopRecovery?: () => Promise<DesktopRecoveryEvidence>;
/** Start the Desktop app hidden. Returns false when the request could not be made. */
launchDesktop: () => boolean;
/** Returns a release function when this caller should launch, or null when another caller already did. */
acquireLaunchLease: () => (() => void) | null;
waitForProxy: (timeoutMs: number) => Promise<T | null>;
info?: (line: string) => void;
}
const QUIT_HINT = "To run the proxy from this CLI instead, quit OpenCodex and run `ocx service install` or `ocx start`.";
export async function runDesktopColdStart<T>(deps: DesktopColdStartDeps<T>): Promise<DesktopColdStartResult<T>> {
const recovery = await deps.desktopRecovery?.();
const plan = planEnsureColdStart({
ownership: deps.ownership(),
desktopProcess: deps.desktopProcess(),
platform: deps.platform,
recovery,
});
if (plan.kind === "spawn-cli") return { kind: "cli" };
if (plan.kind === "refuse") {
return { kind: "failed", message: plan.reason === "unverified"
? "Could not verify whether OpenCodex Desktop manages this proxy, so no CLI proxy was started. Run `ocx doctor`, or start the proxy explicitly with `ocx start`."
: plan.reason === "desktop-stopped" ? `OpenCodex Desktop has stopped its proxy. Use Start Proxy in the OpenCodex menu. ${QUIT_HINT}`
: `OpenCodex Desktop manages this proxy but is not running. Open OpenCodex to start it. ${QUIT_HINT}` };
}
if (plan.kind === "launch-desktop") {
const release = deps.acquireLaunchLease();
try {
if (release) {
deps.info?.("Starting OpenCodex Desktop, which manages this proxy...");
if (!deps.launchDesktop()) {
return { kind: "failed", message: `OpenCodex Desktop manages this proxy, but it could not be started. Open OpenCodex manually. ${QUIT_HINT}` };
}
}
const live = await deps.waitForProxy(DESKTOP_COLD_START_TIMEOUT_MS);
if (live) return { kind: "live", live };
return { kind: "failed", message: `OpenCodex Desktop was started, but its proxy did not answer in time. Check the OpenCodex menu. ${QUIT_HINT}` };
} finally { release?.(); }
}
deps.info?.("Waiting for OpenCodex Desktop to restart its proxy...");
const live = await deps.waitForProxy(DESKTOP_COLD_START_TIMEOUT_MS);
if (live) return { kind: "live", live };
return {
kind: "failed",
message: `OpenCodex Desktop is running but its proxy is not answering. Use Start Proxy in the OpenCodex menu. ${QUIT_HINT}`,
};
}
type Execute = (command: string, args: string[], timeoutMs: number) => string;
function execute(command: string, args: string[], timeoutMs: number): string {
return execFileSync(command, args, {
encoding: "utf8", timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"], windowsHide: true,
});
}
/** A Desktop app executable: `opencodex-desktop`, inside an app bundle's Contents/MacOS on macOS. */
export function isDesktopExecutable(path: string, platform: NodeJS.Platform): boolean {
if (basename(path) !== "opencodex-desktop") return false;
return platform !== "darwin" || (basename(dirname(path)) === "MacOS" && basename(dirname(dirname(path))) === "Contents");
}
export interface DesktopProcessOptions {
platform?: NodeJS.Platform;
uid?: number;
env?: NodeJS.ProcessEnv;
run?: Execute;
/** Linux: executable paths of this user's processes, or \`unverified\`. */
linuxExecutables?: (uid: number) => string[] | "unverified";
/** Linux: whether procfs hides processes (hidepid=2/4). */
procfsHidesProcesses?: () => boolean;
/** Linux: whether this machine shows evidence of an OpenCodex Desktop install. */
desktopInstalled?: () => boolean;
}
/**
* Linux: hidepid=2 (invisible) or 4 (ptraceable) can hide a same-uid process whose credentials
* differ from the caller's (for example after newgrp), so an empty scan proves nothing there.
* An unreadable mount table is treated as filtering.
*/
export function procfsHidesProcesses(mountinfo = "/proc/self/mountinfo"): boolean {
let text: string;
try { text = readFileSync(mountinfo, "utf8"); } catch { return true; }
return text.split("\n").some(line => {
const [mount, fs] = line.split(" - ");
if (mount?.split(" ")[4] !== "/proc" || !fs) return false;
const [type, , options = ""] = fs.split(" ");
return type === "proc" && options.split(",").some(option => /^hidepid=(2|4|invisible|ptraceable)$/.test(option));
});
}
function linuxDesktopInstalled(): boolean {
return existsSync(join(homedir(), ".opencodex-desktop")) || existsSync("/usr/bin/opencodex-desktop");
}
/** Linux truncates comm to 15 bytes. */
const LINUX_DESKTOP_COMM = "opencodex-desktop".slice(0, 15);
/**
* Linux: executables of this user's processes. A process that exited mid-scan or belongs to someone
* else is skipped. A non-dumpable process (ssh-agent, gpg-agent) hides its executable but not its
* comm, so it is ruled out by name; one whose comm could be Desktop makes the answer unverifiable.
* The scan must also see this process, or procfs is filtered and absence proves nothing.
*/
export function scanLinuxExecutables(uid: number, selfPid: number = process.pid, proc = "/proc"): string[] | "unverified" {
const paths: string[] = [];
let sawSelf = false;
const code = (error: unknown) => (error as { code?: unknown } | null)?.code;
for (const entry of readdirSync(proc)) {
if (!/^\d+$/.test(entry)) continue;
if (Number(entry) === selfPid) sawSelf = true;
try {
if (statSync(`${proc}/${entry}`).uid !== uid) continue;
paths.push(readlinkSync(`${proc}/${entry}/exe`).replace(/ \(deleted\)$/, ""));
} catch (error) {
if (code(error) === "ENOENT" || code(error) === "ESRCH") continue;
try {
if (readFileSync(`${proc}/${entry}/comm`, "utf8").trim() !== LINUX_DESKTOP_COMM) continue;
} catch (commError) {
if (code(commError) === "ENOENT" || code(commError) === "ESRCH") continue;
}
return "unverified";
}
}
return sawSelf ? paths : "unverified";
}
/** Whether this user runs an OpenCodex Desktop app, judged by executable identity, never arguments. */
export function inspectDesktopProcess(options: DesktopProcessOptions = {}): DesktopProcessState {
const platform = options.platform ?? process.platform;
const run = options.run ?? execute;
try {
const uid = options.uid ?? process.getuid?.();
if (platform === "linux") {
if (uid === undefined) return "unknown";
const executables = (options.linuxExecutables ?? scanLinuxExecutables)(uid);
if (executables === "unverified") return "unknown";
if (executables.some(path => isDesktopExecutable(path, platform))) return "running";
// A filtered procfs cannot prove absence where Desktop may be installed. Without an install
// there is nothing to hide, so hardened hosts keep the plain CLI cold start.
return (options.procfsHidesProcesses ?? procfsHidesProcesses)() && (options.desktopInstalled ?? linuxDesktopInstalled)()
? "unknown" : "absent";
}
if (platform === "darwin") {
if (uid === undefined) return "unknown";
// macOS reports the full executable path as comm.
const output = run("/bin/ps", ["-U", String(uid), "-o", "comm="], 3_000);
return output.split("\n").some(line => isDesktopExecutable(line.trim(), platform)) ? "running" : "absent";
}
if (platform === "win32") {
const env = options.env ?? process.env;
const root = env.SystemRoot ?? env.windir ?? "C:\\Windows";
const user = env.USERNAME?.trim();
const args = ["/FI", "IMAGENAME eq opencodex-desktop.exe", ...(user ? ["/FI", `USERNAME eq ${user}`] : []), "/FO", "CSV", "/NH"];
const output = run(win32.join(root, "System32", "tasklist.exe"), args, 3_000);
return /^"opencodex-desktop\.exe",/im.test(output) ? "running" : "absent";
}
return "absent";
} catch {
return "unknown";
}
}
const DESKTOP_BUNDLE_ID = "com.opencodex.desktop";
const DESKTOP_PLIST_LABEL = "OpenCodex";
/**
* The app bundle the consented installation itself registered as its Start-at-Login program —
* not whichever bundle LaunchServices would resolve for our identifier. `open -b` answers a
* mutable per-user registry: any planted bundle claiming {@link DESKTOP_BUNDLE_ID} could be
* selected and executed in the real app's place. The recorded claim, this app's own install-id
* store, and the login registration it wrote are the durable evidence of which installation
* that is; a claim whose registration is absent, malformed, stale or points off a Desktop
* executable refuses the launch instead of guessing.
*/
function consentedDesktopBundle(home: string, installId: string, run: Execute): string | null {
const localId = readFileSync(
join(home, "Library", "Application Support", DESKTOP_BUNDLE_ID, "install-id"), "utf8",
).trim();
if (!localId || localId !== installId) return null;
const plistPath = realpathSync(join(home, "Library", "LaunchAgents", `${DESKTOP_PLIST_LABEL}.plist`));
const registration = JSON.parse(
run("/usr/bin/plutil", ["-convert", "json", "-o", "-", plistPath], 3_000),
) as { Label?: unknown; RunAtLoad?: unknown; ProgramArguments?: unknown; Program?: unknown };
const args = registration.ProgramArguments;
// The shapes auto-launch writes: [program] or [program, "--autostart"]; see the migration
// rules in desktop/src-tauri/src/login_registration.rs, which classify anything else Leave.
// This is a macOS plist path, regardless of the host running an injected launch probe.
if (registration.Label !== DESKTOP_PLIST_LABEL || registration.RunAtLoad !== true || !Array.isArray(args)
|| (args.length !== 1 && args.length !== 2) || typeof args[0] !== "string" || !posix.isAbsolute(args[0])
|| (args.length === 2 && args[1] !== "--autostart")
|| (registration.Program !== undefined && registration.Program !== args[0])) return null;
const executable = realpathSync(args[0]);
if (!isDesktopExecutable(executable, "darwin") || !statSync(executable).isFile()) return null;
accessSync(executable, constants.X_OK);
const bundle = dirname(dirname(dirname(executable)));
if (!bundle.endsWith(".app")) return null;
const info = JSON.parse(
run("/usr/bin/plutil", ["-convert", "json", "-o", "-", join(bundle, "Contents", "Info.plist")], 3_000),
) as { CFBundleIdentifier?: unknown; CFBundleExecutable?: unknown };
// `open` uses this selector, so checking only the registration and identifier would
// validate one binary while launching another. The registered path is already canonical.
if (info.CFBundleIdentifier !== DESKTOP_BUNDLE_ID || info.CFBundleExecutable !== "opencodex-desktop") return null;
return realpathSync(join(bundle, "Contents", "MacOS", info.CFBundleExecutable)) === executable ? bundle : null;
}
/** Start the consented macOS app hidden, by the path its own login registration recorded. */
export function launchDesktopApp(options: {
platform?: NodeJS.Platform;
run?: Execute;
home?: string;
ownership?: () => ReturnType<typeof resolveServiceOwnership>;
} = {}): boolean {
if ((options.platform ?? process.platform) !== "darwin") return false;
try {
const owner = (options.ownership ?? resolveServiceOwnership)();
if (owner.kind !== "owned" || owner.ownership.owner !== "desktop") return false;
const bundle = consentedDesktopBundle(options.home ?? homedir(), owner.ownership.installId, options.run ?? execute);
if (bundle === null) return false;
(options.run ?? execute)("/usr/bin/open", ["-g", bundle, "--args", "--autostart"], 10_000);
return true;
} catch { return false; }
}
function processAlive(pid: number): boolean {
try { process.kill(pid, 0); return true; }
catch (error) { return (error as NodeJS.ErrnoException | null)?.code === "EPERM"; }
}
function readHolder(path: string): number | null {
const pid = Number(readFileSync(path, "utf8").trim());
return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
}
const LEASE_FILE = /^desktop-launch\.(\d+)\.lease$/;
/**
* One Desktop launch per cold start. Leases are numbered generations, each published whole with
* link(2), which fails if the name exists, so exactly one contender can create generation N+1. A
* caller launches only after creating the next generation while the newest one belongs to a dead
* process (or none exists). A lease stays valid while its holder lives, so a slow launch never
* expires under its owner. Nothing ever moves or overwrites another holder's lease.
*/
export function acquireDesktopLaunchLease(
configDir: string,
io: { pid?: number; alive?: (pid: number) => boolean } = {},
): (() => void) | null {
const pid = io.pid ?? process.pid;
const alive = io.alive ?? processAlive;
const leasePath = (generation: number) => join(configDir, `desktop-launch.${generation}.lease`);
for (let attempt = 0; attempt < 4; attempt++) {
let generations: number[];
try {
generations = readdirSync(configDir).flatMap(name => {
const match = LEASE_FILE.exec(name);
return match ? [Number(match[1])] : [];
}).sort((a, b) => b - a);
} catch {
// An unreadable lease directory must not suppress the launch; it only loses deduplication.
return () => {};
}
const newest = generations[0];
if (newest !== undefined) {
try {
const holder = readHolder(leasePath(newest));
if (holder !== null && alive(holder)) return null;
} catch (error) {
if ((error as { code?: unknown })?.code === "ENOENT") continue;
return null;
}
}
const next = (newest ?? 0) + 1;
const staged = join(configDir, `desktop-launch.${randomUUID()}.tmp`);
try {
writeFileSync(staged, String(pid), { flag: "wx", mode: 0o600 });
linkSync(staged, leasePath(next));
} catch (error) {
if ((error as { code?: unknown })?.code === "EEXIST") continue;
return () => {};
} finally {
try { unlinkSync(staged); } catch { /* not created */ }
}
const withdraw = () => {
try { if (readHolder(leasePath(next)) === pid) unlinkSync(leasePath(next)); } catch { /* already gone */ }
};
// A contender with a stale directory read can publish a generation a winner already cleaned
// up. The highest generation is the one launcher; anyone below it stands down.
try {
if (readdirSync(configDir).some(name => Number(LEASE_FILE.exec(name)?.[1] ?? 0) > next)) {
withdraw();
return null;
}
} catch { /* keep the lease: the directory was readable a moment ago */ }
// Older generations belong to dead holders: the newest was checked before publishing above it.
for (const generation of generations) {
try { unlinkSync(leasePath(generation)); } catch { /* already gone */ }
}
// The newest generation is never deleted on release: removing it would let numbering restart
// below a stale contender. It stops counting once this process exits.
return () => {};
}
return null;
}
/** Production wiring; `waitForProxy` is ensure's identity-checked readiness probe. */
export function productionDesktopColdStartDeps<T>(waitForProxy: (timeoutMs: number) => Promise<T | null>): DesktopColdStartDeps<T> {
return {
platform: process.platform,
ownership: () => {
try {
const owner = resolveServiceOwnership();
if (owner.kind === "unknown") return "unknown";
return owner.kind === "owned" && owner.ownership.owner === "desktop" ? "desktop" : "other";
} catch { return "unknown"; }
},
desktopProcess: () => inspectDesktopProcess(),
desktopRecovery: () => inspectDesktopRecovery(),
launchDesktop: () => launchDesktopApp(),
acquireLaunchLease: () => acquireDesktopLaunchLease(getConfigDir()),
waitForProxy,
info: line => console.log(line),
};
}