@mrclrchtr/supi-ask-user 2.4.0 → 2.5.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
@@ -30,6 +30,8 @@ All questions are expected to be answered before the form can be submitted. If y
30
30
 
31
31
  You can also add comments to individual questions, options, or the whole form if you want to explain your thinking.
32
32
 
33
+ If you have configured a custom Pi editor, such as a Vim or Emacs editor, Ask User creates one editor instance per form and reuses it for text answers and all comment fields. If the custom editor cannot be initialized or does not satisfy Pi's editor contract, Ask User warns and uses the default editor for that form. The decision form keeps ownership of its navigation shortcuts; main-prompt actions such as model switching are not reproduced inside the form.
34
+
33
35
  ## Agent-facing behavior
34
36
 
35
37
  `ask_user` is an interactive TUI-only handoff. The agent should use one form for one focused decision, combine related questions instead of opening multiple forms, and wait for the result before doing work that depends on your answer. Only one form can be active at a time.
@@ -110,4 +112,6 @@ The model-visible result summary is bounded to Pi's default tool-output limits:
110
112
  | `Enter` | Save comment and return |
111
113
  | `Esc` | Discard comment edits and return |
112
114
 
115
+ With a modal custom editor, `Esc` is offered to the editor first so it can leave insert mode. When the editor delegates the interrupt, Ask User performs the cancel or discard action shown above.
116
+
113
117
  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.4.0",
3
+ "version": "2.5.0",
4
4
  "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
5
5
  "license": "MIT",
6
6
  "repository": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrclrchtr/supi-ask-user",
3
- "version": "2.4.0",
3
+ "version": "2.5.0",
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.4.0"
35
+ "@mrclrchtr/supi-core": "2.5.0"
36
36
  },
