@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
144 lines (135 loc) • 10.5 kB
text/typescript
import type { LinkRecord, LinkStore } from "../link/store";
import type { ChildRestartRequest } from "../link/ssh-argv";
import type { SyncThenRestart } from "../link/sync-then-restart";
import type { LinkStatusPayload } from "./link";
import { LinkStatusError } from "./sync-link-status";
import { childSkipHint } from "../link/sync-fanout-classify";
export { classifySyncResult, classifyVersionProbe, parseOcxVersion, REMOTE_LINK_SYNC_MESSAGE,
STALE_REMOTE_CATALOG_MESSAGE, type ChildVerdict } from "../link/sync-fanout-classify";
export const SYNC_FANOUT_PARTIAL_EXIT = 6;
export type HomeResult = { state: "synced" | "stale" | "skipped" | "failed"; exit: number };
export type ChildResult = { linkId: string; alias: string; state: "synced" | "skipped" | "failed" | "timed-out"; reason: string | null; exit: number | null; hint?: string };
export type FanoutDocument = { schema: "ocx.sync.fanout/1"; home: HomeResult; fanout: { state: "ran" | "disabled" | "not-applicable" | "failed"; reason: string | null }; children: ChildResult[] };
/** The reason on a synced row whose requested restart did not certainly happen (040 decision 1). Each one exits 6. */
export type RestartNote = "restart-skipped:link-active" | "restart-skipped:activity-unknown" | "restart-skipped:windows"
| "restart-unsupported:ocx-child" | "restart-not-run" | "restart-result-unknown";
/** readActivity: a fresh status read for this link; null when unknown (D5: unknown is never idle). */
export type ChildRunOptions = { restart?: ChildRestartRequest; readActivity: () => Promise<{ inFlight: number } | null> };
export async function runHomeFanout(deps: {
home: HomeResult; catalogCurrent: boolean; localOnly?: boolean; applicable?: boolean;
/** null or absent: every link. Otherwise only these ids run; the rest read skipped/not-selected. */
selected?: ReadonlySet<string> | null;
restartChildren?: ChildRestartRequest | null;
readStore: () => LinkStore; readLinkStatus: () => Promise<LinkStatusPayload>;
runChild: (link: LinkRecord, deadline: number, options: ChildRunOptions) => Promise<Omit<ChildResult, "linkId" | "alias">>;
now?: () => number; deadlineMs?: number; concurrency?: number; terminationGraceMs?: number;
}): Promise<FanoutDocument> {
const result: FanoutDocument = { schema: "ocx.sync.fanout/1", home: deps.home, fanout: { state: deps.localOnly ? "disabled" : "not-applicable", reason: null }, children: [] };
if (deps.localOnly || deps.applicable === false) return result;
let store: LinkStore;
try { store = deps.readStore(); } catch { result.fanout = { state: "failed", reason: "link-store-unreadable" }; return result; }
if (!store.links.length) return result;
result.fanout.state = "ran";
const classify = (link: LinkRecord, state: ChildResult["state"], reason: string | null, exit: number | null = null): ChildResult => ({ linkId: link.id, alias: link.alias, state, reason, exit });
// Revision 6: selection is applied first in every branch, so an unselected link always reads not-selected.
const unselected = (link: LinkRecord): boolean => deps.selected != null && !deps.selected.has(link.id);
const rowFor = (link: LinkRecord, state: ChildResult["state"], reason: string | null): ChildResult =>
unselected(link) ? classify(link, "skipped", "not-selected") : classify(link, state, reason);
result.children = store.links.map(link => rowFor(link, "skipped", link.direction === "client-initiated" ? "client-initiated-link" : "home-catalog-not-current"));
const skipReason = deps.home.state === "failed" || deps.home.exit !== 0 ? "home-sync-failed" : deps.home.state === "skipped" ? "home-sync-skipped" : !deps.catalogCurrent ? "home-catalog-not-current" : null;
if (skipReason) {
result.children = store.links.map(link => rowFor(link, "skipped", link.direction === "client-initiated" ? "client-initiated-link" : skipReason));
return result;
}
let status: LinkStatusPayload;
try { status = await deps.readLinkStatus(); }
catch (error) {
const reason = error instanceof LinkStatusError ? error.reason : "home-link-status-unavailable";
result.children = store.links.map(link => link.direction === "client-initiated" ? rowFor(link, "skipped", "client-initiated-link") : rowFor(link, reason === "home-runtime-not-running" ? "skipped" : "failed", reason));
return result;
}
let cursor = 0;
const workers = Array.from({ length: Math.max(1, Math.min(Math.floor(deps.concurrency ?? 3), 3, store.links.length)) }, async () => {
for (;;) {
const index = cursor++;
const link = store.links[index];
if (!link) return;
if (unselected(link) || link.direction === "client-initiated") continue;
const wire = status.links.find(row => row.id === link.id);
if (!wire) { result.children[index] = classify(link, "skipped", "link-not-in-runtime"); continue; }
if (wire.state !== "connected") { result.children[index] = classify(link, "skipped", `tunnel-${wire.state}`); continue; }
// A Child operation (wp2/wp3 job) holds this Child: an intentional skip, no hint, no exit 6.
if (wire.child?.activeJob) { result.children[index] = classify(link, "skipped", "child-busy"); continue; }
// Decision 3 / 4529522035: a fresh read per Child, never the first one; a failed read or a row without child is unknown.
let unknownCause: ActivityUnknownCause = "read-failed";
const readActivity = async (): Promise<{ inFlight: number } | null> => {
let fresh: LinkStatusPayload;
try { fresh = await deps.readLinkStatus(); } catch { unknownCause = "read-failed"; return null; }
const row = fresh.links.find(candidate => candidate.id === link.id);
if (!row) { unknownCause = "read-failed"; return null; }
if (!row.child) { unknownCause = "absent"; return null; }
return row.child.activity;
};
const options: ChildRunOptions = deps.restartChildren ? { restart: deps.restartChildren, readActivity } : { readActivity };
let timer: ReturnType<typeof setTimeout> | undefined;
try {
const budget = deps.deadlineMs ?? 180_000;
const child = await Promise.race([
deps.runChild(link, (deps.now ?? Date.now)() + budget, options),
new Promise<Omit<ChildResult, "linkId" | "alias">>(resolve => {
timer = setTimeout(() => resolve({ state: "timed-out", reason: "termination-unconfirmed", exit: null }), budget + (deps.terminationGraceMs ?? 3000));
}),
]);
// Build the row from the schema's own fields, so an extra key on a runner's result never reaches ocx.sync.fanout/1.
const hint = child.state === "skipped" ? childSkipHint(child.reason, link.alias)
: child.state === "synced" && child.reason?.startsWith("restart-") ? childRestartHint(child.reason, link, deps.restartChildren ?? "app-server", unknownCause) : child.hint;
result.children[index] = { linkId: link.id, alias: link.alias, state: child.state, reason: child.reason, exit: child.exit, ...(hint === undefined ? {} : { hint }) };
} catch { result.children[index] = classify(link, "failed", "internal-error"); }
finally { if (timer !== undefined) clearTimeout(timer); }
}
});
await Promise.all(workers);
return result;
}
/** Maps the shared sequence's result to a synced row's reason; null keeps the row as the sync reported it. */
export function restartNote(done: SyncThenRestart<{ state: string; reason: string | null }>): RestartNote | null {
if (!done.restart) return null;
// Reached only after a successful plain sync; done.sync is then the restarting sync's verdict.
if (done.restartUnknown) return "restart-result-unknown";
// Any failed plain sync keeps its own row, including on Windows or ocx-child (those are checked first).
if (done.sync.state !== "synced") return null;
switch (done.withheld) {
case undefined: case "sync-failed": return null;
case "platform": return "restart-skipped:windows";
case "ocx-child": return "restart-unsupported:ocx-child";
case "activity-unknown": return "restart-skipped:activity-unknown";
case "link-active": return "restart-skipped:link-active";
case "second-not-run": return "restart-not-run";
}
}
type ActivityUnknownCause = "absent" | "read-failed";
function childRestartHint(reason: string, link: LinkRecord, restart: ChildRestartRequest, cause: ActivityUnknownCause): string | undefined {
const retry = `ocx sync --child ${link.id} --restart-children${restart === "codex" ? "=codex --yes" : ""}`;
switch (reason as RestartNote) {
case "restart-skipped:link-active": return `A model request was running on ${link.alias}; its Codex was not restarted. Retry when it is idle: ${retry}.`;
case "restart-skipped:activity-unknown": return cause === "absent"
? `This Home's OpenCodex runtime did not report ${link.alias}'s activity; restart or update it, then retry ${retry}.`
: `The Home could not read ${link.alias}'s activity (the status read failed or timed out); retry ${retry}.`;
case "restart-skipped:windows": return "Codex restarts over SSH are not supported on Windows Children; restart Codex on that machine.";
case "restart-unsupported:ocx-child": return "ocx-child does not restart Codex; restart the Codex app or its app-servers on that machine.";
case "restart-not-run": return `The restart was not sent to ${link.alias}; check its sync status and retry ${retry}.`;
case "restart-result-unknown": return `The restart was sent to ${link.alias} but its result is unknown; check Codex on that machine.`;
default: return undefined;
}
}
export function fanoutExitCode(document: FanoutDocument): number {
if (document.home.exit !== 0) return document.home.exit;
return document.fanout.state === "failed" || document.children.some(child => child.state === "failed" || child.state === "timed-out"
|| (child.state === "skipped" && child.hint !== undefined)
// A requested restart that did not certainly happen (040 decision 2).
|| (child.state === "synced" && child.reason?.startsWith("restart-") === true)) ? SYNC_FANOUT_PARTIAL_EXIT : 0;
}
export function renderFanoutJson(document: FanoutDocument): string { return JSON.stringify(document); }
export function renderFanoutHuman(document: FanoutDocument): string[] {
return document.children.map(child => `${child.alias} (${child.linkId}): ${child.state}${child.reason ? ` (${child.reason})` : ""}${child.hint ? ` — ${child.hint}` : ""}`);
}