diff --git a/README.md b/README.md index 38acfd7f2..88d9d9f74 100644 --- a/README.md +++ b/README.md @@ -97,8 +97,9 @@ box it gets: - **knowledge** — the swarm's shared `internal/knowledge` repo, read-only at `/knowledge`, plus hyperhive's own docs in the container. → [knowledge](docs/2-handbook/swarm/knowledge.md) -- **web UI** — a per-agent page behind the gateway: live terminal of the - turn stream, model / effort switching, cancel. +- **web UI** — the swarm UI's terminal for each agent: the live turn stream and a + message box, with `/compact` and `/clear`; a per-agent stats page behind the + gateway. - **GUI** (opt-in, `services.hyperhive.agent.gui.enable`) — a Wayland desktop with screenshot / keyboard / mouse tools, viewable over VNC in the web UI. diff --git a/docs/2-handbook/agents/README.md b/docs/2-handbook/agents/README.md index 56c8bf55e..c28dacc84 100644 --- a/docs/2-handbook/agents/README.md +++ b/docs/2-handbook/agents/README.md @@ -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. diff --git a/docs/2-handbook/agents/web-page.md b/docs/2-handbook/agents/web-page.md index e0c9dfd5f..be9719cdd 100644 --- a/docs/2-handbook/agents/web-page.md +++ b/docs/2-handbook/agents/web-page.md @@ -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). diff --git a/docs/2-handbook/hives/README.md b/docs/2-handbook/hives/README.md index dd191aab0..0f43302f3 100644 --- a/docs/2-handbook/hives/README.md +++ b/docs/2-handbook/hives/README.md @@ -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//` -(or `http://:/` 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//` (or `http://:/` 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). diff --git a/docs/2-handbook/hives/boundary.md b/docs/2-handbook/hives/boundary.md index 99b81d83c..14b9b373e 100644 --- a/docs/2-handbook/hives/boundary.md +++ b/docs/2-handbook/hives/boundary.md @@ -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//`, 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//`, 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 diff --git a/docs/4-implementation/networking/gateway.md b/docs/4-implementation/networking/gateway.md index 9601a10e0..f886e06c0 100644 --- a/docs/4-implementation/networking/gateway.md +++ b/docs/4-implementation/networking/gateway.md @@ -379,7 +379,7 @@ checking file existence): | request | resolved | outcome | | --- | --- | --- | -| `/agent/iris/` | `/index.html` | main agent page | +| `/agent/iris/` | no file match → `@iris_dynamic` | proxied to the agent daemon, which redirects to `stats` | | `/agent/iris/stats` | `/stats.html` | stats page | | `/agent/iris/screen` | `/screen.html` | screen page | | `/agent/iris/static/app.js` | caught by `^~` block first | served with immutable cache | diff --git a/docs/4-implementation/swarm/claude-login.md b/docs/4-implementation/swarm/claude-login.md index 0e4062619..386f9dc28 100644 --- a/docs/4-implementation/swarm/claude-login.md +++ b/docs/4-implementation/swarm/claude-login.md @@ -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 diff --git a/docs/4-implementation/turn-loop/claude-invocation.md b/docs/4-implementation/turn-loop/claude-invocation.md index 85fd7f1c3..9778420a7 100644 --- a/docs/4-implementation/turn-loop/claude-invocation.md +++ b/docs/4-implementation/turn-loop/claude-invocation.md @@ -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//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 diff --git a/docs/4-implementation/turn-loop/config.md b/docs/4-implementation/turn-loop/config.md index 5cade8126..c454a36b5 100644 --- a/docs/4-implementation/turn-loop/config.md +++ b/docs/4-implementation/turn-loop/config.md @@ -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 | diff --git a/docs/4-implementation/turn-loop/mcp.md b/docs/4-implementation/turn-loop/mcp.md index 460afc785..bc21152f0 100644 --- a/docs/4-implementation/turn-loop/mcp.md +++ b/docs/4-implementation/turn-loop/mcp.md @@ -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 diff --git a/docs/4-implementation/web-ui/agent-page.md b/docs/4-implementation/web-ui/agent-page.md index 68c415b6b..1fbb1e380 100644 --- a/docs/4-implementation/web-ui/agent-page.md +++ b/docs/4-implementation/web-ui/agent-page.md @@ -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** (`
`): 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: - - - -- **Agent icon** (``): fixed-size square - identity anchor — `width: 5em; height: 5em` with explicit pixel - sizing so the ``'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 (`◆