@aiwayds/dsh-tui-pi 0.17.0 → 0.18.0

package/README.md

@@ -162,6 +162,55 @@ Inside a subagent, a committed compaction is visible too: DCP appends one `user/
 
 ---
 
+### APPEND_SYSTEM.md
+
+A user-editable markdown file whose content is appended to the **system prompt of the main agent this TUI creates** — borrows pi's `~/.pi/agent/APPEND_SYSTEM.md` convention, dsh side: `$DSH_HOME/APPEND_SYSTEM.md` (default `~/.dsh/APPEND_SYSTEM.md`, honors the same `$DSH_HOME` override as the rest of dsh).
+
+- **Hot-applied** — the section provider reads the file at every prompt assembly, so editing the file picks up on the **next request**: no restart, no watcher, no `/reload`.
+- **Auto-seeded on first run** — when the file is missing, the TUI seeds it once at startup from the shipped template `templates/APPEND_SYSTEM.md` (the English orchestrator-identity template: identity, core rules, execution workflow). An existing file is yours — the TUI never overwrites user content.
+- **TUI-owned section** — a marked block (`<!-- dsh-tui-pi:todo-lifecycle -->`) is appended once and then maintained idempotently so the model clears its `todo/write` list when every item is done. A marked file is left byte-identical on later startups.
+- **Legacy migration** — the same todo block used to be delivered through `~/.dsh/AGENTS.md`. On startup the TUI strips that block once (no-op when absent), so the guidance is never duplicated.
+- **Empty / unreadable = no section** — if the file is missing or can't be read, the section is silently dropped. No error, no TUI startup failure.
+
+#### Scope: main agent only
+
+The section is registered on the main agent's **scoped** agent context (`installAppendSystem` in `src/session.ts`) — it lands in that agent's own prompt-scope layer, which subagent scopes never merge. An orchestrator identity ("dispatch sub-agents, never execute yourself") riding on the children would defeat its own purpose, so children see nothing from this file. The mechanism is the same one `dsh-subagent-registry` uses for per-child personas.
+
+#### Example
+
+```sh
+# Auto-seeded on first run from templates/APPEND_SYSTEM.md — open and edit.
+$EDITOR ~/.dsh/APPEND_SYSTEM.md
+
+# Or replace with your own from scratch (the TUI still keeps its marked
+# todo-lifecycle section — it gets re-appended when missing).
+cat > ~/.dsh/APPEND_SYSTEM.md <<'EOF'
+# Project ground rules
+
+- Always run `pnpm test` before claiming a task is done.
+- Prefer dispatching `workhorse` for multi-step investigations.
+EOF
+```
+
+There's no slash command to toggle the feature — it's always on, controlled by the file's contents.
+
+---
+
+### Ask User Question
+
+While the model is mid-turn it can pause and ask you structured questions via the `ask_user_question` tool (`@deepseek-ai/dsh-tool-ask-user`, mounted by this profile's bundle patch). The TUI hosts the answering side: a framed overlay opens in place, the tool call stays pending until you answer, and your answers flow back to the model as a normal tool result.
+
+- **One overlay, all questions flattened** — every question renders as a header row followed by its supporting `detail` text (when the model supplies any), option rows, plus a `Type something.` sentinel row for free text. Single-select replaces on Enter; multi-select toggles (`[+]` marks).
+- **Single-question fast path** — a lone single-select question submits immediately on Enter: picking an option or committing typed free text both submit right away (a question without options is answered by typing alone). A lone multiSelect question instead gets a `⏎ Confirm answers` row so you can pick several options before submitting.
+- **Multi-question review page** — with ≥ 2 questions a `⏎ Confirm answers` row hops to a review listing every answer, each row editable in place; `Submit answers` commits (Enter on it while an answer is missing flashes a hint instead of failing silently). After committing free text on one question the cursor hops to the next unanswered one.
+- **Double-Esc declines** — two Esc presses within 200 ms return a declined envelope (the model reads it as a normal reply that no answer was given); holding Esc does not accidentally fire (key auto-repeat below a minimum gap is ignored), and closing the overlay through any other path — theme swap, `/reload`, or the tool call being aborted — settles as declined too.
+- **Conservative-use guidance** — a system-prompt section nudges the model to ask only when it genuinely needs you (1–3 questions, 2–4 options each), so the TUI doesn't turn into a questionnaire.
+- **Keyboard** — `↑↓` navigate · `Enter` select/toggle/confirm · type into the sentinel for free text · `Esc` twice to decline.
+
+Inspired by [juicesharp/rpiv-ask-user-question](https://github.com/juicesharp/rpiv-ask-user-question).
+
+---
+
 ## Slash commands
 
 | Command | What it does |
@@ -340,7 +389,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/ (569 tests, pretest builds)
+pnpm test     # unit tests, node --test against lib/ (652 tests, pretest builds)
 ```
 
 Local type-checking symlinks `node_modules/@deepseek-ai/*` to the installed
