@aiwayds/dsh-tui-pi 0.18.1 → 0.19.1

package/README.md

@@ -2,21 +2,22 @@
 
 pi-style terminal UI for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) — a plugin suite that turns dsh into a pi-like coding agent experience.
 
-**Compatibility:** dsh `0.1.0-rc.7` and `0.1.0-rc.8`. Slash-command execution
-adapts to both `dsh-commands` `execute()` signatures at runtime (rc.8 added an
-`images` parameter before `signal`; the TUI detects the arity and calls either
-form). Verified under rc.8 by unit tests plus a live tmux e2e smoke; the rc.7
-call path is identical to the pre-rc.8 direct invocation.
+**Compatibility:** tested against dsh `0.1.1-rc.2`. Slash-command execution goes
+through an `executeCommand()` compat shim (`src/commands.ts`) that probes the
+arity of `dsh-commands`' `execute()` at runtime — supporting both the pre-rc.8
+3-arg form `(agent, line, signal)` and the current 4-arg form
+`(agent, line, images, signal)`, unchanged since `0.1.0-rc.8`. Verified by unit
+tests plus a live tmux e2e smoke.
 
 > 中文说明: [README.zh.md](README.zh.md)
 
 ## Screenshot
 
-![dsh-tui-pi demo](./dsh-tui-pi-demo.gif)
+https://github.com/user-attachments/assets/6a7e00bb-1fd0-4bc5-9070-457f1e9fa54d
 
