@xynogen/pix-core 0.1.0 → 0.1.2

package/src/nudge/tools.test.ts

@@ -114,15 +114,23 @@ describe("classifyCompound", () => {
 });
 
 describe("nudgeReason", () => {
-		test("active tool: point straight at it, no toolbox", () => {
-		const msg = nudgeReason("Searching file contents via bash grep/rg.", "grep", true);
+	test("active tool: point straight at it, no toolbox", () => {
+		const msg = nudgeReason(
+			"Searching file contents via bash grep/rg.",
+			"grep",
+			true,
+		);
 		expect(msg).toContain("Use `grep` instead");
 		expect(msg).toContain("function definitions");
 		expect(msg).not.toContain("toolbox");
 	});
 
-		test("gated tool: route through toolbox enable, not a direct call", () => {
-		const msg = nudgeReason("Listing a directory via bash ls/tree.", "ls", false);
+	test("gated tool: route through toolbox enable, not a direct call", () => {
+		const msg = nudgeReason(
+			"Listing a directory via bash ls/tree.",
+			"ls",
+			false,
+		);
 		expect(msg).toContain('toolbox(action:"enable", name:"ls")');
 		expect(msg).toContain("prompt-hidden");
 		expect(msg).toContain("function definitions");
@@ -131,13 +139,17 @@ describe("nudgeReason", () => {
 	});
 
 	test("gated find tool names itself in the enable hint", () => {
-		expect(nudgeReason("Locating files via bash find/fd.", "find", false)).toContain(
-			'toolbox(action:"enable", name:"find")',
-		);
+		expect(
+			nudgeReason("Locating files via bash find/fd.", "find", false),
+		).toContain('toolbox(action:"enable", name:"find")');
 	});
 
-		test("is a single short line — no inventory dump, no newlines", () => {
-		const msg = nudgeReason("Listing a directory via bash ls/tree.", "ls", false);
+	test("is a single short line — no inventory dump, no newlines", () => {
+		const msg = nudgeReason(
+			"Listing a directory via bash ls/tree.",
+			"ls",
+			false,
+		);
 		expect(msg).not.toContain("\n");
 		expect(msg).not.toContain("Available tools");
 		expect(msg.length).toBeLessThan(400);

package/src/nudge/tools.ts

@@ -28,7 +28,6 @@ import {
 	isToolCallEventType,
 } from "@earendil-works/pi-coding-agent";
 
-
 /** Categories that map a raw shell command to a dedicated Pi tool. */
 type Category = "read" | "ls" | "grep" | "find" | "edit";
 
@@ -116,7 +115,6 @@ export function splitSegments(command: string): Segment[] {
 	const re = /(\|\||&&|[|;&\n])/g;
 	let last = 0;
 	let m: RegExpExecArray | null;
-	// biome-ignore lint/suspicious/noAssignInExpressions: standard regex walk
 	while ((m = re.exec(command)) !== null) {
 		out.push({ text: command.slice(last, m.index), followedBy: m[1] });
 		last = m.index + m[1].length;

package/src/tool/ask/ask.test.ts

@@ -7,17 +7,21 @@
 
 import { describe, expect, test } from "bun:test";
 import {
-	type OptionData,
-	type QuestionData,
 	buildResponseText,
 	formatAnswerScalar,
 	hasAnyPreview,
+	type OptionData,
+	type QuestionData,
 	sentinelsFor,
-} from "./ask.ts";
+} from "./index.ts";
 
 // ── Fixtures ──────────────────────────────────────────────────────────
 
-const opt = (label: string, description = "Test option", preview?: string): OptionData => ({
+const opt = (
+	label: string,
+	description = "Test option",
+	preview?: string,
+): OptionData => ({
 	label,
 	description,
 	...(preview ? { preview } : {}),
@@ -55,10 +59,7 @@ const qWithPreview: QuestionData = {
 const qSingleNoPreview: QuestionData = {
 	question: "Color?",
 	header: "Color",
-	options: [
-		opt("Red", "Ruby red"),
-		opt("Blue", "Ocean blue"),
-	],
+	options: [opt("Red", "Ruby red"), opt("Blue", "Ocean blue")],
 };
 
 // ── hasAnyPreview ─────────────────────────────────────────────────────
@@ -85,8 +86,8 @@ describe("sentinelsFor", () => {
 	test('single-select without preview appends "Type something."', () => {
 		const r = sentinelsFor(qSingleNoPreview);
 		expect(r).toHaveLength(1);
-		expect(r[0]!.kind).toBe("other");
-		expect(r[0]!.label).toBe("Type something.");
+		expect(r[0]?.kind).toBe("other");
+		expect(r[0]?.label).toBe("Type something.");
 	});
 
 	test('single-select with preview appends nothing (only "Chat about this" is separate)', () => {
@@ -97,8 +98,8 @@ describe("sentinelsFor", () => {
 	test('multi-select appends "Next"', () => {
 		const r = sentinelsFor(qMulti);
 		expect(r).toHaveLength(1);
-		expect(r[0]!.kind).toBe("next");
-		expect(r[0]!.label).toBe("Next");
+		expect(r[0]?.kind).toBe("next");
+		expect(r[0]?.label).toBe("Next");
 	});
 
 	test("multi-select never appends Type something.", () => {
@@ -109,14 +110,14 @@ describe("sentinelsFor", () => {
 	test("empty options still gets freeform sentinel (no preview = single-select)", () => {
 		const r = sentinelsFor({ question: "?", header: "X", options: [] });
 		expect(r).toHaveLength(1);
-		expect(r[0]!.kind).toBe("other");
+		expect(r[0]?.kind).toBe("other");
 	});
 });
 
 // ── formatAnswerScalar ────────────────────────────────────────────────
 
 describe("formatAnswerScalar", () => {
-	test('option kind returns the answer string', () => {
+	test("option kind returns the answer string", () => {
 		const a = {
 			questionIndex: 0,
 			question: "Q",
@@ -126,7 +127,7 @@ describe("formatAnswerScalar", () => {
 		expect(formatAnswerScalar(a)).toBe("REST");
 	});
 
-	test('multi kind joins selected with comma', () => {
+	test("multi kind joins selected with comma", () => {
 		const a = {
 			questionIndex: 0,
 			question: "Q",
@@ -137,7 +138,7 @@ describe("formatAnswerScalar", () => {
 		expect(formatAnswerScalar(a)).toBe("Auth, Search");
 	});
 
-	test('custom kind returns the typed text', () => {
+	test("custom kind returns the typed text", () => {
 		const a = {
 			questionIndex: 0,
 			question: "Q",
@@ -147,7 +148,7 @@ describe("formatAnswerScalar", () => {
 		expect(formatAnswerScalar(a)).toBe("my custom answer");
 	});
 
-	test('chat kind returns (chat)', () => {
+	test("chat kind returns (chat)", () => {
 		const a = {
 			questionIndex: 0,
 			question: "Q",
@@ -163,7 +164,12 @@ describe("formatAnswerScalar", () => {
 describe("buildResponseText", () => {
 	test("formats single answer", () => {
 		const answers = [
-			{ questionIndex: 0, question: "Which approach?", kind: "option" as const, answer: "REST" },
+			{
+				questionIndex: 0,
+				question: "Which approach?",
+				kind: "option" as const,
+				answer: "REST",
+			},
 		];
 		const text = buildResponseText(answers, [qSingle]);
 		expect(text).toContain("REST");
@@ -202,7 +208,12 @@ describe("buildResponseText", () => {
 	test("formats multiple answers", () => {
 		const qs = [qSingle, qMulti];
 		const answers = [
-			{ questionIndex: 0, question: "Which approach?", kind: "option" as const, answer: "GraphQL" },
+			{
+				questionIndex: 0,
+				question: "Which approach?",
+				kind: "option" as const,
+				answer: "GraphQL",
+			},
 			{
 				questionIndex: 1,
 				question: "Which features?",
@@ -226,7 +237,7 @@ describe("buildResponseText", () => {
 
 describe("registerAsk", () => {
 	test("exports a default function", async () => {
-		const mod = await import("./ask.ts");
+		const mod = await import("./index.ts");
 		expect(typeof mod.default).toBe("function");
 	});
 });

package/src/tool/ask/components.ts

@@ -0,0 +1,55 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, truncateToWidth } from "@earendil-works/pi-tui";
+import type { QuestionData } from "./schema.js";
+
+// ── Color helpers ──────────────────────────────────────────────────────
+
+export function borderColor(theme: Theme): (s: string) => string {
+	return (s: string) => theme.fg("accent", s);
+}
+
+export function dim(theme: Theme): (s: string) => string {
+	return (s: string) => theme.fg("dim", s);
+}
+
+// ── TabBar ─────────────────────────────────────────────────────────────
+
+export class TabBar implements Component {
+	private questions: QuestionData[];
+	private activeIndex: number;
+	private theme: Theme;
+
+	constructor(questions: QuestionData[], activeIndex: number, theme: Theme) {
+		this.questions = questions;
+		this.activeIndex = activeIndex;
+		this.theme = theme;
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const t = this.theme;
+		const inner = Math.max(10, width - 2);
+
+		const parts: string[] = [];
+		for (let i = 0; i < this.questions.length; i++) {
+			const active = i === this.activeIndex;
+			const num = `${i + 1}`;
+			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", "  "));
+		return [
+			truncateToWidth(
+				t.fg("accent", "╭─") +
+					line +
+					t.fg(
+						"accent",
+						`${"─".repeat(Math.max(0, inner - line.length - 1))}╮`,
+					),
+				width,
+				"",
+			),
+		].filter(Boolean);
+	}
+}

package/src/tool/ask/helpers.ts

@@ -0,0 +1,77 @@
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import type { MarkdownTheme } from "@earendil-works/pi-tui";
+import type { OptionData, QuestionData } from "./schema.js";
+import { SENTINEL_CHAT, SENTINEL_FREEFORM, SENTINEL_NEXT } from "./schema.js";
+import type { AnswerKind, QuestionAnswer } from "./types.js";
+
+// ── Markdown theme ─────────────────────────────────────────────────────
+
+export function safeMarkdownTheme(): MarkdownTheme | undefined {
+	try {
+		const md = getMarkdownTheme();
+		if (!md) return undefined;
+		md.bold("");
+		return md;
+	} catch {
+		return undefined;
+	}
+}
+
+// ── Option / question helpers ──────────────────────────────────────────
+
+export function hasAnyPreview(q: QuestionData): boolean {
+	return q.options.some(
+		(o) => typeof o.preview === "string" && o.preview.length > 0,
+	);
+}
+
+/** Which sentinel rows are auto-appended for a question. */
+export function sentinelsFor(
+	q: QuestionData,
+): Array<{ kind: string; label: string }> {
+	const out: Array<{ kind: string; label: string }> = [];
+	if (q.multiSelect) {
+		out.push({ kind: "next", label: SENTINEL_NEXT });
+	} else if (!hasAnyPreview(q)) {
+		out.push({ kind: "other", label: SENTINEL_FREEFORM });
+	}
+	return out;
+}
+
+// ── Answer formatting ──────────────────────────────────────────────────
+
+export function formatAnswerScalar(a: QuestionAnswer): string {
+	if (a.kind === "multi") return (a.selected ?? []).join(", ");
+	if (a.kind === "custom") return a.answer ?? "(custom)";
+	if (a.kind === "chat") return "(chat)";
+	return a.answer ?? "(selected)";
+}
+
+export function buildResponseText(
+	answers: QuestionAnswer[],
+	questions: QuestionData[],
+): string {
+	const segs: string[] = [];
+	for (const a of answers) {
+		const q = questions[a.questionIndex]?.question ?? `Q${a.questionIndex + 1}`;
+		let s = `"${q}"="${formatAnswerScalar(a)}"`;
+		if (a.preview) s += `. selected preview: ${a.preview}`;
+		segs.push(s);
+	}
+	return segs.length
+		? `User answered: ${segs.join(". ")}.`
+		: "User declined to answer questions.";
+}
+
+// ── Scroll indicator ───────────────────────────────────────────────────
+
+export function scrollIndicator(index: number, total: number): string {
+	if (total <= 1) return "";
+	const pos = Math.round((index / (total - 1)) * 6);
+	const bar = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦"][pos] ?? "·";
+	return ` ${bar} ${index + 1}/${total}`;
+}
+
+export type { AnswerKind, OptionData, QuestionData };
+// Re-export sentinel constants so callers don't need to import schema directly
+export { SENTINEL_CHAT, SENTINEL_FREEFORM, SENTINEL_NEXT };

package/src/tool/ask/index.ts

@@ -0,0 +1,130 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+import { buildResponseText } from "./helpers.js";
+import { AskQuestionnaire } from "./questionnaire.js";
+import { rpcFallback } from "./rpc.js";
+import type { Params } from "./schema.js";
+import {
+	MAX_OPTIONS,
+	MAX_QUESTIONS,
+	MIN_OPTIONS,
+	ParamsSchema,
+	SENTINEL_CHAT,
+	SENTINEL_FREEFORM,
+} from "./schema.js";
+import type { QuestionAnswer, QuestionnaireResult } from "./types.js";
+
+// ── Re-exports (consumed by tests and single-select-layout) ───────────
+
+export {
+	buildResponseText,
+	formatAnswerScalar,
+	hasAnyPreview,
+	sentinelsFor,
+} from "./helpers.js";
+export type { OptionData, QuestionData } from "./schema.js";
+export type {
+	AnswerKind,
+	QuestionAnswer,
+	QuestionnaireResult,
+} from "./types.js";
+
+// ── Tool registration ──────────────────────────────────────────────────
+
+export default function registerAsk(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "ask_user",
+		label: "Ask",
+		description: `Ask the user up to ${MAX_QUESTIONS} structured questions (${MIN_OPTIONS}-${MAX_OPTIONS} options each) when requirements are ambiguous.`,
+		promptSnippet: `Ask the user up to ${MAX_QUESTIONS} structured questions (${MIN_OPTIONS}-${MAX_OPTIONS} options each) when requirements are ambiguous`,
+		promptGuidelines: [
+			`Use ask whenever the user's request is underspecified and you cannot proceed without concrete decisions — you can ask up to ${MAX_QUESTIONS} questions per invocation.`,
+			`Each question MUST have ${MIN_OPTIONS}-${MAX_OPTIONS} options. Every option requires a concise label (1-5 words) and a description explaining what the choice means or its trade-offs. The user can additionally type a custom answer ("${SENTINEL_FREEFORM}" row is appended automatically to single-select questions) or pick "${SENTINEL_CHAT}" to abandon the questionnaire.`,
+			`Set multiSelect: true when multiple answers are valid; this suppresses the "${SENTINEL_FREEFORM}" row. Provide an options[].preview markdown string when an option benefits from richer side-by-side context (mockups, code snippets, diagrams, configs) — single-select only. NOTE: any non-empty preview on a single-select question ALSO suppresses the "${SENTINEL_FREEFORM}" row (no room in the side-by-side layout); "${SENTINEL_CHAT}" remains the escape hatch. If you recommend a specific option, make it the first option and append "(Recommended)" to its label.`,
+			"Do not stack multiple ask calls back-to-back — group all clarifying questions into one invocation.",
+		],
+		executionMode: "sequential",
+		parameters: ParamsSchema,
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			if (signal?.aborted) {
+				return {
+					content: [{ type: "text", text: "Cancelled" }],
+					details: { answers: [], cancelled: true },
+				};
+			}
+
+			const typed = params as unknown as Params;
+
+			if (!Array.isArray(typed.questions) || typed.questions.length === 0) {
+				return {
+					content: [
+						{ type: "text", text: "At least one question is required." },
+					],
+					isError: true,
+					details: { answers: [], cancelled: true },
+				};
+			}
+
+			if (!ctx.hasUI) {
+				const result = await rpcFallback(ctx.ui, typed);
+				const text = result.cancelled
+					? "User cancelled the questionnaire"
+					: buildResponseText(result.answers, typed.questions);
+				return { content: [{ type: "text", text }], details: result };
+			}
+
+			const result = await ctx.ui.custom<QuestionnaireResult | null>(
+				(tui, theme, keybindings, done) => {
+					if (signal) {
+						signal.addEventListener(
+							"abort",
+							() => done({ answers: [], cancelled: true }),
+							{ once: true },
+						);
+					}
+					return new AskQuestionnaire(typed, tui, theme, keybindings, done);
+				},
+			);
+
+			if (!result || result.cancelled) {
+				return {
+					content: [{ type: "text", text: "User cancelled the questionnaire" }],
+					details: result ?? { answers: [], cancelled: true },
+				};
+			}
+
+			const text = buildResponseText(result.answers, typed.questions);
+			return { content: [{ type: "text", text }], details: result };
+		},
+
+		renderCall(args, theme) {
+			const questions = Array.isArray(args.questions) ? args.questions : [];
+			const count = questions.length;
+			const firstQ = (questions[0]?.question ?? "") as string;
+			let text = theme.fg("toolTitle", theme.bold(`ask (${count}) `));
+			text += theme.fg("muted", firstQ);
+			if (count > 1) text += theme.fg("dim", ` +${count - 1} more`);
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, options, theme) {
+			const details = result.details as
+				| { answers?: QuestionAnswer[]; cancelled?: boolean }
+				| undefined;
+			if (options.isPartial) {
+				return new Text(theme.fg("muted", "Waiting for user input..."), 0, 0);
+			}
+			if (!details || details.cancelled || !details.answers?.length) {
+				return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+			}
+			const texts = details.answers.map((a) => {
+				const v =
+					a.kind === "multi" ? (a.selected ?? []).join(", ") : (a.answer ?? "");
+				return `${a.questionIndex + 1}: ${v}`;
+			});
+			return new Text(theme.fg("success", `✓ ${texts.join(" • ")}`), 0, 0);
+		},
+	});
+}