@mrclrchtr/supi-ask-user 4.9.0 → 5.0.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 ask-user tool to the [Pi coding agent](https://github.com/earendil-works/pi) for moments when it needs your input before continuing.
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
- Instead of guessing or scattering questions across chat, the agent can pause, present one focused form, and resume with structured answers.
11
+ ## What it adds
12
12
 
13
- ## What you and your agent get
14
-
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.
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 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
+ 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,123 @@ 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
- To try it for one run without installing:
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 essentials
95
+ ## Keyboard controls
88
96
 
89
- The form always shows context-specific key hints at the bottom.
97
+ The form shows context-specific key hints at the bottom.
90
98
 
91
99
  | Key | Action |
92
100
  |---|---|
93
- | `↑` `↓` | Move through choices or review rows |
101
+ | `↑` `↓` | Move through choices or review rows; at the first or last row, scroll surrounding content |
102
+ | `Page Up` / `Page Down` | Scroll an overflowing choice or review form by one page |
103
+ | `Alt+Page Up` / `Alt+Page Down` | Scroll the outer form while editing text or comments |
94
104
  | `Space` | Select a single choice or toggle a multi-select option |
95
- | `Enter` | Accept the current answer, save text/comments, or submit from review |
105
+ | `Enter` | Accept an answer, save text or comments, edit a review row, or submit the form |
106
+ | `←` `→` | Move between choice questions; `←` returns from review |
96
107
  | `Tab` / `Shift+Tab` | Move forward or backward between questions |
97
- | `c` / `Alt+C` | Comment on the current question (`Alt+C` in text questions) |
108
+ | `c` / `Alt+C` | Comment on the current question (`Alt+C` for text questions) |
98
109
  | `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 |
110
+ | `u` / `Alt+U` | Mark the question unanswered (`Alt+U` for text questions) |
111
+ | `Esc` | Cancel the form; in a comment editor, discard unsaved comment text |
112
+
113
+ On wide terminals, option details appear beside the choices. On narrow terminals, they appear below the choices. If a form is taller than its inline height limit, Ask User keeps the focused row visible and shows a scroll position indicator.
114
+
115
+ ## Requirements, defaults, and limits
116
+
117
+ - `ask_user` requires Pi's interactive TUI and custom component support. It does not run in RPC, JSON, or print mode.
118
+ - The package needs no additional binary, service, or API key.
119
+ - Only one form can be active. The tool uses sequential execution, so sibling tool calls do not run beside a live form.
120
+ - Cancelling a form cancels the current agent turn. It does not record a user response.
121
+ - All questions are expected for a complete submission. Mark a question unanswered to request discussion.
122
+ - A form contains 1-10 questions. A choice question contains 2-12 options with unique values.
123
+ - If a single-choice question has no recommendation, the first option is selected. A multi-select question has no selection by default.
124
+ - Titles can contain 120 characters. Headers can contain 60 characters. Intros and prompts can contain 4,000 characters. Text placeholders can contain 200 characters.
125
+ - Ask User reuses a compatible Pi custom editor for text and comments. It uses the default editor if the custom editor is not compatible.
126
+ - 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.
127
+
128
+ ## Model guidance configuration
129
+
130
+ 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.
131
+
132
+ Use `~/.pi/agent/supi/config.json` for global configuration or `.pi/supi/config.json` for project configuration:
133
+
134
+ ```json
135
+ {
136
+ "ask-user": {
137
+ "tools": {
138
+ "ask_user": {
139
+ "promptSurface": {
140
+ "appendPromptGuidelines": [
141
+ "Use ask_user for release decisions that need maintainer approval."
142
+ ]
143
+ }
144
+ }
145
+ }
146
+ }
147
+ }
148
+ ```
149
+
150
+ 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`.
151
+
152
+ `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.
153
+
154
+ ## Public API
155
+
156
+ The package also provides a headless TypeScript API. Install the package and its schema dependency with your package manager:
157
+
158
+ ```bash
159
+ pnpm add @mrclrchtr/supi-ask-user typebox
160
+ ```
161
+
162
+ Import the explicit API subpath:
163
+
164
+ ```ts
165
+ import {
166
+ AskUserController,
167
+ normalizeQuestionnaire,
168
+ type AskUserOutcome,
169
+ } from "@mrclrchtr/supi-ask-user/api";
170
+
171
+ const questionnaire = normalizeQuestionnaire({
172
+ questions: [
173
+ {
174
+ type: "text",
175
+ id: "notes",
176
+ header: "Notes",
177
+ prompt: "What must the agent know?",
178
+ },
179
+ ],
180
+ });
181
+
182
+ const controller = new AskUserController(questionnaire);
183
+ const outcome: AskUserOutcome = controller.outcome();
184
+ ```
185
+
186
+ 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.
187
+
188
+ The package ships TypeScript source. A standalone consumer must use a runtime or build tool that can load TypeScript.
101
189
 
102
- On wide terminals, option details appear beside the choices; on narrow terminals, they stack underneath.
190
+ ## Privacy and security
103
191
 
104
- ## Good to know
192
+ 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
193
 
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.
194
+ Like all Pi extensions, this package runs with your user permissions. Review the package source before installation.
@@ -28,6 +28,7 @@ pnpm add @mrclrchtr/supi-core
28
28
  - `loadSupiConfig()` — merged config with resolution order `defaults <- global <- project`
29
29
  - `loadSupiConfigForScope()` — load one scope at a time for settings UIs
30
30
  - `writeSupiConfig()` — persist values
31
+ - `replaceSupiConfigSection()` — replace one nested section while preserving other sections
31
32
  - `removeSupiConfigKey()` — remove a key or override
32
33
 
33
34
  Config file locations:
@@ -49,6 +50,7 @@ Config file locations:
49
50
 
50
51
  - context-provider registry for `/supi-context`
51
52
  - debug-event registry and monotonic phase timers for producers that want shared debug capture
53
+ - optional Debug Operation IDs for exact, directly owned public Tool-call correlation; ambient events stay uncorrelated
52
54
  - settings registry used by `/supi-settings`
53
55
 
54
56
  ### Project and session helpers
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-core",
3
- "version": "4.9.0",
3
+ "version": "5.0.0",
4
4
  "description": "Shared settings, configuration, reporting, and session infrastructure",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -148,6 +148,37 @@ export function writeSupiConfig(
148
148
  fs.writeFileSync(configPath, `${JSON.stringify(existing, null, 2)}\n`, "utf-8");
149
149
  }
150
150
 
151
+ /**
152
+ * Replace one complete config section while preserving other sections.
153
+ *
154
+ * This is useful for nested settings that must remove stale keys as part of
155
+ * one update. An empty section is removed from the config file.
156
+ */
157
+ export function replaceSupiConfigSection(
158
+ loc: SupiConfigLocation,
159
+ value: Record<string, unknown>,
160
+ options?: SupiConfigOptions,
161
+ ): void {
162
+ const configPath = getSupiConfigPath(loc.scope, loc.cwd, options);
163
+ const existing = readJsonFile(configPath) ?? {};
164
+
165
+ if (Object.keys(value).length > 0) existing[loc.section] = value;
166
+ else delete existing[loc.section];
167
+
168
+ const content = Object.keys(existing).length > 0 ? `${JSON.stringify(existing, null, 2)}\n` : "";
169
+ if (content) {
170
+ fs.mkdirSync(path.dirname(configPath), { recursive: true });
171
+ fs.writeFileSync(configPath, content, "utf-8");
172
+ return;
173
+ }
174
+
175
+ try {
176
+ fs.unlinkSync(configPath);
177
+ } catch {
178
+ // File may not exist.
179
+ }
180
+ }
181
+
151
182
  /**
152
183
  * Remove a key from a config section.
153
184
  * Used by `interval default` to remove the project override.
@@ -1,10 +1,12 @@
1
1
  // supi-core config domain — config loading.
2
2
  export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
3
3
  export {
4
+ getSupiConfigPath,
4
5
  loadSupiConfig,
5
6
  loadSupiConfigForScope,
6
7
  loadSupiConfigSectionForScope,
7
8
  readJsonFile,
8
9
  removeSupiConfigKey,
10
+ replaceSupiConfigSection,
9
11
  writeSupiConfig,
10
12
  } from "./config/config.ts";
@@ -25,6 +25,8 @@ export const DEBUG_REGISTRY_DEFAULTS: DebugRegistryConfig = {
25
25
  };
26
26
 
27
27
  export interface DebugEventInput {
28
+ /** Opaque identity for events directly owned by one public Tool call. */
29
+ operationId?: string;
28
30
  source: string;
29
31
  level: DebugLevel;
30
32
  category: string;
@@ -42,6 +44,8 @@ export interface DebugEvent extends DebugEventInput {
42
44
  }
43
45
 
44
46
  export interface DebugEventQuery {
47
+ /** Match one exact Debug Operation ID. */
48
+ operationId?: string;
45
49
  source?: string;
46
50
  level?: DebugLevel;
47
51
  category?: string;
@@ -53,6 +57,7 @@ export interface DebugEventQuery {
53
57
  export interface DebugEventView {
54
58
  id: number;
55
59
  timestamp: number;
60
+ operationId?: string;
56
61
  source: string;
57
62
  level: DebugLevel;
58
63
  category: string;
@@ -84,6 +89,7 @@ interface DebugRegistryState {
84
89
  }
85
90
 
86
91
  const REGISTRY_KEY = Symbol.for("@mrclrchtr/supi-core/debug-registry");
92
+ const DEBUG_OPERATION_ID_RE = /^op-[A-Za-z0-9_-]{21}[AQgw]$/;
87
93
  const SECRET_KEY_RE = /(?:token|password|passwd|secret|api[_-]?key|authorization|credential)/i;
88
94
  const ENV_SECRET_RE =
89
95
  /\b([A-Za-z0-9_]*(?:token|password|passwd|secret|api[_-]?key|authorization|credential)[A-Za-z0-9_]*)=(?:'[^']*'|"[^"]*"|\S+)/gi;
@@ -135,11 +141,17 @@ export function isDebugLevel(value: unknown): value is DebugLevel {
135
141
  return value === "debug" || value === "info" || value === "warning" || value === "error";
136
142
  }
137
143
 
138
- /** Match a debug event against the supported source, level, and category filters. */
144
+ /** Return whether a value has the exact 16-byte base64url Debug Operation ID form. */
145
+ export function isDebugOperationId(value: unknown): value is string {
146
+ return typeof value === "string" && DEBUG_OPERATION_ID_RE.test(value);
147
+ }
148
+
149
+ /** Match a debug event against the supported exact filters. */
139
150
  export function matchesDebugEventQuery(
140
- event: Pick<DebugEventView, "source" | "level" | "category">,
141
- query: Pick<DebugEventQuery, "source" | "level" | "category">,
151
+ event: Pick<DebugEventView, "operationId" | "source" | "level" | "category">,
152
+ query: Pick<DebugEventQuery, "operationId" | "source" | "level" | "category">,
142
153
  ): boolean {
154
+ if (query.operationId && event.operationId !== query.operationId) return false;
143
155
  if (query.source && event.source !== query.source) return false;
144
156
  if (query.level && event.level !== query.level) return false;
145
157
  if (query.category && event.category !== query.category) return false;
@@ -197,6 +209,7 @@ function toSanitizedView(event: DebugEvent): DebugEventView {
197
209
  return {
198
210
  id: event.id,
199
211
  timestamp: event.timestamp,
212
+ operationId: event.operationId,
200
213
  source: event.source,
201
214
  level: event.level,
202
215
  category: event.category,
@@ -216,6 +229,9 @@ export function subscribeDebugEvents(listener: DebugEventListener): () => void {
216
229
  /** Record a session-local debug event if debugging is enabled. */
217
230
  export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
218
231
  const state = getState();
232
+ if (input.operationId !== undefined && !isDebugOperationId(input.operationId)) {
233
+ return null;
234
+ }
219
235
  if (!state.config.enabled) {
220
236
  return null;
221
237
  }
@@ -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
- const startedAt = now();
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
- markAt(phase, now());
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
- if (!isDebugRegistryEnabled()) {
74
- finished = true;
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
  }
@@ -41,7 +41,10 @@ export interface SettingsApplyResult {
41
41
  */
42
42
  export interface SettingsModule {
43
43
  id: string;
44
+ /** Human-readable section label shown in the UI. */
44
45
  label: string;
46
+ /** Optional label that groups this module within its section. */
47
+ subsection?: string;
45
48
  read(context: SettingsContext): Promise<SettingsSnapshot>;
46
49
  apply(request: SettingsActionRequest): Promise<SettingsApplyResult>;
47
50
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-ask-user",
3
- "version": "4.9.0",
3
+ "version": "5.0.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.9.0"
35
+ "@mrclrchtr/supi-core": "5.0.0"
36
36
  },
37
37
  "bundledDependencies": [
38
38
  "@mrclrchtr/supi-core"