@mariozechner/pi-coding-agent 0.37.8 → 0.39.0

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,25 @@
+/**
+ * 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 {
+		execSync("defaults read -g AppleInterfaceStyle", { encoding: "utf-8" });
+		return true; // Returns "Dark" if dark mode
+	} catch {
+		return false; // Throws if light mode
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", (_event, ctx) => {
+		const theme = isDarkMode() ? "dark" : "light";
+		ctx.ui.setTheme(theme);
+	});
+}

package/examples/extensions/modal-editor.ts

@@ -0,0 +1,85 @@
+/**
+ * Modal Editor - vim-like modal editing example
+ *
+ * Usage: pi --extension ./examples/extensions/modal-editor.ts
+ *
+ * - Escape: insert → normal mode (in normal mode, aborts agent)
+ * - i: normal → insert mode
+ * - hjkl: navigation in normal mode
+ * - ctrl+c, ctrl+d, etc. work in both modes
+ */
+
+import { CustomEditor, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+
+// Normal mode key mappings: key -> escape sequence (or null for mode switch)
+const NORMAL_KEYS: Record<string, string | null> = {
+	h: "\x1b[D", // left
+	j: "\x1b[B", // down
+	k: "\x1b[A", // up
+	l: "\x1b[C", // right
+	"0": "\x01", // line start
+	$: "\x05", // line end
+	x: "\x1b[3~", // delete char
+	i: null, // insert mode
+	a: null, // append (insert + right)
+};
+
+class ModalEditor extends CustomEditor {
+	private mode: "normal" | "insert" = "insert";
+
+	handleInput(data: string): void {
+		// Escape toggles to normal mode, or passes through for app handling
+		if (matchesKey(data, "escape")) {
+			if (this.mode === "insert") {
+				this.mode = "normal";
+			} else {
+				super.handleInput(data); // abort agent, etc.
+			}
+			return;
+		}
+
+		// Insert mode: pass everything through
+		if (this.mode === "insert") {
+			super.handleInput(data);
+			return;
+		}
+
+		// Normal mode: check mapped keys
+		if (data in NORMAL_KEYS) {
+			const seq = NORMAL_KEYS[data];
+			if (data === "i") {
+				this.mode = "insert";
+			} else if (data === "a") {
+				this.mode = "insert";
+				super.handleInput("\x1b[C"); // move right first
+			} else if (seq) {
+				super.handleInput(seq);
+			}
+			return;
+		}
+
+		// Pass control sequences (ctrl+c, etc.) to super, ignore printable chars
+		if (data.length === 1 && data.charCodeAt(0) >= 32) return;
+		super.handleInput(data);
+	}
+
+	render(width: number): string[] {
+		const lines = super.render(width);
+		if (lines.length === 0) return lines;
+
+		// Add mode indicator to bottom border
+		const label = this.mode === "normal" ? " NORMAL " : " INSERT ";
+		const last = lines.length - 1;
+		if (visibleWidth(lines[last]!) >= label.length) {
+			lines[last] = truncateToWidth(lines[last]!, width - label.length, "") + label;
+		}
+		return lines;
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", (_event, ctx) => {
+		ctx.ui.setEditorComponent((_tui, theme, kb) => new ModalEditor(theme, kb));
+	});
+}

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

@@ -206,7 +206,7 @@ export default function presetExtension(pi: ExtensionAPI) {
 			description: "Clear active preset, restore defaults",
 		});
 
