pi-usereq 0.49.0 → 0.51.0

package/pi.dev-src/pi-mono/coding-agent/examples/extensions/bash-spawn-hook.ts

@@ -1,30 +0,0 @@
-/**
- * Bash Spawn Hook Example
- *
- * Adjusts command, cwd, and env before execution.
- *
- * Usage:
- *   pi -e ./bash-spawn-hook.ts
- */
-
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { createBashTool } from "@mariozechner/pi-coding-agent";
-
-export default function (pi: ExtensionAPI) {
-	const cwd = process.cwd();
-
-	const bashTool = createBashTool(cwd, {
-		spawnHook: ({ command, cwd, env }) => ({
-			command: `source ~/.profile\n${command}`,
-			cwd,
-			env: { ...env, PI_SPAWN_HOOK: "1" },
-		}),
-	});
-
-	pi.registerTool({
-		...bashTool,
-		execute: async (id, params, signal, onUpdate, _ctx) => {
-			return bashTool.execute(id, params, signal, onUpdate);
-		},
-	});
-}

package/pi.dev-src/pi-mono/coding-agent/examples/extensions/bookmark.ts

@@ -1,50 +0,0 @@
-/**
- * Entry bookmarking example.
- *
- * Shows setLabel to mark entries with labels for easy navigation in /tree.
- * Labels appear in the tree view and help you find important points.
- *
- * Usage: /bookmark [label] - bookmark the last assistant message
- */
-
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-
-export default function (pi: ExtensionAPI) {
-	pi.registerCommand("bookmark", {
-		description: "Bookmark last message (usage: /bookmark [label])",
-		handler: async (args, ctx) => {
-			const label = args.trim() || `bookmark-${Date.now()}`;
-
-			// Find the last assistant message entry
-			const entries = ctx.sessionManager.getEntries();
-			for (let i = entries.length - 1; i >= 0; i--) {
-				const entry = entries[i];
-				if (entry.type === "message" && entry.message.role === "assistant") {
-					pi.setLabel(entry.id, label);
-					ctx.ui.notify(`Bookmarked as: ${label}`, "info");
-					return;
-				}
-			}
-
-			ctx.ui.notify("No assistant message to bookmark", "warning");
-		},
-	});
-
-	// Remove bookmark
-	pi.registerCommand("unbookmark", {
-		description: "Remove bookmark from last labeled entry",
-		handler: async (_args, ctx) => {
-			const entries = ctx.sessionManager.getEntries();
-			for (let i = entries.length - 1; i >= 0; i--) {
-				const entry = entries[i];
-				const label = ctx.sessionManager.getLabel(entry.id);
-				if (label) {
-					pi.setLabel(entry.id, undefined);
-					ctx.ui.notify(`Removed bookmark: ${label}`, "info");
-					return;
-				}
-			}
-			ctx.ui.notify("No bookmarked entry found", "warning");
-		},
-	});
-}

package/pi.dev-src/pi-mono/coding-agent/examples/extensions/built-in-tool-renderer.ts

