239 lines
12 KiB
Markdown
239 lines
12 KiB
Markdown
# Agent hierarchy & privileges
|
|
|
|
Every agent has a place in an operator-editable parent/child tree, used
|
|
to scope which agents can manage which others. This doc covers how the
|
|
tree is stored and edited today, the rules that are meant to run on top
|
|
of it once enforcement is finished, and where the manager still gets
|
|
special-cased in the meantime. Tracking issue:
|
|
[hyperhive#361](http://localhost:3000/hyperhive/hyperhive/issues/361).
|
|
|
|
## Where the tree lives
|
|
|
|
Topology lives in the hive-c0re-owned **meta repo**, alongside
|
|
`flake.nix`, at `/var/lib/hyperhive/meta/topology.json`:
|
|
|
|
```json
|
|
{
|
|
"ruth": null,
|
|
"alice": null,
|
|
"bob": "alice"
|
|
}
|
|
```
|
|
|
|
`null` = root-level agent. New agents **default to root** — there is no
|
|
structural manager that everything hangs under. Hierarchy is built
|
|
explicitly: an agent that requests a sub-agent gets a
|
|
requester-as-parent edge written at its `init_config` approval (so
|
|
`bob` above was spawned by `alice`), and the operator can reparent any
|
|
agent, including the bootstrap container (`ruth`) — it's just another
|
|
root. The manager is reparentable like any other agent; there's no
|
|
"structurally root" carve-out. Its privileges live on its MCP socket,
|
|
not its tree position (see *Manager special-casing today* below).
|
|
|
|
### Reparenting
|
|
|
|
- CLI: `hivectl agent <child> set-parent --parent <new>` (or `--root`
|
|
to promote). Exactly one of `--parent` / `--root` is required.
|
|
- Dashboard: `POST /api/topology/set-parent` (form fields `child`,
|
|
optional `new_parent` — absent / empty ⇒ promote to root).
|
|
- Wire: `HostRequest::SetParent { child, new_parent: Option<String> }`.
|
|
|
|
All three go through the same validation, which refuses:
|
|
|
|
- unknown `child` / `new_parent` (typo guard),
|
|
- self-parenting,
|
|
- cycles (a bounded ancestor walk — moving the manager under one of
|
|
its own descendants is the only real safety concern here, and it's
|
|
caught the same way as any other agent).
|
|
|
|
Setting a parent to its current value is a no-op (no disk write). A
|
|
successful change triggers an immediate rescan, so connected dashboard
|
|
viewers see the tree repaint without polling.
|
|
|
|
### Why meta, not per-agent `agent.nix`
|
|
|
|
An agent shouldn't be able to claim a parent without that parent's
|
|
consent, and operator-driven re-parenting shouldn't require touching
|
|
the moved agent's config. Topology IS a system-level concern; meta is
|
|
where system-level facts live.
|
|
|
|
### How `topology.json` gets updated
|
|
|
|
- **Read** — parsed into an agent→parent map; a missing or unparsable
|
|
file degrades safely to "every agent is root" (covers a fresh
|
|
install that hasn't synced yet).
|
|
- **Reconcile** — runs alongside the periodic meta/flake regeneration.
|
|
New agents default to root unless they already carry an explicit
|
|
parent edge from an `init_config` approval; existing entries
|
|
(including operator overrides) are preserved; removed agents drop.
|
|
Agents that are approved but not yet spawned keep their edge too, so
|
|
it survives the gap until the container actually appears.
|
|
- **Inject** — each container's parent (if any) is exposed to its own
|
|
environment as `HIVE_PARENT`, so the harness / system-prompt
|
|
renderer can see it.
|
|
- **Surface** — every rescan re-reads `topology.json` and populates
|
|
`ContainerView.parent`, which the dashboard renders as a tree.
|
|
|
|
See `hive-c0re/src/topology.rs` and `hive-c0re/src/meta.rs`'s module
|
|
docs for the exact call chain.
|
|
|
|
### Current limitation: state-dir visibility lags topology
|
|
|
|
Reparenting today is purely a JSON edit. Only the top-level manager
|
|
(`root`) gets `/var/lib/hyperhive/agents` bind-mounted at `/agents` in
|
|
its container, so sub-agents don't yet see their would-be children's
|
|
state dirs. Once sub-manager bind mounts land alongside capability
|
|
enforcement, reparenting will grow a companion
|
|
umount-old / mount-new / restart-cascade step.
|
|
|
|
## Planned topology semantics (once ancestor-based enforcement lands)
|
|
|
|
| operation | who can do it |
|
|
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
|
| `kill` / `start` / `restart` / `update` (any descendant) | any ancestor |
|
|
| `request_init_config` (spawn a new child) | any agent, child added under self |
|
|
| config change via forge PR (any descendant's config) | any ancestor |
|
|
| `get_logs` (any descendant) | any ancestor |
|
|
| moderate questions / reminders (cancel any open thread of a descendant) | any ancestor |
|
|
| `send` / `recv` routing | parent ↔ same-parent siblings ↔ self ↔ descendants; explicit allow-list for anyone else |
|
|
| `request_update_meta_inputs` (bump meta lock) | root agents only (today: just `manager`) |
|
|
|
|
"Ancestor" walks `ContainerView.parent` chains; cycles are guarded by a
|
|
visited-set at dispatch time (a malformed `topology.json` can't lock
|
|
the dispatcher into a loop).
|
|
|
|
## Manager special-casing today
|
|
|
|
Enforcement of the ancestor rules above isn't fully wired yet, so the
|
|
**manager (`ruth`) still gets some hard-coded special treatment**
|
|
other agents don't:
|
|
|
|
- **Naming/bootstrap** — the manager's broker recipient name, state-dir
|
|
key, and nixos-container name are all `ruth` (container `h-ruth`).
|
|
`hive-c0re` spawns it directly at boot if missing, with no operator
|
|
approval step — every other agent goes through `request_init_config`
|
|
→ approval. Topology-wise, `ruth` is still just another root agent.
|
|
- **Wire-protocol** — the `ManagerRequest::*` operations
|
|
(`RequestInitConfig`; `Kill` / `Start` / `Restart` / `Update`;
|
|
`GetLogs`; `RequestUpdateMetaInputs`) are reachable only from the
|
|
manager's socket flavour today. Planned rule for each is in the
|
|
table above ("any agent, child added under self" for init-config,
|
|
"any ancestor" for lifecycle/logs); `RequestUpdateMetaInputs` stays
|
|
a root-only capability even post-milestone, not a topology rule.
|
|
One exception: `Wake` (inject a `from: <X>` message into the
|
|
caller's own inbox) isn't really privileged — every per-agent daemon
|
|
(e.g. `hive-forge-notify`) needs it, and sub-agents already have the
|
|
equivalent on their own socket.
|
|
- **Storage/mounts** — only the manager container gets
|
|
`/var/lib/hyperhive/agents` bind-mounted RW at `/agents` (so it can
|
|
manage any agent's state dir — config is not 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). Planned: each agent gets RW to `/agents/<descendant>/`
|
|
for just its own subtree — the manager's full-forest RW becomes the
|
|
"root's subtree is everything" case of that same rule. RO `/meta`
|
|
access will be gated on a "meta read" capability; only
|
|
`request_update_meta_inputs` writes `flake.lock`, gated by its own
|
|
capability.
|
|
- **Prompt/tools** — the system prompt uses `<!-- role:agent -->` /
|
|
`<!-- role:manager -->` marker blocks, and a `Flavor::{Agent,
|
|
Manager}` switch picks the MCP tool allow-list claude sees. Both are
|
|
already parametrised on a single flavour value, so the planned
|
|
per-capability-group version (`cap:<group>` prompt blocks + a
|
|
matching tool allow-list) is additive rather than a rewrite.
|
|
- **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.
|
|
- **Scattered ownership checks** — a handful of independent
|
|
manager-only overrides exist across `hive-c0re` today: loose-ends
|
|
visibility (manager sees hive-wide, sub-agents only their own),
|
|
"manager can cancel any question/reminder" overrides on the owner
|
|
check, `destroy` refusing to act on the manager, and crash-watch
|
|
skipping the manager (it auto-restarts via systemd instead of going
|
|
through the crash-watch loop). Each is planned to become an
|
|
ancestor/descendant check instead of a manager-name check — see the
|
|
module docs for `loose_ends.rs`, `operator_questions.rs`,
|
|
`broker.rs`, `reminder_scheduler.rs`, `actions.rs`, and
|
|
`crash_watch.rs` for the current owner-check logic in each.
|
|
|
|
None of the above is a stable interface — treat the module doc
|
|
comments as the source of truth for exactly which checks exist today.
|
|
|
|
## Future work: sub-agents inside the same container
|
|
|
|
When enabled for an agent, it will be able to spawn temporary
|
|
"sub-agents" that run inside its own container — lighter than a full
|
|
nspawn agent. Open questions, not yet wired:
|
|
|
|
- Inherit caps from parent, or take an explicit narrower set?
|
|
- Survive container restart, or always ephemeral?
|
|
- Inbox: separate from parent, or shared?
|
|
- Filesystem: share parent's `/state` RW, or a sub-dir?
|
|
- Identity: distinct broker recipient name, or address the parent?
|
|
|
|
## Harness systemd unit shape
|
|
|
|
One harness serve binary (`hive-agent`, with its `hive-agent-mcp`
|
|
sibling), one shared `nix/agent-modules/` tree, one service unit
|
|
(`systemd.services.hive-agent`) for all agents. There is no separate
|
|
manager service name or role distinction in the harness — privilege
|
|
differences live server-side in the broker socket (which tool groups
|
|
and manager-surface calls each agent receives).
|
|
|
|
`agent.nix` and `ruth.nix` both import the shared `nix/agent-modules/`.
|
|
`ruth.nix` additionally sets forge defaults to suppress the
|
|
subscription/participation firehose so ruth's inbox stays focused on
|
|
direct mentions, reviews, and assignments.
|
|
|
|
### Environment variables set on the unit
|
|
|
|
- `HOME = /home/<userName>` — systemd defaults `HOME` to `/` for
|
|
services without `User=` set; with the per-agent user the harness
|
|
needs the right home so claude finds its bind-mounted `~/.claude/`
|
|
session dir.
|
|
- `HIVE_STATIC_DIR = <mergedDist>` — `tower_http::ServeDir` root for
|
|
the per-agent web UI; merged dist = agent default + every
|
|
`hyperhive.frontend.extraFiles` overlay.
|
|
- `HIVE_ASSETS_DIR = pkgs.hyperhive-assets/share/hyperhive` — set
|
|
directly on the unit, **not** via `environment.variables`, because
|
|
the latter only populates `/etc/profile` which systemd services
|
|
don't inherit.
|
|
|
|
### `PATH` setup (the wrapper-dir trick)
|
|
|
|
```nix
|
|
path = [ "/run/wrappers" "/run/current-system/sw" ];
|
|
```
|
|
|
|
`/run/wrappers` (not `/run/wrappers/bin`) comes first so setuid
|
|
wrappers — notably `sudo` — resolve before bare nix-store binaries; see
|
|
[`docs/gotchas.md`](gotchas.md) ("`systemd.services.*.path` appends
|
|
`/bin` to every entry") for why the trailing `/bin` matters in
|
|
general. It's load-bearing here because the harness runs as the
|
|
per-agent user: without the wrapper dir on `PATH`, `sudo` resolves to
|
|
the non-setuid nix-store binary and every
|
|
`hyperhive.user.passwordlessSudo` grant fails with "must be owned by
|
|
uid 0 and have the setuid bit set."
|
|
|
|
### `serviceConfig` highlights
|
|
|
|
- `ExecStart = pkgs.hyperhive/bin/hive-agent` — same binary for every
|
|
agent.
|
|
- `Restart = on-failure`, `RestartSec = 2` — keeps the harness
|
|
resilient across transient crashes without thundering retries.
|
|
- `RuntimeDirectory = "hive-config"` → `/run/hive-config/` owned by
|
|
`User=`, auto-cleared on stop. The harness writes regenerated
|
|
`claude-{mcp-config,settings,system-prompt}` files there
|
|
(`paths::config_dir`). Deliberately separate from `/run/hive`, which
|
|
the host bind-mounts in root-owned and which holds hive-c0re's
|
|
`mcp.sock`.
|
|
- `User = Group = userName` — drops root inside the container; sudo is
|
|
the explicit escalation surface (`hyperhive.user.passwordlessSudo`).
|
|
|
|
## Cross-references
|
|
|
|
- Milestone: ["Agent privileges and sub-agents"](http://localhost:3000/hyperhive/hyperhive/issues/361)
|
|
- Dashboard render: ["show agent topology in container list"](http://localhost:3000/hyperhive/hyperhive/issues/363)
|
|
- Audit table source: [milestone comment](http://localhost:3000/hyperhive/hyperhive/issues/361#issuecomment-3335)
|
|
- Operator/agent trust boundary (orthogonal axis): [`boundary.md`](boundary.md)
|