@mrclrchtr/supi-ask-user 4.10.0 → 6.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
@@ -98,7 +98,8 @@ The form shows context-specific key hints at the bottom.
98
98
 
99
99
  | Key | Action |
100
100
  |---|---|
101
- | `↑` `↓` | Move through choices or review rows |
101
+ | `↑` `↓` | Move through choices or review rows; at the first or last row, scroll surrounding content |
102
+ | `Alt+Page Up` / `Alt+Page Down` | Scroll the outer form while editing text or comments |
102
103
  | `Space` | Select a single choice or toggle a multi-select option |
103
104
  | `Enter` | Accept an answer, save text or comments, edit a review row, or submit the form |
104
105
  | `←` `→` | Move between choice questions; `←` returns from review |
@@ -108,11 +109,11 @@ The form shows context-specific key hints at the bottom.
108
109
  | `u` / `Alt+U` | Mark the question unanswered (`Alt+U` for text questions) |
109
110
  | `Esc` | Cancel the form; in a comment editor, discard unsaved comment text |
110
111
 
111
- On wide terminals, option details appear beside the choices. On narrow terminals, they appear below the choices.
112
+ On wide terminals, option details appear beside the choices. On narrow terminals, they appear below the choices. Ask User uses up to 85% of the terminal height, capped at 36 rows. If a form is taller than its inline height limit, Ask User keeps the focused row visible and shows a scroll position indicator.
112
113
 
113
114
  ## Requirements, defaults, and limits
114
115
 
115
- - `ask_user` requires Pi's interactive TUI and custom component support. It does not run in RPC, JSON, or print mode.
116
+ - `ask_user` requires Pi's interactive TUI and custom component support. The tool is only registered in TUI sessions and is not offered to the model in RPC, JSON, or print mode.
116
117
  - The package needs no additional binary, service, or API key.
117
118
  - Only one form can be active. The tool uses sequential execution, so sibling tool calls do not run beside a live form.
118
119
  - Cancelling a form cancels the current agent turn. It does not record a user response.
@@ -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.10.0",
3
+ "version": "6.0.0",
4
4
  "description": "Shared settings, configuration, reporting, and session infrastructure",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -53,7 +53,7 @@
53
53
  "./api": "./src/api.ts",
54
54
  "./config": "./src/config.ts",
55
55
  "./context": "./src/context.ts",
56
- "./debug": "./src/debug-registry.ts",
56
+ "./debug": "./src/debug.ts",
57
57
  "./evidence-badge": "./src/evidence-badge.ts",
58
58
  "./footer-registry": "./src/footer-registry.ts",
59
59
  "./llm": "./src/llm.ts",
@@ -11,7 +11,7 @@ export * from "./config.ts";
11
11
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
12
12
  export * from "./context.ts";
13
13
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
14
- export * from "./debug-registry.ts";
14
+ export * from "./debug.ts";
15
15
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
16
16
  export * from "./evidence-badge.ts";
17
17
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
@@ -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";
@@ -4,9 +4,6 @@
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
-
10
7
  export type DebugLevel = "debug" | "info" | "warning" | "error";
11
8
  export type DebugAgentAccess = "off" | "sanitized" | "raw";
