@openclaw/matrix 2026.3.13 → 2026.5.10-beta.1

package/src/matrix/probe.ts

@@ -1,69 +0,0 @@
-import type { BaseProbeResult } from "openclaw/plugin-sdk/matrix";
-import { createMatrixClient, isBunRuntime } from "./client.js";
-
-export type MatrixProbe = BaseProbeResult & {
-  status?: number | null;
-  elapsedMs: number;
-  userId?: string | null;
-};
-
-export async function probeMatrix(params: {
-  homeserver: string;
-  accessToken: string;
-  userId?: string;
-  timeoutMs: number;
-}): Promise<MatrixProbe> {
-  const started = Date.now();
-  const result: MatrixProbe = {
-    ok: false,
-    status: null,
-    error: null,
-    elapsedMs: 0,
-  };
-  if (isBunRuntime()) {
-    return {
-      ...result,
-      error: "Matrix probe requires Node (bun runtime not supported)",
-      elapsedMs: Date.now() - started,
-    };
-  }
-  if (!params.homeserver?.trim()) {
-    return {
-      ...result,
-      error: "missing homeserver",
-      elapsedMs: Date.now() - started,
-    };
-  }
-  if (!params.accessToken?.trim()) {
-    return {
-      ...result,
-      error: "missing access token",
-      elapsedMs: Date.now() - started,
-    };
-  }
-  try {
-    const client = await createMatrixClient({
-      homeserver: params.homeserver,
-      userId: params.userId ?? "",
-      accessToken: params.accessToken,
-      localTimeoutMs: params.timeoutMs,
-    });
-    // @vector-im/matrix-bot-sdk uses getUserId() which calls whoami internally
-    const userId = await client.getUserId();
-    result.ok = true;
-    result.userId = userId ?? null;
-
-    result.elapsedMs = Date.now() - started;
-    return result;
-  } catch (err) {
-    return {
-      ...result,
-      status:
-        typeof err === "object" && err && "statusCode" in err
-          ? Number((err as { statusCode?: number }).statusCode)
-          : result.status,
-      error: err instanceof Error ? err.message : String(err),
-      elapsedMs: Date.now() - started,
-    };
-  }
-}

package/src/matrix/sdk-runtime.ts

@@ -1,18 +0,0 @@
-import { createRequire } from "node:module";
-
-type MatrixSdkRuntime = typeof import("@vector-im/matrix-bot-sdk");
-
-let cachedMatrixSdkRuntime: MatrixSdkRuntime | null = null;
-
-export function loadMatrixSdk(): MatrixSdkRuntime {
-  if (cachedMatrixSdkRuntime) {
-    return cachedMatrixSdkRuntime;
-  }
-  const req = createRequire(import.meta.url);
-  cachedMatrixSdkRuntime = req("@vector-im/matrix-bot-sdk") as MatrixSdkRuntime;
-  return cachedMatrixSdkRuntime;
-}
-
-export function getMatrixLogService() {
-  return loadMatrixSdk().LogService;
-}

package/src/matrix/send/client.ts

