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

package/CHANGELOG.md

@@ -2,9 +2,9 @@
 
 ## 0.2.0 (unreleased)
 
-Consolidated ACP-based spawn, PTY sessions, and workspace services into
+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 consolidated package.
+`@elizaos/plugin-acpx` callers were rewritten to the package.
 
 ### Added
 
@@ -33,7 +33,7 @@ a single package at `plugins/plugin-agent-orchestrator`. Internal
   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).
+  (`AcpService`, `CodingWorkspaceService`, child_process spawn).
 
 ### Fixed
 
@@ -46,12 +46,10 @@ a single package at `plugins/plugin-agent-orchestrator`. Internal
   `listSessions`/`getSession` for FileSessionStore + RuntimeDbSessionStore,
   `enforceSessionLimit` excluding both `"error"` and `"errored"`.
 
-### Deprecated
+### Removed
 
-- `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`.
+- Removed the legacy swarm/terminal implementation family. The plugin now
+  has one task-agent transport: `AcpService` + `SubAgentRouter`.
 
 ## 0.1.0
 

package/README.md

@@ -4,27 +4,47 @@
 [![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.
+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 uses `acpx` to run coding agents as subprocesses on the same host as the runtime.
+> 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 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).
+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
-acpx --version
+export ELIZA_ACP_TRANSPORT=cli
 ```
 
-You also need at least one ACP-compatible agent CLI (`codex`, `claude`, or `gemini`) installed and authenticated.
+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
 
@@ -38,17 +58,24 @@ export default {
 
 ## 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. |
+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
 
@@ -56,13 +83,14 @@ export default {
 - `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, 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.
+- `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";
@@ -106,21 +134,34 @@ You usually don't subscribe directly — `SubAgentRouter` already does, and rout
 
 ## Configuration
 
-All configuration is via environment variables. Sensible defaults; most users only need `ELIZA_ACP_CLI` if `acpx` is not on `PATH`.
+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_CLI` | `acpx` | ACPX executable name or absolute path. |
-| `ELIZA_ACP_DEFAULT_AGENT` | `codex` | Default agent type. |
+| `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` | `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_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_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. |
+| `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
 
@@ -143,13 +184,44 @@ 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` 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.
+`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
 
-`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.
+`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
 

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.

package/docs/default-eliza-skills-and-agent-bridge-plan.md

@@ -7,7 +7,7 @@ Date: 2026-05-10
 Make Eliza's default task workers self-sufficient:
 
 - They should receive editable, repo-owned default skills for Eliza, elizaOS plugin/app development, Eliza Cloud APIs, and monetization.
-- Claude, Codex, OpenCode, Gemini, Aider, and other orchestrated workers should receive those defaults through the agent orchestrator.
+- Claude, Codex, and OpenCode workers should receive those defaults through the ACP agent orchestrator.
 - Applications should be able to override defaults without forking the shipped skill package.
 - Workers should be able to ask the running parent Eliza agent for context or actions that only the parent can perform.
 - Paid, private, or destructive operations should remain mediated by the parent agent and its confirmation flow.
@@ -39,10 +39,9 @@ The task agent infrastructure is in `plugins/plugin-agent-orchestrator`.
 
 Important surfaces:
 
-- `src/services/pty-service.ts` spawns agents, writes adapter memory files, injects parent runtime loopback context, and manages session lifecycle.
-- `src/actions/coding-task-handlers.ts` prepares `SKILLS.md`, recommends skills, spawns task sessions, and registers per-session skill allow-lists.
+- `src/services/acp-service.ts` spawns ACP agents, records session metadata, and manages session lifecycle.
+- `src/actions/tasks.ts` prepares ACP spawn/send/list/control requests through the single task-agent action surface.
 - `src/services/skill-manifest.ts` renders the task-local manifest and virtual broker skills.
-- `src/services/skill-callback-bridge.ts` listens for child output lines matching `USE_SKILL <slug> <json_args>` and routes them back to the parent runtime.
 - `src/services/skill-lifeops-context-broker.ts` already exposes task-scoped LifeOps context.
 
 ### Cloud and monetization
@@ -95,7 +94,7 @@ Sensitive broker access is session allow-listed. The orchestrator includes `pare
 
 ### Worker manifest
 
-`SKILLS.md` now tells workers to emit a standalone `USE_SKILL <slug> <json_args>` line. The orchestrator writes this manifest into the workspace and sets `ELIZA_SKILLS_MANIFEST`, so Codex/Claude/Gemini/Aider-style workers can discover skill protocol without hardcoding.
+`SKILLS.md` now tells workers to emit a standalone `USE_SKILL <slug> <json_args>` line. The orchestrator writes this manifest into the workspace and sets `ELIZA_SKILLS_MANIFEST`, so Codex/Claude/OpenCode workers can discover skill protocol without hardcoding.
 
 The injected parent runtime memory also now explains:
 
@@ -113,9 +112,6 @@ The orchestrator-managed gitignore block now includes common generated agent fil
 - `.claude/`
 - `AGENTS.md`
 - `.codex/`
-- `GEMINI.md`
-- `.gemini/`
-- `.aider*`
 - `.opencode/`
 - `SKILLS.md`
 
@@ -178,11 +174,11 @@ Review focus:
 
 - Type correctness around synthetic `Memory` construction and `messageService.handleMessage`.
 - Session allow-list behavior for virtual brokers.
-- Whether all spawned adapter types can see `SKILLS.md` and parent memory text.
+- Whether all ACP agent types can see `SKILLS.md` and parent memory text.
 - Whether tracked `AGENTS.md` repos need a safer memory-file strategy than writing in the workspace root.
-- Whether OpenCode should become a first-class adapter type instead of shell-compatible spawn.
+- Whether OpenCode's vendored ACP path has enough smoke coverage against Cerebras.
 
-Status: partially implemented. The first three are covered by code/tests; the last two remain follow-up design items.
+Status: partially implemented. The first three are covered by code/tests; live OpenCode/Cerebras validation remains credential-gated.
 
 ### Pass 5: Testing, Verification, Validation
 
@@ -197,8 +193,8 @@ Minimum local tests:
 Live validation:
 
 - Start a parent Eliza runtime with agent skills and orchestrator loaded.
-- Spawn Codex and Claude workers and verify they read `SKILLS.md`.
-- Spawn OpenCode using Eliza Cloud with Cerebras OpenAI `gpt-oss-120b` and verify it can emit `USE_SKILL parent-agent ...`.
+- Spawn Codex, Claude, and OpenCode workers and verify they read `SKILLS.md`.
+- Spawn OpenCode through ACP using the vendored OpenCode shim with Cerebras `gpt-oss-120b` and verify it can emit `USE_SKILL parent-agent ...`.
 - Simulate:
   - action listing
   - parent memory search
@@ -212,8 +208,6 @@ Status: local unit/type/skills tests are implemented and passing. Live OpenCode/
 
 ## Remaining Gaps
 
-- OpenCode is currently treated through shell-compatible spawn paths in parts of the orchestrator. It should become a first-class memory/config adapter if the project wants equivalent behavior to Claude/Codex/Gemini.
-- `PARALLAX_DEFAULT_AGENT_TYPE` fixed-default parsing still only accepts `claude`, `gemini`, `codex`, and `aider`. Routing can rank OpenCode, but fixed default should be extended after type/API review.
 - Writing adapter memory files named `AGENTS.md` can collide with repos that already track `AGENTS.md`. A safer strategy is needed for Codex memory injection in tracked-repo workspaces.
 - Live agent benchmarking against OpenCode + Eliza Cloud + Cerebras requires credentials and running infrastructure.
 - The parent-agent broker currently asks through the normal parent message pipeline. Direct action invocation APIs could be added later, but the message path is more flexible and preserves confirmation behavior.

package/docs/economics-goal-runbook.md

@@ -0,0 +1,140 @@
+# Economics `/goal` runbook — autonomous monetized-app loop
+
+How to drive (and what currently blocks) a `/goal` sub-agent that autonomously
+runs the monetized-app loop: create app → deploy container → enable monetization
+→ buy a domain → stay alive on earnings, with paid Cloud commands auto-authorized
+within a spend cap.
+
+## What already works (verified)
+
+- **Capped self-spend allowance.** `decideSpendAuthorization`
+  (`src/services/spend-allowance.ts`) gates each Cloud command by risk/cap, and
+  `runCloudCommand` (`src/services/parent-agent-broker.ts:1067`) emits the
+  structured `event: "spend_auto_authorized"` log when a self-spend command
+  auto-authorizes within `ELIZA_AGENT_SPEND_CAP_USD`. Confirmed by
+  `src/__tests__/parent-agent-broker.test.ts` › _capped self-spend allowance_
+  (4 cases pass: within-cap auto-authorizes, over-cap confirms, non-self-spend
+  mutating auto-authorizes).
+- **Economics capability profile.** `/economics` (or `/monetize`,
+  `/monetized-app`) in the composer sets `metadata.capabilityProfile = "economics"`
+  (`plugin-task-coordinator` composer directives → `createOrchestratorTask`), and
+  `spawnAgentForTask` reads `coerceGoalCapabilityProfile(task.metadata.capabilityProfile)`
+  and widens the goal fence via `ECONOMICS_GOAL_CAPABILITIES` (`goal-prompt.ts`).
+- **The Cloud loop itself.** `apps.create → monetization.update → domains.buy
+  (real credit debit) → earnings → survival economics` is exercised end-to-end
+  against the mock stack by
+  `packages/test/cloud-e2e/tests/monetized-app-loop.spec.ts`.
+
+## Runbook
+
+1. Boot a stubbed-but-real Cloud so paid commands succeed without real money:
+
+   ```bash
+   CLOUD_E2E=1 NODE_ENV=test bun run cloud:mock --reset
+   # note the printed "Ready on http://127.0.0.1:<apiPort>"
+   ```
+
+   `cloud:mock` opens its PGlite store as a single-writer file, so you cannot
+   seed an org/API key from a second process while it runs. To seed live (and to
+   give the broker a key the granular per-route permission gate accepts), boot
+   through the cloud-e2e stack fixture instead — it stands up a PGlite **TCP
+   bridge** + the same wrangler launcher, then `seedTestUser()` mints an org with
+   credits + an API key. Mint the key with `permissions: ["*"]` if you want the
+   actual `containers.create` / `domains.buy` cloud calls to succeed (the default
+   `read/write/admin` seed key still proves `spend_auto_authorized`, because that
+   log fires from the cap decision *before* the HTTP call — but the call itself
+   401s on routes that require granular scopes like `containers:write`).
+
+2. Point the broker at the mock and arm the spend cap (these resolve through
+   `config-env.ts`, so the eliza config `env` section or process env both work):
+
+   ```bash
+   ELIZA_CLOUD_BASE_URL=http://127.0.0.1:<apiPort>
+   ELIZAOS_CLOUD_API_KEY=<a seeded org API key>      # see cloud-e2e seedTestUser
+   ELIZA_AGENT_SPEND_CAP_USD=20
+   ELIZA_ACP_DEFAULT_AGENT=opencode                   # Cerebras auto-detected; or codex/claude with their keys
+   OPENCODE_DISABLE_AUTOUPDATE=1                       # opencode's network update check can blow the spawn timeout
+   ACPX_DEFAULT_TIMEOUT_MS=600000                      # first opencode init (compile + provider fetch) ~3-5min
+   ```
+
+3. Create an economics task — `/economics build and monetize a tiny app` in the
+   composer, or `POST /api/orchestrator` with
+   `metadata: { capabilityProfile: "economics" }`.
+
+4. The sub-agent loads the `build-monetized-app` skill and SKILLS.md and drives
+   the loop through the parent-agent broker. Watch the logs for
+   `event: "spend_auto_authorized"` on `containers.create` / `domains.buy` —
+   that line is the proof the agent spent within its cap without a human prompt.
+
+   - **Domains gotcha:** `domains.buy` (and `media.*`/`promote.*`) resolve to
+     unknown cost and stall on confirmation unless the agent first calls
+     `domains.check` and threads the quote into `params.spendEstimateUsd`.
+     `containers.create` has a built-in `$0.67/day` estimate, so it
+     auto-authorizes without a hint.
+   - **`containers.create` needs a `name`** in addition to `appId`/`image`, or
+     the cloud call 422s (the spend log still fires; the deploy record is not
+     created). A capable agent self-corrects via `list-cloud-commands`.
+
+## Sub-agent → broker dispatcher (now wired)
+
+`runCloudCommand` (the only emitter of `spend_auto_authorized`) is now reachable
+by a live agent. The three gaps the earlier draft of this runbook called out are
+closed:
+
+1. **Dispatch.** `SubAgentRouter.handleEvent` accumulates the child's streamed
+   `message` text and, when a complete `USE_SKILL parent-agent <json>` directive
+   appears, bridges it to `runParentAgentBroker({ runtime, sessionId, session,
+   args })` and streams `result.text` back via `acp.sendToSession`
+   (`src/services/parent-agent-dispatch.ts`). Detection is marker-guarded (it
+   only acts on text containing `USE_SKILL parent-agent`, which ordinary coding
+   tasks never emit) and capped by `ACPX_SUB_AGENT_ROUND_TRIP_CAP`.
+2. **Advertise.** `spawnAgentForTask` writes a `SKILLS.md` into the workdir for
+   `capabilityProfile === "economics"` tasks via `buildSkillsManifest(runtime, {
+   recommendedSlugs: ["build-monetized-app", "eliza-cloud"], virtualSkills:
+   [PARENT_AGENT_BROKER_MANIFEST_ENTRY] })`, so the child learns the `parent-agent`
+   slug and its arg contract.
+3. **Estimate.** The broker's unknown-cost stall now returns an *actionable*
+   instruction ("fetch a quote with `domains.check` and retry with
+   `params.spendEstimateUsd`") instead of a human-only yes/no, and the manifest
+   guidance advertises the same pattern — so an autonomous agent self-authorizes
+   `domains.buy` within the cap without a human turn.
+
+The directive parser and the broker→`sendToSession` bridge are unit-tested in
+`src/__tests__/parent-agent-dispatch.test.ts`; `spend_auto_authorized` itself
+stays covered by `parent-agent-broker.test.ts`.
+
+## Live verification (2026-06-06)
+
+The full loop was run end-to-end against `cloud:mock` with a real
+`opencode` ACP child on a Cerebras key (`gpt-oss-120b`) — no human in the loop:
+
+- The child read `SKILLS.md`, then drove `cloud.health → apps.create →
+  containers.create` entirely through `USE_SKILL parent-agent {…}` directives.
+  `apps.create` created a real app; `containers.create` self-authorized within
+  the cap and emitted, verbatim:
+  `event:"spend_auto_authorized" command:"containers.create" risk:"paid"
+  estimatedCostUsd:0.67 runningTotalUsd:0.67 capUsd:20 reason:"within-cap"`.
+  When the first `containers.create` 422'd (missing `name`), the child called
+  `list-cloud-commands`, corrected the params, and re-authorized — no human turn.
+- The `domains.buy` self-resolve path was verified at the broker level against
+  the same live mock: `domains.check` returned a `$14.95` quote, that price was
+  threaded into `params.spendEstimateUsd`, `domains.buy` emitted
+  `spend_auto_authorized` ($14.95 of the $20 cap), and the org credit balance
+  dropped **1000.00 → 985.05** — a real debit.
+
+Two defects the live run surfaced (both fixed):
+
+1. **Windows env forwarding (`acp-service.ts`).** `shouldForwardEnv` matched
+   `PATH` case-sensitively, but the repo runtime is Bun and Bun-on-Windows
+   reports the key as `Path` — so ACP sub-agents spawned with NO `PATH` and the
+   opencode shim died with `'bun' is not recognized`. Now matched
+   case-insensitively (+ Windows system vars), with the path key canonicalized
+   to `PATH` in `buildEnv`.
+2. **Mid-turn reply delivery (`parent-agent-dispatch.ts`).** A child emits its
+   directive *mid-turn* and ends the turn awaiting the reply; delivering the
+   reply is a new prompt, which the transport rejects ("session is already
+   busy") until the turn finishes. The old code dropped the reply, stalling the
+   loop on the first directive. Delivery now retries until the session goes idle.
+
+See `default-eliza-skills-and-agent-bridge-plan.md` for the broader bridge design;
+this runbook is the economics-specific slice.