@shanepadgett/tau-agent 0.33.0 → 0.34.0

package/docs/context.md

@@ -1,21 +1,21 @@
 # Context management
 
-Tau uses `.pi/contexts` as a reusable map of the repository. A selected context supplies a small bootstrap projection for a work scope and points toward related files without loading everything.
+Tau uses `.pi/contexts` as a reusable map of the repository. Selecting a context injects a small bootstrap for a work scope and points toward related files without loading everything.
 
 ## Structure
 
 The catalog has three levels:
 
 ```text
-.pi/contexts/<domain>/<concept>.toml
-                         └── [entry]
+.pi/contexts/<NN_domain>/<concept>.toml
+                            └── [entry]
 ```
 
-- **Domain**: a stable top-level area of the repository, such as `commerce`, `platform`, or `documentation`. Domains become tabs in `/context`.
+- **Domain**: a stable top-level area of the repository, such as `commerce`, `platform`, or `documentation`. Domain folders are named `NN_slug` with a two-digit order (`01_extensions`, `02_core`, …). `/context` sorts tabs by that prefix and shows the slug only.
 - **Concept**: a coherent subsystem or capability inside a domain. Each concept is one TOML file.
 - **Entry**: a selectable work scope inside that concept. Each TOML section defines one entry.
 
-Domain folders, concept filenames, and entry section names use lowercase kebab-case.
+Domain slugs (after `NN_`), concept filenames, and entry section names use lowercase kebab-case. Orders are contiguous from `01` with no gaps or duplicate slugs. Entry ids use the slug (`extensions/checkpoint/checkpoint-tool`), not the folder prefix.
 
 ```toml
 name = "Checkout"
@@ -23,45 +23,54 @@ description = "Checkout calculation and order submission"
 
 [orchestration]
 description = "Building and submitting a checkout order"
-read = []
-outline = ["src/checkout/order.ts", "src/checkout/service.ts"]
-references = ["test/checkout/service.test.ts", "src/payments/client.ts"]
+read = ["src/checkout/order.ts"]
+show = [
+  { path = "src/payments/client.ts", name = "submitPayment" },
+]
+outline = ["src/checkout/service.ts"]
+references = ["test/checkout/service.test.ts"]
 
 [discounts]
 description = "Applying coupons and account discounts"
-read = []
-outline = ["src/checkout/discounts.ts"]
+read = ["src/checkout/discounts.ts"]
+show = []
+outline = []
 references = ["test/checkout/discounts.test.ts"]
 ```
 
-Saved as `.pi/contexts/commerce/checkout.toml`, these entries have the IDs `commerce/checkout/orchestration` and `commerce/checkout/discounts`.
+Saved as `.pi/contexts/01_commerce/checkout.toml`, these entries have the IDs `commerce/checkout/orchestration` and `commerce/checkout/discounts`.
 
 ## Build a useful taxonomy
 
-A good entry gives the agent enough primary code to start one recurring kind of work without flooding its context window. Classify each scope from the top down:
+Each entry is a **work pack**: enough primary material that selecting only that entry lets an agent start one recurring job with little search. Taxonomy groups packs; it is not a file index. Gold-standard example: `.pi/contexts/01_extensions/checkpoint.toml`.
+
+Classify from the top down:
 
 1. **Domain:** Which stable product or technical area owns this work?
 2. **Concept:** Which subsystem inside that area has a clear shared purpose?
-3. **Entry:** Which files are commonly needed together for one task?
+3. **Entry:** Which job would someone select on purpose, and which files form its start pack?
 
 Reuse existing terms when they still describe the code honestly. Create, move, split, or merge taxonomy when ownership or subsystem boundaries change. Directory layout can inform the decision, though domains and concepts should describe responsibility rather than copy the source tree.
 
