{"_id":"@0xsolace/plugin-acpx","name":"@0xsolace/plugin-acpx","dist-tags":{"rc":"0.1.0-rc.1","latest":"0.1.0-rc.1"},"versions":{"0.1.0-rc.1":{"name":"@0xsolace/plugin-acpx","version":"0.1.0-rc.1","description":"acpx-backed task and subagent plugin for ElizaOS. Wraps the acpx CLI to spawn coding agents (codex/claude/gemini) as subprocesses and exposes them through ElizaOS actions.","type":"module","main":"dist/index.js","module":"dist/index.js","types":"dist/index.d.ts","exports":{"./package.json":"./package.json",".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"}}},"scripts":{"build":"tsc -p tsconfig.build.json","test":"vitest run --config ./vitest.config.ts","test:watch":"vitest --config ./vitest.config.ts","typecheck":"tsc --noEmit","format":"biome format --write .","lint":"biome check ."},"keywords":["elizaos","plugin","acpx","agent-client-protocol","coding-agent","subagent","task","milady"],"repository":{"type":"git","url":"git+https://github.com/0xSolace/plugin-acpx.git"},"author":{"name":"@stwd / 0xSolace"},"license":"MIT","engines":{"node":">=20"},"peerDependencies":{"@elizaos/core":"*"},"devDependencies":{"@biomejs/biome":"^2.2.0","@elizaos/core":"*","@types/node":"^25.2.3","typescript":"^6.0.0","vitest":"^4.0.0"},"gitHead":"67d6e7ccea3657aa71933fff484901d227c7a049","_id":"@0xsolace/plugin-acpx@0.1.0-rc.1","bugs":{"url":"https://github.com/0xSolace/plugin-acpx/issues"},"homepage":"https://github.com/0xSolace/plugin-acpx#readme","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-tFRSgIGwUgOgvpeIRvd+dB5LTWcFVJvtXO44B9ZNP7c47EEFb1dnBocJH3XJh2EjdgUta830agX3lQpTX/LwXQ==","shasum":"dfc45bf1888f817fbb8f916f600a9bda1d602153","tarball":"https://registry.npmjs.org/@0xsolace/plugin-acpx/-/plugin-acpx-0.1.0-rc.1.tgz","fileCount":59,"unpackedSize":226793,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCEyC+IwC4OM/8/a2WP4D/oRNYZNhsHKVpoVqaHFplXTAIhANpjo5DsU31AyocTcE4m6s6+VMo6fcN9tuyYb5AgCcAf"}]},"_npmUser":{"name":"0xsolace","email":"sol@shad0w.xyz"},"directories":{},"maintainers":[{"name":"0xsolace","email":"sol@shad0w.xyz"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/plugin-acpx_0.1.0-rc.1_1777812507612_0.17287467312183424"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-03T12:48:27.508Z","0.1.0-rc.1":"2026-05-03T12:48:27.759Z","modified":"2026-05-03T12:48:28.014Z"},"maintainers":[{"name":"0xsolace","email":"sol@shad0w.xyz"}],"description":"acpx-backed task and subagent plugin for ElizaOS. Wraps the acpx CLI to spawn coding agents (codex/claude/gemini) as subprocesses and exposes them through ElizaOS actions.","homepage":"https://github.com/0xSolace/plugin-acpx#readme","keywords":["elizaos","plugin","acpx","agent-client-protocol","coding-agent","subagent","task","milady"],"repository":{"type":"git","url":"git+https://github.com/0xSolace/plugin-acpx.git"},"author":{"name":"@stwd / 0xSolace"},"bugs":{"url":"https://github.com/0xSolace/plugin-acpx/issues"},"license":"MIT","readme":"# @0xsolace/plugin-acpx\n\n[![npm version](https://img.shields.io/npm/v/@0xsolace/plugin-acpx.svg)](https://www.npmjs.com/package/@0xsolace/plugin-acpx)\n[![license](https://img.shields.io/npm/l/@0xsolace/plugin-acpx.svg)](./LICENSE)\n\nAn **acpx-backed task and subagent plugin** for ElizaOS. It wraps the [`acpx`](https://github.com/0xouroboros/acp) CLI to spawn local coding agents (codex, claude, gemini, ...) as background sessions and exposes them through ElizaOS actions. Drop-in compatible with `@elizaos/plugin-agent-orchestrator`'s action surface, but uses structured Agent Client Protocol (ACP) events under the hood instead of PTY scraping.\n\n> Naming: this plugin is *not* the same thing as `@elizaos/plugin-acp`. That package is Shaw's ACP gateway client (IDE bridge over a remote ACP gateway). `@0xsolace/plugin-acpx` is the *task backend* that uses `acpx` to run coding agents as subprocesses on the same host as the runtime.\n\n## Why\n\n`plugin-agent-orchestrator` runs each coding agent (codex, claude, gemini, ...) inside a pseudo-terminal and parses ANSI escape codes, prompt regexes, and stall heuristics. It works, but it inherits every quirk of every agent's terminal UI.\n\n`plugin-acpx` swaps the transport: it spawns each agent through `acpx`, which speaks the [Agent Client Protocol](https://agentclientprotocol.com/) and emits a typed JSON-RPC stream:\n\n- structured `tool_call` / `tool_call_update` events instead of ANSI scraping\n- cooperative cancellation via `session/cancel`\n- crash recovery via `session/load`\n- parallel sessions in the same workspace\n- `agent_message_chunk` for streaming text instead of pty buffer reads\n- works for codex, claude, gemini today; cursor/copilot/droid/qwen via acpx 0.7+\n\nThe plugin keeps the same action names so existing flows continue to work.\n\n## Installation\n\n```bash\nnpm install @0xsolace/plugin-acpx\nnpm install -g acpx@latest\nacpx --version\n```\n\nYou also need at least one ACP-compatible agent CLI installed (`codex`, `claude`, or `gemini`) and authenticated.\n\n## Quick start\n\n```ts\nimport acpPlugin from \"@0xsolace/plugin-acpx\";\n\nexport default {\n  plugins: [acpPlugin],\n};\n```\n\nOnce loaded, the plugin registers `AcpxSubprocessService` (`AcpService` for short, also aliased as `PTY_SERVICE` for back-compat with `plugin-agent-orchestrator` consumers), six actions, and one provider.\n\n## Actions\n\n| Action | Purpose |\n| --- | --- |\n| `SPAWN_AGENT` | Start a long-lived acpx coding-agent session. Returns `data.agents[]`. |\n| `SEND_TO_AGENT` | Send a prompt to a running session, await completion. |\n| `LIST_AGENTS` | List active and persisted sessions. |\n| `STOP_AGENT` | Cooperatively cancel + close a session. |\n| `CREATE_TASK` | One-shot: spawn + prompt + return. Used by nyx-style task agents. |\n| `CANCEL_TASK` | Cancel an in-flight task. |\n\n`CREATE_TASK` returns a shape compatible with `plugin-agent-orchestrator`:\n\n```ts\n{\n  data: {\n    agents: [{ id, sessionId, agentType, name, workdir }],\n  },\n  text: \"...\",\n}\n```\n\n## Provider\n\n`availableAgentsProvider` exposes installed/auth-status/agent-type info to the runtime state, so the model can pick the right agent type at call time.\n\n## Service\n\n`AcpxSubprocessService` (exported as `AcpService` for short) is the core. It wraps acpx subprocess lifecycle, NDJSON parsing, session state, and event emission.\n\n```ts\nimport { AcpService } from \"@0xsolace/plugin-acpx\";\n\nconst acp = runtime.getService(\"PTY_SERVICE\") as AcpService;\n// or: runtime.getService(\"ACP_SERVICE\") as AcpService;\n\nconst { sessionId } = await acp.spawnSession({\n  agentType: \"codex\",\n  workdir: \"/tmp/my-task\",\n  approvalPreset: \"permissive\",\n});\n\nconst result = await acp.sendPrompt(sessionId, \"what is 7 + 8?\");\nconsole.log(result.finalText);     // \"15\"\nconsole.log(result.stopReason);    // \"end_turn\"\nconsole.log(result.durationMs);    // 4864\n```\n\n### Subscribing to events\n\n```ts\nacp.onSessionEvent((sessionId, eventName, data) => {\n  // eventName: \"ready\" | \"message\" | \"tool_running\" | \"task_complete\" | \"stopped\" | \"error\" | \"blocked\" | \"login_required\" | \"reconnected\"\n  // data shape depends on eventName, see SessionEventName in src/services/types.ts\n});\n```\n\nThe `task_complete` event matches `plugin-agent-orchestrator`'s shape:\n\n```ts\n{ response: string, durationMs: number, stopReason: \"end_turn\" | \"error\" | string }\n```\n\n## Configuration\n\nAll configuration is via environment variables. Sensible defaults; most users only need `ELIZA_ACP_CLI` if `acpx` is not on `PATH`. The `ELIZA_ACP_*` prefix is named after the protocol; the package itself wraps the `acpx` CLI.\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `ELIZA_ACP_CLI` | `acpx` | ACPX executable name or absolute path. |\n| `ELIZA_ACP_DEFAULT_AGENT` | `codex` | Default agent type. |\n| `ELIZA_ACP_DEFAULT_APPROVAL` | `autonomous` | Approval preset (`read-only`, `auto`, `permissive`, `autonomous`, `full-access`). |\n| `ELIZA_ACP_PROMPT_TIMEOUT_MS` | `1800000` (30m) | Per-prompt timeout. |\n| `ELIZA_ACP_AUTH_TIMEOUT_MS` | `120000` | Auth handshake timeout. |\n| `ELIZA_ACP_STATE_DIR` | `~/.eliza/plugin-acpx` | Where to persist session state when no runtime DB. |\n| `ELIZA_ACP_WORKSPACE_ROOT` | runtime cwd | Base directory for spawned agent workdirs. |\n| `ELIZA_ACP_LOG_LEVEL` | `info` | `debug` \\| `info` \\| `warn` \\| `error`. |\n| `ELIZA_ACP_MAX_SESSIONS` | unlimited | Concurrent session cap. |\n| `ELIZA_ACP_REGISTER_AS_PTY_SERVICE` | `true` | Register service under `PTY_SERVICE` alias for back-compat. |\n\n## Persistence\n\nSession state is persisted with a tiered backend:\n\n1. If `runtime.databaseAdapter` exposes SQL methods, sessions live in `acp_sessions` table.\n2. Otherwise, JSON file at `$ELIZA_ACP_STATE_DIR/sessions.json` (atomic writes via temp+rename).\n3. Last resort: in-memory `Map` (warns that sessions won't survive restart).\n\n## End-to-end smoke test\n\nThe repo ships with a real e2e smoke at `tests/e2e/acp-codex-smoke.mjs`:\n\n```bash\nnpm install -g acpx@latest\n# authenticate codex first\nnpm run build\nnode tests/e2e/acp-codex-smoke.mjs\n```\n\nIt spawns a real codex session, sends \"what is 7 + 8?\", and verifies `task_complete` fires with response `\"15\"`. Useful as a sanity check before integrating into a real runtime.\n\n## Compatibility with `@elizaos/plugin-agent-orchestrator`\n\nYou can run both plugins side-by-side. The actions don't conflict by name; they are dispatched by description matching, not name collision. To make `runtime.getService(\"PTY_SERVICE\")` return the acpx subprocess service, set `ELIZA_ACP_REGISTER_AS_PTY_SERVICE=true` (default) and don't load `plugin-agent-orchestrator`. To use both, set `ELIZA_ACP_REGISTER_AS_PTY_SERVICE=false` and let the orchestrator own the `PTY_SERVICE` alias.\n\n## Status\n\n`0.1.0-rc.1`. Alpha, but every layer is implemented and tested:\n\n- 9 test files, 38 unit tests, 100% passing\n- real e2e smoke against `acpx` + codex passes\n- nyx-compatible `CREATE_TASK` + `PTY_SERVICE` alias\n\nWhat's deferred to later versions:\n\n- `provision_workspace` / `finalize_workspace` (use git directly for now)\n- `manage_issues` / GitHub integration\n- swarm-coordinator (sibling-to-sibling agent comms)\n- aider, pi, replit-agent (waiting for acpx coverage)\n\n## Contributing\n\nPRs welcome. Run `npm run typecheck && npm test` before opening.\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n","readmeFilename":"README.md","_rev":"1-bfe98ed592d9a96d579feaaf5ec6b758"}