97edd6baac
MergeConfigPr approvals had a fully-implemented approve handler (run_merge_config_pr, ff_push_to_main, mark_pr_merged) and dashboard display, but no way to submit one. An agent with the `approvals` tool group calling request_merge_config_pr(agent, pr_number) is the missing piece. What this adds: - RequestMergeConfigPr variant in hive-sh4re AgentRequest + ToolGroup::Approvals - submit_merge_config_pr: fetches PR head sha (the drift-gate reviewed sha), queues a MergeConfigPr row, sets fetched_sha, emits approval_added with pr_number so the dashboard card links to the forge PR - handle_request_merge_config_pr: topology (require_descendant) + tool-group (require_group(approvals)) guards before submit - socket_server/mod.rs: dispatch arm for RequestMergeConfigPr - hive-ag3nt MCP tool: request_merge_config_pr with full description - docs/tools/lifecycle.md: documents the new tool + boundary table row Unlike submit_apply_commit, no flake pre-flight at submission time (eval- verify happens at approval time inside run_merge_config_pr, same as the rest of the merge pipeline). Applied repo must already exist (guard added with a clear error message pointing at request_apply_commit for first-spawn).
110 lines
4.4 KiB
Markdown
110 lines
4.4 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 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_merge_config_pr(agent, pr_number, description?)`
|
|
|
|
Submit an open PR on the agent's `agent-configs/<agent>` forge repo for
|
|
operator review and merge. The PR-based config flow's counterpart to
|
|
`request_apply_commit`: instead of pinning a commit sha from the proposed
|
|
repo, the submitter references an already-open forge PR.
|
|
|
|
hive-c0re fetches the PR head sha at submission time (the "reviewed" sha);
|
|
on operator approval it re-checks for drift, eval-verifies the commit,
|
|
fast-forwards the forge repo's `main` to the reviewed sha, marks the PR
|
|
merged, and rebuilds the agent container. If the PR head moves between
|
|
submission and approval the approve handler aborts — the submitter must
|
|
re-submit.
|
|
|
|
`agent` must be in the caller's subtree. The agent must already be fully
|
|
provisioned (applied repo present); this tool is not for first-spawn.
|
|
Requires the `approvals` tool group.
|
|
|
|
### `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_apply_commit` | Yes (ApplyCommit) | Direct children |
|
|
| `request_merge_config_pr` | Yes (MergeConfigPr) | Descendants |
|
|
| `request_update_meta_inputs` | Yes (MetaUpdate) | Meta flake (global) |
|
|
|
|
## See also
|
|
|
|
- [`docs/approvals.md`](../approvals.md) — full approval flow, kinds,
|
|
helper events (`config_ready`, `approval_resolved`), flake.lock
|
|
validation.
|