badgerclaw 0.1.7 → 1.4.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,291 @@
+# 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`)
+
+---
+
+## Step 1: Create a Bot in BadgerClaw
+
+Open the BadgerClaw app on your phone.
+
+1. Open any room or DM with BotBadger
+2. Type: `/bot new`
+3. Follow the guided flow to set a bot name and username
+4. BotBadger responds with a pairing code:
+
+```
+🦡 Bot created!
+
+Name: jarvis
+Connect to OpenClaw:
+  openclaw badgerclaw connect BCK-A8F3-X9K2
+
+Code expires in 24 hours.
+```
+
+5. **Copy the pairing code** (BCK-XXXX-XXXX)
+
+> **Need a new code?** Type `/bot pair <name>` to regenerate.
+
+---
+
+## Step 2: Install the BadgerClaw Plugin
+
+On your machine (Mac, PC, Linux, Pi), run:
+
+```bash
+openclaw plugins install @badgerclaw/connect
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/darkstaar4/badgerclaw-plugin.git
+openclaw plugins install ./badgerclaw-plugin
+```
+
+---
+
+## Step 3: Connect with Pairing Code
+
+```bash
+openclaw badgerclaw connect BCK-XXXX-XXXX
+```
+
+Or run the full configure wizard:
+
+```bash
+openclaw configure
+```
+
+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
+- Sets up auto-reply in group chats
+
+---
+
+## Step 4: Start Chatting
+
+Restart the OpenClaw gateway:
+
+```bash
+openclaw gateway restart
+```
+
+Now in the BadgerClaw app:
+
+1. **DM your bot** — find it in your contacts and send a message
+2. **Add to a room** — type `/bot add <name>` 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 — fully end-to-end encrypted.
+
+---
+
+## Bot Commands
+
+Use these commands in any BadgerClaw room or DM where your bot is present.
+
+| Command | Description |
+|---------|-------------|
+| `/bot help` | Show all available commands |
+| `/bot talk on` | **Enable auto-reply** — bot responds to every message without needing an @mention. If multiple bots are in the room, you'll be asked to specify which one. |
+| `/bot talk on @botname` | **Enable auto-reply for a specific bot** — use when multiple bots are in the room. |
+| `/bot talk off` | **Disable auto-reply for ALL bots** — kill switch. All bots in the room go quiet and only respond when @mentioned. |
+| `/bot add <name>` | Invite a bot to the current room (e.g. `/bot add jarvis`) |
+| `/bot list` | List all your bots and their connection status |
+
+### How Auto-Reply Works
+
+- **New installs:** Auto-reply is **ON by default** in all rooms
+- **Per-room toggle:** `/bot talk on` and `/bot talk off` override the default for that specific room
+- **Multi-bot rooms:** If multiple bots are present, `/bot talk on` asks which bot to enable. `/bot talk off` silences all bots at once.
+- **@mentions always work:** Even with auto-reply off, the bot responds when @mentioned
+
+---
+
+## Group Chat Configuration
+
+### Default Behavior
+
+When you install BadgerClaw with a fresh pairing code, the plugin automatically configures:
+
+```json
+{
+  "groupPolicy": "open",
+  "groups": {
+    "*": {
+      "autoReply": true,
+      "enabled": true
+    }
+  }
+}
+```
+
+This means:
+- Bot joins any room it's invited to
+- Bot responds to all messages (no @mention required)
+- Bot uses **your OpenClaw workspace personality** (SOUL.md, IDENTITY.md, etc.) in all conversations — groups and DMs alike
+
+When the bot joins a new encrypted room, it sends a hint message explaining the `/bot talk on|off` commands so room members know how to control it.
+
+### Your Personality, Everywhere
+
+BadgerClaw respects your OpenClaw workspace files. If you've configured a custom personality (SOUL.md), the bot uses that personality in groups and DMs. This means:
+
+- A "pirate assistant" SOUL.md → bot talks like a pirate in groups
+- A "professional COO" SOUL.md → bot acts professional in groups
+- No SOUL.md → bot uses the default helpful assistant behavior
+
+**If your bot stays silent in groups**, your workspace files may include instructions like "stay silent in groups" or "only respond when needed." To fix this:
+
+1. Edit your SOUL.md to allow group responses, OR
+2. Add a group-specific system prompt override:
+
+```json
+{
+  "channels": {
+    "badgerclaw": {
+      "groups": {
+        "*": {
+          "autoReply": true,
+          "systemPrompt": "You are a helpful AI assistant. Always respond to messages in group chats."
+        }
+      }
+    }
+  }
+}
+```
+
+### Per-Room Configuration
+
+You can configure specific rooms differently:
+
+```json
+{
+  "channels": {
+    "badgerclaw": {
+      "groups": {
+        "*": { "autoReply": true },
+        "!specificRoomId:server": {
+          "autoReply": false,
+          "systemPrompt": "Custom prompt for this room only"
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Upgrading from v1.1.x or Earlier
+
+If you installed BadgerClaw before v1.2.0, your config is missing the group auto-reply settings. The bot may not respond in group chats without @mentions.
+
+**Quick fix — run the update command:**
+
+```bash
+openclaw plugins update @badgerclaw/connect
+openclaw configure
+```
+
+Select BadgerClaw and re-enter a pairing code. The new onboarding will add the missing group config automatically.
+
+**Manual fix — if you don't want to re-pair:**
+
+Add this to your `~/.openclaw/openclaw.json` inside `channels.badgerclaw`:
+
+```json
+{
+  "channels": {
+    "badgerclaw": {
+      "groupPolicy": "open",
+      "groups": {
+        "*": {
+          "autoReply": true,
+          "enabled": true
+        }
+      }
+    }
+  }
+}
+```
+
+Then restart: `openclaw gateway restart`
+
+---
+
+## FAQ
+
+### Bot doesn't respond in group chats
+
+1. Send `/bot talk on` in the room to enable auto-reply
+2. Make sure the bot is a member of the room (`/bot add <name>`)
+3. Check OpenClaw is running: `openclaw status`
+
+### Bot shows typing indicator but never replies
+
+Your workspace personality (SOUL.md) may tell the agent to stay silent in groups. BadgerClaw respects your workspace files, so if SOUL.md says "don't respond in groups," the bot won't.
+
+**Fix options:**
+1. Edit your SOUL.md to allow group responses
+2. Add a `systemPrompt` override in `channels.badgerclaw.groups.*` that tells the agent to respond (see Group Chat Configuration above)
+3. Run `openclaw configure` and reconfigure BadgerClaw
+
+### `/bot talk on` doesn't work
+
+After changing bot commands, you may need to restart the gateway:
+
+```bash
+openclaw gateway restart
+```
+
+### Bot responds with wrong personality
+
+The bot uses your **OpenClaw workspace personality** (SOUL.md, IDENTITY.md) for both DMs and groups. To set a different personality for groups only, add a `systemPrompt` in `channels.badgerclaw.groups.*` in your config.
+
+### Bot keeps saying "NO_REPLY" or stays silent
+
+Your workspace files (SOUL.md) instruct the agent to stay silent in groups. BadgerClaw respects your personality — this is intentional.
+
+**To fix:** Add a `systemPrompt` override to your groups config that tells the agent to always respond. See the "Your Personality, Everywhere" section above. Then restart: `openclaw gateway restart`
+
+### "Invalid pairing code"
+
+- Code expires after 24 hours. Run `/bot pair <name>` in the app for a new one.
+- Enter the code exactly as shown (BCK-XXXX-XXXX).
+
+### "Pairing code already redeemed"
+
+Each code is one-time use. Run `/bot pair <name>` to generate a fresh one.
+
+---
+
+## Architecture
+
+```
+Your Phone (BadgerClaw App)
+     │
+     │ E2EE Messages (Megolm/Olm)
+     ▼
+BadgerClaw Server (Matrix homeserver)
+     │
+     │ 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,47 @@
+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 });
+
+    api.registerCli(({ program }) => {
+      const cmd = program.command("badgerclaw").description("BadgerClaw bot management");
+      cmd
+        .command("connect <code>")
+        .description("Connect an OpenClaw instance to a BadgerClaw bot using a pairing code")
+        .action(async (code: string) => {
+          try {
+            const { redeemPairingCode } = await import("./src/connect.js");
+            const result = await redeemPairingCode(code);
+            console.log("\n✅ Connected to BadgerClaw bot!");
+            console.log("   Bot name:   " + result.bot_name);
+            console.log("   Bot user:   " + result.user_id);
+            console.log("   Homeserver: " + result.homeserver);
+            console.log("\nSave these credentials in your OpenClaw config:");
+            console.log("  channels.badgerclaw.accounts.default.userId = " + result.user_id);
+            console.log("  channels.badgerclaw.accounts.default.accessToken = " + result.access_token);
+            console.log("  channels.badgerclaw.accounts.default.homeserver = " + result.homeserver);
+          } catch (err: any) {
+            console.error("\n❌ Failed to connect: " + (err.message || err));
+            process.exit(1);
+          }
+        });
+    }, { commands: ["badgerclaw"] });
+  },
+};
+
+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

