@mariozechner/pi-coding-agent 0.49.2 → 0.50.0

package/docs/providers.md

@@ -0,0 +1,147 @@
+# Providers
+
+Pi supports subscription-based providers via OAuth and API key providers via environment variables or auth file. For each provider, pi knows all available models. The list is updated with every pi release.
+
+## Table of Contents
+
+- [Subscriptions](#subscriptions)
+- [API Keys](#api-keys)
+- [Auth File](#auth-file)
+- [Cloud Providers](#cloud-providers)
+- [Custom Providers](#custom-providers)
+- [Resolution Order](#resolution-order)
+
+## Subscriptions
+
+Use `/login` in interactive mode, then select a provider:
+
+- Claude Pro/Max
+- ChatGPT Plus/Pro (Codex)
+- GitHub Copilot
+- Google Gemini CLI
+- Google Antigravity
+
+Use `/logout` to clear credentials. Tokens are stored in `~/.pi/agent/auth.json` and auto-refresh when expired.
+
+### GitHub Copilot
+
+- Press Enter for github.com, or enter your GitHub Enterprise Server domain
+- If you get "model not supported", enable it in VS Code: Copilot Chat → model selector → select model → "Enable"
+
+### Google Providers
+
+- **Gemini CLI**: Standard Gemini models via Cloud Code Assist
+- **Antigravity**: Sandbox with Gemini 3, Claude, and GPT-OSS models
+- Both free with any Google account, subject to rate limits
+- For paid Cloud Code Assist: set `GOOGLE_CLOUD_PROJECT` env var
+
+### OpenAI Codex
+
+- Requires ChatGPT Plus or Pro subscription
+- Personal use only; for production, use the OpenAI Platform API
+
+## API Keys
+
+Set via environment variable:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+pi
+```
+
+| Provider | Environment Variable |
+|----------|---------------------|
+| Anthropic | `ANTHROPIC_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| Google Gemini | `GEMINI_API_KEY` |
+| Mistral | `MISTRAL_API_KEY` |
+| Groq | `GROQ_API_KEY` |
+| Cerebras | `CEREBRAS_API_KEY` |
+| xAI | `XAI_API_KEY` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+| Vercel AI Gateway | `AI_GATEWAY_API_KEY` |
+| ZAI | `ZAI_API_KEY` |
+| OpenCode Zen | `OPENCODE_API_KEY` |
+| MiniMax | `MINIMAX_API_KEY` |
+| MiniMax (China) | `MINIMAX_CN_API_KEY` |
+
+## Auth File
+
+Store credentials in `~/.pi/agent/auth.json`:
+
+```json
+{
+  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
+  "openai": { "type": "api_key", "key": "sk-..." },
+  "google": { "type": "api_key", "key": "..." }
+}
+```
+
+The file is created with `0600` permissions (user read/write only). Auth file credentials take priority over environment variables.
+
+OAuth credentials are also stored here after `/login` and managed automatically.
+
+## Cloud Providers
+
+### Azure OpenAI
+
+```bash
+export AZURE_OPENAI_API_KEY=...
+export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
+# or use resource name instead of base URL
+export AZURE_OPENAI_RESOURCE_NAME=your-resource
+
+# Optional
+export AZURE_OPENAI_API_VERSION=2024-02-01
+export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o
+```
+
+### Amazon Bedrock
+
+```bash
+# Option 1: AWS Profile
+export AWS_PROFILE=your-profile
+
+# Option 2: IAM Keys
+export AWS_ACCESS_KEY_ID=AKIA...
+export AWS_SECRET_ACCESS_KEY=...
+
+# Option 3: Bearer Token
+export AWS_BEARER_TOKEN_BEDROCK=...
+
+# Optional region (defaults to us-east-1)
+export AWS_REGION=us-west-2
+```
+
+Also supports ECS task roles (`AWS_CONTAINER_CREDENTIALS_*`) and IRSA (`AWS_WEB_IDENTITY_TOKEN_FILE`).
+
+```bash
+pi --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0
+```
+
+### Google Vertex AI
+
+Uses Application Default Credentials:
+
+```bash
+gcloud auth application-default login
+export GOOGLE_CLOUD_PROJECT=your-project
+export GOOGLE_CLOUD_LOCATION=us-central1
+```
+
+Or set `GOOGLE_APPLICATION_CREDENTIALS` to a service account key file.
+
+## Custom Providers
+
+**Via models.json:** Add Ollama, LM Studio, vLLM, or any provider that speaks a supported API (OpenAI Completions, OpenAI Responses, Anthropic Messages, Google Generative AI). See [models.md](models.md).
+
+**Via extensions:** For providers that need custom API implementations or OAuth flows, create an extension. See [custom-provider.md](custom-provider.md) and [examples/extensions/custom-provider-gitlab-duo](../examples/extensions/custom-provider-gitlab-duo/).
+
+## Resolution Order
+
+When resolving credentials for a provider:
+
+1. CLI `--api-key` flag
+2. `auth.json` entry (API key or OAuth token)
+3. Environment variable
+4. Custom provider keys from `models.json`

package/docs/sdk.md

@@ -16,11 +16,11 @@ See [examples/sdk/](../examples/sdk/) for working examples from minimal to full
 ## Quick Start
 
 ```typescript
-import { createAgentSession, discoverAuthStorage, discoverModels, SessionManager } from "@mariozechner/pi-coding-agent";
+import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@mariozechner/pi-coding-agent";
 
 // Set up credential storage and model registry
-const authStorage = discoverAuthStorage();
-const modelRegistry = discoverModels(authStorage);
+const authStorage = new AuthStorage();
+const modelRegistry = new ModelRegistry(authStorage);
 
 const { session } = await createAgentSession({
   sessionManager: SessionManager.inMemory(),
@@ -51,20 +51,17 @@ The SDK is included in the main package. No separate installation needed.
 
 The main factory function. Creates an `AgentSession` with configurable options.
 
-**Philosophy:** "Omit to discover, provide to override."
-- Omit an option → pi discovers/loads from standard locations
-- Provide an option → your value is used, discovery skipped for that option
+`createAgentSession()` uses a `ResourceLoader` to supply extensions, skills, prompt templates, themes, and context files. If you do not provide one, it uses `DefaultResourceLoader` with standard discovery.
 
 ```typescript
 import { createAgentSession } from "@mariozechner/pi-coding-agent";
 
-// Minimal: all defaults (discovers everything from cwd and ~/.pi/agent)
+// Minimal: defaults with DefaultResourceLoader
 const { session } = await createAgentSession();
 
 // Custom: override specific options
 const { session } = await createAgentSession({
   model: myModel,
-  systemPrompt: "You are helpful.",
   tools: [readTool, bashTool],
   sessionManager: SessionManager.inMemory(),
 });
@@ -251,7 +248,7 @@ session.subscribe((event) => {
 
 ```typescript
 const { session } = await createAgentSession({
-  // Working directory for project-local discovery
+  // Working directory for DefaultResourceLoader discovery
   cwd: process.cwd(), // default
   
   // Global config directory
@@ -259,14 +256,14 @@ const { session } = await createAgentSession({
 });
 ```
 
-`cwd` is used for:
+`cwd` is used by `DefaultResourceLoader` for:
 - Project extensions (`.pi/extensions/`)
 - Project skills (`.pi/skills/`)
 - Project prompts (`.pi/prompts/`)
 - Context files (`AGENTS.md` walking up from cwd)
 - Session directory naming
 
-`agentDir` is used for:
+`agentDir` is used by `DefaultResourceLoader` for:
 - Global extensions (`extensions/`)
 - Global skills (`skills/`)
 - Global prompts (`prompts/`)
@@ -276,14 +273,16 @@ const { session } = await createAgentSession({
 - Credentials (`auth.json`)
 - Sessions (`sessions/`)
 
+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 "@mariozechner/pi-ai";
-import { discoverAuthStorage, discoverModels } from "@mariozechner/pi-coding-agent";
+import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
 
-const authStorage = discoverAuthStorage();
-const modelRegistry = discoverModels(authStorage);
+const authStorage = new AuthStorage();
+const modelRegistry = new ModelRegistry(authStorage);
 
 // Find specific built-in model (doesn't check if API key exists)
 const opus = getModel("anthropic", "claude-opus-4-5");
@@ -327,11 +326,11 @@ API key resolution priority (handled by AuthStorage):
 4. Fallback resolver (for custom provider keys from `models.json`)
 
 ```typescript
-import { AuthStorage, ModelRegistry, discoverAuthStorage, discoverModels } from "@mariozechner/pi-coding-agent";
+import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
 
 // Default: uses ~/.pi/agent/auth.json and ~/.pi/agent/models.json
-const authStorage = discoverAuthStorage();
-const modelRegistry = discoverModels(authStorage);
+const authStorage = new AuthStorage();
+const modelRegistry = new ModelRegistry(authStorage);
 
 const { session } = await createAgentSession({
   sessionManager: SessionManager.inMemory(),
@@ -360,16 +359,17 @@ const simpleRegistry = new ModelRegistry(authStorage);
 
 ### System Prompt
 
+Use a `ResourceLoader` to override the system prompt:
+
 ```typescript
-const { session } = await createAgentSession({
-  // Replace entirely
-  systemPrompt: "You are a helpful assistant.",
-  
-  // Or modify default (receives default, returns modified)
-  systemPrompt: (defaultPrompt) => {
-    return `${defaultPrompt}\n\n## Additional Rules\n- Be concise`;
-  },
+import { createAgentSession, DefaultResourceLoader } from "@mariozechner/pi-coding-agent";
+
+const loader = new DefaultResourceLoader({
+  systemPromptOverride: () => "You are a helpful assistant.",
 });
+await loader.reload();
+
+const { session } = await createAgentSession({ resourceLoader: loader });
 ```
 
 > See [examples/sdk/03-custom-prompt.ts](../examples/sdk/03-custom-prompt.ts)
@@ -462,61 +462,45 @@ const { session } = await createAgentSession({
 });
 ```
 
-Custom tools passed via `customTools` are combined with extension-registered tools. Extensions discovered from `~/.pi/agent/extensions/` and `.pi/extensions/` can also register tools via `pi.registerTool()`.
+Custom tools passed via `customTools` are combined with extension-registered tools. Extensions loaded by the ResourceLoader can also register tools via `pi.registerTool()`.
 
 > See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
 
 ### Extensions
 
-By default, extensions are discovered from multiple locations:
-- `~/.pi/agent/extensions/` (global)
-- `.pi/extensions/` (project-local)
-- Paths listed in `settings.json` `"extensions"` array
+Extensions are loaded by the `ResourceLoader`. `DefaultResourceLoader` discovers extensions from `~/.pi/agent/extensions/`, `.pi/extensions/`, and settings.json extension sources.
 
 ```typescript
-import { createAgentSession, type ExtensionFactory } from "@mariozechner/pi-coding-agent";
-
-// Inline extension factory
-const myExtension: ExtensionFactory = (pi) => {
-  pi.on("tool_call", async (event, ctx) => {
-    console.log(`Tool: ${event.toolName}`);
-  });
-
-  pi.registerCommand("hello", {
-    description: "Say hello",
-    handler: async (args, ctx) => {
-      ctx.ui.notify("Hello!", "info");
-    },
-  });
-};
-
-// Pass inline extensions (skips file discovery)
-const { session } = await createAgentSession({
-  extensions: [myExtension],
-});
+import { createAgentSession, DefaultResourceLoader } from "@mariozechner/pi-coding-agent";
 
-// Add paths to load (merged with discovery)
-const { session } = await createAgentSession({
+const loader = new DefaultResourceLoader({
   additionalExtensionPaths: ["/path/to/my-extension.ts"],
+  extensionFactories: [
+    (pi) => {
+      pi.on("agent_start", () => {
+        console.log("[Inline Extension] Agent starting");
+      });
+    },
+  ],
 });
+await loader.reload();
 
-// Disable extension discovery entirely
-const { session } = await createAgentSession({
-  extensions: [],
-});
+const { session } = await createAgentSession({ resourceLoader: loader });
 ```
 
 Extensions can register tools, subscribe to events, add commands, and more. See [extensions.md](extensions.md) for the full API.
 
-**Event Bus:** Extensions can communicate via `pi.events`. Pass a shared `eventBus` to `createAgentSession()` if you need to emit/listen from outside:
+**Event Bus:** Extensions can communicate via `pi.events`. Pass a shared `eventBus` to `DefaultResourceLoader` if you need to emit or listen from outside:
 
 ```typescript
-import { createAgentSession, createEventBus } from "@mariozechner/pi-coding-agent";
+import { createEventBus, DefaultResourceLoader } from "@mariozechner/pi-coding-agent";
 
 const eventBus = createEventBus();
-const { session } = await createAgentSession({ eventBus });
+const loader = new DefaultResourceLoader({
+  eventBus,
+});
+await loader.reload();
 
-// Listen for events from extensions
 eventBus.on("my-extension:status", (data) => console.log(data));
 ```
 
@@ -525,14 +509,13 @@ eventBus.on("my-extension:status", (data) => console.log(data));
 ### Skills
 
 ```typescript
-import { createAgentSession, discoverSkills, type Skill } from "@mariozechner/pi-coding-agent";
-
-// Discover and filter
-const { skills: allSkills, warnings } = discoverSkills();
-const filtered = allSkills.filter(s => s.name.includes("search"));
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  type Skill,
+} from "@mariozechner/pi-coding-agent";
 
-// Custom skill
-const mySkill: Skill = {
+const customSkill: Skill = {
   name: "my-skill",
   description: "Custom instructions",
   filePath: "/path/to/SKILL.md",
@@ -540,20 +523,15 @@ const mySkill: Skill = {
   source: "custom",
 };
 
-const { session } = await createAgentSession({
-  skills: [...filtered, mySkill],
-});
-
-// Disable skills
-const { session } = await createAgentSession({
-  skills: [],
+const loader = new DefaultResourceLoader({
+  skillsOverride: (current) => ({
+    skills: [...current.skills, customSkill],
+    diagnostics: current.diagnostics,
+  }),
 });
+await loader.reload();
 
-// Discovery with settings filter
-const { skills } = discoverSkills(process.cwd(), undefined, {
-  ignoredSkills: ["browser-*"],  // glob patterns to exclude
-  includeSkills: ["search-*"],   // glob patterns to include (empty = all)
-});
+const { session } = await createAgentSession({ resourceLoader: loader });
 ```
 
 > See [examples/sdk/04-skills.ts](../examples/sdk/04-skills.ts)
@@ -561,26 +539,19 @@ const { skills } = discoverSkills(process.cwd(), undefined, {
 ### Context Files
 
 ```typescript
-import { createAgentSession, discoverContextFiles } from "@mariozechner/pi-coding-agent";
-
-// Discover AGENTS.md files
-const discovered = discoverContextFiles();
-
-// Add custom context
-const { session } = await createAgentSession({
-  contextFiles: [
-    ...discovered,
-    {
-      path: "/virtual/AGENTS.md",
-      content: "# Guidelines\n\n- Be concise\n- Use TypeScript",
-    },
-  ],
+import { createAgentSession, DefaultResourceLoader } from "@mariozechner/pi-coding-agent";
+
+const loader = new DefaultResourceLoader({
+  agentsFilesOverride: (current) => ({
+    agentsFiles: [
+      ...current.agentsFiles,
+      { path: "/virtual/AGENTS.md", content: "# Guidelines\n\n- Be concise" },
+    ],
+  }),
 });
+await loader.reload();
 
-// Disable context files
-const { session } = await createAgentSession({
-  contextFiles: [],
-});
+const { session } = await createAgentSession({ resourceLoader: loader });
 ```
 
 > See [examples/sdk/07-context-files.ts](../examples/sdk/07-context-files.ts)
@@ -588,9 +559,11 @@ const { session } = await createAgentSession({
 ### Slash Commands
 
 ```typescript
-import { createAgentSession, discoverPromptTemplates, type PromptTemplate } from "@mariozechner/pi-coding-agent";
-
-const discovered = discoverPromptTemplates();
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  type PromptTemplate,
+} from "@mariozechner/pi-coding-agent";
 
 const customCommand: PromptTemplate = {
   name: "deploy",
@@ -599,9 +572,15 @@ const customCommand: PromptTemplate = {
   content: "# Deploy\n\n1. Build\n2. Test\n3. Deploy",
 };
 
-const { session } = await createAgentSession({
-  promptTemplates: [...discovered, customCommand],
+const loader = new DefaultResourceLoader({
+  promptsOverride: (current) => ({
+    prompts: [...current.prompts, customCommand],
+    diagnostics: current.diagnostics,
+  }),
 });
+await loader.reload();
+
+const { session } = await createAgentSession({ resourceLoader: loader });
 ```
 
 > See [examples/sdk/08-prompt-templates.ts](../examples/sdk/08-prompt-templates.ts)
@@ -719,62 +698,31 @@ Settings load from two locations and merge:
 1. Global: `~/.pi/agent/settings.json`
 2. Project: `<cwd>/.pi/settings.json`
 
-Project overrides global. Nested objects merge keys. Setters only modify global (project is read-only for version control).
+Project overrides global. Nested objects merge keys. Setters modify global settings by default.
 
 > See [examples/sdk/10-settings.ts](../examples/sdk/10-settings.ts)
 
-## Discovery Functions
+## ResourceLoader
 
-All discovery functions accept optional `cwd` and `agentDir` parameters.
+Use `DefaultResourceLoader` to discover extensions, skills, prompts, themes, and context files.
 
 ```typescript
-import { getModel } from "@mariozechner/pi-ai";
 import {
-  AuthStorage,
-  ModelRegistry,
-  discoverAuthStorage,
-  discoverModels,
-  discoverSkills,
-  discoverExtensions,
-  discoverContextFiles,
-  discoverPromptTemplates,
-  loadSettings,
-  buildSystemPrompt,
-  createEventBus,
+  DefaultResourceLoader,
+  getAgentDir,
 } from "@mariozechner/pi-coding-agent";
 
-// 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, warnings } = discoverSkills(cwd, agentDir, skillsSettings);
-
-// Extensions (async - loads TypeScript)
-// Pass eventBus to share pi.events across extensions
-const eventBus = createEventBus();
-const { extensions, errors } = await discoverExtensions(eventBus, cwd, agentDir);
-
-// Context files
-const contextFiles = discoverContextFiles(cwd, agentDir);
-
-// Prompt templates
-const templates = discoverPromptTemplates(cwd, agentDir);
-
-// Settings (global + project merged)
-const settings = loadSettings(cwd, agentDir);
-
-// Build system prompt manually
-const prompt = buildSystemPrompt({
-  skills,
-  contextFiles,
-  appendPrompt: "Additional instructions",
+const loader = new DefaultResourceLoader({
   cwd,
+  agentDir: getAgentDir(),
 });
+await loader.reload();
+
+const extensions = loader.getExtensions();
+const skills = loader.getSkills();
+const prompts = loader.getPrompts();
+const themes = loader.getThemes();
+const contextFiles = loader.getAgentsFiles().agentsFiles;
 ```
 
 ## Return Value
@@ -808,12 +756,12 @@ import { Type } from "@sinclair/typebox";
 import {
   AuthStorage,
   createAgentSession,
+  DefaultResourceLoader,
   ModelRegistry,
   SessionManager,
   SettingsManager,
   readTool,
   bashTool,
-  type ExtensionFactory,
   type ToolDefinition,
 } from "@mariozechner/pi-coding-agent";
 
@@ -828,14 +776,6 @@ if (process.env.MY_KEY) {
 // Model registry (no custom models.json)
 const modelRegistry = new ModelRegistry(authStorage);
 
-// Inline extension
-const auditExtension: ExtensionFactory = (pi) => {
-  pi.on("tool_call", async (event) => {
-    console.log(`[Audit] ${event.toolName}`);
-    return undefined;
-  });
-};
-
 // Inline tool
 const statusTool: ToolDefinition = {
   name: "status",
@@ -857,24 +797,27 @@ const settingsManager = SettingsManager.inMemory({
   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 { session } = await createAgentSession({
   cwd: process.cwd(),
   agentDir: "/custom/agent",
-  
+
   model,
   thinkingLevel: "off",
   authStorage,
   modelRegistry,
-  
-  systemPrompt: "You are a minimal assistant. Be concise.",
-  
+
   tools: [readTool, bashTool],
   customTools: [statusTool],
-  extensions: [auditExtension],
-  skills: [],
-  contextFiles: [],
-  promptTemplates: [],
-  
+  resourceLoader: loader,
+
   sessionManager: SessionManager.inMemory(),
   settingsManager,
 });
@@ -976,21 +919,13 @@ createAgentSession
 // Auth and Models
 AuthStorage
 ModelRegistry
-discoverAuthStorage
-discoverModels
-
-// Discovery
-discoverSkills
-discoverExtensions
-discoverContextFiles
-discoverPromptTemplates
 
-// Event Bus (for shared extension communication)
+// Resource loading
+DefaultResourceLoader
+type ResourceLoader
 createEventBus
 
 // Helpers
-loadSettings
-buildSystemPrompt
 
 // Session management
 SessionManager
@@ -1016,8 +951,6 @@ type ExtensionAPI
 type ToolDefinition
 type Skill
 type PromptTemplate
-type Settings
-type SkillsSettings
 type Tool
 ```