Add configurable OAuth storage backend and respect --models in model selector

- Add setOAuthStorage() and resetOAuthStorage() to pi-ai for custom storage backends
- Configure coding-agent to use its own configurable OAuth path via getOAuthPath()
- Model selector (/model command) now only shows models from --models scope when set
- Rewrite OAuth documentation in pi-ai README with examples

Fixes #255

packages/ai/README.md

@@ -1115,29 +1115,137 @@ setApiKey('anthropic', 'sk-ant-...');
 const key = getApiKey('openai');
 ```
 
-## GitHub Copilot
+## OAuth Providers
 
-GitHub Copilot is available as a provider, requiring OAuth authentication via GitHub's device flow.
+Several providers require OAuth authentication instead of static API keys. This library provides login flows, automatic token refresh, and credential storage for:
 
-**Using with `@mariozechner/pi-coding-agent`**: Use `/login` and select "GitHub Copilot" to authenticate. All models are automatically enabled after login. Token stored in `~/.pi/agent/oauth.json`.
+- **Anthropic** (Claude Pro/Max subscription)
+- **GitHub Copilot** (Copilot subscription)
+- **Google Gemini CLI** (Free Gemini 2.0/2.5 via Google Cloud Code Assist)
+- **Antigravity** (Free Gemini 3, Claude, GPT-OSS via Google Cloud)
 
-**Using standalone**: If you have a valid Copilot OAuth token (e.g., from the coding agent's `oauth.json`):
+Credentials are stored in `~/.pi/agent/oauth.json` by default (with `chmod 600` permissions). Use `setOAuthStorage()` to configure a custom storage backend for different locations or environments (the coding-agent does this to respect its configurable config directory).
+
+### Using with @mariozechner/pi-coding-agent
+
+Use `/login` and select a provider to authenticate. Tokens are automatically refreshed when expired.
+
+### Programmatic OAuth
+
+For standalone usage, the library exposes low-level OAuth functions:
 
 ```typescript
-import { getModel, complete } from '@mariozechner/pi-ai';
+import {
+  // Login functions (each implements provider-specific OAuth flow)
+  loginAnthropic,
+  loginGitHubCopilot,
+  loginGeminiCli,
+  loginAntigravity,
+  
+  // Token management
+  refreshToken,        // Refresh token for any provider
+  getOAuthApiKey,      // Get API key (auto-refreshes if expired)
+  
+  // Credential storage
+  loadOAuthCredentials,
+  saveOAuthCredentials,
+  removeOAuthCredentials,
+  hasOAuthCredentials,
+  listOAuthProviders,
+  getOAuthPath,
+  
+  // Types
+  type OAuthProvider,  // 'anthropic' | 'github-copilot' | 'google-gemini-cli' | 'google-antigravity'
+  type OAuthCredentials,
+} from '@mariozechner/pi-ai';
+```
+
+### Login Flow Example
+
+Each provider has a different OAuth flow. Here's an example with GitHub Copilot:
+
+```typescript
+import { loginGitHubCopilot, saveOAuthCredentials } from '@mariozechner/pi-ai';
+
+const credentials = await loginGitHubCopilot({
+  onAuth: (url, instructions) => {
+    // Display the URL and instructions to the user
+    console.log(`Open: ${url}`);
+    if (instructions) console.log(instructions);
+  },
+  onPrompt: async (prompt) => {
+    // Prompt user for input (e.g., device code confirmation)
+    return await getUserInput(prompt.message);
+  },
+  onProgress: (message) => {
+    // Optional: show progress updates
+    console.log(message);
+  }
+});
+
+// Save credentials for later use
+saveOAuthCredentials('github-copilot', credentials);
+```
+
+### Using OAuth Tokens
+
+Call `getOAuthApiKey()` before **every** `complete()` or `stream()` call. This function checks token expiry and refreshes automatically when needed:
+
+```typescript
+import { getModel, complete, getOAuthApiKey } from '@mariozechner/pi-ai';
 
 const model = getModel('github-copilot', 'gpt-4o');
 
