@yandy0725/pi-ask-user 0.1.0

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@yandy0725/pi-ask-user",
+	"publishConfig": {
+		"access": "public"
+	},
+	"version": "0.1.0",
+	"description": "Interactive ask_user tool for pi-coding-agent with searchable split-pane selection UI, multi-select, and freeform input",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/yandy/pi-packages",
+		"directory": "pi-ask-user"
+	},
+	"type": "module",
+	"keywords": [
+		"pi-package"
+	],
+	"files": [
+		"index.ts",
+		"src/",
+		"skills/"
+	],
+	"scripts": {
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome lint .",
+		"format": "biome format --write .",
+		"check": "biome check ."
+	},
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		],
+		"skills": [
+			"./skills"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": ">=0.80.2",
+		"@earendil-works/pi-tui": ">=0.80.2",
+		"@sinclair/typebox": "*"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.0",
+		"@types/node": "^22.0.0",
+		"typescript": "~5.7.0",
+		"vitest": "^3.0.0"
+	}
+}

package/skills/ask-user/SKILL.md

@@ -0,0 +1,162 @@
+---
+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`, `bash`, `exa`, `ref`, 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 the `PI_ASK_USER_DISPLAY_MODE` environment variable; only pass this when you intentionally want to override it for one call.
+### 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": [
+    "Rate limiting",
+    "Audit logging",
+    "Input schema validation",
+    "Secrets rotation"
+  ],
+  "allowMultiple": true,
+  "allowFreeform": true
+}
+```
+
+## 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
+- 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,96 @@
+# 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
+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 (`PI_ASK_USER_DISPLAY_MODE` environment variable).
+- 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).
+
+### 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": [
+    "Performance first",
+    "UI redesign first",
+    "Do a minimal pass on both"
+  ],
+  "allowMultiple": false,
+  "allowFreeform": true
+}
+```

package/src/single-select-layout.ts

@@ -0,0 +1,208 @@
+export interface QuestionOption {
+	title: string;
+	description?: string;
+}
+
+export interface AnnotatedRow {
+	line: string;
+	selected: boolean;
+}
+
+export interface RenderSingleSelectRowsParams {
+	options: QuestionOption[];
+	selectedIndex: number;
+	width: number;
+	allowFreeform: boolean;
+	allowComment?: boolean;
+	commentEnabled?: boolean;
+	maxRows?: number;
+	hideDescriptions?: boolean;
+}
+
+function wrapText(text: string, width: number): string[] {
+	const normalized = text.replace(/\s+/g, " ").trim();
+	if (!normalized) return [""];
+	if (width <= 1) return normalized.split("");
+
+	const words = normalized.split(" ");
+	const lines: string[] = [];
+	let current = "";
+
+	for (const word of words) {
+		if (!current) {
+			if (word.length <= width) {
+				current = word;
+			} else {
+				for (let i = 0; i < word.length; i += width) {
+					lines.push(word.slice(i, i + width));
+				}
+			}
+			continue;
+		}
+
+		const candidate = `${current} ${word}`;
+		if (candidate.length <= width) {
+			current = candidate;
+			continue;
+		}
+
+		lines.push(current);
+		if (word.length <= width) {
+			current = word;
+		} else {
+			current = "";
+			for (let i = 0; i < word.length; i += width) {
+				const chunk = word.slice(i, i + width);
+				if (chunk.length === width || i + width < word.length) lines.push(chunk);
+				else current = chunk;
+			}
+		}
+	}
+
+	if (current) lines.push(current);
+	return lines;
+}
+
+function padLine(prefix: string, content: string): string {
+	return `${prefix}${content}`.trimEnd();
+}
+
+interface ItemBlock {
+	itemIndex: number;
+	lines: string[];
+}
+
+type ListItem =
+	| { type: "option"; option: QuestionOption }
+	| { type: "comment-toggle"; option: QuestionOption }
+	| { type: "freeform"; option: QuestionOption };
+
+function buildItemBlocks(
+	options: QuestionOption[],
+	width: number,
+	allowFreeform: boolean,
+	allowComment: boolean,
+	commentEnabled: boolean,
+	selectedIndex: number,
+	hideDescriptions = false,
+): ItemBlock[] {
+	const normalizedWidth = Math.max(12, width);
+	const freeformLabel = "Type something. — Enter a custom response";
+	const commentToggleLabel = `${commentEnabled ? "[✓]" : "[ ]"} Add extra context after selection`;
+	const allItems: ListItem[] = options.map((option) => ({ type: "option", option }));
+	if (allowComment) {
+		allItems.push({ type: "comment-toggle", option: { title: commentToggleLabel } });
+	}
+	if (allowFreeform) {
+		allItems.push({ type: "freeform", option: { title: freeformLabel } });
+	}
+
+	return allItems.map((item, itemIndex) => {
+		const pointer = itemIndex === selectedIndex ? "→" : " ";
+		const lines: string[] = [];
+
+		if (item.type === "comment-toggle" || item.type === "freeform") {
+			const prefix = `${pointer}   `;
+			const wrapped = wrapText(item.option.title, Math.max(8, normalizedWidth - prefix.length));
+			wrapped.forEach((line, lineIndex) => {
+				lines.push(padLine(lineIndex === 0 ? prefix : " ".repeat(prefix.length), line));
+			});
+			return { itemIndex, lines };
+		}
+
+		const numberPrefix = `${pointer} ${itemIndex + 1}. `;
+		const continuationPrefix = " ".repeat(numberPrefix.length);
+		const titleLines = wrapText(item.option.title, Math.max(8, normalizedWidth - numberPrefix.length));
+		titleLines.forEach((line, lineIndex) => {
+			lines.push(padLine(lineIndex === 0 ? numberPrefix : continuationPrefix, line));
+		});
+
+		if (item.option.description && !hideDescriptions) {
+			const descriptionPrefix = "      ";
+			const descriptionLines = wrapText(item.option.description, Math.max(8, normalizedWidth - descriptionPrefix.length));
+			descriptionLines.forEach((line) => {
+				lines.push(padLine(descriptionPrefix, line));
+			});
+		}
+
+		return { itemIndex, lines };
+	});
+}
+
+function flatten(blocks: ItemBlock[], selectedIndex: number): AnnotatedRow[] {
+	return blocks.flatMap((block) =>
+		block.lines.map((line) => ({
+			line,
+			selected: block.itemIndex === selectedIndex,
+		})),
+	);
+}
+
+export function renderSingleSelectRows({
+	options,
+	selectedIndex,
+	width,
+	allowFreeform,
+	allowComment = false,
+	commentEnabled = false,
+	maxRows,
+	hideDescriptions,
+}: RenderSingleSelectRowsParams): AnnotatedRow[] {
+	const itemCount = options.length + (allowComment ? 1 : 0) + (allowFreeform ? 1 : 0);
+	const blocks = buildItemBlocks(
+		options,
+		width,
+		allowFreeform,
+		allowComment,
+		commentEnabled,
+		selectedIndex,
+		hideDescriptions,
+	);
+	const allRows = flatten(blocks, selectedIndex);
+
+	if (!Number.isFinite(maxRows) || !maxRows || maxRows <= 0 || allRows.length <= maxRows) {
+		return allRows;
+	}
+
+	const safeMaxRows = Math.max(1, Math.floor(maxRows));
+	const selectedBlock = blocks[selectedIndex] ?? blocks[0];
+	if (!selectedBlock) return [];
+
+	const indicator = `  (${selectedIndex + 1}/${itemCount})`;
+	const availableRows = safeMaxRows > 1 ? safeMaxRows - 1 : 1;
+
+	if (selectedBlock.lines.length >= availableRows) {
+		const visible = selectedBlock.lines.slice(0, availableRows).map((line) => ({
+			line,
+			selected: true,
+		}));
+		if (safeMaxRows > 1) visible.push({ line: indicator, selected: false });
+		return visible.slice(0, safeMaxRows);
+	}
+
+	let start = selectedIndex;
+	let end = selectedIndex + 1;
+	let usedRows = selectedBlock.lines.length;
+
+	while (true) {
+		const nextCanFit = end < blocks.length && usedRows + blocks[end]?.lines.length <= availableRows;
+		if (nextCanFit) {
+			usedRows += blocks[end]?.lines.length;
+			end += 1;
+			continue;
+		}
+
+		const prevCanFit = start > 0 && usedRows + blocks[start - 1]?.lines.length <= availableRows;
+		if (prevCanFit) {
+			start -= 1;
+			usedRows += blocks[start]?.lines.length;
+			continue;
+		}
+
+		break;
+	}
+
+	const visible = flatten(blocks.slice(start, end), selectedIndex);
+	visible.push({ line: indicator, selected: false });
+	return visible.slice(0, safeMaxRows);
+}