@@ -372,8 +421,10 @@ src/
   editor.ts           CwdBorderEditor (top border: cwd + git branch)
   subagent-policy.ts  maxAgents guard + maxRounds wrap-up injection
   subagent-viewer.ts  Ctrl+G picker + live transcript panel + Enter steer injection
+  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 (569 across 38 files)
+test/*.test.mjs       unit tests (652 across 39 files)
 ```
 
 ---
@@ -381,3 +432,14 @@ test/*.test.mjs       unit tests (569 across 38 files)
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for the release history.
+
+---
+
+## Credits
+
+- [Ask User Question](#ask-user-question) is inspired by
+  [juicesharp/rpiv-ask-user-question](https://github.com/juicesharp/rpiv-ask-user-question) —
+  the interaction design (flattened option list with a free-text sentinel,
+  multi-question review page, decline gesture) was adapted to this TUI's
+  framed-overlay and dsh `userQuestions` provider architecture. All code here
+  is original.

package/README.zh.md

@@ -154,6 +154,40 @@ dsh plugin --profile tui add @aiwayds/dsh-dcp
 
 ---
 
+### APPEND_SYSTEM.md
+
+一份用户可编辑的 markdown 文件，内容会**追加到 TUI 创建的主代理的系统提示末尾** —— 借鉴 pi 的 `~/.pi/agent/APPEND_SYSTEM.md` 约定，dsh 侧对应 `$DSH_HOME/APPEND_SYSTEM.md`（默认 `~/.dsh/APPEND_SYSTEM.md`，沿用 dsh 其余部分共用的 `$DSH_HOME` 覆盖）。
+
+- **热应用** —— section 提供者在每次组装提示词时读盘，改完文件**下一次请求**即生效：无需重启、无需 watcher、无需 `/reload`。
+- **首次启动自动播种** —— 文件不存在时，TUI 在启动时一次性从随包模板 `templates/APPEND_SYSTEM.md`（英文版协调者身份模板：身份、核心规则、执行工作流）创建。已有文件归用户所有 —— TUI 永远不会覆盖用户内容。
+- **TUI 自有段落** —— 一段带标记的 block（`<!-- dsh-tui-pi:todo-lifecycle -->`）只在缺失时追加一次，并保持幂等，确保模型在所有 todo 都完成时清空 `todo/write` 列表。已带标记的文件后续启动原样保留。
+- **旧版迁移** —— 同一段 todo block 早期通过 `~/.dsh/AGENTS.md` 下发。启动时 TUI 一次性把它剥掉（无标记时 no-op），避免重复下发。
+- **空 / 读不到 = 不挂载该 section** —— 文件缺失或读不了时该 section 被静默丢弃，无报错、不影响 TUI 启动。
+
+#### 作用范围：仅限主代理
+
+该 section 注册在主代理**带作用域**的 agent context 上（`src/session.ts` 里的 `installAppendSystem`）—— 落在该 agent 自己的 prompt-scope 层，子代理的 scope 不会合并。协调者身份（「调度子代理、不要自己执行」）如果下发到子代理会自废武功，所以子代理完全看不到这个文件。机制与 `dsh-subagent-registry` 给每个子代理设置人设时相同。
+
+#### 示例
+
+```sh
+# 首次启动从 templates/APPEND_SYSTEM.md 自动播种 —— 直接打开编辑即可。
+$EDITOR ~/.dsh/APPEND_SYSTEM.md
+
+# 或者完全替换为自己的版本（TUI 仍会保留它的标记 todo-lifecycle section，
+# 缺失时会重新追加）。
+cat > ~/.dsh/APPEND_SYSTEM.md <<'EOF'
+# 项目约定
+
+- 任何任务都先跑 `pnpm test` 再声称完成。
+- 多步调研优先派发给 `workhorse` 子代理。
+EOF
+```
+
+该功能没有开关斜杠命令 —— 它始终启用，完全由文件内容控制。
+
+---
+
 ## 斜杠命令
 
 | 命令 | 功能 |

package/cordis.patch.yml

@@ -8,7 +8,15 @@
 # its own bundle patch (@aiwayds/dsh-dcp/cordis.patch.yml). Adding dsh-dcp to
 # the profile's bundles mounts it; mounting it here too would duplicate the
 # entry id and crash the loader.
+#
+# dsh-tool-ask-user is mounted here: the upstream tool is a soft-linked
+# closure dependency (not a regular npm dep) and needs an explicit entry in
+# the bundle to be wired into the model-facing tool catalog. Without this
+# insert, the `ask_user_question` tool never registers with the model and
+# the user-questions seam has no visible surface in this profile.
 
 - insert:
     - id: tui-pi
       name: '@aiwayds/dsh-tui-pi'
+    - id: tool-ask-user
+      name: '@deepseek-ai/dsh-tool-ask-user'

package/lib/ask-user.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Ask the human a question while the model is mid-turn.
+ *
+ * Wires the upstream `ctx.userQuestions` capability seam (`dsh-user-questions`)
+ * with a terminal-side UI: an in-place multi-question overlay that pauses the
+ * tool call until the human answers, then feeds the canonical
+ * `AskUserQuestionAnswer` envelope back to `dsh-tool-ask-user` as a normal
+ * tool result.
+ *
+ * Layout — one framed overlay, all questions flattened:
+ *
+ *   ● 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)
+ *
+ * Single-question single-select overlay: Enter on an option (or committing a
+ * filled sentinel) submits immediately. A multiSelect question — even a lone
+ * one — gets a Confirm row instead of auto-submitting, so the user can pick
+ * several options first. Multi-question overlay: Enter on the Confirm row
+ * hops to the review page (all answers listed, each editable in place).
+ * Esc double-press within 200 ms declines — but terminal key auto-repeat
+ * (holding Esc) is ignored below `ESC_REPEAT_GUARD_MS`, so a long press
+ * cannot accidentally fire the decline. The provider returns the "declined"
+ * envelope and the model reads it as a normal user reply. An aborted
+ * request signal (`request.signal`) settles declined too — we resolve the
+ * declined envelope instead of rejecting ASK_ABORTED because the upstream
+ * service already screens entry-time aborts and an aborted step discards
+ * the result anyway.
+ *
+ * Pure logic lives in the top of this file (initial state, answer envelope,
+ * declined envelope, double-Esc state machine, row-layout math) so it can
+ * be unit-tested without a TTY. The component below owns the TUI render +
+ * keyboard handling; the install function at the bottom registers the
+ * provider under `ctx.userQuestions` (a Cordis effect, single active
+ * provider in the tree).
+ *
+ * Inspired by juicesharp/rpiv-ask-user-question
+ * (https://github.com/juicesharp/rpiv-ask-user-question).
+ */
+import { type TUI } from '@earendil-works/pi-tui';
+import type { AskUserQuestionAnswer, AskUserQuestionItem, AskUserQuestionOption } from '@deepseek-ai/dsh-user-questions';
+import type { Context } from '@deepseek-ai/cordis';
+import { type TuiTheme } from './theme/index.ts';
+/** Maximum time between two Esc presses before the second one re-arms instead of firing. */
+export declare const DOUBLE_ESC_WINDOW_MS = 200;
+/**
+ * Minimum gap between two Esc presses below which the second one is treated as
+ * terminal key auto-repeat (the user is HOLDING Esc) rather than a deliberate
+ * press: repeats leave the state untouched, so a long press can never fire the
+ * decline gesture on its own.
+ */
+export declare const ESC_REPEAT_GUARD_MS = 50;
+/** Sentinel row label appended to every question's option list. */
+export declare const SENTINEL_LABEL = "Type something.";
+/** Decline message embedded into the answer envelope when the user bails. */
+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";
+/** A row in the multi-question view. */
+export interface FlatRow {
+    kind: 'question-header' | 'option' | 'sentinel' | 'confirm';
+    questionIndex: number;
+    /** optionIndex for `option` rows, undefined for everything else. */
+    optionIndex?: number;
+    label: string;
+    description?: string;
+    /** Upstream `detail` (supporting text rendered under the header, never in labels). */
+    detail?: string;
+    selectable: boolean;
+}
+/** Pending answer for a single question. */
+export interface PendingAnswer {
+    /** Selected option labels in display order. Empty when the sentinel/custom path owns this question. */
+    selected: readonly string[];
+    /** 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. */
+export interface AskUserState {
+    questions: readonly AskUserQuestionItem[];
+    /** Per-question pending answer. */
+    perQuestion: PendingAnswer[];
+    /** Cursor position in the flat row list (see `buildRowList`). */
+    cursorIndex: number;
+    /** Live inline-edit text per question; non-null when the sentinel is engaged for that question. */
+    customInputs: (string | null)[];
+    /** Live inline edit owner (question index); null when not editing. */
+    customEditingFor: number | null;
+    /** Phase: multi-question uses a review step before submission. */
+    phase: 'questions' | 'review';
+    /** Cursor over the review rows. Q rows + 1 submit row. */
+    reviewIndex: number;
+    /** Last Esc timestamp for the double-Esc guard. */
+    lastEscAt: number | null;
+    /** The status hint shown above the footer after one Esc press. */
+    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;
+}
+/** 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;
+/** Toggle/add an option. Single-select replaces; multi-select toggles membership. */
+export declare function toggleOption(state: AskUserState, questionIndex: number, optionLabel: string): AskUserState;
+/** Set the custom answer for a question (clears selected options). */
+export declare function setCustomAnswer(state: AskUserState, questionIndex: number, text: string): AskUserState;
+/** Mutate the live custom input buffer for a question. */
+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. */
+export declare function exitCustomEdit(state: AskUserState, commit: boolean): AskUserState;
+/**
+ * Double-Esc state machine: 1st press arms; 2nd within the window fires
+ * (caller reads `lastEscAt===null + cancelHint===false`). Presses closer than
+ * `repeatGuardMs` are terminal key auto-repeat (held key) and are ignored
+ * entirely — the armed state stays at its original timestamp, so holding Esc
+ * neither fires the decline nor refreshes the window.
+ */
+export declare function advanceDoubleEsc(state: AskUserState, now: number, windowMs?: number, repeatGuardMs?: number): AskUserState;
+/** Was the most recent double-Esc press a "fired" event (the second within the window)? */
+export declare function didDoubleEscFire(prevState: AskUserState, nextState: AskUserState, now: number, windowMs?: number): boolean;
+/** Canonical envelope for a normal submission. The model reads it as a tool result. */
+export declare function buildAnswerEnvelope(state: AskUserState): AskUserQuestionAnswer;
+/** Canonical envelope for the decline path: empty selected + custom decline message on every question. */
+export declare function buildDeclinedEnvelope(questions: readonly AskUserQuestionItem[], message?: string): AskUserQuestionAnswer;
+/** Build the ordered, flat list of rows for the questions pane. */
+export declare function buildRowList(questions: readonly AskUserQuestionItem[], perQuestion: readonly PendingAnswer[]): FlatRow[];
+/** Find the next selectable index from `i` going in `direction`, clamped into range. */
+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;
+/**
+ * Whether the overlay needs an explicit `⏎ Confirm answers` row: any
+ * multi-question layout, plus a lone multiSelect question — multiSelect can
+ * never auto-submit (the user may want more toggles), so it needs a path to
+ * the review page.
+ */
+export declare function needsConfirmRow(questions: readonly AskUserQuestionItem[]): boolean;
+/**
+ * True when a successful action on THIS state can submit immediately without
+ * the review step: exactly one question, single-select (a multiSelect
+ * question may want further toggles), and every question answered.
+ */
+export declare function canAutoSubmit(state: AskUserState): boolean;
+/**
+ * Row index to land on after answering question `answeredQi`: the first
+ * selectable row of the nearest LATER unanswered question, or -1 when every
+ * 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[];
+/** Options for assembling the panel + provider function. */
+export interface AskUserPanelDeps {
+    tui: TUI;
+    /** Live theme getter — re-read on every render so a mid-overlay hot-swap applies (frame included). */
+    theme: () => TuiTheme;
+    /** Re-focus the current editor on overlay close. */
+    restoreFocus: () => void;
+    /** Injectable clock for tests; defaults to Date.now. */
+    now?: () => number;
+    /** Width and height of the framed overlay. */
+    width?: `${number}%` | number;
+    maxHeight?: `${number}%` | number;
+}
+/** Result promise from `openAskUserPanel`. Declined carries the canonical decline envelope. */
+export type AskUserResult = AskUserQuestionAnswer;
+/**
+ * Open the AskUser overlay for one set of questions.
+ *
+ * `signal` is the caller's abort signal (the tool execution's). Already-aborted
+ * settles declined WITHOUT staging an overlay; a live signal closes the
+ * overlay and settles declined when it fires. We resolve the declined envelope
+ * rather than rejecting with the upstream ASK_ABORTED code on purpose: the
+ * upstream service already screens entry-time aborts, and a step aborted after
+ * this point discards the tool result anyway — resolving keeps the pending
+ * promise from ever hanging either way.
+ */
+export declare function openAskUserPanel(deps: AskUserPanelDeps, questions: readonly AskUserQuestionItem[], signal?: AbortSignal): Promise<AskUserResult>;
+/**
+ * True only for the upstream's documented duplicate-registration failure
+ * (`UserQuestionError` with code `DUPLICATE_PROVIDER`) — the one case where
+ * yielding the single provider slot to the prior UI is correct. Matched
+ * structurally on `name` + `code` so a cross-realm HarnessError instance or a
+ * test double classifies identically.
+ */
+export declare function isDuplicateProviderError(error: unknown): boolean;
+/**
+ * Wires the provider into `ctx.userQuestions`. Call from inside `ctx.effect`.
+ *
+ * Failure semantics are deliberate (review round BM):
+ * - missing service → warn + no-op disposer. The tool stays mounted by the
+ *   bundle patch; without a provider its calls fail with the upstream
+ *   NO_PROVIDER error, which is better than crashing the whole TUI plugin.
+ * - DUPLICATE_PROVIDER → silent no-op disposer (a prior UI owns the slot).
+ * - anything else → rethrown so the effect fails loudly instead of leaving a
+ *   mounted tool with no UI and no trace.
+ */
+export declare function registerAskUserProvider(ctx: Context, deps: AskUserPanelDeps): () => void;
+export type { AskUserQuestionOption };