@@ -1,249 +0,0 @@
-/**
- * Built-in Tool Renderer Example - Custom rendering for built-in tools
- *
- * Demonstrates how to override the rendering of built-in tools (read, bash,
- * edit, write) without changing their behavior. Each tool is re-registered
- * with the same name, delegating execution to the original implementation
- * while providing compact custom renderCall/renderResult functions.
- *
- * This is useful for users who prefer more concise tool output, or who want
- * to highlight specific information (e.g., showing only the diff stats for
- * edit, or just the exit code for bash).
- *
- * How it works:
- * - registerTool() with the same name as a built-in replaces it entirely
- * - We create instances of the original tools via createReadTool(), etc.
- *   and delegate execute() to them
- * - renderCall() controls what's shown when the tool is invoked
- * - renderResult() controls what's shown after execution completes
- * - renderShell: "self" lets a tool render its own outer shell instead of
- *   using the default boxed shell from ToolExecutionComponent
- * - The `expanded` flag in renderResult indicates whether the user has
- *   toggled the tool output open (via ctrl+e or clicking)
- *
- * Usage:
- *   pi -e ./built-in-tool-renderer.ts
- */
-
-import type { BashToolDetails, EditToolDetails, ExtensionAPI, ReadToolDetails } from "@mariozechner/pi-coding-agent";
-import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@mariozechner/pi-coding-agent";
-import { Text } from "@mariozechner/pi-tui";
-
-export default function (pi: ExtensionAPI) {
-	const cwd = process.cwd();
-
-	// --- Read tool: show path and line count ---
-	const originalRead = createReadTool(cwd);
-	pi.registerTool({
-		name: "read",
-		label: "read",
-		description: originalRead.description,
-		parameters: originalRead.parameters,
-
-		async execute(toolCallId, params, signal, onUpdate) {
-			return originalRead.execute(toolCallId, params, signal, onUpdate);
-		},
-
-		renderCall(args, theme, _context) {
-			let text = theme.fg("toolTitle", theme.bold("read "));
-			text += theme.fg("accent", args.path);
-			if (args.offset || args.limit) {
-				const parts: string[] = [];
-				if (args.offset) parts.push(`offset=${args.offset}`);
-				if (args.limit) parts.push(`limit=${args.limit}`);
-				text += theme.fg("dim", ` (${parts.join(", ")})`);
-			}
-			return new Text(text, 0, 0);
-		},
-
-		renderResult(result, { expanded, isPartial }, theme, _context) {
-			if (isPartial) return new Text(theme.fg("warning", "Reading..."), 0, 0);
-
-			const details = result.details as ReadToolDetails | undefined;
-			const content = result.content[0];
-
-			if (content?.type === "image") {
-				return new Text(theme.fg("success", "Image loaded"), 0, 0);
-			}
-
-			if (content?.type !== "text") {
-				return new Text(theme.fg("error", "No content"), 0, 0);
-			}
-
-			const lineCount = content.text.split("\n").length;
-			let text = theme.fg("success", `${lineCount} lines`);
-
-			if (details?.truncation?.truncated) {
-				text += theme.fg("warning", ` (truncated from ${details.truncation.totalLines})`);
-			}
-
-			if (expanded) {
-				const lines = content.text.split("\n").slice(0, 15);
-				for (const line of lines) {
-					text += `\n${theme.fg("dim", line)}`;
-				}
-				if (lineCount > 15) {
-					text += `\n${theme.fg("muted", `... ${lineCount - 15} more lines`)}`;
-				}
-			}
-
-			return new Text(text, 0, 0);
-		},
-	});
-
-	// --- Bash tool: show command and exit code ---
-	const originalBash = createBashTool(cwd);
-	pi.registerTool({
-		name: "bash",
-		label: "bash",
-		description: originalBash.description,
-		parameters: originalBash.parameters,
-
-		async execute(toolCallId, params, signal, onUpdate) {
-			return originalBash.execute(toolCallId, params, signal, onUpdate);
-		},
-
-		renderCall(args, theme, _context) {
-			let text = theme.fg("toolTitle", theme.bold("$ "));
-			const cmd = args.command.length > 80 ? `${args.command.slice(0, 77)}...` : args.command;
-			text += theme.fg("accent", cmd);
-			if (args.timeout) {
-				text += theme.fg("dim", ` (timeout: ${args.timeout}s)`);
-			}
-			return new Text(text, 0, 0);
-		},
-
-		renderResult(result, { expanded, isPartial }, theme, _context) {
-			if (isPartial) return new Text(theme.fg("warning", "Running..."), 0, 0);
-
-			const details = result.details as BashToolDetails | undefined;
-			const content = result.content[0];
-			const output = content?.type === "text" ? content.text : "";
-
-			const exitMatch = output.match(/exit code: (\d+)/);
-			const exitCode = exitMatch ? parseInt(exitMatch[1], 10) : null;
-			const lineCount = output.split("\n").filter((l) => l.trim()).length;
-
-			let text = "";
-			if (exitCode === 0 || exitCode === null) {
-				text += theme.fg("success", "done");
-			} else {
-				text += theme.fg("error", `exit ${exitCode}`);
-			}
-			text += theme.fg("dim", ` (${lineCount} lines)`);
-
-			if (details?.truncation?.truncated) {
-				text += theme.fg("warning", " [truncated]");
-			}
-
-			if (expanded) {
-				const lines = output.split("\n").slice(0, 20);
-				for (const line of lines) {
-					text += `\n${theme.fg("dim", line)}`;
-				}
-				if (output.split("\n").length > 20) {
-					text += `\n${theme.fg("muted", "... more output")}`;
-				}
-			}
-
-			return new Text(text, 0, 0);
-		},
-	});
-
-	// --- Edit tool: show path and diff stats ---
-	const originalEdit = createEditTool(cwd);
-	pi.registerTool({
-		name: "edit",
-		label: "edit",
-		description: originalEdit.description,
-		parameters: originalEdit.parameters,
-		renderShell: "self",
-
-		async execute(toolCallId, params, signal, onUpdate) {
-			return originalEdit.execute(toolCallId, params, signal, onUpdate);
-		},
-
-		renderCall(args, theme, _context) {
-			let text = theme.fg("toolTitle", theme.bold("edit "));
-			text += theme.fg("accent", args.path);
-			return new Text(text, 0, 0);
-		},
-
-		renderResult(result, { expanded, isPartial }, theme, _context) {
-			if (isPartial) return new Text(theme.fg("warning", "Editing..."), 0, 0);
-
-			const details = result.details as EditToolDetails | undefined;
-			const content = result.content[0];
-
-			if (content?.type === "text" && content.text.startsWith("Error")) {
-				return new Text(theme.fg("error", content.text.split("\n")[0]), 0, 0);
-			}
-
-			if (!details?.diff) {
-				return new Text(theme.fg("success", "Applied"), 0, 0);
-			}
-
-			// Count additions and removals from the diff
-			const diffLines = details.diff.split("\n");
-			let additions = 0;
-			let removals = 0;
-			for (const line of diffLines) {
-				if (line.startsWith("+") && !line.startsWith("+++")) additions++;
-				if (line.startsWith("-") && !line.startsWith("---")) removals++;
-			}
-
-			let text = theme.fg("success", `+${additions}`);
-			text += theme.fg("dim", " / ");
-			text += theme.fg("error", `-${removals}`);
-
-			if (expanded) {
-				for (const line of diffLines.slice(0, 30)) {
-					if (line.startsWith("+") && !line.startsWith("+++")) {
-						text += `\n${theme.fg("success", line)}`;
-					} else if (line.startsWith("-") && !line.startsWith("---")) {
-						text += `\n${theme.fg("error", line)}`;
-					} else {
-						text += `\n${theme.fg("dim", line)}`;
-					}
-				}
-				if (diffLines.length > 30) {
-					text += `\n${theme.fg("muted", `... ${diffLines.length - 30} more diff lines`)}`;
-				}
-			}
-
-			return new Text(text, 0, 0);
-		},
-	});
-
-	// --- Write tool: show path and size ---
-	const originalWrite = createWriteTool(cwd);
-	pi.registerTool({
-		name: "write",
-		label: "write",
-		description: originalWrite.description,
-		parameters: originalWrite.parameters,
-
-		async execute(toolCallId, params, signal, onUpdate) {
-			return originalWrite.execute(toolCallId, params, signal, onUpdate);
-		},
-
-		renderCall(args, theme, _context) {
-			let text = theme.fg("toolTitle", theme.bold("write "));
-			text += theme.fg("accent", args.path);
-			const lineCount = args.content.split("\n").length;
-			text += theme.fg("dim", ` (${lineCount} lines)`);
-			return new Text(text, 0, 0);
-		},
-
-		renderResult(result, { isPartial }, theme, _context) {
-			if (isPartial) return new Text(theme.fg("warning", "Writing..."), 0, 0);
-
-			const content = result.content[0];
-			if (content?.type === "text" && content.text.startsWith("Error")) {
-				return new Text(theme.fg("error", content.text.split("\n")[0]), 0, 0);
-			}
-
-			return new Text(theme.fg("success", "Written"), 0, 0);
-		},
-	});
-}

