rich-parallel-agents 0.1.0

package/dist/git.js

@@ -0,0 +1,64 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { GateError } from "./errors.js";
+const execFileAsync = promisify(execFile);
+export async function snapshot(cwd) {
+    let inside = "";
+    try {
+        inside = (await git(cwd, ["rev-parse", "--is-inside-work-tree"])).trim();
+    }
+    catch {
+        throw new GateError(`not a git worktree: ${cwd}`);
+    }
+    if (inside !== "true") {
+        throw new GateError(`not a git worktree: ${cwd}`);
+    }
+    let headSha;
+    try {
+        headSha = (await git(cwd, ["rev-parse", "HEAD"])).trim();
+    }
+    catch {
+        headSha = undefined;
+    }
+    const porcelain = (await git(cwd, ["status", "--porcelain"])).trim();
+    return { headSha, dirty: porcelain.length > 0 };
+}
+export async function currentSha(cwd) {
+    return (await git(cwd, ["rev-parse", "HEAD"])).trim();
+}
+export async function fetchSha(into, from, sha) {
+    try {
+        await git(into, ["fetch", "--no-tags", from, sha]);
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: gitError(err) };
+    }
+}
+export async function mergeCommit(into, sha, message) {
+    try {
+        await git(into, ["merge", "--no-edit", "-m", message, sha]);
+        return { ok: true };
+    }
+    catch (err) {
+        const text = gitError(err);
+        const conflict = /CONFLICT|Automatic merge failed|Merge conflict|fix conflicts/i.test(text);
+        await git(into, ["merge", "--abort"]).catch(() => undefined);
+        return { ok: false, conflict, error: text };
+    }
+}
+async function git(cwd, args) {
+    const { stdout } = await execFileAsync("git", ["-C", cwd, ...args], {
+        encoding: "utf8",
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    return stdout;
+}
+function gitError(err) {
+    if (err && typeof err === "object") {
+        const rec = err;
+        const combined = [rec.stderr, rec.stdout].filter(Boolean).join("\n").trim();
+        return combined || (rec.message || String(err)).trim();
+    }
+    return String(err);
+}

package/dist/history.d.ts

@@ -0,0 +1,27 @@
+import type { ErrorClass, JournalEvent, RunState } from "./types.js";
+export type HistoryRow = {
+    runId: string;
+    status: string;
+    createdAt: string;
+    tasks: number;
+    attempts: number;
+    retries: number;
+    errorClass?: ErrorClass;
+};
+export type HistoryStats = {
+    runs: number;
+    success: number;
+    failed: number;
+    attempts: number;
+    retries: number;
+    byErrorClass: Record<string, number>;
+    byStatus: Record<string, number>;
+};
+export declare function listRunIds(storeDir: string): Promise<string[]>;
+export declare function loadHistory(storeDir: string): Promise<{
+    rows: HistoryRow[];
+    events: JournalEvent[];
+}>;
+export declare function summarizeHistory(rows: HistoryRow[]): HistoryStats;
+export declare function formatHistory(rows: HistoryRow[], stats?: boolean, byType?: boolean): string;
+export declare function formatReport(run: RunState): string;

package/dist/history.js

@@ -0,0 +1,106 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { readEvents } from "./journal.js";
+import { loadRun } from "./store.js";
+export async function listRunIds(storeDir) {
+    try {
+        const dir = path.join(storeDir, "runs");
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+    }
+    catch {
+        return [];
+    }
+}
+export async function loadHistory(storeDir) {
+    const ids = await listRunIds(storeDir);
+    const rows = [];
+    const events = [];
+    for (const id of ids) {
+        let run;
+        try {
+            run = await loadRun(storeDir, id);
+        }
+        catch {
+            continue;
+        }
+        const runEvents = await readEvents(storeDir, id);
+        events.push(...runEvents);
+        const attempts = Object.values(run.tasks).reduce((sum, task) => sum + task.attempts.length, 0);
+        const retries = Math.max(0, attempts - Object.values(run.tasks).length);
+        const errorClass = Object.values(run.tasks)
+            .map((task) => task.errorClass)
+            .find((value) => value);
+        rows.push({
+            runId: run.id,
+            status: run.status,
+            createdAt: run.createdAt,
+            tasks: Object.keys(run.tasks).length,
+            attempts,
+            retries,
+            errorClass,
+        });
+    }
+    return { rows, events };
+}
+export function summarizeHistory(rows) {
+    const byErrorClass = {};
+    const byStatus = {};
+    for (const row of rows) {
+        byStatus[row.status] = (byStatus[row.status] ?? 0) + 1;
+        if (row.errorClass)
+            byErrorClass[row.errorClass] = (byErrorClass[row.errorClass] ?? 0) + 1;
+    }
+    return {
+        runs: rows.length,
+        success: rows.filter((row) => row.status === "success").length,
+        failed: rows.filter((row) => row.status === "failed").length,
+        attempts: rows.reduce((sum, row) => sum + row.attempts, 0),
+        retries: rows.reduce((sum, row) => sum + row.retries, 0),
+        byErrorClass,
+        byStatus,
+    };
+}
+export function formatHistory(rows, stats = false, byType = false) {
+    if (rows.length === 0)
+        return "no runs";
+    if (stats || byType) {
+        const summary = summarizeHistory(rows);
+        const lines = [
+            `runs ${summary.runs}  success ${summary.success}  failed ${summary.failed}`,
+            `attempts ${summary.attempts}  retries ${summary.retries}`,
+        ];
+        const classes = Object.entries(summary.byErrorClass);
+        if (classes.length) {
+            lines.push("by error class:");
+            for (const [name, count] of classes)
+                lines.push(`  ${name}  ${count}`);
+        }
+        lines.push("by status:");
+        for (const [name, count] of Object.entries(summary.byStatus)) {
+            lines.push(`  ${name}  ${count}`);
+        }
+        return lines.join("\n");
+    }
+    return rows
+        .map((row) => `${row.runId}  ${row.status}  tasks=${row.tasks}  attempts=${row.attempts}  retries=${row.retries}${row.errorClass ? `  ${row.errorClass}` : ""}`)
+        .join("\n");
+}
+export function formatReport(run) {
+    const tasks = Object.values(run.tasks);
+    const accepted = tasks.filter((task) => task.status === "accepted" || task.status === "integrated").length;
+    const blocked = tasks.filter((task) => task.status === "blocked").length;
+    const lines = [
+        `run ${run.id}  ${run.status}`,
+        `repo ${run.repo}`,
+        `tasks ${tasks.length}  accepted/integrated ${accepted}  blocked ${blocked}`,
+    ];
+    if (run.objective)
+        lines.push(`objective ${run.objective}`);
+    if (run.integration)
+        lines.push(`integration ${run.integration.status}`);
+    for (const task of tasks) {
+        lines.push(`  ${task.id}  ${task.status}${task.errorClass ? `  ${task.errorClass}` : ""}${task.lastError ? `  ${task.lastError}` : ""}`);
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export { parseConfig, loadConfig, DEFAULT_CONFIG, commandAsCheck } from "./config.js";
+export { GateError } from "./errors.js";
+export { execCommand } from "./exec.js";
+export { formatRun, formatTask, formatCheck, toJson } from "./format.js";
+export { claimTask, verifyTask, verifyAll, retryTask, deriveRunStatus, refreshRunStatus, isMergeFailure, } from "./gate.js";
+export { integrateAccepted } from "./integrate.js";
+export { startOrcaRetry, startOrcaWorker, startOrcaRepair, worktreeSelector, } from "./orca.js";
+export { createRun, loadRun, saveRun, persist, resolveStoreDir } from "./store.js";
+export { runChecks, verifyPassed, requiredFailed } from "./verify.js";
+export { classifyFailure, shouldBlockWithoutRetry } from "./classify.js";
+export { decomposeObjective, applyPlan, loadPlanFile } from "./plan.js";
+export { prepareRun } from "./run.js";
+export { resumeRun } from "./resume.js";
+export { cleanRun } from "./clean.js";
+export { startIntegrationRepair, createRepairTask } from "./repair.js";
+export { loadHistory, formatHistory, formatReport } from "./history.js";
+export { appendEvent, readEvents } from "./journal.js";
+export { readSkill, installSkill } from "./skill.js";
+export type { Attempt, CheckResult, ExecFn, IntegrationState, RpaConfig, RunState, TaskState, VerifyCheck, WorkerOutcome, ErrorClass, Plan, JournalEvent, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,18 @@
+export { parseConfig, loadConfig, DEFAULT_CONFIG, commandAsCheck } from "./config.js";
+export { GateError } from "./errors.js";
+export { execCommand } from "./exec.js";
+export { formatRun, formatTask, formatCheck, toJson } from "./format.js";
+export { claimTask, verifyTask, verifyAll, retryTask, deriveRunStatus, refreshRunStatus, isMergeFailure, } from "./gate.js";
+export { integrateAccepted } from "./integrate.js";
+export { startOrcaRetry, startOrcaWorker, startOrcaRepair, worktreeSelector, } from "./orca.js";
+export { createRun, loadRun, saveRun, persist, resolveStoreDir } from "./store.js";
+export { runChecks, verifyPassed, requiredFailed } from "./verify.js";
+export { classifyFailure, shouldBlockWithoutRetry } from "./classify.js";
+export { decomposeObjective, applyPlan, loadPlanFile } from "./plan.js";
+export { prepareRun } from "./run.js";
+export { resumeRun } from "./resume.js";
+export { cleanRun } from "./clean.js";
+export { startIntegrationRepair, createRepairTask } from "./repair.js";
+export { loadHistory, formatHistory, formatReport } from "./history.js";
+export { appendEvent, readEvents } from "./journal.js";
+export { readSkill, installSkill } from "./skill.js";

package/dist/integrate.d.ts

@@ -0,0 +1,6 @@
+import type { ExecFn, RunState } from "./types.js";
+export declare function integrateAccepted(run: RunState, opts: {
+    into: string;
+    exec: ExecFn;
+    cwd?: string;
+}): Promise<RunState>;

package/dist/integrate.js

@@ -0,0 +1,185 @@
+import path from "node:path";
+import { GateError } from "./errors.js";
+import { isMergeFailure, refreshRunStatus, requireTask } from "./gate.js";
+import { fetchSha, mergeCommit, snapshot } from "./git.js";
+import { runChecks, verifyPassed } from "./verify.js";
+export async function integrateAccepted(run, opts) {
+    const into = path.resolve(opts.cwd ?? process.cwd(), opts.into);
+    const accepted = Object.values(run.tasks).filter((task) => task.status === "accepted");
+    if (accepted.length === 0) {
+        if (run.integration?.status === "failed" && run.integration.headSha) {
+            if (run.integration.into !== into) {
+                throw new GateError(`integration verification rerun target changed: expected ${run.integration.into}, got ${into}`);
+            }
+            const target = await requireCleanTarget(into);
+            if (target.headSha !== run.integration.headSha) {
+                throw new GateError(`integration verification rerun HEAD changed: expected ${run.integration.headSha}, got ${target.headSha ?? "no HEAD"}`);
+            }
+            return verifyIntegration(run, into, opts.exec);
+        }
+        throw new GateError("no accepted tasks to integrate");
+    }
+    const dirty = accepted.filter((task) => task.dirty);
+    if (dirty.length > 0) {
+        throw new GateError(`accepted task(s) have uncommitted changes; commit before integrate: ${dirty
+            .map((task) => task.id)
+            .join(", ")}`);
+    }
+    const missingSha = accepted.filter((task) => !task.headSha);
+    if (missingSha.length > 0) {
+        throw new GateError(`accepted task(s) have no git HEAD to merge: ${missingSha.map((task) => task.id).join(", ")}`);
+    }
+    const initial = await requireCleanTarget(into);
+    const baseSha = initial.headSha;
+    run.integration = {
+        into,
+        status: "merging",
+        baseSha,
+        mergedTaskIds: run.integration?.mergedTaskIds ?? [],
+        checks: [],
+    };
+    for (const task of accepted) {
+        try {
+            await requireCleanTarget(into);
+            await mergeTask(run, task, into);
+        }
+        catch (err) {
+            run.integration.status = "failed";
+            run.integration.error = `integration execution failed for ${task.id}: ${errorMessage(err)}`;
+            refreshRunStatus(run);
+            return run;
+        }
+        if (run.integration.status === "conflict") {
+            refreshRunStatus(run);
+            return run;
+        }
+        if (run.integration.status === "failed") {
+            refreshRunStatus(run);
+            return run;
+        }
+    }
+    const merged = Object.values(run.tasks).filter((task) => task.status === "integrated");
+    const mergeBlocked = Object.values(run.tasks).filter((task) => task.status === "blocked" && isMergeFailure(task));
+    if (mergeBlocked.some((task) => (task.lastError ?? "").startsWith("merge conflict"))) {
+        run.integration.status = "conflict";
+        run.integration.error ??= mergeBlocked[0]?.lastError ?? "merge conflict";
+        refreshRunStatus(run);
+        return run;
+    }
+    if (mergeBlocked.length > 0 || merged.length === 0) {
+        run.integration.status = "failed";
+        run.integration.error ??= mergeBlocked[0]?.lastError ?? "no accepted tasks could be merged";
+        refreshRunStatus(run);
+        return run;
+    }
+    try {
+        const mergedTarget = await snapshot(into);
+        run.integration.headSha = mergedTarget.headSha;
+        if (mergedTarget.dirty) {
+            throw new GateError(`integration worktree has uncommitted changes: ${into}`);
+        }
+        if (!mergedTarget.headSha) {
+            throw new GateError(`integration worktree has no HEAD after merge: ${into}`);
+        }
+    }
+    catch (err) {
+        run.integration.status = "failed";
+        run.integration.error = `could not record clean integration HEAD: ${errorMessage(err)}`;
+        refreshRunStatus(run);
+        return run;
+    }
+    return verifyIntegration(run, into, opts.exec);
+}
+async function verifyIntegration(run, into, exec) {
+    const integration = run.integration;
+    if (!integration?.headSha) {
+        throw new GateError("integration has no recorded HEAD to verify");
+    }
+    const expectedHead = integration.headSha;
+    const checks = run.config.verify.integration;
+    integration.status = "verifying";
+    integration.checks = [];
+    try {
+        const results = await runChecks(checks, into, exec, {
+            config: run.config,
+            extra: { cwd: into, base: integration.baseSha ?? "", head: expectedHead },
+        });
+        integration.checks = results;
+        const after = await snapshot(into);
+        if (after.dirty || after.headSha !== expectedHead) {
+            integration.status = "failed";
+            integration.error = after.dirty
+                ? `integration target became dirty during verification: ${into}`
+                : `integration HEAD changed during verification: expected ${expectedHead}, got ${after.headSha ?? "no HEAD"}`;
+        }
+        else if (verifyPassed(results)) {
+            integration.status = "passed";
+            integration.error = undefined;
+        }
+        else {
+            const failed = results.find((check) => check.required && !check.passed);
+            integration.status = "failed";
+            integration.error = failed
+                ? failed.timedOut
+                    ? `${failed.name} timed out`
+                    : `${failed.name} failed (exit ${failed.exitCode})`
+                : "integration verify failed";
+        }
+    }
+    catch (err) {
+        integration.status = "failed";
+        integration.error = `integration verification execution failed: ${errorMessage(err)}`;
+    }
+    refreshRunStatus(run);
+    return run;
+}
+async function mergeTask(run, task, into) {
+    requireTask(run, task.id);
+    const fetched = await fetchSha(into, task.worktree, task.headSha);
+    if (!fetched.ok) {
+        task.status = "blocked";
+        task.errorClass = "unknown";
+        task.lastError = `merge failed: fetch failed for ${task.id} from ${task.worktree}: ${fetched.error}`;
+        if (run.integration) {
+            run.integration.status = "failed";
+            run.integration.error = task.lastError;
+        }
+        return;
+    }
+    await requireCleanTarget(into);
+    const result = await mergeCommit(into, task.headSha, `rpa: integrate ${task.id}`);
+    if (!result.ok) {
+        task.status = "blocked";
+        task.errorClass = result.conflict ? "merge_conflict" : "unknown";
+        task.lastError = result.conflict
+            ? `merge conflict into ${into}`
+            : `merge failed: ${result.error}`;
+        if (run.integration) {
+            run.integration.error = task.lastError;
+            if (result.conflict)
+                run.integration.status = "conflict";
+        }
+        return;
+    }
+    task.status = "integrated";
+    task.lastError = undefined;
+    if (run.integration && !run.integration.mergedTaskIds.includes(task.id)) {
+        run.integration.mergedTaskIds.push(task.id);
+    }
+}
+async function requireCleanTarget(into) {
+    let target;
+    try {
+        target = await snapshot(into);
+    }
+    catch (err) {
+        throw new GateError(`integration worktree is not a git repo: ${into} (${errorMessage(err)})`);
+    }
+    if (target.dirty) {
+        throw new GateError(`integration worktree has uncommitted changes: ${into}`);
+    }
+    return target;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/journal.d.ts

@@ -0,0 +1,10 @@
+import type { EventType, JournalEvent } from "./types.js";
+export declare function eventsPath(storeDir: string, runId: string): string;
+export declare function appendEvent(storeDir: string, input: {
+    runId: string;
+    type: EventType;
+    taskId?: string;
+    attemptId?: string;
+    payload?: Record<string, unknown>;
+}): Promise<JournalEvent>;
+export declare function readEvents(storeDir: string, runId: string): Promise<JournalEvent[]>;

package/dist/journal.js

@@ -0,0 +1,34 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+export function eventsPath(storeDir, runId) {
+    return path.join(storeDir, "runs", runId, "events.jsonl");
+}
+export async function appendEvent(storeDir, input) {
+    const existing = await readEvents(storeDir, input.runId);
+    const event = {
+        id: existing.length + 1,
+        runId: input.runId,
+        taskId: input.taskId,
+        attemptId: input.attemptId,
+        type: input.type,
+        payload: input.payload ?? {},
+        createdAt: new Date().toISOString(),
+    };
+    const dir = path.dirname(eventsPath(storeDir, input.runId));
+    await mkdir(dir, { recursive: true });
+    await appendFile(eventsPath(storeDir, input.runId), `${JSON.stringify(event)}\n`, "utf8");
+    return event;
+}
+export async function readEvents(storeDir, runId) {
+    try {
+        const raw = await readFile(eventsPath(storeDir, runId), "utf8");
+        return raw
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/orca.d.ts

@@ -0,0 +1,16 @@
+import type { TaskState } from "./types.js";
+export type OrcaExec = (args: string[]) => Promise<string>;
+export type OrcaOpts = {
+    orcaBin?: string;
+    exec?: OrcaExec;
+};
+export declare function worktreeSelector(worktree: string): string;
+export declare function startOrcaRetry(task: TaskState, opts?: OrcaOpts): Promise<string>;
+export declare function startOrcaWorker(task: TaskState, opts?: OrcaOpts): Promise<string>;
+export declare function createOrcaTask(task: TaskState, opts?: OrcaOpts): Promise<string>;
+export declare function startOrcaRepair(task: TaskState, fromIds: string[], opts?: OrcaOpts): Promise<string>;
+export declare function createOrcaRun(objective: string, opts?: OrcaOpts): Promise<string>;
+export declare function listOrcaWorkers(opts?: OrcaOpts): Promise<string>;
+export declare function showOrcaWorker(dispatchId: string, opts?: OrcaOpts): Promise<string>;
+export declare function removeOrcaWorktree(selector: string, opts?: OrcaOpts): Promise<string>;
+export declare function orca(args: string[], opts?: OrcaOpts): Promise<string>;

package/dist/orca.js

@@ -0,0 +1,168 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { GateError } from "./errors.js";
+const execFileAsync = promisify(execFile);
+export function worktreeSelector(worktree) {
+    if (worktree === "current" ||
+        worktree === "active" ||
+        worktree.startsWith("id:") ||
+        worktree.startsWith("name:") ||
+        worktree.startsWith("branch:") ||
+        worktree.startsWith("path:") ||
+        worktree.startsWith("issue:")) {
+        return worktree;
+    }
+    return `path:${worktree}`;
+}
+export async function startOrcaRetry(task, opts = {}) {
+    if (!task.dispatchId) {
+        throw new GateError(`task ${task.id} has no dispatch id; pass --dispatch on claim`);
+    }
+    if (!task.orcaTaskId) {
+        throw new GateError(`task ${task.id} has no Orca task id; create the Orca task before retrying`);
+    }
+    if (!task.agent) {
+        throw new GateError(`task ${task.id} has no agent; pass --agent on claim`);
+    }
+    const predecessorDispatchId = task.dispatchId;
+    const out = await orca([
+        "orchestration",
+        "worker-start",
+        "--task",
+        task.orcaTaskId,
+        "--retry-of",
+        predecessorDispatchId,
+        "--worktree",
+        worktreeSelector(task.worktree),
+        "--agent",
+        task.agent,
+        "--json",
+    ], opts);
+    task.dispatchId = requireDispatchId(out, task.id);
+    return out;
+}
+export async function startOrcaWorker(task, opts = {}) {
+    if (!task.agent) {
+        throw new GateError(`task ${task.id} has no agent; pass --agent to dispatch`);
+    }
+    if (!task.orcaTaskId) {
+        throw new GateError(`task ${task.id} has no Orca task id; create the Orca task before starting a worker`);
+    }
+    const out = await orca([
+        "orchestration",
+        "worker-start",
+        "--task",
+        task.orcaTaskId,
+        "--worktree",
+        worktreeSelector(task.worktree),
+        "--agent",
+        task.agent,
+        "--json",
+    ], opts);
+    task.dispatchId = requireDispatchId(out, task.id);
+    return out;
+}
+export async function createOrcaTask(task, opts = {}) {
+    const spec = task.deliverable ?? task.title ?? task.id;
+    return createOrcaTaskWithSpec(task, spec, opts);
+}
+async function createOrcaTaskWithSpec(task, spec, opts) {
+    const out = await orca([
+        "orchestration",
+        "task-create",
+        "--spec",
+        spec,
+        "--task-title",
+        task.title ?? task.id,
+        "--json",
+    ], opts);
+    const id = extractTaskId(out);
+    if (!id) {
+        throw new GateError(`orca task-create for ${task.id} returned no task id`);
+    }
+    task.orcaTaskId = id;
+    return out;
+}
+export async function startOrcaRepair(task, fromIds, opts = {}) {
+    const spec = [
+        task.deliverable ?? "integration repair",
+        `escalated_from: ${fromIds.join(", ")}`,
+        task.lastError ?? "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    await createOrcaTaskWithSpec(task, spec, opts);
+    if (!task.agent)
+        task.agent = "codex";
+    return startOrcaWorker(task, opts);
+}
+export async function createOrcaRun(objective, opts = {}) {
+    return orca(["orchestration", "run-create", "--objective", objective, "--json"], opts);
+}
+export async function listOrcaWorkers(opts = {}) {
+    return orca(["orchestration", "worker-list", "--json"], opts);
+}
+export async function showOrcaWorker(dispatchId, opts = {}) {
+    return orca(["orchestration", "worker-show", "--dispatch", dispatchId, "--json"], opts);
+}
+export async function removeOrcaWorktree(selector, opts = {}) {
+    return orca(["worktree", "rm", "--worktree", worktreeSelector(selector), "--json"], opts);
+}
+export async function orca(args, opts = {}) {
+    if (opts.exec)
+        return opts.exec(args);
+    const bin = opts.orcaBin ?? "orca";
+    try {
+        const { stdout } = await execFileAsync(bin, args, {
+            encoding: "utf8",
+            maxBuffer: 10 * 1024 * 1024,
+        });
+        return stdout.trim();
+    }
+    catch (err) {
+        const rec = err;
+        throw new GateError(`orca failed: ${(rec.stderr || rec.message || String(err)).trim()}`);
+    }
+}
+function requireDispatchId(stdout, taskId) {
+    const id = extractExplicitId(stdout, ["dispatchId", "dispatch_id"]);
+    if (!id) {
+        throw new GateError(`orca worker-start for ${taskId} returned no dispatch id`);
+    }
+    return id;
+}
+function extractExplicitId(stdout, keys) {
+    try {
+        const parsed = JSON.parse(stdout);
+        const result = parsed.result && typeof parsed.result === "object"
+            ? parsed.result
+            : parsed;
+        for (const key of keys) {
+            const value = result[key] ?? parsed[key];
+            if (typeof value === "string" && value.trim())
+                return value.trim();
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function extractTaskId(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        const result = parsed.result && typeof parsed.result === "object"
+            ? parsed.result
+            : parsed;
+        const task = result.task;
+        if (task && typeof task === "object") {
+            const id = task.id;
+            if (typeof id === "string" && id.trim())
+                return id.trim();
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return extractExplicitId(stdout, ["taskId", "task_id"]);
+}

package/dist/plan.d.ts

@@ -0,0 +1,6 @@
+import type { Plan, RunState, TaskState } from "./types.js";
+export declare function loadPlanFile(file: string): Promise<Plan>;
+export declare function parsePlan(raw: unknown): Plan;
+export declare function decomposeObjective(objective: string, planner?: string): Plan;
+export declare function applyPlan(run: RunState, plan: Plan): TaskState[];
+export declare function readyPlanTasks(run: RunState): TaskState[];