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

🔍 Filter templates...

All Ephemeral Persistent Has-queue

▼ aws-account-lead eph · 2 topics

▣ provision q:3 c:1

▣ teardown q:0 c:1

▼ test-echo eph · 1 topic

▣ echo q:0 c:1

▶ gitea-lead persistent

▶ orchestrator-watch persistent

topic:aws-account-lead/provision

queue: 3

Stats (last 24h)

spawned

completed

failed

running

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.