@tenex-chat/backend 0.9.1

package/src/llm/providers/registry/ProviderRegistry.ts

@@ -0,0 +1,414 @@
+/**
+ * Provider Registry - Central registry for all LLM providers
+ *
+ * This module provides a unified registry for managing LLM providers,
+ * supporting both standard AI SDK providers and custom agent providers.
+ * Integrates with KeyManager for multi-key rotation and fallback.
+ */
+
+import { createProviderRegistry } from "ai";
+import type { ProviderRegistryProvider } from "ai";
+import type { ProviderV3 } from "@ai-sdk/provider";
+import { logger } from "@/utils/logger";
+import { keyManager } from "../key-manager";
+import type {
+    ILLMProvider,
+    ProviderInitConfig,
+    ProviderPoolConfig,
+    ProviderMetadata,
+    ProviderRegistration,
+    ProviderRuntimeContext,
+    ProviderModelResult,
+} from "../types";
+
+/**
+ * Provider initialization result
+ */
+interface InitializationResult {
+    providerId: string;
+    success: boolean;
+    error?: string;
+}
+
+/**
+ * Central registry for all LLM providers
+ *
+ * The registry manages provider lifecycle:
+ * 1. Registration - Providers register themselves
+ * 2. Initialization - Providers are initialized with API keys
+ * 3. Model Creation - Providers create language models on demand
+ * 4. Key Rotation - Providers can be re-initialized with a different key on failure
+ */
+export class ProviderRegistry {
+    private static instance: ProviderRegistry | null = null;
+
+    private providers: Map<string, ILLMProvider> = new Map();
+    private registrations: Map<string, ProviderRegistration> = new Map();
+    private providerConfigs: Map<string, ProviderPoolConfig> = new Map();
+    private activeApiKeys: Map<string, string> = new Map();
+    private aiSdkRegistry: ProviderRegistryProvider | null = null;
+    private initialized = false;
+
+    /**
+     * Get the singleton instance
+     */
+    static getInstance(): ProviderRegistry {
+        if (!ProviderRegistry.instance) {
+            ProviderRegistry.instance = new ProviderRegistry();
+        }
+        return ProviderRegistry.instance;
+    }
+
+    /**
+     * Reset the singleton (for testing)
+     */
+    static resetInstance(): void {
+        if (ProviderRegistry.instance) {
+            ProviderRegistry.instance.reset();
+            ProviderRegistry.instance = null;
+        }
+    }
+
+    /**
+     * Register a provider class
+     * This should be called during module initialization
+     */
+    register(registration: ProviderRegistration): void {
+        const { metadata } = registration;
+
+        if (this.registrations.has(metadata.id)) {
+            logger.warn(`[ProviderRegistry] Provider "${metadata.id}" already registered, skipping`);
+            return;
+        }
+
+        this.registrations.set(metadata.id, registration);
+        logger.debug(`[ProviderRegistry] Registered provider: ${metadata.id}`);
+    }
+
+    /**
+     * Register multiple providers at once
+     */
+    registerAll(registrations: ProviderRegistration[]): void {
+        for (const reg of registrations) {
+            this.register(reg);
+        }
+    }
+
+    /**
+     * Initialize all registered providers with their configurations.
+     * Supports multi-key configs — keys are registered with KeyManager
+     * and a single key is selected for each provider's initial setup.
+     */
+    async initialize(
+        configs: Record<string, ProviderPoolConfig>
+    ): Promise<InitializationResult[]> {
+        const results: InitializationResult[] = [];
+        this.providers.clear();
+        this.providerConfigs.clear();
+        this.activeApiKeys.clear();
+
+        // Check if mock mode is enabled
+        if (process.env.USE_MOCK_LLM === "true") {
+            await this.initializeMockProvider();
+        }
+
+        // Register all key pools with KeyManager and initialize providers
+        for (const [providerId, registration] of this.registrations) {
+            const config = configs[providerId];
+            const rawKey = config?.apiKey;
+
+            // Normalize: treat empty arrays and arrays of only empty strings as "no key"
+            const apiKey = Array.isArray(rawKey)
+                ? (rawKey.filter(k => k.length > 0).length > 0 ? rawKey : undefined)
+                : (rawKey || undefined);
+
+            // Register keys with KeyManager (handles string | string[])
+            if (apiKey) {
+                keyManager.registerKeys(providerId, apiKey);
+            }
+
+            // Skip providers without config (unless they don't require API key)
+            if (!apiKey && registration.metadata.capabilities.requiresApiKey) {
+                continue;
+            }
+
+            // Store the full config for potential re-initialization
+            if (config) {
+                this.providerConfigs.set(providerId, config);
+            }
+
+            // Select a single key for this initialization
+            const selectedKey = apiKey ? keyManager.selectKey(providerId) : undefined;
+
+            try {
+                const provider = new registration.Provider();
+                const initConfig: ProviderInitConfig = {
+                    apiKey: selectedKey,
+                    baseUrl: config?.baseUrl,
+                    options: config?.options,
+                };
+                await provider.initialize(initConfig);
+                this.providers.set(providerId, provider);
+                if (selectedKey) {
+                    this.activeApiKeys.set(providerId, selectedKey);
+                }
+
+                results.push({ providerId, success: true });
+
+                logger.debug(`[ProviderRegistry] Initialized provider: ${providerId}`);
+            } catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                results.push({ providerId, success: false, error: errorMessage });
+
+                logger.error(`[ProviderRegistry] Failed to initialize provider ${providerId}`, {
+                    error: errorMessage,
+                });
+            }
+        }
+
+        // Build the AI SDK registry from standard providers
+        this.buildAiSdkRegistry();
+
+        this.initialized = true;
+
+        logger.debug(`[ProviderRegistry] Initialized ${this.providers.size} providers: ${Array.from(this.providers.keys()).join(", ")}`);
+
+        return results;
+    }
+
+    /**
+     * Re-initialize a provider with a different API key.
+     * Called when a key fails at runtime to attempt fallback.
+     *
+     * @param providerId The provider to re-initialize
+     * @param failedKey The key that failed (will be reported to KeyManager)
+     * @returns true if re-initialization succeeded with a new key
+     */
+    async reinitializeProvider(providerId: string, failedKey: string): Promise<boolean> {
+        if (!keyManager.hasMultipleKeys(providerId)) {
+            return false;
+        }
+
+        // Report the failure to track key health
+        keyManager.reportFailure(providerId, failedKey);
+
+        // Select a new key (KeyManager will avoid disabled keys)
+        const newKey = keyManager.selectKey(providerId);
+        if (!newKey || newKey === failedKey) {
+            logger.warn(`[ProviderRegistry] No alternative key available for "${providerId}"`);
+            return false;
+        }
+
+        const registration = this.registrations.get(providerId);
+        const originalConfig = this.providerConfigs.get(providerId);
+        if (!registration || !originalConfig) {
+            return false;
+        }
+
+        try {
+            // Build the new provider FIRST — never tear down before we have a replacement
+            const newProvider = new registration.Provider();
+            const initConfig: ProviderInitConfig = {
+                apiKey: newKey,
+                baseUrl: originalConfig.baseUrl,
+                options: originalConfig.options,
+            };
+            await newProvider.initialize(initConfig);
+
+            // New provider is ready — now swap it in and clean up the old one
+            const oldProvider = this.providers.get(providerId);
+            this.providers.set(providerId, newProvider);
+            this.activeApiKeys.set(providerId, newKey);
+
+            if (oldProvider) {
+                oldProvider.reset();
+            }
+
+            // Rebuild the AI SDK registry to reflect the new provider instance
+            this.buildAiSdkRegistry();
+
+            const keyPreview = newKey.slice(0, 8) + "...";
+            logger.info(`[ProviderRegistry] Re-initialized "${providerId}" with key ${keyPreview}`);
+            return true;
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error(`[ProviderRegistry] Failed to re-initialize "${providerId}"`, {
+                error: errorMessage,
+            });
+            // Old provider remains intact — no downtime
+            return false;
+        }
+    }
+
+    /**
+     * Get the currently active API key for a provider.
+     * Used by callers that need to report which key failed.
+     */
+    getActiveApiKey(providerId: string): string | undefined {
+        return this.activeApiKeys.get(providerId);
+    }
+
+    /**
+     * Initialize the mock provider for testing
+     */
+    private async initializeMockProvider(): Promise<void> {
+        try {
+            const { createMockProvider } = await import("../MockProvider");
+            const mockProvider = createMockProvider();
+
+            // Create a wrapper that satisfies ILLMProvider
+            const mockWrapper: ILLMProvider = {
+                metadata: {
+                    id: "mock",
+                    displayName: "Mock Provider",
+                    description: "Mock provider for testing",
+                    category: "standard",
+                    capabilities: {
+                        streaming: true,
+                        toolCalling: true,
+                        builtInTools: false,
+                        sessionResumption: false,
+                        requiresApiKey: false,
+                        mcpSupport: false,
+                    },
+                    defaultModel: "mock-model",
+                },
+                initialize: async () => {},
+                isInitialized: () => true,
+                isAvailable: () => true,
+                getProviderInstance: () => mockProvider,
+                createModel: (modelId) => ({
+                    model: mockProvider.languageModel(modelId),
+                    bypassRegistry: false,
+                }),
+                reset: () => {},
+            };
+
+            this.providers.set("mock", mockWrapper);
+        } catch (error) {
+            logger.error("[ProviderRegistry] Failed to load MockProvider:", error);
+            throw new Error(
+                "Mock mode is enabled but MockProvider could not be loaded. " +
+                "Make sure test dependencies are installed.",
+                { cause: error }
+            );
+        }
+    }
+
+    /**
+     * Build the AI SDK provider registry from initialized standard providers
+     */
+    private buildAiSdkRegistry(): void {
+        const standardProviders: Record<string, ProviderV3> = {};
+
+        for (const [providerId, provider] of this.providers) {
+            // Only include standard providers in the AI SDK registry
+            if (provider.metadata.category === "standard") {
+                const instance = provider.getProviderInstance();
+                if (instance) {
+                    standardProviders[providerId] = instance as ProviderV3;
+                }
+            }
+        }
+
+        if (Object.keys(standardProviders).length > 0) {
+            this.aiSdkRegistry = createProviderRegistry(standardProviders);
+        } else {
+            // Create empty registry to avoid null checks
+            this.aiSdkRegistry = createProviderRegistry({});
+        }
+    }
+
+    /**
+     * Get a provider by ID
+     */
+    getProvider(providerId: string): ILLMProvider | undefined {
+        return this.providers.get(providerId);
+    }
+
+    /**
+     * Check if a provider is available
+     */
+    hasProvider(providerId: string): boolean {
+        return this.providers.has(providerId) &&
+               (this.providers.get(providerId)?.isAvailable() ?? false);
+    }
+
+    /**
+     * Get the AI SDK provider registry
+     * Used for standard providers that use createProviderRegistry
+     */
+    getAiSdkRegistry(): ProviderRegistryProvider {
+        if (!this.aiSdkRegistry) {
+            throw new Error("ProviderRegistry not initialized. Call initialize() first.");
+        }
+        return this.aiSdkRegistry;
+    }
+
+    /**
+     * Create a model from a provider
+     */
+    createModel(
+        providerId: string,
+        modelId: string,
+        context?: ProviderRuntimeContext
+    ): ProviderModelResult {
+        // In mock mode, always use mock provider
+        const actualProviderId = process.env.USE_MOCK_LLM === "true" ? "mock" : providerId;
+
+        const provider = this.providers.get(actualProviderId);
+
+        if (!provider) {
+            const available = Array.from(this.providers.keys());
+            throw new Error(
+                `Provider "${actualProviderId}" not available. ` +
+                `Initialized providers: ${available.length > 0 ? available.join(", ") : "none"}`
+            );
+        }
+
+        return provider.createModel(modelId, context);
+    }
+
+    /**
+     * Get all available providers
+     */
+    getAvailableProviders(): ProviderMetadata[] {
+        return Array.from(this.providers.values())
+            .filter(p => p.isAvailable())
+            .map(p => p.metadata);
+    }
+
+    /**
+     * Get all registered providers (even if not initialized)
+     */
+    getRegisteredProviders(): ProviderMetadata[] {
+        return Array.from(this.registrations.values()).map(r => r.metadata);
+    }
+
+    /**
+     * Check if the registry is initialized
+     */
+    isInitialized(): boolean {
+        return this.initialized;
+    }
+
+    /**
+     * Reset the registry
+     */
+    reset(): void {
+        for (const provider of this.providers.values()) {
+            provider.reset();
+        }
+        this.providers.clear();
+        this.providerConfigs.clear();
+        this.activeApiKeys.clear();
+        this.aiSdkRegistry = null;
+        this.initialized = false;
+        keyManager.reset();
+    }
+}
+
+/**
+ * Export singleton instance
+ */
+export const providerRegistry = ProviderRegistry.getInstance();

