rich-parallel-agents 0.1.0

package/dist/classify.d.ts

@@ -0,0 +1,4 @@
+import type { CheckResult, ErrorClass } from "./types.js";
+export declare function classifyFailure(results: CheckResult[], lastError?: string): ErrorClass;
+export declare function shouldBlockWithoutRetry(errorClass: ErrorClass): boolean;
+export declare function isFlakyClass(errorClass: ErrorClass): boolean;

package/dist/classify.js

@@ -0,0 +1,46 @@
+const NO_RETRY = new Set([
+    "environment",
+    "permission",
+    "credential",
+    "ambiguous",
+    "unknown",
+]);
+export function classifyFailure(results, lastError) {
+    const blob = [lastError, ...results.flatMap((r) => [r.name, r.command, r.stdout, r.stderr])]
+        .filter(Boolean)
+        .join("\n")
+        .toLowerCase();
+    if (results.some((r) => r.timedOut) || /timed out|timeout/.test(blob))
+        return "timeout";
+    if (/merge conflict|automatic merge failed|fix conflicts/.test(blob))
+        return "merge_conflict";
+    if (/eacces|eperm|permission denied|operation not permitted/.test(blob))
+        return "permission";
+    if (/credential|api[_ -]?key|unauthorized|401|403|eauth|auth(entication)? failed/.test(blob)) {
+        return "credential";
+    }
+    if (/enotfound|econnrefused|network|docker daemon|no such file|enoent|missing env|not installed/.test(blob)) {
+        return "environment";
+    }
+    if (/ambiguous|unclear requirement|need clarification/.test(blob))
+        return "ambiguous";
+    if (/segfault|sigabrt|sigsegv|panic:|fatal error/.test(blob))
+        return "crash";
+    if (/flaky|intermittent/.test(blob))
+        return "flaky";
+    if (/\btsc\b|typecheck|type error|ts\d{3,5}/.test(blob))
+        return "typecheck";
+    if (/\beslint\b|\blint\b|prettier/.test(blob))
+        return "lint";
+    if (/assert|expected|not to be|toequal|fail(ed)?\s+tests[/\\]|test failed/.test(blob) ||
+        results.some((r) => !r.passed && r.required)) {
+        return "assertion";
+    }
+    return "unknown";
+}
+export function shouldBlockWithoutRetry(errorClass) {
+    return NO_RETRY.has(errorClass);
+}
+export function isFlakyClass(errorClass) {
+    return errorClass === "flaky" || errorClass === "timeout";
+}

package/dist/clean.d.ts

@@ -0,0 +1,25 @@
+import { type OrcaOpts } from "./orca.js";
+import type { ResourceRecord, RunState } from "./types.js";
+export type CleanOpts = {
+    storeDir: string;
+    run: RunState;
+    dry?: boolean;
+    worktrees?: boolean;
+    force?: boolean;
+    orca?: boolean;
+    orcaBin?: string;
+    orcaExec?: OrcaOpts["exec"];
+};
+export declare function cleanRun(opts: CleanOpts): Promise<{
+    expired: ResourceRecord[];
+    cleaned: ResourceRecord[];
+    skipped: ResourceRecord[];
+    dry: boolean;
+}>;
+export declare function assertOwned(resource: ResourceRecord): void;
+export declare function formatCleanResult(result: {
+    expired: ResourceRecord[];
+    cleaned: ResourceRecord[];
+    skipped: ResourceRecord[];
+    dry: boolean;
+}): string;

package/dist/clean.js

