@openclaw/matrix 2026.3.13 → 2026.5.10-beta.1

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

@@ -1,86 +0,0 @@
-import type { PluginRuntime } from "openclaw/plugin-sdk/matrix";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { setMatrixRuntime } from "../../runtime.js";
-import { downloadMatrixMedia } from "./media.js";
-
-describe("downloadMatrixMedia", () => {
-  const saveMediaBuffer = vi.fn().mockResolvedValue({
-    path: "/tmp/media",
-    contentType: "image/png",
-  });
-
-  const runtimeStub = {
-    channel: {
-      media: {
-        saveMediaBuffer: (...args: unknown[]) => saveMediaBuffer(...args),
-      },
-    },
-  } as unknown as PluginRuntime;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    setMatrixRuntime(runtimeStub);
-  });
-
-  function makeEncryptedMediaFixture() {
-    const decryptMedia = vi.fn().mockResolvedValue(Buffer.from("decrypted"));
-    const client = {
-      crypto: { decryptMedia },
-      mxcToHttp: vi.fn().mockReturnValue("https://example/mxc"),
-    } as unknown as import("@vector-im/matrix-bot-sdk").MatrixClient;
-    const file = {
-      url: "mxc://example/file",
-      key: {
-        kty: "oct",
-        key_ops: ["encrypt", "decrypt"],
-        alg: "A256CTR",
-        k: "secret",
-        ext: true,
-      },
-      iv: "iv",
-      hashes: { sha256: "hash" },
-      v: "v2",
-    };
-    return { decryptMedia, client, file };
-  }
-
-  it("decrypts encrypted media when file payloads are present", async () => {
-    const { decryptMedia, client, file } = makeEncryptedMediaFixture();
-
-    const result = await downloadMatrixMedia({
-      client,
-      mxcUrl: "mxc://example/file",
-      contentType: "image/png",
-      maxBytes: 1024,
-      file,
-    });
-
-    // decryptMedia should be called with just the file object (it handles download internally)
-    expect(decryptMedia).toHaveBeenCalledWith(file);
-    expect(saveMediaBuffer).toHaveBeenCalledWith(
-      Buffer.from("decrypted"),
-      "image/png",
-      "inbound",
-      1024,
-    );
-    expect(result?.path).toBe("/tmp/media");
-  });
-
-  it("rejects encrypted media that exceeds maxBytes before decrypting", async () => {
-    const { decryptMedia, client, file } = makeEncryptedMediaFixture();
-
-    await expect(
-      downloadMatrixMedia({
-        client,
-        mxcUrl: "mxc://example/file",
-        contentType: "image/png",
-        sizeBytes: 2048,
-        maxBytes: 1024,
-        file,
-      }),
-    ).rejects.toThrow("Matrix media exceeds configured size limit");
-
-    expect(decryptMedia).not.toHaveBeenCalled();
-    expect(saveMediaBuffer).not.toHaveBeenCalled();
-  });
-});

package/src/matrix/monitor/media.ts

@@ -1,118 +0,0 @@
-import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-import { getMatrixRuntime } from "../../runtime.js";
-
-// Type for encrypted file info
-type EncryptedFile = {
-  url: string;
-  key: {
-    kty: string;
-    key_ops: string[];
-    alg: string;
-    k: string;
-    ext: boolean;
-  };
-  iv: string;
-  hashes: Record<string, string>;
-  v: string;
-};
-
-async function fetchMatrixMediaBuffer(params: {
-  client: MatrixClient;
-  mxcUrl: string;
-  maxBytes: number;
-}): Promise<{ buffer: Buffer; headerType?: string } | null> {
-  // @vector-im/matrix-bot-sdk provides mxcToHttp helper
-  const url = params.client.mxcToHttp(params.mxcUrl);
-  if (!url) {
-    return null;
-  }
-
-  // Use the client's download method which handles auth
-  try {
-    const result = await params.client.downloadContent(params.mxcUrl);
-    const raw = result.data ?? result;
-    const buffer = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
-
-    if (buffer.byteLength > params.maxBytes) {
-      throw new Error("Matrix media exceeds configured size limit");
-    }
-    return { buffer, headerType: result.contentType };
-  } catch (err) {
-    throw new Error(`Matrix media download failed: ${String(err)}`, { cause: err });
-  }
-}
-
-/**
- * Download and decrypt encrypted media from a Matrix room.
- * Uses @vector-im/matrix-bot-sdk's decryptMedia which handles both download and decryption.
- */
-async function fetchEncryptedMediaBuffer(params: {
-  client: MatrixClient;
-  file: EncryptedFile;
-  maxBytes: number;
-}): Promise<{ buffer: Buffer } | null> {
-  if (!params.client.crypto) {
-    throw new Error("Cannot decrypt media: crypto not enabled");
-  }
-
-  // decryptMedia handles downloading and decrypting the encrypted content internally
-  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");
-  }
-
-  return { buffer: decrypted };
-}
-
-export async function downloadMatrixMedia(params: {
-  client: MatrixClient;
-  mxcUrl: string;
-  contentType?: string;
-  sizeBytes?: number;
-  maxBytes: number;
-  file?: EncryptedFile;
-}): Promise<{
-  path: string;
-  contentType?: string;
-  placeholder: string;
-} | null> {
-  let fetched: { buffer: Buffer; headerType?: string } | null;
-  if (typeof params.sizeBytes === "number" && params.sizeBytes > params.maxBytes) {
-    throw new Error("Matrix media exceeds configured size limit");
-  }
-
-  if (params.file) {
-    // Encrypted media
-    fetched = await fetchEncryptedMediaBuffer({
-      client: params.client,
-      file: params.file,
-      maxBytes: params.maxBytes,
-    });
-  } else {
-    // Unencrypted media
-    fetched = await fetchMatrixMediaBuffer({
-      client: params.client,
-      mxcUrl: params.mxcUrl,
-      maxBytes: params.maxBytes,
-    });
-  }
-
-  if (!fetched) {
-    return null;
-  }
-  const headerType = fetched.headerType ?? params.contentType ?? undefined;
-  const saved = await getMatrixRuntime().channel.media.saveMediaBuffer(
-    fetched.buffer,
-    headerType,
-    "inbound",
-    params.maxBytes,
-  );
-  return {
-    path: saved.path,
-    contentType: saved.contentType,
-    placeholder: "[matrix media]",
-  };
-}

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

