@xynogen/pix-commands 0.1.7 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xynogen
+
+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/README.md

@@ -1,12 +1,32 @@
 # pix-commands
 
-Pi extension — slash commands. `/clear`; more commands are planned.
+Pi extension providing focused slash commands:
 
-## What it does
+- `/clear` — flush Pi's cached model data.
+- `/btw <question>` — ask an isolated side question without interrupting the main agent.
 
-Registers slash commands. Currently `/clear`, which deletes `~/.cache/pi` — useful for flushing stale model-data cache — and prompts you to run `/reload` to apply the change. **More commands are on the way.** No extra dependencies beyond Pi.
+## `/clear`
 
-> Diff review moved to the `diff` skill in [`@xynogen/pix-skills`](https://github.com/xynogen/pix-mono/tree/main/packages/pix-skills), which pre-populates `git status` + staged/unstaged diffs via the `` !`cmd` `` directive.
+Deletes `~/.cache/pi` to flush stale model-data cache, then prompts you to run `/reload`.
+
+## `/btw`
+
+`/btw` runs a separate in-memory child session concurrently with the main agent:
+
+```text
+/btw what is the difference between a mutex and a semaphore?
+```
+
+The child session:
+
+- starts with an empty conversation and a lean Pix system prompt;
+- snapshots the main session's model, thinking level, active tools, credentials, extensions, and working directory;
+- never imports the main conversation;
+- publishes its Markdown answer in a visually distinct side-thread card;
+- keeps rendered BTW answers out of future main-agent LLM context;
+- supports multiple concurrent side questions.
+
+When the main agent is streaming, completion is shown as a notification and the durable card is appended after the main session becomes idle. This prevents the side answer from becoming steering input.
 
 ## Install
 
@@ -24,7 +44,7 @@ pi install npm:@xynogen/pix-commands
 
 Source: [github.com/xynogen/pix-mono](https://github.com/xynogen/pix-mono)
 
-To install the complete pix suite (all packages + Pi itself):
+To install the complete pix suite:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@xynogen/pix-commands",
-	"version": "0.1.7",
-	"description": "Pi extension — slash commands (/clear; more planned)",
+	"version": "0.2.0",
+	"description": "Pi extension — slash commands for cache clearing and isolated side questions",
 	"type": "module",
 	"main": "src/index.ts",
 	"scripts": {
@@ -21,7 +21,9 @@
 		"pi",
 		"pi-package",
 		"pi-extension",
-		"pix"
+		"pix",
+		"side-question",
+		"concurrent"
 	],
 	"author": "xynogen",
 	"license": "MIT",
@@ -38,6 +40,8 @@
 		"access": "public"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": "*"
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
 	}
 }

package/src/btw/index.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { filterBtwMessages, shortModelName, summarizeLiveText } from "./index.ts";
+
+describe("BTW display helpers", () => {
+	test("prefers model display name and falls back to id", () => {
+		expect(shortModelName({ id: "id", name: "Friendly" })).toBe("Friendly");
+		expect(shortModelName({ id: "id", name: "  " })).toBe("id");
+	});
+
+	test("summarizes streaming output on one bounded line", () => {
+		expect(summarizeLiveText("hello\n\nworld", 20)).toBe("hello world");
+		expect(summarizeLiveText("abcdefghij", 6)).toBe("abcde…");
+		expect(summarizeLiveText("   ")).toBe("thinking…");
+	});
+
+	test("filters BTW cards from LLM context without affecting the transcript", () => {
+		const messages = [
+			{ role: "user", content: "main question" },
+			{ role: "custom", customType: "pix-btw-answer", content: "aside" },
+			{ role: "custom", customType: "other", content: "keep" },
+		];
+		expect(filterBtwMessages(messages)).toEqual([
+			{ role: "user", content: "main question" },
+			{ role: "custom", customType: "other", content: "keep" },
+		]);
+		expect(messages).toHaveLength(3);
+	});
+});

package/src/btw/index.ts

