UNPKG

@bitkyc08/opencodex

Version:

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

931 lines (901 loc) • 43.7 kB
import { durableBunRuntime } from "../lib/bun-runtime"; import { existsSync, readFileSync } from "node:fs"; import { codexAutoStartEnabled, getConfigPath, readConfigDiagnostics } from "../config"; import { getPidPath, readPid, readRuntimePort, type RuntimePortState } from "../config/process-state"; import { diagnoseCodexBundledPlugins, type CodexPluginsDiagnostic } from "../codex/plugins-doctor"; import { findLiveProxy, probeHostname } from "../server/proxy-liveness"; import type { OcxConfig } from "../types"; import { diagnoseService, serviceLogPath } from "../service"; import { collectStartupHealth, type StartupHealth } from "../codex/autostart-health"; import { getCodexRoutingKind } from "../codex/inject"; import { missingOwnedCatalogPath } from "../codex/inject/config-toml"; import { CODEX_CONFIG_PATH } from "../codex/paths"; import { diagnoseCodexShim } from "../codex/shim"; import { displayCodexRuntimePath, effortClampAppliesToRuntime, liveRemovedEfforts, loadLastEffortClamp, resolveCodexRuntime } from "../codex/runtime"; import { packageVersion } from "./help"; import { computeVersionSkew, type VersionSkew } from "./version-skew"; import { redactSecretString, redactUserPath } from "../lib/redact"; import { collectOrcaCodexHomeDiagnostic, type OrcaCodexHomeDiagnostic } from "../codex/home"; import { grokFenceEndpointDrift, readGrokStatus } from "../grok/status"; import { effectiveLoopbackListenerPort } from "../codex/loopback-target"; import { journaledInjectedOpenaiBaseUrl, journaledInjectedRealtimeWsBaseUrl } from "../codex/journal"; import { detectCodexRoutingDrift, type JournaledCodexRouting } from "../codex/routing-drift"; import { claudeDesktopIntegrationEnabled } from "../codex/desired-state"; import { claudeDesktopPolicyHealth, probeClaudeDesktopPolicy, type ClaudeDesktopPolicyHealth } from "../claude/desktop-policy"; import { collectClientConnectionStatus, type ClientConnectionStatus } from "./connect"; import { readClientConnectionState, sameClientConnectionOwner } from "../client/state"; import type { HubStateOAuthEntry, HubStateProvider } from "../remote/hub-state"; import type { HubStateSource } from "../client/hub-state"; import { readServiceApiTokenState, serviceApiTokenFilePath } from "../lib/service-secrets"; import { tokenCollidesWithAdmin } from "../lib/admin-secrets"; export { proxyHealthFailureReason, isConnectionRefused, isUncleanExitEvidence, probeUncleanExitState } from "./status-probes"; export type { ListenTarget } from "./status-probes"; import { checkProxyHealth, probeUncleanExitState, type ListenTarget } from "./status-probes"; import { LOCAL_MANAGEMENT_READ_PATHS } from "../lib/local-management-capability"; import { fetchBoundLocalManagementRead } from "../server/local-management-read-client"; /** * The state of the data-plane admission secret the SERVICE will use. State only -- never the value. * * Always about the file, because the file is what the service reads: the launchd plist and the * systemd unit `cat` it into `OPENCODEX_API_AUTH_TOKEN` before exec, so a token in the CLI's own * shell says nothing about the running hub. `present (env)` used to be reported here and was * simply wrong about whose environment it meant (see `dataTokenEnvInShell`). * * `admin-collision (file)` is the #4236 incident shape: the file holds the MANAGEMENT token, so * the server fences the whole management plane closed at boot and the hub crash-loops. It used * to report `present (file)`, which is how the cause stayed invisible. */ export type HubDataTokenState = | "present (file)" | "unsafe (file)" | "admin-collision (file)" | "missing"; export type HubStatus = { /** Advertised data origin: hub.dataPublicOrigin, else derived from the bind address. */ dataOrigin: string; /** True when dataOrigin came from config rather than being derived from the bind. */ dataOriginConfigured: boolean; /** * The unauthenticated loopback listener, in PR2's two forms: `companion` shares the public * port (the one-port hub), `ported` binds its own. `off` means the hub does not serve its * own local clients at all. */ loopbackListener: { state: "off" | "companion" | "ported"; port: number | null }; managementIngress: { enabled: boolean; port: number | null }; managementPublicOrigin: string | null; dataToken: HubDataTokenState; dataTokenPath: string; /** * `OPENCODEX_API_AUTH_TOKEN` is set in the shell that ran `ocx status` — which is NOT the * environment the installed service runs in. Reported separately, and honestly, because it * does decide what a FOREGROUND `ocx start` in this same shell would admit. */ dataTokenEnvInShell: boolean; }; /** * What a connected client learned from its hub, and how reliable that answer is (#4236). * * `stateSource` is the load-bearing field. "hub" is a live read; "cache" is the last good read * from THIS connection, still the hub's state rather than this machine's; "unavailable" means * nothing true is known, and the consumer must say so rather than substitute local facts. A * client's own `providers`/`oauth` sections are empty by design, so presenting them as the * answer is not a degraded report — it is a wrong one. */ export type CliRemoteHubStatus = { connected: boolean; /** The hub's advertised data origin when it publishes one, else the URL this client dials. */ origin: string | null; stateSource: HubStateSource; /** Present whenever `stateSource` is not "hub". Operator-facing, never a bare error code. */ reason?: string; fetchedAt?: string; ageSeconds?: number; hubVersion: string | null; providers: HubStateProvider[]; oauth: HubStateOAuthEntry[]; subagentModels: string[]; /** The hub hit one of its own caps, so the lists above are a prefix and the report says so. */ truncated: boolean; /** The hub's own Claude Code toggle; a client cannot infer it from local config. */ claudeCodeEnabled: boolean | null; }; export type CliStatusJson = { schemaVersion: 1; /** * This machine's topology role, named rather than inferred (#4236). * * Every other field in this report was already ambiguous without it: an agent reading * `providers: {}` on a client could not tell "nothing is configured" from "the provider * configuration lives on the hub". Additive, so `schemaVersion` stays 1. */ runtimeRole: "standalone" | "hub" | "client"; proxy: { running: boolean; pid: number | null; /** Persisted owner records outlived their process: the last proxy did not exit cleanly. */ staleProcessState: boolean; health: { ok: boolean; url: string; message: string; }; }; dashboard: { url: string }; listen: { port: number; hostname: string | null; source: "runtime" | "config"; }; paths: { config: string; pid: string; runtime: string; }; runtime: { source: string; overrideEnv?: string; }; codexAutostart: boolean; startup: StartupHealth; defaultProvider: string | null; config: { source: "default" | "file" | "fallback"; error: string | null; }; connection: { state: "disconnected" | "connected" | "invalid" | "mismatched"; reason?: string; serverUrl?: string; managementUrl?: string; protocolVersion?: number; apiKeyId?: string; selectedClients?: string[]; catalog?: "present" | "missing" | "unsafe"; catalogAgeSeconds?: number; credentialFile: "owned" | "missing" | "changed" | "unsafe"; /** * #4207: whether the selected local Codex CLI can consume the catalog this client * installed. Absent unless a client connection exists. `connected` alone proved only the * hub and the credential, and a reader who stopped there saw a healthy connection while * `codex exec` was exiting before its first request. */ readiness?: "ready" | "unverified" | "incompatible"; readinessReason?: string; }; service: { summary: string }; codexShim: { summary: string }; codexPlugins: CodexPluginsDiagnostic; codexRuntime: { path: string; version: string | null; source: string; newerAvailable: { path: string; version: string | null } | null; warning: string | null; catalogClamp: { active: boolean; removedEfforts: string[]; runtimeVersion: string | null; }; }; codexHome: OrcaCodexHomeDiagnostic; claudeDesktop: { desiredEnabled: boolean; policy: ClaudeDesktopPolicyHealth; }; /** * The hub-only facts an operator needs in one place, or null on a standalone/client machine. * * Scattered across the report they were unusable: the public data origin came from `listen`, * the management origin was folded into `dashboard.url`, the loopback companion appeared * nowhere, and the data-plane token appeared nowhere at all -- so the one question a hub * operator actually asks ("is this reachable, and can another machine join?") took four other * commands to answer. Additive and nullable, so `schemaVersion` stays 1. * * Never carries a token value; only which source holds one. */ hub: HubStatus | null; /** * The hub's answer on a connected client, or a not-connected placeholder (#4236). * * Separate from `connection`, which describes the LINK (is the key owned, is the catalog * present). This describes what is on the other end of it. Additive and always present, so * `schemaVersion` stays 1 and a consumer never has to branch on the key existing. */ remoteHub: CliRemoteHubStatus; /** * This CLI's version against the running proxy's (#2701). * * Additive and optional-by-value, so `schemaVersion` stays 1: an existing consumer that * ignores the key is unaffected, and `proxyVersion` is null when nothing is live. */ versionSkew: VersionSkew; }; export type CliStatusView = { json: CliStatusJson; proxyLabel: string; healthLabel: string; }; type StatusListenConfig = Pick<OcxConfig, "port" | "hostname" | "runtimeRole" | "hub">; function statusDashboardUrl(config: StatusListenConfig, hostname: string | undefined, port: number): string { const managementOrigin = config.runtimeRole === "hub" ? config.hub?.managementPublicOrigin : undefined; if (managementOrigin) return managementOrigin.endsWith("/") ? managementOrigin : `${managementOrigin}/`; const reachableHostname = probeHostname(hostname); const dashboardHostname = reachableHostname === "127.0.0.1" || reachableHostname === "[::1]" || reachableHostname.toLowerCase() === "localhost" ? "localhost" : reachableHostname; return `http://${dashboardHostname}:${port}/`; } const STARTUP_HEALTH_BOOLEAN_FIELDS = [ "routingInjected", "localRoutingDependency", "autostartEnabled", "rebootSafe", "serviceInstalled", "serviceViable", "serviceEnabled", "serviceRunning", "serviceStale", "serviceConflict", "shimInstalled", "shimHealthy", "serviceSupported", "diagnosticStale", ] as const; export async function fetchLiveStartupHealth( live: NonNullable<Awaited<ReturnType<typeof findLiveProxy>>>, deps: Parameters<typeof fetchBoundLocalManagementRead>[2] = {}, ): Promise<StartupHealth | null> { const result = await fetchBoundLocalManagementRead( live, LOCAL_MANAGEMENT_READ_PATHS.startupHealth, { timeoutMs: 1_500, ...deps, requireResponseProof: true }, ); if (result.kind !== "response" || !result.response.ok) return null; let payload: unknown; try { payload = await result.response.json(); } catch { return null; } if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null; const row = payload as Record<string, unknown>; if (row.status !== "native" && row.status !== "protected" && row.status !== "at-risk") return null; if (row.protection !== "service" && row.protection !== "shim" && row.protection !== "none") return null; if (row.routingKind !== "native" && row.routingKind !== "opencodex-local" && row.routingKind !== "custom-local" && row.routingKind !== "custom-remote" && row.routingKind !== "unknown") return null; if (row.shimCoverage !== "full" && row.shimCoverage !== "cli-only" && row.shimCoverage !== "none") return null; if (typeof row.platform !== "string") return null; if (row.recommendedCommand !== null && typeof row.recommendedCommand !== "string") return null; if (!row.commands || typeof row.commands !== "object" || Array.isArray(row.commands)) return null; for (const key of ["installService", "repairService", "installShim", "restoreNative"] as const) { if (typeof (row.commands as Record<string, unknown>)[key] !== "string") return null; } if (row.routingAdoption !== undefined) { if (!row.routingAdoption || typeof row.routingAdoption !== "object" || Array.isArray(row.routingAdoption)) return null; const adoption = row.routingAdoption as Record<string, unknown>; if (adoption.adoption !== "not-applicable" && adoption.adoption !== "adopted" && adoption.adoption !== "pending-client-restart" && adoption.adoption !== "unknown") return null; if (adoption.injectedAtMs !== null && typeof adoption.injectedAtMs !== "number") return null; if (typeof adoption.observedClients !== "number" || !Array.isArray(adoption.staleClients)) return null; for (const client of adoption.staleClients) { if (!client || typeof client !== "object" || Array.isArray(client)) return null; const row = client as Record<string, unknown>; if (typeof row.pid !== "number" || typeof row.startedAtMs !== "number") return null; } } for (const key of STARTUP_HEALTH_BOOLEAN_FIELDS) if (typeof row[key] !== "boolean") return null; return payload as StartupHealth; } /** Prefer an attested live verdict and evaluate the local fallback only when live state is absent. */ export function selectStatusStartupHealth( liveStartup: StartupHealth | null, fallback: () => StartupHealth, ): StartupHealth { return liveStartup ?? fallback(); } /** Build the service summary from the same startup source that `ocx status` selected. */ export function statusServiceSummary( liveStartup: StartupHealth | null, service: Pick<ReturnType<typeof diagnoseService>, "installed" | "summary">, live: boolean, ): string { if (liveStartup) { if (liveStartup.protection === "service" && liveStartup.serviceViable) { return `running under the live managed service (logs: ${serviceLogPath()})`; } const state = [ liveStartup.serviceInstalled ? "installed" : "absent", liveStartup.serviceRunning ? "running" : "not running", liveStartup.serviceViable ? "viable" : "not viable", ].join(", "); const action = liveStartup.recommendedCommand ? `; run '${liveStartup.recommendedCommand}'` : ""; return `live startup reports service ${state}${action} (logs: ${serviceLogPath()})`; } return service.installed && !live ? `${service.summary} — registered but NOT serving; see ${serviceLogPath()} and re-run 'ocx service repair'` : service.summary; } /** * The hub block, or null when this machine is not a hub. * * The token line is about the FILE, not this shell. `ocx status` used to print `present (env)` * whenever the calling shell happened to export `OPENCODEX_API_AUTH_TOKEN`, but the service * wrapper overwrites that variable from the token file before exec — so the label described the * operator's terminal and not the hub. The shell's variable is reported as its own flag instead. * * The token VALUE is never read into the report. `readServiceApiTokenState` returns it; the only * things derived from it are `kind` and the admin-token comparison, neither of which can carry * bytes of the secret. */ export function collectHubStatus( config: Pick<OcxConfig, "runtimeRole" | "hostname" | "port" | "hub" | "unauthenticatedLoopbackListener">, listen: { port: number; hostname?: string | null }, env: NodeJS.ProcessEnv = process.env, ): HubStatus | null { if (config.runtimeRole !== "hub") return null; const listener = config.unauthenticatedLoopbackListener; const loopbackPort = effectiveLoopbackListenerPort(config, listen.port); const ingress = config.hub?.managementIngress; const configuredDataOrigin = config.hub?.dataPublicOrigin; const host = probeHostname(listen.hostname ?? config.hostname); const tokenState = ((): HubDataTokenState => { const state = readServiceApiTokenState(); if (state.kind === "unsafe") return "unsafe (file)"; if (state.kind !== "present") return "missing"; return tokenCollidesWithAdmin(state.token, env) ? "admin-collision (file)" : "present (file)"; })(); return { dataOrigin: configuredDataOrigin ?? `http://${host === "127.0.0.1" ? "localhost" : host}:${listen.port}`, dataOriginConfigured: Boolean(configuredDataOrigin), loopbackListener: loopbackPort === null ? { state: "off", port: null } : { state: listener?.enabled && listener.port === undefined ? "companion" : "ported", port: loopbackPort }, managementIngress: { enabled: ingress?.enabled === true, port: ingress?.enabled === true ? ingress.port : null, }, managementPublicOrigin: config.hub?.managementPublicOrigin ?? null, dataToken: tokenState, dataTokenPath: serviceApiTokenFilePath(), dataTokenEnvInShell: Boolean(env.OPENCODEX_API_AUTH_TOKEN?.trim()), }; } /** * The human rendering of the hub block, owned here rather than in the `ocx status` printer so * the sentences are testable without spawning the CLI. Indentation is the caller's. */ export function hubStatusLines(hub: HubStatus): string[] { const listener = hub.loopbackListener.state === "off" ? "off — this hub does not route its own local Codex/Claude clients" : hub.loopbackListener.state === "companion" ? `companion on http://127.0.0.1:${hub.loopbackListener.port} — same port as the public listener, no credential needed locally` : `ported on http://127.0.0.1:${hub.loopbackListener.port} — a second port local clients must be pointed at`; const tokenLines = [` Data token: ${hub.dataToken}${hub.dataToken === "missing" ? "" : ` at ${hub.dataTokenPath}`}`]; if (hub.dataToken === "admin-collision (file)") { // Naming the consequence matters more than naming the state: this is what a crash-looping // hub looks like from `ocx status`, and nothing else in the report says so (#4236). tokenLines.push( " that file holds the MANAGEMENT token, so the hub fences its management API closed at boot —", " delete it and run 'ocx service repair' to generate a data-plane token", ); } if (hub.dataTokenEnvInShell) { tokenLines.push(" OPENCODEX_API_AUTH_TOKEN is also set in this shell; the installed service reads the file, not this"); } return [ "Hub:", ` Data origin: ${hub.dataOrigin}${hub.dataOriginConfigured ? " (hub.dataPublicOrigin)" : " (derived from the bind address)"}`, ` Loopback listener: ${listener}`, ` Management ingress: ${hub.managementIngress.enabled ? `http://127.0.0.1:${hub.managementIngress.port}` : "disabled"}`, ` Management origin: ${hub.managementPublicOrigin ?? "unset — remote pairing and the remote dashboard need hub.managementPublicOrigin"}`, ...tokenLines, " Invite a machine: ocx hub invite", ]; } /** The not-connected placeholder. Arrays are empty because nothing was asked, not because nothing exists. */ export function disconnectedRemoteHubStatus(): CliRemoteHubStatus { return { connected: false, origin: null, stateSource: "unavailable", hubVersion: null, providers: [], oauth: [], subagentModels: [], truncated: false, claudeCodeEnabled: null, }; } /** * The data key this status snapshot may spend, and the cause when it may not. * * A reconnect or a rotation can replace both files between the snapshot and this read, so a * matching cache owner alone does not authorize sending the current token. Withholding is only * half the job: reporting every withheld case as "no usable data-plane token" is false for a * client that reconnected and holds a perfectly good token for a different hub, and a cause the * operator acts on has to be the real one (#4169 is the same defect in the stop path). */ function boundHubStateToken( current: ReturnType<typeof readClientConnectionState>, token: ReturnType<typeof readServiceApiTokenState>, owner: { serverUrl: string; apiKeyId: string; connectedAt: string }, ): { token: string | null; withheldReason?: string } { if (current.kind !== "connected") { return { token: null, withheldReason: "this client is no longer connected" }; } if (!sameClientConnectionOwner(current.value, owner)) { return { token: null, withheldReason: "the saved connection no longer matches the one this status reports" }; } if (token.kind !== "present") { return { token: null, withheldReason: "this client has no usable data-plane token" }; } if (token.fingerprint !== current.value.tokenFingerprint) { return { token: null, withheldReason: "the data-plane token no longer belongs to the saved connection" }; } return { token: token.token }; } /** * Ask the hub what it can serve, with a bounded read and a cache fallback. * * `ocx status` must answer while the hub is offline, so the fetch is bounded and a failure is * reported rather than thrown. It must also never answer from local provider/login state — see * `src/client/hub-state.ts` for why that substitution is the defect rather than a graceful * degradation. */ export async function collectRemoteHubStatus( connection: Pick<ClientConnectionStatus, "state" | "serverUrl" | "apiKeyId" | "connectedAt">, options: { fetchImpl?: typeof fetch; timeoutMs?: number; now?: number } = {}, ): Promise<CliRemoteHubStatus> { if (connection.state !== "connected" || !connection.serverUrl || !connection.apiKeyId || !connection.connectedAt) { return disconnectedRemoteHubStatus(); } const { resolveHubState } = await import("../client/hub-state"); const owner = { serverUrl: connection.serverUrl, apiKeyId: connection.apiKeyId, connectedAt: connection.connectedAt, }; const bound = boundHubStateToken(readClientConnectionState(), readServiceApiTokenState(), owner); const resolved = await resolveHubState({ owner, token: bound.token, ...(bound.withheldReason ? { withheldTokenReason: bound.withheldReason } : {}), ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}), ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }), ...(options.now === undefined ? {} : { now: options.now }), }); return { connected: true, // The hub's own advertised origin when it publishes one; otherwise the URL this client // dials, which is the origin the operator would recognize. origin: resolved.state?.origin ?? connection.serverUrl, stateSource: resolved.stateSource, ...(resolved.reason ? { reason: resolved.reason } : {}), ...(resolved.fetchedAt ? { fetchedAt: resolved.fetchedAt } : {}), ...(resolved.ageSeconds === undefined ? {} : { ageSeconds: resolved.ageSeconds }), hubVersion: resolved.state?.hubVersion ?? null, providers: resolved.state?.providers ?? [], oauth: resolved.state?.oauth ?? [], subagentModels: resolved.state?.subagentModels ?? [], truncated: resolved.state?.truncated === true, claudeCodeEnabled: resolved.state ? resolved.state.claudeCode.enabled : null, }; } /** * The one line that has to be read before anything else in the report. * * It goes FIRST, above the proxy line, because the failure mode is an agent or operator reading * the provider and login lines in isolation and concluding the hub cannot do something it can. * A buried `Remote hub: connected (<url>)` line — which is all this report had — does not stop * that, as #4236 demonstrated. */ export function remoteHubBannerLine(remoteHub: CliRemoteHubStatus): string | null { if (!remoteHub.connected) return null; const origin = remoteHub.origin ?? "the hub"; if (remoteHub.stateSource === "unavailable") { return `⚠️ Hub ${origin}: state unavailable (${remoteHub.reason ?? "unknown reason"}) — provider and login lines below are LOCAL and do not describe the hub.`; } const staleness = remoteHub.stateSource === "cache" ? ` — cached ${remoteHub.ageSeconds ?? "?"}s ago (${remoteHub.reason ?? "live read failed"})` : ""; return `🔗 State from hub ${origin}${staleness}: provider credentials, logins and delegable models below are the HUB's, not this machine's.`; } /** * The hub-sourced provider/login/model block, owned here so the sentences are testable without * spawning the CLI. Indentation is the caller's. Empty when nothing true is known. */ export function remoteHubStatusLines(remoteHub: CliRemoteHubStatus): string[] { if (!remoteHub.connected || remoteHub.stateSource === "unavailable") return []; const origin = remoteHub.origin ?? "hub"; const lines = [ `OAuth logins (hub ${origin}):`, ...(remoteHub.oauth.length === 0 ? [" (the hub reported no OAuth providers)"] : remoteHub.oauth.map(entry => ` ${entry.provider.padEnd(10)} ${entry.loggedIn ? "✓ logged in" : "✗ not logged in"}`)), `Providers (hub ${origin}):`, ...(remoteHub.providers.length === 0 ? [" (the hub reported no providers)"] : remoteHub.providers.map(provider => { // `authMode` is what keeps "no API key" from reading as "not configured": an `oauth` // provider legitimately has no key and is still fully usable. const credential = provider.hasCredential ? "credential stored" : `no API key (authMode ${provider.authMode ?? "key"})`; return ` ${provider.name.padEnd(10)} ${provider.adapter} — ${credential}${provider.disabled ? ", disabled" : ""}`; })), `Delegable models (hub ${origin}): ${remoteHub.subagentModels.length === 0 ? "none" : remoteHub.subagentModels.join(", ")}`, ]; if (remoteHub.hubVersion) lines.push(`Hub version: ${remoteHub.hubVersion}`); // The hub told us its own lists are a prefix. Saying nothing here would make this report claim // completeness it does not have — the same shape of confident-and-wrong answer as #4236. if (remoteHub.truncated) { lines.push(" (the hub truncated this state to fit its response caps; some rows are not listed)"); } return lines; } export function selectListenTarget( config: StatusListenConfig, pid: number | null, runtimePort: RuntimePortState | null, ): ListenTarget { const currentRuntimePort = pid && runtimePort?.pid === pid ? runtimePort : null; const port = currentRuntimePort ? currentRuntimePort.port : config.port ?? 10100; const hostname = currentRuntimePort?.hostname ?? config.hostname; return { port, hostname, source: currentRuntimePort ? "runtime" : "config", healthUrl: `http://${probeHostname(hostname)}:${port}/healthz`, dashboardUrl: statusDashboardUrl(config, hostname, port), }; } /** Prefer live result (including authoritative null pid) over the on-disk pid file. */ export function resolveStatusPid( live: { pid: number | null } | null, pidFile: number | null, ): number | null { return live ? live.pid : pidFile; } /** * `ocx status` greens on process liveness alone, so a proxy that answers * /healthz reads healthy even when Codex is not pointed at it and every routed * request goes to OpenAI instead (#2411). The proxy line is not wrong — the * listener really is up — so it keeps its check, and this supplies the signal * that was missing rather than corrupting the one that was already honest. * * Only `native` warns. `custom-local` and `unknown` are also "this proxy is * unused", but startupHealthSummary already renders both as AT RISK with a * remedy command, and `custom-remote` is a deliberate operator choice. Warning * on all four would teach operators to skip the line that matters. */ export function unusedProxyWarningLines(input: { proxyUp: boolean; routingKind: StartupHealth["routingKind"]; }): string[] { if (!input.proxyUp || input.routingKind !== "native") return []; return [ "⚠️ Codex routing is native — the running proxy is unused.", " Codex requests go to OpenAI, not this proxy. Re-point with: ocx start", ]; } /** * The mirror case: routing is ours and nothing is answering it. * * #5261: this state does not merely fail model calls. The root `openai_base_url` we inject * is the base URL of Codex's own built-in openai provider, so with the proxy down a user can * be stopped at Codex sign-in with no mention of opencodex anywhere on the screen. The * injection is on disk and survives reboot, so it does not clear itself. * * The rest of the not-running report offers only ways to bring the proxy BACK, which is the * wrong half of the choice for someone who wants their editor working again now. `ocx restore` * needs no proxy, no management API and no network, so name it here — this report is the * surface such a user is most likely to reach before the config file itself. * * Restricted to routing opencodex owns. `custom-local` is somebody else's gateway, and * `ocx restore` would not remove it. */ export function deadProxyRoutingAdviceLines(input: { proxyUp: boolean; routingKind: StartupHealth["routingKind"]; }): string[] { if (input.proxyUp || input.routingKind !== "opencodex-local") return []; return [ "Codex is still pointed at this proxy, so sign-in and model requests both fail while it is down.", "To hand Codex back to its own account and endpoints without starting anything: ocx restore", ]; } /** * Read the live Codex config and report an opencodex catalog pointer whose file is gone. * * Unreadable or absent config is reported as no finding rather than as a problem: this is a * diagnostic line, and inventing one from missing evidence is worse than staying quiet. */ export function detectMissingCodexCatalogPath(): string | null { try { if (!existsSync(CODEX_CONFIG_PATH)) return null; return missingOwnedCatalogPath(readFileSync(CODEX_CONFIG_PATH, "utf8")); } catch { return null; } } /** * Owned Codex routing that names a local port the live proxy does not serve. * * `classifyCodexRouting` calls that "opencodex-local" whatever the port, so without this line the * state behind a killed second instance was invisible here. Detection is `routing-drift.ts`, the * same rule the owner's healer uses; this only reports and reads the journal without side effects. * A sibling's report says nothing: its routing correctly names the owner it runs beside. Whether a * healer runs, or is gated or paused, is not visible from here, so the line promises only `ocx sync`. */ export function codexRoutingDriftWarning(input: { content: string | null; livePort: number | undefined; loopbackPort: number | null; /** `siblingOfPort` from this home's runtime record. */ siblingOfPort: number | undefined; journaled: () => JournaledCodexRouting; }): string | null { const { content, livePort, loopbackPort } = input; if (content === null || livePort === undefined || input.siblingOfPort !== undefined) return null; const drift = detectCodexRoutingDrift(content, { ownPorts: loopbackPort === null ? [livePort] : [livePort, loopbackPort], journaled: input.journaled, }); if (drift.kind !== "foreign") return null; const ports = [...new Set(drift.targets.map(target => target.port))].join(", "); return `Codex routing points at port ${ports}, but the proxy is on ${livePort}; if nothing serves that port, ` + "new Codex threads fail with \"Connection refused\". Run 'ocx sync' to re-point it now; a running " + "owner proxy may also do that on its own once the port stays dead."; } /** * The one state in this report where Codex is broken independently of the proxy (#5261). * * A `model_catalog_json` naming a file that is gone stops Codex loading its configuration at * all, so it presents as the same blank wall as dead routing while having a different cause and * a different fix. Both are named, because restarting the proxy rewrites the catalog and * restoring removes the pointer, and which one the user wants is their choice, not ours. */ export function missingCodexCatalogLines(missingCatalogPath: string | null): string[] { if (!missingCatalogPath) return []; return [ "⚠️ Codex is pointed at a model catalog that is no longer on disk, so Codex cannot load its config:", ` ${missingCatalogPath}`, " Regenerate it with 'ocx start', or remove opencodex from Codex with 'ocx restore'.", ]; } export async function collectStatus(): Promise<CliStatusView> { const configDiagnostics = readConfigDiagnostics(); const config = configDiagnostics.config; const claudeDesktop = { desiredEnabled: claudeDesktopIntegrationEnabled(config), policy: claudeDesktopPolicyHealth(probeClaudeDesktopPolicy()), }; const resolvedRuntime = (() => { try { return resolveCodexRuntime(); } catch (error) { const message = error instanceof Error ? error.message : String(error); const redacted = redactUserPath(redactSecretString(message)).slice(0, 160); return { runtime: { command: "codex", version: null, source: "fallback" as const }, failures: [{ command: "codex", source: "fallback" as const, reason: `resolve threw: ${redacted}`, }], replacedConfigured: undefined, newerAvailable: undefined, }; } })(); const clientConnection = collectClientConnectionStatus(Date.now(), undefined, { selectedCodexCommand: resolvedRuntime.runtime.command, }); // Asked before the local probes below so a connected client's report is hub-sourced from its // first line. Bounded and failure-tolerant: an offline hub degrades the remoteHub block, it // does not fail `ocx status`. const remoteHub = await collectRemoteHubStatus(clientConnection); // Prefer identity-verified liveness (runtime-port + /healthz) over ocx.pid alone (#618). // Pass the already-resolved diagnostics config so findLiveProxy does not re-load and // warn on malformed config.json (status --json must stay stderr-clean). const live = await findLiveProxy({ configFn: () => ({ port: config.port, hostname: config.hostname }), }); const pidFile = readPid(); // Preserve an authoritative null from orphan/legacy liveness — do not restore pidFile. const pid = resolveStatusPid(live, pidFile); // No extra request: findLiveProxy's identity probe already parsed and validated the // healthz body, so the version came back with the liveness result. const versionSkew = computeVersionSkew(packageVersion(), live?.version); const listen = live ? { port: live.port, hostname: live.hostname, source: live.source, healthUrl: `http://${probeHostname(live.hostname)}:${live.port}/healthz`, dashboardUrl: statusDashboardUrl(config, live.hostname, live.port), } : selectListenTarget(config, pidFile, pidFile ? readRuntimePort(pidFile) : null); // findLiveProxy already identity-probed /healthz; avoid a second fetch that can race. const health = live ? { ok: true, url: listen.healthUrl, message: `ok (pid ${live.pid ?? "unknown"})`, label: `${listen.healthUrl} ok (live)`, } : await checkProxyHealth(listen); // Same gatherer `ocx doctor` uses, so the two commands cannot reach different verdicts // about the same on-disk state (review found them diverging on fallback ports). const staleProcessState = await probeUncleanExitState({ live: Boolean(live), port: config.port, hostname: config.hostname, }); const bunRuntime = durableBunRuntime(); const liveStartup = live ? await fetchLiveStartupHealth(live) : null; const service = diagnoseService(); // A service can be registered and still not serve: the manager reports the job // either way. When the identity-probed live proxy provides an attested startup verdict, // prefer it over a shell-local service-manager probe that lacks the service environment. const serviceSummary = statusServiceSummary(liveStartup, service, Boolean(live)); const codexShim = diagnoseCodexShim(); const codexShimSummary = codexShim.summary; const startup = selectStatusStartupHealth(liveStartup, () => collectStartupHealth(config, { service, shim: codexShim, routingKind: getCodexRoutingKind(), })); const codexPlugins = diagnoseCodexBundledPlugins(); const lastClamp = loadLastEffortClamp(); const clampActive = effortClampAppliesToRuntime(lastClamp, resolvedRuntime.runtime); const codexHome = collectOrcaCodexHomeDiagnostic(); const warningParts: string[] = []; if ( resolvedRuntime.replacedConfigured && resolvedRuntime.replacedConfigured.from.command !== resolvedRuntime.runtime.command ) { warningParts.push( `Preferred Codex runtime is unavailable; using ${displayCodexRuntimePath(resolvedRuntime.runtime.command)} instead. Run ocx doctor for diagnosis and recovery.`, ); } else if ( resolvedRuntime.runtime.source === "fallback" && resolvedRuntime.failures.length > 0 && !resolvedRuntime.runtime.version ) { const detail = resolvedRuntime.failures[0]?.reason; warningParts.push( detail ? `No validated Codex runtime found (${detail}); falling back to \`codex\`. Run ocx doctor for diagnosis and recovery.` : "No validated Codex runtime found; falling back to `codex`. Run ocx doctor for diagnosis and recovery.", ); } if (resolvedRuntime.newerAvailable) { warningParts.push("OpenCodex is using an older Codex binary. Run ocx doctor for diagnosis and recovery."); } if (clampActive) { warningParts.push( `Catalog clamp removed: ${liveRemovedEfforts(lastClamp).join(", ")}. Run ocx doctor for diagnosis and recovery.`, ); } // A Grok fence naming a port we are not listening on is invisible everywhere else: // grok retries the refused connection on its own side, so no request — and therefore // no log line — ever reaches us. Surface it here, where the live port is already known. const grokDrift = (() => { try { // Locally reachable is a set: the public port plus the unauthenticated loopback // listener's port. A fence naming either is correct; only a third port is drift (#4236). return grokFenceEndpointDrift( readGrokStatus(), health.ok ? listen.port : undefined, health.ok ? effectiveLoopbackListenerPort(config, listen.port) : null, ); } catch { return null; // reading grok's config must never break `ocx status` } })(); if (grokDrift) { warningParts.push( `Grok Build config points at port ${grokDrift.fencePort}, but the proxy is on ` + `${grokDrift.livePort}; grok turns will retry against a closed port. Run 'ocx ensure' to repoint it.`, ); } const codexDrift = (() => { if (!health.ok) return null; try { const siblingOfPort = readRuntimePort()?.siblingOfPort; return codexRoutingDriftWarning({ content: siblingOfPort === undefined ? readFileSync(CODEX_CONFIG_PATH, "utf8") : null, livePort: listen.port, loopbackPort: effectiveLoopbackListenerPort(config, listen.port), siblingOfPort, journaled: () => ({ openaiBaseUrl: journaledInjectedOpenaiBaseUrl({ readOnly: true }), realtimeWsBaseUrl: journaledInjectedRealtimeWsBaseUrl({ readOnly: true }), }), }); } catch { return null; // an absent or unreadable config.toml must never break `ocx status` } })(); if (codexDrift) warningParts.push(codexDrift); const codexRuntime = { path: displayCodexRuntimePath(resolvedRuntime.runtime.command), version: resolvedRuntime.runtime.version, source: resolvedRuntime.runtime.source, newerAvailable: resolvedRuntime.newerAvailable ? { path: displayCodexRuntimePath(resolvedRuntime.newerAvailable.command), version: resolvedRuntime.newerAvailable.version, } : null, warning: warningParts.length > 0 ? warningParts.join(" ") : null, catalogClamp: { active: clampActive, // Report what is still clamped, not what the file happens to name: a leftover written // before the max/ultra exemption lists rungs nothing removes any more. removedEfforts: clampActive ? [...liveRemovedEfforts(lastClamp)] : [], runtimeVersion: clampActive ? (lastClamp?.runtimeVersion ?? null) : null, }, }; const proxyLabel = live ? `running (PID ${live.pid ?? pid ?? "unknown"})` : pid && health.ok ? `running (PID ${pid})` : pid ? `PID file points to PID ${pid}, but health check failed` : health.ok ? "reachable, but PID file is missing or stale" : "not running"; return { proxyLabel, healthLabel: health.label, json: { schemaVersion: 1, runtimeRole: config.runtimeRole ?? "standalone", proxy: { running: Boolean(live) || Boolean(pid && health.ok), pid: live?.pid ?? pid, staleProcessState, health: { ok: health.ok, url: health.url, message: health.message, }, }, dashboard: { url: listen.dashboardUrl }, listen: { port: listen.port, hostname: listen.hostname ?? null, source: listen.source, }, paths: { config: getConfigPath(), pid: getPidPath(), runtime: bunRuntime.path, }, runtime: { source: bunRuntime.source, ...(bunRuntime.source === "override" ? { overrideEnv: bunRuntime.overrideEnv } : {}), }, hub: collectHubStatus(config, listen), remoteHub, codexAutostart: codexAutoStartEnabled(config), startup, defaultProvider: typeof config.defaultProvider === "string" ? config.defaultProvider : null, config: { source: configDiagnostics.source, error: configDiagnostics.error, }, connection: { state: clientConnection.state, ...(clientConnection.reason ? { reason: clientConnection.reason } : {}), ...(clientConnection.serverUrl ? { serverUrl: clientConnection.serverUrl } : {}), ...(clientConnection.managementUrl ? { managementUrl: clientConnection.managementUrl } : {}), ...(clientConnection.protocolVersion ? { protocolVersion: clientConnection.protocolVersion } : {}), ...(clientConnection.apiKeyId ? { apiKeyId: clientConnection.apiKeyId } : {}), ...(clientConnection.selectedClients ? { selectedClients: [...clientConnection.selectedClients] } : {}), catalog: clientConnection.catalog, ...(clientConnection.catalogAgeSeconds !== undefined ? { catalogAgeSeconds: clientConnection.catalogAgeSeconds } : {}), credentialFile: clientConnection.token, ...(clientConnection.readiness ? { readiness: clientConnection.readiness } : {}), ...(clientConnection.readinessReason ? { readinessReason: clientConnection.readinessReason } : {}), }, service: { summary: serviceSummary }, codexShim: { summary: codexShimSummary }, codexPlugins, codexRuntime, codexHome, claudeDesktop, // Own field rather than a line in `codexRuntime.warning`: a stale ocx on PATH is a // fact about this install, not about the Codex runtime, and filing it there would // print it under the wrong heading (#2701). versionSkew, }, }; }