@symerian/symi 3.0.20 → 3.0.22

package/docs/channels/broadcast-groups.md

@@ -1,441 +0,0 @@
----
-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 Symi 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 Symi 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, SYMICORE.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/symi-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/symi-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)
-- 🚧 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 ~/.symi/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 SymiConfig {
-  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/sessions)

package/docs/channels/channel-routing.md

@@ -1,112 +0,0 @@
----
-read_when:
-  - Changing channel routing or inbox behavior
-title: "Channel Routing"
----
-
-# Channels & routing
-
-Symi 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
-
-- **AccountId**: per‑channel account instance (when supported).
-- **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:
-
-- Telegram forum topics embed `:topic:<topicId>` in the group key.
-
-Examples:
-
-- `agent:main:telegram:group:-1001234567890:topic:42`
-
-## 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. **Team match** (Slack) via `teamId`.
-4. **Account match** (`accountId` on the channel).
-5. **Channel match** (any account on that channel, `accountId: "*"`).
-6. **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 Symi 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: "~/.symi/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 `~/.symi`):
-
-- `~/.symi/agents/<agentId>/sessions/sessions.json`
-- JSONL transcripts live alongside the store
-
-You can override the store path via `session.store` and `{agentId}` templating.
-
-## 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.