-A live terminal recording of a session — todos, running subagents, think/tool
-panels and the powerline footer in action. ([Interactive playback on
-asciinema](https://asciinema.org/a/BE212ZO8x1zEZyZn))
+A live terminal recording of a session (MP4, 1.5× speed) — todos, running
+subagents, think/tool panels and the powerline footer in action.
+([Interactive playback on asciinema](https://asciinema.org/a/BE212ZO8x1zEZyZn))
 
 ### Layout overview
 
@@ -156,7 +157,7 @@ Two caps (`/agents` → `l` to configure):
 dsh plugin --profile tui add @aiwayds/dsh-dcp
 ```
 
-Once mounted, DCP runs transparently in the background. The footer's **context** segment prices the current occupancy — the latest request's billed context plus a CJK estimate of messages after it — so after a compaction the next request lands smaller and the display follows it down (the percent is capped at 100, the window being a hard ceiling). The **cache-hit** segment reflects the session's cumulative cache reuse.
+Once mounted, DCP runs transparently in the background. The footer's **context** segment prices the current occupancy — the latest request's billed context plus a CJK estimate of messages after it — so after a compaction the next request lands smaller and the display follows it down (the percent is capped at 100, the window being a hard ceiling). The **cache-hit** segment reflects the current provider/model route's cache reuse — the rate is computed per route segment and restarts (hiding until the next billed message) when the provider or model changes.
 
 Inside a subagent, a committed compaction is visible too: DCP appends one `user/message` **notice** row per compaction on the child's own log, and the Ctrl+G transcript renders it with a `🧹` marker (distinct from the generic `ⓘ`), with the picker rows carrying the per-child compaction count (`🧹 N×` in the description). Both DCP's `roundInterval` and the TUI's `maxRounds` count the **same** thing — `assistant/message` events, one per LLM round-trip — but act differently: the TUI queues one wrap-up request once a child's count reaches `maxRounds`, while DCP compacts (prunes context) at the next idle boundary once a session's count reaches `roundInterval`. One triggers work, the other frees context.
 
@@ -389,7 +390,7 @@ dsh --profile tui        # or: dsh-tui-pi (bin shim)
 ```sh
 pnpm check    # tsc --noEmit
 pnpm build    # emit lib/
-pnpm test     # unit tests, node --test against lib/ (654 tests, pretest builds)
+pnpm test     # unit tests, node --test against lib/ (677 tests, pretest builds)
 ```
 
 Local type-checking symlinks `node_modules/@deepseek-ai/*` to the installed
@@ -424,7 +425,7 @@ src/
   ask-user.ts         Ask User Question overlay: pure state reducers +
                       framed overlay UI + ctx.userQuestions provider
   theme/              GitHub light/dark palettes + terminal detection
-test/*.test.mjs       unit tests (654 across 40 files)
+test/*.test.mjs       unit tests (677 across 40 files)
 ```
 
 ---

package/README.zh.md

@@ -2,15 +2,19 @@
 
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) 的 pi 风格终端 UI 插件 —— 把 dsh 变成 pi 风格的编码代理体验。
 
-**兼容性**：支持 dsh `0.1.0-rc.7` 与 `0.1.0-rc.8`。斜杠命令执行在运行时自适应两个版本的 `dsh-commands` `execute()` 签名（rc.8 在 `signal` 前插入了 `images` 参数；TUI 探测参数个数后按对应形式调用）。rc.8 下经单元测试 + tmux 真机冒烟验证；rc.7 调用路径与升级前的直接调用完全一致。
+**兼容性**：针对 dsh `0.1.1-rc.2` 测试。斜杠命令执行经过 `executeCommand()`
+兼容 shim（`src/commands.ts`），在运行时探测 `dsh-commands` `execute()` 的参数
+个数——同时支持 rc.8 之前的 3 参形式 `(agent, line, signal)` 与当前的 4 参形式
+`(agent, line, images, signal)`（自 `0.1.0-rc.8` 起未再变化）。经单元测试 +
+tmux 真机冒烟验证。
 
 > English version: [README.md](README.md)
 
 ## 截图
 
-![dsh-tui-pi 演示](./dsh-tui-pi-demo.gif)
+https://github.com/user-attachments/assets/6a7e00bb-1fd0-4bc5-9070-457f1e9fa54d
 
-真实会话的终端录制——Todos、运行中的 subagent、思考/工具面板和 powerline footer 一览。（[asciinema 交互播放](https://asciinema.org/a/BE212ZO8x1zEZyZn)）
+真实会话的终端录制（MP4，1.5× 速度）——Todos、运行中的 subagent、思考/工具面板和 powerline footer 一览。（[asciinema 交互播放](https://asciinema.org/a/BE212ZO8x1zEZyZn)）
 
 ### 布局总览
 

package/lib/ask-user.d.ts

@@ -7,16 +7,27 @@
  * `AskUserQuestionAnswer` envelope back to `dsh-tool-ask-user` as a normal
  * tool result.
  *
- * Layout — one framed overlay, all questions flattened:
+ * Layout — one framed overlay, all questions flattened (numbered rows, a
+ * divider between each question block and its options, and a scroll window
+ * so the cursor row is always visible even when the overlay is height-capped):
  *
- *   ● Question 1
- *     Where should we deploy?   (left = header / right = question text)
- *     ▸ staging
- *       production
- *       Type something.          (sentinel row — inline input)
- *     Question 2 ···            (continues vertically)
- *     ▸ …
- *     ⏎ Confirm answers        (when ≥ 2 questions, or any multiSelect question)
+ *   ● Questions (2)
+ *     Fruit  Where should we deploy?      (header — not selectable)
+ *     ─────────────────────────────        (divider)
+ *     ▸ 1. staging                        (cursor marker + per-question number)
+ *       2. production
+ *          red and round                  (option description, own muted line)
+ *       3. Type something.                (sentinel row — inline input)
+ *     Vehicle  Pick a vehicle ···         (continues vertically)
+ *     ⏎ Confirm answers                   (when ≥ 2 questions, or any multiSelect)
+ *
+ * The body renders through a scroll window sized from the live terminal
+ * height (`askUserMaxVisibleForRows`; falls back to `ASK_USER_MAX_VISIBLE`
+ * when the terminal row count is unknown):
+ * pi-tui hard-clips overlay tails at `maxHeight`, so without an inner window
+ * the last options fall off-screen while the cursor can still reach them
+ * ("unselectable" bug). The window slides with the cursor and the footer
+ * gains a `(n/m)` position readout while content overflows.
  *
  * Single-question single-select overlay: Enter on an option (or committing a
  * filled sentinel) submits immediately. A multiSelect question — even a lone
@@ -61,6 +72,26 @@ export declare const SENTINEL_LABEL = "Type something.";
 export declare const DECLINE_MESSAGE = "User declined to answer questions.";
 /** Transient hint when Enter lands on an incomplete confirm/submit row. */
 export declare const INCOMPLETE_HINT = "Answer every question first";
+/**
+ * Fallback visible body-line cap for the questions/review panes, used only
+ * when the terminal row count is unknown (fake TUIs in tests, exotic
+ * terminals). Derived for a 24-row terminal (the e2e matrix floor): 80%
+ * maxHeight = 19 framed lines − 2 frame borders = 17 content lines, and
+ * title(1) + table chrome(3) + 9 body lines + bottom rule + blank + footer
+ * = 16, leaving one line of headroom for a hint. The live path derives the
+ * window from the real terminal height via `askUserMaxVisibleForRows`.
+ */
+export declare const ASK_USER_MAX_VISIBLE = 9;
+/**
+ * Derive the scroll-window size from the terminal height so the window grows
+ * with the terminal instead of pinning to the conservative 24-row budget:
+ * pi-tui hard-clips the framed overlay at its resolved maxHeight, so body
+ * lines beyond `budget − ASK_USER_VIEW_OVERHEAD` would be invisible anyway.
+ * At the 24-row e2e floor this yields exactly ASK_USER_MAX_VISIBLE (9);
+ * larger terminals scale up proportionally. Without a usable row count it
+ * degrades to ASK_USER_MAX_VISIBLE.
+ */
+export declare function askUserMaxVisibleForRows(termRows: number | undefined, maxHeight?: AskUserPanelDeps['maxHeight']): number;
 /** A row in the multi-question view. */
 export interface FlatRow {
     kind: 'question-header' | 'option' | 'sentinel' | 'confirm';
@@ -80,7 +111,14 @@ export interface PendingAnswer {
     /** Free-text answer from the sentinel path. Optional — set only when the user typed. */
     custom?: string;
 }
-/** Whole-state of one AskUser overlay. All setters are pure reducers. */
+/**
+ * Whole-state of one AskUser overlay. All setters are pure reducers — with
+ * ONE deliberate exception: the render pass writes the clamped scroll offset
+ * back into `questionsScroll`/`reviewScroll` (see `clampScrollWindow`). The
+ * clamp depends on the rendered body height, which only exists at render
+ * time; persisting it here makes navigation slide smoothly instead of
+ * snapping, and direct render calls simply start from offset 0.
+ */
 export interface AskUserState {
     questions: readonly AskUserQuestionItem[];
     /** Per-question pending answer. */
@@ -101,6 +139,10 @@ export interface AskUserState {
     cancelHint: boolean;
     /** Transient "you can't do that yet" hint (e.g. Enter on an incomplete confirm row). Cleared by any navigation. */
     attentionHint: string | null;
+    /** Questions-pane scroll offset in rendered body lines (clamped by the render pass, see `clampScrollWindow`). */
+    questionsScroll: number;
+    /** Review-pane scroll offset in rendered rows (same mechanism). */
+    reviewScroll: number;
 }
 /** Initial state for a `questions` payload — defaults: cursor on Q0/option-0, no edit, no Esc history. */
 export declare function initialState(questions: readonly AskUserQuestionItem[]): AskUserState;
@@ -112,7 +154,14 @@ export declare function setCustomAnswer(state: AskUserState, questionIndex: numb
 export declare function patchCustomInput(state: AskUserState, questionIndex: number, mutator: (current: string) => string): AskUserState;
 /** Enter inline-edit mode for a question (sentinel row got pressed). */
 export declare function enterCustomEdit(state: AskUserState, questionIndex: number): AskUserState;
-/** Leave inline-edit mode; commit when `commit === true` and the buffer is non-empty. */
+/**
+ * Leave inline-edit mode; commit when `commit === true` and the buffer is
+ * non-empty. Intentionally NEVER triggers auto-submit on its own: submission
+ * decisions live exclusively with the callers (`commitCustomAnswer` after an
+ * Enter commit, plain navigation after the ↑↓ arrow-exit path), so exiting
+ * the editor — especially via arrow keys mid-multi-question flow — can never
+ * settle the overlay as a side effect.
+ */
 export declare function exitCustomEdit(state: AskUserState, commit: boolean): AskUserState;
 /**
  * Double-Esc state machine: 1st press arms; 2nd within the window fires
@@ -134,6 +183,32 @@ export declare function buildRowList(questions: readonly AskUserQuestionItem[],
 export declare function nextSelectableIndex(rows: readonly FlatRow[], from: number, direction: 1 | -1): number;
 /** True when every question has at least one selected option or a non-empty custom answer. */
 export declare function allQuestionsAnswered(state: AskUserState): boolean;
+/**
+ * Fold newlines (and the whitespace around them) into single spaces so a
+ * label can never break a table row into two rendered lines. Width clipping
+ * still happens later via `clipToWidth`.
+ */
+export declare function foldText(text: string): string;
+/**
+ * The scroll offset that keeps `cursor` inside `[offset, offset + visibleRows)`
+ * for a body of `length` rendered lines — same contract as skills.ts's
+ * `clampScrollOffset`, kept local so ask-user scrolling is self-contained.
+ * Pure; an empty body or non-positive window pins to 0.
+ */
+export declare function clampScrollWindow(cursor: number, visibleRows: number, length: number, currentOffset: number): number;
+/**
+ * 1-based per-question number of the selectable row at `index`: options count
+ * `1..N` inside their question and the sentinel continues after them (`N+1`).
+ * Header rows and the confirm pseudo-row are unnumbered (null). Pure so both
+ * the renderer and tests share one numbering vocabulary.
+ */
+export declare function rowNumber(rows: readonly FlatRow[], index: number): number | null;
+/**
+ * Inverse of `rowNumber` for the digit quick-pick: the index of the `n`-th
+ * numbered row belonging to question `qi`, or -1 when out of range. Rows are
+ * scanned in display order, so options come before the question's sentinel.
+ */
+export declare function rowIndexForNumber(rows: readonly FlatRow[], qi: number, n: number): number;
 /**
  * Whether the overlay needs an explicit `⏎ Confirm answers` row: any
  * multi-question layout, plus a lone multiSelect question — multiSelect can
@@ -153,10 +228,10 @@ export declare function canAutoSubmit(state: AskUserState): boolean;
  * later question is already answered (caller keeps the current cursor).
  */
 export declare function nextUnansweredRow(rows: readonly FlatRow[], perQuestion: readonly PendingAnswer[], answeredQi: number): number;
-/** Render the questions pane as a flat table line list. */
-export declare function renderQuestionsView(theme: TuiTheme, state: AskUserState, width: number): string[];
-/** Render the review page for multi-question overlays. */
-export declare function renderReviewView(theme: TuiTheme, state: AskUserState, width: number): string[];
+/** Render the questions pane as a flat table line list behind a scroll window. */
+export declare function renderQuestionsView(theme: TuiTheme, state: AskUserState, width: number, maxVisible?: number): string[];
+/** Render the review page for multi-question overlays (scroll-windowed). */
+export declare function renderReviewView(theme: TuiTheme, state: AskUserState, width: number, maxVisible?: number): string[];
 /** Options for assembling the panel + provider function. */
 export interface AskUserPanelDeps {
     tui: TUI;