pi-interactive-shell 0.8.2 → 0.10.0

package/pty-log.ts

@@ -0,0 +1,59 @@
+import { stripVTControlCharacters } from "node:util";
+
+export const MAX_RAW_OUTPUT_SIZE = 1024 * 1024;
+
+export function trimRawOutput(rawOutput: string, lastStreamPosition: number): { rawOutput: string; lastStreamPosition: number } {
+	if (rawOutput.length <= MAX_RAW_OUTPUT_SIZE) {
+		return { rawOutput, lastStreamPosition };
+	}
+	const keepSize = Math.floor(MAX_RAW_OUTPUT_SIZE / 2);
+	const trimAmount = rawOutput.length - keepSize;
+	return {
+		rawOutput: rawOutput.substring(trimAmount),
+		lastStreamPosition: Math.max(0, lastStreamPosition - trimAmount),
+	};
+}
+
+export function sliceLogOutput(text: string, options: { offset?: number; limit?: number; stripAnsi?: boolean } = {}): {
+	slice: string;
+	totalLines: number;
+	totalChars: number;
+	sliceLineCount: number;
+} {
+	let source = text;
+	if (options.stripAnsi !== false && source) {
+		source = stripVTControlCharacters(source);
+	}
+	if (!source) {
+		return { slice: "", totalLines: 0, totalChars: 0, sliceLineCount: 0 };
+	}
+
+	const normalized = source.replace(/\r\n/g, "\n");
+	const lines = normalized.split("\n");
+	if (lines.length > 0 && lines[lines.length - 1] === "") {
+		lines.pop();
+	}
+
+	const totalLines = lines.length;
+	const totalChars = source.length;
+	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) {
+		const tailCount = Math.max(0, Math.floor(options.limit));
+		start = Math.max(totalLines - tailCount, 0);
+	} else {
+		start = 0;
+	}
+
+	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,
+	};
+}

package/pty-protocol.ts

@@ -0,0 +1,33 @@
+// DSR (Device Status Report) - cursor position query: ESC[6n or ESC[?6n
+const DSR_PATTERN = /\x1b\[\??6n/g;
+
+/** Result of splitting PTY output around device-status-report cursor queries. */
+export interface DsrSplit {
+	segments: Array<{ text: string; dsrAfter: boolean }>;
+	hasDsr: boolean;
+}
+
+export function splitAroundDsr(input: string): DsrSplit {
+	const segments: Array<{ text: string; dsrAfter: boolean }> = [];
+	let lastIndex = 0;
+	let hasDsr = false;
+	const regex = new RegExp(DSR_PATTERN.source, "g");
+	let match: RegExpExecArray | null;
+	while ((match = regex.exec(input)) !== null) {
+		hasDsr = true;
+		if (match.index > lastIndex) {
+			segments.push({ text: input.slice(lastIndex, match.index), dsrAfter: true });
+		} else {
+			segments.push({ text: "", dsrAfter: true });
+		}
+		lastIndex = match.index + match[0].length;
+	}
+	if (lastIndex < input.length) {
+		segments.push({ text: input.slice(lastIndex), dsrAfter: false });
+	}
+	return { segments, hasDsr };
+}
+
+export function buildCursorPositionResponse(row = 1, col = 1): string {
+	return `\x1b[${row};${col}R`;
+}

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,6 +1,3 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-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";
@@ -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(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.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 {
@@ -358,6 +289,7 @@ export class ReattachOverlay 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);

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

@@ -9,8 +9,19 @@ import { fileURLToPath } from "node:url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "..");
 
-const EXTENSION_DIR = join(homedir(), ".pi", "agent", "extensions", "interactive-shell");
-const SKILL_DIR = join(homedir(), ".pi", "agent", "skills", "interactive-shell");
+function getAgentDir() {
+	const envDir = process.env.PI_CODING_AGENT_DIR;
+	if (envDir) {
+		if (envDir === "~") return homedir();
+		if (envDir.startsWith("~/")) return homedir() + envDir.slice(1);
+		return envDir;
+	}
+	return join(homedir(), ".pi", "agent");
+}
+
+const agentDir = getAgentDir();
+const EXTENSION_DIR = join(agentDir, "extensions", "interactive-shell");
+const SKILL_DIR = join(agentDir, "skills", "interactive-shell");
 
 function log(msg) {
 	console.log(`[pi-interactive-shell] ${msg}`);
@@ -90,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 {