-Keep entries focused. Names such as `misc`, `shared`, and `other` hide missing boundaries. A broad `all` entry can support deliberate subsystem-wide work, but focused entries should remain available for normal tasks. If an entry keeps collecting unrelated paths, split it by work scope. If several tiny entries are always selected together, merge them.
+Keep entries focused on jobs. Names such as `misc`, `shared`, `other`, and a lone `[feature]` bag hide missing boundaries. A broad `all` entry can support deliberate subsystem-wide work, but focused job entries should remain available. If an entry keeps collecting unrelated paths, split it by work scope. If several tiny entries are always selected together, merge them. Overlap across entries is fine when two jobs share files.
 
 Catalog durable code, configuration, tests, standards, and long-lived documentation. Leave scratch files, working plans, interviews, generated output, and rough ideas out of the catalog.
 
 ## Choose loading modes
 
-- `read` supplies exact complete file contents. Reserve it for instructions, small authoritative specifications, and other files whose exact wording is routinely needed.
-- `outline` supplies current structural outlines through Explore. Use it for recurring source entry points.
-- `references` supplies unloaded navigation paths. This should be the default for durable code, tests, callers, shared dependencies, and secondary documentation.
+- `read` supplies exact complete file contents. Default for code the agent must edit or deeply understand for that work scope. Prefer complete reads on clean, bounded modules.
+- `show` supplies one resolved declaration slice (`path` + `name`, optional `view`) through Explore. Use it for a fat neighbor's thin contract — not to microslice a file you should just `read`. Default `view` is `declaration`. Allowed views: `signature`, `signatureWithDocs`, `declaration`, `declarationWithImports`.
+- `outline` supplies structural outlines through Explore. Use it when a full read would drown the job (large or noisy files), not as the default for small clean modules.
+- `references` supplies unloaded navigation paths. Default for secondary code, tests, callers, and spill edges the agent should not load unless the task expands.
+
+Every entry declares all four arrays, including empty arrays. Keep injected material small enough that one selected entry is a start pack for real work. A path may appear in only one of `read`, `outline`, and `references`. The same path may also appear in `show` with `outline` or `references` (structure or nav plus hot symbols). When selected entries disagree, precedence is `read`, then `show`, then `outline`, then `references`. A full `read` drops `show` targets for that path.
 
-Every entry declares all three arrays, including empty arrays. Keep `read` and `outline` small because Tau rebuilds them before model calls. Keep each path's loading mode consistent across the catalog. When selected entries disagree, precedence is `read`, then `outline`, then `references`.
+Do not store raw line ranges in the catalog — they drift. `show` stores durable symbol identity and resolves to current lines at inject time.
 
-`/context` persists selected entry IDs as branch-local session state. It does not append file contents to conversation history. Before each model call Tau resolves those IDs against the current catalog, reads current `read` files, refreshes changed outlines, and adds one ephemeral projection. Reopening `/context` replaces the active selection. Clear all selections and confirm to remove the projection.
+`/context` injects the selected entries once, as soon as you confirm the selector. Tau adds one hidden note naming the selected entries and their `references`, then appends complete `read` files, `show` declaration slices, and `outline` structures as visible rows. Those messages stay in the conversation exactly as injected, so the prompt prefix stays cacheable. Run `/context` again to inject more entries.
 
 ## Maintain the map
 
 Inspect the existing catalog before placing new paths. Re-evaluate domain, concept, and entry boundaries after moves, ownership changes, or a coherent batch of new work; avoid stuffing paths into the nearest existing bucket.
 
-Run `/context-sync` to update the catalog from uncommitted repository changes. Tau can also delegate to the `context-sync` subagent when automation is enabled. Context sync checks every eligible changed file for membership, removes stale paths, and re-evaluates the taxonomy before editing `.pi/contexts`.
+Run `/context-sync` to update the catalog from uncommitted repository changes (editor is replaced until it finishes; Escape or Ctrl+C cancels). Tau can also delegate to the `context-sync` subagent when automation is enabled. The agent uses normal repo tools, checks every eligible changed file for membership, removes stale paths, and re-evaluates taxonomy and work-pack quality (including `read` / `show` / `outline` / `references`) before editing `.pi/contexts`. Nudge with `/context-sync <note>` when you want a quality rewrite of weak bags, not only dirty-path coverage.

