@symerian/symi 3.0.21 → 3.0.22

package/docs/channels/googlechat.md

@@ -1,253 +0,0 @@
----
-summary: "Google Chat app support status, capabilities, and configuration"
-read_when:
-  - Working on Google Chat channel features
-title: "Google Chat"
----
-
-# Google Chat (Chat API)
-
-Status: ready for DMs + spaces via Google Chat API webhooks (HTTP only).
-
-## Onboarding
-
-1. Create a Google Cloud project and enable the **Google Chat API**.
-   - Go to: [Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
-   - Enable the API if it is not already enabled.
-2. Create a **Service Account**:
-   - Press **Create Credentials** > **Service Account**.
-   - Name it whatever you want (e.g., `symi-chat`).
-   - Leave permissions blank (press **Continue**).
-   - Leave principals with access blank (press **Done**).
-3. Create and download the **JSON Key**:
-   - In the list of service accounts, click on the one you just created.
-   - Go to the **Keys** tab.
-   - Click **Add Key** > **Create new key**.
-   - Select **JSON** and press **Create**.
-4. Store the downloaded JSON file on your gateway host (e.g., `~/.symi/googlechat-service-account.json`).
-5. Create a Google Chat app in the [Google Cloud Console Chat Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat):
-   - Fill in the **Application info**:
-     - **App name**: (e.g. `Symi`)
-     - **Avatar URL**: (e.g. `https://symi.ai/logo.png`)
-     - **Description**: (e.g. `Personal AI Assistant`)
-   - Enable **Interactive features**.
-   - Under **Functionality**, check **Join spaces and group conversations**.
-   - Under **Connection settings**, select **HTTP endpoint URL**.
-   - Under **Triggers**, select **Use a common HTTP endpoint URL for all triggers** and set it to your gateway's public URL followed by `/googlechat`.
-     - _Tip: Run `symi status` to find your gateway's public URL._
-   - Under **Visibility**, check **Make this Chat app available to specific people and groups in <Your Domain>**.
-   - Enter your email address (e.g. `user@example.com`) in the text box.
-   - Click **Save** at the bottom.
-6. **Enable the app status**:
-   - After saving, **refresh the page**.
-   - Look for the **App status** section (usually near the top or bottom after saving).
-   - Change the status to **Live - available to users**.
-   - Click **Save** again.
-7. Configure Symi with the service account path + webhook audience:
-   - Env: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json`
-   - Or config: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`.
-8. Set the webhook audience type + value (matches your Chat app config).
-9. Start the gateway. Google Chat will POST to your webhook path.
-
-## Add to Google Chat
-
-Once the gateway is running and your email is added to the visibility list:
-
-1. Go to [Google Chat](https://chat.google.com/).
-2. Click the **+** (plus) icon next to **Direct Messages**.
-3. In the search bar (where you usually add people), type the **App name** you configured in the Google Cloud Console.
-   - **Note**: The bot will _not_ appear in the "Marketplace" browse list because it is a private app. You must search for it by name.
-4. Select your bot from the results.
-5. Click **Add** or **Chat** to start a 1:1 conversation.
-6. Send "Hello" to trigger the assistant!
-
-## Public URL (Webhook-only)
-
-Google Chat webhooks require a public HTTPS endpoint. For security, **only expose the `/googlechat` path** to the internet. Keep the Symi dashboard and other sensitive endpoints on your private network.
-
-### Option A: Tailscale Funnel (Recommended)
-
-Use Tailscale Serve for the private dashboard and Funnel for the public webhook path. This keeps `/` private while exposing only `/googlechat`.
-
-1. **Check what address your gateway is bound to:**
-
-   ```bash
-   ss -tlnp | grep 18789
-   ```
-
-   Note the IP address (e.g., `127.0.0.1`, `0.0.0.0`, or your Tailscale IP like `100.x.x.x`).
-
-2. **Expose the dashboard to the tailnet only (port 8443):**
-
-   ```bash
-   # If bound to localhost (127.0.0.1 or 0.0.0.0):
-   tailscale serve --bg --https 8443 http://127.0.0.1:18789
-
-   # If bound to Tailscale IP only (e.g., 100.106.161.80):
-   tailscale serve --bg --https 8443 http://100.106.161.80:18789
-   ```
-
-3. **Expose only the webhook path publicly:**
-
-   ```bash
-   # If bound to localhost (127.0.0.1 or 0.0.0.0):
-   tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
-
-   # If bound to Tailscale IP only (e.g., 100.106.161.80):
-   tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
-   ```
-
-4. **Authorize the node for Funnel access:**
-   If prompted, visit the authorization URL shown in the output to enable Funnel for this node in your tailnet policy.
-
-5. **Verify the configuration:**
-
-   ```bash
-   tailscale serve status
-   tailscale funnel status
-   ```
-
-Your public webhook URL will be:
-`https://<node-name>.<tailnet>.ts.net/googlechat`
-
-Your private dashboard stays tailnet-only:
-`https://<node-name>.<tailnet>.ts.net:8443/`
-
-Use the public URL (without `:8443`) in the Google Chat app config.
-
-> Note: This configuration persists across reboots. To remove it later, run `tailscale funnel reset` and `tailscale serve reset`.
-
-### Option B: Reverse Proxy (Caddy)
-
-If you use a reverse proxy like Caddy, only proxy the specific path:
-
-```caddy
-your-domain.com {
-    reverse_proxy /googlechat* localhost:18789
-}
-```
-
-With this config, any request to `your-domain.com/` will be ignored or returned as 404, while `your-domain.com/googlechat` is safely routed to Symi.
-
-### Option C: Cloudflare Tunnel
-
-Configure your tunnel's ingress rules to only route the webhook path:
-
-- **Path**: `/googlechat` -> `http://localhost:18789/googlechat`
-- **Default Rule**: HTTP 404 (Not Found)
-
-## How it works
-
-1. Google Chat sends webhook POSTs to the gateway. Each request includes an `Authorization: Bearer <token>` header.
-2. Symi verifies the token against the configured `audienceType` + `audience`:
-   - `audienceType: "app-url"` → audience is your HTTPS webhook URL.
-   - `audienceType: "project-number"` → audience is the Cloud project number.
-3. Messages are routed by space:
-   - DMs use session key `agent:<agentId>:googlechat:dm:<spaceId>`.
-   - Spaces use session key `agent:<agentId>:googlechat:group:<spaceId>`.
-4. DM access is pairing by default. Unknown senders receive a pairing code; approve with:
-   - `symi pairing approve googlechat <code>`
-5. Group spaces require @-mention by default. Use `botUser` if mention detection needs the app’s user name.
-
-## Targets
-
-Use these identifiers for delivery and allowlists:
-
-- Direct messages: `users/<userId>` (recommended) or raw email `name@example.com` (mutable principal).
-- Deprecated: `users/<email>` is treated as a user id, not an email allowlist.
-- Spaces: `spaces/<spaceId>`.
-
-## Config highlights
-
-```json5
-{
-  channels: {
-    googlechat: {
-      enabled: true,
-      serviceAccountFile: "/path/to/service-account.json",
-      audienceType: "app-url",
-      audience: "https://gateway.example.com/googlechat",
-      webhookPath: "/googlechat",
-      botUser: "users/1234567890", // optional; helps mention detection
-      dm: {
-        policy: "pairing",
-        allowFrom: ["users/1234567890", "name@example.com"],
-      },
-      groupPolicy: "allowlist",
-      groups: {
-        "spaces/AAAA": {
-          allow: true,
-          requireMention: true,
-          users: ["users/1234567890"],
-          systemPrompt: "Short answers only.",
-        },
-      },
-      actions: { reactions: true },
-      typingIndicator: "message",
-      mediaMaxMb: 20,
-    },
-  },
-}
-```
-
-Notes:
-
-- Service account credentials can also be passed inline with `serviceAccount` (JSON string).
-- Default webhook path is `/googlechat` if `webhookPath` isn’t set.
-- Reactions are available via the `reactions` tool and `channels action` when `actions.reactions` is enabled.
-- `typingIndicator` supports `none`, `message` (default), and `reaction` (reaction requires user OAuth).
-- Attachments are downloaded through the Chat API and stored in the media pipeline (size capped by `mediaMaxMb`).
-
-## Troubleshooting
-
-### 405 Method Not Allowed
-
-If Google Cloud Logs Explorer shows errors like:
-
-```
-status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed
-```
-
-This means the webhook handler isn't registered. Common causes:
-
-1. **Channel not configured**: The `channels.googlechat` section is missing from your config. Verify with:
-
-   ```bash
-   symi config get channels.googlechat
-   ```
-
-   If it returns "Config path not found", add the configuration (see [Config highlights](#config-highlights)).
-
-2. **Plugin not enabled**: Check plugin status:
-
-   ```bash
-   symi plugins list | grep googlechat
-   ```
-
-   If it shows "disabled", add `plugins.entries.googlechat.enabled: true` to your config.
-
-3. **Gateway not restarted**: After adding config, restart the gateway:
-
-   ```bash
-   symi gateway restart
-   ```
-
-Verify the channel is running:
-
-```bash
-symi channels status
-# Should show: Google Chat default: enabled, configured, ...
-```
-
-### Other issues
-
-- Check `symi channels status --probe` for auth errors or missing audience config.
-- If no messages arrive, confirm the Chat app's webhook URL + event subscriptions.
-- If mention gating blocks replies, set `botUser` to the app's user resource name and verify `requireMention`.
-- Use `symi logs --follow` while sending a test message to see if requests reach the gateway.
-
-Related docs:
-
-- [Gateway configuration](/gateway/configuration)
-- [Security](/gateway/security)
-- [Reactions](/tools/reactions)

package/docs/channels/grammy.md

@@ -1,31 +0,0 @@
----
-summary: "Telegram Bot API integration via grammY with setup notes"
-read_when:
-  - Working on Telegram or grammY pathways
-title: grammY
----
-
-# grammY Integration (Telegram Bot API)
-
-# Why grammY
-
-- TS-first Bot API client with built-in long-poll + webhook helpers, middleware, error handling, rate limiter.
-- Cleaner media helpers than hand-rolling fetch + FormData; supports all Bot API methods.
-- Extensible: proxy support via custom fetch, session middleware (optional), type-safe context.
-
-# What we shipped
-
-- **Single client path:** fetch-based implementation removed; grammY is now the sole Telegram client (send + gateway) with the grammY throttler enabled by default.
-- **Gateway:** `monitorTelegramProvider` builds a grammY `Bot`, wires mention/allowlist gating, media download via `getFile`/`download`, and delivers replies with `sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument`. Supports long-poll or webhook via `webhookCallback`.
-- **Proxy:** optional `channels.telegram.proxy` uses `undici.ProxyAgent` through grammY’s `client.baseFetch`.
-- **Webhook support:** `webhook-set.ts` wraps `setWebhook/deleteWebhook`; `webhook.ts` hosts the callback with health + graceful shutdown. Gateway enables webhook mode when `channels.telegram.webhookUrl` + `channels.telegram.webhookSecret` are set (otherwise it long-polls).
-- **Sessions:** direct chats collapse into the agent main session (`agent:<agentId>:<mainKey>`); groups use `agent:<agentId>:telegram:group:<chatId>`; replies route back to the same channel.
-- **Config knobs:** `channels.telegram.botToken`, `channels.telegram.dmPolicy`, `channels.telegram.groups` (allowlist + mention defaults), `channels.telegram.allowFrom`, `channels.telegram.groupAllowFrom`, `channels.telegram.groupPolicy`, `channels.telegram.mediaMaxMb`, `channels.telegram.linkPreview`, `channels.telegram.proxy`, `channels.telegram.webhookSecret`, `channels.telegram.webhookUrl`, `channels.telegram.webhookHost`.
-- **Live stream preview:** optional `channels.telegram.streaming` sends a temporary message and updates it with `editMessageText`. This is separate from channel block streaming.
-- **Tests:** grammy mocks cover DM + group mention gating and outbound send; more media/webhook fixtures still welcome.
-
-Open questions
-
-- Optional grammY plugins (throttler) if we hit Bot API 429s.
-- Add more structured media tests (stickers, voice notes).
-- Make webhook listen port configurable (currently fixed to 8787 unless wired through the gateway).

package/docs/channels/group-messages.md

@@ -1,82 +0,0 @@
----
-summary: "Behavior and config for WhatsApp group message handling (mentionPatterns are shared across surfaces)"
-read_when:
-  - Changing group message rules or mentions
-title: "Group Messages"
----
-
-# Group messages (WhatsApp web channel)
-
-Goal: let Symi sit in WhatsApp groups, wake up only when pinged, and keep that thread separate from the personal DM session.
-
-## What’s implemented (2025-12-03)
-
-- Activation modes: `mention` (default) or `always`. `mention` requires a ping (real WhatsApp @-mentions via `mentionedJids`, regex patterns, or the bot’s E.164 anywhere in the text). `always` wakes the agent on every message but it should reply only when it can add meaningful value; otherwise it returns the silent token `NO_REPLY`. Defaults can be set in config (`channels.whatsapp.groups`) and overridden per group via `/activation`. When `channels.whatsapp.groups` is set, it also acts as a group allowlist (include `"*"` to allow all).
-- Group policy: `channels.whatsapp.groupPolicy` controls whether group messages are accepted (`open|disabled|allowlist`). `allowlist` uses `channels.whatsapp.groupAllowFrom` (fallback: explicit `channels.whatsapp.allowFrom`). Default is `allowlist` (blocked until you add senders).
-- Per-group sessions: session keys look like `agent:<agentId>:whatsapp:group:<jid>` so commands such as `/verbose on` or `/think high` (sent as standalone messages) are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads.
-- Context injection: **pending-only** group messages (default 50) that _did not_ trigger a run are prefixed under `[Chat messages since your last reply - for context]`, with the triggering line under `[Current message - respond to this]`. Messages already in the session are not re-injected.
-- Sender surfacing: every group batch now ends with `[from: Sender Name (+E164)]` so Pi knows who is speaking.
-- Ephemeral/view-once: we unwrap those before extracting text/mentions, so pings inside them still trigger.
-- Group system prompt: on the first turn of a group session (and whenever `/activation` changes the mode) we inject a short blurb into the system prompt like `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` If metadata isn’t available we still tell the agent it’s a group chat.
-
-## Config example (WhatsApp)
-
-Add a `groupChat` block to `~/.symi/symi.json` so display-name pings work even when WhatsApp strips the visual `@` in the text body:
-
-```json5
-{
-  channels: {
-    whatsapp: {
-      groups: {
-        "*": { requireMention: true },
-      },
-    },
-  },
-  agents: {
-    list: [
-      {
-        id: "main",
-        groupChat: {
-          historyLimit: 50,
-          mentionPatterns: ["@?symi", "\\+?15555550123"],
-        },
-      },
-    ],
-  },
-}
-```
-
-Notes:
-
-- The regexes are case-insensitive; they cover a display-name ping like `@symi` and the raw number with or without `+`/spaces.
-- WhatsApp still sends canonical mentions via `mentionedJids` when someone taps the contact, so the number fallback is rarely needed but is a useful safety net.
-
-### Activation command (owner-only)
-
-Use the group chat command:
-
-- `/activation mention`
-- `/activation always`
-
-Only the owner number (from `channels.whatsapp.allowFrom`, or the bot’s own E.164 when unset) can change this. Send `/status` as a standalone message in the group to see the current activation mode.
-
-## How to use
-
-1. Add your WhatsApp account (the one running Symi) to the group.
-2. Say `@symi …` (or include the number). Only allowlisted senders can trigger it unless you set `groupPolicy: "open"`.
-3. The agent prompt will include recent group context plus the trailing `[from: …]` marker so it can address the right person.
-4. Session-level directives (`/verbose on`, `/think high`, `/new` or `/reset`, `/compact`) apply only to that group’s session; send them as standalone messages so they register. Your personal DM session remains independent.
-
-## Testing / verification
-
-- Manual smoke:
-  - Send an `@symi` ping in the group and confirm a reply that references the sender name.
-  - Send a second ping and verify the history block is included then cleared on the next turn.
-- Check gateway logs (run with `--verbose`) to see `inbound web message` entries showing `from: <groupJid>` and the `[from: …]` suffix.
-
-## Known considerations
-
-- Heartbeats are intentionally skipped for groups to avoid noisy broadcasts.
-- Echo suppression uses the combined batch string; if you send identical text twice without mentions, only the first will get a response.
-- Session store entries will appear as `agent:<agentId>:whatsapp:group:<jid>` in the session store (`~/.symi/agents/<agentId>/sessions/sessions.json` by default); a missing entry just means the group hasn’t triggered a run yet.
-- Typing indicators in groups follow `agents.defaults.typingMode` (default: `message` when unmentioned).