@oh-my-pi/pi-coding-agent 1.337.0

package/examples/hooks/handoff.ts

@@ -0,0 +1,150 @@
+/**
+ * Handoff hook - transfer context to a new focused session
+ *
+ * Instead of compacting (which is lossy), handoff extracts what matters
+ * for your next task and creates a new session with a generated prompt.
+ *
+ * Usage:
+ *   /handoff now implement this for teams as well
+ *   /handoff execute phase one of the plan
+ *   /handoff check other places that need this fix
+ *
+ * The generated prompt appears as a draft in the editor for review/editing.
+ */
+
+import { complete, type Message } from "@oh-my-pi/pi-ai";
+import type { HookAPI, SessionEntry } from "@oh-my-pi/pi-coding-agent";
+import { BorderedLoader, convertToLlm, serializeConversation } from "@oh-my-pi/pi-coding-agent";
+
+const SYSTEM_PROMPT = `You are a context transfer assistant. Given a conversation history and the user's goal for a new thread, generate a focused prompt that:
+
+1. Summarizes relevant context from the conversation (decisions made, approaches taken, key findings)
+2. Lists any relevant files that were discussed or modified
+3. Clearly states the next task based on the user's goal
+4. Is self-contained - the new thread should be able to proceed without the old conversation
+
+Format your response as a prompt the user can send to start the new thread. Be concise but include all necessary context. Do not include any preamble like "Here's the prompt" - just output the prompt itself.
+
+Example output format:
+## Context
+We've been working on X. Key decisions:
+- Decision 1
+- Decision 2
+
+Files involved:
+- path/to/file1.ts
+- path/to/file2.ts
+
+## Task
+[Clear description of what to do next based on user's goal]`;
+
+export default function (pi: HookAPI) {
+	pi.registerCommand("handoff", {
+		description: "Transfer context to a new focused session",
+		handler: async (args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("handoff requires interactive mode", "error");
+				return;
+			}
+
+			if (!ctx.model) {
+				ctx.ui.notify("No model selected", "error");
+				return;
+			}
+
+			const goal = args.trim();
+			if (!goal) {
+				ctx.ui.notify("Usage: /handoff <goal for new thread>", "error");
+				return;
+			}
+
+			// Gather conversation context from current branch
+			const branch = ctx.sessionManager.getBranch();
+			const messages = branch
+				.filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
+				.map((entry) => entry.message);
+
+			if (messages.length === 0) {
+				ctx.ui.notify("No conversation to hand off", "error");
+				return;
+			}
+
+			// Convert to LLM format and serialize
+			const llmMessages = convertToLlm(messages);
+			const conversationText = serializeConversation(llmMessages);
+			const currentSessionFile = ctx.sessionManager.getSessionFile();
+
+			// Generate the handoff prompt with loader UI
+			const result = await ctx.ui.custom<string | null>((tui, theme, done) => {
+				const loader = new BorderedLoader(tui, theme, `Generating handoff prompt...`);
+				loader.onAbort = () => done(null);
+
+				const doGenerate = async () => {
+					const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
+
+					const userMessage: Message = {
+						role: "user",
+						content: [
+							{
+								type: "text",
+								text: `## Conversation History\n\n${conversationText}\n\n## User's Goal for New Thread\n\n${goal}`,
+							},
+						],
+						timestamp: Date.now(),
+					};
+
+					const response = await complete(
+						ctx.model!,
+						{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
+						{ apiKey, signal: loader.signal },
+					);
+
+					if (response.stopReason === "aborted") {
+						return null;
+					}
+
+					return response.content
+						.filter((c): c is { type: "text"; text: string } => c.type === "text")
+						.map((c) => c.text)
+						.join("\n");
+				};
+
+				doGenerate()
+					.then(done)
+					.catch((err) => {
+						console.error("Handoff generation failed:", err);
+						done(null);
+					});
+
+				return loader;
+			});
+
+			if (result === null) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+
+			// Let user edit the generated prompt
+			const editedPrompt = await ctx.ui.editor("Edit handoff prompt (ctrl+enter to submit, esc to cancel)", result);
+
+			if (editedPrompt === undefined) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+
+			// Create new session with parent tracking
+			const newSessionResult = await ctx.newSession({
+				parentSession: currentSessionFile,
+			});
+
+			if (newSessionResult.cancelled) {
+				ctx.ui.notify("New session cancelled", "info");
+				return;
+			}
+
+			// Set the edited prompt in the main editor for submission
+			ctx.ui.setEditorText(editedPrompt);
+			ctx.ui.notify("Handoff ready. Submit when ready.", "info");
+		},
+	});
+}

