@mariozechner/pi-coding-agent 0.27.9 → 0.29.0

package/docs/custom-tools.md

@@ -186,7 +186,7 @@ interface ToolSessionEvent {
   entries: SessionEntry[];      // All session entries
   sessionFile: string | null;   // Current session file
   previousSessionFile: string | null;  // Previous session file
-  reason: "start" | "switch" | "branch" | "clear";
+  reason: "start" | "switch" | "branch" | "new";
 }
 ```
 
@@ -194,7 +194,7 @@ interface ToolSessionEvent {
 - `start`: Initial session load on startup
 - `switch`: User switched to a different session (`/resume`)
 - `branch`: User branched from a previous message (`/branch`)
-- `clear`: User cleared the session (`/clear`)
+- `new`: User started a new session (`/new`)
 
 ### State Management Pattern
 
@@ -250,7 +250,7 @@ const factory: CustomToolFactory = (pi) => {
 This pattern ensures:
 - When user branches, state is correct for that point in history
 - When user switches sessions, state matches that session
-- When user clears, state resets
+- When user starts a new session, state resets
 
 ## Custom Rendering
 

package/docs/hooks.md

@@ -125,10 +125,10 @@ user switches session (/resume)
   ├─► session (reason: "before_switch", can cancel)
   └─► session (reason: "switch", AFTER switch)
 
-user clears session (/clear)
+user starts new session (/new)
   │
-  ├─► session (reason: "before_clear", can cancel)
-  └─► session (reason: "clear", AFTER clear)
+  ├─► session (reason: "before_new", can cancel)
+  └─► session (reason: "new", AFTER new session starts)
 
 context compaction (auto or /compact)
   │
@@ -151,12 +151,12 @@ pi.on("session", async (event, ctx) => {
   // event.entries: SessionEntry[] - all session entries
   // event.sessionFile: string | null - current session file (null with --no-session)
   // event.previousSessionFile: string | null - previous session file
-  // event.reason: "start" | "before_switch" | "switch" | "before_clear" | "clear" |
+  // event.reason: "start" | "before_switch" | "switch" | "before_new" | "new" |
   //               "before_branch" | "branch" | "before_compact" | "compact" | "shutdown"
   // event.targetTurnIndex: number - only for "before_branch" and "branch"
 
   // Cancel a before_* action:
-  if (event.reason === "before_clear") {
+  if (event.reason === "before_new") {
     return { cancel: true };
   }
 
@@ -171,7 +171,7 @@ pi.on("session", async (event, ctx) => {
 **Reasons:**
 - `start`: Initial session load on startup
 - `before_switch` / `switch`: User switched sessions (`/resume`)
-- `before_clear` / `clear`: User cleared the session (`/clear`)
+- `before_new` / `new`: User started a new session (`/new`)
 - `before_branch` / `branch`: User branched the session (`/branch`)
 - `before_compact` / `compact`: Context compaction (auto or `/compact`)
 - `shutdown`: Process is exiting (double Ctrl+C, Ctrl+D, or SIGTERM)
@@ -848,9 +848,9 @@ Session switch:
 
 Clear:
   -> AgentSession.reset()
-     -> hookRunner.emit({ type: "session", reason: "before_clear", ... })  # can cancel
-     -> [if not cancelled: clear happens]
-     -> hookRunner.emit({ type: "session", reason: "clear", ... })
+     -> hookRunner.emit({ type: "session", reason: "before_new", ... })  # can cancel
+     -> [if not cancelled: new session starts]
+     -> hookRunner.emit({ type: "session", reason: "new", ... })
 
 Shutdown (interactive mode):
   -> handleCtrlC() or handleCtrlD()

package/docs/sdk.md

@@ -14,10 +14,16 @@ See [examples/sdk/](../examples/sdk/) for working examples from minimal to full
 ## Quick Start
 
 ```typescript
