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