@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
text/typescript
/**
* 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);
}