rich-parallel-agents 0.1.0

package/dist/config.js

@@ -0,0 +1,142 @@
+import { readFile } from "node:fs/promises";
+import YAML from "yaml";
+const DEFAULT_TIMEOUT_MS = 120_000;
+export const DEFAULT_CONFIG = {
+    verify: { task: [], integration: [] },
+    retry: { max: 1 },
+    flaky: { retries: 0, requireConsecutivePasses: 1 },
+    planner: {},
+    providers: {},
+    lease: { ttlMs: 30 * 60_000 },
+};
+export function parseConfig(raw) {
+    const data = (YAML.parse(raw) ?? {});
+    const verify = data.verify && typeof data.verify === "object"
+        ? data.verify
+        : {};
+    const retry = data.retry && typeof data.retry === "object"
+        ? data.retry
+        : {};
+    const flaky = data.flaky && typeof data.flaky === "object"
+        ? data.flaky
+        : {};
+    const planner = data.planner && typeof data.planner === "object"
+        ? data.planner
+        : typeof data.planner === "string"
+            ? { command: data.planner }
+            : {};
+    const providers = data.providers && typeof data.providers === "object"
+        ? data.providers
+        : {};
+    const lease = data.lease && typeof data.lease === "object"
+        ? data.lease
+        : {};
+    return {
+        verify: {
+            task: parseChecks(verify.task),
+            integration: parseChecks(verify.integration),
+        },
+        retry: {
+            max: parseMax(retry.max, DEFAULT_CONFIG.retry.max),
+        },
+        flaky: {
+            retries: parseMax(flaky.retries, DEFAULT_CONFIG.flaky.retries),
+            requireConsecutivePasses: Math.max(1, parseMax(flaky.require_consecutive_passes ?? flaky.requireConsecutivePasses, DEFAULT_CONFIG.flaky.requireConsecutivePasses)),
+        },
+        planner: parsePlanner(planner),
+        providers: parseProviders(providers),
+        lease: {
+            ttlMs: parseTimeout(lease.ttl ?? lease.ttlMs, DEFAULT_CONFIG.lease.ttlMs),
+        },
+    };
+}
+export async function loadConfig(path) {
+    return parseConfig(await readFile(path, "utf8"));
+}
+function parseChecks(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((item, index) => {
+        if (!item || typeof item !== "object") {
+            throw new Error(`verify check ${index} must be an object`);
+        }
+        const rec = item;
+        const provider = typeof rec.provider === "string" ? rec.provider.trim() : undefined;
+        const command = typeof rec.command === "string" && rec.command.trim()
+            ? rec.command.trim()
+            : provider
+                ? ""
+                : requiredString(rec.command, `verify check ${index} command`);
+        const name = typeof rec.name === "string" && rec.name.trim()
+            ? rec.name.trim()
+            : command || provider || `check-${index}`;
+        const check = {
+            name,
+            command,
+            required: rec.required === undefined ? true : Boolean(rec.required),
+            timeoutMs: parseTimeout(rec.timeout ?? rec.timeoutMs, DEFAULT_TIMEOUT_MS),
+        };
+        if (provider)
+            check.provider = provider;
+        return check;
+    });
+}
+function parsePlanner(value) {
+    const command = typeof value.command === "string" ? value.command.trim() : undefined;
+    return command ? { command } : {};
+}
+function parseProviders(value) {
+    const out = {};
+    for (const [name, item] of Object.entries(value)) {
+        if (typeof item === "string") {
+            out[name] = { command: item };
+            continue;
+        }
+        if (item && typeof item === "object" && typeof item.command === "string") {
+            out[name] = { command: item.command };
+        }
+    }
+    return out;
+}
+function parseMax(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new Error("must be a non-negative integer");
+    }
+    return value;
+}
+export function parseTimeout(value, fallback) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+        return value > 0 && value < 1000 ? value * 1000 : value;
+    }
+    if (typeof value === "string") {
+        const match = value.trim().match(/^(\d+(?:\.\d+)?)(ms|s|m)?$/i);
+        if (!match)
+            throw new Error(`invalid timeout: ${value}`);
+        const n = Number(match[1]);
+        const unit = (match[2] ?? "s").toLowerCase();
+        if (unit === "ms")
+            return n;
+        if (unit === "m")
+            return n * 60_000;
+        return n * 1000;
+    }
+    throw new Error(`invalid timeout: ${String(value)}`);
+}
+function requiredString(value, label) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${label} is required`);
+    }
+    return value.trim();
+}
+export function commandAsCheck(command) {
+    return {
+        name: command,
+        command,
+        required: true,
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class GateError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}

package/dist/errors.js

@@ -0,0 +1,8 @@
+export class GateError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = "GateError";
+        this.exitCode = exitCode;
+    }
+}

package/dist/exec.d.ts

@@ -0,0 +1,2 @@
+import type { ExecFn } from "./types.js";
+export declare const execCommand: ExecFn;

package/dist/exec.js

@@ -0,0 +1,58 @@
+import { spawn } from "node:child_process";
+const OUTPUT_CAP = 32_768;
+export const execCommand = (command, cwd, timeoutMs) => {
+    return new Promise((resolve) => {
+        const child = spawn(command, {
+            cwd,
+            shell: true,
+            env: process.env,
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let settled = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+            setTimeout(() => {
+                if (!settled)
+                    child.kill("SIGKILL");
+            }, 1000).unref();
+        }, timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            stdout = cap(`${stdout}${chunk.toString()}`);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr = cap(`${stderr}${chunk.toString()}`);
+        });
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                exitCode: 1,
+                stdout,
+                stderr: cap(`${stderr}${err.message}`),
+                timedOut: false,
+            });
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                exitCode: timedOut ? 124 : (code ?? 1),
+                stdout,
+                stderr,
+                timedOut,
+            });
+        });
+    });
+};
+function cap(text) {
+    if (text.length <= OUTPUT_CAP)
+        return text;
+    return text.slice(text.length - OUTPUT_CAP);
+}

package/dist/format.d.ts

@@ -0,0 +1,5 @@
+import type { CheckResult, RunState, TaskState } from "./types.js";
+export declare function formatRun(run: RunState): string;
+export declare function formatCheck(check: CheckResult): string;
+export declare function formatTask(task: TaskState): string;
+export declare function toJson(value: unknown): string;

package/dist/format.js

@@ -0,0 +1,71 @@
+export function formatRun(run) {
+    const lines = [`run ${run.id}  ${run.status}`, ""];
+    if (run.objective)
+        lines.push(`objective  ${run.objective}`, "");
+    const tasks = Object.values(run.tasks);
+    if (tasks.length === 0) {
+        lines.push("no tasks");
+        return lines.join("\n");
+    }
+    const idW = Math.max(4, ...tasks.map((task) => task.id.length));
+    const statusW = Math.max(6, ...tasks.map((task) => task.status.length));
+    lines.push(`${pad("TASK", idW)}  ${pad("STATUS", statusW)}  ATT  WORKER     VERIFY`);
+    lines.push("-".repeat(idW + statusW + 28));
+    for (const task of tasks) {
+        const last = task.attempts.at(-1);
+        const verify = last ? (last.verifyPass ? (last.flaky ? "flaky" : "pass") : "fail") : "—";
+        lines.push(`${pad(task.id, idW)}  ${pad(task.status, statusW)}  ${String(task.attempts.length).padStart(3, " ")}  ${pad(task.workerOutcome, 9)}  ${verify}`);
+        if (task.errorClass)
+            lines.push(`  class ${task.errorClass}`);
+        if (task.lastError)
+            lines.push(`  ${task.lastError}`);
+        if (last) {
+            for (const check of last.checks) {
+                lines.push(`  ${formatCheck(check)}`);
+            }
+        }
+    }
+    if (run.integration) {
+        lines.push("");
+        lines.push(`integration  ${run.integration.status}  into ${run.integration.into}`);
+        if (run.integration.mergedTaskIds.length > 0) {
+            lines.push(`  merged: ${run.integration.mergedTaskIds.join(", ")}`);
+        }
+        if (run.integration.error)
+            lines.push(`  ${run.integration.error}`);
+        for (const check of run.integration.checks) {
+            lines.push(`  ${formatCheck(check)}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function formatCheck(check) {
+    const mark = check.passed ? "pass" : check.timedOut ? "timeout" : "fail";
+    const req = check.required ? "required" : "optional";
+    const provider = check.provider ? `  provider:${check.provider}` : "";
+    return `${check.name}  ${mark}  ${req}  ${check.durationMs}ms${provider}`;
+}
+export function formatTask(task) {
+    const last = task.attempts.at(-1);
+    const lines = [
+        `task ${task.id}  ${task.status}  worker=${task.workerOutcome}`,
+        `  worktree ${task.worktree}`,
+    ];
+    if (task.headSha)
+        lines.push(`  head ${task.headSha}${task.dirty ? " (dirty)" : ""}`);
+    if (task.errorClass)
+        lines.push(`  class ${task.errorClass}`);
+    if (task.lastError)
+        lines.push(`  ${task.lastError}`);
+    if (last) {
+        for (const check of last.checks)
+            lines.push(`  ${formatCheck(check)}`);
+    }
+    return lines.join("\n");
+}
+export function toJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function pad(value, width) {
+    return value.padEnd(width, " ");
+}

