@bacnh85/pi-subagent 0.3.1 → 0.5.0

package/{index.ts → extensions/index.ts}

@@ -15,17 +15,18 @@
 
 import * as path from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
-import { getModel } from "@earendil-works/pi-ai/compat";
 import { StringEnum } from "@earendil-works/pi-ai";
 import {
 	AuthStorage,
 	CONFIG_DIR_NAME,
+	DynamicBorder,
 	type ExtensionAPI,
+	type ExtensionContext,
 	getAgentDir,
 	getMarkdownTheme,
 	ModelRegistry,
 } from "@earendil-works/pi-coding-agent";
-import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { Container, Markdown, SelectList, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 import { type AgentConfig, type AgentScope, discoverAgents, formatAgentList, invalidateAgentCache } from "./agents.ts";
@@ -42,6 +43,9 @@ import {
 	formatUsageStats,
 	renderSingleResult,
 } from "./render.ts";
+import { type SubagentThread, threadStore } from "./threads.ts";
+import { SUBAGENT_REQUEST_EVENT, runNamedAgent, type SubagentRunRequest } from "./service.ts";
+import { ThreadViewer, type ThreadViewerCallbacks } from "./thread-viewer.ts";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -51,6 +55,8 @@ const MAX_PARALLEL_TASKS = 8;
 const MAX_CONCURRENCY = 4;
 const PER_TASK_OUTPUT_CAP = 50 * 1024; // 50 KB per parallel task
 
+import { resolveModel } from "./model.ts";
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -66,35 +72,6 @@ function truncateParallelOutput(output: string): string {
 	return `${truncated}\n\n[Output truncated: ${byteLength - Buffer.byteLength(truncated, "utf8")} bytes omitted.]`;
 }
 
-interface ResolvedModel {
-	model: Model | null;
-	attempted: string[];
-}
-
-function resolveModel(
-	modelName: string | undefined,
-	parentModel: Model | undefined,
-): ResolvedModel {
-	const attempted: string[] = [];
-	if (modelName) {
-		// Try as provider/id first, then fall back to anthropic/id
-		const parts = modelName.split("/");
-		if (parts.length === 2) {
-			attempted.push(modelName);
-			const found = getModel(parts[0], parts[1]) ?? null;
-			if (found) return { model: found, attempted };
-		} else {
-			// Assume Anthropic shorthand
-			attempted.push(`anthropic/${modelName}`);
-			const found = getModel("anthropic", modelName) ?? null;
-			if (found) return { model: found, attempted };
-		}
-	} else if (parentModel) {
-		attempted.push(`${parentModel.provider}/${parentModel.id}`);
-		return { model: parentModel, attempted };
-	}
-	return { model: null, attempted };
-}
 
 // ---------------------------------------------------------------------------
 // Tool parameter schema
@@ -140,6 +117,7 @@ const SubagentParams = Type.Object({
 	),
 	cwd: Type.Optional(Type.String({ description: "Working directory (single mode)" })),
 	timeout: Type.Optional(Type.Number({ description: "Global timeout in milliseconds for all sub-agents (overridden by per-task/step timeouts)" })),
+	instructions: Type.Optional(Type.String({ description: "Bounded repository/task instructions passed to each child (max 16 KB)" })),
 	abortOnFailure: Type.Optional(Type.Boolean({ description: "In parallel mode, cancel remaining tasks when one fails. Default: false.", default: false })),
 });
 
