@buihongduc132/pi-acp-agents

Multi-agent orchestration for pi — spawn, control, and coordinate ACP-compatible agents (Gemini CLI, Claude, Codex, custom) as first-class tools within the pi coding agent.

What works vs what does not ← read this first
Install
Quick start
Tool surface
DAG delegation
Alias resolver + fallback chains
Persistent workers
Configuration
Architecture
Resilience
Logs
Supported agents
Development
Release process
Further documentation

What works vs what does not

Status as of 0.5.0. Verified by full test suite (npx vitest run → 2081 passed / 0 failed / 104 skipped / 1 todo). Consolidated tool surface: 9 tools registered (7 ACP core + 2 ACP hooks policy), down from the legacy 33-tool surface. See Tool surface.

✅ Working

Capability	Notes
`acp_spawn` (single agent)	Spawn a session + optional prompt; absorbs legacy acp_prompt / acp_session_new
`acp_msg` (messaging)	Session prompt/steer/cancel + mailbox send/list; absorbs acp_message
`acp_status` (diagnostic)	Agent list, sessions, circuit breaker; absorbs acp_doctor / acp_runtime_info
`acp_fanout` (broadcast/compare)	Same prompt → N agents; absorbs acp_broadcast / acp_compare
`acp_governance`	Plan request/resolve + model policy
`acp_task` (action: create\|update)	Unified task tool: status / assignee / deps / bulk `*` filter
`acp_dag` (action: submit\|status\|cancel)	Wave-based topological DAG execution, persistent resume
`acp_hooks_policy_get` / `acp_hooks_policy_set`	Runtime hooks failure-policy inspection + mutation
Alias resolver (failover + race)	`AliasResolver` class — sequential fallback OR parallel first-wins with cancel of losers
Circuit breaker	3 failures → open, 60s → half-open, auto-recover
Health monitor	30s background polling; distinct no-response vs completed-idle timers
Session-scoped stores	`tasks`/`mailboxes`/`governance`/`workers` partitioned per host session ID; `session-archive`/`session-name-registry`/`event-log` global
Legacy migration	Non-destructive flat → `legacy/` on first run after partitioning
DAG widget	`dagIndexEntryToWidgetDag` helper renders DAG state in TUI
TUI widget	Real-time session + DAG status panel
Gemini CLI adapter	Auto-auth, default
Custom adapter	Any ACP-speaking stdio agent
Stall timeout	Per-op with SIGTERM → SIGKILL escalation
EPIPE safety	stdin/stdout broken-pipe handled
Tag-triggered CI publish	`git push --follow-tags` → npm publish with provenance

❌ Not working / not implemented

Gap	Status
One-call parallel batch delegate	No single-call parallel batch — use `acp_fanout` (broadcast/compare) instead of spawning N sessions manually
Plan approval flow as tool	`acp_plan_request` / `acp_plan_resolve` are command-only stubs, not tools
Hooks policy	No `hooks_policy_*` — retry governance absent
Model policy as tool	`acp_model_policy_get` / `_check` are command-only
Predefined teams	No `predefined_teams_*`
Workspace isolation (worktree mode)	Workers use `cwd` only — no `git worktree` isolation
Context inheritance	No `contextMode: "branch"` (clone leader session)
`task_dep_ls`	Only add/rm via `task_update` — cannot list blockers
`task_get` (single)	Not exposed — only create + update
Diagnostics as tools	`acp_doctor`, `acp_runtime_info`, `acp_event_log`, `acp_env`, `acp_cleanup` are slash commands only
Session lifecycle tools	`acp_session_list` / `_shutdown` / `_kill` / `_prune` / `_set_model` / `_set_mode` are not exposed (automation-only)
Streaming responses	Planned — currently returns after full prompt completes
Tool use forwarding	Planned — ACP agent tool calls not relayed back to pi
OAuth / token auth	Planned — env vars only
Config hot-reload	Manual restart required
Retry with backoff	Circuit breaker handles fail-closed; no exponential backoff
Session sharing across pi instances	Single-host only
Metrics export (Prometheus)	Planned
Agent routing (auto-select)	Manual via alias or explicit
Ensemble / chain-of-agents	Manual via DAG composition
Cost tracking	Planned
Claude Code / Codex ACP adapters	Pending upstream ACP mode

⚠️ Known surface drift

src/settings/config.ts ships a legacy ACP_TOOL_NAMES array of 42 entries (a settings toggle schema) while only 16 tools are actually registered in index.ts. The 26-entry delta is NOT missing tools — it is the per-tool enable/disable toggle schema for /acp settings. See ../pi-plugins/flow/intentions/pi-acp-agents/tool-consolidation.md for the planned consolidation (42 → 7 multiplexed tools).

