@badgerclaw/connect 1.0.0

package/src/channel.ts

@@ -0,0 +1,461 @@
+import {
+  buildOpenGroupPolicyWarning,
+  collectAllowlistProviderGroupPolicyWarnings,
+  createScopedAccountConfigAccessors,
+  createScopedChannelConfigBase,
+  createScopedDmSecurityResolver,
+} from "openclaw/plugin-sdk/compat";
+import {
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
+  buildProbeChannelStatusSummary,
+  collectStatusIssuesFromLastError,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  PAIRING_APPROVED_MESSAGE,
+  type ChannelPlugin,
+} from "openclaw/plugin-sdk/matrix";
+import { buildTrafficStatusSummary } from "/opt/homebrew/lib/node_modules/openclaw/extensions/shared/channel-status-summary.js";
+import { matrixMessageActions } from "./actions.js";
+import { MatrixConfigSchema } from "./config-schema.js";
+import { listMatrixDirectoryGroupsLive, listMatrixDirectoryPeersLive } from "./directory-live.js";
+import {
+  resolveMatrixGroupRequireMention,
+  resolveMatrixGroupToolPolicy,
+} from "./group-mentions.js";
+import {
+  listMatrixAccountIds,
+  resolveMatrixAccountConfig,
+  resolveDefaultMatrixAccountId,
+  resolveMatrixAccount,
+  type ResolvedMatrixAccount,
+} from "./matrix/accounts.js";
+import { resolveMatrixAuth } from "./matrix/client.js";
+import { normalizeMatrixAllowList, normalizeMatrixUserId } from "./matrix/monitor/allowlist.js";
+import { probeMatrix } from "./matrix/probe.js";
+import { sendMessageMatrix } from "./matrix/send.js";
+import { badgerclawOnboardingAdapter } from "./onboarding.js";
+import { matrixOutbound } from "./outbound.js";
+import { resolveMatrixTargets } from "./resolve-targets.js";
+import { normalizeSecretInputString } from "./secret-input.js";
+import type { CoreConfig } from "./types.js";
+
+// Mutex for serializing account startup (workaround for concurrent dynamic import race condition)
+let matrixStartupLock: Promise<void> = Promise.resolve();
+
+const meta = {
+  id: "badgerclaw",
+  label: "BadgerClaw",
+  selectionLabel: "BadgerClaw (plugin)",
+  docsPath: "/channels/badgerclaw",
+  docsLabel: "badgerclaw",
+  blurb: "open protocol; configure a homeserver + access token.",
+  order: 70,
+  quickstartAllowFrom: true,
+};
+
+function normalizeMatrixMessagingTarget(raw: string): string | undefined {
+  let normalized = raw.trim();
+  if (!normalized) {
+    return undefined;
+  }
+  const lowered = normalized.toLowerCase();
+  if (lowered.startsWith("badgerclaw:")) {
+    normalized = normalized.slice("badgerclaw:".length).trim();
+  }
+  const stripped = normalized.replace(/^(room|channel|user):/i, "").trim();
+  return stripped || undefined;
+}
+
+function buildMatrixConfigUpdate(
+  cfg: CoreConfig,
+  input: {
+    homeserver?: string;
+    userId?: string;
+    accessToken?: string;
+    password?: string;
+    deviceName?: string;
+    initialSyncLimit?: number;
+  },
+): CoreConfig {
+  const existing = cfg.channels?.badgerclaw ?? {};
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      badgerclaw: {
+        ...existing,
+        enabled: true,
+        ...(input.homeserver ? { homeserver: input.homeserver } : {}),
+        ...(input.userId ? { userId: input.userId } : {}),
+        ...(input.accessToken ? { accessToken: input.accessToken } : {}),
+        ...(input.password ? { password: input.password } : {}),
+        ...(input.deviceName ? { deviceName: input.deviceName } : {}),
+        ...(typeof input.initialSyncLimit === "number"
+          ? { initialSyncLimit: input.initialSyncLimit }
+          : {}),
+      },
+    },
+  };
+}
+
+const matrixConfigAccessors = createScopedAccountConfigAccessors({
+  resolveAccount: ({ cfg, accountId }) =>
+    resolveMatrixAccountConfig({ cfg: cfg as CoreConfig, accountId }),
+  resolveAllowFrom: (account) => account.dm?.allowFrom,
+  formatAllowFrom: (allowFrom) => normalizeMatrixAllowList(allowFrom),
+});
+
+const matrixConfigBase = createScopedChannelConfigBase<ResolvedMatrixAccount, CoreConfig>({
+  sectionKey: "badgerclaw",
+  listAccountIds: listMatrixAccountIds,
+  resolveAccount: (cfg, accountId) => resolveMatrixAccount({ cfg, accountId }),
+  defaultAccountId: resolveDefaultMatrixAccountId,
+  clearBaseFields: [
+    "name",
+    "homeserver",
+    "userId",
+    "accessToken",
+    "password",
+    "deviceName",
+    "initialSyncLimit",
+  ],
+});
+
+const resolveMatrixDmPolicy = createScopedDmSecurityResolver<ResolvedMatrixAccount>({
+  channelKey: "badgerclaw",
+  resolvePolicy: (account) => account.config.dm?.policy,
+  resolveAllowFrom: (account) => account.config.dm?.allowFrom,
+  allowFromPathSuffix: "dm.",
+  normalizeEntry: (raw) => normalizeMatrixUserId(raw),
+});
+
+export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount> = {
+  id: "badgerclaw",
+  meta,
+  onboarding: badgerclawOnboardingAdapter,
+  pairing: {
+    idLabel: "matrixUserId",
+    normalizeAllowEntry: (entry) => entry.replace(/^badgerclaw:/i, ""),
+    notifyApproval: async ({ id }) => {
+      await sendMessageMatrix(`user:${id}`, PAIRING_APPROVED_MESSAGE);
+    },
+  },
+  capabilities: {
+    chatTypes: ["direct", "group", "thread"],
+    polls: true,
+    reactions: true,
+    threads: true,
+    media: true,
+  },
+  reload: { configPrefixes: ["channels.badgerclaw"] },
+  configSchema: buildChannelConfigSchema(MatrixConfigSchema),
+  config: {
+    ...matrixConfigBase,
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      baseUrl: account.homeserver,
+    }),
+    ...matrixConfigAccessors,
+  },
+  security: {
+    resolveDmPolicy: resolveMatrixDmPolicy,
+    collectWarnings: ({ account, cfg }) => {
+      return collectAllowlistProviderGroupPolicyWarnings({
+        cfg: cfg as CoreConfig,
+        providerConfigPresent: (cfg as CoreConfig).channels?.badgerclaw !== undefined,
+        configuredGroupPolicy: account.config.groupPolicy,
+        collect: (groupPolicy) =>
+          groupPolicy === "open"
+            ? [
+                buildOpenGroupPolicyWarning({
+                  surface: "BadgerClaw rooms",
+                  openBehavior: "allows any room to trigger (mention-gated)",
+                  remediation:
+                    'Set channels.badgerclaw.groupPolicy="allowlist" + channels.badgerclaw.groups (and optionally channels.badgerclaw.groupAllowFrom) to restrict rooms',
+                }),
+              ]
+            : [],
+      });
+    },
+  },
+  groups: {
+    resolveRequireMention: resolveMatrixGroupRequireMention,
+    resolveToolPolicy: resolveMatrixGroupToolPolicy,
+  },
+  threading: {
+    resolveReplyToMode: ({ cfg, accountId }) =>
+      resolveMatrixAccountConfig({ cfg: cfg as CoreConfig, accountId }).replyToMode ?? "off",
+    buildToolContext: ({ context, hasRepliedRef }) => {
+      const currentTarget = context.To;
+      return {
+        currentChannelId: currentTarget?.trim() || undefined,
+        currentThreadTs:
+          context.MessageThreadId != null ? String(context.MessageThreadId) : context.ReplyToId,
+        hasRepliedRef,
+      };
+    },
+  },
+  messaging: {
+    normalizeTarget: normalizeMatrixMessagingTarget,
+    targetResolver: {
+      looksLikeId: (raw) => {
+        const trimmed = raw.trim();
+        if (!trimmed) {
+          return false;
+        }
+        if (/^(badgerclaw:)?[!#@]/i.test(trimmed)) {
+          return true;
+        }
+        return trimmed.includes(":");
+      },
+      hint: "<room|alias|user>",
+    },
+  },
+  directory: {
+    self: async () => null,
+    listPeers: async ({ cfg, accountId, query, limit }) => {
+      const account = resolveMatrixAccount({ cfg: cfg as CoreConfig, accountId });
+      const q = query?.trim().toLowerCase() || "";
+      const ids = new Set<string>();
+
+      for (const entry of account.config.dm?.allowFrom ?? []) {
+        const raw = String(entry).trim();
+        if (!raw || raw === "*") {
+          continue;
+        }
+        ids.add(raw.replace(/^badgerclaw:/i, ""));
+      }
+
+      for (const entry of account.config.groupAllowFrom ?? []) {
+        const raw = String(entry).trim();
+        if (!raw || raw === "*") {
+          continue;
+        }
+        ids.add(raw.replace(/^badgerclaw:/i, ""));
+      }
+
+      const groups = account.config.groups ?? account.config.rooms ?? {};
+      for (const room of Object.values(groups)) {
+        for (const entry of room.users ?? []) {
+          const raw = String(entry).trim();
+          if (!raw || raw === "*") {
+            continue;
+          }
+          ids.add(raw.replace(/^badgerclaw:/i, ""));
+        }
+      }
+
+      return Array.from(ids)
+        .map((raw) => raw.trim())
+        .filter(Boolean)
+        .map((raw) => {
+          const lowered = raw.toLowerCase();
+          const cleaned = lowered.startsWith("user:") ? raw.slice("user:".length).trim() : raw;
+          if (cleaned.startsWith("@")) {
+            return `user:${cleaned}`;
+          }
+          return cleaned;
+        })
+        .filter((id) => (q ? id.toLowerCase().includes(q) : true))
+        .slice(0, limit && limit > 0 ? limit : undefined)
+        .map((id) => {
+          const raw = id.startsWith("user:") ? id.slice("user:".length) : id;
+          const incomplete = !raw.startsWith("@") || !raw.includes(":");
+          return {
+            kind: "user",
+            id,
+            ...(incomplete ? { name: "incomplete id; expected @user:server" } : {}),
+          };
+        });
+    },
+    listGroups: async ({ cfg, accountId, query, limit }) => {
+      const account = resolveMatrixAccount({ cfg: cfg as CoreConfig, accountId });
+      const q = query?.trim().toLowerCase() || "";
+      const groups = account.config.groups ?? account.config.rooms ?? {};
+      const ids = Object.keys(groups)
+        .map((raw) => raw.trim())
+        .filter((raw) => Boolean(raw) && raw !== "*")
+        .map((raw) => raw.replace(/^badgerclaw:/i, ""))
+        .map((raw) => {
+          const lowered = raw.toLowerCase();
+          if (lowered.startsWith("room:") || lowered.startsWith("channel:")) {
+            return raw;
+          }
+          if (raw.startsWith("!")) {
+            return `room:${raw}`;
+          }
+          return raw;
+        })
+        .filter((id) => (q ? id.toLowerCase().includes(q) : true))
+        .slice(0, limit && limit > 0 ? limit : undefined)
+        .map((id) => ({ kind: "group", id }) as const);
+      return ids;
+    },
+    listPeersLive: async ({ cfg, accountId, query, limit }) =>
+      listMatrixDirectoryPeersLive({ cfg, accountId, query, limit }),
+    listGroupsLive: async ({ cfg, accountId, query, limit }) =>
+      listMatrixDirectoryGroupsLive({ cfg, accountId, query, limit }),
+  },
+  resolver: {
+    resolveTargets: async ({ cfg, inputs, kind, runtime }) =>
+      resolveMatrixTargets({ cfg, inputs, kind, runtime }),
+  },
+  actions: matrixMessageActions,
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg: cfg as CoreConfig,
+        channelKey: "badgerclaw",
+        accountId,
+        name,
+      }),
+    validateInput: ({ input }) => {
+      if (input.useEnv) {
+        return null;
+      }
+      if (!input.homeserver?.trim()) {
+        return "BadgerClaw requires --homeserver";
+      }
+      const accessToken = input.accessToken?.trim();
+      const password = normalizeSecretInputString(input.password);
+      const userId = input.userId?.trim();
+      if (!accessToken && !password) {
+        return "BadgerClaw requires --access-token or --password";
+      }
+      if (!accessToken) {
+        if (!userId) {
+          return "BadgerClaw requires --user-id when using --password";
+        }
+        if (!password) {
+          return "BadgerClaw requires --password when using --user-id";
+        }
+      }
+      return null;
+    },
+    applyAccountConfig: ({ cfg, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg: cfg as CoreConfig,
+        channelKey: "badgerclaw",
+        accountId: DEFAULT_ACCOUNT_ID,
+        name: input.name,
+      });
+      if (input.useEnv) {
+        return {
+          ...namedConfig,
+          channels: {
+            ...namedConfig.channels,
+            badgerclaw: {
+              ...namedConfig.channels?.badgerclaw,
+              enabled: true,
+            },
+          },
+        } as CoreConfig;
+      }
+      return buildMatrixConfigUpdate(namedConfig as CoreConfig, {
+        homeserver: input.homeserver?.trim(),
+        userId: input.userId?.trim(),
+        accessToken: input.accessToken?.trim(),
+        password: normalizeSecretInputString(input.password),
+        deviceName: input.deviceName?.trim(),
+        initialSyncLimit: input.initialSyncLimit,
+      });
+    },
+  },
+  outbound: matrixOutbound,
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: (accounts) => collectStatusIssuesFromLastError("badgerclaw", accounts),
+    buildChannelSummary: ({ snapshot }) =>
+      buildProbeChannelStatusSummary(snapshot, { baseUrl: snapshot.baseUrl ?? null }),
+    probeAccount: async ({ account, timeoutMs, cfg }) => {
+      try {
+        const auth = await resolveMatrixAuth({
+          cfg: cfg as CoreConfig,
+          accountId: account.accountId,
+        });
+        return await probeMatrix({
+          homeserver: auth.homeserver,
+          accessToken: auth.accessToken,
+          userId: auth.userId,
+          timeoutMs,
+        });
+      } catch (err) {
+        return {
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+          elapsedMs: 0,
+        };
+      }
+    },
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      baseUrl: account.homeserver,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      probe,
+      lastProbeAt: runtime?.lastProbeAt ?? null,
+      ...buildTrafficStatusSummary(runtime),
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      ctx.setStatus({
+        accountId: account.accountId,
+        baseUrl: account.homeserver,
+      });
+      ctx.log?.info(`[${account.accountId}] starting provider (${account.homeserver ?? "badgerclaw"})`);
+
+      // Serialize startup: wait for any previous startup to complete import phase.
+      // This works around a race condition with concurrent dynamic imports.
+      //
+      // INVARIANT: The import() below cannot hang because:
+      // 1. It only loads local ESM modules with no circular awaits
+      // 2. Module initialization is synchronous (no top-level await in ./matrix/index.js)
+      // 3. The lock only serializes the import phase, not the provider startup
+      const previousLock = matrixStartupLock;
+      let releaseLock: () => void = () => {};
+      matrixStartupLock = new Promise<void>((resolve) => {
+        releaseLock = resolve;
+      });
+      await previousLock;
+
+      // Lazy import: the monitor pulls the reply pipeline; avoid ESM init cycles.
+      // Wrap in try/finally to ensure lock is released even if import fails.
+      let monitorMatrixProvider: typeof import("./matrix/index.js").monitorMatrixProvider;
+      try {
+        const module = await import("./matrix/index.js");
+        monitorMatrixProvider = module.monitorMatrixProvider;
+      } finally {
+        // Release lock after import completes or fails
+        releaseLock();
+      }
+
+      return monitorMatrixProvider({
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        mediaMaxMb: account.config.mediaMaxMb,
+        initialSyncLimit: account.config.initialSyncLimit,
+        replyToMode: account.config.replyToMode,
+        accountId: account.accountId,
+      });
+    },
+  },
+};