-import { createAgentSession, SessionManager } from "@mariozechner/pi-coding-agent";
+import { createAgentSession, discoverAuthStorage, discoverModels, SessionManager } from "@mariozechner/pi-coding-agent";
+
+// Set up credential storage and model registry
+const authStorage = discoverAuthStorage();
+const modelRegistry = discoverModels(authStorage);
 
 const { session } = await createAgentSession({
   sessionManager: SessionManager.inMemory(),
+  authStorage,
+  modelRegistry,
 });
 
 session.subscribe((event) => {
@@ -220,32 +226,42 @@ const { session } = await createAgentSession({
 - Global commands (`commands/`)
 - Global context file (`AGENTS.md`)
 - Settings (`settings.json`)
-- Models (`models.json`)
-- OAuth tokens (`oauth.json`)
+- Custom models (`models.json`)
+- Credentials (`auth.json`)
 - Sessions (`sessions/`)
 
 ### Model
 
 ```typescript
-import { findModel, discoverAvailableModels } from "@mariozechner/pi-coding-agent";
+import { getModel } from "@mariozechner/pi-ai";
+import { discoverAuthStorage, discoverModels } from "@mariozechner/pi-coding-agent";
 
-// Find specific model (returns { model, error })
-const { model, error } = findModel("anthropic", "claude-sonnet-4-20250514");
-if (error) throw new Error(error);
-if (!model) throw new Error("Model not found");
+const authStorage = discoverAuthStorage();
+const modelRegistry = discoverModels(authStorage);
 
-// Or get all models with valid API keys
-const available = await discoverAvailableModels();
+// 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 = modelRegistry.find("my-provider", "my-model");
+
+// Get only models that have valid API keys configured
+const available = await modelRegistry.getAvailable();
 
 const { session } = await createAgentSession({
-  model: model,
+  model: opus,
   thinkingLevel: "medium", // off, minimal, low, medium, high, xhigh
   
   // Models for cycling (Ctrl+P in interactive mode)
   scopedModels: [
-    { model: sonnet, thinkingLevel: "high" },
+    { model: opus, thinkingLevel: "high" },
     { model: haiku, thinkingLevel: "off" },
   ],
+  
+  authStorage,
+  modelRegistry,
 });
 ```
 
@@ -256,38 +272,42 @@ If no model is provided:
 
 > See [examples/sdk/02-custom-model.ts](../examples/sdk/02-custom-model.ts)
 
-### API Keys
+### API Keys and OAuth
 
-API key resolution priority:
-1. `settings.json` apiKeys (e.g., `{ "apiKeys": { "anthropic": "sk-..." } }`)
-2. Custom providers from `models.json`
-3. OAuth credentials from `oauth.json`
-4. Environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)
+API key resolution priority (handled by AuthStorage):
+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 { defaultGetApiKey, configureOAuthStorage } from "@mariozechner/pi-coding-agent";
+import { AuthStorage, ModelRegistry, discoverAuthStorage, discoverModels } from "@mariozechner/pi-coding-agent";
 
-// Default: checks settings.json, models.json, OAuth, environment variables
-const { session } = await createAgentSession();
+// Default: uses ~/.pi/agent/auth.json and ~/.pi/agent/models.json
+const authStorage = discoverAuthStorage();
+const modelRegistry = discoverModels(authStorage);
 
-// Custom resolver
 const { session } = await createAgentSession({
-  getApiKey: async (model) => {
-    // Custom logic (secrets manager, database, etc.)
-    if (model.provider === "anthropic") {
-      return process.env.MY_ANTHROPIC_KEY;
-    }
-    // Fall back to default (pass settingsManager for settings.json lookup)
-    return defaultGetApiKey()(model);
-  },
+  sessionManager: SessionManager.inMemory(),
+  authStorage,
+  modelRegistry,
 });
 
-// Use OAuth from ~/.pi/agent with custom agentDir for everything else
-configureOAuthStorage(); // Must call before createAgentSession
+// Runtime API key override (not persisted to disk)
+authStorage.setRuntimeApiKey("anthropic", "sk-my-temp-key");
+
+// Custom auth storage location
+const customAuth = new AuthStorage("/my/app/auth.json");
+const customRegistry = new ModelRegistry(customAuth, "/my/app/models.json");
+
 const { session } = await createAgentSession({
-  agentDir: "/custom/config",
-  // OAuth tokens still come from ~/.pi/agent/oauth.json
+  sessionManager: SessionManager.inMemory(),
+  authStorage: customAuth,
+  modelRegistry: customRegistry,
 });
+
+// No custom models.json (built-in models only)
+const simpleRegistry = new ModelRegistry(authStorage);
 ```
 
 > See [examples/sdk/09-api-keys-and-oauth.ts](../examples/sdk/09-api-keys-and-oauth.ts)
@@ -630,10 +650,12 @@ Project overrides global. Nested objects merge keys. Setters only modify global
 All discovery functions accept optional `cwd` and `agentDir` parameters.
 
 ```typescript
+import { getModel } from "@mariozechner/pi-ai";
 import {
+  AuthStorage,
+  ModelRegistry,
+  discoverAuthStorage,
   discoverModels,
-  discoverAvailableModels,
-  findModel,
   discoverSkills,
   discoverHooks,
   discoverCustomTools,
@@ -643,10 +665,13 @@ import {
   buildSystemPrompt,
 } from "@mariozechner/pi-coding-agent";
 
-// Models
-const allModels = discoverModels();
-const available = await discoverAvailableModels();
-const { model, error } = findModel("anthropic", "claude-sonnet-4-20250514");
+// Auth and Models
+const authStorage = discoverAuthStorage();           // ~/.pi/agent/auth.json
+const modelRegistry = discoverModels(authStorage);   // + ~/.pi/agent/models.json
+const allModels = modelRegistry.getAll();            // All models (built-in + custom)
+const available = await modelRegistry.getAvailable(); // Only models with API keys
+const model = modelRegistry.find("provider", "id");   // Find specific model
+const builtIn = getModel("anthropic", "claude-opus-4-5"); // Built-in only
 
 // Skills
 const skills = discoverSkills(cwd, agentDir, skillsSettings);
@@ -698,12 +723,12 @@ interface CreateAgentSessionResult {
 ## Complete Example
 
 ```typescript
+import { getModel } from "@mariozechner/pi-ai";
 import { Type } from "@sinclair/typebox";
 import {
+  AuthStorage,
   createAgentSession,
-  configureOAuthStorage,
-  defaultGetApiKey,
-  findModel,
+  ModelRegistry,
   SessionManager,
   SettingsManager,
   readTool,
@@ -711,18 +736,17 @@ import {
   type HookFactory,
   type CustomAgentTool,
 } from "@mariozechner/pi-coding-agent";
-import { getAgentDir } from "@mariozechner/pi-coding-agent/config";
 
-// Use OAuth from default location
-configureOAuthStorage(getAgentDir());
+// Set up auth storage (custom location)
+const authStorage = new AuthStorage("/custom/agent/auth.json");
 
-// Custom API key with fallback
-const getApiKey = async (model: { provider: string }) => {
-  if (model.provider === "anthropic" && process.env.MY_KEY) {
-    return process.env.MY_KEY;
-  }
-  return defaultGetApiKey()(model as any);
-};
+// Runtime API key override (not persisted)
+if (process.env.MY_KEY) {
+  authStorage.setRuntimeApiKey("anthropic", process.env.MY_KEY);
+}
+
+// Model registry (no custom models.json)
+const modelRegistry = new ModelRegistry(authStorage);
 
 // Inline hook
 const auditHook: HookFactory = (api) => {
@@ -744,8 +768,7 @@ const statusTool: CustomAgentTool = {
   }),
 };
 
-const { model, error } = findModel("anthropic", "claude-sonnet-4-20250514");
-if (error) throw new Error(error);
+const model = getModel("anthropic", "claude-opus-4-5");
 if (!model) throw new Error("Model not found");
 
 // In-memory settings with overrides
@@ -760,7 +783,8 @@ const { session } = await createAgentSession({
   
   model,
   thinkingLevel: "off",
-  getApiKey,
+  authStorage,
+  modelRegistry,
   
   systemPrompt: "You are a minimal assistant. Be concise.",
   
@@ -812,12 +836,14 @@ The main entry point exports:
 ```typescript
 // Factory
 createAgentSession
-configureOAuthStorage
 
-// Discovery
+// Auth and Models
+AuthStorage
+ModelRegistry
+discoverAuthStorage
 discoverModels
-discoverAvailableModels
-findModel
+
+// Discovery
 discoverSkills
 discoverHooks
 discoverCustomTools
@@ -825,7 +851,6 @@ discoverContextFiles
 discoverSlashCommands
 
 // Helpers
-defaultGetApiKey
 loadSettings
 buildSystemPrompt
 

package/examples/custom-tools/hello/index.ts

@@ -1,20 +1,20 @@
-import { Type } from "@sinclair/typebox";
 import type { CustomToolFactory } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
 
-const factory: CustomToolFactory = (pi) => ({
-  name: "hello",
-  label: "Hello",
-  description: "A simple greeting tool",
-  parameters: Type.Object({
-    name: Type.String({ description: "Name to greet" }),
-  }),
+const factory: CustomToolFactory = (_pi) => ({
+	name: "hello",
+	label: "Hello",
+	description: "A simple greeting tool",
+	parameters: Type.Object({
+		name: Type.String({ description: "Name to greet" }),
+	}),
 
-  async execute(toolCallId, params) {
-    return {
-      content: [{ type: "text", text: `Hello, ${params.name}!` }],
-      details: { greeted: params.name },
-    };
-  },
+	async execute(_toolCallId, params) {
+		return {
+			content: [{ type: "text", text: `Hello, ${params.name}!` }],
+			details: { greeted: params.name },
+		};
+	},
 });
 
-export default factory;
+export default factory;

package/examples/custom-tools/question/index.ts

@@ -2,9 +2,9 @@
  * Question Tool - Let the LLM ask the user a question with options
  */
 
-import { Type } from "@sinclair/typebox";
-import { Text } from "@mariozechner/pi-tui";
 import type { CustomAgentTool, CustomToolFactory } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
 
 interface QuestionDetails {
 	question: string;
@@ -57,7 +57,7 @@ const factory: CustomToolFactory = (pi) => {
 		renderCall(args, theme) {
 			let text = theme.fg("toolTitle", theme.bold("question ")) + theme.fg("muted", args.question);
 			if (args.options?.length) {
-				text += "\n" + theme.fg("dim", `  Options: ${args.options.join(", ")}`);
+				text += `\n${theme.fg("dim", `  Options: ${args.options.join(", ")}`)}`;
 			}
 			return new Text(text, 0, 0);
 		},

package/examples/custom-tools/subagent/agents.ts

@@ -129,8 +129,7 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
 
 	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
-	const projectAgents =
-		scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
 
 	const agentMap = new Map<string, AgentConfig>();