@oh-my-pi/pi-coding-agent 12.7.6 → 12.8.0

package/docs/sdk.md

@@ -1,1039 +0,0 @@
-> omp can help you use the SDK. Ask it to build an integration for your use case.
-
-# SDK
-
-The SDK provides programmatic access to omp's agent capabilities. Use it to embed omp in other applications, build custom interfaces, or integrate with automated workflows.
-
-**Example use cases:**
-
-- Build a custom UI (web, desktop, mobile)
-- Integrate agent capabilities into existing applications
-- Create automated pipelines with agent reasoning
-- Build custom tools that spawn sub-agents
-- Test agent behavior programmatically
-
-See [examples/sdk/](../examples/sdk/) for working examples from minimal to full control.
-
-## Quick Start
-
-```typescript
-import { createAgentSession, discoverAuthStorage, discoverModels, SessionManager } from "@oh-my-pi/pi-coding-agent";
-
-// Set up credential storage and model registry
-const authStorage = await discoverAuthStorage();
-const modelRegistry = discoverModels(authStorage);
-
-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);
-	}
-});
-
-await session.prompt("What files are in the current directory?");
-```
-
-## Installation
-
-```bash
-bun add @oh-my-pi/pi-coding-agent
-```
-
-The SDK is included in the main package. No separate installation needed.
-
-## Core Concepts
-
-### createAgentSession()
-
-The main factory function. Creates an `AgentSession` with configurable options.
-
-**Philosophy:** "Omit to discover, provide to override."
-
-- Omit an option → omp discovers/loads from standard locations
-- Provide an option → your value is used, discovery skipped for that option
-
-```typescript
-import { createAgentSession } from "@oh-my-pi/pi-coding-agent";
-import systemPrompt from "./SYSTEM.md" with { type: "text" };
-
-// 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,
-	toolNames: ["read", "bash", "edit"], // Filter to specific tools
-	sessionManager: SessionManager.inMemory(),
-});
-```
-
-### AgentSession
-
-The session manages the agent lifecycle, message history, and event streaming.
-
-```typescript
-interface AgentSession {
-	// 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;
-
-	// Session info
-	sessionFile: string | undefined; // undefined for in-memory
-	sessionId: string;
-	sessionName: string | undefined;
-
-	// Model control
-	setModel(model: Model, role?: ModelRole): Promise<void>;
-	setModelTemporary(model: Model): Promise<void>;
-	setThinkingLevel(level: ThinkingLevel): void;
-	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?: 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 }>;
-	navigateTree(
-		targetId: string,
-		options?: { summarize?: boolean; customInstructions?: string }
-	): Promise<{ editorText?: string; cancelled: boolean; aborted?: boolean; summaryEntry?: BranchSummaryEntry }>;
-
-	// 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,
-		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(): Promise<void>;
-}
-```
-
-### Agent and AgentState
-
-The `Agent` class (from `@oh-my-pi/pi-agent-core`) handles the core LLM interaction. Access it via `session.agent`.
-
-```typescript
-// Access current state
-const state = session.agent.state;
-
-// state.messages: AgentMessage[] - conversation history
-// state.model: Model - current model
-// state.thinkingLevel: ThinkingLevel - current thinking level
-// state.systemPrompt: string - system prompt
-// state.tools: Tool[] - available tools
-
-// Replace messages (useful for branching, restoration)
-session.agent.replaceMessages(messages);
-
-// Wait for agent to finish processing
-await session.agent.waitForIdle();
-```
-
-### Events
-
-Subscribe to events to receive streaming output and lifecycle notifications.
-
-```typescript
-session.subscribe((event) => {
-	switch (event.type) {
-		// Streaming text from assistant
-		case "message_update":
-			if (event.assistantMessageEvent.type === "text_delta") {
-				process.stdout.write(event.assistantMessageEvent.delta);
-			}
-			if (event.assistantMessageEvent.type === "thinking_delta") {
-				// Thinking output (if thinking enabled)
-			}
-			break;
-
-		// Tool execution
-		case "tool_execution_start":
-			console.log(`Tool: ${event.toolName}`);
-			break;
-		case "tool_execution_update":
-			// Streaming tool output
-			break;
-		case "tool_execution_end":
-			console.log(`Result: ${event.isError ? "error" : "success"}`);
-			break;
-
-		// Message lifecycle
-		case "message_start":
-			// New message starting
-			break;
-		case "message_end":
-			// Message complete
-			break;
-
-		// Agent lifecycle
-		case "agent_start":
-			// Agent started processing prompt
-			break;
-		case "agent_end":
-			// Agent finished (event.messages contains new messages)
-			break;
-
-		// Turn lifecycle (one LLM response + tool calls)
-		case "turn_start":
-			break;
-		case "turn_end":
-			// event.message: assistant response
-			// event.toolResults: tool results from this turn
-			break;
-
-		// 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;
-	}
-});
-```
-
-## Options Reference
-
-### Directories
-
-```typescript
-const { session } = await createAgentSession({
-	// Working directory for project-local discovery
-	cwd: process.cwd(), // default
-
-	// Global config directory
-	agentDir: "~/.omp/agent", // default (expands ~)
-});
-```
-
-`cwd` is used for:
-
-- 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 (via `SessionManager.create(cwd)`)
-
-`agentDir` is used for:
-
-- Global settings (`config.yml` + `agent.db`)
-- Primary auth/models locations (`agent.db`, `models.yml`, `models.json`)
-- Prompt templates (`prompts/`)
-- Custom TS commands (`commands/`)
-
-### Model
-
-```typescript
-import { getModel } from "@oh-my-pi/pi-ai";
-import { discoverAuthStorage, discoverModels } from "@oh-my-pi/pi-coding-agent";
-
-const authStorage = await discoverAuthStorage();
-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.yml
-// (doesn't check if API key exists)
-const customModel = modelRegistry.find("my-provider", "my-model");
-
-// Get all models that have valid API keys configured
-const available = modelRegistry.getAvailable();
-
-const { session } = await createAgentSession({
-	model: opus,
-	thinkingLevel: "medium", // off, minimal, low, medium, high, xhigh
-
-	// Models for cycling (Ctrl+P in interactive mode)
-	scopedModels: [
-		{ model: opus, thinkingLevel: "high" },
-		{ model: haiku, thinkingLevel: "off" },
-	],
-
-	authStorage,
-	modelRegistry,
-});
-```
-
-If no model is provided:
-
-1. Tries to restore from session (if continuing)
-2. Uses default from settings
-3. Falls back to first available model
-
-> See [examples/sdk/02-custom-model.ts](../examples/sdk/02-custom-model.ts)
-
-### API Keys and OAuth
-
-API key resolution priority (handled by AuthStorage):
-
-1. Runtime overrides (via `setRuntimeApiKey`, not persisted)
-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.yml`)
-
-`discoverAuthStorage` opens the `agent.db` SQLite database in the agent directory.
-
-```typescript
-import { AuthStorage, ModelRegistry, discoverAuthStorage, discoverModels } from "@oh-my-pi/pi-coding-agent";
-
-// Default: uses agentDir/agent.db and agentDir/models.yml
-const authStorage = await discoverAuthStorage();
-const modelRegistry = discoverModels(authStorage);
-
-const { session } = await createAgentSession({
-	sessionManager: SessionManager.inMemory(),
-	authStorage,
-	modelRegistry,
-});
-
-// Runtime API key override (not persisted to disk)
-authStorage.setRuntimeApiKey("anthropic", "sk-my-temp-key");
-
-// Custom auth storage location (use create(), constructor is private)
-const customAuth = await AuthStorage.create("/my/app/agent.db");
-const customRegistry = new ModelRegistry(customAuth, "/my/app/models.yml");
-
-const { session } = await createAgentSession({
-	sessionManager: SessionManager.inMemory(),
-	authStorage: customAuth,
-	modelRegistry: customRegistry,
-});
-
-// No custom models.yml (built-in models only)
-const simpleRegistry = new ModelRegistry(authStorage);
-```
-
-> See [examples/sdk/09-api-keys-and-oauth.ts](../examples/sdk/09-api-keys-and-oauth.ts)
-
-### System Prompt
-
-```typescript
-import systemPrompt from "./SYSTEM.md" with { type: "text" };
-
-const { session } = await createAgentSession({
-	// 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`;
-	},
-});
-```
-
-> See [examples/sdk/03-custom-prompt.ts](../examples/sdk/03-custom-prompt.ts)
-
-### Tools
-
-By default, `createAgentSession` creates all built-in tools automatically. You can filter which tools are available using `toolNames`:
-
-```typescript
-// Use all built-in tools (default)
-const { session } = await createAgentSession();
-
-// Filter to specific tools
-const { session } = await createAgentSession({
-	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
-
-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
-- `grep` - Content search with regex
-- `lsp` - Language server protocol integration
-- `notebook` - Jupyter notebook editing
-- `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 { createTools, Settings, type ToolSession } from "@oh-my-pi/pi-coding-agent";
-
-const settings = await Settings.init({ cwd: "/path/to/project" });
-
-const session: ToolSession = {
-	cwd: "/path/to/project",
-	hasUI: false,
-	getSessionFile: () => null,
-	getSessionSpawns: () => "*",
-	settings,
-};
-
-const tools = await createTools(session);
-```
-
-**When you don't need factories:**
-
-- 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 custom tools
-
-### Custom Tools
-
-```typescript
-import { Type } from "@sinclair/typebox";
-import { createAgentSession, type CustomTool } from "@oh-my-pi/pi-coding-agent";
-
-// Inline custom tool
-const myTool: CustomTool = {
-	name: "my_tool",
-	label: "My Tool",
-	description: "Does something useful",
-	parameters: Type.Object({
-		input: Type.String({ description: "Input value" }),
-	}),
-	execute: async (toolCallId, params, onUpdate, ctx, signal) => ({
-		content: [{ type: "text", text: `Result: ${params.input}` }],
-	}),
-	// Optional session lifecycle handler
-	onSession: async (event, ctx) => {
-		if (event.reason === "shutdown") {
-			// cleanup
-		}
-	},
-};
-
-// Add custom tools (merged with built-in tools)
-const { session } = await createAgentSession({
-	customTools: [myTool],
-});
-```
-
-### Extensions
-
-Extensions intercept agent events and can register custom tools/commands. Hooks remain for legacy compatibility.
-
-```typescript
-import { createAgentSession, discoverExtensions, type ExtensionFactory } from "@oh-my-pi/pi-coding-agent";
-
-// Inline extension
-const loggingExtension: ExtensionFactory = (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) => {
-		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 (args, ctx) => {
-			const entries = ctx.sessionManager.getEntries();
-			ctx.ui.notify(`${entries.length} entries`, "info");
-		},
-	});
-};
-
-// Merge with discovery (default behavior)
-const { session } = await createAgentSession({
-	extensions: [loggingExtension],
-});
-
-// Replace discovery
-const { session } = await createAgentSession({
-	extensions: [loggingExtension],
-	disableExtensionDiscovery: true,
-});
-
-// Disable all extensions
-const { session } = await createAgentSession({
-	extensions: [],
-	disableExtensionDiscovery: true,
-});
-
-// Use preloaded extensions (skip discovery I/O)
-const discovered = await discoverExtensions();
-const { session } = await createAgentSession({
-	preloadedExtensions: discovered,
-	extensions: [loggingExtension],
-});
-
-// Add paths without replacing discovery
-const { session } = await createAgentSession({
-	additionalExtensionPaths: ["/extra/extensions"],
-});
-```
-
-Extension API methods:
-
-- `api.on(event, handler)` - Subscribe to events
-- `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-extensions.ts](../examples/sdk/06-extensions.ts) and [docs/extensions.md](extensions.md)
-
-### Skills
-
-```typescript
-import { createAgentSession, discoverSkills, type Skill } from "@oh-my-pi/pi-coding-agent";
-
-// Discover and filter
-const { skills: allSkills, warnings } = await discoverSkills();
-const filtered = allSkills.filter((s) => s.name.includes("search"));
-
-// Custom skill
-const mySkill: Skill = {
-	name: "my-skill",
-	description: "Custom instructions",
-	filePath: "/path/to/SKILL.md",
-	baseDir: "/path/to",
-	source: "custom",
-};
-
-const { session } = await createAgentSession({
-	skills: [...filtered, mySkill],
-});
-
-// Disable skills
-const { session } = await createAgentSession({
-	skills: [],
-});
-```
-
-> See [examples/sdk/04-skills.ts](../examples/sdk/04-skills.ts)
-
-### Context Files
-
-```typescript
-import { createAgentSession, discoverContextFiles } from "@oh-my-pi/pi-coding-agent";
-
-// Discover AGENTS.md files
-const discovered = await discoverContextFiles();
-
-// Add custom context
-const { session } = await createAgentSession({
-	contextFiles: [
-		...discovered,
-		{
-			path: "/virtual/AGENTS.md",
-			content: "# Guidelines\n\n- Be concise\n- Use TypeScript",
-		},
-	],
-});
-
-// Disable context files
-const { session } = await createAgentSession({
-	contextFiles: [],
-});
-```
-
-> See [examples/sdk/07-context-files.ts](../examples/sdk/07-context-files.ts)
-
-### Slash Commands
-
-```typescript
-import { createAgentSession, discoverSlashCommands, type FileSlashCommand } from "@oh-my-pi/pi-coding-agent";
-
-const discovered = await discoverSlashCommands();
-
-const customCommand: FileSlashCommand = {
-	name: "deploy",
-	description: "Deploy the application",
-	source: "(custom)",
-	content: "# Deploy\n\n1. Build\n2. Test\n3. Deploy",
-};
-
-const { session } = await createAgentSession({
-	slashCommands: [...discovered, customCommand],
-});
-```
-
-> See [examples/sdk/08-slash-commands.ts](../examples/sdk/08-slash-commands.ts)
-
-### Session Management
-
-Sessions use a tree structure with `id`/`parentId` linking, enabling in-place branching.
-
-```typescript
-import { createAgentSession, SessionManager } from "@oh-my-pi/pi-coding-agent";
-
-// In-memory (no persistence)
-const { session } = await createAgentSession({
-	sessionManager: SessionManager.inMemory(),
-});
-
-// New persistent session
-const { session } = await createAgentSession({
-	sessionManager: SessionManager.create(process.cwd()),
-});
-
-// Continue most recent (async)
-const { session, modelFallbackMessage } = await createAgentSession({
-	sessionManager: await SessionManager.continueRecent(process.cwd()),
-});
-if (modelFallbackMessage) {
-	console.log("Note:", modelFallbackMessage);
-}
-
-// Open specific file (async)
-const { session } = await createAgentSession({
-	sessionManager: await SessionManager.open("/path/to/session.jsonl"),
-});
-
-// 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)`);
-}
-
-// Custom session directory (no cwd encoding)
-const customDir = "/path/to/my-sessions";
-const { session } = await createAgentSession({
-	sessionManager: SessionManager.create(process.cwd(), customDir),
-});
-```
-
-**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 = 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 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
-
-// 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
-
-```typescript
-import { createAgentSession, Settings, SessionManager } from "@oh-my-pi/pi-coding-agent";
-
-// Default: loads from files (global config.yml + project settings.json merged)
-const settings = await Settings.init();
-
-const { session } = await createAgentSession({
-	settings,
-});
-
-// Read/write settings
-const enabled = settings.get("compaction.enabled");
-settings.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({
-	settings: isolated,
-	sessionManager: SessionManager.inMemory(),
-});
-
-// Custom directories
-const { session } = await createAgentSession({
-	cwd: "/custom/cwd",
-	agentDir: "/custom/agent",
-});
-```
-
-**Settings static factories:**
-
-- `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)
-
-**Settings file locations:**
-
-Settings load from two locations and merge:
-
-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.
-
-## Discovery Functions
-
-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,
-	discoverExtensions,
-	discoverContextFiles,
-	discoverSlashCommands,
-	discoverPromptTemplates,
-	discoverCustomTSCommands,
-	discoverMCPServers,
-	buildSystemPrompt,
-	Settings,
-} from "@oh-my-pi/pi-coding-agent";
-
-// Auth and Models
-const authStorage = await discoverAuthStorage(); // <agentDir>/agent.db
-const modelRegistry = discoverModels(authStorage); // + <agentDir>/models.yml (or models.json)
-const allModels = modelRegistry.getAll(); // All models (built-in + custom)
-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 (async)
-const { skills, warnings } = await discoverSkills(cwd, agentDir, skillsSettings);
-
-// Extensions (async - loads TypeScript)
-const extensionsResult = await discoverExtensions(cwd);
-
-// Custom TS commands (async - loads TypeScript)
-const customCommands = await discoverCustomTSCommands(cwd, agentDir);
-
-// Context files (async)
-const contextFiles = await discoverContextFiles(cwd, agentDir);
-
-// Slash commands (async)
-const commands = await discoverSlashCommands(cwd);
-
-// Prompt templates (async)
-const promptTemplates = await discoverPromptTemplates(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 = await buildSystemPrompt({
-	skills,
-	contextFiles,
-	appendPrompt,
-	cwd,
-});
-```
-
-## Return Value
-
-`createAgentSession()` returns:
-
-```typescript
-interface CreateAgentSessionResult {
-	// The session
-	session: AgentSession;
-
-	// 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 }>;
-}
-```
-
-## Complete Example
-
-```typescript
-import { getModel } from "@oh-my-pi/pi-ai";
-import { Type } from "@sinclair/typebox";
-import {
-	createAgentSession,
-	discoverAuthStorage,
-	discoverModels,
-	SessionManager,
-	Settings,
-	type ExtensionFactory,
-	type CustomTool,
-} from "@oh-my-pi/pi-coding-agent";
-import systemPrompt from "./SYSTEM.md" with { type: "text" };
-
-// Set up auth storage
-const authStorage = await discoverAuthStorage();
-
-// Runtime API key override (not persisted)
-if (Bun.env.MY_KEY) {
-	authStorage.setRuntimeApiKey("anthropic", Bun.env.MY_KEY);
-}
-
-// Model registry
-const modelRegistry = discoverModels(authStorage);
-
-// Inline extension
-const auditExtension: ExtensionFactory = (api) => {
-	api.on("tool_call", async (event) => {
-		console.log(`[Audit] ${event.toolName}`);
-		return undefined;
-	});
-};
-
-// Inline tool
-const statusTool: CustomTool = {
-	name: "status",
-	label: "Status",
-	description: "Get system status",
-	parameters: Type.Object({}),
-	execute: async (toolCallId, params, onUpdate, ctx, signal) => ({
-		content: [{ type: "text", text: `Uptime: ${process.uptime()}s` }],
-	}),
-};
-
-const model = getModel("anthropic", "claude-opus-4-5");
-if (!model) throw new Error("Model not found");
-
-// In-memory settings with overrides
-const settings = Settings.isolated({
-	"compaction.enabled": false,
-	"retry.enabled": true,
-});
-
-const { session } = await createAgentSession({
-	cwd: process.cwd(),
-	agentDir: "/custom/agent",
-
-	model,
-	thinkingLevel: "off",
-	authStorage,
-	modelRegistry,
-
-	systemPrompt,
-
-	toolNames: ["read", "bash"],
-	customTools: [statusTool],
-	extensions: [auditExtension],
-	skills: [],
-	contextFiles: [],
-	slashCommands: [],
-
-	sessionManager: SessionManager.inMemory(),
-	settings,
-});
-
-session.subscribe((event) => {
-	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
-		process.stdout.write(event.assistantMessageEvent.delta);
-	}
-});
-
-await session.prompt("Get status and list files.");
-```
-
-## RPC Mode Alternative
-
-For subprocess-based integration, use RPC mode instead of the SDK:
-
-```bash
-omp --mode rpc --no-session
-```
-
-See [RPC documentation](rpc.md) for the JSON protocol.
-
-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/extensions programmatically
-
-RPC mode is preferred when:
-
-- You're integrating from another language
-- You want process isolation
-- You're building a language-agnostic client
-
-## Exports
-
-The main entry point exports:
-
-```typescript
-// Factory
-createAgentSession
-
-// Auth and Models
-AuthStorage
-ModelRegistry
-discoverAuthStorage
-discoverModels
-
-// Discovery
-discoverSkills
-discoverExtensions
-discoverCustomTSCommands
-discoverContextFiles
-discoverSlashCommands
-discoverPromptTemplates
-discoverMCPServers
-
-// Helpers
-buildSystemPrompt
-Settings
-
-// Session management
-SessionManager
-
-// 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 classes
-ReadTool, BashTool, EditTool, WriteTool
-GrepTool, FindTool, PythonTool
-loadSshTool
-
-// Types
-type CreateAgentSessionOptions
-type CreateAgentSessionResult
-type CustomTool
-type ExtensionFactory
-type Skill
-type FileSlashCommand
-type SkillsSettings
-type Tool
-```
-
-For extension types, import from the main package:
-
-```typescript
-import type {
-	ExtensionAPI,
-	ExtensionFactory,
-	ExtensionContext,
-	ExtensionCommandContext,
-	ToolDefinition,
-} from "@oh-my-pi/pi-coding-agent";
-```
-
-For legacy hook types (deprecated, use extensions instead):
-
-```typescript
-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";
-```