package/examples/hooks/permission-gate.ts

@@ -0,0 +1,34 @@
+/**
+ * Permission Gate Hook
+ *
+ * Prompts for confirmation before running potentially dangerous bash commands.
+ * Patterns checked: rm -rf, sudo, chmod/chown 777
+ */
+
+import type { HookAPI } from "@oh-my-pi/pi-coding-agent";
+
+export default function (pi: HookAPI) {
+	const dangerousPatterns = [/\brm\s+(-rf?|--recursive)/i, /\bsudo\b/i, /\b(chmod|chown)\b.*777/i];
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName !== "bash") return undefined;
+
+		const command = event.input.command as string;
+		const isDangerous = dangerousPatterns.some((p) => p.test(command));
+
+		if (isDangerous) {
+			if (!ctx.hasUI) {
+				// In non-interactive mode, block by default
+				return { block: true, reason: "Dangerous command blocked (no UI for confirmation)" };
+			}
+
+			const choice = await ctx.ui.select(`⚠️ Dangerous command:\n\n  ${command}\n\nAllow?`, ["Yes", "No"]);
+
+			if (choice !== "Yes") {
+				return { block: true, reason: "Blocked by user" };
+			}
+		}
+
+		return undefined;
+	});
+}

package/examples/hooks/protected-paths.ts

@@ -0,0 +1,30 @@
+/**
+ * Protected Paths Hook
+ *
+ * Blocks write and edit operations to protected paths.
+ * Useful for preventing accidental modifications to sensitive files.
+ */
+
+import type { HookAPI } from "@oh-my-pi/pi-coding-agent";
+
+export default function (pi: HookAPI) {
+	const protectedPaths = [".env", ".git/", "node_modules/"];
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName !== "write" && event.toolName !== "edit") {
+			return undefined;
+		}
+
+		const path = event.input.path as string;
+		const isProtected = protectedPaths.some((p) => path.includes(p));
+
+		if (isProtected) {
+			if (ctx.hasUI) {
+				ctx.ui.notify(`Blocked write to protected path: ${path}`, "warning");
+			}
+			return { block: true, reason: `Path "${path}" is protected` };
+		}
+
+		return undefined;
+	});
+}

package/examples/hooks/qna.ts

@@ -0,0 +1,119 @@
+/**
+ * Q&A extraction hook - extracts questions from assistant responses
+ *
+ * Demonstrates the "prompt generator" pattern:
+ * 1. /qna command gets the last assistant message
+ * 2. Shows a spinner while extracting (hides editor)
+ * 3. Loads the result into the editor for user to fill in answers
+ */
+
+import { complete, type UserMessage } from "@oh-my-pi/pi-ai";
+import type { HookAPI } from "@oh-my-pi/pi-coding-agent";
+import { BorderedLoader } from "@oh-my-pi/pi-coding-agent";
+
+const SYSTEM_PROMPT = `You are a question extractor. Given text from a conversation, extract any questions that need answering and format them for the user to fill in.
+
+Output format:
+- List each question on its own line, prefixed with "Q: "
+- After each question, add a blank line for the answer prefixed with "A: "
+- If no questions are found, output "No questions found in the last message."
+
+Example output:
+Q: What is your preferred database?
+A: 
+
+Q: Should we use TypeScript or JavaScript?
+A: 
+
+Keep questions in the order they appeared. Be concise.`;
+
+export default function (pi: HookAPI) {
+	pi.registerCommand("qna", {
+		description: "Extract questions from last assistant message into editor",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("qna requires interactive mode", "error");
+				return;
+			}
+
+			if (!ctx.model) {
+				ctx.ui.notify("No model selected", "error");
+				return;
+			}
+
+			// Find the last assistant message on the current branch
+			const branch = ctx.sessionManager.getBranch();
+			let lastAssistantText: string | undefined;
+
+			for (let i = branch.length - 1; i >= 0; i--) {
+				const entry = branch[i];
+				if (entry.type === "message") {
+					const msg = entry.message;
+					if ("role" in msg && msg.role === "assistant") {
+						if (msg.stopReason !== "stop") {
+							ctx.ui.notify(`Last assistant message incomplete (${msg.stopReason})`, "error");
+							return;
+						}
+						const textParts = msg.content
+							.filter((c): c is { type: "text"; text: string } => c.type === "text")
+							.map((c) => c.text);
+						if (textParts.length > 0) {
+							lastAssistantText = textParts.join("\n");
+							break;
+						}
+					}
+				}
+			}
+
+			if (!lastAssistantText) {
+				ctx.ui.notify("No assistant messages found", "error");
+				return;
+			}
+
+			// Run extraction with loader UI
+			const result = await ctx.ui.custom<string | null>((tui, theme, done) => {
+				const loader = new BorderedLoader(tui, theme, `Extracting questions using ${ctx.model!.id}...`);
+				loader.onAbort = () => done(null);
+
+				// Do the work
+				const doExtract = async () => {
+					const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
+					const userMessage: UserMessage = {
+						role: "user",
+						content: [{ type: "text", text: lastAssistantText! }],
+						timestamp: Date.now(),
+					};
+
+					const response = await complete(
+						ctx.model!,
+						{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
+						{ apiKey, signal: loader.signal },
+					);
+
+					if (response.stopReason === "aborted") {
+						return null;
+					}
+
+					return response.content
+						.filter((c): c is { type: "text"; text: string } => c.type === "text")
+						.map((c) => c.text)
+						.join("\n");
+				};
+
+				doExtract()
+					.then(done)
+					.catch(() => done(null));
+
+				return loader;
+			});
+
+			if (result === null) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+
+			ctx.ui.setEditorText(result);
+			ctx.ui.notify("Questions loaded. Edit and submit when ready.", "info");
+		},
+	});
+}

