pi-interactive-shell 0.4.9 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to the `pi-interactive-shell` extension will be documented in this file.
 
+## [0.5.1] - 2026-01-22
+
+### Fixed
+- **Prevent overlay stacking** - Starting a new `interactive_shell` session or using `/attach` while an overlay is already open now returns an error instead of causing undefined behavior with stacked/stuck overlays.
+
+## [0.5.0] - 2026-01-22
+
+### Changed
+- **BREAKING: Split `input` into separate fields for Vertex AI compatibility** - The `input` parameter which previously accepted either a string or an object with `text/keys/hex/paste` fields has been split into separate parameters:
+  - `input` - Raw text/keystrokes (string only)
+  - `inputKeys` - Named keys array (e.g., `["ctrl+c", "enter"]`)
+  - `inputHex` - Hex bytes array for raw escape sequences
+  - `inputPaste` - Text for bracketed paste mode
+  
+  This change was required because Claude's Vertex AI API (`google-antigravity` provider) rejects `anyOf` JSON schemas with mixed primitive/object types.
+
+### Migration
+```typescript
+// Before (0.4.x)
+interactive_shell({ sessionId: "abc", input: { keys: ["ctrl+c"] } })
+interactive_shell({ sessionId: "abc", input: { paste: "code" } })
+
+// After (0.5.0)
+interactive_shell({ sessionId: "abc", inputKeys: ["ctrl+c"] })
+interactive_shell({ sessionId: "abc", inputPaste: "code" })
+
+// Combining text with keys (still works)
+interactive_shell({ sessionId: "abc", input: "y", inputKeys: ["enter"] })
+```
+
 ## [0.4.9] - 2026-01-21
 
 ### Fixed

package/README.md

@@ -60,7 +60,7 @@ interactive_shell({ sessionId: "calm-reef" })
 // → { status: "running", output: "...", runtime: 45000 }
 
 // Send input if needed
-interactive_shell({ sessionId: "calm-reef", input: { keys: ["ctrl+c"] } })
+interactive_shell({ sessionId: "calm-reef", inputKeys: ["ctrl+c"] })
 
 // Kill when done
 interactive_shell({ sessionId: "calm-reef", kill: true })
@@ -103,11 +103,17 @@ For multi-turn sessions where you need back-and-forth interaction, leave it disa
 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"] } })
+interactive_shell({ sessionId: "calm-reef", inputKeys: ["ctrl+c"] })
+interactive_shell({ sessionId: "calm-reef", inputKeys: ["down", "down", "enter"] })
 
 // Bracketed paste (multiline without execution)
-interactive_shell({ sessionId: "calm-reef", input: { paste: "line1\nline2\nline3" } })
+interactive_shell({ sessionId: "calm-reef", inputPaste: "line1\nline2\nline3" })
+
+// Hex bytes (raw escape sequences)
+interactive_shell({ sessionId: "calm-reef", inputHex: ["0x1b", "0x5b", "0x41"] })
+
+// Combine text with keys
+interactive_shell({ sessionId: "calm-reef", input: "y", inputKeys: ["enter"] })
 ```
 
 ### Configurable Output

package/SKILL.md

@@ -161,7 +161,9 @@ interactive_shell({ sessionId: "calm-reef", kill: true })
 ### Sending Input
 ```typescript
 interactive_shell({ sessionId: "calm-reef", input: "/help\n" })