Install

For humans

npm install @buihongduc132/pi-acp-agents

For AI agents

Add to ~/.pi/agent/settings.json:

{
  "packages": ["npm:@buihongduc132/pi-acp-agents"]
}

Or:

pi install npm:@buihongduc132/pi-acp-agents

Git-sourced

{
  "gitPackages": [
    { "url": "https://github.com/buihongduc132/pi-acp-agents.git" }
  ]
}

Quick start

Install an ACP agent (Gemini CLI default):

gemini --version
gemini  # first run to authenticate

(Optional) Configure:

mkdir -p ~/.pi/acp-agents
cat > ~/.pi/acp-agents/config.json << 'EOF'
{
  "agent_servers": {
    "gemini": {
      "command": "gemini",
      "args": ["--acp"],
      "default_model": "gemini-2.5-pro"
    }
  },
  "defaultAgent": "gemini"
}
EOF

Use in pi:

Use the acp_spawn tool to spawn a gemini session, then acp_msg to ask "What is the capital of France?"

For full usage patterns, DAG examples, alias configuration, and worker orchestration see docs/USAGE.md.

Tool surface

9 tools registered (7 ACP core + 2 hooks policy, gated by /acp settings per-tool toggles):

Tool	Purpose
`acp_spawn`	Spawn a session + optional prompt (absorbs acp_prompt / acp_session_new)
`acp_msg`	Session prompt/steer/cancel + mailbox send/list (absorbs acp_message / acp_cancel)
`acp_governance`	Plan request/resolve + model policy (absorbs acp_plan_, acp_model_policy_)
`acp_status`	Agents, sessions, circuit breaker, cleanup, prune (absorbs acp_doctor / acp_runtime_info / acp_cleanup)
`acp_fanout`	Broadcast to N agents + compare mode (absorbs acp_broadcast / acp_compare)
`acp_task`	Unified task tool: action:'create' or action:'update' (absorbs acp_task_create / acp_task_update)
`acp_dag`	DAG delegation: action:'submit'\|'status'\|'cancel' (absorbs acp_dag_submit / _status / _cancel)
`acp_hooks_policy_get`	Inspect the ACP hooks failure policy
`acp_hooks_policy_set`	Update the ACP hooks failure policy

Slash command surface (/acp ...):

/acp session <new|load|list|shutdown|kill|prune|set-model|set-mode|cancel>
/acp prompt
/acp delegate
/acp broadcast
/acp compare
/acp task <create|list|get|assign|set-status|dep-add|dep-rm|clear>
/acp message <send|list>
/acp plan <request|resolve>
/acp runtime <status|config|env|info|event-log|cleanup|doctor>
/acp settings — configure tool visibility
Aliases: /acp-doctor, /acp-config

For tool-parameter reference and examples see docs/USAGE.md.

DAG delegation

Submit a complete DAG of ACP agent tasks in a single call. The DAG executor:

Validates statically (cycles, dangling refs, duplicate IDs, agent availability)
Persists state to disk under <runtimeDir>/dag/
Executes in topological wave-order (parallel within wave, serial across waves)
Resumes automatically after pi restart (running steps retried, completed steps skipped)

Submission JSON

{
  "tasks": [
    { "id": "analyze", "agent": "gemini", "prompt": "Analyze the codebase for security issues" },
    { "id": "fix", "agent": "claude", "prompt": "Fix the issues: {analyze.output}", "dependsOn": ["analyze"] },
    { "id": "verify", "agent": "gemini", "prompt": "Verify: {fix.output}", "dependsOn": ["fix"], "gate": "after" }
  ],
  "args": { "project": "my-app" },
  "options": { "failFast": true, "maxRetries": 0 },
  "cwd": "/path/to/project"
}

Template variables

Variable	Resolves to
`{<step-id>.output}`	Output of referenced step (truncated to `dagOutputTruncateChars`)
`{<step-id>.status}`	Terminal status (`completed` / `failed` / `skipped` / `cancelled`)
`{dag.args.<key>}`	Workflow arg from `args` at submission

Unresolvable variables fail the step at dispatch time.

Gates

Gate	Behavior
`needs` (default)	Success-gate — all deps must `complete`. Failure cascades.
`after`	Completion-gate — deps just need a terminal state. Use for cleanup/verify steps.

Config

Option	Default	Description
`dagStaleTimeoutMs`	`3_600_000` (1h)	No step transitions for this long → `stale`
`dagOutputTruncateChars`	`8000`	Max chars injected into downstream prompts

