@openclaw/matrix 2026.3.12 → 2026.5.9-beta.1

package/src/matrix/monitor/replies.ts

@@ -1,124 +0,0 @@
-import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-import type { MarkdownTableMode, ReplyPayload, RuntimeEnv } from "openclaw/plugin-sdk/matrix";
-import { getMatrixRuntime } from "../../runtime.js";
-import { sendMessageMatrix } from "../send.js";
-
-export async function deliverMatrixReplies(params: {
-  replies: ReplyPayload[];
-  roomId: string;
-  client: MatrixClient;
-  runtime: RuntimeEnv;
-  textLimit: number;
-  replyToMode: "off" | "first" | "all";
-  threadId?: string;
-  accountId?: string;
-  tableMode?: MarkdownTableMode;
-}): Promise<void> {
-  const core = getMatrixRuntime();
-  const cfg = core.config.loadConfig();
-  const tableMode =
-    params.tableMode ??
-    core.channel.text.resolveMarkdownTableMode({
-      cfg,
-      channel: "matrix",
-      accountId: params.accountId,
-    });
-  const logVerbose = (message: string) => {
-    if (core.logging.shouldLogVerbose()) {
-      params.runtime.log?.(message);
-    }
-  };
-  const chunkLimit = Math.min(params.textLimit, 4000);
-  const chunkMode = core.channel.text.resolveChunkMode(cfg, "matrix", params.accountId);
-  let hasReplied = false;
-  for (const reply of params.replies) {
-    const hasMedia = Boolean(reply?.mediaUrl) || (reply?.mediaUrls?.length ?? 0) > 0;
-    if (!reply?.text && !hasMedia) {
-      if (reply?.audioAsVoice) {
-        logVerbose("matrix reply has audioAsVoice without media/text; skipping");
-        continue;
-      }
-      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 ?? "";
-    const text = core.channel.text.convertMarkdownTables(rawText, tableMode);
-    const mediaList = reply.mediaUrls?.length
-      ? reply.mediaUrls
-      : reply.mediaUrl
-        ? [reply.mediaUrl]
-        : [];
-
-    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,
-        chunkMode,
-      )) {
-        const trimmed = chunk.trim();
-        if (!trimmed) {
-          continue;
-        }
-        await sendMessageMatrix(params.roomId, trimmed, {
-          client: params.client,
-          replyToId: replyToIdForReply,
-          threadId: params.threadId,
-          accountId: params.accountId,
-        });
-        sentTextChunk = true;
-      }
-      if (replyToIdForReply && !hasReplied && sentTextChunk) {
-        hasReplied = true;
-      }
-      continue;
-    }
-
-    let first = true;
-    for (const mediaUrl of mediaList) {
-      const caption = first ? text : "";
-      await sendMessageMatrix(params.roomId, caption, {
-        client: params.client,
-        mediaUrl,
-        replyToId: replyToIdForReply,
-        threadId: params.threadId,
-        audioAsVoice: reply.audioAsVoice,
-        accountId: params.accountId,
-      });
-      first = false;
-    }
-    if (replyToIdForReply && !hasReplied) {
-      hasReplied = true;
-    }
-  }
-}
-
-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/monitor/room-info.ts

@@ -1,55 +0,0 @@
-import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-
-export type MatrixRoomInfo = {
-  name?: string;
-  canonicalAlias?: string;
-  altAliases: string[];
-};
-
-export function createMatrixRoomInfoResolver(client: MatrixClient) {
-  const roomInfoCache = new Map<string, MatrixRoomInfo>();
-
-  const getRoomInfo = async (roomId: string): Promise<MatrixRoomInfo> => {
-    const cached = roomInfoCache.get(roomId);
-    if (cached) {
-      return cached;
-    }
-    let name: string | undefined;
-    let canonicalAlias: string | undefined;
-    let altAliases: string[] = [];
-    try {
-      const nameState = await client.getRoomStateEvent(roomId, "m.room.name", "").catch(() => null);
-      name = nameState?.name;
-    } catch {
-      // ignore
-    }
-    try {
-      const aliasState = await client
-        .getRoomStateEvent(roomId, "m.room.canonical_alias", "")
-        .catch(() => null);
-      canonicalAlias = aliasState?.alias;
-      altAliases = aliasState?.alt_aliases ?? [];
-    } catch {
-      // ignore
-    }
-    const info = { name, canonicalAlias, altAliases };
-    roomInfoCache.set(roomId, info);
-    return info;
-  };
-
-  const getMemberDisplayName = async (roomId: string, userId: string): Promise<string> => {
-    try {
-      const memberState = await client
-        .getRoomStateEvent(roomId, "m.room.member", userId)
-        .catch(() => null);
-      return memberState?.displayname ?? userId;
-    } catch {
-      return userId;
-    }
-  };
-
-  return {
-    getRoomInfo,
-    getMemberDisplayName,
-  };
-}

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

