From 601cd295e51a32c2694c93a2ce982235ddc2de3d Mon Sep 17 00:00:00 2001 From: damocles Date: Sun, 2 Aug 2026 23:48:53 +0200 Subject: [PATCH] docs: describe the push_todo lifecycle-notice migration --- docs/approvals.md | 51 +++++++++++++++++------------------- hive-agent/prompts/system.md | 9 +++---- 2 files changed, 28 insertions(+), 32 deletions(-) diff --git a/docs/approvals.md b/docs/approvals.md index bdf8a325..ccb8458f 100644 --- a/docs/approvals.md +++ b/docs/approvals.md @@ -132,8 +132,8 @@ without it has nothing of its own to withdraw. `InitConfig` approvals seed a brand-new agent's proposed config repo. On approve, hive-c0re seeds it with a default `agent.nix` template and -sends `HelperEvent::ConfigReady { agent }` to the submitting agent's -inbox via `notify_submitter`. The submitting agent reviews, edits, and +pushes a todo (`push_todo_submitter`) into the submitting agent's +in-container store. The submitting agent reviews, edits, and commits the template; the operator then **spawns** the agent (the `Spawn` approval / `◆ R3QU3ST SP4WN` button), which creates the container from that config. From then on, config changes go through a @@ -626,12 +626,6 @@ root agent. Variants (`hive_sh4re::HelperEvent`): - `ApprovalResolved { id, agent, commit_ref, status, note }` — fired by `actions::approve` + `actions::deny` whenever an approval transitions to its terminal state. -- `Rebuilt { agent, ok, note }` — `auto_update::rebuild_agent` - (covers startup scan + manual `/rebuild` from dashboard) + - the `MergeConfigPr` deploy. -- `Killed { agent }` — admin `HostRequest::Kill` + dashboard - `/kill` + the `Kill` MCP tool. -- `Destroyed { agent }` — `actions::destroy`. - `ContainerCrash { agent, note }` — `crash_watch`: a previously- running container went away with no operator-initiated transient state (Stopping / Restarting / Destroying / Rebuilding) AND no @@ -640,16 +634,6 @@ root agent. Variants (`hive_sh4re::HelperEvent`): lifecycle op finishes between two crash-watch polls and the container shows briefly as "stopped without transient" before the next start). The root agent can `start` it again or escalate. -- `NeedsLogin { agent }` — sub-agent has no claude session yet. - The root agent can't act directly (interactive OAuth); typically flags - the operator. -- `LoggedIn { agent }` — sub-agent just completed login. The root agent - often greets the agent on this event. -- `ConfigReady { agent }` — a new agent's proposed config repo was - just seeded (post-`InitConfig` approval). The root agent can now - edit `/agents//config/agent.nix`, commit the changes, and - hand off to the operator to **spawn** the agent (the `Spawn` - approval creates the container from that config). - `NeedsUpdate { agent }` — sub-agent's recorded flake rev is stale. The root agent calls `update(name)` to rebuild — idempotent, no approval required. @@ -662,20 +646,33 @@ root agent. Variants (`hive_sh4re::HelperEvent`): The recipient responds via `Answer { id, answer }` and the asker sees the matching `QuestionAnswered`. -Optional `sha` field on `ApprovalResolved` and `Rebuilt` carries the -canonical hive-c0re-vouched commit sha. Optional `tag` on the same two -carries the deploy bookkeeping tag — `deployed/` on a successful -build or `failed/` on a failed one, planted by the `MergeConfigPr` -deploy. Both fields are `Option`: `None` on the paths that don't deploy -a new commit (spawn / init_config / meta-update / deny, and +The rest of the original lifecycle notices — `Rebuilt`, `Killed`, +`Destroyed`, `NeedsLogin`, `LoggedIn`, `ConfigReady` — were pure "FYI, +check when convenient" events with no reason to drive an immediate +turn, so they've been migrated off `HelperEvent` onto +`push_todo`/`push_todo_submitter` (see above): `agent_todo_socket` +push instead of a broker message, `subsystem = "core"`, +`key = ":"` for dedup, one free-text `summary` in place +of the old structured fields (`rebuilt_todo_summary` renders +`Rebuilt`'s former `ok`/`note`/`sha`/`tag` into that string). + +Optional `sha` field on `ApprovalResolved` carries the canonical +hive-c0re-vouched commit sha. Optional `tag` carries the deploy +bookkeeping tag — `deployed/` on a successful build or +`failed/` on a failed one, planted by the `MergeConfigPr` deploy. +Both fields are `Option`: `None` on the paths that don't deploy a new +commit (spawn / init_config / meta-update / deny, and `auto_update::rebuild_agent` reapplying the existing main, or the dashboard `↻ R3BU1LD` button when the lock didn't move). When set, `git show ` against `/agents//applied.git` inside the bootstrap container yields the exact tree that was referenced. -To add a new event: new `HelperEvent` variant + call sites + update -`prompts/system.md` (`` block, the lifecycle- -event list) so the root agent knows the new shape. +To add a new lifecycle notice: if it needs to drive an immediate turn +(a live conversation like `Ask`/`Answer`, or something genuinely +urgent), add a `HelperEvent` variant + call sites + update +`prompts/system.md`'s message-event list. If it's "FYI, check when +convenient," call `push_todo`/`push_todo_submitter` directly instead — +no new wire type needed. ## Auto-update on startup diff --git a/hive-agent/prompts/system.md b/hive-agent/prompts/system.md index e545ec0b..44e114dd 100644 --- a/hive-agent/prompts/system.md +++ b/hive-agent/prompts/system.md @@ -15,14 +15,13 @@ Your config repo is mounted **read-only** at `/agents/{label}/config/` — `agen Approval boundary: lifecycle ops on _existing_ direct children (`kill`, `start`, `restart`) are at your discretion — no operator approval needed (requires `lifecycle` tool group). _Creating_ a new agent (two-step: `request_init_config` + `request_apply_commit`) and _changing_ any agent's config (`request_apply_commit`) both go through the approval queue (requires `approvals` tool group). The operator only signs off on changes; you run the day-to-day. -Messages from sender `system` are hyperhive helper events (JSON body, `event` field discriminates): `approval_resolved`, `config_ready`, `spawned`, `rebuilt`, `killed`, `destroyed`, `container_crash`, `needs_login`, `logged_in`, `needs_update`, `question_asked`, `question_answered`. Use these to react to lifecycle changes: +Messages from sender `system` are hyperhive helper events (JSON body, `event` field discriminates): `approval_resolved`, `container_crash`, `needs_update`, `question_asked`, `question_answered`. Use these to react to lifecycle changes: -- `config_ready` — the proposed config repo for a new agent was just seeded (post-`InitConfig` approval). Review and edit `/agents//config/agent.nix`, commit your changes, then call `request_apply_commit` with the commit sha. -- `needs_login` — agent has no claude session yet. Flag the operator if it's been long. -- `logged_in` — agent just completed login; first useful turn is imminent. - `needs_update` — agent's flake rev is stale. Call `update(name)` to rebuild — it's idempotent and doesn't need approval. - `container_crash` — restart with `start(name)`. If it crashes again, ask the operator. -- otherwise greet freshly-spawned agents, retry failed rebuilds, pick up answers to questions you asked. +- otherwise pick up answers to questions you asked. + +Lifecycle notices that don't need an immediate turn — a new agent spawned, its config repo seeded, a container rebuilt/killed/destroyed, or its login state changing — surface as todos instead of messages now. Call `get_loose_ends` to see them. Durable knowledge: