UNPKG

@bitkyc08/opencodex

Version:

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

144 lines (131 loc) • 6.39 kB
/** * Structured summary for `ocx stop --json` (D4 of the app runtime ownership unit). * * The desktop shell drives the real `ocx stop` as a child process so the receipt-backed * teardown, the drain, the Windows respawn verification and the client-config restore run * exactly as they do from a terminal. This module makes that run's RESULT readable from * outside: a StopRunRecord is threaded through the existing stop path in * src/cli/index.ts (the same booleans that already decide the exit code), and * summarizeStopRun turns it into one versioned JSON document. * * Nothing here re-decides anything. If a field of the record is wrong, the fix belongs * in the stop path, not in the summarizer. */ import { STOP_HISTORY_DEFERRED_EXIT_CODE } from "../update/stop-contract.mjs"; /** Wire version of the stop summary document. */ export const STOP_SUMMARY_SCHEMA = "ocx-stop/1"; export type StopServiceOutcome = | "absent" | "stopped" | "stopped-respawnable" | "failed" | "state-unknown" | "error"; export type StopProxyOutcome = | "stopped" | "stopped-orphan" | "not-running" | "stop-failed" | "ownership-refused" | "unresolvable-pid" | "respawned" | "unknown"; export type StopSharedTeardownOutcome = | "restored" | "performed-by-proxy" | "refused" | "failed" | "skipped"; /** Facts recorded where the stop path already decides them. */ export interface StopRunRecord { /** What stopServiceIfInstalledDetailed returned, or "error" when it threw. */ service: StopServiceOutcome; /** Which proxy path ran and how it ended. */ proxy: StopProxyOutcome; /** Who ended up restoring shared client config (native Codex + Grok). */ sharedTeardown: StopSharedTeardownOutcome; /** An inherited pending-teardown receipt blocked the restore. */ inheritedTeardownBlocks: boolean; /** A discharged receipt could not be removed from disk. */ receiptClearFailed: boolean; } /** The internal booleans that already pick the process exit code. */ export interface StopRunSignals { failed: boolean; historyOnly: boolean; historyDeferred: boolean; exitCode: number; } export interface StopSummaryJson { schema: typeof STOP_SUMMARY_SCHEMA; /** Strict exit-code view: true only for exit 0. */ ok: boolean; outcome: "stopped" | "not-running" | "history-incomplete" | "history-deferred" | "failed" | "approval-changed" | "manager-still-active"; exitCode: number; /** True when this stop left no proxy of this home running by its own paths. */ runtimeDown: boolean; service: StopServiceOutcome; proxy: StopProxyOutcome; sharedTeardown: StopSharedTeardownOutcome; /** One stable human-readable line for a caller's UI. */ message: string; } /** What handleStop returns: the pre-existing boolean plus the structured twin. */ export interface StopOutcome { /** * The exact boolean the stop path returned before summaries existed (!stopFailed). * It is NOT the same as summary.ok: 79/80 stops return true here, because the * downtime warning that keys on it applies whenever the runtime went down. */ ok: boolean; summary: StopSummaryJson; } function stopOutcome(record: StopRunRecord, signals: StopRunSignals): StopSummaryJson["outcome"] { if (signals.failed) return "failed"; if (signals.historyOnly) return "history-incomplete"; if (signals.historyDeferred) { // The deferred exit code is a proven claim; anything else means another obligation // was sitting in the home, which the exit-code logic already reports as failure. return signals.exitCode === STOP_HISTORY_DEFERRED_EXIT_CODE ? "history-deferred" : "failed"; } if (record.proxy === "not-running") return "not-running"; if (record.proxy === "stopped" || record.proxy === "stopped-orphan") return "stopped"; return "failed"; } function stopMessage(record: StopRunRecord, signals: StopRunSignals, outcome: StopSummaryJson["outcome"]): string { if (record.proxy === "respawned") return "The proxy was respawned after the stop; it is still running."; if (record.proxy === "ownership-refused") return "The proxy refused the stop; it belongs to a different opencodex home."; if (record.proxy === "unresolvable-pid") return "A proxy is answering, but its process id could not be resolved, so it was not stopped."; if (record.proxy === "stop-failed") return "The proxy process could not be stopped."; if (record.service === "failed") return "The installed service manager did not stop and may respawn the proxy."; if (record.service === "state-unknown") return "The service manager state could not be read."; if (record.service === "error") return "Stopping the installed service failed."; if (record.inheritedTeardownBlocks) return "An earlier stop left an outstanding shared teardown that could not be confirmed."; if (record.sharedTeardown === "failed") return "The shared teardown failed; client configuration may still point at the stopped proxy."; if (record.receiptClearFailed) return "The shared teardown finished, but its receipt could not be removed."; if (record.sharedTeardown === "refused") return "The shared teardown was refused before it changed anything; it is still owed."; if (signals.historyOnly) return "The proxy stopped; Codex history cleanup did not complete."; if (outcome === "history-deferred") return "The proxy stopped; the shared teardown was deferred and is still owed."; if (outcome === "not-running") return "No proxy was running."; if (outcome === "stopped") return "The proxy stopped."; return "The stop failed."; } /** Pure mapper from the recorded run to the wire document. */ export function summarizeStopRun(record: StopRunRecord, signals: StopRunSignals): StopSummaryJson { const outcome = stopOutcome(record, signals); return { schema: STOP_SUMMARY_SCHEMA, ok: signals.exitCode === 0, outcome, exitCode: signals.exitCode, runtimeDown: record.proxy === "stopped" || record.proxy === "stopped-orphan" || record.proxy === "not-running", service: record.service, proxy: record.proxy, sharedTeardown: record.sharedTeardown, message: stopMessage(record, signals, outcome), }; } /** Emit the summary as exactly one JSON document on stdout. */ export function printStopSummary(summary: StopSummaryJson, stdout: { log: (s: string) => void } = console): void { stdout.log(JSON.stringify(summary)); }