pi-interactive-shell 0.6.4 → 0.7.0

package/session-manager.ts

@@ -47,14 +47,14 @@ export interface ActiveSession {
 	reason?: string;
 	write: (data: string) => void;
 	kill: () => void;
-	getOutput: (options?: OutputOptions | boolean) => OutputResult; // Get output since last check (truncated if large)
+	background: () => void;
+	getOutput: (options?: OutputOptions | boolean) => OutputResult;
 	getStatus: () => ActiveSessionStatus;
 	getRuntime: () => number;
-	getResult: () => ActiveSessionResult | undefined; // Available when completed
+	getResult: () => ActiveSessionResult | undefined;
 	setUpdateInterval?: (intervalMs: number) => void;
 	setQuietThreshold?: (thresholdMs: number) => void;
-	onComplete: (callback: () => void) => void; // Register callback for when session completes
-	startedAt: Date;
+	onComplete: (callback: () => void) => void;
 }
 
 // Human-readable session slug generation
@@ -124,7 +124,7 @@ export function releaseSessionId(id: string): void {
 }
 
 // Derive a friendly display name from command (e.g., "pi Fix all bugs" -> "pi Fix all bugs")
-export function deriveSessionName(command: string): string {
+function deriveSessionName(command: string): string {
 	const trimmed = command.trim();
 	if (trimmed.length <= 60) return trimmed;
 
@@ -137,26 +137,21 @@ export class ShellSessionManager {
 	private exitWatchers = new Map<string, NodeJS.Timeout>();
 	private cleanupTimers = new Map<string, NodeJS.Timeout>();
 	private activeSessions = new Map<string, ActiveSession>();
+	private changeListeners = new Set<() => void>();
 
-	// Active hands-free session management
-	registerActive(session: {
-		id: string;
-		command: string;
-		reason?: string;
-		write: (data: string) => void;
-		kill: () => void;
-		getOutput: (options?: OutputOptions | 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,
-			startedAt: new Date(),
-		});
+	onChange(listener: () => void): () => void {
+		this.changeListeners.add(listener);
+		return () => { this.changeListeners.delete(listener); };
+	}
+
+	private notifyChange(): void {
+		for (const listener of this.changeListeners) {
+			try { listener(); } catch { /* ignore */ }
+		}
+	}
+
+	registerActive(session: ActiveSession): void {
+		this.activeSessions.set(session.id, session);
 	}
 
 	unregisterActive(id: string, releaseId = false): void {
@@ -193,42 +188,67 @@ export class ShellSessionManager {
 		return true;
 	}
 
-	listActive(): ActiveSession[] {
-		return Array.from(this.activeSessions.values());
-	}
-
-	// Background session management
-	add(command: string, session: PtyTerminalSession, name?: string, reason?: string): string {
-		const id = generateSessionId(name);
+	add(command: string, session: PtyTerminalSession, name?: string, reason?: string, options?: { id?: string; noAutoCleanup?: boolean; startedAt?: Date }): string {
+		const id = options?.id ?? generateSessionId(name);
+		if (options?.id) usedIds.add(id);
 		this.sessions.set(id, {
 			id,
 			name: name || deriveSessionName(command),
 			command,
 			reason,
 			session,
-			startedAt: new Date(),
+			startedAt: options?.startedAt ?? new Date(),
 		});
 
 		session.setEventHandlers({});
 
-		const checkExit = setInterval(() => {
-			if (session.exited) {
-				clearInterval(checkExit);
-				this.exitWatchers.delete(id);
-				const cleanupTimer = setTimeout(() => {
-					this.cleanupTimers.delete(id);
-					this.remove(id);
-				}, 30000);
-				this.cleanupTimers.set(id, cleanupTimer);
-			}
-		}, 1000);
-		this.exitWatchers.set(id, checkExit);
+		if (!options?.noAutoCleanup) {
+			const checkExit = setInterval(() => {
+				if (session.exited) {
+					clearInterval(checkExit);
+					this.exitWatchers.delete(id);
+					this.notifyChange();
+					const cleanupTimer = setTimeout(() => {
+						this.cleanupTimers.delete(id);
+						this.remove(id);
+					}, 30000);
+					this.cleanupTimers.set(id, cleanupTimer);
+				}
+			}, 1000);
+			this.exitWatchers.set(id, checkExit);
+		}
 
+		this.notifyChange();
 		return id;
 	}
 
+	take(id: string): BackgroundSession | undefined {
+		const watcher = this.exitWatchers.get(id);
+		if (watcher) {
+			clearInterval(watcher);
+			this.exitWatchers.delete(id);
+		}
+		const cleanupTimer = this.cleanupTimers.get(id);
+		if (cleanupTimer) {
+			clearTimeout(cleanupTimer);
+			this.cleanupTimers.delete(id);
+		}
+		const session = this.sessions.get(id);
+		if (session) {
+			this.sessions.delete(id);
+			this.notifyChange();
+			return session;
+		}
+		return undefined;
+	}
+
 	get(id: string): BackgroundSession | undefined {
-		// Cancel auto-cleanup timer when session is being reattached
+		// Suspend all auto-cleanup while session is being actively used
+		const watcher = this.exitWatchers.get(id);
+		if (watcher) {
+			clearInterval(watcher);
+			this.exitWatchers.delete(id);
+		}
 		const cleanupTimer = this.cleanupTimers.get(id);
 		if (cleanupTimer) {
 			clearTimeout(cleanupTimer);
@@ -237,6 +257,34 @@ export class ShellSessionManager {
 		return this.sessions.get(id);
 	}
 
+	restartAutoCleanup(id: string): void {
+		if (this.exitWatchers.has(id)) return;
+		const entry = this.sessions.get(id);
+		if (!entry) return;
+		if (entry.session.exited) {
+			this.scheduleCleanup(id);
+			return;
+		}
+		const checkExit = setInterval(() => {
+			if (entry.session.exited) {
+				clearInterval(checkExit);
+				this.exitWatchers.delete(id);
+				this.notifyChange();
+				this.scheduleCleanup(id);
+			}
+		}, 1000);
+		this.exitWatchers.set(id, checkExit);
+	}
+
+	scheduleCleanup(id: string, delayMs = 30000): void {
+		if (this.cleanupTimers.has(id)) return;
+		const timer = setTimeout(() => {
+			this.cleanupTimers.delete(id);
+			this.remove(id);
+		}, delayMs);
+		this.cleanupTimers.set(id, timer);
+	}
+
 	remove(id: string): void {
 		const watcher = this.exitWatchers.get(id);
 		if (watcher) {
@@ -255,6 +303,7 @@ export class ShellSessionManager {
 			session.session.dispose();
 			this.sessions.delete(id);
 			releaseSessionId(id);
+			this.notifyChange();
 		}
 	}
 

package/tool-schema.ts

@@ -12,11 +12,13 @@ DO NOT use this for regular bash commands - use the standard bash tool instead.
 MODES:
 - interactive (default): User supervises and controls the session
 - hands-free: Agent monitors with periodic updates, user can take over anytime by typing
+- dispatch: Agent is notified on completion via triggerTurn (no polling needed)
 
 The user will see the process in an overlay. They can:
 - Watch output in real-time
 - Scroll through output (Shift+Up/Down)
 - Transfer output to you (Ctrl+T) - closes overlay and sends output as your context
+- Background (Ctrl+B) - dismiss overlay, keep process running
 - Detach (Ctrl+Q) for menu: transfer/background/kill
 - In hands-free mode: type anything to take over control
 
@@ -68,6 +70,39 @@ TIMEOUT (for TUI commands that don't exit cleanly):
 Use timeout to auto-kill after N milliseconds. Useful for capturing output from commands like "pi --help":
 - interactive_shell({ command: "pi --help", mode: "hands-free", timeout: 5000 })
 
+DISPATCH MODE (NON-BLOCKING, NO POLLING):
+When mode="dispatch", the tool returns IMMEDIATELY with a sessionId.
+You do NOT need to poll. You'll be notified automatically when the session completes.
+
+Workflow:
+1. Start session: interactive_shell({ command: 'pi "Fix bugs"', mode: "dispatch" })
+   -> Returns immediately with sessionId
+2. Do other work - no polling needed
+3. When complete, you receive a notification with the session output
+
+Dispatch defaults autoExitOnQuiet to true (opt-out with handsFree.autoExitOnQuiet: false).
+You can still query with sessionId if needed, but it's not required.
+
+BACKGROUND DISPATCH (HEADLESS):
+Start a session without any overlay. Process runs headlessly, agent notified on completion:
+- interactive_shell({ command: 'pi "fix bugs"', mode: "dispatch", background: true })
+
+AGENT-INITIATED BACKGROUND:
+Dismiss an existing overlay, keep the process running in background:
+- interactive_shell({ sessionId: "calm-reef", background: true })
+
+ATTACH (REATTACH TO BACKGROUND SESSION):
+Open an overlay for a background session:
+- interactive_shell({ attach: "calm-reef" }) - interactive (blocking)
+- interactive_shell({ attach: "calm-reef", mode: "dispatch" }) - dispatch (non-blocking, notified)
+
+LIST BACKGROUND SESSIONS:
+- interactive_shell({ listBackground: true })
+
+DISMISS BACKGROUND SESSIONS:
+- interactive_shell({ dismissBackground: true }) - kill running, remove exited, clear all
+- interactive_shell({ dismissBackground: "calm-reef" }) - dismiss specific session
+
 Important: this tool does NOT inject prompts. If you want to start with a prompt,
 include it in the command using the CLI's own prompt flags.
 
@@ -165,7 +200,27 @@ export const toolParameters = Type.Object({
 	),
 	mode: Type.Optional(
 		Type.String({
-			description: "Mode: 'interactive' (default, user controls) or 'hands-free' (agent monitors, user can take over)",
+			description: "Mode: 'interactive' (default, user controls), 'hands-free' (agent monitors, user can take over), or 'dispatch' (agent notified on completion, no polling needed)",
+		}),
+	),
+	background: Type.Optional(
+		Type.Boolean({
+			description: "Run without overlay (with mode='dispatch') or dismiss existing overlay (with sessionId). Process runs in background, user can /attach.",
+		}),
+	),
+	attach: Type.Optional(
+		Type.String({
+			description: "Background session ID to reattach. Opens overlay with the specified mode.",
+		}),
+	),
+	listBackground: Type.Optional(
+		Type.Boolean({
+			description: "List all background sessions.",
+		}),
+	),
+	dismissBackground: Type.Optional(
+		Type.Union([Type.Boolean(), Type.String()], {
+			description: "Dismiss background sessions. true = all, string = specific session ID. Kills running sessions, removes exited ones.",
 		}),
 	),
 	handsFree: Type.Optional(
@@ -235,7 +290,11 @@ export interface ToolParams {
 	cwd?: string;
 	name?: string;
 	reason?: string;
-	mode?: "interactive" | "hands-free";
+	mode?: "interactive" | "hands-free" | "dispatch";
+	background?: boolean;
+	attach?: string;
+	listBackground?: boolean;
+	dismissBackground?: boolean | string;
 	handsFree?: {
 		updateMode?: "on-quiet" | "interval";
 		updateInterval?: number;

package/types.ts

@@ -17,6 +17,12 @@ export interface InteractiveShellResult {
 		totalLines: number;
 		truncated: boolean;
 	};
+	/** Captured before PTY disposal for dispatch mode completion notifications */
+	completionOutput?: {
+		lines: string[];
+		totalLines: number;
+		truncated: boolean;
+	};
 	handoffPreview?: {
 		type: "tail";
 		when: "exit" | "detach" | "kill" | "timeout" | "transfer";
@@ -53,9 +59,9 @@ export interface InteractiveShellOptions {
 	handoffSnapshotEnabled?: boolean;
 	handoffSnapshotLines?: number;
 	handoffSnapshotMaxChars?: number;
-	// Hands-free mode
-	mode?: "interactive" | "hands-free";
-	sessionId?: string; // Pre-generated sessionId for hands-free mode
+	// Hands-free / dispatch mode
+	mode?: "interactive" | "hands-free" | "dispatch";
+	sessionId?: string; // Pre-generated sessionId for non-blocking modes
 	handsFreeUpdateMode?: "on-quiet" | "interval";
 	handsFreeUpdateInterval?: number;
 	handsFreeQuietThreshold?: number;
@@ -66,6 +72,8 @@ export interface InteractiveShellOptions {
 	autoExitOnQuiet?: boolean;
 	// Auto-kill timeout
 	timeout?: number;
+	// Existing PTY session (for attach flow -- skip creating a new PTY)
+	existingSession?: import("./pty-session.js").PtyTerminalSession;
 }
 
 export type DialogChoice = "kill" | "background" | "transfer" | "cancel";