12
9
  export interface DebugRegistryConfig {
@@ -25,6 +22,8 @@ export const DEBUG_REGISTRY_DEFAULTS: DebugRegistryConfig = {
25
22
  };
26
23
 
27
24
  export interface DebugEventInput {
25
+ /** Opaque identity for events directly owned by one public Tool call. */
26
+ operationId?: string;
28
27
  source: string;
29
28
  level: DebugLevel;
30
29
  category: string;
@@ -42,6 +41,8 @@ export interface DebugEvent extends DebugEventInput {
42
41
  }
43
42
 
44
43
  export interface DebugEventQuery {
44
+ /** Match one exact Debug Operation ID. */
45
+ operationId?: string;
45
46
  source?: string;
46
47
  level?: DebugLevel;
47
48
  category?: string;
@@ -53,6 +54,7 @@ export interface DebugEventQuery {
53
54
  export interface DebugEventView {
54
55
  id: number;
55
56
  timestamp: number;
57
+ operationId?: string;
56
58
  source: string;
57
59
  level: DebugLevel;
58
60
  category: string;
@@ -84,6 +86,7 @@ interface DebugRegistryState {
84
86
  }
85
87
 
86
88
  const REGISTRY_KEY = Symbol.for("@mrclrchtr/supi-core/debug-registry");
89
+ const DEBUG_OPERATION_ID_RE = /^op-[A-Za-z0-9_-]{21}[AQgw]$/;
87
90
  const SECRET_KEY_RE = /(?:token|password|passwd|secret|api[_-]?key|authorization|credential)/i;
88
91
  const ENV_SECRET_RE =
89
92
  /\b([A-Za-z0-9_]*(?:token|password|passwd|secret|api[_-]?key|authorization|credential)[A-Za-z0-9_]*)=(?:'[^']*'|"[^"]*"|\S+)/gi;
@@ -135,11 +138,17 @@ export function isDebugLevel(value: unknown): value is DebugLevel {
135
138
  return value === "debug" || value === "info" || value === "warning" || value === "error";
136
139
  }
137
140
 
138
- /** Match a debug event against the supported source, level, and category filters. */
141
+ /** Return whether a value has the exact 16-byte base64url Debug Operation ID form. */
142
+ export function isDebugOperationId(value: unknown): value is string {
143
+ return typeof value === "string" && DEBUG_OPERATION_ID_RE.test(value);
144
+ }
145
+
146
+ /** Match a debug event against the supported exact filters. */
139
147
  export function matchesDebugEventQuery(
140
- event: Pick<DebugEventView, "source" | "level" | "category">,
141
- query: Pick<DebugEventQuery, "source" | "level" | "category">,
148
+ event: Pick<DebugEventView, "operationId" | "source" | "level" | "category">,
149
+ query: Pick<DebugEventQuery, "operationId" | "source" | "level" | "category">,
142
150
  ): boolean {
151
+ if (query.operationId && event.operationId !== query.operationId) return false;
143
152
  if (query.source && event.source !== query.source) return false;
144
153
  if (query.level && event.level !== query.level) return false;
145
154
  if (query.category && event.category !== query.category) return false;
@@ -197,6 +206,7 @@ function toSanitizedView(event: DebugEvent): DebugEventView {
197
206
  return {
198
207
  id: event.id,
199
208
  timestamp: event.timestamp,
209
+ operationId: event.operationId,
200
210
  source: event.source,
201
211
  level: event.level,
202
212
  category: event.category,
@@ -216,6 +226,9 @@ export function subscribeDebugEvents(listener: DebugEventListener): () => void {
216
226
  /** Record a session-local debug event if debugging is enabled. */
217
227
  export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
218
228
  const state = getState();
229
+ if (input.operationId !== undefined && !isDebugOperationId(input.operationId)) {
230
+ return null;
231
+ }
219
232
  if (!state.config.enabled) {
220
233
  return null;
221
234
  }
@@ -0,0 +1,9 @@
1
+ // Debug domain entry for `@mrclrchtr/supi-core/debug`.
2
+ //
3
+ // Kept separate from debug-registry.ts so debug-timing.ts can import the
4
+ // registry without creating an import cycle through the barrel re-export.
5
+
6
+ // biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
7
+ export * from "./debug-registry.ts";
8
+ // biome-ignore lint/performance/noReExportAll: preserve the stable debug domain entry point
9
+ export * from "./debug-timing.ts";
@@ -11,7 +11,7 @@ export * from "./config.ts";
11
11
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
12
12
  export * from "./context.ts";
13
13
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
14
- export * from "./debug-registry.ts";
14
+ export * from "./debug.ts";
15
15
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
16
16
  export * from "./footer-registry.ts";
17
17
  // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
@@ -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.10.0",
3
+ "version": "6.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.10.0"
35
+ "@mrclrchtr/supi-core": "6.0.0"
36
36
  },
37
37
  "bundledDependencies": [
38
38
  "@mrclrchtr/supi-core"
package/src/ask-user.ts CHANGED
@@ -1,40 +1,13 @@
1
- import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
2
  import {
3
3
  notifyToolPromptSurfaceDiagnostics,
4
4
  resolveToolPromptSurface,
5
5
  } from "@mrclrchtr/supi-core/prompt-surface";
6
6
  import { createSessionNameTracker } from "@mrclrchtr/supi-core/session";
7
- import { formatTitle, signalWaiting } from "@mrclrchtr/supi-core/terminal";
8
- import { AskUserValidationError, normalizeQuestionnaire } from "./normalize.ts";
9
- import { type AskUserToolResult, buildResult } from "./render/result.ts";
10
- import { renderAskUserCall, renderAskUserResult } from "./render/transcript.ts";
11
- import { type AskUserParams, AskUserParamsSchema } from "./schema.ts";
12
7
  import { ActiveQuestionnaireLock } from "./session/lock.ts";
13
- import {
14
- ASK_USER_PROMPT_SURFACE_DEFAULTS,
15
- ASK_USER_TOOL_LABEL,
16
- ASK_USER_TOOL_NAME,
17
- } from "./tool/guidance.ts";
18
- import type {
19
- AskUserInteractionResult,
20
- AskUserOutcome,
21
- AskUserToolDetails,
22
- NormalizedQuestionnaire,
23
- } from "./types.ts";
24
- import { runQuestionnaire } from "./ui/choose-renderer.ts";
25
- import type { EditorFactory } from "./ui/types.ts";
26
-
27
- export type AskUserExecutionContext = Pick<ExtensionContext, "cwd" | "hasUI" | "mode" | "abort"> & {
28
- ui: {
29
- custom?: unknown;
30
- notify?(message: string, type?: "info" | "warning" | "error"): void;
31
- setWorkingVisible?(visible: boolean): void;
32
- setTitle?(title: string): void;
33
- getToolsExpanded?(): boolean;
34
- setToolsExpanded?(expanded: boolean): void;
35
- getEditorComponent?(): EditorFactory | undefined;
36
- };
37
- };
8
+ import { ASK_USER_PROMPT_SURFACE_DEFAULTS } from "./tool/ask_user/guidance.ts";
9
+ import { registerAskUserTool } from "./tool/ask_user/register.ts";
10
+ import { ASK_USER_TOOL_NAME } from "./tool/ask_user/spec.ts";
38
11
 
39
12
  export default function askUserExtension(pi: ExtensionAPI): void {
40
13
  const lock = new ActiveQuestionnaireLock();
@@ -63,10 +36,12 @@ export default function askUserExtension(pi: ExtensionAPI): void {
63
36
  }, 0);
64
37
  });
65
38
 
66
- // Factory-time: register with package defaults.
67
- registerAskUserTool(pi, lock, ASK_USER_PROMPT_SURFACE_DEFAULTS, getSessionName);
68
-
69
- // session_start: re-register with resolved prompt surface (global + trusted project config).
39
+ // Register ask_user only for interactive TUI sessions: the form UI has no
40
+ // degraded fallback, so the tool must not be offered in RPC, JSON, or print
41
+ // modes. The run mode is only available on the event context, not at
42
+ // extension factory time, so registration happens on session_start instead
43
+ // of eagerly at load. Config diagnostics stay mode-independent and are
44
+ // still reported so misconfigured prompt surfaces surface in every mode.
70
45
  pi.on("session_start", async (_event, ctx) => {
71
46
  const { surface, diagnostics } = resolveToolPromptSurface({
72
47
  section: "ask-user",
@@ -74,136 +49,18 @@ export default function askUserExtension(pi: ExtensionAPI): void {
74
49
  defaults: ASK_USER_PROMPT_SURFACE_DEFAULTS,
75
50
  ctx,
76
51
  });
77
-
78
- registerAskUserTool(pi, lock, surface, getSessionName);
79
52
  notifyToolPromptSurfaceDiagnostics(ctx, diagnostics);
80
- });
81
- }
82
53
 
83
- function registerAskUserTool(
84
- pi: ExtensionAPI,
85
- lock: ActiveQuestionnaireLock,
86
- surface: typeof ASK_USER_PROMPT_SURFACE_DEFAULTS,
87
- getSessionName: () => string | undefined,
88
- ): void {
89
- pi.registerTool<typeof AskUserParamsSchema, AskUserToolDetails>({
90
- name: ASK_USER_TOOL_NAME,
91
- label: ASK_USER_TOOL_LABEL,
92
- description: surface.description,
93
- promptSnippet: surface.promptSnippet,
94
- promptGuidelines: surface.promptGuidelines,
95
- parameters: AskUserParamsSchema,
96
- executionMode: "sequential",
97
- // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
98
- async execute(_toolCallId, params, signal, _onUpdate, ctx) {
99
- return executeAskUser(params, signal, ctx, lock, pi, getSessionName());
100
- },
101
- renderCall: (args, theme) => renderAskUserCall(args, theme),
102
- renderResult: (result, options, theme, context) =>
103
- renderAskUserResult(result, theme, options, context),
104
- });
105
- }
106
-
107
- // biome-ignore lint/complexity/useMaxParams: keep the execution boundary explicit for tests
108
- export async function executeAskUser(
109
- params: AskUserParams,
110
- signal: AbortSignal | undefined,
111
- ctx: AskUserExecutionContext,
112
- lock: ActiveQuestionnaireLock,
113
- pi: ExtensionAPI,
114
- sessionName?: string,
115
- ): Promise<AskUserToolResult> {
116
- let questionnaire: NormalizedQuestionnaire;
117
- try {
118
- questionnaire = normalizeQuestionnaire(params);
119
- } catch (error) {
120
- if (error instanceof AskUserValidationError) {
121
- throw new Error(error.message, { cause: error });
122
- }
123
- throw error;
124
- }
125
-
126
- if (!ctx.hasUI || ctx.mode !== "tui") {
127
- throw new Error(
128
- "ask_user requires an interactive TUI session. No user-facing form UI is available in the current mode.",
129
- );
130
- }
131
- if (!lock.acquire()) {
132
- throw new Error(
133
- "another ask_user form is already in flight. Wait for it to complete before calling ask_user again.",
134
- );
135
- }
136
-
137
- signalAttention(ctx);
138
- pi.events.emit("supi:ask-user:start", { source: "supi-ask-user" });
139
-
140
- try {
141
- ctx.ui.setWorkingVisible?.(false);
142
- const outcome = await runQuestionnaire(questionnaire, {
143
- ui: {
144
- custom: asFunction(ctx.ui.custom),
145
- notify: ctx.ui.notify,
146
- getEditorComponent: ctx.ui.getEditorComponent
147
- ? () => ctx.ui.getEditorComponent?.()
148
- : undefined,
149
- },
150
- signal,
151
- onToggleToolsExpanded:
152
- ctx.ui.getToolsExpanded && ctx.ui.setToolsExpanded
153
- ? () => ctx.ui.setToolsExpanded?.(!ctx.ui.getToolsExpanded?.())
154
- : undefined,
155
- });
54
+ if (ctx.mode !== "tui") return;
156
55
 
157
- if (outcome === "unsupported") {
158
- throw new Error(
159
- "ask_user requires a TUI with custom form support. Do not use ask_user in non-interactive or degraded UI sessions.",
160
- );
161
- }
162
-
163
- // Internal cancel/abort: treat as control flow, abort the turn, and mark the tool failed.
164
- if (isInternalInteractionResult(outcome)) {
165
- ctx.abort();
166
- throw new Error("The user interaction was cancelled.");
167
- }
168
-
169
- pi.appendEntry("ask_user", {
170
- title: questionnaire.title,
171
- questions: questionnaire.questions.length,
172
- });
173
- return buildResult(questionnaire, outcome);
174
- } finally {
175
- ctx.ui.setWorkingVisible?.(true);
176
- pi.events.emit("supi:ask-user:end", { source: "supi-ask-user" });
177
- restoreTerminalTitle(ctx, sessionName);
178
- lock.release();
179
- }
180
- }
181
-
182
- function isInternalInteractionResult(
183
- outcome: AskUserOutcome | AskUserInteractionResult | "unsupported",
184
- ): outcome is AskUserInteractionResult {
185
- return (
186
- typeof outcome === "object" &&
187
- "kind" in outcome &&
188
- (outcome.kind === "cancel" || outcome.kind === "abort")
189
- );
190
- }
191
-
192
- function signalAttention(ctx: AskUserExecutionContext): void {
193
- signalWaiting(ctx, "pi — waiting for your input");
194
- }
195
-
196
- function restoreTerminalTitle(ctx: AskUserExecutionContext, sessionName: string | undefined): void {
197
- ctx.ui.setTitle?.(formatTitle(sessionName, ctx.cwd));
198
- }
199
-
200
- function asFunction<T extends (...args: never[]) => unknown>(value: unknown): T | undefined {
201
- return typeof value === "function" ? (value as T) : undefined;
56
+ registerAskUserTool(pi, lock, surface, getSessionName);
57
+ });
202
58
  }
203
59
 
204
60
  export { AskUserValidationError, normalizeQuestionnaire } from "./normalize.ts";
205
61
  export { AskUserController } from "./session/controller.ts";
62
+ export { type AskUserExecutionContext, executeAskUser } from "./tool/ask_user/execute.ts";
206
63
  export {
207
64
  promptGuidelines as askUserPromptGuidelines,
208
65
  promptSnippet as askUserPromptSnippet,
209
- } from "./tool/guidance.ts";
66
+ } from "./tool/ask_user/guidance.ts";
package/src/schema.ts CHANGED
@@ -34,7 +34,7 @@ const ChoiceQuestionSchema = Type.Object({
34
34
  header: Type.String({ description: "Short label" }),
35
35
  prompt: Type.String({ description: "Question text" }),
36
36
  options: Type.Array(OptionSchema, {
37
- description: "Allowed options with unique values",
37
+ description: "Each option requires `label` (shown text) and a unique `value` (returned id).",
38
38
  ...ChoiceOptionCount,
39
39
  }),
40
40
  multi: Type.Optional(
@@ -0,0 +1,122 @@
1
+ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
2
+ import { formatTitle, signalWaiting } from "@mrclrchtr/supi-core/terminal";
3
+ import { AskUserValidationError, normalizeQuestionnaire } from "../../normalize.ts";
4
+ import type { AskUserParams } from "../../schema.ts";
5
+ import type { ActiveQuestionnaireLock } from "../../session/lock.ts";
6
+ import type {
7
+ AskUserInteractionResult,
8
+ AskUserOutcome,
9
+ NormalizedQuestionnaire,
10
+ } from "../../types.ts";
11
+ import { runQuestionnaire } from "../../ui/choose-renderer.ts";
12
+ import type { EditorFactory } from "../../ui/types.ts";
13
+ import { type AskUserToolResult, buildResult } from "./result.ts";
14
+
15
+ export type AskUserExecutionContext = Pick<ExtensionContext, "cwd" | "hasUI" | "mode" | "abort"> & {
16
+ ui: {
17
+ custom?: unknown;
18
+ notify?(message: string, type?: "info" | "warning" | "error"): void;
19
+ setWorkingVisible?(visible: boolean): void;
20
+ setTitle?(title: string): void;
21
+ getToolsExpanded?(): boolean;
22
+ setToolsExpanded?(expanded: boolean): void;
23
+ getEditorComponent?(): EditorFactory | undefined;
24
+ };
25
+ };
26
+
27
+ // biome-ignore lint/complexity/useMaxParams: keep the execution boundary explicit for tests
28
+ export async function executeAskUser(
29
+ params: AskUserParams,
30
+ signal: AbortSignal | undefined,
31
+ ctx: AskUserExecutionContext,
32
+ lock: ActiveQuestionnaireLock,
33
+ pi: ExtensionAPI,
34
+ sessionName?: string,
35
+ ): Promise<AskUserToolResult> {
36
+ let questionnaire: NormalizedQuestionnaire;
37
+ try {
38
+ questionnaire = normalizeQuestionnaire(params);
39
+ } catch (error) {
40
+ if (error instanceof AskUserValidationError) {
41
+ throw new Error(error.message, { cause: error });
42
+ }
43
+ throw error;
44
+ }
45
+
46
+ if (!ctx.hasUI || ctx.mode !== "tui") {
47
+ throw new Error(
48
+ "ask_user requires an interactive TUI session. No user-facing form UI is available in the current mode.",
49
+ );
50
+ }
51
+ if (!lock.acquire()) {
52
+ throw new Error(
53
+ "another ask_user form is already in flight. Wait for it to complete before calling ask_user again.",
54
+ );
55
+ }
56
+
57
+ signalAttention(ctx);
58
+ pi.events.emit("supi:ask-user:start", { source: "supi-ask-user" });
59
+
60
+ try {
61
+ ctx.ui.setWorkingVisible?.(false);
62
+ const outcome = await runQuestionnaire(questionnaire, {
63
+ ui: {
64
+ custom: asFunction(ctx.ui.custom),
65
+ notify: ctx.ui.notify,
66
+ getEditorComponent: ctx.ui.getEditorComponent
67
+ ? () => ctx.ui.getEditorComponent?.()
68
+ : undefined,
69
+ },
70
+ signal,
71
+ onToggleToolsExpanded:
72
+ ctx.ui.getToolsExpanded && ctx.ui.setToolsExpanded
73
+ ? () => ctx.ui.setToolsExpanded?.(!ctx.ui.getToolsExpanded?.())
74
+ : undefined,
75
+ });
76
+
77
+ if (outcome === "unsupported") {
78
+ throw new Error(
79
+ "ask_user requires a TUI with custom form support. Do not use ask_user in non-interactive or degraded UI sessions.",
80
+ );
81
+ }
82
+
83
+ // Internal cancel/abort: treat as control flow, abort the turn, and mark the tool failed.
84
+ if (isInternalInteractionResult(outcome)) {
85
+ ctx.abort();
86
+ throw new Error("The user interaction was cancelled.");
87
+ }
88
+
89
+ pi.appendEntry("ask_user", {
90
+ title: questionnaire.title,
91
+ questions: questionnaire.questions.length,
92
+ });
93
+ return buildResult(questionnaire, outcome);
94
+ } finally {
95
+ ctx.ui.setWorkingVisible?.(true);
96
+ pi.events.emit("supi:ask-user:end", { source: "supi-ask-user" });
97
+ restoreTerminalTitle(ctx, sessionName);
98
+ lock.release();
99
+ }
100
+ }
101
+
102
+ function isInternalInteractionResult(
103
+ outcome: AskUserOutcome | AskUserInteractionResult | "unsupported",
104
+ ): outcome is AskUserInteractionResult {
105
+ return (
106
+ typeof outcome === "object" &&
107
+ "kind" in outcome &&
108
+ (outcome.kind === "cancel" || outcome.kind === "abort")
109
+ );
110
+ }
111
+
112
+ function signalAttention(ctx: AskUserExecutionContext): void {
113
+ signalWaiting(ctx, "pi — waiting for your input");
114
+ }
115
+
116
+ function restoreTerminalTitle(ctx: AskUserExecutionContext, sessionName: string | undefined): void {
117
+ ctx.ui.setTitle?.(formatTitle(sessionName, ctx.cwd));
118
+ }
119
+
120
+ function asFunction<T extends (...args: never[]) => unknown>(value: unknown): T | undefined {
121
+ return typeof value === "function" ? (value as T) : undefined;
122
+ }
@@ -2,9 +2,6 @@
2
2
 
3
3
  import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "@earendil-works/pi-coding-agent";
4
4
 
5
- export const ASK_USER_TOOL_NAME = "ask_user";
6
- export const ASK_USER_TOOL_LABEL = "Ask User";
7
-
8
5
  export const toolDescription = `Open a blocking interactive TUI decision form for focused user input. Supports 1-10 choice/text questions, one active form, and sequential execution; requires TUI custom UI. Result text is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}.`;
9
6
 
10
7
  export const promptSnippet = "ask_user — request a focused blocking user decision";
@@ -0,0 +1,33 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+ import type { AskUserParamsSchema } from "../../schema.ts";
3
+ import type { ActiveQuestionnaireLock } from "../../session/lock.ts";
4
+ import type { AskUserToolDetails } from "../../types.ts";
5
+ import { executeAskUser } from "./execute.ts";
6
+ import type { ASK_USER_PROMPT_SURFACE_DEFAULTS } from "./guidance.ts";
7
+ import { renderAskUserCall, renderAskUserResult } from "./render.ts";
8
+ import { askUserSpec } from "./spec.ts";
9
+
10
+ /** Shape of the configurable ask_user prompt surface. */
11
+ export type AskUserPromptSurface = typeof ASK_USER_PROMPT_SURFACE_DEFAULTS;
12
+
13
+ /** Register ask_user with one resolved prompt surface. */
14
+ export function registerAskUserTool(
15
+ pi: ExtensionAPI,
16
+ lock: ActiveQuestionnaireLock,
17
+ surface: AskUserPromptSurface,
18
+ getSessionName: () => string | undefined,
19
+ ): void {
20
+ pi.registerTool<typeof AskUserParamsSchema, AskUserToolDetails>({
21
+ ...askUserSpec,
22
+ description: surface.description,
23
+ promptSnippet: surface.promptSnippet,
24
+ promptGuidelines: surface.promptGuidelines,
25
+ // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
26
+ async execute(_toolCallId, params, signal, _onUpdate, ctx) {
27
+ return executeAskUser(params, signal, ctx, lock, pi, getSessionName());
28
+ },
29
+ renderCall: (args, theme) => renderAskUserCall(args, theme),
30
+ renderResult: (result, options, theme, context) =>
31
+ renderAskUserResult(result, theme, options, context),
32
+ });
33
+ }
@@ -1,15 +1,15 @@
1
1
  import { type AgentToolResult, keyText, type Theme } from "@earendil-works/pi-coding-agent";
2
2
  import { Text } from "@earendil-works/pi-tui";
3
- import type { AskUserParams } from "../schema.ts";
4
- import { ASK_USER_TOOL_NAME } from "../tool/guidance.ts";
3
+ import type { AskUserParams } from "../../schema.ts";
5
4
  import type {
6
5
  AskUserDetails,
7
6
  AskUserOutcomeKind,
8
7
  AskUserResponse,
9
8
  AskUserToolDetails,
10
9
  NormalizedQuestion,
11
- } from "../types.ts";
12
- import { isErrorDetails } from "../types.ts";
10
+ } from "../../types.ts";
11
+ import { isErrorDetails } from "../../types.ts";
12
+ import { ASK_USER_TOOL_NAME } from "./spec.ts";
13
13
 
14
14
  const COLLAPSED_ANSWER_LIMIT = 2;
15
15
  const DEFAULT_REVIEW_KEY = "Ctrl+O";
@@ -14,7 +14,7 @@ import type {
14
14
  ChoiceQuestionResponse,
15
15
  NormalizedQuestion,
16
16
  NormalizedQuestionnaire,
17
- } from "../types.ts";
17
+ } from "../../types.ts";
18
18
 
19
19
  export type AskUserToolResult = AgentToolResult<AskUserToolDetails>;
20
20