From a589acf4d1879063e0ddf268ac8f8a0d7349786d Mon Sep 17 00:00:00 2001 From: iris Date: Thu, 2 Jul 2026 12:18:54 +0200 Subject: [PATCH] docs(web-ui): update C0R3/L0GS/BU1LDS page docs to reflect build queue move R3BU1LD QU3U3 and M3T4 1NPUTS moved from /core.html to /builds.html (the BU1LDS page); the BUILD log tab moved from /logs.html to /builds.html. dashboard.md still described the old 4-tab C0R3 page and 4-tab L0GS page. Changes: - C0R3 page section: update to the actual 2 tabs (K3PT ST4T3 + C0NT41N3R L04D); add pointer to BU1LDS page - Add new BU1LDS page section: R3BU1LD QU3U3 (with all 9 queue kind glyphs + deferred-start parent_id note), M3T4 1NPUTS, BUILD L0GS - L0GS page section: update to actual 3 tabs (AGENT / SYSTEM / AUDIT); remove BUILD sub-tab prose; add pointer to BU1LDS page - Fix two stale 'C0R3 page R3BU1LD QU3U3' refs to 'BU1LDS page' - web-ui.md index: mention BU1LDS alongside C0R3 and L0GS --- docs/web-ui.md | 5 +- docs/web-ui/dashboard.md | 190 ++++++++++++++++++++------------------- 2 files changed, 100 insertions(+), 95 deletions(-) diff --git a/docs/web-ui.md b/docs/web-ui.md index 7e7679ed..e1f40c5a 100644 --- a/docs/web-ui.md +++ b/docs/web-ui.md @@ -13,8 +13,9 @@ This doc has been split for readability. Pick the section you need: per-agent relative paths, `data-async` form pattern, side panel, atomic repaint. - **[Dashboard layout](web-ui/dashboard.md)** — tab contents - (SW4RM, Y3R C4LL, P3RM1SS10NS, SCH3DUL3S) + the standalone C0R3 page - (`/core.html` — the old SYST3M panels), container row, + (SW4RM, Y3R C4LL, P3RM1SS10NS, SCH3DUL3S) + standalone pages + (C0R3 `/core.html`, BU1LDS `/builds.html`, L0GS `/logs.html`, + M4TR1X ACC0UNTS `/matrix-accounts.html`), container row, topology tree, selection bar, approval card, browser notifications, dashboard endpoints + event channel. - **[Per-agent page](web-ui/agent.md)** — header, main terminal, diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md index 90c5e16d..afdb623f 100644 --- a/docs/web-ui/dashboard.md +++ b/docs/web-ui/dashboard.md @@ -126,72 +126,13 @@ in_reply_to, file_refs). Passive / rare-interaction state. No longer a dashboard tab — it's a standalone page reached from the **Core** tile on the H0M3 hub (served at `/core.html`), with the same minimal chrome as `/logs.html`: a `← home` -back-link + a `createTabStrip` sub-tab nav (**R3BU1LD QU3U3** default, -then **M3T4 1NPUTS**, **K3PT ST4T3**, **C0NT41N3R L04D**). The page is its -own esbuild bundle (`core.js`) that cold-loads `/api/state` and subscribes -to `/api/dashboard/stream` for the same live events as the dashboard -(`rebuild_queue_changed`, `meta_inputs_changed`, `meta_update_running`, -`tombstones_changed`). The dashboard keeps the rebuild-queue *state* (it -drives the "building…" badges on SW4RM agent cards) but no longer renders -these panels. - -**M3T4 1NPUTS** — inputs in `meta/flake.lock` the operator can -selectively `nix flake update`, rendered as an indented tree: -every fetched input at every depth (`hyperhive`, -`hyperhive/nixpkgs`, `agent-`, `agent-/mcp-`, …), each -shown once at its shallowest path. `read_meta_inputs` walks the -lock graph with a `visited` set — `follows` aliases and rev-less -nodes are skipped. A `select all / select none` -control sits above the tree. Checking inputs + submitting bumps -the lock in `/meta/` and rebuilds the selected agents in -sequence; each outcome reaches the root agent as a `rebuilt` -system event. `POST /api/meta-update`. While a lock-bump ripple runs, -the panel shows a pulsing "⏳ meta-update running" banner and the -update button is disabled (snapshot field `meta_update_running`, -live event `meta_update_running`). - -**R3BU1LD QU3U3** — pending and recently-completed container -operations: rebuilds, meta-update cascades, and first-spawns. -One operation runs at a time; the worker drains FIFO. Each row -shows a state glyph (`⏸` queued / `▶` running / `✔` done / -`✖` failed / `⊘` cancelled), kind glyph + verb (`↻ rebuild`, -`◆ meta_update`, `✨ spawn`, `🗑 destroy`, `↺ restart`, -`⚡ startup_sweep`, `🔑 perm_change`, `⏹ graceful_stop`, -`▶ start`, `■ stop`), agent name, source -chip (`manual | meta_update | auto_update | startup_sweep | crash_recover | approval` -— green for operator-approved config changes), timing, and an -optional reason / error. Meta-update cascade rebuilds and deferred -start-after-rebuild follow-ups nest under their parent entry -(`parent_id` grouping; `rqe-child` CSS class). -Dedup: re-enqueueing a still-queued op for the same agent -collapses into the existing entry. All timing labels stay live: -running entries tick elapsed seconds every second; queued and -terminal ("done N ago" / "failed N ago") labels tick every 30s so -keyed rows never show stale timestamps as they persist across -`rebuild_queue_changed` snapshots. When the worker has annotated the current phase -a cyan `↳ ` sub-line appears under the main row showing the -in-flight step name (e.g. `↳ meta prepare_deploy` → `↳ nixos-container update` -→ `↳ finalize deploy`). Terminal transitions clear `step` on the -backend so Done / Failed rows don't render stale labels. -Queued entries carry a `✗` cancel button on the right edge; -running / done / failed / cancelled entries don't show it — the -backend refuses cancellation for non-`Queued` rows anyway -(`POST /api/rebuild-queue/{id}/cancel`). Successful -cancel flips the row to `⊘ cancelled` via the next -`rebuild_queue_changed` snapshot. -Cold-loaded from `/api/state.rebuild_queue`; live updates via -`rebuild_queue_changed` snapshot event. - -Below the queue, a **live build-log panel** (`#rebuild-live-log`, -`renderRebuildLiveLog`) streams the currently-running rebuild's output -inline — collapsible, with a live/ok/fail badge and a `↓ raw` download. -It's keyed to the running entry's `build_log_id` and opens one -`EventSource` to `GET /api/build-logs/id/{id}/stream` (the same stream -the L0GS page BUILD tab uses; the stream replays accumulated output on -connect). It lives in its own container outside `#rebuild-queue-section` -so the queue's per-row re-render (rows rebuild as the `step` advances) -never tears down the open stream; it hides when nothing is building and -each row keeps its `logs →` link out to the full L0GS history. +back-link + a `createTabStrip` sub-tab nav (**K3PT ST4T3** default, +then **C0NT41N3R L04D**). The page is its own esbuild bundle (`core.js`) +that cold-loads `/api/state` and subscribes to `/api/dashboard/stream` for +`tombstones_changed`, `capabilities_changed`, and `tool_groups_changed` +(the latter two re-render the stale-perms sub-section when permission +data changes). (Rebuild queue and meta inputs have moved to the BU1LDS +page — see below.) **K3PT ST4T3** — two sub-sections on one pane: @@ -228,6 +169,91 @@ omitted — agents share the host netns, so there is no per-container net counter (per-agent network needs the netns-isolation roadmap in `docs/network.md`). +## BU1LDS page (`/builds.html`) + +The build lifecycle hub — rebuild queue, live build log, meta inputs, +and build log history on one page. Standalone page reached from the +**Builds** tile on the H0M3 hub, same minimal chrome as `/core.html`. +Three sub-tabs: **R3BU1LD QU3U3** (default), **M3T4 1NPUTS**, +**BUILD L0GS**. Its own esbuild bundle (`builds.js`); cold-loads +`/api/state` and subscribes to `/dashboard/stream` for +`rebuild_queue_changed`, `meta_inputs_changed`, `meta_update_running`. +The dashboard tab keeps the rebuild-queue *state* for the SW4RM +card badges without rendering these panels. + +**R3BU1LD QU3U3** — pending and recently-completed container +operations: rebuilds, meta-update cascades, and first-spawns. +One operation runs at a time; the worker drains FIFO. Each row +shows a state glyph (`⏸` queued / `▶` running / `✔` done / +`✖` failed / `⊘` cancelled), kind glyph + verb (`↻ rebuild`, +`◆ meta_update`, `✨ spawn`, `🗑 destroy`, `↺ restart`, +`⚡ startup_sweep`, `🔑 perm_change`, `⏹ graceful_stop`, `▶ start`, +`■ stop`), agent name, +source chip (`manual | meta_update | auto_update | startup_sweep | crash_recover | approval` +— green for operator-approved config changes), timing, and an +optional reason / error. Meta-update cascade rebuilds and +deferred-start follow-ups nest under their parent entry (`parent_id` +grouping; `rqe-child` CSS class — e.g. a `Rebuild` entry groups its +`Start` child, which fires after the profile-swap to free the build +lane before the container boot). Dedup: re-enqueueing a still-queued +op for the same agent collapses into the existing entry. All timing +labels stay live: running entries tick elapsed seconds every second; +queued and terminal ("done N ago" / "failed N ago") labels tick every +30s so keyed rows never show stale timestamps as they persist across +`rebuild_queue_changed` snapshots. When the worker has annotated the +current phase a cyan `↳ ` sub-line appears under the main row +showing the in-flight step name (e.g. `↳ meta prepare_deploy` → +`↳ nixos-container update` → `↳ finalize deploy`). Terminal +transitions clear `step` on the backend so Done / Failed rows don't +render stale labels. +Queued entries carry a `✗` cancel button on the right edge; +running / done / failed / cancelled entries don't show it — the +backend refuses cancellation for non-`Queued` rows anyway +(`POST /api/rebuild-queue/{id}/cancel`). Successful +cancel flips the row to `⊘ cancelled` via the next +`rebuild_queue_changed` snapshot. +Cold-loaded from `/api/state.rebuild_queue`; live updates via +`rebuild_queue_changed` snapshot event. + +Below the queue, a **live build-log panel** (`#rebuild-live-log`, +`renderRebuildLiveLog`) streams the currently-running rebuild's output +inline — collapsible, with a live/ok/fail badge and a `↓ raw` download. +It's keyed to the running entry's `build_log_id` and opens one +`EventSource` to `GET /api/build-logs/id/{id}/stream` (the same stream +the BUILD L0GS tab uses; the stream replays accumulated output on +connect). It lives in its own container outside `#rebuild-queue-section` +so the queue's per-row re-render (rows rebuild as the `step` advances) +never tears down the open stream; it hides when nothing is building and +each row keeps its `logs →` link out to the full build log history. + +**M3T4 1NPUTS** — inputs in `meta/flake.lock` the operator can +selectively `nix flake update`, rendered as an indented tree: +every fetched input at every depth (`hyperhive`, +`hyperhive/nixpkgs`, `agent-`, `agent-/mcp-`, …), each +shown once at its shallowest path. `read_meta_inputs` walks the +lock graph with a `visited` set — `follows` aliases and rev-less +nodes are skipped. A `select all / select none` +control sits above the tree. Checking inputs + submitting bumps +the lock in `/meta/` and rebuilds the selected agents in +sequence; each outcome reaches the root agent as a `rebuilt` +system event. `POST /meta-update`. While a lock-bump ripple runs, +the panel shows a pulsing "⏳ meta-update running" banner and the +update button is disabled (snapshot field `meta_update_running`, +live event `meta_update_running`). + +**BUILD L0GS** — all-agents build log history (moved from `/logs.html`). +Lazy-loaded on first tab activation; auto-refreshes when +`rebuild_queue_changed` fires. Fetches `GET /api/build-logs?limit=30`. +Renders a scrollable list of build entries; each row is a collapsible +button showing status badge (`live` / `ok` / `fail`), agent name, +elapsed duration, build kind, age, and the invocation command line. +Expanding a row fetches the full stdout+stderr via +`GET /api/build-logs/id/{id}`. A live in-progress build shows a `live` +badge with a ticking elapsed-time chip; expanding streams output via +`GET /api/build-logs/stream/{id}` with sticky-bottom auto-scroll +(suspends on manual scroll-up). Deep-link: `?id=N#buildlogs` opens the +entry with that id pre-expanded. + ## M4TR1X ACC0UNTS page (`/matrix-accounts.html`) Operator surface to provision / log in a per-agent **external** matrix @@ -631,31 +657,9 @@ root. All dashboard sub-pages include a `← Home` back-link for navigation. A dedicated log-viewer page (not a tab pane — a separate HTML page), reachable from the Logs tile on the H0M3 hub. Minimal chrome: -a `← home` back link and a four-item sub-tab strip. Tab -routing is hash-based (`#build`, `#agent`, `#system`, `#audit`); default is -`#build`. - -**BUILD sub-tab** — all-agents build log history. Fetches -`GET /api/build-logs?limit=30` on load and on `↻ refresh`. Renders -a scrollable list of build entries; each row is a collapsible button -showing status badge (`live` / `ok` / `fail`), agent name, elapsed -duration, build kind, age, and the invocation command line. -Expanding a row fetches the full stdout+stderr via -`GET /api/build-logs/id/{id}`. - -A live in-progress build shows a `live` badge with an elapsed-time -chip that ticks every second (updated by a `setInterval` on the -row; cleared when the build finishes or the stream errors). Expanding -a live row streams its output via `GET /api/build-logs/id/{id}/stream` -(newline-delimited JSON frames) with **sticky-bottom auto-scroll**: -the stream scrolls to keep the latest output visible as long as the -operator hasn't scrolled up manually; once the operator scrolls up, -new lines append silently at the bottom without jumping. - -The build list auto-refreshes when a `rebuild_queue_changed` SSE -event fires while the BUILD tab is active (2s debounce to let the -backend commit the new row). The `↻ refresh` button triggers an -immediate re-fetch. +a `← home` back link and a three-item sub-tab strip. Tab +routing is hash-based (`#agent`, `#system`, `#audit`); default is +`#agent`. (Build log history has moved to the BU1LDS page — see above.) **AGENT sub-tab** — per-container journald viewer. Two selects: agent name (populated from `GET /api/state`) and unit filter @@ -769,7 +773,7 @@ fetch entirely. (per queue `kind` — e.g. a `start` entry shows `starting…` / `start queued`, `stop` and `graceful_stop` both show `stopping…` / `stop queued`) sourced from `rebuildQueueState` — so the SW4RM tab - shows the same progress visible on the C0R3 page's R3BU1LD QU3U3. + shows the same progress visible on the BU1LDS page's R3BU1LD QU3U3. The row visual splits queued vs running: a **queued** entry shows only the pending-state pill (no row tint, so a long queue doesn't paint half the tab amber); a **running** entry keeps the amber @@ -834,7 +838,7 @@ agent is stale. Banner pulses on each broker SSE event **Build-queue summary banner** — when the rebuild queue has any `queued` / `running` entries, a compact amber banner sits above the container list: `◐ build queue — N running · M queued — view queue →` -(the link goes to the C0R3 page's R3BU1LD QU3U3). It replaces the +(the link goes to the BU1LDS page's R3BU1LD QU3U3). It replaces the old per-transient spinner list; the actual running step for each agent is already shown on its card (transient + in-flight-queue badges), so the top of the tab only needs the at-a-glance summary.