cpa-agents 0.1.0

package/dist/agent.js

@@ -0,0 +1,148 @@
+/**
+ * AgentProcess: bridges the process algebra to actual LLM agent calls.
+ *
+ * An AgentProcess wraps an LLM invocation (tool use loop, ReAct step,
+ * or sub-agent spawn) as a Process<T> that can be composed with
+ * all the algebra combinators.
+ */
+import { Channel } from "./channel.js";
+import { branchFix, par } from "./process.js";
+/**
+ * Lift an agent call into a Process.
+ */
+export function agentProcess(agent, input) {
+    return async (ctx) => {
+        ctx.trace.emit({
+            type: "spawn",
+            runId: ctx.runId,
+            parentId: ctx.parentId,
+            name: agent.name,
+            ts: Date.now(),
+        });
+        const result = await agent.invoke(input, ctx.signal);
+        ctx.trace.emit({
+            type: "done",
+            runId: ctx.runId,
+            ts: Date.now(),
+        });
+        return result;
+    };
+}
+// ─── Common agent workflow patterns ─────────────────────────────
+/**
+ * Code-then-fix: the tree pattern from Pi Harness.
+ *
+ * 1. Agent writes code
+ * 2. Lint/test/typecheck runs
+ * 3. If errors found → branch to fix agent → re-check → continue
+ * 4. If clean → proceed to next task
+ */
+export function codeThenFix(opts) {
+    return branchFix({
+        name: `code_fix_${opts.task.slice(0, 20)}`,
+        maxFixes: opts.maxFixes,
+        main: (requestFix) => async (ctx) => {
+            // Step 1: generate code
+            let code = await opts.coder.invoke(opts.task, ctx.signal);
+            // Step 2: check it
+            let checkResult = await opts.checker.invoke(code, ctx.signal);
+            // Step 3: loop fix if needed
+            while (!checkResult.pass) {
+                await requestFix(checkResult.errors.join("; "));
+                code = await opts.fixer.invoke({ code, errors: checkResult.errors }, ctx.signal);
+                checkResult = await opts.checker.invoke(code, ctx.signal);
+            }
+            return code;
+        },
+        fix: (reason) => async (ctx) => {
+            ctx.trace.emit({
+                type: "fix_start",
+                runId: ctx.runId,
+                reason,
+                ts: Date.now(),
+            });
+            // The actual fix work happens in the main loop above.
+            // This hook is for side effects: logging, notifying, etc.
+            ctx.trace.emit({
+                type: "fix_end",
+                runId: ctx.runId,
+                success: true,
+                ts: Date.now(),
+            });
+        },
+    });
+}
+/**
+ * Fan-out pattern: send the same task to N agents in parallel,
+ * collect results, then merge.
+ *
+ * Useful for: parallel research, multi-model consensus, ensemble.
+ */
+export function fanOut(opts) {
+    const processes = opts.agents.map((agent) => agentProcess(agent, opts.input));
+    return async (ctx) => {
+        const results = await par(...processes)(ctx);
+        return opts.merge(results);
+    };
+}
+export function pipeline(a, inputA) {
+    return new PipelineBuilder(a, inputA);
+}
+export class PipelineBuilder {
+    steps = [];
+    firstAgent;
+    firstInput;
+    constructor(agent, input) {
+        this.firstAgent = agent;
+        this.firstInput = input;
+    }
+    then(agent, transform) {
+        this.steps.push({ agent, inputFn: transform });
+        return this;
+    }
+    build() {
+        const { firstAgent, firstInput, steps } = this;
+        return async (ctx) => {
+            let result = await firstAgent.invoke(firstInput, ctx.signal);
+            for (const step of steps) {
+                const input = step.inputFn ? step.inputFn(result) : result;
+                result = await step.agent.invoke(input, ctx.signal);
+            }
+            return result;
+        };
+    }
+}
+/**
+ * Handoff: one agent works, then hands off to another via a channel.
+ * Models the Pi Harness pattern of sub-agent spawning.
+ */
+export function handoff(opts) {
+    return async (ctx) => {
+        await Channel.restrict("handoff", async (ch) => {
+            await par(
+            // Producer: runs `from`, sends result on channel
+            async (pCtx) => {
+                const result = await opts.from.invoke(undefined, pCtx.signal);
+                pCtx.trace.emit({
+                    type: "send",
+                    runId: pCtx.runId,
+                    channel: ch.name,
+                    ts: Date.now(),
+                });
+                await ch.send(result);
+            }, 
+            // Consumer: receives from channel, runs `to`
+            async (cCtx) => {
+                const value = await ch.receive();
+                cCtx.trace.emit({
+                    type: "receive",
+                    runId: cCtx.runId,
+                    channel: ch.name,
+                    ts: Date.now(),
+                });
+                await opts.to.invoke(value, cCtx.signal);
+            })(ctx);
+        });
+    };
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

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

package/dist/channel.d.ts

@@ -0,0 +1,57 @@
+/**
+ * cpa-agents — Concurrent Process Algebra for AI Agents
+ *
+ * Channel<T>: typed communication channel with π-calculus semantics.
+ * Supports synchronous rendezvous (sender blocks until receiver is ready).
+ */
+export type ChannelId = string & {
+    __brand: "ChannelId";
+};
+export declare function freshId(prefix?: string): ChannelId;
+/**
+ * A typed, named channel. Corresponds to π-calculus names.
+ * Channels can be sent over other channels (mobility).
+ */
+export declare class Channel<T = unknown> {
+    readonly id: ChannelId;
+    readonly name: string;
+    private sendQueue;
+    private recvQueue;
+    private _closed;
+    constructor(name?: string);
+    get closed(): boolean;
+    /**
+     * Send a value. Blocks until a receiver picks it up (rendezvous).
+     * In π-calculus: ā⟨v⟩.P — output v on channel a, then continue as P.
+     */
+    send(value: T): Promise<void>;
+    /**
+     * Receive a value. Blocks until a sender provides one.
+     * In π-calculus: a(x).P — input x from channel a, then continue as P.
+     */
+    receive(): Promise<T>;
+    /**
+     * Non-blocking try-receive. Returns undefined if nothing is waiting.
+     */
+    tryReceive(): T | undefined;
+    /**
+     * Close the channel. Rejects all pending waiters.
+     */
+    close(): void;
+    /**
+     * π-calculus restriction: ν(x). Creates a fresh channel
+     * scoped to the provided function. The channel is closed
+     * when the scope exits.
+     */
+    static restrict<T, R>(name: string, body: (ch: Channel<T>) => Promise<R>): Promise<R>;
+}
+/**
+ * Select: π-calculus external choice (P + Q).
+ * Waits on multiple channels, returns the first that fires.
+ */
+export interface SelectCase<T> {
+    channel: Channel<T>;
+    handler: (value: T) => Promise<void> | void;
+}
+export declare function select(...cases: SelectCase<any>[]): Promise<void>;
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AAG1D,wBAAgB,OAAO,CAAC,MAAM,SAAO,GAAG,SAAS,CAEhD;AAOD;;;GAGG;AACH,qBAAa,OAAO,CAAC,CAAC,GAAG,OAAO;IAC9B,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,SAAS,CAAwB;IACzC,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,CAAC,EAAE,MAAM;IAKzB,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB7B;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC;IAkBrB;;OAEG;IACH,UAAU,IAAI,CAAC,GAAG,SAAS;IAS3B;;OAEG;IACH,KAAK,IAAI,IAAI;IASb;;;;OAIG;WACU,QAAQ,CAAC,CAAC,EAAE,CAAC,EACxB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GACnC,OAAO,CAAC,CAAC,CAAC;CAQd;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED,wBAAsB,MAAM,CAAC,GAAG,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAUvE"}

package/dist/channel.js

@@ -0,0 +1,113 @@
+/**
+ * cpa-agents — Concurrent Process Algebra for AI Agents
+ *
+ * Channel<T>: typed communication channel with π-calculus semantics.
+ * Supports synchronous rendezvous (sender blocks until receiver is ready).
+ */
+let _nextId = 0;
+export function freshId(prefix = "ch") {
+    return `${prefix}_${_nextId++}`;
+}
+/**
+ * A typed, named channel. Corresponds to π-calculus names.
+ * Channels can be sent over other channels (mobility).
+ */
+export class Channel {
+    id;
+    name;
+    sendQueue = [];
+    recvQueue = [];
+    _closed = false;
+    constructor(name) {
+        this.id = freshId(name ?? "ch");
+        this.name = name ?? this.id;
+    }
+    get closed() {
+        return this._closed;
+    }
+    /**
+     * Send a value. Blocks until a receiver picks it up (rendezvous).
+     * In π-calculus: ā⟨v⟩.P — output v on channel a, then continue as P.
+     */
+    send(value) {
+        if (this._closed) {
+            return Promise.reject(new Error(`Channel ${this.name} is closed`));
+        }
+        // If a receiver is already waiting, hand off directly
+        const receiver = this.recvQueue.shift();
+        if (receiver) {
+            receiver.resolve(value);
+            return Promise.resolve();
+        }
+        // Otherwise, block until a receiver appears
+        return new Promise((resolve, reject) => {
+            this.sendQueue.push({ value, done: { resolve, reject } });
+        });
+    }
+    /**
+     * Receive a value. Blocks until a sender provides one.
+     * In π-calculus: a(x).P — input x from channel a, then continue as P.
+     */
+    receive() {
+        if (this._closed && this.sendQueue.length === 0) {
+            return Promise.reject(new Error(`Channel ${this.name} is closed`));
+        }
+        // If a sender is already waiting, hand off directly
+        const sender = this.sendQueue.shift();
+        if (sender) {
+            sender.done.resolve();
+            return Promise.resolve(sender.value);
+        }
+        // Otherwise, block until a sender appears
+        return new Promise((resolve, reject) => {
+            this.recvQueue.push({ resolve, reject });
+        });
+    }
+    /**
+     * Non-blocking try-receive. Returns undefined if nothing is waiting.
+     */
+    tryReceive() {
+        const sender = this.sendQueue.shift();
+        if (sender) {
+            sender.done.resolve();
+            return sender.value;
+        }
+        return undefined;
+    }
+    /**
+     * Close the channel. Rejects all pending waiters.
+     */
+    close() {
+        this._closed = true;
+        const err = new Error(`Channel ${this.name} closed`);
+        for (const w of this.sendQueue)
+            w.done.reject(err);
+        for (const w of this.recvQueue)
+            w.reject(err);
+        this.sendQueue = [];
+        this.recvQueue = [];
+    }
+    /**
+     * π-calculus restriction: ν(x). Creates a fresh channel
+     * scoped to the provided function. The channel is closed
+     * when the scope exits.
+     */
+    static async restrict(name, body) {
+        const ch = new Channel(name);
+        try {
+            return await body(ch);
+        }
+        finally {
+            ch.close();
+        }
+    }
+}
+export async function select(...cases) {
+    // Race all receives
+    const result = await Promise.race(cases.map(async (c, i) => {
+        const value = await c.channel.receive();
+        return { index: i, value };
+    }));
+    await cases[result.index].handler(result.value);
+}
+//# sourceMappingURL=channel.js.map

package/dist/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,IAAI,OAAO,GAAG,CAAC,CAAC;AAChB,MAAM,UAAU,OAAO,CAAC,MAAM,GAAG,IAAI;IACnC,OAAO,GAAG,MAAM,IAAI,OAAO,EAAE,EAAe,CAAC;AAC/C,CAAC;AAOD;;;GAGG;AACH,MAAM,OAAO,OAAO;IACT,EAAE,CAAY;IACd,IAAI,CAAS;IACd,SAAS,GAA4C,EAAE,CAAC;IACxD,SAAS,GAAqB,EAAE,CAAC;IACjC,OAAO,GAAG,KAAK,CAAC;IAExB,YAAY,IAAa;QACvB,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;IAC9B,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,KAAQ;QACX,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,WAAW,IAAI,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC;QACrE,CAAC;QAED,sDAAsD;QACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACxC,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACxB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QAED,4CAA4C;QAC5C,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC3C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;QAC5D,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChD,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,WAAW,IAAI,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC;QACrE,CAAC;QAED,oDAAoD;QACpD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACtC,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACtB,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;QAED,0CAA0C;QAC1C,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QAC3C,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,UAAU;QACR,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACtC,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACtB,OAAO,MAAM,CAAC,KAAK,CAAC;QACtB,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,WAAW,IAAI,CAAC,IAAI,SAAS,CAAC,CAAC;QACrD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS;YAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS;YAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9C,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;QACpB,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,QAAQ,CACnB,IAAY,EACZ,IAAoC;QAEpC,MAAM,EAAE,GAAG,IAAI,OAAO,CAAI,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,EAAE,CAAC,CAAC;QACxB,CAAC;gBAAS,CAAC;YACT,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,CAAC;IACH,CAAC;CACF;AAWD,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,GAAG,KAAwB;IACtD,oBAAoB;IACpB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAC/B,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE;QACvB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACxC,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC;IAC7B,CAAC,CAAC,CACH,CAAC;IAEF,MAAM,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAClD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * cpa-agents — Concurrent Process Algebra for AI Agents
+ *
+ * A TypeScript library that applies π-calculus process algebra
+ * to AI agent orchestration. Designed for Pi Harness and OpenClaw,
+ * but usable standalone.
+ *
+ * Core concepts:
+ * - Channel<T>: typed communication (π-calculus names)
+ * - Process<T>: unit of computation
+ * - par(P, Q): parallel composition (P | Q)
+ * - seq(P, Q): sequential composition (P ; Q)
+ * - choice([...branches]): external choice (P + Q)
+ * - branchFix({ main, fix }): branch-to-fix-then-continue
+ * - restrict(name, body): scoped channel creation (ν(x).P)
+ * - replicate(trigger, handler): server pattern (!P)
+ * - supervisor({ process, maxRetries }): error recovery
+ *
+ * Agent patterns:
+ * - agentProcess(agent, input): lift an LLM call into a Process
+ * - codeThenFix({ coder, checker, fixer }): code → check → fix loop
+ * - fanOut({ agents, input, merge }): parallel multi-agent
+ * - pipeline(a, input).then(b).build(): sequential chain
+ * - handoff({ from, to }): channel-mediated agent transfer
+ */
+export { Channel, freshId, select, type ChannelId, type SelectCase } from "./channel.js";
+export { type Process, type ProcessContext, type TraceEvent, type SessionNode, TraceCollector, par, seq, choice, branchFix, restrict, replicate, supervisor, } from "./process.js";
+export { type AgentCall, type CheckResult, agentProcess, codeThenFix, fanOut, pipeline, PipelineBuilder, handoff, } from "./agent.js";
+export { Scheduler, type SchedulerOpts, type SchedulerResult } from "./scheduler.js";
+//# 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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAGzF,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,cAAc,EACd,GAAG,EACH,GAAG,EACH,MAAM,EACN,SAAS,EACT,QAAQ,EACR,SAAS,EACT,UAAU,GACX,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,YAAY,EACZ,WAAW,EACX,MAAM,EACN,QAAQ,EACR,eAAe,EACf,OAAO,GACR,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,34 @@
+/**
+ * cpa-agents — Concurrent Process Algebra for AI Agents
+ *
+ * A TypeScript library that applies π-calculus process algebra
+ * to AI agent orchestration. Designed for Pi Harness and OpenClaw,
+ * but usable standalone.
+ *
+ * Core concepts:
+ * - Channel<T>: typed communication (π-calculus names)
+ * - Process<T>: unit of computation
+ * - par(P, Q): parallel composition (P | Q)
+ * - seq(P, Q): sequential composition (P ; Q)
+ * - choice([...branches]): external choice (P + Q)
+ * - branchFix({ main, fix }): branch-to-fix-then-continue
+ * - restrict(name, body): scoped channel creation (ν(x).P)
+ * - replicate(trigger, handler): server pattern (!P)
+ * - supervisor({ process, maxRetries }): error recovery
+ *
+ * Agent patterns:
+ * - agentProcess(agent, input): lift an LLM call into a Process
+ * - codeThenFix({ coder, checker, fixer }): code → check → fix loop
+ * - fanOut({ agents, input, merge }): parallel multi-agent
+ * - pipeline(a, input).then(b).build(): sequential chain
+ * - handoff({ from, to }): channel-mediated agent transfer
+ */
+// Core primitives
+export { Channel, freshId, select } from "./channel.js";
+// Process algebra
+export { TraceCollector, par, seq, choice, branchFix, restrict, replicate, supervisor, } from "./process.js";
+// Agent wrappers
+export { agentProcess, codeThenFix, fanOut, pipeline, PipelineBuilder, handoff, } from "./agent.js";
+// Scheduler
+export { Scheduler } from "./scheduler.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,kBAAkB;AAClB,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAmC,MAAM,cAAc,CAAC;AAEzF,kBAAkB;AAClB,OAAO,EAKL,cAAc,EACd,GAAG,EACH,GAAG,EACH,MAAM,EACN,SAAS,EACT,QAAQ,EACR,SAAS,EACT,UAAU,GACX,MAAM,cAAc,CAAC;AAEtB,iBAAiB;AACjB,OAAO,EAGL,YAAY,EACZ,WAAW,EACX,MAAM,EACN,QAAQ,EACR,eAAe,EACf,OAAO,GACR,MAAM,YAAY,CAAC;AAEpB,YAAY;AACZ,OAAO,EAAE,SAAS,EAA4C,MAAM,gBAAgB,CAAC"}