@@ -159,9 +137,13 @@ interface SubagentDetails {
 // ---------------------------------------------------------------------------
 
 export default function (pi: ExtensionAPI) {
-	// Invalidate agent cache on reload so edited agent files take effect
-	pi.on("session_start", (event) => {
+	let currentCtx: ExtensionContext | undefined;
+
+	// Invalidate agent cache + clear thread store on session replacement.
+	pi.on("session_start", (event, ctx) => {
+		currentCtx = ctx;
 		if (event.reason === "reload") invalidateAgentCache();
+		threadStore.clear();
 	});
 
 	// Proactively steer agents toward sub-agent delegation when users mention it
@@ -176,22 +158,43 @@ export default function (pi: ExtensionAPI) {
 		}
 	});
 
-	// Inject available agent list into system prompt on every session
-	pi.on("before_agent_start", async (event, ctx) => {
-		const discovery = discoverAgents(ctx.cwd, "both", bundledAgentsDir);
-		if (discovery.agents.length > 0) {
-			const names = discovery.agents.map(a => a.name).join(", ");
-			return {
-				systemPrompt:
-					event.systemPrompt +
-					`\n\nAvailable sub-agents: ${names}. Use /subagent for details.`,
-			};
+	// Resolve bundled agents directory relative to this extension file
+	const bundledAgentsDir = path.resolve(__dirname, "../agents");
+
+	// Public one-request/one-response service used by pi-review.
+	pi.events.on(SUBAGENT_REQUEST_EVENT, (raw) => {
+		const request = raw as SubagentRunRequest;
+		const ctx = currentCtx;
+		if (!ctx || !request?.id || typeof request.respond !== "function") return;
+		if (request.accept && !request.accept()) return;
+		const agent = discoverAgents(ctx.cwd, "user", bundledAgentsDir).agents.find((item) => item.name === request.agent);
+		if (!agent) {
+			request.respond({ id: request.id, ok: false, error: `Unknown agent: ${request.agent}` });
+			return;
 		}
+		const thread = threadStore.createThread({ agentName: agent.name, task: request.task, mode: "single" });
+		void runNamedAgent({
+			agent: request.readOnly ? { ...agent, tools: ["read", "grep", "find", "ls"] } : agent,
+			task: request.task,
+			cwd: request.cwd ?? ctx.cwd,
+			ctx,
+			timeout: request.timeout,
+			instructions: request.instructions,
+			signal: request.signal,
+			onMessage: (result) => threadStore.updateThread(thread.id, { result }),
+		}).then((result) => {
+			threadStore.updateThread(thread.id, {
+				status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
+				result,
+			});
+			if (isFailedResult(result)) request.respond({ id: request.id, ok: false, error: getResultOutput(result) });
+			else request.respond({ id: request.id, ok: true, result });
+		}, (error) => {
+			threadStore.updateThread(thread.id, { status: "failed" });
+			request.respond({ id: request.id, ok: false, error: error instanceof Error ? error.message : String(error) });
+		});
 	});
 
-	// Resolve bundled agents directory relative to this extension file
-	const bundledAgentsDir = path.resolve(__dirname, "agents");
-
 	// /subagent command — list available agents
 	pi.registerCommand("subagent", {
 		description: "List available sub-agents, reload agent definitions, or show agent details",
@@ -242,6 +245,7 @@ export default function (pi: ExtensionAPI) {
 						`Agent: ${agent.name} (${agent.source})`,
 						`Description: ${agent.description}`,
 						`Model: ${agent.model || "inherits from parent"}`,
+						`Thinking: ${agent.thinking || "off"}`,
 						`Tools: ${agent.tools?.join(", ") || "all default"}`,
 						`Source file: ${agent.filePath}`,
 						"",
@@ -322,12 +326,8 @@ export default function (pi: ExtensionAPI) {
 				};
 			}
 
-			// Confirm project-local agents
-			if (
-				(agentScope === "project" || agentScope === "both") &&
-				confirmProjectAgents &&
-				ctx.hasUI
-			) {
+			// Handle project-local agent confirmation
+			if (agentScope === "project" || agentScope === "both") {
 				const requestedAgentNames = new Set<string>();
 				if (params.chain) for (const s of params.chain) requestedAgentNames.add(s.agent);
 				if (params.tasks) for (const t of params.tasks) requestedAgentNames.add(t.agent);
@@ -337,16 +337,30 @@ export default function (pi: ExtensionAPI) {
 					.map((name) => agents.find((a) => a.name === name))
 					.filter((a): a is AgentConfig => a?.source === "project");
 
-				if (projectAgentsRequested.length > 0) {
-					const names = projectAgentsRequested.map((a) => a.name).join(", ");
-					const dir = discovery.projectAgentsDir ?? "(unknown)";
-					const ok = await ctx.ui.confirm(
-						"Run project-local agents?",
-						`Agents: ${names}\nSource: ${dir}\n\nProject agents are repo-controlled. Only continue for trusted repositories.`,
-					);
-					if (!ok) {
+				if (projectAgentsRequested.length > 0 && confirmProjectAgents) {
+					if (ctx.hasUI) {
+						const names = projectAgentsRequested.map((a) => a.name).join(", ");
+						const dir = discovery.projectAgentsDir ?? "(unknown)";
+						const ok = await ctx.ui.confirm(
+							"Run project-local agents?",
+							`Agents: ${names}\nSource: ${dir}\n\nProject agents are repo-controlled. Only continue for trusted repositories.`,
+						);
+						if (!ok) {
+							return {
+								content: [{ type: "text", text: "Canceled: project-local agents not approved." }],
+								details: makeDetails(hasChain ? "chain" : hasTasks ? "parallel" : "single")([]),
+							};
+						}
+					} else {
+						// ponytail: fail closed in headless sessions — project agent
+						// prompts and tools run without user oversight.
 						return {
-							content: [{ type: "text", text: "Canceled: project-local agents not approved." }],
+							content: [{
+								type: "text",
+								text: "Cannot run project-local agents without UI confirmation. "
+									+ "Set confirmProjectAgents: false to allow in headless sessions, "
+									+ "or use agentScope: 'user' to skip project agents.",
+							}],
 							details: makeDetails(hasChain ? "chain" : hasTasks ? "parallel" : "single")([]),
 						};
 					}
@@ -354,14 +368,17 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			// Shared auth/model setup for SDK sessions
-			const authStorage = AuthStorage.create();
-			const modelRegistry = ModelRegistry.create(authStorage);
+			// ponytail: reuse parent modelRegistry instead of a fresh copy — avoids
+			// internal API casts (storeModelHeaders) and preserves env/headers/OAuth.
+			const authStorage = AuthStorage.inMemory();
+			const modelRegistry = ctx.modelRegistry;
 
 			// Helper: inject parent's API key into child auth storage
-			async function injectApiKey(model: Model): Promise<void> {
+			async function injectApiKey(model: Model<any>): Promise<void> {
 				const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-				if (auth.ok && auth.apiKey) {
-					authStorage.setRuntimeApiKey(model.provider, auth.apiKey);
+				if (auth.ok) {
+					if (auth.apiKey) authStorage.setRuntimeApiKey(model.provider, auth.apiKey);
+					// ponytail: headers/env stay on the parent registry — no copy needed.
 				}
 			}
 
@@ -372,6 +389,7 @@ export default function (pi: ExtensionAPI) {
 				cwd: string | undefined,
 				parentSignal?: AbortSignal,
 				timeoutMs?: number,
+			onProgress?: (partial: SubAgentResult) => void,
 			): Promise<SubAgentResult> {
 				const agent = agents.find((a) => a.name === agentName);
 
@@ -388,7 +406,7 @@ export default function (pi: ExtensionAPI) {
 					};
 				}
 
-				const resolved = resolveModel(agent.model, ctx.model);
+				const resolved = resolveModel(agent.model, ctx.model, ctx.modelRegistry);
 				if (!resolved.model) {
 					const tried = resolved.attempted.join(", ") || "none";
 					const parentInfo = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none";
@@ -412,52 +430,40 @@ export default function (pi: ExtensionAPI) {
 				let tools = agent.tools ?? defaultTools;
 				tools = tools.filter((t) => t !== "subagent");
 
-				// Build timeout + parent signal into a combined AbortSignal
-				let combinedSignal = parentSignal;
-				let timeoutId: ReturnType<typeof setTimeout> | undefined;
-				let timeoutController: AbortController | undefined;
-				if (timeoutMs && timeoutMs > 0) {
-					timeoutController = new AbortController();
-					timeoutId = setTimeout(() => {
-						timeoutController!.abort();
-					}, timeoutMs);
-					// Combine with parent signal if present (Node 20+ AbortSignal.any)
-					if (parentSignal && typeof (AbortSignal as any).any === "function") {
-						combinedSignal = (AbortSignal as any).any([parentSignal, timeoutController.signal]);
-					} else if (parentSignal) {
-						combinedSignal = timeoutController.signal;
-						// Link parent to timeout: if parent aborts, also abort our timeout controller
-						if (parentSignal.aborted) timeoutController.abort();
-						else parentSignal.addEventListener("abort", () => timeoutController!.abort(), { once: true });
-					} else {
-						combinedSignal = timeoutController.signal;
+				const timeoutController = timeoutMs && timeoutMs > 0 ? new AbortController() : undefined;
+				const timeoutId = timeoutController ? setTimeout(() => timeoutController.abort(), timeoutMs) : undefined;
+				const signals = [parentSignal, timeoutController?.signal].filter((value): value is AbortSignal => Boolean(value));
+				const combinedSignal = signals.length > 1
+					? typeof (AbortSignal as any).any === "function"
+						? (AbortSignal as any).any(signals)
+						: signals[0]
+					: signals[0];
+
+				try {
+					const result = await runSubAgent({
+						cwd: cwd ?? ctx.cwd,
+						systemPrompt: params.instructions
+						? `${agent.systemPrompt}\n\n## Task Contract\n${params.instructions.slice(0, 16 * 1024)}`
+						: agent.systemPrompt,
+						task,
+						tools,
+						model: resolved.model,
+						authStorage,
+						modelRegistry,
+						signal: combinedSignal,
+						agentName,
+						thinkingLevel: agent.thinking,
+						onMessage: onProgress,
+					});
+					if (timeoutController?.signal.aborted && !parentSignal?.aborted) {
+						result.exitCode = 1;
+						result.stopReason = "timeout";
+						result.errorMessage ||= `Timeout after ${timeoutMs}ms`;
 					}
+					return result;
+				} finally {
+					if (timeoutId) clearTimeout(timeoutId);
 				}
-
-				const result = await runSubAgent({
-					cwd: cwd ?? ctx.cwd,
-					systemPrompt: agent.systemPrompt,
-					task,
-					tools,
-					model: resolved.model,
-					authStorage,
-					modelRegistry,
-					signal: combinedSignal,
-					agentName,
-				});
-
-				// Clean up timeout
-				if (timeoutId) clearTimeout(timeoutId);
-
-				// Detect timeout: our timeout controller fired, not the parent
-				const timedOut = timeoutController?.signal.aborted && !parentSignal?.aborted;
-				if (timedOut) {
-					result.exitCode = 1;
-					result.stopReason = "timeout";
-					if (!result.errorMessage) result.errorMessage = `Timeout after ${timeoutMs}ms`;
-				}
-
-				return result;
 			}
 
 			// --- Chain mode ---
@@ -469,10 +475,21 @@ export default function (pi: ExtensionAPI) {
 					const step = params.chain[i];
 					const taskWithContext = step.task.replace(/\{previous\}/g, previousOutput);
 
+					const thread = threadStore.createThread({
+						agentName: step.agent,
+						task: taskWithContext,
+						mode: "chain-step",
+						toolCallId: _toolCallId,
+					});
 					const result = await runOne(
 						step.agent, taskWithContext, step.cwd,
 						signal, step.timeout ?? params.timeout,
+						(partial) => threadStore.updateThread(thread.id, { result: partial }),
 					);
+					threadStore.updateThread(thread.id, {
+						status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
+						result,
+					});
 					results.push(result);
 
 					const isError = isFailedResult(result);
@@ -539,13 +556,21 @@ export default function (pi: ExtensionAPI) {
 
 				const abortOnFailure = params.abortOnFailure ?? false;
 				const parallelController = new AbortController();
+				let abortCause: "parent" | "sibling" | undefined;
 
 				// Combine parent signal with parallel abort controller
 				let parallelSignal: AbortSignal = parallelController.signal;
 				if (signal) {
 					// Always link parent abort into parallelController so queued tasks see aborted state
-					if (signal.aborted) parallelController.abort();
-					else signal.addEventListener("abort", () => parallelController.abort(), { once: true });
+					if (signal.aborted) {
+						abortCause = "parent";
+						parallelController.abort();
+					} else {
+						signal.addEventListener("abort", () => {
+							if (!abortCause) abortCause = "parent";
+							parallelController.abort();
+						}, { once: true });
+					}
 					if (typeof (AbortSignal as any).any === "function") {
 						parallelSignal = (AbortSignal as any).any([signal, parallelController.signal]);
 					} else {
@@ -553,6 +578,16 @@ export default function (pi: ExtensionAPI) {
 					}
 				}
 
+				// Pre-create threads for all parallel tasks
+				const parallelThreads = params.tasks.map((t) =>
+					threadStore.createThread({
+						agentName: t.agent,
+						task: t.task,
+						mode: "parallel-task",
+						toolCallId: _toolCallId,
+					}),
+				);
+
 				const allResults: SubAgentResult[] = new Array(params.tasks.length);
 				// Initialize placeholder results for streaming
 				for (let i = 0; i < params.tasks.length; i++) {
@@ -596,21 +631,32 @@ export default function (pi: ExtensionAPI) {
 								stderr: "",
 								usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
 								stopReason: "aborted",
-								errorMessage: parallelController.signal.aborted
-								? "Cancelled: sibling task failed"
-								: "Cancelled: parent operation aborted",
+								errorMessage:
+									abortCause === "sibling"
+									? "Cancelled: sibling task failed"
+									: "Cancelled: parent operation aborted",
 							};
 							allResults[index] = skippedResult;
+							threadStore.updateThread(parallelThreads[index].id, {
+								status: "aborted",
+								result: skippedResult,
+							});
 							emitParallelUpdate();
 							return skippedResult;
 						}
 						const result = await runOne(
 							t.agent, t.task, t.cwd,
 							parallelSignal, t.timeout ?? params.timeout,
+						(partial) => threadStore.updateThread(parallelThreads[index].id, { result: partial }),
 						);
 						allResults[index] = result;
+						threadStore.updateThread(parallelThreads[index].id, {
+							status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
+							result,
+						});
 						// Early-abort: if this task failed and abortOnFailure is set
 						if (abortOnFailure && isFailedResult(result)) {
+							abortCause = "sibling";
 							parallelController.abort();
 						}
 						emitParallelUpdate();
@@ -643,10 +689,21 @@ export default function (pi: ExtensionAPI) {
 
 			// --- Single mode ---
 			if (params.agent && params.task) {
+				const thread = threadStore.createThread({
+					agentName: params.agent,
+					task: params.task,
+					mode: "single",
+					toolCallId: _toolCallId,
+				});
 				const result = await runOne(
 					params.agent, params.task, params.cwd,
 					signal, params.timeout,
+					(partial) => threadStore.updateThread(thread.id, { result: partial }),
 				);
+				threadStore.updateThread(thread.id, {
+					status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
+					result,
+				});
 				const isError = isFailedResult(result);
 
 				if (onUpdate) {
@@ -921,4 +978,241 @@ export default function (pi: ExtensionAPI) {
 			return new Text(fallback?.type === "text" ? fallback.text : "(no output)", 0, 0);
 		},
 	});
-}
+	// /agent command — switch between subagent threads.
+	// When a thread is selected, the viewer replaces the main TUI (not overlay).
+	pi.registerCommand("agent", {
+		description: "Switch to a subagent thread to view its work in isolation",
+		handler: async (_args, ctx) => {
+			// Show picker overlay
+			const selectedId = await showAgentPicker(ctx, buildPickerItems(threadStore.getAllThreads()));
+			if (!selectedId) return; // Cancelled — stay in current view
+
+			// Main selected — close viewer if active, return to conversation
+			if (selectedId === "__main__") {
+				if (activeViewerDone) {
+					activeViewerDone();
+					activeViewerDone = null;
+				}
+				return;
+			}
+
+			// Close existing viewer (if any) before opening new one
+			if (activeViewerDone) {
+				activeViewerDone();
+				activeViewerDone = null;
+			}
+
+			// Show thread viewer (re-resolve against current store)
+			const freshThreads = threadStore.getAllThreads();
+			const idx = freshThreads.findIndex((t) => t.id === selectedId);
+			if (idx === -1) {
+				ctx.ui.notify("Selected subagent thread no longer exists.", "warning");
+				return;
+			}
+
+			await showThreadViewer(ctx, freshThreads, idx);
+		},
+	});
+
+	// ---------------------------------------------------------------------------
+	// Module-level viewer state (so /agent can close an active viewer)
+	// ---------------------------------------------------------------------------
+	let activeViewerDone: (() => void) | null = null;
+
+	// ---------------------------------------------------------------------------
+	// Picker helpers (shared between /agent handler and Ctrl+P in viewer)
+	// ---------------------------------------------------------------------------
+
+	interface PickerItem { value: string; label: string; description: string }
+
+	function buildPickerItems(threads: SubagentThread[]): PickerItem[] {
+		const items: PickerItem[] = [
+			{ value: "__main__", label: "Main [default]", description: "(current)" },
+		];
+		for (const t of threads) {
+			let statusIcon: string;
+			switch (t.status) {
+				case "running": statusIcon = "⏳"; break;
+				case "completed": statusIcon = "✓"; break;
+				case "failed": statusIcon = "✗"; break;
+				case "aborted": statusIcon = "✗"; break;
+			}
+			let modeTag = "";
+			if (t.mode === "parallel-task") modeTag = " [parallel]";
+			else if (t.mode === "chain-step") modeTag = " [chain]";
+			const label = `${statusIcon} ${t.agentName}${modeTag}`;
+			const desc = t.task.length > 60 ? `${t.task.slice(0, 57)}...` : t.task;
+			items.push({ value: t.id, label, description: desc });
+		}
+		return items;
+	}
+
+	async function showAgentPicker(
+		ctx: { ui: { custom: <T>(factory: any, opts?: any) => Promise<T> } },
+		items: PickerItem[],
+	): Promise<string | null> {
+		return ctx.ui.custom<string | null>((tui: any, theme: any, _kb: any, done: (value: string | null) => void) => {
+			const container = new Container();
+			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+			container.addChild(new Text(theme.fg("accent", theme.bold("Subagents")), 1, 0));
+			container.addChild(new Text(theme.fg("dim", "⌥ + ← previous, ⌥ + → next."), 1, 0));
+
+			const selectList = new SelectList(
+				items.map((it) => ({ value: it.value, label: it.label, description: it.description })),
+				Math.min(items.length + 2, 15),
+				{
+					selectedPrefix: (t: string) => theme.fg("accent", t),
+					selectedText: (t: string) => theme.fg("accent", t),
+					description: (t: string) => theme.fg("muted", t),
+					scrollInfo: (t: string) => theme.fg("dim", t),
+					noMatch: (t: string) => theme.fg("warning", t),
+				},
+			);
+			selectList.onSelect = (item) => done(item.value);
+			selectList.onCancel = () => done(null);
+			container.addChild(selectList);
+
+			container.addChild(new Text(
+				`${theme.fg("dim", "↑↓ navigate · enter select · esc back")}`,
+				1, 0,
+			));
+
+			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+			return {
+				render: (w: number) => container.render(w),
+				invalidate: () => container.invalidate(),
+				handleInput: (data: string) => { selectList.handleInput(data); tui.requestRender(); },
+			};
+		}, { overlay: true });
+	}
+
+	// Helper: show thread viewer as overlay so editor remains visible.
+	// Uses dynamic thread list + store subscriptions for live progress.
+	// Ctrl+P opens picker overlay to jump to any thread.
+	async function showThreadViewer(
+		ctx: { ui: { custom: <T>(factory: any, opts?: any) => Promise<T> } },
+		_threads: SubagentThread[],
+		startIndex: number,
+	): Promise<void> {
+		let currentIndex = startIndex;
+
+		// Resolve thread list dynamically
+		const getThreads = () => threadStore.getAllThreads();
+
+		// Overlay mode: viewer appears above editor, Esc dismisses
+		await ctx.ui.custom<void>((tui: any, theme: any, _kb: any, done: () => void) => {
+			let unsubscribe: (() => void) | undefined;
+			let closed = false;
+
+			const cleanup = () => {
+				if (unsubscribe) {
+					unsubscribe();
+					unsubscribe = undefined;
+				}
+			};
+
+			const close = () => {
+				if (closed) return;
+				closed = true;
+				cleanup();
+				activeViewerDone = null;
+				done();
+			};
+
+			// Track this viewer so /agent can close it before opening a new one
+			activeViewerDone = close;
+
+			function makeCallbacks(): ThreadViewerCallbacks {
+				const list = getThreads();
+				return {
+					onClose: close,
+					onPrev: () => {
+						const current = getThreads();
+						if (currentIndex > 0) {
+							currentIndex--;
+							viewer.setThread(current[currentIndex], makeCallbacks());
+							tui.requestRender();
+						}
+					},
+					onNext: () => {
+						const current = getThreads();
+						if (currentIndex < current.length - 1) {
+							currentIndex++;
+							viewer.setThread(current[currentIndex], makeCallbacks());
+							tui.requestRender();
+						}
+					},
+					hasPrev: currentIndex > 0,
+					hasNext: currentIndex < list.length - 1,
+				};
+			}
+
+			const list = getThreads();
+			if (list.length === 0 || currentIndex < 0 || currentIndex >= list.length) {
+				close();
+				return {
+					render: (_w: number) => [],
+					invalidate: () => {},
+					handleInput: (_data: string) => {},
+					dispose: () => {
+					cleanup();
+					if (activeViewerDone === close) activeViewerDone = null;
+					closed = true;
+				},
+				};
+			}
+
+			const viewer = new ThreadViewer(list[currentIndex], makeCallbacks(), theme);
+			let pickerOpen = false;
+
+			// Subscribe to thread store for live updates (after viewer is created)
+			unsubscribe = threadStore.subscribe(() => {
+				const current = getThreads();
+				if (current.length === 0) {
+					close();
+					return;
+				}
+				currentIndex = Math.min(currentIndex, current.length - 1);
+				viewer.setThread(current[currentIndex], makeCallbacks());
+				tui.requestRender();
+			});
+
+			return {
+				render: (w: number) => viewer.render(w),
+				invalidate: () => viewer.invalidate(),
+				handleInput: (data: string) => {
+					// Ctrl+P opens the picker to jump between threads
+					if (data === "\x10") {
+			if (!pickerOpen) {
+				pickerOpen = true;
+				openThreadPicker().finally(() => { pickerOpen = false; });
+			}
+						return;
+					}
+					viewer.handleInput(data);
+					tui.requestRender();
+				},
+				dispose: () => {
+					cleanup();
+					if (activeViewerDone === close) activeViewerDone = null;
+					closed = true;
+				},
+			};
+
+			// Opens picker overlay on top of viewer to jump to any thread
+			async function openThreadPicker() {
+				const items = buildPickerItems(getThreads());
+				const selectedId = await showAgentPicker(ctx, items);
+				if (!selectedId) return;
+				if (selectedId === "__main__") { close(); return; }
+				const idx = getThreads().findIndex((t) => t.id === selectedId);
+				if (idx >= 0) {
+					currentIndex = idx;
+					viewer.setThread(getThreads()[currentIndex], makeCallbacks());
+					tui.requestRender();
+				}
+			}
+		}, { overlay: true, overlayOptions: { maxHeight: "70%" } }); // Overlay: editor stays visible below
+	}
+}