@turmind/halo 0.2.0 → 0.2.1-bc7cf2b

package/bundled-docs/dev/acp-adapter.md

@@ -81,9 +81,35 @@ To remove a binding: `/acp remove` (deletes the skill directory and points out t
 | `--token`        | yes      | Web-channel token from admin UI. `full` access required for multi-workspace use.         |
 | `--workspace`    | yes      | Absolute server-side path for the workspace this adapter drives.                         |
 | `--agent-id`     | no       | Halo agent profile to use when ACP `session/new` creates a new halo session. Default: `default`. |
+| `--header`       | no       | Extra HTTP header on every upstream request, `"Name: value"` (like `curl -H`). Repeatable. For auth that sits **in front of** the halo server — see "Upstream auth" below. |
 
 One adapter process binds to one workspace. To drive multiple workspaces concurrently from the same token, run multiple adapter processes — see "Multi-workspace" below.
 
+## Upstream auth (`--header`)
+
+`--token` authenticates the adapter to *halo itself* (it becomes the `x-token` header on every web-channel call). It does **not** cover a proxy sitting in front of the server — an SSO/session-cookie gateway, Cloudflare Access, ALB OIDC, nginx basic-auth. Those reject the request before halo ever sees the token.
+
+`--header` is the generic escape hatch: it forwards arbitrary headers on every request the adapter makes (`/api/web/chat`, `/history`, `/stop`), exactly like `curl -H`. The adapter deliberately knows nothing about any specific gateway — you supply whatever that layer wants:
+
+```sh
+# session-cookie gateway
+halo acp --host h --port 9527 --scheme https --token <t> --workspace /ws \
+  --header "Cookie: <the gateway's session cookie, verbatim>"
+
+# Cloudflare Access (two headers — --header is repeatable)
+halo acp … --header "CF-Access-Client-Id: <id>" --header "CF-Access-Client-Secret: <secret>"
+
+# HTTP basic auth
+halo acp … --header "Authorization: Basic <base64 user:pass>"
+```
+
+Notes:
+
+- **Repeatable** — pass `--header` as many times as the gateway needs.
+- **Colon-safe** — the value is split on the *first* `:` only, so header values that themselves contain colons (`Cookie: a=b:c`) survive intact.
+- **`x-token` always wins** — `--header` cannot override the adapter's own `x-token` / `content-type`; it only adds headers for the layer in front of halo.
+- The generated `ask-<label>` bindings (halo→halo, via `ask.py`) do **not** yet expose `--header`; upstream auth through a binding isn't wired. `halo acp` direct is the path when a gateway is in play.
+
 ## ACP method coverage
 
 | Method              | Implemented? | Notes                                                                  |

package/bundled-docs/dev/api.md

@@ -235,10 +235,12 @@ runtime so the frontend can render rooms (workspaces) + characters (sessions).
 
 | Method | Path | Purpose |
 |---|---|---|
-| GET | `/api/show/state` | Full-access token → every known workspace; otherwise the account's own. Returns `{ serverTime, uptime, accessLevel, skills[], workspaces[] }` |
-| GET | `/api/show/session?ws=&id=` | Inspector-panel detail for a single session. Trimmed message log (last 40, content/tool I/O capped) plus `contextTokens` / `outputTokens` / `maxContextTokens` / `isRunning`. Non-full tokens may only read their own workspace. |
+| GET | `/api/show/state` | `full` or `observer` token → every known workspace; otherwise the account's own. Returns `{ serverTime, uptime, accessLevel, skills[], workspaces[] }` |
+| GET | `/api/show/session?ws=&id=` | Inspector-panel detail for a single session. Trimmed message log (last 40, content/tool I/O capped) plus `contextTokens` / `outputTokens` / `maxContextTokens` / `isRunning`. Non-`full`/`observer` tokens may only read their own workspace. |
 
-Each `workspace` = `{ path, key, label, counts{running,idle,stopped}, totalSessions, skills[], sessions[] }`; each `session` = `{ id, parentId, depth, agentName, description, status, lastTool, activeSkill, contextTokens, outputTokens, updatedAt }`. `lastTool` / `activeSkill` come from the live in-memory UI log (empty when the session isn't loaded). Sessions per room are capped (`totalSessions` reports the true total). Frontend: `halo-city/` at repo root.
+Each `workspace` = `{ path, key, label, counts{running,idle,stopped}, totalSessions, skills[], sessions[] }`; each `session` = `{ id, parentId, depth, agentName, description, status, lastTool, activeSkill, contextTokens, outputTokens, messageCount, updatedAt }`. `lastTool` / `activeSkill` come from the live in-memory UI log (empty when the session isn't loaded). Sessions per room are capped (`totalSessions` reports the true total). Frontend: `halo-city/` at repo root.
+
+**Read-only by construction — degraded snapshots.** Both endpoints resolve a workspace's runtime via `registry.peek()` — in-memory lookup only, **never** `getOrCreate`: constructing a SessionManager has write side effects (boot orphan-reconciliation batch-stops live sub-session rows; `.halo/` scaffolding), so a pure visualization poll must not trigger it. When no live SessionManager exists in this process, the handler opens that workspace's `.halo/halo.db` **read-only** (cached connection; missing db/tables silently degrade to an empty room) and projects rows / the persisted session file into the same wire shape. Sessions not in memory therefore return a **persisted snapshot**: `status` / token counts / `messageCount` may lag behind the last persistence point, and the live-only signals (`lastTool` / `activeSkill`) are empty by definition. The degraded `/api/show/session` path reports `maxContextTokens: 0` (the real cap needs a live agent config; the city inspector hides the meter when the cap is unknown).
 
 ## Agent Configs
 
@@ -312,7 +314,7 @@ File: `packages/server/src/routes/evolution.ts`. Surfaces the global `evolution_
 | Method | Path | Purpose |
 |---|---|---|
 | GET | `/api/evolution/runs` | List all evolution runs across workspaces. Carries the latest `apply_id`/`apply_status` per run. (Score isn't surfaced in the list — it's read from `score.json` on the detail fetch only.) |
-| GET | `/api/evolution/runs/:id` | Detail: db row + `patch.md` + `score.json` + `system-suggestions.md` (optional, evo writes when it has platform-level feedback) + `.skip.md` (when `status='skipped'`) + a snapshot summary (first user message + first assistant reply + message count). |
+| GET | `/api/evolution/runs/:id` | Detail: db row + `patch.md` + `score.json` + `.skip.md` (when `status='skipped'`) + wrapper/sub-cli logs + a snapshot summary (first user message + first assistant reply + message count). Row carries `failureReason` (and `applyFailureReason` from the latest apply) — apply-side values include `phase A': apply cli exited <code>`, `phase A': apply agent aborted: <first line of ABORT.md>`, and `phase A': apply agent didn't produce apply.log`. |
 | POST | `/api/evolution/runs/:id/approve` `{reviewerHint?}` | Move run from `awaiting_review` → `approved`, insert a pending `evolution_applies` row that the ticker will pick up. |
 | POST | `/api/evolution/runs/:id/reject` | Move run from `awaiting_review` → `rejected`. |
 | POST | `/api/evolution/runs/:id/retry` `{hint}` | Reset a finished run back to `pending` with the supplied (required) hint so the wrapper picks it up again. Rejected with 409 when the run is already `running` / `pending`. |

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

@@ -56,6 +56,10 @@ done   # all five must read the same x.y.z, and match the tag you're about to cu
 pnpm --filter @turmind/halo-core build
 pnpm --filter @turmind/halo-server build
 pnpm --filter @turmind/halo-admin build
+# NOTE: acp-adapter is NOT listed here on purpose — build-bundle.mjs now
+# builds every workspace:* dep (core / server / acp-adapter) itself before
+# esbuild inlines them, so its dist can't go stale. This block only covers
+# artifacts the stage script consumes directly (server dist, admin-out).
 
 # 2. stage + package (arm64)
 cd packages/desktop

package/bundled-docs/dev/env.md

@@ -87,7 +87,7 @@ Source: `packages/server/src/config.ts`
 | Variable | Default | Config path | Description |
 |---|---|---|---|
 | `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. The hash is set by `halo setup` for interactive installs. |
+| `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_MAX_CONTEXT_TOKENS` | `200000` | — | Model max context |
@@ -117,6 +117,8 @@ settings.yaml only (no env override):
 - `kimi.secrets.api_key` — Kimi (Moonshot AI)
 - `deepseek.secrets.api_key` — DeepSeek
 
+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
 
@@ -136,7 +138,7 @@ settings.yaml-driven `general.limits.*` (no env override):
 Two ways to authenticate:
 
 1. **Interactive** — run `halo setup`, pick "Set / change password". The value is scrypt-hashed and written to `~/.halo/secrets/config.yaml server.password`. Best for personal installs.
-2. **Env** — export `HALO_PASSWORD=...` before launching the server. The plaintext value is compared directly (no hashing) and takes precedence over any stored hash. Best for Docker / systemd / CI where a secrets manager already protects the env.
+2. **Env** — export `HALO_PASSWORD=...` before launching the server. The plaintext value is compared directly (no hashing) and takes precedence over any stored hash. A stored hash isn't required at all — env plaintext alone satisfies the startup gate, so env-only deployments are legal. Best for Docker / systemd / CI where a secrets manager already protects the env.
 
 ## Verify
 

package/bundled-docs/dev/previews.md

@@ -27,6 +27,9 @@ previews/
     ├── docx.tsx / docx-view.tsx
     ├── xlsx.tsx / xlsx-view.tsx
     ├── pptx.tsx / pptx-view.tsx
+    ├── pptx-notes.ts         pptx zip helpers: speaker-notes extraction (jszip +
+    │                         DOMParser, play order via sldIdLst) + Content_Types
+    │                         repair for decks with dangling Override parts
     └── media.tsx / media-view.tsx
 ```
 

package/bundled-docs/dev/tools.md

@@ -181,6 +181,8 @@ Start a sub-agent session asynchronously. When the sub-agent finishes, its **wra
 - 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)
 
+UI note: the `agent_start` event this emits carries both a 200-char `text` preview (parent-side rendering) and the full un-truncated brief as `fullText`, which seeds the sub-session log's opening user message — so viewing the child session shows the complete task brief (`system_prompt_context` + `message`), not a cut-off preview. See [session.md → Event routing](../design/session.md#event-routing).
+
 ### session_list
 
 List direct child sessions of the current session and their status.
@@ -293,7 +295,7 @@ Returns: full SKILL.md content (body + resource files list). For progressive dis
 |---|---|---|---|
 | `content` | string | yes | The complete draft answer. Required and must be non-empty |
 
-The tool **description is deliberately plain** — "Submit a draft answer for self-review; returns a checklist that critiques the draft." It does NOT say *when* to call it (no "call this for complex questions / when unsure"). An earlier version that did embed such self-referential guidance made some models (notably GPT-5.x) thrash. Steering toward *using* draft belongs in the agent's `system_prompt` (e.g. the bundled `default` agents say "hold your answers to a high standard… don't reply off the cuff"), not in the tool description. Empty `content` is rejected with an error **without consuming a draft round**.
+The tool **description is deliberately plain** — "Submit a draft answer for self-review; returns a checklist that critiques the draft." It does NOT say *when* to call it (no "call this for complex questions / when unsure"). An earlier version that did embed such self-referential guidance made some models (notably GPT-5.x) thrash. Steering toward *using* draft belongs in the agent's prompt files (the bundled `default` agent's AGENT.md says "hold your answers to a high standard… don't reply off the cuff" — it lives in AGENT.md because the yaml `system_prompt` is only a fallback when the MD layer is empty), not in the tool description. Empty `content` is rejected with an error **without consuming a draft round**.
 
 **Why it exists:** the agent loop only makes another model call when the model emits a `tool_use` block. A plain-text answer (`end_turn`) is single-pass — `thinking` runs *before* the answer in the same call, so the model never gets to look at its *finished* answer and revise it. `draft` closes that gap without touching the loop: the model writes its answer into `content` (materialised into the conversation as a `tool_use` block — uncapped, never echoed back), and the tool_result hands back an adversarial review checklist (framed as a hostile reviewer: list every factual claim and tag its source, verify the unverified ones with tools *now*, check directness/tone, flag gaps). The next model call then critiques that now-concrete draft and either revises (calls `draft` again) or writes the final answer.
 

package/bundled-docs/guide/cli.md

@@ -46,12 +46,14 @@ End users then install with `npm install -g @turmind/halo`.
 Run a one-shot prompt and exit:
 
 ```bash
-halo "review this PR"
-halo -w /path/to/workspace "analyze code"
-echo "review the changes" | halo
-cat prompt.txt | halo -w /path/to/review-ws
+halo cli "review this PR"
+halo cli -w /path/to/workspace "analyze code"
+echo "review the changes" | halo cli
+cat prompt.txt | halo cli -w /path/to/review-ws
 ```
 
+To list agents or sessions without running a prompt, use the dedicated subcommands `halo agents` / `halo sessions` (same `-w` flag).
+
 ### Options
 
 | Flag | Short | Default | Description |
@@ -59,11 +61,10 @@ cat prompt.txt | halo -w /path/to/review-ws
 | `--workspace` | `-w` | cwd | Workspace path |
 | `--agent` | `-a` | `default` | Agent ID |
 | `--session` | `-s` | auto | Resume session by ID |
+| `--new` | `-n` | off | Always start a new session |
 | `--format` | `-f` | `text` | Output format: `text` or `json` |
 | `--verbose` | `-v` | off | Show thinking, tool calls, usage on stderr |
 | `--access` | | `full` | Access level: `full`, `workspace`, `readonly` |
-| `--agents` | | | List available agents and exit |
-| `--sessions` | | | List recent sessions and exit |
 | `--lang` | | `en` | Language: `en` or `zh` |
 
 ### Output
@@ -91,21 +92,22 @@ cat prompt.txt | halo -w /path/to/review-ws
 
 ```bash
 # Code review in CI
-halo -w /path/to/review-ws "review the diff" --format json | jq '.text'
+halo cli -w /path/to/review-ws "review the diff" --format json | jq '.text'
 
 # Pipe content in
-git diff HEAD~1 | halo -w /path/to/review-ws "review this diff"
+git diff HEAD~1 | halo cli -w /path/to/review-ws "review this diff"
 
 # Exit code: 0 = success, 1 = error, 130 = SIGINT
-halo "check for issues" && echo "OK" || echo "FAILED"
+halo cli "check for issues" && echo "OK" || echo "FAILED"
 ```
 
 ## TUI Mode (interactive)
 
 ```bash
-halo -i
-halo -i -w /path/to/workspace
-halo -i -s sid_abc123   # resume session
+halo tui
+halo tui -w /path/to/workspace
+halo tui -s sid_abc123   # resume session
+halo tui -n              # always start a new session
 ```
 
 Multi-turn conversation. Supports all standard Halo slash commands:
@@ -130,6 +132,16 @@ Multi-turn conversation. Supports all standard Halo slash commands:
 | `/evo [hint]` | Queue a self-evolution run on this session (full access only) |
 | `/quit` | Exit |
 
+TUI-only client commands (handled locally, also visible in the completion popup):
+
+| Command | Description |
+|---|---|
+| `/clear` | Start a new session (alias for `/session new`) |
+| `/retry` | Resend the last user message |
+| `/verbose` | Toggle verbose tool output (args + truncated results) at runtime — same as launching with `-v`; the status bar shows a `v` badge while on |
+| `/log` | Browse the session tree and view a session log (same as `Ctrl+O`) |
+| `/exit` | Alias for `/quit` |
+
 Bare `/<obj>` (or `/<obj> help`) lists the verbs you may run. Verbs gated above your access level are hidden.
 
 ### Keybindings
@@ -139,9 +151,15 @@ Bare `/<obj>` (or `/<obj> help`) lists the verbs you may run. Verbs gated above
 | `Esc` (while running) | Interrupt the current turn immediately — aborts a command mid-execution, then any messages typed while it was running are folded into one follow-up turn. Same as `/session interrupt`. |
 | `Ctrl+C` | Graceful exit; press twice to force |
 | `Ctrl+O` | Toggle the sub-agent navigator — lists every sub-agent spawned this session, each showing its agent name, task title (same as the session list), and status (`●` running green / `○` idle grey / `✕` stopped red, plus a `▢ archived` marker when the session is archived); `↑↓` to move, `Enter` to view that sub-agent's log, `Esc`/`q` to close. (Was `Shift+Tab`, but Windows terminals consume that as backtab.) The log viewer auto-refreshes while the viewed session is still running (a `● live` hint shows in the header) and follows the bottom as new output lands — unless you've scrolled up to read, in which case it stays put (`G` jumps back to the bottom and resumes following). |
-| `↑` / `↓` | Walk input history (when no popup is open) |
+| `↑` / `↓` | Walk input history (when no popup is open). History persists across restarts in `~/.halo/global/tui-history.json` (last 100 entries, shared across workspaces) |
+| `←` / `→`, `Home` / `End` | Move the cursor within the input; text is inserted/deleted at the cursor (CJK and emoji safe) |
+| `Ctrl+A` / `Ctrl+E` | Jump to start / end of input |
+| `Ctrl+W` / `Alt+Backspace` | Delete the word before the cursor |
+| `Ctrl+U` / `Ctrl+K` | Delete to start / to end of input |
+
+On resume (`-s <id>`, or the default latest session), the TUI replays the session's prior conversation on screen so you see where you left off. `shell_exec` output is shown inline by default (other tools' output needs `-v`). Tool lines show a short argument summary and duration, e.g. `⚙ file_read hello.txt 4ms`.
 
-On resume (`-s <id>`, or the default latest session), the TUI replays the session's prior conversation on screen so you see where you left off. `shell_exec` output is shown inline by default (other tools' output needs `-v`).
+**Multi-line paste**: pasting text with newlines (or >800 chars) collapses into a compact placeholder like `[#1 pasted 3 lines]` in the input; you can keep typing around it, and the original text is expanded back in full on submit. Pasted content is inserted at the cursor position.
 
 ## File, Image, and Scope References
 
@@ -174,10 +192,16 @@ Attach files or images to your message with `@file` and `@image`, or pull a dire
 ```
 packages/cli/
   src/
-    index.ts        — Entry: arg parsing, mode dispatch, SIGINT handling
+    index.ts        — Entry: subcommand dispatch (tui/cli/agents/sessions/server/setup/acp), SIGINT handling
     harness.ts      — Shared agent harness wrapping SessionManager
     cli.ts          — Non-interactive: stdin/args → agent → stdout → exit
-    tui.ts          — Interactive: readline loop + event display + commands
+    tui.tsx         — Interactive entry: mounts the ink app
+    tui/
+      app.tsx       — Root component: event reducer, blocks, submit/command handling
+      line-editor.ts — Grapheme-aware pure line-editing functions (cursor, insert, delete)
+      history.ts    — Persistent input history (~/.halo/global/tui-history.json)
+      components/   — input-box, text-input, messages, streaming, status-bar,
+                      slash-suggest, path-suggest, log-navigator, log-viewer, banner
     format-usage.ts — Usage-line formatter (mirrors admin UsageLine badge order)
     resolve-refs.ts — @file / @image reference resolution with size limits
     render-md.ts    — Terminal markdown rendering (marked + marked-terminal)

package/bundled-docs/requirements/editor.md

@@ -42,7 +42,7 @@ Non-text files go through `FilePreview`, which looks up a **plugin** in the prev
 - **PDF** — browser-native iframe
 - **DOCX / DOC** — `mammoth` → HTML (parsed in a Web Worker so the UI stays responsive)
 - **XLSX / XLS / CSV** — `xlsx` (SheetJS) → table (parsed in a Web Worker; CSV decoded as UTF-8 with BOM strip)
-- **PPTX / PPT** — `pptx-preview` list mode. Fidelity is approximate — complex animations / SmartArt / embedded fonts may not render perfectly; users can download for the exact source. Flagged `heavy: true` so only the *active* pptx mounts (canvas-based rendering needs the main thread)
+- **PPTX / PPT** — `pptx-preview` list mode. Fidelity is approximate — complex animations / SmartArt / embedded fonts may not render perfectly; users can download for the exact source. Flagged `heavy: true` so only the *active* pptx mounts (canvas-based rendering needs the main thread). **Speaker-notes sidebar**: notes are extracted from the pptx zip in presentation (play) order and listed on the left; clicking a note scrolls to the corresponding slide (a domIndex mapping bridges play order to pptx-preview's part-filename render order, so reordered decks still land on the right slide). Collapsible with the state remembered in localStorage (`halo.pptxNotesHidden`); the sidebar doesn't appear at all when no slide has notes. Decks with dangling `[Content_Types].xml` overrides (e.g. some WPS exports) are repaired before rendering; if zero slides render anyway, a real error UI is shown instead of a silent black wrapper
 - **Images / video / audio** — native `<img>` / `<video>` / `<audio>`, supports HTTP Range for seek-without-full-download
 
 All previews share a **standard header** (`PreviewShell`) with filename, Download, Open-as-Text, and an `extraToolbar` slot for plugin-specific buttons (e.g. DOCX Print, XLSX sheet tabs).