rich-parallel-agents 0.1.0

package/dist/plan.js

@@ -0,0 +1,114 @@
+import { readFile } from "node:fs/promises";
+import { GateError } from "./errors.js";
+export async function loadPlanFile(file) {
+    const raw = JSON.parse(await readFile(file, "utf8"));
+    return parsePlan(raw);
+}
+export function parsePlan(raw) {
+    if (!raw || typeof raw !== "object")
+        throw new GateError("plan must be an object");
+    const rec = raw;
+    const tasksRaw = rec.tasks ?? (Array.isArray(raw) ? raw : undefined);
+    if (tasksRaw && !Array.isArray(tasksRaw))
+        throw new GateError("plan.tasks must be an array");
+    const tasks = (tasksRaw ?? []).map((item, index) => parsePlanTask(item, index));
+    if (tasks.length === 0 && typeof rec.id === "string") {
+        return {
+            objective: asString(rec.title) ?? asString(rec.objective),
+            tasks: [parsePlanTask(rec, 0)],
+        };
+    }
+    return {
+        objective: asString(rec.objective),
+        planner: asString(rec.planner),
+        tasks,
+    };
+}
+function parsePlanTask(item, index) {
+    if (!item || typeof item !== "object")
+        throw new GateError(`plan task ${index} must be an object`);
+    const rec = item;
+    const id = asString(rec.id) ?? slug(asString(rec.title) ?? `task-${index + 1}`, index);
+    const title = asString(rec.title) ?? id;
+    const scopeRec = rec.scope && typeof rec.scope === "object" ? rec.scope : undefined;
+    return {
+        id,
+        title,
+        agent: asString(rec.agent),
+        mode: asString(rec.mode),
+        deliverable: asString(rec.deliverable),
+        deps: Array.isArray(rec.deps) ? rec.deps.filter((d) => typeof d === "string") : undefined,
+        worktree: asString(rec.worktree),
+        scope: scopeRec
+            ? {
+                paths: Array.isArray(scopeRec.paths)
+                    ? scopeRec.paths.filter((p) => typeof p === "string")
+                    : undefined,
+            }
+            : undefined,
+    };
+}
+export function decomposeObjective(objective, planner) {
+    const lines = objective
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const bullet = lines.filter((line) => /^(?:[-*]|\d+[.)])\s+/.test(line));
+    const titles = (bullet.length > 1 ? bullet : [objective.trim()]).map((line) => line.replace(/^\s*(?:[-*]|\d+[.)])\s+/, "").trim());
+    const tasks = titles.filter(Boolean).map((title, index) => ({
+        id: slug(title, index),
+        title,
+        deliverable: title,
+    }));
+    return { objective, planner, tasks: tasks.length ? tasks : [{ id: "task-1", title: objective, deliverable: objective }] };
+}
+export function applyPlan(run, plan) {
+    run.plan = plan;
+    run.objective = plan.objective ?? run.objective;
+    run.planner = plan.planner ?? run.planner;
+    if (run.status !== "cleaned" && run.status !== "success" && run.status !== "failed") {
+        run.status = "planned";
+    }
+    const created = [];
+    for (const item of plan.tasks) {
+        const existing = run.tasks[item.id];
+        if (existing && (existing.status === "accepted" || existing.status === "integrated"))
+            continue;
+        const task = {
+            id: item.id,
+            status: "planned",
+            worktree: item.worktree ?? run.repo,
+            agent: item.agent,
+            workerOutcome: "pending",
+            attempts: existing?.attempts ?? [],
+            title: item.title,
+            deliverable: item.deliverable,
+            deps: item.deps,
+        };
+        run.tasks[item.id] = task;
+        created.push(task);
+    }
+    return created;
+}
+export function readyPlanTasks(run) {
+    return Object.values(run.tasks).filter((task) => {
+        if (task.status !== "planned")
+            return false;
+        const deps = task.deps ?? [];
+        return deps.every((dep) => {
+            const other = run.tasks[dep];
+            return other?.status === "accepted" || other?.status === "integrated";
+        });
+    });
+}
+function asString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function slug(title, index) {
+    const base = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 40);
+    return base || `task-${index + 1}`;
+}

package/dist/repair.d.ts

