@signalridge/pi-workflows

JavaScript orchestration over managed Pi subagents: fan-out, DAGs, phases, soft budgets, quality helpers and journal-backed resume. pi-subagents alone owns model/thinking, queue/concurrency, tools, skills, cwd, isolation, retries and child sessions.

Install

@signalridge/pi-workflows requires @signalridge/pi-subagents >=1.9.0 with protocol v4 managed-spawn, Agent-tier, and managed-policy support. They are separate Pi packages: the peer dependency documents the requirement but intentionally does not auto-load or duplicate the subagent extension.

pi install npm:@signalridge/pi-subagents
pi install npm:@signalridge/pi-workflows

Use from this checkout

From the repository root, load both local package directories once. Disable extension discovery so the npm-installed copies do not also load — an npm copy of one alongside a local checkout of the other loads both, and the duplicate registers its tools twice:

pi -ne -e ./packages/pi-subagents -e ./packages/pi-workflows

-ne skips the installed extension catalogue while keeping explicit -e paths; without it, first remove the installed copies (pi remove @signalridge/pi-subagents @signalridge/pi-workflows) or accept duplicate tool registration.

Pi activates each package from its own pi.extensions manifest.

Writing a workflow

A workflow script starts with the only legal export — a literal-only meta contract — and then runs inside an async function:

export const meta = {
  name: "example",
  description: "Fan out three checks and synthesize",
  phases: [{ title: "scan" }, { title: "synthesize" }],
};

phase("scan");
const findings = await parallel([
  () => agent("Check for cross-package imports", { label: "imports", strength: "low" }),
  () => agent("Check for secrets", { label: "secrets", strength: "low" }),
  () => agent("Check for dead code", { label: "dead-code", strength: "low" }),
]);

phase("synthesize");
const report = await agent("Summarize the findings: " + JSON.stringify(findings), {
  label: "report",
});
return report;

The meta statement must be the first statement and use only literals — spread, computed keys, methods, template interpolation, and the reserved keys __proto__/constructor/prototype are rejected. Date.now(), Math.random(), and no-argument new Date() are unavailable (an AST precheck plus in-realm stubs); prompt text containing those words remains valid. Pass timestamps and randomness through args. The vm is a determinism guardrail, not a security boundary — scripts are generated by the user's own LLM and run on the user's own machine.

Try /code-review for a built-in, then /workflows to inspect it. Bun/compiled hosts need node on PATH; inherited NODE_OPTIONS can affect startup. Execution and resource bounds.

Runtime globals

The shipped capability index owns signatures/options/defaults; runtime reference covers execution and soft-budget semantics. Budgets may overshoot with in-flight work; neither scripts nor the VM provide a security sandbox.

Tools and commands

