pi-interactive-shell 0.4.5 → 0.4.6

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to the `pi-interactive-shell` extension will be documented in this file.
 
+## [0.4.6] - 2026-01-18
+
+### Added
+- **Offset/limit pagination** - New `outputOffset` parameter for reading specific ranges of output:
+  - `outputOffset: 0, outputLines: 50` reads lines 0-49
+  - `outputOffset: 50, outputLines: 50` reads lines 50-99
+  - Returns `totalLines` in response for pagination
+- **Drain mode for incremental output** - New `drain: true` parameter returns only NEW output since last query:
+  - More token-efficient than re-reading the tail each time
+  - Ideal for repeated polling of long-running sessions
+- **Token Efficiency section in README** - Documents advantages over tmux workflow:
+  - Incremental aggregation vs full capture-pane
+  - Tail by default (20 lines, not full history)
+  - ANSI stripping before sending to agent
+  - Drain mode for only-new-output
+
+### Changed
+- **getLogSlice() method in pty-session** - New low-level method for offset/limit pagination through raw output buffer
+
 ## [0.4.3] - 2026-01-18
 
 ### Added

package/README.md

@@ -149,6 +149,38 @@ interactive_shell({ sessionId: "calm-reef", outputMaxChars: 30000 })
 | Shift+Up/Down | Scroll history |
 | Any key (hands-free) | Take over control |
 
