@mariozechner/pi-coding-agent 0.49.2 → 0.50.0

package/docs/session.md

@@ -26,11 +26,147 @@ Sessions have a version field in the header:
 
 Existing sessions are automatically migrated to the current version (v3) when loaded.
 
-## Type Definitions
+## Source Files
 
-- [`src/core/session-manager.ts`](../src/core/session-manager.ts) - Session entry types
-- [`packages/agent-core/src/types.ts`](../../agent-core/src/types.ts) - `AgentMessage`
-- [`packages/ai/src/types.ts`](../../ai/src/types.ts) - `UserMessage`, `AssistantMessage`, `ToolResultMessage`, `Usage`, `ToolCall`, `ImageContent`, `TextContent`
+Source on GitHub ([pi-mono](https://github.com/badlogic/pi-mono)):
+- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts) - Session entry types and SessionManager
+- [`packages/coding-agent/src/core/messages.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
+- [`packages/ai/src/types.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/types.ts) - Base message types (UserMessage, AssistantMessage, ToolResultMessage)
+- [`packages/agent/src/types.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/agent/src/types.ts) - AgentMessage union type
+
+For TypeScript definitions in your project, inspect `node_modules/@mariozechner/pi-coding-agent/dist/` and `node_modules/@mariozechner/pi-ai/dist/`.
+
+## Message Types
+
+Session entries contain `AgentMessage` objects. Understanding these types is essential for parsing sessions and writing extensions.
+
+### Content Blocks
+
+Messages contain arrays of typed content blocks:
+
+```typescript
+interface TextContent {
+  type: "text";
+  text: string;
+}
+
+interface ImageContent {
+  type: "image";
+  data: string;      // base64 encoded
+  mimeType: string;  // e.g., "image/jpeg", "image/png"
+}
+
+interface ThinkingContent {
+  type: "thinking";
+  thinking: string;
+}
+
+interface ToolCall {
+  type: "toolCall";
+  id: string;
+  name: string;
+  arguments: Record<string, any>;
+}
+```
+
+### Base Message Types (from pi-ai)
+
+```typescript
+interface UserMessage {
+  role: "user";
+  content: string | (TextContent | ImageContent)[];
+  timestamp: number;  // Unix ms
+}
+
+interface AssistantMessage {
+  role: "assistant";
+  content: (TextContent | ThinkingContent | ToolCall)[];
+  api: string;
+  provider: string;
+  model: string;
+  usage: Usage;
+  stopReason: "stop" | "length" | "toolUse" | "error" | "aborted";
+  errorMessage?: string;
+  timestamp: number;
+}
+
+interface ToolResultMessage {
+  role: "toolResult";
+  toolCallId: string;
+  toolName: string;
+  content: (TextContent | ImageContent)[];
+  details?: any;      // Tool-specific metadata
+  isError: boolean;
+  timestamp: number;
+}
+
+interface Usage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  };
+}
+```
+
+### Extended Message Types (from pi-coding-agent)
+
+```typescript
+interface BashExecutionMessage {
+  role: "bashExecution";
+  command: string;
+  output: string;
+  exitCode: number | undefined;
+  cancelled: boolean;
+  truncated: boolean;
+  fullOutputPath?: string;
+  excludeFromContext?: boolean;  // true for !! prefix commands
+  timestamp: number;
+}
+
+interface CustomMessage {
+  role: "custom";
+  customType: string;            // Extension identifier
+  content: string | (TextContent | ImageContent)[];
+  display: boolean;              // Show in TUI
+  details?: any;                 // Extension-specific metadata
+  timestamp: number;
+}
+
+interface BranchSummaryMessage {
+  role: "branchSummary";
+  summary: string;
+  fromId: string;                // Entry we branched from
+  timestamp: number;
+}
+
+interface CompactionSummaryMessage {
+  role: "compactionSummary";
+  summary: string;
+  tokensBefore: number;
+  timestamp: number;
+}
+```
+
+### AgentMessage Union
+
+```typescript
+type AgentMessage =
+  | UserMessage
+  | AssistantMessage
+  | ToolResultMessage
+  | BashExecutionMessage
+  | CustomMessage
+  | BranchSummaryMessage
+  | CompactionSummaryMessage;
+```
 
 ## Entry Base
 
@@ -96,8 +232,8 @@ Created when context is compacted. Stores a summary of earlier messages.
 ```
 
 Optional fields:
-- `details`: Compaction-implementation specific data (e.g., file operations for default implementation, or custom data for extension implementations)
-- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated
+- `details`: Implementation-specific data (e.g., `{ readFiles: string[], modifiedFiles: string[] }` for default, or custom data for extensions)
+- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated (legacy field name)
 
 ### BranchSummaryEntry
 
