@badgerclaw/connect 1.0.0

package/src/matrix/monitor/inbound-body.ts

@@ -0,0 +1,28 @@
+export function resolveMatrixSenderUsername(senderId: string): string | undefined {
+  const username = senderId.split(":")[0]?.replace(/^@/, "").trim();
+  return username ? username : undefined;
+}
+
+export function resolveMatrixInboundSenderLabel(params: {
+  senderName: string;
+  senderId: string;
+  senderUsername?: string;
+}): string {
+  const senderName = params.senderName.trim();
+  const senderUsername = params.senderUsername ?? resolveMatrixSenderUsername(params.senderId);
+  if (senderName && senderUsername && senderName !== senderUsername) {
+    return `${senderName} (${senderUsername})`;
+  }
+  return senderName || senderUsername || params.senderId;
+}
+
+export function resolveMatrixBodyForAgent(params: {
+  isDirectMessage: boolean;
+  bodyText: string;
+  senderLabel: string;
+}): string {
+  if (params.isDirectMessage) {
+    return params.bodyText;
+  }
+  return `${params.senderLabel}: ${params.bodyText}`;
+}

package/src/matrix/monitor/index.ts

@@ -0,0 +1,414 @@
+import {
+  GROUP_POLICY_BLOCKED_LABEL,
+  mergeAllowlist,
+  resolveRuntimeEnv,
+  resolveAllowlistProviderRuntimeGroupPolicy,
+  resolveDefaultGroupPolicy,
+  summarizeMapping,
+  warnMissingProviderGroupPolicyFallbackOnce,
+  type RuntimeEnv,
+} from "openclaw/plugin-sdk/matrix";
+import { resolveMatrixTargets } from "../../resolve-targets.js";
+import { getMatrixRuntime } from "../../runtime.js";
+import type { CoreConfig, MatrixConfig, MatrixRoomConfig, ReplyToMode } from "../../types.js";
+import { resolveMatrixAccount } from "../accounts.js";
+import { setActiveMatrixClient } from "../active-client.js";
+import {
+  isBunRuntime,
+  resolveMatrixAuth,
+  resolveSharedMatrixClient,
+  stopSharedClientForAccount,
+} from "../client.js";
+import { normalizeMatrixUserId } from "./allowlist.js";
+import { registerMatrixAutoJoin } from "./auto-join.js";
+import { createDirectRoomTracker } from "./direct.js";
+import { registerMatrixMonitorEvents } from "./events.js";
+import { createMatrixRoomMessageHandler } from "./handler.js";
+import { createMatrixRoomInfoResolver } from "./room-info.js";
+
+export type MonitorMatrixOpts = {
+  runtime?: RuntimeEnv;
+  abortSignal?: AbortSignal;
+  mediaMaxMb?: number;
+  initialSyncLimit?: number;
+  replyToMode?: ReplyToMode;
+  accountId?: string | null;
+};
+
+const DEFAULT_MEDIA_MAX_MB = 20;
+export const DEFAULT_STARTUP_GRACE_MS = 5000;
+
+export function isConfiguredMatrixRoomEntry(entry: string): boolean {
+  return entry.startsWith("!") || (entry.startsWith("#") && entry.includes(":"));
+}
+
+function normalizeMatrixUserEntry(raw: string): string {
+  return raw
+    .replace(/^matrix:/i, "")
+    .replace(/^user:/i, "")
+    .trim();
+}
+
+function normalizeMatrixRoomEntry(raw: string): string {
+  return raw
+    .replace(/^matrix:/i, "")
+    .replace(/^(room|channel):/i, "")
+    .trim();
+}
+
+function isMatrixUserId(value: string): boolean {
+  return value.startsWith("@") && value.includes(":");
+}
+
+async function resolveMatrixUserAllowlist(params: {
+  cfg: CoreConfig;
+  runtime: RuntimeEnv;
+  label: string;
+  list?: Array<string | number>;
+}): Promise<string[]> {
+  let allowList = params.list ?? [];
+  if (allowList.length === 0) {
+    return allowList.map(String);
+  }
+  const entries = allowList
+    .map((entry) => normalizeMatrixUserEntry(String(entry)))
+    .filter((entry) => entry && entry !== "*");
+  if (entries.length === 0) {
+    return allowList.map(String);
+  }
+  const mapping: string[] = [];
+  const unresolved: string[] = [];
+  const additions: string[] = [];
+  const pending: string[] = [];
+  for (const entry of entries) {
+    if (isMatrixUserId(entry)) {
+      additions.push(normalizeMatrixUserId(entry));
+      continue;
+    }
+    pending.push(entry);
+  }
+  if (pending.length > 0) {
+    const resolved = await resolveMatrixTargets({
+      cfg: params.cfg,
+      inputs: pending,
+      kind: "user",
+      runtime: params.runtime,
+    });
+    for (const entry of resolved) {
+      if (entry.resolved && entry.id) {
+        const normalizedId = normalizeMatrixUserId(entry.id);
+        additions.push(normalizedId);
+        mapping.push(`${entry.input}→${normalizedId}`);
+      } else {
+        unresolved.push(entry.input);
+      }
+    }
+  }
+  allowList = mergeAllowlist({ existing: allowList, additions });
+  summarizeMapping(params.label, mapping, unresolved, params.runtime);
+  if (unresolved.length > 0) {
+    params.runtime.log?.(
+      `${params.label} entries must be full BadgerClaw user IDs (example: @user:server). Unresolved entries are ignored.`,
+    );
+  }
+  return allowList.map(String);
+}
+
+async function resolveMatrixRoomsConfig(params: {
+  cfg: CoreConfig;
+  runtime: RuntimeEnv;
+  roomsConfig?: Record<string, MatrixRoomConfig>;
+}): Promise<Record<string, MatrixRoomConfig> | undefined> {
+  let roomsConfig = params.roomsConfig;
+  if (!roomsConfig || Object.keys(roomsConfig).length === 0) {
+    return roomsConfig;
+  }
+  const mapping: string[] = [];
+  const unresolved: string[] = [];
+  const nextRooms: Record<string, MatrixRoomConfig> = {};
+  if (roomsConfig["*"]) {
+    nextRooms["*"] = roomsConfig["*"];
+  }
+  const pending: Array<{ input: string; query: string; config: MatrixRoomConfig }> = [];
+  for (const [entry, roomConfig] of Object.entries(roomsConfig)) {
+    if (entry === "*") {
+      continue;
+    }
+    const trimmed = entry.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const cleaned = normalizeMatrixRoomEntry(trimmed);
+    if (isConfiguredMatrixRoomEntry(cleaned)) {
+      if (!nextRooms[cleaned]) {
+        nextRooms[cleaned] = roomConfig;
+      }
+      if (cleaned !== entry) {
+        mapping.push(`${entry}→${cleaned}`);
+      }
+      continue;
+    }
+    pending.push({ input: entry, query: trimmed, config: roomConfig });
+  }
+  if (pending.length > 0) {
+    const resolved = await resolveMatrixTargets({
+      cfg: params.cfg,
+      inputs: pending.map((entry) => entry.query),
+      kind: "group",
+      runtime: params.runtime,
+    });
+    resolved.forEach((entry, index) => {
+      const source = pending[index];
+      if (!source) {
+        return;
+      }
+      if (entry.resolved && entry.id) {
+        if (!nextRooms[entry.id]) {
+          nextRooms[entry.id] = source.config;
+        }
+        mapping.push(`${source.input}→${entry.id}`);
+      } else {
+        unresolved.push(source.input);
+      }
+    });
+  }
+  roomsConfig = nextRooms;
+  summarizeMapping("badgerclaw rooms", mapping, unresolved, params.runtime);
+  if (unresolved.length > 0) {
+    params.runtime.log?.(
+      "badgerclaw rooms must be room IDs or aliases (example: !room:server or #alias:server). Unresolved entries are ignored.",
+    );
+  }
+  if (Object.keys(roomsConfig).length === 0) {
+    return roomsConfig;
+  }
+  const nextRoomsWithUsers = { ...roomsConfig };
+  for (const [roomKey, roomConfig] of Object.entries(roomsConfig)) {
+    const users = roomConfig?.users ?? [];
+    if (users.length === 0) {
+      continue;
+    }
+    const resolvedUsers = await resolveMatrixUserAllowlist({
+      cfg: params.cfg,
+      runtime: params.runtime,
+      label: `badgerclaw room users (${roomKey})`,
+      list: users,
+    });
+    if (resolvedUsers !== users) {
+      nextRoomsWithUsers[roomKey] = { ...roomConfig, users: resolvedUsers };
+    }
+  }
+  return nextRoomsWithUsers;
+}
+
+async function resolveMatrixMonitorConfig(params: {
+  cfg: CoreConfig;
+  runtime: RuntimeEnv;
+  accountConfig: MatrixConfig;
+}): Promise<{
+  allowFrom: string[];
+  groupAllowFrom: string[];
+  roomsConfig?: Record<string, MatrixRoomConfig>;
+}> {
+  const allowFrom = await resolveMatrixUserAllowlist({
+    cfg: params.cfg,
+    runtime: params.runtime,
+    label: "badgerclaw dm allowlist",
+    list: params.accountConfig.dm?.allowFrom ?? [],
+  });
+  const groupAllowFrom = await resolveMatrixUserAllowlist({
+    cfg: params.cfg,
+    runtime: params.runtime,
+    label: "badgerclaw group allowlist",
+    list: params.accountConfig.groupAllowFrom ?? [],
+  });
+  const roomsConfig = await resolveMatrixRoomsConfig({
+    cfg: params.cfg,
+    runtime: params.runtime,
+    roomsConfig: params.accountConfig.groups ?? params.accountConfig.rooms,
+  });
+  return { allowFrom, groupAllowFrom, roomsConfig };
+}
+
+export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promise<void> {
+  if (isBunRuntime()) {
+    throw new Error("BadgerClaw provider requires Node (bun runtime not supported)");
+  }
+  const core = getMatrixRuntime();
+  let cfg = core.config.loadConfig() as CoreConfig;
+  if (cfg.channels?.badgerclaw?.enabled === false) {
+    return;
+  }
+
+  const logger = core.logging.getChildLogger({ module: "matrix-auto-reply" });
+  const runtime: RuntimeEnv = resolveRuntimeEnv({
+    runtime: opts.runtime,
+    logger,
+  });
+  const logVerboseMessage = (message: string) => {
+    if (!core.logging.shouldLogVerbose()) {
+      return;
+    }
+    logger.debug?.(message);
+  };
+
+  // Resolve account-specific config for multi-account support
+  const account = resolveMatrixAccount({ cfg, accountId: opts.accountId });
+  const accountConfig = account.config;
+  const allowlistOnly = accountConfig.allowlistOnly === true;
+  const { allowFrom, groupAllowFrom, roomsConfig } = await resolveMatrixMonitorConfig({
+    cfg,
+    runtime,
+    accountConfig,
+  });
+
+  cfg = {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      badgerclaw: {
+        ...cfg.channels?.badgerclaw,
+        dm: {
+          ...cfg.channels?.badgerclaw?.dm,
+          allowFrom,
+        },
+        groupAllowFrom,
+        ...(roomsConfig ? { groups: roomsConfig } : {}),
+      },
+    },
+  };
+
+  const auth = await resolveMatrixAuth({ cfg, accountId: opts.accountId });
+  const resolvedInitialSyncLimit =
+    typeof opts.initialSyncLimit === "number"
+      ? Math.max(0, Math.floor(opts.initialSyncLimit))
+      : auth.initialSyncLimit;
+  const authWithLimit =
+    resolvedInitialSyncLimit === auth.initialSyncLimit
+      ? auth
+      : { ...auth, initialSyncLimit: resolvedInitialSyncLimit };
+  const client = await resolveSharedMatrixClient({
+    cfg,
+    auth: authWithLimit,
+    startClient: false,
+    accountId: opts.accountId,
+  });
+  setActiveMatrixClient(client, opts.accountId);
+
+  const mentionRegexes = core.channel.mentions.buildMentionRegexes(cfg);
+  const defaultGroupPolicy = resolveDefaultGroupPolicy(cfg);
+  const { groupPolicy: groupPolicyRaw, providerMissingFallbackApplied } =
+    resolveAllowlistProviderRuntimeGroupPolicy({
+      providerConfigPresent: cfg.channels?.badgerclaw !== undefined,
+      groupPolicy: accountConfig.groupPolicy,
+      defaultGroupPolicy,
+    });
+  warnMissingProviderGroupPolicyFallbackOnce({
+    providerMissingFallbackApplied,
+    providerKey: "badgerclaw",
+    accountId: account.accountId,
+    blockedLabel: GROUP_POLICY_BLOCKED_LABEL.room,
+    log: (message) => logVerboseMessage(message),
+  });
+  const groupPolicy = allowlistOnly && groupPolicyRaw === "open" ? "allowlist" : groupPolicyRaw;
+  const replyToMode = opts.replyToMode ?? accountConfig.replyToMode ?? "off";
+  const threadReplies = accountConfig.threadReplies ?? "inbound";
+  const dmConfig = accountConfig.dm;
+  const dmEnabled = dmConfig?.enabled ?? true;
+  const dmPolicyRaw = dmConfig?.policy ?? "pairing";
+  const dmPolicy = allowlistOnly && dmPolicyRaw !== "disabled" ? "allowlist" : dmPolicyRaw;
+  const textLimit = core.channel.text.resolveTextChunkLimit(cfg, "badgerclaw");
+  const mediaMaxMb = opts.mediaMaxMb ?? accountConfig.mediaMaxMb ?? DEFAULT_MEDIA_MAX_MB;
+  const mediaMaxBytes = Math.max(1, mediaMaxMb) * 1024 * 1024;
+  const startupMs = Date.now();
+  const startupGraceMs = DEFAULT_STARTUP_GRACE_MS;
+  const directTracker = createDirectRoomTracker(client, {
+    log: logVerboseMessage,
+    includeMemberCountInLogs: core.logging.shouldLogVerbose(),
+  });
+  registerMatrixAutoJoin({ client, cfg, runtime });
+  const warnedEncryptedRooms = new Set<string>();
+  const warnedCryptoMissingRooms = new Set<string>();
+
+  const { getRoomInfo, getMemberDisplayName } = createMatrixRoomInfoResolver(client);
+  const handleRoomMessage = createMatrixRoomMessageHandler({
+    client,
+    core,
+    cfg,
+    runtime,
+    logger,
+    logVerboseMessage,
+    allowFrom,
+    roomsConfig,
+    mentionRegexes,
+    groupPolicy,
+    replyToMode,
+    threadReplies,
+    dmEnabled,
+    dmPolicy,
+    textLimit,
+    mediaMaxBytes,
+    startupMs,
+    startupGraceMs,
+    directTracker,
+    getRoomInfo,
+    getMemberDisplayName,
+    accountId: opts.accountId,
+  });
+
+  registerMatrixMonitorEvents({
+    client,
+    auth,
+    logVerboseMessage,
+    warnedEncryptedRooms,
+    warnedCryptoMissingRooms,
+    logger,
+    formatNativeDependencyHint: core.system.formatNativeDependencyHint,
+    onRoomMessage: handleRoomMessage,
+  });
+
+  logVerboseMessage("badgerclaw: starting client");
+  await resolveSharedMatrixClient({
+    cfg,
+    auth: authWithLimit,
+    accountId: opts.accountId,
+  });
+  logVerboseMessage("badgerclaw: client started");
+
+  // @vector-im/matrix-bot-sdk client is already started via resolveSharedMatrixClient
+  logger.info(`badgerclaw: logged in as ${auth.userId}`);
+
+  // If E2EE is enabled, trigger device verification
+  if (auth.encryption && client.crypto) {
+    try {
+      // Request verification from other sessions
+      const verificationRequest = await (
+        client.crypto as { requestOwnUserVerification?: () => Promise<unknown> }
+      ).requestOwnUserVerification?.();
+      if (verificationRequest) {
+        logger.info("badgerclaw: device verification requested - please verify in another client");
+      }
+    } catch (err) {
+      logger.debug?.("Device verification request failed (may already be verified)", {
+        error: String(err),
+      });
+    }
+  }
+
+  await new Promise<void>((resolve) => {
+    const onAbort = () => {
+      try {
+        logVerboseMessage("badgerclaw: stopping client");
+        stopSharedClientForAccount(auth, opts.accountId);
+      } finally {
+        setActiveMatrixClient(null, opts.accountId);
+        resolve();
+      }
+    };
+    if (opts.abortSignal?.aborted) {
+      onAbort();
+      return;
+    }
+    opts.abortSignal?.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/matrix/monitor/location.ts

@@ -0,0 +1,100 @@
+import type { LocationMessageEventContent } from "@vector-im/matrix-bot-sdk";
+import {
+  formatLocationText,
+  toLocationContext,
+  type NormalizedLocation,
+} from "openclaw/plugin-sdk/matrix";
+import { EventType } from "./types.js";
+
+export type MatrixLocationPayload = {
+  text: string;
+  context: ReturnType<typeof toLocationContext>;
+};
+
+type GeoUriParams = {
+  latitude: number;
+  longitude: number;
+  accuracy?: number;
+};
+
+function parseGeoUri(value: string): GeoUriParams | null {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+  if (!trimmed.toLowerCase().startsWith("geo:")) {
+    return null;
+  }
+  const payload = trimmed.slice(4);
+  const [coordsPart, ...paramParts] = payload.split(";");
+  const coords = coordsPart.split(",");
+  if (coords.length < 2) {
+    return null;
+  }
+  const latitude = Number.parseFloat(coords[0] ?? "");
+  const longitude = Number.parseFloat(coords[1] ?? "");
+  if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) {
+    return null;
+  }
+
+  const params = new Map<string, string>();
+  for (const part of paramParts) {
+    const segment = part.trim();
+    if (!segment) {
+      continue;
+    }
+    const eqIndex = segment.indexOf("=");
+    const rawKey = eqIndex === -1 ? segment : segment.slice(0, eqIndex);
+    const rawValue = eqIndex === -1 ? "" : segment.slice(eqIndex + 1);
+    const key = rawKey.trim().toLowerCase();
+    if (!key) {
+      continue;
+    }
+    const valuePart = rawValue.trim();
+    params.set(key, valuePart ? decodeURIComponent(valuePart) : "");
+  }
+
+  const accuracyRaw = params.get("u");
+  const accuracy = accuracyRaw ? Number.parseFloat(accuracyRaw) : undefined;
+
+  return {
+    latitude,
+    longitude,
+    accuracy: Number.isFinite(accuracy) ? accuracy : undefined,
+  };
+}
+
+export function resolveMatrixLocation(params: {
+  eventType: string;
+  content: LocationMessageEventContent;
+}): MatrixLocationPayload | null {
+  const { eventType, content } = params;
+  const isLocation =
+    eventType === EventType.Location ||
+    (eventType === EventType.RoomMessage && content.msgtype === EventType.Location);
+  if (!isLocation) {
+    return null;
+  }
+  const geoUri = typeof content.geo_uri === "string" ? content.geo_uri.trim() : "";
+  if (!geoUri) {
+    return null;
+  }
+  const parsed = parseGeoUri(geoUri);
+  if (!parsed) {
+    return null;
+  }
+  const caption = typeof content.body === "string" ? content.body.trim() : "";
+  const location: NormalizedLocation = {
+    latitude: parsed.latitude,
+    longitude: parsed.longitude,
+    accuracy: parsed.accuracy,
+    caption: caption || undefined,
+    source: "pin",
+    isLive: false,
+  };
+
+  return {
+    text: formatLocationText(location),
+    context: toLocationContext(location),
+  };
+}

package/src/matrix/monitor/media.ts

@@ -0,0 +1,118 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import { getMatrixRuntime } from "../../runtime.js";
+
+// Type for encrypted file info
+type EncryptedFile = {
+  url: string;
+  key: {
+    kty: string;
+    key_ops: string[];
+    alg: string;
+    k: string;
+    ext: boolean;
+  };
+  iv: string;
+  hashes: Record<string, string>;
+  v: string;
+};
+
+async function fetchMatrixMediaBuffer(params: {
+  client: MatrixClient;
+  mxcUrl: string;
+  maxBytes: number;
+}): Promise<{ buffer: Buffer; headerType?: string } | null> {
+  // @vector-im/matrix-bot-sdk provides mxcToHttp helper
+  const url = params.client.mxcToHttp(params.mxcUrl);
+  if (!url) {
+    return null;
+  }
+
+  // Use the client's download method which handles auth
+  try {
+    const result = await params.client.downloadContent(params.mxcUrl);
+    const raw = result.data ?? result;
+    const buffer = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+
+    if (buffer.byteLength > params.maxBytes) {
+      throw new Error("BadgerClaw media exceeds configured size limit");
+    }
+    return { buffer, headerType: result.contentType };
+  } catch (err) {
+    throw new Error(`BadgerClaw media download failed: ${String(err)}`, { cause: err });
+  }
+}
+
+/**
+ * Download and decrypt encrypted media from a Matrix room.
+ * Uses @vector-im/matrix-bot-sdk's decryptMedia which handles both download and decryption.
+ */
+async function fetchEncryptedMediaBuffer(params: {
+  client: MatrixClient;
+  file: EncryptedFile;
+  maxBytes: number;
+}): Promise<{ buffer: Buffer } | null> {
+  if (!params.client.crypto) {
+    throw new Error("Cannot decrypt media: crypto not enabled");
+  }
+
+  // decryptMedia handles downloading and decrypting the encrypted content internally
+  const decrypted = await params.client.crypto.decryptMedia(
+    params.file as Parameters<typeof params.client.crypto.decryptMedia>[0],
+  );
+
+  if (decrypted.byteLength > params.maxBytes) {
+    throw new Error("BadgerClaw media exceeds configured size limit");
+  }
+
+  return { buffer: decrypted };
+}
+
+export async function downloadMatrixMedia(params: {
+  client: MatrixClient;
+  mxcUrl: string;
+  contentType?: string;
+  sizeBytes?: number;
+  maxBytes: number;
+  file?: EncryptedFile;
+}): Promise<{
+  path: string;
+  contentType?: string;
+  placeholder: string;
+} | null> {
+  let fetched: { buffer: Buffer; headerType?: string } | null;
+  if (typeof params.sizeBytes === "number" && params.sizeBytes > params.maxBytes) {
+    throw new Error("BadgerClaw media exceeds configured size limit");
+  }
+
+  if (params.file) {
+    // Encrypted media
+    fetched = await fetchEncryptedMediaBuffer({
+      client: params.client,
+      file: params.file,
+      maxBytes: params.maxBytes,
+    });
+  } else {
+    // Unencrypted media
+    fetched = await fetchMatrixMediaBuffer({
+      client: params.client,
+      mxcUrl: params.mxcUrl,
+      maxBytes: params.maxBytes,
+    });
+  }
+
+  if (!fetched) {
+    return null;
+  }
+  const headerType = fetched.headerType ?? params.contentType ?? undefined;
+  const saved = await getMatrixRuntime().channel.media.saveMediaBuffer(
+    fetched.buffer,
+    headerType,
+    "inbound",
+    params.maxBytes,
+  );
+  return {
+    path: saved.path,
+    contentType: saved.contentType,
+    placeholder: "[badgerclaw media]",
+  };
+}