@badgerclaw/connect 1.2.0 → 1.2.2

package/SETUP.md

@@ -6,7 +6,6 @@ Connect your OpenClaw AI agent to BadgerClaw encrypted chat rooms.
 
 - **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)
 
 ---
 
@@ -14,28 +13,24 @@ Connect your OpenClaw AI agent to BadgerClaw encrypted chat rooms.
 
 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:
+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
-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)
+5. **Copy the pairing code** (BCK-XXXX-XXXX)
 
-> **Need a new code?** Type `/bot pair jarvis` to regenerate.
+> **Need a new code?** Type `/bot pair <name>` to regenerate.
 
 ---
 
@@ -44,38 +39,42 @@ Run /bot pair jarvis to generate a new code.
 On your machine (Mac, PC, Linux, Pi), run:
 
 ```bash
-# From GitHub (current method)
+openclaw plugins install @badgerclaw/connect
+```
+
+Or install from source:
+
+```bash
 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 badgerclaw connect BCK-XXXX-XXXX
+```
+
+Or run the full 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.
+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 to apply the new config:
+Restart the OpenClaw gateway:
 
 ```bash
 openclaw gateway restart
@@ -83,30 +82,189 @@ 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
+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 through BadgerClaw — fully end-to-end encrypted.
+Your OpenClaw agent will receive messages and respond — fully end-to-end encrypted.
 
 ---
 
-## Troubleshooting
+## 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. Great for 1-on-1 rooms. |
+| `/bot talk off` | **Disable auto-reply** — bot only responds when @mentioned. Use in busy group rooms. |
+| `/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
+- **@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 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`
+- 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.
 
-### Need to reconnect
-Run `openclaw configure` again and enter a new pairing code.
+Each code is one-time use. Run `/bot pair <name>` to generate a fresh one.
 
 ---
 
@@ -115,9 +273,9 @@ Run `openclaw configure` again and enter a new pairing code.
 ```
 Your Phone (BadgerClaw App)
      │
-     │ E2EE Messages
+     │ E2EE Messages (Megolm/Olm)
      ▼
-BadgerClaw Server (badger.signout.io)
+BadgerClaw Server (Matrix homeserver)
      │
      │ E2EE Messages
      ▼

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@badgerclaw/connect",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "BadgerClaw channel plugin for OpenClaw",
   "type": "module",
   "dependencies": {
@@ -31,4 +31,4 @@
       "defaultChoice": "npm"
     }
   }
-}
+}

package/src/group-mentions.ts

