@oh-my-pi/pi-coding-agent 10.6.2 → 11.0.0

package/docs/sdk.md

@@ -21,14 +21,18 @@ import { createAgentSession, discoverAuthStorage, discoverModels, SessionManager
 
 // Set up credential storage and model registry
 const authStorage = await discoverAuthStorage();
-const modelRegistry = await discoverModels(authStorage);
+const modelRegistry = discoverModels(authStorage);
 
-const { session } = await createAgentSession({
+const { session, modelFallbackMessage } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
 	authStorage,
 	modelRegistry,
 });
 
+if (modelFallbackMessage) {
+	process.stderr.write(`${modelFallbackMessage}\n`);
+}
+
 session.subscribe((event) => {
 	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
 		process.stdout.write(event.assistantMessageEvent.delta);
@@ -41,7 +45,7 @@ await session.prompt("What files are in the current directory?");
 ## Installation
 
 ```bash
-npm install @oh-my-pi/pi-coding-agent
+bun add @oh-my-pi/pi-coding-agent
 ```
 
 The SDK is included in the main package. No separate installation needed.
@@ -59,15 +63,16 @@ The main factory function. Creates an `AgentSession` with configurable options.
 
 ```typescript
 import { createAgentSession } from "@oh-my-pi/pi-coding-agent";
+import systemPrompt from "./SYSTEM.md" with { type: "text" };
 
-// Minimal: all defaults (discovers everything from cwd and ~/.omp/agent)
+// Minimal: all defaults (discovers from cwd + config dirs and ~/.omp/agent)
 const { session } = await createAgentSession();
 
 // Custom: override specific options
 const { session } = await createAgentSession({
 	model: myModel,
-	systemPrompt: "You are helpful.",
-	tools: [readTool, bashTool],
+	systemPrompt,
+	toolNames: ["read", "bash", "edit"], // Filter to specific tools
 	sessionManager: SessionManager.inMemory(),
 });
 ```
@@ -78,8 +83,14 @@ The session manages the agent lifecycle, message history, and event streaming.
 
 ```typescript
 interface AgentSession {
-	// Send a prompt and wait for completion
+	// Prompting
 	prompt(text: string, options?: PromptOptions): Promise<void>;
+	sendUserMessage(
+		content: string | (TextContent | ImageContent)[],
+		options?: { deliverAs?: "steer" | "followUp" },
+	): Promise<void>;
+	steer(text: string): void;
+	followUp(text: string): void;
 
 	// Subscribe to events (returns unsubscribe function)
 	subscribe(listener: (event: AgentSessionEvent) => void): () => void;
@@ -87,43 +98,65 @@ interface AgentSession {
 	// Session info
 	sessionFile: string | undefined; // undefined for in-memory
 	sessionId: string;
+	sessionName: string | undefined;
 
 	// Model control
-	setModel(model: Model): Promise<void>;
+	setModel(model: Model, role?: ModelRole): Promise<void>;
+	setModelTemporary(model: Model): Promise<void>;
 	setThinkingLevel(level: ThinkingLevel): void;
-	cycleModel(): Promise<ModelCycleResult | undefined>;
+	cycleModel(direction?: "forward" | "backward"): Promise<ModelCycleResult | undefined>;
+	cycleRoleModels(
+		direction?: "forward" | "backward",
+	): Promise<{ model: Model; thinkingLevel: ThinkingLevel; role: ModelRole } | undefined>;
 	cycleThinkingLevel(): ThinkingLevel | undefined;
 
 	// State access
 	agent: Agent;
+	sessionManager: SessionManager;
+	settings: Settings;
 	model: Model | undefined;
 	thinkingLevel: ThinkingLevel;
 	messages: AgentMessage[];
 	isStreaming: boolean;
+	isCompacting: boolean;
+	isRetrying: boolean;
 
 	// Session management
-	newSession(options?: { parentSession?: string }): Promise<boolean>; // Returns false if cancelled by hook
-	switchSession(sessionPath: string): Promise<boolean>;
+	newSession(options?: NewSessionOptions): Promise<boolean>; // Returns false if cancelled by extension
+	fork(): Promise<boolean>; // Creates a new session file
 
 	// Branching
-	branch(entryId: string): Promise<{ selectedText: string; cancelled: boolean }>; // Creates new session file
+	branch(entryId: string): Promise<{ selectedText: string; cancelled: boolean }>;
 	navigateTree(
 		targetId: string,
-		options?: { summarize?: boolean }
-	): Promise<{ editorText?: string; cancelled: boolean }>; // In-place navigation
+		options?: { summarize?: boolean; customInstructions?: string }
+	): Promise<{ editorText?: string; cancelled: boolean; aborted?: boolean; summaryEntry?: BranchSummaryEntry }>;
 
-	// Hook message injection
-	sendHookMessage(message: HookMessage, triggerTurn?: boolean): Promise<void>;
+	// Custom message injection
+	sendCustomMessage<T>(
+		message: { customType: string; content: T; display?: boolean; details?: unknown },
+		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" }
+	): Promise<void>;
 
 	// Compaction
-	compact(customInstructions?: string): Promise<CompactionResult>;
+	compact(
+		customInstructions?: string,
+		options?: { onComplete?: (result: CompactionResult) => void; onError?: (error: Error) => void },
+	): Promise<CompactionResult>;
 	abortCompaction(): void;
 
+	// Utilities
+	getSessionStats(): SessionStats;
+	formatSessionAsText(): string;
+	formatCompactContext(): string;
+	exportToHtml(outputPath?: string): Promise<string>;
+	handoff(customInstructions?: string): Promise<{ document: string } | undefined>;
+
 	// Abort current operation
 	abort(): Promise<void>;
 
 	// Cleanup
-	dispose(): void;
+	dispose(): Promise<void>;
 }
 ```
 
@@ -200,11 +233,16 @@ session.subscribe((event) => {
 			// event.toolResults: tool results from this turn
 			break;
 
-		// Session events (auto-compaction, retry)
+		// Session events (auto-compaction, retry, TTSR, todo reminders)
 		case "auto_compaction_start":
 		case "auto_compaction_end":
 		case "auto_retry_start":
 		case "auto_retry_end":
+		case "ttsr_triggered":
+			// event.rules
+			break;
+		case "todo_reminder":
+			// event.todos
 			break;
 	}
 });
@@ -226,24 +264,17 @@ const { session } = await createAgentSession({
 
 `cwd` is used for:
 
-- Project hooks (`.omp/hooks/`)
-- Project tools (`.omp/tools/`)
-- Project skills (`.omp/skills/`)
-- Project commands (`.omp/commands/`)
+- Project config discovery (`.omp/`, `.pi/`, `.claude/`, `.codex/`, `.gemini/`)
+- Project extensions/tools/skills/commands (via config dirs)
 - Context files (`AGENTS.md` walking up from cwd)
-- Session directory naming
+- Session directory naming (via `SessionManager.create(cwd)`)
 
 `agentDir` is used for:
 
-- Global hooks (`hooks/`)
-- Global tools (`tools/`)
-- Global skills (`skills/`)
-- Global commands (`commands/`)
-- Global context file (`AGENTS.md`)
-- Settings (`settings.json`)
-- Custom models (`models.json`)
-- Credentials (`auth.json`)
-- Sessions (`sessions/`)
+- Global settings (`config.yml` + `agent.db`)
+- Primary auth/models locations (`auth.json`, `models.yml`, `models.json`)
+- Prompt templates (`prompts/`)
+- Custom TS commands (`commands/`)
 
 ### Model
 
@@ -252,18 +283,18 @@ import { getModel } from "@oh-my-pi/pi-ai";
 import { discoverAuthStorage, discoverModels } from "@oh-my-pi/pi-coding-agent";
 
 const authStorage = await discoverAuthStorage();
-const modelRegistry = await discoverModels(authStorage);
+const modelRegistry = discoverModels(authStorage);
 
 // Find specific built-in model (doesn't check if API key exists)
 const opus = getModel("anthropic", "claude-opus-4-5");
 if (!opus) throw new Error("Model not found");
 
-// Find any model by provider/id, including custom models from models.json
+// Find any model by provider/id, including custom models from models.yml
 // (doesn't check if API key exists)
 const customModel = modelRegistry.find("my-provider", "my-model");
 
-// Get only models that have valid API keys configured
-const available = await modelRegistry.getAvailable();
+// Get all models that have valid API keys configured
+const available = modelRegistry.getAvailable();
 
 const { session } = await createAgentSession({
 	model: opus,
@@ -293,16 +324,18 @@ If no model is provided:
 API key resolution priority (handled by AuthStorage):
 
 1. Runtime overrides (via `setRuntimeApiKey`, not persisted)
-2. Stored credentials in `auth.json` (API keys or OAuth tokens)
+2. Stored credentials in `agent.db` (API keys or OAuth tokens)
 3. Environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)
-4. Fallback resolver (for custom provider keys from `models.json`)
+4. Fallback resolver (for custom provider keys from `models.yml`)
+
+`discoverAuthStorage` also migrates legacy `auth.json` from user config directories (`.pi`, `.claude`, `.codex`, `.gemini`) into `agent.db`.
 
 ```typescript
 import { AuthStorage, ModelRegistry, discoverAuthStorage, discoverModels } from "@oh-my-pi/pi-coding-agent";
 
-// Default: uses ~/.omp/agent/auth.json and ~/.omp/agent/models.json
+// Default: uses agentDir/auth.json → agent.db and agentDir/models.yml (with legacy fallbacks)
 const authStorage = await discoverAuthStorage();
-const modelRegistry = await discoverModels(authStorage);
+const modelRegistry = discoverModels(authStorage);
 
 const { session } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
@@ -313,9 +346,9 @@ const { session } = await createAgentSession({
 // Runtime API key override (not persisted to disk)
 authStorage.setRuntimeApiKey("anthropic", "sk-my-temp-key");
 
-// Custom auth storage location
-const customAuth = new AuthStorage("/my/app/auth.json");
-const customRegistry = new ModelRegistry(customAuth, "/my/app/models.json");
+// Custom auth storage location (use create(), constructor is private)
+const customAuth = await AuthStorage.create("/my/app/auth.json");
+const customRegistry = new ModelRegistry(customAuth, "/my/app/models.yml");
 
 const { session } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
@@ -323,7 +356,7 @@ const { session } = await createAgentSession({
 	modelRegistry: customRegistry,
 });
 
-// No custom models.json (built-in models only)
+// No custom models.yml (built-in models only)
 const simpleRegistry = new ModelRegistry(authStorage);
 ```
 
@@ -332,10 +365,14 @@ const simpleRegistry = new ModelRegistry(authStorage);
 ### System Prompt
 
 ```typescript
+import systemPrompt from "./SYSTEM.md" with { type: "text" };
+
 const { session } = await createAgentSession({
-	// Replace entirely
-	systemPrompt: "You are a helpful assistant.",
+	// Replace entirely with a static prompt
+	systemPrompt,
+});
 
+const { session: modified } = await createAgentSession({
 	// Or modify default (receives default, returns modified)
 	systemPrompt: (defaultPrompt) => {
 		return `${defaultPrompt}\n\n## Additional Rules\n- Be concise`;
@@ -355,8 +392,10 @@ const { session } = await createAgentSession();
 
 // Filter to specific tools
 const { session } = await createAgentSession({
-	toolNames: ["read", "grep", "find", "ls"], // Read-only tools
+	toolNames: ["read", "grep", "find"], // Read-only tools
 });
+
+`toolNames` is an allowlist for built-ins; custom tools are always included even if not listed.
 ```
 
 #### Available Built-in Tools
@@ -365,32 +404,43 @@ All tools are defined in `BUILTIN_TOOLS`:
 
 - `ask` - Interactive user prompts (requires UI)
 - `bash` - Shell command execution
+- `python` - Python REPL execution
+- `calc` - Calculator
+- `ssh` - Remote SSH execution
 - `edit` - Surgical file editing
 - `find` - File search by glob patterns
-- `git` - Git operations (can be disabled via settings)
 - `grep` - Content search with regex
-- `ls` - Directory listing
 - `lsp` - Language server protocol integration
 - `notebook` - Jupyter notebook editing
-- `output` - Task output retrieval
 - `read` - File reading (text and images)
+- `browser` - Puppeteer-based web browser
 - `task` - Subagent spawning
+- `todo_write` - Todo file management
 - `fetch` - URL fetching
 - `web_search` - Web search
 - `write` - File writing
 
+Hidden tools (not in `BUILTIN_TOOLS`) are available but excluded unless requested:
+
+- `submit_result` - Required for subagent structured output (use `requireSubmitResultTool` or include in `toolNames`)
+- `report_finding` - Security review reporting
+- `exit_plan_mode` - Plan mode control
+
 #### Creating Tools Manually
 
 For advanced use cases, you can create tools directly using `createTools`:
 
 ```typescript
-import { BUILTIN_TOOLS, createTools, type ToolSession } from "@oh-my-pi/pi-coding-agent";
+import { createTools, Settings, type ToolSession } from "@oh-my-pi/pi-coding-agent";
+
+const settingsInstance = await Settings.init({ cwd: "/path/to/project" });
 
 const session: ToolSession = {
 	cwd: "/path/to/project",
 	hasUI: false,
 	getSessionFile: () => null,
 	getSessionSpawns: () => "*",
+	settings: settingsInstance,
 };
 
 const tools = await createTools(session);
@@ -398,20 +448,18 @@ const tools = await createTools(session);
 
 **When you don't need factories:**
 
-- If you omit `tools`, omp automatically creates them with the correct `cwd`
+- If you omit `toolNames`, omp automatically creates them with the correct `cwd`
 - If you use `process.cwd()` as your `cwd`, the pre-built instances work fine
 
 **When you must use factories:**
 
-- When you specify both `cwd` (different from `process.cwd()`) AND `tools`
-
-> See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
+- When you specify both `cwd` (different from `process.cwd()`) AND custom tools
 
 ### Custom Tools
 
 ```typescript
 import { Type } from "@sinclair/typebox";
-import { createAgentSession, discoverCustomTools, type CustomTool } from "@oh-my-pi/pi-coding-agent";
+import { createAgentSession, type CustomTool } from "@oh-my-pi/pi-coding-agent";
 
 // Inline custom tool
 const myTool: CustomTool = {
@@ -421,38 +469,36 @@ const myTool: CustomTool = {
 	parameters: Type.Object({
 		input: Type.String({ description: "Input value" }),
 	}),
-	execute: async (toolCallId, params) => ({
+	execute: async (toolCallId, params, onUpdate, ctx, signal) => ({
 		content: [{ type: "text", text: `Result: ${params.input}` }],
-		details: {},
 	}),
+	// Optional session lifecycle handler
+	onSession: async (event, ctx) => {
+		if (event.reason === "shutdown") {
+			// cleanup
+		}
+	},
 };
 
-// Replace discovery with inline tools
-const { session } = await createAgentSession({
-	customTools: [{ tool: myTool }],
-});
-
-// Merge with discovered tools
-const discovered = await discoverCustomTools();
-const { session } = await createAgentSession({
-	customTools: [...discovered, { tool: myTool }],
-});
-
-// Add paths without replacing discovery
+// Add custom tools (merged with built-in tools)
 const { session } = await createAgentSession({
-	additionalCustomToolPaths: ["/extra/tools"],
+	customTools: [myTool],
 });
 ```
 
-> See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
+### Extensions
 
-### Hooks
+Extensions intercept agent events and can register custom tools/commands. Hooks remain for legacy compatibility.
 
 ```typescript
-import { createAgentSession, discoverHooks, type HookFactory } from "@oh-my-pi/pi-coding-agent";
+import {
+	createAgentSession,
+	discoverExtensions,
+	type ExtensionFactory,
+} from "@oh-my-pi/pi-coding-agent";
 
-// Inline hook
-const loggingHook: HookFactory = (api) => {
+// Inline extension
+const loggingExtension: ExtensionFactory = (api) => {
 	// Log tool calls
 	api.on("tool_call", async (event) => {
 		console.log(`Tool: ${event.toolName}`);
@@ -470,58 +516,52 @@ const loggingHook: HookFactory = (api) => {
 	// Register custom slash command
 	api.registerCommand("stats", {
 		description: "Show session stats",
-		handler: async (ctx) => {
+		handler: async (args, 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 });
 };
 
+// Merge with discovery (default behavior)
+const { session } = await createAgentSession({
+	extensions: [loggingExtension],
+});
+
 // Replace discovery
 const { session } = await createAgentSession({
-	hooks: [{ factory: loggingHook }],
+	extensions: [loggingExtension],
+	disableExtensionDiscovery: true,
 });
 
-// Disable all hooks
+// Disable all extensions
 const { session } = await createAgentSession({
-	hooks: [],
+	extensions: [],
+	disableExtensionDiscovery: true,
 });
 
-// Merge with discovered
-const discovered = await discoverHooks();
+// Use preloaded extensions (skip discovery I/O)
+const discovered = await discoverExtensions();
 const { session } = await createAgentSession({
-	hooks: [...discovered, { factory: loggingHook }],
+	preloadedExtensions: discovered,
+	extensions: [loggingExtension],
 });
 
-// Add paths without replacing
+// Add paths without replacing discovery
 const { session } = await createAgentSession({
-	additionalHookPaths: ["/extra/hooks"],
+	additionalExtensionPaths: ["/extra/extensions"],
 });
 ```
 
-Hook API methods:
+Extension 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.registerTool(definition)` - Register a custom tool
 - `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)
+> See [examples/sdk/06-extensions.ts](../examples/sdk/06-extensions.ts) and [docs/extensions.md](extensions.md)
 
 ### Skills
 
@@ -529,7 +569,7 @@ Hook API methods:
 import { createAgentSession, discoverSkills, type Skill } from "@oh-my-pi/pi-coding-agent";
 
 // Discover and filter
-const { skills: allSkills, warnings } = discoverSkills();
+const { skills: allSkills, warnings } = await discoverSkills();
 const filtered = allSkills.filter((s) => s.name.includes("search"));
 
 // Custom skill
@@ -549,12 +589,6 @@ const { session } = await createAgentSession({
 const { session } = await createAgentSession({
 	skills: [],
 });
-
-// Discovery with settings filter
-const { skills } = discoverSkills(process.cwd(), undefined, {
-	ignoredSkills: ["browser-*"], // glob patterns to exclude
-	includeSkills: ["search-*"], // glob patterns to include (empty = all)
-});
 ```
 
 > See [examples/sdk/04-skills.ts](../examples/sdk/04-skills.ts)
@@ -565,7 +599,7 @@ const { skills } = discoverSkills(process.cwd(), undefined, {
 import { createAgentSession, discoverContextFiles } from "@oh-my-pi/pi-coding-agent";
 
 // Discover AGENTS.md files
-const discovered = discoverContextFiles();
+const discovered = await discoverContextFiles();
 
 // Add custom context
 const { session } = await createAgentSession({
@@ -591,7 +625,7 @@ const { session } = await createAgentSession({
 ```typescript
 import { createAgentSession, discoverSlashCommands, type FileSlashCommand } from "@oh-my-pi/pi-coding-agent";
 
-const discovered = discoverSlashCommands();
+const discovered = await discoverSlashCommands();
 
 const customCommand: FileSlashCommand = {
 	name: "deploy",
@@ -624,21 +658,21 @@ const { session } = await createAgentSession({
 	sessionManager: SessionManager.create(process.cwd()),
 });
 
-// Continue most recent
+// Continue most recent (async)
 const { session, modelFallbackMessage } = await createAgentSession({
-	sessionManager: SessionManager.continueRecent(process.cwd()),
+	sessionManager: await SessionManager.continueRecent(process.cwd()),
 });
 if (modelFallbackMessage) {
 	console.log("Note:", modelFallbackMessage);
 }
 
-// Open specific file
+// Open specific file (async)
 const { session } = await createAgentSession({
-	sessionManager: SessionManager.open("/path/to/session.jsonl"),
+	sessionManager: await SessionManager.open("/path/to/session.jsonl"),
 });
 
-// List available sessions
-const sessions = SessionManager.list(process.cwd());
+// List available sessions (async)
+const sessions = await SessionManager.list(process.cwd());
 for (const info of sessions) {
 	console.log(`${info.id}: ${info.firstMessage} (${info.messageCount} messages)`);
 }
@@ -650,15 +684,25 @@ const { session } = await createAgentSession({
 });
 ```
 
+**SessionManager static factories:**
+
+- `SessionManager.create(cwd, sessionDir?)` - New persistent session (sync)
+- `SessionManager.inMemory(cwd?)` - In-memory session (sync)
+- `SessionManager.open(filePath, sessionDir?)` - Open existing file (async)
+- `SessionManager.continueRecent(cwd, sessionDir?)` - Most recent session (async)
+- `SessionManager.list(cwd, sessionDir?)` - List sessions (async)
+- `SessionManager.listAll()` - List all sessions across cwds (async)
+- `SessionManager.forkFrom(sourcePath, cwd, sessionDir?)` - Fork from existing (async)
+
 **SessionManager tree API:**
 
 ```typescript
-const sm = SessionManager.open("/path/to/session.jsonl");
+const sm = await 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 branch = sm.getBranch(); // 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
@@ -678,100 +722,112 @@ sm.createBranchedSession(leafId); // Extract path to new file
 ### Settings Management
 
 ```typescript
-import { createAgentSession, SettingsManager, SessionManager } from "@oh-my-pi/pi-coding-agent";
+import { createAgentSession, Settings, SessionManager } from "@oh-my-pi/pi-coding-agent";
+
+// Default: loads from files (global config.yml + project settings.json merged)
+const settingsInstance = await Settings.init();
 
-// Default: loads from files (global + project merged)
 const { session } = await createAgentSession({
-	settingsManager: await SettingsManager.create(),
+	settingsInstance,
 });
 
-// With overrides
-const settingsManager = await SettingsManager.create();
-settingsManager.applyOverrides({
-	compaction: { enabled: false },
-	retry: { enabled: true, maxRetries: 5 },
-});
-const { session } = await createAgentSession({ settingsManager });
+// Read/write settings
+const enabled = settingsInstance.get("compaction.enabled");
+settingsInstance.set("compaction.enabled", false);
 
 // In-memory (no file I/O, for testing)
+const isolated = Settings.isolated({
+	"compaction.enabled": false,
+	"retry.enabled": true,
+});
+
 const { session } = await createAgentSession({
-	settingsManager: SettingsManager.inMemory({ compaction: { enabled: false } }),
+	settingsInstance: isolated,
 	sessionManager: SessionManager.inMemory(),
 });
 
 // Custom directories
 const { session } = await createAgentSession({
-	settingsManager: await SettingsManager.create("/custom/cwd", "/custom/agent"),
+	cwd: "/custom/cwd",
+	agentDir: "/custom/agent",
 });
 ```
 
-**Static factories:**
+**Settings static factories:**
 
-- `SettingsManager.create(cwd?, agentDir?)` - Load from files (async)
-- `SettingsManager.inMemory(settings?)` - No file I/O
+- `Settings.init(options?)` - Load from files (async)
+- `Settings.isolated(overrides?)` - In-memory, no file I/O (sync)
+- `Settings.instance` - Global singleton (throws if not initialized)
 
-**Project-specific settings:**
+**Settings file locations:**
 
 Settings load from two locations and merge:
 
-1. Global: `~/.omp/agent/settings.json`
-2. Project: `<cwd>/.omp/settings.json`
+1. Global: `<agentDir>/config.yml` (default `~/.omp/agent/config.yml`)
+2. Project: `settings.json` from the first matching config dir (`.omp/`, `.pi/`, `.claude/`, `.codex/`, `.gemini/`)
 
-Project overrides global. Nested objects merge keys. Setters only modify global (project is read-only for version control).
-
-> See [examples/sdk/10-settings.ts](../examples/sdk/10-settings.ts)
+Project overrides global. Nested objects merge keys.
 
 ## Discovery Functions
 
-All discovery functions accept optional `cwd` and `agentDir` parameters.
+Discovery functions accept optional `cwd` and `agentDir` parameters where applicable.
 
 ```typescript
 import { getModel } from "@oh-my-pi/pi-ai";
+import appendPrompt from "./APPEND_SYSTEM.md" with { type: "text" };
 import {
 	AuthStorage,
 	ModelRegistry,
 	discoverAuthStorage,
 	discoverModels,
 	discoverSkills,
-	discoverHooks,
-	discoverCustomTools,
+	discoverExtensions,
 	discoverContextFiles,
 	discoverSlashCommands,
-	loadSettings,
+	discoverPromptTemplates,
+	discoverCustomTSCommands,
+	discoverMCPServers,
 	buildSystemPrompt,
+	Settings,
 } from "@oh-my-pi/pi-coding-agent";
 
 // Auth and Models
-const authStorage = await discoverAuthStorage(); // ~/.omp/agent/agent.db
-const modelRegistry = await discoverModels(authStorage); // + ~/.omp/agent/models.json
+const authStorage = await discoverAuthStorage(); // <agentDir>/auth.json → agent.db (with fallbacks)
+const modelRegistry = discoverModels(authStorage); // + <agentDir>/models.yml (or models.json)
 const allModels = modelRegistry.getAll(); // All models (built-in + custom)
-const available = await modelRegistry.getAvailable(); // Only models with API keys
+const available = modelRegistry.getAvailable(); // Only models with API keys
 const model = modelRegistry.find("provider", "id"); // Find specific model
 const builtIn = getModel("anthropic", "claude-opus-4-5"); // Built-in only
 
-// Skills
-const { skills, warnings } = discoverSkills(cwd, agentDir, skillsSettings);
+// Skills (async)
+const { skills, warnings } = await discoverSkills(cwd, agentDir, skillsSettings);
+
+// Extensions (async - loads TypeScript)
+const extensionsResult = await discoverExtensions(cwd);
 
-// Hooks (async - loads TypeScript)
-const hooks = await discoverHooks(cwd, agentDir);
+// Custom TS commands (async - loads TypeScript)
+const customCommands = await discoverCustomTSCommands(cwd, agentDir);
 
-// Custom tools (async - loads TypeScript)
-const tools = await discoverCustomTools(cwd, agentDir);
+// Context files (async)
+const contextFiles = await discoverContextFiles(cwd, agentDir);
 
-// Context files
-const contextFiles = discoverContextFiles(cwd, agentDir);
+// Slash commands (async)
+const commands = await discoverSlashCommands(cwd);
 
-// Slash commands
-const commands = discoverSlashCommands(cwd, agentDir);
+// Prompt templates (async)
+const promptTemplates = await discoverPromptTemplates(cwd, agentDir);
 
-// Settings (global + project merged)
-const settings = await loadSettings(cwd, agentDir);
+// MCP servers (async)
+const mcp = await discoverMCPServers(cwd);
+
+// Settings (async - global + project merged)
+const settings = await Settings.init({ cwd, agentDir });
 
 // Build system prompt manually
-const prompt = buildSystemPrompt({
+const prompt = await buildSystemPrompt({
 	skills,
 	contextFiles,
-	appendPrompt: "Additional instructions",
+	appendPrompt,
 	cwd,
 });
 ```
@@ -785,14 +841,20 @@ interface CreateAgentSessionResult {
 	// The session
 	session: AgentSession;
 
-	// Custom tools (for UI setup)
-	customToolsResult: {
-		tools: LoadedCustomTool[];
-		setUIContext: (ctx, hasUI) => void;
-	};
+	// Extensions result (loaded extensions + runtime)
+	extensionsResult: LoadExtensionsResult;
+
+	// Update tool UI context (interactive mode)
+	setToolUIContext: (uiContext: ExtensionUIContext, hasUI: boolean) => void;
+
+	// MCP manager for server lifecycle management (undefined if MCP disabled)
+	mcpManager?: MCPManager;
 
 	// Warning if session model couldn't be restored
 	modelFallbackMessage?: string;
+
+	// LSP servers that were warmed up at startup
+	lspServers?: Array<{ name: string; status: "ready" | "error"; fileTypes: string[]; error?: string }>;
 }
 ```
 
@@ -802,30 +864,29 @@ interface CreateAgentSessionResult {
 import { getModel } from "@oh-my-pi/pi-ai";
 import { Type } from "@sinclair/typebox";
 import {
-	AuthStorage,
 	createAgentSession,
-	ModelRegistry,
+	discoverAuthStorage,
+	discoverModels,
 	SessionManager,
-	SettingsManager,
-	readTool,
-	bashTool,
-	type HookFactory,
+	Settings,
+	type ExtensionFactory,
 	type CustomTool,
 } from "@oh-my-pi/pi-coding-agent";
+import systemPrompt from "./SYSTEM.md" with { type: "text" };
 
-// Set up auth storage (custom location)
-const authStorage = new AuthStorage("/custom/agent/auth.json");
+// Set up auth storage
+const authStorage = await discoverAuthStorage();
 
 // Runtime API key override (not persisted)
 if (process.env.MY_KEY) {
 	authStorage.setRuntimeApiKey("anthropic", process.env.MY_KEY);
 }
 
-// Model registry (no custom models.json)
-const modelRegistry = new ModelRegistry(authStorage);
+// Model registry
+const modelRegistry = discoverModels(authStorage);
 
-// Inline hook
-const auditHook: HookFactory = (api) => {
+// Inline extension
+const auditExtension: ExtensionFactory = (api) => {
 	api.on("tool_call", async (event) => {
 		console.log(`[Audit] ${event.toolName}`);
 		return undefined;
@@ -838,9 +899,8 @@ const statusTool: CustomTool = {
 	label: "Status",
 	description: "Get system status",
 	parameters: Type.Object({}),
-	execute: async () => ({
+	execute: async (toolCallId, params, onUpdate, ctx, signal) => ({
 		content: [{ type: "text", text: `Uptime: ${process.uptime()}s` }],
-		details: {},
 	}),
 };
 
@@ -848,9 +908,9 @@ const model = getModel("anthropic", "claude-opus-4-5");
 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 settingsInstance = Settings.isolated({
+	"compaction.enabled": false,
+	"retry.enabled": true,
 });
 
 const { session } = await createAgentSession({
@@ -862,17 +922,17 @@ const { session } = await createAgentSession({
 	authStorage,
 	modelRegistry,
 
-	systemPrompt: "You are a minimal assistant. Be concise.",
+	systemPrompt,
 
-	tools: [readTool, bashTool],
-	customTools: [{ tool: statusTool }],
-	hooks: [{ factory: auditHook }],
+	toolNames: ["read", "bash"],
+	customTools: [statusTool],
+	extensions: [auditExtension],
 	skills: [],
 	contextFiles: [],
 	slashCommands: [],
 
 	sessionManager: SessionManager.inMemory(),
-	settingsManager,
+	settingsInstance,
 });
 
 session.subscribe((event) => {
@@ -899,7 +959,7 @@ The SDK is preferred when:
 - You want type safety
 - You're in the same Node.js process
 - You need direct access to agent state
-- You want to customize tools/hooks programmatically
+- You want to customize tools/extensions programmatically
 
 RPC mode is preferred when:
 
@@ -923,62 +983,61 @@ discoverModels
 
 // Discovery
 discoverSkills
-discoverHooks
-discoverCustomTools
+discoverExtensions
+discoverCustomTSCommands
 discoverContextFiles
 discoverSlashCommands
+discoverPromptTemplates
+discoverMCPServers
 
 // Helpers
-loadSettings
 buildSystemPrompt
+Settings
 
 // Session management
 SessionManager
-SettingsManager
 
 // Tool registry and factory
 BUILTIN_TOOLS              // Map of tool name to factory
 createTools                // Create all tools from ToolSession
 type ToolSession           // Session context for tool creation
 
-// Individual tool factories
-createReadTool, createBashTool, EditTool, createWriteTool
-createGrepTool, createFindTool, createLsTool, createGitTool
+// Individual tool classes
+ReadTool, BashTool, EditTool, WriteTool
+GrepTool, FindTool, PythonTool
+loadSshTool
 
 // Types
 type CreateAgentSessionOptions
 type CreateAgentSessionResult
 type CustomTool
-type HookFactory
+type ExtensionFactory
 type Skill
 type FileSlashCommand
-type Settings
 type SkillsSettings
 type Tool
 ```
 
-For hook types, import from the hooks subpath:
+For extension types, import from the main package:
 
 ```typescript
 import type {
-	HookAPI,
-	HookMessage,
-	HookFactory,
-	HookEventContext,
-	HookCommandContext,
-	ToolCallEvent,
-	ToolResultEvent,
-} from "@oh-my-pi/pi-coding-agent/hooks";
+	ExtensionAPI,
+	ExtensionFactory,
+	ExtensionContext,
+	ExtensionCommandContext,
+	ToolDefinition,
+} from "@oh-my-pi/pi-coding-agent";
 ```
 
-For message utilities:
+For legacy hook types (deprecated, use extensions instead):
 
 ```typescript
-import { isHookMessage, createHookMessage } from "@oh-my-pi/pi-coding-agent";
+import type { HookAPI, HookFactory, HookContext, HookCommandContext } from "@oh-my-pi/pi-coding-agent/hooks";
 ```
 
 For config utilities:
 
 ```typescript
-import { getAgentDir } from "@oh-my-pi/pi-coding-agent/config";
+import { getAgentDir } from "@oh-my-pi/pi-coding-agent";
 ```