@@ -1,39 +1,37 @@
 {
   "name": "badgerclaw",
-  "version": "0.1.7",
-  "description": "BadgerClaw CLI \u2014 one-click bot provisioning",
-  "main": "dist/index.js",
-  "bin": {
-    "badgerclaw": "./dist/index.js"
-  },
-  "files": [
-    "dist/",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/darkstaar4/badgerclaw-cli.git"
-  },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "bugs": {
-    "url": "https://github.com/darkstaar4/badgerclaw-cli/issues"
-  },
-  "homepage": "https://github.com/darkstaar4/badgerclaw-cli#readme",
+  "version": "1.4.0",
+  "description": "BadgerClaw channel plugin for OpenClaw",
+  "type": "module",
   "dependencies": {
-    "axios": "^1.6.0",
-    "chalk": "^4.1.2",
-    "commander": "^12.0.0",
-    "open": "^8.4.2",
-    "ora": "^5.4.1"
+    "@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"
+    }
   },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.3.0"
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
   }
-}
+}

package/scripts/postinstall.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * postinstall.js — patches openclaw package.json exports map to expose
+ * plugin-sdk/compat subpath, which was removed in openclaw >=2026.3.24.
+ * This runs automatically after `npm install` in the plugin directory.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const OPENCLAW_PKG = path.join(
+  path.dirname(require.resolve('openclaw/package.json')),
+  'package.json'
+);
+
+const COMPAT_EXPORT = './plugin-sdk/compat';
+const COMPAT_ENTRY = {
+  types: './dist/plugin-sdk/compat.d.ts',
+  default: './dist/plugin-sdk/compat.js',
+};
+
+try {
+  const pkg = JSON.parse(fs.readFileSync(OPENCLAW_PKG, 'utf-8'));
+  if (!pkg.exports) pkg.exports = {};
+  if (!pkg.exports[COMPAT_EXPORT]) {
+    pkg.exports[COMPAT_EXPORT] = COMPAT_ENTRY;
+    fs.writeFileSync(OPENCLAW_PKG, JSON.stringify(pkg, null, 2));
+    console.log('[badgerclaw] patched openclaw exports map: added plugin-sdk/compat');
+  } else {
+    console.log('[badgerclaw] openclaw exports map already has plugin-sdk/compat');
+  }
+} catch (e) {
+  // Non-fatal — openclaw may not be installed yet
+  console.log('[badgerclaw] postinstall: could not patch openclaw exports map:', e.message);
+}