@mrclrchtr/supi-ask-user 4.8.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 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,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
- 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
101
  | `↑` `↓` | Move through choices or review rows |
94
102
  | `Space` | Select a single choice or toggle a multi-select option |
95
- | `Enter` | Accept the current answer, save text/comments, or submit from review |
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` in text questions) |
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` | Deliberately mark the question unanswered (`Alt+U` in text questions) |
100
- | `Esc` | Cancel the form; inside a comment editor, discard unsaved comment edits |
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
- On wide terminals, option details appear beside the choices; on narrow terminals, they stack underneath.
188
+ ## Privacy and security
103
189
 
104
- ## Good to know
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
- - `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.
192
+ Like all Pi extensions, this package runs with your user permissions. Review the package source before installation.
@@ -48,7 +48,7 @@ Config file locations:
48
48
  ### Shared registries
49
49
 
50
50
  - context-provider registry for `/supi-context`
51
- - debug-event registry for producers that want shared debug capture
51
+ - debug-event registry and monotonic phase timers for producers that want shared debug capture
52
52
  - settings registry used by `/supi-settings`
53
53
 
54
54
  ### Project and session helpers
@@ -108,5 +108,7 @@ export default function myExtension(pi: ExtensionAPI) {
108
108
 
109
109
  - `src/api.ts` — exported library surface
110
110
  - `src/config.ts` — shared config loading and writing
111
+ - `src/debug-registry.ts` — Debug domain surface, event state, retention, redaction, listeners, and queries
112
+ - `src/debug-timing.ts` — monotonic total and phase timers for Debug Event Producers
111
113
  - `src/settings/` — settings registry, schema, scope resolution, and persistence
112
114
  - `src/report.ts` — shared text/report rendering helpers
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-core",
3
- "version": "4.8.0",
3
+ "version": "4.10.0",
4
4
  "description": "Shared settings, configuration, reporting, and session infrastructure",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -4,6 +4,9 @@
4
4
  // supi-debug extension owns policy/configuration and exposes events through a
5
5
  // command/tool while this module stays dependency-free for producers.
6
6
 
7
+ // biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
8
+ export * from "./debug-timing.ts";
9
+
7
10
  export type DebugLevel = "debug" | "info" | "warning" | "error";
8
11
  export type DebugAgentAccess = "off" | "sanitized" | "raw";
9
12
  export interface DebugRegistryConfig {
@@ -180,6 +183,11 @@ export function getDebugRegistryConfig(): DebugRegistryConfig {
180
183
  return cloneConfig(getState().config);
181
184
  }
182
185
 
186
+ /** Return whether the Debug Registry currently retains producer events. */
187
+ export function isDebugRegistryEnabled(): boolean {
188
+ return getState().config.enabled;
189
+ }
190
+
183
191
  /** Best-effort redaction helper for data exposed through sanitized debug views. */
184
192
  export function redactDebugData<T>(value: T): T {
185
193
  return redactValue(value, 8) as T;
@@ -0,0 +1,120 @@
1
+ import { performance } from "node:perf_hooks";
2
+ import {
3
+ type DebugEvent,
4
+ type DebugEventInput,
5
+ isDebugRegistryEnabled,
6
+ recordDebugEvent,
7
+ } from "./debug-registry.ts";
8
+
9
+ /** Monotonic duration data added to a timed debug event. */
10
+ export interface DebugTiming {
11
+ readonly durationMs: number;
12
+ readonly phasesMs: Readonly<Record<string, number>>;
13
+ }
14
+
15
+ /** Debug event input whose data can receive the reserved `timing` field. */
16
+ export interface TimedDebugEventInput extends Omit<DebugEventInput, "data"> {
17
+ readonly data?: Readonly<Record<string, unknown>>;
18
+ }
19
+
20
+ /** Test seam for the monotonic clock used by a debug timer. */
21
+ export interface DebugTimerOptions {
22
+ readonly now?: () => number;
23
+ }
24
+
25
+ /** Lazy timed-event input that is not evaluated when Debug is disabled. */
26
+ export type TimedDebugEventFactory = () => TimedDebugEventInput;
27
+
28
+ /** One-shot debug timer with optional sequential phase measurements. */
29
+ export interface DebugTimer {
30
+ /** Whether this timer sampled Debug as enabled when it started. */
31
+ readonly enabled: boolean;
32
+ /** Finish the current phase and start the next unnamed interval. */
33
+ mark(phase: string): void;
34
+ /** Record one event. A second call returns `null` without recording another event. */
35
+ finish(
36
+ input: TimedDebugEventInput | TimedDebugEventFactory,
37
+ finalPhase?: string,
38
+ ): DebugEvent | null;
39
+ }
40
+
41
+ /**
42
+ * Start a monotonic timer for one debug event.
43
+ *
44
+ * Each `mark(name)` stores the interval since the previous mark. `finish()`
45
+ * stores the total duration and can name the final interval. Repeated phase
46
+ * names are accumulated. Event data reserves the `timing` field. When Debug is
47
+ * disabled at start, this returns a no-op timer and does not read the clock.
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.
51
+ */
52
+ export function startDebugTimer(options: DebugTimerOptions = {}): DebugTimer {
53
+ if (!isDebugRegistryEnabled()) return DISABLED_DEBUG_TIMER;
54
+ const now = options.now ?? performance.now.bind(performance);
55
+ let startedAt: number;
56
+ try {
57
+ startedAt = now();
58
+ } catch {
59
+ return DISABLED_DEBUG_TIMER;
60
+ }
61
+ let previousAt = startedAt;
62
+ let finished = false;
63
+ let failed = false;
64
+ const phases = new Map<string, number>();
65
+
66
+ const markAt = (phase: string, current: number): void => {
67
+ const name = phase.trim();
68
+ if (!name) return;
69
+ phases.set(name, (phases.get(name) ?? 0) + Math.max(0, current - previousAt));
70
+ previousAt = current;
71
+ };
72
+
73
+ return {
74
+ enabled: true,
75
+ mark(phase) {
76
+ if (finished || failed) return;
77
+ try {
78
+ markAt(phase, now());
79
+ } catch {
80
+ failed = true;
81
+ }
82
+ },
83
+ finish(input, finalPhase) {
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 {
103
+ return null;
104
+ }
105
+ },
106
+ };
107
+ }
108
+
109
+ const DISABLED_DEBUG_TIMER: DebugTimer = Object.freeze({
110
+ enabled: false,
111
+ mark() {},
112
+ finish() {
113
+ return null;
114
+ },
115
+ });
116
+
117
+ function duration(value: number): number {
118
+ if (!Number.isFinite(value)) return 0;
119
+ return Math.round(Math.max(0, value) * 10) / 10;
120
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-ask-user",
3
- "version": "4.8.0",
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.8.0"
35
+ "@mrclrchtr/supi-core": "4.10.0"
36
36
  },
37
37
  "bundledDependencies": [
38
38
  "@mrclrchtr/supi-core"