@elizaos/plugin-agent-orchestrator 2.0.0-alpha.9 → 2.0.3-beta.2

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+## 0.2.0 (unreleased)
+
+ACP-based spawn, sub-agent routing, and workspace services into
+a single package at `plugins/plugin-agent-orchestrator`. Internal
+`@elizaos/plugin-acpx` callers were rewritten to the 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
+  (`AcpService`, `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"`.
+
+### Removed
+
+- Removed the legacy swarm/terminal implementation family. The plugin now
+  has one task-agent transport: `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/README.md

@@ -0,0 +1,232 @@
+# @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 (elizaos, pi-agent, opencode, codex, claude) through Agent Client Protocol transports, 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 runs 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 default path embeds ACP JSON-RPC session management in this plugin and talks directly to an ACP-compatible agent process; the legacy path can still shell out to [`acpx`](https://github.com/openclaw/acpx) when `ELIZA_ACP_TRANSPORT=cli`.
+2. **Route** sub-agent terminal events (`task_complete`, `error`, `blocked`) and swarm coordination events back into the runtime as synthetic inbound messages addressed to the task room, worktree room, or 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, ask the task creator a question, or coordinate with other agents. 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
+```
+
+Native TypeScript ACP is the default transport. Set the default coding agent with `ELIZA_ACP_DEFAULT_AGENT` (`elizaos`, `pi-agent`, or `opencode` are the primary supported defaults):
+
+```bash
+export ELIZA_ACP_TRANSPORT=native
+export ELIZA_ACP_DEFAULT_AGENT=elizaos
+export ELIZA_ELIZAOS_ACP_COMMAND="elizaos"
+export ELIZA_PI_AGENT_ACP_COMMAND="pi-agent"
+export ELIZA_CODEX_ACP_COMMAND="npx -y @zed-industries/codex-acp@0.14.0"
+export ELIZA_CLAUDE_ACP_COMMAND="npx -y @agentclientprotocol/claude-agent-acp@0.34.0"
+```
+
+Authenticate the underlying agent you plan to use before spawning sessions. Native Codex and Claude defaults use `npx`, so pin or replace those commands in production if you do not want runtime downloads.
+
+The legacy command-wrapper path remains available for compatibility:
+
+```bash
+npm install -g acpx@latest
+export ELIZA_ACP_TRANSPORT=cli
+```
+
+Adapter packaging decision: this release does not vendor the Codex or Claude ACP adapter packages. Native transport is the default; Codex and Claude use pinned `npx` commands unless deployment config overrides them. OpenCode is the exception: the package prefers the bundled OpenCode shim when available, then falls back to `opencode acp`.
+
+`coding-agent-adapters` is a runtime registry/API dependency used by this plugin's agent inventory and routes; it is not a bundled Codex or Claude ACP adapter executable.
+
+## Quick start
+
+```ts
+import agentOrchestratorPlugin from "@elizaos/plugin-agent-orchestrator";
+
+export default {
+  plugins: [agentOrchestratorPlugin],
+};
+```
+
+## Action surface
+
+All actions are virtual sub-operations of the single `TASKS` parent action, promoted via `promoteSubactionsToActions` with the `TASKS_` prefix.
+
+| Promoted action | Sub-operation | Purpose |
+| --- | --- | --- |
+| `TASKS_CREATE` | `create` | One-shot: spawn + prompt + return. Captures origin metadata for routing. |
+| `TASKS_SPAWN_AGENT` | `spawn_agent` | Start a long-lived ACP coding-agent session. Returns active session info. |
+| `TASKS_SEND` | `send` | Send a follow-up prompt to a running session (`SEND_TO_AGENT` simile). |
+| `TASKS_STOP_AGENT` | `stop_agent` | Cooperatively cancel + close a session. |
+| `TASKS_LIST_AGENTS` | `list_agents` | List active and persisted sessions. |
+| `TASKS_CANCEL` | `cancel` | Cancel an in-flight task while preserving history. |
+| `TASKS_HISTORY` | `history` | Retrieve past task sessions. |
+| `TASKS_CONTROL` | `control` | Lifecycle control: pause/resume/stop/continue/archive/reopen. |
+| `TASKS_SHARE` | `share` | Share a task session. |
+| `TASKS_PROVISION_WORKSPACE` | `provision_workspace` | Clone repo, create git worktree for a task. |
+| `TASKS_SUBMIT_WORKSPACE` | `submit_workspace` | Commit, push, open PR for a workspace. |
+| `TASKS_MANAGE_ISSUES` | `manage_issues` | GitHub issue create/list/get/update/comment/close/reopen/add_labels. |
+| `TASKS_ARCHIVE` | `archive` | Archive a completed coding task. |
+| `TASKS_REOPEN` | `reopen` | Reopen an archived task. |
+
+## 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.
+- `CODING_SESSION_CHANGES` — real git changeset for "show me the diff" queries.
+
+## Services
+
+- `AcpService` — ACP subprocess lifecycle, session state, event emission, and transport selection. Registers under `ACP_SUBPROCESS_SERVICE`.
+- `OrchestratorTaskService` — durable task store, sub-agent lifecycle API, event bridge from ACP to task records. Registers under `ORCHESTRATOR_TASK_SERVICE`.
+- `SubAgentRouter` — subscribes to `AcpService.onSessionEvent`, posts terminal-event synthetic memories to `runtime.messageService.handleMessage`. Registers under `ACPX_SUB_AGENT_ROUTER`. 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`.
+- `CodingWorkspaceService` — git workspace lifecycle helpers. Registers under `CODING_WORKSPACE_SERVICE`.
+
+```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. Use `ELIZA_ACP_TRANSPORT=native` for the embedded TypeScript ACP client and `ELIZA_ACP_TRANSPORT=cli` only when you deliberately want the existing `acpx` wrapper.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `ELIZA_ACP_TRANSPORT` | `native` | Transport mode. Accepted values include `native`/`direct` and `cli`/`acpx`. |
+| `ELIZA_ACP_CLI` | `acpx` | ACPX executable name or absolute path for the CLI transport. |
+| `ELIZA_ACP_DEFAULT_AGENT` | `elizaos` | Default agent type. Primary choices: `elizaos`, `pi-agent`, `opencode`. |
+| `ELIZA_ELIZAOS_ACP_COMMAND` | `elizaos` | Native elizaOS ACP command. |
+| `ELIZA_PI_AGENT_ACP_COMMAND` | `pi-agent` | Native Pi Agent ACP command. |
+| `ELIZA_CODEX_ACP_COMMAND` | `npx -y @zed-industries/codex-acp@0.14.0` | Native Codex ACP command. |
+| `ELIZA_CLAUDE_ACP_COMMAND` | `npx -y @agentclientprotocol/claude-agent-acp@0.34.0` | Native Claude ACP command. |
+| `ELIZA_OPENCODE_ACP_COMMAND` | bundled shim or `opencode acp` | Native OpenCode ACP command override. |
+| `ELIZA_ACP_DEFAULT_APPROVAL` | `autonomous` | Approval preset (`read-only`, `auto`, `permissive`, `autonomous`, `full-access`). |
+| `ELIZA_ACP_PROMPT_TIMEOUT_MS` / `ACPX_DEFAULT_TIMEOUT_MS` | `300000` (5m) | Per-prompt timeout. |
+| `ELIZA_ACP_STATE_DIR` | `~/.eliza/plugin-acp` | Where to persist session state when no runtime DB. |
+| `ACPX_DEFAULT_CWD` | runtime cwd | Base directory for spawned agent workdirs. |
+| `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. |
+| `ACPX_PROGRESS_MODE` / `ELIZA_SUB_AGENT_PROGRESS_MODE` | `compact` | Sub-agent progress UX: `compact` delays and edits one status message, `threaded` preserves per-task threads, `silent` disables visible progress. |
+| `ACPX_PROGRESS_DELAY_MS` / `ELIZA_SUB_AGENT_PROGRESS_DELAY_MS` | `15000` | Delay before the first visible progress message, so short tasks only show the final answer. |
+| `ACPX_PROGRESS_REACTIONS` / `ELIZA_SUB_AGENT_PROGRESS_REACTIONS` | unset | Set to `1` to add progress reactions in `threaded` mode. |
+
+### Native transport status
+
+Native transport is an ACP JSON-RPC client. It currently handles `initialize`, `session/new`, `session/prompt`, cooperative `session/cancel`, `session/close`, file reads/writes scoped to the session workspace, permission requests, and basic terminal requests from the agent.
+
+Use the CLI transport only when you need the existing `acpx` command wrapper semantics.
+
+## 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
+
+# Native ACP adapter smoke (gated, no-op unless enabled):
+RUN_LIVE_NATIVE_ACP=1 node tests/e2e/live-native-acp-smoke.mjs
+```
+
+`acp-codex-smoke.mjs` exercises the legacy `acpx` path by spawning a real codex session, sending "what is 7 + 8?", and verifying `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 test `messageService.handleMessage` with all routing keys intact. Both no-op (skip) when `acpx` isn't installed.
+
+`live-native-acp-smoke.mjs` sets `ELIZA_ACP_TRANSPORT=native`, starts a native ACP adapter over stdio, sends a tiny math prompt, and verifies the prompt response ended with `stopReason: "end_turn"` and final text containing `15`. Optional providers require explicit commands:
+
+```bash
+RUN_LIVE_NATIVE_ACP=1 LIVE_NATIVE_ACP_AGENT=claude ELIZA_CLAUDE_ACP_COMMAND="npx -y @agentclientprotocol/claude-agent-acp@0.34.0" node tests/e2e/live-native-acp-smoke.mjs
+RUN_LIVE_NATIVE_ACP=1 LIVE_NATIVE_ACP_AGENT=opencode ELIZA_OPENCODE_ACP_COMMAND="opencode acp" node tests/e2e/live-native-acp-smoke.mjs
+```
+
+The native smoke skips successfully when `RUN_LIVE_NATIVE_ACP` is unset, when an optional provider command is not configured, or when the adapter reports missing authentication/credentials. Use `RUN_LIVE_NATIVE_ACP=1 bun run test -- __tests__/live/native-acp-smoke.live.test.ts` to run the same smoke through Vitest.
+
+Native transport is covered by unit tests under `__tests__/unit/acp-native-transport.test.ts` and by the gated live smoke above.
+
+## Package scripts
+
+| Script | Purpose |
+| --- | --- |
+| `bun run build` / `bun run build:ts` | Build Node ESM, CJS, and declaration outputs. |
+| `bun run dev` | Rebuild in watch mode. |
+| `bun run typecheck` | Run TypeScript without emitting files. |
+| `bun run test` | Run the plugin vitest suite. |
+| `bun run test:unit` | Run unit tests only. |
+| `bun run test:e2e:manual` | Run the manual `acp-codex-smoke.mjs` smoke against installed/authenticated `acpx` + Codex. |
+| `bun run test:watch` | Run the vitest suite in watch mode. |
+| `bun run lint:check` | Run Biome checks without writing changes. |
+| `bun run lint` | Run Biome checks with write/unsafe fixes. |
+| `bun run format:check` | Check formatting. |
+| `bun run format` | Write formatting changes. |
+| `bun run clean` | Remove local build/cache outputs. |
+
+## Status
+
+`2.0.3-beta.14` — package. ACP subprocess sessions are the only task-agent spawn path. The native ACP client is the default (`ELIZA_ACP_TRANSPORT=native`).
+
+## Contributing
+
+PRs welcome. Run `npm run typecheck && npm test` before opening.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/docs/SUBAGENT_FLOW_AND_PARITY.md

@@ -0,0 +1,138 @@
+# Sub-agent flow & Codex / Claude-Code parity review
+
+A thorough walk of how the main agent creates a task, spawns sub-agents,
+provisions them, and communicates — across the elizaOS, Codex, and Claude
+frameworks — plus an honest parity assessment against standalone Codex CLI and
+Claude Code, and the concrete open items.
+
+## 1. End-to-end flow
+
+```
+user msg → planner → TASKS_CREATE ─────────────► durable task (status: open)
+                         │                         roomId, taskRoomId, ownerUserId,
+                         │                         originalRequest, acceptanceCriteria
+                         ▼
+                   TASKS_SPAWN_AGENT ────────────► AcpService.spawnSession(SpawnOptions)
+                         │   goal-prompt.ts wraps   agentType, workdir, goalPrompt,
+                         │   the goal + rooms +      approvalPreset, metadata{roomId,
+                         │   acceptance criteria     source, label, worldId, userId}
+                         ▼
+                   ACP subprocess (native JSON-RPC over stdio)
+                   elizaos | codex | claude | opencode | pi-agent
+                         │   session/new → session/prompt(goal)
+                         ▼
+                   events: ready · tool_running · message · reasoning · plan ·
+                           blocked · task_complete · error · usage_update
+                         │
+        ┌────────────────┴───────────────────────────────┐
+        ▼                                                  ▼
+  OrchestratorTaskService.onSessionEvent          SubAgentRouter.handleEvent
+  (durable: addEvent / updateSession /            (synthetic Memory → planner;
+   recordMessage; task_complete → "validating")    round-trip cap = 32)
+                                                          │
+                                                          ▼
+                                          planner ↔ subAgentCompletionResponseEvaluator
+                                          → reply to user OR TASKS_SEND_TO_AGENT
+```
+
+**Key files:** task create `actions/tasks.ts:685` → `services/orchestrator-task-service.ts:746`;
+spawn `actions/tasks.ts:743` → `services/acp-service.ts:511`; goal wrap
+`services/goal-prompt.ts:129`; event bridge `orchestrator-task-service.ts:519`;
+routing `services/sub-agent-router.ts`; completion gate
+`orchestrator-task-service.ts:608` (`task_complete` → `validating`, never straight
+to `done`); evaluator `evaluators/sub-agent-completion.ts`.
+
+**Provisioning** happens at spawn: `acp-service.ts` resolves the workdir, captures
+a git baseline SHA + dirty set (for the completion changeset), and writes a
+sub-agent `AGENTS.md`/`CLAUDE.md` identity manifest on bare workdirs
+(`sub-agent-identity.ts`). Explicit repo clone / worktree / branch / commit / push
+/ PR is `CodingWorkspaceService` (`workspace-*.ts`), driven by
+`TASKS_PROVISION_WORKSPACE` / `TASKS_SUBMIT_WORKSPACE`.
+
+## 2. Sub-agent rooms per task
+
+- `roomId` = the originating user channel (where the final reply goes).
+  `taskRoomId` = a dedicated task-scoped room; all sessions' messages
+  (`senderKind: user|orchestrator|sub_agent|system`) append there. Exposed via
+  `GET /api/orchestrator/tasks/:id/messages`, `/timeline`, and `/stream` (SSE).
+- The in-app **task view** (`plugin-task-coordinator/src/OrchestratorWorkbench.tsx`)
+  renders this as a per-task message room: the merged timeline + per-sub-agent
+  sessions list + plan + diff + usage + recovery, with near-live polling.
+- On chat connectors, the **progress thread** (`index.ts emitProgress`) routes all
+  sub-agent narration into a per-task Discord thread / Telegram forum topic
+  (capability-gated on `create_thread` + `post_to_thread` + threaded progress
+  mode), keeping the main channel clean. This is the "task info as threads in TG
+  and Discord" surface.
+
+## 3. Inter-agent communication
+
+**Topology: hub-and-spoke.** Sub-agents do not address each other directly. Each
+talks only to the parent:
+- parent → sub: initial goal prompt; mid-flight `TASKS_SEND_TO_AGENT`; live user
+  messages in the task room are auto-forwarded to the active session
+  (`index.ts` MESSAGE_RECEIVED listener).
+- sub → parent: terminal ACP events → synthetic memories; plus a sub-agent can
+  emit `USE_SKILL parent-agent {…}` which the router dispatches to the
+  parent-agent broker (`parent-agent-dispatch.ts` / `parent-agent-broker.ts`) and
+  replies back over the session.
+- sub → parent context: loopback-only bridge `GET /api/coding-agents/:id/context/*`
+  (parent character, current room, memory search, active workspaces).
+
+Multiple sub-agents per task are supported (`sessions[]`), unsynchronized; the
+router de-dupes concurrent `task_complete` so only the first posts to the user.
+
+## 4. Framework matrix (elizaOS / Codex / Claude)
+
+All run as ACP subprocesses over the native JSON-RPC transport
+(`acp-native-transport.ts`); spawn command per framework is env-overridable
+(`ELIZA_{ELIZAOS,CODEX,CLAUDE,OPENCODE,PI_AGENT}_ACP_COMMAND`; Codex/Claude default
+to pinned `npx` ACP shims). The orchestrator implements the ACP client side of:
+`session/new`, `session/prompt`, `session/cancel`, `session/update` (streaming
+`agent_message_chunk` / `agent_thought_chunk` / `tool_call` / `plan`),
+`session/request_permission`, `fs/read_text_file`, `fs/write_text_file`, and the
+`terminal/*` family. Approval presets (`readonly|standard|permissive|autonomous`)
+gate file/terminal ops. Credentials reach sub-agents via the loopback credential
+tunnel (`bridge-routes.ts`); host connector tokens are denylisted from the child
+env, and Claude OAuth-subscription tokens are stripped so the child uses its own
+subscription.
+
+## 5. Parity vs standalone Codex CLI / Claude Code
+
+**At parity:** multi-framework spawn + routing; file read/write; terminal exec;
+plan/reasoning/tool streaming; approval gates; real git-diff capture & surfacing
+(`coding-session-changes.ts`); token usage; orphaned-session recovery on restart;
+durable task store + task view; per-task threads on connectors.
+
+**Partial:** plan/todo events are emitted by OpenCode but not uniformly by
+Codex/Claude; diff surfacing truncates (20 files / 50 lines) with no inline
+per-line review UI; sub-agents run `--no-terminal` (event-driven, no interactive
+TUI — correct for orchestration, but differs from a human at the CLI).
+
+**Gaps:**
+1. **MCP forwarding** — ✅ implemented (opt-in). `acp-native-transport.ts`
+   forwards `ELIZA_ACP_MCP_SERVERS` (a JSON array of stdio/http MCP server
+   configs) into `session/new.mcpServers` via `parseAcpMcpServersEnv`, so
+   sub-agents get the parent's MCP tools (Codex / Claude-Code parity). Defaults
+   to `[]` (prior behavior) so spawning never regresses. Remaining: auto-inherit
+   the parent runtime's MCP set without explicit env config (needs a runtime
+   MCP-config surface, which doesn't exist yet).
+2. **Sub-agent nesting** (open) — no spawn-child API; a sub-agent cannot delegate
+   to its own sub-agents (single level of orchestration). Feature-level work.
+3. **Inline code-review surface** — diffs are captured but there's no structured
+   per-file/line review/approve UI in the task view.
+
+## 6. Open items checklist
+
+- [x] Interaction protocol (forms / choice + custom / secret / task) across app + TG + Discord
+- [x] Pick-an-option round-trip on both connectors; secret/OAuth DM link-out on both
+- [x] Per-task threads on TG + Discord (orchestrator-driven; both connectors now capable)
+- [x] Task view with sub-agent message room (OrchestratorWorkbench)
+- [x] Real interaction-widget + connector round-trip tests
+- [x] MCP server forwarding to sub-agents (opt-in via `ELIZA_ACP_MCP_SERVERS`)
+- [ ] Sub-agent nesting / delegation (gap #2 — feature-level)
+- [ ] Inline diff review UI in the task view (gap #3)
+- [ ] Live connector E2E (needs TG/Discord credentials) + orchestrator HTTP task-flow E2E
+- [ ] Optional: `outgoing_before_deliver` central interaction normalization hook
+
+See `@elizaos/core` `src/messaging/interactions/README.md` for the interaction
+protocol; this doc covers the orchestration + sub-agent layer.