pi-interactive-shell 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to the `pi-interactive-shell` extension will be documented in this file.
 
+## [0.4.2] - 2026-01-17
+
+### Added
+- **Query rate limiting** - Queries are limited to once every 60 seconds by default. If you query too soon, the tool automatically waits until the limit expires before returning (blocking behavior). Configurable via `minQueryIntervalSeconds` in settings (range: 5-300 seconds). Note: Rate limiting does not apply to completed sessions or kills - you can always query the final result immediately.
+
+### Changed
+- **autoExitOnQuiet now defaults to true** - In hands-free mode, sessions auto-kill when output stops (~5s of quiet). Set `handsFree: { autoExitOnQuiet: false }` to disable.
+- **Smaller default overlay** - Height reduced from 90% to 45%. Configurable via `overlayHeightPercent` in settings (range: 20-90%).
+
+### Fixed
+- **Rate limit wait now interruptible** - When waiting for rate limit, the wait is interrupted immediately if the session completes (user kills, process exits, etc.). Uses Promise.race with onComplete callback instead of blocking sleep.
+- **scrollbackLines NaN handling** - Config now uses `clampInt` like other numeric fields, preventing NaN from breaking xterm scrollback.
+- **autoExitOnQuiet status mismatch** - Now sends "killed" status (not "exited") to match `finishWithKill()` behavior.
+- **hasNewOutput semantics** - Renamed to `hasOutput` since we use tail-based output, not incremental tracking.
+- **dispose() orphaned sessions** - Now kills running processes before unregistering to prevent orphaned sessions.
+- **killAll() premature ID release** - IDs now released via natural cleanup after process exit, not immediately after kill() call.
+
 ## [0.4.1] - 2026-01-17
 
 ### Changed

package/README.md

@@ -146,7 +146,7 @@ Project: `<cwd>/.pi/interactive-shell.json`
   "doubleEscapeThreshold": 300,
   "exitAutoCloseDelay": 10,
   "overlayWidthPercent": 95,
-  "overlayHeightPercent": 90,
+  "overlayHeightPercent": 45,
   "scrollbackLines": 5000,
   "ansiReemit": true,
   "handoffPreviewEnabled": true,

package/SKILL.md

@@ -113,7 +113,7 @@ Returns:
 - `output`: Last 20 lines of rendered terminal (clean, no TUI animation noise)
 - `runtime`: Time elapsed in ms
 
-**Don't query too frequently!** Wait 30-60 seconds between checks. The user is watching the overlay in real-time - you're just checking in periodically to see progress.
+**Rate limited:** Queries are limited to once every 60 seconds. If you query too soon, the tool will automatically wait until the limit expires before returning. The user is watching the overlay in real-time - you're just checking in periodically.
 
 ### Ending a Session
 ```typescript
@@ -122,6 +122,8 @@ interactive_shell({ sessionId: "calm-reef", kill: true })
 
 Kill when you see the task is complete in the output. Returns final status and output.
 
+**Auto-exit:** In hands-free mode, sessions auto-kill when output stops (after ~5 seconds of quiet). This means when an agent finishes its task, the session closes automatically. You can disable this with `handsFree: { autoExitOnQuiet: false }`.
+
 ### Sending Input
 ```typescript
 interactive_shell({ sessionId: "calm-reef", input: "/help\n" })

package/config.ts

