pi-interactive-shell 0.9.0 → 0.10.1

package/notification-utils.ts

@@ -0,0 +1,134 @@
+import type { InteractiveShellResult, HandsFreeUpdate } from "./types.js";
+import type { HeadlessCompletionInfo } from "./headless-monitor.js";
+import { formatDurationMs } from "./types.js";
+
+const BRIEF_TAIL_LINES = 5;
+
+export function buildDispatchNotification(sessionId: string, info: HeadlessCompletionInfo, duration: string): string {
+	const parts = [buildDispatchStatusLine(sessionId, info, duration)];
+	if (info.completionOutput && info.completionOutput.totalLines > 0) {
+		parts.push(` ${info.completionOutput.totalLines} lines of output.`);
+	}
+	appendTailBlock(parts, info.completionOutput?.lines, BRIEF_TAIL_LINES);
+	parts.push(`\n\nAttach to review full output: interactive_shell({ attach: "${sessionId}" })`);
+	return parts.join("");
+}
+
+export function buildResultNotification(sessionId: string, result: InteractiveShellResult): string {
+	const parts = [buildResultStatusLine(sessionId, result)];
+	if (result.completionOutput && result.completionOutput.lines.length > 0) {
+		const truncNote = result.completionOutput.truncated
+			? ` (truncated from ${result.completionOutput.totalLines} total lines)`
+			: "";
+		parts.push(`\nOutput (${result.completionOutput.lines.length} lines${truncNote}):\n\n${result.completionOutput.lines.join("\n")}`);
+	}
+	return parts.join("");
+}
+
+export function buildHandsFreeUpdateMessage(update: HandsFreeUpdate): { content: string; details: HandsFreeUpdate } | null {
+	if (update.status === "running") return null;
+
+	const tail = update.tail.length > 0 ? `\n\n${update.tail.join("\n")}` : "";
+	let statusLine: string;
+	switch (update.status) {
+		case "exited":
+			statusLine = `Session ${update.sessionId} exited (${formatDurationMs(update.runtime)})`;
+			break;
+		case "killed":
+			statusLine = `Session ${update.sessionId} killed (${formatDurationMs(update.runtime)})`;
+			break;
+		case "user-takeover":
+			statusLine = `Session ${update.sessionId}: user took over (${formatDurationMs(update.runtime)})`;
+			break;
+		default:
+			statusLine = `Session ${update.sessionId} update (${formatDurationMs(update.runtime)})`;
+	}
+	return { content: statusLine + tail, details: update };
+}
+
+export function summarizeInteractiveResult(command: string, result: InteractiveShellResult, timeout?: number, reason?: string): string {
+	let summary = buildInteractiveSummary(result, timeout);
+
+	if (result.userTookOver) {
+		summary += "\n\nNote: User took over control during hands-free mode.";
+	}
+
+	if (!result.transferred && result.handoffPreview?.type === "tail" && result.handoffPreview.lines.length > 0) {
+		summary += `\n\nOverlay tail (${result.handoffPreview.when}, last ${result.handoffPreview.lines.length} lines):\n${result.handoffPreview.lines.join("\n")}`;
+	}
+
+	const warning = buildIdlePromptWarning(command, reason);
+	if (warning) {
+		summary += `\n\n${warning}`;
+	}
+
+	return summary;
+}
+
+export function buildIdlePromptWarning(command: string, reason: string | undefined): string | null {
+	if (!reason) return null;
+
+	const tasky = /\b(scan|check|review|summariz|analyz|inspect|audit|find|fix|refactor|debug|investigat|explore|enumerat|list)\b/i;
+	if (!tasky.test(reason)) return null;
+
+	const trimmed = command.trim();
+	const binaries = ["pi", "claude", "codex", "gemini", "cursor-agent"] as const;
+	const bin = binaries.find((candidate) => trimmed === candidate || trimmed.startsWith(`${candidate} `));
+	if (!bin) return null;
+
+	const rest = trimmed === bin ? "" : trimmed.slice(bin.length).trim();
+	const hasQuotedPrompt = /["']/.test(rest);
+	const hasKnownPromptFlag =
+		/\b(-p|--print|--prompt|--prompt-interactive|-i|exec)\b/.test(rest) ||
+		(bin === "pi" && /\b-p\b/.test(rest)) ||
+		(bin === "codex" && /\bexec\b/.test(rest));
+
+	if (hasQuotedPrompt || hasKnownPromptFlag) return null;
+	if (!looksLikeIdleCommand(rest)) return null;
+
+	const examplePrompt = reason.replace(/\s+/g, " ").trim();
+	const clipped = examplePrompt.length > 120 ? `${examplePrompt.slice(0, 117)}...` : examplePrompt;
+	return `Note: \`reason\` is UI-only. This command likely started the agent idle. If you intended an initial prompt, embed it in \`command\`, e.g. \`${bin} "${clipped}"\`.`;
+}
+
+function buildDispatchStatusLine(sessionId: string, info: HeadlessCompletionInfo, duration: string): string {
+	if (info.timedOut) return `Session ${sessionId} timed out (${duration}).`;
+	if (info.cancelled) return `Session ${sessionId} completed (${duration}).`;
+	if (info.exitCode === 0) return `Session ${sessionId} completed successfully (${duration}).`;
+	return `Session ${sessionId} exited with code ${info.exitCode} (${duration}).`;
+}
+
+function buildResultStatusLine(sessionId: string, result: InteractiveShellResult): string {
+	if (result.timedOut) return `Session ${sessionId} timed out.`;
+	if (result.cancelled) return `Session ${sessionId} was killed.`;
+	if (result.exitCode === 0) return `Session ${sessionId} completed successfully.`;
+	return `Session ${sessionId} exited with code ${result.exitCode}.`;
+}
+
+function buildInteractiveSummary(result: InteractiveShellResult, timeout?: number): string {
+	if (result.transferred) {
+		const truncatedNote = result.transferred.truncated ? ` (truncated from ${result.transferred.totalLines} total lines)` : "";
+		return `Session output transferred (${result.transferred.lines.length} lines${truncatedNote}):\n\n${result.transferred.lines.join("\n")}`;
+	}
+	if (result.backgrounded) {
+		return `Session running in background (id: ${result.backgroundId}). User can reattach with /attach ${result.backgroundId}`;
+	}
+	if (result.cancelled) return "User killed the interactive session";
+	if (result.timedOut) return `Session killed after timeout (${timeout ?? "?"}ms)`;
+	const status = result.exitCode === 0 ? "successfully" : `with code ${result.exitCode}`;
+	return `Session ended ${status}`;
+}
+
+function appendTailBlock(parts: string[], lines: string[] | undefined, tailLines: number): void {
+	if (!lines || lines.length === 0) return;
+	let end = lines.length;
+	while (end > 0 && lines[end - 1].trim() === "") end--;
+	const tail = lines.slice(Math.max(0, end - tailLines), end);
+	if (tail.length > 0) {
+		parts.push(`\n\n${tail.join("\n")}`);
+	}
+}
+
+function looksLikeIdleCommand(rest: string): boolean {
+	return rest.length === 0 || /^(-{1,2}[A-Za-z0-9][A-Za-z0-9-]*(?:=[^\s]+)?\s*)+$/.test(rest);
+}

package/overlay-component.ts

@@ -1,10 +1,7 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
 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, generateSessionId } from "./session-manager.js";
 import type { InteractiveShellConfig } from "./config.js";
