nodmix 2026.5.25

package/docs/channels/ambient-room-events.md

@@ -0,0 +1,214 @@
+---
+summary: "Let supported group rooms provide quiet context unless the agent sends with the message tool"
+read_when:
+  - Configuring always-on group or channel rooms
+  - You want the agent to watch room chatter without posting final text automatically
+  - Debugging typing and token usage with no visible room message
+title: "Ambient room events"
+sidebarTitle: "Ambient room events"
+---
+
+Ambient room events let Nodmix process unmentioned group or channel chatter as quiet context. The agent can update memory and session state, but the room stays silent unless the agent explicitly calls the `message` tool.
+
+For always-on group chats, this is the recommended mode: combine `messages.groupChat.unmentionedInbound: "room_event"` with `messages.groupChat.visibleReplies: "message_tool"`. Use it when the agent should listen, decide when a reply is useful, and avoid the old prompt pattern of answering `NO_REPLY`.
+
+Supported today: Discord guild channels, Slack channels and private channels, Slack multi-person DMs, and Telegram groups or supergroups. Other group channels keep their existing group behavior unless their channel page says they support ambient room events.
+
+## Recommended setup
+
+Set the global group-chat behavior:
+
+```json5
+{
+  messages: {
+    groupChat: {
+      unmentionedInbound: "room_event",
+      visibleReplies: "message_tool",
+      historyLimit: 50,
+    },
+  },
+}
+```
+
+Then configure the room itself as always-on by disabling mention gating for that room. The channel must still be allowed by its normal `groupPolicy`, room allowlist, and sender allowlist.
+
+After saving the config, the Gateway hot-reloads `messages` settings. Restart only when file watching or config reload is disabled.
+
+## What changes
+
+With `messages.groupChat.unmentionedInbound: "room_event"`:
+
+- unmentioned allowed group or channel messages become quiet room events
+- mentioned messages stay user requests
+- text commands and native commands stay user requests
+- abort or stop requests stay user requests
+- direct messages stay user requests
+
+Room events use strict visible delivery. Final assistant text is private. The agent must call `message(action=send)` to post in the room.
+
+## Discord example
+
+```json5
+{
+  messages: {
+    groupChat: {
+      unmentionedInbound: "room_event",
+      visibleReplies: "message_tool",
+      historyLimit: 50,
+    },
+  },
+  channels: {
+    discord: {
+      groupPolicy: "allowlist",
+      guilds: {
+        "<DISCORD_SERVER_ID>": {
+          requireMention: false,
+          users: ["<YOUR_DISCORD_USER_ID>"],
+        },
+      },
+    },
+  },
+}
+```
+
+Use per-channel Discord config when only one channel should be ambient:
+
+```json5
+{
+  channels: {
+    discord: {
+      guilds: {
+        "<DISCORD_SERVER_ID>": {
+          channels: {
+            "<DISCORD_CHANNEL_ID_OR_NAME>": {
+              allow: true,
+              requireMention: false,
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Slack example
+
+Slack channel allowlists are ID-first. Use channel IDs such as `C12345678`, not `#channel-name`.
+
+```json5
+{
+  messages: {
+    groupChat: {
+      unmentionedInbound: "room_event",
+      visibleReplies: "message_tool",
+      historyLimit: 50,
+    },
+  },
+  channels: {
+    slack: {
+      groupPolicy: "allowlist",
+      channels: {
+        "<SLACK_CHANNEL_ID>": {
+          allow: true,
+          requireMention: false,
+        },
+      },
+    },
+  },
+}
+```
+
+## Telegram example
+
+For Telegram groups, the bot must be able to see normal group messages. If `requireMention: false`, disable BotFather privacy mode or use another Telegram setup that delivers full group traffic to the bot.
+
+```json5
+{
+  messages: {
+    groupChat: {
+      unmentionedInbound: "room_event",
+      visibleReplies: "message_tool",
+      historyLimit: 50,
+    },
+  },
+  channels: {
+    telegram: {
+      groups: {
+        "<TELEGRAM_GROUP_CHAT_ID>": {
+          groupPolicy: "open",
+          requireMention: false,
+        },
+      },
+    },
+  },
+}
+```
+
+Telegram group IDs are usually negative numbers such as `-1001234567890`. Read `chat.id` from `nodmix logs --follow`, forward a group message to an ID helper bot, or inspect Bot API `getUpdates`.
+
+## Agent specific policy
+
+Use an agent override when several agents share the same room but only one should treat unmentioned chatter as ambient context:
+
+```json5
+{
+  messages: {
+    groupChat: {
+      visibleReplies: "message_tool",
+    },
+  },
+  agents: {
+    list: [
+      {
+        id: "main",
+        groupChat: {
+          unmentionedInbound: "room_event",
+          mentionPatterns: ["@nodmix", "nodmix"],
+        },
+      },
+    ],
+  },
+}
+```
+
+The agent-specific `agents.list[].groupChat.unmentionedInbound` value overrides `messages.groupChat.unmentionedInbound` for that agent.
+
+## Visible reply modes
+
+`messages.groupChat.visibleReplies` defaults to `"automatic"` for normal group/channel user requests. Keep that default when you want final assistant text to post visibly without requiring an explicit message-tool call.
+
+For ambient always-on rooms, `messages.groupChat.visibleReplies: "message_tool"` is still recommended, especially with latest-generation, tool-reliable models such as GPT 5.5. It lets the agent decide when to speak by calling the message tool. If the model returns final text without calling the tool, Nodmix keeps that final text private and logs suppressed delivery metadata.
+
+Room events stay strict even when other group requests use automatic replies. Unmentioned ambient room events still require `message(action=send)` for visible output.
+
+## History
+
+`messages.groupChat.historyLimit` controls the global group history default. Channels can override it with `channels.<channel>.historyLimit`, and some channels also support per-account history limits.
+
+Set `historyLimit: 0` to disable group history context.
+
+Supported room-event channels keep recent ambient room messages as context. Discord keeps room-event history until a visible Discord send succeeds, so quiet context is not lost before message-tool delivery.
+
+## Troubleshooting
+
+If the room shows typing or token usage but no visible message:
+
+1. Confirm the room is allowed by the channel allowlist and sender allowlist.
+2. Confirm `requireMention: false` is set at the room level you expect.
+3. Check whether `messages.groupChat.unmentionedInbound` or the agent override is `"room_event"`.
+4. Inspect logs for suppressed final payload metadata or `didSendViaMessagingTool: false`.
+5. For normal group requests, keep or restore `messages.groupChat.visibleReplies: "automatic"` if you want final replies posted automatically. For ambient rooms using `message_tool`, use a model/runtime that reliably calls tools.
+
+If Telegram ambient rooms do not trigger at all, check BotFather privacy mode and verify the Gateway is receiving normal group messages.
+
+If Slack ambient rooms do not trigger, verify the channel key is the Slack channel ID and the app has the required `channels:history` or `groups:history` scope for that room type.
+
+## Related
+
+- [Groups](/channels/groups)
+- [Discord](/channels/discord)
+- [Slack](/channels/slack)
+- [Telegram](/channels/telegram)
+- [Channel troubleshooting](/channels/troubleshooting)
+- [Channel configuration reference](/gateway/config-channels)

