@hheei/pi-ask-user 0.0.0-stage → 0.1.1

package/dist/single-select-list.d.ts

@@ -0,0 +1,23 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, KeybindingsManager } from "@earendil-works/pi-tui";
+import { type QuestionOption } from "./single-select-layout";
+export declare class WrappedSingleSelectList implements Component {
+    private options;
+    private theme;
+    private keybindings;
+    private readonly rows;
+    private cachedWidth;
+    private cachedLines;
+    onCancel?: () => void;
+    onSubmit?: (result: string) => void;
+    onEnterFreeform?: () => void;
+    constructor(options: QuestionOption[], allowFreeform: boolean, theme: Theme, keybindings: KeybindingsManager);
+    setMaxVisibleRows(count: number): void;
+    invalidate(): void;
+    private styleListLine;
+    private buildLines;
+    /** Enter on the selected row: open the custom response, or choose the option. */
+    private confirm;
+    handleInput(data: string): void;
+    render(width: number): string[];
+}

package/dist/single-select-list.js

@@ -0,0 +1,99 @@
+import { fitRow } from "@hheei/pi-ext-core";
+import { OptionRows } from "./option-rows";
+import { digitKey, matchesSelectDown, matchesSelectUp } from "./shortcuts";
+import { renderSingleSelectRows, } from "./single-select-layout";
+export class WrappedSingleSelectList {
+    options;
+    theme;
+    keybindings;
+    rows;
+    cachedWidth;
+    cachedLines;
+    onCancel;
+    onSubmit;
+    onEnterFreeform;
+    constructor(options, allowFreeform, theme, keybindings) {
+        this.options = options;
+        this.theme = theme;
+        this.keybindings = keybindings;
+        this.rows = new OptionRows(allowFreeform, 12);
+    }
+    setMaxVisibleRows(count) {
+        if (this.rows.setMaxVisibleRows(count))
+            this.invalidate();
+    }
+    invalidate() {
+        this.cachedWidth = undefined;
+        this.cachedLines = undefined;
+    }
+    styleListLine(row, width) {
+        const text = row.line;
+        if (row.kind === "indicator")
+            return fitRow(this.theme.fg("dim", text), width, "");
+        if (row.selected)
+            return fitRow(this.theme.fg("accent", this.theme.bold(text)), width, "");
+        if (row.kind === "description")
+            return fitRow(this.theme.fg("muted", text), width, "");
+        return fitRow(this.theme.fg("text", text), width, "");
+    }
+    buildLines(width) {
+        const count = this.rows.count(this.options.length);
+        if (count === 0)
+            return [fitRow(this.theme.fg("warning", "No options"), width, "")];
+        const optionRows = renderSingleSelectRows({
+            options: this.options,
+            selectedIndex: this.rows.selected,
+            width,
+            allowFreeform: this.rows.allowFreeform,
+            maxRows: this.rows.visibleRows,
+        });
+        return optionRows.map((row) => this.styleListLine(row, width));
+    }
+    /** Enter on the selected row: open the custom response, or choose the option. */
+    confirm() {
+        const index = this.rows.selected;
+        if (this.rows.isFreeformRow(index, this.options.length)) {
+            this.onEnterFreeform?.();
+            return;
+        }
+        const result = this.options[index]?.title;
+        if (result)
+            this.onSubmit?.(result);
+        else
+            this.onCancel?.();
+    }
+    handleInput(data) {
+        if (this.keybindings.matches(data, "tui.select.cancel")) {
+            this.onCancel?.();
+            return;
+        }
+        const count = this.rows.count(this.options.length);
+        if (matchesSelectUp(data, this.keybindings) && this.rows.moveSelection(-1, count)) {
+            this.invalidate();
+            return;
+        }
+        if (matchesSelectDown(data, this.keybindings) && this.rows.moveSelection(1, count)) {
+            this.invalidate();
+            return;
+        }
+        const digit = digitKey(data);
+        if (digit !== null && digit <= this.options.length) {
+            this.rows.selected = digit - 1;
+            this.invalidate();
+            return;
+        }
+        if (this.keybindings.matches(data, "tui.select.confirm") && count > 0) {
+            this.confirm();
+        }
+    }
+    render(width) {
+        if (this.cachedLines && this.cachedWidth === width)
+            return this.cachedLines;
+        const count = this.rows.count(this.options.length);
+        this.rows.clampSelection(count);
+        const lines = this.buildLines(width);
+        this.cachedWidth = width;
+        this.cachedLines = lines;
+        return lines;
+    }
+}

package/dist/tool.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export declare function registerAskUserTool(pi: ExtensionAPI): void;

