@maxiaochao/pi-toolkit 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2026-09-02 - v0.1.9
+
+- add the `/btw` side-chat extension
+- bundle the `nightowl` theme
+- select `nightowl` during npm postinstall only when no theme is configured
+
+
+- fix cache export branch attribution and update HTML artifact guidance
+
 ## 2026-08-21 - v0.1.7
 
 - add the html-artifact skill for interactive HTML explanations and codebase visualizations

package/README.md

@@ -1,7 +1,64 @@
 # pi-toolkit
 
-Personal pi toolkit: `/todos` todo extension + `/cache_export` interactive prompt-cache dashboard. See [AGENTS.md](./AGENTS.md) for dev/build/release rules.
+Personal Pi toolkit with the `/todos`, `/btw`, and `/cache_export` extensions plus the bundled Night Owl theme.
+
+## Install
+
+Install the root package to enable the toolkit extensions globally:
 
 ```bash
 pi install npm:@maxiaochao/pi-toolkit
 ```
+
+The package also provides the `/btw` side-chat extension and the `nightowl` theme. On npm installation, the postinstall hook selects `nightowl` only when no theme has been configured yet; an existing Pi theme setting is preserved.
+
+The package postinstall hook synchronizes the bundled global instructions to:
+
+```text
+~/.pi/agent/AGENTS.md
+```
+
+It also selects `nightowl` as the default theme only when `~/.pi/agent/settings.json` does not already contain a theme. To switch manually, use `/settings` or:
+
+```bash
+pi --use-theme nightowl
+```
+
+An installed package can expose a theme through `pi.themes`, but Pi has no package-manifest field for a default theme, so the guarded postinstall step is used for the npm install case.
+
+When `global/AGENTS.md` changes, publish a new `@maxiaochao/pi-toolkit` version and update installed copies:
+
+```bash
+pi update npm:@maxiaochao/pi-toolkit
+```
+
+To synchronize the file directly from a checkout instead:
+
+```bash
+bash scripts/install.sh
+```
+
+The `/btw` side chat is a separate agent session. It can inspect the main conversation and repository, and its thread stays out of the main context until you close it and choose to inject a summary. Use `/btw` to open it or `/btw <question>` to ask directly.
+
+The bundled `nightowl` theme is available to Pi through the package manifest and is selected automatically on npm installation only when no theme is already configured.
+
+## Tiny Subagent
+
+The tiny subagent is a separate npm package. Install it independently when you want the `tiny_subagents` tool:
+
+```bash
+pi install npm:@maxiaochao/pi-tiny-subagent
+```
+
+It is not included in the root package's `pi.extensions` list. The two packages have independent versions, release tags, and update commands:
+
+```bash
+pi update npm:@maxiaochao/pi-toolkit
+pi update npm:@maxiaochao/pi-tiny-subagent
+```
+
+See [packages/tiny-subagent/README.md](packages/tiny-subagent/README.md) for personas, model selection, child isolation, live transcript rendering, and diagnostics.
+
+## Development
+
+Repository development and release rules are documented in [AGENTS.md](AGENTS.md).

package/extensions/btw.ts

