/plugins/plugin-agent-orchestrator/README.md

# @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.

> **Vocabulary:** the work items this plugin manages (`OrchestratorTaskRecord`, `orchestrator_tasks`) are **coding tasks** — always qualify them as such in prose and UI, never the bare word "task" (which is reserved for the core runtime `Task` primitive). A coding task has no cron/recurrence; scheduling belongs to the trigger layer, not here. See [`docs/automation-glossary.md`](../../docs/automation-glossary.md).

## 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="eliza-code-acp"
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` | `eliza-code-acp` | 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_CODEX_ACP_SANDBOX_MODE` / `ELIZA_CODEX_SANDBOX_MODE` | unset | Optional Codex ACP `sandbox_mode` override: `read-only`, `workspace-write`, or `danger-full-access`. |
| `ELIZA_CODEX_ACP_NO_LANDLOCK_SANDBOX_MODE` | `danger-full-access` | Codex ACP sandbox mode used when Linux Landlock is unavailable. |
| `ELIZA_CODEX_ACP_APPROVAL_POLICY` / `ELIZA_CODEX_APPROVAL_POLICY` | `never` for no-Landlock fallback, otherwise unset | Optional Codex ACP `approval_policy` override. |
| `ELIZA_CODEX_ACP_LANDLOCK` / `ELIZA_CODEX_LANDLOCK` | auto-detect | Force Landlock detection for containers/tests: `1`/`true` or `0`/`false`. |
| `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.

## GitHub credentials

Every GitHub-touching capability needs a credential before it can act. Without one, the operation fails with a clean error naming both accepted settings (`ensureGitHubClient` in `src/services/workspace-github.ts`).

**Which capabilities need a token:**

| Capability | What breaks without a token |
| --- | --- |
| `TASKS_MANAGE_ISSUES` | create / list / get / update / comment / close / reopen / add-labels on GitHub issues (`src/services/workspace-github.ts`). |
| `TASKS_SUBMIT_WORKSPACE` | authenticated `commit` / `push` / open-PR against the remote (`src/services/workspace-service.ts` → `workspace-git-ops.ts`). |

Read-only actions (spawn, provision-workspace against a public repo) do not require a token; anything that writes to GitHub does.

**Two ways to supply the credential:**

1. **Personal access token (PAT)** — set `GITHUB_TOKEN`. Read at act-time via `runtime.getSetting("GITHUB_TOKEN")`, so it can be stored per-agent in the vault/settings and rotated without a restart. This is the path a live multi-tenant deployment uses: the agent acts as its own bot account with zero `GITHUB_*` in process env.
2. **OAuth device flow** — set `GITHUB_OAUTH_CLIENT_ID` (via `getSetting`) and the server-side `GITHUB_OAUTH_CLIENT_SECRET` (read directly from process env, deliberately kept out of the plugin `getSetting` allowlist). On first GitHub access the agent surfaces a device-code prompt (verification URI + user code) through an immediate, user-visible channel and polls until the user completes login. The flow requires an `authPromptCallback` wired to a live chat path — a buffered action callback is unsafe because the flow blocks on user consent.

When both are present, `GITHUB_TOKEN` wins.

**Multi-tenant safety — prefer vault/settings over process env.** A `GITHUB_TOKEN` placed in the host **process environment** is visible to *every* agent sharing that host, so on a shared/cloud deployment one tenant's token would act on behalf of all of them. Store the token **per-agent in the runtime settings/vault** instead, where `runtime.getSetting("GITHUB_TOKEN")` scopes it to the single agent. The service does fall back to `process.env.GITHUB_TOKEN` for the git push/PR path, but that fallback is a single-tenant/local-dev convenience — do not rely on it on a shared host.

## 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

These live smokes ship with the repo:

```bash
# Native AcpService against Codex ACP. No global acpx is required; the default
# native Codex command is `npx -y @zed-industries/codex-acp@0.14.0`.
# Authenticate Codex first.
bun run build
RUN_LIVE_NATIVE_ACP=1 bun run test:e2e:native

# Native ACP smoke through Vitest (gated):
RUN_LIVE_NATIVE_ACP=1 bun run test -- __tests__/live/native-acp-smoke.live.test.ts

# Legacy CLI transport smoke against installed acpx + codex:
npm install -g acpx@latest
ELIZA_ACP_TRANSPORT=cli node tests/e2e/acp-codex-smoke.mjs

# Legacy full router loop through acpx (vitest, gated):
RUN_LIVE_ACPX=1 ELIZA_ACP_TRANSPORT=cli bun run test -- __tests__/live/sub-agent-router.live.test.ts
```

`live-native-acp-smoke.mjs` exercises the default native path by spawning a
real Codex ACP session through `npx -y @zed-industries/codex-acp@0.14.0`,
sending "what is 7 + 8?", and verifying `task_complete` fires with response
`"15"`. The Vitest wrapper is skipped unless `RUN_LIVE_NATIVE_ACP=1` is set;
when enabled, it requires `NATIVE ACP SMOKE PASSED`.

`acp-codex-smoke.mjs` and `__tests__/live/sub-agent-router.live.test.ts`
exercise the legacy `acpx` CLI transport. They require `ELIZA_ACP_TRANSPORT=cli`
and an installed/authenticated `acpx` + Codex environment.

`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:e2e:native` | Run the gated native ACP smoke using the configured native agent command. |
| `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).