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

138 lines
7.9 KiB
Markdown

# 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](../../2-handbook/agents/web-page.md). 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.