@openclaw/matrix 2026.3.12 → 2026.5.9-beta.1

package/src/channel.ts

@@ -1,461 +0,0 @@
-import {
-  buildOpenGroupPolicyWarning,
-  collectAllowlistProviderGroupPolicyWarnings,
-  createScopedAccountConfigAccessors,
-  createScopedChannelConfigBase,
-  createScopedDmSecurityResolver,
-} from "openclaw/plugin-sdk/compat";
-import {
-  applyAccountNameToChannelSection,
-  buildChannelConfigSchema,
-  buildProbeChannelStatusSummary,
-  collectStatusIssuesFromLastError,
-  DEFAULT_ACCOUNT_ID,
-  normalizeAccountId,
-  PAIRING_APPROVED_MESSAGE,
-  type ChannelPlugin,
-} from "openclaw/plugin-sdk/matrix";
-import { matrixMessageActions } from "./actions.js";
-import { MatrixConfigSchema } from "./config-schema.js";
-import { listMatrixDirectoryGroupsLive, listMatrixDirectoryPeersLive } from "./directory-live.js";
-import {
-  resolveMatrixGroupRequireMention,
-  resolveMatrixGroupToolPolicy,
-} from "./group-mentions.js";
-import {
-  listMatrixAccountIds,
-  resolveMatrixAccountConfig,
-  resolveDefaultMatrixAccountId,
-  resolveMatrixAccount,
-  type ResolvedMatrixAccount,
-} from "./matrix/accounts.js";
-import { resolveMatrixAuth } from "./matrix/client.js";
-import { normalizeMatrixAllowList, normalizeMatrixUserId } from "./matrix/monitor/allowlist.js";
-import { probeMatrix } from "./matrix/probe.js";
-import { sendMessageMatrix } from "./matrix/send.js";
-import { matrixOnboardingAdapter } from "./onboarding.js";
-import { matrixOutbound } from "./outbound.js";
-import { resolveMatrixTargets } from "./resolve-targets.js";
-import { normalizeSecretInputString } from "./secret-input.js";
-import type { CoreConfig } from "./types.js";
-
-// Mutex for serializing account startup (workaround for concurrent dynamic import race condition)
-let matrixStartupLock: Promise<void> = Promise.resolve();
-
-const meta = {
-  id: "matrix",
-  label: "Matrix",
-  selectionLabel: "Matrix (plugin)",
-  docsPath: "/channels/matrix",
-  docsLabel: "matrix",
-  blurb: "open protocol; configure a homeserver + access token.",
-  order: 70,
-  quickstartAllowFrom: true,
-};
-
-function normalizeMatrixMessagingTarget(raw: string): string | undefined {
-  let normalized = raw.trim();
-  if (!normalized) {
-    return undefined;
-  }
-  const lowered = normalized.toLowerCase();
-  if (lowered.startsWith("matrix:")) {
-    normalized = normalized.slice("matrix:".length).trim();
-  }
-  const stripped = normalized.replace(/^(room|channel|user):/i, "").trim();
-  return stripped || undefined;
-}
-
-function buildMatrixConfigUpdate(
-  cfg: CoreConfig,
-  input: {
-    homeserver?: string;
-    userId?: string;
-    accessToken?: string;
-    password?: string;
-    deviceName?: string;
-    initialSyncLimit?: number;
-  },
-): CoreConfig {
-  const existing = cfg.channels?.matrix ?? {};
-  return {
-    ...cfg,
-    channels: {
-      ...cfg.channels,
-      matrix: {
-        ...existing,
-        enabled: true,
-        ...(input.homeserver ? { homeserver: input.homeserver } : {}),
-        ...(input.userId ? { userId: input.userId } : {}),
-        ...(input.accessToken ? { accessToken: input.accessToken } : {}),
-        ...(input.password ? { password: input.password } : {}),
-        ...(input.deviceName ? { deviceName: input.deviceName } : {}),
-        ...(typeof input.initialSyncLimit === "number"
-          ? { initialSyncLimit: input.initialSyncLimit }
-          : {}),
-      },
-    },
-  };
-}
-
-const matrixConfigAccessors = createScopedAccountConfigAccessors({
-  resolveAccount: ({ cfg, accountId }) =>
-    resolveMatrixAccountConfig({ cfg: cfg as CoreConfig, accountId }),
-  resolveAllowFrom: (account) => account.dm?.allowFrom,
-  formatAllowFrom: (allowFrom) => normalizeMatrixAllowList(allowFrom),
-});
-
-const matrixConfigBase = createScopedChannelConfigBase<ResolvedMatrixAccount, CoreConfig>({
-  sectionKey: "matrix",
-  listAccountIds: listMatrixAccountIds,
-  resolveAccount: (cfg, accountId) => resolveMatrixAccount({ cfg, accountId }),
-  defaultAccountId: resolveDefaultMatrixAccountId,
-  clearBaseFields: [
-    "name",
-    "homeserver",
-    "userId",
-    "accessToken",
-    "password",
-    "deviceName",
-    "initialSyncLimit",
-  ],
-});
-
-const resolveMatrixDmPolicy = createScopedDmSecurityResolver<ResolvedMatrixAccount>({
-  channelKey: "matrix",
-  resolvePolicy: (account) => account.config.dm?.policy,
-  resolveAllowFrom: (account) => account.config.dm?.allowFrom,
-  allowFromPathSuffix: "dm.",
-  normalizeEntry: (raw) => normalizeMatrixUserId(raw),
-});
-
-export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
-  id: "matrix",
-  meta,
-  onboarding: matrixOnboardingAdapter,
-  pairing: {
-    idLabel: "matrixUserId",
-    normalizeAllowEntry: (entry) => entry.replace(/^matrix:/i, ""),
-    notifyApproval: async ({ id }) => {
-      await sendMessageMatrix(`user:${id}`, PAIRING_APPROVED_MESSAGE);
-    },
-  },
-  capabilities: {
-    chatTypes: ["direct", "group", "thread"],
-    polls: true,
-    reactions: true,
-    threads: true,
-    media: true,
-  },
-  reload: { configPrefixes: ["channels.matrix"] },
-  configSchema: buildChannelConfigSchema(MatrixConfigSchema),
-  config: {
-    ...matrixConfigBase,
-    isConfigured: (account) => account.configured,
-    describeAccount: (account) => ({
-      accountId: account.accountId,
-      name: account.name,
-      enabled: account.enabled,
-      configured: account.configured,
-      baseUrl: account.homeserver,
-    }),
-    ...matrixConfigAccessors,
-  },
-  security: {
-    resolveDmPolicy: resolveMatrixDmPolicy,
-    collectWarnings: ({ account, cfg }) => {
-      return collectAllowlistProviderGroupPolicyWarnings({
-        cfg: cfg as CoreConfig,
-        providerConfigPresent: (cfg as CoreConfig).channels?.matrix !== undefined,
-        configuredGroupPolicy: account.config.groupPolicy,
-        collect: (groupPolicy) =>
-          groupPolicy === "open"
-            ? [
-                buildOpenGroupPolicyWarning({
-                  surface: "Matrix rooms",
-                  openBehavior: "allows any room to trigger (mention-gated)",
-                  remediation:
-                    'Set channels.matrix.groupPolicy="allowlist" + channels.matrix.groups (and optionally channels.matrix.groupAllowFrom) to restrict rooms',
-                }),
-              ]
-            : [],
-      });
-    },
-  },
-  groups: {
-    resolveRequireMention: resolveMatrixGroupRequireMention,
-    resolveToolPolicy: resolveMatrixGroupToolPolicy,
-  },
-  threading: {
-    resolveReplyToMode: ({ cfg, accountId }) =>
-      resolveMatrixAccountConfig({ cfg: cfg as CoreConfig, accountId }).replyToMode ?? "off",
-    buildToolContext: ({ context, hasRepliedRef }) => {
-      const currentTarget = context.To;
-      return {
-        currentChannelId: currentTarget?.trim() || undefined,
-        currentThreadTs:
-          context.MessageThreadId != null ? String(context.MessageThreadId) : context.ReplyToId,
-        hasRepliedRef,
-      };
-    },
-  },
-  messaging: {
-    normalizeTarget: normalizeMatrixMessagingTarget,
-    targetResolver: {
-      looksLikeId: (raw) => {
-        const trimmed = raw.trim();
-        if (!trimmed) {
-          return false;
-        }
-        if (/^(matrix:)?[!#@]/i.test(trimmed)) {
-          return true;
-        }
-        return trimmed.includes(":");
-      },
-      hint: "<room|alias|user>",
-    },
-  },
-  directory: {
-    self: async () => null,
-    listPeers: async ({ cfg, accountId, query, limit }) => {
-      const account = resolveMatrixAccount({ cfg: cfg as CoreConfig, accountId });
-      const q = query?.trim().toLowerCase() || "";
-      const ids = new Set<string>();
-
-      for (const entry of account.config.dm?.allowFrom ?? []) {
-        const raw = String(entry).trim();
-        if (!raw || raw === "*") {
-          continue;
-        }
-        ids.add(raw.replace(/^matrix:/i, ""));
-      }
-
-      for (const entry of account.config.groupAllowFrom ?? []) {
-        const raw = String(entry).trim();
-        if (!raw || raw === "*") {
-          continue;
-        }
-        ids.add(raw.replace(/^matrix:/i, ""));
-      }
-
-      const groups = account.config.groups ?? account.config.rooms ?? {};
-      for (const room of Object.values(groups)) {
-        for (const entry of room.users ?? []) {
-          const raw = String(entry).trim();
-          if (!raw || raw === "*") {
-            continue;
-          }
-          ids.add(raw.replace(/^matrix:/i, ""));
-        }
-      }
-
-      return Array.from(ids)
-        .map((raw) => raw.trim())
-        .filter(Boolean)
-        .map((raw) => {
-          const lowered = raw.toLowerCase();
-          const cleaned = lowered.startsWith("user:") ? raw.slice("user:".length).trim() : raw;
-          if (cleaned.startsWith("@")) {
-            return `user:${cleaned}`;
-          }
-          return cleaned;
-        })
-        .filter((id) => (q ? id.toLowerCase().includes(q) : true))
-        .slice(0, limit && limit > 0 ? limit : undefined)
-        .map((id) => {
-          const raw = id.startsWith("user:") ? id.slice("user:".length) : id;
-          const incomplete = !raw.startsWith("@") || !raw.includes(":");
-          return {
-            kind: "user",
-            id,
-            ...(incomplete ? { name: "incomplete id; expected @user:server" } : {}),
-          };
-        });
-    },
-    listGroups: async ({ cfg, accountId, query, limit }) => {
-      const account = resolveMatrixAccount({ cfg: cfg as CoreConfig, accountId });
-      const q = query?.trim().toLowerCase() || "";
-      const groups = account.config.groups ?? account.config.rooms ?? {};
-      const ids = Object.keys(groups)
-        .map((raw) => raw.trim())
-        .filter((raw) => Boolean(raw) && raw !== "*")
-        .map((raw) => raw.replace(/^matrix:/i, ""))
-        .map((raw) => {
-          const lowered = raw.toLowerCase();
-          if (lowered.startsWith("room:") || lowered.startsWith("channel:")) {
-            return raw;
-          }
-          if (raw.startsWith("!")) {
-            return `room:${raw}`;
-          }
-          return raw;
-        })
-        .filter((id) => (q ? id.toLowerCase().includes(q) : true))
-        .slice(0, limit && limit > 0 ? limit : undefined)
-        .map((id) => ({ kind: "group", id }) as const);
-      return ids;
-    },
-    listPeersLive: async ({ cfg, accountId, query, limit }) =>
-      listMatrixDirectoryPeersLive({ cfg, accountId, query, limit }),
-    listGroupsLive: async ({ cfg, accountId, query, limit }) =>
-      listMatrixDirectoryGroupsLive({ cfg, accountId, query, limit }),
-  },
-  resolver: {
-    resolveTargets: async ({ cfg, inputs, kind, runtime }) =>
-      resolveMatrixTargets({ cfg, inputs, kind, runtime }),
-  },
-  actions: matrixMessageActions,
-  setup: {
-    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
-    applyAccountName: ({ cfg, accountId, name }) =>
-      applyAccountNameToChannelSection({
-        cfg: cfg as CoreConfig,
-        channelKey: "matrix",
-        accountId,
-        name,
-      }),
-    validateInput: ({ input }) => {
-      if (input.useEnv) {
-        return null;
-      }
-      if (!input.homeserver?.trim()) {
-        return "Matrix requires --homeserver";
-      }
-      const accessToken = input.accessToken?.trim();
-      const password = normalizeSecretInputString(input.password);
-      const userId = input.userId?.trim();
-      if (!accessToken && !password) {
-        return "Matrix requires --access-token or --password";
-      }
-      if (!accessToken) {
-        if (!userId) {
-          return "Matrix requires --user-id when using --password";
-        }
-        if (!password) {
-          return "Matrix requires --password when using --user-id";
-        }
-      }
-      return null;
-    },
-    applyAccountConfig: ({ cfg, input }) => {
-      const namedConfig = applyAccountNameToChannelSection({
-        cfg: cfg as CoreConfig,
-        channelKey: "matrix",
-        accountId: DEFAULT_ACCOUNT_ID,
-        name: input.name,
-      });
-      if (input.useEnv) {
-        return {
-          ...namedConfig,
-          channels: {
-            ...namedConfig.channels,
-            matrix: {
-              ...namedConfig.channels?.matrix,
-              enabled: true,
-            },
-          },
-        } as CoreConfig;
-      }
-      return buildMatrixConfigUpdate(namedConfig as CoreConfig, {
-        homeserver: input.homeserver?.trim(),
-        userId: input.userId?.trim(),
-        accessToken: input.accessToken?.trim(),
-        password: normalizeSecretInputString(input.password),
-        deviceName: input.deviceName?.trim(),
-        initialSyncLimit: input.initialSyncLimit,
-      });
-    },
-  },
-  outbound: matrixOutbound,
-  status: {
-    defaultRuntime: {
-      accountId: DEFAULT_ACCOUNT_ID,
-      running: false,
-      lastStartAt: null,
-      lastStopAt: null,
-      lastError: null,
-    },
-    collectStatusIssues: (accounts) => collectStatusIssuesFromLastError("matrix", accounts),
-    buildChannelSummary: ({ snapshot }) =>
-      buildProbeChannelStatusSummary(snapshot, { baseUrl: snapshot.baseUrl ?? null }),
-    probeAccount: async ({ account, timeoutMs, cfg }) => {
-      try {
-        const auth = await resolveMatrixAuth({
-          cfg: cfg as CoreConfig,
-          accountId: account.accountId,
-        });
-        return await probeMatrix({
-          homeserver: auth.homeserver,
-          accessToken: auth.accessToken,
-          userId: auth.userId,
-          timeoutMs,
-        });
-      } catch (err) {
-        return {
-          ok: false,
-          error: err instanceof Error ? err.message : String(err),
-          elapsedMs: 0,
-        };
-      }
-    },
-    buildAccountSnapshot: ({ account, runtime, probe }) => ({
-      accountId: account.accountId,
-      name: account.name,
-      enabled: account.enabled,
-      configured: account.configured,
-      baseUrl: account.homeserver,
-      running: runtime?.running ?? false,
-      lastStartAt: runtime?.lastStartAt ?? null,
-      lastStopAt: runtime?.lastStopAt ?? null,
-      lastError: runtime?.lastError ?? null,
-      probe,
-      lastProbeAt: runtime?.lastProbeAt ?? null,
-      lastInboundAt: runtime?.lastInboundAt ?? null,
-      lastOutboundAt: runtime?.lastOutboundAt ?? null,
-    }),
-  },
-  gateway: {
-    startAccount: async (ctx) => {
-      const account = ctx.account;
-      ctx.setStatus({
-        accountId: account.accountId,
-        baseUrl: account.homeserver,
-      });
-      ctx.log?.info(`[${account.accountId}] starting provider (${account.homeserver ?? "matrix"})`);
-
-      // Serialize startup: wait for any previous startup to complete import phase.
-      // This works around a race condition with concurrent dynamic imports.
-      //
-      // INVARIANT: The import() below cannot hang because:
-      // 1. It only loads local ESM modules with no circular awaits
-      // 2. Module initialization is synchronous (no top-level await in ./matrix/index.js)
-      // 3. The lock only serializes the import phase, not the provider startup
-      const previousLock = matrixStartupLock;
-      let releaseLock: () => void = () => {};
-      matrixStartupLock = new Promise<void>((resolve) => {
-        releaseLock = resolve;
-      });
-      await previousLock;
-
-      // Lazy import: the monitor pulls the reply pipeline; avoid ESM init cycles.
-      // Wrap in try/finally to ensure lock is released even if import fails.
-      let monitorMatrixProvider: typeof import("./matrix/index.js").monitorMatrixProvider;
-      try {
-        const module = await import("./matrix/index.js");
-        monitorMatrixProvider = module.monitorMatrixProvider;
-      } finally {
-        // Release lock after import completes or fails
-        releaseLock();
-      }
-
-      return monitorMatrixProvider({
-        runtime: ctx.runtime,
-        abortSignal: ctx.abortSignal,
-        mediaMaxMb: account.config.mediaMaxMb,
-        initialSyncLimit: account.config.initialSyncLimit,
-        replyToMode: account.config.replyToMode,
-        accountId: account.accountId,
-      });
-    },
-  },
-};

