@earendil-works/pi-coding-agent 0.80.7 → 0.80.9

package/docs/sdk.md

@@ -16,16 +16,12 @@ See [examples/sdk/](../examples/sdk/) for working examples from minimal to full
 ## Quick Start
 
 ```typescript
-import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@earendil-works/pi-coding-agent";
-
-// Set up credential storage and model registry
-const authStorage = AuthStorage.create();
-const modelRegistry = ModelRegistry.create(authStorage);
+import { createAgentSession, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
 
+const modelRuntime = await ModelRuntime.create();
 const { session } = await createAgentSession({
   sessionManager: SessionManager.inMemory(),
-  authStorage,
-  modelRegistry,
+  modelRuntime,
 });
 
 session.subscribe((event) => {
@@ -369,10 +365,9 @@ When you pass a custom `ResourceLoader`, `cwd` and `agentDir` no longer control
 
 ```typescript
 import { getModel } from "@earendil-works/pi-ai";
-import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 
-const authStorage = AuthStorage.create();
-const modelRegistry = ModelRegistry.create(authStorage);
+const modelRuntime = await ModelRuntime.create();
 
 // Find specific built-in model (doesn't check if API key exists)
 const opus = getModel("anthropic", "claude-opus-4-5");
@@ -380,10 +375,10 @@ 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 = modelRegistry.find("my-provider", "my-model");
+const customModel = modelRuntime.getModel("my-provider", "my-model");
 
