@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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
20
|
-
pi install ./packages/supi-ask-user
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
## What to expect
|
|
13
|
+
## What you and your agent get
|
|
24
14
|
|
|
25
|
-
|
|
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
|
-
|
|
23
|
+
## Example requests
|
|
28
24
|
|
|
29
|
-
|
|
25
|
+
You can tell Pi when you want a structured handoff:
|
|
30
26
|
|
|
31
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
34
|
+
## How it works
|
|
36
35
|
|
|
37
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
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="
|
|
47
|
-
<br/>
|
|
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-
|
|
51
|
-
<br/>
|
|
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-
|
|
57
|
-
<br/>
|
|
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-
|
|
61
|
-
<br/>
|
|
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
|
|
67
|
-
<br/>Review
|
|
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
|
-
##
|
|
73
|
-
|
|
74
|
-
### Choice questions
|
|
75
|
+
## Install
|
|
75
76
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
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
|
-
|
|
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
|
-
|
|
83
|
+
```bash
|
|
84
|
+
pi -e npm:@mrclrchtr/supi-ask-user
|
|
85
|
+
```
|
|
99
86
|
|
|
100
|
-
|
|
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
|
-
|
|
89
|
+
The form always shows context-specific key hints at the bottom.
|
|
109
90
|
|
|
110
91
|
| Key | Action |
|
|
111
|
-
|
|
112
|
-
|
|
|
113
|
-
| `
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mrclrchtr/supi-ask-user",
|
|
3
|
-
"version": "4.
|
|
4
|
-
"description": "
|
|
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.
|
|
35
|
+
"@mrclrchtr/supi-core": "4.5.0"
|
|
36
36
|
},
|
|
37
37
|
"bundledDependencies": [
|
|
38
38
|
"@mrclrchtr/supi-core"
|