@shanepadgett/tau-agent 0.1.0

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

@@ -0,0 +1,89 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Focusable, Input, Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { renderQuestionPrompt } from "./body-render.ts";
+import { getAnswer, type NormalizedQuestion, type QnaState, saveInputAnswer } from "./model.ts";
+
+export class InputQuestionBody implements Focusable {
+	private readonly theme: Theme;
+	private readonly getState: () => QnaState;
+	private readonly setState: (state: QnaState) => void;
+	private readonly advance: () => void;
+	private readonly inputs = new Map<string, Input>();
+	private activeQuestionId: string | undefined;
+	private _focused = false;
+
+	constructor(theme: Theme, getState: () => QnaState, setState: (state: QnaState) => void, advance: () => void) {
+		this.theme = theme;
+		this.getState = getState;
+		this.setState = setState;
+		this.advance = advance;
+	}
+
+	get focused(): boolean {
+		return this._focused;
+	}
+
+	set focused(value: boolean) {
+		this._focused = value;
+		for (const [id, input] of this.inputs) input.focused = value && id === this.activeQuestionId;
+	}
+
+	forQuestion(question: NormalizedQuestion): this {
+		this.activeQuestionId = question.id;
+		this.focused = this._focused;
+		return this;
+	}
+
+	handleInput(data: string): void {
+		const question = this.currentQuestion();
+		if (!question) return;
+		const input = this.getQuestionInput(question);
+		if (matchesKey(data, Key.enter)) {
+			this.setState(saveInputAnswer(this.getState(), question, input.getValue()));
+			this.advance();
+			return;
+		}
+		input.handleInput(data);
+		this.setState(saveInputAnswer(this.getState(), question, input.getValue()));
+	}
+
+	render(question: NormalizedQuestion, width: number): string[] {
+		this.activeQuestionId = question.id;
+		this.focused = this._focused;
+		const lines = renderQuestionPrompt(question, width);
+		lines.push(...renderRecommendation(question, width, this.theme));
+		if (question.recommendation) lines.push("");
+		lines.push(
+			...this.getQuestionInput(question)
+				.render(width)
+				.map((line) => truncateToWidth(line, width, "")),
+		);
+		return lines;
+	}
+
+	private currentQuestion(): NormalizedQuestion | undefined {
+		return this.getState().questions.find((question) => question.id === this.activeQuestionId);
+	}
+
+	private getQuestionInput(question: NormalizedQuestion): Input {
+		const existing = this.inputs.get(question.id);
+		if (existing) return existing;
+		const input = new Input();
+		const value = getAnswer(this.getState(), question.id).input;
+		if (value) input.handleInput(value);
+		input.focused = this._focused && this.activeQuestionId === question.id;
+		this.inputs.set(question.id, input);
+		return input;
+	}
+}
+
+export function renderRecommendation(question: NormalizedQuestion, width: number, theme: Theme): string[] {
+	if (!question.recommendation) return [];
+	const labels = question.recommendation.values.map(
+		(value) => question.options.find((option) => option.value === value)?.label ?? value,
+	);
+	return [
+		...wrapTextWithAnsi(`${theme.fg("muted", theme.bold("Recommendation: "))}${labels.join(", ")}`, width),
+		...wrapTextWithAnsi(theme.fg("muted", `${theme.bold("Reason: ")}${question.recommendation.reason}`), width),
+	];
+}

package/extensions/qna/model.ts

