@aiwayds/dsh-tui-pi 0.1.0 → 0.3.0

package/README.md

@@ -16,16 +16,12 @@ pi-style terminal UI for [DeepSeek Harness](https://github.com/deepseek-ai/deeps
 │ ├─ ☑ Todo 1: 启动 subagent A 执行 10s 任务并收集结果        │  ← fixed widgets
 │ └─ ◐ Todo 2: 启动 subagent B 执行 10s 任务并收集结果        │    above the input
 └─────────────────────────────────────────────────────────────┘
-┌─ ● Agents ─────────────────────────────────────────────────┐
-│ ├─ ⠼ spawn  Subagent A 10s 任务 · 1.2k token · 19.0s       │
-│ │    ⎿  running sleep…                                     │
-│ └─ ⠼ spawn  Subagent B 10s 任务 · 562 token · 6.0s         │
-│      ⎿  working…                                           │
-└─────────────────────────────────────────────────────────────┘
 ∴ working…                                                    ← status
 📁 ~/github (Full access) │ ⎇ main                            ← editor border
 [ 请输入指令…                                                ] ← input
  ↳ 创建 2 个 todo, 每个 todo 起一个 10s 的 subagent            ← last request
+  ↳ ⠼ Subagent A 10s 任务 · 1.2k token · 19.0s                 ← running agents
+  ↳ ⠼ Subagent B 10s 任务 · 562 token · 6.0s                   ← (compact lines)
 dsh ▸ ☁ opencode-go ▸ 🤖 deepseek-v4-flash ▸ ● high ▸ 🧠 11.6k/1.0M (1.2%) ▸ ⚡ CH98.9% ▸ 💬 8 ▸ 🔧 4       00:00:14   ← footer
 ⌨ Enter: send · Ctrl+C: cancel / double: quit                 ← hints
 ```
@@ -42,21 +38,27 @@ dsh ▸ ☁ opencode-go ▸ 🤖 deepseek-v4-flash ▸ ● high ▸ 🧠 11.6k/1
   `cmux-theme.sh` GitHub terminal themes). Hot-switchable at runtime: pick one
   with `/theme` (applies immediately), edit the `dsh-tui.theme` setting
   (external edits hot-apply too), or pin with `DSH_TUI_THEME=light|dark` — the
-  env var wins over every preference. Without a preference, terminal-background
-  detection (COLORFGBG).
+  env var wins over every preference. The app paints its own canvas, so a
+  switch recolors the whole screen (background included) even inside
+  multiplexers; without a preference, `auto` detects the terminal background
+  (COLORFGBG + a live OSC 11 / CSI 996n query) and follows the terminal's
+  light/dark switches in real time.
 - **Footer**: powerline segments ported from
   [pi-powerline-footer](https://github.com/fan56/pi-powerline-footer) —
   provider / model+thinking / context / cache-hit / msgs / tools with U+E0B0
   arrows, right-aligned live clock, cwd+git-branch editor top border, and the
   `↳ last-request` widget.
-- **Live todos & subagents**: bordered panels pinned **above the chat input** —
-  a `● Todos (done/total)` tree (`☐`/`◐`/`☑` status icons) and a live
-  `● Agents` board (spinner, provider + label, retries, token count + context
-  percent, elapsed and the current tool) refreshed ~10×/s. Show while there is
-  content, clear when done — a settled child drops off the board and an empty
-  panel collapses to zero rows. Subagents are tracked from the child sessions
-  themselves (header `origin: subagent` + `parentSession`), so any spawn
-  mechanism works. The TUI also supports pi's `APPEND_SYSTEM.md` convention
+- **Live todos & subagents**: the `● Todos (done/total)` tree (`☐`/`◐`/`☑`
+  status icons) is a bordered panel pinned **above the chat input**; the
+  running subagent activity merges into the **last-request area below the
+  editor** as compact lines (`  ↳ ` prefix, spinner + agent **name** first,
+  retries, token count + context percent, elapsed — no provider) — no box, no
+  header, just one line per running
+  child. Both refresh ~10×/s. Show while there is content, clear when done —
+  a settled child drops off and an empty panel/area collapses to zero rows.
+  Subagents are tracked from the child sessions themselves (header `origin:
+  subagent` + `parentSession`), so any spawn mechanism works. The TUI also
+  supports pi's `APPEND_SYSTEM.md` convention
   (dsh side: `~/.dsh/APPEND_SYSTEM.md`): a user-editable file whose content is
   appended to the system prompt of every agent the TUI creates — read at each
   assembly, so edits apply to the next request without a restart. The TUI's
@@ -78,7 +80,10 @@ dsh ▸ ☁ opencode-go ▸ 🤖 deepseek-v4-flash ▸ ● high ▸ 🧠 11.6k/1
 | `/export` | write the current session log as JSONL — default `~/Downloads/dsh-session-<id>.jsonl`, or a path argument. |
 | `/permission` | permission-preset picker (whatever the deployment table advertises — read-only / workspace-write / danger-full-access). Select a preset to apply it through dsh's canonical `/permission <name>` command, or Esc to keep the current one. The editor's top border shows the live preset badge (danger-full-access → "Full access"). |
 | `/theme` | color-scheme picker (auto / light / dark). The choice applies immediately and is persisted to `dsh-tui.theme`. |
+| `/agents` | manage agent definition markdown files (name/model/thinking/deep per agent) **and the subagent limits** — `l` from the table opens the limits panel: `maxAgents` (concurrent live children, default 4) and `maxRounds` (completed turns before the TUI queues a wrap-up request, default 50; both `0 = unlimited`). Limits are read live at every spawn/turn decision; writes go to the `dsh-tui` settings namespace and hot-apply. Also the initial view when no agent files exist yet. |
+| `/subagents` | the command twin of `Ctrl+G`: pick a running (or recently settled) subagent and watch its live transcript in the 80% viewer — status, rounds against the cap, tokens, tool calls. |
 | `/reload` | hot-reload the plugin from the current source (after `pnpm build`) without restarting dsh — the TUI and the live agent are torn down; the session log persists and can be rejoined with `/resume`. |
+| `/hotkeys` | keybinding browser: the effective app-key table (custom overrides starred) plus the keybindings file path — see [Custom keybindings](#custom-keybindings). |
 
 Anything that is not a resolvable command falls through to the model as an
 ordinary prompt, so dsh packages' commands (and future registrations) appear
@@ -94,9 +99,9 @@ serves the route), and one-line API-key state (`API key set` / `missing` /
 document — with dedicated `DeepSeek (official)` and `Default model` rows and a
 `+ Add provider…` action. The add flow mirrors pi's `/login`:
 
-1. pick from the built-in directory (10 searchable catalog routes — Anthropic,
-   DeepSeek, Google Gemini, Groq, Mistral, OpenAI, OpenCode Go, OpenRouter,
-   Together AI, xAI);
+1. pick from the directory — every llm-pi-ai catalog route that takes an API
+   key (36 in the installed pi-ai 0.82.1), read live from the llm service with
+   a static fallback, the same directory as the web Models page;
 2. enter exactly one API key — masked dot-row editor, the value never echoes
    and never reaches the rendered output;
 3. the commit double-writes like the web Models page: `llm-pi-ai.providers.<id>`
@@ -116,13 +121,26 @@ Themes change live, no restart:
   `applies: 'live'`. The namespace's watch hook pushes the commit to the
   running TUI, which repaints everything on the next frame: transcript
   (replayed from its operation buffer), editor border, footer hint, spinner.
+- **The whole screen changes, background included.** The TUI paints its own
+  canvas (a patched pi-tui paints every rendered row with the palette's
+  canvas color), so a light→dark switch recolors the entire surface — the
+  terminal's own background never shows through, which is what makes the
+  switch look broken inside multiplexers like cmux/gostty where the pane
+  background belongs to the terminal, not the app. Set
+  `DSH_TUI_TRANSPARENT=1` to go back to the see-through canvas and keep your
+  terminal theme visible.
 - An **external edit** of `~/.dsh/settings.yaml` (`dsh-tui.theme: dark`)
   hot-applies through the same watch path.
 - `DSH_TUI_THEME=light|dark` **pins** the display regardless of preference —
   it wins at startup and keeps winning; `/theme` still persists the
   preference and honestly reports `Theme preference saved — display is pinned
   by DSH_TUI_THEME=…` instead of claiming it applied.
-- The choice survives restarts (`auto` falls back to terminal detection).
+- The choice survives restarts. `auto` detects the terminal: the synchronous
+  startup guess reads `COLORFGBG`; a background refinement then asks the
+  terminal itself (CSI `?996n` color-scheme query, falling back to an OSC 11
+  background-color query — both answered by Ghostty/cmux, kitty and iTerm),
+  and while `auto` stays selected the TUI follows live light/dark switches of
+  the terminal (CSI 997 push notifications) and repaints on the next frame.
 
 ## APPEND_SYSTEM.md
 
@@ -149,18 +167,25 @@ no reload, no watcher.
 ## Install (local)
 
 ```sh
-# build once
-cd dsh-tui-pi && pnpm install && pnpm build
-
-# live development link (recommended; edits to src/ + pnpm build apply on next launch)
-dsh plugin --profile tui add link:/path/to/dsh-tui-pi
+# build + pack + install into the profile in one step (the recommended dev loop)
+node scripts/dev-install.mjs        # = pnpm build → pnpm pack → refresh the profile's copies
 
-# or an npm tarball
-npm pack                                   # → aiwayds-dsh-tui-pi-0.1.0.tgz
-dsh plugin --profile tui add /path/to/aiwayds-dsh-tui-pi-0.1.0.tgz
+# or, manually, like a real user would:
+pnpm pack                            # → aiwayds-dsh-tui-pi-0.2.0.tgz
+dsh plugin --profile tui add /path/to/aiwayds-dsh-tui-pi-0.2.0.tgz
 ```
 
-Both paths auto-add `dsh-tui-pi` to the profile's `dsh.profile.bundles`.
+The profile's `package.json` carries **both** keys pointing at the tarball —
+`dsh-tui-pi` (dsh resolves the bundle by this name) and
+`@aiwayds/dsh-tui-pi` (the loader entry in `cordis.patch.yml` imports this
+name) — and its `pnpm-workspace.yaml` declares the pi-tui
+`patchedDependencies` (see `~/.dsh/profiles/tui/`). At runtime
+`@deepseek-ai/*` resolve through dsh's shared
+`~/.dsh/profiles/node_modules` fallback to the installed closure, so the
+profile never needs the repo's `node_modules`. Known quirk: pnpm does not
+re-read a changed `file:` tarball while its `node_modules` entry exists —
+`scripts/dev-install.mjs` removes the two installed copies before installing,
+which forces the refresh.
 
 ## Use
 
@@ -170,15 +195,112 @@ dsh --profile tui        # or: dsh-tui-pi (bin shim)
 
 - Type a prompt → Enter. Streaming reply renders live; tool calls render as
   `⚙/✔/✘` cards.
-- Todos and subagent children the model spawns show in bordered panels pinned
-  **above the chat input** (they never scroll with the transcript): a
-  `● Todos (done/total)` tree and a live `● Agents` board — spinner, provider
-  + label, retries (`↻N≤M`), tokens (+ context percent), elapsed, and the
-  current tool (`⎿ running …`). A finished child drops off the board; when
-  nothing is left the panels collapse away.
+- Todos the model spawns show in a bordered panel pinned **above the chat
+  input** (never scrolls with the transcript): a `● Todos (done/total)` tree.
+  Subagent children render as **compact lines in the last-request area below
+  the editor** (` ↳ <last request>` then one line per running child) — `  ↳ `
+  prefix, spinner + agent **name** first, retries (`↻N≤M`), tokens
+  (+ context percent), elapsed (no box, no `● Agents` header, no provider). A
+  finished child drops off; when nothing is left the panel and the activity
+  lines collapse away.
 - `/` opens slash-command autocomplete (Tab/arrows/Enter).
-- Ctrl+C quits — while the agent is mid-turn the first press cancels the turn
-  (`⏹ canceling current turn…`), any further press quits.
+
+## Keyboard shortcuts
+
+App-level keys (key mappings mirror [pi](https://github.com/badlogic/pi-mono)):
+
+| Key | Action |
+| --- | --- |
+| `Enter` | send the prompt |
+| `Esc` | **stop the current task — as a deliberate double-press** — priority chain: a popup that is open closes itself first (Esc inside a popup *never* stops the running task); the editor's autocomplete closes; a mid-turn agent waits for a second `Esc` within 500ms to cancel the whole task (parent + subagents, `⏹ canceling current turn…`; the first press only arms the window and shows a hint); a non-empty editor does **nothing** (anti-misfire); on an **empty** editor a second `Esc` within 500ms opens `/session` |
+| `Ctrl+C` | mid-turn: first press cancels the running turn, second press (within 500ms) quits; idle: first press clears the editor, second press quits. With a popup open it cancels the popup instead. **Held-key auto-repeat never quits** — repeats under 80ms apart are swallowed, and the double-press quit is confirmed for 200ms (a follow-up repeat aborts it, a human-speed re-press fires it immediately) |
+| `Ctrl+D` | quit — only when the editor is **empty**, like pi's `app.exit`; with text it is the regular delete-character-forward |
+| `Ctrl+L` | open the model/think picker (pi's `app.model.select`) |
+| `Ctrl+G` | open the subagent picker while subagents run (see `/subagents`); idle the key falls through untouched. dsh's own mapping — pi spends this key on an external editor we don't have, remap in `keybindings.json` if you miss it |
+| `Tab` | autocomplete |
+
+Editor keys (movement/deletion/undo) come from the pi-tui `Editor` default
+bindings — no dsh code involved: `←→` / `Ctrl+B`/`Ctrl+F` move, `Alt+←→` /
+`Ctrl+←→` / `Alt+B`/`Alt+F` word-move, `Home`/`End` / `Ctrl+A`/`Ctrl+E` line
+edges, `PageUp`/`PageDown` scroll, `Backspace` / `Delete`/`Ctrl+D` delete,
+`Ctrl+W`/`Alt+Backspace` delete word back, `Alt+D` delete word forward,
+`Ctrl+U`/`Ctrl+K` delete to line start/end, `Ctrl+-` undo, `Ctrl+Y`/`Alt+Y`
+yank, `Shift+Enter`/`Ctrl+J` newline. `↑` / `↓` follow this interplay: on the
+first line `↑` moves the cursor to the line start, whereas on an **empty**
+editor (or with the cursor at the line start) it browses history instead (next
+paragraph).
+
+`↑` / `↓` browse the submitted-message history shell-style. `↑` recalls the
+most recent prompt and walks further back; `↓` moves forward again, and past
+the newest entry it restores your in-progress draft. Browsing starts when the
+cursor is at the start of the first line — including on an empty editor — and
+the text you were leaving is preserved as the draft, so `↓` all the way back
+hands you the draft again. The history holds up to **500 entries**, dropping
+the oldest ones beyond that; it survives a theme hot-swap (the editor is
+rebuilt on switch). The history is in-memory for the current TUI run — it does
+**not** survive `/reload` or a restart. Submitted slash commands (`/theme`,
+`/hotkeys`, …) are recorded too. Recalling a multi-line entry places the
+cursor at its start; `↓` then walks the entry's lines before advancing the
+history — but a single-line entry round-trips identically (do not fight the
+pi-tui behavior).
+
+Not supported yet (documented status): `Ctrl+O` collapse tool output, `Ctrl+X`
+copy the last assistant message, `Alt+Enter` follow-up queue, `Ctrl+V` paste
+image, `Ctrl+Z` suspend, `Ctrl+P`/`Ctrl+Shift+P` model cycle, `Shift+Tab` think
+cycle, `Ctrl+T` collapse thinking.
+
+### Subagent viewer & fine-grained control
+
+`Ctrl+G` (or `/subagents`) opens an 80% picker over the tracked children —
+running ones first (spinner, mode, rounds against `maxRounds`, tokens,
+elapsed), then the five most recently settled. Enter opens the transcript
+viewer: one readable line per buffered child event (user/assistant messages,
+tool calls paired with truncated results, turns, todos), refreshing ~3x/s
+with tail-follow (scroll up to detach, reach the bottom to re-attach), and a
+truncation note when the per-child 2000-event ring buffer dropped its head.
+`Esc` closes; a deliberate double-`x` within 500ms closes too.
+
+Two caps steer delegation (configure in `/agents` → `l`, both live-read at
+every decision):
+
+- **`maxAgents`** (default 4, `0` = unlimited) — a `tools.guard` denies
+  model-facing spawn tools (`subagent`, `subagent_fork`, `workflow`, `ralph`,
+  `use_agent`) once that many children run, with the running labels in the
+  deny reason so the model can wait or `list_agents`. The cap is approximate
+  under a burst of parallel spawns; workflow fan-out (which bypasses the tool
+  pipeline) is pruned after the fact on `subagent/start`.
+- **`maxRounds`** (default 50, `0` = unlimited) — when a child's completed
+  turns reach the cap, the TUI queues one wrap-up request
+  ("总结和结束这个任务，汇报情况。") as its next turn — it never interrupts
+  work underway, never repeats per child, and never re-awakens a child that
+  already settled. There is deliberately **no force stop**.
+
+### Custom keybindings
+
+The five app-level keys are remappable through `$DSH_HOME/keybindings.json`
+(`~/.dsh/keybindings.json` by default) — pi's
+`~/.pi/agent/keybindings.json` convention. The file is a **partial** map of
+the app keys to pi-tui key ids; anything missing keeps its default. Key id
+format: `modifier+key`, modifiers `ctrl`/`shift`/`alt`/`super` (combined with
+`+`), key a letter/digit/symbol or a named key (`escape`, `enter`, `tab`,
+`space`, `backspace`, `delete`, `home`, `end`, `pageUp`, `pageDown`, arrows,
+`f1`–`f24` …).
+
+```json
+{
+  "escape": "ctrl+x",
+  "ctrlC": "alt+c",
+  "ctrlD": "ctrl+w",
+  "modelPicker": "ctrl+m"
+}
+```
+
+The file is read when the TUI starts. You can edit it by hand (then
+`/reload`) — or use `/hotkeys`, which shows the effective table in the same
+select-panel style as `/agents`: each app key is a row (custom overrides
+starred), `Enter` prompts for a new key id (empty input resets the key to its
+default), and a commit **writes the file and applies the change live** — no
+`/reload` needed. Invalid entries never block: they warn and keep the default.
 
 ## Performance rules (from the pi-turbo findings)
 
@@ -216,7 +338,7 @@ dsh-tui-pi avoids both by construction:
 ```sh
 pnpm check    # tsc --noEmit
 pnpm build    # emit lib/
-pnpm test     # unit tests, node --test against lib/ (171 tests, pretest builds)
+pnpm test     # unit tests, node --test against lib/ (296 tests, pretest builds)
 ```
 
 Local type-checking symlinks `node_modules/@deepseek-ai/*` to the installed
@@ -224,23 +346,13 @@ dsh closure (`/opt/homebrew/lib/node_modules/@deepseek-ai/dsh/node_modules`);
 at runtime those imports resolve to the same module instances the running dsh
 uses. Those symlinks stay out of any tarball (`files` ships lib/bin/patch only).
 
-⚠️ `pnpm install` regenerates the three type-check symlinks declared in
-`package.json` (`dsh-settings`, `dsh-client-schema-form`, `schemastery`)
-into local `.pnpm` copies, splitting the cordis module identity and breaking
-`pnpm check` — after any install, re-link them:
-
-```sh
-ln -sfn /opt/homebrew/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/{dsh-settings,dsh-client-schema-form,schemastery} node_modules/@deepseek-ai/
-```
-
-`dsh-permission-presets` is a fourth, undeclared type-check link — the same
-extraneous-closure pattern as `cordis`/`dsh-agent` above: `pnpm install`
-never regenerates it (it is not in the dependency tree), but a wiped
-`node_modules` needs it re-created by hand:
-
-```sh
-ln -sfn /opt/homebrew/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-permission-presets node_modules/@deepseek-ai/
-```
+`scripts/link-dsh-closure.mjs` (the package's `postinstall`) re-creates every
+`node_modules/@deepseek-ai/*` link to the global dsh closure after **each**
+`pnpm install`/`patch-commit`, and is a no-op without a global dsh install.
+That keeps a single `@deepseek-ai/cordis` module identity in the type graph
+(declaring any of them in `package.json` would make pnpm install a second
+local copy and break the cordis `settings` augmentation). A wiped
+`node_modules` self-heals on the next `pnpm install`.
 
 **pi-tui patch**: this plugin applies a small patch to the pinned
 `@earendil-works/pi-tui` 0.84.2 (`pnpm.patchedDependencies` in
@@ -261,14 +373,16 @@ src/
   index.ts          cordis plugin entry + wiring: command registration, footer,
                     git watcher, clock, bridge, theme hot-swap sink, shutdown
   tui.ts            TUI bootstrap: alt-screen tree, transcript ScrollView,
-                    dock (status/editor/last-request/footer), editor rebuild
+                    dock (status/editor/last-request/footer), editor rebuild,
+                    app-owned canvas background (patched pi-tui)
   session.ts        DshSessionBridge: lazy agent create, followup, resume,
                     replay, cancel, O(1) incremental stats, persistDefaultModel,
                     subagent tracker (tool-workflow + child events → live rows)
   dsh-events.ts     local types + guards for tool-workflow/subagent/llm-retry
                     events (declaring packages not installed) + AgentView
-  live-widgets.ts   LiveWidgets: fixed Todos/Agents widgets pinned above the
-                    chat window (renderTodos/renderAgents/tickLive/setTheme)
+  live-widgets.ts   LiveWidgets: Todos boxed above the input + running-agent
+                    activity merged under the last-request line
+                    (renderTodos/renderAgents/setLastRequest/tickLive/setTheme)
   commands.ts       CommandService: slash autocomplete + dual-channel dispatch
                     (registerLocal agentless direct / ctx.commands host path)
   messages.ts       TranscriptRenderer: session events → pi-tui components;
@@ -278,8 +392,19 @@ src/
   editor.ts         CwdBorderEditor (top border: 📁 cwd │ ⎇ branch)
   git.ts            GitBranchWatcher (polled, cached)
   frame.ts          FramedOverlay: shared top/bottom ─ border for every popup
-  provider-catalog.ts  built-in provider directory + deriveKeyRef + row views
-                    (pure data/functions for the Models add-provider flow)
+  panels.ts         select-panel framework: TablePanel/FieldPanel/ViewerPanel/
+                    PanelHost + padCell/columnWidths/ListController
+  keymap.ts         pure key-action decision (resolveKeyAction) — Esc/Ctrl+C/
+                    Ctrl+D/Ctrl+L/Ctrl+G chains with double-press guards
+  hotkeys.ts        keybindings.json contract + validation + /hotkeys manager
+  agent-manager.ts  agent markdown files: parse/validate/write-back engine +
+                    ~/.zcode/agents seeding, `deep` policy
+  agents.ts         /agents table + fields window + subagent limits panel
+  subagent-policy.ts  maxAgents guard + maxRounds wrap-up injection (read live)
+  subagent-viewer.ts  Ctrl+G picker + live transcript panel (300 ms tick)
+  provider-catalog.ts  built-in provider directory (36 llm-pi-ai catalog
+                    routes, mirrors the web Models page) + deriveKeyRef + row
+                    views (pure data/functions for the Models add-provider flow)
   reload.ts         /reload hot-reload (cordis-plugin-hmr style partial reload)
   text.ts           clipToWidth / visibleWidth (grapheme-safe column clipping)
   theme-settings.ts dsh-tui settings namespace (applies: 'live') + watch sink
@@ -291,22 +416,34 @@ src/
   sessions.ts       /session info panel + /resume persisted-session picker
   settings.ts       /settings browser: categories, schema walk, inline editors,
                     serialized mutate write chain, add-provider flow
+  welcome.ts        startup whale banner (WHALE_ART + PIXEL_FONT glyphs)
+  quotes.ts         startup quote pool
+  append-system.ts  APPEND_SYSTEM.md support + todo-lifecycle section
+                    maintenance (idempotent, atomic)
   theme/
     palette.ts      GitHub light/dark palettes + terminal-background detection
+                    (rgbIsLight luminance)
     index.ts        buildTheme: Editor/Markdown/SelectList/chat roles, POWERLINE
                     segment palette, resolveTheme (env > preference > detect)
-test/*.test.mjs     unit tests, node --test against lib/ (171 across 14 files)
+test/*.test.mjs     unit tests, node --test against lib/ (296 across 24 files)
 ```
 
-## Status (2026-08-15)
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for the release history.
+
+## Status (0.2.0)
 
 All surface commands shipped and tmux-e2e verified: `/model /think /session
-/resume /new /settings /export /theme /reload`; provider-first Models with the
-add-provider flow; overlay chrome (backgrounds + borders); theme hot-switch
-(immediate apply, external-change watch, env pinning); graded Ctrl+C; live
-todos + subagent progress blocks; clean Ctrl+C exit. `pnpm check` clean,
-171 unit tests green, e2e run confirmed the settings/credentials files are
-restored byte-for-byte.
+/resume /new /settings /export /theme /reload /agents /subagents /hotkeys`;
+provider-first Models with the add-provider flow; overlay chrome
+(backgrounds + borders); theme hot-switch (immediate apply, external-change
+watch, env pinning) with an app-owned canvas background that recolors the
+whole screen; terminal-following `auto` theme; subagent viewer with live
+rounds/tokens/elapsed; subagent `maxAgents`/`maxRounds` limits; pi-aligned
+keybindings with double-press guards; live todos + subagent progress blocks;
+clean Ctrl+C exit. `pnpm check` clean, 296 unit tests green, e2e run
+confirmed the settings/credentials files are restored byte-for-byte.
 
 Known limitations (accepted, pi-tui 0.84.2 constraints):
 

package/lib/agent-manager.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Agent definitions as markdown files — the dsh terminal counterpart of the
+ * pi fun-agent / zcode "one file per agent" convention.
+ *
+ * An agent is a `<agents-dir>/<name>.md` file with a `---` frontmatter block
+ * and a markdown body that doubles as the agent's system prompt:
+ *
+ *   ---
+ *   name: oldfox
+ *   display_name: 老法师
+ *   description: "顾问角色：review、挑刺、保证健壮性。"
+ *   color: red
+ *   model: volc-ark-plan/glm-5.3
+ *   thinking: high
+ *   deep: 1
+ *   ---
+ *   You are 老法师 — 顾问…
+ *
+ * Frontmatter keys are parsed loosely (`key: value`, optional surrounding
+ * quotes); `name` is required, `description` feeds the picker subtitle,
+ * `model` is a dsh `provider/model` route (the picker rewrites it), and
+ * `deep` caps how many levels of subagents this agent may spawn (default 1,
+ * 0 = never, no unlimited — there is no spelling for unbounded depth).
+ * The body is kept verbatim.
+ */
+/** One agent's frontmatter-derived metadata (the editable surface). */
+export interface AgentMeta {
+    /** File basename without `.md` — required, the stable agent id. */
+    name: string;
+    /** Optional display name, shown before `name` in the picker. */
+    displayName?: string;
+    /** Optional one-line summary shown as the picker subtitle. */
+    description?: string;
+    /** Optional 8-color label (red/blue/green/yellow/purple/orange/pink/cyan). */
+    color?: string;
+    /** dsh model route (`provider/model`); absent = inherit the default. */
+    model?: string;
+    /** Reasoning effort id (off/low/medium/high/max); absent = inherit. */
+    thinking?: string;
+    /** Max subagent spawn depth: default 1, 0 = never spawn children. */
+    deep: number;
+}
+/** A parsed agent file: metadata + the raw system-prompt body. */
+export interface AgentFile {
+    path: string;
+    meta: AgentMeta;
+    body: string;
+}
+/** One parse outcome: a usable agent, or a broken file with a reason. */
+export type AgentParseResult = {
+    ok: true;
+    agent: AgentFile;
+} | {
+    ok: false;
+    error: string;
+};
+/** The dsh agents directory (`~/.dsh/agents`, under the dsh home). */
+export declare function agentsDir(): string;
+/**
+ * The legacy agents directory from the first shipped layout (`~/dsh/agents`,
+ * no dot). Kept only for one-time migration — see `migrateLegacyAgentsDir`.
+ */
+export declare function legacyAgentsDir(): string;
+/**
+ * One-time migration from the legacy `~/dsh/agents` layout into
+ * `~/.dsh/agents`: when the target directory holds no agents but the legacy
+ * one does, every legacy file is copied over. Idempotent.
+ */
+export declare function migrateLegacyAgentsDir(targetDir?: string, legacyDir?: string): number;
+/** zcode agent files are the one-time seeding source (model converted). */
+export declare function zcodeAgentsDir(): string;
+/**
+ * Parse one agent markdown file. Tolerates CRLF, quotes, and non-key lines
+ * inside the frontmatter; `name` is required, `deep` must be a non-negative
+ * integer when present (absent defaults to 1).
+ */
+export declare function parseAgentMarkdown(text: string, path: string): AgentParseResult;
+/** Render an agent back to markdown (frontmatter + blank line + body). */
+export declare function renderAgentMarkdown(meta: AgentMeta, body: string): string;
+/** List agents under `dir` (top level only), broken files reported aside. */
+export declare function listAgentFiles(dir: string): {
+    agents: AgentFile[];
+    broken: Array<{
+        path: string;
+        error: string;
+    }>;
+};
+/**
+ * Frontmatter field updates for one agent file. `undefined` leaves the key
+ * untouched; `null` removes the line (the "inherit" spelling — the agent
+ * falls back to its default); a concrete value writes/replaces the line.
+ */
+export interface FrontmatterUpdates {
+    model?: string | null;
+    thinking?: string | null;
+    deep?: number | null;
+}
+/**
+ * Apply frontmatter updates in place: existing lines are rewritten in place,
+ * missing keys are inserted before the closing fence, `null` removes the
+ * line. CRLF is preserved; a no-op returns without touching the file.
+ * Resolves with an error message, or `undefined` on success.
+ */
+export declare function updateAgentFrontmatter(path: string, updates: FrontmatterUpdates): string | undefined;
+/**
+ * Convert a zcode `custom:<uri-encoded providerId>:<modelName>` model value
+ * to a dsh `provider/model` route for providers we know. Unknown providers
+ * return `undefined` (caller keeps the original line); a value without the
+ * `custom:` prefix is assumed to be dsh format already.
+ */
+export declare function convertZcodeModel(model: string): string | undefined;
+/**
+ * One-time seeding: when `targetDir` holds no agents yet, copy every
+ * parseable zcode agent into it with the model converted to a dsh route.
+ * Idempotent — once any agent exists, nothing is written.
+ */
+export declare function seedFromZcode(targetDir: string, sourceDir?: string): {
+    seeded: number;
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+};
+/** Short file label for diagnostics (kept importable for callers). */
+export declare function agentFileLabel(path: string): string;