@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
307 lines (296 loc) • 14.8 kB
text/typescript
import { readConfigAdmissionSnapshot } from "../config/diagnostics";
import { readRuntimePort } from "../config/process-state";
import { readClientConnectionState } from "../client/state";
import { getActiveTurnCount, isDraining, isRecyclingForExit, isShutdownDraining } from "../server/lifecycle";
import type { OcxConfig } from "../types";
import { compareCatalogHealPaths, observeCatalogHealFile, retainCatalogHealPath, selectCatalogHealPath, type CatalogObservation } from "./catalog/heal-observation";
import { subscribeCatalogPublication } from "./catalog/publication-observer";
import { configEnablesRoutedNamespace, ocxRoutedNamespaceCounts } from "./catalog/routed-removal";
import { inspectCodexHomeOwner } from "./codex-home-owner";
import { shouldSyncCodexOnStart } from "./desired-state";
import { JOURNAL_PATH, journalOwner } from "./journal";
import { CODEX_CONFIG_PATH, CODEX_HOME, DEFAULT_CATALOG_PATH, resolveCodexCatalogPath } from "./paths";
import { siblingOfLivePort } from "./sibling-start";
export type { CatalogObservation } from "./catalog/heal-observation";
export const CATALOG_HEAL_TICK_MS = 30_000;
export const CATALOG_HEAL_RECHECK_MS = 5 * 60_000;
export const CATALOG_HEAL_WINDOW_MS = 60 * 60_000;
export const CATALOG_HEAL_MAX_ATTEMPTS = 6;
export const CATALOG_HEAL_MAX_HEALS = 3;
export type CatalogSelfHealGate = "sibling" | "exiting" | "idle" | "runtime-record" | "config-unavailable" | "codex-off" | "not-owner" | "client";
export interface CatalogSelfHealGates {
siblingOfLivePort(): number | null;
exiting(): boolean;
idle(): boolean;
runtimeOwned(): boolean;
/** File-backed config authority; missing, malformed or salvaged config returns null. */
loadConfig(): OcxConfig | null;
ownsCodexHome(): boolean;
clientConnected(): boolean;
clientJournalOwner(): boolean;
}
export interface CatalogHealOutcome { readonly committed: boolean }
export interface CatalogHealLifecycle {
readonly beforeCommit: () => boolean;
readonly expectedCatalogPath: string;
}
export interface CatalogSelfHealRecord {
readonly at: string;
readonly lostNamespaces: number;
readonly committed: boolean;
}
export interface CatalogSelfHealHandle {
stop(): void;
lastHeal(): CatalogSelfHealRecord | null;
tickForTests(): Promise<void>;
}
export interface CatalogSelfHealDeps {
scheduleFn?: (fn: () => void, ms: number) => { cancel(): void };
now?: () => number;
catalogPath?: () => string | null;
observe?: (path: string, readContent: boolean) => CatalogObservation | null;
retainPath?: typeof retainCatalogHealPath;
converge?: (config: OcxConfig, lifecycle: CatalogHealLifecycle) => Promise<CatalogHealOutcome>;
subscribe?: typeof subscribeCatalogPublication;
gates?: Partial<CatalogSelfHealGates>;
log?: Pick<Console, "warn">;
}
function defaultSchedule(fn: () => void, ms: number): { cancel(): void } {
const timer = setTimeout(fn, ms);
timer.unref?.();
return { cancel: () => clearTimeout(timer) };
}
async function convergeOwnCatalog(config: OcxConfig, lifecycle: CatalogHealLifecycle): Promise<CatalogHealOutcome> {
const [{ armDetachedConfigBaseline }, { createManagementConvergeCodex }, { createCatalogConvergeRequest }] = await Promise.all([
import("../config"), import("./management-convergence"), import("./catalog-admission"),
]);
if (!lifecycle.beforeCommit()) return { committed: false };
// Discovery persistence rebases this detached snapshot against current disk config.
armDetachedConfigBaseline(config);
const outcome = await createManagementConvergeCodex(config, lifecycle)(createCatalogConvergeRequest({ deadlineMs: 1_000 }));
return { committed: outcome.kind === "catalog-only" && outcome.catalogRefresh.status === "committed" };
}
export function evaluateCatalogSelfHealGates(gates: CatalogSelfHealGates):
{ readonly open: true; readonly config: OcxConfig } | { readonly open: false; readonly gate: CatalogSelfHealGate } {
if (gates.siblingOfLivePort() !== null) return { open: false, gate: "sibling" };
if (gates.exiting()) return { open: false, gate: "exiting" };
if (!gates.idle()) return { open: false, gate: "idle" };
if (!gates.runtimeOwned()) return { open: false, gate: "runtime-record" };
const config = gates.loadConfig();
if (config === null) return { open: false, gate: "config-unavailable" };
if (!shouldSyncCodexOnStart(config)) return { open: false, gate: "codex-off" };
if (gates.clientConnected() || gates.clientJournalOwner()) return { open: false, gate: "client" };
if (!gates.ownsCodexHome()) return { open: false, gate: "not-owner" };
return { open: true, config };
}
type NamespaceObservation = { path: string; signature: string; namespaces: ReadonlySet<string> | null };
/** Owner lifecycle only: importing this module starts no timer or publication subscription. */
export function startCodexCatalogSelfHeal(options: { port?: number; deps?: CatalogSelfHealDeps } = {}): CatalogSelfHealHandle {
const deps = options.deps ?? {};
const scheduleFn = deps.scheduleFn ?? defaultSchedule;
const clock = deps.now ?? (() => performance.now());
const catalogPath = deps.catalogPath ?? (() => selectCatalogHealPath(
JOURNAL_PATH, DEFAULT_CATALOG_PATH, path => resolveCodexCatalogPath(CODEX_CONFIG_PATH, path),
));
const observe = deps.observe ?? observeCatalogHealFile;
const converge = deps.converge ?? convergeOwnCatalog;
const gates: CatalogSelfHealGates = {
siblingOfLivePort,
exiting: () => isRecyclingForExit() || isShutdownDraining(),
idle: () => !isDraining() && getActiveTurnCount() === 0,
runtimeOwned: () => {
const runtime = readRuntimePort(process.pid);
return runtime !== null && runtime.siblingOfPort === undefined
&& (options.port === undefined || runtime.port === options.port);
},
loadConfig: () => {
const snapshot = readConfigAdmissionSnapshot();
return snapshot.kind === "read" && snapshot.diagnostics.source === "file"
? snapshot.diagnostics.config : null;
},
ownsCodexHome: () => {
const owner = inspectCodexHomeOwner(CODEX_HOME);
return owner.kind === "owned" || owner.kind === "unbound";
},
clientConnected: () => readClientConnectionState().kind !== "disconnected",
clientJournalOwner: () => journalOwner({ readOnly: true })?.kind === "client",
...deps.gates,
};
const log = deps.log ?? console;
let stopped = false;
let released = false;
let generation = 0;
let timer: { cancel(): void } | undefined;
let running = false;
let last: CatalogSelfHealRecord | null = null;
let target: string | null = null;
let baseline: NamespaceObservation | null = null;
let observed: NamespaceObservation | null = null;
let pendingRetry: { path: string; lostNamespaces: readonly string[] } | null = null;
let recheckAt = 0;
const attempts: number[] = [];
const heals: number[] = [];
const read = (path: string, fresh = false): NamespaceObservation | null => {
const quick = observe(path, false);
if (quick === null) return null;
if (!fresh && observed !== null) {
const relation = compareCatalogHealPaths(observed.path, path);
if (relation === "unknown") return null;
if (relation === "same" && observed.signature === quick.signature) return observed;
}
const seen = observe(path, true);
if (seen === null) return null;
const result = { path, signature: seen.signature, namespaces: seen.catalog ? new Set(ocxRoutedNamespaceCounts(seen.catalog).keys()) : null };
if (!fresh) observed = result;
return result;
};
const accept = (path: string): void => {
const seen = read(path);
if (seen?.namespaces != null) baseline = seen;
};
const clear = (): void => {
generation += 1;
baseline = observed = null;
pendingRetry = null;
recheckAt = 0;
};
const updateTarget = (path: string | null): boolean => {
// Unavailable selection is not evidence of a different target or lost authority.
if (path === null) return false;
if (target !== null) {
const relation = compareCatalogHealPaths(target, path);
if (relation === "unknown") return false;
if (relation === "same") return true;
}
clear();
target = path;
return true;
};
const beforeCommit = (path: string, entryGeneration: number): boolean => {
try {
const selected = catalogPath();
return !stopped && !released && generation === entryGeneration
&& selected !== null && compareCatalogHealPaths(selected, path) === "same" && evaluateCatalogSelfHealGates(gates).open;
} catch { return false; }
};
const capRetryAt = (now: number): number => {
while (attempts.length && now - attempts[0]! >= CATALOG_HEAL_WINDOW_MS) attempts.shift();
while (heals.length && now - heals[0]! >= CATALOG_HEAL_WINDOW_MS) heals.shift();
return Math.max(
attempts.length >= CATALOG_HEAL_MAX_ATTEMPTS ? attempts[0]! + CATALOG_HEAL_WINDOW_MS : 0,
heals.length >= CATALOG_HEAL_MAX_HEALS ? heals[0]! + CATALOG_HEAL_WINDOW_MS : 0,
);
};
const tick = async (): Promise<void> => {
if (stopped || running || released) return;
running = true;
try {
const path = catalogPath();
if (!updateTarget(path) || path === null) return;
// Pending cache/funnel failure is independent of catalog stat or apparent repaired rows.
if (pendingRetry) {
const config = gates.loadConfig();
if (config === null) return;
const enabled = pendingRetry.lostNamespaces.filter(ns => configEnablesRoutedNamespace(config, ns));
if (enabled.length === 0) {
pendingRetry = null;
recheckAt = 0;
const seen = read(path);
if (seen?.namespaces != null) baseline = seen;
return;
}
pendingRetry = { path, lostNamespaces: enabled };
}
const now = clock();
if (now < recheckAt) return;
const seen = read(path);
// Missing/corrupt custom paths are unavailable, never reconstructed from the default.
if (seen?.namespaces == null) return;
if (baseline === null) { baseline = seen; return; }
if (!pendingRetry) {
if (baseline.signature === seen.signature) return;
const lost = [...baseline.namespaces!].filter(ns => !seen.namespaces!.has(ns));
if (lost.length === 0) { baseline = seen; return; }
pendingRetry = { path, lostNamespaces: lost };
}
const gate = evaluateCatalogSelfHealGates(gates);
if (!gate.open) { recheckAt = now + CATALOG_HEAL_RECHECK_MS; return; }
const lostEnabled = pendingRetry.lostNamespaces.filter(ns => configEnablesRoutedNamespace(gate.config, ns));
if (lostEnabled.length === 0) { pendingRetry = null; baseline = seen; return; }
pendingRetry = { path, lostNamespaces: lostEnabled };
const cappedUntil = capRetryAt(now);
if (cappedUntil > now) { recheckAt = cappedUntil; return; }
attempts.push(now);
const entryGeneration = generation;
log.warn(`[catalog-self-heal] republishing ${lostEnabled.length} lost routed provider namespace${lostEnabled.length === 1 ? "" : "s"}`);
let committed = false;
try { committed = (await converge(gate.config, {
beforeCommit: () => beforeCommit(path, entryGeneration), expectedCatalogPath: path,
})).committed; }
catch { /* Failed attempts retain pending retry and consume the attempt budget. */ }
const selected = catalogPath();
if (stopped || released || generation !== entryGeneration || selected === null || compareCatalogHealPaths(selected, path) !== "same") return;
last = { at: new Date().toISOString(), lostNamespaces: lostEnabled.length, committed };
if (committed) {
heals.push(clock());
pendingRetry = null;
recheckAt = 0;
accept(path); // Authoritative emptiness is a successful owner baseline too.
} else recheckAt = clock() + CATALOG_HEAL_RECHECK_MS;
} catch {
log.warn("[catalog-self-heal] observation unavailable; deferred");
} finally { running = false; }
};
const unsubscribe = (deps.subscribe ?? subscribeCatalogPublication)(event => {
if (stopped) return;
const release = event.kind === "native-released" || event.intent === "restore";
// Bind publication evidence before comparisons can observe a retargeted alias.
const stillPublished = !release && event.path !== null ? (deps.retainPath ?? retainCatalogHealPath)(event.path) : null;
// Native restoration can remove the journal before notification. Fence the known
// target (and target-less releases) without resolving possibly unavailable evidence.
const known = event.path !== null && target !== null ? compareCatalogHealPaths(event.path, target) : "different";
if (release && (event.path === null || known !== "different")) {
clear();
released = true;
return;
}
const path = catalogPath();
const selected = event.path !== null && path !== null ? compareCatalogHealPaths(event.path, path) : "different";
if (event.path !== null && known === "different" && selected === "different") return;
if (release) {
clear();
released = true; // Only a later accepted owner publication can re-arm this lifecycle.
return;
}
if (running) {
if (known === "unknown" || selected === "unknown") clear();
return; // Catalog-success/cache-failure must not accept a baseline.
}
// A committed owner publication supplies a read-only baseline even while heal writes are gated.
if (event.path === null || path === null || selected !== "same" || stillPublished === null) return;
// Read independently of obsolete evidence, but retire it only after current selection proof.
const seen = read(event.path, true);
const current = catalogPath();
if (seen?.namespaces == null || current === null
|| compareCatalogHealPaths(event.path, current) !== "same" || !stillPublished(seen.signature)) return;
clear();
target = current;
baseline = observed = seen;
released = false;
});
// Capture immediately after startup sync, before a foreign write can become the first tick.
try { const path = catalogPath(); if (updateTarget(path) && target !== null) accept(target); }
catch { /* Unavailable observation can be retried by the scheduled tick. */ }
const schedule = (): void => {
if (stopped) return;
timer = scheduleFn(() => {
void tick().catch(() => log.warn("[catalog-self-heal] scheduled observation failed")).finally(schedule);
}, CATALOG_HEAL_TICK_MS);
};
schedule();
return {
stop() { stopped = true; clear(); timer?.cancel(); timer = undefined; unsubscribe(); },
lastHeal: () => last,
tickForTests: tick,
};
}