@openclaw/matrix 2026.3.12 → 2026.5.9-beta.1

package/src/directory-live.ts

@@ -1,209 +0,0 @@
-import type { ChannelDirectoryEntry } from "openclaw/plugin-sdk/matrix";
-import { resolveMatrixAuth } from "./matrix/client.js";
-
-type MatrixUserResult = {
-  user_id?: string;
-  display_name?: string;
-};
-
-type MatrixUserDirectoryResponse = {
-  results?: MatrixUserResult[];
-};
-
-type MatrixJoinedRoomsResponse = {
-  joined_rooms?: string[];
-};
-
-type MatrixRoomNameState = {
-  name?: string;
-};
-
-type MatrixAliasLookup = {
-  room_id?: string;
-};
-
-type MatrixDirectoryLiveParams = {
-  cfg: unknown;
-  accountId?: string | null;
-  query?: string | null;
-  limit?: number | null;
-};
-
-type MatrixResolvedAuth = Awaited<ReturnType<typeof resolveMatrixAuth>>;
-
-async function fetchMatrixJson<T>(params: {
-  homeserver: string;
-  path: string;
-  accessToken: string;
-  method?: "GET" | "POST";
-  body?: unknown;
-}): Promise<T> {
-  const res = await fetch(`${params.homeserver}${params.path}`, {
-    method: params.method ?? "GET",
-    headers: {
-      Authorization: `Bearer ${params.accessToken}`,
-      "Content-Type": "application/json",
-    },
-    body: params.body ? JSON.stringify(params.body) : undefined,
-  });
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    throw new Error(`Matrix API ${params.path} failed (${res.status}): ${text || "unknown error"}`);
-  }
-  return (await res.json()) as T;
-}
-
-function normalizeQuery(value?: string | null): string {
-  return value?.trim().toLowerCase() ?? "";
-}
-
-function resolveMatrixDirectoryLimit(limit?: number | null): number {
-  return typeof limit === "number" && limit > 0 ? limit : 20;
-}
-
-async function resolveMatrixDirectoryContext(
-  params: MatrixDirectoryLiveParams,
-): Promise<{ query: string; auth: MatrixResolvedAuth } | null> {
-  const query = normalizeQuery(params.query);
-  if (!query) {
-    return null;
-  }
-  const auth = await resolveMatrixAuth({ cfg: params.cfg as never, accountId: params.accountId });
-  return { query, auth };
-}
-
-function createGroupDirectoryEntry(params: {
-  id: string;
-  name: string;
-  handle?: string;
-}): ChannelDirectoryEntry {
-  return {
-    kind: "group",
-    id: params.id,
-    name: params.name,
-    handle: params.handle,
-  } satisfies ChannelDirectoryEntry;
-}
-
-export async function listMatrixDirectoryPeersLive(
-  params: MatrixDirectoryLiveParams,
-): Promise<ChannelDirectoryEntry[]> {
-  const context = await resolveMatrixDirectoryContext(params);
-  if (!context) {
-    return [];
-  }
-  const { query, auth } = context;
-  const res = await fetchMatrixJson<MatrixUserDirectoryResponse>({
-    homeserver: auth.homeserver,
-    accessToken: auth.accessToken,
-    path: "/_matrix/client/v3/user_directory/search",
-    method: "POST",
-    body: {
-      search_term: query,
-      limit: resolveMatrixDirectoryLimit(params.limit),
-    },
-  });
-  const results = res.results ?? [];
-  return results
-    .map((entry) => {
-      const userId = entry.user_id?.trim();
-      if (!userId) {
-        return null;
-      }
-      return {
-        kind: "user",
-        id: userId,
-        name: entry.display_name?.trim() || undefined,
-        handle: entry.display_name ? `@${entry.display_name.trim()}` : undefined,
-        raw: entry,
-      } satisfies ChannelDirectoryEntry;
-    })
-    .filter(Boolean) as ChannelDirectoryEntry[];
-}
-
-async function resolveMatrixRoomAlias(
-  homeserver: string,
-  accessToken: string,
-  alias: string,
-): Promise<string | null> {
-  try {
-    const res = await fetchMatrixJson<MatrixAliasLookup>({
-      homeserver,
-      accessToken,
-      path: `/_matrix/client/v3/directory/room/${encodeURIComponent(alias)}`,
-    });
-    return res.room_id?.trim() || null;
-  } catch {
-    return null;
-  }
-}
-
-async function fetchMatrixRoomName(
-  homeserver: string,
-  accessToken: string,
-  roomId: string,
-): Promise<string | null> {
-  try {
-    const res = await fetchMatrixJson<MatrixRoomNameState>({
-      homeserver,
-      accessToken,
-      path: `/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/state/m.room.name`,
-    });
-    return res.name?.trim() || null;
-  } catch {
-    return null;
-  }
-}
-
-export async function listMatrixDirectoryGroupsLive(
-  params: MatrixDirectoryLiveParams,
-): Promise<ChannelDirectoryEntry[]> {
-  const context = await resolveMatrixDirectoryContext(params);
-  if (!context) {
-    return [];
-  }
-  const { query, auth } = context;
-  const limit = resolveMatrixDirectoryLimit(params.limit);
-
-  if (query.startsWith("#")) {
-    const roomId = await resolveMatrixRoomAlias(auth.homeserver, auth.accessToken, query);
-    if (!roomId) {
-      return [];
-    }
-    return [createGroupDirectoryEntry({ id: roomId, name: query, handle: query })];
-  }
-
-  if (query.startsWith("!")) {
-    const originalId = params.query?.trim() ?? query;
-    return [createGroupDirectoryEntry({ id: originalId, name: originalId })];
-  }
-
-  const joined = await fetchMatrixJson<MatrixJoinedRoomsResponse>({
-    homeserver: auth.homeserver,
-    accessToken: auth.accessToken,
-    path: "/_matrix/client/v3/joined_rooms",
-  });
-  const rooms = joined.joined_rooms ?? [];
-  const results: ChannelDirectoryEntry[] = [];
-
-  for (const roomId of rooms) {
-    const name = await fetchMatrixRoomName(auth.homeserver, auth.accessToken, roomId);
-    if (!name) {
-      continue;
-    }
-    if (!name.toLowerCase().includes(query)) {
-      continue;
-    }
-    results.push({
-      kind: "group",
-      id: roomId,
-      name,
-      handle: `#${name}`,
-    });
-    if (results.length >= limit) {
-      break;
-    }
-  }
-
-  return results;
-}

