@robota-sdk/agent-core 3.0.0-beta.52 → 3.0.0-beta.53

package/dist/node/index.d.ts

@@ -714,57 +714,6 @@ interface IParameterValidationResult {
  * Generic tool executor function
  */
 type TToolExecutor<TParams = TToolParameters, TResult = TUniversalValue> = (parameters: TParams, context?: IToolExecutionContext) => Promise<TResult>;
-/**
- * OpenAPI specification configuration
- */
-interface IOpenAPIToolConfig {
-    /** OpenAPI 3.0 specification */
-    spec: {
-        openapi: string;
-        info: {
-            title: string;
-            version: string;
-            description?: string;
-        };
-        servers?: Array<{
-            url: string;
-            description?: string;
-        }>;
-        paths: Record<string, Record<string, string | number | boolean | Record<string, string | number | boolean>>>;
-        components?: Record<string, Record<string, string | number | boolean>>;
-    };
-    /** Operation ID from the OpenAPI spec */
-    operationId: string;
-    /** Base URL for API calls */
-    baseURL: string;
-    /** Authentication configuration */
-    auth?: {
-        type: 'bearer' | 'apiKey' | 'basic';
-        token?: string;
-        apiKey?: string;
-        header?: string;
-        username?: string;
-        password?: string;
-    };
-}
-/**
- * MCP (Model Context Protocol) configuration
- */
-interface IMCPToolConfig {
-    /** MCP server endpoint */
-    endpoint: string;
-    /** Protocol version */
-    version?: string;
-    /** Authentication configuration */
-    auth?: {
-        type: 'bearer' | 'apiKey';
-        token: string;
-    };
-    /** Tool-specific configuration */
-    toolConfig?: Record<string, string | number | boolean>;
-    /** Timeout in milliseconds */
-    timeout?: number;
-}
 /**
  * Base tool interface
  */
@@ -828,23 +777,6 @@ interface IToolRegistry {
      */
     clear(): void;
 }
-/**
- * Tool factory interface
- */
-interface IToolFactory {
-    /**
-     * Create function tool from schema and function
-     */
-    createFunctionTool(schema: IToolSchema, fn: TToolExecutor): IFunctionTool;
-    /**
-     * Create tool from OpenAPI specification
-     */
-    createOpenAPITool(config: IOpenAPIToolConfig): ITool;
-    /**
-     * Create MCP tool
-     */
-    createMCPTool(config: IMCPToolConfig): ITool;
-}
 
 declare const EXECUTION_EVENT_NAMES: {
     readonly START: "execution.start";
@@ -1941,6 +1873,75 @@ interface IAgentFactory {
     mergeConfig(base: IAgentConfig, override: Partial<IAgentConfig>): IAgentConfig;
 }
 
+/**
+ * OpenAPI specification configuration
+ */
+interface IOpenAPIToolConfig {
+    /** OpenAPI 3.0 specification */
+    spec: {
+        openapi: string;
+        info: {
+            title: string;
+            version: string;
+            description?: string;
+        };
+        servers?: Array<{
+            url: string;
+            description?: string;
+        }>;
+        paths: Record<string, Record<string, string | number | boolean | Record<string, string | number | boolean>>>;
+        components?: Record<string, Record<string, string | number | boolean>>;
+    };
+    /** Operation ID from the OpenAPI spec */
+    operationId: string;
+    /** Base URL for API calls */
+    baseURL: string;
+    /** Authentication configuration */
+    auth?: {
+        type: 'bearer' | 'apiKey' | 'basic';
+        token?: string;
+        apiKey?: string;
+        header?: string;
+        username?: string;
+        password?: string;
+    };
+}
+/**
+ * MCP (Model Context Protocol) configuration
+ */
+interface IMCPToolConfig {
+    /** MCP server endpoint */
+    endpoint: string;
+    /** Protocol version */
+    version?: string;
+    /** Authentication configuration */
+    auth?: {
+        type: 'bearer' | 'apiKey';
+        token: string;
+    };
+    /** Tool-specific configuration */
+    toolConfig?: Record<string, string | number | boolean>;
+    /** Timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Tool factory interface
+ */
+interface IToolFactory {
+    /**
+     * Create function tool from schema and function
+     */
+    createFunctionTool(schema: IToolSchema, fn: TToolExecutor): IFunctionTool;
+    /**
+     * Create tool from OpenAPI specification
+     */
+    createOpenAPITool(config: IOpenAPIToolConfig): ITool;
+    /**
+     * Create MCP tool
+     */
+    createMCPTool(config: IMCPToolConfig): ITool;
+}
+
 /**
  * Execution step definition for tools that support step-by-step progress reporting
  */
@@ -2507,72 +2508,13 @@ interface IExecutorAwareProviderConfig {
     [key: string]: string | number | boolean | IExecutor | undefined;
 }
 /**
- * Base AI provider implementation with proper type constraints
- * All AI providers should extend this class
- *
- * ========================================
- * CRITICAL IMPLEMENTATION GUIDELINES
- * ========================================
- *
- * ALL AI PROVIDER IMPLEMENTATIONS (OpenAI, Anthropic, Google, etc.) MUST:
+ * Base AI provider implementation with proper type constraints.
+ * All AI providers should extend this class.
  *
- * 1. EXTEND THIS CLASS:
- *    ```typescript
- *    export class OpenAIProvider extends AbstractAIProvider {
- *        override readonly name = 'openai';
- *        override readonly version = '1.0.0';
- *    ```
+ * Subclasses MUST: extend this class, use override keyword, call super() in constructor,
+ * not redefine types that exist in agent-core, handle null message content correctly.
  *
- * 2. USE IMPORTS FROM @robota-sdk/agent-core:
- *    ```typescript
- *    import { AbstractAIProvider } from '@robota-sdk/agent-core';
- *    import type {
- *        TUniversalMessage,
- *        ChatOptions,
- *        IToolCall,
- *        ToolSchema,
- *        AssistantMessage
- *    } from '@robota-sdk/agent-core';
- *    ```
- *
- * 3. USE OVERRIDE KEYWORD FOR ALL INHERITED METHODS:
- *    - override async chat(...)
- *    - override async *chatStream(...)
- *    - override supportsTools()
- *    - override validateConfig()
- *    - override async dispose()
- *
- * 4. DO NOT REDEFINE TYPES THAT EXIST IN @robota-sdk/agent-core:
- *    - TUniversalMessage
- *    - ChatOptions
- *    - IToolCall
- *    - ToolSchema
- *    - AssistantMessage
- *    - SystemMessage
- *    - UserMessage
- *    - ToolMessage
- *
- * 5. HANDLE MESSAGE CONTENT PROPERLY:
- *    - For tool calls: content should be null (not empty string)
- *    - For regular messages: content can be string or null
- *    - Always preserve null values from API responses
- *
- * 6. CALL SUPER() IN CONSTRUCTOR:
- *    ```typescript
- *    constructor(options: IProviderOptions) {
- *        super();
- *        // provider-specific initialization
- *    }
- *    ```
- *
- * This ensures ExecutionService can properly identify providers
- * and prevents type conflicts across the codebase.
- *
- * ========================================
- *
- * @template TConfig - Provider configuration type (defaults to IProviderConfig for type safety)
- * @template TUniversalMessage - Message type (defaults to TUniversalMessage for backward compatibility)
- * @template TResponse - Response type (defaults to TUniversalMessage for backward compatibility)
+ * @template TConfig - Provider configuration type
  */
 declare abstract class AbstractAIProvider<TConfig = IProviderConfig> implements IAIProvider {
     abstract readonly name: string;
@@ -2633,25 +2575,17 @@ declare abstract class AbstractAIProvider<TConfig = IProviderConfig> implements
      * @returns true if configuration is valid
      */
     validateConfig(): boolean;
-    /**
-     * Utility method for validating TUniversalMessage array
-     * @param messages - Messages to validate
-     */
+    /** Validate that messages is a non-empty array with valid roles. */
     protected validateMessages(messages: TUniversalMessage[]): void;
-    /**
-     * Utility method for validating tool schemas
-     * @param tools - Tool schemas to validate
-     */
+    /** Validate tool schemas. No-ops if tools is undefined. */
     protected validateTools(tools?: IToolSchema[]): void;
     /**
      * Execute chat via executor.
-     *
      * Subclasses should call this only when an executor is configured.
      */
     protected executeViaExecutorOrDirect(messages: TUniversalMessage[], options?: IChatOptions): Promise<TUniversalMessage>;
     /**
      * Execute streaming chat via executor.
-     *
      * Subclasses should call this only when an executor is configured.
      */
     protected executeStreamViaExecutorOrDirect(messages: TUniversalMessage[], options?: IChatOptions): AsyncIterable<TUniversalMessage>;
@@ -3361,17 +3295,43 @@ declare class EventEmitterPlugin extends AbstractPlugin<IEventEmitterPluginOptio
     off(eventType: TEventName, handlerIdOrListener: string | TEventEmitterListener): boolean;
     emit(eventType: TEventName, eventData?: Partial<IEventEmitterEventData>): Promise<void>;
     private processEvent;
-    private executeHandler;
     flushBuffer(): Promise<void>;
     getStats(): IEventEmitterPluginStats;
     clearAllListeners(): void;
     destroy(): Promise<void>;
-    private validateOptions;
 }
 
 /** Agent statistics metadata type */
 type TAgentStatsMetadata = Record<string, string | number | boolean | Date | string[]>;
 
+/** Shared model configuration shape used in setModel / getModel. */
+type TModelConfig = {
+    provider: string;
+    model: string;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    systemMessage?: string;
+};
+/** Return shape of getConfiguration(). */
+type TConfigurationSnapshot = {
+    version: number;
+    tools: Array<{
+        name: string;
+        parameters?: string[];
+    }>;
+    updatedAt: number;
+};
+/** Return shape of getModuleStats(). */
+type TModuleStats = {
+    totalExecutions: number;
+    successfulExecutions: number;
+    failedExecutions: number;
+    averageExecutionTime: number;
+    lastExecutionTime?: Date;
+} | undefined;
+/** Shorthand for the plugin contract type used throughout this class. */
+type TPlugin = IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks;
 /**
  * Core AI agent integrating multiple AI providers, tools, and plugins
  * into a unified conversational interface.
@@ -3401,68 +3361,33 @@ declare class Robota extends AbstractAgent<IAgentConfig, IRunOptions, TUniversal
     private pluginManager;
     private configManager;
     constructor(config: IAgentConfig);
-    private initDelegates;
-    private emitCreatedEvent;
     run(input: string, options?: IRunOptions): Promise<string>;
     runStream(input: string, options?: IRunOptions): AsyncGenerator<string, void, undefined>;
     private executionDeps;
     getHistory(): TUniversalMessage[];
-    /** Get full history timeline (IHistoryEntry[]) including events */
-    getFullHistory(): Array<{
-        id: string;
-        timestamp: Date;
-        category: string;
-        type: string;
-        data?: unknown;
-    }>;
-    /** Add an event entry to history */
-    addHistoryEntry(entry: {
-        id: string;
-        timestamp: Date;
-        category: string;
-        type: string;
-        data?: unknown;
-    }): void;
+    getFullHistory(): IHistoryEntry[];
+    addHistoryEntry(entry: IHistoryEntry): void;
     clearHistory(): void;
-    /** Inject a message into conversation history without triggering execution. */
-    injectMessage(role: 'user' | 'assistant' | 'system', content: string): void;
+    injectMessage(role: 'user' | 'assistant' | 'system' | 'tool', content: string, options?: {
+        toolCallId?: string;
+        name?: string;
+    }): void;
     updateTools(next: Array<IToolWithEventService>): Promise<{
         version: number;
     }>;
     updateConfiguration(patch: Partial<IAgentConfig>): Promise<{
         version: number;
     }>;
-    getConfiguration(): Promise<{
-        version: number;
-        tools: Array<{
-            name: string;
-            parameters?: string[];
-        }>;
-        updatedAt: number;
-    }>;
-    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;
-    };
+    getConfiguration(): Promise<TConfigurationSnapshot>;
+    setModel(mc: TModelConfig): void;
+    getModel(): TModelConfig;
     registerTool(tool: AbstractTool): void;
     unregisterTool(toolName: string): void;
     getConfig(): IAgentConfig;
-    addPlugin(plugin: IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks): void;
+    addPlugin(plugin: TPlugin): void;
     removePlugin(pluginName: string): boolean;
-    getPlugin(pluginName: string): (IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks) | undefined;
-    getPlugins(): Array<IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks>;
+    getPlugin(pluginName: string): TPlugin | undefined;
+    getPlugins(): TPlugin[];
     getPluginNames(): string[];
     registerModule(module: IModule, options?: {
         autoInitialize?: boolean;
@@ -3485,13 +3410,7 @@ declare class Robota extends AbstractAgent<IAgentConfig, IRunOptions, TUniversal
         error?: Error;
         duration?: number;
     }>;
-    getModuleStats(moduleName: string): {
-        totalExecutions: number;
-        successfulExecutions: number;
-        failedExecutions: number;
-        averageExecutionTime: number;
-        lastExecutionTime?: Date;
-    } | undefined;
+    getModuleStats(moduleName: string): TModuleStats;
     getStats(): {
         name: string;
         version: string;
@@ -3510,7 +3429,6 @@ declare class Robota extends AbstractAgent<IAgentConfig, IRunOptions, TUniversal
     private ensureFullyInitialized;
     private doAsyncInit;
     private emitAgentEvent;
-    private buildOwnerPath;
 }
 
 /**
@@ -3631,6 +3549,7 @@ interface IAgentLifecycleEvents {
     /** Called when agent is destroyed */
     onDestroy?: (agentId: string) => Promise<void> | void;
 }
+
 /**
  * Agent Factory for creating and managing agents
  * Instance-based for isolated agent factory management
@@ -3704,18 +3623,6 @@ declare class AgentFactory {
         isValid: boolean;
         errors: string[];
     };
-    /**
-     * Apply default configuration values
-     */
-    private applyDefaults;
-    /**
-     * Generate unique agent ID
-     */
-    private generateAgentId;
-    /**
-     * Update creation statistics
-     */
-    private updateCreationStats;
 }
 
 declare class EventHistoryModule implements IEventHistoryModule {
@@ -4194,11 +4101,13 @@ interface IExecutionProxyConfig {
         task?: boolean;
     };
 }
+/** Internal target shape for proxy interception */
+type TExecutionProxyTarget = Record<string, TUniversalValue>;
+/** Internal args shape for proxy interception */
+type TExecutionProxyArgs = TUniversalValue[];
 /**
  * Metadata extractor function type
  */
-type TExecutionProxyTarget = Record<string, TUniversalValue>;
-type TExecutionProxyArgs = TUniversalValue[];
 type TMetadataExtractor = (target: TExecutionProxyTarget, methodName: string, args: TExecutionProxyArgs) => Record<string, TUniversalValue>;
 /**
  * Method configuration for proxy
@@ -4210,6 +4119,7 @@ interface IMethodConfig {
     extractMetadata?: TMetadataExtractor;
     extractResult?: (result: TUniversalValue) => Record<string, TUniversalValue>;
 }
+
 /**
  * ExecutionProxy - Automatic event emission using Proxy pattern
  *
@@ -4406,7 +4316,7 @@ declare function formatTokenCount(tokens: number): string;
  * Hook system types — Claude Code compatible event/hook model.
  */
 /** Hook lifecycle events */
-type THookEvent = 'PreToolUse' | 'PostToolUse' | 'SessionStart' | 'Stop' | 'PreCompact' | 'PostCompact' | 'UserPromptSubmit' | 'Notification';
+type THookEvent = 'PreToolUse' | 'PostToolUse' | 'SessionStart' | 'Stop' | 'PreCompact' | 'PostCompact' | 'UserPromptSubmit';
 /** Command hook — executes a shell command */
 interface ICommandHookDefinition {
     type: 'command';