@buihongduc132/pi-acp-agents 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-05-05
+
+### Added
+
+- Extracted as standalone repository from pi-plugins monorepo
+- Production-grade package structure (files whitelist, engines, scripts)
+- SKILL.md for pi skill discovery
+- GitHub Actions CI workflow
+- Comprehensive test suite (36+ tests)
+- `acp_delegate` — short-lived task delegation
+- `acp_broadcast` — parallel multi-agent broadcast
+- `acp_compare` — structured response comparison
+- TUI widget for session status display
+- Circuit breaker resilience (closed/open/half-open)
+- Background health monitor with stale session cleanup
+- Busy-session mutex (concurrent prompt guard)
+- Per-session JSON-RPC trace logging
+- `/acp-config` slash command
+
+### Changed
+
+- Package name: `@walodayeet/pi-acp-agents`
+- Repository: standalone GitHub repo
+
+## [0.1.0] - 2025-05-04
+
+### Added
+
+- Initial release within pi-plugins monorepo
+- Core tools: `acp_prompt`, `acp_status`, `acp_session_new`
+- Session management: `acp_session_load`, `acp_session_set_model`, `acp_session_set_mode`
+- `acp_cancel` for ongoing prompt cancellation
+- Gemini CLI adapter with auto-authentication
+- Custom adapter for user-defined ACP commands
+- Config file support at `~/.pi/acp-agents/config.json`
+
+[0.2.0]: https://github.com/buihongduc132/pi-acp-agents/releases/tag/v0.2.0
+[0.1.0]: https://github.com/buihongduc132/pi-acp-agents/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 walodayeet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,359 @@
+# @buihongduc132/pi-acp-agents
+
+> Multi-agent orchestration for pi — spawn, control, and coordinate ACP-compatible agents (Gemini CLI, Claude, Codex, etc.) as first-class tools within the pi coding agent.
+
+[![npm version](https://img.shields.io/npm/v/@buihongduc132/pi-acp-agents.svg)](https://www.npmjs.com/package/@buihongduc132/pi-acp-agents)
+[![CI](https://github.com/buihongduc132/pi-acp-agents/actions/workflows/ci.yml/badge.svg)](https://github.com/buihongduc132/pi-acp-agents/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@buihongduc132/pi-acp-agents.svg)](https://github.com/buihongduc132/pi-acp-agents/blob/main/LICENSE)
+
+---
+
+## Features
+
+- Registers 10 pi tools for ACP agent management
+- Manages session lifecycle (create, load, set model/mode, cancel, dispose)
+- Provides multi-agent coordination (delegate, broadcast, compare)
+- Resilient by default: circuit breaker, stall timeout, health polling
+- TUI widget for real-time session status
+- Adapter pattern: one config format for any ACP agent
+
+---
+
+## Installation
+
+### For Humans
+
+```bash
+npm install @buihongduc132/pi-acp-agents
+```
+
+### For AI Agents
+
+Add to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": ["npm:@buihongduc132/pi-acp-agents"]
+}
+```
+
+Or install via pi CLI:
+
+### Humans
+
+```bash
+pi install npm:@buihongduc132/pi-acp-agents
+```
+
+Or with npm directly:
+
+```bash
+npm install @buihongduc132/pi-acp-agents
+```
+
+### AI Agents (pip install)
+
+```
+pi install npm:@buihongduc132/pi-acp-agents
+```
+
+### Git-sourced for pi
+
+Add to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "gitPackages": [
+    { "url": "https://github.com/buihongduc132/pi-acp-agents.git" }
+  ]
+}
+```
+
+Or clone and link locally:
+
+```bash
+git clone https://github.com/buihongduc132/pi-acp-agents.git
+cd pi-acp-agents && npm install
+```
+
+Then reference the local path in `settings.json`:
+
+```json
+{
+  "packages": ["/path/to/pi-acp-agents"]
+}
+```
+```
+
+## Quick Start
+
+1. Ensure an ACP agent is installed (e.g., Gemini CLI):
+
+   ```bash
+   gemini --version
+   gemini  # first run to authenticate
+   ```
+
+2. Configure (optional — defaults to gemini):
+
+   ```bash
+   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
+   ```
+
+3. Use in pi:
+   ```
+   Use the acp_prompt tool to ask gemini "What is the capital of France?"
+   ```
+
+---
+
+## Tools
+
+### Session Management (Level 1)
+
+Friendly session names are globally unique across ACP sessions, immutable once assigned, persisted in the runtime directory, and remain resolvable after reload for both live and archived sessions.
+
+| Tool         | Description                                                    |
+| ------------ | -------------------------------------------------------------- |
+| `acp_prompt` | Send a prompt to an ACP agent, get the text response           |
+| `acp_status` | Show configured agents, active sessions, circuit breaker state |
+
+### Session Lifecycle (Level 2)
+
+| Tool                    | Description                                            |
+| ----------------------- | ------------------------------------------------------ |
+| `acp_session_new`       | Create a new isolated session with an agent; optional immutable `session_name`, caller cannot choose fresh session IDs |
+| `acp_session_load`      | Load/resume an existing session by ID or friendly name, including archived auto-closed sessions       |
+| `acp_session_set_model` | Change the model for an active session by ID or friendly name                 |
+| `acp_session_set_mode`  | Change the mode (thinking level) for an active session by ID or friendly name |
+| `acp_cancel`            | Cancel an ongoing prompt by ID or friendly name                               |
+
+### Multi-Agent Coordination (Level 3)
+
+| Tool            | Description                                          |
+| --------------- | ---------------------------------------------------- |
+| `acp_delegate`  | Delegate a task (short-lived session, auto-disposed) |
+| `acp_broadcast` | Send same prompt to multiple agents in parallel      |
+| `acp_compare`   | Get responses from multiple agents and compare them  |
+
+**Commands:** `/acp` — ACP root command with session, prompt, delegate, broadcast, compare, task, message, plan, runtime groups
+
+**Compatibility aliases:** `/acp-doctor`, `/acp-config`
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│                    pi agent                      │
+│                                                  │
+│  acp_prompt ──┐                                  │
+│  acp_status ──┤                                  │
+│  acp_session ─┤──► AgentCoordinator ──┐          │
+│  acp_cancel ──┤                       │          │
+│  acp_compare ─┘                       ▼          │
+│                              AcpCircuitBreaker   │
+│                                       │          │
+│                              ┌────────┴────────┐ │
+│                              │  Adapter Factory │ │
+│                              └────┬───────┬────┘ │
+│                              GeminiAdapter  │      │
+│                                    CustomAdapter  │
+│                                       │          │
+│                              AcpClient (stdio)    │
+│                                       │          │
+│                              HealthMonitor ◄──────┤
+│                              SessionManager       │
+└─────────────────────────────────────────────────┘
+                                       │
+                              ┌────────┴────────┐
+                              │  ACP Agent (gemini│
+                              │  --acp, claude,  │
+                              │  codex, custom)  │
+                              └─────────────────┘
+```
+
+### Patterns
+
+| Pattern             | Implementation                                              |
+| ------------------- | ----------------------------------------------------------- |
+| **Adapter** (GoF)   | `AcpAgentAdapter` → `GeminiAcpAdapter` / `CustomAcpAdapter` |
+| **Factory**         | `createAdapter()` — string dispatch                         |
+| **Circuit Breaker** | Closed → Open → Half-Open with configurable thresholds      |
+| **Health Monitor**  | Background polling with distinct 1-hour no-response and completed-idle auto-close    |
+| **Coordinator**     | Multi-agent delegate/broadcast/compare                      |
+
+---
+
+## 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 enforces separate no-response and completed-idle timers |
+| Busy mutex      | per-session       | Prevents concurrent prompts on the same session             |
+| Process safety  | SIGTERM→SIGKILL   | Graceful process 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 |
+
+---
+
+## Configuration
+
+Config file: `~/.pi/acp-agents/config.json`
+
+```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 config
+
+| Field                       | Default                 | Description                               |
+| --------------------------- | ----------------------- | ----------------------------------------- |
+| `agent_servers`             | `{ gemini: {...} }`     | Map of agent name → config                |
+| `defaultAgent`              | `"gemini"`              | Agent used when not specified             |
+| `staleTimeoutMs`            | `3600000` (1 hour)      | Auto-close threshold for each separate lifecycle policy: 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` (1 hour)      | Per-operation timeout                     |
+| `logsDir`                   | `~/.pi/acp-agents/logs` | Log directory                             |
+
+### Per-agent config
+
+| Field          | Required | Description                   |
+| -------------- | -------- | ----------------------------- |
+| `command`      | **yes**  | Executable to spawn           |
+| `args`         | no       | Arguments (e.g., `["--acp"]`) |
+| `env`          | no       | Extra environment variables   |
+| `cwd`          | no       | Working directory override    |
+| `default_model` | no      | Default model ID              |
+
+---
+
+## Logs
+
+Central logs: `~/.pi/acp-agents/logs/`
+
+- `main.log` — general structured JSON log
+- `session-{id}/trace.jsonl` — per-session ACP JSON-RPC traces
+
+---
+
+## Supported Agents
+
+| Agent           | Status                    | Config                               |
+| --------------- | ------------------------- | ------------------------------------ |
+| **Gemini CLI**  | ✅ Built-in adapter       | `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  |
+
+---
+
+## Roadmap
+
+### v0.2.x — Current (Foundation)
+
+- [x] ACP stdio JSON-RPC client
+- [x] Gemini CLI adapter with auto-auth
+- [x] Session lifecycle (new, load, set model/mode, cancel)
+- [x] Circuit breaker + health monitor
+- [x] Multi-agent: delegate, broadcast, compare
+- [x] TUI widget for session status
+- [x] 148 unit + integration tests
+- [x] CI/CD pipeline with provenance publishing
+
+### v0.3.x — Streaming & Auth
+
+- [ ] **Streaming responses** — forward `agent_message_chunk` events to pi in real-time
+- [ ] **Tool use forwarding** — expose ACP agent tool calls back to pi's tool registry
+- [ ] **OAuth/token auth** — support API key and OAuth flows per-agent
+- [ ] **Config hot-reload** — watch config file, reload without restart
+- [ ] **Retry with backoff** — exponential backoff for transient failures
+- [ ] Custom adapter smoke tests
+
+### v0.4.x — Persistence & Recovery
+
+- [ ] **Session persistence** — save/restore sessions across pi restarts
+- [ ] **Session sharing** — share ACP sessions between pi instances via file lock
+- [x] **Checkpoint/resume** — archived runtime metadata reopens auto-closed ACP sessions by original session ID
+- [ ] **Metrics export** — Prometheus-compatible metrics (session count, latency, error rate)
+
+### v0.5.x — Advanced Orchestration
+
+- [ ] **Agent routing** — automatic agent selection based on task type
+- [ ] **Ensemble mode** — run same prompt across N agents, merge via configurable strategy (vote, rank, consensus)
+- [ ] **Chain-of-agents** — pipe output of one agent as input to next
+- [ ] **Cost tracking** — per-agent, per-session token usage and cost estimation
+- [ ] **Agent health dashboard** — web UI for monitoring all connected agents
+
+### v1.0.0 — Production
+
+- [ ] **Stable API** — no breaking changes without major version bump
+- [ ] **Full ACP spec compliance** — implement all optional ACP capabilities
+- [ ] **Multi-platform support** — OpenClaw, Claude Code plugin, standalone MCP server
+- [ ] **Comprehensive docs** — API reference, migration guides, examples
+
+---
+
+## Development
+
+```bash
+npm install
+npm test              # run all tests
+npm run test:ci       # run with coverage
+npm run typecheck     # TypeScript validation
+npm run publish:dry   # verify package contents before publish
+```
+
+### Release process
+
+```bash
+npm run release:patch    # 0.2.0 → 0.2.1
+npm run release:minor    # 0.2.0 → 0.3.0
+npm run release:beta     # 0.2.0 → 0.2.1-beta.0
+git push --follow-tags   # triggers CI → auto-publish with provenance
+```
+
+---
+
+## License
+
+MIT
+
+## Attribution
+
+Maintained by [buihongduc132](https://github.com/buihongduc132). Forked from [walodayeet/pi-acp-agents](https://github.com/walodayeet/pi-acp-agents).