The broadcast, schedules and message log cards now sit on the swarm page, after the notification router; the message log opens its stream on its first open instead of when the page loads, and its connection badge moves into its filter bar. The messages tab is removed from the header, and the old /messages address redirects to /swarm next to /schedules, which now does too. MessagesPage becomes MessageCards, and comments, tests and the swarm UI docs say the swarm page where they said the messages tab.
10 KiB
Shape (shared by both)
Part of Hives. See also: Dashboard reference · Per-agent page reference
Shared routes
GET /→index.htmlfrom the bundled frontend dist (seefrontend/). Both binaries' routers declare their dynamic endpoints first and thenfallback_service(ServeDir::new(...))pointed atHIVE_STATIC_DIR— that fallback serves anything not matched by an API or action route from the dist. Dashboard dist lives at${frontend}/dashboard; per-agent dist is the mergedservices.hyperhive.agent.frontend.mergedDist(default agent dist + per-agentextraFilesoverlay).GET /static/*→ bundled CSS + JS produced by esbuild (frontend/packages/{dashboard,agent}/build.mjs). Both pages pull the shared terminal rows + Catppuccin palette + typography from@hive/shared(washive-fr0nt); the dashboard shipscolors.css+theme.css+common.css+dashboard.css;common.cssinlines@hive/shared'sbase.css+terminal.css+tabs.css+pill.cssvia esbuild's@importresolution. Terminal rows come from@hive/shared's PreactRow,linkifyandmarkdownmodules (see "Shared terminal pane" below).GET /api/state→ JSON snapshot the JS app renders into the DOM.GET /api/dashboard/stream(dashboard) /GET /events/stream(per-agent) →text/event-streamSSE for live updates. The dashboard stream carries brokerSent/Delivered(mirrored by a forwarder task from the broker's intra-process channel) plus mutation events (transient_set/transient_cleared). The agent's own stream isGET /events/stream. One unified channel: browsers cap concurrent SSE connections per origin (~6 in Chrome). Using one channel per domain would exhaust this budget on a live hive; dispatching bykindon the client is a one-liner. Per-domain splits are reserved for high-volume sub-streams most consumers skip (none exist yet). Broker messages don't ride it: the broker's intra-process channel only wakesrecv_blocking_batch. SSE multiplexing: the dashboard uses aSharedWorker(stream-worker.js) to hold one upstreamEventSourceper URL. All same-origin tabs share this worker — a second dashboard tab joins the existing connection rather than opening a duplicate. The worker fans SSE events out to each subscribed tab viaMessagePort; on bfcache restore the page re-subscribes (gets a syntheticopenevent immediately if the upstream is already connected). Falls back gracefully whenSharedWorkeris unavailable (for example some private-mode browsers). Worker-death self-heal: Firefox kills "idle" SharedWorkers under memory pressure with no client-side signal — the port silently goes no-op. The worker now pings every connected port every 30s; the client bumps a last-activity timestamp on every message (incl. pings, which carry no URL — bumped before the URL filter). A visibility-gated watchdog polls every 15s and, if the page is visible AND has active subs AND hasn't heard from the worker in >90s (three missed pings), presumes the worker dead and re-subscribes on a freshSharedWorkerport (same code path bfcache-restore uses). Recovery is per-tab; pings are invisible on the healthy path.
Shared terminal pane
Preact components in @hive/shared draw the terminal log
(frontend/packages/shared/src/terminal/): Row.tsx draws one row, linkify.tsx
turns bare http(s):// URLs in row text into new-tab links (text nodes, so no
innerHTML), and markdown.ts turns a markdown body into HTML with marked
and then DOMPurify.sanitize() before Row.tsx assigns it. Untrusted row text
(peer messages, agent-written state files) can carry raw HTML through markdown,
so the sanitiser is what keeps that path safe, where the text-node linkify
path is safe by construction. Links open in a new tab.
A row with a body is a collapsible <details> row, open by default when the
operator's expand-tool-output preference is on. A row's kind (see termMsg.ts)
picks its look, and row-visibility.ts decides which rows show given the "show
thinking" and "hide developer details" preferences.
The consumers are the swarm UI's AgentTermPreview (the card preview and the full
terminal tab) and MessageCards. Each reads rows off a stream,
keeps the scroll pinned to the newest row until the operator scrolls more than
48 px up, and renders through Row.
The JS app handles all form[data-async] submissions via a delegated
listener: read data-confirm, swap the button to a spinner, POST
application/x-www-form-urlencoded, re-enable the button on success
(refreshState may keep the form mounted, so the handler doesn't rely on a
re-render), call refreshState(). State shapes live in
hive-c0re/src/dashboard/state_snapshot.rs::StateSnapshot and
web_ui/state.rs::StateSnapshot — when
adding state fields, plumb through the snapshot struct and the
relevant domain module (agents.js, permissions.js, etc.) render function.
Focus preservation: refreshState checks whether
document.activeElement sits inside one of the managed sections
and, if so, skips the refresh (defers 2s). The operator never has
the form yanked out from under them mid-type; the update lands as
soon as they blur.
Atomic section repaint: every managed-section renderer goes
through paintAtomic(liveRoot, build): the builder appends into
a fresh DocumentFragment (off-DOM) and the commit is one
replaceChildren call, so the intermediate empty state is never
visible — clearing and re-appending directly into the live root can
leave it empty for a paint (on async builders) or a whole frame (on
large synchronous ones), which reads as a visible flash on every
poll cycle. Builders receive the fragment as their
root, so existing renderer code carries over unchanged; early
returns inside the builder still commit whatever it appended
before returning.
Keyed DOM caching: for sections whose rows hold interactive state
(textarea drafts, checkboxes, focused inputs) paintAtomic isn't
enough — wiping and rebuilding still destroys the state even if
paintAtomic hides the flash. The keyed pattern keeps a
Map<id, {el, fingerprint}> where the fingerprint is
JSON.stringify({...visible fields...}). On each render, the pattern
reuses cache-hit rows verbatim (preserving textarea draft, checkbox
state, and event listeners) and rebuilds only cache-miss rows. Used for: containers (containerRowCache),
rebuild-queue entries (rebuildQueueRowCache). The spawn-form input+focus
uses a lighter snapshot-then-restore pattern (snapshot
before replaceChildren, restore after) since it's a single
value rather than a per-row cache.
<details> open-state preservation: any collapsible element
tagged with data-restore-key="<stable-key>" survives the
refresh. snapshotOpenDetails() walks managed sections before
render, restoreOpenDetails() re-applies after. The
dashboard's own answered-questions history list was the only
<details data-restore-key> consumer and is gone
— snapshotOpenDetails() / restoreOpenDetails() currently have
nothing to restore, kept in place for the next collapsible section
that needs it rather than ripped out along with their one caller.
Listener bind
Both bind their TCP listener with SO_REUSEADDR via
tokio::net::TcpSocket plus a retry loop on AddrInUse
(exponential backoff capped at 2s) so an nspawn restart that races
the previous process's socket release resolves itself, but the two
binaries differ on the attempt budget. The dashboard's
bind_with_retry (hive-c0re/src/dashboard/mod.rs) has no
attempt cap — retrying forever is deliberate, since
lifecycle::{spawn,rebuild} preflights genuine port collisions
host-side (refuses with a clear error, surfaced on the dashboard as a banner),
so at this layer a persistent AddrInUse always reflects a
recoverable stale socket. Its first 12 attempts log at WARN; after
that the level drops to INFO so a long-held stale socket doesn't
flood the journal. The per-agent UI's bind_with_retry
(hive-agent/src/web_ui/mod.rs) instead gives up after
MAX_BIND_ATTEMPTS (12) and returns the AddrInUse error rather
than looping forever.
The per-agent UI optionally binds a UnixListener instead of
TCP when the nix module sets HIVE_WEB_SOCKET — the unix-socket transition
mechanics (per-agent /run/hive-agent/<name>/ bind-mount,
.bound marker filtering, agent-sockets.json consumer on the
gateway side) live in docs/4-implementation/networking/gateway.md::Per-agent unix-socket upstream. The env var is opt-in per agent so the
two modes coexist while sub-agents transition.
Per-agent relative paths
The per-agent UI uses document-relative paths everywhere for
assets, API calls, form actions, and the screen WebSocket. Bare
references like static/main.js, api/state, events/stream,
screen/ws resolve against document.baseURI — the page's URL
without its last path segment.
That makes the page work under any prefix the agent ends up mounted at without rebuilding the dist. The cases that matter:
| served at | api/state resolves to |
|---|---|
/ (own port, today's shape) |
/api/state |
/agent/iris/ (gateway-prefixed) |
/agent/iris/api/state |
/agent/iris/screen (subpage, no trailing slash) |
/agent/iris/api/state |
The gateway upstream config strips the prefix before forwarding to
the per-agent server, so the agent's Rust routes (api/state,
events/stream, screen/ws, …) keep their absolute
paths server-side. Only the browser-facing URLs key off the
mount prefix.
The router serves subpages (screen) without a trailing slash so
the relative-path resolution stays correct: static/agent.css from
/screen becomes /static/agent.css (last segment screen gets
replaced), not /screen/static/agent.css. Adding a trailing slash to
those routes would break the resolution; either keep them
slash-less or use <base href> injection at serve time.