package/docs/channels/bot-loop-protection.md

@@ -0,0 +1,131 @@
+---
+summary: "Bot-to-bot loop protection defaults and channel overrides"
+read_when:
+  - Configuring bot-authored channel messages
+  - Tuning bot-to-bot loop protection
+title: "Bot loop protection"
+sidebarTitle: "Bot loop protection"
+---
+
+# Bot loop protection
+
+Nodmix can accept messages written by other bots on channels that support `allowBots`.
+When that path is enabled, pair loop protection prevents two bot identities from
+replying to each other indefinitely.
+
+The guard is enforced by the core channel-turn kernel. Each supporting channel
+maps its own inbound event into generic facts: account or scope, conversation id,
+sender bot id, and receiver bot id. Core then tracks the participant pair in both
+directions, applies a sliding-window budget, and suppresses the pair during a
+cooldown after the budget is exceeded.
+
+## Defaults
+
+Pair loop protection is active when a channel lets bot-authored messages reach
+dispatch. Built-in defaults are:
+
+- `maxEventsPerWindow: 20` - a bot pair can exchange 20 events within the window
+- `windowSeconds: 60` - sliding window length
+- `cooldownSeconds: 60` - suppression time after the pair exceeds the budget
+
+The guard does not affect normal human-authored messages, single-bot deployments,
+self-message filtering, or one-shot bot replies that stay under the budget.
+
+## Configure shared defaults
+
+Set `channels.defaults.botLoopProtection` once to give every supporting channel
+the same baseline. Channel and account overrides can still tune individual
+surfaces.
+
+```json5
+{
+  channels: {
+    defaults: {
+      botLoopProtection: {
+        maxEventsPerWindow: 20,
+        windowSeconds: 60,
+        cooldownSeconds: 60,
+      },
+    },
+  },
+}
+```
+
+Set `enabled: false` only when your channel policy intentionally allows
+bot-to-bot conversations without automatic suppression.
+
+## Override per channel or account
+
+Supporting channels layer their own config over the shared default. Precedence is:
+
+- `channels.<channel>.<room-or-space>.botLoopProtection`, when the channel supports per-conversation overrides
+- `channels.<channel>.accounts.<account>.botLoopProtection`, when the channel supports accounts
+- `channels.<channel>.botLoopProtection`, when the channel supports top-level defaults
+- `channels.defaults.botLoopProtection`
+- built-in defaults
+
+```json5
+{
+  channels: {
+    defaults: {
+      botLoopProtection: {
+        maxEventsPerWindow: 20,
+      },
+    },
+    discord: {
+      botLoopProtection: {
+        maxEventsPerWindow: 8,
+      },
+      accounts: {
+        molty: {
+          allowBots: "mentions",
+          botLoopProtection: {
+            maxEventsPerWindow: 5,
+            cooldownSeconds: 90,
+          },
+        },
+      },
+    },
+    slack: {
+      allowBots: "mentions",
+      botLoopProtection: {
+        maxEventsPerWindow: 8,
+      },
+    },
+    matrix: {
+      allowBots: "mentions",
+      groups: {
+        "!roomid:example.org": {
+          botLoopProtection: {
+            maxEventsPerWindow: 5,
+          },
+        },
+      },
+    },
+    googlechat: {
+      allowBots: true,
+      groups: {
+        "spaces/AAAA": {
+          botLoopProtection: {
+            maxEventsPerWindow: 5,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Channel support
+
+- Discord: native `author.bot` facts, keyed by Discord account, channel, and bot pair.
+- Slack: native `bot_id` facts for accepted bot-authored messages, keyed by Slack account, channel, and bot pair.
+- Matrix: configured Matrix bot accounts, keyed by Matrix account, room, and configured bot pair.
+- Google Chat: native `sender.type=BOT` facts for accepted bot-authored messages, keyed by account, space, and bot pair.
+
+Channels that do not expose a reliable inbound bot identity keep using their
+normal self-message and access-policy filters. They should not opt into this
+guard until they can identify both participants in the bot pair.
+
+See [SDK runtime](/plugins/sdk-runtime#reusable-runtime-utilities) for plugin
+implementation details.