-interactive_shell({ sessionId: "calm-reef", input: { keys: ["ctrl+c"] } })
+interactive_shell({ sessionId: "calm-reef", inputKeys: ["ctrl+c"] })
+interactive_shell({ sessionId: "calm-reef", inputPaste: "multi\nline\ncode" })
+interactive_shell({ sessionId: "calm-reef", input: "y", inputKeys: ["enter"] })  // combine text + keys
 ```
 
 ### Query Output
@@ -223,14 +225,14 @@ Use the `sessionId` from updates to send input to a running hands-free session:
 // Send text
 interactive_shell({ sessionId: "shell-1", input: "/help\n" })
 
-// Send with named keys
-interactive_shell({ sessionId: "shell-1", input: { text: "/model", keys: ["enter"] } })
+// Send text with keys
+interactive_shell({ sessionId: "shell-1", input: "/model", inputKeys: ["enter"] })
 
 // Navigate menus
-interactive_shell({ sessionId: "shell-1", input: { keys: ["down", "down", "enter"] } })
+interactive_shell({ sessionId: "shell-1", inputKeys: ["down", "down", "enter"] })
 
 // Interrupt
-interactive_shell({ sessionId: "shell-1", input: { keys: ["ctrl+c"] } })
+interactive_shell({ sessionId: "shell-1", inputKeys: ["ctrl+c"] })
 ```
 
 ### Named Keys
@@ -257,45 +259,45 @@ Note: `ic`/`dc`, `ppage`/`npage`, `bspace` are tmux-style aliases for compatibil
 Supports `ctrl+`, `alt+`, `shift+` prefixes (or shorthand `c-`, `m-`, `s-`):
 ```typescript
 // Cancel
-{ keys: ["ctrl+c"] }
+inputKeys: ["ctrl+c"]
 
 // Alt+Tab
-{ keys: ["alt+tab"] }
+inputKeys: ["alt+tab"]
 
 // Ctrl+Alt+Delete
-{ keys: ["ctrl+alt+delete"] }
+inputKeys: ["ctrl+alt+delete"]
 
 // Shorthand syntax
-{ keys: ["c-c", "m-x", "s-tab"] }
+inputKeys: ["c-c", "m-x", "s-tab"]
 ```
 
 ### Hex Bytes (Advanced)
 Send raw escape sequences:
 ```typescript
-{ hex: ["0x1b", "0x5b", "0x41"] }  // ESC[A (up arrow)
+inputHex: ["0x1b", "0x5b", "0x41"]  // ESC[A (up arrow)
 ```
 
 ### Bracketed Paste
 Paste multiline text without triggering autocompletion/execution:
 ```typescript
-{ paste: "function foo() {\n  return 42;\n}" }
+inputPaste: "function foo() {\n  return 42;\n}"
 ```
 
 ### Model Selection Example
 ```typescript
 // Step 1: Open model selector
-interactive_shell({ sessionId: "shell-1", input: { text: "/model", keys: ["enter"] } })
+interactive_shell({ sessionId: "shell-1", input: "/model", inputKeys: ["enter"] })
 
 // Step 2: Filter and select (after ~500ms delay)
-interactive_shell({ sessionId: "shell-1", input: { text: "sonnet", keys: ["enter"] } })
+interactive_shell({ sessionId: "shell-1", input: "sonnet", inputKeys: ["enter"] })
 
 // Or navigate with arrows:
-interactive_shell({ sessionId: "shell-1", input: { keys: ["down", "down", "down", "enter"] } })
+interactive_shell({ sessionId: "shell-1", inputKeys: ["down", "down", "down", "enter"] })
 ```
 
 ### Context Compaction
 ```typescript
-interactive_shell({ sessionId: "shell-1", input: { text: "/compact", keys: ["enter"] } })
+interactive_shell({ sessionId: "shell-1", input: "/compact", inputKeys: ["enter"] })
 ```
 
 ### Changing Update Settings
