@baryonlabs/pi-dynamic-workflows 1.0.2

package/dist/workflow-tool.js

@@ -0,0 +1,183 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { createToolUpdateWorkflowDisplay, createWorkflowSnapshot, preview, recomputeWorkflowSnapshot, renderWorkflowText, } from "./display.js";
+import { parseWorkflowScript, runWorkflow } from "./workflow.js";
+const workflowToolSchema = Type.Object({
+    script: Type.String({
+        description: [
+            "Required raw JavaScript workflow script, with no Markdown fences.",
+            "First statement: export const meta = { name: 'short_snake_case', description: 'non-empty description' }. meta.phases is optional documentation; live progress is driven by phase(title).",
+            "Use phase('Name'), agent(prompt, opts), parallel(arrayOfFunctions), pipeline(items, ...stages), log(message), args, and budget. The workflow must call agent() at least once.",
+            "parallel() requires functions, not promises: await parallel(items.map(item => () => agent(...))).",
+        ].join(" "),
+    }),
+    args: Type.Optional(Type.Any({ description: "Optional JSON value exposed to the workflow script as global `args`." })),
+});
+const workflowDisplayOptions = {
+    key: "workflow",
+    streamToolUpdates: true,
+    maxAgents: 4,
+    maxLogs: 1,
+    showResultPreviews: false,
+};
+export function createWorkflowTool(options = {}) {
+    return defineTool({
+        name: "workflow",
+        label: "Workflow",
+        description: [
+            "Execute a deterministic JavaScript workflow that orchestrates multiple subagents with agent(), parallel(), and pipeline().",
+            "script is required raw JavaScript. It must start with export const meta = { name, description } and must call agent() at least once; phases are optional metadata.",
+        ].join(" "),
+        promptSnippet: "Run a deterministic JavaScript workflow. Required script header: export const meta = { name: 'short_snake_case', description: 'non-empty description' }. Use phase(title) at runtime to create progress groups.",
+        promptGuidelines: [
+            "Use workflow only when the user explicitly asks for a workflow, workflows, fan-out, or multi-agent orchestration.",
+            "For workflow, always pass one raw JavaScript string in the required script parameter; do not include Markdown fences or prose around the script.",
+            "For workflow, the script's first statement must be `export const meta = { name: 'short_snake_case', description: 'non-empty human description' }`; meta.name and meta.description are required non-empty strings, and meta.phases is optional metadata for a stable upfront outline.",
+            "For workflow, write plain JavaScript after the meta export. Do not use TypeScript syntax, imports, require(), fs, Date.now(), Math.random(), or new Date().",
+            "For workflow, available globals are agent(prompt, opts), parallel(thunks), pipeline(items, ...stages), phase(title), log(message), args, cwd, process.cwd(), and budget. Every workflow must call agent() at least once; do not use workflow only to declare phases or return a static object.",
+            "For workflow, call phase(title) when a new group of work starts. Phase names may be conditional or built in a loop; do not predeclare speculative phases just in case.",
+            "For workflow, prefer it for decomposable work: repository inspection, independent research/checks, multi-perspective review, or fan-out/fan-in synthesis. Do not use it for a single quick file read/edit or when ordinary tools are enough.",
+            "For workflow, parallel() takes functions, not promises: use `await parallel(items.map(item => () => agent('...', { label: '...' })))`, never `await parallel(items.map(item => agent(...)))`. Results are returned in input order.",
+            "For workflow, pipeline(items, ...stages) runs each item through stages sequentially, while different items may run concurrently. Each stage receives (previousValue, originalItem, index).",
+            "For workflow, every agent() call should include a unique short label option, 2-5 words, such as { label: 'repo inventory' } or { label: 'source modules' }; unique labels make live status and error reporting readable.",
+            "For workflow, failed agent(), parallel(), or pipeline() branches return null and log the failure unless the workflow is aborted. Check for nulls before synthesizing conclusions.",
+            "For workflow, include a final synthesis/assertion agent when combining multiple subagent results; return a compact JSON-serializable value with ok/verdict plus the important outputs.",
+            "For workflow, if agent() needs machine-readable output, pass a plain JSON Schema via opts.schema; agent() will return the validated object. Use JSON Schema syntax, not TypeScript or TypeBox constructors.",
+            "For workflow, do not assume the parent assistant has repository code context inside subagents; include enough task context and relevant paths in each agent prompt.",
+        ],
+        parameters: workflowToolSchema,
+        prepareArguments(args) {
+            return normalizeWorkflowToolArgs(args);
+        },
+        async execute(_toolCallId, params, signal, onUpdate, ctx) {
+            const script = normalizeWorkflowScript(params.script);
+            const parsed = parseWorkflowScript(script);
+            let snapshot = createWorkflowSnapshot(parsed.meta);
+            const display = createToolUpdateWorkflowDisplay(onUpdate, undefined, workflowDisplayOptions);
+            const update = () => {
+                snapshot = recomputeWorkflowSnapshot(snapshot);
+                display.update(snapshot);
+            };
+            const recordPhase = (title) => {
+                if (!title)
+                    return;
+                if (!snapshot.phases.includes(title))
+                    snapshot.phases.push(title);
+            };
+            let result;
+            try {
+                result = await runWorkflow(script, {
+                    cwd: options.cwd ?? ctx.cwd,
+                    args: params.args,
+                    signal,
+                    concurrency: options.concurrency,
+                    session: {
+                        modelRegistry: ctx.modelRegistry,
+                        model: ctx.model,
+                    },
+                    onLog(message) {
+                        snapshot.logs.push(message);
+                        update();
+                    },
+                    onPhase(title) {
+                        snapshot.currentPhase = title;
+                        recordPhase(title);
+                        update();
+                    },
+                    onAgentStart(event) {
+                        if (signal?.aborted)
+                            throw new Error("Workflow was aborted");
+                        recordPhase(event.phase);
+                        snapshot.agents.push({
+                            id: snapshot.agents.length + 1,
+                            label: event.label,
+                            phase: event.phase,
+                            prompt: event.prompt,
+                            status: "running",
+                        });
+                        update();
+                    },
+                    onAgentEnd(event) {
+                        const agent = [...snapshot.agents]
+                            .reverse()
+                            .find((item) => item.label === event.label && item.status === "running");
+                        if (agent) {
+                            agent.status = event.result === null ? "error" : "done";
+                            agent.resultPreview = preview(event.result);
+                        }
+                        update();
+                    },
+                });
+            }
+            catch (error) {
+                if (signal?.aborted || isAbortError(error)) {
+                    for (const agent of snapshot.agents) {
+                        if (agent.status === "running") {
+                            agent.status = "skipped";
+                            agent.error = "aborted";
+                        }
+                    }
+                    snapshot = recomputeWorkflowSnapshot(snapshot);
+                    display.complete(snapshot);
+                    throw new Error("Workflow was aborted");
+                }
+                throw error;
+            }
+            if (result.agentCount === 0) {
+                throw new Error("workflow scripts must call agent() at least once; this workflow declared phases but did not run any subagents");
+            }
+            snapshot.result = result.result;
+            snapshot.durationMs = result.durationMs;
+            snapshot = recomputeWorkflowSnapshot(snapshot);
+            display.complete(snapshot);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Workflow ${result.meta.name} completed with ${result.agentCount} agent(s).\n\nResult:\n${JSON.stringify(result.result, null, 2)}`,
+                    },
+                ],
+                details: {
+                    ...snapshot,
+                    meta: result.meta,
+                    phases: result.phases,
+                    logs: result.logs,
+                    result: result.result,
+                    durationMs: result.durationMs,
+                },
+            };
+        },
+        renderCall(_args, theme) {
+            return new Text(theme.fg("toolTitle", theme.bold("workflow")), 0, 0);
+        },
+        renderResult(result, { isPartial }, theme) {
+            const snapshot = result.details;
+            if (snapshot?.name) {
+                return new Text(renderWorkflowText(snapshot, !isPartial, workflowDisplayOptions), 0, 0);
+            }
+            const text = result.content?.[0];
+            return new Text(text?.type === "text" ? text.text : theme.fg("muted", "workflow"), 0, 0);
+        },
+    });
+}
+function normalizeWorkflowToolArgs(args) {
+    if (!args || typeof args !== "object")
+        throw new Error("workflow requires an object argument with a script string");
+    const value = args;
+    if (typeof value.script !== "string")
+        throw new Error("workflow requires `script` to be a string");
+    return { ...value, script: normalizeWorkflowScript(value.script) };
+}
+function normalizeWorkflowScript(script) {
+    let text = script.trim();
+    const fence = text.match(/^```(?:js|javascript)?\s*\n([\s\S]*?)\n```$/i);
+    if (fence)
+        text = fence[1].trim();
+    return text;
+}
+function isAbortError(error) {
+    if (!(error instanceof Error))
+        return false;
+    return /\babort(?:ed)?\b/i.test(error.message);
+}

package/dist/workflow.d.ts

@@ -0,0 +1,53 @@
+import type { TSchema } from "typebox";
+import { WorkflowAgent, type WorkflowAgentOptions } from "./agent.js";
+export interface WorkflowMetaPhase {
+    title: string;
+    detail?: string;
+    model?: string;
+}
+export interface WorkflowMeta {
+    name: string;
+    description: string;
+    whenToUse?: string;
+    phases?: WorkflowMetaPhase[];
+}
+export interface WorkflowRunOptions extends WorkflowAgentOptions {
+    args?: unknown;
+    agent?: Pick<WorkflowAgent, "run">;
+    concurrency?: number;
+    tokenBudget?: number | null;
+    signal?: AbortSignal;
+    onLog?: (message: string) => void;
+    onPhase?: (title: string) => void;
+    onAgentStart?: (event: {
+        label: string;
+        phase?: string;
+        prompt: string;
+    }) => void;
+    onAgentEnd?: (event: {
+        label: string;
+        phase?: string;
+        result: unknown;
+    }) => void;
+}
+export interface WorkflowRunResult<T = unknown> {
+    meta: WorkflowMeta;
+    result: T;
+    logs: string[];
+    phases: string[];
+    agentCount: number;
+    durationMs: number;
+}
+export interface AgentOptions<TSchemaDef extends TSchema | undefined = TSchema | undefined> {
+    label?: string;
+    phase?: string;
+    schema?: TSchemaDef;
+    model?: string;
+    isolation?: "worktree";
+    agentType?: string;
+}
+export declare function runWorkflow<T = unknown>(script: string, options?: WorkflowRunOptions): Promise<WorkflowRunResult<T>>;
+export declare function parseWorkflowScript(script: string): {
+    meta: WorkflowMeta;
+    body: string;
+};

package/dist/workflow.js

@@ -0,0 +1,426 @@
+import vm from "node:vm";
+import { parse } from "acorn";
+import { WorkflowAgent } from "./agent.js";
+const NONDETERMINISM_ERROR = "Workflow scripts must be deterministic: Date.now()/Math.random()/new Date() are unavailable";
+export async function runWorkflow(script, options = {}) {
+    const started = Date.now();
+    const { meta, body } = parseWorkflowScript(script);
+    const state = { logs: [], phases: [], agentCount: 0, spent: 0 };
+    const agentRunner = options.agent ?? new WorkflowAgent(options);
+    const concurrency = Math.max(1, Math.min(options.concurrency ?? Math.max(1, (globalThis.navigator?.hardwareConcurrency ?? 8) - 2), 16));
+    const limiter = createLimiter(concurrency);
+    const pendingAgentRuns = new Set();
+    const log = (message) => {
+        const text = String(message);
+        state.logs.push(text);
+        options.onLog?.(text);
+    };
+    const phase = (title) => {
+        const text = requireString(title, "phase title");
+        state.currentPhase = text;
+        if (!state.phases.includes(text))
+            state.phases.push(text);
+        options.onPhase?.(text);
+    };
+    const budget = Object.freeze({
+        total: options.tokenBudget ?? null,
+        spent: () => state.spent,
+        remaining: () => (options.tokenBudget == null ? Infinity : Math.max(0, options.tokenBudget - state.spent)),
+    });
+    const throwIfAborted = () => {
+        if (options.signal?.aborted)
+            throw new Error("workflow aborted");
+    };
+    const agent = async (prompt, agentOptions = {}) => {
+        throwIfAborted();
+        if (budget.total !== null && budget.remaining() <= 0)
+            throw new Error("workflow token budget exhausted");
+        const taskPrompt = requireString(prompt, "agent prompt");
+        const normalizedOptions = normalizeAgentOptions(agentOptions);
+        const assignedPhase = normalizedOptions.phase ?? state.currentPhase;
+        const requestedLabel = normalizedOptions.label?.trim();
+        const run = limiter(async () => {
+            state.agentCount++;
+            const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
+            options.onAgentStart?.({ label, phase: assignedPhase, prompt: taskPrompt });
+            try {
+                throwIfAborted();
+                const result = await agentRunner.run(taskPrompt, {
+                    label,
+                    schema: normalizedOptions.schema,
+                    signal: options.signal,
+                    instructions: buildAgentInstructions(assignedPhase, normalizedOptions),
+                });
+                throwIfAborted();
+                state.spent += estimateTokens(result);
+                options.onAgentEnd?.({ label, phase: assignedPhase, result });
+                return result;
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    throw error;
+                log(`agent ${label} failed: ${error instanceof Error ? error.message : String(error)}`);
+                options.onAgentEnd?.({ label, phase: assignedPhase, result: null });
+                return null;
+            }
+        });
+        pendingAgentRuns.add(run);
+        run.then(() => pendingAgentRuns.delete(run), () => pendingAgentRuns.delete(run));
+        return run;
+    };
+    const parallel = async (thunks) => {
+        throwIfAborted();
+        if (!Array.isArray(thunks))
+            throw new TypeError("parallel() expects an array of functions");
+        if (thunks.some((thunk) => typeof thunk !== "function")) {
+            throw new TypeError("parallel() expects an array of functions, not promises. Wrap each call: () => agent(...)");
+        }
+        return Promise.all(thunks.map(async (thunk, index) => {
+            try {
+                return await thunk();
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    throw error;
+                log(`parallel[${index}] failed: ${error instanceof Error ? error.message : String(error)}`);
+                return null;
+            }
+        }));
+    };
+    const pipeline = async (items, ...stages) => {
+        throwIfAborted();
+        if (!Array.isArray(items))
+            throw new TypeError("pipeline() expects an array as the first argument");
+        if (stages.some((stage) => typeof stage !== "function")) {
+            throw new TypeError("pipeline() stages must be functions: pipeline(items, item => ..., result => ...)");
+        }
+        return Promise.all(items.map(async (item, index) => {
+            let value = item;
+            for (const stage of stages) {
+                try {
+                    throwIfAborted();
+                    value = await stage(value, item, index);
+                    throwIfAborted();
+                }
+                catch (error) {
+                    if (options.signal?.aborted)
+                        throw error;
+                    log(`pipeline[${index}] failed: ${error instanceof Error ? error.message : String(error)}`);
+                    return null;
+                }
+            }
+            return value;
+        }));
+    };
+    // Models sometimes hallucinate host APIs inside workflow scripts (bash, fetch,
+    // require, ...). A bare ReferenceError is opaque and, when thrown inside an
+    // un-awaited async call, escapes as an unhandled rejection. Predefine the
+    // usual suspects as guards that throw a descriptive, actionable error instead.
+    const unavailable = (name, hint) => () => {
+        throw new Error(`${name}() is not available in workflow scripts — ${hint}`);
+    };
+    const shellHint = 'delegate shell/file work to a subagent instead, e.g. await agent("run <command> and report the output")';
+    const guards = Object.fromEntries(["bash", "sh", "shell", "exec", "execSync", "spawn", "spawnSync", "system"].map((name) => [
+        name,
+        unavailable(name, shellHint),
+    ]));
+    guards.fetch = unavailable("fetch", 'use await agent("fetch <url> and report ...") instead');
+    guards.require = unavailable("require", "workflow scripts have no module system; use agent()/parallel()/pipeline()");
+    const context = vm.createContext({
+        ...guards,
+        agent,
+        parallel,
+        pipeline,
+        log,
+        phase,
+        args: options.args,
+        cwd: options.cwd ?? process.cwd(),
+        process: Object.freeze({ cwd: () => options.cwd ?? process.cwd() }),
+        budget,
+        console: {
+            log,
+            info: log,
+            warn: (m) => log(`[warn] ${String(m)}`),
+            error: (m) => log(`[error] ${String(m)}`),
+        },
+        JSON,
+        Math,
+        Array,
+        Object,
+        String,
+        Number,
+        Boolean,
+        Set,
+        Map,
+        Promise,
+    });
+    const wrapped = `(async () => {\n${body}\n})()`;
+    // A floating rejection inside the script (e.g. an un-awaited `main()` that
+    // throws) bypasses this await and escapes as a process-level unhandled
+    // rejection — killing the HOST process (pi exits, losing the session).
+    // Capture unhandled rejections for the duration of the run and fail the
+    // workflow with them instead, so the error comes back as a tool result.
+    // Node emits `unhandledRejection` at end-of-tick, possibly AFTER the script
+    // resolves — so keep listening one extra event-loop turn before deciding.
+    let floated = false;
+    let floatingReject;
+    const floatingRejection = new Promise((_, reject) => {
+        floatingReject = (reason) => {
+            floated = true;
+            reject(reason instanceof Error ? reason : new Error(String(reason)));
+        };
+    });
+    floatingRejection.catch(() => { }); // avoid the sentinel itself going unhandled
+    const onUnhandled = (reason) => floatingReject(reason);
+    process.on("unhandledRejection", onUnhandled);
+    let result;
+    try {
+        const scriptRun = new vm.Script(wrapped, { filename: `${meta.name || "workflow"}.js` }).runInContext(context);
+        result = await Promise.race([scriptRun, floatingRejection]);
+        await Promise.allSettled([...pendingAgentRuns]);
+    }
+    finally {
+        // Late rejections surface on the next tick — absorb them before detaching,
+        // otherwise they'd escape to the process the instant we stop listening.
+        await new Promise((resolve) => setImmediate(resolve));
+        process.off("unhandledRejection", onUnhandled);
+    }
+    if (floated)
+        await floatingRejection; // rethrow the captured floating error
+    assertStructuredCloneable(result, "workflow result");
+    return {
+        meta,
+        result: result,
+        logs: state.logs,
+        phases: state.phases,
+        agentCount: state.agentCount,
+        durationMs: Date.now() - started,
+    };
+}
+export function parseWorkflowScript(script) {
+    const ast = parse(script, {
+        ecmaVersion: "latest",
+        sourceType: "module",
+        allowAwaitOutsideFunction: true,
+        allowReturnOutsideFunction: true,
+        ranges: false,
+    });
+    assertDeterministicAst(ast);
+    const first = ast.body?.[0];
+    if (first?.type !== "ExportNamedDeclaration") {
+        throw new Error("`export const meta = { name, description }` must be the first statement in the script");
+    }
+    const declaration = first.declaration;
+    if (declaration?.type !== "VariableDeclaration" || declaration.kind !== "const") {
+        throw new Error("meta export must be `export const meta = ...`");
+    }
+    if (declaration.declarations.length !== 1) {
+        throw new Error("meta export must declare only `meta`");
+    }
+    const declarator = declaration.declarations[0];
+    if (declarator.id?.type !== "Identifier" || declarator.id.name !== "meta") {
+        throw new Error("meta export must declare `meta`");
+    }
+    if (!declarator.init)
+        throw new Error("meta must have a literal value");
+    const meta = evaluateLiteral(declarator.init, "meta");
+    validateMeta(meta);
+    return {
+        meta,
+        body: script.slice(0, first.start) + script.slice(first.end),
+    };
+}
+function evaluateLiteral(node, path) {
+    switch (node.type) {
+        case "ObjectExpression": {
+            const out = {};
+            for (const prop of node.properties) {
+                if (prop.type === "SpreadElement")
+                    throw new Error(`spread not allowed in ${path}`);
+                if (prop.type !== "Property")
+                    throw new Error(`only plain properties allowed in ${path}`);
+                if (prop.computed)
+                    throw new Error(`computed keys not allowed in ${path}`);
+                if (prop.kind !== "init" || prop.method)
+                    throw new Error(`methods/accessors not allowed in ${path}`);
+                const key = propertyKey(prop.key, path);
+                if (key === "__proto__" || key === "constructor" || key === "prototype") {
+                    throw new Error(`reserved key name not allowed in ${path}: ${key}`);
+                }
+                out[key] = evaluateLiteral(prop.value, `${path}.${key}`);
+            }
+            return out;
+        }
+        case "ArrayExpression":
+            return node.elements.map((element, index) => {
+                if (!element)
+                    throw new Error(`sparse arrays not allowed in ${path}`);
+                if (element.type === "SpreadElement")
+                    throw new Error(`spread not allowed in ${path}`);
+                return evaluateLiteral(element, `${path}[${index}]`);
+            });
+        case "Literal":
+            return node.value;
+        case "TemplateLiteral":
+            if (node.expressions.length > 0)
+                throw new Error(`template interpolation not allowed in ${path}`);
+            return node.quasis.map((quasi) => quasi.value.cooked ?? quasi.value.raw).join("");
+        case "UnaryExpression":
+            if (node.operator === "-" && node.argument?.type === "Literal" && typeof node.argument.value === "number") {
+                return -node.argument.value;
+            }
+            throw new Error(`only negative-number unary allowed in ${path}`);
+        default:
+            throw new Error(`non-literal node type in ${path}: ${node.type}`);
+    }
+}
+function propertyKey(node, path) {
+    if (node.type === "Identifier")
+        return node.name;
+    if (node.type === "Literal" && (typeof node.value === "string" || typeof node.value === "number"))
+        return String(node.value);
+    throw new Error(`unsupported key type in ${path}: ${node.type}`);
+}
+function assertDeterministicAst(node) {
+    if (isDateNowCall(node) || isMathRandomCall(node) || isNewDateExpression(node)) {
+        throw new Error(NONDETERMINISM_ERROR);
+    }
+    for (const child of astChildren(node))
+        assertDeterministicAst(child);
+}
+function astChildren(node) {
+    const children = [];
+    for (const value of Object.values(node)) {
+        if (Array.isArray(value))
+            children.push(...value.filter(isAstNode));
+        else if (isAstNode(value))
+            children.push(value);
+    }
+    return children;
+}
+function isAstNode(value) {
+    return !!value && typeof value === "object" && typeof value.type === "string";
+}
+function isDateNowCall(node) {
+    return node.type === "CallExpression" && isMemberExpression(node.callee, "Date", "now");
+}
+function isMathRandomCall(node) {
+    return node.type === "CallExpression" && isMemberExpression(node.callee, "Math", "random");
+}
+function isNewDateExpression(node) {
+    return node.type === "NewExpression" && node.callee?.type === "Identifier" && node.callee.name === "Date";
+}
+function isMemberExpression(node, objectName, propertyName) {
+    if (node?.type !== "MemberExpression" || node.object?.type !== "Identifier" || node.object.name !== objectName) {
+        return false;
+    }
+    return propertyNameOf(node) === propertyName;
+}
+function propertyNameOf(node) {
+    if (!node.computed && node.property?.type === "Identifier")
+        return node.property.name;
+    return staticStringOf(node.property);
+}
+function staticStringOf(node) {
+    if (node?.type === "Literal" && typeof node.value === "string")
+        return node.value;
+    if (node?.type === "TemplateLiteral" && node.expressions.length === 0) {
+        return node.quasis.map((quasi) => quasi.value.cooked ?? quasi.value.raw).join("");
+    }
+    if (node?.type === "BinaryExpression" && node.operator === "+") {
+        const left = staticStringOf(node.left);
+        const right = staticStringOf(node.right);
+        if (left !== undefined && right !== undefined)
+            return left + right;
+    }
+    return undefined;
+}
+function validateMeta(meta) {
+    if (!meta || typeof meta !== "object")
+        throw new Error("meta must be an object");
+    const value = meta;
+    if (typeof value.name !== "string" || !value.name.trim())
+        throw new Error("meta.name must be a non-empty string");
+    if (typeof value.description !== "string" || !value.description.trim())
+        throw new Error("meta.description must be a non-empty string");
+    if (value.whenToUse !== undefined && typeof value.whenToUse !== "string")
+        throw new Error("meta.whenToUse must be a string");
+    if (value.phases !== undefined) {
+        if (!Array.isArray(value.phases))
+            throw new Error("meta.phases must be an array");
+        for (const phase of value.phases) {
+            if (!phase || typeof phase !== "object" || typeof phase.title !== "string") {
+                throw new Error("each meta phase must have a title string");
+            }
+        }
+    }
+}
+function createLimiter(limit) {
+    let active = 0;
+    const queue = [];
+    const next = () => {
+        active--;
+        queue.shift()?.();
+    };
+    return async (fn) => {
+        if (active >= limit)
+            await new Promise((resolve) => queue.push(resolve));
+        active++;
+        try {
+            return await fn();
+        }
+        finally {
+            next();
+        }
+    };
+}
+function requireString(value, name) {
+    if (typeof value !== "string")
+        throw new TypeError(`${name} must be a string`);
+    return value;
+}
+function optionalString(value, name) {
+    if (value === undefined)
+        return undefined;
+    return requireString(value, name);
+}
+function normalizeAgentOptions(value) {
+    if (!value || typeof value !== "object")
+        throw new TypeError("agent options must be an object");
+    const options = value;
+    return {
+        ...options,
+        label: optionalString(options.label, "agent label"),
+        phase: optionalString(options.phase, "agent phase"),
+        model: optionalString(options.model, "agent model"),
+        isolation: options.isolation,
+        agentType: optionalString(options.agentType, "agent type"),
+    };
+}
+function assertStructuredCloneable(value, name) {
+    try {
+        structuredClone(value);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? ` ${error.message}` : "";
+        throw new Error(`${name} must be structured-cloneable; did you forget to await agent(), parallel(), or pipeline()?${detail}`);
+    }
+}
+function defaultAgentLabel(phase, index) {
+    return phase ? `${phase} agent ${index}` : `agent ${index}`;
+}
+function buildAgentInstructions(phase, options) {
+    const lines = [];
+    if (phase)
+        lines.push(`Workflow phase: ${phase}`);
+    if (options.agentType)
+        lines.push(`Act as workflow subagent type: ${options.agentType}`);
+    if (options.isolation)
+        lines.push(`Requested isolation: ${options.isolation}`);
+    if (options.model)
+        lines.push(`Requested model: ${options.model}`);
+    return lines.length ? lines.join("\n") : undefined;
+}
+function estimateTokens(value) {
+    return Math.ceil(JSON.stringify(value ?? "").length / 4);
+}

package/extensions/workflow.ts

@@ -0,0 +1,14 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createWorkflowTool } from "../src/index.js";
+
+export default function extension(pi: ExtensionAPI) {
+  const workflowTool = createWorkflowTool();
+  pi.registerTool(workflowTool);
+
+  pi.on("session_start", () => {
+    const active = pi.getActiveTools();
+    if (!active.includes(workflowTool.name)) {
+      pi.setActiveTools([...active, workflowTool.name]);
+    }
+  });
+}