UNPKG

@bitkyc08/opencodex

Version:

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

551 lines (523 loc) • 24.4 kB
/** * Coordination helpers for the native Codex write section. * * Split out of `inject.ts` so the injection function keeps reading as the * sequence it is, rather than doubling in length around the lock. */ import { createHash } from "node:crypto"; import { existsSync, lstatSync, readFileSync } from "node:fs"; import { publishCodexArtifact, publishCodexConfigIfUnchanged } from "./inject/config-write-section"; import { ConfigWriteContentChanged, configDigest, publishedConfigDigest, withConfigWriteLockHeld, type LockHandle } from "./config-write-lock"; import { atomicWriteFile } from "../config"; import type { CodexWriteLockResult, CodexWriteLockSkipReason } from "./codex-write-lock"; import { HUB_GATED_SKIP_MESSAGE } from "./desired-state"; import { siblingSkipMessage } from "./sibling-start"; import { inspectCodexCoordinatorPath } from "./coordinator-doctor"; import { JOURNAL_PATH } from "./journal"; import { updateIntegrationRecord } from "./integration-record"; import { CODEX_CONFIG_PATH, CODEX_PROFILE_PATH } from "./paths"; import type { CodexArtifactId, CodexProvenanceEntry, CodexProvenanceLedger, } from "./convergence-types"; import { codexWriteCoordination, type CodexWriteCandidate, type CodexWriteCoordination, type CodexWriteEvidence, } from "./write-coordination"; /** Bounded so a stuck holder cannot wedge `ocx start` indefinitely. */ export const DEFAULT_INJECT_LOCK_TIMEOUT_MS = 5_000; /** * Can this home be coordinated at all, decided BEFORE any lock attempt? * * The order matters and is not stylistic. `assertInitialStateCanBeCreated` * refuses to create the first coordinator row while native routing residue * exists (`transition-state.ts:268-280`) — correctly, because installing * `{0,null}` over routed bytes would erase the only evidence that an * interrupted transition needs salvage. But "already routed, no coordinator * row" is the state of every install predating this substrate, so a "try the * lock, fall back on refusal" shape would attempt acquisition on the entire * installed base. Deciding first means that refusal path is never entered. * * `legacy-uncoordinated` is a temporary boundary, not a design: the * compatibility-adoption contract (`005_contract.md:709-779`) records an * existing routed home into the coordinator, and once that lands this branch * narrows to homes not yet adopted. */ export type CodexWriteCoordinationEligibility = | { kind: "coordinated" } | { kind: "adopt" } | { kind: "legacy-uncoordinated"; reason: string } | { kind: "refused"; reason: string }; /** * A live SQLite creator exposes a zero-byte pathname before BEGIN IMMEDIATE. * Requiring a settled filesystem age makes that scheduling window remain on * the coordinated path while old crash remnants can use the legacy boundary. */ export const STABLE_ZERO_BYTE_COORDINATOR_AGE_MS = 1_000; export function codexWriteCoordinationEligibility(deps: { coordinatorPath: () => string; residue: () => { kind: string }; integrationRecord: () => { kind: string }; nowMs?: () => number; }): CodexWriteCoordinationEligibility { let coordinatorExists: boolean; let coordinatorIsStableZeroByte = false; try { const path = deps.coordinatorPath(); coordinatorExists = existsSync(path); if (coordinatorExists) { const entry = lstatSync(path); if (entry.isFile() && !entry.isSymbolicLink() && entry.size === 0) { const diagnostic = inspectCodexCoordinatorPath(path); if (diagnostic.kind === "zero-byte") { const lastIdentityChange = Math.max(diagnostic.identity.mtimeMs, diagnostic.identity.ctimeMs); coordinatorIsStableZeroByte = (deps.nowMs?.() ?? Date.now()) - lastIdentityChange >= STABLE_ZERO_BYTE_COORDINATOR_AGE_MS; } } } } catch (error) { return { kind: "refused", reason: `the coordinator path could not be resolved: ${String(error)}` }; } // Every existing coordinator remains authoritative unless it is proven to be // an old, immutable SQLite-empty remnant. The age gate is part of that proof: // a live creator exposes the same zero-byte pathname briefly before taking N, // and sending that fresh file down the legacy path would bypass its lock. // Non-empty, fresh, unsafe, changed, unversioned, and rowless files therefore // stay coordinated and are validated/refused by the transaction owner. // // We do NOT initialize or adopt it here. Clean homes still enter the // coordinated path, whose SQLite transaction safely initializes it. Routed // or indeterminate legacy homes keep the same uncoordinated compatibility // boundary they would have had if the remnant pathname were absent. if (coordinatorExists && !coordinatorIsStableZeroByte) return { kind: "coordinated" }; const record = deps.integrationRecord(); if (record.kind === "invalid") { return { kind: "refused", reason: "the Codex integration record is invalid" }; } const residue = deps.residue(); if (residue.kind === "clean") return { kind: "coordinated" }; if (residue.kind === "residue" && !coordinatorIsStableZeroByte) return { kind: "adopt" }; /* * Everything else keeps the path it has always had. * * `residue` is a pre-substrate routed home; `indeterminate` means the * classifier could not read what is there — a profile it cannot parse, for * instance, which is an ordinary re-injection over an older file rather than * a hazard. * * Neither may CREATE a coordinator row: doing that over unclassified or * routed bytes would erase the evidence an interrupted transition needs. But * refusing the injection outright, which an earlier draft of this function * did for `indeterminate`, breaks re-injection on homes that work today — * caught by the shipped restore tests rather than by review. Declining to * coordinate is the correct scope of the refusal; declining to write is not. */ return { kind: "legacy-uncoordinated", reason: coordinatorIsStableZeroByte ? "the coordinator is a zero-byte non-authoritative remnant and this routed home has not been adopted yet" : residue.kind === "residue" ? "this home was routed before write coordination existed and has not been adopted yet" : "the existing native Codex state could not be classified, so it cannot seed a coordinator row", }; } /** The transition row rejected this publication; a conflict, not an exception. */ export class CodexWriteConflictError extends Error { readonly code = "CODEX_WRITE_CONFLICT"; constructor(message: string) { super(message); this.name = "CodexWriteConflictError"; } } /** * A write failed AND its compensation failed. * * Carries which surfaces are unrestored, never their contents — this reaches * logs and HTTP responses, and config bytes carry credentials. */ export class CodexPartialWriteError extends Error { readonly code = "CODEX_PARTIAL_WRITE"; constructor(readonly unrestored: readonly string[]) { super(`Native Codex files are in a partial state; unrestored: ${unrestored.join(", ")}.`); this.name = "CodexPartialWriteError"; } } function contentIdentity(path: string): string { try { return createHash("sha256").update(readFileSync(path)).digest("hex").slice(0, 32); } catch { return existsSync(path) ? "unreadable" : "absent"; } } export interface CodexPreImages { readonly config: string | null; readonly profile: string | null; readonly journal: string | null; } /** `null` means the file was ABSENT, which restoration must reproduce exactly. */ function readOrNull(path: string): string | null { try { return readFileSync(path, "utf-8"); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; } } export function captureCodexPreImages(): CodexPreImages { return { config: readOrNull(CODEX_CONFIG_PATH), profile: readOrNull(CODEX_PROFILE_PATH), journal: readOrNull(JOURNAL_PATH), }; } /** The profile bytes one injection published, set just before it writes them. */ export interface CodexProfilePublish { published?: string } /** * How many transactions of evidence the ledger keeps. * * Each transaction appends three entries, and a `present` baseline embeds the artifact's exact * bytes as base64 — a 25 KB `config.toml` is ~34 KB per entry, so roughly 100 KB per transaction. * A machine that syncs on every start would grow this file without limit, and it is re-read and * re-serialized on every append, so the cost is quadratic rather than merely large. * * A ledger is evidence, not an archive. The most recent transactions are the ones anyone * diagnoses against, so the window keeps those and drops the oldest. */ export const CODEX_PROVENANCE_MAX_TRANSACTIONS = 16; /** * How many serialized bytes of evidence the ledger keeps. * * The transaction window alone bounds the ledger only if each transaction is small, and a * baseline embeds the artifact's exact bytes. Those artifacts sit outside this proxy's trust * boundary: a native `config.toml` grown to hundreds of megabytes is copied into the record as * base64 and re-serialized on every append, so a single oversized file turns a 16-transaction * window into a multi-gigabyte write. * * The size is derived from the window above rather than picked: the 25 KB `config.toml` that * comment describes measures 100.8 KiB per transaction, so a full 16-transaction window is * 1.58 MiB. 4 MiB leaves that ordinary window untouched with room to spare while still refusing * the pathological case, and a regression test pins the ordinary window so the two cannot drift * apart silently. */ export const CODEX_PROVENANCE_MAX_BYTES = 4 * 1024 * 1024; /** * Measure the representation the integration-record writer actually emits. * * The minimal wrapper reproduces the final indentation depth of `provenance.entries`, including * structured unknown extension fields preserved from older records. Its fixed wrapper makes this * slightly conservative as a ledger-only ceiling, which is preferable to admitting an entry that * expands past the limit when `JSON.stringify(record, null, 2)` writes it. */ function serializedProvenanceBytes( entries: readonly CodexProvenanceEntry[], ledger: CodexProvenanceLedger | undefined, ): number { return Buffer.byteLength(`${JSON.stringify({ version: 1, provenance: { ...ledger, entries }, }, null, 2)}\n`, "utf-8"); } function provenanceBaseline(bytes: string | null): CodexProvenanceEntry["baseline"] { if (bytes === null) return { kind: "absent" }; return { kind: "present", sha256: createHash("sha256").update(bytes).digest("hex"), bytesBase64: Buffer.from(bytes).toString("base64"), }; } function provenancePostImage(path: string): string | null { try { return createHash("sha256").update(readFileSync(path)).digest("hex"); } catch { return null; } } /** * Keep the newest transactions that fit both the transaction window and the byte ceiling, whole. * * Trimming by ENTRY count would cut a transaction in half and leave evidence that says a * transaction touched two artifacts when it touched three — worse than dropping it outright, * because a partial record still reads as complete. Order is preserved; only whole transactions * are removed. * * The byte ceiling applies the same rule: a transaction that does not fit is omitted whole, * including the newest one — a record silently truncated to fit would be read as a faithful * pre-image. An oversized transaction is skipped rather than ending the scan, so one pathological * artifact cannot erase the smaller transactions that still fit and are still diagnosable. */ export function boundProvenanceEntries( entries: readonly CodexProvenanceEntry[], maxTransactions = CODEX_PROVENANCE_MAX_TRANSACTIONS, maxBytes = CODEX_PROVENANCE_MAX_BYTES, ledger?: CodexProvenanceLedger, ): readonly CodexProvenanceEntry[] { const transactions = new Map<string, CodexProvenanceEntry[]>(); for (const entry of entries) { const transaction = transactions.get(entry.txId); if (transaction) transaction.push(entry); else transactions.set(entry.txId, [entry]); } const order = [...transactions.keys()]; if (order.length <= maxTransactions) { const baselineBytes = entries.reduce( (total, entry) => total + (entry.baseline.kind === "present" ? entry.baseline.bytesBase64.length : 0), 0, ); if ( baselineBytes <= maxBytes && serializedProvenanceBytes(entries, ledger) <= maxBytes ) return entries; } // Newest first, so the transactions anyone diagnoses against are the ones that fit. const keep = new Set<string>(); let baselineBytes = 0; for (let i = order.length - 1; i >= 0 && keep.size < maxTransactions; i--) { const txId = order[i]!; const txEntries = transactions.get(txId)!; // Measure the embedded pre-images first: a pathological baseline is refused without // serializing it, so the ceiling does not itself allocate the payload it exists to reject. const transactionBaselineBytes = txEntries.reduce( (total, entry) => total + (entry.baseline.kind === "present" ? entry.baseline.bytesBase64.length : 0), 0, ); if (baselineBytes + transactionBaselineBytes > maxBytes) continue; const candidateKeep = new Set(keep); candidateKeep.add(txId); // Reuse the already-grouped transactions: this avoids another full-ledger filter on each // iteration while preserving the original transaction and entry order. const candidateEntries = order.flatMap(id => candidateKeep.has(id) ? transactions.get(id)! : [] ); if (serializedProvenanceBytes(candidateEntries, ledger) > maxBytes) continue; baselineBytes += transactionBaselineBytes; keep.add(txId); } if (keep.size === order.length) return entries; return entries.filter(entry => keep.has(entry.txId)); } /** Append evidence for an already-committed native transaction, best-effort. */ export function recordCodexNativeTransactionProvenance( preImages: CodexPreImages, txId: string, ) { const at = new Date().toISOString(); const surfaces: readonly [CodexArtifactId, string, string | null][] = [ [{ kind: "config" }, CODEX_CONFIG_PATH, preImages.config], [{ kind: "generated-profile" }, CODEX_PROFILE_PATH, preImages.profile], [{ kind: "injection-journal" }, JOURNAL_PATH, preImages.journal], ]; const entries: readonly CodexProvenanceEntry[] = surfaces.map(([artifact, path, baseline]) => ({ artifact, baseline: provenanceBaseline(baseline), postImage: provenancePostImage(path), txId, at, })); return updateIntegrationRecord(record => { const previousLedger = record.provenance; // Unknown ledger extensions are forward-compatible and must be preserved. If those fixed // fields alone exceed the ceiling, no entry selection can make the write compliant. Keep the // existing record byte-for-byte instead of deleting all known evidence and rewriting the // same oversized extension on every native transaction. if ( previousLedger && serializedProvenanceBytes([], previousLedger) > CODEX_PROVENANCE_MAX_BYTES ) return record; return { ...record, provenance: { ...previousLedger, entries: boundProvenanceEntries( [...(previousLedger?.entries ?? []), ...entries], CODEX_PROVENANCE_MAX_TRANSACTIONS, CODEX_PROVENANCE_MAX_BYTES, previousLedger, ), }, }; }); } /** * Put back exactly what was there, and report honestly when that fails. * * Every surface is attempted even after one fails: a second failure is worth * knowing about, and stopping early would leave more unrestored than necessary. * * `profilePublish`, when given, limits the profile surface to bytes this * operation wrote: it is reverted only if `published` is set and the file still * holds exactly those bytes. A refusal before the publish, or a profile another * writer replaced since, is left as it is. */ let afterCompensationDecisionForTests: ((surface: string) => void) | undefined; /** Test seam: runs after compensation decided a surface must be restored and before it publishes. */ export function setAfterCompensationDecisionForTests(hook: typeof afterCompensationDecisionForTests): void { afterCompensationDecisionForTests = hook; } export function restoreCodexPreImages( pre: CodexPreImages, heldConfigWriteLock?: LockHandle, profilePublish?: CodexProfilePublish, ): { complete: boolean; unrestored: readonly string[] } { const surfaces: readonly [string, string, string | null][] = [ ["config", CODEX_CONFIG_PATH, pre.config], ["profile", CODEX_PROFILE_PATH, pre.profile], ["journal", JOURNAL_PATH, pre.journal], ]; /* * What a surface needs. One already holding its preimage needs nothing, and must not be made to * pass a destination check: a foreign atomic rename of config.toml would otherwise fail the * untouched profile and journal too. With a held lock (every injection and restore section), * config.toml is reverted only when this section published it and it still holds that * publication; any other bytes there belong to another writer. A direct call without a held lock * has no publication record and keeps the unconditional config restore it always had. */ // Returns the bytes the decision was made on (undefined when unreadable), so the restore can // refuse when the file changed after it was judged to be OpenCodex's. type Decision = readonly ["skip" | "foreign" | "restore", (string | null)?]; const decide = (name: string, path: string, bytes: string | null, held: LockHandle | undefined): Decision => { let current: string | null; // An unreadable surface proves nothing; the guarded restore attempt reports it as unrestored. try { current = readOrNull(path); } catch { return ["restore"]; } if (current === bytes) return ["skip", current]; if (name === "profile" && profilePublish && (profilePublish.published === undefined || current !== profilePublish.published)) return ["skip", current]; if (name !== "config") return ["restore", current]; const ours = held ? publishedConfigDigest(held) : undefined; if (ours === undefined) return [held ? "skip" : "restore", current]; return [configDigest(current) === ours ? "restore" : "foreign", current]; }; if (surfaces.every(([name, path, bytes]) => decide(name, path, bytes, heldConfigWriteLock)[0] === "skip")) { return { complete: true, unrestored: [] }; } const locked = withConfigWriteLockHeld(CODEX_CONFIG_PATH, heldConfigWriteLock, held => { const unrestored: string[] = []; for (const [name, path, bytes] of surfaces) { // The current journal remains recovery authority until both artifacts are restored. if (name === "journal" && unrestored.length > 0) { unrestored.push(name); continue; } try { const [need, decided] = decide(name, path, bytes, heldConfigWriteLock === undefined ? undefined : held); if (need === "skip") continue; if (need === "foreign") { unrestored.push(name); continue; } afterCompensationDecisionForTests?.(name); if (name === "config" && heldConfigWriteLock !== undefined) { if (decided === undefined) throw new ConfigWriteContentChanged(); // Publish over, or remove, only the exact bytes judged to be this section's publication. if (bytes !== null) { publishCodexConfigIfUnchanged(held, "compensate", decided, bytes); continue; } publishCodexArtifact(path, held, (destination, hooks) => { hooks.validateBeforeRename?.(destination); if (readOrNull(destination) !== decided) throw new ConfigWriteContentChanged(); if (existsSync(destination)) require("node:fs").unlinkSync(destination); hooks.afterRename?.(destination); }); continue; } publishCodexArtifact(path, held, (destination, hooks) => { if (bytes === null) { hooks.validateBeforeRename?.(destination); if (existsSync(destination)) require("node:fs").unlinkSync(destination); hooks.afterRename?.(destination); } else if (readOrNull(destination) !== bytes) atomicWriteFile(destination, bytes, undefined, hooks); }); } catch { unrestored.push(name); } } return { complete: unrestored.length === 0, unrestored }; }); if (locked.ok) return locked.value; // The section can no longer publish (its destination changed). Name only what still differs // from its preimage; a surface already holding it was not left partial. const unrestored = surfaces.filter(([name, path, bytes]) => decide(name, path, bytes, heldConfigWriteLock)[0] !== "skip").map(([name]) => name); if (unrestored.length > 0 && !unrestored.includes("journal")) unrestored.push("journal"); return { complete: false, unrestored }; } export function buildInjectWitness( candidate: CodexWriteCandidate, nativeInput: string, persistedIdentity: string, generation: CodexWriteEvidence["generation"], observedOwnership: CodexWriteCoordination["observedOwnership"], ): CodexWriteCoordination { return codexWriteCoordination( candidate, { nativeInputIdentity: createHash("sha256").update(nativeInput).digest("hex"), persistedIdentity, generation, journalIdentity: contentIdentity(JOURNAL_PATH), canonicalTargets: { config: CODEX_CONFIG_PATH, profile: CODEX_PROFILE_PATH, journal: JOURNAL_PATH, }, }, observedOwnership, ); } /** * The under-lock re-read. * * The candidate bytes are fixed — they were computed before acquisition and do * not change — so what is re-read is the EVIDENCE: the native input on disk, the * journal, the generation from the open transaction. A comparison that copied * those forward would match itself and prove nothing. */ export function recomputeInjectWitness(options: { candidate: CodexWriteCandidate; canonicalTargets: CodexWriteEvidence["canonicalTargets"]; persistedIdentity: string; generation: CodexWriteEvidence["generation"]; observedOwnership: CodexWriteCoordination["observedOwnership"]; }): CodexWriteCoordination { const nativeInput = readOrNull(options.canonicalTargets.config) ?? ""; return codexWriteCoordination( options.candidate, { nativeInputIdentity: createHash("sha256").update(nativeInput).digest("hex"), persistedIdentity: options.persistedIdentity, generation: options.generation, journalIdentity: contentIdentity(options.canonicalTargets.journal), canonicalTargets: options.canonicalTargets, }, options.observedOwnership, ); } /** Project a non-acquired lock result into the injection result shape. */ export function codexInjectLockOutcome( result: Exclude<CodexWriteLockResult<unknown>, { status: "acquired" }>, ): { success: false; message: string; retryable: boolean } | { success: true; status: "skipped"; skippedReason: CodexWriteLockSkipReason; message: string; } { if (result.status === "skipped") { return { success: true, status: "skipped", skippedReason: result.reason, // Four distinct facts, four sentences. The hub gate in particular must not borrow the // toggle's wording — that is the phantom "integration is OFF" report from #4236. message: result.reason === "hub-gated" ? `${HUB_GATED_SKIP_MESSAGE} No Codex config, catalog, cache, or history was changed.` : result.reason === "sibling" ? `${siblingSkipMessage()} No Codex config, catalog, cache, or history was changed.` : result.reason === "desired_disabled" ? "Codex integration is OFF; no Codex config, catalog, cache, or history was changed." : "Codex integration was re-enabled; native restore was skipped.", }; } if (result.status === "busy") { return { success: false, retryable: true, message: `Another process is writing Codex configuration right now (waited ${result.waitedMs}ms). Retry shortly.`, }; } return { success: false, retryable: false, message: `Codex configuration was not written: ${result.message}`, }; }