@acpus/runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkkyran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @acpus/runtime
+
+`@acpus/runtime` contains the local durable execution engine for Acpus: the interpreter, Run Supervisor, state store, executors, artifacts, replay, and Run controls.
+
+Most users should install the `acpus` CLI package.
+
+See the repository README for full usage: https://github.com/kelvinschen/acpus

package/dist/artifacts.d.ts

@@ -0,0 +1,30 @@
+import type { ArtifactRef } from "./types.js";
+/**
+ * Local filesystem artifact store under .acpus/state/runs/<run_id>/artifacts/.
+ * Artifact URIs follow the format: artifact://runs/<runId>/nodes/<nodeKey>/<filename>
+ */
+export declare class ArtifactStore {
+    private readonly baseDir;
+    constructor(baseDir?: string);
+    /**
+     * Write an artifact file. Uses atomic write (temp + rename) for crash safety.
+     * Returns the ArtifactRef for the written file.
+     */
+    write(runId: string, nodeKey: string, filename: string, content: string | Buffer): ArtifactRef;
+    /**
+     * Create or truncate an artifact file and return its reference.
+     * Used for artifacts that will be appended while an execution is still live.
+     */
+    create(runId: string, nodeKey: string, filename: string): ArtifactRef;
+    /** Append content to an existing artifact, creating it if needed. */
+    append(runId: string, nodeKey: string, filename: string, content: string | Buffer): ArtifactRef;
+    /** Read an artifact file content. */
+    read(runId: string, nodeKey: string, filename: string): Buffer;
+    /** List all artifact refs for a node. */
+    list(runId: string, nodeKey: string): ArtifactRef[];
+    /** Parse an artifact URI into its components. */
+    parseArtifactRef(uri: string): ArtifactRef;
+    private nodeDir;
+    private makeRef;
+}
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,CAAC,EAAE,MAAM;IAI5B;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW;IAa9F;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW;IAQrE,qEAAqE;IACrE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW;IAQ/F,qCAAqC;IACrC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAM9D,yCAAyC;IACzC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE;IASnD,iDAAiD;IACjD,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW;IAqB1C,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,OAAO;CAKhB"}

package/dist/artifacts.js

