open-pi-coding-agent 0.57.1

package/docs/themes.md

@@ -0,0 +1,295 @@
+> pi can create themes. Ask it to build one for your setup.
+
+# Themes
+
+Themes are JSON files that define colors for the TUI.
+
+## Table of Contents
+
+- [Locations](#locations)
+- [Selecting a Theme](#selecting-a-theme)
+- [Creating a Custom Theme](#creating-a-custom-theme)
+- [Theme Format](#theme-format)
+- [Color Tokens](#color-tokens)
+- [Color Values](#color-values)
+- [Tips](#tips)
+
+## Locations
+
+Pi loads themes from:
+
+- Built-in: `dark`, `light`
+- Global: `~/.pi/agent/themes/*.json`
+- Project: `.pi/themes/*.json`
+- Packages: `themes/` directories or `pi.themes` entries in `package.json`
+- Settings: `themes` array with files or directories
+- CLI: `--theme <path>` (repeatable)
+
+Disable discovery with `--no-themes`.
+
+## Selecting a Theme
+
+Select a theme via `/settings` or in `settings.json`:
+
+```json
+{
+  "theme": "my-theme"
+}
+```
+
+On first run, pi detects your terminal background and defaults to `dark` or `light`.
+
+## Creating a Custom Theme
+
+1. Create a theme file:
+
+```bash
+mkdir -p ~/.pi/agent/themes
+vim ~/.pi/agent/themes/my-theme.json
+```
+
+2. Define the theme with all required colors (see [Color Tokens](#color-tokens)):
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "name": "my-theme",
+  "vars": {
+    "primary": "#00aaff",
+    "secondary": 242
+  },
+  "colors": {
+    "accent": "primary",
+    "border": "primary",
+    "borderAccent": "#00ffff",
+    "borderMuted": "secondary",
+    "success": "#00ff00",
+    "error": "#ff0000",
+    "warning": "#ffff00",
+    "muted": "secondary",
+    "dim": 240,
+    "text": "",
+    "thinkingText": "secondary",
+    "selectedBg": "#2d2d30",
+    "userMessageBg": "#2d2d30",
+    "userMessageText": "",
+    "customMessageBg": "#2d2d30",
+    "customMessageText": "",
+    "customMessageLabel": "primary",
+    "toolPendingBg": "#1e1e2e",
+    "toolSuccessBg": "#1e2e1e",
+    "toolErrorBg": "#2e1e1e",
+    "toolTitle": "primary",
+    "toolOutput": "",
+    "mdHeading": "#ffaa00",
+    "mdLink": "primary",
+    "mdLinkUrl": "secondary",
+    "mdCode": "#00ffff",
+    "mdCodeBlock": "",
+    "mdCodeBlockBorder": "secondary",
+    "mdQuote": "secondary",
+    "mdQuoteBorder": "secondary",
+    "mdHr": "secondary",
+    "mdListBullet": "#00ffff",
+    "toolDiffAdded": "#00ff00",
+    "toolDiffRemoved": "#ff0000",
+    "toolDiffContext": "secondary",
+    "syntaxComment": "secondary",
+    "syntaxKeyword": "primary",
+    "syntaxFunction": "#00aaff",
+    "syntaxVariable": "#ffaa00",
+    "syntaxString": "#00ff00",
+    "syntaxNumber": "#ff00ff",
+    "syntaxType": "#00aaff",
+    "syntaxOperator": "primary",
+    "syntaxPunctuation": "secondary",
+    "thinkingOff": "secondary",
+    "thinkingMinimal": "primary",
+    "thinkingLow": "#00aaff",
+    "thinkingMedium": "#00ffff",
+    "thinkingHigh": "#ff00ff",
+    "thinkingXhigh": "#ff0000",
+    "bashMode": "#ffaa00"
+  }
+}
+```
+
+3. Select the theme via `/settings`.
+
+**Hot reload:** When you edit the currently active custom theme file, pi reloads it automatically for immediate visual feedback.
+
+## Theme Format
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "name": "my-theme",
+  "vars": {
+    "blue": "#0066cc",
+    "gray": 242
+  },
+  "colors": {
+    "accent": "blue",
+    "muted": "gray",
+    "text": "",
+    ...
+  }
+}
+```
+
+- `name` is required and must be unique.
+- `vars` is optional. Define reusable colors here, then reference them in `colors`.
+- `colors` must define all 51 required tokens.
+
+The `$schema` field enables editor auto-completion and validation.
+
+## Color Tokens
+
+Every theme must define all 51 color tokens. There are no optional colors.
+
+### Core UI (11 colors)
+
+| Token | Purpose |
+|-------|---------|
+| `accent` | Primary accent (logo, selected items, cursor) |
+| `border` | Normal borders |
+| `borderAccent` | Highlighted borders |
+| `borderMuted` | Subtle borders (editor) |
+| `success` | Success states |
+| `error` | Error states |
+| `warning` | Warning states |
+| `muted` | Secondary text |
+| `dim` | Tertiary text |
+| `text` | Default text (usually `""`) |
+| `thinkingText` | Thinking block text |
+
+### Backgrounds & Content (11 colors)
+
+| Token | Purpose |
+|-------|---------|
+| `selectedBg` | Selected line background |
+| `userMessageBg` | User message background |
+| `userMessageText` | User message text |
+| `customMessageBg` | Extension message background |
+| `customMessageText` | Extension message text |
+| `customMessageLabel` | Extension message label |
+| `toolPendingBg` | Tool box (pending) |
+| `toolSuccessBg` | Tool box (success) |
+| `toolErrorBg` | Tool box (error) |
+| `toolTitle` | Tool title |
+| `toolOutput` | Tool output text |
+
+### Markdown (10 colors)
+
+| Token | Purpose |
+|-------|---------|
+| `mdHeading` | Headings |
+| `mdLink` | Link text |
+| `mdLinkUrl` | Link URL |
+| `mdCode` | Inline code |
+| `mdCodeBlock` | Code block content |
+| `mdCodeBlockBorder` | Code block fences |
+| `mdQuote` | Blockquote text |
+| `mdQuoteBorder` | Blockquote border |
+| `mdHr` | Horizontal rule |
+| `mdListBullet` | List bullets |
+
+### Tool Diffs (3 colors)
+
+| Token | Purpose |
+|-------|---------|
+| `toolDiffAdded` | Added lines |
+| `toolDiffRemoved` | Removed lines |
+| `toolDiffContext` | Context lines |
+
+### Syntax Highlighting (9 colors)
+
+| Token | Purpose |
+|-------|---------|
+| `syntaxComment` | Comments |
+| `syntaxKeyword` | Keywords |
+| `syntaxFunction` | Function names |
+| `syntaxVariable` | Variables |
+| `syntaxString` | Strings |
+| `syntaxNumber` | Numbers |
+| `syntaxType` | Types |
+| `syntaxOperator` | Operators |
+| `syntaxPunctuation` | Punctuation |
+
+### Thinking Level Borders (6 colors)
+
+Editor border colors indicating thinking level (visual hierarchy from subtle to prominent):
+
+| Token | Purpose |
+|-------|---------|
+| `thinkingOff` | Thinking off |
+| `thinkingMinimal` | Minimal thinking |
+| `thinkingLow` | Low thinking |
+| `thinkingMedium` | Medium thinking |
+| `thinkingHigh` | High thinking |
+| `thinkingXhigh` | Extra high thinking |
+
+### Bash Mode (1 color)
+
+| Token | Purpose |
+|-------|---------|
+| `bashMode` | Editor border in bash mode (`!` prefix) |
+
+### HTML Export (optional)
+
+The `export` section controls colors for `/export` HTML output. If omitted, colors are derived from `userMessageBg`.
+
+```json
+{
+  "export": {
+    "pageBg": "#18181e",
+    "cardBg": "#1e1e24",
+    "infoBg": "#3c3728"
+  }
+}
+```
+
+## Color Values
+
+Four formats are supported:
+
+| Format | Example | Description |
+|--------|---------|-------------|
+| Hex | `"#ff0000"` | 6-digit hex RGB |
+| 256-color | `39` | xterm 256-color palette index (0-255) |
+| Variable | `"primary"` | Reference to a `vars` entry |
+| Default | `""` | Terminal's default color |
+
+### 256-Color Palette
+
+- `0-15`: Basic ANSI colors (terminal-dependent)
+- `16-231`: 6×6×6 RGB cube (`16 + 36×R + 6×G + B` where R,G,B are 0-5)
+- `232-255`: Grayscale ramp
+
+### Terminal Compatibility
+
+Pi uses 24-bit RGB colors. Most modern terminals support this (iTerm2, Kitty, WezTerm, Windows Terminal, VS Code). For older terminals with only 256-color support, pi falls back to the nearest approximation.
+
+Check truecolor support:
+
+```bash
+echo $COLORTERM  # Should output "truecolor" or "24bit"
+```
+
+## Tips
+
+**Dark terminals:** Use bright, saturated colors with higher contrast.
+
+**Light terminals:** Use darker, muted colors with lower contrast.
+
+**Color harmony:** Start with a base palette (Nord, Gruvbox, Tokyo Night), define it in `vars`, and reference consistently.
+
+**Testing:** Check your theme with different message types, tool states, markdown content, and long wrapped text.
+
+**VS Code:** Set `terminal.integrated.minimumContrastRatio` to `1` for accurate colors.
+
+## Examples
+
+See the built-in themes:
+- [dark.json](../src/modes/interactive/theme/dark.json)
+- [light.json](../src/modes/interactive/theme/light.json)

package/docs/tmux.md

@@ -0,0 +1,61 @@
+# tmux Setup
+
+Pi works inside tmux, but tmux strips modifier information from certain keys by default. Without configuration, `Shift+Enter` and `Ctrl+Enter` are usually indistinguishable from plain `Enter`.
+
+## Recommended Configuration
+
+Add to `~/.tmux.conf`:
+
+```tmux
+set -g extended-keys on
+set -g extended-keys-format csi-u
+```
+
+Then restart tmux fully:
+
+```bash
+tmux kill-server
+tmux
+```
+
+Pi requests extended key reporting automatically when Kitty keyboard protocol is not available. With `extended-keys-format csi-u`, tmux forwards modified keys in CSI-u format, which is the most reliable configuration.
+
+## Why `csi-u` Is Recommended
+
+With only:
+
+```tmux
+set -g extended-keys on
+```
+
+tmux defaults to `extended-keys-format xterm`. When an application requests extended key reporting, modified keys are forwarded in xterm `modifyOtherKeys` format such as:
+
+- `Ctrl+C` → `\x1b[27;5;99~`
+- `Ctrl+D` → `\x1b[27;5;100~`
+- `Ctrl+Enter` → `\x1b[27;5;13~`
+
+With `extended-keys-format csi-u`, the same keys are forwarded as:
+
+- `Ctrl+C` → `\x1b[99;5u`
+- `Ctrl+D` → `\x1b[100;5u`
+- `Ctrl+Enter` → `\x1b[13;5u`
+
+Pi supports both formats, but `csi-u` is the recommended tmux setup.
+
+## What This Fixes
+
+Without tmux extended keys, modified Enter keys collapse to legacy sequences:
+
+| Key | Without extkeys | With `csi-u` |
+|-----|-----------------|--------------|
+| Enter | `\r` | `\r` |
+| Shift+Enter | `\r` | `\x1b[13;2u` |
+| Ctrl+Enter | `\r` | `\x1b[13;5u` |
+| Alt/Option+Enter | `\x1b\r` | `\x1b[13;3u` |
+
+This affects the default keybindings (`Enter` to submit, `Shift+Enter` for newline) and any custom keybindings using modified Enter.
+
+## Requirements
+
+- tmux 3.2 or later (run `tmux -V` to check)
+- A terminal emulator that supports extended keys (Ghostty, Kitty, iTerm2, WezTerm, Windows Terminal)

package/docs/tree.md

@@ -0,0 +1,228 @@
+# 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 `/fork`
+
+| Feature | `/fork` | `/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_fork` / `session_fork` | `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) |
+| ←/→ | Page up/down |
+| Ctrl+←/Ctrl+→ or Alt+←/Alt+→ | Fold/unfold and jump between branch segments |
+| Enter | Select node |
+| Escape/Ctrl+C | Cancel |
+| Ctrl+U | Toggle: user messages only |
+| Ctrl+O | Toggle: show all (including custom/label entries) |
+
+`Ctrl+←` or `Alt+←` folds the current node if it is foldable. Foldable nodes are roots and branch segment starts that have visible children. If the current node is not foldable, or is already folded, the selection jumps up to the previous visible branch segment start.
+
+`Ctrl+→` or `Alt+→` unfolds the current node if it is folded. Otherwise, the selection jumps down to the next visible branch segment start, or to the branch end when there is no further branch point.
+
+### Display
+
+- Height: half terminal height
+- Current leaf marked with `← active`
+- Labels shown inline: `[label-name]`
+- Foldable branch starts show `⊟` in the connector. Folded branches show `⊞`
+- Active path marker `•` appears after the fold indicator when applicable
+- Search and filter changes reset all folds
+- 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 branches, user is presented with three options:
+
+1. **No summary** - Switch immediately without summarizing
+2. **Summarize** - Generate a summary using the default prompt
+3. **Summarize with custom prompt** - Opens an editor to enter additional focus instructions that are appended to the default summarization prompt
+
+### 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;
+    replaceInstructions?: boolean;
+    label?: string;
+  }
+): Promise<{ editorText?: string; cancelled: boolean }>
+```
+
+Options:
+- `summarize`: Whether to generate a summary of the abandoned branch
+- `customInstructions`: Custom instructions for the summarizer
+- `replaceInstructions`: If true, `customInstructions` replaces the default prompt instead of being appended
+- `label`: Label to attach to the branch summary entry (or target entry if not summarizing)
+
+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;
+  customInstructions?: string;
+  replaceInstructions?: boolean;
+  label?: string;
+}
+
+interface SessionBeforeTreeEvent {
+  type: "session_before_tree";
+  preparation: TreePreparation;
+  signal: AbortSignal;
+}
+
+interface SessionBeforeTreeResult {
+  cancel?: boolean;
+  summary?: { summary: string; details?: unknown };
+  customInstructions?: string;    // Override custom instructions
+  replaceInstructions?: boolean;  // Override replace mode
+  label?: string;                 // Override label
+}
+```
+
+Extensions can override `customInstructions`, `replaceInstructions`, and `label` by returning them from the `session_before_tree` handler.
+
+### `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