@0xsolace/plugin-acpx

An acpx-backed task and subagent plugin for ElizaOS. It wraps the acpx 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.

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.

Why

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.

plugin-acpx swaps the transport: it spawns each agent through acpx, which speaks the Agent Client Protocol and emits a typed JSON-RPC stream:

• structured tool_call / tool_call_update events instead of ANSI scraping
• cooperative cancellation via session/cancel
• crash recovery via session/load
• parallel sessions in the same workspace
• agent_message_chunk for streaming text instead of pty buffer reads
• works for codex, claude, gemini today; cursor/copilot/droid/qwen via acpx 0.7+

The plugin keeps the same action names so existing flows continue to work.

Installation

npm install @0xsolace/plugin-acpx
npm install -g acpx@latest
acpx --version

You also need at least one ACP-compatible agent CLI installed (codex, claude, or gemini) and authenticated.

Quick start

import acpPlugin from "@0xsolace/plugin-acpx";

export default {
  plugins: [acpPlugin],
};

Once 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.

Actions

| Action | Purpose | | --- | --- | | SPAWN_AGENT | Start a long-lived acpx coding-agent session. Returns data.agents[]. | | SEND_TO_AGENT | Send a prompt to a running session, await completion. | | LIST_AGENTS | List active and persisted sessions. | | STOP_AGENT | Cooperatively cancel + close a session. | | CREATE_TASK | One-shot: spawn + prompt + return. Used by nyx-style task agents. | | CANCEL_TASK | Cancel an in-flight task. |

CREATE_TASK returns a shape compatible with plugin-agent-orchestrator:

{
  data: {
    agents: [{ id, sessionId, agentType, name, workdir }],
  },
  text: "...",
}

Provider

availableAgentsProvider exposes installed/auth-status/agent-type info to the runtime state, so the model can pick the right agent type at call time.

Service

AcpxSubprocessService (exported as AcpService for short) is the core. It wraps acpx subprocess lifecycle, NDJSON parsing, session state, and event emission.

import { AcpService } from "@0xsolace/plugin-acpx";

const acp = runtime.getService("PTY_SERVICE") as AcpService;
// or: runtime.getService("ACP_SERVICE") as AcpService;

const { sessionId } = await acp.spawnSession({
  agentType: "codex",
  workdir: "/tmp/my-task",
  approvalPreset: "permissive",
});

const result = await acp.sendPrompt(sessionId, "what is 7 + 8?");
console.log(result.finalText);     // "15"
console.log(result.stopReason);    // "end_turn"
console.log(result.durationMs);    // 4864

Subscribing to events

acp.onSessionEvent((sessionId, eventName, data) => {
  // eventName: "ready" | "message" | "tool_running" | "task_complete" | "stopped" | "error" | "blocked" | "login_required" | "reconnected"
  // data shape depends on eventName, see SessionEventName in src/services/types.ts
});

The task_complete event matches plugin-agent-orchestrator's shape:

{ response: string, durationMs: number, stopReason: "end_turn" | "error" | string }

Configuration

All 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.

| Variable | Default | Purpose | | --- | --- | --- | | ELIZA_ACP_CLI | acpx | ACPX executable name or absolute path. | | ELIZA_ACP_DEFAULT_AGENT | codex | Default agent type. | | ELIZA_ACP_DEFAULT_APPROVAL | autonomous | Approval preset (read-only, auto, permissive, autonomous, full-access). | | ELIZA_ACP_PROMPT_TIMEOUT_MS | 1800000 (30m) | Per-prompt timeout. | | ELIZA_ACP_AUTH_TIMEOUT_MS | 120000 | Auth handshake timeout. | | ELIZA_ACP_STATE_DIR | ~/.eliza/plugin-acpx | Where to persist session state when no runtime DB. | | ELIZA_ACP_WORKSPACE_ROOT | runtime cwd | Base directory for spawned agent workdirs. | | ELIZA_ACP_LOG_LEVEL | info | debug | info | warn | error. | | ELIZA_ACP_MAX_SESSIONS | unlimited | Concurrent session cap. | | ELIZA_ACP_REGISTER_AS_PTY_SERVICE | true | Register service under PTY_SERVICE alias for back-compat. |

Persistence

Session state is persisted with a tiered backend:

1. If runtime.databaseAdapter exposes SQL methods, sessions live in acp_sessions table.
2. Otherwise, JSON file at $ELIZA_ACP_STATE_DIR/sessions.json (atomic writes via temp+rename).
3. Last resort: in-memory Map (warns that sessions won't survive restart).

End-to-end smoke test

The repo ships with a real e2e smoke at tests/e2e/acp-codex-smoke.mjs:

npm install -g acpx@latest
# authenticate codex first
npm run build
node tests/e2e/acp-codex-smoke.mjs

It 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.

Compatibility with @elizaos/plugin-agent-orchestrator

You 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.

Status

0.1.0-rc.1. Alpha, but every layer is implemented and tested:

• 9 test files, 38 unit tests, 100% passing
• real e2e smoke against acpx + codex passes
• nyx-compatible CREATE_TASK + PTY_SERVICE alias

What's deferred to later versions:

• provision_workspace / finalize_workspace (use git directly for now)
• manage_issues / GitHub integration
• swarm-coordinator (sibling-to-sibling agent comms)
• aider, pi, replit-agent (waiting for acpx coverage)

Contributing

PRs welcome. Run npm run typecheck && npm test before opening.

License

MIT. See LICENSE.