package/dist/tool.js

@@ -0,0 +1,91 @@
+import { Type } from "typebox";
+import { BATCH_MAX_QUESTIONS, BATCH_MIN_QUESTIONS } from "./constants";
+import { executeBatch, executeSingle } from "./execute";
+import { createAskUserRenderers } from "./presentation";
+import { StringEnum } from "./schema";
+const ASK_DESCRIPTION = "Ask the user a question with optional multiple-choice answers, or 2-4 independent questions in one prompt. The turn blocks until the user answers.";
+const ASK_PROMPT_SNIPPET = "Ask the user one focused question, or 2-4 independent ones together, with optional multiple-choice answers";
+const ASK_PROMPT_GUIDELINES = [
+    "ask_user: gather context with tools (read/web/ref) first and put a short summary of findings in context; the user sees only what you send.",
+    "ask_user: use it when intent is ambiguous, when a decision needs explicit user input, or when several valid options exist.",
+    "ask_user: ask one focused question per call; never bundle numbered, multipart, or unrelated questions into one question.",
+    "ask_user: use questions (2-4 entries) only for independent decisions whose prerequisites are settled; anything that depends on an earlier answer belongs in a later call.",
+    "ask_user: with questions, put every question inside questions; a top-level question is only the batch heading and is never asked.",
+    "ask_user: keep option titles short and put the trade-off in description; allowFreeform is on by default, so do not invent an option for every possible answer.",
+];
+const ASK_PARAMETER_DESCRIPTIONS = {
+    question: "The question to ask. With questions, it is only an optional heading for the batch; put every actual question inside questions.",
+    questions: "2-4 independent questions shown together, used instead of question. Set context, options, allowMultiple, and allowFreeform on each entry; the remaining parameters apply to the whole batch.",
+    batchQuestion: "One question in the batch",
+    context: "Relevant context shown before the question (summary of findings)",
+    options: "Options for the user to choose from",
+    allowMultiple: "Allow selecting multiple options (default: false)",
+    allowFreeform: "Add a freeform text option (default: true)",
+    displayMode: "'overlay' shows a centered modal, 'inline' renders in place (default: displayMode in the askUser section of ext_settings.json, otherwise 'overlay')",
+    timeoutMs: "Auto-dismiss after N milliseconds; the result is cancelled",
+};
+// Flat object shape: union item schemas get stripped or rejected by several
+// providers/proxies (Google function calling, Codex-style backends, cmux),
+// leaving the model to guess the shape and produce empty options. Plain
+// strings are still accepted at runtime for older transcripts. See issue #22.
+const optionSchema = Type.Object({
+    title: Type.String({ description: "Short title for this option" }),
+    description: Type.Optional(Type.String({ description: "Longer description explaining this option" })),
+});
+const questionEntrySchema = Type.Object({
+    question: Type.String({ description: ASK_PARAMETER_DESCRIPTIONS.batchQuestion }),
+    context: Type.Optional(Type.String({ description: ASK_PARAMETER_DESCRIPTIONS.context })),
+    options: Type.Optional(Type.Array(optionSchema, { description: ASK_PARAMETER_DESCRIPTIONS.options })),
+    allowMultiple: Type.Optional(Type.Boolean({ description: ASK_PARAMETER_DESCRIPTIONS.allowMultiple })),
+    allowFreeform: Type.Optional(Type.Boolean({ description: ASK_PARAMETER_DESCRIPTIONS.allowFreeform })),
+});
+export function registerAskUserTool(pi) {
+    pi.registerTool({
+        // Asks the user, so only the model may call it; codemode scripts cannot open prompts.
+        exposure: "model-only",
+        name: "ask_user",
+        label: "ask_user",
+        description: ASK_DESCRIPTION,
+        promptSnippet: ASK_PROMPT_SNIPPET,
+        promptGuidelines: ASK_PROMPT_GUIDELINES,
+        // Block other tool calls in the same assistant turn until the user answers,
+        // so the model cannot batch ask_user with bash/edit/write and let those run
+        // (potentially with side effects) before the user sees the prompt.
+        executionMode: "sequential",
+        parameters: Type.Object({
+            question: Type.Optional(Type.String({ description: ASK_PARAMETER_DESCRIPTIONS.question })),
+            questions: Type.Optional(Type.Array(questionEntrySchema, {
+                minItems: BATCH_MIN_QUESTIONS,
+                maxItems: BATCH_MAX_QUESTIONS,
+                description: ASK_PARAMETER_DESCRIPTIONS.questions,
+            })),
+            context: Type.Optional(Type.String({ description: ASK_PARAMETER_DESCRIPTIONS.context })),
+            options: Type.Optional(Type.Array(optionSchema, { description: ASK_PARAMETER_DESCRIPTIONS.options })),
+            allowMultiple: Type.Optional(Type.Boolean({ description: ASK_PARAMETER_DESCRIPTIONS.allowMultiple })),
+            allowFreeform: Type.Optional(Type.Boolean({ description: ASK_PARAMETER_DESCRIPTIONS.allowFreeform })),
+            displayMode: Type.Optional(StringEnum(["overlay", "inline"], {
+                description: ASK_PARAMETER_DESCRIPTIONS.displayMode,
+            })),
+            timeout_ms: Type.Optional(Type.Integer({
+                minimum: 1,
+                description: ASK_PARAMETER_DESCRIPTIONS.timeoutMs,
+            })),
+        }),
+        async execute(_toolCallId, params, signal, onUpdate, ctx) {
+            const ask = params;
+            const questions = ask.questions;
+            if (questions !== undefined && questions.length > 1) {
+                return executeBatch(pi, ask, signal, onUpdate, ctx);
+            }
+            // A one-entry batch is one question: models wrap a single question in questions often
+            // enough that rejecting it would cost the whole turn.
+            const only = questions?.[0];
+            if (only === undefined)
+                return executeSingle(pi, ask, signal, onUpdate, ctx);
+            const single = { ...ask, ...only };
+            delete single.questions;
+            return executeSingle(pi, single, signal, onUpdate, ctx);
+        },
+        ...createAskUserRenderers(pi),
+    });
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@hheei/pi-ask-user",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Interactive ask_user tool for pi-coding-agent: one question or 2-4 in one prompt, multiple choice, multi-select, and freeform answers.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "dist/index.js"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "ask",
+    "ask_user",
+    "interactive"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hheei/pi-mono.git",
+    "directory": "packages/pi-ask-user"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hheei/pi-ext-core": "^0.8.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=1.2.0",
+    "@earendil-works/pi-coding-agent": ">=1.2.0",
+    "@earendil-works/pi-tui": ">=1.2.0",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^1.4.0",
+    "@earendil-works/pi-coding-agent": "^1.4.0",
+    "@earendil-works/pi-tui": "^1.4.0"
+  },
+  "scripts": {
+    "build": "node -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json"
+  }
 }

