@lenylvt/pi-coding-agent 0.64.0

package/docs/windows.md

@@ -0,0 +1,17 @@
+# Windows Setup
+
+Pi requires a bash shell on Windows. Checked locations (in order):
+
+1. Custom path from `~/.pi/agent/settings.json`
+2. Git Bash (`C:\Program Files\Git\bin\bash.exe`)
+3. `bash.exe` on PATH (Cygwin, MSYS2, WSL)
+
+For most users, [Git for Windows](https://git-scm.com/download/win) is sufficient.
+
+## Custom Shell Path
+
+```json
+{
+  "shellPath": "C:\\cygwin64\\bin\\bash.exe"
+}
+```

package/examples/README.md

@@ -0,0 +1,25 @@
+# Examples
+
+Example code for pi-coding-agent SDK and extensions.
+
+## Directories
+
+### [sdk/](sdk/)
+Programmatic usage via `createAgentSession()`. Shows how to customize models, prompts, tools, extensions, and session management.
+
+### [extensions/](extensions/)
+Example extensions demonstrating:
+- Lifecycle event handlers (tool interception, safety gates, context modifications)
+- Custom tools (todo lists, questions, subagents, output truncation)
+- Commands and keyboard shortcuts
+- Custom UI (footers, headers, editors, overlays)
+- Git integration (checkpoints, auto-commit)
+- System prompt modifications and custom compaction
+- External integrations (SSH, file watchers, system theme sync)
+- Custom providers (Anthropic with custom streaming, GitLab Duo)
+
+## Documentation
+
+- [SDK Reference](sdk/README.md)
+- [Extensions Documentation](../docs/extensions.md)
+- [Skills Documentation](../docs/skills.md)

package/examples/extensions/README.md

@@ -0,0 +1,204 @@
+# Extension Examples
+
+Example extensions for pi-coding-agent.
+
+## Usage
+
+```bash
+# Load an extension with --extension flag
+pi --extension examples/extensions/permission-gate.ts
+
+# Or copy to extensions directory for auto-discovery
+cp permission-gate.ts ~/.pi/agent/extensions/
+```
+
+## Examples
+
+### Lifecycle & Safety
+
+| Extension | Description |
+|-----------|-------------|
+| `permission-gate.ts` | Prompts for confirmation before dangerous bash commands (rm -rf, sudo, etc.) |
+| `protected-paths.ts` | Blocks writes to protected paths (.env, .git/, node_modules/) |
+| `confirm-destructive.ts` | Confirms before destructive session actions (clear, switch, fork) |
+| `dirty-repo-guard.ts` | Prevents session changes with uncommitted git changes |
+| `sandbox/` | OS-level sandboxing using `@anthropic-ai/sandbox-runtime` with per-project config |
+
+### Custom Tools
+
+| Extension | Description |
+|-----------|-------------|
+| `todo.ts` | Todo list tool + `/todos` command with custom rendering and state persistence |
+| `hello.ts` | Minimal custom tool example |
+| `question.ts` | Demonstrates `ctx.ui.select()` for asking the user questions with custom UI |
+| `questionnaire.ts` | Multi-question input with tab bar navigation between questions |
+| `tool-override.ts` | Override built-in tools (e.g., add logging/access control to `read`) |
+| `dynamic-tools.ts` | Register tools after startup (`session_start`) and at runtime via command, with prompt snippets and tool-specific prompt guidelines |
+| `built-in-tool-renderer.ts` | Custom compact rendering for built-in tools (read, bash, edit, write) while keeping original behavior |
+| `minimal-mode.ts` | Override built-in tool rendering for minimal display (only tool calls, no output in collapsed mode) |
+| `truncated-tool.ts` | Wraps ripgrep with proper output truncation (50KB/2000 lines) |
+| `ssh.ts` | Delegate all tools to a remote machine via SSH using pluggable operations |
+| `subagent/` | Delegate tasks to specialized subagents with isolated context windows |
+
+### Commands & UI
+
+| Extension | Description |
+|-----------|-------------|
+| `preset.ts` | Named presets for model, thinking level, tools, and instructions via `--preset` flag and `/preset` command |
+| `plan-mode/` | Claude Code-style plan mode for read-only exploration with `/plan` command and step tracking |
+| `tools.ts` | Interactive `/tools` command to enable/disable tools with session persistence |
+| `handoff.ts` | Transfer context to a new focused session via `/handoff <goal>` |
+| `qna.ts` | Extracts questions from last response into editor via `ctx.ui.setEditorText()` |
+| `status-line.ts` | Shows turn progress in footer via `ctx.ui.setStatus()` with themed colors |
+| `widget-placement.ts` | Shows widgets above and below the editor via `ctx.ui.setWidget()` placement |
+| `hidden-thinking-label.ts` | Customizes the collapsed thinking label via `ctx.ui.setHiddenThinkingLabel()` |
+| `model-status.ts` | Shows model changes in status bar via `model_select` hook |
+| `snake.ts` | Snake game with custom UI, keyboard handling, and session persistence |
+| `send-user-message.ts` | Demonstrates `pi.sendUserMessage()` for sending user messages from extensions |
+| `timed-confirm.ts` | Demonstrates AbortSignal for auto-dismissing `ctx.ui.confirm()` and `ctx.ui.select()` dialogs |
+| `rpc-demo.ts` | Exercises all RPC-supported extension UI methods; pair with [`examples/rpc-extension-ui.ts`](../rpc-extension-ui.ts) |
+| `modal-editor.ts` | Custom vim-like modal editor via `ctx.ui.setEditorComponent()` |
+| `rainbow-editor.ts` | Animated rainbow text effect via custom editor |
+| `notify.ts` | Desktop notifications via OSC 777 when agent finishes (Ghostty, iTerm2, WezTerm) |
+| `titlebar-spinner.ts` | Braille spinner animation in terminal title while the agent is working |
+| `summarize.ts` | Summarize conversation with GPT-5.4 and show in transient UI |
+| `custom-footer.ts` | Custom footer with git branch and token stats via `ctx.ui.setFooter()` |
+| `custom-header.ts` | Custom header via `ctx.ui.setHeader()` |
+| `overlay-test.ts` | Test overlay compositing with inline text inputs and edge cases |
+| `overlay-qa-tests.ts` | Comprehensive overlay QA tests: anchors, margins, stacking, overflow, animation |
+| `doom-overlay/` | DOOM game running as an overlay at 35 FPS (demonstrates real-time game rendering) |
+| `shutdown-command.ts` | Adds `/quit` command demonstrating `ctx.shutdown()` |
+| `reload-runtime.ts` | Adds `/reload-runtime` and `reload_runtime` tool showing safe reload flow |
+| `interactive-shell.ts` | Run interactive commands (vim, htop) with full terminal via `user_bash` hook |
+| `inline-bash.ts` | Expands `!{command}` patterns in prompts via `input` event transformation |
+
+### Git Integration
+
+| Extension | Description |
+|-----------|-------------|
+| `git-checkpoint.ts` | Creates git stash checkpoints at each turn for code restoration on fork |
+| `auto-commit-on-exit.ts` | Auto-commits on exit using last assistant message for commit message |
+
+### System Prompt & Compaction
+
+| Extension | Description |
+|-----------|-------------|
+| `pirate.ts` | Demonstrates `systemPromptAppend` to dynamically modify system prompt |
+| `claude-rules.ts` | Scans `.claude/rules/` folder and lists rules in system prompt |
+| `custom-compaction.ts` | Custom compaction that summarizes entire conversation |
+| `trigger-compact.ts` | Triggers compaction when context usage exceeds 100k tokens and adds `/trigger-compact` command |
+
+### System Integration
+
+| Extension | Description |
+|-----------|-------------|
+| `mac-system-theme.ts` | Syncs pi theme with macOS dark/light mode |
+
+### Resources
+
+| Extension | Description |
+|-----------|-------------|
+| `dynamic-resources/` | Loads skills, prompts, and themes using `resources_discover` |
+
+### Messages & Communication
+
+| Extension | Description |
+|-----------|-------------|
+| `message-renderer.ts` | Custom message rendering with colors and expandable details via `registerMessageRenderer` |
+| `event-bus.ts` | Inter-extension communication via `pi.events` |
+
+### Session Metadata
+
+| Extension | Description |
+|-----------|-------------|
+| `session-name.ts` | Name sessions for the session selector via `setSessionName` |
+| `bookmark.ts` | Bookmark entries with labels for `/tree` navigation via `setLabel` |
+
+### Custom Providers
+
+| Extension | Description |
+|-----------|-------------|
+| `custom-provider-anthropic/` | Custom Anthropic provider with OAuth support and custom streaming implementation |
+| `custom-provider-gitlab-duo/` | GitLab Duo provider using pi-ai's built-in Anthropic/OpenAI streaming via proxy |
+
+### External Dependencies
+
+| Extension | Description |
+|-----------|-------------|
+| `with-deps/` | Extension with its own package.json and dependencies (demonstrates jiti module resolution) |
+| `file-trigger.ts` | Watches a trigger file and injects contents into conversation |
+
+## Writing Extensions
+
+See [docs/extensions.md](../../docs/extensions.md) for full documentation.
+
+```typescript
+import type { ExtensionAPI } from "@lenylvt/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+export default function (pi: ExtensionAPI) {
+  // Subscribe to lifecycle events
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
+      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
+      if (!ok) return { block: true, reason: "Blocked by user" };
+    }
+  });
+
+  // Register custom tools
+  pi.registerTool({
+    name: "greet",
+    label: "Greeting",
+    description: "Generate a greeting",
+    parameters: Type.Object({
+      name: Type.String({ description: "Name to greet" }),
+    }),
+    async execute(toolCallId, params, onUpdate, ctx, signal) {
+      return {
+        content: [{ type: "text", text: `Hello, ${params.name}!` }],
+        details: {},
+      };
+    },
+  });
+
+  // Register commands
+  pi.registerCommand("hello", {
+    description: "Say hello",
+    handler: async (args, ctx) => {
+      ctx.ui.notify("Hello!", "info");
+    },
+  });
+}
+```
+
+## Key Patterns
+
+**Use StringEnum for string parameters** (required for Google API compatibility):
+```typescript
+import { StringEnum } from "@lenylvt/pi-ai";
+
+// Good
+action: StringEnum(["list", "add"] as const)
+
+// Bad - doesn't work with Google
+action: Type.Union([Type.Literal("list"), Type.Literal("add")])
+```
+
+**State persistence via details:**
+```typescript
+// Store state in tool result details for proper forking support
+return {
+  content: [{ type: "text", text: "Done" }],
+  details: { todos: [...todos], nextId },  // Persisted in session
+};
+
+// Reconstruct on session events
+pi.on("session_start", async (_event, ctx) => {
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type === "message" && entry.message.toolName === "my_tool") {
+      const details = entry.message.details;
+      // Reconstruct state from details
+    }
+  }
+});
+```

package/examples/extensions/auto-commit-on-exit.ts

@@ -0,0 +1,49 @@
+/**
+ * Auto-Commit on Exit Extension
+ *
+ * Automatically commits changes when the agent exits.
+ * Uses the last assistant message to generate a commit message.
+ */
+
+import type { ExtensionAPI } from "@lenylvt/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_shutdown", async (_event, ctx) => {
+		// Check for uncommitted changes
+		const { stdout: status, code } = await pi.exec("git", ["status", "--porcelain"]);
+
+		if (code !== 0 || status.trim().length === 0) {
+			// Not a git repo or no changes
+			return;
+		}
+
+		// Find the last assistant message for commit context
+		const entries = ctx.sessionManager.getEntries();
+		let lastAssistantText = "";
+		for (let i = entries.length - 1; i >= 0; i--) {
+			const entry = entries[i];
+			if (entry.type === "message" && entry.message.role === "assistant") {
+				const content = entry.message.content;
+				if (Array.isArray(content)) {
+					lastAssistantText = content
+						.filter((c): c is { type: "text"; text: string } => c.type === "text")
+						.map((c) => c.text)
+						.join("\n");
+				}
+				break;
+			}
+		}
+
+		// Generate a simple commit message
+		const firstLine = lastAssistantText.split("\n")[0] || "Work in progress";
+		const commitMessage = `[pi] ${firstLine.slice(0, 50)}${firstLine.length > 50 ? "..." : ""}`;
+
+		// Stage and commit
+		await pi.exec("git", ["add", "-A"]);
+		const { code: commitCode } = await pi.exec("git", ["commit", "-m", commitMessage]);
+
+		if (commitCode === 0 && ctx.hasUI) {
+			ctx.ui.notify(`Auto-committed: ${commitMessage}`, "info");
+		}
+	});
+}

package/examples/extensions/bash-spawn-hook.ts

@@ -0,0 +1,30 @@
+/**
+ * Bash Spawn Hook Example
+ *
+ * Adjusts command, cwd, and env before execution.
+ *
+ * Usage:
+ *   pi -e ./bash-spawn-hook.ts
+ */
+
+import type { ExtensionAPI } from "@lenylvt/pi-coding-agent";
+import { createBashTool } from "@lenylvt/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/examples/extensions/bookmark.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 "@lenylvt/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/examples/extensions/built-in-tool-renderer.ts

@@ -0,0 +1,246 @@
+/**
+ * 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
+ * - 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 "@lenylvt/pi-coding-agent";
+import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@lenylvt/pi-coding-agent";
+import { Text } from "@lenylvt/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,
+
+		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);
+		},
+	});
+}