@shanepadgett/tau-agent 0.1.0

package/extensions/qna/choice-question-body.ts

@@ -0,0 +1,322 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Editor, type Focusable, Key, matchesKey, type TUI } from "@earendil-works/pi-tui";
+import { editorTheme } from "@shanepadgett/tau-tui";
+import { bindingHint, bindingsHint, rawHint, type ToolKeyHint } from "@shanepadgett/tau-tui";
+import { renderQuestionPrompt } from "./body-render.ts";
+import { pushSavedNote, renderInlineEditor, renderNoteEditor, wrapWithPrefix } from "./inline-editor-row.ts";
+import { renderRecommendation } from "./input-question-body.ts";
+import {
+	getAnswer,
+	hasCustom,
+	moveOption,
+	type NormalizedQuestion,
+	optionCount,
+	type QnaState,
+	saveCustomAnswer,
+	saveOptionNote,
+	toggleOrSelectOption,
+} from "./model.ts";
+
+type Mode = "navigate" | "custom" | "note";
+
+export class ChoiceQuestionBody implements Focusable {
+	private readonly theme: Theme;
+	private readonly getState: () => QnaState;
+	private readonly setState: (state: QnaState) => void;
+	private readonly advance: () => void;
+	private readonly noteEditor: Editor;
+	private readonly customEditor: Editor;
+	private mode: Mode = "navigate";
+	private noteTarget?: { questionId: string; value: string };
+	private customQuestionId?: string;
+	private activeQuestionId: string | undefined;
+	private _focused = false;
+
+	constructor(
+		tui: TUI,
+		theme: Theme,
+		getState: () => QnaState,
+		setState: (state: QnaState) => void,
+		advance: () => void,
+	) {
+		this.theme = theme;
+		this.getState = getState;
+		this.setState = setState;
+		this.advance = advance;
+		this.noteEditor = new Editor(tui, editorTheme(theme));
+		this.customEditor = new Editor(tui, editorTheme(theme));
+		this.noteEditor.onSubmit = (value) => this.saveNote(value);
+	}
+
+	get focused(): boolean {
+		return this._focused;
+	}
+
+	set focused(value: boolean) {
+		this._focused = value;
+		this.noteEditor.focused = value && this.mode === "note";
+		this.customEditor.focused = value && this.mode === "custom";
+	}
+
+	forQuestion(question: NormalizedQuestion): this {
+		this.activeQuestionId = question.id;
+		this.focused = this._focused;
+		return this;
+	}
+
+	isEditing(): boolean {
+		return this.mode !== "navigate";
+	}
+
+	keyHints(): readonly ToolKeyHint[] {
+		if (this.mode === "custom") {
+			return [bindingHint("tui.input.submit", "save"), bindingHint("tui.select.cancel", "cancel edit")];
+		}
+		if (this.mode === "note") {
+			return [bindingHint("tui.input.submit", "save"), bindingHint("tui.select.cancel", "cancel note")];
+		}
+		const question = this.currentQuestion();
+		return question?.kind === "multi"
+			? [
+					bindingsHint(["tui.select.up", "tui.select.down"], "move"),
+					rawHint("Space", "toggle"),
+					bindingHint("tui.select.confirm", "next"),
+					rawHint("n", "note"),
+				]
+			: [
+					bindingsHint(["tui.select.up", "tui.select.down"], "move"),
+					bindingHint("tui.select.confirm", "choose"),
+					rawHint("n", "note"),
+				];
+	}
+
+	handleInput(data: string): void {
+		const question = this.currentQuestion();
+		if (!question) return;
+		this.activeQuestionId = question.id;
+		if (this.mode === "note") {
+			this.handleNoteInput(data);
+			return;
+		}
+		if (this.mode === "custom") {
+			this.handleCustomInput(data);
+			return;
+		}
+		if (matchesKey(data, Key.up)) {
+			this.setState(moveOption(this.getState(), -1));
+			return;
+		}
+		if (matchesKey(data, Key.down)) {
+			this.setState(moveOption(this.getState(), 1));
+			return;
+		}
+		if (this.isCustomActive(question) && isPrintable(data)) {
+			this.openCustom(question, "");
+			this.customEditor.handleInput(data);
+			return;
+		}
+		if (data === "n") {
+			this.openNote(question);
+			return;
+		}
+		if (matchesKey(data, Key.enter) && question.kind === "multi") {
+			this.advance();
+			return;
+		}
+		if (data === " " || matchesKey(data, Key.enter)) this.chooseActive(question);
+	}
+
+	render(question: NormalizedQuestion, width: number): string[] {
+		this.activeQuestionId = question.id;
+		this.focused = this._focused;
+		const lines = renderQuestionPrompt(question, width);
+		for (let index = 0; index < optionCount(question); index++) {
+			if (question.kind === "multi") lines.push(...this.renderMultiOption(question, index, width));
+			else lines.push(...this.renderSingleOption(question, index, width));
+		}
+		lines.push("");
+		lines.push(...renderRecommendation(question, width, this.theme));
+		return lines;
+	}
+
+	closeInactiveEditors(): void {
+		if (this.mode === "navigate") return;
+		if (this.activeQuestionId === this.getState().questions[this.getState().activeTab]?.id) return;
+		this.closeNote();
+		this.closeCustom();
+	}
+
+	private renderSingleOption(question: NormalizedQuestion, index: number, width: number): string[] {
+		if (this.isCustomIndex(question, index)) return this.renderCustomOption(question, false, width);
+		const ctx = this.optionContext(question, index);
+		if (!ctx) return [];
+		const { option, active, selected } = ctx;
+		const prefix = active ? this.theme.fg("accent", "→ ") : "  ";
+		const label = `${this.theme.fg(active ? "accent" : "text", option.label)}${
+			selected ? this.theme.fg("success", " ✓") : ""
+		}`;
+		const lines = wrapWithPrefix(prefix, label, width);
+		this.renderOptionNote(lines, question, option.value, width, "  ");
+		return lines;
+	}
+
+	private renderMultiOption(question: NormalizedQuestion, index: number, width: number): string[] {
+		if (this.isCustomIndex(question, index)) return this.renderCustomOption(question, true, width);
+		const ctx = this.optionContext(question, index);
+		if (!ctx) return [];
+		const { option, active, selected } = ctx;
+		const pointer = active ? this.theme.fg("accent", "→ ") : "  ";
+		const box = selected ? "[x]" : this.theme.fg("dim", "[ ]");
+		const label = this.theme.fg(active ? "accent" : "text", option.label);
+		const lines = wrapWithPrefix(`${pointer}${box} `, label, width);
+		this.renderOptionNote(lines, question, option.value, width, "      ");
+		return lines;
+	}
+
+	private renderCustomOption(question: NormalizedQuestion, multi: boolean, width: number): string[] {
+		const answer = getAnswer(this.getState(), question.id);
+		const active = this.isCustomActive(question);
+		const editing = active && this.mode === "custom" && this.customQuestionId === question.id;
+		const draftSelected = editing ? Boolean(clean(this.customEditor.getText())) : false;
+		const selected = Boolean(answer.custom) || draftSelected;
+		const pointer = active ? this.theme.fg("accent", "→ ") : "  ";
+		const box = multi ? `${selected ? "[x]" : this.theme.fg("dim", "[ ]")} ` : "";
+		const prefix = `${pointer}${box}`;
+		if (editing) return renderInlineEditor(prefix, this.customEditor, width);
+		const label = answer.custom || "Type your own answer...";
+		return wrapWithPrefix(
+			prefix,
+			`${this.theme.fg(active ? "accent" : "text", label)}${
+				!multi && selected ? this.theme.fg("success", " ✓") : ""
+			}`,
+			width,
+		);
+	}
+
+	private optionContext(question: NormalizedQuestion, index: number) {
+		const option = question.options[index];
+		if (!option) return null;
+		const answer = getAnswer(this.getState(), question.id);
+		const active = index === this.getState().activeOption;
+		const selected = answer.selected.includes(option.value);
+		return { option, active, selected };
+	}
+
+	private renderOptionNote(
+		lines: string[],
+		question: NormalizedQuestion,
+		value: string,
+		width: number,
+		indent: string,
+	): void {
+		if (this.mode === "note" && this.noteTarget?.questionId === question.id && this.noteTarget.value === value) {
+			renderNoteEditor(lines, this.noteEditor, width, this.theme, indent);
+			return;
+		}
+		const note = getAnswer(this.getState(), question.id).notes[value];
+		if (note) pushSavedNote(lines, note, width, this.theme, indent);
+	}
+
+	private chooseActive(question: NormalizedQuestion): void {
+		if (this.isCustomActive(question)) {
+			this.openCustom(question, getAnswer(this.getState(), question.id).custom || "");
+			return;
+		}
+		const option = question.options[this.getState().activeOption];
+		if (!option) return;
+		this.setState(toggleOrSelectOption(this.getState(), question, option.value));
+		if (question.kind !== "multi") this.advance();
+	}
+
+	private openNote(question: NormalizedQuestion): void {
+		const option = question.options[this.getState().activeOption];
+		if (!option) return;
+		this.noteTarget = { questionId: question.id, value: option.value };
+		this.mode = "note";
+		this.noteEditor.setText(getAnswer(this.getState(), question.id).notes[option.value] || "");
+		this.focused = this._focused;
+	}
+
+	private openCustom(question: NormalizedQuestion, value: string): void {
+		this.mode = "custom";
+		this.customQuestionId = question.id;
+		this.customEditor.setText(value);
+		this.focused = this._focused;
+	}
+
+	private handleNoteInput(data: string): void {
+		if (matchesKey(data, Key.escape)) {
+			this.closeNote();
+			return;
+		}
+		this.noteEditor.handleInput(data);
+	}
+
+	private handleCustomInput(data: string): void {
+		if (matchesKey(data, Key.escape)) {
+			this.closeCustom();
+			return;
+		}
+		if (matchesKey(data, Key.enter)) {
+			this.saveCustom();
+			return;
+		}
+		this.customEditor.handleInput(data);
+	}
+
+	private saveNote(value: string): void {
+		const question = this.currentQuestion();
+		if (question && this.noteTarget) {
+			this.setState(saveOptionNote(this.getState(), question, this.noteTarget.value, value));
+		}
+		this.closeNote();
+	}
+
+	private saveCustom(): void {
+		const question = this.currentQuestion();
+		if (!question) return;
+		this.setState(saveCustomAnswer(this.getState(), question, this.customEditor.getText()));
+		this.closeCustom();
+		this.advance();
+	}
+
+	private closeNote(): void {
+		this.mode = "navigate";
+		this.noteTarget = undefined;
+		this.noteEditor.setText("");
+		this.focused = this._focused;
+	}
+
+	private closeCustom(): void {
+		this.mode = "navigate";
+		this.customQuestionId = undefined;
+		this.customEditor.setText("");
+		this.focused = this._focused;
+	}
+
+	private currentQuestion(): NormalizedQuestion | undefined {
+		return this.getState().questions.find((question) => question.id === this.activeQuestionId);
+	}
+
+	private isCustomActive(question: NormalizedQuestion): boolean {
+		return this.isCustomIndex(question, this.getState().activeOption);
+	}
+
+	private isCustomIndex(question: NormalizedQuestion, index: number): boolean {
+		return hasCustom(question) && index === question.options.length;
+	}
+}
+
+function isPrintable(data: string): boolean {
+	return (
+		data.length > 0 &&
+		![...data].some((char) => {
+			const code = char.charCodeAt(0);
+			return code < 32 || code === 0x7f || (code >= 0x80 && code <= 0x9f);
+		})
+	);
+}
+
+function clean(value: string): string {
+	return value.trim();
+}

