@mariozechner/pi-coding-agent 0.22.4 → 0.23.0

package/examples/custom-tools/todo.ts

@@ -0,0 +1,192 @@
+/**
+ * Todo Tool - Demonstrates state management via session entries
+ *
+ * This tool stores state in tool result details (not external files),
+ * which allows proper branching - when you branch, the todo state
+ * is automatically correct for that point in history.
+ *
+ * The onSession callback reconstructs state by scanning past tool results.
+ */
+
+import { Type } from "@mariozechner/pi-coding-agent";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Text } from "@mariozechner/pi-tui";
+import type { CustomAgentTool, CustomToolFactory, ToolSessionEvent } from "@mariozechner/pi-coding-agent";
+
+interface Todo {
+	id: number;
+	text: string;
+	done: boolean;
+}
+
+// State stored in tool result details
+interface TodoDetails {
+	action: "list" | "add" | "toggle" | "clear";
+	todos: Todo[];
+	nextId: number;
+	error?: string;
+}
+
+// Define schema separately for proper type inference
+const TodoParams = Type.Object({
+	action: StringEnum(["list", "add", "toggle", "clear"] as const),
+	text: Type.Optional(Type.String({ description: "Todo text (for add)" })),
+	id: Type.Optional(Type.Number({ description: "Todo ID (for toggle)" })),
+});
+
+const factory: CustomToolFactory = (_pi) => {
+	// In-memory state (reconstructed from session on load)
+	let todos: Todo[] = [];
+	let nextId = 1;
+
+	/**
+	 * Reconstruct state from session entries.
+	 * Scans tool results for this tool and applies them in order.
+	 */
+	const reconstructState = (event: ToolSessionEvent) => {
+		todos = [];
+		nextId = 1;
+
+		for (const entry of event.entries) {
+			if (entry.type !== "message") continue;
+			const msg = entry.message;
+
+			// Tool results have role "toolResult"
+			if (msg.role !== "toolResult") continue;
+			if (msg.toolName !== "todo") continue;
+
+			const details = msg.details as TodoDetails | undefined;
+			if (details) {
+				todos = details.todos;
+				nextId = details.nextId;
+			}
+		}
+	};
+
+	const tool: CustomAgentTool<typeof TodoParams, TodoDetails> = {
+		name: "todo",
+		label: "Todo",
+		description: "Manage a todo list. Actions: list, add (text), toggle (id), clear",
+		parameters: TodoParams,
+
+		// Called on session start/switch/branch/clear
+		onSession: reconstructState,
+
+		async execute(_toolCallId, params) {
+			switch (params.action) {
+				case "list":
+					return {
+						content: [{ type: "text", text: todos.length ? todos.map((t) => `[${t.done ? "x" : " "}] #${t.id}: ${t.text}`).join("\n") : "No todos" }],
+						details: { action: "list", todos: [...todos], nextId },
+					};
+
+				case "add":
+					if (!params.text) {
+						return {
+							content: [{ type: "text", text: "Error: text required for add" }],
+							details: { action: "add", todos: [...todos], nextId, error: "text required" },
+						};
+					}
+					const newTodo: Todo = { id: nextId++, text: params.text, done: false };
+					todos.push(newTodo);
+					return {
+						content: [{ type: "text", text: `Added todo #${newTodo.id}: ${newTodo.text}` }],
+						details: { action: "add", todos: [...todos], nextId },
+					};
+
+				case "toggle":
+					if (params.id === undefined) {
+						return {
+							content: [{ type: "text", text: "Error: id required for toggle" }],
+							details: { action: "toggle", todos: [...todos], nextId, error: "id required" },
+						};
+					}
+					const todo = todos.find((t) => t.id === params.id);
+					if (!todo) {
+						return {
+							content: [{ type: "text", text: `Todo #${params.id} not found` }],
+							details: { action: "toggle", todos: [...todos], nextId, error: `#${params.id} not found` },
+						};
+					}
+					todo.done = !todo.done;
+					return {
+						content: [{ type: "text", text: `Todo #${todo.id} ${todo.done ? "completed" : "uncompleted"}` }],
+						details: { action: "toggle", todos: [...todos], nextId },
+					};
+
+				case "clear":
+					const count = todos.length;
+					todos = [];
+					nextId = 1;
+					return {
+						content: [{ type: "text", text: `Cleared ${count} todos` }],
+						details: { action: "clear", todos: [], nextId: 1 },
+					};
+
+				default:
+					return {
+						content: [{ type: "text", text: `Unknown action: ${params.action}` }],
+						details: { action: "list", todos: [...todos], nextId, error: `unknown action: ${params.action}` },
+					};
+			}
+		},
+
+		renderCall(args, theme) {
+			let text = theme.fg("toolTitle", theme.bold("todo ")) + theme.fg("muted", args.action);
+			if (args.text) text += " " + theme.fg("dim", `"${args.text}"`);
+			if (args.id !== undefined) text += " " + theme.fg("accent", `#${args.id}`);
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme) {
+			const { details } = result;
+			if (!details) {
+				const text = result.content[0];
+				return new Text(text?.type === "text" ? text.text : "", 0, 0);
+			}
+
+			// Error
+			if (details.error) {
+				return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
+			}
+
+			const todoList = details.todos;
+
+			switch (details.action) {
+				case "list":
+					if (todoList.length === 0) {
+						return new Text(theme.fg("dim", "No todos"), 0, 0);
+					}
+					let listText = theme.fg("muted", `${todoList.length} todo(s):`);
+					const display = expanded ? todoList : todoList.slice(0, 5);
+					for (const t of display) {
+						const check = t.done ? theme.fg("success", "✓") : theme.fg("dim", "○");
+						const itemText = t.done ? theme.fg("dim", t.text) : theme.fg("muted", t.text);
+						listText += "\n" + check + " " + theme.fg("accent", `#${t.id}`) + " " + itemText;
+					}
+					if (!expanded && todoList.length > 5) {
+						listText += "\n" + theme.fg("dim", `... ${todoList.length - 5} more`);
+					}
+					return new Text(listText, 0, 0);
+
+				case "add": {
+					const added = todoList[todoList.length - 1];
+					return new Text(theme.fg("success", "✓ Added ") + theme.fg("accent", `#${added.id}`) + " " + theme.fg("muted", added.text), 0, 0);
+				}
+
+				case "toggle": {
+					const text = result.content[0];
+					const msg = text?.type === "text" ? text.text : "";
+					return new Text(theme.fg("success", "✓ ") + theme.fg("muted", msg), 0, 0);
+				}
+
+				case "clear":
+					return new Text(theme.fg("success", "✓ ") + theme.fg("muted", "Cleared all todos"), 0, 0);
+			}
+		},
+	};
+
+	return tool;
+};
+
+export default factory;

