@sammorrowdrums/mcpi 0.70.9 → 0.85.0-bootstrap.0

package/examples/sdk/03-custom-prompt.ts

@@ -15,7 +15,7 @@ const loader1 = new DefaultResourceLoader({
 	agentDir,
 	systemPromptOverride: () => `You are a helpful assistant that speaks like a pirate.
 Always end responses with "Arrr!"`,
-	// Needed to avoid DefaultResourceLoader appending APPEND_SYSTEM.md from ~/.pi/agent or <cwd>/.pi.
+	// Needed to avoid DefaultResourceLoader appending APPEND_SYSTEM.md from the mcpi config directory or <cwd>/.mcpi.
 	appendSystemPromptOverride: () => [],
 });
 await loader1.reload();
@@ -25,15 +25,19 @@ const { session: session1 } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
 });
 
-session1.subscribe((event) => {
-	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
-		process.stdout.write(event.assistantMessageEvent.delta);
-	}
-});
+try {
+	session1.subscribe((event) => {
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			process.stdout.write(event.assistantMessageEvent.delta);
+		}
+	});
 
-console.log("=== Replace prompt ===");
-await session1.prompt("What is 2 + 2?");
-console.log("\n");
+	console.log("=== Replace prompt ===");
+	await session1.prompt("What is 2 + 2?");
+	console.log("\n");
+} finally {
+	session1.dispose();
+}
 
 // Option 2: Append instructions to the default prompt
 const loader2 = new DefaultResourceLoader({
@@ -51,12 +55,16 @@ const { session: session2 } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
 });
 
-session2.subscribe((event) => {
-	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
-		process.stdout.write(event.assistantMessageEvent.delta);
-	}
-});
+try {
+	session2.subscribe((event) => {
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			process.stdout.write(event.assistantMessageEvent.delta);
+		}
+	});
 
-console.log("=== Modify prompt ===");
-await session2.prompt("List 3 benefits of TypeScript.");
-console.log();
+	console.log("=== Modify prompt ===");
+	await session2.prompt("List 3 benefits of TypeScript.");
+	console.log();
+} finally {
+	session2.dispose();
+}

package/examples/sdk/04-skills.ts

@@ -37,7 +37,7 @@ const loader = new DefaultResourceLoader({
 });
 await loader.reload();
 
