@badgerclaw/connect 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+## 2026.3.13
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.12
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.11
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.10
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.9
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.8-beta.1
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.8
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.7
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.3
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.2
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.1
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.26
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.25
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.24
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.22
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.14
+
+### Features
+
+- Matrix channel plugin with homeserver + user ID auth (access token or password login with device name).
+- Direct messages with pairing/allowlist/open/disabled policies and allowFrom support.
+- Group/room controls: allowlist policy, per-room config, mention gating, auto-reply, per-room skills/system prompts.
+- Threads: replyToMode controls and thread replies (off/inbound/always).
+- Messaging: text chunking, media uploads with size caps, reactions, polls, typing, and message edits/deletes.
+- Actions: read messages, list/remove reactions, pin/unpin/list pins, member info, room info.
+- Auto-join invites with allowlist support.
+- Status + probe reporting for health checks.

package/SETUP.md

@@ -0,0 +1,131 @@
+# BadgerClaw + OpenClaw — Setup Guide
+
+Connect your OpenClaw AI agent to BadgerClaw encrypted chat rooms.
+
+## Prerequisites
+
+- **BadgerClaw iOS app** installed and logged in
+- **OpenClaw** installed on your machine (`npm install -g openclaw`)
+- Both on the same network (not required, just for initial setup)
+
+---
+
+## Step 1: Create a Bot in BadgerClaw
+
+Open the BadgerClaw app on your phone.
+
+1. Open any room or DM
+2. Type: `/bot create <name>`
+   - Example: `/bot create jarvis`
+3. BotBadger responds with:
+
+```
+🦡 Bot created!
+
+Name: jarvis
+ID: @abc123_jarvis_bot:badger.signout.io
+
+Connect to OpenClaw:
+  openclaw plugins install @badgerclaw/connect
+  openclaw badgerclaw connect BCK-A8F3-X9K2
+
+Code expires in 24 hours.
+Run /bot pair jarvis to generate a new code.
+```
+
+4. **Copy the pairing code** (BCK-XXXX-XXXX)
+
+> **Need a new code?** Type `/bot pair jarvis` to regenerate.
+
+---
+
+## Step 2: Install the BadgerClaw Plugin
+
+On your machine (Mac, PC, Linux, Pi), run:
+
+```bash
+# From GitHub (current method)
+git clone https://github.com/darkstaar4/badgerclaw-plugin.git
+openclaw plugins install ./badgerclaw-plugin
+
+# From npm (coming soon)
+# openclaw plugins install @badgerclaw/connect
+```
+
+---
+
+## Step 3: Connect with Pairing Code
+
+Run the OpenClaw configure wizard:
+
+```bash
+openclaw configure
+```
+
+1. Select **BadgerClaw** as your channel
+2. Enter your pairing code: `BCK-XXXX-XXXX`
+3. The plugin automatically:
+   - Validates the code with BadgerClaw servers
+   - Retrieves your bot's credentials
+   - Enables end-to-end encryption
+   - Configures auto-join for room invites
+4. Done! Your agent is connected.
+
+---
+
+## Step 4: Start Chatting
+
+Restart the OpenClaw gateway to apply the new config:
+
+```bash
+openclaw gateway restart
+```
+
+Now in the BadgerClaw app:
+
+1. **DM your bot** — find it in your contacts (`@xxx_jarvis_bot:badger.signout.io`) and send a message
+2. **Add to a room** — type `/bot add @jarvis` in any room
+3. **Add to a Space** — add the bot to any room inside a Space
+
+Your OpenClaw agent will receive messages and respond through BadgerClaw — fully end-to-end encrypted.
+
+---
+
+## Troubleshooting
+
+### "Invalid pairing code"
+- Code may have expired (24h limit). Run `/bot pair <name>` in the app to get a new one.
+- Make sure you're entering the code exactly as shown (BCK-XXXX-XXXX).
+
+### Bot doesn't respond
+1. Check OpenClaw is running: `openclaw status`
+2. Check gateway logs: `openclaw logs --follow`
+3. Verify the BadgerClaw channel is configured: `openclaw channels status`
+
+### "Pairing code already redeemed"
+Each code is one-time use. Run `/bot pair <name>` to generate a fresh one.
+
+### Need to reconnect
+Run `openclaw configure` again and enter a new pairing code.
+
+---
+
+## Architecture
+
+```
+Your Phone (BadgerClaw App)
+     │
+     │ E2EE Messages
+     ▼
+BadgerClaw Server (badger.signout.io)
+     │
+     │ E2EE Messages
+     ▼
+Your Machine (OpenClaw + BadgerClaw Plugin)
+     │
+     │ Agent Processing
+     ▼
+AI Response → Back through the same encrypted path
+```
+
+All messages are end-to-end encrypted. BadgerClaw servers cannot read your conversations.

