@turmind/halo 1.5.6 → 1.5.8

package/bundled-docs/dev/deploy.md

@@ -224,7 +224,7 @@ This installs the `halo` binary on `$PATH`. Subcommands available:
 ### Upgrade flow
 
 1. `halo upgrade` — bumps the on-disk npm package
-2. `halo server restart` — server's startup check sees `~/.halo/global/.template-version` is behind the new bundled `TEMPLATE_VERSION`, runs `ensureHaloHome` automatically, then starts. Refreshes `docs/`, built-in agents, built-in skills, system prompts, and the model registry. User-owned files (USER.md, custom agents/skills, INSTRUCTIONS.md overrides) are left alone. See `init.ts` for the per-category overwrite policy.
+2. `halo server restart` — server's startup check sees `~/.halo/global/.template-version` is behind the new bundled `TEMPLATE_VERSION`, runs `ensureHaloHome` automatically, then starts (`halo cli` / `halo tui` run the same check on start, so a CLI-only install refreshes without a server). Refreshes `docs/`, built-in agents, built-in skills, system prompts, and the model registry. User-owned files (USER.md, custom agents/skills, INSTRUCTIONS.md overrides) are left alone. See `init.ts` for the per-category overwrite policy.
 
 ### Public release command reference
 

package/bundled-docs/dev/desktop-packaging.md

@@ -374,9 +374,10 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
 
 - **Changing anything under `templates/` requires bumping `TEMPLATE_VERSION`
   (`packages/server/src/init.ts`) — otherwise the change never reaches existing
-  installs.** Server startup only re-runs `ensureHaloHome` (the template
-  reseed) when the on-disk `~/.halo/global/.template-version` is *strictly less
-  than* the compiled `TEMPLATE_VERSION` (`index.ts` startup block). Equal → the
+  installs.** Server startup (and `halo cli` / `halo tui` start) only re-runs
+  `ensureHaloHome` (the template reseed) when the on-disk
+  `~/.halo/global/.template-version` is *strictly less than* the compiled
+  `TEMPLATE_VERSION` (`init.ts` `refreshTemplatesIfOutdated`). Equal → the
   whole reseed is skipped, so a template edit with no version bump is invisible
   to every machine that already has the prior version stamped. This bit the
   `team`-delegation rewrite: `default/AGENT.md` gained the "team whitelist"

package/bundled-docs/dev/env.md

@@ -82,7 +82,7 @@ Three config file types, precedence **env vars > config.yaml / settings.yaml > c
 | `~/.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).
+`init.ts` seeds these on first run with a per-category policy. Refresh trigger: `halo setup` always re-runs the seed, and the startup check re-runs it automatically when `~/.halo/global/.template-version` is behind the bundled `TEMPLATE_VERSION` — on server start and at the start of `halo cli` / `halo tui` (`init.ts` `refreshTemplatesIfOutdated`, called from `index.ts` and the CLI's `harness.ts` `initRuntime`; a never-seeded home is left to `halo setup`).
 
 - **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.

package/bundled-docs/guide/agents.md

@@ -42,7 +42,7 @@ Click an agent in the sidebar to open the right-hand editor. Two views:
 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`
+- `provider` — dropdown populated from `~/.halo/global/models/*.yaml` plus hub-installed `~/.halo/global/models.d/*.yaml` (`/extension models`; updates the list live)
 - `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
@@ -227,6 +227,6 @@ With `export NANO_BANANA_KEY=sk-xxx` in the env, the agent's system prompt gets
 
 ## Model registry — adding a new provider
 
-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.
+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/` (refreshed between releases by `/extension models`, which installs newer copies into `~/.halo/global/models.d/`) whose `runtime:` field names the implementation in [packages/server/src/agents/model-runtime.ts](../../../packages/server/src/agents/model-runtime.ts) (e.g. `anthropic-messages`, `openai-chat`, `bedrock-invoke`). 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.
 
