@phi-code-admin/phi-code 0.82.3 → 0.84.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## [0.84.0] - 2026-06-14
+
+### Added
+
+- **Four new bundled extensions** (on by default, no install, fully self-contained,
+  vendored from MIT-licensed Pi packages and adapted for phi):
+  - **Goal Mode** (`/goal`): autonomous objective loop. Runs the agent toward a
+    goal, re-continuing after each turn until `goal_complete` or an optional
+    `/goal --tokens` budget is hit. From `@narumitw/pi-goal` (narumitw).
+  - **Todo** (`/todos` + a `todo` tool): persistent task list with a
+    `pending -> in_progress -> completed` state machine and dependency tracking.
+    From `@juicesharp/rpiv-todo` (juicesharp), with its `rpiv-config` helper
+    vendored; 8 UI locales ship.
+  - **Side Questions** (`/btw`): ask a one-off question on a read-only clone of
+    the context without polluting the transcript. From `@juicesharp/rpiv-btw`.
+  - **Chrome** (`/chrome` + `chrome_*` tools): drive your real signed-in Chrome
+    profile after an explicit, time-boxed grant. From `pi-chrome`. Highest-
+    privilege extension: while authorized the agent can act as you in your
+    authenticated browser; grant only for short, supervised tasks.
+
+  Adaptation: imports rewritten to `phi-code` / `phi-code-ai` / `phi-code-tui`,
+  config moved to the phi `configDir` (`.phi`, via `getAgentDir`), MIT LICENSE +
+  attribution kept in each `extensions/phi/<name>/`. No new npm dependencies
+  (typebox already present, rpiv-config vendored, btw/chrome have none).
+
+## [0.83.0] - 2026-06-14
+
+### Added
+
+- **Built-in MCP (Model Context Protocol) client.** phi now ships a bundled MCP
+  extension (`extensions/phi/mcp/`), on by default with no install: connect to any
+  MCP server (Supabase, Playwright, Context7, filesystem, databases, and more)
+  over `stdio`, `streamable-http`, or `sse`, including OAuth for remote servers.
+  Each server's tools are bridged into the agent as `<prefix>_<server>_<tool>`.
+  New commands: `/mcp`, `/mcp <name>`, `/mcp:start`, `/mcp:stop`, `/mcp:auth`.
+
+  Configure servers in `~/.phi/agent/mcp.json` (global) or
+  `<project>/.phi/mcp.json` (project). Vendored from the MIT-licensed
+  `pi-mcp-extension` by irahardianto and adapted for phi: imports resolve via
+  `phi-code`, config uses the phi `configDir` (`.phi`), and it ships bundled
+  instead of requiring `phi install`.
+
+- Dependencies: `@modelcontextprotocol/sdk` and `zod`, used by the bundled MCP
+  extension.
+
 ## [0.82.3] - 2026-06-14
 
 ### Added

package/docs/usage.md

@@ -272,6 +272,6 @@ pi --tools read,grep,find,ls -p "Review the code"
 
 Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
 
-It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
+It bundles MCP support (see the MCP extension) and sub-agents. It does not include permission popups, to-dos, or background bash by default: you can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.
 
 For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).

package/extensions/phi/btw/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 juicesharp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/extensions/phi/btw/btw-ui.ts

