@mrclrchtr/supi-ask-user 1.14.2 → 1.14.3
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/README.md +48 -246
- package/node_modules/@mrclrchtr/supi-core/package.json +12 -3
- package/package.json +17 -6
- package/src/ask-user.ts +22 -17
- package/src/normalize.ts +2 -1
- package/src/render/result.ts +28 -2
- package/src/render/transcript.ts +45 -3
- package/src/schema.ts +19 -12
- package/src/tool/guidance.ts +11 -9
- package/src/types.ts +4 -2
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
# @mrclrchtr/supi-ask-user
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
SuPi Ask-User brings structured decision forms to your [pi](https://github.com/earendil-works/pi) sessions. When the agent needs your input, you get a clear, keyboard-driven form instead of a chat message.
|
|
10
10
|
|
|
11
11
|
## Install
|
|
12
12
|
|
|
@@ -20,6 +20,22 @@ For local development:
|
|
|
20
20
|
pi install ./packages/supi-ask-user
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
+
## What to expect
|
|
24
|
+
|
|
25
|
+
During a session, the agent may pause and open a small form when it needs an explicit decision from you. The form appears directly in the TUI and blocks the agent until you respond.
|
|
26
|
+
|
|
27
|
+
Each form can contain up to ten questions. A question is either a **choice** (pick one or more from a list) or a **text** (type a short answer). The agent can suggest a recommended answer, which is preselected or prefilled for you.
|
|
28
|
+
|
|
29
|
+
All questions are expected to be answered before the form can be submitted. If you leave any question unanswered, the agent receives a "needs discussion" outcome so it can follow up.
|
|
30
|
+
|
|
31
|
+
You can also add comments to individual questions, options, or the whole form if you want to explain your thinking.
|
|
32
|
+
|
|
33
|
+
## Agent-facing behavior
|
|
34
|
+
|
|
35
|
+
`ask_user` is an interactive TUI-only handoff. The agent should use one form for one focused decision, combine related questions instead of opening multiple forms, and wait for the result before doing work that depends on your answer. Only one form can be active at a time.
|
|
36
|
+
|
|
37
|
+
The model-visible result summary is bounded to Pi's default tool-output limits: 2,000 lines or 50KB, whichever is hit first. If a very large response is truncated, the agent is told to ask a focused follow-up for any omitted text it still needs.
|
|
38
|
+
|
|
23
39
|
## Preview
|
|
24
40
|
|
|
25
41
|
<table>
|
|
@@ -51,261 +67,47 @@ pi install ./packages/supi-ask-user
|
|
|
51
67
|
</tr>
|
|
52
68
|
</table>
|
|
53
69
|
|
|
54
|
-
##
|
|
55
|
-
|
|
56
|
-
After install, pi gets one new tool:
|
|
57
|
-
|
|
58
|
-
- **`ask_user`** — open a blocking decision form during a run
|
|
59
|
-
|
|
60
|
-
The tool presents a structured questionnaire in the TUI form and blocks the agent turn until the user responds. It is designed for focused decisions, **not** long surveys or open-ended discovery.
|
|
61
|
-
|
|
62
|
-
Typical use cases:
|
|
63
|
-
|
|
64
|
-
- Clarify a narrow implementation choice
|
|
65
|
-
- Confirm a risky or destructive action
|
|
66
|
-
- Ask for a preference the repo cannot answer
|
|
67
|
-
- Gather one short cluster of related decisions before proceeding
|
|
68
|
-
|
|
69
|
-
## Package surfaces
|
|
70
|
-
|
|
71
|
-
- `@mrclrchtr/supi-ask-user/extension` — pi extension entrypoint, registers the `ask_user` tool
|
|
72
|
-
- `@mrclrchtr/supi-ask-user/api` — reusable types and utilities
|
|
73
|
-
|
|
74
|
-
Example:
|
|
75
|
-
|
|
76
|
-
```ts
|
|
77
|
-
import { normalizeQuestionnaire, AskUserController } from "@mrclrchtr/supi-ask-user/api";
|
|
78
|
-
|
|
79
|
-
const questionnaire = normalizeQuestionnaire(params);
|
|
80
|
-
const controller = new AskUserController(questionnaire);
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
## Request shape
|
|
84
|
-
|
|
85
|
-
`ask_user` accepts a small form with optional framing text:
|
|
86
|
-
|
|
87
|
-
| Field | Type | Description |
|
|
88
|
-
|-------|------|-------------|
|
|
89
|
-
| `title` | string (optional) | Short overall title for the form |
|
|
90
|
-
| `intro` | string (optional) | Why the agent is asking |
|
|
91
|
-
| `questions` | array (1–10) | Choice or text questions |
|
|
92
|
-
|
|
93
|
-
All questions are always required for a full submission. Unanswered questions produce a `needs_discussion` outcome instead of a silent partial submit. The deprecated fields `allowPartialSubmit`, `required`, `initial`, and `allowOther` are rejected with a validation error.
|
|
94
|
-
|
|
95
|
-
## Questions
|
|
96
|
-
|
|
97
|
-
Each question has a `type`, `id`, `header`, and `prompt`. Two question types are supported:
|
|
98
|
-
|
|
99
|
-
### `choice` — fixed options
|
|
100
|
-
|
|
101
|
-
| Field | Type | Description |
|
|
102
|
-
|-------|------|-------------|
|
|
103
|
-
| `options` | array (2–12) | Allowed answers; each option has the fields below |
|
|
104
|
-
| `multi` | boolean (default: `false`) | Allow selecting multiple options |
|
|
105
|
-
| `recommendation` | string \| string[] | Recommended option value(s). Single-select: a string (default: first option). Multi-select: an array (default: none). |
|
|
106
|
-
|
|
107
|
-
Each `options` entry:
|
|
108
|
-
|
|
109
|
-
| Field | Type | Description |
|
|
110
|
-
|-------|------|-------------|
|
|
111
|
-
| `value` | string | Returned identifier for the response |
|
|
112
|
-
| `label` | string | Displayed option label |
|
|
113
|
-
| `description` | string (optional) | Short sub-label shown under the option |
|
|
114
|
-
| `preview` | string (optional) | Longer explanatory text rendered in the side preview panel |
|
|
115
|
-
|
|
116
|
-
Model yes/no questions as a `choice` with `{ value: "yes", label: "Yes" }` and `{ value: "no", label: "No" }`.
|
|
117
|
-
|
|
118
|
-
### `text` — freeform input
|
|
119
|
-
|
|
120
|
-
| Field | Type | Description |
|
|
121
|
-
|-------|------|-------------|
|
|
122
|
-
| `recommendation` | string (optional) | Suggested text prefilled in the editor |
|
|
123
|
-
| `placeholder` | string (optional) | Placeholder shown before the user types |
|
|
124
|
-
|
|
125
|
-
## Result
|
|
126
|
-
|
|
127
|
-
A completed form returns a result with `details.outcome` set to one of:
|
|
128
|
-
|
|
129
|
-
| Outcome | Meaning |
|
|
130
|
-
|---------|---------|
|
|
131
|
-
| `submitted` | Full submit, every question was answered |
|
|
132
|
-
| `needs_discussion` | One or more questions were left unanswered |
|
|
133
|
-
|
|
134
|
-
`details.responses` is an ordered array matching the original question order. Each response has:
|
|
135
|
-
- `questionId` — matching the original question ID
|
|
136
|
-
- `questionComment` (optional) — user comment on this specific question
|
|
137
|
-
- `answer` — structured response with `kind`, `answered`, and type-specific data
|
|
138
|
-
|
|
139
|
-
**Choice responses** include only touched options (selected options and/or options with comments):
|
|
140
|
-
```ts
|
|
141
|
-
{
|
|
142
|
-
answer: {
|
|
143
|
-
kind: "choice",
|
|
144
|
-
answered: boolean,
|
|
145
|
-
options: Array<{
|
|
146
|
-
value: string;
|
|
147
|
-
label: string;
|
|
148
|
-
selected: boolean;
|
|
149
|
-
comment?: string;
|
|
150
|
-
}>;
|
|
151
|
-
}
|
|
152
|
-
}
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
**Text responses**:
|
|
156
|
-
```ts
|
|
157
|
-
{
|
|
158
|
-
answer: {
|
|
159
|
-
kind: "text",
|
|
160
|
-
answered: boolean,
|
|
161
|
-
value?: string;
|
|
162
|
-
}
|
|
163
|
-
}
|
|
164
|
-
```
|
|
165
|
-
|
|
166
|
-
`details.comment` is the form-level user comment when one was entered.
|
|
167
|
-
|
|
168
|
-
The tool result `details` also includes `title`, `intro`, and the normalized `questions` array (same order as the original request, with internal fields such as `multi` and `recommendedIndexes`). Consumers should rely on `responses` for the user's answers; `questions` is kept for rendering and is not part of the model-facing answer contract.
|
|
169
|
-
|
|
170
|
-
Internal cancel and abort results are not persisted as user responses — they cause the agent turn to be aborted and return an error-style result to the model.
|
|
171
|
-
|
|
172
|
-
## Behavior
|
|
173
|
-
|
|
174
|
-
- Requires pi in interactive (TUI) mode with custom form support — no degraded fallback
|
|
175
|
-
- Only one `ask_user` form may be active at a time; calling `ask_user` while another form is in flight returns an error
|
|
176
|
-
- Cancellation or abort stops the current agent turn
|
|
177
|
-
- Completed forms are summarized in the session tree
|
|
178
|
-
- In pi's normal chat history, completed `ask_user` results can be expanded into a read-only review with `Ctrl+O`; this does not reopen the live form and is separate from `/tree`
|
|
179
|
-
- Do not use `ask_user` for open-ended interviews or repo facts the agent can discover on its own
|
|
180
|
-
|
|
181
|
-
## Tool guidance
|
|
182
|
-
|
|
183
|
-
The tool registers the following prompt guidance that the model sees:
|
|
184
|
-
|
|
185
|
-
- Use ask_user only for blocking user input, not open-ended interviews or repo facts.
|
|
186
|
-
- Use ask_user with 1-10 related questions; prefer one when possible.
|
|
187
|
-
- Use ask_user `choice` for fixed options and ask_user `text` for freeform input; yes/no should be a `choice`.
|
|
188
|
-
- Keep one ask_user form active at a time.
|
|
189
|
-
- Use `recommendation` to suggest default choices or prefilled text.
|
|
190
|
-
- Comments are user UI affordances — do not reference removed fields like `required`, `initial`, `allowOther`, or `allowPartialSubmit`.
|
|
191
|
-
|
|
192
|
-
## UI controls
|
|
70
|
+
## Keyboard reference
|
|
193
71
|
|
|
194
72
|
### Choice questions
|
|
195
73
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
On wide terminals, option previews render side-by-side with the option list. On narrow terminals, previews stack below.
|
|
74
|
+
| Key | Action |
|
|
75
|
+
|-----|--------|
|
|
76
|
+
| `↑` `↓` | Move between options |
|
|
77
|
+
| `Space` | Select / toggle an option |
|
|
78
|
+
| `Enter` | Confirm and advance |
|
|
79
|
+
| `Tab` / `→` | Next question (last question goes to review) |
|
|
80
|
+
| `Shift+Tab` / `←` | Previous question |
|
|
81
|
+
| `n` | Comment on the focused option |
|
|
82
|
+
| `c` | Comment on the current question |
|
|
83
|
+
| `u` | Mark the current question unanswered |
|
|
84
|
+
| `Esc` | Cancel the whole form |
|
|
209
85
|
|
|
210
86
|
### Text questions
|
|
211
87
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
88
|
+
| Key | Action |
|
|
89
|
+
|-----|--------|
|
|
90
|
+
| `Enter` | Submit text and advance |
|
|
91
|
+
| `Tab` | Next question |
|
|
92
|
+
| `Alt+C` | Comment on the current question |
|
|
93
|
+
| `Alt+U` | Mark the current question unanswered |
|
|
94
|
+
| `Esc` | Cancel the whole form |
|
|
219
95
|
|
|
220
96
|
### Review screen
|
|
221
97
|
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
98
|
+
| Key | Action |
|
|
99
|
+
|-----|--------|
|
|
100
|
+
| `↑` `↓` | Move between questions and Submit |
|
|
101
|
+
| `Enter` | Open a question for editing, or submit the form |
|
|
102
|
+
| `←` / `Shift+Tab` | Return to the last question |
|
|
103
|
+
| `c` | Edit the form-level comment |
|
|
104
|
+
| `Esc` | Cancel the whole form |
|
|
229
105
|
|
|
230
106
|
### Comment editors
|
|
231
107
|
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
## Example
|
|
238
|
-
|
|
239
|
-
```json
|
|
240
|
-
{
|
|
241
|
-
"title": "Formatter decision",
|
|
242
|
-
"intro": "I need a couple of explicit choices before I update the repo config.",
|
|
243
|
-
"questions": [
|
|
244
|
-
{
|
|
245
|
-
"type": "choice",
|
|
246
|
-
"id": "formatter",
|
|
247
|
-
"header": "Formatter",
|
|
248
|
-
"prompt": "Which formatter should I configure?",
|
|
249
|
-
"options": [
|
|
250
|
-
{
|
|
251
|
-
"value": "biome",
|
|
252
|
-
"label": "Biome",
|
|
253
|
-
"description": "Lint + format in one tool",
|
|
254
|
-
"preview": "Rust-based linter/formatter. Replaces ESLint + Prettier. Only JS/TS/JSON/CSS. Fastest option."
|
|
255
|
-
},
|
|
256
|
-
{
|
|
257
|
-
"value": "prettier",
|
|
258
|
-
"label": "Prettier",
|
|
259
|
-
"description": "Standalone formatter",
|
|
260
|
-
"preview": "Mature formatter with a large ecosystem of plugins and configuration presets."
|
|
261
|
-
}
|
|
262
|
-
],
|
|
263
|
-
"recommendation": "biome"
|
|
264
|
-
},
|
|
265
|
-
{
|
|
266
|
-
"type": "choice",
|
|
267
|
-
"id": "features",
|
|
268
|
-
"header": "Features",
|
|
269
|
-
"prompt": "Which extra tooling should I set up?",
|
|
270
|
-
"options": [
|
|
271
|
-
{ "value": "vitest", "label": "Vitest" },
|
|
272
|
-
{ "value": "knip", "label": "Knip" },
|
|
273
|
-
{ "value": "lefthook", "label": "Lefthook" }
|
|
274
|
-
],
|
|
275
|
-
"multi": true,
|
|
276
|
-
"recommendation": ["vitest"]
|
|
277
|
-
},
|
|
278
|
-
{
|
|
279
|
-
"type": "text",
|
|
280
|
-
"id": "reason",
|
|
281
|
-
"header": "Reason",
|
|
282
|
-
"prompt": "Anything I should optimize for?",
|
|
283
|
-
"placeholder": "optional"
|
|
284
|
-
}
|
|
285
|
-
]
|
|
286
|
-
}
|
|
287
|
-
```
|
|
288
|
-
|
|
289
|
-
## Source layout
|
|
108
|
+
| Key | Action |
|
|
109
|
+
|-----|--------|
|
|
110
|
+
| `Enter` | Save comment and return |
|
|
111
|
+
| `Esc` | Discard comment edits and return |
|
|
290
112
|
|
|
291
|
-
|
|
292
|
-
- `src/api.ts` — reusable public surface
|
|
293
|
-
- `src/index.ts` — package barrel
|
|
294
|
-
- `src/ask-user.ts` — tool registration and execution boundary
|
|
295
|
-
- `src/schema.ts` — tool-call parameter schema (TypeBox)
|
|
296
|
-
- `src/types.ts` — internal normalized types and response shapes
|
|
297
|
-
- `src/normalize.ts` — validation and lowering into internal types
|
|
298
|
-
- `src/tool/guidance.ts` — prompt guidance and tool description
|
|
299
|
-
- `src/session/controller.ts` — headless decision-form state machine with comment/responses
|
|
300
|
-
- `src/session/lock.ts` — session-scoped concurrency lock
|
|
301
|
-
- `src/ui/choose-renderer.ts` — custom-form capability gate
|
|
302
|
-
- `src/ui/form.ts` — form runner that creates the custom interaction session
|
|
303
|
-
- `src/ui/form-component.ts` — keyboard orchestration for question screens, comment editors, and review
|
|
304
|
-
- `src/ui/form-view.ts` — choice row helpers
|
|
305
|
-
- `src/ui/form-render.ts` — main form rendering for choices, text, comments, and layout frame
|
|
306
|
-
- `src/ui/form-review-render.ts` — review-screen summary cards
|
|
307
|
-
- `src/ui/form-render-primitives.ts` — shared rendering primitives for boxes, wrapping, prompts, and padding
|
|
308
|
-
- `src/ui/types.ts` — shared UI runner types
|
|
309
|
-
- `src/render/result.ts` — tool result shaping
|
|
310
|
-
- `src/render/transcript.ts` — transcript rendering
|
|
311
|
-
- `src/render/tree-summary.ts` — session-tree summary labels
|
|
113
|
+
The recommended option is labeled `[recommended]`. On wide terminals, option previews render side-by-side with the list; on narrow terminals they stack below.
|
|
@@ -1,18 +1,27 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mrclrchtr/supi-core",
|
|
3
|
-
"version": "1.14.
|
|
3
|
+
"version": "1.14.3",
|
|
4
4
|
"description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
|
-
"url": "git+https://github.com/mrclrchtr/supi.git"
|
|
8
|
+
"url": "git+https://github.com/mrclrchtr/supi.git",
|
|
9
|
+
"directory": "packages/supi-core"
|
|
10
|
+
},
|
|
11
|
+
"homepage": "https://github.com/mrclrchtr/supi/tree/main/packages/supi-core#readme",
|
|
12
|
+
"bugs": {
|
|
13
|
+
"url": "https://github.com/mrclrchtr/supi/issues"
|
|
9
14
|
},
|
|
10
15
|
"publishConfig": {
|
|
11
16
|
"access": "public"
|
|
12
17
|
},
|
|
13
18
|
"keywords": [
|
|
14
19
|
"pi",
|
|
15
|
-
"pi-coding-agent"
|
|
20
|
+
"pi-coding-agent",
|
|
21
|
+
"supi",
|
|
22
|
+
"extension-utils",
|
|
23
|
+
"settings",
|
|
24
|
+
"configuration"
|
|
16
25
|
],
|
|
17
26
|
"files": [
|
|
18
27
|
"src/**/*.ts",
|
package/package.json
CHANGED
|
@@ -1,11 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mrclrchtr/supi-ask-user",
|
|
3
|
-
"version": "1.14.
|
|
3
|
+
"version": "1.14.3",
|
|
4
4
|
"description": "SuPi ask-user extension — rich questionnaire UI for structured agent-user decisions",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
|
-
"url": "git+https://github.com/mrclrchtr/supi.git"
|
|
8
|
+
"url": "git+https://github.com/mrclrchtr/supi.git",
|
|
9
|
+
"directory": "packages/supi-ask-user"
|
|
10
|
+
},
|
|
11
|
+
"homepage": "https://github.com/mrclrchtr/supi/tree/main/packages/supi-ask-user#readme",
|
|
12
|
+
"bugs": {
|
|
13
|
+
"url": "https://github.com/mrclrchtr/supi/issues"
|
|
9
14
|
},
|
|
10
15
|
"publishConfig": {
|
|
11
16
|
"access": "public"
|
|
@@ -13,15 +18,20 @@
|
|
|
13
18
|
"keywords": [
|
|
14
19
|
"pi-package",
|
|
15
20
|
"pi",
|
|
16
|
-
"pi-coding-agent"
|
|
21
|
+
"pi-coding-agent",
|
|
22
|
+
"pi-extension",
|
|
23
|
+
"ask-user",
|
|
24
|
+
"questionnaire",
|
|
25
|
+
"decision-form",
|
|
26
|
+
"interactive",
|
|
27
|
+
"tui"
|
|
17
28
|
],
|
|
18
29
|
"files": [
|
|
19
30
|
"src/**/*.ts",
|
|
20
31
|
"!__tests__"
|
|
21
32
|
],
|
|
22
|
-
"main": "src/api.ts",
|
|
23
33
|
"dependencies": {
|
|
24
|
-
"@mrclrchtr/supi-core": "1.14.
|
|
34
|
+
"@mrclrchtr/supi-core": "1.14.3"
|
|
25
35
|
},
|
|
26
36
|
"bundledDependencies": [
|
|
27
37
|
"@mrclrchtr/supi-core"
|
|
@@ -46,8 +56,9 @@
|
|
|
46
56
|
"extensions": [
|
|
47
57
|
"./src/extension.ts"
|
|
48
58
|
],
|
|
49
|
-
"image": "https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/
|
|
59
|
+
"image": "https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-choice-preview.png"
|
|
50
60
|
},
|
|
61
|
+
"main": "src/api.ts",
|
|
51
62
|
"exports": {
|
|
52
63
|
"./api": "./src/api.ts",
|
|
53
64
|
"./extension": "./src/extension.ts",
|
package/src/ask-user.ts
CHANGED
|
@@ -1,12 +1,18 @@
|
|
|
1
1
|
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
2
2
|
import { formatTitle, signalWaiting } from "@mrclrchtr/supi-core/terminal";
|
|
3
3
|
import { AskUserValidationError, normalizeQuestionnaire } from "./normalize.ts";
|
|
4
|
-
import { type AskUserToolResult,
|
|
4
|
+
import { type AskUserToolResult, buildResult } from "./render/result.ts";
|
|
5
5
|
import { renderAskUserCall, renderAskUserResult } from "./render/transcript.ts";
|
|
6
6
|
import { buildTreeSummaryLabel } from "./render/tree-summary.ts";
|
|
7
7
|
import { type AskUserParams, AskUserParamsSchema } from "./schema.ts";
|
|
8
8
|
import { ActiveQuestionnaireLock } from "./session/lock.ts";
|
|
9
|
-
import {
|
|
9
|
+
import {
|
|
10
|
+
ASK_USER_TOOL_LABEL,
|
|
11
|
+
ASK_USER_TOOL_NAME,
|
|
12
|
+
promptGuidelines,
|
|
13
|
+
promptSnippet,
|
|
14
|
+
toolDescription,
|
|
15
|
+
} from "./tool/guidance.ts";
|
|
10
16
|
import type {
|
|
11
17
|
AskUserInteractionResult,
|
|
12
18
|
AskUserOutcome,
|
|
@@ -15,9 +21,6 @@ import type {
|
|
|
15
21
|
} from "./types.ts";
|
|
16
22
|
import { runQuestionnaire } from "./ui/choose-renderer.ts";
|
|
17
23
|
|
|
18
|
-
const TOOL_NAME = "ask_user";
|
|
19
|
-
const TOOL_LABEL = "Ask User";
|
|
20
|
-
|
|
21
24
|
export type AskUserExecutionContext = Pick<ExtensionContext, "cwd" | "hasUI" | "mode" | "abort"> & {
|
|
22
25
|
ui: {
|
|
23
26
|
custom?: unknown;
|
|
@@ -33,18 +36,20 @@ export default function askUserExtension(pi: ExtensionAPI): void {
|
|
|
33
36
|
const lock = new ActiveQuestionnaireLock();
|
|
34
37
|
|
|
35
38
|
pi.registerTool<typeof AskUserParamsSchema, AskUserToolDetails>({
|
|
36
|
-
name:
|
|
37
|
-
label:
|
|
39
|
+
name: ASK_USER_TOOL_NAME,
|
|
40
|
+
label: ASK_USER_TOOL_LABEL,
|
|
38
41
|
description: toolDescription,
|
|
39
42
|
promptSnippet,
|
|
40
43
|
promptGuidelines,
|
|
41
44
|
parameters: AskUserParamsSchema,
|
|
45
|
+
executionMode: "sequential",
|
|
42
46
|
// biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
|
|
43
47
|
async execute(_toolCallId, params, signal, _onUpdate, ctx) {
|
|
44
48
|
return executeAskUser(params, signal, ctx, lock, pi);
|
|
45
49
|
},
|
|
46
50
|
renderCall: (args, theme) => renderAskUserCall(args, theme),
|
|
47
|
-
renderResult: (result, options, theme) =>
|
|
51
|
+
renderResult: (result, options, theme, context) =>
|
|
52
|
+
renderAskUserResult(result, theme, options, context),
|
|
48
53
|
});
|
|
49
54
|
}
|
|
50
55
|
|
|
@@ -61,19 +66,19 @@ export async function executeAskUser(
|
|
|
61
66
|
questionnaire = normalizeQuestionnaire(params);
|
|
62
67
|
} catch (error) {
|
|
63
68
|
if (error instanceof AskUserValidationError) {
|
|
64
|
-
|
|
69
|
+
throw new Error(error.message, { cause: error });
|
|
65
70
|
}
|
|
66
71
|
throw error;
|
|
67
72
|
}
|
|
68
73
|
|
|
69
74
|
if (!ctx.hasUI || ctx.mode !== "tui") {
|
|
70
|
-
|
|
71
|
-
"
|
|
75
|
+
throw new Error(
|
|
76
|
+
"ask_user requires an interactive TUI session. No user-facing form UI is available in the current mode.",
|
|
72
77
|
);
|
|
73
78
|
}
|
|
74
79
|
if (!lock.acquire()) {
|
|
75
|
-
|
|
76
|
-
"
|
|
80
|
+
throw new Error(
|
|
81
|
+
"another ask_user form is already in flight. Wait for it to complete before calling ask_user again.",
|
|
77
82
|
);
|
|
78
83
|
}
|
|
79
84
|
|
|
@@ -95,15 +100,15 @@ export async function executeAskUser(
|
|
|
95
100
|
});
|
|
96
101
|
|
|
97
102
|
if (outcome === "unsupported") {
|
|
98
|
-
|
|
99
|
-
"
|
|
103
|
+
throw new Error(
|
|
104
|
+
"ask_user requires a TUI with custom form support. Do not use ask_user in non-interactive or degraded UI sessions.",
|
|
100
105
|
);
|
|
101
106
|
}
|
|
102
107
|
|
|
103
|
-
// Internal cancel/abort: treat as control flow, abort the turn
|
|
108
|
+
// Internal cancel/abort: treat as control flow, abort the turn, and mark the tool failed.
|
|
104
109
|
if (isInternalInteractionResult(outcome)) {
|
|
105
110
|
ctx.abort();
|
|
106
|
-
|
|
111
|
+
throw new Error("The user interaction was cancelled.");
|
|
107
112
|
}
|
|
108
113
|
|
|
109
114
|
pi.appendEntry(buildTreeSummaryLabel(questionnaire));
|
package/src/normalize.ts
CHANGED
|
@@ -242,8 +242,9 @@ function resolveIndexes(args: {
|
|
|
242
242
|
seen.add(trimmed);
|
|
243
243
|
const index = options.findIndex((option) => option.value === trimmed);
|
|
244
244
|
if (index < 0) {
|
|
245
|
+
const allowed = options.map((option) => `"${option.value}"`).join(", ");
|
|
245
246
|
throw new AskUserValidationError(
|
|
246
|
-
`choice question "${questionId}" recommendation value "${trimmed}" does not match any option value.`,
|
|
247
|
+
`choice question "${questionId}" recommendation value "${trimmed}" does not match any option value. Allowed values: [${allowed}].`,
|
|
247
248
|
);
|
|
248
249
|
}
|
|
249
250
|
return index;
|
package/src/render/result.ts
CHANGED
|
@@ -1,4 +1,10 @@
|
|
|
1
|
-
import
|
|
1
|
+
import {
|
|
2
|
+
type AgentToolResult,
|
|
3
|
+
DEFAULT_MAX_BYTES,
|
|
4
|
+
DEFAULT_MAX_LINES,
|
|
5
|
+
formatSize,
|
|
6
|
+
truncateHead,
|
|
7
|
+
} from "@earendil-works/pi-coding-agent";
|
|
2
8
|
import type {
|
|
3
9
|
AskUserDetails,
|
|
4
10
|
AskUserErrorDetails,
|
|
@@ -26,7 +32,12 @@ export function buildResult(
|
|
|
26
32
|
};
|
|
27
33
|
|
|
28
34
|
return {
|
|
29
|
-
content: [
|
|
35
|
+
content: [
|
|
36
|
+
{
|
|
37
|
+
type: "text",
|
|
38
|
+
text: truncateModelVisibleSummary(summarizeOutcome(questionnaire.questions, outcome)),
|
|
39
|
+
},
|
|
40
|
+
],
|
|
30
41
|
details,
|
|
31
42
|
};
|
|
32
43
|
}
|
|
@@ -39,6 +50,21 @@ export function buildErrorResult(message: string): AskUserToolResult {
|
|
|
39
50
|
};
|
|
40
51
|
}
|
|
41
52
|
|
|
53
|
+
function truncateModelVisibleSummary(summary: string): string {
|
|
54
|
+
const truncation = truncateHead(summary, {
|
|
55
|
+
maxLines: DEFAULT_MAX_LINES,
|
|
56
|
+
maxBytes: DEFAULT_MAX_BYTES,
|
|
57
|
+
});
|
|
58
|
+
|
|
59
|
+
if (!truncation.truncated) return summary;
|
|
60
|
+
|
|
61
|
+
const notice = truncation.firstLineExceedsLimit
|
|
62
|
+
? `[Output truncated: first response line exceeds ${formatSize(truncation.maxBytes)}; ask a focused follow-up for omitted text.]`
|
|
63
|
+
: `[Output truncated: showing ${truncation.outputLines}/${truncation.totalLines} lines (${formatSize(truncation.outputBytes)}/${formatSize(truncation.totalBytes)}); ask a focused follow-up for omitted text.]`;
|
|
64
|
+
|
|
65
|
+
return truncation.content ? `${truncation.content}\n\n${notice}` : notice;
|
|
66
|
+
}
|
|
67
|
+
|
|
42
68
|
function summarizeOutcome(questions: NormalizedQuestion[], outcome: AskUserOutcome): string {
|
|
43
69
|
const responseLines = outcome.responses.flatMap((response) =>
|
|
44
70
|
formatResponseSummaryLines(questions, response),
|
package/src/render/transcript.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { type AgentToolResult, keyText, type Theme } from "@earendil-works/pi-coding-agent";
|
|
2
2
|
import { Text } from "@earendil-works/pi-tui";
|
|
3
3
|
import type { AskUserParams } from "../schema.ts";
|
|
4
|
+
import { ASK_USER_TOOL_NAME } from "../tool/guidance.ts";
|
|
4
5
|
import type {
|
|
5
6
|
AskUserDetails,
|
|
6
7
|
AskUserOutcomeKind,
|
|
@@ -15,6 +16,11 @@ const DEFAULT_REVIEW_KEY = "Ctrl+O";
|
|
|
15
16
|
|
|
16
17
|
type AskUserRenderOptions = {
|
|
17
18
|
expanded?: boolean;
|
|
19
|
+
isPartial?: boolean;
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
type AskUserRenderContext = {
|
|
23
|
+
isError?: boolean;
|
|
18
24
|
};
|
|
19
25
|
|
|
20
26
|
export function renderAskUserCall(args: AskUserParams, theme: Theme): Text {
|
|
@@ -22,7 +28,7 @@ export function renderAskUserCall(args: AskUserParams, theme: Theme): Text {
|
|
|
22
28
|
const headers = args.questions.map((question) => question.header.trim()).filter(Boolean);
|
|
23
29
|
const label = title || `${headers.length} question${headers.length === 1 ? "" : "s"}`;
|
|
24
30
|
const suffix = title && headers.length > 0 ? ` (${headers.join(", ")})` : headers.join(", ");
|
|
25
|
-
const text = `${theme.fg("toolTitle", theme.bold(
|
|
31
|
+
const text = `${theme.fg("toolTitle", theme.bold(`${ASK_USER_TOOL_NAME} `))}${theme.fg("muted", label)}${suffix ? theme.fg("dim", ` ${suffix}`) : ""}`;
|
|
26
32
|
return new Text(text, 0, 0);
|
|
27
33
|
}
|
|
28
34
|
|
|
@@ -30,9 +36,22 @@ export function renderAskUserResult(
|
|
|
30
36
|
result: Pick<AgentToolResult<AskUserToolDetails>, "content" | "details">,
|
|
31
37
|
theme: Theme,
|
|
32
38
|
options: AskUserRenderOptions = {},
|
|
39
|
+
context: AskUserRenderContext = {},
|
|
33
40
|
): Text {
|
|
34
|
-
if (isErrorDetails(result.details)) {
|
|
35
|
-
return new Text(theme.fg("error", result
|
|
41
|
+
if (context.isError || isErrorDetails(result.details)) {
|
|
42
|
+
return new Text(theme.fg("error", formatErrorResult(result)), 0, 0);
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
if (options.isPartial) {
|
|
46
|
+
return new Text(
|
|
47
|
+
theme.fg("dim", firstTextContent(result) ?? "Waiting for user response..."),
|
|
48
|
+
0,
|
|
49
|
+
0,
|
|
50
|
+
);
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
if (!isAskUserDetails(result.details)) {
|
|
54
|
+
return new Text(theme.fg("error", formatErrorResult(result)), 0, 0);
|
|
36
55
|
}
|
|
37
56
|
|
|
38
57
|
const lines = options.expanded
|
|
@@ -41,6 +60,29 @@ export function renderAskUserResult(
|
|
|
41
60
|
return new Text(lines.join("\n"), 0, 0);
|
|
42
61
|
}
|
|
43
62
|
|
|
63
|
+
function isAskUserDetails(details: unknown): details is AskUserDetails {
|
|
64
|
+
if (typeof details !== "object" || details === null) return false;
|
|
65
|
+
const candidate = details as Partial<AskUserDetails>;
|
|
66
|
+
return (
|
|
67
|
+
(candidate.outcome === "submitted" || candidate.outcome === "needs_discussion") &&
|
|
68
|
+
Array.isArray(candidate.questions) &&
|
|
69
|
+
Array.isArray(candidate.responses)
|
|
70
|
+
);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function formatErrorResult(
|
|
74
|
+
result: Pick<AgentToolResult<AskUserToolDetails>, "content" | "details">,
|
|
75
|
+
): string {
|
|
76
|
+
if (isErrorDetails(result.details)) return result.details.message;
|
|
77
|
+
return firstTextContent(result) ?? "ask_user failed.";
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
function firstTextContent(
|
|
81
|
+
result: Pick<AgentToolResult<AskUserToolDetails>, "content" | "details">,
|
|
82
|
+
): string | undefined {
|
|
83
|
+
return result.content.find((block) => block.type === "text")?.text;
|
|
84
|
+
}
|
|
85
|
+
|
|
44
86
|
function buildCollapsedResultLines(details: AskUserDetails, theme: Theme): string[] {
|
|
45
87
|
const answerLines = buildAnswerLines(details, theme);
|
|
46
88
|
const shownAnswerLines = answerLines.slice(0, COLLAPSED_ANSWER_LIMIT);
|
package/src/schema.ts
CHANGED
|
@@ -1,32 +1,39 @@
|
|
|
1
1
|
// External, model-facing parameter schema for the redesigned ask_user tool.
|
|
2
2
|
|
|
3
3
|
import { type Static, Type } from "typebox";
|
|
4
|
+
import { ASK_USER_LIMITS } from "./types.ts";
|
|
4
5
|
|
|
5
6
|
const OptionSchema = Type.Object({
|
|
6
|
-
value: Type.String({ description: "
|
|
7
|
+
value: Type.String({ description: "Unique returned id" }),
|
|
7
8
|
label: Type.String({ description: "Displayed label" }),
|
|
8
9
|
description: Type.Optional(
|
|
9
10
|
Type.String({
|
|
10
|
-
description: "Optional
|
|
11
|
+
description: "Optional helper text",
|
|
11
12
|
}),
|
|
12
13
|
),
|
|
13
14
|
preview: Type.Optional(
|
|
14
15
|
Type.String({
|
|
15
|
-
description: "Optional preview",
|
|
16
|
+
description: "Optional focused-option preview",
|
|
16
17
|
}),
|
|
17
18
|
),
|
|
18
19
|
});
|
|
19
20
|
|
|
20
|
-
const ChoiceOptionCount = {
|
|
21
|
-
|
|
21
|
+
const ChoiceOptionCount = {
|
|
22
|
+
minItems: ASK_USER_LIMITS.minChoiceOptions,
|
|
23
|
+
maxItems: ASK_USER_LIMITS.maxChoiceOptions,
|
|
24
|
+
} as const;
|
|
25
|
+
const QuestionCount = {
|
|
26
|
+
minItems: ASK_USER_LIMITS.minQuestions,
|
|
27
|
+
maxItems: ASK_USER_LIMITS.maxQuestions,
|
|
28
|
+
} as const;
|
|
22
29
|
|
|
23
30
|
const ChoiceQuestionSchema = Type.Object({
|
|
24
31
|
type: Type.Literal("choice"),
|
|
25
|
-
id: Type.String({ description: "
|
|
32
|
+
id: Type.String({ description: "Unique question id" }),
|
|
26
33
|
header: Type.String({ description: "Short label" }),
|
|
27
34
|
prompt: Type.String({ description: "Question text" }),
|
|
28
35
|
options: Type.Array(OptionSchema, {
|
|
29
|
-
description: "Allowed options
|
|
36
|
+
description: "Allowed options with unique values",
|
|
30
37
|
...ChoiceOptionCount,
|
|
31
38
|
}),
|
|
32
39
|
multi: Type.Optional(
|
|
@@ -37,17 +44,17 @@ const ChoiceQuestionSchema = Type.Object({
|
|
|
37
44
|
),
|
|
38
45
|
recommendation: Type.Optional(
|
|
39
46
|
Type.Union([Type.String(), Type.Array(Type.String())], {
|
|
40
|
-
description: "Recommended value(s)",
|
|
47
|
+
description: "Recommended value(s): single string, multi array",
|
|
41
48
|
}),
|
|
42
49
|
),
|
|
43
50
|
});
|
|
44
51
|
|
|
45
52
|
const TextQuestionSchema = Type.Object({
|
|
46
53
|
type: Type.Literal("text"),
|
|
47
|
-
id: Type.String({ description: "
|
|
54
|
+
id: Type.String({ description: "Unique question id" }),
|
|
48
55
|
header: Type.String({ description: "Short label" }),
|
|
49
56
|
prompt: Type.String({ description: "Question text" }),
|
|
50
|
-
recommendation: Type.Optional(Type.String({ description: "Suggested
|
|
57
|
+
recommendation: Type.Optional(Type.String({ description: "Suggested text" })),
|
|
51
58
|
placeholder: Type.Optional(Type.String({ description: "Editor placeholder" })),
|
|
52
59
|
});
|
|
53
60
|
|
|
@@ -57,11 +64,11 @@ export const AskUserParamsSchema = Type.Object({
|
|
|
57
64
|
title: Type.Optional(Type.String({ description: "Optional title" })),
|
|
58
65
|
intro: Type.Optional(
|
|
59
66
|
Type.String({
|
|
60
|
-
description: "Optional
|
|
67
|
+
description: "Optional context",
|
|
61
68
|
}),
|
|
62
69
|
),
|
|
63
70
|
questions: Type.Array(QuestionSchema, {
|
|
64
|
-
description: "1-10
|
|
71
|
+
description: "1-10 related questions for one decision",
|
|
65
72
|
...QuestionCount,
|
|
66
73
|
}),
|
|
67
74
|
});
|
package/src/tool/guidance.ts
CHANGED
|
@@ -1,16 +1,18 @@
|
|
|
1
1
|
// Prompt guidance and tool description for the redesigned ask_user tool.
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "@earendil-works/pi-coding-agent";
|
|
4
|
+
|
|
5
|
+
export const ASK_USER_TOOL_NAME = "ask_user";
|
|
6
|
+
export const ASK_USER_TOOL_LABEL = "Ask User";
|
|
7
|
+
|
|
8
|
+
export const toolDescription = `Open a blocking interactive TUI decision form. Use only when the agent needs focused user input before continuing. Supports 1-10 choice/text questions, one active form, and sequential execution. Requires TUI custom UI. Result text is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}.`;
|
|
5
9
|
|
|
6
10
|
export const promptSnippet = "ask_user — request a focused blocking user decision";
|
|
7
11
|
|
|
8
12
|
export const promptGuidelines = [
|
|
9
|
-
"Use ask_user only
|
|
10
|
-
"Use ask_user
|
|
11
|
-
"Use ask_user
|
|
12
|
-
"
|
|
13
|
-
"
|
|
14
|
-
"All questions are expected for a full submission — unanswered questions produce `needs_discussion` instead.",
|
|
15
|
-
"Comments on questions and options are user UI affordances — do not reference removed fields like `required`, `initial`, `allowOther`, or `allowPartialSubmit`.",
|
|
13
|
+
"Use ask_user only when blocked on a focused user decision; not for status updates or broad surveys.",
|
|
14
|
+
"Use one ask_user form for one decision; combine related questions instead of multiple calls.",
|
|
15
|
+
"Use ask_user after needed inspection; do not make sibling tool calls that depend on the answer.",
|
|
16
|
+
"Use ask_user `choice` for fixed/yes-no options and `text` for short freeform input.",
|
|
17
|
+
"In ask_user, use stable ids/values; recommendations are single-choice string (omitted = first option), multi-choice array (omitted = none), or text string; unanswered questions return `needs_discussion`.",
|
|
16
18
|
];
|
package/src/types.ts
CHANGED
|
@@ -124,6 +124,8 @@ export function isTextQuestion(question: NormalizedQuestion): question is Normal
|
|
|
124
124
|
return question.type === "text";
|
|
125
125
|
}
|
|
126
126
|
|
|
127
|
-
export function isErrorDetails(details:
|
|
128
|
-
return
|
|
127
|
+
export function isErrorDetails(details: unknown): details is AskUserErrorDetails {
|
|
128
|
+
return (
|
|
129
|
+
typeof details === "object" && details !== null && "kind" in details && details.kind === "error"
|
|
130
|
+
);
|
|
129
131
|
}
|