-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 "..."`.
+A provider that speaks an existing wire protocol needs only a yaml manifest with that `runtime:`; a new protocol also needs a runtime class. The step-by-step is in [dev/add-model-provider.md](../dev/add-model-provider.md). A provider yaml without `runtime:` (or with a name Halo doesn't know) makes session spawn fail with an error naming the yaml; for a bundled provider that means the seed is stale — run `halo setup` or restart the Halo server.

package/bundled-docs/guide/cli.md

@@ -144,7 +144,7 @@ Multi-turn conversation. Supports all standard Halo slash commands:
 | `/workspace setup` / `/workspace tidy` / `/workspace share` | Set up / tidy the `.halo/` knowledge files, or export a shareable bundle (workspace skill) |
 | `/cron <verb>` | Manage scheduled agent runs: `create` / `list` / `update` / `enable` / `disable` / `delete` |
 | `/acp <verb>` | Ask other agents over ACP (`kiro <q>` / `claude <q>`) and manage `ask-*` bindings (`add` / `list` / `remove`) |
-| `/extension <verb>` | Canvas preview extensions: `install` / `list` / `remove` (full access only) |
+| `/extension <verb>` | Canvas preview extensions: `install` / `list` / `remove`; `models` updates the model provider list from the hub (full access only) |
 | `/evo [hint]` | Queue a self-evolution run on this session (full access only) |
 | `/quit` | Exit |
 
@@ -211,6 +211,15 @@ Attach files or images to your message with `@file` and `@image`, or pull a dire
 - **Images**: skipped if larger than 5MB
 - If the current model does not support vision, a warning is shown and images are ignored
 
+## Model provider configs (`halo models`)
+
+```bash
+halo models install <dir> [--yes]   # install <dir>/*.yaml into ~/.halo/global/models.d/
+halo models list                    # id · copy in effect (bundled | hub) · revision · runtime
+```
+
+Normally run for you by `/extension models`, which downloads the hub's newest `models-v*` release (https GitHub / Gitea / Forgejo / GitLab only) and passes the unpacked directory to `halo models install`. Per provider id the copy with the higher `revision` is in effect (tie → the `models.d` copy); an older one is skipped, an identical one reported up to date. Refused per provider: a `runtime:` this halo doesn't know (needs a newer halo), no `revision`, a `secrets[].default` that isn't empty or `<<ENV_NAME>>`. If any provider is new or changes `defaultEndpoint` / `endpointPresets`, the changes are listed, **nothing is written**, and the exit code is `3` — re-run with `--yes` to apply. Writes are atomic (tmp + rename); a running server reloads its registry from `models.d/` without a restart and pushes the change to open admin pages. Existing agents keep the model / endpoint in their own `agent.yaml`. Exit codes: `0` ok (refusals listed in the summary line), `1` error, `3` needs `--yes`. To undo, delete the file from `~/.halo/global/models.d/`.
+
 ## Server Mode (background daemon)
 
 `halo server start|stop|restart|status|logs` manages a local server from the
@@ -251,7 +260,8 @@ Session prefix: `cli_`. Sessions are persisted to `<workspace>/.halo/sessions/`
 ### Initialization
 
 `tui` / `cli` / `agents` / `sessions` refuse to run ("~/.halo/global/ not initialized. Run halo setup first.") until `halo setup` has seeded `~/.halo/global/`. Then the CLI replicates the server's init sequence (`initRuntime()` in `harness.ts`):
-1. `initLogger()` — redirect console to stderr + file logger
-2. `initBwrapCheck()` — probe sandbox availability
-3. `setSandboxHiddenPaths()` — configure sandbox paths
-4. `new SessionManager(workspace)` — create agent session manager (the workspace's `.halo/` is seeded via `ensureWorkspaceHalo`)
+1. `refreshTemplatesIfOutdated()` — the server's template startup check: when `~/.halo/global/.template-version` is behind the bundled `TEMPLATE_VERSION` (typically right after `halo upgrade`), re-seed `~/.halo/global/` before anything reads the models registry; logs `[CLI] Templates outdated (vX → vY), refreshing ~/.halo/global/` to stderr. Runs once per upgrade — afterwards the stamp matches and it's a single file read
+2. `initLogger()` — redirect console to stderr + file logger
+3. `initBwrapCheck()` — probe sandbox availability
+4. `setSandboxHiddenPaths()` — configure sandbox paths
+5. `new SessionManager(workspace)` — create agent session manager (the workspace's `.halo/` is seeded via `ensureWorkspaceHalo`)

package/bundled-docs/guide/getting-started.md

@@ -77,7 +77,7 @@ After `halo setup`:
     └── channels/channels.db  ← per-channel account state
 ```
 
-**When does "refreshed on upgrade" actually run?** `halo setup` always re-runs the seed; the server's startup check also re-runs it automatically when `~/.halo/global/.template-version` is behind the bundled `TEMPLATE_VERSION`. So the routine flow `halo upgrade && halo server restart` is enough — no need to remember `halo setup`.
+**When does "refreshed on upgrade" actually run?** `halo setup` always re-runs the seed; the server's startup check — and the same check at the start of `halo cli` / `halo tui` — also re-runs it automatically when `~/.halo/global/.template-version` is behind the bundled `TEMPLATE_VERSION`. So the routine flow `halo upgrade && halo server restart` is enough — no need to remember `halo setup` — and a CLI-only user just runs `halo cli` / `halo tui` after `halo upgrade`.
 
 **Server-refreshed**: `INSTRUCTIONS.md`, `prompts/`, `models/`, `docs/`, the built-in agent ids (`default`, `executor`, `deep-executor`, `goal`, `__evo_agent__`, `__score__`, `__apply_agent__`), and the built-in skill ids (`agent`, `skill`, `workspace`, `cron`, `acp`, `send-file`, `self`, `aws-knowledge`, `web-search`, `halo`, `extension`). To customize one, copy it into the workspace scope (`<project>/.halo/...`) — workspace replaces global at runtime.
 

