UNPKG

@bitkyc08/opencodex

Version:

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

219 lines (206 loc) • 14.6 kB
import { DEFAULT_IDLE_AFTER_MS, isLinkIdle } from "../../link/child-activity"; import { readChildPolicy, updateChildPolicy, validPolicyPatch } from "../../link/child-policy"; import { createCatalogRevisionMonitor, type CatalogRevisionMonitor } from "../../link/child-catalog-freshness"; import { observeChild } from "../../link/child-observe"; import { patchChildObservation, readChildObservations, updateChildObservations } from "../../link/child-observations"; import { sharedChildOpsEngine, type ChildOpsEngine, type SubmitRefusal, type SubmitResult } from "../../link/child-ops-engine"; import { CHILD_OPS, CHILD_OPS_MAX_LINK_IDS, type ChildOp, type ChildOpsEnv, type ChildRestart } from "../../link/child-ops-types"; import { requireRemotePlatform } from "../../link/remote-platform"; import { inspectRemoteChildRuntime } from "../../link/remote-plant"; import { attachLinkChildOps, projectLinkStatus, type LinkStatusDto } from "../../link/status-projection"; import type { LinkStore } from "../../link/store"; import { packageVersion } from "../../lib/package-version"; import { readCatalog, readCodexCatalogPath } from "../../codex/catalog"; import type { ManagementContext } from "./context"; import { readManagementJsonBodyOr } from "./body"; import { auth, fail, isRecord, knownHostsFile, readStoreFor, runnerFor, type LinkRouteState } from "./link-route-state"; const LINK_ID = /^lnk_[0-9a-f]{16}$/; const JOB_ID = /^ljob_[0-9a-f]{16}$/; const MAX_LINK_IDS = CHILD_OPS_MAX_LINK_IDS; const JOB_PATH = /^\/api\/link\/children\/jobs\/([^/]+)$/; const NO_STORE = { "cache-control": "no-store" }; let revisionMonitor: CatalogRevisionMonitor | undefined; /** * The production Home catalog revision: the exact bytes `/v1/catalog` serves, hashed like its etag, with the * revision persisted as `homeCatalog` in child-observations.json. Created lazily on the first `?children=1` read. */ export function catalogRevisionForRoutes(): CatalogRevisionMonitor { return revisionMonitor ??= createCatalogRevisionMonitor({ catalogPath: () => readCodexCatalogPath(), read: path => { const catalog = readCatalog(path); return catalog ? JSON.stringify(catalog) : null; }, load: () => readChildObservations().homeCatalog, persist: revision => { updateChildObservations(file => { file.homeCatalog = revision; }); }, }); } /** * One engine per Home process (Revision 5). wp2 kept one per route state, which link-routes.ts keys by the config * object, so a config reload started a second engine without the first one's locks, and the wp5 scheduler must submit * to the engine the routes read. state.childOps stays the seam a direct test can set. */ export function childOpsEngineFor(state: LinkRouteState): ChildOpsEngine { return state.childOps ??= sharedChildOpsEngine(); } const errorName = (error: unknown): string => error instanceof Error ? error.name : "unknown"; /** The env captures this request's seams for the job's lifetime; every read is live. wp5 passes the policy idleAfterMs. */ export function childOpsEnvFor(ctx: ManagementContext, state: LinkRouteState, idleAfterMs = DEFAULT_IDLE_AFTER_MS): ChildOpsEnv { const now = ctx.deps.now ?? Date.now; const runner = runnerFor(ctx); const hosts = knownHostsFile(ctx); const homeVersion = packageVersion("0.0.0"); return { readStore: () => readStoreFor(ctx), runner, knownHostsFile: hosts, homeVersion, now, // The wire state the status route reports, including a recorded compensation failure. wireState: linkId => { if (state.compensationFailures?.has(linkId)) return "failed"; return projectLinkStatus(readStoreFor(ctx), state.supervisor.status(), state.listener.status(), ctx.config) .links.find(link => link.id === linkId)?.state ?? null; }, activity: linkId => { const snapshot = state.listener.linkActivity?.(linkId, now()); return snapshot ? { inFlight: snapshot.inFlight, idle: isLinkIdle(snapshot, now(), idleAfterMs) } : null; }, sleep: ms => Bun.sleep(ms), // wp2's observe deps, unchanged: the peer and activity listeners are optional on LinkRouteListener. observe: record => observeChild(record, { runner, knownHostsFile: hosts, homeVersion, peer: linkId => state.listener.peerObservation?.(linkId) ?? { observed: null, refused: null }, platformOf: link => requireRemotePlatform(runner, link.alias, link.explicitRoute ?? null, hosts), inspect: inspectRemoteChildRuntime, now: () => new Date(now()) }), readObservation: linkId => readChildObservations().children[linkId] ?? null, // Never throws into a runner: a cache write failure is logged by error name (ChildOpsEnv contract). writeObservation: (linkId, patch) => { try { updateChildObservations(file => patchChildObservation(file, linkId, patch, new Date(now()))); } catch (error) { console.warn(`[link] child observation write failed linkId=${linkId} error=${errorName(error)}`); } }, // Revision 4: wp2's monitor on LinkRouteState.catalogRevision (catalogEtag hashing); null when the catalog cannot be read. catalogEtag: () => { try { return (state.catalogRevision ??= catalogRevisionForRoutes()).current()?.etag ?? null; } catch { return null; } }, }; } export interface ParsedOperation { op: ChildOp; linkIds: string[] | "all"; restart: ChildRestart; ignoreActivity?: true } /** * Exactly {op, linkIds, restart?}. A2 / M8: any request that carries a restart (sync with restart, or restart-codex, * whose restart defaults to app-server) must name its links; "all" is accepted only when restart is "none". * Scope (audit r2 R6): this rule binds this API route and the ocx link verbs only; ocx sync --restart-children (040) * and the automatic restart policy (050) select links themselves and apply the same run-time activity check. * No body can set trigger: the route always submits manual operations. ignoreActivity (D8, the operator's explicit * restart past activity) is accepted only as true, on a sync or restart-codex request with a restart and exactly one * link id; an update's own restart keeps the activity gate, so the flag is refused there. */ export function parseOperation(body: unknown): ParsedOperation | null { if (!isRecord(body) || Object.keys(body).some(key => key !== "op" && key !== "linkIds" && key !== "restart" && key !== "ignoreActivity")) return null; if (!(CHILD_OPS as readonly unknown[]).includes(body.op)) return null; const op = body.op as ChildOp; if (body.restart !== undefined && body.restart !== "app-server" && body.restart !== "codex") return null; if (body.restart !== undefined && op === "observe") return null; const restart: ChildRestart = op === "restart-codex" ? (body.restart as ChildRestart | undefined) ?? "app-server" : (body.restart as ChildRestart | undefined) ?? "none"; const ids = body.linkIds; let linkIds: string[] | "all"; if (ids === "all" && restart === "none") linkIds = "all"; else if (Array.isArray(ids) && ids.length >= 1 && ids.length <= MAX_LINK_IDS && ids.every(id => typeof id === "string" && LINK_ID.test(id)) && new Set(ids).size === ids.length) linkIds = [...ids as string[]]; else return null; if (body.ignoreActivity !== undefined && (body.ignoreActivity !== true || (op !== "sync" && op !== "restart-codex") || restart === "none" || linkIds === "all" || linkIds.length !== 1)) return null; return { op, linkIds, restart, ...(body.ignoreActivity === true ? { ignoreActivity: true as const } : {}) }; } function refusal(code: SubmitRefusal): Response { switch (code) { case "link_not_found": return fail(code, "The link was not found.", 404); case "link_not_home_initiated": return fail(code, "Only a Home-initiated link can be operated from this computer.", 409); case "link_operation_in_progress": return fail(code, "Another operation is running on this link.", 409); // Returned only when links.json has no link at all, so the message says exactly that. case "no_eligible_links": return fail(code, "This Home has no links.", 409); } } /** `?children=1` on a Home: attach every row's `child` block. Never fails on the cache or the revision save. */ export function attachLinkChildOpsForState(dto: LinkStatusDto, state: LinkRouteState, store: LinkStore, now: number = Date.now()): LinkStatusDto { // A pull inside the recorder's write window would otherwise reach the file only at the next pull or at shutdown. // Best effort: a lock failure is logged by the recorder and retried later; the status read never fails on it. state.listener.flushCatalogPulls?.(); const revision = (state.catalogRevision ??= catalogRevisionForRoutes()).current(); const observations = readChildObservations(); const known = new Set(store.links.map(link => link.id)); return attachLinkChildOps(dto, { // The policy threshold governs every idle decision (050 reconciliation item 5). homeVersion: packageVersion("0.0.0"), now, idleAfterMs: readChildPolicy().policy.idleAfterMs, revision, peerVersion: linkId => state.listener.peerObservation?.(linkId).observed?.version ?? null, observation: linkId => known.has(linkId) ? observations.children[linkId] ?? null : null, activity: linkId => state.listener.linkActivity?.(linkId, now) ?? null, catalogPull: linkId => state.listener.catalogPull?.(linkId) ?? null, // The shared engine: a job the wp5 scheduler started shows on a status read that never submitted one. activeJob: linkId => childOpsEngineFor(state).activeJob(linkId), // D8: present only on a row whose link WebSocket activity holds keep it in flight. holds: linkId => state.listener.linkHolds?.(linkId) ?? null, }); } /** * D8: the operator's clear of one link's WebSocket activity holds, including an unknown state left by a crash. Never * automatic. Exactly {linkId}; the link must exist in links.json. The holds file is written before anything is forgotten. */ async function clearActivityHolds(ctx: ManagementContext, state: LinkRouteState): Promise<Response> { if (ctx.config.runtimeRole === "client") return fail("runtime_role_client", "A Child runtime does not operate other Children.", 409); const body = await readManagementJsonBodyOr(ctx.req, null); if (!isRecord(body) || Object.keys(body).some(key => key !== "linkId") || typeof body.linkId !== "string" || !LINK_ID.test(body.linkId)) { return fail("invalid_body", "The body must be exactly {linkId}.", 400); } const linkId = body.linkId; let store: LinkStore; try { store = readStoreFor(ctx); } catch { return fail("link_unavailable", "The link store could not be read.", 503); } if (!store.links.some(link => link.id === linkId)) return fail("link_not_found", "The link was not found.", 404); // A listener without the hook cannot clear anything; answering "nothing held" would hide a wiring gap. if (!state.listener.clearLinkHolds) return fail("activity_holds_unavailable", "This Home cannot clear link activity holds.", 503); const result = state.listener.clearLinkHolds(linkId); if (!result.ok) { return result.reason === "links-unreadable" ? fail("link_unavailable", "The links could not be listed, so every link stays held; try again once links.json is readable.", 503) : fail("activity_holds_write_failed", "The activity holds could not be saved; nothing was cleared.", 503); } if (result.cleared) console.log(`[link] activity holds cleared by the operator linkId=${linkId} holds=${result.cleared.holds.length} unknown=${result.cleared.unknown ?? "none"}`); return Response.json({ linkId, cleared: result.cleared }, { headers: NO_STORE }); } export async function handleLinkChildOpsRoutes(ctx: ManagementContext, state: LinkRouteState): Promise<Response | null> { const { url, req } = ctx; const path = url.pathname; const denied = auth(ctx, "either"); if (denied) return denied; if (url.pathname === "/api/link/children/operations" && req.method === "POST") { if (ctx.config.runtimeRole === "client") return fail("runtime_role_client", "A Child runtime does not operate other Children.", 409); const operation = parseOperation(await readManagementJsonBodyOr(req, null)); if (!operation) return fail("invalid_body", "The body must be exactly {op, linkIds, restart?}; restart is app-server or codex and needs explicit linkIds.", 400); let result: SubmitResult; try { result = childOpsEngineFor(state).submit({ ...operation, trigger: "manual" }, childOpsEnvFor(ctx, state, readChildPolicy().policy.idleAfterMs)); } catch { return fail("link_unavailable", "The link store could not be read.", 503); } return result.ok ? Response.json({ job: result.job }, { status: 202, headers: NO_STORE }) : refusal(result.code); } // 050: the Child policy. The handler-wide auth above admits a dashboard session or the admin token on loopback. if (url.pathname === "/api/link/children/policy" && req.method === "GET") return Response.json(readChildPolicy(), { headers: NO_STORE }); if (url.pathname === "/api/link/children/policy" && req.method === "PUT") { // Same refusal as POST operations: a Child's policy file would govern nothing. if (ctx.config.runtimeRole === "client") return fail("runtime_role_client", "A Child runtime does not operate other Children.", 409); const body = await readManagementJsonBodyOr(req, null); const patch = isRecord(body) && Object.keys(body).length > 0 ? validPolicyPatch(body) : null; if (!patch) return fail("invalid_body", "Send one or more of catalogFanout, childCodexRestart, updates, idleAfterMs with valid values.", 400); try { return Response.json({ policy: updateChildPolicy(patch), warning: null }, { headers: NO_STORE }); } catch { return fail("policy_write_failed", "The Child policy could not be saved.", 503); } } // D8: the operator clears one link's WebSocket activity holds. if (url.pathname === "/api/link/children/activity/clear" && req.method === "POST") { return clearActivityHolds(ctx, state); } const jobPath = req.method === "GET" ? JOB_PATH.exec(path) : null; if (jobPath) { let jobId: string; try { jobId = decodeURIComponent(jobPath[1]!); } catch { return fail("invalid_job_id", "The job id is invalid.", 400); } if (!JOB_ID.test(jobId)) return fail("invalid_job_id", "The job id is invalid.", 400); const job = childOpsEngineFor(state).job(jobId); if (!job) return fail("job_not_found", "The job was not found.", 404); return Response.json({ job }, { headers: NO_STORE }); } return fail("not_found", "Not found.", 404); }