@mariozechner/pi-coding-agent 0.6.2

package/README.md

@@ -0,0 +1,485 @@
+# pi
+
+A radically simple and opinionated coding agent with multi-model support (including mid-session switching), a simple yet powerful CLI for headless coding tasks, and many creature comforts you might be used to from other coding agents.
+
+## Installation
+
+```bash
+npm install -g @mariozechner/pi-coding-agent
+```
+
+## Quick Start
+
+```bash
+# Set your API key (see API Keys section)
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Start the interactive CLI
+pi
+```
+
+Once in the CLI, you can chat with the AI:
+
+```
+You: Create a simple Express server in src/server.ts
+```
+
+The agent will use its tools to read, write, and edit files as needed, and execute commands via Bash.
+
+## API Keys
+
+The CLI supports multiple LLM providers. Set the appropriate environment variable for your chosen provider:
+
+```bash
+# Anthropic (Claude)
+export ANTHROPIC_API_KEY=sk-ant-...
+# Or use OAuth token (retrieved via: claude setup-token)
+export ANTHROPIC_OAUTH_TOKEN=...
+
+# OpenAI (GPT)
+export OPENAI_API_KEY=sk-...
+
+# Google (Gemini)
+export GEMINI_API_KEY=...
+
+# Groq
+export GROQ_API_KEY=gsk_...
+
+# Cerebras
+export CEREBRAS_API_KEY=csk-...
+
+# xAI (Grok)
+export XAI_API_KEY=xai-...
+
+# OpenRouter
+export OPENROUTER_API_KEY=sk-or-...
+
+# ZAI
+export ZAI_API_KEY=...
+```
+
+If no API key is set, the CLI will prompt you to configure one on first run.
+
+## Slash Commands
+
+The CLI supports several commands to control its behavior:
+
+### /model
+
+Switch models mid-session. Opens an interactive selector where you can type to search (by provider or model name), use arrow keys to navigate, Enter to select, or Escape to cancel.
+
+### /thinking
+
+Adjust thinking/reasoning level for supported models (Claude Sonnet 4, GPT-5, Gemini 2.5). Opens an interactive selector where you can use arrow keys to navigate, Enter to select, or Escape to cancel.
+
+### /export [filename]
+
+Export the current session to a self-contained HTML file:
+
+```
+/export                          # Auto-generates filename
+/export my-session.html          # Custom filename
+```
+
+The HTML file includes the full conversation with syntax highlighting and is viewable in any browser.
+
+### /session
+
+Show session information and statistics:
+
+```
+/session
+```
+
+Displays:
+- Session file path and ID
+- Message counts (user, assistant, total)
+- Token usage (input, output, cache read/write, total)
+- Total cost (if available)
+
+## Editor Features
+
+The interactive input editor includes several productivity features:
+
+### Path Completion
+
+Press **Tab** to autocomplete file and directory paths:
+- Works with relative paths: `./src/` + Tab → complete files in src/
+- Works with parent directories: `../../` + Tab → navigate up and complete
+- Works with home directory: `~/Des` + Tab → `~/Desktop/`
+- Use **Up/Down arrows** to navigate completion suggestions
+- Press **Enter** to select a completion
+- Shows matching files and directories as you type
+
+### File Drag & Drop
+
+Drag files from your OS file explorer (Finder on macOS, Explorer on Windows) directly onto the terminal. The file path will be automatically inserted into the editor. Works great with screenshots from macOS screenshot tool.
+
+### Multi-line Paste
+
+Paste multiple lines of text (e.g., code snippets, logs) and they'll be automatically coalesced into a compact `[paste #123 <N> lines]` reference in the editor. The full content is still sent to the model.
+
+### Keyboard Shortcuts
+
+- **Ctrl+K**: Delete current line
+- **Ctrl+C**: Clear editor (first press) / Exit pi (second press)
+- **Tab**: Path completion
+- **Enter**: Send message
+- **Shift+Enter**: Insert new line (multi-line input)
+- **Arrow keys**: Move cursor
+- **Ctrl+A** / **Home** / **Cmd+Left** (macOS): Jump to start of line
+- **Ctrl+E** / **End** / **Cmd+Right** (macOS): Jump to end of line
+
+## Project Context Files
+
+The agent automatically loads context from `AGENT.md` or `CLAUDE.md` files at the start of new sessions (not when continuing/resuming). These files are loaded in hierarchical order to support both global preferences and monorepo structures.
+
+### File Locations
+
+Context files are loaded in this order:
+
+1. **Global context**: `~/.pi/agent/AGENT.md` or `CLAUDE.md`
+   - Applies to all your coding sessions
+   - Great for personal coding preferences and workflows
+
+2. **Parent directories** (top-most first down to current directory)
+   - Walks up from current directory to filesystem root
+   - Each directory can have its own `AGENT.md` or `CLAUDE.md`
+   - Perfect for monorepos with shared context at higher levels
+
+3. **Current directory**: Your project's `AGENT.md` or `CLAUDE.md`
+   - Most specific context, loaded last
+   - Overwrites or extends parent/global context
+
+**File preference**: In each directory, `AGENT.md` is preferred over `CLAUDE.md` if both exist.
+
+### What to Include
+
+Context files are useful for:
+- Project-specific instructions and guidelines
+- Common bash commands and workflows
+- Architecture documentation
+- Coding conventions and style guides
+- Dependencies and setup information
+- Testing instructions
+- Repository etiquette (branch naming, merge vs. rebase, etc.)
+
+### Example
+
+```markdown
+# Common Commands
+- npm run build: Build the project
+- npm test: Run tests
+
+# Code Style
+- Use TypeScript strict mode
+- Prefer async/await over promises
+
+# Workflow
+- Always run tests before committing
+- Update CHANGELOG.md for user-facing changes
+```
+
+All context files are automatically included in the system prompt at session start, along with the current date/time and working directory. This ensures the AI has complete project context from the very first message.
+
+## Image Support
+
+Send images to vision-capable models by providing file paths:
+
+```
+You: What is in this screenshot? /path/to/image.png
+```
+
+Supported formats: `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`
+
+The image will be automatically encoded and sent with your message. JPEG and PNG are supported across all vision models. Other formats may only be supported by some models.
+
+## Session Management
+
+Sessions are automatically saved in `~/.pi/agent/sessions/` organized by working directory. Each session is stored as a JSONL file with a unique timestamp-based ID.
+
+To continue the most recent session:
+
+```bash
+pi --continue
+# or
+pi -c
+```
+
+To browse and select from past sessions:
+
+```bash
+pi --resume
+# or
+pi -r
+```
+
+This opens an interactive session selector where you can:
+- Type to search through session messages
+- Use arrow keys to navigate the list
+- Press Enter to resume a session
+- Press Escape to cancel
+
+Sessions include all conversation messages, tool calls and results, model switches, and thinking level changes.
+
+To run without saving a session (ephemeral mode):
+
+```bash
+pi --no-session
+```
+
+To use a specific session file instead of auto-generating one:
+
+```bash
+pi --session /path/to/my-session.jsonl
+```
+
+## CLI Options
+
+```bash
+pi [options] [messages...]
+```
+
+### Options
+
+**--provider <name>**
+Provider name. Available: `anthropic`, `openai`, `google`, `xai`, `groq`, `cerebras`, `openrouter`, `zai`. Default: `anthropic`
+
+**--model <id>**
+Model ID. Default: `claude-sonnet-4-5`
+
+**--api-key <key>**
+API key (overrides environment variables)
+
+**--system-prompt <text|file>**
+Custom system prompt. Can be:
+- Inline text: `--system-prompt "You are a helpful assistant"`
+- File path: `--system-prompt ./my-prompt.txt`
+
+If the argument is a valid file path, the file contents will be used as the system prompt. Otherwise, the text is used directly. Project context files and datetime are automatically appended.
+
+**--mode <mode>**
+Output mode for non-interactive usage. Options:
+- `text` (default): Output only the final assistant message text
+- `json`: Stream all agent events as JSON (one event per line). Events are emitted by `@mariozechner/pi-agent` and include message updates, tool executions, and completions
+- `rpc`: JSON mode plus stdin listener for headless operation. Send JSON commands on stdin: `{"type":"prompt","message":"..."}` or `{"type":"abort"}`. See [test/rpc-example.ts](test/rpc-example.ts) for a complete example
+
+**--no-session**
+Don't save session (ephemeral mode)
+
+**--session <path>**
+Use specific session file path instead of auto-generating one
+
+**--continue, -c**
+Continue the most recent session
+
+**--resume, -r**
+Select a session to resume (opens interactive selector)
+
+**--help, -h**
+Show help message
+
+### Examples
+
+```bash
+# Start interactive mode
+pi
+
+# Single message mode (text output)
+pi "List all .ts files in src/"
+
+# JSON mode - stream all agent events
+pi --mode json "List all .ts files in src/"
+
+# RPC mode - headless operation (see test/rpc-example.ts)
+pi --mode rpc --no-session
+# Then send JSON on stdin:
+# {"type":"prompt","message":"List all .ts files"}
+# {"type":"abort"}
+
+# Continue previous session
+pi -c "What did we discuss?"
+
+# Use different model
+pi --provider openai --model gpt-4o "Help me refactor this code"
+```
+
+## Tools
+
+### Built-in Tools
+
+The agent has access to four core tools for working with your codebase:
+
+**read**
+Read file contents. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, defaults to first 2000 lines. Use offset/limit parameters for large files. Lines longer than 2000 characters are truncated.
+
+**write**
+Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.
+
+**edit**
+Edit a file by replacing exact text. The oldText must match exactly (including whitespace). Use this for precise, surgical edits. Returns an error if the text appears multiple times or isn't found.
+
+**bash**
+Execute a bash command in the current working directory. Returns stdout and stderr. Commands run with a 30 second timeout.
+
+### MCP & Adding Your Own Tools
+
+**pi does and will not support MCP.** Instead, it relies on the four built-in tools above and assumes the agent can invoke pre-existing CLI tools or write them on the fly as needed.
+
+**Here's the gist:**
+
+1. Create a simple CLI tool (any language, any executable)
+2. Write a concise README.md describing what it does and how to use it
+3. Tell the agent to read that README
+
+**Minimal example:**
+
+`~/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 file.
+```
+
+`~/agent-tools/screenshot/screenshot.sh`:
+```bash
+#!/bin/bash
+screencapture -x /tmp/screenshot-$(date +%s).png
+ls -t /tmp/screenshot-*.png | head -1
+```
+
+**In your session:**
+```
+You: Read ~/agent-tools/screenshot/README.md and use that tool to take a screenshot
+```
+
+The agent will read the README, understand the tool, and invoke it via bash as needed. If you need a new tool, ask the agent to write it for you.
+
+You can also reference tool READMEs in your `AGENT.md` files to make them automatically available:
+- Global: `~/.pi/agent/AGENT.md` - available in all sessions
+- Project-specific: `./AGENT.md` - available in this project
+
+**Real-world example:**
+
+The [exa-search](https://github.com/badlogic/exa-search) tools provide web search capabilities via the Exa API. Built by the agent itself in ~2 minutes. Far from perfect, but functional. Just tell your agent: "Read ~/agent-tools/exa-search/README.md and search for X".
+
+For a detailed walkthrough with more examples, and the reasons for and benefits of this decision, see: https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/
+
+## Security (YOLO by default)
+
+This agent runs in full YOLO mode and assumes you know what you're doing. It has unrestricted access to your filesystem and can execute any command without permission checks or safety rails.
+
+**What this means:**
+- No permission prompts for file operations or commands
+- No pre-checking of bash commands for malicious content
+- Full filesystem access - can read, write, or delete anything
+- Can execute any command with your user privileges
+
+**Why:**
+- Permission systems add massive friction while being easily circumvented
+- Pre-checking tools for "dangerous" patterns introduces latency, false positives, and is ineffective
+
+**Prompt injection risks:**
+- By default, pi has no web search or fetch tool
+- However, it can use `curl` or read files from disk
+- Both provide ample surface area for prompt injection attacks
+- Malicious content in files or command outputs can influence behavior
+
+**Mitigations:**
+- Run pi inside a container if you're uncomfortable with full access
+- Use a different tool if you need guardrails
+- Don't use pi on systems with sensitive data you can't afford to lose
+- Fork pi and add all of the above
+
+This is how I want it to work and I'm not likely to change my stance on this.
+
+Use at your own risk.
+
+## Sub-Agents
+
+**pi does not and will not support sub-agents as a built-in feature.** If the agent needs to delegate work, it can:
+
+1. Spawn another instance of itself via the `pi` CLI command
+2. Write a custom tool with a README.md that describes how to invoke pi for specific tasks
+
+**Why no built-in sub-agents:**
+
+Context transfer between agents is generally poor. Information gets lost, compressed, or misrepresented when passed through agent boundaries. Direct execution with full context is more effective than delegation with summarized context.
+
+If you need parallel work on independent tasks, manually run multiple `pi` sessions in different terminal tabs. You're the orchestrator.
+
+## To-Dos
+
+**pi does not and will not support built-in to-dos.** In my experience, to-do lists generally confuse models more than they help.
+
+If you need task tracking, make it stateful by writing to a file:
+
+```markdown
+# TODO.md
+
+- [x] Implement user authentication
+- [x] Add database migrations
+- [ ] Write API documentation
+- [ ] Add rate limiting
+```
+
+The agent can read and update this file as needed. Using checkboxes keeps track of what's done and what remains. Simple, visible, and under your control.
+
+## Planning
+
+**pi does not and will not have a built-in planning mode.** Telling the agent to think through a problem together with you, without modifying files or executing commands, is generally sufficient.
+
+If you need persistent planning across sessions, write it to a file:
+
+```markdown
+# PLAN.md
+
+## Goal
+Refactor authentication system to support OAuth
+
+## Approach
+1. Research OAuth 2.0 flows
+2. Design token storage schema
+3. Implement authorization server endpoints
+4. Update client-side login flow
+5. Add tests
+
+## Current Step
+Working on step 3 - authorization endpoints
+```
+
+The agent can read, update, and reference the plan as it works. Unlike ephemeral planning modes that only exist within a session, file-based plans persist and can be versioned with your code.
+
+## Background Bash
+
+**pi does not and will not implement background bash execution.** Instead, tell the agent to use `tmux` or something like [tterminal-cp](https://mariozechner.at/posts/2025-08-15-mcp-vs-cli/). Bonus points: you can watch the agent interact with a CLI like a debugger and even intervene if necessary.
+
+## Planned Features
+
+Things that might happen eventually:
+
+- **Custom/local models**: Support for Ollama, llama.cpp, vLLM, SGLang, LM Studio via JSON config file
+- **Auto-compaction**: Currently, watch the context percentage at the bottom. When it approaches 80%, either:
+  - Ask the agent to write a summary .md file you can load in a new session
+  - Switch to a model with bigger context (e.g., Gemini) using `/model` and either continue with that model, or let it summarize the session to a .md file to be loaded in a new session
+- **Message queuing**: Core engine supports it, just needs UI wiring
+- **Better RPC mode docs**: It works, you'll figure it out (see `test/rpc-example.ts`)
+- **Beter Markdown and tool call/result rendering**
+- **Full details mode**: use `/export out.html` for now
+- **More flicker than Claude Code**: One day...
+
+## License
+
+MIT
+
+## See Also
+
+- [@mariozechner/pi-ai](https://www.npmjs.com/package/@mariozechner/pi-ai): Core LLM toolkit with multi-provider support
+- [@mariozechner/pi-agent](https://www.npmjs.com/package/@mariozechner/pi-agent): Agent framework with tool execution

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"","sourcesContent":["#!/usr/bin/env node\n\n// Suppress punycode deprecation warning from dependencies\n// This warning comes from old dependencies still using the deprecated punycode module\nconst originalEmit = process.emit;\n// @ts-expect-error - Monkey-patch emit to filter warnings\nprocess.emit = (event, ...args) => {\n\tif (event === \"warning\") {\n\t\tconst warning = args[0] as any;\n\t\tif (warning?.name === \"DeprecationWarning\" && warning?.code === \"DEP0040\") {\n\t\t\treturn false; // Suppress punycode deprecation\n\t\t}\n\t}\n\t// @ts-expect-error - Call original with event and args\n\treturn originalEmit.apply(process, [event, ...args]);\n};\n\nimport { main } from \"./main.js\";\n\nmain(process.argv.slice(2)).catch((err) => {\n\tconsole.error(err);\n\tprocess.exit(1);\n});\n"]}

package/dist/cli.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// Suppress punycode deprecation warning from dependencies
+// This warning comes from old dependencies still using the deprecated punycode module
+const originalEmit = process.emit;
+// @ts-expect-error - Monkey-patch emit to filter warnings
+process.emit = (event, ...args) => {
+    if (event === "warning") {
+        const warning = args[0];
+        if (warning?.name === "DeprecationWarning" && warning?.code === "DEP0040") {
+            return false; // Suppress punycode deprecation
+        }
+    }
+    // @ts-expect-error - Call original with event and args
+    return originalEmit.apply(process, [event, ...args]);
+};
+import { main } from "./main.js";
+main(process.argv.slice(2)).catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,0DAA0D;AAC1D,sFAAsF;AACtF,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;AAClC,0DAA0D;AAC1D,OAAO,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAQ,CAAC;QAC/B,IAAI,OAAO,EAAE,IAAI,KAAK,oBAAoB,IAAI,OAAO,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;YAC3E,OAAO,KAAK,CAAC,CAAC,gCAAgC;QAC/C,CAAC;IACF,CAAC;IACD,uDAAuD;IACvD,OAAO,YAAY,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;AAAA,CACrD,CAAC;AAEF,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC;IAC1C,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAAA,CAChB,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\n\n// Suppress punycode deprecation warning from dependencies\n// This warning comes from old dependencies still using the deprecated punycode module\nconst originalEmit = process.emit;\n// @ts-expect-error - Monkey-patch emit to filter warnings\nprocess.emit = (event, ...args) => {\n\tif (event === \"warning\") {\n\t\tconst warning = args[0] as any;\n\t\tif (warning?.name === \"DeprecationWarning\" && warning?.code === \"DEP0040\") {\n\t\t\treturn false; // Suppress punycode deprecation\n\t\t}\n\t}\n\t// @ts-expect-error - Call original with event and args\n\treturn originalEmit.apply(process, [event, ...args]);\n};\n\nimport { main } from \"./main.js\";\n\nmain(process.argv.slice(2)).catch((err) => {\n\tconsole.error(err);\n\tprocess.exit(1);\n});\n"]}

package/dist/export-html.d.ts

@@ -0,0 +1,7 @@
+import type { AgentState } from "@mariozechner/pi-agent";
+import type { SessionManager } from "./session-manager.js";
+/**
+ * Export session to a self-contained HTML file matching TUI visual style
+ */
+export declare function exportSessionToHtml(sessionManager: SessionManager, state: AgentState, outputPath?: string): string;
+//# sourceMappingURL=export-html.d.ts.map

package/dist/export-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-html.d.ts","sourceRoot":"","sources":["../src/export-html.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAMzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AA0S3D;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAqXlH","sourcesContent":["import type { AgentState } from \"@mariozechner/pi-agent\";\nimport type { AssistantMessage, Message, ToolResultMessage, UserMessage } from \"@mariozechner/pi-ai\";\nimport { readFileSync, writeFileSync } from \"fs\";\nimport { homedir } from \"os\";\nimport { basename, dirname, join } from \"path\";\nimport { fileURLToPath } from \"url\";\nimport type { SessionManager } from \"./session-manager.js\";\n\n// Get version from package.json\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\nconst packageJson = JSON.parse(readFileSync(join(__dirname, \"../package.json\"), \"utf-8\"));\nconst VERSION = packageJson.version;\n\n/**\n * TUI Color scheme (matching exact RGB values from TUI components)\n */\nconst COLORS = {\n\t// Backgrounds\n\tuserMessageBg: \"rgb(52, 53, 65)\", // Dark slate\n\ttoolPendingBg: \"rgb(40, 40, 50)\", // Dark blue-gray\n\ttoolSuccessBg: \"rgb(40, 50, 40)\", // Dark green\n\ttoolErrorBg: \"rgb(60, 40, 40)\", // Dark red\n\tbodyBg: \"rgb(24, 24, 30)\", // Very dark background\n\tcontainerBg: \"rgb(30, 30, 36)\", // Slightly lighter container\n\n\t// Text colors (matching chalk colors)\n\ttext: \"rgb(229, 229, 231)\", // Light gray (close to white)\n\ttextDim: \"rgb(161, 161, 170)\", // Dimmed gray\n\tcyan: \"rgb(103, 232, 249)\", // Cyan for paths\n\tgreen: \"rgb(34, 197, 94)\", // Green for success\n\tred: \"rgb(239, 68, 68)\", // Red for errors\n\tyellow: \"rgb(234, 179, 8)\", // Yellow for warnings\n\titalic: \"rgb(161, 161, 170)\", // Gray italic for thinking\n};\n\n/**\n * Escape HTML special characters\n */\nfunction escapeHtml(text: string): string {\n\treturn text\n\t\t.replace(/&/g, \"&amp;\")\n\t\t.replace(/</g, \"&lt;\")\n\t\t.replace(/>/g, \"&gt;\")\n\t\t.replace(/\"/g, \"&quot;\")\n\t\t.replace(/'/g, \"&#039;\");\n}\n\n/**\n * Shorten path with tilde notation\n */\nfunction shortenPath(path: string): string {\n\tconst home = homedir();\n\tif (path.startsWith(home)) {\n\t\treturn \"~\" + path.slice(home.length);\n\t}\n\treturn path;\n}\n\n/**\n * Replace tabs with 3 spaces\n */\nfunction replaceTabs(text: string): string {\n\treturn text.replace(/\\t/g, \"   \");\n}\n\n/**\n * Format tool execution matching TUI ToolExecutionComponent\n */\nfunction formatToolExecution(\n\ttoolName: string,\n\targs: any,\n\tresult?: ToolResultMessage,\n): { html: string; bgColor: string } {\n\tlet html = \"\";\n\tconst isError = result?.isError || false;\n\tconst bgColor = result ? (isError ? COLORS.toolErrorBg : COLORS.toolSuccessBg) : COLORS.toolPendingBg;\n\n\t// Get text output from result\n\tconst getTextOutput = (): string => {\n\t\tif (!result) return \"\";\n\t\tconst textBlocks = result.content.filter((c) => c.type === \"text\");\n\t\treturn textBlocks.map((c: any) => c.text).join(\"\\n\");\n\t};\n\n\t// Format based on tool type (matching TUI logic exactly)\n\tif (toolName === \"bash\") {\n\t\tconst command = args?.command || \"\";\n\t\thtml = `<div class=\"tool-command\">$ ${escapeHtml(command || \"...\")}</div>`;\n\n\t\tif (result) {\n\t\t\tconst output = getTextOutput().trim();\n\t\t\tif (output) {\n\t\t\t\tconst lines = output.split(\"\\n\");\n\t\t\t\tconst maxLines = 5;\n\t\t\t\tconst displayLines = lines.slice(0, maxLines);\n\t\t\t\tconst remaining = lines.length - maxLines;\n\n\t\t\t\tif (remaining > 0) {\n\t\t\t\t\t// Truncated output - make it expandable\n\t\t\t\t\thtml += '<div class=\"tool-output expandable\" onclick=\"this.classList.toggle(\\'expanded\\')\">';\n\t\t\t\t\thtml += '<div class=\"output-preview\">';\n\t\t\t\t\tfor (const line of displayLines) {\n\t\t\t\t\t\thtml += `<div>${escapeHtml(line)}</div>`;\n\t\t\t\t\t}\n\t\t\t\t\thtml += `<div class=\"expand-hint\">... (${remaining} more lines) - click to expand</div>`;\n\t\t\t\t\thtml += \"</div>\";\n\t\t\t\t\thtml += '<div class=\"output-full\">';\n\t\t\t\t\tfor (const line of lines) {\n\t\t\t\t\t\thtml += `<div>${escapeHtml(line)}</div>`;\n\t\t\t\t\t}\n\t\t\t\t\thtml += \"</div>\";\n\t\t\t\t\thtml += \"</div>\";\n\t\t\t\t} else {\n\t\t\t\t\t// Short output - show all\n\t\t\t\t\thtml += '<div class=\"tool-output\">';\n\t\t\t\t\tfor (const line of displayLines) {\n\t\t\t\t\t\thtml += `<div>${escapeHtml(line)}</div>`;\n\t\t\t\t\t}\n\t\t\t\t\thtml += \"</div>\";\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t} else if (toolName === \"read\") {\n\t\tconst path = shortenPath(args?.file_path || args?.path || \"\");\n\t\thtml = `<div class=\"tool-header\"><span class=\"tool-name\">read</span> <span class=\"tool-path\">${escapeHtml(path || \"...\")}</span></div>`;\n\n\t\tif (result) {\n\t\t\tconst output = getTextOutput();\n\t\t\tconst lines = output.split(\"\\n\");\n\t\t\tconst maxLines = 10;\n\t\t\tconst displayLines = lines.slice(0, maxLines);\n\t\t\tconst remaining = lines.length - maxLines;\n\n\t\t\tif (remaining > 0) {\n\t\t\t\t// Truncated output - make it expandable\n\t\t\t\thtml += '<div class=\"tool-output expandable\" onclick=\"this.classList.toggle(\\'expanded\\')\">';\n\t\t\t\thtml += '<div class=\"output-preview\">';\n\t\t\t\tfor (const line of displayLines) {\n\t\t\t\t\thtml += `<div>${escapeHtml(replaceTabs(line))}</div>`;\n\t\t\t\t}\n\t\t\t\thtml += `<div class=\"expand-hint\">... (${remaining} more lines) - click to expand</div>`;\n\t\t\t\thtml += \"</div>\";\n\t\t\t\thtml += '<div class=\"output-full\">';\n\t\t\t\tfor (const line of lines) {\n\t\t\t\t\thtml += `<div>${escapeHtml(replaceTabs(line))}</div>`;\n\t\t\t\t}\n\t\t\t\thtml += \"</div>\";\n\t\t\t\thtml += \"</div>\";\n\t\t\t} else {\n\t\t\t\t// Short output - show all\n\t\t\t\thtml += '<div class=\"tool-output\">';\n\t\t\t\tfor (const line of displayLines) {\n\t\t\t\t\thtml += `<div>${escapeHtml(replaceTabs(line))}</div>`;\n\t\t\t\t}\n\t\t\t\thtml += \"</div>\";\n\t\t\t}\n\t\t}\n\t} else if (toolName === \"write\") {\n\t\tconst path = shortenPath(args?.file_path || args?.path || \"\");\n\t\tconst fileContent = args?.content || \"\";\n\t\tconst lines = fileContent ? fileContent.split(\"\\n\") : [];\n\t\tconst totalLines = lines.length;\n\n\t\thtml = `<div class=\"tool-header\"><span class=\"tool-name\">write</span> <span class=\"tool-path\">${escapeHtml(path || \"...\")}</span>`;\n\t\tif (totalLines > 10) {\n\t\t\thtml += ` <span class=\"line-count\">(${totalLines} lines)</span>`;\n\t\t}\n\t\thtml += \"</div>\";\n\n\t\tif (fileContent) {\n\t\t\tconst maxLines = 10;\n\t\t\tconst displayLines = lines.slice(0, maxLines);\n\t\t\tconst remaining = lines.length - maxLines;\n\n\t\t\tif (remaining > 0) {\n\t\t\t\t// Truncated output - make it expandable\n\t\t\t\thtml += '<div class=\"tool-output expandable\" onclick=\"this.classList.toggle(\\'expanded\\')\">';\n\t\t\t\thtml += '<div class=\"output-preview\">';\n\t\t\t\tfor (const line of displayLines) {\n\t\t\t\t\thtml += `<div>${escapeHtml(replaceTabs(line))}</div>`;\n\t\t\t\t}\n\t\t\t\thtml += `<div class=\"expand-hint\">... (${remaining} more lines) - click to expand</div>`;\n\t\t\t\thtml += \"</div>\";\n\t\t\t\thtml += '<div class=\"output-full\">';\n\t\t\t\tfor (const line of lines) {\n\t\t\t\t\thtml += `<div>${escapeHtml(replaceTabs(line))}</div>`;\n\t\t\t\t}\n\t\t\t\thtml += \"</div>\";\n\t\t\t\thtml += \"</div>\";\n\t\t\t} else {\n\t\t\t\t// Short output - show all\n\t\t\t\thtml += '<div class=\"tool-output\">';\n\t\t\t\tfor (const line of displayLines) {\n\t\t\t\t\thtml += `<div>${escapeHtml(replaceTabs(line))}</div>`;\n\t\t\t\t}\n\t\t\t\thtml += \"</div>\";\n\t\t\t}\n\t\t}\n\n\t\tif (result) {\n\t\t\tconst output = getTextOutput().trim();\n\t\t\tif (output) {\n\t\t\t\thtml += `<div class=\"tool-output\"><div>${escapeHtml(output)}</div></div>`;\n\t\t\t}\n\t\t}\n\t} else if (toolName === \"edit\") {\n\t\tconst path = shortenPath(args?.file_path || args?.path || \"\");\n\t\thtml = `<div class=\"tool-header\"><span class=\"tool-name\">edit</span> <span class=\"tool-path\">${escapeHtml(path || \"...\")}</span></div>`;\n\n\t\t// Show diff if available from result.details.diff\n\t\tif (result?.details?.diff) {\n\t\t\tconst diffLines = result.details.diff.split(\"\\n\");\n\t\t\thtml += '<div class=\"tool-diff\">';\n\t\t\tfor (const line of diffLines) {\n\t\t\t\tif (line.startsWith(\"+\")) {\n\t\t\t\t\thtml += `<div class=\"diff-line-new\">${escapeHtml(line)}</div>`;\n\t\t\t\t} else if (line.startsWith(\"-\")) {\n\t\t\t\t\thtml += `<div class=\"diff-line-old\">${escapeHtml(line)}</div>`;\n\t\t\t\t} else {\n\t\t\t\t\thtml += `<div class=\"diff-line-context\">${escapeHtml(line)}</div>`;\n\t\t\t\t}\n\t\t\t}\n\t\t\thtml += \"</div>\";\n\t\t}\n\n\t\tif (result) {\n\t\t\tconst output = getTextOutput().trim();\n\t\t\tif (output) {\n\t\t\t\thtml += `<div class=\"tool-output\"><div>${escapeHtml(output)}</div></div>`;\n\t\t\t}\n\t\t}\n\t} else {\n\t\t// Generic tool\n\t\thtml = `<div class=\"tool-header\"><span class=\"tool-name\">${escapeHtml(toolName)}</span></div>`;\n\t\thtml += `<div class=\"tool-output\"><pre>${escapeHtml(JSON.stringify(args, null, 2))}</pre></div>`;\n\n\t\tif (result) {\n\t\t\tconst output = getTextOutput();\n\t\t\tif (output) {\n\t\t\t\thtml += `<div class=\"tool-output\"><div>${escapeHtml(output)}</div></div>`;\n\t\t\t}\n\t\t}\n\t}\n\n\treturn { html, bgColor };\n}\n\n/**\n * Format a message as HTML (matching TUI component styling)\n */\nfunction formatMessage(message: Message, toolResultsMap: Map<string, ToolResultMessage>): string {\n\tlet html = \"\";\n\n\tif (message.role === \"user\") {\n\t\tconst userMsg = message as UserMessage;\n\t\tlet textContent = \"\";\n\n\t\tif (typeof userMsg.content === \"string\") {\n\t\t\ttextContent = userMsg.content;\n\t\t} else {\n\t\t\tconst textBlocks = userMsg.content.filter((c) => c.type === \"text\");\n\t\t\ttextContent = textBlocks.map((c: any) => c.text).join(\"\");\n\t\t}\n\n\t\tif (textContent.trim()) {\n\t\t\thtml += `<div class=\"user-message\">${escapeHtml(textContent).replace(/\\n/g, \"<br>\")}</div>`;\n\t\t}\n\t} else if (message.role === \"assistant\") {\n\t\tconst assistantMsg = message as AssistantMessage;\n\n\t\t// Render text and thinking content\n\t\tfor (const content of assistantMsg.content) {\n\t\t\tif (content.type === \"text\" && content.text.trim()) {\n\t\t\t\thtml += `<div class=\"assistant-text\">${escapeHtml(content.text.trim()).replace(/\\n/g, \"<br>\")}</div>`;\n\t\t\t} else if (content.type === \"thinking\" && content.thinking.trim()) {\n\t\t\t\thtml += `<div class=\"thinking-text\">${escapeHtml(content.thinking.trim()).replace(/\\n/g, \"<br>\")}</div>`;\n\t\t\t}\n\t\t}\n\n\t\t// Render tool calls with their results\n\t\tfor (const content of assistantMsg.content) {\n\t\t\tif (content.type === \"toolCall\") {\n\t\t\t\tconst toolResult = toolResultsMap.get(content.id);\n\t\t\t\tconst { html: toolHtml, bgColor } = formatToolExecution(content.name, content.arguments, toolResult);\n\t\t\t\thtml += `<div class=\"tool-execution\" style=\"background-color: ${bgColor}\">${toolHtml}</div>`;\n\t\t\t}\n\t\t}\n\n\t\t// Show error/abort status if no tool calls\n\t\tconst hasToolCalls = assistantMsg.content.some((c) => c.type === \"toolCall\");\n\t\tif (!hasToolCalls) {\n\t\t\tif (assistantMsg.stopReason === \"aborted\") {\n\t\t\t\thtml += '<div class=\"error-text\">Aborted</div>';\n\t\t\t} else if (assistantMsg.stopReason === \"error\") {\n\t\t\t\tconst errorMsg = assistantMsg.errorMessage || \"Unknown error\";\n\t\t\t\thtml += `<div class=\"error-text\">Error: ${escapeHtml(errorMsg)}</div>`;\n\t\t\t}\n\t\t}\n\t}\n\n\treturn html;\n}\n\n/**\n * Export session to a self-contained HTML file matching TUI visual style\n */\nexport function exportSessionToHtml(sessionManager: SessionManager, state: AgentState, outputPath?: string): string {\n\tconst sessionFile = sessionManager.getSessionFile();\n\tconst timestamp = new Date().toISOString();\n\n\t// Use session filename + .html if no output path provided\n\tif (!outputPath) {\n\t\tconst sessionBasename = basename(sessionFile, \".jsonl\");\n\t\toutputPath = `${sessionBasename}.html`;\n\t}\n\n\t// Read and parse session data\n\tconst sessionContent = readFileSync(sessionFile, \"utf8\");\n\tconst lines = sessionContent.trim().split(\"\\n\");\n\n\tlet sessionHeader: any = null;\n\tconst messages: Message[] = [];\n\tconst toolResultsMap = new Map<string, ToolResultMessage>();\n\n\tfor (const line of lines) {\n\t\ttry {\n\t\t\tconst entry = JSON.parse(line);\n\t\t\tif (entry.type === \"session\") {\n\t\t\t\tsessionHeader = entry;\n\t\t\t} else if (entry.type === \"message\") {\n\t\t\t\tmessages.push(entry.message);\n\t\t\t\t// Build map of tool call ID to result\n\t\t\t\tif (entry.message.role === \"toolResult\") {\n\t\t\t\t\ttoolResultsMap.set(entry.message.toolCallId, entry.message);\n\t\t\t\t}\n\t\t\t}\n\t\t} catch {\n\t\t\t// Skip malformed lines\n\t\t}\n\t}\n\n\t// Generate messages HTML\n\tlet messagesHtml = \"\";\n\tfor (const message of messages) {\n\t\tif (message.role !== \"toolResult\") {\n\t\t\t// Skip toolResult messages as they're rendered with their tool calls\n\t\t\tmessagesHtml += formatMessage(message, toolResultsMap);\n\t\t}\n\t}\n\n\t// Generate HTML (matching TUI aesthetic)\n\tconst html = `<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"UTF-8\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n    <title>Session Export - ${basename(sessionFile)}</title>\n    <style>\n        * {\n            margin: 0;\n            padding: 0;\n            box-sizing: border-box;\n        }\n\n        body {\n            font-family: 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, 'Courier New', monospace;\n            font-size: 14px;\n            line-height: 1.6;\n            color: ${COLORS.text};\n            background: ${COLORS.bodyBg};\n            padding: 24px;\n        }\n\n        .container {\n            max-width: 1200px;\n            margin: 0 auto;\n        }\n\n        .header {\n            margin-bottom: 24px;\n            padding: 16px;\n            background: ${COLORS.containerBg};\n            border-radius: 4px;\n        }\n\n        .header h1 {\n            font-size: 16px;\n            font-weight: bold;\n            margin-bottom: 12px;\n            color: ${COLORS.cyan};\n        }\n\n        .header-info {\n            display: flex;\n            flex-direction: column;\n            gap: 6px;\n            font-size: 13px;\n        }\n\n        .info-item {\n            color: ${COLORS.textDim};\n            display: flex;\n            align-items: baseline;\n        }\n\n        .info-label {\n            font-weight: 600;\n            margin-right: 8px;\n            min-width: 80px;\n        }\n\n        .info-value {\n            color: ${COLORS.text};\n            flex: 1;\n        }\n\n        .messages {\n            display: flex;\n            flex-direction: column;\n            gap: 16px;\n        }\n\n        /* User message - matching TUI UserMessageComponent */\n        .user-message {\n            background: ${COLORS.userMessageBg};\n            padding: 12px 16px;\n            border-radius: 4px;\n            white-space: pre-wrap;\n            word-wrap: break-word;\n        }\n\n        /* Assistant text - matching TUI AssistantMessageComponent */\n        .assistant-text {\n            padding: 12px 16px;\n            white-space: pre-wrap;\n            word-wrap: break-word;\n        }\n\n        /* Thinking text - gray italic */\n        .thinking-text {\n            padding: 12px 16px;\n            color: ${COLORS.italic};\n            font-style: italic;\n            white-space: pre-wrap;\n            word-wrap: break-word;\n        }\n\n        /* Tool execution - matching TUI ToolExecutionComponent */\n        .tool-execution {\n            padding: 12px 16px;\n            border-radius: 4px;\n            margin-top: 8px;\n        }\n\n        .tool-header {\n            font-weight: bold;\n        }\n\n        .tool-name {\n            font-weight: bold;\n        }\n\n        .tool-path {\n            color: ${COLORS.cyan};\n        }\n\n        .line-count {\n            color: ${COLORS.textDim};\n        }\n\n        .tool-command {\n            font-weight: bold;\n        }\n\n        .tool-output {\n            margin-top: 12px;\n            color: ${COLORS.textDim};\n            white-space: pre-wrap;\n            font-family: inherit;\n        }\n\n        .tool-output > div {\n            line-height: 1.4;\n        }\n\n        .tool-output pre {\n            margin: 0;\n            font-family: inherit;\n            color: inherit;\n        }\n\n        /* Expandable tool output */\n        .tool-output.expandable {\n            cursor: pointer;\n        }\n\n        .tool-output.expandable:hover {\n            opacity: 0.9;\n        }\n\n        .tool-output.expandable .output-full {\n            display: none;\n        }\n\n        .tool-output.expandable.expanded .output-preview {\n            display: none;\n        }\n\n        .tool-output.expandable.expanded .output-full {\n            display: block;\n        }\n\n        .expand-hint {\n            color: ${COLORS.cyan};\n            font-style: italic;\n            margin-top: 4px;\n        }\n\n        /* System prompt section */\n        .system-prompt {\n            background: rgb(60, 55, 40);\n            padding: 12px 16px;\n            border-radius: 4px;\n            margin-bottom: 16px;\n        }\n\n        .system-prompt-header {\n            font-weight: bold;\n            color: ${COLORS.yellow};\n            margin-bottom: 8px;\n        }\n\n        .system-prompt-content {\n            color: ${COLORS.textDim};\n            white-space: pre-wrap;\n            word-wrap: break-word;\n            font-size: 13px;\n        }\n\n        .tools-list {\n            background: rgb(60, 55, 40);\n            padding: 12px 16px;\n            border-radius: 4px;\n            margin-bottom: 16px;\n        }\n\n        .tools-header {\n            font-weight: bold;\n            color: ${COLORS.yellow};\n            margin-bottom: 8px;\n        }\n\n        .tools-content {\n            color: ${COLORS.textDim};\n            font-size: 13px;\n        }\n\n        .tool-item {\n            margin: 4px 0;\n        }\n\n        .tool-item-name {\n            font-weight: bold;\n            color: ${COLORS.text};\n        }\n\n        /* Diff styling */\n        .tool-diff {\n            margin-top: 12px;\n            font-size: 13px;\n            font-family: 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, 'Courier New', monospace;\n            overflow-x: auto;\n            max-width: 100%;\n        }\n\n        .diff-line-old {\n            color: ${COLORS.red};\n            white-space: pre;\n        }\n\n        .diff-line-new {\n            color: ${COLORS.green};\n            white-space: pre;\n        }\n\n        .diff-line-context {\n            color: ${COLORS.textDim};\n            white-space: pre;\n        }\n\n        /* Error text */\n        .error-text {\n            color: ${COLORS.red};\n            padding: 12px 16px;\n        }\n\n        .footer {\n            margin-top: 48px;\n            padding: 20px;\n            text-align: center;\n            color: ${COLORS.textDim};\n            font-size: 12px;\n        }\n\n        @media print {\n            body {\n                background: white;\n                color: black;\n            }\n            .tool-execution {\n                border: 1px solid #ddd;\n            }\n        }\n    </style>\n</head>\n<body>\n    <div class=\"container\">\n        <div class=\"header\">\n            <h1>pi v${VERSION}</h1>\n            <div class=\"header-info\">\n                <div class=\"info-item\">\n                    <span class=\"info-label\">Session:</span>\n                    <span class=\"info-value\">${escapeHtml(sessionHeader?.id || \"unknown\")}</span>\n                </div>\n                <div class=\"info-item\">\n                    <span class=\"info-label\">Date:</span>\n                    <span class=\"info-value\">${sessionHeader?.timestamp ? new Date(sessionHeader.timestamp).toLocaleString() : timestamp}</span>\n                </div>\n                <div class=\"info-item\">\n                    <span class=\"info-label\">Model:</span>\n                    <span class=\"info-value\">${escapeHtml(sessionHeader?.model || state.model.id)}</span>\n                </div>\n                <div class=\"info-item\">\n                    <span class=\"info-label\">Messages:</span>\n                    <span class=\"info-value\">${messages.filter((m) => m.role !== \"toolResult\").length}</span>\n                </div>\n                <div class=\"info-item\">\n                    <span class=\"info-label\">Directory:</span>\n                    <span class=\"info-value\">${escapeHtml(shortenPath(sessionHeader?.cwd || process.cwd()))}</span>\n                </div>\n                <div class=\"info-item\">\n                    <span class=\"info-label\">Thinking:</span>\n                    <span class=\"info-value\">${escapeHtml(sessionHeader?.thinkingLevel || state.thinkingLevel)}</span>\n                </div>\n            </div>\n        </div>\n\n        <div class=\"system-prompt\">\n            <div class=\"system-prompt-header\">System Prompt</div>\n            <div class=\"system-prompt-content\">${escapeHtml(sessionHeader?.systemPrompt || state.systemPrompt)}</div>\n        </div>\n\n        <div class=\"tools-list\">\n            <div class=\"tools-header\">Available Tools</div>\n            <div class=\"tools-content\">\n                ${state.tools\n\t\t\t\t\t\t\t.map(\n\t\t\t\t\t\t\t\t(tool) =>\n\t\t\t\t\t\t\t\t\t`<div class=\"tool-item\"><span class=\"tool-item-name\">${escapeHtml(tool.name)}</span> - ${escapeHtml(tool.description)}</div>`,\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\t.join(\"\")}\n            </div>\n        </div>\n\n        <div class=\"messages\">\n            ${messagesHtml}\n        </div>\n\n        <div class=\"footer\">\n            Generated by pi coding-agent on ${new Date().toLocaleString()}\n        </div>\n    </div>\n</body>\n</html>`;\n\n\t// Write HTML file\n\twriteFileSync(outputPath, html, \"utf8\");\n\n\treturn outputPath;\n}\n"]}