@turmind/halo 0.1.9

package/bundled-docs/design/telegram.md

@@ -0,0 +1,161 @@
+# Telegram Channel — Design
+
+Let the user talk to Halo from Telegram, sharing the same workspace + sessions as the web and WeChat sides.
+
+## Architecture
+
+```
+                       ┌── ws/ (web channel)            ─┐
+                       ├── channels/weixin/              │
+Halo server (9527) ──┤                                 ├── SessionManager
+                       └── channels/telegram/            ─┘    (per workspace, via Registry)
+                               ↕ grammy long-poll
+                           api.telegram.org
+```
+
+All channels are peers — each one is a subscriber + caller against SessionManager.
+
+## Data model
+
+### Workspace ↔ Bot mapping
+
+One bot (= one BotFather token) is bound to one workspace. A workspace can bind multiple bots.
+
+### Session strategy
+
+- **One Telegram user → many sessions (one active at a time)**
+- Session ID format: `tg_<userId>_<createdAtBase36>` (e.g. `tg_123456789_m1abc`)
+- Sessions live under the bot's bound workspace and use the highest-priority agent (falls back to `default` only when none exists)
+- The web side sees these sessions in the session list (labelled `Telegram: <userId>`)
+- Access level inherited from the bot account
+
+### Access level
+
+Each account carries `accessLevel: 'full' | 'workspace' | 'readonly'` (default `readonly`). Same semantics as WeChat — `readonly` runs tools in a read-only bwrap sandbox, `workspace` runs tools in a read-write sandbox confined to the workspace, `full` is unrestricted (no sandbox).
+
+### Allowed users
+
+Optional whitelist (`allowedUsers` in config JSON): comma-separated user IDs or @usernames. Empty = allow everyone.
+
+### Storage
+
+Telegram bot accounts are stored in the unified channel DB: `~/.halo/secrets/channels/channels.db`, table `channel_accounts` with `channel_type = 'telegram'`. See [storage.md](storage.md#channel_accounts) for the full schema.
+
+Telegram-specific config JSON fields: `botToken`, `botUsername`, `allowedUsers`, `lastActiveChatId`.
+
+`lastActiveChatId` is a runtime cache of the most recent chat id the bot has exchanged messages with. Written by `rememberLastActiveChat()` in `channels/shared/accounts.ts` on every inbound message, but with a per-process hash so unchanged values never touch the db (idempotent — on the hot path we skip the read-modify-write entirely after the first sight). It is **not** used for cron dispatch (see below); it is kept as a runtime cache for any future "reply to whoever talked last" feature.
+
+### Proactive sending (cron)
+
+Halo can send to a Telegram chat without that user having messaged the bot first — Telegram's Bot API allows `sendMessage(chatId, text)` for any known chat id. Halo only requires that the chat id come from a *trusted source*.
+
+The telegram cron-dispatcher (`channels/telegram/cron-dispatcher.ts`) registers itself with `cron/dispatcher.ts`'s registry at boot and **requires an explicit `chatId`** (numeric — Telegram private-chat ids equal user ids):
+
+- Cron jobs created from inside a telegram chat via the `cron` skill auto-pin the current chat id (target `telegram:<account>:<chatId>`).
+- Admin-UI cron jobs that don't specify a target run silently — the result shows in the cron log, nothing is pushed.
+- `@username` entries are not accepted by `sendMessage`; the dispatcher rejects non-numeric values with a clear error.
+
+Earlier drafts considered "fan-out to every id in `allowedUsers`" or "fall back to `lastActiveChatId`", but in practice both pushed the cron output to strangers' chats. The cron creator's intent is "reach me, the person who set this up" — so the only target is what the caller passes explicitly.
+
+## Modules
+
+Files: `packages/server/src/channels/telegram/`
+
+- `types.ts` — TelegramAccount interface
+- `accounts.ts` — thin adapter over `channels/shared/accounts.ts` (maps config JSON ↔ TelegramAccount)
+- `handler.ts` — grammy Bot setup, command registration, message handling, polling loop
+- `event-adapter.ts` — LLM streaming events → Telegram messages (coalesce same as WeChat)
+
+Routes: `packages/server/src/routes/telegram.ts`
+
+- `POST /api/telegram/accounts` — register a bot (validates token via `getMe`)
+- `GET /api/telegram/accounts` — list bots
+- `PATCH /api/telegram/accounts/:id` — update config
+- `DELETE /api/telegram/accounts/:id` — remove + stop
+
+## Bot lifecycle
+
+1. User registers a bot via the API (provides token + workspace)
+2. Server calls `getMe` to validate; stores account; starts polling
+3. grammy's built-in long-polling handles reconnection / retries
+4. On graceful shutdown, `bot.stop()` is called for each active bot
+
+## Message handling flow
+
+`bot.on('message:text')`:
+1. Check user against `allowedUsers` whitelist
+2. Resolve workspace (check path exists on disk)
+3. Resolve or create active session for this Telegram userId
+4. If session is compacting → reply "⏳ wait"
+5. If session is busy → reply "🔄 queued"
+6. Register a `TelegramResponder` event listener (once per session)
+7. `sm.sendUserMessage(sessionId, agentInput)` with channel prefix
+
+Photos / documents trigger the same flow with file metadata in the text.
+
+## Slash commands (native Telegram /commands)
+
+| Command | Purpose |
+|---|---|
+| `/start` | Welcome message |
+| `/session new` | Create a new session |
+| `/session list` | List recent sessions (up to 20) |
+| `/session switch <index>` | Switch active session |
+| `/session stop` | Abort running task |
+| `/session compact` | Compress context |
+| `/workspace info` | Show workspace; `/workspace switch <path>` changes it (full only) |
+| `/help` | List commands |
+
+## Event coalescing (TelegramResponder)
+
+Same strategy as WeChat:
+- Buffer until `complete` event, then flush as one message
+- Flush happens on **any** `complete` — the responder doesn't read its `batchBoundary` flag, so a multi-round queue drain ships each merged turn as its own message instead of one blob (see [session.md](session.md#message-queue-and-drain))
+- If buffer exceeds 4000 chars (Telegram limit), split at paragraph boundary
+- `MEDIA:<path>` markers are intercepted and sent as native Telegram media
+- Errors flush immediately
+- Sub-agent events are dropped (visible in web UI only)
+
+## Media support
+
+Inbound: text, photos (file URL in text), documents (file URL in text).
+
+Outbound: the `send-file` skill produces `MEDIA:<path>` markers. The responder sends files via grammy's `InputFile`:
+- `.jpg/.png/.gif/.webp/.bmp` → `sendPhoto`
+- `.mp4/.mov/.webm` → `sendVideo`
+- `.ogg/.oga` → `sendVoice`
+- anything else → `sendDocument`
+
+## Configuration
+
+### BotFather setup
+
+1. `/newbot` → get token
+2. Optional: `/setcommands` to register the command menu:
+   ```
+   start - 开始
+   session - 会话管理（new/list/switch/stop/compact…）
+   agent - Agent 管理
+   skill - Skill 管理
+   ws - 查看/切换workspace
+   help - 帮助
+   ```
+
+### Register to Halo
+
+```bash
+curl -X POST http://localhost:9527/api/telegram/accounts \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "botToken": "123456:ABC-DEF...",
+    "workspacePath": "/home/user/my-workspace",
+    "accessLevel": "full",
+    "allowedUsers": "123456789,@myusername"
+  }'
+```
+
+## Scope and out-of-scope
+
+Supported: private chat text, photos, documents; slash commands; per-session access level; user whitelist; media sending.
+
+Not supported: group chats, inline queries, callback buttons, webhook mode (polling only).

package/bundled-docs/design/web.md

@@ -0,0 +1,222 @@
+# Web Channel — Design
+
+Browser-based access to Halo via token-authenticated HTTP API. Supports SSE streaming, slash commands, image/voice upload.
+
+## Architecture
+
+```
+                       ┌── ws/ (admin channel)             ─┐
+                       ├── channels/wechat/                 │
+Halo server (9527) ──┤── channels/telegram/               ├── SessionManager
+                       └── channels/web/                   ─┘    (per workspace, via Registry)
+                               ↕ HTTP + SSE
+                         web-demo (9528) ── browser
+                         or any HTTP client
+```
+
+Common slash commands (`/help`, `/evo`, and the object commands `/session`, `/agent`, `/skill`, `/workspace`) live in `channels/shared/commands.ts`; each channel handler is a thin adapter.
+
+Web channel is a public HTTP API on Halo. `packages/web-demo` is a standalone demo frontend that proxies requests through its own auth layer.
+
+## Data model
+
+### Account / Token
+
+One token = one web access point, bound to one workspace.
+
+Storage: `~/.halo/secrets/channels/channels.db`, table `channel_accounts` with `channel_type = 'web'`. See [storage.md](storage.md#channel_accounts) for the full schema.
+
+Web-specific config JSON fields: `token` (auto-generated base64url, 24 bytes).
+
+### Session strategy
+
+- **One account → many sessions (one active at a time)**
+- Session ID format: `web_<accountId>_<createdAtBase36>`
+- Active session tracked in memory (`activeOverrides` Map); defaults to most recent
+- Sessions live under the account's bound workspace using the highest-priority agent (falls back to `default` only when none exists)
+- Admin panel and other channels see these sessions in their `/session list` (tagged `[web]`)
+- Access level inherited from the account
+
+### Commands
+
+Slash commands are intercepted before reaching the agent:
+
+| Command | Effect |
+|---|---|
+| `/help` | List available commands |
+| `/session new` | Create a new session |
+| `/session list` | List all sessions (show ownership tags) |
+| `/session switch <n>` | Switch to session by number (readonly can only switch to own) |
+| `/session stop` | Interrupt current running task |
+| `/session compact` | Compress session context |
+| `/workspace info` | Show current workspace |
+| `/workspace switch <path>` | Switch workspace (full access only) |
+
+### Media handling
+
+- **Images** (jpeg/png/gif/webp): passed directly to LLM via multimodal content blocks
+- **Audio/other files**: saved to `<workspace>/.halo/assets/web/inbound/<accountId>/<yyyy-mm-dd>/` and path reported to agent in message text
+
+## Halo API — Public endpoints
+
+File: `packages/server/src/routes/web.ts`
+
+All public endpoints require `x-token` header (or `?token=` query param) with a valid account token. No cookie auth needed.
+
+> These paths are listed in `PUBLIC_PATHS` (`middleware/auth.ts`) so they bypass the admin cookie gate: `/api/web/chat`, `/api/web/stop`, `/api/web/history`, `/api/web/subscribe`, `/api/web/file`, and `/api/show/state` (the [halo-city](../../../halo-city/) snapshot — see [dev/api.md](../dev/api.md#show-world-snapshot)). The server CORS allowlist includes the `x-token` header, so browser-based custom frontends (web-demo, halo-city) can call these cross-origin.
+
+### POST `/api/web/chat`
+
+Send a message and receive streaming response via SSE.
+
+```json
+// Request
+{
+  "message": "hello",
+  "images": [{ "data": "<base64>", "mimeType": "image/png" }],  // optional
+  "workspace": "/abs/path",     // optional override, full-access tokens only
+  "sessionId": "web_explicit",  // optional override, see below
+  "agentId": "default"          // optional, only used when creating a new session
+}
+
+// Response: text/event-stream
+data: {"type":"session","sessionId":"web_abc123_m1xyz"}
+data: {"type":"thinking","text":"..."}
+data: {"type":"tool_call","toolName":"read_file","toolInput":{...}}
+data: {"type":"tool_result","toolName":"read_file","result":"..."}
+data: {"type":"stream","text":"Hello! "}
+data: {"type":"stream","text":"How can I help?"}
+data: {"type":"switch","sessionId":"..."}   // after /session switch or /session new command
+data: {"type":"complete"}
+data: {"type":"error","error":"..."}
+```
+
+> **Batch-boundary `complete` (must be absorbed, never closes the stream)**: when a root session drains a queue of multiple messages, the server runs N merged turns and emits an internal `complete` with `batchBoundary: true` between rounds (see [session.md](session.md#message-queue-and-drain)). The SSE generators in `channels/web/handler.ts` flush the just-finished round's text on a `batchBoundary` complete but **do not** send a `complete` SSE frame and **do not** set `done` — the response stays open for the next round; only the **terminal** (unmarked) `complete` closes the HTTP stream. Without this guard a producer→sub-agent fan-out would truncate the web client after the first round. The `batchBoundary` flag is therefore an internal server-side event marker only — it is never serialized into the SSE payload a client sees, so a custom frontend just consumes one ordinary `complete` at the end. (ACP rides on this channel, so it inherits the same safe behavior.)
+
+#### Per-request overrides (`workspace`, `sessionId`, `agentId`)
+
+By default each token is bound 1:1 to the workspace its admin row configured, and `/web/chat` operates on the account's "active" session (most-recently-used or one set by `/session new` / `/session switch`). External integrations — currently the [ACP adapter](../dev/acp-adapter.md) — need finer control:
+
+- `workspace` (string, optional): server-side absolute path. Overrides `account.workspacePath` for this request only. **Gated on `accessLevel === 'full'`** — readonly / workspace tokens cannot escape their account-bound workspace; the gate returns an SSE `error` event.
+- `sessionId` (string, optional): explicit halo session id. Bypasses the account's active-session pointer entirely. If the session doesn't yet exist, the server creates it with the supplied id (so callers can pre-mint stable ids and address them across reconnects).
+- `agentId` (string, optional): only consulted when the request is creating a new session (no row yet for `sessionId`). Picks the agent profile to bootstrap with. Defaults to `default`.
+
+Browser web-demo doesn't use any of these — it relies on per-token defaults. Three accepted transports per request, lowest-priority first:
+
+1. Query string: `?workspace=…&sessionId=…&agentId=…`
+2. Headers: `x-workspace`, `x-session-id`, `x-agent-id`
+3. POST body fields (highest priority).
+
+`/api/web/stop`, `/api/web/history`, `/api/web/subscribe` accept the same `workspace` + `sessionId` overrides via query string / header. They don't accept `agentId` (no session creation path).
+
+### POST `/api/web/stop`
+
+Stop the currently running task. Accepts optional `workspace` / `sessionId` overrides as documented above.
+
+```json
+// Response
+{ "stopped": true }
+```
+
+### GET `/api/web/history`
+
+Get a session's message history. Without overrides, returns the account's active session; with `sessionId` (and optionally `workspace`), returns whichever session you address.
+
+```json
+// Response
+{
+  "sessionId": "web_abc123_m1xyz",
+  "messages": [ { "id": "...", "role": "user", "content": "..." }, ... ],
+  "running": false
+}
+```
+
+### GET `/api/web/subscribe`
+
+Reconnect to a running session's event stream (same SSE format as `/chat`). If session is not running, returns a single `complete` event immediately. Accepts the same `workspace` / `sessionId` overrides.
+
+## Halo API — Admin endpoints
+
+Protected by cookie auth (admin panel). File: `packages/server/src/routes/web.ts`
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/api/web/accounts` | List all accounts |
+| POST | `/api/web/accounts` | Create account (body: `{workspacePath, label?, accessLevel?, language?}`) |
+| PATCH | `/api/web/accounts/:id` | Update account fields (label, workspacePath, enabled, accessLevel, language) |
+| DELETE | `/api/web/accounts/:id` | Delete account (token invalidated) |
+
+---
+
+## packages/web-demo — Standalone Demo Frontend
+
+An independent Express app that provides a browser UI for the web channel. It holds the Halo token server-side and exposes its own password-based auth.
+
+### Deployment
+
+```bash
+cd packages/web-demo
+node server.js
+```
+
+### Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `HALO_API` | Yes | Halo server URL (e.g. `http://localhost:9527`) |
+| `HALO_TOKEN` | Yes | Token from Halo admin panel (Web settings) |
+| `HALO_WEB_DEMO_PASSWORD` | No | Password for web-demo login. Empty = open access |
+| `PORT` | No | Listen port (default: `9528`) |
+
+### Security model
+
+- `HALO_TOKEN` and `HALO_API` are server-side only, never exposed to the browser
+- Frontend uses same-origin relative paths (`/chat`, `/history`, etc.)
+- web-demo server proxies all requests to Halo, injecting the token in `x-token` header
+- Session auth: random hex token stored in `x-session` header + localStorage
+
+### Proxy routes
+
+| Frontend path | Upstream Halo path |
+|---|---|
+| `POST /chat` | `POST /api/web/chat` |
+| `POST /stop` | `POST /api/web/stop` |
+| `GET /history` | `GET /api/web/history` |
+| `GET /subscribe` | `GET /api/web/subscribe` |
+
+### Features
+
+- SSE streaming with tool call display (collapsible)
+- Auto-reconnect: if session is running on page load, subscribes to live stream
+- Message queue: can send while agent is running, messages queue and send sequentially
+- Slash commands (`/help`, `/session`, `/agent`, `/skill`, `/workspace`)
+- Image upload (file picker + camera capture)
+- Voice recording (webm audio saved to workspace, path given to agent)
+- Stop/interrupt button
+- i18n: auto-detects browser language (`navigator.language`), toggle button in header, persists to `localStorage`
+
+## Integration guide (custom frontend)
+
+To build your own frontend against Halo's web channel:
+
+1. Create an account in the admin panel (Channels → Web → Create)
+2. Copy the generated token
+3. Make HTTP requests with `x-token: <your-token>` header:
+
+```bash
+# Send a message (SSE response)
+curl -N -H "x-token: YOUR_TOKEN" -H "Content-Type: application/json" \
+  -d '{"message":"hello"}' \
+  http://localhost:9527/api/web/chat
+
+# Stop current task
+curl -X POST -H "x-token: YOUR_TOKEN" http://localhost:9527/api/web/stop
+
+# Get history
+curl -H "x-token: YOUR_TOKEN" http://localhost:9527/api/web/history
+
+# Subscribe to running session
+curl -N -H "x-token: YOUR_TOKEN" http://localhost:9527/api/web/subscribe
+```
+
+SSE events are newline-delimited `data: {json}\n\n` lines. Parse the `type` field to handle each event kind.

package/bundled-docs/design/wechat.md

@@ -0,0 +1,146 @@
+# Weixin Channel — Design
+
+Let the user talk to Halo from WeChat on their phone, sharing the same workspace + session as the web side.
+
+## Architecture
+
+```
+                       ┌── ws/ (admin channel)           ─┐
+                       ├── channels/web/                  │
+Halo server (9527) ──┤── channels/telegram/             ├── SessionManager
+                       └── channels/wechat/              ─┘    (per workspace, via Registry)
+                               ↕ HTTPS long-poll
+                           ilinkai.weixin.qq.com
+```
+
+All channels are peers — each one is a subscriber + caller against SessionManager. Common slash commands (`/help`, `/evo`, and the object commands `/session`, `/agent`, `/skill`, `/workspace`) live in `channels/shared/commands.ts`; each channel handler is a thin adapter that builds a `CommandContext` and formats the result for its transport.
+
+## Data model
+
+### Workspace ↔ Bot mapping
+
+One bot (= one `ilink_bot_id` from a QR scan) is bound to one workspace. A workspace can bind multiple bots, but 1:1 is recommended.
+
+### Session strategy
+
+- **One WeChat user → many sessions (one active at a time)**
+- Session ID format: `wx_<normalizedUserId>_<createdAtBase36>` (e.g. `a1b2c3@im.wechat` → `wx_a1b2c3-im-wechat_<ts>`)
+- Sessions live under the bot's bound workspace and use the highest-priority agent (falls back to `default` only when none exists)
+- The web side sees these sessions in the session list (labelled `WeChat: <user>`)
+- Access level inherited from the bot account (see below)
+
+### Access level
+
+Each account carries `accessLevel: 'full' | 'workspace' | 'readonly'` (default `readonly`). Inbound messages create sessions with the matching access level:
+- `full` — no restrictions (no sandbox)
+- `workspace` — tool execution runs inside a bwrap sandbox with the workspace mounted read-write; `~/.halo/secrets/` is not mounted
+- `readonly` — tool execution runs inside a bwrap sandbox with the workspace mounted read-only; `~/.halo/secrets/` is not mounted
+
+Additionally, readonly sessions only receive read-only tools (file_read, view_image, file_list, grep, glob) — write/exec/fetch tools are not injected.
+
+When bwrap is not installed, app-level `assertPathAllowed` enforces the same path boundaries; `shell_exec` is blocked entirely without bwrap.
+
+Sub-sessions inherit the parent's access level — a readonly channel can't delegate to a full-access child and escape the sandbox.
+
+### Storage
+
+WeChat bot accounts are stored in the unified channel DB: `~/.halo/secrets/channels/channels.db`, table `channel_accounts` with `channel_type = 'wechat'`. See [storage.md](storage.md#channel_accounts) for the full schema.
+
+WeChat-specific config JSON fields: `botToken`, `baseUrl`, `userId`, `syncBuf`, `lastActiveChatId`.
+
+- `userId` is the QR-bind owner (the ilink_user_id of whoever scanned the QR code to register this bot). Used by the wechat cron-dispatcher as the default proactive-send target — sending here means cron output goes back to the bot's owner, which is the common-case "report to me on a schedule" intent.
+- `lastActiveChatId` is a runtime cache of the most recent inbound `from_user_id`. Written by `rememberLastActiveChat()` in `channels/shared/accounts.ts` with a per-process hash so unchanged values never touch the db (idempotent — hot path stays in memory). Used as a fallback for cron sends in the shared-bot case where you want to reply to whoever talked last.
+
+### Proactive sending (cron)
+
+The wechat cron-dispatcher (`channels/wechat/cron-dispatcher.ts`) registers itself with `cron/dispatcher.ts`'s registry at boot. On a fire it picks the recipient in this order:
+
+1. **Explicit `chatId` on the target** — when the cron was created from inside a wechat chat, the target carries the originating openId; dispatch sends only there.
+2. **`account.userId`** — the QR-bind owner, the "report to me on a schedule" default.
+3. **`lastActiveChatId`** — shared-bot fallback (reply to whoever talked last).
+
+WeChat is single-recipient per dispatch (no fan-out across `allowedUsers` like telegram has). If none of the three yields an id, dispatch fails with a clear "no wechat target — bind the account first" message.
+
+## Modules
+
+Files: `packages/server/src/channels/wechat/`
+
+- `api.ts` — HTTP client (getUpdates long-poll / sendMessage / notifyStart / notifyStop)
+- `login.ts` — QR login (startWeixinLoginWithQr + waitForWeixinLogin)
+- `accounts.ts` — DAL (insertAccount / updateAccount / deleteAccount / list / normalize / saveSyncBuf)
+- `cdn.ts` — media CDN client (download + decrypt)
+- `media-store.ts` — saves inbound media to the workspace. Shared with the web chat channel: WeChat uses `<workspace>/.halo/assets/weixin/inbound/<accountId>/<date>/`, web pasted images land in `<workspace>/.halo/assets/web/inbound/<date>/`. Both emit `[图片已保存: /abs/path]` markers that the UI turns into media chips.
+- `send-media.ts` — uploads and sends files/images out
+- `handler.ts` — long-poll main loop, routes messages to SessionManager + slash-command dispatch
+- `event-adapter.ts` — LLM streaming events → WeChat whole-message send (coalesce by 200 chars / 3s silence / complete flush)
+
+## SessionManager dependencies
+
+- **Multi-subscriber listener**: `eventListeners: Map<rootId, Set<handler>>` — web and weixin can subscribe to the same session simultaneously
+- **Registry**: `SessionManagerRegistry` caches SessionManager instances by workspace path; web and weixin share it
+
+## Long-poll main loop
+
+Per enabled account:
+
+```
+loop {
+  resp = await getUpdates({ baseUrl, token, sync_buf })
+  for msg in resp.msgs:
+    handleInbound(account, msg)
+  sync_buf = resp.get_updates_buf   // also saveSyncBuf to DB
+}
+```
+
+> **单实例依赖**：长轮询循环跟 HTTP server 解耦 —— 即便 `:9527` 没绑上，只要进程活着，`runAccountLoop` 就继续拉消息。如果有孤儿 server 进程残留，每个进程都会独立收到同一条消息并 fan out 到不同 session（每个进程内存里的 `activeOverrides` 是独立的，`findActiveSessionId` 可能返回不同结果）。因此 `src/index.ts` 在启动时要抢 `~/.halo/global/server.pid` 单实例锁，详见 [dev/deploy.md](../dev/deploy.md#4-start-the-server)。
+
+`handleInbound(account, msg)`:
+1. Extract `from_user_id` / text + media items / `context_token`
+2. Process inbound media: images → base64 attached to the agent message; voice / video / files → saved under the workspace with a `[voice saved: ...]` etc. marker appended to the text
+3. If the text begins with `/`, dispatch a slash command (see below) — if it returns `handled`, stop here
+4. sm = `registry.getOrCreate(account.workspacePath)`
+5. Resolve the active session for this user (override from `/session new`/`/session switch`; otherwise the most recent non-archived session matching the user prefix)
+6. If no active session exists, create one with the inherited access level
+7. If the session is compacting, reply with `⏳ integrating context, try again in ~30s` and skip queueing
+8. If the session is busy, reply with `🔄 still processing last message, queued` and still enqueue
+9. Register a WeixinResponder event listener (once per session) that coalesces outbound text
+10. `sm.sendUserMessage(sessionId, agentInput, images?)` — the actual agent input is prefixed with `[channel: wechat | user: <id>]` so the agent knows how to address the media-send skill
+
+## Slash commands
+
+Implemented in `handler.ts`'s `handleSlashCommand()`:
+
+| Command | Purpose |
+|---|---|
+| `/session new` | Create a new session; old sessions remain accessible via `/session list` + `/session switch` (nothing is archived) |
+| `/session list` | List recent sessions (newest first, up to 20); the active one is marked `→` |
+| `/session switch <index>` | Switch the active session to the indexed entry from `/session list`. Override is in-memory per user per account. Readonly bot 仅能切到自己 prefix 下的 session（跨用户会话拒绝）。 |
+| `/workspace info` | Show the current workspace. `/workspace switch <path>` 切换（绝对路径），**仅 full 权限 bot 可用**；切换后重启 account loop。readonly 切换等于绕过沙箱，直接拒绝。 |
+| `/workspace setup` / `/workspace tidy` | Triggers the `workspace` skill — setup for new workspaces (creates INDEX.md / INSTRUCTIONS.md / memory), tidy for cleanup of existing ones |
+| `/help` | List available commands |
+
+Unknown `/` input falls through to normal message handling.
+
+## Event coalescing (WeixinResponder)
+
+WeChat `sendMessage` is block-send, while LLMs stream. The current strategy is "buffer the whole turn, flush as one message":
+- `stream` events accumulate in a single buffer
+- `complete` → flush the whole buffer as one (or more) messages. The responder flushes on **any** `complete` and does not read its `batchBoundary` flag — so when the root drains a multi-message queue across several merged turns (see [session.md](session.md#message-queue-and-drain)), each round's batch-boundary `complete` ships that round as its own message instead of buffering every round into one blob that lands only at the terminal `complete` (the "8 reports in one lump" bug)
+- Hard cap `HARD_CHARS = 3500` (WeChat rejects >~4000) — when the buffer reaches it mid-stream, split at the nearest paragraph break and dispatch; remaining text keeps accumulating
+- `error` → immediate flush + send a `[错误] …` message; `system` → immediate flush + send a `[系统] …` message
+- Tool calls / tool results / thinking are dropped (detail lives in the web UI)
+- Media: the agent emits `MEDIA: <path>` markers, which the responder extracts and turns into actual media uploads
+
+## Supported inbound media
+
+Plain text + images (base64 attached to the agent message), voice, video, files. For voice/video/files, the content is decrypted (AES from CDN), saved under the workspace, and referenced in the agent's input text.
+
+## Scope and out-of-scope
+
+Supported: text, images, voice, video, files; slash commands listed above; per-session access level.
+
+Not supported: group chats, typing indicators.
+
+## References
+
+Original rollout plan: [plans/weixin-channel.md](../plans/weixin-channel.md).