@mrclrchtr/supi-ask-user 2.2.1 → 2.3.1

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
@@ -41,8 +41,8 @@ The model-visible result summary is bounded to Pi's default tool-output limits:
41
41
  <table>
42
42
  <tr>
43
43
  <td align="center">
44
- <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-choice-preview.png" width="100%" alt="Choice question with side preview" />
45
- <br/>Choice question with side preview
44
+ <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-choice-details.png" width="100%" alt="Choice question with side details" />
45
+ <br/>Choice question with side details
46
46
  </td>
47
47
  <td align="center">
48
48
  <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" />
@@ -51,8 +51,8 @@ The model-visible result summary is bounded to Pi's default tool-output limits:
51
51
  </tr>
52
52
  <tr>
53
53
  <td align="center">
54
- <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-multi-choice-preview.png" width="100%" alt="Multi-select with preview" />
55
- <br/>Multi-select with preview
54
+ <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 with details" />
55
+ <br/>Multi-select with details
56
56
  </td>
57
57
  <td align="center">
58
58
  <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-text-input.png" width="100%" alt="Text input with recommendation" />
@@ -110,4 +110,4 @@ The model-visible result summary is bounded to Pi's default tool-output limits:
110
110
  | `Enter` | Save comment and return |
111
111
  | `Esc` | Discard comment edits and return |
112
112
 
113
- The recommended option is labeled `[recommended]`. On wide terminals, option previews render side-by-side with the list; on narrow terminals they stack below.
113
+ The recommended option is labeled `[recommended]`. On wide terminals, option details render side-by-side with the list; on narrow terminals they stack below.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-core",
3
- "version": "2.2.1",
3
+ "version": "2.3.1",
4
4
  "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -2,6 +2,48 @@
2
2
 
3
3
  import type { FileEntry, SessionEntry } from "@earendil-works/pi-coding-agent";
4
4
 
