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

package/dist/node/src/services/workspace-types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Type definitions for the Coding Workspace Service.
+ *
+ * Extracted from workspace-service.ts to reduce module size.
+ *
+ * @module services/workspace-types
+ */
+import type { WorkspaceStatus } from "git-workspace-service";
+export interface CodingWorkspaceConfig {
+    /** Base directory for workspaces (default: ~/.eliza/workspaces) */
+    baseDir?: string;
+    /** Branch prefix (default: "eliza") */
+    branchPrefix?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Max age for orphaned workspace directories in ms (default: 24 hours). Set to 0 to disable GC. */
+    workspaceTtlMs?: number;
+}
+export interface ProvisionWorkspaceOptions {
+    /** Git repository URL */
+    repo: string;
+    /** Base branch to create from (default: "main") */
+    baseBranch?: string;
+    /** Exact branch name to use (overrides auto-generated name) */
+    branchName?: string;
+    /** Use worktree instead of clone */
+    useWorktree?: boolean;
+    /** Parent workspace ID for worktree */
+    parentWorkspaceId?: string;
+    /** Execution context */
+    execution?: {
+        id: string;
+        patternName: string;
+    };
+    /** Task context */
+    task?: {
+        id: string;
+        role: string;
+        slug?: string;
+    };
+    /** User-provided credentials */
+    userCredentials?: {
+        type: "pat" | "oauth" | "ssh";
+        token?: string;
+    };
+}
+export interface WorkspaceResult {
+    id: string;
+    path: string;
+    branch: string;
+    baseBranch: string;
+    isWorktree: boolean;
+    repo: string;
+    status: WorkspaceStatus;
+    /** Semantic label for referencing this workspace (e.g. "auth-bugfix", "api-tests") */
+    label?: string;
+}
+export interface CommitOptions {
+    message: string;
+    all?: boolean;
+}
+export interface PushOptions {
+    setUpstream?: boolean;
+    force?: boolean;
+}
+export interface PROptions {
+    title: string;
+    body: string;
+    base?: string;
+    draft?: boolean;
+    labels?: string[];
+    reviewers?: string[];
+}
+export interface WorkspaceStatusResult {
+    branch: string;
+    clean: boolean;
+    modified: string[];
+    staged: string[];
+    untracked: string[];
+}
+//# sourceMappingURL=workspace-types.d.ts.map

package/dist/node/src/services/workspace-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-types.d.ts","sourceRoot":"","sources":["../../../../src/services/workspace-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oGAAoG;IACpG,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB;IACxB,SAAS,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,mBAAmB;IACnB,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,gCAAgC;IAChC,eAAe,CAAC,EAAE;QAAE,IAAI,EAAE,KAAK,GAAG,OAAO,GAAG,KAAK,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;IACxB,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB"}

package/dist/node/src/setup-routes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Coding-agent orchestrator HTTP routes — Plugin route registration.
+ *
+ * Mounts `/api/coding-agents/*`, `/api/workspace/*`, and `/api/issues/*`
+ * through `Plugin.routes` with `rawPath: true`.
+ */
+import type { Plugin } from "@elizaos/core";
+export declare const codingAgentRoutePlugin: Plugin;
+//# sourceMappingURL=setup-routes.d.ts.map

package/dist/node/src/setup-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-routes.d.ts","sourceRoot":"","sources":["../../../src/setup-routes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAiB,MAAM,EAAS,MAAM,eAAe,CAAC;AAuIlE,eAAO,MAAM,sBAAsB,EAAE,MAMpC,CAAC"}

package/dist/node/vitest.config.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("vite").UserConfig;
+export default _default;
+//# sourceMappingURL=vitest.config.d.ts.map

package/dist/node/vitest.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.config.d.ts","sourceRoot":"","sources":["../../vitest.config.ts"],"names":[],"mappings":";AAEA,wBAQG"}

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