@@ -0,0 +1,234 @@
+import type {
+	AgentSession,
+	ExtensionAPI,
+	ExtensionCommandContext,
+	Theme,
+} from "@earendil-works/pi-coding-agent";
+import { Text, type TUI } from "@earendil-works/pi-tui";
+import { type BtwMessageDetails, registerBtwRenderer } from "./render.ts";
+import { runBtw, snapshotMainSettings } from "./session.ts";
+
+const STATUS_KEY = "pix-btw";
+const WIDGET_KEY = "pix-btw-live";
+
+interface BtwJob {
+	id: number;
+	question: string;
+	model: string;
+	startedAt: number;
+	status: "running" | "completed" | "error" | "stopped";
+	text: string;
+	activeTools: Set<string>;
+	toolUses: number;
+	session?: AgentSession;
+	error?: string;
+}
+
+export function shortModelName(model: { name?: string; id: string }): string {
+	return model.name?.trim() || model.id;
+}
+
+export function summarizeLiveText(text: string, max = 100): string {
+	const first = text.replace(/\s+/g, " ").trim();
+	if (!first) return "thinking…";
+	return first.length > max ? `${first.slice(0, Math.max(1, max - 1))}…` : first;
+}
+
+/** Keep rendered BTW cards out of every agent's LLM conversation context. */
+export function filterBtwMessages<T>(messages: T[]): T[] {
+	return messages.filter((message) => {
+		const candidate = message as { role?: string; customType?: string };
+		return !(candidate.role === "custom" && candidate.customType === "pix-btw-answer");
+	});
+}
+
+export function registerBtw(pi: ExtensionAPI): void {
+	registerBtwRenderer(pi);
+
+	const jobs = new Map<number, BtwJob>();
+	let nextId = 1;
+	let latestUi: ExtensionCommandContext["ui"] | undefined;
+	let refreshTimer: ReturnType<typeof setInterval> | undefined;
+
+	const renderJobs = (theme: Theme): string[] => {
+		const running = [...jobs.values()].filter((job) => job.status === "running");
+		if (running.length === 0) return [];
+		const lines = [theme.fg("accent", `○ BTW (${running.length})`)];
+		for (const job of running.slice(-4)) {
+			const elapsed = ((Date.now() - job.startedAt) / 1_000).toFixed(1);
+			const activity =
+				job.activeTools.size > 0
+					? [...job.activeTools].map((name) => `using ${name}`).join(", ")
+					: summarizeLiveText(job.text);
+			lines.push(theme.fg("dim", `└─ #${job.id} [${job.model}] · ${elapsed}s · ${activity}`));
+		}
+		return lines;
+	};
+
+	const updateUi = () => {
+		if (!latestUi) return;
+		const running = [...jobs.values()].filter((job) => job.status === "running");
+		if (running.length === 0) {
+			latestUi.setStatus(STATUS_KEY, undefined);
+			latestUi.setWidget(WIDGET_KEY, undefined);
+			if (refreshTimer) clearInterval(refreshTimer);
+			refreshTimer = undefined;
+			return;
+		}
+		latestUi.setStatus(STATUS_KEY, `BTW ${running.length}`);
+		latestUi.setWidget(
+			WIDGET_KEY,
+			(tui: TUI, theme: Theme) => {
+				const text = new Text("", 0, 0);
+				return {
+					render: (width: number) => {
+						text.setText(renderJobs(theme).join("\n"));
+						return text.render(width || tui.terminal.columns);
+					},
+					invalidate: () => text.invalidate(),
+				};
+			},
+			{ placement: "aboveEditor" },
+		);
+		refreshTimer ??= setInterval(updateUi, 100);
+	};
+
+	const publish = async (job: BtwJob, details: BtwMessageDetails, ctx: ExtensionCommandContext) => {
+		job.session?.dispose();
+		job.session = undefined;
+		updateUi();
+
+		// Sending a custom message while the main agent streams would enqueue it
+		// as a steer and leak the side answer into the in-flight task. Surface the
+		// result immediately as a UI notification, then wait to append the durable
+		// rendered transcript card until the main agent is idle.
+		if (!ctx.isIdle()) {
+			ctx.ui.notify(
+				details.error
+					? `BTW #${job.id} failed: ${details.error}`
+					: `BTW #${job.id} complete\n\n${details.answer}`,
+				details.error ? "error" : "info",
+			);
+			await ctx.waitForIdle();
+		}
+
+		pi.sendMessage<BtwMessageDetails>({
+			customType: "pix-btw-answer",
+			content: details.error
+				? `BTW question failed: ${details.error}`
+				: `BTW answer to “${details.question}”:\n\n${details.answer}`,
+			display: true,
+			details,
+		});
+	};
+
+	pi.on("context", (event) => ({ messages: filterBtwMessages(event.messages) }));
+
+	pi.registerCommand("btw", {
+		description: "Ask an isolated side question without interrupting the main agent",
+		handler: async (rawArgs, ctx) => {
+			const question = rawArgs.trim();
+			latestUi = ctx.ui;
+			if (!question) {
+				ctx.ui.notify("Usage: /btw <question>", "warning");
+				return;
+			}
+
+			let snapshot: ReturnType<typeof snapshotMainSettings>;
+			try {
+				snapshot = snapshotMainSettings(ctx, pi.getThinkingLevel(), pi.getActiveTools());
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+				return;
+			}
+
+			const id = nextId++;
+			const job: BtwJob = {
+				id,
+				question,
+				model: shortModelName(snapshot.model),
+				startedAt: Date.now(),
+				status: "running",
+				text: "",
+				activeTools: new Set(),
+				toolUses: 0,
+			};
+			jobs.set(id, job);
+			updateUi();
+			ctx.ui.notify(`BTW #${id} started — the main agent will keep running.`, "info");
+
+			void runBtw({
+				question,
+				snapshot,
+				ctx,
+				onSession: (session) => {
+					job.session = session;
+				},
+				onTextDelta: (_delta, fullText) => {
+					job.text = fullText;
+				},
+				onToolStart: (name) => {
+					job.activeTools.add(name);
+				},
+				onToolEnd: (name) => {
+					job.activeTools.delete(name);
+					job.toolUses++;
+				},
+			})
+				.then(({ text, session }) => {
+					job.status = "completed";
+					job.text = text;
+					job.session = session;
+					void publish(
+						job,
+						{
+							question,
+							answer: text || "No answer returned.",
+							model: job.model,
+							thinkingLevel: snapshot.thinkingLevel,
+							durationMs: Date.now() - job.startedAt,
+							toolUses: job.toolUses,
+						},
+						ctx,
+					).catch(() => {});
+				})
+				.catch((error) => {
+					job.status = "error";
+					job.error = error instanceof Error ? error.message : String(error);
+					void publish(
+						job,
+						{
+							question,
+							answer: "",
+							model: job.model,
+							thinkingLevel: snapshot.thinkingLevel,
+							durationMs: Date.now() - job.startedAt,
+							toolUses: job.toolUses,
+							error: job.error,
+						},
+						ctx,
+					).catch(() => {});
+				});
+		},
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		latestUi = ctx.ui;
+		updateUi();
+	});
+
+	pi.on("session_shutdown", () => {
+		if (refreshTimer) clearInterval(refreshTimer);
+		refreshTimer = undefined;
+		latestUi?.setStatus(STATUS_KEY, undefined);
+		latestUi?.setWidget(WIDGET_KEY, undefined);
+		for (const job of jobs.values()) {
+			if (job.status === "running") {
+				job.status = "stopped";
+				void job.session?.abort();
+			}
+			job.session?.dispose();
+		}
+		jobs.clear();
+	});
+}

