@narumitw/pi-btw 0.20.0 → 0.25.0

package/README.md

@@ -8,8 +8,9 @@ Use it when you want to ask a temporary question, inspect context, or get a shor
 
 ## ✨ Features
 
-- Adds a `/btw <question>` command to Pi.
+- Adds a `/btw` side-thread command to Pi, with an optional initial question.
 - Answers side questions in a temporary, scrollable UI.
+- Supports follow-up questions in the same ephemeral side thread.
 - Uses the current session branch as context.
 - Uses Pi's current model or an independent model selected in `pi-btw.json`.
 - Inherits Pi's current thinking level or uses a fixed level from `pi-btw.json`.
@@ -36,22 +37,34 @@ pi -e ./extensions/pi-btw
 
 ## 🚀 Usage
 
+Start an empty side thread or provide its first question immediately:
+
 ```text
+/btw
 /btw <your side question>
 ```
 
 Examples:
 
 ```text
+/btw
 /btw what does this TypeScript error mean?
 /btw summarize the current implementation before we continue
 /btw is this API name idiomatic?
 ```
 
-Long answers open in a pager-style view. Use `↑`/`↓` or `k`/`j` to scroll by line,
-`PgUp`/`PgDn`, `Shift+Space`/`Space`, or `Ctrl+B`/`Ctrl+F` to scroll by page,
-`Ctrl+U`/`Ctrl+D` to scroll by half page, and `Home`/`End` to jump. Close with
-`q`, `Esc`, `Enter`, or `Ctrl+C`.
+Running `/btw` alone opens an empty ephemeral side thread with its editor ready. When an
+initial question is provided, its answer opens above the same editor. A compact
+`btw · side thread` header stays fixed above the content so the ephemeral workspace remains
+recognizable while scrolling. Messages use Pi's normal user and assistant presentation without
+numbered turns or role labels. Type each question and press `Enter`; no follow-up shortcut is
+required.
+Previous side questions and answers remain available to the model and visible for that
+invocation. While a response is running, the transcript stays visible above a compact
+`Answering…` status. The footer shows `PgUp`/`PgDn` only when history can scroll; press
+`Ctrl+C` to cancel an in-progress answer or leave the side thread. Closing it, reloading Pi,
+or switching sessions discards it without adding any of its questions or answers to the main
+conversation.
 
 ## ⚙️ Model and thinking level
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-btw",
-	"version": "0.20.0",
+	"version": "0.25.0",
 	"description": "Pi extension that adds a /btw side-question command.",
 	"type": "module",
 	"license": "MIT",

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);
 }
 

package/src/side-thread.ts

