@quantumclaw/quantumclaw 2026.3.22

package/docs/channels/broadcast-groups.md

@@ -0,0 +1,442 @@
+---
+summary: "Broadcast a WhatsApp message to multiple agents"
+read_when:
+  - Configuring broadcast groups
+  - Debugging multi-agent replies in WhatsApp
+status: experimental
+title: "Broadcast Groups"
+---
+
+# Broadcast Groups
+
+**Status:** Experimental  
+**Version:** Added in 2026.1.9
+
+## 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 QuantumClaw would normally reply (for example: on mention, depending on your group settings).
+
+## Use Cases
+
+### 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.
+
+### 2. Multi-Language Support
+
+```
+Group: "International Support"
+Agents:
+  - Agent_EN (responds in English)
+  - Agent_DE (responds in German)
+  - Agent_ES (responds in Spanish)
+```
+
+### 3. Quality Assurance Workflows
+
+```
+Group: "Customer Support"
+Agents:
+  - SupportAgent (provides answer)
+  - QAAgent (reviews quality, only responds if issues found)
+```
+
+### 4. Task Automation
+
+```
+Group: "Project Management"
+Agents:
+  - TaskTracker (updates task database)
+  - TimeLogger (logs time spent)
+  - ReportGenerator (creates summaries)
+```
+
+## 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 QuantumClaw would reply in this chat, it will run all three agents.
+
+### Processing Strategy
+
+Control how agents process messages:
+
+#### Parallel (Default)
+
+All agents process simultaneously:
+
+```json
+{
+  "broadcast": {
+    "strategy": "parallel",
+    "120363403215116621@g.us": ["alfred", "baerbel"]
+  }
+}
+```
+
+#### Sequential
+
+Agents process in order (one waits for previous to finish):
+
+```json
+{
+  "broadcast": {
+    "strategy": "sequential",
+    "120363403215116621@g.us": ["alfred", "baerbel"]
+  }
+}
+```
+
+### 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
+
+1. **Incoming message** arrives in a WhatsApp group
+2. **Broadcast check**: System checks if peer ID is in `broadcast`
+3. **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
+4. **If not in broadcast list**:
+   - Normal routing applies (first matching binding)
+
+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.
+
+### 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"]`:
+
+**Alfred's context:**
+
+```
+Session: agent:alfred:whatsapp:group:120363403215116621@g.us
+History: [user message, alfred's previous responses]
+Workspace: /Users/pascal/quantumclaw-alfred/
+Tools: read, write, exec
+```
+
+**Bärbel's context:**
+
+```
+Session: agent:baerbel:whatsapp:group:120363403215116621@g.us
+History: [user message, baerbel's previous responses]
+Workspace: /Users/pascal/quantumclaw-baerbel/
+Tools: read only
+```
+
+## Best Practices
+
+### 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
+
+### 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" }
+  }
+}
+```
+
+### 3. Configure Different Tool Access
+
+Give agents only the tools they need:
+
+```json
+{
+  "agents": {
+    "reviewer": {
+      "tools": { "allow": ["read", "exec"] } // Read-only
+    },
+    "fixer": {
+      "tools": { "allow": ["read", "write", "edit", "exec"] } // Read-write
+    }
+  }
+}
+```
+
+### 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
+
+### 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
+```
+
+## 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)
+
+**Precedence:** `broadcast` takes priority over `bindings`.
+
+## Troubleshooting
+
+### 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 ~/.quantumclaw/logs/gateway.log | grep broadcast
+```
+
+### Only One Agent Responding
+
+**Cause:** Peer ID might be in `bindings` but not `broadcast`.
+
+**Fix:** Add to broadcast config or remove from bindings.
+
+### Performance Issues
+
+**If slow with many agents:**
+
+- Reduce number of agents per group
+- Use lighter models (sonnet instead of opus)
+- Check sandbox startup time
+
+## Examples
+
+### 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`"
+
+### 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" }
+    ]
+  }
+}
+```
+
+## API Reference
+
+### Config Schema
+
+```typescript
+interface QuantumClawConfig {
+  broadcast?: {
+    strategy?: "parallel" | "sequential";
+    [peerId: string]: string[];
+  };
+}
+```
+
+### Fields
+
+- `strategy` (optional): How to process agents
+  - `"parallel"` (default): All agents process simultaneously
+  - `"sequential"`: Agents process in array order
+- `[peerId]`: WhatsApp group JID, E.164 number, or other peer ID
+  - Value: Array of agent IDs that should process messages
+
+## 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)
+
+## See Also
+
+- [Multi-Agent Configuration](/tools/multi-agent-sandbox-tools)
+- [Routing Configuration](/channels/channel-routing)
+- [Session Management](/concepts/session)

package/docs/channels/channel-routing.md

@@ -0,0 +1,139 @@
+---
+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
+
+QuantumClaw 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**: `whatsapp`, `telegram`, `discord`, `slack`, `signal`, `imessage`, `webchat`.
+- **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.
+
+## Session key shapes (examples)
+
+Direct messages collapse to the agent’s **main** session:
+
+- `agent:<agentId>:<mainKey>` (default: `agent:main:main`)
+
+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,
+QuantumClaw 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, QuantumClaw still records inbound session metadata, but it
+skips updating the main session `lastRoute`.
+
+## 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 QuantumClaw 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: "~/.quantumclaw/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 `~/.quantumclaw`):
+
+- `~/.quantumclaw/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.