package/bundled-docs/requirements/chat.md

@@ -32,7 +32,7 @@ A Bug-icon **Debug** button in the composer's left control cluster (next to the
 ### User-message actions (Expand / Copy / Delete)
 Actions on user-role turns: the blue sticky user bubble, plus the sub-agent-report (green) and compact-summary (purple) callouts — all three share the same Copy/Delete pair. The icons are **always visible** (not hover-only). On the callouts, Copy copies the body only (the `(from: session X)` / `[Conversation Summary…]` marker line is stripped); a deleted callout greys out and gains a "deleted" badge like the bubble does:
 - **Expand / Collapse** — from a **header row**, not an icon in the action group (the top-right expand arrow was removed in 1.5.3-alpha):
-  - **User bubble**: the header row holds a chevron, the send time and, while collapsed, a preview (the first 20 characters, then `…`). A long message is **collapsed by default**: the body height is 0, so only the header row shows. Clicking anywhere on the row toggles it.
+  - **User bubble**: every message is a single header row — a marker, the send time and a one-line preview. A message that fits on that row (no line breaks) shows a muted `·` marker and has nothing to expand. One that has line breaks or overflows the row shows a chevron, is **collapsed by default**, and its preview is cut by width with `…` (a multi-line message previews its first line plus `…`); clicking anywhere on the row shows the full body below. The `·` and the chevron are the same width, so the times line up. Whether a message overflows is re-measured when the panel width changes.
   - **Report callout**: its "Report from sub-session" title row toggles the same way.
   - The chevron only appears when the body is actually clamped; a short body has no chevron and its row does nothing on click.
   - An expanded body is capped at 40vh and scrolls inside the bubble, because the bubbles are sticky.
@@ -97,7 +97,7 @@ When `contextEnabled` is on (default), user messages are auto-prepended with:
 - Clipboard paste
 - File-picker button
 
-Images ride along as base64; multimodal supported. Pasted images are also persisted to `<workspace>/.halo/assets/web/inbound/web/<date>/` so a `[图片已保存: /abs/path]` marker survives page reload and renders as a click-to-preview chip (shared with the WeChat channel's inbound media flow).
+Images ride along as base64; multimodal supported. Before sending, every attachment is downscaled (long edge ≤ 1568) and re-encoded as JPEG; an SVG is rasterized the same way (long edge 1024, on white), since vision input only takes jpeg / png / gif / webp. An image the browser can't decode (e.g. HEIC / TIFF in Chrome) and that isn't one of those four is refused when attached, with an inline notice naming the file — it is never sent only to be dropped server-side. Pasted images are also persisted to `<workspace>/.halo/assets/web/inbound/web/<date>/` so a `[图片已保存: /abs/path]` marker survives page reload and renders as a click-to-preview chip (shared with the WeChat channel's inbound media flow).
 
 ### Inline media chips
 Any message containing `[图片/视频/语音/文件 已保存: /path]` markers (WeChat + web) or a leading `MEDIA: /path` line (agent-emitted, e.g. from `wechat-send`) renders a compact chip with filename + icon. Clicking opens a full-size preview modal (image/video/audio inline, file → download link). The modal has a Download button (top-right, next to close) for image/video/audio; the media URL carries a per-open cache-buster (`&t=<timestamp>`) so overwritten files (same path, new bytes) always show current content. Paths inside the active workspace or under the OS temp dir (`/tmp/`) are previewable; everything else degrades to a non-clickable chip.

package/bundled-docs/requirements/settings.md

@@ -62,7 +62,8 @@ Schema lives **inside the package**, alongside its other files:
 ### Provider secrets — `models/<provider-id>.yaml`
 
 ```yaml
-id: aws-bedrock-claude-invoke
+id: aws-bedrock-claude-invoke       # provider identity — also the settings namespace below
+runtime: bedrock-invoke             # implementation class; not part of the settings schema
 displayName: AWS Bedrock Claude (Invoke API)
 defaultEndpoint: https://bedrock-runtime.us-west-2.amazonaws.com