# agentic-collab 3.0 — Q9 dashboard wireframes

Templates & topics tree · approval inbox · live updates via Q4 WS events
Spec: `docs/v3-vision.md` §"UI deltas" · markdown source: `docs/v3-wireframes.md` · scope: human follow-up (deferred from the one-shot run)

## 1 · Sidebar view toggle

The toggle sits above today's `Filter agents…` search box. Three segments; the sidebar contents swap. Existing Agents view is unchanged.

View toggle

Badge counts come from:

- Agents — existing unread count.
- Templates — sum of `topic_queue` depths across all templates. Source: aggregated `topic_queue_changed` WS events.
- Approvals — count where `state = 'pending'`. Source: `approval_changed` WS events + initial `GET /api/approvals?state=pending`.

## 2 · Templates & Topics — sidebar tree

topic:aws-account-lead/provision
queue: 3
Stats (last 24h)
spawned
17
completed
12
failed
2
running
3
median runtime: 4m12s · p95 runtime: 11m02s
Live queue (3 items)

id | payload | reply_to
--- | --- | ---
#q-4019 | {"region":"us-east-1"...} | gitea-lead
#q-4021 | {"region":"eu-west-2"...} | gitea-lead
#q-4023 | {"region":"ap-south-1"...} | dashboard

Recent instances

instance | state | started | completed | exit
--- | --- | --- | --- | ---
a7c2b1…3f | running | 2m ago | — | —
b8d3c2…ee | completed | 14m ago | 9m ago | ok
c9e4d3…77 | failed | 1h ago | 42m ago | error

Config

    concurrency: 1      monitor_template: aws-account-monitor
    schema:       ./schemas/provision.json
    reply_schema: ./schemas/provision-reply.json
    cwd_base:     /var/agentic/work/aws-account-lead
    start:        bash $WORKTREE_PATH/start.sh

Actions are NEW endpoints — ship the read-only view first, layer mutations second.

## 3 · Templates & Topics — instance detail

agent:aws-account-lead/a7c2b1…3f
running

    template: aws-account-lead     spawned: 2m ago     proxy: mac-mini
    reply_to: gitea-lead           queue_id: 4019      message_id: m-7d3a

tmux pane

    $ cd /var/agentic/work/aws-account-lead/wt-m-7d3a
    $ aws sts get-caller-identity
    {
      "UserId": "...",
      "Account": "123456789012",
      "Arn": "arn:aws:iam::..."
    }
    $ ▮

IPC files

    MESSAGE_PATH:  /run/agentic-collab/ipc/a7c2b1…3f/message.json
    REPLY_PATH:    /run/agentic-collab/ipc/a7c2b1…3f/reply.json   (empty)
    STATUS_PATH:   /run/agentic-collab/ipc/a7c2b1…3f/status.txt  (empty)

Env contract

    WORKTREE_PATH:   /var/agentic/work/aws-account-lead/wt-m-7d3a
    CWD_BASE:        /var/agentic/work/aws-account-lead
    REPO_ROOT:       /var/agentic/work/aws-account-lead
    AGENT_TEMPLATE:  aws-account-lead
    TOPIC_NAME:      provision
    INSTANCE_ADDR:   agent:aws-account-lead/a7c2b1…3f
    REPLY_TO_ADDR:   gitea-lead

"Send message" targets the instance address — mid-run paste, per Q3 invariant #10.

## 4 · Approval Inbox

approval:aws-account-provision/a3f1…8b
pending

    Requester: agent:gitea-lead
    Created:   2026-05-19T14:23:11Z (2m ago)
    Updated:   2026-05-19T14:23:11Z

Payload

    {
      "region": "us-east-1",
      "purpose": "staging environment for q3-features",
      "budget_usd_per_month": 250,
      "tags": { "team": "platform", "cost_center": "eng-infra" }
    }

Timeline

at | event | by
--- | --- | ---
14:23:11 | created | gitea-lead
— (no further events yet)

Decided-by: sammons (current user). Withdraw enabled only for the original requester while pending.
Once decided, requester receives an auto-notify message via the existing dispatcher: `"Approval <id> updated: <state>. Run 'collab approval get <id>' for details."`

## 5 · Approval — Amend modal

Amend approval a3f1…8b
[ ✕ ]

State transitions to `amended`; new payload version recorded. Q5's server rejects amend without a payload — the textarea below is required.

Original payload (read-only)

    { "region": "us-east-1", "budget_usd_per_month": 250, ... }

Amended payload (JSON, validated client-side)

    { "region": "us-east-1", "budget_usd_per_month": 100,  ← human edits inline
      ... }

Optional comment for the requester
budget reduced to $100/mo for staging-only — see #DEPLOY-4123 for context

## 6 · Real-time wiring

    // state.ts subscriptions added by Q9. WebSocket already in place from Q4.
    on('template_updated',    (ev) => templateStore.applyUpdate(ev));
    on('topic_queue_changed', (ev) => topicQueueStore.applyDepth(ev));
    on('instance_spawned',    (ev) => instanceStore.add(ev.instance));
    on('instance_completed',  (ev) => instanceStore.update(ev.instance));
    on('instance_failed',     (ev) => instanceStore.update(ev.instance));
    on('approval_changed',    (ev) => approvalStore.refetch(ev.approvalId));

## 7 · API additions needed (additive only)

Method | Path | Purpose
--- | --- | ---
GET | /api/templates | Sidebar tree — all `agent_templates` + joined `topics`
GET | /api/topics/:template/:name/queue | Live queue rows for the topic-detail view
GET | /api/topics/:template/:name/stats | Aggregate counts + percentiles
GET | /api/agent-instances | Filtered list for the "Recent instances" pane
GET | /api/agent-instances/:id | Single-instance detail — env contract, IPC paths
POST | /api/agent-instances/:id/fail | "Fail (force)" button
POST | /api/topics/:template/:name/pause | Pause-queue
POST | /api/topics/:template/:name/drain | Drain-queue (refuse new, finish in-flight)

`/api/approvals*` are already in place (Q5).

## 8 · Integration with existing dashboard

    ┌──────────────────┬──────────────────────────────────────────────────────┐
    │ SIDEBAR          │ MAIN PANE                                             │
    │ (existing class: │ (existing class: thread-panel — swap-in)              │
    │  agent-list)     │                                                       │
    │                  │   default: thread-messages                            │
    │  swap-in:        │                                                       │
    │   - agents       │   swap-in:                                            │
    │   - templates    │     - thread-messages    (existing)                  │
    │   - approvals    │     - topic-detail       ← new (Q9)                  │
    │                  │     - instance-detail    ← new (Q9)                  │
    │                  │     - approval-detail    ← new (Q9)                  │
    │                  │     - persona / reminder / watch / files / settings   │
    └──────────────────┴──────────────────────────────────────────────────────┘

Three new web-components (~300 LOC each in vanilla TS, following `agent-list.ts` / `thread.ts` / `persona-editor.ts`). The view-toggle is one small additive component above the existing `agent-search` block.