87970a8c93
Container lifecycle from inside an agent goes away: an agent no longer starts, stops, restarts or rebuilds a container in its subtree, and no longer reads another container's journal. Those are operator actions — the dashboard and hivectl keep their own paths to the same job-queue and hive-priv plumbing, which is why none of that machinery is removed here, only the five MCP verbs and what they alone reached. What went with them: the `Request` variants and `Response::Logs` on the agent socket, the five tool definitions and their arg structs, the four lifecycle handlers plus `handle_get_logs`, and `require_descendant` — the topology guard those five were the only remaining callers of. `ToolGroup::Diagnostics` goes too: `get_logs` was its only tool, so it would otherwise be a grantable group that grants nothing. `lifecycle` stays, now carrying `list_containers` alone. An agent that gets a `needs_update` or `container_crash` helper event has no remedy of its own left, so the system prompt and the docs now send it to the operator instead of to a tool that no longer exists. Refs #4480
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. 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 — 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.
|