• workflow: run a script (script) or a saved/built-in workflow (name), with args, background (default true), maxAgents (default 1000), concurrency (defaults to the host's pool size), agentRetries (default 0), tokenBudget (default unlimited), agentTimeoutMs (default 1800000; public tool input is numeric), and resumeFromRunId. The execution limits are tuned defaults: a caller that names one narrower than the script needs stops the run rather than shaping it.

  Live pi-subagents maxConcurrent owns the pool (stock 4); starts/resumes clamp to it and log clamps. Missing peer pool metadata falls back to 16. The timeout starts after leaving the host queue, not while waiting. The engine API accepts agentTimeoutMs: null to disable it; the public workflow tool schema does not.

• workflow_control: list, get, pause, resume, stop, or rm a run; rm writes a durable removal tombstone.

• pi.events emits pi-workflows:runtime snapshots ({ runId, event }) for phase, task, quality, retry, and nested-workflow progress; observer failures are contained.

• /workflows: TUI navigator plus run, status, watch, stop, pause, resume, rm, save <name> [runId], and strength subcommands.

• /workflows strength: [<low|medium|high> <tier>|off] — which Agent tier each workflow strength runs on, and the tiers this host defines. Unconfigured hosts start on a shipped default table (identity, where the host defines the name). The tiers themselves are still configured only in pi-subagents' /agents → Model tiers; there is deliberately no second tier configuration file.

• /effort and /ultracode: standing off|high|ultra effort guidance that auto-arms substantive messages.

• /workflows-progress: compact|detailed|status|max <N> controls the persisted live panel.

• /deep-research, /adversarial-review, /code-review, /multi-perspective, /codebase-audit: the five built-in workflows. A saved workflow with the same name takes precedence.

• /workflows-trigger: set <keyword>, off, or on. See keyword arming below.

• /<saved-name>: every saved workflow registers its own slash command at session_start (Pi cannot unregister commands, so registration happens there rather than at factory time, and existing commands are never overwritten).

Saved workflows use project scope before user fallback; names are path-safe and writes atomic.

Model routing

Scripts may name only strength: "low"|"medium"|"high", never tier, model or thinking. No strength means no requested tier; pi-subagents then uses the agent tier, configured default, or managed medium fallback. Explicit noDefaultTier rejects untiered managed calls.

{ "strengths": { "low": "cheap-search", "high": "deep" } }

/workflows strength
/workflows strength low cheap
/workflows strength low off

Global settings: <agent dir>/workflows/settings.json; project: <agent dir>/workflows/projects/<basename>-<sha256(cwd)[0:12]>/settings.json. Project overrides global. Commands write a full effective table to project scope; edit global by hand. Agent tiers/models remain solely in pi-subagents. If a host tier is literally named off, it wins over the clear keyword; remove the JSON mapping to unmap it. Routing is reread on every resume: moved strengths invalidate finished calls and everything after the first miss, causing re-spend (including automatic provider-limit retry). Stop paused work before editing if that is unwanted. Full routing/resume contract.

Live command center

/workflows or /workflows watch <runId> opens the run/phase/task/call inspector. Esc closes observation only; p pauses, r resumes, and stop needs explicit confirmation and is non-resumable. Outside TUI, watch reports a snapshot. One passive below-editor overview takes no empty-prompt arrow keys; Fleet owns independent agents. Update both packages together to avoid mixed-version duplicate panels. Retained exact-attempt child conversations remain owned by Subagents. Controls and navigation.

Background result notifications

workflow_control({ action: "get", run_id: "...", consume: true })

Only an acknowledged terminal result with consume: true consumes its execution's pending reminder; ordinary reads/list, running or cancelled/stale reads do not. notificationConsumed: true means active-branch acknowledgement, not history deletion or message retraction. Later resumes remain eligible. Overflow delivers context without a wake: run /compact (or /codex-compact) or start a new session. Delivery, ACK and hook-race limits.

Keyword arming

Standalone workflow/workflows in interactive/RPC input offers advisory permission, never compels execution or replaces tool permissions. “please run a workflow.” matches; myworkflow, workflow_name, WorkflowEngine, --workflow-id, src/workflow-editor.ts, workflow.ts, workflow.json and /workflows do not. /workflows-trigger set <word> matches that exact word (plural only for the default); off|on toggles it. /effort//ultracode off|high|ultra set standing guidance. Ambiguous/transformed input fails closed; extension notifications cannot arm. Guidance is request-local, not edits to user messages; updating requires reload and does not rewrite old history. Full arming contract.

Skills

The package ships three model-routable skills:

• workflow-authoring — design, review, and debug custom JavaScript workflows; it teaches topology selection, stable work IDs, bounded failure handling, and resume-safe authoring.
• workflow-patterns — choose and invoke a reviewed built-in for research, adversarial review, code review, multi-perspective analysis, or codebase audit.
• workflow-review — audit an existing workflow for topology, data flow, recovery, resume safety, and publication readiness without editing it.

Use the pattern skill for a standard task, the authoring skill for a custom workflow, and the review skill before accepting a topology or recovery change.

Intentional adaptations from upstream

• No host-side web tools. Agents reach the web through configured pi-web-access/MCP tools or an agent type's tool policy.
• Agent registry and tier catalogue ownership. agentType and the tier catalogue resolve in pi-subagents; the workflow package supplies only a tier key its own strengths table chose, avoiding a second model/thinking policy.
• Schema validation is client-side. The managed request does not assume a structured-output tool; the runtime asks for JSON, parses, validates (including additionalProperties), and repairs across bounded attempts.

Status navigation

With a compatible selector, Ctrl+Alt+S → Workflow runs opens the existing navigator; queries are presentation-only and branch-bound. The footer reports active/paused or retained terminal counts from run status, never inferred child completion. Wire and footer semantics.

Reference

Detailed contracts and legacy section links:

• JavaScript execution boundary
• Resume
• The default table
• Editing it
• Helpers that dispatch for you
• Resume