hyperhive/docs/web-ui/agent.md

# Per-agent page

> Part of [Web UI](../web-ui.md). See also:
> [Shape (shared)](shape.md) · [Dashboard layout](dashboard.md)


Three fixed-position layers frame a full-viewport terminal: a header,
scrollable main content, and a footer composer — plus a slide-in side
panel for flyouts and long content.

## Header

Preact component tree (`Header.tsx` + `StatusChips.tsx` +
`MetaNav.tsx` + `OverflowMenu.tsx` + `HeaderPill.tsx`, wired together
in `Root.tsx`) — see `frontend/packages/agent/src/components/`. This
section describes the rendered result, not the DOM ids the pre-Preact
page used (there are none any more — every element is component
output, not something a selector reaches by id).

**Fixed-overlay header** (`<header class="agent-header">`): frosted
glass — `backdrop-filter: blur` lets scrolled terminal rows show
through. Measures its own rendered height via `ResizeObserver`
(`Header.tsx`) and writes it to a CSS custom property the content
below reads for its offset — a fixed `6em` guess used to be baked into
`agent.css`, which silently broke (content overlapping the header) the
moment any row of badges/pills wrapped onto an extra line at some
viewport width; measuring instead of guessing closes that bug class
structurally rather than for one specific trigger. Two columns:

- **Agent icon** (`<img class="agent-icon">`): fixed-size square
  identity anchor — `width: 5em; height: 5em` with explicit pixel
  sizing so the `<img>`'s intrinsic (large) dimensions don't push
  the parent flex container open via `align-items: stretch`-driven
  height feedback. Falls back to the dimmed hyperhive mark
  (`/favicon.svg`) on load error (`/icon` 404s when the agent has no
  `hyperhive.icon` override — there is no server-side default image).
- **Main column** (`.agent-header-main`, `Header.tsx`): two rows —
  title (`◆ <label> ◆`) and, when set, the "swarm / hive" identity
  line. Nothing else lives here; both rows are short, fixed-shape text
  that doesn't wrap in practice, so this column's height stays stable
  regardless of how many badges or pills are showing (a design
  correction mid-review — the first pass put the variable-width
  content here instead, which is exactly the kind of thing the
  `ResizeObserver` measurement above exists to catch even when a
  layout choice reintroduces it).