@@ -396,11 +398,11 @@ interactive_shell({
 // Text with enter
 interactive_shell({ sessionId: "calm-reef", input: "/compact\n" })
 
-// Named keys
-interactive_shell({ sessionId: "calm-reef", input: { text: "/model", keys: ["enter"] } })
+// Text + named keys
+interactive_shell({ sessionId: "calm-reef", input: "/model", inputKeys: ["enter"] })
 
 // Menu navigation
-interactive_shell({ sessionId: "calm-reef", input: { keys: ["down", "down", "enter"] } })
+interactive_shell({ sessionId: "calm-reef", inputKeys: ["down", "down", "enter"] })
 ```
 
 **Change update frequency:**

package/index.ts

@@ -8,6 +8,9 @@ import { translateInput } from "./key-encoding.js";
 import { TOOL_NAME, TOOL_LABEL, TOOL_DESCRIPTION, toolParameters, type ToolParams } from "./tool-schema.js";
 import { formatDuration, formatDurationMs } from "./types.js";
 
+// Track whether an overlay is currently open to prevent stacking
+let overlayOpen = false;
+
 export default function interactiveShellExtension(pi: ExtensionAPI) {
 	pi.on("session_shutdown", () => {
 		sessionManager.killAll();
@@ -31,6 +34,9 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 				incremental,
 				settings,
 				input,
+				inputKeys,
+				inputHex,
+				inputPaste,
 				cwd,
 				name,
 				reason,
@@ -41,6 +47,12 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 				timeout,
 			} = params as ToolParams;
 
+			// Build structured input from separate fields if any are provided
+			const hasStructuredInput = inputKeys?.length || inputHex?.length || inputPaste;
+			const effectiveInput = hasStructuredInput
+				? { text: input, keys: inputKeys, hex: inputHex, paste: inputPaste }
+				: input;
+
 			// Mode 1: Interact with existing session (query status, send input, kill, or change settings)
 			if (sessionId) {
 				const session = sessionManager.getActive(sessionId);
@@ -100,8 +112,8 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 				}
 
 				// Send input if provided
-				if (input !== undefined) {
-					const translatedInput = translateInput(input);
+				if (effectiveInput !== undefined) {
+					const translatedInput = translateInput(effectiveInput);
 					const success = sessionManager.writeToActive(sessionId, translatedInput);
 
 					if (!success) {
@@ -113,17 +125,17 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 					}
 
 					const inputDesc =
-						typeof input === "string"
-							? input.length === 0
+						typeof effectiveInput === "string"
+							? effectiveInput.length === 0
 								? "(empty)"
-								: input.length > 50
-									? `${input.slice(0, 50)}...`
-									: input
+								: effectiveInput.length > 50
+									? `${effectiveInput.slice(0, 50)}...`
+									: effectiveInput
 							: [
-									input.text ?? "",
-									input.keys ? `keys:[${input.keys.join(",")}]` : "",
-									input.hex ? `hex:[${input.hex.length} bytes]` : "",
-									input.paste ? `paste:[${input.paste.length} chars]` : "",
+									effectiveInput.text ?? "",
+									effectiveInput.keys ? `keys:[${effectiveInput.keys.join(",")}]` : "",
+									effectiveInput.hex ? `hex:[${effectiveInput.hex.length} bytes]` : "",
+									effectiveInput.paste ? `paste:[${effectiveInput.paste.length} chars]` : "",
 								]
 									.filter(Boolean)
 									.join(" + ") || "(empty)";
@@ -361,12 +373,24 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 			const config = loadConfig(effectiveCwd);
 			const isHandsFree = mode === "hands-free";
 
+			// Prevent starting a new overlay while one is already open
+			if (overlayOpen) {
+				return {
+					content: [{ type: "text", text: "An interactive shell overlay is already open. Wait for it to close or kill the active session before starting a new one." }],
+					isError: true,
+					details: { error: "overlay_already_open" },
+				};
+			}
+
 			// Generate sessionId early so it's available immediately
 			const generatedSessionId = isHandsFree ? generateSessionId(name) : undefined;
 
 			// For hands-free mode: non-blocking - return immediately with sessionId
 			// Agent can then query status/output via sessionId and kill when done
 			if (isHandsFree && generatedSessionId) {
+				// Mark overlay as open
+				overlayOpen = true;
+
 				// Start overlay but don't await - it runs in background
 				const overlayPromise = ctx.ui.custom<InteractiveShellResult>(
 					(tui, theme, _kb, done) =>
@@ -412,12 +436,14 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 
 				// Handle overlay completion in background (cleanup when user closes)
 				overlayPromise.then((result) => {
+					overlayOpen = false;
 					// Session already handles cleanup via finishWith* methods
 					// This just ensures the promise doesn't cause unhandled rejection
 					if (result.userTookOver) {
 						// User took over - session continues interactively
 					}
 				}).catch(() => {
+					overlayOpen = false;
 					// Ignore errors - session cleanup handles this
 				});
 
@@ -439,6 +465,7 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 			}
 
 			// Interactive mode: blocking - wait for overlay to close
+			overlayOpen = true;
 			onUpdate?.({
 				content: [{ type: "text", text: `Opening: ${command}` }],
 				details: {
@@ -448,7 +475,9 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 				},
 			});
 
-			const result = await ctx.ui.custom<InteractiveShellResult>(
+			let result: InteractiveShellResult;
+			try {
+				result = await ctx.ui.custom<InteractiveShellResult>(
 				(tui, theme, _kb, done) =>
 					new InteractiveShellOverlay(
 						tui,
@@ -523,6 +552,9 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 					},
 				},
 			);
+			} finally {
+				overlayOpen = false;
+			}
 
 			let summary: string;
 			if (result.backgrounded) {
@@ -560,6 +592,12 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 	pi.registerCommand("attach", {
 		description: "Reattach to a background shell session",
 		handler: async (args, ctx) => {
+			// Prevent reattaching while another overlay is open
+			if (overlayOpen) {
+				ctx.ui.notify("An overlay is already open. Close it first.", "error");
+				return;
+			}
+
 			const sessions = sessionManager.list();
 
 			if (sessions.length === 0) {
@@ -592,25 +630,30 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 			}
 
 			const config = loadConfig(ctx.cwd);
-			await ctx.ui.custom<InteractiveShellResult>(
-				(tui, theme, _kb, done) =>
-					new ReattachOverlay(
-						tui,
-						theme,
-						{ id: session.id, command: session.command, reason: session.reason, session: session.session },
-						config,
-						done,
-					),
-				{
-					overlay: true,
-					overlayOptions: {
-						width: `${config.overlayWidthPercent}%`,
-						maxHeight: `${config.overlayHeightPercent}%`,
-						anchor: "center",
-						margin: 1,
+			overlayOpen = true;
+			try {
+				await ctx.ui.custom<InteractiveShellResult>(
+					(tui, theme, _kb, done) =>
+						new ReattachOverlay(
+							tui,
+							theme,
+							{ id: session.id, command: session.command, reason: session.reason, session: session.session },
+							config,
+							done,
+						),
+					{
+						overlay: true,
+						overlayOptions: {
+							width: `${config.overlayWidthPercent}%`,
+							maxHeight: `${config.overlayHeightPercent}%`,
+							anchor: "center",
+							margin: 1,
+						},
 					},
-				},
-			);
+				);
+			} finally {
+				overlayOpen = false;
+			}
 		},
 	});
 }

package/package.json

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

package/tool-schema.ts

@@ -54,13 +54,14 @@ Queries are limited to once every 60 seconds (configurable). If you query too so
 the tool will automatically wait until the limit expires before returning.
 
 SENDING INPUT:
-- interactive_shell({ sessionId: "calm-reef", input: "/help\\n" })
-- interactive_shell({ sessionId: "calm-reef", input: { keys: ["ctrl+c"] } })
+- interactive_shell({ sessionId: "calm-reef", input: "/help\\n" }) - raw text/keystrokes
+- interactive_shell({ sessionId: "calm-reef", inputKeys: ["ctrl+c"] }) - named keys
+- interactive_shell({ sessionId: "calm-reef", inputKeys: ["up", "up", "enter"] }) - multiple keys
+- interactive_shell({ sessionId: "calm-reef", inputHex: ["0x1b", "0x5b", "0x41"] }) - raw escape sequences
+- interactive_shell({ sessionId: "calm-reef", inputPaste: "multiline\\ntext" }) - bracketed paste (prevents auto-execution)
 
-Named keys: up, down, left, right, enter, escape, tab, backspace, ctrl+c, ctrl+d, etc.
+Named keys for inputKeys: up, down, left, right, enter, escape, tab, backspace, ctrl+c, ctrl+d, etc.
 Modifiers: ctrl+x, alt+x, shift+tab, ctrl+alt+delete (or c-x, m-x, s-tab syntax)
-Hex bytes: input: { hex: ["0x1b", "0x5b", "0x41"] } for raw escape sequences
-Bracketed paste: input: { paste: "multiline\\ntext" } prevents auto-execution
 
 TIMEOUT (for TUI commands that don't exit cleanly):
 Use timeout to auto-kill after N milliseconds. Useful for capturing output from commands like "pi --help":
@@ -128,31 +129,22 @@ export const toolParameters = Type.Object({
 		}),
 	),
 	input: Type.Optional(
-		Type.Union(
-			[
-				Type.String({ description: "Raw text/keystrokes to send" }),
-				Type.Object({
-					text: Type.Optional(Type.String({ description: "Text to type" })),
-					keys: Type.Optional(
-						Type.Array(Type.String(), {
-							description:
-								"Named keys with modifier support: up, down, enter, ctrl+c, alt+x, shift+tab, ctrl+alt+delete, etc.",
-						}),
-					),
-					hex: Type.Optional(
-						Type.Array(Type.String(), {
-							description: "Hex bytes to send (e.g., ['0x1b', '0x5b', '0x41'] for ESC[A)",
-						}),
-					),
-					paste: Type.Optional(
-						Type.String({
-							description: "Text to paste with bracketed paste mode (prevents auto-execution)",
-						}),
-					),
-				}),
-			],
-			{ description: "Input to send to an existing session (requires sessionId)" },
-		),
+		Type.String({ description: "Raw text/keystrokes to send to the session (requires sessionId). For special keys, use inputKeys instead." }),
+	),
+	inputKeys: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Named keys with modifier support: up, down, enter, ctrl+c, alt+x, shift+tab, ctrl+alt+delete, etc. (requires sessionId)",
+		}),
+	),
+	inputHex: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Hex bytes to send as raw escape sequences (e.g., ['0x1b', '0x5b', '0x41'] for ESC[A). (requires sessionId)",
+		}),
+	),
+	inputPaste: Type.Optional(
+		Type.String({
+			description: "Text to paste with bracketed paste mode - prevents shells from auto-executing multiline input. (requires sessionId)",
+		}),
 	),
 	cwd: Type.Optional(
 		Type.String({
@@ -171,15 +163,15 @@ export const toolParameters = Type.Object({
 		}),
 	),
 	mode: Type.Optional(
-		Type.Union([Type.Literal("interactive"), Type.Literal("hands-free")], {
-			description: "interactive (default): user controls. hands-free: agent monitors, user can take over",
+		Type.String({
+			description: "Mode: 'interactive' (default, user controls) or 'hands-free' (agent monitors, user can take over)",
 		}),
 	),
 	handsFree: Type.Optional(
 		Type.Object({
 			updateMode: Type.Optional(
-				Type.Union([Type.Literal("on-quiet"), Type.Literal("interval")], {
-					description: "on-quiet (default): emit when output stops. interval: emit on fixed schedule.",
+				Type.String({
+					description: "Update mode: 'on-quiet' (default, emit when output stops) or 'interval' (emit on fixed schedule)",
 				}),
 			),
 			updateInterval: Type.Optional(
@@ -235,7 +227,10 @@ export interface ToolParams {
 	drain?: boolean;
 	incremental?: boolean;
 	settings?: { updateInterval?: number; quietThreshold?: number };
-	input?: string | { text?: string; keys?: string[]; hex?: string[]; paste?: string };
+	input?: string;
+	inputKeys?: string[];
+	inputHex?: string[];
+	inputPaste?: string;
 	cwd?: string;
 	name?: string;
 	reason?: string;