+// Always call getOAuthApiKey() right before the API call
+// Do NOT cache the result - tokens expire and need refresh
+const apiKey = await getOAuthApiKey('github-copilot');
+if (!apiKey) {
+  throw new Error('Not logged in to GitHub Copilot');
+}
+
 const response = await complete(model, {
   messages: [{ role: 'user', content: 'Hello!' }]
-}, {
-  apiKey: 'tid=...;exp=...;proxy-ep=...'  // OAuth token from ~/.pi/agent/oauth.json
-});
+}, { apiKey });
 ```
 
-**Note**: OAuth tokens expire and need periodic refresh. The coding agent handles this automatically.
+### Custom Storage Backend
 
-If you get "The requested model is not supported" error, enable the model manually in VS Code: open Copilot Chat, click the model selector, select the model (warning icon), and click "Enable".
+Override the default storage location with `setOAuthStorage()`:
+
+```typescript
+import { setOAuthStorage, resetOAuthStorage } from '@mariozechner/pi-ai';
+import { readFileSync, writeFileSync } from 'fs';
+
+// Custom file path
+setOAuthStorage({
+  load: () => {
+    try {
+      return JSON.parse(readFileSync('/custom/path/oauth.json', 'utf-8'));
+    } catch {
+      return {};
+    }
+  },
+  save: (storage) => {
+    writeFileSync('/custom/path/oauth.json', JSON.stringify(storage, null, 2));
+  }
+});
+
+// In-memory storage (for testing or browser environments)
+let memoryStorage = {};
+setOAuthStorage({
+  load: () => memoryStorage,
+  save: (storage) => { memoryStorage = storage; }
+});
+
+// Reset to default (~/.pi/agent/oauth.json)
+resetOAuthStorage();
+```
+
+### Provider Notes
+
+**GitHub Copilot**: If you get "The requested model is not supported" error, enable the model manually in VS Code: open Copilot Chat, click the model selector, select the model (warning icon), and click "Enable".
+
+**Google Gemini CLI / Antigravity**: These use Google Cloud OAuth. The API key returned by `getOAuthApiKey()` is a JSON string containing both the token and project ID, which the library handles automatically.
 
 ## License
 

packages/ai/src/utils/oauth/index.ts

@@ -43,8 +43,11 @@ export {
 	type OAuthCredentials,
 	type OAuthProvider,
 	type OAuthStorage,
+	type OAuthStorageBackend,
 	removeOAuthCredentials,
+	resetOAuthStorage,
 	saveOAuthCredentials,
+	setOAuthStorage,
 } from "./storage.js";
 
 // ============================================================================

packages/ai/src/utils/oauth/storage.ts

@@ -1,5 +1,8 @@
 /**
- * OAuth credential storage for ~/.pi/agent/oauth.json
+ * OAuth credential storage with configurable backend.
+ *
+ * Default: ~/.pi/agent/oauth.json
+ * Override with setOAuthStorage() for custom storage locations or backends.
  */
 
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
@@ -23,54 +26,104 @@ export interface OAuthStorage {
 export type OAuthProvider = "anthropic" | "github-copilot" | "google-gemini-cli" | "google-antigravity";
 
 /**
- * Get the path to the OAuth credentials file
+ * Storage backend interface.
+ * Implement this to use a custom storage location or backend.
  */
-export function getOAuthPath(): string {
-	return join(homedir(), ".pi", "agent", "oauth.json");
+export interface OAuthStorageBackend {
+	/** Load all OAuth credentials. Return empty object if none exist. */
+	load(): OAuthStorage;
+	/** Save all OAuth credentials. */
+	save(storage: OAuthStorage): void;
 }
 
-/**
- * Ensure the config directory exists
- */
-function ensureConfigDir(): void {
-	const configDir = dirname(getOAuthPath());
-	if (!existsSync(configDir)) {
-		mkdirSync(configDir, { recursive: true, mode: 0o700 });
-	}
-}
+// ============================================================================
+// Default filesystem backend
+// ============================================================================
 
-/**
- * Load all OAuth credentials from ~/.pi/agent/oauth.json
- */
-export function loadOAuthStorage(): OAuthStorage {
-	const filePath = getOAuthPath();
-	if (!existsSync(filePath)) {
+const DEFAULT_PATH = join(homedir(), ".pi", "agent", "oauth.json");
+
+function defaultLoad(): OAuthStorage {
+	if (!existsSync(DEFAULT_PATH)) {
 		return {};
 	}
-
 	try {
-		const content = readFileSync(filePath, "utf-8");
+		const content = readFileSync(DEFAULT_PATH, "utf-8");
 		return JSON.parse(content);
 	} catch {
 		return {};
 	}
 }
 
+function defaultSave(storage: OAuthStorage): void {
+	const configDir = dirname(DEFAULT_PATH);
+	if (!existsSync(configDir)) {
+		mkdirSync(configDir, { recursive: true, mode: 0o700 });
+	}
+	writeFileSync(DEFAULT_PATH, JSON.stringify(storage, null, 2), "utf-8");
+	chmodSync(DEFAULT_PATH, 0o600);
+}
+
+// ============================================================================
+// Configurable backend
+// ============================================================================
+
+let currentBackend: OAuthStorageBackend = {
+	load: defaultLoad,
+	save: defaultSave,
+};
+
 /**
- * Save all OAuth credentials to ~/.pi/agent/oauth.json
+ * Configure the OAuth storage backend.
+ *
+ * @example
+ * // Custom file path
+ * setOAuthStorage({
+ *   load: () => JSON.parse(readFileSync('/custom/path/oauth.json', 'utf-8')),
+ *   save: (storage) => writeFileSync('/custom/path/oauth.json', JSON.stringify(storage))
+ * });
+ *
+ * @example
+ * // In-memory storage (for testing)
+ * let memoryStorage = {};
+ * setOAuthStorage({
+ *   load: () => memoryStorage,
+ *   save: (storage) => { memoryStorage = storage; }
+ * });
  */
-function saveOAuthStorage(storage: OAuthStorage): void {
-	ensureConfigDir();
-	const filePath = getOAuthPath();
-	writeFileSync(filePath, JSON.stringify(storage, null, 2), "utf-8");
-	chmodSync(filePath, 0o600);
+export function setOAuthStorage(backend: OAuthStorageBackend): void {
+	currentBackend = backend;
+}
+
+/**
+ * Reset to default filesystem storage (~/.pi/agent/oauth.json)
+ */
+export function resetOAuthStorage(): void {
+	currentBackend = { load: defaultLoad, save: defaultSave };
+}
+
+/**
+ * Get the default OAuth path (for reference, may not be used if custom backend is set)
+ */
+export function getOAuthPath(): string {
+	return DEFAULT_PATH;
+}
+
+// ============================================================================
+// Public API (uses current backend)
+// ============================================================================
+
+/**
+ * Load all OAuth credentials
+ */
+export function loadOAuthStorage(): OAuthStorage {
+	return currentBackend.load();
 }
 
 /**
  * Load OAuth credentials for a specific provider
  */
 export function loadOAuthCredentials(provider: string): OAuthCredentials | null {
-	const storage = loadOAuthStorage();
+	const storage = currentBackend.load();
 	return storage[provider] || null;
 }
 
@@ -78,18 +131,18 @@ export function loadOAuthCredentials(provider: string): OAuthCredentials | null
  * Save OAuth credentials for a specific provider
  */
 export function saveOAuthCredentials(provider: string, creds: OAuthCredentials): void {
-	const storage = loadOAuthStorage();
+	const storage = currentBackend.load();
 	storage[provider] = creds;
-	saveOAuthStorage(storage);
+	currentBackend.save(storage);
 }
 
 /**
  * Remove OAuth credentials for a specific provider
  */
 export function removeOAuthCredentials(provider: string): void {
-	const storage = loadOAuthStorage();
+	const storage = currentBackend.load();
 	delete storage[provider];
-	saveOAuthStorage(storage);
+	currentBackend.save(storage);
 }
 
 /**
@@ -103,6 +156,6 @@ export function hasOAuthCredentials(provider: string): boolean {
  * List all providers with OAuth credentials
  */
 export function listOAuthProviders(): string[] {
-	const storage = loadOAuthStorage();
+	const storage = currentBackend.load();
 	return Object.keys(storage);
 }