-		const result = await ctx.ui.custom<string | null>((tui, theme, done) => {
+		const result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
 			const container = new Container();
 			container.addChild(new DynamicBorder((str) => theme.fg("accent", str)));
 
@@ -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/qna.ts

@@ -71,7 +71,7 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			// Run extraction with loader UI
-			const result = await ctx.ui.custom<string | null>((tui, theme, done) => {
+			const result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
 				const loader = new BorderedLoader(tui, theme, `Extracting questions using ${ctx.model!.id}...`);
 				loader.onAbort = () => done(null);
 

package/examples/extensions/rainbow-editor.ts

@@ -0,0 +1,95 @@
+/**
+ * Rainbow Editor - highlights "ultrathink" with animated shine effect
+ *
+ * Usage: pi --extension ./examples/extensions/rainbow-editor.ts
+ */
+
+import { CustomEditor, type ExtensionAPI, type KeybindingsManager } from "@mariozechner/pi-coding-agent";
+import type { EditorTheme, TUI } from "@mariozechner/pi-tui";
+
+// Base colors (coral → yellow → green → teal → blue → purple → pink)
+const COLORS: [number, number, number][] = [
+	[233, 137, 115], // coral
+	[228, 186, 103], // yellow
+	[141, 192, 122], // green
+	[102, 194, 179], // teal
+	[121, 157, 207], // blue
+	[157, 134, 195], // purple
+	[206, 130, 172], // pink
+];
+const RESET = "\x1b[0m";
+
+function brighten(rgb: [number, number, number], factor: number): string {
+	const [r, g, b] = rgb.map((c) => Math.round(c + (255 - c) * factor));
+	return `\x1b[38;2;${r};${g};${b}m`;
+}
+
+function colorize(text: string, shinePos: number): string {
+	return (
+		[...text]
+			.map((c, i) => {
+				const baseColor = COLORS[i % COLORS.length]!;
+				// 3-letter shine: center bright, adjacent dimmer
+				let factor = 0;
+				if (shinePos >= 0) {
+					const dist = Math.abs(i - shinePos);
+					if (dist === 0) factor = 0.7;
+					else if (dist === 1) factor = 0.35;
+				}
+				return `${brighten(baseColor, factor)}${c}`;
+			})
+			.join("") + RESET
+	);
+}
+
+class RainbowEditor extends CustomEditor {
+	private animationTimer?: ReturnType<typeof setInterval>;
+	private tui: TUI;
+	private frame = 0;
+
+	constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) {
+		super(theme, keybindings);
+		this.tui = tui;
+	}
+
+	private hasUltrathink(): boolean {
+		return /ultrathink/i.test(this.getText());
+	}
+
+	private startAnimation(): void {
+		if (this.animationTimer) return;
+		this.animationTimer = setInterval(() => {
+			this.frame++;
+			this.tui.requestRender();
+		}, 60);
+	}
+
+	private stopAnimation(): void {
+		if (this.animationTimer) {
+			clearInterval(this.animationTimer);
+			this.animationTimer = undefined;
+		}
+	}
+
+	handleInput(data: string): void {
+		super.handleInput(data);
+		if (this.hasUltrathink()) {
+			this.startAnimation();
+		} else {
+			this.stopAnimation();
+		}
+	}
+
+	render(width: number): string[] {
+		// Cycle: 10 shine positions + 10 pause frames
+		const cycle = this.frame % 20;
+		const shinePos = cycle < 10 ? cycle : -1; // -1 means no shine (pause)
+		return super.render(width).map((line) => line.replace(/ultrathink/gi, (m) => colorize(m, shinePos)));
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", (_event, ctx) => {
+		ctx.ui.setEditorComponent((tui, theme, kb) => new RainbowEditor(tui, theme, kb));
+	});
+}

package/examples/extensions/shutdown-command.ts

@@ -0,0 +1,63 @@
+/**
+ * Shutdown Command Extension
+ *
+ * Adds a /quit command that allows extensions to trigger clean shutdown.
+ * Demonstrates how extensions can use ctx.shutdown() to exit pi cleanly.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+export default function (pi: ExtensionAPI) {
+	// Register a /quit command that cleanly exits pi
+	pi.registerCommand("quit", {
+		description: "Exit pi cleanly",
+		handler: async (_args, ctx) => {
+			ctx.shutdown();
+		},
+	});
+
+	// You can also create a tool that shuts down after completing work
+	pi.registerTool({
+		name: "finish_and_exit",
+		label: "Finish and Exit",
+		description: "Complete a task and exit pi",
+		parameters: Type.Object({}),
+		async execute(_toolCallId, _params, _onUpdate, ctx, _signal) {
+			// Do any final work here...
+			// Request graceful shutdown (deferred until agent is idle)
+			ctx.shutdown();
+
+			// This return is sent to the LLM before shutdown occurs
+			return {
+				content: [{ type: "text", text: "Shutdown requested. Exiting after this response." }],
+				details: {},
+			};
+		},
+	});
+
+	// You could also create a more complex tool with parameters
+	pi.registerTool({
+		name: "deploy_and_exit",
+		label: "Deploy and Exit",
+		description: "Deploy the application and exit pi",
+		parameters: Type.Object({
+			environment: Type.String({ description: "Target environment (e.g., production, staging)" }),
+		}),
+		async execute(_toolCallId, params, onUpdate, ctx, _signal) {
+			onUpdate?.({ content: [{ type: "text", text: `Deploying to ${params.environment}...` }], details: {} });
+
+			// Example deployment logic
+			// const result = await pi.exec("npm", ["run", "deploy", params.environment], { signal });
+
+			// On success, request graceful shutdown
+			onUpdate?.({ content: [{ type: "text", text: "Deployment complete, exiting..." }], details: {} });
+			ctx.shutdown();
+
+			return {
+				content: [{ type: "text", text: "Done! Shutdown requested." }],
+				details: { environment: params.environment },
+			};
+		},
+	});
+}

package/examples/extensions/snake.ts

@@ -327,7 +327,7 @@ export default function (pi: ExtensionAPI) {
 				}
 			}
 
-			await ctx.ui.custom((tui, _theme, done) => {
+			await ctx.ui.custom((tui, _theme, _kb, done) => {
 				return new SnakeComponent(
 					tui,
 					() => done(undefined),