+## Token Efficiency
+
+Unlike the standard tmux workflow where you `capture-pane` the entire terminal on every poll, Interactive Shell minimizes token waste:
+
+**Incremental Aggregation** - Output is accumulated as it arrives, not re-captured on each query.
+
+**Tail by Default** - Status queries return only the last 20 lines (configurable), not the full history.
+
+**ANSI Stripping** - All escape codes are stripped before sending output to the agent. Clean text only.
+
+**Drain Mode** - Use `drain: true` to get only NEW output since last query. No re-reading old content.
+
+```typescript
+// First query: get recent output
+interactive_shell({ sessionId: "calm-reef" })
+// → returns last 20 lines
+
+// Subsequent queries: get only new output (incremental)
+interactive_shell({ sessionId: "calm-reef", drain: true })
+// → returns only output since last query
+```
+
+**Offset/Limit Pagination** - Read specific ranges of the full output log.
+
+```typescript
+// Read lines 0-49
+interactive_shell({ sessionId: "calm-reef", outputOffset: 0, outputLines: 50 })
+
+// Read lines 50-99
+interactive_shell({ sessionId: "calm-reef", outputOffset: 50, outputLines: 50 })
+```
+
 ## How It Works
 
 ```

package/index.ts

@@ -315,6 +315,8 @@ QUERYING SESSION STATUS:
 - interactive_shell({ sessionId: "calm-reef" }) - get status + rendered terminal output (default: 20 lines, 5KB)
 - interactive_shell({ sessionId: "calm-reef", outputLines: 50 }) - get more lines (max: 200)
 - interactive_shell({ sessionId: "calm-reef", outputMaxChars: 20000 }) - get more content (max: 50KB)
+- interactive_shell({ sessionId: "calm-reef", outputOffset: 0, outputLines: 50 }) - pagination (lines 0-49)
+- interactive_shell({ sessionId: "calm-reef", drain: true }) - only NEW output since last query (token-efficient)
 - interactive_shell({ sessionId: "calm-reef", kill: true }) - end session
 - interactive_shell({ sessionId: "calm-reef", input: "..." }) - send input
 
@@ -374,6 +376,16 @@ Examples:
 					description: "Max chars to return when querying (default: 5KB, max: 50KB)",
 				}),
 			),
+			outputOffset: Type.Optional(
+				Type.Number({
+					description: "Line offset for pagination (0-indexed). Use with outputLines to read specific ranges.",
+				}),
+			),
+			drain: Type.Optional(
+				Type.Boolean({
+					description: "If true, return only NEW output since last query (incremental). More token-efficient for repeated polling.",
+				}),
+			),
 			settings: Type.Optional(
 				Type.Object({
 					updateInterval: Type.Optional(
@@ -488,6 +500,8 @@ Examples:
 				kill,
 				outputLines,
 				outputMaxChars,
+				outputOffset,
+				drain,
 				settings,
 				input,
 				cwd,
@@ -504,6 +518,8 @@ Examples:
 				kill?: boolean;
 				outputLines?: number;
 				outputMaxChars?: number;
+				outputOffset?: number;
+				drain?: boolean;
 				settings?: { updateInterval?: number; quietThreshold?: number };
 				input?: string | { text?: string; keys?: string[]; hex?: string[]; paste?: string };
 				cwd?: string;
@@ -536,7 +552,7 @@ Examples:
 
 				// Kill session if requested
 				if (kill) {
-					const { output, truncated, totalBytes } = session.getOutput({ skipRateLimit: true, lines: outputLines, maxChars: outputMaxChars });
+					const { output, truncated, totalBytes } = session.getOutput({ skipRateLimit: true, lines: outputLines, maxChars: outputMaxChars, offset: outputOffset, drain });
 					const status = session.getStatus();
 					const runtime = session.getRuntime();
 					session.kill();
@@ -619,7 +635,7 @@ Examples:
 					// If session completed, always allow query (no rate limiting)
 					// Rate limiting only applies to "checking in" on running sessions
 					if (result) {
-						const { output, truncated, totalBytes } = session.getOutput({ skipRateLimit: true, lines: outputLines, maxChars: outputMaxChars });
+						const { output, truncated, totalBytes } = session.getOutput({ skipRateLimit: true, lines: outputLines, maxChars: outputMaxChars, offset: outputOffset, drain });
 						const truncatedNote = truncated ? ` (${totalBytes} bytes total, truncated)` : "";
 						const hasOutput = output.length > 0;
 
@@ -646,7 +662,7 @@ Examples:
 					}
 
 					// Session still running - check rate limiting
-					const outputResult = session.getOutput({ lines: outputLines, maxChars: outputMaxChars });
+					const outputResult = session.getOutput({ lines: outputLines, maxChars: outputMaxChars, offset: outputOffset, drain });
 
 					// If rate limited, wait until allowed then return fresh result
 					// Use Promise.race to detect if session completes during wait
@@ -669,7 +685,7 @@ Examples:
 								};
 							}
 							const earlyResult = earlySession.getResult();
-							const { output, truncated, totalBytes } = earlySession.getOutput({ skipRateLimit: true, lines: outputLines, maxChars: outputMaxChars });
+							const { output, truncated, totalBytes } = earlySession.getOutput({ skipRateLimit: true, lines: outputLines, maxChars: outputMaxChars, offset: outputOffset, drain });
 							const earlyStatus = earlySession.getStatus();
 							const earlyRuntime = earlySession.getRuntime();
 							const truncatedNote = truncated ? ` (${totalBytes} bytes total, truncated)` : "";
@@ -718,7 +734,7 @@ Examples:
 							};
 						}
 						// Get fresh output after waiting
-						const freshOutput = session.getOutput({ lines: outputLines, maxChars: outputMaxChars });
+						const freshOutput = session.getOutput({ lines: outputLines, maxChars: outputMaxChars, offset: outputOffset, drain });
 						const truncatedNote = freshOutput.truncated ? ` (${freshOutput.totalBytes} bytes total, truncated)` : "";
 						const hasOutput = freshOutput.output.length > 0;
 						const freshStatus = session.getStatus();

package/overlay-component.ts

@@ -256,7 +256,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 	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 } | boolean = false): { output: string; truncated: boolean; totalBytes: number; rateLimited?: boolean; waitSeconds?: number } {
+	getOutputSinceLastCheck(options: { skipRateLimit?: boolean; lines?: number; maxChars?: number; offset?: number; drain?: boolean } | boolean = false): { output: string; truncated: boolean; totalBytes: number; totalLines?: number; rateLimited?: boolean; waitSeconds?: number } {
 		// Handle legacy boolean parameter
 		const opts = typeof options === "boolean" ? { skipRateLimit: options } : options;
 		const skipRateLimit = opts.skipRateLimit ?? false;
@@ -291,7 +291,40 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			this.lastQueryTime = now;
 		}
 
-		// Use rendered terminal output instead of raw stream
+		// Drain mode: return only NEW output since last query (incremental)
+		// 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;
+			const lineCount = output.split("\n").length;
+			return {
+				output,
+				truncated: truncatedByChars || lineCount >= requestedLines,
+				totalBytes: output.length,
+				totalLines: result.totalLines,
+			};
+		}
+
+		// Default: Use rendered terminal output (tail)
 		// This gives clean, readable content without TUI animation garbage
 		const lines = this.session.getTailLines({
 			lines: requestedLines,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-interactive-shell",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Run AI coding agents as foreground subagents in pi TUI overlays with hands-free monitoring",
   "type": "module",
   "bin": {

package/pty-session.ts

@@ -567,6 +567,64 @@ export class PtyTerminalSession {
 		return output;
 	}
 
+	/**
+	 * Get a slice of log output with offset/limit pagination.
+	 * Similar to Clawdbot's sliceLogLines - enables reading specific ranges of output.
+	 * @param options.offset - Line number to start from (0-indexed). If omitted with limit, returns tail.
+	 * @param options.limit - Max number of lines to return
+	 * @param options.stripAnsi - If true, strip ANSI escape codes (default: true)
+	 */
+	getLogSlice(options: { offset?: number; limit?: number; stripAnsi?: boolean } = {}): {
+		slice: string;
+		totalLines: number;
+		totalChars: 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 };
+		}
+
+		// 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;
+
+		return {
+			slice: lines.slice(start, end).join("\n"),
+			totalLines,
+			totalChars,
+		};
+	}
+
 	scrollUp(lines: number): void {
 		const buffer = this.xterm.buffer.active;
 		const maxScroll = Math.max(0, buffer.length - this.xterm.rows);

package/session-manager.ts

@@ -33,6 +33,8 @@ export interface OutputOptions {
 	skipRateLimit?: boolean;
 	lines?: number; // Override default 20 lines
 	maxChars?: number; // Override default 5KB
+	offset?: number; // Line offset for pagination (0-indexed)
+	drain?: boolean; // If true, return only NEW output since last query (incremental)
 }
 
 export interface ActiveSession {