@aiwayds/dsh-tui-pi 2.18.2 → 2.19.0

package/README.md

@@ -149,8 +149,13 @@ dsh-tui:
   resume:           # /resume display filter — only HIDES picker rows, never deletes.
     maxAgeDays: 30
     minBytes: 1024
+  askUser:          # ask_user_question auto-answer timeouts — the panel never waits forever.
+    idleMinutes: 5       # no-input window per question; <= 0 disables (DSH_TUI_ASK_USER_IDLE_MINUTES)
+    absoluteMinutes: 10  # hard cap per question even with input; <= 0 disables (DSH_TUI_ASK_USER_ABSOLUTE_MINUTES)
 ```
 
+On a timeout the focused question is auto-answered with the **recommended option** (first in the list); plans are never auto-approved, a half-typed answer is committed, and every automatic pick is noted to the model in the answer. Details: [Ask User Question → Timeouts](docs/features/ask-user-question.md#timeouts--the-panel-never-waits-forever).
+
 Key remaps live in `~/.dsh/keybindings.json` (keyboard section above); `DSH_TUI_COPY_ON_SELECT=0` keeps drag-selection visual-only.
 
 The plugin ships a bundled skill (`dsh-tui-pi-config`): ask the agent to "configure the TUI" and the guide loads automatically — it collects your choices interactively via ask_user_question (theme, panel height, subagent concurrency) and writes the `dsh-tui:` section for you. The full key table and the `DSH_TUI_*` env var list live in `skills/dsh-tui-pi-config/SKILL.md`.

package/README.zh-CN.md

@@ -145,8 +145,13 @@ dsh-tui:
   resume:           # /resume 显示过滤器——只隐藏选择器行，从不删除。
     maxAgeDays: 30
     minBytes: 1024
+  askUser:          # ask_user_question 自动应答超时——面板绝不无限等待。
+    idleMinutes: 5       # 每题无操作窗口；<= 0 关闭（DSH_TUI_ASK_USER_IDLE_MINUTES）
+    absoluteMinutes: 10  # 每题硬上限，有操作也生效；<= 0 关闭（DSH_TUI_ASK_USER_ABSOLUTE_MINUTES）
 ```
 