package/examples/hooks/README.md

@@ -0,0 +1,79 @@
+# Hooks Examples
+
+Example hooks for pi-coding-agent.
+
+## Examples
+
+### permission-gate.ts
+Prompts for confirmation before running dangerous bash commands (rm -rf, sudo, chmod 777, etc.).
+
+### git-checkpoint.ts
+Creates git stash checkpoints at each turn, allowing code restoration when branching.
+
+### protected-paths.ts
+Blocks writes to protected paths (.env, .git/, node_modules/).
+
+### file-trigger.ts
+Watches a trigger file and injects its contents into the conversation. Useful for external systems (CI, file watchers, webhooks) to send messages to the agent.
+
+## Usage
+
+```bash
+# Test directly
+pi --hook examples/hooks/permission-gate.ts
+
+# Or copy to hooks directory for persistent use
+cp permission-gate.ts ~/.pi/agent/hooks/
+```
+
+## Writing Hooks
+
+See [docs/hooks.md](../../docs/hooks.md) for full documentation.
+
+### Key Points
+
+**Hook structure:**
+```typescript
+import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+
+export default function (pi: HookAPI) {
+  pi.on("session", async (event, ctx) => {
+    // event.reason: "start" | "switch" | "clear"
+    // ctx.ui, ctx.exec, ctx.cwd, ctx.sessionFile, ctx.hasUI
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    // Can block tool execution
+    if (dangerous) {
+      return { block: true, reason: "Blocked" };
+    }
+    return undefined;
+  });
+
+  pi.on("tool_result", async (event, ctx) => {
+    // Can modify result
+    return { result: "modified result" };
+  });
+}
+```
+
+**Available events:**
+- `session` - startup, session switch, clear
+- `branch` - before branching (can skip conversation restore)
+- `agent_start` / `agent_end` - per user prompt
+- `turn_start` / `turn_end` - per LLM turn
+- `tool_call` - before tool execution (can block)
+- `tool_result` - after tool execution (can modify)
+
+**UI methods:**
+```typescript
+const choice = await ctx.ui.select("Title", ["Option A", "Option B"]);
+const confirmed = await ctx.ui.confirm("Title", "Are you sure?");
+const input = await ctx.ui.input("Title", "placeholder");
+ctx.ui.notify("Message", "info"); // or "warning", "error"
+```
+
+**Sending messages:**
+```typescript
+pi.send("Message to inject into conversation");
+```

package/examples/hooks/file-trigger.ts

