@elizaos/plugin-agent-orchestrator 2.0.0-beta.1 → 2.0.3-beta.3

package/docs/sub-agent-routing.md

@@ -1,8 +1,7 @@
 # Sub-agent routing
 
-> Canonical orchestration path for ACPX sub-agents. ACP-spawned sessions
-> route through `AcpService` and `SubAgentRouter`; PTY-spawned sessions keep
-> using the coordinator modules that ship in this package.
+> Canonical orchestration path for ACP sub-agents. ACP-spawned sessions route
+> through `AcpService` and `SubAgentRouter`.
 
 ## Goals
 
@@ -20,7 +19,7 @@
 
 ## Components
 
-### `AcpService` (existing)
+### `AcpService`
 
 Spawn surface. TASKS op=create records origin context in
 `session.metadata` at spawn time:
@@ -28,7 +27,14 @@ Spawn surface. TASKS op=create records origin context in
 ```ts
 {
   messageId: message.id,    // parent message UUID
-  roomId:    message.roomId,
+  roomId:    taskRoomId,    // task-owner room, defaults to message.roomId
+  originRoomId: message.roomId,
+  taskRoomId,
+  worktreeRoomId,
+  swarmRooms: [
+    { roomId: taskRoomId, roles: ["task"] },
+    { roomId: worktreeRoomId, roles: ["worktree"] },
+  ],
   worldId:   message.worldId,
   userId:    message.entityId,
   label,
@@ -36,19 +42,19 @@ Spawn surface. TASKS op=create records origin context in
 }
 ```
 
-### `SubAgentRouter` (new — `services/sub-agent-router.ts`)
+### `SubAgentRouter` (`services/sub-agent-router.ts`)
 
 Subscribes to `AcpService.onSessionEvent`. On `task_complete`, `error`, or
 `blocked` (boundary events only — not streaming chunks), it:
 
-1. Reads `session.metadata` for origin keys.
+1. Reads `session.metadata` for origin and swarm-room keys.
 2. Constructs a synthetic `Memory` with:
    - `entityId` = a deterministic per-session sub-agent UUID derived locally
      via SHA1 of `<runtime.agentId>:acpx:sub-agent:<sessionId>` (no runtime
      dependency on `@elizaos/core`'s `createUniqueUuid` so the router stays
      type-only on core),
    - `agentId`  = `runtime.agentId`,
-   - `roomId`   = origin `roomId`,
+   - `roomId`   = the selected swarm target room,
    - `content.source` = `"sub_agent"`,
    - `content.inReplyTo` = origin `messageId`,
    - `content.metadata.subAgent*` carries the structured event
@@ -56,12 +62,19 @@ Subscribes to `AcpService.onSessionEvent`. On `task_complete`, `error`, or
      `subAgentStatus`, `subAgentAgentType`, `subAgentRoundTrip`,
      `subAgentRoundTripCap`, `subAgentCapExceeded`, `originUserId`,
      `originMessageId`, `originSource`).
-3. Persists the memory via `runtime.createMemory(..., "messages")`.
-4. Delivers via `runtime.messageService.handleMessage(runtime, memory)`.
-
-The runtime's connector hooks (`outgoing_before_deliver`) handle delivery to
-Telegram/Discord/UI — same path a real user message would follow. There is
-no callback held by the router.
+   - `content.metadata.subAgentRoutingKind`,
+     `subAgentTargetRoomId`, `subAgentTargetRoomRole`,
+     `subAgentTargetRoomRoles`, `taskRoomId`, `worktreeRoomId`, and
+     `subAgentSwarmRooms` tell the main agent why this memory landed in
+     this room and which other swarm room(s) exist for the task.
+3. Delivers via `runtime.messageService.handleMessage(runtime, memory, callback)`,
+   which also persists the memory. If `messageService` is unavailable, it
+   falls back to `runtime.createMemory(..., "messages")` plus
+   `MESSAGE_RECEIVED`.
+
+For platform-originated tasks, the router builds a short-lived callback from
+`runtime.sendMessageToTarget` so the planner's answer can return to the same
+selected swarm room.
 
 #### Why only boundary events
 
@@ -78,6 +91,26 @@ re-emitting the same `task_complete` payload posts once. A different
 response payload posts again — that's "the sub-agent did more work and
 reported a new state".
 
