@black942026/pi-ask-user 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,11 @@
 # @black942026/pi-ask-user
 
-`ask_user` — a route-resolved "ask the user" interaction for Pi.
+A Pi extension for asking structured questions through interactive terminal
+or native input dialogs. Supports single-choice, multiple-choice, and free-text
+answers, with configurable timeouts and cancellation.
+
+Install the package to add the **`ask_user`** tool to Pi. Other extensions can
+reuse the same interaction through the TypeScript API.
 
 Two entry points share one strict questionnaire contract and one route resolution:
 
@@ -22,16 +27,14 @@ or probed when the host is created, never per request.
 
 ```bash
 pi install npm:@black942026/pi-ask-user
-# or, from a local checkout
-pi install /absolute/path/to/pi-ask-user
-# or, during development
-pi --extension ./index.ts
 ```
 
-Requires Node.js ≥ 22.19.0.
+Start a new Pi session, or run `/reload` in an existing session, to load the
+extension. The `ask_user` tool is registered automatically.
 
-Peer dependencies: `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`,
-`typebox`.
+Requires Node.js ≥ 22.19.0 and Pi ≥ 0.87.0. Pi supplies the host dependencies
+`@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, and `typebox`;
+no separate dependency installation is needed when using `pi install`.
 
 ## Tool parameters
 
@@ -111,8 +114,8 @@ against the questionnaire's own controls. A malformed spec (`alt+banana`), a
 reserved key (`escape`/`esc` — which must keep cancelling — plus
 `enter`/`tab`/arrows/`space`/`pageUp`/…), a bare printable key that would swallow
 typing (`o`), and conflicting chords (`ctrl+c`, `ctrl+d`, `ctrl+u`, `ctrl+p`,
-`ctrl+n`, `ctrl+enter`) are each rejected with a specific reason. A key is never
-silently substituted.
+`ctrl+n`, `ctrl+enter`, `alt+q`) are each rejected with a specific reason. A key
+is never silently substituted.
 
 ### Effective precedence and read timing
 
@@ -275,6 +278,19 @@ an optional sink — `createAskUser(ctx, { events: { waitStarted, waitEnded } })
 or `createAskUser(host, { events })` — or accept that no runtime events are
 emitted. `AskUserEventSink` is exported for this.
 
+## Cancel countdown shortcut
+
+In the **custom terminal UI** (overlay or inline), press **`Alt+Q`** to cancel
+this questionnaire's countdown without dismissing it or changing your answers.
+The header shows **`No timeout`**; you can keep answering, submit normally, or
+press `Esc` to dismiss. Caller aborts still work. This is a one-way change for
+the current questionnaire only; the next call starts with its configured timeout.
+An already-expired deadline cannot be cancelled.
+
+The key is shown in the bottom hints and reserved against `overlayToggleKey`
+conflicts. Native input dialogs do not support this shortcut. If an overlay is
+hidden, restore it first with its show/hide key before pressing `Alt+Q`.
+
 ## Overlay show/hide key
 
 On the **custom overlay route only** (never inline, never native), the overlay
@@ -325,12 +341,14 @@ for a refused explicit config, names the requested route.
 ## Key constraints
 
 - **The deadline is shared and owned by the core.** Per questionnaire it is
-  strictly `timeoutPerQuestionMs × questionCount` (default 60 s each), clamped to
+  initially `timeoutPerQuestionMs × questionCount` (default 60 s each), clamped to
   `MAX_SAFE_TIMEOUT_MS` (2³¹−1); there is no absolute override. The deadline and
   the caller's cancellation are raced independently of the renderer, so a renderer
   that never resolves or ignores its `AbortSignal` still yields
-  `timeout`/`aborted`; late results are discarded. Cancellation is checked before
-  any route branch, so an already-aborted call never renders a UI.
+  `timeout`/`aborted`, unless the user explicitly cancels the timeout with `Alt+Q`
+  in the custom UI (caller aborts remain effective); late results are discarded.
+  Cancellation is checked before any route branch, so an already-aborted call
+  never renders a UI.
 - **A missing route is an error, not a downgrade.** JSON/print, or an explicit
   `mode` that cannot run, is refused with `unsupported_mode` and never replaced by
   another route.
