UNPKG

@bitkyc08/opencodex

Version:

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

558 lines (533 loc) • 26.2 kB
import { existsSync, lstatSync, readFileSync } from "node:fs"; import { DEFAULT_CATALOG_PATH } from "../codex/paths"; import { codexSupportedReasoningEfforts } from "../codex/catalog/effort"; import { resolveCodexRuntime } from "../codex/runtime"; import { inspectClientCatalogReadiness, type CatalogCompatibilityDeps, type ClientCatalogFileState, type ClientCatalogReadiness, } from "../client/catalog-compatibility"; import { disconnectClient, revokeConnectedClientKey, rotateConnectedClientKey, connectClient, } from "../client/connect"; import { inspectClientRotationRecoveryGate, readClientConnectionState } from "../client/state"; import { readClientLinkState } from "../client/link-state"; import { teardownClientLink } from "../client/link-teardown"; import { reapOrphanTunnel } from "../client/link-tunnel"; import { readServiceApiTokenState } from "../lib/service-secrets"; import type { ClientLifecycleLockDeps } from "../client/lifecycle-lock"; import { linkKnownHostsPath } from "../link/paths"; import { createSshRunner, type SshRunner } from "../link/ssh-runner"; import type { OrphanTunnelResult } from "../client/link-tunnel"; import { inspectRemoteDesktopStore } from "../claude/desktop-remote-store"; import type { OcxConnectedClientId } from "../types"; import { CliUsageError, csv, printData, readSecretBytes, readSecretLine, rejectArgs, runCliAction, takeFlag, takeIntegerOption, takeOption, terminalSafeError, terminalSafeText, type RuntimeApiDeps, } from "./runtime-api"; export interface ClientCommandDeps extends RuntimeApiDeps { lifecycleLockDeps?: ClientLifecycleLockDeps; catalogProbeDeps?: ClientCatalogProbeDeps; linkTeardownDeps?: { runner?: Pick<SshRunner, "run">; reapOrphanTunnel?: () => Promise<OrphanTunnelResult>; knownHostsFile?: string; timeoutMs?: number; }; } export interface ClientCatalogProbeDeps extends CatalogCompatibilityDeps { /** Injected in tests; defaults to reading the materialized client catalog off disk. */ readCatalogBody?: () => string | null; /** * A Codex command the caller already resolved, handed over so readiness skips resolving it * again. General `ocx status` resolves the full runtime for its diagnostics block; the resolver * memo is keyed by discovery scope and holds one entry, so a priority-only readiness resolve * and the full one miss each other and re-probe the same command with `--version` — up to eight * seconds apiece. Passing the command across adds no cache state, and it cannot disagree with * what status prints because it is the selection status is printing. */ selectedCodexCommand?: string; } export const CONNECT_USAGE = `Usage: ocx connect --link --key-stdin --tunnel-port <port> --link-id <id> [--clients codex,claude] [--catalog-timeout <seconds>] [--no-sync] ocx connect <url> [--management-url <url>] (--pairing-code-stdin | --admin-token-stdin) [--clients codex,claude] [--management-transport direct|relay] [--catalog-timeout <seconds>] [--no-sync] ocx connect status [--json] ocx connect rotate (--pairing-code-stdin | --admin-token-stdin) [--json] ocx connect revoke --admin-token-stdin [--json]`; export const DISCONNECT_USAGE = `Usage: ocx disconnect [--keep-catalog] [--json]`; export type ClientConnectionStatus = { state: "disconnected" | "connected" | "invalid" | "mismatched"; reason?: string; serverUrl?: string; managementUrl?: string; managementTransport?: "direct" | "relay"; transport?: "hub" | "link"; link?: { tunnelPort: number; linkId: string }; protocolVersion?: number; apiKeyId?: string; selectedClients?: OcxConnectedClientId[]; connectedAt?: string; catalogSyncedAt?: string; catalogAgeSeconds?: number; catalog: "present" | "missing" | "unsafe"; token: "owned" | "missing" | "changed" | "unsafe"; rotation: "clean" | "orphan-cleaned" | "recovery-required" | "unsafe"; /** * Whether the selected local Codex CLI can actually launch against this connection (#4207). * * `state: "connected"` proves the hub answered and the credential works. It never proved the * local runtime could consume what was downloaded, which is how a connection kept reporting * itself healthy while `codex exec` exited on `unknown variant` before its first request. * * Reported only while connected, and reported as its own field rather than as a fourth * `catalog` value: the status JSON is documented additive-only, so widening an existing * field's value domain would change what `catalog: "present"` means for every consumer that * already reads it. */ readiness?: ClientCatalogReadiness["kind"]; /** Present whenever readiness is not `ready`; names the fault and the way out. */ readinessReason?: string; }; function readInstalledCatalogBody(): string | null { try { return readFileSync(DEFAULT_CATALOG_PATH, "utf8"); } catch { return null; } } /** * The ladder the selected Codex CLI accepts, observed without persisting anything. * * `codexSupportedReasoningEfforts()` with no deps reaches `resolveAndPersistCodexRuntime`, which * writes codex-runtime.json. `ocx status` deliberately resolves without persisting, and a * read-only diagnostics command should not start writing runtime selection state because a * readiness check was added to it. Stop at the first valid runtime, then hand only that command * to the catalog probe: readiness does not consume alternative-runtime diagnostics. The resolver * keeps this priority-only cache separate from the full discovery used by `ocx status`. * * A caller that has already resolved passes its selection in through `selectedCodexCommand` rather * than paying for a second `--version` probe of the command it just resolved. */ function observeLocalCodexEffortLadder(selected?: string): ReadonlySet<string> | null { const command = selected ?? resolveCodexRuntime({ discoverAlternatives: false }).runtime.command; return codexSupportedReasoningEfforts({ commandCandidates: () => [command] }); } /** * One observer per command, for the write-time gate and the readiness check alike. Built even * when nothing was injected, so production does not silently fall back to the default inside * {@link assertClientCatalogCompatible} — that default persists runtime selection state and * would run its own probe, which is how the two checks could disagree about the ladder within * a single `ocx connect`. */ function catalogObserver(deps: ClientCatalogProbeDeps | undefined): CatalogCompatibilityDeps { const selected = deps?.selectedCodexCommand; return { supportedEfforts: deps?.supportedEfforts ?? (() => observeLocalCodexEffortLadder(selected)) }; } /** The stat half of the catalog verdict, shared by the status collector and `ocx connect`. */ function installedCatalogFileState(): ClientCatalogFileState { if (!existsSync(DEFAULT_CATALOG_PATH)) return "missing"; try { const stat = lstatSync(DEFAULT_CATALOG_PATH); return !stat.isSymbolicLink() && stat.isFile() ? "present" : "unsafe"; } catch { return "unsafe"; } } /** * Observing the runtime spawns `codex debug models`, so this runs only for a connected client — * the one configuration that installs hub bytes the local clamp never touched. A standalone or * hub install pays nothing for it. * * Never throws. A status command that dies because a Codex probe failed would replace one wrong * answer with a worse one. */ function inspectInstalledCatalogReadiness( file: ClientCatalogFileState, deps: ClientCatalogProbeDeps, ): ClientCatalogReadiness { try { const read = deps.readCatalogBody ?? readInstalledCatalogBody; return inspectClientCatalogReadiness(file, file === "present" ? read() : null, catalogObserver(deps)); } catch { return { kind: "unverified", reason: "the selected local Codex runtime could not be inspected" }; } } export function collectClientConnectionStatus( now = Date.now(), lifecycleLockDeps?: ClientLifecycleLockDeps, catalogProbeDeps: ClientCatalogProbeDeps = {}, ): ClientConnectionStatus { const state = readClientConnectionState(); const tokenState = readServiceApiTokenState(); const rotation = inspectClientRotationRecoveryGate(state, lifecycleLockDeps).kind; const catalog = installedCatalogFileState(); if (state.kind !== "connected") { return { state: state.kind, ...(state.kind === "invalid" || state.kind === "mismatched" ? { reason: state.reason } : {}), catalog, token: tokenState.kind === "absent" ? "missing" : tokenState.kind === "unsafe" ? "unsafe" : "changed", rotation, }; } const catalogAgeSeconds = state.value.catalogSyncedAt ? Math.max(0, Math.floor((now - Date.parse(state.value.catalogSyncedAt)) / 1000)) : undefined; const token = tokenState.kind === "absent" ? "missing" : tokenState.kind === "unsafe" ? "unsafe" : tokenState.fingerprint === state.value.tokenFingerprint ? "owned" : "changed"; const readiness = inspectInstalledCatalogReadiness(catalog, catalogProbeDeps); return { state: "connected", serverUrl: state.value.serverUrl, managementUrl: state.value.managementUrl, managementTransport: state.value.managementTransport, ...(state.value.transport ? { transport: state.value.transport } : {}), ...(state.value.link ? { link: { ...state.value.link } } : {}), protocolVersion: state.value.protocolVersion, apiKeyId: state.value.apiKeyId, selectedClients: [...state.value.selectedClients], connectedAt: state.value.connectedAt, ...(state.value.catalogSyncedAt ? { catalogSyncedAt: state.value.catalogSyncedAt } : {}), ...(catalogAgeSeconds !== undefined ? { catalogAgeSeconds } : {}), catalog, token, rotation, readiness: readiness.kind, ...(readiness.kind === "ready" ? {} : { readinessReason: readiness.reason }), }; } function parseClients(raw: string | undefined): OcxConnectedClientId[] { const values = csv(raw) ?? ["codex", "claude"]; if (values.length < 1 || values.some(value => value !== "codex" && value !== "claude")) { throw new CliUsageError("--clients must contain codex and/or claude", CONNECT_USAGE); } return values as OcxConnectedClientId[]; } async function readLinkCredential(deps: ClientCommandDeps): Promise<{ apiKeyId: string; key: string }> { const raw = await readSecretBytes(deps, "link credential"); try { const text = new TextDecoder("utf-8", { fatal: true }).decode(raw).trim(); const parsed: unknown = JSON.parse(text); if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("shape"); const record = parsed as Record<string, unknown>; if (Object.keys(record).some(key => key !== "apiKeyId" && key !== "key") || typeof record.apiKeyId !== "string" || !record.apiKeyId.trim() || record.apiKeyId.length > 256 || typeof record.key !== "string" || !/^ocx_data_[0-9a-f]{40}$/.test(record.key)) { throw new Error("shape"); } return { apiKeyId: record.apiKeyId, key: record.key }; } catch { throw new CliUsageError("invalid link credential", CONNECT_USAGE); } finally { raw.fill(0); } } /** Reads as a verdict, not a field dump: "ready" is the only word that means the client works. */ function readinessLine(status: ClientConnectionStatus): string { const label = status.readiness === "ready" ? "ready" : status.readiness === "incompatible" ? "not ready" : "unverified"; return `Local Codex CLI: ${label}${status.readinessReason ? ` (${terminalSafeText(status.readinessReason)})` : ""}`; } export type ConnectCompletionReport = { readonly lines: readonly string[]; /** Non-null when `ocx connect` must exit non-zero rather than report success. */ readonly failure: string | null; }; /** * What `ocx connect` says once the hub and the credential are settled, and whether the command * still fails (#4207). * * Pure so the fail-closed decision can be exercised without a hub. Two rules it encodes: * * On a proven incompatibility the verdict is printed FIRST and the `Connected to …` line is * withheld, because a caller grepping for that phrase would otherwise read a catalog the local * CLI cannot parse as a success. The connection really was saved, so the replacement line says * where to see it. * * And that failure applies only when this connection selected Codex. A Claude-only connection * never launches the Codex CLI, so an old binary somewhere on PATH is not a reason to fail the * operator's Claude Desktop setup — it is still worth saying, which is why the line survives * without the exit code. */ export function connectCompletionReport( connection: { serverUrl: string; apiKeyId: string }, selectedClients: readonly OcxConnectedClientId[], readiness: ClientCatalogReadiness, ): ConnectCompletionReport { const connected = `Connected to ${connection.serverUrl} as key ${connection.apiKeyId}.`; if (readiness.kind === "ready") { return { lines: [connected, "Local Codex CLI: ready (it accepts every reasoning level in the installed catalog)."], failure: null }; } if (readiness.kind === "unverified") { // Not a failure. A client with no observable Codex CLI is a working configuration, and the // write-time gate deliberately lets it through; saying so is the honest middle report. return { lines: [connected, `Local Codex CLI: unverified (${terminalSafeText(readiness.reason)}).`], failure: null }; } const safeReason = terminalSafeText(readiness.reason); const verdict = `Local Codex CLI: not ready (${safeReason})`; if (!selectedClients.includes("codex")) { return { lines: [connected, `${verdict} This connection selected ${selectedClients.join(", ")}, so nothing here launches Codex.`], failure: null, }; } return { lines: [verdict, `The connection to ${connection.serverUrl} as key ${connection.apiKeyId} was saved; run 'ocx connect status' to see it.`], failure: `client_not_ready: ${safeReason}`, }; } function statusLines(status: ClientConnectionStatus): string[] { if (status.state !== "connected") { return [`Connection: ${status.state}${status.reason ? ` (${status.reason})` : ""}`]; } return [ "Connection: connected", // Second line on purpose. The whole of #4207 is that a reader stopped at "connected" and // believed the client was usable, so the local verdict has to arrive before the hub detail. readinessLine(status), `Transport: ${status.transport ?? "hub"}`, ...(status.link ? [`Link: ${status.link.linkId} via tunnel port ${status.link.tunnelPort}`] : []), `Hub: ${status.serverUrl}`, `Management: ${status.managementUrl} (${status.managementTransport})`, `Protocol: ${status.protocolVersion}`, `API key id: ${status.apiKeyId}`, `Clients: ${status.selectedClients?.join(", ")}`, `Token file: ${status.token}`, `Key rotation: ${status.rotation}`, `Catalog: ${status.catalog}${status.catalogAgeSeconds !== undefined ? ` (${status.catalogAgeSeconds}s old)` : ""}`, ]; } async function runRotate(argv: string[], deps: ClientCommandDeps): Promise<void> { const args = [...argv]; const wantsJson = takeFlag(args, "--json"); const pairing = takeFlag(args, "--pairing-code-stdin"); const admin = takeFlag(args, "--admin-token-stdin"); if (Number(pairing) + Number(admin) !== 1) { throw new CliUsageError("choose exactly one of --pairing-code-stdin or --admin-token-stdin", CONNECT_USAGE); } rejectArgs(args, CONNECT_USAGE, { redactValues: true }); const value = new TextEncoder().encode(await readSecretLine(deps, pairing ? "pairing code" : "admin token")); const connection = await rotateConnectedClientKey({ credential: { kind: pairing ? "pairing-grant" : "admin", value }, }, { fetchImpl: deps.fetchImpl, lifecycleLockDeps: deps.lifecycleLockDeps }); const restartRequired = inspectRemoteDesktopStore({ serverUrl: connection.serverUrl, apiKeyId: connection.apiKeyId, connectedAt: connection.connectedAt }).kind !== "absent"; printData({ apiKeyId: connection.apiKeyId, rotation: connection.rotationOutcome, restartRequired }, wantsJson, [ connection.rotationOutcome === "committed" ? `Rotated connected API key ${connection.apiKeyId}; the previous key is no longer admitted.` : `Rotation rolled back for API key ${connection.apiKeyId}; the previous key was retained or restored.`, ...(restartRequired ? ["Fully quit and reopen Claude Desktop; a running app may still hold the previous credential."] : []), ]); } async function runHubConnect(argv: string[], deps: ClientCommandDeps): Promise<void> { const args = [...argv]; const serverUrl = args.shift(); if (!serverUrl || serverUrl.startsWith("--")) throw new CliUsageError("hub URL is required", CONNECT_USAGE); const managementUrl = takeOption(args, "--management-url"); const clients = parseClients(takeOption(args, "--clients")); const catalogTimeoutSeconds = takeIntegerOption(args, "--catalog-timeout", { min: 1 }); if (catalogTimeoutSeconds !== undefined && catalogTimeoutSeconds > 120) { throw new CliUsageError("--catalog-timeout must be an integer between 1 and 120", CONNECT_USAGE); } const managementTransport = takeOption(args, "--management-transport") ?? "direct"; if (managementTransport !== "direct" && managementTransport !== "relay") { throw new CliUsageError("--management-transport must be direct or relay", CONNECT_USAGE); } const pairing = takeFlag(args, "--pairing-code-stdin"); const admin = takeFlag(args, "--admin-token-stdin"); const noSync = takeFlag(args, "--no-sync"); if (Number(pairing) + Number(admin) !== 1) { throw new CliUsageError("choose exactly one of --pairing-code-stdin or --admin-token-stdin", CONNECT_USAGE); } rejectArgs(args, CONNECT_USAGE, { redactValues: true }); const secret = await readSecretLine(deps, pairing ? "pairing code" : "admin token"); const value = new TextEncoder().encode(secret); const connection = await connectClient({ serverUrl, ...(managementUrl ? { managementUrl } : {}), credential: { kind: pairing ? "pairing-grant" : "admin", value }, selectedClients: clients, managementTransport, noSync, ...(catalogTimeoutSeconds === undefined ? {} : { catalogTimeoutMs: catalogTimeoutSeconds * 1_000 }), }, { fetchImpl: deps.fetchImpl, lifecycleLockDeps: deps.lifecycleLockDeps, // Same observer the readiness check below uses. Passed unconditionally: leaving it out in // production would let the gate fall back to its own probing, persisting default, so one // command could run two probes and act on two different ladders. catalogCompatibility: catalogObserver(deps.catalogProbeDeps), }).catch((error: unknown) => { // Compatibility refusals happen before the completion report and reach stderr. // Keep the domain error untouched; render its message only at the CLI boundary. throw terminalSafeError(error); }); // The hub and the credential are proven at this point; the local runtime is not. Reporting // only the first half is what #4207 was filed for, so the catalog now on disk is checked // against the Codex CLI that will read it. const readiness = inspectInstalledCatalogReadiness(installedCatalogFileState(), deps.catalogProbeDeps ?? {}); const report = connectCompletionReport(connection, clients, readiness); for (const line of report.lines) console.log(line); if (report.failure) throw new Error(report.failure); } async function runLinkConnect(argv: string[], deps: ClientCommandDeps): Promise<void> { const args = [...argv]; const keyStdin = takeFlag(args, "--key-stdin"); const rawPort = takeIntegerOption(args, "--tunnel-port", { min: 1024 }); const linkId = takeOption(args, "--link-id"); const managementUrl = takeOption(args, "--management-url"); const managementTransport = takeOption(args, "--management-transport"); const pairing = takeFlag(args, "--pairing-code-stdin"); const admin = takeFlag(args, "--admin-token-stdin"); const clients = parseClients(takeOption(args, "--clients")); const catalogTimeoutSeconds = takeIntegerOption(args, "--catalog-timeout", { min: 1 }); if (catalogTimeoutSeconds !== undefined && catalogTimeoutSeconds > 120) { throw new CliUsageError("--catalog-timeout must be an integer between 1 and 120", CONNECT_USAGE); } const noSync = takeFlag(args, "--no-sync"); if (!keyStdin || rawPort === undefined || !linkId) { throw new CliUsageError("link connect requires --key-stdin, --tunnel-port, and --link-id", CONNECT_USAGE); } if (managementUrl || managementTransport !== undefined || pairing || admin || args.some(value => !value.startsWith("--"))) { throw new CliUsageError("link connect accepts no hub URL, management URL, management transport, pairing code, or admin token", CONNECT_USAGE); } if (rawPort > 65535 || !/^lnk_[0-9a-f]{16}$/.test(linkId)) { throw new CliUsageError("invalid link transport", CONNECT_USAGE); } rejectArgs(args, CONNECT_USAGE, { redactValues: true }); const credential = await readLinkCredential(deps); const connection = await connectClient({ serverUrl: `http://127.0.0.1:${rawPort}`, managementUrl: `http://127.0.0.1:${rawPort}`, credential: { kind: "link", ...credential }, selectedClients: clients, managementTransport: "direct", transport: "link", link: { tunnelPort: rawPort, linkId }, noSync, ...(catalogTimeoutSeconds === undefined ? {} : { catalogTimeoutMs: catalogTimeoutSeconds * 1_000 }), }, { fetchImpl: deps.fetchImpl, lifecycleLockDeps: deps.lifecycleLockDeps, catalogCompatibility: catalogObserver(deps.catalogProbeDeps), }).catch((error: unknown) => { throw terminalSafeError(error); }); const readiness = inspectInstalledCatalogReadiness(installedCatalogFileState(), deps.catalogProbeDeps ?? {}); const report = connectCompletionReport(connection, clients, readiness); for (const line of report.lines) console.log(line); if (report.failure) throw new Error(report.failure); } async function runConnect(argv: string[], deps: ClientCommandDeps): Promise<void> { const args = [...argv]; if (takeFlag(args, "--link")) { await runLinkConnect(args, deps); return; } await runHubConnect(argv, deps); } async function runRevoke(argv: string[], deps: ClientCommandDeps): Promise<void> { const args = [...argv]; const wantsJson = takeFlag(args, "--json"); const admin = takeFlag(args, "--admin-token-stdin"); if (!admin) throw new CliUsageError("revoke requires --admin-token-stdin", CONNECT_USAGE); rejectArgs(args, CONNECT_USAGE, { redactValues: true }); const value = new TextEncoder().encode(await readSecretLine(deps, "admin token")); const result = await revokeConnectedClientKey({ kind: "admin", value }, { fetchImpl: deps.fetchImpl, lifecycleLockDeps: deps.lifecycleLockDeps }); printData(result, wantsJson, [`Revoked connected API key ${result.apiKeyId}. Disconnect this client next.`]); } export async function handleConnectCommand(argv: string[], deps: ClientCommandDeps = {}): Promise<number> { return runCliAction(async () => { if (argv[0] === "status") { const args = argv.slice(1); const wantsJson = takeFlag(args, "--json"); rejectArgs(args, CONNECT_USAGE, { redactValues: true }); const status = collectClientConnectionStatus(Date.now(), deps.lifecycleLockDeps, deps.catalogProbeDeps ?? {}); printData(status, wantsJson, statusLines(status)); return; } if (argv[0] === "revoke") { await runRevoke(argv.slice(1), deps); return; } if (argv[0] === "rotate") { await runRotate(argv.slice(1), deps); return; } await runConnect(argv, deps); }); } export async function handleDisconnectCommand( argv: string[], deps: Pick<ClientCommandDeps, "lifecycleLockDeps" | "linkTeardownDeps"> = {}, ): Promise<number> { return runCliAction(async () => { const args = [...argv]; const keepCatalog = takeFlag(args, "--keep-catalog"); const wantsJson = takeFlag(args, "--json"); rejectArgs(args, DISCONNECT_USAGE, { redactValues: true }); const teardown = await teardownClientLink({ readSidecar: readClientLinkState, connectedLinkId: () => { const state = readClientConnectionState(); return state.kind === "connected" && state.value.transport === "link" ? state.value.link?.linkId ?? null : null; }, reapOrphanTunnel: deps.linkTeardownDeps?.reapOrphanTunnel ?? (() => reapOrphanTunnel()), runner: deps.linkTeardownDeps?.runner ?? createSshRunner(), knownHostsFile: deps.linkTeardownDeps?.knownHostsFile ?? linkKnownHostsPath(), timeoutMs: deps.linkTeardownDeps?.timeoutMs, }); const result = await disconnectClient({ keepCatalog }, deps); const payload = { ...result, homeRevoke: teardown.homeRevoke, tunnel: teardown.tunnel, revoke: { apiKeyId: result.apiKeyId, location: "Integrations → API Keys", }, }; printData(payload, wantsJson, [ "Disconnected locally; native Codex state was restored.", ...(result.desktopRestoration === "standard_fallback" ? ["Previous Desktop settings were not recorded; the managed profile was switched to standard mode."] : []), ...(result.restartRequired ? ["Fully quit and reopen Claude Desktop; local cleanup cannot revoke an in-memory credential."] : []), ...(teardown.homeRevoke === "failed" && teardown.linkId ? [`Home revoke failed; run ocx link revoke --link-id ${teardown.linkId} on the home.`] : []), ...(teardown.tunnel?.tunnel === "unresolved" ? [`A link tunnel (pid ${teardown.tunnel.pid}) may still be running; stop it if it is.`] : []), teardown.homeRevoke === "revoked" ? `The home revoked link ${teardown.linkId} and its key ${result.apiKeyId}.` : `The hub key ${result.apiKeyId} is still valid. Revoke it from Integrations → API Keys.`, ]); }); }