@@ -0,0 +1,238 @@
+/**
+ * btw-ui — dynamic-height bottom-slot overlay for /btw.
+ *
+ * Layout (grows with content, bottom-anchored, max = terminal height):
+ *   banner (theme.bg stripe, padded to width)        sticky top
+ *   blank
+ *   history  — "/btw <q>" (accent prefix + muted text), left-padded 2 cols
+ *   echo     — "/btw <q>" (accent prefix + muted text), left-padded 2 cols
+ *   blank
+ *   answer   — body wrapped at width-2, left-padded 2 cols
+ *   blank
+ *   footer   — key hints (dim)                       sticky bottom
+ *
+ * Natural height = fixed(5: banner, 3 blanks, footer) + 2 (echo + 1 blank before answer)
+ *                  + history.length + answerLines.length.
+ * Pi-tui bottom-anchors the overlay so it grows upward with each /btw message.
+ * If natural height > terminal rows, we clip from the top (older history scrolls off)
+ * and ↑/↓ scroll the clip window.
+ *
+ * Keys (via matchesKey — handles ANSI + Kitty):
+ *   Esc → abort in-flight call + dismiss
+ *   ↑/↓ → scroll (when content exceeds terminal)
+ *   x   → clear current-session /btw history
+ *   (f fork key deferred)
+ */
+
+import type { ExtensionCommandContext, Theme } from "phi-code";
+import type { OverlayOptions } from "phi-code-tui";
+import {
+	type Component,
+	Key,
+	matchesKey,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "phi-code-tui";
+import { type BtwTurn, userMessageText } from "./btw.js";
+
+const BTW_MAX_HEIGHT_RATIO = 0.85;
+
+const BTW_OVERLAY_OPTIONS: OverlayOptions = {
+	anchor: "bottom-center",
+	width: "100%",
+	maxHeight: `${BTW_MAX_HEIGHT_RATIO * 100}%`,
+	margin: { left: 0, right: 0, bottom: 0 },
+};
+
+const SIDE_PAD = "  "; // 2-col left gutter for history, echo, footer
+const ANSWER_PAD = "    "; // 4-col left gutter for answer body (double of SIDE_PAD)
+const BTW_LITERAL = "/btw";
+const PENDING_GLYPH = "…";
+const FOOTER_SCROLL = "↑/↓ to scroll";
+const FOOTER_CLEAR = "x to clear history";
+const FOOTER_DISMISS = "Esc to dismiss";
+const FOOTER_SEP = " · ";
+
+type Mode = "pending" | "answer" | "error";
+
+export interface ShowBtwOverlayParams {
+	ctx: ExtensionCommandContext;
+	question: string;
+	history: BtwTurn[];
+	controller: AbortController;
+	onClearHistory: () => void;
+}
+
+export interface ShowBtwOverlayResult {
+	overlayPromise: Promise<void>;
+	controllerReady: Promise<BtwOverlayController>;
+}
+
+export class BtwOverlayController implements Component {
+	private mode: Mode = "pending";
+	private answer = "";
+	private error = "";
+	private scrollOffset = 0;
+	private history: BtwTurn[];
+
+	constructor(
+		private readonly question: string,
+		history: BtwTurn[],
+		private readonly theme: Theme,
+		private readonly tui: TUI,
+		private readonly done: (result?: undefined) => void,
+		private readonly controller: AbortController,
+		private readonly onClearHistory: () => void,
+	) {
+		this.history = [...history];
+	}
+
+	setAnswer(text: string): void {
+		this.mode = "answer";
+		this.answer = text;
+		this.tui.requestRender();
+	}
+
+	setError(message: string): void {
+		this.mode = "error";
+		this.error = message;
+		this.tui.requestRender();
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, Key.escape)) {
+			this.controller.abort();
+			this.done();
+			return;
+		}
+		if (matchesKey(data, Key.up)) {
+			this.scrollOffset = Math.max(0, this.scrollOffset - 1);
+			this.tui.requestRender();
+			return;
+		}
+		if (matchesKey(data, Key.down)) {
+			this.scrollOffset = this.scrollOffset + 1;
+			this.tui.requestRender();
+			return;
+		}
+		if (data === "x") {
+			this.history = [];
+			this.onClearHistory();
+			this.scrollOffset = 0;
+			this.tui.requestRender();
+			return;
+		}
+	}
+
+	render(width: number): string[] {
+		const banner = this.renderBanner(width);
+		const historyLines = this.history.map((h) => this.historyLine(userMessageText(h.userMessage), width));
+		const echoLine = this.echoLine(this.question, width);
+		const answerLines = this.renderAnswer(width);
+		const footerAvail = Math.max(1, width - SIDE_PAD.length);
+		const footerParts: string[] = [];
+		if (this.mode !== "pending") footerParts.push(FOOTER_SCROLL);
+		if (this.history.length > 0) footerParts.push(FOOTER_CLEAR);
+		footerParts.push(FOOTER_DISMISS);
+		const footer =
+			SIDE_PAD + truncateToWidth(this.theme.fg("dim", footerParts.join(FOOTER_SEP)), footerAvail, "…", false);
+
+		// Natural content: banner + blank + history + echo + blank + answer + blank + footer
+		const natural: string[] = [banner, "", ...historyLines, echoLine, "", ...answerLines, "", footer];
+
+		// Clip to terminal height if we overflow. Bottom-anchor keeps footer+answer visible;
+		// ↑/↓ scrolls the top (history) up into the clipped region.
+		const termRows = (this.tui.terminal as { rows?: number }).rows ?? 24;
+		const maxRows = Math.max(4, Math.floor(termRows * BTW_MAX_HEIGHT_RATIO));
+		if (natural.length <= maxRows) {
+			return natural;
+		}
+		const excess = natural.length - maxRows;
+		if (this.scrollOffset > excess) this.scrollOffset = excess;
+		// scrollOffset=0 shows the BOTTOM (newest). Scrolling up reveals older history.
+		const start = excess - this.scrollOffset;
+		return natural.slice(start, start + maxRows);
+	}
+
+	invalidate(): void {
+		// no-op — render recomputes from state each cycle
+	}
+
+	private renderBanner(width: number): string {
+		const prefix = `${SIDE_PAD}${BTW_LITERAL} `;
+		const prefixWidth = visibleWidth(prefix);
+		const qAvail = Math.max(0, width - prefixWidth);
+		const qTrunc = truncateToWidth(this.question, qAvail, "…", false);
+		const raw = prefix + qTrunc;
+		const padded = raw + " ".repeat(Math.max(0, width - visibleWidth(raw)));
+		return this.theme.bg("customMessageBg", this.theme.fg("customMessageText", padded));
+	}
+
+	private historyLine(question: string, width: number): string {
+		const qAvail = Math.max(0, width - SIDE_PAD.length);
+		const qClean = question.replace(/\s+/g, " ").trim();
+		const raw = `${BTW_LITERAL} ${qClean}`;
+		const trunc = truncateToWidth(raw, qAvail, "…", false);
+		return SIDE_PAD + this.theme.fg("muted", trunc);
+	}
+
+	private echoLine(question: string, width: number): string {
+		const bodyAvail = Math.max(1, width - SIDE_PAD.length);
+		const prefixWidth = visibleWidth(BTW_LITERAL) + 1; // "/btw "
+		const qAvail = Math.max(0, bodyAvail - prefixWidth);
+		const qClean = question.replace(/\s+/g, " ").trim();
+		const qTrunc = truncateToWidth(qClean, qAvail, "…", false);
+		return `${SIDE_PAD + this.theme.fg("accent", BTW_LITERAL)} ${this.theme.fg("muted", qTrunc)}`;
+	}
+
+	private wrapBodyLines(text: string, bodyWidth: number, colorFn?: (s: string) => string): string[] {
+		const out: string[] = [];
+		for (const ln of text.split("\n")) {
+			const src = ln.length === 0 ? " " : ln;
+			const colored = colorFn ? colorFn(src) : src;
+			out.push(...wrapTextWithAnsi(colored, bodyWidth));
+		}
+		return out;
+	}
+
+	private renderAnswer(width: number): string[] {
+		const bodyWidth = Math.max(1, width - ANSWER_PAD.length);
+		const indent = (lines: string[]) => lines.map((l) => ANSWER_PAD + l);
+
+		if (this.mode === "pending") {
+			return indent([this.theme.fg("warning", PENDING_GLYPH)]);
+		}
+		if (this.mode === "error") {
+			return indent(this.wrapBodyLines(this.error, bodyWidth, (s) => this.theme.fg("error", s)));
+		}
+		return indent(this.wrapBodyLines(this.answer, bodyWidth));
+	}
+}
+
+export function showBtwOverlay(params: ShowBtwOverlayParams): ShowBtwOverlayResult {
+	let resolveReady!: (controller: BtwOverlayController) => void;
+	const controllerReady = new Promise<BtwOverlayController>((resolve) => {
+		resolveReady = resolve;
+	});
+
+	const overlayPromise = params.ctx.ui.custom<void>(
+		(tui, theme, _kb, done) => {
+			const controller = new BtwOverlayController(
+				params.question,
+				params.history,
+				theme,
+				tui,
+				done,
+				params.controller,
+				params.onClearHistory,
+			);
+			resolveReady(controller);
+			return controller;
+		},
+		{ overlay: true, overlayOptions: BTW_OVERLAY_OPTIONS },
+	);
+
+	return { overlayPromise, controllerReady };
+}

