cpa-agents 0.1.0

package/dist/process.js

@@ -0,0 +1,273 @@
+/**
+ * Process: the core unit of computation in the algebra.
+ *
+ * A Process is a function that takes a context (channels, signals)
+ * and returns a result. Processes compose via parallel, sequential,
+ * choice, and branch-fix-continue combinators.
+ */
+import { Channel, freshId, select } from "./channel.js";
+export class TraceCollector {
+    events = [];
+    emit(event) {
+        this.events.push(event);
+    }
+    /** Get a serialisable session tree from the flat event log */
+    toTree() {
+        const nodes = new Map();
+        const roots = [];
+        for (const e of this.events) {
+            if (e.type === "spawn") {
+                const node = {
+                    runId: e.runId,
+                    name: e.name,
+                    parentId: e.parentId,
+                    events: [],
+                    children: [],
+                };
+                nodes.set(e.runId, node);
+                if (e.parentId && nodes.has(e.parentId)) {
+                    nodes.get(e.parentId).children.push(node);
+                }
+                else {
+                    roots.push(node);
+                }
+            }
+            const node = nodes.get(e.runId);
+            if (node) {
+                node.events.push(e);
+            }
+        }
+        return roots;
+    }
+}
+// ─── Combinators ────────────────────────────────────────────────
+/**
+ * Parallel composition: P | Q
+ * Runs all processes concurrently and waits for all to complete.
+ */
+export function par(...processes) {
+    return async (ctx) => {
+        const results = await Promise.all(processes.map((p, i) => {
+            const childId = freshId("par");
+            ctx.trace.emit({
+                type: "spawn",
+                runId: childId,
+                parentId: ctx.runId,
+                name: `par[${i}]`,
+                ts: Date.now(),
+            });
+            const childCtx = {
+                ...ctx,
+                runId: childId,
+                parentId: ctx.runId,
+            };
+            return p(childCtx).then((r) => {
+                ctx.trace.emit({ type: "done", runId: childId, ts: Date.now() });
+                return r;
+            });
+        }));
+        return results;
+    };
+}
+/**
+ * Sequential composition: P ; Q
+ * Runs processes one after another, threading context.
+ */
+export function seq(...processes) {
+    return async (ctx) => {
+        let result;
+        for (const p of processes) {
+            if (ctx.signal.aborted)
+                throw new Error("Process aborted");
+            result = await p(ctx);
+        }
+        return result;
+    };
+}
+/**
+ * Choice: P + Q (external choice)
+ *
+ * Waits for a message on any of the guard channels.
+ * The first channel that fires determines which branch runs.
+ * All other branches are discarded (committed choice).
+ */
+export function choice(branches) {
+    return async (ctx) => {
+        const alternatives = branches.map((b) => b.name);
+        let chosenIdx = -1;
+        const cases = branches.map((b, i) => ({
+            channel: b.guard,
+            handler: () => {
+                chosenIdx = i;
+            },
+        }));
+        await select(...cases);
+        ctx.trace.emit({
+            type: "branch",
+            runId: ctx.runId,
+            chosen: branches[chosenIdx].name,
+            alternatives,
+            ts: Date.now(),
+        });
+        return branches[chosenIdx].process(ctx);
+    };
+}
+/**
+ * Branch-Fix-Continue: the tree pattern you described.
+ *
+ * 1. Run the main process.
+ * 2. If it signals a fix is needed (via the fix channel), pause main,
+ *    run the fix process, then resume main from where it left off.
+ * 3. If the main completes without needing a fix, continue normally.
+ *
+ * This is the key pattern for AI agents: you're coding along,
+ * discover a lint error, branch to fix it, then rejoin the main flow.
+ */
+export function branchFix(opts) {
+    const maxFixes = opts.maxFixes ?? 5;
+    return async (ctx) => {
+        let fixCount = 0;
+        const fixChannel = new Channel(`${opts.name}_fix`);
+        const fixDone = new Channel(`${opts.name}_fixdone`);
+        const requestFix = async (reason) => {
+            if (fixCount >= maxFixes) {
+                throw new Error(`${opts.name}: exceeded max fix attempts (${maxFixes})`);
+            }
+            fixCount++;
+            ctx.trace.emit({
+                type: "fix_start",
+                runId: ctx.runId,
+                reason,
+                ts: Date.now(),
+            });
+            // Signal that a fix is needed
+            await fixChannel.send(reason);
+            // Wait for the fix to complete
+            await fixDone.receive();
+            ctx.trace.emit({
+                type: "fix_end",
+                runId: ctx.runId,
+                success: true,
+                ts: Date.now(),
+            });
+        };
+        const mainProcess = opts.main(requestFix);
+        // Run main and fix-listener concurrently
+        const mainPromise = mainProcess(ctx);
+        // Fix listener loop: runs in background
+        const fixListener = (async () => {
+            while (!fixChannel.closed) {
+                try {
+                    const reason = await fixChannel.receive();
+                    const fixProc = opts.fix(reason);
+                    await fixProc(ctx);
+                    await fixDone.send(undefined);
+                }
+                catch {
+                    // Channel closed or fix failed — stop listening
+                    break;
+                }
+            }
+        })();
+        try {
+            const result = await mainPromise;
+            fixChannel.close();
+            fixDone.close();
+            return result;
+        }
+        catch (err) {
+            fixChannel.close();
+            fixDone.close();
+            throw err;
+        }
+    };
+}
+/**
+ * Restriction: ν(name). Creates a fresh scoped channel.
+ * The channel is only visible to processes inside the scope.
+ */
+export function restrict(name, body) {
+    return async (ctx) => {
+        const ch = new Channel(name);
+        const scopedChannels = new Map(ctx.channels);
+        scopedChannels.set(name, ch);
+        const scopedCtx = { ...ctx, channels: scopedChannels };
+        try {
+            return await body(ch)(scopedCtx);
+        }
+        finally {
+            ch.close();
+        }
+    };
+}
+/**
+ * Replication: !P — spawn a new copy of P each time the trigger fires.
+ * Useful for server-like patterns where each incoming request
+ * gets its own agent process.
+ */
+export function replicate(trigger, handler) {
+    return async (ctx) => {
+        while (!ctx.signal.aborted && !trigger.closed) {
+            try {
+                const value = await trigger.receive();
+                const childId = freshId("repl");
+                ctx.trace.emit({
+                    type: "spawn",
+                    runId: childId,
+                    parentId: ctx.runId,
+                    name: "replicated",
+                    ts: Date.now(),
+                });
+                const childCtx = {
+                    ...ctx,
+                    runId: childId,
+                    parentId: ctx.runId,
+                };
+                // Fire and forget — each replica runs independently
+                handler(value)(childCtx).catch((err) => {
+                    ctx.trace.emit({
+                        type: "error",
+                        runId: childId,
+                        error: String(err),
+                        ts: Date.now(),
+                    });
+                });
+            }
+            catch {
+                break;
+            }
+        }
+    };
+}
+/**
+ * Supervisor: wraps a process with retry + fallback semantics.
+ * On failure, can either restart the process or run a recovery process.
+ */
+export function supervisor(opts) {
+    const maxRetries = opts.maxRetries ?? 3;
+    return async (ctx) => {
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await opts.process(ctx);
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                ctx.trace.emit({
+                    type: "error",
+                    runId: ctx.runId,
+                    error: lastError.message,
+                    ts: Date.now(),
+                });
+                if (opts.onError && attempt < maxRetries) {
+                    await opts.onError(lastError, attempt)(ctx);
+                }
+            }
+        }
+        if (opts.fallback) {
+            return opts.fallback(ctx);
+        }
+        throw lastError;
+    };
+}
+//# sourceMappingURL=process.js.map

