@vandeepunk/pi-coding-agent 0.0.6 → 1.0.0

package/examples/extensions/subagent/agents.ts

@@ -3,9 +3,8 @@
  */
 
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
-import { parseFrontmatter } from "@mariozechner/pi-coding-agent";
+import { getAgentDir, parseFrontmatter } from "@mariozechner/pi-coding-agent";
 
 export type AgentScope = "user" | "project" | "both";
 
@@ -96,7 +95,7 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
 }
 
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
-	const userDir = path.join(os.homedir(), ".pi", "agent", "agents");
+	const userDir = path.join(getAgentDir(), "agents");
 	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
 
 	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");

package/examples/extensions/subagent/index.ts

@@ -19,7 +19,7 @@ import * as path from "node:path";
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
 import type { Message } from "@mariozechner/pi-ai";
 import { StringEnum } from "@mariozechner/pi-ai";
-import { type ExtensionAPI, getMarkdownTheme } from "@mariozechner/pi-coding-agent";
+import { type ExtensionAPI, getMarkdownTheme, withFileMutationQueue } from "@mariozechner/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.js";
@@ -207,14 +207,31 @@ async function mapWithConcurrencyLimit<TIn, TOut>(
 	return results;
 }
 
-function writePromptToTempFile(agentName: string, prompt: string): { dir: string; filePath: string } {
-	const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
+async function writePromptToTempFile(agentName: string, prompt: string): Promise<{ dir: string; filePath: string }> {
+	const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-subagent-"));
 	const safeName = agentName.replace(/[^\w.-]+/g, "_");
 	const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
-	fs.writeFileSync(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
+	await withFileMutationQueue(filePath, async () => {
+		await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
+	});
 	return { dir: tmpDir, filePath };
 }
 
+function getPiInvocation(args: string[]): { command: string; args: string[] } {
+	const currentScript = process.argv[1];
+	if (currentScript && fs.existsSync(currentScript)) {
+		return { command: process.execPath, args: [currentScript, ...args] };
+	}
+
+	const execName = path.basename(process.execPath).toLowerCase();
+	const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+	if (!isGenericRuntime) {
+		return { command: process.execPath, args };
+	}
+
+	return { command: "pi", args };
+}
+
 type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
 
 async function runSingleAgent(
@@ -274,7 +291,7 @@ async function runSingleAgent(
 
 	try {
 		if (agent.systemPrompt.trim()) {
-			const tmp = writePromptToTempFile(agent.name, agent.systemPrompt);
+			const tmp = await writePromptToTempFile(agent.name, agent.systemPrompt);
 			tmpPromptDir = tmp.dir;
 			tmpPromptPath = tmp.filePath;
 			args.push("--append-system-prompt", tmpPromptPath);
@@ -284,7 +301,12 @@ async function runSingleAgent(
 		let wasAborted = false;
 
 		const exitCode = await new Promise<number>((resolve) => {
-			const proc = spawn("pi", args, { cwd: cwd ?? defaultCwd, shell: false, stdio: ["ignore", "pipe", "pipe"] });
+			const invocation = getPiInvocation(args);
+			const proc = spawn(invocation.command, invocation.args, {
+				cwd: cwd ?? defaultCwd,
+				shell: false,
+				stdio: ["ignore", "pipe", "pipe"],
+			});
 			let buffer = "";
 
 			const processLine = (line: string) => {
@@ -646,7 +668,7 @@ export default function (pi: ExtensionAPI) {
 			};
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			const scope: AgentScope = args.agentScope ?? "user";
 			if (args.chain && args.chain.length > 0) {
 				let text =
@@ -690,7 +712,7 @@ export default function (pi: ExtensionAPI) {
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded }, theme, _context) {
 			const details = result.details as SubagentDetails | undefined;
 			if (!details || details.results.length === 0) {
 				const text = result.content[0];

package/examples/extensions/summarize.ts

@@ -165,12 +165,15 @@ export default function (pi: ExtensionAPI) {
 				ctx.ui.notify("Model openai/gpt-5.2 not found", "warning");
 			}
 
-			const apiKey = model ? await ctx.modelRegistry.getApiKey(model) : undefined;
-			if (!apiKey && ctx.hasUI) {
+			const auth = model ? await ctx.modelRegistry.getApiKeyAndHeaders(model) : undefined;
+			if (auth && !auth.ok && ctx.hasUI) {
+				ctx.ui.notify(auth.error, "warning");
+			}
+			if (auth?.ok && !auth.apiKey && ctx.hasUI) {
 				ctx.ui.notify("No API key for openai/gpt-5.2", "warning");
 			}
 
-			if (!model || !apiKey) {
+			if (!model || !auth?.ok || !auth.apiKey) {
 				return;
 			}
 
@@ -182,7 +185,15 @@ export default function (pi: ExtensionAPI) {
 				},
 			];
 
-			const response = await complete(model, { messages: summaryMessages }, { apiKey, reasoningEffort: "high" });
+			const response = await complete(
+				model,
+				{ messages: summaryMessages },
+				{
+					apiKey: auth.apiKey,
+					headers: auth.headers,
+					reasoningEffort: "high",
+				},
+			);
 
 			const summary = response.content
 				.filter((c): c is { type: "text"; text: string } => c.type === "text")

package/examples/extensions/todo.ts

@@ -130,8 +130,6 @@ export default function (pi: ExtensionAPI) {
 
 	// Reconstruct state on session events
 	pi.on("session_start", async (_event, ctx) => reconstructState(ctx));
-	pi.on("session_switch", async (_event, ctx) => reconstructState(ctx));
-	pi.on("session_fork", async (_event, ctx) => reconstructState(ctx));
 	pi.on("session_tree", async (_event, ctx) => reconstructState(ctx));
 
 	// Register the todo tool for the LLM
@@ -220,14 +218,14 @@ export default function (pi: ExtensionAPI) {
 			}
 		},
 
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("todo ")) + theme.fg("muted", args.action);
 			if (args.text) text += ` ${theme.fg("dim", `"${args.text}"`)}`;
 			if (args.id !== undefined) text += ` ${theme.fg("accent", `#${args.id}`)}`;
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded }, theme, _context) {
 			const details = result.details as TodoDetails | undefined;
 			if (!details) {
 				const text = result.content[0];

package/examples/extensions/tool-override.ts

@@ -21,14 +21,13 @@
  */
 
 import type { TextContent } from "@mariozechner/pi-ai";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { type ExtensionAPI, getAgentDir, withFileMutationQueue } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
-import { appendFileSync, constants, readFileSync } from "fs";
-import { access, readFile } from "fs/promises";
-import { homedir } from "os";
+import { constants, readFileSync } from "fs";
+import { access, appendFile, readFile } from "fs/promises";
 import { join, resolve } from "path";
 
-const LOG_FILE = join(homedir(), ".pi", "agent", "read-access.log");
+const LOG_FILE = join(getAgentDir(), "read-access.log");
 
 // Paths that are blocked from reading
 const BLOCKED_PATTERNS = [
@@ -45,14 +44,16 @@ function isBlockedPath(path: string): boolean {
 	return BLOCKED_PATTERNS.some((pattern) => pattern.test(path));
 }
 
-function logAccess(path: string, allowed: boolean, reason?: string) {
+async function logAccess(path: string, allowed: boolean, reason?: string) {
 	const timestamp = new Date().toISOString();
 	const status = allowed ? "ALLOWED" : "BLOCKED";
 	const msg = reason ? ` (${reason})` : "";
 	const line = `[${timestamp}] ${status}: ${path}${msg}\n`;
 
 	try {
-		appendFileSync(LOG_FILE, line);
+		await withFileMutationQueue(LOG_FILE, async () => {
+			await appendFile(LOG_FILE, line);
+		});
 	} catch {
 		// Ignore logging errors
 	}
@@ -78,7 +79,7 @@ export default function (pi: ExtensionAPI) {
 
 			// Check if path is blocked
 			if (isBlockedPath(absolutePath)) {
-				logAccess(absolutePath, false, "matches blocked pattern");
+				await logAccess(absolutePath, false, "matches blocked pattern");
 				return {
 					content: [
 						{
@@ -91,7 +92,7 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			// Log allowed access
-			logAccess(absolutePath, true);
+			await logAccess(absolutePath, true);
 
 			// Perform the actual read (simplified implementation)
 			try {

package/examples/extensions/tools.ts

@@ -138,9 +138,4 @@ export default function toolsExtension(pi: ExtensionAPI) {
 	pi.on("session_tree", async (_event, ctx) => {
 		restoreFromBranch(ctx);
 	});
-
-	// Restore state after forking
-	pi.on("session_fork", async (_event, ctx) => {
-		restoreFromBranch(ctx);
-	});
 }

package/examples/extensions/trigger-compact.ts

@@ -3,6 +3,8 @@ import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-age
 const COMPACT_THRESHOLD_TOKENS = 100_000;
 
 export default function (pi: ExtensionAPI) {
+	let previousTokens: number | null | undefined;
+
 	const triggerCompaction = (ctx: ExtensionContext, customInstructions?: string) => {
 		if (ctx.hasUI) {
 			ctx.ui.notify("Compaction started", "info");
@@ -24,7 +26,15 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("turn_end", (_event, ctx) => {
 		const usage = ctx.getContextUsage();
-		if (!usage || usage.tokens <= COMPACT_THRESHOLD_TOKENS) {
+		const currentTokens = usage?.tokens ?? null;
+		if (currentTokens === null) {
+			return;
+		}
+
+		const crossedThreshold =
+			previousTokens !== undefined && previousTokens !== null && previousTokens <= COMPACT_THRESHOLD_TOKENS;
+		previousTokens = currentTokens;
+		if (!crossedThreshold || currentTokens <= COMPACT_THRESHOLD_TOKENS) {
 			return;
 		}
 		triggerCompaction(ctx);

package/examples/extensions/truncated-tool.ts

@@ -14,6 +14,7 @@
  * built-in `grep` tool in src/core/tools/grep.ts for a more complete implementation.
  */
 
+import { mkdtemp, writeFile } from "node:fs/promises";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import {
 	DEFAULT_MAX_BYTES,
@@ -21,11 +22,11 @@ import {
 	formatSize,
 	type TruncationResult,
 	truncateHead,
+	withFileMutationQueue,
 } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { execSync } from "child_process";
-import { mkdtempSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 
@@ -108,9 +109,11 @@ export default function (pi: ExtensionAPI) {
 
 			if (truncation.truncated) {
 				// Save full output to a temp file so LLM can access it if needed
-				const tempDir = mkdtempSync(join(tmpdir(), "pi-rg-"));
+				const tempDir = await mkdtemp(join(tmpdir(), "pi-rg-"));
 				const tempFile = join(tempDir, "output.txt");
-				writeFileSync(tempFile, output);
+				await withFileMutationQueue(tempFile, async () => {
+					await writeFile(tempFile, output, "utf8");
+				});
 
 				details.truncation = truncation;
 				details.fullOutputPath = tempFile;
@@ -132,7 +135,7 @@ export default function (pi: ExtensionAPI) {
 		},
 
 		// Custom rendering of the tool call (shown before/during execution)
-		renderCall(args, theme) {
+		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("rg "));
 			text += theme.fg("accent", `"${args.pattern}"`);
 			if (args.path) {
@@ -145,7 +148,7 @@ export default function (pi: ExtensionAPI) {
 		},
 
 		// Custom rendering of the tool result
-		renderResult(result, { expanded, isPartial }, theme) {
+		renderResult(result, { expanded, isPartial }, theme, _context) {
 			const details = result.details as RgDetails | undefined;
 
 			// Handle streaming/partial results

package/examples/extensions/widget-placement.ts

@@ -1,17 +1,9 @@
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
-
-const applyWidgets = (ctx: ExtensionContext) => {
-	if (!ctx.hasUI) return;
-	ctx.ui.setWidget("widget-above", ["Above editor widget"]);
-	ctx.ui.setWidget("widget-below", ["Below editor widget"], { placement: "belowEditor" });
-};
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
 export default function widgetPlacementExtension(pi: ExtensionAPI) {
 	pi.on("session_start", (_event, ctx) => {
-		applyWidgets(ctx);
-	});
-
-	pi.on("session_switch", (_event, ctx) => {
-		applyWidgets(ctx);
+		if (!ctx.hasUI) return;
+		ctx.ui.setWidget("widget-above", ["Above editor widget"]);
+		ctx.ui.setWidget("widget-below", ["Below editor widget"], { placement: "belowEditor" });
 	});
 }

package/examples/extensions/with-deps/index.ts

@@ -21,11 +21,7 @@ export default function (pi: ExtensionAPI) {
 		execute: async (_toolCallId, params) => {
 			const result = ms(params.duration as ms.StringValue);
 			if (result === undefined) {
-				return {
-					content: [{ type: "text", text: `Invalid duration: "${params.duration}"` }],
-					isError: true,
-					details: {},
-				};
+				throw new Error(`Invalid duration: "${params.duration}"`);
 			}
 			return {
 				content: [{ type: "text", text: `${params.duration} = ${result} milliseconds` }],

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-with-deps",
-  "version": "1.16.9",
+  "version": "1.29.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-with-deps",
-      "version": "1.16.9",
+      "version": "1.29.1",
       "dependencies": {
         "ms": "^2.1.3"
       },

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-with-deps",
   "private": true,
-  "version": "1.16.9",
+  "version": "1.29.1",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/sdk/02-custom-model.ts

@@ -8,8 +8,8 @@ import { getModel } from "@mariozechner/pi-ai";
 import { AuthStorage, createAgentSession, ModelRegistry } from "@mariozechner/pi-coding-agent";
 
 // Set up auth storage and model registry
-const authStorage = new AuthStorage();
-const modelRegistry = new ModelRegistry(authStorage);
+const authStorage = AuthStorage.create();
+const modelRegistry = ModelRegistry.create(authStorage);
 
 // Option 1: Find a specific built-in model by provider/id
 const opus = getModel("anthropic", "claude-opus-4-5");

package/examples/sdk/04-skills.ts

@@ -5,7 +5,13 @@
  * Discover, filter, merge, or replace them.
  */
 
-import { createAgentSession, DefaultResourceLoader, SessionManager, type Skill } from "@mariozechner/pi-coding-agent";
+import {
+	createAgentSession,
+	createSyntheticSourceInfo,
+	DefaultResourceLoader,
+	SessionManager,
+	type Skill,
+} from "@mariozechner/pi-coding-agent";
 
 // Or define custom skills inline
 const customSkill: Skill = {
@@ -13,7 +19,7 @@ const customSkill: Skill = {
 	description: "Custom project instructions",
 	filePath: "/virtual/SKILL.md",
 	baseDir: "/virtual",
-	source: "path",
+	sourceInfo: createSyntheticSourceInfo("/virtual/SKILL.md", { source: "sdk" }),
 	disableModelInvocation: false,
 };
 

package/examples/sdk/08-prompt-templates.ts

@@ -6,6 +6,7 @@
 
 import {
 	createAgentSession,
+	createSyntheticSourceInfo,
 	DefaultResourceLoader,
 	type PromptTemplate,
 	SessionManager,
@@ -15,8 +16,8 @@ import {
 const deployTemplate: PromptTemplate = {
 	name: "deploy",
 	description: "Deploy the application",
-	source: "path",
-	filePath: "/virtual/commands/deploy.md",
+	filePath: "/virtual/prompts/deploy.md",
+	sourceInfo: createSyntheticSourceInfo("/virtual/prompts/deploy.md", { source: "sdk" }),
 	content: `# Deploy Instructions
 
 1. Build: npm run build
@@ -32,7 +33,7 @@ const loader = new DefaultResourceLoader({
 });
 await loader.reload();
 
-// Discover templates from cwd/.pi/commands/ and ~/.pi/agent/commands/
+// Discover templates from cwd/.pi/prompts/ and ~/.pi/agent/prompts/
 const discovered = loader.getPrompts().prompts;
 console.log("Discovered prompt templates:");
 for (const template of discovered) {

package/examples/sdk/09-api-keys-and-oauth.ts

@@ -8,8 +8,8 @@ import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "
 
 // Default: AuthStorage uses ~/.pi/agent/auth.json
 // ModelRegistry loads built-in + custom models from ~/.pi/agent/models.json
-const authStorage = new AuthStorage();
-const modelRegistry = new ModelRegistry(authStorage);
+const authStorage = AuthStorage.create();
+const modelRegistry = ModelRegistry.create(authStorage);
 
 await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
@@ -19,8 +19,8 @@ await createAgentSession({
 console.log("Session with default auth storage and model registry");
 
 // Custom auth storage location
-const customAuthStorage = new AuthStorage("/tmp/my-app/auth.json");
-const customModelRegistry = new ModelRegistry(customAuthStorage, "/tmp/my-app/models.json");
+const customAuthStorage = AuthStorage.create("/tmp/my-app/auth.json");
+const customModelRegistry = ModelRegistry.create(customAuthStorage, "/tmp/my-app/models.json");
 
 await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
@@ -39,7 +39,7 @@ await createAgentSession({
 console.log("Session with runtime API key override");
 
 // No models.json - only built-in models
-const simpleRegistry = new ModelRegistry(authStorage); // null = no models.json
+const simpleRegistry = ModelRegistry.inMemory(authStorage);
 await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
 	authStorage,

package/examples/sdk/10-settings.ts

@@ -24,6 +24,19 @@ await createAgentSession({
 
 console.log("Session created with custom settings");
 
+// Setters update memory immediately and queue persistence writes.
+// Call flush() when you need a durability boundary.
+settingsManager.setDefaultThinkingLevel("low");
+await settingsManager.flush();
+
+// Surface settings I/O errors at the app layer.
+const settingsErrors = settingsManager.drainErrors();
+if (settingsErrors.length > 0) {
+	for (const { scope, error } of settingsErrors) {
+		console.warn(`Warning (${scope} settings): ${error.message}`);
+	}
+}
+
 // For testing without file I/O:
 const inMemorySettings = SettingsManager.inMemory({
 	compaction: { enabled: false },

package/examples/sdk/12-full-control.ts

@@ -22,7 +22,7 @@ import {
 } from "@mariozechner/pi-coding-agent";
 
 // Custom auth storage location
-const authStorage = new AuthStorage("/tmp/my-agent/auth.json");
+const authStorage = AuthStorage.create("/tmp/my-agent/auth.json");
 
 // Runtime API key override (not persisted)
 if (process.env.MY_ANTHROPIC_KEY) {
@@ -30,7 +30,7 @@ if (process.env.MY_ANTHROPIC_KEY) {
 }
 
 // Model registry with no custom models.json
-const modelRegistry = new ModelRegistry(authStorage);
+const modelRegistry = ModelRegistry.inMemory(authStorage);
 
 const model = getModel("anthropic", "claude-sonnet-4-20250514");
 if (!model) throw new Error("Model not found");
@@ -53,7 +53,6 @@ const resourceLoader: ResourceLoader = {
 	getSystemPrompt: () => `You are a minimal assistant.
 Available: read, bash. Be concise.`,
 	getAppendSystemPrompt: () => [],
-	getPathMetadata: () => new Map(),
 	extendResources: () => {},
 	reload: async () => {},
 };

package/examples/sdk/13-session-runtime.ts

@@ -0,0 +1,67 @@
+/**
+ * Session runtime
+ *
+ * Use AgentSessionRuntime when you need to replace the active AgentSession,
+ * for example for new-session, resume, fork, or import flows.
+ *
+ * The important pattern is: after the runtime replaces the active session,
+ * rebind any session-local subscriptions and extension bindings to `runtime.session`.
+ */
+
+import {
+	type CreateAgentSessionRuntimeFactory,
+	createAgentSessionFromServices,
+	createAgentSessionRuntime,
+	createAgentSessionServices,
+	getAgentDir,
+	SessionManager,
+} from "@mariozechner/pi-coding-agent";
+
+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()),
+});
+
+let unsubscribe: (() => void) | undefined;
+
+async function bindSession() {
+	unsubscribe?.();
+	const session = runtime.session;
+	await session.bindExtensions({});
+	unsubscribe = session.subscribe((event) => {
+		if (event.type === "queue_update") {
+			console.log("Queued:", event.steering.length + event.followUp.length);
+		}
+	});
+	return session;
+}
+
+let session = await bindSession();
+const originalSessionFile = session.sessionFile;
+console.log("Initial session:", originalSessionFile);
+
+await runtime.newSession();
+session = await bindSession();
+console.log("After newSession():", session.sessionFile);
+
+if (originalSessionFile) {
+	await runtime.switchSession(originalSessionFile);
+	session = await bindSession();
+	console.log("After switchSession():", session.sessionFile);
+}
+
+unsubscribe?.();
+await runtime.dispose();

package/examples/sdk/README.md

@@ -1,6 +1,8 @@
 # SDK Examples
 
-Programmatic usage of pi-coding-agent via `createAgentSession()`.
+Programmatic usage of pi-coding-agent via `createAgentSession()` and `createAgentSessionRuntime()`.
+
+The runtime example shows how to build a recreate function that closes over process-global fixed inputs and recreates cwd-bound services and sessions as the active session cwd changes.
 
 ## Examples
 
@@ -18,6 +20,7 @@ Programmatic usage of pi-coding-agent via `createAgentSession()`.
 | `10-settings.ts` | Override compaction, retry, terminal settings |
 | `11-sessions.ts` | In-memory, persistent, continue, list sessions |
 | `12-full-control.ts` | Replace everything, no discovery |
+| `13-session-runtime.ts` | Manage runtime-backed session replacement |
 
 ## Running
 
@@ -43,8 +46,8 @@ import {
 } from "@mariozechner/pi-coding-agent";
 
 // Auth and models setup
-const authStorage = new AuthStorage();
-const modelRegistry = new ModelRegistry(authStorage);
+const authStorage = AuthStorage.create();
+const modelRegistry = ModelRegistry.create(authStorage);
 
 // Minimal
 const { session } = await createAgentSession({ authStorage, modelRegistry });
@@ -71,9 +74,9 @@ const { session } = await createAgentSession({
 });
 
 // Full control
-const customAuth = new AuthStorage("/my/app/auth.json");
+const customAuth = AuthStorage.create("/my/app/auth.json");
 customAuth.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
-const customRegistry = new ModelRegistry(customAuth);
+const customRegistry = ModelRegistry.create(customAuth);
 
 const resourceLoader = new DefaultResourceLoader({
   systemPromptOverride: () => "You are helpful.",
@@ -108,8 +111,8 @@ await session.prompt("Hello");
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `authStorage` | `new AuthStorage()` | Credential storage |
-| `modelRegistry` | `new ModelRegistry(authStorage)` | Model registry |
+| `authStorage` | `AuthStorage.create()` | Credential storage |
+| `modelRegistry` | `ModelRegistry.create(authStorage)` | Model registry |
 | `cwd` | `process.cwd()` | Working directory |
 | `agentDir` | `~/.pi/agent` | Config directory |
 | `model` | From settings/first available | Model to use |