@@ -0,0 +1,97 @@
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { encodeNodeKeyForDir } from "./keys.js";
+/**
+ * Local filesystem artifact store under .acpus/state/runs/<run_id>/artifacts/.
+ * Artifact URIs follow the format: artifact://runs/<runId>/nodes/<nodeKey>/<filename>
+ */
+export class ArtifactStore {
+    baseDir;
+    constructor(baseDir) {
+        this.baseDir = baseDir ?? join(process.cwd(), ".acpus", "state", "runs");
+    }
+    /**
+     * Write an artifact file. Uses atomic write (temp + rename) for crash safety.
+     * Returns the ArtifactRef for the written file.
+     */
+    write(runId, nodeKey, filename, content) {
+        validateArtifactFilename(filename);
+        const dir = this.nodeDir(runId, nodeKey);
+        mkdirSync(dir, { recursive: true });
+        const filePath = join(dir, filename);
+        const tmpPath = filePath + ".tmp";
+        writeFileSync(tmpPath, content);
+        renameSync(tmpPath, filePath);
+        return this.makeRef(runId, nodeKey, filename);
+    }
+    /**
+     * Create or truncate an artifact file and return its reference.
+     * Used for artifacts that will be appended while an execution is still live.
+     */
+    create(runId, nodeKey, filename) {
+        validateArtifactFilename(filename);
+        const dir = this.nodeDir(runId, nodeKey);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, filename), "");
+        return this.makeRef(runId, nodeKey, filename);
+    }
+    /** Append content to an existing artifact, creating it if needed. */
+    append(runId, nodeKey, filename, content) {
+        validateArtifactFilename(filename);
+        const dir = this.nodeDir(runId, nodeKey);
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(join(dir, filename), content);
+        return this.makeRef(runId, nodeKey, filename);
+    }
+    /** Read an artifact file content. */
+    read(runId, nodeKey, filename) {
+        validateArtifactFilename(filename);
+        const filePath = join(this.nodeDir(runId, nodeKey), filename);
+        return readFileSync(filePath);
+    }
+    /** List all artifact refs for a node. */
+    list(runId, nodeKey) {
+        const dir = this.nodeDir(runId, nodeKey);
+        if (!existsSync(dir))
+            return [];
+        return readdirSync(dir)
+            .filter((f) => !f.endsWith(".tmp"))
+            .map((filename) => this.makeRef(runId, nodeKey, filename));
+    }
+    /** Parse an artifact URI into its components. */
+    parseArtifactRef(uri) {
+        const prefix = "artifact://runs/";
+        if (!uri.startsWith(prefix)) {
+            throw new Error(`Invalid artifact URI: ${uri}`);
+        }
+        const rest = uri.slice(prefix.length);
+        // Format: <runId>/nodes/<nodeKey>/<filename>
+        // nodeKey may contain : but not /
+        const parts = rest.split("/");
+        if (parts.length < 4 || parts[1] !== "nodes") {
+            throw new Error(`Invalid artifact URI format: ${uri}`);
+        }
+        const runId = parts[0];
+        // Everything between "nodes/" and the last segment is the nodeKey
+        const filename = parts[parts.length - 1];
+        const nodeKey = parts.slice(2, parts.length - 1).join("/");
+        return { uri, runId, nodeKey, filename };
+    }
+    // ─── Internal helpers ──────────────────────────────────────────
+    nodeDir(runId, nodeKey) {
+        const safeKey = encodeNodeKeyForDir(nodeKey);
+        return join(this.baseDir, runId, "artifacts", safeKey);
+    }
+    makeRef(runId, nodeKey, filename) {
+        const safeKey = encodeNodeKeyForDir(nodeKey);
+        const uri = `artifact://runs/${runId}/nodes/${safeKey}/${filename}`;
+        return { uri, runId, nodeKey, filename };
+    }
+}
+/** Validate that an artifact filename has no path traversal or separator characters. */
+function validateArtifactFilename(filename) {
+    if (filename.includes("/") || filename.includes("\\") || filename.includes("..")) {
+        throw new Error(`Invalid artifact filename: ${filename}`);
+    }
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/artifacts.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,54 @@
+/**
+ * RunSupervisorClient — thin HTTP client for the acpus Run Supervisor.
+ *
+ * Lives in @acpus/runtime so both the CLI and the TUI can share one client
+ * without a package cycle.
+ *
+ * Node keys are passed as ?key= query parameters since they contain "/"
+ * characters that are incompatible with URL path segments.
+ */
+import type { AcpusIr } from "@acpus/core";
+import type { RunCleanResult, RunState, NodeExecutionState, RunSummary, ReplayResult, SupervisorHealth } from "./types.js";
+export declare class RunSupervisorClient {
+    private readonly baseUrl;
+    /** Client identity for lease tracking on the supervisor. */
+    readonly clientId: string;
+    /** When set, includes x-acpus-client-kind header to pin the supervisor alive. */
+    clientKind?: "follow" | "visualize";
+    constructor(baseUrl: string);
+    private headers;
+    health(): Promise<SupervisorHealth>;
+    startRun(spec: string, input?: Record<string, unknown>, sourcePath?: string, workflowRef?: string): Promise<RunState>;
+    listRuns(): Promise<RunSummary[]>;
+    cleanRuns(options?: {
+        dryRun?: boolean;
+    }): Promise<RunCleanResult>;
+    getRun(runId: string): Promise<RunState>;
+    getIr(runId: string): Promise<AcpusIr>;
+    /** Resolve an artifact:// URI to its absolute filesystem path on the supervisor host. */
+    getArtifactPath(runId: string, uri: string): Promise<string>;
+    getNodeStates(runId: string): Promise<NodeExecutionState[]>;
+    getNode(runId: string, nodeKey: string): Promise<NodeExecutionState>;
+    retryNode(runId: string, nodeKey: string): Promise<NodeExecutionState>;
+    /**
+     * Deliver a human-in-the-loop approval decision to an Approval Gate that is
+     * currently `awaiting`. Node-level only. On a non-2xx response the
+     * supervisor's error message (e.g. 409 "not awaiting") is surfaced.
+     */
+    signalApproval(runId: string, nodeKey: string, approved: boolean): Promise<NodeExecutionState>;
+    pauseRun(runId: string): Promise<RunState>;
+    resumeRun(runId: string): Promise<RunState>;
+    cancelRun(runId: string): Promise<RunState>;
+    retryRun(runId: string): Promise<RunState>;
+    getOutput(runId: string): Promise<{
+        status: string;
+        output: Record<string, unknown>;
+    }>;
+    replay(runId: string): Promise<ReplayResult>;
+    /**
+     * Issue a Run-level control action. No ?key= parameter — the action applies
+     * to the entire Run.
+     */
+    private controlRun;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,kBAAkB,EAAE,UAAU,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG3H,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,UAAU,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;gBAExB,OAAO,EAAE,MAAM;IAK3B,OAAO,CAAC,OAAO;IAUT,MAAM,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAMnC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAarH,QAAQ,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAMjC,SAAS,CAAC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAUtE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAMxC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAM5C,yFAAyF;IACnF,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO5D,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAM3D,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAMpE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAY5E;;;;OAIG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAkB9F,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI1C,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI3C,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI3C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI1C,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAMtF,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAMlD;;;OAGG;YACW,UAAU;CAczB"}

package/dist/client.js

@@ -0,0 +1,159 @@
+/**
+ * RunSupervisorClient — thin HTTP client for the acpus Run Supervisor.
+ *
+ * Lives in @acpus/runtime so both the CLI and the TUI can share one client
+ * without a package cycle.
+ *
+ * Node keys are passed as ?key= query parameters since they contain "/"
+ * characters that are incompatible with URL path segments.
+ */
+import { randomUUID } from "node:crypto";
+export class RunSupervisorClient {
+    baseUrl;
+    /** Client identity for lease tracking on the supervisor. */
+    clientId;
+    /** When set, includes x-acpus-client-kind header to pin the supervisor alive. */
+    clientKind;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+        this.clientId = randomUUID();
+    }
+    headers() {
+        const h = {
+            "x-acpus-client-id": this.clientId
+        };
+        if (this.clientKind) {
+            h["x-acpus-client-kind"] = this.clientKind;
+        }
+        return h;
+    }
+    async health() {
+        const res = await fetch(`${this.baseUrl}/health`, { headers: this.headers() });
+        if (!res.ok)
+            throw new Error(`Health check failed: ${res.status}`);
+        return res.json();
+    }
+    async startRun(spec, input, sourcePath, workflowRef) {
+        const res = await fetch(`${this.baseUrl}/runs`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...this.headers() },
+            body: JSON.stringify({ spec, input, sourcePath, workflowRef })
+        });
+        if (!res.ok) {
+            const body = await res.json().catch(() => ({}));
+            throw new Error(`Failed to start run: ${res.status} ${JSON.stringify(body)}`);
+        }
+        return res.json();
+    }
+    async listRuns() {
+        const res = await fetch(`${this.baseUrl}/runs`, { headers: this.headers() });
+        if (!res.ok)
+            throw new Error(`Failed to list runs: ${res.status}`);
+        return res.json();
+    }
+    async cleanRuns(options = {}) {
+        const res = await fetch(`${this.baseUrl}/runs/clean`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...this.headers() },
+            body: JSON.stringify({ dryRun: Boolean(options.dryRun) })
+        });
+        if (!res.ok)
+            throw new Error(`Failed to clean runs: ${res.status}`);
+        return res.json();
+    }
+    async getRun(runId) {
+        const res = await fetch(`${this.baseUrl}/runs/${runId}`, { headers: this.headers() });
+        if (!res.ok)
+            throw new Error(`Run not found: ${runId}`);
+        return res.json();
+    }
+    async getIr(runId) {
+        const res = await fetch(`${this.baseUrl}/runs/${runId}/ir`, { headers: this.headers() });
+        if (!res.ok)
+            throw new Error(`IR not found: ${runId}`);
+        return res.json();
+    }
+    /** Resolve an artifact:// URI to its absolute filesystem path on the supervisor host. */
+    async getArtifactPath(runId, uri) {
+        const res = await fetch(`${this.baseUrl}/runs/${runId}/artifact-path?uri=${encodeURIComponent(uri)}`, { headers: this.headers() });
+        if (!res.ok)
+            throw new Error(`Failed to resolve artifact path: ${res.status}`);
+        const body = (await res.json());
+        return body.absPath;
+    }
+    async getNodeStates(runId) {
+        const res = await fetch(`${this.baseUrl}/runs/${runId}/nodes`, { headers: this.headers() });
+        if (!res.ok)
+            throw new Error(`Failed to get node states: ${res.status}`);
+        return res.json();
+    }
+    async getNode(runId, nodeKey) {
+        const res = await fetch(`${this.baseUrl}/runs/${runId}/node?key=${encodeURIComponent(nodeKey)}`, { headers: this.headers() });
+        if (!res.ok)
+            throw new Error(`Node not found: ${nodeKey}`);
+        return res.json();
+    }
+    async retryNode(runId, nodeKey) {
+        const res = await fetch(`${this.baseUrl}/runs/${runId}/retry?key=${encodeURIComponent(nodeKey)}`, { method: "POST", headers: this.headers() });
+        if (!res.ok) {
+            const body = (await res.json().catch(() => ({})));
+            throw new Error(body.error ?? `Failed to retry node: ${res.status}`);
+        }
+        return res.json();
+    }
+    /**
+     * Deliver a human-in-the-loop approval decision to an Approval Gate that is
+     * currently `awaiting`. Node-level only. On a non-2xx response the
+     * supervisor's error message (e.g. 409 "not awaiting") is surfaced.
+     */
+    async signalApproval(runId, nodeKey, approved) {
+        const res = await fetch(`${this.baseUrl}/runs/${runId}/signal?key=${encodeURIComponent(nodeKey)}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...this.headers() },
+            body: JSON.stringify({ kind: "approval", approved })
+        });
+        if (!res.ok) {
+            const body = (await res.json().catch(() => ({})));
+            throw new Error(body.error ?? `Failed to signal approval: ${res.status}`);
+        }
+        return res.json();
+    }
+    // ─── Run-level controls ────────────────────────────────────────
+    async pauseRun(runId) {
+        return this.controlRun(runId, "pause");
+    }
+    async resumeRun(runId) {
+        return this.controlRun(runId, "resume");
+    }
+    async cancelRun(runId) {
+        return this.controlRun(runId, "cancel");
+    }
+    async retryRun(runId) {
+        return this.controlRun(runId, "retry");
+    }
+    async getOutput(runId) {
+        const res = await fetch(`${this.baseUrl}/runs/${runId}/output`, { headers: this.headers() });
+        if (!res.ok)
+            throw new Error(`Failed to get output: ${res.status}`);
+        return res.json();
+    }
+    async replay(runId) {
+        const res = await fetch(`${this.baseUrl}/runs/${runId}/replay`, { method: "POST", headers: this.headers() });
+        if (!res.ok)
+            throw new Error(`Failed to replay run: ${res.status}`);
+        return res.json();
+    }
+    /**
+     * Issue a Run-level control action. No ?key= parameter — the action applies
+     * to the entire Run.
+     */
+    async controlRun(runId, action) {
+        const res = await fetch(`${this.baseUrl}/runs/${runId}/${action}`, { method: "POST", headers: this.headers() });
+        if (!res.ok) {
+            const body = (await res.json().catch(() => ({})));
+            throw new Error(body.error ?? `Failed to ${action} run: ${res.status}`);
+        }
+        return res.json();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/evaluator.d.ts

@@ -0,0 +1,37 @@
+import type { ExpressionContext } from "./types.js";
+/**
+ * Wraps @marcbachmann/cel-js to evaluate ${{ expr }} templates and raw CEL
+ * expressions. Registers custom functions (now, len, startsWith, matches,
+ * coalesce) via Environment.registerFunction().
+ */
+export declare class ExpressionEvaluator {
+    private readonly env;
+    private readonly nowTimestamp;
+    constructor(options?: {
+        nowTimestamp?: string;
+    });
+    /**
+     * The deterministic timestamp bound to now(). Exposed so the interpreter can
+     * stamp control outputs (e.g. approval `at`) without reading wall-clock time.
+     */
+    getNow(): string;
+    /**
+     * Evaluate a ${{ expr }} template by finding all expression patterns,
+     * evaluating each, and substituting the results.
+     */
+    evaluateTemplate(template: string, ctx: ExpressionContext): string;
+    /**
+     * Evaluate a raw CEL expression against the given context.
+     */
+    evaluateExpression(expr: string, ctx: ExpressionContext): unknown;
+    /**
+     * Evaluate a fanout `over` expression and validate the result is an array.
+     */
+    evaluateOverExpression(expr: string, ctx: ExpressionContext): unknown[];
+    /**
+     * Build the CEL variable bindings from the expression context.
+     * Transforms loop → loop_ctx to match the toCelParseSource rewriting.
+     */
+    private buildBindings;
+}
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../src/evaluator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE;IAgC/C;;;OAGG;IACH,MAAM,IAAI,MAAM;IAIhB;;;OAGG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,MAAM;IAOlE;;OAEG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,OAAO;IAMjE;;OAEG;IACH,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,OAAO,EAAE;IAQvE;;;OAGG;IACH,OAAO,CAAC,aAAa;CA0BtB"}

package/dist/evaluator.js

@@ -0,0 +1,101 @@
+import { Environment } from "@marcbachmann/cel-js";
+import { EXPRESSION_PATTERN, toCelParseSource } from "@acpus/core";
+/**
+ * Wraps @marcbachmann/cel-js to evaluate ${{ expr }} templates and raw CEL
+ * expressions. Registers custom functions (now, len, startsWith, matches,
+ * coalesce) via Environment.registerFunction().
+ */
+export class ExpressionEvaluator {
+    env;
+    nowTimestamp;
+    constructor(options) {
+        this.nowTimestamp = options?.nowTimestamp ?? new Date().toISOString();
+        this.env = new Environment({ unlistedVariablesAreDyn: true });
+        // Register custom functions with type signatures
+        this.env.registerFunction("now(): string", () => this.nowTimestamp);
+        // len() overloads — string and list
+        this.env.registerFunction("len(string): int", (str) => BigInt(str.length));
+        this.env.registerFunction("len(list): int", (arr) => BigInt(arr.length));
+        // startsWith
+        this.env.registerFunction("startsWith(string, string): bool", (str, prefix) => str.startsWith(prefix));
+        // matches
+        this.env.registerFunction("matches(string, string): bool", (str, pattern) => {
+            try {
+                return new RegExp(pattern).test(str);
+            }
+            catch {
+                return false;
+            }
+        });
+        // coalesce overloads — 2 and 3 args
+        this.env.registerFunction("coalesce(dyn, dyn): dyn", (a, b) => (a !== null && a !== undefined) ? a : b);
+        this.env.registerFunction("coalesce(dyn, dyn, dyn): dyn", (a, b, c) => {
+            if (a !== null && a !== undefined)
+                return a;
+            if (b !== null && b !== undefined)
+                return b;
+            return c;
+        });
+    }
+    /**
+     * The deterministic timestamp bound to now(). Exposed so the interpreter can
+     * stamp control outputs (e.g. approval `at`) without reading wall-clock time.
+     */
+    getNow() {
+        return this.nowTimestamp;
+    }
+    /**
+     * Evaluate a ${{ expr }} template by finding all expression patterns,
+     * evaluating each, and substituting the results.
+     */
+    evaluateTemplate(template, ctx) {
+        return template.replace(EXPRESSION_PATTERN, (_match, expr) => {
+            const result = this.evaluateExpression(expr.trim(), ctx);
+            return String(result);
+        });
+    }
+    /**
+     * Evaluate a raw CEL expression against the given context.
+     */
+    evaluateExpression(expr, ctx) {
+        const celSource = toCelParseSource(expr);
+        const bindings = this.buildBindings(ctx);
+        return this.env.evaluate(celSource, bindings);
+    }
+    /**
+     * Evaluate a fanout `over` expression and validate the result is an array.
+     */
+    evaluateOverExpression(expr, ctx) {
+        const result = this.evaluateExpression(expr, ctx);
+        if (!Array.isArray(result)) {
+            throw new Error(`fanout.over expression must evaluate to an array, got ${typeof result}: ${expr}`);
+        }
+        return result;
+    }
+    /**
+     * Build the CEL variable bindings from the expression context.
+     * Transforms loop → loop_ctx to match the toCelParseSource rewriting.
+     */
+    buildBindings(ctx) {
+        const bindings = {
+            input: ctx.input,
+            steps: ctx.steps,
+            run_id: ctx.run_id
+        };
+        if (ctx.loop !== undefined) {
+            // toCelParseSource rewrites loop. → loop_ctx.
+            bindings.loop_ctx = ctx.loop;
+        }
+        if (ctx.item !== undefined) {
+            bindings.item = ctx.item;
+        }
+        if (ctx.item_id !== undefined) {
+            bindings.item_id = ctx.item_id;
+        }
+        if (ctx.item_index !== undefined) {
+            bindings.item_index = ctx.item_index;
+        }
+        return bindings;
+    }
+}
+//# sourceMappingURL=evaluator.js.map

package/dist/evaluator.js.map

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

package/dist/executors/agent.d.ts

@@ -0,0 +1,74 @@
+import type { ExpressionContext, ExecutorResult } from "../types.js";
+import type { ExecutorAdapter, ExecutionRequest } from "./types.js";
+import { ExpressionEvaluator } from "../evaluator.js";
+/**
+ * Drives an ACP agent through the `acpx` CLI. Acpus owns scheduling/state;
+ * acpx owns the ACP saved-session lifecycle and dead-pid recovery.
+ *
+ * - Session name is derived from the resolved node key (stable, unique per
+ *   loop round / fanout lane / subworkflow nesting).
+ * - First run: `sessions ensure` then `prompt -s <session>` with the rendered
+ *   prompt; continuation: same session with a fixed continuation prompt.
+ * - Cancel is cooperative: on abort we run `acpx cancel -s <session>` and wait
+ *   for the in-flight prompt to settle (SIGKILL only as a last resort).
+ * - Output is the concatenation of `agent_message_chunk` text from the ACP
+ *   NDJSON stream; the full stream is returned as `stdout` for transcript
+ *   capture by the interpreter.
+ */
+export declare class AgentExecutor implements ExecutorAdapter {
+    private readonly evaluator;
+    private readonly ajv;
+    private readonly acpxPath?;
+    private readonly cancelGraceMs;
+    constructor(options?: {
+        acpxPath?: string;
+        evaluator?: ExpressionEvaluator;
+        cancelGraceMs?: number;
+    });
+    execute({ node, context, signal, nodeKey, prompt: preparedPrompt, continuation, retry, onStream }: ExecutionRequest): Promise<ExecutorResult>;
+    /**
+     * On abort, request a cooperative `session/cancel` via acpx and schedule a
+     * SIGKILL fallback if the in-flight prompt does not settle within the grace
+     * period. Returns a handle exposing whether cancel fired and a cleanup fn.
+     */
+    private wireCooperativeCancel;
+    /**
+     * Build acpx arg lists for a subcommand. Global flags (--cwd, --model,
+     * --format) precede the command. For `command` agents the custom ACP server
+     * is selected via the `--agent` escape hatch; for `builtin` agents the
+     * adapter name is the command prefix.
+     */
+    private argsBuilder;
+    /** Resolve how to invoke acpx: an explicit path, or the resolved package bin via node. */
+    private resolveInvoker;
+    private sessionName;
+    private resolveCwd;
+    private resolveTimeoutSeconds;
+    private stringEnv;
+}
+/**
+ * Decide the prompt text for an agent turn:
+ *   - first run        → rendered task template
+ *   - continuation     → fixed continuation prompt
+ *   - parse/schema retry→ fixed continuation prompt
+ * When an output schema is declared it is appended as a `# OUTPUT SCHEMA`
+ * section on the first run and on retries, but NOT on a plain continuation
+ * (the original task is still live in the acpx session there).
+ */
+export declare function buildAgentPrompt(renderedTask: string, outputSchema: Record<string, unknown> | undefined, continuation: boolean, retry: boolean): string;
+/** Render the exact Agent request prompt that will be sent to acpx. */
+export declare function renderAgentRequestPrompt(node: {
+    metadata: Record<string, unknown>;
+}, context: ExpressionContext, evaluator: ExpressionEvaluator, continuation: boolean, retry: boolean): string;
+/**
+ * Extract a JSON value from an agent reply that may wrap JSON in prose and/or
+ * Markdown code fences. Three tiers, strictest first:
+ *   1. Strict fast path: parse the whole trimmed reply (pure-JSON response).
+ *   2. Independent balanced scan: try every `{...}`/`[...]` candidate from each
+ *      opening brace/bracket so unbalanced prose/code cannot block later JSON.
+ *   3. Candidate-local jsonrepair fallback: for each later candidate, try strict
+ *      parse first, then repair that same candidate before moving earlier.
+ * Returns `undefined` when no JSON can be recovered (→ retryable parse failure).
+ */
+export declare function extractJson(text: string): unknown | undefined;
+//# sourceMappingURL=agent.d.ts.map

package/dist/executors/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/executors/agent.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAUtD;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,YAAW,eAAe;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE;IAO9F,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC;IAgHnJ;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IA6B7B;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAenB,0FAA0F;IAC1F,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,qBAAqB;IAU7B,OAAO,CAAC,SAAS;CAMlB;AAYD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EACjD,YAAY,EAAE,OAAO,EACrB,KAAK,EAAE,OAAO,GACb,MAAM,CAQR;AAED,uEAAuE;AACvE,wBAAgB,wBAAwB,CACtC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAC3C,OAAO,EAAE,iBAAiB,EAC1B,SAAS,EAAE,mBAAmB,EAC9B,YAAY,EAAE,OAAO,EACrB,KAAK,EAAE,OAAO,GACb,MAAM,CAIR;AAoCD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CA4B7D"}