UNPKG

@bitkyc08/opencodex

Version:

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

208 lines (195 loc) • 10.9 kB
import type { ChildOpsEngine } from "./child-ops-engine"; import type { ChildJob, ChildOpsEnv } from "./child-ops-types"; import type { ChildPolicyRead } from "./child-policy"; /** * The Home's automatic catalog fan-out (050): after a Home catalog change settles, one no-restart sync job per pass for * every eligible Child through the shared Child-ops engine. Timers come from the host (unref'd); this module starts * none of its own, and nothing loads it on a Home without links (INV-LINK-CHILD-OPS-01). */ export const QUIET_PERIOD_MS = 60_000; export const QUIET_MAX_DEFER_MS = 300_000; export const CATALOG_POLL_MS = 300_000; export const BACKOFF_MIN_MS = 300_000; export const BACKOFF_MAX_MS = 21_600_000; /** States that grow the backoff for catalog fan-out; busy is retried at the next poll without growth. */ export const BACKOFF_STATES: ReadonlySet<string> = new Set(["failed", "offline", "uncertain", "refused", "unsupported"]); export const CATALOG_BACKOFF_KEY = "catalog"; export interface LinkBackoff { /** key: CATALOG_BACKOFF_KEY for fan-out; the target version for automatic updates (070). */ blocked(linkId: string, key: string, now: number, peerVersion: string | null): boolean; record(linkId: string, key: string, outcome: { state: string; reason: string | null }, now: number, peerVersion: string | null): void; /** Attempts recorded for (link, key) since its last success. 070 caps automatic update attempts with it. */ attempts(linkId: string, key: string): number; /** Last attempt for the link under any key; 070 rotates candidates by it (least recent first). */ lastAttemptAt(linkId: string): number | null; } /** legacy: a Child below 2.93 (lacks --expect-link). legacyAtVersion null means its version was not known yet. */ interface BackoffEntry { until: number; delayMs: number; attempts: number; legacy: boolean; legacyAtVersion: string | null } /** Per-link exponential backoff shared by the catalog fan-out (here) and the update sweep (070). Memory only. */ export function createLinkBackoff(options: { growOn?: ReadonlySet<string>; countOn?: ReadonlySet<string>; minMs?: number; maxMs?: number } = {}): LinkBackoff { const growOn = options.growOn ?? BACKOFF_STATES; // Revision 4 (4529522103): only these states count toward attempts(); absent ⇒ every non-success outcome counts. const countOn = options.countOn ?? null; const minMs = options.minMs ?? BACKOFF_MIN_MS, maxMs = options.maxMs ?? BACKOFF_MAX_MS; const entries = new Map<string, BackoffEntry>(); const last = new Map<string, number>(); const key = (linkId: string, name: string): string => `${linkId}\u0000${name}`; return { blocked(linkId, name, now, peerVersion) { const entry = entries.get(key(linkId, name)); if (!entry) return false; // A Child below 2.93 is retried only after it reports a different version (D6). Revision 4 (4529522058): with no // version known at the time, any reported version, or the end of the maxMs backoff, allows one retry. // #8557 review: once a version was recorded, a report without one is not "another version". if (entry.legacy) return entry.legacyAtVersion !== null ? peerVersion === null || peerVersion === entry.legacyAtVersion : peerVersion === null && now < entry.until; return now < entry.until; }, record(linkId, name, { state, reason }, now, peerVersion) { last.set(linkId, now); const k = key(linkId, name); const previous = entries.get(k); if (state === "succeeded" || state === "up-to-date") { entries.delete(k); return; } const attempts = (previous?.attempts ?? 0) + (countOn === null || countOn.has(state) ? 1 : 0); if (state === "owner-action" && reason === "child-ocx-lacks-expect-link") { entries.set(k, { until: peerVersion === null ? now + maxMs : Number.POSITIVE_INFINITY, delayMs: maxMs, attempts, legacy: true, legacyAtVersion: peerVersion }); return; } if (!growOn.has(state)) { entries.set(k, { until: now, delayMs: previous?.delayMs ?? 0, attempts, legacy: false, legacyAtVersion: null }); return; } const delayMs = previous && previous.delayMs > 0 ? Math.min(previous.delayMs * 2, maxMs) : minMs; entries.set(k, { until: now + delayMs, delayMs, attempts, legacy: false, legacyAtVersion: null }); }, attempts: (linkId, name) => entries.get(key(linkId, name))?.attempts ?? 0, lastAttemptAt: linkId => last.get(linkId) ?? null, }; } export interface ChildOpsSchedulerDeps { engine: ChildOpsEngine; env: () => ChildOpsEnv; readPolicy: () => ChildPolicyRead; revision: { current(): { etag: string | null; changedAt: number | null }; recompute(): Promise<boolean> }; /** Revision 4 (4529521968): 030's catalogSyncedEtag; a GET of /v1/catalog does not count as delivered. */ syncedEtag: (linkId: string) => string | null; /** codexSettingsDigest of the Home settings; null when they cannot be projected. */ homeDigest: () => string | null; /** The Child's parity report appliedCodexSettingsDigest. */ childDigest: (linkId: string) => string | null; /** The relay peer report's version. */ peerVersion: (linkId: string) => string | null; /** 050 Revision 6: a runtime whose runtimeRole is client operates no Children. */ isClientRuntime: () => boolean; setCatalogChangedSlot: (fanout: (() => void) | null) => void; setTimeout: (fn: () => void, ms: number) => unknown; clearTimeout: (handle: unknown) => void; setInterval: (fn: () => void, ms: number) => unknown; clearInterval: (handle: unknown) => void; /** Extension point for wp7; called once per poll after the catalog pass. Unset in wp5. */ afterPoll?: () => Promise<void>; } export interface ChildOpsScheduler { start(): void; stop(): void; notifyCatalogChanged(): void; /** Test seam: run one evaluation now and wait for the jobs it submitted. */ evaluateForTest(): Promise<ChildJob[]>; } export function createChildOpsScheduler(deps: ChildOpsSchedulerDeps): ChildOpsScheduler { const backoff = createLinkBackoff(); let quiet: unknown = null; let firstChangeAt: number | null = null; let poll: unknown = null; let running = false; let rerun = false; let stopped = true; // Etag equality, never time order (4529521959); an unreadable Home catalog makes no Child behind. const behind = (linkId: string): boolean => { const etag = deps.revision.current().etag; return etag !== null && deps.syncedEtag(linkId) !== etag; }; const record = (job: ChildJob, now: number): void => { for (const item of job.items) backoff.record(item.linkId, CATALOG_BACKOFF_KEY, item, now, deps.peerVersion(item.linkId)); }; const evaluate = async (): Promise<ChildJob[]> => { if (stopped || deps.isClientRuntime()) return []; // 050 Revision 6: a quiet timer that fires during a pass is not lost; the pass evaluates once more when it ends. if (running) { rerun = true; return []; } const { policy } = deps.readPolicy(); if (policy.catalogFanout !== "auto") return []; running = true; try { const env = deps.env(); const now = env.now(); const homeDigest = deps.homeDigest(); const plain: string[] = []; const withRestart: string[] = []; for (const link of env.readStore().links) { if (link.direction !== "hub-initiated" || env.wireState(link.id) !== "connected") continue; if (deps.engine.activeJob(link.id) || backoff.blocked(link.id, CATALOG_BACKOFF_KEY, now, deps.peerVersion(link.id)) || !behind(link.id)) continue; const idle = env.activity(link.id)?.idle === true; const sameSettings = homeDigest !== null && deps.childDigest(link.id) === homeDigest; // Digest rule (D6): a sync that applies changed settings restarts the Child's client runtime and cuts relayed // streams, so a busy Child is synced only when its settings already match. if (!idle && !sameSettings) continue; (idle && policy.childCodexRestart === "app-server-when-idle" ? withRestart : plain).push(link.id); } const jobs: ChildJob[] = []; for (const [ids, restart] of [[plain, "none"], [withRestart, "app-server"]] as const) { if (ids.length === 0) continue; // #8557 review: the first group's job can run for minutes. A stop() (listener closed, shutdown) or a policy // change in that time governs the next group, which is admitted against the policy as it is now. const current = deps.readPolicy().policy; if (stopped || deps.isClientRuntime() || current.catalogFanout !== "auto") break; const restartNow = restart === "app-server" && current.childCodexRestart === "app-server-when-idle" ? "app-server" : "none"; // submit reads links.json and can throw (the POST route maps that to 503); the next poll retries. let result: ReturnType<ChildOpsEngine["submit"]>; try { result = deps.engine.submit({ op: "sync", linkIds: [...ids], restart: restartNow, trigger: "auto" }, env); } catch { continue; } if (!result.ok) continue; // a single-link list held by a job or a reserve() answers link_operation_in_progress const done = await deps.engine.whenDone(result.job.jobId); if (done) { record(done, env.now()); jobs.push(done); } } return jobs; } finally { running = false; if (rerun) { rerun = false; if (!stopped) void evaluate().catch(() => []); } } }; const armQuiet = (): void => { if (stopped) return; const now = deps.env().now(); firstChangeAt ??= now; if (quiet !== null) deps.clearTimeout(quiet); const wait = Math.min(QUIET_PERIOD_MS, Math.max(0, firstChangeAt + QUIET_MAX_DEFER_MS - now)); quiet = deps.setTimeout(() => { quiet = null; firstChangeAt = null; void evaluate().catch(() => []); }, wait); }; const onPoll = async (): Promise<void> => { let changed = false; try { changed = await deps.revision.recompute(); } catch { /* next poll */ } if (changed) armQuiet(); else if (quiet === null) await evaluate().catch(() => []); // retries idle-blocked and backed-off links await deps.afterPoll?.().catch(() => {}); }; return { start() { if (!stopped) return; stopped = false; deps.setCatalogChangedSlot(() => armQuiet()); poll = deps.setInterval(() => { void onPoll(); }, CATALOG_POLL_MS); // A Home restarted after a change still owes its Children a sync. void deps.revision.recompute().catch(() => false).then(() => armQuiet()); }, stop() { if (stopped) return; stopped = true; deps.setCatalogChangedSlot(null); if (quiet !== null) deps.clearTimeout(quiet); if (poll !== null) deps.clearInterval(poll); quiet = poll = null; firstChangeAt = null; rerun = false; }, notifyCatalogChanged: armQuiet, evaluateForTest: evaluate, }; }