@@ -0,0 +1,958 @@
+import {
+	buildSessionContext,
+	createAgentSession,
+	createExtensionRuntime,
+	getMarkdownTheme,
+	SessionManager,
+	type AgentSession,
+	type AgentSessionEvent,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+	type ExtensionContext,
+	type ResourceLoader,
+} from "@earendil-works/pi-coding-agent";
+import { type AssistantMessage, type Message, type ThinkingLevel as AiThinkingLevel } from "@earendil-works/pi-ai";
+import {
+	Container,
+	Input,
+	Markdown,
+	truncateToWidth,
+	visibleWidth,
+	type Focusable,
+	type KeybindingsManager,
+	type OverlayHandle,
+	type TUI,
+} from "@earendil-works/pi-tui";
+
+const BTW_ENTRY_TYPE = "btw-thread-entry";
+const BTW_RESET_TYPE = "btw-thread-reset";
+
+const BTW_SYSTEM_PROMPT = [
+	"You are BTW, a side-channel assistant embedded in the user's coding agent.",
+	"You have access to the main conversation context — use it to give informed answers.",
+	"Help with focused questions, planning, and quick explorations.",
+	"Be direct and practical.",
+].join(" ");
+
+const BTW_SUMMARY_PROMPT =
+	"Summarize this side conversation for handoff into the main conversation. Keep key decisions, findings, risks, and next actions. Output only the summary.";
+
+type SessionThinkingLevel = "off" | AiThinkingLevel;
+
+type BtwDetails = {
+	question: string;
+	answer: string;
+	timestamp: number;
+	provider: string;
+	model: string;
+	thinkingLevel: SessionThinkingLevel;
+	usage?: AssistantMessage["usage"];
+};
+
+type BtwResetDetails = {
+	timestamp: number;
+};
+
+type OverlayRuntime = {
+	handle?: OverlayHandle;
+	refresh?: () => void;
+	close?: () => void;
+	finish?: () => void;
+	setDraft?: (value: string) => void;
+	closed?: boolean;
+};
+
+type SideSessionRuntime = {
+	session: AgentSession;
+	modelKey: string;
+	unsubscribe: () => void;
+};
+
+type ToolCallInfo = {
+	toolCallId: string;
+	toolName: string;
+	args: string;
+	status: "running" | "done" | "error";
+};
+
+function stripDynamicSystemPromptFooter(systemPrompt: string): string {
+	return systemPrompt
+		.replace(/\nCurrent date and time:[^\n]*(?:\nCurrent working directory:[^\n]*)?$/u, "")
+		.replace(/\nCurrent working directory:[^\n]*$/u, "")
+		.trim();
+}
+
+function createBtwResourceLoader(ctx: ExtensionContext, appendSystemPrompt: string[] = [BTW_SYSTEM_PROMPT]): ResourceLoader {
+	const extensionsResult = { extensions: [], errors: [], runtime: createExtensionRuntime() };
+	const systemPrompt = stripDynamicSystemPromptFooter(ctx.getSystemPrompt());
+
+	return {
+		getExtensions: () => extensionsResult,
+		getSkills: () => ({ skills: [], diagnostics: [] }),
+		getPrompts: () => ({ prompts: [], diagnostics: [] }),
+		getThemes: () => ({ themes: [], diagnostics: [] }),
+		getAgentsFiles: () => ({ agentsFiles: [] }),
+		getSystemPrompt: () => systemPrompt,
+		getAppendSystemPrompt: () => appendSystemPrompt,
+		extendResources: () => {},
+		reload: async () => {},
+	};
+}
+
+function extractText(parts: AssistantMessage["content"]): string {
+	return parts
+		.filter((part) => part.type === "text")
+		.map((part) => part.text)
+		.join("\n")
+		.trim();
+}
+
+function extractEventAssistantText(message: unknown): string {
+	if (!message || typeof message !== "object") {
+		return "";
+	}
+
+	const maybeMessage = message as { role?: unknown; content?: unknown };
+	if (maybeMessage.role !== "assistant" || !Array.isArray(maybeMessage.content)) {
+		return "";
+	}
+
+	return maybeMessage.content
+		.filter((part): part is { type: "text"; text: string } => {
+			return !!part && typeof part === "object" && (part as { type?: unknown }).type === "text";
+		})
+		.map((part) => part.text)
+		.join("\n")
+		.trim();
+}
+
+function getLastAssistantMessage(session: AgentSession): AssistantMessage | null {
+	for (let i = session.state.messages.length - 1; i >= 0; i--) {
+		const message = session.state.messages[i];
+		if (message.role === "assistant") {
+			return message as AssistantMessage;
+		}
+	}
+
+	return null;
+}
+
+function buildSeedMessages(ctx: ExtensionContext, thread: BtwDetails[]): Message[] {
+	const seed: Message[] = [];
+
+	try {
+		const contextMessages = buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId()).messages;
+		seed.push(...(contextMessages.filter((message) => "role" in message) as Message[]));
+	} catch {
+		// Ignore context seed failures and continue with an empty side thread.
+	}
+
+	for (const item of thread) {
+		seed.push(
+			{
+				role: "user",
+				content: [{ type: "text", text: item.question }],
+				timestamp: item.timestamp,
+			},
+			{
+				role: "assistant",
+				content: [{ type: "text", text: item.answer }],
+				provider: item.provider,
+				model: item.model,
+				api: ctx.model?.api ?? "openai-responses",
+				usage:
+					item.usage ??
+					{
+						input: 0,
+						output: 0,
+						cacheRead: 0,
+						cacheWrite: 0,
+						totalTokens: 0,
+						cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+					},
+				stopReason: "stop",
+				timestamp: item.timestamp,
+			},
+		);
+	}
+
+	return seed;
+}
+
+function formatThread(thread: BtwDetails[]): string {
+	return thread
+		.map((item) => `User: ${item.question.trim()}\nAssistant: ${item.answer.trim()}`)
+		.join("\n\n---\n\n");
+}
+
+function notify(ctx: ExtensionContext | ExtensionCommandContext, message: string, level: "info" | "warning" | "error"): void {
+	if (ctx.hasUI) {
+		ctx.ui.notify(message, level);
+	}
+}
+
+
+class BtwOverlay extends Container implements Focusable {
+	private readonly input: Input;
+	private readonly tui: TUI;
+	private readonly theme: ExtensionContext["ui"]["theme"];
+	private readonly keybindings: KeybindingsManager;
+	private readonly getTranscript: (width: number, theme: ExtensionContext["ui"]["theme"]) => string[];
+	private readonly getStatus: () => string;
+	private readonly onSubmitCallback: (value: string) => void;
+	private readonly onDismissCallback: () => void;
+	private _focused = false;
+
+	get focused(): boolean {
+		return this._focused;
+	}
+
+	set focused(value: boolean) {
+		this._focused = value;
+		this.input.focused = value;
+	}
+
+	constructor(
+		tui: TUI,
+		theme: ExtensionContext["ui"]["theme"],
+		keybindings: KeybindingsManager,
+		getTranscript: (width: number, theme: ExtensionContext["ui"]["theme"]) => string[],
+		getStatus: () => string,
+		onSubmit: (value: string) => void,
+		onDismiss: () => void,
+	) {
+		super();
+		this.tui = tui;
+		this.theme = theme;
+		this.keybindings = keybindings;
+		this.getTranscript = getTranscript;
+		this.getStatus = getStatus;
+		this.onSubmitCallback = onSubmit;
+		this.onDismissCallback = onDismiss;
+
+		this.input = new Input();
+		this.input.onSubmit = (value) => {
+			this.onSubmitCallback(value);
+		};
+		this.input.onEscape = () => {
+			this.onDismissCallback();
+		};
+	}
+
+	handleInput(data: string): void {
+		if (this.keybindings.matches(data, "tui.select.cancel")) {
+			this.onDismissCallback();
+			return;
+		}
+
+		this.input.handleInput(data);
+	}
+
+	setDraft(value: string): void {
+		this.input.setValue(value);
+		this.tui.requestRender();
+	}
+
+	getDraft(): string {
+		return this.input.getValue();
+	}
+
+	private frameLine(content: string, innerWidth: number): string {
+		const truncated = truncateToWidth(content, innerWidth, "");
+		const padding = Math.max(0, innerWidth - visibleWidth(truncated));
+		return `${this.theme.fg("borderMuted", "│")}${truncated}${" ".repeat(padding)}${this.theme.fg("borderMuted", "│")}`;
+	}
+
+	private borderLine(innerWidth: number, edge: "top" | "bottom"): string {
+		const left = edge === "top" ? "┌" : "└";
+		const right = edge === "top" ? "┐" : "┘";
+		return this.theme.fg("borderMuted", `${left}${"─".repeat(innerWidth)}${right}`);
+	}
+
+	override render(width: number): string[] {
+		const dialogWidth = Math.max(56, Math.min(width, Math.floor(width * 0.9)));
+		const innerWidth = Math.max(40, dialogWidth - 2);
+		const terminalRows = process.stdout.rows ?? 30;
+		const dialogHeight = Math.max(16, Math.min(30, Math.floor(terminalRows * 0.75)));
+		const chromeHeight = 7;
+		const transcriptHeight = Math.max(6, dialogHeight - chromeHeight);
+
+		// Markdown renders to innerWidth already — no manual wrapping needed
+		const transcript = this.getTranscript(innerWidth, this.theme);
+		const visibleTranscript = transcript.slice(-transcriptHeight);
+		const transcriptPadding = Math.max(0, transcriptHeight - visibleTranscript.length);
+
+		const status = this.getStatus();
+
+		const previousFocused = this.input.focused;
+		this.input.focused = false;
+		const inputLine = this.input.render(innerWidth)[0] ?? "";
+		this.input.focused = previousFocused;
+
+		const lines = [
+			this.borderLine(innerWidth, "top"),
+			this.frameLine(this.theme.fg("accent", this.theme.bold(" BTW side chat ")), innerWidth),
+			this.frameLine(this.theme.fg("dim", "Separate side conversation. Esc closes."), innerWidth),
+			this.theme.fg("borderMuted", `├${"─".repeat(innerWidth)}┤`),
+		];
+
+		for (const line of visibleTranscript) {
+			lines.push(this.frameLine(line, innerWidth));
+		}
+		for (let i = 0; i < transcriptPadding; i++) {
+			lines.push(this.frameLine("", innerWidth));
+		}
+
+		lines.push(this.theme.fg("borderMuted", `├${"─".repeat(innerWidth)}┤`));
+		lines.push(this.frameLine(this.theme.fg("warning", status), innerWidth));
+		lines.push(
+			`${this.theme.fg("borderMuted", "│")}${inputLine}${this.theme.fg("borderMuted", "│")}`,
+		);
+		lines.push(this.frameLine(this.theme.fg("dim", "Enter submit · Esc close"), innerWidth));
+		lines.push(this.borderLine(innerWidth, "bottom"));
+
+		return lines;
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	let thread: BtwDetails[] = [];
+	let pendingQuestion: string | null = null;
+	let pendingAnswer = "";
+	let pendingError: string | null = null;
+	let pendingToolCalls: ToolCallInfo[] = [];
+	let sideBusy = false;
+	let overlayStatus = "Ready";
+	let overlayDraft = "";
+	let overlayRuntime: OverlayRuntime | null = null;
+	let activeSideSession: SideSessionRuntime | null = null;
+	let overlayRefreshTimer: ReturnType<typeof setTimeout> | null = null;
+
+	const mdTheme = getMarkdownTheme();
+
+	function getModelKey(ctx: ExtensionContext): string {
+		const model = ctx.model;
+		return model ? `${model.provider}/${model.id}` : "none";
+	}
+
+	function renderMarkdownLines(text: string, width: number): string[] {
+		if (!text) return [];
+		try {
+			const md = new Markdown(text, 0, 0, mdTheme);
+			return md.render(width);
+		} catch {
+			// Fall back to plain text wrapping if Markdown rendering fails
+			return text.split("\n").flatMap((line) => {
+				if (!line) return [""];
+				const wrapped: string[] = [];
+				for (let i = 0; i < line.length; i += width) {
+					wrapped.push(line.slice(i, i + width));
+				}
+				return wrapped.length > 0 ? wrapped : [""];
+			});
+		}
+	}
+
+	function formatToolArgs(toolName: string, args: unknown): string {
+		if (!args || typeof args !== "object") return "";
+		const a = args as Record<string, unknown>;
+		switch (toolName) {
+			case "bash":
+				return typeof a.command === "string" ? truncateToWidth(a.command.split("\n")[0], 50, "…") : "";
+			case "read":
+			case "write":
+			case "edit":
+				return typeof a.path === "string" ? a.path : "";
+			default: {
+				const first = Object.values(a)[0];
+				return typeof first === "string" ? truncateToWidth(first.split("\n")[0], 40, "…") : "";
+			}
+		}
+	}
+
+	function renderToolCallLines(toolCalls: ToolCallInfo[], theme: ExtensionContext["ui"]["theme"], width: number): string[] {
+		const lines: string[] = [];
+		for (const tc of toolCalls) {
+			const icon = tc.status === "running" ? "⚙" : tc.status === "error" ? "✗" : "✓";
+			const color = tc.status === "error" ? "error" : tc.status === "done" ? "success" : "dim";
+			const label = theme.fg(color, `${icon} `) + theme.fg("toolTitle", tc.toolName);
+			const argsText = tc.args ? theme.fg("dim", ` ${tc.args}`) : "";
+			lines.push(truncateToWidth(`  ${label}${argsText}`, width, ""));
+		}
+		return lines;
+	}
+
+	function getTranscriptLines(width: number, theme: ExtensionContext["ui"]["theme"]): string[] {
+		try {
+			return getTranscriptLinesInner(width, theme);
+		} catch (error) {
+			return [theme.fg("error", `Render error: ${error instanceof Error ? error.message : String(error)}`)];
+		}
+	}
+
+	function getTranscriptLinesInner(width: number, theme: ExtensionContext["ui"]["theme"]): string[] {
+		if (thread.length === 0 && !pendingQuestion && !pendingAnswer && !pendingError) {
+			return [theme.fg("dim", "No BTW messages yet. Type a question below.")];
+		}
+
+		const lines: string[] = [];
+		for (const item of thread.slice(-6)) {
+			// User message
+			const userText = item.question.trim().split("\n")[0];
+			lines.push(theme.fg("accent", theme.bold("You: ")) + truncateToWidth(userText, width - 5, "…"));
+			lines.push("");
+
+			// Assistant message rendered as markdown
+			const mdLines = renderMarkdownLines(item.answer, width);
+			lines.push(...mdLines);
+			lines.push("");
+		}
+
+		if (pendingQuestion) {
+			const userText = pendingQuestion.trim().split("\n")[0];
+			lines.push(theme.fg("accent", theme.bold("You: ")) + truncateToWidth(userText, width - 5, "…"));
+
+			// Show tool calls inline
+			if (pendingToolCalls.length > 0) {
+				lines.push(...renderToolCallLines(pendingToolCalls, theme, width));
+			}
+
+			if (pendingError) {
+				lines.push(theme.fg("error", `❌ ${pendingError}`));
+			} else if (pendingAnswer) {
+				lines.push("");
+				const mdLines = renderMarkdownLines(pendingAnswer, width);
+				lines.push(...mdLines);
+			} else if (pendingToolCalls.length === 0) {
+				lines.push(theme.fg("dim", "…"));
+			}
+		}
+
+		// Trim trailing empty line
+		while (lines.length > 0 && lines[lines.length - 1] === "") {
+			lines.pop();
+		}
+		return lines;
+	}
+
+	function syncOverlay(): void {
+		overlayRuntime?.refresh?.();
+	}
+
+	function scheduleOverlayRefresh(): void {
+		if (overlayRefreshTimer) {
+			return;
+		}
+
+		overlayRefreshTimer = setTimeout(() => {
+			overlayRefreshTimer = null;
+			syncOverlay();
+		}, 16);
+	}
+
+	function setOverlayStatus(status: string, throttled = false): void {
+		overlayStatus = status;
+		if (throttled) {
+			scheduleOverlayRefresh();
+		} else {
+			syncOverlay();
+		}
+	}
+
+	function dismissOverlay(): void {
+		overlayRuntime?.close?.();
+		overlayRuntime = null;
+		if (overlayRefreshTimer) {
+			clearTimeout(overlayRefreshTimer);
+			overlayRefreshTimer = null;
+		}
+	}
+
+	function setOverlayDraft(value: string): void {
+		overlayDraft = value;
+		overlayRuntime?.setDraft?.(value);
+	}
+
+	async function disposeSideSession(): Promise<void> {
+		const current = activeSideSession;
+		activeSideSession = null;
+		if (!current) {
+			return;
+		}
+
+		try {
+			current.unsubscribe();
+		} catch {
+			// Ignore unsubscribe errors during cleanup.
+		}
+
+		try {
+			await current.session.abort();
+		} catch {
+			// Ignore abort errors during cleanup.
+		}
+		current.session.dispose();
+
+		if (overlayRefreshTimer) {
+			clearTimeout(overlayRefreshTimer);
+			overlayRefreshTimer = null;
+		}
+	}
+
+	async function resetThread(ctx: ExtensionContext | ExtensionCommandContext, persist = true): Promise<void> {
+		thread = [];
+		pendingQuestion = null;
+		pendingAnswer = "";
+		pendingError = null;
+		pendingToolCalls = [];
+		sideBusy = false;
+		setOverlayDraft("");
+		setOverlayStatus("Ready");
+		await disposeSideSession();
+		if (persist) {
+			const details: BtwResetDetails = { timestamp: Date.now() };
+			pi.appendEntry(BTW_RESET_TYPE, details);
+		}
+		syncOverlay();
+	}
+
+	async function restoreThread(ctx: ExtensionContext): Promise<void> {
+		await disposeSideSession();
+		thread = [];
+		pendingQuestion = null;
+		pendingAnswer = "";
+		pendingError = null;
+		pendingToolCalls = [];
+		sideBusy = false;
+		overlayStatus = "Ready";
+		overlayDraft = "";
+		const branch = ctx.sessionManager.getBranch();
+		let lastResetIndex = -1;
+		for (let i = 0; i < branch.length; i++) {
+			const entry = branch[i];
+			if (entry.type === "custom" && entry.customType === BTW_RESET_TYPE) {
+				lastResetIndex = i;
+			}
+		}
+
+		for (const entry of branch.slice(lastResetIndex + 1)) {
+			if (entry.type !== "custom" || entry.customType !== BTW_ENTRY_TYPE) {
+				continue;
+			}
+			const details = entry.data as BtwDetails | undefined;
+			if (!details?.question || !details.answer) {
+				continue;
+			}
+			thread.push(details);
+		}
+
+		syncOverlay();
+	}
+
+	async function createSideSession(ctx: ExtensionCommandContext): Promise<SideSessionRuntime | null> {
+		if (!ctx.model) {
+			return null;
+		}
+
+		const { session } = await createAgentSession({
+			sessionManager: SessionManager.inMemory(),
+			model: ctx.model,
+			modelRegistry: ctx.modelRegistry as AgentSession["modelRegistry"],
+			thinkingLevel: pi.getThinkingLevel() as SessionThinkingLevel,
+			tools: ["read", "bash", "edit", "write"],
+			resourceLoader: createBtwResourceLoader(ctx),
+		});
+
+		const seedMessages = buildSeedMessages(ctx, thread);
+		if (seedMessages.length > 0) {
+			session.agent.state.messages = seedMessages as typeof session.agent.state.messages;
+		}
+
+		const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+			if (!sideBusy || !pendingQuestion) {
+				return;
+			}
+
+			switch (event.type) {
+				case "message_start":
+				case "message_update":
+				case "message_end": {
+					const streamed = extractEventAssistantText(event.message);
+					if (streamed) {
+						pendingAnswer = streamed;
+						pendingError = null;
+					}
+					setOverlayStatus(event.type === "message_end" ? "Finalizing side response..." : "Streaming side response...", true);
+					return;
+				}
+				case "tool_execution_start": {
+					const toolName = (event as { toolName?: string }).toolName ?? "unknown";
+					try {
+						pendingToolCalls.push({
+							toolCallId: (event as { toolCallId?: string }).toolCallId ?? "",
+							toolName,
+							args: formatToolArgs(toolName, (event as { args?: unknown }).args),
+							status: "running",
+						});
+					} catch {
+						// Ignore tool tracking failures
+					}
+					setOverlayStatus(`Running tool: ${toolName}...`, true);
+					return;
+				}
+				case "tool_execution_end": {
+					const endToolName = (event as { toolName?: string }).toolName ?? "unknown";
+					const tc = pendingToolCalls.find(
+						(t) => t.toolName === endToolName && t.status === "running",
+					);
+					if (tc) {
+						tc.status = (event as { isError?: boolean }).isError ? "error" : "done";
+					}
+					setOverlayStatus("Streaming side response...", true);
+					return;
+				}
+				case "turn_end": {
+					setOverlayStatus("Finalizing side response...", true);
+					return;
+				}
+				default:
+					return;
+			}
+		});
+
+		return {
+			session,
+			modelKey: getModelKey(ctx),
+			unsubscribe,
+		};
+	}
+
+	async function ensureSideSession(ctx: ExtensionCommandContext): Promise<SideSessionRuntime | null> {
+		if (!ctx.model) {
+			return null;
+		}
+
+		const expectedModelKey = getModelKey(ctx);
+		if (activeSideSession && activeSideSession.modelKey === expectedModelKey) {
+			return activeSideSession;
+		}
+
+		await disposeSideSession();
+		activeSideSession = await createSideSession(ctx);
+		return activeSideSession;
+	}
+
+	async function ensureOverlay(ctx: ExtensionCommandContext | ExtensionContext): Promise<void> {
+		if (!ctx.hasUI) {
+			return;
+		}
+
+		if (overlayRuntime?.handle) {
+			overlayRuntime.handle.setHidden(false);
+			overlayRuntime.handle.focus();
+			overlayRuntime.refresh?.();
+			return;
+		}
+
+		const runtime: OverlayRuntime = {};
+		const closeRuntime = () => {
+			if (runtime.closed) {
+				return;
+			}
+			runtime.closed = true;
+			runtime.handle?.hide();
+			if (overlayRuntime === runtime) {
+				overlayRuntime = null;
+			}
+			runtime.finish?.();
+		};
+		runtime.close = closeRuntime;
+		overlayRuntime = runtime;
+
+		void ctx.ui
+			.custom<void>(
+				async (tui, theme, keybindings, done) => {
+					runtime.finish = () => done();
+
+					const overlay = new BtwOverlay(
+						tui,
+						theme,
+						keybindings,
+						(width, t) => getTranscriptLines(width, t),
+						() => overlayStatus,
+						(value) => {
+							void submitFromOverlay(ctx, value);
+						},
+						() => {
+							void closeOverlayFlow(ctx);
+						},
+					);
+
+					overlay.focused = true;
+					overlay.setDraft(overlayDraft);
+					runtime.setDraft = (value) => overlay.setDraft(value);
+					runtime.refresh = () => {
+						overlay.focused = runtime.handle?.isFocused() ?? false;
+						tui.requestRender();
+					};
+					runtime.close = () => {
+						overlayDraft = overlay.getDraft();
+						closeRuntime();
+					};
+
+					if (runtime.closed) {
+						done();
+					}
+
+					return overlay;
+				},
+				{
+					overlay: true,
+					overlayOptions: {
+						width: "80%",
+						minWidth: 72,
+						maxHeight: "78%",
+						anchor: "top-center",
+						margin: { top: 1, left: 2, right: 2 },
+					},
+					onHandle: (handle) => {
+						runtime.handle = handle;
+						handle.focus();
+						if (runtime.closed) {
+							closeRuntime();
+						}
+					},
+				},
+			)
+			.catch((error) => {
+				if (overlayRuntime === runtime) {
+					overlayRuntime = null;
+				}
+				notify(ctx, error instanceof Error ? error.message : String(error), "error");
+			});
+	}
+
+	async function summarizeThread(ctx: ExtensionContext, items: BtwDetails[]): Promise<string> {
+		const model = ctx.model;
+		if (!model) {
+			throw new Error("No active model selected.");
+		}
+
+		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+		if (auth.ok === false) {
+			throw new Error(auth.error);
+		}
+
+		const { session } = await createAgentSession({
+			sessionManager: SessionManager.inMemory(),
+			model,
+			modelRegistry: ctx.modelRegistry as AgentSession["modelRegistry"],
+			thinkingLevel: "off",
+			tools: [],
+			resourceLoader: createBtwResourceLoader(ctx, [BTW_SUMMARY_PROMPT]),
+		});
+
+		try {
+			await session.prompt(formatThread(items), { source: "extension" });
+			const response = getLastAssistantMessage(session);
+			if (!response) {
+				throw new Error("Summary finished without a response.");
+			}
+			if (response.stopReason === "aborted") {
+				throw new Error("Summary request was aborted.");
+			}
+			if (response.stopReason === "error") {
+				throw new Error(response.errorMessage || "Summary request failed.");
+			}
+
+			return extractText(response.content) || "(No summary generated)";
+		} finally {
+			try {
+				await session.abort();
+			} catch {
+				// Ignore abort errors during temporary session teardown.
+			}
+			session.dispose();
+		}
+	}
+
+	async function injectSummaryIntoMain(ctx: ExtensionContext | ExtensionCommandContext): Promise<void> {
+		if (thread.length === 0) {
+			notify(ctx, "No BTW thread to summarize.", "warning");
+			return;
+		}
+
+		setOverlayStatus("Summarizing BTW thread for injection...");
+		try {
+			const summary = await summarizeThread(ctx, thread);
+			const message = `Summary of my BTW side conversation:\n\n${summary}`;
+			if (ctx.isIdle()) {
+				pi.sendUserMessage(message);
+			} else {
+				pi.sendUserMessage(message, { deliverAs: "followUp" });
+			}
+
+			await resetThread(ctx);
+			notify(ctx, "Injected BTW summary into main chat.", "info");
+		} catch (error) {
+			notify(ctx, error instanceof Error ? error.message : String(error), "error");
+		}
+	}
+
+	async function closeOverlayFlow(ctx: ExtensionContext | ExtensionCommandContext): Promise<void> {
+		dismissOverlay();
+		if (!ctx.hasUI) {
+			return;
+		}
+
+		if (thread.length === 0) {
+			return;
+		}
+
+		const choice = await ctx.ui.select("Close BTW:", ["Keep side thread", "Inject summary into main chat"]);
+		if (choice === "Inject summary into main chat") {
+			await injectSummaryIntoMain(ctx);
+		}
+	}
+
+	async function runBtwPrompt(ctx: ExtensionCommandContext, question: string): Promise<void> {
+		const model = ctx.model;
+		if (!model) {
+			setOverlayStatus("No active model selected.");
+			notify(ctx, "No active model selected.", "error");
+			return;
+		}
+
+		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+		if (auth.ok === false) {
+			const message = auth.error;
+			setOverlayStatus(message);
+			notify(ctx, message, "error");
+			return;
+		}
+
+		if (sideBusy) {
+			notify(ctx, "BTW is still processing the previous message.", "warning");
+			return;
+		}
+
+		const side = await ensureSideSession(ctx);
+		if (!side) {
+			notify(ctx, "Unable to create BTW side session.", "error");
+			return;
+		}
+
+		sideBusy = true;
+		pendingQuestion = question;
+		pendingAnswer = "";
+		pendingError = null;
+		pendingToolCalls = [];
+		setOverlayStatus("Streaming side response...");
+		syncOverlay();
+
+		try {
+			await side.session.prompt(question, { source: "extension" });
+			const response = getLastAssistantMessage(side.session);
+			if (!response) {
+				throw new Error("BTW request finished without a response.");
+			}
+			if (response.stopReason === "aborted") {
+				throw new Error("BTW request aborted.");
+			}
+			if (response.stopReason === "error") {
+				throw new Error(response.errorMessage || "BTW request failed.");
+			}
+
+			const answer = extractText(response.content) || "(No text response)";
+			pendingAnswer = answer;
+			const details: BtwDetails = {
+				question,
+				answer,
+				timestamp: Date.now(),
+				provider: model.provider,
+				model: model.id,
+				thinkingLevel: pi.getThinkingLevel() as SessionThinkingLevel,
+				usage: response.usage,
+			};
+			thread.push(details);
+			pi.appendEntry(BTW_ENTRY_TYPE, details);
+
+			pendingQuestion = null;
+			pendingAnswer = "";
+			pendingToolCalls = [];
+			setOverlayStatus("Ready for the next side question.");
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			pendingError = message;
+			setOverlayStatus("BTW request failed.");
+			notify(ctx, message, "error");
+		} finally {
+			sideBusy = false;
+			syncOverlay();
+		}
+	}
+
+	async function submitFromOverlay(ctx: ExtensionContext | ExtensionCommandContext, rawValue: string): Promise<void> {
+		const question = rawValue.trim();
+		if (!question) {
+			setOverlayStatus("Enter a question first.");
+			return;
+		}
+
+		setOverlayDraft("");
+		if (!("waitForIdle" in ctx)) {
+			setOverlayStatus("BTW submit requires command context. Re-open with /btw.");
+			return;
+		}
+
+		await runBtwPrompt(ctx, question);
+	}
+
+	pi.registerCommand("btw", {
+		description: "Open a simple BTW side-chat popover. `/btw <text>` asks immediately, `/btw` opens the side thread.",
+		handler: async (args, ctx) => {
+			const question = args.trim();
+
+			if (!question) {
+				if (thread.length > 0 && ctx.hasUI) {
+					const choice = await ctx.ui.select("BTW side chat:", [
+						"Continue previous conversation",
+						"Start fresh",
+					]);
+					if (choice === "Continue previous conversation") {
+						// Dispose session so it's recreated with fresh main context on next submit
+						await disposeSideSession();
+						setOverlayStatus("Continuing BTW thread.");
+						await ensureOverlay(ctx);
+					} else if (choice === "Start fresh") {
+						await resetThread(ctx, true);
+						setOverlayStatus("Ready");
+						await ensureOverlay(ctx);
+					}
+					// null = user cancelled (Esc), do nothing
+				} else {
+					await resetThread(ctx, true);
+					setOverlayStatus("Ready");
+					await ensureOverlay(ctx);
+				}
+				return;
+			}
+
+			await ensureOverlay(ctx);
+			await runBtwPrompt(ctx, question);
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		await restoreThread(ctx);
+	});
+
+	pi.on("session_tree", async (_event, ctx) => {
+		await restoreThread(ctx);
+	});
+
+	pi.on("session_shutdown", async () => {
+		await disposeSideSession();
+		dismissOverlay();
+	});
+}

