@elizaos/plugin-agent-orchestrator 2.0.0-beta.1 → 2.0.11-beta.7

package/docs/orchestrator-dashboard-task-widget-secrets-design.md

@@ -0,0 +1,301 @@
+# Orchestrator dashboard, in-chat task widget, and secrets widgets — design
+
+Date: 2026-06-05. Companion to
+[`orchestrator-buildout-followups.md`](./orchestrator-buildout-followups.md).
+
+This is a code-grounded, intentionally small design for three connected gaps the
+goal hook calls out, in priority order:
+
+1. **Orchestrator view should read as a *dashboard*** of ongoing tasks — quick
+   active/finished/needs-attention counts at the top, a minimal card list
+   underneath, click a card to drill into the existing full inspector.
+2. **Task creation should drop a live `TaskWidget` into the chat** that shows
+   status and is clickable. The chat conversation continues; the agent keeps
+   task context; the orchestrator view's action bar stays view-dependent on the
+   currently-selected task.
+3. **Sensitive-request widgets in chat (form / OAuth / secret) must
+   actually work and be tested**, with no secret material echoed to chat.
+
+Scope is intentionally narrow. The existing
+[`OrchestratorWorkbench.tsx`](../src/OrchestratorWorkbench.tsx) (4142 LOC) is
+mature — rail, inspector, action bar, timeline, operator drawer, plan editor.
+We do not redesign it. We add a thin glance strip, fix the gaps, and lock
+behavior in tests.
+
+## What exists today (ground truth)
+
+- `OrchestratorWorkbench` renders `/orchestrator`. Header has Pause All / Resume
+  All / New Task; a filter dropdown shows status + count; rail renders
+  `TaskCardList` cards. Selecting a card swaps the rail for a full-pane task
+  room with timeline + inspector (`data-testid="orchestrator-inspector"`).
+  Inspector action bar is already view-dependent: validating → Approve/Reject,
+  archived → Reopen, active → Pause/Resume, plus Fork/Restart/Add Agent.
+- `MessageContent.tsx` dispatches 7 segment kinds: `text`, `config`, `ui-spec`,
+  `choice`, `followups`, `form`, `permission`, `analysis-xml`. **There is no
+  `task-widget` kind**. A `[TASK:id]title[/TASK]` block in an assistant message
+  renders as plain text today.
+- `SensitiveRequestBlock` (in `MessageContent.tsx`) renders inline-secret form
+  widgets driven by `message.secretRequest`. It is tested
+  (`MessageContent.sensitive-request.test.tsx`). It supports `form.kind ===
+  "secret"` only; **OAuth is not wired** — `owner-app-inline-adapter.ts`
+  explicitly rejects any non-secret kind.
+- `task-coordinator-gui-interactions.spec.ts` covers list, search, open detail,
+  archive, reopen. `orchestrator-gui-workbench.spec.ts` covers the rich rail
+  and inspector controls (priority change, restart-with-plan, add agent,
+  pause/resume, retry/rerun). **Neither covers a chat task widget or any
+  sensitive-request widget.**
+
+## Design
+
+### 1. `OrchestratorGlanceStrip` — at-a-glance dashboard tile
+
+A single pinned row above the rail, four count tiles + the existing usage chip.
+No new state — derived from the same `/api/orchestrator/status` payload the
+header reads. Each tile is a button that sets the filter and scrolls the rail
+to the top.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ ● 3 Active   ◐ 1 Validating   ⚠ 0 Blocked   ✓ 12 Done   12.3K · $0.42 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+Rules:
+
+- **One row, fixed height.** ~32px. No subtitle text under counts.
+- **Color = state, not decoration.** `ok` for Active, `accent` for Validating,
+  `warn` for Blocked, `muted` for Done.
+- **Zero = `muted` text + de-emphasized tile.** Zero counts never animate.
+- **Click filters.** Click "Active" → filter "active". Click "Blocked" →
+  filter "blocked" (rolls up `waiting_on_user` per existing status fan-out).
+- **Hidden when there are zero tasks total** — the empty state already covers
+  this case.
+
+Test ids: `orchestrator-glance`, `orchestrator-glance-active`,
+`orchestrator-glance-validating`, `orchestrator-glance-blocked`,
+`orchestrator-glance-done`.
+
+Implementation: new component `OrchestratorGlanceStrip.tsx` rendered in
+`OrchestratorWorkbench.tsx` directly above the rail. It reads
+`taskCount`/`activeTaskCount`/`blockedTaskCount`/`validatingTaskCount` from
+the same status payload `WorkbenchHeader` already consumes; we promote a small
+counts derivation out so both call sites stay in sync.
+
+### 2. `TaskWidget` — inline chat widget for an orchestrator task
+
+A new segment kind in `MessageContent`. The agent emits
+`[TASK:<threadId>]<title>[/TASK]` after a successful `TASKS_CREATE`, and the
+chat renderer replaces it with a live widget.
+
+Anatomy (one compact card, ~64px tall):
+
+```
+┌────────────────────────────────────────────────────────┐
+│ ▶ Build Kanban planner app           [Open]           │
+│   ● active · 2/2 agents · 3m ago · ~12.3K              │
+└────────────────────────────────────────────────────────┘
+```
+
+Rules:
+
+- **One title line + one status line.** No goal, no acceptance criteria, no
+  artifact list. Those live in the orchestrator inspector.
+- **Status line is structured, not prose.** Status dot + label, agents
+  active/total, relative last activity, token total. Tokens hidden when
+  `usageState === "unavailable"`.
+- **Click → navigate `/orchestrator?taskId=<id>`** (the workbench already
+  reads `?task=` via `readInitialTaskId`; we alias `?taskId=` to it).
+- **Live updates by polling**, not WebSocket. Reuses the workbench's
+  `POLL_INTERVAL_MS = 5000` (kept in one place — exported, not duplicated). On
+  unmount, polling stops. When the underlying task is terminal
+  (`done`/`failed`/`archived`/`closed`), polling stops and the status freezes.
+- **One outstanding fetch per widget.** Concurrent renders share a tiny
+  per-thread cache so two widgets in scrollback don't quadruple traffic.
+- **No action buttons inline.** Action belongs to the workbench's
+  view-dependent action bar (we are explicit about this — the goal asks the
+  workbench to own actions when on a task).
+- **Failure mode is silent.** If the task 404s (deleted), the widget shrinks
+  to "Task removed." in muted text; it never throws into the chat.
+
+Backend hook: after `TASKS_CREATE` succeeds, the action's response text gets
+`[TASK:${task.id}]${task.title}[/TASK]` appended. This is a one-line change in
+`tasks.ts` (the `create` runner already returns a callback with prose).
+
+Segment parser: extend the existing regex sweep in
+`MessageContent.parseSegments` with a `[TASK:...]...[/TASK]` pattern, ordered
+after `[FORM]` and before plain text. The matcher requires `threadId` to be a
+UUID-shaped string (lowercase a–f0-9-) to avoid trivial injection from
+unrelated text.
+
+Test ids: `task-widget`, `task-widget-status`, `task-widget-open`.
+
+### 3. View-dependent action bar in the workbench
+
+Already exists in `TaskInspector` (`OrchestratorWorkbench.tsx` lines
+2007–2187). It is correctly state-conditional but every button is always
+rendered (just disabled when N/A). The minimal change is grouping and hiding:
+
+- **Hide the entire "Edit" group** (Fork, Restart, Add Agent, Edit Plan) when
+  `task.status` is in {`done`, `failed`, `archived`, `closed`}. Terminal tasks
+  should only expose Reopen (and Delete).
+- **Hide priority dropdown for terminal tasks.** Priority is meaningless once
+  closed.
+- **Keep validating-task Approve/Reject as the only primary affordance.**
+  Other buttons collapse into an overflow.
+
+This is small — three `if` guards. Locked in by an inspector test that
+toggles status and asserts visibility.
+
+### 4. Sensitive-request widgets — what's working and what we add
+
+Working today: inline form for `kind: "secret"`. We tighten and extend.
+
+**a. `SensitiveRequestBlock` polish (existing component, small fix)**
+
+- Distinguish `pending` (gray "Pending"), `saving` (spinner + "Saving…"),
+  `saved` (green "Saved" + redacted preview "•••• (saved)"),
+  `failed` (red "Failed — retry"), `expired` (muted "Expired").
+- On `saved`, the form **never re-renders the password input** for the same
+  request id, even if the message re-mounts. Backed by a tiny per-requestId
+  saved-state cache in component scope.
+- Reason and instruction text already render; we make sure they never include
+  the secret value (server-side sanitization is the actual guarantee; the
+  widget asserts `value` is never substituted into `instruction` or `reason`
+  via `MessageContent.sensitive-request.test.tsx`).
+
+**b. `OAuthRequestBlock` (new, in `MessageContent.tsx`)**
+
+Renders when `message.secretRequest.form.kind === "oauth"`. Shape:
+
+```
+┌────────────────────────────────────────────┐
+│  Connect GitHub                            │
+│  Needed for: managing PRs on this task     │
+│                                            │
+│  [ Connect with GitHub → ]   Pending       │
+└────────────────────────────────────────────┘
+```
+
+Rules:
+
+- **One button.** It calls `client.startSensitiveRequestOAuth(requestId)`
+  which returns `{ authorizationUrl, state }` and opens it in a popup
+  (`window.open` with a sized rect). Same-origin fallback for embedded
+  environments where popups are blocked.
+- **No token ever passed through chat.** The OAuth callback fulfills the
+  request server-side; the widget polls
+  `GET /api/sensitive-requests/:id/status` every 2s, up to `expiresAt`, and
+  stops on terminal states.
+- **Visible state machine:** `Pending` → `Authorizing…` → `Saved` |
+  `Failed — retry` | `Expired`.
+- **Cancel.** A small `Cancel` link sends `DELETE
+  /api/sensitive-requests/:id` and flips to `Cancelled`.
+
+Backend wiring is a sibling of the inline adapter:
+`packages/app-core/src/services/sensitive-requests/owner-app-oauth-adapter.ts`.
+The adapter's `deliver()` accepts `request.target.kind === "oauth"` requests
+(new target kind), builds an envelope with `form: { kind: "oauth", provider,
+scopes, label, submitLabel: "Connect …" }`, and sends the inline chat content.
+The OAuth callback handler lands tokens in `sharedVault` exactly like the
+existing GitHub OAuth flow; only the *trigger* differs.
+
+We do **not** ship a generic OAuth backend in this slice. We ship the widget +
+its parser + a fixture-backed e2e + a unit test for envelope construction.
+A follow-up wires production providers (per
+[`orchestrator-buildout-followups.md`](./orchestrator-buildout-followups.md)
+section B).
+
+**c. `FormRequest` (existing `[FORM]` widget) — unchanged**
+
+The non-sensitive `[FORM]` widget already works
+(`form-request.tsx`). It is referenced here only to draw the line: that
+widget's submission **is echoed to chat** because it carries non-secret data.
+Sensitive requests must never reuse it.
+
+### Security guarantees we explicitly maintain
+
+- The secret/OAuth widgets must never push the value or token into the chat
+  message stream. The current inline adapter calls
+  `client.updateSecrets(secrets)` directly and ignores its message channel
+  for the value; we keep that, and add an integration test that scrapes the
+  recorded chat-message stream after a successful save and asserts no field
+  value appears.
+- OAuth callbacks must never include tokens in URL fragments delivered to the
+  chat surface. The popup posts the result to the server; the chat surface
+  only sees `status` transitions.
+- Widget rendering is gated on `delivery.canCollectValueInCurrentChannel ===
+  true`. Public/group surfaces continue to render the existing
+  status-only card pointing at the owner app.
+
+## Tests
+
+All under existing infra (`packages/ui` vitest for components,
+`packages/app/test/ui-smoke` Playwright for the route).
+
+1. **Component (vitest, packages/ui):**
+   - `MessageContent.task-widget.test.tsx` — `[TASK:id]title[/TASK]` parses to a
+     `TaskWidget`; renders title; polls once and renders status; click
+     dispatches navigation.
+   - `MessageContent.sensitive-request.test.tsx` (extend) — status transitions;
+     saved-state cache survives remount; instruction never contains the
+     entered value.
+   - `MessageContent.oauth-request.test.tsx` — OAuth widget shows Connect,
+     opens popup (mocked `window.open`), polls status, lands on `Saved`.
+
+2. **Plugin (vitest, plugin-agent-orchestrator):**
+   - `create-task-emits-task-block.test.ts` — `TASKS_CREATE` runner output
+     contains `[TASK:${id}]${title}[/TASK]`.
+   - `owner-app-oauth-adapter.test.ts` — envelope shape; rejects non-OAuth
+     kind; emits an inline content with `form.kind === "oauth"`.
+
+3. **Playwright (packages/app):**
+   - Extend `orchestrator-gui-workbench.spec.ts` with a `glance strip` test —
+     fixture seeds 3 active / 1 validating / 12 done; assert tile counts;
+     click Validating → filter switches; assert rail shows only the validating
+     task.
+   - New `task-widget-in-chat.spec.ts` — boot the chat route, send a
+     "create task X" prompt, mock the orchestrator POST to return a fixture
+     task, assert a `task-widget` appears, status flips to active when the
+     mocked poll returns active, click `task-widget-open` lands on
+     `/orchestrator?taskId=…` with that task selected and its inspector
+     visible.
+   - New `sensitive-request-in-chat.spec.ts` —
+     (a) seed a secret request, fill the password, submit, assert
+     `client.updateSecrets` was called with that field, assert the password
+     is **never** posted to any chat-message endpoint;
+     (b) seed an OAuth request, click Connect, mock popup `postMessage`
+     completion, assert status flips to Saved without any token appearing in
+     the chat-message stream.
+
+4. **Scenario runner (`packages/scenario-runner`):** add a `task-creation`
+   scenario that drives the e2e create → widget → click → workbench path
+   against the real orchestrator routes, using the fake-ACP transport already
+   used by the orchestrator unit tests. Gated under `test:e2e:manual` because
+   it needs the ACP transport pinned, matching the existing convention.
+
+## Out of scope (explicitly)
+
+- Replacing the 5s poll with SSE/WS — that's
+  [`orchestrator-buildout-followups.md`](./orchestrator-buildout-followups.md)
+  section D and design-touching.
+- A general "remote/mobile orchestrator" — same followups section D.
+- Re-anchoring planner follow-ups to durable goal — section F.
+- Real production OAuth providers beyond the widget — see followups B.
+
+## Rollout
+
+One PR per slice keeps blast radius small and lets the visual review run on
+each:
+
+1. Slice 1: `OrchestratorGlanceStrip` + counts derivation + tests.
+2. Slice 2: `task-widget` segment + `TaskWidget` component +
+   `TASKS_CREATE` emission + unit tests.
+3. Slice 3: `task-widget-in-chat.spec.ts`.
+4. Slice 4: Sensitive-request polish + OAuth widget + adapter +
+   `sensitive-request-in-chat.spec.ts`.
+5. Slice 5: View-dependent inspector cleanup (hide Edit group on terminal,
+   hide priority on terminal) + inspector test.
+
+Each slice ships and gets an audit pass. No slice is "done" until the
+relevant Playwright spec is green locally and the chat / `/orchestrator`
+route renders cleanly under the workbench audit pass.

