byterover-cli 2.1.5 → 2.3.0

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).
@@ -352,9 +362,12 @@ async function main() {
             broadcastToProject(projectPath, event, data) {
                 broadcastToProjectRoom(projectRegistry, projectRouter, projectPath, event, data);
             },
+            getActiveProjectPaths: () => clientManager.getActiveProjects(),
             log,
+            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/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 };

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

@@ -8,7 +8,8 @@
  * - OpenAICompatibleModelFetcher: Generic for xAI/Groq/Mistral (REST API)
  * - OpenRouterModelFetcher: Wraps existing OpenRouterApiClient
  */
-import type { IProviderModelFetcher, ProviderModelInfo } from '../../core/interfaces/i-provider-model-fetcher.js';
+import type { FetchModelsOptions, IProviderModelFetcher, ProviderModelInfo } from '../../core/interfaces/i-provider-model-fetcher.js';
+import { type ModelsDevClient } from './models-dev-client.js';
 /**
  * Fetches models from Anthropic using the official SDK.
  */
@@ -16,26 +17,50 @@ export declare class AnthropicModelFetcher implements IProviderModelFetcher {
     private cache;
     private readonly cacheTtlMs;
     constructor(cacheTtlMs?: number);
-    fetchModels(apiKey: string, forceRefresh?: boolean): Promise<ProviderModelInfo[]>;
+    fetchModels(apiKey: string, options?: FetchModelsOptions): Promise<ProviderModelInfo[]>;
     validateApiKey(apiKey: string): Promise<{
         error?: string;
         isValid: boolean;
     }>;
 }
+/**
+ * Strict allowlist of model IDs permitted for OAuth-connected OpenAI (Codex).
+ * Only models verified to work with the ChatGPT Codex endpoint are included.
+ *
+ * NOT supported (Bad Request on chatgpt.com/backend-api/codex):
+ * - codex-mini-latest: standard API model, not a Codex endpoint model
+ * - o4-mini: reasoning model, not supported by the Codex endpoint
+ * - gpt-5.3-codex-spark: reported unsupported (GitHub openai/codex#13469)
+ */
+export declare const CODEX_ALLOWED_MODELS: Set<string>;
+/**
+ * Fallback Codex models used when models.dev is unreachable and no disk cache exists.
+ */
+export declare const CODEX_FALLBACK_MODELS: readonly ProviderModelInfo[];
 /**
  * Fetches models from OpenAI using the official SDK.
+ * For OAuth-connected providers, fetches from models.dev and filters to Codex-allowed models.
  */
 export declare class OpenAIModelFetcher implements IProviderModelFetcher {
     private cache;
     private readonly cacheTtlMs;
-    constructor(cacheTtlMs?: number);
-    fetchModels(apiKey: string, forceRefresh?: boolean): Promise<ProviderModelInfo[]>;
+    private readonly getModelsDevClient;
+    constructor(options?: {
+        cacheTtlMs?: number;
+        modelsDevClient?: ModelsDevClient;
+    });
+    fetchModels(apiKey: string, options?: FetchModelsOptions): Promise<ProviderModelInfo[]>;
     validateApiKey(apiKey: string): Promise<{
         error?: string;
         isValid: boolean;
     }>;
     private estimateContextLength;
     private estimatePricing;
+    /**
+     * Fetch Codex models from models.dev, filtered by allowlist.
+     * Falls back to CODEX_FALLBACK_MODELS if models.dev is unavailable.
+     */
+    private fetchCodexModels;
 }
 /**
  * Fetches models from Google using the @google/genai SDK.
@@ -44,7 +69,7 @@ export declare class GoogleModelFetcher implements IProviderModelFetcher {
     private cache;
     private readonly cacheTtlMs;
     constructor(cacheTtlMs?: number);
-    fetchModels(apiKey: string, forceRefresh?: boolean): Promise<ProviderModelInfo[]>;
+    fetchModels(apiKey: string, options?: FetchModelsOptions): Promise<ProviderModelInfo[]>;
     validateApiKey(apiKey: string): Promise<{
         error?: string;
         isValid: boolean;
@@ -60,7 +85,7 @@ export declare class OpenAICompatibleModelFetcher implements IProviderModelFetch
     private readonly cacheTtlMs;
     private readonly providerName;
     constructor(baseUrl: string, providerName: string, cacheTtlMs?: number);
-    fetchModels(apiKey: string, forceRefresh?: boolean): Promise<ProviderModelInfo[]>;
+    fetchModels(apiKey: string, options?: FetchModelsOptions): Promise<ProviderModelInfo[]>;
     validateApiKey(apiKey: string): Promise<{
         error?: string;
         isValid: boolean;
@@ -75,7 +100,7 @@ export declare class ChatBasedModelFetcher implements IProviderModelFetcher {
     private readonly baseUrl;
     private readonly knownModels;
     constructor(baseUrl: string, providerName: string, knownModels: string[]);
-    fetchModels(_apiKey: string, _forceRefresh?: boolean): Promise<ProviderModelInfo[]>;
+    fetchModels(_apiKey: string, _options?: FetchModelsOptions): Promise<ProviderModelInfo[]>;
     validateApiKey(apiKey: string): Promise<{
         error?: string;
         isValid: boolean;
@@ -86,7 +111,7 @@ export declare class ChatBasedModelFetcher implements IProviderModelFetcher {
  * Adapts NormalizedModel to ProviderModelInfo.
  */
 export declare class OpenRouterModelFetcher implements IProviderModelFetcher {
-    fetchModels(apiKey: string, forceRefresh?: boolean): Promise<ProviderModelInfo[]>;
+    fetchModels(apiKey: string, options?: FetchModelsOptions): Promise<ProviderModelInfo[]>;
     validateApiKey(apiKey: string): Promise<{
         error?: string;
         isValid: boolean;