package/src/group-mentions.ts

@@ -1,52 +0,0 @@
-import type { ChannelGroupContext, GroupToolPolicyConfig } from "openclaw/plugin-sdk/matrix";
-import { resolveMatrixAccountConfig } from "./matrix/accounts.js";
-import { resolveMatrixRoomConfig } from "./matrix/monitor/rooms.js";
-import type { CoreConfig } from "./types.js";
-
-function stripLeadingPrefixCaseInsensitive(value: string, prefix: string): string {
-  return value.toLowerCase().startsWith(prefix.toLowerCase())
-    ? value.slice(prefix.length).trim()
-    : value;
-}
-
-function resolveMatrixRoomConfigForGroup(params: ChannelGroupContext) {
-  const rawGroupId = params.groupId?.trim() ?? "";
-  let roomId = rawGroupId;
-  roomId = stripLeadingPrefixCaseInsensitive(roomId, "matrix:");
-  roomId = stripLeadingPrefixCaseInsensitive(roomId, "channel:");
-  roomId = stripLeadingPrefixCaseInsensitive(roomId, "room:");
-
-  const groupChannel = params.groupChannel?.trim() ?? "";
-  const aliases = groupChannel ? [groupChannel] : [];
-  const cfg = params.cfg as CoreConfig;
-  const matrixConfig = resolveMatrixAccountConfig({ cfg, accountId: params.accountId });
-  return resolveMatrixRoomConfig({
-    rooms: matrixConfig.groups ?? matrixConfig.rooms,
-    roomId,
-    aliases,
-    name: groupChannel || undefined,
-  }).config;
-}
-
-export function resolveMatrixGroupRequireMention(params: ChannelGroupContext): boolean {
-  const resolved = resolveMatrixRoomConfigForGroup(params);
-  if (resolved) {
-    if (resolved.autoReply === true) {
-      return false;
-    }
-    if (resolved.autoReply === false) {
-      return true;
-    }
-    if (typeof resolved.requireMention === "boolean") {
-      return resolved.requireMention;
-    }
-  }
-  return true;
-}
-
-export function resolveMatrixGroupToolPolicy(
-  params: ChannelGroupContext,
-): GroupToolPolicyConfig | undefined {
-  const resolved = resolveMatrixRoomConfigForGroup(params);
-  return resolved?.tools;
-}