@@ -1,124 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { resolveMatrixRoomConfig } from "./rooms.js";
-
-describe("resolveMatrixRoomConfig", () => {
-  it("matches room IDs and aliases, not names", () => {
-    const rooms = {
-      "!room:example.org": { allow: true },
-      "#alias:example.org": { allow: true },
-      "Project Room": { allow: true },
-    };
-
-    const byId = resolveMatrixRoomConfig({
-      rooms,
-      roomId: "!room:example.org",
-      aliases: [],
-      name: "Project Room",
-    });
-    expect(byId.allowed).toBe(true);
-    expect(byId.matchKey).toBe("!room:example.org");
-
-    const byAlias = resolveMatrixRoomConfig({
-      rooms,
-      roomId: "!other:example.org",
-      aliases: ["#alias:example.org"],
-      name: "Other Room",
-    });
-    expect(byAlias.allowed).toBe(true);
-    expect(byAlias.matchKey).toBe("#alias:example.org");
-
-    const byName = resolveMatrixRoomConfig({
-      rooms: { "Project Room": { allow: true } },
-      roomId: "!different:example.org",
-      aliases: [],
-      name: "Project Room",
-    });
-    expect(byName.allowed).toBe(false);
-    expect(byName.config).toBeUndefined();
-  });
-
-  describe("matchSource classification", () => {
-    it('returns matchSource="direct" for exact room ID match', () => {
-      const result = resolveMatrixRoomConfig({
-        rooms: { "!room:example.org": { allow: true } },
-        roomId: "!room:example.org",
-        aliases: [],
-      });
-      expect(result.matchSource).toBe("direct");
-      expect(result.config).toBeDefined();
-    });
-
-    it('returns matchSource="direct" for alias match', () => {
-      const result = resolveMatrixRoomConfig({
-        rooms: { "#alias:example.org": { allow: true } },
-        roomId: "!room:example.org",
-        aliases: ["#alias:example.org"],
-      });
-      expect(result.matchSource).toBe("direct");
-      expect(result.config).toBeDefined();
-    });
-
-    it('returns matchSource="wildcard" for wildcard match', () => {
-      const result = resolveMatrixRoomConfig({
-        rooms: { "*": { allow: true } },
-        roomId: "!any:example.org",
-        aliases: [],
-      });
-      expect(result.matchSource).toBe("wildcard");
-      expect(result.config).toBeDefined();
-    });
-
-    it("returns undefined matchSource when no match", () => {
-      const result = resolveMatrixRoomConfig({
-        rooms: { "!other:example.org": { allow: true } },
-        roomId: "!room:example.org",
-        aliases: [],
-      });
-      expect(result.matchSource).toBeUndefined();
-      expect(result.config).toBeUndefined();
-    });
-
-    it("direct match takes priority over wildcard", () => {
-      const result = resolveMatrixRoomConfig({
-        rooms: {
-          "!room:example.org": { allow: true, systemPrompt: "room-specific" },
-          "*": { allow: true, systemPrompt: "generic" },
-        },
-        roomId: "!room:example.org",
-        aliases: [],
-      });
-      expect(result.matchSource).toBe("direct");
-      expect(result.config?.systemPrompt).toBe("room-specific");
-    });
-  });
-
-  describe("DM override safety (matchSource distinction)", () => {
-    // These tests verify the matchSource property that handler.ts uses
-    // to decide whether a configured room should override DM classification.
-    // Only "direct" matches should trigger the override -- never "wildcard".
-
-    it("wildcard config should NOT be usable to override DM classification", () => {
-      const result = resolveMatrixRoomConfig({
-        rooms: { "*": { allow: true, skills: ["general"] } },
-        roomId: "!dm-room:example.org",
-        aliases: [],
-      });
-      // handler.ts checks: matchSource === "direct" -> this is "wildcard", so no override
-      expect(result.matchSource).not.toBe("direct");
-      expect(result.matchSource).toBe("wildcard");
-    });
-
-    it("explicitly configured room should be usable to override DM classification", () => {
-      const result = resolveMatrixRoomConfig({
-        rooms: {
-          "!configured-room:example.org": { allow: true },
-          "*": { allow: true },
-        },
-        roomId: "!configured-room:example.org",
-        aliases: [],
-      });
-      // handler.ts checks: matchSource === "direct" -> this IS "direct", so override is safe
-      expect(result.matchSource).toBe("direct");
-    });
-  });
-});