@@ -0,0 +1,64 @@
+import { GateError } from "./errors.js";
+import { removeOrcaWorktree } from "./orca.js";
+import { expiredResources, liveResources, markCleaned } from "./resources.js";
+import { persist } from "./store.js";
+export async function cleanRun(opts) {
+    const { run } = opts;
+    const expired = expiredResources(run);
+    const skipped = [];
+    const cleaned = [];
+    const dryWorktrees = !opts.force;
+    const dry = Boolean(opts.dry);
+    run.status = "cleaning";
+    for (const resource of liveResources(run)) {
+        assertOwned(resource);
+        if (resource.kind === "worktree" && !opts.worktrees) {
+            skipped.push(resource);
+            continue;
+        }
+        const resourceDry = resource.kind === "worktree" ? dryWorktrees || dry : dry;
+        if (resourceDry) {
+            skipped.push(resource);
+            continue;
+        }
+        if (resource.kind === "worktree" && opts.orca) {
+            await removeOrcaWorktree(resource.selector, { orcaBin: opts.orcaBin, exec: opts.orcaExec });
+        }
+        const marked = markCleaned(run, resource.id);
+        if (marked)
+            cleaned.push(marked);
+        await persist(opts.storeDir, run, {
+            type: "RESOURCE_CLEANED",
+            taskId: resource.taskId,
+            payload: { id: resource.id, kind: resource.kind, selector: resource.selector },
+        });
+    }
+    const remaining = liveResources(run);
+    run.status = remaining.length === 0 ? "cleaned" : "partial";
+    await persist(opts.storeDir, run);
+    return { expired, cleaned, skipped, dry };
+}
+export function assertOwned(resource) {
+    if (resource.createdBy !== "rpa") {
+        throw new GateError(`refusing to clean non-RPA resource ${resource.id}`);
+    }
+}
+export function formatCleanResult(result) {
+    const lines = [
+        result.dry ? "clean dry-run" : "clean",
+        `cleaned ${result.cleaned.length}  skipped ${result.skipped.length}  expired-leases ${result.expired.length}`,
+    ];
+    if (result.expired.length) {
+        lines.push("expired leases (investigate, not deleted):");
+        for (const resource of result.expired) {
+            lines.push(`  ${resource.kind}  ${resource.selector}  ${resource.leaseExpiresAt}`);
+        }
+    }
+    for (const resource of result.cleaned) {
+        lines.push(`  cleaned ${resource.kind}  ${resource.selector}`);
+    }
+    for (const resource of result.skipped) {
+        lines.push(`  skipped ${resource.kind}  ${resource.selector}`);
+    }
+    return lines.join("\n");
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,449 @@
+#!/usr/bin/env node
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { Command } from "commander";
+import { commandAsCheck, DEFAULT_CONFIG, loadConfig } from "./config.js";
+import { formatCleanResult, cleanRun } from "./clean.js";
+import { GateError } from "./errors.js";
+import { execCommand } from "./exec.js";
+import { formatRun, formatTask, toJson } from "./format.js";
+import { claimTask, refreshRunStatus, retryTask, verifyAll, verifyTask } from "./gate.js";
+import { formatHistory, formatReport, loadHistory } from "./history.js";
+import { integrateAccepted } from "./integrate.js";
+import { startOrcaRetry } from "./orca.js";
+import { startIntegrationRepair } from "./repair.js";
+import { resumeRun } from "./resume.js";
+import { prepareRun } from "./run.js";
+import { installSkill, readSkill } from "./skill.js";
+import { createRun, loadRun, persist, resolveStoreDir, StoreError } from "./store.js";
+import { runChecks, verifyPassed } from "./verify.js";
+export async function main(argv = process.argv) {
+    const program = new Command();
+    program
+        .name("rpa")
+        .description("Verification gate for orca workers. worker_done is a claim until verify passes.")
+        .version("0.1.0");
+    program
+        .command("init")
+        .description("Create a run and store verification config")
+        .option("--store <dir>", "state directory (default: $RPA_STORE or ./.rpa)")
+        .option("--repo <path>", "repository root", ".")
+        .option("--config <path>", "YAML config (verify + retry)")
+        .option("--id <id>", "run id")
+        .option("--json", "print JSON", false)
+        .action(async (opts) => {
+        const storeDir = resolveStoreDir(opts.store);
+        const config = await resolveConfigFile(opts.config, opts.repo ?? ".");
+        const run = await createRun(storeDir, {
+            repo: opts.repo ?? ".",
+            config,
+            id: opts.id,
+        });
+        writeOutput(opts.json, run, formatRun(run));
+    });
+    program
+        .command("run")
+        .description("Create a planned run from an objective or plan.json")
+        .argument("[objective...]", "run objective; numbered/bullet lines become tasks")
+        .option("--plan <file>", "plan.json")
+        .option("--planner <name>", "planner id or command")
+        .option("--plan-only", "write plan.json without dispatching", false)
+        .option("--dry", "plan only; print and stop", false)
+        .option("--orca", "dispatch via orca task-create/worker-start", false)
+        .option("--store <dir>", "state directory")
+        .option("--repo <path>", "repository root", ".")
+        .option("--config <path>", "YAML config")
+        .option("--id <id>", "run id")
+        .option("--json", "print JSON", false)
+        .action(async (objectiveParts, opts) => {
+        const objective = objectiveParts.join(" ").trim() || undefined;
+        const storeDir = resolveStoreDir(opts.store);
+        const config = await resolveConfigFile(opts.config, opts.repo ?? ".");
+        const run = await createRun(storeDir, {
+            repo: opts.repo ?? ".",
+            config,
+            id: opts.id,
+            objective,
+            planner: opts.planner,
+        });
+        try {
+            await prepareRun({
+                storeDir,
+                run,
+                objective,
+                planFile: opts.plan,
+                planner: opts.planner,
+                planOnly: opts.planOnly || opts.dry,
+                dry: opts.dry,
+                orca: opts.orca,
+            });
+        }
+        catch (err) {
+            run.status = "failed";
+            await persist(storeDir, run, {
+                type: "RUN_FAILED",
+                payload: {
+                    phase: run.plan ? "dispatch" : "planning",
+                    error: err instanceof Error ? err.message : String(err),
+                },
+            });
+            throw err;
+        }
+        writeOutput(opts.json, run, formatRun(run));
+    });
+    program
+        .command("claim")
+        .description("Record worker_done as a claim, not acceptance")
+        .requiredOption("--task <id>", "task id")
+        .requiredOption("--worktree <path>", "worker worktree")
+        .option("--outcome <outcome>", "worker_done outcome: succeeded|failed", "succeeded")
+        .option("--dispatch <id>", "orca dispatch id")
+        .option("--orca-task <id>", "orca task id")
+        .option("--agent <id>", "orca agent id")
+        .option("--store <dir>", "state directory")
+        .option("--repo <path>", "repository root", ".")
+        .option("--config <path>", "YAML config used if a run is created")
+        .option("--run <id>", "run id")
+        .option("--json", "print JSON", false)
+        .action(async (opts) => {
+        const outcome = parseOutcome(opts.outcome);
+        const storeDir = resolveStoreDir(opts.store);
+        const run = await loadOrCreate(storeDir, opts);
+        const task = await claimTask(run, {
+            taskId: opts.task,
+            worktree: opts.worktree,
+            outcome,
+            dispatchId: opts.dispatch,
+            orcaTaskId: opts.orcaTask,
+            agent: opts.agent,
+        });
+        await persist(storeDir, run, {
+            type: "TASK_CLAIMED",
+            taskId: task.id,
+            payload: { outcome: task.workerOutcome, dispatchId: task.dispatchId ?? null },
+        });
+        writeOutput(opts.json, { run, task }, formatTask(task));
+    });
+    program
+        .command("verify")
+        .description("Run task verify; pass becomes accepted")
+        .option("--task <id>", "task id (default: all claimed/retrying)")
+        .option("--command <cmd>", "override with a single required command")
+        .option("--cwd <path>", "working directory for --command without --task")
+        .option("--store <dir>", "state directory")
+        .option("--config <path>", "YAML config override")
+        .option("--run <id>", "run id")
+        .option("--json", "print JSON", false)
+        .action(async (opts) => {
+        if (opts.command && !opts.task) {
+            const cwd = path.resolve(opts.cwd ?? process.cwd());
+            const results = await runChecks([commandAsCheck(opts.command)], cwd, execCommand);
+            const ok = verifyPassed(results);
+            writeOutput(opts.json, { cwd, checks: results, passed: ok }, results
+                .map((check) => `${check.name}  ${check.passed ? "pass" : "fail"}`)
+                .join("\n"));
+            if (!ok)
+                throw new GateError("verify failed");
+            return;
+        }
+        const storeDir = resolveStoreDir(opts.store);
+        const run = await loadRun(storeDir, opts.run);
+        const checks = opts.command
+            ? [commandAsCheck(opts.command)]
+            : opts.config
+                ? (await loadConfig(opts.config)).verify.task
+                : undefined;
+        const tasks = opts.task
+            ? [await verifyTask(run, opts.task, { exec: execCommand, checks })]
+            : await verifyAll(run, { exec: execCommand, checks });
+        if (!opts.task && tasks.length === 0) {
+            throw new GateError("no claimed/retrying tasks to verify");
+        }
+        for (const task of tasks) {
+            const last = task.attempts.at(-1);
+            await persist(storeDir, run, {
+                type: task.status === "accepted" ? "TASK_ACCEPTED" : "VERIFY_FAILED",
+                taskId: task.id,
+                attemptId: last ? String(last.attemptNo) : undefined,
+                payload: { status: task.status, errorClass: task.errorClass ?? null },
+            });
+        }
+        writeOutput(opts.json, { run, tasks }, opts.task ? formatTask(tasks[0]) : formatRun(run));
+        if (tasks.some((task) => task.status !== "accepted" && task.status !== "integrated")) {
+            throw new GateError("verify did not accept every selected task");
+        }
+    });
+    program
+        .command("retry")
+        .description("Mark a failed verify for retry; merge-blocked tasks must be re-claimed with a repaired SHA. Optionally start orca --retry-of")
+        .requiredOption("--task <id>", "task id")
+        .option("--orca", "call orca orchestration worker-start --retry-of", false)
+        .option("--store <dir>", "state directory")
+        .option("--run <id>", "run id")
+        .option("--json", "print JSON", false)
+        .action(async (opts) => {
+        const storeDir = resolveStoreDir(opts.store);
+        const run = await loadRun(storeDir, opts.run);
+        const task = retryTask(run, opts.task);
+        let orca;
+        const predecessorDispatchId = task.dispatchId;
+        if (opts.orca) {
+            task.dispatchPhase = "intent";
+            await persist(storeDir, run, {
+                type: "RETRY_REQUESTED",
+                taskId: task.id,
+                payload: {
+                    phase: "intent",
+                    orca: true,
+                    predecessorDispatchId: predecessorDispatchId ?? null,
+                    orcaTaskId: task.orcaTaskId ?? null,
+                },
+            });
+            try {
+                orca = await startOrcaRetry(task);
+                task.dispatchPhase = "worker-started";
+            }
+            catch (err) {
+                task.status = "blocked";
+                task.dispatchPhase = "failed";
+                task.errorClass = "environment";
+                task.lastError = `orca retry failed: ${err instanceof Error ? err.message : String(err)}`;
+                refreshRunStatus(run);
+                await persist(storeDir, run, {
+                    type: "RETRY_REQUESTED",
+                    taskId: task.id,
+                    payload: {
+                        phase: "failed",
+                        orca: true,
+                        predecessorDispatchId: predecessorDispatchId ?? null,
+                        orcaTaskId: task.orcaTaskId ?? null,
+                        error: task.lastError,
+                    },
+                });
+                throw new GateError(task.lastError);
+            }
+        }
+        await persist(storeDir, run, {
+            type: "RETRY_REQUESTED",
+            taskId: task.id,
+            payload: {
+                phase: opts.orca ? "worker-started" : "requested",
+                orca: Boolean(opts.orca),
+                predecessorDispatchId: predecessorDispatchId ?? null,
+                dispatchId: task.dispatchId ?? null,
+                orcaTaskId: task.orcaTaskId ?? null,
+            },
+        });
+        writeOutput(opts.json, { run, task, orca }, orca ? `${formatTask(task)}\n\n${orca}` : formatTask(task));
+    });
+    program
+        .command("integrate")
+        .description("Merge accepted task SHAs only, then run integration verify")
+        .requiredOption("--into <path>", "integration worktree")
+        .option("--store <dir>", "state directory")
+        .option("--run <id>", "run id")
+        .option("--json", "print JSON", false)
+        .action(async (opts) => {
+        const storeDir = resolveStoreDir(opts.store);
+        const run = await loadRun(storeDir, opts.run);
+        await persist(storeDir, run, {
+            type: "INTEGRATION_STARTED",
+            payload: { into: opts.into },
+        });
+        await integrateAccepted(run, { into: opts.into, exec: execCommand });
+        const integration = run.integration;
+        const type = integration?.status === "passed"
+            ? "RUN_SUCCEEDED"
+            : integration?.status === "conflict"
+                ? "INTEGRATION_CONFLICT"
+                : "INTEGRATION_FAILED";
+        await persist(storeDir, run, {
+            type,
+            payload: { status: integration?.status ?? null, error: integration?.error ?? null },
+        });
+        writeOutput(opts.json, run, formatRun(run));
+        if (!integration || integration.status !== "passed") {
+            throw new GateError(integration?.error ?? "integration did not pass");
+        }
+    });
+    program
+        .command("repair")
+        .description("Open an integration_repair task from blocked merge/verify evidence")
+        .option("--from <ids>", "comma-separated task ids (default: all blocked)")
+        .option("--orca", "start an orca integration repair worker", false)
+        .option("--agent <id>", "agent for --orca")
+        .option("--store <dir>", "state directory")
+        .option("--run <id>", "run id")
+        .option("--json", "print JSON", false)
+        .action(async (opts) => {
+        const storeDir = resolveStoreDir(opts.store);
+        const run = await loadRun(storeDir, opts.run);
+        const fromIds = opts.from ? opts.from.split(",").map((id) => id.trim()).filter(Boolean) : undefined;
+        const result = await startIntegrationRepair(run, {
+            fromIds,
+            orca: opts.orca,
+            agent: opts.agent,
+        });
+        await persist(storeDir, run, {
+            type: "REPAIR_STARTED",
+            taskId: result.task.id,
+            payload: { from: result.task.escalatedFrom ?? [], orca: Boolean(opts.orca) },
+        });
+        writeOutput(opts.json, { run, task: result.task, orca: result.orca }, formatTask(result.task));
+    });
+    program
+        .command("resume")
+        .description("Reconcile journal/orca state and continue verify")
+        .argument("[run-id]", "run id (default: current)")
+        .option("--orca", "reconcile against orca worker-list", false)
+        .option("--store <dir>", "state directory")
+        .option("--json", "print JSON", false)
+        .action(async (runId, opts) => {
+        const storeDir = resolveStoreDir(opts.store);
+        const run = await loadRun(storeDir, runId ?? opts.run);
+        await resumeRun({ storeDir, run, exec: execCommand, orca: opts.orca });
+        writeOutput(opts.json, run, formatRun(run));
+    });
+    program
+        .command("clean")
+        .description("Clean RPA-owned resources only; expired leases are investigate signals")
+        .option("--worktrees", "include worktrees (dry unless --force)", false)
+        .option("--dry", "do not delete anything", false)
+        .option("--force", "actually remove worktrees recorded by RPA", false)
+        .option("--orca", "call orca worktree rm for recorded worktrees", false)
+        .option("--store <dir>", "state directory")
+        .option("--run <id>", "run id")
+        .option("--json", "print JSON", false)
+        .action(async (opts) => {
+        const storeDir = resolveStoreDir(opts.store);
+        const run = await loadRun(storeDir, opts.run);
+        const result = await cleanRun({
+            storeDir,
+            run,
+            dry: opts.dry,
+            worktrees: opts.worktrees,
+            force: opts.force,
+            orca: opts.orca,
+        });
+        writeOutput(opts.json, { run, ...result }, formatCleanResult(result));
+    });
+    program
+        .command("status")
+        .description("Show claim vs accepted vs integrated")
+        .option("--store <dir>", "state directory")
+        .option("--run <id>", "run id")
+        .option("--json", "print JSON", false)
+        .action(async (opts) => {
+        const storeDir = resolveStoreDir(opts.store);
+        const run = await loadRun(storeDir, opts.run);
+        writeOutput(opts.json, run, formatRun(run));
+    });
+    program
+        .command("report")
+        .description("Print a run report")
+        .option("--store <dir>", "state directory")
+        .option("--run <id>", "run id")
+        .option("--json", "print JSON", false)
+        .action(async (opts) => {
+        const storeDir = resolveStoreDir(opts.store);
+        const run = await loadRun(storeDir, opts.run);
+        writeOutput(opts.json, run, formatReport(run));
+    });
+    program
+        .command("skill")
+        .description("Print the agent skill, or install rpa onto PATH and agent skill dirs")
+        .option("--install", "symlink dist/cli.js to ~/.local/bin/rpa and SKILL.md into agent skill dirs", false)
+        .option("--json", "print JSON", false)
+        .action(async (opts) => {
+        if (opts.install) {
+            const result = await installSkill();
+            writeOutput(opts.json, result, [`installed bin ${result.bin}`, ...result.skills.map((skill) => `skill ${skill}`)].join("\n"));
+            return;
+        }
+        const text = await readSkill();
+        writeOutput(opts.json, { skill: text }, text.endsWith("\n") ? text.slice(0, -1) : text);
+    });
+    program
+        .command("history")
+        .description("List runs from the store journal")
+        .option("--stats", "aggregate success/retry stats", false)
+        .option("--by-type", "group by error class / status", false)
+        .option("--store <dir>", "state directory")
+        .option("--json", "print JSON", false)
+        .action(async (opts) => {
+        const storeDir = resolveStoreDir(opts.store);
+        const { rows, events } = await loadHistory(storeDir);
+        writeOutput(opts.json, { rows, events }, formatHistory(rows, opts.stats, opts.byType));
+    });
+    program.exitOverride();
+    try {
+        await program.parseAsync(argv);
+        return 0;
+    }
+    catch (err) {
+        if (isCommanderHelp(err))
+            return 0;
+        if (err instanceof GateError) {
+            process.stderr.write(`${err.message}\n`);
+            return err.exitCode;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`${message}\n`);
+        return 1;
+    }
+}
+function parseOutcome(value) {
+    if (value === "succeeded" || value === "failed")
+        return value;
+    throw new GateError(`outcome must be succeeded or failed, got ${value}`);
+}
+async function resolveConfigFile(configPath, repo = ".") {
+    if (configPath)
+        return loadConfig(configPath);
+    const fallback = path.resolve(repo, "rpa.yaml");
+    try {
+        await access(fallback);
+    }
+    catch (err) {
+        if (err &&
+            typeof err === "object" &&
+            "code" in err &&
+            err.code === "ENOENT") {
+            return DEFAULT_CONFIG;
+        }
+        throw err;
+    }
+    return loadConfig(fallback);
+}
+async function loadOrCreate(storeDir, opts) {
+    try {
+        return await loadRun(storeDir, opts.run);
+    }
+    catch (err) {
+        if (opts.run || !(err instanceof StoreError) || err.kind !== "no-current")
+            throw err;
+        const config = await resolveConfigFile(opts.config, opts.repo ?? ".");
+        return createRun(storeDir, { repo: opts.repo ?? ".", config });
+    }
+}
+function writeOutput(json, value, text) {
+    if (json) {
+        process.stdout.write(toJson(value));
+        return;
+    }
+    process.stdout.write(`${text}\n`);
+}
+function isCommanderHelp(err) {
+    return Boolean(err &&
+        typeof err === "object" &&
+        "code" in err &&
+        (err.code === "commander.helpDisplayed" || err.code === "commander.version"));
+}
+const entry = process.argv[1];
+if (entry &&
+    (entry.endsWith("/cli.ts") || entry.endsWith("/cli.js") || entry.endsWith("/rpa"))) {
+    main().then((code) => {
+        if (code !== 0)
+            process.exit(code);
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+import type { RpaConfig, VerifyCheck } from "./types.js";
+export declare const DEFAULT_CONFIG: RpaConfig;
+export declare function parseConfig(raw: string): RpaConfig;
+export declare function loadConfig(path: string): Promise<RpaConfig>;
+export declare function parseTimeout(value: unknown, fallback: number): number;
+export declare function commandAsCheck(command: string): VerifyCheck;