@openclaw/matrix 2026.2.22 → 2026.2.24

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026.2.24
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.2.22
 
 ### Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/matrix",
-  "version": "2026.2.22",
+  "version": "2026.2.24",
   "description": "OpenClaw Matrix channel plugin",
   "type": "module",
   "dependencies": {
@@ -10,9 +10,6 @@
     "music-metadata": "^11.12.1",
     "zod": "^4.3.6"
   },
-  "devDependencies": {
-    "openclaw": "workspace:*"
-  },
   "openclaw": {
     "extensions": [
       "./index.ts"

package/src/matrix/deps.ts

@@ -1,9 +1,8 @@
-import { spawn } from "node:child_process";
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import type { RuntimeEnv } from "openclaw/plugin-sdk";
+import { runPluginCommandWithTimeout, type RuntimeEnv } from "openclaw/plugin-sdk";
 
 const MATRIX_SDK_PACKAGE = "@vector-im/matrix-bot-sdk";
 
@@ -22,85 +21,6 @@ function resolvePluginRoot(): string {
   return path.resolve(currentDir, "..", "..");
 }
 
-type CommandResult = {
-  code: number;
-  stdout: string;
-  stderr: string;
-};
-
-async function runFixedCommandWithTimeout(params: {
-  argv: string[];
-  cwd: string;
-  timeoutMs: number;
-  env?: NodeJS.ProcessEnv;
-}): Promise<CommandResult> {
-  return await new Promise((resolve) => {
-    const [command, ...args] = params.argv;
-    if (!command) {
-      resolve({
-        code: 1,
-        stdout: "",
-        stderr: "command is required",
-      });
-      return;
-    }
-
-    const proc = spawn(command, args, {
-      cwd: params.cwd,
-      env: { ...process.env, ...params.env },
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-
-    let stdout = "";
-    let stderr = "";
-    let settled = false;
-    let timer: NodeJS.Timeout | null = null;
-
-    const finalize = (result: CommandResult) => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      if (timer) {
-        clearTimeout(timer);
-      }
-      resolve(result);
-    };
-
-    proc.stdout?.on("data", (chunk: Buffer | string) => {
-      stdout += chunk.toString();
-    });
-    proc.stderr?.on("data", (chunk: Buffer | string) => {
-      stderr += chunk.toString();
-    });
-
-    timer = setTimeout(() => {
-      proc.kill("SIGKILL");
-      finalize({
-        code: 124,
-        stdout,
-        stderr: stderr || `command timed out after ${params.timeoutMs}ms`,
-      });
-    }, params.timeoutMs);
-
-    proc.on("error", (err) => {
-      finalize({
-        code: 1,
-        stdout,
-        stderr: err.message,
-      });
-    });
-
-    proc.on("close", (code) => {
-      finalize({
-        code: code ?? 1,
-        stdout,
-        stderr,
-      });
-    });
-  });
-}
-
 export async function ensureMatrixSdkInstalled(params: {
   runtime: RuntimeEnv;
   confirm?: (message: string) => Promise<boolean>;
@@ -121,7 +41,7 @@ export async function ensureMatrixSdkInstalled(params: {
     ? ["pnpm", "install"]
     : ["npm", "install", "--omit=dev", "--silent"];
   params.runtime.log?.(`matrix: installing dependencies via ${command[0]} (${root})…`);
-  const result = await runFixedCommandWithTimeout({
+  const result = await runPluginCommandWithTimeout({
     argv: command,
     cwd: root,
     timeoutMs: 300_000,

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

@@ -0,0 +1,141 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import type { PluginRuntime, RuntimeLogger } from "openclaw/plugin-sdk";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { MatrixAuth } from "../client.js";
+import { registerMatrixMonitorEvents } from "./events.js";
+import type { MatrixRawEvent } from "./types.js";
+
+const sendReadReceiptMatrixMock = vi.hoisted(() => vi.fn().mockResolvedValue(undefined));
+
+vi.mock("../send.js", () => ({
+  sendReadReceiptMatrix: (...args: unknown[]) => sendReadReceiptMatrixMock(...args),
+}));
+
+describe("registerMatrixMonitorEvents", () => {
+  beforeEach(() => {
+    sendReadReceiptMatrixMock.mockClear();
+  });
+
+  function createHarness(options?: { getUserId?: ReturnType<typeof vi.fn> }) {
+    const handlers = new Map<string, (...args: unknown[]) => void>();
+    const getUserId = options?.getUserId ?? vi.fn().mockResolvedValue("@bot:example.org");
+    const client = {
+      on: vi.fn((event: string, handler: (...args: unknown[]) => void) => {
+        handlers.set(event, handler);
+      }),
+      getUserId,
+      crypto: undefined,
+    } as unknown as MatrixClient;
+
+    const onRoomMessage = vi.fn();
+    const logVerboseMessage = vi.fn();
+    const logger = {
+      warn: vi.fn(),
+    } as unknown as RuntimeLogger;
+
+    registerMatrixMonitorEvents({
+      client,
+      auth: { encryption: false } as MatrixAuth,
+      logVerboseMessage,
+      warnedEncryptedRooms: new Set<string>(),
+      warnedCryptoMissingRooms: new Set<string>(),
+      logger,
+      formatNativeDependencyHint: (() =>
+        "") as PluginRuntime["system"]["formatNativeDependencyHint"],
+      onRoomMessage,
+    });
+
+    const roomMessageHandler = handlers.get("room.message");
+    if (!roomMessageHandler) {
+      throw new Error("missing room.message handler");
+    }
+
+    return { client, getUserId, onRoomMessage, roomMessageHandler, logVerboseMessage };
+  }
+
+  it("sends read receipt immediately for non-self messages", async () => {
+    const { client, onRoomMessage, roomMessageHandler } = createHarness();
+    const event = {
+      event_id: "$e1",
+      sender: "@alice:example.org",
+    } as MatrixRawEvent;
+
+    roomMessageHandler("!room:example.org", event);
+
+    expect(onRoomMessage).toHaveBeenCalledWith("!room:example.org", event);
+    await vi.waitFor(() => {
+      expect(sendReadReceiptMatrixMock).toHaveBeenCalledWith("!room:example.org", "$e1", client);
+    });
+  });
+
+  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();
+  });
+
+  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();
+  });
+
+  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;
+
+    roomMessageHandler("!room:example.org", first);
+    roomMessageHandler("!room:example.org", second);
+
+    await vi.waitFor(() => {
+      expect(sendReadReceiptMatrixMock).toHaveBeenCalledTimes(2);
+    });
+    expect(getUserId).toHaveBeenCalledTimes(1);
+  });
+
+  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;
+
+    roomMessageHandler("!room:example.org", event);
+
+    await vi.waitFor(() => {
+      expect(onRoomMessage).toHaveBeenCalledWith("!room:example.org", event);
+      expect(logVerboseMessage).toHaveBeenCalledWith(
+        expect.stringContaining("matrix: early read receipt failed"),
+      );
+    });
+  });
+
+  it("skips read receipts if self-user lookup fails", async () => {
+    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;
+
+    roomMessageHandler("!room:example.org", event);
+
+    await vi.waitFor(() => {
+      expect(onRoomMessage).toHaveBeenCalledWith("!room:example.org", event);
+    });
+    expect(getUserId).toHaveBeenCalledTimes(1);
+    expect(sendReadReceiptMatrixMock).not.toHaveBeenCalled();
+  });
+});

package/src/matrix/monitor/events.ts

@@ -1,9 +1,36 @@
 import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
 import type { PluginRuntime, RuntimeLogger } from "openclaw/plugin-sdk";
 import type { MatrixAuth } from "../client.js";
+import { sendReadReceiptMatrix } from "../send.js";
 import type { MatrixRawEvent } from "./types.js";
 import { EventType } from "./types.js";
 
+function createSelfUserIdResolver(client: Pick<MatrixClient, "getUserId">) {
+  let selfUserId: string | undefined;
+  let selfUserIdLookup: Promise<string | undefined> | undefined;
+
+  return async (): Promise<string | undefined> => {
+    if (selfUserId) {
+      return selfUserId;
+    }
+    if (!selfUserIdLookup) {
+      selfUserIdLookup = client
+        .getUserId()
+        .then((userId) => {
+          selfUserId = userId;
+          return userId;
+        })
+        .catch(() => undefined)
+        .finally(() => {
+          if (!selfUserId) {
+            selfUserIdLookup = undefined;
+          }
+        });
+    }
+    return await selfUserIdLookup;
+  };
+}
+
 export function registerMatrixMonitorEvents(params: {
   client: MatrixClient;
   auth: MatrixAuth;
@@ -25,7 +52,26 @@ export function registerMatrixMonitorEvents(params: {
     onRoomMessage,
   } = params;
 
-  client.on("room.message", onRoomMessage);
+  const resolveSelfUserId = createSelfUserIdResolver(client);
+  client.on("room.message", (roomId: string, event: MatrixRawEvent) => {
+    const eventId = event?.event_id;
+    const senderId = event?.sender;
+    if (eventId && senderId) {
+      void (async () => {
+        const currentSelfUserId = await resolveSelfUserId();
+        if (!currentSelfUserId || senderId === currentSelfUserId) {
+          return;
+        }
+        await sendReadReceiptMatrix(roomId, eventId, client).catch((err) => {
+          logVerboseMessage(
+            `matrix: early read receipt failed room=${roomId} id=${eventId}: ${String(err)}`,
+          );
+        });
+      })();
+    }
+
+    onRoomMessage(roomId, event);
+  });
 
   client.on("room.encrypted_event", (roomId: string, event: MatrixRawEvent) => {
     const eventId = event?.event_id ?? "unknown";

package/src/matrix/monitor/handler.ts

@@ -18,12 +18,7 @@ import {
   parsePollStartContent,
   type PollStartContent,
 } from "../poll-types.js";
-import {
-  reactMatrixMessage,
-  sendMessageMatrix,
-  sendReadReceiptMatrix,
-  sendTypingMatrix,
-} from "../send.js";
+import { reactMatrixMessage, sendMessageMatrix, sendTypingMatrix } from "../send.js";
 import {
   normalizeMatrixAllowList,
   resolveMatrixAllowListMatch,
@@ -602,14 +597,6 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
         return;
       }
 
-      if (messageId) {
-        sendReadReceiptMatrix(roomId, messageId, client).catch((err) => {
-          logVerboseMessage(
-            `matrix: read receipt failed room=${roomId} id=${messageId}: ${String(err)}`,
-          );
-        });
-      }
-
       let didSendReply = false;
       const tableMode = core.channel.text.resolveMarkdownTableMode({
         cfg,
@@ -648,6 +635,7 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
         core.channel.reply.createReplyDispatcherWithTyping({
           ...prefixOptions,
           humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, route.agentId),
+          typingCallbacks,
           deliver: async (payload) => {
             await deliverMatrixReplies({
               replies: [payload],
@@ -665,8 +653,6 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
           onError: (err, info) => {
             runtime.error?.(`matrix ${info.kind} reply failed: ${String(err)}`);
           },
-          onReplyStart: typingCallbacks.onReplyStart,
-          onIdle: typingCallbacks.onIdle,
         });
 
       const { queuedFinal, counts } = await core.channel.reply.dispatchReplyFromConfig({

package/src/matrix/monitor/index.ts

@@ -1,5 +1,5 @@
-import { format } from "node:util";
 import {
+  createLoggerBackedRuntime,
   GROUP_POLICY_BLOCKED_LABEL,
   mergeAllowlist,
   resolveAllowlistProviderRuntimeGroupPolicy,
@@ -48,18 +48,11 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
   }
 
   const logger = core.logging.getChildLogger({ module: "matrix-auto-reply" });
-  const formatRuntimeMessage = (...args: Parameters<RuntimeEnv["log"]>) => format(...args);
-  const runtime: RuntimeEnv = opts.runtime ?? {
-    log: (...args) => {
-      logger.info(formatRuntimeMessage(...args));
-    },
-    error: (...args) => {
-      logger.error(formatRuntimeMessage(...args));
-    },
-    exit: (code: number): never => {
-      throw new Error(`exit ${code}`);
-    },
-  };
+  const runtime: RuntimeEnv =
+    opts.runtime ??
+    createLoggerBackedRuntime({
+      logger,
+    });
   const logVerboseMessage = (message: string) => {
     if (!core.logging.shouldLogVerbose()) {
       return;

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

@@ -108,6 +108,58 @@ describe("deliverMatrixReplies", () => {
     );
   });
 
+  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("|"));
 

package/src/matrix/monitor/replies.ts

@@ -41,6 +41,11 @@ export async function deliverMatrixReplies(params: {
       params.runtime.error?.("matrix reply missing text/media");
       continue;
     }
+    // Skip pure reasoning messages so internal thinking traces are never delivered.
+    if (reply.text && isReasoningOnlyMessage(reply.text)) {
+      logVerbose("matrix reply is reasoning-only; skipping");
+      continue;
+    }
     const replyToIdRaw = reply.replyToId?.trim();
     const replyToId = params.threadId || params.replyToMode === "off" ? undefined : replyToIdRaw;
     const rawText = reply.text ?? "";
@@ -98,3 +103,22 @@ export async function deliverMatrixReplies(params: {
     }
   }
 }
+
+const REASONING_PREFIX = "Reasoning:\n";
+const THINKING_TAG_RE = /^\s*<\s*(?:think(?:ing)?|thought|antthinking)\b/i;
+
+/**
+ * Detect messages that contain only reasoning/thinking content and no user-facing answer.
+ * These are emitted by the agent when `includeReasoning` is active but should not
+ * be forwarded to channels that do not support a dedicated reasoning lane.
+ */
+function isReasoningOnlyMessage(text: string): boolean {
+  const trimmed = text.trim();
+  if (trimmed.startsWith(REASONING_PREFIX)) {
+    return true;
+  }
+  if (THINKING_TAG_RE.test(trimmed)) {
+    return true;
+  }
+  return false;
+}

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

@@ -0,0 +1,154 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+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();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("serializes sends per room", async () => {
+    const gate = deferred<void>();
+    const events: string[] = [];
+
+    const first = enqueueSend("!room:example.org", async () => {
+      events.push("start1");
+      await gate.promise;
+      events.push("end1");
+      return "one";
+    });
+    const second = enqueueSend("!room:example.org", async () => {
+      events.push("start2");
+      events.push("end2");
+      return "two";
+    });
+
+    await vi.advanceTimersByTimeAsync(DEFAULT_SEND_GAP_MS);
+    expect(events).toEqual(["start1"]);
+
+    await vi.advanceTimersByTimeAsync(DEFAULT_SEND_GAP_MS * 2);
+    expect(events).toEqual(["start1"]);
+
+    gate.resolve();
+    await first;
+    await vi.advanceTimersByTimeAsync(DEFAULT_SEND_GAP_MS - 1);
+    expect(events).toEqual(["start1", "end1"]);
+    await vi.advanceTimersByTimeAsync(1);
+    await second;
+    expect(events).toEqual(["start1", "end1", "start2", "end2"]);
+  });
+
+  it("does not serialize across different rooms", async () => {
+    const events: string[] = [];
+
+    const a = enqueueSend("!a:example.org", async () => {
+      events.push("a");
+      return "a";
+    });
+    const b = enqueueSend("!b:example.org", async () => {
+      events.push("b");
+      return "b";
+    });
+
+    await vi.advanceTimersByTimeAsync(DEFAULT_SEND_GAP_MS);
+    await Promise.all([a, b]);
+    expect(events.sort()).toEqual(["a", "b"]);
+  });
+
+  it("continues queue after failures", async () => {
+    const first = enqueueSend("!room:example.org", async () => {
+      throw new Error("boom");
+    }).then(
+      () => ({ ok: true as const }),
+      (error) => ({ ok: false as const, error }),
+    );
+
+    await vi.advanceTimersByTimeAsync(DEFAULT_SEND_GAP_MS);
+    const firstResult = await first;
+    expect(firstResult.ok).toBe(false);
+    if (firstResult.ok) {
+      throw new Error("expected first queue item to fail");
+    }
+    expect(firstResult.error).toBeInstanceOf(Error);
+    expect(firstResult.error.message).toBe("boom");
+
+    const second = enqueueSend("!room:example.org", async () => "ok");
+    await vi.advanceTimersByTimeAsync(DEFAULT_SEND_GAP_MS);
+    await expect(second).resolves.toBe("ok");
+  });
+
+  it("continues queued work when the head task fails", async () => {
+    const gate = deferred<void>();
+    const events: string[] = [];
+
+    const first = enqueueSend("!room:example.org", async () => {
+      events.push("start1");
+      await gate.promise;
+      throw new Error("boom");
+    }).then(
+      () => ({ ok: true as const }),
+      (error) => ({ ok: false as const, error }),
+    );
+    const second = enqueueSend("!room:example.org", async () => {
+      events.push("start2");
+      return "two";
+    });
+
+    await vi.advanceTimersByTimeAsync(DEFAULT_SEND_GAP_MS);
+    expect(events).toEqual(["start1"]);
+
+    gate.resolve();
+    const firstResult = await first;
+    expect(firstResult.ok).toBe(false);
+    if (firstResult.ok) {
+      throw new Error("expected head queue item to fail");
+    }
+    expect(firstResult.error).toBeInstanceOf(Error);
+
+    await vi.advanceTimersByTimeAsync(DEFAULT_SEND_GAP_MS);
+    await expect(second).resolves.toBe("two");
+    expect(events).toEqual(["start1", "start2"]);
+  });
+
+  it("supports custom gap and delay injection", async () => {
+    const events: string[] = [];
+    const delayFn = vi.fn(async (_ms: number) => {});
+
+    const first = enqueueSend(
+      "!room:example.org",
+      async () => {
+        events.push("first");
+        return "one";
+      },
+      { gapMs: 7, delayFn },
+    );
+    const second = enqueueSend(
+      "!room:example.org",
+      async () => {
+        events.push("second");
+        return "two";
+      },
+      { gapMs: 7, delayFn },
+    );
+
+    await expect(first).resolves.toBe("one");
+    await expect(second).resolves.toBe("two");
+    expect(events).toEqual(["first", "second"]);
+    expect(delayFn).toHaveBeenCalledTimes(2);
+    expect(delayFn).toHaveBeenNthCalledWith(1, 7);
+    expect(delayFn).toHaveBeenNthCalledWith(2, 7);
+  });
+});

package/src/matrix/send-queue.ts

@@ -0,0 +1,44 @@
+export const DEFAULT_SEND_GAP_MS = 150;
+
+type MatrixSendQueueOptions = {
+  gapMs?: number;
+  delayFn?: (ms: number) => Promise<void>;
+};
+
+// Serialize sends per room to preserve Matrix delivery order.
+const roomQueues = new Map<string, Promise<void>>();
+
+export async function enqueueSend<T>(
+  roomId: string,
+  fn: () => Promise<T>,
+  options?: MatrixSendQueueOptions,
+): Promise<T> {
+  const gapMs = options?.gapMs ?? DEFAULT_SEND_GAP_MS;
+  const delayFn = options?.delayFn ?? delay;
+  const previous = roomQueues.get(roomId) ?? Promise.resolve();
+
+  const next = previous
+    .catch(() => {})
+    .then(async () => {
+      await delayFn(gapMs);
+      return await fn();
+    });
+
+  const queueMarker = next.then(
+    () => {},
+    () => {},
+  );
+  roomQueues.set(roomId, queueMarker);
+
+  queueMarker.finally(() => {
+    if (roomQueues.get(roomId) === queueMarker) {
+      roomQueues.delete(roomId);
+    }
+  });
+
+  return await next;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/matrix/send.ts

@@ -2,6 +2,7 @@ import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
 import type { PollInput } from "openclaw/plugin-sdk";
 import { getMatrixRuntime } from "../runtime.js";
 import { buildPollStartContent, M_POLL_START } from "./poll-types.js";
+import { enqueueSend } from "./send-queue.js";
 import { resolveMatrixClient, resolveMediaMaxBytes } from "./send/client.js";
 import {
   buildReplyRelation,
@@ -49,103 +50,105 @@ export async function sendMessageMatrix(
   });
   try {
     const roomId = await resolveMatrixRoomId(client, to);
-    const cfg = getCore().config.loadConfig();
-    const tableMode = getCore().channel.text.resolveMarkdownTableMode({
-      cfg,
-      channel: "matrix",
-      accountId: opts.accountId,
-    });
-    const convertedMessage = getCore().channel.text.convertMarkdownTables(
-      trimmedMessage,
-      tableMode,
-    );
-    const textLimit = getCore().channel.text.resolveTextChunkLimit(cfg, "matrix");
-    const chunkLimit = Math.min(textLimit, MATRIX_TEXT_LIMIT);
-    const chunkMode = getCore().channel.text.resolveChunkMode(cfg, "matrix", opts.accountId);
-    const chunks = getCore().channel.text.chunkMarkdownTextWithMode(
-      convertedMessage,
-      chunkLimit,
-      chunkMode,
-    );
-    const threadId = normalizeThreadId(opts.threadId);
-    const relation = threadId
-      ? buildThreadRelation(threadId, opts.replyToId)
-      : buildReplyRelation(opts.replyToId);
-    const sendContent = async (content: MatrixOutboundContent) => {
-      // @vector-im/matrix-bot-sdk uses sendMessage differently
-      const eventId = await client.sendMessage(roomId, content);
-      return eventId;
-    };
-
-    let lastMessageId = "";
-    if (opts.mediaUrl) {
-      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,
-        filename: media.fileName,
-      });
-      const durationMs = await resolveMediaDurationMs({
-        buffer: media.buffer,
-        contentType: media.contentType,
-        fileName: media.fileName,
-        kind: media.kind,
+    return await enqueueSend(roomId, async () => {
+      const cfg = getCore().config.loadConfig();
+      const tableMode = getCore().channel.text.resolveMarkdownTableMode({
+        cfg,
+        channel: "matrix",
+        accountId: opts.accountId,
       });
-      const baseMsgType = resolveMatrixMsgType(media.contentType, media.fileName);
-      const { useVoice } = resolveMatrixVoiceDecision({
-        wantsVoice: opts.audioAsVoice === true,
-        contentType: media.contentType,
-        fileName: media.fileName,
-      });
-      const msgtype = useVoice ? MsgType.Audio : baseMsgType;
-      const isImage = msgtype === MsgType.Image;
-      const imageInfo = isImage
-        ? await prepareImageInfo({ buffer: media.buffer, client })
-        : undefined;
-      const [firstChunk, ...rest] = chunks;
-      const body = useVoice ? "Voice message" : (firstChunk ?? media.fileName ?? "(file)");
-      const content = buildMediaContent({
-        msgtype,
-        body,
-        url: uploaded.url,
-        file: uploaded.file,
-        filename: media.fileName,
-        mimetype: media.contentType,
-        size: media.buffer.byteLength,
-        durationMs,
-        relation,
-        isVoice: useVoice,
-        imageInfo,
-      });
-      const eventId = await sendContent(content);
-      lastMessageId = eventId ?? lastMessageId;
-      const textChunks = useVoice ? chunks : rest;
-      const followupRelation = threadId ? relation : undefined;
-      for (const chunk of textChunks) {
-        const text = chunk.trim();
-        if (!text) {
-          continue;
-        }
-        const followup = buildTextContent(text, followupRelation);
-        const followupEventId = await sendContent(followup);
-        lastMessageId = followupEventId ?? lastMessageId;
-      }
-    } else {
-      for (const chunk of chunks.length ? chunks : [""]) {
-        const text = chunk.trim();
-        if (!text) {
-          continue;
-        }
-        const content = buildTextContent(text, relation);
+      const convertedMessage = getCore().channel.text.convertMarkdownTables(
+        trimmedMessage,
+        tableMode,
+      );
+      const textLimit = getCore().channel.text.resolveTextChunkLimit(cfg, "matrix");
+      const chunkLimit = Math.min(textLimit, MATRIX_TEXT_LIMIT);
+      const chunkMode = getCore().channel.text.resolveChunkMode(cfg, "matrix", opts.accountId);
+      const chunks = getCore().channel.text.chunkMarkdownTextWithMode(
+        convertedMessage,
+        chunkLimit,
+        chunkMode,
+      );
+      const threadId = normalizeThreadId(opts.threadId);
+      const relation = threadId
+        ? buildThreadRelation(threadId, opts.replyToId)
+        : buildReplyRelation(opts.replyToId);
+      const sendContent = async (content: MatrixOutboundContent) => {
+        // @vector-im/matrix-bot-sdk uses sendMessage differently
+        const eventId = await client.sendMessage(roomId, content);
+        return eventId;
+      };
+
+      let lastMessageId = "";
+      if (opts.mediaUrl) {
+        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,
+          filename: media.fileName,
+        });
+        const durationMs = await resolveMediaDurationMs({
+          buffer: media.buffer,
+          contentType: media.contentType,
+          fileName: media.fileName,
+          kind: media.kind,
+        });
+        const baseMsgType = resolveMatrixMsgType(media.contentType, media.fileName);
+        const { useVoice } = resolveMatrixVoiceDecision({
+          wantsVoice: opts.audioAsVoice === true,
+          contentType: media.contentType,
+          fileName: media.fileName,
+        });
+        const msgtype = useVoice ? MsgType.Audio : baseMsgType;
+        const isImage = msgtype === MsgType.Image;
+        const imageInfo = isImage
+          ? await prepareImageInfo({ buffer: media.buffer, client })
+          : undefined;
+        const [firstChunk, ...rest] = chunks;
+        const body = useVoice ? "Voice message" : (firstChunk ?? media.fileName ?? "(file)");
+        const content = buildMediaContent({
+          msgtype,
+          body,
+          url: uploaded.url,
+          file: uploaded.file,
+          filename: media.fileName,
+          mimetype: media.contentType,
+          size: media.buffer.byteLength,
+          durationMs,
+          relation,
+          isVoice: useVoice,
+          imageInfo,
+        });
         const eventId = await sendContent(content);
         lastMessageId = eventId ?? lastMessageId;
+        const textChunks = useVoice ? chunks : rest;
+        const followupRelation = threadId ? relation : undefined;
+        for (const chunk of textChunks) {
+          const text = chunk.trim();
+          if (!text) {
+            continue;
+          }
+          const followup = buildTextContent(text, followupRelation);
+          const followupEventId = await sendContent(followup);
+          lastMessageId = followupEventId ?? lastMessageId;
+        }
+      } else {
+        for (const chunk of chunks.length ? chunks : [""]) {
+          const text = chunk.trim();
+          if (!text) {
+            continue;
+          }
+          const content = buildTextContent(text, relation);
+          const eventId = await sendContent(content);
+          lastMessageId = eventId ?? lastMessageId;
+        }
       }
-    }
 
-    return {
-      messageId: lastMessageId || "unknown",
-      roomId,
-    };
+      return {
+        messageId: lastMessageId || "unknown",
+        roomId,
+      };
+    });
   } finally {
     if (stopOnDone) {
       client.stop();