@nicknisi/pi-workflows 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Nisi
+
+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,86 @@
+# @nicknisi/pi-workflows
+
+The model-facing front door to the first-party workflow engine. One `workflow` tool runs JavaScript workflow scripts that orchestrate subagents over the in-process runtime, replacing the third-party `@quintinshaw/pi-dynamic-workflows` extension. A `/wf` command is the thin human-facing wrapper.
+
+## The platform story
+
+Four pieces compose the workflow platform: `@nicknisi/pi-shared`'s **subagent runtime** (hermetic in-process child sessions), `@nicknisi/pi-codemode`'s **VM** approach (compile a model-written script in `node:vm` with injected bindings), `@nicknisi/pi-shared`'s **`workflow.ts` engine** (declarative multi-stage DAGs with needs/foreach/gates/retries), and **this tool** as the model-facing front door that ties them together with the script contract the old third-party engine used. The third-party `@quintinshaw/pi-dynamic-workflows` engine is being evicted — its script contract lives on unchanged here, its built-in pattern library / model tiers / agent-type registry / trigger-word arming do not.
+
+## What it adds
+
+- **`workflow` tool** (model-facing) — actions: `run` (inline JS `script` OR `name` of a saved workflow file), `list`, `status <runId>`, `stop <runId>`.
+- **`/wf` command** (human-facing) — `/wf list | /wf run <name> [argsJson] | /wf status <runId> | /wf stop <runId>`.
+
+## The script contract
+
+A workflow script is a JavaScript **statement body** (no imports) with a leading `export const meta = { name, description }` declaration and a trailing `return value`. The body is wrapped in an async function so a top-level `return` compiles; `export const meta =` is rewritten so `node:vm` compiles it (a stranded `export` fails loudly) and `meta.name`/`meta.description` surface in the result.
+
+Injected globals — the exact names the old third-party tool's scripts use, so existing scripts run unchanged:
+
+```js
+export const meta = { name: 'research', description: 'parallel research fan-out' };
+
+const questions = ['How does the auth refresh flow work?', 'Where are sessions persisted?'];
+const results = await parallel(questions.map((q) => () => agent(q, { label: 'researcher' })));
+return { answered: results.length, results };
+```
+
+| Global                       | Behavior                                                                                                                                                                                                                                                                                                                             |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `agent(prompt, opts)`        | Spawns a hermetic in-process child via the subagent runtime (namespace `workflows`). Throws `${kind}: ${error}` on failure — wrap with a `safeAgent` that returns `{ ok, value, error }` so a failure inside `parallel()` reports which stage died instead of collapsing the wave to `null`. Returns `res.data ?? res.text ?? null`. |
+| `parallel(thunks)`           | `Promise.all` over zero-arg thunks — pass `() => agent(...)`, not `agent(...)`.                                                                                                                                                                                                                                                      |
+| `pipeline(items, ...stages)` | Folds items through stages: each stage maps over the previous stage's outputs in parallel, producing the next array.                                                                                                                                                                                                                 |
+| `phase(name)`                | Logging marker only — NOT a budget boundary. Appends `── name` to the result logs.                                                                                                                                                                                                                                                   |
+| `log(...args)`               | Captured into the result logs.                                                                                                                                                                                                                                                                                                       |
+| `args`                       | The `args` JSON value passed to `run`.                                                                                                                                                                                                                                                                                               |
+| `budget`                     | `{ total, spent, remaining }` over the run's token usage. `total` defaults to `Infinity`; `spent` accumulates across `agent()` calls. Read-only.                                                                                                                                                                                     |
+| `cwd`                        | The session working directory.                                                                                                                                                                                                                                                                                                       |
+
+`agent()` opts: `model` (`'provider/id'`), `tools` (allowlist — default read-only `['read','grep','find','ls']`; pass `['read','bash','edit','write']` for builders), `label` (child agent label), `systemPrompt`, `schema` (validated; parsed JSON lands in `result.data`), `effort` (thinking level), `timeoutMs`, `maxTurns`, `worktree` (run the child in an isolated git worktree; on settle the change set is captured to a `.patch` and `agent()` returns `{ value, patchPath, runId }` instead of the bare value — opt-in, so non-worktree calls are unchanged), `agentType` (accepted but ignored — no agent-type registry; resolve `systemPrompt` in the script itself).
+
+The script executes **in the host process with full Node access** — `process`, `require`, and `fs` are all reachable, the same trust boundary as the `bash` tool. Keep the returned value small: summaries, counts, key findings — never raw file dumps.
+
+## Saved workflows
+
+Plain files. The registry is `ls` — no database, no manifest, no config keys.
+
+- `~/.pi/agent/workflows/*.js` — global.
+- `.pi/workflows/*.js` — project-local, **trusted projects only** (the same trust gate as codemode's `/cx`). Untrusted projects see only global workflows.
+
+Names are bare file stems (`research`, not `research.js`, never a path — `..` and `/` are rejected to prevent escaping the workflows dirs). Global shadows a same-named project workflow. Files are read on demand, so `/reload` needs no workflow-specific wiring.
+
+## Runs are visible
+
+Every `agent()` call spawns through `@nicknisi/pi-shared`'s subagent runtime with `artifactsDir` set to `~/.pi/agent/subagent-runs/` and namespace `workflows`, so child spawns appear in the `fleet` tool / `/fleet` command from `@nicknisi/pi-subagents`. `status <runId>` and `stop <runId>` here read from / cancel via the same runtime's run records — no parallel store. `stop` cancels in-flight spawns through a live `runId → AbortController` registry (mirroring subagents' cascading-cancellation); a run belonging to a different host process is reported as not cancellable from here.
+
+## Migration from `@quintinshaw/pi-dynamic-workflows`
+
+| Old concept                                          | New home                                                                                                                                                                                                       |
+| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Built-in named patterns (e.g. `research`, `review`)  | Example `.js` files you drop in `~/.pi/agent/workflows/`. No built-in library — the registry is `ls`.                                                                                                          |
+| Model tiers (`fast` / `balanced` / `deep`)           | Explicit `model:` strings passed to `agent(prompt, { model: 'anthropic/claude-haiku-4-5' })`. No tier registry.                                                                                                |
+| `agentType` → tool/systemPrompt resolution           | Resolve `systemPrompt` in the script itself: `agent(prompt, { systemPrompt: 'You are a reviewer…', tools: ['read','grep','bash'] })`. `agentType` is accepted but ignored (logged).                            |
+| Trigger-word arming (the tool activates on keywords) | The model calls the `workflow` tool when intent warrants — no arming, no keyword matching.                                                                                                                     |
+| Phases with per-phase budgets                        | `phase(name)` is a logging marker only. Budget is a single run-level `{ total, spent, remaining }`; per-stage budgets are the `workflow.ts` engine's `tokenBudget` (use `runWorkflow` from codemode for that). |
+| The third-party engine's script globals              | Unchanged: `args`, `agent`, `parallel`, `pipeline`, `phase`, `log`, `budget`, `cwd`. Existing scripts run as-is.                                                                                               |
+
+## Recipes
+
+The `examples/` directory ships standalone, copy-and-adapt workflow scripts — the registry is `ls`, so these are code you read and copy, never APIs you import (no index re-exports them). Drop any of them into `~/.pi/agent/workflows/` and run via `/wf run <name>`.
+
+- **`lanes.js`** — N parallel agents editing FILE-DISJOINT lanes of one repo under a hard-rules preamble (each lane owns a fixed file set; no git, no installs; the parent integrates centrally). Use it when a task splits into independent edits that don't overlap on files. Adapt by setting `VERIFY` to your typecheck command and filling the `LANES` array with `{ name, files, brief }` per lane.
+- **`gates.js`** — three judge/verify prompt builders returning prompt strings: adversarial refutation (defeats confirmation bias), deep-research coverage (defeats silent source omission), and a 3-way code-review verdict (defeats verdict collapse). Use it when you need a reliable gate inside your own workflow. Adapt by copying the builder whose failure mode you need and calling it from an `agent()` with a JSON schema. Prompt patterns distilled from `@quintinshaw/pi-dynamic-workflows`.
+- **`bake-off.js`** — race N models on the SAME task in isolated worktrees (`worktree: true`), then an advisory judge reads each contender's `.patch` and picks a winner. Use it on hard build tasks where a single GLM-5.2-class builder produces decent-but-flawed code; the 2x token cost buys a measurably better hit rate. Adapt by setting `CONTENDERS` to the models to race and passing `task` in `args`; the workflow returns the winner's `patchPath` to apply via `/patches`.
+
+## Dependencies
+
+- `@nicknisi/pi-shared` (`workspace:*`) — the subagent runtime and `runWorkflow` engine.
+- `typebox` — the tool's parameter schema.
+- `@earendil-works/pi-coding-agent` (peer) — the extension API, `getAgentDir`, `CONFIG_DIR_NAME`.
+
+## Caveats
+
+- The script runs in the host process with full Node access — the same trust boundary as the `bash` and `codemode` tools. Your model, your session.
+- Project-local workflows (`.pi/workflows/`) load only in trusted projects; untrusted projects are limited to global workflows so a cloned repo cannot silently inject orchestration scripts.
+- `agent()` cannot spawn children of its own (the ecosystem recursion guard refuses nested orchestration). For dependent multi-stage work where stages spawn, use `@nicknisi/pi-codemode`'s `runWorkflow` instead.
+- `stop` cancels only runs spawned by this host process; persisted runs from other hosts show in `status` but are not cancellable here.

package/dist/engine.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The workflow script engine — pi-free and testable.
+ *
+ * A workflow script is a JavaScript statement body with injected globals
+ * (args, agent, parallel, pipeline, phase, log, budget, cwd) and a leading
+ * `export const meta = { name, description }` declaration. It returns a value
+ * by evaluating a trailing expression or a top-level `return` (the body is
+ * wrapped in an async function so a bare `return` compiles).
+ *
+ * This module deliberately imports nothing from pi or @nicknisi/pi-shared so
+ * the test suite can exercise it without an install step: the spawn function
+ * is injected. index.ts wires it to the shared subagent runtime.
+ *
+ * The compile model mirrors ~/Developer/ideation/workflows/engine-host.mjs:
+ * `export const meta =` is rewritten to an outer-binding assignment so the vm
+ * compiles (a stranded `export` fails loudly) and the tool can surface
+ * meta.name/description.
+ */
+export interface EngineSpawnUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cost?: number | undefined;
+}
+export interface EngineSpawnOk {
+    ok: true;
+    text: string;
+    data?: unknown;
+    usage: EngineSpawnUsage;
+    /** Run id of the child spawn, when the spawn fn attaches it. */
+    runId?: string;
+    /** Path to the worktree `.patch` file, for `worktree: true` runs that changed files. */
+    patchPath?: string;
+}
+export interface EngineSpawnFail {
+    ok: false;
+    kind: string;
+    error: string;
+    text: string;
+    usage: EngineSpawnUsage;
+}
+export type EngineSpawnResult = EngineSpawnOk | EngineSpawnFail;
+export interface EngineSpawnOptions {
+    prompt: string;
+    agent?: string;
+    model?: string;
+    tools?: string[];
+    systemPrompt?: string;
+    thinkingLevel?: string;
+    timeoutMs?: number;
+    maxTurns?: number;
+    outputSchema?: unknown;
+    /** Run the child in an isolated git worktree; its change set is captured to a `.patch`. */
+    worktree?: boolean;
+}
+export type EngineSpawnFn = (opts: EngineSpawnOptions) => Promise<EngineSpawnResult>;
+export interface EngineBudget {
+    total: number;
+    spent: number;
+    remaining: number;
+}
+export interface ScriptMeta {
+    name?: string;
+    description?: string;
+    [k: string]: unknown;
+}
+export interface RunScriptOptions {
+    script: string;
+    args?: unknown;
+    spawn: EngineSpawnFn;
+    cwd: string;
+    budgetTotal?: number;
+    onLog?: (line: string) => void;
+}
+export interface RunScriptResult {
+    value: unknown;
+    meta: ScriptMeta | undefined;
+    logs: string[];
+    usage: EngineSpawnUsage;
+    durationMs: number;
+}
+export declare function runScript(opts: RunScriptOptions): Promise<RunScriptResult>;
+/** The compiled async body; invoking it runs the script with injected globals. */
+export type CompiledFn = (args: unknown, agent: unknown, parallel: unknown, pipeline: unknown, phase: unknown, log: unknown, budget: unknown, cwd: string) => Promise<unknown>;
+export interface CompiledScript {
+    /** The script's `meta` export, read via a stub dry-run (no real spawn). */
+    meta: ScriptMeta | undefined;
+    /** Invoke to run the script; spawn-backed globals must be supplied. */
+    fn: CompiledFn;
+}
+/**
+ * Compile a workflow script and read its `meta` export WITHOUT a real spawn.
+ *
+ * `export const meta =` is rewritten to an outer-binding assignment so the vm
+ * compiles (a stranded `export` fails loudly) and `meta` is captured into a
+ * holder. The body is wrapped in an async function so a top-level `return`
+ * compiles. `meta` is populated by a stub dry-run — `agent` returns `null`,
+ * `parallel`/`pipeline` are `Promise.all`-style folds over those stubs — so the
+ * script's `meta` declaration (which well-formed scripts place first) is read
+ * without spawning any child sessions. A syntax error throws here.
+ */
+export declare function compileScript(script: string): CompiledScript;

package/dist/engine.js

@@ -0,0 +1,167 @@
+/**
+ * The workflow script engine — pi-free and testable.
+ *
+ * A workflow script is a JavaScript statement body with injected globals
+ * (args, agent, parallel, pipeline, phase, log, budget, cwd) and a leading
+ * `export const meta = { name, description }` declaration. It returns a value
+ * by evaluating a trailing expression or a top-level `return` (the body is
+ * wrapped in an async function so a bare `return` compiles).
+ *
+ * This module deliberately imports nothing from pi or @nicknisi/pi-shared so
+ * the test suite can exercise it without an install step: the spawn function
+ * is injected. index.ts wires it to the shared subagent runtime.
+ *
+ * The compile model mirrors ~/Developer/ideation/workflows/engine-host.mjs:
+ * `export const meta =` is rewritten to an outer-binding assignment so the vm
+ * compiles (a stranded `export` fails loudly) and the tool can surface
+ * meta.name/description.
+ */
+import vm from 'node:vm';
+// ── Internals ──────────────────────────────────────────────────────────────
+const STRIP_META = /export\s+const\s+meta\s*=/;
+const DEFAULT_TOOLS = ['read', 'grep', 'find', 'ls'];
+const MAX_LOG_ENTRIES = 200;
+const MAX_LOG_CHARS = 2000;
+function truncate(line, max) {
+    return line.length <= max ? line : `${line.slice(0, max)}…[truncated at ${max} chars]`;
+}
+function safeStringify(v) {
+    if (typeof v === 'string')
+        return v;
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+function zeroUsage() {
+    return { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+}
+function addUsage(a, b) {
+    a.inputTokens += b.inputTokens;
+    a.outputTokens += b.outputTokens;
+    a.totalTokens += b.totalTokens;
+    if (b.cost !== undefined)
+        a.cost = (a.cost ?? 0) + b.cost;
+}
+// ── Engine ─────────────────────────────────────────────────────────────────
+export async function runScript(opts) {
+    const { script, spawn, cwd } = opts;
+    const args = opts.args;
+    const budgetTotal = opts.budgetTotal ?? Infinity;
+    const logs = [];
+    const usage = zeroUsage();
+    const startedAt = Date.now();
+    const log = (...parts) => {
+        if (logs.length >= MAX_LOG_ENTRIES)
+            return;
+        const line = parts.map(safeStringify).join(' ');
+        const t = truncate(line, MAX_LOG_CHARS);
+        logs.push(t);
+        opts.onLog?.(t);
+    };
+    const phase = (name) => {
+        const line = `── ${name}`;
+        logs.push(line);
+        opts.onLog?.(line);
+    };
+    const budget = {
+        get total() {
+            return budgetTotal;
+        },
+        get spent() {
+            return usage.totalTokens;
+        },
+        get remaining() {
+            return budgetTotal - usage.totalTokens;
+        },
+    };
+    // agent(prompt, opts) backed by the injected spawn. A failure kind becomes
+    // a throw so a script's safeAgent wrapper converts it into a typed stage
+    // failure (matching ~/Developer/ideation/workflows/engine-host.mjs).
+    const agent = async (prompt, agentOpts = {}) => {
+        if (typeof agentOpts.agentType === 'string') {
+            log(`(agentType '${agentOpts.agentType}' accepted but ignored — no agent-type registry)`);
+        }
+        const spawnOpts = {
+            prompt,
+            ...(typeof agentOpts.label === 'string' ? { agent: agentOpts.label } : {}),
+            ...(typeof agentOpts.model === 'string' ? { model: agentOpts.model } : {}),
+            ...(Array.isArray(agentOpts.tools) ? { tools: agentOpts.tools } : { tools: DEFAULT_TOOLS }),
+            ...(typeof agentOpts.systemPrompt === 'string' ? { systemPrompt: agentOpts.systemPrompt } : {}),
+            ...(typeof agentOpts.effort === 'string' ? { thinkingLevel: agentOpts.effort } : {}),
+            ...(typeof agentOpts.timeoutMs === 'number' ? { timeoutMs: agentOpts.timeoutMs } : {}),
+            ...(typeof agentOpts.maxTurns === 'number' ? { maxTurns: agentOpts.maxTurns } : {}),
+            ...(agentOpts.schema !== undefined ? { outputSchema: agentOpts.schema } : {}),
+            ...(agentOpts.worktree === true ? { worktree: true } : {}),
+        };
+        const res = await spawn(spawnOpts);
+        addUsage(usage, res.usage);
+        if (!res.ok)
+            throw new Error(`${res.kind}: ${res.error}`);
+        // A worktree run that changed files produces a `.patch`; surface it
+        // alongside the value so the script can hand the path to a judge or
+        // return it for the `/patches` apply flow. Opt-in: only when patchPath is
+        // present, so non-worktree scripts see the unchanged `data ?? text` return.
+        if (res.patchPath)
+            return { value: res.data ?? res.text ?? null, patchPath: res.patchPath, runId: res.runId };
+        return res.data ?? res.text ?? null;
+    };
+    const parallel = (thunks) => Promise.all(thunks.map((t) => t()));
+    // pipeline(items, ...stages): each stage maps over the previous stage's
+    // outputs in parallel, producing the next array. A fold over Promise.all.
+    const pipeline = async (items, ...stages) => {
+        let values = [...items];
+        for (const stage of stages) {
+            values = await parallel(values.map((v, i) => () => stage(v, i)));
+        }
+        return values;
+    };
+    // Compile + run. compileScript is extracted so callers (tests, future
+    // tooling) can compile + read `meta` without a real spawn.
+    const compiled = compileScript(script);
+    const value = await compiled.fn(args, agent, parallel, pipeline, phase, log, budget, cwd);
+    return { value, meta: compiled.meta, logs, usage, durationMs: Date.now() - startedAt };
+}
+/**
+ * Compile a workflow script and read its `meta` export WITHOUT a real spawn.
+ *
+ * `export const meta =` is rewritten to an outer-binding assignment so the vm
+ * compiles (a stranded `export` fails loudly) and `meta` is captured into a
+ * holder. The body is wrapped in an async function so a top-level `return`
+ * compiles. `meta` is populated by a stub dry-run — `agent` returns `null`,
+ * `parallel`/`pipeline` are `Promise.all`-style folds over those stubs — so the
+ * script's `meta` declaration (which well-formed scripts place first) is read
+ * without spawning any child sessions. A syntax error throws here.
+ */
+export function compileScript(script) {
+    const metaHolder = { value: undefined };
+    const stripped = script.replace(STRIP_META, 'const meta = metaHolder.value =');
+    const wrapped = `(async function(args, agent, parallel, pipeline, phase, log, budget, cwd, metaHolder){\n${stripped}\n})`;
+    const raw = new vm.Script(wrapped, { filename: 'workflow.js' }).runInThisContext();
+    // Bind metaHolder so callers invoke an 8-arg fn; the holder rides the call
+    // (runInThisContext cannot see a closure variable, so it must be a parameter).
+    const fn = (args, agent, parallel, pipeline, phase, log, budget, cwd) => raw(args, agent, parallel, pipeline, phase, log, budget, cwd, metaHolder);
+    // Stub dry-run to read `meta`. Well-formed scripts declare `meta` first, so
+    // it is assigned synchronously before the first `await`; we await the whole
+    // stubbed body anyway so a script that computes meta from `args` works too.
+    // Any throw is swallowed — we only care that it compiled + set meta.
+    const stubAgent = async () => null;
+    const stubParallel = (thunks) => Promise.all(thunks.map((t) => t()));
+    const stubPipeline = async (items, ...stages) => {
+        let values = [...items];
+        for (const stage of stages)
+            values = await stubParallel(values.map((v) => () => stage(v)));
+        return values;
+    };
+    const stubBudget = { total: Infinity, spent: 0, remaining: Infinity };
+    void fn(undefined, stubAgent, stubParallel, stubPipeline, () => { }, () => { }, stubBudget, '/tmp').catch(() => { });
+    // `meta` is a getter so a caller that re-runs `fn` with real globals sees
+    // the post-run meta (the stub dry-run may have thrown on args-derived meta;
+    // the real run sets it). For static meta the stub already populated it.
+    return Object.defineProperty({ fn }, 'meta', {
+        get: () => metaHolder.value,
+        enumerable: true,
+    });
+}

package/dist/examples.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Smoke test for the example workflow files: each example file COMPILES under
+ * the package's script compiler (`compileScript` — a stub dry-run, no real
+ * spawn) and its `meta` export has a non-empty `name` + `description`.
+ *
+ * No real spawns: compileScript reads `meta` via a stub dry-run where
+ * `agent`/`parallel`/`pipeline` are no-ops (see engine.ts).
+ */
+export {};

package/dist/examples.test.js

@@ -0,0 +1,35 @@
+/**
+ * Smoke test for the example workflow files: each example file COMPILES under
+ * the package's script compiler (`compileScript` — a stub dry-run, no real
+ * spawn) and its `meta` export has a non-empty `name` + `description`.
+ *
+ * No real spawns: compileScript reads `meta` via a stub dry-run where
+ * `agent`/`parallel`/`pipeline` are no-ops (see engine.ts).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { compileScript } from './engine.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const examplesDir = path.join(here, 'examples');
+const examples = fs
+    .readdirSync(examplesDir)
+    .filter((f) => f.endsWith('.js'))
+    .map((f) => path.join(examplesDir, f));
+describe('examples smoke: compile + meta', () => {
+    it('discovers exactly the three example files', () => {
+        expect(examples.map((e) => path.basename(e)).sort()).toEqual(['bake-off.js', 'gates.js', 'lanes.js']);
+    });
+    for (const file of examples) {
+        const name = path.basename(file);
+        it(`${name} compiles and exports meta.name + meta.description`, () => {
+            const src = fs.readFileSync(file, 'utf8');
+            const compiled = compileScript(src);
+            expect(typeof compiled.meta?.name).toBe('string');
+            expect((compiled.meta?.name ?? '').length).toBeGreaterThan(0);
+            expect(typeof compiled.meta?.description).toBe('string');
+            expect((compiled.meta?.description ?? '').length).toBeGreaterThan(0);
+        });
+    }
+});

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @nicknisi/pi-workflows — the model-facing front door to the first-party
+ * workflow engine.
+ *
+ * One `workflow` tool with actions: run (inline JS script OR a saved workflow
+ * file name), list, status (runId), stop (runId). `run` compiles the script in
+ * a node:vm context exactly like codemode compiles its snippets — `export const
+ * meta =` is rewritten so the vm compiles, the body is wrapped in an async
+ * function so a top-level `return` works, and meta.name/description surface in
+ * the result. Injected globals: agent, parallel, pipeline, phase, log, args,
+ * budget, cwd — the contract the old third-party tool's scripts were written
+ * against, so existing scripts run unchanged.
+ *
+ * Saved workflows are plain files: ~/.pi/agent/workflows/*.js (global) and
+ * .pi/workflows/*.js (project, trusted-only). The registry is `ls` — no
+ * database, no manifest.
+ *
+ * Runs are visible: agent() spawns through @nicknisi/pi-shared's subagent
+ * runtime (namespace 'workflows'), so child spawns appear in the fleet radar
+ * from @nicknisi/pi-subagents. status/stop read from / cancel via the same
+ * runtime's run records — no parallel store.
+ *
+ * The platform story: subagents runtime + codemode VM + shared/workflow.ts
+ * engine + this tool = the workflow platform; the third-party
+ * @quintinshaw/pi-dynamic-workflows engine is being evicted.
+ */
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+export declare function findWorkflowFile(name: string, cwd: string, trusted: boolean): string | undefined;
+export interface SavedWorkflow {
+    name: string;
+    scope: 'global' | 'project';
+    description?: string;
+}
+export declare function listWorkflows(cwd: string, trusted: boolean): SavedWorkflow[];
+export default function workflows(pi: ExtensionAPI): void;
+export type { ExtensionContext };