package/src/config-schema.test.ts

@@ -1,26 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { MatrixConfigSchema } from "./config-schema.js";
-
-describe("MatrixConfigSchema SecretInput", () => {
-  it("accepts SecretRef password at top-level", () => {
-    const result = MatrixConfigSchema.safeParse({
-      homeserver: "https://matrix.example.org",
-      userId: "@bot:example.org",
-      password: { source: "env", provider: "default", id: "MATRIX_PASSWORD" },
-    });
-    expect(result.success).toBe(true);
-  });
-
-  it("accepts SecretRef password on account", () => {
-    const result = MatrixConfigSchema.safeParse({
-      accounts: {
-        work: {
-          homeserver: "https://matrix.example.org",
-          userId: "@bot:example.org",
-          password: { source: "env", provider: "default", id: "MATRIX_WORK_PASSWORD" },
-        },
-      },
-    });
-    expect(result.success).toBe(true);
-  });
-});

package/src/config-schema.ts

@@ -1,62 +0,0 @@
-import {
-  AllowFromListSchema,
-  buildNestedDmConfigSchema,
-  DmPolicySchema,
-  GroupPolicySchema,
-} from "openclaw/plugin-sdk/compat";
-import { MarkdownConfigSchema, ToolPolicySchema } from "openclaw/plugin-sdk/matrix";
-import { z } from "zod";
-import { buildSecretInputSchema } from "./secret-input.js";
-
-const matrixActionSchema = z
-  .object({
-    reactions: z.boolean().optional(),
-    messages: z.boolean().optional(),
-    pins: z.boolean().optional(),
-    memberInfo: z.boolean().optional(),
-    channelInfo: z.boolean().optional(),
-  })
-  .optional();
-
-const matrixRoomSchema = z
-  .object({
-    enabled: z.boolean().optional(),
-    allow: z.boolean().optional(),
-    requireMention: z.boolean().optional(),
-    tools: ToolPolicySchema,
-    autoReply: z.boolean().optional(),
-    users: AllowFromListSchema,
-    skills: z.array(z.string()).optional(),
-    systemPrompt: z.string().optional(),
-  })
-  .optional();
-
-export const MatrixConfigSchema = z.object({
-  name: z.string().optional(),
-  enabled: z.boolean().optional(),
-  defaultAccount: z.string().optional(),
-  accounts: z.record(z.string(), z.unknown()).optional(),
-  markdown: MarkdownConfigSchema,
-  homeserver: z.string().optional(),
-  userId: z.string().optional(),
-  accessToken: z.string().optional(),
-  password: buildSecretInputSchema().optional(),
-  deviceName: z.string().optional(),
-  initialSyncLimit: z.number().optional(),
-  encryption: z.boolean().optional(),
-  allowlistOnly: z.boolean().optional(),
-  groupPolicy: GroupPolicySchema.optional(),
-  replyToMode: z.enum(["off", "first", "all"]).optional(),
-  threadReplies: z.enum(["off", "inbound", "always"]).optional(),
-  textChunkLimit: z.number().optional(),
-  chunkMode: z.enum(["length", "newline"]).optional(),
-  responsePrefix: z.string().optional(),
-  mediaMaxMb: z.number().optional(),
-  autoJoin: z.enum(["always", "allowlist", "off"]).optional(),
-  autoJoinAllowlist: AllowFromListSchema,
-  groupAllowFrom: AllowFromListSchema,
-  dm: buildNestedDmConfigSchema(),
-  groups: z.object({}).catchall(matrixRoomSchema).optional(),
-  rooms: z.object({}).catchall(matrixRoomSchema).optional(),
-  actions: matrixActionSchema,
-});