-// Discover all skills from cwd/.pi/skills, ~/.pi/agent/skills, etc.
+// Discover all skills from cwd/.mcpi/skills, the mcpi config directory's skills/, etc.
 const { skills: allSkills, diagnostics } = loader.getSkills();
 console.log(
 	"Discovered skills:",
@@ -47,9 +47,9 @@ if (diagnostics.length > 0) {
 	console.log("Warnings:", diagnostics);
 }
 
-await createAgentSession({
+const { session } = await createAgentSession({
 	resourceLoader: loader,
 	sessionManager: SessionManager.inMemory(),
 });
-
 console.log("Session created with filtered skills");
+session.dispose();

package/examples/sdk/05-tools.ts

@@ -13,32 +13,36 @@
 import { createAgentSession, SessionManager } from "@sammorrowdrums/mcpi";
 
 // Read-only mode (no edit/write)
-await createAgentSession({
+const { session: readOnlySession } = await createAgentSession({
 	tools: ["read", "grep", "find", "ls"],
 	sessionManager: SessionManager.inMemory(),
 });
 console.log("Read-only session created");
+readOnlySession.dispose();
 
 // Custom tool selection
-await createAgentSession({
+const { session: customToolsSession } = await createAgentSession({
 	tools: ["read", "bash", "grep"],
 	sessionManager: SessionManager.inMemory(),
 });
 console.log("Custom tools session created");
+customToolsSession.dispose();
 
 // With custom cwd
 const customCwd = "/path/to/project";
-await createAgentSession({
+const { session: customCwdSession } = await createAgentSession({
 	cwd: customCwd,
 	tools: ["read", "bash", "edit", "write"],
 	sessionManager: SessionManager.inMemory(customCwd),
 });
 console.log("Custom cwd session created");
+customCwdSession.dispose();
 
 // Or pick specific tools for custom cwd
-await createAgentSession({
+const { session: specificToolsSession } = await createAgentSession({
 	cwd: customCwd,
 	tools: ["read", "bash", "grep"],
 	sessionManager: SessionManager.inMemory(customCwd),
 });
 console.log("Specific tools with custom cwd session created");
+specificToolsSession.dispose();

package/examples/sdk/06-extensions.ts

@@ -5,8 +5,8 @@
  * They provide a unified system for extensions, custom tools, commands, and more.
  *
  * By default, extension files are discovered from:
- * - ~/.pi/agent/extensions/
- * - <cwd>/.pi/extensions/
+ * - $XDG_CONFIG_HOME/mcpi/extensions/ (or the platform config fallback)
+ * - <cwd>/.mcpi/extensions/
  * - Paths specified in settings.json "extensions" array
  *
  * An extension is a TypeScript file that exports a default function:
@@ -37,14 +37,18 @@ const { session } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
 });
 
-session.subscribe((event) => {
-	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
-		process.stdout.write(event.assistantMessageEvent.delta);
-	}
-});
+try {
+	session.subscribe((event) => {
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			process.stdout.write(event.assistantMessageEvent.delta);
+		}
+	});
 
-await session.prompt("List files in the current directory.");
-console.log();
+	await session.prompt("List files in the current directory.");
+	console.log();
+} finally {
+	session.dispose();
+}
 
 // Example extension file (./my-logging-extension.ts):
 /*

package/examples/sdk/07-context-files.ts

@@ -34,9 +34,9 @@ for (const file of discovered) {
 	console.log(`  - ${file.path} (${file.content.length} chars)`);
 }
 
-await createAgentSession({
+const { session } = await createAgentSession({
 	resourceLoader: loader,
 	sessionManager: SessionManager.inMemory(),
 });
-
 console.log(`Session created with ${discovered.length + 1} context files`);
+session.dispose();

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

@@ -36,16 +36,16 @@ const loader = new DefaultResourceLoader({
 });
 await loader.reload();
 
-// Discover templates from cwd/.pi/prompts/ and ~/.pi/agent/prompts/
+// Discover templates from cwd/.mcpi/prompts/ and the mcpi config directory's prompts/
 const discovered = loader.getPrompts().prompts;
 console.log("Discovered prompt templates:");
 for (const template of discovered) {
 	console.log(`  /${template.name}: ${template.description}`);
 }
 
-await createAgentSession({
+const { session } = await createAgentSession({
 	resourceLoader: loader,
 	sessionManager: SessionManager.inMemory(),
 });
-
 console.log(`Session created with ${discovered.length + 1} prompt templates`);
+session.dispose();

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

@@ -1,48 +1,34 @@
 /**
  * API Keys and OAuth
  *
- * Configure API key resolution via AuthStorage and ModelRegistry.
+ * Configure provider auth through ModelRuntime.
  */
 
-import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@sammorrowdrums/mcpi";
+import { createAgentSession, ModelRuntime, SessionManager } from "@sammorrowdrums/mcpi";
 
-// Default: AuthStorage uses ~/.pi/agent/auth.json
-// ModelRegistry loads built-in + custom models from ~/.pi/agent/models.json
-const authStorage = AuthStorage.create();
-const modelRegistry = ModelRegistry.create(authStorage);
-
-await createAgentSession({
+const modelRuntime = await ModelRuntime.create();
+const { session: defaultAuthSession } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
-	authStorage,
-	modelRegistry,
+	modelRuntime,
 });
-console.log("Session with default auth storage and model registry");
-
-// Custom auth storage location
-const customAuthStorage = AuthStorage.create("/tmp/my-app/auth.json");
-const customModelRegistry = ModelRegistry.create(customAuthStorage, "/tmp/my-app/models.json");
+console.log("Session with default model runtime");
+defaultAuthSession.dispose();
 
-await createAgentSession({
-	sessionManager: SessionManager.inMemory(),
-	authStorage: customAuthStorage,
-	modelRegistry: customModelRegistry,
+const customRuntime = await ModelRuntime.create({
+	authPath: "/tmp/my-app/auth.json",
+	modelsPath: "/tmp/my-app/models.json",
 });
-console.log("Session with custom auth storage location");
-
-// Runtime API key override (not persisted to disk)
-authStorage.setRuntimeApiKey("anthropic", "sk-my-temp-key");
-await createAgentSession({
+const { session: customAuthSession } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
-	authStorage,
-	modelRegistry,
+	modelRuntime: customRuntime,
 });
-console.log("Session with runtime API key override");
+console.log("Session with custom auth and models locations");
+customAuthSession.dispose();
 
-// No models.json - only built-in models
-const simpleRegistry = ModelRegistry.inMemory(authStorage);
-await createAgentSession({
+await modelRuntime.setRuntimeApiKey("anthropic", "sk-my-temp-key");
+const { session: runtimeKeySession } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
-	authStorage,
-	modelRegistry: simpleRegistry,
+	modelRuntime,
 });
-console.log("Session with only built-in models");
+console.log("Session with runtime API key override");
+runtimeKeySession.dispose();

package/examples/sdk/10-settings.ts

@@ -19,12 +19,12 @@ settingsManager.applyOverrides({
 	retry: { enabled: true, maxRetries: 5, baseDelayMs: 1000 },
 });
 
-await createAgentSession({
+const { session: customSettingsSession } = await createAgentSession({
 	settingsManager,
 	sessionManager: SessionManager.inMemory(),
 });
-
 console.log("Session created with custom settings");
+customSettingsSession.dispose();
 
 // Setters update memory immediately and queue persistence writes.
 // Call flush() when you need a durability boundary.
@@ -45,9 +45,9 @@ const inMemorySettings = SettingsManager.inMemory({
 	retry: { enabled: false },
 });
 
-await createAgentSession({
+const { session: testSession } = await createAgentSession({
 	settingsManager: inMemorySettings,
 	sessionManager: SessionManager.inMemory(),
 });
-
 console.log("Test session created with in-memory settings");
+testSession.dispose();

package/examples/sdk/11-sessions.ts

@@ -11,12 +11,14 @@ const { session: inMemory } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
 });
 console.log("In-memory session:", inMemory.sessionFile ?? "(none)");
+inMemory.dispose();
 
 // New persistent session
 const { session: newSession } = await createAgentSession({
 	sessionManager: SessionManager.create(process.cwd()),
 });
 console.log("New session file:", newSession.sessionFile);
+newSession.dispose();
 
 // Continue most recent session (or create new if none)
 const { session: continued, modelFallbackMessage } = await createAgentSession({
@@ -24,6 +26,7 @@ const { session: continued, modelFallbackMessage } = await createAgentSession({
 });
 if (modelFallbackMessage) console.log("Note:", modelFallbackMessage);
 console.log("Continued session:", continued.sessionFile);
+continued.dispose();
 
 // List and open specific session
 const sessions = await SessionManager.list(process.cwd());
@@ -37,6 +40,7 @@ if (sessions.length > 0) {
 		sessionManager: SessionManager.open(sessions[0].path),
 	});
 	console.log(`\nOpened: ${opened.sessionId}`);
+	opened.dispose();
 }
 
 // Custom session directory (no cwd encoding)

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

@@ -5,28 +5,24 @@
  */
 
 import {
-	AuthStorage,
 	createAgentSession,
 	createExtensionRuntime,
-	ModelRegistry,
+	ModelRuntime,
 	type ResourceLoader,
 	SessionManager,
 	SettingsManager,
 } from "@sammorrowdrums/mcpi";
-import { getModel } from "@sammorrowdrums/mcpi-ai";
+import { getModel } from "@sammorrowdrums/mcpi-ai/compat";
 
-// Custom auth storage location
-const authStorage = AuthStorage.create("/tmp/my-agent/auth.json");
-
-// Runtime API key override (not persisted)
+const modelRuntime = await ModelRuntime.create({
+	authPath: "/tmp/my-agent/auth.json",
+	modelsPath: "/tmp/my-agent/models.json",
+});
 if (process.env.MY_ANTHROPIC_KEY) {
-	authStorage.setRuntimeApiKey("anthropic", process.env.MY_ANTHROPIC_KEY);
+	await modelRuntime.setRuntimeApiKey("anthropic", process.env.MY_ANTHROPIC_KEY);
 }
 
-// Model registry with no custom models.json
-const modelRegistry = ModelRegistry.inMemory(authStorage);
-
-const model = getModel("anthropic", "claude-sonnet-4-20250514");
+const model = getModel("anthropic", "claude-sonnet-4-5");
 if (!model) throw new Error("Model not found");
 
 // In-memory settings with overrides
@@ -45,7 +41,9 @@ const resourceLoader: ResourceLoader = {
 	getAgentsFiles: () => ({ agentsFiles: [] }),
 	getSystemPrompt: () => `You are a minimal assistant.
 Available: read, bash. Be concise.`,
+	getSystemPromptSource: () => undefined,
 	getAppendSystemPrompt: () => [],
+	getAppendSystemPromptSources: () => [],
 	extendResources: () => {},
 	reload: async () => {},
 };
@@ -55,19 +53,22 @@ const { session } = await createAgentSession({
 	agentDir: "/tmp/my-agent",
 	model,
 	thinkingLevel: "off",
-	authStorage,
-	modelRegistry,
+	modelRuntime,
 	resourceLoader,
 	tools: ["read", "bash"],
 	sessionManager: SessionManager.inMemory(cwd),
 	settingsManager,
 });
 
-session.subscribe((event) => {
-	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
-		process.stdout.write(event.assistantMessageEvent.delta);
-	}
-});
+try {
+	session.subscribe((event) => {
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			process.stdout.write(event.assistantMessageEvent.delta);
+		}
+	});
 
-await session.prompt("List files in the current directory.");
-console.log();
+	await session.prompt("List files in the current directory.");
+	console.log();
+} finally {
+	session.dispose();
+}

package/examples/sdk/README.md

@@ -1,6 +1,6 @@
 # SDK Examples
 
-Programmatic usage of pi-coding-agent via `createAgentSession()` and `createAgentSessionRuntime()`.
+Programmatic usage of mcpi 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.
 
@@ -12,7 +12,7 @@ The runtime example shows how to build a recreate function that closes over proc
 | `02-custom-model.ts` | Select model and thinking level |
 | `03-custom-prompt.ts` | Replace or modify system prompt |
 | `04-skills.ts` | Discover, filter, or replace skills |
-| `05-tools.ts` | Built-in tools, custom tools |
+| `05-tools.ts` | Built-in tool allowlists |
 | `06-extensions.ts` | Logging, blocking, result modification |
 | `07-context-files.ts` | AGENTS.md context files |
 | `08-slash-commands.ts` | File-based slash commands |
@@ -32,51 +32,46 @@ npx tsx examples/sdk/01-minimal.ts
 ## Quick Reference
 
 ```typescript
-import { getModel } from "@mariozechner/pi-ai";
+import { getModel } from "@sammorrowdrums/mcpi-ai";
 import {
-  AuthStorage,
   createAgentSession,
   DefaultResourceLoader,
-  ModelRegistry,
+  ModelRuntime,
   SessionManager,
   SettingsManager,
-  codingTools,
-  readOnlyTools,
-  readTool, bashTool, editTool, writeTool,
-} from "@mariozechner/pi-coding-agent";
+} from "@sammorrowdrums/mcpi";
 
-// Auth and models setup
-const authStorage = AuthStorage.create();
-const modelRegistry = ModelRegistry.create(authStorage);
+const modelRuntime = await ModelRuntime.create();
 
 // Minimal
-const { session } = await createAgentSession({ authStorage, modelRegistry });
+const { session } = await createAgentSession({ modelRuntime });
 
 // Custom model
 const model = getModel("anthropic", "claude-opus-4-5");
-const { session } = await createAgentSession({ model, thinkingLevel: "high", authStorage, modelRegistry });
+const { session } = await createAgentSession({ model, thinkingLevel: "high", modelRuntime });
 
 // Modify prompt
 const loader = new DefaultResourceLoader({
   systemPromptOverride: (base) => `${base}\n\nBe concise.`,
 });
 await loader.reload();
-const { session } = await createAgentSession({ resourceLoader: loader, authStorage, modelRegistry });
+const { session } = await createAgentSession({ resourceLoader: loader, modelRuntime });
 
 // Read-only
-const { session } = await createAgentSession({ tools: readOnlyTools, authStorage, modelRegistry });
+const { session } = await createAgentSession({ tools: ["read", "grep", "find", "ls"], modelRuntime });
 
 // In-memory
 const { session } = await createAgentSession({
   sessionManager: SessionManager.inMemory(),
-  authStorage,
-  modelRegistry,
+  modelRuntime,
 });
 
 // Full control
-const customAuth = AuthStorage.create("/my/app/auth.json");
-customAuth.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
-const customRegistry = ModelRegistry.create(customAuth);
+const customRuntime = await ModelRuntime.create({
+  authPath: "/my/app/auth.json",
+  modelsPath: "/my/app/models.json",
+});
+await customRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
 
 const resourceLoader = new DefaultResourceLoader({
   systemPromptOverride: () => "You are helpful.",
@@ -89,11 +84,10 @@ await resourceLoader.reload();
 
 const { session } = await createAgentSession({
   model,
-  authStorage: customAuth,
-  modelRegistry: customRegistry,
+  modelRuntime: customRuntime,
   resourceLoader,
-  tools: [readTool, bashTool],
-  customTools: [{ tool: myTool }],
+  tools: ["read", "bash", "my_tool"],
+  customTools: [myTool],
   sessionManager: SessionManager.inMemory(),
   settingsManager: SettingsManager.inMemory(),
 });
@@ -111,15 +105,14 @@ await session.prompt("Hello");
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `authStorage` | `AuthStorage.create()` | Credential storage |
-| `modelRegistry` | `ModelRegistry.create(authStorage)` | Model registry |
+| `modelRuntime` | Runtime using `agentDir/auth.json` and `models.json` | Canonical model and authentication runtime |
 | `cwd` | `process.cwd()` | Working directory |
-| `agentDir` | `~/.pi/agent` | Config directory |
+| `agentDir` | Platform mcpi config directory | Config directory |
 | `model` | From settings/first available | Model to use |
 | `thinkingLevel` | From settings/"off" | off, low, medium, high |
-| `tools` | `codingTools` | Built-in tools |
+| `tools` | `["read", "bash", "edit", "write"]` built-ins | Allowlist tool names across built-in, extension, and custom tools |
 | `customTools` | `[]` | Additional tool definitions |
-| `resourceLoader` | DefaultResourceLoader | Resource loader for extensions, skills, prompts, themes |
+| `resourceLoader` | DefaultResourceLoader | Resource loader for extensions, skills, prompts, themes, and context files |
 | `sessionManager` | `SessionManager.create(cwd)` | Persistence |
 | `settingsManager` | `SettingsManager.create(cwd, agentDir)` | Settings overrides |