- **Pills cluster** (`.agent-header-pills`, right-aligned): status
  badges (`StatusChips.tsx`) and flyout triggers together in one row —
  a deliberate choice (not the historical default) so the header reads
  as one identity zone + one status/actions zone rather than several
  separate clusters:
  - **Alive badge**: `● alive` (green) / `⊘ rate limited` (red) /
    `◌ needs login` / `◌ logging in` / `○ offline` / `… connecting`.
  - **State badge**: `💤 idle` / `🧠 thinking` / `📦 compacting` /
    `○ offline` / `… booting` + age suffix.
  - **Model badge** (`model · <name> ▾`): a real picker — click opens
    a `Dropdown` of `state.available_models`, selecting one POSTs
    `/api/model` immediately (same endpoint the `/model <name>` slash
    command uses). No longer buried in the overflow menu — the design
    guide's own named anti-example (control disconnected from
    display) this rewrite exists to fix.
  - **Effort badge** (`effort · <level> ▾`): same shape, `/api/effort`,
    shown when `state.available_efforts` is non-empty.
  - **Ctx / cost badges**: `ctx · 142k` (last inference's prompt size,
    tooltip shows % of context window) / `cost · 1.3M` (cumulative
    tokens billed across every inference in the last turn).
  - **Pause badge** (`⏸ pause` / `▶ resume`): toggles via the same
    hive-c0re-owned `/api/pause/<name>` / `/api/resume/<name>`
    endpoints the dashboard uses (pausing needs a write this
    unprivileged process can't make directly).
  - **Inbox / todos pills** (`📬 inbox · N` / `📋 todos · N`): hidden
    when empty; click opens the matching flyout in the side panel.
  - **Links badge** (`🔗`): opens a popover listing `↑ dashboard`
    (back-link to the host dashboard, `${dashboardBase}dashboard.html`)
    followed by this agent's `agent_links()`-sourced navigation (stats,
    screen when VNC is enabled, forge profile + config-repo mirror when
    the agent has a forge account, any `hyperhive.dashboardLinks`
    extras) — all as real `<a>` elements, not a `Dropdown`-style
    command list, so ctrl/middle-click and "copy link address" keep
    working. Each `AgentLink.kind` resolves differently: `container` →
    same-origin path; `forge` → `state.forge_public_url + url`, and the
    link is dropped entirely when that's unset (never guessed from
    `<host>:3000`); `external` → already absolute. Same source
    (`GET /api/state`'s `links` field) also feeds
    `DashboardState.links` for the dashboard card's icon strip —
    `agent_links()` in hive-agent is the single source of truth for
    both. There is no separate overflow (`⋯`) menu any more — it used
    to hold exactly this dashboard link plus a rebuild-container action
    (mara, hyperhive#3704: "remove rebuild button, move link to
    dashboards into links menu") — rebuild had no real discoverability
    need of its own (the dashboard's own R3BU1LD button already covers
    it) so it's gone outright, and the dashboard link moved here,
    leaving nothing to justify a separate menu. Everything else that
    used to live in the old overflow menu (model/effort pickers,
    new-session, logout) already had a better home before this: pickers
    are real badges above, and `/new-session` / `/logout` are typed
    slash commands with their own type-twice confirm (see below) — a
    modal doesn't fit a text-input flow, and burying rare-but-important
    actions in one flat menu was the design guide's own named
    anti-example.
  - No header cancel-turn button any more — `/cancel` (slash command,
    below) is the only path; the turn-loop state badge already shows
    `thinking` as the discoverability cue.

Values throughout come from `GET /api/state`'s cold-load snapshot,
kept in sync afterwards by the SSE stream (see Live view below) —
`context_window_tokens` for the ctx badge tooltip, `qualified_label`
(the hive-qualified `name@domain` form, used for the browser tab title
so two tabs from different hives are distinguishable; the header's own
`◆ <label> ◆` stays short).

## Main content

**Main content** (`<main class="agent-main">`): fills the viewport
and scrolls behind the fixed header + footer.

- `#status` overlay: empty when online; shows the login form / OAuth
  URL when `status` is `needs_login_*`. The OAuth code input is
  `type="password"` with a `👁 reveal` toggle that flips it back to
  `text` on press so the operator can sanity-check the paste before
  submit — avoids accidental on-screen token exposure to
  shoulder-surfers or screenshots. `autocomplete="one-time-code"`
  is the semantic value for OAuth codes (per WHATWG): browsers may
  silently ignore `autocomplete="off"` on `type="password"`, but
  `one-time-code` is honoured and suppresses the "save password
  for this site?" prompt that would otherwise fire on submit.
- Terminal-wrap: live event tail (sticky-bottom auto-scroll +
  `↓ N new` pill when not at bottom). The pill is **anchored in
  `.agent-main`**, not in `log.parentElement = .terminal-wrap`:
  `.terminal-wrap` applies `backdrop-filter: blur` for the frost
  effect, which creates a CSS stacking context — anchoring the
  pill inside that context would trap its `z-index` below the
  fixed composer in the root stacking context, and it'd never
  float. `.agent-main` has no backdrop-filter (no stacking-context
  creators), so the pill's `z-index` reaches the root and properly
  composites above the composer. Geometry is unchanged —
  `.agent-main` and `.terminal-wrap` both `inset: 0` fill the same
  area.

## Footer / composer

**Fixed-overlay footer** (`<footer class="agent-composer">`): frosted
glass, symmetric with the header. Contains the operator-input
textarea (`#term-input`) — multi-line, Enter sends, Shift+Enter
newlines, Tab-completes slash commands (see [Terminal-embedded
prompt](#terminal-embedded-prompt) below).

## Side panel

**Side panel** (slide-in from right): singleton shared with the
dashboard's side panel shape. Carries inbox and todos flyouts (opened
via the header pills) as well as long content (file previews, diffs,
journald logs). Inbox flyout: unread messages addressed to this agent
(`acked_at IS NULL`, newest-first, up to 30); reply messages indented
with `↳ reply ·` in amber. A `✓ mark all read` button appears in the
flyout header when the inbox is non-empty; clicking it confirms then
POSTs cross-origin to the core dashboard's `POST
/api/agent/{name}/mark-all-read` — all pending messages for this agent
are acked, the harness won't receive wake-prompts for them. A `{
marked: N }` pill surfaces the count. After the drain the inbox list
empties on reload (the filter is `acked_at IS NULL`, so drained
messages disappear). Todos flyout ("loose-ends v2"): the harness-local
todos other subsystems push at this agent (`GET /api/todos`) — matrix,
forge, and bash are the built-in producers, but any user-configured MCP
server can push its own via the same in-agent socket. Each row shows the
producing subsystem, an
optional source label, a summary, and age. A checkbox per row plus a
select-all / select-none / `✓ mark done` bulk row above the list POSTs
the checked ids to `POST /api/todos/mark-done`, which dismisses them
from the harness-local store (same effect as `cancel_loose_end(kind:
"todo")`, just from the web UI instead of the agent's own tool calls).

The todos flyout is the only per-agent flyout — there is no separate
"loose-ends" or "tasks" list. There is also no inline answer form for
`ask` tool calls in this terminal: an `ask` renders like any other
tool call, and the operator answers a pending question from the
dashboard's Y3R C4LL tab instead (see
[`terminal-rendering.md`](../terminal-rendering.md#inline-ask-operator-answer)).

## 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 }`. Each event also carries a `ts` (unix
seconds) — a flattened sibling of the event tag on both the live
SSE frame and the replayed history rows. The web UI:

- fetches `GET /events/history` on page load and replays the last
  2000 events (oldest first);
- 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;
- terminal-themed: phosphor mauve glow, Crust bg,
  backdrop-filter blur, row fade-in slide-up.

The backfill/live-tail dedupe, sticky-bottom auto-scroll, and "↓ N
new" pill are the shared terminal-pane mechanics described in
[Shape](shape.md#shared-terminal-pane) — this page's log is one
instance of that same factory.

Per-stream rendering (see [`docs/terminal-rendering.md`](../terminal-rendering.md) for
the full row taxonomy and dispatch logic):

- `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 with
    per-tool salient-arg extraction (`fmtToolUse`).
- `Stream` `tool_result` short → flat `← ...`; long → collapsed
  `<details>` `▸ ← Nl · headline` (click to expand full body).
- `Stream` `thinking` → `.thinking` row with a `💭 thinking …`
  indicator.
- `Stream` `system` → handled by subtype: `plugin_install` and
  `compact_boundary` emit muted notes; `commands_changed` emits an
  expandable details row listing slash commands; `thinking_tokens`
  updates a single in-place `🧠` counter; `init`, `result`, and
  `rate_limit_event` are dropped (noise / used elsewhere); other
  subtypes → muted `⚙ <subtype>` note.
- `Note` → `· text`.
- `TurnStart` → `◆ TURN ← <from>` with the wake-prompt body; a
  muted `· HH:MM:SS` time suffix from the event `ts`.
- `TurnEnd` → `✓ turn ok` / `✗ turn fail — note`, with a
  `· HH:MM:SS · <duration>` suffix (duration = end − the paired
  turn-start), triggers a `refreshState()`. The time suffix is
  guarded on a numeric `ts`, so rows degrade cleanly when absent.

## 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` → sets the deferred
  `Bus::request_compact()` flag and returns immediately. The harness
  runs the `/compact` at the next turn boundary (end of the in-flight
  turn, or `turn::run_pending_compact` when idle); output streams into
  the live panel. Works mid-turn, not only when idle.
- `/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.
- `/effort <level>` — `POST /api/effort` setting the claude effort
  level (`low` / `medium` / `high` / `xhigh` / `max`). Takes effect on the next
  turn. The overflow menu surfaces an effort picker that calls the
  same endpoint; both stay in sync via `StateSnapshot.effort`.
- `/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.
- `/logout` — `POST /api/logout` (confirms first). Wipes OAuth
  credential files, parks the agent in `needs_login`. Session
  history (`~/.claude/projects/`) is preserved.

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

## Per-agent endpoints

Successful POSTs return 200 (no 303 redirects). Error responses
use semantic status codes: **400** for missing/invalid input
(`body` required, unknown model name, invalid effort level),
**409** for retryable state conflicts (turn in flight when
`/compact` is called), **500** only for genuine server/transport
failures. 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/effort` (`effort=<level>`) — switch the claude
  effort level for future sessions. Validated server-side against
  `EFFORT_LEVELS` (`low`/`medium`/`high`/`xhigh`/`max`) — unknown values are
  rejected rather than forwarded to `claude --effort`. Persists via
  `Bus::set_effort`, which emits `EffortChanged`. Applies on the next
  session start (no mid-session swap).
- `POST /api/new-session` — arm a one-shot for the next turn to
  drop `--continue`. Emits a `LiveEvent::Note`.
- `POST /api/logout` — three-step teardown that re-uses the
  existing `wait_for_login` resumption path:
  1. SIGINT any running claude (matches `/api/cancel`'s pattern —
     idempotent no-op when nothing is running) so the credential
     wipe doesn't race a mid-API-call turn.
  2. Delete only the OAuth credential files
     (`.credentials.json` + `mcp-needs-auth-cache.json` under
     `~/.claude/`). **Preserves** session history files
     (`projects/<hash>/*.jsonl`), sessions, shell-snapshots,
     plans, settings, telemetry, and the dir itself, so
     `claude --continue` keeps working after a fresh login.
     ⚠️ Deleting the whole `~/.claude/` directory instead breaks
     session continuity — logout must stay narrowed to just the
     credential files.
  3. Flip `LoginState::NeedsLogin` + emit a `LiveEvent::Note`
     describing exactly what was wiped, then emit
     `needs_login_idle`. The turn-loop's next iteration parks
     into `wait_for_login`, which snapshots the credential dir
     (now missing the wiped files) and resumes when a fresh
     credentials file appears via the dashboard's `/login/code`
     flow (the same mtime-resumption path manual re-login uses).

  Always returns 200 with a body describing what happened —
  per-file errors are folded into the response + the Note so the
  operator sees them in the live panel rather than as an HTTP
  error. Missing files (already logged out) are treated as
  idempotent.
- `GET /api/state` — cold-load snapshot (`StateSnapshot`) consumed by
  the frontend (`useAgentState.ts`) on page load and, on a poll, while
  `status === 'needs_login_in_progress'`. Includes `turn_state`,
  `context_window_tokens`, `qualified_label`,
  `available_models`, `effort`, `available_efforts`, `links`, and
  other fields described inline throughout this document. All
  subsequent state updates arrive via SSE.
- `GET /api/dashboard-state` — lean snapshot of agent-owned fields
  fetched once per running agent by the dashboard's container row to
  get fresh values without relying on hive-c0re's periodic file-reads.
  Returns `{ status_text?, status_set_at?, ctx_tokens?, context_window_tokens,
  rate_limited, links }`. Only called when the container is running;
  skipped (muted badges) when stopped. Also accessible via the gateway
  at `/agent/<name>/api/dashboard-state`.
- `GET /api/todos` — harness-local todos snapshot (loose-ends v2)
  consumed by the todos flyout (`refreshTodos` / `buildTodosList`).
  See the todos-flyout paragraph above for the producer/subsystem
  model and the bulk mark-done row.
- `GET /api/stats?window=24h|7d|30d|all` — time-bucketed turn analytics
  `Snapshot` consumed by the `/stats` page. `all` ranges from the
  earliest recorded turn with an adaptive bucket width.
- `GET /icon` — agent's icon as `image/svg+xml`. Returns
  `/etc/hyperhive/icon.svg` (set via `hyperhive.icon` in `agent.nix`)
  when present, otherwise **404** — there is no server-side default.
  Consumers (dashboard container row, this page's own header icon)
  hit `/icon` optimistically and fall back client-side on load failure
  to the frontend-bundled `/favicon.svg` rather than probing first.
- `GET /events/history` — replay buffer for the terminal.
- `GET /screen` — VNC viewer page (minimal RFB-over-WebSocket
  renderer — deliberately thin, just enough to display the
  desktop + forward pointer + keyboard. A production-grade viewer
  would vendor noVNC; this file ships the minimal in-tree variant).
  Only accessible when `hyperhive.gui.enable = true` in the agent's
  `agent.nix`; the harness shows a 🖥 screen link in the state row
  when `gui_vnc_port` is present. A `← agent` back-link in the page
  header returns to the main per-agent page. Controls: `⤢ fit` CSS-downscales
  the canvas to the window via `relayoutCanvas()` setting explicit
  pixel dimensions on the canvas — *not* CSS `max-width/max-height`,
  because a flex item's automatic minimum size (`min-width: auto`
  resolves to the canvas's intrinsic framebuffer resolution) silently
  clamps `max-*` back up, making fit mode a no-op that just centred +
  clipped the oversized canvas. The fit-mode rules pin the canvas
  with `flex: none; min-width: 0; min-height: 0` so the JS-set size
  sticks. `⤡ match size` sends an RFB `SetDesktopSize` request so the
  server (weston) changes its real output resolution to the window
  dimensions; enabled once the server advertises the
  `ExtendedDesktopSize` pseudo-encoding (`-308` rect in the header).
  Fit-mode state persists in `localStorage` (`screen-fit`); default
  is on. Pointer coordinates are rescaled in `sendPointer` so clicks
  land on the right pixel regardless of CSS scale.
- `GET /screen/ws` — raw RFB byte relay: proxies WebSocket
  frames to the weston VNC server at `127.0.0.1:<vnc_port>`.
  Transparent to any RFB variant. VNC port comes from the
  `HIVE_GUI_VNC_PORT` env var (a fixed port set on the harness
  service when `hyperhive.gui.enable`; see `weston-vnc.nix`).
- `GET|POST /extra/<name>/…` — **extra web proxies** declared via
  `hyperhive.extraWebProxies` in `agent.nix` (serialised to the
  `HIVE_EXTRA_WEB_PROXIES` env var as a JSON object
  `{"<name>": "<upstream_url>"}`). Each entry mounts a transparent
  reverse-proxy at `/extra/<name>/` that forwards every request (method,
  headers, body) to the configured upstream, strips hop-by-hop headers
  on both sides, and buffers the full response body (MVP — SSE
  connections will appear as one large response rather than streaming).
  The `/extra/` namespace ensures user-declared proxies can never
  conflict with native agent endpoints. Upstream values are either an
  `http(s)://` URL (forwarded via `reqwest`) or a Unix domain socket,
  spelled `unix:<path>` (e.g. `unix:/run/myapp/http.sock`) — dialed
  directly with a raw HTTP/1.1 client per request, since `reqwest` has
  no UDS transport. Implemented in `web_ui/proxy.rs`.

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

- `status_changed { status }` — `online` / `rate_limited` /
  `needs_login_idle` / `needs_login_in_progress`. Drives the
  alive-badge. `rate_limited` is set when the harness detects a
  429 response and cleared when the retry sleep expires.
- `model_changed { model }` — drives the model chip.
- `effort_changed { effort }` — drives the effort picker chip.
  Emitted from `Bus::set_effort` on `POST /api/effort`; applies on
  the next session start.
- `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`).

## Stats page

`GET /stats` is a separate per-agent page (served by the
harness, linked from the per-agent page's `📊 stats →` and from
each dashboard container row). A `← live` back-link in the page
header returns to the main per-agent page. Turn analytics, read-only, from
`/state/hyperhive-turn-stats.sqlite`. `GET /api/stats?window=
24h|7d|30d|all` returns a time-bucketed `Snapshot`; the page renders
it with Chart.js (bundled into `stats.js` via esbuild — no CDN
dependency). Charts: turns, duration (p50 · p95 · avg), context
tokens, token cost per bucket, a **turns-by-model** stacked bar
(model choice drives token cost, so it sits directly under the
cost chart), doughnuts for tool / wake-source / result mix, and a
**result-trend** stacked bar — per-bucket `result_counts` so
error / rate-limit / compaction outcomes are visible over time
(the doughnut shows only the window total).
A **favorite tools** doughnut shows the most-run shell commands —
normalised `bash_commands` heads written per bash task by the
hive-bash-daemon capture: the basename of the *first real command*,
looking past `cd repo &&` prefixes, env-assignments, and
prefix-runners like `sudo` / `env` (so `cd /repo && cargo build`
records `cargo`, not `cd`). Read via `bash_breakdown`; the card
stays hidden until the agent has run a bash command (a missing
`bash_commands` table degrades to an empty list), so it never
renders an empty chart.
A summary chip row carries window totals, plus two
token-efficiency chips derived from the bucket sums: **cache
hit-rate** (`cache_read` over all input-side tokens) and
**tokens/turn**. When `reminder_stats` is present (fetched via
`ReminderRollup` RPC and merged into the snapshot in
`web_ui/stats.rs::api_stats`) three more chips appear: **reminders
scheduled / delivered / pending** for the window. When the
per-session capture has data, a **first-turn ctx** chip shows the
input tokens of the most recent fresh claude session's first turn —
a proxy for system-prompt + CLAUDE.md sprawl (a fresh session's first
turn pays the full static prefix uncached). It's derived in `stats.rs`
(`first_turn_ctx`: the first turn, `ORDER BY started_at LIMIT 1`, of
the latest `sessions` row in the window) and is omitted from the JSON
until the `sessions` / `turn_stats.session_id` capture has rows — so
the chip stays hidden on older dbs (inert-until-capture).
`stats.rs` opens the sqlite db read-only and degrades to an
empty snapshot on any error — the page is decorative, never
authoritative.