58 lines
2.4 KiB
Markdown
58 lines
2.4 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.
|
|
|
|
### `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. The swarm controller's `InitAgentConfigRepo` job scaffolds a new
|
|
agent's config repo (`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 — the operator rebuilds affected
|
|
agents after the approval resolves.
|
|
|
|
## Boundary summary
|
|
|
|
| Operation | Requires approval? | Scope |
|
|
| ---------------------------- | ------------------ | ---------------------------- |
|
|
| `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.
|