package/dist/gate.d.ts

@@ -0,0 +1,24 @@
+import type { ExecFn, RpaConfig, RunState, RunStatus, TaskState, VerifyCheck, WorkerOutcome } from "./types.js";
+export type ClaimInput = {
+    taskId: string;
+    worktree: string;
+    outcome?: WorkerOutcome;
+    dispatchId?: string;
+    orcaTaskId?: string;
+    agent?: string;
+};
+export declare function claimTask(run: RunState, input: ClaimInput, cwd?: string): Promise<TaskState>;
+export declare function verifyTask(run: RunState, taskId: string, opts: {
+    exec: ExecFn;
+    checks?: VerifyCheck[];
+}): Promise<TaskState>;
+export declare function verifyAll(run: RunState, opts: {
+    exec: ExecFn;
+    checks?: VerifyCheck[];
+}): Promise<TaskState[]>;
+export declare function retryTask(run: RunState, taskId: string): TaskState;
+export declare function isMergeFailure(task: TaskState): boolean;
+export declare function requireTask(run: RunState, taskId: string): TaskState;
+export declare function refreshRunStatus(run: RunState): void;
+export declare function deriveRunStatus(run: RunState): RunStatus;
+export declare function withConfig(run: RunState, config: RpaConfig): void;

package/dist/gate.js