package/src/llm/providers/registry/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Provider Registry Index
+ *
+ * Exports the provider registry and related utilities.
+ */
+
+export { ProviderRegistry, providerRegistry } from "./ProviderRegistry";

package/src/llm/providers/standard/AnthropicProvider.ts

@@ -0,0 +1,71 @@
+/**
+ * Anthropic Provider
+ *
+ * Direct access to Anthropic's Claude models.
+ * Supports both API keys (sk-ant-api*) and OAuth setup-tokens (sk-ant-oat*)
+ * from `claude setup-token` for Claude Code Max subscription auth.
+ *
+ * https://www.anthropic.com/
+ */
+
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { logger } from "@/utils/logger";
+import type { ProviderInitConfig, ProviderMetadata } from "../types";
+import { StandardProvider } from "../base/StandardProvider";
+import { PROVIDER_IDS } from "../provider-ids";
+
+/**
+ * Beta headers required when using OAuth setup-tokens.
+ * Without these, Anthropic rejects OAuth Bearer auth with 401.
+ */
+const OAUTH_BETAS = [
+    "claude-code-20250219",
+    "oauth-2025-04-20",
+];
+
+function isOAuthToken(key: string): boolean {
+    return key.startsWith("sk-ant-oat");
+}
+
+/**
+ * Anthropic provider implementation
+ */
+export class AnthropicProvider extends StandardProvider {
+    static readonly METADATA: ProviderMetadata = StandardProvider.createMetadata(
+        PROVIDER_IDS.ANTHROPIC,
+        "Anthropic",
+        "Direct access to Claude models",
+        "standard",
+        "claude-sonnet-4-20250514",
+        {
+            streaming: true,
+            toolCalling: true,
+            requiresApiKey: true,
+        },
+        "https://docs.anthropic.com/"
+    );
+
+    get metadata(): ProviderMetadata {
+        return AnthropicProvider.METADATA;
+    }
+
+    protected createProviderInstance(config: ProviderInitConfig): unknown {
+        if (!config.apiKey) {
+            throw new Error("Anthropic requires an API key or setup-token");
+        }
+
+        if (isOAuthToken(config.apiKey)) {
+            logger.info("[AnthropicProvider] Using OAuth setup-token auth (Claude Code Max subscription)");
+            return createAnthropic({
+                authToken: config.apiKey,
+                headers: {
+                    "anthropic-beta": OAUTH_BETAS.join(","),
+                },
+            });
+        }
+
+        return createAnthropic({
+            apiKey: config.apiKey,
+        });
+    }
+}

