@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
399 lines (384 loc) • 18.3 kB
text/typescript
/**
* `ocx resolve` — the machine-readable runtime resolution surface for an embedding shell.
*
* D5 of devlog/_fin/260921_app_runtime_ownership/: the desktop shell must stop resolving
* the config home, the port and liveness itself. The tuned probe budgets in
* src/server/proxy-liveness.ts exist because a shell-side reimplementation answered
* "nobody listening" twice and started duplicate proxies; this verb exposes that module's
* verdict instead of copying it, alongside src/config/paths.ts (the home) and the CLI's
* own preferred-port selection (`config.port ?? 10100` — resolve takes no --port).
*
* Contract:
* - `--json` puts exactly ONE JSON document on stdout, versioned by `schema`; the
* default prints two human lines, the same opt-in split as `ocx ready --json`.
* - liveness has three answers, not two: "live", "absent-proven" (every recorded and
* configured endpoint definitively refused or answered non-opencodex), and unknown.
* Unknown NEVER reaches the wire as absent — a probe that timed out, a listener that
* withheld /healthz, or an identity mismatch exits 1 instead. Only "absent-proven"
* may authorise starting a new runtime.
* - exit 0 whenever a trustworthy verdict exists — live, or proven absent. A MISSING
* config.json is defaults, not an error.
* - exit 1 when the CLI cannot resolve: an invalid config.json must NOT be answered
* with `loadConfig`'s repair-to-defaults behaviour, because that hands the caller
* a guessed port; and unknown liveness must not be answered as absence.
* Under `--json` that exit still prints its one document: a `ResolveFailureJson`
* (`ok: false` plus a fixed `reason`) beside the unchanged stderr line (#8318).
* - exit 64 for any argument, pre-parsed in src/cli/root.ts before preflight side
* effects, mirroring `ocx ready`. The verb is read-only and listed in
* skipsCodexShimAutoRestore, so a lookup made to populate a consent surface never
* triggers a shim repair side effect.
*
* Discovery uses the START_OWNERSHIP_LIVENESS budget, not the 750ms single-shot default:
* the shell's launch decision keys on this verdict, and answering "nobody" for a slow
* live proxy is the duplicate-proxy decision the start path tunes against (#5004).
*
* Lives outside cli/index.ts (which dispatches argv at module top level) so tests can
* import it, the same split as ready.ts.
*/
import { readConfigDiagnostics, type ConfigDiagnostics } from "../config";
import { getConfigDir } from "../config/paths";
import { readRuntimePort } from "../config/process-state";
import { packageVersion } from "../lib/package-version";
import {
findLiveProxy,
probeEndpointLiveness,
START_OWNERSHIP_LIVENESS,
type EndpointLiveness,
type LiveProxy,
} from "../server/proxy-liveness";
import { endpointsToProve, everyEndpointProvenDownAsync, type ProbeEndpoint } from "./uninstall-plan";
import {
resolveServiceOwnership,
resolveServiceState,
type ServiceInstallState,
type ServiceOwnershipResolution,
type ServiceStateResolution,
} from "../service/state";
import {
assessServiceTakeoverCompatibility,
type ManagingCliObservation,
type ManagingCliRole,
} from "../service/ownership-compatibility";
import { observeManagingClis } from "../service/managing-cli";
import { SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION } from "../service/install-state-contract.mjs";
import { inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
import { computeVersionSkew, type VersionSkew } from "./version-skew";
/** Wire version of the resolve document. Bump only on an incompatible shape change. */
export const RESOLVE_SCHEMA = "ocx-resolve/1";
/** The port every preferred-port selection in the CLI falls back to. */
export const RESOLVE_DEFAULT_PORT = 10100;
export interface ResolveLivenessJson {
/**
* "live" when the identity-checked probe found our proxy; "absent-proven" when every
* recorded and configured endpoint is definitively dead. The third state — unknown —
* exits 1 before this document is printed, so it never appears on the wire as absence.
*/
status: "live" | "absent-proven";
pid: number | null;
port: number | null;
/** Raw bind hostname that answered; compose probe URLs via probeHostname semantics. */
hostname?: string;
/** Where the verdict came from: the runtime record, or the configured listen port. */
source: LiveProxy["source"] | null;
/** Version the live proxy reported on /healthz, when it reported one. */
version?: string;
/** Listener role the live proxy reported, when it reported one ("client" = connected client). */
role?: string;
}
export interface ResolveJson {
schema: typeof RESOLVE_SCHEMA;
/** Version of this CLI binary, so a shell can compare its engine against the live proxy. */
cliVersion: string;
/** Resolved opencodex home (OPENCODEX_HOME or ~/.opencodex), from src/config/paths.ts. */
configHome: string;
port: {
/** The port a client should use: the live listener's port when one answers, else the configured one. */
effective: number;
/** The configured listen port (config.port ?? 10100); what a start would prefer. */
configured: number;
/** Whether `effective` came from a live proxy or from configuration. */
source: LiveProxy["source"];
};
liveness: ResolveLivenessJson;
/**
* The recorded runtime owner, in the CLI's own three answers. `unknown` is on the wire
* deliberately: it never changes the exit code — the liveness verdict is still
* trustworthy — and the embedding shell fails closed on it rather than asking consent
* against a record it could not read.
*/
ownership: ServiceOwnershipResolution;
/**
* Whether a desktop takeover can be offered, and the token that binds that approval to
* the exact subject and managing-CLI observations a later `ocx service claim` must find
* unchanged. `ownership-unknown` is produced only here: it is a wire reason, not a new
* member of `ServiceTakeoverCompatibility`'s union.
*/
takeover: ResolveTakeover;
/**
* The bundled CLI's version compared against the live proxy's, present only when
* something is live. A shell reads `relation` to decide whether attaching or a
* takeover moves versions: `"proxy-newer"` means this CLI's bundled runtime would
* DOWNGRADE the listener, which the desktop uses to stay a guest instead of offering
* takeover. Additive within ocx-resolve/1; older shells ignore it and read as unknown.
*/
versionSkew?: VersionSkew;
supervisor?: {
kind: "desktop" | "none" | "unknown" | "unsupported";
supervisorPid?: number;
runtimePid?: number;
app?: string;
};
}
export type ResolveTakeover =
| { kind: "supported"; protocolVersion: number; minimumCliVersion: string; token: string }
| { kind: "blocked"; reason: string; detail: string; minimumCliVersion: string };
/**
* The document `--json` prints when resolve exits 1 (#8318). It carries no liveness, port or
* ownership field, so nothing in it can be read as absence; `error` repeats the stderr line.
* A shell that keys on the exit status, as the desktop does, can ignore it.
*/
export interface ResolveFailureJson {
schema: typeof RESOLVE_SCHEMA;
ok: false;
reason: "config_unreadable" | "config_invalid" | "discovery_failed" | "liveness_unknown";
error: string;
}
export interface ResolveArgs {
json: boolean;
}
export type ResolveParseResult = { ok: true; args: ResolveArgs } | { ok: false; code: 64 };
/** Pure argument parser: the only flag is `--json`. */
export function parseResolveArgs(argv: string[]): ResolveParseResult {
for (const flag of argv) {
if (flag !== "--json") return { ok: false, code: 64 };
}
return { ok: true, args: { json: argv.includes("--json") } };
}
export interface ResolveIo {
configDir?: () => string;
readDiagnostics?: () => ConfigDiagnostics;
findLive?: () => Promise<LiveProxy | null>;
/** Runtime-port record reader; production default is readRuntimePort. */
readRuntime?: () => { port?: number; hostname?: string } | null;
/** Tri-state endpoint probe; production default runs in-process for compiled standalone binaries. */
probeEndpoint?: (endpoint: ProbeEndpoint) => EndpointLiveness | Promise<EndpointLiveness>;
cliVersion?: () => string;
/** Recorded-ownership resolver; production default is resolveServiceOwnership. */
resolveOwnership?: () => ServiceOwnershipResolution;
/** Full install-state resolver; production default is resolveServiceState. */
resolveState?: () => ServiceStateResolution;
/** Managing-CLI observer; production default is observeManagingClis. */
observeManagers?: (
state: ServiceInstallState | null,
) => Readonly<Record<ManagingCliRole, ManagingCliObservation>>;
inspectSupervision?: typeof inspectDesktopSupervision;
stdout?: { log: (s: string) => void };
stderr?: { error: (s: string) => void };
}
function livenessJson(live: LiveProxy | null): ResolveLivenessJson {
// Reaching here with null means absence was PROVEN by the caller (unknown exits 1
// before this document is built).
if (!live) return { status: "absent-proven", pid: null, port: null, source: null };
return {
status: "live",
pid: live.pid,
port: live.port,
source: live.source,
...(live.hostname === undefined ? {} : { hostname: live.hostname }),
...(live.version === undefined ? {} : { version: live.version }),
...(live.role === undefined ? {} : { role: live.role }),
};
}
/** Pure shaper: one live verdict plus configuration becomes the wire document. */
export function buildResolveJson(
config: { port?: number },
live: LiveProxy | null,
configHome: string,
cliVersion: string,
ownership: ServiceOwnershipResolution,
takeover: ResolveTakeover,
supervision?: ReturnType<typeof inspectDesktopSupervision>,
): ResolveJson {
const configured = config.port ?? RESOLVE_DEFAULT_PORT;
return {
schema: RESOLVE_SCHEMA,
cliVersion,
configHome,
port: {
effective: live ? live.port : configured,
configured,
source: live ? live.source : "config",
},
liveness: livenessJson(live),
...(live && supervision ? { supervisor: supervision.kind === "desktop"
? { kind: supervision.kind, supervisorPid: supervision.supervisorPid, runtimePid: supervision.runtimePid, app: supervision.app }
: { kind: supervision.kind } } : {}),
ownership,
takeover,
// A proven absence has nothing to skew against; the field is omitted there rather
// than emitted as an "unknown" row, matching the liveness identity fields.
...(live ? { versionSkew: computeVersionSkew(cliVersion, live.version) } : {}),
};
}
/**
* Human form: two lines, no prose flourish — an operator skims it, a shell uses --json.
*/
function reportHuman(json: ResolveJson, stdout: { log: (s: string) => void }): void {
stdout.log(`Config home: ${json.configHome}`);
const live = json.liveness;
if (live.status === "live") {
const pidText = live.pid === null ? "unknown" : String(live.pid);
const versionText = live.version ?? "unknown version";
const supervisor = json.supervisor?.kind === "desktop" ? `; supervisor: desktop (pid ${json.supervisor.supervisorPid})` : "";
stdout.log(`Proxy live on port ${json.port.effective} (PID ${pidText}, ${versionText}); effective port ${json.port.effective}${supervisor}.`);
} else {
stdout.log(`No live proxy (absence proven); effective port ${json.port.effective} (configured).`);
}
const ownership = json.ownership;
if (ownership.kind === "owned") {
stdout.log(`Owner: ${ownership.ownership.owner} (install ${ownership.ownership.installId}, generation ${ownership.ownership.consentGeneration})`);
} else if (ownership.kind === "unknown") {
stdout.log(`Owner: unknown (${ownership.reason})`);
} else {
stdout.log("Owner: none recorded");
}
stdout.log(
json.takeover.kind === "supported"
? "Takeover: supported"
: `Takeover: blocked (${json.takeover.reason}: ${json.takeover.detail})`,
);
// The skew warning is the same sentence `ocx status` and `doctor` surface; an
// operator comparing a live proxy against this CLI gets it here too instead of
// discovering the mismatch only inside the desktop shell.
if (json.versionSkew?.warning) {
stdout.log(`Version skew: ${json.versionSkew.warning}`);
}
}
/**
* Run `ocx resolve` over injected I/O. Returns the exit code. The production defaults
* read config through the diagnostics surface (which distinguishes missing, valid and
* invalid instead of repairing to defaults) and perform one identity-checked discovery
* at the ownership-safe budget — resolve adds no probing policy of its own.
*/
export async function runResolve(args: ResolveArgs, io: ResolveIo = {}): Promise<number> {
const stdout = io.stdout ?? console;
const stderr = io.stderr ?? console;
const configDir = io.configDir ?? getConfigDir;
const readDiagnostics = io.readDiagnostics ?? readConfigDiagnostics;
const findLive = io.findLive ?? (() => findLiveProxy(START_OWNERSHIP_LIVENESS));
const readRuntime = io.readRuntime ?? readRuntimePort;
const probeEndpoint = io.probeEndpoint ?? probeEndpointLiveness;
const cliVersion = io.cliVersion ?? packageVersion;
const resolveOwnership = io.resolveOwnership ?? resolveServiceOwnership;
const resolveState = io.resolveState ?? resolveServiceState;
const observeManagers = io.observeManagers ?? observeManagingClis;
const configHome = configDir();
const fail = (reason: ResolveFailureJson["reason"], error: string): number => {
stderr.error(error);
if (args.json) stdout.log(JSON.stringify({ schema: RESOLVE_SCHEMA, ok: false, reason, error } satisfies ResolveFailureJson));
return 1;
};
let diagnostics: ConfigDiagnostics;
try {
diagnostics = readDiagnostics();
} catch (error) {
// A resolution that could not run must not read as "no proxy": the caller has to
// refuse to guess (D5) rather than treat this as a proven-absent verdict.
return fail("config_unreadable", `resolve failed: ${error instanceof Error ? error.message : String(error)}`);
}
if (diagnostics.source === "fallback") {
// An invalid config must not resolve to defaults: the effective port would be a
// guess at 10100 while the operator's config.port is unread. The repair-to-defaults
// policy in loadConfig is for interactive recovery, not for a shell contract.
return fail("config_invalid", `resolve failed: the config in ${configHome} is invalid (${diagnostics.error ?? "unknown error"}); refusing to guess.`);
}
let live: LiveProxy | null;
try {
live = await findLive();
} catch (error) {
return fail("discovery_failed", `resolve failed: ${error instanceof Error ? error.message : String(error)}`);
}
if (!live) {
// findLiveProxy collapses "definitely nothing" and "could not tell" into the same
// null. The launch decision keys on this verdict, so resolve owes the caller the
// tri-state answer the updater already enforces: only EVERY candidate definitively
// dead is absence. Anything else is unknown, and unknown exits 1 — it must never
// authorise starting a second runtime.
let provenDown = false;
try {
provenDown = await everyEndpointProvenDownAsync(endpointsToProve(readRuntime(), diagnostics.config), probeEndpoint);
} catch {
// A probe that cannot run is not evidence of absence.
provenDown = false;
}
if (!provenDown) {
return fail("liveness_unknown", "resolve: liveness is unknown (a probe timed out or a listener withheld /healthz); refusing to treat unknown as absent.");
}
}
let ownership: ServiceOwnershipResolution;
try {
ownership = resolveOwnership();
} catch (error) {
ownership = { kind: "unknown", reason: error instanceof Error ? error.message : String(error) };
}
let takeover: ResolveTakeover;
if (!live) {
// A proven absence may authorize start, but there is no runtime to take over.
// Avoid synchronous managing-CLI version probes on this launch path.
takeover = {
kind: "blocked",
reason: "runtime-absent",
detail: "no live runtime is available for takeover",
minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
};
} else if (ownership.kind === "unknown") {
// The claim cannot be read, so nothing can be approved against it. This reason is a
// wire answer, not a new member of the compatibility union.
takeover = {
kind: "blocked",
reason: "ownership-unknown",
detail: ownership.reason,
minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
};
} else {
try {
const resolved = resolveState();
if (resolved.kind === "unknown") {
takeover = {
kind: "blocked",
reason: "ownership-unknown",
detail: resolved.reason,
minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
};
} else {
const resolvedState = resolved.kind === "state" ? resolved.state : null;
takeover = assessServiceTakeoverCompatibility({
state: resolvedState,
subject: ownership,
managers: observeManagers(resolvedState),
});
}
} catch (error) {
takeover = {
kind: "blocked",
reason: "managing-cli-unknown",
detail: error instanceof Error ? error.message : String(error),
minimumCliVersion: SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION,
};
}
}
let supervision: ReturnType<typeof inspectDesktopSupervision> | undefined;
if (live) {
try {
supervision = live.pid === null ? { kind: "unknown", reason: "pid-unavailable", desktopSeen: false }
: (io.inspectSupervision ?? inspectDesktopSupervision)({ targetPid: live.pid });
} catch {
// Supervision is independent evidence; its failure cannot invalidate established liveness.
supervision = { kind: "unknown", reason: "probe-failed", desktopSeen: false };
}
}
const json = buildResolveJson(diagnostics.config, live, configHome, cliVersion(), ownership, takeover, supervision);
if (args.json) stdout.log(JSON.stringify(json));
else reportHuman(json, stdout);
return 0;
}