@skaft/hamr 0.4.1

package/examples/extensions/timed-confirm.ts

@@ -0,0 +1,70 @@
+/**
+ * Example extension demonstrating timed dialogs with live countdown.
+ *
+ * Commands:
+ * - /timed - Shows confirm dialog that auto-cancels after 5 seconds with countdown
+ * - /timed-select - Shows select dialog that auto-cancels after 10 seconds with countdown
+ * - /timed-signal - Shows confirm using AbortSignal (manual approach)
+ */
+
+import type { ExtensionAPI } from "@hamr/coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	// Simple approach: use timeout option (recommended)
+	pi.registerCommand("timed", {
+		description: "Show a timed confirmation dialog (auto-cancels in 5s with countdown)",
+		handler: async (_args, ctx) => {
+			const confirmed = await ctx.ui.confirm(
+				"Timed Confirmation",
+				"This dialog will auto-cancel in 5 seconds. Confirm?",
+				{ timeout: 5000 },
+			);
+
+			if (confirmed) {
+				ctx.ui.notify("Confirmed by user!", "info");
+			} else {
+				ctx.ui.notify("Cancelled or timed out", "info");
+			}
+		},
+	});
+
+	pi.registerCommand("timed-select", {
+		description: "Show a timed select dialog (auto-cancels in 10s with countdown)",
+		handler: async (_args, ctx) => {
+			const choice = await ctx.ui.select("Pick an option", ["Option A", "Option B", "Option C"], { timeout: 10000 });
+
+			if (choice) {
+				ctx.ui.notify(`Selected: ${choice}`, "info");
+			} else {
+				ctx.ui.notify("Selection cancelled or timed out", "info");
+			}
+		},
+	});
+
+	// Manual approach: use AbortSignal for more control
+	pi.registerCommand("timed-signal", {
+		description: "Show a timed confirm using AbortSignal (manual approach)",
+		handler: async (_args, ctx) => {
+			const controller = new AbortController();
+			const timeoutId = setTimeout(() => controller.abort(), 5000);
+
+			ctx.ui.notify("Dialog will auto-cancel in 5 seconds...", "info");
+
+			const confirmed = await ctx.ui.confirm(
+				"Timed Confirmation",
+				"This dialog will auto-cancel in 5 seconds. Confirm?",
+				{ signal: controller.signal },
+			);
+
+			clearTimeout(timeoutId);
+
+			if (confirmed) {
+				ctx.ui.notify("Confirmed by user!", "info");
+			} else if (controller.signal.aborted) {
+				ctx.ui.notify("Dialog timed out (auto-cancelled)", "warning");
+			} else {
+				ctx.ui.notify("Cancelled by user", "info");
+			}
+		},
+	});
+}

package/examples/extensions/titlebar-spinner.ts

@@ -0,0 +1,58 @@
+/**
+ * Titlebar Spinner Extension
+ *
+ * Shows a braille spinner animation in the terminal title while the agent is working.
+ * Uses `ctx.ui.setTitle()` to update the terminal title via the extension API.
+ *
+ * Usage:
+ *   pi --extension examples/extensions/titlebar-spinner.ts
+ */
+
+import path from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@hamr/coding-agent";
+
+const BRAILLE_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+function getBaseTitle(pi: ExtensionAPI): string {
+	const cwd = path.basename(process.cwd());
+	const session = pi.getSessionName();
+	return session ? `π - ${session} - ${cwd}` : `π - ${cwd}`;
+}
+
+export default function (pi: ExtensionAPI) {
+	let timer: ReturnType<typeof setInterval> | null = null;
+	let frameIndex = 0;
+
+	function stopAnimation(ctx: ExtensionContext) {
+		if (timer) {
+			clearInterval(timer);
+			timer = null;
+		}
+		frameIndex = 0;
+		ctx.ui.setTitle(getBaseTitle(pi));
+	}
+
+	function startAnimation(ctx: ExtensionContext) {
+		stopAnimation(ctx);
+		timer = setInterval(() => {
+			const frame = BRAILLE_FRAMES[frameIndex % BRAILLE_FRAMES.length];
+			const cwd = path.basename(process.cwd());
+			const session = pi.getSessionName();
+			const title = session ? `${frame} π - ${session} - ${cwd}` : `${frame} π - ${cwd}`;
+			ctx.ui.setTitle(title);
+			frameIndex++;
+		}, 80);
+	}
+
+	pi.on("agent_start", async (_event, ctx) => {
+		startAnimation(ctx);
+	});
+
+	pi.on("agent_end", async (_event, ctx) => {
+		stopAnimation(ctx);
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		stopAnimation(ctx);
+	});
+}

package/examples/extensions/todo.ts