package/docs/extending-tau-agent.md

@@ -32,45 +32,84 @@ Fields:
 
 The promise resolves after publication with the generated bytes, absolute path, provider, model, operation, MIME type, width, and height. The bytes are the same bytes written to `result.path`, so callers can attach the image without reopening the file. Failures reject with a bounded, sanitized error. Cancellation before publication rejects with the signal's abort reason and removes staged files.
 
-## Events
-
-External event integration uses Pi's native `pi.events` bus. The caller and Tau Agent must be loaded in the same Pi runtime. Event callers use string channel names and documented payloads. They do not import Tau Agent internals.
-
-Only events documented in this file are public. Extensions run trusted in-process; event emitters can ask Tau Agent to do work.
-
-Related:
-
-- [Custom subagents](./subagents.md)
-- [TUI components](./tui.md)
-
-## `tau:autoread.requested`
+## File injection
 
-Ask Tau Agent to read files and inject visible `tau.autoread` messages.
+`injectFiles()` reads or outlines files and injects them as visible `tau.file` messages, in request order. `prepareFileInjection(pi, request)` builds the same messages without sending them, for callers that need to inspect or append the prepared rows themselves. Both APIs use the supplied Pi runtime to reach Explore's runtime-scoped outline provider.
 
 ```ts
-pi.events.emit("tau:autoread.requested", {
-  source: "my-extension",
-  title: "Skill context",
+import { injectFiles } from "@shanepadgett/tau-agent";
+
+await injectFiles(pi, {
   cwd: ctx.cwd,
+  source: "my-extension",
   batchId,
-  files: [{ path: "skills/foo/SKILL.md" }],
+  files: [
+    { path: "src/server.ts", mode: "full" },
+    { path: "src/router.ts", mode: "outline" },
+  ],
 });
 ```
 
 Fields:
 
-- `source`: caller identifier shown in Tau metadata.
-- `title`: optional display/context label.
 - `cwd`: root used to resolve file paths.
-- `batchId`: groups visible autoread messages.
+- `source`: caller identifier recorded on each message.
+- `batchId`: groups the visible rows produced by one call.
 - `files[].path`: file path relative to `cwd`.
+- `files[].mode`: `full` injects complete contents, `outline` injects structure, `auto` injects contents unless the file is larger than Explore's structural read threshold.
+- `signal`: optional cancellation signal.
 
 Behavior:
 