@@ -1,99 +0,0 @@
-import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
-import { getMatrixRuntime } from "../../runtime.js";
-import type { CoreConfig } from "../../types.js";
-import { getActiveMatrixClient, getAnyActiveMatrixClient } from "../active-client.js";
-import { createPreparedMatrixClient } from "../client-bootstrap.js";
-import { isBunRuntime, resolveMatrixAuth, resolveSharedMatrixClient } from "../client.js";
-
-const getCore = () => getMatrixRuntime();
-
-export function ensureNodeRuntime() {
-  if (isBunRuntime()) {
-    throw new Error("Matrix support requires Node (bun runtime not supported)");
-  }
-}
-
-/** Look up account config with case-insensitive key fallback. */
-function findAccountConfig(
-  accounts: Record<string, unknown> | undefined,
-  accountId: string,
-): Record<string, unknown> | undefined {
-  if (!accounts) return undefined;
-  const normalized = normalizeAccountId(accountId);
-  // Direct lookup first
-  if (accounts[normalized]) return accounts[normalized] as Record<string, unknown>;
-  // Case-insensitive fallback
-  for (const key of Object.keys(accounts)) {
-    if (normalizeAccountId(key) === normalized) {
-      return accounts[key] as Record<string, unknown>;
-    }
-  }
-  return undefined;
-}
-
-export function resolveMediaMaxBytes(accountId?: string, cfg?: CoreConfig): number | undefined {
-  const resolvedCfg = cfg ?? (getCore().config.loadConfig() as CoreConfig);
-  // Check account-specific config first (case-insensitive key matching)
-  const accountConfig = findAccountConfig(
-    resolvedCfg.channels?.matrix?.accounts as Record<string, unknown> | undefined,
-    accountId ?? "",
-  );
-  if (typeof accountConfig?.mediaMaxMb === "number") {
-    return (accountConfig.mediaMaxMb as number) * 1024 * 1024;
-  }
-  // Fall back to top-level config
-  if (typeof resolvedCfg.channels?.matrix?.mediaMaxMb === "number") {
-    return resolvedCfg.channels.matrix.mediaMaxMb * 1024 * 1024;
-  }
-  return undefined;
-}
-
-export async function resolveMatrixClient(opts: {
-  client?: MatrixClient;
-  timeoutMs?: number;
-  accountId?: string;
-  cfg?: CoreConfig;
-}): Promise<{ client: MatrixClient; stopOnDone: boolean }> {
-  ensureNodeRuntime();
-  if (opts.client) {
-    return { client: opts.client, stopOnDone: false };
-  }
-  const accountId =
-    typeof opts.accountId === "string" && opts.accountId.trim().length > 0
-      ? normalizeAccountId(opts.accountId)
-      : undefined;
-  // Try to get the client for the specific account
-  const active = getActiveMatrixClient(accountId);
-  if (active) {
-    return { client: active, stopOnDone: false };
-  }
-  // When no account is specified, try the default account first; only fall back to
-  // any active client as a last resort (prevents sending from an arbitrary account).
-  if (!accountId) {
-    const defaultClient = getActiveMatrixClient(DEFAULT_ACCOUNT_ID);
-    if (defaultClient) {
-      return { client: defaultClient, stopOnDone: false };
-    }
-    const anyActive = getAnyActiveMatrixClient();
-    if (anyActive) {
-      return { client: anyActive, stopOnDone: false };
-    }
-  }
-  const shouldShareClient = Boolean(process.env.OPENCLAW_GATEWAY_PORT);
-  if (shouldShareClient) {
-    const client = await resolveSharedMatrixClient({
-      timeoutMs: opts.timeoutMs,
-      accountId,
-      cfg: opts.cfg,
-    });
-    return { client, stopOnDone: false };
-  }
-  const auth = await resolveMatrixAuth({ accountId, cfg: opts.cfg });
-  const client = await createPreparedMatrixClient({
-    auth,
-    timeoutMs: opts.timeoutMs,
-    accountId,
-  });
-  return { client, stopOnDone: true };
-}

package/src/matrix/send/formatting.ts

@@ -1,93 +0,0 @@
-import { getMatrixRuntime } from "../../runtime.js";
-import { markdownToMatrixHtml } from "../format.js";
-import {
-  MsgType,
-  RelationType,
-  type MatrixFormattedContent,
-  type MatrixMediaMsgType,
-  type MatrixRelation,
-  type MatrixReplyRelation,
-  type MatrixTextContent,
-  type MatrixThreadRelation,
-} from "./types.js";
-
-const getCore = () => getMatrixRuntime();
-
-export function buildTextContent(body: string, relation?: MatrixRelation): MatrixTextContent {
-  const content: MatrixTextContent = relation
-    ? {
-        msgtype: MsgType.Text,
-        body,
-        "m.relates_to": relation,
-      }
-    : {
-        msgtype: MsgType.Text,
-        body,
-      };
-  applyMatrixFormatting(content, body);
-  return content;
-}
-
-export function applyMatrixFormatting(content: MatrixFormattedContent, body: string): void {
-  const formatted = markdownToMatrixHtml(body ?? "");
-  if (!formatted) {
-    return;
-  }
-  content.format = "org.matrix.custom.html";
-  content.formatted_body = formatted;
-}
-
-export function buildReplyRelation(replyToId?: string): MatrixReplyRelation | undefined {
-  const trimmed = replyToId?.trim();
-  if (!trimmed) {
-    return undefined;
-  }
-  return { "m.in_reply_to": { event_id: trimmed } };
-}
-
-export function buildThreadRelation(threadId: string, replyToId?: string): MatrixThreadRelation {
-  const trimmed = threadId.trim();
-  return {
-    rel_type: RelationType.Thread,
-    event_id: trimmed,
-    is_falling_back: true,
-    "m.in_reply_to": { event_id: replyToId?.trim() || trimmed },
-  };
-}
-
-export function resolveMatrixMsgType(contentType?: string, _fileName?: string): MatrixMediaMsgType {
-  const kind = getCore().media.mediaKindFromMime(contentType ?? "");
-  switch (kind) {
-    case "image":
-      return MsgType.Image;
-    case "audio":
-      return MsgType.Audio;
-    case "video":
-      return MsgType.Video;
-    default:
-      return MsgType.File;
-  }
-}
-
-export function resolveMatrixVoiceDecision(opts: {
-  wantsVoice: boolean;
-  contentType?: string;
-  fileName?: string;
-}): { useVoice: boolean } {
-  if (!opts.wantsVoice) {
-    return { useVoice: false };
-  }
-  if (isMatrixVoiceCompatibleAudio(opts)) {
-    return { useVoice: true };
-  }
-  return { useVoice: false };
-}
-
-function isMatrixVoiceCompatibleAudio(opts: { contentType?: string; fileName?: string }): boolean {
-  // Matrix currently shares the core voice compatibility policy.
-  // Keep this wrapper as the seam if Matrix policy diverges later.
-  return getCore().media.isVoiceCompatibleAudio({
-    contentType: opts.contentType,
-    fileName: opts.fileName,
-  });
-}