For DAG executor internals, persistence model, and resume semantics see docs/USAGE.md.

Alias resolver + fallback chains

Resolves an alias name to a concrete agent using configurable strategies. Used internally by acp_spawn / acp_fanout when called with an alias name.

Strategy	Behavior
failover (sequential)	Try agents in order; first success wins; throws `AllAgentsFailedError` if all fail
race (parallel)	Send to all healthy agents in parallel; first success cancels losers (default race timeout 30s)

Both strategies consult the circuit breaker (isHealthyFn) before dispatching and skip unhealthy agents.

For alias configuration schema and examples see docs/USAGE.md.

Persistent workers

Spawn long-lived named workers via acp_spawn. Workers persist across task completions and are managed via the unified tools:

Workers share the caller's filesystem (no git worktree isolation). For parallel worktree-isolated delegation use the teams pi-plugin instead.

Async run lifecycle (telemetry, steer, interrupt, resume, worktree)

Async runs (spawned with async: true or acp_dag) now support full lifecycle management, aligning ACP with subagents:

Fleet view

acp_status({ action: "fleet" })  // or acp_status({ view: "fleet" })

Returns compact list of active runs with telemetry (turns, toolCalls, tokensUsed, filesWritten, lastActivityAt).

Interrupt / Resume

acp_status({ action: "interrupt", id: "<runId>" })   // abort in-flight turn → needs-attention
acp_status({ action: "resume", id: "<runId>", message: "Continue with X" })

Silent-failure detection

Runs that complete with zero tool calls, zero file writes, AND empty text are auto-flagged as failed with error: "silent-no-output".

Worktree isolation

acp_spawn({ agent: "gemini", prompt: "...", worktree: true })          // isolated git worktree
acp_spawn({ agent: "gemini", prompt: "...", worktree: true, keepWorktree: true })  // keep after run

Creates a git worktree at <cwd>/.worktrees/acp-<runId>. Cleaned up on run dispose unless keepWorktree: true.

Configuration

Config file: ~/.pi/acp-agents/config.json

{
  "agent_servers": {
    "gemini": { "command": "gemini", "args": ["--acp"], "default_model": "gemini-2.5-pro" },
    "custom": { "command": "/path/to/my-acp-agent", "args": ["--mode", "acp"] }
  },
  "defaultAgent": "gemini",
  "staleTimeoutMs": 3600000,
  "healthCheckIntervalMs": 30000,
  "circuitBreakerMaxFailures": 3,
  "circuitBreakerResetMs": 60000,
  "stallTimeoutMs": 3600000
}

Global

Field	Default	Description
`agent_servers`	`{ gemini: {...} }`	Map of agent name → config
`defaultAgent`	`"gemini"`	Agent used when not specified
`staleTimeoutMs`	`3600000` (1h)	Auto-close: stalled-no-response AND completed-idle
`healthCheckIntervalMs`	`30000` (30s)	Background health polling interval
`circuitBreakerMaxFailures`	`3`	Consecutive failures before circuit opens
`circuitBreakerResetMs`	`60000` (60s)	Time before circuit half-opens
`stallTimeoutMs`	`3600000` (1h)	Per-operation timeout
`logsDir`	`~/.pi/acp-agents/logs`	Log directory
`dagStaleTimeoutMs`	`3600000`	DAG stale threshold
`dagOutputTruncateChars`	`8000`	DAG downstream prompt truncation

Per-agent

Field	Required	Description
`command`	yes	Executable to spawn
`args`	no	Args (e.g. `["--acp"]`)
`env`	no	Extra env vars
`cwd`	no	Working dir override
`default_model`	no	Default model ID

For aliases, model policy, and runtime store paths see docs/USAGE.md.

Architecture

┌─────────────────────────────────────────────────────┐
│                    pi agent                          │
│                                                      │
│  acp_spawn ───┐                                      │
│  acp_status ──┤                                      │
│  acp_msg ─────┤──► AliasResolver ──► Coordinator ──┐ │
│  acp_dag ─────┤                       │            │ │
│  acp_fanout ──┤                       ▼            │ │
│  acp_task ────┤              AcpCircuitBreaker     │ │
│  acp_governance┘                       │            │ │
│                              ┌────────┴────────┐   │ │
│                              │ Adapter Factory │   │ │
│                              └────┬───────┬────┘   │ │
│                            GeminiAdapter│          │ │
│                                  CustomAdapter     │ │
│                                       │            │ │
│                              AcpClient (stdio)     │ │
│                                       │            │ │
│                              HealthMonitor ◄───────┤ │
│                              SessionManager        │ │
│                              DagStore + DagExecutor│ │
│                              WorkerStore           │ │
│                              SessionStoreFactory   │ │
└─────────────────────────────────────────────────────┘

