@pi-in-go/pigpen-acp 0.1.0

package/port/oracle/pi-acp/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sergii Kozak
+
+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/port/oracle/pi-acp/README.md

@@ -0,0 +1,209 @@
+# pi-acp
+
+ACP ([Agent Client Protocol](https://agentclientprotocol.com/overview/introduction)) adapter for [`pi`](https://github.com/earendil-works/pi) coding agent (fka shitty coding agent).
+
+`pi-acp` communicates **ACP JSON-RPC 2.0 over stdio** to an ACP client (e.g. Zed editor) and spawns `pi --mode rpc`, bridging requests/events between the two.
+
+## Status
+
+This is an MVP-style adapter intended to be useful today and easy to iterate on. Some ACP features may be not implemented or are not supported (see [Limitations](#limitations)). Development is centered around [Zed](https://zed.dev) editor support, other clients may have varying levels of compatibility.
+
+Expect some minor breaking changes.
+
+## Features
+
+- Streams assistant output as ACP `agent_message_chunk`
+- Maps pi tool execution to ACP `tool_call` / `tool_call_update`
+  - Tool call locations are surfaced when available for ACP clients that support opening the referenced file/context
+  - Relative file paths from pi are resolved against the session cwd before being emitted as ACP tool locations, which enables follow-along features in clients like Zed
+  - For `edit`, `pi-acp` attempts to infer a 1-based line number from a unique `oldText` match in the pre-edit file snapshot and includes it in the emitted tool location when possible
+  - For `edit`, `pi-acp` snapshots the file before the tool runs and emits an ACP **structured diff** (`oldText`/`newText`) on completion when possible
+- Session persistence
+  - pi stores its own sessions in `~/.pi/agent/sessions/...`
+  - `pi-acp` stores a small mapping file at `~/.pi/pi-acp/session-map.json` so `session/load` can reattach to a previous pi session file
+- Slash commands
+  - Loads file-based slash commands compatible with pi’s conventions
+  - Adds a small set of built-in commands for headless/editor usage
+  - Supports skill commands (if enabled in pi settings, they appear as `/skill:skill-name` in the ACP client)
+- Context window usage
+  - Reports pi's real context occupancy (`get_session_stats` → `contextUsage`) to the client as ACP `usage_update` after each turn, on `session/new` and `session/load`, and after a model switch
+  - Requires a pi version whose `get_session_stats` response includes `contextUsage`; otherwise no usage is reported
+  - Right after compaction pi may not have a trustworthy token count yet, so the client keeps the previous value until the next model response
+- Skills are loaded by pi directly and are available in ACP sessions
+- (Zed) `pi-acp` emits “startup info” block into the session (pi version, context, skills, prompts, extensions - similar to `pi` in the terminal). You can disable it by setting `quietStartup: true` in pi settings (`~/.pi/agent/settings.json` or `<project>/.pi/settings.json`). When `quietStartup` is enabled, `pi-acp` will still emit a 'New version available' message if the installed pi version is outdated.
+- (Zed) Session history is supported in Zed starting with [`v0.225.0`](https://zed.dev/releases/preview/0.225.0). Session loading / history maps to pi's session files. Sessions can be resumed both in `pi` and in the ACP client.
+
+## Prerequisites
+
+Make sure pi is installed
+
+```bash
+npm install -g @earendil-works/pi-coding-agent
+```
+
+- Node.js 22+
+- `pi` v0.81.0+ installed and available on your `PATH` (the adapter runs the `pi` executable)
+- Configure `pi` separately for your model providers/API keys
+
+## Install
+
+### Add pi-acp to your ACP client, e.g. [Zed](https://zed.dev/docs/agents/external-agents/)
+
+#### Using ACP Registry in Zed or other clients that support it:
+
+In Zed launch the registry with `zed: acp registry` command and select `pi ACP` adapter from the list. This will automatically add the agent server configuration to your `settings.json` and keep it up to date:
+
+```json
+  "agent_servers": {
+    "pi-acp": {
+      "type": "registry",
+    },
+  }
+```
+
+#### Using with `npx` (no global install needed, always loads the latest version):
+
+Add the following to your Zed `settings.json`:
+
+```json
+  "agent_servers": {
+    "pi": {
+      "type": "custom",
+      "command": "npx",
+      "args": ["-y", "pi-acp"],
+      "env": {}
+    }
+  }
+```
+
+#### Global install
+
+```bash
+npm install -g pi-acp
+```
+
+```json
+  "agent_servers": {
+    "pi": {
+      "type": "custom",
+      "command": "pi-acp",
+      "args": [],
+      "env": {}
+    }
+  }
+```
+
+#### From source
+
+```bash
+npm install
+npm run build
+```
+
+Point your ACP client to the built `dist/index.js`:
+
+```json
+  "agent_servers": {
+    "pi": {
+      "type": "custom",
+      "command": "node",
+      "args": ["/path/to/pi-acp/dist/index.js"],
+      "env": {}
+    }
+  }
+```
+
+### Environment variables
+
+- `PI_ACP_ENABLE_EMBEDDED_CONTEXT=true` advertises ACP `promptCapabilities.embeddedContext` support to the client.
+- Default: unset/any other value means `false`.
+- When disabled, compliant ACP clients should avoid sending embedded `resource` blocks. If they send them anyway, `pi-acp` still degrades gracefully by converting them into plain-text prompt context.
+
+You can add the environment variable in the Zed settings with:
+
+```json
+  "agent_servers": {
+    "pi": {
+      "type": "custom",
+      "command": "node",
+      "args": ["/path/to/pi-acp/dist/index.js"],
+      "env": {
+          "PI_ACP_ENABLE_EMBEDDED_CONTEXT": "true",
+      }
+    }
+  }
+```
+
+### Slash commands
+
+`pi-acp` supports slash commands:
+
+#### 1) File-based commands (aka prompts)
+
+Loaded from:
+
+- User commands: `~/.pi/agent/prompts/**/*.md`
+- Project commands: `<cwd>/.pi/prompts/**/*.md`
+
+#### 2) Built-in commands
+
+- `/compact [instructions...]` – run pi compaction (optionally with custom instructions)
+- `/autocompact on|off|toggle` – toggle automatic compaction
+- `/export` – export the current session to HTML in the session `cwd`
+- `/session` – show session stats (tokens/messages/cost/session file)
+- `/name <name>` – set session display name
+- `/queue all|one-at-a-time` – set pi queue mode (unstable feature)
+- `/changelog` – print the installed pi changelog (best-effort)
+- `/steering` - maps to `pi` Steering Mode, get/set
+- `/follow-up` - pats to `pi` Follow-up Mode, get/set
+
+Other built-in commands:
+
+- `/model` - not implemented (use the model selector UI in Zed)
+- `/thinking` - maps to 'mode' selector in Zed
+- `/clear` - not implemented (use ACP client 'new' command)
+
+#### 3) Skill commands
+
+- Skill commands can be enabled in pi settings and will appear in the slash command list in ACP client as `/skill:skill-name`.
+
+**Note**: Slash commands provided by pi extensions are not currently supported.
+
+## Authentication (ACP Registry support)
+
+This agent supports **Terminal Auth** for the [ACP Registry](https://agentclientprotocol.com/get-started/registry).
+In Zed, this will show an **Authenticate** banner that launches pi in a terminal.
+Launch pi in a terminal for interactive login/setup:
+
+```bash
+pi-acp --terminal-login
+```
+
+Your ACP client can also invoke this automatically based on the agent's advertised `authMethods`.
+
+## Development
+
+```bash
+npm install
+npm run dev        # run from src via tsx
+npm run build
+npm run lint
+npm run test
+```
+
+Project layout:
+
+- `src/acp/*` – ACP server + translation layer
+- `src/pi-rpc/*` – pi subprocess wrapper (RPC protocol)
+
+## Limitations
+
+- No ACP filesystem delegation (`fs/*`) and no ACP terminal delegation (`terminal/*`). pi reads/writes and executes locally.
+- MCP servers are accepted in ACP params and stored in session state, but not wired through to pi in this adapter. If you use [pi MCP adapter](https://github.com/nicobailon/pi-mcp-adapter) it will be available in the ACP client.
+- Assistant streaming is currently sent as `agent_message_chunk` (no separate thought stream).
+- Queue is implemented client-side and should work like pi's `one-at-a-time`
+- ~~ACP clients don't yet suport session history, but ACP sessions from `pi-acp` can be `/resume`d in pi directly~~
+
+## License
+
+MIT (see [LICENSE](LICENSE)).

package/port/oracle/pi-acp/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "pi-acp",
+  "version": "0.0.34",
+  "description": "ACP adapter for pi coding agent",
+  "license": "MIT",
+  "author": "Sergii Kozak <svkozak@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/svkozak/pi-acp.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bugs": {
+    "url": "https://github.com/svkozak/pi-acp/issues"
+  },
+  "homepage": "https://github.com/svkozak/pi-acp#readme",
+  "keywords": [
+    "acp",
+    "agent-client-protocol",
+    "pi-coding-agent",
+    "adapter"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "pi-acp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsup",
+    "start": "node dist/index.js",
+    "format": "prettier . --write",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "smoke": "node scripts/smoke-acp.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^0.26.0",
+    "cross-spawn": "^7.0.6",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.17.0",
+    "globals": "^15.14.0",
+    "prettier": "^3.8.3",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.18.0"
+  }
+}