@symerian/symi 3.0.21 → 3.0.22

package/docs/concepts/multi-agent.md

@@ -1,521 +0,0 @@
----
-summary: "Multi-agent routing: isolated agents, channel accounts, and bindings"
-title: Multi-Agent Routing
-read_when: "You want multiple isolated agents (workspaces + auth) in one gateway process."
-status: active
----
-
-# Multi-Agent Routing
-
-Goal: multiple _isolated_ agents (separate workspace + `agentDir` + sessions), plus multiple channel accounts (e.g. two WhatsApps) in one running Gateway. Inbound is routed to an agent via bindings.
-
-## What is “one agent”?
-
-An **agent** is a fully scoped brain with its own:
-
-- **Workspace** (files, AGENTS.md/SYMICORE.md/USER.md, local notes, persona rules).
-- **State directory** (`agentDir`) for auth profiles, model registry, and per-agent config.
-- **Session store** (chat history + routing state) under `~/.symi/agents/<agentId>/sessions`.
-
-Auth profiles are **per-agent**. Each agent reads from its own:
-
-```text
-~/.symi/agents/<agentId>/agent/auth-profiles.json
-```
-
-Main agent credentials are **not** shared automatically. Never reuse `agentDir`
-across agents (it causes auth/session collisions). If you want to share creds,
-copy `auth-profiles.json` into the other agent's `agentDir`.
-
-Skills are per-agent via each workspace’s `skills/` folder, with shared skills
-available from `~/.symi/skills`. See [Skills: per-agent vs shared](/tools/skills#per-agent-vs-shared-skills).
-
-The Gateway can host **one agent** (default) or **many agents** side-by-side.
-
-**Workspace note:** each agent’s workspace is the **default cwd**, not a hard
-sandbox. Relative paths resolve inside the workspace, but absolute paths can
-reach other host locations unless sandboxing is enabled. See
-[Sandboxing](/gateway/sandboxing).
-
-## Paths (quick map)
-
-- Config: `~/.symi/symi.json` (or `SYMI_CONFIG_PATH`)
-- State dir: `~/.symi` (or `SYMI_STATE_DIR`)
-- Workspace: `~/.symi/workspace` (or `~/.symi/workspace-<agentId>`)
-- Agent dir: `~/.symi/agents/<agentId>/agent` (or `agents.list[].agentDir`)
-- Sessions: `~/.symi/agents/<agentId>/sessions`
-
-### Single-agent mode (default)
-
-If you do nothing, Symi runs a single agent:
-
-- `agentId` defaults to **`main`**.
-- Sessions are keyed as `agent:main:<mainKey>`.
-- Workspace defaults to `~/.symi/workspace` (or `~/.symi/workspace-<profile>` when `SYMI_PROFILE` is set).
-- State defaults to `~/.symi/agents/main/agent`.
-
-## Agent helper
-
-Use the agent wizard to add a new isolated agent:
-
-```bash
-symi agents add work
-```
-
-Then add `bindings` (or let the wizard do it) to route inbound messages.
-
-Verify with:
-
-```bash
-symi agents list --bindings
-```
-
-## Quick start
-
-<Steps>
-  <Step title="Create each agent workspace">
-
-Use the wizard or create workspaces manually:
-
-```bash
-symi agents add coding
-symi agents add social
-```
-
-Each agent gets its own workspace with `SYMICORE.md`, `AGENTS.md`, and optional `USER.md`, plus a dedicated `agentDir` and session store under `~/.symi/agents/<agentId>`.
-
-  </Step>
-
-  <Step title="Create channel accounts">
-
-Create one account per agent on your preferred channels:
-
-- Telegram: one bot per agent via BotFather, copy each token.
-- WhatsApp: link each phone number per account.
-
-```bash
-symi channels login --channel whatsapp --account work
-```
-
-  </Step>
-
-  <Step title="Add agents, accounts, and bindings">
-
-Add agents under `agents.list`, channel accounts under `channels.<channel>.accounts`, and connect them with `bindings` (examples below).
-
-  </Step>
-
-  <Step title="Restart and verify">
-
-```bash
-symi gateway restart
-symi agents list --bindings
-symi channels status --probe
-```
-
-  </Step>
-</Steps>
-
-## Multiple agents = multiple people, multiple personalities
-
-With **multiple agents**, each `agentId` becomes a **fully isolated persona**:
-
-- **Different phone numbers/accounts** (per channel `accountId`).
-- **Different personalities** (per-agent workspace files like `AGENTS.md` and `SYMICORE.md`).
-- **Separate auth + sessions** (no cross-talk unless explicitly enabled).
-
-This lets **multiple people** share one Gateway server while keeping their AI “brains” and data isolated.
-
-## One WhatsApp number, multiple people (DM split)
-
-You can route **different WhatsApp DMs** to different agents while staying on **one WhatsApp account**. Match on sender E.164 (like `+15551234567`) with `peer.kind: "direct"`. Replies still come from the same WhatsApp number (no per‑agent sender identity).
-
-Important detail: direct chats collapse to the agent’s **main session key**, so true isolation requires **one agent per person**.
-
-Example:
-
-```json5
-{
-  agents: {
-    list: [
-      { id: "alex", workspace: "~/.symi/workspace-alex" },
-      { id: "mia", workspace: "~/.symi/workspace-mia" },
-    ],
-  },
-  bindings: [
-    {
-      agentId: "alex",
-      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230001" } },
-    },
-    {
-      agentId: "mia",
-      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230002" } },
-    },
-  ],
-  channels: {
-    whatsapp: {
-      dmPolicy: "allowlist",
-      allowFrom: ["+15551230001", "+15551230002"],
-    },
-  },
-}
-```
-
-Notes:
-
-- DM access control is **global per WhatsApp account** (pairing/allowlist), not per agent.
-- For shared groups, bind the group to one agent or use [Broadcast groups](/channels/broadcast-groups).
-
-## Routing rules (how messages pick an agent)
-
-Bindings are **deterministic** and **most-specific wins**:
-
-1. `peer` match (exact DM/group/channel id)
-2. `parentPeer` match (thread inheritance)
-3. `teamId` (Slack)
-4. `accountId` match for a channel
-5. channel-level match (`accountId: "*"`)
-6. fallback to default agent (`agents.list[].default`, else first list entry, default: `main`)
-
-If multiple bindings match in the same tier, the first one in config order wins.
-If a binding sets multiple match fields (for example `peer` + `guildId`), all specified fields are required (`AND` semantics).
-
-## Multiple accounts / phone numbers
-
-Channels that support **multiple accounts** (e.g. WhatsApp) use `accountId` to identify
-each login. Each `accountId` can be routed to a different agent, so one server can host
-multiple phone numbers without mixing sessions.
-
-## Concepts
-
-- `agentId`: one “brain” (workspace, per-agent auth, per-agent session store).
-- `accountId`: one channel account instance (e.g. WhatsApp account `"personal"` vs `"biz"`).
-- `binding`: routes inbound messages to an `agentId` by `(channel, accountId, peer)` and optionally guild/team ids.
-- Direct chats collapse to `agent:<agentId>:<mainKey>` (per-agent “main”; `session.mainKey`).
-
-## Platform examples
-
-```json5
-{
-  agents: {
-    list: [
-      { id: "main", workspace: "~/.symi/workspace-main" },
-      { id: "coding", workspace: "~/.symi/workspace-coding" },
-    ],
-  },
-  bindings: [
-  ],
-  channels: {
-      groupPolicy: "allowlist",
-      accounts: {
-        default: {
-          guilds: {
-            "123456789012345678": {
-              channels: {
-                "222222222222222222": { allow: true, requireMention: false },
-              },
-            },
-          },
-        },
-        coding: {
-          guilds: {
-            "123456789012345678": {
-              channels: {
-                "333333333333333333": { allow: true, requireMention: false },
-              },
-            },
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-Notes:
-
-- Invite each bot to the guild and enable Message Content Intent.
-
-### Telegram bots per agent
-
-```json5
-{
-  agents: {
-    list: [
-      { id: "main", workspace: "~/.symi/workspace-main" },
-      { id: "alerts", workspace: "~/.symi/workspace-alerts" },
-    ],
-  },
-  bindings: [
-    { agentId: "main", match: { channel: "telegram", accountId: "default" } },
-    { agentId: "alerts", match: { channel: "telegram", accountId: "alerts" } },
-  ],
-  channels: {
-    telegram: {
-      accounts: {
-        default: {
-          botToken: "123456:ABC...",
-          dmPolicy: "pairing",
-        },
-        alerts: {
-          botToken: "987654:XYZ...",
-          dmPolicy: "allowlist",
-          allowFrom: ["tg:123456789"],
-        },
-      },
-    },
-  },
-}
-```
-
-Notes:
-
-- Create one bot per agent with BotFather and copy each token.
-- Tokens live in `channels.telegram.accounts.<id>.botToken` (default account can use `TELEGRAM_BOT_TOKEN`).
-
-### WhatsApp numbers per agent
-
-Link each account before starting the gateway:
-
-```bash
-symi channels login --channel whatsapp --account personal
-symi channels login --channel whatsapp --account biz
-```
-
-`~/.symi/symi.json` (JSON5):
-
-```js
-{
-  agents: {
-    list: [
-      {
-        id: "home",
-        default: true,
-        name: "Home",
-        workspace: "~/.symi/workspace-home",
-        agentDir: "~/.symi/agents/home/agent",
-      },
-      {
-        id: "work",
-        name: "Work",
-        workspace: "~/.symi/workspace-work",
-        agentDir: "~/.symi/agents/work/agent",
-      },
-    ],
-  },
-
-  // Deterministic routing: first match wins (most-specific first).
-  bindings: [
-    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
-    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
-
-    // Optional per-peer override (example: send a specific group to work agent).
-    {
-      agentId: "work",
-      match: {
-        channel: "whatsapp",
-        accountId: "personal",
-        peer: { kind: "group", id: "1203630...@g.us" },
-      },
-    },
-  ],
-
-  // Off by default: agent-to-agent messaging must be explicitly enabled + allowlisted.
-  tools: {
-    agentToAgent: {
-      enabled: false,
-      allow: ["home", "work"],
-    },
-  },
-
-  channels: {
-    whatsapp: {
-      accounts: {
-        personal: {
-          // Optional override. Default: ~/.symi/credentials/whatsapp/personal
-          // authDir: "~/.symi/credentials/whatsapp/personal",
-        },
-        biz: {
-          // Optional override. Default: ~/.symi/credentials/whatsapp/biz
-          // authDir: "~/.symi/credentials/whatsapp/biz",
-        },
-      },
-    },
-  },
-}
-```
-
-## Example: WhatsApp daily chat + Telegram deep work
-
-Split by channel: route WhatsApp to a fast everyday agent and Telegram to an Opus agent.
-
-```json5
-{
-  agents: {
-    list: [
-      {
-        id: "chat",
-        name: "Everyday",
-        workspace: "~/.symi/workspace-chat",
-        model: "anthropic/claude-sonnet-4-5",
-      },
-      {
-        id: "opus",
-        name: "Deep Work",
-        workspace: "~/.symi/workspace-opus",
-        model: "anthropic/claude-opus-4-6",
-      },
-    ],
-  },
-  bindings: [
-    { agentId: "chat", match: { channel: "whatsapp" } },
-    { agentId: "opus", match: { channel: "telegram" } },
-  ],
-}
-```
-
-Notes:
-
-- If you have multiple accounts for a channel, add `accountId` to the binding (for example `{ channel: "whatsapp", accountId: "personal" }`).
-- To route a single DM/group to Opus while keeping the rest on chat, add a `match.peer` binding for that peer; peer matches always win over channel-wide rules.
-
-## Example: same channel, one peer to Opus
-
-Keep WhatsApp on the fast agent, but route one DM to Opus:
-
-```json5
-{
-  agents: {
-    list: [
-      {
-        id: "chat",
-        name: "Everyday",
-        workspace: "~/.symi/workspace-chat",
-        model: "anthropic/claude-sonnet-4-5",
-      },
-      {
-        id: "opus",
-        name: "Deep Work",
-        workspace: "~/.symi/workspace-opus",
-        model: "anthropic/claude-opus-4-6",
-      },
-    ],
-  },
-  bindings: [
-    {
-      agentId: "opus",
-      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551234567" } },
-    },
-    { agentId: "chat", match: { channel: "whatsapp" } },
-  ],
-}
-```
-
-Peer bindings always win, so keep them above the channel-wide rule.
-
-## Family agent bound to a WhatsApp group
-
-Bind a dedicated family agent to a single WhatsApp group, with mention gating
-and a tighter tool policy:
-
-```json5
-{
-  agents: {
-    list: [
-      {
-        id: "family",
-        name: "Family",
-        workspace: "~/.symi/workspace-family",
-        identity: { name: "Family Bot" },
-        groupChat: {
-          mentionPatterns: ["@family", "@familybot", "@Family Bot"],
-        },
-        sandbox: {
-          mode: "all",
-          scope: "agent",
-        },
-        tools: {
-          allow: [
-            "exec",
-            "read",
-            "sessions_list",
-            "sessions_history",
-            "sessions_send",
-            "sessions_spawn",
-            "session_status",
-          ],
-          deny: ["write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"],
-        },
-      },
-    ],
-  },
-  bindings: [
-    {
-      agentId: "family",
-      match: {
-        channel: "whatsapp",
-        peer: { kind: "group", id: "120363999999999999@g.us" },
-      },
-    },
-  ],
-}
-```
-
-Notes:
-
-- Tool allow/deny lists are **tools**, not skills. If a skill needs to run a
-  binary, ensure `exec` is allowed and the binary exists in the sandbox.
-- For stricter gating, set `agents.list[].groupChat.mentionPatterns` and keep
-  group allowlists enabled for the channel.
-
-## Per-Agent Sandbox and Tool Configuration
-
-Starting with v2026.1.6, each agent can have its own sandbox and tool restrictions:
-
-```js
-{
-  agents: {
-    list: [
-      {
-        id: "personal",
-        workspace: "~/.symi/workspace-personal",
-        sandbox: {
-          mode: "off",  // No sandbox for personal agent
-        },
-        // No tool restrictions - all tools available
-      },
-      {
-        id: "family",
-        workspace: "~/.symi/workspace-family",
-        sandbox: {
-          mode: "all",     // Always sandboxed
-          scope: "agent",  // One container per agent
-          docker: {
-            // Optional one-time setup after container creation
-            setupCommand: "apt-get update && apt-get install -y git curl",
-          },
-        },
-        tools: {
-          allow: ["read"],                    // Only read tool
-          deny: ["exec", "write", "edit", "apply_patch"],    // Deny others
-        },
-      },
-    ],
-  },
-}
-```
-
-Note: `setupCommand` lives under `sandbox.docker` and runs once on container creation.
-Per-agent `sandbox.docker.*` overrides are ignored when the resolved scope is `"shared"`.
-
-**Benefits:**
-
-- **Security isolation**: Restrict tools for untrusted agents
-- **Resource control**: Sandbox specific agents while keeping others on host
-- **Flexible policies**: Different permissions per agent
-
-Note: `tools.elevated` is **global** and sender-based; it is not configurable per agent.
-If you need per-agent boundaries, use `agents.list[].tools` to deny `exec`.
-For group targeting, use `agents.list[].groupChat.mentionPatterns` so @mentions map cleanly to the intended agent.
-
-See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for detailed examples.

package/docs/concepts/oauth.md

@@ -1,145 +0,0 @@
----
-summary: "OAuth in Symi: token exchange, storage, and multi-account patterns"
-read_when:
-  - You want to understand Symi OAuth end-to-end
-  - You hit token invalidation / logout issues
-  - You want setup-token or OAuth auth flows
-  - You want multiple accounts or profile routing
-title: "OAuth"
----
-
-# OAuth
-
-Symi supports “subscription auth” via OAuth for providers that offer it (notably **OpenAI Codex (ChatGPT OAuth)**). For Anthropic subscriptions, use the **setup-token** flow. This page explains:
-
-- how the OAuth **token exchange** works (PKCE)
-- where tokens are **stored** (and why)
-- how to handle **multiple accounts** (profiles + per-session overrides)
-
-Symi also supports **provider plugins** that ship their own OAuth or API‑key
-flows. Run them via:
-
-```bash
-symi models auth login --provider <id>
-```
-
-## The token sink (why it exists)
-
-OAuth providers commonly mint a **new refresh token** during login/refresh flows. Some providers (or OAuth clients) can invalidate older refresh tokens when a new one is issued for the same user/app.
-
-Practical symptom:
-
-- you log in via Symi _and_ via Claude Code / Codex CLI → one of them randomly gets “logged out” later
-
-To reduce that, Symi treats `auth-profiles.json` as a **token sink**:
-
-- the runtime reads credentials from **one place**
-- we can keep multiple profiles and route them deterministically
-
-## Storage (where tokens live)
-
-Secrets are stored **per-agent**:
-
-- Auth profiles (OAuth + API keys): `~/.symi/agents/<agentId>/agent/auth-profiles.json`
-- Runtime cache (managed automatically; don’t edit): `~/.symi/agents/<agentId>/agent/auth.json`
-
-Legacy import-only file (still supported, but not the main store):
-
-- `~/.symi/credentials/oauth.json` (imported into `auth-profiles.json` on first use)
-
-All of the above also respect `$SYMI_STATE_DIR` (state dir override). Full reference: [/gateway/configuration](/gateway/configuration#auth-storage-oauth--api-keys)
-
-## Anthropic setup-token (subscription auth)
-
-Run `claude setup-token` on any machine, then paste it into Symi:
-
-```bash
-symi models auth setup-token --provider anthropic
-```
-
-If you generated the token elsewhere, paste it manually:
-
-```bash
-symi models auth paste-token --provider anthropic
-```
-
-Verify:
-
-```bash
-symi models status
-```
-
-## OAuth exchange (how login works)
-
-Symi’s interactive login flows are implemented in `@mariozechner/pi-ai` and wired into the wizards/commands.
-
-### Anthropic (Claude Pro/Max) setup-token
-
-Flow shape:
-
-1. run `claude setup-token`
-2. paste the token into Symi
-3. store as a token auth profile (no refresh)
-
-The wizard path is `symi onboard` → auth choice `setup-token` (Anthropic).
-
-### OpenAI Codex (ChatGPT OAuth)
-
-Flow shape (PKCE):
-
-1. generate PKCE verifier/challenge + random `state`
-2. open `https://auth.openai.com/oauth/authorize?...`
-3. try to capture callback on `http://127.0.0.1:1455/auth/callback`
-4. if callback can’t bind (or you’re remote/headless), paste the redirect URL/code
-5. exchange at `https://auth.openai.com/oauth/token`
-6. extract `accountId` from the access token and store `{ access, refresh, expires, accountId }`
-
-Wizard path is `symi onboard` → auth choice `openai-codex`.
-
-## Refresh + expiry
-
-Profiles store an `expires` timestamp.
-
-At runtime:
-
-- if `expires` is in the future → use the stored access token
-- if expired → refresh (under a file lock) and overwrite the stored credentials
-
-The refresh flow is automatic; you generally don't need to manage tokens manually.
-
-## Multiple accounts (profiles) + routing
-
-Two patterns:
-
-### 1) Preferred: separate agents
-
-If you want “personal” and “work” to never interact, use isolated agents (separate sessions + credentials + workspace):
-
-```bash
-symi agents add work
-symi agents add personal
-```
-
-Then configure auth per-agent (wizard) and route chats to the right agent.
-
-### 2) Advanced: multiple profiles in one agent
-
-`auth-profiles.json` supports multiple profile IDs for the same provider.
-
-Pick which profile is used:
-
-- globally via config ordering (`auth.order`)
-- per-session via `/model ...@<profileId>`
-
-Example (session override):
-
-- `/model Opus@anthropic:work`
-
-How to see what profile IDs exist:
-
-- `symi channels list --json` (shows `auth[]`)
-
-Related docs:
-
-- [/concepts/model-failover](/concepts/model-failover) (rotation + cooldown rules)
-- [/tools/slash-commands](/tools/slash-commands) (command surface)