package/pi.dev-src/pi-mono/coding-agent/examples/extensions/claude-rules.ts

@@ -1,86 +0,0 @@
-/**
- * Claude Rules Extension
- *
- * Scans the project's .claude/rules/ folder for rule files and lists them
- * in the system prompt. The agent can then use the read tool to load
- * specific rules when needed.
- *
- * Best practices for .claude/rules/:
- * - Keep rules focused: Each file should cover one topic (e.g., testing.md, api-design.md)
- * - Use descriptive filenames: The filename should indicate what the rules cover
- * - Use conditional rules sparingly: Only add paths frontmatter when rules truly apply to specific file types
- * - Organize with subdirectories: Group related rules (e.g., frontend/, backend/)
- *
- * Usage:
- * 1. Copy this file to ~/.pi/agent/extensions/ or your project's .pi/extensions/
- * 2. Create .claude/rules/ folder in your project root
- * 3. Add .md files with your rules
- */
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-
-/**
- * Recursively find all .md files in a directory
- */
-function findMarkdownFiles(dir: string, basePath: string = ""): string[] {
-	const results: string[] = [];
-
-	if (!fs.existsSync(dir)) {
-		return results;
-	}
-
-	const entries = fs.readdirSync(dir, { withFileTypes: true });
-
-	for (const entry of entries) {
-		const relativePath = basePath ? `${basePath}/${entry.name}` : entry.name;
-
-		if (entry.isDirectory()) {
-			results.push(...findMarkdownFiles(path.join(dir, entry.name), relativePath));
-		} else if (entry.isFile() && entry.name.endsWith(".md")) {
-			results.push(relativePath);
-		}
-	}
-
-	return results;
-}
-
-export default function claudeRulesExtension(pi: ExtensionAPI) {
-	let ruleFiles: string[] = [];
-	let rulesDir: string = "";
-
-	// Scan for rules on session start
-	pi.on("session_start", async (_event, ctx) => {
-		rulesDir = path.join(ctx.cwd, ".claude", "rules");
-		ruleFiles = findMarkdownFiles(rulesDir);
-
-		if (ruleFiles.length > 0) {
-			ctx.ui.notify(`Found ${ruleFiles.length} rule(s) in .claude/rules/`, "info");
-		}
-	});
-
-	// Append available rules to system prompt
-	pi.on("before_agent_start", async (event) => {
-		if (ruleFiles.length === 0) {
-			return;
-		}
-
-		const rulesList = ruleFiles.map((f) => `- .claude/rules/${f}`).join("\n");
-
-		return {
-			systemPrompt:
-				event.systemPrompt +
-				`
-
-## Project Rules
-
-The following project rules are available in .claude/rules/:
-
-${rulesList}
-
-When working on tasks related to these rules, use the read tool to load the relevant rule files for guidance.
-`,
-		};
-	});
-}

