From ee64d294877d1797f936c68e583c1ad4163f91c6 Mon Sep 17 00:00:00 2001
From: Mario Zechner <badlogicgames@gmail.com>
Date: Wed, 31 Dec 2025 13:50:01 +0100
Subject: [PATCH] Fix sdk.md and rpc.md to match actual API

- Remove incorrect prompt(AppMessage) overload
- Change AppMessage to AgentMessage
- Change null to undefined for optional returns
- sendHookMessage returns Promise<void>
- Update rpc.md for entryId change
---
 packages/coding-agent/docs/rpc.md |  6 +++---
 packages/coding-agent/docs/sdk.md | 13 ++++++-------
 2 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/packages/coding-agent/docs/rpc.md b/packages/coding-agent/docs/rpc.md
index 491049c6..bf1276f0 100644
--- a/packages/coding-agent/docs/rpc.md
+++ b/packages/coding-agent/docs/rpc.md
@@ -491,7 +491,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 +530,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..."}
     ]
   }
 }
diff --git a/packages/coding-agent/docs/sdk.md b/packages/coding-agent/docs/sdk.md
index bd86f465..9a8354dc 100644
--- a/packages/coding-agent/docs/sdk.md
+++ b/packages/coding-agent/docs/sdk.md
@@ -78,7 +78,6 @@ The session manages the agent lifecycle, message history, and event streaming.
 interface AgentSession {
   // Send a prompt and wait for completion
   prompt(text: string, options?: PromptOptions): Promise<void>;
-  prompt(message: AppMessage): Promise<void>;  // For HookMessage, etc.
   
   // Subscribe to events (returns unsubscribe function)
   subscribe(listener: (event: AgentSessionEvent) => void): () => void;
@@ -90,14 +89,14 @@ interface AgentSession {
   // 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
@@ -109,7 +108,7 @@ interface AgentSession {
   navigateTree(targetId: string, options?: { summarize?: boolean }): Promise<{ editorText?: string; cancelled: boolean }>;  // In-place navigation
   
   // Hook message injection
-  sendHookMessage(message: HookMessage, triggerTurn?: boolean): void;
+  sendHookMessage(message: HookMessage, triggerTurn?: boolean): Promise<void>;
   
   // Compaction
   compact(customInstructions?: string): Promise<CompactionResult>;
@@ -131,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