/**
 * Tool Provider Registry
 *
 * Centralized registry for managing tool providers.
 * Handles initialization, authentication, and lazy loading.
 *
 * Part of PIE Assessment Toolkit.
 */
import type { ToolProviderApi, ToolCategory } from "./ToolProviderApi.js";
/**
 * Configuration for registering a tool provider
 */
export interface ToolProviderConfig<TConfig = any> {
    /**
     * Provider instance to register
     */
    provider: ToolProviderApi<TConfig>;
    /**
     * Configuration for this provider
     * (may include auth credentials, endpoints, etc.)
     */
    config: TConfig;
    /**
     * Lazy initialization - don't initialize until first use
     *
     * @default true
     * @note Set to false for providers that must be ready immediately
     */
    lazy?: boolean;
    /**
     * Auth fetcher - function to retrieve auth credentials from backend
     *
     * Called during initialization if the provider requires auth.
     * The returned data is merged with the config before initialization.
     *
     * @example
     * ```typescript
     * authFetcher: async () => {
     *   const response = await fetch('/api/desmos/token');
     *   return response.json(); // { apiKey: '...' }
     * }
     * ```
     */
    authFetcher?: () => Promise<Partial<TConfig>>;
    /**
     * Optional telemetry callback used for provider lifecycle/backend instrumentation.
     */
    onTelemetry?: (eventName: string, payload?: Record<string, unknown>) => void | Promise<void>;
}
/**
 * Tool Provider Registry
 *
 * Manages the lifecycle of tool providers:
 * - Registration
 * - Lazy initialization
 * - Auth credential fetching
 * - Provider lookup by ID or category
 *
 * @example
 * ```typescript
 * const registry = new ToolProviderRegistry();
 *
 * // Register a provider with auth fetcher
 * registry.register('desmos-calculator', {
 *   provider: new DesmosToolProvider(),
 *   config: {},
 *   lazy: true,
 *   authFetcher: async () => {
 *     const response = await fetch('/api/desmos/token');
 *     return response.json();
 *   },
 * });
 *
 * // Get provider (auto-initializes if lazy)
 * const desmosProvider = await registry.getProvider('desmos-calculator');
 * ```
 */
export declare class ToolProviderRegistry {
    private providers;
    private configs;
    private initialized;
    private initializationPromises;
    private emitTelemetry;
    /**
     * Register a tool provider
     *
     * Adds a provider to the registry. If lazy is false, initializes immediately.
     *
     * @param providerId Unique provider identifier
     * @param config Provider configuration
     * @throws Error if provider with same ID already registered
     */
    register(providerId: string, config: ToolProviderConfig): void;
    /**
     * Initialize a provider
     *
     * Fetches auth if needed and initializes the provider.
     * Safe to call multiple times - subsequent calls wait for first initialization.
     *
     * @param providerId Provider to initialize
     * @returns Promise that resolves when initialization complete
     * @throws Error if provider not registered or initialization fails
     */
    initialize(providerId: string): Promise<void>;
    /**
     * Internal initialization logic
     */
    private _doInitialize;
    /**
     * Get a provider instance
     *
     * Retrieves a registered provider. If autoInitialize is true and provider
     * is not initialized, initializes it first.
     *
     * @param providerId Provider identifier
     * @param autoInitialize Auto-initialize if not ready (default: true)
     * @returns Provider instance
     * @throws Error if provider not registered
     */
    getProvider<T extends ToolProviderApi = ToolProviderApi>(providerId: string, autoInitialize?: boolean): Promise<T>;
    /**
     * Get all providers in a category
     *
     * @param category Tool category to filter by
     * @returns Array of provider IDs in the category
     */
    getProvidersByCategory(category: ToolCategory): string[];
    /**
     * Get all registered provider IDs
     *
     * @returns Array of all provider IDs
     */
    getProviderIds(): string[];
    /**
     * Check if provider is registered
     *
     * @param providerId Provider identifier
     * @returns true if provider is registered
     */
    has(providerId: string): boolean;
    /**
     * Check if provider is initialized
     *
     * @param providerId Provider identifier
     * @returns true if provider is initialized
     */
    isInitialized(providerId: string): boolean;
    /**
     * Check if provider is currently initializing
     *
     * @param providerId Provider identifier
     * @returns true if initialization in progress
     */
    isInitializing(providerId: string): boolean;
    /**
     * Unregister and destroy a provider
     *
     * Removes the provider from the registry and calls its destroy method.
     *
     * @param providerId Provider to unregister
     */
    unregister(providerId: string): Promise<void>;
    /**
     * Clean up all providers
     *
     * Unregisters and destroys all providers in the registry.
     */
    destroy(): Promise<void>;
}