@@ -0,0 +1,297 @@
+/**
+ * Todo Extension - Demonstrates state management via session entries
+ *
+ * This extension:
+ * - Registers a `todo` tool for the LLM to manage todos
+ * - Registers a `/todos` command for users to view the list
+ *
+ * State is stored 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.
+ */
+
+import { StringEnum } from "@hamr/ai";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@hamr/coding-agent";
+import { matchesKey, Text, truncateToWidth } from "@hamr/tui";
+import { Type } from "typebox";
+
+interface Todo {
+	id: number;
+	text: string;
+	done: boolean;
+}
+
+interface TodoDetails {
+	action: "list" | "add" | "toggle" | "clear";
+	todos: Todo[];
+	nextId: number;
+	error?: string;
+}
+
+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)" })),
+});
+
+/**
+ * UI component for the /todos command
+ */
+class TodoListComponent {
+	private todos: Todo[];
+	private theme: Theme;
+	private onClose: () => void;
+	private cachedWidth?: number;
+	private cachedLines?: string[];
+
+	constructor(todos: Todo[], theme: Theme, onClose: () => void) {
+		this.todos = todos;
+		this.theme = theme;
+		this.onClose = onClose;
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+			this.onClose();
+		}
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) {
+			return this.cachedLines;
+		}
+
+		const lines: string[] = [];
+		const th = this.theme;
+
+		lines.push("");
+		const title = th.fg("accent", " Todos ");
+		const headerLine =
+			th.fg("borderMuted", "─".repeat(3)) + title + th.fg("borderMuted", "─".repeat(Math.max(0, width - 10)));
+		lines.push(truncateToWidth(headerLine, width));
+		lines.push("");
+
+		if (this.todos.length === 0) {
+			lines.push(truncateToWidth(`  ${th.fg("dim", "No todos yet. Ask the agent to add some!")}`, width));
+		} else {
+			const done = this.todos.filter((t) => t.done).length;
+			const total = this.todos.length;
+			lines.push(truncateToWidth(`  ${th.fg("muted", `${done}/${total} completed`)}`, width));
+			lines.push("");
+
+			for (const todo of this.todos) {
+				const check = todo.done ? th.fg("success", "✓") : th.fg("dim", "○");
+				const id = th.fg("accent", `#${todo.id}`);
+				const text = todo.done ? th.fg("dim", todo.text) : th.fg("text", todo.text);
+				lines.push(truncateToWidth(`  ${check} ${id} ${text}`, width));
+			}
+		}
+
+		lines.push("");
+		lines.push(truncateToWidth(`  ${th.fg("dim", "Press Escape to close")}`, width));
+		lines.push("");
+
+		this.cachedWidth = width;
+		this.cachedLines = lines;
+		return lines;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	// 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 = (ctx: ExtensionContext) => {
+		todos = [];
+		nextId = 1;
+
+		for (const entry of ctx.sessionManager.getBranch()) {
+			if (entry.type !== "message") continue;
+			const msg = entry.message;
+			if (msg.role !== "toolResult" || msg.toolName !== "todo") continue;
+
+			const details = msg.details as TodoDetails | undefined;
+			if (details) {
+				todos = details.todos;
+				nextId = details.nextId;
+			}
+		}
+	};
+
+	// Reconstruct state on session events
+	pi.on("session_start", async (_event, ctx) => reconstructState(ctx));
+	pi.on("session_tree", async (_event, ctx) => reconstructState(ctx));
+
+	// Register the todo tool for the LLM
+	pi.registerTool({
+		name: "todo",
+		label: "Todo",
+		description: "Manage a todo list. Actions: list, add (text), toggle (id), clear",
+		parameters: TodoParams,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			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 } as TodoDetails,
+					};
+
+				case "add": {
+					if (!params.text) {
+						return {
+							content: [{ type: "text", text: "Error: text required for add" }],
+							details: { action: "add", todos: [...todos], nextId, error: "text required" } as TodoDetails,
+						};
+					}
+					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 } as TodoDetails,
+					};
+				}
+
+				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" } as TodoDetails,
+						};
+					}
+					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`,
+							} as TodoDetails,
+						};
+					}
+					todo.done = !todo.done;
+					return {
+						content: [{ type: "text", text: `Todo #${todo.id} ${todo.done ? "completed" : "uncompleted"}` }],
+						details: { action: "toggle", todos: [...todos], nextId } as TodoDetails,
+					};
+				}
+
+				case "clear": {
+					const count = todos.length;
+					todos = [];
+					nextId = 1;
+					return {
+						content: [{ type: "text", text: `Cleared ${count} todos` }],
+						details: { action: "clear", todos: [], nextId: 1 } as TodoDetails,
+					};
+				}
+
+				default:
+					return {
+						content: [{ type: "text", text: `Unknown action: ${params.action}` }],
+						details: {
+							action: "list",
+							todos: [...todos],
+							nextId,
+							error: `unknown action: ${params.action}`,
+						} as TodoDetails,
+					};
+			}
+		},
+
+		renderCall(args, theme, _context) {
+			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, _context) {
+			const details = result.details as TodoDetails | undefined;
+			if (!details) {
+				const text = result.content[0];
+				return new Text(text?.type === "text" ? text.text : "", 0, 0);
+			}
+
+			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);
+			}
+		},
+	});
+
+	// Register the /todos command for users
+	pi.registerCommand("todos", {
+		description: "Show all todos on the current branch",
+		handler: async (_args, ctx) => {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("/todos requires interactive mode", "error");
+				return;
+			}
+
+			await ctx.ui.custom<void>((_tui, theme, _kb, done) => {
+				return new TodoListComponent(todos, theme, () => done());
+			});
+		},
+	});
+}