package/skills/ask-user/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: ask-user
+description: "You MUST use this before high-stakes architectural decisions, irreversible changes, or when requirements are ambiguous. Runs a decision handshake with the ask_user tool: summarize context, present structured options, collect explicit user choice, then proceed."
+metadata:
+  short-description: Decision gate for ambiguity and high-stakes choices
+---
+
+# Ask User Decision Gate
+
+Use this skill to force explicit user alignment before consequential decisions.
+
+This skill is about **decision control**, not general chit-chat.
+
+## Non-negotiable rule
+
+Invoke `ask_user` before proceeding when **any** of the following is true:
+
+1. The next step changes architecture, schema, API contracts, deployment strategy, or security posture.
+2. The work is costly to undo (large refactor, migration, destructive edit, production-facing behavior change).
+3. Requirements, constraints, or success criteria are unclear, conflicting, or missing.
+4. Multiple valid options exist and the trade-off is preference-dependent.
+5. You are about to assume something that can materially change implementation.
+
+Do **not** skip this gate unless the user has already provided a clear, explicit decision for the exact trade-off.
+
+## Agent Protocol Handshake (required)
+
+Follow this handshake in order.
+
+### 1) Detect boundary
+Classify the current step as:
+- `high_stakes`
+- `ambiguous`
+- `both`
+- `clear` (no gate needed)
+
+If classification is not `clear`, continue.
+
+### 2) Gather evidence first
+Before asking, gather context from available tools (`read`, `grep`, `bash`, `web`, etc.).
+Do not ask the user to decide blind.
+
+### 3) Synthesize context
+Prepare a short neutral summary (3-7 bullets or short paragraph) covering:
+- current state
+- key constraints
+- trade-offs
+- recommendation (if any)
+
+### 4) Ask one focused question
+Call `ask_user` with one decision at a time:
+- `question`: concrete decision prompt
+- `context`: synthesized summary
+- `options`: 2-5 clear choices when possible
+- `allowMultiple`: `false` unless independent selections are genuinely needed
+- `allowFreeform`: usually `true`
+- `displayMode` *(optional)*: `"overlay"` (default) or `"inline"`. Use `"inline"` when preceding assistant context (summary, trade-offs, recommendation) is essential to the decision and should remain visible — overlays cover the conversation underneath. The user may set a personal default via `displayMode` in the `askUser` section of `ext_settings.json`; only pass this when you intentionally want to override it for one call.
+- `timeout_ms` *(optional)*: auto-dismiss after N milliseconds; the result comes back cancelled. Omit unless the decision is genuinely time-boxed.
+
+When 2-4 decisions at the same boundary are independent of each other and their prerequisites are settled, you may ask them together with `questions` instead of `question`. Each entry carries its own `question`, `context`, `options`, `allowMultiple`, and `allowFreeform`. A top-level `question` sent with `questions` is only a heading, never asked. Never batch a decision whose options depend on another answer; ask it in a later call once that answer is known.
+
+### 5) Commit the decision
+After response:
+- restate the decision in plain language
+- state what will be done next
+- proceed with implementation
+
+### 6) Re-open only on new ambiguity
+Ask again only if materially new uncertainty appears.
+Avoid repetitive confirmation loops.
+
+## Anti-overasking guardrails (required)
+
+Apply a strict question budget per decision boundary:
+
+- **Max 1** `ask_user` call per decision boundary in normal cases.
+- **Max 2** `ask_user` calls for the same boundary when first response is unclear/cancelled.
+- Never ask the same trade-off again without new evidence.
+
+Escalation ladder:
+
+1. **Attempt 1:** structured options + concise context.
+2. **Attempt 2 (only if needed):** narrower question with agent recommendation and explicit choices:
+   - `Proceed with recommended option`
+   - `Choose another option` (freeform)
+   - `Stop for now`
+
+After attempt 2:
+
+- If boundary is `high_stakes` or `both`: **stop and mark blocked**. Do not keep asking.
+- If boundary is `ambiguous` only and user says “your call” or equivalent: proceed with the most reversible default and state assumptions explicitly.
+
+## `ask_user` payload quality standard
+
+### Question quality
+Use:
+- “Which option should we adopt for X?”
+- “Do you want A (fast) or B (safer) for Y?”
+
+Avoid:
+- broad/open prompts with no decision boundary
+- multiple unrelated decisions in one question
+- questions that should be answered by reading code/docs first
+
+### Option quality
+Options must be:
+- mutually understandable
+- short and outcome-oriented
+- explicit on trade-offs
+
+Good options include a short description when trade-offs are non-obvious.
+
+## Recommended patterns
+
+### Single-select architecture decision
+
+```json
+{
+  "question": "Which caching strategy should we use for the first release?",
+  "context": "Current API has p95 latency issues. Redis is fastest but adds infra complexity; in-memory cache is simpler but not shared across instances.",
+  "options": [
+    { "title": "In-memory cache", "description": "Simpler rollout, weaker horizontal consistency" },
+    { "title": "Redis cache", "description": "Better consistency and scalability, more ops overhead" }
+  ],
+  "allowMultiple": false,
+  "allowFreeform": true
+}
+```
+
+### Multi-select when decisions are independent
+
+```json
+{
+  "question": "Select the first-wave hardening items to implement now.",
+  "context": "We can ship quickly with baseline controls, then add targeted hardening. Budget is limited to 1-2 days.",
+  "options": [
+    { "title": "Rate limiting" },
+    { "title": "Audit logging" },
+    { "title": "Input schema validation" },
+    { "title": "Secrets rotation" }
+  ],
+  "allowMultiple": true,
+  "allowFreeform": true
+}
+```
+
+### Independent decisions at one checkpoint
+
+```json
+{
+  "questions": [
+    {
+      "question": "Which logging backend should the service use?",
+      "context": "Both integrate with the existing middleware; only the hosted option needs a new vendor contract.",
+      "options": [
+        { "title": "Self-hosted Loki", "description": "No new vendor, more ops work" },
+        { "title": "Hosted Datadog", "description": "Fastest setup, recurring cost" }
+      ]
+    },
+    {
+      "question": "Should the first release include the admin dashboard?",
+      "options": [{ "title": "Include it" }, { "title": "Defer it" }],
+      "allowFreeform": false
+    }
+  ]
+}
+```
+
+## Anti-patterns
+
+- Asking `ask_user` without first gathering context
+- Using it for trivial formatting choices
+- Forcing options when freeform is clearly better
+- Asking the same question repeatedly without new information
+- Batching dependent decisions in `questions`, or using a batch to dodge the one-decision-per-question rule
+- Proceeding with high-stakes implementation after unclear/cancelled answer
+
+## If user cancels or answer is unclear
+
+Pause execution and explain what is blocked.
+Use at most one narrower follow-up `ask_user` question (attempt 2).
+After that, do not continue asking in a loop:
+- for high-stakes decisions: remain blocked until explicit decision
+- for ambiguity-only decisions: proceed only if user delegated the choice ("your call")
+
+## Additional reference
+
+For full trigger matrix, UX conventions, and extension interaction details, read:
+- `references/ask-user-skill-extension-spec.md`

