@turmind/halo 0.1.9

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

@@ -0,0 +1,62 @@
+# Channel Onboarding
+
+Halo lets users talk to the same agent from many places — a browser, a phone IM, an IDE. Each "place" is a **channel**. Every channel maps a remote identity (a chat id, a token, a JSON-RPC peer) to a workspace + access level on the server.
+
+This folder has one onboarding guide per channel. Pick the one you want and follow it end-to-end:
+
+| Channel | Best for | What you set up | Transport |
+|---|---|---|---|
+| [Web](web.md) | Browsers, custom HTTP clients, any frontend you control | Auto-generated token bound to a workspace | HTTP + SSE |
+| [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) |
+| [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 |
+
+## How channels are wired
+
+```
+                          ┌── ws/ (admin panel)
+                          ├── channels/web/        ── HTTP + SSE
+   halo server ─────────┤── channels/telegram/   ── grammy long-poll
+   (port 9527)            ├── channels/slack/      ── Socket Mode wss
+                          ├── channels/feishu/     ── long-connect wss
+                          └── channels/wechat/     ── ilinkai long-poll
+                                  ↓
+                          SessionManager (per workspace)
+```
+
+Each channel handler is a thin adapter between its native protocol and halo's `SessionManager`. Slash commands (`/session` `/agent` `/skill` `/workspace` `/cron` `/acp` `/evo` `/help`) are shared across all of them — see `channels/shared/commands.ts`.
+
+The ACP adapter is **not** a channel — it's a stdio bridge that translates ACP JSON-RPC into the web channel's HTTP+SSE. Counted here only because users go through the same "set up an account, get a token" flow.
+
+## Account fields at a glance
+
+What the admin UI actually asks you for. Auto-filled fields (botUsername, botUserId, teamId, botOpenId) are not listed because the server resolves them from the credentials you paste.
+
+| Channel | Required | Optional | How to get the credentials |
+|---|---|---|---|
+| Web | Workspace path | Label, access level, language | None — admin generates a token on Create |
+| 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 |
+| WeChat | Workspace path (set before scanning) | Label, access level, language | QR scan in admin UI; bot token comes back from the scan |
+
+## Access level
+
+Every channel account carries an `accessLevel`:
+
+- `readonly` (default) — sandboxed, workspace mounted read-only, secrets dir not mounted, only read-only tools (`file_read`, `view_image`, `file_list`, `grep`, `glob`) injected
+- `workspace` — sandboxed, workspace mounted read-write, secrets dir not mounted
+- `full` — no sandbox, all tools, can `/workspace <path>` to another workspace
+
+When in doubt start at `readonly` and raise it later. The setting is on the **account row**, so a single Slack workspace can have one `readonly` bot account in #general and a separate `full` account in #ops.
+
+## Where to go next
+
+- 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)
+
+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}/`.

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

@@ -0,0 +1,150 @@
+# ACP (Agent Client Protocol)
+
+Drive a halo server from any [ACP](https://github.com/zed-industries/agent-client-protocol)-speaking client. The most common use is **Claude Code on a developer's laptop, talking to a halo agent on EC2** — but any ACP client works.
+
+ACP isn't a channel of its own. The `halo acp` command is a **stdio bridge** that translates ACP JSON-RPC into the Web channel's HTTP+SSE. So setup = "create a Web account, then point an adapter at it."
+
+## When to reach for it
+
+```
+[Mac]                                    [EC2]
+Claude Code                                  halo server (port 9527)
+   │   ACP / JSON-RPC over stdio                │
+   ▼                                            │
+halo acp adapter ────HTTP/SSE────────────────▶│
+                                                │
+                                          halo agent
+                                          (workspace files
+                                           live on EC2)
+```
+
+Use ACP when:
+- You want to use Claude Code locally as the chat UI but the agent's tools / workspace live on a remote machine
+- You want one halo server to delegate to **another** halo server on a different host (the `/acp add` flow below)
+- You're integrating with any tool that already speaks ACP
+
+If you just want a browser UI, use the [Web](web.md) channel directly — ACP is overkill.
+
+## Step 1 — Provision a Web token
+
+ACP rides on the Web channel. Follow [Web channel onboarding](web.md) Steps 1-2 to get a token. **Pick `full` access** if you need multi-workspace support — `readonly` and `workspace` tokens can't override the workspace per request, so each adapter is locked to one workspace.
+
+Save:
+- **Token** (the `…` from Web admin)
+- **Server host + port** (e.g. `localhost:9527`, or `ec2-1-2-3-4.compute.amazonaws.com:9527`)
+- **Workspace path** on the server (absolute, e.g. `/home/ubuntu/my-project`)
+
+## Step 2 — Launch the adapter from your ACP client
+
+The adapter is published as the `halo acp` subcommand in `@turmind/halo` (the same npm package that ships `halo server`).
+
+```sh
+halo acp \
+  --host my-ec2-or-localhost \
+  --port 9527 \
+  --token <web-token-from-step-1> \
+  --workspace /abs/path/on/server \
+  --agent-id default        # optional; defaults to 'default'
+```
+
+| Flag | Required | Notes |
+|---|---|---|
+| `--host` | yes | Halo server hostname / IP |
+| `--port` | yes | Halo server port |
+| `--token` | yes | Web-channel token. `full` access required for multi-workspace use |
+| `--workspace` | yes | Absolute server-side path for this adapter |
+| `--agent-id` | no | Halo agent profile to use when ACP `session/new` creates a fresh session. Default `default` |
+
+Each adapter process binds to **one** workspace. To drive multiple workspaces concurrently from one token, run multiple adapter processes — one per workspace.
+
+The adapter reads/writes JSON-RPC frames on **stdin / stdout** (one message per line, no LSP-style framing). **Stderr** is reserved for human-readable diagnostics — never parse it.
+
+### Wiring into Claude Code
+
+Claude Code lets you register a custom agent. Use its `claude-code config agent add` command (see Claude Code's own docs for the exact incantation) and point it at the `halo acp …` invocation above.
+
+After registration, you can launch a session in Claude Code that streams to the remote halo server transparently — Claude Code thinks it's talking to a local agent, halo thinks it's talking to a Web-channel client.
+
+## Step 3 — (Halo-to-halo) bind a remote with `/acp add`
+
+The most common use of this adapter isn't a third-party ACP client — it's **another halo agent** delegating out to a remote halo workspace. Halo ships a builtin `acp` skill for this (slash command `/acp`, full access). Type `/acp add` — or just ask in chat (e.g. "add an ACP binding to my other halo").
+
+It walks you through `(label, host, port, workspace, token)` and **stamps out a new skill** named `ask-<label>` containing:
+
+- `SKILL.md` — slash command `/ask-<label>`, instructions tailored to this remote
+- `config.yaml` — declares the binding's params so admin Settings shows a form
+- `ask.py` — bundled JSON-RPC ↔ stdio helper (one copy per binding, intentional — keeps `/workspace share` bundles self-contained)
+
+It also writes the connection values into `settings.yaml` (workspace or global, you pick).
+
+After install, the local agent can do `shell_exec: python3 .../ask-<label>/ask.py "<question>"` and halo's runtime substitutes the configured values. **Multiple bindings coexist** — each gets its own slash command, settings namespace, and Admin Settings page. `/acp list` shows the bindings you've generated.
+
+To remove a binding: `/acp remove` (deletes the skill directory and points out the leftover `ask-<label>:` block in `settings.yaml`).
+
+This is the **only** supported way to set up a halo-to-halo binding — there's no generic single-target `ask-acp-agent` skill, because per-binding namespaces (one token-host-workspace triple per skill id) are required for multi-remote use.
+
+### Direct asks — `/acp kiro` / `/acp claude`
+
+Bindings are for **remote halo servers**. For agents on the **same machine** no binding is needed — the `acp` skill talks to them directly, zero config:
+
+- `/acp claude <question>` — local Claude Code (via npm `@agentclientprotocol/claude-agent-acp`)
+- `/acp kiro <question>` — local Kiro (via `kiro-cli acp`)
+
+The question is passed verbatim — including the other agent's own slash commands (e.g. `/acp kiro /model <full-model-id>` switches Kiro's model). Both coexist with `/ask-<label>` bindings.
+
+## ACP method coverage
+
+| Method | Implemented | Notes |
+|---|---|---|
+| `initialize` | ✅ | Declares `protocolVersion: 1`, `loadSession: true`, no auth methods |
+| `authenticate` | ✅ (no-op) | Token is passed via launch flags; ACP-side auth has nothing to do |
+| `session/new` | ✅ | Mints a sessionId of shape `web_acp_<ts>_<rand>`. Halo creates the row lazily on first `/web/chat` |
+| `session/load` | ✅ | Verifies the supplied id still exists on the halo server, then registers it locally |
+| `session/prompt` | ✅ | Forwards text + image content blocks. Resource / embedded-context blocks log a stderr warning and are dropped (see "Reverse fs" below) |
+| `session/cancel` | ✅ | Aborts the in-flight HTTP/SSE stream and POSTs `/web/stop` |
+| Reverse `fs/*` | ❌ | See "Reverse fs" below |
+| Reverse `terminal/*` | ❌ | Same reasoning |
+| `requestPermission` | ❌ | Halo has its own access-level system at the channel-account level |
+
+### Session id model
+
+ACP `sessionId` **is** the halo session id — there's no extra mapping layer. When `session/new` mints `web_acp_<ts>_<rand>`, that exact string is what gets created in `agent_sessions` (lazily on first `/web/chat`). The ACP client persists ids itself; the adapter holds no on-disk state. Losing the adapter's in-memory map on restart is harmless because the conversation lives on the halo server.
+
+The ACP client is the source of truth for "which sessions are mine" — a Mac-side Claude Code knows about *its* sessions, the EC2-side halo agent doesn't need to enumerate them.
+
+## Multi-workspace
+
+A Web-channel token in halo is bound to one workspace at the database level. The adapter works around this by sending `workspace` + `sessionId` overrides on every Web-channel call:
+
+- `/api/web/chat`, `/api/web/stop`, `/api/web/history`, `/api/web/subscribe` accept `workspace=<path>` and `sessionId=<id>` overrides
+- The server gates the `workspace` override on `accessLevel === 'full'` — readonly / workspace tokens cannot escape their bound workspace
+- The adapter sends both fields on every request, so concurrent adapters on the same token but different `--workspace` flags don't step on each other
+
+**Caveat:** sending `/workspace switch <path>` from inside an ACP session still mutates the bound workspace at the **db level** (changing the account's default for everybody using that token). Avoid `/workspace switch` from an adapter — use `--workspace` at adapter launch instead.
+
+## Reverse fs (parked)
+
+ACP optionally lets the agent (running on the server) request files from the client (the laptop on the user's side) via `fs/read_text_file` and `fs/write_text_file`. We don't implement this in v1 because:
+
+1. The Web channel is HTTP + SSE — a one-way stream. Reverse fs would need WebSocket or long-poll
+2. Halo agents currently use `file_read` / `file_write` against the **server's** workspace; supporting reverse fs would need a parallel toolset
+
+For now: if you want the agent to see a Mac-side file, paste it into the prompt. The adapter logs a stderr warning when it sees a `resource` content block in `session/prompt`, so the failure mode is obvious.
+
+## Common problems
+
+| Symptom | Cause / fix |
+|---|---|
+| Adapter exits immediately on launch | Missing required flag, or the token / host are wrong. Check stderr |
+| `401` on first prompt | Token typo, or token was deleted from admin |
+| `403` when launching with `--workspace /some/other/path` | Token is `readonly` / `workspace` access — use a `full` token or omit `--workspace` |
+| Tool calls don't appear in Claude Code | Expected — halo doesn't translate every event back as ACP `tool_call`. See [docs/dev/acp-adapter.md](../../dev/acp-adapter.md) for the full mapping |
+| Two `session/prompt` calls on the same id, second hangs | Halo queues messages when a session is busy; ACP adapter ends the response with `[queued]`. Wait for the first to finish |
+| `/workspace switch <path>` worked but other tokens broke | You changed the db-level default. Switch back with another `/workspace switch`, or stop using slash commands from the adapter |
+
+## Reference
+
+- CLI source: `packages/acp-adapter/src/index.ts`
+- Adapter source: `packages/acp-adapter/src/adapter.ts`, `halo-client.ts`, `jsonrpc.ts`
+- Full design + protocol mapping: [../../dev/acp-adapter.md](../../dev/acp-adapter.md) — read this before changing the wire format
+- Web channel: [web.md](web.md) — the underlying transport

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

@@ -0,0 +1,154 @@
+# Feishu (Lark)
+
+Talk to a halo agent from Feishu — DM the bot, or `@`-mention it in any group it's been added to. Halo uses Feishu's **long-connect** event delivery (an outbound WebSocket from the server to Feishu's open platform), so **no public webhook URL is required**.
+
+## What you'll end up with
+
+- A self-built Feishu app named (e.g.) `halo` published in your tenant
+- Two credentials stored in halo: **App ID** (`cli_…`) and **App Secret**
+- A bot account row pointing those credentials at one halo workspace
+
+## Step 1 — Create a self-built app
+
+1. Go to https://open.feishu.cn/app and click **创建应用 / Create App** → **自建应用 / Custom App** (do NOT pick "应用商店应用 / Marketplace App")
+2. Fill name (e.g. `halo`), upload an icon, write a description
+3. After creation you land on **凭证与基础信息 / Credentials and Basic Info**
+
+## Step 2 — Copy App ID and App Secret
+
+Same page (**凭证与基础信息**):
+
+- **App ID** — value like `cli_a1b2c3d4`. Public-ish; goes into halo
+- **App Secret** — click 显示 / Show. Treat like a password
+
+You'll paste both into halo in Step 7.
+
+## Step 3 — Enable bot capability
+
+A Feishu app with no bot capability can't receive IM events at all.
+
+1. Left sidebar → **添加应用能力 / Add App Capabilities** (or 应用能力 in the new UI)
+2. Find **机器人 / Bot** → click 启用 / Enable
+3. Skip optional bot config (welcome message, menu, etc.) for v1
+
+## Step 4 — Apply for API permissions
+
+Left sidebar → **权限管理 / Permissions** → **API 权限 / API Permissions** → search and **申请 / Apply** for each:
+
+**Required:**
+- `im:message` — receive messages
+- `im:message:send_as_bot` — send messages as the bot
+- `im:resource` — download user-uploaded images / files
+- `im:chat` — read group info (needed when the bot is added to a group)
+
+**For target search in cron jobs** (lets you `@`-search users / chats in the admin's cron form):
+- `im:chat:readonly`
+- `contact:user.id:readonly` (optional, for ID lookups)
+- `contact:user.base:readonly` (optional, for name / email lookups)
+
+After apply, permissions go to **待审批 / Pending Approval**. If you're a tenant admin, approve them yourself in **管理员后台 / Admin Console** → **应用管理 / App Management** → the app → **权限审批 / Permission Approvals**.
+
+## Step 5 — Switch event delivery to long-connect
+
+Halo uses long-connect, **not** webhook callbacks. This is the most error-prone step in the whole flow.
+
+1. Left sidebar → **事件与回调 / Events & Callbacks** → **事件配置 / Event Config**
+2. Look for the **mode toggle** at the top of this page:
+   - **长连接 / Long Connection** ← pick this
+   - 回调地址 / Callback URL — webhook mode, do not pick
+3. With long-connect selected, the Request URL / Verification Token / Encrypt Key fields become **optional / unused**. You can leave them blank.
+
+> If you don't see a mode toggle, your tenant might be on an older console UI. In that case the "configure long-connect" entry is somewhere on the same page; if you can't find it, ping the user — Feishu has reshuffled this UI several times.
+
+4. Same page → scroll to **添加事件 / Add Events** → search and add `im.message.receive_v1` (the v2 event payload, named with a v1 suffix for backwards compat — yes, it's confusing, this is the right one)
+
+Save changes.
+
+## Step 6 — Publish a version (mandatory)
+
+> This is the step everyone forgets. Without publishing, the bot has zero presence in Feishu — you can't find it in search, can't add it to groups, can't DM it, can't receive events.
+
+1. Left sidebar → **版本管理与发布 / Version Management** → **创建版本 / Create Version**
+2. Bump the version number, write a one-line changelog ("initial setup")
+3. **提交审核 / Submit for Review**
+4. If you're a tenant admin: **管理员后台** → **应用管理** → the app → **审核中 / Pending** → approve
+
+After approval the bot is visible in your Feishu tenant. Repeat this step **every time** you change permissions or events — Feishu doesn't honor changes until a new version is published and approved.
+
+## Step 7 — Add the account in halo admin
+
+Open halo admin → **Channels** → **Feishu** → **Add Account**:
+
+| Field | Value |
+|---|---|
+| App ID | from Step 2 |
+| App Secret | from Step 2 |
+| Verification token | leave blank (long-connect doesn't use it) |
+| Encrypt key | leave blank (long-connect doesn't encrypt the wire) |
+| Workspace path | absolute path, e.g. `/home/ubuntu/my-project` |
+| Label | optional |
+| Access level | `readonly` (default), `workspace`, or `full` |
+| Language | `en` or `zh` |
+
+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).
+
+## Step 8 — Test it
+
+In Feishu desktop / mobile:
+
+1. Top-bar search → type the bot's name → click into the bot's profile → start a DM → send `hello` → expect a streamed reply
+2. Add the bot to a group: open a group → 设置 → 群机器人 → add → `@halo hi` → expect a reply
+
+If nothing happens, check halo server logs (`/tmp/halo-server.log`) for `[feishu]` lines.
+
+## How halo handles inbound
+
+- **P2P** (1:1 DMs) — every message routes to the bot
+- **Groups** — only `@`-mentions wake the bot up
+- **Threads** — Feishu's `root_id` is used as the session boundary; replies stay in-thread
+- **Files** — images go to the LLM as multimodal content; other files are saved under `<workspace>/.halo/assets/feishu/inbound/<accountId>/<date>/`
+- **Self-loop** — bot-authored events are dropped to prevent the bot replying to itself
+
+## Slash commands
+
+Same set as the other channels — type as plain text in a DM or thread:
+
+| 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 Feishu
+
+When a cron job is created from inside a Feishu chat, the dispatcher remembers the chat id and sends back there. To target a specific Feishu chat from the admin UI:
+
+- Pick the Feishu target in the cron form
+- Type a user name or chat name in the search box — autocomplete matches via the contacts / chat APIs
+- Selected entries become explicit chat IDs on the cron run
+
+Search depends on the contact and `im:chat:readonly` scopes from Step 4. If autocomplete returns nothing, the most likely cause is that the new permissions haven't been approved + republished yet (Step 6).
+
+## Common problems
+
+| Symptom | Cause / fix |
+|---|---|
+| `99991663` on Add Account | App Secret wrong — copy it again from Step 2 |
+| `99991668` on Add Account | Bot capability not enabled — go back to Step 3 |
+| Bot exists but receives no events | Step 5 mode is set to webhook (not long-connect), or Step 6 wasn't done |
+| Permission errors when sending images / reading group info | New scope was approved but app version wasn't republished — go to Step 6 |
+| Can't find the bot in Feishu search | Step 6 wasn't done. Search results are tenant-wide and only show **published** apps |
+| Multiple halo instances reply to the same message | Only one process should hold the long-connect. Check `~/.halo/global/server.pid` for the lock |
+
+## Multi-tenant setup
+
+Feishu apps are per-tenant (= per company / org account). To support a second Feishu tenant, create a separate self-built app under that tenant, repeat Steps 1-7, add a second account row in halo. Halo routes inbound events by `app_id` so multiple accounts coexist cleanly.
+
+## Reference
+
+- Code: `packages/server/src/channels/feishu/`
+- Routes: `packages/server/src/routes/feishu.ts`
+- Admin UI: `packages/admin/src/features/feishu/feishu-settings.tsx`
+- API client: `packages/server/src/channels/feishu/api.ts` (long-connect open, message send, file download, optional webhook decrypt for legacy bodies)

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

@@ -0,0 +1,156 @@
+# Slack
+
+Talk to a halo agent from a Slack workspace — DM the bot, or `@`-mention it in any channel where it's invited. Halo uses **Socket Mode** (an outbound WebSocket from the server to Slack), so **you don't need a public webhook URL** or an HTTPS reverse proxy.
+
+## What you'll end up with
+
+- A Slack App named (e.g.) `halo` installed in your workspace
+- Two tokens stored in halo: a **Bot Token** (`xoxb-…`) for outbound API calls and an **App-Level Token** (`xapp-…`) for the Socket Mode connection
+- A bot account row pointing those tokens at one halo workspace
+
+## Step 1 — Create a Slack App
+
+1. Go to https://api.slack.com/apps and click **Create New App** → **From scratch**
+2. Name it (`halo` is fine), pick the workspace it should live in
+3. You're now on the app's **Basic Information** page — keep this tab open, you'll come back to it for the App-Level Token
+
+## Step 2 — Enable Socket Mode
+
+Halo uses Socket Mode, not webhooks. Turn it on first so the rest of the config falls into place.
+
+1. Left sidebar → **Socket Mode** → toggle **Enable Socket Mode** on
+2. Slack prompts you to create an **App-Level Token**:
+   - Token Name: anything (e.g. `socket`)
+   - Scopes: select `connections:write` (the only one needed)
+   - Click **Generate** → save the resulting `xapp-…` token. You won't see it again.
+
+Keep the App-Level Token in a password manager or paste it directly into the halo admin form when you get there.
+
+## Step 3 — Subscribe to Bot Events
+
+1. Left sidebar → **Event Subscriptions** → toggle **Enable Events** on
+2. Note: there's **no Request URL field** when Socket Mode is enabled — Slack pushes events over the wss connection instead
+3. Expand **Subscribe to bot events** and add:
+   - `app_mention` — required, fires when someone `@`-mentions the bot
+   - `message.im` — required, fires on direct messages to the bot
+   - `message.channels` — optional, every public-channel message the bot can see (only meaningful if you want the bot to react without a mention)
+   - `message.groups` / `message.mpim` — optional, private channels and group DMs
+
+Click **Save Changes** at the bottom.
+
+## Step 4 — Add Bot Token Scopes
+
+The Bot Token (`xoxb-…`) needs scopes for everything the bot might do.
+
+Left sidebar → **OAuth & Permissions** → scroll to **Scopes** → **Bot Token Scopes** → add:
+
+**Required:**
+- `chat:write` — post messages
+- `app_mentions:read` — receive `@`-mentions
+- `im:history` — read DM history (so the bot can see the user's message)
+- `im:read` — list IM channels
+- `im:write` — open IM channels
+- `channels:history` — read public-channel messages
+- `groups:history` — read private-channel messages
+- `mpim:history` — read group-DM messages
+- `files:read` — download user-uploaded images / files
+
+**For target search in cron jobs** (lets you `@`-search users / channels in the admin's cron form):
+- `users:read`
+- `users:read.email` (optional, only needed if you want email-based user lookup)
+- `channels:read`
+- `groups:read`
+- `mpim:read`
+
+## Step 5 — Install to Workspace
+
+Same page (**OAuth & Permissions**) → top of the page → **Install to Workspace** → review scopes → **Allow**.
+
+After install you get a **Bot User OAuth Token** that starts with `xoxb-…` — this is the second token you need.
+
+> If you change scopes later, hit **Reinstall to Workspace** on the same page. The `xoxb-` token value doesn't change; the install just refreshes its scope list. No need to update the token in halo after a reinstall.
+
+## Step 6 — Open up the Messages tab (so users can DM the bot)
+
+By default Slack hides the input box on the bot's DM page. To allow direct messages:
+
+1. Left sidebar → **App Home**
+2. Scroll to **Show Tabs** → **Messages Tab** → toggle on
+3. Check the box **"Allow users to send Slash commands and messages from the messages tab"**
+4. Save
+
+In the Slack desktop client, fully quit and reopen (or `Cmd+R` to reload) — otherwise the bot's DM page still shows the cached "messaging is disabled" banner.
+
+## Step 7 — Add the account in halo admin
+
+Open halo admin → **Channels** → **Slack** → **Add Account**:
+
+| Field | Value |
+|---|---|
+| Bot token | the `xoxb-…` from Step 5 |
+| App token | the `xapp-…` from Step 2 |
+| Workspace path | absolute path to the workspace this bot drives, e.g. `/home/ubuntu/my-project` |
+| Label | optional, e.g. "Engineering bot" |
+| Access level | `readonly` (default), `workspace`, or `full` |
+| Language | `en` or `zh` |
+
+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.
+
+## 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
+2. Invite the bot into a channel: `/invite @halo` → mention it: `@halo what files are in this workspace?` → expect a reply in the same thread
+
+If nothing happens, check the halo server logs (`/tmp/halo-server.log`) for `[slack]` lines.
+
+## How halo handles inbound
+
+- **DMs** (channel id starts with `D`) — every message routes to the bot, no mention needed
+- **Channels / groups** — only `@`-mentions wake the bot up, plain messages are ignored
+- **Threads** — the bot replies in-thread; one halo session per thread, so a long thread stays in one conversation
+- **Files** — images go to the LLM as multimodal content; other files are saved under `<workspace>/.halo/assets/slack/inbound/<accountId>/<date>/`
+- **`bot_id` self-loop** — messages posted by any bot (including this one) are dropped, so the agent can't reply to itself
+
+## Slash commands
+
+Same set as the other channels — type these as plain text in a DM or thread:
+
+| 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 Slack
+
+When a cron job is created from inside a Slack thread, the dispatcher remembers the channel + thread id and sends back to the same place. To target a specific Slack chat from the admin UI:
+
+- Pick the Slack target in the cron form
+- Type the channel name (`#general`) or `@user` in the search box — autocomplete matches by Slack's `users.list` / `conversations.list`
+- Selected entries become explicit chat IDs on the cron run
+
+The search depends on the `users:read` / `channels:read` scopes added in Step 4. If autocomplete returns nothing, that's the first thing to check.
+
+## Common problems
+
+| Symptom | Cause / fix |
+|---|---|
+| **"向此应用发送消息的功能已关闭"** banner on the DM page | Step 6 wasn't done — open App Home, enable Messages Tab, reload Slack |
+| Account created but no events arrive | Socket Mode token (`xapp-`) is wrong, or `connections:write` scope missing on it |
+| `not_authed` / `invalid_auth` error on Add Account | Bot token (`xoxb-`) typo, or you pasted the App token in the Bot field by mistake |
+| Bot replies to itself in a loop | Should never happen — halo drops all `bot_id`-tagged messages. If it does, file a bug |
+| Search dropdown empty in cron form | Missing `users:read` / `channels:read` scopes — add them, then Reinstall to Workspace |
+| Multiple halo instances reply to the same message | Only one process should hold the Socket Mode connection. Check `~/.halo/global/server.pid` for the lock |
+
+## Multi-workspace setup
+
+Slack apps are per-Slack-workspace. To support a second Slack workspace, repeat Steps 1-7 with a fresh app installed in that second workspace, and add a second account row in halo. The two accounts can point at the same halo workspace path or different ones — halo uses `teamId` to route inbound events.
+
+## Reference
+
+- Code: `packages/server/src/channels/slack/`
+- Routes: `packages/server/src/routes/slack.ts`
+- Admin UI: `packages/admin/src/features/slack/slack-settings.tsx`
+- API client: `packages/server/src/channels/slack/api.ts` (covers Socket Mode connection, `chat.postMessage`, `auth.test`, file download, target search)

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

@@ -0,0 +1,112 @@
+# Telegram
+
+Talk to a halo agent from Telegram. Halo uses Telegram's **long-poll** mode (no webhook URL needed).
+
+## What you'll end up with
+
+- A Telegram bot created via BotFather
+- A bot token like `123456:ABC-DEF…` stored in halo
+- A bot account row pointing that token at one halo workspace
+
+## Step 1 — Create a bot with BotFather
+
+1. In any Telegram client, search `@BotFather` and start a chat
+2. Send `/newbot`
+3. Pick a display name (free text, e.g. `Halo Dev`)
+4. Pick a username — must end in `bot` or `_bot`, must be globally unique. e.g. `halo_dev_bot`
+5. BotFather replies with a token like `123456789:ABCdef-GhI...`. **This is the only credential you need.** Save it.
+
+## Step 2 — (Optional) Register the slash-command menu
+
+Sending `/setcommands` to BotFather lets Telegram clients show a menu next to the input box. This is purely cosmetic — halo handles all these commands whether they're registered or not.
+
+```
+/setcommands → pick your bot → paste:
+
+start - 开始 / start
+new - 新会话 / new session
+list - 会话列表 / list sessions
+switch - 切换会话 / switch session
+stop - 中断任务 / stop running task
+compact - 压缩上下文 / compact context
+ws - 查看/切换 workspace
+help - 帮助 / help
+```
+
+## Step 3 — Add the account in halo admin
+
+Open halo admin → **Channels** → **Telegram** → **Add Account**:
+
+| Field | Value |
+|---|---|
+| Bot token | the `…:ABC…` from Step 1 |
+| Workspace path | absolute path, e.g. `/home/ubuntu/my-project` |
+| Label | optional |
+| Access level | `readonly` (default), `workspace`, or `full` |
+| Language | `en` or `zh` |
+| Allowed users | optional whitelist; comma-separated user IDs and/or `@usernames`. Empty = anyone can talk to the bot |
+
+On submit halo calls Telegram's `getMe` to validate the token and auto-fill `botUsername`. If that call fails the account isn't created.
+
+### About `allowedUsers`
+
+- **Empty** — anyone who finds the bot can chat with it. Fine for personal bots, dangerous if the bot is `full`-access
+- **Numeric IDs** (e.g. `123456789`) — recommended. A user's id is stable and you can find it by sending `/start` to `@userinfobot` in Telegram
+- **`@username`** — works for inbound filtering but **cron fan-out skips them** (Telegram's Bot API needs a numeric chat id, and `@username` lookup isn't always reliable)
+
+For team bots prefer numeric IDs.
+
+## Step 4 — Test it
+
+In Telegram, search the bot's username (`@halo_dev_bot`) → press **Start** → say `hello` → expect a streamed reply.
+
+If nothing happens, check halo server logs for `[telegram]` lines.
+
+## How halo handles inbound
+
+- **Private chats** — every message routes to the bot
+- **Group chats** — not supported in v1 (group messages are dropped)
+- **Photos / documents** — the file URL is included in the agent's input text; images aren't yet sent to vision automatically (by design — Telegram's photo URLs are short-lived and the upstream LLM can't always reach them)
+- **Slash commands** — handled by halo, not by Telegram. The BotFather menu in Step 2 is just a UI hint
+
+## Slash commands
+
+| Command | Effect |
+|---|---|
+| `/start` | Welcome message |
+| `/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 Telegram
+
+When a cron job is created from inside a Telegram chat, the dispatcher targets that chat. From the admin UI you can also enter chat IDs directly (comma-separated for fan-out). The dispatcher resolves recipients in this order:
+
+1. Explicit chat IDs on the cron target row (if provided in the form)
+2. Fan-out to every numeric ID in the account's `allowedUsers` whitelist
+3. The most-recent inbound chat ID, as a single-recipient fallback
+
+Want to fan out a daily report to your whole team? Add their numeric IDs to `allowedUsers` and create a cron without an explicit chat ID — halo delivers to each one and records per-recipient ✓/✗ in the cron run history.
+
+## Common problems
+
+| Symptom | Cause / fix |
+|---|---|
+| "Unauthorized" / `getMe` fails on Add Account | Bot token has a typo, or the bot was deleted in BotFather |
+| Bot exists but doesn't reply | Check `allowedUsers` — if non-empty, your user must be in it |
+| Bot used to work, now silent | Maybe two halo processes are running and stealing each other's `getUpdates` long-poll. Check `~/.halo/global/server.pid` |
+| Group messages don't trigger the bot | Expected — groups aren't supported in v1 |
+| Cron fan-out skips a whitelisted user | The user is listed as `@username`. Add their numeric ID instead |
+
+## Multi-bot setup
+
+Each BotFather token = one bot account in halo. To run two separate bots, create two tokens with BotFather and add two account rows. They can point at the same workspace (e.g. one `readonly` for general team chat + one `full` for ops) or different workspaces.
+
+## Reference
+
+- Code: `packages/server/src/channels/telegram/`
+- Routes: `packages/server/src/routes/telegram.ts`
+- Admin UI: `packages/admin/src/features/telegram/telegram-settings.tsx`
+- Design notes: [../../design/telegram.md](../../design/telegram.md)