@@ -0,0 +1,231 @@
+# Default Eliza Skills And Agent Bridge Plan
+
+Date: 2026-05-10
+
+## Goal
+
+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.
+- 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.
+
+## Current Inventory
+
+### Shipped skills
+
+Repo-owned default skills live under:
+
+```text
+packages/skills/skills/<slug>/SKILL.md
+```
+
+The `@elizaos/skills` package publishes those files. Runtime startup wires bundled, workspace, and extra skill roots through `packages/agent/src/runtime/eliza.ts`. Managed/workspace copies override bundled defaults.
+
+Relevant shipped skills now include:
+
+- `eliza` for the running Eliza app, parent-agent callback protocol, capabilities, and lifecycle.
+- `elizaos` for upstream runtime/plugin abstractions.
+- `eliza-app-development` for this app repo's build and edit workflow.
+- `eliza-cloud` for Cloud APIs, apps, credits, billing, containers, domains, auth, and earnings.
+- `build-monetized-app` for the new-app deploy and monetization loop.
+- `task-agent-eliza-bridge` for low-level task-agent bridge details.
+
+### Agent orchestration
+
+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/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
+
+Current Cloud source-of-truth files:
+
+- OpenAPI: `cloud/apps/api/openapi.json/route.ts`
+- SDK: `cloud/packages/sdk/src/client.ts`
+- billing/pricing: `cloud/packages/lib/services/ai-billing.ts`, `ai-pricing.ts`, `credits.ts`
+- app chat: `cloud/apps/api/v1/apps/[id]/chat/route.ts`
+- OpenAI-compatible chat: `cloud/apps/api/v1/chat/completions/route.ts`
+- app monetization: `cloud/apps/api/v1/apps/[id]/monetization/route.ts`
+- app credits: `cloud/packages/lib/services/app-credits.ts`
+- container billing: `cloud/apps/api/cron/container-billing/route.ts`
+
+Active app monetization is markup/share based. Inference in the current app-chat path debits the caller/user org credits and credits creator markup to redeemable earnings. App-credit purchase/share flows exist, but should not be assumed to fund inference unless the endpoint being edited explicitly does so.
+
+## Implemented Architecture
+
+### Default editable skills
+
+Default skills remain bundled in `@elizaos/skills` and are seeded into the managed skills directory only when the user does not already have an editable copy.
+
+Applications and workspaces can override defaults by placing a same-slug skill in a higher-priority skill root. This preserves:
+
+- global defaults included with Eliza
+- user/application customization
+- stable slugs for orchestrator recommendation and invocation
+- short `SKILL.md` bodies with longer references under `references/`
+
+The root `scripts/ensure-skills.mjs` now resolves the shipped skill tree from `@elizaos/skills`, then falls back to `packages/skills/skills`, then legacy `skills/`.
+
+### Parent-agent broker
+
+A new virtual broker skill, `parent-agent`, lets a child ask the running parent Eliza agent to use its loaded capabilities:
+
+```text
+USE_SKILL parent-agent {"request":"Find the next open 30 minute slot on my calendar tomorrow afternoon"}
+```
+
+The broker builds a synthetic message memory and sends it through the parent's normal `messageService.handleMessage(...)` pipeline with `continueAfterActions: true`. This means the parent can use the same actions, providers, services, connectors, model handlers, confirmation policies, and user approval flow it already uses for normal chat.
+
+It also supports action discovery:
+
+```text
+USE_SKILL parent-agent {"mode":"list-actions","query":"github","limit":25}
+```
+
+Sensitive broker access is session allow-listed. The orchestrator includes `parent-agent` in generated manifests for coding-task sessions and registers the manifest slugs as the session allow-list.
+
+### 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.
+
+The injected parent runtime memory also now explains:
+
+- read-only loopback endpoints
+- `ELIZA_SKILLS_MANIFEST` / `SKILLS.md`
+- `USE_SKILL parent-agent`
+- `USE_SKILL lifeops-context`
+- when to ask the parent for connector/private/paid actions
+
+### Git hygiene
+
+The orchestrator-managed gitignore block now includes common generated agent files:
+
+- `CLAUDE.md`
+- `.claude/`
+- `AGENTS.md`
+- `.codex/`
+- `GEMINI.md`
+- `.gemini/`
+- `.aider*`
+- `.opencode/`
+- `SKILLS.md`
+
+Tracked repo files with the same names still need care; ignore rules only prevent new untracked files from being committed.
+
+## Security Model
+
+The child worker never receives the parent API key, full memory dump, or raw connector credentials.
+
+Allowed paths:
+
+- read-only loopback endpoints for bounded parent context
+- `USE_SKILL` directives for session allow-listed skill/broker slugs
+- parent-agent requests mediated by the parent message pipeline
+- parent confirmation flow for paid, destructive, private, or external operations
+
+Denied or discouraged paths:
+
+- ad hoc POSTs to loopback context endpoints
+- bypassing Cloud/user confirmation for paid steps
+- directly recreating parent credentials inside a child workspace
+- treating task-agent output as a persistent authenticated identity
+
+## Five-Pass Implementation Plan
+
+### Pass 1: Prep
+
+- Inventory shipped skills and confirm `@elizaos/skills` is the bundled default source.
+- Inventory orchestrator spawn/memory/manifest/callback code.
+- Inventory Cloud billing, monetization, app chat, SDK, and container deploy source-of-truth files.
+- Decide stable slugs and default override model.
+- Define task-scoped broker protocol and sensitive-broker allow-list behavior.
+
+Status: implemented for the default skill and broker surfaces.
+
+### Pass 2: Implementation
+
+- Add `eliza` default skill and references.
+- Expand app-development, Cloud, monetization, and task-agent bridge skills.
+- Fix root shipped-skill seeding to resolve `@elizaos/skills`.
+- Add `parent-agent` virtual broker.
+- Include `parent-agent` in `SKILLS.md` and the session allow-list.
+- Update worker memory injection and manifest protocol text.
+- Add generated agent files to orchestrator gitignore.
+
+Status: implemented.
+
+### Pass 3: Cleanup
+
+- Keep skill prose short and push details into references.
+- Remove stale "read-only only / no action delegation" wording from task-agent bridge docs.
+- Correct monetization docs where they implied app-specific inference balances in the active route.
+- Align Cloud skill references to current implementation files.
+
+Status: implemented.
+
+### Pass 4: Review And Fixing
+
+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 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.
+
+Status: partially implemented. The first three are covered by code/tests; the last two remain follow-up design items.
+
+### Pass 5: Testing, Verification, Validation
+
+Minimum local tests:
+
+- unit test `parent-agent` broker list-actions, missing request, and message pipeline callback capture
+- unit test `USE_SKILL` directive parsing and sensitive broker routing if practical
+- typecheck `plugin-agent-orchestrator`
+- test `packages/skills` loader/frontmatter paths
+- run `scripts/ensure-skills.mjs` against a temporary `ELIZA_STATE_DIR`
+
+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 ...`.
+- Simulate:
+  - action listing
+  - parent memory search
+  - calendar/GitHub/browser-style parent request
+  - confirmation-required paid Cloud/domain request
+  - denied broker when not allow-listed
+  - task continuation after a returned parent result
+- Run existing SWE/orchestrator benchmarks with and without the broker skill hint.
+
+Status: local unit/type/skills tests are implemented and passing. Live OpenCode/Cerebras/SWE benchmarking requires running services and credentials, so it remains follow-up unless the environment already has them active.
+
+## 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.
+
+## AGI-Level Direction
+
+The long-term target is not a hardcoded "agent helper" action. It is a capability broker:
+
+- the parent runtime exposes a typed capability graph derived from loaded plugins, actions, providers, services, connectors, and policies
+- workers receive task-scoped manifests and can request capabilities without knowing implementation details
+- the parent decides whether to answer, execute, request confirmation, redact, or deny
+- applications override skills and policies by configuration rather than editing orchestrator code
+- benchmarks measure whether workers solve more repo tasks with fewer human interventions and fewer credential leaks
+
+The current implementation establishes the default skill surface and the child-to-parent request path needed for that architecture.

package/docs/sub-agent-routing.md

@@ -0,0 +1,197 @@
+# 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.
+
+## Goals
+
+1. **Origin tracking.** When the main agent spawns a sub-agent in response to
+   a user message in room R, the sub-agent's terminal output (`task_complete`,
+   `error`, `blocked`) lands back in room R, addressed appropriately.
+2. **Main-agent-in-the-loop.** When a sub-agent reports done, the **main
+   agent** — not a separate coordinator — decides whether to:
+   - reply to the user (sub-agent finished, here's the result),
+   - reply to the sub-agent via `SEND_TO_AGENT` (proof not satisfying; keep
+     going),
+   - or both in one turn.
+3. **Cache friendliness.** Sub-agent updates should not invalidate the
+   stable provider/system prefix on every event.
+
+## Components
+
+### `AcpService` (existing)
+
+Spawn surface. TASKS op=create records origin context in
+`session.metadata` at spawn time:
+
+```ts
+{
+  messageId: message.id,    // parent message UUID
+  roomId:    message.roomId,
+  worldId:   message.worldId,
+  userId:    message.entityId,
+  label,
+  source:    content.source,
+}
+```
+
+### `SubAgentRouter` (new — `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.
+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`,
+   - `content.source` = `"sub_agent"`,
+   - `content.inReplyTo` = origin `messageId`,
+   - `content.metadata.subAgent*` carries the structured event
+     (`subAgentSessionId`, `subAgentLabel`, `subAgentEvent`,
+     `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.
+
+#### Why only boundary events
+
+Streaming events (`agent_message_chunk`, `tool_running`, `ready`) would
+re-fire the planner constantly and burn the prompt cache. Live status is
+exposed via the provider instead. The router is the channel for events
+that warrant an action decision.
+
+#### Dedup / idempotency
+
+Events are deduped in-memory by
+`<sessionId>|<event>|<status>|<short hash of payload>`. Same sub-agent
+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".
+
+#### Disable switch
+
+`ACPX_SUB_AGENT_ROUTER_DISABLED=1` keeps the service registered but unbound
+(useful for tests, headless backfills, or staging where you want spawning
+without runtime injection).
+
+#### Round-trip cap
+
+To prevent ping-pong loops where the main agent and a sub-agent endlessly
+ask each other to keep going, the router tracks per-session inject count.
+When the count exceeds `ACPX_SUB_AGENT_ROUND_TRIP_CAP` (default 32) the
+router force-stops the session and emits a single
+`round_trip_cap_exceeded` memory carrying `subAgentRoundTrip`,
+`subAgentRoundTripCap`, and `subAgentCapExceeded: true`. Subsequent events
+from the same capped session are suppressed.
+
+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`)
+
+Cache-friendly view of live sub-agent sessions. Filters to:
+
+- sessions whose `metadata.roomId` is set (i.e. routed by `createTaskAction`),
+- sessions not in a terminal status (`stopped`, `completed`, `error`,
+  `errored`, `cancelled`).
+
+The text is **structural only** — id, label, agentType, bucketed status,
+last two workdir segments. No timestamps, no message excerpts. Sorted by
+`sessionId` so the rendered text is byte-stable across turns when the
+active set is unchanged.
+
+Status bucketing: `ready`, `running`, `busy`, `tool_running`, and
+`authenticating` all collapse to the literal string `"active"` in the
+provider text. `blocked` is preserved as a distinct value (the planner
+needs to know a session is waiting for input). Terminal statuses
+(`stopped`, `completed`, `error`, `errored`, `cancelled`) cause the
+session to be filtered out entirely. This keeps the cached provider
+segment byte-identical across transient status flips like
+`ready → tool_running → ready`, which would otherwise invalidate the
+prefix cache on every tool call.
+
+This is the live status channel. The synthetic Memory posted by the router
+is the per-event channel.
+
+### Action set
+
+The main agent's planner sees:
+
+- **`REPLY`** (from the bootstrap action set) — replies to the user in
+  current room.
+- **`SEND_TO_AGENT { sessionId, text }`** — pushes a follow-up to a
+  live sub-agent. Use when the sub-agent's proof is unsatisfying or it
+  asked a clarifying question.
+- **`STOP_AGENT { sessionId }`** — terminates. Use when the sub-agent's
+  output is clearly final and you don't want it idling.
+- **`ACPX_CREATE_TASK`** — spawn additional sub-agents.
+
+Multi-action plans (e.g. `[REPLY, SEND_TO_AGENT]`) are supported by the
+planner and execute sequentially in one turn.
+
+## Cache discipline
+
+Anthropic prompt caching breaks at segment boundaries (see
+`plugin-anthropic/models/text.ts`). The plugin marks providers and action
+examples as `stable: true`. Sub-agent flow is designed around this:
+
+- **Stable prefix (cached):** system prompt, character bio, action examples,
+  active-sub-agents provider text (structural only, sorted, deterministic).
+- **Volatile suffix (re-tokenized):** the sub-agent's synthetic message
+  text (the per-event narration).
+
+Each new sub-agent event invalidates only the message tail. The provider
+text changes only when a session enters or leaves the active set, not on
+every chunk.
+
+A per-session router invocation is one cache-miss tail; everything before
+the most recent turn stays warm.
+
+## Loop safety
+
+- The router emits **inbound** memories with `entityId` set to the
+  sub-agent's pseudo-UUID (not `runtime.agentId`), so the runtime processes
+  them as messages from another entity, not as the agent's own outputs.
+- The main agent's reply via `SEND_TO_AGENT` does not directly trigger a
+  new `task_complete`. The sub-agent has to actually do work first, which
+  bounds re-entry.
+- Dedup prevents accidental double-injection from event re-emission.
+- The round-trip cap (above) is the hard ceiling for ping-pong loops.
+
+## Coordinator 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.
+
+The swarm coordinator's autonomous decision logic
+(`makeCoordinationDecision`, `buildTurnCompletePrompt`,
+`buildBlockedEventMessage`) is replaced by the main agent's normal action
+selection over the synthetic Memory.
+
+## Testing
+
+- `__tests__/unit/sub-agent-router.test.ts` — origin tracking, dedup,
+  streaming-event filtering, disable switch, error narration, fallback
+  emit, unsubscribe.
+- `__tests__/unit/active-sub-agents.test.ts` — origin filtering, terminal
+  exclusion, deterministic sort, no volatile fields, action-hint text.
+
+## Related files
+
+- [src/services/sub-agent-router.ts](../src/services/sub-agent-router.ts)
+- [src/providers/active-sub-agents.ts](../src/providers/active-sub-agents.ts)
+- [src/services/acp-service.ts](../src/services/acp-service.ts)
+- [src/actions/create-task.ts](../src/actions/create-task.ts)
+- [src/actions/send-to-agent.ts](../src/actions/send-to-agent.ts)