pi-interactive-shell 0.9.0 → 0.10.0

package/pty-session.ts

@@ -1,15 +1,13 @@
-import { chmodSync, statSync } from "node:fs";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
 import * as pty from "node-pty";
 import type { IBufferCell, Terminal as XtermTerminal } from "@xterm/headless";
 import xterm from "@xterm/headless";
 import { SerializeAddon } from "@xterm/addon-serialize";
+import { sliceLogOutput, trimRawOutput } from "./pty-log.js";
+import { splitAroundDsr, buildCursorPositionResponse } from "./pty-protocol.js";
+import { ensureSpawnHelperExec } from "./spawn-helper.js";
 
 const Terminal = xterm.Terminal;
-const require = createRequire(import.meta.url);
-let spawnHelperChecked = false;
 
 // Regex patterns for sanitizing terminal output (used by sanitizeLine for viewport rendering)
 const OSC_REGEX = /\x1b\][^\x07]*(?:\x07|\x1b\\)/g;
@@ -19,79 +17,6 @@ const CSI_REGEX = /\x1b\[[0-9;?]*[A-Za-z]/g;
 const ESC_SINGLE_REGEX = /\x1b[@-_]/g;
 const CONTROL_REGEX = /[\x00-\x08\x0B\x0C\x0E-\x1A\x1C-\x1F\x7F]/g;
 
-// DSR (Device Status Report) - cursor position query: ESC[6n or ESC[?6n
-const DSR_PATTERN = /\x1b\[\??6n/g;
-
-// Maximum raw output buffer size (1MB) - prevents unbounded memory growth
-const MAX_RAW_OUTPUT_SIZE = 1024 * 1024;
-
-interface DsrSplit {
-	segments: Array<{ text: string; dsrAfter: boolean }>;
-	hasDsr: boolean;
-}
-
-function splitAroundDsr(input: string): DsrSplit {
-	const segments: Array<{ text: string; dsrAfter: boolean }> = [];
-	let lastIndex = 0;
-	let hasDsr = false;
-
-	// Find all DSR requests and split around them
-	const regex = new RegExp(DSR_PATTERN.source, "g");
-	let match;
-	while ((match = regex.exec(input)) !== null) {
-		hasDsr = true;
-		// Text before this DSR
-		if (match.index > lastIndex) {
-			segments.push({ text: input.slice(lastIndex, match.index), dsrAfter: true });
-		} else {
-			// DSR at start or consecutive DSRs - add empty segment to trigger response
-			segments.push({ text: "", dsrAfter: true });
-		}
-		lastIndex = match.index + match[0].length;
-	}
-
-	// Remaining text after last DSR (or entire string if no DSR)
-	if (lastIndex < input.length) {
-		segments.push({ text: input.slice(lastIndex), dsrAfter: false });
-	}
-
-	return { segments, hasDsr };
-}
-
-function buildCursorPositionResponse(row = 1, col = 1): string {
-	return `\x1b[${row};${col}R`;
-}
-
-function ensureSpawnHelperExec(): void {
-	if (spawnHelperChecked) return;
-	spawnHelperChecked = true;
-	if (process.platform !== "darwin") return;
-
-	let pkgPath: string;
-	try {
-		pkgPath = require.resolve("node-pty/package.json");
-	} catch {
-		return;
-	}
-
-	const base = dirname(pkgPath);
-	const targets = [
-		join(base, "prebuilds", "darwin-arm64", "spawn-helper"),
-		join(base, "prebuilds", "darwin-x64", "spawn-helper"),
-	];
-
-	for (const target of targets) {
-		try {
-			const stats = statSync(target);
-			const mode = stats.mode | 0o111;
-			if ((stats.mode & 0o111) !== 0o111) {
-				chmodSync(target, mode);
-			}
-		} catch {
-			continue;
-		}
-	}
-}
 
 function sanitizeLine(line: string): string {
 	let out = line;
@@ -234,13 +159,9 @@ export class PtyTerminalSession {
 
 	// Trim raw output buffer if it exceeds max size
 	private trimRawOutputIfNeeded(): void {
-		if (this.rawOutput.length > MAX_RAW_OUTPUT_SIZE) {
-			const keepSize = Math.floor(MAX_RAW_OUTPUT_SIZE / 2);
-			const trimAmount = this.rawOutput.length - keepSize;
-			this.rawOutput = this.rawOutput.substring(trimAmount);
-			// Adjust stream position to account for trimmed content
-			this.lastStreamPosition = Math.max(0, this.lastStreamPosition - trimAmount);
-		}
+		const trimmed = trimRawOutput(this.rawOutput, this.lastStreamPosition);
+		this.rawOutput = trimmed.rawOutput;
+		this.lastStreamPosition = trimmed.lastStreamPosition;
 	}
 
 	constructor(options: PtySessionOptions, events: PtySessionEvents = {}) {
@@ -367,14 +288,16 @@ export class PtyTerminalSession {
 
 	private notifyDataListeners(data: string): void {
 		this.dataHandler?.(data);
-		for (const listener of this.additionalDataListeners) {
+		// Copy array to avoid issues if a listener unsubscribes during iteration
+		for (const listener of [...this.additionalDataListeners]) {
 			listener(data);
 		}
 	}
 
 	private notifyExitListeners(exitCode: number, signal?: number): void {
 		this.exitHandler?.(exitCode, signal);
-		for (const listener of this.additionalExitListeners) {
+		// Copy array to avoid issues if a listener unsubscribes during iteration
+		for (const listener of [...this.additionalExitListeners]) {
 			listener(exitCode, signal);
 		}
 	}
@@ -626,53 +549,7 @@ export class PtyTerminalSession {
 		totalChars: number;
 		sliceLineCount: number;
 	} {
-		let text = this.rawOutput;
-
-		// Strip ANSI by default
-		if (options.stripAnsi !== false && text) {
-			text = stripVTControlCharacters(text);
-		}
-
-		if (!text) {
-			return { slice: "", totalLines: 0, totalChars: 0, sliceLineCount: 0 };
-		}
-
-		// Normalize line endings and split
-		const normalized = text.replace(/\r\n/g, "\n");
-		const lines = normalized.split("\n");
-		// Remove trailing empty line from split
-		if (lines.length > 0 && lines[lines.length - 1] === "") {
-			lines.pop();
-		}
-
-		const totalLines = lines.length;
-		const totalChars = text.length;
-
-		// Calculate start position
-		let start: number;
-		if (typeof options.offset === "number" && Number.isFinite(options.offset)) {
-			start = Math.max(0, Math.floor(options.offset));
-		} else if (options.limit !== undefined) {
-			// No offset but limit provided - return tail (last N lines)
-			const tailCount = Math.max(0, Math.floor(options.limit));
-			start = Math.max(totalLines - tailCount, 0);
-		} else {
-			start = 0;
-		}
-
-		// Calculate end position
-		const end = typeof options.limit === "number" && Number.isFinite(options.limit)
-			? start + Math.max(0, Math.floor(options.limit))
-			: undefined;
-
-		const selectedLines = lines.slice(start, end);
-
-		return {
-			slice: selectedLines.join("\n"),
-			totalLines,
-			totalChars,
-			sliceLineCount: selectedLines.length,
-		};
+		return sliceLogOutput(this.rawOutput, options);
 	}
 
 	scrollUp(lines: number): void {

package/reattach-overlay.ts

@@ -1,9 +1,6 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
 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";
-import { getAgentDir } from "@mariozechner/pi-coding-agent";
 import { PtyTerminalSession } from "./pty-session.js";
 import { sessionManager } from "./session-manager.js";
 import type { InteractiveShellConfig } from "./config.js";
@@ -15,6 +12,7 @@ import {
 	FOOTER_LINES_COMPACT,
 	FOOTER_LINES_DIALOG,
 } from "./types.js";
+import { captureCompletionOutput, captureTransferOutput, maybeBuildHandoffPreview, maybeWriteHandoffSnapshot } from "./handoff-utils.js";
 
 export class ReattachOverlay implements Component, Focusable {
 	focused = false;
@@ -103,87 +101,20 @@ export class ReattachOverlay implements Component, Focusable {
 	}
 
 	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" | "transfer"): InteractiveShellResult["handoffPreview"] | undefined {
-		if (!this.config.handoffPreviewEnabled) return undefined;
-		const lines = this.config.handoffPreviewLines;
-		const maxChars = 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);
 	}
 
 	private maybeWriteHandoffSnapshot(when: "exit" | "detach" | "kill" | "transfer"): InteractiveShellResult["handoff"] | undefined {
-		if (!this.config.handoffSnapshotEnabled) return undefined;
-		const lines = this.config.handoffSnapshotLines;
-		const maxChars = this.config.handoffSnapshotMaxChars;
-		if (lines <= 0 || maxChars <= 0) return undefined;
-
-		const baseDir = join(getAgentDir(), "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.bgSession.command}`,
-			`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.bgSession.command });
 	}
 
 	private finishAndClose(): void {

package/runtime-coordinator.ts

@@ -0,0 +1,69 @@
+import type { HeadlessDispatchMonitor } from "./headless-monitor.js";
+
+/** Centralizes overlay, monitor, widget, and completion-suppression state for the extension runtime. */
+export class InteractiveShellCoordinator {
+	private overlayOpen = false;
+	private headlessMonitors = new Map<string, HeadlessDispatchMonitor>();
+	private bgWidgetCleanup: (() => void) | null = null;
+	private agentHandledCompletion = new Set<string>();
+
+	isOverlayOpen(): boolean {
+		return this.overlayOpen;
+	}
+
+	beginOverlay(): boolean {
+		if (this.overlayOpen) return false;
+		this.overlayOpen = true;
+		return true;
+	}
+
+	endOverlay(): void {
+		this.overlayOpen = false;
+	}
+
+	markAgentHandledCompletion(sessionId: string): void {
+		this.agentHandledCompletion.add(sessionId);
+	}
+
+	consumeAgentHandledCompletion(sessionId: string): boolean {
+		const had = this.agentHandledCompletion.has(sessionId);
+		this.agentHandledCompletion.delete(sessionId);
+		return had;
+	}
+
+	setMonitor(id: string, monitor: HeadlessDispatchMonitor): void {
+		this.headlessMonitors.set(id, monitor);
+	}
+
+	getMonitor(id: string): HeadlessDispatchMonitor | undefined {
+		return this.headlessMonitors.get(id);
+	}
+
+	deleteMonitor(id: string): void {
+		this.headlessMonitors.delete(id);
+	}
+
+	disposeMonitor(id: string): void {
+		const monitor = this.headlessMonitors.get(id);
+		if (!monitor) return;
+		monitor.dispose();
+		this.headlessMonitors.delete(id);
+	}
+
+	disposeAllMonitors(): void {
+		for (const monitor of this.headlessMonitors.values()) {
+			monitor.dispose();
+		}
+		this.headlessMonitors.clear();
+	}
+
+	replaceBackgroundWidgetCleanup(cleanup: (() => void) | null): void {
+		this.bgWidgetCleanup?.();
+		this.bgWidgetCleanup = cleanup;
+	}
+
+	clearBackgroundWidget(): void {
+		this.bgWidgetCleanup?.();
+		this.bgWidgetCleanup = null;
+	}
+}

package/scripts/install.js

@@ -101,7 +101,11 @@ function main() {
 	log("Restart pi to load the extension.");
 	log("");
 	log("Usage:");
-	log('  interactive_shell({ command: \'pi "Fix all bugs"\', mode: "hands-free" })');
+	log('  interactive_shell({ command: \'pi "Fix all bugs"\', mode: "dispatch" })');
+	log("");
+	log("Bundled example prompts live under extensions/interactive-shell/examples/prompts/");
+	log("Bundled example skills live under extensions/interactive-shell/examples/skills/");
+	log("Copy them into your prompts/skills directories if you want local slash commands or skill copies.");
 	log("");
 }
 

package/session-manager.ts

@@ -191,35 +191,45 @@ export class ShellSessionManager {
 	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, {
+		const entry: BackgroundSession = {
 			id,
 			name: name || deriveSessionName(command),
 			command,
 			reason,
 			session,
 			startedAt: options?.startedAt ?? new Date(),
-		});
+		};
 
-		session.setEventHandlers({});
+		this.storeBackgroundEntry(entry, options?.noAutoCleanup === true);
+		return id;
+	}
+
+	restore(entry: BackgroundSession, options?: { noAutoCleanup?: boolean }): void {
+		usedIds.add(entry.id);
+		this.storeBackgroundEntry(entry, options?.noAutoCleanup === true);
+	}
+
+	private storeBackgroundEntry(entry: BackgroundSession, noAutoCleanup: boolean): void {
+		this.sessions.set(entry.id, entry);
+		entry.session.setEventHandlers({});
 
-		if (!options?.noAutoCleanup) {
+		if (!noAutoCleanup) {
 			const checkExit = setInterval(() => {
-				if (session.exited) {
+				if (entry.session.exited) {
 					clearInterval(checkExit);
-					this.exitWatchers.delete(id);
+					this.exitWatchers.delete(entry.id);
 					this.notifyChange();
 					const cleanupTimer = setTimeout(() => {
-						this.cleanupTimers.delete(id);
-						this.remove(id);
+						this.cleanupTimers.delete(entry.id);
+						this.remove(entry.id);
 					}, 30000);
-					this.cleanupTimers.set(id, cleanupTimer);
+					this.cleanupTimers.set(entry.id, cleanupTimer);
 				}
 			}, 1000);
-			this.exitWatchers.set(id, checkExit);
+			this.exitWatchers.set(entry.id, checkExit);
 		}
 
 		this.notifyChange();
-		return id;
 	}
 
 	take(id: string): BackgroundSession | undefined {

package/session-query.ts

@@ -0,0 +1,170 @@
+import type { InteractiveShellConfig } from "./config.js";
+import type { OutputOptions, OutputResult } from "./session-manager.js";
+import type { InteractiveShellResult } from "./types.js";
+import type { PtyTerminalSession } from "./pty-session.js";
+
+/** Mutable query bookkeeping kept per active session. */
+export interface SessionQueryState {
+	lastQueryTime: number;
+	incrementalReadPosition: number;
+}
+
+export const DEFAULT_STATUS_OUTPUT = 5 * 1024;
+export const DEFAULT_STATUS_LINES = 20;
+export const MAX_STATUS_OUTPUT = 50 * 1024;
+export const MAX_STATUS_LINES = 200;
+
+export function createSessionQueryState(): SessionQueryState {
+	return {
+		lastQueryTime: 0,
+		incrementalReadPosition: 0,
+	};
+}
+
+export function getSessionOutput(
+	session: PtyTerminalSession,
+	config: InteractiveShellConfig,
+	state: SessionQueryState,
+	options: OutputOptions | boolean = false,
+	completionOutput?: InteractiveShellResult["completionOutput"],
+): OutputResult {
+	if (completionOutput) {
+		return buildCompletionOutputResult(completionOutput);
+	}
+
+	const opts = typeof options === "boolean" ? { skipRateLimit: options } : options;
+	const requestedLines = clampPositive(opts.lines ?? DEFAULT_STATUS_LINES, MAX_STATUS_LINES);
+	const requestedMaxChars = clampPositive(opts.maxChars ?? DEFAULT_STATUS_OUTPUT, MAX_STATUS_OUTPUT);
+	const rateLimited = maybeRateLimitQuery(config, state, opts.skipRateLimit ?? false);
+	if (rateLimited) return rateLimited;
+
+	if (opts.incremental) {
+		return getIncrementalOutput(session, state, requestedLines, requestedMaxChars);
+	}
+
+	if (opts.drain) {
+		return buildTruncatedOutput(session.getRawStream({ sinceLast: true, stripAnsi: true }), requestedMaxChars, true);
+	}
+
+	if (opts.offset !== undefined) {
+		return getOffsetOutput(session, opts.offset, requestedLines, requestedMaxChars);
+	}
+
+	const tailResult = session.getTailLines({
+		lines: requestedLines,
+		ansi: false,
+		maxChars: requestedMaxChars,
+	});
+	const output = tailResult.lines.join("\n");
+	return {
+		output,
+		truncated: tailResult.lines.length < tailResult.totalLinesInBuffer || tailResult.truncatedByChars,
+		totalBytes: output.length,
+		totalLines: tailResult.totalLinesInBuffer,
+	};
+}
+
+function maybeRateLimitQuery(
+	config: InteractiveShellConfig,
+	state: SessionQueryState,
+	skipRateLimit: boolean,
+): OutputResult | null {
+	if (skipRateLimit) return null;
+	const now = Date.now();
+	const minIntervalMs = config.minQueryIntervalSeconds * 1000;
+	const elapsed = now - state.lastQueryTime;
+	if (state.lastQueryTime > 0 && elapsed < minIntervalMs) {
+		return {
+			output: "",
+			truncated: false,
+			totalBytes: 0,
+			rateLimited: true,
+			waitSeconds: Math.ceil((minIntervalMs - elapsed) / 1000),
+		};
+	}
+	state.lastQueryTime = now;
+	return null;
+}
+
+function getIncrementalOutput(
+	session: PtyTerminalSession,
+	state: SessionQueryState,
+	requestedLines: number,
+	requestedMaxChars: number,
+): OutputResult {
+	const result = session.getLogSlice({
+		offset: state.incrementalReadPosition,
+		limit: requestedLines,
+		stripAnsi: true,
+	});
+	const output = truncateForMaxChars(result.slice, requestedMaxChars);
+	state.incrementalReadPosition += result.sliceLineCount;
+	return {
+		output: output.value,
+		truncated: output.truncated,
+		totalBytes: output.value.length,
+		totalLines: result.totalLines,
+		hasMore: state.incrementalReadPosition < result.totalLines,
+	};
+}
+
+function getOffsetOutput(
+	session: PtyTerminalSession,
+	offset: number,
+	requestedLines: number,
+	requestedMaxChars: number,
+): OutputResult {
+	const result = session.getLogSlice({
+		offset,
+		limit: requestedLines,
+		stripAnsi: true,
+	});
+	const output = truncateForMaxChars(result.slice, requestedMaxChars);
+	const hasMore = (offset + result.sliceLineCount) < result.totalLines;
+	return {
+		output: output.value,
+		truncated: output.truncated || hasMore,
+		totalBytes: output.value.length,
+		totalLines: result.totalLines,
+		hasMore,
+	};
+}
+
+function buildCompletionOutputResult(completionOutput: NonNullable<InteractiveShellResult["completionOutput"]>): OutputResult {
+	const output = completionOutput.lines.join("\n");
+	return {
+		output,
+		truncated: completionOutput.truncated,
+		totalBytes: output.length,
+		totalLines: completionOutput.totalLines,
+	};
+}
+
+function buildTruncatedOutput(output: string, requestedMaxChars: number, sliceFromEnd = false): OutputResult {
+	const truncated = output.length > requestedMaxChars;
+	let value = output;
+	if (truncated) {
+		value = sliceFromEnd
+			? output.slice(-requestedMaxChars)
+			: output.slice(0, requestedMaxChars);
+	}
+	return {
+		output: value,
+		truncated,
+		totalBytes: value.length,
+	};
+}
+
+function truncateForMaxChars(output: string, requestedMaxChars: number): { value: string; truncated: boolean } {
+	if (output.length <= requestedMaxChars) {
+		return { value: output, truncated: false };
+	}
+	return {
+		value: output.slice(0, requestedMaxChars),
+		truncated: true,
+	};
+}
+
+function clampPositive(value: number, max: number): number {
+	return Math.max(1, Math.min(max, value));
+}

package/spawn-helper.ts

@@ -0,0 +1,37 @@
+import { chmodSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+const require = createRequire(import.meta.url);
+let spawnHelperChecked = false;
+
+export function ensureSpawnHelperExec(): void {
+	if (spawnHelperChecked) return;
+	spawnHelperChecked = true;
+	if (process.platform !== "darwin") return;
+
+	let pkgPath: string;
+	try {
+		pkgPath = require.resolve("node-pty/package.json");
+	} catch {
+		return;
+	}
+
+	const base = dirname(pkgPath);
+	const targets = [
+		join(base, "prebuilds", "darwin-arm64", "spawn-helper"),
+		join(base, "prebuilds", "darwin-x64", "spawn-helper"),
+	];
+
+	for (const target of targets) {
+		try {
+			const stats = statSync(target);
+			const mode = stats.mode | 0o111;
+			if ((stats.mode & 0o111) !== 0o111) {
+				chmodSync(target, mode);
+			}
+		} catch {
+			continue;
+		}
+	}
+}

package/types.ts

@@ -48,11 +48,14 @@ export interface HandsFreeUpdate {
 	budgetExhausted?: boolean;
 }
 
+/** Options for starting or reattaching an interactive shell session. */
 export interface InteractiveShellOptions {
 	command: string;
 	cwd?: string;
 	name?: string;
 	reason?: string;
+	/** Original session start time in ms since epoch, preserved across background/reattach transitions. */
+	startedAt?: number;
 	handoffPreviewEnabled?: boolean;
 	handoffPreviewLines?: number;
 	handoffPreviewMaxChars?: number;