@@ -0,0 +1,317 @@
+export type QuestionKind = "select" | "multi" | "input" | "confirm";
+
+export interface QnaParams {
+	title?: string;
+	questions: QnaQuestionParam[];
+}
+
+export interface QnaQuestionParam {
+	id: string;
+	prompt: string;
+	kind: QuestionKind;
+	options?: QnaOption[];
+	recommendation?: QnaRecommendation;
+}
+
+export interface QnaOption {
+	value: string;
+	label: string;
+}
+
+export interface QnaRecommendation {
+	values: string[];
+	reason: string;
+}
+
+export interface NormalizedQuestion {
+	id: string;
+	label: string;
+	prompt: string;
+	kind: QuestionKind;
+	options: QnaOption[];
+	recommendation?: QnaRecommendation;
+}
+
+export interface AnswerState {
+	selected: string[];
+	custom?: string;
+	input?: string;
+	notes: Record<string, string>;
+}
+
+export interface QnaState {
+	title?: string;
+	questions: NormalizedQuestion[];
+	activeTab: number;
+	activeOption: number;
+	answers: Record<string, AnswerState>;
+	additionalContext: string;
+}
+
+export interface QnaAnswerResult {
+	kind: QuestionKind;
+	prompt: string;
+	values: string[];
+	labels: string[];
+	custom?: string;
+	input?: string;
+	optionNotes?: Record<string, string>;
+	recommendation?: QnaRecommendation & { accepted: boolean; labels: string[] };
+}
+
+export interface QnaResult {
+	answers: Record<string, QnaAnswerResult>;
+	additionalContext?: string;
+}
+
+const confirmOptions: QnaOption[] = [
+	{ value: "yes", label: "Yes" },
+	{ value: "no", label: "No" },
+];
+
+export function normalizeParams(params: QnaParams): NormalizedQuestion[] {
+	if (!Array.isArray(params.questions) || params.questions.length === 0)
+		throw new Error("ask_question requires questions");
+
+	const ids = new Set<string>();
+	return params.questions.map((question, index) => {
+		const id = clean(question.id);
+		if (!id) throw new Error(`ask_question question ${index + 1} needs id`);
+		if (ids.has(id)) throw new Error(`ask_question duplicate question id: ${id}`);
+		ids.add(id);
+
+		const prompt = clean(question.prompt);
+		if (!prompt) throw new Error(`ask_question question ${id} needs prompt`);
+
+		const kind = question.kind;
+		if (!isQuestionKind(kind)) throw new Error(`ask_question question ${id} has invalid kind`);
+
+		const options = normalizeOptions(id, kind, question.options);
+		const recommendation = normalizeRecommendation(id, kind, options, question.recommendation);
+
+		return {
+			id,
+			label: labelFromId(id, index),
+			prompt,
+			kind,
+			options,
+			recommendation,
+		};
+	});
+}
+
+export function createState(title: string | undefined, questions: NormalizedQuestion[]): QnaState {
+	return {
+		title: clean(title),
+		questions,
+		activeTab: 0,
+		activeOption: 0,
+		answers: Object.fromEntries(questions.map((question) => [question.id, { selected: [], notes: {} }])),
+		additionalContext: "",
+	};
+}
+
+export function activeQuestion(state: QnaState): NormalizedQuestion | undefined {
+	return state.questions[state.activeTab];
+}
+
+export function optionCount(question: NormalizedQuestion): number {
+	return question.options.length + (hasCustom(question) ? 1 : 0);
+}
+
+export function hasCustom(question: NormalizedQuestion): boolean {
+	return question.kind === "select" || question.kind === "multi";
+}
+
+export function moveTab(state: QnaState, direction: 1 | -1): QnaState {
+	const tabCount = state.questions.length + 1;
+	return { ...state, activeTab: (state.activeTab + direction + tabCount) % tabCount, activeOption: 0 };
+}
+
+export function moveOption(state: QnaState, direction: 1 | -1): QnaState {
+	const question = activeQuestion(state);
+	if (!question) return state;
+	const count = optionCount(question);
+	if (count === 0) return state;
+	return { ...state, activeOption: (state.activeOption + direction + count) % count };
+}
+
+export function toggleOrSelectOption(state: QnaState, question: NormalizedQuestion, value: string): QnaState {
+	const answer = getAnswer(state, question.id);
+	const selected = new Set(answer.selected);
+	if (question.kind === "multi") {
+		if (selected.has(value)) selected.delete(value);
+		else selected.add(value);
+		return putAnswer(state, question.id, { ...answer, selected: [...selected] });
+	}
+	return putAnswer(state, question.id, { ...answer, selected: [value], custom: undefined });
+}
+
+export function saveCustomAnswer(state: QnaState, question: NormalizedQuestion, value: string): QnaState {
+	const trimmed = clean(value);
+	const answer = getAnswer(state, question.id);
+	if (!trimmed) return putAnswer(state, question.id, { ...answer, custom: undefined });
+	const selected = question.kind === "select" ? [] : answer.selected;
+	return putAnswer(state, question.id, { ...answer, selected, custom: trimmed });
+}
+
+export function saveInputAnswer(state: QnaState, question: NormalizedQuestion, value: string): QnaState {
+	return putAnswer(state, question.id, { ...getAnswer(state, question.id), input: clean(value) });
+}
+
+export function saveAdditionalContext(state: QnaState, value: string): QnaState {
+	return { ...state, additionalContext: clean(value) };
+}
+
+export function saveOptionNote(state: QnaState, question: NormalizedQuestion, value: string, note: string): QnaState {
+	const answer = getAnswer(state, question.id);
+	const notes = { ...answer.notes };
+	const trimmed = clean(note);
+	if (trimmed) notes[value] = trimmed;
+	else delete notes[value];
+	return putAnswer(state, question.id, { ...answer, notes });
+}
+
+export function isAnswered(state: QnaState, question: NormalizedQuestion): boolean {
+	const answer = getAnswer(state, question.id);
+	if (question.kind === "input") return Boolean(clean(answer.input));
+	if (question.kind === "select" || question.kind === "confirm")
+		return answer.selected.length === 1 || Boolean(answer.custom);
+	return answer.selected.length > 0 || Boolean(answer.custom);
+}
+
+export function buildResult(state: QnaState): QnaResult {
+	const answers = Object.fromEntries(state.questions.map((question) => [question.id, buildAnswer(state, question)]));
+	const additionalContext = clean(state.additionalContext);
+	return additionalContext ? { answers, additionalContext } : { answers };
+}
+
+export function getAnswer(state: QnaState, questionId: string): AnswerState {
+	return state.answers[questionId] ?? { selected: [], notes: {} };
+}
+
+function buildAnswer(state: QnaState, question: NormalizedQuestion): QnaAnswerResult {
+	const answer = getAnswer(state, question.id);
+	const selectedOptions = answer.selected.map((value) => optionByValue(question, value)).filter(isOption);
+	const optionNotes = Object.fromEntries(
+		selectedOptions.flatMap((option) => {
+			const note = answer.notes[option.value];
+			return note ? [[option.value, note]] : [];
+		}),
+	);
+	const values = selectedOptions.map((option) => option.value);
+	const labels = selectedOptions.map((option) => option.label);
+	if (answer.custom) {
+		values.push(answer.custom);
+		labels.push(answer.custom);
+	}
+	if (question.kind === "input" && answer.input) {
+		values.push(answer.input);
+		labels.push(answer.input);
+	}
+
+	return dropUndefined({
+		kind: question.kind,
+		prompt: question.prompt,
+		values,
+		labels,
+		custom: answer.custom,
+		input: question.kind === "input" ? answer.input : undefined,
+		optionNotes: Object.keys(optionNotes).length ? optionNotes : undefined,
+		recommendation: question.recommendation
+			? {
+					...question.recommendation,
+					accepted: sameValues(values, question.recommendation.values),
+					labels: question.recommendation.values.map((value) => optionByValue(question, value)?.label ?? value),
+				}
+			: undefined,
+	});
+}
+
+function putAnswer(state: QnaState, questionId: string, answer: AnswerState): QnaState {
+	return { ...state, answers: { ...state.answers, [questionId]: answer } };
+}
+
+function normalizeOptions(id: string, kind: QuestionKind, options: QnaOption[] | undefined): QnaOption[] {
+	if (kind === "confirm") {
+		if (options && options.length > 0) throw new Error(`ask_question confirm question ${id} cannot provide options`);
+		return confirmOptions;
+	}
+	if (kind === "input") {
+		if (options && options.length > 0) throw new Error(`ask_question input question ${id} cannot provide options`);
+		return [];
+	}
+	if (!options || options.length === 0) throw new Error(`ask_question ${kind} question ${id} needs options`);
+
+	const values = new Set<string>();
+	return options.map((option, index) => {
+		const value = clean(option.value);
+		if (!value) throw new Error(`ask_question question ${id} option ${index + 1} needs value`);
+		if (values.has(value)) throw new Error(`ask_question question ${id} duplicate option value: ${value}`);
+		values.add(value);
+		const label = clean(option.label);
+		if (!label) throw new Error(`ask_question question ${id} option ${value} needs label`);
+		return { value, label };
+	});
+}
+
+function normalizeRecommendation(
+	id: string,
+	kind: QuestionKind,
+	options: QnaOption[],
+	recommendation: QnaRecommendation | undefined,
+): QnaRecommendation | undefined {
+	if (!recommendation) {
+		if (kind === "input") return undefined;
+		throw new Error(`ask_question ${kind} question ${id} needs recommendation`);
+	}
+	const reason = clean(recommendation.reason);
+	if (!reason) throw new Error(`ask_question question ${id} recommendation needs reason`);
+	const values = recommendation.values.map(clean).filter(Boolean);
+	if (values.length === 0) throw new Error(`ask_question question ${id} recommendation needs values`);
+	if ((kind === "select" || kind === "confirm" || kind === "input") && values.length !== 1) {
+		throw new Error(`ask_question ${kind} question ${id} recommendation needs exactly one value`);
+	}
+	if (kind === "input") return { values, reason };
+	const valid = new Set(options.map((option) => option.value));
+	const unique = new Set<string>();
+	for (const value of values) {
+		if (!valid.has(value))
+			throw new Error(`ask_question question ${id} recommendation value not in options: ${value}`);
+		if (unique.has(value)) throw new Error(`ask_question question ${id} duplicate recommendation value: ${value}`);
+		unique.add(value);
+	}
+	return { values, reason };
+}
+
+function optionByValue(question: NormalizedQuestion, value: string): QnaOption | undefined {
+	return question.options.find((option) => option.value === value);
+}
+
+function isQuestionKind(value: string): value is QuestionKind {
+	return value === "select" || value === "multi" || value === "input" || value === "confirm";
+}
+
+function isOption(value: QnaOption | undefined): value is QnaOption {
+	return value !== undefined;
+}
+
+function sameValues(left: string[], right: string[]): boolean {
+	return left.length === right.length && left.every((value) => right.includes(value));
+}
+
+function labelFromId(id: string, index: number): string {
+	const label = id
+		.replace(/[-_]+/g, " ")
+		.replace(/\b\w/g, (letter) => letter.toUpperCase())
+		.trim();
+	return label || `Q${index + 1}`;
+}
+
+function clean(value: string | undefined): string {
+	return value?.trim() ?? "";
+}
+
+function dropUndefined<T extends Record<string, unknown>>(value: T): T {
+	return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined)) as T;
+}

