# Per-agent page

> Part of [Web UI](README.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` + `HeaderPill.tsx`, wired together in `Root.tsx`) — see
`frontend/packages/agent/src/components/`. This section describes the
rendered component tree: every element is Preact component output.

**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, so content never overlaps the header
regardless of how many rows of badges/pills wrap onto an extra line
at a given viewport width. Two columns:

<!-- vale write-good.Passive = NO -->
- **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
  `services.hyperhive.agent.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,
  so the header reads as one identity zone + one status/actions zone:
  - **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 — selecting it opens
    a `Dropdown` of `state.available_models`, selecting one POSTs
    `/api/model` immediately (same endpoint the `/model <name>` slash
    command uses). A header badge: the control and its display sit
    together.
  - **Effort badge** (`effort · <level> ▾`): same shape, `/api/effort`,
    shown when `state.available_efforts` is non-empty.
  - On an ACP agent both pickers list what its session offers (its
    `model` and `thought_level` config options), and are empty until the
    first turn has attached a session. The effort picker is hidden when the
    model offers no effort levels, and while a newly picked model waits for
    the next turn, since the levels come with the model.
  - **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; selecting it 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 `services.hyperhive.agent.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
    hive-agent drops the link 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. The dashboard link lives in this 🔗 popover; the model/effort
    pickers are real badges above; and `/new-session` / `/logout` are
    typed slash commands with their own type-twice confirm (see
    below).
  - `/cancel` (slash command, below) is the only cancel-turn path; the
    turn-loop state badge already shows `thinking` as the
    discoverability cue.
<!-- vale write-good.Passive = YES -->

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.

<!-- vale write-good.Passive = NO -->
- `#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
  browsers honour `one-time-code` and suppress the "save password
  for this site?" prompt that would otherwise fire on submit.
- Terminal-wrap: live event tail (sticky-bottom autoscroll +
  `↓ 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.
<!-- vale write-good.Passive = YES -->

## 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; selecting it confirms then
POSTs cross-origin to the core dashboard's `POST
/api/agent/{name}/mark-all-read`, which acks all pending messages for
this agent so 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).

## 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 autoscroll, 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/web-ui/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` (select 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` drop silently (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. On an ACP agent it sends the agent
  `session/cancel` instead, and kills it if the turn hasn't ended 10s
  later. 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. `StatusChips`' effort badge 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`, and preserves
  session history (`~/.claude/projects/`).

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` fires), **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).
- On an ACP agent, `/api/model` and `/api/effort` accept only values the
  session offers, and the runtime sets them with `session/set_config_option`
  before the next prompt.
- `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`
     naming the files it just deleted, 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 — it
  folds per-file errors 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) count 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 `services.hyperhive.agent.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 `services.hyperhive.agent.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. `sendPointer` rescales pointer coordinates 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 `services.hyperhive.agent.gui.enable`; see `weston-vnc.nix`).
- `GET|POST /extra/<name>/…` — **extra web proxies** declared via
  `services.hyperhive.agent.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>` (for example `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. The harness sets `rate_limited` when it detects a
  429 response and clears it 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 stays out of 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.