@lenylvt/pi-coding-agent 0.64.0

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 "@lenylvt/pi-ai";
+import { type ExtensionAPI, getAgentDir, withFileMutationQueue } from "@lenylvt/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { constants, readFileSync } from "fs";
+import { access, appendFile, readFile } from "fs/promises";
+import { join, resolve } from "path";
+
+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");
+			}
+		},
+	});
+}

package/examples/extensions/tools.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 ~/.pi/agent/extensions/ or your project's .pi/extensions/
+ * 2. Use /tools to open the tool selector
+ */
+
+import type { ExtensionAPI, ExtensionContext, ToolInfo } from "@lenylvt/pi-coding-agent";
+import { getSettingsListTheme } from "@lenylvt/pi-coding-agent";
+import { Container, type SettingItem, SettingsList } from "@lenylvt/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: ToolInfo[] = [];
+
+	// 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.customType === "tools-config") {
+				const data = entry.data as ToolsState | undefined;
+				if (data?.enabledTools) {
+					savedTools = data.enabledTools;
+				}
+			}
+		}
+
+		if (savedTools) {
+			// Restore saved tool selection (filter to only tools that still exist)
+			const allToolNames = allTools.map((t) => t.name);
+			enabledTools = new Set(savedTools.filter((t: string) => allToolNames.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, _kb, done) => {
+				// Build settings items for each tool
+				const items: SettingItem[] = allTools.map((tool) => ({
+					id: tool.name,
+					label: tool.name,
+					currentValue: enabledTools.has(tool.name) ? "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 forking
+	pi.on("session_fork", async (_event, ctx) => {
+		restoreFromBranch(ctx);
+	});
+}

package/examples/extensions/trigger-compact.ts

@@ -0,0 +1,50 @@
+import type { ExtensionAPI, ExtensionContext } from "@lenylvt/pi-coding-agent";
+
+const COMPACT_THRESHOLD_TOKENS = 100_000;
+
+export default function (pi: ExtensionAPI) {
+	let previousTokens: number | null | undefined;
+
+	const triggerCompaction = (ctx: ExtensionContext, customInstructions?: string) => {
+		if (ctx.hasUI) {
+			ctx.ui.notify("Compaction started", "info");
+		}
+		ctx.compact({
+			customInstructions,
+			onComplete: () => {
+				if (ctx.hasUI) {
+					ctx.ui.notify("Compaction completed", "info");
+				}
+			},
+			onError: (error) => {
+				if (ctx.hasUI) {
+					ctx.ui.notify(`Compaction failed: ${error.message}`, "error");
+				}
+			},
+		});
+	};
+
+	pi.on("turn_end", (_event, ctx) => {
+		const usage = ctx.getContextUsage();
+		const currentTokens = usage?.tokens ?? null;
+		if (currentTokens === null) {
+			return;
+		}
+
+		const crossedThreshold =
+			previousTokens !== undefined && previousTokens !== null && previousTokens <= COMPACT_THRESHOLD_TOKENS;
+		previousTokens = currentTokens;
+		if (!crossedThreshold || currentTokens <= COMPACT_THRESHOLD_TOKENS) {
+			return;
+		}
+		triggerCompaction(ctx);
+	});
+
+	pi.registerCommand("trigger-compact", {
+		description: "Trigger compaction immediately",
+		handler: async (args, ctx) => {
+			const instructions = args.trim() || undefined;
+			triggerCompaction(ctx, instructions);
+		},
+	});
+}

package/examples/extensions/truncated-tool.ts

@@ -0,0 +1,195 @@
+/**
+ * Truncated Tool Example - Demonstrates proper output truncation for custom tools
+ *
+ * Custom tools MUST truncate their output to avoid overwhelming the LLM context.
+ * The built-in limit is 50KB (~10k tokens) and 2000 lines, whichever is hit first.
+ *
+ * This example shows how to:
+ * 1. Use the built-in truncation utilities
+ * 2. Write full output to a temp file when truncated
+ * 3. Inform the LLM where to find the complete output
+ * 4. Custom rendering of tool calls and results
+ *
+ * The `rg` tool here wraps ripgrep with proper truncation. Compare this to the
+ * built-in `grep` tool in src/core/tools/grep.ts for a more complete implementation.
+ */
+
+import { mkdtemp, writeFile } from "node:fs/promises";
+import type { ExtensionAPI } from "@lenylvt/pi-coding-agent";
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	formatSize,
+	type TruncationResult,
+	truncateHead,
+	withFileMutationQueue,
+} from "@lenylvt/pi-coding-agent";
+import { Text } from "@lenylvt/pi-tui";
+import { Type } from "@sinclair/typebox";
+import { execSync } from "child_process";
+import { tmpdir } from "os";
+import { join } from "path";
+
+const RgParams = Type.Object({
+	pattern: Type.String({ description: "Search pattern (regex)" }),
+	path: Type.Optional(Type.String({ description: "Directory to search (default: current directory)" })),
+	glob: Type.Optional(Type.String({ description: "File glob pattern, e.g. '*.ts'" })),
+});
+
+interface RgDetails {
+	pattern: string;
+	path?: string;
+	glob?: string;
+	matchCount: number;
+	truncation?: TruncationResult;
+	fullOutputPath?: string;
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "rg",
+		label: "ripgrep",
+		// Document the truncation limits in the tool description so the LLM knows
+		description: `Search file contents using ripgrep. Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)} (whichever is hit first). If truncated, full output is saved to a temp file.`,
+		parameters: RgParams,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const { pattern, path: searchPath, glob } = params;
+
+			// Build the ripgrep command
+			const args = ["rg", "--line-number", "--color=never"];
+			if (glob) args.push("--glob", glob);
+			args.push(pattern);
+			args.push(searchPath || ".");
+
+			let output: string;
+			try {
+				output = execSync(args.join(" "), {
+					cwd: ctx.cwd,
+					encoding: "utf-8",
+					maxBuffer: 100 * 1024 * 1024, // 100MB buffer to capture full output
+				});
+			} catch (err: any) {
+				// ripgrep exits with 1 when no matches found
+				if (err.status === 1) {
+					return {
+						content: [{ type: "text", text: "No matches found" }],
+						details: { pattern, path: searchPath, glob, matchCount: 0 } as RgDetails,
+					};
+				}
+				throw new Error(`ripgrep failed: ${err.message}`);
+			}
+
+			if (!output.trim()) {
+				return {
+					content: [{ type: "text", text: "No matches found" }],
+					details: { pattern, path: searchPath, glob, matchCount: 0 } as RgDetails,
+				};
+			}
+
+			// Apply truncation using built-in utilities
+			// truncateHead keeps the first N lines/bytes (good for search results)
+			// truncateTail keeps the last N lines/bytes (good for logs/command output)
+			const truncation = truncateHead(output, {
+				maxLines: DEFAULT_MAX_LINES,
+				maxBytes: DEFAULT_MAX_BYTES,
+			});
+
+			// Count matches (each non-empty line with a match)
+			const matchCount = output.split("\n").filter((line) => line.trim()).length;
+
+			const details: RgDetails = {
+				pattern,
+				path: searchPath,
+				glob,
+				matchCount,
+			};
+
+			let resultText = truncation.content;
+
+			if (truncation.truncated) {
+				// Save full output to a temp file so LLM can access it if needed
+				const tempDir = await mkdtemp(join(tmpdir(), "pi-rg-"));
+				const tempFile = join(tempDir, "output.txt");
+				await withFileMutationQueue(tempFile, async () => {
+					await writeFile(tempFile, output, "utf8");
+				});
+
+				details.truncation = truncation;
+				details.fullOutputPath = tempFile;
+
+				// Add truncation notice - this helps the LLM understand the output is incomplete
+				const truncatedLines = truncation.totalLines - truncation.outputLines;
+				const truncatedBytes = truncation.totalBytes - truncation.outputBytes;
+
+				resultText += `\n\n[Output truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines`;
+				resultText += ` (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}).`;
+				resultText += ` ${truncatedLines} lines (${formatSize(truncatedBytes)}) omitted.`;
+				resultText += ` Full output saved to: ${tempFile}]`;
+			}
+
+			return {
+				content: [{ type: "text", text: resultText }],
+				details,
+			};
+		},
+
+		// Custom rendering of the tool call (shown before/during execution)
+		renderCall(args, theme, _context) {
+			let text = theme.fg("toolTitle", theme.bold("rg "));
+			text += theme.fg("accent", `"${args.pattern}"`);
+			if (args.path) {
+				text += theme.fg("muted", ` in ${args.path}`);
+			}
+			if (args.glob) {
+				text += theme.fg("dim", ` --glob ${args.glob}`);
+			}
+			return new Text(text, 0, 0);
+		},
+
+		// Custom rendering of the tool result
+		renderResult(result, { expanded, isPartial }, theme, _context) {
+			const details = result.details as RgDetails | undefined;
+
+			// Handle streaming/partial results
+			if (isPartial) {
+				return new Text(theme.fg("warning", "Searching..."), 0, 0);
+			}
+
+			// No matches
+			if (!details || details.matchCount === 0) {
+				return new Text(theme.fg("dim", "No matches found"), 0, 0);
+			}
+
+			// Build result display
+			let text = theme.fg("success", `${details.matchCount} matches`);
+
+			// Show truncation warning if applicable
+			if (details.truncation?.truncated) {
+				text += theme.fg("warning", " (truncated)");
+			}
+
+			// In expanded view, show the actual matches
+			if (expanded) {
+				const content = result.content[0];
+				if (content?.type === "text") {
+					// Show first 20 lines in expanded view, or all if fewer
+					const lines = content.text.split("\n").slice(0, 20);
+					for (const line of lines) {
+						text += `\n${theme.fg("dim", line)}`;
+					}
+					if (content.text.split("\n").length > 20) {
+						text += `\n${theme.fg("muted", "... (use read tool to see full output)")}`;
+					}
+				}
+
+				// Show temp file path if truncated
+				if (details.fullOutputPath) {
+					text += `\n${theme.fg("dim", `Full output: ${details.fullOutputPath}`)}`;
+				}
+			}
+
+			return new Text(text, 0, 0);
+		},
+	});
+}

package/examples/extensions/widget-placement.ts

@@ -0,0 +1,17 @@
+import type { ExtensionAPI, ExtensionContext } from "@lenylvt/pi-coding-agent";
+
+const applyWidgets = (ctx: ExtensionContext) => {
+	if (!ctx.hasUI) return;
+	ctx.ui.setWidget("widget-above", ["Above editor widget"]);
+	ctx.ui.setWidget("widget-below", ["Below editor widget"], { placement: "belowEditor" });
+};
+
+export default function widgetPlacementExtension(pi: ExtensionAPI) {
+	pi.on("session_start", (_event, ctx) => {
+		applyWidgets(ctx);
+	});
+
+	pi.on("session_switch", (_event, ctx) => {
+		applyWidgets(ctx);
+	});
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Example extension with its own Bun dependencies.
+ * Tests that jiti resolves modules from the extension's own node_modules.
+ *
+ * Requires: bun install in this directory
+ */
+
+import type { ExtensionAPI } from "@lenylvt/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) {
+				throw new Error(`Invalid duration: "${params.duration}"`);
+			}
+			return {
+				content: [{ type: "text", text: `${params.duration} = ${result} milliseconds` }],
+				details: {},
+			};
+		},
+	});
+}

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

@@ -0,0 +1,22 @@
+{
+  "name": "pi-extension-with-deps",
+  "private": true,
+  "version": "1.28.0",
+  "type": "module",
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "ms": "^2.1.3"
+  },
+  "devDependencies": {
+    "@types/ms": "^2.1.0"
+  }
+}