package/src/matrix/accounts.test.ts

@@ -1,131 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import type { CoreConfig } from "../types.js";
-import { resolveDefaultMatrixAccountId, resolveMatrixAccount } from "./accounts.js";
-
-vi.mock("./credentials.js", () => ({
-  loadMatrixCredentials: () => null,
-  credentialsMatchConfig: () => false,
-}));
-
-const envKeys = [
-  "MATRIX_HOMESERVER",
-  "MATRIX_USER_ID",
-  "MATRIX_ACCESS_TOKEN",
-  "MATRIX_PASSWORD",
-  "MATRIX_DEVICE_NAME",
-];
-
-describe("resolveMatrixAccount", () => {
-  let prevEnv: Record<string, string | undefined> = {};
-
-  beforeEach(() => {
-    prevEnv = {};
-    for (const key of envKeys) {
-      prevEnv[key] = process.env[key];
-      delete process.env[key];
-    }
-  });
-
-  afterEach(() => {
-    for (const key of envKeys) {
-      const value = prevEnv[key];
-      if (value === undefined) {
-        delete process.env[key];
-      } else {
-        process.env[key] = value;
-      }
-    }
-  });
-
-  it("treats access-token-only config as configured", () => {
-    const cfg: CoreConfig = {
-      channels: {
-        matrix: {
-          homeserver: "https://matrix.example.org",
-          accessToken: "tok-access",
-        },
-      },
-    };
-
-    const account = resolveMatrixAccount({ cfg });
-    expect(account.configured).toBe(true);
-  });
-
-  it("requires userId + password when no access token is set", () => {
-    const cfg: CoreConfig = {
-      channels: {
-        matrix: {
-          homeserver: "https://matrix.example.org",
-          userId: "@bot:example.org",
-        },
-      },
-    };
-
-    const account = resolveMatrixAccount({ cfg });
-    expect(account.configured).toBe(false);
-  });
-
-  it("marks password auth as configured when userId is present", () => {
-    const cfg: CoreConfig = {
-      channels: {
-        matrix: {
-          homeserver: "https://matrix.example.org",
-          userId: "@bot:example.org",
-          password: "secret",
-        },
-      },
-    };
-
-    const account = resolveMatrixAccount({ cfg });
-    expect(account.configured).toBe(true);
-  });
-});
-
-describe("resolveDefaultMatrixAccountId", () => {
-  it("prefers channels.matrix.defaultAccount when it matches a configured account", () => {
-    const cfg: CoreConfig = {
-      channels: {
-        matrix: {
-          defaultAccount: "alerts",
-          accounts: {
-            default: { homeserver: "https://matrix.example.org", accessToken: "tok-default" },
-            alerts: { homeserver: "https://matrix.example.org", accessToken: "tok-alerts" },
-          },
-        },
-      },
-    };
-
-    expect(resolveDefaultMatrixAccountId(cfg)).toBe("alerts");
-  });
-
-  it("normalizes channels.matrix.defaultAccount before lookup", () => {
-    const cfg: CoreConfig = {
-      channels: {
-        matrix: {
-          defaultAccount: "Team Alerts",
-          accounts: {
-            "team-alerts": { homeserver: "https://matrix.example.org", accessToken: "tok-alerts" },
-          },
-        },
-      },
-    };
-
-    expect(resolveDefaultMatrixAccountId(cfg)).toBe("team-alerts");
-  });
-
-  it("falls back when channels.matrix.defaultAccount is not configured", () => {
-    const cfg: CoreConfig = {
-      channels: {
-        matrix: {
-          defaultAccount: "missing",
-          accounts: {
-            default: { homeserver: "https://matrix.example.org", accessToken: "tok-default" },
-            alerts: { homeserver: "https://matrix.example.org", accessToken: "tok-alerts" },
-          },
-        },
-      },
-    };
-
-    expect(resolveDefaultMatrixAccountId(cfg)).toBe("default");
-  });
-});

