@baryonlabs/pi-dynamic-workflows 1.0.2

package/LICENSE

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

package/README.md

@@ -0,0 +1,175 @@
+# @baryonlabs/pi-dynamic-workflows
+
+> Claude-Code-style dynamic workflows for [Pi](https://github.com/earendil-works/pi).
+
+**Baryon fork** of [Michaelliv/pi-dynamic-workflows](https://github.com/Michaelliv/pi-dynamic-workflows) (MIT). This fork fixes a crash: a workflow script that calls a non-existent host API (`bash`, `fetch`, `require`, ...) inside an un-awaited async function used to escape as an unhandled promise rejection and kill the whole `pi` process, not just the workflow call. See [CHANGELOG.md](./CHANGELOG.md).
+
+A Pi extension that adds a `workflow` tool. Instead of one assistant doing everything sequentially, the model writes a small JavaScript script that fans out the work across many isolated subagents, then synthesizes the results.
+
+Great for codebase audits, multi-perspective review, large refactors, and fan-out research.
+
+Inspired by Anthropic's [dynamic workflows in Claude Code](https://claude.com/blog/introducing-dynamic-workflows-in-claude-code).
+
+## Install
+
+```bash
+pi install npm:pi-dynamic-workflows
+# or from a local checkout
+pi install /path/to/pi-dynamic-workflows
+```
+
+Then in Pi:
+
+```text
+/reload
+```
+
+That's it. The extension registers a `workflow` tool and activates it on session start.
+
+## Usage
+
+Just ask Pi for a workflow in plain language:
+
+```text
+Run a workflow to inspect this repository and summarize the main modules.
+```
+
+The model will write a workflow script and call the `workflow` tool. Live progress shows up inline:
+
+```text
+◆ Workflow: inspect_project (3/3 done)
+  ✓ Scan 1/1
+    #1 ✓ repo inventory
+  ✓ Analyze 2/2
+    #2 ✓ source modules
+    #3 ✓ final summary
+```
+
+Press `Esc` to cancel a running workflow. Active subagents are aborted and surfaced as skipped.
+
+## Workflow script shape
+
+A workflow is plain JavaScript. The first statement must export literal metadata. `name` and `description` are required; `phases` is optional documentation for an expected outline. The live progress view is driven by `phase(...)` calls at runtime:
+
+```js
+export const meta = {
+  name: 'inspect_project',
+  description: 'Inspect a repository and summarize the main modules',
+  phases: [
+    { title: 'Scan' },
+    { title: 'Analyze' },
+  ],
+}
+
+phase('Scan')
+const inventory = await agent('Inspect the repository structure.', {
+  label: 'repo inventory',
+})
+
+phase('Analyze')
+const summary = await agent(
+  'Summarize the main modules from this inventory:\n' + inventory,
+  { label: 'module summary' },
+)
+
+return { inventory, summary }
+```
+
+Phases are discovered as the script runs, so conditional and loop-created phases work naturally. If a branch is skipped, its phase does not show up as an empty progress row.
+
+### Editor IntelliSense
+
+Reusable workflow files can opt into editor hints for workflow globals:
+
+```js
+/// <reference types="pi-dynamic-workflows/workflow" />
+```
+
+This declares `agent`, `parallel`, `pipeline`, `phase`, `log`, `args`, `cwd`, and `budget` for TypeScript-aware editors.
+
+### Available globals
+
+| Global | Description |
+| --- | --- |
+| `agent(prompt, opts)` | Spawn an isolated subagent. Returns its final text or, with `opts.schema`, a validated object. |
+| `parallel(thunks)` | Run an array of `() => agent(...)` thunks concurrently. Results are returned in input order. |
+| `pipeline(items, ...stages)` | Run each item through sequential stages while items fan out. Each stage receives `(prev, original, index)`. |
+| `phase(title)` | Mark the current phase. Used for grouping in the live progress view. |
+| `log(message)` | Append a workflow-level log line. |
+| `args` | Optional JSON value passed in via the tool's `args` parameter. |
+| `cwd`, `process.cwd()` | Current working directory for subagents. |
+| `budget` | `{ total, spent(), remaining() }` token budget tracker. |
+
+### Determinism rules
+
+Workflow scripts are evaluated inside a Node `vm` sandbox. The following are intentionally unavailable:
+
+- `Date.now()`, `new Date()`
+- `Math.random()`
+- `require`, `import`, `fs`, network APIs
+- spreads, computed keys, template interpolation, function calls inside `meta`
+
+This keeps `meta` parseable, runs reproducible, and the surface area small.
+
+### Structured subagent output
+
+Pass a JSON Schema via `opts.schema` and the subagent will return a validated object:
+
+```js
+const finding = await agent('Find security-sensitive files.', {
+  label: 'security scan',
+  schema: {
+    type: 'object',
+    properties: {
+      paths: { type: 'array', items: { type: 'string' } },
+      reason: { type: 'string' },
+    },
+    required: ['paths', 'reason'],
+  },
+})
+```
+
+Under the hood this is a Pi `structured_output` tool with `terminate: true`, so the subagent ends on that call without an extra assistant turn.
+
+## How it works
+
+```text
+user prompt
+  → Pi model writes a workflow script
+  → workflow tool parses + runs script in a vm sandbox
+  → script calls agent(), parallel(), pipeline()
+  → each agent() spawns an in-memory Pi subagent session
+  → snapshots stream back as compact progress
+  → final structured result returned to the parent assistant
+```
+
+Subagents run in fresh in-memory Pi sessions with the standard coding tools, so they can read files, run shell commands, and call structured output exactly like a normal Pi turn.
+
+## Library modules
+
+| File | Purpose |
+| --- | --- |
+| `src/workflow.ts` | AST-validated parser and sandboxed workflow runtime. |
+| `src/workflow-tool.ts` | The Pi `workflow` tool, prompt guidelines, rendering, abort handling. |
+| `src/agent.ts` | `WorkflowAgent`, an in-memory Pi subagent runner. |
+| `src/structured-output.ts` | Terminating structured-output tool backed by TypeBox/JSON Schema. |
+| `src/display.ts` | Workflow snapshots and compact text renderers. |
+| `extensions/workflow.ts` | The Pi extension entrypoint. |
+
+## Development
+
+```bash
+npm install
+npm test     # biome check + tsc + unit tests
+npm run dev
+```
+
+Parser unit tests live in `tests/workflow-parser.test.ts` and cover both accepted and rejected script shapes.
+
+## Status
+
+This is a prototype. It implements the core workflow primitive (script, subagents, parallel/pipeline, phases, abort, structured output) but does not yet implement persisted or resumable runs, or a `/workflows` manager.
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,29 @@
+import { type CreateAgentSessionOptions, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { Static, TSchema } from "typebox";
+export interface WorkflowAgentOptions {
+    cwd?: string;
+    /** Extra tools available to the subagent in addition to the structured output tool. */
+    tools?: ToolDefinition[];
+    /** Override any createAgentSession option (model, authStorage, resourceLoader, etc.). */
+    session?: Partial<CreateAgentSessionOptions>;
+    /** Extra system guidance prepended to every subagent task. */
+    instructions?: string;
+}
+export interface AgentRunOptions<TSchemaDef extends TSchema | undefined = undefined> {
+    label?: string;
+    schema?: TSchemaDef;
+    tools?: ToolDefinition[];
+    instructions?: string;
+    signal?: AbortSignal;
+}
+export type AgentRunResult<TSchemaDef extends TSchema | undefined> = TSchemaDef extends TSchema ? Static<TSchemaDef> : string;
+export declare class WorkflowAgent {
+    private readonly cwd;
+    private readonly baseTools;
+    private readonly sessionOptions;
+    private readonly instructions?;
+    constructor(options?: WorkflowAgentOptions);
+    run<TSchemaDef extends TSchema | undefined = undefined>(prompt: string, options?: AgentRunOptions<TSchemaDef>): Promise<AgentRunResult<TSchemaDef>>;
+    private buildPrompt;
+    private lastAssistantText;
+}

package/dist/agent.js

@@ -0,0 +1,86 @@
+import { createAgentSession, createCodingTools, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { createStructuredOutputTool } from "./structured-output.js";
+export class WorkflowAgent {
+    cwd;
+    baseTools;
+    sessionOptions;
+    instructions;
+    constructor(options = {}) {
+        this.cwd = options.cwd ?? process.cwd();
+        this.baseTools = options.tools ?? createCodingTools(this.cwd);
+        this.sessionOptions = options.session ?? {};
+        this.instructions = options.instructions;
+    }
+    async run(prompt, options = {}) {
+        const capture = { called: false, value: undefined };
+        const customTools = [...this.baseTools, ...(options.tools ?? [])];
+        if (options.schema) {
+            customTools.push(createStructuredOutputTool({ schema: options.schema, capture }));
+        }
+        const agentDir = getAgentDir();
+        const { session } = await createAgentSession({
+            cwd: this.cwd,
+            agentDir,
+            sessionManager: SessionManager.inMemory(this.cwd),
+            settingsManager: SettingsManager.create(this.cwd, agentDir),
+            customTools,
+            ...this.sessionOptions,
+        });
+        let removeAbortListener;
+        try {
+            if (options.signal?.aborted)
+                throw new Error("Subagent was aborted");
+            if (options.signal) {
+                const onAbort = () => void session.abort();
+                options.signal.addEventListener("abort", onAbort, { once: true });
+                removeAbortListener = () => options.signal?.removeEventListener("abort", onAbort);
+            }
+            await session.prompt(this.buildPrompt(prompt, options, Boolean(options.schema)));
+            if (options.signal?.aborted)
+                throw new Error("Subagent was aborted");
+            if (options.schema) {
+                if (!capture.called) {
+                    throw new Error("Subagent finished without calling structured_output");
+                }
+                return capture.value;
+            }
+            return this.lastAssistantText(session.messages);
+        }
+        finally {
+            removeAbortListener?.();
+            session.dispose();
+        }
+    }
+    buildPrompt(prompt, options, structured) {
+        const parts = [
+            this.instructions,
+            options.instructions,
+            options.label ? `Task label: ${options.label}` : undefined,
+            prompt,
+        ].filter(Boolean);
+        if (structured) {
+            parts.push([
+                "Final output contract:",
+                "- Your final action MUST be a structured_output tool call.",
+                "- The structured_output arguments are the return value of this subagent.",
+                "- Do not emit a prose final answer instead of structured_output.",
+                "- If you need to inspect files or run commands first, do so, then call structured_output exactly once.",
+            ].join("\n"));
+        }
+        return parts.join("\n\n");
+    }
+    lastAssistantText(messages) {
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const message = messages[i];
+            if (message?.role !== "assistant" || !Array.isArray(message.content))
+                continue;
+            const text = message.content
+                .filter((part) => part.type === "text")
+                .map((part) => part.text)
+                .join("");
+            if (text.trim())
+                return text;
+        }
+        return "";
+    }
+}

package/dist/display.d.ts

@@ -0,0 +1,54 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { WorkflowMeta } from "./workflow.js";
+export type WorkflowAgentStatus = "queued" | "running" | "done" | "error" | "skipped";
+export interface WorkflowAgentSnapshot {
+    id: number;
+    label: string;
+    phase?: string;
+    prompt: string;
+    status: WorkflowAgentStatus;
+    resultPreview?: string;
+    error?: string;
+}
+export interface WorkflowSnapshot {
+    name: string;
+    description?: string;
+    phases: string[];
+    currentPhase?: string;
+    logs: string[];
+    agents: WorkflowAgentSnapshot[];
+    agentCount: number;
+    runningCount: number;
+    doneCount: number;
+    errorCount: number;
+    durationMs?: number;
+    result?: unknown;
+}
+export interface WorkflowDisplay {
+    update(snapshot: WorkflowSnapshot): void;
+    complete(snapshot: WorkflowSnapshot): void;
+    clear(): void;
+}
+export interface WorkflowDisplayOptions {
+    key?: string;
+    placement?: "aboveEditor" | "belowEditor";
+    maxAgents?: number;
+    maxLogs?: number;
+    showStatus?: boolean;
+    showResultPreviews?: boolean;
+}
+export declare function createWorkflowSnapshot(meta: WorkflowMeta): WorkflowSnapshot;
+export declare function recomputeWorkflowSnapshot(snapshot: WorkflowSnapshot): WorkflowSnapshot;
+export declare function createWidgetWorkflowDisplay(ctx: Pick<ExtensionContext, "ui" | "hasUI">, options?: WorkflowDisplayOptions): WorkflowDisplay;
+export declare function createToolUpdateWorkflowDisplay(onUpdate: ((result: {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: unknown;
+}) => void) | undefined, ctx?: Pick<ExtensionContext, "ui" | "hasUI">, options?: WorkflowDisplayOptions & {
+    streamToolUpdates?: boolean;
+}): WorkflowDisplay;
+export declare function renderWorkflowLines(snapshot: WorkflowSnapshot, options?: WorkflowDisplayOptions): string[];
+export declare function renderWorkflowText(snapshot: WorkflowSnapshot, completed?: boolean, options?: WorkflowDisplayOptions): string;
+export declare function preview(value: unknown, max?: number): string;

package/dist/display.js

@@ -0,0 +1,169 @@
+export function createWorkflowSnapshot(meta) {
+    return {
+        name: meta.name,
+        description: meta.description,
+        phases: [],
+        logs: [],
+        agents: [],
+        agentCount: 0,
+        runningCount: 0,
+        doneCount: 0,
+        errorCount: 0,
+    };
+}
+export function recomputeWorkflowSnapshot(snapshot) {
+    const runningCount = snapshot.agents.filter((agent) => agent.status === "running").length;
+    const doneCount = snapshot.agents.filter((agent) => agent.status === "done").length;
+    const errorCount = snapshot.agents.filter((agent) => agent.status === "error").length;
+    return { ...snapshot, agentCount: snapshot.agents.length, runningCount, doneCount, errorCount };
+}
+export function createWidgetWorkflowDisplay(ctx, options = {}) {
+    const key = options.key ?? "workflow";
+    const placement = options.placement ?? "belowEditor";
+    const showStatus = options.showStatus ?? false;
+    const render = (snapshot, completed = false) => {
+        if (!ctx.hasUI)
+            return;
+        if (showStatus)
+            ctx.ui.setStatus(key, statusLine(snapshot, completed));
+        ctx.ui.setWidget(key, renderWorkflowLines(snapshot, options), { placement });
+    };
+    return {
+        update(snapshot) {
+            render(snapshot, false);
+        },
+        complete(snapshot) {
+            render(snapshot, true);
+        },
+        clear() {
+            if (!ctx.hasUI)
+                return;
+            if (showStatus)
+                ctx.ui.setStatus(key, undefined);
+            ctx.ui.setWidget(key, undefined);
+        },
+    };
+}
+export function createToolUpdateWorkflowDisplay(onUpdate, ctx, options = {}) {
+    const widget = ctx ? createWidgetWorkflowDisplay(ctx, options) : undefined;
+    const streamToolUpdates = options.streamToolUpdates ?? !ctx?.hasUI;
+    const emit = (snapshot, completed = false) => {
+        if (streamToolUpdates) {
+            onUpdate?.({
+                content: [{ type: "text", text: renderWorkflowText(snapshot, completed, options) }],
+                details: snapshot,
+            });
+        }
+        if (completed)
+            widget?.complete(snapshot);
+        else
+            widget?.update(snapshot);
+    };
+    return {
+        update(snapshot) {
+            emit(snapshot, false);
+        },
+        complete(snapshot) {
+            emit(snapshot, true);
+        },
+        clear() {
+            widget?.clear();
+        },
+    };
+}
+export function renderWorkflowLines(snapshot, options = {}) {
+    const maxAgents = options.maxAgents ?? 8;
+    const maxLogs = options.maxLogs ?? 2;
+    const showResultPreviews = options.showResultPreviews ?? false;
+    const state = snapshot.errorCount > 0
+        ? `, ${snapshot.errorCount} errors`
+        : snapshot.runningCount > 0
+            ? `, ${snapshot.runningCount} running`
+            : "";
+    const lines = [`◆ Workflow: ${snapshot.name} (${snapshot.doneCount}/${snapshot.agentCount} done${state})`];
+    const agentPhaseNames = snapshot.agents
+        .map((agent) => agent.phase)
+        .filter((phase) => Boolean(phase));
+    const phaseNames = unique([
+        ...snapshot.phases,
+        ...(snapshot.currentPhase ? [snapshot.currentPhase] : []),
+        ...agentPhaseNames,
+    ]);
+    const rendered = new Set();
+    for (const phase of phaseNames) {
+        const agents = snapshot.agents.filter((agent) => agent.phase === phase);
+        if (agents.length === 0 && snapshot.currentPhase !== phase)
+            continue;
+        for (const agent of agents)
+            rendered.add(agent);
+        const done = agents.filter((agent) => agent.status === "done").length;
+        const running = agents.filter((agent) => agent.status === "running").length;
+        const errors = agents.filter((agent) => agent.status === "error").length;
+        const skipped = agents.filter((agent) => agent.status === "skipped").length;
+        const complete = agents.length > 0 && done + errors + skipped === agents.length;
+        const marker = running > 0 || (!complete && snapshot.currentPhase === phase) ? "▶" : complete ? "✓" : " ";
+        lines.push(`  ${marker} ${phase} ${done}/${agents.length}${running ? ` · ${running} running` : ""}${errors ? ` · ${errors} errors` : ""}${skipped ? ` · ${skipped} skipped` : ""}`);
+        const visibleAgents = agents.slice(-maxAgents);
+        for (const agent of visibleAgents) {
+            const order = `#${agent.id}`;
+            const result = showResultPreviews && agent.resultPreview ? ` — ${agent.resultPreview}` : "";
+            lines.push(`    ${order} ${statusIcon(agent.status)} ${shorten(agent.label, 48)}${result}`);
+        }
+        if (agents.length > visibleAgents.length)
+            lines.push(`    … ${agents.length - visibleAgents.length} earlier agents`);
+    }
+    const unphased = snapshot.agents.filter((agent) => !rendered.has(agent));
+    if (unphased.length) {
+        lines.push("  Unphased");
+        for (const agent of unphased.slice(-maxAgents)) {
+            const result = showResultPreviews && agent.resultPreview ? ` — ${agent.resultPreview}` : "";
+            lines.push(`    #${agent.id} ${statusIcon(agent.status)} ${shorten(agent.label, 48)}${result}`);
+        }
+    }
+    const visibleLogs = snapshot.logs.slice(-maxLogs);
+    if (visibleLogs.length) {
+        if (lines.length > 1)
+            lines.push("");
+        for (const log of visibleLogs)
+            lines.push(`  log: ${log}`);
+    }
+    return lines;
+}
+export function renderWorkflowText(snapshot, completed = false, options = {}) {
+    const header = completed ? "Workflow completed" : "Workflow running";
+    return [header, ...renderWorkflowLines(snapshot, options)].join("\n");
+}
+function statusLine(snapshot, completed) {
+    if (completed)
+        return `workflow ✓ ${snapshot.name}: ${snapshot.doneCount}/${snapshot.agentCount}`;
+    if (snapshot.runningCount > 0)
+        return `workflow ${snapshot.name}: ${snapshot.runningCount} running, ${snapshot.doneCount}/${snapshot.agentCount} done`;
+    return `workflow ${snapshot.name}: ${snapshot.doneCount}/${snapshot.agentCount} done`;
+}
+function statusIcon(status) {
+    switch (status) {
+        case "queued":
+            return "○";
+        case "running":
+            return "●";
+        case "done":
+            return "✓";
+        case "error":
+            return "✗";
+        case "skipped":
+            return "-";
+    }
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function shorten(value, max) {
+    const text = value.replace(/\s+/g, " ").trim();
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+export function preview(value, max = 80) {
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    if (!text)
+        return "";
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export type { AgentRunOptions, AgentRunResult, WorkflowAgentOptions } from "./agent.js";
+export { WorkflowAgent } from "./agent.js";
+export type { WorkflowAgentSnapshot, WorkflowAgentStatus, WorkflowDisplay, WorkflowDisplayOptions, WorkflowSnapshot, } from "./display.js";
+export { createToolUpdateWorkflowDisplay, createWidgetWorkflowDisplay, createWorkflowSnapshot, preview, recomputeWorkflowSnapshot, renderWorkflowLines, renderWorkflowText, } from "./display.js";
+export type { StructuredOutputCapture, StructuredOutputToolOptions } from "./structured-output.js";
+export { createStructuredOutputTool } from "./structured-output.js";
+export type { AgentOptions, WorkflowMeta, WorkflowMetaPhase, WorkflowRunOptions, WorkflowRunResult, } from "./workflow.js";
+export { parseWorkflowScript, runWorkflow } from "./workflow.js";
+export type { WorkflowToolInput, WorkflowToolOptions } from "./workflow-tool.js";
+export { createWorkflowTool } from "./workflow-tool.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { WorkflowAgent } from "./agent.js";
+export { createToolUpdateWorkflowDisplay, createWidgetWorkflowDisplay, createWorkflowSnapshot, preview, recomputeWorkflowSnapshot, renderWorkflowLines, renderWorkflowText, } from "./display.js";
+export { createStructuredOutputTool } from "./structured-output.js";
+export { parseWorkflowScript, runWorkflow } from "./workflow.js";
+export { createWorkflowTool } from "./workflow-tool.js";

package/dist/structured-output.d.ts

@@ -0,0 +1,19 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { Static, TSchema } from "typebox";
+export interface StructuredOutputCapture<T = unknown> {
+    value: T | undefined;
+    called: boolean;
+}
+export interface StructuredOutputToolOptions<TSchemaDef extends TSchema> {
+    schema: TSchemaDef;
+    capture: StructuredOutputCapture<Static<TSchemaDef>>;
+    name?: string;
+}
+/**
+ * Create a terminating tool that captures validated params as the subagent result.
+ *
+ * Pi validates `params` against `schema` before execute() is called. Returning
+ * `terminate: true` lets the subagent finish on this tool call without paying for
+ * an extra assistant follow-up turn.
+ */
+export declare function createStructuredOutputTool<TSchemaDef extends TSchema>({ schema, capture, name, }: StructuredOutputToolOptions<TSchemaDef>): ToolDefinition<TSchemaDef, Static<TSchemaDef>>;

package/dist/structured-output.js

@@ -0,0 +1,30 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+/**
+ * Create a terminating tool that captures validated params as the subagent result.
+ *
+ * Pi validates `params` against `schema` before execute() is called. Returning
+ * `terminate: true` lets the subagent finish on this tool call without paying for
+ * an extra assistant follow-up turn.
+ */
+export function createStructuredOutputTool({ schema, capture, name = "structured_output", }) {
+    return defineTool({
+        name,
+        label: "Structured Output",
+        description: "Return the final machine-readable result for this subagent task.",
+        promptSnippet: "Return final machine-readable output",
+        promptGuidelines: [
+            `${name} is the final answer channel for this task; call ${name} exactly once when done.`,
+            `Do not write a prose final answer after calling ${name}.`,
+        ],
+        parameters: schema,
+        async execute(_toolCallId, params) {
+            capture.value = params;
+            capture.called = true;
+            return {
+                content: [{ type: "text", text: "Structured output received." }],
+                details: params,
+                terminate: true,
+            };
+        },
+    });
+}

package/dist/workflow-tool.d.ts

@@ -0,0 +1,16 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+declare const workflowToolSchema: Type.TObject<{
+    script: Type.TString;
+    args: Type.TOptional<Type.TAny>;
+}>;
+export type WorkflowToolInput = {
+    script: string;
+    args?: unknown;
+};
+export interface WorkflowToolOptions {
+    cwd?: string;
+    concurrency?: number;
+}
+export declare function createWorkflowTool(options?: WorkflowToolOptions): ToolDefinition<typeof workflowToolSchema, any>;
+export {};