@quintinshaw/pi-dynamic-workflows 1.0.0

package/dist/workflow-tool.js

@@ -0,0 +1,216 @@
+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 { WorkflowError, WorkflowErrorCode } from "./errors.js";
+import { parseWorkflowScript, runWorkflow } from "./workflow.js";
+import { WorkflowManager } from "./workflow-manager.js";
+import { createWorkflowStorage } from "./workflow-saved.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', phases: [{ title: 'Phase' }] }",
+            "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`." })),
+    background: Type.Optional(Type.Boolean({
+        description: "Run the workflow in the background. Default: false. When true, returns immediately with a run ID.",
+    })),
+    maxAgents: Type.Optional(Type.Number({
+        description: "Maximum number of agents allowed in this run. Default: 1000.",
+    })),
+    agentTimeoutMs: Type.Optional(Type.Number({
+        description: "Timeout per agent in milliseconds. Default: 300000 (5 minutes).",
+    })),
+});
+export function createWorkflowTool(options = {}) {
+    const manager = new WorkflowManager({ cwd: options.cwd, concurrency: options.concurrency });
+    const _storage = createWorkflowStorage(options.cwd ?? process.cwd());
+    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, phases? } and must call agent() at least once.",
+        ].join(" "),
+        promptSnippet: "Run a deterministic JavaScript workflow. Required script header: export const meta = { name: 'short_snake_case', description: 'non-empty description', phases: [{ title: 'Phase' }] }.",
+        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', phases: [{ title: 'Phase name' }] }`; meta.name and meta.description are required non-empty strings.",
+            "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, 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.",
+            "For workflow, set background: true to run asynchronously. The workflow will return immediately with a run ID that can be used to check status later.",
+        ],
+        parameters: workflowToolSchema,
+        prepareArguments(args) {
+            return normalizeWorkflowToolArgs(args);
+        },
+        async execute(_toolCallId, params, signal, onUpdate, ctx) {
+            const script = normalizeWorkflowScript(params.script);
+            const parsed = parseWorkflowScript(script);
+            // Background execution
+            if (params.background) {
+                const { runId } = manager.startInBackground(script, params.args);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                `Workflow "${parsed.meta.name}" started in background.`,
+                                `Run ID: ${runId}`,
+                                `Use /workflow status ${runId} to check progress.`,
+                                `Use /workflow stop ${runId} to cancel.`,
+                            ].join("\n"),
+                        },
+                    ],
+                    details: { runId, background: true },
+                };
+            }
+            // Synchronous execution (blocking)
+            let snapshot = createWorkflowSnapshot(parsed.meta);
+            const display = createToolUpdateWorkflowDisplay(onUpdate, undefined, {
+                key: "workflow",
+                streamToolUpdates: true,
+                maxAgents: 4,
+                maxLogs: 1,
+                showResultPreviews: false,
+            });
+            const update = () => {
+                snapshot = recomputeWorkflowSnapshot(snapshot);
+                display.update(snapshot);
+            };
+            let result;
+            try {
+                result = await runWorkflow(script, {
+                    cwd: options.cwd ?? ctx.cwd,
+                    args: params.args,
+                    signal,
+                    concurrency: options.concurrency,
+                    maxAgents: params.maxAgents,
+                    agentTimeoutMs: params.agentTimeoutMs,
+                    onLog(message) {
+                        snapshot.logs.push(message);
+                        update();
+                    },
+                    onPhase(title) {
+                        snapshot.currentPhase = title;
+                        if (!snapshot.phases.includes(title))
+                            snapshot.phases.push(title);
+                        update();
+                    },
+                    onAgentStart(event) {
+                        if (signal?.aborted)
+                            throw new Error("Workflow was aborted");
+                        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);
+                            agent.tokens = event.tokens;
+                        }
+                        update();
+                    },
+                    onTokenUsage(usage) {
+                        snapshot.tokenUsage = usage;
+                        update();
+                    },
+                });
+            }
+            catch (error) {
+                if (signal?.aborted || (error instanceof WorkflowError && error.code === WorkflowErrorCode.WORKFLOW_ABORTED)) {
+                    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);
+            // Format token usage
+            const tokenInfo = result.tokenUsage ? `\n\nToken usage: ${result.tokenUsage.total.toLocaleString()} tokens` : "";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Workflow ${result.meta.name} completed with ${result.agentCount} agent(s).\n\nResult:\n${JSON.stringify(result.result, null, 2)}${tokenInfo}`,
+                    },
+                ],
+                details: {
+                    ...snapshot,
+                    meta: result.meta,
+                    phases: result.phases,
+                    logs: result.logs,
+                    result: result.result,
+                    durationMs: result.durationMs,
+                    tokenUsage: result.tokenUsage,
+                    runId: result.runId,
+                },
+            };
+        },
+        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), 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,75 @@
+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;
+    /** Maximum number of agents allowed in this run. Default: 1000 */
+    maxAgents?: number;
+    /** Timeout per agent in milliseconds. Default: 5 minutes */
+    agentTimeoutMs?: number;
+    /** Whether to persist logs to disk. Default: true */
+    persistLogs?: boolean;
+    /** Run ID for persistence. Auto-generated if not provided. */
+    runId?: string;
+    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;
+        tokens?: number;
+    }) => void;
+    onTokenUsage?: (usage: {
+        input: number;
+        output: number;
+        total: number;
+    }) => void;
+}
+export interface WorkflowRunResult<T = unknown> {
+    meta: WorkflowMeta;
+    result: T;
+    logs: string[];
+    phases: string[];
+    agentCount: number;
+    durationMs: number;
+    runId?: string;
+    tokenUsage?: {
+        input: number;
+        output: number;
+        total: number;
+    };
+}
+export interface AgentOptions<TSchemaDef extends TSchema | undefined = TSchema | undefined> {
+    label?: string;
+    phase?: string;
+    schema?: TSchemaDef;
+    model?: string;
+    isolation?: "worktree";
+    agentType?: string;
+    /** Override timeout for this specific agent. */
+    timeoutMs?: number;
+}
+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,364 @@
+import vm from "node:vm";
+import { parse } from "acorn";
+import { WorkflowAgent } from "./agent.js";
+import { DEFAULT_AGENT_TIMEOUT_MS, MAX_AGENTS_PER_RUN, MAX_CONCURRENCY } from "./config.js";
+import { WorkflowError, WorkflowErrorCode, wrapError } from "./errors.js";
+import { createWorkflowLogger } from "./logger.js";
+const DETERMINISM_BLOCKLIST = /\bDate\s*\.\s*now\b|\bMath\s*\.\s*random\b|\bnew\s+Date\s*\(\s*\)/;
+export async function runWorkflow(script, options = {}) {
+    const started = Date.now();
+    const { meta, body } = parseWorkflowScript(script);
+    const maxAgents = options.maxAgents ?? MAX_AGENTS_PER_RUN;
+    const agentTimeoutMs = options.agentTimeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS;
+    const runId = options.runId ?? `run-${started.toString(36)}`;
+    // Initialize logger
+    const logger = createWorkflowLogger({
+        runId,
+        cwd: options.cwd ?? process.cwd(),
+        persist: options.persistLogs ?? true,
+        onLog: options.onLog,
+    });
+    const state = {
+        logs: [],
+        phases: [],
+        agentCount: 0,
+        spent: 0,
+        tokenUsage: { input: 0, output: 0, total: 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), MAX_CONCURRENCY));
+    const limiter = createLimiter(concurrency);
+    const log = (message) => {
+        const text = String(message);
+        state.logs.push(text);
+        logger.log(text);
+    };
+    const phase = (title) => {
+        state.currentPhase = title;
+        if (!state.phases.includes(title))
+            state.phases.push(title);
+        options.onPhase?.(title);
+    };
+    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 WorkflowError("workflow aborted", WorkflowErrorCode.WORKFLOW_ABORTED, { recoverable: true });
+        }
+    };
+    const agent = async (prompt, agentOptions = {}) => {
+        throwIfAborted();
+        // Check agent limit
+        if (state.agentCount >= maxAgents) {
+            throw new WorkflowError(`Agent limit exceeded (${maxAgents}). Use maxAgents option to increase the limit.`, WorkflowErrorCode.AGENT_LIMIT_EXCEEDED, { recoverable: false });
+        }
+        if (budget.total !== null && budget.remaining() <= 0) {
+            throw new WorkflowError("workflow token budget exhausted", WorkflowErrorCode.TOKEN_BUDGET_EXHAUSTED, {
+                recoverable: false,
+            });
+        }
+        const assignedPhase = agentOptions.phase ?? state.currentPhase;
+        const requestedLabel = agentOptions.label?.trim();
+        return limiter(async () => {
+            state.agentCount++;
+            const label = requestedLabel || defaultAgentLabel(assignedPhase, state.agentCount);
+            const timeout = agentOptions.timeoutMs ?? agentTimeoutMs;
+            options.onAgentStart?.({ label, phase: assignedPhase, prompt });
+            try {
+                throwIfAborted();
+                // Run agent with timeout
+                const result = await withTimeout(agentRunner.run(prompt, {
+                    label,
+                    schema: agentOptions.schema,
+                    signal: options.signal,
+                    instructions: buildAgentInstructions(assignedPhase, agentOptions),
+                }), timeout, `Agent "${label}" timed out after ${timeout}ms`);
+                throwIfAborted();
+                // Estimate token usage
+                const tokens = estimateTokens(result) + estimateTokens(prompt);
+                state.spent += tokens;
+                state.tokenUsage.total += tokens;
+                options.onAgentEnd?.({ label, phase: assignedPhase, result, tokens });
+                return result;
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    throw error;
+                const workflowError = wrapError(error, { agentLabel: label });
+                logger.error(`agent ${label} failed: ${workflowError.message}`);
+                const errorTokens = estimateTokens(prompt);
+                state.tokenUsage.total += errorTokens;
+                options.onAgentEnd?.({ label, phase: assignedPhase, result: null, tokens: errorTokens });
+                // Return null for recoverable errors
+                if (workflowError.recoverable) {
+                    return null;
+                }
+                throw workflowError;
+            }
+        });
+    };
+    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;
+                const workflowError = wrapError(error);
+                log(`parallel[${index}] failed: ${workflowError.message}`);
+                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;
+                    const workflowError = wrapError(error);
+                    log(`pipeline[${index}] failed: ${workflowError.message}`);
+                    return null;
+                }
+            }
+            return value;
+        }));
+    };
+    const context = vm.createContext({
+        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})()`;
+    const result = await new vm.Script(wrapped, { filename: `${meta.name || "workflow"}.js` }).runInContext(context);
+    // Persist logs
+    const logFile = logger.persist();
+    if (logFile) {
+        log(`Logs persisted to ${logFile}`);
+    }
+    // Emit final token usage
+    options.onTokenUsage?.(state.tokenUsage);
+    return {
+        meta,
+        result: result,
+        logs: state.logs,
+        phases: state.phases,
+        agentCount: state.agentCount,
+        durationMs: Date.now() - started,
+        runId,
+        tokenUsage: state.tokenUsage,
+    };
+}
+export function parseWorkflowScript(script) {
+    if (DETERMINISM_BLOCKLIST.test(script)) {
+        throw new WorkflowError("Workflow scripts must be deterministic: Date.now()/Math.random()/new Date() are unavailable", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false });
+    }
+    const ast = parse(script, {
+        ecmaVersion: "latest",
+        sourceType: "module",
+        allowAwaitOutsideFunction: true,
+        allowReturnOutsideFunction: true,
+        ranges: false,
+    });
+    const first = ast.body?.[0];
+    if (first?.type !== "ExportNamedDeclaration") {
+        throw new WorkflowError("`export const meta = { name, description, phases }` must be the first statement in the script", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false });
+    }
+    const declaration = first.declaration;
+    if (declaration?.type !== "VariableDeclaration" || declaration.kind !== "const") {
+        throw new WorkflowError("meta export must be `export const meta = ...`", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+            recoverable: false,
+        });
+    }
+    if (declaration.declarations.length !== 1) {
+        throw new WorkflowError("meta export must declare only `meta`", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+            recoverable: false,
+        });
+    }
+    const declarator = declaration.declarations[0];
+    if (declarator.id?.type !== "Identifier" || declarator.id.name !== "meta") {
+        throw new WorkflowError("meta export must declare `meta`", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+            recoverable: false,
+        });
+    }
+    if (!declarator.init)
+        throw new WorkflowError("meta must have a literal value", WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+            recoverable: false,
+        });
+    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 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 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);
+}
+/**
+ * Run a promise with a timeout.
+ */
+async function withTimeout(promise, ms, message) {
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            reject(new WorkflowError(message, WorkflowErrorCode.AGENT_TIMEOUT, { recoverable: true }));
+        }, ms);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    }
+}

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]);
+    }
+  });
+}