package/pi.dev-src/pi-mono/coding-agent/examples/extensions/commands.ts

@@ -1,72 +0,0 @@
-/**
- * Commands Extension
- *
- * Demonstrates the pi.getCommands() API by providing a /commands command
- * that lists all available slash commands in the current session.
- *
- * Usage:
- * 1. Copy this file to ~/.pi/agent/extensions/ or your project's .pi/extensions/
- * 2. Use /commands to see available commands
- * 3. Use /commands extensions to filter by source
- */
-
-import type { ExtensionAPI, SlashCommandInfo } from "@mariozechner/pi-coding-agent";
-
-export default function commandsExtension(pi: ExtensionAPI) {
-	pi.registerCommand("commands", {
-		description: "List available slash commands",
-		getArgumentCompletions: (prefix) => {
-			const sources = ["extension", "prompt", "skill"];
-			const filtered = sources.filter((s) => s.startsWith(prefix));
-			return filtered.length > 0 ? filtered.map((s) => ({ value: s, label: s })) : null;
-		},
-		handler: async (args, ctx) => {
-			const commands = pi.getCommands();
-			const sourceFilter = args.trim() as "extension" | "prompt" | "skill" | "";
-
-			// Filter by source if specified
-			const filtered = sourceFilter ? commands.filter((c) => c.source === sourceFilter) : commands;
-
-			if (filtered.length === 0) {
-				ctx.ui.notify(sourceFilter ? `No ${sourceFilter} commands found` : "No commands found", "info");
-				return;
-			}
-
-			// Build selection items grouped by source
-			const formatCommand = (cmd: SlashCommandInfo): string => {
-				const desc = cmd.description ? ` - ${cmd.description}` : "";
-				return `/${cmd.name}${desc}`;
-			};
-
-			const items: string[] = [];
-			const sources: Array<{ key: "extension" | "prompt" | "skill"; label: string }> = [
-				{ key: "extension", label: "Extensions" },
-				{ key: "prompt", label: "Prompts" },
-				{ key: "skill", label: "Skills" },
-			];
-
-			for (const { key, label } of sources) {
-				const cmds = filtered.filter((c) => c.source === key);
-				if (cmds.length > 0) {
-					items.push(`--- ${label} ---`);
-					items.push(...cmds.map(formatCommand));
-				}
-			}
-
-			// Show in a selector (user can scroll and see all commands)
-			const selected = await ctx.ui.select("Available Commands", items);
-
-			// If user selected a command (not a header), offer to show its path
-			if (selected && !selected.startsWith("---")) {
-				const cmdName = selected.split(" - ")[0].slice(1); // Remove leading /
-				const cmd = commands.find((c) => c.name === cmdName);
-				if (cmd?.sourceInfo.path) {
-					const showPath = await ctx.ui.confirm(cmd.name, `View source path?\n${cmd.sourceInfo.path}`);
-					if (showPath) {
-						ctx.ui.notify(cmd.sourceInfo.path, "info");
-					}
-				}
-			}
-		},
-	});
-}

