@turmind/halo 1.3.0 → 1.3.2

package/bundled-docs/design/wecom.md

@@ -0,0 +1,217 @@
+# WeCom (企业微信) 智能机器人 Channel — Design
+
+Let the user talk to Halo from WeCom on their phone or desktop, sharing the same workspace + sessions as the web side. All channels are peers — each one is a subscriber + caller against SessionManager.
+
+## Architecture
+
+```
+                       ┌── ws/ (web channel)            ─┐
+                       ├── channels/telegram/            │
+Halo server (9527) ──┤├── channels/wechat/              ├── SessionManager
+                       ├── channels/slack/               │    (per workspace, via Registry)
+                       ├── channels/feishu/              │
+                       └── channels/wecom/ ←─ long-connect (wss) ─┘
+                                    ↕ WSClient (@wecom/aibot-node-sdk)
+                           wss://openws.work.weixin.qq.com
+```
+
+WeCom uses the official SDK's `WSClient` (`@wecom/aibot-node-sdk` ^1.0.7, MIT) to maintain a persistent WebSocket connection. Structurally it is the closest sibling of the Feishu channel (long-connect, one account = one bot), with one big difference: **there is no HTTP send API at all**. Inbound callbacks (`aibot_msg_callback`), replies (`aibot_respond_msg`), proactive pushes (`aibot_send_msg`) and media upload (`aibot_upload_media_*`) are all frames on the same socket. Only file *download* is HTTP (a 5-minute URL + per-file AES key, decrypted by the SDK).
+
+## Data model
+
+### Workspace ↔ Bot mapping
+
+One 智能机器人 (= one botId + secret pair) is bound to one workspace. A workspace can bind multiple bots. `accountId = botId` as-is (charset enforced to `[\w-]` on POST, since the id becomes a media subpath and a URL segment).
+
+### Session strategy
+
+- Session ID format: `wecom_<key>_<createdAtBase36>` where `key` is `normalizeWecomId(...)` — WeCom ids may contain `@` and `.`, which are folded to `-` so the id passes `isSafeIdSegment` and the `_`-delimited prefix format
+- **Single chat (DM)**: `key = userid` → one session per user, latest-by-prefix (`setOverrideOnCreate: false`, same as telegram / wechat). Label `WeCom: <userid>`
+- **Group**: `key = chatid` → **one shared session per group, not per user**. Different people `@`-ing the bot land in the same conversation; the sender travels as the `user:` tag and the group as `thread:` in the agent-input tag. Label `WeCom group: <chatid>`. There is no thread concept in WeCom group chat, so no per-thread keying à la slack / feishu
+- Sessions live under the bot's bound workspace and use the highest-priority agent (falls back to `default` only when none exists)
+- Access level inherited from the account's `accessLevel` field (see below)
+
+### Access level
+
+Each account carries `accessLevel: 'full' | 'workspace' | 'readonly' | 'observer'` (default `readonly`):
+- `full` — no restrictions (no sandbox)
+- `workspace` — tool execution runs inside a bwrap sandbox with the workspace mounted read-write
+- `readonly` — tool execution runs inside a bwrap sandbox with the workspace mounted read-only; readonly sessions only receive read-only tools
+
+There is no per-user whitelist; the bot's 可见范围 (visibility scope) in the WeCom admin console is the only boundary. Because a group shares one session, `full` in a group means every member drives the same shell.
+
+### Storage
+
+WeCom bot accounts are stored in the unified channel DB: `~/.halo/secrets/channels/channels.db`, table `channel_accounts` with `channel_type = 'wecom'`. See [storage.md](storage.md#channel_accounts) for the full schema. **The channel owns no table of its own and added no migration** — `channel_accounts` predates it (created by `channel-db.ts`'s `CREATE TABLE IF NOT EXISTS`), and everything WeCom-specific lives in the row's `config` JSON.
+
+WeCom-specific config JSON fields: `botId`, `secret`, `lastActiveChatId`.
+
+- `lastActiveChatId` is the raw `userid` (single) or `chatid` (group) of the most recent inbound message, written by `rememberLastActiveChat()` in `channels/shared/accounts.ts` (idempotent). Not consumed by cron dispatch (the dispatcher requires an explicit `chatId`).
+- `secret` is never returned by `GET /api/wecom/accounts` and is not patchable — a fresh POST with the same `botId` rotates it.
+
+Inbound media lands under `<workspace>/.halo/assets/wecom/inbound/<accountId>/<date>/`.
+
+### Authentication model
+
+- `botId` + `secret` are long-lived credentials from the bot's **API 模式 → 长连接** settings in the WeCom admin console (the secret is long-connect-specific; callback-URL mode uses a different Token / EncodingAESKey and enabling it invalidates the long-connect one)
+- Auth is one `aibot_subscribe` frame sent by the SDK right after the socket opens; there is no token to mint or refresh
+- Halo does **not** probe credentials on POST — WeCom has no HTTP endpoint to validate against. Bad credentials surface as a `WSAuthFailureError` (`code = 'WS_AUTH_FAILURE_EXHAUSTED'`) on the client's `error` event after `maxAuthFailureAttempts: 3`; the handler then drops the client and the account stays dark until the next `startAccount`
+- **One live connection per bot, server-side.** A newer `aibot_subscribe` with the same botId kicks the older connection with an `event.disconnected_event` frame, after which the SDK deliberately does not reconnect (`isManualClose = true`). The handler honours that — reconnecting would just kick the other side back — logs `kicked by a newer connection for this bot (another halo instance?)` and leaves the account dark. Disable + enable (or re-POST) to reclaim the bot
+
+### Proactive sending (cron)
+
+The wecom cron-dispatcher (`channels/wecom/cron-dispatcher.ts`) requires an explicit `chatId` — there is no fallback to `lastActiveChatId`. When a cron fires:
+
+1. **Explicit `chatId` on the target** — set when the cron was created from inside a WeCom chat (auto-pinned via `CommandContext.channel.chatId`). Shape: `<userid>` for a single chat, `<chatid>` for a group — exactly what `pickConversation` cached as `chatKey`. `sendMessage(chatId, { msgtype: 'markdown', … })` omits `chat_type`; the server's compat mode (`chat_type = 0`) resolves single vs group from the id.
+2. **Admin-UI cron without explicit target** — throws `wecom cron target requires an explicit chatId …` and the run fails visibly. There is no `/search` route (WeCom exposes no directory API on this channel), so the target must be typed as `wecom:<accountId>:<chatId>`.
+
+Because the push rides the handler's socket, the dispatcher borrows it through the exported `liveClients: Map<accountId, WSClient>` (set on `authenticated`, cleared on stop / kick / auth exhaustion). No live client → `{ ok: false, error: 'wecom long-connect not active' }` rather than queueing. WeCom additionally refuses pushes to a user / group that has never messaged the bot, and rate-limits each conversation to 30 msgs/min · 1000/hour (replies and pushes combined).
+
+**`MEDIA:` is not implemented for cron** — the dispatcher declares no `supportsMedia`, so `dispatchToTargets` hands it the original text with `MEDIA:` lines intact (the path degrades to visible text, same caveat as telegram / feishu in [cron.md](cron.md#dispatch-model)). The realtime uploader (`sendWecomMedia` in `handler.ts`) is anchored to an inbound `req_id`; wiring cron up means switching it to `sendMediaMessage(chatid, …)` and flipping `supportsMedia: true`.
+
+## Modules
+
+Files: `packages/server/src/channels/wecom/`
+
+- `types.ts` — `WecomAccount` (no envelope types — the SDK ships `WsFrame` / `BaseMessage` / `TextMessage` / … and the handler imports those)
+- `accounts.ts` — DAL (listAccounts / listEnabledAccounts / getAccount / insertAccount / updateAccount / deleteAccount) + `normalizeWecomId`
+- `handler.ts` — `WSClient` lifecycle, `msgid` dedupe, content ingestion (text / voice transcript / image / mixed / file / video), group-mention strip, `replyStream` + media upload; session routing + listener/route bookkeeping come from `channels/shared/inbound.ts` (`InboundBridge` / `deliverInbound` / `dispatchChannelCommand`). Exports `liveClients` and the pure helpers `pickConversation` / `stripGroupMention` / `sniffImageMime`
+- `event-adapter.ts` — AgentSessionEvent stream → coalesced stream-message replies (`WecomResponder`, buffer + flush at paragraph boundaries)
+- `cron-dispatcher.ts` — registers the cron dispatcher, requires explicit chatId targets, sends via `liveClients`
+- `descriptor.ts` — ServerChannelDescriptor entry point (registered in `channels/descriptors.ts` after feishu)
+
+Routes: `packages/server/src/routes/wecom.ts`
+
+- `GET /api/wecom/accounts` — list bot accounts (admin; `secret` omitted)
+- `POST /api/wecom/accounts` — register / upsert a bot (`accountId = botId`; stop → start the long-connect)
+- `PATCH /api/wecom/accounts/:id` — update `label` / `workspacePath` / `enabled` / `accessLevel` / `language`; credentials are not patchable
+- `DELETE /api/wecom/accounts/:id` — remove + stop
+
+No `/search` route (see cron above). Admin UI: `packages/admin/src/features/wecom/wecom-settings.tsx`.
+
+Session-prefix kind `'wecom'` is registered in `channels/shared/session-prefix.ts`; `channels/shared/markdown.ts` has no `formatForWecom` on purpose (see Event coalescing).
+
+## Bot lifecycle
+
+1. User registers a bot via the API (provides botId + secret + workspace); no remote validation
+2. Server stores the account, calls `stopAccount` (idempotent) then `startAccount` — the stop must fully `disconnect()` before the new socket subscribes, or the new connection would kick its own predecessor
+3. `startAccount` builds `new WSClient({ botId, secret, maxReconnectAttempts: -1, maxAuthFailureAttempts: 3, logger })` and calls `connect()` (synchronous; auth happens on `authenticated`). The SDK handles heartbeat (30 s ping), reconnect with exponential back-off (infinite on network drops), and the auth retry budget
+4. `authenticated` → `liveClients.set(accountId, client)`; `event.disconnected_event` (kicked) or `error` with `WS_AUTH_FAILURE_EXHAUSTED` → client dropped, `liveClients.delete`
+5. `stopAccount` = `bridge.closeAll()` (drains queued chunks, then releases reply routes) → `wsClient.disconnect()` → `liveClients.delete` → state removed
+6. On graceful shutdown the descriptor's `shutdown` calls `stopAll()`
+
+## Long-connect frame protocol
+
+All frames are JSON `{ cmd, headers: { req_id }, body }`; responses echo `headers.req_id` plus `errcode` / `errmsg`. The SDK owns the wire; the handler only sees SDK events. Commands in play:
+
+| cmd | Direction | Used by halo |
+|---|---|---|
+| `aibot_subscribe` | client → server | SDK, on open (`{ bot_id, secret }`) |
+| `ping` / pong | client → server | SDK heartbeat |
+| `aibot_msg_callback` | server → client | inbound message → `'message'` event |
+| `aibot_event_callback` | server → client | events; only `disconnected_event` is handled (kicked). `enter_chat` / `template_card_event` / `feedback_event` are ignored |
+| `aibot_respond_msg` | client → server | `replyStream(frame, streamId, content, finish)` — every reply |
+| `aibot_send_msg` | client → server | `sendMessage(chatid, { msgtype: 'markdown' })` — cron only |
+| `aibot_upload_media_init` / `_chunk` / `_finish` | client → server | `uploadMedia(buffer, { type, filename })` — chunked (≤ 512 KB × ≤ 100), returns `media_id` (valid 3 days) |
+
+**Reply model.** A stream reply is keyed to the callback's `req_id` and carries its own `stream.id`; the same `stream.id` can be re-sent to update the bubble until `finish: true`. Halo does **not** stream: every flushed chunk / hint / command reply is sent as a *new* `stream.id` with `finish: true` in one go — one finished bubble each. This keeps the responder identical to the other channels and sidesteps the 10-minute cap on an open stream (measured from its first frame). Replies must reference the inbound `req_id`, so the reply route stored per session is `{ reqId, chatType, chatId }`, refreshed on every inbound message (the route is read lazily at send time, as in slack / feishu).
+
+## Message handling flow
+
+`'message'` event (`WsFrame<BaseMessage>`):
+
+1. Drop if the account is missing / disabled, or the body has no `msgid` / `from`
+2. **Dedupe on `msgid`** — per-account `Set` + FIFO array capped at 500. WeCom redelivers on reconnect
+3. `pickConversation(body)`: `chattype === 'group' && chatid` → group key; otherwise single-chat key on `from.userid` (both normalized, see Session strategy)
+4. Ingest content by `msgtype` (media URLs are valid 5 minutes, so downloads happen here, before queueing):
+   - `text` → `text.content`
+   - `voice` → `voice.content` is already speech-to-text; forwarded as `[语音转文字] <text>`. No audio to save
+   - `image` / `mixed` image items → `downloadFile(url, aeskey)`, mime sniffed from magic bytes (png / gif / else jpeg), saved as `kind: 'image'`, base64 pushed to `images` for vision, note `[图片已保存: path]`
+   - `mixed` text items → joined with `\n`
+   - `file` / `video` → downloaded, 20 MB cap (`[… 超过 20MB,未保存]`), saved as `kind: 'file' | 'video'` under the sender filename (fallback `file`), note `[文件 "name" 已保存: path]` / `[视频已保存: path]`; failures `[文件下载失败 name: reason]` / `[视频下载失败: reason]` — same wording as wechat / feishu so the admin renders them identically
+   - Image / voice / file / video only arrive in single chat (WeCom doesn't forward them from groups)
+5. Group text: strip leading `@token` mentions (`/^(@\S+\s*)+/`). WeCom only delivers group messages that `@` the bot, so there is no `shouldRespond` check. A multi-word bot name leaves its tail as residue — preferable to guessing the name and eating the user's first word
+6. Slash command dispatch — **single chat only** (a group's shared session belongs to everyone). `/workspace switch` persists the new path on the account row; the reply goes out via `replyStream`
+7. Skip if neither text/notes nor images remain
+8. Hand off to `deliverInbound` ([shared skeleton](telegram.md#shared-inbound-skeleton)): create or retrieve the session (with inherited access level) + goal-mode overlay; busy / compacting hint via `replyStream`; refresh the route and attach the `WecomResponder` listener once; `sm.sendUserMessage(sessionId, agentInput, images?)` with `[channel: wecom | user: <userid>]` (+ ` | thread: <chatid>` in groups)
+
+## Event coalescing (WecomResponder)
+
+Stream `content` is capped at 20480 **bytes**. The responder splits at 5000 **chars** — 5000 × 4 bytes (UTF-8 worst case) stays under the cap, so it never has to measure bytes. Strategy:
+
+- Buffer only streamed text flagged `final` (the turn's wrap-up; pre-tool-call filler is dropped) until `complete`
+- Flush fires on **any** `complete`, so a multi-round queue drain ships each merged turn as its own message (see [session.md](session.md#message-queue-and-drain))
+- Over 5000 chars → split at paragraph boundary (`\n\n`) via the shared `splitText` (`channels/shared/chunk.ts`), else hard-cut
+- `system` / `error` events flush early so users always see something before the run ends
+- **No markdown formatter** — WeCom stream content renders CommonMark natively (headings, bold, lists, quotes, links, code, tables), so text is sent as the agent wrote it. `channels/shared/markdown.ts` lists wecom under "leave alone"
+- `MEDIA:<path>` markers intercepted and sent via native media upload
+- Sub-agent events dropped (visible in web UI only)
+
+Chunk sends are serialized per responder (`sendTail` promise chain, audit A-L3) and `close()` returns the drain promise so `InboundBridge` keeps the reply route alive until the last chunk is out — identical to the feishu adapter, see [feishu.md](feishu.md#event-coalescing-feishuresponder) for the history.
+
+## Media support
+
+**Inbound:** text, voice (as transcript), images (vision + saved), mixed (text + images), files, videos — single chat only for everything but text. Saved under `<workspace>/.halo/assets/wecom/inbound/<accountId>/<date>/`.
+
+**Outbound routing** (`sendWecomMedia`, path must be under the workspace — `isMediaPathAllowed`):
+- `.png` / `.jpg` / `.jpeg` / `.gif` → `uploadMedia(type: 'image')` → `replyMedia('image')`
+- `.mp4` → `uploadMedia(type: 'video')` → `replyMedia('video')`
+- everything else (`.webp` / `.bmp` / `.mov` / documents / audio) → `uploadMedia(type: 'file')` → `replyMedia('file')` — WeCom's `image` accepts png/jpg/gif only and `video` mp4 only
+- > 20 MB → refused; the user sees `t('handler.upload_failed')` (`⚠️ 文件上传失败：name — error`)
+- Voice is never sent: WeCom expects AMR, which the agent doesn't produce
+
+## Similarities vs Feishu and Telegram
+
+| Aspect | WeCom | Feishu | Telegram |
+|--------|-------|--------|----------|
+| **Inbound delivery** | Long-connect (wss), official SDK | Long-connect (wss), official SDK | Long-polling |
+| **Outbound path** | Same wss socket (no HTTP API) | Open API over HTTPS | Bot API over HTTPS |
+| **Session model** | Per user in DM, **one shared per group** | Per-thread in groups, p2p anchored | Per-user (one active) |
+| **Mention required** | Enforced by WeCom (only `@` messages delivered) | Yes in groups, no in p2p | No |
+| **Cron target** | Explicit `userid` / `chatid`, needs live socket | Explicit chatId only | Explicit numeric chatId only |
+| **Credential check on add** | None (no HTTP API) | `bot/v3/info` probe | `getMe` probe |
+| **Markdown** | Native CommonMark, sent as-is | Stripped to plain text | Plain text |
+| **Text limit** | 5000 chars (20480-byte cap) | ~5000 chars | ~4000 chars |
+| **Connection limit** | One per bot — newer kicks older, no auto-reconnect after kick | SDK reconnects freely | N/A |
+
+## Configuration
+
+### WeCom bot setup
+
+1. WeCom admin console → 应用管理 → 智能机器人 → create, set the visibility scope
+2. On the bot's config page enable **API 模式**, choose **长连接**
+3. Copy **BotID** and **Secret** (long-connect secret, distinct from callback-mode Token / EncodingAESKey)
+
+### Register to Halo
+
+```bash
+curl -X POST http://localhost:9527/api/wecom/accounts \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "botId": "aib_xxxxxxxxxxxx",
+    "secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    "workspacePath": "/home/user/my-workspace",
+    "accessLevel": "full",
+    "label": "My WeCom Bot"
+  }'
+```
+
+Server stores the row and opens the long-connect immediately; auth outcome shows up in `[WeCom]` logs, not in the response.
+
+## Scope and out-of-scope
+
+Supported: single-chat text / voice transcript / image / mixed / file / video; group text (mention enforced upstream); Markdown replies; media sending (image / video / file); slash commands (single chat only); per-account access level; cron push to an explicit user or group.
+
+Not supported: streaming partial replies into WeCom (each reply is one finished bubble); template cards, welcome messages (`enter_chat`), feedback events; per-user sessions inside a group; cron `MEDIA:` attachments; a target-search route; voice sending.
+
+## Key file references
+
+- Long-connect: `packages/server/src/channels/wecom/handler.ts:connect()`
+- Conversation key: `packages/server/src/channels/wecom/handler.ts:pickConversation()`
+- Content ingestion: `packages/server/src/channels/wecom/handler.ts:ingestContent()`
+- Event dispatch: `packages/server/src/channels/wecom/handler.ts:handleInbound()`
+- Media upload: `packages/server/src/channels/wecom/handler.ts:sendWecomMedia()`
+- Cron dispatch: `packages/server/src/channels/wecom/cron-dispatcher.ts:dispatch()`
+- Event coalescing: `packages/server/src/channels/wecom/event-adapter.ts:WecomResponder`
+- REST routes: `packages/server/src/routes/wecom.ts`
+- Tests: `packages/server/test/wecom-inbound.test.ts` (pure helpers), `wecom-responder.test.ts` (chunking / ordering / markdown pass-through)

package/bundled-docs/design/ws.md

@@ -55,6 +55,8 @@ Liveness probes bound how long a zombie lives, but a chat sent *into* the zombie
 
 Source: [handler.ts](../../../packages/server/src/ws/handler.ts) — top-level `switch (msg.type)` in the connection handler.
 
+Both directions are typed in `packages/core/src/protocol/ws-frames.ts` (`WsClientMessage` / `WsServerMessage`, exported from `@turmind/halo-core/protocol`) and imported by server `ws/handler.ts` and admin `ws-client.ts` — that file is the source of truth for field names; this doc explains semantics. `__ping__` is a member of `WsClientMessage.type` (previously the server compared it via a string cast).
+
 | Type | Purpose |
 |---|---|
 | `subscribe` | Subscribe to a session (load history, re-attach detached) |
@@ -64,7 +66,7 @@ Source: [handler.ts](../../../packages/server/src/ws/handler.ts) — top-level `
 | `chat:interrupt` | Interrupt the in-flight turn now (aborts a command mid-run); the server then folds any queued messages into one follow-up turn → `interruptSession`. Admin chat esc maps to this. A compacting session cancels the compact instead (same as `chat:stop`). |
 | `session:clear` | Non-destructive /session new: save the current, release its listener, create fresh (handled inline) — see [Command dispatch](#command-dispatch) |
 | `session:delete` | Delete session files + cascade-delete descendants in SQLite (handled inline) |
-| `exchange:delete` | Delete one exchange (a user turn + its responses): **soft-delete** in the UI log (`deleted: true` markers, kept visible/greyed) + **physical-delete** the whole turn from `rawMessages` (LLM context) → `deleteExchange`. Fields: `userOrdinal` (0-based index among *main-conversation* user turns, i.e. excluding `taskId` sub-agent messages — matches the admin's `isMainConversationMessage` count), optional `sessionId` / `projectId`. Rejected (→ `error`) while the session is running or compacting, and permanently once the session has archived UI-log segments — that refusal carries `code: 'archived'` (an ordinal is only meaningful while both sides agree where the log starts; archiving moves the start). See [session.md](session.md#exchange-deletion-soft-ui--hard-raw). |
+| `exchange:delete` | Delete one exchange (a user turn + its responses): **soft-delete** in the UI log (`deleted: true` markers, kept visible/greyed) + **physical-delete** the whole turn from `rawMessages` (LLM context) → `deleteExchange`. Fields: `userOrdinal` (0-based index among *main-conversation* user turns, i.e. excluding `taskId` sub-agent messages — matches the admin's `isMainConversationMessage` count), `archiveCount` (the archived-segment count the client's view was opened against — its archive anchor, from the `state:snapshot` it got on subscribe), optional `sessionId` / `projectId`. Rejected (→ `error`) while the session is running or compacting. The server also compares `archiveCount` against the on-disk header count (`readArchiveCount`); only a **mismatch** is refused, with `code: 'archived'` ("… archived history since it was opened — reopen it to delete individual turns") — a session with archives can still be deleted from as long as the anchor matches. See [session.md](session.md#exchange-deletion-soft-ui--hard-raw). |
 | `command:<name>` | Route through shared `dispatchCommand` (see [command.md](command.md)); `/session compact` handled inline for UI callbacks |
 | `terminal:start` | Spawn a new PTY |
 | `terminal:input` | Send keystrokes. `terminalId` is **required** — an id-less frame is logged and dropped (it used to fall back to the first entry of the process-global terminal map, which with several admin connections open could write into another browser's PTY) |
@@ -101,6 +103,8 @@ Source: [event-processor.ts:48-97](../../../packages/server/src/ws/event-process
 
 `chat:thinking` / `chat:stream` / `chat:followup` / `agent:tool_call` / `agent:tool_result` additionally carry `replay: true` when synthesized by the reattach path (never on live events) — see [Reconnect flow](#reconnect-flow) step 6.
 
+`chat:system` producers (`session-manager.ts`'s `stop` event handling): a `max_tokens` stop emits `⚠️ [<agent>] Response truncated: output token limit reached.`; a `refusal` stop (Anthropic `stop_reason: "refusal"`, HTTP 200 — the model declined, not an error) emits `⚠️ [<agent>] Model declined to respond (<category>): <explanation> — …` suggesting `/new` (see [session.md](session.md#resilient-execution-loop)).
+
 Server-internal flags on `AgentSessionEvent` that are **not** carried into the WS frame: `stream.final` (marks the turn's wrap-up text vs. pre-tool filler — consumed by channel responders and the cli, see [session.md](session.md#message-queue-and-drain)) and `complete.batchBoundary`. The admin renders every streamed block, so neither is needed on the wire.
 
 ### Other Server → Client messages
@@ -127,12 +131,14 @@ Server-internal flags on `AgentSessionEvent` that are **not** carried into the W
 
 ### `error` frames: optional `code`
 
-`{ type: 'error', error }` normally means "something failed"; the admin prefixes it with `Error:` when rendering. An **expected refusal** the server already phrased for the user adds a `code` (currently only `'archived'`, from `exchange:delete`), and the admin renders such a frame verbatim without the prefix. So: add `code` when the message is a complete user-facing sentence, omit it when the client should present it as a fault.
+`{ type: 'error', error }` normally means "something failed"; the admin prefixes it with `Error:` when rendering. An **expected refusal** the server already phrased for the user adds a `code` (currently only `'archived'`, from `exchange:delete`, when the client's `archiveCount` anchor no longer matches the on-disk count), and the admin renders such a frame verbatim without the prefix. So: add `code` when the message is a complete user-facing sentence, omit it when the client should present it as a fault.
 
 ### Archive anchor in `state:snapshot`
 
 `archiveCount` rides only the snapshots sent on **subscribe** and **reattach** — one header read per session open. The per-turn snapshots and the snapshot pushed after `exchange:delete` deliberately omit it: the client's "load older" cursor is an anchor pinned at the moment the session was opened, and a segment written mid-session (a compact while the tab is open) must not move it. The client then requests segments over HTTP (`GET /api/sessions/logs/:id/archive/:n`), not WS — one whole segment per call, cached client-side because segments are immutable. See [session.md](session.md#ui-log-archiving).
 
+The same anchor is what the client sends back as `archiveCount` on `exchange:delete`, so the server can tell a stale ordinal from a live one.
+
 ## WS Handler as a thin session client
 
 > **History**: originally the WS handler directly created and owned Orchestrator instances in a `client.orchestrators` map. Agent logic is now fully owned by SessionManager; the WS handler is a thin routing client.

package/bundled-docs/dev/api.md

@@ -4,6 +4,8 @@ All REST endpoints are served by Hono on port 9527 at `/api/`.
 
 Auth: most `/api/*` routes require a valid JWT cookie (`halo_token`). Exceptions in `PUBLIC_PATHS` (`middleware/auth.ts`) bypass the cookie: `/api/auth/login|check|logout` (but **not** `/api/auth/change-password`), the web-channel routes (`/api/web/chat|sessions|stop|history|subscribe|file`), `/api/show/state|session`, and `/api/metrics` — these are unauthenticated or use a web-channel `x-token` instead.
 
+**Trust model.** The admin cookie is a single-tenant, all-or-nothing credential: there is one password (`~/.halo/secrets/config.yaml`), one JWT secret, and no roles. A valid `halo_token` equals full control of the server process — every workspace's files (`/api/files/*` project-scoped, `/api/fs/browse` unrestricted), shell via the WS terminal, channel credentials, git credentials, cron jobs, and the ability to mint web-channel tokens at any access level. Routes under the cookie therefore don't re-check "who" beyond the cookie itself; per-user isolation is the job of channel accounts (`x-token` with `readonly` / `workspace` / `full`), not of the admin. Consequences worth knowing when adding routes: (1) never put a cookie-gated route in `PUBLIC_PATHS` to "make it easier for a client" — that's the entire boundary; (2) a route that accepts a path or id from the client still needs traversal / shape checks (`isSafeIdSegment`, `assertPathAllowed`), because the *web-channel* surface reuses the same helpers and is multi-user; (3) if multi-user admin ever lands, the first change is a role claim in the JWT plus per-route checks, and this paragraph becomes the checklist.
+
 Compression: every response negotiates gzip/deflate via `hono/compress` (`threshold: 1024` — bodies under 1 KiB pass through uncompressed), mounted after CORS so it covers both `/api/*` JSON and the served admin static assets. `text/event-stream` (SSE) is excluded, so `/api/web/chat`'s streamed reply is unaffected; WS upgrades never enter the Hono fetch pipeline either.
 
 ## Health
@@ -98,14 +100,14 @@ The get endpoint returns the full session file. If only `rawMessages` is present
 ## Channel accounts — shared field validation
 
 `workspacePath` and `accessLevel` are validated at the REST boundary on both
-POST and PATCH across all five channels (web / wechat / telegram / slack /
-feishu) — one shared pair of checks in `channels/shared/accounts.ts`, so the
-five can't drift (they did: four PATCHes never checked `isAbsolute`, and only
+POST and PATCH across all six channels (web / wechat / telegram / slack /
+feishu / wecom) — one shared pair of checks in `channels/shared/accounts.ts`, so the
+six can't drift (they did: four PATCHes never checked `isAbsolute`, and only
 wechat's PATCH rejected an unknown `accessLevel`):
 
 | Field | Rule | 400 body |
 |---|---|---|
-| `accessLevel` | Must be one of the channel's legal levels when present; absent = leave unchanged. **web** allows `full` / `workspace` / `readonly` / `observer` (halo-city / metrics tokens are minted here); the **four chat channels** allow only `full` / `workspace` / `readonly` — `observer` is a dashboard role, not a chat identity | `{error: "accessLevel must be one of: …"}` |
+| `accessLevel` | Must be one of the channel's legal levels when present; absent = leave unchanged. **web** allows `full` / `workspace` / `readonly` / `observer` (halo-city / metrics tokens are minted here); the **five chat channels** allow only `full` / `workspace` / `readonly` — `observer` is a dashboard role, not a chat identity | `{error: "accessLevel must be one of: …"}` |
 | `workspacePath` | Absolute and existing. Empty string / relative path → 400; PATCH treats *absence* as "leave the binding alone" but validates any value supplied. On success `ensureWorkspaceHalo()` scaffolds `.halo/` | `{error: "workspacePath must be absolute"}` / `{error: "workspace path not found"}` |
 
 POST additionally rejects a missing `workspacePath` with `{error: "workspacePath required"}`. Stored levels are still normalized to `readonly` on read, but the db no longer holds a value no code path agrees with.
@@ -161,6 +163,19 @@ File: `packages/server/src/routes/feishu.ts`. Admin cookie auth. Inbound uses lo
 | DELETE | `/api/feishu/accounts/:id` | Stop the wss stream and delete the row |
 | GET | `/api/feishu/accounts/:id/search?q=` | Search chats the bot is a member of (used by the cron form). Returns `{hits}` (max 20) |
 
+## WeCom Channel
+
+File: `packages/server/src/routes/wecom.ts`. Admin cookie auth. Inbound uses the 智能机器人 long-connect wss (no webhook); there is **no HTTP send API**, so replies and cron pushes ride the same socket.
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/api/wecom/accounts` | List accounts. Row: `accountId`, `botId`, `workspacePath`, `workspaceMissing`, `label`, `enabled`, `accessLevel`, `language`, timestamps. `secret` is **never** returned |
+| POST | `/api/wecom/accounts` | Create / upsert. Body: `{botId, secret, workspacePath, label?, accessLevel?, language?}`. `accountId = botId` as-is (must match `[A-Za-z0-9_-]` — it becomes a media subpath + URL segment). **No credential probe** — 智能机器人 has no HTTP endpoint to validate a pair against; bad credentials surface as `WS_AUTH_FAILURE_EXHAUSTED` in the `[WeCom]` server log. Stops any live socket, then (re)connects. Returns `{accountId, botId}` |
+| PATCH | `/api/wecom/accounts/:id` | Update `label` / `workspacePath` / `enabled` / `accessLevel` / `language`. `botId` / `secret` are **not** patchable — re-POST to rotate. Stops then reconnects if still enabled |
+| DELETE | `/api/wecom/accounts/:id` | Close the wss stream and delete the row |
+
+No `/search` endpoint: the cron form takes the WeCom `chatId` verbatim (a `userid` for a single chat, a group `chatid` for a group) — the 智能机器人 API has no contact/chat directory to query. `workspacePath` / `accessLevel` follow the [shared validation rules](#channel-accounts--shared-field-validation). See [design/wecom.md](../design/wecom.md).
+
 ## Cron
 
 File: `packages/server/src/routes/cron.ts`. Admin cookie auth. REST CRUD over `cron_jobs` + read-only `cron_runs`. Mutations call `reloadAll()` / `scheduleJob()` / `unscheduleJob()` so in-memory croner stays in sync with the db. Each mutation also broadcasts `cron:job_changed`.

package/bundled-docs/guide/channels/README.md

@@ -10,6 +10,7 @@ This folder has one onboarding guide per channel. Pick the one you want and foll
 | [Telegram](telegram.md) | Personal use on phone, small whitelisted teams | BotFather token | Long-poll |
 | [Slack](slack.md) | Team workspaces (multi-user, channels, threads) | Slack App + Socket Mode (`xoxb-` + `xapp-` tokens) | WebSocket (Socket Mode) |
 | [Feishu / Lark](feishu.md) | Chinese enterprise teams | Feishu open-platform App (`appId` + `appSecret`) + long connection | WebSocket (long-connect) |
+| [WeCom](wecom.md) | Chinese enterprise teams on 企业微信 (single chat + groups) | 智能机器人 (Bot ID + Secret) + long connection | WebSocket (long-connect) |
 | [WeChat](wechat.md) | China-side personal use; mobile-first | iLink-style bot, login by scanning a QR | Long-poll |
 | [ACP](acp.md) | Claude Code (or other ACP clients) driving a remote halo | Web token + adapter CLI | JSON-RPC over stdio |
 
@@ -21,6 +22,7 @@ This folder has one onboarding guide per channel. Pick the one you want and foll
    halo server ─────────┤── channels/telegram/   ── grammy long-poll
    (port 9527)            ├── channels/slack/      ── Socket Mode wss
                           ├── channels/feishu/     ── long-connect wss
+                          ├── channels/wecom/      ── long-connect wss (aibot sdk)
                           └── channels/wechat/     ── ilinkai long-poll
                                   ↓
                           SessionManager (per workspace)
@@ -40,6 +42,7 @@ What the admin UI actually asks you for. Auto-filled fields (botUsername, botUse
 | Telegram | Bot token, workspace path | Label, access level, language, allowed users | BotFather `/newbot` |
 | Slack | Bot token (`xoxb-`), App token (`xapp-`), workspace path | Label, access level, language | api.slack.com → Create App → install + Socket Mode |
 | Feishu | App ID, App Secret, workspace path | Verification token, encrypt key, label, access level, language | open.feishu.cn → Create App + add bot capability |
+| WeCom | Bot ID, Secret, workspace path | Label, access level, language, allowed users | work.weixin.qq.com → 智能机器人 → create bot, copy Bot ID + Secret |
 | WeChat | Workspace path (set before scanning) | Label, access level, language | QR scan in admin UI; bot token comes back from the scan |
 
 ## Access level
@@ -57,6 +60,6 @@ When in doubt start at `readonly` and raise it later. The setting is on the **ac
 - Already know which channel you want → click the row above
 - New to halo and just want to chat in a browser → [Web](web.md)
 - Want to run halo from your IDE (Claude Code etc.) → [ACP](acp.md)
-- Setting up a team workspace → [Slack](slack.md) or [Feishu](feishu.md)
+- Setting up a team workspace → [Slack](slack.md), [Feishu](feishu.md) or [WeCom](wecom.md)
 
-For the design rationale and protocol details (not user-facing), see [docs/design/](../../design/) — `wechat.md`, `telegram.md`, `web.md`. Slack and Feishu design docs aren't written yet; the source of truth is the code under `packages/server/src/channels/{slack,feishu}/`.
+For the design rationale and protocol details (not user-facing), see [docs/design/](../../design/) — one file per channel: `web.md`, `telegram.md`, `slack.md`, `feishu.md`, `wecom.md`, `wechat.md`.

package/bundled-docs/guide/channels/feishu.md

@@ -92,6 +92,16 @@ Open halo admin → **Channels** → **Feishu** → **Add Account**:
 
 On submit halo calls Feishu's `tenant_access_token` + `bot/info` API to validate your credentials and auto-fill `botOpenId`. If that call fails the account isn't created and you'll see Feishu's error code inline (typical: `99991663` = wrong app secret, `99991668` = bot capability not enabled).
 
+### Who can talk to the bot — and what `full` means
+
+There is **no per-user whitelist** on Feishu accounts (unlike Telegram's `allowedUsers`): the access level applies to **every tenant member who can reach the bot** — anyone who DMs it or is in a group it's been added to. The boundary is Feishu's **app availability scope** (set when creating a version in Step 6 — 可用范围 / Availability: all members vs. selected departments / people), not halo.
+
+Pick the level with that in mind:
+
+- `readonly` — safe default for a tenant-wide bot; the agent can read and answer but not write files or run commands
+- `workspace` — the agent may write inside the bound workspace path; fine for a team that already shares that repo
+- `full` — the agent has shell access as the server user, and any reachable member can drive it. Reserve `full` for an app whose availability is narrowed to people you'd also give SSH to, or point it at a dedicated workspace / server.
+
 ## Step 8 — Test it
 
 In Feishu desktop / mobile:

package/bundled-docs/guide/channels/slack.md

@@ -96,6 +96,16 @@ Open halo admin → **Channels** → **Slack** → **Add Account**:
 
 On submit halo calls Slack's `auth.test` to validate the bot token and auto-fills `botUserId` and `teamId`. If that call fails the account isn't created and you'll see the Slack-returned error inline.
 
+### Who can talk to the bot — and what `full` means
+
+There is **no per-user whitelist** on Slack accounts (unlike Telegram's `allowedUsers`): the access level applies to **every member of the Slack workspace who can reach the bot** — anyone who DMs it or is in a channel it's been invited to. Membership is the boundary, and that boundary is managed on the Slack side (workspace invites, channel membership, app install scope), not in halo.
+
+Pick the level with that in mind:
+
+- `readonly` — safe default for a company-wide bot; the agent can read and answer but not write files or run commands
+- `workspace` — the agent may write inside the bound workspace path; fine for a team that already shares that repo
+- `full` — the agent has shell access as the server user, and any workspace member can drive it. Reserve `full` for a bot in a private channel with people you'd also give SSH to, or point it at a dedicated workspace / server.
+
 ## Step 8 — Test it
 
 1. In Slack, click the bot's name in the sidebar to start a DM → type `hello` → expect a streamed reply

package/bundled-docs/guide/channels/wechat.md

@@ -34,6 +34,8 @@ The form is **just the workspace + label + access level + language** — no bot
 
 Click **Generate QR**. Halo hits `ilinkai.weixin.qq.com` to mint a fresh QR code and starts a poll loop waiting for the scan.
 
+> **What the access level covers.** A WeChat account is bound to exactly one WeChat user — the one who scans — so there's no whitelist to configure; the scanner *is* the whitelist. The level you choose here is what that phone gets: `full` means whoever holds the unlocked phone has shell access as the server user. The same applies to invite QRs minted with `/qr full` from inside the chat — each scan creates a separate account at the level you named, so hand those out as you would an SSH key.
+
 ## Step 3 — Scan with WeChat
 
 1. Open WeChat on your phone

package/bundled-docs/guide/channels/wecom.md

@@ -0,0 +1,136 @@
+# WeCom (企业微信) 智能机器人
+
+Talk to a halo agent from WeCom — DM the bot, or `@`-mention it in any group it's been added to. Halo uses the 智能机器人 **long-connect** API mode (an outbound WebSocket from the server to `wss://openws.work.weixin.qq.com`), so **no public webhook URL is required**.
+
+## What you'll end up with
+
+- A 智能机器人 (intelligent bot) created in your company's WeCom admin console, switched to **API 模式 → 长连接**
+- Two credentials stored in halo: **Bot ID** and **Secret** (the long-connect secret — not the callback-mode Token / EncodingAESKey)
+- A bot account row pointing those credentials at one halo workspace
+
+## Step 1 — Create the intelligent bot
+
+1. Log in to the WeCom admin console (https://work.weixin.qq.com/wework_admin/) as a company admin
+2. Go to **应用管理 / App Management** → **智能机器人 / Intelligent Bot** → **创建 / Create**
+3. Fill name (e.g. `halo`), upload an avatar, pick the **可见范围 / visibility scope** (which departments / members can see and chat with the bot — this scope is your only access whitelist, see below)
+
+## Step 2 — Switch to API mode with long-connect
+
+On the bot's configuration page:
+
+1. Find **API 模式 / API mode** and enable it
+2. Pick **长连接 / Long connection** (NOT 设置接收消息回调地址 / "set a callback URL" — that's webhook mode and needs a public endpoint)
+3. The console now shows the long-connect credentials
+
+> API mode is either/or: switching the bot to callback-URL mode later invalidates the long-connect secret and drops halo's connection. Leave it on 长连接.
+
+## Step 3 — Copy Bot ID and Secret
+
+Same page, after Step 2:
+
+- **BotID** — the bot's unique id. Goes into halo as-is (it also becomes the account id)
+- **Secret** — the long-connect key. Treat like a password; halo never displays it again after you save
+
+## Step 4 — Add the account in halo admin
+
+Open halo admin → **Channels** → **WeCom** → **Add Bot**:
+
+| Field | Value |
+|---|---|
+| Bot ID | from Step 3 |
+| Secret | from Step 3 |
+| Bind to workspace | absolute path, e.g. `/home/ubuntu/my-project` |
+| Name | optional label |
+| Access level | `readonly` (default), `workspace`, or `full` |
+| Language | `en` or `zh` — for hints and command replies |
+
+There is **no credential check on submit** — WeCom has no HTTP endpoint to validate a Bot ID + Secret pair against. Halo stores the row and opens the long-connect immediately; a wrong secret shows up in the server logs as `[WeCom] <botId> error: … WS_AUTH_FAILURE_EXHAUSTED` after three attempts, and the bot stays dark until you re-add it with the right one. Re-submitting the form with the same Bot ID overwrites the stored secret and reconnects. Name, workspace, access level and language can be edited in place afterwards; Bot ID and Secret cannot — re-add to rotate them.
+
+### Who can talk to the bot — and what `full` means
+
+There is **no per-user whitelist** on WeCom accounts (unlike Telegram's `allowedUsers`): the access level applies to **every company member who can reach the bot** — anyone inside the bot's visibility scope who DMs it, plus anyone in a group it's been added to. The boundary is the **可见范围 / visibility scope** you set in Step 1, not halo.
+
+Pick the level with that in mind:
+
+- `readonly` — safe default for a company-wide bot; the agent can read and answer but not write files or run commands
+- `workspace` — the agent may write inside the bound workspace path; fine for a team that already shares that repo
+- `full` — the agent has shell access as the server user, and any reachable member can drive it. Reserve `full` for a bot whose visibility scope is narrowed to people you'd also give SSH to, or point it at a dedicated workspace / server.
+
+In groups the whole group shares **one** session (see below), so `full` in a group means every member is driving the same shell.
+
+## Step 5 — Test it
+
+In WeCom desktop / mobile:
+
+1. Search the bot's name → open the chat → send `hello` → expect a reply (the answer arrives as one message when the turn finishes — halo doesn't stream partial text into WeCom)
+2. Add the bot to a group: group settings → 添加群机器人 → pick it → `@halo hi` → expect a reply
+
+If nothing happens, check halo server logs for `[WeCom]` lines. `long-connect authenticated` means the socket is up; `kicked by a newer connection for this bot` means another process subscribed with the same Bot ID (see Common problems).
+
+## How halo handles inbound
+
+- **Single chat** (1:1 DM) — every message routes to the bot; one session per user
+- **Groups** — WeCom only delivers messages that `@`-mention the bot, so there is no mention check on halo's side; the leading `@BotName` token is stripped. **One shared session per group**, not per user — everyone in the group is talking to the same conversation
+- **Voice** — WeCom transcribes voice notes server-side; the agent receives the text prefixed `[语音转文字]`. No audio file is saved
+- **Images** — downloaded (decrypted) and fed to the LLM as multimodal content, also saved under `<workspace>/.halo/assets/wecom/inbound/<accountId>/<date>/`
+- **Files / videos** — downloaded and saved to the same folder (20 MB cap); the agent gets `[文件 "name" 已保存: path]` / `[视频已保存: path]`
+- Images, voice, files and videos only arrive in **single chat** — WeCom doesn't forward them from groups
+- **Duplicates** — WeCom may redeliver a message after a reconnect; halo dedupes on `msgid`
+
+### Outbound media
+
+When the agent emits a `MEDIA:<path>` line (a file under the workspace), halo uploads it and replies with the matching message type:
+
+| File | Sent as |
+|---|---|
+| `.png` / `.jpg` / `.jpeg` / `.gif` | image |
+| `.mp4` | video |
+| everything else (`.webp`, `.bmp`, `.mov`, `.pdf`, `.docx`, …) | file |
+
+20 MB cap — anything larger fails with a "⚠️ 文件上传失败" reply. Voice messages are never sent (WeCom expects AMR, which the agent doesn't produce).
+
+Replies render **Markdown natively** — headings, bold, lists, quotes, links, code blocks and tables all display as formatted text.
+
+## Slash commands
+
+Same set as the other channels — type as plain text in a **single chat** (commands are ignored in groups, where the shared session belongs to everyone):
+
+| Command | Effect |
+|---|---|
+| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` |
+| `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
+| `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
+| `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
+| `/help` | List commands — object commands show only the verbs you can run |
+
+## Cron jobs targeting WeCom
+
+When a cron job is created from inside a WeCom chat, the dispatcher pins that chat (the user's id in a DM, the group's chatid in a group) and pushes the result back there. To target a WeCom chat from the admin UI, pass the id explicitly — there is no search box (WeCom offers no directory API on this channel): `--targets wecom:<botId>:<userid|chatid>`. A job without an explicit target runs silently.
+
+Two WeCom rules to know:
+
+- Proactive pushes ride the **same long-connect** as inbound messages. If the bot is disabled, kicked, or its secret failed, the run records `wecom long-connect not active` and nothing is sent
+- WeCom only accepts a push to a user or group that has **messaged the bot at least once**. Send the bot a `hi` before scheduling reports to yourself
+
+## Common problems
+
+| Symptom | Cause / fix |
+|---|---|
+| `WS_AUTH_FAILURE_EXHAUSTED` in logs, bot never answers | Secret wrong, or the bot was switched back to callback-URL mode — redo Steps 2-3 and re-add |
+| `kicked by a newer connection for this bot` in logs | Only **one** connection per bot is allowed; a second halo instance (or the SDK sample script) subscribed with the same Bot ID. Stop the other one, then disable + enable the account in halo — halo deliberately does not auto-reconnect after a kick |
+| Cron run says `wecom long-connect not active` | Account disabled / kicked / auth failed — check the account toggle and logs |
+| Cron push returns an error for a user | That user has never messaged the bot; WeCom refuses cold pushes |
+| Replies to a group land as one long thread of context | Expected — groups share one session. Use a DM for a private session |
+| Sent a picture in a group, nothing happened | WeCom only forwards media in single chat |
+
+## Multi-bot setup
+
+One halo account = one bot. To bind a second workspace, create a second 智能机器人 (Steps 1-3) and add it as another account. Bots are company-scoped; a second company needs its own bot under that company's admin console.
+
+## Reference
+
+- Code: `packages/server/src/channels/wecom/`
+- Routes: `packages/server/src/routes/wecom.ts`
+- Admin UI: `packages/admin/src/features/wecom/wecom-settings.tsx`
+- SDK: [`@wecom/aibot-node-sdk`](https://github.com/WecomTeam/aibot-node-sdk) (official, MIT) — wire protocol, auth, heartbeat, media upload / decrypt
+- Design notes: [design/wecom.md](../../design/wecom.md)