@mariozechner/pi-coding-agent 0.30.2 → 0.31.0

package/docs/tui.md

@@ -0,0 +1,343 @@
+> pi can create TUI components. Ask it to build one for your use case.
+
+# TUI Components
+
+Hooks and custom tools can render custom TUI components for interactive user interfaces. This page covers the component system and available building blocks.
+
+**Source:** [`@mariozechner/pi-tui`](https://github.com/badlogic/pi-mono/tree/main/packages/tui)
+
+## Component Interface
+
+All components implement:
+
+```typescript
+interface Component {
+  render(width: number): string[];
+  handleInput?(data: string): void;
+  invalidate?(): void;
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `render(width)` | Return array of strings (one per line). Each line **must not exceed `width`**. |
+| `handleInput?(data)` | Receive keyboard input when component has focus. |
+| `invalidate?()` | Clear cached render state. |
+
+## Using Components
+
+**In hooks** via `ctx.ui.custom()`:
+
+```typescript
+pi.on("session_start", async (_event, ctx) => {
+  const handle = ctx.ui.custom(myComponent);
+  // handle.requestRender() - trigger re-render
+  // handle.close() - restore normal UI
+});
+```
+
+**In custom tools** via `pi.ui.custom()`:
+
+```typescript
+async execute(toolCallId, params, onUpdate, ctx, signal) {
+  const handle = pi.ui.custom(myComponent);
+  // ...
+  handle.close();
+}
+```
+
+## Built-in Components
+
+Import from `@mariozechner/pi-tui`:
+
+```typescript
+import { Text, Box, Container, Spacer, Markdown } from "@mariozechner/pi-tui";
+```
+
+### Text
+
+Multi-line text with word wrapping.
+
+```typescript
+const text = new Text(
+  "Hello World",    // content
+  1,                // paddingX (default: 1)
+  1,                // paddingY (default: 1)
+  (s) => bgGray(s)  // optional background function
+);
+text.setText("Updated");
+```
+
+### Box
+
+Container with padding and background color.
+
+```typescript
+const box = new Box(
+  1,                // paddingX
+  1,                // paddingY
+  (s) => bgGray(s)  // background function
+);
+box.addChild(new Text("Content", 0, 0));
+box.setBgFn((s) => bgBlue(s));
+```
+
+### Container
+
+Groups child components vertically.
+
+```typescript
+const container = new Container();
+container.addChild(component1);
+container.addChild(component2);
+container.removeChild(component1);
+```
+
+### Spacer
+
+Empty vertical space.
+
+```typescript
+const spacer = new Spacer(2);  // 2 empty lines
+```
+
+### Markdown
+
+Renders markdown with syntax highlighting.
+
+```typescript
+const md = new Markdown(
+  "# Title\n\nSome **bold** text",
+  1,        // paddingX
+  1,        // paddingY
+  theme     // MarkdownTheme (see below)
+);
+md.setText("Updated markdown");
+```
+
+### Image
+
+Renders images in supported terminals (Kitty, iTerm2, Ghostty, WezTerm).
+
+```typescript
+const image = new Image(
+  base64Data,   // base64-encoded image
+  "image/png",  // MIME type
+  theme,        // ImageTheme
+  { maxWidthCells: 80, maxHeightCells: 24 }
+);
+```
+
+## Keyboard Input
+
+Use key detection helpers:
+
+```typescript
+import {
+  isEnter, isEscape, isTab,
+  isArrowUp, isArrowDown, isArrowLeft, isArrowRight,
+  isCtrlC, isCtrlO, isBackspace, isDelete,
+  // ... and more
+} from "@mariozechner/pi-tui";
+
+handleInput(data: string) {
+  if (isArrowUp(data)) {
+    this.selectedIndex--;
+  } else if (isEnter(data)) {
+    this.onSelect?.(this.selectedIndex);
+  } else if (isEscape(data)) {
+    this.onCancel?.();
+  }
+}
+```
+
+## Line Width
+
+**Critical:** Each line from `render()` must not exceed the `width` parameter.
+
+```typescript
+import { visibleWidth, truncateToWidth } from "@mariozechner/pi-tui";
+
+render(width: number): string[] {
+  // Truncate long lines
+  return [truncateToWidth(this.text, width)];
+}
+```
+
+Utilities:
+- `visibleWidth(str)` - Get display width (ignores ANSI codes)
+- `truncateToWidth(str, width, ellipsis?)` - Truncate with optional ellipsis
+- `wrapTextWithAnsi(str, width)` - Word wrap preserving ANSI codes
+
+## Creating Custom Components
+
+Example: Interactive selector
+
+```typescript
+import {
+  isEnter, isEscape, isArrowUp, isArrowDown,
+  truncateToWidth, visibleWidth
+} from "@mariozechner/pi-tui";
+
+class MySelector {
+  private items: string[];
+  private selected = 0;
+  private cachedWidth?: number;
+  private cachedLines?: string[];
+  
+  public onSelect?: (item: string) => void;
+  public onCancel?: () => void;
+
+  constructor(items: string[]) {
+    this.items = items;
+  }
+
+  handleInput(data: string): void {
+    if (isArrowUp(data) && this.selected > 0) {
+      this.selected--;
+      this.invalidate();
+    } else if (isArrowDown(data) && this.selected < this.items.length - 1) {
+      this.selected++;
+      this.invalidate();
+    } else if (isEnter(data)) {
+      this.onSelect?.(this.items[this.selected]);
+    } else if (isEscape(data)) {
+      this.onCancel?.();
+    }
+  }
+
+  render(width: number): string[] {
+    if (this.cachedLines && this.cachedWidth === width) {
+      return this.cachedLines;
+    }
+
+    this.cachedLines = this.items.map((item, i) => {
+      const prefix = i === this.selected ? "> " : "  ";
+      return truncateToWidth(prefix + item, width);
+    });
+    this.cachedWidth = width;
+    return this.cachedLines;
+  }
+
+  invalidate(): void {
+    this.cachedWidth = undefined;
+    this.cachedLines = undefined;
+  }
+}
+```
+
+Usage in a hook:
+
+```typescript
+pi.registerCommand("pick", {
+  description: "Pick an item",
+  handler: async (args, ctx) => {
+    const items = ["Option A", "Option B", "Option C"];
+    const selector = new MySelector(items);
+    
+    let handle: { close: () => void; requestRender: () => void };
+    
+    await new Promise<void>((resolve) => {
+      selector.onSelect = (item) => {
+        ctx.ui.notify(`Selected: ${item}`, "info");
+        handle.close();
+        resolve();
+      };
+      selector.onCancel = () => {
+        handle.close();
+        resolve();
+      };
+      handle = ctx.ui.custom(selector);
+    });
+  }
+});
+```
+
+## Theming
+
+Components accept theme objects for styling.
+
+**In `renderCall`/`renderResult`**, use the `theme` parameter:
+
+```typescript
+renderResult(result, options, theme) {
+  // Use theme.fg() for foreground colors
+  return new Text(theme.fg("success", "Done!"), 0, 0);
+  
+  // Use theme.bg() for background colors
+  const styled = theme.bg("toolPendingBg", theme.fg("accent", "text"));
+}
+```
+
+**Foreground colors** (`theme.fg(color, text)`):
+
+| Category | Colors |
+|----------|--------|
+| General | `text`, `accent`, `muted`, `dim` |
+| Status | `success`, `error`, `warning` |
+| Borders | `border`, `borderAccent`, `borderMuted` |
+| Messages | `userMessageText`, `customMessageText`, `customMessageLabel` |
+| Tools | `toolTitle`, `toolOutput` |
+| Diffs | `toolDiffAdded`, `toolDiffRemoved`, `toolDiffContext` |
+| Markdown | `mdHeading`, `mdLink`, `mdLinkUrl`, `mdCode`, `mdCodeBlock`, `mdCodeBlockBorder`, `mdQuote`, `mdQuoteBorder`, `mdHr`, `mdListBullet` |
+| Syntax | `syntaxComment`, `syntaxKeyword`, `syntaxFunction`, `syntaxVariable`, `syntaxString`, `syntaxNumber`, `syntaxType`, `syntaxOperator`, `syntaxPunctuation` |
+| Thinking | `thinkingOff`, `thinkingMinimal`, `thinkingLow`, `thinkingMedium`, `thinkingHigh`, `thinkingXhigh` |
+| Modes | `bashMode` |
+
+**Background colors** (`theme.bg(color, text)`):
+
+`selectedBg`, `userMessageBg`, `customMessageBg`, `toolPendingBg`, `toolSuccessBg`, `toolErrorBg`
+
+**For Markdown**, use `getMarkdownTheme()`:
+
+```typescript
+import { getMarkdownTheme } from "@mariozechner/pi-coding-agent";
+import { Markdown } from "@mariozechner/pi-tui";
+
+renderResult(result, options, theme) {
+  const mdTheme = getMarkdownTheme();
+  return new Markdown(result.details.markdown, 0, 0, mdTheme);
+}
+```
+
+**For custom components**, define your own theme interface:
+
+```typescript
+interface MyTheme {
+  selected: (s: string) => string;
+  normal: (s: string) => string;
+}
+```
+
+## Performance
+
+Cache rendered output when possible:
+
+```typescript
+class CachedComponent {
+  private cachedWidth?: number;
+  private cachedLines?: string[];
+
+  render(width: number): string[] {
+    if (this.cachedLines && this.cachedWidth === width) {
+      return this.cachedLines;
+    }
+    // ... compute lines ...
+    this.cachedWidth = width;
+    this.cachedLines = lines;
+    return lines;
+  }
+
+  invalidate(): void {
+    this.cachedWidth = undefined;
+    this.cachedLines = undefined;
+  }
+}
+```
+
+Call `invalidate()` when state changes, then `handle.requestRender()` to trigger re-render.
+
+## Examples
+
+- **Snake game**: [examples/hooks/snake.ts](../examples/hooks/snake.ts) - Full game with keyboard input, game loop, state persistence
+- **Custom tool rendering**: [examples/custom-tools/todo/](../examples/custom-tools/todo/) - Custom `renderCall` and `renderResult`

package/examples/README.md

@@ -1,6 +1,6 @@
 # Examples
 
-Example code for pi-coding-agent.
+Example code for pi-coding-agent SDK, hooks, and custom tools.
 
 ## Directories
 
@@ -13,14 +13,6 @@ Example hooks for intercepting tool calls, adding safety gates, and integrating
 ### [custom-tools/](custom-tools/)
 Example custom tools that extend the agent's capabilities.
 
-## Running Examples
-
-```bash
-cd packages/coding-agent
-npx tsx examples/sdk/01-minimal.ts
-npx tsx examples/hooks/permission-gate.ts
-```
-
 ## Documentation
 
 - [SDK Reference](sdk/README.md)

package/examples/custom-tools/hello/index.ts

@@ -9,10 +9,11 @@ const factory: CustomToolFactory = (_pi) => ({
 		name: Type.String({ description: "Name to greet" }),
 	}),
 
-	async execute(_toolCallId, params) {
+	async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+		const { name } = params as { name: string };
 		return {
-			content: [{ type: "text", text: `Hello, ${params.name}!` }],
-			details: { greeted: params.name },
+			content: [{ type: "text", text: `Hello, ${name}!` }],
+			details: { greeted: name },
 		};
 	},
 });

package/examples/custom-tools/question/index.ts

@@ -2,7 +2,7 @@
  * Question Tool - Let the LLM ask the user a question with options
  */
 
-import type { CustomAgentTool, CustomToolFactory } from "@mariozechner/pi-coding-agent";
+import type { CustomTool, CustomToolFactory } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 
@@ -18,13 +18,13 @@ const QuestionParams = Type.Object({
 });
 
 const factory: CustomToolFactory = (pi) => {
-	const tool: CustomAgentTool<typeof QuestionParams, QuestionDetails> = {
+	const tool: CustomTool<typeof QuestionParams, QuestionDetails> = {
 		name: "question",
 		label: "Question",
 		description: "Ask the user a question and let them pick from options. Use when you need user input to proceed.",
 		parameters: QuestionParams,
 
-		async execute(_toolCallId, params) {
+		async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
 			if (!pi.hasUI) {
 				return {
 					content: [{ type: "text", text: "Error: UI not available (running in non-interactive mode)" }],
@@ -41,7 +41,7 @@ const factory: CustomToolFactory = (pi) => {
 
 			const answer = await pi.ui.select(params.question, params.options);
 
-			if (answer === null) {
+			if (answer === undefined) {
 				return {
 					content: [{ type: "text", text: "User cancelled the selection" }],
 					details: { question: params.question, options: params.options, answer: null },

package/examples/custom-tools/subagent/index.ts

@@ -16,13 +16,14 @@ import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import type { AgentToolResult, Message } from "@mariozechner/pi-ai";
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import type { Message } from "@mariozechner/pi-ai";
 import { StringEnum } from "@mariozechner/pi-ai";
 import {
-	type CustomAgentTool,
+	type CustomTool,
+	type CustomToolAPI,
 	type CustomToolFactory,
 	getMarkdownTheme,
-	type ToolAPI,
 } from "@mariozechner/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
@@ -223,7 +224,7 @@ function writePromptToTempFile(agentName: string, prompt: string): { dir: string
 type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
 
 async function runSingleAgent(
-	pi: ToolAPI,
+	pi: CustomToolAPI,
 	agents: AgentConfig[],
 	agentName: string,
 	task: string,
@@ -410,7 +411,7 @@ const SubagentParams = Type.Object({
 });
 
 const factory: CustomToolFactory = (pi) => {
-	const tool: CustomAgentTool<typeof SubagentParams, SubagentDetails> = {
+	const tool: CustomTool<typeof SubagentParams, SubagentDetails> = {
 		name: "subagent",
 		label: "Subagent",
 		get description() {
@@ -432,7 +433,7 @@ const factory: CustomToolFactory = (pi) => {
 		},
 		parameters: SubagentParams,
 
-		async execute(_toolCallId, params, signal, onUpdate) {
+		async execute(_toolCallId, params, onUpdate, _ctx, signal) {
 			const agentScope: AgentScope = params.agentScope ?? "user";
 			const discovery = discoverAgents(pi.cwd, agentScope);
 			const agents = discovery.agents;

package/examples/custom-tools/todo/index.ts

@@ -9,7 +9,12 @@
  */
 
 import { StringEnum } from "@mariozechner/pi-ai";
-import type { CustomAgentTool, CustomToolFactory, ToolSessionEvent } from "@mariozechner/pi-coding-agent";
+import type {
+	CustomTool,
+	CustomToolContext,
+	CustomToolFactory,
+	CustomToolSessionEvent,
+} from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 
@@ -43,11 +48,12 @@ const factory: CustomToolFactory = (_pi) => {
 	 * Reconstruct state from session entries.
 	 * Scans tool results for this tool and applies them in order.
 	 */
-	const reconstructState = (event: ToolSessionEvent) => {
+	const reconstructState = (_event: CustomToolSessionEvent, ctx: CustomToolContext) => {
 		todos = [];
 		nextId = 1;
 
-		for (const entry of event.entries) {
+		// Use getBranch() to get entries on the current branch
+		for (const entry of ctx.sessionManager.getBranch()) {
 			if (entry.type !== "message") continue;
 			const msg = entry.message;
 
@@ -63,7 +69,7 @@ const factory: CustomToolFactory = (_pi) => {
 		}
 	};
 
-	const tool: CustomAgentTool<typeof TodoParams, TodoDetails> = {
+	const tool: CustomTool<typeof TodoParams, TodoDetails> = {
 		name: "todo",
 		label: "Todo",
 		description: "Manage a todo list. Actions: list, add (text), toggle (id), clear",
@@ -72,7 +78,7 @@ const factory: CustomToolFactory = (_pi) => {
 		// Called on session start/switch/branch/clear
 		onSession: reconstructState,
 
-		async execute(_toolCallId, params) {
+		async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
 			switch (params.action) {
 				case "list":
 					return {

package/examples/hooks/README.md

@@ -2,97 +2,55 @@
 
 Example hooks for pi-coding-agent.
 
-## Examples
-
-### permission-gate.ts
-Prompts for confirmation before running dangerous bash commands (rm -rf, sudo, chmod 777, etc.).
-
-### git-checkpoint.ts
-Creates git stash checkpoints at each turn, allowing code restoration when branching.
-
-### protected-paths.ts
-Blocks writes to protected paths (.env, .git/, node_modules/).
-
-### file-trigger.ts
-Watches a trigger file and injects its contents into the conversation. Useful for external systems (CI, file watchers, webhooks) to send messages to the agent.
-
-### confirm-destructive.ts
-Prompts for confirmation before destructive session actions (clear, switch, branch). Demonstrates how to cancel `before_*` session events.
-
-### dirty-repo-guard.ts
-Prevents session changes when there are uncommitted git changes. Blocks clear/switch/branch until you commit.
-
-### auto-commit-on-exit.ts
-Automatically commits changes when the agent exits (shutdown event). Uses the last assistant message to generate a commit message.
-
-### custom-compaction.ts
-Custom context compaction that summarizes the entire conversation instead of keeping recent turns. Uses the `before_compact` hook event to intercept compaction and generate a comprehensive summary using `complete()` from the AI package. Useful when you want maximum context window space at the cost of losing exact conversation history.
-
 ## Usage
 
 ```bash
-# Test directly
+# Load a hook with --hook flag
 pi --hook examples/hooks/permission-gate.ts
 
-# Or copy to hooks directory for persistent use
+# Or copy to hooks directory for auto-discovery
 cp permission-gate.ts ~/.pi/agent/hooks/
 ```
 
+## Examples
+
+| Hook | Description |
+|------|-------------|
+| `permission-gate.ts` | Prompts for confirmation before dangerous bash commands (rm -rf, sudo, etc.) |
+| `git-checkpoint.ts` | Creates git stash checkpoints at each turn for code restoration on branch |
+| `protected-paths.ts` | Blocks writes to protected paths (.env, .git/, node_modules/) |
+| `file-trigger.ts` | Watches a trigger file and injects contents into conversation |
+| `confirm-destructive.ts` | Confirms before destructive session actions (clear, switch, branch) |
+| `dirty-repo-guard.ts` | Prevents session changes with uncommitted git changes |
+| `auto-commit-on-exit.ts` | Auto-commits on exit using last assistant message for commit message |
+| `custom-compaction.ts` | Custom compaction that summarizes entire conversation |
+| `qna.ts` | Extracts questions from last response into editor via `ctx.ui.setEditorText()` |
+| `snake.ts` | Snake game with custom UI, keyboard handling, and session persistence |
+| `status-line.ts` | Shows turn progress in footer via `ctx.ui.setStatus()` with themed colors |
+| `handoff.ts` | Transfer context to a new focused session via `/handoff <goal>` |
+
 ## Writing Hooks
 
 See [docs/hooks.md](../../docs/hooks.md) for full documentation.
 
-### Key Points
-
-**Hook structure:**
 ```typescript
 import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
 
 export default function (pi: HookAPI) {
-  pi.on("session", async (event, ctx) => {
-    // event.reason: "start" | "before_switch" | "switch" | "before_clear" | "clear" |
-    //               "before_branch" | "branch" | "shutdown"
-    // event.targetTurnIndex: number (only for before_branch/branch)
-    // ctx.ui, ctx.exec, ctx.cwd, ctx.sessionFile, ctx.hasUI
-
-    // Cancel before_* actions:
-    if (event.reason === "before_clear") {
-      return { cancel: true };
-    }
-    return undefined;
-  });
-
+  // Subscribe to events
   pi.on("tool_call", async (event, ctx) => {
-    // Can block tool execution
-    if (dangerous) {
-      return { block: true, reason: "Blocked" };
+    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" };
     }
-    return undefined;
   });
 
-  pi.on("tool_result", async (event, ctx) => {
-    // Can modify result
-    return { result: "modified result" };
+  // Register custom commands
+  pi.registerCommand("hello", {
+    description: "Say hello",
+    handler: async (args, ctx) => {
+      ctx.ui.notify("Hello!", "info");
+    },
   });
 }
 ```
-
-**Available events:**
-- `session` - lifecycle events with before/after variants (can cancel before_* actions)
-- `agent_start` / `agent_end` - per user prompt
-- `turn_start` / `turn_end` - per LLM turn
-- `tool_call` - before tool execution (can block)
-- `tool_result` - after tool execution (can modify)
-
-**UI methods:**
-```typescript
-const choice = await ctx.ui.select("Title", ["Option A", "Option B"]);
-const confirmed = await ctx.ui.confirm("Title", "Are you sure?");
-const input = await ctx.ui.input("Title", "placeholder");
-ctx.ui.notify("Message", "info"); // or "warning", "error"
-```
-
-**Sending messages:**
-```typescript
-pi.send("Message to inject into conversation");
-```

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

@@ -5,14 +5,12 @@
  * Uses the last assistant message to generate a commit message.
  */
 
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI } from "@mariozechner/pi-coding-agent";
 
 export default function (pi: HookAPI) {
-	pi.on("session", async (event, ctx) => {
-		if (event.reason !== "shutdown") return;
-
+	pi.on("session_shutdown", async (_event, ctx) => {
 		// Check for uncommitted changes
-		const { stdout: status, code } = await ctx.exec("git", ["status", "--porcelain"]);
+		const { stdout: status, code } = await pi.exec("git", ["status", "--porcelain"]);
 
 		if (code !== 0 || status.trim().length === 0) {
 			// Not a git repo or no changes
@@ -20,9 +18,10 @@ export default function (pi: HookAPI) {
 		}
 
 		// Find the last assistant message for commit context
+		const entries = ctx.sessionManager.getEntries();
 		let lastAssistantText = "";
-		for (let i = event.entries.length - 1; i >= 0; i--) {
-			const entry = event.entries[i];
+		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)) {
@@ -40,8 +39,8 @@ export default function (pi: HookAPI) {
 		const commitMessage = `[pi] ${firstLine.slice(0, 50)}${firstLine.length > 50 ? "..." : ""}`;
 
 		// Stage and commit
-		await ctx.exec("git", ["add", "-A"]);
-		const { code: commitCode } = await ctx.exec("git", ["commit", "-m", commitMessage]);
+		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");