@pi-unipi/ask-user 0.1.3 → 0.1.5

package/ask-ui.ts

@@ -5,7 +5,7 @@
  * Uses ctx.ui.custom() callback pattern following question.ts/questionnaire.ts.
  */
 
-import { Editor, type EditorTheme, Key, matchesKey, Text, truncateToWidth } from "@mariozechner/pi-tui";
+import { Editor, type EditorTheme, Key, matchesKey, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
 import type { NormalizedOption, AskUserResponse } from "./types.js";
 
 /** Result returned by the ask UI */
@@ -58,9 +58,11 @@ export function renderAskUI(params: {
     // State
     let optionIndex = 0;
     let editMode = false;
+    let editTarget: "freeform" | number = "freeform"; // which option is being edited
     let cachedLines: string[] | undefined;
     const selected = new Set<string>();
-    let customText: string | null = null; // Store custom text
+    let customText: string | null = null; // Store custom text (global freeform)
+    const optionCustomTexts = new Map<string, string>(); // Per-option custom text for allowCustom
     let timeoutId: ReturnType<typeof setTimeout> | undefined;
     let remainingMs = timeout;
 
@@ -77,21 +79,72 @@ export function renderAskUI(params: {
     };
     const editor = new Editor(tui, editorTheme);
 
+    function getOptionCustomText(optIndex: number): string | null {
+      const opt = displayOptions[optIndex];
+      return optionCustomTexts.get(opt.value) ?? null;
+    }
+
+    function setOptionCustomText(optIndex: number, text: string | null) {
+      const opt = displayOptions[optIndex];
+      if (text) {
+        optionCustomTexts.set(opt.value, text);
+      } else {
+        optionCustomTexts.delete(opt.value);
+      }
+    }
+
+    /** Get effective action for an option (allowCustom maps to input) */
+    function getAction(opt: NormalizedOption & { isFreeform?: boolean }): string {
+      if (opt.isFreeform) return "freeform";
+      if (opt.action && opt.action !== "select") return opt.action;
+      if (opt.allowCustom) return "input";
+      return "select";
+    }
+
     editor.onSubmit = (value: string) => {
       const trimmed = value.trim();
-      if (trimmed) {
-        customText = trimmed;
-        editMode = false;
-        editor.setText("");
-        refresh();
+      if (editTarget === "freeform") {
+        // Global freeform input
+        if (trimmed) {
+          customText = trimmed;
+          editMode = false;
+          editor.setText("");
+          refresh();
+        } else {
+          // If empty and no previous custom text, uncheck freeform option
+          if (!customText) {
+            selected.delete("__freeform__");
+          }
+          editMode = false;
+          editor.setText("");
+          refresh();
+        }
       } else {
-        // If empty and no previous custom text, uncheck freeform option
-        if (!customText) {
-          selected.delete("__freeform__");
+        // Per-option custom input (allowCustom)
+        if (trimmed) {
+          setOptionCustomText(editTarget, trimmed);
+          editMode = false;
+          editor.setText("");
+          // Auto-submit in single-select mode
+          if (!allowMultiple) {
+            cleanup();
+            const opt = displayOptions[editTarget];
+            done({
+              response: {
+                kind: "combined",
+                selections: [opt.value],
+                text: trimmed,
+              },
+            });
+            return;
+          }
+          refresh();
+        } else {
+          // Empty: cancel edit mode, keep option selected but without custom text
+          editMode = false;
+          editor.setText("");
+          refresh();
         }
-        editMode = false;
-        editor.setText("");
-        refresh();
       }
     };
 
@@ -137,10 +190,13 @@ export function renderAskUI(params: {
       if (editMode) {
         if (matchesKey(data, Key.escape)) {
           // Cancel text input
-          if (!customText) {
-            // No custom text yet: uncheck freeform option
-            selected.delete("__freeform__");
+          if (editTarget === "freeform") {
+            // Global freeform: uncheck if no previous text
+            if (!customText) {
+              selected.delete("__freeform__");
+            }
           }
+          // For per-option: just cancel edit, keep option selected
           editMode = false;
           editor.setText("");
           refresh();
@@ -167,17 +223,41 @@ export function renderAskUI(params: {
       if (allowMultiple && matchesKey(data, Key.space)) {
         const opt = displayOptions[optionIndex];
         const val = opt.value;
-        if (opt.isFreeform) {
+        const action = getAction(opt);
+
+        if (action === "freeform") {
           // Freeform option: toggle and enter edit mode if checking
           if (selected.has(val)) {
-            // Unchecking: clear custom text
             selected.delete(val);
             customText = null;
           } else {
-            // Checking: enter edit mode to get custom text
             selected.add(val);
             if (!customText) {
               editMode = true;
+              editTarget = "freeform";
+              editor.setText("");
+            }
+          }
+        } else if (action === "end_turn") {
+          // End turn: immediate
+          cleanup();
+          done({ response: { kind: "end_turn", selections: [val] } });
+          return;
+        } else if (action === "new_session") {
+          // New session: immediate
+          cleanup();
+          done({ response: { kind: "new_session", selections: [val], prefill: opt.prefill } });
+          return;
+        } else if (action === "input") {
+          // Input action: toggle and enter edit mode if checking
+          if (selected.has(val)) {
+            selected.delete(val);
+            optionCustomTexts.delete(val);
+          } else {
+            selected.add(val);
+            if (!getOptionCustomText(optionIndex)) {
+              editMode = true;
+              editTarget = optionIndex;
               editor.setText("");
             }
           }
@@ -196,74 +276,82 @@ export function renderAskUI(params: {
       // Enter: select or submit
       if (matchesKey(data, Key.enter)) {
         const opt = displayOptions[optionIndex];
+        const action = getAction(opt);
 
-        if (opt.isFreeform) {
+        if (action === "freeform") {
           // Freeform option: if already checked with text, submit; otherwise enter edit mode
           if (selected.has(opt.value) && customText) {
-            // Already checked with text: submit the form
             cleanup();
             const regularSelections = Array.from(selected).filter(v => v !== "__freeform__");
             if (regularSelections.length > 0) {
-              done({
-                response: {
-                  kind: "combined",
-                  selections: regularSelections,
-                  text: customText,
-                },
-              });
+              done({ response: { kind: "combined", selections: regularSelections, text: customText } });
             } else {
-              done({
-                response: {
-                  kind: "freeform",
-                  text: customText,
-                },
-              });
+              done({ response: { kind: "freeform", text: customText } });
             }
           } else {
-            // Not checked or no text: check it and enter edit mode
             selected.add(opt.value);
             editMode = true;
+            editTarget = "freeform";
             editor.setText("");
           }
           refresh();
           return;
         }
 
+        if (action === "end_turn") {
+          cleanup();
+          done({ response: { kind: "end_turn", selections: [opt.value] } });
+          return;
+        }
+
+        if (action === "new_session") {
+          cleanup();
+          done({ response: { kind: "new_session", selections: [opt.value], prefill: opt.prefill } });
+          return;
+        }
+
         if (allowMultiple) {
           // In multi-select, Enter submits current selection
           if (selected.size > 0) {
             cleanup();
             if (customText && selected.has("__freeform__")) {
-              // Combined response with custom text
               const regularSelections = Array.from(selected).filter(v => v !== "__freeform__");
-              done({
-                response: {
-                  kind: "combined",
-                  selections: regularSelections,
-                  text: customText,
-                },
-              });
+              done({ response: { kind: "combined", selections: regularSelections, text: customText } });
             } else {
-              // Regular selection
-              done({
-                response: {
-                  kind: "selection",
-                  selections: Array.from(selected),
-                },
-              });
+              const selections = Array.from(selected);
+              const combinedTexts: string[] = [];
+              for (const sel of selections) {
+                const txt = optionCustomTexts.get(sel);
+                if (txt) combinedTexts.push(`${sel}: ${txt}`);
+              }
+              if (combinedTexts.length > 0) {
+                done({ response: { kind: "combined", selections, text: combinedTexts.join("\n") } });
+              } else {
+                done({ response: { kind: "selection", selections } });
+              }
             }
           }
           return;
         }
 
-        // Single-select: return immediately
+        // Single-select: check if option has input action
+        if (action === "input") {
+          const existing = getOptionCustomText(optionIndex);
+          if (existing) {
+            cleanup();
+            done({ response: { kind: "combined", selections: [opt.value], text: existing } });
+          } else {
+            editMode = true;
+            editTarget = optionIndex;
+            editor.setText("");
+            refresh();
+          }
+          return;
+        }
+
+        // Single-select without special action: return immediately
         cleanup();
-        done({
-          response: {
-            kind: "selection",
-            selections: [opt.value],
-          },
-        });
+        done({ response: { kind: "selection", selections: [opt.value] } });
         return;
       }
 
@@ -278,39 +366,78 @@ export function renderAskUI(params: {
       if (cachedLines) return cachedLines;
 
       const lines: string[] = [];
-      const add = (s: string) => lines.push(truncateToWidth(s, width));
+      const innerWidth = Math.max(40, width - 2);
+      const border = (s: string) => theme.fg("accent", s);
 
-      add(theme.fg("accent", "─".repeat(width)));
+      function padVisible(content: string, targetWidth: number): string {
+        const vw = visibleWidth(content);
+        const pad = Math.max(0, targetWidth - vw);
+        return content + " ".repeat(pad);
+      }
+
+      const add = (s: string) => lines.push(border("│") + padVisible(truncateToWidth(s, innerWidth), innerWidth) + border("│"));
+      const addWrapped = (s: string) => {
+        for (const line of wrapTextWithAnsi(s, innerWidth)) {
+          lines.push(border("│") + padVisible(truncateToWidth(line, innerWidth), innerWidth) + border("│"));
+        }
+      };
+      const addEmpty = () => lines.push(border("│") + " ".repeat(innerWidth) + border("│"));
+
+      // Top border
+      lines.push(border(`╭${"─".repeat(innerWidth)}╮`));
 
       // Context
       if (context) {
-        add(theme.fg("muted", ` ${context}`));
-        lines.push("");
+        addWrapped(theme.fg("muted", ` ${context}`));
+        addEmpty();
       }
 
       // Question
-      add(theme.fg("text", ` ${question}`));
-      lines.push("");
+      addWrapped(theme.fg("text", ` ${question}`));
+      addEmpty();
 
       // Options (editor is now inline with freeform option)
-      renderOptions(lines, add, theme, width);
+      renderOptions(lines, add, theme, innerWidth);
 
       // Timeout countdown
       if (timeout && remainingMs !== undefined && remainingMs > 0) {
-        lines.push("");
+        addEmpty();
         const secs = Math.ceil(remainingMs / 1000);
         add(theme.fg("dim", ` ⏱ ${secs}s remaining`));
       }
 
-      lines.push("");
+      addEmpty();
       if (editMode) {
         add(theme.fg("dim", " Enter to confirm text • Esc to cancel text input"));
       } else if (allowMultiple) {
-        add(theme.fg("dim", " ↑↓ navigate • Space toggle • Enter submit • Esc cancel"));
+        const currentOpt = displayOptions[optionIndex];
+        const action = currentOpt ? getAction(currentOpt) : "select";
+        const base = " ↑↓ navigate • Space toggle • Enter submit • Esc cancel";
+        let hint = "";
+        if (action === "input" && !optionCustomTexts.get(currentOpt.value)) {
+          hint = " • Space to add note";
+        } else if (action === "end_turn") {
+          hint = " • Space to end turn";
+        } else if (action === "new_session") {
+          hint = " • Space to start new session";
+        }
+        add(theme.fg("dim", base + hint));
       } else {
-        add(theme.fg("dim", " ↑↓ navigate • Enter select • Esc cancel"));
+        const currentOpt = displayOptions[optionIndex];
+        const action = currentOpt ? getAction(currentOpt) : "select";
+        if (action === "input" && !optionCustomTexts.get(currentOpt.value)) {
+          add(theme.fg("dim", " ↑↓ navigate • Enter to add note • Esc cancel"));
+        } else if (action === "end_turn") {
+          add(theme.fg("dim", " ↑↓ navigate • Enter to end turn • Esc cancel"));
+        } else if (action === "new_session") {
+          add(theme.fg("dim", " ↑↓ navigate • Enter to start new session • Esc cancel"));
+        } else {
+          add(theme.fg("dim", " ↑↓ navigate • Enter select • Esc cancel"));
+        }
       }
-      add(theme.fg("accent", "─".repeat(width)));
+
+      // Bottom border
+      lines.push(border(`╰${"─".repeat(innerWidth)}╯`));
 
       cachedLines = lines;
       return lines;
@@ -347,7 +474,7 @@ export function renderAskUI(params: {
           );
           
           // Show edit indicator if in edit mode for this option
-          if (editMode && isSelected) {
+          if (editMode && editTarget === "freeform" && isSelected) {
             add(`   ${theme.fg("muted", "Type your response:")}`);
             for (const line of editor.render(width - 4)) {
               add(`   ${line}`);
@@ -358,20 +485,59 @@ export function renderAskUI(params: {
           const checked = selected.has(opt.value);
           const box = checked ? "✓" : " ";
           const color = checked ? "success" : isSelected ? "accent" : "text";
+          
+          let label = opt.label;
+          const optCustom = optionCustomTexts.get(opt.value);
+          if (optCustom) {
+            label = `${opt.label}: "${optCustom}"`;
+          }
+          
           add(
             prefix +
               theme.fg(color, `[${box}]`) +
               " " +
-              theme.fg(isSelected ? "accent" : "text", opt.label),
+              theme.fg(isSelected ? "accent" : "text", label),
           );
+          
+          // Show edit indicator if in edit mode for this option
+          if (editMode && editTarget === i && isSelected) {
+            add(`   ${theme.fg("muted", "Type your response:")}`);
+            for (const line of editor.render(width - 4)) {
+              add(`   ${line}`);
+            }
+          }
         } else {
-          // Single-select: simple option
+          // Single-select: option
+          let label = opt.label;
+          const optCustom = optionCustomTexts.get(opt.value);
+          if (optCustom) {
+            label = `${opt.label}: "${optCustom}"`;
+          }
+          
+          // Show action indicator
+          const action = getAction(opt);
+          if (action === "input" && !optCustom) {
+            label += theme.fg("dim", " (add note)");
+          } else if (action === "end_turn") {
+            label += theme.fg("dim", " ↵");
+          } else if (action === "new_session") {
+            label += theme.fg("dim", " ↗");
+          }
+          
           add(
             prefix +
               (isSelected
-                ? theme.fg("accent", opt.label)
-                : theme.fg("text", opt.label)),
+                ? theme.fg("accent", label)
+                : theme.fg("text", label)),
           );
+          
+          // Show edit indicator if in edit mode for this option
+          if (editMode && editTarget === i && isSelected) {
+            add(`   ${theme.fg("muted", "Type your response:")}`);
+            for (const line of editor.render(width - 4)) {
+              add(`   ${line}`);
+            }
+          }
         }
 
         // Description
@@ -466,6 +632,20 @@ export function createRenderResult() {
           0,
         );
       }
+      case "end_turn":
+        return new Text(
+          theme.fg("success", "✓ ") + theme.fg("muted", "end turn"),
+          0,
+          0,
+        );
+      case "new_session":
+        return new Text(
+          theme.fg("success", "✓ ") +
+            theme.fg("muted", "new session") +
+            (response.prefill ? theme.fg("accent", `: ${response.prefill}`) : ""),
+          0,
+          0,
+        );
       default:
         return new Text(
           theme.fg("text", JSON.stringify(response)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ask-user",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Structured user input tool for Pi coding agent — single-select, multi-select, freeform",
   "type": "module",
   "license": "MIT",

package/settings-tui.ts

@@ -6,7 +6,7 @@
  */
 
 import type { Component } from "@mariozechner/pi-tui";
-import { truncateToWidth } from "@mariozechner/pi-tui";
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import { getAskUserSettings, saveAskUserSettings, type AskUserSettings } from "./config.js";
 
 /** ANSI escape codes */
@@ -135,12 +135,24 @@ export class AskUserSettingsOverlay implements Component {
    */
   render(width: number): string[] {
     const lines: string[] = [];
-    const add = (s: string) => lines.push(truncateToWidth(s, width));
+    const innerWidth = Math.max(40, width - 2);
+
+    function padVisible(content: string, targetWidth: number): string {
+      const vw = visibleWidth(content);
+      const pad = Math.max(0, targetWidth - vw);
+      return content + " ".repeat(pad);
+    }
+
+    const add = (s: string) => lines.push(`${ansi.cyan}│${ansi.reset}` + padVisible(truncateToWidth(s, innerWidth), innerWidth) + `${ansi.cyan}│${ansi.reset}`);
+    const addEmpty = () => lines.push(`${ansi.cyan}│${ansi.reset}` + " ".repeat(innerWidth) + `${ansi.cyan}│${ansi.reset}`);
+
+    // Top border
+    lines.push(`${ansi.cyan}╭${"─".repeat(innerWidth)}╮${ansi.reset}`);
 
     // Header
     add(`${ansi.bold}${ansi.cyan}Ask User Settings${ansi.reset}`);
     add(`${ansi.dim}Configure how the agent can ask you questions${ansi.reset}`);
-    add("");
+    addEmpty();
 
     // Settings list
     for (let i = 0; i < SETTINGS.length; i++) {
@@ -156,9 +168,12 @@ export class AskUserSettingsOverlay implements Component {
     }
 
     // Footer
-    add("");
+    addEmpty();
     add(`${ansi.dim}↑↓ navigate • Space toggle • Enter save • Esc cancel${ansi.reset}`);
 
+    // Bottom border
+    lines.push(`${ansi.cyan}╰${"─".repeat(innerWidth)}╯${ansi.reset}`);
+
     return lines;
   }
 }

package/skills/ask-user/SKILL.md

@@ -38,6 +38,26 @@ Use the `ask_user` tool to collect structured input from the user.
 | `allowFreeform` | boolean? | true | Add "Custom response" checkable option |
 | `timeout` | number? | — | Auto-dismiss after N ms |
 
+### Option Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `label` | string | required | Display label |
+| `description` | string? | — | Description shown below label |
+| `value` | string? | label | Value returned when selected |
+| `allowCustom` | boolean? | false | Allow user to add custom text for this option (shorthand for `action: "input"`) |
+| `action` | string? | "select" | Special action: `"select"`, `"input"`, `"end_turn"`, `"new_session"` |
+| `prefill` | string? | — | Prefill message for `"new_session"` action |
+
+### Action Types
+
+| Action | Behavior |
+|--------|----------|
+| `"select"` | Normal selection (default). Returns immediately. |
+| `"input"` | Enters text input mode. Returns `combined` response with selection + text. |
+| `"end_turn"` | Signals end of agent turn. Returns `end_turn` response kind. |
+| `"new_session"` | Starts a new session. Returns `new_session` response kind with optional `prefill`. |
+
 ## Examples
 
 Single choice:
@@ -98,3 +118,35 @@ ask_user({
 })
 ```
 User can check "Auth", "Cache", and "Custom response" to type additional features.
+
+With per-option custom text:
+```
+ask_user({
+  question: "Does this look right?",
+  options: [
+    { label: "Yes", value: "yes" },
+    { label: "Partially", value: "partial", allowCustom: true },
+    { label: "No", value: "no", allowCustom: true }
+  ],
+  allowFreeform: false
+})
+```
+Selecting "Partially" or "No" enters text input so the user can explain what needs to change.
+
+With end_turn and new_session actions:
+```
+ask_user({
+  question: "How would you like to proceed?",
+  options: [
+    { label: "Looks good, proceed", value: "proceed" },
+    { label: "I want changes", value: "changes", action: "input" },
+    { label: "Done for now", value: "done", action: "end_turn" },
+    { label: "Start fresh", value: "new", action: "new_session", prefill: "Let's redesign the..." }
+  ],
+  allowFreeform: false
+})
+```
+- "Looks good" returns immediately with selection
+- "I want changes" enters text input mode for the user to explain
+- "Done for now" signals the agent to end its turn
+- "Start fresh" starts a new session with the prefill message

package/tools.ts

@@ -29,6 +29,9 @@ export function registerAskUserTools(pi: ExtensionAPI): void {
       "Provide clear options with labels and optional descriptions.",
       "Use allowMultiple for multi-select scenarios (e.g., choosing features to enable).",
       "Use allowFreeform: false to restrict to predefined options only.",
+      "Use action: 'input' on an option to let the user add custom text before submitting.",
+      "Use action: 'end_turn' on an option to let the user signal end of turn.",
+      "Use action: 'new_session' with prefill to let the user start a new session.",
     ],
     parameters: Type.Object({
       question: Type.String({
@@ -51,6 +54,33 @@ export function registerAskUserTools(pi: ExtensionAPI): void {
                 description: "Value returned when selected (defaults to label)",
               }),
             ),
+            allowCustom: Type.Optional(
+              Type.Boolean({
+                description:
+                  "When true, selecting this option enters text input mode " +
+                  "so the user can add a custom comment before submitting.",
+              }),
+            ),
+            action: Type.Optional(
+              Type.Union(
+                [
+                  Type.Literal("select"),
+                  Type.Literal("input"),
+                  Type.Literal("end_turn"),
+                  Type.Literal("new_session"),
+                ],
+                {
+                  description:
+                    "Special action: 'select' (default), 'input' (text input), " +
+                    "'end_turn' (signal end of turn), 'new_session' (start new session with prefill).",
+                },
+              ),
+            ),
+            prefill: Type.Optional(
+              Type.String({
+                description: "Prefill message for new_session action.",
+              }),
+            ),
           }),
           {
             description:
@@ -86,7 +116,7 @@ export function registerAskUserTools(pi: ExtensionAPI): void {
       } = params as {
         question: string;
         context?: string;
-        options?: { label: string; description?: string; value?: string }[];
+        options?: { label: string; description?: string; value?: string; allowCustom?: boolean; action?: string; prefill?: string }[];
         allowMultiple?: boolean;
         allowFreeform?: boolean;
         timeout?: number;
@@ -211,6 +241,9 @@ export function registerAskUserTools(pi: ExtensionAPI): void {
         label: opt.label,
         description: opt.description,
         value: opt.value ?? opt.label,
+        allowCustom: opt.allowCustom ?? false,
+        action: (opt.action as NormalizedOption["action"]) ?? "select",
+        prefill: opt.prefill,
       }));
 
       // Render interactive UI
@@ -268,6 +301,14 @@ export function registerAskUserTools(pi: ExtensionAPI): void {
           contentText = `User selected: ${selText} and wrote: ${response.text}`;
           break;
         }
+        case "end_turn":
+          contentText = "User chose to end the turn.";
+          break;
+        case "new_session":
+          contentText = response.prefill
+            ? `User chose to start a new session: ${response.prefill}`
+            : "User chose to start a new session.";
+          break;
         case "timed_out":
           contentText = "User did not respond (timed out)";
           break;

package/types.ts

@@ -10,6 +10,18 @@ export interface AskUserOption {
   description?: string;
   /** Value returned when selected (defaults to label) */
   value?: string;
+  /** When true, selecting this option allows the user to add custom text before submitting */
+  allowCustom?: boolean;
+  /**
+   * Special action for this option:
+   * - "select": normal selection (default)
+   * - "input": enter text input mode, return combined response
+   * - "end_turn": signal end of agent turn
+   * - "new_session": start a new session with optional prefill message
+   */
+  action?: "select" | "input" | "end_turn" | "new_session";
+  /** Prefill message for new_session action */
+  prefill?: string;
 }
 
 /** Parameters for ask_user tool */
@@ -31,11 +43,13 @@ export interface AskUserParams {
 /** Response from ask_user tool */
 export interface AskUserResponse {
   /** Response kind */
-  kind: "selection" | "freeform" | "combined" | "cancelled" | "timed_out";
+  kind: "selection" | "freeform" | "combined" | "cancelled" | "timed_out" | "end_turn" | "new_session";
   /** Selected option values (for selection kind) */
   selections?: string[];
   /** Freeform text (for freeform kind) */
   text?: string;
+  /** Prefill message (for new_session kind) */
+  prefill?: string;
   /** Optional user comment */
   comment?: string;
 }
@@ -45,4 +59,10 @@ export interface NormalizedOption {
   label: string;
   description?: string;
   value: string;
+  /** When true, selecting this option allows the user to add custom text before submitting */
+  allowCustom?: boolean;
+  /** Special action for this option */
+  action?: "select" | "input" | "end_turn" | "new_session";
+  /** Prefill message for new_session action */
+  prefill?: string;
 }