@@ -0,0 +1,36 @@
+/**
+ * File Trigger Hook
+ *
+ * Watches a trigger file and injects its contents into the conversation.
+ * Useful for external systems to send messages to the agent.
+ *
+ * Usage:
+ *   echo "Run the tests" > /tmp/agent-trigger.txt
+ */
+
+import * as fs from "node:fs";
+import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+
+export default function (pi: HookAPI) {
+	pi.on("session", async (event, ctx) => {
+		if (event.reason !== "start") return;
+
+		const triggerFile = "/tmp/agent-trigger.txt";
+
+		fs.watch(triggerFile, () => {
+			try {
+				const content = fs.readFileSync(triggerFile, "utf-8").trim();
+				if (content) {
+					pi.send(`External trigger: ${content}`);
+					fs.writeFileSync(triggerFile, ""); // Clear after reading
+				}
+			} catch {
+				// File might not exist yet
+			}
+		});
+
+		if (ctx.hasUI) {
+			ctx.ui.notify(`Watching ${triggerFile}`, "info");
+		}
+	});
+}

package/examples/hooks/git-checkpoint.ts

@@ -0,0 +1,48 @@
+/**
+ * Git Checkpoint Hook
+ *
+ * Creates git stash checkpoints at each turn so /branch can restore code state.
+ * When branching, offers to restore code to that point in history.
+ */
+
+import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+
+export default function (pi: HookAPI) {
+	const checkpoints = new Map<number, string>();
+
+	pi.on("turn_start", async (event, ctx) => {
+		// Create a git stash entry before LLM makes changes
+		const { stdout } = await ctx.exec("git", ["stash", "create"]);
+		const ref = stdout.trim();
+		if (ref) {
+			checkpoints.set(event.turnIndex, ref);
+		}
+	});
+
+	pi.on("branch", async (event, ctx) => {
+		const ref = checkpoints.get(event.targetTurnIndex);
+		if (!ref) return undefined;
+
+		if (!ctx.hasUI) {
+			// In non-interactive mode, don't restore automatically
+			return undefined;
+		}
+
+		const choice = await ctx.ui.select("Restore code state?", [
+			"Yes, restore code to that point",
+			"No, keep current code",
+		]);
+
+		if (choice?.startsWith("Yes")) {
+			await ctx.exec("git", ["stash", "apply", ref]);
+			ctx.ui.notify("Code restored to checkpoint", "info");
+		}
+
+		return undefined;
+	});
+
+	pi.on("agent_end", async () => {
+		// Clear checkpoints after agent completes
+		checkpoints.clear();
+	});
+}

package/examples/hooks/permission-gate.ts

@@ -0,0 +1,38 @@
+/**
+ * Permission Gate Hook
+ *
+ * Prompts for confirmation before running potentially dangerous bash commands.
+ * Patterns checked: rm -rf, sudo, chmod/chown 777
+ */
+
+import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+
+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 "@mariozechner/pi-coding-agent/hooks";
+
+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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mariozechner/pi-coding-agent",
-	"version": "0.22.4",
+	"version": "0.23.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {
@@ -25,6 +25,7 @@
 	"files": [
 		"dist",
 		"docs",
+		"examples",
 		"CHANGELOG.md"
 	],
 	"scripts": {
@@ -32,16 +33,16 @@
 		"build": "tsgo -p tsconfig.build.json && chmod +x dist/cli.js && npm run copy-assets",
 		"build:binary": "npm run build && bun build --compile ./dist/cli.js --outfile dist/pi && npm run copy-binary-assets",
 		"copy-assets": "mkdir -p dist/modes/interactive/theme && cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/",
-		"copy-binary-assets": "cp package.json dist/ && cp README.md dist/ && cp CHANGELOG.md dist/ && mkdir -p dist/theme && cp src/modes/interactive/theme/*.json dist/theme/ && cp -r docs dist/",
+		"copy-binary-assets": "cp package.json dist/ && cp README.md dist/ && cp CHANGELOG.md dist/ && mkdir -p dist/theme && cp src/modes/interactive/theme/*.json dist/theme/ && cp -r docs dist/ && cp -r examples dist/",
 		"dev": "tsgo -p tsconfig.build.json --watch --preserveWatchOutput",
-		"check": "tsgo --noEmit",
+		"check": "tsgo --noEmit && tsc -p tsconfig.examples.json",
 		"test": "vitest --run",
 		"prepublishOnly": "npm run clean && npm run build"
 	},
 	"dependencies": {
-		"@mariozechner/pi-agent-core": "^0.22.4",
-		"@mariozechner/pi-ai": "^0.22.4",
-		"@mariozechner/pi-tui": "^0.22.4",
+		"@mariozechner/pi-agent-core": "^0.23.0",
+		"@mariozechner/pi-ai": "^0.23.0",
+		"@mariozechner/pi-tui": "^0.23.0",
 		"chalk": "^5.5.0",
 		"diff": "^8.0.2",
 		"glob": "^11.0.3",