@badgerclaw/connect 1.0.0

package/src/matrix/send/client.ts

@@ -0,0 +1,99 @@
+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("BadgerClaw 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?.badgerclaw?.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?.badgerclaw?.mediaMaxMb === "number") {
+    return resolvedCfg.channels.badgerclaw.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

@@ -0,0 +1,93 @@
+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

@@ -0,0 +1,230 @@
+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.ts

@@ -0,0 +1,150 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import { EventType, type MatrixDirectAccountData } from "./types.js";
+
+function normalizeTarget(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    throw new Error("BadgerClaw target is required (room:<id> or #alias)");
+  }
+  return trimmed;
+}
+
+export function normalizeThreadId(raw?: string | number | null): string | null {
+  if (raw === undefined || raw === null) {
+    return null;
+  }
+  const trimmed = String(raw).trim();
+  return trimmed ? trimmed : null;
+}
+
+// Size-capped to prevent unbounded growth (#4948)
+const MAX_DIRECT_ROOM_CACHE_SIZE = 1024;
+const directRoomCache = new Map<string, string>();
+function setDirectRoomCached(key: string, value: string): void {
+  directRoomCache.set(key, value);
+  if (directRoomCache.size > MAX_DIRECT_ROOM_CACHE_SIZE) {
+    const oldest = directRoomCache.keys().next().value;
+    if (oldest !== undefined) {
+      directRoomCache.delete(oldest);
+    }
+  }
+}
+
+async function persistDirectRoom(
+  client: MatrixClient,
+  userId: string,
+  roomId: string,
+): Promise<void> {
+  let directContent: MatrixDirectAccountData | null = null;
+  try {
+    directContent = await client.getAccountData(EventType.Direct);
+  } catch {
+    // Ignore fetch errors and fall back to an empty map.
+  }
+  const existing = directContent && !Array.isArray(directContent) ? directContent : {};
+  const current = Array.isArray(existing[userId]) ? existing[userId] : [];
+  if (current[0] === roomId) {
+    return;
+  }
+  const next = [roomId, ...current.filter((id) => id !== roomId)];
+  try {
+    await client.setAccountData(EventType.Direct, {
+      ...existing,
+      [userId]: next,
+    });
+  } catch {
+    // Ignore persistence errors.
+  }
+}
+
+async function resolveDirectRoomId(client: MatrixClient, userId: string): Promise<string> {
+  const trimmed = userId.trim();
+  if (!trimmed.startsWith("@")) {
+    throw new Error(`BadgerClaw user IDs must be fully qualified (got "${trimmed}")`);
+  }
+
+  const cached = directRoomCache.get(trimmed);
+  if (cached) {
+    return cached;
+  }
+
+  // 1) Fast path: use account data (m.direct) for *this* logged-in user (the bot).
+  try {
+    const directContent = (await client.getAccountData(EventType.Direct)) as Record<
+      string,
+      string[] | undefined
+    >;
+    const list = Array.isArray(directContent?.[trimmed]) ? directContent[trimmed] : [];
+    if (list && list.length > 0) {
+      setDirectRoomCached(trimmed, list[0]);
+      return list[0];
+    }
+  } catch {
+    // Ignore and fall back.
+  }
+
+  // 2) Fallback: look for an existing joined room that looks like a 1:1 with the user.
+  // Many clients only maintain m.direct for *their own* account data, so relying on it is brittle.
+  let fallbackRoom: string | null = null;
+  try {
+    const rooms = await client.getJoinedRooms();
+    for (const roomId of rooms) {
+      let members: string[];
+      try {
+        members = await client.getJoinedRoomMembers(roomId);
+      } catch {
+        continue;
+      }
+      if (!members.includes(trimmed)) {
+        continue;
+      }
+      // Prefer classic 1:1 rooms, but allow larger rooms if requested.
+      if (members.length === 2) {
+        setDirectRoomCached(trimmed, roomId);
+        await persistDirectRoom(client, trimmed, roomId);
+        return roomId;
+      }
+      if (!fallbackRoom) {
+        fallbackRoom = roomId;
+      }
+    }
+  } catch {
+    // Ignore and fall back.
+  }
+
+  if (fallbackRoom) {
+    setDirectRoomCached(trimmed, fallbackRoom);
+    await persistDirectRoom(client, trimmed, fallbackRoom);
+    return fallbackRoom;
+  }
+
+  throw new Error(`No direct room found for ${trimmed} (m.direct missing)`);
+}
+
+export async function resolveMatrixRoomId(client: MatrixClient, raw: string): Promise<string> {
+  const target = normalizeTarget(raw);
+  const lowered = target.toLowerCase();
+  if (lowered.startsWith("badgerclaw:")) {
+    return await resolveMatrixRoomId(client, target.slice("badgerclaw:".length));
+  }
+  if (lowered.startsWith("room:")) {
+    return await resolveMatrixRoomId(client, target.slice("room:".length));
+  }
+  if (lowered.startsWith("channel:")) {
+    return await resolveMatrixRoomId(client, target.slice("channel:".length));
+  }
+  if (lowered.startsWith("user:")) {
+    return await resolveDirectRoomId(client, target.slice("user:".length));
+  }
+  if (target.startsWith("@")) {
+    return await resolveDirectRoomId(client, target);
+  }
+  if (target.startsWith("#")) {
+    const resolved = await client.resolveRoom(target);
+    if (!resolved) {
+      throw new Error(`BadgerClaw alias ${target} could not be resolved`);
+    }
+    return resolved;
+  }
+  return target;
+}