@@ -31,13 +31,44 @@ function resolveMatrixRoomConfigForGroup(params: ChannelGroupContext) {
 export function resolveMatrixGroupRequireMention(params: ChannelGroupContext): boolean {
   // Check per-room config first (set by /bot talk on|off)
   try {
-    const { getRoomAutoReply } = require("./matrix/monitor/bot-commands.js");
-    const roomId = params.groupId?.trim() ?? "";
-    const roomAutoReply = getRoomAutoReply(roomId);
-    if (roomAutoReply === true) return false;
-    if (roomAutoReply === false) return true;
-  } catch {
-    // bot-commands module not available, fall through
+    const fs = require("fs");
+    const path = require("path");
+    const configPath = path.join(
+      process.env.HOME || "/tmp",
+      ".openclaw/extensions/badgerclaw/room-config.json"
+    );
+    const raw = fs.readFileSync(configPath, "utf-8");
+    const roomConfig = JSON.parse(raw) as Record<string, { autoReply?: boolean }>;
+    const rawGroupId = params.groupId?.trim() ?? "";
+    // Try multiple formats: raw, stripped prefixes, just the room ID part
+    const variants = [
+      rawGroupId,
+      rawGroupId.replace(/^badgerclaw:/, ""),
+      rawGroupId.replace(/^channel:/, ""),
+      rawGroupId.replace(/^room:/, ""),
+    ];
+    // Case-insensitive lookup: OpenClaw may lowercase the groupId while
+    // room-config.json stores original-cased Matrix room IDs
+    const configKeys = Object.keys(roomConfig);
+    for (const variant of variants) {
+      if (!variant) continue;
+      const matchedKey = configKeys.find(
+        (k) => k.toLowerCase() === variant.toLowerCase()
+      );
+      if (matchedKey) {
+        if (roomConfig[matchedKey]?.autoReply === true) {
+          console.log(`[badgerclaw] room-config autoReply=true for ${matchedKey} (lookup=${variant})`);
+          return false;
+        }
+        if (roomConfig[matchedKey]?.autoReply === false) {
+          console.log(`[badgerclaw] room-config autoReply=false for ${matchedKey} (lookup=${variant})`);
+          return true;
+        }
+      }
+    }
+    console.log(`[badgerclaw] room-config: no match for groupId="${rawGroupId}", keys=${configKeys.join(",")}`);
+  } catch (err) {
+    console.log(`[badgerclaw] room-config error: ${err}`);
   }
 
   const resolved = resolveMatrixRoomConfigForGroup(params);

package/src/matrix/monitor/auto-join.ts

@@ -34,11 +34,47 @@ export function registerMatrixAutoJoin(params: {
   }
   autoJoinRegistered.add(client);
 
+  // After joining a room, send a notice in encrypted rooms to force Megolm session rotation.
+  // When the bot joins, other clients may use a cached outbound Megolm session that doesn't
+  // include the bot. Sending a message causes compliant clients to detect the new member and
+  // rotate their session so subsequent messages are decryptable by the bot.
+  async function postJoinEncryptionHandshake(roomId: string) {
+    try {
+      const encryptionState = await client
+        .getRoomStateEvent(roomId, "m.room.encryption", "")
+        .catch(() => null);
+
+      if (!encryptionState) {
+        logVerbose(`badgerclaw: room ${roomId} is not encrypted, skipping handshake`);
+        return;
+      }
+
+      logVerbose(`badgerclaw: room ${roomId} is encrypted, sending notice to trigger key rotation`);
+      await client.sendNotice(
+        roomId,
+        "🔐 Connected — encryption active.\n\n" +
+          "I'll respond when @mentioned. To toggle auto-reply:\n" +
+          "• /bot talk on — I'll respond to every message\n" +
+          "• /bot talk off — I'll only respond when @mentioned\n" +
+          "• /bot help — see all commands",
+      );
+      logVerbose(`badgerclaw: sent encryption handshake + hint notice in room ${roomId}`);
+    } catch (err) {
+      runtime.log?.(`badgerclaw: encryption handshake failed for room ${roomId}: ${String(err)}`);
+    }
+  }
+
   if (autoJoin === "always") {
     // Use the built-in autojoin mixin for "always" mode
     const { AutojoinRoomsMixin } = loadMatrixSdk();
     AutojoinRoomsMixin.setupOnClient(client);
     logVerbose("badgerclaw: auto-join enabled for all invites");
+
+    // AutojoinRoomsMixin handles the join, so listen for room.join to run post-join logic
+    client.on("room.join", async (roomId: string, _joinEvent: unknown) => {
+      logVerbose(`badgerclaw: bot joined room ${roomId} (always mode), running post-join handshake`);
+      await postJoinEncryptionHandshake(roomId);
+    });
     return;
   }
 
@@ -75,6 +111,7 @@ export function registerMatrixAutoJoin(params: {
     try {
       await client.joinRoom(roomId);
       logVerbose(`badgerclaw: joined room ${roomId}`);
+      await postJoinEncryptionHandshake(roomId);
     } catch (err) {
       runtime.error?.(`badgerclaw: failed to join room ${roomId}: ${String(err)}`);
     }

package/src/matrix/monitor/bot-commands.ts

@@ -7,6 +7,12 @@ const ROOM_CONFIG_PATH = path.join(
   ".openclaw/extensions/badgerclaw/room-config.json"
 );
 
+// Session store path for core groupActivation
+const SESSION_STORE_PATH = path.join(
+  process.env.HOME || "/tmp",
+  ".openclaw/agents/main/sessions/sessions.json"
+);
+
 function loadRoomConfig(): Record<string, { autoReply?: boolean }> {
   try {
     return JSON.parse(fs.readFileSync(ROOM_CONFIG_PATH, "utf-8"));
@@ -19,6 +25,22 @@ function saveRoomConfig(config: Record<string, { autoReply?: boolean }>): void {
   fs.writeFileSync(ROOM_CONFIG_PATH, JSON.stringify(config, null, 2));
 }
 
+function setGroupActivation(roomId: string, activation: "always" | "mention"): void {
+  try {
+    const store = JSON.parse(fs.readFileSync(SESSION_STORE_PATH, "utf-8"));
+    // Session key format: agent:main:badgerclaw:channel:!roomid (lowercase)
+    const sessionKey = `agent:main:badgerclaw:channel:${roomId.toLowerCase()}`;
+    if (!store[sessionKey]) {
+      store[sessionKey] = {};
+    }
+    store[sessionKey].groupActivation = activation;
+    fs.writeFileSync(SESSION_STORE_PATH, JSON.stringify(store, null, 2));
+    console.log(`[badgerclaw] set groupActivation=${activation} for ${sessionKey}`);
+  } catch (err) {
+    console.error(`[badgerclaw] failed to set groupActivation: ${err}`);
+  }
+}
+
 export function getRoomAutoReply(roomId: string): boolean | undefined {
   const config = loadRoomConfig();
   return config[roomId]?.autoReply;
@@ -106,8 +128,11 @@ export async function handleBotCommand(params: {
       case "talk": {
         if (arg === "on") {
           const config = loadRoomConfig();
-          config[roomId] = { ...config[roomId], autoReply: true };
+          // Store with lowercase key to match OpenClaw's lowercased groupId
+          const normalizedRoomId = roomId.toLowerCase();
+          config[normalizedRoomId] = { ...config[normalizedRoomId], autoReply: true };
           saveRoomConfig(config);
+          setGroupActivation(roomId, "always");
           await client.sendMessage(roomId, {
             msgtype: "m.text",
             body: "✅ Auto-reply enabled — I'll respond to every message in this room.",
@@ -116,8 +141,10 @@ export async function handleBotCommand(params: {
         }
         if (arg === "off") {
           const config = loadRoomConfig();
-          config[roomId] = { ...config[roomId], autoReply: false };
+          const normalizedRoomId = roomId.toLowerCase();
+          config[normalizedRoomId] = { ...config[normalizedRoomId], autoReply: false };
           saveRoomConfig(config);
+          setGroupActivation(roomId, "mention");
           await client.sendMessage(roomId, {
             msgtype: "m.text",
             body: "✅ Auto-reply disabled — I'll only respond when @mentioned.",

package/src/matrix/monitor/handler.ts

@@ -472,14 +472,39 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
         });
         return;
       }
+      // Check room-config.json first (set by /bot talk on|off) — it takes priority
+      // over the OpenClaw config wildcard entry.
+      const roomConfigJsonAutoReply = (() => {
+        try {
+          const fs = require("fs");
+          const path = require("path");
+          const configPath = path.join(
+            process.env.HOME || "/tmp",
+            ".openclaw/extensions/badgerclaw/room-config.json"
+          );
+          const raw = fs.readFileSync(configPath, "utf-8");
+          const roomCfg = JSON.parse(raw) as Record<string, { autoReply?: boolean }>;
+          const normalizedRoomId = roomId.toLowerCase();
+          const keys = Object.keys(roomCfg);
+          const matchedKey = keys.find((k) => k.toLowerCase() === normalizedRoomId);
+          if (matchedKey && typeof roomCfg[matchedKey]?.autoReply === "boolean") {
+            return roomCfg[matchedKey].autoReply;
+          }
+        } catch { /* ignore */ }
+        return undefined;
+      })();
       const shouldRequireMention = isRoom
-        ? roomConfig?.autoReply === true
+        ? roomConfigJsonAutoReply === true
           ? false
-          : roomConfig?.autoReply === false
+          : roomConfigJsonAutoReply === false
             ? true
-            : typeof roomConfig?.requireMention === "boolean"
-              ? roomConfig?.requireMention
-              : true
+            : roomConfig?.autoReply === true
+              ? false
+              : roomConfig?.autoReply === false
+                ? true
+                : typeof roomConfig?.requireMention === "boolean"
+                  ? roomConfig?.requireMention
+                  : true
         : false;
       const shouldBypassMention =
         allowTextCommands &&

package/src/onboarding.ts

@@ -245,6 +245,16 @@ export const badgerclawOnboardingAdapter: ChannelOnboardingAdapter = {
             autoJoin: "always",
             // Open policy: bot responds in any room it's invited to
             groupPolicy: "open",
+            // Default group config: auto-reply in all rooms.
+            // No systemPrompt override — the bot respects the user's workspace personality
+            // (SOUL.md, IDENTITY.md, etc.). When the bot joins a group, it sends a hint
+            // message about /bot talk on|off so users know how to control it.
+            groups: {
+              "*": {
+                autoReply: true,
+                enabled: true,
+              },
+            },
             dm: {
               ...next.channels?.badgerclaw?.dm,
               policy: "open",