@pi-unipi/ask-user 0.1.9 → 0.1.11

package/README.md

@@ -1,30 +1,24 @@
 # @pi-unipi/ask-user
 
-Structured user input tool for the Pi coding agent — part of the Unipi suite.
+Structured user input for decision gates. When the agent needs you to pick between options — which database, which approach, which files to change — it calls `ask_user` instead of guessing.
 
-## Features
+Three input modes: single-select (pick one), multi-select (toggle several), freeform (type your own). The agent presents the question, you answer, it continues.
 
-### `ask_user` Tool
+## Commands
 
-Ask the user a question with structured options. Supports three modes:
+Ask-user has no user commands. It's an agent tool package — the agent calls it when it needs input.
 
-- **Single-select** — Pick one option from a list
-- **Multi-select** — Toggle multiple options, then submit
-- **Freeform** — Type a custom answer
+## Special Triggers
 
-### Usage
+All workflow skills detect ask-user and use it for decision gates. Instead of the agent deciding on its own, it presents options and waits for your input. This happens naturally during brainstorm, plan, work, and other skills when the agent faces ambiguity.
 
-The agent calls the tool when it needs user input:
+The bundled skill guides the agent to use `ask_user` for high-stakes decisions — architecture choices, database selection, naming decisions, anything with lasting impact.
 
-```typescript
-ask_user({
-  question: "Which database should we use?",
-  options: [
-    { label: "PostgreSQL", description: "Reliable, feature-rich" },
-    { label: "SQLite", description: "Simple, serverless" },
-  ],
-})
-```
+## Agent Tool
+
+| Tool | Description |
+|------|-------------|
+| `ask_user` | Structured user input with options |
 
 ### Parameters
 
