@openclaw/matrix 2026.2.3 → 2026.2.9

package/CHANGELOG.md

@@ -1,6 +1,24 @@
 # Changelog
 
-## 2026.2.3
+## 2026.2.6-3
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.6-2
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.6
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.4
 
 ### Changes
 

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@openclaw/matrix",
-  "version": "2026.2.3",
+  "version": "2026.2.9",
   "description": "OpenClaw Matrix channel plugin",
   "type": "module",
   "dependencies": {
     "@matrix-org/matrix-sdk-crypto-nodejs": "^0.4.0",
     "@vector-im/matrix-bot-sdk": "0.8.0-element.3",
     "markdown-it": "14.1.0",
-    "music-metadata": "^11.11.2",
+    "music-metadata": "^11.12.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/src/actions.ts

@@ -78,7 +78,7 @@ export const matrixMessageActions: ChannelMessageActionAdapter = {
           replyToId: replyTo ?? undefined,
           threadId: threadId ?? undefined,
         },
-        cfg,
+        cfg as CoreConfig,
       );
     }
 
@@ -94,7 +94,7 @@ export const matrixMessageActions: ChannelMessageActionAdapter = {
           emoji,
           remove,
         },
-        cfg,
+        cfg as CoreConfig,
       );
     }
 
@@ -108,7 +108,7 @@ export const matrixMessageActions: ChannelMessageActionAdapter = {
           messageId,
           limit,
         },
-        cfg,
+        cfg as CoreConfig,
       );
     }
 
@@ -122,7 +122,7 @@ export const matrixMessageActions: ChannelMessageActionAdapter = {
           before: readStringParam(params, "before"),
           after: readStringParam(params, "after"),
         },
-        cfg,
+        cfg as CoreConfig,
       );
     }
 
@@ -136,7 +136,7 @@ export const matrixMessageActions: ChannelMessageActionAdapter = {
           messageId,
           content,
         },
-        cfg,
+        cfg as CoreConfig,
       );
     }
 
@@ -148,7 +148,7 @@ export const matrixMessageActions: ChannelMessageActionAdapter = {
           roomId: resolveRoomId(),
           messageId,
         },
-        cfg,
+        cfg as CoreConfig,
       );
     }
 
@@ -164,7 +164,7 @@ export const matrixMessageActions: ChannelMessageActionAdapter = {
           roomId: resolveRoomId(),
           messageId,
         },
-        cfg,
+        cfg as CoreConfig,
       );
     }
 
@@ -176,7 +176,7 @@ export const matrixMessageActions: ChannelMessageActionAdapter = {
           userId,
           roomId: readStringParam(params, "roomId") ?? readStringParam(params, "channelId"),
         },
-        cfg,
+        cfg as CoreConfig,
       );
     }
 
@@ -186,7 +186,7 @@ export const matrixMessageActions: ChannelMessageActionAdapter = {
           action: "channelInfo",
           roomId: resolveRoomId(),
         },
-        cfg,
+        cfg as CoreConfig,
       );
     }
 

package/src/matrix/actions/client.ts

@@ -1,4 +1,4 @@
-import type { CoreConfig } from "../types.js";
+import type { CoreConfig } from "../../types.js";
 import type { MatrixActionClient, MatrixActionClientOpts } from "./types.js";
 import { getMatrixRuntime } from "../../runtime.js";
 import { getActiveMatrixClient } from "../active-client.js";
