@badgerclaw/connect 1.0.0

package/src/resolve-targets.ts

@@ -0,0 +1,125 @@
+import { mapAllowlistResolutionInputs } from "openclaw/plugin-sdk/compat";
+import type {
+  ChannelDirectoryEntry,
+  ChannelResolveKind,
+  ChannelResolveResult,
+  RuntimeEnv,
+} from "openclaw/plugin-sdk/matrix";
+import { listMatrixDirectoryGroupsLive, listMatrixDirectoryPeersLive } from "./directory-live.js";
+
+function findExactDirectoryMatches(
+  matches: ChannelDirectoryEntry[],
+  query: string,
+): ChannelDirectoryEntry[] {
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) {
+    return [];
+  }
+  return matches.filter((match) => {
+    const id = match.id.trim().toLowerCase();
+    const name = match.name?.trim().toLowerCase();
+    const handle = match.handle?.trim().toLowerCase();
+    return normalized === id || normalized === name || normalized === handle;
+  });
+}
+
+function pickBestGroupMatch(
+  matches: ChannelDirectoryEntry[],
+  query: string,
+): ChannelDirectoryEntry | undefined {
+  if (matches.length === 0) {
+    return undefined;
+  }
+  const [exact] = findExactDirectoryMatches(matches, query);
+  return exact ?? matches[0];
+}
+
+function pickBestUserMatch(
+  matches: ChannelDirectoryEntry[],
+  query: string,
+): ChannelDirectoryEntry | undefined {
+  if (matches.length === 0) {
+    return undefined;
+  }
+  const exact = findExactDirectoryMatches(matches, query);
+  if (exact.length === 1) {
+    return exact[0];
+  }
+  return undefined;
+}
+
+function describeUserMatchFailure(matches: ChannelDirectoryEntry[], query: string): string {
+  if (matches.length === 0) {
+    return "no matches";
+  }
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) {
+    return "empty input";
+  }
+  const exact = findExactDirectoryMatches(matches, normalized);
+  if (exact.length === 0) {
+    return "no exact match; use full BadgerClaw ID";
+  }
+  if (exact.length > 1) {
+    return "multiple exact matches; use full BadgerClaw ID";
+  }
+  return "no exact match; use full BadgerClaw ID";
+}
+
+export async function resolveMatrixTargets(params: {
+  cfg: unknown;
+  inputs: string[];
+  kind: ChannelResolveKind;
+  runtime?: RuntimeEnv;
+}): Promise<ChannelResolveResult[]> {
+  return await mapAllowlistResolutionInputs({
+    inputs: params.inputs,
+    mapInput: async (input): Promise<ChannelResolveResult> => {
+      const trimmed = input.trim();
+      if (!trimmed) {
+        return { input, resolved: false, note: "empty input" };
+      }
+      if (params.kind === "user") {
+        if (trimmed.startsWith("@") && trimmed.includes(":")) {
+          return { input, resolved: true, id: trimmed };
+        }
+        try {
+          const matches = await listMatrixDirectoryPeersLive({
+            cfg: params.cfg,
+            query: trimmed,
+            limit: 5,
+          });
+          const best = pickBestUserMatch(matches, trimmed);
+          return {
+            input,
+            resolved: Boolean(best?.id),
+            id: best?.id,
+            name: best?.name,
+            note: best ? undefined : describeUserMatchFailure(matches, trimmed),
+          };
+        } catch (err) {
+          params.runtime?.error?.(`badgerclaw resolve failed: ${String(err)}`);
+          return { input, resolved: false, note: "lookup failed" };
+        }
+      }
+      try {
+        const matches = await listMatrixDirectoryGroupsLive({
+          cfg: params.cfg,
+          query: trimmed,
+          limit: 5,
+        });
+        const best = pickBestGroupMatch(matches, trimmed);
+        return {
+          input,
+          resolved: Boolean(best?.id),
+          id: best?.id,
+          name: best?.name,
+          note: matches.length > 1 ? "multiple matches; chose first" : undefined,
+        };
+      } catch (err) {
+        params.runtime?.error?.(`badgerclaw resolve failed: ${String(err)}`);
+        return { input, resolved: false, note: "lookup failed" };
+      }
+    },
+  });
+}

package/src/runtime.ts

@@ -0,0 +1,6 @@
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/compat";
+import type { PluginRuntime } from "openclaw/plugin-sdk/matrix";
+
+const { setRuntime: setMatrixRuntime, getRuntime: getMatrixRuntime } =
+  createPluginRuntimeStore<PluginRuntime>("BadgerClaw runtime not initialized");
+export { getMatrixRuntime, setMatrixRuntime };

