@oh-my-pi/pi-coding-agent 5.5.0 → 5.6.7

package/CHANGELOG.md

@@ -2,6 +2,104 @@
 
 ## [Unreleased]
 
+## [5.6.7] - 2026-01-18
+
+### Added
+
+- Added Python shared gateway setting to enable resource-efficient kernel reuse across sessions
+- Added Python tool cancellation support with proper timeout and cleanup handling
+- Added enhanced Python prelude helpers including file operations, text processing, and Git utilities
+- Added Python tool documentation rendering with categorized helper functions
+- Added session-scoped Python kernel isolation with workdir-aware session IDs
+- Added structured status events for Python prelude functions with TUI rendering
+- Added status event display system with operation icons and formatted descriptions
+- Added support for rich output using IPython.display.display() in Python tool
+- Added setup subcommand to install dependencies for optional features
+- Added Python setup component to install Jupyter kernel dependencies
+- Added setup command help with component and option documentation
+- Added Python tool dependency check in help output
+- Added file locking mechanism for shared Python gateway to prevent race conditions
+- Added Python gateway status monitoring with URL, PID, client count, and uptime information
+- Added comprehensive Git helpers to Python prelude including status, diff, log, show, branch, and file operations
+- Added line-based operations to Python prelude including line extraction, deletion, insertion, and pattern matching
+- Added automatic categorization system for Python prelude functions with discoverable documentation
+- Added enhanced `/status` command display showing Python gateway, LSP servers, and MCP server connections
+- Added shared Python gateway coordinator for resource-efficient kernel management across sessions
+- Added Python shared gateway setting with session-scoped kernel reuse and fallback behavior
+- Added automatic idle shutdown for shared Python gateway after 30 seconds of inactivity
+- Added environment filtering for shared Python gateway to exclude sensitive API keys
+- Added virtual environment detection and automatic PATH configuration for Python gateway
+- Added IPython-backed Python tool with streaming output, image/JSON rendering, and Jupyter kernel gateway integration
+- Added Python prelude with 30+ shell-like utility functions for file operations
+- Added Python tool exposure settings with session-scoped kernel reuse and fallback behavior
+- Added streaming output system with automatic spill-to-disk for large outputs
+- Added extension input interception with source metadata and command argument completion
+- Added extension command context `compact()` helper plus context usage accessors
+- Added ExtensionAPI `setLabel()` for extension and entry labels
+- Added startup quiet setting to suppress welcome screen and startup messages
+- Added support for auto-discovering APPEND_SYSTEM.md files
+- Added support for piped input in non-interactive mode (auto-print mode)
+- Added global session listing across all project directories with enhanced search metadata
+- Added session fork prompt when resolving sessions from other projects
+- Added key hint formatting utilities plus public exports for getShellConfig/getAgentDir/VERSION
+- Added bash tool timeout display in tool output
+- Added fuzzy text normalization for improved edit diff matching
+- Added $@ argument slicing syntax in prompt templates
+- Added configurable keybindings for expand tools and dequeue actions
+- Added process title update on CLI startup
+
+### Changed
+
+- Updated Python tool description to display categorized helper functions with improved formatting
+- Enhanced Python kernel startup to use shared gateway by default for better resource utilization
+- Improved Python prelude functions to emit structured status events instead of text output
+- Updated agent prompts to use bash tool instead of exec for git operations
+- Changed default Python tool mode from ipy-only to both to enable shell execution
+- Enhanced Python gateway coordination with Windows environment support and stale process cleanup
+- Updated Python prelude functions to emit structured status events instead of text output
+- Enhanced Python tool renderer to display status events alongside output
+- Improved Python tool output formatting with status event integration
+- Improved shared Python gateway coordination with environment validation and stale process cleanup
+- Updated Python prelude to rename `bash()` function to `sh()` for consistency
+- Changed default Python tool mode from "ipy-only" to "both" to enable both IPython and shell execution
+- Enhanced Python gateway metadata tracking to include Python path and virtual environment information
+- Improved Python kernel startup to use shared gateway by default for better resource utilization
+- Updated Python tool to support proxy execution mode for worker processes
+- Enhanced Python kernel availability checking with faster validation
+- Optimized Python environment warming to avoid blocking during tool initialization
+- Reorganized settings interface into behavior, tools, display, voice, status, lsp, and exa tabs
+- Migrated environment variables from PI_ to OMP_ prefix with automatic migration
+- Updated model selector to use TabBar component for provider navigation
+- Changed role badges to inverted style with colored backgrounds
+- Added support for /models command alias in addition to /model
+- Improved error retry detection to include fetch failures
+- Enhanced session selector search and overflow handling
+- Updated skill command execution to include skill path metadata
+- Surfaced loaded prompt templates during initialization
+- Updated compaction summarization to use serialized prompt text
+- Cleaned up Python prelude `sh()` and `run()` output to only show stdout/stderr without noisy metadata
+
+### Fixed
+
+- Fixed Python kernel cancellation handling and WebSocket cleanup for in-flight executions
+- Fixed Python tool session scoping to include workdir and honor sharedGateway settings
+- Fixed gist sharing output draining to avoid truncated URLs
+- Fixed streaming output byte accounting and UTF-8 decoder flushing
+- Fixed Python prelude integration tests to detect virtual environments and cover helper exports
+- Fixed Python kernel cancellation/timeout handling and WebSocket close cleanup for in-flight executions
+- Fixed Python output byte accounting and UTF-8 decoder flushing in streaming output
+- Fixed shared Python gateway coordination (Windows env allowlist, lock staleness, refcount recovery)
+- Fixed Python tool session scoping to include workdir and honor sharedGateway settings
+- Fixed subagent Python proxy session isolation and cancellation/timeout propagation
+- Fixed print-mode cleanup to dispose Python sessions before exit
+- Fixed gist share output draining to avoid truncated URLs
+- Fixed explore agent tool list to use bash for git operations
+- Fixed Python prelude integration tests to detect venv-only Python and cover helper exports
+
+### Security
+
+- Enhanced Python gateway environment filtering to exclude sensitive API keys and Windows system paths
+
 ## [5.5.0] - 2026-01-18
 ### Changed
 

