@openclaw/matrix 2026.2.17 → 2026.2.19

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 2026.2.17
+## 2026.2.19
 
 ### Changes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/matrix",
-  "version": "2026.2.17",
+  "version": "2026.2.19",
   "description": "OpenClaw Matrix channel plugin",
   "type": "module",
   "dependencies": {

package/src/directory-live.test.ts

@@ -51,4 +51,24 @@ describe("matrix directory live", () => {
 
     expect(resolveMatrixAuth).toHaveBeenCalledWith({ cfg, accountId: "assistant" });
   });
+
+  it("returns no peer results for empty query without resolving auth", async () => {
+    const result = await listMatrixDirectoryPeersLive({
+      cfg,
+      query: "   ",
+    });
+
+    expect(result).toEqual([]);
+    expect(resolveMatrixAuth).not.toHaveBeenCalled();
+  });
+
+  it("returns no group results for empty query without resolving auth", async () => {
+    const result = await listMatrixDirectoryGroupsLive({
+      cfg,
+      query: "",
+    });
+
+    expect(result).toEqual([]);
+    expect(resolveMatrixAuth).not.toHaveBeenCalled();
+  });
 });

package/src/directory-live.ts

@@ -22,6 +22,15 @@ type MatrixAliasLookup = {
   room_id?: string;
 };
 
+type MatrixDirectoryLiveParams = {
+  cfg: unknown;
+  accountId?: string | null;
+  query?: string | null;
+  limit?: number | null;
+};
+
+type MatrixResolvedAuth = Awaited<ReturnType<typeof resolveMatrixAuth>>;
+
 async function fetchMatrixJson<T>(params: {
   homeserver: string;
   path: string;
@@ -48,17 +57,42 @@ function normalizeQuery(value?: string | null): string {
   return value?.trim().toLowerCase() ?? "";
 }
 
-export async function listMatrixDirectoryPeersLive(params: {
-  cfg: unknown;
-  accountId?: string | null;
-  query?: string | null;
-  limit?: number | null;
-}): Promise<ChannelDirectoryEntry[]> {
+function resolveMatrixDirectoryLimit(limit?: number | null): number {
+  return typeof limit === "number" && limit > 0 ? limit : 20;
+}
+
+async function resolveMatrixDirectoryContext(
+  params: MatrixDirectoryLiveParams,
+): Promise<{ query: string; auth: MatrixResolvedAuth } | null> {
   const query = normalizeQuery(params.query);
   if (!query) {
-    return [];
+    return null;
   }
   const auth = await resolveMatrixAuth({ cfg: params.cfg as never, accountId: params.accountId });
+  return { query, auth };
+}
+
+function createGroupDirectoryEntry(params: {
+  id: string;
+  name: string;
+  handle?: string;
+}): ChannelDirectoryEntry {
+  return {
+    kind: "group",
+    id: params.id,
+    name: params.name,
+    handle: params.handle,
+  } satisfies ChannelDirectoryEntry;
+}
+
+export async function listMatrixDirectoryPeersLive(
+  params: MatrixDirectoryLiveParams,
+): Promise<ChannelDirectoryEntry[]> {
+  const context = await resolveMatrixDirectoryContext(params);
+  if (!context) {
+    return [];
+  }
+  const { query, auth } = context;
   const res = await fetchMatrixJson<MatrixUserDirectoryResponse>({
     homeserver: auth.homeserver,
     accessToken: auth.accessToken,
@@ -66,7 +100,7 @@ export async function listMatrixDirectoryPeersLive(params: {
     method: "POST",
     body: {
       search_term: query,
-      limit: typeof params.limit === "number" && params.limit > 0 ? params.limit : 20,
+      limit: resolveMatrixDirectoryLimit(params.limit),
     },
   });
   const results = res.results ?? [];
@@ -121,42 +155,26 @@ async function fetchMatrixRoomName(
   }
 }
 
-export async function listMatrixDirectoryGroupsLive(params: {
-  cfg: unknown;
-  accountId?: string | null;
-  query?: string | null;
-  limit?: number | null;
-}): Promise<ChannelDirectoryEntry[]> {
-  const query = normalizeQuery(params.query);
-  if (!query) {
+export async function listMatrixDirectoryGroupsLive(
+  params: MatrixDirectoryLiveParams,
+): Promise<ChannelDirectoryEntry[]> {
+  const context = await resolveMatrixDirectoryContext(params);
+  if (!context) {
     return [];
   }
-  const auth = await resolveMatrixAuth({ cfg: params.cfg as never, accountId: params.accountId });
-  const limit = typeof params.limit === "number" && params.limit > 0 ? params.limit : 20;
+  const { query, auth } = context;
+  const limit = resolveMatrixDirectoryLimit(params.limit);
 
   if (query.startsWith("#")) {
     const roomId = await resolveMatrixRoomAlias(auth.homeserver, auth.accessToken, query);
     if (!roomId) {
       return [];
     }
-    return [
-      {
-        kind: "group",
-        id: roomId,
-        name: query,
-        handle: query,
-      } satisfies ChannelDirectoryEntry,
-    ];
+    return [createGroupDirectoryEntry({ id: roomId, name: query, handle: query })];
   }
 
   if (query.startsWith("!")) {
-    return [
-      {
-        kind: "group",
-        id: query,
-        name: query,
-      } satisfies ChannelDirectoryEntry,
-    ];
+    return [createGroupDirectoryEntry({ id: query, name: query })];
   }
 
   const joined = await fetchMatrixJson<MatrixJoinedRoomsResponse>({

package/src/matrix/actions/limits.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest";
+import { resolveMatrixActionLimit } from "./limits.js";
+
+describe("resolveMatrixActionLimit", () => {
+  it("uses fallback for non-finite values", () => {
+    expect(resolveMatrixActionLimit(undefined, 20)).toBe(20);
+    expect(resolveMatrixActionLimit(Number.NaN, 20)).toBe(20);
+  });
+
+  it("normalizes finite numbers to positive integers", () => {
+    expect(resolveMatrixActionLimit(7.9, 20)).toBe(7);
+    expect(resolveMatrixActionLimit(0, 20)).toBe(1);
+    expect(resolveMatrixActionLimit(-3, 20)).toBe(1);
+  });
+});

package/src/matrix/actions/limits.ts

@@ -0,0 +1,6 @@
+export function resolveMatrixActionLimit(raw: unknown, fallback: number): number {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) {
+    return fallback;
+  }
+  return Math.max(1, Math.floor(raw));
+}

package/src/matrix/actions/messages.ts

@@ -1,5 +1,6 @@
 import { resolveMatrixRoomId, sendMessageMatrix } from "../send.js";
 import { resolveActionClient } from "./client.js";
+import { resolveMatrixActionLimit } from "./limits.js";
 import { summarizeMatrixRawEvent } from "./summary.js";
 import {
   EventType,
@@ -95,10 +96,7 @@ export async function readMatrixMessages(
   const { client, stopOnDone } = await resolveActionClient(opts);
   try {
     const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    const limit =
-      typeof opts.limit === "number" && Number.isFinite(opts.limit)
-        ? Math.max(1, Math.floor(opts.limit))
-        : 20;
+    const limit = resolveMatrixActionLimit(opts.limit, 20);
     const token = opts.before?.trim() || opts.after?.trim() || undefined;
     const dir = opts.after ? "f" : "b";
     // @vector-im/matrix-bot-sdk uses doRequest for room messages

package/src/matrix/actions/pins.test.ts

@@ -0,0 +1,74 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import { describe, expect, it, vi } from "vitest";
+import { listMatrixPins, pinMatrixMessage, unpinMatrixMessage } from "./pins.js";
+
+function createPinsClient(seedPinned: string[], knownBodies: Record<string, string> = {}) {
+  let pinned = [...seedPinned];
+  const getRoomStateEvent = vi.fn(async () => ({ pinned: [...pinned] }));
+  const sendStateEvent = vi.fn(
+    async (_roomId: string, _type: string, _key: string, payload: any) => {
+      pinned = [...payload.pinned];
+    },
+  );
+  const getEvent = vi.fn(async (_roomId: string, eventId: string) => {
+    const body = knownBodies[eventId];
+    if (!body) {
+      throw new Error("missing");
+    }
+    return {
+      event_id: eventId,
+      sender: "@alice:example.org",
+      type: "m.room.message",
+      origin_server_ts: 123,
+      content: { msgtype: "m.text", body },
+    };
+  });
+
+  return {
+    client: {
+      getRoomStateEvent,
+      sendStateEvent,
+      getEvent,
+      stop: vi.fn(),
+    } as unknown as MatrixClient,
+    getPinned: () => pinned,
+    sendStateEvent,
+  };
+}
+
+describe("matrix pins actions", () => {
+  it("pins a message once even when asked twice", async () => {
+    const { client, getPinned, sendStateEvent } = createPinsClient(["$a"]);
+
+    const first = await pinMatrixMessage("!room:example.org", "$b", { client });
+    const second = await pinMatrixMessage("!room:example.org", "$b", { client });
+
+    expect(first.pinned).toEqual(["$a", "$b"]);
+    expect(second.pinned).toEqual(["$a", "$b"]);
+    expect(getPinned()).toEqual(["$a", "$b"]);
+    expect(sendStateEvent).toHaveBeenCalledTimes(2);
+  });
+
+  it("unpinds only the selected message id", async () => {
+    const { client, getPinned } = createPinsClient(["$a", "$b", "$c"]);
+
+    const result = await unpinMatrixMessage("!room:example.org", "$b", { client });
+
+    expect(result.pinned).toEqual(["$a", "$c"]);
+    expect(getPinned()).toEqual(["$a", "$c"]);
+  });
+
+  it("lists pinned ids and summarizes only resolvable events", async () => {
+    const { client } = createPinsClient(["$a", "$missing"], { $a: "hello" });
+
+    const result = await listMatrixPins("!room:example.org", { client });
+
+    expect(result.pinned).toEqual(["$a", "$missing"]);
+    expect(result.events).toEqual([
+      expect.objectContaining({
+        eventId: "$a",
+        body: "hello",
+      }),
+    ]);
+  });
+});

package/src/matrix/actions/pins.ts

@@ -4,23 +4,22 @@ import { fetchEventSummary, readPinnedEvents } from "./summary.js";
 import {
   EventType,
   type MatrixActionClientOpts,
+  type MatrixActionClient,
   type MatrixMessageSummary,
   type RoomPinnedEventsEventContent,
 } from "./types.js";
 
-export async function pinMatrixMessage(
+type ActionClient = MatrixActionClient["client"];
+
+async function withResolvedPinRoom<T>(
   roomId: string,
-  messageId: string,
-  opts: MatrixActionClientOpts = {},
-): Promise<{ pinned: string[] }> {
+  opts: MatrixActionClientOpts,
+  run: (client: ActionClient, resolvedRoom: string) => Promise<T>,
+): Promise<T> {
   const { client, stopOnDone } = await resolveActionClient(opts);
   try {
     const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    const current = await readPinnedEvents(client, resolvedRoom);
-    const next = current.includes(messageId) ? current : [...current, messageId];
-    const payload: RoomPinnedEventsEventContent = { pinned: next };
-    await client.sendStateEvent(resolvedRoom, EventType.RoomPinnedEvents, "", payload);
-    return { pinned: next };
+    return await run(client, resolvedRoom);
   } finally {
     if (stopOnDone) {
       client.stop();
@@ -28,33 +27,46 @@ export async function pinMatrixMessage(
   }
 }
 
-export async function unpinMatrixMessage(
+async function updateMatrixPins(
   roomId: string,
   messageId: string,
-  opts: MatrixActionClientOpts = {},
+  opts: MatrixActionClientOpts,
+  update: (current: string[]) => string[],
 ): Promise<{ pinned: string[] }> {
-  const { client, stopOnDone } = await resolveActionClient(opts);
-  try {
-    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+  return await withResolvedPinRoom(roomId, opts, async (client, resolvedRoom) => {
     const current = await readPinnedEvents(client, resolvedRoom);
-    const next = current.filter((id) => id !== messageId);
+    const next = update(current);
     const payload: RoomPinnedEventsEventContent = { pinned: next };
     await client.sendStateEvent(resolvedRoom, EventType.RoomPinnedEvents, "", payload);
     return { pinned: next };
-  } finally {
-    if (stopOnDone) {
-      client.stop();
-    }
-  }
+  });
+}
+
+export async function pinMatrixMessage(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts = {},
+): Promise<{ pinned: string[] }> {
+  return await updateMatrixPins(roomId, messageId, opts, (current) =>
+    current.includes(messageId) ? current : [...current, messageId],
+  );
+}
+
+export async function unpinMatrixMessage(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts = {},
+): Promise<{ pinned: string[] }> {
+  return await updateMatrixPins(roomId, messageId, opts, (current) =>
+    current.filter((id) => id !== messageId),
+  );
 }
 
 export async function listMatrixPins(
   roomId: string,
   opts: MatrixActionClientOpts = {},
 ): Promise<{ pinned: string[]; events: MatrixMessageSummary[] }> {
-  const { client, stopOnDone } = await resolveActionClient(opts);
-  try {
-    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+  return await withResolvedPinRoom(roomId, opts, async (client, resolvedRoom) => {
     const pinned = await readPinnedEvents(client, resolvedRoom);
     const events = (
       await Promise.all(
@@ -68,9 +80,5 @@ export async function listMatrixPins(
       )
     ).filter((event): event is MatrixMessageSummary => Boolean(event));
     return { pinned, events };
-  } finally {
-    if (stopOnDone) {
-      client.stop();
-    }
-  }
+  });
 }

package/src/matrix/actions/reactions.test.ts

@@ -0,0 +1,109 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import { describe, expect, it, vi } from "vitest";
+import { listMatrixReactions, removeMatrixReactions } from "./reactions.js";
+
+function createReactionsClient(params: {
+  chunk: Array<{
+    event_id?: string;
+    sender?: string;
+    key?: string;
+  }>;
+  userId?: string | null;
+}) {
+  const doRequest = vi.fn(async (_method: string, _path: string, _query: any) => ({
+    chunk: params.chunk.map((item) => ({
+      event_id: item.event_id ?? "",
+      sender: item.sender ?? "",
+      content: item.key
+        ? {
+            "m.relates_to": {
+              rel_type: "m.annotation",
+              event_id: "$target",
+              key: item.key,
+            },
+          }
+        : {},
+    })),
+  }));
+  const getUserId = vi.fn(async () => params.userId ?? null);
+  const redactEvent = vi.fn(async () => undefined);
+
+  return {
+    client: {
+      doRequest,
+      getUserId,
+      redactEvent,
+      stop: vi.fn(),
+    } as unknown as MatrixClient,
+    doRequest,
+    redactEvent,
+  };
+}
+
+describe("matrix reaction actions", () => {
+  it("aggregates reactions by key and unique sender", async () => {
+    const { client, doRequest } = createReactionsClient({
+      chunk: [
+        { event_id: "$1", sender: "@alice:example.org", key: "👍" },
+        { event_id: "$2", sender: "@bob:example.org", key: "👍" },
+        { event_id: "$3", sender: "@alice:example.org", key: "👎" },
+        { event_id: "$4", sender: "@bot:example.org" },
+      ],
+      userId: "@bot:example.org",
+    });
+
+    const result = await listMatrixReactions("!room:example.org", "$msg", { client, limit: 2.9 });
+
+    expect(doRequest).toHaveBeenCalledWith(
+      "GET",
+      expect.stringContaining("/rooms/!room%3Aexample.org/relations/%24msg/"),
+      expect.objectContaining({ limit: 2 }),
+    );
+    expect(result).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          key: "👍",
+          count: 2,
+          users: expect.arrayContaining(["@alice:example.org", "@bob:example.org"]),
+        }),
+        expect.objectContaining({
+          key: "👎",
+          count: 1,
+          users: ["@alice:example.org"],
+        }),
+      ]),
+    );
+  });
+
+  it("removes only current-user reactions matching emoji filter", async () => {
+    const { client, redactEvent } = createReactionsClient({
+      chunk: [
+        { event_id: "$1", sender: "@me:example.org", key: "👍" },
+        { event_id: "$2", sender: "@me:example.org", key: "👎" },
+        { event_id: "$3", sender: "@other:example.org", key: "👍" },
+      ],
+      userId: "@me:example.org",
+    });
+
+    const result = await removeMatrixReactions("!room:example.org", "$msg", {
+      client,
+      emoji: "👍",
+    });
+
+    expect(result).toEqual({ removed: 1 });
+    expect(redactEvent).toHaveBeenCalledTimes(1);
+    expect(redactEvent).toHaveBeenCalledWith("!room:example.org", "$1");
+  });
+
+  it("returns removed=0 when current user id is unavailable", async () => {
+    const { client, redactEvent } = createReactionsClient({
+      chunk: [{ event_id: "$1", sender: "@me:example.org", key: "👍" }],
+      userId: null,
+    });
+
+    const result = await removeMatrixReactions("!room:example.org", "$msg", { client });
+
+    expect(result).toEqual({ removed: 0 });
+    expect(redactEvent).not.toHaveBeenCalled();
+  });
+});

package/src/matrix/actions/reactions.ts

@@ -1,5 +1,6 @@
 import { resolveMatrixRoomId } from "../send.js";
 import { resolveActionClient } from "./client.js";
+import { resolveMatrixActionLimit } from "./limits.js";
 import {
   EventType,
   RelationType,
@@ -9,6 +10,23 @@ import {
   type ReactionEventContent,
 } from "./types.js";
 
+function getReactionsPath(roomId: string, messageId: string): string {
+  return `/_matrix/client/v1/rooms/${encodeURIComponent(roomId)}/relations/${encodeURIComponent(messageId)}/${RelationType.Annotation}/${EventType.Reaction}`;
+}
+
+async function listReactionEvents(
+  client: NonNullable<MatrixActionClientOpts["client"]>,
+  roomId: string,
+  messageId: string,
+  limit: number,
+): Promise<MatrixRawEvent[]> {
+  const res = (await client.doRequest("GET", getReactionsPath(roomId, messageId), {
+    dir: "b",
+    limit,
+  })) as { chunk: MatrixRawEvent[] };
+  return res.chunk;
+}
+
 export async function listMatrixReactions(
   roomId: string,
   messageId: string,
@@ -17,18 +35,10 @@ export async function listMatrixReactions(
   const { client, stopOnDone } = await resolveActionClient(opts);
   try {
     const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    const limit =
-      typeof opts.limit === "number" && Number.isFinite(opts.limit)
-        ? Math.max(1, Math.floor(opts.limit))
-        : 100;
-    // @vector-im/matrix-bot-sdk uses doRequest for relations
-    const res = (await client.doRequest(
-      "GET",
-      `/_matrix/client/v1/rooms/${encodeURIComponent(resolvedRoom)}/relations/${encodeURIComponent(messageId)}/${RelationType.Annotation}/${EventType.Reaction}`,
-      { dir: "b", limit },
-    )) as { chunk: MatrixRawEvent[] };
+    const limit = resolveMatrixActionLimit(opts.limit, 100);
+    const chunk = await listReactionEvents(client, resolvedRoom, messageId, limit);
     const summaries = new Map<string, MatrixReactionSummary>();
-    for (const event of res.chunk) {
+    for (const event of chunk) {
       const content = event.content as ReactionEventContent;
       const key = content["m.relates_to"]?.key;
       if (!key) {
@@ -62,17 +72,13 @@ export async function removeMatrixReactions(
   const { client, stopOnDone } = await resolveActionClient(opts);
   try {
     const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    const res = (await client.doRequest(
-      "GET",
-      `/_matrix/client/v1/rooms/${encodeURIComponent(resolvedRoom)}/relations/${encodeURIComponent(messageId)}/${RelationType.Annotation}/${EventType.Reaction}`,
-      { dir: "b", limit: 200 },
-    )) as { chunk: MatrixRawEvent[] };
+    const chunk = await listReactionEvents(client, resolvedRoom, messageId, 200);
     const userId = await client.getUserId();
     if (!userId) {
       return { removed: 0 };
     }
     const targetEmoji = opts.emoji?.trim();
-    const toRemove = res.chunk
+    const toRemove = chunk
       .filter((event) => event.sender === userId)
       .filter((event) => {
         if (!targetEmoji) {

package/src/matrix/deps.ts

@@ -1,9 +1,9 @@
+import { spawn } from "node:child_process";
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { RuntimeEnv } from "openclaw/plugin-sdk";
-import { getMatrixRuntime } from "../runtime.js";
 
 const MATRIX_SDK_PACKAGE = "@vector-im/matrix-bot-sdk";
 
@@ -22,6 +22,85 @@ function resolvePluginRoot(): string {
   return path.resolve(currentDir, "..", "..");
 }
 
+type CommandResult = {
+  code: number;
+  stdout: string;
+  stderr: string;
+};
+
+async function runFixedCommandWithTimeout(params: {
+  argv: string[];
+  cwd: string;
+  timeoutMs: number;
+  env?: NodeJS.ProcessEnv;
+}): Promise<CommandResult> {
+  return await new Promise((resolve) => {
+    const [command, ...args] = params.argv;
+    if (!command) {
+      resolve({
+        code: 1,
+        stdout: "",
+        stderr: "command is required",
+      });
+      return;
+    }
+
+    const proc = spawn(command, args, {
+      cwd: params.cwd,
+      env: { ...process.env, ...params.env },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timer: NodeJS.Timeout | null = null;
+
+    const finalize = (result: CommandResult) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (timer) {
+        clearTimeout(timer);
+      }
+      resolve(result);
+    };
+
+    proc.stdout?.on("data", (chunk: Buffer | string) => {
+      stdout += chunk.toString();
+    });
+    proc.stderr?.on("data", (chunk: Buffer | string) => {
+      stderr += chunk.toString();
+    });
+
+    timer = setTimeout(() => {
+      proc.kill("SIGKILL");
+      finalize({
+        code: 124,
+        stdout,
+        stderr: stderr || `command timed out after ${params.timeoutMs}ms`,
+      });
+    }, params.timeoutMs);
+
+    proc.on("error", (err) => {
+      finalize({
+        code: 1,
+        stdout,
+        stderr: err.message,
+      });
+    });
+
+    proc.on("close", (code) => {
+      finalize({
+        code: code ?? 1,
+        stdout,
+        stderr,
+      });
+    });
+  });
+}
+
 export async function ensureMatrixSdkInstalled(params: {
   runtime: RuntimeEnv;
   confirm?: (message: string) => Promise<boolean>;
@@ -42,7 +121,8 @@ export async function ensureMatrixSdkInstalled(params: {
     ? ["pnpm", "install"]
     : ["npm", "install", "--omit=dev", "--silent"];
   params.runtime.log?.(`matrix: installing dependencies via ${command[0]} (${root})…`);
-  const result = await getMatrixRuntime().system.runCommandWithTimeout(command, {
+  const result = await runFixedCommandWithTimeout({
+    argv: command,
     cwd: root,
     timeoutMs: 300_000,
     env: { COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" },

package/src/matrix/monitor/mentions.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it, vi } from "vitest";
+
+// Mock the runtime before importing resolveMentions
+vi.mock("../../runtime.js", () => ({
+  getMatrixRuntime: () => ({
+    channel: {
+      mentions: {
+        matchesMentionPatterns: (text: string, patterns: RegExp[]) =>
+          patterns.some((p) => p.test(text)),
+      },
+    },
+  }),
+}));
+
+import { resolveMentions } from "./mentions.js";
+
+describe("resolveMentions", () => {
+  const userId = "@bot:matrix.org";
+  const mentionRegexes = [/@bot/i];
+
+  describe("m.mentions field", () => {
+    it("detects mention via m.mentions.user_ids", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "hello",
+          "m.mentions": { user_ids: ["@bot:matrix.org"] },
+        },
+        userId,
+        text: "hello",
+        mentionRegexes,
+      });
+      expect(result.wasMentioned).toBe(true);
+      expect(result.hasExplicitMention).toBe(true);
+    });
+
+    it("detects room mention via m.mentions.room", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "hello everyone",
+          "m.mentions": { room: true },
+        },
+        userId,
+        text: "hello everyone",
+        mentionRegexes,
+      });
+      expect(result.wasMentioned).toBe(true);
+    });
+  });
+
+  describe("formatted_body matrix.to links", () => {
+    it("detects mention in formatted_body with plain user ID", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "Bot: hello",
+          formatted_body: '<a href="https://matrix.to/#/@bot:matrix.org">Bot</a>: hello',
+        },
+        userId,
+        text: "Bot: hello",
+        mentionRegexes: [],
+      });
+      expect(result.wasMentioned).toBe(true);
+    });
+
+    it("detects mention in formatted_body with URL-encoded user ID", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "Bot: hello",
+          formatted_body: '<a href="https://matrix.to/#/%40bot%3Amatrix.org">Bot</a>: hello',
+        },
+        userId,
+        text: "Bot: hello",
+        mentionRegexes: [],
+      });
+      expect(result.wasMentioned).toBe(true);
+    });
+
+    it("detects mention with single quotes in href", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "Bot: hello",
+          formatted_body: "<a href='https://matrix.to/#/@bot:matrix.org'>Bot</a>: hello",
+        },
+        userId,
+        text: "Bot: hello",
+        mentionRegexes: [],
+      });
+      expect(result.wasMentioned).toBe(true);
+    });
+
+    it("does not detect mention for different user ID", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "Other: hello",
+          formatted_body: '<a href="https://matrix.to/#/@other:matrix.org">Other</a>: hello',
+        },
+        userId,
+        text: "Other: hello",
+        mentionRegexes: [],
+      });
+      expect(result.wasMentioned).toBe(false);
+    });
+
+    it("does not false-positive on partial user ID match", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "Bot2: hello",
+          formatted_body: '<a href="https://matrix.to/#/@bot2:matrix.org">Bot2</a>: hello',
+        },
+        userId: "@bot:matrix.org",
+        text: "Bot2: hello",
+        mentionRegexes: [],
+      });
+      expect(result.wasMentioned).toBe(false);
+    });
+  });
+
+  describe("regex patterns", () => {
+    it("detects mention via regex pattern in body text", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "hey @bot can you help?",
+        },
+        userId,
+        text: "hey @bot can you help?",
+        mentionRegexes,
+      });
+      expect(result.wasMentioned).toBe(true);
+    });
+  });
+
+  describe("no mention", () => {
+    it("returns false when no mention is present", () => {
+      const result = resolveMentions({
+        content: {
+          msgtype: "m.text",
+          body: "hello world",
+        },
+        userId,
+        text: "hello world",
+        mentionRegexes,
+      });
+      expect(result.wasMentioned).toBe(false);
+      expect(result.hasExplicitMention).toBe(false);
+    });
+  });
+});

package/src/matrix/monitor/mentions.ts

@@ -4,12 +4,36 @@ import { getMatrixRuntime } from "../../runtime.js";
 type MessageContentWithMentions = {
   msgtype: string;
   body: string;
+  formatted_body?: string;
   "m.mentions"?: {
     user_ids?: string[];
     room?: boolean;
   };
 };
 
+/**
+ * Check if the formatted_body contains a matrix.to mention link for the given user ID.
+ * Many Matrix clients (including Element) use HTML links in formatted_body instead of
+ * or in addition to the m.mentions field.
+ */
+function checkFormattedBodyMention(formattedBody: string | undefined, userId: string): boolean {
+  if (!formattedBody || !userId) {
+    return false;
+  }
+  // Escape special regex characters in the user ID (e.g., @user:matrix.org)
+  const escapedUserId = userId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // Match matrix.to links with the user ID, handling both URL-encoded and plain formats
+  // Example: href="https://matrix.to/#/@user:matrix.org" or href="https://matrix.to/#/%40user%3Amatrix.org"
+  const plainPattern = new RegExp(`href=["']https://matrix\\.to/#/${escapedUserId}["']`, "i");
+  if (plainPattern.test(formattedBody)) {
+    return true;
+  }
+  // Also check URL-encoded version (@ -> %40, : -> %3A)
+  const encodedUserId = encodeURIComponent(userId).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const encodedPattern = new RegExp(`href=["']https://matrix\\.to/#/${encodedUserId}["']`, "i");
+  return encodedPattern.test(formattedBody);
+}
+
 export function resolveMentions(params: {
   content: MessageContentWithMentions;
   userId?: string | null;
@@ -20,9 +44,16 @@ export function resolveMentions(params: {
   const mentionedUsers = Array.isArray(mentions?.user_ids)
     ? new Set(mentions.user_ids)
     : new Set<string>();
+
+  // Check formatted_body for matrix.to mention links (legacy/alternative mention format)
+  const mentionedInFormattedBody = params.userId
+    ? checkFormattedBodyMention(params.content.formatted_body, params.userId)
+    : false;
+
   const wasMentioned =
     Boolean(mentions?.room) ||
     (params.userId ? mentionedUsers.has(params.userId) : false) ||
+    mentionedInFormattedBody ||
     getMatrixRuntime().channel.mentions.matchesMentionPatterns(
       params.text ?? "",
       params.mentionRegexes,

package/src/resolve-targets.test.ts

@@ -1,6 +1,6 @@
 import type { ChannelDirectoryEntry } from "openclaw/plugin-sdk";
 import { describe, expect, it, vi, beforeEach } from "vitest";
-import { listMatrixDirectoryPeersLive } from "./directory-live.js";
+import { listMatrixDirectoryGroupsLive, listMatrixDirectoryPeersLive } from "./directory-live.js";
 import { resolveMatrixTargets } from "./resolve-targets.js";
 
 vi.mock("./directory-live.js", () => ({
@@ -11,6 +11,7 @@ vi.mock("./directory-live.js", () => ({
 describe("resolveMatrixTargets (users)", () => {
   beforeEach(() => {
     vi.mocked(listMatrixDirectoryPeersLive).mockReset();
+    vi.mocked(listMatrixDirectoryGroupsLive).mockReset();
   });
 
   it("resolves exact unique display name matches", async () => {
@@ -45,4 +46,22 @@ describe("resolveMatrixTargets (users)", () => {
     expect(result?.resolved).toBe(false);
     expect(result?.note).toMatch(/use full Matrix ID/i);
   });
+
+  it("prefers exact group matches over first partial result", async () => {
+    const matches: ChannelDirectoryEntry[] = [
+      { kind: "group", id: "!one:example.org", name: "General", handle: "#general" },
+      { kind: "group", id: "!two:example.org", name: "Team", handle: "#team" },
+    ];
+    vi.mocked(listMatrixDirectoryGroupsLive).mockResolvedValue(matches);
+
+    const [result] = await resolveMatrixTargets({
+      cfg: {},
+      inputs: ["#team"],
+      kind: "group",
+    });
+
+    expect(result?.resolved).toBe(true);
+    expect(result?.id).toBe("!two:example.org");
+    expect(result?.note).toBe("multiple matches; chose first");
+  });
 });

package/src/resolve-targets.ts

@@ -6,6 +6,22 @@ import type {
 } from "openclaw/plugin-sdk";
 import { listMatrixDirectoryGroupsLive, listMatrixDirectoryPeersLive } from "./directory-live.js";
 
+function findExactDirectoryMatches(
+  matches: ChannelDirectoryEntry[],
+  query: string,
+): ChannelDirectoryEntry[] {
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) {
+    return [];
+  }
+  return matches.filter((match) => {
+    const id = match.id.trim().toLowerCase();
+    const name = match.name?.trim().toLowerCase();
+    const handle = match.handle?.trim().toLowerCase();
+    return normalized === id || normalized === name || normalized === handle;
+  });
+}
+
 function pickBestGroupMatch(
   matches: ChannelDirectoryEntry[],
   query: string,
@@ -13,19 +29,8 @@ function pickBestGroupMatch(
   if (matches.length === 0) {
     return undefined;
   }
-  const normalized = query.trim().toLowerCase();
-  if (normalized) {
-    const exact = matches.find((match) => {
-      const name = match.name?.trim().toLowerCase();
-      const handle = match.handle?.trim().toLowerCase();
-      const id = match.id.trim().toLowerCase();
-      return name === normalized || handle === normalized || id === normalized;
-    });
-    if (exact) {
-      return exact;
-    }
-  }
-  return matches[0];
+  const [exact] = findExactDirectoryMatches(matches, query);
+  return exact ?? matches[0];
 }
 
 function pickBestUserMatch(
@@ -35,16 +40,7 @@ function pickBestUserMatch(
   if (matches.length === 0) {
     return undefined;
   }
-  const normalized = query.trim().toLowerCase();
-  if (!normalized) {
-    return undefined;
-  }
-  const exact = matches.filter((match) => {
-    const id = match.id.trim().toLowerCase();
-    const name = match.name?.trim().toLowerCase();
-    const handle = match.handle?.trim().toLowerCase();
-    return normalized === id || normalized === name || normalized === handle;
-  });
+  const exact = findExactDirectoryMatches(matches, query);
   if (exact.length === 1) {
     return exact[0];
   }
@@ -59,12 +55,7 @@ function describeUserMatchFailure(matches: ChannelDirectoryEntry[], query: strin
   if (!normalized) {
     return "empty input";
   }
-  const exact = matches.filter((match) => {
-    const id = match.id.trim().toLowerCase();
-    const name = match.name?.trim().toLowerCase();
-    const handle = match.handle?.trim().toLowerCase();
-    return normalized === id || normalized === name || normalized === handle;
-  });
+  const exact = findExactDirectoryMatches(matches, normalized);
   if (exact.length === 0) {
     return "no exact match; use full Matrix ID";
   }