5
+ /**
6
+ * Minimal pi API surface needed to track the current session display name reactively.
7
+ * Accept `ExtensionAPI` or any object satisfying this shape.
8
+ */
9
+ export interface SessionNameTrackerHost {
10
+ on(event: string, handler: (...args: unknown[]) => unknown): void;
11
+ getSessionName(): string | undefined;
12
+ }
13
+
14
+ /**
15
+ * Create a reactive session-name tracker that stays consistent across
16
+ * session starts, renames, and shutdowns without polling.
17
+ *
18
+ * Subscribes to `session_start` (initial name), `session_info_changed`
19
+ * (renames via `/name`, `pi.setSessionName()`, or RPC), and
20
+ * `session_shutdown` (reset to `undefined`).
21
+ *
22
+ * @returns a zero-arg getter that always returns the current session name
23
+ *
24
+ * @example
25
+ * ```ts
26
+ * const getSessionName = createSessionNameTracker(pi);
27
+ * // …later, during tool execute or spinner rendering:
28
+ * const name = getSessionName();
29
+ * ```
30
+ */
31
+ export function createSessionNameTracker(pi: SessionNameTrackerHost): () => string | undefined {
32
+ let name: string | undefined;
33
+
34
+ pi.on("session_start", () => {
35
+ name = pi.getSessionName();
36
+ });
37
+ pi.on("session_info_changed", (event) => {
38
+ name = (event as { name?: string }).name;
39
+ });
40
+ pi.on("session_shutdown", () => {
41
+ name = undefined;
42
+ });
43
+
44
+ return () => name;
45
+ }
46
+
5
47
  /**
6
48
  * Resolve the active branch path using PI's append-only tree semantics.
7
49
  *
@@ -1,4 +1,8 @@
1
1
  // supi-core session domain — session utilities and registries.
2
2
 
3
3
  export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
4
- export { getActiveBranchEntries } from "./session-utils.ts";
4
+ export type { SessionNameTrackerHost } from "./session-utils.ts";
5
+ export {
6
+ createSessionNameTracker,
7
+ getActiveBranchEntries,
8
+ } from "./session-utils.ts";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-ask-user",
3
- "version": "2.2.1",
3
+ "version": "2.3.1",
4
4
  "description": "SuPi ask-user extension — rich questionnaire UI for structured 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": "2.2.1"
35
+ "@mrclrchtr/supi-core": "2.3.1"
36
36
  },
37
37
  "bundledDependencies": [
38
38
  "@mrclrchtr/supi-core"
@@ -57,7 +57,7 @@
57
57
  "extensions": [
58
58
  "./src/extension.ts"
59
59
  ],
60
- "image": "https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-choice-preview.png"
60
+ "image": "https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-ask-user/assets/ask-user-choice-details.png"
61
61
  },
62
62
  "main": "src/api.ts",
63
63
  "exports": {
package/src/ask-user.ts CHANGED
@@ -3,11 +3,11 @@ import {
3
3
  notifyToolPromptSurfaceDiagnostics,
4
4
  resolveToolPromptSurface,
5
5
  } from "@mrclrchtr/supi-core/prompt-surface";
6
+ import { createSessionNameTracker } from "@mrclrchtr/supi-core/session";
6
7
  import { formatTitle, signalWaiting } from "@mrclrchtr/supi-core/terminal";
7
8
  import { AskUserValidationError, normalizeQuestionnaire } from "./normalize.ts";
8
9
  import { type AskUserToolResult, buildResult } from "./render/result.ts";
9
10
  import { renderAskUserCall, renderAskUserResult } from "./render/transcript.ts";
10
- import { buildTreeSummaryLabel } from "./render/tree-summary.ts";
11
11
  import { type AskUserParams, AskUserParamsSchema } from "./schema.ts";
12
12
  import { ActiveQuestionnaireLock } from "./session/lock.ts";
13
13
  import {
@@ -36,9 +36,33 @@ export type AskUserExecutionContext = Pick<ExtensionContext, "cwd" | "hasUI" | "
36
36
 
37
37
  export default function askUserExtension(pi: ExtensionAPI): void {
38
38
  const lock = new ActiveQuestionnaireLock();
39
+ const getSessionName = createSessionNameTracker(pi);
40
+
41
+ // Label ask_user tool results so they're visible and filterable in /tree.
42
+ // Use a non-awaited setTimeout: the agent awaits our handler's return before
43
+ // it appends the tool result to the session, so we must let the handler resolve
44
+ // first and label from a deferred callback.
45
+ pi.on("tool_result", (event, ctx) => {
46
+ if (event.toolName !== ASK_USER_TOOL_NAME) return;
47
+ const toolCallId = event.toolCallId;
48
+ setTimeout(() => {
49
+ const entries = ctx.sessionManager.getEntries();
50
+ const entry = [...entries]
51
+ .reverse()
52
+ .find(
53
+ (e) =>
54
+ e.type === "message" &&
55
+ e.message.role === "toolResult" &&
56
+ e.message.toolCallId === toolCallId,
57
+ );
58
+ if (entry) {
59
+ pi.setLabel(entry.id, "decision");
60
+ }
61
+ }, 0);
62
+ });
39
63
 
40
64
  // Factory-time: register with package defaults.
41
- registerAskUserTool(pi, lock, ASK_USER_PROMPT_SURFACE_DEFAULTS);
65
+ registerAskUserTool(pi, lock, ASK_USER_PROMPT_SURFACE_DEFAULTS, getSessionName);
42
66
 
43
67
  // session_start: re-register with resolved prompt surface (global + trusted project config).
44
68
  pi.on("session_start", async (_event, ctx) => {
@@ -49,7 +73,7 @@ export default function askUserExtension(pi: ExtensionAPI): void {
49
73
  ctx,
50
74
  });
51
75
 
52
- registerAskUserTool(pi, lock, surface);
76
+ registerAskUserTool(pi, lock, surface, getSessionName);
53
77
  notifyToolPromptSurfaceDiagnostics(ctx, diagnostics);
54
78
  });
55
79
  }
@@ -58,6 +82,7 @@ function registerAskUserTool(
58
82
  pi: ExtensionAPI,
59
83
  lock: ActiveQuestionnaireLock,
60
84
  surface: typeof ASK_USER_PROMPT_SURFACE_DEFAULTS,
85
+ getSessionName: () => string | undefined,
61
86
  ): void {
62
87
  pi.registerTool<typeof AskUserParamsSchema, AskUserToolDetails>({
63
88
  name: ASK_USER_TOOL_NAME,
@@ -69,7 +94,7 @@ function registerAskUserTool(
69
94
  executionMode: "sequential",
70
95
  // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
71
96
  async execute(_toolCallId, params, signal, _onUpdate, ctx) {
72
- return executeAskUser(params, signal, ctx, lock, pi);
97
+ return executeAskUser(params, signal, ctx, lock, pi, getSessionName());
73
98
  },
74
99
  renderCall: (args, theme) => renderAskUserCall(args, theme),
75
100
  renderResult: (result, options, theme, context) =>
@@ -84,6 +109,7 @@ export async function executeAskUser(
84
109
  ctx: AskUserExecutionContext,
85
110
  lock: ActiveQuestionnaireLock,
86
111
  pi: ExtensionAPI,
112
+ sessionName?: string,
87
113
  ): Promise<AskUserToolResult> {
88
114
  let questionnaire: NormalizedQuestionnaire;
89
115
  try {
@@ -135,12 +161,15 @@ export async function executeAskUser(
135
161
  throw new Error("The user interaction was cancelled.");
136
162
  }
137
163
 
138
- pi.appendEntry(buildTreeSummaryLabel(questionnaire));
164
+ pi.appendEntry("ask_user", {
165
+ title: questionnaire.title,
166
+ questions: questionnaire.questions.length,
167
+ });
139
168
  return buildResult(questionnaire, outcome);
140
169
  } finally {
141
170
  ctx.ui.setWorkingVisible?.(true);
142
171
  pi.events.emit("supi:ask-user:end", { source: "supi-ask-user" });
143
- restoreTerminalTitle(ctx, pi);
172
+ restoreTerminalTitle(ctx, sessionName);
144
173
  lock.release();
145
174
  }
146
175
  }
@@ -159,8 +188,8 @@ function signalAttention(ctx: AskUserExecutionContext): void {
159
188
  signalWaiting(ctx, "pi — waiting for your input");
160
189
  }
161
190
 
162
- function restoreTerminalTitle(ctx: AskUserExecutionContext, pi: ExtensionAPI): void {
163
- ctx.ui.setTitle?.(formatTitle(pi.getSessionName(), ctx.cwd));
191
+ function restoreTerminalTitle(ctx: AskUserExecutionContext, sessionName: string | undefined): void {
192
+ ctx.ui.setTitle?.(formatTitle(sessionName, ctx.cwd));
164
193
  }
165
194
 
166
195
  function asFunction<T extends (...args: never[]) => unknown>(value: unknown): T | undefined {
package/src/normalize.ts CHANGED
@@ -195,7 +195,7 @@ function normalizeOptions(
195
195
  value,
196
196
  label,
197
197
  description: trimOptional(option.description),
198
- preview: trimOptional(option.preview),
198
+ details: trimOptional(option.details),
199
199
  };
200
200
  });
201
201
  }
package/src/schema.ts CHANGED
@@ -11,9 +11,10 @@ const OptionSchema = Type.Object({
11
11
  description: "Optional helper text",
12
12
  }),
13
13
  ),
14
- preview: Type.Optional(
14
+ details: Type.Optional(
15
15
  Type.String({
16
- description: "Optional focused-option preview",
16
+ description:
17
+ "Extended details shown when focused — trade-offs, code snippets, or consequences",
17
18
  }),
18
19
  ),
19
20
  });
@@ -13,6 +13,7 @@ export const promptGuidelines = [
13
13
  "Use ask_user only when blocked after inspecting what can be inspected; not for status updates or broad surveys.",
14
14
  "Use ask_user for one decision form; combine related choice/text questions and avoid sibling tool calls that depend on the answer.",
15
15
  "In ask_user, use stable ids/values; recommendations must match question type, and unanswered questions return `needs_discussion`.",
16
+ "Set option.details on ask_user choice questions for trade-offs, code samples, or context the user needs to decide.",
16
17
  ];
17
18
 
18
19
  /** Package defaults for the ask_user prompt surface (used by the config resolver). */
