pi-ask-user-questions 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qunm00
+
+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,127 @@
+# pi-ask-user-questions
+
+**The agent asks a question. You type the answer. There is no list to pick from.**
+
+If you want the agent to *offer you options* — searchable lists, multi-select, split-pane
+previews, overlay modes — use [`pi-ask-user`](https://www.npmjs.com/package/pi-ask-user)
+instead. It is further along and does more. This package is for the other case: you want
+to be **asked in words and answer in words**, and you want to be asked **less**.
+
+## How it differs
+
+|  | `pi-ask-user-questions` (this) | `pi-ask-user` |
+|---|---|---|
+| Answer format | free-form text, always | option list, with freeform as an extra |
+| Interaction | one question, one text field | menus, multi-select, split-pane preview, configurable overlay/inline |
+| Effect on interruptions | guidelines push the agent to ask **less** | bundles a skill that **mandates** asking at decision gates |
+| Maturity | new | 25 published versions, actively maintained |
+
+That last row is the real trade. This package is deliberately narrower: fewer moving parts,
+and one abort-safe input path instead of a configurable TUI. If you want richer selection
+UI, the other package is the better tool and there is no reason to fight it.
+
+## The anti-pester stance
+
+The usual failure mode is an agent that asks about everything. Three things push back,
+all in the tool's `promptGuidelines` — which Pi appends to your system prompt while the
+tool is active:
+
+- **Batch everything into one call.** The agent collects all its questions up front, so you
+  answer in a single pass instead of being interrupted repeatedly.
+- **Don't ask what you can work out.** Reading the repo, inferring, or choosing a sensible
+  default is preferred over asking. State the assumption and move on.
+- **Never invent an answer.** Skipped questions come back marked as skips, with an explicit
+  instruction not to fill in the blank. A skip means "no answer", not "assume something".
+
+[`pi-ask-user`](https://www.npmjs.com/package/pi-ask-user) takes the opposite position: it
+ships a skill that *requires* the agent to stop and ask at high-stakes decision points. Both
+are defensible. If being interrupted too much is your problem, this is the one you want.
+
+The exact guidelines, verbatim:
+
+> - Batch every question you need into a single `ask_user` call; the user answers them in sequence.
+> - Ask only when you truly cannot proceed. Never ask what you can read from the repo, infer, or decide yourself.
+> - State an assumption and continue instead of asking.
+> - Phrase each question to be answerable in one typed sentence — the user types text, they do not pick from options.
+> - A skipped question means the user declined to answer. Never fabricate an answer; re-ask or proceed without it.
+
+## Install
+
+```bash
+# from npm
+pi install npm:pi-ask-user-questions
+
+# from git
+pi install git:github.com/qunm00/pi-ask-user-questions@v1
+
+# try it for one run without saving
+pi -e npm:pi-ask-user-questions
+```
+
+Then enable the tool in a session if it is not already active:
+
+```
+/tools
+```
+
+## How it behaves
+
+- **One dialog at a time**, titled `Question 2 of 3: <the question>`. Questions are asked
+  and answered in the order given.
+- **Enter** submits. **Escape** skips that one question and moves to the next — you keep
+  your momentum instead of restarting the batch.
+- Submitting an empty answer re-prompts once, because a stray Enter is usually an accident.
+  Press Escape at the re-prompt to skip.
+- Skipped questions are reported to the model explicitly, with an instruction not to invent
+  an answer.
+- Batching holds even when the agent is careless: the tool is registered with
+  `executionMode: "sequential"`, so three separate `ask_user` calls in one assistant message
+  queue instead of stacking.
+
+## Limitations
+
+These are deliberate, not oversights:
+
+- **Single-line answers.** `ui.editor()` accepts no `AbortSignal`, so aborting a turn while
+  a multiline dialog is open would leave the dialog waiting and the turn unable to finish.
+  Single-line input is abort-safe. Pasted multi-line text is preserved, but you cannot type
+  a newline mid-answer.
+- **No `placeholder` support.** In pi 0.87.1 the `ui.input` placeholder argument is taken by
+  `ExtensionInputComponent` as `_placeholder` and never read. There is nowhere to put an
+  example answer, so put any needed guidance in the question text.
+- **No timeout.** If the agent asks and you walk away, the dialog waits. Press Escape to skip.
+- **Needs an interactive session.** In `print`/`json` mode there is no UI; the tool returns
+  a message telling the model to ask in plain text instead of failing the turn.
+
+## Development
+
+```bash
+npm install
+npm test          # 19 tests, includes a real npm pack + install + load check
+npm run test:unit # skips the slow sandbox install check
+npm run typecheck # tsc --noEmit
+
+# load it into a live pi without installing
+pi -e ./extensions/ask-user.ts
+
+# then, in that session:
+/ask-demo
+```
+
+`/ask-demo` exercises the real dialog path without involving a model, so you can check
+rendering and the skip/empty behaviour by hand.
+
+Tests run on [`@marcfargas/pi-test-harness`](https://github.com/marcfargas/pi-test-harness),
+which keeps pi real — real extension loading, real hooks, real tool registry — and
+substitutes only the model boundary (`streamFn`) and `ctx.ui.*`.
+
+That harness targets pi 0.75.x. Three things moved by 0.87 and are bridged in
+`__tests__/support/pi-compat.ts` and `vitest.config.ts`; the comments there explain each
+one. Remove those shims once a harness release supports 0.87.
+
+Because the harness substitutes `ctx.ui.*`, **no automated test can check terminal
+rendering**. `/ask-demo` is the manual gate for that.
+
+## License
+
+MIT

package/extensions/ask-user.ts

@@ -0,0 +1,243 @@
+/**
+ * ask_user — ask the user a question, get a typed free-form answer.
+ *
+ * The agent calls this tool; the user answers by typing. There are no options
+ * to pick from. When several questions are needed, the user answers them one
+ * after another in a single run.
+ *
+ * Design notes worth keeping:
+ *
+ *  - `executionMode: "sequential"` is load-bearing. Tool calls from one
+ *    assistant message can otherwise run in parallel, and pi renders dialogs
+ *    into a single shared editor container — two concurrent dialogs collide.
+ *    Sequential also means that when the agent asks three questions as three
+ *    separate calls, they queue instead of stacking.
+ *
+ *  - The dialog title is the ONLY channel that renders. In pi 0.87.1
+ *    `ui.input`'s second argument is taken by `ExtensionInputComponent` as
+ *    `_placeholder` and never read, so it is a silent no-op. We therefore put
+ *    the question, the progress counter and any hint all in the title, and
+ *    deliberately expose no `placeholder` parameter to the model.
+ *
+ *  - `ui.editor()` (multiline) is intentionally NOT used. Unlike `ui.input`,
+ *    it accepts no AbortSignal, so aborting a turn while a multiline dialog is
+ *    open leaves the dialog waiting and the turn unable to finish. Single-line
+ *    input is abort-safe. Multiline is a possible follow-up once that path
+ *    can be made cancellable.
+ *
+ *  - `promptGuidelines` do the real work of stopping the agent pestering the
+ *    user: batch into one call, don't ask what you can determine yourself, and
+ *    never invent an answer.
+ */
+
+import { Type } from "typebox";
+import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+interface AskQuestion {
+	question: string;
+	hint?: string;
+}
+
+interface AskAnswer {
+	question: string;
+	hint?: string;
+	answer: string;
+	skipped: boolean;
+}
+
+interface AskDetails {
+	answers: AskAnswer[];
+	/** True when an abort signal stopped the batch before every question was shown. */
+	aborted: boolean;
+}
+
+const MAX_QUESTIONS = 10;
+
+/**
+ * Build the dialog title. This is the only text the user actually sees, so it
+ * carries the counter, the question and the hint. `Text` wraps, so length is
+ * not a problem.
+ */
+function formatTitle(index: number, total: number, question: AskQuestion, note?: string): string {
+	const position = `Question ${index + 1} of ${total}`;
+	const prefix = note ? `${position} — ${note}` : position;
+	return `${prefix}: ${question.question}${question.hint ? ` (${question.hint})` : ""}`;
+}
+
+/**
+ * Ask each question in order, one dialog at a time. Never returns until every
+ * question is answered, skipped, or the turn is aborted.
+ */
+async function askQuestions(
+	ctx: ExtensionContext,
+	questions: AskQuestion[],
+	signal: AbortSignal | undefined,
+): Promise<AskDetails> {
+	const answers: AskAnswer[] = [];
+	let aborted = false;
+
+	for (const [index, question] of questions.entries()) {
+		if (signal?.aborted) {
+			aborted = true;
+			break;
+		}
+
+		let answer = await ctx.ui.input(formatTitle(index, questions.length, question), undefined, { signal });
+
+		if (signal?.aborted) {
+			aborted = true;
+			break;
+		}
+
+		// An accidental Enter is likelier than a deliberate blank answer, so
+		// confirm once before recording it as a skip. Escape skips immediately.
+		if (answer !== undefined && answer.trim() === "") {
+			answer = await ctx.ui.input(
+				formatTitle(index, questions.length, question, "empty, Escape to skip"),
+				undefined,
+				{ signal },
+			);
+			if (signal?.aborted) {
+				aborted = true;
+				break;
+			}
+		}
+
+		const text = answer ?? "";
+		const skipped = text.trim() === "";
+		answers.push({
+			question: question.question,
+			hint: question.hint,
+			answer: skipped ? "" : text,
+			skipped,
+		});
+	}
+
+	return { answers, aborted };
+}
+
+/** Model-facing transcript. Explicit about skips so nothing gets invented. */
+function buildContent(details: AskDetails, requested: number): string {
+	const lines: string[] = [];
+
+	for (const [index, entry] of details.answers.entries()) {
+		lines.push(`Q${index + 1}: ${entry.question}`);
+		lines.push(`A${index + 1}: ${entry.skipped ? "(skipped — the user did not answer)" : entry.answer}`);
+		lines.push("");
+	}
+
+	if (details.answers.length === 0) {
+		lines.push("The user did not answer any question.");
+	}
+
+	const skipped = details.answers.filter((entry) => entry.skipped).length;
+	if (skipped > 0) {
+		lines.push(
+			`${skipped} of ${requested} question(s) went unanswered. Do not fabricate an answer — ` +
+				`either re-ask ${skipped === 1 ? "it" : "them"} or proceed without ${skipped === 1 ? "it" : "them"}.`,
+		);
+	}
+
+	const neverShown = requested - details.answers.length;
+	if (details.aborted) {
+		lines.push(
+			`The turn was interrupted before ${neverShown} question(s) were shown. ` +
+				"Do not assume answers to questions that were never asked.",
+		);
+	}
+
+	return lines.join("\n").trimEnd();
+}
+
+const askUserTool = defineTool({
+	name: "ask_user",
+	label: "Ask User",
+	description:
+		"Ask the user a question and read back the answer they type. The user types free-form text — " +
+		"there is no list of options to choose from, so phrase each question so it can be answered in " +
+		"a sentence. Put every question you need into a single call; the user answers them in sequence. " +
+		"Use this only when you genuinely cannot proceed: never ask what you can read from the repo, " +
+		"infer, or decide yourself. If a question comes back skipped, the user declined to answer it — " +
+		"never invent an answer for it.",
+	promptSnippet: "Ask the user a question and read their typed free-form answer",
+	promptGuidelines: [
+		"Batch every question you need into a single ask_user call; the user answers them in sequence.",
+		"Ask only when you truly cannot proceed. Never ask what you can read from the repo, infer, or decide yourself.",
+		"State an assumption and continue instead of asking.",
+		"Phrase each question to be answerable in one typed sentence — the user types text, they do not pick from options.",
+		"A skipped question means the user declined to answer. Never fabricate an answer; re-ask or proceed without it.",
+	],
+	parameters: Type.Object({
+		questions: Type.Array(
+			Type.Object({
+				question: Type.String({
+					description: "The question to ask, phrased so it can be answered in one typed sentence.",
+				}),
+				hint: Type.Optional(
+					Type.String({
+						description: "Optional short context for why you are asking, shown with the question.",
+					}),
+				),
+			}),
+			{
+				minItems: 1,
+				maxItems: MAX_QUESTIONS,
+				description: "Every question you need answered, asked and answered in this order.",
+			},
+		),
+	}),
+	executionMode: "sequential",
+	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		if (!ctx.hasUI) {
+			return {
+				content: [
+					{
+						type: "text",
+						text:
+							"ask_user needs an interactive session and this run has no UI. " +
+							"Ask the user directly in plain text instead of calling this tool.",
+					},
+				],
+				details: { answers: [], aborted: false } as AskDetails,
+			};
+		}
+
+		const details = await askQuestions(ctx, params.questions, signal);
+		return {
+			content: [{ type: "text", text: buildContent(details, params.questions.length) }],
+			details,
+		};
+	},
+});
+
+/** Questions used by /ask-demo to exercise the dialogs without a model. */
+const DEMO_QUESTIONS: AskQuestion[] = [
+	{ question: "What should I call you?", hint: "used in the greeting" },
+	{ question: "What are we working on today?" },
+];
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool(askUserTool);
+
+	pi.registerCommand("ask-demo", {
+		description: "Manually test the ask dialogs (same code path as ask_user)",
+		handler: async (_args, ctx) => {
+			ctx.ui.notify(`/ask-demo invoked (mode=${ctx.mode}, hasUI=${ctx.hasUI})`, "info");
+
+			if (!ctx.hasUI) {
+				ctx.ui.notify("ask-demo needs an interactive session. Drop --mode/--print.", "error");
+				return;
+			}
+
+			const details = await askQuestions(ctx, DEMO_QUESTIONS, ctx.signal);
+
+			for (const [index, entry] of details.answers.entries()) {
+				ctx.ui.notify(
+					`Q${index + 1}: ${entry.skipped ? "skipped (Escape)" : entry.answer}`,
+					entry.skipped ? "warning" : "info",
+				);
+			}
+			if (details.aborted) ctx.ui.notify("aborted before all questions were shown", "warning");
+		},
+	});
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "pi-ask-user-questions",
+  "version": "0.1.0",
+  "description": "Let the agent ask you a question and type your answer. No multiple choice. Batch questions are answered consecutively.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension"
+  ],
+  "files": [
+    "extensions/**/*.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/ask-user.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:unit": "vitest run __tests__/ask-user.test.ts __tests__/mock-ui.test.ts __tests__/smoke.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "0.87.1",
+    "@earendil-works/pi-ai": "0.87.1",
+    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@marcfargas/pi-test-harness": "0.6.1",
+    "@types/node": "^26.6.3",
+    "typebox": "^1.1.38",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+github.com/qunm00/pi-ask-user-questions.git"
+  },
+  "homepage": "https://github.com/qunm00/pi-ask-user-questions#readme",
+  "bugs": {
+    "url": "https://github.com/qunm00/pi-ask-user-questions/issues"
+  }
+}