@openclaw/matrix 2026.3.13 → 2026.5.10-beta.1

package/src/resolve-targets.test.ts

@@ -1,68 +0,0 @@
-import type { ChannelDirectoryEntry } from "openclaw/plugin-sdk/matrix";
-import { describe, expect, it, vi, beforeEach } from "vitest";
-import { listMatrixDirectoryGroupsLive, listMatrixDirectoryPeersLive } from "./directory-live.js";
-import { resolveMatrixTargets } from "./resolve-targets.js";
-
-vi.mock("./directory-live.js", () => ({
-  listMatrixDirectoryPeersLive: vi.fn(),
-  listMatrixDirectoryGroupsLive: vi.fn(),
-}));
-
-async function resolveUserTarget(input = "Alice") {
-  const [result] = await resolveMatrixTargets({
-    cfg: {},
-    inputs: [input],
-    kind: "user",
-  });
-  return result;
-}
-
-describe("resolveMatrixTargets (users)", () => {
-  beforeEach(() => {
-    vi.mocked(listMatrixDirectoryPeersLive).mockReset();
-    vi.mocked(listMatrixDirectoryGroupsLive).mockReset();
-  });
-
-  it("resolves exact unique display name matches", async () => {
-    const matches: ChannelDirectoryEntry[] = [
-      { kind: "user", id: "@alice:example.org", name: "Alice" },
-    ];
-    vi.mocked(listMatrixDirectoryPeersLive).mockResolvedValue(matches);
-
-    const result = await resolveUserTarget();
-
-    expect(result?.resolved).toBe(true);
-    expect(result?.id).toBe("@alice:example.org");
-  });
-
-  it("does not resolve ambiguous or non-exact matches", async () => {
-    const matches: ChannelDirectoryEntry[] = [
-      { kind: "user", id: "@alice:example.org", name: "Alice" },
-      { kind: "user", id: "@alice:evil.example", name: "Alice" },
-    ];
-    vi.mocked(listMatrixDirectoryPeersLive).mockResolvedValue(matches);
-
-    const result = await resolveUserTarget();
-
-    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

@@ -1,125 +0,0 @@
-import { mapAllowlistResolutionInputs } from "openclaw/plugin-sdk/compat";
-import type {
-  ChannelDirectoryEntry,
-  ChannelResolveKind,
-  ChannelResolveResult,
-  RuntimeEnv,
-} from "openclaw/plugin-sdk/matrix";
-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,
-): ChannelDirectoryEntry | undefined {
-  if (matches.length === 0) {
-    return undefined;
-  }
-  const [exact] = findExactDirectoryMatches(matches, query);
-  return exact ?? matches[0];
-}
-
-function pickBestUserMatch(
-  matches: ChannelDirectoryEntry[],
-  query: string,
-): ChannelDirectoryEntry | undefined {
-  if (matches.length === 0) {
-    return undefined;
-  }
-  const exact = findExactDirectoryMatches(matches, query);
-  if (exact.length === 1) {
-    return exact[0];
-  }
-  return undefined;
-}
-
-function describeUserMatchFailure(matches: ChannelDirectoryEntry[], query: string): string {
-  if (matches.length === 0) {
-    return "no matches";
-  }
-  const normalized = query.trim().toLowerCase();
-  if (!normalized) {
-    return "empty input";
-  }
-  const exact = findExactDirectoryMatches(matches, normalized);
-  if (exact.length === 0) {
-    return "no exact match; use full Matrix ID";
-  }
-  if (exact.length > 1) {
-    return "multiple exact matches; use full Matrix ID";
-  }
-  return "no exact match; use full Matrix ID";
-}
-
-export async function resolveMatrixTargets(params: {
-  cfg: unknown;
-  inputs: string[];
-  kind: ChannelResolveKind;
-  runtime?: RuntimeEnv;
-}): Promise<ChannelResolveResult[]> {
-  return await mapAllowlistResolutionInputs({
-    inputs: params.inputs,
-    mapInput: async (input): Promise<ChannelResolveResult> => {
-      const trimmed = input.trim();
-      if (!trimmed) {
-        return { input, resolved: false, note: "empty input" };
-      }
-      if (params.kind === "user") {
-        if (trimmed.startsWith("@") && trimmed.includes(":")) {
-          return { input, resolved: true, id: trimmed };
-        }
-        try {
-          const matches = await listMatrixDirectoryPeersLive({
-            cfg: params.cfg,
-            query: trimmed,
-            limit: 5,
-          });
-          const best = pickBestUserMatch(matches, trimmed);
-          return {
-            input,
-            resolved: Boolean(best?.id),
-            id: best?.id,
-            name: best?.name,
-            note: best ? undefined : describeUserMatchFailure(matches, trimmed),
-          };
-        } catch (err) {
-          params.runtime?.error?.(`matrix resolve failed: ${String(err)}`);
-          return { input, resolved: false, note: "lookup failed" };
-        }
-      }
-      try {
-        const matches = await listMatrixDirectoryGroupsLive({
-          cfg: params.cfg,
-          query: trimmed,
-          limit: 5,
-        });
-        const best = pickBestGroupMatch(matches, trimmed);
-        return {
-          input,
-          resolved: Boolean(best?.id),
-          id: best?.id,
-          name: best?.name,
-          note: matches.length > 1 ? "multiple matches; chose first" : undefined,
-        };
-      } catch (err) {
-        params.runtime?.error?.(`matrix resolve failed: ${String(err)}`);
-        return { input, resolved: false, note: "lookup failed" };
-      }
-    },
-  });
-}

package/src/runtime.ts

@@ -1,6 +0,0 @@
-import { createPluginRuntimeStore } from "openclaw/plugin-sdk/compat";
-import type { PluginRuntime } from "openclaw/plugin-sdk/matrix";
-
-const { setRuntime: setMatrixRuntime, getRuntime: getMatrixRuntime } =
-  createPluginRuntimeStore<PluginRuntime>("Matrix runtime not initialized");
-export { getMatrixRuntime, setMatrixRuntime };

package/src/secret-input.ts

@@ -1,13 +0,0 @@
-import {
-  buildSecretInputSchema,
-  hasConfiguredSecretInput,
-  normalizeResolvedSecretInputString,
-  normalizeSecretInputString,
-} from "openclaw/plugin-sdk/matrix";
-
-export {
-  buildSecretInputSchema,
-  hasConfiguredSecretInput,
-  normalizeResolvedSecretInputString,
-  normalizeSecretInputString,
-};

package/src/test-mocks.ts

@@ -1,53 +0,0 @@
-import type { Mock } from "vitest";
-import { vi } from "vitest";
-
-type MatrixBotSdkMockParams = {
-  matrixClient?: unknown;
-  simpleFsStorageProvider?: unknown;
-  rustSdkCryptoStorageProvider?: unknown;
-  includeVerboseLogService?: boolean;
-};
-
-type MatrixBotSdkMock = {
-  ConsoleLogger: new () => {
-    trace: Mock<() => void>;
-    debug: Mock<() => void>;
-    info: Mock<() => void>;
-    warn: Mock<() => void>;
-    error: Mock<() => void>;
-  };
-  MatrixClient: unknown;
-  LogService: {
-    setLogger: Mock<() => void>;
-    warn?: Mock<() => void>;
-    info?: Mock<() => void>;
-    debug?: Mock<() => void>;
-  };
-  SimpleFsStorageProvider: unknown;
-  RustSdkCryptoStorageProvider: unknown;
-};
-
-export function createMatrixBotSdkMock(params: MatrixBotSdkMockParams = {}): MatrixBotSdkMock {
-  return {
-    ConsoleLogger: class {
-      trace = vi.fn();
-      debug = vi.fn();
-      info = vi.fn();
-      warn = vi.fn();
-      error = vi.fn();
-    },
-    MatrixClient: params.matrixClient ?? class {},
-    LogService: {
-      setLogger: vi.fn(),
-      ...(params.includeVerboseLogService
-        ? {
-            warn: vi.fn(),
-            info: vi.fn(),
-            debug: vi.fn(),
-          }
-        : {}),
-    },
-    SimpleFsStorageProvider: params.simpleFsStorageProvider ?? class {},
-    RustSdkCryptoStorageProvider: params.rustSdkCryptoStorageProvider ?? class {},
-  };
-}

package/src/tool-actions.ts

@@ -1,164 +0,0 @@
-import type { AgentToolResult } from "@mariozechner/pi-agent-core";
-import {
-  createActionGate,
-  jsonResult,
-  readNumberParam,
-  readReactionParams,
-  readStringParam,
-} from "openclaw/plugin-sdk/matrix";
-import {
-  deleteMatrixMessage,
-  editMatrixMessage,
-  getMatrixMemberInfo,
-  getMatrixRoomInfo,
-  listMatrixPins,
-  listMatrixReactions,
-  pinMatrixMessage,
-  readMatrixMessages,
-  removeMatrixReactions,
-  sendMatrixMessage,
-  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"]);
-const pinActions = new Set(["pinMessage", "unpinMessage", "listPins"]);
-
-function readRoomId(params: Record<string, unknown>, required = true): string {
-  const direct = readStringParam(params, "roomId") ?? readStringParam(params, "channelId");
-  if (direct) {
-    return direct;
-  }
-  if (!required) {
-    return readStringParam(params, "to") ?? "";
-  }
-  return readStringParam(params, "to", { required: true });
-}
-
-export async function handleMatrixAction(
-  params: Record<string, unknown>,
-  cfg: CoreConfig,
-): Promise<AgentToolResult<unknown>> {
-  const action = readStringParam(params, "action", { required: true });
-  const isActionEnabled = createActionGate(cfg.channels?.matrix?.actions);
-
-  if (reactionActions.has(action)) {
-    if (!isActionEnabled("reactions")) {
-      throw new Error("Matrix reactions are disabled.");
-    }
-    const roomId = readRoomId(params);
-    const messageId = readStringParam(params, "messageId", { required: true });
-    if (action === "react") {
-      const { emoji, remove, isEmpty } = readReactionParams(params, {
-        removeErrorMessage: "Emoji is required to remove a Matrix reaction.",
-      });
-      if (remove || isEmpty) {
-        const result = await removeMatrixReactions(roomId, messageId, {
-          emoji: remove ? emoji : undefined,
-        });
-        return jsonResult({ ok: true, removed: result.removed });
-      }
-      await reactMatrixMessage(roomId, messageId, emoji);
-      return jsonResult({ ok: true, added: emoji });
-    }
-    const reactions = await listMatrixReactions(roomId, messageId);
-    return jsonResult({ ok: true, reactions });
-  }
-
-  if (messageActions.has(action)) {
-    if (!isActionEnabled("messages")) {
-      throw new Error("Matrix messages are disabled.");
-    }
-    switch (action) {
-      case "sendMessage": {
-        const to = readStringParam(params, "to", { required: true });
-        const content = readStringParam(params, "content", {
-          required: true,
-          allowEmpty: true,
-        });
-        const mediaUrl = readStringParam(params, "mediaUrl");
-        const replyToId =
-          readStringParam(params, "replyToId") ?? readStringParam(params, "replyTo");
-        const threadId = readStringParam(params, "threadId");
-        const result = await sendMatrixMessage(to, content, {
-          mediaUrl: mediaUrl ?? undefined,
-          replyToId: replyToId ?? undefined,
-          threadId: threadId ?? undefined,
-        });
-        return jsonResult({ ok: true, result });
-      }
-      case "editMessage": {
-        const roomId = readRoomId(params);
-        const messageId = readStringParam(params, "messageId", { required: true });
-        const content = readStringParam(params, "content", { required: true });
-        const result = await editMatrixMessage(roomId, messageId, content);
-        return jsonResult({ ok: true, result });
-      }
-      case "deleteMessage": {
-        const roomId = readRoomId(params);
-        const messageId = readStringParam(params, "messageId", { required: true });
-        const reason = readStringParam(params, "reason");
-        await deleteMatrixMessage(roomId, messageId, { reason: reason ?? undefined });
-        return jsonResult({ ok: true, deleted: true });
-      }
-      case "readMessages": {
-        const roomId = readRoomId(params);
-        const limit = readNumberParam(params, "limit", { integer: true });
-        const before = readStringParam(params, "before");
-        const after = readStringParam(params, "after");
-        const result = await readMatrixMessages(roomId, {
-          limit: limit ?? undefined,
-          before: before ?? undefined,
-          after: after ?? undefined,
-        });
-        return jsonResult({ ok: true, ...result });
-      }
-      default:
-        break;
-    }
-  }
-
-  if (pinActions.has(action)) {
-    if (!isActionEnabled("pins")) {
-      throw new Error("Matrix pins are disabled.");
-    }
-    const roomId = readRoomId(params);
-    if (action === "pinMessage") {
-      const messageId = readStringParam(params, "messageId", { required: true });
-      const result = await pinMatrixMessage(roomId, messageId);
-      return jsonResult({ ok: true, pinned: result.pinned });
-    }
-    if (action === "unpinMessage") {
-      const messageId = readStringParam(params, "messageId", { required: true });
-      const result = await unpinMatrixMessage(roomId, messageId);
-      return jsonResult({ ok: true, pinned: result.pinned });
-    }
-    const result = await listMatrixPins(roomId);
-    return jsonResult({ ok: true, pinned: result.pinned, events: result.events });
-  }
-
-  if (action === "memberInfo") {
-    if (!isActionEnabled("memberInfo")) {
-      throw new Error("Matrix member info is disabled.");
-    }
-    const userId = readStringParam(params, "userId", { required: true });
-    const roomId = readStringParam(params, "roomId") ?? readStringParam(params, "channelId");
-    const result = await getMatrixMemberInfo(userId, {
-      roomId: roomId ?? undefined,
-    });
-    return jsonResult({ ok: true, member: result });
-  }
-
-  if (action === "channelInfo") {
-    if (!isActionEnabled("channelInfo")) {
-      throw new Error("Matrix room info is disabled.");
-    }
-    const roomId = readRoomId(params);
-    const result = await getMatrixRoomInfo(roomId);
-    return jsonResult({ ok: true, room: result });
-  }
-
-  throw new Error(`Unsupported Matrix action: ${action}`);
-}

package/src/types.ts

@@ -1,118 +0,0 @@
-import type { DmPolicy, GroupPolicy, SecretInput } from "openclaw/plugin-sdk/matrix";
-export type { DmPolicy, GroupPolicy };
-
-export type ReplyToMode = "off" | "first" | "all";
-
-export type MatrixDmConfig = {
-  /** If false, ignore all incoming Matrix DMs. Default: true. */
-  enabled?: boolean;
-  /** Direct message access policy (default: pairing). */
-  policy?: DmPolicy;
-  /** Allowlist for DM senders (matrix user IDs or "*"). */
-  allowFrom?: Array<string | number>;
-};
-
-export type MatrixRoomConfig = {
-  /** If false, disable the bot in this room (alias for allow: false). */
-  enabled?: boolean;
-  /** Legacy room allow toggle; prefer enabled. */
-  allow?: boolean;
-  /** Require mentioning the bot to trigger replies. */
-  requireMention?: boolean;
-  /** Optional tool policy overrides for this room. */
-  tools?: { allow?: string[]; deny?: string[] };
-  /** If true, reply without mention requirements. */
-  autoReply?: boolean;
-  /** Optional allowlist for room senders (matrix user IDs). */
-  users?: Array<string | number>;
-  /** Optional skill filter for this room. */
-  skills?: string[];
-  /** Optional system prompt snippet for this room. */
-  systemPrompt?: string;
-};
-
-export type MatrixActionConfig = {
-  reactions?: boolean;
-  messages?: boolean;
-  pins?: boolean;
-  memberInfo?: boolean;
-  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>;
-  /** Optional default account id when multiple accounts are configured. */
-  defaultAccount?: string;
-  /** Matrix homeserver URL (https://matrix.example.org). */
-  homeserver?: string;
-  /** Matrix user id (@user:server). */
-  userId?: string;
-  /** Matrix access token. */
-  accessToken?: string;
-  /** Matrix password (used only to fetch access token). */
-  password?: SecretInput;
-  /** Optional device name when logging in via password. */
-  deviceName?: string;
-  /** Initial sync limit for startup (default: @vector-im/matrix-bot-sdk default). */
-  initialSyncLimit?: number;
-  /** Enable end-to-end encryption (E2EE). Default: false. */
-  encryption?: boolean;
-  /** If true, enforce allowlists for groups + DMs regardless of policy. */
-  allowlistOnly?: boolean;
-  /** Group message policy (default: allowlist). */
-  groupPolicy?: GroupPolicy;
-  /** Allowlist for group senders (matrix user IDs). */
-  groupAllowFrom?: Array<string | number>;
-  /** Control reply threading when reply tags are present (off|first|all). */
-  replyToMode?: ReplyToMode;
-  /** How to handle thread replies (off|inbound|always). */
-  threadReplies?: "off" | "inbound" | "always";
-  /** Outbound text chunk size (chars). Default: 4000. */
-  textChunkLimit?: number;
-  /** Chunking mode: "length" (default) splits by size; "newline" splits on every newline. */
-  chunkMode?: "length" | "newline";
-  /** Outbound response prefix override for this channel/account. */
-  responsePrefix?: string;
-  /** Max outbound media size in MB. */
-  mediaMaxMb?: number;
-  /** Auto-join invites (always|allowlist|off). Default: always. */
-  autoJoin?: "always" | "allowlist" | "off";
-  /** Allowlist for auto-join invites (room IDs, aliases). */
-  autoJoinAllowlist?: Array<string | number>;
-  /** Direct message policy + allowlist overrides. */
-  dm?: MatrixDmConfig;
-  /** Room config allowlist keyed by room ID or alias (names resolved to IDs when possible). */
-  groups?: Record<string, MatrixRoomConfig>;
-  /** Room config allowlist keyed by room ID or alias. Legacy; use groups. */
-  rooms?: Record<string, MatrixRoomConfig>;
-  /** Per-action tool gating (default: true for all). */
-  actions?: MatrixActionConfig;
-};
-
-export type CoreConfig = {
-  channels?: {
-    matrix?: MatrixConfig;
-    defaults?: {
-      groupPolicy?: "open" | "allowlist" | "disabled";
-    };
-  };
-  commands?: {
-    useAccessGroups?: boolean;
-  };
-  session?: {
-    store?: string;
-  };
-  messages?: {
-    ackReaction?: string;
-    ackReactionScope?: "group-mentions" | "group-all" | "direct" | "all" | "off" | "none";
-  };
-  [key: string]: unknown;
-};