@xynogen/pix-ask 0.2.22 → 0.2.24

package/README.md

@@ -4,9 +4,15 @@ Pi tool — structured questionnaire UI (`ask_user`).
 
 ## What it does
 
-Registers the `ask_user` tool in Pi. When the agent needs to resolve ambiguous requirements, it presents up to 4 structured multiple-choice questions in a TUI dialog. Each question requires 2–4 options with labels and descriptions; supports multi-select and markdown side-by-side previews for richer context. Single-select questions (without a preview) auto-append a "Type something." row for free-form input; multi-select questions append a "Next" row to advance. Single-select questions with a `preview` skip the free-form row to make room for the side-by-side layout. In non-interactive (RPC/JSON) mode, falls back to text-based prompts. The agent uses this tool before proceeding rather than guessing at intent.
+Registers the `ask_user` tool — up to 4 structured multiple-choice questions in a TUI dialog when the agent needs to resolve ambiguous requirements, instead of guessing.
 
-While the dialog is open, `ask_user` holds the shared **agent-state** coordinator in the `blocked` state (via `withAgentBlock` from [`@xynogen/pix-runtime`](https://www.npmjs.com/package/@xynogen/pix-runtime)). Inside a herdr pane that transition fires a "needs attention" notification, so a user away from the terminal is pinged when a question is waiting.
+- Each question: 2–4 options with labels + descriptions. Supports multi-select and markdown side-by-side previews.
+- **Single-select** (no preview) → appends a "Type something." free-form row.
+- **Single-select with `preview`** → skips the free-form row to fit the side-by-side layout.
+- **Multi-select** → appends a "Next" row to advance.
+- Non-interactive (RPC/JSON) mode falls back to text prompts.
+
+**Away notifications** — while the dialog is open, `ask_user` holds the shared **agent-state** coordinator `blocked` (via `withAgentBlock` from [`@xynogen/pix-runtime`](https://www.npmjs.com/package/@xynogen/pix-runtime)), so a herdr pane pings an away user when a question waits.
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-ask",
-	"version": "0.2.22",
+	"version": "0.2.24",
 	"description": "Pi tool — structured questionnaire UI (ask_user)",
 	"type": "module",
 	"main": "src/index.ts",

package/src/components.ts

@@ -38,7 +38,7 @@ export class TabBar implements Component {
 			const tag = `${num}.${this.questions[i]?.header}`;
 			parts.push(active ? t.fg("accent", t.bold(tag)) : t.fg("dim", tag));
 		}
-		const line = parts.join(t.fg("dim", "  "));
+		const line = parts.join(t.fg("muted", "  "));
 		return [
 			truncateToWidth(
 				t.fg("accent", "╭─") +

package/src/index.ts

@@ -57,6 +57,7 @@ export default function registerAsk(pi: ExtensionAPI): void {
 					};
 				}
 
+				// SAFETY: ParamsSchema validates tool input before execute receives it.
 				const typed = params as unknown as Params;
 
 				if (!Array.isArray(typed.questions) || typed.questions.length === 0) {
@@ -113,9 +114,11 @@ export default function registerAsk(pi: ExtensionAPI): void {
 				const questions = Array.isArray(args.questions) ? args.questions : [];
 				const count = questions.length;
 				const firstQ = questions[0]?.question ?? "";
-				const head = `${theme.fg("toolTitle", theme.bold("ask_user"))} ${theme.fg("muted", firstQ)}`;
+				const head = `${theme.fg("toolTitle", theme.bold("ask_user"))} ${theme.fg("dim", firstQ)}`;
 				text.setText(
-					dotJoin([head, theme.fg("dim", pluralize(count, "question"))], (s) => theme.fg("dim", s)),
+					dotJoin([head, theme.fg("muted", pluralize(count, "question"))], (s) =>
+						theme.fg("muted", s),
+					),
 				);
 				return text;
 			},

package/src/questionnaire.ts

@@ -18,7 +18,6 @@ import {
 	terminalModalHeight,
 } from "@xynogen/pix-pretty/modal-frame";
 import { ChipEditor } from "./chip-editor.js";
-import { dim } from "./components.js";
 import { checkboxGlyphs, selectionGlyph } from "./glyphs.js";
 import { safeMarkdownTheme, sentinelsFor } from "./helpers.js";
 import type { OptionData, Params, QuestionData } from "./schema.js";
@@ -127,8 +126,8 @@ export class AskQuestionnaire extends Container {
 				selectList: {
 					selectedPrefix: (s: string) => this.theme.fg("accent", s),
 					selectedText: (s: string) => this.theme.fg("accent", s),
-					description: (s: string) => this.theme.fg("muted", s),
-					scrollInfo: (s: string) => this.theme.fg("dim", s),
+					description: (s: string) => this.theme.fg("dim", s),
+					scrollInfo: (s: string) => this.theme.fg("muted", s),
 					noMatch: (s: string) => this.theme.fg("warning", s),
 				},
 			},
@@ -470,19 +469,19 @@ export class AskQuestionnaire extends Container {
 						Math.max(10, inner - LABEL_COL),
 					);
 					for (const w of wrapped) {
-						lines.push(truncateToWidth(`${pad}${t.fg("muted", w)}`, inner, ""));
+						lines.push(truncateToWidth(`${pad}${t.fg("dim", w)}`, inner, ""));
 					}
 				}
 			} else if (item.kind === "other") {
 				const label = sel
 					? t.fg("accent", t.bold(SENTINEL_FREEFORM))
 					: t.fg("text", t.bold(SENTINEL_FREEFORM));
-				lines.push(truncateToWidth(`${ptr} ${t.fg("dim", "✎")} ${label}`, inner, ""));
+				lines.push(truncateToWidth(`${ptr} ${t.fg("muted", "✎")} ${label}`, inner, ""));
 			} else if (item.kind === "next") {
 				const label = sel
 					? t.fg("accent", t.bold(SENTINEL_NEXT))
 					: t.fg("text", t.bold(SENTINEL_NEXT));
-				lines.push(truncateToWidth(`${ptr} ${t.fg("dim", "→")} ${label}`, inner, ""));
+				lines.push(truncateToWidth(`${ptr} ${t.fg("muted", "→")} ${label}`, inner, ""));
 			}
 			if (sel)
 				this.selectedOptionRows = { start: itemStart, end: Math.max(itemStart + 1, lines.length) };
@@ -494,7 +493,7 @@ export class AskQuestionnaire extends Container {
 	private renderPreview(width: number): string[] {
 		const item = this.selectedItem;
 		if (item?.kind !== "option" || !item.option?.preview) {
-			return [this.theme.fg("dim", "No preview")];
+			return [this.theme.fg("muted", "No preview")];
 		}
 
 		const mdText = item.option.preview;
@@ -506,7 +505,7 @@ export class AskQuestionnaire extends Container {
 		}
 
 		const lines = wrapTextWithAnsi(mdText, mdWidth);
-		return lines.map((l) => truncateToWidth(this.theme.fg("muted", l), mdWidth, ""));
+		return lines.map((l) => truncateToWidth(this.theme.fg("dim", l), mdWidth, ""));
 	}
 
 	override render(termWidth: number): string[] {
@@ -528,8 +527,8 @@ export class AskQuestionnaire extends Container {
 		let footer: string[] = [];
 
 		const row = (content: string): string => truncateToWidth(content, width, "");
-		const guide = (key: string, action: string) => t.fg("text", key) + t.fg("dim", ` ${action}`);
-		const guideSep = t.fg("dim", " • ");
+		const guide = (key: string, action: string) => t.fg("muted", `${key} ${action}`);
+		const guideSep = t.fg("muted", " • ");
 
 		// Tab bar — rendered as the framed top edge (frameLines `top`).
 		let top: string | undefined;
@@ -540,14 +539,14 @@ export class AskQuestionnaire extends Container {
 				const tag = `${i + 1}.${this.params.questions[i]?.header}`;
 				tabParts.push(active ? t.fg("accent", t.bold(tag)) : t.fg("dim", tag));
 			}
-			top = truncateToWidth(tabParts.join(t.fg("dim", "  ")), width, "");
+			top = truncateToWidth(tabParts.join(t.fg("muted", "  ")), width, "");
 		}
 
 		// Header chip
 		const chip = t.fg("accent", t.bold(this.currentQ.header));
 		const prog =
 			this.params.questions.length > 1
-				? dim(t)(` ${this.currentIndex + 1}/${this.params.questions.length}`)
+				? t.fg("muted", ` ${this.currentIndex + 1}/${this.params.questions.length}`)
 				: "";
 		header.push(row(`${chip}${prog}`));
 
@@ -583,7 +582,7 @@ export class AskQuestionnaire extends Container {
 		if (!isMulti) {
 			const searchVal = this.searchQuery
 				? t.fg("text", this.searchQuery)
-				: t.fg("dim", "type to filter");
+				: t.fg("muted", "type to filter");
 			header.push(row(`${t.fg("accent", "Filter:")} ${searchVal}`));
 		}
 
@@ -593,7 +592,7 @@ export class AskQuestionnaire extends Container {
 		const maxOptLines = Math.max(optionLines.length, previewLines.length);
 
 		if (useSplit) {
-			const sep = t.fg("dim", SEPARATOR);
+			const sep = t.fg("muted", SEPARATOR);
 			for (let i = 0; i < maxOptLines; i++) {
 				const left = truncateToWidth(optionLines[i] ?? "", leftWidth, "", true);
 				const right = truncateToWidth(previewLines[i] ?? "", previewWidth, "");
@@ -643,7 +642,7 @@ export class AskQuestionnaire extends Container {
 			color: (s) => t.fg("accent", s),
 			bg: (s) => t.bg("customMessageBg", s),
 			overflowLine: ({ page, totalPages }) =>
-				t.fg("dim", `PgUp/PgDn inspect • ${page}/${totalPages}`),
+				t.fg("muted", `PgUp/PgDn inspect • ${page}/${totalPages}`),
 		});
 		this.pager.sync(result);
 		return result.lines;