package/src/matrix/send/types.ts

@@ -0,0 +1,110 @@
+import type {
+  DimensionalFileInfo,
+  EncryptedFile,
+  FileWithThumbnailInfo,
+  MessageEventContent,
+  TextualMessageEventContent,
+  TimedFileInfo,
+  VideoFileInfo,
+} from "@vector-im/matrix-bot-sdk";
+
+// Message types
+export const MsgType = {
+  Text: "m.text",
+  Image: "m.image",
+  Audio: "m.audio",
+  Video: "m.video",
+  File: "m.file",
+  Notice: "m.notice",
+} as const;
+
+// Relation types
+export const RelationType = {
+  Annotation: "m.annotation",
+  Replace: "m.replace",
+  Thread: "m.thread",
+} as const;
+
+// Event types
+export const EventType = {
+  Direct: "m.direct",
+  Reaction: "m.reaction",
+  RoomMessage: "m.room.message",
+} as const;
+
+export type MatrixDirectAccountData = Record<string, string[]>;
+
+export type MatrixReplyRelation = {
+  "m.in_reply_to": { event_id: string };
+};
+
+export type MatrixThreadRelation = {
+  rel_type: typeof RelationType.Thread;
+  event_id: string;
+  is_falling_back?: boolean;
+  "m.in_reply_to"?: { event_id: string };
+};
+
+export type MatrixRelation = MatrixReplyRelation | MatrixThreadRelation;
+
+export type MatrixReplyMeta = {
+  "m.relates_to"?: MatrixRelation;
+};
+
+export type MatrixMediaInfo =
+  | FileWithThumbnailInfo
+  | DimensionalFileInfo
+  | TimedFileInfo
+  | VideoFileInfo;
+
+export type MatrixTextContent = TextualMessageEventContent & MatrixReplyMeta;
+
+export type MatrixMediaContent = MessageEventContent &
+  MatrixReplyMeta & {
+    info?: MatrixMediaInfo;
+    url?: string;
+    file?: EncryptedFile;
+    filename?: string;
+    "org.matrix.msc3245.voice"?: Record<string, never>;
+    "org.matrix.msc1767.audio"?: { duration: number };
+  };
+
+export type MatrixOutboundContent = MatrixTextContent | MatrixMediaContent;
+
+export type ReactionEventContent = {
+  "m.relates_to": {
+    rel_type: typeof RelationType.Annotation;
+    event_id: string;
+    key: string;
+  };
+};
+
+export type MatrixSendResult = {
+  messageId: string;
+  roomId: string;
+};
+
+export type MatrixSendOpts = {
+  cfg?: import("../../types.js").CoreConfig;
+  client?: import("@vector-im/matrix-bot-sdk").MatrixClient;
+  mediaUrl?: string;
+  accountId?: string;
+  replyToId?: string;
+  threadId?: string | number | null;
+  timeoutMs?: number;
+  /** Send audio as voice message (voice bubble) instead of audio file. Defaults to false. */
+  audioAsVoice?: boolean;
+};
+
+export type MatrixMediaMsgType =
+  | typeof MsgType.Image
+  | typeof MsgType.Audio
+  | typeof MsgType.Video
+  | typeof MsgType.File;
+
+export type MediaKind = "image" | "audio" | "video" | "document" | "unknown";
+
+export type MatrixFormattedContent = MessageEventContent & {
+  format?: string;
+  formatted_body?: string;
+};

package/src/matrix/send-queue.ts

@@ -0,0 +1,28 @@
+import { KeyedAsyncQueue } from "openclaw/plugin-sdk/keyed-async-queue";
+
+export const DEFAULT_SEND_GAP_MS = 150;
+
+type MatrixSendQueueOptions = {
+  gapMs?: number;
+  delayFn?: (ms: number) => Promise<void>;
+};
+
+// Serialize sends per room to preserve Matrix delivery order.
+const roomQueues = new KeyedAsyncQueue();
+
+export function enqueueSend<T>(
+  roomId: string,
+  fn: () => Promise<T>,
+  options?: MatrixSendQueueOptions,
+): Promise<T> {
+  const gapMs = options?.gapMs ?? DEFAULT_SEND_GAP_MS;
+  const delayFn = options?.delayFn ?? delay;
+  return roomQueues.enqueue(roomId, async () => {
+    await delayFn(gapMs);
+    return await fn();
+  });
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}