package/src/matrix/send/media.ts

@@ -1,230 +0,0 @@
-import type {
-  DimensionalFileInfo,
-  EncryptedFile,
-  FileWithThumbnailInfo,
-  MatrixClient,
-  TimedFileInfo,
-  VideoFileInfo,
-} from "@vector-im/matrix-bot-sdk";
-import { getMatrixRuntime } from "../../runtime.js";
-import { applyMatrixFormatting } from "./formatting.js";
-import {
-  type MatrixMediaContent,
-  type MatrixMediaInfo,
-  type MatrixMediaMsgType,
-  type MatrixRelation,
-  type MediaKind,
-} from "./types.js";
-
-const getCore = () => getMatrixRuntime();
-type IFileInfo = import("music-metadata").IFileInfo;
-
-export function buildMatrixMediaInfo(params: {
-  size: number;
-  mimetype?: string;
-  durationMs?: number;
-  imageInfo?: DimensionalFileInfo;
-}): MatrixMediaInfo | undefined {
-  const base: FileWithThumbnailInfo = {};
-  if (Number.isFinite(params.size)) {
-    base.size = params.size;
-  }
-  if (params.mimetype) {
-    base.mimetype = params.mimetype;
-  }
-  if (params.imageInfo) {
-    const dimensional: DimensionalFileInfo = {
-      ...base,
-      ...params.imageInfo,
-    };
-    if (typeof params.durationMs === "number") {
-      const videoInfo: VideoFileInfo = {
-        ...dimensional,
-        duration: params.durationMs,
-      };
-      return videoInfo;
-    }
-    return dimensional;
-  }
-  if (typeof params.durationMs === "number") {
-    const timedInfo: TimedFileInfo = {
-      ...base,
-      duration: params.durationMs,
-    };
-    return timedInfo;
-  }
-  if (Object.keys(base).length === 0) {
-    return undefined;
-  }
-  return base;
-}
-
-export function buildMediaContent(params: {
-  msgtype: MatrixMediaMsgType;
-  body: string;
-  url?: string;
-  filename?: string;
-  mimetype?: string;
-  size: number;
-  relation?: MatrixRelation;
-  isVoice?: boolean;
-  durationMs?: number;
-  imageInfo?: DimensionalFileInfo;
-  file?: EncryptedFile;
-}): MatrixMediaContent {
-  const info = buildMatrixMediaInfo({
-    size: params.size,
-    mimetype: params.mimetype,
-    durationMs: params.durationMs,
-    imageInfo: params.imageInfo,
-  });
-  const base: MatrixMediaContent = {
-    msgtype: params.msgtype,
-    body: params.body,
-    filename: params.filename,
-    info: info ?? undefined,
-  };
-  // Encrypted media should only include the "file" payload, not top-level "url".
-  if (!params.file && params.url) {
-    base.url = params.url;
-  }
-  // For encrypted files, add the file object
-  if (params.file) {
-    base.file = params.file;
-  }
-  if (params.isVoice) {
-    base["org.matrix.msc3245.voice"] = {};
-    if (typeof params.durationMs === "number") {
-      base["org.matrix.msc1767.audio"] = {
-        duration: params.durationMs,
-      };
-    }
-  }
-  if (params.relation) {
-    base["m.relates_to"] = params.relation;
-  }
-  applyMatrixFormatting(base, params.body);
-  return base;
-}
-
-const THUMBNAIL_MAX_SIDE = 800;
-const THUMBNAIL_QUALITY = 80;
-
-export async function prepareImageInfo(params: {
-  buffer: Buffer;
-  client: MatrixClient;
-}): Promise<DimensionalFileInfo | undefined> {
-  const meta = await getCore()
-    .media.getImageMetadata(params.buffer)
-    .catch(() => null);
-  if (!meta) {
-    return undefined;
-  }
-  const imageInfo: DimensionalFileInfo = { w: meta.width, h: meta.height };
-  const maxDim = Math.max(meta.width, meta.height);
-  if (maxDim > THUMBNAIL_MAX_SIDE) {
-    try {
-      const thumbBuffer = await getCore().media.resizeToJpeg({
-        buffer: params.buffer,
-        maxSide: THUMBNAIL_MAX_SIDE,
-        quality: THUMBNAIL_QUALITY,
-        withoutEnlargement: true,
-      });
-      const thumbMeta = await getCore()
-        .media.getImageMetadata(thumbBuffer)
-        .catch(() => null);
-      const thumbUri = await params.client.uploadContent(
-        thumbBuffer,
-        "image/jpeg",
-        "thumbnail.jpg",
-      );
-      imageInfo.thumbnail_url = thumbUri;
-      if (thumbMeta) {
-        imageInfo.thumbnail_info = {
-          w: thumbMeta.width,
-          h: thumbMeta.height,
-          mimetype: "image/jpeg",
-          size: thumbBuffer.byteLength,
-        };
-      }
-    } catch {
-      // Thumbnail generation failed, continue without it
-    }
-  }
-  return imageInfo;
-}
-
-export async function resolveMediaDurationMs(params: {
-  buffer: Buffer;
-  contentType?: string;
-  fileName?: string;
-  kind: MediaKind;
-}): Promise<number | undefined> {
-  if (params.kind !== "audio" && params.kind !== "video") {
-    return undefined;
-  }
-  try {
-    const { parseBuffer } = await import("music-metadata");
-    const fileInfo: IFileInfo | string | undefined =
-      params.contentType || params.fileName
-        ? {
-            mimeType: params.contentType,
-            size: params.buffer.byteLength,
-            path: params.fileName,
-          }
-        : undefined;
-    const metadata = await parseBuffer(params.buffer, fileInfo, {
-      duration: true,
-      skipCovers: true,
-    });
-    const durationSeconds = metadata.format.duration;
-    if (typeof durationSeconds === "number" && Number.isFinite(durationSeconds)) {
-      return Math.max(0, Math.round(durationSeconds * 1000));
-    }
-  } catch {
-    // Duration is optional; ignore parse failures.
-  }
-  return undefined;
-}
-
-async function uploadFile(
-  client: MatrixClient,
-  file: Buffer,
-  params: {
-    contentType?: string;
-    filename?: string;
-  },
-): Promise<string> {
-  return await client.uploadContent(file, params.contentType, params.filename);
-}
-
-/**
- * Upload media with optional encryption for E2EE rooms.
- */
-export async function uploadMediaMaybeEncrypted(
-  client: MatrixClient,
-  roomId: string,
-  buffer: Buffer,
-  params: {
-    contentType?: string;
-    filename?: string;
-  },
-): Promise<{ url: string; file?: EncryptedFile }> {
-  // Check if room is encrypted and crypto is available
-  const isEncrypted = client.crypto && (await client.crypto.isRoomEncrypted(roomId));
-
-  if (isEncrypted && client.crypto) {
-    // Encrypt the media before uploading
-    const encrypted = await client.crypto.encryptMedia(buffer);
-    const mxc = await client.uploadContent(encrypted.buffer, params.contentType, params.filename);
-    const file: EncryptedFile = { url: mxc, ...encrypted.file };
-    return {
-      url: mxc,
-      file,
-    };
-  }
-
-  // Upload unencrypted
-  const mxc = await uploadFile(client, buffer, params);
-  return { url: mxc };
-}

