vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(conventions): add Capabilities section parallel to Tool groups

Browse source 
Capabilities were added with the permissions tab but conventions.md only
documented tool groups. Adds a full Capabilities section covering: the
known capabilities table, config storage path, HIVE_CAPABILITIES env var
injection, runtime resolution, operator-only grant constraint, and the
pattern for adding a new capability.
This commit is contained in:
iris 2026-06-02 11:00:17 +02:00 • committed by mara
commit 1e04047059
1 changed files with 40 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

40
docs/conventions.md
View file

@ -316,6 +316,46 @@ or `ManagerServer` in `hive-ag3nt/src/mcp.rs`, add its name to the matching
`ToolGroup::tools()` slice in `hive-sh4re/src/lib.rs`. That's the single
source of truth; `allowed_mcp_tools` reads it at session start.
## Capabilities
Capabilities gate system-level access that goes beyond the MCP tool surface —
things an agent can *access*, not just *call*. Parallel to tool groups but
orthogonal: an agent can have a tool group that registers a tool AND a capability
that allows the underlying resource access.
| Capability | Effect |
|---|---|
| `manage_root_agent` | may lifecycle-manage the root/manager agent via `kill`/`start`/`restart` |
| `read_host_journal` | `get_host_journal` MCP tool is registered + `GET /journal-host` requests are served |
| `query_agent_state` | may call `get_loose_ends` / `CountPendingReminders` targeting non-child agents |
**Config storage** — per-agent capabilities live in
`/var/lib/hyperhive/meta/capabilities.json` alongside `tool-groups.json`.
Format: `{ "atlas": ["read_host_journal"], "root": ["manage_root_agent"] }`.
An absent entry means "no extra capabilities". `render_flake` in `meta.rs`
reads this file and injects `HIVE_CAPABILITIES` (comma-separated
`snake_case` names) into each agent's systemd service env; absent entries emit
no env var so agents without capabilities don't trigger a spurious rebuild.
**Setting capabilities** — the operator sets capabilities via the
C4P4B1L1T13S section in the dashboard's P3RM1SS10NS tab.
`hive-c0re::capabilities::set_caps(name, caps)` is the write path.
After a change `meta::sync_agents` commits the updated file; the next agent
rebuild picks up the new `HIVE_CAPABILITIES` env var.
**Runtime resolution** — at session start the harness reads `HIVE_CAPABILITIES`
and resolves each token to a `Capability` variant. Unrecognised tokens are
logged and skipped. An absent or empty var means no extra capabilities.
**Capability NOT configurable from `agent.nix`** — same reasoning as tool
groups: an agent that could grant its own capabilities via a config commit would
bypass the operator approval gate.
**Adding a new capability** — add a variant to `Capability` in
`hive-sh4re/src/lib.rs` + an arm to `as_str`. Add it to `Capability::ALL` (the
source of truth for the permissions UI columns). Implement the access check in
the relevant handler (`agent_server.rs`, `mcp.rs`, or `dashboard.rs`).
## Async forms
Dashboard + per-agent mutating forms carry `data-async`; a delegated