@badgerclaw/connect 1.1.3 → 1.2.1

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,153 @@ 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.
+
+---
+
+## 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
 
 ---
 
-## Troubleshooting
+## 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,
+      "systemPrompt": "You are a helpful AI assistant..."
+    }
+  }
+}
+```
+
+This means:
+- Bot joins any room it's invited to
+- Bot responds to all messages (no @mention required)
+- Bot uses a helpful assistant personality in groups
+
+### Custom Group Personality
+
+By default, the bot uses a generic helpful assistant prompt in groups — **not** your OpenClaw workspace personality (SOUL.md, IDENTITY.md). This prevents workspace personas from causing the bot to stay silent in groups.
+
+To customize the group personality, edit your OpenClaw config:
+
+```bash
+openclaw configure
+```
+
+Or manually edit `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "channels": {
+    "badgerclaw": {
+      "groups": {
+        "*": {
+          "autoReply": true,
+          "systemPrompt": "You are Captain Bot, a pirate AI. Answer in pirate speak."
+        }
+      }
+    }
+  }
+}
+```
+
+### 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"
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## 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
+
+This usually means the bot's system prompt is telling it to stay silent. Check:
+
+1. Your `groups` config has `autoReply: true`
+2. The `systemPrompt` in groups config tells the agent to respond (not stay silent)
+3. If you have a SOUL.md with "stay silent in groups" — the groups `systemPrompt` overrides this, but only if it's set
+
+Fix: Run `openclaw configure` and reconfigure BadgerClaw, or manually add the groups config shown above.
+
+### `/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** for DMs (SOUL.md, IDENTITY.md) but uses the **groups systemPrompt** for group chats. To change the group personality, edit `channels.badgerclaw.groups.*.systemPrompt` in your config.
+
+### Bot keeps saying "NO_REPLY" or stays silent
+
+Your workspace files (SOUL.md) may instruct the agent to stay silent in groups. The groups `systemPrompt` should override this. If it doesn't:
+
+1. Make sure `groups.*.systemPrompt` is set in your config
+2. The prompt should explicitly say to respond to messages
+3. Restart the gateway after config changes
 
 ### "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 +237,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.1.3",
