pi-workflow-engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 timbrinded
+
+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,135 @@
+<p align="center">
+  <img src="assets/preview.png" width="200" alt="pi-workflow-engine — a central agent orchestrating a ring of subagents" />
+</p>
+
+# pi-workflow-engine
+
+A customisable multi-agent workflow-orchestration engine for the [pi](https://pi.dev) coding agent — your own version of Claude Code's built-in `/code-review`, built on pi's SDK. Workflows fan out to many subagents, pass validated structured data between stages, and synthesise a result.
+
+## Install
+
+```bash
+pi install git:github.com/timbrinded/pi-workflow-engine
+```
+
+Or from npm:
+
+```bash
+pi install npm:pi-workflow-engine
+```
+
+That's all — pi fetches the package and serves its dependencies from its own bundle, so there's no clone, install, or build step. Restart pi (or run `/reload` in an open session), then confirm it's registered:
+
+```bash
+pi list
+```
+
+Scope it to a single repo instead of globally (writes to that repo's `.pi/settings.json`):
+
+```bash
+pi install git:github.com/timbrinded/pi-workflow-engine -l
+```
+
+Uninstall with `pi remove git:github.com/timbrinded/pi-workflow-engine`.
+
+## Usage
+
+In a pi session, from inside a git repo with changes:
+
+```
+/workflow code-review            # review the current branch
+/workflow code-review HEAD~3     # review a ref range / target / focus area
+/workflow ping                   # quick engine smoke test (one agent)
+```
+
+The host agent can also invoke the `workflow` tool itself mid-conversation (e.g. "run the code-review workflow") and fold the structured result back into its reasoning.
+
+`code-review` returns a verified, ranked report:
+
+```json
+{
+  "summary": "1 confirmed bug: off-by-one loop boundary in sum.js ...",
+  "findings": [
+    {
+      "file": "sum.js",
+      "line": 3,
+      "severity": "bug",
+      "verdict": "CONFIRMED",
+      "summary": "Off-by-one: `i <= arr.length` should be `i < arr.length`; accesses arr[arr.length] (undefined) → NaN."
+    }
+  ]
+}
+```
+
+## How it works
+
+A **workflow** is a TypeScript module that exports `meta` plus a default `async (api) => result`. The injected `api` gives you five primitives:
+
+| Primitive | Behaviour |
+|-----------|-----------|
+| `agent(prompt, { schema })` | Runs a subagent in an isolated session; with a typebox `schema` it returns validated structured data, otherwise the final text. |
+| `parallel(thunks)` | Runs every thunk concurrently and waits for all (a barrier). |
+| `pipeline(items, ...stages)` | Runs each item through all stages independently — no barrier between stages. |
+| `phase(title)` / `log(msg)` | Drive the live progress tree shown in the TUI. |
+
+```ts
+import { Type } from "typebox";
+import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
+
+export const meta: WorkflowMeta = { name: "my-workflow", description: "..." };
+
+export default async function run({ agent, parallel, pipeline, phase, log, args }: WorkflowApi) {
+  phase("Find");
+  const result = await agent("find issues ...", { schema: Type.Object({ /* ... */ }) });
+  return result; // a typed object, validated against the schema
+}
+```
+
+Under the hood:
+
+- **Each `agent()` is an in-process pi `AgentSession`** (`createAgentSession` + `SessionManager.inMemory()`), inheriting the host's model unless you set one.
+- **Structured output is a terminating tool**: the engine registers one tool whose `parameters` *is* your schema; pi validates the call and the engine captures the args — no parsing.
+- **A single global semaphore caps concurrent agents**, so `parallel`/`pipeline` nest freely while the cap holds inside every `agent()` call.
+- **Surfaces**: a `/workflow <name> [args]` command, plus a `workflow` tool the host agent can call.
+
+## Local development
+
+Only needed if you want to **add or customise workflows, or contribute** — using the bundled workflows requires none of this.
+
+```bash
+git clone https://github.com/timbrinded/pi-workflow-engine
+cd pi-workflow-engine
+bun install            # dev deps for typechecking only; pi serves bundled copies at runtime
+bun run typecheck      # tsc --noEmit
+bun scripts/smoke.ts   # no-LLM check: module graph loads + workflow discovery resolves
+```
+
+Load your working copy into a session without installing it (ephemeral — overrides nothing):
+
+```bash
+pi -e ./src/index.ts -p "/workflow ping"
+```
+
+**Add a workflow:** drop a `.ts` in `workflows/`, import it in `src/workflows.ts`, and add it to `BUILTIN_WORKFLOWS`. Statically-imported workflows share pi's bundled `typebox`, which guarantees schema validation. (Files in `workflows/` and `~/.pi/agent/workflows/` are also discovered dynamically at runtime, best-effort.)
+
+**Customise the review:** edit the `ANGLES` array in `workflows/code-review.ts` — the lenses are where your codebase's real failure modes and conventions belong. Tune `model` / `thinkingLevel` / `tools` per `agent()` call, and `DEFAULT_CONCURRENCY` in `src/engine.ts`.
+
+### Layout
+
+```
+src/
+  index.ts         extension entry (registers the command + tool)
+  types.ts         WorkflowApi / WorkflowModule contracts
+  agent-runner.ts  the createAgentSession + terminating-tool schema bridge
+  concurrency.ts   Semaphore, parallel(), pipeline()
+  engine.ts        runWorkflow() — binds the primitives to a run
+  progress.ts      live phase/agent tree via ctx.ui.setWidget
+  discovery.ts     static registry + best-effort drop-in loading
+workflows/
+  code-review.ts   the example: scope → find → verify → synthesize
+  ping.ts          minimal smoke workflow
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "pi-workflow-engine",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A customisable multi-agent workflow-orchestration engine for the pi coding agent.",
+  "keywords": ["pi-package"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/timbrinded/pi-workflow-engine.git"
+  },
+  "files": ["src", "workflows"],
+  "pi": {
+    "extensions": ["./src/index.ts"],
+    "image": "https://raw.githubusercontent.com/timbrinded/pi-workflow-engine/master/assets/preview.png"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.6.0"
+  }
+}

package/src/agent-runner.ts

@@ -0,0 +1,118 @@
+import { createAgentSession, defineTool, SessionManager } from "@earendil-works/pi-coding-agent";
+import type { ModelRegistry, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+import type { AgentState } from "@earendil-works/pi-agent-core";
+import type { AgentOptions } from "./types.ts";
+import type { Semaphore } from "./concurrency.ts";
+import type { ProgressTracker } from "./progress.ts";
+
+/** Name of the synthetic terminating tool that carries structured output. */
+const FINAL_TOOL = "final_answer";
+
+/** Shared per-run context threaded into every agent() call. */
+export interface RunContext {
+  cwd: string;
+  hostModel: Model<any> | undefined;
+  modelRegistry: ModelRegistry;
+  semaphore: Semaphore;
+  progress: ProgressTracker;
+  signal: AbortSignal | undefined;
+}
+
+/** Pull the last assistant message's plain text out of a finished session. */
+function lastAssistantText(state: AgentState): string {
+  const messages = state.messages;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if ("role" in message && message.role === "assistant") {
+      const content = (message as { content?: Array<{ type: string; text?: string }> }).content ?? [];
+      return content
+        .filter((part) => part.type === "text")
+        .map((part) => part.text ?? "")
+        .join("")
+        .trim();
+    }
+  }
+  return "";
+}
+
+/**
+ * Run one subagent to completion in an isolated in-memory session.
+ *
+ * Structured output trick: when `opts.schema` is set we register a single
+ * terminating tool whose `parameters` IS the schema. The agent's last action is to
+ * call it; pi validates the args against the schema, hands them to `execute`, and
+ * `terminate: true` ends the turn with no extra LLM round-trip. We capture those
+ * validated args in a closure — that captured object is the structured result, so
+ * no event-stream parsing is needed.
+ */
+export async function runAgent(rc: RunContext, prompt: string, opts: AgentOptions = {}): Promise<unknown> {
+  const label = opts.label ?? "agent";
+
+  // Acquire a global concurrency slot before spawning the session.
+  return rc.semaphore.run(async () => {
+    rc.progress.agentStart(opts.phase, label);
+
+    let captured: unknown = null;
+    const customTools: ToolDefinition[] = opts.schema
+      ? [
+          defineTool({
+            name: FINAL_TOOL,
+            label: "Final Answer",
+            description:
+              "Return your final structured answer. This MUST be your last action — do not write a normal reply after calling it.",
+            parameters: opts.schema,
+            async execute(_toolCallId, params) {
+              captured = params;
+              return { content: [{ type: "text", text: "Recorded." }], details: params, terminate: true };
+            },
+          }),
+        ]
+      : [];
+
+    // When the workflow restricts built-in tools, keep the terminating tool visible.
+    const allow = opts.tools
+      ? opts.schema
+        ? [...opts.tools, FINAL_TOOL]
+        : opts.tools
+      : undefined;
+
+    // Resolve the model by runtime id lookup (no compile-time model-id union); fall back to the host's model.
+    const model = opts.model ? rc.modelRegistry.find("anthropic", opts.model) ?? rc.hostModel : rc.hostModel;
+
+    const { session } = await createAgentSession({
+      cwd: rc.cwd,
+      model,
+      modelRegistry: rc.modelRegistry,
+      thinkingLevel: opts.thinkingLevel,
+      tools: allow,
+      customTools,
+      sessionManager: SessionManager.inMemory(rc.cwd),
+    });
+
+    const unsubscribe = session.subscribe((event) => {
+      if (event.type === "tool_execution_start" && event.toolName !== FINAL_TOOL) {
+        rc.progress.agentTool(label, event.toolName);
+      }
+    });
+
+    try {
+      const finalPrompt = opts.schema
+        ? `${prompt}\n\nWhen finished, return your result by calling the ${FINAL_TOOL} tool.`
+        : prompt;
+      await session.prompt(finalPrompt);
+      if (opts.schema) {
+        if (captured === null) rc.progress.log(`${label}: no structured answer returned`);
+        return captured;
+      }
+      return lastAssistantText(session.state);
+    } catch (error) {
+      rc.progress.log(`${label} failed: ${error instanceof Error ? error.message : String(error)}`);
+      throw error;
+    } finally {
+      unsubscribe();
+      session.dispose();
+      rc.progress.agentDone(label);
+    }
+  });
+}

package/src/concurrency.ts

@@ -0,0 +1,55 @@
+/**
+ * A counting semaphore: bounds how many async tasks run at once.
+ *
+ * This is the single global concurrency cap for a workflow run. Every `agent()`
+ * call acquires a slot before spawning a session and releases it when done, so the
+ * cap holds no matter how `parallel`/`pipeline` are nested — exactly like the
+ * built-in Workflow tool, where "concurrent agent() calls are capped and excess queue".
+ */
+export class Semaphore {
+  private active = 0;
+  private readonly waiters: Array<() => void> = [];
+
+  constructor(private readonly max: number) {}
+
+  async run<T>(fn: () => Promise<T>): Promise<T> {
+    if (this.active >= this.max) {
+      await new Promise<void>((resolve) => this.waiters.push(resolve));
+    }
+    this.active++;
+    try {
+      return await fn();
+    } finally {
+      this.active--;
+      this.waiters.shift()?.();
+    }
+  }
+}
+
+/** Run every thunk concurrently and wait for all results (a barrier). */
+export async function parallel<T>(thunks: Array<() => Promise<T>>): Promise<T[]> {
+  return Promise.all(thunks.map((thunk) => thunk()));
+}
+
+/**
+ * Run each item through all stages independently. There is NO barrier between
+ * stages: item A can be in stage 3 while item B is still in stage 1. Actual agent
+ * concurrency is bounded by the run's Semaphore (inside each `agent()`), not here —
+ * so launching every item at once is safe.
+ *
+ * Each stage receives (previousResult, originalItem, index).
+ */
+export async function pipeline(
+  items: unknown[],
+  ...stages: Array<(prev: unknown, item: unknown, index: number) => Promise<unknown>>
+): Promise<unknown[]> {
+  return Promise.all(
+    items.map(async (item, index) => {
+      let acc: unknown = item;
+      for (const stage of stages) {
+        acc = await stage(acc, item, index);
+      }
+      return acc;
+    }),
+  );
+}

package/src/discovery.ts

@@ -0,0 +1,54 @@
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { WorkflowModule } from "./types.ts";
+import { BUILTIN_WORKFLOWS } from "./workflows.ts";
+
+function isWorkflowModule(value: unknown): value is WorkflowModule {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as { meta?: { name?: unknown }; default?: unknown };
+  return typeof candidate.meta?.name === "string" && typeof candidate.default === "function";
+}
+
+/** Best-effort dynamic load of every `*.ts` workflow in a directory. */
+async function loadDir(dir: string): Promise<WorkflowModule[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return [];
+  }
+
+  const modules: WorkflowModule[] = [];
+  for (const name of entries) {
+    if (!name.endsWith(".ts") || name.startsWith("_") || name.startsWith(".")) continue;
+    try {
+      const loaded: unknown = await import(pathToFileURL(join(dir, name)).href);
+      if (isWorkflowModule(loaded)) modules.push(loaded);
+    } catch (error) {
+      // Drop-in loading depends on the runtime resolving TS + the bundled typebox.
+      // Failures here are non-fatal: the static registry still works.
+      console.error(`[workflow-engine] skipped ${name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return modules;
+}
+
+/**
+ * All available workflows by name. Static registry wins on name collisions, so the
+ * bundled example is always the verified one even if a same-named file is dropped in.
+ */
+export async function discoverWorkflows(repoDir: string): Promise<Map<string, WorkflowModule>> {
+  const byName = new Map<string, WorkflowModule>();
+  for (const mod of BUILTIN_WORKFLOWS) byName.set(mod.meta.name, mod);
+
+  const dynamic = [
+    ...(await loadDir(join(repoDir, "workflows"))),
+    ...(await loadDir(join(homedir(), ".pi", "agent", "workflows"))),
+  ];
+  for (const mod of dynamic) {
+    if (!byName.has(mod.meta.name)) byName.set(mod.meta.name, mod);
+  }
+  return byName;
+}

package/src/engine.ts

@@ -0,0 +1,43 @@
+import { cpus } from "node:os";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { parallel, pipeline, Semaphore } from "./concurrency.ts";
+import { runAgent, type RunContext } from "./agent-runner.ts";
+import { ProgressTracker } from "./progress.ts";
+import type { AgentOptions, WorkflowApi, WorkflowModule } from "./types.ts";
+
+/** Default global cap on concurrent agents per run. */
+const DEFAULT_CONCURRENCY = Math.min(8, Math.max(2, cpus().length));
+
+/**
+ * Run a workflow module: build the per-run primitives (binding agent/parallel/pipeline
+ * to a shared semaphore + progress tracker), invoke the workflow, return its result.
+ */
+export async function runWorkflow(ctx: ExtensionContext, mod: WorkflowModule, args: string): Promise<unknown> {
+  const progress = new ProgressTracker(ctx, mod.meta.name);
+  const rc: RunContext = {
+    cwd: ctx.cwd,
+    hostModel: ctx.model,
+    modelRegistry: ctx.modelRegistry,
+    semaphore: new Semaphore(DEFAULT_CONCURRENCY),
+    progress,
+    signal: ctx.signal,
+  };
+
+  const agent = ((prompt: string, opts?: AgentOptions) => runAgent(rc, prompt, opts)) as WorkflowApi["agent"];
+
+  const api: WorkflowApi = {
+    agent,
+    parallel,
+    pipeline,
+    phase: (title) => progress.phase(title),
+    log: (message) => progress.log(message),
+    args,
+    signal: ctx.signal,
+  };
+
+  try {
+    return await mod.default(api);
+  } finally {
+    progress.done();
+  }
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+import { fileURLToPath } from "node:url";
+import { Type } from "typebox";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { discoverWorkflows } from "./discovery.ts";
+import { runWorkflow } from "./engine.ts";
+
+/** Repo root (this file lives in <repo>/src/index.ts). */
+const REPO_DIR = fileURLToPath(new URL("..", import.meta.url));
+
+function summarize(result: unknown): string {
+  if (result && typeof result === "object" && typeof (result as { summary?: unknown }).summary === "string") {
+    return (result as { summary: string }).summary;
+  }
+  return typeof result === "string" ? result : "Workflow finished.";
+}
+
+function formatReport(name: string, result: unknown): string {
+  return [`## Workflow: ${name}`, "", "```json", JSON.stringify(result, null, 2), "```"].join("\n");
+}
+
+export default function workflowEngine(pi: ExtensionAPI): void {
+  // /workflow <name> [args] — user-invoked.
+  pi.registerCommand("workflow", {
+    description: "Run a multi-agent workflow: /workflow <name> [args]",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const trimmed = args.trim();
+      const space = trimmed.indexOf(" ");
+      const name = space === -1 ? trimmed : trimmed.slice(0, space);
+      const rest = space === -1 ? "" : trimmed.slice(space + 1).trim();
+
+      const workflows = await discoverWorkflows(REPO_DIR);
+      const available = [...workflows.keys()].join(", ") || "(none)";
+
+      if (!name) {
+        ctx.ui.notify(`Usage: /workflow <name> [args]. Available: ${available}`, "warning");
+        return;
+      }
+      const mod = workflows.get(name);
+      if (!mod) {
+        ctx.ui.notify(`Unknown workflow "${name}". Available: ${available}`, "error");
+        return;
+      }
+
+      const result = await runWorkflow(ctx, mod, rest);
+      pi.sendMessage(
+        { customType: "workflow-result", content: formatReport(name, result), display: true, details: result },
+        { triggerTurn: false },
+      );
+    },
+  });
+
+  // workflow tool — lets the host agent fan out mid-conversation.
+  pi.registerTool({
+    name: "workflow",
+    label: "Workflow",
+    description:
+      "Run a named multi-agent workflow (fan-out → verify → synthesize) and return its structured result. Use for thorough reviews or audits.",
+    parameters: Type.Object({
+      name: Type.String({ description: "Workflow name, e.g. code-review" }),
+      args: Type.Optional(Type.String({ description: "Arguments for the workflow (e.g. target or focus)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const workflows = await discoverWorkflows(REPO_DIR);
+      const mod = workflows.get(params.name);
+      if (!mod) {
+        const available = [...workflows.keys()].join(", ") || "(none)";
+        return {
+          content: [{ type: "text", text: `Unknown workflow "${params.name}". Available: ${available}` }],
+          details: { error: "unknown_workflow", available },
+        };
+      }
+      const result = await runWorkflow(ctx, mod, params.args ?? "");
+      return { content: [{ type: "text", text: summarize(result) }], details: result };
+    },
+  });
+}

package/src/progress.ts

@@ -0,0 +1,108 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+interface AgentRow {
+  label: string;
+  status: "running" | "done";
+  lastTool?: string;
+}
+
+interface Phase {
+  title: string;
+  agents: AgentRow[];
+}
+
+/**
+ * Renders a live phase/agent tree into the pi TUI via `ctx.ui.setWidget`.
+ * In non-interactive modes (print/JSON/RPC) it falls back to terse stderr breadcrumbs
+ * so it never corrupts stdout.
+ */
+export class ProgressTracker {
+  private readonly phases: Phase[] = [];
+  private readonly logs: string[] = [];
+  private current = "Workflow";
+
+  constructor(
+    private readonly ctx: ExtensionContext,
+    private readonly title: string,
+  ) {
+    this.ensurePhase(this.current);
+  }
+
+  private ensurePhase(title: string): Phase {
+    let phase = this.phases.find((candidate) => candidate.title === title);
+    if (!phase) {
+      phase = { title, agents: [] };
+      this.phases.push(phase);
+    }
+    return phase;
+  }
+
+  phase(title: string): void {
+    this.current = title;
+    this.ensurePhase(title);
+    if (!this.ctx.hasUI) process.stderr.write(`[${this.title}] ${title}\n`);
+    this.render();
+  }
+
+  log(message: string): void {
+    this.logs.push(message);
+    if (this.logs.length > 6) this.logs.shift();
+    if (!this.ctx.hasUI) process.stderr.write(`[${this.title}] ${message}\n`);
+    this.render();
+  }
+
+  agentStart(phase: string | undefined, label: string): void {
+    this.ensurePhase(phase ?? this.current).agents.push({ label, status: "running" });
+    this.render();
+  }
+
+  agentTool(label: string, tool: string): void {
+    const row = this.findRow(label);
+    if (row) row.lastTool = tool;
+    this.render();
+  }
+
+  agentDone(label: string): void {
+    const row = this.findRow(label);
+    if (row && row.status === "running") row.status = "done";
+    this.render();
+  }
+
+  private findRow(label: string): AgentRow | undefined {
+    for (let i = this.phases.length - 1; i >= 0; i--) {
+      const running = this.phases[i].agents.find((agent) => agent.label === label && agent.status === "running");
+      if (running) return running;
+    }
+    for (let i = this.phases.length - 1; i >= 0; i--) {
+      const any = this.phases[i].agents.find((agent) => agent.label === label);
+      if (any) return any;
+    }
+    return undefined;
+  }
+
+  private lines(): string[] {
+    const out: string[] = [`⚙ ${this.title}`];
+    for (const phase of this.phases) {
+      if (phase.agents.length === 0 && phase.title === "Workflow") continue;
+      out.push(`  ${phase.title}`);
+      for (const agent of phase.agents) {
+        const icon = agent.status === "done" ? "✓" : "⏳";
+        const tool = agent.status === "running" && agent.lastTool ? ` · ${agent.lastTool}` : "";
+        out.push(`    ${icon} ${agent.label}${tool}`);
+      }
+    }
+    for (const line of this.logs) out.push(`  · ${line}`);
+    return out;
+  }
+
+  private render(): void {
+    if (this.ctx.hasUI) this.ctx.ui.setWidget("workflow", this.lines());
+  }
+
+  /** Clear the widget; optionally leave a one-line status in the footer. */
+  done(status?: string): void {
+    if (!this.ctx.hasUI) return;
+    this.ctx.ui.setWidget("workflow", undefined);
+    this.ctx.ui.setStatus("workflow", status);
+  }
+}

package/src/types.ts

@@ -0,0 +1,58 @@
+import type { Static, TSchema } from "typebox";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+
+/** Metadata every workflow module must export. */
+export interface WorkflowMeta {
+  name: string;
+  description: string;
+  phases?: Array<{ title: string }>;
+}
+
+/** Options for a single `agent()` call. */
+export interface AgentOptions<S extends TSchema = TSchema> {
+  /** Label shown in the progress tree (e.g. "find:logic-bugs"). */
+  label?: string;
+  /** Phase to group this agent under in the progress tree. */
+  phase?: string;
+  /** Model id (e.g. "claude-opus-4-5"); omit to inherit the host's current model. */
+  model?: string;
+  /** Reasoning effort for this agent. */
+  thinkingLevel?: ThinkingLevel;
+  /** Allowlist of built-in tool names the agent may use (e.g. ["read", "bash"]). */
+  tools?: string[];
+  /** typebox schema. When set, the agent is forced to return matching structured data. */
+  schema?: S;
+}
+
+/**
+ * The primitives injected into every workflow run. A workflow is any module that
+ * exports `meta` plus a default `async (api: WorkflowApi) => result`.
+ */
+export interface WorkflowApi {
+  /** Run a subagent and return its validated structured output (null if it never produced one). */
+  agent<S extends TSchema>(prompt: string, opts: AgentOptions<S> & { schema: S }): Promise<Static<S> | null>;
+  /** Run a subagent and return its final assistant text. */
+  agent(prompt: string, opts?: AgentOptions): Promise<string>;
+  /** Run every thunk concurrently and wait for all (a barrier). */
+  parallel<T>(thunks: Array<() => Promise<T>>): Promise<T[]>;
+  /** Run each item through all stages independently — no barrier between stages. */
+  pipeline(
+    items: unknown[],
+    ...stages: Array<(prev: unknown, item: unknown, index: number) => Promise<unknown>>
+  ): Promise<unknown[]>;
+  /** Start a new phase; subsequent agents group under it in the progress tree. */
+  phase(title: string): void;
+  /** Emit a progress line. */
+  log(message: string): void;
+  /** Raw argument string passed after the workflow name. */
+  args: string;
+  /** Abort signal for the run, propagated from the host. */
+  signal: AbortSignal | undefined;
+}
+
+export type WorkflowRun = (api: WorkflowApi) => Promise<unknown>;
+
+export interface WorkflowModule {
+  meta: WorkflowMeta;
+  default: WorkflowRun;
+}

package/src/workflows.ts

@@ -0,0 +1,14 @@
+import type { WorkflowModule } from "./types.ts";
+import * as codeReview from "../workflows/code-review.ts";
+import * as ping from "../workflows/ping.ts";
+
+/**
+ * Workflows statically imported by the extension. These are loaded through pi's own
+ * jiti instance (because they're part of the extension's module graph), so they share
+ * pi's bundled `typebox` / SDK — guaranteeing schema validation works.
+ *
+ * To add a guaranteed workflow: drop a `.ts` in `workflows/`, import it here, and add
+ * it to this array. (Drop-in workflows discovered at runtime are also supported — see
+ * discovery.ts — but the static registry is the always-correct path.)
+ */
+export const BUILTIN_WORKFLOWS: WorkflowModule[] = [codeReview, ping];

package/workflows/code-review.ts

@@ -0,0 +1,185 @@
+import { Type } from "typebox";
+import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
+
+export const meta: WorkflowMeta = {
+  name: "code-review",
+  description: "Fan-out review of the branch's open PR (or branch vs main): scope → per-angle find → independent verify → synthesize.",
+  phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Synthesize" }],
+};
+
+// ─── Schemas (the contracts that make orchestration plain code) ───
+const ScopeSchema = Type.Object({
+  diffCommand: Type.String({ description: "Exact git command that produces the review diff" }),
+  files: Type.Array(Type.String(), { description: "Changed file paths" }),
+  summary: Type.String({ description: "One-paragraph summary of the change" }),
+  conventions: Type.Optional(Type.String({ description: "Relevant CLAUDE.md / project conventions" })),
+});
+
+const CandidatesSchema = Type.Object({
+  candidates: Type.Array(
+    Type.Object({
+      file: Type.String(),
+      line: Type.Optional(Type.Number()),
+      summary: Type.String({ description: "One-line description of the issue" }),
+      failure_scenario: Type.String({ description: "Concrete scenario where this causes a problem" }),
+    }),
+  ),
+});
+
+const VerdictSchema = Type.Object({
+  verdict: Type.Union([Type.Literal("CONFIRMED"), Type.Literal("PLAUSIBLE"), Type.Literal("REFUTED")]),
+  evidence: Type.String({ description: "Quote or cite the relevant line(s)" }),
+});
+
+const ReportSchema = Type.Object({
+  summary: Type.String(),
+  findings: Type.Array(
+    Type.Object({
+      file: Type.String(),
+      line: Type.Optional(Type.Number()),
+      severity: Type.Union([Type.Literal("bug"), Type.Literal("cleanup")]),
+      verdict: Type.Union([Type.Literal("CONFIRMED"), Type.Literal("PLAUSIBLE")]),
+      summary: Type.String(),
+    }),
+  ),
+});
+
+interface Candidate {
+  file: string;
+  line?: number;
+  summary: string;
+  failure_scenario: string;
+}
+interface Angle {
+  label: string;
+  kind: "bug" | "cleanup";
+  text: string;
+}
+interface Verified extends Candidate {
+  verdict: "CONFIRMED" | "PLAUSIBLE" | "REFUTED";
+  evidence: string;
+  kind: "bug" | "cleanup";
+}
+
+// The review lenses — this is the part you customise to your codebase's real failure modes.
+const ANGLES: Angle[] = [
+  { label: "logic-bugs", kind: "bug", text: "Off-by-one errors, wrong conditionals, incorrect return values, broken control flow." },
+  { label: "error-paths", kind: "bug", text: "Unhandled errors, swallowed exceptions, missing awaits, partial failure leaving inconsistent state." },
+  { label: "edge-cases", kind: "bug", text: "Empty/null inputs, boundary values, concurrency races, resource leaks." },
+  { label: "simplification", kind: "cleanup", text: "Dead code, needless complexity, duplicated logic, clearer equivalents." },
+  { label: "conventions", kind: "cleanup", text: "Violations of the project conventions noted in scope (naming, idioms, banned patterns)." },
+];
+
+const TOOLS = ["read", "bash"];
+const PER_ANGLE = 6;
+
+export default async function run(api: WorkflowApi): Promise<unknown> {
+  const { agent, parallel, pipeline, phase, log, args } = api;
+  const target = args.trim();
+
+  // ─── Phase 0: Scope ───
+  phase("Scope");
+  const scope = await agent(
+    "Establish the scope of a code review.\n" +
+      (target
+        ? `Target / instructions (verbatim): "${target}". If it names a PR number, branch, ref range, or files, build the matching diff command (use 'gh pr diff <number>' for a PR). Otherwise use the default selection below.\n`
+        : "No explicit target — select the diff to review using the default below.\n") +
+      "Default selection — run commands to decide, falling through until you get a NON-EMPTY diff:\n" +
+      "1. Get the current branch: `git branch --show-current`.\n" +
+      "2. Check for an OPEN GitHub PR for this branch: `gh pr list --head <branch> --state open --json number,title`. " +
+      "If one exists, the diff command is `gh pr diff <number>` — note the PR number and title in the summary.\n" +
+      "3. If there is no open PR (or `gh` is unavailable / there is no GitHub remote), diff the branch against its base: " +
+      "prefer `git diff main...HEAD`, then `git diff master...HEAD`, then `git diff HEAD~1`. " +
+      "If the branch itself is main/master, use `git diff HEAD~1`.\n" +
+      "4. Run the chosen command to confirm the diff is non-empty.\n\n" +
+      "Then: list the changed files, summarize the change in one paragraph (mention the PR if one was found), " +
+      "and read any relevant CLAUDE.md noting conventions a reviewer should know.\n" +
+      "Return diffCommand exactly as a reviewer should run it. Structured output only.",
+    { phase: "Scope", label: "scope", tools: TOOLS, thinkingLevel: "medium", schema: ScopeSchema },
+  );
+
+  if (!scope || scope.files.length === 0) {
+    return { summary: "No changes found to review.", findings: [], stats: { candidates: 0, verified: 0 } };
+  }
+  log(`${scope.files.length} changed files`);
+
+  const scopeBlock =
+    `## Diff command\n${scope.diffCommand}\n\n## Changed files\n${scope.files.map((file) => `- ${file}`).join("\n")}\n\n` +
+    `## Summary\n${scope.summary}\n\n## Conventions\n${scope.conventions ?? "(none noted)"}\n` +
+    (target ? `\n## User instructions (verbatim)\n${target}\n` : "");
+
+  // Dedup state accumulates as finders complete (the pipeline has no barrier).
+  const seen = new Set<string>();
+  const dedupKey = (candidate: Candidate): string =>
+    `${candidate.file}:${candidate.line != null ? Math.round(candidate.line / 5) * 5 : candidate.summary.slice(0, 40).toLowerCase()}`;
+
+  // ─── Find → dedup → Verify (no barrier between stages) ───
+  phase("Find");
+  const perAngle = await pipeline(
+    ANGLES,
+    // Stage 1: each angle finds candidates through its single lens.
+    async (_prev, item) => {
+      const angle = item as Angle;
+      const found = await agent(
+        `## Code-review finder — ${angle.label}\n\n${scopeBlock}\n` +
+          `Run the diff command and review ONLY through this lens:\n${angle.text}\n` +
+          `Surface up to ${PER_ANGLE} candidates, each with file, line, a one-line summary, and a concrete failure_scenario. ` +
+          "Pass through anything with a nameable failure scenario — a separate verifier judges them next. Structured output only.",
+        { phase: "Find", label: `find:${angle.label}`, tools: TOOLS, thinkingLevel: "low", schema: CandidatesSchema },
+      );
+      return { angle, candidates: (found?.candidates ?? []).slice(0, PER_ANGLE) };
+    },
+    // Stage 2: dedup against the shared set, then verify survivors concurrently.
+    async (prev) => {
+      const { angle, candidates } = prev as { angle: Angle; candidates: Candidate[] };
+      const novel = candidates.filter((candidate) => {
+        const key = dedupKey(candidate);
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+      });
+      const verdicts = await parallel(
+        novel.map((candidate) => async (): Promise<Verified | null> => {
+          const judged = await agent(
+            `## Code-review verifier\n\n${scopeBlock}\n## Candidate\n` +
+              `File: ${candidate.file}${candidate.line != null ? `:${candidate.line}` : ""}\n` +
+              `Summary: ${candidate.summary}\nFailure scenario: ${candidate.failure_scenario}\n\n` +
+              "Run the diff command, read the relevant file(s), and return exactly one verdict (CONFIRMED / PLAUSIBLE / REFUTED) " +
+              "with evidence quoting the line(s). Default toward REFUTED if you cannot substantiate it. Structured output only.",
+            { phase: "Verify", label: `verify:${candidate.file.split("/").pop() ?? candidate.file}`, tools: TOOLS, thinkingLevel: "low", schema: VerdictSchema },
+          );
+          return judged ? { ...candidate, verdict: judged.verdict, evidence: judged.evidence, kind: angle.kind } : null;
+        }),
+      );
+      return verdicts.filter((value): value is Verified => value !== null);
+    },
+  );
+
+  const verified = (perAngle as Verified[][]).flat();
+  const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
+  log(`${verified.length} verified → ${surviving.length} kept`);
+
+  if (surviving.length === 0) {
+    return { summary: "No findings survived verification.", findings: [], stats: { candidates: seen.size, verified: verified.length } };
+  }
+
+  // ─── Synthesize: rank, merge, report ───
+  phase("Synthesize");
+  const rank = (finding: Verified): number => (finding.kind === "cleanup" ? 2 : 0) + (finding.verdict === "PLAUSIBLE" ? 1 : 0);
+  const ranked = [...surviving].sort((a, b) => rank(a) - rank(b));
+  const block = ranked
+    .map(
+      (finding, index) =>
+        `### [${index}] ${finding.file}${finding.line != null ? `:${finding.line}` : ""} (${finding.verdict}${finding.kind === "cleanup" ? ", cleanup" : ""})\n` +
+        `${finding.summary}\nFailure: ${finding.failure_scenario}\nEvidence: ${finding.evidence}`,
+    )
+    .join("\n\n");
+
+  const report = await agent(
+    `## Synthesis: final code-review report\n\n${ranked.length} findings survived independent verification.\n\n${block}\n\n` +
+      "Merge findings with the same root cause, rank most-severe first (correctness bugs above cleanups), and produce the final report. Structured output only.",
+    { phase: "Synthesize", label: "synthesize", thinkingLevel: "medium", schema: ReportSchema },
+  );
+
+  return report ?? { summary: "Synthesis produced no output.", findings: [] };
+}

package/workflows/ping.ts

@@ -0,0 +1,28 @@
+import { Type } from "typebox";
+import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
+
+/** Minimal engine smoke test: a single structured-output agent call. Fast + cheap. */
+export const meta: WorkflowMeta = {
+  name: "ping",
+  description: "Engine smoke test — one structured agent call, no tools.",
+  phases: [{ title: "Ping" }],
+};
+
+export default async function run(api: WorkflowApi): Promise<unknown> {
+  const { agent, phase, log } = api;
+  phase("Ping");
+  log("calling one structured agent");
+  const result = await agent(
+    "You are a code-review workflow engine. Return a one-word headline and a one-sentence summary of what you do.",
+    {
+      phase: "Ping",
+      label: "ping",
+      tools: [],
+      schema: Type.Object({
+        headline: Type.String({ description: "One word" }),
+        summary: Type.String({ description: "One sentence" }),
+      }),
+    },
+  );
+  return result ?? { headline: "none", summary: "no structured answer returned" };
+}