pi-interactive-shell 0.8.2 → 0.10.0

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/tool-schema.ts

@@ -14,6 +14,10 @@ MODES:
 - 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)
 
+RECOMMENDED DEFAULT FOR DELEGATED TASKS:
+- For fire-and-forget delegations and QA-style checks, prefer mode="dispatch".
+- Dispatch is the safest choice when the agent should continue immediately and be notified automatically on completion.
+
 The user will see the process in an overlay. They can:
 - Watch output in real-time
 - Scroll through output (Shift+Up/Down)
@@ -234,10 +238,10 @@ export const toolParameters = Type.Object({
 				Type.Number({ description: "Max interval between updates in ms (default: 60000)" }),
 			),
 			quietThreshold: Type.Optional(
-				Type.Number({ description: "Silence duration before emitting update in on-quiet mode (default: 5000ms)" }),
+				Type.Number({ description: "Silence duration before emitting update in on-quiet mode (default: 8000ms)" }),
 			),
 			gracePeriod: Type.Optional(
-				Type.Number({ description: "Startup grace period before autoExitOnQuiet can kill the session (default: 30000ms)" }),
+				Type.Number({ description: "Startup grace period before autoExitOnQuiet can kill the session (default: 15000ms)" }),
 			),
 			updateMaxChars: Type.Optional(
 				Type.Number({ description: "Max chars per update (default: 1500)" }),

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;
@@ -73,6 +76,9 @@ export interface InteractiveShellOptions {
 	autoExitGracePeriod?: number;
 	// Auto-kill timeout
 	timeout?: number;
+	// When true, unregister active session on completion (blocking tool call path).
+	// When false/undefined, keep registered so agent can query result later.
+	streamingMode?: boolean;
 	// Existing PTY session (for attach flow -- skip creating a new PTY)
 	existingSession?: import("./pty-session.js").PtyTerminalSession;
 }