shared/src/terminal/terminal.js (and its index.js re-export and package export) had no importer: the Preact Row replaced it. The .tail-pill and .load-more-pill rules were only made by it, and the preview's own tail-pill override styled a pill that no longer exists. hive-tab-strip.js had no importer either. Four constants nobody imports are no longer exported. The shared terminal pane section of the web-ui shape doc now describes Row, linkify and markdown instead of the removed factory. Header comments that named removed components (StatusChips, MetaNav, Root.tsx, the cost badge, four folded sections, a detail dialog) now describe the current code.
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 `MessagesPage`. 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.
|