package/src/llm/providers/standard/OllamaProvider.ts

@@ -0,0 +1,59 @@
+/**
+ * Ollama Provider
+ *
+ * Run open-source LLMs locally with Ollama.
+ * https://ollama.ai/
+ */
+
+import { createOllama } from "ollama-ai-provider-v2";
+import type { ProviderInitConfig, ProviderMetadata } from "../types";
+import { StandardProvider } from "../base/StandardProvider";
+import { PROVIDER_IDS } from "../provider-ids";
+
+/**
+ * Ollama provider implementation
+ */
+export class OllamaProvider extends StandardProvider {
+    static readonly METADATA: ProviderMetadata = StandardProvider.createMetadata(
+        PROVIDER_IDS.OLLAMA,
+        "Ollama",
+        "Run open-source LLMs locally",
+        "standard",
+        "llama3.1:8b",
+        {
+            streaming: true,
+            toolCalling: true,
+            requiresApiKey: false, // Ollama uses a base URL instead of API key
+        },
+        "https://ollama.ai/"
+    );
+
+    get metadata(): ProviderMetadata {
+        return OllamaProvider.METADATA;
+    }
+
+    protected createProviderInstance(config: ProviderInitConfig): unknown {
+        // For Ollama, apiKey is actually the base URL
+        // The library expects the URL to include /api path
+        let baseURL: string | undefined;
+
+        if (!config.apiKey || config.apiKey === "local") {
+            // Use default (library provides http://127.0.0.1:11434/api)
+            baseURL = undefined;
+        } else {
+            // Custom URL - ensure it ends with /api
+            baseURL = config.apiKey.endsWith("/api")
+                ? config.apiKey
+                : `${config.apiKey.replace(/\/$/, "")}/api`;
+        }
+
+        return createOllama(baseURL ? { baseURL } : undefined);
+    }
+
+    /**
+     * Ollama is available if initialized (no API key required)
+     */
+    isAvailable(): boolean {
+        return this._initialized;
+    }
+}