@@ -0,0 +1,329 @@
+import path from "node:path";
+import { classifyFailure, isFlakyClass, shouldBlockWithoutRetry } from "./classify.js";
+import { GateError } from "./errors.js";
+import { snapshot } from "./git.js";
+import { requiredFailed, runChecks, verifyPassed } from "./verify.js";
+export async function claimTask(run, input, cwd = process.cwd()) {
+    const worktree = path.resolve(cwd, input.worktree);
+    const existing = run.tasks[input.taskId];
+    if (existing && (existing.status === "accepted" || existing.status === "integrated")) {
+        throw new GateError(`task ${input.taskId} is ${existing.status}; not overwriting a verified result`);
+    }
+    const git = await snapshot(worktree);
+    const outcome = input.outcome ?? "succeeded";
+    const task = {
+        id: input.taskId,
+        status: outcome === "failed" ? "blocked" : "claimed",
+        worktree,
+        dispatchId: input.dispatchId ?? existing?.dispatchId,
+        agent: input.agent ?? existing?.agent,
+        workerOutcome: outcome === "pending" ? "succeeded" : outcome,
+        headSha: git.headSha,
+        dirty: git.dirty,
+        attempts: existing?.attempts ?? [],
+        title: existing?.title,
+        deliverable: existing?.deliverable,
+        deps: existing?.deps,
+        escalatedFrom: existing?.escalatedFrom,
+        orcaTaskId: input.orcaTaskId ?? existing?.orcaTaskId,
+        lastError: outcome === "failed" ? "worker_done outcome=failed is a failed claim, not accepted" : undefined,
+    };
+    run.tasks[input.taskId] = task;
+    refreshRunStatus(run);
+    return task;
+}
+export async function verifyTask(run, taskId, opts) {
+    const task = requireTask(run, taskId);
+    if (task.status === "integrated") {
+        throw new GateError(`task ${taskId} is already integrated`);
+    }
+    if (task.workerOutcome === "failed") {
+        task.status = "blocked";
+        task.lastError = "worker_done outcome=failed; skipping verify";
+        refreshRunStatus(run);
+        return task;
+    }
+    if (task.status === "accepted")
+        return task;
+    if (task.status !== "claimed" && task.status !== "retrying") {
+        throw new GateError(`task ${taskId} is ${task.status}; verification requires a claimed or retrying task`);
+    }
+    const checks = opts.checks ?? run.config.verify.task;
+    task.status = "verifying";
+    const startedAt = new Date().toISOString();
+    let before;
+    try {
+        before = await snapshot(task.worktree);
+    }
+    catch (err) {
+        return finalizeFailedVerification(run, task, startedAt, [snapshotFailure(`pre-check snapshot failed: ${errorMessage(err)}`)]);
+    }
+    task.headSha = before.headSha;
+    task.dirty = before.dirty;
+    const extra = {
+        cwd: task.worktree,
+        base: run.baseSha ?? "",
+        head: before.headSha ?? "",
+    };
+    let results;
+    if (!before.headSha || before.dirty) {
+        results = [
+            snapshotFailure(!before.headSha
+                ? "verification refused: pre-check snapshot has no HEAD commit"
+                : `verification refused: pre-check worktree is dirty at ${before.headSha}`),
+        ];
+    }
+    else {
+        try {
+            results = await runChecks(checks, task.worktree, opts.exec, {
+                config: run.config,
+                extra,
+            });
+        }
+        catch (err) {
+            results = [executionFailure(`verification execution failed: ${errorMessage(err)}`)];
+        }
+    }
+    let passed = verifyPassed(results);
+    let flaky = false;
+    let errorClass = passed ? undefined : classifyFailure(results);
+    if (before.headSha &&
+        !before.dirty &&
+        !passed &&
+        errorClass &&
+        isFlakyClass(errorClass) &&
+        run.config.flaky.retries > 0) {
+        let consecutive = 0;
+        const need = run.config.flaky.requireConsecutivePasses;
+        for (let i = 0; i < run.config.flaky.retries; i += 1) {
+            let extraResults;
+            try {
+                extraResults = await runChecks(checks, task.worktree, opts.exec, {
+                    config: run.config,
+                    extra,
+                });
+            }
+            catch (err) {
+                extraResults = [
+                    executionFailure(`verification execution failed: ${errorMessage(err)}`),
+                ];
+            }
+            if (verifyPassed(extraResults))
+                consecutive += 1;
+            else
+                consecutive = 0;
+            results = extraResults;
+            if (consecutive >= need) {
+                passed = true;
+                flaky = true;
+                errorClass = "flaky";
+                break;
+            }
+        }
+        if (!passed)
+            errorClass = classifyFailure(results);
+    }
+    let git;
+    try {
+        git = await snapshot(task.worktree);
+        task.headSha = git.headSha;
+        task.dirty = git.dirty;
+    }
+    catch (err) {
+        results.push(snapshotFailure(`post-check snapshot failed: ${errorMessage(err)}`));
+        passed = false;
+        flaky = false;
+        errorClass = classifyFailure(results);
+    }
+    if (git &&
+        before.headSha &&
+        !before.dirty &&
+        (git.headSha !== before.headSha || git.dirty)) {
+        results.push(snapshotFailure(`verification snapshot changed during checks: expected HEAD ${before.headSha} with a clean worktree; observed HEAD ${git.headSha ?? "<none>"}, dirty=${git.dirty}`));
+        passed = false;
+        flaky = false;
+        errorClass = classifyFailure(results);
+    }
+    const attemptNo = (task.attempts.at(-1)?.attemptNo ?? 0) + 1;
+    task.attempts.push({
+        attemptNo,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        verifyPass: passed,
+        checks: results,
+        flaky: flaky || undefined,
+        errorClass,
+        escalatedFrom: task.escalatedFrom?.[0],
+    });
+    if (passed) {
+        task.status = "accepted";
+        task.lastError = undefined;
+        task.errorClass = flaky ? "flaky" : undefined;
+        refreshRunStatus(run);
+        return task;
+    }
+    const failed = requiredFailed(results);
+    const reason = failed
+        ? failed.name === "verification-snapshot" || failed.name === "verification-execution"
+            ? failed.stderr
+            : failed.timedOut
+                ? `${failed.name} timed out`
+                : `${failed.name} failed (exit ${failed.exitCode})`
+        : "verify failed";
+    task.lastError = reason;
+    task.errorClass = errorClass ?? classifyFailure(results, reason);
+    const maxAttempts = 1 + run.config.retry.max;
+    if (shouldBlockWithoutRetry(task.errorClass) || attemptNo >= maxAttempts) {
+        task.status = "blocked";
+    }
+    else {
+        task.status = "retrying";
+    }
+    refreshRunStatus(run);
+    return task;
+}
+export async function verifyAll(run, opts) {
+    const ids = Object.values(run.tasks)
+        .filter((task) => task.status === "claimed" || task.status === "retrying")
+        .map((task) => task.id);
+    const out = [];
+    for (const id of ids) {
+        out.push(await verifyTask(run, id, opts));
+    }
+    return out;
+}
+export function retryTask(run, taskId) {
+    const task = requireTask(run, taskId);
+    if (task.workerOutcome === "failed") {
+        throw new GateError(`task ${taskId} has worker_done outcome=failed; require a new successful claim`);
+    }
+    if (task.status === "accepted" || task.status === "integrated") {
+        throw new GateError(`task ${taskId} is ${task.status}; nothing to retry`);
+    }
+    if (task.status !== "retrying" && task.status !== "blocked" && task.status !== "repairing") {
+        throw new GateError(`task ${taskId} is ${task.status}; claim/verify first`);
+    }
+    if (task.status === "blocked" && isMergeFailure(task)) {
+        task.status = "retrying";
+        if (run.integration?.status === "conflict" || run.integration?.status === "failed" || run.integration?.status === "repairing") {
+            run.integration.status = "pending";
+        }
+        refreshRunStatus(run);
+        return task;
+    }
+    if (task.errorClass && shouldBlockWithoutRetry(task.errorClass)) {
+        throw new GateError(`task ${taskId} is blocked as ${task.errorClass}; not retrying`);
+    }
+    const maxAttempts = 1 + run.config.retry.max;
+    if (task.attempts.length >= maxAttempts && task.status === "blocked") {
+        throw new GateError(`task ${taskId} is blocked after ${task.attempts.length} verify attempt(s)`);
+    }
+    task.status = "retrying";
+    refreshRunStatus(run);
+    return task;
+}
+export function isMergeFailure(task) {
+    const err = task.lastError ?? "";
+    return (task.errorClass === "merge_conflict" ||
+        err.startsWith("merge conflict") ||
+        err.startsWith("merge failed:"));
+}
+export function requireTask(run, taskId) {
+    const task = run.tasks[taskId];
+    if (!task)
+        throw new GateError(`task not found: ${taskId}`);
+    return task;
+}
+export function refreshRunStatus(run) {
+    run.status = deriveRunStatus(run);
+}
+export function deriveRunStatus(run) {
+    const tasks = Object.values(run.tasks);
+    if (run.status === "cleaned")
+        return "cleaned";
+    if (run.status === "cleaning")
+        return "cleaning";
+    if (tasks.length === 0)
+        return run.plan ? "planned" : "running";
+    if (tasks.every((task) => task.status === "planned"))
+        return "planned";
+    const integrationFailed = run.integration?.status === "failed" || run.integration?.status === "conflict";
+    if (integrationFailed)
+        return "failed";
+    if (run.integration?.status === "passed") {
+        const allIntegrated = tasks.every((task) => task.status === "integrated" || task.status === "blocked");
+        if (allIntegrated && tasks.some((task) => task.status === "integrated")) {
+            return tasks.some((task) => task.status === "blocked") ? "partial" : "success";
+        }
+    }
+    const allBlocked = tasks.every((task) => task.status === "blocked");
+    if (allBlocked)
+        return "failed";
+    const someBlocked = tasks.some((task) => task.status === "blocked");
+    const pending = tasks.some((task) => task.status === "planned" ||
+        task.status === "dispatched" ||
+        task.status === "claimed" ||
+        task.status === "verifying" ||
+        task.status === "retrying" ||
+        task.status === "repairing");
+    if (pending)
+        return someBlocked ? "partial" : "running";
+    const allAccepted = tasks.every((task) => task.status === "accepted" || task.status === "integrated");
+    if (allAccepted)
+        return "running";
+    return someBlocked ? "partial" : "running";
+}
+export function withConfig(run, config) {
+    run.config = config;
+}
+function snapshotFailure(message) {
+    return {
+        name: "verification-snapshot",
+        command: "git snapshot",
+        required: true,
+        exitCode: 1,
+        passed: false,
+        timedOut: false,
+        durationMs: 0,
+        stdout: "",
+        stderr: message,
+    };
+}
+function executionFailure(message) {
+    return {
+        name: "verification-execution",
+        command: "task verification",
+        required: true,
+        exitCode: 1,
+        passed: false,
+        timedOut: false,
+        durationMs: 0,
+        stdout: "",
+        stderr: message,
+    };
+}
+function finalizeFailedVerification(run, task, startedAt, results) {
+    const attemptNo = (task.attempts.at(-1)?.attemptNo ?? 0) + 1;
+    const reason = requiredFailed(results)?.stderr || "verify failed";
+    task.attempts.push({
+        attemptNo,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        verifyPass: false,
+        checks: results,
+        errorClass: classifyFailure(results, reason),
+        escalatedFrom: task.escalatedFrom?.[0],
+    });
+    task.lastError = reason;
+    task.errorClass = classifyFailure(results, reason);
+    const maxAttempts = 1 + run.config.retry.max;
+    task.status =
+        shouldBlockWithoutRetry(task.errorClass) || attemptNo >= maxAttempts
+            ? "blocked"
+            : "retrying";
+    refreshRunStatus(run);
+    return task;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/git.d.ts

@@ -0,0 +1,19 @@
+export type GitSnapshot = {
+    headSha?: string;
+    dirty: boolean;
+};
+export declare function snapshot(cwd: string): Promise<GitSnapshot>;
+export declare function currentSha(cwd: string): Promise<string>;
+export declare function fetchSha(into: string, from: string, sha: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;
+export declare function mergeCommit(into: string, sha: string, message: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    conflict: boolean;
+    error: string;
+}>;