hyperhive/docs/web-ui.md

# Web UI

Two web surfaces share the same skeleton: the dashboard (port 7000)
and the per-agent UIs (manager on :8000, sub-agents on a hashed
:8100-8999). Both are SPAs — `GET /` returns a static shell,
`/api/state` returns JSON, JS renders. No full-page reloads.

## Shape (shared by both)

- `GET /` → `assets/index.html` (placeholders for state-driven
  sections, shipped via `include_str!` so the binary has no runtime
  file dependency).
- `GET /static/*.css` + `GET /static/*.js` → static assets. Both
  pages prepend `hive_fr0nt::BASE_CSS` + `TERMINAL_CSS` to their
  per-page stylesheet, and `GET /static/hive-fr0nt.js` serves the
  shared `window.HiveTerminal.create` runtime. The dashboard's
  `#msgflow` and the per-agent `#live` log are both backed by
  this terminal — sticky-bottom auto-scroll, "↓ N new" pill,
  history backfill, SSE plumbing all live there. Each page
  registers a kind→renderer map; unknown kinds fall through to
  a JSON-dump note row.
- `GET /api/state` → JSON snapshot the JS app renders into the
  DOM. Includes a top-level `seq` (the dashboard event channel's
  high-water mark at the moment the snapshot was assembled);
  clients use it to dedupe their buffered SSE traffic against
  the snapshot (drop frames with `seq <= snapshot.seq`).
