From 744494ba73bc0c031324261e5725314014b5602d Mon Sep 17 00:00:00 2001 From: lexis Date: Fri, 29 May 2026 20:58:16 +0200 Subject: [PATCH] docs: matrix MCP per-agent option + tool surface (follow-up to #603) --- README.md | 11 +++++++++++ docs/turn-loop.md | 22 ++++++++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/README.md b/README.md index 9e1045ba..ff542931 100644 --- a/README.md +++ b/README.md @@ -145,6 +145,17 @@ the container as environment variables. Common options: replace the whole dist. Paths with leading `/` or `..` segments are rejected at eval time. +- **`hyperhive.matrix.enable`** — Boolean (default `true`). When true, + each agent container runs `hive-matrix-daemon` (a long-running + matrix-sdk process that holds the per-agent client + sync) and + auto-injects `hive-matrix-mcp` as a stdio MCP server so claude can + call the matrix tools (`mcp__matrix__send_message`, `send_dm`, + `send_reaction`, `send_reply`, `mark_read`, `list_rooms`, + `list_room_members`, `read_room`). Silently no-ops when + `/matrix-token` is absent (i.e., the host-level + `hyperhive.matrix` tuwunel container hasn't provisioned the account + yet). Set to `false` to opt a specific agent out of matrix. + See `nix/templates/harness-base.nix` for the full list of options and their descriptions. diff --git a/docs/turn-loop.md b/docs/turn-loop.md index 5b5c64b8..d19d3546 100644 --- a/docs/turn-loop.md +++ b/docs/turn-loop.md @@ -284,6 +284,28 @@ Identity = socket: anything that can connect to which is fine because the bind-mount is the agent's own container only. +### Built-in matrix MCP (`mcp__matrix__*`) + +When `hyperhive.matrix.enable = true` (default) and the host-level +matrix tuwunel is configured, the harness auto-injects `hive-matrix-mcp` +as a second stdio MCP server. Tools land as `mcp__matrix__`: + +- `send_message(room_id, body, format?)` — send a plain or markdown message +- `send_dm(user_id, body, format?)` — send a direct message to a matrix user +- `send_reaction(room_id, event_id, key)` — react to a message +- `send_reply(room_id, event_id, body, format?)` — threaded reply +- `mark_read(room_id, event_id)` — advance the read receipt +- `list_rooms()` — enumerate joined rooms (id + name + unread count) +- `list_room_members(room_id)` — members of a room +- `read_room(room_id, limit?)` — recent timeline events + +The daemon (`hive-matrix-daemon`) holds the long-running matrix-sdk +`Client` + sync loop; the stdio bridge (`hive-matrix-mcp`) is spawned +per turn and forwards tool calls over `/run/hive-matrix.sock`. Both +silently exit when `/matrix-token` is absent (account not yet +provisioned). Incoming room events wake the agent via `AgentRequest::Wake` +with `from: "matrix"` and a teaser body (`[matrix] @sender in #room: …`). + ### Extra MCP servers (per-agent) Each agent's NixOS config can declare additional MCP servers via