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

swarm-ui: restructure the agent card into status, terminal, subagents and settings, with badge controls for internet, permissions and allowed domains

Browse source
This commit is contained in:
iris 2026-11-03 23:47:44 +01:00 • committed by mara
commit 5e23734667
1 changed files with 437 additions and 302 deletions
Download patch file Download diff file Expand all files Collapse all files

47
docs/swarm/ui.md
View file

@ -26,7 +26,7 @@ smaller; short confirm dialogs stay short.
| route | what |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/` | the start page: the swarm's name over a digital-rain backdrop with the slug (`hyperhive / we are the wired`, its shaded gradients pulsing in a wave unless reduced motion is on) at the foot, 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 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` | every agent as a card that opens in place (status, terminal, subagents, and settings with permissions, internet, allowed domains and accounts), 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** |
@ -70,18 +70,19 @@ filter card, which also holds the **+ agent** button and the refresh picker,
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:
An opened card has four sections, and each reads nothing until you open it.
**status** and **terminal** start open, the other two folded:
- **overview**: the agent's turn state, context and cost, its hive, links to its
- **status**: the agent's turn state, context and cost, its hive, links to its
profile and its config repo on the swarm's forge (built from the forge entry
of `GET /api/links`; the row stays hidden when the swarm lists none), 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).
- **terminal**: the live terminal with its message box.
- **subagents**: the agent's subagents and their terminal preview (next section).
- **settings**: inference, instructions, resource caps, internet, allowed
domains and permissions, then the agent's linked accounts and the menu that
links another. Internet, allowed domains and permissions show a badge; select
it to open the control that changes it (described below).
### Agent and subagent terminals
@ -148,8 +149,8 @@ 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
opened card on `/agents`, without the terminal preview. The popover doesn't dim the
the same status, state, wanted state and folded **status** and **settings** sections (inference, resource caps, internet, allowed domains, permissions and linked accounts) as the
opened card on `/agents`, without the terminal and subagents. 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
@ -645,19 +646,22 @@ sets the hive's own limits.
### 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
a badge reading the default set, none, or a count. 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
it. Selecting the badge opens a box under it with one checkbox per permission the controller
knows (`GET /api/permissions`), ticked as the grant stands, or on the default
set when the swarm sets none.
Saving does a `PUT /api/agents/{agent}/permissions` of the ticked boxes. A
Each tick saves at once, as a `PUT /api/agents/{agent}/permissions` of the ticked boxes. A
`PUT` replaces the stored list whole, so an unticked box revokes that
permission, and ticking nothing grants nothing. Ticking exactly the default set sends the
`DELETE` instead, as the create form sends no list for it, so the agent follows
the default if it changes. **use the default** sends the `DELETE` too. The
dialog shows a refusal's reason under the boxes and leaves them as you ticked
them.
box shows a refusal's reason under the boxes and puts them back as stored.
The agent's **internet** access is its own row beside it: a badge reading
restricted, log or unrestricted. Selecting it lists the three modes; picking one does a
`PUT` of the mode with the stored permissions beside it.
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`
@ -670,14 +674,15 @@ same grant from a shell.
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
agent has: one badge per source with its count, **swarm-wide** (the entries for every
agent), **this agent** (the ones for it alone) and **automatic**. Selecting a badge
opens the names behind it. An entry matters
to a restricted agent. One with the unrestricted internet flag reaches any
name the proxy's private-range rules leave. **remove** drops one entry;
name the proxy's private-range rules leave. **remove**, beside a name, drops one entry;
**add** opens a dialog with a domain box and a tick for every agent in the
swarm. The tick is off by default, so an entry is for this agent alone.
An entry with the badge **automatic** has no **remove**: the controller keeps
An entry under **automatic** has no **remove**: the controller keeps
it from the host in the agent's stored API-key environment
(`ANTHROPIC_BASE_URL`, or any `*_BASE_URL` variable), so a restricted agent on
another provider reaches it. Saving or removing the environment changes it, and
@ -773,7 +778,7 @@ 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.
An opened agent card lists its linked accounts in its **accounts** section, one row
An opened agent card lists its linked accounts at the end of its **settings** 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 card