@elizaos/plugin-agent-orchestrator 2.0.0-alpha.8 → 2.0.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+## 0.2.0 (unreleased)
+
+Consolidated ACP-based spawn, PTY sessions, and workspace services into
+a single package at `plugins/plugin-agent-orchestrator`. Internal
+`@elizaos/plugin-acpx` callers were rewritten to the consolidated package.
+
+### Added
+
+- `SubAgentRouter` service: subscribes to `AcpService.onSessionEvent`,
+  posts terminal events (`task_complete`, `error`, `blocked`) as
+  synthetic inbound memories addressed to the original
+  `roomId`/`userId`/`messageId` captured at spawn time. Lets the main
+  agent's normal action layer decide `REPLY` / `SEND_TO_AGENT` / both.
+- `activeSubAgentsProvider`: cache-stable view of routed sub-agent
+  sessions. Sorted by sessionId, structural-only fields, status bucketing
+  (`ready`/`running`/`busy`/`tool_running`/`authenticating` → `"active"`)
+  so transient flips don't invalidate the prefix cache.
+- Round-trip cap: per-session inject counter; force-stops after
+  `ACPX_SUB_AGENT_ROUND_TRIP_CAP` (default 32) and surfaces a single
+  `round_trip_cap_exceeded` notice with `subAgentRoundTrip` /
+  `subAgentRoundTripCap` / `subAgentCapExceeded: true`.
+- Live e2e test (`__tests__/live/sub-agent-router.live.test.ts`) gated on
+  `RUN_LIVE_ACPX=1` plus `acpx --version`.
+- `spawnAgentAction` now threads `source: content.source` into spawn
+  metadata for parity with `createTaskAction`.
+
+### Changed
+
+- Package renamed from `@elizaos/plugin-acpx` → `@elizaos/plugin-agent-orchestrator`.
+- `SubAgentRouter` derives the per-session sub-agent UUID locally via SHA1
+  instead of importing `createUniqueUuid` from `@elizaos/core`. This keeps
+  the router's import surface type-only.
+- Browser build dropped: this package owns Node-only services
+  (`PTYService`, `CodingWorkspaceService`, child_process spawn).
+
+### Fixed
+
+- `task-agent-frameworks.ts` `normalizeTaskAgentAdapterForModelPrefs`:
+  removed three duplicate switch cases (`opencode` / `open-code` /
+  `open code`) that were dead code after the matching cases earlier in
+  the same switch.
+- Greptile-flagged bugs from PR #7463 (already on develop pre-rename):
+  `"errored"` → `"error"` status normalization,
+  `listSessions`/`getSession` for FileSessionStore + RuntimeDbSessionStore,
+  `enforceSessionLimit` excluding both `"error"` and `"errored"`.
+
+### Deprecated
+
+- `swarm-coordinator.ts` and the entire `swarm-*` / `pty-*` family are
+  retained for callers that still depend on `PTYService`, but are
+  dormant for ACP-spawned sessions. Retiring them is a follow-up
+  cleanup; new work should use `AcpService` + `SubAgentRouter`.
+
+## 0.1.0
+
+Pre-consolidation. Bootstrap package scaffold for `@elizaos/plugin-acpx`
+under its original name. Initial ACP subprocess service, session store
+adapters, six canonical actions (`CREATE_TASK`, `SPAWN_AGENT`,
+`SEND_TO_AGENT`, `STOP_AGENT`, `LIST_AGENTS`, `CANCEL_TASK`), and the
+`availableAgentsProvider`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 @stwd / 0xSolace
+
+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/PROJECT.md