package/skills/ask-user/references/ask-user-skill-extension-spec.md

@@ -0,0 +1,106 @@
+# Ask User Skill × Extension Interaction Spec
+
+## Purpose
+
+This document defines a minimal decision-gating protocol for using the `ask-user` skill with the `ask_user` tool.
+
+Goal: require explicit user decisions at high-impact or ambiguous boundaries before implementation continues.
+
+---
+
+## 1) Trigger Matrix (When to Call `ask_user`)
+
+| Scenario | Must Ask? | Why |
+|---|---:|---|
+| Architecture trade-off (e.g., queue vs cron, SQL vs KV) | Yes | Preference-sensitive, high blast radius |
+| Data schema / migration path selection | Yes | Costly to reverse |
+| Security/compliance posture trade-off | Yes | Risk ownership is human |
+| Requirements conflict or ambiguity | Yes | Need explicit intent |
+| Non-trivial scope cut/prioritization | Yes | Product decision, not purely technical |
+| Purely local refactor with identical behavior | Usually no | No policy-level decision |
+| Formatting-only edits | No | Trivial |
+| User already gave explicit choice for exact trade-off | No (unless new ambiguity) | Decision already captured |
+
+---
+
+## 2) Decision Handshake
+
+Use this protocol whenever the trigger matrix says to ask.
+
+1. **Detect boundary**
+   - classify as `high_stakes`, `ambiguous`, `both`, or `clear`
+2. **Gather evidence**
+   - read code/docs/logs first; do not ask blindly
+3. **Summarize context**
+   - prepare concise trade-off context (3–7 bullets or short paragraph)
+4. **Ask one focused question**
+   - call `ask_user` for one decision at a time; 2-4 independent decisions with settled prerequisites may go together in `questions`
+5. **Commit and proceed**
+   - restate chosen option and implement accordingly
+
+### Retry/cancel policy
+
+- Max **2** `ask_user` attempts for the same decision boundary.
+- Attempt 1: normal structured question.
+- Attempt 2: narrower question with recommendation and explicit options.
+- After attempt 2:
+  - `high_stakes` / `both`: stop and report blocked.
+  - `ambiguous` only: proceed only if user delegates (e.g., “your call”), using the most reversible default.
+
+---
+
+## 3) Example Payloads
+
+### Architecture decision
+
+```json
+{
+  "question": "Which implementation path should we use for v1?",
+  "context": "Path A is faster to ship but less extensible. Path B takes longer but supports plugin-style growth. Existing deadline is 2 weeks.",
+  "options": [
+    { "title": "Path A (ship fast)", "description": "Lowest scope, revisit architecture later" },
+    { "title": "Path B (extensible)", "description": "Higher initial effort, cleaner long-term composition" }
+  ],
+  "allowMultiple": false,
+  "allowFreeform": true
+}
+```
+
+### Display mode (optional)
+
+The `ask_user` tool accepts an optional `displayMode` parameter:
+
+- `"overlay"` *(default)*: centered modal; covers the conversation underneath.
+- `"inline"`: rendered in the conversation flow; preceding messages stay visible.
+
+Guidance:
+
+- Omit `displayMode` to respect the user's configured preference (`displayMode` in the `askUser` section of `ext_settings.json`).
+- Pass `"inline"` only when the immediately preceding assistant message (summary, trade-offs, recommendation) is the primary context for the decision and must remain visible.
+- Pass `"overlay"` only to explicitly force the modal style (rare).
+
+### Batches (optional)
+
+`questions` replaces `question` with 2-4 entries, each with its own `question`, `context`, `options`, `allowMultiple`, and `allowFreeform`. The user answers them on separate pages and submits from a review page, where unanswered questions can be submitted as skipped.
+
+Guidance:
+
+- Batch only decisions that are independent and whose prerequisites are settled.
+- Treat each entry as its own decision boundary for the retry/cancel policy.
+- Skipped entries come back as `{ "status": "skipped" }`; handle them like an unclear answer for that decision.
+
+### Requirement-priority decision
+
+```json
+{
+  "question": "Which requirement should be prioritized first?",
+  "context": "Current request mixes performance tuning and UI redesign. Doing both now risks delaying delivery.",
+  "options": [
+    { "title": "Performance first" },
+    { "title": "UI redesign first" },
+    { "title": "Do a minimal pass on both" }
+  ],
+  "allowMultiple": false,
+  "allowFreeform": true
+}
+```