@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 +22 -0
- package/README.md +52 -2
- package/dist/index.d.ts +21 -0
- package/dist/index.js +48 -0
- package/example.png +0 -0
- package/extensions/ask-question.ts +57 -0
- package/package.json +60 -4
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
|
-
#
|
|
1
|
+
# `@hcflabs/pi-ask-question`
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+

|
|
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.
|
package/dist/index.d.ts
ADDED
|
@@ -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": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|