@openclaw/matrix 2026.2.12 → 2026.2.14

package/src/matrix/send/formatting.ts

@@ -77,13 +77,17 @@ export function resolveMatrixVoiceDecision(opts: {
   if (!opts.wantsVoice) {
     return { useVoice: false };
   }
-  if (
-    getCore().media.isVoiceCompatibleAudio({
-      contentType: opts.contentType,
-      fileName: opts.fileName,
-    })
-  ) {
+  if (isMatrixVoiceCompatibleAudio(opts)) {
     return { useVoice: true };
   }
   return { useVoice: false };
 }
+
+function isMatrixVoiceCompatibleAudio(opts: { contentType?: string; fileName?: string }): boolean {
+  // Matrix currently shares the core voice compatibility policy.
+  // Keep this wrapper as the seam if Matrix policy diverges later.
+  return getCore().media.isVoiceCompatibleAudio({
+    contentType: opts.contentType,
+    fileName: opts.fileName,
+  });
+}

package/src/matrix/send/media.ts

@@ -6,7 +6,6 @@ import type {
   TimedFileInfo,
   VideoFileInfo,
 } from "@vector-im/matrix-bot-sdk";
-import { parseBuffer, type IFileInfo } from "music-metadata";
 import { getMatrixRuntime } from "../../runtime.js";
 import { applyMatrixFormatting } from "./formatting.js";
 import {
@@ -18,6 +17,7 @@ import {
 } from "./types.js";
 
 const getCore = () => getMatrixRuntime();
+type IFileInfo = import("music-metadata").IFileInfo;
 
 export function buildMatrixMediaInfo(params: {
   size: number;
@@ -164,6 +164,7 @@ export async function resolveMediaDurationMs(params: {
     return undefined;
   }
   try {
+    const { parseBuffer } = await import("music-metadata");
     const fileInfo: IFileInfo | string | undefined =
       params.contentType || params.fileName
         ? {

package/src/matrix/send.test.ts

@@ -2,6 +2,12 @@ import type { PluginRuntime } from "openclaw/plugin-sdk";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { setMatrixRuntime } from "../runtime.js";
 
+vi.mock("music-metadata", () => ({
+  // `resolveMediaDurationMs` lazily imports `music-metadata`; in tests we don't
+  // need real duration parsing and the real module is expensive to load.
+  parseBuffer: vi.fn().mockResolvedValue({ format: {} }),
+}));
+
 vi.mock("@vector-im/matrix-bot-sdk", () => ({
   ConsoleLogger: class {
     trace = vi.fn();
@@ -24,6 +30,8 @@ const loadWebMediaMock = vi.fn().mockResolvedValue({
   contentType: "image/png",
   kind: "image",
 });
+const mediaKindFromMimeMock = vi.fn(() => "image");
+const isVoiceCompatibleAudioMock = vi.fn(() => false);
 const getImageMetadataMock = vi.fn().mockResolvedValue(null);
 const resizeToJpegMock = vi.fn();
 
@@ -33,8 +41,8 @@ const runtimeStub = {
   },
   media: {
     loadWebMedia: (...args: unknown[]) => loadWebMediaMock(...args),
-    mediaKindFromMime: () => "image",
-    isVoiceCompatibleAudio: () => false,
+    mediaKindFromMime: (...args: unknown[]) => mediaKindFromMimeMock(...args),
+    isVoiceCompatibleAudio: (...args: unknown[]) => isVoiceCompatibleAudioMock(...args),
     getImageMetadata: (...args: unknown[]) => getImageMetadataMock(...args),
     resizeToJpeg: (...args: unknown[]) => resizeToJpegMock(...args),
   },
@@ -63,14 +71,16 @@ const makeClient = () => {
   return { client, sendMessage, uploadContent };
 };
 
-describe("sendMessageMatrix media", () => {
-  beforeAll(async () => {
-    setMatrixRuntime(runtimeStub);
-    ({ sendMessageMatrix } = await import("./send.js"));
-  });
+beforeAll(async () => {
+  setMatrixRuntime(runtimeStub);
+  ({ sendMessageMatrix } = await import("./send.js"));
+});
 
+describe("sendMessageMatrix media", () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    mediaKindFromMimeMock.mockReturnValue("image");
+    isVoiceCompatibleAudioMock.mockReturnValue(false);
     setMatrixRuntime(runtimeStub);
   });
 
@@ -133,14 +143,69 @@ describe("sendMessageMatrix media", () => {
     expect(content.url).toBeUndefined();
     expect(content.file?.url).toBe("mxc://example/file");
   });
-});
 
-describe("sendMessageMatrix threads", () => {
-  beforeAll(async () => {
-    setMatrixRuntime(runtimeStub);
-    ({ sendMessageMatrix } = await import("./send.js"));
+  it("marks voice metadata and sends caption follow-up when audioAsVoice is compatible", async () => {
+    const { client, sendMessage } = makeClient();
+    mediaKindFromMimeMock.mockReturnValue("audio");
+    isVoiceCompatibleAudioMock.mockReturnValue(true);
+    loadWebMediaMock.mockResolvedValueOnce({
+      buffer: Buffer.from("audio"),
+      fileName: "clip.mp3",
+      contentType: "audio/mpeg",
+      kind: "audio",
+    });
+
+    await sendMessageMatrix("room:!room:example", "voice caption", {
+      client,
+      mediaUrl: "file:///tmp/clip.mp3",
+      audioAsVoice: true,
+    });
+
+    expect(isVoiceCompatibleAudioMock).toHaveBeenCalledWith({
+      contentType: "audio/mpeg",
+      fileName: "clip.mp3",
+    });
+    expect(sendMessage).toHaveBeenCalledTimes(2);
+    const mediaContent = sendMessage.mock.calls[0]?.[1] as {
+      msgtype?: string;
+      body?: string;
+      "org.matrix.msc3245.voice"?: Record<string, never>;
+    };
+    expect(mediaContent.msgtype).toBe("m.audio");
+    expect(mediaContent.body).toBe("Voice message");
+    expect(mediaContent["org.matrix.msc3245.voice"]).toEqual({});
   });
 
+  it("keeps regular audio payload when audioAsVoice media is incompatible", async () => {
+    const { client, sendMessage } = makeClient();
+    mediaKindFromMimeMock.mockReturnValue("audio");
+    isVoiceCompatibleAudioMock.mockReturnValue(false);
+    loadWebMediaMock.mockResolvedValueOnce({
+      buffer: Buffer.from("audio"),
+      fileName: "clip.wav",
+      contentType: "audio/wav",
+      kind: "audio",
+    });
+
+    await sendMessageMatrix("room:!room:example", "voice caption", {
+      client,
+      mediaUrl: "file:///tmp/clip.wav",
+      audioAsVoice: true,
+    });
+
+    expect(sendMessage).toHaveBeenCalledTimes(1);
+    const mediaContent = sendMessage.mock.calls[0]?.[1] as {
+      msgtype?: string;
+      body?: string;
+      "org.matrix.msc3245.voice"?: Record<string, never>;
+    };
+    expect(mediaContent.msgtype).toBe("m.audio");
+    expect(mediaContent.body).toBe("voice caption");
+    expect(mediaContent["org.matrix.msc3245.voice"]).toBeUndefined();
+  });
+});
+
+describe("sendMessageMatrix threads", () => {
   beforeEach(() => {
     vi.clearAllMocks();
     setMatrixRuntime(runtimeStub);

package/src/matrix/send.ts

@@ -45,6 +45,7 @@ export async function sendMessageMatrix(
   const { client, stopOnDone } = await resolveMatrixClient({
     client: opts.client,
     timeoutMs: opts.timeoutMs,
+    accountId: opts.accountId,
   });
   try {
     const roomId = await resolveMatrixRoomId(client, to);
@@ -78,7 +79,7 @@ export async function sendMessageMatrix(
 
     let lastMessageId = "";
     if (opts.mediaUrl) {
-      const maxBytes = resolveMediaMaxBytes();
+      const maxBytes = resolveMediaMaxBytes(opts.accountId);
       const media = await getCore().media.loadWebMedia(opts.mediaUrl, maxBytes);
       const uploaded = await uploadMediaMaybeEncrypted(client, roomId, media.buffer, {
         contentType: media.contentType,
@@ -166,6 +167,7 @@ export async function sendPollMatrix(
   const { client, stopOnDone } = await resolveMatrixClient({
     client: opts.client,
     timeoutMs: opts.timeoutMs,
+    accountId: opts.accountId,
   });
 
   try {

package/src/outbound.ts

@@ -7,13 +7,14 @@ export const matrixOutbound: ChannelOutboundAdapter = {
   chunker: (text, limit) => getMatrixRuntime().channel.text.chunkMarkdownText(text, limit),
   chunkerMode: "markdown",
   textChunkLimit: 4000,
-  sendText: async ({ to, text, deps, replyToId, threadId }) => {
+  sendText: async ({ to, text, deps, replyToId, threadId, accountId }) => {
     const send = deps?.sendMatrix ?? sendMessageMatrix;
     const resolvedThreadId =
       threadId !== undefined && threadId !== null ? String(threadId) : undefined;
     const result = await send(to, text, {
       replyToId: replyToId ?? undefined,
       threadId: resolvedThreadId,
+      accountId: accountId ?? undefined,
     });
     return {
       channel: "matrix",
@@ -21,7 +22,7 @@ export const matrixOutbound: ChannelOutboundAdapter = {
       roomId: result.roomId,
     };
   },
-  sendMedia: async ({ to, text, mediaUrl, deps, replyToId, threadId }) => {
+  sendMedia: async ({ to, text, mediaUrl, deps, replyToId, threadId, accountId }) => {
     const send = deps?.sendMatrix ?? sendMessageMatrix;
     const resolvedThreadId =
       threadId !== undefined && threadId !== null ? String(threadId) : undefined;
@@ -29,6 +30,7 @@ export const matrixOutbound: ChannelOutboundAdapter = {
       mediaUrl,
       replyToId: replyToId ?? undefined,
       threadId: resolvedThreadId,
+      accountId: accountId ?? undefined,
     });
     return {
       channel: "matrix",
@@ -36,11 +38,12 @@ export const matrixOutbound: ChannelOutboundAdapter = {
       roomId: result.roomId,
     };
   },
-  sendPoll: async ({ to, poll, threadId }) => {
+  sendPoll: async ({ to, poll, threadId, accountId }) => {
     const resolvedThreadId =
       threadId !== undefined && threadId !== null ? String(threadId) : undefined;
     const result = await sendPollMatrix(to, poll, {
       threadId: resolvedThreadId,
+      accountId: accountId ?? undefined,
     });
     return {
       channel: "matrix",

package/src/types.ts

@@ -39,11 +39,16 @@ export type MatrixActionConfig = {
   channelInfo?: boolean;
 };
 
+/** Per-account Matrix config (excludes the accounts field to prevent recursion). */
+export type MatrixAccountConfig = Omit<MatrixConfig, "accounts">;
+
 export type MatrixConfig = {
   /** Optional display name for this account (used in CLI/UI lists). */
   name?: string;
   /** If false, do not start Matrix. Default: true. */
   enabled?: boolean;
+  /** Multi-account configuration keyed by account ID. */
+  accounts?: Record<string, MatrixAccountConfig>;
   /** Matrix homeserver URL (https://matrix.example.org). */
   homeserver?: string;
   /** Matrix user id (@user:server). */