package/examples/hooks/snake.ts

@@ -0,0 +1,343 @@
+/**
+ * Snake game hook - play snake with /snake command
+ */
+
+import type { HookAPI } from "@oh-my-pi/pi-coding-agent";
+import { isArrowDown, isArrowLeft, isArrowRight, isArrowUp, isEscape, visibleWidth } from "@oh-my-pi/pi-tui";
+
+const GAME_WIDTH = 40;
+const GAME_HEIGHT = 15;
+const TICK_MS = 100;
+
+type Direction = "up" | "down" | "left" | "right";
+type Point = { x: number; y: number };
+
+interface GameState {
+	snake: Point[];
+	food: Point;
+	direction: Direction;
+	nextDirection: Direction;
+	score: number;
+	gameOver: boolean;
+	highScore: number;
+}
+
+function createInitialState(): GameState {
+	const startX = Math.floor(GAME_WIDTH / 2);
+	const startY = Math.floor(GAME_HEIGHT / 2);
+	return {
+		snake: [
+			{ x: startX, y: startY },
+			{ x: startX - 1, y: startY },
+			{ x: startX - 2, y: startY },
+		],
+		food: spawnFood([{ x: startX, y: startY }]),
+		direction: "right",
+		nextDirection: "right",
+		score: 0,
+		gameOver: false,
+		highScore: 0,
+	};
+}
+
+function spawnFood(snake: Point[]): Point {
+	let food: Point;
+	do {
+		food = {
+			x: Math.floor(Math.random() * GAME_WIDTH),
+			y: Math.floor(Math.random() * GAME_HEIGHT),
+		};
+	} while (snake.some((s) => s.x === food.x && s.y === food.y));
+	return food;
+}
+
+class SnakeComponent {
+	private state: GameState;
+	private interval: ReturnType<typeof setInterval> | null = null;
+	private onClose: () => void;
+	private onSave: (state: GameState | null) => void;
+	private tui: { requestRender: () => void };
+	private cachedLines: string[] = [];
+	private cachedWidth = 0;
+	private version = 0;
+	private cachedVersion = -1;
+	private paused: boolean;
+
+	constructor(
+		tui: { requestRender: () => void },
+		onClose: () => void,
+		onSave: (state: GameState | null) => void,
+		savedState?: GameState,
+	) {
+		this.tui = tui;
+		if (savedState && !savedState.gameOver) {
+			// Resume from saved state, start paused
+			this.state = savedState;
+			this.paused = true;
+		} else {
+			// New game or saved game was over
+			this.state = createInitialState();
+			if (savedState) {
+				this.state.highScore = savedState.highScore;
+			}
+			this.paused = false;
+			this.startGame();
+		}
+		this.onClose = onClose;
+		this.onSave = onSave;
+	}
+
+	private startGame(): void {
+		this.interval = setInterval(() => {
+			if (!this.state.gameOver) {
+				this.tick();
+				this.version++;
+				this.tui.requestRender();
+			}
+		}, TICK_MS);
+	}
+
+	private tick(): void {
+		// Apply queued direction change
+		this.state.direction = this.state.nextDirection;
+
+		// Calculate new head position
+		const head = this.state.snake[0];
+		let newHead: Point;
+
+		switch (this.state.direction) {
+			case "up":
+				newHead = { x: head.x, y: head.y - 1 };
+				break;
+			case "down":
+				newHead = { x: head.x, y: head.y + 1 };
+				break;
+			case "left":
+				newHead = { x: head.x - 1, y: head.y };
+				break;
+			case "right":
+				newHead = { x: head.x + 1, y: head.y };
+				break;
+		}
+
+		// Check wall collision
+		if (newHead.x < 0 || newHead.x >= GAME_WIDTH || newHead.y < 0 || newHead.y >= GAME_HEIGHT) {
+			this.state.gameOver = true;
+			return;
+		}
+
+		// Check self collision
+		if (this.state.snake.some((s) => s.x === newHead.x && s.y === newHead.y)) {
+			this.state.gameOver = true;
+			return;
+		}
+
+		// Move snake
+		this.state.snake.unshift(newHead);
+
+		// Check food collision
+		if (newHead.x === this.state.food.x && newHead.y === this.state.food.y) {
+			this.state.score += 10;
+			if (this.state.score > this.state.highScore) {
+				this.state.highScore = this.state.score;
+			}
+			this.state.food = spawnFood(this.state.snake);
+		} else {
+			this.state.snake.pop();
+		}
+	}
+
+	handleInput(data: string): void {
+		// If paused (resuming), wait for any key
+		if (this.paused) {
+			if (isEscape(data) || data === "q" || data === "Q") {
+				// Quit without clearing save
+				this.dispose();
+				this.onClose();
+				return;
+			}
+			// Any other key resumes
+			this.paused = false;
+			this.startGame();
+			return;
+		}
+
+		// ESC to pause and save
+		if (isEscape(data)) {
+			this.dispose();
+			this.onSave(this.state);
+			this.onClose();
+			return;
+		}
+
+		// Q to quit without saving (clears saved state)
+		if (data === "q" || data === "Q") {
+			this.dispose();
+			this.onSave(null); // Clear saved state
+			this.onClose();
+			return;
+		}
+
+		// Arrow keys or WASD
+		if (isArrowUp(data) || data === "w" || data === "W") {
+			if (this.state.direction !== "down") this.state.nextDirection = "up";
+		} else if (isArrowDown(data) || data === "s" || data === "S") {
+			if (this.state.direction !== "up") this.state.nextDirection = "down";
+		} else if (isArrowRight(data) || data === "d" || data === "D") {
+			if (this.state.direction !== "left") this.state.nextDirection = "right";
+		} else if (isArrowLeft(data) || data === "a" || data === "A") {
+			if (this.state.direction !== "right") this.state.nextDirection = "left";
+		}
+
+		// Restart on game over
+		if (this.state.gameOver && (data === "r" || data === "R" || data === " ")) {
+			const highScore = this.state.highScore;
+			this.state = createInitialState();
+			this.state.highScore = highScore;
+			this.onSave(null); // Clear saved state on restart
+			this.version++;
+			this.tui.requestRender();
+		}
+	}
+
+	invalidate(): void {
+		this.cachedWidth = 0;
+	}
+
+	render(width: number): string[] {
+		if (width === this.cachedWidth && this.cachedVersion === this.version) {
+			return this.cachedLines;
+		}
+
+		const lines: string[] = [];
+
+		// Each game cell is 2 chars wide to appear square (terminal cells are ~2:1 aspect)
+		const cellWidth = 2;
+		const effectiveWidth = Math.min(GAME_WIDTH, Math.floor((width - 4) / cellWidth));
+		const effectiveHeight = GAME_HEIGHT;
+
+		// Colors
+		const dim = (s: string) => `\x1b[2m${s}\x1b[22m`;
+		const green = (s: string) => `\x1b[32m${s}\x1b[0m`;
+		const red = (s: string) => `\x1b[31m${s}\x1b[0m`;
+		const yellow = (s: string) => `\x1b[33m${s}\x1b[0m`;
+		const bold = (s: string) => `\x1b[1m${s}\x1b[22m`;
+
+		const boxWidth = effectiveWidth * cellWidth;
+
+		// Helper to pad content inside box
+		const boxLine = (content: string) => {
+			const contentLen = visibleWidth(content);
+			const padding = Math.max(0, boxWidth - contentLen);
+			return dim(" │") + content + " ".repeat(padding) + dim("│");
+		};
+
+		// Top border
+		lines.push(this.padLine(dim(` ╭${"─".repeat(boxWidth)}╮`), width));
+
+		// Header with score
+		const scoreText = `Score: ${bold(yellow(String(this.state.score)))}`;
+		const highText = `High: ${bold(yellow(String(this.state.highScore)))}`;
+		const title = `${bold(green("SNAKE"))} │ ${scoreText} │ ${highText}`;
+		lines.push(this.padLine(boxLine(title), width));
+
+		// Separator
+		lines.push(this.padLine(dim(` ├${"─".repeat(boxWidth)}┤`), width));
+
+		// Game grid
+		for (let y = 0; y < effectiveHeight; y++) {
+			let row = "";
+			for (let x = 0; x < effectiveWidth; x++) {
+				const isHead = this.state.snake[0].x === x && this.state.snake[0].y === y;
+				const isBody = this.state.snake.slice(1).some((s) => s.x === x && s.y === y);
+				const isFood = this.state.food.x === x && this.state.food.y === y;
+
+				if (isHead) {
+					row += green("██"); // Snake head (2 chars)
+				} else if (isBody) {
+					row += green("▓▓"); // Snake body (2 chars)
+				} else if (isFood) {
+					row += red("◆ "); // Food (2 chars)
+				} else {
+					row += "  "; // Empty cell (2 spaces)
+				}
+			}
+			lines.push(this.padLine(dim(" │") + row + dim("│"), width));
+		}
+
+		// Separator
+		lines.push(this.padLine(dim(` ├${"─".repeat(boxWidth)}┤`), width));
+
+		// Footer
+		let footer: string;
+		if (this.paused) {
+			footer = `${yellow(bold("PAUSED"))} Press any key to continue, ${bold("Q")} to quit`;
+		} else if (this.state.gameOver) {
+			footer = `${red(bold("GAME OVER!"))} Press ${bold("R")} to restart, ${bold("Q")} to quit`;
+		} else {
+			footer = `↑↓←→ or WASD to move, ${bold("ESC")} pause, ${bold("Q")} quit`;
+		}
+		lines.push(this.padLine(boxLine(footer), width));
+
+		// Bottom border
+		lines.push(this.padLine(dim(` ╰${"─".repeat(boxWidth)}╯`), width));
+
+		this.cachedLines = lines;
+		this.cachedWidth = width;
+		this.cachedVersion = this.version;
+
+		return lines;
+	}
+
+	private padLine(line: string, width: number): string {
+		// Calculate visible length (strip ANSI codes)
+		const visibleLen = line.replace(/\x1b\[[0-9;]*m/g, "").length;
+		const padding = Math.max(0, width - visibleLen);
+		return line + " ".repeat(padding);
+	}
+
+	dispose(): void {
+		if (this.interval) {
+			clearInterval(this.interval);
+			this.interval = null;
+		}
+	}
+}
+
+const SNAKE_SAVE_TYPE = "snake-save";
+
+export default function (pi: HookAPI) {
+	pi.registerCommand("snake", {
+		description: "Play Snake!",
+
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("Snake requires interactive mode", "error");
+				return;
+			}
+
+			// Load saved state from session
+			const entries = ctx.sessionManager.getEntries();
+			let savedState: GameState | undefined;
+			for (let i = entries.length - 1; i >= 0; i--) {
+				const entry = entries[i];
+				if (entry.type === "custom" && entry.customType === SNAKE_SAVE_TYPE) {
+					savedState = entry.data as GameState;
+					break;
+				}
+			}
+
+			await ctx.ui.custom((tui, _theme, done) => {
+				return new SnakeComponent(
+					tui,
+					() => done(undefined),
+					(state) => {
+						// Save or clear state
+						pi.appendEntry(SNAKE_SAVE_TYPE, state);
+					},
+					savedState,
+				);
+			});
+		},
+	});
+}