Watch
0
0
Fork
You've already forked hyperhive
0

remove the agent's live terminal page and the endpoints only it used

This commit is contained in:
iris 2026-11-16 04:31:36 +01:00 • committed by mara
commit 6289b8d64b
14 changed files with 127 additions and 4053 deletions

View file

@ -11,8 +11,8 @@ config changes, what its own page shows and how far you can trust it.
- **[Persistence and config changes](persistence.md)** — what survives a
restart, a destroy and a purge, and how a change to an agent's config flows
from a pull request to its container.
- **[The agent's web page](web-page.md)** — the per-agent terminal view, its
actions and its endpoints.
- **[The agent's web server](web-page.md)** — the stats and screen pages and
what the dashboard reads from each agent.
- **[Security model](security.md)** — the trust model, the prompt-injection
threat model and credential isolation.

View file

@ -1,24 +1,18 @@
# Per-agent page
# Per-agent web server
> Part of [Agents](README.md). See also: [Dashboard layout](../hives/dashboard.md)
Every agent's harness serves a page of its own, reached from the agent's row on
the hive dashboard. It shows a live terminal view of what the agent is doing: its
turns, tool calls and results as they happen, with the recent history replayed
when you open it. The page has no message box; to write to an agent, use the
terminal in the [swarm UI](../swarm/ui.md). Like the hive dashboard, it
keeps shrinking, bit by bit.
Every agent's harness serves a small web server of its own, reached from the
agent's row on the hive dashboard. It has no terminal and no message box: to
watch an agent work or write to it, use its terminal in the
[swarm UI](../swarm/ui.md), and `hivectl watch` follows it from the command
line. What the server offers:
- **Header**: the agent's icon and name, a state badge (idle, thinking, needs
login), and pills for its inbox and todos. Selecting a pill opens the list in
a side panel. The inbox panel has **mark all read**, and the todos panel lets
you dismiss todos.
- **State badge menu**: **cancel turn** stops the turn in flight, **new session**
starts the next turn without the resume session, and **log out** wipes the
agent's claude login (it then waits in `needs_login`).
- **Stats page**: the agent's turn statistics. The same figures are in Grafana's
`agents` board.
- **Stats page**: the agent's turn statistics. The same figures are in
Grafana's `agents` board.
- **Screen page**: a live view of the agent's desktop, for an agent with a GUI.
- **Dashboard card data**: the status text and the links the hive dashboard shows
for the agent.
The header's parts, the live view, the endpoints the page and the harness serve,
and the stats page are in
[the agent page reference](../../4-implementation/web-ui/agent-page.md).
The endpoints and the stats page are in
[the per-agent web server reference](../../4-implementation/web-ui/agent-page.md).

View file

@ -36,17 +36,17 @@ The dashboard is a single page with these tabs:
- **K3PT ST4T3** — kept state from agents with no container (tombstones),
with a purge button per entry.
Each agent also has its own page, a full terminal view of that agent's
session. Select its name anywhere in the dashboard, or open `/agent/<name>/`
(or `http://<host>:<port>/` if the gateway isn't in front). [The agent's web page](../agents/web-page.md)
covers it.
Each agent also serves a small web server, with its stats and screen pages: open
`/agent/<name>/` (or `http://<host>:<port>/` if the gateway isn't in front).
[The agent's web server](../agents/web-page.md) covers it. To watch an agent
work, use its terminal in the swarm UI.
## The things you do here
**Check on an agent.** 4G3NTS shows every container as a row: name, whether
it's running, what it's doing (a live status pill such as `rebuilding…` or
`starting…` while something's in flight), and quick links (stats, screen).
Select the name to open its terminal and watch it work.
Open the agent in the swarm UI to watch it work.
**Review a config change.** Agent config changes (new packages, env vars, MCP
servers) are pull requests on the agent's `agent-configs` repo. Review and
@ -79,9 +79,8 @@ schedules card on the swarm UI's messages tab ([`swarm-ui.md`](../../4-implement
## More depth
The dashboard and the per-agent pages are single-page apps that share one
skeleton: `GET /` returns a static shell, `/api/state` returns JSON, and
JavaScript renders, with no full-page reloads.
The dashboard is a single-page app: `GET /` returns a static shell, `/api/state`
returns JSON, and JavaScript renders, with no full-page reloads.
- **[Shape (shared by both)](../../4-implementation/web-ui/shape.md)** — the
SPA skeleton, SSE multiplexing, terminal pane, listener bind, per-agent
@ -105,10 +104,9 @@ For the code, these jump straight to the relevant section:
- **"What endpoints does the dashboard expose?"** →
[`dashboard.md`](../../4-implementation/web-ui/dashboard.md) (Dashboard endpoints,
Dashboard event channel).
- **"How does the per-agent terminal render tool calls?"** →
- **"How does a terminal render tool calls?"** →
[`terminal-rendering.md`](../../4-implementation/web-ui/terminal-rendering.md)
(the full row taxonomy and dispatch walkthrough); for a summary see
[`agent-page.md`](../../4-implementation/web-ui/agent-page.md) (Per-stream rendering).
(the full row taxonomy and dispatch walkthrough).
- **"Which CSS variable to use, and where are the colours defined?"** →
[`css-vars.md`](../../4-implementation/web-ui/css-vars.md) (Palette, the
single-source `base.css` rule).

View file

@ -17,7 +17,7 @@ always on), the gateway proxies all operator-facing traffic, and
## Two principals, two paths
- **Operator** — reaches every UI (the dashboard + every
per-agent page) through the gateway, on one origin.
per-agent web server) through the gateway, on one origin.
The core daemon serves operator-authority actions
(answer-as-operator, lifecycle POSTs), reachable only via the
gateway.
@ -67,13 +67,11 @@ netns-isolated for the same reason.
The boundary rests on three layers:
1. **Gateway** — fronts all surfaces (dashboard + every per-agent UI)
on one origin. An nginx nixos-container proxies per-agent UIs under
`/agent/<name>/`, which is what lets each agent page's inbox panel
POST `mark-all-read` to the core dashboard's
`/api/agent/{name}/mark-all-read` go same-origin instead of needing
a cross-origin CORS shim. Pure ergonomics — no behavioural risk on
its own.
1. **Gateway** — fronts all surfaces (dashboard + every per-agent web
server) on one origin. An nginx nixos-container proxies the per-agent
servers under `/agent/<name>/`, so the dashboard's links to them go
same-origin instead of needing a cross-origin CORS shim. Pure
ergonomics — no behavioural risk on its own.
2. **Network isolation** — the load-bearing layer: every agent
container runs in a private netns behind the hive bridge, always
on and unconditional. This is what turns the operator/agent split

View file

@ -379,7 +379,7 @@ checking file existence):
| request | resolved | outcome |
| --- | --- | --- |
| `/agent/iris/` | `<frontend>/index.html` | main agent page |
| `/agent/iris/` | no file match → `@iris_dynamic` | proxied to the agent daemon, which redirects to `stats` |
| `/agent/iris/stats` | `<frontend>/stats.html` | stats page |
| `/agent/iris/screen` | `<frontend>/screen.html` | screen page |
| `/agent/iris/static/app.js` | caught by `^~` block first | served with immutable cache |

View file

@ -71,7 +71,7 @@ time the first time it reads the same number.
- it logs the agent out when the store holds nothing although a version was
installed: the operator deleted the stored login. A read that failed never
does it, since an unreachable store says nothing about the login. The
logout is the one `/api/logout` does, and the recorded version is
logout wipes the credential files and flips the agent to `needs_login`, and the recorded version is
forgotten so the next login installs.
## Credentials

View file

@ -95,8 +95,8 @@ primary mechanism; hyperhive still owns that). `outputStyle` is fleet-wide
preamble/recap Concise drops carries no information a turn-loop consumer
needs.
**Session reset** is available via `POST /api/new-session` (the state
badge's `new session` menu row). It does _not_ touch the session inline —
**Session reset** is available as `/clear` in the swarm UI's message box
(`POST /api/agents/<name>/new-session`, a command on the agent's control subject). It does _not_ touch the session inline —
that would race a mid-write claude process. Instead `Bus::request_session_reset()`
sets a one-shot flag consumed at the next turn boundary by `drive_turn`,
which **archives** the current session: it renames the backing

View file

@ -30,7 +30,7 @@ services.hyperhive.agent.icon = ./icon.svg; # default: null (falls back to shar
```
Path to an SVG file used as this agent's visual identity — shown in
the per-agent page header, as the page favicon, and uploaded to the
the swarm UI's agent card, as the page favicon, and uploaded to the
agent's Forgejo profile avatar (via the `forge-avatar-sync` boot
unit) and Matrix profile avatar (set by `hive-matrix-daemon` over its
live Client). Commit the SVG next to `agent.nix` in the config repo
@ -73,8 +73,8 @@ services.hyperhive.agent.dashboardLinks = [
];
```
Declares extra navigation links that appear in the per-agent page
header alongside the built-in forge / config / container links. Each
Declares extra navigation links that appear in the hive dashboard's agent row
alongside the built-in stats and screen links. Each
entry has:
| Field | Required | Description |

View file

@ -171,9 +171,9 @@ addition to the broadcast channel and the events history. Variants:
The harness flips state at the relevant transitions
(`set_state(Thinking)` before `drive_turn`, `set_state(Idle)`
after; `set_state(Compacting)` around an idle operator compact in
`turn::run_pending_compact`). Exposed via `/api/state.turn_state` +
`turn_state_since` (unix seconds); the agent page renders this rather
than deriving from SSE events.
`turn::run_pending_compact`). Published to the swarm queue as `turn_state` +
`turn_state_since` (unix seconds), which the swarm UI renders rather
than deriving from the terminal rows.
## Tool envelope

View file

@ -1,325 +1,43 @@
# Per-agent page: header, live view and endpoints
# Per-agent web server: stats, screen and endpoints
The page each agent's harness serves: header, live view, side panel, actions,
its endpoints and the stats page. The operator's overview is
[the agent page](../../2-handbook/agents/web-page.md).
Two fixed-position layers frame a full-viewport terminal: a header and
scrollable main content — plus a slide-in side panel for flyouts and long
content. The page has no message box: to write to an agent, use the swarm
UI's terminal.
## Header
Preact component tree (`Header.tsx` + `StatusChips.tsx` +
`MetaNav.tsx` + `HeaderPill.tsx`, wired together in `Root.tsx`) — see
`frontend/packages/agent/src/components/`. This section describes the
rendered component tree: every element is Preact component output.
**Fixed-overlay header** (`<header class="agent-header">`): frosted
glass — `backdrop-filter: blur` lets scrolled terminal rows show
through. Measures its own rendered height via `ResizeObserver`
(`Header.tsx`) and writes it to a CSS custom property the content
below reads for its offset, so content never overlaps the header
regardless of how many rows of badges/pills wrap onto an extra line
at a given viewport width. Two columns:
<!-- vale write-good.Passive = NO -->
- **Agent icon** (`<img class="agent-icon">`): fixed-size square
identity anchor — `width: 5em; height: 5em` with explicit pixel
sizing so the `<img>`'s intrinsic (large) dimensions don't push
the parent flex container open via `align-items: stretch`-driven
height feedback. Falls back to the dimmed hyperhive mark
(`/favicon.svg`) on load error (`/icon` 404s when the agent has no
`services.hyperhive.agent.icon` override — there is no server-side default image).
- **Main column** (`.agent-header-main`, `Header.tsx`): two rows —
title (`◆ <label> ◆`) and, when set, the "swarm / hive" identity
line. Nothing else lives here; both rows are short, fixed-shape text
that doesn't wrap in practice, so this column's height stays stable
regardless of how many badges or pills are showing (a design
correction mid-review — the first pass put the variable-width
content here instead, which is exactly the kind of thing the
`ResizeObserver` measurement above exists to catch even when a
layout choice reintroduces it).
- **Pills cluster** (`.agent-header-pills`, right-aligned): status
badges (`StatusChips.tsx`) and flyout triggers together in one row,
so the header reads as one identity zone + one status/actions zone:
- **Status badge**, one badge for liveness and turn state: `● alive`
(green) / `⊘ rate limited` (red) / `◌ needs login` / `◌ logging in` /
`○ offline` / `… connecting` / `💤 idle` / `🧠 thinking` /
`📦 compacting` / `… booting` + age suffix, or paused. Selecting it
opens a menu: `⏸ pause` / `▶ resume` (via the same hive-c0re-owned
`/api/pause/<name>` / `/api/resume/<name>` endpoints the dashboard
uses; pausing needs a write this unprivileged process can't make
directly), `■ cancel turn` (only while a turn is running),
`↻ new session` and `🔓 logout`. Cancel turn, new session and logout
need a second selection to confirm.
- **Model and effort badges** (`model · <name>`, `effort · <level>`):
display only. Each tooltip says where the value comes from
(`state.model_source` / `state.effort_source`: set on the swarm,
agent.nix, an existing `hyperhive-model` / `hyperhive-effort` file, or
the built-in default); the model's also says what the last turn
resolved it to. Both are set on the swarm: the swarm UI's agents page,
or `swarmctl agent inference set`
([`inference.md`](../swarm/inference.md)).
- On an ACP agent each badge shows the session's own value when it
doesn't offer the requested one. The effort badge is hidden
(`state.effort` is `null`) until the first turn has attached a
session, when the model offers no effort levels, and while a newly
set model waits for the next turn, since the levels come with the
model.
- **Ctx / cost badges**: `ctx · 142k` (last inference's prompt size,
tooltip shows % of context window) / `cost · 1.3M` (cumulative
tokens billed across every inference in the last turn).
- **Inbox / todos pills** (`📬 inbox · N` / `📋 todos · N`): hidden
when empty; selecting it opens the matching flyout in the side panel.
- **Profile avatar**: the signed-in user's initial, opening a popover with
their name and links to authelia's settings and sign-out pages, as on the
dashboard (`AgentUserMenu.tsx`). It shows only behind the gateway, where
the page shares the dashboard's origin and session; opened on the agent's
own port there is no sign-in and no avatar. The name comes from the
dashboard's `/api/whoami`, authelia's URL from the dashboard's
`/api/state`.
- **Links badge** (`🔗`): opens a popover listing `↑ dashboard`
(back-link to the host dashboard, `${dashboardBase}`)
followed by this agent's `agent_links()`-sourced navigation (stats,
screen when VNC is enabled, any `services.hyperhive.agent.dashboardLinks`
extras) — all as real `<a>` elements, not a `Dropdown`-style
command list, so ctrl/middle-click and "copy link address" keep
working. Each `AgentLink.kind` resolves differently: `container` →
same-origin path; `external` → already absolute. Same source
(`GET /api/state`'s `links` field) also feeds
`DashboardState.links` for the dashboard card's icon strip —
`agent_links()` in hive-agent is the single source of truth for
both. The dashboard link lives in this 🔗 popover. `cancel turn`,
`new session` and `log out` are rows of the state badge's menu, each
with a click-again confirm (see Actions below).
<!-- vale write-good.Passive = YES -->
Values throughout come from `GET /api/state`'s cold-load snapshot,
kept in sync afterwards by the SSE stream (see Live view below) —
`qualified_label`
(the hive-qualified `name@domain` form, used for the browser tab title
so two tabs from different hives are distinguishable; the header's own
`◆ <label> ◆` stays short).
## Main content
**Main content** (`<main class="agent-main">`): fills the viewport
and scrolls behind the fixed header + footer.
<!-- vale write-good.Passive = NO -->
- `#status` overlay: empty when online; shows the login form / OAuth
URL when `status` is `needs_login_*`. The OAuth code input is
`type="password"` with a `👁 reveal` toggle that flips it back to
`text` on press so the operator can sanity-check the paste before
submit — avoids accidental on-screen token exposure to
shoulder-surfers or screenshots. `autocomplete="one-time-code"`
is the semantic value for OAuth codes (per WHATWG): browsers may
silently ignore `autocomplete="off"` on `type="password"`, but
browsers honour `one-time-code` and suppress the "save password
for this site?" prompt that would otherwise fire on submit.
- Terminal-wrap: live event tail (sticky-bottom autoscroll +
`↓ N new` pill when not at bottom). The pill is **anchored in
`.agent-main`**, not in `log.parentElement = .terminal-wrap`:
`.terminal-wrap` applies `backdrop-filter: blur` for the frost
effect, which creates a CSS stacking context — anchoring the
pill inside that context would confine its `z-index` below the
fixed header in the root stacking context, and it'd never
float. `.agent-main` has no backdrop-filter (no stacking-context
creators), so the pill's `z-index` reaches the root and properly
composites above the header. Geometry is unchanged —
`.agent-main` and `.terminal-wrap` both `inset: 0` fill the same
area.
<!-- vale write-good.Passive = YES -->
## Side panel
**Side panel** (slide-in from right): singleton shared with the
dashboard's side panel shape. Carries inbox and todos flyouts (opened
via the header pills) as well as long content (file previews, diffs,
journald logs). Inbox flyout: unread messages addressed to this agent
(`acked_at IS NULL`, newest-first, up to 30); reply messages indented
with `↳ reply ·` in amber. A `✓ mark all read` button appears in the
flyout header when the inbox is non-empty; selecting it confirms then
POSTs cross-origin to the core dashboard's `POST
/api/agent/{name}/mark-all-read`, which acks all pending messages for
this agent so the harness won't receive wake-prompts for them. A `{
marked: N }` pill surfaces the count. After the drain the inbox list
empties on reload (the filter is `acked_at IS NULL`, so drained
messages disappear). Todos flyout ("loose-ends v2"): the harness-local
todos other subsystems push at this agent (`GET /api/todos`) — matrix,
forge, and bash are the built-in producers, but any user-configured MCP
server can push its own via the same in-agent socket. Each row shows the
producing subsystem, an
optional source label, a summary, and age. A checkbox per row plus a
select-all / select-none / `✓ mark done` bulk row above the list POSTs
the checked ids to `POST /api/todos/mark-done`, which dismisses them
from the harness-local store (same effect as `cancel_loose_end(kind:
"todo")`, just from the web UI instead of the agent's own tool calls).
If the todo store errors or doesn't answer for any id, the endpoint returns
500 naming how many ids failed, and the panel shows `failed: …` instead of
`✓ marked done`. The calls share one 3-second deadline, so a stalled store
gets its 500 after about 3 seconds however many ids you check; ids not
answered by then count as failed. A request with more than 200 ids gets a 400.
## Live view
Each agent runs an `events::Bus`: a `tokio::sync::broadcast<LiveEvent>`
plus a sqlite-backed history at `/harness/hyperhive-events.sqlite`.
The harness emits `TurnStart { from, body, unread }`,
`Stream(value)` (one per parsed stream-json line), `Note`,
`TurnEnd { ok, note }`. Each event also carries a `ts` (unix
seconds) — a flattened sibling of the event tag on both the live
SSE frame and the replayed history rows. The web UI:
- fetches `GET /events/history` on page load and replays the last
2000 events (oldest first);
- then subscribes to `GET /events/stream` (SSE) for live tail;
- shows a granular state badge above the terminal, driven
authoritatively from `/api/state.turn_state`. SSE turn_start /
turn_end still flip the badge instantly between renders;
- terminal-themed: phosphor mauve glow, Crust bg,
backdrop-filter blur, row fade-in slide-up.
The backfill/live-tail dedupe, sticky-bottom autoscroll, and "↓ N
new" pill are the shared terminal-pane mechanics described in
[Shape](../web-ui/shape.md#shared-terminal-pane) — this page's log is one
instance of that same factory.
Per-stream rendering (see [`docs/4-implementation/web-ui/terminal-rendering.md`](../web-ui/terminal-rendering.md) for
the full row taxonomy and dispatch logic):
- `Stream` `tool_use` →
- `Write` / `Edit`: collapsed `<details>` with a +/- diff body
(`-` lines from `input.old_string`, `+` lines from
`input.new_string` or every line of `input.content`).
Summary carries the path + line counts.
- others (`Read /path`, `Bash $ cmd`, `mcp__matrix__send_dm →
iris: "..."`, etc.): flat one-line per-tool format with
per-tool salient-arg extraction (`fmtToolUse`).
- `Stream` `tool_result` short → flat `← ...`; long → collapsed
`<details>` `▸ ← Nl · headline` (select to expand full body).
- `Stream` `thinking` → `.thinking` row with a `💭 thinking …`
indicator.
- `Stream` `system` → handled by subtype: `plugin_install` and
`compact_boundary` emit muted notes; `commands_changed` emits an
expandable details row listing slash commands; `thinking_tokens`
updates a single in-place `🧠` counter; `init`, `result`, and
`rate_limit_event` drop silently (noise / used elsewhere); other
subtypes → muted `⚙ <subtype>` note.
- `Note` → `· text`.
- `TurnStart` → `◆ TURN ← <from>` with the wake-prompt body; a
muted `· HH:MM:SS` time suffix from the event `ts`.
- `TurnEnd` → `✓ turn ok` / `✗ turn fail — note`, with a
`· HH:MM:SS · <duration>` suffix (duration = end − the paired
turn-start), triggers a `refreshState()`. The time suffix is
guarded on a numeric `ts`, so rows degrade cleanly when absent.
## Actions
The state badge's menu carries the actions on the agent's claude:
- `cancel turn` — `POST /api/cancel` → SIGINT to the turn's claude and every
command it started (its process group), emits a Note. On an ACP agent
it sends the agent `session/cancel` instead, and SIGINT if the turn
hasn't ended 10s later. Offered while the state is `thinking`.
- `new session` — `POST /api/new-session` (confirms first).
Arms a one-shot on the Bus; next turn runs without
`--continue`, dropping the resume session entirely.
- `log out` — `POST /api/logout` (confirms first). Wipes OAuth
credential files, parks the agent in `needs_login`, and preserves
session history (`~/.claude/projects/`).
The agent's `compact` MCP tool sets the deferred `Bus::request_compact()` flag and
returns immediately. The harness runs the `/compact` at the next turn
boundary (end of the in-flight turn, or `turn::run_pending_compact` when
idle); output streams into the live panel, which ends with a `/compact done`
or `/compact failed: …` note. It works mid-turn, not only when idle.
What each agent's harness serves on its own port: the stats page, 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
Successful POSTs return 200 (no 303 redirects). Error responses
use semantic status codes: **400** for missing/malformed input
(`/api/todos/mark-done` with no todo ids), **500** only for genuine
server/transport failures. A queued `/compact` never conflicts: it
runs at the end of the current turn. The matching
mutations fire `LiveEvent` variants on the per-agent bus, so the
client doesn't refetch `/api/state` on submit — the SSE stream
delivers the new state faster anyway.
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.
- `POST /api/cancel` — SIGINT the in-flight claude turn and the
commands it started. Emits a `LiveEvent::Note`.
- `POST /api/new-session` — arm a one-shot for the next turn to
drop `--continue`. Emits a `LiveEvent::Note`.
- `POST /api/logout` — three-step teardown that re-uses the
existing `wait_for_login` resumption path:
1. SIGINT any running claude (matches `/api/cancel`'s pattern —
idempotent no-op when nothing is running) so the credential
wipe doesn't race a mid-API-call turn.
2. Delete only the OAuth credential files
(`.credentials.json` + `mcp-needs-auth-cache.json` under
`~/.claude/`). **Preserves** session history files
(`projects/<hash>/*.jsonl`), sessions, shell-snapshots,
plans, settings, telemetry, and the dir itself, so
`claude --continue` keeps working after a fresh login.
⚠️ Deleting the whole `~/.claude/` directory instead breaks
session continuity — logout must stay narrowed to just the
credential files.
3. Flip `LoginState::NeedsLogin` + emit a `LiveEvent::Note`
naming the files it just deleted, then emit
`needs_login_idle`. The turn-loop's next iteration parks
into `wait_for_login`, which snapshots the credential dir
(now missing the wiped files) and resumes when a fresh
credentials file appears (a login from the swarm UI stores one,
and the agent installs it).
Always returns 200 with a body describing what happened — it
folds per-file errors into the response + the Note so the
operator sees them in the live panel rather than as an HTTP
error. Missing files (already logged out) count as
idempotent.
- `GET /api/state` — cold-load snapshot (`StateSnapshot`) consumed by
the frontend (`useAgentState.ts`) on page load. Includes `turn_state`,
`qualified_label`,
`model`, `model_source`, `effort`, `effort_source`, `links`, and
other fields described inline throughout this document. All
subsequent state updates arrive via SSE.
- `GET /api/state` — `{label, dashboard_port}`: the agent's name, for the stats
and screen pages' titles and the screen's login, and the hive dashboard's port
for their 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 /api/todos` — harness-local todos snapshot (loose-ends v2)
consumed by the todos flyout (`refreshTodos` / `buildTodosList`).
See the todos-flyout paragraph above for the producer/subsystem
model and the bulk mark-done row.
- `GET /api/stats?window=24h|7d|30d|all` — time-bucketed turn analytics
`Snapshot` consumed by the `/stats` page. `all` ranges from the
earliest recorded turn with an adaptive bucket width.
- `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 (dashboard container row, this page's own header icon)
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 /events/history` — replay buffer for the terminal.
- `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. A `← agent` back-link in the page
header returns to the main per-agent page. Controls: `⤢ fit` CSS-downscales
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`
@ -354,8 +72,11 @@ credentials arrive from the swarm secret store.
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.
- `GET /` redirects to `/stats`.
Bus events (new vocabulary on `/events/stream`):
Bus events on `/events/stream`:
- `status_changed { status }` — `online` / `rate_limited` /
`needs_login_idle`. Drives the
@ -376,10 +97,8 @@ Bus events (new vocabulary on `/events/stream`):
## Stats page
`GET /stats` is a separate per-agent page (served by the
harness, linked from the per-agent page's `📊 stats →` and from
each dashboard container row). A `← live` back-link in the page
header returns to the main per-agent page. Turn analytics, read-only, from
`GET /stats` is a per-agent page (served by the
harness, linked from each dashboard container row). Turn analytics, read-only, from
`/state/hyperhive-turn-stats.sqlite`. `GET /api/stats?window=
24h|7d|30d|all` returns a time-bucketed `Snapshot`; the page renders
it with Chart.js (bundled into `stats.js` via esbuild — no CDN

View file

@ -45,8 +45,7 @@
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 matching backfill endpoint is `GET /events/history` (last 2000
`LiveEvent`s wrapped in `{ seq, events }`).
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
@ -79,7 +78,7 @@
## Shared terminal pane
The shared terminal factory in `@hive/shared/terminal.js` backs the
per-agent page's scrollable log stream (`#live`). The factory wires up
scrollable log stream. The factory wires up
sticky-bottom autoscroll, a "↓ N new" pill, history backfill, and
SSE replay. Pages register a `kind → renderer` map; unknown kinds
fall through to a JSON-dump note row. The factory ships three row

View file

@ -9,7 +9,7 @@ The operator's overview, with how to reach the UI and who may, is
The signed-in user's avatar sits at the right end of the header on every page.
It opens a menu with the user's name and links to authelia's settings and
sign-out pages; the hive dashboard and the per-agent page have the same menu.
sign-out pages; the hive dashboard has the same menu.
Every dropdown (a form's select, the refresh interval, the history window) opens a
list in the swarm UI's own theme, not the browser's, and works the same in every
@ -173,7 +173,7 @@ the muted debug rows (thinking, coalesced ticks, harness chatter) from every
terminal, the preview and the tabs, and rows already on screen hide or show as
you flip it. It also hides the **components** tab, a page for developers, which
still answers at `/components`. The browser keeps the choice for the swarm UI, apart from the
per-agent pages'.
hive dashboard's.
The menu also has a **solid backgrounds** toggle. It turns the frosted, see-through
surfaces opaque: the header bar, the badges and the terminal panes. It stays off

View file

@ -1,12 +1,12 @@
# Per-agent terminal: row taxonomy (as built)
# Agent terminal: row taxonomy (as built)
The per-agent web UI's live pane renders one row per `TermMsg`
An agent's terminal in the swarm UI renders one row per `TermMsg`
(`hive-agent/src/term_msg.rs`): `{ts, icon?, level: debug|info|warn|error,
summary, body?, body_format?: markdown|diff, coalesce_key?}`. Classification
(icon, summary text, whether a tool call gets an expandable body) happens
server-side, once — `term_msg.rs` + `stream_enrich.rs` — and both
`GET /api/events/history` and `GET /api/events/stream` serve it identically
as `TermEnvelope { seq?, msgs: TermMsg[] }` frames
server-side, once — `term_msg.rs` + `stream_enrich.rs` — and the swarm queue's
terminal rows and `GET /events/stream` carry it identically. The stream wraps
rows as `TermEnvelope { seq?, msgs: TermMsg[] }` frames
(`hive-agent/src/web_ui/stream.rs`).
`ts` is ISO 8601 UTC (`2026-09-13T12:35:03Z`) and is the **source event's**
@ -53,8 +53,8 @@ that motivated the change.
The settings menu's "hide developer details" toggle (`getHideDebugPref()`,
`@hive/shared/prefs.js`) skips `debug`-level rows entirely rather than
muting them further — client-side only, no reload. The per-agent page and
the swarm UI both have the toggle, as one shared row
muting them further — client-side only, no reload. The swarm UI and the hive
dashboard both have the toggle, as one shared row
(`@hive/shared/hide-debug-setting.js`). Each browser origin keeps its own
setting. A `debug` row follows the toggle as it changes, so rows already
on screen hide or show at once, not only the rows that arrive after it.

View file

@ -86,7 +86,7 @@ One agent: its entry in the agent list, state, config and page. Start at
[`2-handbook/agents/persistence.md`](2-handbook/agents/persistence.md).
- **Who can do what to whom — the agent list and privilege?** →
[`2-handbook/agents/agent-permissions.md`](2-handbook/agents/agent-permissions.md).
- **What does an agent's own page show?** →
- **What does an agent's own web server offer?** →
[`2-handbook/agents/web-page.md`](2-handbook/agents/web-page.md).
- **Agent trust model, prompt-injection threat model, credential
isolation?** → [`2-handbook/agents/security.md`](2-handbook/agents/security.md).
@ -207,7 +207,7 @@ Nothing of it sits in this tree.
[`swarm-ui`](4-implementation/web-ui/swarm-ui.md).
- **What's on each tab of the hive dashboard?** →
[`dashboard`](4-implementation/web-ui/dashboard.md).
- **What does an agent's own page show, in full?** →
- **What does an agent's own web server serve, in full?** →
[`agent-page`](4-implementation/web-ui/agent-page.md).
### Crate reference