@openclaw/matrix 2026.3.11 → 2026.3.13

package/CHANGELOG.md

@@ -1,8 +1,21 @@
 # Changelog
 
+## 2026.3.13
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.12
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.3.11
 
 ### Changes
+
 - Version alignment with core OpenClaw release numbers.
 
 ## 2026.3.10

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@openclaw/matrix",
-  "version": "2026.3.11",
+  "version": "2026.3.13",
   "description": "OpenClaw Matrix channel plugin",
   "type": "module",
   "dependencies": {
-    "@mariozechner/pi-agent-core": "0.57.1",
+    "@mariozechner/pi-agent-core": "0.58.0",
     "@matrix-org/matrix-sdk-crypto-nodejs": "^0.4.0",
     "@vector-im/matrix-bot-sdk": "0.8.0-element.3",
     "markdown-it": "14.1.1",
-    "music-metadata": "^11.12.1",
+    "music-metadata": "^11.12.3",
     "zod": "^4.3.6"
   },
   "openclaw": {

package/src/channel.directory.test.ts

@@ -1,36 +1,17 @@
 import type { PluginRuntime, RuntimeEnv } from "openclaw/plugin-sdk/matrix";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createRuntimeEnv } from "../../test-utils/runtime-env.js";
 import { matrixPlugin } from "./channel.js";
 import { setMatrixRuntime } from "./runtime.js";
+import { createMatrixBotSdkMock } from "./test-mocks.js";
 import type { CoreConfig } from "./types.js";
 
