docs(agents): fix dangling xref and sweep conventions.md Wake injection
Review fixes for #4879 (argus): - mcp.md: the 'Waking the agent' cross-ref pointed at Core tools, which never mentions UpsertTodo/HIVE_AGENT_SOCKET. Point it at docs/tools/bash.md's 'Completion as a todo (loose-ends v2)' section, which documents the actual upsert/signal/clear mechanism. - conventions.md 'Wake injection': still framed AgentRequest::Wake (a type that no longer exists) as the live wake surface with matrix/forge as callers. hive_core_agent_sock::Request::Wake has exactly one non-test reference on origin/main (the handler at socket_server/mod.rs:307) and no client; matrix/bash/forge all moved to the in-agent todo socket. Rewritten to match, linking mcp.md's 'Waking the agent' section instead of duplicating it. docs/tools/matrix.md:136-137 has the same stale AgentRequest::Wake claim (and contradicts its own :159-165) but is out of scope (#4136) — noted as a follow-up in the PR body instead of edited.
This commit is contained in:
parent
4e31550dad
commit
ac35f0f2cf
2 changed files with 20 additions and 14 deletions
|
|
@ -60,15 +60,18 @@ hive-c0re owns the host admin socket.
|
|||
|
||||
### Wake injection
|
||||
|
||||
`AgentRequest::Wake { from, body }` (and the manager-flavour mirror)
|
||||
is the wake-event-injection surface. Recipient is implicit — the
|
||||
agent the socket belongs to — and `from` is caller-chosen so the
|
||||
wake prompt can label the source verbatim (`"matrix: new message in
|
||||
#general"`, `"forge: PR #42 opened"`, etc.). <!-- lint:allow: example strings, not real tags -->
|
||||
Typical caller: an
|
||||
in-container background task (the matrix daemon, a scraper, the
|
||||
forge-notify webhook subscriber) that needs to signal "external work
|
||||
has arrived" without going through the broker as a peer agent.
|
||||
`hive_core_agent_sock::Request::Wake { from, body }` is the
|
||||
wake-event-injection surface on the host-served per-agent socket.
|
||||
Recipient is implicit — the agent the socket belongs to — and `from`
|
||||
is caller-chosen so the wake prompt can label the source verbatim
|
||||
(`"matrix: new message in #general"`, `"forge: PR #42 opened"`, etc.). <!-- lint:allow: example strings, not real tags -->
|
||||
`hive-c0re` still handles it, but no built-in
|
||||
in-container producer calls it today — matrix, bash and forge
|
||||
notifications all upsert a todo on the harness's in-agent socket
|
||||
(`HIVE_AGENT_SOCKET`) instead, which signals the same turn loop without
|
||||
a hive-c0re round-trip. See
|
||||
[`docs/turn-loop/mcp.md` § Waking the agent from inside the
|
||||
container](../turn-loop/mcp.md#waking-the-agent-from-inside-the-container).
|
||||
|
||||
Identity = socket means anything that can connect to
|
||||
`/run/hive/mcp.sock` is implicitly trusted to inject wakes. That's
|
||||
|
|
|
|||
|
|
@ -180,11 +180,14 @@ hive_name?, swarm_name?, matrix_accounts? }`. `matrix_accounts` is a
|
|||
|
||||
The built-in producers (matrix, bash, forge) no longer dial a direct
|
||||
wake — all three now upsert a todo on the harness's in-agent socket
|
||||
(`HIVE_AGENT_SOCKET`, `UpsertTodo`, see [Inbox](#core-tools-always-available)
|
||||
above): a new or changed summary makes the harness signal its own turn
|
||||
loop, with no hive-c0re round-trip. An external MCP server (or any
|
||||
other in-container process) can push its own todo the same way —
|
||||
`subsystem` is a plain string, not a closed set.
|
||||
(`HIVE_AGENT_SOCKET`, `UpsertTodo` — see
|
||||
[`docs/tools/bash.md` § Completion as a todo
|
||||
(loose-ends v2)](../tools/bash.md#completion-as-a-todo-loose-ends-v2)
|
||||
for the full upsert/signal/clear mechanism): a new or changed summary
|
||||
makes the harness signal its own turn loop, with no hive-c0re
|
||||
round-trip. An external MCP server (or any other in-container process)
|
||||
can push its own todo the same way — `subsystem` is a plain string,
|
||||
not a closed set.
|
||||
|
||||
The host-served per-agent socket at `/run/hive/mcp.sock` still carries
|
||||
a lower-level `Wake` request (`hive_core_agent_sock::Request::Wake {
|
||||
|
|
|
|||
Loading…
Reference in a new issue