138 lines
7.9 KiB
Markdown
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.
|