pi-interactive-shell 0.4.7 → 0.4.8

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to the `pi-interactive-shell` extension will be documented in this file.
 
+## [0.4.8] - 2026-01-19
+
+### Changed
+- **node-pty ^1.1.0** - Updated minimum version to 1.1.0 which includes prebuilt binaries for macOS (arm64, x64) and Windows (x64, arm64). No more Xcode or Visual Studio required for installation on these platforms. Linux still requires build tools (`build-essential`, `python3`).
+
+## [0.4.7] - 2026-01-18
+
+### Added
+- **Incremental mode** - New `incremental: true` parameter for server-tracked pagination. Agent calls repeatedly and server tracks position automatically. Returns `hasMore` to indicate when more output is available.
+- **hasMore in offset mode** - Offset pagination now returns `hasMore` field so agents can know when they've finished reading all output.
+
+### Fixed
+- **Session ID leak on user takeover** - In streaming mode, session ID was unregistered but never released when user took over. Now properly releases ID since agent was notified and won't query.
+- **Session ID leak in dispose()** - When overlay was disposed without going through finishWith* methods (error cases), session ID was never released. Now releases ID in all cleanup paths.
+
+### Changed
+- **autoExitOnQuiet now defaults to false** - Sessions stay alive for multi-turn interaction by default. Enable with `handsFree: { autoExitOnQuiet: true }` for fire-and-forget single-task delegations.
+- **Config documentation** - Fixed incorrect config path in README. Config files are `~/.pi/agent/interactive-shell.json` (global) and `.pi/interactive-shell.json` (project), not under `settings.json`. Added full settings table with all options documented.
+- **Detach key** - Changed from double-Escape to Ctrl+Q for more reliable detection.
+
 ## [0.4.6] - 2026-01-18
 
 ### Added

package/README.md

@@ -1,31 +1,22 @@
 # Pi Interactive Shell
 
