UNPKG

@bitkyc08/opencodex

Version:

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

207 lines (194 loc) • 13.1 kB
import { chmodSync, mkdirSync, readFileSync } from "node:fs"; import { dirname, join } from "node:path"; import { atomicWriteFile } from "../config/atomic-write"; import { withConfigMutationLockSync } from "../config/mutation-lock"; import { assertNotRealHomeUnderTest } from "../lib/test-home-guard"; import { parseStrictSemver } from "../lib/strict-semver"; import { hardenSecretDir } from "../lib/windows-secret-acl"; import { PLAN_RUNTIME_OWNERS, type InstallKind, type PlanRuntimeOwner, type UpdateRoute } from "./child-update-contract"; import { childObservationsPath } from "./paths"; import { readLinkStore } from "./store"; /** * What the Home last learned about each Child, keyed by link id, in <configDir>/link/child-observations.json. * A cache, not a trust boundary: unlike links.json's strict record keys, unknown keys are dropped, an invalid entry is * dropped and a damaged or foreign file reads as empty, so a downgraded Home ignores it and links.json never changes. */ export const CHILD_OBSERVATIONS_SCHEMA = "ocx.link.child-observations/1"; export const CHILD_OBSERVATIONS_MAX_BYTES = 1024 * 1024; export const DEFAULT_MAX_CHILD_OBSERVATIONS = 256; export type ChildOp = "observe" | "sync" | "restart-codex" | "update"; /** The persisted slice of a wp3 job item. */ export interface ChildOperationSummary { op: ChildOp; jobId: string; state: string; reason: string | null; fromVersion?: string; toVersion?: string; finishedAt: string; } export interface ChildObservation { observedAt: string; source: "plan" | "inspect" | "peer"; installedVersion: string | null; installKind: InstallKind; runtimeOwner: PlanRuntimeOwner | null; updateRoute: UpdateRoute; updateReason: string | null; targetVersion: string | null; catalogPulledAt: number | null; lastOperation: ChildOperationSummary | null; suppressedTarget: string | null; /** Etag of the catalog bytes served with the pull at catalogPulledAt. Display verdict only. */ catalogPulledEtag: string | null; /** Home catalog etag current when a Home-run pinned sync of this Child last reported synced. Fan-out eligibility * uses this field, never catalogPulledAt: a GET of /v1/catalog only proves a fetch. */ catalogSyncedEtag: string | null; /** Counted automatic update attempts for one target; survives a Home restart. */ autoUpdateAttempts: { target: string; count: number } | null; /** plan.updateInFlight from the last ocx.update.plan/1 probe; null when the observation did not come from a plan. * Not a carried field: every observe replaces it. */ updateInFlight: boolean | null; /** An update whose result is unknown. A record carrying desktopRequestId is cleared only by the Desktop route's * status reconciliation or by expiry, never by a sync. */ pendingUpdateRecovery: { target: string; since: string; until: string; desktopRequestId?: string } | null; } /** Fields an operation or the Home owns; a fresh observe never overwrites them. Missing in an older file ⇒ null. */ export const CARRIED_OBSERVATION_FIELDS = ["catalogPulledAt", "catalogPulledEtag", "catalogSyncedEtag", "lastOperation", "suppressedTarget", "autoUpdateAttempts", "pendingUpdateRecovery"] as const; export interface ChildObservationsFile { schema: typeof CHILD_OBSERVATIONS_SCHEMA; homeCatalog: { etag: string; changedAt: number } | null; children: Record<string, ChildObservation>; } const LINK_ID = /^lnk_[0-9a-f]{16}$/; // Underscores: the sync classifier's reasons carry the Child's own mismatch token (child-link-mismatch:other_link). const REASON = /^[a-z][a-z0-9:_-]{0,79}$/; const STATE = /^[a-z][a-z0-9-]{0,63}$/; const OPAQUE_ID = /^[A-Za-z0-9_.:-]{1,128}$/; const SOURCES: ReadonlySet<string> = new Set(["plan", "inspect", "peer"]); const OPS: ReadonlySet<string> = new Set<ChildOp>(["observe", "sync", "restart-codex", "update"]); const INSTALL_KINDS: ReadonlySet<string> = new Set<InstallKind>(["npm", "pnpm", "bun", "source", "mise", "desktop-app", "goat", "standalone", "ocx-child", "unknown"]); const ROUTES: ReadonlySet<string> = new Set<UpdateRoute>(["orchestrated", "desktop-request", "owner-action", "replant", "none"]); /** Thrown inside a field reader; the entry that holds the field is dropped. */ class Drop extends Error {} const drop = (): never => { throw new Drop(); }; const isObject = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value); const version = (value: unknown): string => typeof value === "string" && value.length <= 128 && parseStrictSemver(value) ? value : drop(); const nullable = <T>(value: unknown, read: (value: unknown) => T): T | null => value === null || value === undefined ? null : read(value); const time = (value: unknown): string => typeof value === "string" && value.length <= 64 && !Number.isNaN(Date.parse(value)) ? value : drop(); const epoch = (value: unknown): number => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : drop(); const token = (pattern: RegExp) => (value: unknown): string => typeof value === "string" && pattern.test(value) ? value : drop(); const member = <T extends string>(set: ReadonlySet<string>) => (value: unknown): T => typeof value === "string" && set.has(value) ? value as T : drop(); // Etags are quoted opaque strings; anything printable and bounded is kept. const etag = (value: unknown): string => typeof value === "string" && value.length >= 1 && value.length <= 256 && /^[\x20-\x7e]+$/.test(value) ? value : drop(); function summary(value: unknown): ChildOperationSummary { if (!isObject(value)) return drop(); return { op: member<ChildOp>(OPS)(value.op), jobId: token(OPAQUE_ID)(value.jobId), state: token(STATE)(value.state), reason: nullable(value.reason, token(REASON)), ...(value.fromVersion === undefined ? {} : { fromVersion: version(value.fromVersion) }), ...(value.toVersion === undefined ? {} : { toVersion: version(value.toVersion) }), finishedAt: time(value.finishedAt), }; } function attempts(value: unknown): { target: string; count: number } { if (!isObject(value)) return drop(); const count = value.count; return { target: version(value.target), count: typeof count === "number" && Number.isSafeInteger(count) && count >= 0 ? count : drop() }; } function recovery(value: unknown): NonNullable<ChildObservation["pendingUpdateRecovery"]> { if (!isObject(value)) return drop(); return { target: version(value.target), since: time(value.since), until: time(value.until), ...(value.desktopRequestId === undefined ? {} : { desktopRequestId: token(OPAQUE_ID)(value.desktopRequestId) }) }; } function observation(value: unknown): ChildObservation { if (!isObject(value)) return drop(); return { observedAt: time(value.observedAt), source: member<ChildObservation["source"]>(SOURCES)(value.source), installedVersion: nullable(value.installedVersion, version), installKind: member<InstallKind>(INSTALL_KINDS)(value.installKind), runtimeOwner: nullable(value.runtimeOwner, member<PlanRuntimeOwner>(PLAN_RUNTIME_OWNERS)), updateRoute: member<UpdateRoute>(ROUTES)(value.updateRoute), updateReason: nullable(value.updateReason, token(REASON)), targetVersion: nullable(value.targetVersion, version), catalogPulledAt: nullable(value.catalogPulledAt, epoch), lastOperation: nullable(value.lastOperation, summary), suppressedTarget: nullable(value.suppressedTarget, version), catalogPulledEtag: nullable(value.catalogPulledEtag, etag), catalogSyncedEtag: nullable(value.catalogSyncedEtag, etag), autoUpdateAttempts: nullable(value.autoUpdateAttempts, attempts), updateInFlight: nullable(value.updateInFlight, item => typeof item === "boolean" ? item : drop()), pendingUpdateRecovery: nullable(value.pendingUpdateRecovery, recovery), }; } function homeCatalog(value: unknown): ChildObservationsFile["homeCatalog"] { if (!isObject(value)) return null; try { return { etag: etag(value.etag), changedAt: epoch(value.changedAt) }; } catch (error) { if (error instanceof Drop) return null; throw error; } } export function emptyChildObservations(): ChildObservationsFile { return { schema: CHILD_OBSERVATIONS_SCHEMA, homeCatalog: null, children: {} }; } export function withoutCarriedFields(value: ChildObservation): Partial<ChildObservation> { const copy: Partial<ChildObservation> = { ...value }; for (const field of CARRIED_OBSERVATION_FIELDS) delete copy[field]; return copy; } /** Tolerant: unknown keys dropped, an invalid entry dropped, an invalid file or wrong schema reads as empty. */ export function parseChildObservations(text: string): ChildObservationsFile { let raw: unknown; try { raw = JSON.parse(text); } catch { return emptyChildObservations(); } if (!isObject(raw) || raw.schema !== CHILD_OBSERVATIONS_SCHEMA) return emptyChildObservations(); const file: ChildObservationsFile = { schema: CHILD_OBSERVATIONS_SCHEMA, homeCatalog: homeCatalog(raw.homeCatalog), children: {} }; if (!isObject(raw.children)) return file; for (const [linkId, entry] of Object.entries(raw.children)) { if (!LINK_ID.test(linkId)) continue; try { file.children[linkId] = observation(entry); } catch (error) { if (!(error instanceof Drop)) throw error; } } return file; } /** Missing, unreadable, larger than 1 MiB or damaged → empty. Never throws for content. */ export function readChildObservations(path: string = childObservationsPath()): ChildObservationsFile { let bytes: Buffer; try { bytes = readFileSync(path); } catch { return emptyChildObservations(); } if (bytes.length > CHILD_OBSERVATIONS_MAX_BYTES) return emptyChildObservations(); return parseChildObservations(bytes.toString("utf8")); } /** Keep the most recently observed entries when the file holds more than maxEntries. */ function capEntries(file: ChildObservationsFile, maxEntries: number): void { const entries = Object.entries(file.children); if (entries.length <= maxEntries) return; entries.sort(([, a], [, b]) => Date.parse(b.observedAt) - Date.parse(a.observedAt)); file.children = Object.fromEntries(entries.slice(0, Math.max(0, maxEntries))); } /** * Read–mutate–write under withConfigMutationLockSync. Inside the lock it reads links.json and drops entries whose link * id is absent; a damaged links.json disables pruning for that write only. Dir 0700 (hardenSecretDir on Windows), file * written with atomicWriteFile then chmod 0600, as writeLinkStore. Throws ConfigMutationLockError on contention * (busy_timeout=0); callers decide whether to retry. */ export function updateChildObservations(mutate: (file: ChildObservationsFile) => void, deps: { path?: string; storePath?: string; maxEntries?: number } = {}): ChildObservationsFile { const path = deps.path ?? childObservationsPath(); const dir = dirname(path), configDir = dirname(dir); assertNotRealHomeUnderTest(configDir); return withConfigMutationLockSync(() => { const current = readChildObservations(path); mutate(current); const next = parseChildObservations(JSON.stringify(current)); let linkIds: Set<string> | null = null; try { linkIds = new Set(readLinkStore(deps.storePath ?? join(dir, "links.json")).links.map(link => link.id)); } catch { linkIds = null; } if (linkIds) for (const linkId of Object.keys(next.children)) if (!linkIds.has(linkId)) delete next.children[linkId]; capEntries(next, deps.maxEntries ?? DEFAULT_MAX_CHILD_OBSERVATIONS); mkdirSync(dir, { recursive: true, mode: 0o700 }); if (process.platform === "win32") hardenSecretDir(dir, { required: true }); else chmodSync(dir, 0o700); atomicWriteFile(path, `${JSON.stringify(next, null, 2)}\n`); if (process.platform !== "win32") chmodSync(path, 0o600); return next; }, configDir); } /** * Merge a patch into one Child's entry and stamp observedAt with now. A patch of carried fields only (a catalog pull, * an operation summary) keeps an existing entry's observedAt, so install facts never read fresher than they are. * A Child never observed before starts as an unknown "inspect" record with every field null, so an operation summary * can be stored before the first observe; that new entry is stamped. */ export function patchChildObservation(file: ChildObservationsFile, linkId: string, patch: Partial<ChildObservation>, now: Date): void { const existing = file.children[linkId]; const base: ChildObservation = existing ?? { observedAt: now.toISOString(), source: "inspect", installedVersion: null, installKind: "unknown", runtimeOwner: null, updateRoute: "none", updateReason: null, targetVersion: null, catalogPulledAt: null, lastOperation: null, suppressedTarget: null, catalogPulledEtag: null, catalogSyncedEtag: null, autoUpdateAttempts: null, updateInFlight: null, pendingUpdateRecovery: null, }; const carriedOnly = Object.keys(patch).every(key => (CARRIED_OBSERVATION_FIELDS as readonly string[]).includes(key)); file.children[linkId] = { ...base, ...patch, observedAt: carriedOnly && existing ? base.observedAt : now.toISOString() }; }