@oh-my-pi/pi-coding-agent 3.15.0 → 3.20.0

package/examples/extensions/todo.ts

@@ -0,0 +1,299 @@
+/**
+ * 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 "@oh-my-pi/pi-ai";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@oh-my-pi/pi-coding-agent";
+import { matchesKey, Text, truncateToWidth } from "@oh-my-pi/pi-tui";
+import { Type } from "@sinclair/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 as { message?: { role?: string; toolName?: string; details?: unknown } }).message;
+			if (!msg || 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_switch", async (_event, ctx) => reconstructState(ctx));
+	pi.on("session_branch", 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, _onUpdate, _ctx, _signal) {
+			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) {
+			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.details as TodoDetails | undefined;
+			if (!details) {
+				const text = result.content[0] as { type: string; text?: string } | undefined;
+				return new Text(text?.type === "text" && text.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] as { type: string; text?: string } | undefined;
+					const msg = text?.type === "text" && text.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.hasUI) {
+				ctx.ui.notify("/todos requires interactive mode", "error");
+				return;
+			}
+
+			await ctx.ui.custom<void>((_tui, theme, done) => {
+				return new TodoListComponent(todos, theme, () => done());
+			});
+		},
+	});
+}

package/examples/extensions/tools.ts

@@ -0,0 +1,145 @@
+/**
+ * Tools Extension
+ *
+ * Provides a /tools command to enable/disable tools interactively.
+ * Tool selection persists across session reloads and respects branch navigation.
+ *
+ * Usage:
+ * 1. Copy this file to ~/.omp/agent/extensions/ (legacy: ~/.pi/agent/extensions/) or your project's .omp/extensions/
+ * 2. Use /tools to open the tool selector
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@oh-my-pi/pi-coding-agent";
+import { getSettingsListTheme } from "@oh-my-pi/pi-coding-agent";
+import { Container, type SettingItem, SettingsList } from "@oh-my-pi/pi-tui";
+
+// State persisted to session
+interface ToolsState {
+	enabledTools: string[];
+}
+
+export default function toolsExtension(pi: ExtensionAPI) {
+	// Track enabled tools
+	let enabledTools: Set<string> = new Set();
+	let allTools: string[] = [];
+
+	// Persist current state
+	function persistState() {
+		pi.appendEntry<ToolsState>("tools-config", {
+			enabledTools: Array.from(enabledTools),
+		});
+	}
+
+	// Apply current tool selection
+	function applyTools() {
+		pi.setActiveTools(Array.from(enabledTools));
+	}
+
+	// Find the last tools-config entry in the current branch
+	function restoreFromBranch(ctx: ExtensionContext) {
+		allTools = pi.getAllTools();
+
+		// Get entries in current branch only
+		const branchEntries = ctx.sessionManager.getBranch();
+		let savedTools: string[] | undefined;
+
+		for (const entry of branchEntries) {
+			if (entry.type === "custom" && (entry as { customType?: string }).customType === "tools-config") {
+				const data = (entry as { data?: ToolsState }).data;
+				if (data?.enabledTools) {
+					savedTools = data.enabledTools;
+				}
+			}
+		}
+
+		if (savedTools) {
+			// Restore saved tool selection (filter to only tools that still exist)
+			enabledTools = new Set(savedTools.filter((t: string) => allTools.includes(t)));
+			applyTools();
+		} else {
+			// No saved state - sync with currently active tools
+			enabledTools = new Set(pi.getActiveTools());
+		}
+	}
+
+	// Register /tools command
+	pi.registerCommand("tools", {
+		description: "Enable/disable tools",
+		handler: async (_args, ctx) => {
+			// Refresh tool list
+			allTools = pi.getAllTools();
+
+			await ctx.ui.custom((tui, theme, done) => {
+				// Build settings items for each tool
+				const items: SettingItem[] = allTools.map((tool) => ({
+					id: tool,
+					label: tool,
+					currentValue: enabledTools.has(tool) ? "enabled" : "disabled",
+					values: ["enabled", "disabled"],
+				}));
+
+				const container = new Container();
+				container.addChild(
+					new (class {
+						render(_width: number) {
+							return [theme.fg("accent", theme.bold("Tool Configuration")), ""];
+						}
+						invalidate() {}
+					})(),
+				);
+
+				const settingsList = new SettingsList(
+					items,
+					Math.min(items.length + 2, 15),
+					getSettingsListTheme(),
+					(id, newValue) => {
+						// Update enabled state and apply immediately
+						if (newValue === "enabled") {
+							enabledTools.add(id);
+						} else {
+							enabledTools.delete(id);
+						}
+						applyTools();
+						persistState();
+					},
+					() => {
+						// Close dialog
+						done(undefined);
+					},
+				);
+
+				container.addChild(settingsList);
+
+				const component = {
+					render(width: number) {
+						return container.render(width);
+					},
+					invalidate() {
+						container.invalidate();
+					},
+					handleInput(data: string) {
+						settingsList.handleInput?.(data);
+						tui.requestRender();
+					},
+				};
+
+				return component;
+			});
+		},
+	});
+
+	// Restore state on session start
+	pi.on("session_start", async (_event, ctx) => {
+		restoreFromBranch(ctx);
+	});
+
+	// Restore state when navigating the session tree
+	pi.on("session_tree", async (_event, ctx) => {
+		restoreFromBranch(ctx);
+	});
+
+	// Restore state after branching
+	pi.on("session_branch", async (_event, ctx) => {
+		restoreFromBranch(ctx);
+	});
+}

package/examples/extensions/with-deps/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Example extension with its own npm dependencies.
+ * Tests that jiti resolves modules from the extension's own node_modules.
+ *
+ * Requires: npm install in this directory
+ */
+
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import ms from "ms";
+
+export default function (pi: ExtensionAPI) {
+	// Register a tool that uses ms
+	pi.registerTool({
+		name: "parse_duration",
+		label: "Parse Duration",
+		description: "Parse a human-readable duration string (e.g., '2 days', '1h', '5m') to milliseconds",
+		parameters: Type.Object({
+			duration: Type.String({ description: "Duration string like '2 days', '1h', '5m'" }),
+		}),
+		execute: async (_toolCallId, params) => {
+			const result = ms(params.duration as ms.StringValue);
+			if (result === undefined) {
+				return {
+					content: [{ type: "text", text: `Invalid duration: "${params.duration}"` }],
+					isError: true,
+					details: {},
+				};
+			}
+			return {
+				content: [{ type: "text", text: `${params.duration} = ${result} milliseconds` }],
+				details: {},
+			};
+		},
+	});
+}

