@mariozechner/pi-coding-agent 0.38.0 → 0.39.1

package/examples/extensions/claude-rules.ts

@@ -61,7 +61,7 @@ export default function claudeRulesExtension(pi: ExtensionAPI) {
 	});
 
 	// Append available rules to system prompt
-	pi.on("before_agent_start", async () => {
+	pi.on("before_agent_start", async (event) => {
 		if (ruleFiles.length === 0) {
 			return;
 		}
@@ -69,7 +69,10 @@ export default function claudeRulesExtension(pi: ExtensionAPI) {
 		const rulesList = ruleFiles.map((f) => `- .claude/rules/${f}`).join("\n");
 
 		return {
-			systemPromptAppend: `
+			systemPrompt:
+				event.systemPrompt +
+				`
+
 ## Project Rules
 
 The following project rules are available in .claude/rules/:

package/examples/extensions/interactive-shell.ts

@@ -0,0 +1,196 @@
+/**
+ * Interactive Shell Commands Extension
+ *
+ * Enables running interactive commands (vim, git rebase -i, htop, etc.)
+ * with full terminal access. The TUI suspends while they run.
+ *
+ * Usage:
+ *   pi -e examples/extensions/interactive-shell.ts
+ *
+ *   !vim file.txt        # Auto-detected as interactive
+ *   !i any-command       # Force interactive mode with !i prefix
+ *   !git rebase -i HEAD~3
+ *   !htop
+ *
+ * Configuration via environment variables:
+ *   INTERACTIVE_COMMANDS - Additional commands (comma-separated)
+ *   INTERACTIVE_EXCLUDE  - Commands to exclude (comma-separated)
+ *
+ * Note: This only intercepts user `!` commands, not agent bash tool calls.
+ * If the agent runs an interactive command, it will fail (which is fine).
+ */
+
+import { spawnSync } from "node:child_process";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+// Default interactive commands - editors, pagers, git ops, TUIs
+const DEFAULT_INTERACTIVE_COMMANDS = [
+	// Editors
+	"vim",
+	"nvim",
+	"vi",
+	"nano",
+	"emacs",
+	"pico",
+	"micro",
+	"helix",
+	"hx",
+	"kak",
+	// Pagers
+	"less",
+	"more",
+	"most",
+	// Git interactive
+	"git commit",
+	"git rebase",
+	"git merge",
+	"git cherry-pick",
+	"git revert",
+	"git add -p",
+	"git add --patch",
+	"git add -i",
+	"git add --interactive",
+	"git stash -p",
+	"git stash --patch",
+	"git reset -p",
+	"git reset --patch",
+	"git checkout -p",
+	"git checkout --patch",
+	"git difftool",
+	"git mergetool",
+	// System monitors
+	"htop",
+	"top",
+	"btop",
+	"glances",
+	// File managers
+	"ranger",
+	"nnn",
+	"lf",
+	"mc",
+	"vifm",
+	// Git TUIs
+	"tig",
+	"lazygit",
+	"gitui",
+	// Fuzzy finders
+	"fzf",
+	"sk",
+	// Remote sessions
+	"ssh",
+	"telnet",
+	"mosh",
+	// Database clients
+	"psql",
+	"mysql",
+	"sqlite3",
+	"mongosh",
+	"redis-cli",
+	// Kubernetes/Docker
+	"kubectl edit",
+	"kubectl exec -it",
+	"docker exec -it",
+	"docker run -it",
+	// Other
+	"tmux",
+	"screen",
+	"ncdu",
+];
+
+function getInteractiveCommands(): string[] {
+	const additional =
+		process.env.INTERACTIVE_COMMANDS?.split(",")
+			.map((s) => s.trim())
+			.filter(Boolean) ?? [];
+	const excluded = new Set(process.env.INTERACTIVE_EXCLUDE?.split(",").map((s) => s.trim().toLowerCase()) ?? []);
+	return [...DEFAULT_INTERACTIVE_COMMANDS, ...additional].filter((cmd) => !excluded.has(cmd.toLowerCase()));
+}
+
+function isInteractiveCommand(command: string): boolean {
+	const trimmed = command.trim().toLowerCase();
+	const commands = getInteractiveCommands();
+
+	for (const cmd of commands) {
+		const cmdLower = cmd.toLowerCase();
+		// Match at start
+		if (trimmed === cmdLower || trimmed.startsWith(`${cmdLower} `) || trimmed.startsWith(`${cmdLower}\t`)) {
+			return true;
+		}
+		// Match after pipe: "cat file | less"
+		const pipeIdx = trimmed.lastIndexOf("|");
+		if (pipeIdx !== -1) {
+			const afterPipe = trimmed.slice(pipeIdx + 1).trim();
+			if (afterPipe === cmdLower || afterPipe.startsWith(`${cmdLower} `)) {
+				return true;
+			}
+		}
+	}
+	return false;
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("user_bash", async (event, ctx) => {
+		let command = event.command;
+		let forceInteractive = false;
+
+		// Check for !i prefix (command comes without the leading !)
+		// The prefix parsing happens before this event, so we check if command starts with "i "
+		if (command.startsWith("i ") || command.startsWith("i\t")) {
+			forceInteractive = true;
+			command = command.slice(2).trim();
+		}
+
+		const shouldBeInteractive = forceInteractive || isInteractiveCommand(command);
+		if (!shouldBeInteractive) {
+			return; // Let normal handling proceed
+		}
+
+		// No UI available (print mode, RPC, etc.)
+		if (!ctx.hasUI) {
+			return {
+				result: { output: "(interactive commands require TUI)", exitCode: 1, cancelled: false, truncated: false },
+			};
+		}
+
+		// Use ctx.ui.custom() to get TUI access, then run the command
+		const exitCode = await ctx.ui.custom<number | null>((tui, _theme, _kb, done) => {
+			// Stop TUI to release terminal
+			tui.stop();
+
+			// Clear screen
+			process.stdout.write("\x1b[2J\x1b[H");
+
+			// Run command with full terminal access
+			const shell = process.env.SHELL || "/bin/sh";
+			const result = spawnSync(shell, ["-c", command], {
+				stdio: "inherit",
+				env: process.env,
+			});
+
+			// Restart TUI
+			tui.start();
+			tui.requestRender(true);
+
+			// Signal completion
+			done(result.status);
+
+			// Return empty component (immediately disposed since done() was called)
+			return { render: () => [], invalidate: () => {} };
+		});
+
+		// Return result to prevent default bash handling
+		const output =
+			exitCode === 0
+				? "(interactive command completed successfully)"
+				: `(interactive command exited with code ${exitCode})`;
+
+		return {
+			result: {
+				output,
+				exitCode: exitCode ?? 1,
+				cancelled: false,
+				truncated: false,
+			},
+		};
+	});
+}

package/examples/extensions/mac-system-theme.ts

@@ -0,0 +1,45 @@
+/**
+ * Syncs pi theme with macOS system appearance (dark/light mode).
+ *
+ * Usage:
+ *   pi -e examples/extensions/mac-system-theme.ts
+ */
+
+import { execSync } from "node:child_process";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+function isDarkMode(): boolean {
+	try {
+		const result = execSync(
+			"osascript -e 'tell application \"System Events\" to tell appearance preferences to return dark mode'",
+			{ encoding: "utf-8" },
+		);
+		return result.trim() === "true";
+	} catch {
+		return false;
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	let intervalId: ReturnType<typeof setInterval> | null = null;
+
+	pi.on("session_start", (_event, ctx) => {
+		let currentTheme = isDarkMode() ? "dark" : "light";
+		ctx.ui.setTheme(currentTheme);
+
+		intervalId = setInterval(() => {
+			const newTheme = isDarkMode() ? "dark" : "light";
+			if (newTheme !== currentTheme) {
+				currentTheme = newTheme;
+				ctx.ui.setTheme(currentTheme);
+			}
+		}, 2000);
+	});
+
+	pi.on("session_shutdown", () => {
+		if (intervalId) {
+			clearInterval(intervalId);
+			intervalId = null;
+		}
+	});
+}

package/examples/extensions/overlay-test.ts

@@ -0,0 +1,145 @@
+/**
+ * Overlay Test - validates overlay compositing with inline text inputs
+ *
+ * Usage: pi --extension ./examples/extensions/overlay-test.ts
+ *
+ * Run /overlay-test to show a floating overlay with:
+ * - Inline text inputs within menu items
+ * - Edge case tests (wide chars, styled text, emoji)
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@mariozechner/pi-coding-agent";
+import { matchesKey, visibleWidth } from "@mariozechner/pi-tui";
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("overlay-test", {
+		description: "Test overlay rendering with edge cases",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			const result = await ctx.ui.custom<{ action: string; query?: string } | undefined>(
+				(_tui, theme, _keybindings, done) => new OverlayTestComponent(theme, done),
+				{ overlay: true },
+			);
+
+			if (result) {
+				const msg = result.query ? `${result.action}: "${result.query}"` : result.action;
+				ctx.ui.notify(msg, "info");
+			}
+		},
+	});
+}
+
+class OverlayTestComponent {
+	readonly width = 70;
+
+	private selected = 0;
+	private items = [
+		{ label: "Search", hasInput: true, text: "", cursor: 0 },
+		{ label: "Run", hasInput: true, text: "", cursor: 0 },
+		{ label: "Settings", hasInput: false, text: "", cursor: 0 },
+		{ label: "Cancel", hasInput: false, text: "", cursor: 0 },
+	];
+
+	constructor(
+		private theme: Theme,
+		private done: (result: { action: string; query?: string } | undefined) => void,
+	) {}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape")) {
+			this.done(undefined);
+			return;
+		}
+
+		const current = this.items[this.selected]!;
+
+		if (matchesKey(data, "return")) {
+			this.done({ action: current.label, query: current.hasInput ? current.text : undefined });
+			return;
+		}
+
+		if (matchesKey(data, "up")) {
+			this.selected = Math.max(0, this.selected - 1);
+		} else if (matchesKey(data, "down")) {
+			this.selected = Math.min(this.items.length - 1, this.selected + 1);
+		} else if (current.hasInput) {
+			if (matchesKey(data, "backspace")) {
+				if (current.cursor > 0) {
+					current.text = current.text.slice(0, current.cursor - 1) + current.text.slice(current.cursor);
+					current.cursor--;
+				}
+			} else if (matchesKey(data, "left")) {
+				current.cursor = Math.max(0, current.cursor - 1);
+			} else if (matchesKey(data, "right")) {
+				current.cursor = Math.min(current.text.length, current.cursor + 1);
+			} else if (data.length === 1 && data.charCodeAt(0) >= 32) {
+				current.text = current.text.slice(0, current.cursor) + data + current.text.slice(current.cursor);
+				current.cursor++;
+			}
+		}
+	}
+
+	render(_width: number): string[] {
+		const w = this.width;
+		const th = this.theme;
+		const innerW = w - 2;
+		const lines: string[] = [];
+
+		const pad = (s: string, len: number) => {
+			const vis = visibleWidth(s);
+			return s + " ".repeat(Math.max(0, len - vis));
+		};
+
+		const row = (content: string) => th.fg("border", "│") + pad(content, innerW) + th.fg("border", "│");
+
+		lines.push(th.fg("border", `╭${"─".repeat(innerW)}╮`));
+		lines.push(row(` ${th.fg("accent", "🧪 Overlay Test")}`));
+		lines.push(row(""));
+
+		// Edge cases - full width lines to test compositing at boundaries
+		lines.push(row(` ${th.fg("dim", "─── Edge Cases (borders should align) ───")}`));
+		lines.push(row(` Wide: ${th.fg("warning", "中文日本語한글テスト漢字繁體简体ひらがなカタカナ가나다라마바")}`));
+		lines.push(
+			row(
+				` Styled: ${th.fg("error", "RED")} ${th.fg("success", "GREEN")} ${th.fg("warning", "YELLOW")} ${th.fg("accent", "ACCENT")} ${th.fg("dim", "DIM")} ${th.fg("error", "more")} ${th.fg("success", "colors")}`,
+			),
+		);
+		lines.push(row(" Emoji: 👨‍👩‍👧‍👦 🇯🇵 🚀 💻 🎉 🔥 😀 🎯 🌟 💡 🎨 🔧 📦 🏆 🌈 🎪 🎭 🎬 🎮 🎲"));
+		lines.push(row(""));
+
+		// Menu with inline inputs
+		lines.push(row(` ${th.fg("dim", "─── Actions ───")}`));
+
+		for (let i = 0; i < this.items.length; i++) {
+			const item = this.items[i]!;
+			const isSelected = i === this.selected;
+			const prefix = isSelected ? " ▶ " : "   ";
+
+			let content: string;
+			if (item.hasInput) {
+				const label = isSelected ? th.fg("accent", `${item.label}:`) : th.fg("text", `${item.label}:`);
+
+				let inputDisplay = item.text;
+				if (isSelected) {
+					const before = inputDisplay.slice(0, item.cursor);
+					const cursorChar = item.cursor < inputDisplay.length ? inputDisplay[item.cursor] : " ";
+					const after = inputDisplay.slice(item.cursor + 1);
+					inputDisplay = `${before}\x1b[7m${cursorChar}\x1b[27m${after}`;
+				}
+				content = `${prefix + label} ${inputDisplay}`;
+			} else {
+				content = prefix + (isSelected ? th.fg("accent", item.label) : th.fg("text", item.label));
+			}
+
+			lines.push(row(content));
+		}
+
+		lines.push(row(""));
+		lines.push(row(` ${th.fg("dim", "↑↓ navigate • type to input • Enter select • Esc cancel")}`));
+		lines.push(th.fg("border", `╰${"─".repeat(innerW)}╯`));
+
+		return lines;
+	}
+
+	invalidate(): void {}
+	dispose(): void {}
+}

package/examples/extensions/pirate.ts

@@ -1,8 +1,8 @@
 /**
  * Pirate Extension
  *
- * Demonstrates using systemPromptAppend in before_agent_start to dynamically
- * modify the system prompt based on extension state.
+ * Demonstrates modifying the system prompt in before_agent_start to dynamically
+ * change agent behavior based on extension state.
  *
  * Usage:
  * 1. Copy this file to ~/.pi/agent/extensions/ or your project's .pi/extensions/
@@ -25,10 +25,13 @@ export default function pirateExtension(pi: ExtensionAPI) {
 	});
 
 	// Append to system prompt when pirate mode is enabled
-	pi.on("before_agent_start", async () => {
+	pi.on("before_agent_start", async (event) => {
 		if (pirateMode) {
 			return {
-				systemPromptAppend: `
+				systemPrompt:
+					event.systemPrompt +
+					`
+
 IMPORTANT: You are now in PIRATE MODE. You must:
 - Speak like a stereotypical pirate in all responses
 - Use phrases like "Arrr!", "Ahoy!", "Shiver me timbers!", "Avast!", "Ye scurvy dog!"

package/examples/extensions/preset.ts

@@ -345,10 +345,10 @@ export default function presetExtension(pi: ExtensionAPI) {
 	});
 
 	// Inject preset instructions into system prompt
-	pi.on("before_agent_start", async () => {
+	pi.on("before_agent_start", async (event) => {
 		if (activePreset?.instructions) {
 			return {
-				systemPromptAppend: activePreset.instructions,
+				systemPrompt: `${event.systemPrompt}\n\n${activePreset.instructions}`,
 			};
 		}
 	});

package/examples/extensions/ssh.ts

@@ -0,0 +1,220 @@
+/**
+ * SSH Remote Execution Example
+ *
+ * Demonstrates delegating tool operations to a remote machine via SSH.
+ * When --ssh is provided, read/write/edit/bash run on the remote.
+ *
+ * Usage:
+ *   pi -e ./ssh.ts --ssh user@host
+ *   pi -e ./ssh.ts --ssh user@host:/remote/path
+ *
+ * Requirements:
+ *   - SSH key-based auth (no password prompts)
+ *   - bash on remote
+ */
+
+import { spawn } from "node:child_process";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import {
+	type BashOperations,
+	createBashTool,
+	createEditTool,
+	createReadTool,
+	createWriteTool,
+	type EditOperations,
+	type ReadOperations,
+	type WriteOperations,
+} from "@mariozechner/pi-coding-agent";
+
+function sshExec(remote: string, command: string): Promise<Buffer> {
+	return new Promise((resolve, reject) => {
+		const child = spawn("ssh", [remote, command], { stdio: ["ignore", "pipe", "pipe"] });
+		const chunks: Buffer[] = [];
+		const errChunks: Buffer[] = [];
+		child.stdout.on("data", (data) => chunks.push(data));
+		child.stderr.on("data", (data) => errChunks.push(data));
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code !== 0) {
+				reject(new Error(`SSH failed (${code}): ${Buffer.concat(errChunks).toString()}`));
+			} else {
+				resolve(Buffer.concat(chunks));
+			}
+		});
+	});
+}
+
+function createRemoteReadOps(remote: string, remoteCwd: string, localCwd: string): ReadOperations {
+	const toRemote = (p: string) => p.replace(localCwd, remoteCwd);
+	return {
+		readFile: (p) => sshExec(remote, `cat ${JSON.stringify(toRemote(p))}`),
+		access: (p) => sshExec(remote, `test -r ${JSON.stringify(toRemote(p))}`).then(() => {}),
+		detectImageMimeType: async (p) => {
+			try {
+				const r = await sshExec(remote, `file --mime-type -b ${JSON.stringify(toRemote(p))}`);
+				const m = r.toString().trim();
+				return ["image/jpeg", "image/png", "image/gif", "image/webp"].includes(m) ? m : null;
+			} catch {
+				return null;
+			}
+		},
+	};
+}
+
+function createRemoteWriteOps(remote: string, remoteCwd: string, localCwd: string): WriteOperations {
+	const toRemote = (p: string) => p.replace(localCwd, remoteCwd);
+	return {
+		writeFile: async (p, content) => {
+			const b64 = Buffer.from(content).toString("base64");
+			await sshExec(remote, `echo ${JSON.stringify(b64)} | base64 -d > ${JSON.stringify(toRemote(p))}`);
+		},
+		mkdir: (dir) => sshExec(remote, `mkdir -p ${JSON.stringify(toRemote(dir))}`).then(() => {}),
+	};
+}
+
+function createRemoteEditOps(remote: string, remoteCwd: string, localCwd: string): EditOperations {
+	const r = createRemoteReadOps(remote, remoteCwd, localCwd);
+	const w = createRemoteWriteOps(remote, remoteCwd, localCwd);
+	return { readFile: r.readFile, access: r.access, writeFile: w.writeFile };
+}
+
+function createRemoteBashOps(remote: string, remoteCwd: string, localCwd: string): BashOperations {
+	const toRemote = (p: string) => p.replace(localCwd, remoteCwd);
+	return {
+		exec: (command, cwd, { onData, signal, timeout }) =>
+			new Promise((resolve, reject) => {
+				const cmd = `cd ${JSON.stringify(toRemote(cwd))} && ${command}`;
+				const child = spawn("ssh", [remote, cmd], { stdio: ["ignore", "pipe", "pipe"] });
+				let timedOut = false;
+				const timer = timeout
+					? setTimeout(() => {
+							timedOut = true;
+							child.kill();
+						}, timeout * 1000)
+					: undefined;
+				child.stdout.on("data", onData);
+				child.stderr.on("data", onData);
+				child.on("error", (e) => {
+					if (timer) clearTimeout(timer);
+					reject(e);
+				});
+				const onAbort = () => child.kill();
+				signal?.addEventListener("abort", onAbort, { once: true });
+				child.on("close", (code) => {
+					if (timer) clearTimeout(timer);
+					signal?.removeEventListener("abort", onAbort);
+					if (signal?.aborted) reject(new Error("aborted"));
+					else if (timedOut) reject(new Error(`timeout:${timeout}`));
+					else resolve({ exitCode: code });
+				});
+			}),
+	};
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerFlag("ssh", { description: "SSH remote: user@host or user@host:/path", type: "string" });
+
+	const localCwd = process.cwd();
+	const localRead = createReadTool(localCwd);
+	const localWrite = createWriteTool(localCwd);
+	const localEdit = createEditTool(localCwd);
+	const localBash = createBashTool(localCwd);
+
+	// Resolved lazily on session_start (CLI flags not available during factory)
+	let resolvedSsh: { remote: string; remoteCwd: string } | null = null;
+
+	const getSsh = () => resolvedSsh;
+
+	pi.registerTool({
+		...localRead,
+		async execute(id, params, onUpdate, _ctx, signal) {
+			const ssh = getSsh();
+			if (ssh) {
+				const tool = createReadTool(localCwd, {
+					operations: createRemoteReadOps(ssh.remote, ssh.remoteCwd, localCwd),
+				});
+				return tool.execute(id, params, signal, onUpdate);
+			}
+			return localRead.execute(id, params, signal, onUpdate);
+		},
+	});
+
+	pi.registerTool({
+		...localWrite,
+		async execute(id, params, onUpdate, _ctx, signal) {
+			const ssh = getSsh();
+			if (ssh) {
+				const tool = createWriteTool(localCwd, {
+					operations: createRemoteWriteOps(ssh.remote, ssh.remoteCwd, localCwd),
+				});
+				return tool.execute(id, params, signal, onUpdate);
+			}
+			return localWrite.execute(id, params, signal, onUpdate);
+		},
+	});
+
+	pi.registerTool({
+		...localEdit,
+		async execute(id, params, onUpdate, _ctx, signal) {
+			const ssh = getSsh();
+			if (ssh) {
+				const tool = createEditTool(localCwd, {
+					operations: createRemoteEditOps(ssh.remote, ssh.remoteCwd, localCwd),
+				});
+				return tool.execute(id, params, signal, onUpdate);
+			}
+			return localEdit.execute(id, params, signal, onUpdate);
+		},
+	});
+
+	pi.registerTool({
+		...localBash,
+		async execute(id, params, onUpdate, _ctx, signal) {
+			const ssh = getSsh();
+			if (ssh) {
+				const tool = createBashTool(localCwd, {
+					operations: createRemoteBashOps(ssh.remote, ssh.remoteCwd, localCwd),
+				});
+				return tool.execute(id, params, signal, onUpdate);
+			}
+			return localBash.execute(id, params, signal, onUpdate);
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		// Resolve SSH config now that CLI flags are available
+		const arg = pi.getFlag("ssh") as string | undefined;
+		if (arg) {
+			if (arg.includes(":")) {
+				const [remote, path] = arg.split(":");
+				resolvedSsh = { remote, remoteCwd: path };
+			} else {
+				// No path given, evaluate pwd on remote
+				const remote = arg;
+				const pwd = (await sshExec(remote, "pwd")).toString().trim();
+				resolvedSsh = { remote, remoteCwd: pwd };
+			}
+			ctx.ui.setStatus("ssh", ctx.ui.theme.fg("accent", `SSH: ${resolvedSsh.remote}:${resolvedSsh.remoteCwd}`));
+			ctx.ui.notify(`SSH mode: ${resolvedSsh.remote}:${resolvedSsh.remoteCwd}`, "info");
+		}
+	});
+
+	// Handle user ! commands via SSH
+	pi.on("user_bash", (_event) => {
+		const ssh = getSsh();
+		if (!ssh) return; // No SSH, use local execution
+		return { operations: createRemoteBashOps(ssh.remote, ssh.remoteCwd, localCwd) };
+	});
+
+	// Replace local cwd with remote cwd in system prompt
+	pi.on("before_agent_start", async (event) => {
+		const ssh = getSsh();
+		if (ssh) {
+			const modified = event.systemPrompt.replace(
+				`Current working directory: ${localCwd}`,
+				`Current working directory: ${ssh.remoteCwd} (via SSH: ${ssh.remote})`,
+			);
+			return { systemPrompt: modified };
+		}
+	});
+}