nodmix 2026.5.25

package/docs/channels/index.md

@@ -0,0 +1,64 @@
+---
+summary: "Messaging platforms Nodmix can connect to"
+read_when:
+  - You want to choose a chat channel for Nodmix
+  - You need a quick overview of supported messaging platforms
+title: "Chat channels"
+---
+
+Nodmix can talk to you on any chat app you already use. Each channel connects via the Gateway.
+Text is supported everywhere; media and reactions vary by channel.
+
+## Delivery notes
+
+- Telegram replies that contain markdown image syntax, such as `![alt](url)`,
+  are converted into media replies on the final outbound path when possible.
+- Slack multi-person DMs route as group chats, so group policy, mention
+  behavior, and group-session rules apply to MPIM conversations.
+- WhatsApp setup is install-on-demand: onboarding can show the setup flow before
+  the plugin package is installed, and the Gateway loads the external
+  ClawHub/npm plugin only when the channel is actually active.
+- Channels that accept bot-authored inbound messages can use shared
+  [bot loop protection](/channels/bot-loop-protection) to prevent bot pairs from
+  replying to each other indefinitely.
+- Supported always-on rooms can use [ambient room events](/channels/ambient-room-events)
+  so unmentioned room chatter becomes quiet context unless the agent sends with
+  the `message` tool.
+
+## Supported channels
+
+- [Discord](/channels/discord) - Discord Bot API + Gateway; supports servers, channels, and DMs.
+- [Feishu](/channels/feishu) - Feishu/Lark bot via WebSocket (bundled plugin).
+- [Google Chat](/channels/googlechat) - Google Chat API app via HTTP webhook (downloadable plugin).
+- [iMessage](/channels/imessage) - Native macOS integration via the `imsg` bridge on a signed-in Mac (or SSH wrapper when the Gateway runs elsewhere), including private API actions for replies, tapbacks, effects, attachments, and group management. Preferred for new Nodmix iMessage setups when host permissions and Messages access fit.
+- [IRC](/channels/irc) - Classic IRC servers; channels + DMs with pairing/allowlist controls.
+- [LINE](/channels/line) - LINE Messaging API bot (downloadable plugin).
+- [Matrix](/channels/matrix) - Matrix protocol (downloadable plugin).
+- [Mattermost](/channels/mattermost) - Bot API + WebSocket; channels, groups, DMs (downloadable plugin).
+- [Microsoft Teams](/channels/msteams) - Bot Framework; enterprise support (bundled plugin).
+- [Nextcloud Talk](/channels/nextcloud-talk) - Self-hosted chat via Nextcloud Talk (bundled plugin).
+- [Nostr](/channels/nostr) - Decentralized DMs via NIP-04 (bundled plugin).
+- [QQ Bot](/channels/qqbot) - QQ Bot API; private chat, group chat, and rich media (bundled plugin).
+- [Signal](/channels/signal) - signal-cli; privacy-focused.
+- [Slack](/channels/slack) - Bolt SDK; workspace apps.
+- [Synology Chat](/channels/synology-chat) - Synology NAS Chat via outgoing+incoming webhooks (bundled plugin).
+- [Telegram](/channels/telegram) - Bot API via grammY; supports groups.
+- [Tlon](/channels/tlon) - Urbit-based messenger (bundled plugin).
+- [Twitch](/channels/twitch) - Twitch chat via IRC connection (bundled plugin).
+- [Voice Call](/plugins/voice-call) - Telephony via Plivo or Twilio (plugin, installed separately).
+- [WebChat](/web/webchat) - Gateway WebChat UI over WebSocket.
+- [WeChat](/channels/wechat) - Tencent iLink Bot plugin via QR login; private chats only (external plugin).
+- [WhatsApp](/channels/whatsapp) - Most popular; uses Baileys and requires QR pairing.
+- [Yuanbao](/channels/yuanbao) - Tencent Yuanbao bot (external plugin).
+- [Zalo](/channels/zalo) - Zalo Bot API; Vietnam's popular messenger (bundled plugin).
+- [Zalo Personal](/channels/zalouser) - Zalo personal account via QR login (bundled plugin).
+
+## Notes
+
+- Channels can run simultaneously; configure multiple and Nodmix will route per chat.
+- Fastest setup is usually **Telegram** (simple bot token). WhatsApp requires QR pairing and
+  stores more state on disk.
+- Group behavior varies by channel; see [Groups](/channels/groups).
+- DM pairing and allowlists are enforced for safety; see [Security](/gateway/security).
+- Troubleshooting: [Channel troubleshooting](/channels/troubleshooting).
+- Model providers are documented separately; see [Model Providers](/providers/models).

