From 637d36a11f668968614906c7ed9ac821bd93a444 Mon Sep 17 00:00:00 2001 From: iris Date: Sat, 15 Aug 2026 12:29:08 +0200 Subject: [PATCH] docs(turn-loop): fix wrong HelperEvent lifecycle-event list MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Verified against hive-sh4re/src/manager.rs and docs/approvals.md: only ApprovalResolved/ContainerCrash/NeedsUpdate/QuestionAsked/QuestionAnswered are HelperEvents delivered as inbox messages. spawned/rebuilt/killed/ destroyed/needs_login/logged_in/config_ready aren't HelperEvent variants at all — they deliver via Coordinator::push_todo/push_todo_submitter (the in-container todo socket), not the broker inbox. --- docs/turn-loop/mcp.md | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/turn-loop/mcp.md b/docs/turn-loop/mcp.md index 70461d41..35d8b3bb 100644 --- a/docs/turn-loop/mcp.md +++ b/docs/turn-loop/mcp.md @@ -63,16 +63,23 @@ ttl_seconds?, to?)`, `answer(id, answer)`, `ack_until(up_to)`. `ack_until(N)` to prevent re-pop. Acked rows never redeliver. Transient pings (sentinel id 0) have nothing to ack and show no marker. -**System messages** (from sender `system`): lifecycle and Q&A events +**System messages** (from sender `system`): the higher-urgency +lifecycle + Q&A events (`hive_sh4re::manager::HelperEvent`) are delivered as regular inbox messages (same `recv` path; body is a JSON object with an `event` discriminant field). The **submitting agent** (the root agent for top-level containers; an agent with the `approvals` -tool group for its own subtree) receives lifecycle events (`spawned`, -`rebuilt`, `killed`, `destroyed`, `container_crash`, `needs_login`, -`logged_in`, `config_ready`, `needs_update`, `approval_resolved`). Any -agent receives Q&A events when it is the declared target -(`question_asked`) or the asker (`question_answered`). Full payload -shapes and routing logic in +tool group for its own subtree) receives `container_crash`, +`needs_update`, and `approval_resolved` this way. Any agent receives +Q&A events when it is the declared target (`question_asked`) or the +asker (`question_answered`). The remaining, lower-urgency lifecycle +notices — `spawned`, `rebuilt`, `killed`, `destroyed`, `needs_login`, +`logged_in`, `config_ready` — skip the inbox entirely: they land as +todos on the submitting agent's in-container todo socket instead +(`Coordinator::push_todo`/`push_todo_submitter`, `subsystem = "core"`), +which still wakes a turn (the todo-wake path — see [Turn +outcomes](README.md#turn-outcomes)) but via a generic "call +`get_loose_ends`" prompt rather than the event body itself. Full +payload shapes and routing logic in [`docs/approvals.md` § Helper events](../approvals.md#helper-events-to-the-submitting-agent). **Inbox** (`inbox` group): `get_loose_ends(agent?)`,