5.3 KiB
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 asimage/svg+xml. Returns/etc/hyperhive/icon.svg(set viaservices.hyperhive.agent.iconinagent.nix) when present, otherwise 404 — there is no server-side default. Consumers (the dashboard container row) hit/iconoptimistically and fall back client-side on load failure to the frontend-bundled/favicon.svgrather 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 whenservices.hyperhive.agent.gui.enable = truein the agent'sagent.nix; the harness shows a 🖥 screen link in the state row whengui_vnc_portis present. Controls:⤢ fitCSS-downscales the canvas to the window viarelayoutCanvas()setting explicit pixel dimensions on the canvas — not CSSmax-width/max-height, because a flex item's automatic minimum size (min-width: autoresolves to the canvas's intrinsic framebuffer resolution) silently clampsmax-*back up, making fit mode a no-op that just centred + clipped the oversized canvas. The fit-mode rules pin the canvas withflex: none; min-width: 0; min-height: 0so the JS-set size sticks.⤡ match sizesends an RFBSetDesktopSizerequest so the server (weston) changes its real output resolution to the window dimensions; enabled once the server advertises theExtendedDesktopSizepseudo-encoding (-308rect in the header). Fit-mode state persists inlocalStorage(screen-fit); default is on.sendPointerrescales 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 at127.0.0.1:<vnc_port>. Transparent to any RFB variant. VNC port comes from theHIVE_GUI_VNC_PORTenv var (a fixed port set on the harness service whenservices.hyperhive.agent.gui.enable; seeweston-vnc.nix).GET|POST /extra/<name>/…— extra web proxies declared viaservices.hyperhive.agent.extraWebProxiesinagent.nix(serialised to theHIVE_EXTRA_WEB_PROXIESenv 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 twoSet-Cookielines 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 anhttp(s)://URL (forwarded viareqwest) or a Unix domain socket, spelledunix:<path>(for exampleunix:/run/myapp/http.sock) — dialed directly with a raw HTTP/1.1 client per request, sincereqwesthas no UDS transport. Implemented inweb_ui/proxy.rs.GET /events/stream— the live SSE stream of classified terminal rows, whichhivectl watchreads. 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 setsrate_limitedwhen 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 fromBus::record_turn_usageat turn-end;ctxis the last inference's usage (current context size),costis the cumulative across every inference (theresultevent's totals).turn_state_changed { state, since_unix }— drives the state badge (idle/thinking/compacting).