@crooycom/pi-workflows

Generic workflow engine for coding agents — runs a JS workflow script that fans work out to subagents through an injected agent runner. Stripped fork of @quintinshaw/pi-dynamic-workflows 3.14.0: roles, model tiers, commands, TUI and builtin workflows remo

Packages

Package details

package

Install @crooycom/pi-workflows from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:@crooycom/pi-workflows
Package
@crooycom/pi-workflows
Version
0.6.0
Published
Nov 22, 2026
Downloads
869/mo · 869/wk
Author
crooycom
License
MIT
Types
package
Size
1.4 MB
Dependencies
4 dependencies · 3 peers

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-workflow-script

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

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 script 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, node, 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. In a pi session, load the exported tools yourself: createWorkflowTool and createWorkflowControlTool from the package root. The package registers nothing on load.

Compose scripts as nodes

A script can call another script as a node. The child declares what it accepts and what it finishes with in meta; the parent passes inputs by path:

// draft.js
import "pi-workflows/register"

const meta = {
  name: "draft",
  description: "write a draft about a topic",
  inputs: {
    topic: { type: "string" },
    tone: { type: "string", optional: true, default: "neutral" },
  },
  output: { draft: { type: "string" } },
}

const draft = await agent(`write a ${args.tone} draft about ${args.topic}`)
finish({ draft })
// post.js
import "pi-workflows/register"

const made = await node("./draft.js", { topic: "otters" })
finish(made)

The path resolves from the calling script's file. Both sides are validated, and a changed input or a changed child re-runs exactly that node on resume.

CLI

The package ships a pi-workflows bin:

pi-workflows run hello.js                # the include line is optional here
pi-workflows runs                        # list this project's runs
pi-workflows show <id>                   # inspect one run (--json for the raw record)
pi-workflows resume <id>                 # continue a journaled run; no file needed
pi-workflows inbox [--all]               # open questions from parked runs (--all: every project)
pi-workflows answer <qid> --option 1     # answer a parked question (interactive on a TTY)
pi-workflows clean --older-than 7d --yes # delete terminal runs
pi-workflows skill                       # print the authoring guide for agents

run accepts scripts with or without the import "pi-workflows/register" line; node hello.js with the include keeps working unchanged. runs, show, inbox, and clean scope to the current project (the cwd the run started in). show prints a Nodes section for node calls; pi-workflows show <id> --json carries them in a nodes array. A script can pause for input with askUser({ prompt, options }): the run parks, the question lands in the inbox, and answer + resume continue it — headless-friendly, see docs/adr/0003-ask-user-questions.md. After global install use npx @crooycom/pi-workflows. Decision record: docs/adr/0002-cli-returns.md.

Install

npm install @crooycom/pi-workflows

The package is a library. It ships no pi extension and adds no tools on load.

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. Runtime dependencies: acorn (script parsing), effect (the engine core is Effect-first — see docs/adr/0004-effect-native-core.md), tsx (CLI dev entry), and @earendil-works/pi-durable (opt-in durable spine). Effect-family packages are pinned exactly: effect and @effect/vitest at 4.1.5 (no caret range).

Development

npm install
npm run check   # tsc --noEmit, strict — must stay at 0 errors
npm run lint    # eslint, typescript-eslint type-checked
npm run spec    # behavioral given/when/then specs (live ones need SPEC_LIVE=1)
npm run vitest  # @effect/vitest unit specs
npm run smoke   # end-to-end run with a fake agent runner (no model calls)
npm test        # check + lint + spec + vitest + smoke
npm run build   # standalone compile to dist/

Coding standards live in docs/standards.md.

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.

Child sessions load no host extensions unless explicitly opted in: the childExtensions option names individual extensions, each of which loads by explicit path; skills resolve from the workspace only. The old option name providerMiddlewareExtensions still works this release as a deprecated alias.

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.