a3b672d1d5
swarm-controller's `InitAgentConfigRepo` node already covers config-repo creation, so this deletes a duplicate rather than a capability; old `init_config` rows are skipped by `collect_lenient` with no migration, by operator decision. Refs #4398
2.9 KiB
Lifecycle and approvals tools
Two tool groups govern agent lifecycle management and config changes.
The server scopes both to the caller's own subtree (topology-enforced
per topology.json: a child, a child's child, every agent below them —
plus the caller itself). No privileged class exists to belong to; the
root agent reaches every agent purely because the check is transitive and
everything sits under it.
lifecycle tool group
No operator approval required. The caller's own subtree.
kill(name)
Graceful stop. Container state is preserved; recreating the agent reuses prior config and credentials.
start(name)
Start a stopped sub-agent.
restart(name)
Stop + start in one call.
update(name)
Rebuild: re-applies the current hyperhive flake + agent.nix,
then restarts. Idempotent — safe to call repeatedly. Used in response
to needs_update system events.
list_containers()
List the caller's whole subtree with running status — children, their children, every agent below them. The calling agent is part of its own subtree, so it appears in its own listing; a leaf agent gets a one-row answer naming itself.
approvals tool group
Meta-flake input bumps route through the operator approval queue.
Creating a new agent is not in this group — agents have no tool for
it. A new agent's config repo is scaffolded by the swarm controller's
InitAgentConfigRepo job (POST /api/agents, see
swarm-controller/), and the operator spawns the container from the
dashboard (◆ R3QU3ST SP4WN / Spawn approval, routed via
HostRequest::RequestSpawn).
Config changes on an existing agent go through a forge PR on the
agent's agent-configs/<name> repo (queues a MergeConfigPr approval
on open/update — no MCP tool involved), not a tool call. See
docs/agent-lifecycle/approvals.md.
request_update_meta_inputs(inputs?, description?)
Queue an approval to run nix flake update [inputs...] on the meta
flake. Pass specific input names (for example ["bitburner-agent"]) or omit
/ pass [] for all inputs. Returns immediately; the lock update runs
on operator approval.
Doesn't trigger container rebuilds — call update(name) on affected
agents after the approval resolves.
Boundary summary
| Operation | Requires approval? | Scope |
|---|---|---|
kill / start / restart / update |
No | Own subtree |
list_containers |
No | Own subtree, caller included |
request_update_meta_inputs |
Yes (MetaUpdate) | Meta flake (global) |
See also
docs/agent-lifecycle/approvals.md— full approval flow, kinds, helper events (approval_resolved), flake.lock validation.