@robota-sdk/agent-core 3.0.0-beta.2 → 3.0.0-beta.20

package/dist/core/robota.d.ts

@@ -1,108 +1,29 @@
+/**
+ * Core Robota agent class.
+ *
+ * Heavy logic is delegated to extracted helpers:
+ * - {@link RobotaModuleManager} — module lifecycle
+ * - {@link RobotaPluginManager} — plugin lifecycle
+ * - {@link RobotaConfigManager} — config/tool/model management
+ * - {@link performAsyncInitialization} — async boot sequence
+ * - {@link robotaRun}, {@link robotaRunStream} — execution turns
+ * - {@link buildAgentStats}, {@link destroyAgent} — stats and teardown
+ * @public
+ */
 import { AbstractAgent } from '../abstracts/abstract-agent';
 import { TUniversalMessage, IAgentConfig, IRunOptions, IAgent } from '../interfaces/agent';
 import type { IPluginContract, IPluginHooks, IPluginOptions, IPluginStats } from '../abstracts/abstract-plugin';
 import type { IModule } from '../abstracts/abstract-module';
-import { AbstractTool, type IToolWithEventService } from '../abstracts/abstract-tool';
+import type { AbstractTool, IToolWithEventService } from '../abstracts/abstract-tool';
 import type { IModuleResultData } from '../abstracts/abstract-module';