package/docs/python-repl.md

@@ -0,0 +1,77 @@
+# Python REPL (Jupyter Kernel Gateway)
+
+## Requirements
+
+- Python 3 available on PATH (or via an active virtualenv)
+- `jupyter-kernel-gateway` (`kernel_gateway` module) and `ipykernel` installed in the selected Python environment
+
+Install:
+```bash
+python -m pip install jupyter_kernel_gateway ipykernel
+```
+
+## How It Works
+
+The Python tool starts a Jupyter Kernel Gateway process locally, which manages an IPython kernel. All code execution goes through the gateway's REST and WebSocket APIs.
+
+Startup flow:
+1. Spawn `python -m kernel_gateway` on a random available port
+2. Wait for gateway to become ready (`GET /api/kernelspecs`)
+3. Create a kernel (`POST /api/kernels`)
+4. Connect WebSocket for execution messages
+5. Run prelude code (helper functions)
+
+## External Gateway Support
+
+Instead of spawning a local gateway, you can connect to an already-running Jupyter Kernel Gateway:
+
+```bash
+# Connect to external gateway
+export OMP_PYTHON_GATEWAY_URL="http://127.0.0.1:8888"
+
+# Optional: auth token if gateway requires it (KG_AUTH_TOKEN)
+export OMP_PYTHON_GATEWAY_TOKEN="your-token-here"
+```
+
+When `OMP_PYTHON_GATEWAY_URL` is set:
+- No local gateway process is spawned
+- Kernels are created on the external gateway
+- The gateway process is not killed on shutdown
+- Availability check uses `/api/kernelspecs` endpoint instead of local module check
+
+This is useful for:
+- Remote kernel execution
+- Shared kernel environments
+- Pre-configured gateway setups
+
+## Environment Propagation
+
+- The kernel inherits a filtered environment (explicit allowlist + denylist)
+- `PYTHONPATH` includes the working directory and any existing `PYTHONPATH` value
+- Virtual environments are detected via `VIRTUAL_ENV`, `.venv/`, or `venv/` and preferred when present
+
+## Kernel Modes
+
+Settings under `python` control exposure and reuse:
+- `toolMode`: `ipy-only` (default), `bash-only`, `both`
+- `kernelMode`: `session` (default, queued), `per-call`
+
+## Shell Bridge
+
+The Python prelude exposes `bash()` which:
+- Sources the shell snapshot when `OMP_SHELL_SNAPSHOT` is set
+- Runs via `bash -lc` when available, with OS fallbacks
+
+## Output Handling
+
+- Streams `stdout`/`stderr` as text
+- `image/png` display data renders inline in TUI
+- `application/json` display data renders as a collapsible tree
+- `text/html` display data is converted to basic markdown
+
+## Troubleshooting
+
+- **Kernel unavailable**: Ensure `python` + `jupyter-kernel-gateway` + `ipykernel` are installed; the session will fall back to bash-only.
+- **External gateway unreachable**: Check the URL is correct and the gateway is running. If auth is required, set `OMP_PYTHON_GATEWAY_TOKEN`.
+- **IPC tracing**: Set `OMP_PYTHON_IPC_TRACE=1` to log kernel message flow.
+- **Stdin requests**: Interactive input is not supported; refactor code to avoid `input()` or provide data programmatically.