package/src/matrix/accounts.ts

@@ -1,114 +0,0 @@
-import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
-import { createAccountListHelpers } from "openclaw/plugin-sdk/matrix";
-import { hasConfiguredSecretInput } from "../secret-input.js";
-import type { CoreConfig, MatrixConfig } from "../types.js";
-import { resolveMatrixConfigForAccount } from "./client.js";
-import { credentialsMatchConfig, loadMatrixCredentials } from "./credentials.js";
-
-/** Merge account config with top-level defaults, preserving nested objects. */
-function mergeAccountConfig(base: MatrixConfig, account: MatrixConfig): MatrixConfig {
-  const merged = { ...base, ...account };
-  // Deep-merge known nested objects so partial overrides inherit base fields
-  for (const key of ["dm", "actions"] as const) {
-    const b = base[key];
-    const o = account[key];
-    if (typeof b === "object" && b != null && typeof o === "object" && o != null) {
-      (merged as Record<string, unknown>)[key] = { ...b, ...o };
-    }
-  }
-  // Don't propagate the accounts map into the merged per-account config
-  delete (merged as Record<string, unknown>).accounts;
-  delete (merged as Record<string, unknown>).defaultAccount;
-  return merged;
-}
-
-export type ResolvedMatrixAccount = {
-  accountId: string;
-  enabled: boolean;
-  name?: string;
-  configured: boolean;
-  homeserver?: string;
-  userId?: string;
-  config: MatrixConfig;
-};
-
-const {
-  listAccountIds: listMatrixAccountIds,
-  resolveDefaultAccountId: resolveDefaultMatrixAccountId,
-} = createAccountListHelpers("matrix", { normalizeAccountId });
-export { listMatrixAccountIds, resolveDefaultMatrixAccountId };
-
-function resolveAccountConfig(cfg: CoreConfig, accountId: string): MatrixConfig | undefined {
-  const accounts = cfg.channels?.matrix?.accounts;
-  if (!accounts || typeof accounts !== "object") {
-    return undefined;
-  }
-  // Direct lookup first (fast path for already-normalized keys)
-  if (accounts[accountId]) {
-    return accounts[accountId] as MatrixConfig;
-  }
-  // Fall back to case-insensitive match (user may have mixed-case keys in config)
-  const normalized = normalizeAccountId(accountId);
-  for (const key of Object.keys(accounts)) {
-    if (normalizeAccountId(key) === normalized) {
-      return accounts[key] as MatrixConfig;
-    }
-  }
-  return undefined;
-}
-
-export function resolveMatrixAccount(params: {
-  cfg: CoreConfig;
-  accountId?: string | null;
-}): ResolvedMatrixAccount {
-  const accountId = normalizeAccountId(params.accountId);
-  const matrixBase = params.cfg.channels?.matrix ?? {};
-  const base = resolveMatrixAccountConfig({ cfg: params.cfg, accountId });
-  const enabled = base.enabled !== false && matrixBase.enabled !== false;
-
-  const resolved = resolveMatrixConfigForAccount(params.cfg, accountId, process.env);
-  const hasHomeserver = Boolean(resolved.homeserver);
-  const hasUserId = Boolean(resolved.userId);
-  const hasAccessToken = Boolean(resolved.accessToken);
-  const hasPassword = Boolean(resolved.password);
-  const hasPasswordAuth = hasUserId && (hasPassword || hasConfiguredSecretInput(base.password));
-  const stored = loadMatrixCredentials(process.env, accountId);
-  const hasStored =
-    stored && resolved.homeserver
-      ? credentialsMatchConfig(stored, {
-          homeserver: resolved.homeserver,
-          userId: resolved.userId || "",
-        })
-      : false;
-  const configured = hasHomeserver && (hasAccessToken || hasPasswordAuth || Boolean(hasStored));
-  return {
-    accountId,
-    enabled,
-    name: base.name?.trim() || undefined,
-    configured,
-    homeserver: resolved.homeserver || undefined,
-    userId: resolved.userId || undefined,
-    config: base,
-  };
-}
-
-export function resolveMatrixAccountConfig(params: {
-  cfg: CoreConfig;
-  accountId?: string | null;
-}): MatrixConfig {
-  const accountId = normalizeAccountId(params.accountId);
-  const matrixBase = params.cfg.channels?.matrix ?? {};
-  const accountConfig = resolveAccountConfig(params.cfg, accountId);
-  if (!accountConfig) {
-    return matrixBase;
-  }
-  // Merge account-specific config with top-level defaults so settings like
-  // groupPolicy and blockStreaming inherit when not overridden.
-  return mergeAccountConfig(matrixBase, accountConfig);
-}
-
-export function listEnabledMatrixAccounts(cfg: CoreConfig): ResolvedMatrixAccount[] {
-  return listMatrixAccountIds(cfg)
-    .map((accountId) => resolveMatrixAccount({ cfg, accountId }))
-    .filter((account) => account.enabled);
-}