package/index.ts

@@ -0,0 +1,23 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/matrix";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/matrix";
+import { matrixPlugin } from "./src/channel.js";
+import { ensureMatrixCryptoRuntime } from "./src/matrix/deps.js";
+import { setMatrixRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "badgerclaw",
+  name: "BadgerClaw",
+  description: "BadgerClaw encrypted AI agent channel",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setMatrixRuntime(api.runtime);
+    void ensureMatrixCryptoRuntime({ log: api.logger.info }).catch((err) => {
+      const message = err instanceof Error ? err.message : String(err);
+      api.logger.warn?.(`badgerclaw: crypto runtime bootstrap failed: ${message}`);
+    });
+    api.registerChannel({ plugin: matrixPlugin });
+  },
+};
+
+export { redeemPairingCode } from "./src/connect.js";
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1 @@
+{"id":"badgerclaw","channels":["badgerclaw"],"configSchema":{"type":"object","additionalProperties":false,"properties":{}}}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@badgerclaw/connect",
+  "version": "1.0.0",
+  "description": "BadgerClaw channel plugin for OpenClaw",
+  "type": "module",
+  "dependencies": {
+    "@mariozechner/pi-agent-core": "0.58.0",
+    "@matrix-org/matrix-sdk-crypto-nodejs": "^0.4.0",
+    "@vector-im/matrix-bot-sdk": "0.8.0-element.3",
+    "markdown-it": "14.1.1",
+    "music-metadata": "^11.12.3",
+    "zod": "^4.3.6"
+  },
+  "openclaw": {
+    "extensions": ["./index.ts"],
+    "channel": {
+      "id": "badgerclaw",
+      "label": "BadgerClaw",
+      "selectionLabel": "BadgerClaw (encrypted AI agents)",
+      "docsPath": "/channels/badgerclaw",
+      "docsLabel": "badgerclaw",
+      "blurb": "encrypted AI agent messaging platform",
+      "order": 15,
+      "quickstartAllowFrom": true
+    },
+    "install": {
+      "npmSpec": "@badgerclaw/connect",
+      "localPath": "extensions/badgerclaw",
+      "defaultChoice": "npm"
+    }
+  }
+}

package/src/actions.ts

