@mrclrchtr/supi-ask-user 4.3.0 → 4.5.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
@@ -4,114 +4,107 @@
4
4
  </a>
5
5
  </div>
6
6
 
7
- # @mrclrchtr/supi-ask-user
7
+ # @mrclrchtr/supi-ask-user — Ask-User Tool for Pi
8
8
 
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.
9
+ Adds a structured ask-user tool to the [Pi coding agent](https://github.com/earendil-works/pi) for moments when it needs your input before continuing.
10
10
 
11
- ## Install
12
-
13
- ```bash
14
- pi install npm:@mrclrchtr/supi-ask-user
15
- ```
16
-
17
- For local development:
11
+ Instead of guessing or scattering questions across chat, the agent can pause, present one focused form, and resume with structured answers.
18
12
 
19
- ```bash
20
- pi install ./packages/supi-ask-user
21
- ```
22
-
23
- ## What to expect
13
+ ## What you and your agent get
24
14
 
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.
15
+ - **One decision handoff** — combine up to ten related questions in one blocking form rather than interrupting repeatedly.
16
+ - **Choice and text questions** — choose one option, select several, or write a free-form answer.
17
+ - **Useful recommendations** — the agent can preselect or prefill a suggested answer without preventing you from changing it.
18
+ - **Trade-offs beside the options** — focused options can show descriptions, consequences, code samples, or other decision context.
19
+ - **Comments at every level** — explain an answer, annotate an option you selected or rejected, or leave context for the whole form.
20
+ - **Review before submission** — inspect every answer, edit any question, and see unanswered items before sending the decision back.
21
+ - **A structured outcome** — complete forms return `submitted`; forms with unanswered questions return `needs_discussion` so the agent follows up instead of assuming.
26
22
 
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.
23
+ ## Example requests
28
24
 
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.
25
+ You can tell Pi when you want a structured handoff:
30
26
 
31
- You can also add comments to individual questions, options, or the whole form if you want to explain your thinking.
27
+ - “Before scaffolding the project, ask me about the package manager, test runner, and linting.”
28
+ - “If you find product decisions during implementation, collect the related questions into one form.”
29
+ - “Show the trade-offs beside each migration option before I choose.”
30
+ - “Ask me which findings to fix, and let me comment on individual choices.”
32
31
 
33
- If you have configured a custom Pi editor, such as a Vim or Emacs editor, Ask User creates one editor instance per form and reuses it for text answers and all comment fields. If the custom editor cannot be initialized or does not satisfy Pi's editor contract, Ask User warns and uses the default editor for that form. The decision form keeps ownership of its navigation shortcuts; main-prompt actions such as model switching are not reproduced inside the form.
32
+ The agent is also guided to use `ask_user` only after inspecting what it can inspect itself—not for status updates, broad surveys, or facts it can determine from the repository.
34
33
 
35
- ## Agent-facing behavior
34
+ ## How it works
36
35
 
37
- `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
+ 1. The agent calls `ask_user` with one focused decision and related questions.
37
+ 2. Pi opens a keyboard-driven form and pauses the agent.
38
+ 3. You answer, comment, or deliberately mark a question unanswered.
39
+ 4. The review screen lets you edit the form before submitting.
40
+ 5. The agent receives ordered, structured responses and continues from your decision.
38
41
 
39
- 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.
42
+ Completed forms are labeled `decision` in Pi's session tree. The result remains available in chat history; press `Ctrl+O` to expand it for read-only review.
40
43
 
41
- ## Preview
44
+ ## See it in action
42
45
 
43
46
  <table>
44
47
  <tr>
45
48
  <td align="center">
46
- <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-choice-details.png" width="100%" alt="Choice question with side details" />
47
- <br/>Choice question with side details
49
+ <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-choice-details.png" width="100%" alt="Single-choice decision with a recommendation and side-by-side details" />
50
+ <br/>Single choice with recommendation and details
48
51
  </td>
49
52
  <td align="center">
50
- <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-question-comment.png" width="100%" alt="Question comment editor" />
51
- <br/>Question comment editor
53
+ <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-multi-choice-details.png" width="100%" alt="Multi-select decision with recommendations and side-by-side details" />
54
+ <br/>Multi-select with recommendation and details
52
55
  </td>
53
56
  </tr>
54
57
  <tr>
55
58
  <td align="center">
56
- <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-multi-choice-details.png" width="100%" alt="Multi-select with details" />
57
- <br/>Multi-select with details
59
+ <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-text-input.png" width="100%" alt="Free-form text answer prefilled with a recommendation" />
60
+ <br/>Text answer with a recommendation
58
61
  </td>
59
62
  <td align="center">
60
- <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-text-input.png" width="100%" alt="Text input with recommendation" />
61
- <br/>Text input with recommendation
63
+ <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-question-comment.png" width="100%" alt="Question comment editor" />
64
+ <br/>Question comment
62
65
  </td>
63
66
  </tr>
64
67
  <tr>
65
68
  <td colspan="2" align="center">
66
- <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-review-form-comment.png" width="70%" alt="Review screen with form comment" />
67
- <br/>Review screen with form comment
69
+ <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-review-form-comment.png" width="70%" alt="Review screen showing answers, an unanswered question, and a form comment" />
70
+ <br/>Review answers, comments, and unanswered questions
68
71
  </td>
69
72
  </tr>
70
73
  </table>
71
74
 
72
- ## Keyboard reference
73
-
74
- ### Choice questions
75
+ ## Install
75
76
 
76
- | Key | Action |
77
- |-----|--------|
78
- | `↑` `↓` | Move between options |
79
- | `Space` | Select / toggle an option |
80
- | `Enter` | Confirm and advance |
81
- | `Tab` / `→` | Next question (last question goes to review) |
82
- | `Shift+Tab` / `←` | Previous question |
83
- | `n` | Comment on the focused option |
84
- | `c` | Comment on the current question |
85
- | `u` | Mark the current question unanswered |
86
- | `Esc` | Cancel the whole form |
87
-
88
- ### Text questions
77
+ ```bash
78
+ pi install npm:@mrclrchtr/supi-ask-user
79
+ ```
89
80
 
90
- | Key | Action |
91
- |-----|--------|
92
- | `Enter` | Submit text and advance |
93
- | `Tab` | Next question |
94
- | `Alt+C` | Comment on the current question |
95
- | `Alt+U` | Mark the current question unanswered |
96
- | `Esc` | Cancel the whole form |
81
+ To try it for one run without installing:
97
82
 
98
- ### Review screen
83
+ ```bash
84
+ pi -e npm:@mrclrchtr/supi-ask-user
85
+ ```
99
86
 
100
- | Key | Action |
101
- |-----|--------|
102
- | `↑` `↓` | Move between questions and Submit |
103
- | `Enter` | Open a question for editing, or submit the form |
104
- | `←` / `Shift+Tab` | Return to the last question |
105
- | `c` | Edit the form-level comment |
106
- | `Esc` | Cancel the whole form |
87
+ ## Keyboard essentials
107
88
 
108
- ### Comment editors
89
+ The form always shows context-specific key hints at the bottom.
109
90
 
110
91
  | Key | Action |
111
- |-----|--------|
112
- | `Enter` | Save comment and return |
113
- | `Esc` | Discard comment edits and return |
114
-
115
- With a modal custom editor, `Esc` is offered to the editor first so it can leave insert mode. When the editor delegates the interrupt, Ask User performs the cancel or discard action shown above.
116
-
117
- The recommended option is labeled `[recommended]`. On wide terminals, option details render side-by-side with the list; on narrow terminals they stack below.
92
+ |---|---|
93
+ | `↑` `↓` | Move through choices or review rows |
94
+ | `Space` | Select a single choice or toggle a multi-select option |
95
+ | `Enter` | Accept the current answer, save text/comments, or submit from review |
96
+ | `Tab` / `Shift+Tab` | Move forward or backward between questions |
97
+ | `c` / `Alt+C` | Comment on the current question (`Alt+C` in text questions) |
98
+ | `n` | Comment on the focused choice option |
99
+ | `u` / `Alt+U` | Deliberately mark the question unanswered (`Alt+U` in text questions) |
100
+ | `Esc` | Cancel the form; inside a comment editor, discard unsaved comment edits |
101
+
102
+ On wide terminals, option details appear beside the choices; on narrow terminals, they stack underneath.
103
+
104
+ ## Good to know
105
+
106
+ - `ask_user` requires Pi's interactive TUI; there is no degraded non-interactive form.
107
+ - Only one form can be active; sibling tool calls do not run beside a live form.
108
+ - Cancelling a form cancels the current agent turn rather than recording a fake answer.
109
+ - All questions are expected for a complete submission, but you can mark any question unanswered to request discussion.
110
+ - Ask User reuses your configured Pi editor for text and comments when compatible, with the default editor as a fallback.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-core",
3
- "version": "4.3.0",
3
+ "version": "4.5.0",
4
4
  "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
5
5
  "license": "MIT",
6
6
  "repository": {
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-ask-user",
3
- "version": "4.3.0",
4
- "description": "SuPi ask-user extension — rich questionnaire UI for structured agent-user decisions",
3
+ "version": "4.5.0",
4
+ "description": "Ask-user tool for the Pi coding agent — structured questionnaires for focused agent-user decisions",
5
5
  "license": "MIT",
6
6
  "repository": {
7
7
  "type": "git",
@@ -32,7 +32,7 @@
32
32
  "!__tests__"
33
33
  ],
34
34
  "dependencies": {
35
- "@mrclrchtr/supi-core": "4.3.0"
35
+ "@mrclrchtr/supi-core": "4.5.0"
36
36
  },
37
37
  "bundledDependencies": [
38
38
  "@mrclrchtr/supi-core"