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

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

@@ -0,0 +1,225 @@
+# 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, 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.
+
+## 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/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-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/OpenCode 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/`
+- `.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 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's vendored ACP path has enough smoke coverage against Cerebras.
+
+Status: partially implemented. The first three are covered by code/tests; live OpenCode/Cerebras validation remains credential-gated.
+
+### 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, 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
+  - 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
+
+- 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/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.

package/docs/multi-account-orchestration.md

@@ -0,0 +1,76 @@
+# Multi-account coding-agent orchestration
+
+Goal: an Eliza orchestrator agent that runs **multiple Claude Code + Codex
+subscriptions** (and rotates OpenCode across pooled Cerebras accounts), picks
+the **least-used** account for each new
+sub-agent, tracks per-account **session + weekly usage**, manages those
+sub-agents in a **shared task room**, and decides **when to interrupt** a
+running sub-agent vs. let it keep working.
+
+## What already existed (do not rebuild)
+
+| Layer | Location | Status |
+|---|---|---|
+| Account contracts (`LinkedAccountConfig`, `LinkedAccountUsage`, 12 provider ids) | `packages/contracts/src/service-routing.ts` | ✅ |
+| Credential storage (`<stateDir>/auth/{providerId}/{accountId}.json`) | `packages/agent/src/auth/account-storage.ts` | ✅ |
+| OAuth flows (Anthropic + Codex) + coding-plan keys + API keys | `packages/agent/src/auth/oauth-flow.ts`, `credentials.ts` | ✅ |
+| `AccountPool` — priority / round-robin / **least-used** / quota-aware, affinity, health | `packages/app-core/src/services/account-pool.ts` | ✅ |
+| Usage probes (`pollAnthropicUsage`, `pollCodexUsage`) + JSONL day counters | `packages/app-core/src/services/account-usage.ts` | ✅ |
+| Accounts REST API (`/api/accounts/*` incl. OAuth SSE) | `packages/agent/src/api/accounts-routes.ts` | ✅ |
+| Settings UI (AccountList / AccountCard / AddAccountDialog / RotationStrategyPicker) + `useAccounts` | `packages/ui/src/components/accounts/*` | ✅ |
+| Multi-account API-key routing for the *main agent* | `credential-resolver.ts` → `resolveProviderCredentialMulti` | ✅ |
+| Orchestrator tasks, sessions, task-rooms, event bridge, usage rollup, REST + SSE | `plugins/plugin-agent-orchestrator/*` | ✅ |
+| `shouldRespond` (RESPOND/IGNORE/STOP) + per-room `TurnControllerRegistry` abort | `packages/core/src/*` | ✅ |
+
+## The keystone gap
+
+The `AccountPool` was wired into **API-key model routing** but **not into the
+coding-agent spawn path**. Coding agents authenticate by *subscription*, not API
+key: `applySubscriptionCredentialsLocal` never injects Claude/Codex tokens into
+`process.env`, and `AcpService.buildEnv` even *strips* an OAuth
+`ANTHROPIC_API_KEY` so Claude Code falls back to the single machine login
+(`~/.claude`). So every spawned sub-agent used one account, with no rotation and
+no per-account attribution.
+
+The orchestrator plugin depends only on `@elizaos/core`, so it cannot import the
+pool. `account-pool.ts` already solves this with `globalThis`-symbol **bridges**
+(Anthropic + subscription-selector). We add a third: a **coding-agent selector
+bridge**.
+
+## Hitlist
+
+### P0 — Keystone: account selection on spawn (round-robin / least-used)
+- [x] `coding-account-bridge.ts` (app-core): install `Symbol.for("eliza.account-pool.coding-agent.v1")` bridge — `select(agentType)`, `markRateLimited`, `markNeedsReauth`, `recordUsage`, `describe()`.
+- [x] Per-agent credential injection: claude → `CLAUDE_CODE_OAUTH_TOKEN`; codex → per-account `CODEX_HOME/auth.json` + minimal `config.toml`; opencode → `CEREBRAS_API_KEY` (pooled Cerebras); direct API providers → their env key.
+- [x] Wire into `AcpService.spawnSession`: select before transport branch, merge `envPatch` into `customCredentials`, stamp `session.metadata.account*`, surface on `SpawnResult.metadata`.
+- [x] `buildEnv`: when `CLAUDE_CODE_OAUTH_TOKEN` is injected for claude, drop `ANTHROPIC_API_KEY` so the selected subscription wins.
+- [x] `OrchestratorTaskSession` carries `accountProviderId` / `accountId` / `accountLabel`; populate from `result.metadata`.
+- [x] Exclude-on-failure retry: on auth/rate-limit error, mark account + re-select excluding it.
+
+### P1 — Usage attribution + stats
+- [x] `recordUsage` also calls the bridge → pool `recordCall` + `account-usage` JSONL keyed by the serving account.
+- [x] `/api/orchestrator/accounts` route: connected accounts + live usage + which sub-agents are on which account.
+- [x] Settings already shows per-account usage; orchestrator dashboard widget adds the accounts + usage summary.
+
+### P2 — Room system + interruption decider
+- [x] Per-participant interruption decider: a running sub-agent keeps working; a new room message is classified (deliver / queue / interrupt / ignore) before it is injected. The "busy" check covers `tool_running` (the dominant mid-turn state), not just `busy`; queued messages flush when the session returns to `ready`. An Eliza participant's `shouldRespond` verdict threads through unchanged when a caller supplies it; coding sub-agents use the structural decider. `multiParty` (more than one live sub-agent in the room) is computed in the forward handler so ambient-chatter suppression is live.
+- [x] Task-room participant **view**: the "Coding accounts" sidebar widget shows the live sub-agent → account assignment map + per-account usage (the flat global map). The dedicated per-room participant roster (orchestrator + owning user + each sub-agent grouped by room, with `activeAgentCount` / `multiParty`) now ships as `GET /api/orchestrator/rooms` (`OrchestratorTaskService.getRoomRoster`), the room-scoped counterpart to `/accounts`. Rooms with no sub-agent sessions are omitted.
+
+### P3 — Tests + mocks + live E2E
+- [x] Mock account fixtures (multi-account, multi-provider) + an in-memory pool for unit tests.
+- [x] Unit tests: selection strategy, per-agent env injection + API-key drop (Claude & Codex), intra-provider retry, usage attribution, interruption decider, route registration.
+- [x] Live E2E (gated `ORCHESTRATOR_LIVE_MULTI_ACCOUNT=1`): validates the selector bridge + usage probe against ≥2 **real** linked accounts (distinct-account rotation via the exclude set; live session/weekly usage).
+- [x] **Composed offline E2E** (`bun run --cwd plugins/plugin-agent-orchestrator test:e2e:multi-account`): real app-core `AccountPool` (real-format mock accounts in a temp state dir) → installed selector bridge → orchestrator `AcpService.spawnSession` → a REAL spawned subprocess (a fake "acpx" standing in for the subscription CLI). Asserts 10/10: two Claude spawns pick **distinct** accounts (least-used round-robin), each subprocess receives its account's `CLAUDE_CODE_OAUTH_TOKEN`, the parent `ANTHROPIC_API_KEY`/`OPENAI_API_KEY` are dropped, Codex gets a per-account `CODEX_HOME/auth.json` with the right token+account_id. Point `ELIZA_ACP_CLI` at the real binary + connect real accounts for true live-key validation. (This harness caught a real cli-transport bug: `runAcpx` rebuilt the env without `agentType`, re-adding the parent keys — now fixed.)
+
+### P4 — Connect-accounts window
+- [x] The connect-accounts window (Settings → Accounts: `AddAccountDialog` OAuth / API-key / coding-plan-key flows, `AccountList`, `RotationStrategyPicker`) pre-exists and is the surface for linking multiple accounts of each type.
+
+## Known constraints / follow-ups
+- **OpenCode pool-rotates across Cerebras accounts only.** OpenCode resolves a pooled key for exactly one backend — Cerebras (`CEREBRAS_API_KEY`, see `buildOpencodeSpawnConfig`) — so `opencode` is a multi-account selector type mapped to `cerebras-api`: it least-used-rotates across linked Cerebras accounts (the bridge injects the selected `CEREBRAS_API_KEY`, which OpenCode's config reads) and no-ops when none are linked (Eliza Cloud / single-key setups are unchanged). OpenCode's other backends (Eliza Cloud, local, user-configured opencode.json) are not pooled. Precedence: a `CEREBRAS_API_KEY` runtime **setting** still wins over a pooled injection — pooling is authoritative only when no single key is configured.
+- **z.ai / Kimi / GLM have no first-party coding CLI.** Their linked accounts serve the main runtime's API-key routing (`resolveProviderCredentialMulti` for `zai-api` / `moonshot-api`) and OpenCode's provider config — there is no `zai`/`kimi`/`glm` spawnable agent type, so they are not advertised as coding-agent selector candidates.
+
+## Quality bar
+- No regression when zero accounts are linked (bridge returns null → today's behavior).
+- Selected account is **observable** (session metadata + structured log + dashboard), never assumed.
+- Subscription tokens only ever flow to the first-party coding subprocess (TOS), never into runtime `process.env`.
+- Per-agent credential precedence is enforced: a selected Claude subscription drops `ANTHROPIC_API_KEY`; a selected Codex subscription (per-account `CODEX_HOME`) drops a forwarded `OPENAI_API_KEY` — so the chosen account always authenticates.

package/docs/orchestrator-buildout-followups.md

@@ -0,0 +1,124 @@
+# Orchestrator (`/orchestrator`) build-out — status & follow-ups
+
+Date: 2026-05-29. Companion to [`research/orchestrator-view-research-report.md`](./research/orchestrator-view-research-report.md).
+
+This records what was finished in the `nubs/orchestrator-view-feature` branch and the
+exact, code-grounded plan for the remaining design-heavy work. The earlier research
+report is largely **out of date**: the durable task model, SQL store, `/api/orchestrator/*`
+routes, central goal-wrapper, validation-gated completion, token aggregation, the
+`OrchestratorWorkbench` view, and the real (non-stub) client methods all already exist
+(Shaw shipped most of it on 2026-05-29). Verify against current code, not the report's
+line numbers.
+
+## Done in this branch (verified)
+
+1. **Mounted the sub-agent credential bridge** (`plugin-agent-orchestrator/src/api/routes.ts`).
+   `handleBridgeRoutes` was built+tested but never dispatched. + dispatcher regression test.
+2. **Unified the goal-wrapper** so the `TASKS` planner action uses the central
+   `buildGoalPrompt`/`buildGoalFollowUp` (`goal-prompt.ts`, `actions/tasks.ts`) instead of a
+   divergent inline envelope. Workspace-routing / URL-mapping / swarm-room content preserved
+   via new optional `GoalPromptInput` fields. + equivalence test (action env == API env).
+3. **Folded durable task threads into `getCodingAgentStatus`** (`packages/ui` client) — was
+   hardcoded to `taskThreadCount:0`. Documented the two genuinely-vestigial ACP stubs
+   (`/metrics`, `/workspace-files`) pointing at the real `/api/orchestrator/*` usage surface.
+4. **Declared capability param schemas** for the 15 orchestrator view capabilities so
+   voice/NL routing can pass `taskId`/`title`/`goal`/etc. **Mounted the sensitive-request
+   REST routes** (`packages/app-core/src/api/server.ts`) — the secret create/submit/fulfill
+   path that orchestrator provider setup will use.
+5. **Locked capability manifest↔dispatch parity** with a regression test
+   (`plugin-task-coordinator/__tests__/unit/orchestrator-capability-parity.test.ts`) + a
+   `test` script so CI runs it. The declared capabilities (`ORCHESTRATOR_CAPABILITIES` in
+   `index.ts`) must exactly match the ids `runOrchestratorCapability` dispatches; this drift
+   previously reopened (`orchestrator-update-task`/`-validate-task`).
+
+## App-shell hardening (this branch)
+
+**Stale/unreachable saved server can no longer wedge first-run.** A persisted
+`elizaos:active-server` pointing at a now-dead / CSP-blocked remote backend pinned the
+client to that address; the startup poll (`packages/ui/src/state/startup-phase-poll.ts`)
+retried it until `BACKEND_TIMEOUT` and onboarding hung forever (clearing cookies didn't
+help — the pointer lives in localStorage). Fix: on a *connection-level* failure (the request
+never received an HTTP response) against a non-loopback, non-same-origin base on an http(s)
+page — never on native mobile, where the remote IS the agent — clear the saved server,
+re-point the client at the local origin, and reach the backend (one-shot). The decision is a
+pure exported `shouldFallBackToLocalOrigin` covered by a unit matrix, plus an end-to-end
+recovery test.
+
+**Onboarding boot issues we hit that are environmental, not code bugs (no regression test
+applies):**
+- *"No provider registered for TEXT_EMBEDDING" → agent won't boot* — caused by a local
+  `ELIZA_DISABLE_LOCAL_EMBEDDINGS=1` in `.env.worktree` with no cloud route, i.e. *zero*
+  embedding providers. With local embeddings enabled the agent boots degraded-but-non-fatal
+  (the intended behavior). A graceful-degradation guard for the "no embedding provider at
+  all" edge would live in agent/runtime bootstrap, not here; flagged for the runtime owner.
+- *Dev service-worker / HTTPS-upgrade theories* — investigated and **disproven** by
+  reproduction; the actual cause was the stale active-server above. The dev SW renders fine
+  with caching active. An optional dev-only self-unregistering SW remains available as a
+  hygiene improvement but guards no confirmed bug.
+
+## Remaining work (specced, not yet built)
+
+Ordered by leverage. `[BE]` backend, `[FE]` frontend, `[T]` tests.
+
+### A. `orchestrator-open-task` should navigate the workbench `[FE]` — S/M
+`runOrchestratorCapability` ("open-task") fetches detail but does not call `setSelectedId`,
+so a voice "open task X" returns data without visually navigating. `interact()` is a
+module-level function with no handle to the live component state. Fix: have the workbench
+register a navigation callback (e.g. a module-scoped `setSelectedTaskHandler` the mounted
+`OrchestratorWorkbench` sets in a `useEffect`, called by the open-task capability), or route
+selection through the existing `?task=` deep-link that `readInitialTaskId` already reads.
+
+### B. Bridge-backed provider setup `[BE][FE]` — M (design-touching)
+Today `LlmProviderSection`/`CodingAgentSettingsSection` write `ANTHROPIC_API_KEY` etc.
+straight into agent env via `client.updateConfig({ env })` — not the vault. Now that the
+sensitive-request REST routes are mounted, wire missing-key flows to fire `SECRETS
+action=request` (or POST `/api/sensitive-requests`) so secrets land in `sharedVault`. Reuse
+the existing `ProviderCard`/`ProviderPanels`/`useProviderSelection` components rather than the
+bespoke password inputs. Needs a decision on which providers/scopes/validation; do not change
+secret-storage policy without the design owner. Secure-cloud / secure-local / insecure-local
+fallbacks + redaction tests per the report's "Secret And OAuth Flow" section.
+
+### C. Workbench UX gaps `[FE]` — small each, need visual iteration
+From the fidelity review of `OrchestratorWorkbench.tsx` (largely complete; these are the gaps):
+- **Jump-to-latest / autoscroll** in the timeline — no scroll ref/affordance today (net-new).
+- **Change-provider control** — no UI and no `orchestrator-change-provider` capability/backend; provider policy is read-only. Needs a backend capability first.
+- **Branch display** in the sub-agent roster (only repo/workdir shown).
+- **System-event collapse**: only a global show/hide toggle, not expandable clusters.
+- **Verification checklist**: only per-artifact status pills, no dedicated pass/fail surface.
+- **Per-task USD spend** in the left rail (rail shows tokens; cost only in header + inspector).
+- **Provider "state"**: shows policy/identity, not live health/availability.
+
+### D. Remote / mobile for the orchestrator `[BE][FE]` — L (separate design)
+Pairing primitives exist (`auth-pairing-routes`, `tunnel-to-mobile-client`) but **no `tunnel`
+runtime service is registered** (so `runtime.getService("tunnel")` lookups and
+`tunnel_authenticated_link` delivery are inert). The workbench is **polling-only**
+(`POLL_INTERVAL_MS = 5000`); there is no SSE/WS for task updates. Needs: a registered tunnel
+service (`getStatus/isActive/getUrl`), a relay decision (cloud gateway vs Headscale/ngrok per
+the tunnel-to-mobile design), remote-API auth, and SSE/WS to replace the 5s poll so remote/
+mobile clients aren't hammering. Do not attempt blind — design + visual iteration required.
+
+### E. Test depth `[T]`
+Add the report's e2e workflow matrix with mocked providers (create/fork/pause-all/archive/
+search/secret-flows/validation-failure-reopen), keeping live Claude/Codex tests env-gated.
+Also add an integration-level test that drives a `/credentials/*` request through the runtime
+route matcher (`matchPluginRoutePath`), not just the in-process dispatcher, so the
+registry-registration gap (fixed in this branch) can't silently reopen.
+
+### F. Deferred from adversarial review (low priority, not regressions)
+- **Bridge loopback hardening** `[BE]` — `bridge-routes.ts:isLoopback` trusts only
+  `req.socket.remoteAddress` (same model as the existing parent-context bridge). If the
+  runtime is ever fronted by a loopback-bound reverse proxy, mirror the extra checks from
+  `isTrustedLocalRequest` (reject forwarded/proxy-client headers and cross-site
+  `sec-fetch-site`). The single-use scopedToken remains the per-request defense regardless.
+- **Re-anchor follow-ups to the durable goal** `[BE]` — `buildGoalFollowUp` reads
+  `metadata.goal`, but the planner spawn paths in `tasks.ts` never stamp a `goal` key, so
+  follow-ups currently re-anchor to the latest message rather than the original objective.
+  Stash `goal: task` (or the durable goal) onto session metadata at spawn time to realize
+  the intended re-anchoring. Not a regression — the old code sent raw text.
+
+## How to work this branch
+Isolated worktree `/home/nubs/Git/iqlabs/eliza-labs/eliza-orchestrator-feat`, branch
+`nubs/orchestrator-view-feature`. Fresh worktrees need `@elizaos/core` built first
+(`cd packages/core && bun run build`) or vitest can't resolve `@elizaos/core`; building the
+full plugin set is required to run app-core integration tests. Rebase onto the active branch
+before merging (file sets don't overlap with the desktop/local-inference work in flight).