@@ -0,0 +1,13 @@
+import { type OrcaExec } from "./orca.js";
+import type { RunState, TaskState } from "./types.js";
+export declare function createRepairTask(run: RunState, fromIds: string[]): TaskState;
+export declare function startIntegrationRepair(run: RunState, opts?: {
+    fromIds?: string[];
+    orca?: boolean;
+    orcaBin?: string;
+    orcaExec?: OrcaExec;
+    agent?: string;
+}): Promise<{
+    task: TaskState;
+    orca?: string;
+}>;

package/dist/repair.js

@@ -0,0 +1,110 @@
+import { GateError } from "./errors.js";
+import { refreshRunStatus } from "./gate.js";
+import { startOrcaRepair } from "./orca.js";
+import { addResource } from "./resources.js";
+export function createRepairTask(run, fromIds) {
+    if (fromIds.length === 0)
+        throw new GateError("repair requires at least one blocked task");
+    if (new Set(fromIds).size !== fromIds.length) {
+        throw new GateError("repair source task ids must be unique");
+    }
+    for (const taskId of fromIds) {
+        const source = run.tasks[taskId];
+        if (!source)
+            throw new GateError(`repair source task not found: ${taskId}`);
+        const failedIntegrationSource = source.status === "integrated" &&
+            run.integration?.status === "failed" &&
+            run.integration.mergedTaskIds.includes(taskId);
+        if (source.status !== "blocked" && !failedIntegrationSource) {
+            throw new GateError(`repair source task ${taskId} is ${source.status}; expected blocked`);
+        }
+    }
+    let n = 1;
+    while (run.tasks[`integration_repair_${n}`])
+        n += 1;
+    const id = `integration_repair_${n}`;
+    const evidence = fromIds
+        .map((taskId) => {
+        const task = run.tasks[taskId];
+        return `${taskId}: ${task.lastError ??
+            (task.status === "integrated" ? run.integration?.error : undefined) ??
+            "blocked"}`;
+    })
+        .join("\n");
+    const task = {
+        id,
+        status: "planned",
+        worktree: run.integration?.into ?? run.repo,
+        workerOutcome: "pending",
+        attempts: [],
+        title: "integration repair",
+        deliverable: `resolve integration failure for ${fromIds.join(", ")}`,
+        escalatedFrom: fromIds,
+        lastError: evidence,
+        errorClass: "merge_conflict",
+    };
+    run.tasks[id] = task;
+    if (run.integration)
+        run.integration.status = "repairing";
+    refreshRunStatus(run);
+    return task;
+}
+export async function startIntegrationRepair(run, opts = {}) {
+    const fromIds = opts.fromIds ??
+        (() => {
+            const blocked = Object.values(run.tasks)
+                .filter((task) => task.status === "blocked")
+                .map((task) => task.id);
+            if (blocked.length > 0)
+                return blocked;
+            if (run.integration?.status === "failed") {
+                return run.integration.mergedTaskIds.filter((taskId) => run.tasks[taskId]?.status === "integrated");
+            }
+            return blocked;
+        })();
+    const previousIntegration = run.integration
+        ? { status: run.integration.status, error: run.integration.error }
+        : undefined;
+    const task = createRepairTask(run, fromIds);
+    task.status = "repairing";
+    task.agent = opts.agent ?? task.agent;
+    if (opts.orca) {
+        try {
+            const orca = await startOrcaRepair(task, fromIds, {
+                orcaBin: opts.orcaBin,
+                exec: opts.orcaExec,
+            });
+            const dispatchId = task.dispatchId;
+            if (!dispatchId) {
+                throw new GateError(`repair task ${task.id} has no Orca dispatch id`);
+            }
+            addResource(run, {
+                id: `dispatch:${task.id}:${dispatchId}`,
+                kind: "dispatch",
+                selector: dispatchId,
+                taskId: task.id,
+            });
+            return { task, orca };
+        }
+        catch (err) {
+            task.status = "blocked";
+            task.workerOutcome = "failed";
+            task.lastError = `${task.lastError ?? ""}\nOrca repair dispatch failed: ${errorMessage(err)}`.trim();
+            task.errorClass = "unknown";
+            if (run.integration && previousIntegration) {
+                run.integration.status =
+                    previousIntegration.status === "repairing" ? "failed" : previousIntegration.status;
+                run.integration.error =
+                    previousIntegration.status === "repairing"
+                        ? previousIntegration.error ?? task.lastError
+                        : previousIntegration.error;
+            }
+            refreshRunStatus(run);
+            throw err;
+        }
+    }
+    return { task };
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/resources.d.ts

@@ -0,0 +1,8 @@
+import type { ResourceRecord, RunState } from "./types.js";
+export declare function addResource(run: RunState, input: Omit<ResourceRecord, "createdBy" | "createdAt" | "lastHeartbeatAt" | "leaseExpiresAt" | "runId"> & {
+    leaseExpiresAt?: string;
+}): ResourceRecord;
+export declare function heartbeat(run: RunState): void;
+export declare function expiredResources(run: RunState, now?: number): ResourceRecord[];
+export declare function markCleaned(run: RunState, id: string): ResourceRecord | undefined;
+export declare function liveResources(run: RunState, kind?: ResourceRecord["kind"]): ResourceRecord[];

package/dist/resources.js

@@ -0,0 +1,41 @@
+export function addResource(run, input) {
+    const now = new Date();
+    const ttl = run.config.lease.ttlMs;
+    const record = {
+        id: input.id,
+        kind: input.kind,
+        selector: input.selector,
+        createdBy: "rpa",
+        createdAt: now.toISOString(),
+        leaseExpiresAt: input.leaseExpiresAt ?? new Date(now.getTime() + ttl).toISOString(),
+        lastHeartbeatAt: now.toISOString(),
+        runId: run.id,
+        taskId: input.taskId,
+    };
+    run.resources = run.resources ?? [];
+    run.resources.push(record);
+    return record;
+}
+export function heartbeat(run) {
+    const now = new Date().toISOString();
+    run.lastHeartbeatAt = now;
+    for (const resource of run.resources ?? []) {
+        if (resource.cleanedAt)
+            continue;
+        resource.lastHeartbeatAt = now;
+        resource.leaseExpiresAt = new Date(Date.now() + run.config.lease.ttlMs).toISOString();
+    }
+}
+export function expiredResources(run, now = Date.now()) {
+    return (run.resources ?? []).filter((resource) => !resource.cleanedAt && Date.parse(resource.leaseExpiresAt) <= now);
+}
+export function markCleaned(run, id) {
+    const resource = (run.resources ?? []).find((item) => item.id === id);
+    if (!resource)
+        return undefined;
+    resource.cleanedAt = new Date().toISOString();
+    return resource;
+}
+export function liveResources(run, kind) {
+    return (run.resources ?? []).filter((resource) => !resource.cleanedAt && resource.createdBy === "rpa" && (kind ? resource.kind === kind : true));
+}

package/dist/resume.d.ts

@@ -0,0 +1,12 @@
+import { type OrcaOpts } from "./orca.js";
+import type { ExecFn, RunState, TaskState } from "./types.js";
+export type ResumeOpts = {
+    storeDir: string;
+    run: RunState;
+    exec: ExecFn;
+    orca?: boolean;
+    orcaBin?: string;
+    orcaExec?: OrcaOpts["exec"];
+};
+export declare function resumeRun(opts: ResumeOpts): Promise<RunState>;
+export declare function reconcileOrca(run: RunState, opts: Omit<ResumeOpts, "exec">): Promise<TaskState[]>;

package/dist/resume.js

@@ -0,0 +1,129 @@
+import { GateError } from "./errors.js";
+import { refreshRunStatus, verifyAll } from "./gate.js";
+import { listOrcaWorkers } from "./orca.js";
+import { persist } from "./store.js";
+export async function resumeRun(opts) {
+    const { run } = opts;
+    await persist(opts.storeDir, run, { type: "RUN_RESUMED", payload: {} });
+    if (opts.orca) {
+        await reconcileOrca(run, opts);
+    }
+    else {
+        await failClosedIncompleteDispatches(run, opts.storeDir);
+    }
+    const verified = await verifyAll(run, { exec: opts.exec });
+    refreshRunStatus(run);
+    await persist(opts.storeDir, run, {
+        type: "HEARTBEAT",
+        payload: { verified: verified.map((task) => task.id) },
+    });
+    return run;
+}
+export async function reconcileOrca(run, opts) {
+    const touched = await failClosedIncompleteDispatches(run, opts.storeDir);
+    let ids;
+    try {
+        const workersRaw = await listOrcaWorkers({ orcaBin: opts.orcaBin, exec: opts.orcaExec });
+        ids = extractWorkerIds(workersRaw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const evidence = message.startsWith("resume reconcile failed:")
+            ? message
+            : `resume reconcile failed: ${message}`;
+        for (const task of touched) {
+            if (task.status === "dispatched") {
+                blockDispatch(task, `${evidence}; worker presence is unknown, inspect Orca state and resolve manually`);
+            }
+        }
+        refreshRunStatus(run);
+        await persist(opts.storeDir, run, {
+            type: "HEARTBEAT",
+            payload: { reconcileError: evidence },
+        });
+        throw new GateError(evidence);
+    }
+    for (const task of touched) {
+        if (task.status === "dispatched") {
+            if (task.dispatchId && !ids.has(task.dispatchId)) {
+                blockDispatch(task, `orca worker ${task.dispatchId} missing during reconcile; inspect Orca state and resolve manually`);
+            }
+        }
+    }
+    refreshRunStatus(run);
+    await persist(opts.storeDir, run, {
+        type: "HEARTBEAT",
+        payload: { reconciled: touched.map((task) => task.id) },
+    });
+    return touched;
+}
+async function failClosedIncompleteDispatches(run, storeDir) {
+    const touched = [];
+    for (const task of Object.values(run.tasks)) {
+        if (task.status !== "dispatched" && task.status !== "claimed" && task.status !== "repairing")
+            continue;
+        if (task.status === "dispatched") {
+            if (task.dispatchPhase === "intent" || task.dispatchPhase === "task-created") {
+                const identity = task.dispatchPhase === "task-created"
+                    ? `; Orca task ${task.orcaTaskId ?? "identity missing"} may already exist`
+                    : "";
+                blockDispatch(task, `orca dispatch stopped in ${task.dispatchPhase} phase${identity}; inspect Orca state and resolve manually to avoid duplicate dispatch`);
+            }
+            else if (!task.dispatchId) {
+                blockDispatch(task, `orca worker identity missing for ${task.dispatchPhase ?? "unknown"} dispatch phase; inspect Orca state and resolve manually`);
+            }
+        }
+        touched.push(task);
+    }
+    refreshRunStatus(run);
+    await persist(storeDir, run, {
+        type: "HEARTBEAT",
+        payload: { reconciledLocalDispatches: touched.map((task) => task.id) },
+    });
+    return touched;
+}
+function blockDispatch(task, evidence) {
+    task.status = "blocked";
+    task.dispatchPhase = "failed";
+    task.lastError = evidence;
+    task.errorClass = "environment";
+}
+function extractWorkerIds(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new GateError(`resume reconcile failed: orca worker-list returned malformed JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new GateError("resume reconcile failed: orca worker-list response must be an object");
+    }
+    const response = parsed;
+    const result = "result" in response ? response.result : response;
+    if (!result || typeof result !== "object" || Array.isArray(result)) {
+        throw new GateError("resume reconcile failed: orca worker-list result must be an object");
+    }
+    const workers = result.workers;
+    if (!Array.isArray(workers)) {
+        throw new GateError("resume reconcile failed: orca worker-list workers must be an array");
+    }
+    const ids = new Set();
+    for (const [index, worker] of workers.entries()) {
+        if (!worker || typeof worker !== "object" || Array.isArray(worker)) {
+            throw new GateError(`resume reconcile failed: orca worker-list workers[${index}] must be an object`);
+        }
+        const rec = worker;
+        let recognized = false;
+        for (const key of ["id", "dispatchId", "dispatch_id"]) {
+            if (typeof rec[key] === "string" && rec[key].trim()) {
+                ids.add(rec[key].trim());
+                recognized = true;
+            }
+        }
+        if (!recognized) {
+            throw new GateError(`resume reconcile failed: orca worker-list workers[${index}] must expose a non-empty id, dispatchId, or dispatch_id`);
+        }
+    }
+    return ids;
+}

package/dist/run.d.ts

@@ -0,0 +1,18 @@
+import { type OrcaOpts } from "./orca.js";
+import type { ExecFn, RunState } from "./types.js";
+export type RunOpts = {
+    storeDir: string;
+    run: RunState;
+    objective?: string;
+    planFile?: string;
+    planner?: string;
+    planOnly?: boolean;
+    dry?: boolean;
+    dispatch?: boolean;
+    orca?: boolean;
+    orcaBin?: string;
+    exec?: ExecFn;
+    orcaExec?: OrcaOpts["exec"];
+};
+export declare function prepareRun(opts: RunOpts): Promise<RunState>;
+export declare function dispatchReadyTasks(run: RunState, opts: RunOpts): Promise<void>;

package/dist/run.js

@@ -0,0 +1,142 @@
+import { execCommand } from "./exec.js";
+import { GateError } from "./errors.js";
+import { refreshRunStatus } from "./gate.js";
+import { createOrcaTask, startOrcaWorker } from "./orca.js";
+import { applyPlan, decomposeObjective, loadPlanFile, parsePlan, readyPlanTasks } from "./plan.js";
+import { addResource } from "./resources.js";
+import { persist, writeManifest, writePlanFile } from "./store.js";
+export async function prepareRun(opts) {
+    const plan = await resolvePlan(opts);
+    applyPlan(opts.run, plan);
+    opts.run.objective = plan.objective ?? opts.objective ?? opts.run.objective;
+    opts.run.planner = plan.planner ?? opts.planner ?? opts.run.planner;
+    refreshRunStatus(opts.run);
+    await writePlanFile(opts.storeDir, opts.run);
+    await writeManifest(opts.storeDir, opts.run);
+    await persist(opts.storeDir, opts.run, {
+        type: "PLAN_CREATED",
+        payload: { tasks: plan.tasks.map((task) => task.id), planner: plan.planner ?? null },
+    });
+    if (opts.planOnly || opts.dry)
+        return opts.run;
+    if (opts.dispatch !== false) {
+        await dispatchReadyTasks(opts.run, opts);
+    }
+    return opts.run;
+}
+export async function dispatchReadyTasks(run, opts) {
+    for (const task of readyPlanTasks(run)) {
+        task.status = "dispatched";
+        task.workerOutcome = "pending";
+        task.dispatchPhase = "intent";
+        if (opts.orca && !task.agent)
+            task.agent = "codex";
+        await persist(opts.storeDir, run, {
+            type: "TASK_DISPATCHED",
+            taskId: task.id,
+            payload: {
+                phase: "intent",
+                dispatchId: null,
+                agent: task.agent ?? null,
+                orca: Boolean(opts.orca),
+            },
+        });
+        if (opts.orca) {
+            const orcaOpts = { orcaBin: opts.orcaBin, exec: opts.orcaExec };
+            try {
+                await createOrcaTask(task, orcaOpts);
+                if (!task.orcaTaskId) {
+                    throw new GateError(`orca task-create returned no task id for task ${task.id}`);
+                }
+                task.dispatchPhase = "task-created";
+                await persist(opts.storeDir, run, {
+                    type: "TASK_DISPATCHED",
+                    taskId: task.id,
+                    payload: {
+                        phase: "task-created",
+                        orcaTaskId: task.orcaTaskId,
+                        agent: task.agent,
+                        orca: true,
+                    },
+                });
+                await startOrcaWorker(task, orcaOpts);
+                if (!task.dispatchId) {
+                    throw new GateError(`orca worker-start returned no dispatch id for task ${task.id}`);
+                }
+                task.dispatchPhase = "worker-started";
+                await persist(opts.storeDir, run, {
+                    type: "WORKER_STARTED",
+                    taskId: task.id,
+                    payload: {
+                        phase: task.dispatchPhase,
+                        orcaTaskId: task.orcaTaskId,
+                        dispatchId: task.dispatchId,
+                        agent: task.agent,
+                    },
+                });
+            }
+            catch (err) {
+                task.status = "blocked";
+                task.dispatchPhase = "failed";
+                task.lastError = `orca dispatch failed: ${err instanceof Error ? err.message : String(err)}`;
+                refreshRunStatus(run);
+                await persist(opts.storeDir, run, {
+                    type: "TASK_DISPATCHED",
+                    taskId: task.id,
+                    payload: {
+                        phase: "failed",
+                        orcaTaskId: task.orcaTaskId ?? null,
+                        dispatchId: task.dispatchId ?? null,
+                        error: task.lastError,
+                        orca: true,
+                    },
+                });
+                throw new GateError(task.lastError);
+            }
+            addResource(run, {
+                id: `dispatch:${task.id}:${task.dispatchId ?? Date.now()}`,
+                kind: "dispatch",
+                selector: task.dispatchId ?? task.id,
+                taskId: task.id,
+            });
+            addResource(run, {
+                id: `worktree:${task.id}`,
+                kind: "worktree",
+                selector: task.worktree,
+                taskId: task.id,
+            });
+            await persist(opts.storeDir, run);
+        }
+    }
+    refreshRunStatus(run);
+    await persist(opts.storeDir, run);
+}
+async function resolvePlan(opts) {
+    if (opts.planFile) {
+        const plan = await loadPlanFile(opts.planFile);
+        plan.planner = plan.planner ?? opts.planner;
+        return plan;
+    }
+    const command = plannerCommand(opts);
+    if (command && opts.objective) {
+        const exec = opts.exec ?? execCommand;
+        const output = await exec(command, opts.run.repo, 120_000);
+        if (output.exitCode !== 0) {
+            throw new GateError(`planner failed (exit ${output.exitCode}): ${output.stderr || output.stdout}`);
+        }
+        const raw = JSON.parse(output.stdout || "{}");
+        const plan = parsePlan(raw);
+        plan.objective ??= opts.objective;
+        plan.planner = opts.planner ?? command;
+        return plan;
+    }
+    if (!opts.objective)
+        throw new GateError("rpa run needs an objective or --plan");
+    return decomposeObjective(opts.objective, opts.planner);
+}
+function plannerCommand(opts) {
+    if (opts.planner && opts.planner !== "none" && opts.planner !== "heuristic" && opts.planner.includes(" ")) {
+        return opts.planner;
+    }
+    return opts.run.config.planner.command;
+}

package/dist/skill.d.ts

@@ -0,0 +1,18 @@
+export declare function packageRoot(): string;
+export declare function skillPath(): string;
+export declare function cliPath(): string;
+export declare function readSkill(): Promise<string>;
+export type SkillInstall = {
+    bin: string;
+    skills: string[];
+};
+export declare function defaultInstallTargets(home?: string): {
+    bin: string;
+    agentSkillDir: string;
+    claudeSkillDir: string;
+    codexSkillDir: string;
+};
+export declare function installSkill(opts?: {
+    home?: string;
+    cli?: string;
+}): Promise<SkillInstall>;

package/dist/skill.js

@@ -0,0 +1,70 @@
+import { chmod, mkdir, readFile, rm, stat, symlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { GateError } from "./errors.js";
+export function packageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+}
+export function skillPath() {
+    return path.join(packageRoot(), "skills", "rpa", "SKILL.md");
+}
+export function cliPath() {
+    return path.join(packageRoot(), "dist", "cli.js");
+}
+export async function readSkill() {
+    try {
+        return await readFile(skillPath(), "utf8");
+    }
+    catch {
+        throw new GateError(`skill file missing: ${skillPath()}`);
+    }
+}
+export function defaultInstallTargets(home = os.homedir()) {
+    return {
+        bin: path.join(home, ".local", "bin", "rpa"),
+        agentSkillDir: path.join(home, ".agents", "skills", "rpa"),
+        claudeSkillDir: path.join(home, ".claude", "skills", "rpa"),
+        codexSkillDir: path.join(home, ".codex", "skills", "rpa"),
+    };
+}
+async function pathExists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function replaceSymlink(dest, target) {
+    await rm(dest, { force: true, recursive: true });
+    await symlink(target, dest);
+}
+export async function installSkill(opts = {}) {
+    const cli = opts.cli ?? cliPath();
+    if (!(await pathExists(cli))) {
+        throw new GateError(`build first (missing ${cli})`);
+    }
+    const src = skillPath();
+    if (!(await pathExists(src))) {
+        throw new GateError(`skill file missing: ${src}`);
+    }
+    const { bin, agentSkillDir, claudeSkillDir, codexSkillDir } = defaultInstallTargets(opts.home);
+    await mkdir(path.dirname(bin), { recursive: true });
+    await replaceSymlink(bin, cli);
+    await chmod(cli, 0o755);
+    const skills = [];
+    await mkdir(agentSkillDir, { recursive: true });
+    const agentSkill = path.join(agentSkillDir, "SKILL.md");
+    await replaceSymlink(agentSkill, src);
+    skills.push(agentSkill);
+    await mkdir(path.dirname(claudeSkillDir), { recursive: true });
+    await replaceSymlink(claudeSkillDir, agentSkillDir);
+    skills.push(path.join(claudeSkillDir, "SKILL.md"));
+    await mkdir(codexSkillDir, { recursive: true });
+    const codexSkill = path.join(codexSkillDir, "SKILL.md");
+    await replaceSymlink(codexSkill, src);
+    skills.push(codexSkill);
+    return { bin, skills };
+}