-An extension for [Pi coding agent](https://github.com/badlogic/pi-mono/) that lets Pi run any interactive CLI in a TUI overlay - including other AI agents. Watch Pi drive Claude, Gemini, Codex, Cursor directly from Pi. Take over anytime. Real PTY, full terminal emulation, more token efficient than using tmux.
+An extension for [Pi coding agent](https://github.com/badlogic/pi-mono/) that lets Pi autonomously run interactive CLIs in an observable TUI overlay. Pi controls the subprocess while you watch - take over anytime.
+
+https://github.com/user-attachments/assets/76f56ecd-fc12-4d92-a01e-e6ae9ba65ff4
 
 ```typescript
-interactive_shell({ command: 'agent "fix all the bugs"', mode: "hands-free" })
-// Returns immediately with sessionId
-// User watches in overlay, you query for status
-// Session auto-closes when agent finishes
+interactive_shell({ command: 'vim config.yaml' })
 ```
 
 ## Why
 
-AI agents delegating to other AI agents is powerful but messy:
-
-- **Visibility** - What's the subagent doing? Is it stuck?
-- **Control** - User needs to intervene. How?
-- **Integration** - When does the parent agent check in?
-
-Interactive Shell solves all three:
-
-**Real-Time Overlay** - User sees the subprocess in a TUI overlay. Full terminal emulation via xterm-headless. ANSI colors, cursor movement, everything.
-
-**Seamless Takeover** - Type anything to take control. Scroll with Shift+Up/Down. Double-Escape to detach.
+Some tasks need interactive CLIs - editors, REPLs, database shells, long-running processes. Pi can launch them in an overlay where:
 
-**Non-Blocking API** - Start a session, get a sessionId, query for status. Rate-limited to prevent spam. Auto-exits when output stops.
+- **User watches** - See exactly what's happening in real-time
+- **User takes over** - Type anything to gain control
+- **Agent monitors** - Query status, send input, decide when done
 
-**Any CLI** - Not just AI agents. Run `htop`, `vim`, `psql`, `ssh` - anything interactive.
+Works with any CLI: `vim`, `htop`, `psql`, `ssh`, `docker logs -f`, `npm run dev`, `git rebase -i`, etc.
 
 ## Install
 
@@ -35,17 +26,32 @@ npx pi-interactive-shell
 
 Installs to `~/.pi/agent/extensions/interactive-shell/`.
 
+The `interactive-shell` skill is automatically symlinked to `~/.pi/agent/skills/interactive-shell/`.
+
 **Requires:** Node.js, build tools for `node-pty` (Xcode CLI tools on macOS).
 
 ## Quick Start
 
-### Hands-Free (Agent-to-Agent)
+### Interactive Mode
+
+User controls the session directly:
+
+```typescript
+interactive_shell({ command: 'vim package.json' })
+interactive_shell({ command: 'psql -d mydb' })
+interactive_shell({ command: 'ssh user@server' })
+```
+
+### Hands-Free Mode
+
+Agent monitors while user watches. Returns immediately with sessionId:
 
 ```typescript
-// Start - returns immediately
+// Start a long-running process
 interactive_shell({
-  command: 'pi "Refactor the auth module"',
-  mode: "hands-free"
+  command: 'npm run dev',
+  mode: "hands-free",
+  reason: "Dev server"
 })
 // → { sessionId: "calm-reef", status: "running" }
 
@@ -53,53 +59,57 @@ interactive_shell({
 interactive_shell({ sessionId: "calm-reef" })
 // → { status: "running", output: "...", runtime: 45000 }
 
-// Get more output
-interactive_shell({ sessionId: "calm-reef", outputLines: 100 })
+// Send input if needed
+interactive_shell({ sessionId: "calm-reef", input: { keys: ["ctrl+c"] } })
 
-// Kill when done (or let autoExitOnQuiet handle it)
+// Kill when done
 interactive_shell({ sessionId: "calm-reef", kill: true })
 ```
 
-### Interactive (User Control)
+User sees the overlay in real-time. Type anything to take over control.
 
-```typescript
-interactive_shell({ command: 'vim package.json' })
-```
+### Timeout Mode
 
-### Send Input
+Capture output from TUI apps that don't exit cleanly:
 
 ```typescript
-interactive_shell({ sessionId: "calm-reef", input: "/help\n" })
-interactive_shell({ sessionId: "calm-reef", input: { keys: ["ctrl+c"] } })
-interactive_shell({ sessionId: "calm-reef", input: { keys: ["down", "down", "enter"] } })
+interactive_shell({
+  command: "htop",
+  mode: "hands-free",
+  timeout: 3000  // Kill after 3s, return captured output
+})
 ```
 
-## CLI Reference
-
-| Agent | Interactive | With Prompt | Headless (use bash) |
-|-------|-------------|-------------|---------------------|
-| `claude` | `claude` | `claude "prompt"` | `claude -p "prompt"` |
-| `gemini` | `gemini` | `gemini -i "prompt"` | `gemini "prompt"` |
-| `codex` | `codex` | `codex "prompt"` | `codex exec "prompt"` |
-| `agent` | `agent` | `agent "prompt"` | `agent -p "prompt"` |
-| `pi` | `pi` | `pi "prompt"` | `pi -p "prompt"` |
-
 ## Features
 
 ### Auto-Exit on Quiet
 
-Sessions auto-close after 5s of silence. Disable with `handsFree: { autoExitOnQuiet: false }`.
-
-### Timeout for TUI Capture
+For fire-and-forget single-task delegations, enable auto-exit to kill the session after 5s of output silence:
 
 ```typescript
 interactive_shell({
-  command: "pi --help",
+  command: 'cursor-agent -f "Fix the bug in auth.ts"',
   mode: "hands-free",
-  timeout: 5000  // Kill after 5s, return captured output
+  handsFree: { autoExitOnQuiet: true }
 })
 ```
 
+For multi-turn sessions where you need back-and-forth interaction, leave it disabled (default) and use `kill: true` when done.
+
+### Send Input
+
+```typescript
+// Text
+interactive_shell({ sessionId: "calm-reef", input: "SELECT * FROM users;\n" })
+
+// Named keys
+interactive_shell({ sessionId: "calm-reef", input: { keys: ["ctrl+c"] } })
+interactive_shell({ sessionId: "calm-reef", input: { keys: ["down", "down", "enter"] } })
+
+// Bracketed paste (multiline without execution)
+interactive_shell({ sessionId: "calm-reef", input: { paste: "line1\nline2\nline3" } })
+```
+
 ### Configurable Output
 
 ```typescript
@@ -109,77 +119,67 @@ interactive_shell({ sessionId: "calm-reef" })
 // More lines (max: 200)
 interactive_shell({ sessionId: "calm-reef", outputLines: 100 })
 
-// More content (max: 50KB)
-interactive_shell({ sessionId: "calm-reef", outputMaxChars: 30000 })
-```
+// Incremental pagination (server tracks position)
+interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
 
-### Input Methods
-
-| Method | Example |
-|--------|---------|
-| Text | `input: "/model\n"` |
-| Keys | `input: { keys: ["enter", "ctrl+c"] }` |
-| Hex | `input: { hex: ["0x1b", "0x5b", "0x41"] }` |
-| Paste | `input: { paste: "multi\nline" }` |
+// Drain mode (raw stream since last query)
+interactive_shell({ sessionId: "calm-reef", drain: true })
+```
 
 ### Background Sessions
 
-1. Double-Escape → "Run in background"
+1. Ctrl+Q → "Run in background"
 2. `/attach` or `/attach <id>` to reattach
 
-## Config
-
-`~/.pi/agent/interactive-shell.json`
-
-```json
-{
-  "overlayHeightPercent": 45,
-  "overlayWidthPercent": 95,
-  "scrollbackLines": 5000,
-  "minQueryIntervalSeconds": 60,
-  "handsFreeQuietThreshold": 5000
-}
-```
-
 ## Keys
 
 | Key | Action |
 |-----|--------|
-| Double-Escape | Detach dialog |
+| Ctrl+Q | Detach dialog |
 | 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.
+## Config
 
-**Drain Mode** - Use `drain: true` to get only NEW output since last query. No re-reading old content.
+Configuration files (project overrides global):
+- **Global:** `~/.pi/agent/interactive-shell.json`
+- **Project:** `.pi/interactive-shell.json`
 
-```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
+```json
+{
+  "overlayWidthPercent": 95,
+  "overlayHeightPercent": 45,
+  "scrollbackLines": 5000,
+  "exitAutoCloseDelay": 10,
+  "minQueryIntervalSeconds": 60,
+  "handsFreeUpdateMode": "on-quiet",
+  "handsFreeUpdateInterval": 60000,
+  "handsFreeQuietThreshold": 5000,
+  "handsFreeUpdateMaxChars": 1500,
+  "handsFreeMaxTotalChars": 100000,
+  "handoffPreviewEnabled": true,
+  "handoffPreviewLines": 30,
+  "handoffPreviewMaxChars": 2000,
+  "handoffSnapshotEnabled": false,
+  "ansiReemit": true
+}
 ```
 
-**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 })
-```
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `overlayWidthPercent` | 95 | Overlay width (10-100%) |
+| `overlayHeightPercent` | 45 | Overlay height (20-90%) |
+| `scrollbackLines` | 5000 | Terminal scrollback buffer |
+| `exitAutoCloseDelay` | 10 | Seconds before auto-close after exit |
+| `minQueryIntervalSeconds` | 60 | Rate limit between agent queries |
+| `handsFreeUpdateMode` | "on-quiet" | "on-quiet" or "interval" |
+| `handsFreeQuietThreshold` | 5000 | Silence duration before update (ms) |
+| `handsFreeUpdateInterval` | 60000 | Max interval between updates (ms) |
+| `handsFreeUpdateMaxChars` | 1500 | Max chars per update |
+| `handsFreeMaxTotalChars` | 100000 | Total char budget for updates |
+| `handoffPreviewEnabled` | true | Include tail in tool result |
+| `handoffSnapshotEnabled` | false | Write transcript on detach/exit |
+| `ansiReemit` | true | Preserve ANSI colors in output |
 
 ## How It Works
 
@@ -193,6 +193,12 @@ interactive_shell → node-pty → subprocess
 
 Full PTY. The subprocess thinks it's in a real terminal.
 
+## Advanced: Multi-Agent Workflows
+
+For orchestrating multi-agent chains (scout → planner → worker → reviewer) with file-based handoff and auto-continue support, see:
+
+**[pi-foreground-chains](https://github.com/nicobailon/pi-foreground-chains)** - A separate skill that builds on interactive-shell for complex agent workflows.
+
 ## Limitations
 
 - macOS tested, Linux experimental

package/SKILL.md

@@ -97,8 +97,8 @@ const result = interactive_shell({
   command: 'codex "Review this codebase"',
   mode: "hands-free"
 })
-// result.sessionId = "calm-reef"
-// result.status = "running"
+// result.details.sessionId = "calm-reef"
+// result.details.status = "running"
 ```
 
 The user sees the overlay immediately. You get control back to continue working.