package/src/secret-input.ts

@@ -0,0 +1,13 @@
+import {
+  buildSecretInputSchema,
+  hasConfiguredSecretInput,
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+} from "openclaw/plugin-sdk/matrix";
+
+export {
+  buildSecretInputSchema,
+  hasConfiguredSecretInput,
+  normalizeResolvedSecretInputString,
+  normalizeSecretInputString,
+};

package/src/test-mocks.ts

@@ -0,0 +1,53 @@
+import type { Mock } from "vitest";
+import { vi } from "vitest";
+
+type MatrixBotSdkMockParams = {
+  matrixClient?: unknown;
+  simpleFsStorageProvider?: unknown;
+  rustSdkCryptoStorageProvider?: unknown;
+  includeVerboseLogService?: boolean;
+};
+
+type MatrixBotSdkMock = {
+  ConsoleLogger: new () => {
+    trace: Mock<() => void>;
+    debug: Mock<() => void>;
+    info: Mock<() => void>;
+    warn: Mock<() => void>;
+    error: Mock<() => void>;
+  };
+  MatrixClient: unknown;
+  LogService: {
+    setLogger: Mock<() => void>;
+    warn?: Mock<() => void>;
+    info?: Mock<() => void>;
+    debug?: Mock<() => void>;
+  };
+  SimpleFsStorageProvider: unknown;
+  RustSdkCryptoStorageProvider: unknown;
+};
+
+export function createMatrixBotSdkMock(params: MatrixBotSdkMockParams = {}): MatrixBotSdkMock {
+  return {
+    ConsoleLogger: class {
+      trace = vi.fn();
+      debug = vi.fn();
+      info = vi.fn();
+      warn = vi.fn();
+      error = vi.fn();
+    },
+    MatrixClient: params.matrixClient ?? class {},
+    LogService: {
+      setLogger: vi.fn(),
+      ...(params.includeVerboseLogService
+        ? {
+            warn: vi.fn(),
+            info: vi.fn(),
+            debug: vi.fn(),
+          }
+        : {}),
+    },
+    SimpleFsStorageProvider: params.simpleFsStorageProvider ?? class {},
+    RustSdkCryptoStorageProvider: params.rustSdkCryptoStorageProvider ?? class {},
+  };
+}

package/src/tool-actions.ts

