@narumitw/pi-btw 0.20.0 → 0.28.0

package/src/btw.ts

@@ -1,84 +1,36 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import type {
-	Api,
-	AssistantMessage,
-	Context,
-	Model,
-	SimpleStreamOptions,
-	UserMessage,
-} from "@earendil-works/pi-ai";
-// pi-ai 0.79 exports completeSimple from the root; 0.80 moved it to the compat subpath.
-type CompleteSimpleFunction = <TApi extends Api>(
-	model: Model<TApi>,
-	context: Context,
-	options?: SimpleStreamOptions,
-) => Promise<AssistantMessage>;
-
-function hasCompleteSimple(value: unknown): value is { completeSimple: CompleteSimpleFunction } {
-	return (
-		typeof value === "object" &&
-		value !== null &&
-		typeof Reflect.get(value, "completeSimple") === "function"
-	);
-}
-
-type ModuleImporter = (moduleId: string) => Promise<unknown>;
-
-export async function loadCompleteSimple(
-	importModule: ModuleImporter = (moduleId) => import(moduleId),
-): Promise<CompleteSimpleFunction> {
-	let importError: unknown;
-	for (const moduleId of ["@earendil-works/pi-ai/compat", "@earendil-works/pi-ai"]) {
-		try {
-			const module = await importModule(moduleId);
-			if (hasCompleteSimple(module)) return module.completeSimple;
-		} catch (error: unknown) {
-			importError = error;
-		}
-	}
-
-	throw new Error("@earendil-works/pi-ai does not export completeSimple", {
-		cause: importError,
-	});
-}
-
-const completeSimple = await loadCompleteSimple();
+import type { Api, Model } from "@earendil-works/pi-ai";
 import {
 	BorderedLoader,
-	DynamicBorder,
-	getAgentDir,
-	getMarkdownTheme,
 	type ExtensionAPI,
 	type ExtensionCommandContext,
-	type Theme,
+	getAgentDir,
 } from "@earendil-works/pi-coding-agent";
 import {
-	Key,
-	Markdown,
-	matchesKey,
-	truncateToWidth,
-	visibleWidth,
-	type Component,
-	type TUI,
-} from "@earendil-works/pi-tui";
+	BTW_THINKING_LEVELS,
+	type BtwThinkingLevel,
+	completeSideThreadTurn,
+	createSideThread,
+	type SideQuestionAuth,
+	type SideThread,
+} from "./side-thread.js";
+import {
+	BtwAnsweringView,
+	BtwTranscriptPager,
+	type TranscriptPagerAction,
+} from "./transcript-pager.js";
+
+export {
+	BTW_THINKING_LEVELS,
+	type BtwThinkingLevel,
+	buildUserPrompt,
+	completeSideQuestion,
+	loadCompleteSimple,
+} from "./side-thread.js";
 
 const MAX_CONTEXT_CHARS = 40_000;
-const ANSWER_CHROME_LINES = 4;
-// Pi renders a spacer above the custom editor and a two-line built-in footer below it.
-const ANSWER_RESERVED_APP_LINES = 3;
 export const BTW_SETTINGS_FILE = "pi-btw.json";