@@ -19,6 +16,8 @@ import {
 	FOOTER_LINES_DIALOG,
 	formatDuration,
 } from "./types.js";
+import { captureCompletionOutput, captureTransferOutput, maybeBuildHandoffPreview, maybeWriteHandoffSnapshot } from "./handoff-utils.js";
+import { createSessionQueryState, getSessionOutput } from "./session-query.js";
 
 export class InteractiveShellOverlay implements Component, Focusable {
 	focused = false;
@@ -40,7 +39,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 	private userTookOver = false;
 	private handsFreeInterval: ReturnType<typeof setInterval> | null = null;
 	private handsFreeInitialTimeout: ReturnType<typeof setTimeout> | null = null;
-	private startTime = Date.now();
+	private startTime: number;
 	private sessionId: string | null = null;
 	private sessionUnregistered = false;
 	// Timeout
@@ -57,10 +56,7 @@ 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;
-	// Incremental read position (for incremental: true queries)
-	private incrementalReadPosition = 0;
+	private queryState = createSessionQueryState();
 	// Completion callbacks for waiters
 	private completeCallbacks: Array<() => void> = [];
 	// Simple render throttle to reduce flicker
@@ -78,6 +74,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.options = options;
 		this.config = config;
 		this.done = done;
+		this.startTime = options.startedAt ?? Date.now();
 
 		const overlayWidth = Math.floor((tui.terminal.columns * this.config.overlayWidthPercent) / 100);
 		const overlayHeight = Math.floor((tui.terminal.rows * this.config.overlayHeightPercent) / 100);
@@ -209,136 +206,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 
 	// Public methods for non-blocking mode (agent queries)
 
-	// Default output limits per status query
-	private static readonly DEFAULT_STATUS_OUTPUT = 5 * 1024; // 5KB
-	private static readonly DEFAULT_STATUS_LINES = 20;
-	private static readonly MAX_STATUS_OUTPUT = 50 * 1024; // 50KB max
-	private static readonly MAX_STATUS_LINES = 200; // 200 lines max
-
 	/** Get rendered terminal output (last N lines, truncated if too large) */
 	getOutputSinceLastCheck(options: { skipRateLimit?: boolean; lines?: number; maxChars?: number; offset?: number; drain?: boolean; incremental?: boolean } | boolean = false): { output: string; truncated: boolean; totalBytes: number; totalLines?: number; hasMore?: boolean; rateLimited?: boolean; waitSeconds?: number } {
-		if (this.finished) {
-			if (this.completionResult?.completionOutput) {
-				const lines = this.completionResult.completionOutput.lines;
-				const output = lines.join("\n");
-				return {
-					output,
-					truncated: this.completionResult.completionOutput.truncated,
-					totalBytes: output.length,
-					totalLines: this.completionResult.completionOutput.totalLines,
-				};
-			}
-			return { output: "", truncated: false, totalBytes: 0 };
-		}
-
-		// Handle legacy boolean parameter
-		const opts = typeof options === "boolean" ? { skipRateLimit: options } : options;
-		const skipRateLimit = opts.skipRateLimit ?? false;
-		// Clamp lines and maxChars to valid ranges (1 to MAX)
-		const requestedLines = Math.max(1, Math.min(
-			opts.lines ?? InteractiveShellOverlay.DEFAULT_STATUS_LINES,
-			InteractiveShellOverlay.MAX_STATUS_LINES
-		));
-		const requestedMaxChars = Math.max(1, Math.min(
-			opts.maxChars ?? InteractiveShellOverlay.DEFAULT_STATUS_OUTPUT,
-			InteractiveShellOverlay.MAX_STATUS_OUTPUT
-		));
-
-		// 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;
-		}
-
-		// Incremental mode: return next N lines agent hasn't seen yet
-		// Server tracks position - agent just keeps calling with incremental: true
-		if (opts.incremental) {
-			const result = this.session.getLogSlice({
-				offset: this.incrementalReadPosition,
-				limit: requestedLines,
-				stripAnsi: true,
-			});
-			// Use sliceLineCount directly - handles empty lines correctly
-			// (counting newlines in slice fails for empty lines like "")
-			const linesFromSlice = result.sliceLineCount;
-			// Apply maxChars limit (may truncate mid-line, but we still advance past it)
-			const truncatedByChars = result.slice.length > requestedMaxChars;
-			const output = truncatedByChars ? result.slice.slice(0, requestedMaxChars) : result.slice;
-			// Update position for next incremental read
-			this.incrementalReadPosition += linesFromSlice;
-			const hasMore = this.incrementalReadPosition < result.totalLines;
-			return {
-				output,
-				truncated: truncatedByChars,
-				totalBytes: output.length,
-				totalLines: result.totalLines,
-				hasMore,
-			};
-		}
-
-		// Drain mode: return only NEW output since last query (raw stream, not lines)
-		// This is more token-efficient than re-reading the tail each time
-		if (opts.drain) {
-			const newOutput = this.session.getRawStream({ sinceLast: true, stripAnsi: true });
-			// Truncate if exceeds maxChars
-			const truncated = newOutput.length > requestedMaxChars;
-			const output = truncated ? newOutput.slice(-requestedMaxChars) : newOutput;
-			return {
-				output,
-				truncated,
-				totalBytes: output.length,
-			};
-		}
-
-		// Offset mode: use getLogSlice for pagination through full output
-		if (opts.offset !== undefined) {
-			const result = this.session.getLogSlice({
-				offset: opts.offset,
-				limit: requestedLines,
-				stripAnsi: true,
-			});
-			// Apply maxChars limit
-			const truncatedByChars = result.slice.length > requestedMaxChars;
-			const output = truncatedByChars ? result.slice.slice(0, requestedMaxChars) : result.slice;
-			// Calculate hasMore based on whether there are more lines after this slice
-			const hasMore = (opts.offset + result.sliceLineCount) < result.totalLines;
-			return {
-				output,
-				truncated: truncatedByChars || result.sliceLineCount >= requestedLines,
-				totalBytes: output.length,
-				totalLines: result.totalLines,
-				hasMore,
-			};
-		}
-
-		// Default: Use rendered terminal output (tail)
-		// This gives clean, readable content without TUI animation garbage
-		const tailResult = this.session.getTailLines({
-			lines: requestedLines,
-			ansi: false,
-			maxChars: requestedMaxChars,
-		});
-
-		const output = tailResult.lines.join("\n");
-		const totalBytes = output.length;
-		const truncated = tailResult.lines.length >= requestedLines || tailResult.truncatedByChars;
-
-		return { output, truncated, totalBytes, totalLines: tailResult.totalLinesInBuffer };
+		return getSessionOutput(this.session, this.config, this.queryState, options, this.completionResult?.completionOutput);
 	}
 
 	/** Get current session status */