package/dist/process.js.map

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

package/dist/scheduler.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Scheduler: the runtime that executes process trees.
+ *
+ * Handles:
+ * - Process lifecycle (spawn, run, complete, error)
+ * - Cooperative scheduling via async/await
+ * - Deadlock detection (all processes blocked on channels, none can fire)
+ * - Graceful shutdown via AbortController
+ */
+import { type Process, type TraceCollector } from "./process.js";
+export interface SchedulerOpts {
+    /** Timeout for the entire process tree (ms) */
+    timeout?: number;
+    /** Callback when a trace event is emitted */
+    onTrace?: (event: import("./process.js").TraceEvent) => void;
+}
+export declare class Scheduler {
+    private abortController;
+    private trace;
+    private opts;
+    constructor(opts?: SchedulerOpts);
+    /**
+     * Run a process tree to completion.
+     */
+    run<T>(name: string, process: Process<T>): Promise<SchedulerResult<T>>;
+    /**
+     * Abort all running processes.
+     */
+    abort(): void;
+    /**
+     * Get the current session tree (can be called mid-execution).
+     */
+    getSessionTree(): import("./process.js").SessionNode[];
+    /**
+     * Get the flat event trace.
+     */
+    getTrace(): import("./process.js").TraceEvent[];
+}
+export type SchedulerResult<T> = {
+    success: true;
+    value: T;
+    trace: TraceCollector;
+    sessionTree: import("./process.js").SessionNode[];
+} | {
+    success: false;
+    error: Error;
+    trace: TraceCollector;
+    sessionTree: import("./process.js").SessionNode[];
+};
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,cAAc,EAEpB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,cAAc,EAAE,UAAU,KAAK,IAAI,CAAC;CAC9D;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,IAAI,CAAgB;gBAEhB,IAAI,GAAE,aAAkB;IAWpC;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAiE5E;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,cAAc;IAId;;OAEG;IACH,QAAQ;CAGT;AAED,MAAM,MAAM,eAAe,CAAC,CAAC,IACzB;IACE,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,EAAE,OAAO,cAAc,EAAE,WAAW,EAAE,CAAC;CACnD,GACD;IACE,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,EAAE,OAAO,cAAc,EAAE,WAAW,EAAE,CAAC;CACnD,CAAC"}

