UNPKG

@bitkyc08/opencodex

Version:

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

330 lines (312 loc) • 17.9 kB
import { runCatalogAction } from "./catalog-command-result"; import { CliUsageError, desktopSwitchApplyReason, printData, rejectArgs, runCliAction, runtimeRequest, summaryLines, takeBooleanOption, takeFlag, takeOption, type RuntimeApiDeps, } from "./runtime-api"; const USAGE = `Usage: ocx system [status] [--json] ocx system health [--json] ocx system settings [--auto-start <on|off>] [--stream-mode <auto|legacy-tee|eager-relay>] [--desktop-authless <on|off>] [--client-compaction <on|off>] [--show-codex-credits <on|off>] [--account-picker <on|off>] [--main-account-hard-lock <on|off>] [--ultra-fast-tier <on|off>] [--fast-rows <on|off>] [--reserve <on|off>] [--json] ocx system startup <health|install-service|install-shim> [--json] ocx system diagnostics [--json] ocx system sync [--json] ocx system codex-app-server [--json] ocx system codex-restart --yes [--json] ocx system codex-cli-update check [--json] ocx system codex-cli-update attest [--json] ocx system codex-cli-update attest --candidate <absolute-path> --npm-prefix <absolute-path> --npm-cli <absolute-path> --node <absolute-path> [--json] ocx system codex-cli-update plan [--channel latest] [--json] ocx system codex-cli-update apply --plan-id <32-hex> --yes [--request-id <key>] [--json] ocx system codex-cli-update status <job-id> [--json] ocx system update check [--channel <latest|preview>] [--json] ocx system update run [--channel <latest|preview>] [--restart <on|off>] --yes [--json] ocx system update status <job-id> [--json] --client-compaction favors native replay portability for future compactions while keeping OpenCodeX routing active; the configured provider may process summaries and consume its quota.`; async function status(argv: string[], deps: RuntimeApiDeps): Promise<void> { const args = [...argv]; const wantsJson = takeFlag(args, "--json"); rejectArgs(args, USAGE); const [settings, startup, memory] = await Promise.all([ runtimeRequest("/api/settings", {}, deps), runtimeRequest("/api/startup-health", {}, deps), runtimeRequest("/api/system/memory", {}, deps), ]); const result = { settings, startup, memory }; printData(result, wantsJson, summaryLines(result)); } /** The management health observation is distinct from root liveness and aggregate status. */ async function health(argv: string[], deps: RuntimeApiDeps): Promise<number> { return runCatalogAction(async () => { const args = [...argv], wantsJson = takeFlag(args, "--json"); if (args.length) throw new CliUsageError("system health accepts only --json", USAGE); const raw = await runtimeRequest("/api/system/health", { method: "GET", redirect: "error" }, deps); const value = recordValue(raw), ledger = recordValue(value?.spendLedger); const counter = (number: unknown): number => { if (typeof number !== "number" || !Number.isSafeInteger(number) || number < 0 || number > 1_000_000) { throw new Error("Invalid health counter"); } return number; }; if (!value || Array.isArray(raw) || !ledger || Array.isArray(value.spendLedger) || value.status !== "ok" || value.service !== "opencodex" || typeof value.version !== "string" || !value.version.trim() || typeof value.uptime !== "number" || !Number.isFinite(value.uptime) || value.uptime < 0 || typeof value.pid !== "number" || !Number.isSafeInteger(value.pid) || value.pid <= 0 || (ledger.ownership !== "held" && ledger.ownership !== "unheld") || typeof ledger.initialized !== "boolean" || typeof ledger.configured !== "boolean" || typeof ledger.degraded !== "boolean") throw new Error("Invalid system health response"); const result = { status: "ok", service: "opencodex", version: value.version, uptime: value.uptime, pid: value.pid, spendLedger: { ownership: ledger.ownership, initialized: ledger.initialized, configured: ledger.configured, degraded: ledger.degraded, persistFailures: counter(ledger.persistFailures), corruptRecords: counter(ledger.corruptRecords), }, }; printData(result, wantsJson, [ `Management endpoint: ${result.status} (${result.service} ${result.version}, PID ${result.pid})`, `Uptime: ${result.uptime} seconds`, `Spend ledger: ${ledger.degraded ? "degraded" : "no degradation reported"}; ownership ${ledger.ownership}`, `Ledger initialized: ${ledger.initialized}; configured: ${ledger.configured}`, `Ledger persistence failures: ${result.spendLedger.persistFailures}; corrupt records: ${result.spendLedger.corruptRecords}`, "This observation does not certify every subsystem healthy.", ...(ledger.degraded ? ["Next: inspect the proxy diagnostics and spend-ledger configuration before relying on spend limits."] : []), ]); }); } function recordValue(value: unknown): Record<string, unknown> | undefined { return value !== null && typeof value === "object" ? value as Record<string, unknown> : undefined; } function desktopSwitchInertReason(reason: unknown): string { if (reason === "client_role") return "this proxy is running in the client role"; if (reason === "non_loopback_bind_requires_admission_token") { return "a non-loopback bind requires an admission token, so this flag is inert"; } return "the stored setting is not effective in the current runtime configuration"; } function settingsUpdateLines( result: unknown, changed: { desktopAuthless: boolean; clientCompaction: boolean }, ): string[] { if (!changed.desktopAuthless && !changed.clientCompaction) return ["System settings updated."]; const switches = recordValue(recordValue(result)?.codexDesktopSwitches); if (!switches) return ["System settings updated."]; const apply = recordValue(switches.apply); const refused = apply?.applied === false && apply.reason === "injection_refused"; const lines: string[] = []; const appendSwitch = (key: string, label: string): boolean => { const state = recordValue(switches[key]); if (!state || typeof state.stored !== "boolean" || (typeof state.effective !== "boolean" && state.effective !== null)) return false; lines.push(`${label}: stored ${state.stored ? "on" : "off"}.`); if (refused) return true; if (state.effective === null) { // `null` is reported for both withheld cases; the apply reason is the only place // that still distinguishes them, so the line has to read it rather than claim // external control over an ownership the server could not determine. const withheld = recordValue(switches.apply)?.reason === "ownership_undetermined" ? "effective state could not be determined" : "effective state is controlled by the external model provider"; lines.push(`${label}: ${withheld}.`); return true; } // The effective value is always stated, even when it matches. Printing it only on a // mismatch would make silence ambiguous — the reader could not tell "the stored value is // in force" from "this build does not report effective state", and that ambiguity is a // smaller version of the defect being fixed. lines.push(state.effective === state.stored ? `${label}: effective ${state.effective ? "on" : "off"}.` : `${label}: effective ${state.effective ? "on" : "off"} because ${desktopSwitchInertReason(state.inertReason)}.`); return true; }; if (changed.desktopAuthless && !appendSwitch("codexDesktopAuthless", "Codex desktop authless")) { return ["System settings updated."]; } if (changed.clientCompaction && !appendSwitch("codexClientCompaction", "Codex client compaction")) { return ["System settings updated."]; } const authSource = recordValue(switches.authSource); if (!apply || typeof apply.applied !== "boolean" || !authSource || typeof authSource.summary !== "string") { return ["System settings updated."]; } if (apply.applied) { lines.push("Codex config: ~/.codex/config.toml was rewritten."); } else { const detail = typeof apply.detail === "string" && apply.detail.length > 0 ? ` Details: ${apply.detail}` : ""; const retry = refused || apply.reason === "external_provider" ? "" : apply.reason === "ownership_undetermined" ? " Resolve the reported config.toml read error, then inspect 'ocx system settings --json'." : apply.reason === "integration_disabled" ? " Enable Codex integration before applying the stored settings." : " Run 'ocx sync' to apply the stored settings."; lines.push(`Codex config: ~/.codex/config.toml was not rewritten because ${desktopSwitchApplyReason(apply.reason)}.${detail}${retry}`); } lines.push(`Auth source: ${authSource.summary}`); return lines; } async function settings(argv: string[], deps: RuntimeApiDeps): Promise<void> { const args = [...argv]; const wantsJson = takeFlag(args, "--json"); const autoStart = takeBooleanOption(args, "--auto-start"); const streamMode = takeOption(args, "--stream-mode"); const desktopAuthless = takeBooleanOption(args, "--desktop-authless"); const clientCompaction = takeBooleanOption(args, "--client-compaction"); rejectArgs(args, USAGE); if (autoStart === undefined && streamMode === undefined && desktopAuthless === undefined && clientCompaction === undefined) { const result = await runtimeRequest("/api/settings", {}, deps); printData(result, wantsJson, summaryLines(result)); return; } const body = { ...(autoStart !== undefined ? { codexAutoStart: autoStart } : {}), ...(streamMode !== undefined ? { streamMode } : {}), ...(desktopAuthless !== undefined ? { codexDesktopAuthless: desktopAuthless } : {}), ...(clientCompaction !== undefined ? { codexClientCompaction: clientCompaction } : {}), }; const result = await runtimeRequest("/api/settings", { method: "PUT", body: JSON.stringify(body) }, deps); printData(result, wantsJson, settingsUpdateLines(result, { desktopAuthless: desktopAuthless !== undefined, clientCompaction: clientCompaction !== undefined, })); } async function startup(argv: string[], deps: RuntimeApiDeps): Promise<void> { const args = [...argv]; const action = (args.shift() ?? "health").toLowerCase(); const wantsJson = takeFlag(args, "--json"); rejectArgs(args, USAGE); if (action === "health" || action === "status") { const result = await runtimeRequest("/api/startup-health", {}, deps); printData(result, wantsJson, summaryLines(result)); return; } if (action !== "install-service" && action !== "install-shim") throw new CliUsageError("startup action must be health, install-service, or install-shim", USAGE); const result = await runtimeRequest("/api/startup-action", { method: "POST", body: JSON.stringify({ action }) }, deps); printData(result, wantsJson, [String((result as Record<string, unknown>).message ?? `${action} complete.`)]); } async function update(argv: string[], deps: RuntimeApiDeps): Promise<void> { const args = [...argv]; const action = (args.shift() ?? "check").toLowerCase(); const wantsJson = takeFlag(args, "--json"); if (action === "status") { const jobId = args.shift(); if (!jobId) throw new CliUsageError("update job id is required", USAGE); rejectArgs(args, USAGE); printData(await runtimeRequest(`/api/update/status?jobId=${encodeURIComponent(jobId)}`, {}, deps), wantsJson); return; } const channel = takeOption(args, "--channel") ?? "latest"; if (channel !== "latest" && channel !== "preview") throw new CliUsageError("--channel must be latest or preview", USAGE); if (action === "check") { rejectArgs(args, USAGE); printData(await runtimeRequest(`/api/update/check?tag=${channel}`, {}, deps), wantsJson); return; } if (action !== "run") throw new CliUsageError(`unknown update action ${action}`, USAGE); const restart = takeBooleanOption(args, "--restart") ?? true; const yes = takeFlag(args, "--yes"); if (!yes) throw new CliUsageError("update run requires --yes", USAGE); rejectArgs(args, USAGE); const result = await runtimeRequest("/api/update/run", { method: "POST", body: JSON.stringify({ tag: channel, restart }) }, deps); const job = recordValue(recordValue(result)?.job); const jobId = typeof job?.id === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(job.id) ? job.id : undefined; const jobStatus = ["running", "restarting", "succeeded", "failed"].find(state => state === job?.status); const lines = jobId ? [ `Update job ${jobId}: ${jobStatus ?? "status unconfirmed"} (${channel}).`, `Check progress: ocx system update status ${jobId}`, ] : ["Update request returned no usable job ID. Check: ocx system update check."]; printData(result, wantsJson, lines); } export async function handleSystemCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> { const [sub = "status", ...rest] = argv; if (sub === "health") return health(rest, deps); if (sub === "settings") { const { SYSTEM_PARITY_OPTIONS, handleSystemSettingsParity } = await import("./system-settings-parity"); if (rest.some(arg => SYSTEM_PARITY_OPTIONS.some(flag => arg === flag || arg.startsWith(`${flag}=`)))) { return handleSystemSettingsParity(rest, deps); } } if (sub === "codex-cli-update") { const { handleCodexCliUpdateCommand } = await import("./codex-cli-update"); return await handleCodexCliUpdateCommand(rest); } return runCliAction(async () => { if (sub === "status") await status(rest, deps); else if (sub === "settings") await settings(rest, deps); else if (sub === "startup") await startup(rest, deps); else if (sub === "diagnostics") { const args = [...rest]; const wantsJson = takeFlag(args, "--json"); rejectArgs(args, USAGE); printData(await runtimeRequest("/api/diagnostics/project-config", {}, deps), wantsJson); } else if (sub === "sync") { const args = [...rest]; const wantsJson = takeFlag(args, "--json"); rejectArgs(args, USAGE); printData(await runtimeRequest("/api/sync", { method: "POST" }, deps), wantsJson); } else if (sub === "codex-app-server") { // The GUI reads this state directly (gui/src/codex-app-server-state.ts). Without a verb // an agent could not see whether the Codex app-server was reachable at all. const args = [...rest]; const wantsJson = takeFlag(args, "--json"); rejectArgs(args, USAGE); printData(await runtimeRequest("/api/system/codex-app-server", {}, deps), wantsJson); } else if (sub === "codex-restart") { // --yes required: this interrupts running Codex turns, and when the desktop picker predates // the catalog it also quits and relaunches the app, which can discard unsaved client state. const args = [...rest]; const wantsJson = takeFlag(args, "--json"); const yes = takeFlag(args, "--yes"); if (!yes) throw new CliUsageError( "system codex-restart requires --yes: this restarts the Codex app-servers, interrupting running turns, and when the desktop app's model picker predates the current catalog (or that cannot be determined) it fully quits and relaunches the Codex desktop app, so unsaved composer drafts, model-picker selections, and pending approval prompts may be lost", USAGE, ); rejectArgs(args, USAGE); const result = await runtimeRequest("/api/system/codex-restart", { method: "POST" }, deps); printData(result, wantsJson, codexRestartLines(result)); } else if (sub === "update") await update(rest, deps); else throw new CliUsageError(`unknown system command ${sub}`, USAGE); }); } /** * Operator text for a codex-restart outcome. It reports what happened to the desktop app, * because whether unsaved client state survived is the one thing the operator needs to know. */ export function codexRestartLines(result: unknown): string[] { const view = recordValue(result); const desktop = recordValue(view?.desktopApp); const reason = typeof desktop?.reason === "string" ? desktop.reason : undefined; // Only a reported `stale` reading may claim the picker predated the catalog; an unreadable // reading also takes the full restart, and an older proxy reports no reading at all. const why = desktop?.pickerState === "stale" ? "its model picker predated the current catalog" : "its model picker could not be confirmed current"; const stopped = Array.isArray(view?.stopped) ? view.stopped.length : 0; const appServers = view?.code === "stopped" ? `Stopped ${stopped} Codex app-server(s); their owners start replacements.` : view?.code === "partially_stopped" ? "Some Codex app-servers did not exit; stop them manually if Codex stays stale." : view?.code === "enumeration_unavailable" ? "Could not list Codex app-servers, so none were stopped." : "No Codex app-server needed stopping."; if (reason === "picker_current") { return [appServers, "The Codex desktop app was left running: its model picker already shows the current catalog, so unsaved drafts and pending approvals were kept."]; } if (reason === "no_targets") return [appServers, "The Codex desktop app is not running."]; if (desktop?.relaunch === "started") { return [appServers, `The Codex desktop app was quit and relaunched because ${why}. Unsaved composer drafts, model-picker selections, and pending approval prompts may have been lost.`]; } if (desktop?.attempted === true) { return [appServers, `The Codex desktop app restart did not complete (${reason ?? "no outcome reported"}). Unsaved composer drafts, model-picker selections, and pending approval prompts may have been lost.`]; } return [appServers, `The Codex desktop app was not restarted (${reason ?? "no outcome reported"}).`]; } export const SYSTEM_USAGE = USAGE;