package/src/matrix/actions/client.ts

@@ -1,47 +0,0 @@
-import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
-import { getMatrixRuntime } from "../../runtime.js";
-import type { CoreConfig } from "../../types.js";
-import { getActiveMatrixClient } from "../active-client.js";
-import { createPreparedMatrixClient } from "../client-bootstrap.js";
-import { isBunRuntime, resolveMatrixAuth, resolveSharedMatrixClient } from "../client.js";
-import type { MatrixActionClient, MatrixActionClientOpts } from "./types.js";
-
-export function ensureNodeRuntime() {
-  if (isBunRuntime()) {
-    throw new Error("Matrix support requires Node (bun runtime not supported)");
-  }
-}
-
-export async function resolveActionClient(
-  opts: MatrixActionClientOpts = {},
-): Promise<MatrixActionClient> {
-  ensureNodeRuntime();
-  if (opts.client) {
-    return { client: opts.client, stopOnDone: false };
-  }
-  // Normalize accountId early to ensure consistent keying across all lookups
-  const accountId = normalizeAccountId(opts.accountId);
-  const active = getActiveMatrixClient(accountId);
-  if (active) {
-    return { client: active, stopOnDone: false };
-  }
-  const shouldShareClient = Boolean(process.env.OPENCLAW_GATEWAY_PORT);
-  if (shouldShareClient) {
-    const client = await resolveSharedMatrixClient({
-      cfg: getMatrixRuntime().config.loadConfig() as CoreConfig,
-      timeoutMs: opts.timeoutMs,
-      accountId,
-    });
-    return { client, stopOnDone: false };
-  }
-  const auth = await resolveMatrixAuth({
-    cfg: getMatrixRuntime().config.loadConfig() as CoreConfig,
-    accountId,
-  });
-  const client = await createPreparedMatrixClient({
-    auth,
-    timeoutMs: opts.timeoutMs,
-    accountId,
-  });
-  return { client, stopOnDone: true };
-}

package/src/matrix/actions/limits.test.ts

@@ -1,15 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { resolveMatrixActionLimit } from "./limits.js";
-
-describe("resolveMatrixActionLimit", () => {
-  it("uses fallback for non-finite values", () => {
-    expect(resolveMatrixActionLimit(undefined, 20)).toBe(20);
-    expect(resolveMatrixActionLimit(Number.NaN, 20)).toBe(20);
-  });
-
-  it("normalizes finite numbers to positive integers", () => {
-    expect(resolveMatrixActionLimit(7.9, 20)).toBe(7);
-    expect(resolveMatrixActionLimit(0, 20)).toBe(1);
-    expect(resolveMatrixActionLimit(-3, 20)).toBe(1);
-  });
-});

package/src/matrix/actions/limits.ts