package/src/btw/render.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from "bun:test";
+import { type ExtensionAPI, initTheme } from "@earendil-works/pi-coding-agent";
+import { type BtwMessageDetails, formatDuration, registerBtwRenderer } from "./render.ts";
+
+const stripAnsi = (text: string) => text.replace(/\x1b\[[0-9;]*m/g, "");
+
+function captureRenderer() {
+	let renderer: ((message: unknown, options: unknown, theme: unknown) => unknown) | undefined;
+	const pi = {
+		registerMessageRenderer(_name: string, fn: typeof renderer) {
+			renderer = fn;
+		},
+	} as unknown as ExtensionAPI;
+	registerBtwRenderer(pi);
+	if (!renderer) throw new Error("renderer was not registered");
+	return renderer;
+}
+
+const backgrounds: string[] = [];
+const theme = {
+	fg: (_color: string, text: string) => text,
+	bg: (color: string, text: string) => {
+		backgrounds.push(color);
+		return text;
+	},
+	bold: (text: string) => text,
+};
+
+function render(details: BtwMessageDetails): string {
+	const renderer = captureRenderer();
+	const component = renderer({ details, content: details.answer }, { expanded: false }, theme) as {
+		render(width: number): string[];
+	};
+	return stripAnsi(component.render(80).join("\n"));
+}
+
+describe("BTW renderer", () => {
+	test("formats durations compactly", () => {
+		expect(formatDuration(450)).toBe("450ms");
+		expect(formatDuration(2_100)).toBe("2.1s");
+		expect(formatDuration(65_000)).toBe("1m 5s");
+	});
+
+	test("renders metadata and question as distinct side-thread card chrome", () => {
+		backgrounds.length = 0;
+		const output = render({
+			question: "hello",
+			answer: "Hi!",
+			model: "GPT-5.6",
+			thinkingLevel: "high",
+			durationMs: 2_100,
+			toolUses: 0,
+		});
+		expect(output).toContain("✓ BTW · GPT-5.6 · high · 2.1s");
+		expect(output).toContain("▐ hello");
+		expect(output).not.toContain("SIDE THREAD");
+		expect(backgrounds).toContain("selectedBg");
+		expect(backgrounds).not.toContain("customMessageBg");
+	});
+
+	test("renders the answer as Markdown", () => {
+		initTheme();
+		const output = render({
+			question: "show markdown",
+			answer: "## Heading\n\n- alpha\n- beta\n\n`code`",
+			model: "Model",
+			thinkingLevel: "medium",
+			durationMs: 1_000,
+			toolUses: 1,
+		});
+		expect(output).toContain("Heading");
+		expect(output).toContain("alpha");
+		expect(output).toContain("beta");
+		expect(output).toContain("code");
+	});
+});

package/src/btw/render.ts

@@ -0,0 +1,62 @@
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Box, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+
+export interface BtwMessageDetails {
+	question: string;
+	answer: string;
+	model: string;
+	thinkingLevel: string;
+	durationMs: number;
+	toolUses: number;
+	error?: string;
+}
+
+export function formatDuration(ms: number): string {
+	if (ms < 1_000) return `${ms}ms`;
+	if (ms < 60_000) return `${(ms / 1_000).toFixed(ms < 10_000 ? 1 : 0)}s`;
+	return `${Math.floor(ms / 60_000)}m ${Math.round((ms % 60_000) / 1_000)}s`;
+}
+
+export function registerBtwRenderer(
+	pi: Pick<import("@earendil-works/pi-coding-agent").ExtensionAPI, "registerMessageRenderer">,
+): void {
+	pi.registerMessageRenderer<BtwMessageDetails>("pix-btw-answer", (message, _options, theme) => {
+		const details = message.details;
+		if (!details) return undefined;
+		const failed = Boolean(details.error);
+		const icon = failed ? theme.fg("error", "✗") : theme.fg("success", "✓");
+		const meta = [details.model, details.thinkingLevel, formatDuration(details.durationMs)];
+		if (details.toolUses > 0) meta.push(`${details.toolUses} tools`);
+
+		// A custom renderer bypasses Pi's default custom-message box, so provide
+		// our own card. Use selectedBg rather than the generic custom-message
+		// background: it is intentionally more prominent across Pi themes, which
+		// keeps this isolated side thread visually distinct from the main thread.
+		// Keep chrome as Text and render only the answer as Markdown; ANSI-styled
+		// header text embedded inside Markdown can confuse wrapping and parsing.
+		const card = new Box(1, 1, (text) => theme.bg("selectedBg", text));
+		card.addChild(
+			new Text(`${icon} ${theme.bold("BTW")} ${theme.fg("dim", `· ${meta.join(" · ")}`)}`, 0, 0),
+		);
+		card.addChild(
+			new Text(`${theme.fg("accent", "▐")} ${theme.fg("muted", details.question)}`, 0, 0),
+		);
+		card.addChild(new Spacer(1));
+
+		if (failed) {
+			card.addChild(new Text(theme.fg("error", details.error ?? "Unknown error"), 0, 0));
+			return card;
+		}
+
+		try {
+			card.addChild(
+				new Markdown(details.answer, 0, 0, getMarkdownTheme(), {
+					color: (text) => theme.fg("customMessageText", text),
+				}),
+			);
+		} catch {
+			card.addChild(new Text(theme.fg("customMessageText", details.answer), 0, 0));
+		}
+		return card;
+	});
+}

package/src/btw/session.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { LoadExtensionsResult } from "@earendil-works/pi-coding-agent";
+import {
+	BTW_SYSTEM_PROMPT,
+	lastAssistantText,
+	makeLeanExtensions,
+	selectBtwTools,
+	snapshotMainSettings,
+} from "./session.ts";
+
+describe("BTW system prompt", () => {
+	test("is the exact lean Pix identity", () => {
+		expect(BTW_SYSTEM_PROMPT).toBe(
+			"You are Pix Coding Agent. You help users accomplish any task they request.",
+		);
+	});
+});
+
+describe("snapshotMainSettings", () => {
+	test("captures model, thinking, cwd, and a defensive copy of active tools", () => {
+		const tools = ["read", "fetch"];
+		const model = { id: "model-id", name: "Model" } as Model<Api>;
+		const snapshot = snapshotMainSettings({ cwd: "/project", model } as never, "high", tools);
+		tools.push("write");
+		expect(snapshot.cwd).toBe("/project");
+		expect(snapshot.model).toBe(model);
+		expect(snapshot.thinkingLevel).toBe("high");
+		expect(snapshot.activeToolNames).toEqual(["read", "fetch"]);
+	});
+
+	test("rejects invocation when the main session has no model", () => {
+		expect(() =>
+			snapshotMainSettings({ cwd: "/project", model: undefined } as never, "medium", []),
+		).toThrow("No model is selected");
+	});
+});
+
+describe("selectBtwTools", () => {
+	test("uses the main active tools and removes duplicates without reordering", () => {
+		expect(selectBtwTools(["read", "fetch", "read", "agent"])).toEqual(["read", "fetch", "agent"]);
+	});
+});
+
+describe("makeLeanExtensions", () => {
+	test("removes discovered before_agent_start mutators but preserves inline override", () => {
+		const regularHandlers = new Map<string, never[]>([
+			["before_agent_start", []],
+			["tool_call", []],
+		]);
+		const inlineHandlers = new Map<string, never[]>([["before_agent_start", []]]);
+		const base = {
+			extensions: [
+				{ path: "/extensions/pix-prompts.ts", handlers: regularHandlers },
+				{ path: "<inline:1>", handlers: inlineHandlers },
+			],
+			errors: [],
+			runtime: {},
+		} as unknown as LoadExtensionsResult;
+
+		const result = makeLeanExtensions(base);
+		expect(result.extensions[0]?.handlers.has("before_agent_start")).toBe(false);
+		expect(result.extensions[0]?.handlers.has("tool_call")).toBe(true);
+		expect(result.extensions[1]?.handlers.has("before_agent_start")).toBe(true);
+		// Do not mutate the loader's original extension records.
+		expect(regularHandlers.has("before_agent_start")).toBe(true);
+	});
+});
+
+describe("lastAssistantText", () => {
+	test("returns text from the latest assistant response", () => {
+		const messages = [
+			{ role: "assistant", content: [{ type: "text", text: "old" }] },
+			{ role: "user", content: "question" },
+			{
+				role: "assistant",
+				content: [
+					{ type: "thinking", thinking: "hidden" },
+					{ type: "text", text: "latest" },
+				],
+			},
+		];
+		expect(lastAssistantText(messages)).toBe("latest");
+	});
+
+	test("returns an empty string when there is no assistant text", () => {
+		expect(lastAssistantText([{ role: "user", content: "hello" }])).toBe("");
+	});
+});

package/src/btw/session.ts

@@ -0,0 +1,163 @@
+import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
+import {
+	type AgentSession,
+	type AgentSessionEvent,
+	createAgentSession,
+	DefaultResourceLoader,
+	type ExtensionAPI,
+	type ExtensionContext,
+	getAgentDir,
+	type LoadExtensionsResult,
+	SessionManager,
+	SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+
+type ThinkingLevel = ReturnType<ExtensionAPI["getThinkingLevel"]>;
+
+export const BTW_SYSTEM_PROMPT =
+	"You are Pix Coding Agent. You help users accomplish any task they request.";
+
+export interface BtwSnapshot {
+	cwd: string;
+	model: Model<Api>;
+	thinkingLevel: ThinkingLevel;
+	activeToolNames: string[];
+}
+
+export interface BtwRunOptions {
+	question: string;
+	snapshot: BtwSnapshot;
+	ctx: ExtensionContext;
+	onSession?: (session: AgentSession) => void;
+	onTextDelta?: (delta: string, fullText: string) => void;
+	onToolStart?: (toolName: string) => void;
+	onToolEnd?: (toolName: string) => void;
+}
+
+export interface BtwRunResult {
+	text: string;
+	session: AgentSession;
+}
+
+/** Capture main-session settings at invocation time so later changes do not affect a running aside. */
+export function snapshotMainSettings(
+	ctx: Pick<ExtensionContext, "cwd" | "model">,
+	thinkingLevel: ThinkingLevel,
+	activeToolNames: string[],
+): BtwSnapshot {
+	if (!ctx.model) throw new Error("No model is selected in the main session.");
+	return {
+		cwd: ctx.cwd,
+		model: ctx.model as Model<Api>,
+		thinkingLevel,
+		activeToolNames: [...activeToolNames],
+	};
+}
+
+/** Preserve the main session's active tool selection exactly, while removing duplicates. */
+export function selectBtwTools(activeToolNames: string[]): string[] {
+	return [...new Set(activeToolNames)];
+}
+
+/**
+ * Keep extension tools and policies, but remove per-turn system-prompt mutators.
+ * This preserves the deliberately lean /btw identity even when pix-prompts,
+ * optimizer nudges, or project extensions normally append instructions.
+ */
+export function makeLeanExtensions(base: LoadExtensionsResult): LoadExtensionsResult {
+	return {
+		...base,
+		extensions: base.extensions.map((extension) => {
+			// Preserve our final inline prompt override; suppress every discovered
+			// extension's per-turn system-prompt mutation.
+			if (extension.path.startsWith("<inline:")) return extension;
+			const handlers = new Map(extension.handlers);
+			handlers.delete("before_agent_start");
+			return { ...extension, handlers };
+		}),
+	};
+}
+
+/** Extract the final assistant text if no streaming deltas were observed. */
+export function lastAssistantText(messages: readonly unknown[]): string {
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const message = messages[index] as AssistantMessage | undefined;
+		if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
+		const text = message.content
+			.filter((block): block is { type: "text"; text: string } => block.type === "text")
+			.map((block) => block.text)
+			.join("\n")
+			.trim();
+		if (text) return text;
+	}
+	return "";
+}
+
+/**
+ * Run one isolated, in-memory /btw question.
+ *
+ * The child discovers the same extensions, skills, credentials, model registry,
+ * working directory, and settings files as the main session. Its system prompt
+ * is replaced with the lean Pix identity, and its conversation starts empty.
+ */
+export async function runBtw(options: BtwRunOptions): Promise<BtwRunResult> {
+	const { question, snapshot, ctx } = options;
+	const agentDir = getAgentDir();
+	const settingsManager = SettingsManager.create(snapshot.cwd, agentDir);
+	const loader = new DefaultResourceLoader({
+		cwd: snapshot.cwd,
+		agentDir,
+		settingsManager,
+		noContextFiles: true,
+		extensionFactories: [
+			(pi) => {
+				pi.on("before_agent_start", () => ({ systemPrompt: BTW_SYSTEM_PROMPT }));
+			},
+		],
+		extensionsOverride: makeLeanExtensions,
+		systemPromptOverride: () => BTW_SYSTEM_PROMPT,
+		appendSystemPromptOverride: () => [],
+	});
+	await loader.reload();
+
+	const tools = selectBtwTools(snapshot.activeToolNames);
+
+	const { session } = await createAgentSession({
+		cwd: snapshot.cwd,
+		agentDir,
+		sessionManager: SessionManager.inMemory(snapshot.cwd),
+		settingsManager,
+		modelRegistry: ctx.modelRegistry,
+		model: snapshot.model,
+		thinkingLevel: snapshot.thinkingLevel,
+		tools,
+		resourceLoader: loader,
+	});
+	session.setSessionName("btw");
+	await session.bindExtensions({
+		mode: ctx.mode,
+		onError: () => {},
+	});
+	options.onSession?.(session);
+
+	let text = "";
+	const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+		if (event.type === "message_start" && event.message.role === "assistant") text = "";
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			text += event.assistantMessageEvent.delta;
+			options.onTextDelta?.(event.assistantMessageEvent.delta, text);
+		}
+		if (event.type === "tool_execution_start") options.onToolStart?.(event.toolName);
+		if (event.type === "tool_execution_end") options.onToolEnd?.(event.toolName);
+	});
+
+	try {
+		await session.prompt(question, { source: "extension" });
+		return { text: text.trim() || lastAssistantText(session.messages), session };
+	} catch (error) {
+		session.dispose();
+		throw error;
+	} finally {
+		unsubscribe();
+	}
+}

