@turmind/halo 0.1.9 → 0.2.1-bc7cf2b

package/bundled-docs/plans/todo.md

@@ -1,32 +0,0 @@
-# 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

@@ -1,255 +0,0 @@
-# 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/test/docs-seeding.md

@@ -1,101 +0,0 @@
-# Platform Docs Seeding Test Cases
-
-Test URL: local server (default `http://localhost:9527/?folder=<absolute-workspace-path>`).
-Password: whatever `HALO_PASSWORD` is set to, or the random password printed by the server on first startup.
-
-Prerequisite: `~/.halo/global/` already exists from a prior run. Pick any workspace that is **not** the halo source repo (e.g. `/path/to/test-workspace`).
-
----
-
-## Test matrix
-
-### A. First-time seed
-
-| # | Scenario | Method | Expected |
-|---|---|---|---|
-| A1 | Fresh install simulation | `rm -rf ~/.halo/global/docs && restart server` | Startup log: `[Init] Seeding platform docs from ...`; `~/.halo/global/docs/` has 13 files |
-| A2 | Source detection in monorepo | Start server from `/path/to/halo`, delete docs first | Log: `Seeding platform docs from /path/to/halo/.halo/docs` |
-| A3 | Source detection for packaged install | Create `packages/server/bundled-docs/guide/skills.md` with "FAKE"; delete `~/.halo/global/docs/`; restart | Log says `Seeding platform docs from .../bundled-docs`; `~/.halo/global/docs/guide/skills.md` contains "FAKE" |
-| A4 | No source at all | Move init.js somewhere isolated (no repo parent, no bundled-docs), run | Log: `[Init] No docs source found — skipping platform docs seed`; no crash; `~/.halo/global/docs/` not created |
-| A5 | Allowlist boundary | After A1, check what's in `~/.halo/global/docs/` | Only 13 files: `guide/` (8), `dev/` (3), `requirements/` (2). **No** `INDEX.md`, `design/`, `test/`, `plans/`, or other `dev/`/`requirements/` files (the doc lookup table now lives inline in the `halo` skill) |
-
-### B. User edits and upgrades
-
-| # | Scenario | Method | Expected |
-|---|---|---|---|
-| B1 | User edit preserved | Edit `~/.halo/global/docs/guide/skills.md` → restart server | Edit intact; no `[Init] Created` log for that file |
-| B2 | Deleted file restored | `rm ~/.halo/global/docs/guide/agents.md` → restart | Log: `[Init] Created .../agents.md`; file restored from source |
-| B3 | Version bump hint | Set `.template-version` to a value below the current `TEMPLATE_VERSION` (see `packages/server/src/init.ts`), restart | Log: `[Init] Seed templates updated: v<old> → v<current>. To refresh a specific file, delete it from ... and restart.` Plus `[Server] Templates outdated (v<old> → v<current>), refreshing ~/.halo/global/` from the startup version-check |
-| B4 | Idempotent second run | Restart the server twice in a row | Second run has **no** `[Init] Created` logs; `.template-version` stays at the current `TEMPLATE_VERSION` |
-
-### C. Agent-facing integration
-
-| # | Scenario | Input | Expected |
-|---|---|---|---|
-| C1 | `halo` skill carries the doc table | Open any chat with the default agent, Debug mode → first message → Prompt button | System prompt lists the `halo` skill in the available-skills block. Activate it (`activate_skill halo`) and the loaded body contains `### Platform Documentation` with the "User asks … / Read …" lookup table |
-| C2 | Agent knows about bundled docs | Open chat in a non-halo workspace, ask: "what platform docs ship with halo?" | Agent activates the `halo` skill and answers from its lookup table (no `file_read` needed for the overview) |
-| C3 | Answer to "how do I test my skill?" | New chat, ask: "I just made a skill. How do I test it?" | Agent reads `~/.halo/global/docs/guide/testing-agents-and-skills.md` directly (path from system prompt table), answers with the attach-to-agent → Test → trigger flow |
-| C4 | Answer to "where do API keys go?" | New chat, ask: "I want my skill to use an API key. Where do I put it?" | Agent reads `guide/secrets-and-credentials.md`, explains schema in `config.yaml` + value in `settings.yaml` + `<<ENV>>` + skill body using `{{params.<key>}}` short form |
-| C5 | Answer for a question NOT in bundled docs | New chat, ask: "how does the file watcher debounce work?" | Agent looks for it in the docs, doesn't find (bundled docs don't have `design/`), falls back to reading code or admits it doesn't know — **does not hallucinate** |
-| C6 | Works in any workspace | Repeat C3 in a workspace that has **no** `.halo/docs/` of its own (e.g. `/path/to/test-workspace`) | Same answer — proves docs come from `~/.halo/global/`, not the workspace |
-
-### D. Negative / edge cases
-
-| # | Scenario | Method | Expected |
-|---|---|---|---|
-| D1 | Permissions issue | `chmod -w ~/.halo/global/docs/` → delete one file → restart | `[Init] Failed to read template` or similar error logged; server still starts (seed is best-effort) |
-| D2 | Concurrent starts | Start two server processes at the same time against the same home dir | Only one wins the pid lock; losers exit cleanly (not a seed-specific test, but confirms seed doesn't race) |
-| D3 | Partially-populated docs | Remove half the files in `~/.halo/global/docs/guide/`; restart | Exactly the removed files get `[Init] Created` logs; others untouched |
-| D4 | Garbage `.template-version` | Write `abc` to `~/.halo/global/.template-version`; restart | Treated as 0; seed runs; version is reset to the current `TEMPLATE_VERSION` at the end |
-
----
-
-## Verification helpers
-
-### Check seeded file count
-
-```bash
-find ~/.halo/global/docs -type f | wc -l
-# Expected: 13
-```
-
-### Check allowlist boundary (A5)
-
-```bash
-# These should all NOT exist
-ls ~/.halo/global/docs/design/ 2>&1  # No such file
-ls ~/.halo/global/docs/test/ 2>&1    # No such file
-ls ~/.halo/global/docs/plans/ 2>&1   # No such file
-ls ~/.halo/global/docs/requirements/terminal.md 2>&1  # No such file
-ls ~/.halo/global/docs/dev/api.md 2>&1                # No such file
-```
-
-### Check `halo` skill carries the doc table (C1)
-
-```bash
-grep -A 3 "Platform Documentation" ~/.halo/global/skills/halo/SKILL.md
-# Expected: "### Platform Documentation" section with the inline "User asks … / Read …" lookup table
-```
-
-### Check source that was used
-
-```bash
-grep "Seeding platform docs\|No docs source" /tmp/halo.log 2>/dev/null | tail -1
-# Or check server's stdout — the log line is emitted once per startup
-```
-
-### Force a fresh seed
-
-```bash
-rm -rf ~/.halo/global/docs ~/.halo/global/.template-version
-# Restart server
-# Expected: 13 [Init] Created log lines for docs/*
-```
-
----
-
-## Known limitations
-
-- **Cross-links to non-bundled docs** (e.g. `guide/skills.md` → `design/prompt-system.md`) will 404 if an agent tries to follow them. Agents should answer from the doc body rather than chase links. Noted in the `halo` skill body.
-- **Version downgrade** not detected: if you set `.template-version` higher than the current `TEMPLATE_VERSION`, nothing happens — no warning, no overwrite. Not a concern in practice.
-- **Seed does not overwrite**. If a user edits a file and a newer Halo version ships a fix to the same doc, the user's edit wins. Workaround: `rm` the file and restart.