package/src/llm/providers/standard/OpenAIProvider.ts

@@ -0,0 +1,44 @@
+/**
+ * OpenAI Provider
+ *
+ * Direct access to OpenAI's GPT models.
+ * https://openai.com/
+ */
+
+import { createOpenAI } from "@ai-sdk/openai";
+import type { ProviderInitConfig, ProviderMetadata } from "../types";
+import { StandardProvider } from "../base/StandardProvider";
+import { PROVIDER_IDS } from "../provider-ids";
+
+/**
+ * OpenAI provider implementation
+ */
+export class OpenAIProvider extends StandardProvider {
+    static readonly METADATA: ProviderMetadata = StandardProvider.createMetadata(
+        PROVIDER_IDS.OPENAI,
+        "OpenAI",
+        "Direct access to GPT models",
+        "standard",
+        "gpt-4",
+        {
+            streaming: true,
+            toolCalling: true,
+            requiresApiKey: true,
+        },
+        "https://platform.openai.com/docs/"
+    );
+
+    get metadata(): ProviderMetadata {
+        return OpenAIProvider.METADATA;
+    }
+
+    protected createProviderInstance(config: ProviderInitConfig): unknown {
+        if (!config.apiKey) {
+            throw new Error("OpenAI requires an API key");
+        }
+
+        return createOpenAI({
+            apiKey: config.apiKey,
+        });
+    }
+}

