@hcflabs/pi-ask-question 0.0.0-stage → 3.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Henry Wang
4
+ Copyright (c) 2026 hcflabs
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,53 @@
1
- # Temporary Holding Version
1
+ # `@hcflabs/pi-ask-question`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Pause Pi until the user selects a question option with the keyboard or enters a custom answer. Agents and extensions get an explicit answer without parsing free-form chat.
4
+
5
+ ![Pi asking the user to choose a database](./example.png)
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ pi install npm:@hcflabs/pi-ask-question
11
+ ```
12
+
13
+ ## Use
14
+
15
+ Call `ask_question` in an interactive TUI with a question and one to three options in preference order. Pi waits for the selected option or custom answer.
16
+
17
+ | Surface | Type | Purpose |
18
+ | --- | --- | --- |
19
+ | `ask_question` | tool | For agents: pause execution to get one user answer. |
20
+
21
+ ```json
22
+ {
23
+ "question": "Which database should we use?",
24
+ "options": [
25
+ { "label": "PostgreSQL", "description": "Shared server database" },
26
+ { "label": "SQLite", "description": "Local, embedded storage" },
27
+ { "label": "File", "description": "Plain file storage" }
28
+ ]
29
+ }
30
+ ```
31
+
32
+ The UI marks the first option `(Recommended)` and adds `Something else.` for custom text input. Descriptions are optional.
33
+
34
+ While a question is open, the tool publishes `herdr:blocked` with `Input required`. Completion, cancellation, or failure clears the status.
35
+
36
+ ## API
37
+
38
+ Import from the package root, `@hcflabs/pi-ask-question`.
39
+
40
+ | Surface | Type | Purpose |
41
+ | --- | --- | --- |
42
+ | `askQuestion(params, ctx, signal)` | function | Runs the validated question flow for another extension. |
43
+ | `AskQuestionOption` | type | Describes a question option. |
44
+ | `AskQuestionRequest` | type | Describes a question request. |
45
+ | `AskQuestionResult` | type | Describes the flow result. |
46
+
47
+ The answer is `null` for cancellation, empty custom input, invalid requests, or non-TUI calls. Invalid requests and non-TUI calls also include `error`.
48
+
49
+ ## Limits and recovery
50
+
51
+ Questions and option labels must not be blank. Labels must be unique, without regard to case. `Something else.` is reserved for the custom answer option.
52
+
53
+ Non-interactive calls return `UI not available (running in non-interactive mode)`. Ask in plain assistant text instead. Aborting the tool closes the pending question.
@@ -0,0 +1,21 @@
1
+ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
2
+ export interface AskQuestionOption {
3
+ label: string;
4
+ description?: string;
5
+ }
6
+ export interface AskQuestionRequest {
7
+ question: string;
8
+ options: AskQuestionOption[];
9
+ }
10
+ export interface AskQuestionResult {
11
+ question: string;
12
+ options: string[];
13
+ answer: string | null;
14
+ wasCustom?: boolean;
15
+ selectedIndex?: number;
16
+ error?: string;
17
+ }
18
+ type AskQuestionContext = Pick<ExtensionContext, "mode" | "ui">;
19
+ /** Run the validated interactive question flow shared by consumers. */
20
+ export declare function askQuestion(params: AskQuestionRequest, ctx: AskQuestionContext, signal?: AbortSignal): Promise<AskQuestionResult>;
21
+ export {};
package/dist/index.js ADDED
@@ -0,0 +1,48 @@
1
+ const CUSTOM_OPTION_LABEL = "Something else.";
2
+ const RECOMMENDED_SUFFIX = /\s*\(recommended\)\s*$/i;
3
+ /** Run the validated interactive question flow shared by consumers. */
4
+ export async function askQuestion(params, ctx, signal) {
5
+ const question = params.question.trim();
6
+ const suppliedOptions = params.options.map((option) => ({
7
+ label: option.label.trim(),
8
+ description: option.description?.trim(),
9
+ }));
10
+ const options = suppliedOptions.map((option) => option.label);
11
+ if (ctx.mode !== "tui") {
12
+ const error = "UI not available (running in non-interactive mode)";
13
+ return { question, options, answer: null, error };
14
+ }
15
+ let validationError;
16
+ if (!question)
17
+ validationError = "Question must not be blank";
18
+ else if (suppliedOptions.length < 1 || suppliedOptions.length > 3)
19
+ validationError = "Provide one to three options";
20
+ else if (suppliedOptions.some((option) => !option.label))
21
+ validationError = "Option labels must not be blank";
22
+ else if (new Set(options.map((option) => option.toLowerCase())).size !== options.length)
23
+ validationError = "Option labels must be unique";
24
+ else if (options.some((option) => option.toLowerCase() === CUSTOM_OPTION_LABEL.toLowerCase()))
25
+ validationError = `Option label "${CUSTOM_OPTION_LABEL}" is reserved`;
26
+ if (validationError)
27
+ return { question, options, answer: null, error: validationError };
28
+ const choices = suppliedOptions.map((option, index) => {
29
+ const label = index === 0 ? `${option.label.replace(RECOMMENDED_SUFFIX, "")} (Recommended)` : option.label;
30
+ return `${index + 1}. ${label}${option.description ? ` — ${option.description}` : ""}`;
31
+ });
32
+ choices.push(`${choices.length + 1}. ${CUSTOM_OPTION_LABEL}`);
33
+ const selected = await ctx.ui.select(question, choices, { signal });
34
+ const selectedIndex = selected === undefined ? -1 : choices.indexOf(selected);
35
+ const wasCustom = selectedIndex === suppliedOptions.length;
36
+ const answer = wasCustom
37
+ ? (await ctx.ui.input(CUSTOM_OPTION_LABEL, "Type your answer", { signal }))?.trim()
38
+ : suppliedOptions[selectedIndex]?.label;
39
+ if (!answer)
40
+ return { question, options, answer: null };
41
+ return {
42
+ question,
43
+ options,
44
+ answer,
45
+ wasCustom,
46
+ selectedIndex: wasCustom ? undefined : selectedIndex + 1,
47
+ };
48
+ }
package/example.png ADDED
Binary file
@@ -0,0 +1,57 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+ import { askQuestion } from "@hcflabs/pi-ask-question";
3
+ import { Type } from "typebox";
4
+
5
+ const QuestionOptionSchema = Type.Object({
6
+ label: Type.String({ description: "Display label for the option", minLength: 1 }),
7
+ description: Type.Optional(Type.String({ description: "Optional description shown below label", minLength: 1 })),
8
+ });
9
+
10
+ const AskQuestionParams = Type.Object({
11
+ question: Type.String({ description: "Question to ask user", minLength: 1 }),
12
+ options: Type.Array(QuestionOptionSchema, {
13
+ description: "One to three meaningful options, ordered with recommended option first",
14
+ minItems: 1,
15
+ maxItems: 3,
16
+ }),
17
+ });
18
+
19
+ export default function askQuestionExtension(pi: ExtensionAPI): void {
20
+ pi.registerTool({
21
+ name: "ask_question",
22
+ label: "Ask Question",
23
+ description: "In interactive TUI sessions, ask user one question with up to three options or a custom answer. First option is shown as recommended.",
24
+ promptSnippet: "In interactive TUI sessions, ask user one question with up to three options or a custom answer",
25
+ promptGuidelines: [
26
+ "In interactive TUI sessions, use ask_question instead of plain assistant text whenever user input is needed to proceed; in non-interactive sessions, ask in plain assistant text.",
27
+ "Give ask_question one to three concise, meaningful options without inventing filler, put recommended option first, and omit '(Recommended)' from its label.",
28
+ "Give ask_question option descriptions only when they explain meaningful tradeoffs; never repeat option labels.",
29
+ ],
30
+ parameters: AskQuestionParams,
31
+ executionMode: "sequential",
32
+ exposure: "model-only",
33
+
34
+ async execute(_toolCallId, params, signal, _onUpdate, ctx) {
35
+ const interactive = ctx.mode === "tui";
36
+ try {
37
+ if (interactive) pi.events.emit("herdr:blocked", { active: true, label: "Input required" });
38
+ const details = await askQuestion(params, ctx, signal);
39
+ return {
40
+ content: [{
41
+ type: "text" as const,
42
+ text: details.error
43
+ ? `Error: ${details.error}`
44
+ : !details.answer
45
+ ? "User cancelled question"
46
+ : details.wasCustom
47
+ ? `User wrote: ${details.answer}`
48
+ : `User selected: ${details.selectedIndex}. ${details.answer}`,
49
+ }],
50
+ details,
51
+ };
52
+ } finally {
53
+ if (interactive) pi.events.emit("herdr:blocked", { active: false });
54
+ }
55
+ },
56
+ });
57
+ }
package/package.json CHANGED
@@ -1,6 +1,62 @@
1
1
  {
2
2
  "name": "@hcflabs/pi-ask-question",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "3.2.4",
4
+ "description": "Ask Pi users one interactive question with choices or a custom answer.",
5
+ "keywords": [
6
+ "pi-package",
7
+ "pi",
8
+ "question",
9
+ "interactive"
10
+ ],
11
+ "type": "module",
12
+ "engines": {
13
+ "node": ">=22.19.0"
14
+ },
15
+ "license": "MIT",
16
+ "files": [
17
+ "LICENSE",
18
+ "dist",
19
+ "extensions",
20
+ "README.md",
21
+ "example.png"
22
+ ],
23
+ "types": "./dist/index.d.ts",
24
+ "exports": {
25
+ ".": {
26
+ "types": "./dist/index.d.ts",
27
+ "import": "./dist/index.js"
28
+ }
29
+ },
30
+ "scripts": {
31
+ "build": "tsc --project tsconfig.build.json",
32
+ "test": "npm run build && node --test test/*.test.ts",
33
+ "test:manual": "pi --no-extensions -e ./extensions/ask-question.ts --tools ask_question --no-session \"We need storage for a small team app. Before making changes, ask me to choose storage.\"",
34
+ "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck src/*.ts extensions/ask-question.ts test/*.test.ts",
35
+ "prepack": "npm run build",
36
+ "pack:check": "npm pack --dry-run"
37
+ },
38
+ "peerDependencies": {
39
+ "@earendil-works/pi-coding-agent": "^1.3.0",
40
+ "typebox": "^1.3.15"
41
+ },
42
+ "repository": {
43
+ "type": "git",
44
+ "url": "git+https://github.com/hcflabs/pi-harness.git",
45
+ "directory": "extensions/pi-ask-question"
46
+ },
47
+ "bugs": {
48
+ "url": "https://github.com/hcflabs/pi-harness/issues"
49
+ },
50
+ "publishConfig": {
51
+ "access": "public"
52
+ },
53
+ "pi": {
54
+ "extensions": [
55
+ "./extensions/ask-question.ts"
56
+ ],
57
+ "image": "https://raw.githubusercontent.com/hcflabs/pi-harness/main/extensions/pi-ask-question/example.png"
58
+ },
59
+ "devDependencies": {
60
+ "@earendil-works/pi-coding-agent": "1.3.0"
61
+ }
62
+ }