@turmind/halo 1.6.4 → 1.6.6

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

@@ -104,8 +104,8 @@ HALO_STAGE_FULL=1 CI=true pnpm dist:win
 ```
 
 `HALO_STAGE_FULL=1` is **mandatory** here: a cross-stage must re-run the
-per-target native fixups (`@parcel/watcher-win32-x64` swap, `better-sqlite3`
-win prebuild), which the fast path skips. `wine` must be installed (electron-
+per-target native fixups (`@parcel/watcher-win32-x64` swap, `sherpa-onnx-win-x64`
+swap, `better-sqlite3` win prebuild), which the fast path skips. `wine` must be installed (electron-
 builder runs the nsis maker through it).
 
 Verified on the v0.1.9 build (Linux x86_64 host → win-x64):
@@ -114,7 +114,9 @@ Verified on the v0.1.9 build (Linux x86_64 host → win-x64):
   <ver>.exe` + `.exe.blockmap` + `win-unpacked/`. The "discard the stray
   arm64 dmg" gotcha below is mac-host-only.
 - **Native arch check** — every staged `.node` must be PE32+ x86-64, no ELF:
-  `find dist/win-unpacked -path '*watcher-*' -name '*.node' | xargs file` and
+  `find dist/win-unpacked -path '*watcher-*' -name '*.node' | xargs file`,
+  `find dist/win-unpacked -path '*sherpa-onnx-*' \( -name '*.node' -o -name '*.dll' \) | xargs file`
+  (only `sherpa-onnx-win-x64` dirs, one per runtime, no `linux-x64`) and
   `file dist/win-unpacked/resources/node.exe` (should read `PE32+ ... x86-64`).
 - **Two benign warnings**, both expected: `file source doesn't exist
   from=.../resources/node` (win bundles `node.exe`, not the Unix `node` — the
@@ -204,7 +206,9 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
 3. **Native fixup** — re-fetch `better-sqlite3` prebuilds via `prebuild-install
    --target=$NODE_VERSION_BARE` **unconditionally** (pins the ABI to the bundled
    node regardless of the build host's node — see the ABI gotcha below);
-   `@parcel/watcher`'s per-platform binary is swapped only when cross-staging.
+   `@parcel/watcher`'s per-platform binary is swapped only when cross-staging;
+   `sherpa-onnx`'s per-platform package is swapped to the target on every full
+   stage (server-runtime and cli-runtime — see the sherpa gotcha below).
 4. **Trim bloat** — drop non-target `node-pty` prebuilds, `better-sqlite3`'s
    C source, and the server's `src/`/`tests/`.
 5. **Copy `admin-out/`** — the Next.js static export.
@@ -212,9 +216,10 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
    nodejs.org, extract the `node` binary into `resources/`.
 7. **codesign (ad-hoc)** — `codesign --force --sign -` on the node binary for
    Gatekeeper. **We deliberately do NOT `strip`** — see gotcha below.
-8. **Native-addon smoke test** — load the staged better-sqlite3 with the
-   bundled node binary; abort the build if it can't `dlopen` (the ABI backstop,
-   runs on full and fast paths). See the ABI gotcha below.
+8. **Native-addon smoke test** — load the staged better-sqlite3 and
+   sherpa-onnx with the bundled node binary; abort the build if either can't
+   `dlopen` (runs on full and fast paths, skipped when cross-staging). See the
+   ABI gotcha below.
 
 ## Gotchas (learned the hard way)
 
@@ -456,8 +461,8 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
   `node_modules` differs from what's on disk, run with `HALO_STAGE_FULL=1`. The
   fast path only re-syncs compiled outputs and **reuses the existing
   `node_modules`**, so it never re-runs the per-target native fixups
-  (`@parcel/watcher` swap, `better-sqlite3` prebuild-install). Symptom of
-  forgetting: the win/x64 dmg still carries the host's arm64 binaries.
+  (`@parcel/watcher` / `sherpa-onnx` swaps, `better-sqlite3` prebuild-install).
+  Symptom of forgetting: the win/x64 dmg still carries the host's arm64 binaries.
 
 - **`@parcel/watcher` binary doesn't cross-stage via `npm install`.** Its
   per-platform binary package (`@parcel/watcher-win32-x64` etc.) declares
@@ -474,6 +479,29 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
   (`better-sqlite3` and `node-pty` don't hit this — they use `prebuild-install`
   and bundled multi-platform prebuilds respectively.)
 
+- **`sherpa-onnx-node` (local STT) has the same os/cpu trap — and its Windows
+  package is `win-x64`, not `win32-x64`.** The main package is pure JS; the
+  N-API addon + onnxruntime libs ship in `sherpa-onnx-<plat>-<arch>` optional
+  deps (`darwin-arm64`, `win-x64`, `linux-x64`, …), and npm / pnpm install only
+  the host's, so a Linux → win stage ends up with just `sherpa-onnx-linux-x64`.
+  `installSherpaBinary()` `npm pack`s the target's package at the exact
+  installed `sherpa-onnx-node` version, extracts it as a sibling of
+  `sherpa-onnx-node` (its loader requires `../sherpa-onnx-<plat>-<arch>/sherpa-onnx.node`)
+  in both server-runtime and cli-runtime, and deletes every other platform's
+  package. Runs on every full stage, cross or not. The server loads it
+  lazily (`await import`), so a broken binary never blocks boot — it only
+  surfaces as dead transcription; on a native stage `smokeTestNativeAddons()`
+  `require`s it with the bundled node to catch that early.
+  - **Windows: must be loaded by a process named `node.exe`.** The win
+    `sherpa-onnx.node` delay-loads `node.exe` for its N-API imports, so
+    `require`-ing it inside `Halo.exe` (Electron main / `ELECTRON_RUN_AS_NODE`)
+    fails. Fine today: the server and the `halo.cmd` CLI both run under the
+    bundled `resources\node.exe`. Keep it out of the Electron process.
+  - **macOS: minimum OS for the arm64 `.node` is 14.0 (`LC_BUILD_VERSION`
+    minos; the dylibs say 11.0), unverified on older macOS.** Whether 12/13 can
+    load it hasn't been tested on real hardware. Dylibs resolve through
+    `@loader_path` rpath, so no `DYLD_LIBRARY_PATH` is needed.
+
 - **`ENOTEMPTY` / `directory not empty` mid-stage or in electron-builder.** A
   prior stage's `resources/{cli,server}-runtime/node_modules` (or
   `dist/win-unpacked`) can fail to delete cleanly on macOS (open handles, deep

package/bundled-docs/dev/env.md

@@ -99,7 +99,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, exact origins). Empty = reflect any incoming Origin **without** `Allow-Credentials` (header-token callers like `x-token` work; cookie-carrying cross-origin requests don't). A non-empty list = only those origins get CORS, with `Allow-Credentials` (e.g. a frontend behind an SSO that must send its cookie). Read at startup — a change needs a restart. Prefer a same-origin reverse proxy over listing origins (see `halo-city/README.md`). |
+| `HALO_CORS_ORIGINS` | empty (reflect any origin) | `config.yaml server.cors_origins` | CORS allowlist (comma-separated, exact origins). Empty = reflect any incoming Origin **without** `Allow-Credentials` (header-token callers like `x-token` work; cookie-carrying cross-origin requests don't). A non-empty list = only those origins get CORS, with `Allow-Credentials` (e.g. a frontend behind an SSO that must send its cookie). Read at startup — a change needs a restart. Prefer a same-origin reverse proxy over listing origins (see the halo-city extension's [README](https://github.com/turmind/halo-hub/blob/main/extensions/halo-city/README.md#和-halo-同源)). |
 | `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) |

package/bundled-docs/requirements/chat.md

@@ -144,6 +144,14 @@ Constraints:
 - Desktop: screen share needs macOS **Screen Recording** permission; the camera prompts for **Camera** permission on first use, with an "Open Settings" path if previously denied. Browser: the page must be served over HTTPS or from localhost (`getDisplayMedia` / `getUserMedia` are absent elsewhere, so the buttons don't render); a denied camera shows a hint pointing at the address bar's site settings.
 - Binding is **in-memory only** and shared by all chat tabs — a page reload or restart requires re-selecting.
 
+### Extension buttons (chat bar)
+An installed extension whose manifest declares `chatbar` (e.g. the hub's voice input) adds one button to the input toolbar, right after the capture buttons; several sort by `chatbar.order`, then id. No such extension installed = toolbar unchanged; install / uninstall shows up without a reload.
+- **Button**: 32×32 like Attach; the extension's icon in the toolbar colour (a microphone when it has none); tooltip = its title (Chinese UI: `title_zh` → `title` → name; English: `title` → name). Primary-coloured while its panel is open.
+- **Panel**: opens above the whole input box, floating over the editor if the chat is docked low (up to 420 px wide, nearly full width on a phone; height from the manifest, default 160 px, shrunk to fit the space above the input — never so far that its title bar and × leave the screen) with a thin title bar and ×. It follows the input when the dock is resized or the floating chat is moved; switching chat tabs, or hiding the chat (terminal tab, collapsed dock), closes it. One panel at a time — another extension's button switches to it. Its own button again, ×, or Esc closes it (Esc in the text box closes the panel first, before the usual "Esc interrupts the turn"). Clicking elsewhere does **not** close it, so the user can keep dictating while editing the draft.
+- **Lifetime**: the extension runs only while its panel is open; closing stops it (the microphone with it). An extension that says it is still busy (e.g. the last sentence is being recognised) gets to finish first: on its button / × / Esc the panel stays (button still lit, text still arriving) until it is done — at most 35 s; closing it again closes it at once. Switching chat tabs, hiding the chat, or opening another extension's panel closes it at once. Uninstalling it while open closes the panel. An extension that doesn't answer within 10 s shows "did not respond" with Retry.
+- **Text into the draft**: the extension can insert text at the cursor (replacing a selection), exactly as given; the cursor lands after it and keyboard focus stays in the panel. It works while the agent is replying (it only edits the draft). The extension can **never send** — the user always presses Send.
+- Settings → Extensions labels such an extension "Chat bar". Design: [design/canvas-extensions.md → Chat-bar entries](../design/canvas-extensions.md#chat-bar-entries).
+
 ### The agent's face (`self.html`)
 A second channel beyond text: a visual space the agent drives in real time to express itself. Works everywhere (pure HTML/canvas, no Electron dependency) — desktop **and** plain browser.
 

package/bundled-docs/requirements/workspace.md

@@ -42,6 +42,10 @@ The Bottom Panel (Chat + Terminal) can also be **floated** into a draggable wind
 
 The Source Control entry is hidden in workspaces that are not git repos.
 
+**Extension entries.** An installed [canvas extension](../design/canvas-extensions.md#activity-bar-entries) whose manifest declares `activity` adds one button after Cron (several sort by the manifest's `order`, then id; the built-in tabs never move). It uses the extension's icon (tinted like the built-in icons; a puzzle piece when it has none) and its title / description in the hover drawer, in the admin's language. Clicking it shows the extension's page full-width in the main area with no sidebar, like Agents / Settings; leaving the tab closes the page (anything it was playing or refreshing stops). The last-used page is restored after a reload; if that extension has been removed, or doesn't run on this device, the workspace opens on Explorer instead. With no such extension installed, the bar is unchanged.
+
+**Short windows.** When the window is too short for every view button, the upper group (built-in views + extension entries) scrolls (no visible scrollbar); Settings and the quick-toggles entry stay pinned at the bottom.
+
 Below Settings sits the quick-toggles entry (network status, finish notification, and on desktop pin / keep-screen-awake) — see [explorer.md → Desktop windows](explorer.md#desktop-windows-multi-window).
 
 ### Hover drawer