package/src/matrix/monitor/rooms.ts

@@ -1,47 +0,0 @@
-import { buildChannelKeyCandidates, resolveChannelEntryMatch } from "openclaw/plugin-sdk/matrix";
-import type { MatrixRoomConfig } from "../../types.js";
-
-export type MatrixRoomConfigResolved = {
-  allowed: boolean;
-  allowlistConfigured: boolean;
-  config?: MatrixRoomConfig;
-  matchKey?: string;
-  matchSource?: "direct" | "wildcard";
-};
-
-export function resolveMatrixRoomConfig(params: {
-  rooms?: Record<string, MatrixRoomConfig>;
-  roomId: string;
-  aliases: string[];
-  name?: string | null;
-}): MatrixRoomConfigResolved {
-  const rooms = params.rooms ?? {};
-  const keys = Object.keys(rooms);
-  const allowlistConfigured = keys.length > 0;
-  const candidates = buildChannelKeyCandidates(
-    params.roomId,
-    `room:${params.roomId}`,
-    ...params.aliases,
-  );
-  const {
-    entry: matched,
-    key: matchedKey,
-    wildcardEntry,
-    wildcardKey,
-  } = resolveChannelEntryMatch({
-    entries: rooms,
-    keys: candidates,
-    wildcardKey: "*",
-  });
-  const resolved = matched ?? wildcardEntry;
-  const allowed = resolved ? resolved.enabled !== false && resolved.allow !== false : false;
-  const matchKey = matchedKey ?? wildcardKey;
-  const matchSource = matched ? "direct" : wildcardEntry ? "wildcard" : undefined;
-  return {
-    allowed,
-    allowlistConfigured,
-    config: resolved,
-    matchKey,
-    matchSource,
-  };
-}

package/src/matrix/monitor/threads.ts

@@ -1,68 +0,0 @@
-// Type for raw Matrix event from @vector-im/matrix-bot-sdk
-type MatrixRawEvent = {
-  event_id: string;
-  sender: string;
-  type: string;
-  origin_server_ts: number;
-  content: Record<string, unknown>;
-};
-
-type RoomMessageEventContent = {
-  msgtype: string;
-  body: string;
-  "m.relates_to"?: {
-    rel_type?: string;
-    event_id?: string;
-    "m.in_reply_to"?: { event_id?: string };
-  };
-};
-
-const RelationType = {
-  Thread: "m.thread",
-} as const;
-
-export function resolveMatrixThreadTarget(params: {
-  threadReplies: "off" | "inbound" | "always";
-  messageId: string;
-  threadRootId?: string;
-  isThreadRoot?: boolean;
-}): string | undefined {
-  const { threadReplies, messageId, threadRootId } = params;
-  if (threadReplies === "off") {
-    return undefined;
-  }
-  const isThreadRoot = params.isThreadRoot === true;
-  const hasInboundThread = Boolean(threadRootId && threadRootId !== messageId && !isThreadRoot);
-  if (threadReplies === "inbound") {
-    return hasInboundThread ? threadRootId : undefined;
-  }
-  if (threadReplies === "always") {
-    return threadRootId ?? messageId;
-  }
-  return undefined;
-}
-
-export function resolveMatrixThreadRootId(params: {
-  event: MatrixRawEvent;
-  content: RoomMessageEventContent;
-}): string | undefined {
-  const relates = params.content["m.relates_to"];
-  if (!relates || typeof relates !== "object") {
-    return undefined;
-  }
-  if ("rel_type" in relates && relates.rel_type === RelationType.Thread) {
-    if ("event_id" in relates && typeof relates.event_id === "string") {
-      return relates.event_id;
-    }
-    if (
-      "m.in_reply_to" in relates &&
-      typeof relates["m.in_reply_to"] === "object" &&
-      relates["m.in_reply_to"] &&
-      "event_id" in relates["m.in_reply_to"] &&
-      typeof relates["m.in_reply_to"].event_id === "string"
-    ) {
-      return relates["m.in_reply_to"].event_id;
-    }
-  }
-  return undefined;
-}

