@openclaw/matrix 2026.2.15 → 2026.2.19

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

@@ -0,0 +1,132 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import type { PluginRuntime, RuntimeEnv } from "openclaw/plugin-sdk";
+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("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" }),
+    );
+  });
+});

package/src/matrix/monitor/replies.ts

@@ -53,8 +53,10 @@ export async function deliverMatrixReplies(params: {
 
     const shouldIncludeReply = (id?: string) =>
       Boolean(id) && (params.replyToMode === "all" || !hasReplied);
+    const replyToIdForReply = shouldIncludeReply(replyToId) ? replyToId : undefined;
 
     if (mediaList.length === 0) {
+      let sentTextChunk = false;
       for (const chunk of core.channel.text.chunkMarkdownTextWithMode(
         text,
         chunkLimit,
@@ -66,13 +68,14 @@ export async function deliverMatrixReplies(params: {
         }
         await sendMessageMatrix(params.roomId, trimmed, {
           client: params.client,
-          replyToId: shouldIncludeReply(replyToId) ? replyToId : undefined,
+          replyToId: replyToIdForReply,
           threadId: params.threadId,
           accountId: params.accountId,
         });
-        if (shouldIncludeReply(replyToId)) {
-          hasReplied = true;
-        }
+        sentTextChunk = true;
+      }
+      if (replyToIdForReply && !hasReplied && sentTextChunk) {
+        hasReplied = true;
       }
       continue;
     }
@@ -83,15 +86,15 @@ export async function deliverMatrixReplies(params: {
       await sendMessageMatrix(params.roomId, caption, {
         client: params.client,
         mediaUrl,
-        replyToId: shouldIncludeReply(replyToId) ? replyToId : undefined,
+        replyToId: replyToIdForReply,
         threadId: params.threadId,
         audioAsVoice: reply.audioAsVoice,
         accountId: params.accountId,
       });
-      if (shouldIncludeReply(replyToId)) {
-        hasReplied = true;
-      }
       first = false;
     }
+    if (replyToIdForReply && !hasReplied) {
+      hasReplied = true;
+    }
   }
 }

package/src/matrix/send/client.ts

@@ -1,14 +1,10 @@
 import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
-import type { CoreConfig } from "../../types.js";
 import { getMatrixRuntime } from "../../runtime.js";
+import type { CoreConfig } from "../../types.js";
 import { getActiveMatrixClient, getAnyActiveMatrixClient } from "../active-client.js";
-import {
-  createMatrixClient,
-  isBunRuntime,
-  resolveMatrixAuth,
-  resolveSharedMatrixClient,
-} from "../client.js";
+import { createPreparedMatrixClient } from "../client-bootstrap.js";
+import { isBunRuntime, resolveMatrixAuth, resolveSharedMatrixClient } from "../client.js";
 
 const getCore = () => getMatrixRuntime();
 
@@ -92,25 +88,10 @@ export async function resolveMatrixClient(opts: {
     return { client, stopOnDone: false };
   }
   const auth = await resolveMatrixAuth({ accountId });
-  const client = await createMatrixClient({
-    homeserver: auth.homeserver,
-    userId: auth.userId,
-    accessToken: auth.accessToken,
-    encryption: auth.encryption,
-    localTimeoutMs: opts.timeoutMs,
+  const client = await createPreparedMatrixClient({
+    auth,
+    timeoutMs: opts.timeoutMs,
     accountId,
   });
-  if (auth.encryption && client.crypto) {
-    try {
-      const joinedRooms = await client.getJoinedRooms();
-      await (client.crypto as { prepare: (rooms?: string[]) => Promise<void> }).prepare(
-        joinedRooms,
-      );
-    } catch {
-      // Ignore crypto prep failures for one-off sends; normal sync will retry.
-    }
-  }
-  // @vector-im/matrix-bot-sdk uses start() instead of startClient()
-  await client.start();
   return { client, stopOnDone: true };
 }

package/src/matrix/send.test.ts

@@ -40,11 +40,13 @@ const runtimeStub = {
     loadConfig: () => ({}),
   },
   media: {
-    loadWebMedia: (...args: unknown[]) => loadWebMediaMock(...args),
-    mediaKindFromMime: (...args: unknown[]) => mediaKindFromMimeMock(...args),
-    isVoiceCompatibleAudio: (...args: unknown[]) => isVoiceCompatibleAudioMock(...args),
-    getImageMetadata: (...args: unknown[]) => getImageMetadataMock(...args),
-    resizeToJpeg: (...args: unknown[]) => resizeToJpegMock(...args),
+    loadWebMedia: loadWebMediaMock as unknown as PluginRuntime["media"]["loadWebMedia"],
+    mediaKindFromMime:
+      mediaKindFromMimeMock as unknown as PluginRuntime["media"]["mediaKindFromMime"],
+    isVoiceCompatibleAudio:
+      isVoiceCompatibleAudioMock as unknown as PluginRuntime["media"]["isVoiceCompatibleAudio"],
+    getImageMetadata: getImageMetadataMock as unknown as PluginRuntime["media"]["getImageMetadata"],
+    resizeToJpeg: resizeToJpegMock as unknown as PluginRuntime["media"]["resizeToJpeg"],
   },
   channel: {
     text: {

package/src/onboarding.ts

@@ -2,16 +2,17 @@ import type { DmPolicy } from "openclaw/plugin-sdk";
 import {
   addWildcardAllowFrom,
   formatDocsLink,
+  mergeAllowFromEntries,
   promptChannelAccessConfig,
   type ChannelOnboardingAdapter,
   type ChannelOnboardingDmPolicy,
   type WizardPrompter,
 } from "openclaw/plugin-sdk";
-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";
 import { resolveMatrixTargets } from "./resolve-targets.js";
+import type { CoreConfig } from "./types.js";
 
 const channel = "matrix" as const;
 
@@ -118,12 +119,7 @@ async function promptMatrixAllowFrom(params: {
       continue;
     }
 
-    const unique = [
-      ...new Set([
-        ...existingAllowFrom.map((item) => String(item).trim()).filter(Boolean),
-        ...resolvedIds,
-      ]),
-    ];
+    const unique = mergeAllowFromEntries(existingAllowFrom, resolvedIds);
     return {
       ...cfg,
       channels: {

package/src/resolve-targets.test.ts

@@ -1,6 +1,6 @@
 import type { ChannelDirectoryEntry } from "openclaw/plugin-sdk";
 import { describe, expect, it, vi, beforeEach } from "vitest";
-import { listMatrixDirectoryPeersLive } from "./directory-live.js";
+import { listMatrixDirectoryGroupsLive, listMatrixDirectoryPeersLive } from "./directory-live.js";
 import { resolveMatrixTargets } from "./resolve-targets.js";
 
 vi.mock("./directory-live.js", () => ({
@@ -11,6 +11,7 @@ vi.mock("./directory-live.js", () => ({
 describe("resolveMatrixTargets (users)", () => {
   beforeEach(() => {
     vi.mocked(listMatrixDirectoryPeersLive).mockReset();
+    vi.mocked(listMatrixDirectoryGroupsLive).mockReset();
   });
 
   it("resolves exact unique display name matches", async () => {
@@ -45,4 +46,22 @@ describe("resolveMatrixTargets (users)", () => {
     expect(result?.resolved).toBe(false);
     expect(result?.note).toMatch(/use full Matrix ID/i);
   });
+
+  it("prefers exact group matches over first partial result", async () => {
+    const matches: ChannelDirectoryEntry[] = [
+      { kind: "group", id: "!one:example.org", name: "General", handle: "#general" },
+      { kind: "group", id: "!two:example.org", name: "Team", handle: "#team" },
+    ];
+    vi.mocked(listMatrixDirectoryGroupsLive).mockResolvedValue(matches);
+
+    const [result] = await resolveMatrixTargets({
+      cfg: {},
+      inputs: ["#team"],
+      kind: "group",
+    });
+
+    expect(result?.resolved).toBe(true);
+    expect(result?.id).toBe("!two:example.org");
+    expect(result?.note).toBe("multiple matches; chose first");
+  });
 });

package/src/resolve-targets.ts

@@ -6,6 +6,22 @@ import type {
 } from "openclaw/plugin-sdk";
 import { listMatrixDirectoryGroupsLive, listMatrixDirectoryPeersLive } from "./directory-live.js";
 
+function findExactDirectoryMatches(
+  matches: ChannelDirectoryEntry[],
+  query: string,
+): ChannelDirectoryEntry[] {
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) {
+    return [];
+  }
+  return matches.filter((match) => {
+    const id = match.id.trim().toLowerCase();
+    const name = match.name?.trim().toLowerCase();
+    const handle = match.handle?.trim().toLowerCase();
+    return normalized === id || normalized === name || normalized === handle;
+  });
+}
+
 function pickBestGroupMatch(
   matches: ChannelDirectoryEntry[],
   query: string,
@@ -13,19 +29,8 @@ function pickBestGroupMatch(
   if (matches.length === 0) {
     return undefined;
   }
-  const normalized = query.trim().toLowerCase();
-  if (normalized) {
-    const exact = matches.find((match) => {
-      const name = match.name?.trim().toLowerCase();
-      const handle = match.handle?.trim().toLowerCase();
-      const id = match.id.trim().toLowerCase();
-      return name === normalized || handle === normalized || id === normalized;
-    });
-    if (exact) {
-      return exact;
-    }
-  }
-  return matches[0];
+  const [exact] = findExactDirectoryMatches(matches, query);
+  return exact ?? matches[0];
 }
 
 function pickBestUserMatch(
@@ -35,16 +40,7 @@ function pickBestUserMatch(
   if (matches.length === 0) {
     return undefined;
   }
-  const normalized = query.trim().toLowerCase();
-  if (!normalized) {
-    return undefined;
-  }
-  const exact = matches.filter((match) => {
-    const id = match.id.trim().toLowerCase();
-    const name = match.name?.trim().toLowerCase();
-    const handle = match.handle?.trim().toLowerCase();
-    return normalized === id || normalized === name || normalized === handle;
-  });
+  const exact = findExactDirectoryMatches(matches, query);
   if (exact.length === 1) {
     return exact[0];
   }
@@ -59,12 +55,7 @@ function describeUserMatchFailure(matches: ChannelDirectoryEntry[], query: strin
   if (!normalized) {
     return "empty input";
   }
-  const exact = matches.filter((match) => {
-    const id = match.id.trim().toLowerCase();
-    const name = match.name?.trim().toLowerCase();
-    const handle = match.handle?.trim().toLowerCase();
-    return normalized === id || normalized === name || normalized === handle;
-  });
+  const exact = findExactDirectoryMatches(matches, normalized);
   if (exact.length === 0) {
     return "no exact match; use full Matrix ID";
   }

package/src/tool-actions.ts

@@ -6,7 +6,6 @@ import {
   readReactionParams,
   readStringParam,
 } from "openclaw/plugin-sdk";
-import type { CoreConfig } from "./types.js";
 import {
   deleteMatrixMessage,
   editMatrixMessage,
@@ -21,6 +20,7 @@ import {
   unpinMatrixMessage,
 } from "./matrix/actions.js";
 import { reactMatrixMessage } from "./matrix/send.js";
+import type { CoreConfig } from "./types.js";
 
 const messageActions = new Set(["sendMessage", "editMessage", "deleteMessage", "readMessages"]);
 const reactionActions = new Set(["react", "reactions"]);