@@ -662,92 +532,23 @@ export class InteractiveShellOverlay implements Component, Focusable {
 
 	/** Capture output for dispatch completion notifications */
 	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" | "timeout" | "transfer"): InteractiveShellResult["handoffPreview"] | undefined {
-		const enabled = this.options.handoffPreviewEnabled ?? this.config.handoffPreviewEnabled;
-		if (!enabled) return undefined;
-
-		const lines = this.options.handoffPreviewLines ?? this.config.handoffPreviewLines;
-		const maxChars = this.options.handoffPreviewMaxChars ?? 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, this.options);
 	}
 
 	private maybeWriteHandoffSnapshot(when: "exit" | "detach" | "kill" | "timeout" | "transfer"): InteractiveShellResult["handoff"] | undefined {
-		const enabled = this.options.handoffSnapshotEnabled ?? this.config.handoffSnapshotEnabled;
-		if (!enabled) return undefined;
-
-		const lines = this.options.handoffSnapshotLines ?? this.config.handoffSnapshotLines;
-		const maxChars = this.options.handoffSnapshotMaxChars ?? 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.options.command}`,
-			`cwd: ${this.options.cwd ?? ""}`,
-			`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.options.command,
+			cwd: this.options.cwd,
+		}, this.options);
 	}
 
 	private finishWithExit(): void {
@@ -798,7 +599,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		const handoffPreview = this.maybeBuildHandoffPreview("detach");
 		const handoff = this.maybeWriteHandoffSnapshot("detach");
 		const addOptions = this.sessionId
-			? { id: this.sessionId, noAutoCleanup: this.options.mode === "dispatch" }
+			? { id: this.sessionId, noAutoCleanup: this.options.mode === "dispatch", startedAt: new Date(this.startTime) }
 			: undefined;
 		const id = sessionManager.add(this.options.command, this.session, this.options.name, this.options.reason, addOptions);
 		const result: InteractiveShellResult = {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-interactive-shell",
-  "version": "0.9.0",
-  "description": "Run AI coding agents as foreground subagents in pi TUI overlays with hands-free monitoring",
+  "version": "0.10.1",
+  "description": "Run AI coding agents in pi TUI overlays with interactive, hands-free, and dispatch supervision",
   "type": "module",
   "bin": {
     "pi-interactive-shell": "./scripts/install.js"
@@ -17,6 +17,14 @@
     "tool-schema.ts",
     "headless-monitor.ts",
     "types.ts",
+    "background-widget.ts",
+    "handoff-utils.ts",
+    "notification-utils.ts",
+    "pty-log.ts",
+    "pty-protocol.ts",
+    "runtime-coordinator.ts",
+    "session-query.ts",
+    "spawn-helper.ts",
     "scripts/",
     "examples/",
     "banner.png",
@@ -28,15 +36,24 @@
     "extensions": [
       "./index.ts"
     ],
+    "skills": [
+      "./SKILL.md",
+      "./examples/skills"
+    ],
+    "prompts": [
+      "./examples/prompts"
+    ],
     "video": "https://github.com/nicobailon/pi-interactive-shell/raw/refs/heads/main/pi-interactive-shell-extension.mp4"
   },
   "dependencies": {
-    "node-pty": "^1.1.0",
+    "@sinclair/typebox": "^0.34.40",
+    "@xterm/addon-serialize": "^0.13.0",
     "@xterm/headless": "^5.5.0",
-    "@xterm/addon-serialize": "^0.13.0"
+    "node-pty": "^1.1.0"
   },
   "scripts": {
-    "postinstall": "node ./scripts/fix-spawn-helper.cjs"
+    "postinstall": "node ./scripts/fix-spawn-helper.cjs",
+    "test": "vitest run"
   },
   "keywords": [
     "pi-package",
@@ -61,5 +78,8 @@
   "bugs": {
     "url": "https://github.com/nicobailon/pi-interactive-shell/issues"
   },
-  "homepage": "https://github.com/nicobailon/pi-interactive-shell#readme"
+  "homepage": "https://github.com/nicobailon/pi-interactive-shell#readme",
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  }
 }

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`;
+}