@narumitw/pi-btw 0.20.0 → 0.28.0

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./btw.js";

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("");
+}