Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/docs/4-implementation/web-ui/agent-page.md

7.9 KiB

Per-agent web server: stats, screen and endpoints

What each agent's harness serves on its own port: the stats page, the GUI screen page, the stream hivectl watch reads, the dashboard card's state and the extra proxies. The operator's overview is the agent web server. The agent has no terminal page of its own: the live terminal and its message box are in the swarm UI.

Per-agent endpoints

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.

  • GET /api/state — {label, dashboard_port}: the agent's name, for the stats and screen pages' titles and the screen's login, and the hive dashboard's port for their way back.
  • 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?, 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/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 (the dashboard container row) hit /icon optimistically and fall back client-side on load failure to the frontend-bundled /favicon.svg rather than probing first.
  • 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. 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.
  • GET /events/stream — the live SSE stream of classified terminal rows, which hivectl watch reads. The swarm UI shows the same rows from the swarm queue.
  • GET / redirects to /stats.

Bus events 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 per-agent page (served by the harness, linked from each dashboard container row). 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.