-// Get only models that have valid API keys configured
-const available = await modelRegistry.getAvailable();
+// Get only models that have valid authentication configured
+const available = await modelRuntime.getAvailable();
 
 const { session } = await createAgentSession({
   model: opus,
@@ -395,8 +390,7 @@ const { session } = await createAgentSession({
     { model: haiku, thinkingLevel: "off" },
   ],
   
-  authStorage,
-  modelRegistry,
+  modelRuntime,
 });
 ```
 
@@ -415,14 +409,14 @@ import {
 
 const cliModel = resolveCliModel({
   cliModel: "anthropic/claude-opus-4-5:high",
-  modelRegistry,
+  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"],
-  modelRegistry,
+  modelRuntime,
 );
 for (const diagnostic of diagnostics) {
   console.warn(diagnostic.message);
@@ -435,40 +429,41 @@ for (const diagnostic of diagnostics) {
 
 ### API Keys and OAuth
 
-API key resolution priority (handled by AuthStorage):
+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 { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { InMemoryCredentialStore } from "@earendil-works/pi-ai";
+import { createAgentSession, ModelRuntime } from "@earendil-works/pi-coding-agent";
 
 // Default: uses ~/.pi/agent/auth.json and ~/.pi/agent/models.json
-const authStorage = AuthStorage.create();
-const modelRegistry = ModelRegistry.create(authStorage);
+const modelRuntime = await ModelRuntime.create();
 
-const { session } = await createAgentSession({
-  sessionManager: SessionManager.inMemory(),
-  authStorage,
-  modelRegistry,
-});
+// 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)
-authStorage.setRuntimeApiKey("anthropic", "sk-my-temp-key");
+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",
+});
 
-// Custom auth storage location
-const customAuth = AuthStorage.create("/my/app/auth.json");
-const customRegistry = ModelRegistry.create(customAuth, "/my/app/models.json");
+// Or inject any pi-ai CredentialStore
+const credentials = new InMemoryCredentialStore();
+const inMemoryRuntime = await ModelRuntime.create({ credentials });
 
 const { session } = await createAgentSession({
-  sessionManager: SessionManager.inMemory(),
-  authStorage: customAuth,
-  modelRegistry: customRegistry,
+  modelRuntime: customRuntime,
 });
-
-// No custom models.json (built-in models only)
-const simpleRegistry = ModelRegistry.inMemory(authStorage);
 ```
 
 > See [examples/sdk/09-api-keys-and-oauth.ts](../examples/sdk/09-api-keys-and-oauth.ts)
@@ -927,26 +922,22 @@ interface LoadExtensionsResult {
 import { getModel } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import {
-  AuthStorage,
   createAgentSession,
   DefaultResourceLoader,
   defineTool,
-  ModelRegistry,
+  ModelRuntime,
   SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 
-// Set up auth storage (custom location)
-const authStorage = AuthStorage.create("/custom/agent/auth.json");
-
-// Runtime API key override (not persisted)
+const modelRuntime = await ModelRuntime.create({
+  authPath: "/custom/agent/auth.json",
+  modelsPath: "/custom/agent/models.json",
+});
 if (process.env.MY_KEY) {
-  authStorage.setRuntimeApiKey("anthropic", process.env.MY_KEY);
+  modelRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY);
 }
 
-// Model registry (no custom models.json)
-const modelRegistry = ModelRegistry.create(authStorage);
-
 // Inline tool
 const statusTool = defineTool({
   name: "status",
@@ -982,8 +973,7 @@ const { session } = await createAgentSession({
 
   model,
   thinkingLevel: "off",
-  authStorage,
-  modelRegistry,
+  modelRuntime,
 
   tools: ["read", "bash", "status"],
   customTools: [statusTool],
@@ -1149,8 +1139,8 @@ createAgentSessionRuntime
 AgentSessionRuntime
 
 // Auth and Models
-AuthStorage
-ModelRegistry
+ModelRuntime // implements pi-ai Models and owns credential storage
+ModelRegistry // synchronous extension compatibility facade
 resolveCliModel
 resolveModelScopeWithDiagnostics
 

package/docs/usage.md

@@ -151,6 +151,7 @@ pi uninstall <source> [-l]   # Alias for remove
 pi update [source|self|pi]   # Update pi only, or one package source
 pi update --all              # Update pi and packages; reconcile pinned git refs
 pi update --extensions       # Update packages only; reconcile pinned git refs
+pi update --models           # Refresh model catalogs only
 pi update --self             # Update pi only
 pi update --extension <src>  # Update one package
 pi list                      # List installed packages

package/examples/extensions/README.md

@@ -36,6 +36,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 | `questionnaire.ts` | Multi-question input with tab bar navigation between questions |
 | `tool-override.ts` | Override built-in tools (e.g., add logging/access control to `read`) |
 | `dynamic-tools.ts` | Register tools after startup (`session_start`) and at runtime via command, with prompt snippets and tool-specific prompt guidelines |
+| `kimi-deferred-tools.ts` | Search for and progressively activate tools for Kimi's deferred-tool loading protocol |
 | `structured-output.ts` | Final structured-output tool that returns `terminate: true` so the agent can end on the tool call |
 | `built-in-tool-renderer.ts` | Custom compact rendering for built-in tools (read, bash, edit, write) while keeping original behavior |
 | `minimal-mode.ts` | Override built-in tool rendering for minimal display (only tool calls, no output in collapsed mode) |

package/examples/extensions/custom-provider-anthropic/index.ts

@@ -46,7 +46,7 @@ import {
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 // =============================================================================
-// OAuth Implementation (copied from packages/ai/src/utils/oauth/anthropic.ts)
+// OAuth implementation adapted for the legacy extension compatibility interface.
 // =============================================================================
 
 const decode = (s: string) => atob(s);

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.80.7",
+  "version": "0.80.9",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.80.7",
+      "version": "0.80.9",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "0.80.7",
+  "version": "0.80.9",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "0.80.7",
+  "version": "0.80.9",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/gondolin/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-gondolin",
-	"version": "0.80.7",
+	"version": "0.80.9",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-gondolin",
-			"version": "0.80.7",
+			"version": "0.80.9",
 			"dependencies": {
 				"@earendil-works/gondolin": "0.12.0"
 			}

package/examples/extensions/gondolin/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-gondolin",
 	"private": true,
-	"version": "0.80.7",
+	"version": "0.80.9",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/kimi-deferred-tools.ts

@@ -0,0 +1,61 @@
+/**
+ * Minimal Kimi deferred-tool loading demo.
+ *
+ *   pi -e ./kimi-deferred-tools.ts
+ *    example prompt: Use the available tools to calculate 100 + 500. Do not calculate it yourself.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+function calculate(_expr: string): string {
+	return "42";
+}
+
+export default function (pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "Calculator",
+		label: "Calculator",
+		description: "Evaluate a simple arithmetic expression.",
+		parameters: Type.Object({
+			expr: Type.String({ description: "An expression such as 100 + 500" }),
+		}),
+		async execute(_toolCallId, params) {
+			return {
+				content: [{ type: "text", text: calculate(params.expr) }],
+				details: {},
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "tool_search",
+		label: "Tool Search",
+		description: "Find and activate tools for a capability.",
+		promptSnippet: "Search for additional tools when the active tools cannot perform the task",
+		parameters: Type.Object({
+			query: Type.String({ description: "Capability to search for" }),
+		}),
+		async execute(_toolCallId, params) {
+			if (!params.query.toLowerCase().includes("calc")) {
+				return {
+					content: [{ type: "text", text: "The relevant tools do not exist." }],
+					details: { matches: [], added: [] },
+				};
+			}
+
+			const active = pi.getActiveTools();
+			const added = active.includes("Calculator") ? [] : ["Calculator"];
+			if (added.length > 0) pi.setActiveTools([...active, ...added]);
+
+			return {
+				content: [{ type: "text", text: "Success. Found 1 matching tool(s)" }],
+				details: { matches: ["Calculator"], added },
+			};
+		},
+	});
+
+	pi.on("session_start", () => {
+		pi.setActiveTools(["tool_search"]);
+	});
+}

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-sandbox",
-	"version": "1.10.7",
+	"version": "1.10.9",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-sandbox",
-			"version": "1.10.7",
+			"version": "1.10.9",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "^0.0.26"
 			}

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-sandbox",
 	"private": true,
-	"version": "1.10.7",
+	"version": "1.10.9",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

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

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

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

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

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

@@ -5,11 +5,9 @@
  */
 
 import { getModel } from "@earendil-works/pi-ai/compat";
-import { AuthStorage, createAgentSession, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, ModelRuntime } from "@earendil-works/pi-coding-agent";
 
-// Set up auth storage and model registry
-const authStorage = AuthStorage.create();
-const modelRegistry = ModelRegistry.create(authStorage);
+const modelRuntime = await ModelRuntime.create();
 
 // Option 1: Find a specific built-in model by provider/id
 const opus = getModel("anthropic", "claude-opus-4-5");
@@ -18,13 +16,13 @@ if (opus) {
 }
 
 // Option 2: Find model via registry (includes custom models from models.json)
-const customModel = modelRegistry.find("my-provider", "my-model");
+const customModel = modelRuntime.getModel("my-provider", "my-model");
 if (customModel) {
 	console.log(`Found custom model: ${customModel.provider}/${customModel.id}`);
 }
 
 // Option 3: Pick from available models (have valid API keys)
-const available = await modelRegistry.getAvailable();
+const available = await modelRuntime.getAvailable();
 console.log(
 	"Available models:",
 	available.map((m) => `${m.provider}/${m.id}`),
@@ -34,8 +32,7 @@ if (available.length > 0) {
 	const { session } = await createAgentSession({
 		model: available[0],
 		thinkingLevel: "medium", // off, low, medium, high
-		authStorage,
-		modelRegistry,
+		modelRuntime,
 	});
 
 	try {

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

@@ -1,52 +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 "@earendil-works/pi-coding-agent";
-
-// 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);
+import { createAgentSession, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
 
+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");
+console.log("Session with default model runtime");
 defaultAuthSession.dispose();
 
-// Custom auth storage location
-const customAuthStorage = AuthStorage.create("/tmp/my-app/auth.json");
-const customModelRegistry = ModelRegistry.create(customAuthStorage, "/tmp/my-app/models.json");
-
+const customRuntime = await ModelRuntime.create({
+	authPath: "/tmp/my-app/auth.json",
+	modelsPath: "/tmp/my-app/models.json",
+});
 const { session: customAuthSession } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
-	authStorage: customAuthStorage,
-	modelRegistry: customModelRegistry,
+	modelRuntime: customRuntime,
 });
-console.log("Session with custom auth storage location");
+console.log("Session with custom auth and models locations");
 customAuthSession.dispose();
 
-// Runtime API key override (not persisted to disk)
-authStorage.setRuntimeApiKey("anthropic", "sk-my-temp-key");
+modelRuntime.setRuntimeApiKey("anthropic", "sk-my-temp-key");
 const { session: runtimeKeySession } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
-	authStorage,
-	modelRegistry,
+	modelRuntime,
 });
 console.log("Session with runtime API key override");
 runtimeKeySession.dispose();
-
-// No models.json - only built-in models
-const simpleRegistry = ModelRegistry.inMemory(authStorage);
-const { session: builtInModelsSession } = await createAgentSession({
-	sessionManager: SessionManager.inMemory(),
-	authStorage,
-	modelRegistry: simpleRegistry,
-});
-console.log("Session with only built-in models");
-builtInModelsSession.dispose();

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

@@ -6,26 +6,22 @@
 
 import { getModel } from "@earendil-works/pi-ai/compat";
 import {
-	AuthStorage,
 	createAgentSession,
 	createExtensionRuntime,
-	ModelRegistry,
+	ModelRuntime,
 	type ResourceLoader,
 	SessionManager,
 	SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 
-// 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);
+	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-5");
 if (!model) throw new Error("Model not found");
 
@@ -55,8 +51,7 @@ const { session } = await createAgentSession({
 	agentDir: "/tmp/my-agent",
 	model,
 	thinkingLevel: "off",
-	authStorage,
-	modelRegistry,
+	modelRuntime,
 	resourceLoader,
 	tools: ["read", "bash"],
 	sessionManager: SessionManager.inMemory(cwd),

package/examples/sdk/README.md

@@ -34,46 +34,44 @@ npx tsx examples/sdk/01-minimal.ts
 ```typescript
 import { getModel } from "@earendil-works/pi-ai";
 import {
-  AuthStorage,
   createAgentSession,
   DefaultResourceLoader,
-  ModelRegistry,
+  ModelRuntime,
   SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 
-// 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: ["read", "grep", "find", "ls"], 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",
+});
+customRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
 
 const resourceLoader = new DefaultResourceLoader({
   systemPromptOverride: () => "You are helpful.",
@@ -86,8 +84,7 @@ await resourceLoader.reload();
 
 const { session } = await createAgentSession({
   model,
-  authStorage: customAuth,
-  modelRegistry: customRegistry,
+  modelRuntime: customRuntime,
   resourceLoader,
   tools: ["read", "bash", "my_tool"],
   customTools: [myTool],
@@ -108,8 +105,7 @@ 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 |
 | `model` | From settings/first available | Model to use |