package/src/directory-live.test.ts

@@ -1,85 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { listMatrixDirectoryGroupsLive, listMatrixDirectoryPeersLive } from "./directory-live.js";
-import { resolveMatrixAuth } from "./matrix/client.js";
-
-vi.mock("./matrix/client.js", () => ({
-  resolveMatrixAuth: vi.fn(),
-}));
-
-describe("matrix directory live", () => {
-  const cfg = { channels: { matrix: {} } };
-
-  beforeEach(() => {
-    vi.mocked(resolveMatrixAuth).mockReset();
-    vi.mocked(resolveMatrixAuth).mockResolvedValue({
-      homeserver: "https://matrix.example.org",
-      userId: "@bot:example.org",
-      accessToken: "test-token",
-    });
-    vi.stubGlobal(
-      "fetch",
-      vi.fn().mockResolvedValue({
-        ok: true,
-        json: async () => ({ results: [] }),
-        text: async () => "",
-      }),
-    );
-  });
-
-  afterEach(() => {
-    vi.unstubAllGlobals();
-  });
-
-  it("passes accountId to peer directory auth resolution", async () => {
-    await listMatrixDirectoryPeersLive({
-      cfg,
-      accountId: "assistant",
-      query: "alice",
-      limit: 10,
-    });
-
-    expect(resolveMatrixAuth).toHaveBeenCalledWith({ cfg, accountId: "assistant" });
-  });
-
-  it("passes accountId to group directory auth resolution", async () => {
-    await listMatrixDirectoryGroupsLive({
-      cfg,
-      accountId: "assistant",
-      query: "!room:example.org",
-      limit: 10,
-    });
-
-    expect(resolveMatrixAuth).toHaveBeenCalledWith({ cfg, accountId: "assistant" });
-  });
-
-  it("returns no peer results for empty query without resolving auth", async () => {
-    const result = await listMatrixDirectoryPeersLive({
-      cfg,
-      query: "   ",
-    });
-
-    expect(result).toEqual([]);
-    expect(resolveMatrixAuth).not.toHaveBeenCalled();
-  });
-
-  it("returns no group results for empty query without resolving auth", async () => {
-    const result = await listMatrixDirectoryGroupsLive({
-      cfg,
-      query: "",
-    });
-
-    expect(result).toEqual([]);
-    expect(resolveMatrixAuth).not.toHaveBeenCalled();
-  });
-
-  it("preserves original casing for room IDs without :server suffix", async () => {
-    const mixedCaseId = "!EonMPPbOuhntHEHgZ2dnBO-c_EglMaXlIh2kdo8cgiA";
-    const result = await listMatrixDirectoryGroupsLive({
-      cfg,
-      query: mixedCaseId,
-    });
-
-    expect(result).toHaveLength(1);
-    expect(result[0].id).toBe(mixedCaseId);
-  });
-});