-export const BTW_THINKING_LEVELS = [
-	"off",
-	"minimal",
-	"low",
-	"medium",
-	"high",
-	"xhigh",
-	"max",
-] as const;
-
-export type BtwThinkingLevel = (typeof BTW_THINKING_LEVELS)[number];
 
 export interface BtwSettings {
 	model?: string;
@@ -95,15 +47,11 @@ interface LoadBtwThinkingLevelOptions {
 	warn?: (message: string) => void;
 }
 
-interface SideQuestionAuth {
-	apiKey?: string;
-	headers?: Record<string, string>;
-	env?: Record<string, string>;
-}
-
 interface BtwModelRegistry {
 	find(provider: string, modelId: string): Model<Api> | undefined;
-	getApiKeyAndHeaders(model: Model<Api>): Promise<
+	getApiKeyAndHeaders(
+		model: Model<Api>,
+	): Promise<
 		| { ok: true; apiKey?: string; headers?: Record<string, string>; env?: Record<string, string> }
 		| { ok: false; error: string }
 	>;
@@ -116,21 +64,11 @@ interface ResolveBtwModelOptions {
 	warn?: (message: string) => void;
 }
 
-interface ResolvedBtwModel {
+export interface ResolvedBtwModel {
 	model: Model<Api>;
 	auth: SideQuestionAuth;
 }
 
-interface CompleteSideQuestionOptions {
-	model: Model<Api>;
-	question: string;
-	conversationContext: string;
-	thinkingLevel: BtwThinkingLevel;
-	auth: SideQuestionAuth;
-	signal?: AbortSignal;
-	completeSimple?: CompleteSimpleFunction;
-}
-
 export function normalizeBtwSettings(value: unknown): BtwSettings | undefined {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
 
@@ -167,14 +105,19 @@ export async function resolveBtwModel({
 		const fallback = currentModel
 			? `${currentModel.provider}/${currentModel.id}`
 			: "the current model";
-		const reference = parseBtwModelReference(settings.model)!;
+		const reference = parseBtwModelReference(settings.model);
+		if (!reference) {
+			warn?.(`pi-btw model ${settings.model} is invalid; falling back to ${fallback}.`);
+			return resolveBtwModel({ settings: {}, currentModel, modelRegistry, warn });
+		}
 		const configuredModel = modelRegistry.find(reference.provider, reference.modelId);
 		if (!configuredModel) {
 			warn?.(`pi-btw model ${settings.model} was not found; falling back to ${fallback}.`);
 		} else {
 			const sameAsCurrent =
 				configuredModel === currentModel ||
-				(configuredModel.provider === currentModel?.provider && configuredModel.id === currentModel.id);
+				(configuredModel.provider === currentModel?.provider &&
+					configuredModel.id === currentModel.id);
 			const fallbackAction = sameAsCurrent
 				? "no distinct current model is available"
 				: `falling back to ${fallback}`;
@@ -182,9 +125,7 @@ export async function resolveBtwModel({
 				const auth = await modelRegistry.getApiKeyAndHeaders(configuredModel);
 				if (auth.ok && hasRequestAuth(auth)) return { model: configuredModel, auth };
 				const reason = auth.ok ? "has no request credentials" : auth.error;
-				warn?.(
-					`pi-btw model ${settings.model} is unavailable (${reason}); ${fallbackAction}.`,
-				);
+				warn?.(`pi-btw model ${settings.model} is unavailable (${reason}); ${fallbackAction}.`);
 			} catch (error: unknown) {
 				warn?.(
 					`pi-btw model ${settings.model} credentials failed (${formatError(error)}); ${fallbackAction}.`,
@@ -248,38 +189,6 @@ export async function loadBtwThinkingLevel(
 	return currentThinkingLevel;
 }
 
-export async function completeSideQuestion({
-	model,
-	question,
-	conversationContext,
-	thinkingLevel,
-	auth,
-	signal,
-	completeSimple: runCompleteSimple = completeSimple,
-}: CompleteSideQuestionOptions): Promise<AssistantMessage> {
-	const userMessage: UserMessage = {
-		role: "user",
-		content: [
-			{
-				type: "text",
-				text: buildUserPrompt(question, conversationContext),
-			},
-		],
-		timestamp: Date.now(),
-	};
-	const streamOptions: SimpleStreamOptions = {
-		apiKey: auth.apiKey,
-		headers: auth.headers,
-		env: auth.env,
-		signal,
-	};
-	if (thinkingLevel !== "off") {
-		(streamOptions as unknown as { reasoning?: BtwThinkingLevel }).reasoning = thinkingLevel;
-	}
-
-	return runCompleteSimple(model, { systemPrompt: SYSTEM_PROMPT, messages: [userMessage] }, streamOptions);
-}
-
 function isBtwThinkingLevel(value: unknown): value is BtwThinkingLevel {
 	return BTW_THINKING_LEVELS.includes(value as BtwThinkingLevel);
 }
@@ -292,52 +201,17 @@ function formatError(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
 
-const SYSTEM_PROMPT = `You answer quick side questions for a coding-agent user.
-
-Use the provided conversation context only as background. Answer the user's side question directly and concisely. Do not claim to have changed files, run tools, or affected the main task. If the context is insufficient, say what is unknown and give the best next step.`;
-
-type MessageContentBlock = {
-	type?: string;
-	text?: string;
-	name?: string;
-	arguments?: unknown;
-	result?: unknown;
-};
-
-type SessionMessage = {
-	role?: string;
-	content?: unknown;
-	stopReason?: string;
-};
-
-type SessionEntry = {
-	type: string;
-	message?: SessionMessage;
-};
-
 export default function btw(pi: ExtensionAPI) {
 	pi.registerCommand("btw", {
 		description: "Ask a quick side question without adding it to the main conversation",
 		handler: async (args, ctx) => {
 			const question = args.trim();
-			if (!question) {
-				ctx.ui.notify("Usage: /btw <your side question>", "warning");
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("/btw requires interactive TUI mode", "error");
 				return;
 			}
 
-			if (!ctx.hasUI) {
-				ctx.ui.notify("/btw requires interactive mode", "error");
-				return;
-			}
-
-			const settingsResult = await readBtwSettings();
-			let settings: BtwSettings = {};
-			if (settingsResult.kind === "loaded") {
-				settings = settingsResult.settings;
-			} else if (settingsResult.kind === "invalid") {
-				ctx.ui.notify(`pi-btw settings ignored: ${settingsResult.reason}`, "warning");
-			}
-
+			const settings = await loadSettingsForCommand(ctx);
 			const resolution = await resolveBtwModelWithLoader(settings, ctx);
 			if (resolution.kind === "cancelled") {
 				ctx.ui.notify("Cancelled", "info");
@@ -348,18 +222,25 @@ export default function btw(pi: ExtensionAPI) {
 				return;
 			}
 
-			const thinkingLevel = settings.thinkingLevel ?? pi.getThinkingLevel();
-			const answer = await askSideQuestion(question, resolution.selected, thinkingLevel, ctx);
-			if (answer === undefined) {
-				ctx.ui.notify("Cancelled", "info");
-				return;
-			}
-
-			await showAnswer(question, answer, ctx);
+			await runBtwThread({
+				initialQuestion: question || undefined,
+				selected: resolution.selected,
+				thinkingLevel: settings.thinkingLevel ?? pi.getThinkingLevel(),
+				ctx,
+			});
 		},
 	});
 }
 
+async function loadSettingsForCommand(ctx: ExtensionCommandContext): Promise<BtwSettings> {
+	const settingsResult = await readBtwSettings();
+	if (settingsResult.kind === "loaded") return settingsResult.settings;
+	if (settingsResult.kind === "invalid") {
+		ctx.ui.notify(`pi-btw settings ignored: ${settingsResult.reason}`, "warning");
+	}
+	return {};
+}
+
 type ModelResolutionOutcome =
 	| { kind: "cancelled" }
 	| { kind: "unavailable" }
@@ -371,9 +252,10 @@ async function resolveBtwModelWithLoader(
 ): Promise<ModelResolutionOutcome> {
 	return ctx.ui.custom<ModelResolutionOutcome>((tui, theme, _keybindings, done) => {
 		const loader = new BorderedLoader(tui, theme, "Resolving /btw model credentials...");
-		let cancelled = false;
+		let settled = false;
 		loader.onAbort = () => {
-			cancelled = true;
+			if (settled) return;
+			settled = true;
 			done({ kind: "cancelled" });
 		};
 
@@ -382,235 +264,146 @@ async function resolveBtwModelWithLoader(
 			currentModel: ctx.model,
 			modelRegistry: ctx.modelRegistry,
 			warn: (message) => {
-				if (!cancelled) ctx.ui.notify(message, "warning");
+				if (!settled) ctx.ui.notify(message, "warning");
 			},
-		}).then((selected) => {
-			if (cancelled) return;
-			done(selected ? { kind: "selected", selected } : { kind: "unavailable" });
-		});
-
-		return loader;
-	});
-}
-
-async function askSideQuestion(
-	question: string,
-	selected: ResolvedBtwModel,
-	thinkingLevel: BtwThinkingLevel,
-	ctx: ExtensionCommandContext,
-): Promise<string | undefined> {
-	return ctx.ui.custom<string | undefined>((tui, theme, _keybindings, done) => {
-		const loader = new BorderedLoader(
-			tui,
-			theme,
-			`Answering /btw with ${selected.model.provider}/${selected.model.id}...`,
-		);
-		loader.onAbort = () => done(undefined);
-
-		const ask = async () => {
-			const conversationContext = buildConversationContext(ctx.sessionManager.getBranch());
-			const response = await completeSideQuestion({
-				model: selected.model,
-				question,
-				conversationContext,
-				thinkingLevel,
-				auth: selected.auth,
-				signal: loader.signal,
-			});
-
-			if (response.stopReason === "aborted") {
-				return undefined;
-			}
-
-			const text = response.content
-				.filter((content): content is { type: "text"; text: string } => content.type === "text")
-				.map((content) => content.text)
-				.join("\n")
-				.trim();
-
-			return text || "No response received.";
-		};
-
-		ask()
-			.then(done)
-			.catch((error: unknown) => {
-				const message = error instanceof Error ? error.message : String(error);
-				done(`Error: ${message}`);
+		})
+			.then((selected) => {
+				if (settled) return;
+				settled = true;
+				done(selected ? { kind: "selected", selected } : { kind: "unavailable" });
+			})
+			.catch(() => {
+				if (settled) return;
+				settled = true;
+				done({ kind: "unavailable" });
 			});
 
 		return loader;
 	});
 }
 
-async function showAnswer(question: string, answer: string, ctx: ExtensionCommandContext) {
-	await ctx.ui.custom((tui, theme, _keybindings, done) => {
-		return new BtwAnswerPager(tui, theme, question, answer, () => done(undefined));
-	});
+interface RunBtwThreadDependencies {
+	ask?: typeof askThreadQuestion;
+	interact?: typeof showThreadComposer;
 }
 
-class BtwAnswerPager implements Component {
-	private readonly tui: TUI;
-	private readonly theme: Theme;
-	private readonly title: string;
-	private readonly onClose: () => void;
-	private readonly topBorder: DynamicBorder;
-	private readonly bottomBorder: DynamicBorder;
-	private readonly markdown: Markdown;
-	private scrollOffset = 0;
-	private lastContentLineCount = 0;
-	private lastViewportHeight = 1;
-
-	constructor(tui: TUI, theme: Theme, question: string, answer: string, onClose: () => void) {
-		this.tui = tui;
-		this.theme = theme;
-		this.title = sanitizeSingleLine(`/btw ${question}`);
-		this.onClose = onClose;
-		const borderColor = (text: string) => this.theme.fg("warning", text);
-		this.topBorder = new DynamicBorder(borderColor);
-		this.bottomBorder = new DynamicBorder(borderColor);
-		this.markdown = new Markdown(answer, 1, 1, getMarkdownTheme());
-	}
+interface RunBtwThreadOptions {
+	initialQuestion?: string;
+	selected: ResolvedBtwModel;
+	thinkingLevel: BtwThinkingLevel;
+	ctx: ExtensionCommandContext;
+	dependencies?: RunBtwThreadDependencies;
+}
 
-	render(width: number): string[] {
-		const viewportHeight = this.getViewportHeight();
-		const contentLines = this.markdown.render(width);
-		this.lastContentLineCount = contentLines.length;
-		this.lastViewportHeight = viewportHeight;
-		this.clampScrollOffset();
-
-		const visibleContent = contentLines.slice(
-			this.scrollOffset,
-			this.scrollOffset + viewportHeight,
-		);
-
-		return [
-			...this.topBorder.render(width),
-			this.renderTitle(width),
-			...visibleContent,
-			this.renderFooter(width),
-			...this.bottomBorder.render(width),
-		];
-	}
+export async function runBtwThread({
+	initialQuestion,
+	selected,
+	thinkingLevel,
+	ctx,
+	dependencies = {},
+}: RunBtwThreadOptions): Promise<void> {
+	const ask = dependencies.ask ?? askThreadQuestion;
+	const interact = dependencies.interact ?? showThreadComposer;
+	const thread = createSideThread(buildConversationContext(ctx.sessionManager.getBranch()));
+	let pendingQuestion = initialQuestion;
+
+	while (true) {
+		if (!pendingQuestion) {
+			const action = await interact(thread, thread.turns.length > 0, ctx);
+			if (action.kind === "close") return;
+			pendingQuestion = action.question;
+		}
 
-	handleInput(data: string): void {
-		if (this.matchesCloseKey(data)) {
-			this.onClose();
+		const result = await ask(thread, pendingQuestion, selected, thinkingLevel, ctx);
+		if (result.kind === "aborted") {
+			ctx.ui.notify("Cancelled", "info");
 			return;
 		}
-
-		if (matchesKey(data, Key.up) || matchesKey(data, "k")) {
-			this.scrollBy(-1);
-		} else if (matchesKey(data, Key.down) || matchesKey(data, "j")) {
-			this.scrollBy(1);
-		} else if (
-			matchesKey(data, Key.pageUp) ||
-			matchesKey(data, Key.shift(Key.space)) ||
-			matchesKey(data, Key.ctrl("b"))
-		) {
-			this.scrollBy(-this.lastViewportHeight);
-		} else if (
-			matchesKey(data, Key.pageDown) ||
-			matchesKey(data, Key.space) ||
-			matchesKey(data, Key.ctrl("f"))
-		) {
-			this.scrollBy(this.lastViewportHeight);
-		} else if (matchesKey(data, Key.ctrl("u"))) {
-			this.scrollBy(-this.getHalfPageHeight());
-		} else if (matchesKey(data, Key.ctrl("d"))) {
-			this.scrollBy(this.getHalfPageHeight());
-		} else if (matchesKey(data, Key.home)) {
-			this.scrollOffset = 0;
-		} else if (matchesKey(data, Key.end)) {
-			this.scrollOffset = this.getMaxScrollOffset();
+		if (result.kind === "error") {
+			thread.turns.push({
+				kind: "error",
+				question: pendingQuestion,
+				answer: result.message,
+			});
 		}
-	}
-
-	invalidate(): void {
-		this.topBorder.invalidate();
-		this.bottomBorder.invalidate();
-		this.markdown.invalidate();
-	}
 
-	private matchesCloseKey(data: string): boolean {
-		return (
-			matchesKey(data, "q") ||
-			matchesKey(data, Key.escape) ||
-			matchesKey(data, Key.enter) ||
-			matchesKey(data, Key.return) ||
-			matchesKey(data, Key.ctrl("c"))
-		);
-	}
-
-	private renderTitle(width: number): string {
-		return truncateToWidth(this.theme.fg("warning", this.theme.bold(this.title)), width);
-	}
-
-	private renderFooter(width: number): string {
-		const progress = this.formatProgress();
-		const hints = "↑↓/j/k scroll • PgUp/PgDn page • Home/End jump • q/Esc close";
-		const progressWidth = visibleWidth(progress);
-		const footer =
-			progressWidth + 3 >= width
-				? truncateToWidth(progress, width)
-				: `${truncateToWidth(hints, width - progressWidth - 3)} • ${progress}`;
-		return this.theme.fg("dim", footer);
-	}
-
-	private formatProgress(): string {
-		const total = this.lastContentLineCount;
-		if (total === 0) return "100% 0-0/0";
-
-		const maxScroll = this.getMaxScrollOffset();
-		const percent = maxScroll === 0 ? 100 : Math.round((this.scrollOffset / maxScroll) * 100);
-		const firstLine = this.scrollOffset + 1;
-		const lastLine = Math.min(total, this.scrollOffset + this.lastViewportHeight);
-
-		return `${percent}% ${firstLine}-${lastLine}/${total}`;
-	}
-
-	private scrollBy(delta: number): void {
-		this.scrollOffset += delta;
-		this.clampScrollOffset();
-	}
-
-	private clampScrollOffset(): void {
-		this.scrollOffset = Math.max(0, Math.min(this.scrollOffset, this.getMaxScrollOffset()));
-	}
-
-	private getMaxScrollOffset(): number {
-		return Math.max(0, this.lastContentLineCount - this.lastViewportHeight);
+		pendingQuestion = undefined;
 	}
+}
 
-	private getViewportHeight(): number {
-		return Math.max(1, this.tui.terminal.rows - ANSWER_CHROME_LINES - ANSWER_RESERVED_APP_LINES);
-	}
+async function askThreadQuestion(
+	thread: SideThread,
+	question: string,
+	selected: ResolvedBtwModel,
+	thinkingLevel: BtwThinkingLevel,
+	ctx: ExtensionCommandContext,
+) {
+	return ctx.ui.custom<Awaited<ReturnType<typeof completeSideThreadTurn>>>(
+		(tui, theme, _keybindings, done) => {
+			let settled = false;
+			const view = new BtwAnsweringView(tui, theme, thread.turns, question, () => {
+				if (settled) return;
+				settled = true;
+				done({ kind: "aborted" });
+			});
+			completeSideThreadTurn({
+				thread,
+				question,
+				model: selected.model,
+				thinkingLevel,
+				auth: selected.auth,
+				signal: view.signal,
+			}).then((result) => {
+				if (settled) return;
+				settled = true;
+				view.finish();
+				done(result);
+			});
+			return view;
+		},
+	);
+}
 
-	private getHalfPageHeight(): number {
-		return Math.max(1, Math.ceil(this.lastViewportHeight / 2));
-	}
+async function showThreadComposer(
+	thread: SideThread,
+	startAtBottom: boolean,
+	ctx: ExtensionCommandContext,
+): Promise<TranscriptPagerAction> {
+	return ctx.ui.custom<TranscriptPagerAction>(
+		(tui, theme, _keybindings, done) =>
+			new BtwTranscriptPager(tui, theme, thread.turns, done, { startAtBottom }),
+	);
 }
 
 export function sanitizeSingleLine(text: string) {
-	return text
-		.replace(/[\r\n\t]/g, " ")
-		.replace(/[\u0000-\u001f\u007f-\u009f]/g, "")
+	return [...text.replace(/[\r\n\t]/g, " ")]
+		.filter((character) => {
+			const code = character.charCodeAt(0);
+			return code > 31 && (code < 127 || code > 159);
+		})
+		.join("")
 		.replace(/ +/g, " ")
 		.trim();
 }
 
-export function buildUserPrompt(question: string, conversationContext: string) {
-	return [
-		"Answer this side question without modifying the main conversation.",
-		"",
-		"<side_question>",
-		question,
-		"</side_question>",
-		"",
-		"<conversation_context>",
-		conversationContext || "No prior conversation context was available.",
-		"</conversation_context>",
-	].join("\n");
-}
+type MessageContentBlock = {
+	type?: string;
+	text?: string;
+	name?: string;
+	arguments?: unknown;
+	result?: unknown;
+};
+
+type SessionMessage = {
+	role?: string;
+	content?: unknown;
+	stopReason?: string;
+};
+
+type SessionEntry = {
+	type: string;
+	message?: SessionMessage;
+};
 
 export function buildConversationContext(entries: readonly SessionEntry[]) {
 	const sections: string[] = [];
@@ -636,18 +429,12 @@ export function buildConversationContext(entries: readonly SessionEntry[]) {
 }
 
 function extractContentLines(content: unknown): string[] {
-	if (typeof content === "string") {
-		return [content.trim()].filter(Boolean);
-	}
-
-	if (!Array.isArray(content)) {
-		return [];
-	}
+	if (typeof content === "string") return [content.trim()].filter(Boolean);
+	if (!Array.isArray(content)) return [];
 
 	const lines: string[] = [];
 	for (const part of content) {
 		if (!part || typeof part !== "object") continue;
-
 		const block = part as MessageContentBlock;
 		if (block.type === "text" && typeof block.text === "string") {
 			lines.push(block.text.trim());
@@ -657,7 +444,6 @@ function extractContentLines(content: unknown): string[] {
 			lines.push(`Tool result from ${block.name}: ${formatJson(block.result)}`);
 		}
 	}
-
 	return lines.filter(Boolean);
 }