package/src/matrix/send/targets.test.ts

@@ -1,98 +0,0 @@
-import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { EventType } from "./types.js";
-
-let resolveMatrixRoomId: typeof import("./targets.js").resolveMatrixRoomId;
-let normalizeThreadId: typeof import("./targets.js").normalizeThreadId;
-
-beforeEach(async () => {
-  vi.resetModules();
-  ({ resolveMatrixRoomId, normalizeThreadId } = await import("./targets.js"));
-});
-
-describe("resolveMatrixRoomId", () => {
-  it("uses m.direct when available", async () => {
-    const userId = "@user:example.org";
-    const client = {
-      getAccountData: vi.fn().mockResolvedValue({
-        [userId]: ["!room:example.org"],
-      }),
-      getJoinedRooms: vi.fn(),
-      getJoinedRoomMembers: vi.fn(),
-      setAccountData: vi.fn(),
-    } as unknown as MatrixClient;
-
-    const roomId = await resolveMatrixRoomId(client, userId);
-
-    expect(roomId).toBe("!room:example.org");
-    // oxlint-disable-next-line typescript/unbound-method
-    expect(client.getJoinedRooms).not.toHaveBeenCalled();
-    // oxlint-disable-next-line typescript/unbound-method
-    expect(client.setAccountData).not.toHaveBeenCalled();
-  });
-
-  it("falls back to joined rooms and persists m.direct", async () => {
-    const userId = "@fallback:example.org";
-    const roomId = "!room:example.org";
-    const setAccountData = vi.fn().mockResolvedValue(undefined);
-    const client = {
-      getAccountData: vi.fn().mockRejectedValue(new Error("nope")),
-      getJoinedRooms: vi.fn().mockResolvedValue([roomId]),
-      getJoinedRoomMembers: vi.fn().mockResolvedValue(["@bot:example.org", userId]),
-      setAccountData,
-    } as unknown as MatrixClient;
-
-    const resolved = await resolveMatrixRoomId(client, userId);
-
-    expect(resolved).toBe(roomId);
-    expect(setAccountData).toHaveBeenCalledWith(
-      EventType.Direct,
-      expect.objectContaining({ [userId]: [roomId] }),
-    );
-  });
-
-  it("continues when a room member lookup fails", async () => {
-    const userId = "@continue:example.org";
-    const roomId = "!good:example.org";
-    const setAccountData = vi.fn().mockResolvedValue(undefined);
-    const getJoinedRoomMembers = vi
-      .fn()
-      .mockRejectedValueOnce(new Error("boom"))
-      .mockResolvedValueOnce(["@bot:example.org", userId]);
-    const client = {
-      getAccountData: vi.fn().mockRejectedValue(new Error("nope")),
-      getJoinedRooms: vi.fn().mockResolvedValue(["!bad:example.org", roomId]),
-      getJoinedRoomMembers,
-      setAccountData,
-    } as unknown as MatrixClient;
-
-    const resolved = await resolveMatrixRoomId(client, userId);
-
-    expect(resolved).toBe(roomId);
-    expect(setAccountData).toHaveBeenCalled();
-  });
-
-  it("allows larger rooms when no 1:1 match exists", async () => {
-    const userId = "@group:example.org";
-    const roomId = "!group:example.org";
-    const client = {
-      getAccountData: vi.fn().mockRejectedValue(new Error("nope")),
-      getJoinedRooms: vi.fn().mockResolvedValue([roomId]),
-      getJoinedRoomMembers: vi
-        .fn()
-        .mockResolvedValue(["@bot:example.org", userId, "@extra:example.org"]),
-      setAccountData: vi.fn().mockResolvedValue(undefined),
-    } as unknown as MatrixClient;
-
-    const resolved = await resolveMatrixRoomId(client, userId);
-
-    expect(resolved).toBe(roomId);
-  });
-});
-
-describe("normalizeThreadId", () => {
-  it("returns null for empty thread ids", () => {
-    expect(normalizeThreadId("   ")).toBeNull();
-    expect(normalizeThreadId("$thread")).toBe("$thread");
-  });
-});