Add ez-assistant and kerberos service folders

2026-02-11 14:56:03 -05:00
parent e4e8ae1b87
commit 9ccfb36923
4471 changed files with 746463 additions and 0 deletions
--- a/docker-compose/ez-assistant/docs/broadcast-groups.md
+++ b/docker-compose/ez-assistant/docs/broadcast-groups.md
@@ -0,0 +1,407 @@
+---
+summary: "Broadcast a WhatsApp message to multiple agents"
+read_when:
+  - Configuring broadcast groups
+  - Debugging multi-agent replies in WhatsApp
+status: experimental
+---
+
+# 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 Moltbot 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 Moltbot 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/clawd-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/clawd-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 ~/.clawdbot/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 MoltbotConfig {
+  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](/multi-agent-sandbox-tools)
+- [Routing Configuration](/concepts/channel-routing)
+- [Session Management](/concepts/sessions)