@pify/workflow 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pifydev
+
+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,37 @@
+# @pify/workflow
+
+Deterministic multi-step agent orchestration for [pi](https://github.com/earendil-works/pi) — a Claude Code-style `workflow` tool: the model writes a small JavaScript script that fans work out across child agents, cross-checks, and returns one synthesized answer. Intermediate work stays in script variables, not your chat context.
+
+Part of the [Pify suite](https://github.com/pifydev). Install with [`pify install workflow`](https://github.com/pifydev/cli) or `pi install npm:@pify/workflow`.
+
+## Example
+
+```js
+export const meta = { name: "review", phases: [{ title: "Find" }, { title: "Verify" }] };
+phase("Find");
+const findings = await parallel([
+  () => agent("Review src/auth for security issues. Report file:line + why.", { agent: "reviewer", label: "auth" }),
+  () => agent("Review src/api for correctness. Report file:line + why.", { agent: "reviewer", label: "api" }),
+]);
+phase("Verify");
+const verified = await pipeline(findings.filter(Boolean),
+  (finding) => agent(`Adversarially verify this finding — is it real?\n${finding}`, { agent: "scout" }));
+return { findings: verified.filter(Boolean) };
+```
+
+## The contract
+
+- **Globals**: `agent(prompt, {agent?, label?, phase?})` → child's report or `null`; `parallel(thunks)` (barrier, failures → null); `pipeline(items, ...stages)` (no barrier between stages); `phase(title)`; `log(msg)`; `args`. The script's return value is the tool result.
+- **Determinism enforced** in a poisoned `node:vm` context: `Date.now()`, `Math.random()`, argless `new Date()`, `eval`, and `Function` throw — control flow stays reproducible. (Cooperative discipline, not a security boundary: scripts run at the same trust level as the bash tool.)
+- **One agent catalog**: `agent()` uses the same `reviewer`/`scout`/`worker` builtins and `.pi/agents/*.md` custom types as [`@pify/subagent`](https://github.com/pifydev/subagent) and [`@pify/swarm`](https://github.com/pifydev/swarm).
+- **Limits**: 20 agents per run, 4 concurrent (shared semaphore), 10-minute script timeout.
+- **Saved workflows**: `.pi/workflows/<name>.js` runs by name. `export const meta = {…}` prefixes are tolerated, so Claude Code-style scripts mostly run unchanged.
+- **Background runs**: `background: true` returns a `runId`; poll with `workflow_status`. A live widget shows the current phase and agents; finished runs survive `/reload`. `/workflows` lists saved scripts and runs.
+
+## The Pify agent stack
+
+`agent_run` (one child) → `swarm_run` (independent parallel items) → `workflow` (scripted control flow). Use the smallest tool that fits.
+
+## License
+
+MIT © [Pify maintainers](https://github.com/pifydev)

package/extensions/workflow.ts

@@ -0,0 +1,419 @@
+/**
+ * @pify/workflow — deterministic multi-step agent orchestration for pi.
+ *
+ * The top of the Pify agent stack (subagent → swarm → workflow): the model
+ * submits a JavaScript orchestration script to the `workflow` tool — with
+ * agent()/parallel()/pipeline()/phase()/log()/args globals — and the script
+ * fans work out across child agents from the shared .pi/agents catalog,
+ * keeping intermediate results in script variables instead of chat context.
+ * Scripts run in a poisoned vm context (Date.now/Math.random/eval throw)
+ * so control flow stays reproducible. Saved scripts in .pi/workflows/<name>.js
+ * run by name. Background runs are polled with workflow_status.
+ *
+ * Design synthesis: CC-style dynamic workflow tool (michaelliv/
+ * pi-dynamic-workflows), vm determinism discipline (tintinweb's
+ * SubagentWorkflow), saved named workflows (AgwaB), child-runner pattern
+ * proven in @pify/subagent and @pify/swarm.
+ */
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  getAgentDir,
+  SessionManager,
+  type AgentSession,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { readFileSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+
+import { BUILTIN_AGENTS } from "../src/builtin.ts";
+import { parseAgentFile } from "../src/frontmatter.ts";
+import { buildWidgetLines, formatResult, formatStatus } from "../src/report.ts";
+import { runScript, type AgentOptions } from "../src/sandbox.ts";
+import {
+  AGENT_CONCURRENCY,
+  MAX_PERSISTED_RESULT_CHARS,
+  isRecord,
+  type AgentCallState,
+  type AgentDef,
+  type WorkflowRun,
+} from "../src/types.ts";
+
+const RUN_ENTRY = "workflow-run";
+const FALLBACK_AGENT = "scout";
+
+type UiContext = ExtensionContext;
+
+export default function workflow(pi: ExtensionAPI) {
+  let defs = new Map<string, AgentDef>();
+  const runs = new Map<string, WorkflowRun>();
+  let activeRun: WorkflowRun | null = null;
+  let runCounter = 0;
+  let lastUiCtx: UiContext | null = null;
+
+  function loadDefs(cwd: string): void {
+    defs = new Map();
+    for (const [name, content] of Object.entries(BUILTIN_AGENTS)) {
+      const def = parseAgentFile(name, content, "builtin");
+      if (def) defs.set(def.name, def);
+    }
+    for (const [dir, source] of [
+      [join(getAgentDir(), "agents"), "global"],
+      [join(cwd, ".pi", "agents"), "project"],
+    ] as const) {
+      try {
+        for (const file of readdirSync(dir).filter((f) => f.endsWith(".md"))) {
+          try {
+            const def = parseAgentFile(basename(file, ".md"), readFileSync(join(dir, file), "utf8"), source);
+            if (def) defs.set(def.name, def);
+          } catch {
+            // skip
+          }
+        }
+      } catch {
+        // dir missing
+      }
+    }
+  }
+
+  function renderWidget(ctx: UiContext | null = lastUiCtx): void {
+    if (!ctx || !ctx.hasUI) return;
+    lastUiCtx = ctx;
+    const run = activeRun;
+    const now = Date.now();
+    if (!run || (run.status !== "running" && (run.finishedAt ?? 0) < now - 15_000)) {
+      ctx.ui.setWidget("workflow", undefined);
+      return;
+    }
+    ctx.ui.setWidget(
+      "workflow",
+      (_tui: unknown, theme: { fg(c: string, s: string): string; bold(s: string): string }) =>
+        new Text(buildWidgetLines(run, theme, Date.now()).join("\n"), 0, 0),
+      { placement: "aboveEditor" },
+    );
+  }
+
+  function notify(ctx: UiContext, message: string, level: "info" | "warning" | "error"): void {
+    if (ctx.hasUI) ctx.ui.notify(message, level);
+  }
+
+  // ── Child agent runner behind a shared concurrency semaphore ─────────
+
+  let inFlight = 0;
+  const waiters: Array<() => void> = [];
+
+  async function acquire(): Promise<void> {
+    if (inFlight < AGENT_CONCURRENCY) {
+      inFlight++;
+      return;
+    }
+    await new Promise<void>((resolve) => waiters.push(resolve));
+    inFlight++;
+  }
+
+  function release(): void {
+    inFlight--;
+    const next = waiters.shift();
+    if (next) next();
+  }
+
+  async function runChildAgent(
+    ctx: UiContext,
+    run: WorkflowRun,
+    prompt: string,
+    opts: AgentOptions | undefined,
+  ): Promise<string | null> {
+    const def = defs.get((opts?.agent ?? FALLBACK_AGENT).toLowerCase()) ?? defs.get(FALLBACK_AGENT);
+    if (!def) return null;
+
+    const call: AgentCallState = {
+      id: run.agents.length + 1,
+      label: opts?.label ?? `${def.name}-${run.agents.length + 1}`,
+      agent: def.name,
+      phase: opts?.phase ?? (run.phases[run.phases.length - 1] ?? null),
+      status: "running",
+      turns: 0,
+      tokens: 0,
+    };
+    run.agents.push(call);
+    renderWidget();
+
+    await acquire();
+    let session: AgentSession | null = null;
+    let unsubscribe: (() => void) | null = null;
+    try {
+      let model = ctx.model ?? null;
+      if (def.model) {
+        const [provider, ...rest] = def.model.split("/");
+        const found =
+          provider && rest.length > 0 ? ctx.modelRegistry.find(provider, rest.join("/")) : undefined;
+        if (found) model = found;
+      }
+      if (!model) throw new Error("No model available");
+
+      const promptHost = ctx as unknown as {
+        getSystemPromptOptions?: () => { customPrompt?: string; appendSystemPrompt?: string };
+      };
+      const promptOptions = promptHost.getSystemPromptOptions?.() ?? {};
+
+      const created = await createAgentSession({
+        sessionManager: SessionManager.inMemory(ctx.cwd),
+        model,
+        thinkingLevel: (def.thinking ?? pi.getThinkingLevel()) as never,
+        tools: def.tools,
+        resourceLoader: new DefaultResourceLoader({
+          cwd: ctx.cwd,
+          agentDir: getAgentDir(),
+          noExtensions: true,
+          noPromptTemplates: true,
+          noThemes: true,
+          systemPrompt: promptOptions.customPrompt,
+          appendSystemPrompt: [
+            ...(promptOptions.appendSystemPrompt ? [promptOptions.appendSystemPrompt] : []),
+            def.systemPrompt,
+            "You are one step of a scripted workflow. Your final assistant message IS the value returned to the script — return raw data/report, no pleasantries, no questions.",
+          ],
+        }),
+      });
+      session = created.session;
+
+      unsubscribe = session.subscribe((event) => {
+        if (event.type === "message_end" && (event as { message?: { role?: string } }).message?.role === "assistant") {
+          call.turns++;
+          const usage = (event as { message?: { usage?: { totalTokens?: number } } }).message?.usage;
+          if (usage && typeof usage.totalTokens === "number") call.tokens += usage.totalTokens;
+          renderWidget();
+          if (call.turns >= def.maxTurns) void session?.abort().catch(() => {});
+        }
+      });
+
+      await session.prompt(prompt, { source: "extension" } as never);
+
+      const messages = session.messages as Array<{
+        role?: string;
+        stopReason?: unknown;
+        content?: Array<{ type?: string; text?: string }>;
+      }>;
+      const last = [...messages].reverse().find((m) => m.role === "assistant");
+      const text = (last?.content ?? [])
+        .filter((c) => c.type === "text" && typeof c.text === "string")
+        .map((c) => c.text)
+        .join("\n")
+        .trim();
+
+      if (last?.stopReason === "aborted") {
+        call.status = "aborted";
+        return text || null;
+      }
+      if (last?.stopReason === "error" || !text) {
+        call.status = "error";
+        return null;
+      }
+      call.status = "done";
+      return text;
+    } catch {
+      call.status = "error";
+      return null;
+    } finally {
+      release();
+      if (unsubscribe) {
+        try {
+          unsubscribe();
+        } catch {
+          // gone
+        }
+      }
+      if (session) {
+        try {
+          session.dispose();
+        } catch {
+          // fine
+        }
+      }
+      renderWidget();
+    }
+  }
+
+  // ── Execution ────────────────────────────────────────────────────────
+
+  async function execute(ctx: UiContext, run: WorkflowRun, script: string, args: unknown): Promise<void> {
+    try {
+      const value = await runScript(script, args, {
+        agent: (prompt, opts) => runChildAgent(ctx, run, prompt, opts),
+        log: (message) => {
+          run.logs.push(message.slice(0, 500));
+          renderWidget();
+        },
+        phase: (title) => {
+          run.phases.push(title.slice(0, 100));
+          renderWidget();
+        },
+      });
+      run.result =
+        typeof value === "string" ? value : value === undefined ? null : JSON.stringify(value, null, 2);
+      if (run.result && run.result.length > MAX_PERSISTED_RESULT_CHARS) {
+        run.result = `${run.result.slice(0, MAX_PERSISTED_RESULT_CHARS)}\n… (truncated)`;
+      }
+      run.status = "done";
+    } catch (err) {
+      run.status = "error";
+      run.error = err instanceof Error ? err.message : String(err);
+    } finally {
+      run.finishedAt = Date.now();
+      pi.appendEntry(RUN_ENTRY, run);
+      renderWidget();
+    }
+  }
+
+  function savedWorkflows(cwd: string): string[] {
+    try {
+      return readdirSync(join(cwd, ".pi", "workflows"))
+        .filter((f) => f.endsWith(".js") || f.endsWith(".mjs"))
+        .sort();
+    } catch {
+      return [];
+    }
+  }
+
+  // ── Tools ────────────────────────────────────────────────────────────
+
+  pi.registerTool({
+    name: "workflow",
+    label: "Run workflow",
+    description:
+      "Run a deterministic JavaScript orchestration script that fans work out across child agents. " +
+      "Globals: agent(prompt, {agent?, label?, phase?}) -> Promise<string|null> (agent types: " +
+      "reviewer/scout/worker + .pi/agents custom; write prompts as self-contained briefs); " +
+      "parallel(thunks) (barrier, failures resolve null); pipeline(items, ...stages) (no barrier " +
+      "between stages); phase(title); log(msg); args. The script's return value is the tool result. " +
+      "Date.now()/Math.random()/eval throw (determinism). Provide script XOR name " +
+      "(name loads .pi/workflows/<name>.js). background=true returns a runId for workflow_status.",
+    parameters: Type.Object({
+      script: Type.Optional(Type.String({ description: "JavaScript orchestration script body" })),
+      name: Type.Optional(Type.String({ description: "Saved workflow name in .pi/workflows/" })),
+      args: Type.Optional(Type.Unknown({ description: "Value exposed to the script as `args`" })),
+      background: Type.Optional(Type.Boolean()),
+    }),
+    async execute(
+      _id,
+      params: { script?: string; name?: string; args?: unknown; background?: boolean },
+      _signal,
+      _onUpdate,
+      ctx,
+    ) {
+      const uiCtx = ctx as UiContext;
+      if (activeRun?.status === "running") {
+        throw new Error(`Workflow ${activeRun.runId} is still running — wait or poll workflow_status.`);
+      }
+
+      let script = params.script ?? "";
+      if (params.name) {
+        if (script) throw new Error("Provide script OR name, not both.");
+        const safe = params.name.trim().toLowerCase();
+        if (!/^[a-z0-9._-]+$/.test(safe)) throw new Error(`Invalid workflow name "${params.name}".`);
+        const dir = join(uiCtx.cwd, ".pi", "workflows");
+        const file = ["", ".js", ".mjs"].map((ext) => join(dir, safe + ext)).find((f) => {
+          try {
+            return readFileSync(f, "utf8") !== undefined;
+          } catch {
+            return false;
+          }
+        });
+        if (!file) {
+          throw new Error(
+            `No saved workflow "${safe}". Available: ${savedWorkflows(uiCtx.cwd).join(", ") || "(none)"}`,
+          );
+        }
+        script = readFileSync(file, "utf8");
+      }
+      if (!script.trim()) throw new Error("workflow requires a script (or a saved name).");
+
+      runCounter++;
+      const run: WorkflowRun = {
+        runId: `w${runCounter}`,
+        background: params.background === true,
+        status: "running",
+        startedAt: Date.now(),
+        finishedAt: null,
+        phases: [],
+        agents: [],
+        logs: [],
+        result: null,
+        error: null,
+      };
+      runs.set(run.runId, run);
+      activeRun = run;
+      renderWidget(uiCtx);
+
+      if (run.background) {
+        void execute(uiCtx, run, script, params.args).then(() => {
+          notify(uiCtx, `workflow ${run.runId}: ${run.status}`, run.status === "done" ? "info" : "warning");
+        });
+        return {
+          content: [{ type: "text", text: `Workflow ${run.runId} started. Poll workflow_status runId="${run.runId}".` }],
+          details: { runId: run.runId },
+        };
+      }
+
+      await execute(uiCtx, run, script, params.args);
+      return {
+        content: [{ type: "text", text: formatResult(run) }],
+        details: { runId: run.runId, status: run.status, agents: run.agents.length },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "workflow_status",
+    label: "Workflow status",
+    description: "Progress of a workflow run (default: the latest). Returns the result when finished.",
+    parameters: Type.Object({
+      runId: Type.Optional(Type.String()),
+    }),
+    async execute(_id, params: { runId?: string }) {
+      const run = params.runId ? runs.get(params.runId.trim()) : activeRun ?? [...runs.values()].pop();
+      if (!run) throw new Error("No workflow runs this session.");
+      const text = run.status === "running" ? formatStatus(run) : formatResult(run);
+      return { content: [{ type: "text", text }], details: { runId: run.runId, status: run.status } };
+    },
+  });
+
+  // ── Lifecycle & command ──────────────────────────────────────────────
+
+  pi.on("session_start", async (_event, ctx) => {
+    loadDefs(ctx.cwd);
+    runs.clear();
+    activeRun = null;
+    for (const entry of ctx.sessionManager.getBranch()) {
+      const e = entry as { type?: string; customType?: string; data?: unknown };
+      if (e.type !== "custom" || e.customType !== RUN_ENTRY || !isRecord(e.data)) continue;
+      const run = e.data as unknown as WorkflowRun;
+      if (typeof run.runId === "string" && run.status !== "running") {
+        runs.set(run.runId, run);
+        const n = Number.parseInt(run.runId.slice(1), 10);
+        if (Number.isFinite(n) && n > runCounter) runCounter = n;
+      }
+    }
+    renderWidget(ctx);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    if (ctx.hasUI) ctx.ui.setWidget("workflow", undefined);
+  });
+
+  pi.registerCommand("workflows", {
+    description: "List workflow runs and saved scripts (.pi/workflows/)",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+      const saved = savedWorkflows(ctx.cwd);
+      const runLines = [...runs.values()].map((r) => formatStatus(r)).join("\n") || "(no runs yet)";
+      ctx.ui.notify(
+        `Saved workflows\n${saved.length > 0 ? saved.join("\n") : "(none — add .pi/workflows/<name>.js)"}\n\nRuns\n${runLines}`,
+        "info",
+      );
+    },
+  });
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@pify/workflow",
+  "version": "0.1.1",
+  "description": "Deterministic multi-step agent orchestration for pi: a Claude Code-style workflow tool with agent()/parallel()/pipeline() scripts over the shared agent catalog",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pify",
+    "workflow",
+    "orchestration"
+  ],
+  "homepage": "https://github.com/pifydev/workflow#readme",
+  "bugs": {
+    "url": "https://github.com/pifydev/workflow/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pifydev/workflow.git"
+  },
+  "license": "MIT",
+  "author": "Pify maintainers",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/workflow.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
+    "@types/node": "^22.10.2",
+    "typebox": "^1.1.38",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/workflow/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: workflow
+description: Use when a task needs deterministic multi-agent orchestration - fan out, verify, synthesize across many child agents with loops/conditionals - explains the workflow tool's script contract and when NOT to use it
+---
+
+# Workflows
+
+This project has the `@pify/workflow` extension installed: the `workflow`
+tool runs a JavaScript orchestration script over child agents.
+
+## When to reach for it
+
+- The work decomposes into many agent calls with real control flow
+  (loops, conditionals, staged verification) — audits, migrations,
+  multi-perspective reviews with cross-checking.
+- Intermediate results should stay in script variables instead of
+  flooding this conversation's context.
+
+Use the smaller primitives when they fit: one task → agent_run
+(@pify/subagent); independent parallel items → swarm_run (@pify/swarm).
+Only orchestrate when the structure earns it.
+
+## Script contract
+
+- `agent(prompt, {agent?, label?, phase?})` → the child's report (or null
+  on failure). Agent types: reviewer / scout / worker / .pi/agents custom.
+  Prompts must be self-contained briefs — children see nothing else.
+- `parallel(thunks)` is a barrier; failed thunks resolve null —
+  `.filter(Boolean)` before use. `pipeline(items, ...stages)` has no
+  barrier between stages; a throwing stage drops that item to null.
+- `phase(title)` groups progress; `log(msg)` narrates; `args` carries the
+  input value; the script's `return` value is the tool result.
+- Determinism is enforced: `Date.now()`, `Math.random()`, argless
+  `new Date()`, and `eval` throw. Pass timestamps in via `args`.
+- Caps: 20 agents per run, 4 concurrent, 10-minute timeout.
+
+## Saved workflows
+
+Reusable scripts live in `.pi/workflows/<name>.js` and run with
+`workflow name="<name>" args={...}`. Prefer a saved script when the user
+runs the same orchestration repeatedly.

package/src/builtin.ts

@@ -0,0 +1,48 @@
+/**
+ * Built-in agent types (adapted from nicobailon/pi-subagents' agent set,
+ * trimmed to three archetypes). Overridable: a project or global .md file
+ * with the same name wins.
+ */
+
+export const BUILTIN_AGENTS: Record<string, string> = {
+  reviewer: `---
+description: Read-only review specialist for diffs, plans, and code health
+tools: read, grep, find, ls
+thinking: high
+max_turns: 25
+---
+
+You are a disciplined review subagent. Inspect, evaluate, and report findings
+with evidence — never guess; verify from the code itself. You cannot modify
+anything: your deliverable is the report.
+
+For each finding give: file:line, what is wrong, why it matters, and a
+concrete suggestion. Rank findings by severity. If the code is fine, say so
+plainly — do not invent issues. End with a one-paragraph verdict.`,
+
+  scout: `---
+description: Fast read-only exploration and research across the codebase
+tools: read, grep, find, ls
+thinking: low
+max_turns: 25
+---
+
+You are a scout subagent: locate, map, and summarize — quickly. Answer the
+question with file paths and line references, quoting only the smallest
+relevant excerpts. Prefer breadth over depth unless asked otherwise. If
+something cannot be found, report exactly what you searched so the caller
+can redirect you. Your final message is the entire deliverable.`,
+
+  worker: `---
+description: Implementation agent with full tool access for a scoped task
+tools: read, bash, edit, write, grep, find, ls
+thinking: medium
+max_turns: 60
+---
+
+You are a worker subagent implementing one scoped task. Stay strictly within
+the task's boundaries: no drive-by refactors, no scope creep. Follow the
+project's existing conventions. Verify your work (build, tests, or a smoke
+check) before finishing. Your final message must state exactly what changed,
+what you verified, and anything you deliberately left undone.`,
+};

package/src/frontmatter.ts

@@ -0,0 +1,74 @@
+import {
+  DEFAULT_MAX_TURNS,
+  THINKING_LEVELS,
+  VALID_TOOLS,
+  type AgentDef,
+  type ThinkingLevelName,
+  type ValidTool,
+} from "./types.ts";
+
+/**
+ * Parse an agent definition file: same schema as @pify/subagent plus the
+ * routing keys `match_patterns` / `match_keywords` (comma-separated, also
+ * accepts the camelCase spellings gjczone used). One definition file serves
+ * both packages.
+ */
+export function parseAgentFile(
+  name: string,
+  content: string,
+  source: AgentDef["source"],
+): AgentDef | null {
+  const normalized = content.replace(/\r\n/g, "\n");
+  const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(normalized);
+  if (!match) return null;
+
+  const fields = new Map<string, string>();
+  for (const line of match[1]!.split("\n")) {
+    const kv = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(line.trim());
+    if (kv) fields.set(kv[1]!.toLowerCase(), kv[2]!.trim());
+  }
+
+  const description = fields.get("description") ?? "";
+  if (!description) return null;
+
+  const thinkingRaw = fields.get("thinking")?.toLowerCase();
+  const maxTurnsRaw = Number.parseInt(fields.get("max_turns") ?? "", 10);
+
+  return {
+    name: name.toLowerCase(),
+    description,
+    tools: parseTools(fields.get("tools")),
+    model: fields.get("model") || null,
+    thinking: (THINKING_LEVELS as readonly string[]).includes(thinkingRaw ?? "")
+      ? (thinkingRaw as ThinkingLevelName)
+      : null,
+    maxTurns:
+      Number.isFinite(maxTurnsRaw) && maxTurnsRaw > 0 && maxTurnsRaw <= 200
+        ? maxTurnsRaw
+        : DEFAULT_MAX_TURNS,
+    systemPrompt: match[2]!.trim(),
+    source,
+    matchPatterns: parseList(fields.get("match_patterns") ?? fields.get("matchpatterns")),
+    matchKeywords: parseList(fields.get("match_keywords") ?? fields.get("matchkeywords")).map((k) =>
+      k.toLowerCase(),
+    ),
+  };
+}
+
+function parseList(raw: string | undefined): string[] {
+  if (!raw) return [];
+  return raw
+    .replace(/^\[|\]$/g, "")
+    .split(",")
+    .map((t) => t.trim().replace(/^["']|["']$/g, ""))
+    .filter(Boolean);
+}
+
+function parseTools(raw: string | undefined): ValidTool[] {
+  if (!raw) return ["read", "grep", "find", "ls"];
+  const valid = raw
+    .split(",")
+    .map((t) => t.trim().toLowerCase())
+    .filter((t): t is ValidTool => (VALID_TOOLS as readonly string[]).includes(t));
+  return valid.length > 0 ? valid : ["read", "grep", "find", "ls"];
+}

package/src/report.ts

@@ -0,0 +1,53 @@
+import type { ThemeLike, WorkflowRun } from "./types.ts";
+
+export function formatResult(run: WorkflowRun): string {
+  const header = `[workflow ${run.runId}] ${run.status} — ${run.agents.length} agents, ${run.phases.length} phases`;
+  if (run.status === "error") return `${header}\nError: ${run.error ?? "unknown"}`;
+  if (run.status === "running") {
+    return `${header}\nStill running — poll workflow_status runId="${run.runId}".`;
+  }
+  return `${header}\n${run.result ?? "(script returned nothing)"}`;
+}
+
+export function formatStatus(run: WorkflowRun): string {
+  const agents = run.agents
+    .map((a) => `${a.id}:${a.label}=${a.status}${a.turns ? `(${a.turns}t)` : ""}`)
+    .join(" · ");
+  const phase = run.phases.length > 0 ? ` · phase: ${run.phases[run.phases.length - 1]}` : "";
+  return `[workflow ${run.runId}] ${run.status}${phase}${agents ? ` — ${agents}` : ""}`;
+}
+
+const WIDTH = 54;
+
+export function buildWidgetLines(run: WorkflowRun | null, theme: ThemeLike, now: number): string[] {
+  if (!run) return [];
+  if (run.status !== "running" && (run.finishedAt ?? 0) < now - 15_000) return [];
+
+  const dim = (s: string) => theme.fg("dim", s);
+  const lines: string[] = [];
+  const title = ` ⚙ workflow ${run.runId} `;
+  const hint = " /workflows ";
+  const pad = Math.max(1, WIDTH - title.length - hint.length);
+  lines.push(dim(`╭${title}${"─".repeat(pad)}${hint}╮`));
+
+  if (run.phases.length > 0) {
+    lines.push(`${dim("│ ")}${theme.bold(run.phases[run.phases.length - 1]!)}`);
+  }
+
+  for (const agent of run.agents.slice(-6)) {
+    const paint =
+      agent.status === "running"
+        ? (s: string) => theme.fg("warning", s)
+        : agent.status === "done"
+          ? (s: string) => theme.fg("success", s)
+          : (s: string) => theme.fg("error", s);
+    const icon = agent.status === "running" ? "⟳" : agent.status === "done" ? "✓" : "✗";
+    lines.push(`${dim("│ ")}${paint(`${icon} ${agent.label}`)}${dim(` (${agent.agent})`)}`);
+  }
+
+  const lastLog = run.logs[run.logs.length - 1];
+  if (lastLog) lines.push(dim(`│ ${lastLog.length > 48 ? `${lastLog.slice(0, 48)}…` : lastLog}`));
+
+  lines.push(dim(`╰${"─".repeat(WIDTH)}╯`));
+  return lines;
+}

package/src/sandbox.ts

@@ -0,0 +1,159 @@
+import vm from "node:vm";
+import { MAX_AGENTS_PER_RUN, SCRIPT_TIMEOUT_MS } from "./types.ts";
+
+/**
+ * Deterministic script sandbox (tintinweb's discipline, Claude Code's
+ * contract): a fresh vm context exposing exactly the orchestration globals —
+ * agent / parallel / pipeline / phase / log / args — with Date.now(),
+ * Math.random(), argless new Date(), and string code generation poisoned so
+ * a script's control flow is reproducible. This is cooperative determinism,
+ * not a security boundary: the script runs at the same trust level as the
+ * bash tool in the same session.
+ */
+
+export interface AgentOptions {
+  agent?: string;
+  label?: string;
+  phase?: string;
+}
+
+export interface SandboxHooks {
+  /** Spawn one child agent; resolves to its report text or null on failure. */
+  agent(prompt: string, opts?: AgentOptions): Promise<string | null>;
+  log(message: string): void;
+  phase(title: string): void;
+}
+
+function poisonedMath(): Math {
+  const clone = Object.create(Math) as Math;
+  Object.defineProperty(clone, "random", {
+    value: () => {
+      throw new Error("Math.random() is unavailable in workflow scripts (determinism).");
+    },
+  });
+  return clone;
+}
+
+function poisonedDate(): DateConstructor {
+  return new Proxy(Date, {
+    construct(target, args: unknown[]) {
+      if (args.length === 0) {
+        throw new Error("new Date() without arguments is unavailable in workflow scripts (determinism).");
+      }
+      return new (target as DateConstructor)(...(args as [number]));
+    },
+    get(target, prop) {
+      if (prop === "now") {
+        return () => {
+          throw new Error("Date.now() is unavailable in workflow scripts (determinism).");
+        };
+      }
+      return Reflect.get(target, prop);
+    },
+  }) as DateConstructor;
+}
+
+/**
+ * CC-style scripts may start with `export const meta = {...}`; vm scripts
+ * are not modules, so export prefixes are stripped (the binding remains).
+ */
+export function stripExports(script: string): string {
+  return script.replace(/^\s*export\s+(?=const|let|var|function|async)/gm, "");
+}
+
+export interface RunScriptOptions {
+  timeoutMs?: number;
+  maxAgents?: number;
+}
+
+export async function runScript(
+  script: string,
+  args: unknown,
+  hooks: SandboxHooks,
+  options: RunScriptOptions = {},
+): Promise<unknown> {
+  const maxAgents = options.maxAgents ?? MAX_AGENTS_PER_RUN;
+  let agentCalls = 0;
+
+  const agent = (prompt: unknown, opts?: AgentOptions): Promise<string | null> => {
+    if (typeof prompt !== "string" || !prompt.trim()) {
+      throw new Error("agent() requires a non-empty prompt string.");
+    }
+    agentCalls++;
+    if (agentCalls > maxAgents) {
+      throw new Error(`Agent cap reached (${maxAgents} per run).`);
+    }
+    return hooks.agent(prompt, opts);
+  };
+
+  const parallel = (thunks: Array<() => Promise<unknown>>): Promise<unknown[]> => {
+    if (!Array.isArray(thunks)) throw new Error("parallel() takes an array of thunks.");
+    return Promise.all(thunks.map((t) => Promise.resolve().then(t).catch(() => null)));
+  };
+
+  const pipeline = (items: unknown[], ...stages: Array<(prev: unknown, item: unknown, index: number) => unknown>): Promise<unknown[]> => {
+    if (!Array.isArray(items)) throw new Error("pipeline() takes an items array.");
+    return Promise.all(
+      items.map(async (item, index) => {
+        let value: unknown = item;
+        for (const stage of stages) {
+          try {
+            value = await stage(value, item, index);
+          } catch {
+            return null;
+          }
+        }
+        return value;
+      }),
+    );
+  };
+
+  const context = vm.createContext(
+    {
+      agent,
+      parallel,
+      pipeline,
+      phase: (title: unknown) => hooks.phase(String(title)),
+      log: (message: unknown) => hooks.log(String(message)),
+      args,
+      JSON,
+      Math: poisonedMath(),
+      Date: poisonedDate(),
+      Promise,
+      Array,
+      Object,
+      String,
+      Number,
+      Boolean,
+      Set,
+      Map,
+      console: { log: (message: unknown) => hooks.log(String(message)) },
+      eval: undefined,
+      Function: undefined,
+    },
+    { codeGeneration: { strings: false, wasm: false } },
+  );
+
+  const body = stripExports(script);
+  const promise = vm.runInContext(
+    `(async () => {\n${body}\n})()`,
+    context,
+    { timeout: 30_000 }, // guards synchronous runaway loops only
+  ) as Promise<unknown>;
+
+  const timeoutMs = options.timeoutMs ?? SCRIPT_TIMEOUT_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`Workflow script timed out after ${Math.round(timeoutMs / 1000)}s.`)),
+          timeoutMs,
+        );
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}

package/src/types.ts

@@ -0,0 +1,93 @@
+/**
+ * Local structural types for @pify/workflow.
+ * No imports from pi packages: src/ typechecks and runs standalone.
+ */
+
+export const VALID_TOOLS = [
+  "read",
+  "bash",
+  "powershell",
+  "edit",
+  "write",
+  "grep",
+  "find",
+  "ls",
+] as const;
+export type ValidTool = (typeof VALID_TOOLS)[number];
+
+export type ThinkingLevelName = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export const THINKING_LEVELS: readonly ThinkingLevelName[] = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+];
+
+/** Agent definition — same file format as @pify/subagent and @pify/swarm. */
+export interface AgentDef {
+  name: string;
+  description: string;
+  tools: ValidTool[];
+  model: string | null;
+  thinking: ThinkingLevelName | null;
+  maxTurns: number;
+  systemPrompt: string;
+  source: "builtin" | "global" | "project";
+  matchPatterns: string[];
+  matchKeywords: string[];
+}
+
+export const DEFAULT_MAX_TURNS = 30;
+
+/** Workflow execution limits. */
+export const MAX_AGENTS_PER_RUN = 20;
+export const AGENT_CONCURRENCY = 4;
+export const SCRIPT_TIMEOUT_MS = 10 * 60 * 1000;
+/** Persisted results are capped so session files stay sane. */
+export const MAX_PERSISTED_RESULT_CHARS = 32_000;
+
+export type AgentCallStatus = "running" | "done" | "error" | "aborted";
+
+export interface AgentCallState {
+  id: number;
+  label: string;
+  agent: string;
+  phase: string | null;
+  status: AgentCallStatus;
+  turns: number;
+  tokens: number;
+}
+
+export type RunStatus = "running" | "done" | "error";
+
+export interface WorkflowRun {
+  runId: string;
+  background: boolean;
+  status: RunStatus;
+  startedAt: number;
+  finishedAt: number | null;
+  phases: string[];
+  agents: AgentCallState[];
+  logs: string[];
+  result: string | null;
+  error: string | null;
+}
+
+export interface ThemeLike {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+}
+
+export interface BranchEntryLike {
+  type?: string;
+  customType?: string;
+  data?: unknown;
+  [key: string]: unknown;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}