@oh-my-pi/pi-coding-agent 1.337.0

package/docs/tree.md

@@ -0,0 +1,197 @@
+# Session Tree Navigation
+
+The `/tree` command provides tree-based navigation of the session history.
+
+## Overview
+
+Sessions are stored as trees where each entry has an `id` and `parentId`. The "leaf" pointer tracks the current position. `/tree` lets you navigate to any point and optionally summarize the branch you're leaving.
+
+### Comparison with `/branch`
+
+| Feature | `/branch` | `/tree` |
+|---------|-----------|---------|
+| View | Flat list of user messages | Full tree structure |
+| Action | Extracts path to **new session file** | Changes leaf in **same session** |
+| Summary | Never | Optional (user prompted) |
+| Events | `session_before_branch` / `session_branch` | `session_before_tree` / `session_tree` |
+
+## Tree UI
+
+```
+├─ user: "Hello, can you help..."
+│  └─ assistant: "Of course! I can..."
+│     ├─ user: "Let's try approach A..."
+│     │  └─ assistant: "For approach A..."
+│     │     └─ [compaction: 12k tokens]
+│     │        └─ user: "That worked..."  ← active
+│     └─ user: "Actually, approach B..."
+│        └─ assistant: "For approach B..."
+```
+
+### Controls
+
+| Key | Action |
+|-----|--------|
+| ↑/↓ | Navigate (depth-first order) |
+| Enter | Select node |
+| Escape/Ctrl+C | Cancel |
+| Ctrl+U | Toggle: user messages only |
+| Ctrl+O | Toggle: show all (including custom/label entries) |
+
+### Display
+
+- Height: half terminal height
+- Current leaf marked with `← active`
+- Labels shown inline: `[label-name]`
+- Default filter hides `label` and `custom` entries (shown in Ctrl+O mode)
+- Children sorted by timestamp (oldest first)
+
+## Selection Behavior
+
+### User Message or Custom Message
+1. Leaf set to **parent** of selected node (or `null` if root)
+2. Message text placed in **editor** for re-submission
+3. User edits and submits, creating a new branch
+
+### Non-User Message (assistant, compaction, etc.)
+1. Leaf set to **selected node**
+2. Editor stays empty
+3. User continues from that point
+
+### Selecting Root User Message
+If user selects the very first message (has no parent):
+1. Leaf reset to `null` (empty conversation)
+2. Message text placed in editor
+3. User effectively restarts from scratch
+
+## Branch Summarization
+
+When switching, user is prompted: "Summarize the branch you're leaving?"
+
+### What Gets Summarized
+
+Path from old leaf back to common ancestor with target:
+
+```
+A → B → C → D → E → F  ← old leaf
+        ↘ G → H        ← target
+```
+
+Abandoned path: D → E → F (summarized)
+
+Summarization stops at:
+1. Common ancestor (always)
+2. Compaction node (if encountered first)
+
+### Summary Storage
+
+Stored as `BranchSummaryEntry`:
+
+```typescript
+interface BranchSummaryEntry {
+  type: "branch_summary";
+  id: string;
+  parentId: string;      // New leaf position
+  timestamp: string;
+  fromId: string;        // Old leaf we abandoned
+  summary: string;       // LLM-generated summary
+  details?: unknown;     // Optional hook data
+}
+```
+
+## Implementation
+
+### AgentSession.navigateTree()
+
+```typescript
+async navigateTree(
+  targetId: string,
+  options?: { summarize?: boolean; customInstructions?: string }
+): Promise<{ editorText?: string; cancelled: boolean }>
+```
+
+Flow:
+1. Validate target, check no-op (target === current leaf)
+2. Find common ancestor between old leaf and target
+3. Collect entries to summarize (if requested)
+4. Fire `session_before_tree` event (hook can cancel or provide summary)
+5. Run default summarizer if needed
+6. Switch leaf via `branch()` or `branchWithSummary()`
+7. Update agent: `agent.replaceMessages(sessionManager.buildSessionContext().messages)`
+8. Fire `session_tree` event
+9. Notify custom tools via session event
+10. Return result with `editorText` if user message was selected
+
+### SessionManager
+
+- `getLeafUuid(): string | null` - Current leaf (null if empty)
+- `resetLeaf(): void` - Set leaf to null (for root user message navigation)
+- `getTree(): SessionTreeNode[]` - Full tree with children sorted by timestamp
+- `branch(id)` - Change leaf pointer
+- `branchWithSummary(id, summary)` - Change leaf and create summary entry
+
+### InteractiveMode
+
+`/tree` command shows `TreeSelectorComponent`, then:
+1. Prompt for summarization
+2. Call `session.navigateTree()`
+3. Clear and re-render chat
+4. Set editor text if applicable
+
+## Hook Events
+
+### `session_before_tree`
+
+```typescript
+interface TreePreparation {
+  targetId: string;
+  oldLeafId: string | null;
+  commonAncestorId: string | null;
+  entriesToSummarize: SessionEntry[];
+  userWantsSummary: boolean;
+}
+
+interface SessionBeforeTreeEvent {
+  type: "session_before_tree";
+  preparation: TreePreparation;
+  model: Model;
+  signal: AbortSignal;
+}
+
+interface SessionBeforeTreeResult {
+  cancel?: boolean;
+  summary?: { summary: string; details?: unknown };
+}
+```
+
+### `session_tree`
+
+```typescript
+interface SessionTreeEvent {
+  type: "session_tree";
+  newLeafId: string | null;
+  oldLeafId: string | null;
+  summaryEntry?: BranchSummaryEntry;
+  fromHook?: boolean;
+}
+```
+
+### Example: Custom Summarizer
+
+```typescript
+export default function(pi: HookAPI) {
+  pi.on("session_before_tree", async (event, ctx) => {
+    if (!event.preparation.userWantsSummary) return;
+    if (event.preparation.entriesToSummarize.length === 0) return;
+    
+    const summary = await myCustomSummarizer(event.preparation.entriesToSummarize);
+    return { summary: { summary, details: { custom: true } } };
+  });
+}
+```
+
+## Error Handling
+
+- Summarization failure: cancels navigation, shows error
+- User abort (Escape): cancels navigation
+- Hook returns `cancel: true`: cancels navigation silently