-- Tau reads each requested file.
-- Tau injects visible `tau.autoread` messages.
-- Missing or unreadable files produce visible failed autoread messages.
-- `pi.events.emit(...)` does not return file contents and should not be treated as completion or ack.
+- Messages are sent in request order and resolve to the prepared messages.
+- Missing, unreadable, or oversized files produce visible failed rows instead of rejecting.
+- Outlining requires Tau's Explore extension to be loaded.
+
+## Deferred tool groups
+
+Extensions can register tools with Tau's `load_tools` registry while keeping their schemas out of the active tool set until the agent needs them. The extension and Tau must run in the same Pi runtime.
+
+```ts
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerDeferredToolGroup } from "@shanepadgett/tau-agent";
+import { Type } from "typebox";
+
+const confluenceSearch = defineTool({
+    name: "confluence_search",
+    label: "Confluence Search",
+    description: "Search and read Confluence pages.",
+    parameters: Type.Object({ query: Type.String() }),
+    async execute(_toolCallId, params) {
+        return {
+            content: [{ type: "text", text: await searchConfluence(params.query) }],
+            details: {},
+        };
+    },
+});
+
+export default function confluenceExtension(pi: ExtensionAPI): void {
+    registerDeferredToolGroup(pi, {
+        id: "confluence",
+        description: "Search and read Confluence pages",
+        tools: [confluenceSearch],
+    });
+}
+```
+
+`registerDeferredToolGroup()` registers tool definitions with Pi and exposes the group through `load_tools`. Call it during extension initialization. Project-local and global package extensions use the same API. `id` must be unique in the runtime, and tool names must be unique within the group.
+
+Deferred loading affects model-visible tool schemas, not JavaScript package loading. Initialize expensive clients, authentication, and network connections inside tool execution when possible. Pi handles provider-specific deferred-tool behavior after Tau additively activates the group.
+
+## Events
+
+External event integration uses Pi's native `pi.events` bus. The caller and Tau Agent must be loaded in the same Pi runtime. Event callers use string channel names and documented payloads. They do not import Tau Agent internals.
+
+Only events documented in this file are public. Extensions run trusted in-process; event emitters can ask Tau Agent to do work.
+
+Related:
+
+- [Custom subagents](./subagents.md)
+- [TUI components](./tui.md)
 
 ## `tau:footer-item`
 

package/extensions/appshot/index.ts

@@ -11,6 +11,7 @@ import { mkdir, readFile, rename, rm, stat } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { type Static, Type } from "typebox";
 import { createToolRowStateStore, formatToolRowTitle } from "../../shared/tool-row-state.js";
+import { registerDeferredToolGroup } from "../../src/tool-loading/index.ts";
 import { createNativeHelper, type RunHelper } from "./native-helper.ts";
 
 const MAX_PNG_BYTES = 12 * 1024 * 1024;