+超时后，聚焦的未答题目自动选**推荐项**（列表第一项）；计划审批绝不自动批准；打了一半的自由文本会被提交；每次自动作答都会在答案里向模型注明。详见 [Ask User Question → Timeouts](docs/features/ask-user-question.md#timeouts--the-panel-never-waits-forever)。
+
 按键重映射见 `~/.dsh/keybindings.json`（上文键盘一节）。
 
 插件内置了一个 skill（`dsh-tui-pi-config`）：直接让 agent「帮我配置 TUI」，指南会自动加载——以 ask_user_question 问答方式逐项收集（主题、面板高度、子代理并发）并代写 `dsh-tui:` 段；全键表与 `DSH_TUI_*` 环境变量清单见 `skills/dsh-tui-pi-config/SKILL.md`。

package/lib/ask-user.d.ts

@@ -124,6 +124,34 @@ export declare const ASK_COLLAPSE_KEY: KeyId;
 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";
+/** Default no-input window per focused question, in minutes: after this long
+ *  without a single keypress the question is auto-answered (recommended
+ *  option, plan-safe) and the panel moves on. */
+export declare const ASK_USER_IDLE_MINUTES_DEFAULT = 5;
+/** Default hard cap per focused question, in minutes: after this long the
+ *  question is auto-answered EVEN IF the user keeps interacting — the panel
+ *  must never hold a run hostage indefinitely (dual rule with the idle
+ *  window; either firing resolves the question). */
+export declare const ASK_USER_ABSOLUTE_MINUTES_DEFAULT = 10;
+/** Env override for the no-input window (minutes; <= 0 disables the rule). */
+export declare const ASK_USER_IDLE_ENV = "DSH_TUI_ASK_USER_IDLE_MINUTES";
+/** Env override for the hard cap (minutes; <= 0 disables the rule). */
+export declare const ASK_USER_ABSOLUTE_ENV = "DSH_TUI_ASK_USER_ABSOLUTE_MINUTES";
+/** Note folded into the answer envelope's `custom` field when a question was
+ *  auto-answered with the recommended option — the model reads the answer as
+ *  a tool result, so an automatic pick is declared in-band (same spirit as
+ *  DECLINE_MESSAGE), never silently passed off as a human choice. */
+export declare const TIMEOUT_RECOMMENDED_NOTE = "Auto-answered after the no-input timeout: the recommended option was picked.";
+/** Note for a plan-review question auto-answered by timeout: plans are NEVER
+ *  auto-approved — the first non-approve option is picked instead. */
+export declare const TIMEOUT_PLAN_DECLINED_NOTE = "Auto-answered after the no-input timeout: no user input, so the plan was NOT approved.";
+/** Note for a question with no options at all — there is no recommended value
+ *  to fall back to, so the answer carries the explanation only. */
+export declare const TIMEOUT_NO_DEFAULT_NOTE = "Auto-answered after the no-input timeout: the question offers no default option to pick.";
+/** Note appended when the timeout commits a half-typed sentinel buffer: the
+ *  text is the user's own, but it never went through Enter, so the envelope
+ *  says so. */
+export declare const TIMEOUT_CUSTOM_NOTE = "Auto-committed after the no-input timeout: the text typed so far.";
 /**
  * Fallback visible body-line cap for the questions/review panes, used only
  * when the terminal row count is unknown (fake TUIs in tests, exotic
@@ -286,6 +314,81 @@ export declare function needsConfirmRow(questions: readonly AskUserQuestionItem[
  * question may want further toggles), and every question answered.
  */
 export declare function canAutoSubmit(state: AskUserState): boolean;
+/**
+ * Timeout rules for one open ask-user panel — the unit is ms internally,
+ * minutes in settings/env (human units, like retention's maxAgeDays).
+ * `0` disables that rule; both zero = the legacy wait-forever panel.
+ */
+export interface AskUserTimeouts {
+    /** No-input window per focused question. Any keypress restarts it. */
+    idleMs: number;
+    /** Hard cap per focused question, measured from when focus entered it —
+     *  fires even under continuous input. */
+    absoluteMs: number;
+}
+/** Both rules off — the panel waits for the human exactly as before. */
+export declare const ASK_USER_TIMEOUTS_DISABLED: AskUserTimeouts;
+/** Raw user-layer `dsh-tui.askUser` section (handed over by the
+ * theme-settings reader): every field is `unknown` because a hand-edited
+ * settings.yaml can carry anything. */
+export interface AskUserTimeoutSettings {
+    idleMinutes?: unknown;
+    absoluteMinutes?: unknown;
+}
+/**
+ * Resolve the ask-user timeout knobs through the repo's standard precedence
+ * chain — explicit settings.yaml values (`dsh-tui.askUser.*`) outrank the
+ * `DSH_TUI_ASK_USER_*` environment variables, which outrank the defaults
+ * (5 min idle / 10 min absolute). Invalid settings values emit one notice
+ * each (notice bridge) and fall to the next level; invalid env values fall
+ * back silently. Pure; `process.env` and the settings section are passed
+ * explicitly so tests can pin them.
+ */
+export declare function resolveAskUserTimeouts(settings?: AskUserTimeoutSettings, env?: Record<string, string | undefined>): AskUserTimeouts;
+/**
+ * Earliest deadline at which the panel's timeout should fire, or null when
+ * no rule is armed. The idle deadline runs from `lastInputAt` (any
+ * keypress); the absolute deadline runs from `focusEnteredAt` (focus entry
+ * into the current question) and applies in BOTH phases — a review page
+ * entered late inherits its question's remaining budget, so the total wait
+ * per question stays bounded. Pure; the panel arms a timer on this.
+ */
+export declare function nextTimeoutDeadline(timeouts: AskUserTimeouts, now: number, focusEnteredAt: number, lastInputAt: number): number | null;
+/**
+ * The timeout auto-answer for ONE unanswered question — what the panel
+ * writes into `perQuestion` when a timer fires on it. Priority:
+ *
+ * 1. a non-empty live sentinel buffer is committed as the custom answer
+ *    (the panel's own ↑↓ arrow-exit semantics commit non-empty buffers, so
+ *    typed-but-uncommitted text is honored, not discarded);
+ * 2. a `plan-review` question NEVER auto-approves — the first option that
+ *    is not the intent's `approve` label is picked (decline by omission);
+ * 3. otherwise the FIRST option — the dsh tool contract declares the
+ *    recommended choice by putting it first ("put it first and append
+ *    '(Recommended)' to that label").
+ *
+ * The companion envelope note is returned alongside so the panel can fold
+ * it into the answer at settle time; the note never enters panel state
+ * (it would leak into the sentinel row / review rendering).
+ */
+export declare function timeoutAnswerFor(question: AskUserQuestionItem, liveBuffer: string | null | undefined): {
+    answer: PendingAnswer;
+    note?: string;
+};
+/**
+ * `buildAnswerEnvelope` with the timeout notes folded in: `notes` maps a
+ * question index to the note appended to that answer item's `custom` field
+ * (created when absent, concatenated when the answer already carries custom
+ * text — the buffer-commit case). The model reads the envelope as the tool
+ * result, so every automatic pick is declared in-band. Omitting `notes`
+ * reproduces `buildAnswerEnvelope` exactly.
+ */
+export declare function buildAnswerEnvelopeWithNotes(state: AskUserState, notes?: ReadonlyMap<number, string>): AskUserQuestionAnswer;
+/**
+ * The idle countdown for the panel footer: `m:ss` until the next deadline,
+ * floored at 0:00. Pure so tests pin it without a clock.
+ */
+export declare function formatCountdown(msRemaining: number): string;
 /**
  * Row index to land on after a single-select answer on question `answeredQi`
  * (option toggle or committed custom text): advance the tab focus to the
@@ -321,9 +424,9 @@ export declare function switchFocus(state: AskUserState, direction: 1 | -1): Ask
  */
 export declare function toggleCollapse(state: AskUserState): AskUserState;
 /** Render the questions pane (one focused question tab) as a flat table line list behind a scroll window. */
-export declare function renderQuestionsView(theme: TuiTheme, state: AskUserState, width: number, maxVisible?: number): string[];
+export declare function renderQuestionsView(theme: TuiTheme, state: AskUserState, width: number, maxVisible?: number, countdown?: string): string[];
 /** Render the review page for multi-question overlays (scroll-windowed). */
-export declare function renderReviewView(theme: TuiTheme, state: AskUserState, width: number, maxVisible?: number): string[];
+export declare function renderReviewView(theme: TuiTheme, state: AskUserState, width: number, maxVisible?: number, countdown?: string): string[];
 /**
  * The ONE interior line of the folded (Ctrl+T) panel. The panel is a hard
  * modal that owns the keyboard while it pends, so the strip keeps the
@@ -411,6 +514,13 @@ export interface AskUserPanelDeps {
     setModalActive: (active: boolean) => void;
     /** Injectable clock for tests; defaults to Date.now. */
     now?: () => number;
+    /**
+     * Resolve the timeout rules for ONE ask (settings > env > defaults, read
+     * fresh per ask so a committed settings change applies to the next
+     * question without a reload). Absent = disabled — the panel waits for the
+     * human exactly as before (direct callers, tests, embedders).
+     */
+    resolveTimeouts?: () => Promise<AskUserTimeouts>;
 }
 /** Result promise from `openAskUserPanel`. Declined carries the canonical decline envelope. */
 export type AskUserResult = AskUserQuestionAnswer;
@@ -424,8 +534,17 @@ export type AskUserResult = AskUserQuestionAnswer;
  * 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.
+ *
+ * `timeouts` arms the auto-answer rules (see {@link AskUserTimeouts}): the
+ * FOCUSED question's idle window and hard cap. A firing timer auto-answers
+ * the focused question (recommended option, plan-safe —
+ * {@link timeoutAnswerFor}), hops to the next unanswered question with fresh
+ * budgets, and — once nothing is left unanswered — settles the envelope
+ * directly (the review page exists for a human double-check an absent human
+ * cannot do). Defaults to disabled: callers opt in through the provider's
+ * `resolveTimeouts`.
  */
-export declare function openAskUserPanel(deps: AskUserPanelDeps, questions: readonly AskUserQuestionItem[], signal?: AbortSignal): Promise<AskUserResult>;
+export declare function openAskUserPanel(deps: AskUserPanelDeps, questions: readonly AskUserQuestionItem[], signal?: AbortSignal, timeouts?: AskUserTimeouts): Promise<AskUserResult>;
 /**
  * Wires the TUI into `ctx.userQuestions`. Call from inside `ctx.effect`.
  * Two registration shapes, chosen by what the host exposes: