@tylerho/pi-workflows

Sandboxed multi-agent workflow orchestration, plus a deterministic multi-angle code review built on it.

Install

pi install npm:@tylerho/pi-workflows

---

Workflows

Model-authored multi-agent orchestration for pi. The workflow tool runs an inline JavaScript orchestration script in a restricted, killable child process, and each agent() call in that script becomes one isolated child AgentSession. Runs background by default, return a run id immediately, and deliver a follow-up message when they settle. Artifacts land in ~/.pi/agent/workflows/<runId>/, and resumeFromRunId replays the unchanged prefix of agent() calls from that run's journal.

How it works

The script holds the structure. Fan-out, verification, and synthesis live in plain JavaScript (map, filter, if, await) instead of model decisions. The tool description gates calls on explicit user opt-in: the keyword ultracode, a direct request to run a workflow or fan out agents, or a skill or slash command that says to call it. For any other task, the agent describes what a workflow could do and asks first.

Execution passes through three layers.

1. prepareWorkflowScript (meta.ts) parses the source with acorn and statically decodes export const meta = {...}. Only plain object, array, and primitive literals pass, so calls, spreads, computed keys, and templates fail closed. The metadata bytes are then blanked out of the source with the line count preserved, so nothing executable survives.
2. runWorkflowSandbox (sandbox.ts) spawns a Node child with --permission (fs-read of the worker directory only, --max-old-space-size=128, --stack-size=2048) and runs the script inside a vm context with codeGeneration: { strings: false, wasm: false }. The child has no imports, eval, timers, filesystem, network, or process APIs, and process, require, and fetch are undefined. It talks to the host only over an authenticated IPC channel, with a token of 24 random bytes and validation of every message. The body compiles as (async function __piWorkflowBody() { ... })() with agent, parallel, pipeline, phase, log, budget, workflow, and args as parameters.
3. RunController (controller.ts) owns the run-wide semaphore, the agent-call cap, and the abort signal. Each agent() resolves through runAgent (runner.ts), which creates a fresh in-process AgentSession with SessionManager.inMemory, binds child-session extensions, and denies recursive orchestration tools.

Determinism is required because resume depends on it. Math.random(), Date.now(), and a bare new Date() throw inside the script, so a replayed call produces the same prompt. Vary work by index and pass timestamps through args. The sandbox also rejects non-yielding synchronous code through the vm timeout, unawaited agent() calls (Workflow created N unawaited agent() call(s)), and a return before in-flight agents settle.

pipeline() is the default and holds no barrier. Items flow through stages independently, and each stage callback receives (prevResult, originalItem, index). Wall-clock equals the slowest single-item chain, not the sum of stage maxima. parallel() is a barrier that awaits every thunk before returning, so it fits only a genuine cross-item dependency such as dedup before expensive downstream work or an early exit on zero findings. A throwing stage or thunk drops that item to null, and a pipeline failure also logs pipeline[index] failed: <msg>.

agent() selects a delegation tier: fast for bounded mechanical work or lookups, standard for normal coding, research, and review (the default when omitted), and deep for uncertain, cross-cutting, architectural, or adversarial work. resolveDelegationTarget() in shared/subagent-models.ts maps the tier through the user's map in extensions/shared/subagent-models.json, set with /subagent-model, to a pi provider, model, and effort. An unavailable target fails the agent with a direct error. tier cannot be combined with model, provider, or effort. The runner passes supportedHarnesses: ["pi"], so the claude tier fails rather than running another target. A tier's effort replaces the inherited parent thinking level, and tiered agents render as tier→resolved-id. Resolution happens when agent() is called, before a concurrency slot is taken, so a queued agent already records the model it will run, and a call that fails to resolve records no model at all rather than the parent session's.

