@symerian/symi 3.0.21 → 3.0.22

package/docs/channels/imessage.md

@@ -1,366 +0,0 @@
----
-summary: "Legacy iMessage support via imsg (JSON-RPC over stdio). New setups should use BlueBubbles."
-read_when:
-  - Setting up iMessage support
-  - Debugging iMessage send/receive
-title: "iMessage"
----
-
-# iMessage (legacy: imsg)
-
-<Warning>
-For new iMessage deployments, use <a href="/channels/bluebubbles">BlueBubbles</a>.
-
-The `imsg` integration is legacy and may be removed in a future release.
-</Warning>
-
-Status: legacy external CLI integration. Gateway spawns `imsg rpc` and communicates over JSON-RPC on stdio (no separate daemon/port).
-
-<CardGroup cols={3}>
-  <Card title="BlueBubbles (recommended)" icon="message-circle" href="/channels/bluebubbles">
-    Preferred iMessage path for new setups.
-  </Card>
-  <Card title="Pairing" icon="link" href="/channels/pairing">
-    iMessage DMs default to pairing mode.
-  </Card>
-  <Card title="Configuration reference" icon="settings" href="/gateway/configuration-reference#imessage">
-    Full iMessage field reference.
-  </Card>
-</CardGroup>
-
-## Onboarding
-
-<Tabs>
-  <Tab title="Local Mac (fast path)">
-    <Steps>
-      <Step title="Install and verify imsg">
-
-```bash
-brew install steipete/tap/imsg
-imsg rpc --help
-```
-
-      </Step>
-
-      <Step title="Configure Symi">
-
-```json5
-{
-  channels: {
-    imessage: {
-      enabled: true,
-      cliPath: "/usr/local/bin/imsg",
-      dbPath: "/Users/<you>/Library/Messages/chat.db",
-    },
-  },
-}
-```
-
-      </Step>
-
-      <Step title="Start gateway">
-
-```bash
-symi gateway
-```
-
-      </Step>
-
-      <Step title="Approve first DM pairing (default dmPolicy)">
-
-```bash
-symi pairing list imessage
-symi pairing approve imessage <CODE>
-```
-
-        Pairing requests expire after 1 hour.
-      </Step>
-    </Steps>
-
-  </Tab>
-
-  <Tab title="Remote Mac over SSH">
-    Symi only requires a stdio-compatible `cliPath`, so you can point `cliPath` at a wrapper script that SSHes to a remote Mac and runs `imsg`.
-
-```bash
-#!/usr/bin/env bash
-exec ssh -T gateway-host imsg "$@"
-```
-
-    Recommended config when attachments are enabled:
-
-```json5
-{
-  channels: {
-    imessage: {
-      enabled: true,
-      cliPath: "~/.symi/scripts/imsg-ssh",
-      remoteHost: "user@gateway-host", // used for SCP attachment fetches
-      includeAttachments: true,
-      // Optional: override allowed attachment roots.
-      // Defaults include /Users/*/Library/Messages/Attachments
-      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
-      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
-    },
-  },
-}
-```
-
-    If `remoteHost` is not set, Symi attempts to auto-detect it by parsing the SSH wrapper script.
-    `remoteHost` must be `host` or `user@host` (no spaces or SSH options).
-    Symi uses strict host-key checking for SCP, so the relay host key must already exist in `~/.ssh/known_hosts`.
-    Attachment paths are validated against allowed roots (`attachmentRoots` / `remoteAttachmentRoots`).
-
-  </Tab>
-</Tabs>
-
-## Requirements and permissions (macOS)
-
-- Messages must be signed in on the Mac running `imsg`.
-- Full Disk Access is required for the process context running Symi/`imsg` (Messages DB access).
-- Automation permission is required to send messages through Messages.app.
-
-<Tip>
-Permissions are granted per process context. If gateway runs headless (LaunchAgent/SSH), run a one-time interactive command in that same context to trigger prompts:
-
-```bash
-imsg chats --limit 1
-# or
-imsg send <handle> "test"
-```
-
-</Tip>
-
-## Access control and routing
-
-<Tabs>
-  <Tab title="DM policy">
-    `channels.imessage.dmPolicy` controls direct messages:
-
-    - `pairing` (default)
-    - `allowlist`
-    - `open` (requires `allowFrom` to include `"*"`)
-    - `disabled`
-
-    Allowlist field: `channels.imessage.allowFrom`.
-
-    Allowlist entries can be handles or chat targets (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`).
-
-  </Tab>
-
-  <Tab title="Group policy + mentions">
-    `channels.imessage.groupPolicy` controls group handling:
-
-    - `allowlist` (default when configured)
-    - `open`
-    - `disabled`
-
-    Group sender allowlist: `channels.imessage.groupAllowFrom`.
-
-    Runtime fallback: if `groupAllowFrom` is unset, iMessage group sender checks fall back to `allowFrom` when available.
-
-    Mention gating for groups:
-
-    - iMessage has no native mention metadata
-    - mention detection uses regex patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
-    - with no configured patterns, mention gating cannot be enforced
-
-    Control commands from authorized senders can bypass mention gating in groups.
-
-  </Tab>
-
-  <Tab title="Sessions and deterministic replies">
-    - DMs use direct routing; groups use group routing.
-    - With default `session.dmScope=main`, iMessage DMs collapse into the agent main session.
-    - Group sessions are isolated (`agent:<agentId>:imessage:group:<chat_id>`).
-    - Replies route back to iMessage using originating channel/target metadata.
-
-    Group-ish thread behavior:
-
-    Some multi-participant iMessage threads can arrive with `is_group=false`.
-    If that `chat_id` is explicitly configured under `channels.imessage.groups`, Symi treats it as group traffic (group gating + group session isolation).
-
-  </Tab>
-</Tabs>
-
-## Deployment patterns
-
-<AccordionGroup>
-  <Accordion title="Dedicated bot macOS user (separate iMessage identity)">
-    Use a dedicated Apple ID and macOS user so bot traffic is isolated from your personal Messages profile.
-
-    Typical flow:
-
-    1. Create/sign in a dedicated macOS user.
-    2. Sign into Messages with the bot Apple ID in that user.
-    3. Install `imsg` in that user.
-    4. Create SSH wrapper so Symi can run `imsg` in that user context.
-    5. Point `channels.imessage.accounts.<id>.cliPath` and `.dbPath` to that user profile.
-
-    First run may require GUI approvals (Automation + Full Disk Access) in that bot user session.
-
-  </Accordion>
-
-  <Accordion title="Remote Mac over Tailscale (example)">
-    Common topology:
-
-    - gateway runs on Linux/VM
-    - iMessage + `imsg` runs on a Mac in your tailnet
-    - `cliPath` wrapper uses SSH to run `imsg`
-    - `remoteHost` enables SCP attachment fetches
-
-    Example:
-
-```json5
-{
-  channels: {
-    imessage: {
-      enabled: true,
-      cliPath: "~/.symi/scripts/imsg-ssh",
-      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
-      includeAttachments: true,
-      dbPath: "/Users/bot/Library/Messages/chat.db",
-    },
-  },
-}
-```
-
-```bash
-#!/usr/bin/env bash
-exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
-```
-
-    Use SSH keys so both SSH and SCP are non-interactive.
-    Ensure the host key is trusted first (for example `ssh bot@mac-mini.tailnet-1234.ts.net`) so `known_hosts` is populated.
-
-  </Accordion>
-
-  <Accordion title="Multi-account pattern">
-    iMessage supports per-account config under `channels.imessage.accounts`.
-
-    Each account can override fields such as `cliPath`, `dbPath`, `allowFrom`, `groupPolicy`, `mediaMaxMb`, history settings, and attachment root allowlists.
-
-  </Accordion>
-</AccordionGroup>
-
-## Media, chunking, and delivery targets
-
-<AccordionGroup>
-  <Accordion title="Attachments and media">
-    - inbound attachment ingestion is optional: `channels.imessage.includeAttachments`
-    - remote attachment paths can be fetched via SCP when `remoteHost` is set
-    - attachment paths must match allowed roots:
-      - `channels.imessage.attachmentRoots` (local)
-      - `channels.imessage.remoteAttachmentRoots` (remote SCP mode)
-      - default root pattern: `/Users/*/Library/Messages/Attachments`
-    - SCP uses strict host-key checking (`StrictHostKeyChecking=yes`)
-    - outbound media size uses `channels.imessage.mediaMaxMb` (default 16 MB)
-  </Accordion>
-
-  <Accordion title="Outbound chunking">
-    - text chunk limit: `channels.imessage.textChunkLimit` (default 4000)
-    - chunk mode: `channels.imessage.chunkMode`
-      - `length` (default)
-      - `newline` (paragraph-first splitting)
-  </Accordion>
-
-  <Accordion title="Addressing formats">
-    Preferred explicit targets:
-
-    - `chat_id:123` (recommended for stable routing)
-    - `chat_guid:...`
-    - `chat_identifier:...`
-
-    Handle targets are also supported:
-
-    - `imessage:+1555...`
-    - `sms:+1555...`
-    - `user@example.com`
-
-```bash
-imsg chats --limit 20
-```
-
-  </Accordion>
-</AccordionGroup>
-
-## Config writes
-
-iMessage allows channel-initiated config writes by default (for `/config set|unset` when `commands.config: true`).
-
-Disable:
-
-```json5
-{
-  channels: {
-    imessage: {
-      configWrites: false,
-    },
-  },
-}
-```
-
-## Troubleshooting
-
-<AccordionGroup>
-  <Accordion title="imsg not found or RPC unsupported">
-    Validate the binary and RPC support:
-
-```bash
-imsg rpc --help
-symi channels status --probe
-```
-
-    If probe reports RPC unsupported, update `imsg`.
-
-  </Accordion>
-
-  <Accordion title="DMs are ignored">
-    Check:
-
-    - `channels.imessage.dmPolicy`
-    - `channels.imessage.allowFrom`
-    - pairing approvals (`symi pairing list imessage`)
-
-  </Accordion>
-
-  <Accordion title="Group messages are ignored">
-    Check:
-
-    - `channels.imessage.groupPolicy`
-    - `channels.imessage.groupAllowFrom`
-    - `channels.imessage.groups` allowlist behavior
-    - mention pattern configuration (`agents.list[].groupChat.mentionPatterns`)
-
-  </Accordion>
-
-  <Accordion title="Remote attachments fail">
-    Check:
-
-    - `channels.imessage.remoteHost`
-    - `channels.imessage.remoteAttachmentRoots`
-    - SSH/SCP key auth from the gateway host
-    - host key exists in `~/.ssh/known_hosts` on the gateway host
-    - remote path readability on the Mac running Messages
-
-  </Accordion>
-
-  <Accordion title="macOS permission prompts were missed">
-    Re-run in an interactive GUI terminal in the same user/session context and approve prompts:
-
-```bash
-imsg chats --limit 1
-imsg send <handle> "test"
-```
-
-    Confirm Full Disk Access + Automation are granted for the process context that runs Symi/`imsg`.
-
-  </Accordion>
-</AccordionGroup>
-
-## Configuration
-
-- [Configuration reference - iMessage](/gateway/configuration-reference#imessage)
-- [Gateway configuration](/gateway/configuration)
-- [Pairing](/channels/pairing)
-- [BlueBubbles](/channels/bluebubbles)

package/docs/channels/index.md

@@ -1,46 +0,0 @@
----
-summary: "Messaging platforms Symi can connect to"
-read_when:
-  - You want to choose a chat channel for Symi
-  - You need a quick overview of supported messaging platforms
-title: "Chat Channels"
----
-
-# Chat Channels
-
-Symi can talk to you on any chat app you already use. Each channel connects via the Gateway.
-Text is supported everywhere; media and reactions vary by channel.
-
-## Supported channels
-
-- [WhatsApp](/channels/whatsapp) — Most popular; uses Baileys and requires QR pairing.
-- [Telegram](/channels/telegram) — Bot API via grammY; supports groups.
-- [IRC](/channels/irc) — Classic IRC servers; channels + DMs with pairing/allowlist controls.
-- [Slack](/channels/slack) — Bolt SDK; workspace apps.
-- [Feishu](/channels/feishu) — Feishu/Lark bot via WebSocket (plugin, installed separately).
-- [Google Chat](/channels/googlechat) — Google Chat API app via HTTP webhook.
-- [Mattermost](/channels/mattermost) — Bot API + WebSocket; channels, groups, DMs (plugin, installed separately).
-- [Signal](/channels/signal) — signal-cli; privacy-focused.
-- [BlueBubbles](/channels/bluebubbles) — **Recommended for iMessage**; uses the BlueBubbles macOS server REST API with full feature support (edit, unsend, effects, reactions, group management — edit currently broken on macOS 26 Tahoe).
-- [iMessage (legacy)](/channels/imessage) — Legacy macOS integration via imsg CLI (deprecated, use BlueBubbles for new setups).
-- [Microsoft Teams](/channels/msteams) — Bot Framework; enterprise support (plugin, installed separately).
-- [LINE](/channels/line) — LINE Messaging API bot (plugin, installed separately).
-- [Nextcloud Talk](/channels/nextcloud-talk) — Self-hosted chat via Nextcloud Talk (plugin, installed separately).
-- [Matrix](/channels/matrix) — Matrix protocol (plugin, installed separately).
-- [Nostr](/channels/nostr) — Decentralized DMs via NIP-04 (plugin, installed separately).
-- [Tlon](/channels/tlon) — Urbit-based messenger (plugin, installed separately).
-- [Twitch](/channels/twitch) — Twitch chat via IRC connection (plugin, installed separately).
-- [Zalo](/channels/zalo) — Zalo Bot API; Vietnam's popular messenger (plugin, installed separately).
-- [Zalo Personal](/channels/zalouser) — Zalo personal account via QR login (plugin, installed separately).
-- [WebChat](/web/webchat) — Gateway WebChat UI over WebSocket.
-
-## Notes
-
-- Channels can run simultaneously; configure multiple and Symi will route per chat.
-- Fastest setup is usually **Telegram** (simple bot token). WhatsApp requires QR pairing and
-  stores more state on disk.
-- Group behavior varies by channel; see [Groups](/channels/groups).
-- DM pairing and allowlists are enforced for safety; see [Security](/gateway/security).
-- Telegram internals: [grammY notes](/channels/grammy).
-- Troubleshooting: [Channel troubleshooting](/channels/troubleshooting).
-- Model providers are documented separately; see [Model Providers](/providers/models).

package/docs/channels/irc.md

@@ -1,234 +0,0 @@
----
-title: IRC
-description: Connect Symi to IRC channels and direct messages.
----
-
-Use IRC when you want Symi in classic channels (`#room`) and direct messages.
-IRC ships as an extension plugin, but it is configured in the main config under `channels.irc`.
-
-## Quick start
-
-1. Enable IRC config in `~/.symi/symi.json`.
-2. Set at least:
-
-```json
-{
-  "channels": {
-    "irc": {
-      "enabled": true,
-      "host": "irc.libera.chat",
-      "port": 6697,
-      "tls": true,
-      "nick": "symi-bot",
-      "channels": ["#symi"]
-    }
-  }
-}
-```
-
-3. Start/restart gateway:
-
-```bash
-symi gateway run
-```
-
-## Security defaults
-
-- `channels.irc.dmPolicy` defaults to `"pairing"`.
-- `channels.irc.groupPolicy` defaults to `"allowlist"`.
-- With `groupPolicy="allowlist"`, set `channels.irc.groups` to define allowed channels.
-- Use TLS (`channels.irc.tls=true`) unless you intentionally accept plaintext transport.
-
-## Access control
-
-There are two separate “gates” for IRC channels:
-
-1. **Channel access** (`groupPolicy` + `groups`): whether the bot accepts messages from a channel at all.
-2. **Sender access** (`groupAllowFrom` / per-channel `groups["#channel"].allowFrom`): who is allowed to trigger the bot inside that channel.
-
-Config keys:
-
-- DM allowlist (DM sender access): `channels.irc.allowFrom`
-- Group sender allowlist (channel sender access): `channels.irc.groupAllowFrom`
-- Per-channel controls (channel + sender + mention rules): `channels.irc.groups["#channel"]`
-- `channels.irc.groupPolicy="open"` allows unconfigured channels (**still mention-gated by default**)
-
-Allowlist entries can use nick or `nick!user@host` forms.
-
-### Common gotcha: `allowFrom` is for DMs, not channels
-
-If you see logs like:
-
-- `irc: drop group sender alice!ident@host (policy=allowlist)`
-
-…it means the sender wasn’t allowed for **group/channel** messages. Fix it by either:
-
-- setting `channels.irc.groupAllowFrom` (global for all channels), or
-- setting per-channel sender allowlists: `channels.irc.groups["#channel"].allowFrom`
-
-Example (allow anyone in `#tuirc-dev` to talk to the bot):
-
-```json5
-{
-  channels: {
-    irc: {
-      groupPolicy: "allowlist",
-      groups: {
-        "#tuirc-dev": { allowFrom: ["*"] },
-      },
-    },
-  },
-}
-```
-
-## Reply triggering (mentions)
-
-Even if a channel is allowed (via `groupPolicy` + `groups`) and the sender is allowed, Symi defaults to **mention-gating** in group contexts.
-
-That means you may see logs like `drop channel … (missing-mention)` unless the message includes a mention pattern that matches the bot.
-
-To make the bot reply in an IRC channel **without needing a mention**, disable mention gating for that channel:
-
-```json5
-{
-  channels: {
-    irc: {
-      groupPolicy: "allowlist",
-      groups: {
-        "#tuirc-dev": {
-          requireMention: false,
-          allowFrom: ["*"],
-        },
-      },
-    },
-  },
-}
-```
-
-Or to allow **all** IRC channels (no per-channel allowlist) and still reply without mentions:
-
-```json5
-{
-  channels: {
-    irc: {
-      groupPolicy: "open",
-      groups: {
-        "*": { requireMention: false, allowFrom: ["*"] },
-      },
-    },
-  },
-}
-```
-
-## Security note (recommended for public channels)
-
-If you allow `allowFrom: ["*"]` in a public channel, anyone can prompt the bot.
-To reduce risk, restrict tools for that channel.
-
-### Same tools for everyone in the channel
-
-```json5
-{
-  channels: {
-    irc: {
-      groups: {
-        "#tuirc-dev": {
-          allowFrom: ["*"],
-          tools: {
-            deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-### Different tools per sender (owner gets more power)
-
-Use `toolsBySender` to apply a stricter policy to `"*"` and a looser one to your nick:
-
-```json5
-{
-  channels: {
-    irc: {
-      groups: {
-        "#tuirc-dev": {
-          allowFrom: ["*"],
-          toolsBySender: {
-            "*": {
-              deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
-            },
-            eigen: {
-              deny: ["gateway", "nodes", "cron"],
-            },
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-Notes:
-
-- `toolsBySender` keys can be a nick (e.g. `"eigen"`) or a full hostmask (`"eigen!~eigen@174.127.248.171"`) for stronger identity matching.
-- The first matching sender policy wins; `"*"` is the wildcard fallback.
-
-For more on group access vs mention-gating (and how they interact), see: [/channels/groups](/channels/groups).
-
-## NickServ
-
-To identify with NickServ after connect:
-
-```json
-{
-  "channels": {
-    "irc": {
-      "nickserv": {
-        "enabled": true,
-        "service": "NickServ",
-        "password": "your-nickserv-password"
-      }
-    }
-  }
-}
-```
-
-Optional one-time registration on connect:
-
-```json
-{
-  "channels": {
-    "irc": {
-      "nickserv": {
-        "register": true,
-        "registerEmail": "bot@example.com"
-      }
-    }
-  }
-}
-```
-
-Disable `register` after the nick is registered to avoid repeated REGISTER attempts.
-
-## Environment variables
-
-Default account supports:
-
-- `IRC_HOST`
-- `IRC_PORT`
-- `IRC_TLS`
-- `IRC_NICK`
-- `IRC_USERNAME`
-- `IRC_REALNAME`
-- `IRC_PASSWORD`
-- `IRC_CHANNELS` (comma-separated)
-- `IRC_NICKSERV_PASSWORD`
-- `IRC_NICKSERV_REGISTER_EMAIL`
-
-## Troubleshooting
-
-- If the bot connects but never replies in channels, verify `channels.irc.groups` **and** whether mention-gating is dropping messages (`missing-mention`). If you want it to reply without pings, set `requireMention:false` for the channel.
-- If login fails, verify nick availability and server password.
-- If TLS fails on a custom network, verify host/port and certificate setup.