@@ -0,0 +1,247 @@
+import type {
+	Api,
+	AssistantMessage,
+	Context,
+	Message,
+	Model,
+	SimpleStreamOptions,
+	UserMessage,
+} from "@earendil-works/pi-ai";
+
+export const BTW_THINKING_LEVELS = [
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max",
+] as const;
+
+export type BtwThinkingLevel = (typeof BTW_THINKING_LEVELS)[number];
+
+export interface SideQuestionAuth {
+	apiKey?: string;
+	headers?: Record<string, string>;
+	env?: Record<string, string>;
+}
+
+export type CompleteSimpleFunction = <TApi extends Api>(
+	model: Model<TApi>,
+	context: Context,
+	options?: SimpleStreamOptions,
+) => Promise<AssistantMessage>;
+
+type ModuleImporter = (moduleId: string) => Promise<unknown>;
+
+function hasCompleteSimple(value: unknown): value is { completeSimple: CompleteSimpleFunction } {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		typeof Reflect.get(value, "completeSimple") === "function"
+	);
+}
+
+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 defaultCompleteSimple = await loadCompleteSimple();
+
+export type SideThreadTurn =
+	| {
+			kind: "answered";
+			question: string;
+			answer: string;
+			response: AssistantMessage;
+	  }
+	| {
+			kind: "error";
+			question: string;
+			answer: string;
+	  };
+
+export interface SideThread {
+	conversationContext: string;
+	turns: SideThreadTurn[];
+}
+
+export function createSideThread(conversationContext: string): SideThread {
+	return { conversationContext, turns: [] };
+}
+
+export function buildSideThreadMessages(thread: SideThread, question: string): Message[] {
+	const answeredTurns = thread.turns.filter(
+		(turn): turn is Extract<SideThreadTurn, { kind: "answered" }> => turn.kind === "answered",
+	);
+	const messages: Message[] = [];
+
+	if (answeredTurns.length === 0) {
+		messages.push(createUserMessage(buildUserPrompt(question, thread.conversationContext)));
+		return messages;
+	}
+
+	const [first, ...rest] = answeredTurns;
+	messages.push(
+		createUserMessage(buildUserPrompt(first.question, thread.conversationContext)),
+		first.response,
+	);
+	for (const turn of rest) {
+		messages.push(createUserMessage(buildFollowUpPrompt(turn.question)), turn.response);
+	}
+	messages.push(createUserMessage(buildFollowUpPrompt(question)));
+	return messages;
+}
+
+export interface CompleteSideThreadTurnOptions {
+	thread: SideThread;
+	model: Model<Api>;
+	question: string;
+	thinkingLevel: BtwThinkingLevel;
+	auth: SideQuestionAuth;
+	signal?: AbortSignal;
+	completeSimple?: CompleteSimpleFunction;
+}
+
+export type CompleteSideThreadTurnResult =
+	| { kind: "answered"; response: AssistantMessage; answer: string }
+	| { kind: "aborted" }
+	| { kind: "error"; message: string };
+
+export async function completeSideThreadTurn({
+	thread,
+	model,
+	question,
+	thinkingLevel,
+	auth,
+	signal,
+	completeSimple = defaultCompleteSimple,
+}: CompleteSideThreadTurnOptions): Promise<CompleteSideThreadTurnResult> {
+	if (signal?.aborted) return { kind: "aborted" };
+	let response: AssistantMessage;
+	try {
+		response = await completeSimple(
+			model,
+			{ systemPrompt: SYSTEM_PROMPT, messages: buildSideThreadMessages(thread, question) },
+			buildStreamOptions(auth, thinkingLevel, signal),
+		);
+	} catch (error: unknown) {
+		if (signal?.aborted) return { kind: "aborted" };
+		return { kind: "error", message: formatError(error) };
+	}
+
+	if (signal?.aborted || response.stopReason === "aborted") return { kind: "aborted" };
+	if (response.stopReason === "error") {
+		return { kind: "error", message: response.errorMessage ?? "The side model returned an error." };
+	}
+
+	const answer = extractAssistantText(response) || "No response received.";
+	thread.turns.push({ kind: "answered", question, answer, response });
+	return { kind: "answered", response, answer };
+}
+
+export interface CompleteSideQuestionOptions {
+	model: Model<Api>;
+	question: string;
+	conversationContext: string;
+	thinkingLevel: BtwThinkingLevel;
+	auth: SideQuestionAuth;
+	signal?: AbortSignal;
+	completeSimple?: CompleteSimpleFunction;
+}
+
+export async function completeSideQuestion({
+	model,
+	question,
+	conversationContext,
+	thinkingLevel,
+	auth,
+	signal,
+	completeSimple = defaultCompleteSimple,
+}: CompleteSideQuestionOptions): Promise<AssistantMessage> {
+	return completeSimple(
+		model,
+		{
+			systemPrompt: SYSTEM_PROMPT,
+			messages: [createUserMessage(buildUserPrompt(question, conversationContext))],
+		},
+		buildStreamOptions(auth, thinkingLevel, signal),
+	);
+}
+
+export function extractAssistantText(response: AssistantMessage): string {
+	return response.content
+		.filter((content): content is { type: "text"; text: string } => content.type === "text")
+		.map((content) => content.text)
+		.join("\n")
+		.trim();
+}
+
+export function buildUserPrompt(question: string, conversationContext: string): 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");
+}
+
+export function buildFollowUpPrompt(question: string): string {
+	return [
+		"Continue the same side conversation.",
+		"",
+		"<side_question>",
+		question,
+		"</side_question>",
+	].join("\n");
+}
+
+function createUserMessage(text: string): UserMessage {
+	return {
+		role: "user",
+		content: [{ type: "text", text }],
+		timestamp: Date.now(),
+	};
+}
+
+function buildStreamOptions(
+	auth: SideQuestionAuth,
+	thinkingLevel: BtwThinkingLevel,
+	signal?: AbortSignal,
+): SimpleStreamOptions {
+	const options: SimpleStreamOptions = {
+		apiKey: auth.apiKey,
+		headers: auth.headers,
+		env: auth.env,
+		signal,
+	};
+	if (thinkingLevel !== "off") options.reasoning = thinkingLevel;
+	return options;
+}
+
+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.`;

package/src/transcript-pager.ts

@@ -0,0 +1,378 @@
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import {
+	AssistantMessageComponent,
+	getMarkdownTheme,
+	type Theme,
+	UserMessageComponent,
+} from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	CURSOR_MARKER,
+	Editor,
+	type EditorTheme,
+	Key,
+	Loader,
+	Markdown,
+	matchesKey,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+} from "@earendil-works/pi-tui";
+import type { SideThreadTurn } from "./side-thread.js";
+
+const TRANSCRIPT_CHROME_LINES = 2;
+const OSC133_MARKERS = ["\u001b]133;A\u0007", "\u001b]133;B\u0007", "\u001b]133;C\u0007"];
+// Pi renders a spacer above the custom component and a two-line built-in footer below it.
+const RESERVED_APP_LINES = 3;
+
+export type TranscriptPagerAction = { kind: "submit"; question: string } | { kind: "close" };
+
+export class BtwTranscriptPager implements Component {
+	private readonly transcriptComponents: Component[];
+	private readonly editor: Editor;
+	private scrollOffset = 0;
+	private lastContentLineCount = 0;
+	private lastViewportHeight = 1;
+	private followBottom: boolean;
+	private warning: string | undefined;
+	private finished = false;
+	private isFocused = false;
+
+	constructor(
+		private readonly tui: TUI,
+		private readonly theme: Theme,
+		turns: readonly SideThreadTurn[],
+		private readonly onAction: (action: TranscriptPagerAction) => void,
+		options: { startAtBottom?: boolean } = {},
+	) {
+		this.transcriptComponents = buildTranscriptComponents(turns, this.theme);
+		this.followBottom = options.startAtBottom ?? false;
+		const editorTheme: EditorTheme = {
+			borderColor: (text) => this.theme.fg("accent", text),
+			selectList: {
+				selectedPrefix: (text) => this.theme.fg("accent", text),
+				selectedText: (text) => this.theme.fg("accent", text),
+				description: (text) => this.theme.fg("muted", text),
+				scrollInfo: (text) => this.theme.fg("dim", text),
+				noMatch: (text) => this.theme.fg("warning", text),
+			},
+		};
+		this.editor = new Editor(this.tui, editorTheme);
+		this.editor.onChange = () => {
+			this.warning = undefined;
+		};
+		this.editor.onSubmit = (text) => {
+			const question = text.trim();
+			if (!question) {
+				this.warning = "Question cannot be empty";
+				return;
+			}
+			this.finished = true;
+			this.onAction({ kind: "submit", question });
+		};
+	}
+
+	get focused(): boolean {
+		return this.isFocused;
+	}
+
+	set focused(value: boolean) {
+		this.isFocused = value;
+		this.editor.focused = value;
+	}
+
+	render(width: number): string[] {
+		const safeWidth = Math.max(1, width);
+		const editorLines = this.editor.render(safeWidth);
+		const availableRows = Math.max(1, this.tui.terminal.rows - RESERVED_APP_LINES);
+		const viewportHeight = Math.max(
+			0,
+			availableRows - editorLines.length - TRANSCRIPT_CHROME_LINES,
+		);
+		const contentLines = renderTranscriptLines(this.transcriptComponents, safeWidth);
+		this.lastContentLineCount = contentLines.length;
+		this.lastViewportHeight = viewportHeight;
+		if (this.followBottom) this.scrollOffset = this.getMaxScrollOffset();
+		this.clampScrollOffset();
+
+		return fitComposerLayout(
+			renderSideThreadHeader(safeWidth, this.theme),
+			contentLines.slice(this.scrollOffset, this.scrollOffset + viewportHeight),
+			this.renderFooter(safeWidth),
+			editorLines,
+			availableRows,
+		);
+	}
+
+	handleInput(data: string): void {
+		if (this.finished) return;
+		if (matchesKey(data, Key.ctrl("c"))) {
+			this.finished = true;
+			this.onAction({ kind: "close" });
+			return;
+		}
+		if (matchesKey(data, Key.pageUp)) {
+			const previousOffset = this.scrollOffset;
+			this.scrollBy(-this.lastViewportHeight);
+			if (this.scrollOffset < previousOffset) this.followBottom = false;
+			this.tui.requestRender();
+			return;
+		}
+		if (matchesKey(data, Key.pageDown)) {
+			this.scrollBy(this.lastViewportHeight);
+			this.followBottom = this.scrollOffset >= this.getMaxScrollOffset();
+			this.tui.requestRender();
+			return;
+		}
+		this.editor.handleInput(data);
+		if (!this.finished) this.tui.requestRender();
+	}
+
+	invalidate(): void {
+		for (const component of this.transcriptComponents) component.invalidate();
+		this.editor.invalidate();
+	}
+
+	private renderFooter(width: number): string {
+		if (this.warning) {
+			const warning = width < 32 ? "Empty • Ctrl+C" : `${this.warning} • Ctrl+C exit`;
+			return truncateToWidth(this.theme.fg("warning", warning), width);
+		}
+		const scrollable = this.getMaxScrollOffset() > 0;
+		const fullBase = "btw • Enter send • Ctrl+C exit";
+		const compactBase = "btw • Enter • Ctrl+C";
+		let hints = visibleWidth(fullBase) <= width ? fullBase : compactBase;
+		if (scrollable) {
+			const history = ` • ${this.scrollOffset > 0 ? "↑ older" : "↓ newer"} • PgUp/PgDn history`;
+			const compactHistory = " • PgUp/PgDn";
+			if (visibleWidth(`${hints}${history}`) <= width) {
+				hints += history;
+			} else if (visibleWidth(`${hints}${compactHistory}`) <= width) {
+				hints += compactHistory;
+			} else if (visibleWidth(`${compactBase}${compactHistory}`) <= width) {
+				hints = `${compactBase}${compactHistory}`;
+			}
+		}
+		return truncateToWidth(this.theme.fg("muted", hints), width);
+	}
+
+	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);
+	}
+}
+
+export class BtwAnsweringView implements Component {
+	private readonly transcriptComponents: Component[];
+	private readonly loader: Loader;
+	private readonly controller = new AbortController();
+	private scrollOffset = 0;
+	private lastContentLineCount = 0;
+	private lastViewportHeight = 1;
+	private followBottom = true;
+	private finished = false;
+
+	constructor(
+		private readonly tui: TUI,
+		private readonly theme: Theme,
+		turns: readonly SideThreadTurn[],
+		pendingQuestion: string,
+		private readonly onCancel: () => void,
+	) {
+		this.transcriptComponents = buildTranscriptComponents(turns, this.theme, pendingQuestion);
+		this.loader = new Loader(
+			this.tui,
+			(text) => this.theme.fg("accent", text),
+			(text) => this.theme.fg("muted", text),
+			"Answering…",
+		);
+	}
+
+	get signal(): AbortSignal {
+		return this.controller.signal;
+	}
+
+	render(width: number): string[] {
+		const safeWidth = Math.max(1, width);
+		const availableRows = Math.max(1, this.tui.terminal.rows - RESERVED_APP_LINES);
+		const viewportHeight = Math.max(0, availableRows - TRANSCRIPT_CHROME_LINES);
+		const contentLines = renderTranscriptLines(this.transcriptComponents, safeWidth);
+		this.lastContentLineCount = contentLines.length;
+		this.lastViewportHeight = viewportHeight;
+		if (this.followBottom) this.scrollOffset = this.getMaxScrollOffset();
+		this.clampScrollOffset();
+		const cancelHint = safeWidth < 28 ? "Ctrl+C" : "Ctrl+C cancel";
+		const loaderWidth = Math.max(1, safeWidth - visibleWidth(cancelHint) - 3);
+		const loaderLine = this.loader.render(loaderWidth).at(-1) ?? "Answering…";
+		const lines = [
+			renderSideThreadHeader(safeWidth, this.theme),
+			...contentLines.slice(this.scrollOffset, this.scrollOffset + viewportHeight),
+			truncateToWidth(`${loaderLine} • ${this.theme.fg("muted", cancelHint)}`, safeWidth),
+		];
+		return fitWithFixedHeader(lines, availableRows);
+	}
+
+	handleInput(data: string): void {
+		if (this.finished) return;
+		if (matchesKey(data, Key.ctrl("c"))) {
+			this.finished = true;
+			this.loader.stop();
+			this.controller.abort();
+			this.onCancel();
+			return;
+		}
+		if (matchesKey(data, Key.pageUp)) {
+			const previousOffset = this.scrollOffset;
+			this.scrollBy(-this.lastViewportHeight);
+			if (this.scrollOffset < previousOffset) this.followBottom = false;
+			this.tui.requestRender();
+		} else if (matchesKey(data, Key.pageDown)) {
+			this.scrollBy(this.lastViewportHeight);
+			this.followBottom = this.scrollOffset >= this.getMaxScrollOffset();
+			this.tui.requestRender();
+		}
+	}
+
+	invalidate(): void {
+		for (const component of this.transcriptComponents) component.invalidate();
+		this.loader.invalidate();
+	}
+
+	finish(): void {
+		this.finished = true;
+		this.loader.stop();
+	}
+
+	dispose(): void {
+		this.finish();
+		this.controller.abort();
+	}
+
+	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);
+	}
+}
+
+export function formatSideTranscript(turns: readonly SideThreadTurn[]): string {
+	return turns
+		.map((turn) => {
+			const question = escapeTerminalControls(turn.question);
+			const rawAnswer = escapeTerminalControls(turn.answer);
+			const answer = turn.kind === "error" ? `Error: ${rawAnswer}` : rawAnswer;
+			return `${question}\n\n${answer}`;
+		})
+		.join("\n\n");
+}
+
+function buildTranscriptComponents(
+	turns: readonly SideThreadTurn[],
+	theme: Theme,
+	pendingQuestion?: string,
+): Component[] {
+	const components = turns.flatMap((turn): Component[] => {
+		const question = new UserMessageComponent(
+			escapeTerminalControls(turn.question),
+			getMarkdownTheme(),
+			1,
+		);
+		if (turn.kind === "error") {
+			const error = new Markdown(
+				`Error: ${escapeTerminalControls(turn.answer)}`,
+				1,
+				1,
+				getMarkdownTheme(),
+				{ color: (text) => theme.fg("error", text) },
+			);
+			return [question, error];
+		}
+		const response: AssistantMessage = {
+			...turn.response,
+			content: [{ type: "text", text: escapeTerminalControls(turn.answer) }],
+			stopReason: "stop",
+			errorMessage: undefined,
+		};
+		return [question, new AssistantMessageComponent(response, true, getMarkdownTheme(), "", 1)];
+	});
+	if (pendingQuestion) {
+		components.push(
+			new UserMessageComponent(escapeTerminalControls(pendingQuestion), getMarkdownTheme(), 1),
+		);
+	}
+	return components;
+}
+
+function renderTranscriptLines(components: readonly Component[], width: number): string[] {
+	return components
+		.flatMap((component) => component.render(width))
+		.map(stripShellIntegrationMarkers);
+}
+
+function renderSideThreadHeader(width: number, theme: Theme): string {
+	const title = truncateToWidth("─ btw · side thread ", width);
+	const ruleWidth = Math.max(0, width - visibleWidth(title));
+	return theme.fg("muted", `${title}${"─".repeat(ruleWidth)}`);
+}
+
+function fitComposerLayout(
+	header: string,
+	contentLines: string[],
+	footer: string,
+	editorLines: string[],
+	availableRows: number,
+): string[] {
+	const lines = [header, ...contentLines, footer, ...editorLines];
+	if (lines.length <= availableRows) return lines;
+	if (availableRows <= 1) return [header];
+	const editorBudget = Math.max(0, availableRows - 2);
+	return [header, footer, ...fitEditorLines(editorLines, editorBudget)];
+}
+
+function fitEditorLines(editorLines: string[], budget: number): string[] {
+	if (budget <= 0) return [];
+	if (editorLines.length <= budget) return editorLines;
+	const cursorIndex = editorLines.findIndex((line) => line.includes(CURSOR_MARKER));
+	if (cursorIndex < 0) return editorLines.slice(-budget);
+	const start = Math.min(cursorIndex, editorLines.length - budget);
+	return editorLines.slice(start, start + budget);
+}
+
+function fitWithFixedHeader(lines: string[], availableRows: number): string[] {
+	if (lines.length <= availableRows) return lines;
+	if (availableRows <= 1) return lines.slice(0, 1);
+	return [lines[0] ?? "", ...lines.slice(lines.length - availableRows + 1)];
+}
+
+function stripShellIntegrationMarkers(line: string): string {
+	return OSC133_MARKERS.reduce((result, marker) => result.replaceAll(marker, ""), line);
+}
+
+function escapeTerminalControls(text: string): string {
+	return [...text]
+		.map((character) => {
+			if (character === "\n") return character;
+			if (character === "\t") return "    ";
+			const code = character.charCodeAt(0);
+			if (code <= 31 || (code >= 127 && code <= 159)) {
+				return `\\x${code.toString(16).padStart(2, "0")}`;
+			}
+			return character;
+		})
+		.join("");
+}