@@ -122,21 +122,41 @@ interactive_shell({ sessionId: "calm-reef", kill: true })
 
 Kill when you see the task is complete in the output. Returns final status and output.
 
-**Auto-exit (default: enabled):** In hands-free mode, sessions auto-kill when output stops (after ~5 seconds of quiet). This means when an agent finishes its task and returns to its prompt, the session closes automatically.
+### Fire-and-Forget Tasks
 
-Since sessions auto-close, **always instruct the subagent to save results to a file** so you can read them:
+For single-task delegations where you don't need multi-turn interaction, enable auto-exit so the session kills itself when the agent goes quiet:
 
 ```typescript
 interactive_shell({
   command: 'pi "Review this codebase for security issues. Save your findings to /tmp/security-review.md"',
   mode: "hands-free",
-  reason: "Security review"
+  reason: "Security review",
+  handsFree: { autoExitOnQuiet: true }
 })
-// After session ends, read the results:
+// Session auto-kills after ~5s of quiet
+// Read results from file:
 // read("/tmp/security-review.md")
 ```
 
-To disable auto-exit (for long-running tasks or when you need to review output): `handsFree: { autoExitOnQuiet: false }`
+**Instruct subagent to save results to a file** since the session closes automatically.
+
+### Multi-Turn Sessions (default)
+
+For back-and-forth interaction, leave auto-exit disabled (the default). Query status and kill manually when done:
+
+```typescript
+interactive_shell({
+  command: 'cursor-agent -f',
+  mode: "hands-free",
+  reason: "Interactive refactoring"
+})
+
+// Send follow-up prompts
+interactive_shell({ sessionId: "calm-reef", input: "Now fix the tests\n" })
+
+// Kill when done
+interactive_shell({ sessionId: "calm-reef", kill: true })
+```
 
 ### Sending Input
 ```typescript
@@ -159,19 +179,32 @@ interactive_shell({ sessionId: "calm-reef", outputLines: 50 })
 interactive_shell({ sessionId: "calm-reef", outputLines: 100, outputMaxChars: 30000 })
 ```
 
