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

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

/**
 * Persona Loader Implementation
 *
 * This module implements persona loading functionality that parses YAML configs,
 * loads MCP configurations, and catalogs all assets in persona folders. The loader
 * orchestrates the parsing, validation, and asset discovery process to create
 * complete LoadedPersona objects ready for activation.
 *
 * @fileoverview Comprehensive persona loading with asset cataloging and validation
 */
import type { IToolDiscoveryEngine } from "../discovery/types.js";
import { type LoadedPersona, type ValidationResult, type PersonaReference, type PersonaDiscoveryConfig } from "./types.js";
import { PersonaValidator, type ValidationOptions } from "./validator.js";
import { PersonaDiscovery } from "./discovery.js";
/**
 * Persona loading options
 */
export interface PersonaLoadOptions {
    /** Whether to perform full validation during loading */
    validateOnLoad?: boolean;
    /** Whether to load MCP configuration files */
    loadMcpConfig?: boolean;
    /** Whether to catalog all assets in the persona folder */
    catalogAssets?: boolean;
    /** Tool discovery engine for validation */
    toolDiscoveryEngine?: IToolDiscoveryEngine;
    /** Custom validation options */
    validationOptions?: ValidationOptions;
    /** Whether to stop on validation errors */
    stopOnValidationError?: boolean;
    /** Whether to include warnings in validation results */
    includeWarnings?: boolean;
}
/**
 * Asset cataloging options
 */
export interface AssetCatalogOptions {
    /** Maximum directory depth to scan for assets */
    maxDepth?: number;
    /** File extensions to include in asset catalog */
    includedExtensions?: string[];
    /** File patterns to exclude from asset catalog */
    excludePatterns?: string[];
    /** Whether to follow symbolic links */
    followSymlinks?: boolean;
}
/**
 * Persona loading result
 */
export interface PersonaLoadResult {
    /** Whether loading was successful */
    success: boolean;
    /** Loaded persona if successful */
    persona?: LoadedPersona;
    /** Loading errors */
    errors: string[];
    /** Loading warnings */
    warnings: string[];
    /** Load time in milliseconds */
    loadTime: number;
}
/**
 * Batch loading result for multiple personas
 */
export interface BatchLoadResult {
    /** Successfully loaded personas */
    loaded: LoadedPersona[];
    /** Failed loading attempts with errors */
    failed: Array<{
        path: string;
        errors: string[];
        warnings: string[];
    }>;
    /** Total load time in milliseconds */
    totalLoadTime: number;
    /** Load statistics */
    stats: {
        attempted: number;
        succeeded: number;
        failed: number;
        averageLoadTime: number;
    };
}
/**
 * PersonaLoader class for comprehensive persona loading
 *
 * Orchestrates the loading process including YAML parsing, MCP configuration loading,
 * validation, and asset cataloging. Provides both individual and batch loading
 * capabilities with comprehensive error handling and performance monitoring.
 */
export declare class PersonaLoader {
    private validator;
    private discovery?;
    private toolDiscoveryEngine?;
    constructor(toolDiscoveryEngine?: IToolDiscoveryEngine, discovery?: PersonaDiscovery);
    /**
     * Load a persona from a file path
     *
     * @param filePath - Path to persona.yaml/yml file or persona directory
     * @param options - Loading options
     * @returns Promise resolving to load result
     */
    loadPersona(filePath: string, options?: PersonaLoadOptions): Promise<PersonaLoadResult>;
    /**
     * Load a persona from a PersonaReference
     *
     * @param reference - Persona reference from discovery
     * @param options - Loading options
     * @returns Promise resolving to load result
     */
    loadPersonaFromReference(reference: PersonaReference, options?: PersonaLoadOptions): Promise<PersonaLoadResult>;
    /**
     * Load multiple personas from paths
     *
     * @param paths - Array of file or directory paths
     * @param options - Loading options
     * @returns Promise resolving to batch load result
     */
    loadMultiplePersonas(paths: string[], options?: PersonaLoadOptions): Promise<BatchLoadResult>;
    /**
     * Load personas from discovery results
     *
     * @param discoveredPersonas - Array of persona references
     * @param options - Loading options
     * @returns Promise resolving to batch load result
     */
    loadPersonasFromDiscovery(discoveredPersonas: PersonaReference[], options?: PersonaLoadOptions): Promise<BatchLoadResult>;
    /**
     * Discover and load all available personas
     *
     * @param discoveryConfig - Discovery configuration
     * @param loadOptions - Loading options
     * @returns Promise resolving to batch load result with discovery info
     */
    discoverAndLoadPersonas(discoveryConfig?: PersonaDiscoveryConfig, loadOptions?: PersonaLoadOptions): Promise<BatchLoadResult & {
        discoveryErrors: string[];
        discoveryWarnings: string[];
    }>;
    /**
     * Validate loaded persona without reloading
     *
     * @param persona - Loaded persona to validate
     * @param options - Validation options
     * @returns Promise resolving to validation result
     */
    validateLoadedPersona(persona: LoadedPersona, options?: ValidationOptions): Promise<ValidationResult>;
    /**
     * Find persona configuration file in directory
     */
    private findPersonaConfigFile;
    /**
     * Load MCP configuration from file
     */
    private loadMcpConfigFile;
    /**
     * Catalog all assets in persona folder
     */
    private catalogPersonaAssets;
    /**
     * Set tool discovery engine for validation
     */
    setToolDiscoveryEngine(engine: IToolDiscoveryEngine): void;
    /**
     * Set persona discovery engine
     */
    setDiscoveryEngine(discovery: PersonaDiscovery): void;
    /**
     * Get loader statistics
     */
    getLoaderStats(): {
        hasToolDiscoveryEngine: boolean;
        hasDiscoveryEngine: boolean;
        validatorStats: ReturnType<PersonaValidator["getValidationStats"]>;
    };
}
/**
 * Create a default persona loader instance
 *
 * @param toolDiscoveryEngine - Optional tool discovery engine
 * @param discovery - Optional persona discovery engine
 * @returns PersonaLoader instance
 */
export declare function createPersonaLoader(toolDiscoveryEngine?: IToolDiscoveryEngine, discovery?: PersonaDiscovery): PersonaLoader;
/**
 * Quick load function for simple use cases
 *
 * @param personaPath - Path to persona file or directory
 * @param options - Loading options
 * @returns Promise resolving to load result
 */
export declare function loadPersona(personaPath: string, options?: PersonaLoadOptions): Promise<PersonaLoadResult>;
/**
 * Batch load function for multiple personas
 *
 * @param paths - Array of persona paths
 * @param options - Loading options
 * @returns Promise resolving to batch load result
 */
export declare function loadMultiplePersonas(paths: string[], options?: PersonaLoadOptions): Promise<BatchLoadResult>;
/**
 * Discover and load all available personas
 *
 * @param discoveryConfig - Discovery configuration
 * @param loadOptions - Loading options
 * @returns Promise resolving to batch load result with discovery info
 */
export declare function discoverAndLoadAllPersonas(discoveryConfig?: PersonaDiscoveryConfig, loadOptions?: PersonaLoadOptions): Promise<BatchLoadResult & {
    discoveryErrors: string[];
    discoveryWarnings: string[];
}>;
/**
 * Default persona loader instance
 */
export declare const defaultPersonaLoader: PersonaLoader;
//# sourceMappingURL=loader.d.ts.map