vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

hive-sh4re + docs: extract Wake-injection prose (#717 batch 5)

Browse source
This commit is contained in:
iris 2026-05-31 16:04:32 +02:00 • committed by mara
commit 18d0fbfecb
2 changed files with 23 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

17
docs/conventions.md
View file

@ -21,6 +21,23 @@ bind-mount." A sub-agent only sees its own `/run/hive/mcp.sock`; the
manager has access to its privileged socket; 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.). 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.
Identity = socket means anything that can connect to
`/run/hive/mcp.sock` is implicitly trusted to inject wakes. That's
fine: the bind-mount only exposes the socket inside the agent's own
container, so the trust boundary is the container's process
namespace, not the wire surface.
## Recipient sentinels
A few recipient names are reserved by the broker and have special

19
hive-sh4re/src/lib.rs
View file

@ -328,15 +328,10 @@ pub enum AgentRequest {
/// per-agent equivalent of the old dashboard T4LK form, but scoped to
/// the agent whose page the operator is on.
OperatorMsg { body: String },
/// Wake-up event injected from inside the container — typically an
/// extra MCP server (matrix, scraper, webhook bridge) signalling
/// that external work has arrived for this agent. Recipient is
/// implicit (this agent); `from` is caller-chosen so the wake
/// prompt can label the source ("matrix: new message in
/// #general"). Identity = socket means anything that can connect
/// to `/run/hive/mcp.sock` is implicitly trusted to inject these,
/// which is fine: the bind-mount is restricted to the agent's
/// own container.
/// Wake-up event injected from inside the container. Recipient is
/// implicit (this agent); `from` is caller-chosen. See
/// `docs/conventions.md::Wake injection` for the trust model and
/// typical callers.
Wake { from: String, body: String },
/// Last `limit` messages addressed to this agent, newest-first.
/// Non-mutating — pulls from the broker without delivering. The
@ -835,10 +830,8 @@ pub enum ManagerRequest {
/// Mirror of `AgentRequest::RequeueInflight` on the manager
/// surface — fired exactly once on manager harness boot.
RequeueInflight,
/// Mirror of `AgentRequest::Wake` on the manager surface. Used by
/// in-container background tasks (e.g. `forge_notify`) to push a
/// message into the manager's own broker inbox. `from` is caller-
/// chosen; `body` becomes the wake prompt body.
/// Mirror of `AgentRequest::Wake` on the manager surface. See
/// `docs/conventions.md::Wake injection`.
Wake { from: String, body: String },
/// Queue an approval to run `nix flake update [inputs...]` on the
/// meta flake. `inputs` is the list of named inputs to update