package/examples/extensions/with-deps/package-lock.json

@@ -0,0 +1,31 @@
+{
+  "name": "pi-extension-with-deps",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "pi-extension-with-deps",
+      "version": "1.0.0",
+      "dependencies": {
+        "ms": "^2.1.3"
+      },
+      "devDependencies": {
+        "@types/ms": "^2.1.0"
+      }
+    },
+    "node_modules/@types/ms": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz",
+      "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "license": "MIT"
+    }
+  }
+}

package/examples/extensions/with-deps/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "pi-extension-with-deps",
+  "version": "1.0.0",
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "ms": "^2.1.3"
+  },
+  "devDependencies": {
+    "@types/ms": "^2.1.0"
+  }
+}

package/examples/sdk/02-custom-model.ts

@@ -8,8 +8,8 @@ import { getModel } from "@oh-my-pi/pi-ai";
 import { createAgentSession, discoverAuthStorage, discoverModels } from "@oh-my-pi/pi-coding-agent";
 
 // Set up auth storage and model registry
-const authStorage = discoverAuthStorage();
-const modelRegistry = discoverModels(authStorage);
+const authStorage = await discoverAuthStorage();
+const modelRegistry = await discoverModels(authStorage);
 
 // Option 1: Find a specific built-in model by provider/id
 const opus = getModel("anthropic", "claude-opus-4-5");
@@ -24,7 +24,7 @@ if (customModel) {
 }
 
 // Option 3: Pick from available models (have valid API keys)
