- TypeScript 82%
- HTML 18%
- JavaScript <1%
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 #
- 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 })
- Run it:
node hello.js. The engine journals the agent call, prints the result, and exits 0. - Or run it from a pi session: tell pi
run the workflow in hello.js— theworkflowtool 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.