@mariozechner/pi-coding-agent 0.30.2 → 0.31.0

package/docs/rpc.md

@@ -36,9 +36,9 @@ Send a user prompt to the agent. Returns immediately; events stream asynchronous
 {"id": "req-1", "type": "prompt", "message": "Hello, world!"}
 ```
 
-With attachments:
+With images:
 ```json
-{"type": "prompt", "message": "What's in this image?", "attachments": [...]}
+{"type": "prompt", "message": "What's in this image?", "images": [{"type": "image", "source": {"type": "base64", "mediaType": "image/png", "data": "..."}}]}
 ```
 
 Response:
@@ -46,7 +46,7 @@ Response:
 {"id": "req-1", "type": "response", "command": "prompt", "success": true}
 ```
 
-The `attachments` field is optional. See [Attachments](#attachments) for the schema.
+The `images` field is optional. Each image uses `ImageContent` format with base64 or URL source.
 
 #### queue_message
 
@@ -76,22 +76,27 @@ Response:
 {"type": "response", "command": "abort", "success": true}
 ```
 
-#### reset
+#### new_session
 
-Clear context and start a fresh session. Can be cancelled by a `before_clear` hook.
+Start a fresh session. Can be cancelled by a `session_before_switch` hook.
 
 ```json
-{"type": "reset"}
+{"type": "new_session"}
+```
+
+With optional parent session tracking:
+```json
+{"type": "new_session", "parentSession": "/path/to/parent-session.jsonl"}
 ```
 
 Response:
 ```json
-{"type": "response", "command": "reset", "success": true, "data": {"cancelled": false}}
+{"type": "response", "command": "new_session", "success": true, "data": {"cancelled": false}}
 ```
 
-If a hook cancelled the reset:
+If a hook cancelled:
 ```json
-{"type": "response", "command": "reset", "success": true, "data": {"cancelled": true}}
+{"type": "response", "command": "new_session", "success": true, "data": {"cancelled": true}}
 ```
 
 ### State
@@ -145,7 +150,7 @@ Response:
 }
 ```
 
-Messages are `AppMessage` objects (see [Message Types](#message-types)).
+Messages are `AgentMessage` objects (see [Message Types](#message-types)).
 
 ### Model
 
@@ -289,8 +294,10 @@ Response:
   "command": "compact",
   "success": true,
   "data": {
+    "summary": "Summary of conversation...",
+    "firstKeptEntryId": "abc123",
     "tokensBefore": 150000,
-    "summary": "Summary of conversation..."
+    "details": {}
   }
 }
 ```
@@ -491,7 +498,7 @@ If a hook cancelled the switch:
 Create a new branch from a previous user message. Can be cancelled by a `before_branch` hook. Returns the text of the message being branched from.
 
 ```json
-{"type": "branch", "entryIndex": 2}
+{"type": "branch", "entryId": "abc123"}
 ```
 
 Response:
@@ -530,8 +537,8 @@ Response:
   "success": true,
   "data": {
     "messages": [
-      {"entryIndex": 0, "text": "First prompt..."},
-      {"entryIndex": 2, "text": "Second prompt..."}
+      {"entryId": "abc123", "text": "First prompt..."},
+      {"entryId": "def456", "text": "Second prompt..."}
     ]
   }
 }
@@ -618,7 +625,7 @@ A turn consists of one assistant response plus any resulting tool calls and resu
 
 ### message_start / message_end
 
-Emitted when a message begins and completes. The `message` field contains an `AppMessage`.
+Emitted when a message begins and completes. The `message` field contains an `AgentMessage`.
 
 ```json
 {"type": "message_start", "message": {...}}
@@ -717,20 +724,27 @@ Use `toolCallId` to correlate events. The `partialResult` in `tool_execution_upd
 Emitted when automatic compaction runs (when context is nearly full).
 
 ```json
-{"type": "auto_compaction_start"}
+{"type": "auto_compaction_start", "reason": "threshold"}
 ```
 
+The `reason` field is `"threshold"` (context getting large) or `"overflow"` (context exceeded limit).
+
 ```json
 {
   "type": "auto_compaction_end",
   "result": {
+    "summary": "Summary of conversation...",
+    "firstKeptEntryId": "abc123",
     "tokensBefore": 150000,
-    "summary": "Summary of conversation..."
+    "details": {}
   },
-  "aborted": false
+  "aborted": false,
+  "willRetry": false
 }
 ```
 
+If `reason` was `"overflow"` and compaction succeeds, `willRetry` is `true` and the agent will automatically retry the prompt.
+
 If compaction was aborted, `result` is `null` and `aborted` is `true`.
 
 ### auto_retry_start / auto_retry_end
@@ -806,7 +820,7 @@ Parse errors:
 
 Source files:
 - [`packages/ai/src/types.ts`](../../ai/src/types.ts) - `Model`, `UserMessage`, `AssistantMessage`, `ToolResultMessage`
-- [`packages/agent/src/types.ts`](../../agent/src/types.ts) - `AppMessage`, `Attachment`, `AgentEvent`
+- [`packages/agent/src/types.ts`](../../agent/src/types.ts) - `AgentMessage`, `AgentEvent`
 - [`src/core/messages.ts`](../src/core/messages.ts) - `BashExecutionMessage`
 - [`src/modes/rpc/rpc-types.ts`](../src/modes/rpc/rpc-types.ts) - RPC command/response types
 

package/docs/sdk.md

@@ -1,3 +1,5 @@
+> pi can help you use the SDK. Ask it to build an integration for your use case.
+
 # SDK
 
 The SDK provides programmatic access to pi's agent capabilities. Use it to embed pi in other applications, build custom interfaces, or integrate with automated workflows.
@@ -81,26 +83,32 @@ interface AgentSession {
   subscribe(listener: (event: AgentSessionEvent) => void): () => void;
   
   // Session info
-  sessionFile: string | null;
+  sessionFile: string | undefined;  // undefined for in-memory
   sessionId: string;
   
   // Model control
   setModel(model: Model): Promise<void>;
   setThinkingLevel(level: ThinkingLevel): void;
-  cycleModel(): Promise<ModelCycleResult | null>;
-  cycleThinkingLevel(): ThinkingLevel | null;
+  cycleModel(): Promise<ModelCycleResult | undefined>;
+  cycleThinkingLevel(): ThinkingLevel | undefined;
   
   // State access
   agent: Agent;
-  model: Model | null;
+  model: Model | undefined;
   thinkingLevel: ThinkingLevel;
-  messages: AppMessage[];
+  messages: AgentMessage[];
   isStreaming: boolean;
   
   // Session management
-  reset(): Promise<void>;
-  branch(entryIndex: number): Promise<{ selectedText: string; skipped: boolean }>;
-  switchSession(sessionPath: string): Promise<void>;
+  newSession(options?: { parentSession?: string }): Promise<boolean>;  // Returns false if cancelled by hook
+  switchSession(sessionPath: string): Promise<boolean>;
+  
+  // Branching
+  branch(entryId: string): Promise<{ selectedText: string; cancelled: boolean }>;  // Creates new session file
+  navigateTree(targetId: string, options?: { summarize?: boolean }): Promise<{ editorText?: string; cancelled: boolean }>;  // In-place navigation
+  
+  // Hook message injection
+  sendHookMessage(message: HookMessage, triggerTurn?: boolean): Promise<void>;
   
   // Compaction
   compact(customInstructions?: string): Promise<CompactionResult>;
@@ -122,7 +130,7 @@ The `Agent` class (from `@mariozechner/pi-agent-core`) handles the core LLM inte
 // Access current state
 const state = session.agent.state;
 
-// state.messages: AppMessage[] - conversation history
+// state.messages: AgentMessage[] - conversation history
 // state.model: Model - current model
 // state.thinkingLevel: ThinkingLevel - current thinking level
 // state.systemPrompt: string - system prompt
@@ -394,10 +402,10 @@ const { session } = await createAgentSession({
 
 ```typescript
 import { Type } from "@sinclair/typebox";
-import { createAgentSession, discoverCustomTools, type CustomAgentTool } from "@mariozechner/pi-coding-agent";
+import { createAgentSession, discoverCustomTools, type CustomTool } from "@mariozechner/pi-coding-agent";
 
 // Inline custom tool
-const myTool: CustomAgentTool = {
+const myTool: CustomTool = {
   name: "my_tool",
   label: "My Tool",
   description: "Does something useful",
@@ -436,18 +444,38 @@ import { createAgentSession, discoverHooks, type HookFactory } from "@mariozechn
 
 // Inline hook
 const loggingHook: HookFactory = (api) => {
+  // Log tool calls
   api.on("tool_call", async (event) => {
     console.log(`Tool: ${event.toolName}`);
     return undefined; // Don't block
   });
   
+  // Block dangerous commands
   api.on("tool_call", async (event) => {
-    // Block dangerous commands
     if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
       return { block: true, reason: "Dangerous command" };
     }
     return undefined;
   });
+  
+  // Register custom slash command
+  api.registerCommand("stats", {
+    description: "Show session stats",
+    handler: async (ctx) => {
+      const entries = ctx.sessionManager.getEntries();
+      ctx.ui.notify(`${entries.length} entries`, "info");
+    },
+  });
+  
+  // Inject messages
+  api.sendMessage({
+    customType: "my-hook",
+    content: "Hook initialized",
+    display: false,  // Hidden from TUI
+  }, false);  // Don't trigger agent turn
+  
+  // Persist hook state
+  api.appendEntry("my-hook", { initialized: true });
 };
 
 // Replace discovery
@@ -472,7 +500,15 @@ const { session } = await createAgentSession({
 });
 ```
 
-> See [examples/sdk/06-hooks.ts](../examples/sdk/06-hooks.ts)
+Hook API methods:
+- `api.on(event, handler)` - Subscribe to events
+- `api.sendMessage(message, triggerTurn?)` - Inject message (creates `CustomMessageEntry`)
+- `api.appendEntry(customType, data?)` - Persist hook state (not in LLM context)
+- `api.registerCommand(name, options)` - Register custom slash command
+- `api.registerMessageRenderer(customType, renderer)` - Custom TUI rendering
+- `api.exec(command, args, options?)` - Execute shell commands
+
+> See [examples/sdk/06-hooks.ts](../examples/sdk/06-hooks.ts) and [docs/hooks.md](hooks.md)
 
 ### Skills
 
@@ -560,6 +596,8 @@ const { session } = await createAgentSession({
 
 ### Session Management
 
+Sessions use a tree structure with `id`/`parentId` linking, enabling in-place branching.
+
 ```typescript
 import { createAgentSession, SessionManager } from "@mariozechner/pi-coding-agent";
 
@@ -597,12 +635,32 @@ const customDir = "/path/to/my-sessions";
 const { session } = await createAgentSession({
   sessionManager: SessionManager.create(process.cwd(), customDir),
 });
-// Also works with list and continueRecent:
-// SessionManager.list(process.cwd(), customDir);
-// SessionManager.continueRecent(process.cwd(), customDir);
 ```
 
-> See [examples/sdk/11-sessions.ts](../examples/sdk/11-sessions.ts)
+**SessionManager tree API:**
+
+```typescript
+const sm = SessionManager.open("/path/to/session.jsonl");
+
+// Tree traversal
+const entries = sm.getEntries();        // All entries (excludes header)
+const tree = sm.getTree();              // Full tree structure
+const path = sm.getPath();              // Path from root to current leaf
+const leaf = sm.getLeafEntry();         // Current leaf entry
+const entry = sm.getEntry(id);          // Get entry by ID
+const children = sm.getChildren(id);    // Direct children of entry
+
+// Labels
+const label = sm.getLabel(id);          // Get label for entry
+sm.appendLabelChange(id, "checkpoint"); // Set label
+
+// Branching
+sm.branch(entryId);                     // Move leaf to earlier entry
+sm.branchWithSummary(id, "Summary...");  // Branch with context summary
+sm.createBranchedSession(leafId);       // Extract path to new file
+```
+
+> See [examples/sdk/11-sessions.ts](../examples/sdk/11-sessions.ts) and [docs/session.md](session.md)
 
 ### Settings Management
 
@@ -737,7 +795,7 @@ import {
   readTool,
   bashTool,
   type HookFactory,
-  type CustomAgentTool,
+  type CustomTool,
 } from "@mariozechner/pi-coding-agent";
 
 // Set up auth storage (custom location)
@@ -760,7 +818,7 @@ const auditHook: HookFactory = (api) => {
 };
 
 // Inline tool
-const statusTool: CustomAgentTool = {
+const statusTool: CustomTool = {
   name: "status",
   label: "Status",
   description: "Get system status",
@@ -876,7 +934,7 @@ createGrepTool, createFindTool, createLsTool
 // Types
 type CreateAgentSessionOptions
 type CreateAgentSessionResult
-type CustomAgentTool
+type CustomTool
 type HookFactory
 type Skill
 type FileSlashCommand
@@ -888,7 +946,21 @@ type Tool
 For hook types, import from the hooks subpath:
 
 ```typescript
-import type { HookAPI, HookEvent, ToolCallEvent } from "@mariozechner/pi-coding-agent/hooks";
+import type {
+  HookAPI,
+  HookMessage,
+  HookFactory,
+  HookEventContext,
+  HookCommandContext,
+  ToolCallEvent,
+  ToolResultEvent,
+} from "@mariozechner/pi-coding-agent/hooks";
+```
+
+For message utilities:
+
+```typescript
+import { isHookMessage, createHookMessage } from "@mariozechner/pi-coding-agent";
 ```
 
 For config utilities: