@turmind/halo 0.1.9

package/bundled-docs/plans/todo.md

@@ -0,0 +1,32 @@
+# TODO
+
+## Architecture
+
+(done)
+
+## Deep session nesting
+
+(done) — detailed analysis in [issue-session-deep-nesting.md](issue-session-deep-nesting.md)
+
+## Other
+
+- [ ] `eventListeners` should support multiple listeners (Map<string, handler> → Map<string, handler[]>) so multiple frontends can subscribe to the same session tree simultaneously
+
+## Workspace settings.yaml copy in share-workspace
+
+share-workspace 当前完全排除 `settings.yaml`(stage.py:63 ALWAYS_EXCLUDED)。
+但 workspace 自己的 `settings.yaml`(如 `<ws>/.halo/settings.yaml`,跟
+`~/.halo/secrets/settings.yaml` 不同)其实包含项目特定的非 secret 偏好,
+应该带走。需要区分:
+
+- `~/.halo/secrets/settings.yaml` — 含密码 / API key,**永远不带**
+- `<workspace>/.halo/settings.yaml`(如果存在) — 项目级偏好,**应该带**
+
+实施时要看 workspace 是否真的支持 `<ws>/.halo/settings.yaml` 加载;如果
+不支持,这条 todo 是个 feature request 而非修复。
+
+## i18n: agent management "Internal" section
+
+`agent-management-main.tsx` 新加的 internal scope label 当前是硬编码英文
+"Internal"。其他 scope label 用了 i18n key (`t('common.global')` /
+`t('common.workspace')`)。下次集中补 i18n 时加 `t('common.internal')`。

package/bundled-docs/plans/weixin-channel.md