package/extensions/phi/btw/btw.ts

@@ -0,0 +1,363 @@
+/**
+ * @juicesharp/rpiv-btw — /btw side-question slash command.
+ *
+ * Asks the same primary model a one-off side question using the cloned primary
+ * conversation as context. Answer is rendered ephemerally in a bottom-slot
+ * overlay (never enters main agent's messages). History persists per-session-file
+ * via globalThis-keyed storage; process-scoped only (no disk persistence).
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import {
+	type AssistantMessage,
+	completeSimple,
+	type Message,
+	type StopReason,
+	type UserMessage,
+} from "phi-code-ai";
+import {
+	convertToLlm,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+	type ExtensionContext,
+	type SessionEntry,
+} from "phi-code";
+import { showBtwOverlay } from "./btw-ui.js";
+
+// ---------------------------------------------------------------------------
+// Constants — flat named consts, grouped by concern (advisor pattern, b9428e9)
+// ---------------------------------------------------------------------------
+
+// Identity
+export const BTW_COMMAND_NAME = "btw";
+
+// Storage — globalThis-keyed survives module re-import on /new, /fork, /resume.
+// Lost on Pi process exit (intentional — no disk persistence).
+export const BTW_STATE_KEY = Symbol.for("rpiv-btw");
+
+// Cross-session pattern hint: how many recent question-strings to inject
+export const CROSS_SESSION_HINT_LIMIT = 10;
+
+// Messages (static)
+const MSG_REQUIRES_INTERACTIVE = "/btw requires interactive mode";
+const MSG_USAGE = "Usage: /btw <question>";
+const MSG_NO_MODEL = "/btw requires an active model";
+
+// Errors (static)
+const ERR_EMPTY_RESPONSE = "/btw returned no text content.";
+
+// Errors (parameterized)
+const errMisconfigured = (label: string, err: string) => `/btw model (${label}) is misconfigured: ${err}`;
+const errNoApiKey = (label: string) => `/btw model (${label}) has no API key available.`;
+const errCallFailed = (err: string | undefined) => `/btw call failed: ${err ?? "unknown error"}`;
+const errCallThrew = (msg: string) => `/btw call threw: ${msg}`;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+// Real messages — no fabrication. userMessage is built at call time; assistantMessage
+// is the unmodified completeSimple response. Stable object references across calls →
+// byte-identical prompt prefix on subsequent /btw invocations (cache parity).
+export interface BtwTurn {
+	userMessage: UserMessage;
+	assistantMessage: AssistantMessage;
+}
+
+interface BtwState {
+	histories: Map<string, BtwTurn[]>;
+	snapshots: Map<string, { messages: Message[] }>;
+}
+
+function branchToMessages(branch: SessionEntry[]): Message[] {
+	const agentMessages = branch
+		.filter((e): e is SessionEntry & { type: "message" } => e.type === "message")
+		.map((e) => e.message);
+	return convertToLlm(agentMessages);
+}
+
+// ---------------------------------------------------------------------------
+// System prompt — loaded once at module init from prompts/btw-system.txt
+// ---------------------------------------------------------------------------
+
+export const BTW_SYSTEM_PROMPT = readFileSync(
+	fileURLToPath(new URL("./prompts/btw-system.txt", import.meta.url)),
+	"utf-8",
+).trimEnd();
+
+// ---------------------------------------------------------------------------
+// Storage — globalThis-keyed, survives module re-import on /new, /fork, /resume.
+// Standard Node.js `globalThis + Symbol.for()` idiom for cross-import-graph
+// singleton state (used by OpenTelemetry, etc.); lost on process exit.
+// ---------------------------------------------------------------------------
+
+function getState(): BtwState {
+	const g = globalThis as unknown as { [k: symbol]: BtwState | undefined };
+	let state = g[BTW_STATE_KEY];
+	if (!state) {
+		state = {
+			histories: new Map(),
+			snapshots: new Map(),
+		};
+		g[BTW_STATE_KEY] = state;
+	}
+	return state;
+}
+
+function getSessionFile(ctx: ExtensionContext): string {
+	return ctx.sessionManager.getSessionFile() ?? `memory:${ctx.sessionManager.getSessionId()}`;
+}
+
+function getSessionHistory(ctx: ExtensionContext): BtwTurn[] {
+	const key = getSessionFile(ctx);
+	const state = getState();
+	let turns = state.histories.get(key);
+	if (!turns) {
+		turns = [];
+		state.histories.set(key, turns);
+	}
+	return turns;
+}
+
+function pushSessionTurn(ctx: ExtensionContext, turn: BtwTurn): void {
+	getSessionHistory(ctx).push(turn);
+}
+
+export function clearSessionHistory(ctx: ExtensionContext): void {
+	getState().histories.set(getSessionFile(ctx), []);
+}
+
+function getSnapshot(ctx: ExtensionContext): { messages: Message[] } | undefined {
+	return getState().snapshots.get(getSessionFile(ctx));
+}
+
+function setSnapshot(ctx: ExtensionContext, snapshot: { messages: Message[] }): void {
+	getState().snapshots.set(getSessionFile(ctx), snapshot);
+}
+
+export function invalidateSnapshot(ctx: ExtensionContext): void {
+	getState().snapshots.delete(getSessionFile(ctx));
+}
+
+// Extract text from a UserMessage's content.
+export function userMessageText(msg: UserMessage): string {
+	if (typeof msg.content === "string") return msg.content;
+	return msg.content
+		.filter((c): c is { type: "text"; text: string } => c.type === "text")
+		.map((c) => c.text)
+		.join("\n");
+}
+
+// Extract text from an AssistantMessage's content (text parts only).
+export function assistantMessageText(msg: AssistantMessage): string {
+	return msg.content
+		.filter((c): c is { type: "text"; text: string } => c.type === "text")
+		.map((c) => c.text)
+		.join("\n");
+}
+
+// Cross-session pattern hint — last N question-strings across ALL sessions.
+function getCrossSessionHint(): string {
+	const allTurns: { q: string; ts: number }[] = [];
+	for (const turns of getState().histories.values()) {
+		for (const t of turns) {
+			allTurns.push({ q: userMessageText(t.userMessage), ts: t.userMessage.timestamp });
+		}
+	}
+	if (allTurns.length === 0) return "";
+	const recent = allTurns.sort((a, b) => a.ts - b.ts).slice(-CROSS_SESSION_HINT_LIMIT);
+	const lines = recent.map((t, i) => `${i + 1}. ${t.q.replace(/\s+/g, " ").slice(0, 200)}`);
+	return `\n\n## Recent /btw questions across sessions (oldest first)\n\n${lines.join("\n")}`;
+}
+
+// ---------------------------------------------------------------------------
+// Executor — auth, message threading, completeSimple, four StopReason branches
+// Modeled after rpiv-advisor/advisor.ts:225-336
+// ---------------------------------------------------------------------------
+
+export type BtwExecResult =
+	| { ok: true; answer: string; userMessage: UserMessage; assistantMessage: AssistantMessage; stopReason: StopReason }
+	| { ok: false; error: string; stopReason?: StopReason }
+	| { ok: false; aborted: true; stopReason: StopReason };
+
+function readBranchMessages(ctx: ExtensionContext): Message[] {
+	const cached = getSnapshot(ctx);
+	if (cached) return cached.messages;
+	// Cold start (no message_end fired yet) — fall back to live read
+	const branch = ctx.sessionManager.getBranch() as SessionEntry[];
+	return branchToMessages(branch);
+}
+
+function buildBtwMessages(ctx: ExtensionContext, userMessage: UserMessage): Message[] {
+	const branchMessages = readBranchMessages(ctx);
+	const history = getSessionHistory(ctx);
+	// Reusing stored real UserMessage/AssistantMessage object references across calls
+	// preserves byte-identical prompt prefix (cache parity).
+	const historyMessages: Message[] = history.flatMap((h) => [h.userMessage, h.assistantMessage]);
+	return [...branchMessages, ...historyMessages, userMessage];
+}
+
+function buildSystemPrompt(): string {
+	return BTW_SYSTEM_PROMPT + getCrossSessionHint();
+}
+
+export async function executeBtw(
+	question: string,
+	ctx: ExtensionContext,
+	controller: AbortController,
+): Promise<BtwExecResult> {
+	const model = ctx.model;
+	if (!model) {
+		return { ok: false, error: MSG_NO_MODEL };
+	}
+	const modelLabel = `${model.provider}:${model.id}`;
+
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (!auth.ok) {
+		return { ok: false, error: errMisconfigured(modelLabel, auth.error) };
+	}
+	if (!auth.apiKey) {
+		return { ok: false, error: errNoApiKey(modelLabel) };
+	}
+
+	const userMessage: UserMessage = {
+		role: "user",
+		content: [{ type: "text", text: question }],
+		timestamp: Date.now(),
+	};
+	const messages = buildBtwMessages(ctx, userMessage);
+	const systemPrompt = buildSystemPrompt();
+
+	try {
+		const response = await completeSimple(
+			model,
+			{ systemPrompt, messages, tools: [] },
+			{
+				apiKey: auth.apiKey,
+				headers: auth.headers,
+				signal: controller.signal, // own AbortController, NOT ctx.signal (Decision 8)
+			},
+		);
+
+		if (response.stopReason === "aborted") {
+			return { ok: false, aborted: true, stopReason: response.stopReason };
+		}
+		if (response.stopReason === "error") {
+			return {
+				ok: false,
+				error: errCallFailed(response.errorMessage),
+				stopReason: response.stopReason,
+			};
+		}
+
+		const answerText = assistantMessageText(response).trim();
+		if (!answerText) {
+			return { ok: false, error: ERR_EMPTY_RESPONSE, stopReason: response.stopReason };
+		}
+
+		return {
+			ok: true,
+			answer: answerText,
+			userMessage,
+			assistantMessage: response,
+			stopReason: response.stopReason,
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		if (controller.signal.aborted) {
+			return { ok: false, aborted: true, stopReason: "aborted" as const };
+		}
+		return { ok: false, error: errCallThrew(message) };
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Registrars — 3 hooks total: command + message_end snapshot + compact/tree invalidate
+// ---------------------------------------------------------------------------
+
+export function registerMessageEndSnapshot(pi: ExtensionAPI): void {
+	pi.on("message_end", async (event, ctx) => {
+		const msg = event.message;
+		if (msg.role !== "assistant") return;
+		if ((msg as AssistantMessage).stopReason === "toolUse") return;
+		const branch = ctx.sessionManager.getBranch() as SessionEntry[];
+		setSnapshot(ctx, { messages: branchToMessages(branch) });
+	});
+}
+
+export function registerInvalidationHooks(pi: ExtensionAPI): void {
+	pi.on("session_compact", async (_e, ctx) => safeInvalidateSnapshot(ctx));
+	pi.on("session_tree", async (_e, ctx) => safeInvalidateSnapshot(ctx));
+}
+
+// Auto-compaction races session disposal: pi-core invalidates the extension
+// runner while still emitting session_compact, so `ctx` may be a dead proxy
+// whose getters throw the stale error. The compacting session is being
+// discarded — there is no snapshot worth invalidating — so swallow only the
+// stale error. Any other error is a real bug and must propagate.
+function safeInvalidateSnapshot(ctx: ExtensionContext): void {
+	try {
+		invalidateSnapshot(ctx);
+	} catch (e) {
+		if (!isStaleCtxError(e)) throw e;
+	}
+}
+
+// pi-core's ExtensionRunner throws this exact phrase from an invalidated ctx
+// proxy after session replacement/reload. Match the stable substring.
+function isStaleCtxError(e: unknown): boolean {
+	return /stale after session replacement/.test(String(e));
+}
+
+export function registerBtwCommand(pi: ExtensionAPI): void {
+	pi.registerCommand(BTW_COMMAND_NAME, {
+		description: "Ask a side question without polluting the main conversation",
+		handler: (args: string, ctx: ExtensionCommandContext) => handleBtwCommand(pi, args, ctx),
+	});
+}
+
+async function handleBtwCommand(_pi: ExtensionAPI, args: string, ctx: ExtensionCommandContext): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify(MSG_REQUIRES_INTERACTIVE, "error");
+		return;
+	}
+	const question = args.trim();
+	if (!question) {
+		ctx.ui.notify(MSG_USAGE, "warning");
+		return;
+	}
+	if (!ctx.model) {
+		ctx.ui.notify(MSG_NO_MODEL, "error");
+		return;
+	}
+
+	const controller = new AbortController();
+	const historySnapshot = [...getSessionHistory(ctx)];
+
+	const { overlayPromise, controllerReady } = showBtwOverlay({
+		ctx,
+		question,
+		history: historySnapshot,
+		controller,
+		onClearHistory: () => clearSessionHistory(ctx),
+	});
+
+	const overlayCtl = await controllerReady;
+	const result = await executeBtw(question, ctx, controller);
+
+	if (result.ok) {
+		overlayCtl.setAnswer(result.answer);
+		pushSessionTurn(ctx, {
+			userMessage: result.userMessage,
+			assistantMessage: result.assistantMessage,
+		});
+		// No disk persistence — process-scoped only (Decision 4)
+	} else if ("aborted" in result) {
+		// User Esc'd — overlay already dismissed via done(); no further action
+	} else {
+		overlayCtl.setError(result.error);
+	}
+
+	await overlayPromise;
+}