package/extensions/qna/index.ts

@@ -0,0 +1,245 @@
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { emitAgentBlocked } from "../../shared/agent-blocked.ts";
+import { normalizeParams, type QnaParams, type QnaResult } from "./model.ts";
+import { runQnaUi } from "./ui.ts";
+
+const TOOL_ASK_QUESTION = "ask_question";
+
+const optionSchema = Type.Object({
+	value: Type.String({ description: "Stable option value returned in result" }),
+	label: Type.String({ description: "Short user-facing option label" }),
+});
+
+const recommendationSchema = Type.Object({
+	values: Type.Array(Type.String(), { description: "Recommended option values, chosen after options are written" }),
+	reason: Type.String({ description: "Honest tradeoff-based justification for recommendation" }),
+});
+
+const askQuestionParamsSchema = Type.Object({
+	title: Type.Optional(Type.String({ description: "Short title for the question panel" })),
+	questions: Type.Array(
+		Type.Object({
+			id: Type.String({ description: "Unique question id" }),
+			prompt: Type.String({ description: "Question shown to the user" }),
+			kind: StringEnum(["select", "multi", "input", "confirm"] as const, {
+				description: "select: one choice; multi: several choices; input: typed answer; confirm: yes/no",
+			}),
+			options: Type.Optional(
+				Type.Array(optionSchema, { description: "Required for select/multi, forbidden for input/confirm" }),
+			),
+			recommendation: Type.Optional(recommendationSchema),
+		}),
+		{ description: "Focused questions. Prefer 1-3." },
+	),
+});
+
+const QNA_PROMPT = `Use ask_question to re-ask the question you just asked the user.
+
+Do not blindly copy your previous wording or options. Reframe the question if needed so it follows ask_question quality rules:
+- options must be real, valid, defensible choices
+- do not include filler, strawmen, joke options, bad decoys, or preferred answer plus trash
+- use as many options as the real decision space needs: 2 is fine, 10 is fine, 3 is not special
+- if your previous options were weak, replace them
+- ground the reframed question in existing context; inspect repo or docs first only when current context is not enough
+- use select for one choice, multi for combinable choices, confirm for yes/no, input when choices would be fake
+- include recommendation only when you have a real one, with honest tradeoff reason
+- do not include a catch-all additional-context question; the UI always provides a final optional Additional Context tab
+- do not answer the question yourself
+- if there is no question to re-ask, say so without using tools`;
+
+function buildQnaPrompt(context: string): string {
+	const trimmed = context.trim();
+	if (!trimmed) return QNA_PROMPT;
+	return `${QNA_PROMPT}
+
+Additional user context for framing the question:
+${trimmed}`;
+}
+
+function createAskQuestionTool(pi: ExtensionAPI) {
+	return defineTool<typeof askQuestionParamsSchema, QnaResult>({
+		name: "ask_question",
+		label: "Ask Question",
+		description:
+			"Ask user structured question only when missing intent, preference, or constraint blocks progress. Supports select, multi-select, yes/no, and free-form input. Choices must be real, valid, non-filler. Selectable questions require recommendation values plus honest reason after options. Do not use for routine chat, obvious choices, or avoidable analysis.",
+		promptSnippet:
+			"Ask structured questions only when a real user decision blocks progress; every choice must be valid, defensible, non-filler.",
+		promptGuidelines: [
+			"Use ask_question only when missing user intent, preference, or constraint would materially change next action.",
+			"Do not use ask_question for routine chat, status updates, obvious decisions, or questions answerable from files/instructions.",
+			"If one path is clearly correct, do not use ask_question. Proceed and state assumption briefly.",
+			"When using ask_question choices, every option must be real, valid, and defensible. No filler, strawmen, joke options, bad decoys, or preferred answer plus junk.",
+			"When using ask_question choices, cover realistic decision space. Custom answer is safety valve, not excuse for weak options.",
+			"For ask_question select, multi-select, confirm, and recommended input: write options or suggested answer first, then recommendation values, then recommendation reason.",
+			"ask_question recommendation reason must explain tradeoff honestly. Do not manipulate user toward fake-obvious answer.",
+			"Use ask_question multi-select only when combining options is valid. Use select for one path. Use confirm for yes/no. Use input when choices would be fake; include an input recommendation only when you have a real suggested answer.",
+			"Ask fewest questions that unblock work. Prefer 1-3 focused questions. No surveys.",
+			"Do not add catch-all or additional-context questions; the UI always provides a final optional Additional Context tab.",
+		],
+		parameters: askQuestionParamsSchema,
+		executionMode: "sequential",
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const castParams = params as QnaParams;
+			const questions = normalizeParams(castParams);
+			if (ctx.mode !== "tui" || !ctx.hasUI) {
+				ctx.abort();
+				throw new Error("ask_question aborted: interactive UI unavailable");
+			}
+
+			ctx.ui.setWorkingVisible(false);
+			try {
+				emitAgentBlocked(pi, {
+					title: castParams.title || "Tau",
+					body: "Waiting for your answer",
+					source: "qna.ask_question",
+				});
+				const result = await ctx.ui.custom<QnaResult | undefined>((tui, theme, _keybindings, done) =>
+					runQnaUi(tui, theme, castParams.title, questions, done),
+				);
+				if (!result) {
+					ctx.abort();
+					throw new Error("ask_question aborted by user");
+				}
+				return {
+					content: [{ type: "text", text: formatResult(result) }],
+					details: result,
+				};
+			} finally {
+				ctx.ui.setWorkingVisible(true);
+			}
+		},
+
+		renderCall(args, theme) {
+			const params = args as QnaParams;
+			const count = Array.isArray(params.questions) ? params.questions.length : 0;
+			return new Text(
+				`${theme.fg("toolTitle", theme.bold("ask_question"))} ${theme.fg("muted", params.title || `${count} question${count === 1 ? "" : "s"}`)}`,
+				0,
+				0,
+			);
+		},
+
+		renderResult(result, _options, theme) {
+			const details = result.details;
+			if (!details) return new Text(theme.fg("warning", "ask_question returned no details"), 0, 0);
+			return new Text(
+				formatResult(details, (text) => theme.bold(text)),
+				0,
+				0,
+			);
+		},
+	});
+}
+
+export default function qnaExtension(pi: ExtensionAPI): void {
+	let qnaActive = false;
+
+	function syncQnaTools(): void {
+		const active = new Set(pi.getActiveTools());
+		if (qnaActive) active.add(TOOL_ASK_QUESTION);
+		else active.delete(TOOL_ASK_QUESTION);
+		pi.setActiveTools([...active]);
+	}
+
+	pi.registerTool(createAskQuestionTool(pi));
+
+	pi.on("session_start", () => {
+		qnaActive = false;
+		syncQnaTools();
+	});
+	pi.on("tool_result", (event) => {
+		if (event.toolName !== TOOL_ASK_QUESTION) return;
+		qnaActive = false;
+		syncQnaTools();
+	});
+	pi.on("agent_end", () => {
+		qnaActive = false;
+		syncQnaTools();
+	});
+
+	pi.registerCommand("qna", {
+		description:
+			"Ask the agent to re-ask its last question with structured choices. Optional text is framing context.",
+		handler: async (args, ctx) => {
+			if (!ctx.isIdle()) {
+				ctx.ui.notify("Agent is busy", "warning");
+				return;
+			}
+
+			qnaActive = true;
+			syncQnaTools();
+			pi.sendMessage(
+				{ customType: "tau.qna", content: buildQnaPrompt(args), display: false },
+				{ triggerTurn: true },
+			);
+		},
+	});
+}
+
+function formatResult(result: QnaResult, formatLabel: (text: string) => string = (text) => text): string {
+	const sections = [
+		Object.values(result.answers)
+			.map((answer, index) => formatAnswer(answer, index, formatLabel))
+			.join("\n\n"),
+	];
+	const additionalContext = result.additionalContext?.trim();
+	if (additionalContext) sections.push(`${formatLabel("Additional context:")}\n${additionalContext}`);
+	return `\n${sections.join("\n\n")}`;
+}
+
+function formatAnswer(
+	answer: QnaResult["answers"][string],
+	index: number,
+	formatLabel: (text: string) => string,
+): string {
+	if (answer.kind !== "multi") {
+		return [
+			`${index + 1}. ${formatLabel(answer.prompt)}`,
+			...formatRecommendation(answer, formatLabel),
+			formatSingleAnswer(answer, formatLabel),
+		].join("\n");
+	}
+
+	return [
+		`${index + 1}. ${formatLabel(answer.prompt)}`,
+		...formatRecommendation(answer, formatLabel),
+		`   ${formatLabel("Answer:")}`,
+		formatMultiAnswer(answer),
+	].join("\n");
+}
+
+function formatRecommendation(answer: QnaResult["answers"][string], formatLabel: (text: string) => string): string[] {
+	if (!answer.recommendation) return [];
+	const recommendation = answer.recommendation.labels;
+	return [
+		...(recommendation.length === 1
+			? [`   ${formatLabel("Recommendation:")} ${recommendation[0]}`]
+			: [`   ${formatLabel("Recommendation:")}`, ...recommendation.map((label) => `   - ${label}`)]),
+		`   ${formatLabel("Reason:")} ${answer.recommendation.reason}`,
+	];
+}
+
+function formatSingleAnswer(answer: QnaResult["answers"][string], formatLabel: (text: string) => string): string {
+	const value = answer.kind === "input" ? answer.input : answer.labels[0];
+	const answerLine = `   ${formatLabel("Answer:")} ${value || "_Skipped_"}`;
+	return [answerLine, ...formatNotes(answer, "   ", answer.values[0])].join("\n");
+}
+
+function formatMultiAnswer(answer: QnaResult["answers"][string]): string {
+	if (answer.labels.length === 0) return "   _Skipped_";
+	return answer.labels
+		.map((label, index) => [`   - ${label}`, ...formatNotes(answer, "     ", answer.values[index])].join("\n"))
+		.join("\n");
+}
+
+function formatNotes(answer: QnaResult["answers"][string], indent: string, value?: string): string[] {
+	const notes = value
+		? answer.optionNotes?.[value]
+			? [answer.optionNotes[value]]
+			: []
+		: Object.values(answer.optionNotes ?? {});
+	return notes.flatMap((note) => note.split("\n").map((line) => `${indent}└─ ${line}`));
+}

