Watch

atlas 97edd6baac feat(#2346 ): request_merge_config_pr — submission path for the PR-based config flow

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).

2026-07-11 12:19:52 +02:00

4.4 KiB

Raw Blame History

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)

4.4 KiB Raw Blame History

Lifecycle and approvals tools

lifecycle tool group

kill(name)

start(name)

restart(name)

update(name)

list_containers()

approvals tool group

request_init_config(name, description?)

request_apply_commit(agent, commit_ref, description?)

request_merge_config_pr(agent, pr_number, description?)

request_update_meta_inputs(inputs?, description?)