@@ -0,0 +1,255 @@
+# WeChat Channel Integration Plan
+
+**Status**: shipped. Channel implementation lives in [packages/server/src/channels/wechat/](../../../packages/server/src/channels/wechat/) and routes in [packages/server/src/routes/weixin.ts](../../../packages/server/src/routes/weixin.ts). Runtime behavior is documented in [design/wechat.md](../design/wechat.md). This file is kept as the design log.
+
+## Goals
+
+Let the user talk to Halo from WeChat on their phone, sharing the same workspace + session as the web client.
+On the road, exchange messages / see simple results on WeChat; at the desk, use web for the full conversation / code / files.
+
+## Architecture
+
+```
+                       ┌── ws/ (web channel)            ─┐
+Halo server (9527) ──┤                                 ├── SessionManager
+                       └── channels/weixin/ (new)        ─┘    (per workspace)
+                               ↕ HTTPS long-poll
+                           ilinkai.weixin.qq.com
+```
+
+Two channels are peers; both are SessionManager subscribers + callers.
+
+## Data model
+
+### Workspace ↔ Bot mapping
+
+One bot (= one `ilink_bot_id` from a QR scan) is bound to one workspace. A workspace can bind multiple bots (redundancy or use-case split), though 1:1 is recommended.
+
+### Session strategy
+
+- **One WeChat user → one long-lived session**
+- Session ID: `wx_<normalizedUserId>` (e.g. `a1b2c3@im.wechat` → `wx_a1b2c3-im-wechat`)
+- Session lives in the bot's bound workspace
+- Uses the `default` agent
+
+On the web side the workspace's session list shows this session (labelled `wx: <username or userId>`).
+
+### Storage
+
+WeChat bot accounts are **cross-workspace** (they record which workspace a bot binds to). Not in a workspace DB; separate file: `~/.halo/global/weixin.db` (new).
+
+Table `weixin_accounts`:
+
+| Field | Type | Notes |
+|---|---|---|
+| account_id | TEXT PK | Normalised ilink_bot_id (e.g. `abc-im-bot`) |
+| bot_token | TEXT | For all subsequent API auth |
+| base_url | TEXT | Regional URL from QR scan |
+| user_id | TEXT | ilink_user_id of the scanner |
+| workspace_path | TEXT | Absolute path of the bound workspace |
+| label | TEXT | User-provided name (for UI) |
+| enabled | INTEGER | 1 = long-poll active; 0 = disabled |
+| created_at | INTEGER | |
+| updated_at | INTEGER | |
+
+## Code changes
+
+### Phase 1: shared foundation
+
+**1.1 SessionManager multi-listener**
+File: `packages/server/src/agents/session-manager.ts`
+
+Current: `eventListeners: Map<rootId, handler>` stores a single handler; later callers overwrite earlier ones.
+Target: `Map<rootId, Set<handler>>`; `emitEvent` iterates the Set.
+
+API changes:
+- `registerEventListener(rootId, handler)` returns `() => void` (unsubscribe)
+- `unregisterEventListener(rootId)` removes a specific handler (signature preserved for backwards compat)
+
+Callers to update:
+- ws/handler.ts three `registerEventListener` sites (lines 228, 287, 373, 408)
+- ws/handler.ts one `unregisterEventListener` site (line 343)
+  Use the returned unsubscribe fn instead of clearing by rootId.
+
+**1.2 SessionManager registry**
+File: `packages/server/src/agents/session-manager-registry.ts` (new)
+
+Extract ws/handler.ts:54's closure-scoped `sessionManagers: Map<string, SessionManager>`:
+
+```ts
+export class SessionManagerRegistry {
+  private cache = new Map<string, SessionManager>()
+  getOrCreate(workspacePath: string): SessionManager
+  get(workspacePath: string): SessionManager | undefined
+  list(): Array<{ workspacePath: string; sm: SessionManager }>
+}
+```
+
+`index.ts` creates one `registry` shared by ws setup and weixin setup.
+
+ws/handler.ts uses the registry (minimal change: `getSessionManager(path)` delegates to the registry).
+
+### Phase 2: WeChat channel
+
+**2.1 Global DB**
+File: `packages/server/src/db/weixin-db.ts` (new)
+
+- `createWeixinDb(globalDir)` → open `~/.halo/global/weixin.db`, create the table
+- Drizzle schema for `weixin_accounts`
+
+**2.2 HTTP client**
+File: `packages/server/src/channels/weixin/api.ts` (new)
+
+Copy from plugin [api.ts](/tmp/weixin-inspect/plugin/package/src/api/api.ts), keep:
+- `getUpdates` (long-poll)
+- `sendMessage`
+- `notifyStart` / `notifyStop`
+- `getUploadUrl` + CDN upload (media support later; stub for now)
+
+Drop:
+- `redactUrl/redactBody` (no redacted logs needed)
+- `loadConfigRouteTag` + `SKRouteTag` header (internal routing)
+- `ilink_appid` reading from package.json → hard-code `"bot"`
+- `iLink-App-ClientVersion` → hard-code `buildClientVersion('2.1.10')`
+
+**2.3 QR login**
+File: `packages/server/src/channels/weixin/login.ts` (new)
+
+Copy from plugin [login-qr.ts](/tmp/weixin-inspect/plugin/package/src/auth/login-qr.ts), export:
+- `startWeixinLoginWithQr({ sessionKey })` → `{ qrcodeUrl, sessionKey }`
+- `waitForWeixinLogin({ sessionKey })` → `{ connected, botToken, accountId, baseUrl, userId }`
+
+Preserve concurrent-login via sessionKey (multiple scans in parallel).
+
+**2.4 Account DAL**
+File: `packages/server/src/channels/weixin/accounts.ts` (new)
+
+Thin DAL:
+- `insertAccount(row)`
+- `updateAccount(accountId, patch)`
+- `deleteAccount(accountId)`
+- `listAccounts()` / `getAccount(accountId)`
+- `getEnabledAccounts()`
+- `normalizeAccountId(rawId)` — from plugin: `abc@im.bot` → `abc-im-bot`
+
+**2.5 Long-poll handler**
+File: `packages/server/src/channels/weixin/handler.ts` (new)
+
+Main loop:
+
+```
+per enabled account:
+  loop {
+    resp = await getUpdates({ baseUrl, token, sync_buf })
+    for msg in resp.msgs:
+      handleInboundMessage(account, msg)
+    sync_buf = resp.get_updates_buf
+  }
+```
+
+`handleInboundMessage(account, msg)`:
+1. Extract `from_user_id` / `text` / `context_token`
+2. sessionId = `wx_` + normalize(from_user_id)
+3. sm = `registry.getOrCreate(account.workspace_path)`
+4. If session doesn't exist: `sm.createSession('default', null, 'WeChat: <userId>', 'default', sessionId)`
+5. Register a one-shot listener (or a long-lived reused one) to collect stream/tool_call/error/complete for this turn
+6. `sm.sendUserMessage(sessionId, text)`
+7. Events → text aggregation (see 2.6) → `api.sendMessage(bot_token, to=from_user_id, text, context_token)`
+
+On process start, walk `getEnabledAccounts()` and launch a long-poll per account.
+Expose `startAccount(accountId)` / `stopAccount(accountId)` for the API layer.
+
+**2.6 Event adapter**
+File: `packages/server/src/channels/weixin/event-adapter.ts` (new)
+
+WeChat `sendMessage` is whole-block; LLM is streaming — we coalesce. Copy plugin's `StreamingMarkdownFilter` strategy:
+
+- ≥ 200 chars accumulated → flush
+- 3s silence → flush
+- `complete` → flush remainder
+- Tool calls not forwarded to WeChat (user sees details on web); errors are forwarded
+
+Pseudocode:
+
+```ts
+class WeixinResponder {
+  constructor(sendFn: (text: string) => Promise<void>)
+  handle(event: OrchestratorEvent) {...}
+  flush()
+}
+```
+
+**2.7 Wire-up**
+File: `packages/server/src/index.ts`
+
+- Create `registry = new SessionManagerRegistry()`
+- Open `weixinDb = createWeixinDb(path.join(HALO_HOME, 'global'))`
+- `setupWebSocketHandler({ wss, registry })` (signature change)
+- `startWeixinChannels({ registry, db: weixinDb })`
+- On SIGTERM, call `stopAllWeixinChannels()` (which sends notifyStop)
+
+### Phase 3: API + frontend admin UI
+
+**3.1 Backend routes**
+File: `packages/server/src/routes/weixin.ts` (new)
+
+- `POST /api/weixin/login/start` → `{ qrcodeUrl, sessionKey }`
+- `POST /api/weixin/login/wait` (body: `{ sessionKey, workspacePath, label? }`)
+  On success, insertAccount + startAccount immediately
+- `GET /api/weixin/accounts` → list
+- `PATCH /api/weixin/accounts/:id` (label / workspacePath / enabled)
+- `DELETE /api/weixin/accounts/:id` → stop long-poll + delete row
+
+Mount after `index.ts:121`.
+
+**3.2 Frontend page**
+Directory: `packages/admin/src/features/weixin/` (new)
+
+- `weixin-settings.tsx` — adds "WeChat Bot" to Settings menu
+- List each bot: label / workspace / status / [edit] [delete]
+- "Add Bot" button → QR modal → poll wait API → on success let the user pick a workspace + name → save
+- QR: use client-side [qrcode](https://www.npmjs.com/package/qrcode) (pass the qrcodeUrl string)
+
+Add the tab inside the settings feature, matching current settings page style.
+
+## Execution order
+
+1. ✅ Phase 1.1 multi-listener (10 min)
+2. ✅ Phase 1.2 Registry (15 min)
+3. ✅ Phase 2.1 DB + schema (10 min)
+4. ✅ Phase 2.2 HTTP API (30 min)
+5. ✅ Phase 2.3 QR login (20 min)
+6. ✅ Phase 2.4 accounts DAL (15 min)
+7. ✅ Phase 2.6 event adapter (15 min)
+8. ✅ Phase 2.5 handler main loop (45 min)
+9. ✅ Phase 2.7 wire up index.ts (15 min)
+10. ✅ Phase 3.1 API routes (20 min)
+11. ✅ Phase 3.2 frontend page (60 min)
+12. ✅ Compile + manual QR scan test
+
+## Test path (manual)
+
+1. Deploy, open web, go to Settings → WeChat Bot → Add
+2. Scan the QR on your phone, see the bot friend request
+3. Accept the friend request, pick an existing workspace + enter a name
+4. Send "hi" from WeChat to the bot
+5. Watch the reply (with a ≥ 200 char response, test the chunking)
+6. Open the same workspace on the web, see `wx: xxx` in the session list; click to see the full conversation
+7. Send a message from the web to the same session; confirm it arrives on WeChat
+
+## Out of scope (explicit)
+
+- Image / voice / video messages (plugin supports them; MVP is text-only)
+- Group chats (plugin is private-chat only anyway)
+- /slash commands (plugin has them; we don't copy)
+- Typing indicators (`sendTyping` uncalled)
+- CDN media upload
+- Complex routing of one bot's messages to multiple sessions in a workspace
+- Inter-bot message isolation (assumption: user knows which bot maps to which workspace)
+
+## Risks
+
+- **Tencent may cap bots-per-WeChat-account**: test and see; if exceeded, fall back to "1 bot per user"
+- **`bot_type=3` stability**: hard-coded by the plugin; we follow
+- **Long-poll connection count**: each bot opens one 35s-long connection; 10 bots is fine
+- **Event-coalescing edge cases**: the 200-char / 3s cutoffs can split Markdown mid-block. Start with plugin defaults and tune after real usage.

package/bundled-docs/requirements/agent.md

@@ -0,0 +1,92 @@
+# Agent — Requirements
+
+Agent configuration management: creating, editing YAML / Form / AGENT.md.
+
+## Layout
+
+Left sidebar has two collapsible groups (Global / Workspace); right side is the editor:
+
+```
+┌─────────────────┬───────────────────────────────┐
+│ Agents          │                               │
+│─────────────────│   Form / YAML / MD Editor     │
+│ ▼ Global    (2) │                               │
+│   🤖 Default     │                               │
+│   🤖 sleeper     │                               │
+│ ▼ Workspace (1) │                               │
+│   🤖 coder       │                               │
+└─────────────────┴───────────────────────────────┘
+```
+
+## Core behaviour
+
+### YAML / Form dual view
+- **YAML view**: Monaco-edit the raw `agent.yaml`
+- **Form view**: data-driven form derived from YAML fields (name / description / model / tools / skills / thinking)
+- Switching views preserves edits
+
+### CRUD
+| Operation | API |
+|---|---|
+| List | `GET /api/agent-configs?projectId=xxx` |
+| Create | `POST /api/agent-configs` (body: `{name, description, scope, projectId?}`) |
+| Read YAML | `GET /api/agent-configs/:id/yaml` |
+| Write YAML | `PUT /api/agent-configs/:id/yaml` |
+| Delete | `DELETE /api/agent-configs/:id` |
+| Toggle disabled | `PATCH /api/agent-configs/:id/toggle` → `{ ok, disabled }` |
+
+Creating requires name + description; the backend uses `defaultAgentYaml(name, description)` to produce a full YAML.
+
+### Scope (Global / Workspace)
+- **Global**: `~/.halo/global/agents/<id>/agent.yaml` — shared across projects
+- **Workspace**: `<project>/.halo/agents/<id>/agent.yaml` — project-private; wins over a same-id global
+
+Same id present in both scopes: workspace wins; the overridden global is greyed out as "overridden".
+
+**Cross-scope conflict**: creating a same-name agent in the other scope prompts about the overwrite behaviour.
+
+**Delete protection**: at least one global agent must remain (server-enforced).
+
+### Disable / Enable
+- Toggle switch on each agent row in the admin sidebar. Disabled state is stored per workspace in the `disabled_items` table of `halo.db` (not in agent.yaml). Both global and workspace agents can be independently toggled per workspace.
+- Disabled agents are greyed out (opacity-40) with sub-text "disabled"; the toggle stays visible.
+- Hidden from: the delegation roster, chat agent selector, `/workspace share` export.
+- Still visible in the admin management sidebar for re-enabling.
+
+### Tool selection
+- **Session tools**: `start_session` / `session_list` / `query_session` / `interrupt_session` / `stop_session` / `archive_session` / `get_session_output` / `query_agent` — **not** selected by name; the whole bundle is granted automatically by a non-empty `team` (see below). Listing them under `agent.yaml tools` has no effect.
+- **Workspace tools**: `file_read` / `file_write` / `file_edit` / `file_list` / `shell_exec` / `grep` / `glob` / `web_fetch`, returned by `GET /api/agent-configs/tools`
+- **`activate_skill`**: auto-injected whenever the YAML lists `skills`; loads the full SKILL.md on demand
+
+### Team (delegation switch + whitelist)
+- Optional `team: [id, …]` field in `agent.yaml`. A **non-empty** list is the on/off switch for delegation: it grants the whole session-tool bundle (`start_session` / `query_agent` / …) plus the prompt roster, AND scopes which agents this one may reach.
+- **Unset or empty `[]` = no delegation** — no session tools, no roster. (Breaking change from the earlier "unset = every agent reachable" default; agents that relied on implicit-all must now list their team explicitly.)
+- Enforced server-side on `start_session` and `query_agent`, not just in the roster — a call to a non-team agent is rejected.
+- `self` is treated like any other agent: shown in the picker tagged `(you)`. Include the agent's own id to allow parallel self-spawn (the seed `default` agent lists `default`); omit it to block self-spawn — no special-casing.
+- **Admin form**: the Team is an always-present chip picker (one chip per delegatable agent, `self` tagged `(you)`). Checking a chip toggles that id in the `team` list; unchecking the last one drops the field entirely (`undefined` = delegation off), mirroring the server's "non-empty team" switch.
+- **Picker only offers effective, enabled agents.** A chip shows iff the *effective* agent for that id is runnable — same resolve-then-check the runtime uses: a workspace agent shadows the same-id global (the overridden global is skipped), then anything disabled is dropped. So a global stays out of the picker when its workspace override is disabled, even though that global's own record isn't flagged disabled. Matches the chat / cron selectors and the runtime roster — you can never pick a teammate that can't actually run.
+
+### Skill selection
+`GET /api/skills?projectId=xxx` lists available skills; `agent.yaml`'s `skills` references them by id.
+
+### MD file editing
+
+| File | Writable | Purpose |
+|---|---|---|
+| AGENT.md | yes | Agent personality / behaviour (overrides YAML `system_prompt`) |
+| INSTRUCTIONS.md | yes | User preferences (global or workspace scope) |
+
+The MD editor has a **Global / Workspace** scope toggle (visible when a workspace is open).
+
+API: `GET/PUT /api/agent-configs/:id/md/:fileType`
+
+### Test button
+- Sets `selectedAgentId` in the chat store
+- Dispatches a `halo:navigate` event to switch to explorer/chat
+- The user chats with the selected agent in the main chat panel
+- **Not rendered for internal agents** (`internal: true`) — they're delegated to by other agents, never driven directly
+
+### Internal agents
+Agents flagged `internal: true` in agent.yaml (e.g. `__evo_agent__`, `__apply_agent__`, `__score__`) are platform tooling. They are hidden from every user-facing surface: the delegation roster, `/session new` default pick, and the chat agent selector — and have no Test button. They stay editable in the management sidebar's collapsed **Internal** group.
+
+Replaces the old built-in test chat panel, giving a more realistic environment (full workspace tools + session persistence).

package/bundled-docs/requirements/chat.md

@@ -0,0 +1,81 @@
+# Chat — Requirements
+
+The primary surface for talking to an agent.
+
+## Core behaviour
+
+### Agent selection
+- Bottom-left dropdown in the chat panel selects which agent to use
+- Lists every available agent (from `GET /api/agent-configs`; overridden and disabled agents are hidden)
+- Default agent has a "default" badge
+- **Locked during an active session** — the agent is bound to the session; to change, start a new session (/session new)
+- The Agents panel's "Test" button can also preselect an agent
+
+### Message rendering
+- Markdown + code-block highlighting
+- Tool-call card: expandable, shows tool name / input / output
+- Sub-agent messages carry the agent-name label (e.g. "Coder", "Researcher")
+- Streaming text has a cursor animation
+
+### Slash commands
+
+The full command list is fetched from `GET /api/commands` per session and includes built-ins + skill commands. The following are always-present highlights for the chat surface:
+
+| Command | Type | Purpose |
+|---|---|---|
+| `/help` | client | List available commands |
+| `/clear` | client | Alias for `/session new` (admin-UI shortcut, no server registration) |
+| `/session new` | server | Start a new session |
+| `/session context` | server | Show context window usage, agent info |
+| `/session compact` | server | LLM-summary compact of the conversation |
+
+See [requirements/command.md](command.md) for the full command surface.
+
+### Graceful interrupt
+Sending a new message while the agent is generating **does not** abort — the message goes to the server queue, the agent finishes the current turn at the next safe checkpoint (after a tool call), and then runs the queued message. Queueing multiple messages is supported; they run in order.
+
+### Stop
+The Stop button hard-aborts — the server receives `chat:stop`, AbortController fires, queue clears, buffers flush.
+
+### Editor context injection
+When `contextEnabled` is on (default), user messages are auto-prepended with:
+- `[Currently viewing: path/to/file.ts]`
+- `[Selected text in file.ts:10-25]\n\`\`\`...\n\`\`\``
+
+### File attachments
+- Drag to chat input
+- 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).
+
+### 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). Paths inside the active workspace or under `/tmp/` are previewable; everything else degrades to a non-clickable chip.
+
+### Live capture (desktop only)
+Lets the agent *see something live* on demand. Desktop client (Electron) only — the entry points never render in a plain browser. Borrows the meeting-app "share" model: the user binds one source, then the agent requests a frame when it actually needs to look.
+
+Two source kinds in the chat-input toolbar, **mutually exclusive** (only one bound at a time):
+- **Screen / window share** (MonitorUp button) — opens a picker grid of screens + app windows. A bound window can be grabbed even while it sits in the background.
+- **Camera** (Camera button) — toggles the webcam on. Hidden entirely on a machine with no camera.
+
+Once bound, a frame is **not** attached to every message. Instead a one-line instruction is injected into the next send ("the user is sharing the «X» window" / "the user has turned the camera on") telling the model to output a line containing exactly `<<<CAPTURE>>>` when it needs to see the current view. On turn completion the frontend detects the marker, grabs one frame, and sends it back as a **visible image message** — the model sees it on its following turn. So it's a cross-turn round-trip: model asks → frame is sent back → model answers next turn. The returned frame is also shown inline on the user bubble so you can see exactly what was sent.
+
+Constraints:
+- Shown only when the selected agent's model accepts image input (capture is pointless on a text-only model); switching to a text-only model auto-unbinds.
+- Screen share needs macOS **Screen Recording** permission; the camera prompts for **Camera** permission on first use, with an "Open Settings" path if previously denied.
+- Binding is **in-memory only** — switching sessions or restarting requires re-selecting.
+
+### 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.
+
+- **What it is.** A self-contained animated particle canvas at `<workspace>/.halo/canvas/self.html` — a breathing core that reacts to the cursor (knows when it's watched), can form words/CJK/ASCII-from-emoji, play choreographed sequences, and gesture (pulse/flash/shake). Zero external references (no CDN/remote fonts) — ships and runs offline.
+- **Seeding.** Force-copied from `packages/server/templates/canvas/self.html` into every workspace on open (platform-owned, like built-in skills). The `self` built-in skill (wired into the default agent) teaches the agent it has this face and how to drive it.
+- **Opening it.** The ✨ button in the chat-input toolbar opens the face in the editor preview (switches to Explorer, render-mode on → lands on the live face) and posts `self.intro()` once it has mounted, so there's always a greeting when a human turns to look. The greeting is driven solely by this open action — the page does **not** self-fire it on load — so it plays exactly once, on both first and subsequent opens. The user can also just open the file directly (no auto-greeting in that path).
+- **Driving it.** The agent emits `<<<SHOW: …js… >>>` markers in a reply; Halo forwards the payload **verbatim** (it never parses it) to the open preview iframe via `postMessage`, where it's `eval`'d against the face's `self` API (`say`/`play`/`react`/`pulse`/`flash`/`shake`/`intro`) inside the sandboxed iframe. Markers are stripped from the rendered chat (like `<<<CAPTURE>>>`) — the user sees the face move, not the code. Multiple markers in one reply **queue and play in order**.
+- **Engine vs. expression.** `self.html` is a stable *engine* (defines how the face can move); the agent expresses itself by sending runtime JS, **never** by editing the file — so the force-copy-on-open never clobbers anything meaningful. The engine only changes when the platform adds a new capability (template edit + `TEMPLATE_VERSION` bump).
+- **No open preview = no-op.** `<<<SHOW>>>` only reaches a mounted preview; if the face isn't open the marker is silently dropped (the skill tells the agent to invite the user to open it rather than rely on a marker landing in the void).
+- **Identity.** Deliberately nameless ("HELLO / A MIND / IS HERE / BEYOND WORDS") — the conversational identity is user-configurable and the model may not be Claude, so the face never hard-codes a name.
+
+### Token usage
+`TokenRing` shows live context window usage. Crossing `model.compressAt` (default 80%) auto-triggers compact.

package/bundled-docs/requirements/command.md

@@ -0,0 +1,130 @@
+# Command — Requirements
+
+Unified command processing — all slash commands (built-in + skill) are dispatched through `dispatchCommand` (channels/shared/commands.ts) and discoverable via REST.
+
+## Built-in commands
+
+Source: [commands/index.ts](../../../packages/server/src/commands/index.ts) (descriptors) + [channels/shared/commands.ts](../../../packages/server/src/channels/shared/commands.ts) (execution)
+
+Top-level built-in slash commands: `/help` `/evo` `/session` `/agent` `/skill` `/workspace`. (`/cron` and `/acp` look like top-level commands too but are provided by same-name skills — see the verb table below; they aren't registered in `commands/index.ts` or `DISPATCH_COMMANDS`.)
+
+| Name | Slash | Type | Purpose |
+|---|---|---|---|
+| `help` | `/help` | client | List commands — object commands show only the verbs the user can run; a command is hidden entirely if no verb is runnable |
+| `evo` | `/evo [text]` | server | Flat command (no verbs), **full-only**. Trigger self-evolution on the current root session: snapshot the conversation + queue an evo run. Optional text becomes a hint for what to focus on. Available only when `general.evolution.level=L1`. See [plans/self-evolution.md](../plans/self-evolution.md). |
+
+The rest are noun-verb **object commands**: `/<obj> <verb> [args]`. Some verbs are built-in deterministic code (`SUBCOMMAND_ROUTES`); the others fall through to the same-name skill (LLM, dispatched via `$1`). Bare `/<obj>` or `/<obj> help` lists the verbs available to the user (filtered by access level).
+
+| Command | Verbs (access) |
+|---|---|
+| `/session` | new / list / info / switch \<n\> / stop / interrupt / compact / context — all built-in, all users (readonly can only switch / inspect its own sessions) |
+| `/agent` | list / switch / desc (built-in, no gate) · delete (built-in, full) · create / update (skill verb, full) |
+| `/skill` | list / desc (built-in, no gate) · disable / enable (built-in, workspace) · delete (built-in, full) · create / update (skill verb, full) |
+| `/workspace` | info (built-in, no gate) · switch (built-in, full) · setup / tidy (skill verb, workspace) · share (skill verb, full) — `/w` is a built-in alias (see [Command aliases](#command-aliases)) |
+| `/cron` | create / list / update / enable / disable / delete — all skill verbs, full |
+| `/acp` | kiro / claude (ask a local agent directly; question = rest of line) · add / list / remove (manage generated ask-* bindings) — all full |
+
+Session lifecycle actions (`session:clear`, `session:delete`) are handled inline by the WS handler, not as slash commands.
+
+### `/session info`
+
+Built-in verb (no access gate beyond ownership). Prints the **session tree** for the caller's current root session — the root plus every descendant sub-agent, so the user can see the whole delegation fan-out at a glance:
+
+- One line per session, indented by depth (root is flush-left with a `→` bullet; each level of sub-agent adds two spaces and a `├` bullet).
+- Each line carries the agent name, a **status glyph** — 🟢 running / ⏹ stopped / 📦 archived — and two timestamps: created (`建` / `new`) and last-active (`活` / `act`).
+- A header line names the root id (last 12 chars) and its title.
+
+Resolution starts from the caller's active session, walks up to its root (`id.split('>')[0]`), then lists descendants via `SessionManager.listDescendants`. **Access scoping**: non-`full` users only see a tree whose root id starts with their own `sessionPrefix` — otherwise the command refuses (a readonly/guest user can't inspect another user's tree). The same own-tree scoping applies to **agents**: the by-id session tools (`query_session` / `interrupt_session` / `stop_session` / `archive_session` / `get_session_output`) only act on sessions sharing the caller's root id — see [session.md → By-id tool scoping](../design/session.md#by-id-tool-scoping).
+
+## Command aliases
+
+`dispatchCommand` expands shorthand aliases before routing, so every channel (WS, WeChat, Telegram, Web, CLI/TUI) gets the same shortcuts uniformly. Aliases are read from a single seed file:
+
+- **`~/.halo/global/aliases.yaml`** — seeded once on first run (`init.ts`, via `writeIfMissing`), **never overwritten**, so the user can freely edit it. Deleting the file disables all aliases. Changes take effect immediately: the loader caches the parsed YAML keyed by file **mtime**, re-reading only when the file changes (no restart, no per-command disk parse on the hot path).
+
+Two expansion stages run in order (`expandAlias`):
+
+1. **`top`** — whole-prefix replacement of the first slash token. The alias value can carry a verb, which is prepended to the args. E.g. `/ss <n>` → `/session switch <n>`; `/w` → `/workspace`.
+2. **`verb`** — abbreviation of the first word of the args (the verb). E.g. `/session sw 2` → `/session switch 2`.
+
+The seeded defaults:
+
+| Stage | Alias → expansion |
+|---|---|
+| `top` | `/s`→`/session` · `/a`→`/agent` · `/h`→`/help` · `/w`→`/workspace` · `/ss`→`/session switch` · `/sl`→`/session list` · `/si`→`/session info` · `/sn`→`/session new` · `/ws`→`/workspace switch` · `/wi`→`/workspace info` · `/as`→`/agent switch` · `/al`→`/agent list` |
+| `verb` | `sw`→`switch` · `ls`→`list` · `i`→`info` · `n`→`new` · `ctx`→`context` · `st`→`stop` · `int`→`interrupt` |
+
+The canonical command is `/workspace`; `/w` is its bare alias. `/ws` and `/wi` are shortcuts for the two built-in verbs (`/workspace switch` / `/workspace info`), mirroring the `/ss` / `/si` session shortcuts.
+
+## Cross-channel commands
+
+All channels (WS, WeChat, Telegram, Web, CLI/TUI) share `dispatchCommand` for common commands. Channel-specific commands (e.g. WeChat `/name`) are handled in the channel handler before reaching the shared dispatch.
+
+## Skill-as-command
+
+Skills whose SKILL.md frontmatter carries a `command` field auto-register as slash commands:
+
+```yaml
+---
+name: code-review
+description: Review code changes
+command: /review
+---
+```
+
+Related frontmatter fields:
+
+- `verbs` (Halo extension) — declares subcommands, each `{ name, builtin?, requiresAccess?, desc? }`; `builtin: true` means the verb is handled by platform code (declarative — actual routing is `SUBCOMMAND_ROUTES`); a skill verb's access gate is what's declared here.
+- `user-invocable: false` (standard) — never becomes a slash command; the model can still activate the skill.
+- `disable-model-invocation: true` (standard) — command exists but the skill is not injected for model auto-activation.
+
+When triggered, the skill body is read from disk and sent to the agent session as a message:
+
+```
+[Skill activated: /review]
+
+{SKILL.md body}
+```
+
+User args are filled via `$ARGUMENTS` / `$1`–`$9` placeholders (args are no longer appended verbatim to the body end); a verb reaches the body as `$1` for dispatch.
+
+Every `GET /api/commands?projectId=xxx` rescans skill directories.
+
+### Conflict detection
+
+A skill's `command` must not collide with a built-in slash command or with another skill's. Collisions are resolved at scan time in `scanSkillDescriptors`, the single source feeding both dispatch and the discovery API:
+
+- **Built-ins always win** — a skill command colliding with a built-in is not registered as a command. This is by design for object commands: their same-name skill (e.g. `agent`, `skill`, `workspace`) is shadowed as a command, but its body still serves the skill verbs (create / update etc.) via the verb fallback.
+- **Among skills, first-come wins** (workspace scope is merged over global before this check); the later one is dropped with a warning.
+- Colliding entries are **dropped** from the command list and a warning is logged (`[CommandRegistry] skill "<id>" command "/x" shadowed by …`). Dropping at the shared source guarantees a command can never appear in the palette that dispatch is unable to route ("visible but unreachable").
+
+Note: a skill's `command` collision only removes the *slash command*; the skill itself remains usable via the agent's normal skill activation.
+
+## Command discovery API
+
+```
+GET /api/commands?projectId=xxx
+→ { commands: CommandDescriptor[] }
+```
+
+Returns every non-hidden command (built-in + skill). The frontend calls this on project switch to populate the command palette.
+
+## Adding a new command
+
+A server-handled command lives in **three** places that must stay in sync —
+miss any one and the server either throws at startup or silently no-ops:
+
+1. Add a `exec<Name>` function in `channels/shared/commands.ts`
+2. Add a case to the `dispatchCommand` switch (same file)
+3. Add the slash name to the `DISPATCH_COMMANDS` array (same file) — this is the
+   list the startup sanity check in `index.ts` compares against the registered
+   descriptors. It is **not** derived from the switch; forgetting it throws
+   `Command descriptors without a dispatch case: /<name>` and the server exits.
+4. Register a descriptor in `commands/index.ts` via `commandRegistry.registerDescriptor()`
+
+The startup check is bidirectional: every `type:'server'` descriptor must appear
+in `DISPATCH_COMMANDS`, and every entry in `DISPATCH_COMMANDS` must have a
+descriptor (else `Dispatch cases without a descriptor: /<name>`). Client-only
+commands (e.g. `/clear`) belong in neither — they're handled in the frontend.
+
+Implementation details in [design/command.md](../design/command.md).