@turmind/halo 1.5.4 → 1.5.6

package/bundled-docs/dev/env.md

@@ -51,9 +51,9 @@ nohup node dist/index.js >> /dev/null 2>&1 &   # HALO_PASSWORD read from env/con
 ## Prerequisites
 
 - Node.js ≥ 22 (better-sqlite3 native binding is bound to v22)
-- pnpm ≥ 9
+- pnpm 11 (pinned by the root `packageManager`; `corepack enable` picks it up)
 - AWS credentials configured (`~/.aws/credentials` or env vars) with Bedrock access
-- bubblewrap (`sudo apt install bubblewrap`) — OS-level sandbox for non-full access levels. Without it, only app-level path validation is active and `shell_exec` is blocked for non-full sessions
+- bubblewrap (`sudo apt install bubblewrap`) — OS-level sandbox for non-full access levels on Linux (macOS uses the built-in Seatbelt). Without one, only app-level path validation is active and `shell_exec` is blocked for non-full sessions
 
 ### nvm PATH
 
@@ -67,7 +67,7 @@ Your deployment scripts should also prepend this line.
 
 ## Runtime directories
 
-- SQLite: `<workspace>/.halo/halo.db` (per-workspace, auto-created on first use) + global queues `~/.halo/global/evo.db`, `~/.halo/global/cron.db` and `~/.halo/global/runs.db`
+- SQLite: `<workspace>/.halo/halo.db` (per-workspace, auto-created on first use) + global queues `~/.halo/global/evo.db`, `~/.halo/global/cron.db` and `~/.halo/global/runs.db` + channel accounts `~/.halo/secrets/channels/channels.db`
 - Session files: `.halo/sessions/{agentId}/{sessionId}.json`
 - Global config: `~/.halo/global/`
 - Per-project config: `<workspace>/.halo/`
@@ -78,15 +78,16 @@ Three config file types, precedence **env vars > config.yaml / settings.yaml > c
 
 | File | Scope | Contents |
 |---|---|---|
-| `~/.halo/secrets/config.yaml` | System | Port, password, CORS, timeouts, limits, logging — "infrastructure" settings |
-| `~/.halo/secrets/settings.yaml` | User | Model, region, session behaviour — "preferences" |
-| `<project>/.halo/settings.yaml` | Project | Overrides of global settings |
+| `~/.halo/secrets/config.yaml` | System | Port, password, JWT secret, CORS, timeouts, log rotation — "infrastructure" settings |
+| `~/.halo/secrets/settings.yaml` | User | Provider secrets, skill params, `general.*` server knobs (session, compaction, limits, sandbox, logging) — "preferences" |
+| `<project>/.halo/settings.yaml` | Project | Overrides of provider / skill `params` and `secrets`; every `general.*` key is global-only (a workspace value is rejected by the API and ignored at runtime) |
 
 `init.ts` seeds these on first run with a per-category policy. Refresh trigger: `halo setup` always re-runs the seed, and the server's startup check re-runs it automatically when `~/.halo/global/.template-version` is behind the bundled `TEMPLATE_VERSION` (see `init.ts:TEMPLATE_VERSION` + `index.ts` startup block).
 
-- **Always overwritten** (platform-owned, refreshed when the template version moves): `~/.halo/global/{prompts,models,docs}/`, `INSTRUCTIONS.md`, the built-in agent ids (`default`, `executor`, `deep-executor`, `__evo_agent__`, `__score__`, `__apply_agent__`), built-in skill ids (`agent`, `skill`, `workspace`, `cron`, `acp`, `send-file`, `self`, `aws-knowledge`, `nova-web-search`, `halo`).
-- **Built-in agents** keep the user's `model:` block on overwrite — the admin UI lets users change which model an agent uses, and that choice survives upgrades.
+- **Always overwritten** (platform-owned, refreshed when the template version moves): `~/.halo/global/{prompts,models,docs}/`, `INSTRUCTIONS.md`, the built-in agent ids (`default`, `executor`, `deep-executor`, `goal`, `__evo_agent__`, `__score__`, `__apply_agent__`), built-in skill ids (`agent`, `skill`, `workspace`, `cron`, `acp`, `send-file`, `aws-knowledge`, `web-search`, `self`, `halo`, `extension`).
+- **Built-in agents** keep the user's `model:` and `context:` blocks on overwrite — the admin UI lets users change which model an agent uses and its context limits, and that choice survives upgrades.
 - **Optional skills** (`tavily-web-search`) install only when picked via `halo setup`; the opt-in list is `~/.halo/global/.installed-optional-skills`. Picked skills are force-overwritten alongside the always-overwritten set.
