@ai-agent-forge/agent-forge 0.85.0

package/docs/sdk.md

@@ -0,0 +1,1146 @@
+> 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.
+
+**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 { createStableAgentSession, ModelRuntime, SessionManager } from "@agent-forge/agent-forge";
+
+const modelRuntime = await ModelRuntime.create();
+const { facade } = await createStableAgentSession({
+  sessionManager: SessionManager.inMemory(),
+  modelRuntime,
+});
+
+facade.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+
+await facade.prompt("What files are in the current directory?");
+```
+
+## Installation
+
+```bash
+npm install @ai-agent-forge/agent-forge
+```
+
+The SDK is included in the main package. No separate installation needed.
+
+## Core Concepts
+
+### createStableAgentSession()
+
+The stable entry point for a single agent session. It runs the same assembly as the legacy `createAgentSession` factory and returns the stable pair instead of the raw session:
+
+- `facade` — a `CodingAgentFacadeV1` view for session control and state reads
+- `sessionAPI` — the `SessionAPI` projection of the session mechanism, for host adapters and embedded consumers
+
+The raw `AgentSession` stays an internal adapter: it is never returned and is not part of the stable surface.
+
+`createStableAgentSession()` uses a `ResourceLoader` to supply skills, prompt templates, themes, and context files. If you do not provide one, it uses `DefaultResourceLoader` with standard discovery. Capability plugins are discovered separately during session assembly from the plugins directories, or passed explicitly via `capabilityPluginPaths`.
+
+```typescript
+import { createStableAgentSession, SessionManager } from "@agent-forge/agent-forge";
+
+// Minimal: defaults with DefaultResourceLoader
+const { facade } = await createStableAgentSession();
+
+// Custom: override specific options
+const { facade } = await createStableAgentSession({
+  model: myModel,
+  tools: ["read", "bash"],
+  sessionManager: SessionManager.inMemory(),
+});
+```
+
+### Stable Surface: facade and SessionAPI
+
+The session that manages agent lifecycle, message history, model state, compaction, and event streaming is `AgentSession`. It is an internal adapter: new code neither constructs it nor calls it directly, and the stable entry never returns it. Program against the two stable faces instead:
+
+- `facade` (`CodingAgentFacadeV1`) — session control and state reads for host applications.
+- `sessionAPI` (`SessionAPI`) — the session mechanism projection, also reachable as `facade.getSessionAPI()`; the stable read/write face for host adapters and embedded consumers.
+
+Facade members by area:
+
+- Run control: `prompt`, `steer`, `followUp`, `abort`, `waitForIdle`, `getQueuedMessages`, `clearQueue`, `getPendingMessageCount`
+- State and info: `getState` (current `AgentState`), `getModel`, `getSessionId`, `getSessionFile`, `getSessionName`, `setSessionName`, `getCwd`, `getHeader`, `getSessionStats`
+- Model control: `setModel`, `getThinkingLevel`, `setThinkingLevel`, `cycleModel`, `cycleThinkingLevel`, `getScopedModels`, `setScopedModels`, `getAvailableModels`, `checkProviderAuth`, `getProviderAuth`
+- Events: `subscribe` (returns an unsubscribe function), `subscribeRawEventGate` (stdout backpressure pacing)
+- Run state: `isIdle`, `isStreaming`, `isCompacting`, `getContextUsage`, `getRetryAttempt`, `isBashRunning`
+- Compaction and tree: `compact`, `abortCompaction`, `navigateTree`, `getTree`, `getLeafId`, `getEntries`, `getContextEntries`, `appendLabelChange`
+- Tools and resources: `getToolNames`, `setActiveToolsByName`, `getToolDefinition`, `getSkills`, `getPrompts`, `getThemes`, `getAgentsFiles`, `getDiagnostics`
+- Export: `exportToHtml`, `exportToJsonl`
+- Lifecycle: `dispose`
+
+Members of the internal adapter such as the raw `Agent` object, in-place assignment to the state arrays, session rebinding, and underscore-prefixed internals are implementation details of the adapter, not stable contract.
+
+Session replacement APIs such as new-session, resume, fork, and import live on the runtime facade (`CodingAgentRuntimeFacadeV1`, reached through `createStableAgentSessionRuntime()`), not on the session facade.
+
+### createStableAgentSessionRuntime() and the runtime facade
+
+Use the runtime API when you need to replace the active session and rebuild cwd-bound runtime state.
+This is the same layer used by the built-in interactive, print, and RPC modes.
+
+`createStableAgentSessionRuntime()` takes a runtime factory plus the initial cwd/session target and returns the stable runtime facade (`CodingAgentRuntimeFacadeV1`). The raw `AgentSessionRuntime` and its `session` are internal adapters: the stable result carries no `runtime`/`session` field, and the current session is read through `runtimeFacade.getSessionFacade()`. The factory closes over process-global fixed inputs, recreates cwd-bound services for the effective cwd, resolves session options against those services, and returns a full runtime result.
+
+```typescript
+import {
+  type CreateAgentSessionRuntimeFactory,
+  createAgentSessionFromServices,
+  createAgentSessionServices,
+  createStableAgentSessionRuntime,
+  getAgentDir,
+  SessionManager,
+} from "@agent-forge/agent-forge";
+
+const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
+  const services = await createAgentSessionServices({ cwd });
+  return {
+    ...(await createAgentSessionFromServices({
+      services,
+      sessionManager,
+      sessionStartEvent,
+    })),
+    services,
+    diagnostics: services.diagnostics,
+  };
+};
+
+const { runtimeFacade } = await createStableAgentSessionRuntime(createRuntime, {
+  cwd: process.cwd(),
+  agentDir: getAgentDir(),
+  sessionManager: SessionManager.create(process.cwd()),
+});
+```
+
+The runtime facade owns replacement of the active session across:
+
+- `newSession()`
+- `switchSession()`
+- `fork()`
+- clone flows via `fork(entryId, { position: "at" })`
+- `importFromJsonl()`
+
+Important behavior:
+
+- the current session changes after those operations; the runtime facade's selector reads (`getSessionFile()`, `getSessionId()`, `getSessionDir()`, ...) follow it
+- `runtimeFacade.getSessionFacade()` returns the session facade (`CodingAgentFacadeV1`) over the **current** session, re-derived on every call — re-read it after a replacement instead of caching it
+- event subscriptions are attached to a specific session, so re-subscribe through the re-read session facade after replacement
+- rebinding a replaced session is host assembly: a host wires it through the runtime's rebind callback (`setRebindSession`), not through the stable surface; only hosts that register that callback get automatic rebinding
+- if runtime creation or replacement fails, the method throws and the caller decides how to handle it
+
+```typescript
+let unsubscribe: (() => void) | undefined;
+
+function bindSession() {
+  unsubscribe?.();
+  // Re-projects the runtime's current session; nothing to rebind by hand.
+  const facade = runtimeFacade.getSessionFacade();
+  unsubscribe = facade.subscribe(() => {});
+  return facade;
+}
+
+let facade = bindSession();
+await runtimeFacade.newSession();
+facade = bindSession();
+```
+
+> The runtime-level diagnostics the legacy runtime path exposes on `runtime.diagnostics` are not carried on the stable result yet; the stable result is `{ runtimeFacade }`.
+
+### Prompting and Message Queueing
+
+`PromptOptions` controls prompt expansion, queueing behavior while streaming, and prompt preflight notifications:
+
+```typescript
+interface PromptOptions {
+  expandPromptTemplates?: boolean;
+  images?: ImageContent[];
+  streamingBehavior?: "steer" | "followUp";
+  source?: InputSource;
+  preflightResult?: (success: boolean) => void;
+}
+```
+
+`preflightResult` is called once per `prompt()` invocation:
+
+- `true` when the prompt was accepted, queued, or handled immediately
+- `false` when prompt preflight rejected before acceptance
+
+It fires before `prompt()` resolves. `prompt()` still resolves only after the full accepted run finishes, including retries. Failures after acceptance are reported through the normal event and message stream, not through `preflightResult(false)`.
+
+The `facade.prompt()` method handles prompt templates, plugin commands, and message sending:
+
+```typescript
+// Basic prompt (when not streaming)
+await facade.prompt("What files are here?");
+
+// With images
+await facade.prompt("What's in this image?", {
+  images: [{ type: "image", source: { type: "base64", mediaType: "image/png", data: "..." } }]
+});
+
+// During streaming: must specify how to queue the message
+await facade.prompt("Stop and do this instead", { streamingBehavior: "steer" });
+await facade.prompt("After you're done, also check X", { streamingBehavior: "followUp" });
+```
+
+**Behavior:**
+- **Plugin commands** (e.g., `/mycommand` from a capability plugin): Execute immediately, even during streaming. They manage their own execution and user interaction.
+- **File-based prompt templates** (from `.md` files): Expanded to their content before sending or queueing.
+- **During streaming without `streamingBehavior`**: Throws an error. Use `steer()` or `followUp()` directly, or specify the option.
+- **`preflightResult(true)`**: Means the prompt was accepted, queued, or handled immediately.
+- **`preflightResult(false)`**: Means preflight rejected before acceptance.
+
+For explicit queueing during streaming:
+
+```typescript
+// Queue a steering message for delivery after the current assistant turn finishes its tool calls
+await facade.steer("New instruction");
+
+// Wait for agent to finish (delivered only when agent stops)
+await facade.followUp("After you're done, also do this");
+```
+
+Both `steer()` and `followUp()` expand file-based prompt templates but error on plugin commands (plugin commands cannot be queued).
+
+### Agent and AgentState
+
+The `Agent` class (from `@agent-forge/agent-core`) handles the core LLM interaction. It belongs to the internal session adapter, so the stable surface exposes its state as a view instead of handing out the agent:
+
+```typescript
+// Read the current state
+const state = facade.getState();
+
+// state.messages: AgentMessage[] - conversation history
+// state.model: Model - current model
+// state.thinkingLevel: ThinkingLevel - current thinking level
+// state.systemPrompt: string - system prompt
+// state.tools: AgentTool[] - available tools
+// state.streamingMessage?: AgentMessage - current partial assistant message
+// state.errorMessage?: string - latest assistant error
+
+// Wait for the agent to finish processing
+await facade.waitForIdle();
+```
+
+The returned state is the live agent state, but the stable contract is the read path. Replacing the state arrays in place (conversation history or tools) is internal adapter behavior outside the stable surface: use `navigateTree()` for branching or restoration, and `setActiveToolsByName()` to change the active tool set.
+
+### Events
+
+Subscribe to events to receive streaming output and lifecycle notifications.
+
+```typescript
+facade.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 (queue, compaction, retry)
+    case "queue_update":
+      console.log(event.steering, event.followUp);
+      break;
+    case "compaction_start":
+    case "compaction_end":
+    case "auto_retry_start":
+    case "auto_retry_end":
+    case "summarization_retry_scheduled":
+    case "summarization_retry_attempt_start":
+    case "summarization_retry_finished":
+      break;
+  }
+});
+```
+
+## Options Reference
+
+### Directories
+
+```typescript
+const { facade } = await createStableAgentSession({
+  // Working directory for DefaultResourceLoader discovery
+  cwd: process.cwd(), // default
+  
+  // Global config directory
+  agentDir: "~/.agent-forge/agent", // default (expands ~)
+});
+```
+
+`cwd` is used by `DefaultResourceLoader` for:
+- Project skills:
+  - `.agent-forge/skills/`
+  - `.agents/skills/` in `cwd` and ancestor directories (up to git repo root, or filesystem root when not in a repo)
+- Project prompts (`.agent-forge/prompts/`)
+- Context files (`AGENTS.md` walking up from cwd)
+- Session directory naming
+
+`agentDir` is used by `DefaultResourceLoader` for:
+- Global skills:
+  - `skills/` under `agentDir` (for example `~/.agent-forge/agent/skills/`)
+  - `~/.agents/skills/`
+- Global prompts (`prompts/`)
+- Global context file (`AGENTS.md`)
+- Settings (`settings.json`)
+- Custom models (`models.json`)
+- Credentials (`auth.json`)
+- Sessions (`sessions/`)
+
+Capability plugins are not discovered by the `ResourceLoader`. They are discovered from `<agentDir>/plugins` and `<cwd>/.agent-forge/plugins` during session assembly, or passed explicitly via the `capabilityPluginPaths` option.
+
+When you pass a custom `ResourceLoader`, `cwd` and `agentDir` no longer control resource discovery. They still influence session naming and tool path resolution.
+
+### Model
+
+```typescript
+import { getModel } from "@agent-forge/ai";
+import { createStableAgentSession, ModelRuntime } from "@agent-forge/agent-forge";
+
+const modelRuntime = await ModelRuntime.create();
+
+// create() restores cached catalogs but does not refresh an external catalog URL by default.
+// Opt in to a create-time network refresh and bound how long it may take:
+const refreshedRuntime = await ModelRuntime.create({
+  allowModelNetwork: true,
+  modelRefreshTimeoutMs: 15_000,
+});
+
+// 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
+// (doesn't check if API key exists)
+const customModel = modelRuntime.getModel("my-provider", "my-model");
+
+// Get only models that have valid authentication configured
+const available = await modelRuntime.getAvailable();
+
+const { facade } = await createStableAgentSession({
+  model: opus,
+  thinkingLevel: "medium", // off, minimal, low, medium, high, xhigh, max
+  
+  // Models for cycling (Ctrl+P in interactive mode)
+  scopedModels: [
+    { model: opus, thinkingLevel: "high" },
+    { model: haiku, thinkingLevel: "off" },
+  ],
+  
+  modelRuntime,
+});
+```
+
+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
+
+Remote catalogs are persisted locally so later runtimes can restore them without a network request. The default file is `~/.agent-forge/agent/models-store.json`; set `modelsStorePath` to choose another location, or inject `modelsStore` to control persistence. Network refreshes are throttled to once per provider every four hours unless forced. To force an immediate refresh, call `await modelRuntime.refresh({ allowNetwork: true, force: true, signal })`. Setting `AGENT_FORGE_OFFLINE` disables model network access.
+
+To match CLI model parsing, use the exported resolver helpers:
+
+```typescript
+import {
+  resolveCliModel,
+  resolveModelScopeWithDiagnostics,
+} from "@agent-forge/agent-forge";
+
+const cliModel = resolveCliModel({
+  cliModel: "anthropic/claude-opus-4-5:high",
+  modelRuntime,
+});
+if (cliModel.error) throw new Error(cliModel.error);
+if (cliModel.warning) console.warn(cliModel.warning);
+
+const { scopedModels, diagnostics } = await resolveModelScopeWithDiagnostics(
+  ["anthropic/*:high", "gpt-5"],
+  modelRuntime,
+);
+for (const diagnostic of diagnostics) {
+  console.warn(diagnostic.message);
+}
+```
+
+`resolveCliModel()` uses all registered models so `--api-key` style first-time setup can resolve a model before stored auth exists. `resolveModelScopeWithDiagnostics()` matches `--models` and `enabledModels` semantics while returning warnings instead of printing them.
+
+> See [examples/sdk/02-custom-model.ts](../examples/sdk/02-custom-model.ts)
+
+### API Keys and OAuth
+
+Authentication resolution priority (handled by `ModelRuntime`):
+1. Runtime overrides (via `setRuntimeApiKey`, not persisted)
+2. Stored credentials in `auth.json` (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`)
+
+```typescript
+import { InMemoryCredentialStore } from "@agent-forge/ai";
+import { createStableAgentSession, ModelRuntime } from "@agent-forge/agent-forge";
+
+// Default: uses ~/.agent-forge/agent/auth.json and ~/.agent-forge/agent/models.json
+const modelRuntime = await ModelRuntime.create();
+
+// Provider-owned auth methods and current status
+for (const provider of modelRuntime.getProviders()) {
+  const status = await modelRuntime.checkAuth(provider.id);
+  console.log(provider.name, provider.auth, status);
+}
+
+// Runtime API key override (not persisted to disk)
+await modelRuntime.setRuntimeApiKey("anthropic", "sk-my-temp-key");
+
+// Custom credential and model locations
+const customRuntime = await ModelRuntime.create({
+  authPath: "/my/app/auth.json",
+  modelsPath: "/my/app/models.json",
+});
+
+// Or inject any pi-ai CredentialStore
+const credentials = new InMemoryCredentialStore();
+const inMemoryRuntime = await ModelRuntime.create({ credentials });
+
+const { facade } = await createStableAgentSession({
+  modelRuntime: customRuntime,
+});
+```
+
+`login()`, `logout()`, `setRuntimeApiKey()`, and `removeRuntimeApiKey()` resolve after the affected provider's cached/built-in catalog, composition, and availability snapshot are locally consistent. They do not wait for remote catalog freshness. If credentials were committed but local synchronization fails, they reject with the exported `CredentialSynchronizationError`; inspect its `providerId`, `operation`, `credential`, and `cause` fields instead of retrying the credential mutation blindly.
+
+Public model/auth operations and `ModelRuntime.create({ signal })` accept optional abort signals and are unbounded when omitted. SDK applications own deadline policy for remote catalog freshness:
+
+```typescript
+const signal = AbortSignal.timeout(15_000);
+const result = await modelRuntime.refresh({
+  providers: ["anthropic"],
+  signal,
+});
+if (result.aborted) console.warn("Catalog refresh timed out; using cached models");
+for (const [providerId, error] of result.errors) {
+  console.warn(`Could not refresh ${providerId}:`, error);
+}
+```
+
+A failed or timed-out network refresh does not undo a successful credential operation. `refresh()` starts a new provider generation, so it does not wait behind an older stalled refresh and stale generations cannot publish afterward.
+
+> See [examples/sdk/09-api-keys-and-oauth.ts](../examples/sdk/09-api-keys-and-oauth.ts)
+
+### System Prompt
+
+Use a `ResourceLoader` to override the system prompt:
+
+```typescript
+import { createStableAgentSession, DefaultResourceLoader } from "@agent-forge/agent-forge";
+
+const loader = new DefaultResourceLoader({
+  systemPromptOverride: () => "You are a helpful assistant.",
+});
+await loader.reload();
+
+const { facade } = await createStableAgentSession({ resourceLoader: loader });
+```
+
+> See [examples/sdk/03-custom-prompt.ts](../examples/sdk/03-custom-prompt.ts)
+
+### Tools
+
+Specify which built-in tools to enable:
+
+- Built-in tool names: `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, `ls`
+- Default built-ins: `read`, `bash`, `edit`, `write`
+- `noTools: "all"` disables all tools
+- `noTools: "builtin"` disables default built-ins while keeping plugin/custom tools enabled
+- `excludeTools` disables specific built-in, plugin, or custom tool names after any `tools` allowlist is applied
+
+The `edit` tool returns `details.diff` for Pi's TUI display and `details.patch` as a standard unified patch for SDK consumers.
+
+```typescript
+import { createStableAgentSession } from "@agent-forge/agent-forge";
+
+// Read-only mode
+const { facade } = await createStableAgentSession({
+  tools: ["read", "grep", "find", "ls"],
+});
+
+// Pick specific tools
+const { facade } = await createStableAgentSession({
+  tools: ["read", "bash", "grep"],
+});
+
+// Use PowerShell instead of Bash on Windows
+const { facade } = await createStableAgentSession({
+  tools: ["read", "powershell", "edit", "write"],
+});
+
+// Disable one tool while keeping the rest available
+const { facade } = await createStableAgentSession({
+  excludeTools: ["ask_question"],
+});
+```
+
+#### Tools with Custom cwd
+
+When you pass a custom `cwd`, `createStableAgentSession()` builds selected built-in tools for that cwd.
+
+```typescript
+import { createStableAgentSession, SessionManager } from "@agent-forge/agent-forge";
+
+const cwd = "/path/to/project";
+
+// Use default tools for custom cwd
+const { facade } = await createStableAgentSession({
+  cwd,
+  sessionManager: SessionManager.inMemory(cwd),
+});
+
+// Or pick specific tools for custom cwd
+const { facade } = await createStableAgentSession({
+  cwd,
+  tools: ["read", "bash", "grep"],
+  sessionManager: SessionManager.inMemory(cwd),
+});
+```
+
+> See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
+
+### Custom Tools
+
+```typescript
+import { Type } from "typebox";
+import { createStableAgentSession, defineTool } from "@agent-forge/agent-forge";
+
+// Inline custom tool
+const myTool = defineTool({
+  name: "my_tool",
+  label: "My Tool",
+  description: "Does something useful",
+  parameters: Type.Object({
+    input: Type.String({ description: "Input value" }),
+  }),
+  execute: async (_toolCallId, params) => ({
+    content: [{ type: "text", text: `Result: ${params.input}` }],
+    details: {},
+  }),
+});
+
+// Pass custom tools directly
+const { facade } = await createStableAgentSession({
+  customTools: [myTool],
+});
+```
+
+Use `defineTool()` for standalone definitions and arrays like `customTools: [myTool]`.
+
+Custom tools passed via `customTools` are combined with the tools registered by capability plugins.
+
+If you pass `tools`, include each custom or plugin tool name you want enabled, for example `tools: ["read", "bash", "my_tool"]`.
+
+> See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
+
+### Capability Plugins
+
+Custom tools, commands, and lifecycle handlers ship as capability plugins: a `plugin.json` manifest plus a factory that receives the public capability API. Sessions discover plugins from `<agentDir>/plugins` (default `~/.agent-forge/agent/plugins`) and `<cwd>/.agent-forge/plugins`; you can also pass manifest paths explicitly via the `capabilityPluginPaths` option.
+
+See [packages.md](packages.md) for the authoring guide and [examples/extensions/](../examples/extensions/) for working capability plugins.
+
+### Skills
+
+```typescript
+import {
+  createStableAgentSession,
+  DefaultResourceLoader,
+  type Skill,
+} from "@agent-forge/agent-forge";
+
+const customSkill: Skill = {
+  name: "my-skill",
+  description: "Custom instructions",
+  filePath: "/path/to/SKILL.md",
+  baseDir: "/path/to",
+  source: "custom",
+};
+
+const loader = new DefaultResourceLoader({
+  skillsOverride: (current) => ({
+    skills: [...current.skills, customSkill],
+    diagnostics: current.diagnostics,
+  }),
+});
+await loader.reload();
+
+const { facade } = await createStableAgentSession({ resourceLoader: loader });
+```
+
+> See [examples/sdk/04-skills.ts](../examples/sdk/04-skills.ts)
+
+### Context Files
+
+```typescript
+import { createStableAgentSession, DefaultResourceLoader } from "@agent-forge/agent-forge";
+
+const loader = new DefaultResourceLoader({
+  agentsFilesOverride: (current) => ({
+    agentsFiles: [
+      ...current.agentsFiles,
+      { path: "/virtual/AGENTS.md", content: "# Guidelines\n\n- Be concise" },
+    ],
+  }),
+});
+await loader.reload();
+
+const { facade } = await createStableAgentSession({ resourceLoader: loader });
+```
+
+> See [examples/sdk/07-context-files.ts](../examples/sdk/07-context-files.ts)
+
+### Slash Commands
+
+```typescript
+import {
+  createStableAgentSession,
+  DefaultResourceLoader,
+  type PromptTemplate,
+} from "@agent-forge/agent-forge";
+
+const customCommand: PromptTemplate = {
+  name: "deploy",
+  description: "Deploy the application",
+  source: "(custom)",
+  content: "# Deploy\n\n1. Build\n2. Test\n3. Deploy",
+};
+
+const loader = new DefaultResourceLoader({
+  promptsOverride: (current) => ({
+    prompts: [...current.prompts, customCommand],
+    diagnostics: current.diagnostics,
+  }),
+});
+await loader.reload();
+
+const { facade } = await createStableAgentSession({ resourceLoader: loader });
+```
+
+> See [examples/sdk/08-prompt-templates.ts](../examples/sdk/08-prompt-templates.ts)
+
+### Session Management
+
+Sessions use a tree structure with `id`/`parentId` linking, enabling in-place branching.
+
+```typescript
+import {
+  type CreateAgentSessionRuntimeFactory,
+  createAgentSessionFromServices,
+  createAgentSessionServices,
+  createStableAgentSession,
+  createStableAgentSessionRuntime,
+  getAgentDir,
+  SessionManager,
+} from "@agent-forge/agent-forge";
+
+// In-memory (no persistence)
+const { facade } = await createStableAgentSession({
+  sessionManager: SessionManager.inMemory(),
+});
+
+// New persistent session
+const { facade: persistedFacade } = await createStableAgentSession({
+  sessionManager: SessionManager.create(process.cwd()),
+});
+
+// Continue most recent
+const { facade: continuedFacade } = await createStableAgentSession({
+  sessionManager: SessionManager.continueRecent(process.cwd()),
+});
+
+// Open specific file
+const { facade: openedFacade } = await createStableAgentSession({
+  sessionManager: SessionManager.open("/path/to/session.jsonl"),
+});
+
+// List sessions
+const currentProjectSessions = await SessionManager.list(process.cwd());
+const allSessions = await SessionManager.listAll(process.cwd());
+
+// Session replacement API for /new, /resume, /fork, /clone, and import flows.
+const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
+  const services = await createAgentSessionServices({ cwd });
+  return {
+    ...(await createAgentSessionFromServices({
+      services,
+      sessionManager,
+      sessionStartEvent,
+    })),
+    services,
+    diagnostics: services.diagnostics,
+  };
+};
+
+const { runtimeFacade } = await createStableAgentSessionRuntime(createRuntime, {
+  cwd: process.cwd(),
+  agentDir: getAgentDir(),
+  sessionManager: SessionManager.create(process.cwd()),
+});
+
+// Replace the active session with a fresh one
+await runtimeFacade.newSession();
+
+// Replace the active session with another saved session
+await runtimeFacade.switchSession("/path/to/session.jsonl");
+
+// Replace the active session with a fork from a specific user entry
+await runtimeFacade.fork("entry-id");
+
+// Clone the active path through a specific entry
+await runtimeFacade.fork("entry-id", { position: "at" });
+
+// The current session's v1 facade, re-read after a replacement
+const currentFacade = runtimeFacade.getSessionFacade();
+```
+
+> `createStableAgentSession()` reports the same `modelFallbackMessage` create-time warning as the legacy factory: it is set when a continued session's model could not be restored, or when no model resolves at all. It rides the create result (`CreateStableAgentSessionResult.modelFallbackMessage`), not a facade member, because it describes the create step rather than the session.
+
+**SessionManager tree API:**
+
+```typescript
+const sm = SessionManager.open("/path/to/session.jsonl");
+
+// Session listing
+const currentProjectSessions = await SessionManager.list(process.cwd());
+const allSessions = await SessionManager.listAll(process.cwd());
+
+// 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 [Session Format](session-format.md)
+
+### Settings Management
+
+```typescript
+import { createStableAgentSession, SettingsManager, SessionManager } from "@agent-forge/agent-forge";
+
+// Default: loads from files (global + project merged)
+const { facade } = await createStableAgentSession({
+  settingsManager: SettingsManager.create(),
+});
+
+// With overrides
+const settingsManager = SettingsManager.create();
+settingsManager.applyOverrides({
+  compaction: { enabled: false },
+  retry: { enabled: true, maxRetries: 5 },
+});
+const { facade } = await createStableAgentSession({ settingsManager });
+
+// In-memory (no file I/O, for testing)
+const { facade } = await createStableAgentSession({
+  settingsManager: SettingsManager.inMemory({ compaction: { enabled: false } }),
+  sessionManager: SessionManager.inMemory(),
+});
+
+// Custom directories
+const { facade } = await createStableAgentSession({
+  settingsManager: SettingsManager.create("/custom/cwd", "/custom/agent"),
+});
+```
+
+**Static factories:**
+- `SettingsManager.create(cwd?, agentDir?)` - Load from files
+- `SettingsManager.inMemory(settings?)` - No file I/O
+
+**Project-specific settings:**
+
+Settings load from two locations and merge:
+1. Global: `~/.agent-forge/agent/settings.json`
+2. Project: `<cwd>/.agent-forge/settings.json`
+
+Project overrides global. Nested objects merge keys. Setters modify global settings by default.
+
+**Persistence and error handling semantics:**
+
+- Settings getters/setters are synchronous for in-memory state.
+- Setters enqueue persistence writes asynchronously.
+- Call `await settingsManager.flush()` when you need a durability boundary (for example, before process exit or before asserting file contents in tests).
+- `SettingsManager` does not print settings I/O errors. Use `settingsManager.drainErrors()` and report them in your app layer.
+
+> See [examples/sdk/10-settings.ts](../examples/sdk/10-settings.ts)
+
+## ResourceLoader
+
+Use `DefaultResourceLoader` to discover skills, prompts, themes, and context files.
+
+```typescript
+import {
+  DefaultResourceLoader,
+  getAgentDir,
+} from "@agent-forge/agent-forge";
+
+const loader = new DefaultResourceLoader({
+  cwd,
+  agentDir: getAgentDir(),
+});
+await loader.reload();
+
+const skills = loader.getSkills();
+const prompts = loader.getPrompts();
+const themes = loader.getThemes();
+const contextFiles = loader.getAgentsFiles().agentsFiles;
+```
+
+## Return Value
+
+`createStableAgentSession()` returns the stable facade pair:
+
+```typescript
+interface CreateStableAgentSessionResult {
+  // Session control and state reads (CodingAgentFacadeV1)
+  facade: CodingAgentFacadeV1;
+
+  // Session mechanism projection for host adapters and embedded consumers
+  sessionAPI: SessionAPI;
+
+  // Create-time model fallback diagnostic, undefined when no fallback happened
+  modelFallbackMessage?: string;
+}
+```
+
+Both types are exported from the package root, and no raw `AgentSession` is returned. The create-time model-fallback warning is readable as `modelFallbackMessage` on the create result above.
+
+## Complete Example
+
+```typescript
+import { getModel } from "@agent-forge/ai";
+import { Type } from "typebox";
+import {
+  createStableAgentSession,
+  DefaultResourceLoader,
+  defineTool,
+  ModelRuntime,
+  SessionManager,
+  SettingsManager,
+} from "@agent-forge/agent-forge";
+
+const modelRuntime = await ModelRuntime.create({
+  authPath: "/custom/agent/auth.json",
+  modelsPath: "/custom/agent/models.json",
+});
+if (process.env.MY_KEY) {
+  await modelRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY);
+}
+
+// Inline tool
+const statusTool = defineTool({
+  name: "status",
+  label: "Status",
+  description: "Get system status",
+  parameters: Type.Object({}),
+  execute: async () => ({
+    content: [{ type: "text", text: `Uptime: ${process.uptime()}s` }],
+    details: {},
+  }),
+});
+
+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 loader = new DefaultResourceLoader({
+  cwd: process.cwd(),
+  agentDir: "/custom/agent",
+  settingsManager,
+  systemPromptOverride: () => "You are a minimal assistant. Be concise.",
+});
+await loader.reload();
+
+const { facade } = await createStableAgentSession({
+  cwd: process.cwd(),
+  agentDir: "/custom/agent",
+
+  model,
+  thinkingLevel: "off",
+  modelRuntime,
+
+  tools: ["read", "bash", "status"],
+  customTools: [statusTool],
+  resourceLoader: loader,
+
+  sessionManager: SessionManager.inMemory(),
+  settingsManager,
+});
+
+facade.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+
+await facade.prompt("Get status and list files.");
+```
+
+## Run Modes
+
+The SDK exports run mode utilities for building custom interfaces on top of the session runtime (`createAgentSessionRuntime()`):
+
+### InteractiveMode
+
+Full TUI interactive mode with editor, chat history, and all built-in commands:
+
+```typescript
+import {
+  type CreateAgentSessionRuntimeFactory,
+  createAgentSessionFromServices,
+  createAgentSessionRuntime,
+  createAgentSessionServices,
+  getAgentDir,
+  InteractiveMode,
+  SessionManager,
+} from "@agent-forge/agent-forge";
+
+const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
+  const services = await createAgentSessionServices({ cwd });
+  return {
+    ...(await createAgentSessionFromServices({ services, sessionManager, sessionStartEvent })),
+    services,
+    diagnostics: services.diagnostics,
+  };
+};
+const runtime = await createAgentSessionRuntime(createRuntime, {
+  cwd: process.cwd(),
+  agentDir: getAgentDir(),
+  sessionManager: SessionManager.create(process.cwd()),
+});
+
+const mode = new InteractiveMode(runtime, {
+  migratedProviders: [],
+  modelFallbackMessage: undefined,
+  initialMessage: "Hello",
+  initialImages: [],
+  initialMessages: [],
+});
+
+await mode.run();
+```
+
+### runPrintMode
+
+Single-shot mode: send prompts, output result, exit:
+
+```typescript
+import {
+  type CreateAgentSessionRuntimeFactory,
+  createAgentSessionFromServices,
+  createAgentSessionRuntime,
+  createAgentSessionServices,
+  getAgentDir,
+  runPrintMode,
+  SessionManager,
+} from "@agent-forge/agent-forge";
+
+const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
+  const services = await createAgentSessionServices({ cwd });
+  return {
+    ...(await createAgentSessionFromServices({ services, sessionManager, sessionStartEvent })),
+    services,
+    diagnostics: services.diagnostics,
+  };
+};
+const runtime = await createAgentSessionRuntime(createRuntime, {
+  cwd: process.cwd(),
+  agentDir: getAgentDir(),
+  sessionManager: SessionManager.create(process.cwd()),
+});
+
+await runPrintMode(runtime, {
+  mode: "text",
+  initialMessage: "Hello",
+  initialImages: [],
+  messages: ["Follow up"],
+});
+```
+
+### runRpcMode
+
+JSON-RPC mode for subprocess integration:
+
+```typescript
+import {
+  type CreateAgentSessionRuntimeFactory,
+  createAgentSessionFromServices,
+  createAgentSessionRuntime,
+  createAgentSessionServices,
+  getAgentDir,
+  runRpcMode,
+  SessionManager,
+} from "@agent-forge/agent-forge";
+
+const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
+  const services = await createAgentSessionServices({ cwd });
+  return {
+    ...(await createAgentSessionFromServices({ services, sessionManager, sessionStartEvent })),
+    services,
+    diagnostics: services.diagnostics,
+  };
+};
+const runtime = await createAgentSessionRuntime(createRuntime, {
+  cwd: process.cwd(),
+  agentDir: getAgentDir(),
+  sessionManager: SessionManager.create(process.cwd()),
+});
+
+await runRpcMode(runtime);
+```
+
+See [RPC documentation](rpc.md) for the JSON protocol.
+
+## RPC Mode Alternative
+
+For subprocess-based integration without building with the SDK, use the CLI directly:
+
+```bash
+agent-forge --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 and plugins 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
+createStableAgentSession
+createStableAgentSessionRuntime
+createAgentSessionRuntime
+AgentSessionRuntime
+createAgentSession // legacy factory; returns the internal AgentSession adapter
+
+// Stable surface
+type CreateStableAgentSessionResult
+type CodingAgentFacadeV1
+type CreateStableAgentSessionRuntimeResult
+type CodingAgentRuntimeFacadeV1
+type SessionAPI
+
+// Auth and Models
+ModelRuntime // implements pi-ai Models and owns credential storage
+ModelRegistry // synchronous model registry facade
+CredentialSynchronizationError
+resolveCliModel
+resolveModelScopeWithDiagnostics
+
+// Resource loading
+DefaultResourceLoader
+type ResourceLoader
+createEventBus
+
+// Constants and helpers
+CONFIG_DIR_NAME
+defineTool
+getAgentDir
+getPackageDir
+getReadmePath
+getDocsPath
+getExamplesPath
+
+// Session management
+SessionManager
+SettingsManager
+
+// Tool factories
+createCodingTools
+createReadOnlyTools
+createReadTool, createBashTool, createPowerShellTool, createEditTool, createWriteTool
+createGrepTool, createFindTool, createLsTool
+
+// Types
+type CreateAgentSessionOptions
+type CreateAgentSessionResult
+type ToolDefinition
+type Skill
+type PromptTemplate
+type Tool
+```