package/pi.dev-src/pi-mono/coding-agent/examples/extensions/confirm-destructive.ts

@@ -1,59 +0,0 @@
-/**
- * Confirm Destructive Actions Extension
- *
- * Prompts for confirmation before destructive session actions (clear, switch, branch).
- * Demonstrates how to cancel session events using the before_* events.
- */
-
-import type { ExtensionAPI, SessionBeforeSwitchEvent, SessionMessageEntry } from "@mariozechner/pi-coding-agent";
-
-export default function (pi: ExtensionAPI) {
-	pi.on("session_before_switch", async (event: SessionBeforeSwitchEvent, ctx) => {
-		if (!ctx.hasUI) return;
-
-		if (event.reason === "new") {
-			const confirmed = await ctx.ui.confirm(
-				"Clear session?",
-				"This will delete all messages in the current session.",
-			);
-
-			if (!confirmed) {
-				ctx.ui.notify("Clear cancelled", "info");
-				return { cancel: true };
-			}
-			return;
-		}
-
-		// reason === "resume" - check if there are unsaved changes (messages since last assistant response)
-		const entries = ctx.sessionManager.getEntries();
-		const hasUnsavedWork = entries.some(
-			(e): e is SessionMessageEntry => e.type === "message" && e.message.role === "user",
-		);
-
-		if (hasUnsavedWork) {
-			const confirmed = await ctx.ui.confirm(
-				"Switch session?",
-				"You have messages in the current session. Switch anyway?",
-			);
-
-			if (!confirmed) {
-				ctx.ui.notify("Switch cancelled", "info");
-				return { cancel: true };
-			}
-		}
-	});
-
-	pi.on("session_before_fork", async (event, ctx) => {
-		if (!ctx.hasUI) return;
-
-		const choice = await ctx.ui.select(`Fork from entry ${event.entryId.slice(0, 8)}?`, [
-			"Yes, create fork",
-			"No, stay in current session",
-		]);
-
-		if (choice !== "Yes, create fork") {
-			ctx.ui.notify("Fork cancelled", "info");
-			return { cancel: true };
-		}
-	});
-}

package/pi.dev-src/pi-mono/coding-agent/examples/extensions/custom-compaction.ts

