acpus 0.0.1 → 0.1.0

package/README.md

@@ -1,97 +1,13 @@
-<p align="center">
-  <img src="page/logo/logo-opus-mark.svg" alt="Acpus mark" width="120">
-</p>
+# acpus
 
-<h1 align="center">Acpus</h1>
-<p align="center" font-style="italic">Every run is an opus.</p>
+The `acpus` package provides the Acpus CLI for local durable ACP agent workflows.
 
-Acpus is a runtime-driven workflow orchestrator for ACP agents, built on the acpx agent runtime. You hand it a *workflow spec*; Acpus validates it, compiles a deterministic execution plan, conducts heterogeneous fanout across lanes, and tracks every run as a numbered, replayable execution, or say, an *opus*.
+Install:
 
-## Quick Start
-
-```bash
-# Install
+```sh
 npm install -g acpus
-
-# Validate a workflow spec
-acpus validate --spec workflows/examples/simple-feature.workflow.spec.json
-
-# Preview the execution plan
-acpus preview --spec workflows/examples/simple-feature.workflow.spec.json
-
-# Run the workflow
-acpus run --spec workflows/examples/simple-feature.workflow.spec.json
-
-# Follow a running workflow in real time
-acpus follow <logical-run-id>
 ```
 
-## Skill
-
-```bash
-npx skills add kelvinschen/acpus --skill acpus
-```
-
-## Commands
-
-Acpus commands are grouped by four verbs.
-
-### Compose — validate, preview, save, generate
-
-| Command | Purpose |
-|---|---|
-| `acpus validate --spec <path>` | Validate a workflow spec against the schema |
-| `acpus preview --spec <path>` | Render the compiled execution plan without running |
-| `acpus save <name> --spec <path>` | Save a spec to the local store |
-| `acpus generate` | Scaffold a new workflow spec from a template |
-
-### Conduct — run, follow, monitor, resume
-
-| Command | Purpose |
-|---|---|
-| `acpus run --spec <path>` | Execute a workflow spec end-to-end |
-| `acpus follow <run-id>` | Attach to a running workflow and stream output |
-| `acpus monitor <run-id>` | Open the terminal UI for run inspection |
-| `acpus resume <run-id>` | Resume an interrupted or failed run from last checkpoint |
-
-### Recover — recover, diagnose
-
-| Command | Purpose |
-|---|---|
-| `acpus recover <run-id>` | Attempt automatic repair of a failed run |
-| `acpus diagnose <run-id> [--wait]` | Produce a structured diagnosis of a completed or running run |
-
-### Catalogue — list, show
-
-| Command | Purpose |
-|---|---|
-| `acpus list` | List saved specs and historical runs |
-| `acpus show <id>` | Display details of a saved spec or past run |
-
-## Architecture
-
-Acpus sits between the author and the acpx runtime. The main agent produces a *workflow spec*. Acpus reads it, validates it against the JSON schema, and compiles it into an *execution plan* — a deterministic sequence of stages, each containing parallel lanes that map to independent acpx sessions.
-
-Run directories live under `.acpus/runs/<id>/`. Each contains:
-
-- `workflow.spec.json` — the original workflow spec
-- `execution-plan.json` — the compiled plan
-- `input.json` — resolved inputs at launch time
-- `outputs/` — stage outputs and final artefacts
-- `attempts/` — raw attempt records with agent transcripts
-- `acpx-state/` — run-local acpx session state
-- `sessions/` — per-lane session logs
-- `events.ndjson` — timestamped event log for the entire run
-
-The orchestrator does not generate or execute ACPX flow files directly. It drives acpx through its runtime API.
-
-## Documentation
-
-- [Developer documentation](docs/README.md)
-- [Design and implementation specifications](specs/INDEX.md)
-- [CLI guide](docs/cli.md)
-- [Error code guide](docs/error-codes.md)
-
-## License
+Use it to lint Workflow Specs, run Workflows, inspect Runs, control Runs, replay persisted Runs, and open the terminal visualizer.
 
-MIT
+See the repository README for full usage: https://github.com/kelvinschen/acpus

package/dist/catalog.d.ts

@@ -0,0 +1,27 @@
+import { type Diagnostic } from "@acpus/core";
+export type WorkflowCatalogScope = "project" | "global";
+export type WorkflowCatalogStatus = "ready" | "invalid" | "conflict";
+export interface WorkflowCatalogEntry {
+    scope: WorkflowCatalogScope;
+    ref?: string;
+    name?: string;
+    description?: string;
+    input?: Record<string, unknown>;
+    inputKeys: string[];
+    path: string;
+    status: WorkflowCatalogStatus;
+    diagnostics: Diagnostic[];
+}
+export interface ResolvedWorkflowTarget {
+    sourcePath: string;
+    source: string;
+    workflowRef?: string;
+}
+export declare function projectWorkflowRoot(workspace?: string): string;
+export declare function globalWorkflowRoot(): string;
+export declare function listWorkflowCatalog(workspace?: string): WorkflowCatalogEntry[];
+export declare function resolveWorkflowTarget(target: string, workspace?: string): ResolvedWorkflowTarget;
+export declare function findWorkflowCatalogEntry(target: string, workspace?: string): WorkflowCatalogEntry;
+export declare function looksLikeWorkflowPath(target: string): boolean;
+export declare function resolveWorkflowPath(path: string): string;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,KAAK,UAAU,EAAmB,MAAM,aAAa,CAAC;AAG7E,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,QAAQ,CAAC;AACxD,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,CAAC;AAErE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,oBAAoB,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,qBAAqB,CAAC;IAC9B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,mBAAmB,CAAC,SAAS,SAAgB,GAAG,MAAM,CAErE;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,wBAAgB,mBAAmB,CAAC,SAAS,SAAgB,GAAG,oBAAoB,EAAE,CA+BrF;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAAgB,GAAG,sBAAsB,CAyBvG;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAAgB,GAAG,oBAAoB,CAUxG;AA+FD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAO7D;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQxD"}

package/dist/catalog.js

@@ -0,0 +1,189 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { lintWorkflow } from "@acpus/core";
+import { createIncludeResolver } from "./io.js";
+export function projectWorkflowRoot(workspace = process.cwd()) {
+    return resolve(workspace, ".acpus", "workflows");
+}
+export function globalWorkflowRoot() {
+    return resolve(homedir(), ".acpus", "workflows");
+}
+export function listWorkflowCatalog(workspace = process.cwd()) {
+    const allowedSourceRoots = [resolve(workspace), globalWorkflowRoot()];
+    const entries = [
+        ...scanScope("project", projectWorkflowRoot(workspace), allowedSourceRoots),
+        ...scanScope("global", globalWorkflowRoot(), allowedSourceRoots)
+    ];
+    for (const scope of ["project", "global"]) {
+        const byName = new Map();
+        for (const entry of entries) {
+            if (entry.scope !== scope || !entry.name || entry.status === "invalid")
+                continue;
+            const group = byName.get(entry.name) ?? [];
+            group.push(entry);
+            byName.set(entry.name, group);
+        }
+        for (const [name, group] of byName) {
+            if (group.length <= 1)
+                continue;
+            for (const entry of group) {
+                entry.status = "conflict";
+                entry.ref = undefined;
+                entry.diagnostics = [{
+                        severity: "error",
+                        code: "CATALOG_CONFLICT",
+                        message: `Workflow name '${name}' is duplicated in ${scope} catalog.`,
+                        path: "$.name"
+                    }];
+            }
+        }
+    }
+    return entries;
+}
+export function resolveWorkflowTarget(target, workspace = process.cwd()) {
+    if (looksLikeWorkflowPath(target)) {
+        const sourcePath = resolveWorkflowPath(target);
+        return { sourcePath, source: readFileSync(sourcePath, "utf8") };
+    }
+    const catalog = listWorkflowCatalog(workspace);
+    const matches = catalog.filter((entry) => entry.status === "ready" && matchesCatalogTarget(entry, target));
+    if (matches.length === 0) {
+        const blocked = catalog.find((entry) => matchesCatalogTarget(entry, target));
+        if (blocked) {
+            throw new Error(`Workflow '${target}' is ${blocked.status}: ${blocked.diagnostics.map((d) => d.message).join("; ")}`);
+        }
+        throw new Error(`Workflow '${target}' was not found in the Workflow Catalog.`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`Workflow short name '${target}' is ambiguous; use a full ref such as ${matches.map((m) => m.ref).join(" or ")}.`);
+    }
+    const entry = matches[0];
+    return {
+        sourcePath: entry.path,
+        source: readFileSync(entry.path, "utf8"),
+        workflowRef: entry.ref
+    };
+}
+export function findWorkflowCatalogEntry(target, workspace = process.cwd()) {
+    const catalog = listWorkflowCatalog(workspace);
+    const matches = catalog.filter((entry) => matchesCatalogTarget(entry, target));
+    if (matches.length === 0) {
+        throw new Error(`Workflow '${target}' was not found in the Workflow Catalog.`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`Workflow name '${target}' is ambiguous; use a full ref when available.`);
+    }
+    return matches[0];
+}
+function matchesCatalogTarget(entry, target) {
+    return entry.ref === target || entry.name === target || (entry.name !== undefined && `${entry.scope}:${entry.name}` === target);
+}
+function scanScope(scope, root, allowedSourceRoots) {
+    if (!existsSync(root))
+        return [];
+    const files = collectCandidateFiles(root);
+    return files.map((file) => entryFromFile(scope, file, allowedSourceRoots));
+}
+function collectCandidateFiles(root) {
+    const out = [];
+    const visit = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                visit(path);
+            }
+            else if (entry.isFile() && isWorkflowCandidate(entry.name)) {
+                out.push(path);
+            }
+        }
+    };
+    visit(root);
+    return out.sort();
+}
+function entryFromFile(scope, path, allowedSourceRoots) {
+    const source = readFileSync(path, "utf8");
+    const parsed = parseSpecSummary(source);
+    const lint = lintCatalogEntry(source, path, allowedSourceRoots);
+    const name = parsed.name;
+    const status = lint.ok && name ? "ready" : "invalid";
+    return {
+        scope,
+        ref: status === "ready" ? `${scope}:${name}` : undefined,
+        name,
+        description: parsed.description,
+        input: parsed.input,
+        inputKeys: Object.keys(parsed.input ?? {}),
+        path,
+        status,
+        diagnostics: lint.ok && !name
+            ? [{ severity: "error", code: "CATALOG_NAME", message: "Workflow Spec must declare a string name.", path: "$.name" }]
+            : lint.diagnostics
+    };
+}
+function lintCatalogEntry(source, path, allowedSourceRoots) {
+    try {
+        return lintWorkflow(source, {
+            sourcePath: path,
+            includeResolver: createIncludeResolver(allowedSourceRoots)
+        });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            diagnostics: [{
+                    severity: "error",
+                    code: "CATALOG_LINT",
+                    message: error instanceof Error ? error.message : String(error),
+                    path: "$"
+                }]
+        };
+    }
+}
+function parseSpecSummary(source) {
+    try {
+        const parsed = parseYaml(source);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return {};
+        const map = parsed;
+        return {
+            name: typeof map.name === "string" ? map.name : undefined,
+            description: typeof map.description === "string" ? map.description : undefined,
+            input: typeof map.input === "object" && map.input !== null && !Array.isArray(map.input)
+                ? map.input
+                : undefined
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function isWorkflowCandidate(filename) {
+    return filename === "workflow.yaml"
+        || filename === "workflow.yml"
+        || filename.endsWith(".workflow.yaml")
+        || filename.endsWith(".workflow.yml")
+        || filename.endsWith(".workflow.spec.yaml")
+        || filename.endsWith(".workflow.spec.yml");
+}
+export function looksLikeWorkflowPath(target) {
+    return target.startsWith(".")
+        || target.startsWith("/")
+        || target.startsWith("~")
+        || target.includes("/")
+        || target.endsWith(".yaml")
+        || target.endsWith(".yml");
+}
+export function resolveWorkflowPath(path) {
+    if (path === "~")
+        return homedir();
+    if (path.startsWith("~/"))
+        return resolve(homedir(), path.slice(2));
+    const resolved = resolve(process.cwd(), path);
+    if (!existsSync(resolved) || !statSync(resolved).isFile()) {
+        throw new Error(`Workflow Spec path not found: ${path}`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}

package/dist/follow.d.ts

@@ -0,0 +1,23 @@
+/**
+ * FollowLoop — polls a running Run and emits observations to stdout.
+ *
+ * Used by `acpus workflows run <spec>` (foreground follow mode) and
+ * `acpus workflows run <spec> --json`.
+ * Tracks node state changes and deduplicates: only emits when a node is first
+ * observed or when its state changes.
+ *
+ * Ctrl-C detaches (exit 0) without cancelling the Run.
+ */
+import type { RunSupervisorClient, RunStatus } from "@acpus/runtime";
+export interface FollowOptions {
+    /** Emit JSONL observations instead of human-readable glyphs */
+    json?: boolean;
+    /** Polling interval in milliseconds (default 400) */
+    intervalMs?: number;
+}
+/**
+ * Run a follow loop until the Run reaches a terminal state.
+ * Returns the terminal RunStatus for exit-code mapping.
+ */
+export declare function followRun(client: RunSupervisorClient, runId: string, options?: FollowOptions): Promise<RunStatus>;
+//# sourceMappingURL=follow.d.ts.map

package/dist/follow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"follow.d.ts","sourceRoot":"","sources":["../src/follow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAgC,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGnG,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,SAAS,CAAC,CAuFpB"}

package/dist/follow.js

@@ -0,0 +1,109 @@
+/**
+ * FollowLoop — polls a running Run and emits observations to stdout.
+ *
+ * Used by `acpus workflows run <spec>` (foreground follow mode) and
+ * `acpus workflows run <spec> --json`.
+ * Tracks node state changes and deduplicates: only emits when a node is first
+ * observed or when its state changes.
+ *
+ * Ctrl-C detaches (exit 0) without cancelling the Run.
+ */
+import { formatObservation, formatTerminalSummary } from "./observations.js";
+/**
+ * Run a follow loop until the Run reaches a terminal state.
+ * Returns the terminal RunStatus for exit-code mapping.
+ */
+export async function followRun(client, runId, options = {}) {
+    const intervalMs = options.intervalMs ?? 400;
+    // Pin the supervisor alive while following
+    client.clientKind = "follow";
+    const lastObserved = new Map();
+    let lastRunStatus;
+    let runName = "";
+    // Register Ctrl-C handler: detach (exit 0) without cancelling
+    let detached = false;
+    const onSigint = () => {
+        detached = true;
+        process.off("SIGINT", onSigint);
+        // Don't call process.exit(0) here — it skips the finally block and
+        // prevents cleanup. Instead, set the flag and let the loop exit naturally.
+    };
+    process.on("SIGINT", onSigint);
+    try {
+        for (;;) {
+            if (detached) {
+                // Ctrl-C detach: the Run continues in the background supervisor.
+                // Return a non-terminal status so the caller maps to exit 0.
+                return "running";
+            }
+            let run;
+            let nodes;
+            try {
+                [run, nodes] = await Promise.all([
+                    client.getRun(runId),
+                    client.getNodeStates(runId)
+                ]);
+            }
+            catch (err) {
+                // Transient fetch error — retry after interval
+                if (!options.json) {
+                    process.stderr.write(`⚠ poll error: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+                await new Promise((r) => setTimeout(r, intervalMs));
+                continue;
+            }
+            runName = run.workflowName;
+            // Emit Run-level observation on first poll or status change.
+            // Terminal states are handled by formatTerminalSummary below; skip here
+            // to avoid duplicate "Run ... completed" lines with different glyphs.
+            if (lastRunStatus === undefined || run.status !== lastRunStatus) {
+                if (!isTerminal(run.status)) {
+                    const event = { type: "run", runId, status: run.status };
+                    emit(formatObservation(event, runName, options.json));
+                }
+                lastRunStatus = run.status;
+            }
+            // Emit Node-level observations for new/changed nodes
+            for (const node of nodes) {
+                const prev = lastObserved.get(node.nodeKey);
+                if (!prev || prev.state !== node.state) {
+                    const duration = computeDuration(node);
+                    const event = {
+                        type: "node",
+                        nodeKey: node.nodeKey,
+                        state: node.state,
+                        duration,
+                        error: node.error
+                    };
+                    emit(formatObservation(event, undefined, options.json));
+                }
+                lastObserved.set(node.nodeKey, node);
+            }
+            // Check if Run is terminal
+            if (isTerminal(run.status)) {
+                const summary = formatTerminalSummary(runId, run.status, runName, options.json);
+                emit(summary);
+                return run.status;
+            }
+            // Wait before next poll
+            await new Promise((r) => setTimeout(r, intervalMs));
+        }
+    }
+    finally {
+        process.off("SIGINT", onSigint);
+    }
+}
+function emit(line) {
+    process.stdout.write(line + "\n");
+}
+function isTerminal(status) {
+    return status === "completed" || status === "failed" || status === "cancelled" || status === "paused";
+}
+function computeDuration(node) {
+    if (!node.startedAt)
+        return undefined;
+    const start = Date.parse(node.startedAt);
+    const end = node.completedAt ? Date.parse(node.completedAt) : Date.now();
+    return end - start;
+}
+//# sourceMappingURL=follow.js.map

package/dist/follow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"follow.js","sourceRoot":"","sources":["../src/follow.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}