@@ -1,6 +0,0 @@
-export function resolveMatrixActionLimit(raw: unknown, fallback: number): number {
-  if (typeof raw !== "number" || !Number.isFinite(raw)) {
-    return fallback;
-  }
-  return Math.max(1, Math.floor(raw));
-}

package/src/matrix/actions/messages.ts

@@ -1,126 +0,0 @@
-import { resolveMatrixRoomId, sendMessageMatrix } from "../send.js";
-import { resolveActionClient } from "./client.js";
-import { resolveMatrixActionLimit } from "./limits.js";
-import { summarizeMatrixRawEvent } from "./summary.js";
-import {
-  EventType,
-  MsgType,
-  RelationType,
-  type MatrixActionClientOpts,
-  type MatrixMessageSummary,
-  type MatrixRawEvent,
-  type RoomMessageEventContent,
-} from "./types.js";
-
-export async function sendMatrixMessage(
-  to: string,
-  content: string,
-  opts: MatrixActionClientOpts & {
-    mediaUrl?: string;
-    replyToId?: string;
-    threadId?: string;
-  } = {},
-) {
-  return await sendMessageMatrix(to, content, {
-    mediaUrl: opts.mediaUrl,
-    replyToId: opts.replyToId,
-    threadId: opts.threadId,
-    client: opts.client,
-    timeoutMs: opts.timeoutMs,
-  });
-}
-
-export async function editMatrixMessage(
-  roomId: string,
-  messageId: string,
-  content: string,
-  opts: MatrixActionClientOpts = {},
-) {
-  const trimmed = content.trim();
-  if (!trimmed) {
-    throw new Error("Matrix edit requires content");
-  }
-  const { client, stopOnDone } = await resolveActionClient(opts);
-  try {
-    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    const newContent = {
-      msgtype: MsgType.Text,
-      body: trimmed,
-    } satisfies RoomMessageEventContent;
-    const payload: RoomMessageEventContent = {
-      msgtype: MsgType.Text,
-      body: `* ${trimmed}`,
-      "m.new_content": newContent,
-      "m.relates_to": {
-        rel_type: RelationType.Replace,
-        event_id: messageId,
-      },
-    };
-    const eventId = await client.sendMessage(resolvedRoom, payload);
-    return { eventId: eventId ?? null };
-  } finally {
-    if (stopOnDone) {
-      client.stop();
-    }
-  }
-}
-
-export async function deleteMatrixMessage(
-  roomId: string,
-  messageId: string,
-  opts: MatrixActionClientOpts & { reason?: string } = {},
-) {
-  const { client, stopOnDone } = await resolveActionClient(opts);
-  try {
-    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    await client.redactEvent(resolvedRoom, messageId, opts.reason);
-  } finally {
-    if (stopOnDone) {
-      client.stop();
-    }
-  }
-}
-
-export async function readMatrixMessages(
-  roomId: string,
-  opts: MatrixActionClientOpts & {
-    limit?: number;
-    before?: string;
-    after?: string;
-  } = {},
-): Promise<{
-  messages: MatrixMessageSummary[];
-  nextBatch?: string | null;
-  prevBatch?: string | null;
-}> {
-  const { client, stopOnDone } = await resolveActionClient(opts);
-  try {
-    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    const limit = resolveMatrixActionLimit(opts.limit, 20);
-    const token = opts.before?.trim() || opts.after?.trim() || undefined;
-    const dir = opts.after ? "f" : "b";
-    // @vector-im/matrix-bot-sdk uses doRequest for room messages
-    const res = (await client.doRequest(
-      "GET",
-      `/_matrix/client/v3/rooms/${encodeURIComponent(resolvedRoom)}/messages`,
-      {
-        dir,
-        limit,
-        from: token,
-      },
-    )) as { chunk: MatrixRawEvent[]; start?: string; end?: string };
-    const messages = res.chunk
-      .filter((event) => event.type === EventType.RoomMessage)
-      .filter((event) => !event.unsigned?.redacted_because)
-      .map(summarizeMatrixRawEvent);
-    return {
-      messages,
-      nextBatch: res.end ?? null,
-      prevBatch: res.start ?? null,
-    };
-  } finally {
-    if (stopOnDone) {
-      client.stop();
-    }
-  }
-}