package/examples/hooks/snake.ts

@@ -3,7 +3,7 @@
  */
 
 import type { HookAPI } from "@oh-my-pi/pi-coding-agent";
-import { isArrowDown, isArrowLeft, isArrowRight, isArrowUp, isEscape, visibleWidth } from "@oh-my-pi/pi-tui";
+import { matchesKey, visibleWidth } from "@oh-my-pi/pi-tui";
 
 const GAME_WIDTH = 40;
 const GAME_HEIGHT = 15;
@@ -150,7 +150,7 @@ class SnakeComponent {
 	handleInput(data: string): void {
 		// If paused (resuming), wait for any key
 		if (this.paused) {
-			if (isEscape(data) || data === "q" || data === "Q") {
+			if (matchesKey(data, "escape") || matchesKey(data, "esc") || data === "q" || data === "Q") {
 				// Quit without clearing save
 				this.dispose();
 				this.onClose();
@@ -163,7 +163,7 @@ class SnakeComponent {
 		}
 
 		// ESC to pause and save
-		if (isEscape(data)) {
+		if (matchesKey(data, "escape") || matchesKey(data, "esc")) {
 			this.dispose();
 			this.onSave(this.state);
 			this.onClose();
@@ -179,13 +179,13 @@ class SnakeComponent {
 		}
 
 		// Arrow keys or WASD
-		if (isArrowUp(data) || data === "w" || data === "W") {
+		if (matchesKey(data, "up") || data === "w" || data === "W") {
 			if (this.state.direction !== "down") this.state.nextDirection = "up";
-		} else if (isArrowDown(data) || data === "s" || data === "S") {
+		} else if (matchesKey(data, "down") || data === "s" || data === "S") {
 			if (this.state.direction !== "up") this.state.nextDirection = "down";
-		} else if (isArrowRight(data) || data === "d" || data === "D") {
+		} else if (matchesKey(data, "right") || data === "d" || data === "D") {
 			if (this.state.direction !== "left") this.state.nextDirection = "right";
-		} else if (isArrowLeft(data) || data === "a" || data === "A") {
+		} else if (matchesKey(data, "left") || data === "a" || data === "A") {
 			if (this.state.direction !== "right") this.state.nextDirection = "left";
 		}
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "5.5.0",
+	"version": "5.6.7",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"ompConfig": {
@@ -39,10 +39,10 @@
 		"prepublishOnly": "bun run generate-template && bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-agent-core": "5.5.0",
-		"@oh-my-pi/pi-ai": "5.5.0",
-		"@oh-my-pi/pi-git-tool": "5.5.0",
-		"@oh-my-pi/pi-tui": "5.5.0",
+		"@oh-my-pi/pi-agent-core": "5.6.7",
+		"@oh-my-pi/pi-ai": "5.6.7",
+		"@oh-my-pi/pi-git-tool": "5.6.7",
+		"@oh-my-pi/pi-tui": "5.6.7",
 		"@openai/agents": "^0.3.7",
 		"@silvia-odwyer/photon-node": "^0.3.4",
 		"@sinclair/typebox": "^0.34.46",

package/src/bun-imports.d.ts

@@ -14,3 +14,9 @@ declare module "*.txt" {
 	const content: string;
 	export default content;
 }
+
+// Python files imported as text
+declare module "*.py" {
+	const content: string;
+	export default content;
+}

package/src/cli/args.ts

@@ -181,6 +181,12 @@ export function printHelp(): void {
 ${chalk.bold("Usage:")}
   ${APP_NAME} [options] [@files...] [messages...]
 
+${chalk.bold("Subcommands:")}
+  plugin    Manage plugins (install, uninstall, list, etc.)
+  update    Check for and install updates
+  config    Manage configuration settings
+  setup     Install dependencies for optional features
+
 ${chalk.bold("Options:")}
   --model <pattern>              Model to use (fuzzy match: "opus", "gpt-5.2", or "p-openai/gpt-5.2")
    --smol <id>                    Smol/fast model for lightweight tasks (or OMP_SMOL_MODEL env)
@@ -284,6 +290,7 @@ ${chalk.bold("Available Tools (all enabled by default):")}
   find       - Find files by glob pattern
   ls         - List directory contents
   lsp        - Language server protocol (code intelligence)
+  python     - Execute Python code (requires: ${APP_NAME} setup python)
   notebook   - Edit Jupyter notebooks
   task       - Launch sub-agents for parallel tasks
   web_fetch  - Fetch and process web pages

package/src/cli/setup-cli.ts

@@ -0,0 +1,231 @@
+/**
+ * Setup CLI command handler.
+ *
+ * Handles `omp setup <component>` to install dependencies for optional features.
+ */
+
+import chalk from "chalk";
+import { APP_NAME } from "../config";
+import { theme } from "../modes/interactive/theme/theme";
+
+export type SetupComponent = "python";
+
+export interface SetupCommandArgs {
+	component: SetupComponent;
+	flags: {
+		json?: boolean;
+		check?: boolean;
+	};
+}
+
+const VALID_COMPONENTS: SetupComponent[] = ["python"];
+
+const PYTHON_PACKAGES = ["jupyter_kernel_gateway", "ipykernel"];
+
+/**
+ * Parse setup subcommand arguments.
+ * Returns undefined if not a setup command.
+ */
+export function parseSetupArgs(args: string[]): SetupCommandArgs | undefined {
+	if (args.length === 0 || args[0] !== "setup") {
+		return undefined;
+	}
+
+	if (args.length < 2) {
+		console.error(chalk.red(`Usage: ${APP_NAME} setup <component>`));
+		console.error(`Valid components: ${VALID_COMPONENTS.join(", ")}`);
+		process.exit(1);
+	}
+
+	const component = args[1];
+	if (!VALID_COMPONENTS.includes(component as SetupComponent)) {
+		console.error(chalk.red(`Unknown component: ${component}`));
+		console.error(`Valid components: ${VALID_COMPONENTS.join(", ")}`);
+		process.exit(1);
+	}
+
+	const flags: SetupCommandArgs["flags"] = {};
+	for (let i = 2; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--json") {
+			flags.json = true;
+		} else if (arg === "--check" || arg === "-c") {
+			flags.check = true;
+		}
+	}
+
+	return {
+		component: component as SetupComponent,
+		flags,
+	};
+}
+
+interface PythonCheckResult {
+	available: boolean;
+	pythonPath?: string;
+	uvPath?: string;
+	pipPath?: string;
+	missingPackages: string[];
+	installedPackages: string[];
+}
+
+/**
+ * Check Python environment and kernel dependencies.
+ */
+async function checkPythonSetup(): Promise<PythonCheckResult> {
+	const result: PythonCheckResult = {
+		available: false,
+		missingPackages: [],
+		installedPackages: [],
+	};
+
+	const pythonPath = Bun.which("python") ?? Bun.which("python3");
+	if (!pythonPath) {
+		return result;
+	}
+	result.pythonPath = pythonPath;
+	result.uvPath = Bun.which("uv") ?? undefined;
+	result.pipPath = Bun.which("pip3") ?? Bun.which("pip") ?? undefined;
+
+	for (const pkg of PYTHON_PACKAGES) {
+		const moduleName = pkg === "jupyter_kernel_gateway" ? "kernel_gateway" : pkg;
+		const check = Bun.spawnSync(
+			[pythonPath, "-c", `import importlib.util; exit(0 if importlib.util.find_spec('${moduleName}') else 1)`],
+			{ stdin: "ignore", stdout: "pipe", stderr: "pipe" },
+		);
+		if (check.exitCode === 0) {
+			result.installedPackages.push(pkg);
+		} else {
+			result.missingPackages.push(pkg);
+		}
+	}
+
+	result.available = result.missingPackages.length === 0;
+	return result;
+}
+
+/**
+ * Install Python packages using uv (preferred) or pip.
+ */
+function installPythonPackages(packages: string[], uvPath?: string, pipPath?: string): boolean {
+	if (uvPath) {
+		console.log(chalk.dim(`Installing via uv: ${packages.join(" ")}`));
+		const result = Bun.spawnSync([uvPath, "pip", "install", ...packages], {
+			stdin: "ignore",
+			stdout: "inherit",
+			stderr: "inherit",
+		});
+		return result.exitCode === 0;
+	}
+
+	if (pipPath) {
+		console.log(chalk.dim(`Installing via pip: ${packages.join(" ")}`));
+		const result = Bun.spawnSync([pipPath, "install", ...packages], {
+			stdin: "ignore",
+			stdout: "inherit",
+			stderr: "inherit",
+		});
+		return result.exitCode === 0;
+	}
+
+	return false;
+}
+
+/**
+ * Run the setup command.
+ */
+export async function runSetupCommand(cmd: SetupCommandArgs): Promise<void> {
+	switch (cmd.component) {
+		case "python":
+			await handlePythonSetup(cmd.flags);
+			break;
+	}
+}
+
+async function handlePythonSetup(flags: { json?: boolean; check?: boolean }): Promise<void> {
+	const check = await checkPythonSetup();
+
+	if (flags.json) {
+		console.log(JSON.stringify(check, null, 2));
+		if (!check.available) process.exit(1);
+		return;
+	}
+
+	if (!check.pythonPath) {
+		console.error(chalk.red(`${theme.status.error} Python not found`));
+		console.error(chalk.dim("Install Python 3.8+ and ensure it's in your PATH"));
+		process.exit(1);
+	}
+
+	console.log(chalk.dim(`Python: ${check.pythonPath}`));
+
+	if (check.uvPath) {
+		console.log(chalk.dim(`uv: ${check.uvPath}`));
+	} else if (check.pipPath) {
+		console.log(chalk.dim(`pip: ${check.pipPath}`));
+	}
+
+	if (check.installedPackages.length > 0) {
+		console.log(chalk.green(`${theme.status.success} Installed: ${check.installedPackages.join(", ")}`));
+	}
+
+	if (check.missingPackages.length === 0) {
+		console.log(chalk.green(`\n${theme.status.success} Python execution is ready`));
+		return;
+	}
+
+	console.log(chalk.yellow(`${theme.status.warning} Missing: ${check.missingPackages.join(", ")}`));
+
+	if (flags.check) {
+		process.exit(1);
+	}
+
+	if (!check.uvPath && !check.pipPath) {
+		console.error(chalk.red(`\n${theme.status.error} No package manager found`));
+		console.error(chalk.dim("Install uv (recommended) or pip:"));
+		console.error(chalk.dim("  curl -LsSf https://astral.sh/uv/install.sh | sh"));
+		process.exit(1);
+	}
+
+	console.log("");
+	const success = installPythonPackages(check.missingPackages, check.uvPath, check.pipPath);
+
+	if (!success) {
+		console.error(chalk.red(`\n${theme.status.error} Installation failed`));
+		console.error(chalk.dim("Try installing manually:"));
+		console.error(chalk.dim(`  ${check.uvPath ? "uv pip" : "pip"} install ${check.missingPackages.join(" ")}`));
+		process.exit(1);
+	}
+
+	const recheck = await checkPythonSetup();
+	if (recheck.available) {
+		console.log(chalk.green(`\n${theme.status.success} Python execution is ready`));
+	} else {
+		console.error(chalk.red(`\n${theme.status.error} Setup incomplete`));
+		console.error(chalk.dim(`Still missing: ${recheck.missingPackages.join(", ")}`));
+		process.exit(1);
+	}
+}
+
+/**
+ * Print setup command help.
+ */
+export function printSetupHelp(): void {
+	console.log(`${chalk.bold(`${APP_NAME} setup`)} - Install dependencies for optional features
+
+${chalk.bold("Usage:")}
+  ${APP_NAME} setup <component> [options]
+
+${chalk.bold("Components:")}
+  python    Install Jupyter kernel dependencies for Python code execution
+            Packages: ${PYTHON_PACKAGES.join(", ")}
+
+${chalk.bold("Options:")}
+  -c, --check   Check if dependencies are installed without installing
+  --json        Output status as JSON
+
+${chalk.bold("Examples:")}
+  ${APP_NAME} setup python           Install Python execution dependencies
+  ${APP_NAME} setup python --check   Check if Python execution is available
+`);
+}

package/src/cli.ts

@@ -5,6 +5,8 @@
  *
  * Test with: npx tsx src/cli-new.ts [args...]
  */
+import { APP_NAME } from "./config";
 import { main } from "./main";
 
+process.title = APP_NAME;
 main(process.argv.slice(2));