UNPKG

@bitkyc08/opencodex

Version:

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

223 lines (211 loc) • 10.9 kB
import { readConfigAdmissionSnapshot } from "./diagnostics"; import { getConfigPath } from "./paths"; import { canonicalPlainData, copyPlainData, isPlainObject, ownDataKeys } from "../lib/plain-data"; import type { OcxConfig } from "../types"; /** * A configuration a roster may be built from, detached from the object the caller holds. * * The detachment is the point. A gather suspends, and while it is suspended a management route can * edit the resident configuration in place; gathering from one state and projecting from another * would produce rows that belong to neither. Every authoritative pass uses this copy from * beginning to end, so what the resident object does in the meantime becomes a question about * whether the result may be retained rather than a question about what the result is. * * What this deliberately does NOT do is require the resident configuration to equal the file on * disk. The proxy routes by the configuration it is holding, so that is the configuration a * preview and the mutation it authorizes must both describe. A file the operator has edited and * the process has not adopted is a supported state rather than a fault: live reconciliation * (src/config/live-reconcile.ts) merges persisted state while deliberately retaining live changes * and the active listener binding, and can persist a binding the resident object does not have. * Demanding equality would make preview permanently unavailable on exactly those configurations * while proving nothing about the rows, which come from the resident object either way. */ export interface ExportConfigAdmission { readonly config: OcxConfig; } /** * What was true when an admission was captured, kept here rather than on the admission object. * * None of it is data a consumer has any business reading: the file term is a digest of the * operator's configuration file and the canonical form contains their credentials. Holding it in a * module WeakMap means an admission can be passed around, and even serialized by a careless * caller, without carrying any of it. */ interface AdmissionEvidence { readonly path: string; readonly file: string; readonly data: string; readonly executors: ReadonlyMap<string, unknown>; } const evidence = new WeakMap<ExportConfigAdmission, AdmissionEvidence>(); /** * Detach the configuration a roster is about to be built from, and record what it was. * * Two things are recorded because two things can move independently. The resident configuration is * what the rows are derived from, so its complete structure is captured: structurally rather than * as a list of the fields that seemed to matter, because such a list is only as complete as * whoever last thought about it and this one had already missed export-affecting configuration. * The configuration file is recorded beside it, so a roster does not outlive an operator editing * the configuration under a process that has not adopted it yet. * * Null when the file cannot be read, when it is there but the loader would have had to salvage it, * and when the configuration object cannot be copied as plain data. Every caller fails closed on * it: refusing a preview costs an ordinary load, and serving one that describes a configuration * nobody has costs a file the operator did not ask for. */ export function captureExportConfigAdmission(live: OcxConfig): ExportConfigAdmission | null { const path = getConfigPath(); const file = admittedFileTerm(); if (file === null) return null; const resident = detachConfig(live); if (resident === null) return null; const config = withExecutors(resident); if (config === null) return null; const admission: ExportConfigAdmission = { config }; evidence.set(admission, { path, file, data: canonicalPlainData(resident.data), executors: resident.executors }); return admission; } /** * Whether an admission still describes the configuration in hand and the file it was taken beside. * * Three things are checked because three things can move: the file can be rewritten, the resident * object can be edited in place, and a consumer of the detached copy can mutate what it was given. * The last matters as much as the others, because a pass that edited its own input and then * published would be retaining a roster under a state that no longer describes even that input. * * Passive: it reads the configuration file and nothing else. No credential is resolved, no * provider is contacted, no path is hardened and nothing is written. */ export function isExportConfigAdmissionCurrent(admission: ExportConfigAdmission, live: OcxConfig): boolean { const captured = evidence.get(admission); if (captured === undefined) return false; // A different configuration home is a different question, not a stale answer to this one. if (getConfigPath() !== captured.path) return false; const file = admittedFileTerm(); if (file === null || file !== captured.file) return false; const resident = detachConfig(live); if (resident === null || canonicalPlainData(resident.data) !== captured.data) return false; if (!sameExecutors(resident.executors, captured.executors)) return false; const working = detachConfig(admission.config); return working !== null && canonicalPlainData(working.data) === captured.data && sameExecutors(working.executors, captured.executors); } /** * A plain-data copy of a configuration for a consumer that must not observe later edits, or null. * * The integration writer is the case this exists for. It freezes every other resolution seam * before its first await and then held the configuration by reference, so a plan checked under one * configuration could be written from another: the check and the document it authorized were * reading the same object at two different moments. One copy taken before the await gives both of * them the same configuration. * * Null rather than the caller's object when the copy cannot be made. Handing back the reference * would have been a copy in name only, and the caller would have gone on to describe it as the * configuration it checked. */ export function detachedConfigSnapshot(config: OcxConfig): OcxConfig | null { const detached = detachConfig(config); return detached === null ? null : withExecutors(detached); } /** * The configuration file as an opaque term: its exact bytes, or the distinguished absence of one. * * This is a byte observation and nothing more. It says the operator's configuration file has not * been rewritten since a roster was built; it is not a claim about whether the configuration the * process is holding agrees with that file. * * Null for a file that cannot be read, because then a later read cannot tell whether it changed. * Null too for one that is there and does not load cleanly, which is the existing contract for a * derived roster rather than an inference about the resident configuration. Before this, a digest * was accepted ahead of any look at what the parse produced. * * Absence is a configuration rather than the lack of one. No file means defaults, which is an * ordinary fresh install and the ordinary state in CI. */ function admittedFileTerm(): string | null { const snapshot = readConfigAdmissionSnapshot(); const { source, error } = snapshot.diagnostics; if (snapshot.kind === "read") return source === "file" && error === null ? snapshot.contentSha256 : null; return source === "default" && error === null ? "absent" : null; } interface DetachedConfig { readonly data: Record<string, unknown>; readonly executors: ReadonlyMap<string, unknown>; } /** * A configuration as plain data, with the transport executors kept out of it. * * The copier refuses everything JSON could not have produced, so the one thing that needs handling * here is a provider's fetch executor: a caller owns it and the gather uses it instead of the * global transport. It is held by reference for the detached copy and compared by reference * afterwards, so replacing it invalidates the binding while it is never serialized. */ function detachConfig(live: OcxConfig): DetachedConfig | null { const executors = new Map<string, unknown>(); const root = live as unknown; if (!isPlainObject(root)) return null; const data: Record<string, unknown> = {}; for (const key of ownDataKeys(root)) { if (key === null) return null; const value = root[key]; if (value === undefined) continue; if (key !== "providers") { const copied = copyPlainData(value); if (!copied.ok) return null; data[key] = copied.value; continue; } if (!isPlainObject(value)) return null; const providers: Record<string, unknown> = {}; for (const name of ownDataKeys(value)) { if (name === null) return null; const provider = value[name]; if (provider === undefined) continue; if (!isPlainObject(provider)) return null; const copiedProvider: Record<string, unknown> = {}; for (const field of ownDataKeys(provider)) { if (field === null) return null; const fieldValue = provider[field]; if (fieldValue === undefined) continue; // The executor exception applies to an executor. A provider entry keeps unknown // configuration keys, so a fetch value that is not a function is something an operator // wrote into the file, and it is copied and compared as the data it is. Discovery reads it // the same way: the outbound transport takes its built-in path unless the value is // callable. if (field === "fetch" && typeof fieldValue === "function") { executors.set(name, fieldValue); continue; } const copied = copyPlainData(fieldValue); if (!copied.ok) return null; copiedProvider[field] = copied.value; } providers[name] = copiedProvider; } data[key] = providers; } return { data, executors }; } /** The copy a consumer runs against, with the executors put back by reference. */ function withExecutors(detached: DetachedConfig): OcxConfig | null { // A second copy, so what is compared later is never the object handed to a consumer. const copied = copyPlainData(detached.data); if (!copied.ok) return null; const config = copied.value; const providers = config.providers; if (isPlainObject(providers)) { for (const [name, executor] of detached.executors) { const provider = providers[name]; if (isPlainObject(provider)) provider.fetch = executor; } } return config as unknown as OcxConfig; } function sameExecutors(left: ReadonlyMap<string, unknown>, right: ReadonlyMap<string, unknown>): boolean { if (left.size !== right.size) return false; for (const [name, executor] of left) { if (!right.has(name) || right.get(name) !== executor) return false; } return true; }