@@ -1,154 +0,0 @@
-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

@@ -1,62 +0,0 @@
-import { getMatrixRuntime } from "../../runtime.js";
-
-// Type for room message content with mentions
-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;
-  text?: string;
-  mentionRegexes: RegExp[];
-}) {
-  const mentions = params.content["m.mentions"];
-  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,
-    );
-  return { wasMentioned, hasExplicitMention: Boolean(mentions) };
-}

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

@@ -1,184 +0,0 @@
-import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-import type { PluginRuntime, RuntimeEnv } from "openclaw/plugin-sdk/matrix";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const sendMessageMatrixMock = vi.hoisted(() => vi.fn().mockResolvedValue({ messageId: "mx-1" }));
-
-vi.mock("../send.js", () => ({
-  sendMessageMatrix: (to: string, message: string, opts?: unknown) =>
-    sendMessageMatrixMock(to, message, opts),
-}));
-
-import { setMatrixRuntime } from "../../runtime.js";
-import { deliverMatrixReplies } from "./replies.js";
-
-describe("deliverMatrixReplies", () => {
-  const loadConfigMock = vi.fn(() => ({}));
-  const resolveMarkdownTableModeMock = vi.fn(() => "code");
-  const convertMarkdownTablesMock = vi.fn((text: string) => text);
-  const resolveChunkModeMock = vi.fn(() => "length");
-  const chunkMarkdownTextWithModeMock = vi.fn((text: string) => [text]);
-
-  const runtimeStub = {
-    config: {
-      loadConfig: () => loadConfigMock(),
-    },
-    channel: {
-      text: {
-        resolveMarkdownTableMode: () => resolveMarkdownTableModeMock(),
-        convertMarkdownTables: (text: string) => convertMarkdownTablesMock(text),
-        resolveChunkMode: () => resolveChunkModeMock(),
-        chunkMarkdownTextWithMode: (text: string) => chunkMarkdownTextWithModeMock(text),
-      },
-    },
-    logging: {
-      shouldLogVerbose: () => false,
-    },
-  } as unknown as PluginRuntime;
-
-  const runtimeEnv: RuntimeEnv = {
-    log: vi.fn(),
-    error: vi.fn(),
-  } as unknown as RuntimeEnv;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    setMatrixRuntime(runtimeStub);
-    chunkMarkdownTextWithModeMock.mockImplementation((text: string) => [text]);
-  });
-
-  it("keeps replyToId on first reply only when replyToMode=first", async () => {
-    chunkMarkdownTextWithModeMock.mockImplementation((text: string) => text.split("|"));
-
-    await deliverMatrixReplies({
-      replies: [
-        { text: "first-a|first-b", replyToId: "reply-1" },
-        { text: "second", replyToId: "reply-2" },
-      ],
-      roomId: "room:1",
-      client: {} as MatrixClient,
-      runtime: runtimeEnv,
-      textLimit: 4000,
-      replyToMode: "first",
-    });
-
-    expect(sendMessageMatrixMock).toHaveBeenCalledTimes(3);
-    expect(sendMessageMatrixMock.mock.calls[0]?.[2]).toEqual(
-      expect.objectContaining({ replyToId: "reply-1", threadId: undefined }),
-    );
-    expect(sendMessageMatrixMock.mock.calls[1]?.[2]).toEqual(
-      expect.objectContaining({ replyToId: "reply-1", threadId: undefined }),
-    );
-    expect(sendMessageMatrixMock.mock.calls[2]?.[2]).toEqual(
-      expect.objectContaining({ replyToId: undefined, threadId: undefined }),
-    );
-  });
-
-  it("keeps replyToId on every reply when replyToMode=all", async () => {
-    await deliverMatrixReplies({
-      replies: [
-        {
-          text: "caption",
-          mediaUrls: ["https://example.com/a.jpg", "https://example.com/b.jpg"],
-          replyToId: "reply-media",
-          audioAsVoice: true,
-        },
-        { text: "plain", replyToId: "reply-text" },
-      ],
-      roomId: "room:2",
-      client: {} as MatrixClient,
-      runtime: runtimeEnv,
-      textLimit: 4000,
-      replyToMode: "all",
-    });
-
-    expect(sendMessageMatrixMock).toHaveBeenCalledTimes(3);
-    expect(sendMessageMatrixMock.mock.calls[0]).toEqual([
-      "room:2",
-      "caption",
-      expect.objectContaining({ mediaUrl: "https://example.com/a.jpg", replyToId: "reply-media" }),
-    ]);
-    expect(sendMessageMatrixMock.mock.calls[1]).toEqual([
-      "room:2",
-      "",
-      expect.objectContaining({ mediaUrl: "https://example.com/b.jpg", replyToId: "reply-media" }),
-    ]);
-    expect(sendMessageMatrixMock.mock.calls[2]?.[2]).toEqual(
-      expect.objectContaining({ replyToId: "reply-text" }),
-    );
-  });
-
-  it("skips reasoning-only replies with Reasoning prefix", async () => {
-    await deliverMatrixReplies({
-      replies: [
-        { text: "Reasoning:\nThe user wants X because Y.", replyToId: "r1" },
-        { text: "Here is the answer.", replyToId: "r2" },
-      ],
-      roomId: "room:reason",
-      client: {} as MatrixClient,
-      runtime: runtimeEnv,
-      textLimit: 4000,
-      replyToMode: "first",
-    });
-
-    expect(sendMessageMatrixMock).toHaveBeenCalledTimes(1);
-    expect(sendMessageMatrixMock.mock.calls[0]?.[1]).toBe("Here is the answer.");
-  });
-
-  it("skips reasoning-only replies with thinking tags", async () => {
-    await deliverMatrixReplies({
-      replies: [
-        { text: "<thinking>internal chain of thought</thinking>", replyToId: "r1" },
-        { text: "  <think>more reasoning</think>  ", replyToId: "r2" },
-        { text: "<antthinking>hidden</antthinking>", replyToId: "r3" },
-        { text: "Visible reply", replyToId: "r4" },
-      ],
-      roomId: "room:tags",
-      client: {} as MatrixClient,
-      runtime: runtimeEnv,
-      textLimit: 4000,
-      replyToMode: "all",
-    });
-
-    expect(sendMessageMatrixMock).toHaveBeenCalledTimes(1);
-    expect(sendMessageMatrixMock.mock.calls[0]?.[1]).toBe("Visible reply");
-  });
-
-  it("delivers all replies when none are reasoning-only", async () => {
-    await deliverMatrixReplies({
-      replies: [
-        { text: "First answer", replyToId: "r1" },
-        { text: "Second answer", replyToId: "r2" },
-      ],
-      roomId: "room:normal",
-      client: {} as MatrixClient,
-      runtime: runtimeEnv,
-      textLimit: 4000,
-      replyToMode: "all",
-    });
-
-    expect(sendMessageMatrixMock).toHaveBeenCalledTimes(2);
-  });
-
-  it("suppresses replyToId when threadId is set", async () => {
-    chunkMarkdownTextWithModeMock.mockImplementation((text: string) => text.split("|"));
-
-    await deliverMatrixReplies({
-      replies: [{ text: "hello|thread", replyToId: "reply-thread" }],
-      roomId: "room:3",
-      client: {} as MatrixClient,
-      runtime: runtimeEnv,
-      textLimit: 4000,
-      replyToMode: "all",
-      threadId: "thread-77",
-    });
-
-    expect(sendMessageMatrixMock).toHaveBeenCalledTimes(2);
-    expect(sendMessageMatrixMock.mock.calls[0]?.[2]).toEqual(
-      expect.objectContaining({ replyToId: undefined, threadId: "thread-77" }),
-    );
-    expect(sendMessageMatrixMock.mock.calls[1]?.[2]).toEqual(
-      expect.objectContaining({ replyToId: undefined, threadId: "thread-77" }),
-    );
-  });
-});