package/docs/channels/irc.md

@@ -0,0 +1,253 @@
+---
+summary: "IRC plugin setup, access controls, and troubleshooting"
+title: IRC
+read_when:
+  - You want to connect Nodmix to IRC channels or DMs
+  - You are configuring IRC allowlists, group policy, or mention gating
+---
+
+Use IRC when you want Nodmix in classic channels (`#room`) and direct messages.
+IRC ships as a bundled plugin, but it is configured in the main config under `channels.irc`.
+
+## Quick start
+
+1. Enable IRC config in `~/.nodmix/nodmix.json`.
+2. Set at least:
+
+```json5
+{
+  channels: {
+    irc: {
+      enabled: true,
+      host: "irc.example.com",
+      port: 6697,
+      tls: true,
+      nick: "nodmix-bot",
+      channels: ["#nodmix"],
+    },
+  },
+}
+```
+
+Prefer a private IRC server for bot coordination. If you intentionally use a public IRC network, common choices include Libera.Chat, OFTC, and Snoonet. Avoid predictable public channels for bot or swarm backchannel traffic.
+
+3. Start/restart gateway:
+
+```bash
+nodmix gateway run
+```
+
+## Security defaults
+
+- IRC uses raw TCP/TLS sockets outside Nodmix operator-managed forward proxy routing. In deployments that require all egress through that forward proxy, set `channels.irc.enabled=false` unless direct IRC egress is explicitly approved.
+- `channels.irc.dmPolicy` defaults to `"pairing"`.
+- `channels.irc.groupPolicy` defaults to `"allowlist"`.
+- With `groupPolicy="allowlist"`, set `channels.irc.groups` to define allowed channels.
+- Use TLS (`channels.irc.tls=true`) unless you intentionally accept plaintext transport.
+
+## Access control
+
+There are two separate "gates" for IRC channels:
+
+1. **Channel access** (`groupPolicy` + `groups`): whether the bot accepts messages from a channel at all.
+2. **Sender access** (`groupAllowFrom` / per-channel `groups["#channel"].allowFrom`): who is allowed to trigger the bot inside that channel.
+
+Config keys:
+
+- DM allowlist (DM sender access): `channels.irc.allowFrom`
+- Group sender allowlist (channel sender access): `channels.irc.groupAllowFrom`
+- Per-channel controls (channel + sender + mention rules): `channels.irc.groups["#channel"]`
+- `channels.irc.groupPolicy="open"` allows unconfigured channels (**still mention-gated by default**)
+
+Allowlist entries should use stable sender identities (`nick!user@host`).
+Bare nick matching is mutable and only enabled when `channels.irc.dangerouslyAllowNameMatching: true`.
+
+### Common gotcha: `allowFrom` is for DMs, not channels
+
+If you see logs like:
+
+- `irc: drop group sender alice!ident@host (policy=allowlist)`
+
+...it means the sender wasn't allowed for **group/channel** messages. Fix it by either:
+
+- setting `channels.irc.groupAllowFrom` (global for all channels), or
+- setting per-channel sender allowlists: `channels.irc.groups["#channel"].allowFrom`
+
+Example (allow anyone in `#tuirc-dev` to talk to the bot):
+
+```json5
+{
+  channels: {
+    irc: {
+      groupPolicy: "allowlist",
+      groups: {
+        "#tuirc-dev": { allowFrom: ["*"] },
+      },
+    },
+  },
+}
+```
+
+## Reply triggering (mentions)
+
+Even if a channel is allowed (via `groupPolicy` + `groups`) and the sender is allowed, Nodmix defaults to **mention-gating** in group contexts.
+
+That means you may see logs like `drop channel … (missing-mention)` unless the message includes a mention pattern that matches the bot.
+
+To make the bot reply in an IRC channel **without needing a mention**, disable mention gating for that channel:
+
+```json5
+{
+  channels: {
+    irc: {
+      groupPolicy: "allowlist",
+      groups: {
+        "#tuirc-dev": {
+          requireMention: false,
+          allowFrom: ["*"],
+        },
+      },
+    },
+  },
+}
+```
+
+Or to allow **all** IRC channels (no per-channel allowlist) and still reply without mentions:
+
+```json5
+{
+  channels: {
+    irc: {
+      groupPolicy: "open",
+      groups: {
+        "*": { requireMention: false, allowFrom: ["*"] },
+      },
+    },
+  },
+}
+```
+
+## Security note (recommended for public channels)
+
+If you allow `allowFrom: ["*"]` in a public channel, anyone can prompt the bot.
+To reduce risk, restrict tools for that channel.
+
+### Same tools for everyone in the channel
+
+```json5
+{
+  channels: {
+    irc: {
+      groups: {
+        "#tuirc-dev": {
+          allowFrom: ["*"],
+          tools: {
+            deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### Different tools per sender (owner gets more power)
+
+Use `toolsBySender` to apply a stricter policy to `"*"` and a looser one to your nick:
+
+```json5
+{
+  channels: {
+    irc: {
+      groups: {
+        "#tuirc-dev": {
+          allowFrom: ["*"],
+          toolsBySender: {
+            "*": {
+              deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
+            },
+            "id:eigen": {
+              deny: ["gateway", "nodes", "cron"],
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- `toolsBySender` keys should use `id:` for IRC sender identity values:
+  `id:eigen` or `id:eigen!~eigen@174.127.248.171` for stronger matching.
+- Legacy unprefixed keys are still accepted and matched as `id:` only.
+- The first matching sender policy wins; `"*"` is the wildcard fallback.
+
+For more on group access vs mention-gating (and how they interact), see: [/channels/groups](/channels/groups).
+
+## NickServ
+
+To identify with NickServ after connect:
+
+```json5
+{
+  channels: {
+    irc: {
+      nickserv: {
+        enabled: true,
+        service: "NickServ",
+        password: "your-nickserv-password",
+      },
+    },
+  },
+}
+```
+
+Optional one-time registration on connect:
+
+```json5
+{
+  channels: {
+    irc: {
+      nickserv: {
+        register: true,
+        registerEmail: "bot@example.com",
+      },
+    },
+  },
+}
+```
+
+Disable `register` after the nick is registered to avoid repeated REGISTER attempts.
+
+## Environment variables
+
+Default account supports:
+
+- `IRC_HOST`
+- `IRC_PORT`
+- `IRC_TLS`
+- `IRC_NICK`
+- `IRC_USERNAME`
+- `IRC_REALNAME`
+- `IRC_PASSWORD`
+- `IRC_CHANNELS` (comma-separated)
+- `IRC_NICKSERV_PASSWORD`
+- `IRC_NICKSERV_REGISTER_EMAIL`
+
+`IRC_HOST` cannot be set from a workspace `.env`; see [Workspace `.env` files](/gateway/security).
+
+## Troubleshooting
+
+- If the bot connects but never replies in channels, verify `channels.irc.groups` **and** whether mention-gating is dropping messages (`missing-mention`). If you want it to reply without pings, set `requireMention:false` for the channel.
+- If login fails, verify nick availability and server password.
+- If TLS fails on a custom network, verify host/port and certificate setup.
+
+## Related
+
+- [Channels Overview](/channels) — all supported channels
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Security](/gateway/security) — access model and hardening

package/docs/channels/line.md

@@ -0,0 +1,243 @@
+---
+summary: "LINE Messaging API plugin setup, config, and usage"
+read_when:
+  - You want to connect Nodmix to LINE
+  - You need LINE webhook + credential setup
+  - You want LINE-specific message options
+title: LINE
+---
+
+LINE connects to Nodmix via the LINE Messaging API. The plugin runs as a webhook
+receiver on the gateway and uses your channel access token + channel secret for
+authentication.
+
+Status: downloadable plugin. Direct messages, group chats, media, locations, Flex
+messages, template messages, and quick replies are supported. Reactions and threads
+are not supported.
+
+## Install
+
+Install LINE before configuring the channel:
+
+```bash
+nodmix plugins install @nodmix/line
+```
+
+Local checkout (when running from a git repo):
+
+```bash
+nodmix plugins install ./path/to/local/line-plugin
+```
+
+## Setup
+
+1. Create a LINE Developers account and open the Console:
+   [https://developers.line.biz/console/](https://developers.line.biz/console/)
+2. Create (or pick) a Provider and add a **Messaging API** channel.
+3. Copy the **Channel access token** and **Channel secret** from the channel settings.
+4. Enable **Use webhook** in the Messaging API settings.
+5. Set the webhook URL to your gateway endpoint (HTTPS required):
+
+```
+https://gateway-host/line/webhook
+```
+
+The gateway responds to LINE's webhook verification (GET) and acknowledges signed
+inbound events (POST) immediately after signature and payload validation; agent
+processing continues asynchronously.
+If you need a custom path, set `channels.line.webhookPath` or
+`channels.line.accounts.<id>.webhookPath` and update the URL accordingly.
+
+Security note:
+
+- LINE signature verification is body-dependent (HMAC over the raw body), so Nodmix applies strict pre-auth body limits and timeout before verification.
+- Nodmix processes webhook events from the verified raw request bytes. Upstream middleware-transformed `req.body` values are ignored for signature-integrity safety.
+
+## Configure
+
+Minimal config:
+
+```json5
+{
+  channels: {
+    line: {
+      enabled: true,
+      channelAccessToken: "LINE_CHANNEL_ACCESS_TOKEN",
+      channelSecret: "LINE_CHANNEL_SECRET",
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+Public DM config:
+
+```json5
+{
+  channels: {
+    line: {
+      enabled: true,
+      channelAccessToken: "LINE_CHANNEL_ACCESS_TOKEN",
+      channelSecret: "LINE_CHANNEL_SECRET",
+      dmPolicy: "open",
+      allowFrom: ["*"],
+    },
+  },
+}
+```
+
+Env vars (default account only):
+
+- `LINE_CHANNEL_ACCESS_TOKEN`
+- `LINE_CHANNEL_SECRET`
+
+Token/secret files:
+
+```json5
+{
+  channels: {
+    line: {
+      tokenFile: "/path/to/line-token.txt",
+      secretFile: "/path/to/line-secret.txt",
+    },
+  },
+}
+```
+
+`tokenFile` and `secretFile` must point to regular files. Symlinks are rejected.
+
+Multiple accounts:
+
+```json5
+{
+  channels: {
+    line: {
+      accounts: {
+        marketing: {
+          channelAccessToken: "...",
+          channelSecret: "...",
+          webhookPath: "/line/marketing",
+        },
+      },
+    },
+  },
+}
+```
+
+## Access control
+
+Direct messages default to pairing. Unknown senders get a pairing code and their
+messages are ignored until approved.
+
+```bash
+nodmix pairing list line
+nodmix pairing approve line <CODE>
+```
+
+Allowlists and policies:
+
+- `channels.line.dmPolicy`: `pairing | allowlist | open | disabled`
+- `channels.line.allowFrom`: allowlisted LINE user IDs for DMs; `dmPolicy: "open"` requires `["*"]`
+- `channels.line.groupPolicy`: `allowlist | open | disabled`
+- `channels.line.groupAllowFrom`: allowlisted LINE user IDs for groups
+- Per-group overrides: `channels.line.groups.<groupId>.allowFrom`
+- Static sender access groups can be referenced from `allowFrom`, `groupAllowFrom`, and per-group `allowFrom` with `accessGroup:<name>`.
+- Runtime note: if `channels.line` is completely missing, runtime falls back to `groupPolicy="allowlist"` for group checks (even if `channels.defaults.groupPolicy` is set).
+
+LINE IDs are case-sensitive. Valid IDs look like:
+
+- User: `U` + 32 hex chars
+- Group: `C` + 32 hex chars
+- Room: `R` + 32 hex chars
+
+## Message behavior
+
+- Text is chunked at 5000 characters.
+- Markdown formatting is stripped; code blocks and tables are converted into Flex
+  cards when possible.
+- Streaming responses are buffered; LINE receives full chunks with a loading
+  animation while the agent works.
+- Media downloads are capped by `channels.line.mediaMaxMb` (default 10).
+- Inbound media is saved under `~/.nodmix/media/inbound/` before it is passed
+  to the agent, matching the shared media store used by other bundled channel
+  plugins.
+
+## Channel data (rich messages)
+
+Use `channelData.line` to send quick replies, locations, Flex cards, or template
+messages.
+
+```json5
+{
+  text: "Here you go",
+  channelData: {
+    line: {
+      quickReplies: ["Status", "Help"],
+      location: {
+        title: "Office",
+        address: "123 Main St",
+        latitude: 35.681236,
+        longitude: 139.767125,
+      },
+      flexMessage: {
+        altText: "Status card",
+        contents: {
+          /* Flex payload */
+        },
+      },
+      templateMessage: {
+        type: "confirm",
+        text: "Proceed?",
+        confirmLabel: "Yes",
+        confirmData: "yes",
+        cancelLabel: "No",
+        cancelData: "no",
+      },
+    },
+  },
+}
+```
+
+The LINE plugin also ships a `/card` command for Flex message presets:
+
+```
+/card info "Welcome" "Thanks for joining!"
+```
+
+## ACP support
+
+LINE supports ACP (Agent Communication Protocol) conversation bindings:
+
+- `/acp spawn <agent> --bind here` binds the current LINE chat to an ACP session without creating a child thread.
+- Configured ACP bindings and active conversation-bound ACP sessions work on LINE like other conversation channels.
+
+See [ACP agents](/tools/acp-agents) for details.
+
+## Outbound media
+
+The LINE plugin supports sending images, videos, and audio files through the agent message tool. Media is sent via the LINE-specific delivery path with appropriate preview and tracking handling:
+
+- **Images**: sent as LINE image messages with automatic preview generation.
+- **Videos**: sent with explicit preview and content-type handling.
+- **Audio**: sent as LINE audio messages.
+
+Outbound media URLs must be public HTTPS URLs. Nodmix validates the target hostname before handing the URL to LINE and rejects loopback, link-local, and private-network targets.
+
+Generic media sends fall back to the existing image-only route when a LINE-specific path is not available.
+
+## Troubleshooting
+
+- **Webhook verification fails:** ensure the webhook URL is HTTPS and the
+  `channelSecret` matches the LINE console.
+- **No inbound events:** confirm the webhook path matches `channels.line.webhookPath`
+  and that the gateway is reachable from LINE.
+- **Media download errors:** raise `channels.line.mediaMaxMb` if media exceeds the
+  default limit.
+
+## Related
+
+- [Channels Overview](/channels) — all supported channels
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Security](/gateway/security) — access model and hardening

package/docs/channels/location.md

@@ -0,0 +1,71 @@
+---
+summary: "Inbound channel location parsing (Telegram/WhatsApp/Matrix) and context fields"
+read_when:
+  - Adding or modifying channel location parsing
+  - Using location context fields in agent prompts or tools
+title: "Channel location parsing"
+---
+
+Nodmix normalizes shared locations from chat channels into:
+
+- terse coordinate text appended to the inbound body, and
+- structured fields in the auto-reply context payload. Channel-provided labels, addresses, and captions/comments are rendered into the prompt by the shared untrusted metadata JSON block, not inline in the user body.
+
+Currently supported:
+
+- **Telegram** (location pins + venues + live locations)
+- **WhatsApp** (locationMessage + liveLocationMessage)
+- **Matrix** (`m.location` with `geo_uri`)
+
+## Text formatting
+
+Locations are rendered as friendly lines without brackets:
+
+- Pin:
+  - `📍 48.858844, 2.294351 ±12m`
+- Named place:
+  - `📍 48.858844, 2.294351 ±12m`
+- Live share:
+  - `🛰 Live location: 48.858844, 2.294351 ±12m`
+
+If the channel includes a label, address, or caption/comment, it is preserved in the context payload and appears in the prompt as fenced untrusted JSON:
+
+````text
+Location (untrusted metadata):
+```json
+{
+  "latitude": 48.858844,
+  "longitude": 2.294351,
+  "name": "Eiffel Tower",
+  "address": "Champ de Mars, Paris",
+  "caption": "Meet here"
+}
+```
+````
+
+## Context fields
+
+When a location is present, these fields are added to `ctx`:
+
+- `LocationLat` (number)
+- `LocationLon` (number)
+- `LocationAccuracy` (number, meters; optional)
+- `LocationName` (string; optional)
+- `LocationAddress` (string; optional)
+- `LocationSource` (`pin | place | live`)
+- `LocationIsLive` (boolean)
+- `LocationCaption` (string; optional)
+
+The prompt renderer treats `LocationName`, `LocationAddress`, and `LocationCaption` as untrusted metadata and serializes them through the same bounded JSON path used for other channel context.
+
+## Channel notes
+
+- **Telegram**: venues map to `LocationName/LocationAddress`; live locations use `live_period`.
+- **WhatsApp**: `locationMessage.comment` and `liveLocationMessage.caption` populate `LocationCaption`.
+- **Matrix**: `geo_uri` is parsed as a pin location; altitude is ignored and `LocationIsLive` is always false.
+
+## Related
+
+- [Location command (nodes)](/nodes/location-command)
+- [Camera capture](/nodes/camera)
+- [Media understanding](/nodes/media-understanding)