package/src/config-schema.ts

@@ -0,0 +1,62 @@
+import {
+  AllowFromListSchema,
+  buildNestedDmConfigSchema,
+  DmPolicySchema,
+  GroupPolicySchema,
+} from "openclaw/plugin-sdk/compat";
+import { MarkdownConfigSchema, ToolPolicySchema } from "openclaw/plugin-sdk/matrix";
+import { z } from "zod";
+import { buildSecretInputSchema } from "./secret-input.js";
+
+const matrixActionSchema = z
+  .object({
+    reactions: z.boolean().optional(),
+    messages: z.boolean().optional(),
+    pins: z.boolean().optional(),
+    memberInfo: z.boolean().optional(),
+    channelInfo: z.boolean().optional(),
+  })
+  .optional();
+
+const matrixRoomSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    allow: z.boolean().optional(),
+    requireMention: z.boolean().optional(),
+    tools: ToolPolicySchema,
+    autoReply: z.boolean().optional(),
+    users: AllowFromListSchema,
+    skills: z.array(z.string()).optional(),
+    systemPrompt: z.string().optional(),
+  })
+  .optional();
+
+export const MatrixConfigSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  defaultAccount: z.string().optional(),
+  accounts: z.record(z.string(), z.unknown()).optional(),
+  markdown: MarkdownConfigSchema,
+  homeserver: z.string().optional(),
+  userId: z.string().optional(),
+  accessToken: z.string().optional(),
+  password: buildSecretInputSchema().optional(),
+  deviceName: z.string().optional(),
+  initialSyncLimit: z.number().optional(),
+  encryption: z.boolean().optional(),
+  allowlistOnly: z.boolean().optional(),
+  groupPolicy: GroupPolicySchema.optional(),
+  replyToMode: z.enum(["off", "first", "all"]).optional(),
+  threadReplies: z.enum(["off", "inbound", "always"]).optional(),
+  textChunkLimit: z.number().optional(),
+  chunkMode: z.enum(["length", "newline"]).optional(),
+  responsePrefix: z.string().optional(),
+  mediaMaxMb: z.number().optional(),
+  autoJoin: z.enum(["always", "allowlist", "off"]).optional(),
+  autoJoinAllowlist: AllowFromListSchema,
+  groupAllowFrom: AllowFromListSchema,
+  dm: buildNestedDmConfigSchema(),
+  groups: z.object({}).catchall(matrixRoomSchema).optional(),
+  rooms: z.object({}).catchall(matrixRoomSchema).optional(),
+  actions: matrixActionSchema,
+});

package/src/connect.ts

@@ -0,0 +1,17 @@
+export async function redeemPairingCode(code: string): Promise<{
+  homeserver: string;
+  access_token: string;
+  user_id: string;
+  bot_name: string;
+}> {
+  const resp = await fetch("https://api.badger.signout.io/api/v1/pairing/redeem", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ code }),
+  });
+  if (!resp.ok) {
+    const err = await resp.json().catch(() => ({ detail: resp.statusText }));
+    throw new Error(err.detail || "Failed to redeem pairing code");
+  }
+  return resp.json();
+}