pi-interactive-shell 0.8.2 → 0.10.0

package/notification-utils.ts

@@ -0,0 +1,134 @@
+import type { InteractiveShellResult, HandsFreeUpdate } from "./types.js";
+import type { HeadlessCompletionInfo } from "./headless-monitor.js";
+import { formatDurationMs } from "./types.js";
+
+const BRIEF_TAIL_LINES = 5;
+
+export function buildDispatchNotification(sessionId: string, info: HeadlessCompletionInfo, duration: string): string {
+	const parts = [buildDispatchStatusLine(sessionId, info, duration)];
+	if (info.completionOutput && info.completionOutput.totalLines > 0) {
+		parts.push(` ${info.completionOutput.totalLines} lines of output.`);
+	}
+	appendTailBlock(parts, info.completionOutput?.lines, BRIEF_TAIL_LINES);
+	parts.push(`\n\nAttach to review full output: interactive_shell({ attach: "${sessionId}" })`);
+	return parts.join("");
+}
+
+export function buildResultNotification(sessionId: string, result: InteractiveShellResult): string {
+	const parts = [buildResultStatusLine(sessionId, result)];
+	if (result.completionOutput && result.completionOutput.lines.length > 0) {
+		const truncNote = result.completionOutput.truncated
+			? ` (truncated from ${result.completionOutput.totalLines} total lines)`
+			: "";
+		parts.push(`\nOutput (${result.completionOutput.lines.length} lines${truncNote}):\n\n${result.completionOutput.lines.join("\n")}`);
+	}
+	return parts.join("");
+}
+
+export function buildHandsFreeUpdateMessage(update: HandsFreeUpdate): { content: string; details: HandsFreeUpdate } | null {
+	if (update.status === "running") return null;
+
+	const tail = update.tail.length > 0 ? `\n\n${update.tail.join("\n")}` : "";
+	let statusLine: string;
+	switch (update.status) {
+		case "exited":
+			statusLine = `Session ${update.sessionId} exited (${formatDurationMs(update.runtime)})`;
+			break;
+		case "killed":
+			statusLine = `Session ${update.sessionId} killed (${formatDurationMs(update.runtime)})`;
+			break;
+		case "user-takeover":
+			statusLine = `Session ${update.sessionId}: user took over (${formatDurationMs(update.runtime)})`;
+			break;
+		default:
+			statusLine = `Session ${update.sessionId} update (${formatDurationMs(update.runtime)})`;
+	}
+	return { content: statusLine + tail, details: update };
+}
+
+export function summarizeInteractiveResult(command: string, result: InteractiveShellResult, timeout?: number, reason?: string): string {
+	let summary = buildInteractiveSummary(result, timeout);
+
+	if (result.userTookOver) {
+		summary += "\n\nNote: User took over control during hands-free mode.";
+	}
+
+	if (!result.transferred && result.handoffPreview?.type === "tail" && result.handoffPreview.lines.length > 0) {
+		summary += `\n\nOverlay tail (${result.handoffPreview.when}, last ${result.handoffPreview.lines.length} lines):\n${result.handoffPreview.lines.join("\n")}`;
+	}
+
+	const warning = buildIdlePromptWarning(command, reason);
+	if (warning) {
+		summary += `\n\n${warning}`;
+	}
+
+	return summary;
+}
+
+export function buildIdlePromptWarning(command: string, reason: string | undefined): string | null {
+	if (!reason) return null;
+
+	const tasky = /\b(scan|check|review|summariz|analyz|inspect|audit|find|fix|refactor|debug|investigat|explore|enumerat|list)\b/i;
+	if (!tasky.test(reason)) return null;
+
+	const trimmed = command.trim();
+	const binaries = ["pi", "claude", "codex", "gemini", "cursor-agent"] as const;
+	const bin = binaries.find((candidate) => trimmed === candidate || trimmed.startsWith(`${candidate} `));
+	if (!bin) return null;
+
+	const rest = trimmed === bin ? "" : trimmed.slice(bin.length).trim();
+	const hasQuotedPrompt = /["']/.test(rest);
+	const hasKnownPromptFlag =
+		/\b(-p|--print|--prompt|--prompt-interactive|-i|exec)\b/.test(rest) ||
+		(bin === "pi" && /\b-p\b/.test(rest)) ||
+		(bin === "codex" && /\bexec\b/.test(rest));
+
+	if (hasQuotedPrompt || hasKnownPromptFlag) return null;
+	if (!looksLikeIdleCommand(rest)) return null;
+
+	const examplePrompt = reason.replace(/\s+/g, " ").trim();
+	const clipped = examplePrompt.length > 120 ? `${examplePrompt.slice(0, 117)}...` : examplePrompt;
+	return `Note: \`reason\` is UI-only. This command likely started the agent idle. If you intended an initial prompt, embed it in \`command\`, e.g. \`${bin} "${clipped}"\`.`;
+}
+
+function buildDispatchStatusLine(sessionId: string, info: HeadlessCompletionInfo, duration: string): string {
+	if (info.timedOut) return `Session ${sessionId} timed out (${duration}).`;
+	if (info.cancelled) return `Session ${sessionId} completed (${duration}).`;
+	if (info.exitCode === 0) return `Session ${sessionId} completed successfully (${duration}).`;
+	return `Session ${sessionId} exited with code ${info.exitCode} (${duration}).`;
+}
+
+function buildResultStatusLine(sessionId: string, result: InteractiveShellResult): string {
+	if (result.timedOut) return `Session ${sessionId} timed out.`;
+	if (result.cancelled) return `Session ${sessionId} was killed.`;
+	if (result.exitCode === 0) return `Session ${sessionId} completed successfully.`;
+	return `Session ${sessionId} exited with code ${result.exitCode}.`;
+}
+
+function buildInteractiveSummary(result: InteractiveShellResult, timeout?: number): string {
+	if (result.transferred) {
+		const truncatedNote = result.transferred.truncated ? ` (truncated from ${result.transferred.totalLines} total lines)` : "";
+		return `Session output transferred (${result.transferred.lines.length} lines${truncatedNote}):\n\n${result.transferred.lines.join("\n")}`;
+	}
+	if (result.backgrounded) {
+		return `Session running in background (id: ${result.backgroundId}). User can reattach with /attach ${result.backgroundId}`;
+	}
+	if (result.cancelled) return "User killed the interactive session";
+	if (result.timedOut) return `Session killed after timeout (${timeout ?? "?"}ms)`;
+	const status = result.exitCode === 0 ? "successfully" : `with code ${result.exitCode}`;
+	return `Session ended ${status}`;
+}
+
+function appendTailBlock(parts: string[], lines: string[] | undefined, tailLines: number): void {
+	if (!lines || lines.length === 0) return;
+	let end = lines.length;
+	while (end > 0 && lines[end - 1].trim() === "") end--;
+	const tail = lines.slice(Math.max(0, end - tailLines), end);
+	if (tail.length > 0) {
+		parts.push(`\n\n${tail.join("\n")}`);
+	}
+}
+
+function looksLikeIdleCommand(rest: string): boolean {
+	return rest.length === 0 || /^(-{1,2}[A-Za-z0-9][A-Za-z0-9-]*(?:=[^\s]+)?\s*)+$/.test(rest);
+}

package/overlay-component.ts

@@ -1,6 +1,4 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { stripVTControlCharacters } from "node:util";
 import type { Component, Focusable, TUI } from "@mariozechner/pi-tui";
 import { matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import type { Theme } from "@mariozechner/pi-coding-agent";
@@ -18,6 +16,8 @@ import {
 	FOOTER_LINES_DIALOG,
 	formatDuration,
 } from "./types.js";
+import { captureCompletionOutput, captureTransferOutput, maybeBuildHandoffPreview, maybeWriteHandoffSnapshot } from "./handoff-utils.js";
+import { createSessionQueryState, getSessionOutput } from "./session-query.js";
 
 export class InteractiveShellOverlay implements Component, Focusable {
 	focused = false;
@@ -39,7 +39,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 	private userTookOver = false;
 	private handsFreeInterval: ReturnType<typeof setInterval> | null = null;
 	private handsFreeInitialTimeout: ReturnType<typeof setTimeout> | null = null;
-	private startTime = Date.now();
+	private startTime: number;
 	private sessionId: string | null = null;
 	private sessionUnregistered = false;
 	// Timeout
@@ -56,10 +56,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 	private hasUnsentData = false;
 	// Non-blocking mode: track status for agent queries
 	private completionResult: InteractiveShellResult | undefined;
-	// Rate limiting for queries
-	private lastQueryTime = 0;
-	// Incremental read position (for incremental: true queries)
-	private incrementalReadPosition = 0;
+	private queryState = createSessionQueryState();
 	// Completion callbacks for waiters
 	private completeCallbacks: Array<() => void> = [];
 	// Simple render throttle to reduce flicker
@@ -77,6 +74,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.options = options;
 		this.config = config;
 		this.done = done;
+		this.startTime = options.startedAt ?? Date.now();
 
 		const overlayWidth = Math.floor((tui.terminal.columns * this.config.overlayWidthPercent) / 100);
 		const overlayHeight = Math.floor((tui.terminal.rows * this.config.overlayHeightPercent) / 100);
@@ -84,11 +82,16 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		const rows = Math.max(3, overlayHeight - (HEADER_LINES + FOOTER_LINES_COMPACT + 2));
 
 		const ptyEvents = {
-			onData: () => {
+			onData: (data: string) => {
 				this.debouncedRender();
-				if (this.state === "hands-free" && this.updateMode === "on-quiet") {
-					this.hasUnsentData = true;
-					this.resetQuietTimer();
+				if (this.state === "hands-free" && (this.updateMode === "on-quiet" || this.options.autoExitOnQuiet)) {
+					const visible = stripVTControlCharacters(data);
+					if (visible.trim().length > 0) {
+						if (this.updateMode === "on-quiet") {
+							this.hasUnsentData = true;
+						}
+						this.resetQuietTimer();
+					}
 				}
 			},
 			onExit: () => {
@@ -203,136 +206,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 
 	// Public methods for non-blocking mode (agent queries)
 
-	// Default output limits per status query
-	private static readonly DEFAULT_STATUS_OUTPUT = 5 * 1024; // 5KB
-	private static readonly DEFAULT_STATUS_LINES = 20;
-	private static readonly MAX_STATUS_OUTPUT = 50 * 1024; // 50KB max
-	private static readonly MAX_STATUS_LINES = 200; // 200 lines max
-
 	/** Get rendered terminal output (last N lines, truncated if too large) */
 	getOutputSinceLastCheck(options: { skipRateLimit?: boolean; lines?: number; maxChars?: number; offset?: number; drain?: boolean; incremental?: boolean } | boolean = false): { output: string; truncated: boolean; totalBytes: number; totalLines?: number; hasMore?: boolean; rateLimited?: boolean; waitSeconds?: number } {
-		if (this.finished) {
-			if (this.completionResult?.completionOutput) {
-				const lines = this.completionResult.completionOutput.lines;
-				const output = lines.join("\n");
-				return {
-					output,
-					truncated: this.completionResult.completionOutput.truncated,
-					totalBytes: output.length,
-					totalLines: this.completionResult.completionOutput.totalLines,
-				};
-			}
-			return { output: "", truncated: false, totalBytes: 0 };
-		}
-
-		// Handle legacy boolean parameter
-		const opts = typeof options === "boolean" ? { skipRateLimit: options } : options;
-		const skipRateLimit = opts.skipRateLimit ?? false;
-		// Clamp lines and maxChars to valid ranges (1 to MAX)
-		const requestedLines = Math.max(1, Math.min(
-			opts.lines ?? InteractiveShellOverlay.DEFAULT_STATUS_LINES,
-			InteractiveShellOverlay.MAX_STATUS_LINES
-		));
-		const requestedMaxChars = Math.max(1, Math.min(
-			opts.maxChars ?? InteractiveShellOverlay.DEFAULT_STATUS_OUTPUT,
-			InteractiveShellOverlay.MAX_STATUS_OUTPUT
-		));
-
-		// Check rate limiting (unless skipped, e.g., for completed sessions)
-		if (!skipRateLimit) {
-			const now = Date.now();
-			const minIntervalMs = this.config.minQueryIntervalSeconds * 1000;
-			const elapsed = now - this.lastQueryTime;
-
-			if (this.lastQueryTime > 0 && elapsed < minIntervalMs) {
-				const waitSeconds = Math.ceil((minIntervalMs - elapsed) / 1000);
-				return {
-					output: "",
-					truncated: false,
-					totalBytes: 0,
-					rateLimited: true,
-					waitSeconds,
-				};
-			}
-
-			// Update last query time
-			this.lastQueryTime = now;
-		}
-
-		// Incremental mode: return next N lines agent hasn't seen yet
-		// Server tracks position - agent just keeps calling with incremental: true
-		if (opts.incremental) {
-			const result = this.session.getLogSlice({
-				offset: this.incrementalReadPosition,
-				limit: requestedLines,
-				stripAnsi: true,
-			});
-			// Use sliceLineCount directly - handles empty lines correctly
-			// (counting newlines in slice fails for empty lines like "")
-			const linesFromSlice = result.sliceLineCount;
-			// Apply maxChars limit (may truncate mid-line, but we still advance past it)
-			const truncatedByChars = result.slice.length > requestedMaxChars;
-			const output = truncatedByChars ? result.slice.slice(0, requestedMaxChars) : result.slice;
-			// Update position for next incremental read
-			this.incrementalReadPosition += linesFromSlice;
-			const hasMore = this.incrementalReadPosition < result.totalLines;
-			return {
-				output,
-				truncated: truncatedByChars,
-				totalBytes: output.length,
-				totalLines: result.totalLines,
-				hasMore,
-			};
-		}
-
-		// Drain mode: return only NEW output since last query (raw stream, not lines)
-		// This is more token-efficient than re-reading the tail each time
-		if (opts.drain) {
-			const newOutput = this.session.getRawStream({ sinceLast: true, stripAnsi: true });
-			// Truncate if exceeds maxChars
-			const truncated = newOutput.length > requestedMaxChars;
-			const output = truncated ? newOutput.slice(-requestedMaxChars) : newOutput;
-			return {
-				output,
-				truncated,
-				totalBytes: output.length,
-			};
-		}
-
-		// Offset mode: use getLogSlice for pagination through full output
-		if (opts.offset !== undefined) {
-			const result = this.session.getLogSlice({
-				offset: opts.offset,
-				limit: requestedLines,
-				stripAnsi: true,
-			});
-			// Apply maxChars limit
-			const truncatedByChars = result.slice.length > requestedMaxChars;
-			const output = truncatedByChars ? result.slice.slice(0, requestedMaxChars) : result.slice;
-			// Calculate hasMore based on whether there are more lines after this slice
-			const hasMore = (opts.offset + result.sliceLineCount) < result.totalLines;
-			return {
-				output,
-				truncated: truncatedByChars || result.sliceLineCount >= requestedLines,
-				totalBytes: output.length,
-				totalLines: result.totalLines,
-				hasMore,
-			};
-		}
-
-		// Default: Use rendered terminal output (tail)
-		// This gives clean, readable content without TUI animation garbage
-		const tailResult = this.session.getTailLines({
-			lines: requestedLines,
-			ansi: false,
-			maxChars: requestedMaxChars,
-		});
-
-		const output = tailResult.lines.join("\n");
-		const totalBytes = output.length;
-		const truncated = tailResult.lines.length >= requestedLines || tailResult.truncatedByChars;
-
-		return { output, truncated, totalBytes, totalLines: tailResult.totalLinesInBuffer };
+		return getSessionOutput(this.session, this.config, this.queryState, options, this.completionResult?.completionOutput);
 	}
 
 	/** Get current session status */
@@ -427,13 +303,21 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			}
 		}, 2000);
 
+		if (this.options.autoExitOnQuiet) {
+			this.resetQuietTimer();
+		}
+
 		this.handsFreeInterval = setInterval(() => {
 			if (this.state === "hands-free") {
 				if (this.updateMode === "on-quiet") {
 					if (this.hasUnsentData && this.options.onHandsFreeUpdate) {
 						this.emitHandsFreeUpdate();
 						this.hasUnsentData = false;
-						this.stopQuietTimer();
+						if (this.options.autoExitOnQuiet) {
+							this.resetQuietTimer();
+						} else {
+							this.stopQuietTimer();
+						}
 					}
 				} else {
 					this.emitHandsFreeUpdate();
@@ -442,7 +326,6 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		}, this.currentUpdateInterval);
 	}
 
-	/** Reset the quiet timer - called on each data event in on-quiet mode */
 	private resetQuietTimer(): void {
 		this.stopQuietTimer();
 		this.quietTimer = setTimeout(() => {
@@ -510,7 +393,11 @@ export class InteractiveShellOverlay implements Component, Focusable {
 						if (this.hasUnsentData && this.options.onHandsFreeUpdate) {
 							this.emitHandsFreeUpdate();
 							this.hasUnsentData = false;
-							this.stopQuietTimer();
+							if (this.options.autoExitOnQuiet) {
+								this.resetQuietTimer();
+							} else {
+								this.stopQuietTimer();
+							}
 						}
 					} else {
 						this.emitHandsFreeUpdate();
@@ -526,9 +413,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		if (clamped === this.currentQuietThreshold) return;
 		this.currentQuietThreshold = clamped;
 
-		// If a quiet timer is active, restart it with the new threshold
-		// Use resetQuietTimer to ensure autoExitOnQuiet logic is included
-		if (this.quietTimer && this.updateMode === "on-quiet") {
+		if (this.quietTimer) {
 			this.resetQuietTimer();
 		}
 	}
@@ -624,8 +509,6 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.state = "running";
 		this.userTookOver = true;
 
-		// Notify agent that user took over (streaming mode)
-		// In non-blocking mode, keep session registered so agent can query status
 		if (this.options.onHandsFreeUpdate) {
 			this.options.onHandsFreeUpdate({
 				status: "user-takeover",
@@ -637,103 +520,35 @@ export class InteractiveShellOverlay implements Component, Focusable {
 				totalCharsSent: this.totalCharsSent,
 				budgetExhausted: this.budgetExhausted,
 			});
-			// Unregister and release ID in streaming mode - agent got notified, won't query
+		}
+		// In streaming mode (blocking tool call), unregister now since the agent
+		// gets the result via tool return. Otherwise keep registered for queries.
+		if (this.options.streamingMode) {
 			this.unregisterActiveSession(true);
 		}
-		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
-		// so agent can query and see "user-takeover" status
 
 		this.tui.requestRender();
 	}
 
 	/** Capture output for dispatch completion notifications */
 	private captureCompletionOutput(): InteractiveShellResult["completionOutput"] {
-		const result = this.session.getTailLines({
-			lines: this.config.completionNotifyLines,
-			ansi: false,
-			maxChars: this.config.completionNotifyMaxChars,
-		});
-		return {
-			lines: result.lines,
-			totalLines: result.totalLinesInBuffer,
-			truncated: result.lines.length < result.totalLinesInBuffer || result.truncatedByChars,
-		};
+		return captureCompletionOutput(this.session, this.config);
 	}
 
 	/** Capture output for transfer action (Ctrl+T or dialog) */
 	private captureTransferOutput(): InteractiveShellResult["transferred"] {
-		const maxLines = this.config.transferLines;
-		const maxChars = this.config.transferMaxChars;
-
-		const result = this.session.getTailLines({
-			lines: maxLines,
-			ansi: false,
-			maxChars,
-		});
-
-		const truncated = result.lines.length < result.totalLinesInBuffer || result.truncatedByChars;
-
-		return {
-			lines: result.lines,
-			totalLines: result.totalLinesInBuffer,
-			truncated,
-		};
+		return captureTransferOutput(this.session, this.config);
 	}
 
 	private maybeBuildHandoffPreview(when: "exit" | "detach" | "kill" | "timeout" | "transfer"): InteractiveShellResult["handoffPreview"] | undefined {
-		const enabled = this.options.handoffPreviewEnabled ?? this.config.handoffPreviewEnabled;
-		if (!enabled) return undefined;
-
-		const lines = this.options.handoffPreviewLines ?? this.config.handoffPreviewLines;
-		const maxChars = this.options.handoffPreviewMaxChars ?? this.config.handoffPreviewMaxChars;
-		if (lines <= 0 || maxChars <= 0) return undefined;
-
-		const result = this.session.getTailLines({
-			lines,
-			ansi: false,
-			maxChars,
-		});
-
-		return { type: "tail", when, lines: result.lines };
+		return maybeBuildHandoffPreview(this.session, when, this.config, this.options);
 	}
 
 	private maybeWriteHandoffSnapshot(when: "exit" | "detach" | "kill" | "timeout" | "transfer"): InteractiveShellResult["handoff"] | undefined {
-		const enabled = this.options.handoffSnapshotEnabled ?? this.config.handoffSnapshotEnabled;
-		if (!enabled) return undefined;
-
-		const lines = this.options.handoffSnapshotLines ?? this.config.handoffSnapshotLines;
-		const maxChars = this.options.handoffSnapshotMaxChars ?? this.config.handoffSnapshotMaxChars;
-		if (lines <= 0 || maxChars <= 0) return undefined;
-
-		const baseDir = join(homedir(), ".pi", "agent", "cache", "interactive-shell");
-		mkdirSync(baseDir, { recursive: true });
-
-		const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-		const pid = this.session.pid;
-		const filename = `snapshot-${timestamp}-pid${pid}.log`;
-		const transcriptPath = join(baseDir, filename);
-
-		const tailResult = this.session.getTailLines({
-			lines,
-			ansi: this.config.ansiReemit,
-			maxChars,
-		});
-
-		const header = [
-			`# interactive-shell snapshot (${when})`,
-			`time: ${new Date().toISOString()}`,
-			`command: ${this.options.command}`,
-			`cwd: ${this.options.cwd ?? ""}`,
-			`pid: ${pid}`,
-			`exitCode: ${this.session.exitCode ?? ""}`,
-			`signal: ${this.session.signal ?? ""}`,
-			`lines: ${tailResult.lines.length} (requested ${lines}, maxChars ${maxChars})`,
-			"",
-		].join("\n");
-
-		writeFileSync(transcriptPath, header + tailResult.lines.join("\n") + "\n", { encoding: "utf-8" });
-
-		return { type: "snapshot", when, transcriptPath, linesWritten: tailResult.lines.length };
+		return maybeWriteHandoffSnapshot(this.session, when, this.config, {
+			command: this.options.command,
+			cwd: this.options.cwd,
+		}, this.options);
 	}
 
 	private finishWithExit(): void {
@@ -761,10 +576,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.completionResult = result;
 		this.triggerCompleteCallbacks();
 
-		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
-		// so agent can query completion result. Agent's query will unregister.
-		// In streaming mode, unregister now since agent got final update.
-		if (this.options.onHandsFreeUpdate) {
+		// In streaming mode (blocking tool call), unregister now since the agent
+		// gets the result via tool return. Otherwise keep registered for queries.
+		if (this.options.streamingMode) {
 			this.unregisterActiveSession(true);
 		}
 
@@ -785,7 +599,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		const handoffPreview = this.maybeBuildHandoffPreview("detach");
 		const handoff = this.maybeWriteHandoffSnapshot("detach");
 		const addOptions = this.sessionId
-			? { id: this.sessionId, noAutoCleanup: this.options.mode === "dispatch" }
+			? { id: this.sessionId, noAutoCleanup: this.options.mode === "dispatch", startedAt: new Date(this.startTime) }
 			: undefined;
 		const id = sessionManager.add(this.options.command, this.session, this.options.name, this.options.reason, addOptions);
 		const result: InteractiveShellResult = {
@@ -801,10 +615,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.completionResult = result;
 		this.triggerCompleteCallbacks();
 
-		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
-		// so agent can query completion result. Agent's query will unregister.
-		// Use releaseId=false because the background session now owns the ID.
-		if (this.options.onHandsFreeUpdate) {
+		// In streaming mode (blocking tool call), unregister now since the agent
+		// gets the result via tool return. releaseId=false because background owns the ID.
+		if (this.options.streamingMode) {
 			this.unregisterActiveSession(false);
 		}
 
@@ -836,9 +649,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.completionResult = result;
 		this.triggerCompleteCallbacks();
 
-		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
-		// so agent can query completion result. Agent's query will unregister.
-		if (this.options.onHandsFreeUpdate) {
+		// In streaming mode (blocking tool call), unregister now since the agent
+		// gets the result via tool return. Otherwise keep registered for queries.
+		if (this.options.streamingMode) {
 			this.unregisterActiveSession(true);
 		}
 
@@ -875,9 +688,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.completionResult = result;
 		this.triggerCompleteCallbacks();
 
-		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
-		// so agent can query completion result. Agent's query will unregister.
-		if (this.options.onHandsFreeUpdate) {
+		// In streaming mode (blocking tool call), unregister now since the agent
+		// gets the result via tool return. Otherwise keep registered for queries.
+		if (this.options.streamingMode) {
 			this.unregisterActiveSession(true);
 		}
 
@@ -929,9 +742,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.completionResult = result;
 		this.triggerCompleteCallbacks();
 
-		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
-		// so agent can query completion result. Agent's query will unregister.
-		if (this.options.onHandsFreeUpdate) {
+		// In streaming mode (blocking tool call), unregister now since the agent
+		// gets the result via tool return. Otherwise keep registered for queries.
+		if (this.options.streamingMode) {
 			this.unregisterActiveSession(true);
 		}
 
@@ -1040,6 +853,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 	}
 
 	render(width: number): string[] {
+		width = Math.max(4, width);
 		const th = this.theme;
 		const border = (s: string) => th.fg("border", s);
 		const accent = (s: string) => th.fg("accent", s);
@@ -1176,10 +990,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		if (!this.completionResult) {
 			this.session.kill();
 			this.session.dispose();
-			// Release ID since session is dead and agent can't query anymore
 			this.unregisterActiveSession(true);
-		} else if (this.options.onHandsFreeUpdate) {
-			// Streaming mode already delivered result, safe to unregister and release
+		} else if (this.options.streamingMode) {
+			// Streaming mode already delivered result via tool return, safe to clean up
 			this.unregisterActiveSession(true);
 		}
 		// Non-blocking mode with completion: keep registered so agent can query

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-interactive-shell",
-  "version": "0.8.2",
-  "description": "Run AI coding agents as foreground subagents in pi TUI overlays with hands-free monitoring",
+  "version": "0.10.0",
+  "description": "Run AI coding agents in pi TUI overlays with interactive, hands-free, and dispatch supervision",
   "type": "module",
   "bin": {
     "pi-interactive-shell": "./scripts/install.js"
@@ -17,6 +17,14 @@
     "tool-schema.ts",
     "headless-monitor.ts",
     "types.ts",
+    "background-widget.ts",
+    "handoff-utils.ts",
+    "notification-utils.ts",
+    "pty-log.ts",
+    "pty-protocol.ts",
+    "runtime-coordinator.ts",
+    "session-query.ts",
+    "spawn-helper.ts",
     "scripts/",
     "examples/",
     "banner.png",
@@ -28,15 +36,24 @@
     "extensions": [
       "./index.ts"
     ],
+    "skills": [
+      "./SKILL.md",
+      "./examples/skills"
+    ],
+    "prompts": [
+      "./examples/prompts"
+    ],
     "video": "https://github.com/nicobailon/pi-interactive-shell/raw/refs/heads/main/pi-interactive-shell-extension.mp4"
   },
   "dependencies": {
-    "node-pty": "^1.1.0",
+    "@sinclair/typebox": "^0.34.40",
+    "@xterm/addon-serialize": "^0.13.0",
     "@xterm/headless": "^5.5.0",
-    "@xterm/addon-serialize": "^0.13.0"
+    "node-pty": "^1.1.0"
   },
   "scripts": {
-    "postinstall": "node ./scripts/fix-spawn-helper.cjs"
+    "postinstall": "node ./scripts/fix-spawn-helper.cjs",
+    "test": "vitest run"
   },
   "keywords": [
     "pi-package",
@@ -61,5 +78,8 @@
   "bugs": {
     "url": "https://github.com/nicobailon/pi-interactive-shell/issues"
   },
-  "homepage": "https://github.com/nicobailon/pi-interactive-shell#readme"
+  "homepage": "https://github.com/nicobailon/pi-interactive-shell#readme",
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  }
 }