@@ -0,0 +1,195 @@
+import {
+  createActionGate,
+  readNumberParam,
+  readStringParam,
+  type ChannelMessageActionAdapter,
+  type ChannelMessageActionContext,
+  type ChannelMessageActionName,
+  type ChannelToolSend,
+} from "openclaw/plugin-sdk/matrix";
+import { resolveMatrixAccount } from "./matrix/accounts.js";
+import { handleMatrixAction } from "./tool-actions.js";
+import type { CoreConfig } from "./types.js";
+
+export const matrixMessageActions: ChannelMessageActionAdapter = {
+  listActions: ({ cfg }) => {
+    const account = resolveMatrixAccount({ cfg: cfg as CoreConfig });
+    if (!account.enabled || !account.configured) {
+      return [];
+    }
+    const gate = createActionGate((cfg as CoreConfig).channels?.badgerclaw?.actions);
+    const actions = new Set<ChannelMessageActionName>(["send", "poll"]);
+    if (gate("reactions")) {
+      actions.add("react");
+      actions.add("reactions");
+    }
+    if (gate("messages")) {
+      actions.add("read");
+      actions.add("edit");
+      actions.add("delete");
+    }
+    if (gate("pins")) {
+      actions.add("pin");
+      actions.add("unpin");
+      actions.add("list-pins");
+    }
+    if (gate("memberInfo")) {
+      actions.add("member-info");
+    }
+    if (gate("channelInfo")) {
+      actions.add("channel-info");
+    }
+    return Array.from(actions);
+  },
+  supportsAction: ({ action }) => action !== "poll",
+  extractToolSend: ({ args }): ChannelToolSend | null => {
+    const action = typeof args.action === "string" ? args.action.trim() : "";
+    if (action !== "sendMessage") {
+      return null;
+    }
+    const to = typeof args.to === "string" ? args.to : undefined;
+    if (!to) {
+      return null;
+    }
+    return { to };
+  },
+  handleAction: async (ctx: ChannelMessageActionContext) => {
+    const { action, params, cfg } = ctx;
+    const resolveRoomId = () =>
+      readStringParam(params, "roomId") ??
+      readStringParam(params, "channelId") ??
+      readStringParam(params, "to", { required: true });
+
+    if (action === "send") {
+      const to = readStringParam(params, "to", { required: true });
+      const content = readStringParam(params, "message", {
+        required: true,
+        allowEmpty: true,
+      });
+      const mediaUrl = readStringParam(params, "media", { trim: false });
+      const replyTo = readStringParam(params, "replyTo");
+      const threadId = readStringParam(params, "threadId");
+      return await handleMatrixAction(
+        {
+          action: "sendMessage",
+          to,
+          content,
+          mediaUrl: mediaUrl ?? undefined,
+          replyToId: replyTo ?? undefined,
+          threadId: threadId ?? undefined,
+        },
+        cfg as CoreConfig,
+      );
+    }
+
+    if (action === "react") {
+      const messageId = readStringParam(params, "messageId", { required: true });
+      const emoji = readStringParam(params, "emoji", { allowEmpty: true });
+      const remove = typeof params.remove === "boolean" ? params.remove : undefined;
+      return await handleMatrixAction(
+        {
+          action: "react",
+          roomId: resolveRoomId(),
+          messageId,
+          emoji,
+          remove,
+        },
+        cfg as CoreConfig,
+      );
+    }
+
+    if (action === "reactions") {
+      const messageId = readStringParam(params, "messageId", { required: true });
+      const limit = readNumberParam(params, "limit", { integer: true });
+      return await handleMatrixAction(
+        {
+          action: "reactions",
+          roomId: resolveRoomId(),
+          messageId,
+          limit,
+        },
+        cfg as CoreConfig,
+      );
+    }
+
+    if (action === "read") {
+      const limit = readNumberParam(params, "limit", { integer: true });
+      return await handleMatrixAction(
+        {
+          action: "readMessages",
+          roomId: resolveRoomId(),
+          limit,
+          before: readStringParam(params, "before"),
+          after: readStringParam(params, "after"),
+        },
+        cfg as CoreConfig,
+      );
+    }
+
+    if (action === "edit") {
+      const messageId = readStringParam(params, "messageId", { required: true });
+      const content = readStringParam(params, "message", { required: true });
+      return await handleMatrixAction(
+        {
+          action: "editMessage",
+          roomId: resolveRoomId(),
+          messageId,
+          content,
+        },
+        cfg as CoreConfig,
+      );
+    }
+
+    if (action === "delete") {
+      const messageId = readStringParam(params, "messageId", { required: true });
+      return await handleMatrixAction(
+        {
+          action: "deleteMessage",
+          roomId: resolveRoomId(),
+          messageId,
+        },
+        cfg as CoreConfig,
+      );
+    }
+
+    if (action === "pin" || action === "unpin" || action === "list-pins") {
+      const messageId =
+        action === "list-pins"
+          ? undefined
+          : readStringParam(params, "messageId", { required: true });
+      return await handleMatrixAction(
+        {
+          action:
+            action === "pin" ? "pinMessage" : action === "unpin" ? "unpinMessage" : "listPins",
+          roomId: resolveRoomId(),
+          messageId,
+        },
+        cfg as CoreConfig,
+      );
+    }
+
+    if (action === "member-info") {
+      const userId = readStringParam(params, "userId", { required: true });
+      return await handleMatrixAction(
+        {
+          action: "memberInfo",
+          userId,
+          roomId: readStringParam(params, "roomId") ?? readStringParam(params, "channelId"),
+        },
+        cfg as CoreConfig,
+      );
+    }
+
+    if (action === "channel-info") {
+      return await handleMatrixAction(
+        {
+          action: "channelInfo",
+          roomId: resolveRoomId(),
+        },
+        cfg as CoreConfig,
+      );
+    }
+
+    throw new Error(`Action ${action} is not supported for provider matrix.`);
+  },
+};