@@ -47,7 +47,9 @@ export async function resolveActionClient(
   if (auth.encryption && client.crypto) {
     try {
       const joinedRooms = await client.getJoinedRooms();
-      await client.crypto.prepare(joinedRooms);
+      await (client.crypto as { prepare: (rooms?: string[]) => Promise<void> }).prepare(
+        joinedRooms,
+      );
     } catch {
       // Ignore crypto prep failures for one-off actions.
     }

package/src/matrix/actions/summary.ts

@@ -63,7 +63,7 @@ export async function fetchEventSummary(
   eventId: string,
 ): Promise<MatrixMessageSummary | null> {
   try {
-    const raw = (await client.getEvent(roomId, eventId)) as MatrixRawEvent;
+    const raw = (await client.getEvent(roomId, eventId)) as unknown as MatrixRawEvent;
     if (raw.unsigned?.redacted_because) {
       return null;
     }

package/src/matrix/client/config.ts

@@ -1,5 +1,5 @@
 import { MatrixClient } from "@vector-im/matrix-bot-sdk";
-import type { CoreConfig } from "../types.js";
+import type { CoreConfig } from "../../types.js";
 import type { MatrixAuth, MatrixResolvedConfig } from "./types.js";
 import { getMatrixRuntime } from "../../runtime.js";
 import { ensureMatrixSdkLoggingConfigured } from "./logging.js";

package/src/matrix/client/shared.ts

@@ -1,6 +1,6 @@
 import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
 import { LogService } from "@vector-im/matrix-bot-sdk";
-import type { CoreConfig } from "../types.js";
+import type { CoreConfig } from "../../types.js";
 import type { MatrixAuth } from "./types.js";
 import { resolveMatrixAuth } from "./config.js";
 import { createMatrixClient } from "./create-client.js";
@@ -69,7 +69,9 @@ async function ensureSharedClientStarted(params: {
       try {
         const joinedRooms = await client.getJoinedRooms();
         if (client.crypto) {
-          await client.crypto.prepare(joinedRooms);
+          await (client.crypto as { prepare: (rooms?: string[]) => Promise<void> }).prepare(
+            joinedRooms,
+          );
           params.state.cryptoReady = true;
         }
       } catch (err) {

package/src/matrix/monitor/events.ts

@@ -1,5 +1,5 @@
 import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-import type { PluginRuntime } from "openclaw/plugin-sdk";
+import type { PluginRuntime, RuntimeLogger } from "openclaw/plugin-sdk";
 import type { MatrixAuth } from "../client.js";
 import type { MatrixRawEvent } from "./types.js";
 import { EventType } from "./types.js";
@@ -10,7 +10,7 @@ export function registerMatrixMonitorEvents(params: {
   logVerboseMessage: (message: string) => void;
   warnedEncryptedRooms: Set<string>;
   warnedCryptoMissingRooms: Set<string>;
-  logger: { warn: (meta: Record<string, unknown>, message: string) => void };
+  logger: RuntimeLogger;
   formatNativeDependencyHint: PluginRuntime["system"]["formatNativeDependencyHint"];
   onRoomMessage: (roomId: string, event: MatrixRawEvent) => void | Promise<void>;
 }): void {
@@ -42,10 +42,11 @@ export function registerMatrixMonitorEvents(params: {
   client.on(
     "room.failed_decryption",
     async (roomId: string, event: MatrixRawEvent, error: Error) => {
-      logger.warn(
-        { roomId, eventId: event.event_id, error: error.message },
-        "Failed to decrypt message",
-      );
+      logger.warn("Failed to decrypt message", {
+        roomId,
+        eventId: event.event_id,
+        error: error.message,
+      });
       logVerboseMessage(
         `matrix: failed decrypt room=${roomId} id=${event.event_id ?? "unknown"} error=${error.message}`,
       );
@@ -76,7 +77,7 @@ export function registerMatrixMonitorEvents(params: {
         warnedEncryptedRooms.add(roomId);
         const warning =
           "matrix: encrypted event received without encryption enabled; set channels.matrix.encryption=true and verify the device to decrypt";
-        logger.warn({ roomId }, warning);
+        logger.warn(warning, { roomId });
       }
       if (auth.encryption === true && !client.crypto && !warnedCryptoMissingRooms.has(roomId)) {
         warnedCryptoMissingRooms.add(roomId);
@@ -86,7 +87,7 @@ export function registerMatrixMonitorEvents(params: {
           downloadCommand: "node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js",
         });
         const warning = `matrix: encryption enabled but crypto is unavailable; ${hint}`;
-        logger.warn({ roomId }, warning);
+        logger.warn(warning, { roomId });
       }
       return;
     }

package/src/matrix/monitor/handler.ts

@@ -6,9 +6,11 @@ import {
   logInboundDrop,
   logTypingFailure,
   resolveControlCommandGate,
+  type PluginRuntime,
   type RuntimeEnv,
+  type RuntimeLogger,
 } from "openclaw/plugin-sdk";
-import type { CoreConfig, ReplyToMode } from "../../types.js";
+import type { CoreConfig, MatrixRoomConfig, ReplyToMode } from "../../types.js";
 import type { MatrixRawEvent, RoomMessageEventContent } from "./types.js";
 import {
   formatPollAsText,
@@ -37,34 +39,14 @@ import { EventType, RelationType } from "./types.js";
 
 export type MatrixMonitorHandlerParams = {
   client: MatrixClient;
-  core: {
-    logging: {
-      shouldLogVerbose: () => boolean;
-    };
-    channel: (typeof import("openclaw/plugin-sdk"))["channel"];
-    system: {
-      enqueueSystemEvent: (
-        text: string,
-        meta: { sessionKey?: string | null; contextKey?: string | null },
-      ) => void;
-    };
-  };
+  core: PluginRuntime;
   cfg: CoreConfig;
   runtime: RuntimeEnv;
-  logger: {
-    info: (message: string | Record<string, unknown>, ...meta: unknown[]) => void;
-    warn: (meta: Record<string, unknown>, message: string) => void;
-  };
+  logger: RuntimeLogger;
   logVerboseMessage: (message: string) => void;
   allowFrom: string[];
-  roomsConfig: CoreConfig["channels"] extends { matrix?: infer MatrixConfig }
-    ? MatrixConfig extends { groups?: infer Groups }
-      ? Groups
-      : Record<string, unknown> | undefined
-    : Record<string, unknown> | undefined;
-  mentionRegexes: ReturnType<
-    (typeof import("openclaw/plugin-sdk"))["channel"]["mentions"]["buildMentionRegexes"]
-  >;
+  roomsConfig: Record<string, MatrixRoomConfig> | undefined;
+  mentionRegexes: ReturnType<PluginRuntime["channel"]["mentions"]["buildMentionRegexes"]>;
   groupPolicy: "open" | "allowlist" | "disabled";
   replyToMode: ReplyToMode;
   threadReplies: "off" | "inbound" | "always";
@@ -121,7 +103,7 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
       }
 
       const isPollEvent = isPollStartType(eventType);
-      const locationContent = event.content as LocationMessageEventContent;
+      const locationContent = event.content as unknown as LocationMessageEventContent;
       const isLocationEvent =
         eventType === EventType.Location ||
         (eventType === EventType.RoomMessage && locationContent.msgtype === EventType.Location);
@@ -159,9 +141,9 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
       const roomName = roomInfo.name;
       const roomAliases = [roomInfo.canonicalAlias ?? "", ...roomInfo.altAliases].filter(Boolean);
 
-      let content = event.content as RoomMessageEventContent;
+      let content = event.content as unknown as RoomMessageEventContent;
       if (isPollEvent) {
-        const pollStartContent = event.content as PollStartContent;
+        const pollStartContent = event.content as unknown as PollStartContent;
         const pollSummary = parsePollStartContent(pollStartContent);
         if (pollSummary) {
           pollSummary.eventId = event.event_id ?? "";
@@ -435,7 +417,7 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
         hasControlCommandInMessage;
       const canDetectMention = mentionRegexes.length > 0 || hasExplicitMention;
       if (isRoom && shouldRequireMention && !wasMentioned && !shouldBypassMention) {
-        logger.info({ roomId, reason: "no-mention" }, "skipping room message");
+        logger.info("skipping room message", { roomId, reason: "no-mention" });
         return;
       }
 
@@ -453,7 +435,7 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
         cfg,
         channel: "matrix",
         peer: {
-          kind: isDirectMessage ? "dm" : "channel",
+          kind: isDirectMessage ? "direct" : "channel",
           id: isDirectMessage ? senderId : roomId,
         },
       });
@@ -523,14 +505,11 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
             }
           : undefined,
         onRecordError: (err) => {
-          logger.warn(
-            {
-              error: String(err),
-              storePath,
-              sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
-            },
-            "failed updating session meta",
-          );
+          logger.warn("failed updating session meta", {
+            error: String(err),
+            storePath,
+            sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+          });
         },
       });
 

package/src/matrix/monitor/index.ts

@@ -55,7 +55,7 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
     if (!core.logging.shouldLogVerbose()) {
       return;
     }
-    logger.debug(message);
+    logger.debug?.(message);
   };
 
   const normalizeUserEntry = (raw: string) =>
@@ -75,13 +75,13 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
   ): Promise<string[]> => {
     let allowList = list ?? [];
     if (allowList.length === 0) {
-      return allowList;
+      return allowList.map(String);
     }
     const entries = allowList
       .map((entry) => normalizeUserEntry(String(entry)))
       .filter((entry) => entry && entry !== "*");
     if (entries.length === 0) {
-      return allowList;
+      return allowList.map(String);
     }
     const mapping: string[] = [];
     const unresolved: string[] = [];
@@ -118,12 +118,12 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
         `${label} entries must be full Matrix IDs (example: @user:server). Unresolved entries are ignored.`,
       );
     }
-    return allowList;
+    return allowList.map(String);
   };
 
   const allowlistOnly = cfg.channels?.matrix?.allowlistOnly === true;
-  let allowFrom = cfg.channels?.matrix?.dm?.allowFrom ?? [];
-  let groupAllowFrom = cfg.channels?.matrix?.groupAllowFrom ?? [];
+  let allowFrom: string[] = (cfg.channels?.matrix?.dm?.allowFrom ?? []).map(String);
+  let groupAllowFrom: string[] = (cfg.channels?.matrix?.groupAllowFrom ?? []).map(String);
   let roomsConfig = cfg.channels?.matrix?.groups ?? cfg.channels?.matrix?.rooms;
 
   allowFrom = await resolveUserAllowlist("matrix dm allowlist", allowFrom);
@@ -307,15 +307,16 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
   if (auth.encryption && client.crypto) {
     try {
       // Request verification from other sessions
-      const verificationRequest = await client.crypto.requestOwnUserVerification();
+      const verificationRequest = await (
+        client.crypto as { requestOwnUserVerification?: () => Promise<unknown> }
+      ).requestOwnUserVerification?.();
       if (verificationRequest) {
         logger.info("matrix: device verification requested - please verify in another client");
       }
     } catch (err) {
-      logger.debug(
-        { error: String(err) },
-        "Device verification request failed (may already be verified)",
-      );
+      logger.debug?.("Device verification request failed (may already be verified)", {
+        error: String(err),
+      });
     }
   }
 

package/src/matrix/monitor/media.ts

@@ -29,7 +29,8 @@ async function fetchMatrixMediaBuffer(params: {
 
   // Use the client's download method which handles auth
   try {
-    const buffer = await params.client.downloadContent(params.mxcUrl);
+    const result = await params.client.downloadContent(params.mxcUrl);
+    const buffer = result.data;
     if (buffer.byteLength > params.maxBytes) {
       throw new Error("Matrix media exceeds configured size limit");
     }
@@ -53,7 +54,9 @@ async function fetchEncryptedMediaBuffer(params: {
   }
 
   // decryptMedia handles downloading and decrypting the encrypted content internally
-  const decrypted = await params.client.crypto.decryptMedia(params.file);
+  const decrypted = await params.client.crypto.decryptMedia(
+    params.file as Parameters<typeof params.client.crypto.decryptMedia>[0],
+  );
 
   if (decrypted.byteLength > params.maxBytes) {
     throw new Error("Matrix media exceeds configured size limit");

package/src/matrix/poll-types.ts

@@ -73,7 +73,7 @@ export type PollSummary = {
 };
 
 export function isPollStartType(eventType: string): boolean {
-  return POLL_START_TYPES.includes(eventType);
+  return (POLL_START_TYPES as readonly string[]).includes(eventType);
 }
 
 export function getTextContent(text?: TextContent): string {
@@ -147,7 +147,8 @@ export function buildPollStartContent(poll: PollInput): PollStartContent {
       ...buildTextContent(option),
     }));
 
-  const maxSelections = poll.multiple ? Math.max(1, answers.length) : 1;
+  const isMultiple = (poll.maxSelections ?? 1) > 1;
+  const maxSelections = isMultiple ? Math.max(1, answers.length) : 1;
   const fallbackText = buildPollFallbackText(
     question,
     answers.map((answer) => getTextContent(answer)),
@@ -156,7 +157,7 @@ export function buildPollStartContent(poll: PollInput): PollStartContent {
   return {
     [M_POLL_START]: {
       question: buildTextContent(question),
-      kind: poll.multiple ? "m.poll.undisclosed" : "m.poll.disclosed",
+      kind: isMultiple ? "m.poll.undisclosed" : "m.poll.disclosed",
       max_selections: maxSelections,
       answers,
     },

package/src/matrix/send/client.ts

@@ -1,5 +1,5 @@
 import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-import type { CoreConfig } from "../types.js";
+import type { CoreConfig } from "../../types.js";
 import { getMatrixRuntime } from "../../runtime.js";
 import { getActiveMatrixClient } from "../active-client.js";
 import {
@@ -55,7 +55,9 @@ export async function resolveMatrixClient(opts: {
   if (auth.encryption && client.crypto) {
     try {
       const joinedRooms = await client.getJoinedRooms();
-      await client.crypto.prepare(joinedRooms);
+      await (client.crypto as { prepare: (rooms?: string[]) => Promise<void> }).prepare(
+        joinedRooms,
+      );
     } catch {
       // Ignore crypto prep failures for one-off sends; normal sync will retry.
     }

package/src/matrix/send/targets.ts

@@ -17,7 +17,18 @@ export function normalizeThreadId(raw?: string | number | null): string | null {
   return trimmed ? trimmed : null;
 }
 
+// Size-capped to prevent unbounded growth (#4948)
+const MAX_DIRECT_ROOM_CACHE_SIZE = 1024;
 const directRoomCache = new Map<string, string>();
+function setDirectRoomCached(key: string, value: string): void {
+  directRoomCache.set(key, value);
+  if (directRoomCache.size > MAX_DIRECT_ROOM_CACHE_SIZE) {
+    const oldest = directRoomCache.keys().next().value;
+    if (oldest !== undefined) {
+      directRoomCache.delete(oldest);
+    }
+  }
+}
 
 async function persistDirectRoom(
   client: MatrixClient,
@@ -59,10 +70,13 @@ async function resolveDirectRoomId(client: MatrixClient, userId: string): Promis
 
   // 1) Fast path: use account data (m.direct) for *this* logged-in user (the bot).
   try {
-    const directContent = await client.getAccountData(EventType.Direct);
+    const directContent = (await client.getAccountData(EventType.Direct)) as Record<
+      string,
+      string[] | undefined
+    >;
     const list = Array.isArray(directContent?.[trimmed]) ? directContent[trimmed] : [];
-    if (list.length > 0) {
-      directRoomCache.set(trimmed, list[0]);
+    if (list && list.length > 0) {
+      setDirectRoomCached(trimmed, list[0]);
       return list[0];
     }
   } catch {
@@ -86,7 +100,7 @@ async function resolveDirectRoomId(client: MatrixClient, userId: string): Promis
       }
       // Prefer classic 1:1 rooms, but allow larger rooms if requested.
       if (members.length === 2) {
-        directRoomCache.set(trimmed, roomId);
+        setDirectRoomCached(trimmed, roomId);
         await persistDirectRoom(client, trimmed, roomId);
         return roomId;
       }
@@ -99,7 +113,7 @@ async function resolveDirectRoomId(client: MatrixClient, userId: string): Promis
   }
 
   if (fallbackRoom) {
-    directRoomCache.set(trimmed, fallbackRoom);
+    setDirectRoomCached(trimmed, fallbackRoom);
     await persistDirectRoom(client, trimmed, fallbackRoom);
     return fallbackRoom;
   }

package/src/onboarding.ts

@@ -1,3 +1,4 @@
+import type { DmPolicy } from "openclaw/plugin-sdk";
 import {
   addWildcardAllowFrom,
   formatDocsLink,
@@ -6,7 +7,7 @@ import {
   type ChannelOnboardingDmPolicy,
   type WizardPrompter,
 } from "openclaw/plugin-sdk";
-import type { CoreConfig, DmPolicy } from "./types.js";
+import type { CoreConfig } from "./types.js";
 import { listMatrixDirectoryGroupsLive } from "./directory-live.js";
 import { resolveMatrixAccount } from "./matrix/accounts.js";
 import { ensureMatrixSdkInstalled, isMatrixSdkAvailable } from "./matrix/deps.js";

package/src/types.ts

@@ -1,6 +1,7 @@
+import type { DmPolicy, GroupPolicy } from "openclaw/plugin-sdk";
+export type { DmPolicy, GroupPolicy };
+
 export type ReplyToMode = "off" | "first" | "all";
-export type GroupPolicy = "open" | "disabled" | "allowlist";
-export type DmPolicy = "pairing" | "allowlist" | "open" | "disabled";
 
 export type MatrixDmConfig = {
   /** If false, ignore all incoming Matrix DMs. Default: true. */
@@ -92,6 +93,19 @@ export type MatrixConfig = {
 export type CoreConfig = {
   channels?: {
     matrix?: MatrixConfig;
+    defaults?: {
+      groupPolicy?: "open" | "allowlist" | "disabled";
+    };
+  };
+  commands?: {
+    useAccessGroups?: boolean;
+  };
+  session?: {
+    store?: string;
+  };
+  messages?: {
+    ackReaction?: string;
+    ackReactionScope?: "group-mentions" | "group-all" | "direct" | "all";
   };
   [key: string]: unknown;
 };