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

drop the hyperhive send/recv/ack_until tools: agents message over matrix

Browse source
This commit is contained in:
damocles 2026-11-07 11:55:45 +01:00 • committed by mara
commit bffb2c07a8
2 changed files with 52 additions and 397 deletions
Download patch file Download diff file Expand all files Collapse all files

8
docs/4-implementation/turn-loop/claude-invocation.md
View file

@ -220,12 +220,8 @@ the `CLAUDE.md` (see `docs/2-handbook/agents/persistence.md` for the
boot-time rename).
The wake prompt is intentionally minimal: the popped message's
`from`/`body`, prefixed with a `[msg #<id>]` broker-row-id marker
(so the agent knows what id to pass to `ack_until` for bulk triage;
transient pings show no marker because their sentinel id 0 has nothing
to ack), plus an inline `({unread} more pending — drain via …)` hint
when `unread > 0`. Claude drives any further `recv`/`send` itself via
the embedded MCP server.
`from` and `body`, behind a redelivery or interruption banner when one applies.
The harness drives one turn per inbox message.
`hive-agent` self-announces once on every boot:
`boot_announce::announce` pushes a one-line "you were just

48
docs/4-implementation/turn-loop/mcp.md
View file

@ -36,41 +36,25 @@ runs on the change.
## Core tools (always available)
**Messaging** (`messaging` group): `send(to, body, in_reply_to?)`,
`recv(max?)`, `ack_until(up_to)`.
**Messaging.** There is no hyperhive messaging tool. Agents talk to peers and the
operator over matrix ([matrix](../agent-tools/matrix.md)); `send_dm` takes a peer's agent
name (`iris`, meaning that agent on the same homeserver) or a full user id. An agent
without matrix tools is cut off from peers on purpose, and the operator reads its
`set_status` line, its turn output on the dashboard, and its logs. The `messaging`
permission remains an accepted value for stored permission sets, but grants no tool.
- `send` — hive-local broker message to a peer on this hive (logical name). With
the matrix MCP tools, talk to peers over matrix instead (a DM to the `user_id` in
`get_agent_meta`'s `matrix_accounts`); `send` is for peers without a matrix
account and agents without matrix tools. Optional
`in_reply_to: i64` links the message to a prior id for thread
rendering. The broker refuses `to: "operator"`. The error
points an agent that has the matrix MCP tools at matrix
([matrix](../agent-tools/matrix.md)), and tells one without them that the
operator reads its `set_status` line, its turn output on the dashboard,
and its logs.
- `recv` — drain inbox. Always an immediate peek, never blocks. `max`
(default 1, cap 5) drains up to N rows. `recv` prefixes each returned row
with `[msg #<id>]` (broker row id; note the highest id seen, then pass
it to `ack_until` to bulk-triage the batch). **Graceful shutdown**: when the harness
receives a stop signal, the inbox becomes fenced and `recv` returns an
explicit `from: "graceful-stop"` message instead of an empty inbox.
This unmissably directs the agent to flush durable state (`/state`
files) and end the turn — the container exits when the turn completes.
The graceful-stop turn takes the same post-turn compaction path as any
other turn: if the context crossed the watermark the harness runs a
notes-checkpoint turn and then `/compact`. Compacting before shutdown
keeps a later cold start cheap instead of re-uploading a large transcript.
- `ack_until(up_to)` — bulk-mark inbox rows handled: it stamps every row
with broker id `<= up_to` as acked in a single UPDATE.
Recipient-scoped (agents can only ack their own rows). Use when a
restart redelivers a large backlog of already-handled messages: read
the highest `[msg #N]` from the set you've actually processed, then
`ack_until(N)` to prevent re-pop. Acked rows never redeliver.
Transient pings (sentinel id 0) have nothing to ack and show no marker.
The inbox itself is the harness's: it pops one message per turn and acks it when the
turn ends, so there is no agent-facing `recv` or `ack_until`. **Graceful shutdown**:
when the harness receives a stop signal, the inbox becomes fenced and the harness
delivers an explicit `from: "graceful-stop"` message as the turn's prompt. It
directs the agent to flush durable state (`/state` files) and end the turn; the
container exits when the turn completes. The graceful-stop turn takes the same
post-turn compaction path as any other turn: if the context crossed the watermark the
harness runs a notes-checkpoint turn and then `/compact`. Compacting before shutdown
keeps a later cold start cheap instead of re-uploading a large transcript.
**System messages** (from sender `system`): the broker delivers them as regular inbox
messages (same `recv` path). A container crash never reaches an
messages (the same path as every other inbox message). A container crash never reaches an
agent — it only produces a log line + swarm-level grafana
alert, no agent turn at all (`docs/4-implementation/scheduler/observability.md`). Lifecycle
transitions the job-queue scheduler or crash watcher drive directly —