+export type { TAgentStatsMetadata } from './robota-config-manager';
 /**
- * Reusable type definitions for Robota agent
- */
-/**
- * Agent statistics metadata type
- * Used for storing statistics and performance data in getStats method
- */
-export type TAgentStatsMetadata = Record<string, string | number | boolean | Date | string[]>;
-/**
- * Configuration options for creating a Robota instance.
- * Extends AgentConfig with additional options specific to the Robota agent system.
- *
+ * Core AI agent integrating multiple AI providers, tools, and plugins
+ * into a unified conversational interface.
  * @public
- * @interface
- * @example
- * ```typescript
- * const config: AgentConfig = {
- *   name: 'MyAgent',
- *   aiProviders: [new OpenAIProvider()],
- *   defaultModel: {
- *     provider: 'openai',
- *     model: 'gpt-4'
- *   },
- *   tools: [weatherTool, calculatorTool],
- *   plugins: [new LoggingPlugin(), new UsagePlugin()],
- *   logging: { level: 'info', enabled: true }
- * };
- * ```
- */
-/**
- * Core AI agent implementation for the Robota SDK.
- *
- * Robota is a comprehensive AI agent that integrates multiple AI providers, tools, and plugins
- * into a unified conversational interface. Each instance is completely independent with its own
- * managers and services - NO GLOBAL SINGLETONS are used.
- *
- * Key Features:
- * - Multiple AI provider support (OpenAI, Anthropic, Google)
- * - Function/tool calling with Zod schema validation
- * - Plugin system for extensible functionality
- * - Streaming response support
- * - Conversation history management
- * - Instance-specific resource management
- *
- * @public
- * @class
- * @implements AgentInterface
- *
- * @example Basic Usage
- * ```typescript
- * import { Robota } from '@robota-sdk/agents';
- * import { OpenAIProvider } from '@robota-sdk/openai';
- *
- * const robota = new Robota({
- *   name: 'MyAgent',
- *   aiProviders: [new OpenAIProvider({ apiKey: 'sk-...' })],
- *   defaultModel: {
- *     provider: 'openai',
- *     model: 'gpt-4'
- *   }
- * });
- *
- * const response = await robota.run('Hello, how are you?');
- * console.log(response);
- * ```
- *
- * @example With Tools and Plugins
- * ```typescript
- * import { Robota, LoggingPlugin, UsagePlugin } from '@robota-sdk/agents';
- * import { weatherTool, calculatorTool } from './my-tools';
- *
- * const robota = new Robota({
- *   name: 'AdvancedAgent',
- *   aiProviders: [openaiProvider],
- *   defaultModel: {
- *     provider: 'openai',
- *     model: 'gpt-4'
- *   },
- *   tools: [weatherTool, calculatorTool],
- *   plugins: [
- *     new LoggingPlugin({ level: 'info' }),
- *     new UsagePlugin({ trackTokens: true })
- *   ]
- * });
- *
- * const response = await robota.run('What\'s the weather in Tokyo?');
- * ```
- *
- * @example Streaming Response
- * ```typescript
- * for await (const chunk of robota.runStream('Tell me a story')) {
- *   process.stdout.write(chunk);
- * }
- * ```
  */
 export declare class Robota extends AbstractAgent<IAgentConfig, IRunOptions, TUniversalMessage> implements IAgent<IAgentConfig, IRunOptions, TUniversalMessage> {
-    /** The name of this agent instance */
     readonly name: string;
-    /** The version of the Robota agent implementation */
     readonly version: string;
     private aiProviders;
     private tools;
@@ -121,52 +42,25 @@ export declare class Robota extends AbstractAgent<IAgentConfig, IRunOptions, TUn
     private startTime;
     private configVersion;
     private configUpdatedAt;
-    /**
-     * Creates a new Robota agent instance with the new aiProviders array design.
-     *
-     * The constructor performs synchronous initialization and validation.
-     * Async initialization (AI provider setup, tool registration) is deferred
-     * until the first run() call for optimal performance.
-     *
-     * @param config - Configuration options for the agent
-     * @throws {ConfigurationError} When required configuration is missing or invalid
-     * @throws {ValidationError} When configuration values are invalid
-     *
-     * @example
-     * ```typescript
-     * const robota = new Robota({
-     *   name: 'CustomerSupport',
-     *   aiProviders: [
-     *     new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
-     *     new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY })
-     *   ],
-     *   defaultModel: {
-     *     provider: 'openai',
-     *     model: 'gpt-4',
-     *     temperature: 0.7
-     *   },
-     *   tools: [emailTool, ticketTool],
-     *   plugins: [new LoggingPlugin(), new ErrorHandlingPlugin()]
-     * });
-     * ```
-     */
+    private moduleManager;
+    private pluginManager;
+    private configManager;
     constructor(config: IAgentConfig);
-    /**
-     * Update tools for this agent instance.
-     * Rebuilds the Tools registry atomically and emits CONFIG_UPDATED event.
-     */
+    private initDelegates;
+    private emitCreatedEvent;
+    run(input: string, options?: IRunOptions): Promise<string>;
+    runStream(input: string, options?: IRunOptions): AsyncGenerator<string, void, undefined>;
+    private executionDeps;
+    getHistory(): TUniversalMessage[];
+    clearHistory(): void;
+    /** Inject a message into conversation history without triggering execution. */
+    injectMessage(role: 'user' | 'assistant' | 'system', content: string): void;
     updateTools(next: Array<IToolWithEventService>): Promise<{
         version: number;
     }>;
-    /**
-     * Update configuration partially. Currently supports tools.
-     */
     updateConfiguration(patch: Partial<IAgentConfig>): Promise<{
         version: number;
     }>;
-    /**
-     * Read-only configuration overview for UI.
-     */
     getConfiguration(): Promise<{
         version: number;
         tools: Array<{
@@ -174,299 +68,41 @@ export declare class Robota extends AbstractAgent<IAgentConfig, IRunOptions, TUn
             parameters?: string[];
         }>;
         updatedAt: number;
-        metadata?: TAgentStatsMetadata;
     }>;
-    private emitAgentEvent;
-    private buildOwnerPath;
-    /**
-     * Create instance-specific AIProviders manager
-     */
-    private createAIProvidersInstance;
-    /**
-     * Create instance-specific Tools manager
-     */
-    private createToolsInstance;
-    /**
-     * Create instance-specific AgentFactory manager
-     */
-    private createAgentFactoryInstance;
-    /**
-     * Create instance-specific ConversationHistory manager
-     */
-    private createConversationHistoryInstance;
-    /**
-     * Create instance-specific EventEmitter plugin
-     */
-    private createEventEmitterInstance;
-    /**
-     * Create instance-specific ModuleRegistry
-     */
-    private createModuleRegistryInstance;
-    /**
-     * Ensure full initialization has occurred
-     */
-    private ensureFullyInitialized;
-    /**
-     * Perform actual async initialization
-     */
-    private performAsyncInitialization;
-    /**
-     * Initialize the agent if not already done
-     *
-     * Note: This is a protected lifecycle hook required by AbstractAgent.
-     * Do not mark it as an internal tag, because DTS generation uses `stripInternal`
-     * and would remove this method from the public type surface, breaking the
-     * abstract contract in `.d.ts`.
-     */
-    protected initialize(): Promise<void>;
-    /**
-     * Execute a conversation turn with the AI agent.
-     *
-     * This is the primary method for interacting with the agent. It processes user input,
-     * manages conversation history, executes any required tools, and returns the AI response.
-     * The method automatically initializes the agent on first use.
-     *
-     * @param input - The user's message or prompt to send to the AI
-     * @param options - Optional configuration for this specific execution
-     * @returns Promise that resolves to the AI's response as a string
-     *
-     * @throws {ConfigurationError} When the agent configuration is invalid
-     * @throws {ProviderError} When the AI provider encounters an error
-     * @throws {ToolExecutionError} When a tool execution fails
-     *
-     * @example Basic conversation
-     * ```typescript
-     * const response = await robota.run('Hello, how are you?');
-     * console.log(response); // "Hello! I'm doing well, thank you for asking..."
-     * ```
-     *
-     * @example With execution options
-     * ```typescript
-     * const response = await robota.run('Analyze this data', {
-     *   sessionId: 'user-123',
-     *   userId: 'john.doe',
-     *   metadata: { source: 'web-app', priority: 'high' }
-     * });
-     * ```
-     *
-     * @example Error handling
-     * ```typescript
-     * try {
-     *   const response = await robota.run('Complex request');
-     * } catch (error) {
-     *   if (error instanceof ToolExecutionError) {
-     *     console.error('Tool failed:', error.toolName, error.message);
-     *   }
-     * }
-     * ```
-     */
-    run(input: string, options?: IRunOptions): Promise<string>;
-    /**
-     * Execute a conversation turn with streaming response.
-     *
-     * Similar to run() but returns an async generator that yields response chunks
-     * as they arrive from the AI provider. This enables real-time streaming of
-     * the AI's response for better user experience.
-     *
-     * @param input - The user's message or prompt to send to the AI
-     * @param options - Optional configuration for this specific execution
-     * @returns AsyncGenerator that yields string chunks of the AI response
-     *
-     * @throws {ConfigurationError} When the agent configuration is invalid
-     * @throws {ProviderError} When the AI provider encounters an error
-     * @throws {ToolExecutionError} When a tool execution fails
-     *
-     * @example Basic streaming
-     * ```typescript
-     * for await (const chunk of robota.runStream('Tell me a story')) {
-     *   process.stdout.write(chunk);
-     * }
-     * console.log('\n'); // New line after story
-     * ```
-     *
-     * @example Collecting full response
-     * ```typescript
-     * let fullResponse = '';
-     * for await (const chunk of robota.runStream('Explain quantum computing')) {
-     *   fullResponse += chunk;
-     *   updateUI(chunk); // Update UI in real-time
-     * }
-     * console.log('Complete response:', fullResponse);
-     * ```
-     *
-     * @example Error handling in streams
-     * ```typescript
-     * try {
-     *   for await (const chunk of robota.runStream('Complex request')) {
-     *     handleChunk(chunk);
-     *   }
-     * } catch (error) {
-     *   console.error('Streaming failed:', error.message);
-     * }
-     * ```
-     */
-    runStream(input: string, options?: IRunOptions): AsyncGenerator<string, void, undefined>;
-    /**
-     * Get the conversation history for this agent instance.
-     *
-     * Returns an array of messages representing the complete conversation history
-     * for this agent's conversation session. The history includes user messages,
-     * assistant responses, and tool call results.
-     *
-     * @returns Array of TUniversalMessage objects representing the conversation history
-     *
-     * @example
-     * ```typescript
-     * await robota.run('What is 2 + 2?');
-     * await robota.run('What about 3 + 3?');
-     *
-     * const history = robota.getHistory();
-     * console.log(history.length); // 4 (2 user messages, 2 assistant responses)
-     * console.log(history[0].role); // 'user'
-     * console.log(history[0].content); // 'What is 2 + 2?'
-     * ```
-     */
-    getHistory(): TUniversalMessage[];
-    /**
-     * Clear the conversation history for this agent instance.
-     *
-     * Removes all messages from the conversation history, starting fresh.
-     * This does not affect the agent's configuration or other state.
-     *
-     * @example
-     * ```typescript
-     * await robota.run('First message');
-     * console.log(robota.getHistory().length); // 2 (user + assistant)
-     *
-     * robota.clearHistory();
-     * console.log(robota.getHistory().length); // 0
-     * ```
-     */
-    clearHistory(): void;
-    /**
-     * Add a plugin to the agent at runtime.
-     *
-     * Plugins provide extensible functionality through lifecycle hooks.
-     * This method allows dynamic addition of plugins after agent creation.
-     *
-     * @param plugin - The plugin instance to add
-     *
-     * @example
-     * ```typescript
-     * import { UsagePlugin, PerformancePlugin } from '@robota-sdk/agents';
-     *
-     * const robota = new Robota(config);
-     *
-     * // Add plugins dynamically
-     * robota.addPlugin(new UsagePlugin({ trackTokens: true }));
-     * robota.addPlugin(new PerformancePlugin({ trackMemory: true }));
-     * ```
-     */
+    setModel(mc: {
+        provider: string;
+        model: string;
+        temperature?: number;
+        maxTokens?: number;
+        topP?: number;
+        systemMessage?: string;
+    }): void;
+    getModel(): {
+        provider: string;
+        model: string;
+        temperature?: number;
+        maxTokens?: number;
+        topP?: number;
+        systemMessage?: string;
+    };
+    registerTool(tool: AbstractTool): void;
+    unregisterTool(toolName: string): void;
+    getConfig(): IAgentConfig;
     addPlugin(plugin: IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks): void;
-    /**
-     * Remove a plugin from the agent by name.
-     *
-     * @param pluginName - The name of the plugin to remove
-     * @returns true if the plugin was found and removed, false otherwise
-     *
-     * @example
-     * ```typescript
-     * const removed = robota.removePlugin('usage-plugin');
-     * if (removed) {
-     *   console.log('Plugin removed successfully');
-     * } else {
-     *   console.log('Plugin not found');
-     * }
-     * ```
-     */
     removePlugin(pluginName: string): boolean;
-    /**
-     * Get a specific plugin by name with type safety.
-     *
-     * @template T - The expected plugin type extending AbstractPlugin
-     * @param pluginName - The name of the plugin to retrieve
-     * @returns The plugin instance if found, null otherwise
-     *
-     * @example
-     * ```typescript
-     * import { UsagePlugin } from '@robota-sdk/agents';
-     *
-     * const usagePlugin = robota.getPlugin<UsagePlugin>('usage-plugin');
-     * if (usagePlugin) {
-     *   const stats = usagePlugin.getUsageStats();
-     *   console.log('Token usage:', stats.totalTokens);
-     * }
-     * ```
-     */
-    getPlugin(pluginName: string): (IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks) | null;
-    /**
-     * Get all registered plugins.
-     *
-     * @returns Array of all currently registered plugin instances
-     *
-     * @example
-     * ```typescript
-     * const plugins = robota.getPlugins();
-     * console.log(`Agent has ${plugins.length} plugins registered`);
-     * plugins.forEach(plugin => {
-     *   console.log(`- ${plugin.name} (${plugin.version})`);
-     * });
-     * ```
-     */
+    getPlugin(pluginName: string): (IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks) | undefined;
     getPlugins(): Array<IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks>;
-    /**
-     * Get all registered plugin names
-     */
     getPluginNames(): string[];
-    /**
-     * Register a new module with the agent
-     * @param module - The module instance to register
-     * @param options - Registration options
-     */
     registerModule(module: IModule, options?: {
         autoInitialize?: boolean;
         validateDependencies?: boolean;
     }): Promise<void>;
-    /**
-     * Unregister a module from the agent
-     * @param moduleName - Name of the module to unregister
-     * @returns True if module was unregistered, false if not found
-     */
     unregisterModule(moduleName: string): Promise<boolean>;
-    /**
-     * Get a module by name with type safety
-     * @param moduleName - Name of the module to retrieve
-     * @returns The module instance or null if not found
-     */
-    getModule(moduleName: string): IModule | null;
-    /**
-     * Get modules by type
-     * @param moduleType - Type of modules to retrieve
-     * @returns Array of modules matching the type
-     */
+    getModule(moduleName: string): IModule | undefined;
     getModulesByType(moduleType: string): IModule[];
-    /**
-     * Get all registered modules
-     * @returns Array of all registered modules
-     */
     getModules(): IModule[];
-    /**
-     * Get all registered module names
-     * @returns Array of module names
-     */
     getModuleNames(): string[];
-    /**
-     * Check if a module is registered
-     * @param moduleName - Name of the module to check
-     * @returns True if module is registered
-     */
     hasModule(moduleName: string): boolean;
-    /**
-     * Execute a module by name
-     * @param moduleName - Name of the module to execute
-     * @param context - Execution context
-     * @returns Module execution result
-     */
     executeModule(moduleName: string, context: {
         executionId?: string;
         sessionId?: string;
@@ -478,186 +114,13 @@ export declare class Robota extends AbstractAgent<IAgentConfig, IRunOptions, TUn
         error?: Error;
         duration?: number;
     }>;
-    /**
-     * Get module execution statistics
-     * @param moduleName - Name of the module
-     * @returns Module statistics or null if not found
-     */
     getModuleStats(moduleName: string): {
         totalExecutions: number;
         successfulExecutions: number;
         failedExecutions: number;
         averageExecutionTime: number;
         lastExecutionTime?: Date;
-    } | null;
-    /**
-     * Register a new AI provider at runtime.
-     *
-     * Allows dynamic addition of AI providers after agent creation.
-     * The provider can then be selected using switchProvider().
-     *
-     * @param name - Unique name for the provider
-     * @param provider - The AI provider instance to register
-     *
-     * @example
-     * ```typescript
-     * import { AnthropicProvider } from '@robota-sdk/anthropic';
-     *
-     * const anthropicProvider = new AnthropicProvider({
-     *   apiKey: process.env.ANTHROPIC_API_KEY
-     * });
-     *
-     * robota.registerProvider('anthropic', anthropicProvider);
-     * robota.switchProvider('anthropic', 'claude-3-opus-20240229');
-     * ```
-     */
-    /**
-     * Set the current model configuration (complete replacement).
-     *
-     * Updates the current AI provider, model, and related settings. This completely
-     * replaces the current model configuration with the new values.
-     *
-     * @param modelConfig - New model configuration
-     *
-     * @throws {ConfigurationError} When the provider is not available
-     *
-     * @example
-     * ```typescript
-     * // Switch to a different provider and model
-     * robota.setModel({
-     *   provider: 'anthropic',
-     *   model: 'claude-3-opus',
-     *   temperature: 0.9,
-     *   maxTokens: 4000
-     * });
-     *
-     * // Simple model change
-     * robota.setModel({
-     *   provider: 'openai',
-     *   model: 'gpt-4-turbo'
-     * });
-     * ```
-     */
-    setModel(modelConfig: {
-        provider: string;
-        model: string;
-        temperature?: number;
-        maxTokens?: number;
-        topP?: number;
-        systemMessage?: string;
-    }): void;
-    /**
-     * Get the current model configuration.
-     *
-     * Returns the current AI provider, model, and related settings.
-     *
-     * @returns Current model configuration
-     *
-     * @example
-     * ```typescript
-     * const current = robota.getModel();
-     * console.log(`Current: ${current.provider}/${current.model}`);
-     * console.log(`Temperature: ${current.temperature}`);
-     * console.log(`Max tokens: ${current.maxTokens}`);
-     * ```
-     */
-    getModel(): {
-        provider: string;
-        model: string;
-        temperature?: number;
-        maxTokens?: number;
-        topP?: number;
-        systemMessage?: string;
-    };
-    /**
-     * Register a new tool for function calling.
-     *
-     * Adds a tool that the AI can call during conversations. The tool's schema
-     * defines its name, description, and parameters for the AI to understand.
-     *
-     * @param tool - The tool instance to register
-     *
-     * @example
-     * ```typescript
-     * import { AbstractTool } from '@robota-sdk/agents';
-     *
-     * class WeatherTool extends AbstractTool {
-     *   name = 'get_weather';
-     *   description = 'Get current weather for a location';
-     *
-     *   get schema() {
-     *     return {
-     *       name: this.name,
-     *       description: this.description,
-     *       parameters: {
-     *         type: 'object',
-     *         properties: {
-     *           location: { type: 'string', description: 'City name' }
-     *         },
-     *         required: ['location']
-     *       }
-     *     };
-     *   }
-     *
-     *   async execute(params: { location: string }) {
-     *     // Implementation here
-     *     return { temperature: 22, condition: 'sunny' };
-     *   }
-     * }
-     *
-     * robota.registerTool(new WeatherTool());
-     * ```
-     */
-    registerTool(tool: AbstractTool): void;
-    /**
-     * Unregister a tool by name.
-     *
-     * Removes a previously registered tool, making it unavailable for future AI calls.
-     *
-     * @param toolName - Name of the tool to unregister
-     *
-     * @example
-     * ```typescript
-     * robota.unregisterTool('weather-tool');
-     *
-     * const stats = robota.getStats();
-     * console.log('Remaining tools:', stats.tools);
-     * ```
-     */
-    unregisterTool(toolName: string): void;
-    /**
-     * Get the current agent configuration.
-     *
-     * Returns a copy of the current configuration object. Modifications to the
-     * returned object do not affect the agent - use updateConfig() to make changes.
-     *
-     * @returns Copy of the current IAgentConfig
-     *
-     * @example
-     * ```typescript
-     * const config = robota.getConfig();
-     * console.log('Current model:', config.currentModel);
-     * console.log('Available providers:', Object.keys(config.aiProviders || {}));
-     * ```
-     */
-    getConfig(): IAgentConfig;
-    /**
-     * Get comprehensive agent statistics including providers, tools, plugins, modules, and performance data.
-     *
-     * @returns Object containing all agent statistics and metadata
-     *
-     * @example
-     * ```typescript
-     * const stats = robota.getStats();
-     * console.log(`Agent: ${stats.name} v${stats.version}`);
-     * console.log(`Uptime: ${stats.uptime}ms`);
-     * console.log(`Providers: ${stats.providers.join(', ')}`);
-     * console.log(`Tools: ${stats.tools.join(', ')}`);
-     * console.log(`Plugins: ${stats.plugins.join(', ')}`);
-     * console.log(`Modules: ${stats.modules.join(', ')}`);
-     * console.log(`Messages: ${stats.historyLength}`);
-     * ```
-     */
+    } | undefined;
     getStats(): {
         name: string;
         version: string;
@@ -668,27 +131,14 @@ export declare class Robota extends AbstractAgent<IAgentConfig, IRunOptions, TUn
         plugins: string[];
         modules: string[];
         historyLength: number;
-        historyStats: TAgentStatsMetadata;
+        historyStats: import("./robota-config-manager").TAgentStatsMetadata;
         uptime: number;
     };
-    /**
-     * Validate the new agent configuration format.
-     * @internal
-     */
-    private validateNewConfig;
-    /**
-     * Clean up and dispose of the agent instance.
-     *
-     * This method properly cleans up all resources, managers, and services
-     * to prevent memory leaks and ensure graceful shutdown.
-     *
-     * @example
-     * ```typescript
-     * // Clean shutdown
-     * await robota.destroy();
-     * console.log('Agent destroyed');
-     * ```
-     */
     destroy(): Promise<void>;
+    protected initialize(): Promise<void>;
+    private ensureFullyInitialized;
+    private doAsyncInit;
+    private emitAgentEvent;
+    private buildOwnerPath;
 }
 //# sourceMappingURL=robota.d.ts.map