@aiwayds/dsh-tui-pi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-tui-pi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,324 @@
+# dsh-tui-pi
+
+pi-style terminal UI for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh).
+
+## Preview (ASCII mock-up)
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  🐳: 两个 subagent 已在后台并行启动 (A: 5b19b15c, B: d2072ffd) │  ← transcript (scrolls)
+│  ┌─ 💭 thinking ──────────────────────────────────────────┐  │
+│  │ Actually, I can check list_agents or wait…             │  │
+│  └────────────────────────────────────────────────────────┘  │
+│  ⚙ bash  python scripts/demo.py  …  ✔ bash                │  │
+└──────────────────────────────────────────────────────────────┘
+┌─ ● Todos (1/2) ────────────────────────────────────────────┐
+│ ├─ ☑ 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
+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
+```
+
+- **Look & feel**: pi coding agent interactive TUI, built on
+  `@earendil-works/pi-tui` 0.84.2 (pinned) — alt-screen scrollable transcript,
+  docked editor/status/footer, markdown messages, slash-command autocomplete.
+- **Slash commands**: dsh's own, untouched. Autocomplete from
+  `ctx.commands.list(agent)`, executed via `ctx.commands.execute(agent, line, signal)`.
+  Verified: `/compact`, `/plan`, `/goal`, `/permission`, `/feedback`. The TUI
+  adds its own surface commands — `/model /think /session /resume /new
+  /settings /export /theme /reload` (see below).
+- **Themes**: GitHub light / GitHub dark palettes (aligned with the
+  `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).
+- **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
+  (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
+  own `dsh-tui-pi:todo-lifecycle` guidance (marker
+  `<!-- dsh-tui-pi:todo-lifecycle -->`) lives in that file, telling the model
+  to write an empty todo list once everything is completed (idempotent,
+  atomic, best-effort; the panel-side all-completed hide remains as fallback).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/model` | pick provider/model — every route the mounted llm services list (pi-ai's built-in catalog + llm-deepseek's static pair). Two-stage picker: choose the model, then a think level when the route exposes one (Esc on stage 2 abandons the whole pick). Live switch with footer sync, persisted as the default. |
+| `/think` | reasoning-effort picker for the current model — `(provider default)` clears the override, then the route's efforts (Off / High / Max …). Live + persisted. |
+| `/session` | read-only info panel: id, cwd, created, model, think level, status, message/tool counts, token usage, event count, parent session. |
+| `/resume` | pick a persisted session (subagent children and the current session are filtered out), validate its log *before* touching the live agent, then restore it — transcript and footer stats rebuild from the stored events. |
+| `/new` | detach the current session and clear the transcript; the next prompt opens a fresh one (the escape hatch when the current history must not follow, e.g. images in it). |
+| `/settings` | text-based settings browser: namespaces grouped into categories (General / Models / Plugins / Agent Presets / Other), schema walk with drill-ins, cycle rows, inline editors (secrets masked), dict add-key, reset-to-defaults. Writes go through the settings mutate chain. |
+| `/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`. |
+| `/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`. |
+
+Anything that is not a resolvable command falls through to the model as an
+ordinary prompt, so dsh packages' commands (and future registrations) appear
+automatically.
+
+### Models: provider-first
+
+`/settings → Models` does not expose the raw `llm-pi-ai` namespace. It lists
+one row per configured provider — label (`displayName` ?? catalog name ??
+route key), value column (first model / `N models` / `catalog` when pi-ai
+serves the route), and one-line API-key state (`API key set` / `missing` /
+`not configured`) probed from the process environment plus the credentials
+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);
+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>`
+   gets `{ apiKeyEnv: <ref> }` through the settings mutate chain (ref derived
+   by convention: route key uppercased, non-alphanumerics → `_`, `_API_KEY`
+   suffix, e.g. `opencode-go → OPENCODE_GO_API_KEY`) and the key is stored via
+   `ctx.credentials.set` — never in `settings.yaml`. Without a credentials
+   service the profile still commits and the UI says
+   `export <REF>=<key> to use it` instead.
+
+### Theme hot-switch
+
+Themes change live, no restart:
+
+- `/theme` (or an edit through `/settings → General → dsh-tui`) commits the
+  preference to the `dsh-tui` settings namespace, which is registered
+  `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.
+- 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).
+
+## APPEND_SYSTEM.md
+
+dsh-tui-pi supports pi's `APPEND_SYSTEM.md` convention on the dsh side:
+**`~/.dsh/APPEND_SYSTEM.md`** (`$DSH_HOME` or `~/.dsh`) is appended to the
+system prompt of every agent this TUI creates. The file is read at each
+prompt assembly, so **edits apply to the very next request** — no restart,
+no reload, no watcher.
+
+- **The file is not shipped with the source**: the repo contains no
+  `APPEND_SYSTEM.md` at its root — it lives in your `~/.dsh` and is yours to
+  edit freely (identity, persona rules, UI conventions — anything you want
+  the model to know). The English **template** the installer seeds from is
+  `templates/APPEND_SYSTEM.md` (the pi orchestrator-identity definition,
+  translated — content lives in that file, not in code).
+- On first run the TUI **creates** the file from the template if missing and
+  **maintains one marked section** in it (`<!-- dsh-tui-pi:todo-lifecycle
+  -->`, telling the model to clear the todo list once everything is
+  completed). Your own content is never touched; the maintenance is
+  idempotent, atomic (tmp + rename) and best-effort.
+- An empty or missing file contributes nothing to the prompt (the section is
+  dropped by the prompt renderer).
+
+## 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
+
+# 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
+```
+
+Both paths auto-add `dsh-tui-pi` to the profile's `dsh.profile.bundles`.
+
+## Use
+
+```sh
+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.
+- `/` 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.
+
+## Performance rules (from the pi-turbo findings)
+
+pi's TUI lags in long sessions because its footer re-scans the whole session
+log on every render (O(n)) and a 1s clock tick recomputes everything.
+dsh-tui-pi avoids both by construction:
+
+- **Event-driven incremental state**: `session/event` listeners maintain an
+  append-only transcript model + running counters (tokens, messages, tools,
+  cache-hit rate). Render never re-scans the dsh session log.
+- **Footer reads O(1) maintained values** — never derived in `render()`.
+- **Clock tick only re-renders the footer line**; transcript components cache.
+- **Live widgets tick at 100 ms** (`AGENT_TICK_MS`, unref'd timer): a tick
+  only re-setTexts the widget's single Text (O(agents)) and is a no-op while
+  no child runs — never a transcript re-scan.
+- **Streaming strategy**: deltas accumulate in a plain Text via `setText` on
+  the same component (never remove+re-add per token); markdown renders once on
+  the assembled `assistant/message` (no per-token markdown parsing).
+- **Configurable think/tool panels** (`dsh-tui.panelHeight`, default `'5'`):
+  `'5'/'7'/'10'` set the total panel rows (top border + header row + body rows
+  + bottom border); `'all'` prints the full body, with bounded on-screen
+  content — a streaming reasoning panel boxes a 200-line live tail while
+  chunks are in flight (the assembled message renders everything) and a
+  settled tool result keeps at most 2000 lines (a `… (+N lines)` marker
+  reports the drop). No inner scroll — pi-tui 0.84.2 never lays out nested
+  components, so a nested ScrollView cannot obtain a viewport. Body lines are
+  clipped to one physical row *before* styling, so long output can never wrap
+  the panel past its configured rows.
+- **Width safety**: every truncation goes through `clipToWidth` (src/text.ts)
+  — CJK full-width characters count 2 columns and graphemes are never split.
+  Bare `String.length` clipping is banned.
+
+## Dev
+
+```sh
+pnpm check    # tsc --noEmit
+pnpm build    # emit lib/
+pnpm test     # unit tests, node --test against lib/ (171 tests, pretest builds)
+```
+
+Local type-checking symlinks `node_modules/@deepseek-ai/*` to the installed
+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/
+```
+
+**pi-tui patch**: this plugin applies a small patch to the pinned
+`@earendil-works/pi-tui` 0.84.2 (`pnpm.patchedDependencies` in
+`pnpm-workspace.yaml`, patch in `patches/`): it adds an `unselectedText`
+SelectListTheme hook (full-row background on unselected rows), wires the
+previously dead `selectedPrefix` hook (accent arrow on the selected row), and
+frames the editor's slash-autocomplete list in a `│` box. The patch travels in
+the tarball (`files` includes `patches` + `pnpm-workspace.yaml`); the
+link:-mounted dev workflow uses the already-patched copy in this repo's
+`node_modules`.
+
+## Layout
+
+```
+bin/dsh-tui-pi      launcher shim (exec dsh --profile tui)
+cordis.patch.yml    bundle patch: mounts the plugin as `tui-pi`
+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
+  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)
+  commands.ts       CommandService: slash autocomplete + dual-channel dispatch
+                    (registerLocal agentless direct / ctx.commands host path)
+  messages.ts       TranscriptRenderer: session events → pi-tui components;
+                    streaming setText, height-configurable panels, ReplayOp
+                    buffer for theme-switch rebuilds
+  footer.ts         PowerlineFooter (ported segment palette, 7 segments + clock)
+  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)
+  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
+                    + preference read/write with conflict retry
+  selectors.ts      /model (two-stage), /think, /theme and /permission picker
+                    overlays
+  permission.ts     permission display names (web-client conventions) + picker
+                    option assembly (pure, unit-tested)
+  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
+  theme/
+    palette.ts      GitHub light/dark palettes + terminal-background detection
+    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)
+```
+
+## Status (2026-08-15)
+
+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.
+
+Known limitations (accepted, pi-tui 0.84.2 constraints):
+
+- **SelectList unselected rows and the SettingsList search row have no
+  background**: unselected rows render as raw `prefix + value` and the search
+  input row is pushed without a theme hook — the popup backdrop is striped
+  rather than one solid surface.
+- **On a 24-row terminal a popup can reach the dock rows**: overlays float
+  over the status/editor area (the frame adds 4 rows on top of the list cap),
+  so the popup bottom border and the status line share screen rows while a
+  popup is open. Cosmetic — popups are modal.
+- **An overlay open at switch time does not follow a theme hot-switch**: the
+  transcript, dock and editor repaint immediately, but an open popup keeps the
+  palette it was built with until it closes (its submenus inherit the same
+  stale bundle).

package/bin/dsh-tui-pi

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+# Convenience launcher: boots the dsh `tui` profile that mounts @aiwayds/dsh-tui-pi.
+# Requires the dsh CLI on PATH and @aiwayds/dsh-tui-pi installed into that profile
+# (dsh plugin --profile tui add @aiwayds/dsh-tui-pi).
+exec dsh --profile tui "$@"

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-tui-pi bundle patch: mounts the pi-style TUI plugin over the profile's
+# base bundle under the stable plugin id `tui-pi`. The plugin renders the
+# terminal UI in-process with @earendil-works/pi-tui and talks to the dsh tree
+# directly (ctx.agents / ctx.commands / session events), keeping dsh's slash
+# commands untouched.
+
+- insert:
+    - id: tui-pi
+      name: '@aiwayds/dsh-tui-pi'

package/lib/append-system.d.ts

@@ -0,0 +1,66 @@
+/**
+ * APPEND_SYSTEM.md support — pi's convention (`~/.pi/agent/APPEND_SYSTEM.md`),
+ * dsh side: `~/.dsh/APPEND_SYSTEM.md`. A user-editable file whose content is
+ * appended to the system prompt of every agent this TUI creates. The TUI
+ * registers a system-prompt section whose text provider reads the file at
+ * each assembly, so edits apply to the very next request — no restart, no
+ * watcher.
+ *
+ * The TUI seeds a fresh file at first run (`ensureAppendSystemFile`) from
+ * the shipped template `templates/APPEND_SYSTEM.md` (the user's pi
+ * orchestrator-identity definition in English — content lives in the FILE,
+ * not in code), then maintains its marked todo-lifecycle section. An
+ * existing file is user-owned — the TUI only maintains its marker section
+ * there, idempotently (marker `<!-- dsh-tui-pi:todo-lifecycle -->`),
+ * atomically (tmp + rename) and best-effort — a failure is contained and
+ * reported, never breaks TUI startup. `migrateAgentsMdTodoSection` removes
+ * the todo section's earlier incarnation from `~/.dsh/AGENTS.md` (the
+ * pre-APPEND_SYSTEM.md delivery channel) so the guidance is not delivered
+ * twice.
+ */
+/** Idempotency marker for the TUI-owned section of the append file. */
+export declare const TODO_LIFECYCLE_MARKER = "<!-- dsh-tui-pi:todo-lifecycle -->";
+/**
+ * The TUI-owned section: the model must clear the todo list when the work is
+ * done, because `todo/write` is a whole-list snapshot (last-write-wins) and
+ * an all-completed list would stay pinned above the chat input.
+ */
+export declare const TODO_LIFECYCLE_SECTION = "<!-- dsh-tui-pi:todo-lifecycle -->\n## Todo list lifecycle (dsh-tui-pi)\n\nThe UI renders your todo list as a fixed panel above the chat input. Keep\nitems `pending` or `in_progress` while they are not done. When EVERY todo is\ncompleted \u2014 no pending or in-progress items remain \u2014 write an EMPTY todo list\n(`todos: []`) so the panel clears. Never leave a fully-completed list behind.\n";
+/** The user-editable append file path (`$DSH_HOME/APPEND_SYSTEM.md`). */
+export declare function appendSystemPath(home?: string): string;
+/**
+ * The shipped English template (`templates/APPEND_SYSTEM.md`): the user's pi
+ * orchestrator-identity definition translated to English. The content lives
+ * in this FILE, not in code — installation seeds `~/.dsh/APPEND_SYSTEM.md`
+ * from it (a fresh file only; existing files are user-owned).
+ */
+export declare function appendSystemTemplatePath(): string;
+/**
+ * Synchronous read for the system-prompt section provider (the provider
+ * signature is sync; the file is small and read once per assembly).
+ * @returns the file content, or '' when missing/unreadable — an empty
+ *   section is dropped by the prompt renderer.
+ */
+export declare function readAppendSystem(path?: string): string;
+/**
+ * Ensure the append file exists with the shipped template and the TUI's
+ * marked todo-lifecycle section: a missing file is seeded from
+ * `templates/APPEND_SYSTEM.md` (the English orchestrator template) followed
+ * by the marked section; an existing file is user-owned — only the marked
+ * section is appended when its marker is missing, and a marked file is left
+ * untouched.
+ * @param path - target file (injectable for tests).
+ * @param templatePath - the shipped template (injectable for tests).
+ * @returns an error message on failure, undefined on success (including the
+ *   no-op case where the marker is already present).
+ */
+export declare function ensureAppendSystemFile(path?: string, templatePath?: string): Promise<string | undefined>;
+/**
+ * Migration: strip the TUI-owned todo-lifecycle block from `~/.dsh/AGENTS.md`
+ * (the earlier delivery channel). No-op when the marker is absent; the file
+ * is deleted when the strip leaves it empty. The block is removed by exact
+ * content match, so a user-edited block is left alone (best-effort). Every
+ * write here is atomic and failure-contained.
+ * @returns an error message on failure, undefined on success or no-op.
+ */
+export declare function migrateAgentsMdTodoSection(path?: string): Promise<string | undefined>;

package/lib/append-system.js

@@ -0,0 +1,161 @@
+/**
+ * APPEND_SYSTEM.md support — pi's convention (`~/.pi/agent/APPEND_SYSTEM.md`),
+ * dsh side: `~/.dsh/APPEND_SYSTEM.md`. A user-editable file whose content is
+ * appended to the system prompt of every agent this TUI creates. The TUI
+ * registers a system-prompt section whose text provider reads the file at
+ * each assembly, so edits apply to the very next request — no restart, no
+ * watcher.
+ *
+ * The TUI seeds a fresh file at first run (`ensureAppendSystemFile`) from
+ * the shipped template `templates/APPEND_SYSTEM.md` (the user's pi
+ * orchestrator-identity definition in English — content lives in the FILE,
+ * not in code), then maintains its marked todo-lifecycle section. An
+ * existing file is user-owned — the TUI only maintains its marker section
+ * there, idempotently (marker `<!-- dsh-tui-pi:todo-lifecycle -->`),
+ * atomically (tmp + rename) and best-effort — a failure is contained and
+ * reported, never breaks TUI startup. `migrateAgentsMdTodoSection` removes
+ * the todo section's earlier incarnation from `~/.dsh/AGENTS.md` (the
+ * pre-APPEND_SYSTEM.md delivery channel) so the guidance is not delivered
+ * twice.
+ */
+import { readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Idempotency marker for the TUI-owned section of the append file. */
+export const TODO_LIFECYCLE_MARKER = '<!-- dsh-tui-pi:todo-lifecycle -->';
+/**
+ * The TUI-owned section: the model must clear the todo list when the work is
+ * done, because `todo/write` is a whole-list snapshot (last-write-wins) and
+ * an all-completed list would stay pinned above the chat input.
+ */
+export const TODO_LIFECYCLE_SECTION = `${TODO_LIFECYCLE_MARKER}
+## Todo list lifecycle (dsh-tui-pi)
+
+The UI renders your todo list as a fixed panel above the chat input. Keep
+items \`pending\` or \`in_progress\` while they are not done. When EVERY todo is
+completed — no pending or in-progress items remain — write an EMPTY todo list
+(\`todos: []\`) so the panel clears. Never leave a fully-completed list behind.
+`;
+/** Default harness home: `$DSH_HOME` or `~/.dsh`. */
+function dshHome() {
+    return process.env.DSH_HOME ?? join(homedir(), '.dsh');
+}
+/** The user-editable append file path (`$DSH_HOME/APPEND_SYSTEM.md`). */
+export function appendSystemPath(home = dshHome()) {
+    return join(home, 'APPEND_SYSTEM.md');
+}
+/**
+ * The shipped English template (`templates/APPEND_SYSTEM.md`): the user's pi
+ * orchestrator-identity definition translated to English. The content lives
+ * in this FILE, not in code — installation seeds `~/.dsh/APPEND_SYSTEM.md`
+ * from it (a fresh file only; existing files are user-owned).
+ */
+export function appendSystemTemplatePath() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), '..', 'templates', 'APPEND_SYSTEM.md');
+}
+/** The user-global AGENTS.md path (the legacy delivery channel). */
+function agentsMdPath(home = dshHome()) {
+    return join(home, 'AGENTS.md');
+}
+/**
+ * Synchronous read for the system-prompt section provider (the provider
+ * signature is sync; the file is small and read once per assembly).
+ * @returns the file content, or '' when missing/unreadable — an empty
+ *   section is dropped by the prompt renderer.
+ */
+export function readAppendSystem(path = appendSystemPath()) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Ensure the append file exists with the shipped template and the TUI's
+ * marked todo-lifecycle section: a missing file is seeded from
+ * `templates/APPEND_SYSTEM.md` (the English orchestrator template) followed
+ * by the marked section; an existing file is user-owned — only the marked
+ * section is appended when its marker is missing, and a marked file is left
+ * untouched.
+ * @param path - target file (injectable for tests).
+ * @param templatePath - the shipped template (injectable for tests).
+ * @returns an error message on failure, undefined on success (including the
+ *   no-op case where the marker is already present).
+ */
+export async function ensureAppendSystemFile(path = appendSystemPath(), templatePath = appendSystemTemplatePath()) {
+    let existing;
+    try {
+        existing = await readFile(path, 'utf8');
+    }
+    catch {
+        existing = '';
+    }
+    if (existing.includes(TODO_LIFECYCLE_MARKER))
+        return undefined;
+    if (existing !== '') {
+        return writeAtomically(path, `${existing.replace(/\s+$/u, '')}\n\n${TODO_LIFECYCLE_SECTION}`);
+    }
+    // Fresh file: seed from the shipped template, then the marked section. A
+    // missing template (broken tarball) degrades to the marked section alone.
+    let template;
+    try {
+        template = await readFile(templatePath, 'utf8');
+    }
+    catch {
+        template = '';
+    }
+    const seed = template === '' ? TODO_LIFECYCLE_SECTION : `${template.replace(/\s+$/u, '')}\n\n${TODO_LIFECYCLE_SECTION}`;
+    return writeAtomically(path, seed);
+}
+/**
+ * Migration: strip the TUI-owned todo-lifecycle block from `~/.dsh/AGENTS.md`
+ * (the earlier delivery channel). No-op when the marker is absent; the file
+ * is deleted when the strip leaves it empty. The block is removed by exact
+ * content match, so a user-edited block is left alone (best-effort). Every
+ * write here is atomic and failure-contained.
+ * @returns an error message on failure, undefined on success or no-op.
+ */
+export async function migrateAgentsMdTodoSection(path = agentsMdPath()) {
+    let content;
+    try {
+        content = await readFile(path, 'utf8');
+    }
+    catch {
+        return undefined; // no AGENTS.md — nothing to migrate
+    }
+    if (!content.includes(TODO_LIFECYCLE_MARKER))
+        return undefined;
+    const next = content.trim() === TODO_LIFECYCLE_SECTION.trim()
+        ? ''
+        : content.split(TODO_LIFECYCLE_SECTION).join('').replace(/\n{3,}/gu, '\n\n').trim();
+    if (next === '') {
+        try {
+            await unlink(path);
+        }
+        catch (error) {
+            return error instanceof Error ? error.message : String(error);
+        }
+        return undefined;
+    }
+    return writeAtomically(path, `${next}\n`);
+}
+/** Atomic write (tmp + rename); the tmp file is cleaned up on failure. */
+async function writeAtomically(path, content) {
+    const tmp = `${path}.tmp`;
+    try {
+        await writeFile(tmp, content, 'utf8');
+        await rename(tmp, path);
+        return undefined;
+    }
+    catch (error) {
+        try {
+            await unlink(tmp);
+        }
+        catch { /* already gone */ }
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+//# sourceMappingURL=append-system.js.map

package/lib/append-system.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"append-system.js","sourceRoot":"","sources":["../src/append-system.ts"],"names":[],"mappings":"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"}

package/lib/commands.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Slash-command integration with dsh's own command registry.
+ *
+ * dsh-tui-pi never re-implements a command: autocomplete lists
+ * `ctx.commands.list(agent)` and submission routes through
+ * `ctx.commands.execute(agent, line, signal)`. Anything that is not a
+ * resolvable command falls through to the model as an ordinary prompt, so
+ * every command registered by dsh packages (plan, compact, feedback, export,
+ * permission, goal, …) works here unchanged and future registrations appear
+ * automatically.
+ *
+ * One exemption: TUI-owned commands that never touch the receiving agent
+ * (model pickers, settings browser, session info/resume) are dispatched
+ * locally when no live agent exists — dsh's execute path addresses an agent
+ * and would mint a throwaway session just to run them.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type CommandDescriptor, type CommandResult } from '@deepseek-ai/dsh-commands';
+import type { AutocompleteProvider } from '@earendil-works/pi-tui';
+import type { DshSessionBridge } from './session.ts';
+/** A TUI-owned command body that needs no receiving agent. */
+export type LocalCommandHandler = (rawInput: string, signal: AbortSignal) => CommandResult | Promise<CommandResult>;
+export declare class CommandService {
+    private readonly ctx;
+    private readonly bridge;
+    /** TUI-owned command bodies, dispatchable without a live agent. */
+    private readonly local;
+    constructor(ctx: Context, bridge: DshSessionBridge);
+    /**
+     * Register a local command body (the same handler the ctx.commands
+     * registration wraps). It is dispatched directly when no live agent
+     * exists, avoiding a throwaway session for agentless commands.
+     */
+    registerLocal(name: string, handler: LocalCommandHandler): void;
+    /**
+     * Try to run `line` as a dsh slash command.
+     * @returns `handled: true` when the line was admitted as a command (the
+     *   caller must not forward it to the model), with an optional `error` or
+     *   success `text` to surface; `handled: false` when it is not a command.
+     */
+    tryExecute(line: string, signal: AbortSignal): Promise<{
+        handled: boolean;
+        error?: string;
+        text?: string;
+    }>;
+    /**
+     * Effective command descriptors for the current agent. Warms the session on
+     * first use so `/` autocompletes before any prompt was sent.
+     */
+    list(): Promise<readonly CommandDescriptor[]>;
+    /** pi-tui autocomplete provider over the live command registry. */
+    autocompleteProvider(): AutocompleteProvider;
+}