@turmind/halo 1.5.3-alpha → 1.5.5

package/bundled-docs/dev/previews.md

@@ -8,12 +8,18 @@ Location: [`packages/admin/src/features/editor/previews/`](../../../packages/adm
 
 ```
 previews/
-├── FilePreview.tsx           Public entry. Looks up plugin by extension,
-│                             renders <Suspense><Component/></Suspense>.
-├── types.ts                  PreviewPlugin, PreviewProps
-├── registry.ts               register() / getPlugin() / registeredExtensions() / isHeavyPreview() / loadExtensions()
+├── FilePreview.tsx           Public entry. Asks the registry for the candidates for the
+│                             extension, renders the chosen one (<Suspense><Component/></Suspense>
+│                             for a built-in, the iframe host for an extension); too-large and
+│                             no-viewer placeholders.
+├── types.ts                  PreviewPlugin, PreviewProps, Resolved
+├── registry.ts               register() / setExtensions() / loadExtensions() / resolve() / canPreview() / isHeavyPreview()
+│                             + subscribe() / useRegistryVersion() so open tabs re-resolve on change
+├── extension-host.tsx        Iframe host for installed preview extensions (+ extension-host-logic.ts,
+│                             extension-token.ts) — see design/canvas-extensions.md
 ├── ui/
-│   ├── preview-shell.tsx     Standard header (filename + Open-as-Text + Download + extraToolbar)
+│   ├── preview-shell.tsx     Standard header (filename + extraToolbar + Open with + Open-as-Text + Download)
+│   ├── open-with-menu.tsx    "Open with" picker, shown only when a file has more than one viewer
 │   ├── use-preview-fetch.ts  Hook: fetch + AbortController + parse, returns {data, error, loading}
 │   ├── use-data-fetch.ts     JSON-endpoint sibling: abortable fetcher → {data, error, loading},
 │   │                         for previews that parse server-side instead of raw bytes
@@ -60,6 +66,8 @@ interface PreviewProps {
   viewUrl: string      // for inline viewing, supports HTTP Range
   downloadUrl: string  // for forced download (used by the shell's Download button)
   onOpenAsText?: () => void  // set when the file can also be force-opened as text
+  tooLarge?: boolean   // file over the editor's 10MB read cap; FilePreview shows a placeholder instead of the plugin
+  size?: number        // on-disk size in bytes, shown by that placeholder
 }
 ```
 
@@ -121,7 +129,7 @@ register(fooPlugin)
 
 Done. The Canvas panel will:
 - Treat `.foo` / `.foobar` as non-text (routes to preview instead of Monaco)
-- Mount `FooPreview` inside an MRU cache (up to 5 concurrent plugins cached)
+- Mount `FooPreview` inside an MRU cache (up to 5 concurrent previews cached)
 
 ### Routing API: `canPreview()` vs `loadExtensions()`
 
@@ -129,6 +137,7 @@ Done. The Canvas panel will:
 
 - **One-shot routing decisions** (`isBinaryExtension` in `editor-panel.tsx`: click-open, tab restore after reload, open-to-side) must `await loadExtensions()` before concluding "text", because an extension may claim an extension-only type (`.glb`) or a text suffix (`.json`). A preview verdict needs no wait — extensions only add viewers ahead of text, and `FilePreview` re-picks the viewer on a registry version bump.
 - The wait is capped at `INITIAL_LOAD_WAIT_MS` (3 s, `registry.ts`), counted from the first call; on timeout callers proceed as if nothing were installed. The request isn't cancelled — a late result still lands via `setExtensions`.
+- Candidates come from `resolve(ext)`, best first: `default` extensions → the built-in plugin → `option` extensions → Open as Text (always last). More than one candidate puts an **Open with** menu in the header.
 - It never rejects and is never re-issued: a failed fetch leaves the extension layer empty without delaying later opens. The WS-reconnect re-fetch and `extension:changed` frames fill it in.
 
 ## PreviewShell — the standard header
@@ -211,21 +220,21 @@ const { data } = usePreviewFetch(viewUrl, (buf, signal) =>
 
 ## `heavy: true` — when to use it
 
-Set `heavy: true` when the preview:
+Set `heavy: true` on a built-in when the preview:
 - Needs DOM access (can't run in a Worker — e.g. `pptx-preview` draws to canvas)
 - Is the dominant memory cost of the page (large canvas, many cached elements)
 
 Effect: the MRU cache skips this plugin. Only the **active** instance mounts; switching away unmounts the component (releases memory and stops any in-flight work). Switching back re-fetches/re-renders.
 
-Only pptx currently uses this. Don't set it by default — the MRU cache gives much faster switches.
+Only pptx currently uses this among built-ins (read-only preview extensions are also treated as heavy, judged by `isHeavyPreview()`). Don't set it by default — the MRU cache gives much faster switches.
 
 ## `onOpenAsText`
 
-When the user right-clicks a previewable file in Explorer and picks "Open as Text", Canvas closes the preview tab and opens the raw file in Monaco. The preview plugin receives this as `props.onOpenAsText` — pass it straight through to `PreviewShell` and the button appears automatically.
+The editor panel passes `props.onOpenAsText` to every preview tab. Calling it closes the preview tab and opens the raw file in Monaco. Pass it straight through to `PreviewShell` and the button appears automatically (the **Open with** menu also lists Open as text).
 
 ## Two plugin patterns: raw-bytes vs. server-parsed
 
-Most built-in plugins (pdf, docx, xlsx, pptx, media) are **raw-bytes**: `usePreviewFetch` downloads the whole file as an ArrayBuffer via `GET /api/files/download?inline=1`, then parsing happens client-side (a Worker for the heavy formats). This is the pattern documented above.
+Most built-in plugins (pdf, docx, xlsx, pptx, media) are **raw-bytes**: they load the file from `viewUrl` (`GET /api/files/download?inline=1`). docx and xlsx use `usePreviewFetch` to download it as an ArrayBuffer and parse client-side in a Worker; pptx fetches it itself and renders on the main thread; pdf and media just hand `viewUrl` to the browser (`<iframe>` / `<img>` / `<video>` / `<audio>`). This is the pattern documented above.
 
 Parquet, SQLite and CSV/TSV are **server-parsed** instead: the server does the parsing and hands back one page of JSON rows at a time via `GET /api/data-preview/*` (route details in [`dev/api.md`](api.md#data-preview)), so a multi-GB file never has to reach the browser.
 
@@ -288,4 +297,4 @@ See [`dev/api.md`](api.md) for the route details.
    - Open-as-Text button works (closes preview, opens in Monaco)
    - Closing the preview tab cleanly aborts any in-flight fetch/parse
    - Opening a second file of the same type reuses the worker (no second worker instance — check DevTools → Application → Service Workers / the process graph)
-   - Switching between up to 5 preview tabs is instant (MRU cache); the 6th oldest unmounts
+   - Switching between up to 5 preview tabs is instant (MRU cache); the 6th oldest unmounts (a dirty extension tab is never evicted)

package/bundled-docs/dev/tools.md

@@ -31,13 +31,14 @@ Write a file (creates parent dirs on demand).
 
 ### file_edit
 
-Replace a string in a file (exact match).
+Replace a string in a file (exact match). Fails when `old_string` is empty, identical to `new_string`, not found, or (without `replace_all`) found more than once.
 
 | Arg | Type | Required | Description |
 |---|---|---|---|
 | path | string | yes | File path |
 | old_string | string | yes | The exact text to find |
 | new_string | string | yes | The replacement |
+| replace_all | boolean | no | Replace every occurrence (default: false) |
 
 ### view_image
 
@@ -58,7 +59,7 @@ Processing before the bytes go out — only the payload changes, the file on dis
 
 How many images history can hold in total is capped separately at the session level — see [design/session.md → History image budget](../design/session.md#history-image-budget).
 
-**Vision gating**: this tool is only injected into the agent's tool list when the underlying model declares `capabilities.image: true` in its provider manifest. For text-only models (DeepSeek and others), `view_image` is silently dropped at `createWorkspaceTools()` time so the model never sees it — calling it would otherwise produce a 400 from the provider.
+**Vision gating**: this tool is only injected into the agent's tool list when the underlying model declares `capabilities.image: true` in its provider manifest (or the agent's `model.image` in `agent.yaml` overrides it). For text-only models (DeepSeek and others), `view_image` is silently dropped at `createWorkspaceTools()` time so the model never sees it — calling it would otherwise produce a 400 from the provider.
 
 ### file_list
 
@@ -103,7 +104,7 @@ Find files by glob.
 | pattern | string | yes | Glob, e.g. `**/*.ts`, `src/**/*.tsx` |
 | path | string | no | Starting dir (default: workspace root) |
 
-Returns paths relative to workspace root, alphabetically. Same skip list as grep.
+Returns paths relative to workspace root, alphabetically; stops collecting at 5,000 matches. Same skip list as grep.
 
 ### web_fetch
 
@@ -125,7 +126,7 @@ Each session carries `accessLevel: 'readonly' | 'workspace' | null` (persisted i
 
 | Level | DB value | Tools (with OS sandbox) | Tools (without) | Sandbox |
 |---|---|---|---|---|
-| `null` (full) | `full` | All 9 tools | All 9 tools | None (rm guard still applies) |
+| `null` (full) | `NULL` | All 9 tools | All 9 tools | None (rm guard still applies) |
 | `workspace` | `workspace` | All 9 tools | All 9 tools | workspace rw, sensitive paths + workspace runtime state hidden |
 | `readonly` | `readonly` | All 9 tools | file_read, view_image, file_list, grep, glob (5 tools) | workspace ro, sensitive paths + workspace runtime state hidden |
 
@@ -182,7 +183,7 @@ Sensitive directories and files are hidden from workspace/readonly sessions via
 | `hidden_files` | `~/.npmrc,~/.bash_history,~/.gitconfig,~/.git-credentials,~/.netrc,~/.halo/global/{evo,cron,runs}.db` + their `-wal`/`-shm` files | bwrap `--ro-bind ~/.halo/.sandbox-empty` (reads as empty); Seatbelt `literal` deny |
 | `writable_dirs` | (empty) | bwrap `--bind` read-write / Seatbelt write allow — for external CLIs that keep local state (e.g. `~/.kiro`); not applied to readonly sessions |
 
-Changes saved through the settings API (admin Settings page, `PUT` / `PATCH /api/settings`) take effect immediately — the save fires `onSettingsChange`, which re-reads the lists into `sandbox.ts` (`setSandboxHiddenPaths`), so the next tool call uses them. A hand edit of `settings.yaml` is not watched for these keys: it applies at the next restart or the next API save. These keys are `globalOnly` in the schema — a workspace `settings.yaml` cannot override them, since they define the security boundary agents run inside.
+Changes saved through the settings API (admin Settings page, `PUT` / `PATCH` / `DELETE /api/settings`) take effect immediately — the save fires `onSettingsChange`, which re-reads the lists into `sandbox.ts` (`setSandboxHiddenPaths`), so the next tool call uses them. A hand edit of `settings.yaml` is not watched for these keys: it applies at the next restart or the next API save. These keys are `globalOnly` in the schema — a workspace `settings.yaml` cannot override them, since they define the security boundary agents run inside.
 
 **Workspace-relative set (hardcoded)** — the workspace's own runtime state, which holds other channels'/users' conversations on a shared workspace. Code constants in `sandbox.ts` (`WORKSPACE_HIDDEN_DIRS` / `WORKSPACE_HIDDEN_FILES`), deliberately not settings: this is a security boundary (a config edit must not be able to open it), and the entries are workspace-relative while the settings lists are absolute/`~` paths.
 
@@ -198,7 +199,7 @@ The rest of `.halo/` (INSTRUCTIONS.md, INDEX.md, docs/, memory/, skills/, agents
 Per-channel defaults: every channel session (Web, Telegram, Slack, Feishu, WeCom, WeChat) inherits its account's `access_level` — `full` → full, `workspace` → workspace, `readonly` / `observer` → readonly — and new accounts default to `readonly` (DB column default, `insertAccount` fallback and the admin create forms). Level sources for every entry point (admin, cron, cli, relay, goal, sub-agents): [guide/delegation-and-access.md](../guide/delegation-and-access.md#where-a-sessions-level-comes-from).
 
 ### Binary file detection
-`grep` and `glob` read the first 512 bytes looking for a null byte and skip binaries.
+`grep` reads the first 512 bytes of each file looking for a null byte and skips binaries (`glob` matches paths only and never opens files).
 
 ### Tool result budget
 The orchestrator truncates tool results over 8000 chars and appends a `[Content truncated]` hint telling the agent to use `grep` for a targeted search. `activate_skill` results are exempt — a SKILL.md body is instructions, not data, and the built-in acp / cron / self skills exceed 8K.
@@ -227,6 +228,7 @@ Start a sub-agent session asynchronously. When the sub-agent finishes, its **wra
 
 - Success: `{"code": 0, "session_id": "<childSessionId>"}`
 - Unknown agent: `{"code": 1, "error": "agent \"<id>\" not found..."}`
+- Agent outside the caller's `team`: `{"code": 1, "error": "agent \"<id>\" is not in your team..."}`
 - Depth exceeded: `{"code": 1, "error": "Maximum nesting depth (N) reached..."}`
 - Working dir invalid: `{"code": 1, "error": "working_dir \"...\" is outside the workspace"}` (or does-not-exist / not-a-directory)
 
@@ -244,12 +246,21 @@ No arguments. Returns JSON:
   "sessions": [
     {
       "id": "root>sid_xxx",
+      "parentId": "root",
       "agentId": "coder",
       "agentName": "Coder",
-      "title": "Implement login page",
       "description": "Implement login page",
       "status": "running",
-      "createdAt": 1714000000000
+      "accessLevel": null,
+      "goalSessionId": null,
+      "createdAt": 1714000000000,
+      "updatedAt": 1714000005000,
+      "stoppedAt": null,
+      "archivedAt": null,
+      "title": "Implement login page",
+      "exchangeCount": 1,
+      "contextTokens": 12345,
+      "totalOutputTokens": 678
     }
   ],
   "count": 1
@@ -258,10 +269,11 @@ No arguments. Returns JSON:
 
 `status`: `running` / `idle` / `stopped`. Archived sessions are excluded.
 
-`title` is the human-assigned label (set by renaming the session in the admin
-sidebar), read from the per-session jsonl log so it matches what the UI shows.
-It falls back to `description` (the `start_session` task summary) when no title
-was set, so the field is never empty — lets a caller dispatch work by title.
+Each entry is the session's `SessionInfo` row. `title` is the human-assigned
+label (set by renaming the session in the admin sidebar) mirrored onto the row
+from the session file, so it matches what the UI shows. It falls back to
+`description` (the `start_session` task summary) when no title was set, so the
+field is never empty — lets a caller dispatch work by title.
 
 ### query_session
 

package/bundled-docs/guide/README.md

@@ -20,6 +20,7 @@ Aimed at Halo end-users. Pick the doc that matches your situation.
 - [Telegram](channels/telegram.md) — BotFather token, long-poll
 - [Slack](channels/slack.md) — Socket Mode (no public webhook needed)
 - [Feishu / Lark](channels/feishu.md) — long-connect with appId + appSecret
+- [WeCom](channels/wecom.md) — 企业微信 intelligent bot, long-connect with Bot ID + Secret
 - [WeChat](channels/wechat.md) — QR-scan iLink bot
 - [ACP](channels/acp.md) — Claude Code or other ACP clients driving a remote halo
 

package/bundled-docs/guide/agents.md

@@ -6,17 +6,17 @@ The agent is Halo's core abstraction: personality (AGENT.md) + config (agent.yam
 
 | Kind | Description |
 |---|---|
-| Built-in | Server-shipped agents (`default`, `executor`, `deep-executor` + the three internal `__evo_agent__` / `__score__` / `__apply_agent__`). Live under `~/.halo/global/agents/<id>/`. **Force-overwritten on every server startup** — local edits to these files will be lost on the next start. To customize: copy into the workspace scope (workspace replaces global) and edit there. |
+| Built-in | Server-shipped agents (`default`, `executor`, `deep-executor` + the internal `goal` / `__evo_agent__` / `__score__` / `__apply_agent__`; `goal` is seeded like the rest but only usable when `general.goal_mode_enabled` is set — off by default, no UI). Live under `~/.halo/global/agents/<id>/`. **Force-overwritten on every server startup** — local edits to these files will be lost on the next start. To customize: copy into the workspace scope (workspace replaces global) and edit there. |
 | Global | Any other agent under `~/.halo/global/agents/<id>/`, e.g. one you created via the admin UI. Shared across projects. Never overwritten by the server. |
 | Workspace | `<project>/.halo/agents/<id>/`, private to the current project; same-id workspace wins over global. Override is **whole-folder**: the workspace agent folder replaces the global one entirely, so copy *both* `agent.yaml` and `AGENT.md` when customizing — a folder with only `AGENT.md` has no model config and won't load. |
 
 ## Open the Agents panel
 
-Click the `👥 Agents` icon in the Activity Bar.
+Click the `🤖 Agents` icon in the Activity Bar.
 
 ```
 ┌─────────────────┬──────────────────────────┐
-│ Agents          │  Form / YAML / MD Editor │
+│ Agents          │  Form / Edit             │
 │─────────────────│                          │
 │ ▼ Global    (2) │                          │
 │   🤖 Default    │                          │
@@ -28,38 +28,32 @@ Click the `👥 Agents` icon in the Activity Bar.
 
 ## Create an agent
 
-Top-of-sidebar `+` button; modal asks for:
+Click the `+` on the **Global** or **Workspace** group header in the sidebar (the group you click decides the scope; Workspace needs an open workspace). Two prompts follow:
 - **Name**: display name (e.g. "Coder")
-- **Description**: one-line description
-- **Scope**: Global / Workspace
+- **Description**: one-line description (optional)
 
 The backend calls `defaultAgentYaml(name, description)` to generate a minimal `agent.yaml`.
 
 ## Edit an agent
 
-Click an agent in the sidebar to open the right-hand editor. Three views:
+Click an agent in the sidebar to open the right-hand editor. Two views:
 
 ### Form view
-Data-driven form for name / description / model / tools / skills / thinking — click Save.
+Data-driven form for name / description / model / tools / skills / thinking. Changes auto-save about half a second after you stop editing — there's no Save button. The agent's AGENT.md is shown below the form as a read-only preview.
 
 **Model section** has four fields:
 - `provider` — dropdown populated from `~/.halo/global/models/*.yaml`
-- `id` — combobox (input + datalist); preset options filtered by current provider, also accepts manual input of any Bedrock model ID
+- `id` — combobox (input + datalist); preset options filtered by current provider, also accepts manual input of any model ID
 - `endpoint` — combobox (input + datalist); full endpoint URL (e.g. `https://bedrock-runtime.ap-northeast-1.amazonaws.com`), supports custom proxy URLs
 - `maxTokens` — optional; defaults to `maxOutputTokens` in the provider yaml
 
-Switching provider auto-resets the model id to the first model of the new provider.
+Switching provider resets the model id to the new provider's default model (its `defaultModelId`), keeping the current id when the new provider lists it too.
 
 **Capability buttons** (Prompt Caching / Thinking) appear when the selected model matches a registry entry with declared capabilities. For manually entered model IDs not in the registry, default presets are shown (5min/1hour for caching, Low/Medium/High/Max for thinking).
 
-### YAML view
-Edit `agent.yaml` directly (Monaco). Use this for advanced settings (like `context.maxTokens`, `promptCaching`).
-
-### MD view
-Edit `AGENT.md` (personality) and `INSTRUCTIONS.md` (preferences).
+### Edit view
+The **Edit** button (top right) opens the agent's folder in a mini workspace (file tree + Monaco); **Back** returns to the form. Edit `agent.yaml` directly for advanced settings (like `context.maxTokens`, `promptCaching`) and `AGENT.md` for the personality.
 - `AGENT.md` takes precedence over YAML's `system_prompt`
-- `INSTRUCTIONS.md` is injected into every agent, not just this one
-- When a workspace is open, the top-right toggles **Global / Workspace**; both MDs can be edited independently of which scope the current agent lives in. Switching to a non-existent file shows `(new)`; saving auto-creates the dir/file.
 - AGENT.md supports `{{var}}` placeholders (`{{<skill-id>.params.<key>}}` / `<<ENV>>` / built-ins) rendered on agent start — see [skills.md placeholder section](skills.md#placeholders-template-variables)
 
 ## Tool configuration
@@ -75,7 +69,7 @@ team:                 # a non-empty team is what enables delegation
   - executor          # the agent ids this one may spawn
 ```
 
-**Workspace tools**: `file_read / file_write / file_edit / file_list / shell_exec / grep / glob / web_fetch` — listed by name under `tools`.
+**Workspace tools**: `file_read / view_image / file_write / file_edit / file_list / shell_exec / grep / glob / web_fetch` — listed by name under `tools`.
 
 **Session tools**: `start_session / session_list / query_session / interrupt_session / stop_session / archive_session / get_session_output / query_agent` — **not** listed under `tools`. The whole bundle is granted automatically the moment an agent declares a non-empty `team`; an empty/absent `team` means no delegation (no session tools, no roster). To let a sub-agent delegate further, give it its own `team`. Add the agent's own id to its `team` to enable parallel self-spawn.
 
@@ -123,13 +117,14 @@ Internal agents (`internal: true`, e.g. self-evolution agents) have no Test butt
 
 ## Delete
 
-Right-click → Delete. Constraints:
+Hover a **workspace** agent in the sidebar and click its trash icon. Global agents show a crown instead (no delete button there). Constraints:
 - The last global agent cannot be deleted (server-enforced)
 - Workspace agents delete freely
+- `/agent delete <name>` (full access) removes either kind
 
 ## Common workflows
 
-**Copy a global agent into workspace for customisation**: edit it in Form view, switch scope to Workspace, Save — creates an independent copy under `<project>/.halo/agents/<id>/`.
+**Copy a global agent into workspace for customisation**: copy the whole folder `~/.halo/global/agents/<id>/` to `<project>/.halo/agents/<id>/` and edit there. (Clicking `+` on Workspace with the same name creates a fresh scaffold under the same id, not a copy.)
 
 **Multi-agent collaboration**: the Default agent sees its teammates in the prompt roster, starts them with `start_session`, and the sub-agent auto-reports on completion. See [sessions.md](sessions.md).
 
@@ -146,7 +141,7 @@ priority: 0
 
 model:
   provider: aws-bedrock-claude-invoke       # required, matches ~/.halo/global/models/<provider>.yaml
-  id: global.anthropic.claude-sonnet-4-6   # default from settings.yaml params.model.default
+  id: global.anthropic.claude-sonnet-4-6   # the provider yaml's defaultModelId
   endpoint: https://bedrock-runtime.us-west-2.amazonaws.com  # full endpoint URL; supports custom proxy
   maxTokens: 16384                   # optional, max output tokens (default from provider yaml)
 
@@ -226,41 +221,12 @@ nano-banana:
     api_key: <<NANO_BANANA_KEY>>
 ```
 
-…where the schema lives at `extensions/skills/nano-banana/config.yaml`.
+…where the schema lives in the skill's own `config.yaml` (`skills/nano-banana/config.yaml`).
 
 With `export NANO_BANANA_KEY=sk-xxx` in the env, the agent's system prompt gets the real key on start.
 
 ## Model registry — adding a new provider
 
-Halo ships with `aws-bedrock-claude-invoke` only. Hooking up OpenAI / direct Anthropic / another Bedrock variant takes two steps:
-
-### 1. Declare the provider
-
-Create `~/.halo/global/models/<providerId>.yaml`:
-
-```yaml
-id: openai                             # required; matches the filename
-displayName: OpenAI
-description: OpenAI Chat Completions
-models:
-  - id: gpt-4o
-    displayName: GPT-4o
-    maxOutputTokens: 16384
-    capabilities:
-      promptCaching:
-        ttlPresets:
-          - { value: 5m, label: 5min }
-  # No thinking block → UI automatically hides the Thinking button
-```
-
-### 2. Implement the runtime
-
-Add a case in the switch inside [packages/server/src/agents/model-runtime.ts](../../../packages/server/src/agents/model-runtime.ts) returning a class that implements `ModelRuntime` (`messages` + `run()`). Interface detail in [design/agent.md](../design/agent.md#agent-instance).
-
-### Usage
-
-Set `model.provider: openai` in your agent.yaml; the Provider dropdown in Form view lists it automatically.
-
-### Current state
+Halo ships 13 providers (`aws-bedrock-claude-invoke`, `aws-bedrock-mantle`, `aws-bedrock-openai`, `anthropic`, `openai`, `kimi`, `deepseek`, `minimax`, `qwen`, `hunyuan`, `doubao`, `zhipu`, `mimo-token-plan-china`); each one is a yaml under `~/.halo/global/models/` plus a matching case in [packages/server/src/agents/model-runtime.ts](../../../packages/server/src/agents/model-runtime.ts). For any OpenAI- or Anthropic-compatible endpoint you don't need new code: pick `openai` or `anthropic` as the provider and fill in the endpoint and model id in Form view.
 
-Only `aws-bedrock-claude-invoke` ships an implementation. If you drop a provider yaml without a runtime implementation, session spawn fails with `Unknown provider "..."`.
+A truly new provider takes a yaml manifest plus a runtime case; the step-by-step is in [dev/add-model-provider.md](../dev/add-model-provider.md). If you drop a provider yaml without a runtime case, session spawn fails with `Unknown provider "..."`.

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

@@ -28,7 +28,7 @@ This folder has one onboarding guide per channel. Pick the one you want and foll
                           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`.
+Each channel handler is a thin adapter between its native protocol and halo's `SessionManager`. Slash commands (`/session` `/agent` `/skill` `/workspace` `/cron` `/acp` `/evo` `/extension` `/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.
 
@@ -42,16 +42,19 @@ 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 |
+| WeCom | Bot ID, Secret, workspace path | Label, access level, language | 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 |
 
+In the admin account list every row shows an access-level badge next to its name, and a red **(path does not exist)** after the workspace path when the bound folder is missing on disk (the account is skipped at startup until you re-bind it). Secret fields in the Add forms (Telegram bot token, Slack bot / app tokens, Feishu App Secret and Encrypt Key, WeCom Secret) are password inputs — pasted values are masked.
+
 ## 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
+- `readonly` (default) — sandboxed, workspace mounted read-only, secrets dir not mounted. With an OS sandbox the agent gets all its tools (writes fail); without one only the read-only tools (`file_read`, `view_image`, `file_list`, `grep`, `glob`)
 - `workspace` — sandboxed, workspace mounted read-write, secrets dir not mounted
-- `full` — no sandbox, all tools, can `/workspace <path>` to another workspace
+- `full` — no sandbox, all tools, can `/workspace switch <path>` to another workspace
+- `observer` — Web accounts only: global read-only, meant for dashboards / metrics (Halo City, `/api/metrics`); chat runs at `readonly`. A chat-channel account that still holds `observer` from older data shows an Observer badge, and its edit form keeps that level unless you pick another one
 
 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.
 

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

@@ -54,6 +54,8 @@ halo acp \
 | `--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` (alias `--agent`) |
+| `--scheme` | no | `http` (default) or `https` — use `https` for a server behind a TLS reverse proxy |
+| `--header "Name: value"` | no | Repeatable. Extra HTTP header sent on every request (like `curl -H`), for auth in front of the server — proxy cookie, `CF-Access-*`, basic auth |
 
 Each adapter process binds to **one** workspace. To drive multiple workspaces concurrently from one token, run multiple adapter processes — one per workspace.
 
@@ -139,7 +141,7 @@ For now: if you want the agent to see a Mac-side file, paste it into the prompt.
 | `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 |
+| 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 — session busy]`. 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

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

@@ -77,16 +77,16 @@ After approval the bot is visible in your Feishu tenant. Repeat this step **ever
 
 ## Step 7 — Add the account in halo admin
 
-Open halo admin → **Channels** → **Feishu** → **Add Account**:
+Open halo admin → **Channels** → **Feishu** → **Add Bot**:
 
 | 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 |
+| Verification Token (optional) | leave blank (long-connect doesn't use it) |
+| Encrypt Key (optional) | leave blank (long-connect doesn't encrypt the wire) |
+| Bind to workspace | absolute path, e.g. `/home/ubuntu/my-project` |
+| Name (optional) | a label for the account |
 | Access level | `readonly` (default), `workspace`, or `full` |
 | Language | `en` or `zh` |
 
@@ -109,7 +109,7 @@ 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.
+If nothing happens, check halo server logs (`~/.halo/global/logs/server.log`) for `[Feishu]` lines.
 
 ## How halo handles inbound
 
@@ -117,18 +117,20 @@ If nothing happens, check halo server logs (`/tmp/halo-server.log`) for `[feishu
 - **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>/`
+- **After a server restart** — if the agent was mid-task when halo restarted, its reply still reaches the most recent 1:1 DM the bot talked in; group threads reconnect on their next `@`-mention
 - **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:
+Same set as the other channels — type as plain text, **in a 1:1 DM only** (in a group the text goes to the agent as a normal message):
 
 | Command | Effect |
 |---|---|
-| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` |
+| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` / `info` |
 | `/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) |
+| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 
 ## Cron jobs targeting Feishu
@@ -145,12 +147,12 @@ Search depends on the contact and `im:chat:readonly` scopes from Step 4. If auto
 
 | 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 |
+| `99991663` on Add Bot | App Secret wrong — copy it again from Step 2 |
+| `99991668` on Add Bot | 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 |
+| Multiple halo instances reply to the same message | Only one process should hold the long-connect. Check `~/.halo/global/server.lock` for the lock |
 
 ## Multi-tenant setup
 

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

@@ -83,14 +83,14 @@ In the Slack desktop client, fully quit and reopen (or `Cmd+R` to reload) — ot
 
 ## Step 7 — Add the account in halo admin
 
-Open halo admin → **Channels** → **Slack** → **Add Account**:
+Open halo admin → **Channels** → **Slack** → **Add Bot**:
 
 | 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" |
+| Bot Token (xoxb-…) | the `xoxb-…` from Step 5 |
+| App Token (xapp-…) | the `xapp-…` from Step 2 |
+| Bind to workspace | absolute path to the workspace this bot drives, e.g. `/home/ubuntu/my-project` |
+| Name (optional) | e.g. "Engineering bot" |
 | Access level | `readonly` (default), `workspace`, or `full` |
 | Language | `en` or `zh` |
 
@@ -111,7 +111,7 @@ Pick the level with that in mind:
 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.
+If nothing happens, check the halo server logs (`~/.halo/global/logs/server.log`) for `[Slack]` lines.
 
 ## How halo handles inbound
 
@@ -119,18 +119,20 @@ If nothing happens, check the halo server logs (`/tmp/halo-server.log`) for `[sl
 - **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>/`
+- **After a server restart** — if the agent was mid-task when halo restarted, its reply still reaches the most recent conversation (DM or thread) the bot talked in (one per bot); other threads reconnect on their next message
 - **`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:
+Same set as the other channels, but **only in a DM with the bot** — in a channel or thread the text goes to the agent as a normal message. Slack's own client intercepts a leading `/`, so type `!` instead (e.g. `!session list`); halo treats `!cmd` as `/cmd` and shows `!…` in its replies. The table below uses `/`:
 
 | Command | Effect |
 |---|---|
-| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` |
+| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` / `info` |
 | `/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) |
+| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 
 ## Cron jobs targeting Slack
@@ -149,10 +151,10 @@ The search depends on the `users:read` / `channels:read` scopes added in Step 4.
 |---|---|
 | **"向此应用发送消息的功能已关闭"** 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 |
+| `not_authed` / `invalid_auth` error on Add Bot | 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 |
+| Multiple halo instances reply to the same message | Only one process should hold the Socket Mode connection. Check `~/.halo/global/server.lock` for the lock |
 
 ## Multi-workspace setup