@@ -21,13 +21,15 @@ export interface InteractiveShellConfig {
 	handsFreeQuietThreshold: number;
 	handsFreeUpdateMaxChars: number;
 	handsFreeMaxTotalChars: number;
+	// Query rate limiting
+	minQueryIntervalSeconds: number;
 }
 
 const DEFAULT_CONFIG: InteractiveShellConfig = {
 	doubleEscapeThreshold: 300,
 	exitAutoCloseDelay: 10,
 	overlayWidthPercent: 95,
-	overlayHeightPercent: 90,
+	overlayHeightPercent: 45,
 	scrollbackLines: 5000,
 	ansiReemit: true,
 	handoffPreviewEnabled: true,
@@ -42,6 +44,8 @@ const DEFAULT_CONFIG: InteractiveShellConfig = {
 	handsFreeQuietThreshold: 5000,
 	handsFreeUpdateMaxChars: 1500,
 	handsFreeMaxTotalChars: 100000,
+	// Query rate limiting (default 60 seconds between queries)
+	minQueryIntervalSeconds: 60,
 };
 
 export function loadConfig(cwd: string): InteractiveShellConfig {
@@ -72,8 +76,9 @@ export function loadConfig(cwd: string): InteractiveShellConfig {
 	return {
 		...merged,
 		overlayWidthPercent: clampPercent(merged.overlayWidthPercent, DEFAULT_CONFIG.overlayWidthPercent),
-		overlayHeightPercent: clampPercent(merged.overlayHeightPercent, DEFAULT_CONFIG.overlayHeightPercent),
-		scrollbackLines: Math.max(200, merged.scrollbackLines ?? DEFAULT_CONFIG.scrollbackLines),
+		// Height: 20-90% range (default 45%)
+		overlayHeightPercent: clampInt(merged.overlayHeightPercent, DEFAULT_CONFIG.overlayHeightPercent, 20, 90),
+		scrollbackLines: clampInt(merged.scrollbackLines, DEFAULT_CONFIG.scrollbackLines, 200, 50000),
 		ansiReemit: merged.ansiReemit !== false,
 		handoffPreviewEnabled: merged.handoffPreviewEnabled !== false,
 		handoffPreviewLines: clampInt(merged.handoffPreviewLines, DEFAULT_CONFIG.handoffPreviewLines, 0, 500),
@@ -117,6 +122,13 @@ export function loadConfig(cwd: string): InteractiveShellConfig {
 			10000,
 			1000000,
 		),
+		// Query rate limiting (min 5 seconds, max 300 seconds)
+		minQueryIntervalSeconds: clampInt(
+			merged.minQueryIntervalSeconds,
+			DEFAULT_CONFIG.minQueryIntervalSeconds,
+			5,
+			300,
+		),
 	};
 }
 

package/index.ts

@@ -319,6 +319,10 @@ QUERYING SESSION STATUS:
 IMPORTANT: Don't query too frequently! Wait 30-60 seconds between status checks.
 The user is watching the overlay in real-time - you're just checking in periodically.
 
+RATE LIMITING:
+Queries are limited to once every 60 seconds (configurable). If you query too soon,
+the tool will automatically wait until the limit expires before returning.
+
 SENDING INPUT:
 - interactive_shell({ sessionId: "calm-reef", input: "/help\\n" })
 - interactive_shell({ sessionId: "calm-reef", input: { keys: ["ctrl+c"] } })
@@ -437,7 +441,7 @@ Examples:
 					),
 					autoExitOnQuiet: Type.Optional(
 						Type.Boolean({
-							description: "Auto-kill session when output stops (after quietThreshold). Use for agents that don't exit on their own after completing a task.",
+							description: "Auto-kill session when output stops (after quietThreshold). Defaults to true in hands-free mode. Set to false to keep session alive indefinitely.",
 						}),
 					),
 				}),