@@ -0,0 +1,164 @@
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import {
+  createActionGate,
+  jsonResult,
+  readNumberParam,
+  readReactionParams,
+  readStringParam,
+} from "openclaw/plugin-sdk/matrix";
+import {
+  deleteMatrixMessage,
+  editMatrixMessage,
+  getMatrixMemberInfo,
+  getMatrixRoomInfo,
+  listMatrixPins,
+  listMatrixReactions,
+  pinMatrixMessage,
+  readMatrixMessages,
+  removeMatrixReactions,
+  sendMatrixMessage,
+  unpinMatrixMessage,
+} from "./matrix/actions.js";
+import { reactMatrixMessage } from "./matrix/send.js";
+import type { CoreConfig } from "./types.js";
+
+const messageActions = new Set(["sendMessage", "editMessage", "deleteMessage", "readMessages"]);
+const reactionActions = new Set(["react", "reactions"]);
+const pinActions = new Set(["pinMessage", "unpinMessage", "listPins"]);
+
+function readRoomId(params: Record<string, unknown>, required = true): string {
+  const direct = readStringParam(params, "roomId") ?? readStringParam(params, "channelId");
+  if (direct) {
+    return direct;
+  }
+  if (!required) {
+    return readStringParam(params, "to") ?? "";
+  }
+  return readStringParam(params, "to", { required: true });
+}
+
+export async function handleMatrixAction(
+  params: Record<string, unknown>,
+  cfg: CoreConfig,
+): Promise<AgentToolResult<unknown>> {
+  const action = readStringParam(params, "action", { required: true });
+  const isActionEnabled = createActionGate(cfg.channels?.badgerclaw?.actions);
+
+  if (reactionActions.has(action)) {
+    if (!isActionEnabled("reactions")) {
+      throw new Error("BadgerClaw reactions are disabled.");
+    }
+    const roomId = readRoomId(params);
+    const messageId = readStringParam(params, "messageId", { required: true });
+    if (action === "react") {
+      const { emoji, remove, isEmpty } = readReactionParams(params, {
+        removeErrorMessage: "Emoji is required to remove a BadgerClaw reaction.",
+      });
+      if (remove || isEmpty) {
+        const result = await removeMatrixReactions(roomId, messageId, {
+          emoji: remove ? emoji : undefined,
+        });
+        return jsonResult({ ok: true, removed: result.removed });
+      }
+      await reactMatrixMessage(roomId, messageId, emoji);
+      return jsonResult({ ok: true, added: emoji });
+    }
+    const reactions = await listMatrixReactions(roomId, messageId);
+    return jsonResult({ ok: true, reactions });
+  }
+
+  if (messageActions.has(action)) {
+    if (!isActionEnabled("messages")) {
+      throw new Error("BadgerClaw messages are disabled.");
+    }
+    switch (action) {
+      case "sendMessage": {
+        const to = readStringParam(params, "to", { required: true });
+        const content = readStringParam(params, "content", {
+          required: true,
+          allowEmpty: true,
+        });
+        const mediaUrl = readStringParam(params, "mediaUrl");
+        const replyToId =
+          readStringParam(params, "replyToId") ?? readStringParam(params, "replyTo");
+        const threadId = readStringParam(params, "threadId");
+        const result = await sendMatrixMessage(to, content, {
+          mediaUrl: mediaUrl ?? undefined,
+          replyToId: replyToId ?? undefined,
+          threadId: threadId ?? undefined,
+        });
+        return jsonResult({ ok: true, result });
+      }
+      case "editMessage": {
+        const roomId = readRoomId(params);
+        const messageId = readStringParam(params, "messageId", { required: true });
+        const content = readStringParam(params, "content", { required: true });
+        const result = await editMatrixMessage(roomId, messageId, content);
+        return jsonResult({ ok: true, result });
+      }
+      case "deleteMessage": {
+        const roomId = readRoomId(params);
+        const messageId = readStringParam(params, "messageId", { required: true });
+        const reason = readStringParam(params, "reason");
+        await deleteMatrixMessage(roomId, messageId, { reason: reason ?? undefined });
+        return jsonResult({ ok: true, deleted: true });
+      }
+      case "readMessages": {
+        const roomId = readRoomId(params);
+        const limit = readNumberParam(params, "limit", { integer: true });
+        const before = readStringParam(params, "before");
+        const after = readStringParam(params, "after");
+        const result = await readMatrixMessages(roomId, {
+          limit: limit ?? undefined,
+          before: before ?? undefined,
+          after: after ?? undefined,
+        });
+        return jsonResult({ ok: true, ...result });
+      }
+      default:
+        break;
+    }
+  }
+
+  if (pinActions.has(action)) {
+    if (!isActionEnabled("pins")) {
+      throw new Error("BadgerClaw pins are disabled.");
+    }
+    const roomId = readRoomId(params);
+    if (action === "pinMessage") {
+      const messageId = readStringParam(params, "messageId", { required: true });
+      const result = await pinMatrixMessage(roomId, messageId);
+      return jsonResult({ ok: true, pinned: result.pinned });
+    }
+    if (action === "unpinMessage") {
+      const messageId = readStringParam(params, "messageId", { required: true });
+      const result = await unpinMatrixMessage(roomId, messageId);
+      return jsonResult({ ok: true, pinned: result.pinned });
+    }
+    const result = await listMatrixPins(roomId);
+    return jsonResult({ ok: true, pinned: result.pinned, events: result.events });
+  }
+
+  if (action === "memberInfo") {
+    if (!isActionEnabled("memberInfo")) {
+      throw new Error("BadgerClaw member info is disabled.");
+    }
+    const userId = readStringParam(params, "userId", { required: true });
+    const roomId = readStringParam(params, "roomId") ?? readStringParam(params, "channelId");
+    const result = await getMatrixMemberInfo(userId, {
+      roomId: roomId ?? undefined,
+    });
+    return jsonResult({ ok: true, member: result });
+  }
+
+  if (action === "channelInfo") {
+    if (!isActionEnabled("channelInfo")) {
+      throw new Error("BadgerClaw room info is disabled.");
+    }
+    const roomId = readRoomId(params);
+    const result = await getMatrixRoomInfo(roomId);
+    return jsonResult({ ok: true, room: result });
+  }
+
+  throw new Error(`Unsupported BadgerClaw action: ${action}`);
+}

package/src/types.ts

