@toolprint/hypertool-mcp/dist/persona/discovery.d.ts

HyperTool MCP proxy server for routing requests between clients and multiple underlying MCP servers

/**
 * Persona Discovery Engine
 *
 * This module implements the main discovery engine that orchestrates finding,
 * quick-validating, and cataloging personas with caching support. The discovery
 * engine coordinates file system scanning, quick validation, and result caching
 * to provide efficient persona discovery across all configured search paths.
 *
 * @fileoverview Main persona discovery orchestration engine
 */
import { EventEmitter } from "events";
import type { PersonaDiscoveryResult, PersonaDiscoveryConfig, PersonaCacheConfig, PersonaCacheStats } from "./types.js";
/**
 * Discovery cache statistics
 */
interface DiscoveryStats {
    /** Total discovery operations */
    totalDiscoveries: number;
    /** Cache hits */
    cacheHits: number;
    /** Cache misses */
    cacheMisses: number;
    /** Last discovery timestamp */
    lastDiscovery?: Date;
    /** Last scan time (alias for lastDiscovery) */
    lastScanTime?: Date;
    /** Total personas found in last discovery */
    totalPersonas: number;
    /** Alias for totalPersonas (for backward compatibility) */
    lastPersonaCount: number;
    /** Average discovery time in milliseconds */
    averageDiscoveryTime: number;
}
/**
 * Main persona discovery engine class
 *
 * Orchestrates the discovery of personas across all configured search paths,
 * providing quick validation, result caching, and change detection capabilities.
 * Extends EventEmitter to provide real-time updates on discovery progress.
 */
export declare class PersonaDiscovery extends EventEmitter {
    private readonly cache;
    private readonly stats;
    private readonly cacheConfig;
    private lastCleanup;
    constructor(cacheConfig?: PersonaCacheConfig);
    /**
     * Discover personas from all configured paths
     *
     * @param config Discovery configuration options
     * @returns Promise resolving to discovery result
     */
    discoverPersonas(config?: PersonaDiscoveryConfig): Promise<PersonaDiscoveryResult>;
    /**
     * Refresh discovery cache and rescan for personas
     *
     * @param config Discovery configuration options
     * @returns Promise resolving to fresh discovery result
     */
    refreshDiscovery(config?: PersonaDiscoveryConfig): Promise<PersonaDiscoveryResult>;
    /**
     * Check if personas are available without full discovery
     *
     * @param config Discovery configuration options
     * @returns Promise resolving to true if personas are likely available
     */
    hasPersonas(config?: PersonaDiscoveryConfig): Promise<boolean>;
    /**
     * Get discovery cache statistics
     *
     * @returns Current cache statistics
     */
    getCacheStats(): PersonaCacheStats;
    /**
     * Get discovery statistics
     *
     * @returns Current discovery statistics
     */
    getDiscoveryStats(): DiscoveryStats;
    /**
     * Clear discovery cache
     */
    clearCache(): void;
    /**
     * Get standard search paths
     *
     * @returns Array of standard search paths
     */
    getStandardSearchPaths(): string[];
    /**
     * Validate a search path
     *
     * @param path Path to validate
     * @returns Promise resolving to true if path is valid
     */
    validateSearchPath(path: string): Promise<boolean>;
    /**
     * Create discovery context for tracking state
     */
    private createDiscoveryContext;
    /**
     * Perform the actual discovery operation
     */
    private performDiscovery;
    /**
     * Perform quick validation on a persona without full parsing
     */
    private quickValidatePersona;
    /**
     * Perform quick validation without full YAML parsing
     */
    private performQuickValidation;
    /**
     * Validate tool IDs in YAML content using basic regex matching
     *
     * This provides basic format validation during discovery without full parsing
     * to catch obvious tool ID format errors early.
     */
    private validateToolIdsInYaml;
    /**
     * Check for duplicate persona names
     */
    private checkForDuplicates;
    /**
     * Generate cache key for discovery configuration
     */
    private generateCacheKey;
    /**
     * Get cached discovery result if valid
     */
    private getCachedResult;
    /**
     * Cache discovery result
     */
    private cacheResult;
    /**
     * Evict oldest cache entry to make room
     */
    private evictOldestEntry;
    /**
     * Update discovery statistics
     */
    private updateStats;
    /**
     * Estimate memory usage of cache
     */
    private estimateMemoryUsage;
    /**
     * Setup periodic cache cleanup
     */
    private setupCacheCleanup;
    /**
     * Clean up expired cache entries
     */
    private cleanupExpiredEntries;
    /**
     * Clean up resources and stop timers
     */
    dispose(): void;
}
/**
 * Default persona discovery instance
 *
 * Pre-configured discovery instance with default settings for common use cases.
 */
export declare const defaultPersonaDiscovery: PersonaDiscovery;
/**
 * Discover personas using default discovery instance
 *
 * @param config Discovery configuration options
 * @returns Promise resolving to discovery result
 */
export declare function discoverPersonas(config?: PersonaDiscoveryConfig): Promise<PersonaDiscoveryResult>;
/**
 * Refresh personas using default discovery instance
 *
 * @param config Discovery configuration options
 * @returns Promise resolving to fresh discovery result
 */
export declare function refreshPersonaDiscovery(config?: PersonaDiscoveryConfig): Promise<PersonaDiscoveryResult>;
/**
 * Check if personas are available using default discovery instance
 *
 * @param config Discovery configuration options
 * @returns Promise resolving to true if personas are likely available
 */
export declare function hasAvailablePersonas(config?: PersonaDiscoveryConfig): Promise<boolean>;
/**
 * Get discovery cache statistics from default instance
 *
 * @returns Current cache statistics
 */
export declare function getDiscoveryCacheStats(): PersonaCacheStats;
/**
 * Clear discovery cache from default instance
 */
export declare function clearDiscoveryCache(): void;
export {};
//# sourceMappingURL=discovery.d.ts.map