vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

swarm-ui: the agents page is one column of cards that open in place

Browse source 
The roster loses its second column and its table view. Selecting a card opens
its details under it as four folded sections: overview, settings, accounts and
the terminal. The status, message and wanted rows, which the card header
already shows, are gone from the details. The terminal page's details dialog
keeps the flat list.
This commit is contained in:
iris 2026-11-01 01:21:43 +01:00
commit 2eaa02e892
1 changed files with 555 additions and 541 deletions
Download patch file Download diff file Expand all files Collapse all files

62
docs/swarm/ui.md
View file

@ -23,7 +23,7 @@ shut. A dropdown inside a dialog opens above the dialog and the dialog doesn't c
| route | what |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/` | the start page: the swarm's name over a digital-rain backdrop, plus a paperclip offering to set up an agent while no `ruth` exists, or her hive declares her destroyed (it opens the create form with `ruth` filled in); the swarm name in the header links here |
| `/agents` | every agent, under a folded **hives** card with the hive directory and each hive's last reported status: status, config PR, wanted state, inference settings, resource caps, permissions; create agents (with their permissions, optionally from an [archetype](archetypes.md)), link forge, matrix and GitHub accounts |
| `/agents` | every agent as a card that opens in place (status, config PR, wanted state, inference settings, resource caps, permissions, accounts, terminal), under a folded **hives** card with the hive directory and each hive's last reported status; create agents (with their permissions, optionally from an [archetype](archetypes.md)), link forge, matrix and GitHub accounts |
| `/agents/<name>/terminal` | one agent's live terminal |
| `/agents/<name>/subagents/<subagent>/terminal` | one of that agent's subagents' live terminal |
| `/reports` | two folded cards, each read only once opened: the **alerts** the swarm's Grafana holds now, the firing ones, with a button for the pending, no-data and error ones and a link to Grafana's own alert list; read through the controller with a Viewer service-account token, and a cross-repo **issue report** |
@ -53,9 +53,31 @@ the code back. The credentials go to the agent through the secret store
([`claude-login.md`](claude-login.md)). The agent's own web UI login still
works too.
### The agents page
`/agents` is the hives card, then one column of cards, one per agent. A card's
header shows its icon, name, freshness, the status message and the **wanted**
menu (up, offline, paused, destroy), and a **login needed** badge with a
**log in** button when its claude has no session. Select the header to open the
card in place; select it again to close it. Several cards can be open at once,
and a card stays open across the page's refresh, but not across a reload. The
filter bar above the cards filters by name, hive, status, message, wanted state
and config PR.
An opened card has four sections, each folded except **overview**, and each
reads nothing until you open it:
- **overview**: the agent's turn state, context and cost, its hive, and its open
config PR.
- **settings**: inference, instructions, resource caps, permissions and allowed
domains, each with its own editor (described below).
- **accounts**: the agent's linked accounts, and the menu that links another.
- **terminal**: the live terminal with its message box, and the agent's
subagents under it (next section).
### Agent and subagent terminals
An agent's detail panel on `/agents` shows a small live preview of its
An opened agent card on `/agents` shows, in its **terminal** section, a small live preview of its
terminal, and below it the agent's **subagents**: every subagent the swarm
queue holds terminal rows for from the last 24 hours. Picking one shows its
terminal in the same preview, and **expand** opens it in its own tab, as it
@ -113,7 +135,7 @@ with no icon keeps the hyperhive mark.
The tab also has an agent badge, with the agent's icon and name, ahead of the
connection badge. It opens the agent's details in a popover under the badge:
the same status, state, wanted state, inference settings, resource caps, permissions, allowed domains and linked accounts as the
panel on `/agents`, without the terminal preview. The popover doesn't dim the
opened card on `/agents`, without the terminal preview. The popover doesn't dim the
page. Selecting outside it, or Escape, closes it. From the keyboard, opening a
popover moves focus into it, and Escape puts focus back on the badge. The filter
popovers on table headers work the same way. You can stop or pause the
@ -536,7 +558,7 @@ text stays.
### Inference settings
The agent's detail panel shows its model and effort under **inference**, each
An opened agent card shows, in its **settings** section, its model and effort under **inference**, each
with where it comes from: the swarm, its agent.nix, its own pick, or the
default. Below them are the subagent model list the swarm sets, or "its own"
when it sets none, and the subagent cap, which reads "no cap" when unset.
@ -544,13 +566,13 @@ when it sets none, and the subagent cap, which reads "no cap" when unset.
stores; saving does a `PUT /api/agents/{agent}/inference` of
the whole value. A field you leave empty stays out of it, so the agent keeps
its own value for that field; an empty max subagents is no cap. **clear the swarm's setting** sends the `DELETE`.
The panel reads `GET /api/agents/{agent}/inference`; before the agent's first
The card reads `GET /api/agents/{agent}/inference`; before the agent's first
report reaches the controller, it shows the swarm's stored values only.
[inference](inference.md) describes the settings themselves.
### Editing an agent's instructions
The **instructions** row of an agent's detail panel has an **edit** button. It
The **instructions** row of an opened agent card's **settings** has an **edit** button. It
opens `AGENTS.md`, the file the agent reads its instructions from, in a plain
text box. The text is the copy the agent last published, so the box still
opens for a stopped agent, but **save** needs the agent running.
@ -566,7 +588,7 @@ dialog keeps an unsaved edit for the next time you open it.
### Resource caps
The agent's detail panel shows its CPU quota and memory max under **resource
An opened agent card shows, under **settings**, its CPU quota and memory max under **resource
caps**. A cap is the swarm's, so it follows the agent to whichever hive runs
it, and it replaces what the hive says for that field. A field the swarm
leaves out shows as the hive deciding it. **edit** opens a dialog with the two
@ -601,14 +623,14 @@ to an agent's traffic from then on.
A saved change isn't instant. The hive reads the caps about every 30 seconds,
and a running agent takes a changed cap at its next spawn or rebuild, so the
row shows the new value before the agent runs under it. The panel reads
`GET /api/agents/{agent}/limits`; when that read fails, the panel shows the
row shows the new value before the agent runs under it. The card reads
`GET /api/agents/{agent}/limits`; when that read fails, the card shows the
reason and a **retry** button. [hivectl](../tools/hivectl.md#per-agent-resource-limits)
sets the hive's own limits.
### Permissions
The agent's detail panel shows what the swarm grants it under **permissions**:
An opened agent card shows, under **settings**, what the swarm grants it under **permissions**:
the default set, none, or a count with one badge per permission. A swarm
grant is the agent's whole set, so it follows the agent to whichever hive runs
it. **edit** opens a dialog with one checkbox per permission the controller
@ -625,14 +647,14 @@ them.
A saved change isn't instant. The hive reads the grant about every 30 seconds
and the agent takes it at its next turn. A change to `manage_root_agent`
restarts the agent after its current turn. The panel reads
`GET /api/agents/{agent}/permissions`; when that read fails, the panel shows
restarts the agent after its current turn. The card reads
`GET /api/agents/{agent}/permissions`; when that read fails, the card shows
the reason and a **retry** button. `swarmctl agent permissions set` sets the
same grant from a shell.
### Allowed domains
The agent's detail panel lists the destinations it may reach through its
An opened agent card lists, under **settings**, the destinations it may reach through its
hive's egress proxy under **allowed domains**, beyond the base list every
agent has: the entries for every agent in the swarm (badge **swarm-wide**) and
the ones for this agent alone (badge with the agent's name). An entry matters
@ -697,7 +719,7 @@ the dialog goes back to step 2 and shows the reason there.
### Settings at creation
Step 4 of the **+ agent** dialog has **resource caps** and **inference**, with
the same fields as the detail panel's editors. Leave the
the same fields as the opened card's settings editors. Leave the
fields empty and the request is the plain name and hive. Fill them and `POST /api/agents` carries them
as optional `limits` and `inference` objects, the same shapes the two `PUT`
routes take. The controller checks them with the `PUT` rules before it queues
@ -737,13 +759,13 @@ name that already holds an account; delete that account first to replace it.
The fourth, the API-key environment, is the exception: a save overwrites what the
store holds.
The agent's detail panel lists its linked accounts under **accounts**, one row
An opened agent card lists its linked accounts in its **accounts** section, one row
per account: kind, name and host. Opening an agent makes one request,
`GET /api/hives/{hive}/agents/{agent}/linked-accounts`, which returns every
account of that agent as names and hosts and never a credential. When the panel
account of that agent as names and hosts and never a credential. When the card
fails to read the accounts, the inference settings, the resource caps or the
permissions, it
shows the reason as text. A list the panel already loaded stays on screen
shows the reason as text. A list the card already loaded stays on screen
beneath the error.
| kind | one row per | name | host |
@ -753,11 +775,11 @@ beneath the error.
| github | `swarm/agents/<agent>/github-token`, if any | `github` | `github.com` |
| `backend` | `swarm/agents/<agent>/backend-env`, if any | `backend-env` | none |
The route names the second kind `forgejo`; the panel shows it as **forge**,
The route names the second kind `forgejo`; the card shows it as **forge**,
the word the link menu uses.
The matrix `main` row is the agent's own account, which the swarm mints;
it carries an **own account** badge. The panel requests the list again when
it carries an **own account** badge. The card requests the list again when
a link dialog closes.
- **link a matrix account** — `PUT /api/hives/{hive}/agents/{agent}/matrix-accounts/{account}`,
@ -805,7 +827,7 @@ request:
swarm-controller removes every version of the entry from the swarm secret
store, and answers 404 when the store holds nothing there. It refuses `main`: the
swarm mints that account and would re-mint it. The panel requests the list
swarm mints that account and would re-mint it. The card requests the list
again after a delete, including a 404 one: the account being already gone is
the end state the delete wanted, so the dialog closes without an error.