f0844f6da3
mara on #5170: "dont split caps and perms. its all perms. / dont include the now empty tool groups / nothing set -> default / also add perms to agent creation screen". - hive-sh4re: one `Permission` enum (messaging, meta, inbox, execution, web_tools, manage_root_agent) replaces `ToolGroup` and `Capability`; `lifecycle`/`forge` are gone. `Permission::default_for` is the default for an agent the swarm sets nothing for. - The record is `{ "permissions": [...] }`. Missing key, unset field or no successful read yet = default; `[]` = none; a failed read after a good one keeps the last value. - hive-agent reads its own key every 10s and builds each turn's --tools, --allowedTools and MCP config (rewritten before every turn) from it; the subagent daemon reads it on each start/continue. Agents get a read-only grant on their own key. - hive-c0re restarts an agent only when its manage_root_agent changes. The import now merges meta/capabilities.json and meta/tool-groups.json into one list per agent and deletes both; the "import pending, don't read" decision is `ImportOutcome::read_allowed`, table-tested. - swarm-controller: `GET /api/permissions` (names + default) and an optional `permissions` on `POST /api/agents`, stored before the job is queued. swarm-ui's create-agent form gets a permissions field. - Deleted: HIVE_TOOL_GROUPS and its forward to the subagent daemon, tool_groups.rs, ruth's tool-group seed, the permissions rebuild job (PermPayload/WritePermFile/perm_change), the dashboard permissions tab and its stale-entries panel. Part of #5170.
120 lines
5.7 KiB
Markdown
120 lines
5.7 KiB
Markdown
# Dashboard & Web UI
|
|
|
|
The per-hive dashboard: container state and the rebuild
|
|
queue for one hive. For swarm-wide day to day, see
|
|
[the swarm UI](../swarm/ui.md) instead. If you want implementation
|
|
detail — wire formats, DOM structure, event plumbing — see [Dashboard
|
|
layout](dashboard.md), [Per-agent page](agent.md), [Shape](shape.md),
|
|
and [CSS theme variables](css-vars.md) below; this page only covers
|
|
what you actually do here.
|
|
|
|
## Where things are
|
|
|
|
Everything starts at the **H0M3 hub**, served at `/` — a grid of tiles
|
|
linking to every surface (Dashboard, Flow, Logs, Stats,
|
|
Settings, Core). Every page links back to H0M3, so you're
|
|
never more than one step from the hub.
|
|
|
|
The **dashboard** itself (`/dashboard.html`) is where you'll spend most
|
|
of your time. It's a single page with four tabs:
|
|
|
|
- **4G3NTS** — every agent, live. This is the default tab and the one
|
|
you'll check most.
|
|
- **R3BU1LD QU3U3**, **M3T4 1NPUTS** and **BUILD L0GS** — the build
|
|
lifecycle: the rebuild queue with a live log of whatever is building,
|
|
the meta flake inputs you can bump, and the build log history.
|
|
|
|
Everything else lives on its own page instead, all reachable from the
|
|
H0M3 hub: **Flow** (`/flow.html`, the raw live message stream across
|
|
the whole swarm), **Stats** (`/stats.html`, swarm-wide usage stats), and
|
|
**Core** (`/core.html`, tombstones and container resource use).
|
|
|
|
Each agent also has its own page — a full terminal view of that
|
|
agent's session, reachable by selecting its name anywhere in the
|
|
dashboard, or directly at `/agent/<name>/` (or `http://<host>:<port>/`
|
|
if the gateway isn't in front).
|
|
|
|
## The things you'll actually do
|
|
|
|
**Check on an agent.** 4G3NTS shows every container as a row: name,
|
|
whether it's running, what it's currently doing (a live status pill —
|
|
`rebuilding…`, `starting…`, or similar — while something's in flight),
|
|
and quick links (stats, screen, forge profile). Select the name to open
|
|
its terminal and watch it work in real time.
|
|
|
|
**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 merge them on the forge; the merge deploys the change.
|
|
See [`config-changes.md`](../agent-lifecycle/config-changes.md#config-changes).
|
|
|
|
**Start, stop, restart, or rebuild an agent.** Select one or more
|
|
agents on 4G3NTS (select the icon) and use the selection bar, or use the
|
|
per-agent `⋮` menu on a single row. Rebuilding re-applies that agent's
|
|
current config; use it whenever an agent
|
|
shows as "needs update."
|
|
|
|
**Watch a build.** The dashboard's R3BU1LD QU3U3 tab shows the rebuild queue live, plus a
|
|
streaming log of whatever's currently building. Useful right after
|
|
merging a config change or bumping a flake input.
|
|
|
|
**Grant or revoke a permission.** Not on the hive dashboard: an agent's
|
|
permissions live in the swarm. Set them with `swarmctl agent permissions`,
|
|
or on the swarm UI's create-agent screen when creating the agent; see
|
|
[`process/conventions.md`](../process/conventions.md#permissions).
|
|
|
|
**Read an agent's logs.** Logs aren't in the hive dashboard. Every
|
|
hive ships its agents', daemons' and infra containers' journals to the
|
|
swarm's VictoriaLogs; read them in Grafana's **Explore** — see
|
|
[`swarm/services.md`](../swarm/services.md#logs-victorialogs).
|
|
|
|
**Set up a schedule.** Scheduled prompts are swarm-level: set them with
|
|
`swarmctl schedule` ([`swarm/schedules.md`](../swarm/schedules.md)) or
|
|
on the swarm UI's schedules page ([`swarm/ui.md`](../swarm/ui.md)).
|
|
|
|
## More depth
|
|
|
|
Both the dashboard and the per-agent pages are SPAs sharing one
|
|
skeleton: `GET /` returns a static shell, `/api/state` returns JSON,
|
|
JS renders — no full-page reloads.
|
|
|
|
- **[Dashboard layout](dashboard.md)** — every tab and standalone page,
|
|
in full implementation detail: endpoint shapes, event wiring, exact
|
|
badge-derivation rules.
|
|
- **[Per-agent page](agent.md)** — the per-agent terminal, composer,
|
|
side panel, slash commands, and per-agent endpoints.
|
|
- **[Shape (shared by both)](shape.md)** — the SPA skeleton, SSE
|
|
multiplexing, terminal pane, listener bind, per-agent relative
|
|
paths, `data-async` form pattern, side panel, atomic repaint.
|
|
- **[CSS theme variables](css-vars.md)** — the Catppuccin Mocha custom
|
|
properties declared once in `base.css` and the rule that per-page
|
|
stylesheets reference (never redeclare) them.
|
|
- **[swarm-ui design guide](design-guide.md)** — visual language,
|
|
motion, theming, error-UX, and component-first principles for the
|
|
swarm-level Preact app specifically (not this page's dashboard/agent
|
|
UIs). `/components` on a running swarm-ui is the companion living
|
|
demo of every primitive it references.
|
|
|
|
### Implementation reading paths
|
|
|
|
Task-oriented jumps straight to the relevant section, for when you're
|
|
touching the code rather than using the UI:
|
|
|
|
- **"How does the dashboard SPA stay live without polling?"** →
|
|
[`shape.md`](shape.md) (SSE multiplexing, Worker-death self-heal,
|
|
atomic repaint).
|
|
- **"What does a container row contain?"** →
|
|
[`dashboard.md`](dashboard.md) (Container row, Selection bar).
|
|
- **"What endpoints does the dashboard expose?"** →
|
|
[`dashboard.md`](dashboard.md) (Dashboard endpoints, Dashboard event
|
|
channel).
|
|
- **"How does the per-agent terminal render tool calls?"** →
|
|
[`terminal-rendering.md`](terminal-rendering.md) (full row taxonomy
|
|
and dispatch walkthrough); for a high-level summary see
|
|
[`agent.md`](agent.md) (Per-stream rendering).
|
|
- **"What slash commands does the agent accept?"** →
|
|
[`agent.md`](agent.md) (Terminal-embedded prompt).
|
|
- **"What are the per-agent HTTP endpoints?"** →
|
|
[`agent.md`](agent.md) (Per-agent endpoints).
|
|
- **"Which CSS variable do I use / where are colours defined?"** →
|
|
[`css-vars.md`](css-vars.md) (Palette, single-source `base.css`
|
|
rule).
|