package/src/matrix/monitor/types.ts

@@ -1,39 +0,0 @@
-import type { EncryptedFile, MessageEventContent } from "@vector-im/matrix-bot-sdk";
-
-export const EventType = {
-  RoomMessage: "m.room.message",
-  RoomMessageEncrypted: "m.room.encrypted",
-  RoomMember: "m.room.member",
-  Location: "m.location",
-} as const;
-
-export const RelationType = {
-  Replace: "m.replace",
-  Thread: "m.thread",
-} as const;
-
-export type MatrixRawEvent = {
-  event_id: string;
-  sender: string;
-  type: string;
-  origin_server_ts: number;
-  content: Record<string, unknown>;
-  unsigned?: {
-    age?: number;
-    redacted_because?: unknown;
-  };
-};
-
-export type RoomMessageEventContent = MessageEventContent & {
-  url?: string;
-  file?: EncryptedFile;
-  info?: {
-    mimetype?: string;
-    size?: number;
-  };
-  "m.relates_to"?: {
-    rel_type?: string;
-    event_id?: string;
-    "m.in_reply_to"?: { event_id?: string };
-  };
-};

package/src/matrix/poll-types.test.ts

@@ -1,21 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { parsePollStartContent } from "./poll-types.js";
-
-describe("parsePollStartContent", () => {
-  it("parses legacy m.poll payloads", () => {
-    const summary = parsePollStartContent({
-      "m.poll": {
-        question: { "m.text": "Lunch?" },
-        kind: "m.poll.disclosed",
-        max_selections: 1,
-        answers: [
-          { id: "answer1", "m.text": "Yes" },
-          { id: "answer2", "m.text": "No" },
-        ],
-      },
-    });
-
-    expect(summary?.question).toBe("Lunch?");
-    expect(summary?.answers).toEqual(["Yes", "No"]);
-  });
-});

package/src/matrix/poll-types.ts

