docs: the agent roster page keeps the operator view and moves the topology detail out
The page says who is on the roster, who may reach whose state and that the manager is a normal agent. How topology.json is read and rebuilt, the wire protocol and the prompt blocks move to 4-implementation/agent-state/roster.md, unchanged, since the code they describe still exists.
This commit is contained in:
iris
mara
parent
02f21940a4
commit
e746ed1888
1 changed files with 156 additions and 121 deletions
126
docs/4-implementation/agent-state/roster.md
Normal file
126
docs/4-implementation/agent-state/roster.md
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
# Agent roster: topology file and manager behaviour
|
||||
|
||||
The hive-local `topology.json`, how it is derived, and what is special about the
|
||||
manager (`ruth`). The operator's overview is
|
||||
[the agent roster page](../../2-handbook/agents/agent-roster.md).
|
||||
|
||||
<!-- 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/` directory's `topology.json`, 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` dir, read-write, at `/agents/<name>/state`; never `config` or
|
||||
`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`](../agent-state/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. The live set is the
|
||||
hive's existing agent containers plus the agent that spawns now; reconcile
|
||||
drops an agent whose config repo exists but whose container doesn't.
|
||||
|
||||
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 that
|
||||
parses. It refuses to write over a file it can't parse and fails
|
||||
instead, so a broken hand edit stays until someone fixes it.
|
||||
|
||||
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/4-implementation/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
|
||||
each other agent's `state` dir bind-mounted RW at
|
||||
`/agents/<name>/state` (so it can manage any agent's state dir; config
|
||||
isn't mounted, since a real config change is a PR from a clone), plus an RO mount for
|
||||
`/meta` (the hive's topology and limits files). Any agent holding it gets the same mounts.
|
||||
- **Prompt** — identical for every container but one paragraph: an agent
|
||||
built from an [archetype](../../2-handbook/swarm/archetypes.md) is told it has no config
|
||||
repo, every other agent is told how to propose changes to its own.
|
||||
- **Tool allow-list** — the MCP tools claude sees come from the agent's
|
||||
permissions alone, the same mechanism for every agent
|
||||
([`docs/4-implementation/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_ treated as an exception: `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.
|
||||
Loading…
Reference in a new issue