package/docs/research/orchestrator-view-research-report.md

@@ -0,0 +1,273 @@
+# Orchestrator View Research Report
+
+Date: 2026-05-30
+
+## High-Level Goal
+
+Build an `/orchestrator` experience for ElizaOS that treats work as durable tasks, not disposable chats. The main orchestrator room should remain open indefinitely, create and fork task rooms from natural language or explicit UI controls, provision Claude/Codex/OpenCode/Eliza sub-agents using persistent `/goal`-style prompts, and never present a task as done until acceptance criteria, verification, and final handoff are complete. The UI must expose task status, room messages, sub-agent activity, model/provider/subscription selection, token spend, pause/resume/archive/delete controls, secure and local-insecure secret collection, voice/chat-controllable view actions, searchable paginated history, remote/mobile access, and route/action-specific automated plus screenshot/manual verification.
+
+## Current Status And Remaining Work
+
+This report started as a research snapshot. The current branch now has a first durable `/api/orchestrator/*` task surface, `/orchestrator` plugin view registration, task-thread client methods backed by real routes, mandatory goal wrappers for direct coding-agent spawn/send paths, usage aggregation from ACP result usage, and dispatcher-level credential bridge wiring. Treat older unsupported-feature statements below as historical context when they conflict with this section.
+
+Remaining work:
+
+- Replace caller-supplied validation with registered verification hooks that collect durable evidence before `done`.
+- Add end-to-end coverage for every declared orchestrator view capability, TUI endpoint, and task lifecycle mutation.
+- Add screenshot/manual review for the orchestrator UI and any shared cloud frontend changes before declaring UI work complete.
+- Finish provider/subscription settings cleanup and internationalize every new orchestrator string.
+- Prove remote/mobile access against a local desktop agent and against cloud-connected agents.
+
+## Executive Findings
+
+The repository already has three partial layers that should be joined rather than rebuilt from scratch:
+
+- `plugins/plugin-agent-orchestrator` owns ACP subprocess sessions, agent selection, routing, workspace lifecycle, sub-agent progress, and task actions.
+- `plugins/plugin-task-coordinator` owns a plugin view bundle at `/task-coordinator` plus task/session panels, but it is currently wired to mostly stubbed task-thread client methods.
+- `packages/ui` owns the app shell, dynamic plugin views, built-in `/tasks` page, chat sidebar widgets, task-coordinator slots, route resolution, i18n, and local smoke coverage.
+
+The main blocker is that the desired product model is "task thread with room, messages, sub-agents, goal, telemetry, and lifecycle", while the implemented backend model exposed to UI is mostly "ACP session list". Typed task-thread shapes exist in `packages/ui/src/api/client-types-cloud.ts`, and `CodingAgentTasksPanel` already expects thread APIs, but `ElizaClient` returns empty/null for task-thread list/detail/archive/reopen. The `/api/coding-agents/metrics` route returns `{}`, and no route currently exposes per-agent token usage.
+
+## Current Backend State
+
+`plugin-agent-orchestrator` registers raw HTTP routes for coding agents, workspace, and issues, but not task-thread coordinator APIs. The route table includes `/api/coding-agents`, `/api/coding-agents/spawn`, `/api/coding-agents/metrics`, per-agent send/stop/output, parent-context/memory/active-workspaces, workspace, and issue routes in `plugins/plugin-agent-orchestrator/src/setup-routes.ts:81`.
+
+The active session routes can list sessions, spawn sessions, send input, stop sessions, and read output. Relevant gaps:
+
+- `/api/coding-agents/metrics` currently returns `{}` in `plugins/plugin-agent-orchestrator/src/api/agent-routes.ts:274`.
+- `/api/coding-agents/workspace-files` returns an empty file list in `plugins/plugin-agent-orchestrator/src/api/agent-routes.ts:337`.
+- `/api/coding-agents/settings` does expose preferred framework, configured subscription provider, and framework availability in `plugins/plugin-agent-orchestrator/src/api/agent-routes.ts:391`.
+- `/api/coding-agents` lists raw ACP sessions from `ctx.acpService.listSessions()` in `plugins/plugin-agent-orchestrator/src/api/agent-routes.ts:441`.
+- `/api/coding-agents/spawn` passes `initialTask: taskText` directly in `plugins/plugin-agent-orchestrator/src/api/agent-routes.ts:553`; it does not enforce a goal wrapper on direct API spawns.
+- `/api/coding-agents/:id/send` passes user input directly to `sendToSession` in `plugins/plugin-agent-orchestrator/src/api/agent-routes.ts:610`; it does not enforce a goal wrapper on direct sends.
+- Credential bridge routes exist, but the main dispatcher does not import or call `handleBridgeRoutes`; the bridge module itself still says to hook it from `routes.ts` in `plugins/plugin-agent-orchestrator/src/api/bridge-routes.ts:230`. This blocks secure credential retrieval from the current route surface.
+
+The action path is richer. `TASKS_SPAWN_AGENT` constructs task-room/worktree-room metadata, route hints, initial task metadata, and swarming instructions. It tells agents to keep working until finished or blocked in `plugins/plugin-agent-orchestrator/src/actions/tasks.ts:375`, spawns with `initialTask: taskWithRouteHints` in `plugins/plugin-agent-orchestrator/src/actions/tasks.ts:723`, and records session metadata including task room, worktree route, label, source, and `initialTask` in `plugins/plugin-agent-orchestrator/src/actions/tasks.ts:729`. However, it intentionally returns `continueChain: false` immediately after spawn in `plugins/plugin-agent-orchestrator/src/actions/tasks.ts:762` so the parent turn ends while the sub-agent works asynchronously. That is the opposite of the requested "orchestrator does not return until goal completion" behavior unless the new task/goal runner adds a durable task status contract outside the single chat turn.
+
+`TASKS_SEND_TO_AGENT` also sends direct follow-up text unless it is reacting to a routed incomplete completion, where it builds a stronger "continue original task" follow-up in `plugins/plugin-agent-orchestrator/src/actions/tasks.ts:856`. This should become a mandatory `/goal` envelope for Claude/Codex/OpenCode/Eliza prompts, not a best-effort retry phrase.
+
+## Current UI State
+
+`plugin-task-coordinator` already declares a GUI view at `/task-coordinator`, an XR view at `/task-coordinator`, and a TUI view at `/task-coordinator/tui` in `plugins/plugin-task-coordinator/src/index.ts:6`. The GUI exports `CodingAgentTasksPanel`; the TUI exposes capabilities for listing sessions, listing task threads, opening a thread, stopping a session, and refreshing.
+
+`packages/ui` can route dynamic plugin views by matching `ViewRegistryEntry.path` and loading their `bundleUrl` through `DynamicViewLoader` in `packages/ui/src/App.tsx:451`. Built-in static views include `tasks`, which renders `TasksPageView` in `packages/ui/src/App.tsx:542`. The navigation type and path map include `tasks`, but not `orchestrator`, in `packages/ui/src/navigation/index.ts:44` and `packages/ui/src/navigation/index.ts:318`.
+
+`packages/ui/src/slots/task-coordinator-slots.tsx` deliberately keeps app-core from importing the plugin directly and instead lets plugins register task-coordinator components into slots. This is the right pattern to preserve if `/orchestrator` remains a frontend plugin view, but it also means `plugin-agent-orchestrator` cannot simply add a React file without introducing a browser build and a view-registration story.
+
+The current task panel is a useful seed, but not enough for the requested view. `CodingAgentTasksPanel` polls `client.listCodingAgentTaskThreads` every 5 seconds in `plugins/plugin-task-coordinator/src/CodingAgentTasksPanel.tsx:680`, loads selected thread details, and has archive/reopen handlers in `plugins/plugin-task-coordinator/src/CodingAgentTasksPanel.tsx:802`. The client methods behind those calls currently return empty/null/false in `packages/ui/src/api/client-agent.ts:3403`, so local task rooms and history are not truly available.
+
+Chat sidebar widgets are registered for app runs and activity under `agent-orchestrator` in `packages/ui/src/widgets/registry.ts:67`, but they are not the requested full-room orchestration surface.
+
+There is no first-class `/orchestrator` route in desktop or cloud today. Desktop has a built-in `tasks` tab and `/apps/tasks` surface, while `plugin-task-coordinator` registers `/task-coordinator`. Cloud is further behind for this specific feature: inline cloud agent chat is intentionally not wired yet, and public cloud chat is character-room text streaming rather than orchestrator/task-room state.
+
+Slash-chat support is also not built in for this product yet. Existing slash behavior is tied to saved/custom action expansion, not built-in `/orchestrator`, `/task`, `/spawn`, or `/tasks` commands. The first version should decide whether slash commands call the orchestrator API directly or translate into planner-visible task requests.
+
+## Data Model Required
+
+Add a durable orchestrator task model owned by `plugin-agent-orchestrator`:
+
+- `orchestrator_tasks`: id, title, goal, status, priority, owner, worldId, mainRoomId, taskRoomId, archive/delete flags, created/updated/closed timestamps, acceptance criteria, current plan, parent/fork source, provider policy, pause state.
+- `orchestrator_task_sessions`: taskId, sessionId, agentType, providerSource, model, goalPrompt, workdir, status, active tool, lastActivityAt, spawnedAt, stoppedAt, completionSummary, retry count, token totals.
+- `orchestrator_task_events`: taskId, sessionId, eventType, summary, data, timestamp.
+- `orchestrator_task_messages`: taskId, roomId, messageId, sender kind, content refs, searchable text, timestamp. Prefer referencing existing runtime memories where possible instead of duplicating message bodies.
+- `orchestrator_task_usage`: taskId, sessionId, provider, model, input/output/reasoning/cache tokens, cost estimate, source event id, timestamp.
+- `orchestrator_task_artifacts`: taskId, sessionId, path/URI, artifact type, title, verification status.
+- `orchestrator_task_decisions`: taskId, decision type, action selected, prompt excerpt, reasoning summary, timestamp.
+
+The existing UI thread types in `packages/ui/src/api/client-types-cloud.ts:987` are close, but they need room/message fields, token usage, provider/model usage, pause state, and task fork lineage. The existing `CodingAgentTaskThreadDetail` already includes sessions, decisions, events, artifacts, transcripts, and pending decisions in `packages/ui/src/api/client-types-cloud.ts:1104`; extend this instead of inventing an incompatible parallel shape.
+
+Usage capture needs backend work. ACP usage events are currently treated as informational and not surfaced in `plugins/plugin-agent-orchestrator/src/services/acp-service.ts:1639`, so token/cost UI cannot be accurate until those events are persisted and aggregated.
+
+## Prompt And Goal Semantics
+
+The requested behavior should be implemented as a task runner contract, not by expecting one HTTP response or one chat turn to remain open forever. The orchestrator should create a durable goal record, spawn agents with a mandatory goal wrapper, and continue dispatching, verifying, retrying, pausing, or escalating until the goal status is terminal.
+
+Required prompt policy:
+
+- Every `spawnSession` initial task for Claude, Codex, OpenCode, ElizaOS, and Pi Agent must pass through a single `buildGoalPrompt(...)` function.
+- Every `sendToSession` follow-up from direct API, UI, or planner action must pass through `buildGoalFollowUp(...)`.
+- The wrapper must include: goal, acceptance criteria, room IDs, workdir, allowed capabilities, "do not finish until complete or genuinely blocked", "verify before final", "report token/tool status when available", and "return structured completion fields".
+- Direct API spawns in `agent-routes.ts` must get the same wrapper as `TASKS_SPAWN_AGENT`; currently they bypass route hints and goal semantics.
+- Direct API sends in `agent-routes.ts` must get the same wrapper as `TASKS_SEND_TO_AGENT`; currently they pass raw input.
+- When a sub-agent claims completion, the router should transition task state to `validating`, run verification hooks, and only mark `done` after proof passes.
+- The durable task runner should keep a structured objective, blocked reason, retry/resume budget, validation state, and completion summary. Today goal persistence is prompt text plus ACP session metadata, not a true `/goal` record.
+
+The parent orchestrator should not "return done" while a task remains active. In UI terms, this means the chat can acknowledge "task created and running", but task status remains active until validation completes. In agent terms, any final answer about the task must be gated on the durable task state, not just the sub-agent's `task_complete` event.
+
+## API Surface Needed
+
+Add coordinator routes under `/api/coding-agents/coordinator/*` or alias them to `/api/orchestrator/*`:
+
+- `GET /api/orchestrator/status`: aggregate active tasks, sessions, provider usage, token spend, paused state.
+- `GET /api/orchestrator/tasks?cursor=&status=&search=&includeArchived=`
+- `POST /api/orchestrator/tasks`: create task from structured form or inferred chat action.
+- `GET /api/orchestrator/tasks/:taskId`
+- `PATCH /api/orchestrator/tasks/:taskId`: update title, goal, acceptance criteria, priority.
+- `POST /api/orchestrator/tasks/:taskId/pause`
+- `POST /api/orchestrator/tasks/:taskId/resume`
+- `POST /api/orchestrator/tasks/:taskId/archive`
+- `DELETE /api/orchestrator/tasks/:taskId`
+- `POST /api/orchestrator/tasks/:taskId/fork`
+- `POST /api/orchestrator/tasks/:taskId/messages`: user joins a task room.
+- `GET /api/orchestrator/tasks/:taskId/messages?cursor=&limit=`
+- `GET /api/orchestrator/tasks/:taskId/events?cursor=&limit=`
+- `GET /api/orchestrator/tasks/:taskId/usage`
+- `POST /api/orchestrator/tasks/:taskId/agents`: add sub-agent.
+- `POST /api/orchestrator/tasks/:taskId/agents/:sessionId/stop`
+- `POST /api/orchestrator/pause-all`
+- `POST /api/orchestrator/resume-all`
+
+Keep compatibility by mapping `client.listCodingAgentTaskThreads`, `getCodingAgentTaskThread`, `archiveCodingAgentTaskThread`, and `reopenCodingAgentTaskThread` to these real routes instead of returning stubs.
+
+Also register and dispatch credential bridge routes if they are part of provider setup or sub-agent secret retrieval. Leaving `bridge-routes.ts` present but unmounted creates a false sense of security coverage.
+
+Normalize the coding-agent preflight contract at the same time. Current frontend code paths expect an object with `installed`/`available` style fields, while the backend preflight route returns an array of preflight rows. This can make the code button and task affordances appear unreliably.
+
+## Route And View Registration Recommendation
+
+Use `/orchestrator` as the primary product route.
+
+Preferred implementation path:
+
+1. Rename or duplicate `plugin-task-coordinator` view registration so GUI path `/orchestrator` loads the new orchestrator component, with `/task-coordinator` retained as a compatibility alias.
+2. Keep `plugin-agent-orchestrator` as the backend owner and add all durable task/coordinator routes there.
+3. Keep `packages/ui` slots for shared app-shell embedding, but move the full orchestrator product UI into the plugin view bundle to avoid hardcoding a large new static page in `packages/ui`.
+4. Add `orchestrator` to the UI navigation type/path map only if it needs a first-class built-in tab. If it is a plugin view with `desktopTabEnabled`, dynamic view routing can load it by path without adding a built-in tab.
+
+This preserves the existing package boundary: Node orchestration backend in `plugin-agent-orchestrator`, React view bundle in a browser-capable plugin package, and generic shell/view infrastructure in `packages/ui`.
+
+Do not start with cloud `/orchestrator` as the primary implementation path. Build the desktop/local route and backend task contract first, then bridge the same API shape into cloud once cloud-side agent chat/task containers expose durable task-room state.
+
+## UX Requirements
+
+The `/orchestrator` screen should be an operational workbench:
+
+- Left rail: ongoing tasks with status, priority, latest activity, active sub-agent count, token spend, provider icons, pause/archive affordances, search, filters, archived toggle, and plus button.
+- Center: selected room timeline with user, orchestrator, and sub-agent messages; system events collapsed by default; paginated search and jump-to-time.
+- Right rail or inspector: sub-agent roster, current tool/activity, workdir/repo, active branch, artifacts, verification checklist, acceptance criteria, token/cost breakdown, provider/subscription state.
+- Composer: sends to selected room, can also create/fork/update tasks via chat intent.
+- Task creation: plus button opens a compact structured form, but any field can be inferred from chat.
+- Controls: pause task, pause all agents, resume, archive, delete, fork, add agent, stop agent, change provider/model, copy/share task link.
+- Voice/chat actions: every clickable action must have a view capability and natural-language route so "pause this task", "fork it", "show Codex only", or "add Claude to this room" works while the view is open.
+- Settings: provider/subscription management must show Eliza Cloud, local Eliza, Claude, Codex/OpenAI, OpenCode, and any configured cloud routes; copy must be fully internationalized and avoid leaking tokens.
+
+Avoid a marketing layout. This is an operator console: dense, stable, quiet, readable, and optimized for scanning.
+
+## Secret And OAuth Flow
+
+The codebase already has sensitive request infrastructure for secure inline owner-app secret requests and local route submission. `owner-app-inline-adapter` builds owner-only secret forms, and `sensitive-request-routes.ts` supports create/get/submit/cancel flows. Extend this for orchestrator provider setup:
+
+- Secure cloud path: OAuth and API secrets stored in Eliza Cloud or scoped cloud vault, never pasted into public chat.
+- Secure local path: local vault/secret manager when available.
+- Insecure local fallback: explicit "stored locally/insecure" mode for fully local use where cloud is unavailable.
+- Form inference: chat can start an OAuth/secret request, the form opens prefilled with inferred provider/scope, and user can submit in UI.
+- Audit: every secret request emits redacted audit events.
+- Tests: verify redaction, route auth, submission, cancellation, cloud unavailable fallback, and no accidental secret echo in messages/events/transcripts.
+
+## Remote And Mobile Access
+
+The requested "phone as remote to desktop agent" mode needs explicit scope:
+
+- Local desktop runtime exposes a remote pairing/tunnel endpoint with auth and revocation.
+- Mobile connects as a remote client to the desktop agent, not as a separate agent owner.
+- Cloud mode connects all clients to the cloud-hosted state.
+- The orchestrator task state must sync through the same API shape in both local-remote and cloud modes.
+- Long-running task updates should use websocket/SSE where available, with polling fallback matching current 5-second polling.
+
+## Test And Verification Plan
+
+Backend unit coverage:
+
+- Route registration includes every new `/api/orchestrator/*` and coordinator compatibility route.
+- Direct HTTP handler tests for `/api/coding-agents` list/spawn/get/send/stop/output, including missing service, invalid body, spawn workdir rejection, concurrency limit, and output fallback.
+- Task create/list/detail/search/pagination/archive/delete/fork/pause/resume.
+- Session spawn and send always call goal-wrapper builders.
+- Direct API spawn/send and planner action spawn/send produce equivalent goal envelopes.
+- Sub-agent completion does not mark done until validation passes.
+- Token usage aggregation handles missing provider usage, partial usage, duplicate events, and multiple providers.
+- Credential bridge routes are mounted, authorized, redacted, and unavailable in modes that should not expose them.
+- Store fallback works for SQL, file, and memory session stores.
+- Access policy rejects unauthorized remote/mobile clients.
+
+UI component coverage:
+
+- Empty state, loading state, error state, active task, blocked task, validating task, done task, archived task.
+- Search, pagination, task selection, task creation form, plus button, fork, pause, pause all, resume, archive, delete confirmation, add sub-agent, stop sub-agent.
+- Token/cost visualizations with zero/unknown/large values.
+- Provider settings and i18n keys for all visible strings.
+- Voice/chat capability calls for every action.
+- Preflight response normalization so provider/setup affordances render consistently.
+- `mapAcpSessionsToCodingAgentSessions`, `getCodingAgentStatus`, `stopCodingAgent`, scratch workspace actions, and PTY subscribe/send/resize/buffer client helpers.
+
+End-to-end coverage:
+
+- Create task by plus button.
+- Create task by chat message.
+- Fork task from chat.
+- Add Claude/Codex/OpenCode/Eliza sub-agent where available, with mocked providers in CI.
+- Pause one task stops/suspends all attached agents.
+- Pause all affects all running tasks.
+- Archive/delete removes from active list and preserves/cleans history according to mode.
+- Search and paginate main orchestrator room history and task room history.
+- Secret request: secure cloud, secure local, insecure local fallback.
+- Remote phone connects to desktop agent and controls an active task.
+- Cloud client and desktop client see the same task state.
+- Slash commands `/task`, `/tasks`, `/spawn`, and `/stop` route to the intended task APIs or planner requests with destructive-action confirmation.
+- Validation failure triggers retry/reopen, not `done`.
+- Token spend updates per sub-agent and aggregate.
+- Terminal/output management: buffered output loads, live `pty-output` appends, interrupt sends Ctrl-C, terminal input sends a line, and stop posts to the session stop endpoint.
+- Failure handling: `/api/coding-agents` 503, thread list failure, detail failure, output fetch failure, and stop failure all render actionable UI without swallowing the error silently.
+
+Existing coverage to extend:
+
+- `plugins/plugin-agent-orchestrator/__tests__/unit/register-routes.test.ts` verifies route loader registration.
+- `plugins/plugin-agent-orchestrator/__tests__/unit/sub-agent-router.test.ts` verifies task-complete synthetic memory routing.
+- `packages/app/test/ui-smoke/plugin-views-visual.spec.ts:76` already includes `/task-coordinator`.
+- `packages/app/test/ui-smoke/all-pages-clicksafe.spec.ts:477` stubs coding-agent preflight/status routes.
+- `packages/cloud-frontend/AGENTS.md` requires `bun run --cwd packages/cloud-frontend audit:cloud` plus manual review for any `packages/cloud-frontend` UI change.
+
+Manual visual review:
+
+- For `packages/ui` / plugin view changes, run local app UI smoke and plugin-view visual specs, capture desktop and mobile screenshots of `/orchestrator`, `/orchestrator?archived=1`, task detail, settings/provider setup, and secret request forms.
+- Until an app-wide manual-review protocol exists, require screenshots for `/task-coordinator`, `/task-coordinator/tui`, chat with active sub-agent chip, and terminal drawer/side-panel as compatibility surfaces.
+- If any `packages/cloud-frontend` files are touched, follow the mandatory cloud visual audit loop exactly and leave no affected route at `needs-work` or `broken`.
+- For meaningful redesign, iterate screenshots at least five times, tracking issues fixed per loop.
+
+## Highest Risks
+
+- Treating ACP sessions as tasks will lose room history, fork lineage, and durable status. A real task store is required.
+- Letting direct API routes bypass goal-wrapper semantics will create inconsistent worker behavior.
+- Marking completion from `task_complete` alone will violate the "certain complete" requirement.
+- Token accounting may not be available uniformly across Claude/Codex/OpenCode/Eliza; the UI must distinguish measured, estimated, and unavailable usage.
+- Existing archive, reopen, and pause action paths report unsupported ACP-only mode, so current UI archive/reopen affordances cannot work until task-thread lifecycle exists.
+- Putting the full UI in `plugin-agent-orchestrator` without a browser build will break current package boundaries.
+- Building cloud UI before cloud task-room APIs exist will produce a decorative shell, not a working orchestrator.
+- Preflight response mismatch can hide or misstate provider availability.
+- Existing Playwright coverage proves plugin-view renderability, not the management workflows; without dedicated mocked workflow specs, regressions in stop, archive, thread detail, terminal output, and error states will slip through.
+- "100% e2e coverage" is aspirational unless scoped to reachable user flows and backed by mocked provider harnesses; live Claude/Codex tests must stay gated.
+- Secrets can leak through transcripts, task messages, or debug logs unless every sensitive request path redacts by default.
+
+## Recommended Build Sequence
+
+1. Backend task store and routes: create task/thread persistence, expose coordinator APIs, wire compatibility client methods.
+2. Goal wrapper: centralize spawn/send prompt wrapping and enforce it on both action and HTTP routes.
+3. Usage telemetry: capture token/cost events where providers expose them and surface estimated/unavailable states otherwise.
+4. View registration: ship `/orchestrator` plugin view, keep `/task-coordinator` alias.
+5. UI workbench: task rail, room timeline, sub-agent inspector, controls, create/fork flows, i18n.
+6. Chat/voice capabilities: add view actions for every UI control and natural-language task commands.
+7. Secret/OAuth forms: integrate sensitive-request flows into provider setup and task execution blockers.
+8. Remote/mobile: unify cloud/local-remote state APIs and websocket/polling updates.
+9. Tests and visual audits: build the e2e matrix, mocked providers, live gated smokes, screenshot review artifacts, and regression docs.
+
+## Acceptance Criteria
+
+- `/orchestrator` opens as a first-class view and `/task-coordinator` remains compatible or redirects.
+- A user can create, fork, pause, resume, archive, delete, search, and inspect tasks by UI and chat/voice.
+- Each task has a durable room, message history, event history, sub-agent roster, status, goal, acceptance criteria, artifacts, and usage.
+- Claude/Codex/OpenCode/Eliza workers always receive goal-wrapped prompts and follow-ups.
+- The orchestrator never reports a task as `done` until validation passes or a human explicitly overrides.
+- Provider defaults follow configured subscription readiness: user-owned Claude/OpenAI where available, otherwise Eliza Cloud/local policy.
+- Secure and local-insecure secret setup paths are clear, tested, and redacted.
+- Desktop, mobile remote, and cloud clients observe consistent task state.
+- Every visible string is internationalized.
+- Every button/flow/input/view has automated coverage or a documented impossible-to-automate reason plus manual screenshot review.