package/extensions/cache-export/index.ts

@@ -63,7 +63,10 @@ export default function (pi) {
   pi.registerCommand("cache_export", {
     description: "Export a tau-style interactive cache dashboard (hit-rate charts, per-request table, events)",
     handler: async (args, ctx) => {
-      const entries = ctx.sessionManager.getEntries();
+      const sessionManager = ctx.sessionManager;
+      const entries = typeof sessionManager.getBranch === "function"
+        ? sessionManager.getBranch()
+        : sessionManager.getEntries();
       if (!entries || entries.length === 0) {
         ctx.ui.notify("No session entries to analyze.", "error");
         return;

package/extensions/cache-export/tests/run-tests.mjs

@@ -1,5 +1,9 @@
 // Deterministic test cases for analyzeStreaks / analyzeMisses / parseEntries.
 // Run: node --experimental-strip-types tests/run-tests.mjs
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import registerCacheExport from "../index.ts";
 import { parseEntries, analyzeStreaks, analyzeMisses, lineChartForTest } from "../render.ts";
 
 let pass = 0, fail = 0;
@@ -314,6 +318,53 @@ const hitOf = (r) => r.cached / (r.fresh + r.cached + r.cacheWrite);
     s.length === 2 && s.every((x) => x.hits.length === 3), JSON.stringify(s.map((x) => [x.from, x.to])));
 }
 
+// Q. subagent results remain visible as main-session tool input -----------
+{
+  const entries = [
+    req({ cached: 0, fresh: 10000, min: 1, content: [
+      { type: "toolCall", tool: "subagent", name: "subagent" },
+      { type: "toolCall", tool: "bash", name: "bash" },
+    ] }),
+    toolResult("delegated result", "subagent"),
+    toolResult("ordinary result", "bash"),
+    req({ cached: 9000, fresh: 10000, min: 2 }),
+  ];
+  const d = parseEntries(entries);
+  check("Q subagent invocation remains in main-session tool counts",
+    d.toolCalls.some(([name]) => name === "subagent") && d.toolCalls.some(([name]) => name === "bash"),
+    JSON.stringify(d.toolCalls));
+  check("Q subagent result remains available for main fresh-input attribution",
+    d.requests[1].gapTools.length === 2 && d.requests[1].gapTools.some(({ tool }) => tool === "subagent"),
+    JSON.stringify(d.requests[1].gapTools));
+}
+
+// R. command exports only the current main-session branch ----------------
+{
+  const root = mkdtempSync(join(tmpdir(), "cache-export-test-"));
+  const reportFile = join(root, "report.html");
+  const entry = (value, id, parentId) => ({ ...value, id, parentId });
+  const first = entry(req({ cached: 9000, fresh: 1000, min: 1, model: "main-first" }), "p1", null);
+  const abandoned = entry(req({ cached: 0, fresh: 9000, min: 2, model: "abandoned-model" }), "p2", "p1");
+  const active = entry(req({ cached: 8000, fresh: 2000, min: 3, model: "active-model" }), "p3", "p1");
+
+  let command;
+  registerCacheExport({ registerCommand: (name, definition) => { if (name === "cache_export") command = definition; } });
+  await command.handler(reportFile, {
+    sessionManager: {
+      getBranch: () => [first, active],
+      getEntries: () => [first, abandoned, active],
+      getSessionFile: () => join(root, "main.jsonl"),
+      getSessionId: () => "main",
+    },
+    ui: { notify: () => {} },
+  });
+  const html = readFileSync(reportFile, "utf8");
+  check("R current branch excludes abandoned requests",
+    html.includes("2 requests") && html.includes("active-model") && !html.includes("abandoned-model"));
+  check("R main-only report has no subagent dashboard", !html.includes("Subagent cache"));
+  rmSync(root, { recursive: true, force: true });
+}
+
 // K. degenerate inputs ---------------------------------------------------
 {
   check("K empty session -> no crash, no streaks", analyzeStreaks(parseEntries([]).requests).length === 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Personal pi coding agent toolkit: /todos extension + /cache_export interactive cache dashboard.",
   "type": "module",
   "keywords": [
@@ -9,6 +9,7 @@
   ],
   "files": [
     "extensions",
+    "themes",
     "README.md",
     "CHANGELOG.md",
     "global/AGENTS.md",
@@ -22,10 +23,14 @@
   "pi": {
     "extensions": [
       "./extensions/todo.ts",
-      "./extensions/cache-export/index.ts"
+      "./extensions/cache-export/index.ts",
+      "./extensions/btw.ts"
     ],
     "skills": [
       "./skills"
+    ],
+    "themes": [
+      "./themes"
     ]
   },
   "peerDependencies": {
@@ -36,7 +41,9 @@
   },
   "scripts": {
     "test": "cd extensions/cache-export && node --experimental-strip-types tests/run-tests.mjs",
-    "load-test": "pi -ne -e ./extensions/todo.ts && pi -ne -e ./extensions/cache-export/index.ts",
+    "load-test": "pi -ne -e ./extensions/todo.ts && pi -ne -e ./extensions/cache-export/index.ts && pi -ne -e ./extensions/btw.ts",
+    "eval:agents": "node evaluations/agents-md/run.mjs",
+    "eval:agents:test": "node evaluations/agents-md/tests/run-tests.mjs",
     "postinstall": "node scripts/install-agents.mjs"
   },
   "publishConfig": {

package/scripts/install-agents.mjs

@@ -1,15 +1,43 @@
-// postinstall hook: sync the bundled global AGENTS.md to ~/.pi/agent/AGENTS.md
-// (pi's native global context file). Idempotent: writes only when different.
+// postinstall hook: sync the bundled global AGENTS.md and seed the default theme
+// without overriding a theme the user has already selected.
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+const agentDir = join(homedir(), ".pi", "agent");
 const bundled = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "global", "AGENTS.md"), "utf8");
-const target = join(homedir(), ".pi", "agent", "AGENTS.md");
+const agentsTarget = join(agentDir, "AGENTS.md");
+const settingsTarget = join(agentDir, "settings.json");
 
-if (!existsSync(target) || readFileSync(target, "utf8") !== bundled) {
-  mkdirSync(dirname(target), { recursive: true });
-  writeFileSync(target, bundled, "utf8");
-  console.log("[pi-toolkit] global AGENTS.md synced ->", target);
+if (!existsSync(agentsTarget) || readFileSync(agentsTarget, "utf8") !== bundled) {
+  mkdirSync(dirname(agentsTarget), { recursive: true });
+  writeFileSync(agentsTarget, bundled, "utf8");
+  console.log("[pi-toolkit] global AGENTS.md synced ->", agentsTarget);
+}
+
+function writeSettings(settings) {
+  mkdirSync(dirname(settingsTarget), { recursive: true });
+  writeFileSync(settingsTarget, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+}
+
+if (!existsSync(settingsTarget)) {
+  writeSettings({ theme: "nightowl" });
+  console.log("[pi-toolkit] default theme set -> nightowl");
+} else {
+  try {
+    const settings = JSON.parse(readFileSync(settingsTarget, "utf8"));
+    if (!settings || typeof settings !== "object" || Array.isArray(settings)) {
+      throw new Error("settings.json must contain a JSON object");
+    }
+
+    const record = settings;
+    if (typeof record.theme !== "string" || record.theme.length === 0) {
+      record.theme = "nightowl";
+      writeSettings(record);
+      console.log("[pi-toolkit] default theme set -> nightowl");
+    }
+  } catch (error) {
+    console.warn("[pi-toolkit] could not set default theme:", error instanceof Error ? error.message : String(error));
+  }
 }

package/skills/html-artifact/SKILL.md

@@ -1,12 +1,10 @@
 ---
 name: html-artifact
-description: Create self-contained, responsive HTML artifacts for complex explanations that benefit from visual structure or interaction, including workflows, code/module relationships, state machines, event/data flows, architecture maps, timelines, comparisons, dashboards, and interactive demonstrations. Use Markdown for ordinary prose, short answers, diffs, and focused code reviews.
+description: Create self-contained, responsive HTML artifacts for complex explanations that benefit from visual structure or interaction, including workflows, code/module relationships, state machines, event/data flows, architecture maps, timelines, comparisons, dashboards, and interactive demonstrations.
 ---
 
 # HTML Artifact
 
-Use this skill when the user needs to understand or explore a complex process, codebase relationship, system design, state transition, comparison, or other content where static Markdown would be hard to scan or interact with.
-
 ## Decide the format
 
 Use Markdown when the response is short, linear, text-first, or primarily a focused code review. Use an HTML artifact when visual layout, filtering, expanding details, tabs, highlighting, diagrams, timelines, or interactive state changes materially improve understanding.

package/themes/nightowl.json

@@ -0,0 +1,82 @@
+{
+	"$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+	"name": "nightowl",
+	"vars": {
+		"cyan": "#7fdbca",
+		"blue": "#82AAFF",
+		"green": "#c5e478",
+		"red": "#EF5350",
+		"yellow": "#ffcb8b",
+		"magenta": "#c792ea",
+		"gray": "#5f7e97",
+		"dimGray": "#4b6479",
+		"darkGray": "#122d42",
+		"accent": "#80CBC4",
+		"foreground": "#d6deeb",
+		"background": "#011627",
+		"userMsgBg": "#0b2942",
+		"toolPendingBg": "#01111d",
+		"toolSuccessBg": "#0b253a",
+		"toolErrorBg": "#1a1015"
+	},
+	"colors": {
+		"accent": "accent",
+		"border": "blue",
+		"borderAccent": "cyan",
+		"borderMuted": "darkGray",
+		"success": "green",
+		"error": "red",
+		"warning": "yellow",
+		"muted": "gray",
+		"dim": "dimGray",
+		"text": "",
+		"thinkingText": "gray",
+
+		"userMessageBg": "userMsgBg",
+		"userMessageText": "",
+		"toolPendingBg": "toolPendingBg",
+		"toolSuccessBg": "toolSuccessBg",
+		"toolErrorBg": "toolErrorBg",
+		"toolTitle": "",
+		"toolOutput": "gray",
+
+		"selectedBg": "darkGray",
+		"customMessageBg": "userMsgBg",
+		"customMessageText": "",
+		"customMessageLabel": "accent",
+
+		"mdHeading": "blue",
+		"mdLink": "cyan",
+		"mdLinkUrl": "dimGray",
+		"mdCode": "accent",
+		"mdCodeBlock": "green",
+		"mdCodeBlockBorder": "gray",
+		"mdQuote": "gray",
+		"mdQuoteBorder": "gray",
+		"mdHr": "gray",
+		"mdListBullet": "accent",
+
+		"toolDiffAdded": "green",
+		"toolDiffRemoved": "red",
+		"toolDiffContext": "gray",
+
+		"syntaxComment": "#637777",
+		"syntaxKeyword": "magenta",
+		"syntaxFunction": "blue",
+		"syntaxVariable": "cyan",
+		"syntaxString": "#c789d6",
+		"syntaxNumber": "#F78C6C",
+		"syntaxType": "yellow",
+		"syntaxOperator": "cyan",
+		"syntaxPunctuation": "foreground",
+
+		"thinkingOff": "darkGray",
+		"thinkingMinimal": "#234d70",
+		"thinkingLow": "#1d3b53",
+		"thinkingMedium": "#5f7e97",
+		"thinkingHigh": "#7e57c2",
+		"thinkingXhigh": "#c792ea",
+
+		"bashMode": "green"
+	}
+}