@@ -0,0 +1,118 @@
+import type { DmPolicy, GroupPolicy, SecretInput } from "openclaw/plugin-sdk/matrix";
+export type { DmPolicy, GroupPolicy };
+
+export type ReplyToMode = "off" | "first" | "all";
+
+export type MatrixDmConfig = {
+  /** If false, ignore all incoming Matrix DMs. Default: true. */
+  enabled?: boolean;
+  /** Direct message access policy (default: pairing). */
+  policy?: DmPolicy;
+  /** Allowlist for DM senders (matrix user IDs or "*"). */
+  allowFrom?: Array<string | number>;
+};
+
+export type MatrixRoomConfig = {
+  /** If false, disable the bot in this room (alias for allow: false). */
+  enabled?: boolean;
+  /** Legacy room allow toggle; prefer enabled. */
+  allow?: boolean;
+  /** Require mentioning the bot to trigger replies. */
+  requireMention?: boolean;
+  /** Optional tool policy overrides for this room. */
+  tools?: { allow?: string[]; deny?: string[] };
+  /** If true, reply without mention requirements. */
+  autoReply?: boolean;
+  /** Optional allowlist for room senders (matrix user IDs). */
+  users?: Array<string | number>;
+  /** Optional skill filter for this room. */
+  skills?: string[];
+  /** Optional system prompt snippet for this room. */
+  systemPrompt?: string;
+};
+
+export type MatrixActionConfig = {
+  reactions?: boolean;
+  messages?: boolean;
+  pins?: boolean;
+  memberInfo?: boolean;
+  channelInfo?: boolean;
+};
+
+/** Per-account Matrix config (excludes the accounts field to prevent recursion). */
+export type MatrixAccountConfig = Omit<MatrixConfig, "accounts">;
+
+export type MatrixConfig = {
+  /** Optional display name for this account (used in CLI/UI lists). */
+  name?: string;
+  /** If false, do not start Matrix. Default: true. */
+  enabled?: boolean;
+  /** Multi-account configuration keyed by account ID. */
+  accounts?: Record<string, MatrixAccountConfig>;
+  /** Optional default account id when multiple accounts are configured. */
+  defaultAccount?: string;
+  /** Matrix homeserver URL (https://matrix.example.org). */
+  homeserver?: string;
+  /** Matrix user id (@user:server). */
+  userId?: string;
+  /** Matrix access token. */
+  accessToken?: string;
+  /** Matrix password (used only to fetch access token). */
+  password?: SecretInput;
+  /** Optional device name when logging in via password. */
+  deviceName?: string;
+  /** Initial sync limit for startup (default: @vector-im/matrix-bot-sdk default). */
+  initialSyncLimit?: number;
+  /** Enable end-to-end encryption (E2EE). Default: false. */
+  encryption?: boolean;
+  /** If true, enforce allowlists for groups + DMs regardless of policy. */
+  allowlistOnly?: boolean;
+  /** Group message policy (default: allowlist). */
+  groupPolicy?: GroupPolicy;
+  /** Allowlist for group senders (matrix user IDs). */
+  groupAllowFrom?: Array<string | number>;
+  /** Control reply threading when reply tags are present (off|first|all). */
+  replyToMode?: ReplyToMode;
+  /** How to handle thread replies (off|inbound|always). */
+  threadReplies?: "off" | "inbound" | "always";
+  /** Outbound text chunk size (chars). Default: 4000. */
+  textChunkLimit?: number;
+  /** Chunking mode: "length" (default) splits by size; "newline" splits on every newline. */
+  chunkMode?: "length" | "newline";
+  /** Outbound response prefix override for this channel/account. */
+  responsePrefix?: string;
+  /** Max outbound media size in MB. */
+  mediaMaxMb?: number;
+  /** Auto-join invites (always|allowlist|off). Default: always. */
+  autoJoin?: "always" | "allowlist" | "off";
+  /** Allowlist for auto-join invites (room IDs, aliases). */
+  autoJoinAllowlist?: Array<string | number>;
+  /** Direct message policy + allowlist overrides. */
+  dm?: MatrixDmConfig;
+  /** Room config allowlist keyed by room ID or alias (names resolved to IDs when possible). */
+  groups?: Record<string, MatrixRoomConfig>;
+  /** Room config allowlist keyed by room ID or alias. Legacy; use groups. */
+  rooms?: Record<string, MatrixRoomConfig>;
+  /** Per-action tool gating (default: true for all). */
+  actions?: MatrixActionConfig;
+};
+
+export type CoreConfig = {
+  channels?: {
+    badgerclaw?: MatrixConfig;
+    defaults?: {
+      groupPolicy?: "open" | "allowlist" | "disabled";
+    };
+  };
+  commands?: {
+    useAccessGroups?: boolean;
+  };
+  session?: {
+    store?: string;
+  };
+  messages?: {
+    ackReaction?: string;
+    ackReactionScope?: "group-mentions" | "group-all" | "direct" | "all" | "off" | "none";
+  };
+  [key: string]: unknown;
+};