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.
194 lines
10 KiB
Markdown
194 lines
10 KiB
Markdown
# Shape (shared by both)
|
|
|
|
> Part of [Hives](../../2-handbook/hives/README.md). See also:
|
|
> [Dashboard reference](dashboard.md) · [Per-agent page reference](agent-page.md)
|
|
|
|
## Shared routes
|
|
|
|
- `GET /` → `index.html` from the bundled frontend dist (see
|
|
`frontend/`). Both binaries' routers declare their dynamic
|
|
endpoints first and then `fallback_service(ServeDir::new(...))`
|
|
pointed at `HIVE_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 merged
|
|
`services.hyperhive.agent.frontend.mergedDist` (default agent dist + per-agent
|
|
`extraFiles` overlay).
|
|
- `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` (was `hive-fr0nt`); the dashboard ships
|
|
`colors.css` + `theme.css` + `common.css` + `dashboard.css`;
|
|
`common.css` inlines `@hive/shared`'s
|
|
`base.css` + `terminal.css` + `tabs.css` +
|
|
`pill.css` via esbuild's `@import` resolution.
|
|
Terminal rows come from `@hive/shared`'s Preact `Row`, `linkify` and
|
|
`markdown` modules (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-stream` SSE for live updates. The
|
|
dashboard stream carries broker `Sent` / `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 is `GET /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
|
|
by `kind` on 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 wakes `recv_blocking_batch`.
|
|
**SSE multiplexing**: the dashboard uses a
|
|
`SharedWorker` (`stream-worker.js`) to hold one upstream
|
|
`EventSource` per 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 via `MessagePort`; on bfcache restore the
|
|
page re-subscribes (gets a synthetic `open` event immediately
|
|
if the upstream is already connected). Falls back gracefully
|
|
when `SharedWorker` is 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 fresh `SharedWorker` port (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.
|
|
|
|
<!-- vale write-good.Passive = NO -->
|
|
|
|
**`<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.
|
|
|
|
<!-- vale write-good.Passive = YES -->
|
|
|
|
## 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`](../networking/gateway.md). 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.
|