package/extensions/qna/panel.ts

@@ -0,0 +1,240 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, type Focusable, Key, matchesKey, type TUI } from "@earendil-works/pi-tui";
+import { bindingHint, rawHint, type ToolKeyHint } from "@shanepadgett/tau-tui";
+import { type TabItem, Tabs } from "@shanepadgett/tau-tui";
+import { ToolPanel, type ToolPanelConfig } from "@shanepadgett/tau-tui";
+import { AdditionalContextBody } from "./additional-context-body.ts";
+import { ChoiceQuestionBody } from "./choice-question-body.ts";
+import { InputQuestionBody } from "./input-question-body.ts";
+import {
+	activeQuestion,
+	buildResult,
+	isAnswered,
+	moveTab,
+	type NormalizedQuestion,
+	type QnaResult,
+	type QnaState,
+} from "./model.ts";
+
+type QnaUiResult = QnaResult | undefined;
+
+export class QnaPanel implements Component, Focusable {
+	private readonly tui: TUI;
+	private readonly done: (result: QnaUiResult) => void;
+	private readonly choiceBody: ChoiceQuestionBody;
+	private readonly inputBody: InputQuestionBody;
+	private readonly additionalContextBody: AdditionalContextBody;
+	private readonly tabs: Tabs;
+	private readonly panelConfig: ToolPanelConfig;
+	private readonly panel: ToolPanel;
+	private state: QnaState;
+	private _focused = false;
+
+	constructor(tui: TUI, theme: Theme, state: QnaState, done: (result: QnaUiResult) => void) {
+		this.tui = tui;
+		this.state = state;
+		this.done = done;
+		this.choiceBody = new ChoiceQuestionBody(
+			tui,
+			theme,
+			() => this.state,
+			(next) => this.setState(next),
+			() => this.advance(),
+		);
+		this.inputBody = new InputQuestionBody(
+			theme,
+			() => this.state,
+			(next) => this.setState(next),
+			() => this.advance(),
+		);
+		this.additionalContextBody = new AdditionalContextBody(
+			() => this.state,
+			(next) => this.setState(next),
+			() => this.submit(),
+		);
+		this.tabs = new Tabs(theme, this.tabItems(), this.activeTabId());
+		this.panelConfig = {
+			title: `qna: ${this.state.title || "Question"}`,
+			body: this.tabs,
+			footer: { kind: "hints", hints: this.footerHints() },
+		};
+		this.panel = new ToolPanel(theme, this.panelConfig);
+		this.syncFocus();
+	}
+
+	get focused(): boolean {
+		return this._focused;
+	}
+
+	set focused(value: boolean) {
+		this._focused = value;
+		this.syncFocus();
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, Key.ctrl("c"))) {
+			this.done(undefined);
+			return;
+		}
+
+		const active = this.activeBody();
+		if (this.choiceBody.isEditing()) {
+			this.choiceBody.handleInput(data);
+			this.refresh();
+			return;
+		}
+
+		if (matchesKey(data, Key.escape)) {
+			this.done(undefined);
+			return;
+		}
+		if (matchesKey(data, Key.alt("enter"))) {
+			this.submit();
+			return;
+		}
+		if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) {
+			this.setState(moveTab(this.state, 1));
+			return;
+		}
+		if (matchesKey(data, Key.shift("tab")) || matchesKey(data, Key.left)) {
+			this.setState(moveTab(this.state, -1));
+			return;
+		}
+
+		active.handleInput(data);
+		this.refresh();
+	}
+
+	render(width: number): string[] {
+		return this.panel.render(width);
+	}
+
+	invalidate(): void {
+		this.panel.invalidate();
+	}
+
+	private tabItems(): TabItem[] {
+		return [
+			...this.state.questions.map((question, index) => ({
+				id: question.id,
+				label: `${question.label}${isAnswered(this.state, question) ? "•" : ""}`,
+				body: this.questionComponent(question, index),
+			})),
+			{
+				id: "additional-context",
+				label: `Additional Context${this.state.additionalContext ? "•" : ""}`,
+				body: this.additionalContextBody,
+			},
+		];
+	}
+
+	private questionComponent(question: NormalizedQuestion, index: number): Component {
+		return {
+			render: (width) =>
+				question.kind === "input"
+					? this.inputBody.render(question, width)
+					: this.choiceBody.render(question, width),
+			invalidate: () => {},
+			handleInput: (data) => {
+				this.state = { ...this.state, activeTab: index };
+				if (question.kind === "input") this.inputBody.forQuestion(question).handleInput(data);
+				else this.choiceBody.forQuestion(question).handleInput(data);
+			},
+		};
+	}
+
+	private activeBody(): { handleInput(data: string): void; getKeyHints: () => readonly ToolKeyHint[] } {
+		if (this.isAdditionalContextActive()) {
+			return {
+				handleInput: (data) => this.additionalContextBody.handleInput(data),
+				getKeyHints: () => this.additionalContextHints(),
+			};
+		}
+		const question = activeQuestion(this.state);
+		if (question?.kind === "input") {
+			this.inputBody.forQuestion(question);
+			return {
+				handleInput: (data) => this.inputBody.handleInput(data),
+				getKeyHints: () => this.inputHints(),
+			};
+		}
+		if (question) {
+			this.choiceBody.forQuestion(question);
+			return {
+				handleInput: (data) => this.choiceBody.handleInput(data),
+				getKeyHints: () => this.choiceHints(),
+			};
+		}
+		return {
+			handleInput: (data) => this.additionalContextBody.handleInput(data),
+			getKeyHints: () => this.additionalContextHints(),
+		};
+	}
+
+	private setState(state: QnaState): void {
+		this.state = state;
+		this.choiceBody.closeInactiveEditors();
+		this.tabs.setTabs(this.tabItems());
+		this.tabs.setActiveId(this.activeTabId());
+		this.syncFocus();
+		this.refresh();
+	}
+
+	private advance(): void {
+		if (this.state.activeTab < this.state.questions.length) {
+			this.setState(moveTab(this.state, 1));
+			return;
+		}
+		this.submit();
+	}
+
+	private submit(): void {
+		this.done(buildResult(this.state));
+	}
+
+	private syncFocus(): void {
+		this.choiceBody.focused = false;
+		this.inputBody.focused = false;
+		this.additionalContextBody.focused = false;
+		if (!this._focused) return;
+		if (this.isAdditionalContextActive()) this.additionalContextBody.focused = true;
+		else if (activeQuestion(this.state)?.kind === "input") this.inputBody.focused = true;
+		else this.choiceBody.focused = true;
+	}
+
+	private footerHints(): readonly ToolKeyHint[] {
+		return [
+			...this.tabs.getKeyHints(),
+			...this.activeBody().getKeyHints(),
+			rawHint("Alt+Enter", "submit"),
+			bindingHint("tui.select.cancel", "abort"),
+		];
+	}
+
+	private inputHints(): readonly ToolKeyHint[] {
+		return [bindingHint("tui.input.submit", "next")];
+	}
+
+	private additionalContextHints(): readonly ToolKeyHint[] {
+		return [bindingHint("tui.input.submit", "submit")];
+	}
+
+	private choiceHints(): readonly ToolKeyHint[] {
+		return this.choiceBody.keyHints();
+	}
+
+	private refresh(): void {
+		this.panelConfig.footer = { kind: "hints", hints: this.footerHints() };
+		this.tui.requestRender();
+	}
+
+	private activeTabId(): string {
+		return this.isAdditionalContextActive()
+			? "additional-context"
+			: (activeQuestion(this.state)?.id ?? "additional-context");
+	}
+
+	private isAdditionalContextActive(): boolean {
+		return this.state.activeTab === this.state.questions.length;
+	}
+}