37
37
  "bundledDependencies": [
38
38
  "@mrclrchtr/supi-core"
package/src/ask-user.ts CHANGED
@@ -22,6 +22,7 @@ import type {
22
22
  NormalizedQuestionnaire,
23
23
  } from "./types.ts";
24
24
  import { runQuestionnaire } from "./ui/choose-renderer.ts";
25
+ import type { EditorFactory } from "./ui/types.ts";
25
26
 
26
27
  export type AskUserExecutionContext = Pick<ExtensionContext, "cwd" | "hasUI" | "mode" | "abort"> & {
27
28
  ui: {
@@ -31,6 +32,7 @@ export type AskUserExecutionContext = Pick<ExtensionContext, "cwd" | "hasUI" | "
31
32
  setTitle?(title: string): void;
32
33
  getToolsExpanded?(): boolean;
33
34
  setToolsExpanded?(expanded: boolean): void;
35
+ getEditorComponent?(): EditorFactory | undefined;
34
36
  };
35
37
  };
36
38
 
@@ -141,6 +143,9 @@ export async function executeAskUser(
141
143
  ui: {
142
144
  custom: asFunction(ctx.ui.custom),
143
145
  notify: ctx.ui.notify,
146
+ getEditorComponent: ctx.ui.getEditorComponent
147
+ ? () => ctx.ui.getEditorComponent?.()
148
+ : undefined,
144
149
  },
145
150
  signal,
146
151
  onToggleToolsExpanded:
@@ -2,8 +2,10 @@
2
2
  import {
3
3
  type Component,
4
4
  Editor,
5
+ type EditorComponent,
5
6
  type EditorTheme,
6
7
  type Focusable,
8
+ isFocusable,
7
9
  Key,
8
10
  matchesKey,
9
11
  } from "@earendil-works/pi-tui";
@@ -16,7 +18,8 @@ export class AskUserForm implements Component, Focusable {
16
18
  focused: boolean = false;
17
19
  private mode: FormMode = "choice";
18
20
  private focus: FocusTarget = "choices";
19
- private readonly editor: Editor;
21
+ private readonly editor: EditorComponent;
22
+ private readonly editorHandlesEscape: boolean;
20
23
  private settingEditorText: boolean = false;
21
24
  private choiceFocusIndex = 0;
22
25
  private readonly choiceFocusByQuestionId = new Map<string, number>();
@@ -34,13 +37,17 @@ export class AskUserForm implements Component, Focusable {
34
37
  private readonly onAbort: () => void;
35
38
 
36
39
  constructor(private readonly args: FormArgs) {
37
- this.editor = new Editor(args.tui, makeEditorTheme(args));
38
- this.editor.onChange = () => {
39
- if (this.settingEditorText) return;
40
- this.syncTextAnswerFromEditor();
41
- this.refresh();
42
- };
43
- this.editor.onSubmit = (value) => this.handleEditorSubmit(value);
40
+ const { editor, handlesEscape } = createFormEditor(args, {
41
+ onChange: () => {
42
+ if (this.settingEditorText) return;
43
+ this.syncTextAnswerFromEditor();
44
+ this.refresh();
45
+ },
46
+ onSubmit: (value) => this.handleEditorSubmit(value),
47
+ onEscape: () => this.handleEditorEscape(),
48
+ });
49
+ this.editor = editor;
50
+ this.editorHandlesEscape = handlesEscape;
44
51
  this.syncCurrentQuestion();
45
52
  this.onAbort = () => {
46
53
  this.args.controller.abort();
@@ -51,7 +58,7 @@ export class AskUserForm implements Component, Focusable {
51
58
 
52
59
  render(width: number): string[] {
53
60
  const editorFocused = this.focused && this.focus === "editor";
54
- this.editor.focused = editorFocused;
61
+ if (isFocusable(this.editor)) this.editor.focused = editorFocused;
55
62
 
56
63
  if (
57
64
  this.cachedWidth === width &&
@@ -112,6 +119,12 @@ export class AskUserForm implements Component, Focusable {
112
119
  private handleEscapeKey(data: string): boolean {
113
120
  if (!matchesKey(data, Key.escape)) return false;
114
121
 
122
+ if (this.editorHandlesEscape && (this.mode === "text" || this.isCommentEditorMode())) {
123
+ this.editor.handleInput(data);
124
+ if (!this.closed) this.refresh();
125
+ return true;
126
+ }
127
+
115
128
  if (this.isCommentEditorMode()) {
116
129
  this.returnFromCommentEditor();
117
130
  this.refresh();
@@ -135,6 +148,18 @@ export class AskUserForm implements Component, Focusable {
135
148
  return true;
136
149
  }
137
150
 
151
+ private handleEditorEscape(): void {
152
+ if (this.isCommentEditorMode()) {
153
+ this.returnFromCommentEditor();
154
+ this.refresh();
155
+ return;
156
+ }
157
+ if (this.mode === "text") {
158
+ this.args.controller.cancel();
159
+ this.finish();
160
+ }
161
+ }
162
+
138
163
  private handleNavigationKey(data: string): boolean {
139
164
  if (this.isCommentEditorMode()) return false;
140
165
 
@@ -497,7 +522,10 @@ export class AskUserForm implements Component, Focusable {
497
522
  if (this.mode !== "text") return;
498
523
  const question = this.args.controller.currentQuestion;
499
524
  if (question.type !== "text") return;
500
- this.args.controller.setTextAnswer(question.id, this.editor.getExpandedText());
525
+ this.args.controller.setTextAnswer(
526
+ question.id,
527
+ this.editor.getExpandedText?.() ?? this.editor.getText(),
528
+ );
501
529
  }
502
530
 
503
531
  private restoreChoiceFocus(
@@ -560,6 +588,62 @@ export class AskUserForm implements Component, Focusable {
560
588
  }
561
589
  }
562
590
 
591
+ interface FormEditorCallbacks {
592
+ onChange: (value: string) => void;
593
+ onSubmit: (value: string) => void;
594
+ onEscape: () => void;
595
+ }
596
+
597
+ function createFormEditor(
598
+ args: FormArgs,
599
+ callbacks: FormEditorCallbacks,
600
+ ): { editor: EditorComponent; handlesEscape: boolean } {
601
+ const editorTheme = makeEditorTheme(args);
602
+ const createDefault = () => {
603
+ const editor = new Editor(args.tui, editorTheme);
604
+ configureFormEditor(editor, callbacks, false);
605
+ return { editor, handlesEscape: false };
606
+ };
607
+ if (!args.editorFactory) return createDefault();
608
+
609
+ try {
610
+ const editor: unknown = args.editorFactory(args.tui, editorTheme, args.keybindings);
611
+ if (!isEditorComponent(editor)) {
612
+ throw new Error("factory returned an invalid EditorComponent");
613
+ }
614
+ const handlesEscape = "onEscape" in editor;
615
+ configureFormEditor(editor, callbacks, handlesEscape);
616
+ return { editor, handlesEscape };
617
+ } catch (error) {
618
+ const reason = error instanceof Error ? error.message : String(error);
619
+ args.notify?.(
620
+ `Custom editor unavailable in ask_user; using the default editor: ${reason}`,
621
+ "warning",
622
+ );
623
+ return createDefault();
624
+ }
625
+ }
626
+
627
+ function configureFormEditor(
628
+ editor: EditorComponent,
629
+ callbacks: FormEditorCallbacks,
630
+ handlesEscape: boolean,
631
+ ): void {
632
+ editor.onChange = callbacks.onChange;
633
+ editor.onSubmit = callbacks.onSubmit;
634
+ if (handlesEscape) {
635
+ (editor as EditorComponent & { onEscape: () => void }).onEscape = callbacks.onEscape;
636
+ }
637
+ }
638
+
639
+ function isEditorComponent(value: unknown): value is EditorComponent {
640
+ if (!value || typeof value !== "object") return false;
641
+ const candidate = value as Record<string, unknown>;
642
+ return ["render", "invalidate", "getText", "setText", "handleInput"].every(
643
+ (method) => typeof candidate[method] === "function",
644
+ );
645
+ }
646
+
563
647
  function makeEditorTheme(args: FormArgs): EditorTheme {
564
648
  return {
565
649
  borderColor: (text) => args.theme.fg("accent", text),
@@ -1,5 +1,5 @@
1
1
  import type { Theme } from "@earendil-works/pi-coding-agent";
2
- import { type Editor, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
2
+ import { type EditorComponent, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
3
3
  import type { AskUserController } from "../session/controller.ts";
4
4
  import type { NormalizedChoiceQuestion } from "../types.ts";
5
5
  import {
@@ -19,7 +19,7 @@ export interface RenderFormFrameArgs {
19
19
  controller: AskUserController;
20
20
  mode: FormMode;
21
21
  focus: FocusTarget;
22
- editor: Editor;
22
+ editor: EditorComponent;
23
23
  choiceFocusIndex: number;
24
24
  reviewFocusIndex: number;
25
25
  detailsText?: string;
package/src/ui/form.ts CHANGED
@@ -16,6 +16,8 @@ export async function runFormQuestionnaire(
16
16
  return controller.abort();
17
17
  }
18
18
 
19
+ const editorFactory = opts.ui.getEditorComponent?.();
20
+
19
21
  return opts.ui.custom?.<AskUserOutcome | AskUserInteractionResult>(
20
22
  (tui, theme, kb, done) =>
21
23
  new AskUserForm({
@@ -26,6 +28,8 @@ export async function runFormQuestionnaire(
26
28
  signal: opts.signal,
27
29
  keybindings: kb,
28
30
  onToggleToolsExpanded: opts.onToggleToolsExpanded,
31
+ editorFactory,
32
+ notify: opts.ui.notify,
29
33
  }),
30
34
  );
31
35
  }
package/src/ui/types.ts CHANGED
@@ -1,4 +1,8 @@
1
- import type { KeybindingsManager, Theme } from "@earendil-works/pi-coding-agent";
1
+ import type {
2
+ ExtensionUIContext,
3
+ KeybindingsManager,
4
+ Theme,
5
+ } from "@earendil-works/pi-coding-agent";
2
6
  import type { Component, TUI } from "@earendil-works/pi-tui";
3
7
  import type { AskUserController } from "../session/controller.ts";
4
8
  import type {
@@ -7,8 +11,13 @@ import type {
7
11
  NormalizedQuestionnaire,
8
12
  } from "../types.ts";
9
13
 
14
+ // `EditorFactory` isn't re-exported from the package root; derive it from the
15
+ // interface method that is exported.
16
+ export type EditorFactory = NonNullable<ReturnType<ExtensionUIContext["getEditorComponent"]>>;
17
+
10
18
  export interface AskUserUiContext {
11
19
  notify?(message: string, type?: "info" | "warning" | "error"): void;
20
+ getEditorComponent?(): EditorFactory | undefined;
12
21
  custom?<T>(
13
22
  factory: (
14
23
  tui: TUI,
@@ -39,4 +48,6 @@ export interface FormArgs {
39
48
  signal?: AbortSignal;
40
49
  keybindings: KeybindingsManager;
41
50
  onToggleToolsExpanded?: () => void;
51
+ editorFactory?: EditorFactory;
52
+ notify?: AskUserUiContext["notify"];
42
53
  }