Per-agent page

Part of Web UI. See also: Shape (shared) · Dashboard layout

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:

• 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).
  • 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.
  • 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, 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, 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.

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 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.

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 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). 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 — this page's log is one instance of that same factory.

Per-stream rendering (see docs/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.

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 → 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. 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. Either way the live panel ends with a /compact done or /compact failed: … note.
• /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 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 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, 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 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 (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 / 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. 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.