@@ -516,7 +520,7 @@ Examples:
 
 				// Kill session if requested
 				if (kill) {
-					const { output, truncated, totalBytes } = session.getOutput();
+					const { output, truncated, totalBytes } = session.getOutput(true); // skipRateLimit=true for kill
 					const status = session.getStatus();
 					const runtime = session.getRuntime();
 					session.kill();
@@ -592,16 +596,17 @@ Examples:
 
 				// If only querying status (no input, no settings, no kill)
 				if (actions.length === 0) {
-					const { output, truncated, totalBytes } = session.getOutput();
 					const status = session.getStatus();
 					const runtime = session.getRuntime();
 					const result = session.getResult();
 
-					const truncatedNote = truncated ? ` (${totalBytes} bytes total, truncated to last 10KB)` : "";
-					const hasOutput = output.length > 0;
-
-					// Check if session completed
+					// If session completed, always allow query (no rate limiting)
+					// Rate limiting only applies to "checking in" on running sessions
 					if (result) {
+						const { output, truncated, totalBytes } = session.getOutput(true); // skipRateLimit=true
+						const truncatedNote = truncated ? ` (${totalBytes} bytes total, truncated)` : "";
+						const hasOutput = output.length > 0;
+
 						sessionManager.unregisterActive(sessionId, true);
 						return {
 							content: [
@@ -624,11 +629,138 @@ Examples:
 						};
 					}
 
+					// Session still running - check rate limiting
+					const outputResult = session.getOutput();
+
+					// If rate limited, wait until allowed then return fresh result
+					// Use Promise.race to detect if session completes during wait
+					if (outputResult.rateLimited && outputResult.waitSeconds) {
+						const waitMs = outputResult.waitSeconds * 1000;
+						
+						// Race: rate limit timeout vs session completion
+						const completedEarly = await Promise.race([
+							new Promise<false>((resolve) => setTimeout(() => resolve(false), waitMs)),
+							new Promise<true>((resolve) => session.onComplete(() => resolve(true))),
+						]);
+						
+						// If session completed during wait, return result immediately
+						if (completedEarly) {
+							const earlySession = sessionManager.getActive(sessionId);
+							if (!earlySession) {
+								return {
+									content: [{ type: "text", text: `Session ${sessionId} ended` }],
+									details: { sessionId, status: "ended" },
+								};
+							}
+							const earlyResult = earlySession.getResult();
+							const { output, truncated, totalBytes } = earlySession.getOutput(true); // skipRateLimit
+							const earlyStatus = earlySession.getStatus();
+							const earlyRuntime = earlySession.getRuntime();
+							const truncatedNote = truncated ? ` (${totalBytes} bytes total, truncated)` : "";
+							const hasOutput = output.length > 0;
+							
+							if (earlyResult) {
+								sessionManager.unregisterActive(sessionId, true);
+								return {
+									content: [
+										{
+											type: "text",
+											text: `Session ${sessionId} ${earlyStatus} after ${formatDurationMs(earlyRuntime)}${hasOutput ? `\n\nOutput${truncatedNote}:\n${output}` : ""}`,
+										},
+									],
+									details: {
+										sessionId,
+										status: earlyStatus,
+										runtime: earlyRuntime,
+										output,
+										outputTruncated: truncated,
+										outputTotalBytes: totalBytes,
+										exitCode: earlyResult.exitCode,
+										signal: earlyResult.signal,
+										backgroundId: earlyResult.backgroundId,
+									},
+								};
+							}
+							// Edge case: onComplete fired but no result yet (shouldn't happen)
+							// Return current status without unregistering
+							return {
+								content: [
+									{
+										type: "text",
+										text: `Session ${sessionId} ${earlyStatus} (${formatDurationMs(earlyRuntime)})${hasOutput ? `\n\nOutput${truncatedNote}:\n${output}` : ""}`,
+									},
+								],
+								details: {
+									sessionId,
+									status: earlyStatus,
+									runtime: earlyRuntime,
+									output,
+									outputTruncated: truncated,
+									outputTotalBytes: totalBytes,
+									hasOutput,
+								},
+							};
+						}
+						// Get fresh output after waiting
+						const freshOutput = session.getOutput();
+						const truncatedNote = freshOutput.truncated ? ` (${freshOutput.totalBytes} bytes total, truncated)` : "";
+						const hasOutput = freshOutput.output.length > 0;
+						const freshStatus = session.getStatus();
+						const freshRuntime = session.getRuntime();
+						const freshResult = session.getResult();
+
+						if (freshResult) {
+							sessionManager.unregisterActive(sessionId, true);
+							return {
+								content: [
+									{
+										type: "text",
+										text: `Session ${sessionId} ${freshStatus} after ${formatDurationMs(freshRuntime)}${hasOutput ? `\n\nOutput${truncatedNote}:\n${freshOutput.output}` : ""}`,
+									},
+								],
+								details: {
+									sessionId,
+									status: freshStatus,
+									runtime: freshRuntime,
+									output: freshOutput.output,
+									outputTruncated: freshOutput.truncated,
+									outputTotalBytes: freshOutput.totalBytes,
+									exitCode: freshResult.exitCode,
+									signal: freshResult.signal,
+									backgroundId: freshResult.backgroundId,
+								},
+							};
+						}
+
+						return {
+							content: [
+								{
+									type: "text",
+									text: `Session ${sessionId} ${freshStatus} (${formatDurationMs(freshRuntime)})${hasOutput ? `\n\nOutput${truncatedNote}:\n${freshOutput.output}` : ""}`,
+								},
+							],
+							details: {
+								sessionId,
+								status: freshStatus,
+								runtime: freshRuntime,
+								output: freshOutput.output,
+								outputTruncated: freshOutput.truncated,
+								outputTotalBytes: freshOutput.totalBytes,
+								hasOutput,
+							},
+						};
+					}
+
+					const { output, truncated, totalBytes } = outputResult;
+
+					const truncatedNote = truncated ? ` (${totalBytes} bytes total, truncated)` : "";
+					const hasOutput = output.length > 0;
+
 					return {
 						content: [
 							{
 								type: "text",
-								text: `Session ${sessionId} ${status} (${formatDurationMs(runtime)})${hasOutput ? `\n\nNew output${truncatedNote}:\n${output}` : "\n\n(no new output)"}`,
+								text: `Session ${sessionId} ${status} (${formatDurationMs(runtime)})${hasOutput ? `\n\nOutput${truncatedNote}:\n${output}` : ""}`,
 							},
 						],
 						details: {
@@ -638,7 +770,7 @@ Examples:
 							output,
 							outputTruncated: truncated,
 							outputTotalBytes: totalBytes,
-							hasNewOutput: hasOutput,
+							hasOutput,
 						},
 					};
 				}
@@ -699,7 +831,8 @@ Examples:
 								handsFreeQuietThreshold: handsFree?.quietThreshold,
 								handsFreeUpdateMaxChars: handsFree?.updateMaxChars,
 								handsFreeMaxTotalChars: handsFree?.maxTotalChars,
-								autoExitOnQuiet: handsFree?.autoExitOnQuiet,
+								// Default autoExitOnQuiet to true in hands-free mode
+								autoExitOnQuiet: handsFree?.autoExitOnQuiet !== false,
 								// No onHandsFreeUpdate in non-blocking mode - agent queries directly
 								handoffPreviewEnabled: handoffPreview?.enabled,
 								handoffPreviewLines: handoffPreview?.lines,

package/overlay-component.ts

@@ -124,6 +124,10 @@ 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;
+	// Completion callbacks for waiters
+	private completeCallbacks: Array<() => void> = [];
 
 	constructor(
 		tui: TUI,
@@ -221,12 +225,13 @@ export class InteractiveShellOverlay implements Component, Focusable {
 				reason: options.reason,
 				write: (data) => this.session.write(data),
 				kill: () => this.killSession(),
-				getOutput: () => this.getOutputSinceLastCheck(),
+				getOutput: (skipRateLimit) => this.getOutputSinceLastCheck(skipRateLimit),
 				getStatus: () => this.getSessionStatus(),
 				getRuntime: () => this.getRuntime(),
 				getResult: () => this.getCompletionResult(),
 				setUpdateInterval: (intervalMs) => this.setUpdateInterval(intervalMs),
 				setQuietThreshold: (thresholdMs) => this.setQuietThreshold(thresholdMs),
+				onComplete: (callback) => this.registerCompleteCallback(callback),
 			});
 			this.startHandsFreeUpdates();
 		}
@@ -247,7 +252,28 @@ export class InteractiveShellOverlay implements Component, Focusable {
 	private static readonly MAX_STATUS_LINES = 20;
 
 	/** Get rendered terminal output (last N lines, truncated if too large) */
-	getOutputSinceLastCheck(): { output: string; truncated: boolean; totalBytes: number } {
+	getOutputSinceLastCheck(skipRateLimit = false): { output: string; truncated: boolean; totalBytes: number; rateLimited?: boolean; waitSeconds?: number } {
+		// 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;
+		}
+
 		// Use rendered terminal output instead of raw stream
 		// This gives clean, readable content without TUI animation garbage
 		const lines = this.session.getTailLines({
@@ -286,6 +312,28 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		return this.completionResult;
 	}
 
+	/** Register a callback to be called when session completes */
+	registerCompleteCallback(callback: () => void): void {
+		// If already completed, call immediately
+		if (this.completionResult) {
+			callback();
+			return;
+		}
+		this.completeCallbacks.push(callback);
+	}
+
+	/** Trigger all completion callbacks */
+	private triggerCompleteCallbacks(): void {
+		for (const callback of this.completeCallbacks) {
+			try {
+				callback();
+			} catch {
+				// Ignore errors in callbacks
+			}
+		}
+		this.completeCallbacks = [];
+	}
+
 	/** Get the session ID */
 	getSessionId(): string | null {
 		return this.sessionId;
@@ -358,9 +406,10 @@ export class InteractiveShellOverlay implements Component, Focusable {
 						this.hasUnsentData = false;
 					}
 					// Send completion notification and auto-close
+					// Use "killed" status since we're forcibly terminating (matches finishWithKill's cancelled=true)
 					if (this.options.onHandsFreeUpdate && this.sessionId) {
 						this.options.onHandsFreeUpdate({
-							status: "exited",
+							status: "killed",
 							sessionId: this.sessionId,
 							runtime: Date.now() - this.startTime,
 							tail: [],
@@ -631,6 +680,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			handoff,
 		};
 		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.
@@ -663,6 +713,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			handoff,
 		};
 		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.
@@ -694,6 +745,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			handoff,
 		};
 		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.
@@ -746,6 +798,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			handoff,
 		};
 		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.
@@ -970,10 +1023,16 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.stopTimeout();
 		this.stopHandsFreeUpdates();
 		// Safety cleanup in case dispose() is called without going through finishWith*
-		// In non-blocking mode with completion result, keep session so agent can query
-		if (!this.completionResult || this.options.onHandsFreeUpdate) {
+		// If session hasn't completed yet, kill it to prevent orphaned processes
+		if (!this.completionResult) {
+			this.session.kill();
+			this.session.dispose();
+			this.unregisterActiveSession();
+		} else if (this.options.onHandsFreeUpdate) {
+			// Streaming mode already delivered result, safe to unregister
 			this.unregisterActiveSession();
 		}
+		// Non-blocking mode with completion: keep registered so agent can query
 	}
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-interactive-shell",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Run AI coding agents as foreground subagents in pi TUI overlays with hands-free monitoring",
   "type": "module",
   "bin": {

package/session-manager.ts

@@ -24,6 +24,9 @@ export interface OutputResult {
 	output: string;
 	truncated: boolean;
 	totalBytes: number;
+	// Rate limiting
+	rateLimited?: boolean;
+	waitSeconds?: number;
 }
 
 export interface ActiveSession {
@@ -32,12 +35,13 @@ export interface ActiveSession {
 	reason?: string;
 	write: (data: string) => void;
 	kill: () => void;
-	getOutput: () => OutputResult; // Get output since last check (truncated if large)
+	getOutput: (skipRateLimit?: boolean) => OutputResult; // Get output since last check (truncated if large)
 	getStatus: () => ActiveSessionStatus;
 	getRuntime: () => number;
 	getResult: () => ActiveSessionResult | undefined; // Available when completed
 	setUpdateInterval?: (intervalMs: number) => void;
 	setQuietThreshold?: (thresholdMs: number) => void;
+	onComplete: (callback: () => void) => void; // Register callback for when session completes
 	startedAt: Date;
 }
 
@@ -129,12 +133,13 @@ export class ShellSessionManager {
 		reason?: string;
 		write: (data: string) => void;
 		kill: () => void;
-		getOutput: () => OutputResult;
+		getOutput: (skipRateLimit?: boolean) => OutputResult;
 		getStatus: () => ActiveSessionStatus;
 		getRuntime: () => number;
 		getResult: () => ActiveSessionResult | undefined;
 		setUpdateInterval?: (intervalMs: number) => void;
 		setQuietThreshold?: (thresholdMs: number) => void;
+		onComplete: (callback: () => void) => void;
 	}): void {
 		this.activeSessions.set(session.id, {
 			...session,
@@ -259,13 +264,15 @@ export class ShellSessionManager {
 		for (const [id, session] of activeEntries) {
 			try {
 				session.kill();
+				// Only release ID if kill succeeded - let natural cleanup handle failures
+				// The session's exit handler will call unregisterActive() which releases the ID
 			} catch {
-				// Session may already be dead
+				// Session may already be dead - still safe to release since no process running
+				releaseSessionId(id);
 			}
-			// Release ID if not already released by kill()
-			releaseSessionId(id);
 		}
-		this.activeSessions.clear();
+		// Don't clear immediately - let unregisterActive() handle cleanup as sessions exit
+		// This prevents ID reuse while processes are still terminating
 	}
 }