package/extensions/qna/ui.ts

@@ -0,0 +1,16 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { createState, type NormalizedQuestion, type QnaResult } from "./model.ts";
+import { QnaPanel } from "./panel.ts";
+
+type QnaUiResult = QnaResult | undefined;
+
+export function runQnaUi(
+	tui: TUI,
+	theme: Theme,
+	title: string | undefined,
+	questions: NormalizedQuestion[],
+	done: (result: QnaUiResult) => void,
+): Component {
+	return new QnaPanel(tui, theme, createState(title, questions), done);
+}

package/extensions/reference/README.md

@@ -0,0 +1,47 @@
+# Reference
+
+Select local reference repositories, add new ones, and send a prompt that points Tau at them.
+
+## Usage
+
+```text
+/reference
+/reference new <git-url>
+```
+
+## Behavior
+
+- Stores references in `~/.local/share/tau-agent/references/`.
+- `/reference` opens a TUI picker.
+- `n` adds a new reference from a git URL, showing clone progress in the list as `↓ 37%`.
+- New references clone the remote default branch.
+- `b` switches the highlighted reference to another branch.
+- `u` runs `git pull --ff-only --quiet` in each reference without closing the picker, showing `…`, `✓`, or `!` next to each name.
+- `o` opens the highlighted reference in an editor. Defaults to `$VISUAL`, `$EDITOR`, then `code`; settings can force `code` or `zed`.
+- `d` deletes the selected references from disk (with confirm). Disabled with nothing selected.
+- `f` filters references by name, branch, or path. Enter closes the filter; Esc clears/closes it.
+- Space selects references; Enter opens an editor for the request.
+- Sends the request with selected reference paths in the chat.
+
+## Settings
+
+```json
+{
+  "extensions": {
+    "reference": {
+      "editor": "default",
+      "branchChoices": 5
+    }
+  }
+}
+```
+
+`editor` can be `default`, `code`, or `zed`.
+`branchChoices` controls how many branches are shown when switching branches.
+
+## Limits
+
+- Requires TUI mode for the picker.
+- `/reference new <git-url>` works without the reference picker.
+- Uses the git URL basename as the folder name.
+- References are treated as read-only examples by the generated prompt.