90 lines
5.3 KiB
Markdown
90 lines
5.3 KiB
Markdown
# 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](../../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 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`).
|