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

5.3 KiB

Per-agent web server: screen and endpoints

What each agent's harness serves on its own port: 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 screen page's title and login, and the hive dashboard's port for its 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 /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.

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