Patterns

Pattern	Implementation
Adapter	`AcpAgentAdapter` → `GeminiAcpAdapter` / `CustomAcpAdapter`
Factory	`createAdapter()` — string dispatch
Circuit breaker	Closed → Open → Half-Open with configurable thresholds
Health monitor	Background polling; distinct no-response and completed-idle auto-close
Coordinator	Multi-agent delegate / broadcast / compare
Alias resolver	failover (sequential) + race (parallel first-wins)
DAG executor	Topological wave-execution + persistent resume
Session-store factory	Per-host-session lazy-instantiated stores (4 session-scoped + 3 global)

Resilience

Feature	Default	Description
Circuit breaker	3 failures → open	Auto-recovers after 60s in half-open state
Stall timeout	1 hour	Per-operation timeout with SIGTERM → SIGKILL escalation
Health polling	30s	Background monitor with separate no-response and completed-idle timers
Busy mutex	per-session	Prevents concurrent prompts on the same session
Process safety	SIGTERM → SIGKILL	Graceful shutdown with escalation
EPIPE handling	stdin / stdout	Prevents crashes on broken pipes
Non-blocking	all paths	Errors return as tool error results, never unhandled throws
Alias failover	automatic	Sequential fallback on agent failure
Alias race	30s timeout	Parallel first-wins with cancel of losers
DAG resume	on pi restart	`resumeAll()` discovers running DAGs, skips completed steps

Logs

Central logs at ~/.pi/acp-agents/logs/:

main.log — general structured JSON log
session-{id}/trace.jsonl — per-session ACP JSON-RPC traces
<runtimeDir>/dag/<dagId>.json + dag-index.json — DAG state persistence
<runtimeDir>/<sessionId>/{tasks,mailboxes,governance,workers}.json — session-scoped stores
<runtimeDir>/{events,session-archive,session-name-registry}.jsonl|json — global stores

Supported agents

Agent	Status	Config
Gemini CLI	✅ Built-in	`command: "gemini", args: ["--acp"]`
Claude Code	🔜 Planned	ACP mode pending upstream
Codex	🔜 Planned	ACP mode pending upstream
Custom	✅ Via `CustomAcpAdapter`	Any command speaking ACP over stdio

Development

npm install
npm test              # all tests
npm run test:ci       # with coverage
npm run typecheck     # TypeScript validation
npm run publish:dry   # verify package contents before publish

Release process

npm run release:patch    # 0.4.0 → 0.4.1
npm run release:minor    # 0.4.0 → 0.5.0
npm run release:beta     # 0.4.0 → 0.4.1-beta.0
git push --follow-tags   # triggers CI → auto-publish with provenance

Further documentation

Topic	Location
Full usage guide (DAG examples, alias config, worker patterns, slash command reference)	`docs/USAGE.md`
Tool consolidation plan (33 → 7 ACP core multiplexed tools; 9 total with hooks policy)	`../pi-plugins/flow/intentions/pi-acp-agents/tool-consolidation.md`
ACP vs teams gap analysis	`../pi-plugins/flow/findings/acp-vs-teams-analysis.md`
DAG delegation design	`openspec/changes/archive/2026-06-20-acp-dag-delegation/`
DAG widget design	`openspec/changes/archive/2026-06-22-acp-dag-widget/`
Session-scoped runtime stores	`openspec/changes/archive/2026-06-19-scope-runtime-stores-per-session/`
Branch consolidation record (this release)	`docs/branch-consolidation-2026-06-22.md`
OpenSpec changes	`openspec/changes/`
Specs (canonical)	`openspec/specs/`

@buihongduc132/pi-acp-agents

Signals

Download trend

README

@buihongduc132/pi-acp-agents

Table of Contents

What works vs what does not

✅ Working

❌ Not working / not implemented

⚠️ Known surface drift

Install

For humans

For AI agents

Git-sourced

Quick start

Tool surface

DAG delegation

Submission JSON

Template variables

Gates

Config

Alias resolver + fallback chains

Persistent workers

Async run lifecycle (telemetry, steer, interrupt, resume, worktree)

Fleet view

Interrupt / Resume

Silent-failure detection

Worktree isolation

Configuration

Global

Per-agent

Architecture

Patterns

Resilience

Logs

Supported agents

Development

Release process

Further documentation