model, provider, and effort remain for a user-requested override and bypass tiers. An override defaults to the configured subagent model (loadSubagentModels().pi), not the parent session model, so fan-out does not burn an expensive interactive model. model-aliases.ts resolves the model option in a chain: an exact provider/id or bare registry id, then modelAliases from workflows.json, then a known CC alias with no mapping (haiku, sonnet, opus, fable) falling back to the configured default. Exact hits pass a cost ceiling check, where exceedsCostCeiling rejects an agent-picked expensive model and affordableModels supplies alternatives. Alias-resolved models skip the ceiling because the user configured them. A broken alias target fails with a fix modelAliases error. Agents record requestedModel and render as alias→resolved-id. effort sets a thinking level (off, minimal, low, medium, high, xhigh, max), and omitting it inherits the parent level from pi.getThinkingLevel().

Run-wide caps: concurrency is DEFAULT_CONCURRENCY = min(16, max(2, cores - 2)), which is CC's formula. Total agent calls are capped at MAX_AGENT_CALLS 1000, and past it agent() resolves null. parallel() and pipeline() accept at most 4096 items and throw beyond that rather than truncating. budgetTokens, or the /workflows-budget default, sets a hard output-token ceiling. Once spent() reaches total, the next agent() throws WorkflowBudgetExceededError inside the script while in-flight agents finish. An unset budget never blocks and budget.remaining() returns Infinity.

Every settled agent() appends one line to journal.jsonl with { index, key, label, phase?, result }. key is the sha256 of canonical JSON over { prompt, options } with sorted keys, truncated to 32 hex, so option order does not matter. createResumePlan replays the longest unchanged prefix. The first mismatch, whether a different key, a missing entry, or an out-of-order index, ends replay for the rest of the run. Matched calls return cached results instantly and mark cached: true.

background defaults to true, and (params.background ?? true) && ctx.hasUI forces it off in a headless session, where there is no UI to deliver the follow-up to. A background run returns a launch message immediately and delivers the completion follow-up as a workflow-completion custom message through pi.sendMessage(..., { deliverAs: "followUp", triggerTurn: true }). The model-facing content is unchanged ([Background workflow <runId> <status>] plus the full report), and the registered renderer paints a digest instead of the report. A blocking run emits tool-block progress throttled at 120 ms and throws on a non-completed status, which is how pi marks the tool failure. session_shutdown aborts and settles every active run.

The live rail. A belowEditor widget (workflow-task-rail) shows the active runs. A header carries the running and finished counts, and each row carries the run name, the current phase, the settled and total agent counts, and the elapsed time. The rail renders at most 8 rows and collapses the rest into a … N more line. It re-reads the active-runs map on every render, so details that mutate in place (currentPhase, the growing agents array) stay current. A 1 Hz tick repaints the elapsed times while a run is live, and updateIndicator() repaints immediately on a launch or settle. The widget hides while nothing runs, and it has no key handling.

Each agent runs with normal trust-aware resources (createWorkflowResources calls createChildResources in shared/child-session.ts), the same childToolPolicy() denylist subagents use, and an optional one-shot structured_output tool when the script passes schema. The denylist covers subagent_spawn, subagent_wait, subagent_cancel, subagent_check, subagent_list, workflow, ask_user_question, enter_worktree, exit_worktree, and code_review. A schema must be a bounded JSON object of at most 10,000 nodes and depth 24, with no __proto__, constructor, or prototype keys, and it wraps through Type.Unsafe so every JSON Schema keyword survives. Children receive WORKFLOW_AGENT_SYSTEM_INSTRUCTION or STRUCTURED_OUTPUT_SYSTEM_INSTRUCTION. isolation: 'worktree' runs one agent in a fresh detached git worktree on branch wf/<runId>/<agentIndex>-<slug>, removes it when the agent left it unchanged, and keeps it while logging the path and changed-file count when it did not.

Watchdogs in runner.ts bound each agent. The first assistant response event must arrive within FIRST_RESPONSE_TIMEOUT_MS 45 s, or a silent provider request aborts. Mid-run progress must arrive within STALL_TIMEOUT_MS 180 s, and the watchdog suspends while a tool executes because the per-tool guard bounds that. Each child tool call is limited by CHILD_TOOL_CALL_TIMEOUT_MS 30 min in shared/tool-call-timeout.ts. Structured output gets MAX_STRUCTURED_OUTPUT_ATTEMPTS 5 attempts before the agent aborts. runAgent never throws and settles every failure mode into AgentOutcome { ok, output, structured?, error?, aborted, usage, model, contextWindow, transcript }, with output truncated to 64 KiB.