+  "version": "1.2.1",
   "description": "BadgerClaw channel plugin for OpenClaw",
   "type": "module",
   "dependencies": {

package/src/group-mentions.ts

@@ -29,6 +29,48 @@ function resolveMatrixRoomConfigForGroup(params: ChannelGroupContext) {
 }
 
 export function resolveMatrixGroupRequireMention(params: ChannelGroupContext): boolean {
+  // Check per-room config first (set by /bot talk on|off)
+  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 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);
   if (resolved) {
     if (resolved.autoReply === true) {

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

@@ -34,11 +34,40 @@ 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, "🔐 Encryption active — session keys exchanged.");
+      logVerbose(`badgerclaw: sent encryption handshake 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 +104,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

@@ -0,0 +1,200 @@
+import type { MatrixClient } from "@vector-im/matrix-bot-sdk";
+import * as fs from "fs";
+import * as path from "path";
+
+const ROOM_CONFIG_PATH = path.join(
+  process.env.HOME || "/tmp",
+  ".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"));
+  } catch {
+    return {};
+  }
+}
+
+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;
+}
+
+export async function handleBotCommand(params: {
+  client: MatrixClient;
+  roomId: string;
+  senderId: string;
+  body: string;
+  selfUserId: string;
+}): Promise<boolean> {
+  const { client, roomId, senderId, body, selfUserId } = params;
+  const trimmed = body.trim();
+
+  if (!trimmed.startsWith("/bot")) {
+    return false;
+  }
+
+  const parts = trimmed.split(/\s+/);
+  const command = parts[1]?.toLowerCase();
+  const arg = parts[2]?.toLowerCase();
+  const arg2 = parts[3];
+
+  try {
+    switch (command) {
+      case "help": {
+        await client.sendMessage(roomId, {
+          msgtype: "m.text",
+          body: [
+            "🦡 BadgerClaw Bot Commands",
+            "",
+            "━━━ Available Everywhere ━━━",
+            "",
+            "/bot help",
+            "  Show this help message with all available commands.",
+            "  Works in: Any room or DM",
+            "",
+            "/bot talk on",
+            "  Enable auto-reply mode. The bot will respond to every",
+            "  message in this room without needing an @mention.",
+            "  Perfect for 1-on-1 rooms with your AI assistant.",
+            "  Works in: Any room or DM",
+            "",
+            "/bot talk off",
+            "  Disable auto-reply mode. The bot will only respond",
+            "  when @mentioned. Use this in busy group rooms where",
+            "  you don't want the bot responding to everything.",
+            "  Works in: Any room or DM",
+            "",
+            "/bot add <botname>",
+            "  Invite a bot to the current room. The bot username",
+            "  will be @<botname>_bot on this server.",
+            "  Example: /bot add jarvis → invites @jarvis_bot",
+            "  Works in: Any room",
+            "",
+            "━━━ BotBadger DM Only ━━━",
+            "",
+            "/bot new",
+            "  Create a new bot. Starts a guided flow to set up",
+            "  a bot name, username, and generate a pairing code",
+            "  for connecting to an OpenClaw instance.",
+            "  Works in: Direct message with BotBadger only",
+            "",
+            "/bot pair <name>",
+            "  Generate a new pairing code for an existing bot.",
+            "  Use this to connect or reconnect a bot to OpenClaw.",
+            "  Works in: Direct message with BotBadger only",
+            "",
+            "/bot delete <name>",
+            "  Permanently delete a bot and remove it from all rooms.",
+            "  This action cannot be undone.",
+            "  Works in: Direct message with BotBadger only",
+            "",
+            "/bot list",
+            "  List all your bots and their connection status.",
+            "  🟢 Connected — bot is online and responding",
+            "  🔴 Not connected — bot needs pairing",
+            "  Works in: Any room or DM",
+          ].join("\n"),
+        });
+        return true;
+      }
+
+      case "talk": {
+        if (arg === "on") {
+          const config = loadRoomConfig();
+          // 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.",
+          });
+          return true;
+        }
+        if (arg === "off") {
+          const config = loadRoomConfig();
+          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.",
+          });
+          return true;
+        }
+        await client.sendMessage(roomId, {
+          msgtype: "m.text",
+          body: "Usage: /bot talk on  or  /bot talk off",
+        });
+        return true;
+      }
+
+      case "add": {
+        const botName = arg;
+        if (!botName) {
+          await client.sendMessage(roomId, {
+            msgtype: "m.text",
+            body: "Usage: /bot add <botname>",
+          });
+          return true;
+        }
+        const botUserId = `@${botName}_bot:badger.signout.io`;
+        try {
+          await client.inviteUser(botUserId, roomId);
+          await client.sendMessage(roomId, {
+            msgtype: "m.text",
+            body: `✅ Invited ${botUserId} to this room.`,
+          });
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          await client.sendMessage(roomId, {
+            msgtype: "m.text",
+            body: `❌ Failed to invite ${botUserId}: ${msg}`,
+          });
+        }
+        return true;
+      }
+
+      default: {
+        // Unknown /bot command — show help hint
+        await client.sendMessage(roomId, {
+          msgtype: "m.text",
+          body: "Unknown command. Type /bot help for available commands.",
+        });
+        return true;
+      }
+    }
+  } catch (err) {
+    console.error("badgerclaw: bot command error:", err);
+    return true; // Still consumed the command
+  }
+}

package/src/matrix/monitor/handler.ts

@@ -410,6 +410,19 @@ export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParam
         return;
       }
 
+      // Handle /bot commands before anything else
+      if (bodyText.trim().startsWith("/bot")) {
+        const { handleBotCommand } = await import("./bot-commands.js");
+        const handled = await handleBotCommand({
+          client,
+          roomId,
+          senderId,
+          body: bodyText,
+          selfUserId,
+        });
+        if (handled) return;
+      }
+
       const { wasMentioned, hasExplicitMention } = resolveMentions({
         content,
         userId: selfUserId,
@@ -459,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,17 @@ 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 with a helpful assistant prompt.
+            // This prevents the bot from inheriting workspace personas (SOUL.md) that may
+            // tell it to stay silent in groups or reply with NO_REPLY.
+            groups: {
+              "*": {
+                autoReply: true,
+                enabled: true,
+                systemPrompt:
+                  "You are a helpful AI assistant in a BadgerClaw encrypted chat room. Respond to messages directly and helpfully. Be concise and friendly.",
+              },
+            },
             dm: {
               ...next.channels?.badgerclaw?.dm,
               policy: "open",