738dd1c95b
no behaviour change: a pure move of items and tests into new modules, plus visibility edits (pub(crate)) and path updates in sibling modules that named crate-root items. same routes, same OpenAPI, 561 tests before and after. why: #5470, new features stop landing in one 6.4k-line file by default. files outside swarm-controller/src: docs/agent-lifecycle/agent-roster.md, swarm-ui JobsPage.tsx and AgentsPage.tsx, nix/host-modules/swarm-controller.nix and swarm-grafana.nix hold comments that named main.rs for items that moved.
136 lines
6.6 KiB
Markdown
136 lines
6.6 KiB
Markdown
# Agent roster & privileges
|
|
|
|
<!-- vale write-good.Passive = NO -->
|
|
|
|
Agents are a **flat set**: the `manage_root_agent` permission scopes
|
|
which agents can manage which others.
|
|
|
|
<!-- vale write-good.Passive = YES -->
|
|
|
|
This doc covers what the roster file holds, the map-shaped alternative
|
|
`topology::all_agents` accepts, and what's hard-coded for the manager.
|
|
|
|
## Where the roster lives
|
|
|
|
"The roster" means two different, non-overlapping things depending on
|
|
scope. The [README](../../README.md)'s control-plane row ("`swarm-controller`
|
|
holds the hive directory, the agent roster and the job graph") is the
|
|
**swarm-wide** one: `GET /api/agents` on swarm-controller reads
|
|
straight from the swarm's authelia identity store over
|
|
`swarm-authelia-bridge` (`swarm-controller/src/auth.rs::list_agent_identities`)
|
|
— "every agent the swarm holds an identity for" (`swarm-controller/src/routes/agents.rs`'s
|
|
`get_agents` doc comment). It's authoritative: an agent exists in the
|
|
swarm if and only if it has an identity there, and `swarmctl agent
|
|
create` (or the swarm UI, via `POST /api/agents`) writes that identity
|
|
once, by calling `ensure_agent_identity`.
|
|
|
|
This page is about a different, **hive-local** file: the hive-c0re-owned
|
|
**meta repo**, alongside `flake.nix`, at
|
|
`/var/lib/hyperhive/meta/topology.json`:
|
|
|
|
```json
|
|
["alice", "bob", "ruth"]
|
|
```
|
|
|
|
One entry per agent _this hive_ has state/config for, in name order.
|
|
Unlike the swarm roster, it's a derived cache: the reconcile pass below
|
|
rebuilds it from what the hive observes locally (config repos cloned, containers spawned), and it
|
|
answers a narrower question than "does this agent exist": _which of
|
|
this hive's local agents the `ManageRootAgent` permission's bind-mounts
|
|
should cover._ `topology::all_agents` is the only reader that matters.
|
|
|
|
That reader is a permission boundary: the set it returns is what an agent
|
|
holding the `ManageRootAgent` permission gets bind-mounted (each other
|
|
agent's `state` read-write and `config` read-only; never `harness`). An
|
|
agent holding no permission sees its own dirs and nothing else:
|
|
`ManageRootAgent` is the only grant that reaches another agent's state
|
|
dir. See
|
|
[`persistence.md`](persistence.md)'s _Cross-agent access to state._
|
|
|
|
### Reading the map-shaped format
|
|
|
|
`topology.json` may also be a map of `name → parent | null`; the reader
|
|
accepts that shape and takes its keys as the roster. An empty
|
|
roster costs more than a cosmetic gap: every permission holder loses its
|
|
mounts until the next reconcile pass writes the array form.
|
|
|
|
### Why meta, not per-agent `agent.nix`
|
|
|
|
An agent shouldn't be able to add itself to a set that governs who may
|
|
reach its state dir. The roster IS a system-level fact; meta is where
|
|
system-level facts live.
|
|
|
|
### How `topology.json` gets updated
|
|
|
|
- **Read** — parsed into a set of names; a missing or unparsable file
|
|
degrades safely to "no agents" (covers a fresh install that hasn't
|
|
synced yet).
|
|
- **Reconcile** — runs alongside the periodic meta/flake regeneration.
|
|
Adds newly-spawned agents, drops removed ones. Reconcile keeps agents
|
|
whose config repo exists but that haven't spawned yet, so the gap until
|
|
the container appears doesn't churn the file.
|
|
|
|
No write API and no operator verb reach this file. Reconcile derives it
|
|
from which agents exist, so the next pass overwrites a hand edit.
|
|
|
|
See `hive-c0re/src/agent_config/topology.rs` and `hive-c0re/src/meta.rs`'s
|
|
module docs for the exact call chain.
|
|
|
|
## Hard-coded manager behaviour
|
|
|
|
The **manager (`ruth`)** differs from other agents in naming/bootstrap
|
|
and its socket flavour; its permissions, prompt, tool allow-list and
|
|
state dirs work as for every other agent.
|
|
|
|
<!-- vale write-good.Passive = NO -->
|
|
|
|
- **Naming/bootstrap** — the manager's broker recipient name, state-dir
|
|
key, and nixos-container name are all `ruth` (container `h-ruth`).
|
|
Like every agent it comes from the swarm dashboard or
|
|
`swarmctl agent create`; `hive-c0re` creates nothing at boot.
|
|
Roster-wise, `ruth` is just another entry.
|
|
- **Wire-protocol** — `hive-core-agent-sock`'s unified `Request` enum
|
|
is the same on both socket flavours. Container lifecycle
|
|
ops (kill/start/restart/rebuild) go through the separate host-admin
|
|
socket `hivectl` speaks. `Wake` (inject a `from: <X>` message straight
|
|
into the caller's own inbox) is on this socket too, unprivileged on
|
|
both flavours; matrix, bash and forge don't call it — their
|
|
notifications push a todo on the harness's in-agent socket (see
|
|
[`docs/turn-loop/mcp.md`](../turn-loop/mcp.md#waking-the-agent-from-inside-the-container)).
|
|
- **Storage/mounts** — the `manage_root_agent` permission, which the swarm
|
|
UI's setup assistant creates ruth with, gets a container
|
|
`/var/lib/hyperhive/agents` bind-mounted RW at `/agents` (so it can
|
|
manage any agent's state dir — config isn't authored there, since a
|
|
real config change is a PR from a clone), plus RO mounts for
|
|
`/applied` (diff against what's deployed) and `/meta` (system-wide
|
|
deploy log). Any agent holding it gets the same mounts.
|
|
The operator dashboard's `POST /api/meta-update` is the only path
|
|
that writes `flake.lock`.
|
|
- **Prompt** — identical for every container but one block (below):
|
|
`prompts/system.md`
|
|
carries `<!-- role:agent -->` / `<!-- role:manager -->` marker
|
|
blocks, and `prompt::render` filters for `"agent"` unconditionally,
|
|
manager included ("always `agent` role — there is only one role",
|
|
`hive-agent/src/prompt.rs`'s own module doc). The `role:manager`
|
|
blocks are dead in production, exercised only by a unit test
|
|
(`filter_blocks(SAMPLE, "role", "manager")`). The one block that differs
|
|
is `<!-- config:repo -->` vs `<!-- config:archetype -->`: an agent built
|
|
from an [archetype](../swarm/archetypes.md) is told it has no config repo.
|
|
- **Tool allow-list** — the MCP tools claude sees come from the agent's
|
|
permissions alone, the same mechanism for every agent
|
|
([`docs/turn-loop/mcp.md`](../turn-loop/mcp.md)). Ruth's permissions
|
|
are the default plus `manage_root_agent`, stored for her like any grant.
|
|
- **State dirs** — _not_ special-cased: `HYPERHIVE_STATE_DIR` is
|
|
injected uniformly via `systemd.globalEnvironment` for every
|
|
container including the manager, so all token/state paths resolve
|
|
through it the same way everywhere.
|
|
<!-- vale write-good.Passive = YES -->
|
|
|
|
None of the above is a stable interface — treat the module doc
|
|
comments as the source of truth for exactly which checks exist today.
|
|
|
|
## Cross-references
|
|
|
|
- Milestone: "Agent privileges and sub-agents" (tracked internally)
|
|
- Audit table source: milestone comment (tracked internally)
|
|
- Operator/agent trust boundary (orthogonal axis): [`boundary.md`](../trust-boundary/boundary.md)
|