package/src/types.ts CHANGED
@@ -6,7 +6,7 @@ export interface NormalizedOption {
6
6
  value: string;
7
7
  label: string;
8
8
  description?: string;
9
- preview?: string;
9
+ details?: string;
10
10
  }
11
11
 
12
12
  interface BaseQuestion {
@@ -72,7 +72,7 @@ export class AskUserForm implements Component, Focusable {
72
72
  editor: this.editor,
73
73
  choiceFocusIndex: this.choiceFocusIndex,
74
74
  reviewFocusIndex: this.reviewFocusIndex,
75
- previewText: this.currentPreviewText(),
75
+ detailsText: this.currentDetailsText(),
76
76
  editorLabel: this.currentEditorLabel(),
77
77
  editorContext: this.editorContext,
78
78
  });
@@ -539,11 +539,11 @@ export class AskUserForm implements Component, Focusable {
539
539
  this.args.tui.requestRender();
540
540
  }
541
541
 
542
- private currentPreviewText(): string | undefined {
542
+ private currentDetailsText(): string | undefined {
543
543
  if (this.mode !== "choice") return undefined;
544
544
  const question = this.args.controller.currentQuestion;
545
545
  if (question.type !== "choice") return undefined;
546
- return question.options[this.choiceFocusIndex]?.preview;
546
+ return question.options[this.choiceFocusIndex]?.details;
547
547
  }
548
548
 
549
549
  private currentEditorLabel(): string | undefined {
@@ -22,7 +22,7 @@ export interface RenderFormFrameArgs {
22
22
  editor: Editor;
23
23
  choiceFocusIndex: number;
24
24
  reviewFocusIndex: number;
25
- previewText?: string;
25
+ detailsText?: string;
26
26
  editorLabel?: string;
27
27
  editorContext?: string;
28
28
  }
@@ -130,8 +130,8 @@ function renderChoiceScreen(args: RenderFormFrameArgs): string[] {
130
130
  }
131
131
  lines.push("");
132
132
 
133
- if (args.previewText && args.width >= 80) {
134
- lines.push(...renderChoiceWithPreview(args, question));
133
+ if (args.detailsText && args.width >= 80) {
134
+ lines.push(...renderChoiceWithDetails(args, question));
135
135
  return lines;
136
136
  }
137
137
 
@@ -139,15 +139,15 @@ function renderChoiceScreen(args: RenderFormFrameArgs): string[] {
139
139
  lines.push(...renderChoiceOptionLines(args, question, i, args.width));
140
140
  }
141
141
 
142
- if (args.previewText) {
142
+ if (args.detailsText) {
143
143
  lines.push("");
144
- lines.push(...renderPreviewCard(args.theme, args.previewText, args.width));
144
+ lines.push(...renderDetailsCard(args.theme, args.detailsText, args.width));
145
145
  }
146
146
 
147
147
  return lines;
148
148
  }
149
149
 
150
- function renderChoiceWithPreview(
150
+ function renderChoiceWithDetails(
151
151
  args: RenderFormFrameArgs,
152
152
  question: NormalizedChoiceQuestion,
153
153
  ): string[] {
@@ -155,10 +155,10 @@ function renderChoiceWithPreview(
155
155
  const divider = args.theme.fg("borderMuted", "│");
156
156
  const dividerWidth = 1;
157
157
  const minLeftWidth = 28;
158
- const preferredPreviewWidth = Math.max(30, Math.floor(args.width * 0.38));
158
+ const preferredDetailsWidth = Math.max(30, Math.floor(args.width * 0.38));
159
159
  const rightWidth = Math.max(
160
160
  22,
161
- Math.min(preferredPreviewWidth, args.width - gap - dividerWidth - gap - minLeftWidth),
161
+ Math.min(preferredDetailsWidth, args.width - gap - dividerWidth - gap - minLeftWidth),
162
162
  );
163
163
  const leftWidth = Math.max(1, args.width - gap - dividerWidth - gap - rightWidth);
164
164
 
@@ -167,13 +167,13 @@ function renderChoiceWithPreview(
167
167
  optionLines.push(...renderChoiceOptionLines(args, question, i, leftWidth));
168
168
  }
169
169
 
170
- const previewLines = renderPreviewCard(args.theme, args.previewText ?? "", rightWidth);
170
+ const detailsLines = renderDetailsCard(args.theme, args.detailsText ?? "", rightWidth);
171
171
 
172
172
  const merged: string[] = [];
173
- const maxRows = Math.max(optionLines.length, previewLines.length);
173
+ const maxRows = Math.max(optionLines.length, detailsLines.length);
174
174
  for (let i = 0; i < maxRows; i += 1) {
175
175
  const left = optionLines[i] ?? "";
176
- const right = previewLines[i] ?? "";
176
+ const right = detailsLines[i] ?? "";
177
177
  const mergedLine = `${padRight(left, leftWidth)}${" ".repeat(gap)}${divider}${" ".repeat(gap)}${right}`;
178
178
  merged.push(truncateToWidth(mergedLine, args.width));
179
179
  }
@@ -251,9 +251,9 @@ function renderEditorScreen(args: RenderFormFrameArgs): string[] {
251
251
  return lines;
252
252
  }
253
253
 
254
- function renderPreviewCard(theme: Theme, previewText: string, width: number): string[] {
254
+ function renderDetailsCard(theme: Theme, detailsText: string, width: number): string[] {
255
255
  const innerWidth = Math.max(1, safeWidth(width) - 4);
256
- return renderMiniBox(theme, "Preview", renderPrompt(previewText, innerWidth), width);
256
+ return renderMiniBox(theme, "Details", renderPrompt(detailsText, innerWidth), width);
257
257
  }
258
258
 
259
259
  function renderFooter(args: RenderFormFrameArgs): string {
@@ -1,10 +0,0 @@
1
- import type { NormalizedQuestionnaire } from "../types.ts";
2
-
3
- export function buildTreeSummaryLabel(
4
- questionnaire: Pick<NormalizedQuestionnaire, "title" | "questions">,
5
- ): string {
6
- const base =
7
- questionnaire.title?.trim() || questionnaire.questions.map((q) => q.header).join(", ");
8
- const trimmed = base.length > 70 ? `${base.slice(0, 67)}...` : base;
9
- return `ask_user · ${trimmed}`;
10
- }