package/examples/extensions/tool-override.ts

@@ -0,0 +1,144 @@
+/**
+ * Tool Override Example - Demonstrates overriding built-in tools
+ *
+ * Extensions can register tools with the same name as built-in tools to replace them.
+ * This is useful for:
+ * - Adding logging or auditing to tool calls
+ * - Implementing access control or sandboxing
+ * - Routing tool calls to remote systems (e.g., pi-ssh-remote)
+ * - Modifying tool behavior for specific workflows
+ *
+ * This example overrides the `read` tool to:
+ * 1. Log all file access to a log file
+ * 2. Block access to sensitive paths (e.g., .env files)
+ * 3. Delegate to the original read implementation for allowed files
+ *
+ * Since no custom renderCall/renderResult are provided, the built-in renderer
+ * is used automatically (syntax highlighting, line numbers, truncation warnings).
+ *
+ * Usage:
+ *   pi -e ./tool-override.ts
+ */
+
+import type { TextContent } from "@hamr/ai";
+import { type ExtensionAPI, getAgentDir, withFileMutationQueue } from "@hamr/coding-agent";
+import { constants, readFileSync } from "fs";
+import { access, appendFile, readFile } from "fs/promises";
+import { join, resolve } from "path";
+import { Type } from "typebox";
+
+const LOG_FILE = join(getAgentDir(), "read-access.log");
+
+// Paths that are blocked from reading
+const BLOCKED_PATTERNS = [
+	/\.env$/,
+	/\.env\..+$/,
+	/secrets?\.(json|yaml|yml|toml)$/i,
+	/credentials?\.(json|yaml|yml|toml)$/i,
+	/\/\.ssh\//,
+	/\/\.aws\//,
+	/\/\.gnupg\//,
+];
+
+function isBlockedPath(path: string): boolean {
+	return BLOCKED_PATTERNS.some((pattern) => pattern.test(path));
+}
+
+async function logAccess(path: string, allowed: boolean, reason?: string) {
+	const timestamp = new Date().toISOString();
+	const status = allowed ? "ALLOWED" : "BLOCKED";
+	const msg = reason ? ` (${reason})` : "";
+	const line = `[${timestamp}] ${status}: ${path}${msg}\n`;
+
+	try {
+		await withFileMutationQueue(LOG_FILE, async () => {
+			await appendFile(LOG_FILE, line);
+		});
+	} catch {
+		// Ignore logging errors
+	}
+}
+
+const readSchema = Type.Object({
+	path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
+	offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
+	limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
+});
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "read", // Same name as built-in - this will override it
+		label: "read (audited)",
+		description:
+			"Read the contents of a file with access logging. Some sensitive paths (.env, secrets, credentials) are blocked.",
+		parameters: readSchema,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const { path, offset, limit } = params;
+			const absolutePath = resolve(ctx.cwd, path);
+
+			// Check if path is blocked
+			if (isBlockedPath(absolutePath)) {
+				await logAccess(absolutePath, false, "matches blocked pattern");
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Access denied: "${path}" matches a blocked pattern (sensitive file). This tool blocks access to .env files, secrets, credentials, and SSH/AWS/GPG directories.`,
+						},
+					],
+					details: { blocked: true },
+				};
+			}
+
+			// Log allowed access
+			await logAccess(absolutePath, true);
+
+			// Perform the actual read (simplified implementation)
+			try {
+				await access(absolutePath, constants.R_OK);
+				const content = await readFile(absolutePath, "utf-8");
+				const lines = content.split("\n");
+
+				// Apply offset and limit
+				const startLine = offset ? Math.max(0, offset - 1) : 0;
+				const endLine = limit ? startLine + limit : lines.length;
+				const selectedLines = lines.slice(startLine, endLine);
+
+				// Basic truncation (50KB limit)
+				let text = selectedLines.join("\n");
+				const maxBytes = 50 * 1024;
+				if (Buffer.byteLength(text, "utf-8") > maxBytes) {
+					text = `${text.slice(0, maxBytes)}\n\n[Output truncated at 50KB]`;
+				}
+
+				return {
+					content: [{ type: "text", text }] as TextContent[],
+					details: { lines: lines.length },
+				};
+			} catch (error: any) {
+				return {
+					content: [{ type: "text", text: `Error reading file: ${error.message}` }] as TextContent[],
+					details: { error: true },
+				};
+			}
+		},
+
+		// No renderCall/renderResult - uses built-in renderer automatically
+		// (syntax highlighting, line numbers, truncation warnings, etc.)
+	});
+
+	// Also register a command to view the access log
+	pi.registerCommand("read-log", {
+		description: "View the file access log",
+		handler: async (_args, ctx) => {
+			try {
+				const log = readFileSync(LOG_FILE, "utf-8");
+				const lines = log.trim().split("\n").slice(-20); // Last 20 entries
+				ctx.ui.notify(`Recent file access:\n${lines.join("\n")}`, "info");
+			} catch {
+				ctx.ui.notify("No access log found", "info");
+			}
+		},
+	});
+}