@@ -1,127 +0,0 @@
-/**
- * Custom Compaction Extension
- *
- * Replaces the default compaction behavior with a full summary of the entire context.
- * Instead of keeping the last 20k tokens of conversation turns, this extension:
- * 1. Summarizes ALL messages (messagesToSummarize + turnPrefixMessages)
- * 2. Discards all old turns completely, keeping only the summary
- *
- * This example also demonstrates using a different model (Gemini Flash) for summarization,
- * which can be cheaper/faster than the main conversation model.
- *
- * Usage:
- *   pi --extension examples/extensions/custom-compaction.ts
- */
-
-import { complete } from "@mariozechner/pi-ai";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { convertToLlm, serializeConversation } from "@mariozechner/pi-coding-agent";
-
-export default function (pi: ExtensionAPI) {
-	pi.on("session_before_compact", async (event, ctx) => {
-		ctx.ui.notify("Custom compaction extension triggered", "info");
-
-		const { preparation, branchEntries: _, signal } = event;
-		const { messagesToSummarize, turnPrefixMessages, tokensBefore, firstKeptEntryId, previousSummary } = preparation;
-
-		// Use Gemini Flash for summarization (cheaper/faster than most conversation models)
-		const model = ctx.modelRegistry.find("google", "gemini-2.5-flash");
-		if (!model) {
-			ctx.ui.notify(`Could not find Gemini Flash model, using default compaction`, "warning");
-			return;
-		}
-
-		// Resolve request auth for the summarization model
-		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-		if (!auth.ok) {
-			ctx.ui.notify(`Compaction auth failed: ${auth.error}`, "warning");
-			return;
-		}
-		if (!auth.apiKey) {
-			ctx.ui.notify(`No API key for ${model.provider}, using default compaction`, "warning");
-			return;
-		}
-
-		// Combine all messages for full summary
-		const allMessages = [...messagesToSummarize, ...turnPrefixMessages];
-
-		ctx.ui.notify(
-			`Custom compaction: summarizing ${allMessages.length} messages (${tokensBefore.toLocaleString()} tokens) with ${model.id}...`,
-			"info",
-		);
-
-		// Convert messages to readable text format
-		const conversationText = serializeConversation(convertToLlm(allMessages));
-
-		// Include previous summary context if available
-		const previousContext = previousSummary ? `\n\nPrevious session summary for context:\n${previousSummary}` : "";
-
-		// Build messages that ask for a comprehensive summary
-		const summaryMessages = [
-			{
-				role: "user" as const,
-				content: [
-					{
-						type: "text" as const,
-						text: `You are a conversation summarizer. Create a comprehensive summary of this conversation that captures:${previousContext}
-
-1. The main goals and objectives discussed
-2. Key decisions made and their rationale
-3. Important code changes, file modifications, or technical details
-4. Current state of any ongoing work
-5. Any blockers, issues, or open questions
-6. Next steps that were planned or suggested
-
-Be thorough but concise. The summary will replace the ENTIRE conversation history, so include all information needed to continue the work effectively.
-
-Format the summary as structured markdown with clear sections.
-
-<conversation>
-${conversationText}
-</conversation>`,
-					},
-				],
-				timestamp: Date.now(),
-			},
-		];
-
-		try {
-			// Pass signal to honor abort requests (e.g., user cancels compaction)
-			const response = await complete(
-				model,
-				{ messages: summaryMessages },
-				{
-					apiKey: auth.apiKey,
-					headers: auth.headers,
-					maxTokens: 8192,
-					signal,
-				},
-			);
-
-			const summary = response.content
-				.filter((c): c is { type: "text"; text: string } => c.type === "text")
-				.map((c) => c.text)
-				.join("\n");
-
-			if (!summary.trim()) {
-				if (!signal.aborted) ctx.ui.notify("Compaction summary was empty, using default compaction", "warning");
-				return;
-			}
-
-			// Return compaction content - SessionManager adds id/parentId
-			// Use firstKeptEntryId from preparation to keep recent messages
-			return {
-				compaction: {
-					summary,
-					firstKeptEntryId,
-					tokensBefore,
-				},
-			};
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			ctx.ui.notify(`Compaction failed: ${message}`, "error");
-			// Fall back to default compaction on error
-			return;
-		}
-	});
-}