UNPKG

@bitkyc08/opencodex

Version:

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

312 lines (287 loc) • 14.1 kB
/** * Durable desired state for the native Codex integration. * * The switch itself was never the hard part — `ocx restore` already returns Codex * to its native path without stopping the proxy. What was missing is that the * decision did not survive: `ocx start` force-synced unconditionally, so an OFF * lasted exactly until the next start. That is the defect this module closes, and * it is the same one Grok's shipped toggle still has. * * ABSENT MEANS ON. A user who never touched a switch, a config written by an * older binary, and an explicit `true` are the same state, and none of them may * be read as "the user turned this off". Only an explicit `false` is OFF. * * This module does NOT own linearization. The plan that predates * `src/codex/user-identity.ts` proposed a second per-home lock at * `tmpdir()/opencodex-native-locks/sha256(home).sqlite`; that keys on the home * alone, carries no proof of effective user, and would collide or split * depending on the temp root. Convergence takes the write lock; this module only * records intent through the config coordinator. * * Design record: devlog/_fin/260803_codex_desktop_toggle/030_desired_state.md. */ import { deleteConfigTopLevelKey, loadConfig, mutatePersistedConfig } from "../config"; import type { OcxClientIntegrationsConfig, OcxConfig } from "../types"; import { runStartupReadinessSync, type ReadinessGate, type SyncOutcomeLike } from "../server/readiness"; import { siblingOfLivePort, siblingSkipMessage } from "./sibling-start"; /** Clients whose durable intent this module owns. */ export type DurableIntentClientId = keyof OcxClientIntegrationsConfig; /** Injectable for tests; production passes the real sync. */ /** * The startup sync result the caller needs to decide whether anything was * actually written (#1046). It used to be `unknown`, so "a write happened" was * not observable at the startup boundary and no post-write action could be * gated on it. */ export interface CodexStartupSyncOutcome { catalogWritten: boolean; cacheSynced: boolean; /** Readiness-observable fields carried by the raw startup sync. */ ok?: boolean; warning?: string; } export type CodexStartupSync = (port: number) => Promise<SyncOutcomeLike | undefined>; export type CodexDesiredStateResult = | { readonly ok: true; readonly status: "committed" | "unchanged"; readonly enabled: boolean } | { readonly ok: false; readonly reason: "missing" | "invalid" | "conflict"; readonly retryable: boolean; readonly message: string; }; /** * Is native Codex integration wanted? * * Takes the config rather than reading it, so a caller that already holds an * admitted snapshot cannot accidentally answer from a fresher one — the whole * point of admission is that one decision uses one set of bytes. */ export function integrationEnabled( config: Pick<OcxConfig, "clientIntegrations">, client: DurableIntentClientId, ): boolean { return config.clientIntegrations?.[client] !== false; } export function codexIntegrationEnabled(config: Pick<OcxConfig, "clientIntegrations">): boolean { return integrationEnabled(config, "codex"); } /** Whether a Codex sync is permitted for this admitted config snapshot. */ type LocalClientSyncConfig = Pick< OcxConfig, "clientIntegrations" | "runtimeRole" | "unauthenticatedLoopbackListener" >; export function localClientSyncAllowed(config: LocalClientSyncConfig): boolean { // A sibling instance never writes the live owner's client routing (`sibling-start.ts`). if (siblingOfLivePort() !== null) return false; return config.runtimeRole !== "hub" || config.unauthenticatedLoopbackListener?.enabled === true; } /** * The one sentence every hub-gated skip says (#4236). * * The gate is a reasonable decision; reporting it as "Codex integration is OFF" was not. An * operator whose `clientIntegrations` says nothing — or says `true` — was told their own switch * was off, and `ocx restore back` went further and blamed a competing writer that did not * exist. Name the gate and name the key that opens it. */ export const HUB_GATED_SKIP_MESSAGE = "This machine is a hub; it does not rewrite its own Codex/Grok/Claude configs unless " + "unauthenticatedLoopbackListener is enabled."; /** * Why a local-client write was skipped. The gate outranks the toggle: it is the surprising one. * `sibling` outranks both: this process is a second instance beside a live owner. */ export type LocalClientSkipReason = "desired_disabled" | "hub-gated" | "sibling"; /** * "hub-gated" is claimed only when the toggle is ON and the gate is what stopped the write. * With the toggle OFF the gate is moot: telling that operator to enable the loopback listener * would send them to a key that cannot make the sync happen — the mirror image of the defect * this reason exists to fix. */ export function localClientSkipReason( config: LocalClientSyncConfig, client: DurableIntentClientId = "codex", ): LocalClientSkipReason { if (siblingOfLivePort() !== null) return "sibling"; return integrationEnabled(config, client) && !localClientSyncAllowed(config) ? "hub-gated" : "desired_disabled"; } /** * Pick the skip message for a snapshot: today's toggle text, or the hub-gate sentence. * * `hubSuffix` states what the hub-gated path still did (a catalog refresh, say) so the * composed line stays as informative as the toggle one it replaces. */ export function localClientSkipMessage( config: LocalClientSyncConfig, integrationOffMessage: string, hubSuffix?: string, client: DurableIntentClientId = "codex", ): string { const reason = localClientSkipReason(config, client); if (reason === "sibling") return siblingSkipMessage(); if (reason !== "hub-gated") return integrationOffMessage; return hubSuffix ? `${HUB_GATED_SKIP_MESSAGE} ${hubSuffix}` : HUB_GATED_SKIP_MESSAGE; } export function shouldSyncCodexOnStart(config: LocalClientSyncConfig): boolean { // A hub is a server for OTHER machines: it must not rewrite its own host's // Codex/Claude/Grok client configs on startup (interview decision Q6, and the // first clisu-oracle dogfood boot proved the failure mode — the hub marked // /readyz failed because it tried to run the full local client sync). // A hub can be a local client only through its explicitly enabled loopback // listener. The public hub bind remains outside this gate and still requires // admission; an explicit client OFF continues to win. A sibling instance is closed by the // same gate: the live owner keeps the routing it maintains. return localClientSyncAllowed(config) && codexIntegrationEnabled(config); } /** * Grok's toggle SHIPPED without this, which is the bug: it strips the fence in * `~/.grok/config.toml` and records nothing, so the next `ocx start` calls * `syncGrokConfig` unconditionally and writes the fence straight back. */ export function grokIntegrationEnabled(config: Pick<OcxConfig, "clientIntegrations">): boolean { return integrationEnabled(config, "grok"); } /** The same question when no snapshot is in hand. Reads the persisted config. */ export function codexIntegrationEnabledNow(): boolean { return codexIntegrationEnabled(loadConfig()); } /** * Persist the desired state, touching only that one field. * * Field-scoped on purpose: the callback runs on a freshly rebased snapshot inside * the config coordinator, so a concurrent provider or model edit is preserved * instead of being clobbered by a whole-config write built from a stale read. */ export function setIntegrationEnabled( client: DurableIntentClientId, enabled: boolean, ): CodexDesiredStateResult { const outcome = mutatePersistedConfig(config => { const current = integrationEnabled(config, client); if (current === enabled) return { changed: false, value: enabled }; const integrations = { ...(config.clientIntegrations ?? {}) }; if (enabled) { // ON is the absence, not a stored `true`: writing `true` would make an // untouched config and a re-enabled one differ in bytes for no reason, and // every later reader has to treat them identically anyway. delete integrations[client]; } else { integrations[client] = false; } // Drop the key entirely once nothing is left in it, so enabling twice does // not leave `"clientIntegrations": {}` behind in the user's file. if (Object.keys(integrations).length === 0) deleteConfigTopLevelKey(config, "clientIntegrations"); else config.clientIntegrations = integrations; return { changed: true, value: enabled }; }); if (outcome.status !== "unavailable") { return { ok: true, status: outcome.status, enabled }; } // `conflict` is the only retryable one: it means a competing writer won the // rebase, so the same call can succeed. A missing or malformed config will fail // identically forever, and telling a caller to retry that is how a UI ends up // spinning on a problem only the user can fix. const retryable = outcome.reason === "conflict"; return { ok: false, reason: outcome.reason, retryable, message: outcome.reason === "conflict" ? "Another process changed the config while this switch was being written." : outcome.reason === "missing" ? "No config file exists to record the switch in." : "The config file is malformed; refusing to overwrite it.", }; } export function setCodexIntegrationEnabled(enabled: boolean): CodexDesiredStateResult { return setIntegrationEnabled("codex", enabled); } export function setGrokIntegrationEnabled(enabled: boolean): CodexDesiredStateResult { return setIntegrationEnabled("grok", enabled); } /** Whether Claude Desktop's managed gateway profile is wanted. */ export function claudeDesktopIntegrationEnabled(config: Pick<OcxConfig, "clientIntegrations">): boolean { return integrationEnabled(config, "claude-desktop"); } /** The same question when no admitted config snapshot is in hand. */ export function claudeDesktopIntegrationEnabledNow(): boolean { return claudeDesktopIntegrationEnabled(loadConfig()); } export function setClaudeDesktopIntegrationEnabled(enabled: boolean): CodexDesiredStateResult { return setIntegrationEnabled("claude-desktop", enabled); } /** * The startup gate, as a function rather than an `if` buried in `handleStart`. * * `ocx start` used to call `syncModelsToCodex(port).catch(() => {})` * unconditionally, which is exactly why turning Codex off lasted until the next * start: the restore worked, and then start put the routing straight back. It * lived inline in a 600-line startup function that opens sockets and installs * services, so nothing could test it — and an untestable gate is how the * unconditional version survived this long. * * The `.catch` is deliberate and stays: a provider fetch failing at startup must * not stop the proxy from coming up. Swallowing a failure to APPLY is tolerable. * Swallowing the user's decision was not. * * Returns whether the sync ran, so a caller — or a test — can tell "skipped * because the user turned it off" from "ran and quietly failed", plus what it * wrote when it did run (#1046 — the caller warns about stale app-servers only * after a real write). */ export async function syncCodexOnStartIfEnabled( port: number, config: LocalClientSyncConfig, sync: CodexStartupSync = defaultStartupSync, readinessGate?: ReadinessGate, ): Promise<{ ran: boolean; catalogWritten: boolean; cacheSynced: boolean; published?: boolean }> { if (!shouldSyncCodexOnStart(config)) { // The user explicitly turned Codex off: there is nothing to sync, so the // proxy is ready as soon as it is up. The gate is driven here so /readyz // does not stay pending forever for a deployment that deliberately disabled // the native Codex integration. readinessGate?.markReady(); return { ran: false, catalogWritten: false, cacheSynced: false }; } // The `.catch` is deliberate and stays: a failure to APPLY must not stop the // proxy from coming up. A failed sync simply reports no writes. The readiness // gate observes the real outcome so /readyz reflects the sync state exactly as // the contract defines: ready on ok=true once the sync has settled. A nonempty // `warning` is a local-Codex-artifact degradation the sync chose to continue // past, and #5181 is what it cost to treat it as terminal — a healthy // multi-provider proxy reported itself permanently unready. const outcome = readinessGate ? await runStartupReadinessSync(readinessGate, async () => (await sync(port)) ?? null) : await sync(port).catch(() => undefined); // #7423: "published" means this proxy now owns what Codex reads: the sync succeeded and // wrote config and catalog (or the catalog, when an external provider owns config.toml). // A skipped sync (sibling, hub gate, desired OFF) published nothing of its own. const status = (outcome as { status?: unknown } | null | undefined)?.status; return { ran: true, catalogWritten: outcome?.catalogWritten === true, cacheSynced: outcome?.cacheSynced === true, published: outcome?.ok === true && (status === "applied" || status === "catalog-only"), }; } async function defaultStartupSync(port: number): Promise<CodexStartupSyncOutcome> { const { syncModelsToCodex } = await import("./sync"); return syncModelsToCodex(port); } /** * The Grok startup gate. * * Grok's toggle shipped and then `ocx start` called `syncGrokConfig` * unconditionally, so switching Grok off lasted exactly one restart — the fence * came out of `~/.grok/config.toml` and the next start wrote it straight back. * Same defect as Codex had, in a different file. * * The caller keeps its own try/catch, because a Grok failure must never block * startup and its diagnostic is worth printing. This only answers whether to * attempt the sync at all. */ export function shouldSyncGrokOnStart(config: LocalClientSyncConfig): boolean { return localClientSyncAllowed(config) && grokIntegrationEnabled(config); }