-const available = await modelRegistry.getAvailable();
+const available = modelRegistry.getAvailable();
 console.log(
 	"Available models:",
 	available.map((m) => `${m.provider}/${m.id}`),

package/examples/sdk/05-tools.ts

@@ -39,17 +39,21 @@ console.log("Custom tools session created");
 
 // With custom cwd - MUST use factory functions!
 const customCwd = "/path/to/project";
+const customTools = await createCodingTools(customCwd);
 await createAgentSession({
 	cwd: customCwd,
-	tools: createCodingTools(customCwd), // Tools resolve paths relative to customCwd
+	tools: customTools, // Tools resolve paths relative to customCwd
 	sessionManager: SessionManager.inMemory(),
 });
 console.log("Custom cwd session created");
 
 // Or pick specific tools for custom cwd
+const customReadTool = await createReadTool(customCwd);
+const customBashTool = await createBashTool(customCwd);
+const customGrepTool = await createGrepTool(customCwd);
 await createAgentSession({
 	cwd: customCwd,
-	tools: [createReadTool(customCwd), createBashTool(customCwd), createGrepTool(customCwd)],
+	tools: [customReadTool, customBashTool, customGrepTool],
 	sessionManager: SessionManager.inMemory(),
 });
 console.log("Specific tools with custom cwd session created");
@@ -69,7 +73,7 @@ const weatherTool: CustomTool = {
 };
 
 const { session } = await createAgentSession({
-	customTools: [{ tool: weatherTool }],
+	customTools: [weatherTool],
 	sessionManager: SessionManager.inMemory(),
 });
 

package/examples/sdk/06-extensions.ts

@@ -0,0 +1,81 @@
+/**
+ * Extensions Configuration
+ *
+ * Extensions intercept agent events and can register custom tools.
+ * They provide a unified system for extensions, custom tools, commands, and more.
+ *
+ * Extension files are discovered from:
+ * - ~/.omp/agent/extensions/ (legacy: ~/.pi/agent/extensions/)
+ * - <cwd>/.omp/extensions/ (legacy: <cwd>/.pi/extensions/)
+ * - Paths specified in settings.json "extensions" array
+ * - Paths passed via --extension CLI flag
+ *
+ * An extension is a TypeScript file that exports a default function:
+ *   export default function (pi: ExtensionAPI) { ... }
+ */
+
+import { createAgentSession, SessionManager } from "@oh-my-pi/pi-coding-agent";
+
+// Extensions are loaded from disk, not passed inline to createAgentSession.
+// Use the discovery mechanism:
+//   1. Place extension files in ~/.omp/agent/extensions/ or .omp/extensions/
+//   2. Add paths to settings.json: { "extensions": ["./my-extension.ts"] }
+//   3. Use --extension flag: pi --extension ./my-extension.ts
+
+// To add additional extension paths beyond discovery:
+const { session } = await createAgentSession({
+	additionalExtensionPaths: ["./my-logging-extension.ts", "./my-safety-extension.ts"],
+	sessionManager: SessionManager.inMemory(),
+});
+
+session.subscribe((event) => {
+	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+		process.stdout.write(event.assistantMessageEvent.delta);
+	}
+});
+
+await session.prompt("List files in the current directory.");
+console.log();
+
+// Example extension file (./my-logging-extension.ts):
+/*
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("agent_start", async () => {
+		console.log("[Extension] Agent starting");
+	});
+
+	pi.on("tool_call", async (event) => {
+		console.log(\`[Extension] Tool: \${event.toolName}\`);
+		// Return { block: true, reason: "..." } to block execution
+		return undefined;
+	});
+
+	pi.on("agent_end", async (event) => {
+		console.log(\`[Extension] Done, \${event.messages.length} messages\`);
+	});
+
+	// Register a custom tool
+	pi.registerTool({
+		name: "my_tool",
+		label: "My Tool",
+		description: "Does something useful",
+		parameters: Type.Object({
+			input: Type.String(),
+		}),
+		execute: async (_toolCallId, params, _onUpdate, _ctx, _signal) => ({
+			content: [{ type: "text", text: \`Processed: \${params.input}\` }],
+			details: {},
+		}),
+	});
+
+	// Register a command
+	pi.registerCommand("mycommand", {
+		description: "Do something",
+		handler: async (args, ctx) => {
+			ctx.ui.notify(\`Command executed with: \${args}\`);
+		},
+	});
+}
+*/