durar-ai 2026.4.4

package/docs/channels/imessage.md

@@ -0,0 +1,427 @@
+---
+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>
+
+## Quick setup
+
+<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 Durar">
+
+```json5
+{
+  channels: {
+    imessage: {
+      enabled: true,
+      cliPath: "/usr/local/bin/imsg",
+      dbPath: "/Users/<you>/Library/Messages/chat.db",
+    },
+  },
+}
+```
+
+      </Step>
+
+      <Step title="Start gateway">
+
+```bash
+Durar gateway
+```
+
+      </Step>
+
+      <Step title="Approve first DM pairing (default dmPolicy)">
+
+```bash
+Durar pairing list imessage
+Durar pairing approve imessage <CODE>
+```
+
+        Pairing requests expire after 1 hour.
+      </Step>
+    </Steps>
+
+  </Tab>
+
+  <Tab title="Remote Mac over SSH">
+    Durar 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: "~/.Durar/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, Durar attempts to auto-detect it by parsing the SSH wrapper script.
+    `remoteHost` must be `host` or `user@host` (no spaces or SSH options).
+    Durar 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 Durar/`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.
+    Runtime note: if `channels.imessage` is completely missing, runtime falls back to `groupPolicy="allowlist"` and logs a warning (even if `channels.defaults.groupPolicy` is set).
+
+    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`, Durar treats it as group traffic (group gating + group session isolation).
+
+  </Tab>
+</Tabs>
+
+## ACP conversation bindings
+
+Legacy iMessage chats can also be bound to ACP sessions.
+
+Fast operator flow:
+
+- Run `/acp spawn codex --bind here` inside the DM or allowed group chat.
+- Future messages in that same iMessage conversation route to the spawned ACP session.
+- `/new` and `/reset` reset the same bound ACP session in place.
+- `/acp close` closes the ACP session and removes the binding.
+
+Configured persistent bindings are supported through top-level `bindings[]` entries with `type: "acp"` and `match.channel: "imessage"`.
+
+`match.peer.id` can use:
+
+- normalized DM handle such as `+15555550123` or `user@example.com`
+- `chat_id:<id>` (recommended for stable group bindings)
+- `chat_guid:<guid>`
+- `chat_identifier:<identifier>`
+
+Example:
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "codex",
+        runtime: {
+          type: "acp",
+          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
+        },
+      },
+    ],
+  },
+  bindings: [
+    {
+      type: "acp",
+      agentId: "codex",
+      match: {
+        channel: "imessage",
+        accountId: "default",
+        peer: { kind: "group", id: "chat_id:123" },
+      },
+      acp: { label: "codex-group" },
+    },
+  ],
+}
+```
+
+See [ACP Agents](/tools/acp-agents) for shared ACP binding behavior.
+
+## 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 Durar 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: "~/.Durar/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
+Durar 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 (`Durar 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 Durar/`imsg`.
+
+  </Accordion>
+</AccordionGroup>
+
+## Configuration reference pointers
+
+- [Configuration reference - iMessage](/gateway/configuration-reference#imessage)
+- [Gateway configuration](/gateway/configuration)
+- [Pairing](/channels/pairing)
+- [BlueBubbles](/channels/bluebubbles)
+
+## Related
+
+- [Channels Overview](/channels) — all supported channels
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Security](/gateway/security) — access model and hardening

package/docs/channels/index.md

@@ -0,0 +1,50 @@
+---
+summary: "Messaging platforms Durar can connect to"
+read_when:
+  - You want to choose a chat channel for Durar
+  - You need a quick overview of supported messaging platforms
+title: "Chat Channels"
+---
+
+# Chat Channels
+
+Durar 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
+
+- [BlueBubbles](/channels/bluebubbles) — **Recommended for iMessage**; uses the BlueBubbles macOS server REST API with full feature support (bundled plugin; edit, unsend, effects, reactions, group management — edit currently broken on macOS 26 Tahoe).
+- [Discord](/channels/discord) — Discord Bot API + Gateway; supports servers, channels, and DMs.
+- [Feishu](/channels/feishu) — Feishu/Lark bot via WebSocket (bundled plugin).
+- [Google Chat](/channels/googlechat) — Google Chat API app via HTTP webhook.
+- [iMessage (legacy)](/channels/imessage) — Legacy macOS integration via imsg CLI (deprecated, use BlueBubbles for new setups).
+- [IRC](/channels/irc) — Classic IRC servers; channels + DMs with pairing/allowlist controls.
+- [LINE](/channels/line) — LINE Messaging API bot (bundled plugin).
+- [Matrix](/channels/matrix) — Matrix protocol (bundled plugin).
+- [Mattermost](/channels/mattermost) — Bot API + WebSocket; channels, groups, DMs (bundled plugin).
+- [Microsoft Teams](/channels/msteams) — Bot Framework; enterprise support (bundled plugin).
+- [Nextcloud Talk](/channels/nextcloud-talk) — Self-hosted chat via Nextcloud Talk (bundled plugin).
+- [Nostr](/channels/nostr) — Decentralized DMs via NIP-04 (bundled plugin).
+- [QQ Bot](/channels/qqbot) — QQ Bot API; private chat, group chat, and rich media (bundled plugin).
+- [Signal](/channels/signal) — signal-cli; privacy-focused.
+- [Slack](/channels/slack) — Bolt SDK; workspace apps.
+- [Synology Chat](/channels/synology-chat) — Synology NAS Chat via outgoing+incoming webhooks (bundled plugin).
+- [Telegram](/channels/telegram) — Bot API via grammY; supports groups.
+- [Tlon](/channels/tlon) — Urbit-based messenger (bundled plugin).
+- [Twitch](/channels/twitch) — Twitch chat via IRC connection (bundled plugin).
+- [Voice Call](/plugins/voice-call) — Telephony via Plivo or Twilio (plugin, installed separately).
+- [WebChat](/web/webchat) — Gateway WebChat UI over WebSocket.
+- [WeChat](https://www.npmjs.com/package/@tencent-weixin/Durar-weixin) — Tencent iLink Bot plugin via QR login; private chats only.
+- [WhatsApp](/channels/whatsapp) — Most popular; uses Baileys and requires QR pairing.
+- [Zalo](/channels/zalo) — Zalo Bot API; Vietnam's popular messenger (bundled plugin).
+- [Zalo Personal](/channels/zalouser) — Zalo personal account via QR login (bundled plugin).
+
+## Notes
+
+- Channels can run simultaneously; configure multiple and Durar 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).
+- Troubleshooting: [Channel troubleshooting](/channels/troubleshooting).
+- Model providers are documented separately; see [Model Providers](/providers/models).