package/docs/tui.md

@@ -0,0 +1,341 @@
+> 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:** [`@oh-my-pi/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 `@oh-my-pi/pi-tui`:
+
+```typescript
+import { Text, Box, Container, Spacer, Markdown } from "@oh-my-pi/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 "@oh-my-pi/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 "@oh-my-pi/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 "@oh-my-pi/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 "@oh-my-pi/pi-coding-agent";
+import { Markdown } from "@oh-my-pi/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

@@ -0,0 +1,21 @@
+# Examples
+
+Example code for pi-coding-agent SDK, hooks, and custom tools.
+
+## Directories
+
+### [sdk/](sdk/)
+Programmatic usage via `createAgentSession()`. Shows how to customize models, prompts, tools, hooks, and session management.
+
+### [hooks/](hooks/)
+Example hooks for intercepting tool calls, adding safety gates, and integrating with external systems.
+
+### [custom-tools/](custom-tools/)
+Example custom tools that extend the agent's capabilities.
+
+## Documentation
+
+- [SDK Reference](sdk/README.md)
+- [Hooks Documentation](../docs/hooks.md)
+- [Custom Tools Documentation](../docs/custom-tools.md)
+- [Skills Documentation](../docs/skills.md)

package/examples/custom-tools/README.md

@@ -0,0 +1,124 @@
+# Custom Tools Examples
+
+Example custom tools for pi-coding-agent.
+
+## Examples
+
+Each example uses the `subdirectory/index.ts` structure required for tool discovery.
+
+### hello/
+
+Minimal example showing the basic structure of a custom tool.
+
+### question/
+
+Demonstrates `pi.ui.select()` for asking the user questions with options.
+
+### todo/
+
+Full-featured example demonstrating:
+
+- `onSession` for state reconstruction from session history
+- Custom `renderCall` and `renderResult`
+- Proper branching support via details storage
+- State management without external files
+
+### subagent/
+
+Delegate tasks to specialized subagents with isolated context windows. Includes:
+
+- `index.ts` - The custom tool (single, parallel, and chain modes)
+- `agents.ts` - Agent discovery helper
+- `agents/` - Sample agent definitions (scout, planner, reviewer, worker)
+- `commands/` - Workflow presets (/implement, /scout-and-plan, /implement-and-review)
+
+See [subagent/README.md](subagent/README.md) for full documentation.
+
+## Usage
+
+```bash
+# Test directly (can point to any .ts file)
+pi --tool examples/custom-tools/todo/index.ts
+
+# Or copy entire folder to tools directory for persistent use
+cp -r todo ~/.pi/agent/tools/
+```
+
+Then in pi:
+
+```
+> add a todo "test custom tools"
+> list todos
+> toggle todo #1
+> clear todos
+```
+
+## Writing Custom Tools
+
+See [docs/custom-tools.md](../../docs/custom-tools.md) for full documentation.
+
+### Key Points
+
+**Factory pattern:**
+
+```typescript
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@oh-my-pi/pi-ai";
+import { Text } from "@oh-my-pi/pi-tui";
+import type { CustomToolFactory } from "@oh-my-pi/pi-coding-agent";
+
+const factory: CustomToolFactory = (pi) => ({
+	name: "my_tool",
+	label: "My Tool",
+	description: "Tool description for LLM",
+	parameters: Type.Object({
+		action: StringEnum(["list", "add"] as const),
+	}),
+
+	// Called on session start/switch/branch/clear
+	onSession(event) {
+		// Reconstruct state from event.entries
+	},
+
+	async execute(toolCallId, params) {
+		return {
+			content: [{ type: "text", text: "Result" }],
+			details: {
+				/* for rendering and state reconstruction */
+			},
+		};
+	},
+});
+
+export default factory;
+```
+
+**Custom rendering:**
+
+```typescript
+renderCall(args, theme) {
+  return new Text(
+    theme.fg("toolTitle", theme.bold("my_tool ")) + args.action,
+    0, 0  // No padding - Box handles it
+  );
+},
+
+renderResult(result, { expanded, isPartial }, theme) {
+  if (isPartial) {
+    return new Text(theme.fg("warning", "Working..."), 0, 0);
+  }
+  return new Text(theme.fg("success", "✓ Done"), 0, 0);
+},
+```
+
+**Use StringEnum for string parameters** (required for Google API compatibility):
+
+```typescript
+import { StringEnum } from "@oh-my-pi/pi-ai";
+
+// Good
+action: StringEnum(["list", "add"] as const);
+
+// Bad - doesn't work with Google
+action: Type.Union([Type.Literal("list"), Type.Literal("add")]);
+```

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

@@ -0,0 +1,20 @@
+import type { CustomToolFactory } from "@oh-my-pi/pi-coding-agent";
+
+const factory: CustomToolFactory = (pi) => ({
+	name: "hello",
+	label: "Hello",
+	description: "A simple greeting tool",
+	parameters: pi.typebox.Type.Object({
+		name: pi.typebox.Type.String({ description: "Name to greet" }),
+	}),
+
+	async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+		const { name } = params;
+		return {
+			content: [{ type: "text", text: `Hello, ${name}!` }],
+			details: { greeted: name },
+		};
+	},
+});
+
+export default factory;