package/dist/process.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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 } from "./channel.js";
+export interface ProcessContext {
+    /** Unique run ID for this process instance */
+    readonly runId: string;
+    /** Parent process ID, if spawned as a child */
+    readonly parentId?: string;
+    /** Abort signal — checked by cooperative processes */
+    readonly signal: AbortSignal;
+    /** Trace collector for session tree */
+    readonly trace: TraceCollector;
+    /** Named channels available in scope */
+    readonly channels: Map<string, Channel<any>>;
+}
+export type Process<T = void> = (ctx: ProcessContext) => Promise<T>;
+export type TraceEvent = {
+    type: "spawn";
+    runId: string;
+    parentId?: string;
+    name: string;
+    ts: number;
+} | {
+    type: "send";
+    runId: string;
+    channel: string;
+    ts: number;
+} | {
+    type: "receive";
+    runId: string;
+    channel: string;
+    ts: number;
+} | {
+    type: "branch";
+    runId: string;
+    chosen: string;
+    alternatives: string[];
+    ts: number;
+} | {
+    type: "fix_start";
+    runId: string;
+    reason: string;
+    ts: number;
+} | {
+    type: "fix_end";
+    runId: string;
+    success: boolean;
+    ts: number;
+} | {
+    type: "done";
+    runId: string;
+    ts: number;
+} | {
+    type: "error";
+    runId: string;
+    error: string;
+    ts: number;
+};
+export declare class TraceCollector {
+    readonly events: TraceEvent[];
+    emit(event: TraceEvent): void;
+    /** Get a serialisable session tree from the flat event log */
+    toTree(): SessionNode[];
+}
+export interface SessionNode {
+    runId: string;
+    name: string;
+    parentId?: string;
+    events: TraceEvent[];
+    children: SessionNode[];
+}
+/**
+ * Parallel composition: P | Q
+ * Runs all processes concurrently and waits for all to complete.
+ */
+export declare function par<T extends any[]>(...processes: {
+    [K in keyof T]: Process<T[K]>;
+}): Process<T>;
+/**
+ * Sequential composition: P ; Q
+ * Runs processes one after another, threading context.
+ */
+export declare function seq<T>(...processes: Process<any>[]): Process<T>;
+/**
+ * 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 declare function choice<T>(branches: Array<{
+    name: string;
+    guard: Channel<any>;
+    process: Process<T>;
+}>): Process<T>;
+/**
+ * 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 declare function branchFix<T>(opts: {
+    name: string;
+    /** The main process. Receives a `requestFix` function it can call. */
+    main: (requestFix: (reason: string) => Promise<void>) => Process<T>;
+    /** Given the reason, produce a fix process. */
+    fix: (reason: string) => Process<void>;
+    /** Max number of fix cycles before giving up */
+    maxFixes?: number;
+}): Process<T>;
+/**
+ * Restriction: ν(name). Creates a fresh scoped channel.
+ * The channel is only visible to processes inside the scope.
+ */
+export declare function restrict<T, R>(name: string, body: (ch: Channel<T>) => Process<R>): Process<R>;
+/**
+ * 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 declare function replicate<T>(trigger: Channel<T>, handler: (value: T) => Process<void>): Process<void>;
+/**
+ * Supervisor: wraps a process with retry + fallback semantics.
+ * On failure, can either restart the process or run a recovery process.
+ */
+export declare function supervisor<T>(opts: {
+    name: string;
+    process: Process<T>;
+    maxRetries?: number;
+    onError?: (err: Error, attempt: number) => Process<void>;
+    fallback?: Process<T>;
+}): Process<T>;
+//# sourceMappingURL=process.d.ts.map

package/dist/process.d.ts.map

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