@symerian/symi 3.0.20 → 3.0.22

package/docs/channels/line.md

@@ -1,186 +0,0 @@
----
-summary: "LINE Messaging API plugin setup, config, and usage"
-read_when:
-  - You want to connect Symi to LINE
-  - You need LINE webhook + credential setup
-  - You want LINE-specific message options
-title: LINE
----
-
-# LINE (plugin)
-
-LINE connects to Symi via the LINE Messaging API. The plugin runs as a webhook
-receiver on the gateway and uses your channel access token + channel secret for
-authentication.
-
-Status: supported via plugin. Direct messages, group chats, media, locations, Flex
-messages, template messages, and quick replies are supported. Reactions and threads
-are not supported.
-
-## Plugin required
-
-Install the LINE plugin:
-
-```bash
-symi plugins install @symi/line
-```
-
-Local checkout (when running from a git repo):
-
-```bash
-symi plugins install ./extensions/line
-```
-
-## Onboarding
-
-1. Create a LINE Developers account and open the Console:
-   [https://developers.line.biz/console/](https://developers.line.biz/console/)
-2. Create (or pick) a Provider and add a **Messaging API** channel.
-3. Copy the **Channel access token** and **Channel secret** from the channel settings.
-4. Enable **Use webhook** in the Messaging API settings.
-5. Set the webhook URL to your gateway endpoint (HTTPS required):
-
-```
-https://gateway-host/line/webhook
-```
-
-The gateway responds to LINE’s webhook verification (GET) and inbound events (POST).
-If you need a custom path, set `channels.line.webhookPath` or
-`channels.line.accounts.<id>.webhookPath` and update the URL accordingly.
-
-## Configuration
-
-Minimal config:
-
-```json5
-{
-  channels: {
-    line: {
-      enabled: true,
-      channelAccessToken: "LINE_CHANNEL_ACCESS_TOKEN",
-      channelSecret: "LINE_CHANNEL_SECRET",
-      dmPolicy: "pairing",
-    },
-  },
-}
-```
-
-Env vars (default account only):
-
-- `LINE_CHANNEL_ACCESS_TOKEN`
-- `LINE_CHANNEL_SECRET`
-
-Token/secret files:
-
-```json5
-{
-  channels: {
-    line: {
-      tokenFile: "/path/to/line-token.txt",
-      secretFile: "/path/to/line-secret.txt",
-    },
-  },
-}
-```
-
-Multiple accounts:
-
-```json5
-{
-  channels: {
-    line: {
-      accounts: {
-        marketing: {
-          channelAccessToken: "...",
-          channelSecret: "...",
-          webhookPath: "/line/marketing",
-        },
-      },
-    },
-  },
-}
-```
-
-## Access control
-
-Direct messages default to pairing. Unknown senders get a pairing code and their
-messages are ignored until approved.
-
-```bash
-symi pairing list line
-symi pairing approve line <CODE>
-```
-
-Allowlists and policies:
-
-- `channels.line.dmPolicy`: `pairing | allowlist | open | disabled`
-- `channels.line.allowFrom`: allowlisted LINE user IDs for DMs
-- `channels.line.groupPolicy`: `allowlist | open | disabled`
-- `channels.line.groupAllowFrom`: allowlisted LINE user IDs for groups
-- Per-group overrides: `channels.line.groups.<groupId>.allowFrom`
-
-LINE IDs are case-sensitive. Valid IDs look like:
-
-- User: `U` + 32 hex chars
-- Group: `C` + 32 hex chars
-- Room: `R` + 32 hex chars
-
-## Message behavior
-
-- Text is chunked at 5000 characters.
-- Markdown formatting is stripped; code blocks and tables are converted into Flex
-  cards when possible.
-- Streaming responses are buffered; LINE receives full chunks with a loading
-  animation while the agent works.
-- Media downloads are capped by `channels.line.mediaMaxMb` (default 10).
-
-## Channel data (rich messages)
-
-Use `channelData.line` to send quick replies, locations, Flex cards, or template
-messages.
-
-```json5
-{
-  text: "Here you go",
-  channelData: {
-    line: {
-      quickReplies: ["Status", "Help"],
-      location: {
-        title: "Office",
-        address: "123 Main St",
-        latitude: 35.681236,
-        longitude: 139.767125,
-      },
-      flexMessage: {
-        altText: "Status card",
-        contents: {
-          /* Flex payload */
-        },
-      },
-      templateMessage: {
-        type: "confirm",
-        text: "Proceed?",
-        confirmLabel: "Yes",
-        confirmData: "yes",
-        cancelLabel: "No",
-        cancelData: "no",
-      },
-    },
-  },
-}
-```
-
-The LINE plugin also ships a `/card` command for Flex message presets:
-
-```
-/card info "Welcome" "Thanks for joining!"
-```
-
-## Troubleshooting
-
-- **Webhook verification fails:** ensure the webhook URL is HTTPS and the
-  `channelSecret` matches the LINE console.
-- **No inbound events:** confirm the webhook path matches `channels.line.webhookPath`
-  and that the gateway is reachable from LINE.
-- **Media download errors:** raise `channels.line.mediaMaxMb` if media exceeds the
-  default limit.

package/docs/channels/location.md

@@ -1,56 +0,0 @@
----
-summary: "Inbound channel location parsing (Telegram + WhatsApp) and context fields"
-read_when:
-  - Adding or modifying channel location parsing
-  - Using location context fields in agent prompts or tools
-title: "Channel Location Parsing"
----
-
-# Channel location parsing
-
-Symi normalizes shared locations from chat channels into:
-
-- human-readable text appended to the inbound body, and
-- structured fields in the auto-reply context payload.
-
-Currently supported:
-
-- **Telegram** (location pins + venues + live locations)
-- **WhatsApp** (locationMessage + liveLocationMessage)
-- **Matrix** (`m.location` with `geo_uri`)
-
-## Text formatting
-
-Locations are rendered as friendly lines without brackets:
-
-- Pin:
-  - `📍 48.858844, 2.294351 ±12m`
-- Named place:
-  - `📍 Eiffel Tower — Champ de Mars, Paris (48.858844, 2.294351 ±12m)`
-- Live share:
-  - `🛰 Live location: 48.858844, 2.294351 ±12m`
-
-If the channel includes a caption/comment, it is appended on the next line:
-
-```
-📍 48.858844, 2.294351 ±12m
-Meet here
-```
-
-## Context fields
-
-When a location is present, these fields are added to `ctx`:
-
-- `LocationLat` (number)
-- `LocationLon` (number)
-- `LocationAccuracy` (number, meters; optional)
-- `LocationName` (string; optional)
-- `LocationAddress` (string; optional)
-- `LocationSource` (`pin | place | live`)
-- `LocationIsLive` (boolean)
-
-## Channel notes
-
-- **Telegram**: venues map to `LocationName/LocationAddress`; live locations use `live_period`.
-- **WhatsApp**: `locationMessage.comment` and `liveLocationMessage.caption` are appended as the caption line.
-- **Matrix**: `geo_uri` is parsed as a pin location; altitude is ignored and `LocationIsLive` is always false.

package/docs/channels/matrix.md

@@ -1,300 +0,0 @@
----
-summary: "Matrix support status, capabilities, and configuration"
-read_when:
-  - Working on Matrix channel features
-title: "Matrix"
----
-
-# Matrix (plugin)
-
-Matrix is an open, decentralized messaging protocol. Symi connects as a Matrix **user**
-on any homeserver, so you need a Matrix account for the bot. Once it is logged in, you can DM
-the bot directly or invite it to rooms (Matrix "groups"). Beeper is a valid client option too,
-but it requires E2EE to be enabled.
-
-Status: supported via plugin (@vector-im/matrix-bot-sdk). Direct messages, rooms, threads, media, reactions,
-polls (send + poll-start as text), location, and E2EE (with crypto support).
-
-## Plugin required
-
-Matrix ships as a plugin and is not bundled with the core install.
-
-Install via CLI (npm registry):
-
-```bash
-symi plugins install @symi/matrix
-```
-
-Local checkout (when running from a git repo):
-
-```bash
-symi plugins install ./extensions/matrix
-```
-
-If you choose Matrix during configure/onboarding and a git checkout is detected,
-Symi will offer the local install path automatically.
-
-Details: [Plugins](/tools/plugin)
-
-## Onboarding
-
-1. Install the Matrix plugin:
-   - From npm: `symi plugins install @symi/matrix`
-   - From a local checkout: `symi plugins install ./extensions/matrix`
-2. Create a Matrix account on a homeserver:
-   - Browse hosting options at [https://matrix.org/ecosystem/hosting/](https://matrix.org/ecosystem/hosting/)
-   - Or host it yourself.
-3. Get an access token for the bot account:
-   - Use the Matrix login API with `curl` at your home server:
-
-   ```bash
-   curl --request POST \
-     --url https://matrix.example.org/_matrix/client/v3/login \
-     --header 'Content-Type: application/json' \
-     --data '{
-     "type": "m.login.password",
-     "identifier": {
-       "type": "m.id.user",
-       "user": "your-user-name"
-     },
-     "password": "your-password"
-   }'
-   ```
-
-   - Replace `matrix.example.org` with your homeserver URL.
-   - Or set `channels.matrix.userId` + `channels.matrix.password`: Symi calls the same
-     login endpoint, stores the access token in `~/.symi/credentials/matrix/credentials.json`,
-     and reuses it on next start.
-
-4. Configure credentials:
-   - Env: `MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN` (or `MATRIX_USER_ID` + `MATRIX_PASSWORD`)
-   - Or config: `channels.matrix.*`
-   - If both are set, config takes precedence.
-   - With access token: user ID is fetched automatically via `/whoami`.
-   - When set, `channels.matrix.userId` should be the full Matrix ID (example: `@bot:example.org`).
-5. Restart the gateway (or finish onboarding).
-6. Start a DM with the bot or invite it to a room from any Matrix client
-   (Element, Beeper, etc.; see [https://matrix.org/ecosystem/clients/](https://matrix.org/ecosystem/clients/)). Beeper requires E2EE,
-   so set `channels.matrix.encryption: true` and verify the device.
-
-Minimal config (access token, user ID auto-fetched):
-
-```json5
-{
-  channels: {
-    matrix: {
-      enabled: true,
-      homeserver: "https://matrix.example.org",
-      accessToken: "syt_***",
-      dm: { policy: "pairing" },
-    },
-  },
-}
-```
-
-E2EE config (end to end encryption enabled):
-
-```json5
-{
-  channels: {
-    matrix: {
-      enabled: true,
-      homeserver: "https://matrix.example.org",
-      accessToken: "syt_***",
-      encryption: true,
-      dm: { policy: "pairing" },
-    },
-  },
-}
-```
-
-## Encryption (E2EE)
-
-End-to-end encryption is **supported** via the Rust crypto SDK.
-
-Enable with `channels.matrix.encryption: true`:
-
-- If the crypto module loads, encrypted rooms are decrypted automatically.
-- Outbound media is encrypted when sending to encrypted rooms.
-- On first connection, Symi requests device verification from your other sessions.
-- Verify the device in another Matrix client (Element, etc.) to enable key sharing.
-- If the crypto module cannot be loaded, E2EE is disabled and encrypted rooms will not decrypt;
-  Symi logs a warning.
-- If you see missing crypto module errors (for example, `@matrix-org/matrix-sdk-crypto-nodejs-*`),
-  allow build scripts for `@matrix-org/matrix-sdk-crypto-nodejs` and run
-  `pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs` or fetch the binary with
-  `node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js`.
-
-Crypto state is stored per account + access token in
-`~/.symi/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/`
-(SQLite database). Sync state lives alongside it in `bot-storage.json`.
-If the access token (device) changes, a new store is created and the bot must be
-re-verified for encrypted rooms.
-
-**Device verification:**
-When E2EE is enabled, the bot will request verification from your other sessions on startup.
-Open Element (or another client) and approve the verification request to establish trust.
-Once verified, the bot can decrypt messages in encrypted rooms.
-
-## Multi-account
-
-Each account runs as a separate Matrix user on any homeserver. Per-account config
-inherits from the top-level `channels.matrix` settings and can override any option
-(DM policy, groups, encryption, etc.).
-
-```json5
-{
-  channels: {
-    matrix: {
-      enabled: true,
-      dm: { policy: "pairing" },
-      accounts: {
-        assistant: {
-          name: "Main assistant",
-          homeserver: "https://matrix.example.org",
-          accessToken: "syt_assistant_***",
-          encryption: true,
-        },
-        alerts: {
-          name: "Alerts bot",
-          homeserver: "https://matrix.example.org",
-          accessToken: "syt_alerts_***",
-          dm: { policy: "allowlist", allowFrom: ["@admin:example.org"] },
-        },
-      },
-    },
-  },
-}
-```
-
-Notes:
-
-- Account startup is serialized to avoid race conditions with concurrent module imports.
-- Env variables (`MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN`, etc.) only apply to the **default** account.
-- Base channel settings (DM policy, group policy, mention gating, etc.) apply to all accounts unless overridden per account.
-- Use `bindings[].match.accountId` to route each account to a different agent.
-- Crypto state is stored per account + access token (separate key stores per account).
-
-## Routing model
-
-- Replies always go back to Matrix.
-- DMs share the agent's main session; rooms map to group sessions.
-
-## Access control (DMs)
-
-- Default: `channels.matrix.dm.policy = "pairing"`. Unknown senders get a pairing code.
-- Approve via:
-  - `symi pairing list matrix`
-  - `symi pairing approve matrix <CODE>`
-- Public DMs: `channels.matrix.dm.policy="open"` plus `channels.matrix.dm.allowFrom=["*"]`.
-- `channels.matrix.dm.allowFrom` accepts full Matrix user IDs (example: `@user:server`). The wizard resolves display names to user IDs when directory search finds a single exact match.
-- Do not use display names or bare localparts (example: `"Alice"` or `"alice"`). They are ambiguous and are ignored for allowlist matching. Use full `@user:server` IDs.
-
-## Rooms (groups)
-
-- Default: `channels.matrix.groupPolicy = "allowlist"` (mention-gated). Use `channels.defaults.groupPolicy` to override the default when unset.
-- Allowlist rooms with `channels.matrix.groups` (room IDs or aliases; names are resolved to IDs when directory search finds a single exact match):
-
-```json5
-{
-  channels: {
-    matrix: {
-      groupPolicy: "allowlist",
-      groups: {
-        "!roomId:example.org": { allow: true },
-        "#alias:example.org": { allow: true },
-      },
-      groupAllowFrom: ["@owner:example.org"],
-    },
-  },
-}
-```
-
-- `requireMention: false` enables auto-reply in that room.
-- `groups."*"` can set defaults for mention gating across rooms.
-- `groupAllowFrom` restricts which senders can trigger the bot in rooms (full Matrix user IDs).
-- Per-room `users` allowlists can further restrict senders inside a specific room (use full Matrix user IDs).
-- The configure wizard prompts for room allowlists (room IDs, aliases, or names) and resolves names only on an exact, unique match.
-- On startup, Symi resolves room/user names in allowlists to IDs and logs the mapping; unresolved entries are ignored for allowlist matching.
-- Invites are auto-joined by default; control with `channels.matrix.autoJoin` and `channels.matrix.autoJoinAllowlist`.
-- To allow **no rooms**, set `channels.matrix.groupPolicy: "disabled"` (or keep an empty allowlist).
-- Legacy key: `channels.matrix.rooms` (same shape as `groups`).
-
-## Threads
-
-- Reply threading is supported.
-- `channels.matrix.threadReplies` controls whether replies stay in threads:
-  - `off`, `inbound` (default), `always`
-- `channels.matrix.replyToMode` controls reply-to metadata when not replying in a thread:
-  - `off` (default), `first`, `all`
-
-## Capabilities
-
-| Feature         | Status                                                                                |
-| --------------- | ------------------------------------------------------------------------------------- |
-| Direct messages | ✅ Supported                                                                          |
-| Rooms           | ✅ Supported                                                                          |
-| Threads         | ✅ Supported                                                                          |
-| Media           | ✅ Supported                                                                          |
-| E2EE            | ✅ Supported (crypto module required)                                                 |
-| Reactions       | ✅ Supported (send/read via tools)                                                    |
-| Polls           | ✅ Send supported; inbound poll starts are converted to text (responses/ends ignored) |
-| Location        | ✅ Supported (geo URI; altitude ignored)                                              |
-| Native commands | ✅ Supported                                                                          |
-
-## Troubleshooting
-
-Run this ladder first:
-
-```bash
-symi status
-symi gateway status
-symi logs --follow
-symi doctor
-symi channels status --probe
-```
-
-Then confirm DM pairing state if needed:
-
-```bash
-symi pairing list matrix
-```
-
-Common failures:
-
-- Logged in but room messages ignored: room blocked by `groupPolicy` or room allowlist.
-- DMs ignored: sender pending approval when `channels.matrix.dm.policy="pairing"`.
-- Encrypted rooms fail: crypto support or encryption settings mismatch.
-
-For triage flow: [/channels/troubleshooting](/channels/troubleshooting).
-
-## Configuration
-
-Full configuration: [Configuration](/gateway/configuration)
-
-Provider options:
-
-- `channels.matrix.enabled`: enable/disable channel startup.
-- `channels.matrix.homeserver`: homeserver URL.
-- `channels.matrix.userId`: Matrix user ID (optional with access token).
-- `channels.matrix.accessToken`: access token.
-- `channels.matrix.password`: password for login (token stored).
-- `channels.matrix.deviceName`: device display name.
-- `channels.matrix.encryption`: enable E2EE (default: false).
-- `channels.matrix.initialSyncLimit`: initial sync limit.
-- `channels.matrix.threadReplies`: `off | inbound | always` (default: inbound).
-- `channels.matrix.textChunkLimit`: outbound text chunk size (chars).
-- `channels.matrix.chunkMode`: `length` (default) or `newline` to split on blank lines (paragraph boundaries) before length chunking.
-- `channels.matrix.dm.policy`: `pairing | allowlist | open | disabled` (default: pairing).
-- `channels.matrix.dm.allowFrom`: DM allowlist (full Matrix user IDs). `open` requires `"*"`. The wizard resolves names to IDs when possible.
-- `channels.matrix.groupPolicy`: `allowlist | open | disabled` (default: allowlist).
-- `channels.matrix.groupAllowFrom`: allowlisted senders for group messages (full Matrix user IDs).
-- `channels.matrix.allowlistOnly`: force allowlist rules for DMs + rooms.
-- `channels.matrix.groups`: group allowlist + per-room settings map.
-- `channels.matrix.rooms`: legacy group allowlist/config.
-- `channels.matrix.replyToMode`: reply-to mode for threads/tags.
-- `channels.matrix.mediaMaxMb`: inbound/outbound media cap (MB).
-- `channels.matrix.autoJoin`: invite handling (`always | allowlist | off`, default: always).
-- `channels.matrix.autoJoinAllowlist`: allowed room IDs/aliases for auto-join.
-- `channels.matrix.accounts`: multi-account configuration keyed by account ID (each account inherits top-level settings).
-- `channels.matrix.actions`: per-action tool gating (reactions/messages/pins/memberInfo/channelInfo).

package/docs/channels/mattermost.md

@@ -1,158 +0,0 @@
----
-summary: "Mattermost bot setup and Symi config"
-read_when:
-  - Setting up Mattermost
-  - Debugging Mattermost routing
-title: "Mattermost"
----
-
-# Mattermost (plugin)
-
-Status: supported via plugin (bot token + WebSocket events). Channels, groups, and DMs are supported.
-Mattermost is a self-hostable team messaging platform; see the official site at
-[mattermost.com](https://mattermost.com) for product details and downloads.
-
-## Plugin required
-
-Mattermost ships as a plugin and is not bundled with the core install.
-
-Install via CLI (npm registry):
-
-```bash
-symi plugins install @symi/mattermost
-```
-
-Local checkout (when running from a git repo):
-
-```bash
-symi plugins install ./extensions/mattermost
-```
-
-If you choose Mattermost during configure/onboarding and a git checkout is detected,
-Symi will offer the local install path automatically.
-
-Details: [Plugins](/tools/plugin)
-
-## Onboarding
-
-1. Install the Mattermost plugin.
-2. Create a Mattermost bot account and copy the **bot token**.
-3. Copy the Mattermost **base URL** (e.g., `https://chat.example.com`).
-4. Configure Symi and start the gateway.
-
-Minimal config:
-
-```json5
-{
-  channels: {
-    mattermost: {
-      enabled: true,
-      botToken: "mm-token",
-      baseUrl: "https://chat.example.com",
-      dmPolicy: "pairing",
-    },
-  },
-}
-```
-
-## Environment variables (default account)
-
-Set these on the gateway host if you prefer env vars:
-
-- `MATTERMOST_BOT_TOKEN=...`
-- `MATTERMOST_URL=https://chat.example.com`
-
-Env vars apply only to the **default** account (`default`). Other accounts must use config values.
-
-## Chat modes
-
-Mattermost responds to DMs automatically. Channel behavior is controlled by `chatmode`:
-
-- `oncall` (default): respond only when @mentioned in channels.
-- `onmessage`: respond to every channel message.
-- `onchar`: respond when a message starts with a trigger prefix.
-
-Config example:
-
-```json5
-{
-  channels: {
-    mattermost: {
-      chatmode: "onchar",
-      oncharPrefixes: [">", "!"],
-    },
-  },
-}
-```
-
-Notes:
-
-- `onchar` still responds to explicit @mentions.
-- `channels.mattermost.requireMention` is honored for legacy configs but `chatmode` is preferred.
-
-## Access control (DMs)
-
-- Default: `channels.mattermost.dmPolicy = "pairing"` (unknown senders get a pairing code).
-- Approve via:
-  - `symi pairing list mattermost`
-  - `symi pairing approve mattermost <CODE>`
-- Public DMs: `channels.mattermost.dmPolicy="open"` plus `channels.mattermost.allowFrom=["*"]`.
-
-## Channels (groups)
-
-- Default: `channels.mattermost.groupPolicy = "allowlist"` (mention-gated).
-- Allowlist senders with `channels.mattermost.groupAllowFrom` (user IDs or `@username`).
-- Open channels: `channels.mattermost.groupPolicy="open"` (mention-gated).
-
-## Targets for outbound delivery
-
-Use these target formats with `symi message send` or cron/webhooks:
-
-- `channel:<id>` for a channel
-- `user:<id>` for a DM
-- `@username` for a DM (resolved via the Mattermost API)
-
-Bare IDs are treated as channels.
-
-## Reactions (message tool)
-
-- Use `message action=react` with `channel=mattermost`.
-- `messageId` is the Mattermost post id.
-- `emoji` accepts names like `thumbsup` or `:+1:` (colons are optional).
-- Set `remove=true` (boolean) to remove a reaction.
-- Reaction add/remove events are forwarded as system events to the routed agent session.
-
-Examples:
-
-```
-message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup
-message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup remove=true
-```
-
-Config:
-
-- `channels.mattermost.actions.reactions`: enable/disable reaction actions (default true).
-- Per-account override: `channels.mattermost.accounts.<id>.actions.reactions`.
-
-## Multi-account
-
-Mattermost supports multiple accounts under `channels.mattermost.accounts`:
-
-```json5
-{
-  channels: {
-    mattermost: {
-      accounts: {
-        default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" },
-        alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" },
-      },
-    },
-  },
-}
-```
-
-## Troubleshooting
-
-- No replies in channels: ensure the bot is in the channel and mention it (oncall), use a trigger prefix (onchar), or set `chatmode: "onmessage"`.
-- Auth errors: check the bot token, base URL, and whether the account is enabled.
-- Multi-account issues: env vars only apply to the `default` account.