byterover-cli 2.1.5 → 2.3.0

package/dist/server/infra/http/provider-model-fetchers.js

@@ -15,6 +15,7 @@ import { GoogleGenAI } from '@google/genai';
 import { APICallError, generateText } from 'ai';
 import axios, { isAxiosError } from 'axios';
 import OpenAI from 'openai';
+import { getModelsDevClient as getModelsDevClientDefault } from './models-dev-client.js';
 const DEFAULT_CACHE_TTL = 60 * 60 * 1000; // 1 hour
 const ANTHROPIC_KNOWN_MODELS = {
     'claude-3-5-haiku-20241022': { contextLength: 200_000, inputPerM: 0.8, outputPerM: 4 },
@@ -60,7 +61,8 @@ export class AnthropicModelFetcher {
     constructor(cacheTtlMs = DEFAULT_CACHE_TTL) {
         this.cacheTtlMs = cacheTtlMs;
     }
-    async fetchModels(apiKey, forceRefresh = false) {
+    async fetchModels(apiKey, options) {
+        const forceRefresh = options?.forceRefresh ?? false;
         if (!forceRefresh && this.cache && Date.now() - this.cache.timestamp < this.cacheTtlMs) {
             return this.cache.models;
         }
@@ -101,16 +103,64 @@ export class AnthropicModelFetcher {
 // ============================================================================
 // OpenAI Model Fetcher
 // ============================================================================
+/**
+ * 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 const CODEX_ALLOWED_MODELS = new Set([
+    'gpt-5.1-codex',
+    'gpt-5.1-codex-max',
+    'gpt-5.1-codex-mini',
+    'gpt-5.2',
+    'gpt-5.2-codex',
+    'gpt-5.3-codex',
+    'gpt-5.4',
+]);
+/**
+ * Fallback Codex models used when models.dev is unreachable and no disk cache exists.
+ */
+export const CODEX_FALLBACK_MODELS = [
+    {
+        contextLength: 400_000,
+        id: 'gpt-5.3-codex',
+        isFree: false,
+        name: 'GPT-5.3 Codex',
+        pricing: { inputPerM: 0, outputPerM: 0 },
+        provider: 'OpenAI',
+    },
+    {
+        contextLength: 200_000,
+        id: 'gpt-5.1-codex-mini',
+        isFree: false,
+        name: 'GPT-5.1 Codex Mini',
+        pricing: { inputPerM: 0, outputPerM: 0 },
+        provider: 'OpenAI',
+    },
+];
 /**
  * Fetches models from OpenAI using the official SDK.
+ * For OAuth-connected providers, fetches from models.dev and filters to Codex-allowed models.
  */
 export class OpenAIModelFetcher {
     cache;
     cacheTtlMs;
-    constructor(cacheTtlMs = DEFAULT_CACHE_TTL) {
-        this.cacheTtlMs = cacheTtlMs;
+    getModelsDevClient;
+    constructor(options) {
+        this.cacheTtlMs = options?.cacheTtlMs ?? DEFAULT_CACHE_TTL;
+        const injectedClient = options?.modelsDevClient;
+        this.getModelsDevClient = injectedClient ? () => injectedClient : () => getModelsDevClientDefault();
     }
-    async fetchModels(apiKey, forceRefresh = false) {
+    async fetchModels(apiKey, options) {
+        // OAuth-connected OpenAI: fetch from models.dev, filter to Codex models
+        if (options?.authMethod === 'oauth') {
+            return this.fetchCodexModels(options.forceRefresh ?? false);
+        }
+        const forceRefresh = options?.forceRefresh ?? false;
         if (!forceRefresh && this.cache && Date.now() - this.cache.timestamp < this.cacheTtlMs) {
             return this.cache.models;
         }
@@ -198,6 +248,29 @@ export class OpenAIModelFetcher {
             return { inputPerM: 15, outputPerM: 60 };
         return { inputPerM: 0, outputPerM: 0 };
     }
+    /**
+     * Fetch Codex models from models.dev, filtered by allowlist.
+     * Falls back to CODEX_FALLBACK_MODELS if models.dev is unavailable.
+     */
+    async fetchCodexModels(forceRefresh) {
+        const client = this.getModelsDevClient();
+        const allModels = await client.getModelsForProvider('openai', forceRefresh);
+        if (allModels.length === 0) {
+            return [...CODEX_FALLBACK_MODELS];
+        }
+        // Strict allowlist only — dynamic "codex in name" matching is too broad
+        // (e.g. codex-mini-latest, gpt-5.3-codex-spark cause Bad Request)
+        const codexModels = allModels.filter((m) => CODEX_ALLOWED_MODELS.has(m.id));
+        if (codexModels.length === 0) {
+            return [...CODEX_FALLBACK_MODELS];
+        }
+        // Zero out costs (included in ChatGPT subscription)
+        return codexModels.map((m) => ({
+            ...m,
+            isFree: false,
+            pricing: { inputPerM: 0, outputPerM: 0 },
+        }));
+    }
 }
 // ============================================================================
 // Google Model Fetcher
@@ -211,7 +284,8 @@ export class GoogleModelFetcher {
     constructor(cacheTtlMs = DEFAULT_CACHE_TTL) {
         this.cacheTtlMs = cacheTtlMs;
     }
-    async fetchModels(apiKey, forceRefresh = false) {
+    async fetchModels(apiKey, options) {
+        const forceRefresh = options?.forceRefresh ?? false;
         if (!forceRefresh && this.cache && Date.now() - this.cache.timestamp < this.cacheTtlMs) {
             return this.cache.models;
         }
@@ -265,7 +339,8 @@ export class OpenAICompatibleModelFetcher {
         this.providerName = providerName;
         this.cacheTtlMs = cacheTtlMs;
     }
-    async fetchModels(apiKey, forceRefresh = false) {
+    async fetchModels(apiKey, options) {
+        const forceRefresh = options?.forceRefresh ?? false;
         if (!forceRefresh && this.cache && Date.now() - this.cache.timestamp < this.cacheTtlMs) {
             return this.cache.models;
         }
@@ -342,7 +417,7 @@ export class ChatBasedModelFetcher {
             provider: providerName,
         }));
     }
-    async fetchModels(_apiKey, _forceRefresh = false) {
+    async fetchModels(_apiKey, _options) {
         return this.knownModels;
     }
     async validateApiKey(apiKey) {
@@ -384,9 +459,9 @@ import { getOpenRouterApiClient } from './openrouter-api-client.js';
  * Adapts NormalizedModel to ProviderModelInfo.
  */
 export class OpenRouterModelFetcher {
-    async fetchModels(apiKey, forceRefresh = false) {
+    async fetchModels(apiKey, options) {
         const client = getOpenRouterApiClient();
-        const models = await client.fetchModels(apiKey, forceRefresh);
+        const models = await client.fetchModels(apiKey, options?.forceRefresh ?? false);
         return models.map((m) => ({
             contextLength: m.contextLength,
             description: m.description,
@@ -438,7 +513,10 @@ function handleAiSdkValidationError(error) {
 function handleSdkValidationError(error) {
     if (error instanceof Error) {
         const message = error.message.toLowerCase();
-        if (message.includes('401') || message.includes('unauthorized') || message.includes('invalid api key') || message.includes('authentication')) {
+        if (message.includes('401') ||
+            message.includes('unauthorized') ||
+            message.includes('invalid api key') ||
+            message.includes('authentication')) {
             return { error: `Authentication failed: ${error.message}`, isValid: false };
         }
         if (message.includes('403') || message.includes('forbidden') || message.includes('permission')) {

package/dist/server/infra/process/feature-handlers.d.ts

@@ -6,15 +6,20 @@
  */
 import type { IProviderConfigStore } from '../../core/interfaces/i-provider-config-store.js';
 import type { IProviderKeychainStore } from '../../core/interfaces/i-provider-keychain-store.js';
+import type { IProviderOAuthTokenStore } from '../../core/interfaces/i-provider-oauth-token-store.js';
+import type { IProjectRegistry } from '../../core/interfaces/project/i-project-registry.js';
 import type { IAuthStateStore } from '../../core/interfaces/state/i-auth-state-store.js';
 import type { ITransportServer } from '../../core/interfaces/transport/i-transport-server.js';
 import type { ProjectBroadcaster, ProjectPathResolver } from '../transport/handlers/handler-types.js';
 export interface FeatureHandlersOptions {
     authStateStore: IAuthStateStore;
     broadcastToProject: ProjectBroadcaster;
+    getActiveProjectPaths: () => string[];
     log: (msg: string) => void;
+    projectRegistry: IProjectRegistry;
     providerConfigStore: IProviderConfigStore;
     providerKeychainStore: IProviderKeychainStore;
+    providerOAuthTokenStore: IProviderOAuthTokenStore;
     resolveProjectPath: ProjectPathResolver;
     transport: ITransportServer;
 }
@@ -22,4 +27,4 @@ export interface FeatureHandlersOptions {
  * Setup all feature handlers on the transport server.
  * These handlers implement the TUI ↔ Server event contract (auth:*, config:*, status:*, etc.).
  */
-export declare function setupFeatureHandlers({ authStateStore, broadcastToProject, log, providerConfigStore, providerKeychainStore, resolveProjectPath, transport, }: FeatureHandlersOptions): Promise<void>;
+export declare function setupFeatureHandlers({ authStateStore, broadcastToProject, getActiveProjectPaths, log, projectRegistry, providerConfigStore, providerKeychainStore, providerOAuthTokenStore, resolveProjectPath, transport, }: FeatureHandlersOptions): Promise<void>;

package/dist/server/infra/process/feature-handlers.js

@@ -29,13 +29,13 @@ import { HttpSpaceService } from '../space/http-space-service.js';
 import { createTokenStore } from '../storage/token-store.js';
 import { HttpTeamService } from '../team/http-team-service.js';
 import { FsTemplateLoader } from '../template/fs-template-loader.js';
-import { AuthHandler, ConfigHandler, ConnectorsHandler, HubHandler, InitHandler, ModelHandler, ProviderHandler, PullHandler, PushHandler, ResetHandler, SpaceHandler, StatusHandler, } from '../transport/handlers/index.js';
+import { AuthHandler, ConfigHandler, ConnectorsHandler, HubHandler, InitHandler, LocationsHandler, ModelHandler, ProviderHandler, PullHandler, PushHandler, ResetHandler, SpaceHandler, StatusHandler, } from '../transport/handlers/index.js';
 import { HttpUserService } from '../user/http-user-service.js';
 /**
  * Setup all feature handlers on the transport server.
  * These handlers implement the TUI ↔ Server event contract (auth:*, config:*, status:*, etc.).
  */
-export async function setupFeatureHandlers({ authStateStore, broadcastToProject, log, providerConfigStore, providerKeychainStore, resolveProjectPath, transport, }) {
+export async function setupFeatureHandlers({ authStateStore, broadcastToProject, getActiveProjectPaths, log, projectRegistry, providerConfigStore, providerKeychainStore, providerOAuthTokenStore, resolveProjectPath, transport, }) {
     const envConfig = getCurrentConfig();
     const tokenStore = createTokenStore();
     const projectConfigStore = new ProjectConfigStore();
@@ -59,8 +59,10 @@ export async function setupFeatureHandlers({ authStateStore, broadcastToProject,
         userService,
     }).setup();
     new ProviderHandler({
+        browserLauncher: new SystemBrowserLauncher(),
         providerConfigStore,
         providerKeychainStore,
+        providerOAuthTokenStore,
         transport,
     }).setup();
     new ModelHandler({
@@ -90,6 +92,13 @@ export async function setupFeatureHandlers({ authStateStore, broadcastToProject,
         tokenStore,
         transport,
     }).setup();
+    new LocationsHandler({
+        contextTreeService,
+        getActiveProjectPaths,
+        projectRegistry,
+        resolveProjectPath,
+        transport,
+    }).setup();
     new PushHandler({
         broadcastToProject,
         cogitPushService,

package/dist/server/infra/provider/provider-config-resolver.d.ts

@@ -7,6 +7,8 @@
  */
 import type { IProviderConfigStore } from '../../core/interfaces/i-provider-config-store.js';
 import type { IProviderKeychainStore } from '../../core/interfaces/i-provider-keychain-store.js';
+import type { IProviderOAuthTokenStore } from '../../core/interfaces/i-provider-oauth-token-store.js';
+import type { ITokenRefreshManager } from '../../core/interfaces/i-token-refresh-manager.js';
 import { type ProviderConfigResponse } from '../../core/domain/transport/schemas.js';
 /**
  * Validate provider config integrity at startup.
@@ -19,7 +21,7 @@ import { type ProviderConfigResponse } from '../../core/domain/transport/schemas
  * empty string so the TUI routes to the provider setup flow — bypassing the
  * 'byterover' fallback that withProviderDisconnected() would otherwise apply.
  */
-export declare function clearStaleProviderConfig(providerConfigStore: IProviderConfigStore, providerKeychainStore: IProviderKeychainStore): Promise<void>;
+export declare function clearStaleProviderConfig(providerConfigStore: IProviderConfigStore, providerKeychainStore: IProviderKeychainStore, providerOAuthTokenStore?: IProviderOAuthTokenStore): Promise<void>;
 /**
  * Resolve the active provider's full configuration.
  *
@@ -27,4 +29,4 @@ export declare function clearStaleProviderConfig(providerConfigStore: IProviderC
  * the API key (keychain → env fallback), and maps provider-specific
  * fields (base URL, headers, location, etc.).
  */
-export declare function resolveProviderConfig(providerConfigStore: IProviderConfigStore, providerKeychainStore: IProviderKeychainStore): Promise<ProviderConfigResponse>;
+export declare function resolveProviderConfig(providerConfigStore: IProviderConfigStore, providerKeychainStore: IProviderKeychainStore, tokenRefreshManager?: ITokenRefreshManager): Promise<ProviderConfigResponse>;

package/dist/server/infra/provider/provider-config-resolver.js

@@ -5,8 +5,18 @@
  * for the currently active provider. Used by the daemon state server to serve
  * agent child processes on startup and after provider hot-swap.
  */
+import { CHATGPT_OAUTH_BASE_URL, CHATGPT_OAUTH_ORIGINATOR } from '../../../shared/constants/oauth.js';
 import { getProviderById, providerRequiresApiKey } from '../../core/domain/entities/provider-registry.js';
 import { getProviderApiKeyFromEnv } from './env-provider-detector.js';
+/**
+ * Check if a provider's credential (API key or OAuth access token) is accessible.
+ *
+ * Note: authMethod is intentionally NOT passed to providerRequiresApiKey() here.
+ * OAuth access tokens are stored in the keychain (as the provider's "API key"),
+ * so the keychain check on the next line correctly handles both auth methods.
+ * If an OAuth token expires and the refresh manager (Issue 5) deletes it from
+ * keychain, this function returns false — correctly marking the provider as stale.
+ */
 async function isProviderCredentialAccessible(providerId, providerKeychainStore) {
     if (!providerRequiresApiKey(providerId))
         return true;
@@ -23,7 +33,7 @@ async function isProviderCredentialAccessible(providerId, providerKeychainStore)
  * empty string so the TUI routes to the provider setup flow — bypassing the
  * 'byterover' fallback that withProviderDisconnected() would otherwise apply.
  */
-export async function clearStaleProviderConfig(providerConfigStore, providerKeychainStore) {
+export async function clearStaleProviderConfig(providerConfigStore, providerKeychainStore, providerOAuthTokenStore) {
     try {
         const config = await providerConfigStore.read();
         const results = await Promise.all(Object.keys(config.providers).map(async (providerId) => ({
@@ -46,6 +56,11 @@ export async function clearStaleProviderConfig(providerConfigStore, providerKeyc
             newConfig = newConfig.withActiveProvider('');
         }
         await providerConfigStore.write(newConfig);
+        // Clean up orphaned OAuth tokens for stale providers (consistent with
+        // the 3-store cleanup in TokenRefreshManager and ProviderHandler.setupDisconnect)
+        if (providerOAuthTokenStore) {
+            await Promise.all(staleProviderIds.map((id) => providerOAuthTokenStore.delete(id).catch(() => { })));
+        }
     }
     catch {
         // Non-critical: if validation fails, daemon continues normally.
@@ -59,7 +74,7 @@ export async function clearStaleProviderConfig(providerConfigStore, providerKeyc
  * the API key (keychain → env fallback), and maps provider-specific
  * fields (base URL, headers, location, etc.).
  */
-export async function resolveProviderConfig(providerConfigStore, providerKeychainStore) {
+export async function resolveProviderConfig(providerConfigStore, providerKeychainStore, tokenRefreshManager) {
     const config = await providerConfigStore.read();
     const { activeProvider } = config;
     const activeModel = config.getActiveModel(activeProvider);
@@ -96,16 +111,56 @@ export async function resolveProviderConfig(providerConfigStore, providerKeychai
         }
         default: {
             const providerDef = getProviderById(activeProvider);
+            const providerConfig = config.providers[activeProvider];
+            if (!providerConfig) {
+                return { activeModel, activeProvider, maxInputTokens };
+            }
+            const { authMethod } = providerConfig;
+            // Attempt OAuth token refresh if provider is OAuth-connected
+            if (authMethod === 'oauth' && tokenRefreshManager) {
+                try {
+                    const refreshed = await tokenRefreshManager.refreshIfNeeded(activeProvider);
+                    if (!refreshed) {
+                        return { activeModel, activeProvider, authMethod, maxInputTokens, providerKeyMissing: true };
+                    }
+                    // Re-read API key after potential refresh
+                    apiKey = (await providerKeychainStore.getApiKey(activeProvider)) ?? apiKey;
+                }
+                catch {
+                    return { activeModel, activeProvider, authMethod, maxInputTokens, providerKeyMissing: true };
+                }
+            }
+            // OAuth-connected OpenAI: use Codex endpoint + required headers
+            if (activeProvider === 'openai' && authMethod === 'oauth') {
+                const codexHeaders = {
+                    originator: CHATGPT_OAUTH_ORIGINATOR,
+                };
+                if (providerConfig.oauthAccountId) {
+                    codexHeaders['ChatGPT-Account-Id'] = providerConfig.oauthAccountId;
+                }
+                return {
+                    activeModel,
+                    activeProvider,
+                    authMethod,
+                    maxInputTokens,
+                    provider: activeProvider,
+                    providerApiKey: apiKey || undefined,
+                    providerBaseUrl: CHATGPT_OAUTH_BASE_URL,
+                    providerHeaders: codexHeaders,
+                    providerKeyMissing: providerRequiresApiKey(activeProvider, authMethod) && !apiKey,
+                };
+            }
             const headers = providerDef?.headers;
             return {
                 activeModel,
                 activeProvider,
+                authMethod,
                 maxInputTokens,
                 provider: activeProvider,
                 providerApiKey: apiKey || undefined,
-                providerBaseUrl: providerDef?.baseUrl || undefined,
+                providerBaseUrl: config.getBaseUrl(activeProvider) || providerDef?.baseUrl || undefined,
                 providerHeaders: headers && Object.keys(headers).length > 0 ? { ...headers } : undefined,
-                providerKeyMissing: providerRequiresApiKey(activeProvider) && !apiKey,
+                providerKeyMissing: providerRequiresApiKey(activeProvider, authMethod) && !apiKey,
             };
         }
     }

package/dist/server/infra/provider-oauth/callback-server.d.ts

@@ -0,0 +1,24 @@
+import type { ProviderCallbackResult } from './types.js';
+type ProviderCallbackServerOptions = {
+    callbackPath?: string;
+    port: number;
+};
+export declare class ProviderCallbackServer {
+    private readonly callbackPath;
+    private readonly connections;
+    private isStopping;
+    private onCallback;
+    private onError;
+    private pendingTimeout;
+    private readonly port;
+    private server;
+    constructor(options: ProviderCallbackServerOptions);
+    getAddress(): undefined | {
+        port: number;
+    };
+    start(): Promise<number>;
+    stop(): Promise<void>;
+    waitForCallback(expectedState: string, timeoutMs?: number): Promise<ProviderCallbackResult>;
+    private handleRequest;
+}
+export {};

package/dist/server/infra/provider-oauth/callback-server.js

@@ -0,0 +1,203 @@
+import http from 'node:http';
+import { OAUTH_CALLBACK_TIMEOUT_MS } from '../../../shared/constants/oauth.js';
+import { ProviderCallbackOAuthError, ProviderCallbackStateError, ProviderCallbackTimeoutError, ProviderOAuthError, } from './errors.js';
+const DEFAULT_CALLBACK_PATH = '/auth/callback';
+const SUCCESS_HTML = `<!DOCTYPE html>
+<html>
+<head>
+  <title>ByteRover - Authorization Successful</title>
+  <style>
+    body { font-family: 'Plus Jakarta Sans', system-ui, -apple-system, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #0f0f0f; color: #e5e5e5; }
+    .container { text-align: center; padding: 2rem; }
+    h1 { color: #17b26a; margin-bottom: 1rem; }
+    p { color: #a3a3a3; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>Authorization Successful</h1>
+    <p>You can close this window and return to ByteRover.</p>
+  </div>
+  <script>setTimeout(() => window.close(), 2000);</script>
+</body>
+</html>`;
+function errorHtml(message) {
+    return `<!DOCTYPE html>
+<html>
+<head>
+  <title>ByteRover - Authorization Failed</title>
+  <style>
+    body { font-family: 'Plus Jakarta Sans', system-ui, -apple-system, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #0f0f0f; color: #e5e5e5; }
+    .container { text-align: center; padding: 2rem; }
+    h1 { color: #f87171; margin-bottom: 1rem; }
+    p { color: #a3a3a3; }
+    .error { color: #fca5a5; font-family: monospace; margin-top: 1rem; padding: 1rem; background: rgba(248,113,113,0.1); border-radius: 0.5rem; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>Authorization Failed</h1>
+    <p>An error occurred during authorization.</p>
+    <div class="error">${escapeHtml(message)}</div>
+  </div>
+</body>
+</html>`;
+}
+function escapeHtml(text) {
+    return text
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+}
+export class ProviderCallbackServer {
+    callbackPath;
+    connections = new Set();
+    isStopping = false;
+    onCallback;
+    onError;
+    pendingTimeout;
+    port;
+    server = undefined;
+    constructor(options) {
+        this.port = options.port;
+        this.callbackPath = options.callbackPath ?? DEFAULT_CALLBACK_PATH;
+    }
+    getAddress() {
+        const address = this.server?.address();
+        if (address !== null && address !== undefined && typeof address !== 'string') {
+            return { port: address.port };
+        }
+        return undefined;
+    }
+    async start() {
+        const address = this.getAddress();
+        if (address !== undefined) {
+            return address.port;
+        }
+        return new Promise((resolve, reject) => {
+            this.server = http.createServer((req, res) => {
+                this.handleRequest(req, res);
+            });
+            this.server.on('connection', (conn) => {
+                this.connections.add(conn);
+                conn.on('close', () => {
+                    this.connections.delete(conn);
+                });
+            });
+            this.server.on('error', reject);
+            this.server.listen(this.port, '127.0.0.1', () => {
+                const address = this.server?.address();
+                if (address !== null && address !== undefined && typeof address !== 'string') {
+                    resolve(address.port);
+                }
+                else {
+                    reject(new Error('Failed to start provider callback server'));
+                }
+            });
+        });
+    }
+    async stop() {
+        if (this.isStopping)
+            return;
+        this.isStopping = true;
+        // Reject any pending waitForCallback promise so consumers don't hang
+        this.onError?.(new ProviderOAuthError('Callback server was stopped'));
+        this.onCallback = undefined;
+        this.onError = undefined;
+        if (this.pendingTimeout !== undefined) {
+            clearTimeout(this.pendingTimeout);
+            this.pendingTimeout = undefined;
+        }
+        return new Promise((resolve) => {
+            if (this.server === undefined) {
+                this.isStopping = false;
+                resolve();
+                return;
+            }
+            for (const conn of this.connections) {
+                conn.destroy();
+            }
+            this.connections.clear();
+            this.server.close(() => {
+                this.server = undefined;
+                this.isStopping = false;
+                resolve();
+            });
+        });
+    }
+    waitForCallback(expectedState, timeoutMs = OAUTH_CALLBACK_TIMEOUT_MS) {
+        if (this.onCallback !== undefined) {
+            return Promise.reject(new ProviderOAuthError('A callback is already pending'));
+        }
+        const promise = new Promise((resolve, reject) => {
+            let settled = false;
+            this.pendingTimeout = setTimeout(() => {
+                if (!settled) {
+                    settled = true;
+                    this.pendingTimeout = undefined;
+                    reject(new ProviderCallbackTimeoutError(timeoutMs));
+                }
+            }, timeoutMs);
+            this.onCallback = (code, state) => {
+                if (settled)
+                    return;
+                clearTimeout(this.pendingTimeout);
+                this.pendingTimeout = undefined;
+                if (state !== expectedState) {
+                    settled = true;
+                    reject(new ProviderCallbackStateError());
+                    return;
+                }
+                settled = true;
+                resolve({ code, state });
+            };
+            this.onError = (error) => {
+                if (settled)
+                    return;
+                clearTimeout(this.pendingTimeout);
+                this.pendingTimeout = undefined;
+                settled = true;
+                reject(error);
+            };
+        });
+        // Auto-close server after callback or timeout (ticket requirement)
+        const autoClose = () => this.stop();
+        promise.then(autoClose, autoClose);
+        return promise;
+    }
+    handleRequest(req, res) {
+        const url = new URL(req.url ?? '/', `http://localhost:${this.port}`);
+        if (url.pathname !== this.callbackPath) {
+            res.writeHead(404);
+            res.end('Not found');
+            return;
+        }
+        const error = url.searchParams.get('error');
+        const errorDescription = url.searchParams.get('error_description');
+        const code = url.searchParams.get('code');
+        const state = url.searchParams.get('state');
+        if (error !== null) {
+            res.writeHead(400, { 'Content-Type': 'text/html' });
+            res.end(errorHtml(errorDescription ?? error));
+            this.onError?.(new ProviderCallbackOAuthError(error, errorDescription ?? undefined));
+            this.onCallback = undefined;
+            this.onError = undefined;
+            return;
+        }
+        if (code === null || state === null) {
+            res.writeHead(400, { 'Content-Type': 'text/html' });
+            res.end(errorHtml('Missing code or state parameter'));
+            this.onError?.(new ProviderOAuthError('Missing code or state parameter'));
+            this.onCallback = undefined;
+            this.onError = undefined;
+            return;
+        }
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(SUCCESS_HTML);
+        this.onCallback?.(code, state);
+        this.onCallback = undefined;
+        this.onError = undefined;
+    }
+}

package/dist/server/infra/provider-oauth/errors.d.ts

@@ -0,0 +1,39 @@
+export declare class ProviderOAuthError extends Error {
+    constructor(message: string);
+}
+export declare class ProviderCallbackTimeoutError extends ProviderOAuthError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+export declare class ProviderCallbackStateError extends ProviderOAuthError {
+    constructor();
+}
+export declare class ProviderCallbackOAuthError extends ProviderOAuthError {
+    readonly errorCode: string;
+    constructor(errorCode: string, errorDescription?: string);
+}
+export declare class ProviderTokenExchangeError extends ProviderOAuthError {
+    readonly errorCode?: string;
+    readonly statusCode?: number;
+    constructor(params: {
+        errorCode?: string;
+        message: string;
+        statusCode?: number;
+    });
+}
+/**
+ * Extracts OAuth error fields from an unknown error response body.
+ * Shared by token-exchange and refresh-token-exchange.
+ */
+export declare function extractOAuthErrorFields(data: unknown): {
+    error?: string;
+    error_description?: string;
+};
+/**
+ * Checks whether an OAuth token refresh error is permanent (token revoked, client invalid)
+ * vs. transient (network timeout, server error).
+ *
+ * Permanent errors require disconnecting the provider and re-authenticating.
+ * Transient errors should preserve credentials so the existing access token can still be used.
+ */
+export declare function isPermanentOAuthError(error: unknown): boolean;