Workflows as plain JavaScript files for the pi coding agent
README.md

pi-workflow-script #

Site: site/index.html · Explainer: site/explainer.html · Repo: https://tangled.org/crooy.tngl.sh/pi-workflow-script

A generic workflow engine for coding agents — forked and stripped from @quintinshaw/pi-dynamic-workflows 3.14.0 (MIT). It executes a JavaScript workflow script that delegates work to subagents via an injected agent runner, and almost nothing else: no opinions about what work to run. Who runs the work is pluggable — the shipped default runner speaks pi, and a host can inject its own. Roles, builtin workflows, model tiers, commands, TUI and authoring tooling were all removed in the strip (29 of 55 modules) — supply them as data.

Provenance and strip history: see FORK.md. This repo is the only known home of the 3.14.0 sources.

The script contract #

A workflow is a plain JavaScript file. It starts with import "pi-workflows/register", and ends by handing its result to finish():

import "pi-workflows/register"

const meta = { name: "my_flow", description: "what this does" }   // optional

const draft = await agent("write a draft about X")
const review = await agent("review this: " + draft, { model: "provider/model" })
const both = await parallel([
  () => agent("check A with " + review),
  () => agent("check B with " + review),
])
finish({ draft, review, both })

Run it with node my_flow.js. The import launches the engine: it validates the file, journals the run, prints meta/result/token usage, and exits 0 or 1. Resume a stopped run with node my_flow.js --resume <id>. Scripts embedded via WorkflowManager (in-session, tests) keep the classic shape: first statement export const meta = …, result as a top-level return.

Script globals injected by the engine: agent, parallel, pipeline, workflow, verify, judgePanel, judgedLoop, completenessCheck, retry, gate, checkpoint, log, phase, pick, finish, args, cwd, process, budget, console. Execution runs in a node:vm realm with a determinism prelude — host built-ins (Date.now(), Math.random(), imports, fs) are deliberately unavailable. The value handed to finish(result) becomes the run result — a top-level return still works for engine-embedded scripts.

agent() options (data, per call): model, thinking, label, phase, schema (structured output), tools/disallowedToolNames allow/deny, skills (forced skill load), isolation (git worktree), cwd, thread, timeoutMs, retries.

Quickstart #

  1. Save a small workflow file, for example hello.js, in your project:
import "pi-workflows/register"

const meta = { name: "hello", description: "smallest possible run" }

const answer = await agent("Reply with one fun fact about the number 42.")
finish({ answer })
  1. Run it: node hello.js. The engine journals the agent call, prints the result, and exits 0.
  2. Or run it from a pi session: tell pi run the workflow in hello.js — the workflow tool passes the script to the same engine and the answer comes back into the conversation.

Usage #

Install #

The engine loads as a pi extension. Keep this repo on disk, install its dependencies once, and point a wrapper entry at src/pi-extension.ts:

git clone https://tangled.org/crooy.tngl.sh/pi-workflow-script
cd pi-workflow-script
npm install
// ~/.pi/agent/extensions/pi-workflow-script.ts
// point the import at your clone location
import workflowExtension from "~/pi-workflow-script/src/pi-extension.ts";
export default workflowExtension;

Pi reads the entry on every start and registers the workflow and workflow_control tools for the session.

import { WorkflowManager } from "./src/index.ts";

const manager = new WorkflowManager({
  cwd: "/path/to/project",
  agent: myAgentRunner, // (prompt, options) => Promise<unknown> — YOU provide this
});

const result = await manager.runSync(script, args);
// result.meta, result.result, result.agentCount, result.tokenUsage, ...

WorkflowManagerOptions.agent is the integration seam: the engine never calls a model itself — the embedding host supplies the runner. Persistence (run-persistence + run-record-store) journals each call under ~/.pi/workflow-script/projects/<cwd-hash>/runs/ so runs can resume from their journal (resumeFromRunId). For a durable spine (crash-safe tasks, resumable conversations) see the sibling pi-factory framework. It wraps this engine in pi-durable, but the engine itself does not depend on it — its only runtime dependency is acorn.

Development #

npm install
npm run check   # tsc --noEmit, strict — must stay at 0 errors
npm run smoke   # end-to-end run with a fake agent runner (no model calls)
npm test        # both

Note: this repo ships compiled dist/ for installs. npm install and every git install run prepare, which builds dist/ from src/ with npm run build. Run tests against src/ via tsx; installed copies run plain node against dist/.

The runner seam #

The engine never calls a model itself. The host injects one runner. One call runs one agent job: (prompt, options) => Promise<unknown>.

import { WorkflowManager } from "./src/index.ts";

const manager = new WorkflowManager({
  cwd: process.cwd(),
  agent: { run: async (prompt) => myRunner(prompt) },
});

const result = await manager.runSync(script, args);

pi-workflows ships one runner. It spawns one pi --print --no-session child per job. Any other host swaps its own runner in here.

What was stripped #

Builtin workflows (code-review, deep-research, adversarial-review), agent-type registry/roles, model tiers, all slash commands, saved-workflow storage, usage-limit scheduler, web tools, TUI (task panel, navigator, progress widgets), authoring/ comprehension/ release-gate tooling, and the capability-contract's authoring diagnostics (its runtime-binding table lives on inside workflow.ts). Removed features fail loudly: agentType throws SCRIPT_VALIDATION_ERROR.

License #

MIT — © QuintinShaw / Michael Livs, see LICENSE.