@mrclrchtr/supi-ask-user 4.9.0 → 4.10.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,19 +6,17 @@
|
|
|
6
6
|
|
|
7
7
|
# @mrclrchtr/supi-ask-user — Ask-User Tool for Pi
|
|
8
8
|
|
|
9
|
-
Adds a structured
|
|
9
|
+
Adds `ask_user`, a structured decision-form tool for the [Pi coding agent](https://github.com/earendil-works/pi). The agent can stop at one decision, show a keyboard form, and continue with structured answers.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
## What it adds
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
- **
|
|
16
|
-
- **
|
|
17
|
-
- **
|
|
18
|
-
- **
|
|
19
|
-
- **
|
|
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.
|
|
13
|
+
- **One focused decision** — one blocking form contains 1-10 related questions.
|
|
14
|
+
- **Choice and text questions** — choose one option, choose multiple options, or enter free-form text.
|
|
15
|
+
- **Recommendations** — the agent can select or prefill a suggested answer. You can change it.
|
|
16
|
+
- **Option context** — focused options can show descriptions, trade-offs, consequences, or code samples.
|
|
17
|
+
- **Comments at each level** — add a form comment, a question comment, or a comment on a selected or unselected option.
|
|
18
|
+
- **Review before submission** — inspect each answer, edit a question, and see unanswered items.
|
|
19
|
+
- **Structured results** — complete forms return `submitted`. Forms with unanswered questions return `needs_discussion`.
|
|
22
20
|
|
|
23
21
|
## Example requests
|
|
24
22
|
|
|
@@ -39,7 +37,7 @@ The agent is also guided to use `ask_user` only after inspecting what it can ins
|
|
|
39
37
|
4. The review screen lets you edit the form before submitting.
|
|
40
38
|
5. The agent receives ordered, structured responses and continues from your decision.
|
|
41
39
|
|
|
42
|
-
Completed forms
|
|
40
|
+
Completed forms have the `decision` label in Pi's session tree. The result remains in chat history. Use the `app.tools.expand` keybinding (`Ctrl+O` by default) to expand it for read-only review.
|
|
43
41
|
|
|
44
42
|
## See it in action
|
|
45
43
|
|
|
@@ -74,37 +72,121 @@ Completed forms are labeled `decision` in Pi's session tree. The result remains
|
|
|
74
72
|
|
|
75
73
|
## Install
|
|
76
74
|
|
|
75
|
+
This package is in the recommended SuPi release stack. SuPi is pre-release.
|
|
76
|
+
|
|
77
|
+
Install it globally:
|
|
78
|
+
|
|
77
79
|
```bash
|
|
78
80
|
pi install npm:@mrclrchtr/supi-ask-user
|
|
79
81
|
```
|
|
80
82
|
|
|
81
|
-
|
|
83
|
+
Install it for one project:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
pi install npm:@mrclrchtr/supi-ask-user -l
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Try it for one run without a persistent install:
|
|
82
90
|
|
|
83
91
|
```bash
|
|
84
92
|
pi -e npm:@mrclrchtr/supi-ask-user
|
|
85
93
|
```
|
|
86
94
|
|
|
87
|
-
## Keyboard
|
|
95
|
+
## Keyboard controls
|
|
88
96
|
|
|
89
|
-
The form
|
|
97
|
+
The form shows context-specific key hints at the bottom.
|
|
90
98
|
|
|
91
99
|
| Key | Action |
|
|
92
100
|
|---|---|
|
|
93
101
|
| `↑` `↓` | Move through choices or review rows |
|
|
94
102
|
| `Space` | Select a single choice or toggle a multi-select option |
|
|
95
|
-
| `Enter` | Accept
|
|
103
|
+
| `Enter` | Accept an answer, save text or comments, edit a review row, or submit the form |
|
|
104
|
+
| `←` `→` | Move between choice questions; `←` returns from review |
|
|
96
105
|
| `Tab` / `Shift+Tab` | Move forward or backward between questions |
|
|
97
|
-
| `c` / `Alt+C` | Comment on the current question (`Alt+C`
|
|
106
|
+
| `c` / `Alt+C` | Comment on the current question (`Alt+C` for text questions) |
|
|
98
107
|
| `n` | Comment on the focused choice option |
|
|
99
|
-
| `u` / `Alt+U` |
|
|
100
|
-
| `Esc` | Cancel the form;
|
|
108
|
+
| `u` / `Alt+U` | Mark the question unanswered (`Alt+U` for text questions) |
|
|
109
|
+
| `Esc` | Cancel the form; in a comment editor, discard unsaved comment text |
|
|
110
|
+
|
|
111
|
+
On wide terminals, option details appear beside the choices. On narrow terminals, they appear below the choices.
|
|
112
|
+
|
|
113
|
+
## Requirements, defaults, and limits
|
|
114
|
+
|
|
115
|
+
- `ask_user` requires Pi's interactive TUI and custom component support. It does not run in RPC, JSON, or print mode.
|
|
116
|
+
- The package needs no additional binary, service, or API key.
|
|
117
|
+
- Only one form can be active. The tool uses sequential execution, so sibling tool calls do not run beside a live form.
|
|
118
|
+
- Cancelling a form cancels the current agent turn. It does not record a user response.
|
|
119
|
+
- All questions are expected for a complete submission. Mark a question unanswered to request discussion.
|
|
120
|
+
- A form contains 1-10 questions. A choice question contains 2-12 options with unique values.
|
|
121
|
+
- If a single-choice question has no recommendation, the first option is selected. A multi-select question has no selection by default.
|
|
122
|
+
- Titles can contain 120 characters. Headers can contain 60 characters. Intros and prompts can contain 4,000 characters. Text placeholders can contain 200 characters.
|
|
123
|
+
- Ask User reuses a compatible Pi custom editor for text and comments. It uses the default editor if the custom editor is not compatible.
|
|
124
|
+
- The model-visible result is limited to Pi's default 2,000 lines or 50 KB. The structured result remains available in the session transcript.
|
|
125
|
+
|
|
126
|
+
## Model guidance configuration
|
|
127
|
+
|
|
128
|
+
You can change the model-facing tool description, prompt snippet, and guidelines. This configuration changes the instructions that Pi sends to the model. It does not change form behavior.
|
|
129
|
+
|
|
130
|
+
Use `~/.pi/agent/supi/config.json` for global configuration or `.pi/supi/config.json` for project configuration:
|
|
131
|
+
|
|
132
|
+
```json
|
|
133
|
+
{
|
|
134
|
+
"ask-user": {
|
|
135
|
+
"tools": {
|
|
136
|
+
"ask_user": {
|
|
137
|
+
"promptSurface": {
|
|
138
|
+
"appendPromptGuidelines": [
|
|
139
|
+
"Use ask_user for release decisions that need maintainer approval."
|
|
140
|
+
]
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
The extension applies package defaults, then global values, then trusted project values. It ignores project prompt overrides unless Pi trusts the project and finds a trust-requiring project resource, such as `.pi/settings.json`.
|
|
149
|
+
|
|
150
|
+
`promptSurface` accepts `description`, `promptSnippet`, `promptGuidelines`, `prependPromptGuidelines`, and `appendPromptGuidelines`. Use `$reset` with an array of `description`, `promptSnippet`, or `promptGuidelines` to restore those fields to package defaults. Run `/reload` after you edit the file.
|
|
151
|
+
|
|
152
|
+
## Public API
|
|
153
|
+
|
|
154
|
+
The package also provides a headless TypeScript API. Install the package and its schema dependency with your package manager:
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
pnpm add @mrclrchtr/supi-ask-user typebox
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Import the explicit API subpath:
|
|
161
|
+
|
|
162
|
+
```ts
|
|
163
|
+
import {
|
|
164
|
+
AskUserController,
|
|
165
|
+
normalizeQuestionnaire,
|
|
166
|
+
type AskUserOutcome,
|
|
167
|
+
} from "@mrclrchtr/supi-ask-user/api";
|
|
168
|
+
|
|
169
|
+
const questionnaire = normalizeQuestionnaire({
|
|
170
|
+
questions: [
|
|
171
|
+
{
|
|
172
|
+
type: "text",
|
|
173
|
+
id: "notes",
|
|
174
|
+
header: "Notes",
|
|
175
|
+
prompt: "What must the agent know?",
|
|
176
|
+
},
|
|
177
|
+
],
|
|
178
|
+
});
|
|
179
|
+
|
|
180
|
+
const controller = new AskUserController(questionnaire);
|
|
181
|
+
const outcome: AskUserOutcome = controller.outcome();
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
The API exports `AskUserParamsSchema`, `normalizeQuestionnaire`, `AskUserValidationError`, and `AskUserController`. It also exports types for normalized questions, responses, outcomes, tool details, and cancel or abort interaction results. The package root is not an import surface. Use `/api` for the library or `/extension` for the Pi extension entrypoint.
|
|
185
|
+
|
|
186
|
+
The package ships TypeScript source. A standalone consumer must use a runtime or build tool that can load TypeScript.
|
|
101
187
|
|
|
102
|
-
|
|
188
|
+
## Privacy and security
|
|
103
189
|
|
|
104
|
-
|
|
190
|
+
Pi stores the tool result in the session. The active model receives a text summary of answers and comments. This package does not send a separate network request or start an external process.
|
|
105
191
|
|
|
106
|
-
|
|
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.
|
|
192
|
+
Like all Pi extensions, this package runs with your user permissions. Review the package source before installation.
|
|
@@ -46,13 +46,21 @@ export interface DebugTimer {
|
|
|
46
46
|
* names are accumulated. Event data reserves the `timing` field. When Debug is
|
|
47
47
|
* disabled at start, this returns a no-op timer and does not read the clock.
|
|
48
48
|
* Pass a factory to `finish()` to avoid event-data construction when disabled.
|
|
49
|
+
* Clock, event-construction, and registry failures are isolated from the
|
|
50
|
+
* measured operation and make the timer a no-op.
|
|
49
51
|
*/
|
|
50
52
|
export function startDebugTimer(options: DebugTimerOptions = {}): DebugTimer {
|
|
51
53
|
if (!isDebugRegistryEnabled()) return DISABLED_DEBUG_TIMER;
|
|
52
54
|
const now = options.now ?? performance.now.bind(performance);
|
|
53
|
-
|
|
55
|
+
let startedAt: number;
|
|
56
|
+
try {
|
|
57
|
+
startedAt = now();
|
|
58
|
+
} catch {
|
|
59
|
+
return DISABLED_DEBUG_TIMER;
|
|
60
|
+
}
|
|
54
61
|
let previousAt = startedAt;
|
|
55
62
|
let finished = false;
|
|
63
|
+
let failed = false;
|
|
56
64
|
const phases = new Map<string, number>();
|
|
57
65
|
|
|
58
66
|
const markAt = (phase: string, current: number): void => {
|
|
@@ -65,30 +73,35 @@ export function startDebugTimer(options: DebugTimerOptions = {}): DebugTimer {
|
|
|
65
73
|
return {
|
|
66
74
|
enabled: true,
|
|
67
75
|
mark(phase) {
|
|
68
|
-
if (finished) return;
|
|
69
|
-
|
|
76
|
+
if (finished || failed) return;
|
|
77
|
+
try {
|
|
78
|
+
markAt(phase, now());
|
|
79
|
+
} catch {
|
|
80
|
+
failed = true;
|
|
81
|
+
}
|
|
70
82
|
},
|
|
71
83
|
finish(input, finalPhase) {
|
|
72
|
-
if (finished) return null;
|
|
73
|
-
|
|
74
|
-
|
|
84
|
+
if (finished || failed) return null;
|
|
85
|
+
finished = true;
|
|
86
|
+
try {
|
|
87
|
+
if (!isDebugRegistryEnabled()) return null;
|
|
88
|
+
const completedAt = now();
|
|
89
|
+
if (finalPhase) markAt(finalPhase, completedAt);
|
|
90
|
+
const phasesMs = Object.fromEntries(
|
|
91
|
+
[...phases.entries()].map(([name, value]) => [name, duration(value)]),
|
|
92
|
+
);
|
|
93
|
+
const timing: DebugTiming = {
|
|
94
|
+
durationMs: duration(completedAt - startedAt),
|
|
95
|
+
phasesMs,
|
|
96
|
+
};
|
|
97
|
+
const eventInput = typeof input === "function" ? input() : input;
|
|
98
|
+
return recordDebugEvent({
|
|
99
|
+
...eventInput,
|
|
100
|
+
data: { ...eventInput.data, timing },
|
|
101
|
+
});
|
|
102
|
+
} catch {
|
|
75
103
|
return null;
|
|
76
104
|
}
|
|
77
|
-
const completedAt = now();
|
|
78
|
-
if (finalPhase) markAt(finalPhase, completedAt);
|
|
79
|
-
finished = true;
|
|
80
|
-
const phasesMs = Object.fromEntries(
|
|
81
|
-
[...phases.entries()].map(([name, value]) => [name, duration(value)]),
|
|
82
|
-
);
|
|
83
|
-
const timing: DebugTiming = {
|
|
84
|
-
durationMs: duration(completedAt - startedAt),
|
|
85
|
-
phasesMs,
|
|
86
|
-
};
|
|
87
|
-
const eventInput = typeof input === "function" ? input() : input;
|
|
88
|
-
return recordDebugEvent({
|
|
89
|
-
...eventInput,
|
|
90
|
-
data: { ...eventInput.data, timing },
|
|
91
|
-
});
|
|
92
105
|
},
|
|
93
106
|
};
|
|
94
107
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mrclrchtr/supi-ask-user",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.10.0",
|
|
4
4
|
"description": "Structured choice and text forms for agent-user decisions",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
"!__tests__"
|
|
33
33
|
],
|
|
34
34
|
"dependencies": {
|
|
35
|
-
"@mrclrchtr/supi-core": "4.
|
|
35
|
+
"@mrclrchtr/supi-core": "4.10.0"
|
|
36
36
|
},
|
|
37
37
|
"bundledDependencies": [
|
|
38
38
|
"@mrclrchtr/supi-core"
|