byterover-cli 2.2.0 → 2.3.1

package/dist/server/core/domain/entities/provider-config.d.ts

@@ -12,12 +12,16 @@ export interface ConnectedProviderConfig {
     readonly activeModel?: string;
     /** Context window size of the active model (from provider API, e.g. OpenRouter) */
     readonly activeModelContextLength?: number;
+    /** How this provider was authenticated */
+    readonly authMethod?: 'api-key' | 'oauth';
     /** Custom API base URL (for openai-compatible provider) */
     readonly baseUrl?: string;
     /** When the provider was connected */
     readonly connectedAt: string;
     /** User's favorite models (for quick access) */
     readonly favoriteModels: readonly string[];
+    /** OAuth account ID (e.g. ChatGPT-Account-Id for OpenAI) */
+    readonly oauthAccountId?: string;
     /** Recently used models (last 10) */
     readonly recentModels: readonly string[];
 }
@@ -96,7 +100,9 @@ export declare class ProviderConfig {
      */
     withProviderConnected(providerId: string, options?: {
         activeModel?: string;
+        authMethod?: 'api-key' | 'oauth';
         baseUrl?: string;
+        oauthAccountId?: string;
     }): ProviderConfig;
     /**
      * Create a new config with a provider disconnected.

package/dist/server/core/domain/entities/provider-config.js

@@ -10,10 +10,9 @@
 const isProviderConfigJson = (json) => {
     if (typeof json !== 'object' || json === null)
         return false;
-    const obj = json;
-    if (typeof obj.activeProvider !== 'string')
+    if (!('activeProvider' in json) || typeof json.activeProvider !== 'string')
         return false;
-    if (typeof obj.providers !== 'object' || obj.providers === null)
+    if (!('providers' in json) || typeof json.providers !== 'object' || json.providers === null)
         return false;
     return true;
 };
@@ -164,9 +163,11 @@ export class ProviderConfig {
         const existingConfig = this.providers[providerId];
         const newProviderConfig = {
             activeModel: options?.activeModel ?? existingConfig?.activeModel,
+            authMethod: options?.authMethod ?? existingConfig?.authMethod,
             baseUrl: options?.baseUrl ?? existingConfig?.baseUrl,
             connectedAt: existingConfig?.connectedAt ?? new Date().toISOString(),
             favoriteModels: existingConfig?.favoriteModels ?? [],
+            oauthAccountId: options?.oauthAccountId ?? existingConfig?.oauthAccountId,
             recentModels: existingConfig?.recentModels ?? [],
         };
         return new ProviderConfig({

package/dist/server/core/domain/entities/provider-registry.d.ts

@@ -4,6 +4,44 @@
  * Defines available LLM providers that can be connected to byterover-cli.
  * Inspired by OpenCode's provider system.
  */
+/**
+ * Configuration for a single OAuth authentication mode.
+ */
+export interface OAuthModeConfig {
+    /** Auth URL for this mode */
+    readonly authUrl: string;
+    /** Mode identifier (e.g. 'default', 'pro-max') */
+    readonly id: string;
+    /** Display label (e.g. "Sign in with OpenAI") */
+    readonly label: string;
+}
+/**
+ * OAuth configuration for a provider.
+ */
+export interface ProviderOAuthConfig {
+    /** How the callback is received: local server ('auto') or user pastes code ('code-paste') */
+    readonly callbackMode: 'auto' | 'code-paste';
+    /** Port for local callback server (auto mode only) */
+    readonly callbackPort?: number;
+    /** OAuth client ID */
+    readonly clientId: string;
+    /** Whether to add `code=true` query param to auth URL (code-paste mode only — tells server to display paste-able code) */
+    readonly codeDisplay?: boolean;
+    /** Default model when connected via OAuth (overrides ProviderDefinition.defaultModel) */
+    readonly defaultModel?: string;
+    /** Extra query params appended to the authorization URL (provider-specific) */
+    readonly extraParams?: Readonly<Record<string, string>>;
+    /** Supported OAuth modes (some providers have multiple) */
+    readonly modes: readonly OAuthModeConfig[];
+    /** OAuth redirect URI */
+    readonly redirectUri: string;
+    /** OAuth scopes */
+    readonly scopes: string;
+    /** Token endpoint content type: OpenAI = 'form', Anthropic = 'json' */
+    readonly tokenContentType: 'form' | 'json';
+    /** Token exchange endpoint */
+    readonly tokenUrl: string;
+}
 /**
  * Definition for an LLM provider.
  */
@@ -28,6 +66,8 @@ export interface ProviderDefinition {
     readonly modelsEndpoint: string;
     /** Display name */
     readonly name: string;
+    /** OAuth configuration (only for OAuth-capable providers) */
+    readonly oauth?: ProviderOAuthConfig;
     /** Priority for display order (lower = higher priority) */
     readonly priority: number;
 }
@@ -54,4 +94,4 @@ export declare function getProviderById(id: string): ProviderDefinition | undefi
 /**
  * Check if a provider requires an API key.
  */
-export declare function providerRequiresApiKey(id: string): boolean;
+export declare function providerRequiresApiKey(id: string, authMethod?: 'api-key' | 'oauth'): boolean;

package/dist/server/core/domain/entities/provider-registry.js

@@ -4,6 +4,7 @@
  * Defines available LLM providers that can be connected to byterover-cli.
  * Inspired by OpenCode's provider system.
  */
+import { CHATGPT_OAUTH_ORIGINATOR } from '../../../../shared/constants/oauth.js';
 /**
  * Registry of all available providers.
  * Order by priority for consistent display.
@@ -160,6 +161,26 @@ export const PROVIDER_REGISTRY = {
         id: 'openai',
         modelsEndpoint: '/models',
         name: 'OpenAI',
+        oauth: {
+            callbackMode: 'auto',
+            callbackPort: 1455,
+            // Public OAuth client ID (safe to commit — native app public client, no client secret)
+            clientId: 'app_EMoamEEZ73f0CkXaXp7hrann',
+            // OpenAI Codex model used for the ChatGPT OAuth (Codex CLI) flow
+            defaultModel: 'gpt-5.1-codex-mini',
+            /* eslint-disable camelcase -- OAuth query params follow RFC 6749 naming */
+            extraParams: {
+                codex_cli_simplified_flow: 'true',
+                id_token_add_organizations: 'true',
+                originator: CHATGPT_OAUTH_ORIGINATOR,
+            },
+            /* eslint-enable camelcase */
+            modes: [{ authUrl: 'https://auth.openai.com/oauth/authorize', id: 'default', label: 'Sign in with OpenAI' }],
+            redirectUri: 'http://localhost:1455/auth/callback',
+            scopes: 'openid profile email offline_access',
+            tokenContentType: 'form',
+            tokenUrl: 'https://auth.openai.com/oauth/token',
+        },
         priority: 3,
     },
     'openai-compatible': {
@@ -268,7 +289,9 @@ export function getProviderById(id) {
 /**
  * Check if a provider requires an API key.
  */
-export function providerRequiresApiKey(id) {
+export function providerRequiresApiKey(id, authMethod) {
+    if (authMethod === 'oauth')
+        return false;
     const provider = getProviderById(id);
     if (!provider)
         return false;

package/dist/server/core/domain/errors/task-error.d.ts

@@ -11,6 +11,8 @@ export declare const TaskErrorCode: {
     readonly LLM_RATE_LIMIT: "ERR_LLM_RATE_LIMIT";
     readonly LOCAL_CHANGES_EXIST: "ERR_LOCAL_CHANGES_EXIST";
     readonly NOT_AUTHENTICATED: "ERR_NOT_AUTHENTICATED";
+    readonly OAUTH_REFRESH_FAILED: "ERR_OAUTH_REFRESH_FAILED";
+    readonly OAUTH_TOKEN_EXPIRED: "ERR_OAUTH_TOKEN_EXPIRED";
     readonly PROJECT_NOT_INIT: "ERR_PROJECT_NOT_INIT";
     readonly PROVIDER_NOT_CONFIGURED: "ERR_PROVIDER_NOT_CONFIGURED";
     readonly SPACE_NOT_CONFIGURED: "ERR_SPACE_NOT_CONFIGURED";

package/dist/server/core/domain/errors/task-error.js

@@ -15,6 +15,9 @@ export const TaskErrorCode = {
     LOCAL_CHANGES_EXIST: 'ERR_LOCAL_CHANGES_EXIST',
     // Auth/Init errors
     NOT_AUTHENTICATED: 'ERR_NOT_AUTHENTICATED',
+    // OAuth errors
+    OAUTH_REFRESH_FAILED: 'ERR_OAUTH_REFRESH_FAILED',
+    OAUTH_TOKEN_EXPIRED: 'ERR_OAUTH_TOKEN_EXPIRED',
     // Execution errors
     PROJECT_NOT_INIT: 'ERR_PROJECT_NOT_INIT',
     PROVIDER_NOT_CONFIGURED: 'ERR_PROVIDER_NOT_CONFIGURED',
@@ -100,7 +103,9 @@ export class AgentDisconnectedError extends TaskError {
 }
 export class AgentNotInitializedError extends TaskError {
     constructor(reason) {
-        super(reason ? `Agent failed to initialize: ${reason}` : "Agent failed to initialize. Run 'brv restart' to force a clean restart.", TaskErrorCode.AGENT_NOT_INITIALIZED);
+        super(reason
+            ? `Agent failed to initialize: ${reason}`
+            : "Agent failed to initialize. Run 'brv restart' to force a clean restart.", TaskErrorCode.AGENT_NOT_INITIALIZED);
         this.name = 'AgentNotInitializedError';
     }
 }

package/dist/server/core/domain/transport/schemas.d.ts

@@ -463,6 +463,8 @@ export declare const TransportDaemonEventNames: {
 export interface ProviderConfigResponse {
     activeModel?: string;
     activeProvider: string;
+    /** How the provider was authenticated ('api-key' | 'oauth'). Undefined for internal providers. */
+    authMethod?: 'api-key' | 'oauth';
     maxInputTokens?: number;
     openRouterApiKey?: string;
     provider?: string;

package/dist/server/core/interfaces/i-provider-config-store.d.ts

@@ -12,7 +12,9 @@ export interface IProviderConfigStore {
      */
     connectProvider: (providerId: string, options?: {
         activeModel?: string;
+        authMethod?: 'api-key' | 'oauth';
         baseUrl?: string;
+        oauthAccountId?: string;
     }) => Promise<void>;
     /**
      * Removes a provider connection.

package/dist/server/core/interfaces/i-provider-model-fetcher.d.ts

@@ -33,6 +33,15 @@ export interface ProviderModelInfo {
     /** Provider name (e.g., 'Anthropic', 'OpenAI') */
     provider: string;
 }
+/**
+ * Options for fetchModels().
+ */
+export interface FetchModelsOptions {
+    /** How this provider was authenticated */
+    authMethod?: 'api-key' | 'oauth';
+    /** If true, bypass any cache */
+    forceRefresh?: boolean;
+}
 /**
  * Interface for provider-specific model fetching.
  *
@@ -42,11 +51,11 @@ export interface ProviderModelInfo {
 export interface IProviderModelFetcher {
     /**
      * Fetch available models from the provider.
-     * @param apiKey - API key for authentication
-     * @param forceRefresh - If true, bypass any cache
+     * @param apiKey - API key or OAuth access token for authentication
+     * @param options - Fetch options (authMethod, forceRefresh)
      * @returns Array of normalized model info
      */
-    fetchModels(apiKey: string, forceRefresh?: boolean): Promise<ProviderModelInfo[]>;
+    fetchModels(apiKey: string, options?: FetchModelsOptions): Promise<ProviderModelInfo[]>;
     /**
      * Validate an API key by attempting a lightweight API call.
      * @param apiKey - API key to validate

package/dist/server/core/interfaces/i-provider-oauth-token-store.d.ts

@@ -0,0 +1,24 @@
+/**
+ * OAuth Token Record
+ *
+ * Stores the refresh token and expiry for a single OAuth-connected provider.
+ * Access tokens are stored separately in the provider keychain store.
+ */
+export type OAuthTokenRecord = {
+    /** Token expiry as ISO 8601 timestamp */
+    readonly expiresAt: string;
+    /** OAuth refresh token (used to obtain new access tokens) */
+    readonly refreshToken: string;
+};
+/**
+ * Interface for securely storing OAuth token metadata per provider.
+ *
+ * Separate from the provider keychain (which stores access tokens as "API keys").
+ * Implementations must encrypt data at rest.
+ */
+export interface IProviderOAuthTokenStore {
+    delete(providerId: string): Promise<void>;
+    get(providerId: string): Promise<OAuthTokenRecord | undefined>;
+    has(providerId: string): Promise<boolean>;
+    set(providerId: string, data: OAuthTokenRecord): Promise<void>;
+}

package/dist/server/core/interfaces/i-provider-oauth-token-store.js

@@ -0,0 +1 @@
+export {};

package/dist/server/core/interfaces/i-token-refresh-manager.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Interface for the token refresh manager.
+ * Used by resolveProviderConfig to transparently refresh OAuth tokens.
+ */
+export interface ITokenRefreshManager {
+    refreshIfNeeded(providerId: string): Promise<boolean>;
+}

package/dist/server/core/interfaces/i-token-refresh-manager.js

@@ -0,0 +1 @@
+export {};

package/dist/server/infra/daemon/agent-process.js

@@ -111,6 +111,8 @@ let cachedTeamId = '';
 let cachedSpaceId = '';
 let cachedActiveProvider = '';
 let cachedActiveModel = '';
+let cachedProviderApiKey;
+let cachedProviderHeaders;
 // ============================================================================
 // Provider Config (resolved by daemon via state:getProviderConfig)
 // ============================================================================
@@ -182,6 +184,8 @@ async function start() {
     const { activeModel, activeProvider } = providerResult;
     cachedActiveProvider = activeProvider;
     cachedActiveModel = activeModel ?? DEFAULT_LLM_MODEL;
+    cachedProviderApiKey = providerResult.providerApiKey;
+    cachedProviderHeaders = providerResult.providerHeaders ? JSON.stringify(providerResult.providerHeaders) : undefined;
     agentLog(`Provider: ${activeProvider}, Model: ${activeModel ?? 'default'}`);
     // 5. Create CipherAgent with lazy providers + transport client
     const envConfig = getCurrentConfig();
@@ -311,7 +315,8 @@ async function executeTask(task, curateExecutor, folderPackExecutor, queryExecut
     }
     if (freshProviderConfig.providerKeyMissing) {
         const modelInfo = freshProviderConfig.activeModel ? ` (model: ${freshProviderConfig.activeModel})` : '';
-        const errorMessage = `${freshProviderConfig.activeProvider} API key is missing${modelInfo}. Use /provider in the REPL to reconnect.`;
+        const credentialType = freshProviderConfig.authMethod === 'oauth' ? 'authentication has expired' : 'API key is missing';
+        const errorMessage = `${freshProviderConfig.activeProvider} ${credentialType}${modelInfo}. Use /provider in the REPL to reconnect.`;
         const error = serializeTaskError(new TaskError(errorMessage, TaskErrorCode.PROVIDER_NOT_CONFIGURED));
         transport.request(TransportTaskEventNames.ERROR, { clientId, error, taskId });
         return;
@@ -435,6 +440,9 @@ async function executeTask(task, curateExecutor, folderPackExecutor, queryExecut
  *
  * If only the model changed (same provider), the session ID is reused on the
  * fresh SessionManager for metadata continuity (in-memory history is not preserved).
+ * If only credentials changed (same provider and model), the session ID is reused
+ * and the SessionManager is rebuilt with the new credentials. This covers token refresh,
+ * auth method switches (API Key ↔ OAuth), and API key re-entry.
  * If the provider changed, a new session is created (history format is incompatible).
  */
 async function hotSwapProvider(currentAgent, transportClient) {
@@ -464,11 +472,18 @@ async function hotSwapProvider(currentAgent, transportClient) {
     const newModel = freshProvider.activeModel ?? DEFAULT_LLM_MODEL;
     const isProviderChange = ap !== cachedActiveProvider;
     const isModelChange = newModel !== cachedActiveModel;
+    const isCredentialChange = freshProvider.providerApiKey !== cachedProviderApiKey ||
+        (freshProvider.providerHeaders ? JSON.stringify(freshProvider.providerHeaders) : undefined) !==
+            cachedProviderHeaders;
     // Nothing actually changed (duplicate event) — skip
-    if (!isProviderChange && !isModelChange) {
+    if (!isProviderChange && !isModelChange && !isCredentialChange) {
         providerConfigDirty = false;
         return {};
     }
+    // TODO: Credential-only changes (e.g., OAuth token refresh) currently rebuild the entire
+    // SessionManager, which destroys in-memory conversation history. A future
+    // SessionManager.updateCredentials() method could swap LLM config in-place,
+    // preserving sessions and avoiding history loss on hourly token refreshes.
     // Phase 2a: Replace SessionManager (if this throws, old SM remains intact)
     const previousSessionId = currentAgent.sessionId;
     try {
@@ -502,7 +517,7 @@ async function hotSwapProvider(currentAgent, transportClient) {
             await persistNewSession(newSessionId, ap);
         }
         else {
-            // Model-only change: reuse session ID for metadata continuity.
+            // Model-only or credential-only change: reuse session ID for metadata continuity.
             // Note: in-memory conversation history is lost (new SessionManager has no sessions).
             // Only the session ID and persisted metadata are preserved.
             await currentAgent.createSession(previousSessionId);
@@ -530,7 +545,10 @@ async function hotSwapProvider(currentAgent, transportClient) {
     providerConfigDirty = false;
     cachedActiveProvider = ap;
     cachedActiveModel = newModel;
-    agentLog(`Provider hot-switched: ${ap}, Model: ${newModel}`);
+    cachedProviderApiKey = freshProvider.providerApiKey;
+    cachedProviderHeaders = freshProvider.providerHeaders ? JSON.stringify(freshProvider.providerHeaders) : undefined;
+    const changeType = isProviderChange ? 'provider' : isModelChange ? 'model' : 'credentials';
+    agentLog(`Provider hot-swapped (${changeType}): ${ap}, Model: ${newModel}`);
     return {};
 }
 // ============================================================================

package/dist/server/infra/daemon/brv-server.js

@@ -36,6 +36,8 @@ import { CurateLogHandler } from '../process/curate-log-handler.js';
 import { setupFeatureHandlers } from '../process/feature-handlers.js';
 import { TransportHandlers } from '../process/transport-handlers.js';
 import { ProjectRegistry } from '../project/project-registry.js';
+import { createProviderOAuthTokenStore } from '../provider-oauth/provider-oauth-token-store.js';
+import { TokenRefreshManager } from '../provider-oauth/token-refresh-manager.js';
 import { clearStaleProviderConfig, resolveProviderConfig } from '../provider/provider-config-resolver.js';
 import { ProjectRouter } from '../routing/project-router.js';
 import { AuthStateStore } from '../state/auth-state-store.js';
@@ -338,12 +340,20 @@ async function main() {
         // Provider config/keychain stores — shared between feature handlers and state endpoint
         const providerConfigStore = new FileProviderConfigStore();
         const providerKeychainStore = createProviderKeychainStore();
+        const providerOAuthTokenStore = createProviderOAuthTokenStore();
+        // Token refresh manager — transparently refreshes OAuth tokens before they expire
+        const tokenRefreshManager = new TokenRefreshManager({
+            providerConfigStore,
+            providerKeychainStore,
+            providerOAuthTokenStore,
+            transport: transportServer,
+        });
         // Clear stale provider config on startup (e.g. migration from v1 system keychain to v2 file keystore).
         // If a provider is configured but its API key is no longer accessible, disconnect it so the user
         // is returned to the onboarding flow rather than hitting a cryptic API key error mid-task.
-        await clearStaleProviderConfig(providerConfigStore, providerKeychainStore);
+        await clearStaleProviderConfig(providerConfigStore, providerKeychainStore, providerOAuthTokenStore);
         // State endpoint: provider config — agents request this on startup and after provider:updated
-        transportServer.onRequest(TransportStateEventNames.GET_PROVIDER_CONFIG, async () => resolveProviderConfig(providerConfigStore, providerKeychainStore));
+        transportServer.onRequest(TransportStateEventNames.GET_PROVIDER_CONFIG, async () => resolveProviderConfig(providerConfigStore, providerKeychainStore, tokenRefreshManager));
         // Feature handlers (auth, init, status, push, pull, etc.) require async OIDC discovery.
         // Placed after daemon:getState so the debug endpoint is available immediately,
         // without waiting for OIDC discovery (~400ms).
@@ -357,6 +367,7 @@ async function main() {
             projectRegistry,
             providerConfigStore,
             providerKeychainStore,
+            providerOAuthTokenStore,
             resolveProjectPath: (clientId) => clientManager.getClient(clientId)?.projectPath,
             transport: transportServer,
         });

package/dist/server/infra/http/models-dev-client.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Models.dev Client
+ *
+ * Fetches model metadata from https://models.dev/api.json — a centralized
+ * third-party model database. Caches to disk with 60-minute TTL.
+ * Used by OpenAIModelFetcher to get dynamic Codex model lists for OAuth.
+ */
+import type { ProviderModelInfo } from '../../core/interfaces/i-provider-model-fetcher.js';
+export declare class ModelsDevClient {
+    private readonly cachePath;
+    private inMemoryCache;
+    constructor(cachePath?: string);
+    /**
+     * Get models for a specific provider, transformed to ProviderModelInfo[].
+     */
+    getModelsForProvider(providerId: string, forceRefresh?: boolean): Promise<ProviderModelInfo[]>;
+    /**
+     * Force refresh the cache from models.dev.
+     */
+    refresh(): Promise<void>;
+    private fetchAndCache;
+    private getData;
+    private readDiskCache;
+}
+export declare function getModelsDevClient(): ModelsDevClient;
+/**
+ * Reset the singleton (for testing).
+ */
+export declare function resetModelsDevClient(): void;

package/dist/server/infra/http/models-dev-client.js

@@ -0,0 +1,133 @@
+/**
+ * Models.dev Client
+ *
+ * Fetches model metadata from https://models.dev/api.json — a centralized
+ * third-party model database. Caches to disk with 60-minute TTL.
+ * Used by OpenAIModelFetcher to get dynamic Codex model lists for OAuth.
+ */
+import axios from 'axios';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { getGlobalDataDir } from '../../utils/global-data-path.js';
+const CacheEnvelopeSchema = z.object({
+    data: z.record(z.unknown()),
+    timestamp: z.number(),
+});
+// ============================================================================
+// Constants
+// ============================================================================
+const MODELS_DEV_URL = 'https://models.dev/api.json';
+const CACHE_TTL_MS = 60 * 60 * 1000; // 60 minutes
+const FETCH_TIMEOUT_MS = 10_000;
+// ============================================================================
+// Client
+// ============================================================================
+export class ModelsDevClient {
+    cachePath;
+    inMemoryCache;
+    constructor(cachePath) {
+        this.cachePath = cachePath ?? join(getGlobalDataDir(), 'models-dev.json');
+    }
+    /**
+     * Get models for a specific provider, transformed to ProviderModelInfo[].
+     */
+    async getModelsForProvider(providerId, forceRefresh = false) {
+        const data = await this.getData(forceRefresh);
+        const provider = data[providerId];
+        if (!provider)
+            return [];
+        return Object.values(provider.models).map((model) => ({
+            contextLength: model.limit.context,
+            id: model.id,
+            isFree: !model.cost,
+            name: model.name,
+            pricing: {
+                inputPerM: model.cost?.input ?? 0,
+                outputPerM: model.cost?.output ?? 0,
+            },
+            provider: provider.name,
+        }));
+    }
+    /**
+     * Force refresh the cache from models.dev.
+     */
+    async refresh() {
+        await this.fetchAndCache();
+    }
+    async fetchAndCache() {
+        const response = await axios.get(MODELS_DEV_URL, {
+            timeout: FETCH_TIMEOUT_MS,
+        });
+        const { data } = response;
+        const envelope = { data, timestamp: Date.now() };
+        this.inMemoryCache = envelope;
+        // Write to disk (best-effort, don't throw on failure)
+        try {
+            await mkdir(dirname(this.cachePath), { recursive: true });
+            await writeFile(this.cachePath, JSON.stringify(envelope), 'utf8');
+        }
+        catch {
+            // Cache write failure is non-fatal
+        }
+        return data;
+    }
+    async getData(forceRefresh) {
+        // Check in-memory cache
+        if (!forceRefresh && this.inMemoryCache && Date.now() - this.inMemoryCache.timestamp < CACHE_TTL_MS) {
+            return this.inMemoryCache.data;
+        }
+        // Try disk cache
+        if (!forceRefresh) {
+            const diskCache = await this.readDiskCache();
+            if (diskCache && Date.now() - diskCache.timestamp < CACHE_TTL_MS) {
+                this.inMemoryCache = diskCache;
+                return diskCache.data;
+            }
+        }
+        // Fetch from network
+        try {
+            return await this.fetchAndCache();
+        }
+        catch {
+            // Network failure: fall back to stale disk cache (any age)
+            const staleCache = this.inMemoryCache ?? (await this.readDiskCache());
+            if (staleCache) {
+                this.inMemoryCache = staleCache;
+                return staleCache.data;
+            }
+            // No cache at all — return empty
+            return {};
+        }
+    }
+    async readDiskCache() {
+        try {
+            const content = await readFile(this.cachePath, 'utf8');
+            const parsed = JSON.parse(content);
+            const result = CacheEnvelopeSchema.safeParse(parsed);
+            if (result.success) {
+                return result.data;
+            }
+        }
+        catch {
+            // Cache read failure is non-fatal
+        }
+        return undefined;
+    }
+}
+/**
+ * Singleton instance for the models.dev client.
+ */
+let clientInstance;
+export function getModelsDevClient() {
+    if (!clientInstance) {
+        clientInstance = new ModelsDevClient();
+    }
+    return clientInstance;
+}
+/**
+ * Reset the singleton (for testing).
+ */
+export function resetModelsDevClient() {
+    clientInstance = undefined;
+}

package/dist/server/infra/http/openrouter-api-client.js

@@ -129,7 +129,7 @@ export class OpenRouterApiClient {
                 inputPerM,
                 outputPerM,
             },
-            provider: provider.charAt(0).toUpperCase() + provider.slice(1), // Capitalize
+            provider: `OpenRouter (${provider})`,
         };
     }
 }

package/dist/server/infra/http/provider-model-fetcher-registry.d.ts

@@ -23,9 +23,10 @@ export declare function clearModelFetcherCache(): void;
  *
  * @param apiKey - API key to validate
  * @param providerId - Provider identifier
+ * @param authMethod - How this provider is authenticated (OAuth providers skip validation)
  * @returns Validation result, or {isValid: false} if no fetcher exists
  */
-export declare function validateApiKey(apiKey: string, providerId: string): Promise<{
+export declare function validateApiKey(apiKey: string, providerId: string, authMethod?: 'api-key' | 'oauth'): Promise<{
     error?: string;
     isValid: boolean;
 }>;

package/dist/server/infra/http/provider-model-fetcher-registry.js

@@ -106,9 +106,14 @@ export function clearModelFetcherCache() {
  *
  * @param apiKey - API key to validate
  * @param providerId - Provider identifier
+ * @param authMethod - How this provider is authenticated (OAuth providers skip validation)
  * @returns Validation result, or {isValid: false} if no fetcher exists
  */
-export async function validateApiKey(apiKey, providerId) {
+export async function validateApiKey(apiKey, providerId, authMethod) {
+    // OAuth tokens are validated via the token exchange flow, not API key validation
+    if (authMethod === 'oauth') {
+        return { isValid: true };
+    }
     const fetcher = await getModelFetcher(providerId);
     if (!fetcher) {
         return { error: `No model fetcher available for provider: ${providerId}`, isValid: false };