-### Reviewing Long Sessions (autoExitOnQuiet disabled)
+### Incremental Reading
 
-When you disable auto-exit for long-running tasks, progressively review more output as needed:
+Use `incremental: true` to paginate through output without re-reading:
 
 ```typescript
-// Start a long session without auto-exit
-interactive_shell({
-  command: 'pi "Refactor entire codebase"',
-  mode: "hands-free",
-  handsFree: { autoExitOnQuiet: false }
-})
+// First call: get first 50 lines
+interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
+// → { output: "...", hasMore: true }
+
+// Next call: get next 50 lines (server tracks position)
+interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
+// → { output: "...", hasMore: true }
+
+// Keep calling until hasMore: false
+interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true })
+// → { output: "...", hasMore: false }
+```
+
+The server tracks your read position - just keep calling with `incremental: true` to get the next chunk.
+
+### Reviewing Output
 
-// Query returns last 20 lines by default
+Query sessions to see progress. Increase limits when you need more context:
+
+```typescript
+// Default: last 20 lines
 interactive_shell({ sessionId: "calm-reef" })
 
 // Get more lines when you need more context

package/config.ts

@@ -3,7 +3,6 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 export interface InteractiveShellConfig {
-	doubleEscapeThreshold: number;
 	exitAutoCloseDelay: number;
 	overlayWidthPercent: number;
 	overlayHeightPercent: number;
@@ -26,7 +25,6 @@ export interface InteractiveShellConfig {
 }
 
 const DEFAULT_CONFIG: InteractiveShellConfig = {
-	doubleEscapeThreshold: 300,
 	exitAutoCloseDelay: 10,
 	overlayWidthPercent: 95,
 	overlayHeightPercent: 45,