@@ -357,10 +375,16 @@ for a refused explicit config, names the requested route.
 ```bash
 npm install
 npm run typecheck   # tsc --noEmit
-npm test            # node --test test/*.test.ts (Node ≥ 22.6 runs TS directly)
+npm test            # node --test test/*.test.ts
 npm run check       # typecheck + tests
+
+# Load a local checkout for development
+pi --extension ./index.ts
+# Or install it as a local package
+pi install /absolute/path/to/pi-ask-user
 ```
 
-`@earendil-works/pi-tui` is a runtime dependency of the custom UI, and `typebox`
-is a runtime dependency of the parameter schema (`src/schema.ts`). The routing,
-parsing, and deadline layers are pure, non-TUI, and free of both.
+`@earendil-works/pi-tui` and `typebox` are host-provided peer dependencies used
+by the custom UI and parameter schema (`src/schema.ts`). They are also declared
+as development dependencies for local checks. The routing, parsing, and deadline
+layers are pure, non-TUI, and free of both.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@black942026/pi-ask-user",
-  "version": "0.1.0",
-  "description": "AskUser - a route-forced ask-user interaction component/tool for Pi extensions (custom TUI or native dialogs)",
+  "version": "0.1.1",
+  "description": "Structured user questions for Pi, with interactive terminal dialogs, native input dialogs, and a reusable TypeScript API.",
   "type": "module",
   "license": "MIT",
   "repository": {

package/src/adapters/pi.ts

@@ -195,6 +195,7 @@ export function createPiCustomRenderer(ui: ExtensionUIContext, options: PiCustom
 						component = new AskUserComponent({
 							request,
 							deadline,
+							cancelTimeout: input.cancelTimeout,
 							theme: theme as unknown as AskUserTheme,
 							tui,
 							done,

package/src/config.ts

@@ -32,6 +32,8 @@ export const USER_CONFIG_PATH = join(USER_CONFIG_DIR, "config.json");
 
 /** Built-in default key that toggles the overlay between hidden and visible. */
 export const DEFAULT_OVERLAY_TOGGLE_KEY = "alt+o";
+/** Cancel the current questionnaire's countdown without dismissing the UI. */
+export const CANCEL_TIMEOUT_KEY = "alt+q";
 /** Built-in default custom-UI presentation. */
 export const DEFAULT_DISPLAY_MODE: AskUserDisplayMode = "overlay";
 
@@ -129,7 +131,7 @@ const RESERVED_BASES = new Set([
 ]);
 /** Modifier chords that conflict with a questionnaire control. */
 const RESERVED_SIGNATURES = new Set(
-	["ctrl+c", "ctrl+d", "ctrl+u", "ctrl+p", "ctrl+n", "ctrl+enter"].map((id) => {
+	["ctrl+c", "ctrl+d", "ctrl+u", "ctrl+p", "ctrl+n", "ctrl+enter", CANCEL_TIMEOUT_KEY].map((id) => {
 		const parts = id.split("+");
 		const base = parts.pop()!;
 		return [...parts.sort(), base].join("+");

package/src/core.ts

@@ -92,9 +92,17 @@ export async function askUserNormalized(
 	const effectiveRequest = applyPreferences(request, host.preferences);
 	const deadline = createDeadline(effectiveRequest.totalTimeoutMs, now);
 	const deadlineController = new AbortController();
+	const timeoutCancelled = new AbortController();
 	const linked = combineSignals(signal, deadlineController.signal);
 
 	const input: AskUIInput = { request: effectiveRequest, deadline, signal: linked.signal };
+	if (route === "custom") {
+		input.cancelTimeout = () => {
+			if (!deadline.cancel()) return false;
+			timeoutCancelled.abort();
+			return true;
+		};
+	}
 	if (onUpdate) input.onUpdate = onUpdate;
 
 	// Wait events are emitted exactly around a real UI attempt: `waitStarted`
@@ -138,12 +146,14 @@ export async function askUserNormalized(
 	}
 
 	// The core owns the guarantee: even a renderer that ignores its AbortSignal
-	// cannot hang the call. The deadline and the caller's cancellation are raced
-	// independently against the renderer; a late renderer result is ignored.
+	// cannot hang the call unless the user explicitly disables the timeout.
+	// The deadline and caller's cancellation are raced independently against
+	// the renderer; a late renderer result is ignored.
 	let race: DeadlineRace;
 	try {
-		race = await raceWithDeadline(renderPromise, deadline.remainingMs(), signal, () =>
-			deadlineController.abort(),
+		race = await raceWithDeadline(
+			renderPromise, deadline.remainingMs(), signal,
+			() => deadlineController.abort(), timeoutCancelled.signal,
 		);
 	} finally {
 		// Always release the listeners installed on the caller's signal.
@@ -178,7 +188,8 @@ type DeadlineRace =
  *
  * This is what makes the timeout guarantee independent of renderer behaviour: a
  * renderer that never resolves (or that ignores its signal) still yields
- * `timeout`. Late results are discarded, and the rejection path is always
+ * `timeout`, unless the user explicitly cancels the timeout. Late results are
+ * discarded, and the rejection path is always
  * handled so a late failure cannot become an unhandled rejection.
  */
 function raceWithDeadline(
@@ -186,15 +197,23 @@ function raceWithDeadline(
 	remainingMs: number,
 	callerSignal: AbortSignal | undefined,
 	onDeadline: () => void,
+	timeoutCancelled: AbortSignal,
 ): Promise<DeadlineRace> {
 	let timer: ReturnType<typeof setTimeout> | undefined;
 	let abortHandler: (() => void) | undefined;
+	const clearDeadlineTimer = (): void => {
+		if (timer !== undefined) clearTimeout(timer);
+		timer = undefined;
+	};
 	const racers: Array<Promise<DeadlineRace>> = [
 		render.then(
 			(outcome): DeadlineRace => ({ kind: "outcome", outcome }),
 			(error): DeadlineRace => ({ kind: "outcome", outcome: { kind: "error", message: messageOf(error) } }),
 		),
 		new Promise<DeadlineRace>((resolve) => {
+			// Cancellation may happen synchronously during renderer construction.
+			if (timeoutCancelled.aborted) return;
+			timeoutCancelled.addEventListener("abort", clearDeadlineTimer, { once: true });
 			// `safeTimeoutMs` prevents a >32-bit delay from firing immediately.
 			timer = setTimeout(() => {
 				onDeadline();
@@ -215,7 +234,8 @@ function raceWithDeadline(
 		);
 	}
 	return Promise.race(racers).finally(() => {
-		if (timer) clearTimeout(timer);
+		clearDeadlineTimer();
+		timeoutCancelled.removeEventListener("abort", clearDeadlineTimer);
 		// Remove the listener when the render settled first, so repeated calls do
 		// not accumulate listeners on a long-lived caller signal.
 		if (abortHandler && callerSignal) callerSignal.removeEventListener("abort", abortHandler);

package/src/deadline.ts

@@ -13,27 +13,43 @@ export function safeTimeoutMs(ms: number): number {
 	return Math.min(Math.floor(ms), MAX_SAFE_TIMEOUT_MS);
 }
 
+/** A shared deadline that the user can disable for the current questionnaire. */
+export interface CancellableDeadline extends Deadline {
+	/** Disable expiry. Returns false if the deadline has already expired. */
+	cancel(): boolean;
+}
+
 /**
  * Create a single overall deadline for a questionnaire.
  *
- * The deadline is always `timeoutMs` (which callers compute as
+ * The initial deadline is `totalMs` (which callers compute as
  * `timeoutPerQuestionMs × questionCount`). It is clamped to
  * {@link MAX_SAFE_TIMEOUT_MS} so `setTimeout` never overflows. Every interaction
  * for the questionnaire shares this one deadline; native dialogs receive only
- * the remaining time. A deadline never degrades to another route.
+ * the remaining time. `cancel()` disables expiry but does not clear any timers;
+ * the core and custom UI clear their timers separately. A deadline never
+ * degrades to another route.
  */
-export function createDeadline(totalMs: number, now: () => number = Date.now): Deadline {
+export function createDeadline(totalMs: number, now: () => number = Date.now): CancellableDeadline {
 	const startedAt = now();
 	const safeTotal = safeTimeoutMs(totalMs);
 	const expiresAt = safeTotal === 0 ? startedAt : startedAt + safeTotal;
+	let cancelled = false;
 	return {
 		startedAt,
-		expiresAt,
+		get expiresAt(): number {
+			return cancelled ? Infinity : expiresAt;
+		},
 		remainingMs(): number {
-			return Math.max(0, expiresAt - now());
+			return cancelled ? Infinity : Math.max(0, expiresAt - now());
 		},
 		expired(): boolean {
-			return now() >= expiresAt;
+			return !cancelled && now() >= expiresAt;
+		},
+		cancel(): boolean {
+			if (!cancelled && now() >= expiresAt) return false;
+			cancelled = true;
+			return true;
 		},
 	};
 }

package/src/types.ts

@@ -70,8 +70,8 @@ export interface AskUserRequest {
 	/**
 	 * Base timeout per question in milliseconds. Defaults to 60000.
 	 *
-	 * The questionnaire's single deadline is always
-	 * `timeoutPerQuestionMs × questionCount`; there is no absolute override.
+	 * The questionnaire's initial shared deadline is
+	 * `timeoutPerQuestionMs × questionCount`; the user can cancel it in the custom UI.
 	 */
 	timeoutPerQuestionMs?: number;
 }
@@ -220,6 +220,8 @@ export type AskUserSupport =
 export interface AskUIInput {
 	request: NormalizedRequest;
 	deadline: Deadline;
+	/** Custom UI only: disable this questionnaire's timeout; false if already expired. */
+	cancelTimeout?: () => boolean;
 	signal?: AbortSignal;
 	/** Report progress such as "Waiting for user input...". */
 	onUpdate?: (text: string) => void;

package/src/ui/custom.ts

@@ -2,6 +2,7 @@ import {
 	Input,
 	Key,
 	Markdown,
+	isKeyRelease,
 	matchesKey,
 	truncateToWidth,
 	visibleWidth,
@@ -10,6 +11,7 @@ import {
 import type { Component, Focusable, MarkdownTheme } from "@earendil-works/pi-tui";
 import { draftFromDefault, draftIsEmpty, emptyDraft, finalizeAnswers, type DraftAnswer } from "../answers.ts";
 import type { AskUserAnswer, Deadline, NormalizedQuestion, NormalizedRequest } from "../types.ts";
+import { CANCEL_TIMEOUT_KEY } from "../config.ts";
 
 /** Structural theme surface the component needs (a real Pi Theme satisfies it). */
 export interface AskUserTheme {
@@ -35,6 +37,8 @@ export interface CustomUIResult {
 export interface AskUserComponentOptions {
 	request: NormalizedRequest;
 	deadline: Deadline;
+	/** Disable the core deadline as well as this component's local timer. */
+	cancelTimeout?: () => boolean;
 	theme: AskUserTheme;
 	tui: AskUserTUI;
 	done: (result: CustomUIResult) => void;
@@ -132,6 +136,8 @@ function printableText(data: string): string | undefined {
 export class AskUserComponent implements Component, Focusable {
 	private readonly request: NormalizedRequest;
 	private readonly deadline: Deadline;
+	private readonly cancelTimeout: (() => boolean) | undefined;
+	private timeoutCancelled = false;
 	private readonly theme: AskUserTheme;
 	private readonly tui: AskUserTUI;
 	private readonly done: (result: CustomUIResult) => void;
@@ -164,6 +170,7 @@ export class AskUserComponent implements Component, Focusable {
 	constructor(options: AskUserComponentOptions) {
 		this.request = options.request;
 		this.deadline = options.deadline;
+		this.cancelTimeout = options.cancelTimeout;
 		this.theme = options.theme;
 		this.tui = options.tui;
 		this.done = options.done;
@@ -369,6 +376,14 @@ export class AskUserComponent implements Component, Focusable {
 	handleInput(data: string): void {
 		if (this.finished) return;
 
+		if (matchesKey(data, CANCEL_TIMEOUT_KEY)) {
+			if (isKeyRelease(data) || this.timeoutCancelled || this.deadline.expired()) return;
+			if (this.cancelTimeout && !this.cancelTimeout()) return;
+			this.timeoutCancelled = true;
+			this.dispose();
+			this.refresh();
+			return;
+		}
 		if (matchesKey(data, Key.escape)) {
 			this.finish({ kind: "cancelled" });
 			return;
@@ -574,6 +589,7 @@ export class AskUserComponent implements Component, Focusable {
 	}
 
 	private countdownLabel(): string {
+		if (this.timeoutCancelled) return "No timeout";
 		const hours = Math.floor(this.remainingSeconds / 3600);
 		const minutes = Math.floor((this.remainingSeconds % 3600) / 60);
 		const seconds = String(this.remainingSeconds % 60).padStart(2, "0");
@@ -789,13 +805,20 @@ export class AskUserComponent implements Component, Focusable {
 		return parts.join(" | ") + suffix;
 	}
 
-	private hintLine(): string {
-		const toggleHint = this.overlayToggleKey ? `${this.overlayToggleKey} hide` : undefined;
+	private hintLine(width: number): string {
+		// Keep cancellation controls discoverable even when contextual hints grow.
+		const controls = ["Esc cancel"];
+		if (!this.timeoutCancelled) controls.push(`${CANCEL_TIMEOUT_KEY} stop timer`);
+		if (this.overlayToggleKey) controls.push(`${this.overlayToggleKey} hide`);
+		const controlText = controls.join(" · ");
+		const withControls = (hints: string[]): string => {
+			const contextWidth = width - visibleWidth(controlText) - 3;
+			const context = contextWidth > 0 ? truncateToWidth(hints.join(" · "), contextWidth) : "";
+			return this.theme.fg("dim", context ? `${context} · ${controlText}` : controlText);
+		};
 		if (this.isReview) {
 			const reviewHints = ["↓ focus submit", "Enter submit", "Tab switch question"];
-			if (toggleHint) reviewHints.push(toggleHint);
-			reviewHints.push("Esc cancel");
-			return this.theme.fg("dim", reviewHints.join(" · "));
+			return withControls(reviewHints);
 		}
 		const question = this.currentQuestion();
 		const hints = ["Tab switch", "↑/↓ move", `Enter ${this.isInputRow() ? "confirm" : "select"}`];
@@ -803,9 +826,7 @@ export class AskUserComponent implements Component, Focusable {
 		if (question.hasDefault) hints.push("s use default");
 		if (this.viewport.maxScroll > 0) hints.push("PgUp/PgDn preview");
 		if (this.isInputRow() && question.options.length > 0) hints.push("↑ back to options");
-		if (toggleHint) hints.push(toggleHint);
-		hints.push("Esc cancel");
-		return this.theme.fg("dim", hints.join(" · "));
+		return withControls(hints);
 	}
 
 	render(width: number): string[] {
@@ -853,7 +874,7 @@ export class AskUserComponent implements Component, Focusable {
 			? this.wrap(this.theme.fg("warning", `⚠ ${this.notice}`), contentWidth).slice(0, MAX_NOTICE_LINES)
 			: [];
 		const inputBlock = this.isReview ? this.renderSubmitBar(contentWidth) : this.renderInputBar(contentWidth);
-		const hintBlock = [this.hintLine()];
+		const hintBlock = [this.hintLine(contentWidth)];
 
 		let remaining = contentRows;
 		const take = (block: string[]): string[] => {