artifacts.ts coalesces live state to disk every WORKFLOW_CHECKPOINT_INTERVAL_MS 500 ms, runs checkpoint({ immediate: true }) on agent settle, and flushes synchronously at the end. Every write goes through writeFileAtomic, which writes a temp file and renames it.

API

Tool: workflow

index.ts registers the tool through pi.registerTool({ name: "workflow", ... }). The description, snippet, and guidelines come from WORKFLOW_TOOL_DESCRIPTION, WORKFLOW_PROMPT_SNIPPET, and WORKFLOW_PROMPT_GUIDELINES (prompt.ts), and the description appends the saved-workflow registry from describeSavedWorkflows(process.cwd()).

Parameters (typebox WorkflowParams, all optional):

Name	Type	Meaning
script	string	Inline JS orchestration script. Required unless name is given.
name	string	Name of a saved workflow to run instead. Passing script too overrides the saved definition for one run.
args	string	Optional JSON string exposed to the script as args. Parsed when valid JSON, otherwise passed through as the raw string.
background	boolean	Default true: return the run id immediately and deliver a follow-up on completion. false blocks with live progress in the tool block.
resumeFromRunId	string	wf_ plus 12 hex. Replays the unchanged agent() prefix from that run's journal. An invalid id is rejected.
budgetTokens	number	Output-token ceiling for this run. Floored, and a value of 0 or less falls back to the /workflows-budget default.

Return shape:

• Background: { content: [{ type: "text", text: launch message }], details: compact WorkflowDetails } immediately, with empty agent transcripts and the result capped at 64 KiB. The completion follow-up carries the full report.
• Blocking: the same shape after completion, and a throw of Error(buildWorkflowResultMessage(...)) when the status is not completed.
• Errors: an unknown name (the message lists available names), an unparseable script, and an invalid resumeFromRunId.

renderCall extracts metadata through extractMeta and shows the phases. renderResult draws a state square per agent, a phase-grouped expanded view, status colors from statusColor and stateSquare, and an expand hint from keyHint("app.tools.expand").

Script API

A script may start with export const meta = { name?, description?, whenToUse?, phases: [{ title, detail? }] }. The phases drive the progress UI, the registry, and the /workflows display. The body then has these globals, all read-only bindings.

Global	Behavior
agent(prompt, options?)	await agent(prompt, { label?, phase?, schema?, tier?, model?, provider?, effort?, isolation? }) resolves to the final text as a string, the validated object when schema is given, or null on failure. It throws WorkflowBudgetExceededError on budget exhaustion and returns null when the call cap or an abort rejects it, so callers filter with .filter(Boolean). Reason strings live on the run record, not in the value.
pipeline(items, stage1, stage2, ...)	No barrier between stages. Each stage receives (prevResult, originalItem, index). A throwing stage drops that item to null and skips its remaining stages. At most 4096 items.
parallel(thunks, { concurrency? })	Barrier. Zero-argument thunks, and a throwing thunk resolves to null rather than rejecting. Concurrency defaults to the run-wide cap. At most 4096 items. Results come back in order.
phase(title)	Marks the current phase for progress and grouping. Titles are capped at 160 characters.
log(message)	Emits a progress line, capped at 500 characters, which the completion report replays.
workflow(name, args?)	Runs a saved workflow inline as a sub-step and returns its result. The child shares this run's concurrency cap, agent counter, abort signal, and budget. One level only, because nesting throws. An unknown name or a child syntax error throws.
budget	{ total: number | null, spent(): number, remaining(): number }, refreshed by the host after every settled agent.
args	The parsed args tool parameter, deep-frozen, or undefined.

Every agent() call must be awaited, and the script must return a JSON-serializable aggregate. Bigint becomes "<n>n", a cycle becomes "[circular]", and undefined becomes null. Imports, export default, eval, timers, process, and network access are unavailable.

Commands

Command	Purpose
/workflows-budget	Shows the current default with no argument. Otherwise accepts 500k, 1.5m, off, none, unlimited, or a plain token count. The three words all mean unlimited. Persists to workflow-budget.json through parseBudget, saveDefaultBudget, and loadDefaultBudget.
/workflows	Opens the full-screen dashboard in the TUI: a run list, a per-run detail with a phases sidebar and an agents panel, then a per-agent transcript. j and k move, g and G jump, l, right, and enter descend, h, left, and esc ascend, and s writes report.md into the run directory. The view refreshes every 500 ms while a run is live, and opening it acknowledges finished runs and resets the footer counters. An optional runId argument opens that run directly, matched exactly or by a trailing segment of the id. Outside the TUI it prints a plain listing or offers a ctx.ui.select picker.

Messages and renderers

custom type	delivery	renderer
workflow-completion	{ deliverAs: "followUp", triggerTurn: true }, visible	renderWorkflowCompletion

The model-facing content stays the completion report. The renderer reads details (runId, name, status, elapsed, agents, currentPhase, artifactsDir), so the transcript never paints the report verbatim. Collapsed shows the digest (✦ workflow <name> · <status> · N agents · <elapsed>) plus the /workflows <runId> pointer. Expanded shows the report capped at 4000 characters and a pointer to the run directory, where result.json and report.md live. The dashboard s key writes report.md.

Events

Event	Handler
session_start	Captures lastUi = ctx.ui when ctx.hasUI, mounts the rail widget, and refreshes the indicator.
session_shutdown	Aborts every active run with Session is shutting down, settles each with abort: true, waits up to 8 s for completions, and clears the workflows footer status and the rail widget.

updateIndicator() publishes reportRunning("workflows", activeRuns.size) to shared/agent-activity.ts, which summaries gates recaps on, and, when a UI exists, sets the workflows footer status through formatActivityStatus(theme, "workflows", { running, done, failed }). Finished-run counters stay visible until the dashboard acknowledges them.

Config files and artifacts

Path	Contents
workflow-budget.json	In the agent directory from getAgentDir(). { "tokens": number | null }, written by /workflows-budget.
<agent dir>/workflows/*.js	User-level saved workflow definitions.
<cwd>/.pi/workflows/*.js	Project-level saved definitions, which shadow user ones of the same name.
workflows.json	In the agent directory. { "extraDirs": ["~/.claude/workflows"], "modelAliases": { "sonnet": "deepseek/deepseek-v4-pro" } }. loadRegistrySettings() re-reads it on every registry scan and every agent model resolution, so edits take effect immediately.
~/.pi/agent/workflows/<runId>/	Run artifacts.

A saved definition is a .js file with a meta.name and meta.description, at most 512 KiB, and an optional meta.whenToUse that shows in the registry listing. Precedence runs from extraDirs (array order, later entries winning) through the user directory to the project directory. Extra-dir entries render with [from <dir>] in the tool description, and a malformed definition is skipped rather than breaking the registry. Run artifacts live in wf_* subdirectories of the user workflow directory, so they never collide with definitions.

A run directory holds script.js, args.json when args were passed, workflow.json (compact details with the result replaced by a pointer to result.json and transcripts replaced by transcripts.json), result.json (at most 1 MiB), transcripts.json (per-agent bounded transcripts keyed by index, holding the initial prompt plus the newest tail inside 32 KiB), journal.jsonl, and report.md, which the dashboard s key writes.

Module exports

index.ts is the entry point, and its default export is workflows(pi: ExtensionAPI). No other extension imports these modules directly. index.ts registers the run lifecycle into shared/workflow-runtime.ts, and code-review drives it through that seam.

• launch.ts exports createLaunch(deps), a dependency-injected factory over the active-runs map, the indicator and settled-run callbacks, runAgent, createResources, and an injectable delegation-config loader. It parameterizes the core (spec.orchestrate(dsl), which is the sandbox script for the tool and an in-process engine for code-review) and delivery ("model-followup" for the background follow-up and the blocking throw, "programmatic" for a resolved settled with no follow-up). The returned launch matches WorkflowRuntime["launch"]. The internal spec and handle add the tool-only extras: resume plan, extra artifacts, blocking signal, and tool-block progress. It also exports errorText, compactToolDetails, and the types ActiveRun, InternalLaunchSpec, InternalRunHandle, and LaunchDeps. index.ts calls registerWorkflowRuntime({ launch }) on load.
• prompt.ts exports WORKFLOW_PARAMETER_DESCRIPTIONS, WORKFLOW_TOOL_DESCRIPTION, WORKFLOW_PROMPT_SNIPPET, WORKFLOW_PROMPT_GUIDELINES, buildWorkflowAgentPrompt, WORKFLOW_AGENT_SYSTEM_INSTRUCTION, STRUCTURED_OUTPUT_SYSTEM_INSTRUCTION, STRUCTURED_OUTPUT_TOOL_DESCRIPTION, buildWorkflowResultMessage, buildBackgroundWorkflowFollowUp, and buildBackgroundWorkflowLaunchResult.
• runner.ts exports runAgent, createWorkflowResources, guardWorkflowChildTools, recordToolExecutionTiming, transcriptFromMessages, createStallWatchdog, createFirstResponseWatchdog, the constants FIRST_RESPONSE_TIMEOUT_MS (45 s), STALL_TIMEOUT_MS (180 s), and MAX_STRUCTURED_OUTPUT_ATTEMPTS (5), and the types WorkflowModel, ThinkingLevel, AgentOutcome, AgentProgress, RunAgentOptions, and ToolExecutionTiming.
• controller.ts exports RunController with .signal, .calls, .schedule(task, invocationSignal?), .abort(reason?), and .settle({ abort?, timeoutMs? }), which seals the task registry and waits up to 8 s. Constants are DEFAULT_CONCURRENCY, MAX_AGENT_CALLS (1000), and RUN_SHUTDOWN_TIMEOUT_MS (8000).
• budget.ts exports WorkflowBudget (.add(), .spent(), .remaining(), .assertAvailable(), .view()), WorkflowBudgetExceededError, loadDefaultBudget, saveDefaultBudget, parseBudget, formatBudget, and the type BudgetView.
• journal.ts exports callKey(prompt, options), appendJournalEntry, readJournal, createResumePlan (.take(index, key) returns { hit: true, result } or undefined, plus .servedCount and .available), and JOURNAL_FILENAME.
• meta.ts exports prepareWorkflowScript (returns { source, meta }), extractMeta, which is cached and safe in render paths, and the types WorkflowMeta, WorkflowPhase, and PreparedWorkflowScript.
• model.ts exports WorkflowDetails, AgentRecord with tier and effort provenance, AgentUsage and emptyUsage, TranscriptEntry, the state and status helpers stateSquare, statusSquare, statusWord, statusColor, and SQUARE, the formatters formatElapsed, formatUsage, formatTokens, shortenHome, agentModelLabel, agentContext, aggregateUsage, countStates, phaseGroups, and resultJson, and the constants RESULT_JSON_MAX_BYTES and RESULT_JSON_MAX_LINES.
• artifacts.ts exports persistWorkflowJson, createWorkflowPersistence (.checkpoint({ immediate? }) and .flush()), boundedArtifactTranscript, and WORKFLOW_CHECKPOINT_INTERVAL_MS (500).
• sandbox.ts exports runWorkflowSandbox, which spawns the permission-restricted child and validates every IPC message, enforcing 512 KiB of source, 256 KiB of args, a 1 MiB result, and 1000 agent requests. Types are RunWorkflowSandboxOptions, SandboxAgentOptions, and SandboxAgentResult.
• sandbox-child.cjs is the worker runtime. It builds the vm context and the globals, forbids nondeterministic clocks, refreshes the budget through __setBudget, implements parallel and pipeline with MAX_FANOUT_ITEMS 4096, and runs the unawaited and in-flight checks.
• registry.ts exports listSavedWorkflows(cwd), collectSavedWorkflows(dirs), findSavedWorkflow(cwd, name), describeSavedWorkflows(cwd), loadRegistrySettings(), userWorkflowDir(), projectWorkflowDir(cwd), and the types SavedWorkflow and RegistrySettings.
• model-aliases.ts exports resolveModelOption(lookup, model, provider, aliases), which returns an exact, alias, default, or unknown resolution, CC_MODEL_ALIASES, and the types ModelLookup and ModelOptionResolution.
• worktree.ts exports isGitRepo(cwd) and createWorktree({ cwd, runId, agentIndex, label }), which returns { path, branch, release() } with release() giving { removed, changedFiles }.
• serialization.ts exports safeStringify, toSerializable, truncateUtf8, and writeFileAtomic. The whole extension uses these for artifact writes.
• dashboard.ts exports showWorkflowDashboard(ctx, getActive, initialRunId?), sessionWorkflowRunIds(ctx), loadRunEntries(...), the class WorkflowDashboard, and the type RunEntry.
• rail.ts exports MAX_RAIL_ROWS, workflowRailModel, renderWorkflowRail, createWorkflowRail, and the types WorkflowRailRow and WorkflowRailModel. The model and the line renderer are pure, so they unit-test over a fake active-runs map.
• completion.ts exports COMPLETION_REPORT_MAX_CHARS (4000), WorkflowCompletionDetails, buildWorkflowCompletionDetails, and renderWorkflowCompletion.
• prototype-scheduling/ is a throwaway prototype with a scheduler simulation and TUI, run through npm run prototype:scheduling. It answered the barrier-versus-pipeline question in July 2026 and motivated pipeline() and the CC concurrency formula. It is not part of the runtime surface.

Examples

1. Background fan-out over a file list, with a find phase and a verify phase.

export const meta = { name: 'audit', description: 'Find and verify bugs', phases: [{title:'Find'},{title:'Verify'}] }
const findings = await parallel(args.files.map(f => () => agent('Audit ' + f + ' for bugs', { phase: 'Find', schema: FINDINGS_SCHEMA })))
const confirmed = await parallel(findings.filter(Boolean).flatMap(r => r.bugs).map(b => () => agent('Adversarially verify: ' + b.title, { phase: 'Verify', schema: VERDICT_SCHEMA })))
return { confirmed: confirmed.filter(Boolean).filter(v => v.isReal) }

Called as workflow({ script, args: JSON.stringify({ files: ['src/runner.ts'] }), background: true, budgetTokens: 400000 }). The run id comes back immediately, the completion report arrives as a follow-up message, and /workflows shows live progress.

2. Resume after a failure. The result message of a failed run names the resume form, workflow({ script, resumeFromRunId: "wf_..." }). The agent edits the script and relaunches. Byte-identical (prompt, options) pairs replay from journal.jsonl instantly, and the first edited call and everything after it runs live.

3. A blocking run of a saved workflow. With ~/.pi/agent/workflows/review.js saved and a project copy at <cwd>/.pi/workflows/review.js shadowing it, workflow({ name: "review", args: '{"paths": ["src/"]}', background: false }) blocks with live tool-block progress and throws if the run fails. Inside a script, the same registry is reachable as await workflow("review", { paths: [...] }), at one nesting level, sharing the budget, caps, and abort signal.

4. A budget-scaled loop from WORKFLOW_TOOL_DESCRIPTION. The guard on budget.total keeps an unset budget, whose remaining() is Infinity, from running to the 1000-agent cap.

while (budget.total && budget.remaining() > 50_000) {
  const result = await agent('Find bugs.', { schema: BUGS_SCHEMA })
  bugs.push(...(result?.bugs ?? []))
  log(`${bugs.length} found, ${Math.round(budget.remaining()/1000)}k remaining`)
}