@@ -0,0 +1,119 @@
+# @elizaos/plugin-agent-orchestrator
+
+ElizaOS plugin: acpx-backed task and subagent backend (wraps the `acpx` CLI to spawn coding agents). Sibling, not replacement, for `@elizaos/plugin-agent-orchestrator`. Distinct from `@elizaos/plugin-acp` (Shaw's ACP gateway client).
+
+Drop-in compatible with `@elizaos/plugin-agent-orchestrator` (PTY-based). Uses
+ACPX (Agent Client Protocol CLI) under the hood for structured streaming,
+named sessions, cooperative cancel, and crash-resilient sessions.
+
+## Why this exists
+
+`plugin-agent-orchestrator` (sibling, PTY-based) maintains an entire
+stall-classifier, ANSI-stripping, prompt-regex-dismissal, pty-state-capture
+stack to extract structure out of terminal byte streams. The Agent Client Protocol (ACP) is the structured
+protocol underneath, `tool_call`, `thinking`, `diff`, `done` events, typed
+auth handshake, cooperative `session/cancel`. ACPX provides one CLI surface
+across 15 Agent Client Protocol (ACP)-compatible coding agents (codex, claude-code, gemini, copilot,
+cursor, droid, local Eliza-1 agents, etc).
+
+This plugin is a sibling-not-replacement: deploys alongside
+`plugin-agent-orchestrator`, exposes the same action names so users can switch
+transports by swapping the plugin import.
+
+## Goals
+
+- Drop-in action surface compatible with `plugin-agent-orchestrator`
+- ACPX subprocess transport (NDJSON streaming, no pty)
+- Configurable cli binary (`ELIZA_ACP_CLI=acpx`, override possible)
+- Persistent named sessions (eliza-runtime-table-backed)
+- Cooperative cancel + crash reconnect
+- 80%+ unit test coverage
+- Parity smoke vs plugin-agent-orchestrator on at least codex
+- Publishable to npm under `@elizaos`
+
+## Non-goals
+
+- Replace plugin-agent-orchestrator (sibling, not replacement)
+- Git workspace provisioning (PROVISION_WORKSPACE / FINALIZE_WORKSPACE)
+- Frontend xterm view
+- Non-codex agent support in v0.1.0 (codex first; claude/gemini in 0.2.0+)
+
+## Action surface
+
+Match `plugin-agent-orchestrator` exactly:
+
+| Action | Purpose |
+|---|---|
+| `SPAWN_AGENT` | Spawn an acpx coding-agent session |
+| `SEND_TO_AGENT` | Send prompt or input to running session |
+| `LIST_AGENTS` | List active sessions |
+| `STOP_AGENT` | Terminate session via session/cancel |
+| `CREATE_TASK` | Async task (spawn + first prompt + return when done) |
+| `CANCEL_TASK` | Cooperative cancel |
+
+## Provider
+
+`availableAgents` provider exposes which Agent Client Protocol (ACP)-compatible agents are installed.
+
+## Architecture
+
+```
+┌─────────────────────────┐
+│ Eliza runtime           │
+│  ├─ actions (SPAWN, ..) │
+│  └─ provider (available)│
+└──────────┬──────────────┘
+           │
+┌──────────v──────────────┐
+│ AcpService              │
+│  - spawn `acpx` proc    │
+│  - parse NDJSON stream  │
+│  - emit typed events    │
+│  - cancel via session/  │
+└──────────┬──────────────┘
+           │
+┌──────────v──────────────┐
+│ acpx (cli subprocess)   │
+│  --format json          │
+│  codex / claude / etc   │
+└─────────────────────────┘
+```
+
+## Reference materials
+
+- `acpx-docs/README.md`, acpx README
+- `acpx-docs/docs_CLI.md`, full acpx CLI reference
+- `acpx-docs/skills_acpx_SKILL.md`, skill reference
+
+## Layout
+
+```
+src/
+  index.ts              # plugin export
+  actions/
+    spawn-agent.ts
+    send-to-agent.ts
+    list-agents.ts
+    stop-agent.ts
+    create-task.ts
+    cancel-task.ts
+  providers/
+    available-agents.ts
+  services/
+    acp-service.ts      # core ACPX wrapper
+    session-store.ts    # persistent session state
+    types.ts            # acpx event types
+  __tests__/
+    *.test.ts
+docs/
+  sub-agent-routing.md
+PROJECT.md              # this file
+```
+
+## Status
+
+🚧 Bootstrapping, wave A in progress.
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,160 @@
+# @elizaos/plugin-agent-orchestrator
+
+[![npm version](https://img.shields.io/npm/v/@elizaos/plugin-agent-orchestrator.svg)](https://www.npmjs.com/package/@elizaos/plugin-agent-orchestrator)
+[![CI](https://github.com/elizaos/eliza/actions/workflows/ci.yml/badge.svg)](https://github.com/elizaos/eliza/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+The canonical orchestration plugin for ElizaOS task agents. Spawns local coding agents (codex, claude, gemini, ...) via the [`acpx`](https://github.com/0xouroboros/acp) CLI using the structured Agent Client Protocol, routes their output back through the runtime so the main agent decides what to do, and bundles workspace lifecycle, GitHub PR integration, task share, and supporting services in a single package.
+
+> 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). `@elizaos/plugin-agent-orchestrator` is the *task backend* that uses `acpx` to run coding agents as subprocesses on the same host as the runtime.
+
+## What it does
+
+The plugin combines three concerns:
+
+1. **Spawn** coding agents via ACP. The ACP path uses typed JSON-RPC events — `tool_call` / `tool_call_update`, `agent_message_chunk`, cooperative `session/cancel`, parallel sessions in the same workspace, recoverable via `session/load`.
+2. **Route** sub-agent terminal events (`task_complete`, `error`, `blocked`) back into the runtime as synthetic inbound messages addressed to the original `roomId`/`userId`/`messageId`. The main agent's normal action layer then decides whether to `REPLY` to the user, `SEND_TO_AGENT` to push the sub-agent further, or both. See [`docs/sub-agent-routing.md`](./docs/sub-agent-routing.md).
+3. **Coordinate** workspace lifecycle (clone, branch, commit, push, PR open) and GitHub issue management for repo-hosted tasks.
+
+## Installation
+
+```bash
+npm install @elizaos/plugin-agent-orchestrator
+npm install -g acpx@latest
+acpx --version
+```
+
+You also need at least one ACP-compatible agent CLI (`codex`, `claude`, or `gemini`) installed and authenticated.
+
+## Quick start
+
+```ts
+import agentOrchestratorPlugin from "@elizaos/plugin-agent-orchestrator";
+
+export default {
+  plugins: [agentOrchestratorPlugin],
+};
+```
+
+## Action surface
+
+| Action | Purpose |
+| --- | --- |
+| `ACPX_CREATE_TASK` (`CREATE_TASK`) | One-shot: spawn + prompt + return. Captures origin metadata for routing. |
+| `SPAWN_AGENT` | Start a long-lived ACP coding-agent session. Returns `data.agents[]`. |
+| `SEND_TO_AGENT` | Send a follow-up prompt to a running session. The main agent uses this to push a sub-agent further when its proof is unsatisfying. |
+| `STOP_AGENT` | Cooperatively cancel + close a session. |
+| `LIST_AGENTS` | List active and persisted sessions. |
+| `CANCEL_TASK` | Cancel an in-flight task while preserving history. |
+| `TASK_HISTORY` / `TASK_CONTROL` / `TASK_SHARE` | Task lifecycle ops over the coordinator surface. |
+| `PROVISION_WORKSPACE` / `FINALIZE_WORKSPACE` | Git workspace setup, commit, push, PR open. |
+| `MANAGE_ISSUES` | GitHub issue create/list/update/close. |
+
+## Providers
+
+- `AVAILABLE_AGENTS` — adapter inventory + raw session list.
+- `ACTIVE_SUB_AGENTS` — cache-stable view of currently-routed sub-agent sessions; sorted by sessionId, structural fields only (no timestamps, no message excerpts), so the planner-visible block stays cached across status flips.
+- `ACTIVE_WORKSPACE_CONTEXT` — live workspace/session state.
+- `CODING_AGENT_EXAMPLES` — structured action call examples.
+
+## Services
+
+- `AcpService` — ACP subprocess lifecycle, NDJSON parsing, session state, event emission. Registers under `ACP_SUBPROCESS_SERVICE`.
+- `SubAgentRouter` (canonical) — subscribes to `AcpService.onSessionEvent`, posts terminal-event synthetic memories to `runtime.messageService.handleMessage`. Per-session round-trip cap (`ACPX_SUB_AGENT_ROUND_TRIP_CAP`, default 32) force-stops runaway loops. Disable with `ACPX_SUB_AGENT_ROUTER_DISABLED=1`.
+- `PTYService` — PTY-based spawn surface. Bound to `pty-manager`.
+- `CodingWorkspaceService` — git workspace lifecycle helpers.
+
+```ts
+import { AcpService, SubAgentRouter } from "@elizaos/plugin-agent-orchestrator";
+
+const acp = runtime.getService("ACP_SUBPROCESS_SERVICE") as AcpService;
+
+const { sessionId } = await acp.spawnSession({
+  agentType: "codex",
+  workdir: "/tmp/my-task",
+  approvalPreset: "permissive",
+  metadata: {
+    roomId: message.roomId,
+    userId: message.entityId,
+    messageId: message.id,
+    label: "fix bug 42",
+  },
+});
+
+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
+
+```ts
+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:
+
+```ts
+{ response: string, durationMs: number, stopReason: "end_turn" | "error" | string }
+```
+
+You usually don't subscribe directly — `SubAgentRouter` already does, and routes terminal events into the runtime. Subscribe only if you need raw access (e.g. dashboards).
+
+## Configuration
+
+All configuration is via environment variables. Sensible defaults; most users only need `ELIZA_ACP_CLI` if `acpx` is not on `PATH`.
+
+| 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` / `ACPX_DEFAULT_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. |
+| `ACPX_DEFAULT_CWD` | runtime cwd | Base directory for spawned agent workdirs. |
+| `ELIZA_ACP_LOG_LEVEL` | `info` | `debug` \| `info` \| `warn` \| `error`. |
+| `ELIZA_ACP_MAX_SESSIONS` | `8` | Concurrent session cap. |
+| `ACPX_SUB_AGENT_ROUTER_DISABLED` | unset | Set to `1` to keep the router service registered but unbound (test/staging). |
+| `ACPX_SUB_AGENT_ROUND_TRIP_CAP` | `32` | Per-session inject cap before force-stop to prevent ping-pong loops. |
+
+## Persistence
+
+Session state is persisted with a tiered backend:
+
+1. If `runtime.databaseAdapter` exposes SQL methods, sessions live in the `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 tests
+
+Two smokes ship with the repo:
+
+```bash
+# Raw AcpService against installed acpx + codex:
+npm install -g acpx@latest
+# authenticate codex first
+npm run build
+node tests/e2e/acp-codex-smoke.mjs
+
+# Full router loop (vitest, gated):
+RUN_LIVE_ACPX=1 bun run test
+```
+
+`acp-codex-smoke.mjs` spawns a real codex session, sends "what is 7 + 8?", and verifies `task_complete` fires with response `"15"`. The vitest live test (`__tests__/live/sub-agent-router.live.test.ts`) verifies the synthetic Memory routes back from a real subprocess into a fake `messageService.handleMessage` with all routing keys intact. Both no-op (skip) when `acpx` isn't installed.
+
+## Status
+
+`0.2.0` — consolidated package. ACP subprocess sessions are the primary spawn path; PTY services remain available for terminal-backed route handlers and coordinator tooling.
+
+## Contributing
+
+PRs welcome. Run `npm run typecheck && npm test` before opening.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).