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
78 lines
2.9 KiB
Markdown
78 lines
2.9 KiB
Markdown
# 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`](../agent-lifecycle/approvals.md) — full approval flow, kinds,
|
|
helper events (`approval_resolved`), flake.lock
|
|
validation.
|