@mariozechner/pi-coding-agent 0.23.2 → 0.23.4

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 ## [Unreleased]
 
+## [0.23.4] - 2025-12-18
+
+### Added
+
+- **Syntax highlighting**: Added syntax highlighting for markdown code blocks, read tool output, and write tool content. Uses cli-highlight with theme-aware color mapping and VS Code-style syntax colors. ([#214](https://github.com/badlogic/pi-mono/pull/214) by [@svkozak](https://github.com/svkozak))
+
+- **Intra-line diff highlighting**: Edit tool now shows word-level changes with inverse highlighting when a single line is modified. Multi-line changes show all removed lines first, then all added lines.
+
+### Fixed
+
+- **Gemini tool result format**: Fixed tool result format for Gemini 3 Flash Preview which strictly requires `{ output: value }` for success and `{ error: value }` for errors. Previous format using `{ result, isError }` was rejected by newer Gemini models. ([#213](https://github.com/badlogic/pi-mono/issues/213), [#220](https://github.com/badlogic/pi-mono/pull/220))
+
+- **Google baseUrl configuration**: Google provider now respects `baseUrl` configuration for custom endpoints or API proxies. ([#216](https://github.com/badlogic/pi-mono/issues/216), [#221](https://github.com/badlogic/pi-mono/pull/221) by [@theBucky](https://github.com/theBucky))
+
+- **Google provider FinishReason**: Added handling for new `IMAGE_RECITATION` and `IMAGE_OTHER` finish reasons. Upgraded @google/genai to 1.34.0.
+
+## [0.23.3] - 2025-12-17
+
+### Fixed
+
+- Check for compaction before submitting user prompt, not just after agent turn ends. This catches cases where user aborts mid-response and context is already near the limit.
+
+### Changed
+
+- Improved system prompt documentation section with clearer pointers to specific doc files for custom models, themes, skills, hooks, custom tools, and RPC.
+
+- Cleaned up documentation:
+  - `theme.md`: Added missing color tokens (`thinkingXhigh`, `bashMode`)
+  - `skills.md`: Rewrote with better framing and examples
+  - `hooks.md`: Fixed timeout/error handling docs, added import aliases section
+  - `custom-tools.md`: Added intro with use cases and comparison table
+  - `rpc.md`: Added missing `hook_error` event documentation
+  - `README.md`: Complete settings table, condensed philosophy section, standardized OAuth docs
+
+- Hooks loader now supports same import aliases as custom tools (`@sinclair/typebox`, `@mariozechner/pi-ai`, `@mariozechner/pi-tui`, `@mariozechner/pi-coding-agent`).
+
+### Breaking Changes
+
+- **Hooks**: `turn_end` event's `toolResults` type changed from `AppMessage[]` to `ToolResultMessage[]`. If you have hooks that handle `turn_end` events and explicitly type the results, update your type annotations.
+
 ## [0.23.2] - 2025-12-17
 
 ### Fixed

package/README.md

@@ -9,7 +9,7 @@ Works on Linux, macOS, and Windows (requires bash; see [Windows Setup](#windows-
 - [Getting Started](#getting-started)
   - [Installation](#installation)
   - [Windows Setup](#windows-setup)
-  - [API Keys](#api-keys)
+  - [API Keys & OAuth](#api-keys--oauth)
   - [Quick Start](#quick-start)
 - [Usage](#usage)
   - [Slash Commands](#slash-commands)
@@ -101,13 +101,13 @@ For most users, [Git for Windows](https://git-scm.com/download/win) is sufficien
 }
 ```
 
-### API Keys
+### API Keys & OAuth
 
 Set the environment variable for your provider:
 
 | Provider | Environment Variable |
 |----------|---------------------|
-| Anthropic | `ANTHROPIC_API_KEY` or `ANTHROPIC_OAUTH_TOKEN` |
+| Anthropic | `ANTHROPIC_API_KEY` |
 | OpenAI | `OPENAI_API_KEY` |
 | Google | `GEMINI_API_KEY` |
 | Mistral | `MISTRAL_API_KEY` |
@@ -117,31 +117,27 @@ Set the environment variable for your provider:
 | OpenRouter | `OPENROUTER_API_KEY` |
 | ZAI | `ZAI_API_KEY` |
 
-The `/model` command only shows models for providers with configured API keys.
-
-**OAuth (Claude Pro/Max subscribers):**
+**Anthropic OAuth (Claude Pro/Max):**
 
 ```bash
 pi
 /login  # Select "Anthropic (Claude Pro/Max)", authorize in browser
 ```
 
-Tokens stored in `~/.pi/agent/oauth.json` (mode 0600). Use `/logout` to clear.
+Tokens stored in `~/.pi/agent/oauth.json`. Use `/logout` to clear.
 
-**GitHub Copilot:**
+**GitHub Copilot OAuth:**
 
 ```bash
 pi
 /login  # Select "GitHub Copilot", authorize in browser
 ```
 
-During login, you'll be prompted for an enterprise domain. Press Enter to use github.com, or enter your GitHub Enterprise Server domain (e.g., `github.mycompany.com`). All models are automatically enabled after login.
-
-If you get "The requested model is not supported" error, enable the model manually in VS Code: open Copilot Chat, click the model selector, select the model, and click "Enable".
+Press Enter to use github.com, or enter your GitHub Enterprise Server domain (e.g., `github.mycompany.com`).
 
-For enterprise users, check with your organization's Copilot administrator for model availability.
+If you get "The requested model is not supported" error, enable the model in VS Code: Copilot Chat → model selector → select model → "Enable".
 
-Tokens stored in `~/.pi/agent/oauth.json` (mode 0600). Use `/logout` to clear.
+Tokens stored in `~/.pi/agent/oauth.json`. Use `/logout` to clear.
 
 ### Quick Start
 
@@ -303,6 +299,8 @@ When disabled, neither case triggers automatic compaction (use `/compact` manual
 3. Summary replaces old messages as "context handoff"
 4. Previous compaction summaries chain into new ones
 
+Compaction does not create a new session, but continues the existing one, with a marker in the `.jsonl` file that encodes the compaction point.
+
 **Configuration** (`~/.pi/agent/settings.json`):
 
 ```json
@@ -315,7 +313,7 @@ When disabled, neither case triggers automatic compaction (use `/compact` manual
 }
 ```
 
-> **Note:** Compaction is lossy. The agent loses full conversation access afterward. Size tasks to avoid context limits when possible. For critical context, ask the agent to write a summary to a file, then start a new session with that file. The full session history is preserved in the JSONL file; use `/branch` to revisit any previous point.
+> **Note:** Compaction is lossy. The agent loses full conversation access afterward. Size tasks to avoid context limits when possible. For critical context, ask the agent to write a summary to a file, iterate on it until it covers everything, then start a new session with that file. The full session history is preserved in the JSONL file; use `/branch` to revisit any previous point.
 
 ### Branching
 
@@ -427,6 +425,8 @@ Add custom models (Ollama, vLLM, LM Studio, etc.) via `~/.pi/agent/models.json`:
 4. Saved default from settings
 5. First available model with valid API key
 
+> pi can help you create custom provider and model configurations.
+
 ### Themes
 
 Built-in themes: `dark` (default), `light`. Auto-detected on first run.
@@ -444,7 +444,7 @@ cp $(npm root -g)/@mariozechner/pi-coding-agent/dist/theme/dark.json ~/.pi/agent
 
 Select with `/theme`, then edit the file. Changes apply on save.
 
-See [Theme Documentation](docs/theme.md) for all 44 color tokens.
+> See [Theme Documentation](docs/theme.md) on how to create custom themes in detail. Pi can help you create a new one.
 
 **VS Code terminal fix:** Set `terminal.integrated.minimumContrastRatio` to `1` for accurate colors.
 
@@ -488,66 +488,49 @@ Usage: `/component Button "onClick handler" "disabled support"`
 
 ### Skills
 
-Skills are instruction files loaded on-demand when tasks match their descriptions. Compatible with Claude Code and Codex CLI skill formats.
+Skills are self-contained capability packages that the agent loads on-demand. A skill provides specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks. Skills are loaded when the agent decides a task matches the description, or when you explicitly ask to use one.
+
+**Example use cases:**
+- Web search and content extraction (Brave Search API)
+- Browser automation via Chrome DevTools Protocol
+- Google Calendar, Gmail, Drive integration
+- PDF/DOCX processing and creation
+- Speech-to-text transcription
+- YouTube transcript extraction
 
 **Skill locations:**
-- Pi user: `~/.pi/agent/skills/**/SKILL.md` (recursive, colon-separated names)
-- Pi project: `.pi/skills/**/SKILL.md` (recursive, colon-separated names)
-- Claude Code user: `~/.claude/skills/*/SKILL.md` (one level)
-- Claude Code project: `.claude/skills/*/SKILL.md` (one level)
+- Pi user: `~/.pi/agent/skills/**/SKILL.md` (recursive)
+- Pi project: `.pi/skills/**/SKILL.md` (recursive)
+- Claude Code: `~/.claude/skills/*/SKILL.md` and `.claude/skills/*/SKILL.md`
 - Codex CLI: `~/.codex/skills/**/SKILL.md` (recursive)
 
-Later locations win on name collisions (Pi skills override Claude/Codex).
-
-Pi skills in subdirectories use colon-separated names: `~/.pi/agent/skills/db/migrate/SKILL.md` → `db:migrate`
-
 **Format:**
 
 ```markdown
 ---
-description: Extract text and tables from PDF files
+description: Web search via Brave Search API. Use for documentation, facts, or web content.
 ---
 
-# PDF Processing
+# Brave Search
 
-Use `pdftotext` for plain text extraction.
-For tables, use `tabula-py`.
+## Setup
+\`\`\`bash
+cd {baseDir} && npm install
+\`\`\`
 
-Helper scripts: {baseDir}/scripts/
-```
-
-- `description`: Required. Shown in system prompt for agent to decide when to load.
-- `name`: Optional. Overrides directory name.
-- `{baseDir}`: Placeholder for the skill's directory. Agent substitutes it when following instructions.
-
-**How it works:**
-
-Skills are listed in the system prompt with descriptions:
-
-```
-<available_skills>
-- pdf-extract: Extract text and tables from PDF files
-  File: ~/.pi/agent/skills/pdf-extract/SKILL.md
-  Base directory: ~/.pi/agent/skills/pdf-extract
-</available_skills>
+## Usage
+\`\`\`bash
+{baseDir}/search.js "query"           # Basic search
+{baseDir}/search.js "query" --content # Include page content
+\`\`\`
 ```
 
-Agent uses `read` tool to load full instructions when needed.
+- `description`: Required. Determines when the skill is loaded.
+- `{baseDir}`: Placeholder for the skill's directory.
 
-**Disable skills:**
+**Disable skills:** `pi --no-skills` or set `skills.enabled: false` in settings.
 
-CLI: `pi --no-skills`
-
-Settings (`~/.pi/agent/settings.json`):
-```json
-{
-  "skills": {
-    "enabled": false
-  }
-}
-```
-
-See [docs/skills.md](docs/skills.md) for details.
+> See [docs/skills.md](docs/skills.md) for details, examples, and links to skill repositories. pi can help you create new skills.
 
 ### Hooks
 
@@ -557,7 +540,7 @@ Hooks are TypeScript modules that extend pi's behavior by subscribing to lifecyc
 - **Checkpoint code state** (git stash at each turn, restore on `/branch`)
 - **Protect paths** (block writes to `.env`, `node_modules/`, etc.)
 - **Modify tool output** (filter or transform results before the LLM sees them)
-- **Inject messages from external sources** (file watchers, webhooks, CI systems)
+- **Inject messages from external sources to wake up the agent** (file watchers, webhooks, CI systems)
 
 **Hook locations:**
 - Global: `~/.pi/agent/hooks/*.ts`
@@ -599,13 +582,13 @@ export default function (pi: HookAPI) {
 }
 ```
 
-See [Hooks Documentation](docs/hooks.md) for full API reference.
+> See [Hooks Documentation](docs/hooks.md) for full API reference. pi can help you create new hooks
 
-See [examples/hooks/](examples/hooks/) for working examples including permission gates, git checkpointing, and path protection.
+> See [examples/hooks/](examples/hooks/) for working examples including permission gates, git checkpointing, and path protection.
 
 ### Custom Tools
 
-Custom tools extend pi with new capabilities beyond the built-in tools. They are TypeScript modules that define tools with optional custom TUI rendering.
+Custom tools let you extend the built-in toolset (read, write, edit, bash, ...) and are called by the LLM directly. They are TypeScript modules that define tools with optional custom TUI integration for getting user input and custom tool call and result rendering.
 
 **Tool locations:**
 - Global: `~/.pi/agent/tools/*.ts`
@@ -644,12 +627,11 @@ export default factory;
 - Custom rendering via `renderCall()` and `renderResult()` methods
 - Streaming results via `onUpdate` callback
 - Abort handling via `signal` parameter
-- Cleanup via `dispose()` method
 - Multiple tools from one factory (return an array)
 
-See [Custom Tools Documentation](docs/custom-tools.md) for the full API reference, TUI component guide, and examples.
+> See [Custom Tools Documentation](docs/custom-tools.md) for the full API reference, TUI component guide, and examples. pi can help you create custom tools.
 
-See [examples/custom-tools/](examples/custom-tools/) for working examples including a todo list with session state management and a question tool with UI interaction.
+> See [examples/custom-tools/](examples/custom-tools/) for working examples including a todo list with session state management and a question tool with UI interaction.
 
 ### Settings File
 
@@ -658,8 +640,13 @@ See [examples/custom-tools/](examples/custom-tools/) for working examples includ
 ```json
 {
   "theme": "dark",
-  "shellPath": "C:\\path\\to\\bash.exe",
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-sonnet-4-20250514",
+  "defaultThinkingLevel": "medium",
   "queueMode": "one-at-a-time",
+  "shellPath": "C:\\path\\to\\bash.exe",
+  "hideThinkingBlock": false,
+  "collapseChangelog": false,
   "compaction": {
     "enabled": true,
     "reserveTokens": 16384,
@@ -675,17 +662,34 @@ See [examples/custom-tools/](examples/custom-tools/) for working examples includ
   },
   "terminal": {
     "showImages": true
-  }
+  },
+  "hooks": ["/path/to/hook.ts"],
+  "hookTimeout": 30000,
+  "customTools": ["/path/to/tool.ts"]
 }
 ```
 
-**Retry settings:**
-- `enabled`: Auto-retry on transient errors (overloaded, rate limit, 5xx). Default: `true`
-- `maxRetries`: Maximum retry attempts. Default: `3`
-- `baseDelayMs`: Base delay for exponential backoff (2s, 4s, 8s). Default: `2000`
-
-**Terminal settings:**
-- `showImages`: Render images inline in supported terminals. Default: `true`
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `theme` | Color theme name | auto-detected |
+| `defaultProvider` | Default model provider | - |
+| `defaultModel` | Default model ID | - |
+| `defaultThinkingLevel` | Thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` | - |
+| `queueMode` | Message queue mode: `all` or `one-at-a-time` | `one-at-a-time` |
+| `shellPath` | Custom bash path (Windows) | auto-detected |
+| `hideThinkingBlock` | Hide thinking blocks in output (Ctrl+T to toggle) | `false` |
+| `collapseChangelog` | Show condensed changelog after update | `false` |
+| `compaction.enabled` | Enable auto-compaction | `true` |
+| `compaction.reserveTokens` | Tokens to reserve before compaction triggers | `16384` |
+| `compaction.keepRecentTokens` | Recent tokens to keep after compaction | `20000` |
+| `skills.enabled` | Enable skills discovery | `true` |
+| `retry.enabled` | Auto-retry on transient errors | `true` |
+| `retry.maxRetries` | Maximum retry attempts | `3` |
+| `retry.baseDelayMs` | Base delay for exponential backoff | `2000` |
+| `terminal.showImages` | Render images inline (supported terminals) | `true` |
+| `hooks` | Additional hook file paths | `[]` |
+| `hookTimeout` | Timeout for hook operations (ms) | `30000` |
+| `customTools` | Additional custom tool file paths | `[]` |
 
 ---
 
@@ -793,32 +797,7 @@ Available via `--tools` flag:
 
 Example: `--tools read,grep,find,ls` for code review without modification.
 
-### Custom Tools
-
-Pi relies on CLI tools invoked via bash rather than MCP. Create a tool with a README:
-
-`~/agent-tools/screenshot/README.md`:
-```markdown
-# Screenshot Tool
-Takes a screenshot of your main display.
-
-## Usage
-```bash
-screenshot.sh
-```
-Returns the path to the saved PNG.
-```
-
-`~/agent-tools/screenshot/screenshot.sh`:
-```bash
-#!/bin/bash
-screencapture -x /tmp/screenshot-$(date +%s).png
-ls -t /tmp/screenshot-*.png | head -1
-```
-
-Usage: "Read ~/agent-tools/screenshot/README.md and take a screenshot"
-
-Reference tool READMEs in `AGENTS.md` to make them automatically available.
+For adding new tools, see [Custom Tools](#custom-tools) in the Configuration section.
 
 ---
 
@@ -855,59 +834,21 @@ Works with both session files and streaming event logs from `--mode json`.
 
 ## Philosophy
 
-Pi is opinionated about what it won't do. These are intentional design decisions.
-
-### No MCP
+Pi is opinionated about what it won't do. These are intentional design decisions to minimize context bloat and avoid anti-patterns.
 
-Pi does not support MCP (Model Context Protocol). Instead, it relies on four core tools (read, write, edit, bash) and assumes the agent can invoke CLI tools or write them as needed.
-
-CLI tools are simpler: any executable with a README works. No protocol overhead, no server management. The agent reads the README and uses bash.
-
-See: [What if you don't need MCP?](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/)
-
-### No Sub-Agents
-
-If the agent needs to delegate, it can spawn `pi` via bash or write a custom tool. Built-in sub-agents transfer context poorly; information gets lost or misrepresented. For parallel work, run multiple `pi` sessions in different terminals.
-
-### No Built-in To-Dos
-
-To-do lists confuse models more than they help. For task tracking, use a file:
-
-```markdown
-# TODO.md
-- [x] Implement authentication
-- [ ] Write API docs
-```
-
-### No Planning Mode
-
-Tell the agent to think through problems without modifying files. For persistent plans, write to a file:
-
-```markdown
-# PLAN.md
-## Goal
-Refactor auth to support OAuth
-## Current Step
-Working on authorization endpoints
-```
+**No MCP.** Build CLI tools with READMEs (see [Skills](#skills)). The agent reads them on demand. [Would you like to know more?](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/)
 
-### No Permission System (YOLO Mode)
+**No sub-agents.** Spawn pi instances via tmux, or build a task tool with [custom tools](#custom-tools). Full observability and steerability.
 
-Pi runs with full filesystem access and no permission prompts. Why:
-- Permission systems add friction while being easily circumvented
-- Pre-checking for "dangerous" patterns causes latency and false positives
+**No permission popups.** Security theater. Run in a container or build your own with [Hooks](#hooks).
 
-**Risks:**
-- Can read, write, delete anything with your user privileges
-- Prompt injection via files or command output can influence behavior
+**No plan mode.** Gather context in one session, write plans to file, start fresh for implementation.
 
-**Mitigations:**
-- Run in a container if uncomfortable
-- Don't use on systems with sensitive data you can't afford to lose
+**No built-in to-dos.** They confuse models. Use a TODO.md file, or [build your own](examples/custom-tools/todo.ts) with [custom tools](#custom-tools).
 
-### No Background Bash
+**No background bash.** Use tmux. Full observability, direct interaction.
 
-Use `tmux` or similar. Bonus: you can watch the agent interact with CLIs and intervene if needed.
+Read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/) for the full rationale.
 
 ---
 
@@ -942,7 +883,7 @@ Never use `__dirname` directly for package assets.
 
 ### Debug Command
 
-`/debug` (hidden) writes rendered lines with ANSI codes to `~/.pi/agent/pi-debug.log` for TUI debugging.
+`/debug` (hidden) writes rendered lines with ANSI codes to `~/.pi/agent/pi-debug.log` for TUI debugging, as well as the last set of messages that were sent to the LLM.
 
 For architecture and contribution guidelines, see [DEVELOPMENT.md](./DEVELOPMENT.md).
 

package/dist/core/agent-session.d.ts

@@ -126,6 +126,8 @@ export declare class AgentSession {
     private _resolveRetry;
     /** Extract text content from a message */
     private _getUserMessageText;
+    /** Find the last assistant message in agent state (including aborted ones) */
+    private _findLastAssistantMessage;
     private _emitHookEvent;
     /**
      * Subscribe to agent events.
@@ -253,7 +255,7 @@ export declare class AgentSession {
      * Cancel in-progress compaction (manual or auto).
      */
     abortCompaction(): void;
-    private _handleAgentEndCompaction;
+    private _checkCompaction;
     private _runAutoCompaction;
     /**
      * Toggle auto-compaction setting.