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 is 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 call request_apply_commit with the commit sha — the first ApplyCommit on a freshly-init'd config creates the container.

Fails if a proposed config repo for name already exists. name is ≤ 9 characters. The operator can also spawn an empty agent via the dashboard ◆ R3QU3ST SP4WN button, which routes via HostRequest::RequestSpawn.

request_apply_commit(agent, commit_ref, description?)

Step 2 of spawning (or updating an existing child's config). Submit a commit sha from the child's proposed config repo for operator approval. On approve, hive-c0re rebuilds the container with the pinned commit.

commit_ref must be a 7-40 char hex sha (branch/tag names are rejected — the approval pins the exact commit). agent must be a direct child. Topology-enforced.

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

See also

• docs/approvals.md — full approval flow, kinds, helper events (config_ready, approval_resolved), flake.lock validation.