@@ -105,121 +106,121 @@ function encodeWindowList(windows: WindowInfo[]): string {
 function registerAppshotTools(pi: ExtensionAPI, runHelper: RunHelper): void {
 	const rowState = createToolRowStateStore(pi, "appshot.tool-row-state");
 
-	pi.registerTool(
-		defineTool<typeof listWindowsSchema, undefined>({
-			name: "list_windows",
-			label: "List Windows",
-			description:
-				"List visible normal macOS windows as compact JSON with window IDs, titles, application identity, process IDs, and bounds. Use list_windows to discover exact window IDs and application PIDs before screenshot_window or activate_app. Requires macOS 14 or newer and Screen & System Audio Recording permission.",
-			parameters: listWindowsSchema,
-			async execute(_toolCallId, _params, signal) {
-				if (process.platform !== "darwin") throw new Error("list_windows is only available on macOS");
-				const result = await runHelper(["list"], signal, 30_000);
-				if (result.code !== 0)
-					throw new Error(result.stderr.trim() || result.stdout.trim() || "Window listing failed");
-				let parsed: unknown;
+	const listWindowsTool = defineTool<typeof listWindowsSchema, undefined>({
+		name: "list_windows",
+		label: "List Windows",
+		description:
+			"List visible normal macOS windows as compact JSON with window IDs, titles, application identity, process IDs, and bounds. Use list_windows to discover exact window IDs and application PIDs before screenshot_window or activate_app. Requires macOS 14 or newer and Screen & System Audio Recording permission.",
+		parameters: listWindowsSchema,
+		async execute(_toolCallId, _params, signal) {
+			if (process.platform !== "darwin") throw new Error("list_windows is only available on macOS");
+			const result = await runHelper(["list"], signal, 30_000);
+			if (result.code !== 0)
+				throw new Error(result.stderr.trim() || result.stdout.trim() || "Window listing failed");
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(result.stdout);
+			} catch {
+				throw new Error("Window listing helper returned invalid data");
+			}
+			if (!Array.isArray(parsed) || !parsed.every(isWindowInfo)) {
+				throw new Error("Window listing helper returned invalid data");
+			}
+			return { content: [{ type: "text", text: encodeWindowList(parsed) }], details: undefined };
+		},
+		renderCall(_args, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+			text.setText(formatToolRowTitle(rowState, context.toolCallId, "list_windows", theme));
+			return text;
+		},
+		renderResult(result, _options, _theme, context) {
+			const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+			const content = result.content.find((item) => item.type === "text");
+			text.setText(context.expanded && content?.type === "text" ? content.text : "");
+			return text;
+		},
+	});
+
+	const screenshotWindowTool = defineTool<typeof screenshotWindowSchema, ScreenshotDetails | undefined>({
+		name: "screenshot_window",
+		label: "Screenshot Window",
+		description:
+			"Capture one visible macOS window by an exact ID returned by list_windows, resize it to fit within 1568×1568 pixels, save it to the required PNG path, and inspect the image. Call list_windows first.",
+		parameters: screenshotWindowSchema,
+		async execute(_toolCallId, params: ScreenshotWindowParams, signal, onUpdate, ctx) {
+			if (process.platform !== "darwin") throw new Error("screenshot_window is only available on macOS");
+			const rawPath = params.path.startsWith("@") ? params.path.slice(1) : params.path;
+			if (!rawPath.trim()) throw new Error("Screenshot path cannot be empty");
+			const absolutePath = isAbsolute(rawPath) ? rawPath : resolve(ctx.cwd, rawPath);
+			if (!absolutePath.toLowerCase().endsWith(".png")) throw new Error("Screenshot path must end in .png");
+
+			await onUpdate?.({
+				content: [{ type: "text", text: `Capturing window ${params.window_id}...` }],
+				details: undefined,
+			});
+			return withFileMutationQueue(absolutePath, async () => {
+				await mkdir(dirname(absolutePath), { recursive: true });
+				const temporaryPath = join(dirname(absolutePath), `.${basename(absolutePath)}.${randomUUID()}.tmp.png`);
 				try {
-					parsed = JSON.parse(result.stdout);
-				} catch {
-					throw new Error("Window listing helper returned invalid data");
-				}
-				if (!Array.isArray(parsed) || !parsed.every(isWindowInfo)) {
-					throw new Error("Window listing helper returned invalid data");
-				}
-				return { content: [{ type: "text", text: encodeWindowList(parsed) }], details: undefined };
-			},
-			renderCall(_args, theme, context) {
-				rowState.watch(context.toolCallId, context.invalidate);
-				const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
-				text.setText(formatToolRowTitle(rowState, context.toolCallId, "list_windows", theme));
-				return text;
-			},
-			renderResult(result, _options, _theme, context) {
-				const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
-				const content = result.content.find((item) => item.type === "text");
-				text.setText(context.expanded && content?.type === "text" ? content.text : "");
-				return text;
-			},
-		}),
-	);
-
-	pi.registerTool(
-		defineTool<typeof screenshotWindowSchema, ScreenshotDetails | undefined>({
-			name: "screenshot_window",
-			label: "Screenshot Window",
-			description:
-				"Capture one visible macOS window by an exact ID returned by list_windows, resize it to fit within 1568×1568 pixels, save it to the required PNG path, and inspect the image. Call list_windows first.",
-			parameters: screenshotWindowSchema,
-			async execute(_toolCallId, params: ScreenshotWindowParams, signal, onUpdate, ctx) {
-				if (process.platform !== "darwin") throw new Error("screenshot_window is only available on macOS");
-				const rawPath = params.path.startsWith("@") ? params.path.slice(1) : params.path;
-				if (!rawPath.trim()) throw new Error("Screenshot path cannot be empty");
-				const absolutePath = isAbsolute(rawPath) ? rawPath : resolve(ctx.cwd, rawPath);
-				if (!absolutePath.toLowerCase().endsWith(".png")) throw new Error("Screenshot path must end in .png");
-
-				await onUpdate?.({
-					content: [{ type: "text", text: `Capturing window ${params.window_id}...` }],
-					details: undefined,
-				});
-				return withFileMutationQueue(absolutePath, async () => {
-					await mkdir(dirname(absolutePath), { recursive: true });
-					const temporaryPath = join(dirname(absolutePath), `.${basename(absolutePath)}.${randomUUID()}.tmp.png`);
+					const result = await runHelper(["capture", String(params.window_id), temporaryPath], signal, 30_000);
+					if (result.code !== 0) {
+						throw new Error(result.stderr.trim() || result.stdout.trim() || "Window capture failed");
+					}
+					let imageSize: number;
 					try {
-						const result = await runHelper(["capture", String(params.window_id), temporaryPath], signal, 30_000);
-						if (result.code !== 0) {
-							throw new Error(result.stderr.trim() || result.stdout.trim() || "Window capture failed");
-						}
-						let imageSize: number;
-						try {
-							imageSize = (await stat(temporaryPath)).size;
-						} catch {
-							throw new Error(result.stderr.trim() || "Window capture produced no PNG file");
-						}
-						if (imageSize > MAX_PNG_BYTES) {
-							throw new Error(`Window capture exceeds the ${MAX_PNG_BYTES / 1024 / 1024} MiB attachment limit`);
-						}
-						const image = await readFile(temporaryPath);
-						if (
-							image.length < PNG_SIGNATURE.length ||
-							!image.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)
-						) {
-							throw new Error("Window capture produced an invalid PNG file");
-						}
-
-						await rename(temporaryPath, absolutePath);
-						return {
-							content: [
-								{ type: "text", text: `Captured window ${params.window_id} to ${absolutePath}` },
-								{ type: "image", data: image.toString("base64"), mimeType: "image/png" },
-							],
-							details: { path: absolutePath, window_id: params.window_id },
-						};
-					} finally {
-						await rm(temporaryPath, { force: true });
+						imageSize = (await stat(temporaryPath)).size;
+					} catch {
+						throw new Error(result.stderr.trim() || "Window capture produced no PNG file");
+					}
+					if (imageSize > MAX_PNG_BYTES) {
+						throw new Error(`Window capture exceeds the ${MAX_PNG_BYTES / 1024 / 1024} MiB attachment limit`);
+					}
+					const image = await readFile(temporaryPath);
+					if (
+						image.length < PNG_SIGNATURE.length ||
+						!image.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)
+					) {
+						throw new Error("Window capture produced an invalid PNG file");
 					}
-				});
-			},
-		}),
-	);
 
-	pi.registerTool(
-		defineTool<typeof activateAppSchema, ActivationDetails>({
-			name: "activate_app",
-			label: "Activate App",
-			description:
-				"Bring a running macOS application and its windows to the foreground by a process ID returned by list_windows. Use only when foregrounding is required for visual validation because activate_app changes user focus.",
-			parameters: activateAppSchema,
-			async execute(_toolCallId, params, signal) {
-				if (process.platform !== "darwin") throw new Error("activate_app is only available on macOS");
-				const result = await runHelper(["activate", String(params.pid)], signal, 5000);
-				if (result.code !== 0) throw new Error(result.stderr.trim() || result.stdout.trim() || "Activation failed");
-				return {
-					content: [{ type: "text", text: `Activated application PID ${params.pid}` }],
-					details: { pid: params.pid },
-				};
-			},
-		}),
-	);
+					await rename(temporaryPath, absolutePath);
+					return {
+						content: [
+							{ type: "text", text: `Captured window ${params.window_id} to ${absolutePath}` },
+							{ type: "image", data: image.toString("base64"), mimeType: "image/png" },
+						],
+						details: { path: absolutePath, window_id: params.window_id },
+					};
+				} finally {
+					await rm(temporaryPath, { force: true });
+				}
+			});
+		},
+	});
+
+	const activateAppTool = defineTool<typeof activateAppSchema, ActivationDetails>({
+		name: "activate_app",
+		label: "Activate App",
+		description:
+			"Bring a running macOS application and its windows to the foreground by a process ID returned by list_windows. Use only when foregrounding is required for visual validation because activate_app changes user focus.",
+		parameters: activateAppSchema,
+		async execute(_toolCallId, params, signal) {
+			if (process.platform !== "darwin") throw new Error("activate_app is only available on macOS");
+			const result = await runHelper(["activate", String(params.pid)], signal, 5000);
+			if (result.code !== 0) throw new Error(result.stderr.trim() || result.stdout.trim() || "Activation failed");
+			return {
+				content: [{ type: "text", text: `Activated application PID ${params.pid}` }],
+				details: { pid: params.pid },
+			};
+		},
+	});
+
+	registerDeferredToolGroup(pi, {
+		id: "appshot",
+		description: "macOS window discovery, capture, and activation",
+		tools: [listWindowsTool, screenshotWindowTool, activateAppTool],
+	});
 
 	pi.on("session_start", () => rowState.clear());
 }