package/src/clear.ts

@@ -1,25 +1,16 @@
-import type {
-	ExtensionAPI,
-	ExtensionCommandContext,
-} from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
 async function clearCache(pi: ExtensionAPI, ctx: ExtensionCommandContext) {
 	ctx.ui.notify("Clearing ~/.cache/pi", "info");
 	const result = await pi.exec("/bin/sh", ["-lc", 'rm -rf "$HOME/.cache/pi"'], {
 		timeout: 10_000,
 	});
-	const output = [result.stdout, result.stderr]
-		.filter(Boolean)
-		.join("\n")
-		.trim();
+	const output = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
 	if ((result.code ?? 0) !== 0) {
 		ctx.ui.notify(`Cache clear failed. ${output || "No output."}`, "error");
 		return;
 	}
-	ctx.ui.notify(
-		"~/.cache/pi cleared. Run /reload to apply changes.",
-		"warning",
-	);
+	ctx.ui.notify("~/.cache/pi cleared. Run /reload to apply changes.", "warning");
 }
 
 export default function (pi: ExtensionAPI) {

package/src/extension.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import extension from "./extension.ts";
+
+afterEach(() => {
+	delete (globalThis as { __pixOnce?: WeakMap<object, Set<string>> }).__pixOnce;
+});
+
+describe("pix-commands registration", () => {
+	function host() {
+		const commands: string[] = [];
+		const renderers: string[] = [];
+		const pi = {
+			registerCommand(name: string) {
+				commands.push(name);
+			},
+			registerMessageRenderer(name: string) {
+				renderers.push(name);
+			},
+			on() {},
+		} as unknown as ExtensionAPI;
+		return { pi, commands, renderers };
+	}
+
+	test("registers /clear, /btw, and the BTW renderer once per Pi instance", () => {
+		const { pi, commands, renderers } = host();
+		extension(pi);
+		extension(pi);
+		expect(commands).toEqual(["clear", "btw"]);
+		expect(renderers).toEqual(["pix-btw-answer"]);
+	});
+
+	test("registers again for a fresh Pi session", () => {
+		const first = host();
+		const second = host();
+		extension(first.pi);
+		extension(second.pi);
+		expect(first.commands).toEqual(["clear", "btw"]);
+		expect(second.commands).toEqual(["clear", "btw"]);
+	});
+});

package/src/extension.ts

@@ -1,9 +1,11 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerBtw } from "./btw/index.ts";
 import registerClear from "./clear.ts";
 import { once } from "./once.ts";
 
 export default function (pi: ExtensionAPI): void {
 	once(pi, "pix-commands", () => {
 		registerClear(pi);
+		registerBtw(pi);
 	});
 }

package/src/index.ts

@@ -1 +1,2 @@
+export { registerBtw } from "./btw/index.ts";
 export { default as registerClear } from "./clear.ts";