PR #64796: fix(matrix): trust m.mentions.user_ids as authoritative mention source

• Repository: openclaw/openclaw
• Author: hclsys
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/64796

Description (problem / solution / changelog)

Summary

resolveMentions() in the Matrix extension required BOTH m.mentions.user_ids metadata AND a visible text or formatted_body mention for a user mention to register. When non-OpenClaw Matrix clients (Element, standalone bots via matrix-bot-sdk) send proper m.mentions metadata without duplicating the @bot text in the message body, the mention was silently ignored and requireMention: true dropped the message.

This effectively made requireMention: true unusable for any Matrix room receiving messages from non-OpenClaw clients — which is most production deployments.

Fixes #64785

Root cause

// mentions.ts:166-169 (before fix)
const metadataBackedUserMention = Boolean(
  params.userId &&
  mentionedUsers.has(params.userId) &&
  (mentionedInFormattedBody || textMentioned),  // ← requires BOTH
);

Per MSC3952, m.mentions.user_ids is the authoritative mention source. The visible @bot in the body is a display hint for clients that don't support m.mentions, not a prerequisite for the mention to be valid.

The conjunction meant that a message like:

{
  "body": "please reply",
  "m.mentions": { "user_ids": ["@bot:matrix.org"] }
}

...was NOT detected as a mention because "please reply" doesn't contain @bot.

Fix

Drop the (mentionedInFormattedBody || textMentioned) conjunction:

// mentions.ts:166-172 (after fix)
const metadataBackedUserMention = Boolean(
  params.userId && mentionedUsers.has(params.userId),
);

Metadata-backed user mentions are now trusted on their own, matching the Matrix spec.

Why m.mentions.room is left unchanged

The metadataBackedRoomMention check at line 171 still requires visible @room text alongside m.mentions.room: true. This is intentional: @room mentions have different security implications (spam amplification to all room members), so requiring both metadata AND visible text is a reasonable anti-spam measure. User mentions don't have this concern.

Tests

Updated extensions/matrix/src/matrix/monitor/mentions.test.ts:

• Before: "does not trust forged m.mentions.user_ids without a visible mention" → asserted wasMentioned: false
• After: "detects mention via m.mentions.user_ids even without visible text mention (#64785)" → asserts wasMentioned: true + hasExplicitMention: true

The existing test for room mentions (requiring both m.mentions.room and visible @room text) is unchanged.

Scope

• Files: mentions.ts (+6/-3), mentions.test.ts (+8/-5)
• Production LOC: 1 condition removed from 1 boolean expression
• oxlint clean
• Zero competing PRs (only closed #51106 in adjacent area — different fix scope)

cc @BunsDev — Matrix channel. Credit to @guci314 for the clear reproduction with proper m.mentions metadata in #64785.

Changed files

• CHANGELOG.md (modified, +5/-0)
• extensions/matrix/src/matrix/monitor/handler.test.ts (modified, +27/-3)
• extensions/matrix/src/matrix/monitor/mentions.test.ts (modified, +21/-3)
• extensions/matrix/src/matrix/monitor/mentions.ts (modified, +4/-0)