97e2a993e3
Read all 62 write-good.Passive hits across the 6 hand-written files in docs/tools/ (bash.md, lifecycle.md, forge.md, hivectl.md, matrix.md, scheduling.md) in context. Excludes forge-cli.md/hivectl-cli.md/ swarmctl-cli.md (57 more hits) -- those are CI-generated from the clap doc-comment strings in hive-forge/hivectl/swarmctl, freshness- checked against the committed markdown, so a fix there has to go in the Rust source and get regenerated -- separate batch. 33 rewritten to active, actor usually already established in the same paragraph or given via a 'by X' clause (the daemon, hive-c0re, hive-forge, hivectl, hyperhive itself, or an established module name like nix/agent-modules/mcp.nix). Several sibling-inconsistency fixes: a passive clause next to an already-active sibling stating the same fact (lifecycle.md's server-scoping sentence, forge.md's clone-derives sentence, hivectl.md's daemon-hashes-passwords sentence, matrix.md's daemon-upserts-a-todo paragraph). 29 left alone: no-X-is-Y / no-X-is-needed invariant idioms, config-state conditionals (whenever/when X is set/configured/given), requirement- list idiom, a false-positive tokenization (vale matching 'are read' inside 'read-only'), definitional facts about CLI/attrset structure with no real actor, hypothetical/counterfactual clauses describing a rejected design alternative, a forward-looking not-yet-real removal, compressed bullet-fragment conventions, and one deliberately-parallel sentence structure left both halves alone to avoid breaking the symmetry. Verified via vale on the 6 touched files, diffed against main's exact baseline (not just the Passive count): write-good.Passive 62 -> 29 exactly, every other category unchanged in count AND location (TooWordy 16, Microsoft.We 1, Microsoft.FirstPerson 1, and the same 4 pre-existing Microsoft.Contractions errors at the same 4 lines).
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.
|
|
The server scopes both to **direct children only** (topology-enforced: it
|
|
rejects any name that's not a direct child of the calling
|
|
agent per `topology.json`). Privileged agents (for example 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 (for example `["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.
|