From fd33ffa2cd7bfdc4921a6104e6564f575700be89 Mon Sep 17 00:00:00 2001 From: Heimdall Date: Wed, 11 Nov 2026 06:24:52 +0000 Subject: [PATCH] Mouth addressing facts: room-keyed reply cache, exact pill anchors, no lookup for notices and edits, doc says claimed Co-Authored-By: Claude Sonnet 5.5 --- docs/bridge.md | 10 ++++----- tests/persona-matrix-mouth.test.mjs | 35 +++++++++++++++++++++++++++++ tools/persona-matrix-mouth.mjs | 22 ++++++++++-------- 3 files changed, 53 insertions(+), 14 deletions(-) diff --git a/docs/bridge.md b/docs/bridge.md index 7c830ab..14ede89 100644 --- a/docs/bridge.md +++ b/docs/bridge.md @@ -200,24 +200,24 @@ Persona speech goes out through Matrix, not Discord. `tools/persona-matrix-mouth ### Addressing facts (`chat_pending.v3`) -The mouth wakes no one; the heartbeat and each Persona session decide who is told a delivery (Huginn `address.rs`, ruling `eureka-body:ruling:addressed-delivery-only`). Telling every Persona every message made 71.5% of 4,351 Persona turns on 2026-11-10 do nothing. The rule stays in one place, Huginn's, because two of its inputs are not Matrix facts: the Persona's stewardship records (her projects' chat names) and the sender's role (operator or Mind). The mouth owns the other half: what Matrix itself proves, per Persona, for the delivery. +The mouth wakes no one; the heartbeat and each Persona session decide who is told a delivery (Huginn `address.rs`, ruling `eureka-body:ruling:addressed-delivery-only`). Telling every Persona every message made 71.5% of 4,351 Persona turns on 2026-11-10 do nothing. The rule stays in one place, Huginn's, because two of its inputs are not Matrix facts: the Persona's stewardship records (her projects' chat names) and the sender's role (operator or Mind). The mouth owns the other half: what Matrix itself says, per Persona, for the delivery. Matrix verifies the sender's identity and nothing else: `tag` and `room` are the sender's claim in `m.mentions` (the homeserver does not check the text against it, nor that the sender may use `@room`), and `reply` is checked against the event it targets, which the mouth reads as her account. A client asks for the facts by the kind it polls with: `gamecult.persona.chat_pending_request.v2` (the v1 tuple, `[persona, after_seq]`) is answered with `gamecult.persona.chat_pending.v3`; a v1 request still gets the 12-field `chat_pending.v2` answer unchanged. A v3 delivery is the 12 fields of the v2 delivery, then: | Field | Type | Meaning | |---|---|---| -| 12 `basis` | `"direct"`, `"tag"`, `"reply"`, `"room"` or nil | Why Matrix proves the message is for this Persona, first that holds: `direct` the room is one of her DMs; `tag` `m.mentions.user_ids` lists her id, or the client sent no `m.mentions` at all and the HTML body links her `matrix.to` pill; `reply` it replies to, or is in a thread under, an event her account wrote (her Self run speaks as her account, so its words count); `room` an `@room` mention. | +| 12 `basis` | `"direct"`, `"tag"`, `"reply"`, `"room"` or nil | Why the message is for this Persona, by what Matrix says, first that holds: `direct` the room is one of her DMs; `tag` `m.mentions.user_ids` lists her id, or the client sent no `m.mentions` at all and an `` in the HTML body is exactly her `matrix.to` link; `reply` it replies to, or is in a thread under, an event her account wrote (her Self run speaks as her account, so its words count; any member's message in a thread under one of her events is a `reply` too, and the target is read once per room and event, a failure for a minute); `room` an `@room` mention. A `notice` or an `edit` costs no reply lookup. | | 13 `form` | `"message"`, `"notice"` or `"edit"` | `m.notice` is an automated line; `m.replace` is an edit of an earlier message. Only a `message` can address anyone. | -What the mouth cannot know, and so what a nil `basis` means: **unproven, not "not for her"**. Her handle and public name in the text (any casing, with or without `@`, `'s`), the names her stewardships list, a project's repo name, and whether the sender is the operator or a Mind are all matched by Huginn, not here. A reply whose target the homeserver will not give is nil and logged. The mouth also cannot see whether a message was meant for her without naming her. Every delivery is still delivered: nothing is dropped in the mouth, so the Huginn rule cannot lose a message the mouth had no way to judge. +What the mouth cannot know, and so what a nil `basis` means: **unproven, not "not for her"**. Her handle and public name in the text (any casing, with or without `@`, `'s`), the names her stewardships list, a project's repo name, and whether the sender is the operator or a Mind are all matched by Huginn, not here. A reply whose target the homeserver will not give is nil and logged. The mouth also cannot see whether a message was meant for her without naming her. Every delivery is still delivered, claimed tags included: nothing is dropped in the mouth, so the Huginn rule cannot lose a message the mouth had no way to judge. Proposed runtime half (follow-up `persona-wakes-on-address-only`): 1. Poll with `chat_pending_request.v2` and parse `chat_pending.v3`. -2. A delivery is *addressed* to a Persona when `form == "message"` and (`basis` is not nil, or `address::addresses` matches her names or her projects' names on the text, or the sender is the operator and the rule matches). `basis == "room"` is the runtime's policy to weigh; the mouth only reports it. +2. A delivery is *addressed* to a Persona when `form == "message"` and either `basis` is `direct`, `tag` or `reply`, or `address::addresses` matches her names or her projects' names on the text. The off-beat wake keeps the sender gate of `heartbeat.rs` `wakes` (the operator or another Mind of the roster): a stranger's tag, `@room` or DM is delivered but wakes no one off the beat. `basis == "room"` is the runtime's policy to weigh; the mouth only reports it. 3. A real-time wake, a live session's tell and the stagger apply to addressed deliveries only. A `notice` or an `edit` never wakes, whatever its basis. 4. A delivery that is not addressed is acked in sequence with the rest, so the position moves (the mouth stops reading at 500 unacked deliveries); it is not lost: Matrix is the record, and the next addressed delivery's `context` (up to 20 lines) and a beat's own room read show it. Reading the tail on a scheduled beat is a runtime read of Matrix, a follow-up of the ruling `wake-reads-room-tail`; the mouth adds no endpoint for it. -5. `basis` and `form` are evidence, not authority: if they disagree with Huginn's own reading of the text, the runtime's `address.rs` decides for names, the mouth's `basis` for what only Matrix knows. +5. `basis` and `form` are evidence, not authority: a sender's claim is weighed by the runtime's own rule (`address.rs` for names, the sender gate for who may wake her); the mouth reports what the event says and what only Matrix could look up (the author of a reply target). Golden bytes: `tests/fixtures/persona-chat-v5/`; Huginn pins the same bytes. diff --git a/tests/persona-matrix-mouth.test.mjs b/tests/persona-matrix-mouth.test.mjs index 6a0c2b1..fcaa255 100644 --- a/tests/persona-matrix-mouth.test.mjs +++ b/tests/persona-matrix-mouth.test.mjs @@ -1423,3 +1423,38 @@ test("addressing facts: the v3 answer carries basis and form; the v2 answer a v1 assert.throws(() => docs.parseDeliveryV3([...docs.deliveryTuple(made[0]), "everyone", "message"]), /unknown delivery basis/); assert.throws(() => docs.parseDeliveryV3(docs.deliveryTuple(made[0])), /14-field/); }); + +test("addressing facts: a hit read for a reply in one room is not lent to a reply in another room, and a target the server places elsewhere is null", async () => { + const mine = { ...withContent("$mine", SELF, { body: "mine" }, 1000), room_id: ROOM }; + const reply = id => withContent(id, META, { body: "re", "m.relates_to": { "m.in_reply_to": { event_id: "$mine" } } }); + const hs = await fakeHomeserver({ + preload: { [ROOM]: [mine], "!operator:gamecult.test": [{ ...mine, room_id: "!elsewhere:gamecult.test" }] }, + sync: since => since === null ? { next_batch: "b0" } : { next_batch: "b1", ...joined({ [ROOM]: { timeline: { events: [reply("$prime")] } }, "!operator:gamecult.test": { timeline: { events: [reply("$spoof")] } } }) }, + }); + try { + const mouth = mouthFor(hs); + await mouth.syncOnce(); + assert.deepEqual(facts(await mouth.syncOnce()), [["$prime", "reply", "message"], ["$spoof", null, "message"]]); + } finally { await hs.close(); } +}); + +test("addressing facts: a pill is her exact matrix.to anchor: a longer id, a non-link attribute and a quoted reply are no tag", async () => { + const html = h => ({ body: "x", format: "org.matrix.custom.html", formatted_body: h }); + const { made } = await deliver([ + withContent("$a", META, html(`x`)), + withContent("$b", META, html(`x`)), + withContent("$c", META, html(`Eureka`)), + ]); + assert.deepEqual(made.map(d => d.basis), [null, null, "tag"]); +}); + +test("addressing facts: an edit or a notice replying to her costs no target fetch, and a target that failed is not refetched within a minute", async () => { + const rel = { "m.relates_to": { "m.in_reply_to": { event_id: "$gone" } } }; + const { made, hs } = await deliver([ + withContent("$n", META, { msgtype: "m.notice", body: "n", ...rel }), + withContent("$r1", META, { body: "a", ...rel }), + withContent("$r2", META, { body: "b", ...rel }), + ]); + assert.deepEqual(facts(made), [["$n", null, "notice"], ["$r1", null, "message"], ["$r2", null, "message"]]); + assert.equal(hs.seen.filter(r => r.path.includes("/event/")).length, 1); +}); diff --git a/tools/persona-matrix-mouth.mjs b/tools/persona-matrix-mouth.mjs index 7c0f6aa..636a303 100644 --- a/tools/persona-matrix-mouth.mjs +++ b/tools/persona-matrix-mouth.mjs @@ -298,23 +298,27 @@ export function createMouth({ if (directRooms.has(roomId)) return "direct"; const mentions = event.content["m.mentions"]; if (Array.isArray(mentions?.user_ids) ? mentions.user_ids.includes(selfId) : mentions === undefined && pillFor(event.content.formatted_body)) return "tag"; - if (await repliesToMe(roomId, event.content["m.relates_to"])) return "reply"; + if (formOf(event.content) === "message" && await repliesToMe(roomId, event.content["m.relates_to"])) return "reply"; // an edit or a notice wakes no one: no fetch for it return mentions?.room === true ? "room" : null; } - const pillFor = html => typeof html === "string" && [selfId, encodeURIComponent(selfId)].some(id => html.includes(`https://matrix.to/#/${id}`)); - const authors = new Map(); // event id -> sender, read successes only, bounded + // A pill is an anchor whose href is exactly her matrix.to link; a longer id, an attribute that merely contains one and a quoted reply do not count. + const pillFor = html => typeof html === "string" && [...html.matchAll(/]*?href\s*=\s*(["'])(.*?)\1/gi)].some(([, , href]) => [selfId, encodeURIComponent(selfId)].some(id => href === `https://matrix.to/#/${id}`)); + const authors = new Map(); // `${room id} ${event id}` -> { sender, at }: read results, a failure kept for NEGATIVE_MS, bounded; the key holds the room so another room's reply cannot borrow a hit + const NEGATIVE_MS = 60 * 1000; async function authorOf(roomId, eventId) { - if (authors.has(eventId)) return authors.get(eventId); + const key = `${roomId} ${eventId}`; + const known = authors.get(key); + if (known && (known.sender !== null || now() - known.at < NEGATIVE_MS)) return known.sender; + let sender = null; try { const target = await matrix("GET", `/rooms/${encodeURIComponent(roomId)}/event/${encodeURIComponent(eventId)}`, undefined, API, AbortSignal.timeout(sendTimeoutMs)); - if (target?.room_id !== undefined && target.room_id !== roomId) return null; // an id from another room is not an answer about this one - authors.set(eventId, target.sender); - if (authors.size > DELIVERED_INDEX) authors.delete(authors.keys().next().value); - return target.sender; + if (target?.room_id === undefined || target.room_id === roomId) sender = typeof target?.sender === "string" ? target.sender : null; // an id from another room is not an answer about this one } catch (error) { say(`reply target ${eventId} not read: ${error.message}`); - return null; } + authors.set(key, { sender, at: now() }); + if (authors.size > DELIVERED_INDEX) authors.delete(authors.keys().next().value); + return sender; } async function repliesToMe(roomId, relates) { const targets = new Set([relates?.["m.in_reply_to"]?.event_id, relates?.rel_type === "m.thread" ? relates.event_id : undefined].filter(id => typeof id === "string" && id !== ""));