UNPKG

@bitkyc08/opencodex

Version:

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

231 lines (220 loc) • 12.9 kB
import { randomBytes } from "node:crypto"; import { parseStrictSemver } from "../lib/strict-semver"; import type { ChildObservation, ChildOperationSummary } from "./child-observations"; import { CHILD_JOB_SCHEMA, type ChildJob, type ChildJobItem, type ChildOp, type ChildOpsEnv, type ChildRestart, type ChildTrigger, type ItemOutcome, type ItemRunner } from "./child-ops-types"; import { runObserveItem, runRestartCodexItem, runSyncItem, runUpdateItem } from "./child-ops-runners"; import type { LinkRecord } from "./store"; export { CHILD_JOB_SCHEMA } from "./child-ops-types"; export const CHILD_OPS_CONCURRENCY = 3; /** Update items run one at a time across the engine; each also takes one of the CHILD_OPS_CONCURRENCY places. */ export const CHILD_OPS_UPDATE_CONCURRENCY = 1; export const CHILD_JOB_RETENTION_MS = 60 * 60 * 1000; export const CHILD_JOB_RETENTION_COUNT = 32; /** The CLI's job validator keeps strings up to this length; a longer hint would make the whole document unreadable. */ const HINT_MAX = 256; /** ignoreActivity (D8) is honoured only on a manual request; the route accepts it only with one link and a restart. */ export interface ChildOpRequest { op: ChildOp; linkIds: readonly string[] | "all"; restart: ChildRestart; trigger: ChildTrigger; ignoreActivity?: true } export type SubmitRefusal = "link_not_found" | "link_not_home_initiated" | "link_operation_in_progress" | "no_eligible_links"; export type SubmitResult = { ok: true; job: ChildJob } | { ok: false; code: SubmitRefusal; linkId: string | null }; export interface ChildJobHold { jobId: string; op: ChildOp; state: "queued" | "running" } export interface ChildOpsEngine { /** Synchronous admission: locks are taken before it returns, so a DELETE racing it sees them. */ submit(request: ChildOpRequest, env: ChildOpsEnv): SubmitResult; /** A structuredClone snapshot. */ job(jobId: string): ChildJob | undefined; activeJob(linkId: string): ChildJobHold | null; /** * Take the link's admission lock for a non-job holder (link removal). Returns null when a job holds the link; * otherwise a release function. While reserved, a single-link submit answers link_operation_in_progress and a * multi-link item for the link ends busy, exactly as for a link a job holds. Synchronous, like submit. */ reserve(linkId: string): (() => void) | null; /** Resolves with a clone of the finished job, or null when the id is unknown or already pruned (wp5 scheduler). */ whenDone(jobId: string): Promise<ChildJob | null>; /** Resolves once no job of this engine is queued or running. Tests and shutdown only. */ settled(): Promise<void>; } export interface ChildOpsEngineOptions { runners?: Partial<Record<ChildOp, ItemRunner>>; jobId?: () => string; /** Default and maximum CHILD_OPS_CONCURRENCY. */ concurrency?: number; } const DONE: ReadonlySet<string> = new Set(["succeeded", "up-to-date", "busy", "offline", "refused", "owner-action", "unsupported", "failed", "uncertain"]); const errorName = (error: unknown): string => error instanceof Error ? error.name : "unknown"; const iso = (env: ChildOpsEnv): string => new Date(env.now()).toISOString(); const strictVersion = (value: string | undefined): value is string => typeof value === "string" && value.length <= 128 && parseStrictSemver(value) !== null; /** 010's persisted slice; called after finishedAt is set. A version the cache would refuse ("unknown") is left out. */ export function summarize(job: ChildJob, item: ChildJobItem): ChildOperationSummary { return { op: job.op, jobId: job.jobId, state: item.state, reason: item.reason, finishedAt: item.finishedAt!, ...(strictVersion(item.fromVersion) ? { fromVersion: item.fromVersion } : {}), ...(strictVersion(item.toVersion) ? { toVersion: item.toVersion } : {}) }; } /** * The D11 job model: one in-memory registry, one lock per link per Home process, at most three items running across * every job and at most one of them an update, finished jobs kept one hour and at most 32. A Home restart loses the * jobs only; the observation cache keeps each Child's last result. Items carry closed tokens, never remote text. * No timers: retention is applied on each submit and read, on each job's own env clock. */ export function createChildOpsEngine(options: ChildOpsEngineOptions = {}): ChildOpsEngine { const runners: Record<ChildOp, ItemRunner> = { observe: runObserveItem, sync: runSyncItem, "restart-codex": runRestartCodexItem, update: runUpdateItem, ...options.runners }; const newJobId = options.jobId ?? (() => `ljob_${randomBytes(8).toString("hex")}`); const concurrency = Math.max(1, Math.min(options.concurrency ?? CHILD_OPS_CONCURRENCY, CHILD_OPS_CONCURRENCY)); const jobs = new Map<string, { job: ChildJob; env: ChildOpsEnv }>(); const locks = new Map<string, string>(); // linkId -> jobId const idle = new Set<() => void>(); // A running job is never pruned (prune drops done jobs only), so every waiter is resolved by finishJob. const waiters = new Map<string, Array<(job: ChildJob) => void>>(); // One engine-wide FIFO: the bound is on SSH sessions from this Home, not per job. const pending: Array<{ job: ChildJob; item: ChildJobItem; env: ChildOpsEnv }> = []; let active = 0; let activeUpdates = 0; let reservations = 0; const write = (env: ChildOpsEnv, linkId: string, patch: Partial<ChildObservation>): void => { try { env.writeObservation(linkId, patch); } catch (error) { // The env contract is "never throws"; this guards an env that breaks it. The job document carries the result. console.warn(`[link] child observation write failed linkId=${linkId} error=${errorName(error)}`); } }; const running = (): boolean => [...jobs.values()].some(({ job }) => job.state !== "done"); const prune = (): void => { const finished = [...jobs.values()].filter(({ job }) => job.state === "done"); for (const { job, env } of finished) if (Date.parse(job.finishedAt!) < env.now() - CHILD_JOB_RETENTION_MS) jobs.delete(job.jobId); const kept = finished.filter(({ job }) => jobs.has(job.jobId)).sort((a, b) => Date.parse(a.job.finishedAt!) - Date.parse(b.job.finishedAt!)); for (const { job } of kept.slice(0, Math.max(0, kept.length - CHILD_JOB_RETENTION_COUNT))) jobs.delete(job.jobId); }; /** ran = false: the item never touched its link (busy, child-initiated), so it writes no lastOperation. */ const finishItem = (job: ChildJob, item: ChildJobItem, env: ChildOpsEnv, outcome: ItemOutcome, ran = true): void => { Object.assign(item, outcome); if (item.hint !== undefined && item.hint.length > HINT_MAX) item.hint = item.hint.slice(0, HINT_MAX); item.finishedAt = iso(env); if (!ran) return; if (locks.get(item.linkId) === job.jobId) locks.delete(item.linkId); write(env, item.linkId, { lastOperation: summarize(job, item) }); }; const finishJob = (job: ChildJob, env: ChildOpsEnv): void => { if (job.state === "done" || job.items.some(item => item.state === "queued" || item.state === "running")) return; job.state = "done"; job.finishedAt = iso(env); const resolvers = waiters.get(job.jobId); if (resolvers) { waiters.delete(job.jobId); for (const resolve of resolvers) resolve(structuredClone(job)); } if (!running()) { for (const resolve of idle) resolve(); idle.clear(); } }; const runItem = async (job: ChildJob, item: ChildJobItem, env: ChildOpsEnv): Promise<void> => { item.state = "running"; item.startedAt = iso(env); if (job.state === "queued") job.state = "running"; let record: LinkRecord | undefined; try { record = env.readStore().links.find(link => link.id === item.linkId); } catch { record = undefined; } if (!record) { finishItem(job, item, env, { state: "refused", reason: "link-removed" }); return; } let outcome: ItemOutcome; try { outcome = await runners[job.op](record, job, env); } catch (error) { console.warn(`[link] child ${job.op} failed linkId=${item.linkId} error=${errorName(error)}`); outcome = { state: "failed", reason: "internal-error" }; } finishItem(job, item, env, DONE.has(outcome.state) ? outcome : { state: "failed", reason: "internal-error" }); }; const pump = (): void => { // FIFO across jobs; an update waiting for the update place does not hold up the items behind it. for (let index = 0; index < pending.length && active < concurrency;) { const entry = pending[index]!; const update = entry.job.op === "update"; if (update && activeUpdates >= CHILD_OPS_UPDATE_CONCURRENCY) { index += 1; continue; } pending.splice(index, 1); active += 1; if (update) activeUpdates += 1; void runItem(entry.job, entry.item, entry.env).finally(() => { active -= 1; if (update) activeUpdates -= 1; finishJob(entry.job, entry.env); pump(); }); } }; return { submit(request, env) { prune(); const store = env.readStore(); let records: LinkRecord[]; if (request.linkIds === "all") { records = store.links; if (records.length === 0) return { ok: false, code: "no_eligible_links", linkId: null }; } else { records = []; for (const linkId of request.linkIds) { const record = store.links.find(link => link.id === linkId); if (!record) return { ok: false, code: "link_not_found", linkId }; records.push(record); } const only = records.length === 1 ? records[0]! : null; // observe answers a client-initiated link itself without SSH (020); the other ops need the Home's SSH trust. if (only && request.op !== "observe" && only.direction === "client-initiated") return { ok: false, code: "link_not_home_initiated", linkId: only.id }; if (only && locks.has(only.id)) return { ok: false, code: "link_operation_in_progress", linkId: only.id }; } const job: ChildJob = { schema: CHILD_JOB_SCHEMA, jobId: newJobId(), op: request.op, trigger: request.trigger, restart: request.restart, ...(request.ignoreActivity === true && request.trigger === "manual" ? { ignoreActivity: true as const } : {}), state: "queued", createdAt: iso(env), finishedAt: null, items: records.map(record => ({ linkId: record.id, alias: record.alias, state: "queued" as const, reason: null, startedAt: null, finishedAt: null })) }; jobs.set(job.jobId, { job, env }); job.items.forEach((item, index) => { if (locks.has(item.linkId)) finishItem(job, item, env, { state: "busy", reason: "link-operation-in-progress" }, false); else if (request.op !== "observe" && records[index]!.direction === "client-initiated") { finishItem(job, item, env, { state: "unsupported", reason: "child-initiated" }, false); } else { locks.set(item.linkId, job.jobId); pending.push({ job, item, env }); } }); pump(); finishJob(job, env); return { ok: true, job: structuredClone(job) }; }, job(jobId) { prune(); const entry = jobs.get(jobId); return entry ? structuredClone(entry.job) : undefined; }, activeJob(linkId) { const jobId = locks.get(linkId); const job = jobId ? jobs.get(jobId)?.job : undefined; if (!job || job.state === "done") return null; return { jobId: job.jobId, op: job.op, state: job.state }; }, reserve(linkId) { if (locks.has(linkId)) return null; // Never a job id (those start ljob_), so activeJob reads null and no job finish releases it. const token = `reservation:${++reservations}`; locks.set(linkId, token); let released = false; return () => { if (released) return; released = true; if (locks.get(linkId) === token) locks.delete(linkId); }; }, whenDone(jobId) { const entry = jobs.get(jobId); if (!entry) return Promise.resolve(null); if (entry.job.state === "done") return Promise.resolve(structuredClone(entry.job)); return new Promise<ChildJob | null>(resolve => { const list = waiters.get(jobId) ?? []; list.push(resolve); waiters.set(jobId, list); }); }, settled() { if (!running()) return Promise.resolve(); return new Promise<void>(resolve => { idle.add(resolve); }); }, }; } let shared: ChildOpsEngine | null = null; /** One engine per Home process, shared by the routes (wp3) and the scheduler (wp5, wp7). */ export function sharedChildOpsEngine(): ChildOpsEngine { return shared ??= createChildOpsEngine(); } /** Tests that reach the routes through handleManagementAPI cannot set LinkRouteState.childOps; they await * sharedChildOpsEngine().settled() and call this in afterEach. Precedent: resetQuotaResetActivationForTests. */ export function resetSharedChildOpsEngineForTests(): void { shared = null; }