@ccgv2/pi-acp 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Victor Software House
+
+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,226 @@
+# pi-acp
+
+ACP ([Agent Client Protocol](https://agentclientprotocol.com/get-started/introduction)) adapter for [`pi`](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) coding agent.
+
+`pi-acp` embeds pi directly via the `@earendil-works/pi-coding-agent` SDK and exposes it as an ACP agent over stdio. Each ACP session owns one in-process `AgentSession`.
+
+> **Fork notice:** This repository is based on
+> [`victor-software-house/pi-acp`](https://github.com/victor-software-house/pi-acp).
+> This fork adds per-session MCP runtime support, including stdio and Streamable HTTP
+> servers, MCP tool discovery, and exposing those tools to pi as `customTools`.
+
+## Specs and decisions
+
+- [`docs/prd/PRD-001-acp-v013-zed-alignment.md`](docs/prd/PRD-001-acp-v013-zed-alignment.md) — active release PRD (v0.5).
+- [`docs/architecture/plan-acp-v013-zed-alignment.md`](docs/architecture/plan-acp-v013-zed-alignment.md) — phased implementation plan.
+- [`docs/adr/`](docs/adr/) — architecture decision records (ADR-0001..ADR-0004).
+- [`docs/architecture/acp-conformance.md`](docs/architecture/acp-conformance.md) — ACP conformance reference.
+- [`docs/architecture/claude-acp-comparison.md`](docs/architecture/claude-acp-comparison.md) — reference comparison against `claude-agent-acp`.
+
+## Status
+
+Active development. ACP compliance is improving steadily. Development is centered around [Zed](https://zed.dev) editor support; other ACP clients may have varying levels of compatibility.
+
+## Features
+
+- Streams assistant output as ACP `agent_message_chunk`
+- Streams thinking output as ACP `agent_thought_chunk`
+- Maps pi tool execution to ACP `tool_call` / `tool_call_update`
+  - Descriptive tool titles (`Read src/index.ts`, `Run ls -la`, `Edit config.ts`)
+  - Tool call locations surfaced for follow-along features in clients like Zed
+  - For `edit` and `write`, emits ACP structured diffs (`oldText`/`newText`)
+  - Tool kinds: `read`, `edit`, `execute` (bash), `other`
+- Session configuration via ACP `configOptions`
+  - Model selector (category: `model`)
+  - Thinking level selector (category: `thought_level`)
+  - Also advertises `modes` and `models` for backward compatibility
+  - `session/set_config_option` for changing model or thinking level
+  - `config_option_update` emitted when configuration changes
+- Session persistence and lifecycle
+  - Multiple concurrent sessions supported
+  - pi manages sessions in `~/.pi/agent/sessions/...`
+  - `session/list` with title fallback from first user message
+  - `session/load` replays structured history (text, thinking, tool calls)
+  - `closeSession`, `resumeSession` (stable in ACP v0.12.2+)
+  - `unstable_forkSession` (preview)
+  - Sessions can be resumed in both `pi` CLI and ACP clients
+- Per-session MCP servers
+  - stdio servers with command, arguments, session cwd, and explicit environment overrides
+  - Streamable HTTP servers over HTTPS or loopback HTTP
+  - MCP tools are exposed to pi as namespaced `customTools`
+  - Atomic startup rollback, bounded stderr diagnostics, cancellation, and awaited cleanup
+- Usage and cost tracking
+  - `usage_update` emitted after each agent turn with context size and cost
+  - `PromptResponse.usage` includes per-turn token counts
+- Slash commands
+  - File-based prompt templates from `~/.pi/agent/prompts/` and `<cwd>/.pi/prompts/`
+  - Extension commands from pi extensions
+  - Skill commands (appear as `/skill:skill-name`)
+  - Built-in adapter commands (see below)
+- Authentication via Terminal Auth (ACP Registry support)
+- Startup info block with pi version and context (configurable via `quietStartup` setting)
+
+## Prerequisites
+
+- Node.js 24+ (hard requirement, matches pi runtime)
+- Configure `pi` for your model providers/API keys
+
+## Install
+
+### ACP Registry (Zed)
+
+Launch the registry with `zed: acp registry` and select `pi ACP`:
+
+```json
+"agent_servers": {
+  "pi-acp": {
+    "type": "registry"
+  }
+}
+```
+
+### npx (no global install)
+
+```json
+"agent_servers": {
+  "pi": {
+    "type": "custom",
+    "command": "npx",
+    "args": ["-y", "@ccgv2/pi-acp"],
+    "env": {}
+  }
+}
+```
+
+### Global install
+
+```bash
+npm install -g @ccgv2/pi-acp
+```
+
+```json
+"agent_servers": {
+  "pi": {
+    "type": "custom",
+    "command": "pi-acp",
+    "args": [],
+    "env": {}
+  }
+}
+```
+
+### From source
+
+```bash
+npm install
+npm run build
+```
+
+```json
+"agent_servers": {
+  "pi": {
+    "type": "custom",
+    "command": "node",
+    "args": ["/path/to/pi-acp/dist/index.js"],
+    "env": {}
+  }
+}
+```
+
+## Built-in commands
+
+- `/compact [instructions...]` -- compact session context
+- `/autocompact on|off|toggle` -- toggle automatic compaction
+- `/export` -- export session to HTML
+- `/session` -- show session stats (tokens, messages, cost)
+- `/name <name>` -- set session display name
+- `/steering all|one-at-a-time` -- set steering message delivery mode
+- `/follow-up all|one-at-a-time` -- set follow-up message delivery mode
+- `/changelog` -- show pi changelog
+
+## Authentication
+
+Terminal Auth for the [ACP Registry](https://agentclientprotocol.com/get-started/registry):
+
+```bash
+pi-acp --terminal-login
+```
+
+Zed shows an Authenticate banner that launches this automatically.
+
+## Development
+
+```bash
+npm install
+npm run dev          # run from src
+npm run build        # tsdown -> dist/index.mjs
+npm run typecheck    # tsc --noEmit
+npm run lint         # biome + oxlint
+npm test             # Vitest
+```
+
+Project layout:
+
+```
+src/
+  index.ts                  # stdio entry point
+  env.d.ts                  # ProcessEnv augmentation
+  acp/
+    agent.ts                # PiAcpAgent (ACP Agent interface)
+    session.ts              # PiAcpSession (wraps AgentSession, translates events)
+    auth.ts                 # AuthMethod builder
+    auth-required.ts        # auth error detection
+    pi-settings.ts          # settings reader (Zod schema)
+    translate/
+      pi-messages.ts        # pi message text extraction
+      pi-tools.ts           # pi tool result text extraction (Zod schema)
+      prompt.ts             # ACP ContentBlock -> pi message
+  pi-auth/
+    status.ts               # auth detection (Zod schema)
+test/
+  helpers/fakes.ts          # test doubles
+  unit/                     # unit tests
+  component/                # integration tests
+```
+
+## Limitations
+
+### MCP behavior
+
+- stdio and Streamable HTTP transports are supported. Legacy SSE and unstable ACP-routed MCP transports are rejected.
+- Remote plaintext HTTP is rejected; `http://` is accepted only for `localhost`, `127.0.0.1`, and `::1`.
+- stdio processes inherit only the MCP SDK safe environment allowlist plus explicit ACP `env` entries.
+- Each ACP session owns its MCP connections. Startup is atomic and `session/close` waits for cleanup.
+- `session/load` and `session/fork` rebuild MCP from the request. `session/resume` reuses a live runtime when MCP is omitted and rejects an explicitly different configuration.
+
+### SHOULD-level gaps
+
+- **`session/request_permission`** -- pi does not request permission from ACP clients before tool execution.
+
+### Not implemented (MAY / client capabilities)
+
+- **`agent_plan`** -- plan updates not emitted before tool execution. pi has no equivalent planning surface.
+- **ACP filesystem delegation** (`fs/read_text_file`, `fs/write_text_file`) -- pi reads/writes locally. Not advertised.
+- **ACP terminal delegation** (`terminal/*`) -- pi executes commands locally. Not advertised.
+
+### Design decisions
+
+- pi does not have real session modes (ask/architect/code). The `modes` field exposes thinking levels for backward compatibility with clients that do not support `configOptions`.
+- `configOptions` is the preferred configuration mechanism. Zed uses it exclusively when present.
+- pi-acp uses direct filesystem access rather than delegating reads/writes to the ACP client. This means pi reads on-disk file versions, not unsaved editor buffers.
+
+See [docs/architecture/acp-conformance.md](docs/architecture/acp-conformance.md) for detailed conformance status.
+
+## Release
+
+Releases are automated via [semantic-release](https://semantic-release.gitbook.io/) on pushes to `main`. The pipeline runs typecheck, lint, tests, and `npm pack --dry-run` before publishing. npm trusted publishing (OIDC) is used -- no long-lived npm tokens.
+
+Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/). Commitlint enforces this locally via lefthook and in CI.
+
+## License
+
+MIT (see [LICENSE](LICENSE)).
+
+---
+
+Inspired by [svkozak/pi-acp](https://github.com/svkozak/pi-acp).