+Swarm target rooms are also normalized before posting. `taskRoomId` is first,
+`worktreeRoomId` is second, duplicate room IDs collapse into one target, and
+the collapsed target keeps both roles (`["task", "worktree"]`). That means a
+task room that is also the worktree coordination room gets one useful message
+rather than two identical messages with ambiguous purpose.
+
+#### Routing kinds
+
+Most terminal events use `subAgentRoutingKind: "TASK_STATUS"` and fan out to
+the normalized task/worktree swarm rooms. Two explicit coordination events are
+targeted:
+
+- `QUESTION_FOR_TASK_CREATOR` routes only to the task room and carries
+  `subAgentTargetRoomRole: "task"`.
+- `AGENT_COORDINATION` routes to the worktree room when present, otherwise the
+  task room, and carries the selected target role.
+
+`blocked` events default to `QUESTION_FOR_TASK_CREATOR` because the sub-agent
+is waiting on human or parent-agent input.
+
 #### Disable switch
 
 `ACPX_SUB_AGENT_ROUTER_DISABLED=1` keeps the service registered but unbound
@@ -98,7 +131,7 @@ Set `ACPX_SUB_AGENT_ROUND_TRIP_CAP=N` in the runtime config to override.
 The default of 32 is generous; a typical sub-agent task hits 1–5
 round-trips before terminal completion.
 
-### `activeSubAgentsProvider` (new — `providers/active-sub-agents.ts`)
+### `activeSubAgentsProvider` (`providers/active-sub-agents.ts`)
 
 Cache-friendly view of live sub-agent sessions. Filters to:
 
@@ -169,16 +202,13 @@ the most recent turn stays warm.
 - Dedup prevents accidental double-injection from event re-emission.
 - The round-trip cap (above) is the hard ceiling for ping-pong loops.
 
-## Coordinator Boundary
+## ACP Boundary
 
-`plugin-agent-orchestrator`'s `swarm-coordinator.ts` and
-`swarm-decision-loop.ts` are bound to `PTYService` only. Sessions spawned
-through `AcpService` bypass them entirely.
+`plugin-agent-orchestrator` has a single task-agent transport: `AcpService`.
+There is no PTY/coordinator fallback path.
 
-The swarm coordinator's autonomous decision logic
-(`makeCoordinationDecision`, `buildTurnCompletePrompt`,
-`buildBlockedEventMessage`) is replaced by the main agent's normal action
-selection over the synthetic Memory.
+Autonomous follow-up decisions are handled by the main agent's normal action
+selection over the synthetic Memory emitted by `SubAgentRouter`.
 
 ## Testing
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elizaos/plugin-agent-orchestrator",
-  "version": "2.0.0-beta.1",
-  "description": "Canonical ElizaOS plugin for spawning and orchestrating coding agents via the Agent Client Protocol (acpx) — combined with workspace lifecycle, GitHub integration, task share, runtime-driven sub-agent routing, and supporting services.",
+  "version": "2.0.3-beta.3",
+  "description": "Canonical ElizaOS plugin for spawning and orchestrating coding agents via native Agent Client Protocol transports — combined with workspace lifecycle, GitHub integration, task share, runtime-driven sub-agent routing, and supporting services.",
   "type": "module",
   "main": "dist/node/index.node.js",
   "module": "dist/node/index.node.js",
