⚡ pi-agent-orchestrator

Parallel Subagents, Background Shell Jobs & Interactive Activity Dock for Pi

Delegate complex exploration, research, coding, and code review to isolated child agents • Run long builds and dev servers in the background without polling • Steer, pause, or inspect everything live in a native TUI dock.

Quick Start · Subagent Roles · Interactive Lifecycle · Tools · Activity Dock · Architecture Docs

✨ Why pi-agent-orchestrator?

By default, an AI coding agent runs a single synchronous loop: a long test suite, a dev server, or a 40-file codebase search blocks the conversation and floods the main context window with raw tool output.

pi-agent-orchestrator adds a native multi-agent and background-execution layer on top of Pi:

• 🚀 True Parallelism: Spawn up to 10 concurrent subagents (@explore, @code, @review, @research, @general) in a single turn.
• 🧠 Context Isolation: Each child agent runs in its own isolated Pi session with role-tailored prompts and tools, returning a distilled report + ground-truth <telemetry> to keep the parent context lean.
• ⚡ Zero-Latency Interactivity:
  • Send a message (Enter) while subagents or job_wait are running $\to$ work is automatically backgrounded so the Main Agent replies to you immediately without losing subagent progress.
  • Press Esc $\to$ stops both the Main Agent and any active subagents immediately while preserving their sessionID so saying continue resumes right where they left off.
  • Live Mid-Run Steering $\to$ inject new instructions into an already-running subagent via subagent({ sessionID, prompt }) without restarting it.
• 🔔 Push Completion Notices (No Polling): Background shells and subagents automatically wake the parent session via steering messages when they finish.
• 🛡️ Fail-Closed Review Gate (review: true): Optional independent reviewer audits code changes against task criteria, mid-run steering updates, and verified test execution before accepting delivery.

📦 Quick Start

Install directly via Pi's package manager:

pi install npm:pi-agent-orchestrator

Or install from a local checkout during development:

pi install ./path/to/pi-agent-orchestrator

🤖 Specialized Subagent Roles

Every child session inherits Pi's built-in tools (including codemode), plus callable parent tools (web_search, fetch_content, MCP tools, etc.), filtered through a strict role-based capability matrix:

Built-in Safety & Reliability Guardrails

• Two-Layer Read-Only Guard (createReadOnlyGuard): @explore, @review, and @research exclude edit and write from their tool schema and enforce a runtime tool_call hook blocking file modifications, while leaving bash unrestricted for complex multi-repo inspection (cd repo && git status, find, rg).
• Default Child bash Timeout: Child bash calls automatically default to a 120-second timeout when omitted, preventing runaway filesystem scans (e.g. find /) from hanging a subagent indefinitely.
• 4-Stage Handoff Protocol:
  1. expectedOutput Contract: Appended to the end of the child prompt for recency focus.
  2. One-Shot Empty-Completion Nudge: Automatically recovers if a child executes tools but forgets to emit a final synthesis turn.
  3. Ground-Truth <telemetry>: Every <subagent> completion envelope includes exact tool call counts, modified files, executed commands, and verification status.
  4. Durable sessionID Continuation: Child sessions are stored under <parent-session-dir>/subagents/*.jsonl (hidden from /resume clutter) and can be resumed across turns or Pi restarts.

🔄 Interactive Lifecycle & Steering

User Input / Key          Main Agent State               Subagent / Job Behavior
──────────────────────────────────────────────────────────────────────────────────────────────────
Enter (send message)  ──► Unblocks immediately       ──► Auto-backgrounds active subagents &
                          to answer your message         interrupts job_wait (jobs keep running)

Esc (cancel turn)     ──► Aborts current turn        ──► Aborts active subagents & preserves
                                                         sessionID for instant "continue" resume

"continue" / "tiếp"   ──► Sees <interrupted_subagents> ─► Calls subagent({ sessionID }) to resume
                          system notice                  from existing tool & message history

Steer running agent   ──► Calls subagent({ sessionID, ──► Injects live steering prompt into the
                          prompt: "<new guidance>" })    running child session without aborting

Independent Verification Gate (review: true)

When review: true is passed to a @code or @general subagent:

1. The implementer completes its changes and runs project verification commands (npm test, ./mvnw test, pytest, cargo test, tsc --noEmit, git diff --check, etc., including multi-repo cd <repo> && ... chains).
2. An isolated read-only @review agent audits the repository state against both the original task prompt and any mid-run steering instructions.
3. If the reviewer returns NEEDS_FIX, the implementer is resumed at most once to fix the concrete findings and re-run verification before a final re-review.
4. Fails closed if no verification command succeeded or if findings remain unresolved (while always preserving the implementer's full report for inspection).

🛠️ Tools Reference

All job management tools (job_wait, job_status, job_background, job_cancel) accept either the exact UUID or the human-readable subagent description / job title (exact or substring match).

🖥️ Activity Dock (TUI)

Press ↓ (Down Arrow) from an empty editor (or run /agents) to open the live Activity Dock overlay:

╭─ Activity · Subagents (2) · Shell (1) ──────────────────────────────────────────────────────────╮
│ ● @explore  Explore existing docs and templates                       18 tools · 14s · running  │
│ ✓ @code     Implement backend finding query endpoint                  12 tools · 42s · done     │
├─────────────────────────────────────────────────────────────────────────────────────────────────┤
│ ↑/↓ select · ←/→ switch tab · Enter inspect transcript · x cancel job · Esc close               │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯

Keyboard & Mouse Controls

⚙️ Runtime Defaults

📚 Architecture & Research Docs

Deep-dive engineering documentation, empirical benchmarks, and failure-mode analyses are available in docs/:

1. 01 — Problem Statement, Failure Taxonomy & Empirical Research Quantitative findings from MAST (NeurIPS 2025), Anthropic Multi-Agent Research (+90.2% gain, BrowseComp token-variance analysis), OpenDev, and Task Spec Contracts.
2. 02 — System Architecture & Pi Harness Integration Component diagrams, DefaultResourceLoader isolation, createCodemodeExtension() integration, Inherit-All + Role Denylist tool resolution (resolveChildTools), and durable SessionManager linkage.
3. 03 — Subagent Roles, Handoff Protocol & Verification Gate Capability matrix for explore, research, code, review, and general; the 4-stage handoff protocol; createReadOnlyGuard(); and the fail-closed review: true gate.
4. 04 — Background Jobs, Shell Pipeline & Crash Recovery JobRegistry state machine, 32 KB Head-Tail truncation, automatic dev-server promotion (isServerCommand), negative-offset tail reads, and session-scoped durable recovery (pi-agent-orchestrator.recovery.v1).
5. 05 — TUI Activity Dock & The 4-Phase Engineering Workflow Cached sub-millisecond TUI rendering (Markdown, ThinkingSection, ToolExecutionBox) and integration with structured engineering workflows (grill-me $\to$ plan $\to$ execute $\to$ verify).

🧪 Development

npm install          # Installs devDependencies (typescript, @types/node, jiti)
npm run typecheck    # Runs tsc --noEmit
npm test             # Runs all 60 unit & integration tests via node --test

📄 License

MIT © 2026 tungbach12