docs(web-ui): update dashboard.md for dashboard-state endpoint

Replace the stale GET /api/agent/{name}/links reference with
GET /api/dashboard-state (merged in #1292). The new endpoint is
served by the agent backend and returns DashboardState carrying
links, status_text, rate_limited, ctx_tokens, and
context_window_tokens — all agent-owned fields that were previously
(mis)read by hive-c0re from disk.

Also update the ctx_tokens description: it's now sourced from
DashboardState rather than ContainerView (which no longer carries
ctx_tokens/context_window_tokens).
This commit is contained in:
iris 2026-06-04 20:14:58 +02:00
commit f0271f95e4

View file

@ -403,34 +403,36 @@ fallback fires immediately, skipping the doomed `<url>/icon`
fetch entirely.
- Line 1: agent name (link → new tab), m1nd/ag3nt chip, an
**icon-only nav strip** populated async from the agent backend
(`📊 stats`, `🖥 screen` when GUI is enabled, `⬡ forge profile`,
`↳ agent-configs mirror`, plus any agent-declared
`dashboardLinks` extras). The dashboard JS fetches
`GET /api/agent/{name}/links`, a same-origin passthrough proxy
that forwards the agent's own link list; the agent backend is
the single source of truth. The frontend resolves each
`AgentLink.kind` against a per-agent base URL that depends on
whether hive-gateway is in front (`StateSnapshot.gateway_enabled`,
sourced from the `HIVE_GATEWAY_ENABLED` env the c0re NixOS
module sets when `services.hyperhive.gateway.enable = true`).
Gateway-on (default): `container``/agent/<name>/<url>` (same
origin, gateway proxies to the per-agent harness — TCP or
unix-domain depending on the agent's `HIVE_WEB_SOCKET` opt-in,
see `docs/gateway.md::Per-agent unix-socket upstream`).
Gateway-off (legacy / local dev):
`container``http://<host>:<container.port>/<url>` (direct TCP
fallback). Forge links resolve against `http://<host>:3000`,
external links are already absolute. The same flag drives the
primary agent-name link + favicon fetch (`<url>/icon`), so the
whole row routes through the gateway as a unit.
**icon-only nav strip** plus live agent-owned state, all populated
async from a single `GET /api/dashboard-state` call to the
agent's own backend. The response (`DashboardState`) carries:
`links` (nav strip entries — `📊 stats`, `🖥 screen` when GUI is
enabled, `⬡ forge profile`, `↳ agent-configs mirror`, plus any
agent-declared `dashboardLinks` extras), `status_text` /
`status_set_at` (agent self-reported status), `rate_limited`,
`ctx_tokens` / `context_window_tokens` (context-window badge
data). The agent backend is the single source of truth for all
of these. The dashboard resolves each `AgentLink.kind` against a
per-agent base URL depending on whether hive-gateway is in front
(`StateSnapshot.gateway_enabled`, sourced from the
`HIVE_GATEWAY_ENABLED` env the c0re NixOS module sets when
`services.hyperhive.gateway.enable = true`). Gateway-on (default):
base URL is `/agent/<name>` (same origin, gateway proxies to the
per-agent harness — TCP or unix-domain depending on the agent's
`HIVE_WEB_SOCKET` opt-in, see
`docs/gateway.md::Per-agent unix-socket upstream`).
Gateway-off (legacy / local dev): base URL is
`http://<host>:<container.port>` (direct TCP fallback). Forge
links resolve against `http://<host>:3000`, external links are
already absolute. The same base URL drives the primary agent-name
link + favicon fetch, so the whole row routes through the gateway
as a unit.
**When the container is stopped** (`ContainerView.running = false`),
the host clears live-only fields before emitting the state, so
the dashboard never renders stale data: the badge chain is
replaced by a single muted `■ not running` badge, the nav-strip
fetch is skipped (the agent web server is down), and the
self-reported status text is suppressed. The agent icon goes
straight to the dimmed `/favicon.svg` fallback instead of
the async `dashboard-state` fetch is skipped entirely (the agent
web server is down), so the badge chain is replaced by a single
muted `■ not running` badge, the nav strip is empty, and status
text / rate-limited / ctx badges are suppressed. The agent icon
goes straight to the dimmed `/favicon.svg` fallback instead of
attempting a doomed load from the container's URL. Static fields
`needs_update`, `deployed_sha`, `pending_reminders`, `parent`,
`config` link — remain visible regardless of run state.
@ -465,17 +467,15 @@ fetch entirely.
`opRunning` flag (driving the `pending-running` row class +
spinner) is true when (1) is set OR (2) is in `running` state;
queued entries leave `opRunning` false.
Container name + port, and a `ctx · Nk` chip showing the
agent's last-turn context size (from `ContainerView.ctx_tokens`,
read from the turn-stats sqlite on each `build_all` sweep;
absent until the first turn). The chip colour (green / yellow /
red) is keyed off the model's real context window: `build_all`
resolves the last turn's model against the host's per-model
`contextWindowTokens` config and exposes it as
`ContainerView.context_window_tokens`; the badge goes yellow
≥ 50% and red ≥ 75% of that window (the harness compaction
watermarks). When the window can't be resolved the badge falls
back to fixed 100k / 150k thresholds.
A `ctx · Nk` chip showing the agent's last-turn context size,
populated from `DashboardState.ctx_tokens` (absent until the
agent has completed at least one turn). The chip colour (green /
yellow / red) is keyed off `DashboardState.context_window_tokens`
(the real context window for the model the agent last ran on,
authoritative from the agent side); the badge goes yellow ≥ 50%
and red ≥ 75% of that window, matching the harness compaction
watermarks. When the window value is absent the badge falls back
to fixed 100k / 150k thresholds.
- Line 2: status badges only (no per-card action buttons — actions
moved to the **selection bar**, see below).
- Line 3: drill-in triggers —