@@ -37,12 +31,24 @@ ask_user({
 | `allowFreeform` | boolean? | true | Allow freeform text input |
 | `timeout` | number? | — | Auto-dismiss after N ms |
 
+### Example
+
+```typescript
+ask_user({
+  question: "Which database should we use?",
+  options: [
+    { label: "PostgreSQL", description: "Reliable, feature-rich" },
+    { label: "SQLite", description: "Simple, serverless" },
+  ],
+})
+```
+
 ### Keyboard Controls
 
 | Mode | Keys |
 |------|------|
-| Single-select | ↑↓ navigate, Enter select, Esc cancel |
-| Multi-select | ↑↓ navigate, Space toggle, Enter submit, Esc cancel |
+| Single-select | Up/Down navigate, Enter select, Esc cancel |
+| Multi-select | Up/Down navigate, Space toggle, Enter submit, Esc cancel |
 | Freeform | Type text, Enter submit, Esc back |
 
 ### TUI Display
@@ -57,7 +63,7 @@ ask_user({
    Option C
    Type something...
 
- ↑↓ navigate • Enter select • Esc cancel
+ Up/Down navigate, Enter select, Esc cancel
 ─────────────────────────────
 ```
 
@@ -66,34 +72,19 @@ ask_user({
 ─────────────────────────────
  Which features to enable?
 ─────────────────────────────
- > [✓] Logging
+ > [x] Logging
    [ ] Metrics
-   [✓] Tracing
+   [x] Tracing
    [ ] Type something...
 
- ↑↓ navigate • Space toggle • Enter submit • Esc cancel
+ Up/Down navigate, Space toggle, Enter submit, Esc cancel
 ─────────────────────────────
 ```
 
-## Installation
-
-```bash
-pi install npm:@pi-unipi/ask-user
-```
-
-Or install the full Unipi suite:
-
-```bash
-pi install npm:@pi-unipi/unipi
-```
-
-## Bundled Skill
+## Configurables
 
-The package includes a skill that guides the agent to use `ask_user` for high-stakes decisions. The skill is automatically discovered when the extension loads.
+Ask-user has no configuration. Input mode is determined by the `allowMultiple` and `allowFreeform` parameters the agent passes.
 
-## Dependencies
+## License
 
-- `@pi-unipi/core` — Shared constants and utilities
-- `@mariozechner/pi-coding-agent` — Pi extension API
-- `@mariozechner/pi-tui` — TUI components
-- `@sinclair/typebox` — Schema validation
+MIT

package/ask-ui.ts

@@ -638,7 +638,24 @@ export function createRenderResult() {
           0,
           0,
         );
-      case "new_session":
+      case "new_session": {
+        const launchedWith = (response as any).launchedWith;
+        if (launchedWith === "compact") {
+          return new Text(
+            theme.fg("success", "✓ compacted → ") +
+              theme.fg("accent", response.prefill || ""),
+            0,
+            0,
+          );
+        }
+        if (launchedWith === "direct") {
+          return new Text(
+            theme.fg("success", "✓ running → ") +
+              theme.fg("accent", response.prefill || ""),
+            0,
+            0,
+          );
+        }
         return new Text(
           theme.fg("success", "✓ ") +
             theme.fg("muted", "new session") +
@@ -646,6 +663,7 @@ export function createRenderResult() {
           0,
           0,
         );
+      }
       default:
         return new Text(
           theme.fg("text", JSON.stringify(response)),

package/launcher-ui.ts

@@ -0,0 +1,142 @@
+/**
+ * @pi-unipi/ask-user — Session Launcher TUI
+ *
+ * Secondary overlay shown when user selects a new_session option.
+ * Offers Compact & run, Run directly, or Cancel.
+ */
+
+import { Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import type { SessionLauncherResult } from "./types.js";
+
+/** Launcher option definition */
+interface LauncherOption {
+  label: string;
+  icon: string;
+  action: SessionLauncherResult["action"];
+}
+
+const OPTIONS: LauncherOption[] = [
+  { label: "Compact & run", icon: "🧹", action: "compact" },
+  { label: "Run directly", icon: "▶", action: "direct" },
+  { label: "Cancel", icon: "✕", action: "cancel" },
+];
+
+/**
+ * Render the session launcher UI.
+ *
+ * Simple single-select picker with 3 fixed options.
+ * No editor, no timeout, no multi-select.
+ */
+export function renderLauncherUI(params: {
+  prefill: string;
+}): (
+  tui: any,
+  theme: any,
+  kb: any,
+  done: (result: SessionLauncherResult | null) => void,
+) => {
+  render: (width: number) => string[];
+  invalidate: () => void;
+  handleInput: (data: string) => void;
+} {
+  return (_tui, theme, _kb, done) => {
+    const { prefill } = params;
+
+    // State
+    let optionIndex = 0;
+    let cachedLines: string[] | undefined;
+
+    function refresh() {
+      cachedLines = undefined;
+      _tui.requestRender();
+    }
+
+    function handleInput(data: string) {
+      // Navigation
+      if (matchesKey(data, Key.up)) {
+        optionIndex = Math.max(0, optionIndex - 1);
+        refresh();
+        return;
+      }
+      if (matchesKey(data, Key.down)) {
+        optionIndex = Math.min(OPTIONS.length - 1, optionIndex + 1);
+        refresh();
+        return;
+      }
+
+      // Enter: select
+      if (matchesKey(data, Key.enter)) {
+        const opt = OPTIONS[optionIndex];
+        done({ action: opt.action, prefill });
+        return;
+      }
+
+      // Escape: cancel
+      if (matchesKey(data, Key.escape)) {
+        done(null);
+        return;
+      }
+    }
+
+    function render(width: number): string[] {
+      if (cachedLines) return cachedLines;
+
+      const lines: string[] = [];
+      const innerWidth = Math.max(40, width - 2);
+      const border = (s: string) => theme.fg("accent", s);
+
+      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 addEmpty = () =>
+        lines.push(border("│") + " ".repeat(innerWidth) + border("│"));
+
+      // Top border
+      lines.push(border(`╭${"─".repeat(innerWidth)}╮`));
+
+      // Header: show prefill command (truncated)
+      const headerPrefix = " 🚀 ";
+      const maxPrefillWidth = innerWidth - headerPrefix.length - 1;
+      const truncatedPrefill = truncateToWidth(prefill || "(no command)", maxPrefillWidth);
+      add(theme.fg("accent", headerPrefix) + theme.fg("text", truncatedPrefill));
+      addEmpty();
+
+      // Options
+      for (let i = 0; i < OPTIONS.length; i++) {
+        const opt = OPTIONS[i];
+        const isSelected = i === optionIndex;
+        const prefix = isSelected ? theme.fg("accent", "> ") : "  ";
+        const label = `${opt.icon} ${opt.label}`;
+        const color = isSelected ? "accent" : "text";
+        add(prefix + theme.fg(color, label));
+      }
+
+      // Footer hint
+      addEmpty();
+      add(theme.fg("dim", " ↑↓ navigate • Enter select • Esc cancel"));
+
+      // Bottom border
+      lines.push(border(`╰${"─".repeat(innerWidth)}╯`));
+
+      cachedLines = lines;
+      return lines;
+    }
+
+    return {
+      render,
+      invalidate: () => {
+        cachedLines = undefined;
+      },
+      handleInput,
+    };
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ask-user",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Structured user input tool for Pi coding agent — single-select, multi-select, freeform",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,7 @@
     "types.ts",
     "tools.ts",
     "ask-ui.ts",
+    "launcher-ui.ts",
     "commands.ts",
     "config.ts",
     "settings-tui.ts",

package/skills/ask-user/SKILL.md

@@ -56,7 +56,7 @@ Use the `ask_user` tool to collect structured input from the user.
 | `"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`. |
+| `"new_session"` | Starts a new session. Returns `new_session` response kind with optional `prefill`. Shows a launcher overlay offering **Compact & run** (compacts context first) or **Run directly**. |
 
 ## Examples
 
@@ -150,3 +150,15 @@ ask_user({
 - "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
+
+## Session Launcher
+
+When a user selects a `new_session` option, a secondary launcher overlay appears with three choices:
+
+| Choice | Behavior |
+|--------|----------|
+| 🧹 Compact & run | Compacts current context (via `ctx.compact()`), then returns the prefill command to the LLM |
+| ▶ Run directly | Returns the prefill command to the LLM without compaction |
+| ✕ Cancel | Cancels the session launch |
+
+This two-step flow lets the user manage context window usage before starting a new task.

package/tools.ts

@@ -11,8 +11,9 @@ import {
   UNIPI_EVENTS,
   emitEvent,
 } from "@pi-unipi/core";
-import type { NormalizedOption, AskUserResponse } from "./types.js";
+import type { NormalizedOption, AskUserResponse, SessionLauncherResult } from "./types.js";
 import { renderAskUI, createRenderCall, createRenderResult } from "./ask-ui.js";
+import { renderLauncherUI } from "./launcher-ui.js";
 import { getAskUserSettings } from "./config.js";
 
 /**
@@ -331,6 +332,57 @@ export function registerAskUserTools(pi: ExtensionAPI): void {
           contentText = "No response";
       }
 
+      // Session launcher intercept: when user selects new_session, offer compact/direct/cancel
+      if (response.kind === "new_session") {
+        const prefill = response.prefill || "";
+        const launcherResult = await ctx.ui.custom<SessionLauncherResult | null>(
+          renderLauncherUI({ prefill }),
+        );
+
+        if (!launcherResult || launcherResult.action === "cancel") {
+          return {
+            content: [{ type: "text", text: "User cancelled the session launch" }],
+            details: {
+              question,
+              options: normalizedOptions.map((o) => o.label),
+              response: {
+                kind: "cancelled",
+                comment: "Session launcher cancelled",
+              } as AskUserResponse,
+            },
+          };
+        }
+
+        if (launcherResult.action === "compact") {
+          try {
+            await new Promise<void>((resolve, reject) => {
+              ctx.compact({
+                customInstructions: `Preparing for new task. Summarize previous work concisely, preserving only what's essential for: ${prefill}`,
+                onComplete: () => resolve(),
+                onError: (err) => reject(err),
+              });
+            });
+          } catch (err) {
+            // Compaction failure shouldn't block the session launch — continue anyway
+          }
+        }
+
+        const actionLabel = launcherResult.action === "compact" ? "compacted" : "running";
+        contentText = `User chose to proceed (${actionLabel}): ${prefill}`;
+
+        return {
+          content: [{ type: "text", text: contentText }],
+          details: {
+            question,
+            options: normalizedOptions.map((o) => o.label),
+            response: {
+              ...response,
+              launchedWith: launcherResult.action,
+            },
+          },
+        };
+      }
+
       return {
         content: [{ type: "text", text: contentText }],
         details: {

package/types.ts

@@ -54,6 +54,12 @@ export interface AskUserResponse {
   comment?: string;
 }
 
+/** Result from the session launcher UI */
+export interface SessionLauncherResult {
+  action: "compact" | "direct" | "cancel";
+  prefill: string;
+}
+
 /** Normalized option with resolved value */
 export interface NormalizedOption {
   label: string;