-vi.mock("@vector-im/matrix-bot-sdk", () => ({
-  ConsoleLogger: class {
-    trace = vi.fn();
-    debug = vi.fn();
-    info = vi.fn();
-    warn = vi.fn();
-    error = vi.fn();
-  },
-  MatrixClient: class {},
-  LogService: {
-    setLogger: vi.fn(),
-    warn: vi.fn(),
-    info: vi.fn(),
-    debug: vi.fn(),
-  },
-  SimpleFsStorageProvider: class {},
-  RustSdkCryptoStorageProvider: class {},
-}));
+vi.mock("@vector-im/matrix-bot-sdk", () =>
+  createMatrixBotSdkMock({ includeVerboseLogService: true }),
+);
 
 describe("matrix directory", () => {
-  const runtimeEnv: RuntimeEnv = {
-    log: vi.fn(),
-    error: vi.fn(),
-    exit: vi.fn((code: number): never => {
-      throw new Error(`exit ${code}`);
-    }),
-  };
+  const runtimeEnv: RuntimeEnv = createRuntimeEnv();
 
   beforeEach(() => {
     setMatrixRuntime({

package/src/channel.ts

@@ -15,6 +15,7 @@ import {
   PAIRING_APPROVED_MESSAGE,
   type ChannelPlugin,
 } from "openclaw/plugin-sdk/matrix";
+import { buildTrafficStatusSummary } from "../../shared/channel-status-summary.js";
 import { matrixMessageActions } from "./actions.js";
 import { MatrixConfigSchema } from "./config-schema.js";
 import { listMatrixDirectoryGroupsLive, listMatrixDirectoryPeersLive } from "./directory-live.js";
@@ -410,8 +411,7 @@ export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
       lastError: runtime?.lastError ?? null,
       probe,
       lastProbeAt: runtime?.lastProbeAt ?? null,
-      lastInboundAt: runtime?.lastInboundAt ?? null,
-      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+      ...buildTrafficStatusSummary(runtime),
     }),
   },
   gateway: {

package/src/matrix/monitor/allowlist.ts

@@ -1,7 +1,7 @@
 import {
   compileAllowlist,
   normalizeStringEntries,
-  resolveAllowlistCandidates,
+  resolveCompiledAllowlistMatch,
   type AllowlistMatch,
 } from "openclaw/plugin-sdk/matrix";
 
@@ -77,19 +77,13 @@ export function resolveMatrixAllowListMatch(params: {
   userId?: string;
 }): MatrixAllowListMatch {
   const compiledAllowList = compileAllowlist(params.allowList);
-  if (compiledAllowList.set.size === 0) {
-    return { allowed: false };
-  }
-  if (compiledAllowList.wildcard) {
-    return { allowed: true, matchKey: "*", matchSource: "wildcard" };
-  }
   const userId = normalizeMatrixUser(params.userId);
   const candidates: Array<{ value?: string; source: MatrixAllowListSource }> = [
     { value: userId, source: "id" },
     { value: userId ? `matrix:${userId}` : "", source: "prefixed-id" },
     { value: userId ? `user:${userId}` : "", source: "prefixed-user" },
   ];
-  return resolveAllowlistCandidates({
+  return resolveCompiledAllowlistMatch({
     compiledAllowlist: compiledAllowList,
     candidates,
   });

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

@@ -7,6 +7,8 @@ import { createDirectRoomTracker } from "./direct.js";
 
 type StateEvent = Record<string, unknown>;
 type DmMap = Record<string, boolean>;
+const brokenDmRoomId = "!broken-dm:example.org";
+const defaultBrokenDmMembers = ["@alice:example.org", "@bot:example.org"];
 
 function createMockClient(opts: {
   dmRooms?: DmMap;
@@ -50,6 +52,21 @@ function createMockClient(opts: {
   };
 }
 
+function createBrokenDmClient(roomNameEvent?: StateEvent) {
+  return createMockClient({
+    dmRooms: {},
+    membersByRoom: {
+      [brokenDmRoomId]: defaultBrokenDmMembers,
+    },
+    stateEvents: {
+      // is_direct not set on either member (e.g. Continuwuity bug)
+      [`${brokenDmRoomId}|m.room.member|@alice:example.org`]: {},
+      [`${brokenDmRoomId}|m.room.member|@bot:example.org`]: {},
+      ...(roomNameEvent ? { [`${brokenDmRoomId}|m.room.name|`]: roomNameEvent } : {}),
+    },
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Tests -- isDirectMessage
 // ---------------------------------------------------------------------------
@@ -131,22 +148,11 @@ describe("createDirectRoomTracker", () => {
 
   describe("conservative fallback (memberCount + room name)", () => {
     it("returns true for 2-member room WITHOUT a room name (broken flags)", async () => {
-      const client = createMockClient({
-        dmRooms: {},
-        membersByRoom: {
-          "!broken-dm:example.org": ["@alice:example.org", "@bot:example.org"],
-        },
-        stateEvents: {
-          // is_direct not set on either member (e.g. Continuwuity bug)
-          "!broken-dm:example.org|m.room.member|@alice:example.org": {},
-          "!broken-dm:example.org|m.room.member|@bot:example.org": {},
-          // No m.room.name -> getRoomStateEvent will throw (event not found)
-        },
-      });
+      const client = createBrokenDmClient();
       const tracker = createDirectRoomTracker(client as never);
 
       const result = await tracker.isDirectMessage({
-        roomId: "!broken-dm:example.org",
+        roomId: brokenDmRoomId,
         senderId: "@alice:example.org",
       });
 
@@ -154,21 +160,11 @@ describe("createDirectRoomTracker", () => {
     });
 
     it("returns true for 2-member room with empty room name", async () => {
-      const client = createMockClient({
-        dmRooms: {},
-        membersByRoom: {
-          "!broken-dm:example.org": ["@alice:example.org", "@bot:example.org"],
-        },
-        stateEvents: {
-          "!broken-dm:example.org|m.room.member|@alice:example.org": {},
-          "!broken-dm:example.org|m.room.member|@bot:example.org": {},
-          "!broken-dm:example.org|m.room.name|": { name: "" },
-        },
-      });
+      const client = createBrokenDmClient({ name: "" });
       const tracker = createDirectRoomTracker(client as never);
 
       const result = await tracker.isDirectMessage({
-        roomId: "!broken-dm:example.org",
+        roomId: brokenDmRoomId,
         senderId: "@alice:example.org",
       });
 

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

@@ -12,6 +12,19 @@ vi.mock("../send.js", () => ({
 }));
 
 describe("registerMatrixMonitorEvents", () => {
+  const roomId = "!room:example.org";
+
+  function makeEvent(overrides: Partial<MatrixRawEvent>): MatrixRawEvent {
+    return {
+      event_id: "$event",
+      sender: "@alice:example.org",
+      type: "m.room.message",
+      origin_server_ts: 0,
+      content: {},
+      ...overrides,
+    };
+  }
+
   beforeEach(() => {
     sendReadReceiptMatrixMock.mockClear();
   });
@@ -53,12 +66,22 @@ describe("registerMatrixMonitorEvents", () => {
     return { client, getUserId, onRoomMessage, roomMessageHandler, logVerboseMessage };
   }
 
+  async function expectForwardedWithoutReadReceipt(event: MatrixRawEvent) {
+    const { onRoomMessage, roomMessageHandler } = createHarness();
+
+    roomMessageHandler(roomId, event);
+    await vi.waitFor(() => {
+      expect(onRoomMessage).toHaveBeenCalledWith(roomId, event);
+    });
+    expect(sendReadReceiptMatrixMock).not.toHaveBeenCalled();
+  }
+
   it("sends read receipt immediately for non-self messages", async () => {
     const { client, onRoomMessage, roomMessageHandler } = createHarness();
-    const event = {
+    const event = makeEvent({
       event_id: "$e1",
       sender: "@alice:example.org",
-    } as MatrixRawEvent;
+    });
 
     roomMessageHandler("!room:example.org", event);
 
@@ -69,36 +92,27 @@ describe("registerMatrixMonitorEvents", () => {
   });
 
   it("does not send read receipts for self messages", async () => {
-    const { onRoomMessage, roomMessageHandler } = createHarness();
-    const event = {
-      event_id: "$e2",
-      sender: "@bot:example.org",
-    } as MatrixRawEvent;
-
-    roomMessageHandler("!room:example.org", event);
-    await vi.waitFor(() => {
-      expect(onRoomMessage).toHaveBeenCalledWith("!room:example.org", event);
-    });
-    expect(sendReadReceiptMatrixMock).not.toHaveBeenCalled();
+    await expectForwardedWithoutReadReceipt(
+      makeEvent({
+        event_id: "$e2",
+        sender: "@bot:example.org",
+      }),
+    );
   });
 
   it("skips receipt when message lacks sender or event id", async () => {
-    const { onRoomMessage, roomMessageHandler } = createHarness();
-    const event = {
-      sender: "@alice:example.org",
-    } as MatrixRawEvent;
-
-    roomMessageHandler("!room:example.org", event);
-    await vi.waitFor(() => {
-      expect(onRoomMessage).toHaveBeenCalledWith("!room:example.org", event);
-    });
-    expect(sendReadReceiptMatrixMock).not.toHaveBeenCalled();
+    await expectForwardedWithoutReadReceipt(
+      makeEvent({
+        sender: "@alice:example.org",
+        event_id: "",
+      }),
+    );
   });
 
   it("caches self user id across messages", async () => {
     const { getUserId, roomMessageHandler } = createHarness();
-    const first = { event_id: "$e3", sender: "@alice:example.org" } as MatrixRawEvent;
-    const second = { event_id: "$e4", sender: "@bob:example.org" } as MatrixRawEvent;
+    const first = makeEvent({ event_id: "$e3", sender: "@alice:example.org" });
+    const second = makeEvent({ event_id: "$e4", sender: "@bob:example.org" });
 
     roomMessageHandler("!room:example.org", first);
     roomMessageHandler("!room:example.org", second);
@@ -112,7 +126,7 @@ describe("registerMatrixMonitorEvents", () => {
   it("logs and continues when sending read receipt fails", async () => {
     sendReadReceiptMatrixMock.mockRejectedValueOnce(new Error("network boom"));
     const { roomMessageHandler, onRoomMessage, logVerboseMessage } = createHarness();
-    const event = { event_id: "$e5", sender: "@alice:example.org" } as MatrixRawEvent;
+    const event = makeEvent({ event_id: "$e5", sender: "@alice:example.org" });
 
     roomMessageHandler("!room:example.org", event);
 
@@ -128,7 +142,7 @@ describe("registerMatrixMonitorEvents", () => {
     const { roomMessageHandler, onRoomMessage, getUserId } = createHarness({
       getUserId: vi.fn().mockRejectedValue(new Error("cannot resolve self")),
     });
-    const event = { event_id: "$e6", sender: "@alice:example.org" } as MatrixRawEvent;
+    const event = makeEvent({ event_id: "$e6", sender: "@alice:example.org" });
 
     roomMessageHandler("!room:example.org", event);
 

package/src/matrix/monitor/handler.ts

@@ -686,6 +686,7 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
         channel: "matrix",
         accountId: route.accountId,
       });
+      const humanDelay = core.channel.reply.resolveHumanDelayConfig(cfg, route.agentId);
       const typingCallbacks = createTypingCallbacks({
         start: () => sendTypingMatrix(roomId, true, undefined, client),
         stop: () => sendTypingMatrix(roomId, false, undefined, client),
@@ -711,7 +712,7 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
       const { dispatcher, replyOptions, markDispatchIdle } =
         core.channel.reply.createReplyDispatcherWithTyping({
           ...prefixOptions,
-          humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, route.agentId),
+          humanDelay,
           typingCallbacks,
           deliver: async (payload) => {
             await deliverMatrixReplies({

package/src/matrix/send-queue.test.ts

@@ -1,16 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createDeferred } from "../../../shared/deferred.js";
 import { DEFAULT_SEND_GAP_MS, enqueueSend } from "./send-queue.js";
 
-function deferred<T>() {
-  let resolve!: (value: T | PromiseLike<T>) => void;
-  let reject!: (reason?: unknown) => void;
-  const promise = new Promise<T>((res, rej) => {
-    resolve = res;
-    reject = rej;
-  });
-  return { promise, resolve, reject };
-}
-
 describe("enqueueSend", () => {
   beforeEach(() => {
     vi.useFakeTimers();
@@ -21,7 +12,7 @@ describe("enqueueSend", () => {
   });
 
   it("serializes sends per room", async () => {
-    const gate = deferred<void>();
+    const gate = createDeferred<void>();
     const events: string[] = [];
 
     const first = enqueueSend("!room:example.org", async () => {
@@ -91,7 +82,7 @@ describe("enqueueSend", () => {
   });
 
   it("continues queued work when the head task fails", async () => {
-    const gate = deferred<void>();
+    const gate = createDeferred<void>();
     const events: string[] = [];
 
     const first = enqueueSend("!room:example.org", async () => {

package/src/matrix/send.test.ts

@@ -1,6 +1,7 @@
 import type { PluginRuntime } from "openclaw/plugin-sdk/matrix";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { setMatrixRuntime } from "../runtime.js";
+import { createMatrixBotSdkMock } from "../test-mocks.js";
 
 vi.mock("music-metadata", () => ({
   // `resolveMediaDurationMs` lazily imports `music-metadata`; in tests we don't
@@ -8,21 +9,13 @@ vi.mock("music-metadata", () => ({
   parseBuffer: vi.fn().mockResolvedValue({ format: {} }),
 }));
 
-vi.mock("@vector-im/matrix-bot-sdk", () => ({
-  ConsoleLogger: class {
-    trace = vi.fn();
-    debug = vi.fn();
-    info = vi.fn();
-    warn = vi.fn();
-    error = vi.fn();
-  },
-  LogService: {
-    setLogger: vi.fn(),
-  },
-  MatrixClient: vi.fn(),
-  SimpleFsStorageProvider: vi.fn(),
-  RustSdkCryptoStorageProvider: vi.fn(),
-}));
+vi.mock("@vector-im/matrix-bot-sdk", () =>
+  createMatrixBotSdkMock({
+    matrixClient: vi.fn(),
+    simpleFsStorageProvider: vi.fn(),
+    rustSdkCryptoStorageProvider: vi.fn(),
+  }),
+);
 
 vi.mock("./send-queue.js", () => ({
   enqueueSend: async <T>(_roomId: string, fn: () => Promise<T>) => await fn(),

package/src/resolve-targets.test.ts

@@ -8,6 +8,15 @@ vi.mock("./directory-live.js", () => ({
   listMatrixDirectoryGroupsLive: vi.fn(),
 }));
 
+async function resolveUserTarget(input = "Alice") {
+  const [result] = await resolveMatrixTargets({
+    cfg: {},
+    inputs: [input],
+    kind: "user",
+  });
+  return result;
+}
+
 describe("resolveMatrixTargets (users)", () => {
   beforeEach(() => {
     vi.mocked(listMatrixDirectoryPeersLive).mockReset();
@@ -20,11 +29,7 @@ describe("resolveMatrixTargets (users)", () => {
     ];
     vi.mocked(listMatrixDirectoryPeersLive).mockResolvedValue(matches);
 
-    const [result] = await resolveMatrixTargets({
-      cfg: {},
-      inputs: ["Alice"],
-      kind: "user",
-    });
+    const result = await resolveUserTarget();
 
     expect(result?.resolved).toBe(true);
     expect(result?.id).toBe("@alice:example.org");
@@ -37,11 +42,7 @@ describe("resolveMatrixTargets (users)", () => {
     ];
     vi.mocked(listMatrixDirectoryPeersLive).mockResolvedValue(matches);
 
-    const [result] = await resolveMatrixTargets({
-      cfg: {},
-      inputs: ["Alice"],
-      kind: "user",
-    });
+    const result = await resolveUserTarget();
 
     expect(result?.resolved).toBe(false);
     expect(result?.note).toMatch(/use full Matrix ID/i);

package/src/test-mocks.ts

@@ -0,0 +1,53 @@
+import type { Mock } from "vitest";
+import { vi } from "vitest";
+
+type MatrixBotSdkMockParams = {
+  matrixClient?: unknown;
+  simpleFsStorageProvider?: unknown;
+  rustSdkCryptoStorageProvider?: unknown;
+  includeVerboseLogService?: boolean;
+};
+
+type MatrixBotSdkMock = {
+  ConsoleLogger: new () => {
+    trace: Mock<() => void>;
+    debug: Mock<() => void>;
+    info: Mock<() => void>;
+    warn: Mock<() => void>;
+    error: Mock<() => void>;
+  };
+  MatrixClient: unknown;
+  LogService: {
+    setLogger: Mock<() => void>;
+    warn?: Mock<() => void>;
+    info?: Mock<() => void>;
+    debug?: Mock<() => void>;
+  };
+  SimpleFsStorageProvider: unknown;
+  RustSdkCryptoStorageProvider: unknown;
+};
+
+export function createMatrixBotSdkMock(params: MatrixBotSdkMockParams = {}): MatrixBotSdkMock {
+  return {
+    ConsoleLogger: class {
+      trace = vi.fn();
+      debug = vi.fn();
+      info = vi.fn();
+      warn = vi.fn();
+      error = vi.fn();
+    },
+    MatrixClient: params.matrixClient ?? class {},
+    LogService: {
+      setLogger: vi.fn(),
+      ...(params.includeVerboseLogService
+        ? {
+            warn: vi.fn(),
+            info: vi.fn(),
+            debug: vi.fn(),
+          }
+        : {}),
+    },
+    SimpleFsStorageProvider: params.simpleFsStorageProvider ?? class {},
+    RustSdkCryptoStorageProvider: params.rustSdkCryptoStorageProvider ?? class {},
+  };
+}