package/dist/scheduler.js

@@ -0,0 +1,109 @@
+/**
+ * Scheduler: the runtime that executes process trees.
+ *
+ * Handles:
+ * - Process lifecycle (spawn, run, complete, error)
+ * - Cooperative scheduling via async/await
+ * - Deadlock detection (all processes blocked on channels, none can fire)
+ * - Graceful shutdown via AbortController
+ */
+import { freshId } from "./channel.js";
+import { TraceCollector as TraceCollectorImpl, } from "./process.js";
+export class Scheduler {
+    abortController;
+    trace;
+    opts;
+    constructor(opts = {}) {
+        this.abortController = new AbortController();
+        this.opts = opts;
+        this.trace = new (class extends TraceCollectorImpl {
+            emit(event) {
+                super.emit(event);
+                opts.onTrace?.(event);
+            }
+        })();
+    }
+    /**
+     * Run a process tree to completion.
+     */
+    async run(name, process) {
+        const runId = freshId("root");
+        const ctx = {
+            runId,
+            signal: this.abortController.signal,
+            trace: this.trace,
+            channels: new Map(),
+        };
+        this.trace.emit({
+            type: "spawn",
+            runId,
+            name,
+            ts: Date.now(),
+        });
+        let timeoutId;
+        try {
+            const resultPromise = process(ctx);
+            // Apply timeout if configured
+            let result;
+            if (this.opts.timeout) {
+                result = await Promise.race([
+                    resultPromise,
+                    new Promise((_, reject) => {
+                        timeoutId = setTimeout(() => {
+                            this.abortController.abort();
+                            reject(new Error(`Scheduler timeout after ${this.opts.timeout}ms`));
+                        }, this.opts.timeout);
+                    }),
+                ]);
+            }
+            else {
+                result = await resultPromise;
+            }
+            this.trace.emit({ type: "done", runId, ts: Date.now() });
+            return {
+                success: true,
+                value: result,
+                trace: this.trace,
+                sessionTree: this.trace.toTree(),
+            };
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.trace.emit({
+                type: "error",
+                runId,
+                error: error.message,
+                ts: Date.now(),
+            });
+            return {
+                success: false,
+                error,
+                trace: this.trace,
+                sessionTree: this.trace.toTree(),
+            };
+        }
+        finally {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Abort all running processes.
+     */
+    abort() {
+        this.abortController.abort();
+    }
+    /**
+     * Get the current session tree (can be called mid-execution).
+     */
+    getSessionTree() {
+        return this.trace.toTree();
+    }
+    /**
+     * Get the flat event trace.
+     */
+    getTrace() {
+        return this.trace.events;
+    }
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/scheduler.js.map

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

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "cpa-agents",
+  "version": "0.1.0",
+  "description": "Concurrent Process Algebra for AI Agents — π-calculus primitives for Pi Harness and OpenClaw",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./adapters/pi": {
+      "import": "./dist/adapters/pi-harness.js",
+      "types": "./dist/adapters/pi-harness.d.ts"
+    },
+    "./adapters/openclaw": {
+      "import": "./dist/adapters/openclaw.js",
+      "types": "./dist/adapters/openclaw.d.ts"
+    }
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "test": "tsx --test test/*.test.ts",
+    "coverage": "c8 --all --include='src/**/*.ts' --reporter=text --check-coverage --lines 80 --branches 80 --functions 80 --statements 80 npm test",
+    "check": "tsc --noEmit",
+    "prepublishOnly": "npm run check && npm run build && npm test && npm run coverage"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-calculus",
+    "process-algebra",
+    "ai-agents",
+    "concurrency",
+    "pi-harness",
+    "openclaw",
+    "orchestration"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "c8": "^11.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.5.0"
+  }
+}