package/src/llm/providers/standard/OpenRouterProvider.ts

@@ -0,0 +1,103 @@
+/**
+ * OpenRouter Provider
+ *
+ * OpenRouter provides access to multiple AI models through a single API.
+ * https://openrouter.ai/
+ */
+
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+import type { LanguageModelUsage } from "ai";
+import type { LanguageModelUsageWithCostUsd } from "../../types";
+import type { ProviderInitConfig, ProviderMetadata } from "../types";
+import { StandardProvider } from "../base/StandardProvider";
+import { PROVIDER_IDS } from "../provider-ids";
+
+/**
+ * OpenRouter-specific metadata structure
+ */
+interface OpenRouterProviderMetadata {
+    id?: string;
+    usage?: {
+        cost?: number;
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+        promptTokensDetails?: { cachedTokens?: number };
+        completionTokensDetails?: { reasoningTokens?: number };
+    };
+}
+
+/**
+ * OpenRouter provider implementation
+ */
+export class OpenRouterProvider extends StandardProvider {
+    static readonly METADATA: ProviderMetadata = StandardProvider.createMetadata(
+        PROVIDER_IDS.OPENROUTER,
+        "OpenRouter",
+        "Access multiple AI models through a single API",
+        "standard",
+        "openai/gpt-4",
+        {
+            streaming: true,
+            toolCalling: true,
+            requiresApiKey: true,
+        },
+        "https://openrouter.ai/docs"
+    );
+
+    get metadata(): ProviderMetadata {
+        return OpenRouterProvider.METADATA;
+    }
+
+    protected createProviderInstance(config: ProviderInitConfig): unknown {
+        if (!config.apiKey) {
+            throw new Error("OpenRouter requires an API key");
+        }
+
+        return createOpenRouter({
+            apiKey: config.apiKey,
+            headers: {
+                "X-Title": "TENEX",
+                "HTTP-Referer": "https://tenex.chat/",
+            },
+        });
+    }
+
+    /**
+     * Extract usage metadata from OpenRouter provider response
+     */
+    static extractUsageMetadata(
+        model: string,
+        totalUsage: LanguageModelUsage | undefined,
+        providerMetadata: Record<string, unknown> | undefined
+    ): LanguageModelUsageWithCostUsd {
+        const metadata = providerMetadata?.openrouter as OpenRouterProviderMetadata | undefined;
+        const usage = metadata?.usage;
+
+        const inputTokens = usage?.promptTokens ?? totalUsage?.inputTokens;
+        const outputTokens = usage?.completionTokens ?? totalUsage?.outputTokens;
+        const totalTokens = usage?.totalTokens ??
+            (inputTokens !== undefined && outputTokens !== undefined
+                ? inputTokens + outputTokens
+                : undefined);
+
+        return {
+            model,
+            inputTokens,
+            outputTokens,
+            totalTokens,
+            costUsd: usage?.cost,
+            cachedInputTokens: usage?.promptTokensDetails?.cachedTokens,
+            reasoningTokens: usage?.completionTokensDetails?.reasoningTokens,
+        } as LanguageModelUsageWithCostUsd;
+    }
+
+    /**
+     * Extract OpenRouter generation ID for trace correlation
+     */
+    static extractGenerationId(
+        providerMetadata: Record<string, unknown> | undefined
+    ): string | undefined {
+        return (providerMetadata?.openrouter as OpenRouterProviderMetadata | undefined)?.id;
+    }
+}