hyperhive/docs/2-handbook/agents/web-page.md

# Per-agent page

> Part of [Agents](README.md). See also:
> [Shape (shared)](../../4-implementation/web-ui/shape.md) · [Dashboard layout](../hives/dashboard.md)


Two fixed-position layers frame a full-viewport terminal: a header and
scrollable main content — plus a slide-in side panel for flyouts and long
content. The page has no message box: to write to an agent, use the swarm
UI's terminal.

## 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 and effort badges** (`model · <name>`, `effort · <level>`):
    display only. Each tooltip says where the value comes from
    (`state.model_source` / `state.effort_source`: set on the swarm,
    agent.nix, an existing `hyperhive-model` / `hyperhive-effort` file, or
    the built-in default); the model's also says what the last turn
    resolved it to. Both are set on the swarm: the swarm UI's agents page,
    or `swarmctl agent inference set`
    ([`inference.md`](../../4-implementation/swarm/inference.md)).
  - On an ACP agent each badge shows the session's own value when it
    doesn't offer the requested one. The effort badge is hidden
    (`state.effort` is `null`) until the first turn has attached a
    session, when the model offers no effort levels, and while a newly
    set 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.
  - **Profile avatar**: the signed-in user's initial, opening a popover with
    their name and links to authelia's settings and sign-out pages, as on the
    dashboard (`AgentUserMenu.tsx`). It shows only behind the gateway, where
    the page shares the dashboard's origin and session; opened on the agent's
    own port there is no sign-in and no avatar. The name comes from the
    dashboard's `/api/whoami`, authelia's URL from the dashboard's
    `/api/state`.
  - **Links badge** (`🔗`): opens a popover listing `↑ dashboard`
    (back-link to the host dashboard, `${dashboardBase}`)
    followed by this agent's `agent_links()`-sourced navigation (stats,
    screen when VNC is enabled, 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; `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. `cancel turn`,
    `new session` and `log out` are rows of the state badge's menu, each
    with a click-again confirm (see Actions below).
<!-- 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 confine its `z-index` below the
  fixed header 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 header. Geometry is unchanged —
  `.agent-main` and `.terminal-wrap` both `inset: 0` fill the same
  area.
<!-- vale write-good.Passive = YES -->

## 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).
If the todo store errors or doesn't answer for any id, the endpoint returns
500 naming how many ids failed, and the panel shows `failed: …` instead of
`✓ marked done`.

## 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](../../4-implementation/web-ui/shape.md#shared-terminal-pane) — this page's log is one
instance of that same factory.

Per-stream rendering (see [`docs/4-implementation/web-ui/terminal-rendering.md`](../../4-implementation/web-ui/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.

## Actions

The state badge's menu carries the actions on the agent's claude:

- `cancel turn` — `POST /api/cancel` → SIGINT to the turn's claude and every
  command it started (its process group), emits a Note. On an ACP agent
  it sends the agent `session/cancel` instead, and SIGINT if the turn
  hasn't ended 10s later. Offered while the state is `thinking`.
- `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.
- `log out` — `POST /api/logout` (confirms first). Wipes OAuth
  credential files, parks the agent in `needs_login`, and preserves
  session history (`~/.claude/projects/`).

`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, which ends with a `/compact done`
or `/compact failed: …` note. It works mid-turn, not only when idle. Nothing
on this page calls it now.

## Per-agent endpoints

Successful POSTs return 200 (no 303 redirects). Error responses
use semantic status codes: **400** for missing/malformed input
(`body` required, unknown model name, unrecognised 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.

The agent has no login flow of its own. An agent without credentials
reports `needs_login_idle`, the operator logs in from the swarm UI, and the
credentials arrive from the swarm secret store.

- `POST /api/cancel` — SIGINT the in-flight claude turn and the
  commands it started. 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/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 (a login from the swarm UI stores one,
     and the agent installs it).

  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. Includes `turn_state`,
  `context_window_tokens`, `qualified_label`,
  `model`, `model_source`, `effort`, `effort_source`, `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 presses
  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 (repeated response headers such as two `Set-Cookie` lines
  are all forwarded), 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`. 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. The harness emits it
  when it applies or clears a swarm value.
- `effort_changed { effort }` — drives the effort chip. The harness
  emits it when it applies or clears a swarm value.
- `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 + AGENTS.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.