vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

docs(agents): fix dangling xref and sweep conventions.md Wake injection

Browse source 
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:
atlas 2026-10-02 00:22:06 +02:00 • committed by mara
commit ac35f0f2cf
2 changed files with 20 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

21
docs/process/conventions.md
View file

@ -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