package/extensions/aside/README.md

@@ -0,0 +1,7 @@
+# aside Extension
+
+Ask the current model a one-off side question without adding it or its answer to the current conversation.
+
+Run `/aside <question>`, then choose whether to include the current conversation branch or ask with no context. The request uses the current model without tools and runs in the background. A status widget remains above the editor while the model is thinking, then the answer opens in an overlay.
+
+Run `/aside` to open the latest answer. Run `/aside clear` to cancel a running aside and clear its in-memory result. Aside results also clear when the session changes or Tau reloads.

package/extensions/aside/index.ts

@@ -0,0 +1,168 @@
+import { randomUUID } from "node:crypto";
+import type { Context, Message, Model } from "@earendil-works/pi-ai";
+import {
+	buildSessionContext,
+	convertToLlm,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { errorText } from "../../shared/text.ts";
+import { AsideResultPanel, AsideWidget, type AsideResult } from "./panel.ts";
+
+const WIDGET_KEY = "aside";
+const CURRENT_CONVERSATION = "Current conversation branch";
+const NO_CONTEXT = "No context";
+
+function buildAsideRequest(messages: readonly Message[], question: string, systemPrompt: string | undefined): Context {
+	const toolResults = new Set(
+		messages.flatMap((message) => (message.role === "toolResult" ? [message.toolCallId] : [])),
+	);
+	let validLength = messages.length;
+	for (const [index, message] of messages.entries()) {
+		if (
+			message.role === "assistant" &&
+			message.content.some((part) => part.type === "toolCall" && !toolResults.has(part.id))
+		) {
+			validLength = index;
+			break;
+		}
+	}
+
+	const userMessage: Message = {
+		role: "user",
+		content: [{ type: "text", text: question }],
+		timestamp: Date.now(),
+	};
+	const request = { messages: [...messages.slice(0, validLength), userMessage] };
+	return systemPrompt === undefined ? request : { ...request, systemPrompt };
+}
+
+export default function asideExtension(pi: ExtensionAPI): void {
+	let activeController: AbortController | undefined;
+	let latest: AsideResult | undefined;
+	let generation = 0;
+
+	const setWidget = (ctx: ExtensionContext, question: string | undefined): void => {
+		ctx.ui.setWidget(WIDGET_KEY, question ? (_tui, theme) => new AsideWidget(theme, question) : undefined, {
+			placement: "aboveEditor",
+		});
+	};
+
+	const clear = (ctx: ExtensionContext): void => {
+		generation += 1;
+		activeController?.abort();
+		activeController = undefined;
+		latest = undefined;
+		setWidget(ctx, undefined);
+	};
+
+	pi.on("session_start", (_event, ctx) => clear(ctx));
+	pi.on("session_shutdown", (_event, ctx) => clear(ctx));
+
+	pi.registerCommand("aside", {
+		description: "Ask the current model a side question outside the transcript",
+		handler: async (args, ctx) => {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("/aside requires TUI mode", "warning");
+				return;
+			}
+
+			const question = args.trim();
+			if (question === "clear") {
+				clear(ctx);
+				return;
+			}
+			if (!question) {
+				if (!latest) {
+					ctx.ui.notify(activeController ? "Aside is still running" : "No aside answer available", "info");
+					return;
+				}
+				await showResult(ctx, latest);
+				return;
+			}
+			if (activeController) {
+				ctx.ui.notify("An aside is already running", "warning");
+				return;
+			}
+
+			const contextChoice = await ctx.ui.select("Aside context", [CURRENT_CONVERSATION, NO_CONTEXT]);
+			if (!contextChoice) return;
+			const model = ctx.model;
+			if (!model) {
+				ctx.ui.notify("No model selected", "error");
+				return;
+			}
+
+			const controller = new AbortController();
+			activeController = controller;
+			const requestGeneration = ++generation;
+			setWidget(ctx, question);
+			void runAside(ctx, model, question, contextChoice === CURRENT_CONVERSATION, controller.signal)
+				.then((result) => {
+					if (generation !== requestGeneration || controller.signal.aborted) return;
+					latest = result;
+					activeController = undefined;
+					setWidget(ctx, undefined);
+					void showResult(ctx, result).catch((error: unknown) => {
+						if (generation !== requestGeneration) return;
+						ctx.ui.notify(`Could not open aside: ${errorText(error)}`, "error");
+					});
+				})
+				.catch((error: unknown) => {
+					if (generation !== requestGeneration || controller.signal.aborted) return;
+					setWidget(ctx, undefined);
+					ctx.ui.notify(`Aside failed: ${errorText(error)}`, "error");
+				})
+				.finally(() => {
+					if (generation === requestGeneration) activeController = undefined;
+				});
+		},
+	});
+}
+
+async function runAside(
+	ctx: ExtensionCommandContext,
+	model: Model<string>,
+	question: string,
+	withConversation: boolean,
+	signal: AbortSignal,
+): Promise<AsideResult> {
+	const provider = ctx.modelRegistry.getProvider(model.provider);
+	if (!provider) throw new Error(`Provider ${model.provider} is unavailable`);
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (!auth.ok) throw new Error(auth.error);
+
+	const request = withConversation
+		? buildAsideRequest(
+				convertToLlm(buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId()).messages),
+				question,
+				ctx.getSystemPrompt(),
+			)
+		: buildAsideRequest([], question, undefined);
+	const response = await provider
+		.streamSimple(model, request, {
+			apiKey: auth.apiKey,
+			headers: auth.headers,
+			env: auth.env,
+			signal,
+			reasoning: ctx.thinkingLevel === "off" ? undefined : ctx.thinkingLevel,
+			sessionId: withConversation ? ctx.sessionManager.getSessionId() : randomUUID(),
+		})
+		.result();
+	if (response.stopReason === "error") throw new Error(response.errorMessage || "model returned an error");
+	if (response.stopReason === "aborted") throw new Error("Cancelled");
+	const answer = response.content
+		.flatMap((part) => (part.type === "text" ? [part.text] : []))
+		.join("\n")
+		.trim();
+	if (!answer) throw new Error("model returned no text");
+	return { question, answer, context: withConversation ? CURRENT_CONVERSATION : NO_CONTEXT };
+}
+
+async function showResult(ctx: ExtensionCommandContext, result: AsideResult): Promise<void> {
+	await ctx.ui.custom<void>((tui, theme, keys, done) => new AsideResultPanel(tui, theme, keys, result, done), {
+		overlay: true,
+		overlayOptions: { anchor: "top-center", width: "80%", minWidth: 68, maxHeight: "90%", margin: 1 },
+	});
+}