{"_id":"@csookermany/paperclip-plugin-acp","name":"@csookermany/paperclip-plugin-acp","dist-tags":{"latest":"0.2.4"},"versions":{"0.2.4":{"name":"@csookermany/paperclip-plugin-acp","version":"0.2.4","type":"module","main":"./dist/index.js","paperclipPlugin":{"manifest":"./dist/manifest.js","worker":"./dist/worker.js"},"scripts":{"build":"tsc","typecheck":"tsc --noEmit","dev":"tsc --watch","test":"vitest run","prepublishOnly":"npm run build"},"peerDependencies":{"@paperclipai/plugin-sdk":"*","@paperclipai/shared":"*"},"devDependencies":{"@paperclipai/plugin-sdk":"^2026.318.0","@paperclipai/shared":"^2026.318.0","@types/node":"^25.5.0","typescript":"^5.7.0","vitest":"^3.0.0"},"repository":{"type":"git","url":"git+https://github.com/mvanhorn/paperclip-plugin-acp.git"},"license":"MIT","_id":"@csookermany/paperclip-plugin-acp@0.2.4","gitHead":"b0466f0b691e1b9723f50311690cfec62815e8e4","types":"./dist/index.d.ts","description":"[![npm](https://img.shields.io/npm/v/paperclip-plugin-acp)](https://www.npmjs.com/package/paperclip-plugin-acp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)","bugs":{"url":"https://github.com/mvanhorn/paperclip-plugin-acp/issues"},"homepage":"https://github.com/mvanhorn/paperclip-plugin-acp#readme","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-panxUqvy5AXPCPWHwUviE85aLIulu85ShP2IAeV3pFKnXo2klTk2m7avpnnM/tdWYGZYOpQ0rACd7yG2nSDcdw==","shasum":"c8038fe809347f7d16951738f50c35725a91f159","tarball":"https://registry.npmjs.org/@csookermany/paperclip-plugin-acp/-/paperclip-plugin-acp-0.2.4.tgz","fileCount":35,"unpackedSize":85251,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHPK044tQvEBWXdD0ljDSMxb/8fg/pGbL5R/DECAETxVAiEAlDXX3/gUTIryyoTu81kNDAV4zP8AemboUHMmdJl46Tw="}]},"_npmUser":{"name":"csookermany","email":"hello@valueinstituteai.com"},"directories":{},"maintainers":[{"name":"csookermany","email":"hello@valueinstituteai.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/paperclip-plugin-acp_0.2.4_1774871296812_0.9680340931723934"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-30T11:48:16.709Z","0.2.4":"2026-03-30T11:48:16.963Z","modified":"2026-03-30T11:48:17.169Z"},"maintainers":[{"name":"csookermany","email":"hello@valueinstituteai.com"}],"description":"[![npm](https://img.shields.io/npm/v/paperclip-plugin-acp)](https://www.npmjs.com/package/paperclip-plugin-acp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)","homepage":"https://github.com/mvanhorn/paperclip-plugin-acp#readme","repository":{"type":"git","url":"git+https://github.com/mvanhorn/paperclip-plugin-acp.git"},"bugs":{"url":"https://github.com/mvanhorn/paperclip-plugin-acp/issues"},"license":"MIT","readme":"# paperclip-plugin-acp\n\n[![npm](https://img.shields.io/npm/v/paperclip-plugin-acp)](https://www.npmjs.com/package/paperclip-plugin-acp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nACP (Agent Client Protocol) runtime plugin for [Paperclip](https://github.com/paperclipai/paperclip). Run Claude Code, Codex, Gemini CLI, and other coding agents from any chat platform through thread-bound sessions.\n\nBuilt on the Paperclip plugin SDK.\n\n## Why this exists\n\nPaperclip's chat plugins (Telegram, Discord, Slack) let users interact with agents through messaging platforms, but they need a runtime to actually spawn and manage coding agent processes. The ACP plugin is that runtime - it bridges chat messages to subprocess-managed coding agents over stdio, following the [Agent Client Protocol](https://agentclientprotocol.com/) standard created by Zed Industries.\n\nWithout this plugin, the `/acp spawn`, `/acp status`, and `/acp close` commands in the chat plugins have nothing to connect to.\n\n## What it does\n\n### Agent lifecycle management\n- **Spawn agents** as subprocesses over stdio from any chat platform\n- **Persistent sessions** - agents stay alive for follow-up prompts within the same thread\n- **Oneshot mode** - single-task sessions that auto-close after completion\n- **Idle timeout** - sessions close after 30 min of inactivity (configurable)\n- **Max age** - sessions close after 8 hours regardless of activity (configurable)\n- **Graceful shutdown** - SIGTERM with cleanup of thread bindings and state\n\n### 1:N session support\n- A single chat thread can run up to 5 concurrent agent sessions (configurable via `maxSessionsPerThread`)\n- Spawn multiple agents in the same thread - for example, Claude Code reviewing while Codex implements\n- Route messages to specific sessions by session ID\n- Active sessions tracked per-thread as an array; closed/errored sessions don't count toward the cap\n- The `acp_status` tool lists all active sessions with uptime, idle time, and binding info\n\n### Supported agents\n\n| Agent | Command | Status |\n|-------|---------|--------|\n| Claude Code | `claude` | Supported |\n| Codex CLI | `codex` | Supported |\n| Gemini CLI | `gemini` | Supported |\n| OpenCode | `opencode` | Supported |\n\nAgents must be installed on the Paperclip server. The plugin spawns them as subprocesses.\n\n### Cross-plugin event system\n\nChat plugins communicate with the ACP plugin via namespaced events on Paperclip's event bus. Each platform plugin emits events under its own namespace:\n\n```\nplugin.paperclip-plugin-telegram.acp-spawn\nplugin.paperclip-plugin-slack.acp-message\nplugin.paperclip-plugin-discord.acp-close\n```\n\n**Inbound events (chat plugin -> ACP)**\n\n| Event suffix | Payload | Description |\n|-------------|---------|-------------|\n| `acp-spawn` | `{ agentName, chatId, threadId, companyId, cwd?, mode? }` | Spawn an agent session bound to a thread |\n| `acp-message` | `{ sessionId, text }` | Send a prompt to a running session |\n| `acp-cancel` | `{ sessionId }` | SIGINT the current turn |\n| `acp-close` | `{ sessionId }` | SIGTERM and remove the session |\n\n**Outbound events (ACP -> chat plugin)**\n\n| Event | Payload | Description |\n|-------|---------|-------------|\n| `output` | `{ sessionId, type, text?, error?, chatId, threadId }` | Agent output routed back to the originating thread |\n\nThe ACP plugin registers listeners for all three platforms (Telegram, Slack, Discord) on startup. Adding a new platform requires adding its plugin ID to `CHAT_PLATFORM_PLUGINS` in `constants.ts`.\n\n### Lazy migration from 1:1 format\nExisting threads that used the old 1:1 binding format (`acp_{chatId}_{threadId}` key) are migrated automatically on first access. The old key is read, converted to a single-entry sessions array under the new `acp_sessions_{chatId}_{threadId}` key, and the old key is deleted. No manual migration needed.\n\n## Install\n\n```bash\nnpm install paperclip-plugin-acp\n```\n\nOr register with your Paperclip instance directly:\n\n```bash\ncurl -X POST http://127.0.0.1:3100/api/plugins/install \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"packageName\":\"paperclip-plugin-acp\"}'\n```\n\n## Configuration\n\n| Setting | Default | Description |\n|---------|---------|-------------|\n| `enabledAgents` | `claude,codex,gemini,opencode` | Comma-separated list of enabled agents |\n| `defaultAgent` | `claude` | Agent used when none specified |\n| `defaultMode` | `persistent` | `persistent` (stays alive) or `oneshot` (single task) |\n| `defaultCwd` | `/workspace` | Working directory for spawned agents |\n| `sessionIdleTimeoutMs` | `1800000` | Close idle sessions after 30 min |\n| `sessionMaxAgeMs` | `28800000` | Close sessions after 8 hours |\n| `maxSessionsPerThread` | `5` | Max concurrent sessions per chat thread |\n\n## Agent tools\n\nThe plugin exposes these tools to Paperclip agents:\n\n| Tool | Description |\n|------|-------------|\n| `acp_spawn` | Start a new coding agent session (agent, mode, cwd, initial prompt) |\n| `acp_status` | List active sessions with uptime, idle time, and binding info |\n| `acp_send` | Send a prompt to an active session |\n| `acp_cancel` | Cancel the current turn (SIGINT) |\n| `acp_close` | Close a session and remove thread bindings |\n\n## How it works\n\n```\nChat message (Telegram/Discord/Slack)\n    -> Chat plugin emits acp:spawn / acp:message event\n    -> ACP plugin routes to bound session\n    -> Coding agent subprocess (stdio)\n    -> Agent output emitted as acp:output event\n    -> Chat plugin sends response to thread\n```\n\n## Development\n\n```bash\npnpm install\npnpm typecheck\npnpm test\npnpm build\n```\n\n~50 tests covering session lifecycle, spawn/send/cancel/close flows, 1:N session support, idle timeout, max age, lazy migration, cross-plugin event routing, and error handling.\n\n## Contributing\n\nIssues and PRs welcome at [github.com/mvanhorn/paperclip-plugin-acp](https://github.com/mvanhorn/paperclip-plugin-acp).\n\nAuto-publishes to npm on push to `main` via OIDC trusted publishing.\n\n## Architecture reference\n\nThis plugin follows patterns from [OpenClaw's ACP implementation](https://github.com/openclaw/openclaw), which has extensive ACP support for Discord, Telegram, Slack, and Matrix with thread-bound sessions, agent spawning, and session lifecycle management.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-b3bc1156aa75d4cb7c783c3681d02215"}