+- **Skill params in `halo setup`**: a newly picked optional skill walks all its declared params; for built-in skills setup asks only the `secret: true` ones (`listRequiredSkillsWithSecrets`, `setup-providers.ts`) — plain params such as `extension.params.hub_repo` / `web-search.params.fast_region` are set in Settings → Skills only.
 - **`secrets/config.yaml`** is leaf-merged: existing leaf `value`s preserved, new leaves added when a server upgrade introduces them.
 - **`secrets/settings.yaml`** is created empty if missing and never touched again. Defaults live in `settings-schema.ts`.
 
@@ -99,7 +100,7 @@ Source: `packages/server/src/config.ts`
 | `HALO_PORT` | `9527` | `config.yaml server.port` | Hono listen port |
 | `HALO_PASSWORD` | (none) | `config.yaml server.password` (scrypt hash) | Plaintext login password. When set, takes precedence over the stored hash and bypasses scrypt entirely — intended for Docker / systemd / CI. It also satisfies the **startup gate**: the server refuses to boot with no password configured, and env plaintext counts as a first-class credential there, so an env-only deployment (`halo setup -y && HALO_PASSWORD=... halo server start`, no stored hash) boots fine. The hash is set by `halo setup` for interactive installs. |
 | `HALO_CORS_ORIGINS` | empty (reflect any origin) | `config.yaml server.cors_origins` | CORS allowlist (comma-separated). Empty = reflect any incoming Origin so credentials work cross-origin. Set explicit list to enforce strict CORS. |
-| `HALO_FRONTEND_DIR` | `packages/admin/out` | — | Static frontend dir (resolved as absolute path from project root) |
+| `HALO_FRONTEND_DIR` | auto (bundled `admin-out`, else `packages/admin/out`) | — | Static frontend dir; resolved against the current working directory |
 | `HALO_MAX_CONTEXT_TOKENS` | `272000` | — | Model max context |
 | `HALO_SHELL_TIMEOUT` | `120000` | `config.yaml timeout.shell_exec` | Shell command timeout (ms) |
 | `HALO_WEB_FETCH_TIMEOUT` | `10000` | `config.yaml timeout.web_fetch` | web_fetch timeout |
@@ -111,22 +112,26 @@ Source: `packages/server/src/config.ts`
 | `HALO_LOG_MAX_FILES` | `5` | `config.yaml logging.max_files` | Retained rotated logs |
 | `HALO_LOG_LEVEL` | `warn` | `settings.yaml general.logging.level` | Log level: debug \| info \| warn \| error |
 | `HALO_JWT_SECRET` | (none) | `config.yaml server.jwt_secret` | JWT signing secret (generated by `halo setup` if missing; stripped from child-process env) |
