From e3864fe78772053e443e0b34c003844028c01a50 Mon Sep 17 00:00:00 2001 From: atlas Date: Fri, 11 Sep 2026 18:06:26 +0200 Subject: [PATCH] docs/matrix: name the [acct:] prefix a multi-account agent receives MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `matrix.md` documents the exact text of every inbound matrix signal — three wake-body shapes and the invite loose-end — and none of them mention that the daemon prefixes `[acct:] ` when it serves more than one account. `wake::tag_account` is live on both documented paths (`timeline.rs:75` for unread wakes, `:139` for invite todos), so an agent with an extra account receives `[acct:ccc] [matrix] @a:s in #x: hi` where the page promises a body starting `[matrix]`. The example is not hypothetical: the matrix module uses `matrix-token-ccc` on dmatrix as its worked example of an extra account. It stayed invisible because the `None` arm returns the body unchanged, so every single-account agent sees the documented format exactly. The page is right for almost every reader and wrong for precisely the readers its "Multiple accounts" section is written for. Two placements rather than one. The prefix itself goes next to the wake formats it corrects, with the worked example and the reason a leading `[matrix]` match works until a second account exists. A forward pointer goes in "Multiple accounts", because that is the section someone configuring extra accounts actually lands on, and it previously covered only the outbound `account` parameter — the half you pass, not the half you parse. Closes #4243. --- docs/tools/matrix.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/tools/matrix.md b/docs/tools/matrix.md index d3fc1efe..8d39c7ed 100644 --- a/docs/tools/matrix.md +++ b/docs/tools/matrix.md @@ -84,6 +84,10 @@ Requires `hyperhive.matrix.enable = true`. Every matrix tool above takes an optional `account` parameter (a name from this map) to act as that identity instead of the primary one. +Declaring an extra account also changes what the agent *receives*: wake +bodies and invite todos gain an `[acct:]` prefix — see +[Architecture](#architecture) below. + ## Architecture `hive-matrix-daemon` is a single long-running process (one per agent @@ -110,6 +114,13 @@ Incoming room events wake the agent via `AgentRequest::Wake` with bulleted list (`- : : ` or `- : N unread` per room) +**Multi-account prefix**: when the daemon serves more than one account +(`hyperhive.matrixAccounts`), it prefixes every wake body and every invite todo +below with `[acct:] `, so a wake arrives as +`[acct:ccc] [matrix] in : …`. A single-account agent gets the +formats exactly as written — the daemon adds nothing — which is why matching +on a leading `[matrix]` works right up until you declare a second account. + hive-matrix-daemon includes the same per-room breakdown in the `UnreadMatrix` entry `get_loose_ends` returns, so unread rooms surface in the loose-ends list between turns.