From 5d290f048edf86770f72cdc8ede0f68e40169c51 Mon Sep 17 00:00:00 2001
From: Mario Zechner <badlogicgames@gmail.com>
Date: Mon, 22 Dec 2025 12:32:25 +0100
Subject: [PATCH] Fix SDK docs: AgentSession interface, findModel usage,
 settings example

---
 packages/coding-agent/docs/sdk.md | 53 +++++++++++++++++++++----------
 packages/coding-agent/src/main.ts |  3 +-
 2 files changed, 39 insertions(+), 17 deletions(-)

diff --git a/packages/coding-agent/docs/sdk.md b/packages/coding-agent/docs/sdk.md
index ae840b73..0d35d54f 100644
--- a/packages/coding-agent/docs/sdk.md
+++ b/packages/coding-agent/docs/sdk.md
@@ -79,18 +79,32 @@ interface AgentSession {
   sessionId: string;
   
   // Model control
-  setModel(model: Model, thinkingLevel?: ThinkingLevel): void;
+  setModel(model: Model): Promise<void>;
   setThinkingLevel(level: ThinkingLevel): void;
+  cycleModel(): Promise<ModelCycleResult | null>;
+  cycleThinkingLevel(): ThinkingLevel | null;
   
-  // Access underlying agent
+  // State access
   agent: Agent;
+  model: Model | null;
+  thinkingLevel: ThinkingLevel;
+  messages: AppMessage[];
+  isStreaming: boolean;
   
   // Session management
-  reset(): void;
-  branch(targetTurnIndex: number): Promise<void>;
+  reset(): Promise<void>;
+  branch(entryIndex: number): Promise<{ selectedText: string; skipped: boolean }>;
+  switchSession(sessionPath: string): Promise<void>;
+  
+  // Compaction
+  compact(customInstructions?: string): Promise<CompactionResult>;
+  abortCompaction(): void;
   
   // Abort current operation
-  abort(): void;
+  abort(): Promise<void>;
+  
+  // Cleanup
+  dispose(): void;
 }
 ```
 
@@ -215,15 +229,17 @@ const { session } = await createAgentSession({
 ```typescript
 import { findModel, discoverAvailableModels } from "@mariozechner/pi-coding-agent";
 
-// Find specific model
-const { model } = findModel("anthropic", "claude-sonnet-4-20250514");
+// Find specific model (returns { model, error })
+const { model, error } = findModel("anthropic", "claude-sonnet-4-20250514");
+if (error) throw new Error(error);
+if (!model) throw new Error("Model not found");
 
 // Or get all models with valid API keys
 const available = await discoverAvailableModels();
 
 const { session } = await createAgentSession({
   model: model,
-  thinkingLevel: "medium", // off, low, medium, high
+  thinkingLevel: "medium", // off, minimal, low, medium, high, xhigh
   
   // Models for cycling (Ctrl+P in interactive mode)
   scopedModels: [
@@ -580,8 +596,8 @@ const contextFiles = discoverContextFiles(cwd, agentDir);
 // Slash commands
 const commands = discoverSlashCommands(cwd, agentDir);
 
-// Settings
-const settings = loadSettings(agentDir);
+// Settings (global + project merged)
+const settings = loadSettings(cwd, agentDir);
 
 // Build system prompt manually
 const prompt = buildSystemPrompt({
@@ -622,6 +638,7 @@ import {
   defaultGetApiKey,
   findModel,
   SessionManager,
+  SettingsManager,
   readTool,
   bashTool,
   type HookFactory,
@@ -660,9 +677,16 @@ const statusTool: CustomAgentTool = {
   }),
 };
 
-const { model } = findModel("anthropic", "claude-sonnet-4-20250514");
+const { model, error } = findModel("anthropic", "claude-sonnet-4-20250514");
+if (error) throw new Error(error);
 if (!model) throw new Error("Model not found");
 
+// In-memory settings with overrides
+const settingsManager = SettingsManager.inMemory({
+  compaction: { enabled: false },
+  retry: { enabled: true, maxRetries: 2 },
+});
+
 const { session } = await createAgentSession({
   cwd: process.cwd(),
   agentDir: "/custom/agent",
@@ -681,11 +705,7 @@ const { session } = await createAgentSession({
   slashCommands: [],
   
   sessionManager: SessionManager.inMemory(),
-  
-  settings: {
-    compaction: { enabled: false },
-    retry: { enabled: true, maxRetries: 2 },
-  },
+  settingsManager,
 });
 
 session.subscribe((event) => {
@@ -744,6 +764,7 @@ buildSystemPrompt
 
 // Session management
 SessionManager
+SettingsManager
 
 // Built-in tools
 codingTools
diff --git a/packages/coding-agent/src/main.ts b/packages/coding-agent/src/main.ts
index 1ad5616e..0987d3f6 100644
--- a/packages/coding-agent/src/main.ts
+++ b/packages/coding-agent/src/main.ts
@@ -17,6 +17,7 @@ import { getModelsPath, VERSION } from "./config.js";
 import type { AgentSession } from "./core/agent-session.js";
 import type { LoadedCustomTool } from "./core/custom-tools/index.js";
 import { exportFromFile } from "./core/export-html.js";
+import type { HookUIContext } from "./core/index.js";
 import { findModel } from "./core/model-config.js";
 import { resolveModelScope, type ScopedModel } from "./core/model-resolver.js";
 import { type CreateAgentSessionOptions, configureOAuthStorage, createAgentSession } from "./core/sdk.js";
@@ -54,7 +55,7 @@ async function runInteractiveMode(
 	versionCheckPromise: Promise<string | null>,
 	initialMessages: string[],
 	customTools: LoadedCustomTool[],
-	setToolUIContext: (uiContext: import("./core/hooks/types.js").HookUIContext, hasUI: boolean) => void,
+	setToolUIContext: (uiContext: HookUIContext, hasUI: boolean) => void,
 	initialMessage?: string,
 	initialAttachments?: Attachment[],
 	fdPath: string | null = null,