@openclaw/matrix 2026.2.25 → 2026.3.1

package/src/matrix/monitor/events.ts

@@ -5,6 +5,21 @@ import { sendReadReceiptMatrix } from "../send.js";
 import type { MatrixRawEvent } from "./types.js";
 import { EventType } from "./types.js";
 
+const matrixMonitorListenerRegistry = (() => {
+  // Prevent duplicate listener registration when both bundled and extension
+  // paths attempt to start monitors against the same shared client.
+  const registeredClients = new WeakSet<object>();
+  return {
+    tryRegister(client: object): boolean {
+      if (registeredClients.has(client)) {
+        return false;
+      }
+      registeredClients.add(client);
+      return true;
+    },
+  };
+})();
+
 function createSelfUserIdResolver(client: Pick<MatrixClient, "getUserId">) {
   let selfUserId: string | undefined;
   let selfUserIdLookup: Promise<string | undefined> | undefined;
@@ -41,6 +56,11 @@ export function registerMatrixMonitorEvents(params: {
   formatNativeDependencyHint: PluginRuntime["system"]["formatNativeDependencyHint"];
   onRoomMessage: (roomId: string, event: MatrixRawEvent) => void | Promise<void>;
 }): void {
+  if (!matrixMonitorListenerRegistry.tryRegister(params.client)) {
+    params.logVerboseMessage("matrix: skipping duplicate listener registration for client");
+    return;
+  }
+
   const {
     client,
     auth,

package/src/matrix/monitor/handler.body-for-agent.test.ts

@@ -0,0 +1,142 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import type { PluginRuntime, RuntimeEnv, RuntimeLogger } from "openclaw/plugin-sdk";
+import { describe, expect, it, vi } from "vitest";
+import { createMatrixRoomMessageHandler } from "./handler.js";
+import { EventType, type MatrixRawEvent } from "./types.js";
+
+describe("createMatrixRoomMessageHandler BodyForAgent sender label", () => {
+  it("stores sender-labeled BodyForAgent for group thread messages", async () => {
+    const recordInboundSession = vi.fn().mockResolvedValue(undefined);
+    const formatInboundEnvelope = vi
+      .fn()
+      .mockImplementation((params: { senderLabel?: string; body: string }) => params.body);
+    const finalizeInboundContext = vi
+      .fn()
+      .mockImplementation((ctx: Record<string, unknown>) => ctx);
+
+    const core = {
+      channel: {
+        pairing: {
+          readAllowFromStore: vi.fn().mockResolvedValue([]),
+        },
+        routing: {
+          resolveAgentRoute: vi.fn().mockReturnValue({
+            agentId: "main",
+            accountId: undefined,
+            sessionKey: "agent:main:matrix:channel:!room:example.org",
+            mainSessionKey: "agent:main:main",
+          }),
+        },
+        session: {
+          resolveStorePath: vi.fn().mockReturnValue("/tmp/openclaw-test-session.json"),
+          readSessionUpdatedAt: vi.fn().mockReturnValue(123),
+          recordInboundSession,
+        },
+        reply: {
+          resolveEnvelopeFormatOptions: vi.fn().mockReturnValue({}),
+          formatInboundEnvelope,
+          formatAgentEnvelope: vi
+            .fn()
+            .mockImplementation((params: { body: string }) => params.body),
+          finalizeInboundContext,
+          resolveHumanDelayConfig: vi.fn().mockReturnValue(undefined),
+          createReplyDispatcherWithTyping: vi.fn().mockReturnValue({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+          }),
+          withReplyDispatcher: vi
+            .fn()
+            .mockResolvedValue({ queuedFinal: false, counts: { final: 0, partial: 0, tool: 0 } }),
+        },
+        commands: {
+          shouldHandleTextCommands: vi.fn().mockReturnValue(true),
+        },
+        text: {
+          hasControlCommand: vi.fn().mockReturnValue(false),
+          resolveMarkdownTableMode: vi.fn().mockReturnValue("code"),
+        },
+      },
+      system: {
+        enqueueSystemEvent: vi.fn(),
+      },
+    } as unknown as PluginRuntime;
+
+    const runtime = {
+      error: vi.fn(),
+    } as unknown as RuntimeEnv;
+    const logger = {
+      info: vi.fn(),
+      warn: vi.fn(),
+    } as unknown as RuntimeLogger;
+    const logVerboseMessage = vi.fn();
+
+    const client = {
+      getUserId: vi.fn().mockResolvedValue("@bot:matrix.example.org"),
+    } as unknown as MatrixClient;
+
+    const handler = createMatrixRoomMessageHandler({
+      client,
+      core,
+      cfg: {},
+      runtime,
+      logger,
+      logVerboseMessage,
+      allowFrom: [],
+      roomsConfig: undefined,
+      mentionRegexes: [],
+      groupPolicy: "open",
+      replyToMode: "first",
+      threadReplies: "inbound",
+      dmEnabled: true,
+      dmPolicy: "open",
+      textLimit: 4000,
+      mediaMaxBytes: 5 * 1024 * 1024,
+      startupMs: Date.now(),
+      startupGraceMs: 60_000,
+      directTracker: {
+        isDirectMessage: vi.fn().mockResolvedValue(false),
+      },
+      getRoomInfo: vi.fn().mockResolvedValue({
+        name: "Dev Room",
+        canonicalAlias: "#dev:matrix.example.org",
+        altAliases: [],
+      }),
+      getMemberDisplayName: vi.fn().mockResolvedValue("Bu"),
+      accountId: undefined,
+    });
+
+    const event = {
+      type: EventType.RoomMessage,
+      event_id: "$event1",
+      sender: "@bu:matrix.example.org",
+      origin_server_ts: Date.now(),
+      content: {
+        msgtype: "m.text",
+        body: "show me my commits",
+        "m.mentions": { user_ids: ["@bot:matrix.example.org"] },
+        "m.relates_to": {
+          rel_type: "m.thread",
+          event_id: "$thread-root",
+        },
+      },
+    } as unknown as MatrixRawEvent;
+
+    await handler("!room:example.org", event);
+
+    expect(formatInboundEnvelope).toHaveBeenCalledWith(
+      expect.objectContaining({
+        chatType: "channel",
+        senderLabel: "Bu (bu)",
+      }),
+    );
+    expect(recordInboundSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ctx: expect.objectContaining({
+          ChatType: "thread",
+          BodyForAgent: "Bu (bu): show me my commits",
+        }),
+      }),
+    );
+  });
+});

package/src/matrix/monitor/handler.ts

@@ -1,5 +1,7 @@
 import type { LocationMessageEventContent, MatrixClient } from "@vector-im/matrix-bot-sdk";
 import {
+  DEFAULT_ACCOUNT_ID,
+  createScopedPairingAccess,
   createReplyPrefixOptions,
   createTypingCallbacks,
   formatAllowlistMatchMeta,
@@ -19,11 +21,17 @@ import {
   type PollStartContent,
 } from "../poll-types.js";
 import { reactMatrixMessage, sendMessageMatrix, sendTypingMatrix } from "../send.js";
+import { enforceMatrixDirectMessageAccess, resolveMatrixAccessState } from "./access-policy.js";
 import {
   normalizeMatrixAllowList,
   resolveMatrixAllowListMatch,
   resolveMatrixAllowListMatches,
 } from "./allowlist.js";
+import {
+  resolveMatrixBodyForAgent,
+  resolveMatrixInboundSenderLabel,
+  resolveMatrixSenderUsername,
+} from "./inbound-body.js";
 import { resolveMatrixLocation, type MatrixLocationPayload } from "./location.js";
 import { downloadMatrixMedia } from "./media.js";
 import { resolveMentions } from "./mentions.js";
@@ -91,6 +99,12 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
     getMemberDisplayName,
     accountId,
   } = params;
+  const resolvedAccountId = accountId?.trim() || DEFAULT_ACCOUNT_ID;
+  const pairing = createScopedPairingAccess({
+    core,
+    channel: "matrix",
+    accountId: resolvedAccountId,
+  });
 
   return async (roomId: string, event: MatrixRawEvent) => {
     try {
@@ -213,62 +227,42 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
       }
 
       const senderName = await getMemberDisplayName(roomId, senderId);
-      const storeAllowFrom =
-        dmPolicy === "allowlist"
-          ? []
-          : await core.channel.pairing.readAllowFromStore("matrix").catch(() => []);
-      const effectiveAllowFrom = normalizeMatrixAllowList([...allowFrom, ...storeAllowFrom]);
+      const senderUsername = resolveMatrixSenderUsername(senderId);
+      const senderLabel = resolveMatrixInboundSenderLabel({
+        senderName,
+        senderId,
+        senderUsername,
+      });
       const groupAllowFrom = cfg.channels?.matrix?.groupAllowFrom ?? [];
-      const effectiveGroupAllowFrom = normalizeMatrixAllowList(groupAllowFrom);
-      const groupAllowConfigured = effectiveGroupAllowFrom.length > 0;
+      const { access, effectiveAllowFrom, effectiveGroupAllowFrom, groupAllowConfigured } =
+        await resolveMatrixAccessState({
+          isDirectMessage,
+          resolvedAccountId,
+          dmPolicy,
+          groupPolicy,
+          allowFrom,
+          groupAllowFrom,
+          senderId,
+          readStoreForDmPolicy: pairing.readStoreForDmPolicy,
+        });
 
       if (isDirectMessage) {
-        if (!dmEnabled || dmPolicy === "disabled") {
+        const allowedDirectMessage = await enforceMatrixDirectMessageAccess({
+          dmEnabled,
+          dmPolicy,
+          accessDecision: access.decision,
+          senderId,
+          senderName,
+          effectiveAllowFrom,
+          upsertPairingRequest: pairing.upsertPairingRequest,
+          sendPairingReply: async (text) => {
+            await sendMessageMatrix(`room:${roomId}`, text, { client });
+          },
+          logVerboseMessage,
+        });
+        if (!allowedDirectMessage) {
           return;
         }
-        if (dmPolicy !== "open") {
-          const allowMatch = resolveMatrixAllowListMatch({
-            allowList: effectiveAllowFrom,
-            userId: senderId,
-          });
-          const allowMatchMeta = formatAllowlistMatchMeta(allowMatch);
-          if (!allowMatch.allowed) {
-            if (dmPolicy === "pairing") {
-              const { code, created } = await core.channel.pairing.upsertPairingRequest({
-                channel: "matrix",
-                id: senderId,
-                meta: { name: senderName },
-              });
-              if (created) {
-                logVerboseMessage(
-                  `matrix pairing request sender=${senderId} name=${senderName ?? "unknown"} (${allowMatchMeta})`,
-                );
-                try {
-                  await sendMessageMatrix(
-                    `room:${roomId}`,
-                    [
-                      "OpenClaw: access not configured.",
-                      "",
-                      `Pairing code: ${code}`,
-                      "",
-                      "Ask the bot owner to approve with:",
-                      "openclaw pairing approve matrix <code>",
-                    ].join("\n"),
-                    { client },
-                  );
-                } catch (err) {
-                  logVerboseMessage(`matrix pairing reply failed for ${senderId}: ${String(err)}`);
-                }
-              }
-            }
-            if (dmPolicy !== "pairing") {
-              logVerboseMessage(
-                `matrix: blocked dm sender ${senderId} (dmPolicy=${dmPolicy}, ${allowMatchMeta})`,
-              );
-            }
-            return;
-          }
-        }
       }
 
       const roomUsers = roomConfig?.users ?? [];
@@ -286,7 +280,7 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
           return;
         }
       }
-      if (isRoom && groupPolicy === "allowlist" && roomUsers.length === 0 && groupAllowConfigured) {
+      if (isRoom && roomUsers.length === 0 && groupAllowConfigured && access.decision !== "allow") {
         const groupAllowMatch = resolveMatrixAllowListMatch({
           allowList: effectiveGroupAllowFrom,
           userId: senderId,
@@ -498,19 +492,25 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
         storePath,
         sessionKey: route.sessionKey,
       });
-      const body = core.channel.reply.formatAgentEnvelope({
+      const body = core.channel.reply.formatInboundEnvelope({
         channel: "Matrix",
         from: envelopeFrom,
         timestamp: eventTs ?? undefined,
         previousTimestamp,
         envelope: envelopeOptions,
         body: textWithId,
+        chatType: isDirectMessage ? "direct" : "channel",
+        senderLabel,
       });
 
       const groupSystemPrompt = roomConfig?.systemPrompt?.trim() || undefined;
       const ctxPayload = core.channel.reply.finalizeInboundContext({
         Body: body,
-        BodyForAgent: bodyText,
+        BodyForAgent: resolveMatrixBodyForAgent({
+          isDirectMessage,
+          bodyText,
+          senderLabel,
+        }),
         RawBody: bodyText,
         CommandBody: bodyText,
         From: isDirectMessage ? `matrix:${senderId}` : `matrix:channel:${roomId}`,
@@ -521,7 +521,7 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
         ConversationLabel: envelopeFrom,
         SenderName: senderName,
         SenderId: senderId,
-        SenderUsername: senderId.split(":")[0]?.replace(/^@/, ""),
+        SenderUsername: senderUsername,
         GroupSubject: isRoom ? (roomName ?? roomId) : undefined,
         GroupChannel: isRoom ? (roomInfo.canonicalAlias ?? roomId) : undefined,
         GroupSystemPrompt: isRoom ? groupSystemPrompt : undefined,
@@ -655,17 +655,23 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
           },
         });
 
-      const { queuedFinal, counts } = await core.channel.reply.dispatchReplyFromConfig({
-        ctx: ctxPayload,
-        cfg,
+      const { queuedFinal, counts } = await core.channel.reply.withReplyDispatcher({
         dispatcher,
-        replyOptions: {
-          ...replyOptions,
-          skillFilter: roomConfig?.skills,
-          onModelSelected,
+        onSettled: () => {
+          markDispatchIdle();
         },
+        run: () =>
+          core.channel.reply.dispatchReplyFromConfig({
+            ctx: ctxPayload,
+            cfg,
+            dispatcher,
+            replyOptions: {
+              ...replyOptions,
+              skillFilter: roomConfig?.skills,
+              onModelSelected,
+            },
+          }),
       });
-      markDispatchIdle();
       if (!queuedFinal) {
         return;
       }

package/src/matrix/monitor/inbound-body.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import {
+  resolveMatrixBodyForAgent,
+  resolveMatrixInboundSenderLabel,
+  resolveMatrixSenderUsername,
+} from "./inbound-body.js";
+
+describe("resolveMatrixSenderUsername", () => {
+  it("extracts localpart without leading @", () => {
+    expect(resolveMatrixSenderUsername("@bu:matrix.example.org")).toBe("bu");
+  });
+});
+
+describe("resolveMatrixInboundSenderLabel", () => {
+  it("uses provided senderUsername when present", () => {
+    expect(
+      resolveMatrixInboundSenderLabel({
+        senderName: "Bu",
+        senderId: "@bu:matrix.example.org",
+        senderUsername: "BU_CUSTOM",
+      }),
+    ).toBe("Bu (BU_CUSTOM)");
+  });
+
+  it("includes sender username when it differs from display name", () => {
+    expect(
+      resolveMatrixInboundSenderLabel({
+        senderName: "Bu",
+        senderId: "@bu:matrix.example.org",
+      }),
+    ).toBe("Bu (bu)");
+  });
+
+  it("falls back to sender username when display name is blank", () => {
+    expect(
+      resolveMatrixInboundSenderLabel({
+        senderName: " ",
+        senderId: "@zhang:matrix.example.org",
+      }),
+    ).toBe("zhang");
+  });
+
+  it("falls back to sender id when username cannot be parsed", () => {
+    expect(
+      resolveMatrixInboundSenderLabel({
+        senderName: "",
+        senderId: "matrix-user-without-colon",
+      }),
+    ).toBe("matrix-user-without-colon");
+  });
+});
+
+describe("resolveMatrixBodyForAgent", () => {
+  it("keeps direct message body unchanged", () => {
+    expect(
+      resolveMatrixBodyForAgent({
+        isDirectMessage: true,
+        bodyText: "show me my commits",
+        senderLabel: "Bu (bu)",
+      }),
+    ).toBe("show me my commits");
+  });
+
+  it("prefixes non-direct message body with sender label", () => {
+    expect(
+      resolveMatrixBodyForAgent({
+        isDirectMessage: false,
+        bodyText: "show me my commits",
+        senderLabel: "Bu (bu)",
+      }),
+    ).toBe("Bu (bu): show me my commits");
+  });
+});

package/src/matrix/monitor/inbound-body.ts

@@ -0,0 +1,28 @@
+export function resolveMatrixSenderUsername(senderId: string): string | undefined {
+  const username = senderId.split(":")[0]?.replace(/^@/, "").trim();
+  return username ? username : undefined;
+}
+
+export function resolveMatrixInboundSenderLabel(params: {
+  senderName: string;
+  senderId: string;
+  senderUsername?: string;
+}): string {
+  const senderName = params.senderName.trim();
+  const senderUsername = params.senderUsername ?? resolveMatrixSenderUsername(params.senderId);
+  if (senderName && senderUsername && senderName !== senderUsername) {
+    return `${senderName} (${senderUsername})`;
+  }
+  return senderName || senderUsername || params.senderId;
+}
+
+export function resolveMatrixBodyForAgent(params: {
+  isDirectMessage: boolean;
+  bodyText: string;
+  senderLabel: string;
+}): string {
+  if (params.isDirectMessage) {
+    return params.bodyText;
+  }
+  return `${params.senderLabel}: ${params.bodyText}`;
+}

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

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_STARTUP_GRACE_MS, isConfiguredMatrixRoomEntry } from "./index.js";
+
+describe("monitorMatrixProvider helpers", () => {
+  it("treats !-prefixed room IDs as configured room entries", () => {
+    expect(isConfiguredMatrixRoomEntry("!abc123")).toBe(true);
+    expect(isConfiguredMatrixRoomEntry("!RoomMixedCase")).toBe(true);
+  });
+
+  it("requires a homeserver suffix for # aliases", () => {
+    expect(isConfiguredMatrixRoomEntry("#alias:example.org")).toBe(true);
+    expect(isConfiguredMatrixRoomEntry("#alias")).toBe(false);
+  });
+
+  it("uses a non-zero startup grace window", () => {
+    expect(DEFAULT_STARTUP_GRACE_MS).toBe(5000);
+  });
+});