@@ -108,8 +244,8 @@ Created when switching branches via `/tree` with an LLM generated summary of the
 ```
 
 Optional fields:
-- `details`: File tracking data (`{ readFiles: string[], modifiedFiles: string[] }`) for default implementation, arbitrary for custom implementation
-- `fromHook`: `true` if generated by an extension
+- `details`: File tracking data (`{ readFiles: string[], modifiedFiles: string[] }`) for default, or custom data for extensions
+- `fromHook`: `true` if generated by an extension, `false`/`undefined` if pi-generated (legacy field name)
 
 ### CustomEntry
 
@@ -224,15 +360,25 @@ for (const line of lines) {
 
 ## SessionManager API
 
-Key methods for working with sessions programmatically:
+Key methods for working with sessions programmatically.
 
-### Creation
+### Static Creation Methods
 - `SessionManager.create(cwd, sessionDir?)` - New session
-- `SessionManager.open(path, sessionDir?)` - Open existing
+- `SessionManager.open(path, sessionDir?)` - Open existing session file
 - `SessionManager.continueRecent(cwd, sessionDir?)` - Continue most recent or create new
 - `SessionManager.inMemory(cwd?)` - No file persistence
+- `SessionManager.forkFrom(sourcePath, targetCwd, sessionDir?)` - Fork session from another project
+
+### Static Listing Methods
+- `SessionManager.list(cwd, sessionDir?, onProgress?)` - List sessions for a directory
+- `SessionManager.listAll(onProgress?)` - List all sessions across all projects
+
+### Instance Methods - Session Management
+- `newSession(options?)` - Start a new session (options: `{ parentSession?: string }`)
+- `setSessionFile(path)` - Switch to a different session file
+- `createBranchedSession(leafId)` - Extract branch to new session file
 
-### Appending (all return entry ID)
+### Instance Methods - Appending (all return entry ID)
 - `appendMessage(message)` - Add message
 - `appendThinkingLevelChange(level)` - Record thinking change
 - `appendModelChange(provider, modelId)` - Record model change
@@ -242,7 +388,7 @@ Key methods for working with sessions programmatically:
 - `appendCustomMessageEntry(customType, content, display, details?)` - Extension message (in context)
 - `appendLabelChange(targetId, label)` - Set/clear label
 
-### Tree Navigation
+### Instance Methods - Tree Navigation
 - `getLeafId()` - Current position
 - `getLeafEntry()` - Get current leaf entry
 - `getEntry(id)` - Get entry by ID
@@ -254,8 +400,13 @@ Key methods for working with sessions programmatically:
 - `resetLeaf()` - Reset leaf to null (before any entries)
 - `branchWithSummary(entryId, summary, details?, fromHook?)` - Branch with context summary
 
-### Context
-- `buildSessionContext()` - Get messages for LLM
+### Instance Methods - Context & Info
+- `buildSessionContext()` - Get messages, thinkingLevel, and model for LLM
 - `getEntries()` - All entries (excluding header)
-- `getHeader()` - Session metadata
+- `getHeader()` - Session header metadata
 - `getSessionName()` - Get display name from latest session_info entry
+- `getCwd()` - Working directory
+- `getSessionDir()` - Session storage directory
+- `getSessionId()` - Session UUID
+- `getSessionFile()` - Session file path (undefined for in-memory)
+- `isPersisted()` - Whether session is saved to disk

package/docs/settings.md

@@ -0,0 +1,216 @@
+# Settings
+
+Pi uses JSON settings files with project settings overriding global settings.
+
+| Location | Scope |
+|----------|-------|
+| `~/.pi/agent/settings.json` | Global (all projects) |
+| `.pi/settings.json` | Project (current directory) |
+
+Edit directly or use `/settings` for common options.
+
+## All Settings
+
+### Model & Thinking
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `defaultProvider` | string | - | Default provider (e.g., `"anthropic"`, `"openai"`) |
+| `defaultModel` | string | - | Default model ID |
+| `defaultThinkingLevel` | string | - | `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"` |
+| `hideThinkingBlock` | boolean | `false` | Hide thinking blocks in output |
+| `thinkingBudgets` | object | - | Custom token budgets per thinking level |
+
+#### thinkingBudgets
+
+```json
+{
+  "thinkingBudgets": {
+    "minimal": 1024,
+    "low": 4096,
+    "medium": 10240,
+    "high": 32768
+  }
+}
+```
+
+### UI & Display
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `theme` | string | `"dark"` | Theme name (`"dark"`, `"light"`, or custom) |
+| `quietStartup` | boolean | `false` | Hide startup header |
+| `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
+| `doubleEscapeAction` | string | `"tree"` | Action for double-escape: `"tree"` or `"fork"` |
+| `editorPaddingX` | number | `0` | Horizontal padding for input editor (0-3) |
+| `showHardwareCursor` | boolean | `false` | Show terminal cursor |
+
+### Compaction
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `compaction.enabled` | boolean | `true` | Enable auto-compaction |
+| `compaction.reserveTokens` | number | `16384` | Tokens reserved for LLM response |
+| `compaction.keepRecentTokens` | number | `20000` | Recent tokens to keep (not summarized) |
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384,
+    "keepRecentTokens": 20000
+  }
+}
+```
+
+### Branch Summary
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `branchSummary.reserveTokens` | number | `16384` | Tokens reserved for branch summarization |
+
+### Retry
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `retry.enabled` | boolean | `true` | Enable automatic retry on transient errors |
+| `retry.maxRetries` | number | `3` | Maximum retry attempts |
+| `retry.baseDelayMs` | number | `2000` | Base delay for exponential backoff (2s, 4s, 8s) |
+
+```json
+{
+  "retry": {
+    "enabled": true,
+    "maxRetries": 3,
+    "baseDelayMs": 2000
+  }
+}
+```
+
+### Message Delivery
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `steeringMode` | string | `"one-at-a-time"` | How steering messages are sent: `"all"` or `"one-at-a-time"` |
+| `followUpMode` | string | `"one-at-a-time"` | How follow-up messages are sent: `"all"` or `"one-at-a-time"` |
+
+### Terminal & Images
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `terminal.showImages` | boolean | `true` | Show images in terminal (if supported) |
+| `images.autoResize` | boolean | `true` | Resize images to 2000x2000 max |
+| `images.blockImages` | boolean | `false` | Block all images from being sent to LLM |
+
+### Shell
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `shellPath` | string | - | Custom shell path (e.g., for Cygwin on Windows) |
+| `shellCommandPrefix` | string | - | Prefix for every bash command (e.g., `"shopt -s expand_aliases"`) |
+
+### Model Cycling
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `enabledModels` | string[] | - | Model patterns for Ctrl+P cycling (same format as `--models` CLI flag) |
+
+```json
+{
+  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
+}
+```
+
+### Markdown
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `markdown.codeBlockIndent` | string | `"  "` | Indentation for code blocks |
+
+### Resources
+
+These settings define where to load extensions, skills, prompts, and themes from.
+
+Paths in `~/.pi/agent/settings.json` resolve relative to `~/.pi/agent`. Paths in `.pi/settings.json` resolve relative to `.pi`. Absolute paths and `~` are supported.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `packages` | array | `[]` | npm/git packages to load resources from |
+| `extensions` | string[] | `[]` | Local extension file paths or directories |
+| `skills` | string[] | `[]` | Local skill file paths or directories |
+| `prompts` | string[] | `[]` | Local prompt template paths or directories |
+| `themes` | string[] | `[]` | Local theme file paths or directories |
+| `enableSkillCommands` | boolean | `true` | Register skills as `/skill:name` commands |
+
+Arrays support glob patterns and exclusions. Use `!pattern` to exclude. Use `+path` to force-include an exact path and `-path` to force-exclude an exact path.
+
+#### packages
+
+String form loads all resources from a package:
+
+```json
+{
+  "packages": ["pi-skills", "@org/my-extension"]
+}
+```
+
+Object form filters which resources to load:
+
+```json
+{
+  "packages": [
+    {
+      "source": "pi-skills",
+      "skills": ["brave-search", "transcribe"],
+      "extensions": []
+    }
+  ]
+}
+```
+
+See [packages.md](packages.md) for package management details.
+
+## Example
+
+```json
+{
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-sonnet-4-20250514",
+  "defaultThinkingLevel": "medium",
+  "theme": "dark",
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384,
+    "keepRecentTokens": 20000
+  },
+  "retry": {
+    "enabled": true,
+    "maxRetries": 3
+  },
+  "enabledModels": ["claude-*", "gpt-4o"],
+  "packages": ["pi-skills"]
+}
+```
+
+## Project Overrides
+
+Project settings (`.pi/settings.json`) override global settings. Nested objects are merged:
+
+```json
+// ~/.pi/agent/settings.json (global)
+{
+  "theme": "dark",
+  "compaction": { "enabled": true, "reserveTokens": 16384 }
+}
+
+// .pi/settings.json (project)
+{
+  "compaction": { "reserveTokens": 8192 }
+}
+
+// Result
+{
+  "theme": "dark",
+  "compaction": { "enabled": true, "reserveTokens": 8192 }
+}
+```

package/docs/shell-aliases.md

@@ -0,0 +1,13 @@
+# Shell Aliases
+
+Pi runs bash in non-interactive mode (`bash -c`), which doesn't expand aliases by default.
+
+To enable your shell aliases, add to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "shellCommandPrefix": "shopt -s expand_aliases\neval \"$(grep '^alias ' ~/.zshrc)\""
+}
+```
+
+Adjust the path (`~/.zshrc`, `~/.bashrc`, etc.) to match your shell config.