@mrclrchtr/supi-ask-user 1.14.2 → 1.15.0

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 CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  # @mrclrchtr/supi-ask-user
8
8
 
9
- Adds a redesigned `ask_user` tool to the [pi coding agent](https://github.com/earendil-works/pi). It lets the model pause and request a small decision form when explicit human input is required.
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
- ## What you get
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
- - `↑↓` — move between options
197
- - `Space` — select the focused option (single-select) or toggle (multi-select)
198
- - `Enter` — on single-select, selects the focused option and advances; on multi-select, accepts current selections and advances (no toggling)
199
- - `Tab` / `→` — go to the next question; from the last question, go to review
200
- - `Shift+Tab` / `←` — go to the previous question
201
- - `n` — edit a comment for the focused choice option (whether selected or not)
202
- - `c` — edit a comment for the current question
203
- - `u` — mark the current question unanswered and show an unanswered status line (preserves comments)
204
- - `Esc` — cancel the whole form
205
-
206
- The recommended/preselected option is labeled `[recommended]`.
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
- - The editor is visible immediately with any recommendation prefilled
213
- - `Enter` — submit the current text and advance
214
- - `Tab` — go to the next question
215
- - `Alt+C` — edit a comment for the current question
216
- - `Alt+U` — mark the current question unanswered
217
- - Plain printable characters, including `c` and `u`, are inserted into the editor
218
- - `Esc` — cancel the whole form
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
- - `↑↓` — move between questions and the Submit row
223
- - `Enter` — on a question, open that question for editing; on the Submit row, submit the form
224
- - `←` / `Shift+Tab` — return to the last question
225
- - `c` — edit the form-level comment
226
- - `Esc` — cancel the whole form
227
-
228
- The review screen shows every question with an answered/unanswered marker and any option comments before submission. The final question always moves to review rather than submitting immediately, and the Submit row is focused by default so the form can be submitted with a single `Enter`. When a question is opened from review, saving/advancing that question returns to review instead of walking through later questions.
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
- Question, option, and form-level comment editors are opened with `c`, `n`, or `Alt+C` depending on the current screen.
233
-
234
- - `Enter` — save the comment and return to the form or review screen
235
- - `Esc` — discard unsaved comment edits and return to the form or review screen without cancelling the whole interaction
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
- - `src/extension.ts` — pi extension entrypoint
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.2",
3
+ "version": "1.15.0",
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",
@@ -6,7 +6,7 @@
6
6
  import { createRegistry } from "../registry-utils.ts";
7
7
 
8
8
  export interface ContextProvider {
9
- /** Unique identifier — e.g. "rtk" */
9
+ /** Unique identifier — e.g. "lsp" */
10
10
  id: string;
11
11
  /** Human-readable label shown in the report */
12
12
  label: string;
package/package.json CHANGED
@@ -1,11 +1,16 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-ask-user",
3
- "version": "1.14.2",
3
+ "version": "1.15.0",
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.2"
34
+ "@mrclrchtr/supi-core": "1.15.0"
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/logo.png"
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, buildErrorResult, buildResult } from "./render/result.ts";
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 { promptGuidelines, promptSnippet, toolDescription } from "./tool/guidance.ts";
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: TOOL_NAME,
37
- label: TOOL_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) => renderAskUserResult(result, theme, options),
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
- return buildErrorResult(`Error: ${error.message}`);
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
- return buildErrorResult(
71
- "Error: ask_user requires an interactive TUI session. No user-facing form UI is available in the current mode.",
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
- return buildErrorResult(
76
- "Error: another ask_user form is already in flight. Wait for it to complete before calling ask_user again.",
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
- return buildErrorResult(
99
- "Error: ask_user requires a TUI with custom form support. Do not use ask_user in non-interactive or degraded UI sessions.",
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
- return buildErrorResult("The user interaction was cancelled.");
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;
@@ -1,4 +1,10 @@
1
- import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
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: [{ type: "text", text: summarizeOutcome(questionnaire.questions, outcome) }],
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),
@@ -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("ask_user "))}${theme.fg("muted", label)}${suffix ? theme.fg("dim", ` ${suffix}`) : ""}`;
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.details.message), 0, 0);
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: "Returned id" }),
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 description",
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 = { minItems: 2, maxItems: 12 } as const;
21
- const QuestionCount = { minItems: 1, maxItems: 10 } as const;
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: "Question id" }),
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 (2-12)",
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: "Question id" }),
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 prefilled text" })),
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 intro for the decision",
67
+ description: "Optional context",
61
68
  }),
62
69
  ),
63
70
  questions: Type.Array(QuestionSchema, {
64
- description: "1-10 focused questions for one decision",
71
+ description: "1-10 related questions for one decision",
65
72
  ...QuestionCount,
66
73
  }),
67
74
  });
@@ -1,16 +1,18 @@
1
1
  // Prompt guidance and tool description for the redesigned ask_user tool.
2
2
 
3
- export const toolDescription =
4
- "Ask the user for a focused blocking decision. Use 1-10 related `choice` or `text` questions, and keep only one ask_user form active at a time.";
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 for blocking user input, not open-ended interviews or repo facts.",
10
- "Use ask_user with 1-10 related questions; prefer one when possible.",
11
- "Use ask_user `choice` for fixed options and ask_user `text` for freeform input; yes/no should be a `choice`.",
12
- "Keep one ask_user form active at a time.",
13
- "Use `recommendation` to suggest default choices or prefilled text.",
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: AskUserToolDetails): details is AskUserErrorDetails {
128
- return "kind" in details && details.kind === "error";
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
  }