- `GET /dashboard/stream` (dashboard) / `GET /events/stream`
  (per-agent) → `text/event-stream` SSE for live updates. The
  dashboard stream carries broker `Sent` / `Delivered` (mirrored
  by a forwarder task from the broker's intra-process channel)
  plus mutation events (`approval_added` / `approval_resolved`,
  `question_added` / `question_resolved`, `transient_set` /
  `transient_cleared`). Each frame carries a `seq`. The
  matching backfill endpoint is `GET /dashboard/history` (last
  ~200 broker messages wrapped in `{ seq, events }`) on the
  dashboard and `GET /events/history` (last 2000 `LiveEvent`s
  also wrapped in `{ seq, events }`) on the agent.

The JS app handles all `form[data-async]` submissions via a delegated
listener: read `data-confirm`, swap the button to a spinner, POST
`application/x-www-form-urlencoded`, re-enable the button on success
(refreshState may keep the form mounted, so we don't rely on a
re-render), call `refreshState()`. State shapes live in
`dashboard.rs::StateSnapshot` and `web_ui.rs::StateSnapshot` — when
adding state fields, plumb through the snapshot struct and the
relevant `assets/app.js` render function.

**Focus preservation:** `refreshState` checks whether
`document.activeElement` sits inside one of the managed sections
and, if so, skips the refresh (defers 2s). The operator never has
the form yanked out from under them mid-type; the update lands as
soon as they blur.

**`<details>` open-state preservation:** any collapsible element
tagged with `data-restore-key="<stable-key>"` survives the
refresh. `snapshotOpenDetails()` walks managed sections before
render, `restoreOpenDetails()` re-applies after. Used today for
the journald viewer (`journal:<container>`), the agent-config
viewer (`agent-config:<name>`), and approval diff blocks
(`approval-diff:<id>`). Setting `.open = true` programmatically
also fires the `toggle` event, so any lazy-fetch wired to it
re-runs cleanly on restore.

Both bind their listeners with `SO_REUSEADDR` via
`tokio::net::TcpSocket` plus a retry loop on `AddrInUse` (12 tries,
exponential backoff capped at 2s) so an nspawn restart that races
the previous process's socket release resolves itself.

## Dashboard sections (top to bottom)

1. **Notification row** — `🔔 enable notifications` button when
   permission ungranted; `🔕 mute / 🔔 unmute` toggle once granted;
   inline "unsupported / blocked" message when applicable. Sits
   under the banner.
2. **C0NTAINERS** — live containers with their action surface.
   Pulsing red banner at the top of this section if any two
   sub-agents hash to the same port (`port_conflicts` from
   `/api/state`): the operator must rename one of them and
   rebuild. `lifecycle::{spawn,rebuild}` also preflight this and
   refuse with a clear error message naming the conflicting agent.
3. **K3PT ST4T3** — destroyed-but-state-kept tombstones (size +
   age + claude-creds badge). Two actions: `⊕ R3V1V3` (queues a
   Spawn approval; existing state is reused), `PURG3` (wipes
   state + applied dirs; `POST /purge-tombstone/{name}`).
4. **M1ND H4S QU3STI0NS** — pending operator-targeted `ask`
   questions, i.e. rows with `target IS NULL` (peer-to-peer
   questions live in the same table but never surface here)
   (amber pulsing border). Free-text fallback always rendered
   alongside any option list; `multi=true` renders options as
   checkboxes; submit merges selections + free text comma-joined.
   Each row has a `✗ CANC3L` button that resolves the question
   with `[cancelled]`. Questions with a `ttl_seconds` show a
   `⏳ MM:SS` chip; the host-side watchdog auto-cancels with
   `[expired]` when the deadline fires.
5. **0PER4T0R 1NB0X** — recent messages addressed to `operator`,
   derived client-side from the dashboard event stream (no longer
   a snapshot field). Cold load seeds from
   `/dashboard/history`'s 200-message backfill; subsequent
   `sent` events with `to == "operator"` are appended live. Cap
   50, newest-first.
6. **P3NDING APPR0VALS** — the queue. The R3QU3ST SP4WN form
   lives at the top of this section since submitting it
   immediately queues an approval that lands directly below.
7. **MESS4GE FL0W** — live broker tail wrapped in a
   `.terminal-wrap` (same chrome as the per-agent terminal).
   Cold load backfills the last ~200 messages from
   `/dashboard/history`; live frames arrive on
   `/dashboard/stream` and dispatch through
   `HiveTerminal.create`. Each row is one broker event —
   `sent` or `delivered` — with `from → to: body`; per-agent
   thinking / tool calls / claude chatter stay out of this
   view, only what passes through hive-c0re's broker. Sticky-
   bottom auto-scroll + "↓ N new" pill match the per-agent
   page. Below the stream sits a terminal-style compose box:
   `@name` picks the recipient (sticky across sends via
   localStorage; auto-complete from the live container list,
   Tab/Enter to confirm; `@*` broadcasts to every registered
   agent), starting a message with `@<name> body` retargets
   in one stroke, plain text sends to the sticky recipient.
   `POST /op-send` drops `{from:"operator", to, body}` into
   the broker and returns 200; the resulting SSE frame
   re-renders both the terminal row and the inbox section
   (no `/api/state` refetch). Manager is addressed as
   `@manager` (the broker recipient string), not `@hm1nd`
   (the container name); the auto-complete swaps automatically.

### Container row

Two-line layout (`assets/app.js::renderContainers`):

- Line 1: agent name (link → new tab), m1nd/ag3nt chip, `needs
  login` / `needs update` warning badges, in-flight `◐
  pending-state…` pill (replaces buttons during start / stop /
  restart / rebuild / destroy), container name + port.
- Line 2: action buttons — `↻ R3BU1LD` always, `DESTR0Y` + `PURG3`
  on sub-agents, `↺ R3ST4RT` + (sub-agents) `■ ST0P` when running,
  `▶ ST4RT` when stopped. Buttons dim + disable while a transient
  lifecycle action is in flight.
- Plus two collapsible `<details>` blocks:
  - `↳ logs · <container>` — lazy-fetches journald output via
    `GET /api/journal/{name}?unit=...&lines=...` (`journalctl -M
    <container> -b --no-pager --output=short-iso`). A unit
    dropdown switches between the harness service (default) and
    the full machine journal; refresh button re-fetches.
  - `↳ agent.nix · <name>` — lazy-fetches the applied config
    file via `GET /api/agent-config/{name}` (read-only mirror of
    `/var/lib/hyperhive/applied/<name>/agent.nix`). Mutating
    this still requires `request_apply_commit` + approval.

`↻ UPD4TE 4LL` button appears above the containers list when any
agent is stale. Banner pulses on each broker SSE event
(`pulseBanner` with a 4s grace timer).

### Browser notifications

Pure frontend (`Notification` API). Three signals trigger them:

- new pending approval (per id, delta on `/api/state`)
- new pending operator question (per id)
- new broker message sent `to: "operator"` (live via SSE)

First `/api/state` after page load seeds "seen" sets without
firing — only items that arrive while the page is open count.
Per-event tags (`hyperhive:approval:<id>`, `hyperhive:question:<id>`,
`hyperhive:msg:<at>:<rand>`) so distinct events stack in the OS
notification center instead of overwriting each other.
`console.debug` logs at every block point (unsupported,
permission ungranted, muted) for in-browser debugging. Click
focuses the dashboard tab. localStorage-backed mute toggle
silences without revoking the OS permission. Requires a secure
context (HTTPS or localhost); on other origins the controls hide
themselves. Browsers typically suppress notifications while the
originating tab is focused — that's a browser-level decision,
not ours.

### Dashboard endpoints

- `POST /approve/{id}` — approve a pending approval. Fires
  `ApprovalResolved` on the dashboard event channel; client
  updates derived approvals state from the event.
- `POST /deny/{id}` (`note=<reason>`, optional) — deny a pending
  approval with an optional operator-supplied reason. The reason
  travels to the manager as `HelperEvent::ApprovalResolved.note`
  and also rides on the dashboard's `ApprovalResolved` event.
  Dashboard prompts via `window.prompt()` on click.
- `POST /{rebuild,kill,restart,start,destroy}/{name}` — lifecycle.
  `destroy` accepts `purge=on` to also wipe state dirs.
- `POST /purge-tombstone/{name}` — wipe a tombstone's state dirs.
- `POST /answer-question/{id}` — answer a pending operator question.
- `POST /cancel-question/{id}` — cancel a pending question with
  the sentinel `[cancelled]`. Same code path as a real answer.
- `POST /request-spawn` — queue a Spawn approval.
- `POST /update-all` — rebuild every stale container.
- `POST /op-send` (`to=<name>`, `body=<text>`) — drop an
  operator-authored message into `<name>`'s inbox. `to=*` fans
  out to every registered agent. Returns 200; the broker
  `Sent` event re-renders both the message-flow terminal and
  the operator inbox without a snapshot refetch. Used by the
  compose textbox under MESS4GE FL0W.
- `GET /api/journal/{name}?unit=&lines=` — journalctl viewer for
  a managed container.
- `GET /api/agent-config/{name}` — read-only view of the applied
  `agent.nix`.
- `GET /api/state-file?path=<host-or-container-path>` — bounded
  text read of a file under the per-agent `state/` subtree or
  the shared `/var/lib/hyperhive/shared/`. Accepts the
  container-view forms (`/agents/<n>/state/...`, `/shared/...`)
  and the host form. Canonicalises + verifies the path stays
  inside the allow-list, refuses anything but a regular file,
  refuses `/agents/<n>/claude` / `config` subtrees, truncates
  bodies at 1 MiB. Click-time backing for the inline path-link
  preview.

  Detection of which tokens *are* path links is done
  **server-side at broker-message ingest**, not client-side:
  the broker forwarder calls `scan_validated_paths(body)` —
  same allow-list helper the read endpoint uses — and attaches
  the verified file tokens to the event as `file_refs: Vec<String>`.
  The client trusts that list and linkifies only those tokens,
  so directories, missing files, and forbidden subtrees never
  become anchors. No probe endpoint, no client-side regex
  heuristics. Historical messages get the same treatment on
  `/dashboard/history` backfill.
- `GET /api/reminders` — list pending reminders for the
  dashboard's queued-reminders panel.
- `POST /cancel-reminder/{id}` — hard-delete a pending reminder.
- `GET /dashboard/stream` — unified live event channel:
  broker `sent` / `delivered`, plus the mutation events listed
  below. Each frame carries `seq`.
- `GET /dashboard/history` — last ~200 broker messages
  (wrapped as `{ seq, events }`) for the message-flow
  terminal's backfill on page load.

### Dashboard event channel

Wire vocabulary on `/dashboard/stream` (kind tag is in the JSON
payload):

- `sent` / `delivered` — broker traffic, mirrored from the
  intra-process channel by a forwarder task. Used by the
  message-flow terminal renderer and the operator-inbox
  derived state.
- `approval_added` (id, agent, approval_kind, sha_short, diff,
  description) / `approval_resolved` (id, agent, approval_kind,
  sha_short, status, resolved_at, note, description) — pending
  queue + history mutations. Client mutates a derived store and
  re-renders only the approvals section.
- `question_added` (id, asker, question, options, multi,
  asked_at, deadline_at, target) / `question_resolved` (id,
  answer, answerer, answered_at, cancelled, target) — both
  operator-targeted and peer (agent-to-agent) threads fire
  these. The dashboard's questions pane surfaces both, with
  filter chips (all / @operator / @peer / per-participant) and
  an `0V3RR1D3` button on peer rows so the operator can
  answer when an agent is stuck. The ttl watchdog fires
  `question_resolved` with `answerer = "ttl-watchdog"` on
  expiry.
- `transient_set` (name, transient_kind, since_unix) /
  `transient_cleared` (name) — lifecycle action spinners. The
  client ticks the elapsed-seconds badge off `since_unix`
  client-side, no polling.
- `container_state_changed` (container: ContainerView) /
  `container_removed` (name) — per-row container mutations,
  emitted by `Coordinator::rescan_containers_and_emit` from
  every mutation site (`actions::approve` post-spawn,
  `actions::destroy`, the lifecycle_action wrapper,
  `auto_update::rebuild_agent`) and from the 10s
  `crash_watch` poll. Client upserts/removes by name; the
  pending overlay is read from `transientsState` since the
  payload doesn't carry it.

`/api/state` is **only fetched on cold-load and on the few
forms that mutate non-event-derived state** (PURG3 +
meta-update, since tombstones + meta_inputs aren't event-
shaped yet). Every other section — approvals, questions,
transients, containers, operator inbox, message flow —
derives from `/dashboard/stream` after the initial snapshot,
maintaining its own client-side store and applying events on
top. The 5s periodic poll is gone.

Generalised form helpers: `form[data-confirm="…"]` pops
`confirm()` before submit; `form[data-prompt="…"]` pops
`prompt()` and stashes the answer in a hidden input named by
`data-prompt-field` (default `note`).

## Per-agent page

Layout, top to bottom:

- Banner (gradient shimmer while state=thinking).
- Title with `↑ DASHB04RD` back-link (new tab) + `↻ R3BU1LD`.
- Status section: empty when online (alive-badge in the state
  row carries the signal), populated with the login form /
  OAuth URL when `status` is `needs_login_*`.
- **State row**: alive badge + state badge + model chip + ctx
  badge + last-turn timing + cancel-turn button + new-session
  button. Every chip carries a `title=...` tooltip with the
  detailed breakdown.
  - Alive badge: `● alive` (green) / `◌ needs login` (amber) /
    `◌ logging in` / `○ offline` / `… connecting`. Driven by
    `LiveEvent::StatusChanged`; replaces the old "harness alive
    — turn loop running" paragraph so the state row carries
    every reachability signal.
  - State badge: `💤 idle` / `🧠 thinking` / `📦 compacting` /
    `○ offline` / `… booting`, with an age suffix (`12s`,
    `2m 14s`). Driven by `LiveEvent::TurnStateChanged`
    (`{state, since_unix}`) — the bus emits on every
    `Bus::set_state` so the badge updates without a /api/state
    refetch. Cold-load via `/api/state.turn_state` +
    `turn_state_since`.
  - Model chip: `model · <name>` (e.g. `model · haiku`). Driven
    by `LiveEvent::ModelChanged`; emitted from `Bus::set_model`.
  - Ctx badge: `ctx · 142k` — last inference's prompt size
    (input + cache_read + cache_write of the most recent
    model call in the just-ended turn). This is the **actual
    context window utilisation** — the number to watch when
    deciding whether to compact.
  - Cost badge: `cost · 1.3M` — cumulative tokens billed
    across **every inference** in the last turn (sum of all
    per-call prompts). Tool-heavy turns rebill the cached
    prefix per call, so this routinely exceeds the model's
    window — it's a cost signal, not a size signal.
  - Both badges driven by `LiveEvent::TokenUsageChanged {
    ctx, cost }`, emitted once at turn-end from
    `Bus::record_turn_usage`. The harness tracks per-inference
    usage by walking `assistant` events in the stream-json
    and updating `last_inference` on each one; the `result`
    event supplies `cost` and triggers the emit.
  - Last-turn chip: `last turn 12.3s` appears after the first
    turn ends, computed from the state-since deltas.
  - `■ cancel turn` button: visible only while state=thinking,
    POSTs `/api/cancel`.
  - `↻ new session` button: always visible, amber. Confirms
    via `window.confirm()` then POSTs `/api/new-session` to
    arm a one-shot Bus flag — the next turn drops
    `--continue`, starting a fresh claude session. Subsequent
    turns resume normal `--continue`.

  Polling: `/api/state` is fetched **once** on cold load, and
  again while `status === 'needs_login_in_progress'` (login
  session output isn't event-shaped yet). Every other badge
  updates from SSE; no periodic refresh timer runs.
- Inbox `<details>` block (collapsed): `inbox · N` — last 30
  messages addressed to this agent, fetched via
  `AgentRequest::Recent { limit: 30 }`. (Separate from
  `AgentRequest::Recv { wait_seconds }` which the harness uses
  internally to long-poll the broker.)
- Terminal-wrap: live event tail (sticky-bottom auto-scroll +
  `↓ N new` pill when not at bottom) followed by an
  operator-input textarea acting as a prompt.

### Live view

Each agent runs an `events::Bus`: a `tokio::sync::broadcast<LiveEvent>`
plus a sqlite-backed history at `/state/hyperhive-events.sqlite`.
The harness emits `TurnStart { from, body, unread }`,
`Stream(value)` (one per parsed stream-json line), `Note`,
`TurnEnd { ok, note }`. The web UI:

- fetches `GET /events/history` on page load and replays the last
  2000 events (oldest first, with `.no-anim` so they don't
  stagger);
- then subscribes to `GET /events/stream` (SSE) for live tail;
- shows a granular state badge above the terminal, driven
  authoritatively from `/api/state.turn_state`. SSE turn_start /
  turn_end still flip the badge instantly between renders;
- sticky-bottom auto-scroll: scrolling up parks the view; new rows
  surface a "↓ N new" pill instead of yanking;
- terminal-themed: phosphor mauve glow, Crust bg,
  backdrop-filter blur, row fade-in slide-up.

Per-stream rendering:

- `Stream` `tool_use` →
  - `Write` / `Edit`: collapsed `<details>` with a +/- diff body
    (`-` lines from `input.old_string`, `+` lines from
    `input.new_string` or every line of `input.content`).
    Summary carries the path + line counts.
  - others (`Read /path`, `Bash $ cmd`, `mcp__hyperhive__send →
    operator: "..."`, etc.): flat one-line per-tool format.
- `Stream` `tool_result` short → flat `← ...`; long → collapsed
  `<details>` `▸ ← Nl · headline` (click to expand full body).
- `Stream` `thinking` → text content if claude provided one,
  otherwise the bare `· thinking …` indicator.
- `Stream` `system init`, `result`, `rate_limit_event` are
  dropped — too noisy.
- `Note` → `· text`.
- `TurnEnd` → `✓ turn ok` / `✗ turn fail — note`, triggers a
  `refreshState()`.

### Terminal-embedded prompt

The operator input lives *inside* the terminal-wrap as a
prompt-style textarea below the live tail: multi-line (Enter
sends, Shift+Enter newlines), tab-completes slash commands.

Slash commands today:

- `/help` — list commands locally.
- `/clear` — wipe the local terminal view (server history kept).
- `/cancel` — `POST /api/cancel` → host shellouts `pkill -INT
  claude`, emits a Note. Also surfaces as a `■ cancel turn`
  button in the state row while state=thinking.
- `/compact` — `POST /api/compact` → host spawns
  `turn::compact_session` in the background; output streams into
  the live panel.
- `/model <name>` — `POST /api/model` flipping `Bus::set_model`.
  Takes effect on the next turn; persisted to
  `/state/hyperhive-model` so the override survives harness
  restart / rebuild.
- `/new-session` — `POST /api/new-session` (confirms first).
  Arms a one-shot on the Bus; next turn runs without
  `--continue`, dropping the resume session entirely.

Unknown `/foo` shows an error row instead of being silently sent.

### Per-agent endpoints

All POSTs return 200 (no 303 redirects). The matching mutations
fire `LiveEvent` variants on the per-agent bus, so the client
doesn't refetch `/api/state` on submit — the SSE stream
delivers the new state faster anyway. Only the login flow still
polls (session output streams in updates that aren't event-
shaped).

- `POST /send` — operator-injected message into this agent's inbox.
- `POST /login/{start,code,cancel}` — claude OAuth login flow.
  Start/cancel emit `LiveEvent::StatusChanged` to flip the
  badge to/from `needs_login_in_progress`.
- `POST /api/cancel` — SIGINT the in-flight claude turn. Emits a
  `LiveEvent::Note`.
- `POST /api/compact` — run `/compact` on the persistent session
  (same MCP config + system prompt + allowed tools as a normal
  turn — only the stdin payload differs). Flips state to
  `Compacting` via `Bus::set_state`, which emits
  `TurnStateChanged`.
- `POST /api/model` (`model=<name>`) — switch the model for
  future turns. `Bus::set_model` emits `ModelChanged`.
- `POST /api/new-session` — arm a one-shot for the next turn to
  drop `--continue`. Emits a `LiveEvent::Note`.
- `GET /events/history` — replay buffer for the terminal.

Bus events (new vocabulary on `/events/stream`):

- `status_changed { status }` — `online` /
  `needs_login_idle` / `needs_login_in_progress`. Drives the
  alive-badge.
- `model_changed { model }` — drives the model chip.
- `token_usage_changed { ctx: TokenUsage, cost: TokenUsage }`
  — drives the ctx + cost badges. Emitted from
  `Bus::record_turn_usage` at turn-end; `ctx` is the last
  inference's usage (current context size), `cost` is the
  cumulative across every inference (the `result` event's
  totals).
- `turn_state_changed { state, since_unix }` — drives the
  state badge (`idle`/`thinking`/`compacting`).