better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/wecom-callback.md

@@ -0,0 +1,179 @@
+---
+sidebar_position: 15
+---
+
+# WeCom Callback (Self-Built App)
+
+Connect Hermes to WeCom (Enterprise WeChat) as a self-built enterprise application using the callback/webhook model.
+
+:::info WeCom Bot vs WeCom Callback
+Hermes supports two WeCom integration modes:
+- **[WeCom Bot](wecom.md)** — bot-style, connects via WebSocket. Simpler setup, works in group chats.
+- **WeCom Callback** (this page) — self-built app, receives encrypted XML callbacks. Shows as a first-class app in users' WeCom sidebar. Supports multi-corp routing.
+:::
+
+See also: [WeCom Bot](./wecom.md) for the bot-style integration.
+
+> Run `hermes gateway setup` and pick **WeCom Callback** for a guided walk-through.
+
+## How It Works
+
+1. You register a self-built application in the WeCom Admin Console
+2. WeCom pushes encrypted XML to your HTTP callback endpoint
+3. Hermes decrypts the message, queues it for the agent
+4. Immediately acknowledges (silent — nothing displayed to the user)
+5. The agent processes the request (typically 3–30 minutes)
+6. The reply is delivered proactively via the WeCom `message/send` API
+
+## Prerequisites
+
+- A WeCom enterprise account with admin access
+- `aiohttp` and `httpx` Python packages (included in the default install)
+- A publicly reachable server for the callback URL (or a tunnel like ngrok)
+
+## Setup
+
+### 1. Create a Self-Built App in WeCom
+
+1. Go to [WeCom Admin Console](https://work.weixin.qq.com/) → **Applications** → **Create App**
+2. Note your **Corp ID** (shown at the top of the admin console)
+3. In the app settings, create a **Corp Secret**
+4. Note the **Agent ID** from the app's overview page
+5. Under **Receive Messages**, configure the callback URL:
+   - URL: `http://YOUR_PUBLIC_IP:8645/wecom/callback`
+   - Token: Generate a random token (WeCom provides one)
+   - EncodingAESKey: Generate a key (WeCom provides one)
+
+### 2. Configure Environment Variables
+
+Add to your `.env` file:
+
+```bash
+WECOM_CALLBACK_CORP_ID=your-corp-id
+WECOM_CALLBACK_CORP_SECRET=your-corp-secret
+WECOM_CALLBACK_AGENT_ID=1000002
+WECOM_CALLBACK_TOKEN=your-callback-token
+WECOM_CALLBACK_ENCODING_AES_KEY=your-43-char-aes-key
+
+# Optional
+# WECOM_CALLBACK_HOST=  # optional pin; unset = dual-stack (all interfaces, IPv4+IPv6)
+WECOM_CALLBACK_PORT=8645
+WECOM_CALLBACK_ALLOWED_USERS=user1,user2
+```
+
+### 3. Start the Gateway
+
+```bash
+hermes gateway
+```
+
+(Use `hermes gateway start` only after `hermes gateway install` has registered the systemd/launchd service.)
+
+The callback adapter starts an HTTP server on the configured port. WeCom will verify the callback URL via a GET request, then begin sending messages via POST.
+
+## Configuration Reference
+
+Set these in `config.yaml` under `platforms.wecom_callback.extra`, or use environment variables:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `corp_id` | — | WeCom enterprise Corp ID (required) |
+| `corp_secret` | — | Corp secret for the self-built app (required) |
+| `agent_id` | — | Agent ID of the self-built app (required) |
+| `token` | — | Callback verification token (required) |
+| `encoding_aes_key` | — | 43-character AES key for callback encryption (required) |
+| `host` | unset (dual-stack: all interfaces, IPv4+IPv6) | Bind address for the HTTP callback server |
+| `port` | `8645` | Port for the HTTP callback server |
+| `path` | `/wecom/callback` | URL path for the callback endpoint |
+
+## Multi-App Routing
+
+For enterprises running multiple self-built apps (e.g., across different departments or subsidiaries), configure the `apps` list in `config.yaml`:
+
+```yaml
+platforms:
+  wecom_callback:
+    enabled: true
+    extra:
+      host: "0.0.0.0"
+      port: 8645
+      apps:
+        - name: "dept-a"
+          corp_id: "ww_corp_a"
+          corp_secret: "secret-a"
+          agent_id: "1000002"
+          token: "token-a"
+          encoding_aes_key: "key-a-43-chars..."
+        - name: "dept-b"
+          corp_id: "ww_corp_b"
+          corp_secret: "secret-b"
+          agent_id: "1000003"
+          token: "token-b"
+          encoding_aes_key: "key-b-43-chars..."
+```
+
+Users are scoped by `corp_id:user_id` to prevent cross-corp collisions. When a user sends a message, the adapter records which app (corp) they belong to and routes replies through the correct app's access token.
+
+## Access Control
+
+Restrict which users can interact with the app:
+
+```bash
+# Allowlist specific users
+WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu
+
+# Or allow all users
+WECOM_CALLBACK_ALLOW_ALL_USERS=true
+```
+
+## Endpoints
+
+The adapter exposes:
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/wecom/callback` | URL verification handshake (WeCom sends this during setup) |
+| POST | `/wecom/callback` | Encrypted message callback (WeCom sends user messages here) |
+| GET | `/health` | Health check — returns `{"status": "ok"}` |
+
+## Encryption
+
+All callback payloads are encrypted with AES-CBC using the EncodingAESKey. The adapter handles:
+
+- **Inbound**: Decrypt XML payload, verify SHA1 signature
+- **Outbound**: Replies sent via proactive API (not encrypted callback response)
+
+The crypto implementation is compatible with Tencent's official WXBizMsgCrypt SDK.
+
+## Limitations
+
+- **No streaming** — replies arrive as complete messages after the agent finishes
+- **No typing indicators** — the callback model doesn't support typing status
+- **Text only** — currently supports text messages for input; image/file/voice input not yet implemented. The agent is aware of outbound media capabilities via the WeCom platform hint (images, documents, video, voice).
+- **Response latency** — agent sessions take 3–30 minutes; users see the reply when processing completes
+
+## Troubleshooting
+
+**Signature verification failing.**
+WeCom signs every request with the **Token** you registered in the admin
+console. A mismatch between the token configured in Hermes and the token the
+admin console expects is the most common cause. Re-copy both the **Token** and
+**EncodingAESKey** from the admin console — they're easy to truncate. Whitespace
+in `~/.hermes/.env` values around `=` will also break signature checks. After
+fixing, restart `hermes gateway run`.
+
+**Callback URL not reachable / verification step fails.**
+WeCom hits the public URL you registered. Confirm:
+1. Your reverse proxy / tunnel forwards `/wecom/callback` to the gateway's port.
+2. The URL in the admin console is HTTPS (WeCom rejects plain HTTP).
+3. From outside your network, `curl -i https://<your-domain>/wecom/callback`
+   returns something other than a timeout (a 4xx without query params is fine —
+   it just means the listener is reachable).
+
+**Port not reachable / listener not bound.**
+Check `hermes gateway run` logs for the bound host/port. If the adapter bound to
+`127.0.0.1` you must front it with a reverse proxy or tunnel — WeCom's servers
+can't reach loopback. Leave `extra.host` unset so the default dual-stack
+bind (all interfaces, IPv4+IPv6) applies, or pin an interface in `config.yaml` (plus
+`allowed_source_cidrs` if exposing directly) or keep loopback and use a tunnel
+such as Cloudflare Tunnel / nginx.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/wecom.md

@@ -0,0 +1,306 @@
+---
+sidebar_position: 14
+title: "WeCom (Enterprise WeChat)"
+description: "Connect Hermes Agent to WeCom via the AI Bot WebSocket gateway"
+---
+
+# WeCom (Enterprise WeChat)
+
+Connect Hermes to [WeCom](https://work.weixin.qq.com/) (企业微信), Tencent's enterprise messaging platform. The adapter uses WeCom's AI Bot WebSocket gateway for real-time bidirectional communication — no public endpoint or webhook needed.
+
+See also: [WeCom Callback](./wecom-callback.md) for inbound webhook setup.
+
+## Prerequisites
+
+- A WeCom organization account
+- An AI Bot created in the WeCom Admin Console
+- The Bot ID and Secret from the bot's credentials page
+- Python packages: `aiohttp` and `httpx`
+
+## Setup
+
+### Step 1: Create an AI Bot
+
+#### Recommended: Scan-to-Create (one command)
+
+```bash
+hermes gateway setup
+```
+
+Select **WeCom** and scan the QR code with your WeCom mobile app. Hermes will automatically create a bot application with the correct permissions and save the credentials.
+
+The setup wizard will:
+1. Display a QR code in your terminal
+2. Wait for you to scan it with the WeCom mobile app
+3. Automatically retrieve the Bot ID and Secret
+4. Guide you through access control configuration
+
+#### Alternative: Manual Setup
+
+If scan-to-create is not available, the wizard falls back to manual input:
+
+1. Log in to the [WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame)
+2. Navigate to **Applications** → **Create Application** → **AI Bot**
+3. Configure the bot name and description
+4. Copy the **Bot ID** and **Secret** from the credentials page
+5. Run `hermes gateway setup`, select **WeCom**, and enter the credentials when prompted
+
+:::warning
+Keep the Bot Secret private. Anyone with it can impersonate your bot.
+:::
+
+### Step 2: Configure Hermes
+
+#### Option A: Interactive Setup (Recommended)
+
+```bash
+hermes gateway setup
+```
+
+Select **WeCom** and follow the prompts. The wizard will guide you through:
+- Bot credentials (via QR scan or manual entry)
+- Access control settings (allowlist, pairing mode, or open access)
+- Home channel for notifications
+
+#### Option B: Manual Configuration
+
+Add the following to `~/.hermes/.env`:
+
+```bash
+WECOM_BOT_ID=your-bot-id
+WECOM_SECRET=your-secret
+
+# Optional: restrict access
+WECOM_ALLOWED_USERS=user_id_1,user_id_2
+
+# Optional: home channel for cron/notifications
+WECOM_HOME_CHANNEL=chat_id
+```
+
+### Step 3: Start the gateway
+
+```bash
+hermes gateway
+```
+
+## Features
+
+- **WebSocket transport** — persistent connection, no public endpoint needed
+- **DM and group messaging** — configurable access policies
+- **Per-group sender allowlists** — fine-grained control over who can interact in each group
+- **Media support** — images, files, voice, video upload and download
+- **AES-encrypted media** — automatic decryption for inbound attachments
+- **Quote context** — preserves reply threading
+- **Markdown rendering** — rich text responses
+- **Reply correlation** — responses are correlated to the inbound message context
+- **Auto-reconnect** — exponential backoff on connection drops
+
+:::note Streaming and typing indicators
+The WeCom adapter streams responses natively over WeCom's `msgtype: "stream"`
+protocol: the client shows a thinking/typing bubble as soon as a turn starts,
+and the reply renders token-by-token in a single bubble as the model
+generates it. Tool-call progress is folded into the same bubble. Native
+streaming is enabled by default (`display.platforms.wecom.streaming: true` in
+`config.yaml`); set it to `false` to restore single-shot delivery.
+:::
+
+## Configuration Options
+
+Set these in `config.yaml` under `platforms.wecom.extra`:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `bot_id` | — | WeCom AI Bot ID (required) |
+| `secret` | — | WeCom AI Bot Secret (required) |
+| `websocket_url` | `wss://openws.work.weixin.qq.com` | WebSocket gateway URL |
+| `dm_policy` | `open` | DM access: `open`, `allowlist`, `disabled`, `pairing` |
+| `group_policy` | `open` | Group access: `open`, `allowlist`, `disabled` |
+| `allow_from` | `[]` | User IDs allowed for DMs (when dm_policy=allowlist) |
+| `group_allow_from` | `[]` | Group IDs allowed (when group_policy=allowlist) |
+| `groups` | `{}` | Per-group configuration (see below) |
+| `stream_keepalive_enabled` | `false` | Send periodic keepalive frames to refresh WeCom's ~6-minute reply-stream window on long turns |
+| `stream_keepalive_interval_seconds` | `120` | Keepalive frame cadence when enabled |
+| `stream_safe_duration_seconds` | `330` | Stream age after which finalize prefers the reliable proactive send |
+
+## Access Policies
+
+### DM Policy
+
+Controls who can send direct messages to the bot:
+
+| Value | Behavior |
+|-------|----------|
+| `open` | Anyone can DM the bot (default) |
+| `allowlist` | Only user IDs in `allow_from` can DM |
+| `disabled` | All DMs are ignored |
+| `pairing` | Pairing mode (for initial setup) |
+
+```bash
+WECOM_DM_POLICY=allowlist
+```
+
+### Group Policy
+
+Controls which groups the bot responds in:
+
+| Value | Behavior |
+|-------|----------|
+| `open` | Bot responds in all groups (default) |
+| `allowlist` | Bot only responds in group IDs listed in `group_allow_from` |
+| `disabled` | All group messages are ignored |
+
+```bash
+WECOM_GROUP_POLICY=allowlist
+```
+
+### Per-Group Sender Allowlists
+
+For fine-grained control, you can restrict which users are allowed to interact with the bot within specific groups. This is configured in `config.yaml`:
+
+```yaml
+platforms:
+  wecom:
+    enabled: true
+    extra:
+      bot_id: "your-bot-id"
+      secret: "your-secret"
+      group_policy: "allowlist"
+      group_allow_from:
+        - "group_id_1"
+        - "group_id_2"
+      groups:
+        group_id_1:
+          allow_from:
+            - "user_alice"
+            - "user_bob"
+        group_id_2:
+          allow_from:
+            - "user_charlie"
+        "*":
+          allow_from:
+            - "user_admin"
+```
+
+**How it works:**
+
+1. The `group_policy` and `group_allow_from` controls determine whether a group is allowed at all.
+2. If a group passes the top-level check, the `groups.<group_id>.allow_from` list (if present) further restricts which senders within that group can interact with the bot.
+3. A wildcard `"*"` group entry serves as a default for groups not explicitly listed.
+4. Allowlist entries support the `*` wildcard to allow all users, and entries are case-insensitive.
+5. Entries can optionally use the `wecom:user:` or `wecom:group:` prefix format — the prefix is stripped automatically.
+
+If no `allow_from` is configured for a group, all users in that group are allowed (assuming the group itself passes the top-level policy check).
+
+## Media Support
+
+### Inbound (receiving)
+
+The adapter receives media attachments from users and caches them locally for agent processing:
+
+| Type | How it's handled |
+|------|-----------------|
+| **Images** | Downloaded and cached locally. Supports both URL-based and base64-encoded images. |
+| **Files** | Downloaded and cached. Filename is preserved from the original message. |
+| **Voice** | Voice message text transcription is extracted if available. |
+| **Mixed messages** | WeCom mixed-type messages (text + images) are parsed and all components extracted. |
+
+**Quoted messages:** Media from quoted (replied-to) messages is also extracted, so the agent has context about what the user is replying to.
+
+### AES-Encrypted Media Decryption
+
+WeCom encrypts some inbound media attachments with AES-256-CBC. The adapter handles this automatically:
+
+- When an inbound media item includes an `aeskey` field, the adapter downloads the encrypted bytes and decrypts them using AES-256-CBC with PKCS#7 padding.
+- The AES key is the base64-decoded value of the `aeskey` field (must be exactly 32 bytes).
+- The IV is derived from the first 16 bytes of the key.
+- This requires the `cryptography` Python package (`pip install cryptography`).
+
+No configuration is needed — decryption happens transparently when encrypted media is received.
+
+### Outbound (sending)
+
+| Method | What it sends | Size limit |
+|--------|--------------|------------|
+| `send` | Markdown text messages | 4000 chars |
+| `send_image` / `send_image_file` | Native image messages | 10 MB |
+| `send_document` | File attachments | 20 MB |
+| `send_voice` | Voice messages (AMR format only for native voice) | 2 MB |
+| `send_video` | Video messages | 10 MB |
+
+**Chunked upload:** Files are uploaded in 512 KB chunks through a three-step protocol (init → chunks → finish). The adapter handles this automatically.
+
+**Automatic downgrade:** When media exceeds the native type's size limit but is under the absolute 20 MB file limit, it is automatically sent as a generic file attachment instead:
+
+- Images > 10 MB → sent as file
+- Videos > 10 MB → sent as file
+- Voice > 2 MB → sent as file
+- Non-AMR audio → sent as file (WeCom only supports AMR for native voice)
+
+Files exceeding the absolute 20 MB limit are rejected with an informational message sent to the chat.
+
+## Reply-Mode Responses
+
+When the bot receives a message via the WeCom callback, the adapter remembers the inbound request ID. If a response is sent while the request context is still active, the adapter uses WeCom's reply-mode (`aibot_respond_msg`) to correlate the response directly to the inbound message. This provides a more natural conversation experience in the WeCom client.
+
+When a native reply stream is active, the response streams incrementally through reply-mode `msgtype: "stream"` frames. If the inbound request context has expired or is unavailable (or a stream frame fails), the adapter falls back to proactive message sending via `aibot_send_msg`.
+
+Reply-mode also works for media: uploaded media can be sent as a reply to the originating message.
+
+## Connection and Reconnection
+
+The adapter maintains a persistent WebSocket connection to WeCom's gateway at `wss://openws.work.weixin.qq.com`.
+
+### Connection Lifecycle
+
+1. **Connect:** Opens a WebSocket connection and sends an `aibot_subscribe` authentication frame with the bot_id and secret.
+2. **Heartbeat:** Sends application-level ping frames every 30 seconds to keep the connection alive.
+3. **Listen:** Continuously reads inbound frames and dispatches message callbacks.
+
+### Reconnection Behavior
+
+On connection loss, the adapter uses exponential backoff to reconnect:
+
+| Attempt | Delay |
+|---------|-------|
+| 1st retry | 2 seconds |
+| 2nd retry | 5 seconds |
+| 3rd retry | 10 seconds |
+| 4th retry | 30 seconds |
+| 5th+ retry | 60 seconds |
+
+After each successful reconnection, the backoff counter resets to zero. All pending request futures are failed on disconnect so callers don't hang indefinitely.
+
+### Deduplication
+
+Inbound messages are deduplicated using message IDs with a 5-minute window and a maximum cache of 1000 entries. This prevents double-processing of messages during reconnection or network hiccups.
+
+## All Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `WECOM_BOT_ID` | ✅ | — | WeCom AI Bot ID |
+| `WECOM_SECRET` | ✅ | — | WeCom AI Bot Secret |
+| `WECOM_ALLOWED_USERS` | — | _(empty)_ | Comma-separated user IDs for the gateway-level allowlist |
+| `WECOM_HOME_CHANNEL` | — | — | Chat ID for cron/notification output |
+| `WECOM_WEBSOCKET_URL` | — | `wss://openws.work.weixin.qq.com` | WebSocket gateway URL |
+| `WECOM_DM_POLICY` | — | `open` | DM access policy |
+| `WECOM_GROUP_POLICY` | — | `open` | Group access policy |
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `WECOM_BOT_ID and WECOM_SECRET are required` | Set both env vars or configure in setup wizard |
+| `WeCom startup failed: aiohttp not installed` | Install aiohttp: `pip install aiohttp` |
+| `WeCom startup failed: httpx not installed` | Install httpx: `pip install httpx` |
+| `invalid secret (errcode=40013)` | Verify the secret matches your bot's credentials |
+| `Timed out waiting for subscribe acknowledgement` | Check network connectivity to `openws.work.weixin.qq.com` |
+| Bot doesn't respond in groups | Check `group_policy` setting and ensure the group ID is in `group_allow_from` |
+| Bot ignores certain users in a group | Check per-group `allow_from` lists in the `groups` config section |
+| Media decryption fails | Install `cryptography`: `pip install cryptography` |
+| `cryptography is required for WeCom media decryption` | The inbound media is AES-encrypted. Install: `pip install cryptography` |
+| Voice messages sent as files | WeCom only supports AMR format for native voice. Other formats are auto-downgraded to file. |
+| `File too large` error | WeCom has a 20 MB absolute limit on all file uploads. Compress or split the file. |
+| Images sent as files | Images > 10 MB exceed the native image limit and are auto-downgraded to file attachments. |
+| `Timeout sending message to WeCom` | The WebSocket may have disconnected. Check logs for reconnection messages. |
+| `WeCom websocket closed during authentication` | Network issue or incorrect credentials. Verify bot_id and secret. |