78021ce982
Apply contraction fixes across ~40 doc files (setup, integrations, lifecycle, networking, scheduler, swarm, tools, trust-boundary, UI, etc.). Skipped 14 hits: - 10 where words appear in ALL CAPS for deliberate emphasis (is NOT, do NOT, etc.) - 4 where text could not be safely located due to markdown formatting or column position Applied via systematic scan with checks for fenced code blocks, inline code spans, and intentional caps. Preserves sentence-initial capitalization throughout.
83 lines
3.1 KiB
Markdown
83 lines
3.1 KiB
Markdown
# Lifecycle and approvals tools
|
|
|
|
Two tool groups govern agent lifecycle management and config changes.
|
|
Both are scoped to **direct children only** (topology-enforced: the
|
|
server rejects any name that's not a direct child of the calling
|
|
agent per `topology.json`). Privileged agents (e.g. ruth) may operate
|
|
on any sub-agent — the topology scope applies to all others.
|
|
|
|
## `lifecycle` tool group
|
|
|
|
No operator approval required. Direct children only.
|
|
|
|
### `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 all **descendant** containers (children + their subtrees) with
|
|
running status. Topology-scoped to descendants only.
|
|
|
|
## `approvals` tool group
|
|
|
|
Config changes and new-agent spawns route through the operator
|
|
approval queue. Direct children only (topology-enforced).
|
|
|
|
### `request_init_config(name, description?)`
|
|
|
|
Step 1 of spawning a new direct child agent. Queues an `InitConfig`
|
|
approval; on operator approve, hive-c0re seeds the proposed config
|
|
repo at `/agents/<name>/config/agent.nix` with a default template and
|
|
delivers a `config_ready` system event. Then edit `agent.nix`, commit,
|
|
and the operator **spawns** the agent (the dashboard `◆ R3QU3ST SP4WN`
|
|
button / `Spawn` approval, routed via `HostRequest::RequestSpawn`),
|
|
which creates the container from that config.
|
|
|
|
Subsequent config changes 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`.
|
|
|
|
Fails if a proposed config repo for `name` already exists.
|
|
`name` is ≤ 9 characters.
|
|
|
|
### `request_update_meta_inputs(inputs?, description?)`
|
|
|
|
Queue an approval to run `nix flake update [inputs...]` on the meta
|
|
flake. Pass specific input names (e.g. `["bitburner-agent"]`) or omit
|
|
/ pass `[]` for all inputs. Returns immediately; the lock update runs
|
|
on operator approval.
|
|
|
|
Does NOT trigger container rebuilds — call `update(name)` on affected
|
|
agents after the approval resolves.
|
|
|
|
## Boundary summary
|
|
|
|
| Operation | Requires approval? | Scope |
|
|
| --------------------------------------- | ------------------ | --------------------- |
|
|
| `kill` / `start` / `restart` / `update` | No | Direct children |
|
|
| `list_containers` | No | All descendants |
|
|
| `request_init_config` | Yes (InitConfig) | New direct child only |
|
|
| `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 (`config_ready`, `approval_resolved`), flake.lock
|
|
validation.
|