nodmix 2026.5.25

package/docs/channels/broadcast-groups.md

@@ -0,0 +1,472 @@
+---
+summary: "Broadcast a WhatsApp message to multiple agents"
+read_when:
+  - Configuring broadcast groups
+  - Debugging multi-agent replies in WhatsApp
+status: experimental
+title: "Broadcast groups"
+sidebarTitle: "Broadcast groups"
+---
+
+<Note>
+**Status:** Experimental. Added in 2026.1.9.
+</Note>
+
+## Overview
+
+Broadcast Groups enable multiple agents to process and respond to the same message simultaneously. This allows you to create specialized agent teams that work together in a single WhatsApp group or DM — all using one phone number.
+
+Current scope: **WhatsApp only** (web channel).
+
+Broadcast groups are evaluated after channel allowlists and group activation rules. In WhatsApp groups, this means broadcasts happen when Nodmix would normally reply (for example: on mention, depending on your group settings).
+
+## Use cases
+
+<AccordionGroup>
+  <Accordion title="1. Specialized agent teams">
+    Deploy multiple agents with atomic, focused responsibilities:
+
+    ```
+    Group: "Development Team"
+    Agents:
+      - CodeReviewer (reviews code snippets)
+      - DocumentationBot (generates docs)
+      - SecurityAuditor (checks for vulnerabilities)
+      - TestGenerator (suggests test cases)
+    ```
+
+    Each agent processes the same message and provides its specialized perspective.
+
+  </Accordion>
+  <Accordion title="2. Multi-language support">
+    ```
+    Group: "International Support"
+    Agents:
+      - Agent_EN (responds in English)
+      - Agent_DE (responds in German)
+      - Agent_ES (responds in Spanish)
+    ```
+  </Accordion>
+  <Accordion title="3. Quality assurance workflows">
+    ```
+    Group: "Customer Support"
+    Agents:
+      - SupportAgent (provides answer)
+      - QAAgent (reviews quality, only responds if issues found)
+    ```
+  </Accordion>
+  <Accordion title="4. Task automation">
+    ```
+    Group: "Project Management"
+    Agents:
+      - TaskTracker (updates task database)
+      - TimeLogger (logs time spent)
+      - ReportGenerator (creates summaries)
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Configuration
+
+### Basic setup
+
+Add a top-level `broadcast` section (next to `bindings`). Keys are WhatsApp peer ids:
+
+- group chats: group JID (e.g. `120363403215116621@g.us`)
+- DMs: E.164 phone number (e.g. `+15551234567`)
+
+```json
+{
+  "broadcast": {
+    "120363403215116621@g.us": ["alfred", "baerbel", "assistant3"]
+  }
+}
+```
+
+**Result:** When Nodmix would reply in this chat, it will run all three agents.
+
+### Processing strategy
+
+Control how agents process messages:
+
+<Tabs>
+  <Tab title="parallel (default)">
+    All agents process simultaneously:
+
+    ```json
+    {
+      "broadcast": {
+        "strategy": "parallel",
+        "120363403215116621@g.us": ["alfred", "baerbel"]
+      }
+    }
+    ```
+
+  </Tab>
+  <Tab title="sequential">
+    Agents process in order (one waits for previous to finish):
+
+    ```json
+    {
+      "broadcast": {
+        "strategy": "sequential",
+        "120363403215116621@g.us": ["alfred", "baerbel"]
+      }
+    }
+    ```
+
+  </Tab>
+</Tabs>
+
+### Complete example
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "code-reviewer",
+        "name": "Code Reviewer",
+        "workspace": "/path/to/code-reviewer",
+        "sandbox": { "mode": "all" }
+      },
+      {
+        "id": "security-auditor",
+        "name": "Security Auditor",
+        "workspace": "/path/to/security-auditor",
+        "sandbox": { "mode": "all" }
+      },
+      {
+        "id": "docs-generator",
+        "name": "Documentation Generator",
+        "workspace": "/path/to/docs-generator",
+        "sandbox": { "mode": "all" }
+      }
+    ]
+  },
+  "broadcast": {
+    "strategy": "parallel",
+    "120363403215116621@g.us": ["code-reviewer", "security-auditor", "docs-generator"],
+    "120363424282127706@g.us": ["support-en", "support-de"],
+    "+15555550123": ["assistant", "logger"]
+  }
+}
+```
+
+## How it works
+
+### Message flow
+
+<Steps>
+  <Step title="Incoming message arrives">
+    A WhatsApp group or DM message arrives.
+  </Step>
+  <Step title="Broadcast check">
+    System checks if peer ID is in `broadcast`.
+  </Step>
+  <Step title="If in broadcast list">
+    - All listed agents process the message.
+    - Each agent has its own session key and isolated context.
+    - Agents process in parallel (default) or sequentially.
+
+  </Step>
+  <Step title="If not in broadcast list">
+    Normal routing applies (first matching binding).
+  </Step>
+</Steps>
+
+<Note>
+Broadcast groups do not bypass channel allowlists or group activation rules (mentions/commands/etc). They only change _which agents run_ when a message is eligible for processing.
+</Note>
+
+### Session isolation
+
+Each agent in a broadcast group maintains completely separate:
+
+- **Session keys** (`agent:alfred:whatsapp:group:120363...` vs `agent:baerbel:whatsapp:group:120363...`)
+- **Conversation history** (agent doesn't see other agents' messages)
+- **Workspace** (separate sandboxes if configured)
+- **Tool access** (different allow/deny lists)
+- **Memory/context** (separate IDENTITY.md, SOUL.md, etc.)
+- **Group context buffer** (recent group messages used for context) is shared per peer, so all broadcast agents see the same context when triggered
+
+This allows each agent to have:
+
+- Different personalities
+- Different tool access (e.g., read-only vs. read-write)
+- Different models (e.g., opus vs. sonnet)
+- Different skills installed
+
+### Example: isolated sessions
+
+In group `120363403215116621@g.us` with agents `["alfred", "baerbel"]`:
+
+<Tabs>
+  <Tab title="Alfred's context">
+    ```
+    Session: agent:alfred:whatsapp:group:120363403215116621@g.us
+    History: [user message, alfred's previous responses]
+    Workspace: /Users/user/nodmix-alfred/
+    Tools: read, write, exec
+    ```
+  </Tab>
+  <Tab title="Bärbel's context">
+    ```
+    Session: agent:baerbel:whatsapp:group:120363403215116621@g.us
+    History: [user message, baerbel's previous responses]
+    Workspace: /Users/user/nodmix-baerbel/
+    Tools: read only
+    ```
+  </Tab>
+</Tabs>
+
+## Best practices
+
+<AccordionGroup>
+  <Accordion title="1. Keep agents focused">
+    Design each agent with a single, clear responsibility:
+
+    ```json
+    {
+      "broadcast": {
+        "DEV_GROUP": ["formatter", "linter", "tester"]
+      }
+    }
+    ```
+
+    ✅ **Good:** Each agent has one job. ❌ **Bad:** One generic "dev-helper" agent.
+
+  </Accordion>
+  <Accordion title="2. Use descriptive names">
+    Make it clear what each agent does:
+
+    ```json
+    {
+      "agents": {
+        "security-scanner": { "name": "Security Scanner" },
+        "code-formatter": { "name": "Code Formatter" },
+        "test-generator": { "name": "Test Generator" }
+      }
+    }
+    ```
+
+  </Accordion>
+  <Accordion title="3. Configure different tool access">
+    Give agents only the tools they need:
+
+    ```json
+    {
+      "agents": {
+        "reviewer": {
+          "tools": { "allow": ["read", "exec"] }
+        },
+        "fixer": {
+          "tools": { "allow": ["read", "write", "edit", "exec"] }
+        }
+      }
+    }
+    ```
+
+    `reviewer` is read-only. `fixer` can read and write.
+
+  </Accordion>
+  <Accordion title="4. Monitor performance">
+    With many agents, consider:
+
+    - Using `"strategy": "parallel"` (default) for speed
+    - Limiting broadcast groups to 5-10 agents
+    - Using faster models for simpler agents
+
+  </Accordion>
+  <Accordion title="5. Handle failures gracefully">
+    Agents fail independently. One agent's error doesn't block others:
+
+    ```
+    Message → [Agent A ✓, Agent B ✗ error, Agent C ✓]
+    Result: Agent A and C respond, Agent B logs error
+    ```
+
+  </Accordion>
+</AccordionGroup>
+
+## Compatibility
+
+### Providers
+
+Broadcast groups currently work with:
+
+- ✅ WhatsApp (implemented)
+- 🚧 Telegram (planned)
+- 🚧 Discord (planned)
+- 🚧 Slack (planned)
+
+### Routing
+
+Broadcast groups work alongside existing routing:
+
+```json
+{
+  "bindings": [
+    {
+      "match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } },
+      "agentId": "alfred"
+    }
+  ],
+  "broadcast": {
+    "GROUP_B": ["agent1", "agent2"]
+  }
+}
+```
+
+- `GROUP_A`: Only alfred responds (normal routing).
+- `GROUP_B`: agent1 AND agent2 respond (broadcast).
+
+<Note>
+**Precedence:** `broadcast` takes priority over `bindings`.
+</Note>
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Agents not responding">
+    **Check:**
+
+    1. Agent IDs exist in `agents.list`.
+    2. Peer ID format is correct (e.g., `120363403215116621@g.us`).
+    3. Agents are not in deny lists.
+
+    **Debug:**
+
+    ```bash
+    tail -f ~/.nodmix/logs/gateway.log | grep broadcast
+    ```
+
+  </Accordion>
+  <Accordion title="Only one agent responding">
+    **Cause:** Peer ID might be in `bindings` but not `broadcast`.
+
+    **Fix:** Add to broadcast config or remove from bindings.
+
+  </Accordion>
+  <Accordion title="Performance issues">
+    If slow with many agents:
+
+    - Reduce number of agents per group.
+    - Use lighter models (sonnet instead of opus).
+    - Check sandbox startup time.
+
+  </Accordion>
+</AccordionGroup>
+
+## Examples
+
+<AccordionGroup>
+  <Accordion title="Example 1: Code review team">
+    ```json
+    {
+      "broadcast": {
+        "strategy": "parallel",
+        "120363403215116621@g.us": [
+          "code-formatter",
+          "security-scanner",
+          "test-coverage",
+          "docs-checker"
+        ]
+      },
+      "agents": {
+        "list": [
+          {
+            "id": "code-formatter",
+            "workspace": "~/agents/formatter",
+            "tools": { "allow": ["read", "write"] }
+          },
+          {
+            "id": "security-scanner",
+            "workspace": "~/agents/security",
+            "tools": { "allow": ["read", "exec"] }
+          },
+          {
+            "id": "test-coverage",
+            "workspace": "~/agents/testing",
+            "tools": { "allow": ["read", "exec"] }
+          },
+          { "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } }
+        ]
+      }
+    }
+    ```
+
+    **User sends:** Code snippet.
+
+    **Responses:**
+
+    - code-formatter: "Fixed indentation and added type hints"
+    - security-scanner: "⚠️ SQL injection vulnerability in line 12"
+    - test-coverage: "Coverage is 45%, missing tests for error cases"
+    - docs-checker: "Missing docstring for function `process_data`"
+
+  </Accordion>
+  <Accordion title="Example 2: Multi-language support">
+    ```json
+    {
+      "broadcast": {
+        "strategy": "sequential",
+        "+15555550123": ["detect-language", "translator-en", "translator-de"]
+      },
+      "agents": {
+        "list": [
+          { "id": "detect-language", "workspace": "~/agents/lang-detect" },
+          { "id": "translator-en", "workspace": "~/agents/translate-en" },
+          { "id": "translator-de", "workspace": "~/agents/translate-de" }
+        ]
+      }
+    }
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## API reference
+
+### Config schema
+
+```typescript
+interface NodmixConfig {
+  broadcast?: {
+    strategy?: "parallel" | "sequential";
+    [peerId: string]: string[];
+  };
+}
+```
+
+### Fields
+
+<ParamField path="strategy" type='"parallel" | "sequential"' default='"parallel"'>
+  How to process agents. `parallel` runs all agents simultaneously; `sequential` runs them in array order.
+</ParamField>
+<ParamField path="[peerId]" type="string[]">
+  WhatsApp group JID, E.164 number, or other peer ID. Value is the array of agent IDs that should process messages.
+</ParamField>
+
+## Limitations
+
+1. **Max agents:** No hard limit, but 10+ agents may be slow.
+2. **Shared context:** Agents don't see each other's responses (by design).
+3. **Message ordering:** Parallel responses may arrive in any order.
+4. **Rate limits:** All agents count toward WhatsApp rate limits.
+
+## Future enhancements
+
+Planned features:
+
+- [ ] Shared context mode (agents see each other's responses)
+- [ ] Agent coordination (agents can signal each other)
+- [ ] Dynamic agent selection (choose agents based on message content)
+- [ ] Agent priorities (some agents respond before others)
+
+## Related
+
+- [Channel routing](/channels/channel-routing)
+- [Groups](/channels/groups)
+- [Multi-agent sandbox tools](/tools/multi-agent-sandbox-tools)
+- [Pairing](/channels/pairing)
+- [Session management](/concepts/session)

package/docs/channels/channel-routing.md

@@ -0,0 +1,162 @@
+---
+summary: "Routing rules per channel (WhatsApp, Telegram, Discord, Slack) and shared context"
+read_when:
+  - Changing channel routing or inbox behavior
+title: "Channel routing"
+---
+
+# Channels & routing
+
+Nodmix routes replies **back to the channel where a message came from**. The
+model does not choose a channel; routing is deterministic and controlled by the
+host configuration.
+
+## Key terms
+
+- **Channel**: `telegram`, `whatsapp`, `discord`, `irc`, `googlechat`, `slack`, `signal`, `imessage`, `line`, plus plugin channels. `webchat` is the internal WebChat UI channel and is not a configurable outbound channel.
+- **AccountId**: per-channel account instance (when supported).
+- Optional channel default account: `channels.<channel>.defaultAccount` chooses
+  which account is used when an outbound path does not specify `accountId`.
+  - In multi-account setups, set an explicit default (`defaultAccount` or `accounts.default`) when two or more accounts are configured. Without it, fallback routing may pick the first normalized account ID.
+- **AgentId**: an isolated workspace + session store ("brain").
+- **SessionKey**: the bucket key used to store context and control concurrency.
+
+## Outbound target prefixes
+
+Explicit outbound targets may include a provider prefix, such as `telegram:123` or `tg:123`. Core treats that prefix as a channel-selection hint only when the selected channel is `last` or otherwise unresolved, and only when the loaded plugin advertises that prefix. If the caller already selected an explicit channel, the provider prefix must match that channel; cross-channel combinations such as WhatsApp delivery to `telegram:123` fail before plugin-specific target normalization.
+
+Target-kind and service prefixes such as `channel:<id>`, `user:<id>`, `room:<id>`, `thread:<id>`, `imessage:<handle>`, and `sms:<number>` stay inside the selected channel's grammar. They do not select the provider by themselves.
+
+## Session key shapes (examples)
+
+Direct messages collapse to the agent's **main** session by default:
+
+- `agent:<agentId>:<mainKey>` (default: `agent:main:main`)
+
+Even when direct-message conversation history is shared with main, sandbox and
+tool policy use a derived per-account direct-chat runtime key for external DMs
+so channel-originated messages are not treated like local main-session runs.
+
+Groups and channels remain isolated per channel:
+
+- Groups: `agent:<agentId>:<channel>:group:<id>`
+- Channels/rooms: `agent:<agentId>:<channel>:channel:<id>`
+
+Threads:
+
+- Slack/Discord threads append `:thread:<threadId>` to the base key.
+- Telegram forum topics embed `:topic:<topicId>` in the group key.
+
+Examples:
+
+- `agent:main:telegram:group:-1001234567890:topic:42`
+- `agent:main:discord:channel:123456:thread:987654`
+
+## Main DM route pinning
+
+When `session.dmScope` is `main`, direct messages may share one main session.
+To prevent the session's `lastRoute` from being overwritten by non-owner DMs,
+Nodmix infers a pinned owner from `allowFrom` when all of these are true:
+
+- `allowFrom` has exactly one non-wildcard entry.
+- The entry can be normalized to a concrete sender ID for that channel.
+- The inbound DM sender does not match that pinned owner.
+
+In that mismatch case, Nodmix still records inbound session metadata, but it
+skips updating the main session `lastRoute`.
+
+## Guarded inbound recording
+
+Channel plugins can mark an inbound session record as `createIfMissing: false`
+when a guarded path must not create a new Nodmix session. In that mode,
+Nodmix may update metadata and `lastRoute` for an existing session, but it
+does not create a route-only session entry just because a message was observed.
+
+## Routing rules (how an agent is chosen)
+
+Routing picks **one agent** for each inbound message:
+
+1. **Exact peer match** (`bindings` with `peer.kind` + `peer.id`).
+2. **Parent peer match** (thread inheritance).
+3. **Guild + roles match** (Discord) via `guildId` + `roles`.
+4. **Guild match** (Discord) via `guildId`.
+5. **Team match** (Slack) via `teamId`.
+6. **Account match** (`accountId` on the channel).
+7. **Channel match** (any account on that channel, `accountId: "*"`).
+8. **Default agent** (`agents.list[].default`, else first list entry, fallback to `main`).
+
+When a binding includes multiple match fields (`peer`, `guildId`, `teamId`, `roles`), **all provided fields must match** for that binding to apply.
+
+The matched agent determines which workspace and session store are used.
+
+## Broadcast groups (run multiple agents)
+
+Broadcast groups let you run **multiple agents** for the same peer **when Nodmix would normally reply** (for example: in WhatsApp groups, after mention/activation gating).
+
+Config:
+
+```json5
+{
+  broadcast: {
+    strategy: "parallel",
+    "120363403215116621@g.us": ["alfred", "baerbel"],
+    "+15555550123": ["support", "logger"],
+  },
+}
+```
+
+See: [Broadcast Groups](/channels/broadcast-groups).
+
+## Config overview
+
+- `agents.list`: named agent definitions (workspace, model, etc.).
+- `bindings`: map inbound channels/accounts/peers to agents.
+
+Example:
+
+```json5
+{
+  agents: {
+    list: [{ id: "support", name: "Support", workspace: "~/.nodmix/workspace-support" }],
+  },
+  bindings: [
+    { match: { channel: "slack", teamId: "T123" }, agentId: "support" },
+    { match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" },
+  ],
+}
+```
+
+## Session storage
+
+Session stores live under the state directory (default `~/.nodmix`):
+
+- `~/.nodmix/agents/<agentId>/sessions/sessions.json`
+- JSONL transcripts live alongside the store
+
+You can override the store path via `session.store` and `{agentId}` templating.
+
+Gateway and ACP session discovery also scans disk-backed agent stores under the
+default `agents/` root and under templated `session.store` roots. Discovered
+stores must stay inside that resolved agent root and use a regular
+`sessions.json` file. Symlinks and out-of-root paths are ignored.
+
+## WebChat behavior
+
+WebChat attaches to the **selected agent** and defaults to the agent's main
+session. Because of this, WebChat lets you see cross-channel context for that
+agent in one place.
+
+## Reply context
+
+Inbound replies include:
+
+- `ReplyToId`, `ReplyToBody`, and `ReplyToSender` when available.
+- Quoted context is appended to `Body` as a `[Replying to ...]` block.
+
+This is consistent across channels.
+
+## Related
+
+- [Groups](/channels/groups)
+- [Broadcast groups](/channels/broadcast-groups)
+- [Pairing](/channels/pairing)