UNPKG

@bitkyc08/opencodex

Version:

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

144 lines (131 loc) • 7.61 kB
/** * What a Remote Link Child tells its Home about the last settings apply (OCX-6). * * The Child knows when it last applied the Home's Codex settings, which digest it applied and when * its runtime started; the Home knows none of it. The Child reports these facts over the link * (`POST` to {@link LINK_CHILD_PARITY_PATH}, admitted by its link key) and the Home shows them on * each link row of `GET /api/link/status` (`lastApplyAt`, `runtimeStartedAt`, * `appliedCodexSettingsDigest`), so a peer can compare apply time with runtime start, and the * applied digest with the Home's own, without reading the Child. * * Display only. A report never admits, routes or changes anything on the Home, carries no setting * value, and lives in memory: a Home restart forgets it until the Child's next report (at most a * minute later). */ import { CODEX_SETTINGS_DIGEST_PATTERN } from "./codex-settings"; import { LINK_MANAGEMENT_PREFIX } from "./management-routes"; import { parseRouteClientOutcomes, ROUTE_INTENT_DIGEST_PATTERN, routeClientOutcomesForPeer, type RouteClientOutcome } from "./route-intent"; /** The one write a Child may send its Home over the link. */ export const LINK_CHILD_PARITY_PATH = `${LINK_MANAGEMENT_PREFIX}/child-parity`; /** A report is four short fields; anything larger is refused while it is still being read. */ export const LINK_CHILD_PARITY_MAX_BYTES = 8192; const LINK_ID = /^lnk_[0-9a-f]{16}$/; /** 2001-09-09 .. 2286-11-20: any epoch-millisecond time a real clock reports. */ const MIN_EPOCH_MS = 1_000_000_000_000; const MAX_EPOCH_MS = 9_999_999_999_999; export interface LinkChildParityReport { linkId: string; /** Epoch ms of the Child's last successful apply of a different Home settings document. */ lastApplyAt: number | null; /** Epoch ms of the Child runtime's process start. */ runtimeStartedAt: number; /** `appliedCodexSettingsDigest` of the applied settings; null before any apply. */ appliedCodexSettingsDigest: string | null; appliedRouteIntentDigest?: string | null; routeClientOutcomes?: RouteClientOutcome[]; /** * Increases with every report this runtime process sends. With `runtimeStartedAt` it orders * reports, so a late POST from an older runtime or an earlier send never replaces a newer one. */ sequence: number; } /** The per-link fields `GET /api/link/status` carries; every one is null until a report arrives. */ export interface LinkChildParity { lastApplyAt: number | null; runtimeStartedAt: number | null; appliedCodexSettingsDigest: string | null; appliedRouteIntentDigest?: string | null; routeClientOutcomes?: RouteClientOutcome[]; /** Epoch ms the Home received the report (the Home's clock; the other times are the Child's). */ reportedAt: number | null; } export const EMPTY_LINK_CHILD_PARITY: LinkChildParity = Object.freeze({ lastApplyAt: null, runtimeStartedAt: null, appliedCodexSettingsDigest: null, reportedAt: null, }); export function isEpochMs(value: unknown): value is number { return typeof value === "number" && Number.isSafeInteger(value) && value >= MIN_EPOCH_MS && value <= MAX_EPOCH_MS; } function exactKeys(value: unknown, keys: readonly string[]): value is Record<string, unknown> { if (!value || typeof value !== "object" || Array.isArray(value)) return false; const actual = Object.keys(value); return actual.length === keys.length && actual.every(key => keys.includes(key)); } /** Strict: an unknown field, a non-integer time or a malformed digest rejects the report. */ export function parseLinkChildParityReport(value: unknown): LinkChildParityReport | null { const base = ["linkId", "lastApplyAt", "runtimeStartedAt", "appliedCodexSettingsDigest", "sequence"]; const extended = [...base, "appliedRouteIntentDigest", "routeClientOutcomes"]; if (!exactKeys(value, base) && !exactKeys(value, extended)) return null; const { linkId, lastApplyAt, runtimeStartedAt, appliedCodexSettingsDigest: digest, sequence } = value; if (typeof linkId !== "string" || !LINK_ID.test(linkId)) return null; if (lastApplyAt !== null && !isEpochMs(lastApplyAt)) return null; if (!isEpochMs(runtimeStartedAt)) return null; if (digest !== null && (typeof digest !== "string" || !CODEX_SETTINGS_DIGEST_PATTERN.test(digest))) return null; // An apply has both a time and a digest; before the first apply it has neither. if ((lastApplyAt === null) !== (digest === null)) return null; if (typeof sequence !== "number" || !Number.isSafeInteger(sequence) || sequence < 0) return null; let route: Pick<LinkChildParityReport, "appliedRouteIntentDigest" | "routeClientOutcomes"> = {}; if (Object.hasOwn(value, "appliedRouteIntentDigest")) { const routeDigest = value.appliedRouteIntentDigest; if (routeDigest !== null && (typeof routeDigest !== "string" || !ROUTE_INTENT_DIGEST_PATTERN.test(routeDigest))) return null; const outcomes = parseRouteClientOutcomes(value.routeClientOutcomes); if (!outcomes) return null; route = { appliedRouteIntentDigest: routeDigest, routeClientOutcomes: routeClientOutcomesForPeer(outcomes) }; } return { linkId, lastApplyAt, runtimeStartedAt, appliedCodexSettingsDigest: digest, sequence, ...route }; } export interface LinkChildParityStore { /** * Keep the report for its link unless a newer one is already kept (by `runtimeStartedAt`, then * `sequence`), dropping every entry whose link is not in `currentLinkIds`. True when kept. */ record(report: LinkChildParityReport, currentLinkIds: ReadonlySet<string>): boolean; get(linkId: string): LinkChildParity; clear(): void; } export function createLinkChildParityStore(now: () => number = Date.now): LinkChildParityStore { const reports = new Map<string, LinkChildParity & { sequence: number }>(); return { record(report, currentLinkIds) { for (const id of reports.keys()) if (!currentLinkIds.has(id)) reports.delete(id); if (!currentLinkIds.has(report.linkId)) return false; const kept = reports.get(report.linkId); if (kept && (kept.runtimeStartedAt! > report.runtimeStartedAt || (kept.runtimeStartedAt === report.runtimeStartedAt && kept.sequence >= report.sequence))) return false; reports.set(report.linkId, { lastApplyAt: report.lastApplyAt, runtimeStartedAt: report.runtimeStartedAt, appliedCodexSettingsDigest: report.appliedCodexSettingsDigest, ...(report.routeClientOutcomes === undefined ? {} : { appliedRouteIntentDigest: report.appliedRouteIntentDigest ?? null, routeClientOutcomes: routeClientOutcomesForPeer(report.routeClientOutcomes), }), reportedAt: now(), sequence: report.sequence, }); return true; }, get(linkId) { const kept = reports.get(linkId); if (!kept) return { ...EMPTY_LINK_CHILD_PARITY }; const { sequence: _sequence, ...parity } = kept; return { ...parity, ...(parity.routeClientOutcomes === undefined ? {} : { routeClientOutcomes: routeClientOutcomesForPeer(parity.routeClientOutcomes) }) }; }, clear() { reports.clear(); }, }; } /** The Home's reports: one process-wide store, bounded by the link store on every write. */ export const homeLinkChildParity: LinkChildParityStore = createLinkChildParityStore(); /** Home link listener: is this the Child's report (exact path, POST, no query, no upgrade)? */ export function linkChildParityRouteAllowed(url: URL, req: Request): boolean { return url.pathname === LINK_CHILD_PARITY_PATH && req.method === "POST" && url.search === "" && !req.headers.has("upgrade"); }