@@ -1,167 +0,0 @@
-/**
- * Matrix Poll Types (MSC3381)
- *
- * Defines types for Matrix poll events:
- * - m.poll.start - Creates a new poll
- * - m.poll.response - Records a vote
- * - m.poll.end - Closes a poll
- */
-
-import type { PollInput } from "openclaw/plugin-sdk/matrix";
-
-export const M_POLL_START = "m.poll.start" as const;
-export const M_POLL_RESPONSE = "m.poll.response" as const;
-export const M_POLL_END = "m.poll.end" as const;
-
-export const ORG_POLL_START = "org.matrix.msc3381.poll.start" as const;
-export const ORG_POLL_RESPONSE = "org.matrix.msc3381.poll.response" as const;
-export const ORG_POLL_END = "org.matrix.msc3381.poll.end" as const;
-
-export const POLL_EVENT_TYPES = [
-  M_POLL_START,
-  M_POLL_RESPONSE,
-  M_POLL_END,
-  ORG_POLL_START,
-  ORG_POLL_RESPONSE,
-  ORG_POLL_END,
-];
-
-export const POLL_START_TYPES = [M_POLL_START, ORG_POLL_START];
-export const POLL_RESPONSE_TYPES = [M_POLL_RESPONSE, ORG_POLL_RESPONSE];
-export const POLL_END_TYPES = [M_POLL_END, ORG_POLL_END];
-
-export type PollKind = "m.poll.disclosed" | "m.poll.undisclosed";
-
-export type TextContent = {
-  "m.text"?: string;
-  "org.matrix.msc1767.text"?: string;
-  body?: string;
-};
-
-export type PollAnswer = {
-  id: string;
-} & TextContent;
-
-export type PollStartSubtype = {
-  question: TextContent;
-  kind?: PollKind;
-  max_selections?: number;
-  answers: PollAnswer[];
-};
-
-export type LegacyPollStartContent = {
-  "m.poll"?: PollStartSubtype;
-};
-
-export type PollStartContent = {
-  [M_POLL_START]?: PollStartSubtype;
-  [ORG_POLL_START]?: PollStartSubtype;
-  "m.poll"?: PollStartSubtype;
-  "m.text"?: string;
-  "org.matrix.msc1767.text"?: string;
-};
-
-export type PollSummary = {
-  eventId: string;
-  roomId: string;
-  sender: string;
-  senderName: string;
-  question: string;
-  answers: string[];
-  kind: PollKind;
-  maxSelections: number;
-};
-
-export function isPollStartType(eventType: string): boolean {
-  return (POLL_START_TYPES as readonly string[]).includes(eventType);
-}
-
-export function getTextContent(text?: TextContent): string {
-  if (!text) {
-    return "";
-  }
-  return text["m.text"] ?? text["org.matrix.msc1767.text"] ?? text.body ?? "";
-}
-
-export function parsePollStartContent(content: PollStartContent): PollSummary | null {
-  const poll =
-    (content as Record<string, PollStartSubtype | undefined>)[M_POLL_START] ??
-    (content as Record<string, PollStartSubtype | undefined>)[ORG_POLL_START] ??
-    (content as Record<string, PollStartSubtype | undefined>)["m.poll"];
-  if (!poll) {
-    return null;
-  }
-
-  const question = getTextContent(poll.question);
-  if (!question) {
-    return null;
-  }
-
-  const answers = poll.answers
-    .map((answer) => getTextContent(answer))
-    .filter((a) => a.trim().length > 0);
-
-  return {
-    eventId: "",
-    roomId: "",
-    sender: "",
-    senderName: "",
-    question,
-    answers,
-    kind: poll.kind ?? "m.poll.disclosed",
-    maxSelections: poll.max_selections ?? 1,
-  };
-}
-
-export function formatPollAsText(summary: PollSummary): string {
-  const lines = [
-    "[Poll]",
-    summary.question,
-    "",
-    ...summary.answers.map((answer, idx) => `${idx + 1}. ${answer}`),
-  ];
-  return lines.join("\n");
-}
-
-function buildTextContent(body: string): TextContent {
-  return {
-    "m.text": body,
-    "org.matrix.msc1767.text": body,
-  };
-}
-
-function buildPollFallbackText(question: string, answers: string[]): string {
-  if (answers.length === 0) {
-    return question;
-  }
-  return `${question}\n${answers.map((answer, idx) => `${idx + 1}. ${answer}`).join("\n")}`;
-}
-
-export function buildPollStartContent(poll: PollInput): PollStartContent {
-  const question = poll.question.trim();
-  const answers = poll.options
-    .map((option) => option.trim())
-    .filter((option) => option.length > 0)
-    .map((option, idx) => ({
-      id: `answer${idx + 1}`,
-      ...buildTextContent(option),
-    }));
-
-  const isMultiple = (poll.maxSelections ?? 1) > 1;
-  const maxSelections = isMultiple ? Math.max(1, answers.length) : 1;
-  const fallbackText = buildPollFallbackText(
-    question,
-    answers.map((answer) => getTextContent(answer)),
-  );
-
-  return {
-    [M_POLL_START]: {
-      question: buildTextContent(question),
-      kind: isMultiple ? "m.poll.undisclosed" : "m.poll.disclosed",
-      max_selections: maxSelections,
-      answers,
-    },
-    "m.text": fallbackText,
-    "org.matrix.msc1767.text": fallbackText,
-  };
-}