package/extensions/qna/inline-editor-row.ts

@@ -0,0 +1,56 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Editor, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+export function renderInlineEditor(prefix: string, editor: Editor, width: number): string[] {
+	const available = Math.max(1, width - visibleWidth(prefix));
+	const lines = editorContentLines(editor.render(available));
+	const contentLines = lines.length ? lines : [""];
+	const continuation = " ".repeat(visibleWidth(prefix));
+	return contentLines.map((line, index) =>
+		truncateToWidth(`${index === 0 ? prefix : continuation}${line}`, width, ""),
+	);
+}
+
+export function renderNoteEditor(lines: string[], editor: Editor, width: number, theme: Theme, indent: string): void {
+	const prefix = `${indent}${theme.fg("muted", "└─ ")}`;
+	const available = Math.max(1, width - visibleWidth(prefix));
+	const editorLines = editorContentLines(editor.render(available));
+	const contentLines = editorLines.length ? editorLines : [""];
+	lines.push(truncateToWidth(`${prefix}${contentLines[0] ?? ""}`, width, ""));
+	const continuation = " ".repeat(visibleWidth(prefix));
+	for (const line of contentLines.slice(1)) lines.push(truncateToWidth(`${continuation}${line}`, width, ""));
+}
+
+export function pushSavedNote(lines: string[], note: string, width: number, theme: Theme, indent: string): void {
+	for (const line of wrapWithPrefix(`${indent}${theme.fg("muted", "└─ ")}`, theme.fg("muted", note), width)) {
+		lines.push(line);
+	}
+}
+
+export function wrapWithPrefix(prefix: string, text: string, width: number): string[] {
+	const restWidth = Math.max(1, width - visibleWidth(prefix));
+	return wrapTextWithAnsi(text, restWidth).map(
+		(line, index) => `${index === 0 ? prefix : " ".repeat(visibleWidth(prefix))}${line}`,
+	);
+}
+
+function editorContentLines(lines: string[]): string[] {
+	if (lines.length <= 2) return lines;
+	return lines.slice(1).filter((line) => !isEditorBorderLine(line));
+}
+
+function isEditorBorderLine(line: string): boolean {
+	const text = stripAnsi(line).trim();
+	return /^[┌┐└┘─]+$/.test(text) || /^─── [↑↓] \d+ more ─*$/.test(text);
+}
+
+function stripAnsi(text: string): string {
+	let result = text;
+	while (true) {
+		const start = result.indexOf("\u001b[");
+		if (start === -1) return result;
+		const end = result.indexOf("m", start + 2);
+		if (end === -1) return result;
+		result = result.slice(0, start) + result.slice(end + 1);
+	}
+}