-| `HALO_BADGE` | (none) | — | Environment badge (e.g. `DEV`) returned by `GET /api/auth/check` on **both** the 200 and 401 branches, so the admin can brand the login screen too. The admin repaints the favicon with a badge band and prefixes the tab title, making parallel dev/prod tabs tellable apart. dev and prod serve the same static build, so this has to be a runtime signal. Unset / whitespace-only → `null` → stock branding. Because the 401 branch carries it, the value is **public to unauthenticated clients** — keep it a label (`DEV`, `staging`), never anything sensitive. |
+| `HALO_BADGE` | (none) | — | Environment badge (e.g. `DEV`) returned by `GET /api/auth/check` on **both** the 200 and 401 branches, so the admin can brand the login screen too. The admin repaints the favicon with a badge band and prefixes the tab title, making parallel dev/prod tabs tellable apart. dev and prod serve the same static build, so this has to be a runtime signal. Unset / whitespace-only → `null` → stock branding. Because the 401 branch carries it, the value is **public to unauthenticated clients** — keep it a label (`DEV`, `staging`), never anything sensitive. `DEV` (trimmed, any case) also makes the server a **non-owner of workspace runtimes**: it never claims `<workspace>/.halo/runtime.lock` and skips boot cleanup (orphan reconcile, goal / run-ledger sweeps), leaving both to the prod server that shares those workspaces. Any other value → normal owner. See [storage.md](../design/storage.md#workspace-runtime-lock). |
 | `HALO_RUNTIME_MODE` | (none) | — | `agentcore` runs the server as an Amazon Bedrock AgentCore Runtime container (see [design/agentcore.md](../design/agentcore.md)) |
 | `HALO_WORKSPACE` | `process.cwd()` | — | Workspace root in agentcore mode |
+| `HALO_DEFAULT_PROVIDER` | (none) | — | Read by `halo setup --non-interactive`: binds the built-in agents to this provider id (and its default model). An unknown id only prints a warning |
+| `HALO_CLI` | `halo` (`halo.cmd` on Windows) | — | `halo` cli executable that cron runs and the evolution wrapper spawn — a dev override |
+| `HALO_VERSION` | `dev` | — | Version string reported by `GET /api/health` and the cli; stamped by the bundle / desktop launcher, so normally not set by hand |
+| `HALO_PROMPT` | (none) | — | `plain` makes `halo setup` use numbered-menu prompts instead of the raw-mode TUI |
 
 settings.yaml only (no env override):
-- `general.session.max_queue_size` (default 256)
-- `general.session.max_nesting_depth` (default 16)
-- `general.agent.max_retries` (default 5)
-- `general.compact.keep_messages` (default 5) — recent messages to keep uncompacted
-- `general.compact.max_summary_input` (default 15000) — local compaction fallback input cap
-- `general.compact.max_message_slice` (default 800) — local compaction per-message cap
+- `general.session.max_queue_size` (default 256), restart required
+- `general.session.max_nesting_depth` (default 16), restart required
+- `general.agent.max_retries` (default 5), restart required
+- `general.compact.keep_messages` (default 5) — recent messages to keep uncompacted, restart required
+- `general.compact.max_summary_input` (default 15000) — local compaction fallback input cap, restart required
+- `general.compact.max_message_slice` (default 800) — local compaction per-message cap, restart required
 - `general.server.trust_proxy` (default `false`) — trust `x-forwarded-for` for client IP resolution, scope: global (enable only behind a reverse proxy you control)
-- `general.sandbox.hidden_dirs` (default `~/.halo/secrets,~/.aws,~/.ssh,~/.gnupg,~/.docker,~/.config/gh,~/.halo/global/internal-sessions,~/.halo/global/logs`) — hidden from workspace/readonly sessions (bwrap tmpfs overlays on Linux, Seatbelt deny on macOS), scope: global
+- `general.sandbox.hidden_dirs` (default empty) — extra dirs hidden from workspace/readonly sessions (bwrap tmpfs overlays on Linux, Seatbelt deny on macOS), **appended** to the built-in list, which is always included (`~/.halo/secrets,~/.aws,~/.ssh,~/.gnupg,~/.docker,~/.config/gh,~/.halo/global/internal-sessions,~/.halo/global/logs`); Full sessions, the admin file explorer and the terminal are not affected, scope: global
 - `general.sandbox.writable_dirs` (default empty) — dirs writable inside the sandbox besides the workspace (Linux / macOS), for external CLIs that keep local state (e.g. `~/.kiro`); not applied to readonly sessions, scope: global
-- `general.sandbox.hidden_files` (default `~/.npmrc,~/.bash_history,~/.gitconfig,~/.git-credentials,~/.netrc,~/.halo/global/{evo,cron,runs}.db` + their `-wal`/`-shm` files) — hidden from workspace/readonly sessions, read as empty files (bwrap bind of `~/.halo/.sandbox-empty` on Linux, Seatbelt deny on macOS), scope: global
-- `general.logging.level` (default `warn`) — log level: debug | info | warn | error
+- `general.sandbox.hidden_files` (default empty) — extra files hidden from workspace/readonly sessions, read as empty files (bwrap bind of `~/.halo/.sandbox-empty` on Linux, Seatbelt deny on macOS), **appended** to the built-in list, which is always included (`~/.npmrc,~/.bash_history,~/.gitconfig,~/.git-credentials,~/.netrc,~/.halo/global/{evo,cron,runs}.db` + their `-wal`/`-shm` files); Full sessions, the admin file explorer and the terminal are not affected, scope: global
+- `general.logging.level` (default `warn`) — log level: debug | info | warn | error, restart required
 - `general.observability.endpoint` (default `''`) — OTLP collector base URL (e.g. `http://localhost:4318`); empty = off, scope: global, restart required. See [design/observability.md](../design/observability.md)
 - `general.observability.service_name` (default `halo`) — OTel resource `service.name`, scope: global, restart required
 - `general.observability.headers` (default `''`, secret) — extra OTLP request headers, comma-separated `k=v`, scope: global, restart required
@@ -140,7 +145,9 @@ settings.yaml only (no env override):
 When a provider manifest declares a `default: <<NAME>>` for a secret, `halo setup` offers a "Use env $NAME" action. Picking it **writes the literal `<<NAME>>` placeholder into settings.yaml**, which the standard env-var interpolation ([storage.md](../design/storage.md#env-var-interpolation-env_name)) expands against `process.env` at read time. There is no separate runtime env fallback — the placeholder in the file is the only mechanism (an unset env var leaves the literal `<<NAME>>` visible in the request, failing loudly).
 
 `<skill-id>.params.*` (referenceable from skills via `{{<skill-id>.params.<key>}}`, or short form `{{params.<key>}}` inside SKILL.md; declared in `skills/<id>/config.yaml`):
-- `tavily-search.params.api_key` — example only; declared by whichever skill needs it
+- `tavily-web-search.params.api_key` — example only; declared by whichever skill needs it
+- `web-search.params.fast_region` / `web-search.params.deep_region` — AWS regions for web-search's fast gear (Nova grounding, US only; empty = us-east-1) and deep gear (Bedrock Mantle; empty = us-west-2 for luna, us-east-1 for sol, and sol set to a region it isn't offered in falls back to us-east-1)
+- `extension.params.hub_repo` — hub `/extension install <id>` pulls from (empty = `https://github.com/turmind/halo-hub`); the skill's `ext.sh` also reads the optional `GITHUB_TOKEN` / `GITLAB_TOKEN` / `GITEA_TOKEN` from the server environment and sends them to that hub's release API only. See [design/canvas-extensions.md](../design/canvas-extensions.md#extension-skill-and-halo-hub)
 
 Hardcoded (config.ts, no override):
 - `auth.tokenMaxAge` — 14 days
@@ -152,7 +159,8 @@ settings.yaml-driven `general.limits.*` (no env override):
 - `general.limits.web_fetch_bytes` (default 50 KiB)
 - `general.limits.grep_default_matches` (default 50)
 - `general.limits.tool_result_render_chars` (default 8000)
-- `general.limits.ws_event_buffer` (default 5000)
+- `general.limits.tool_result_ui_chars` (default 64 KiB)
+- `general.limits.auto_report_chars` (default 8192)
 - `general.limits.terminal_scrollback_bytes` (default 50000)
 
 Two ways to authenticate:

package/bundled-docs/dev/logging.md

@@ -6,28 +6,26 @@ File: `packages/server/src/logger.ts`
 
 ## Architecture
 
-On startup the logger intercepts `console.log` / `console.error` / `console.warn` / `console.debug`. Every call writes twice:
+On startup the logger intercepts `console.log` / `console.error` / `console.warn` / `console.debug`. A call that passes the level gate (`general.logging.level` / `HALO_LOG_LEVEL`, default `warn`) writes to:
 1. The original console (stdout/stderr) — live monitoring
 2. A disk log file — persistent history
+3. The OTel logger, when observability is on (see [design/observability.md](../design/observability.md))
 
-## Log locations
+Any `?token=…` value in a message is replaced with `?token=<redacted>` before it reaches a sink.
 
-| Scenario | Directory | File |
-|---|---|---|
-| Default (no workspace) | `~/.halo/logs/` | `server.log` |
-| Workspace open | `<project>/.halo/logs/` | `server.log` |
+## Log locations
 
-When the WS handler receives a `subscribe` or `chat` with `projectId`, it calls `setLogDir()` to switch to the project's log directory.
+One file for the whole server: `~/.halo/global/logs/server.log`. A single server process serves many workspaces, so there is no per-workspace log. Cron runs and evolution runs keep their own logs under `~/.halo/global/logs/{cron,evo}/`. `halo server start -d` additionally captures the process's stdout/stderr in `~/.halo/logs/server.log` (plus the supervisor's `[respawn]` lines) — that is the file `halo server logs` tails.
 
 ## Log format
 
 ```
-2026-04-19T10:30:00.000Z INFO  [Server] Hono server listening on http://localhost:9527
-2026-04-19T10:30:01.234Z ERROR [WS] Chat error: ThrottlingException
-2026-04-19T10:30:02.567Z WARN  [Orchestrator] Context overflow, auto-compacting...
+time=2026-04-19T10:30:00.000Z level=info [Server] Hono server listening on http://localhost:9527
+time=2026-04-19T10:30:01.234Z level=error [WS] Chat error: ThrottlingException
+time=2026-04-19T10:30:02.567Z level=warn [SessionManager] Context overflow, auto-compacting...
 ```
 
-Every line: `ISO timestamp` + `level (DEBUG/INFO/WARN/ERROR)` + `message`.
+Every line is logfmt-flavored: `time=<ISO timestamp> level=<debug|info|warn|error> <message>`; the message keeps its `[Module]` prefix.
 
 ## Rotation
 
@@ -41,8 +39,9 @@ When the log file exceeds the cap:
 
 | Config key | Default | Env var | Purpose |
 |---|---|---|---|
-| `logging.maxFileSize` | 10 MB | `HALO_LOG_MAX_SIZE` | Rotation threshold |
-| `logging.maxFiles` | 5 | `HALO_LOG_MAX_FILES` | Retained rotated files |
+| `logging.max_file_size` (`config.yaml`) | 10 MB | `HALO_LOG_MAX_SIZE` | Rotation threshold |
+| `logging.max_files` (`config.yaml`) | 5 | `HALO_LOG_MAX_FILES` | Retained rotated files |
+| `general.logging.level` (`settings.yaml`) | `warn` | `HALO_LOG_LEVEL` | Minimum level written: debug \| info \| warn \| error |
 
 Defined in `packages/server/src/config.ts`.
 
@@ -54,18 +53,8 @@ initLogger()
 ```
 
 Called once from `packages/server/src/index.ts` at startup. Steps:
-1. Create the log directory
-2. Replace console methods with the interceptor
-3. Each interceptor calls the original method and appends to the log file
-
-## Workspace switching
-
-```typescript
-import { setLogDir } from './logger.js'
-setLogDir('/path/to/project')
-```
-
-Called from `packages/server/src/ws/handler.ts` when the client subscribes to a workspace.
+1. Replace console methods with the interceptor
+2. Each interceptor calls the original method and appends to the log file (the directory is created on first write)
 
 ## Error handling
 
@@ -78,8 +67,5 @@ Log writes use synchronous `fs.appendFileSync` and fail silently — logging mus
 tail -f /tmp/server.log
 
 # file logs (always written, regardless of nohup redirection)
-tail -f ~/.halo/logs/server.log
-
-# project-specific logs
-tail -f /path/to/your-project/.halo/logs/server.log
+tail -f ~/.halo/global/logs/server.log
 ```

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 |
 
@@ -174,15 +175,15 @@ This is a known, unfixed gap (not a bug in a specific route): don't hand out `wo
 
 Sensitive directories and files are hidden from workspace/readonly sessions via bwrap overlays / Seatbelt deny rules (and the same lists gate `assertPathAllowed` for in-process file tools). Under bwrap a hidden file reads as empty and a hidden dir as an empty directory; under Seatbelt both are denied outright. Paths that don't exist on the filesystem are silently skipped. Two categories coexist:
 
-**Global lists (configurable)** — credentials and cross-workspace state, configured in `settings.yaml` under `general.sandbox`:
+**Global lists (built-in + configurable extras)** — credentials and cross-workspace state. The built-in lists are code constants in `sandbox.ts` (`DEFAULT_HIDDEN_DIRS` / `DEFAULT_HIDDEN_FILES`, the single source) and are always included in the effective lists (which apply to workspace/readonly sessions only — Full sessions skip the sandbox entirely); `settings.yaml` `general.sandbox.hidden_dirs` / `hidden_files` hold extra entries that are **appended** (deduped) — they never replace the built-ins, so a built-in entry cannot be removed from the list in settings. `config.ts` `resolveSandboxPaths()` builds the effective lists for both the server and the CLI:
 
-| Setting | Default | Method |
+| Setting | Built-in (always included) | Method |
 |---|---|---|
 | `hidden_dirs` | `~/.halo/secrets,~/.aws,~/.ssh,~/.gnupg,~/.docker,~/.config/gh,~/.halo/global/internal-sessions,~/.halo/global/logs` | bwrap `--tmpfs` overlay (empty directory); Seatbelt `subpath` deny |
 | `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.