@@ -15,6 +15,11 @@
     "./package.json": "./package.json",
     ".": {
       "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
       "node": {
         "types": "./dist/node/index.d.ts",
         "import": "./dist/node/index.node.js",
@@ -26,6 +31,12 @@
       },
       "require": "./dist/cjs/index.node.cjs",
       "default": "./dist/node/index.node.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
     }
   },
   "files": [
@@ -36,11 +47,15 @@
     "LICENSE",
     "docs"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "./src/register-routes.ts",
+    "./src/register-routes.js",
+    "./dist/node/index.node.js",
+    "./dist/cjs/index.node.cjs"
+  ],
   "keywords": [
     "elizaos",
     "plugin",
-    "acpx",
     "agent-client-protocol",
     "coding-agent",
     "subagent",
@@ -49,44 +64,45 @@
   "author": "@stwd / 0xSolace",
   "license": "MIT",
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   },
   "peerDependencies": {
-    "@elizaos/core": "2.0.0-beta.1",
-    "git-workspace-service": "0.4.5",
-    "pty-manager": "1.11.0"
+    "@elizaos/core": "2.0.3-beta.3",
+    "git-workspace-service": "0.4.5"
   },
   "dependencies": {
-    "@elizaos/app-task-coordinator": "2.0.0-beta.1",
+    "@octokit/rest": "^22.0.0",
     "coding-agent-adapters": "0.16.3",
     "drizzle-orm": "^0.45.1",
-    "pty-console": "0.3.1",
-    "pty-state-capture": "0.2.0"
+    "effect": "^3.21.1",
+    "smithers-orchestrator": "0.22.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
     "@electric-sql/pglite": "^0.4.0",
-    "@elizaos/core": "2.0.0-beta.1",
+    "@elizaos/core": "2.0.3-beta.3",
+    "@elizaos/shared": "2.0.3-beta.3",
     "@types/bun": "^1.3.9",
     "@types/node": "^25.2.3",
-    "bun-types": "1.3.13",
+    "bun-types": "1.3.14",
     "git-workspace-service": "0.4.5",
-    "pty-manager": "1.11.0",
     "typescript": "^6.0.3",
     "vitest": "^4.0.0"
   },
   "scripts": {
-    "postinstall": "node ./scripts/ensure-node-pty.mjs",
     "dev": "bun run build.ts --watch",
     "clean": "rm -rf dist .turbo .turbo-tsconfig.json tsconfig.tsbuildinfo tsconfig.build.tsbuildinfo",
     "format": "bunx @biomejs/biome format --write .",
     "format:check": "bunx @biomejs/biome format .",
     "lint": "bunx @biomejs/biome check --write --unsafe .",
     "lint:check": "bunx @biomejs/biome check . --no-errors-on-unmatched",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "typecheck": "tsgo --noEmit -p tsconfig.json",
     "test": "bunx vitest run --config vitest.config.ts",
-    "test:unit": "bunx vitest run --config vitest.config.ts --dir __tests__/unit",
-    "test:integration": "bunx vitest run --config vitest.config.ts --dir tests/e2e --passWithNoTests",
+    "test:unit": "bunx vitest run --config vitest.config.ts __tests__/unit",
+    "test:e2e:manual": "node tests/e2e/acp-codex-smoke.mjs",
+    "test:e2e:multi-account": "bun --conditions=eliza-source scripts/compose-multi-account-e2e.ts",
+    "test:scenarios": "bun --conditions=eliza-source ../../packages/scenario-runner/src/cli.ts run test/scenarios --lane pr-deterministic",
+    "test:scenarios:live": "bun --conditions=eliza-source ../../packages/scenario-runner/src/cli.ts run test/scenarios --lane live-only",
     "test:watch": "bunx vitest --config vitest.config.ts",
     "build": "bun run build.ts",
     "build:ts": "bun run build.ts"
@@ -99,41 +115,110 @@
     "pluginParameters": {
       "ELIZA_ACP_CLI": {
         "type": "string",
-        "description": "Path or command name for the acpx CLI used to spawn Agent Client Protocol subprocess sessions.",
+        "description": "Path or command name for the legacy acpx command-wrapper transport when ELIZA_ACP_TRANSPORT=cli.",
         "required": false,
         "default": "acpx",
         "sensitive": false
       },
+      "ELIZA_ACP_TRANSPORT": {
+        "type": "string",
+        "description": "ACP transport mode. Native/direct uses the embedded TypeScript ACP client; cli/acpx keeps the legacy command-wrapper transport.",
+        "required": false,
+        "default": "native",
+        "sensitive": false
+      },
+      "ELIZA_ACP_DEFAULT_AGENT": {
+        "type": "string",
+        "description": "Default coding agent adapter for TASKS create/spawn_agent when the user or planner does not choose one. Supported defaults include elizaos, pi-agent, and opencode.",
+        "required": false,
+        "default": "elizaos",
+        "sensitive": false
+      },
+      "ELIZA_DEFAULT_AGENT_TYPE": {
+        "type": "string",
+        "description": "Compatibility alias for the default coding agent adapter. Use elizaos, pi-agent, or opencode to switch the default code agent from settings.",
+        "required": false,
+        "default": "elizaos",
+        "sensitive": false
+      },
+      "ELIZA_AGENT_SELECTION_STRATEGY": {
+        "type": "string",
+        "description": "Task-agent selection policy. fixed makes the configured default adapter authoritative; dynamic allows runtime selection when implemented.",
+        "required": false,
+        "default": "fixed",
+        "sensitive": false
+      },
+      "ELIZA_ELIZAOS_ACP_COMMAND": {
+        "type": "string",
+        "description": "Native ACP command used for ElizaOS coding-agent sessions when ELIZA_ACP_TRANSPORT=native.",
+        "required": false,
+        "default": "elizaos",
+        "sensitive": false
+      },
+      "ELIZA_PI_AGENT_ACP_COMMAND": {
+        "type": "string",
+        "description": "Native ACP command used for Pi Agent sessions when ELIZA_ACP_TRANSPORT=native.",
+        "required": false,
+        "default": "pi-agent",
+        "sensitive": false
+      },
+      "ELIZA_CODEX_ACP_COMMAND": {
+        "type": "string",
+        "description": "Native ACP command used for Codex sessions when ELIZA_ACP_TRANSPORT=native. Pin this in production to avoid implicit package upgrades.",
+        "required": false,
+        "default": "npx -y @zed-industries/codex-acp@0.14.0",
+        "sensitive": false
+      },
+      "ELIZA_CLAUDE_ACP_COMMAND": {
+        "type": "string",
+        "description": "Native ACP command used for Claude sessions when ELIZA_ACP_TRANSPORT=native. Pin this in production to avoid implicit package upgrades.",
+        "required": false,
+        "default": "npx -y @agentclientprotocol/claude-agent-acp@0.34.0",
+        "sensitive": false
+      },
+      "ELIZA_OPENCODE_ACP_COMMAND": {
+        "type": "string",
+        "description": "Native ACP command used for OpenCode sessions when ELIZA_ACP_TRANSPORT=native. Defaults to the bundled OpenCode shim when available, otherwise opencode acp.",
+        "required": false,
+        "sensitive": false
+      },
+      "ELIZA_ACP_FORMAT": {
+        "type": "string",
+        "description": "Agent Client Protocol event format expected from legacy transports.",
+        "required": false,
+        "default": "json",
+        "sensitive": false
+      },
       "ACPX_DEFAULT_TIMEOUT_MS": {
         "type": "number",
-        "description": "Default timeout in milliseconds for ACPX prompt/session subprocess calls when an action does not provide a timeout.",
+        "description": "Default timeout in milliseconds for ACP prompt/session calls when an action does not provide a timeout.",
         "required": false,
         "sensitive": false
       },
       "ACPX_APPROVE_ALL": {
         "type": "boolean",
-        "description": "When true, defaults ACPX sessions to the approve-all approval preset unless an action overrides approvalPreset.",
+        "description": "When true, defaults ACP sessions to the approve-all approval preset unless an action overrides approvalPreset.",
         "required": false,
         "default": false,
         "sensitive": false
       },
       "ACPX_FORMAT": {
         "type": "string",
-        "description": "Output format passed to acpx. The plugin expects typed JSON/NDJSON Agent Client Protocol events.",
+        "description": "Deprecated alias for ELIZA_ACP_FORMAT.",
         "required": false,
         "default": "json",
         "sensitive": false
       },
       "ACPX_NO_TERMINAL": {
         "type": "boolean",
-        "description": "When true, passes --no-terminal so coding agents communicate through ACP events rather than PTY terminal UI.",
+        "description": "When true, passes --no-terminal so coding agents communicate through ACP events rather than terminal UI.",
         "required": false,
         "default": true,
         "sensitive": false
       },
       "ACPX_DEFAULT_CWD": {
         "type": "string",
-        "description": "Default working directory for ACPX sessions when an action does not provide workdir.",
+        "description": "Default working directory for ACP sessions when an action does not provide workdir.",
         "required": false,
         "sensitive": false
       }
@@ -147,5 +232,6 @@
     "platformDetails": {
       "node": "Node.js subprocess integration available via exports.node; browser export is a compatibility shim for package resolution."
     }
-  }
+  },
+  "gitHead": "f54b0f4eaed317d59fa7dbcdce20f4cdb0734420"
 }

package/PROJECT.md

@@ -1,119 +0,0 @@
-# @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