@robota-sdk/agent-core 3.0.0-beta.1

package/dist/node/index.d.cts

@@ -0,0 +1,4237 @@
+/**
+ * Message Contracts (Single Source of Truth)
+ *
+ * IMPORTANT:
+ * - This module is owned by the `interfaces` layer.
+ * - All message types used across the SDK must be defined here to avoid drift.
+ * - Runtime values (variables/classes/objects) and compile-time types can share the same name in TypeScript.
+ *   Prefixing type aliases (`T*`) and interfaces (`I*`) reduces value/type name collision risk and review overhead.
+ */
+/**
+ * Universal message role type - provider-independent neutral role.
+ */
+type TUniversalMessageRole = 'user' | 'assistant' | 'system' | 'tool';
+/**
+ * Message metadata used across conversation history and provider adapters.
+ */
+type TUniversalMessageMetadata = Record<string, string | number | boolean | Date | string[] | number[]>;
+/**
+ * Universal multimodal message part contracts.
+ */
+interface ITextMessagePart {
+    type: 'text';
+    text: string;
+}
+interface IInlineImageMessagePart {
+    type: 'image_inline';
+    mimeType: string;
+    data: string;
+}
+interface IUriImageMessagePart {
+    type: 'image_uri';
+    uri: string;
+    mimeType?: string;
+}
+type TUniversalMessagePart = ITextMessagePart | IInlineImageMessagePart | IUriImageMessagePart;
+/**
+ * Tool call (OpenAI tool calling format).
+ */
+interface IToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * Base message contract shared by all message variants.
+ */
+interface IBaseMessage {
+    /** Message creation timestamp */
+    timestamp: Date;
+    /** Additional metadata */
+    metadata?: TUniversalMessageMetadata;
+}
+interface IUserMessage extends IBaseMessage {
+    role: 'user';
+    content: string;
+    parts?: TUniversalMessagePart[];
+    name?: string;
+}
+interface IAssistantMessage extends IBaseMessage {
+    role: 'assistant';
+    /** Assistant response content (can be null when making tool calls) */
+    content: string | null;
+    parts?: TUniversalMessagePart[];
+    toolCalls?: IToolCall[];
+}
+interface ISystemMessage extends IBaseMessage {
+    role: 'system';
+    content: string;
+    parts?: TUniversalMessagePart[];
+    name?: string;
+}
+interface IToolMessage extends IBaseMessage {
+    role: 'tool';
+    content: string;
+    parts?: TUniversalMessagePart[];
+    toolCallId: string;
+    name?: string;
+}
+/**
+ * Universal message union used across the SDK as the canonical contract.
+ */
+type TUniversalMessage = IUserMessage | IAssistantMessage | ISystemMessage | IToolMessage;
+/**
+ * Type guards for the canonical TUniversalMessage union.
+ *
+ * NOTE:
+ * - These guards are owned by the `interfaces` layer and must not depend on managers/services.
+ * - Call sites should use these guards instead of importing from manager layers.
+ */
+declare function isUserMessage(message: TUniversalMessage): message is IUserMessage;
+declare function isAssistantMessage(message: TUniversalMessage): message is IAssistantMessage;
+declare function isSystemMessage(message: TUniversalMessage): message is ISystemMessage;
+declare function isToolMessage(message: TUniversalMessage): message is IToolMessage;
+
+/**
+ * Agent-specific type definitions
+ * Local types for agent functionality - not forced to use base types unless needed for cross-connections
+ */
+
+/**
+ * Primitive value types - foundation for all other types
+ * Extended to include null/undefined for agent contexts
+ */
+type TPrimitiveValue = string | number | boolean | null | undefined;
+/**
+ * Universal value type axis (recursive, JSON-like + Date).
+ *
+ * IMPORTANT:
+ * - This axis is the single source of truth for payload/context/result values.
+ * - It must support nested objects/arrays without `any`/`unknown`.
+ */
+type TUniversalValue = TPrimitiveValue | Date | TUniversalArrayValue | IUniversalObjectValue;
+type TUniversalArrayValue = TUniversalValue[];
+interface IUniversalObjectValue {
+    [key: string]: TUniversalValue;
+}
+/**
+ * Metadata type - consistent across agent components
+ */
+type TMetadataValue = TPrimitiveValue | TUniversalArrayValue | Date;
+type TMetadata = Record<string, TMetadataValue>;
+/**
+ * Context data type - for execution contexts
+ */
+type TContextData = Record<string, TUniversalValue>;
+/**
+ * Logger data type - for logging contexts
+ */
+type TLoggerData = Record<string, TUniversalValue | Date | Error>;
+/**
+ * Configuration types - for agent configuration
+ */
+type TComplexConfigValue = Record<string, TPrimitiveValue | TUniversalArrayValue | IUniversalObjectValue>;
+type TConfigValue = TPrimitiveValue | TUniversalArrayValue | IUniversalObjectValue | Array<TComplexConfigValue> | Array<Record<string, TPrimitiveValue | TUniversalArrayValue | IUniversalObjectValue>> | Array<TComplexConfigValue> | TComplexConfigValue;
+type TConfigData = Record<string, TConfigValue>;
+/**
+ * Tool parameter value type - specific for tool parameters
+ */
+type TToolParameters = Record<string, TUniversalValue>;
+/**
+ * Tool result data type - for tool execution results
+ */
+/**
+ * Plugin context type - for plugin execution contexts
+ */
+interface IPluginContext {
+    input?: string;
+    response?: string;
+    messages?: TUniversalMessage[];
+    responseMessage?: TUniversalMessage;
+    metadata?: TMetadata;
+    error?: Error;
+    executionContext?: TContextData;
+}
+
+/**
+ * Reusable type definitions for provider layer
+ */
+/**
+ * Provider configuration value type
+ * Used for storing provider-specific configuration values
+ */
+type TProviderConfigValue = string | number | boolean;
+/**
+ * JSON Schema parameter default value type
+ * Used for default values in parameter schemas
+ */
+type TParameterDefaultValue = string | number | boolean | null;
+/**
+ * JSON Schema primitive types
+ */
+type TJSONSchemaKind = 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
+/**
+ * JSON Schema enum values
+ */
+type TJSONSchemaEnum = string[] | number[] | boolean[] | (string | number | boolean)[];
+/**
+ * Tool schema definition
+ */
+interface IToolSchema {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, IParameterSchema>;
+        required?: string[];
+    };
+}
+/**
+ * Parameter schema for tools
+ */
+interface IParameterSchema {
+    type: TJSONSchemaKind;
+    description?: string;
+    enum?: TJSONSchemaEnum;
+    items?: IParameterSchema;
+    properties?: Record<string, IParameterSchema>;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    format?: string;
+    default?: TParameterDefaultValue;
+}
+/**
+ * Token usage statistics
+ */
+interface ITokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/**
+ * Raw provider response interface
+ */
+interface IRawProviderResponse {
+    content: string | null;
+    toolCalls?: IToolCall[];
+    usage?: ITokenUsage;
+    finishReason?: string;
+    model?: string;
+    metadata?: Record<string, TProviderConfigValue>;
+}
+/**
+ * Provider request payload
+ */
+interface IProviderRequest {
+    messages: TUniversalMessage[];
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    tools?: IToolSchema[];
+    systemMessage?: string;
+    metadata?: Record<string, string | number | boolean>;
+}
+/**
+ * Provider-specific configuration options
+ */
+interface IProviderSpecificOptions {
+    /** OpenAI specific options */
+    openai?: {
+        organization?: string;
+        user?: string;
+        stop?: string | string[];
+        presencePenalty?: number;
+        frequencyPenalty?: number;
+        logitBias?: Record<string, number>;
+        topP?: number;
+        n?: number;
+        stream?: boolean;
+        suffix?: string;
+        echo?: boolean;
+        bestOf?: number;
+        logprobs?: number;
+    };
+    /** Anthropic specific options */
+    anthropic?: {
+        stopSequences?: string[];
+        topP?: number;
+        topK?: number;
+        metadata?: {
+            userId?: string;
+        };
+    };
+    /** Google specific options */
+    google?: {
+        candidateCount?: number;
+        stopSequences?: string[];
+        safetySettings?: Array<{
+            category: string;
+            threshold: string;
+        }>;
+        responseModalities?: Array<'TEXT' | 'IMAGE'>;
+        topP?: number;
+        topK?: number;
+    };
+}
+/**
+ * Callback for receiving text deltas during streaming.
+ * Called for each text chunk as the model generates output.
+ */
+type TTextDeltaCallback = (delta: string) => void;
+/**
+ * Options for AI provider chat requests
+ */
+interface IChatOptions extends IProviderSpecificOptions {
+    /** Tool schemas to provide to the AI provider */
+    tools?: IToolSchema[];
+    /** Maximum number of tokens to generate */
+    maxTokens?: number;
+    /** Temperature for response randomness (0-1) */
+    temperature?: number;
+    /** Model to use for the request */
+    model?: string;
+    /** Callback for text deltas during streaming. When provided, the provider
+     *  should use streaming internally and call this for each text chunk,
+     *  while still returning the complete assembled message. */
+    onTextDelta?: TTextDeltaCallback;
+}
+/**
+ * Provider-agnostic AI Provider interface
+ * This interface uses only TUniversalMessage types and avoids provider-specific types
+ */
+interface IAIProvider {
+    /** Provider identifier */
+    readonly name: string;
+    /** Provider version */
+    readonly version: string;
+    /**
+     * Generate response from AI model using TUniversalMessage
+     * @param messages - Array of TUniversalMessage from conversation history
+     * @param options - Chat options including tools, model settings, etc.
+     * @returns Promise resolving to a TUniversalMessage response
+     */
+    chat(messages: TUniversalMessage[], options?: IChatOptions): Promise<TUniversalMessage>;
+    /**
+     * Generate streaming response from AI model using TUniversalMessage
+     * @param messages - Array of TUniversalMessage from conversation history
+     * @param options - Chat options including tools, model settings, etc.
+     * @returns AsyncIterable of TUniversalMessage chunks
+     */
+    chatStream?(messages: TUniversalMessage[], options?: IChatOptions): AsyncIterable<TUniversalMessage>;
+    /**
+     * Generate response from AI model (raw provider response)
+     * @param payload - Provider request payload
+     * @returns Promise resolving to raw provider response
+     */
+    generateResponse(payload: IProviderRequest): Promise<IRawProviderResponse>;
+    /**
+     * Generate streaming response from AI model (raw provider response)
+     * @param payload - Provider request payload
+     * @returns AsyncIterable of raw provider response chunks
+     */
+    generateStreamingResponse?(payload: IProviderRequest): AsyncIterable<IRawProviderResponse>;
+    /**
+     * Check if the provider supports tool calling
+     * @returns true if tool calling is supported
+     */
+    supportsTools(): boolean;
+    /**
+     * Validate provider configuration
+     * @returns true if configuration is valid
+     */
+    validateConfig(): boolean;
+    /**
+     * Clean up resources when provider is no longer needed
+     */
+    dispose?(): Promise<void>;
+    /**
+     * Close provider connections and cleanup resources
+     */
+    close?(): Promise<void>;
+}
+/**
+ * Provider options interface
+ */
+interface IProviderOptions {
+    apiKey?: string;
+    baseURL?: string;
+    timeout?: number;
+    retries?: number;
+    maxConcurrentRequests?: number;
+    defaultModel?: string;
+    organization?: string;
+    project?: string;
+    /** Additional provider-specific configuration */
+    extra?: Record<string, TProviderConfigValue>;
+}
+/**
+ * Base union for provider option values.
+ *
+ * Purpose:
+ * - Enable provider packages to compose their own option value unions without redefining the primitives.
+ * - Keep the shared axis in @robota-sdk/agent-core (SSOT).
+ *
+ * Note:
+ * - Provider packages may extend this with provider-specific runtime objects (e.g., OpenAI/Anthropic clients).
+ */
+type TProviderOptionValueBase = string | number | boolean | undefined | null | TProviderOptionValueBase[] | {
+    [key: string]: TProviderOptionValueBase;
+};
+
+/**
+ * @fileoverview Event service interface definitions.
+ *
+ * These interfaces are the single source of truth for event-related contracts
+ * within @robota-sdk/agent-core.
+ */
+/**
+ * Primitive value types for event payloads.
+ */
+type TEventPrimitiveValue = string | number | boolean | null | undefined;
+/**
+ * Recursive universal value type for event payloads (JSON-like + Date).
+ */
+type TEventUniversalValue = TEventPrimitiveValue | Date | TEventUniversalValue[] | IEventObjectValue;
+interface IEventObjectValue {
+    [key: string]: TEventUniversalValue;
+}
+/**
+ * Logger data type for event metadata.
+ */
+type TEventLoggerData = Record<string, TEventUniversalValue | Date | Error>;
+/**
+ * A single segment in an explicit ownerPath.
+ *
+ * Path-only rule:
+ * - Relationships must be derived from these explicit segments, not from parsing IDs.
+ */
+interface IOwnerPathSegment {
+    type: string;
+    id: string;
+}
+/**
+ * Event context that accompanies an emitted event.
+ * This is the single source of truth for deterministic linking in subscribers.
+ */
+interface IEventContext {
+    ownerType: string;
+    ownerId: string;
+    ownerPath: IOwnerPathSegment[];
+    /** Depth of the current execution in the hierarchy (0 = root) */
+    depth?: number;
+    /** Unique span identifier for distributed tracing correlation */
+    spanId?: string;
+    /** Optional structured metadata for debugging/observability */
+    metadata?: TEventLoggerData;
+}
+/**
+ * Allowed extension values for event payloads.
+ */
+type TEventExtensionValue = TEventUniversalValue | TEventLoggerData | Error | IEventContext | IOwnerPathSegment[];
+/**
+ * Base event payload shape.
+ * Emitters may add additional fields, but MUST keep linkage information explicit.
+ */
+interface IBaseEventData {
+    /** Timestamp when the event was emitted. This is required for deterministic ordering. */
+    timestamp: Date;
+    /** Optional structured metadata */
+    metadata?: TEventLoggerData;
+    /** Extensible fields for event-specific payloads */
+    [key: string]: TEventExtensionValue | undefined;
+}
+/**
+ * Execution-related event payload.
+ */
+interface IExecutionEventData extends IBaseEventData {
+}
+/**
+ * Tool-related event payload.
+ */
+interface IToolEventData extends IBaseEventData {
+    toolName?: string;
+    parameters?: Record<string, TEventUniversalValue>;
+}
+/**
+ * Agent-related event payload.
+ */
+interface IAgentEventData extends IBaseEventData {
+    agentId?: string;
+}
+type TEventListener = (eventType: string, data: IBaseEventData, context?: IEventContext) => void;
+/**
+ * Minimal EventService contract for emitting events.
+ */
+interface IEventService {
+    emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
+    subscribe(listener: TEventListener): void;
+    unsubscribe(listener: TEventListener): void;
+}
+/**
+ * Explicit owner binding information used for scoped event emission.
+ */
+interface IEventServiceOwnerBinding {
+    ownerType: string;
+    ownerId: string;
+    ownerPath: IOwnerPathSegment[];
+}
+
+type TToolContextExtensionValue = TUniversalValue | Date | Error | TLoggerData | TContextData | TToolParameters | TToolMetadata;
+/**
+ * Tool metadata structure - specific type definition
+ */
+type TToolMetadata = Record<string, string | number | boolean | string[] | number[] | boolean[] | TToolParameters>;
+/**
+ * Tool execution data - domain payload for tool results.
+ *
+ * IMPORTANT:
+ * - This must support structured tool outputs without resorting to `any`.
+ * - Prefer `ToolResultData` (derived from the canonical `UniversalValue` axis).
+ */
+/**
+ * Tool execution result - extended for ToolExecutionData compatibility
+ */
+interface IToolResult {
+    success: boolean;
+    data?: TUniversalValue;
+    error?: string;
+    metadata?: TToolMetadata;
+    [key: string]: TToolContextExtensionValue | undefined;
+}
+/**
+ * Enhanced tool execution result with additional metadata
+ */
+interface IToolExecutionResult {
+    /** Whether execution was successful */
+    success: boolean;
+    /** Tool name that was executed */
+    toolName?: string;
+    /** Execution result or data */
+    result?: TUniversalValue;
+    /** Error message if execution failed */
+    error?: string;
+    /** Execution duration in milliseconds */
+    duration?: number;
+    /** Unique execution ID */
+    executionId?: string;
+    /** Additional metadata */
+    metadata?: TToolMetadata;
+}
+/**
+ * Tool execution context - type-safe context for tool execution
+ * Enhanced with hierarchical execution tracking support
+ */
+interface IToolExecutionContext {
+    toolName: string;
+    parameters: TToolParameters;
+    executionId?: string;
+    userId?: string;
+    sessionId?: string;
+    metadata?: TToolMetadata;
+    /** Parent execution ID for hierarchical tool execution tracking */
+    parentExecutionId?: string;
+    /** Root execution ID (Team/Agent level) for complete execution tree tracking */
+    rootExecutionId?: string;
+    /** Execution depth level (0: Team, 1: Agent, 2: Tool, etc.) */
+    executionLevel?: number;
+    /** Execution path array showing the complete execution hierarchy */
+    executionPath?: string[];
+    /** Real-time execution data for accurate tracking (no simulation) */
+    realTimeData?: {
+        /** Actual execution start time */
+        startTime: Date;
+        /** Actual input parameters passed to the tool */
+        actualParameters: TToolParameters;
+        /** Tool-provided estimated duration (optional) */
+        estimatedDuration?: number;
+    };
+    /**
+     * Additional tool execution context extensions.
+     *
+     * IMPORTANT:
+     * - Avoid ad-hoc top-level fields to keep the contract stable.
+     * - Use this map for forward-compatible extra data with constrained value types.
+     */
+    extensions?: Record<string, TToolContextExtensionValue>;
+    /** Owner context propagated from EventService */
+    ownerType?: string;
+    ownerId?: string;
+    ownerPath?: IOwnerPathSegment[];
+    sourceId?: string;
+    /**
+     * Tool-call scoped EventService instance.
+     * Caller (ExecutionService/ToolExecutionService) is responsible for providing
+     * an ownerPath-bound EventService for this tool call.
+     */
+    eventService?: IEventService;
+    /**
+     * Unbound base EventService instance.
+     *
+     * Required when a tool needs to create another owner-bound EventService
+     * for a different owner (e.g., creating an agent from a tool call).
+     *
+     * NOTE: Do not wrap an already owner-bound EventService to bind a different owner.
+     * Owner-bound instances must not be layered across different owners.
+     */
+    baseEventService?: IEventService;
+}
+/**
+ * Parameter validation result
+ */
+interface IParameterValidationResult {
+    /** Whether parameters are valid */
+    isValid: boolean;
+    /** Validation error messages */
+    errors: string[];
+}
+/**
+ * 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
+ */
+interface ITool {
+    /** Tool schema */
+    schema: IToolSchema;
+    /**
+     * Execute the tool with given parameters
+     */
+    execute(parameters: TToolParameters, context?: IToolExecutionContext): Promise<IToolResult>;
+    /**
+     * Validate tool parameters
+     */
+    validate(parameters: TToolParameters): boolean;
+    /**
+     * Validate tool parameters with detailed result
+     */
+    validateParameters(parameters: TToolParameters): IParameterValidationResult;
+    /**
+     * Get tool description
+     */
+    getDescription(): string;
+}
+/**
+ * Function tool implementation
+ */
+interface IFunctionTool extends ITool {
+    /** Function to execute */
+    fn: TToolExecutor;
+}
+/**
+ * Tool registry interface
+ */
+interface IToolRegistry {
+    /**
+     * Register a tool
+     */
+    register(tool: ITool): void;
+    /**
+     * Unregister a tool
+     */
+    unregister(name: string): void;
+    /**
+     * Get tool by name
+     */
+    get(name: string): ITool | undefined;
+    /**
+     * Get all registered tools
+     */
+    getAll(): ITool[];
+    /**
+     * Get tool schemas
+     */
+    getSchemas(): IToolSchema[];
+    /**
+     * Check if tool exists
+     */
+    has(name: string): boolean;
+    /**
+     * Clear all tools
+     */
+    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";
+    readonly COMPLETE: "execution.complete";
+    readonly ERROR: "execution.error";
+};
+declare const TOOL_EVENT_NAMES: {
+    readonly CALL_START: "tool.call_start";
+    readonly CALL_COMPLETE: "tool.call_complete";
+    readonly CALL_ERROR: "tool.call_error";
+};
+declare const AGENT_EVENT_NAMES: {
+    readonly EXECUTION_START: "agent.execution_start";
+    readonly EXECUTION_COMPLETE: "agent.execution_complete";
+    readonly EXECUTION_ERROR: "agent.execution_error";
+    readonly CREATED: "agent.created";
+};
+type TExecutionEventName = (typeof EXECUTION_EVENT_NAMES)[keyof typeof EXECUTION_EVENT_NAMES];
+type TToolEventName = (typeof TOOL_EVENT_NAMES)[keyof typeof TOOL_EVENT_NAMES];
+type TAgentEventName = (typeof AGENT_EVENT_NAMES)[keyof typeof AGENT_EVENT_NAMES];
+/**
+ * Event types that can be emitted.
+ *
+ * IMPORTANT:
+ * - Do not use string literals for event names outside this module.
+ * - Import and use EVENT_EMITTER_EVENTS instead.
+ */
+declare const EVENT_EMITTER_EVENTS: {
+    readonly EXECUTION_START: "execution.start";
+    readonly EXECUTION_COMPLETE: "execution.complete";
+    readonly EXECUTION_ERROR: "execution.error";
+    readonly TOOL_BEFORE_EXECUTE: "tool.beforeExecute";
+    readonly TOOL_AFTER_EXECUTE: "tool.afterExecute";
+    readonly TOOL_SUCCESS: "tool.success";
+    readonly TOOL_ERROR: "tool.call_error";
+    readonly CONVERSATION_START: "conversation.start";
+    readonly CONVERSATION_COMPLETE: "conversation.complete";
+    readonly CONVERSATION_ERROR: "conversation.error";
+    readonly AGENT_EXECUTION_START: "agent.execution_start";
+    readonly AGENT_EXECUTION_COMPLETE: "agent.execution_complete";
+    readonly AGENT_EXECUTION_ERROR: "agent.execution_error";
+    readonly AGENT_CREATED: "agent.created";
+    readonly AGENT_DESTROYED: "agent.destroyed";
+    readonly PLUGIN_LOADED: "plugin.loaded";
+    readonly PLUGIN_UNLOADED: "plugin.unloaded";
+    readonly PLUGIN_ERROR: "plugin.error";
+    readonly ERROR_OCCURRED: "error.occurred";
+    readonly WARNING_OCCURRED: "warning.occurred";
+    readonly MODULE_INITIALIZE_START: "module.initialize.start";
+    readonly MODULE_INITIALIZE_COMPLETE: "module.initialize.complete";
+    readonly MODULE_INITIALIZE_ERROR: "module.initialize.error";
+    readonly MODULE_EXECUTION_START: "module.execution.start";
+    readonly MODULE_EXECUTION_COMPLETE: "module.execution.complete";
+    readonly MODULE_EXECUTION_ERROR: "module.execution.error";
+    readonly MODULE_DISPOSE_START: "module.dispose.start";
+    readonly MODULE_DISPOSE_COMPLETE: "module.dispose.complete";
+    readonly MODULE_DISPOSE_ERROR: "module.dispose.error";
+    readonly MODULE_REGISTERED: "module.registered";
+    readonly MODULE_UNREGISTERED: "module.unregistered";
+    readonly EXECUTION_HIERARCHY: "execution.hierarchy";
+    readonly EXECUTION_REALTIME: "execution.realtime";
+    readonly TOOL_REALTIME: "tool.realtime";
+    readonly CUSTOM: "custom";
+};
+type TEventName = TExecutionEventName | TToolEventName | TAgentEventName | 'tool.beforeExecute' | 'tool.afterExecute' | 'tool.success' | 'conversation.start' | 'conversation.complete' | 'conversation.error' | 'agent.destroyed' | 'plugin.loaded' | 'plugin.unloaded' | 'plugin.error' | 'error.occurred' | 'warning.occurred' | 'module.initialize.start' | 'module.initialize.complete' | 'module.initialize.error' | 'module.execution.start' | 'module.execution.complete' | 'module.execution.error' | 'module.dispose.start' | 'module.dispose.complete' | 'module.dispose.error' | 'module.registered' | 'module.unregistered' | 'execution.hierarchy' | 'execution.realtime' | 'tool.realtime' | 'custom';
+/**
+ * Valid event data value types
+ */
+type TEventDataValue = string | number | boolean | Date | null | undefined | TEventDataValue[] | {
+    [key: string]: TEventDataValue;
+};
+/**
+ * Event data structure
+ */
+interface IEventEmitterEventData {
+    type: TEventName;
+    timestamp: Date;
+    executionId?: string;
+    sessionId?: string;
+    userId?: string;
+    data?: Record<string, TEventDataValue>;
+    error?: Error;
+    metadata?: Record<string, TEventDataValue>;
+}
+/**
+ * Event listener function
+ */
+type TEventEmitterListener = (event: IEventEmitterEventData) => void | Promise<void>;
+/**
+ * Console-like interface for the EventEmitterPlugin.
+ *
+ * Use this interface for typing instead of the concrete EventEmitterPlugin class.
+ */
+interface IEventEmitterPlugin {
+    on(eventType: TEventName, listener: TEventEmitterListener, options?: {
+        once?: boolean;
+        filter?: (event: IEventEmitterEventData) => boolean;
+    }): string;
+    once(eventType: TEventName, listener: TEventEmitterListener, filter?: (event: IEventEmitterEventData) => boolean): string;
+    off(eventType: TEventName, handlerIdOrListener: string | TEventEmitterListener): boolean;
+    emit(eventType: TEventName, eventData?: Partial<IEventEmitterEventData>): Promise<void>;
+}
+
+/**
+ * Reusable type definitions for logger utility
+ */
+/**
+ * Log levels for the logger
+ */
+type TUtilLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Log entry structure
+ */
+interface IUtilLogEntry {
+    timestamp: string;
+    level: TUtilLogLevel;
+    message: string;
+    context?: TLoggerData;
+    packageName?: string;
+}
+/**
+ * Logger interface
+ */
+interface ILogger {
+    debug(...args: Array<TUniversalValue | TLoggerData | Error>): void;
+    info(...args: Array<TUniversalValue | TLoggerData | Error>): void;
+    warn(...args: Array<TUniversalValue | TLoggerData | Error>): void;
+    error(...args: Array<TUniversalValue | TLoggerData | Error>): void;
+    log(...args: Array<TUniversalValue | TLoggerData | Error>): void;
+    group?(label?: string): void;
+    groupEnd?(): void;
+}
+/**
+ * Silent logger that does nothing (Null Object Pattern)
+ *
+ * IMPORTANT:
+ * - This library must not write to stdio by default.
+ * - Inject a real logger explicitly if you want output.
+ */
+declare const SilentLogger: ILogger;
+/**
+ * Create a named logger instance for a package or module.
+ * Use this to create loggers with a specific name prefix for easy log filtering.
+ */
+declare function createLogger(packageName: string, logger?: ILogger): ILogger;
+/**
+ * Set global log level for all loggers
+ */
+declare function setGlobalLogLevel(level: TUtilLogLevel): void;
+/**
+ * Get global log level
+ */
+declare function getGlobalLogLevel(): TUtilLogLevel;
+/**
+ * Default logger for the agents package
+ */
+declare const logger: ILogger;
+
+/**
+ * Type definitions for AbstractPlugin.
+ *
+ * Extracted from abstract-plugin.ts to keep each file under 300 lines.
+ */
+
+/** Plugin categories for classification */
+declare enum PluginCategory {
+    MONITORING = "monitoring",
+    LOGGING = "logging",
+    STORAGE = "storage",
+    NOTIFICATION = "notification",
+    SECURITY = "security",
+    PERFORMANCE = "performance",
+    ERROR_HANDLING = "error_handling",
+    LIMITS = "limits",
+    EVENT_PROCESSING = "event_processing",
+    CUSTOM = "custom"
+}
+/** Plugin priority levels */
+declare enum PluginPriority {
+    CRITICAL = 1000,
+    HIGH = 800,
+    NORMAL = 500,
+    LOW = 200,
+    MINIMAL = 100
+}
+/** Plugin execution context for all plugins */
+interface IPluginExecutionContext {
+    executionId?: string;
+    sessionId?: string;
+    userId?: string;
+    messages?: TUniversalMessage[];
+    config?: Record<string, string | number | boolean>;
+    metadata?: Record<string, string | number | boolean | Date>;
+    [key: string]: string | number | boolean | Date | string[] | number[] | boolean[] | TUniversalMessage[] | Record<string, string | number | boolean> | Record<string, string | number | boolean | Date> | undefined;
+}
+/** Plugin execution result for all plugins */
+interface IPluginExecutionResult {
+    response?: string;
+    content?: string;
+    duration?: number;
+    tokensUsed?: number;
+    toolsExecuted?: number;
+    success?: boolean;
+    usage?: {
+        totalTokens?: number;
+        promptTokens?: number;
+        completionTokens?: number;
+    };
+    toolCalls?: Array<{
+        id?: string;
+        name?: string;
+        arguments?: Record<string, string | number | boolean>;
+        result?: string | number | boolean | null;
+    }>;
+    results?: Array<{
+        id?: string;
+        type?: string;
+        data?: string | number | boolean | null;
+        success?: boolean;
+    }>;
+    error?: Error;
+    metadata?: Record<string, string | number | boolean | Date>;
+}
+/** Error context for plugin error handling */
+interface IPluginErrorContext {
+    action: string;
+    tool?: string;
+    parameters?: TToolParameters;
+    result?: IToolExecutionResult;
+    error?: Error;
+    executionId?: string;
+    sessionId?: string;
+    userId?: string;
+    timestamp?: Date;
+    attempt?: number;
+    stack?: string;
+    metadata?: Record<string, string | number | boolean>;
+}
+/** Plugin configuration interface */
+interface IPluginConfig extends IPluginOptions {
+    options?: Record<string, string | number | boolean>;
+}
+/** Plugin options that all plugin options should extend */
+interface IPluginOptions {
+    enabled?: boolean;
+    category?: PluginCategory;
+    priority?: PluginPriority | number;
+    moduleEvents?: TEventName[];
+    subscribeToAllModuleEvents?: boolean;
+}
+/** Plugin data interface */
+interface IPluginData {
+    name: string;
+    version: string;
+    enabled: boolean;
+    category: PluginCategory;
+    priority: number;
+    subscribedEvents: TEventName[];
+    metadata?: Record<string, string | number | boolean>;
+}
+/** Type-safe plugin interface with specific type parameters */
+interface IPluginContract<TOptions extends IPluginOptions = IPluginOptions, TStats = IPluginStats> {
+    name: string;
+    version: string;
+    enabled: boolean;
+    category: PluginCategory;
+    priority: number;
+    initialize(options?: TOptions): Promise<void>;
+    cleanup?(): Promise<void>;
+    getData?(): IPluginData;
+    getStats?(): TStats;
+    subscribeToModuleEvents?(eventEmitter: IEventEmitterPlugin): Promise<void>;
+    unsubscribeFromModuleEvents?(eventEmitter: IEventEmitterPlugin): Promise<void>;
+    onModuleEvent?(eventName: TEventName, eventData: IEventEmitterEventData): Promise<void> | void;
+}
+/** Plugin statistics base interface with common metrics */
+interface IPluginStats {
+    enabled: boolean;
+    calls: number;
+    errors: number;
+    lastActivity?: Date;
+    moduleEventsReceived?: number;
+    [key: string]: string | number | boolean | Date | string[] | number[] | boolean[] | Record<string, string | number | boolean | Date> | undefined;
+}
+/** Plugin interface extending IPluginContract */
+interface IPlugin extends IPluginContract<IPluginConfig, IPluginStats> {
+}
+/** Plugin lifecycle hooks */
+interface IPluginHooks {
+    beforeRun?(input: string, options?: IRunOptions): Promise<void> | void;
+    afterRun?(input: string, response: string, options?: IRunOptions): Promise<void> | void;
+    beforeExecution?(context: IPluginExecutionContext): Promise<void> | void;
+    afterExecution?(context: IPluginExecutionContext, result: IPluginExecutionResult): Promise<void> | void;
+    beforeConversation?(context: IPluginExecutionContext): Promise<void> | void;
+    afterConversation?(context: IPluginExecutionContext, result: IPluginExecutionResult): Promise<void> | void;
+    beforeToolCall?(toolName: string, parameters: TToolParameters): Promise<void> | void;
+    beforeToolExecution?(context: IPluginExecutionContext, toolData: IToolExecutionContext): Promise<void> | void;
+    afterToolCall?(toolName: string, parameters: TToolParameters, result: IToolExecutionResult): Promise<void> | void;
+    afterToolExecution?(context: IPluginExecutionContext, toolResults: IPluginExecutionResult): Promise<void> | void;
+    beforeProviderCall?(messages: TUniversalMessage[]): Promise<void> | void;
+    afterProviderCall?(messages: TUniversalMessage[], response: TUniversalMessage): Promise<void> | void;
+    onStreamingChunk?(chunk: TUniversalMessage): Promise<void> | void;
+    onError?(error: Error, context?: IPluginErrorContext): Promise<void> | void;
+    onMessageAdded?(message: TUniversalMessage): Promise<void> | void;
+    onModuleEvent?(eventName: TEventName, eventData: IEventEmitterEventData): Promise<void> | void;
+}
+
+/**
+ * Abstract class for all plugins with type parameter support.
+ *
+ * Type definitions live in ./abstract-plugin-types.ts.
+ */
+
+/**
+ * Abstract class for all plugins with type parameter support.
+ * Provides plugin lifecycle management and common functionality.
+ * @template TOptions - Plugin options type that extends IPluginOptions
+ * @template TStats - Plugin statistics type
+ */
+declare abstract class AbstractPlugin<TOptions extends IPluginOptions = IPluginOptions, TStats extends IPluginStats = IPluginStats> implements IPluginContract<TOptions, TStats>, IPluginHooks {
+    abstract readonly name: string;
+    abstract readonly version: string;
+    enabled: boolean;
+    category: PluginCategory;
+    priority: number;
+    protected options: TOptions | undefined;
+    protected eventEmitter: IEventEmitterPlugin | undefined;
+    protected subscribedEvents: TEventName[];
+    protected eventHandlers: Map<TEventName, string[]>;
+    protected readonly pluginLogger: ILogger;
+    protected stats: {
+        calls: number;
+        errors: number;
+        moduleEventsReceived: number;
+        lastActivity: Date | undefined;
+    };
+    initialize(options?: TOptions): Promise<void>;
+    subscribeToModuleEvents(eventEmitter: IEventEmitterPlugin): Promise<void>;
+    unsubscribeFromModuleEvents(eventEmitter: IEventEmitterPlugin): Promise<void>;
+    dispose(): Promise<void>;
+    enable(): void;
+    disable(): void;
+    isEnabled(): boolean;
+    getConfig(): IPluginConfig;
+    updateConfig(_config: IPluginConfig): void;
+    getData(): IPluginData;
+    clearData?(): void;
+    getStatus(): {
+        name: string;
+        version: string;
+        enabled: boolean;
+        initialized: boolean;
+        category: PluginCategory;
+        priority: number;
+        subscribedEventsCount: number;
+        hasEventEmitter: boolean;
+    };
+    getStats(): TStats;
+    protected updateCallStats(): void;
+    protected updateErrorStats(): void;
+    beforeRun?(input: string, options?: IRunOptions): Promise<void>;
+    afterRun?(input: string, response: string, options?: IRunOptions): Promise<void>;
+    beforeExecution?(context: IPluginExecutionContext): Promise<void>;
+    afterExecution?(context: IPluginExecutionContext, result: IPluginExecutionResult): Promise<void>;
+    beforeConversation?(context: IPluginExecutionContext): Promise<void>;
+    afterConversation?(context: IPluginExecutionContext, result: IPluginExecutionResult): Promise<void>;
+    beforeToolCall?(toolName: string, parameters: TToolParameters): Promise<void>;
+    beforeToolExecution?(context: IPluginExecutionContext, toolData: IToolExecutionContext): Promise<void>;
+    afterToolCall?(toolName: string, parameters: TToolParameters, result: IToolExecutionResult): Promise<void>;
+    afterToolExecution?(context: IPluginExecutionContext, toolResults: IPluginExecutionResult): Promise<void>;
+    beforeProviderCall?(messages: TUniversalMessage[]): Promise<void>;
+    afterProviderCall?(messages: TUniversalMessage[], response: TUniversalMessage): Promise<void>;
+    onStreamingChunk?(chunk: TUniversalMessage): Promise<void>;
+    onError?(error: Error, context?: IPluginErrorContext): Promise<void>;
+    onMessageAdded?(message: TUniversalMessage): Promise<void>;
+    onModuleEvent?(eventName: TEventName, eventData: IEventEmitterEventData): Promise<void>;
+}
+
+/**
+ * Type definitions, interfaces, and enums for the module system.
+ *
+ * Extracted from abstract-module.ts to keep each file under 300 lines.
+ */
+
+/** Module execution context */
+interface IModuleExecutionContext {
+    executionId?: string;
+    sessionId?: string;
+    userId?: string;
+    agentName?: string;
+    metadata?: Record<string, string | number | boolean | Date>;
+    [key: string]: string | number | boolean | Date | Record<string, string | number | boolean | Date> | undefined;
+}
+/** Module execution result */
+interface IModuleExecutionResult {
+    success: boolean;
+    data?: IModuleResultData;
+    error?: Error;
+    duration?: number;
+    metadata?: Record<string, string | number | boolean | Date>;
+}
+/** Module result data */
+interface IModuleResultData {
+    [key: string]: string | number | boolean | Record<string, string | number | boolean> | undefined;
+}
+/** Base module options */
+interface IBaseModuleOptions {
+    enabled?: boolean;
+    config?: Record<string, string | number | boolean>;
+}
+/** Module capabilities */
+interface IModuleCapabilities {
+    capabilities: string[];
+    dependencies?: string[];
+    optionalDependencies?: string[];
+}
+/** Module type descriptor */
+interface IModuleDescriptor {
+    type: string;
+    category: ModuleCategory;
+    layer: ModuleLayer;
+    dependencies?: string[];
+    capabilities?: string[];
+}
+/** Module categories */
+declare enum ModuleCategory {
+    CORE = "core",
+    STORAGE = "storage",
+    PROCESSING = "processing",
+    INTEGRATION = "integration",
+    INTERFACE = "interface",
+    CAPABILITY = "capability"
+}
+/** Module layers */
+declare enum ModuleLayer {
+    INFRASTRUCTURE = "infrastructure",
+    CORE = "core",
+    APPLICATION = "application",
+    DOMAIN = "domain",
+    PRESENTATION = "presentation"
+}
+/** Module data for introspection */
+interface IModuleData {
+    name: string;
+    version: string;
+    type: string;
+    enabled: boolean;
+    initialized: boolean;
+    capabilities: IModuleCapabilities;
+    metadata?: Record<string, string | number | boolean>;
+}
+/** Module statistics */
+interface IModuleStats {
+    enabled: boolean;
+    initialized: boolean;
+    executionCount: number;
+    errorCount: number;
+    lastActivity?: Date;
+    averageExecutionTime?: number;
+    [key: string]: string | number | boolean | Date | undefined;
+}
+/** Type-safe module interface */
+interface IModule<TOptions extends IBaseModuleOptions = IBaseModuleOptions, TStats = IModuleStats> {
+    name: string;
+    version: string;
+    enabled: boolean;
+    initialize(options?: TOptions, eventEmitter?: IEventEmitterPlugin): Promise<void>;
+    dispose?(): Promise<void>;
+    execute?(context: IModuleExecutionContext): Promise<IModuleExecutionResult>;
+    getModuleType(): IModuleDescriptor;
+    getCapabilities(): IModuleCapabilities;
+    getData?(): IModuleData;
+    getStats?(): TStats;
+    isEnabled(): boolean;
+    isInitialized(): boolean;
+}
+
+/**
+ * @fileoverview Abstract Tool Base Class
+ *
+ * 🎯 ABSTRACT CLASS - DO NOT DEPEND ON CONCRETE IMPLEMENTATIONS
+ *
+ * This is a pure abstract base class that defines the interface and common behavior
+ * for all tools. It follows strict architectural principles:
+ *
+ * - Depends ONLY on interfaces (EventService interface, not concrete implementations)
+ * - Does NOT import concrete classes
+ * - Uses Dependency Injection for all dependencies
+ * - Handles undefined dependencies gracefully (Null Object Pattern)
+ *
+ * Concrete implementations should be handled
+ * by the caller who creates the tool instance, not by this abstract class.
+ *
+ * @example
+ * ```typescript
+ * // ✅ CORRECT: Caller prepares an owner-bound EventService and injects it
+ * // (Example: bind to the current tool call identity and ownerPath.)
+ * const toolEventService = bindWithOwnerPath(baseEventService, {
+ *   ownerType: 'tool',
+ *   ownerId: toolCallId,
+ *   ownerPath,
+ * });
+ * const tool = new MyTool({ eventService: toolEventService });
+ *
+ * // ❌ WRONG: AbstractTool creates concrete EventService
+ * // This violates Dependency Inversion Principle
+ * ```
+ */
+
+/**
+ * Options for AbstractTool construction
+ */
+interface IAbstractToolOptions {
+    /**
+     * Optional logger for tool operations
+     * Defaults to SilentLogger if not provided
+     */
+    logger?: ILogger;
+    /**
+     * Optional event service for unified event emission
+     * If not provided, tool will operate silently without emitting events
+     *
+     * The caller should provide an EventService configured with appropriate settings
+     * (e.g., ownerPrefix='tool' for tool events)
+     *
+     * @since 2.1.0
+     */
+    eventService?: IEventService;
+}
+/**
+ * Tool execution function type with proper parameter constraints
+ */
+type TToolExecutionFunction<TParams = TToolParameters, TResult = IToolResult> = (parameters: TParams) => Promise<TResult> | TResult;
+/**
+ * Abstract tool interface with type parameters for enhanced type safety
+ *
+ * @template TParams - Tool parameters type (defaults to AbstractToolParameters for backward compatibility)
+ * @template TResult - Tool result type (defaults to ToolResult for backward compatibility)
+ */
+interface IAbstractTool<TParams = TToolParameters, TResult = IToolResult> {
+    name: string;
+    description: string;
+    parameters: IToolSchema['parameters'];
+    execute: TToolExecutionFunction<TParams, TResult>;
+}
+/**
+ * Type-safe tool interface with type parameters
+ *
+ * @template TParameters - Tool parameters type (defaults to AbstractToolParameters for backward compatibility)
+ * @template TResult - Tool result type (defaults to ToolResult for backward compatibility)
+ */
+interface IToolContract<TParameters = TToolParameters, TResult = IToolResult> {
+    readonly schema: IToolSchema;
+    execute(parameters: TParameters, context: IToolExecutionContext): Promise<TResult>;
+    validate(parameters: TParameters): boolean;
+    validateParameters(parameters: TParameters): IParameterValidationResult;
+    getDescription(): string;
+    getName(): string;
+}
+/**
+ * Runtime tool instance contract used by Robota internals.
+ *
+ * Tools passed into Agent configuration must support EventService injection
+ * so Robota can emit unified tool lifecycle events.
+ */
+interface IToolWithEventService<TParameters = TToolParameters, TResult = IToolResult> extends IToolContract<TParameters, TResult> {
+    setEventService(eventService: IEventService | undefined): void;
+}
+/**
+ * Abstract base class for tools with type parameter support
+ * Provides type-safe parameter handling and result processing
+ *
+ * 🎯 ARCHITECTURAL PRINCIPLES:
+ * - Pure abstract class - depends only on interfaces
+ * - No concrete class dependencies (EventService interface only)
+ * - Dependency Injection for all external dependencies
+ * - Graceful degradation (undefined dependencies = silent operation)
+ *
+ * @template TParameters - Tool parameters type (defaults to TToolParameters)
+ * @template TResult - Tool result type (defaults to ToolResult for backward compatibility)
+ */
+declare abstract class AbstractTool<TParameters = TToolParameters, TResult = IToolResult> implements IToolWithEventService<TParameters, TResult> {
+    abstract readonly schema: IToolSchema;
+    /**
+     * Logger for tool operations
+     */
+    protected readonly logger: ILogger;
+    /**
+     * EventService for direct event emission (optional)
+     * If undefined, tool operates silently without emitting events
+     */
+    private eventService;
+    /**
+     * Constructor with simplified options
+     *
+     * 🎯 DEPENDENCY INJECTION:
+     * All dependencies are injected via options parameter
+     * No concrete classes are instantiated within this constructor
+     *
+     * @param options - Configuration options for the tool
+     */
+    constructor(options?: IAbstractToolOptions);
+    /**
+     * Set EventService for post-construction injection
+     *
+     * 🎯 DEPENDENCY INJECTION:
+     * Accepts EventService as-is without transformation
+     * Caller is responsible for providing properly configured EventService
+     *
+     * @param eventService - EventService instance to use for event emission (or undefined for silent operation)
+     */
+    setEventService(eventService: IEventService | undefined): void;
+    /**
+     * Get current EventService (for testing/inspection)
+     */
+    protected getEventService(): IEventService | undefined;
+    /**
+     * Emit event through EventService (if available)
+     * If EventService is not available, silently ignores the event (Null Object Pattern)
+     *
+     * @param eventType - Type of event to emit
+     * @param data - Event data
+     */
+    protected emitEvent(eventType: string, data: IBaseEventData): void;
+    /**
+     * Execute tool with simplified lifecycle
+     * @param parameters - Tool parameters
+     * @param context - Optional execution context
+     * @returns Promise resolving to tool result
+     */
+    execute(parameters: TParameters, context: IToolExecutionContext): Promise<TResult>;
+    /**
+     * Concrete implementation of tool execution
+     * This method should be implemented by subclasses to provide actual tool logic
+     *
+     * @param parameters - Tool parameters
+     * @param context - Optional execution context
+     * @returns Promise resolving to tool result
+     */
+    protected abstract executeImpl(parameters: TParameters, context: IToolExecutionContext): Promise<TResult>;
+    validate(parameters: TParameters): boolean;
+    /**
+     * Validate tool parameters with detailed result (default implementation)
+     */
+    validateParameters(parameters: TParameters): IParameterValidationResult;
+    getDescription(): string;
+    getName(): string;
+}
+
+/**
+ * Cache key identifying a unique LLM execution request
+ */
+interface ICacheKey {
+    /** SHA-256 hash of the serialized request */
+    hash: string;
+    /** Model identifier */
+    model: string;
+    /** Provider name */
+    provider: string;
+}
+/**
+ * Cached LLM response entry
+ */
+interface ICacheEntry {
+    /** Cache key that produced this entry */
+    key: ICacheKey;
+    /** Cached response content */
+    response: string;
+    /** When the entry was cached */
+    timestamp: number;
+    /** SHA-256 integrity hash of the response */
+    integrityHash: string;
+}
+/**
+ * Cache storage interface for pluggable backends
+ */
+interface ICacheStorage {
+    /** Retrieve a cached entry by key hash */
+    get(hash: string): ICacheEntry | undefined;
+    /** Store a cache entry */
+    set(entry: ICacheEntry): void;
+    /** Delete a cached entry by key hash */
+    delete(hash: string): boolean;
+    /** Clear all cached entries */
+    clear(): void;
+    /** Get cache statistics */
+    getStats(): ICacheStats;
+}
+/**
+ * Cache performance statistics
+ */
+interface ICacheStats {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Current number of cached entries */
+    entries: number;
+    /** Hit rate (hits / (hits + misses)), 0 if no lookups */
+    hitRate: number;
+}
+/**
+ * Configuration options for execution caching
+ */
+interface ICacheOptions {
+    /** Whether caching is enabled */
+    enabled: boolean;
+    /** Maximum number of cached entries */
+    maxEntries: number;
+    /** Time-to-live in milliseconds */
+    ttlMs: number;
+}
+
+/**
+ * IExecutionContextInjection
+ *
+ * Minimal context payload used to inject an existing ownerPath into a new agent instance
+ * (e.g., when a tool creates an agent and must preserve absolute ownerPath semantics).
+ *
+ * NOTE: This is intentionally NOT ToolExecutionContext. ToolExecutionContext is for tool calls
+ * and requires toolName/parameters; agent creation only needs ownerPath and execution linkage.
+ */
+interface IExecutionContextInjection {
+    ownerPath?: IOwnerPathSegment[];
+    parentExecutionId?: string;
+    rootExecutionId?: string;
+    executionLevel?: number;
+    sourceId?: string;
+}
+/**
+ * Provider-specific configuration
+ */
+interface IAgentProviderConfig {
+    openai?: {
+        apiKey?: string;
+        baseURL?: string;
+        organization?: string;
+        [key: string]: TProviderConfigValue | undefined;
+    };
+    anthropic?: {
+        apiKey?: string;
+        baseURL?: string;
+        [key: string]: TProviderConfigValue | undefined;
+    };
+    google?: {
+        apiKey?: string;
+        projectId?: string;
+        location?: string;
+        [key: string]: TProviderConfigValue | undefined;
+    };
+    [provider: string]: Record<string, TProviderConfigValue | undefined> | undefined;
+}
+/**
+ * Agent configuration options - New design with aiProviders array and defaultModel
+ */
+interface IAgentConfig {
+    id?: string;
+    name: string;
+    aiProviders: IAIProvider[];
+    defaultModel: {
+        provider: string;
+        model: string;
+        temperature?: number;
+        maxTokens?: number;
+        topP?: number;
+        systemMessage?: string;
+    };
+    tools?: Array<IToolWithEventService>;
+    plugins?: Array<IPluginContract<IPluginOptions, IPluginStats>>;
+    modules?: IModule[];
+    systemMessage?: string;
+    systemPrompt?: string;
+    conversationId?: string;
+    sessionId?: string;
+    userId?: string;
+    metadata?: TUniversalMessageMetadata;
+    context?: Record<string, TConfigValue>;
+    logging?: {
+        level?: TUtilLogLevel;
+        enabled?: boolean;
+        format?: string;
+        destination?: string;
+    };
+    providerConfig?: IAgentProviderConfig;
+    stream?: boolean;
+    toolChoice?: 'auto' | 'none' | string;
+    responseFormat?: IResponseFormatConfig;
+    safetySettings?: ISafetySetting[];
+    timeout?: number;
+    retryAttempts?: number;
+    rateLimiting?: {
+        enabled?: boolean;
+        maxRequests?: number;
+        windowMs?: number;
+    };
+    eventService?: IEventService;
+    executionContext?: IExecutionContextInjection;
+    cache?: ICacheOptions;
+}
+/**
+ * Agent template interface
+ */
+interface IAgentTemplate {
+    id: string;
+    name: string;
+    description?: string;
+    category?: string;
+    tags?: string[];
+    config: IAgentConfig;
+    version?: string;
+    author?: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+/**
+ * Agent run options - type-safe interface for all agent execution options
+ */
+interface IRunOptions {
+    temperature?: number;
+    maxTokens?: number;
+    stream?: boolean;
+    toolChoice?: 'auto' | 'none' | string;
+    sessionId?: string;
+    userId?: string;
+    metadata?: TMetadata;
+}
+/**
+ * Generic agent interface with type parameters for enhanced type safety
+ *
+ * @template TConfig - Agent configuration type (defaults to IAgentConfig for backward compatibility)
+ * @template TContext - Execution context type (defaults to IRunOptions for backward compatibility)
+ * @template TUniversalMessage - Message type (defaults to TUniversalMessage for backward compatibility)
+ */
+interface IAgent<TConfig = IAgentConfig, TContext = IRunOptions, TMessage = TUniversalMessage> {
+    /**
+     * Configure the agent with type-safe configuration
+     */
+    configure?(config: TConfig): Promise<void>;
+    /**
+     * Run agent with user input and type-safe context
+     */
+    run(input: string, context?: TContext): Promise<string>;
+    /**
+     * Run agent with streaming response and type-safe context
+     */
+    runStream(input: string, context?: TContext): AsyncGenerator<string, void, never>;
+    /**
+     * Get conversation history with type-safe messages
+     */
+    getHistory(): TMessage[];
+    /**
+     * Clear conversation history
+     */
+    clearHistory(): void;
+}
+/**
+ * Response format configuration
+ */
+interface IResponseFormatConfig {
+    type?: 'text' | 'json_object';
+    schema?: Record<string, TConfigValue>;
+}
+/**
+ * Safety setting configuration
+ */
+interface ISafetySetting {
+    category: string;
+    threshold: string;
+    [key: string]: TConfigValue;
+}
+
+/**
+ * Provider-agnostic media output reference.
+ * Providers must not return raw binary payloads in this contract.
+ */
+interface IMediaOutputRef {
+    kind: 'asset' | 'uri';
+    assetId?: string;
+    uri?: string;
+    mimeType?: string;
+    bytes?: number;
+}
+interface IProviderMediaError {
+    code: 'PROVIDER_AUTH_ERROR' | 'PROVIDER_RATE_LIMITED' | 'PROVIDER_TIMEOUT' | 'PROVIDER_INVALID_REQUEST' | 'PROVIDER_UPSTREAM_ERROR' | 'PROVIDER_JOB_NOT_FOUND' | 'PROVIDER_JOB_NOT_CANCELLABLE';
+    message: string;
+    details?: Record<string, TUniversalValue>;
+}
+type TProviderMediaResult<TValue> = {
+    ok: true;
+    value: TValue;
+} | {
+    ok: false;
+    error: IProviderMediaError;
+};
+interface IInlineImageInputSource {
+    kind: 'inline';
+    mimeType: string;
+    data: string;
+}
+interface IUriImageInputSource {
+    kind: 'uri';
+    uri: string;
+    mimeType?: string;
+}
+type TImageInputSource = IInlineImageInputSource | IUriImageInputSource;
+interface IImageGenerationRequest {
+    prompt: string;
+    model: string;
+}
+interface IImageEditRequest {
+    image: TImageInputSource;
+    prompt: string;
+    model: string;
+}
+interface IImageComposeRequest {
+    images: TImageInputSource[];
+    prompt: string;
+    model: string;
+}
+interface IImageGenerationResult {
+    outputs: IMediaOutputRef[];
+    model: string;
+}
+interface IImageGenerationProvider {
+    generateImage(request: IImageGenerationRequest): Promise<TProviderMediaResult<IImageGenerationResult>>;
+    editImage?(request: IImageEditRequest): Promise<TProviderMediaResult<IImageGenerationResult>>;
+    composeImage?(request: IImageComposeRequest): Promise<TProviderMediaResult<IImageGenerationResult>>;
+}
+interface IVideoGenerationRequest {
+    prompt: string;
+    model: string;
+    durationSeconds?: number;
+    aspectRatio?: string;
+    seed?: number;
+    inputImages?: TImageInputSource[];
+}
+interface IVideoJobAccepted {
+    jobId: string;
+    status: 'queued' | 'running';
+    createdAt: string;
+}
+interface IVideoJobSnapshot {
+    jobId: string;
+    status: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+    output?: IMediaOutputRef;
+    error?: IProviderMediaError;
+    updatedAt: string;
+}
+interface IVideoGenerationProvider {
+    createVideo(request: IVideoGenerationRequest): Promise<TProviderMediaResult<IVideoJobAccepted>>;
+    getVideoJob(jobId: string): Promise<TProviderMediaResult<IVideoJobSnapshot>>;
+    cancelVideoJob(jobId: string): Promise<TProviderMediaResult<IVideoJobSnapshot>>;
+}
+declare function isImageGenerationProvider(provider: object): provider is IImageGenerationProvider;
+declare function isVideoGenerationProvider(provider: object): provider is IVideoGenerationProvider;
+
+/**
+ * Reusable type definitions for manager layer
+ */
+/**
+ * Agent creation metadata type
+ * Used for storing additional information about agent creation and configuration
+ */
+type TAgentCreationMetadata = Record<string, string | number | boolean | Date>;
+/**
+ * Tool execution parameters for manager operations
+ * Used for tool parameter validation and execution in manager context
+ */
+type TManagerToolParameters = Record<string, string | number | boolean | string[] | number[] | boolean[]>;
+/**
+ * Configuration validation result
+ */
+interface IConfigValidationResult {
+    isValid: boolean;
+    errors: string[];
+    warnings?: string[];
+}
+/**
+ * AI Provider Manager interface for provider registration and selection
+ */
+interface IAIProviderManager {
+    /**
+     * Register an AI provider
+     */
+    addProvider(name: string, provider: IAIProvider): void;
+    /**
+     * Remove an AI provider
+     */
+    removeProvider(name: string): void;
+    /**
+     * Get registered provider by name
+     */
+    getProvider(name: string): IAIProvider | undefined;
+    /**
+     * Get all registered providers
+     */
+    getProviders(): Record<string, IAIProvider>;
+    /**
+     * Set current provider and model
+     */
+    setCurrentProvider(name: string, model: string): void;
+    /**
+     * Get current provider and model
+     */
+    getCurrentProvider(): {
+        provider: string;
+        model: string;
+    } | undefined;
+    /**
+     * Check if provider is configured
+     */
+    isConfigured(): boolean;
+    /**
+     * Get available models for a provider
+     */
+    getAvailableModels(providerName: string): string[];
+}
+/**
+ * Tool Manager interface for tool registration and management
+ */
+interface IToolManager {
+    /**
+     * Register a tool
+     */
+    addTool(schema: IToolSchema, executor: TToolExecutor): void;
+    /**
+     * Remove a tool by name
+     */
+    removeTool(name: string): void;
+    /**
+     * Get tool interface by name
+     */
+    getTool(name: string): ITool | undefined;
+    /**
+     * Get tool schema by name
+     */
+    getToolSchema(name: string): IToolSchema | undefined;
+    /**
+     * Get all registered tools
+     */
+    getTools(): IToolSchema[];
+    /**
+     * Execute a tool
+     */
+    executeTool(name: string, parameters: TToolParameters, context?: IToolExecutionContext): Promise<TUniversalValue>;
+    /**
+     * Check if tool exists
+     */
+    hasTool(name: string): boolean;
+    /**
+     * Set allowed tools (for filtering)
+     */
+    setAllowedTools(tools: string[]): void;
+    /**
+     * Get allowed tools
+     */
+    getAllowedTools(): string[] | undefined;
+}
+/**
+ * Agent creation options
+ */
+interface IAgentCreationOptions {
+    /** Override default configuration */
+    overrides?: Partial<IAgentConfig>;
+    /** Validation options */
+    validation?: {
+        strict?: boolean;
+        skipOptional?: boolean;
+    };
+    /** Additional metadata */
+    metadata?: TAgentCreationMetadata;
+}
+/**
+ * Agent Factory interface for agent creation and configuration
+ */
+interface IAgentFactory {
+    /**
+     * Create agent instance
+     */
+    createAgent(config: IAgentConfig, options?: IAgentCreationOptions): IAgent<IAgentConfig>;
+    /**
+     * Validate agent configuration
+     */
+    validateConfig(config: IAgentConfig): IConfigValidationResult;
+    /**
+     * Get default configuration
+     */
+    getDefaultConfig(): IAgentConfig;
+    /**
+     * Merge configurations
+     */
+    mergeConfig(base: IAgentConfig, override: Partial<IAgentConfig>): IAgentConfig;
+}
+
+/**
+ * Execution step definition for tools that support step-by-step progress reporting
+ */
+interface IToolExecutionStep {
+    /** Unique identifier for this step */
+    id: string;
+    /** Human-readable name of the step */
+    name: string;
+    /** Tool-provided estimated duration for this step in milliseconds */
+    estimatedDuration: number;
+    /** Optional description of what this step does */
+    description?: string;
+}
+/**
+ * Progress callback function type for real-time progress updates
+ */
+type TToolProgressCallback = (step: string, progress: number) => void;
+/**
+ * 🆕 IProgressReportingTool - Optional interface for tools that can provide their own progress information
+ *
+ * This interface extends the standard ITool to allow tools to optionally provide:
+ * - Estimated execution duration
+ * - Step-by-step execution plans
+ * - Real-time progress callbacks
+ *
+ * Benefits:
+ * - Tools can provide accurate progress information based on their internal knowledge
+ * - No simulation or fake progress - only real tool-provided estimates
+ * - Completely optional - existing tools work unchanged
+ * - Tools can self-report progress for better user experience
+ */
+interface IProgressReportingTool extends ITool {
+    /**
+     * Get estimated execution duration for given parameters (optional)
+     *
+     * Tools can implement this to provide accurate time estimates based on:
+     * - Parameter complexity (e.g., search query length, file size)
+     * - Historical execution data
+     * - Internal optimization knowledge
+     *
+     * @param parameters - The parameters that will be passed to execute()
+     * @returns Estimated duration in milliseconds, or undefined if not available
+     */
+    getEstimatedDuration?(parameters: TToolParameters): number;
+    /**
+     * Get execution steps for given parameters (optional)
+     *
+     * Tools can implement this to provide step-by-step execution plans:
+     * - webSearch: [query processing, API call, result parsing, filtering]
+     * - fileSearch: [file scanning, content reading, pattern matching, result formatting]
+     * - github-mcp: [authentication, API request, response processing, data transformation]
+     *
+     * @param parameters - The parameters that will be passed to execute()
+     * @returns Array of execution steps, or undefined if not available
+     */
+    getExecutionSteps?(parameters: TToolParameters): IToolExecutionStep[];
+    /**
+     * Set progress callback for real-time updates (optional)
+     *
+     * Tools can implement this to provide real-time progress updates during execution:
+     * - Called when each step starts/completes
+     * - Progress value between 0-100 representing completion percentage
+     * - Step name helps users understand what's currently happening
+     *
+     * @param callback - Function to call with progress updates
+     */
+    setProgressCallback?(callback: TToolProgressCallback): void;
+}
+/**
+ * Type guard to check if a tool implements progress reporting
+ */
+declare function isProgressReportingTool(tool: ITool): tool is IProgressReportingTool;
+/**
+ * Helper function to safely get estimated duration from any tool
+ */
+declare function getToolEstimatedDuration(tool: ITool, parameters: TToolParameters): number | undefined;
+/**
+ * Helper function to safely get execution steps from any tool
+ */
+declare function getToolExecutionSteps(tool: ITool, parameters: TToolParameters): IToolExecutionStep[] | undefined;
+/**
+ * Helper function to safely set progress callback on any tool
+ */
+declare function setToolProgressCallback(tool: ITool, callback: TToolProgressCallback): boolean;
+
+/**
+ * Service layer interfaces for the agents package
+ * Defines contracts for stateless service implementations
+ */
+
+/**
+ * Reusable type definitions for service layer
+ */
+/**
+ * Metadata type for conversation and execution context
+ * Used for storing additional information about conversations, responses, and execution
+ */
+type TConversationContextMetadata = Record<string, string | number | boolean | Date>;
+/**
+ * Tool execution parameters type
+ * Used for passing parameters to tool execution methods
+ */
+type TToolExecutionParameters = Record<string, string | number | boolean | string[] | number[] | boolean[]>;
+/**
+ * Execution metadata type
+ * Used for storing metadata about execution processes and options
+ */
+type TExecutionMetadata = Record<string, string | number | boolean | Date>;
+/**
+ * Response metadata type
+ * Used for storing metadata about AI provider responses and streaming chunks
+ */
+type TResponseMetadata = Record<string, string | number | boolean | Date>;
+/**
+ * Tool call data structure for function calls
+ */
+/**
+ * Tool execution request
+ */
+interface IToolExecutionRequest {
+    toolName: string;
+    parameters: TToolParameters;
+    executionId?: string;
+    metadata?: TToolMetadata;
+    ownerType?: string;
+    ownerId?: string;
+    ownerPath?: IOwnerPathSegment[];
+    eventService?: IEventService;
+    baseEventService?: IEventService;
+}
+/**
+ * Conversation context containing messages and metadata
+ */
+interface IConversationContext {
+    /** All messages in the conversation */
+    messages: TUniversalMessage[];
+    /** System message for the conversation */
+    systemMessage?: string;
+    /** Model to use for generation */
+    model: string;
+    /** Provider to use for generation */
+    provider: string;
+    /** Temperature for generation */
+    temperature?: number;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Available tools */
+    tools?: IToolSchema[];
+    /** Additional metadata */
+    metadata?: TConversationContextMetadata;
+}
+/**
+ * Response from AI provider
+ */
+interface IConversationResponse {
+    /** Generated content */
+    content: string;
+    /** Tool calls if any */
+    toolCalls?: IToolCall[];
+    /** Usage statistics */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** Response metadata */
+    metadata?: TResponseMetadata;
+    /** Finish reason */
+    finishReason?: string;
+}
+/**
+ * Streaming response chunk
+ */
+interface IStreamingChunk {
+    /** Content delta */
+    delta: string;
+    /** Whether this is the final chunk */
+    done: boolean;
+    /** Tool calls if any */
+    toolCalls?: IToolCall[];
+    /** Usage statistics (only in final chunk) */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+/**
+ * Service options for conversation operations
+ */
+interface IConversationServiceOptions {
+    /** Maximum conversation history length */
+    maxHistoryLength?: number;
+    /** Whether to automatically retry on failure */
+    enableRetry?: boolean;
+    /** Maximum number of retries */
+    maxRetries?: number;
+    /** Retry delay in milliseconds */
+    retryDelay?: number;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Context options for conversation preparation
+ */
+interface IContextOptions {
+    systemMessage?: string;
+    temperature?: number;
+    maxTokens?: number;
+    tools?: IToolSchema[];
+    metadata?: TConversationContextMetadata;
+}
+/**
+ * Execution service options
+ */
+interface IExecutionServiceOptions {
+    /** Maximum number of tool execution rounds */
+    maxToolRounds?: number;
+    /** Tool execution timeout */
+    toolTimeout?: number;
+    /** Whether to enable parallel tool execution */
+    enableParallelExecution?: boolean;
+    /** Additional execution metadata */
+    metadata?: TExecutionMetadata;
+}
+/**
+ * Interface for conversation service operations
+ * All methods should be stateless and pure functions
+ */
+interface IConversationService {
+    /**
+     * Prepare conversation context from messages and configuration
+     * Pure function that transforms inputs to context object
+     */
+    prepareContext(messages: TUniversalMessage[], model: string, provider: string, contextOptions?: IContextOptions, serviceOptions?: IConversationServiceOptions): IConversationContext;
+    /**
+     * Generate a response using the AI provider
+     * Stateless operation that handles the full request-response cycle
+     */
+    generateResponse(provider: IAIProvider, context: IConversationContext, serviceOptions?: IConversationServiceOptions): Promise<IConversationResponse>;
+    /**
+     * Generate streaming response using the AI provider
+     * Stateless streaming operation
+     */
+    generateStreamingResponse(provider: IAIProvider, context: IConversationContext, serviceOptions?: IConversationServiceOptions): AsyncGenerator<IStreamingChunk, void, never>;
+    /**
+     * Validate conversation context
+     * Pure validation function
+     */
+    validateContext(context: IConversationContext): {
+        isValid: boolean;
+        errors: string[];
+    };
+}
+/**
+ * Interface for tool execution service operations
+ */
+interface IToolExecutionService {
+    /**
+     * Execute a single tool
+     */
+    executeTool(toolName: string, parameters: TToolParameters): Promise<TUniversalValue>;
+    /**
+     * Execute multiple tools in parallel
+     */
+    executeToolsParallel(toolCalls: IToolExecutionRequest[]): Promise<TUniversalValue[]>;
+    /**
+     * Execute multiple tools sequentially
+     */
+    executeToolsSequential(toolCalls: IToolExecutionRequest[]): Promise<TUniversalValue[]>;
+}
+/**
+ * Interface for execution service operations
+ */
+interface IExecutionService {
+    /**
+     * Execute complete agent pipeline
+     */
+    execute(input: string, context: IConversationContext, options?: IExecutionServiceOptions): Promise<string>;
+    /**
+     * Execute streaming agent pipeline
+     */
+    executeStream(input: string, context: IConversationContext, options?: IExecutionServiceOptions): AsyncGenerator<string, void, never>;
+}
+
+/**
+ * Request for executing a streaming chat completion through an executor
+ */
+interface IChatExecutionRequest {
+    /** Array of messages in the conversation */
+    messages: TUniversalMessage[];
+    /** Chat options including model, temperature, etc. */
+    options?: IChatOptions;
+    /** Available tools for the AI to use */
+    tools?: IToolSchema[];
+    /** Target AI provider (e.g., 'openai', 'anthropic', 'google') */
+    provider: string;
+    /** Specific model to use */
+    model: string;
+}
+/**
+ * Request for executing a streaming chat completion through an executor
+ */
+interface IStreamExecutionRequest extends IChatExecutionRequest {
+    /** Indicates this is a streaming request */
+    stream: true;
+}
+/**
+ * Interface for executing AI provider operations
+ *
+ * Executors abstract the execution mechanism, allowing providers to work
+ * with either local API calls or remote server calls transparently.
+ *
+ * Implementation patterns:
+ * - LocalExecutor: Direct API calls using provider SDKs
+ * - RemoteExecutor: HTTP/WebSocket calls to remote server
+ * - CacheExecutor: Cached responses with explicit error propagation
+ * - HybridExecutor: Conditional local/remote execution
+ */
+interface IExecutor {
+    /**
+     * Execute a chat completion request
+     *
+     * @param request - Chat execution request with messages, options, and tools
+     * @returns Promise resolving to assistant message response
+     *
+     * @example
+     * ```typescript
+     * const response = await executor.executeChat({
+     *   messages: [{ role: 'user', content: 'Hello!' }],
+     *   options: { model: 'gpt-4', temperature: 0.7 },
+     *   provider: 'openai',
+     *   model: 'gpt-4'
+     * });
+     * ```
+     */
+    executeChat(request: IChatExecutionRequest): Promise<IAssistantMessage>;
+    /**
+     * Execute a streaming chat completion request
+     *
+     * @param request - Streaming chat execution request
+     * @returns AsyncIterable of message chunks
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of executor.executeChatStream({
+     *   messages: [{ role: 'user', content: 'Tell me a story' }],
+     *   options: { model: 'gpt-4' },
+     *   provider: 'openai',
+     *   model: 'gpt-4',
+     *   stream: true
+     * })) {
+     *   console.log(chunk.content);
+     * }
+     * ```
+     */
+    executeChatStream?(request: IStreamExecutionRequest): AsyncIterable<TUniversalMessage>;
+    /**
+     * Check if the executor supports tool calling
+     * @returns true if tool calling is supported
+     */
+    supportsTools(): boolean;
+    /**
+     * Validate executor configuration
+     * @returns true if configuration is valid
+     */
+    validateConfig(): boolean;
+    /**
+     * Clean up resources when executor is no longer needed
+     */
+    dispose?(): Promise<void>;
+    /**
+     * Get executor name/identifier
+     */
+    readonly name: string;
+    /**
+     * Get executor version
+     */
+    readonly version: string;
+}
+/**
+ * Configuration options for local executor
+ */
+interface ILocalExecutorConfig {
+    /** Timeout for API requests in milliseconds */
+    timeout?: number;
+    /** Maximum number of retry attempts */
+    maxRetries?: number;
+    /** Base delay between retries in milliseconds */
+    retryDelay?: number;
+    /** Whether to enable request/response logging */
+    enableLogging?: boolean;
+}
+/**
+ * Configuration options for remote executor
+ */
+interface IRemoteExecutorConfig {
+    /** Remote server URL */
+    serverUrl: string;
+    /** User authentication token */
+    userApiKey: string;
+    /** Timeout for HTTP requests in milliseconds */
+    timeout?: number;
+    /** Maximum number of retry attempts */
+    maxRetries?: number;
+    /** Whether to enable WebSocket for streaming */
+    enableWebSocket?: boolean;
+    /** Custom headers to include in requests */
+    headers?: Record<string, string>;
+}
+
+interface IEventHistoryRecord {
+    eventName: string;
+    sequenceId: number;
+    timestamp: Date;
+    eventData: IBaseEventData;
+    context: IEventContext;
+}
+interface IEventHistorySnapshot {
+    lastSequenceId: number;
+    createdAt: Date;
+}
+interface IEventHistoryModule {
+    append(record: IEventHistoryRecord): void;
+    read(fromSequenceId: number, toSequenceId?: number): IEventHistoryRecord[];
+    readStream(fromSequenceId: number, toSequenceId?: number): AsyncIterable<IEventHistoryRecord>;
+    getSnapshot?(): IEventHistorySnapshot | undefined;
+}
+
+/**
+ * @fileoverview Abstract Agent Base Class
+ *
+ * 🎯 ABSTRACT CLASS - DO NOT DEPEND ON CONCRETE IMPLEMENTATIONS
+ *
+ * This class defines the foundational lifecycle for agent implementations.
+ * Subclasses provide provider/tool-specific behavior while inheriting the
+ * shared guarantees around initialization, history, and disposal.
+ */
+
+declare abstract class AbstractAgent<TConfig = IAgentConfig, TContext = IRunOptions, TMessage = TUniversalMessage> implements IAgent<TConfig, TContext, TMessage> {
+    protected history: TMessage[];
+    protected isInitialized: boolean;
+    protected config?: TConfig;
+    /**
+     * Initialize the agent (subclass responsibility)
+     */
+    protected abstract initialize(): Promise<void>;
+    /**
+     * Configure the agent with type-safe configuration
+     */
+    configure(config: TConfig): Promise<void>;
+    /**
+     * Run agent with user input and type-safe context
+     */
+    abstract run(input: string, context?: TContext): Promise<string>;
+    /**
+     * Run agent with streaming response and type-safe context
+     */
+    abstract runStream(input: string, context?: TContext): AsyncGenerator<string, void, never>;
+    /**
+     * Get conversation history with type-safe messages
+     */
+    getHistory(): TMessage[];
+    /**
+     * Clear conversation history
+     */
+    clearHistory(): void;
+    /**
+     * Add message to history
+     */
+    protected addMessage(message: TMessage): void;
+    /**
+     * Validate user input
+     */
+    protected validateInput(input: string): void;
+    /**
+     * Ensure agent is initialized before running
+     */
+    protected ensureInitialized(): Promise<void>;
+    /**
+     * Cleanup resources
+     */
+    dispose(): Promise<void>;
+}
+
+/**
+ * @fileoverview Abstract Manager Base Class
+ *
+ * 🎯 ABSTRACT CLASS - DO NOT IMPORT CONCRETE IMPLEMENTATIONS
+ *
+ * This class defines the common lifecycle contract for all manager implementations.
+ * It enforces explicit initialization/disposal semantics so that subclasses can
+ * provide their own resource management logic while sharing guard rails.
+ *
+ * Architectural rules:
+ * - Depends only on abstractions (no concrete manager implementations)
+ * - Provides finalize hooks (`doInitialize`, `doDispose`) for subclasses
+ * - Guards public APIs via `ensureInitialized`
+ */
+declare abstract class AbstractManager {
+    protected initialized: boolean;
+    /**
+     * Initialize the manager (idempotent)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Subclass-specific initialization logic
+     */
+    protected abstract doInitialize(): Promise<void>;
+    /**
+     * Dispose manager resources (idempotent)
+     */
+    dispose(): Promise<void>;
+    /**
+     * Subclass-specific disposal logic
+     */
+    protected abstract doDispose(): Promise<void>;
+    /**
+     * Whether the manager completed initialization
+     */
+    isInitialized(): boolean;
+    /**
+     * Ensure manager is initialized before performing operations
+     */
+    protected ensureInitialized(): void;
+}
+
+/**
+ * @fileoverview Abstract AI Provider Base Class
+ *
+ * 🎯 ABSTRACT CLASS - DO NOT DEPEND ON CONCRETE IMPLEMENTATIONS
+ *
+ * Defines the shared contract and helper utilities for all AI provider implementations.
+ * Concrete providers should extend this class and inject their own dependencies.
+ */
+
+/**
+ * Provider logging data type
+ * Used for storing logging information in provider operations
+ */
+type TProviderLoggingData = Record<string, string | number | boolean | Date | string[]>;
+/**
+ * Provider configuration base interface
+ */
+interface IProviderConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Enhanced provider configuration that supports executor injection
+ */
+interface IExecutorAwareProviderConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    /**
+     * Optional executor for handling AI requests
+     * When provided, the provider will delegate all chat operations to this executor
+     * instead of making direct API calls. This enables remote execution capabilities.
+     */
+    executor?: IExecutor;
+    [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:
+ *
+ * 1. EXTEND THIS CLASS:
+ *    ```typescript
+ *    export class OpenAIProvider extends AbstractAIProvider {
+ *        override readonly name = 'openai';
+ *        override readonly version = '1.0.0';
+ *    ```
+ *
+ * 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)
+ */
+declare abstract class AbstractAIProvider<TConfig = IProviderConfig> implements IAIProvider {
+    abstract readonly name: string;
+    abstract readonly version: string;
+    protected config?: TConfig;
+    protected executor?: IExecutor;
+    protected readonly logger: ILogger;
+    constructor(logger?: ILogger);
+    /**
+     * Configure the provider with type-safe configuration
+     */
+    configure(config: TConfig): Promise<void>;
+    private hasExecutor;
+    /**
+     * Each provider must implement chat using their own native SDK types internally
+     * @param messages - Array of messages from conversation history
+     * @param options - Chat options including tools, model settings, etc.
+     * @returns Promise resolving to a response
+     */
+    abstract chat(messages: TUniversalMessage[], options?: IChatOptions): Promise<TUniversalMessage>;
+    /**
+     * Each provider must implement streaming chat using their own native SDK types internally
+     * @param messages - Array of messages from conversation history
+     * @param options - Chat options including tools, model settings, etc.
+     * @returns AsyncIterable of response chunks
+     */
+    chatStream?(messages: TUniversalMessage[], options?: IChatOptions): AsyncIterable<TUniversalMessage>;
+    /**
+     * Provider-agnostic raw response API.
+     *
+     * This is the canonical "raw payload" entrypoint required by the AIProvider contract.
+     * The default implementation delegates to `chat()` and adapts the result into a
+     * RawProviderResponse shape.
+     */
+    generateResponse(payload: IProviderRequest): Promise<IRawProviderResponse>;
+    /**
+     * Provider-agnostic raw streaming API.
+     *
+     * If a provider does not implement chatStream, it does not support streaming.
+     */
+    generateStreamingResponse(payload: IProviderRequest): AsyncIterable<IRawProviderResponse>;
+    /**
+     * Default implementation - most modern providers support tools
+     * @returns true if tool calling is supported
+     */
+    supportsTools(): boolean;
+    /**
+     * Default implementation - providers can override for specific validation
+     * @returns true if configuration is valid
+     */
+    validateConfig(): boolean;
+    /**
+     * Utility method for validating TUniversalMessage array
+     * @param messages - Messages to validate
+     */
+    protected validateMessages(messages: TUniversalMessage[]): void;
+    /**
+     * Utility method for validating tool schemas
+     * @param tools - Tool schemas to validate
+     */
+    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>;
+    /**
+     * Clean up resources when provider is no longer needed
+     * Override this method in subclasses for additional cleanup
+     */
+    dispose(): Promise<void>;
+}
+
+/**
+ * @fileoverview Abstract Executor Base Class
+ *
+ * 🎯 ABSTRACT CLASS - DO NOT DEPEND ON CONCRETE IMPLEMENTATIONS
+ *
+ * Provides shared execution helpers (retry, timeout, validation, logging) for all
+ * executor implementations. Concrete executors should extend this class and inject
+ * their own logger implementation if they need custom logging behavior.
+ *
+ * @example
+ * ```typescript
+ * export class MyCustomExecutor extends AbstractExecutor {
+ *   async executeChat(request: IChatExecutionRequest): Promise<AssistantMessage> {
+ *     return this.withRetry(() => this.performChat(request));
+ *   }
+ * }
+ * ```
+ */
+declare abstract class AbstractExecutor implements IExecutor {
+    /**
+     * Logger injected via constructor (defaults to abstract logger)
+     */
+    protected readonly logger: ILogger;
+    constructor(logger?: ILogger);
+    abstract readonly name: string;
+    abstract readonly version: string;
+    /**
+     * Execute a chat completion request
+     * Must be implemented by concrete executor classes
+     */
+    abstract executeChat(request: IChatExecutionRequest): Promise<IAssistantMessage>;
+    /**
+     * Execute a streaming chat completion request
+     * Optional - can be implemented by concrete executor classes
+     */
+    abstract executeChatStream?(request: IStreamExecutionRequest): AsyncIterable<TUniversalMessage>;
+    /**
+     * Check if the executor supports tool calling
+     * Default implementation returns false, can be overridden
+     */
+    supportsTools(): boolean;
+    /**
+     * Validate executor configuration
+     * Default implementation returns true, can be overridden
+     */
+    validateConfig(): boolean;
+    /**
+     * Clean up resources when executor is no longer needed
+     * Default implementation does nothing, can be overridden
+     */
+    dispose?(): Promise<void>;
+    /**
+     * Execute function with retry logic
+     *
+     * @param fn - Function to execute with retries
+     * @param maxRetries - Maximum number of retry attempts (default: 3)
+     * @param retryDelay - Delay between retries in milliseconds (default: 1000)
+     * @returns Promise resolving to function result
+     */
+    protected withRetry<T>(fn: () => Promise<T>, maxRetries?: number, retryDelay?: number): Promise<T>;
+    /**
+     * Execute function with timeout
+     *
+     * @param promise - Promise to execute with timeout
+     * @param timeoutMs - Timeout in milliseconds
+     * @returns Promise resolving to function result
+     */
+    protected withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T>;
+    /**
+     * Delay execution for specified milliseconds
+     *
+     * @param ms - Milliseconds to delay
+     * @returns Promise that resolves after the delay
+     */
+    protected delay(ms: number): Promise<void>;
+    /**
+     * Log debug information (only if logging is enabled)
+     *
+     * @param message - Log message
+     * @param data - Optional data to log
+     */
+    protected logDebug(message: string, data?: TLoggerData): void;
+    /**
+     * Log error information
+     *
+     * @param message - Log message
+     * @param error - Error object
+     * @param data - Optional additional data
+     */
+    protected logError(message: string, error: Error, data?: TLoggerData): void;
+    /**
+     * Validate that request has required fields
+     *
+     * @param request - Chat execution request to validate
+     * @throws Error if validation fails
+     */
+    protected validateRequest(request: IChatExecutionRequest): void;
+    /**
+     * Validate that response is properly formatted
+     *
+     * @param response - Response to validate
+     * @throws Error if validation fails
+     */
+    protected validateResponse(response: TUniversalMessage): void;
+}
+
+interface IOpenAIMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    tool_calls?: {
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }[];
+    tool_call_id?: string;
+    name?: string;
+}
+interface IAnthropicProviderMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+interface IGoogleProviderMessage {
+    role: 'user' | 'model';
+    parts: {
+        text: string;
+    }[];
+}
+/**
+ * Provider message format union type
+ */
+type TProviderMessage = IOpenAIMessage | IAnthropicProviderMessage | IGoogleProviderMessage | TUniversalMessage;
+/**
+ * Universal message converter utility
+ * Handles message format conversion between different providers
+ */
+declare class MessageConverter {
+    /**
+     * Convert messages to provider-specific format
+     */
+    static toProviderFormat(messages: TUniversalMessage[], providerName: string): TProviderMessage[];
+    /**
+     * Convert to OpenAI format
+     */
+    private static toOpenAIFormat;
+    /**
+     * Convert to Anthropic format
+     */
+    private static toAnthropicFormat;
+    /**
+     * Convert to Google format
+     */
+    private static toGoogleFormat;
+    /**
+     * Convert to universal format (no conversion)
+     */
+    private static toUniversalFormat;
+    /**
+     * Extract system message from messages
+     */
+    static extractSystemMessage(messages: TUniversalMessage[]): string | undefined;
+    /**
+     * Filter non-system messages
+     */
+    static filterNonSystemMessages(messages: TUniversalMessage[]): TUniversalMessage[];
+}
+
+/**
+ * Validation result interface
+ */
+interface ISimpleValidationResult {
+    isValid: boolean;
+    errors: string[];
+    warnings?: string[];
+}
+/**
+ * Validation utility class
+ */
+declare class Validator {
+    /**
+     * Validate agent configuration
+     */
+    static validateAgentConfig(config: Partial<IAgentConfig>): ISimpleValidationResult;
+    /**
+     * Validate user input string
+     */
+    static validateUserInput(input: string): ISimpleValidationResult;
+    /**
+     * Validate provider name
+     */
+    static validateProviderName(name: string): ISimpleValidationResult;
+    /**
+     * Validate model name
+     */
+    static validateModelName(name: string): ISimpleValidationResult;
+    /**
+     * Validate API key format (basic check)
+     */
+    static validateApiKey(apiKey: string, provider?: string): ISimpleValidationResult;
+}
+declare const validateAgentConfig: typeof Validator.validateAgentConfig;
+declare const validateUserInput: typeof Validator.validateUserInput;
+declare const validateProviderName: typeof Validator.validateProviderName;
+declare const validateModelName: typeof Validator.validateModelName;
+declare const validateApiKey: typeof Validator.validateApiKey;
+
+/**
+ * Reusable type definitions for error utilities
+ */
+/**
+ * Error context data type
+ * Used for storing contextual information in error instances
+ */
+type TErrorContextData = Record<string, string | number | boolean | Date | Error | string[] | undefined>;
+/**
+ * Error external input type
+ * Used for handling external errors from unknown sources
+ */
+type TErrorExternalInput = Error | string | Record<string, string | number | boolean> | null | undefined;
+/**
+ * Base error class for all Robota errors
+ */
+declare abstract class RobotaError extends Error {
+    readonly context?: TErrorContextData | undefined;
+    abstract readonly code: string;
+    abstract readonly category: 'user' | 'system' | 'provider';
+    abstract readonly recoverable: boolean;
+    constructor(message: string, context?: TErrorContextData | undefined);
+}
+/**
+ * Configuration related errors
+ */
+declare class ConfigurationError extends RobotaError {
+    readonly code = "CONFIGURATION_ERROR";
+    readonly category: "user";
+    readonly recoverable = false;
+    constructor(message: string, context?: TErrorContextData);
+}
+/**
+ * Input validation errors
+ */
+declare class ValidationError extends RobotaError {
+    readonly field?: string | undefined;
+    readonly code = "VALIDATION_ERROR";
+    readonly category: "user";
+    readonly recoverable = false;
+    constructor(message: string, field?: string | undefined, context?: TErrorContextData);
+}
+/**
+ * Provider related errors
+ */
+declare class ProviderError extends RobotaError {
+    readonly provider: string;
+    readonly originalError?: Error | undefined;
+    readonly code = "PROVIDER_ERROR";
+    readonly category: "provider";
+    readonly recoverable = true;
+    constructor(message: string, provider: string, originalError?: Error | undefined, context?: TErrorContextData);
+}
+/**
+ * Authentication errors
+ */
+declare class AuthenticationError extends RobotaError {
+    readonly provider?: string | undefined;
+    readonly code = "AUTHENTICATION_ERROR";
+    readonly category: "user";
+    readonly recoverable = false;
+    constructor(message: string, provider?: string | undefined, context?: TErrorContextData);
+}
+/**
+ * Rate limit errors
+ */
+declare class RateLimitError extends RobotaError {
+    readonly retryAfter?: number | undefined;
+    readonly provider?: string | undefined;
+    readonly code = "RATE_LIMIT_ERROR";
+    readonly category: "provider";
+    readonly recoverable = true;
+    constructor(message: string, retryAfter?: number | undefined, provider?: string | undefined, context?: TErrorContextData);
+}
+/**
+ * Network/connectivity errors
+ */
+declare class NetworkError extends RobotaError {
+    readonly originalError?: Error | undefined;
+    readonly code = "NETWORK_ERROR";
+    readonly category: "system";
+    readonly recoverable = true;
+    constructor(message: string, originalError?: Error | undefined, context?: TErrorContextData);
+}
+/**
+ * Tool execution errors
+ */
+declare class ToolExecutionError extends RobotaError {
+    readonly toolName: string;
+    readonly originalError?: Error | undefined;
+    readonly code = "TOOL_EXECUTION_ERROR";
+    readonly category: "system";
+    readonly recoverable = false;
+    constructor(message: string, toolName: string, originalError?: Error | undefined, context?: TErrorContextData);
+}
+/**
+ * Model not available errors
+ */
+declare class ModelNotAvailableError extends RobotaError {
+    readonly availableModels?: string[] | undefined;
+    readonly code = "MODEL_NOT_AVAILABLE";
+    readonly category: "user";
+    readonly recoverable = false;
+    constructor(model: string, provider: string, availableModels?: string[] | undefined, context?: TErrorContextData);
+}
+/**
+ * Circuit breaker open error
+ */
+declare class CircuitBreakerOpenError extends RobotaError {
+    readonly code = "CIRCUIT_BREAKER_OPEN";
+    readonly category: "system";
+    readonly recoverable = true;
+    constructor(message?: string, context?: TErrorContextData);
+}
+/**
+ * Plugin errors
+ */
+declare class PluginError extends RobotaError {
+    readonly pluginName: string;
+    readonly code = "PLUGIN_ERROR";
+    readonly category: "system";
+    readonly recoverable = false;
+    constructor(message: string, pluginName: string, context?: TErrorContextData);
+}
+/**
+ * Storage related errors
+ */
+declare class StorageError extends RobotaError {
+    readonly code = "STORAGE_ERROR";
+    readonly category: "system";
+    readonly recoverable = true;
+    constructor(message: string, context?: TErrorContextData);
+}
+/**
+ * Cache integrity validation errors
+ */
+declare class CacheIntegrityError extends RobotaError {
+    readonly code = "CACHE_INTEGRITY_ERROR";
+    readonly category: "system";
+    readonly recoverable = false;
+    constructor(message: string, context?: TErrorContextData);
+}
+/**
+ * Error utility functions
+ */
+declare class ErrorUtils {
+    /**
+     * Check if error is recoverable
+     */
+    static isRecoverable(error: Error): boolean;
+    /**
+     * Extract error code from any error
+     */
+    static getErrorCode(error: Error): string;
+    /**
+     * Create error from unknown value
+     */
+    static fromUnknown(error: TErrorExternalInput, defaultMessage?: string): RobotaError;
+    /**
+     * Wrap external errors
+     */
+    static wrapProviderError(error: TErrorExternalInput, provider: string, operation: string): ProviderError;
+}
+
+interface IPeriodicTaskOptions {
+    name: string;
+    intervalMs: number;
+}
+/**
+ * Start a periodic async task with consistent error logging.
+ * SSOT helper to avoid duplicating setInterval(async () => ...) patterns.
+ */
+declare function startPeriodicTask(logger: ILogger, options: IPeriodicTaskOptions, task: () => Promise<void>): TTimerId;
+declare function stopPeriodicTask(timer: TTimerId | undefined): void;
+
+/**
+ * Cross-platform timer identifier type
+ * Works in both Node.js and browser environments
+ */
+type TTimerId = ReturnType<typeof setTimeout>;
+
+/**
+ * Local executor that directly delegates to AI provider instances
+ *
+ * This executor maintains a registry of AI provider instances and delegates
+ * chat execution requests to the appropriate provider based on the provider
+ * name in the request. This is the "traditional" execution mode where
+ * API calls are made directly from the client.
+ *
+ * @example
+ * ```typescript
+ * import { LocalExecutor } from '@robota-sdk/agent-core';
+ * import { OpenAIProvider } from '@robota-sdk/agent-provider-openai';
+ *
+ * const executor = new LocalExecutor();
+ * executor.registerProvider('openai', new OpenAIProvider({ apiKey: 'sk-...' }));
+ *
+ * const response = await executor.executeChat({
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ *   provider: 'openai',
+ *   model: 'gpt-4'
+ * });
+ * ```
+ */
+declare class LocalExecutor extends AbstractExecutor {
+    readonly name = "local";
+    readonly version = "1.0.0";
+    private providers;
+    private config;
+    constructor(config?: ILocalExecutorConfig);
+    /**
+     * Register an AI provider instance for use with this executor
+     *
+     * @param name - Provider name (e.g., 'openai', 'anthropic', 'google')
+     * @param provider - Provider instance that implements the required chat methods
+     */
+    registerProvider(name: string, provider: IAIProviderInstance): void;
+    /**
+     * Unregister an AI provider
+     *
+     * @param name - Provider name to remove
+     */
+    unregisterProvider(name: string): void;
+    /**
+     * Get registered provider instance
+     *
+     * @param name - Provider name
+     * @returns Provider instance or undefined if not registered
+     */
+    getProvider(name: string): IAIProviderInstance | undefined;
+    /**
+     * Execute a chat completion request by delegating to the appropriate provider
+     */
+    executeChat(request: IChatExecutionRequest): Promise<IAssistantMessage>;
+    /**
+     * Execute a streaming chat completion request
+     */
+    executeChatStream(request: IStreamExecutionRequest): AsyncIterable<TUniversalMessage>;
+    /**
+     * Check if any registered providers support tools
+     */
+    supportsTools(): boolean;
+    /**
+     * Validate executor configuration and all registered providers
+     */
+    validateConfig(): boolean;
+    /**
+     * Clean up all registered providers
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Interface that AI provider instances must implement to work with LocalExecutor
+ *
+ * This interface represents the subset of AI provider methods that LocalExecutor
+ * needs to delegate to. It's designed to be compatible with existing BaseAIProvider
+ * implementations from @robota-sdk packages.
+ */
+interface IAIProviderInstance {
+    /** Provider name */
+    readonly name?: string;
+    /** Chat completion method */
+    chat?(messages: TUniversalMessage[], options?: IChatOptions): Promise<TUniversalMessage>;
+    /** Streaming chat completion method */
+    chatStream?(messages: TUniversalMessage[], options?: IChatOptions): AsyncIterable<TUniversalMessage>;
+    /** Check if provider supports tools */
+    supportsTools?(): boolean;
+    /** Validate provider configuration */
+    validateConfig?(): boolean;
+    /** Clean up provider resources */
+    dispose?(): Promise<void>;
+}
+
+interface IEventEmitterMetricsSnapshot {
+    totalEmitted: number;
+    totalErrors: number;
+}
+interface IEventEmitterMetrics {
+    incrementEmitted(): void;
+    incrementErrors(): void;
+    getSnapshot(): IEventEmitterMetricsSnapshot;
+}
+declare class InMemoryEventEmitterMetrics implements IEventEmitterMetrics {
+    private totalEmitted;
+    private totalErrors;
+    incrementEmitted(): void;
+    incrementErrors(): void;
+    getSnapshot(): IEventEmitterMetricsSnapshot;
+}
+
+/**
+ * Type definitions for EventEmitterPlugin.
+ *
+ * Extracted from event-emitter-plugin.ts to keep each file under 300 lines.
+ */
+
+/** Enhanced event data for hierarchical execution tracking */
+interface IEventEmitterHierarchicalEventData extends IEventEmitterEventData {
+    parentExecutionId?: string;
+    rootExecutionId?: string;
+    executionLevel: number;
+    executionPath: string[];
+    realTimeData?: {
+        startTime: Date;
+        actualDuration?: number;
+        actualParameters?: TToolParameters;
+        actualResult?: IToolResult;
+    };
+}
+
+/** Event emitter configuration */
+interface IEventEmitterPluginOptions extends IPluginOptions {
+    events?: TEventName[];
+    maxListeners?: number;
+    async?: boolean;
+    catchErrors?: boolean;
+    filters?: Record<TEventName, (event: IEventEmitterEventData) => boolean>;
+    buffer?: {
+        enabled: boolean;
+        maxSize: number;
+        flushInterval: number;
+    };
+    metrics?: IEventEmitterMetrics;
+}
+/** Event emitter plugin statistics */
+interface IEventEmitterPluginStats extends IPluginStats {
+    eventTypes: TEventName[];
+    listenerCounts: Partial<Record<TEventName, number>>;
+    totalListeners: number;
+    bufferedEvents: number;
+    totalEmitted: number;
+    totalErrors: number;
+}
+
+/**
+ * Provides pub/sub event coordination during the agent execution lifecycle.
+ * @extends AbstractPlugin
+ * @see IEventEmitterPluginOptions
+ * @see EVENT_EMITTER_EVENTS
+ */
+declare class EventEmitterPlugin extends AbstractPlugin<IEventEmitterPluginOptions, IEventEmitterPluginStats> {
+    name: string;
+    version: string;
+    private pluginOptions;
+    private logger;
+    private handlers;
+    private eventBuffer;
+    private nextHandlerId;
+    private bufferTimer?;
+    private metrics;
+    constructor(options?: IEventEmitterPluginOptions);
+    beforeExecution(context: IPluginExecutionContext): Promise<void>;
+    afterExecution(context: IPluginExecutionContext, result: IPluginExecutionResult): Promise<void>;
+    beforeConversation(context: IPluginExecutionContext): Promise<void>;
+    afterConversation(context: IPluginExecutionContext, result: IPluginExecutionResult): Promise<void>;
+    beforeToolExecution(context: IPluginExecutionContext, toolData: IToolExecutionContext): Promise<void>;
+    afterToolExecution(context: IPluginExecutionContext, toolResults: IPluginExecutionResult): Promise<void>;
+    onError(error: Error, context?: IPluginErrorContext): Promise<void>;
+    on(eventType: TEventName, listener: TEventEmitterListener, options?: {
+        once?: boolean;
+        filter?: (event: IEventEmitterEventData) => boolean;
+    }): string;
+    once(eventType: TEventName, listener: TEventEmitterListener, filter?: (event: IEventEmitterEventData) => boolean): string;
+    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[]>;
+
+/**
+ * Core AI agent integrating multiple AI providers, tools, and plugins
+ * into a unified conversational interface.
+ * @public
+ */
+declare class Robota extends AbstractAgent<IAgentConfig, IRunOptions, TUniversalMessage> implements IAgent<IAgentConfig, IRunOptions, TUniversalMessage> {
+    readonly name: string;
+    readonly version: string;
+    private aiProviders;
+    private tools;
+    private agentFactory;
+    private conversationHistory;
+    private moduleRegistry;
+    private eventEmitter;
+    private executionService;
+    private eventService;
+    private agentEventService;
+    protected config: IAgentConfig;
+    private conversationId;
+    private logger;
+    private initializationPromise?;
+    private isFullyInitialized;
+    private startTime;
+    private configVersion;
+    private configUpdatedAt;
+    private moduleManager;
+    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[];
+    clearHistory(): 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;
+    };
+    registerTool(tool: AbstractTool): void;
+    unregisterTool(toolName: string): void;
+    getConfig(): IAgentConfig;
+    addPlugin(plugin: IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks): void;
+    removePlugin(pluginName: string): boolean;
+    getPlugin(pluginName: string): (IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks) | undefined;
+    getPlugins(): Array<IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks>;
+    getPluginNames(): string[];
+    registerModule(module: IModule, options?: {
+        autoInitialize?: boolean;
+        validateDependencies?: boolean;
+    }): Promise<void>;
+    unregisterModule(moduleName: string): Promise<boolean>;
+    getModule(moduleName: string): IModule | undefined;
+    getModulesByType(moduleType: string): IModule[];
+    getModules(): IModule[];
+    getModuleNames(): string[];
+    hasModule(moduleName: string): boolean;
+    executeModule(moduleName: string, context: {
+        executionId?: string;
+        sessionId?: string;
+        userId?: string;
+        metadata?: Record<string, string | number | boolean | Date>;
+    }): Promise<{
+        success: boolean;
+        data?: IModuleResultData;
+        error?: Error;
+        duration?: number;
+    }>;
+    getModuleStats(moduleName: string): {
+        totalExecutions: number;
+        successfulExecutions: number;
+        failedExecutions: number;
+        averageExecutionTime: number;
+        lastExecutionTime?: Date;
+    } | undefined;
+    getStats(): {
+        name: string;
+        version: string;
+        conversationId: string;
+        providers: string[];
+        currentProvider: string | null;
+        tools: string[];
+        plugins: string[];
+        modules: string[];
+        historyLength: number;
+        historyStats: TAgentStatsMetadata;
+        uptime: number;
+    };
+    destroy(): Promise<void>;
+    protected initialize(): Promise<void>;
+    private ensureFullyInitialized;
+    private doAsyncInit;
+    private emitAgentEvent;
+    private buildOwnerPath;
+}
+
+/**
+ * Template application result
+ */
+interface ITemplateApplicationResult {
+    /** Applied configuration */
+    config: IAgentConfig;
+    /** Template that was applied */
+    template: IAgentTemplate;
+    /** Any warnings during application */
+    warnings: string[];
+    /** Whether config was modified during application */
+    modified: boolean;
+}
+/**
+ * Agent Templates implementation
+ * Manages agent templates for AgentFactory
+ * Instance-based for isolated template management
+ */
+declare class AgentTemplates {
+    private templates;
+    private logger;
+    constructor();
+    /**
+     * Register a template
+     */
+    registerTemplate(template: IAgentTemplate): void;
+    /**
+     * Unregister a template
+     */
+    unregisterTemplate(templateId: string): boolean;
+    /**
+     * Get all templates
+     */
+    getTemplates(): IAgentTemplate[];
+    /**
+     * Get template by ID
+     */
+    getTemplate(templateId: string): IAgentTemplate | undefined;
+    /**
+     * Find templates by criteria
+     */
+    findTemplates(criteria: {
+        category?: string;
+        tags?: string[];
+        provider?: string;
+        model?: string;
+    }): IAgentTemplate[];
+    /**
+     * Apply template to configuration
+     */
+    applyTemplate(template: IAgentTemplate, overrides?: Partial<IAgentConfig>): ITemplateApplicationResult;
+    /**
+     * Check if template exists
+     */
+    hasTemplate(templateId: string): boolean;
+    /**
+     * Get template count
+     */
+    getTemplateCount(): number;
+    /**
+     * Clear all templates
+     */
+    clearAll(): void;
+    /**
+     * Get template statistics
+     */
+    getStats(): {
+        totalTemplates: number;
+        categories: string[];
+        tags: string[];
+        providers: string[];
+        models: string[];
+    };
+}
+
+/**
+ * Configuration options for AgentFactory
+ */
+interface IAgentFactoryOptions {
+    /** Default model to use if not specified in config */
+    defaultModel?: string;
+    /** Default provider to use if not specified in config */
+    defaultProvider?: string;
+    /** Maximum number of concurrent agents */
+    maxConcurrentAgents?: number;
+    /** Default system message for agents */
+    defaultSystemMessage?: string;
+    /** Enable strict configuration validation */
+    strictValidation?: boolean;
+}
+/**
+ * Agent creation statistics
+ */
+interface IAgentCreationStats {
+    /** Total number of agents created */
+    totalCreated: number;
+    /** Number of currently active agents */
+    activeCount: number;
+    /** Number of agents created from templates */
+    fromTemplates: number;
+    /** Number of custom configured agents */
+    customConfigured: number;
+    /** Template vs custom creation ratio (fromTemplates / totalCreated) */
+    templateUsageRatio: number;
+}
+/**
+ * Agent lifecycle events
+ */
+interface IAgentLifecycleEvents {
+    /** Called before agent creation */
+    beforeCreate?: (config: IAgentConfig) => Promise<void> | void;
+    /** Called after successful agent creation */
+    afterCreate?: (agent: IAgent<IAgentConfig>, config: IAgentConfig) => Promise<void> | void;
+    /** Called when agent creation fails */
+    onCreateError?: (error: Error, config: IAgentConfig) => Promise<void> | void;
+    /** 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
+ */
+declare class AgentFactory {
+    private agentTemplates;
+    private initialized;
+    private logger;
+    private options;
+    private activeAgents;
+    private creationStats;
+    private lifecycleEvents;
+    constructor(options?: IAgentFactoryOptions, lifecycleEvents?: IAgentLifecycleEvents);
+    /**
+     * Initialize the factory
+     */
+    initialize(): Promise<void>;
+    /**
+     * Create a new agent instance
+     */
+    createAgent(AgentClass: new (config: IAgentConfig) => IAgent<IAgentConfig>, config: Partial<IAgentConfig>, fromTemplate?: boolean): Promise<IAgent<IAgentConfig>>;
+    /**
+     * Create agent from template
+     */
+    createFromTemplate(AgentClass: new (config: IAgentConfig) => IAgent<IAgentConfig>, templateId: string, overrides?: Partial<IAgentConfig>): Promise<IAgent<IAgentConfig>>;
+    /**
+     * Register a template
+     */
+    registerTemplate(template: IAgentTemplate): void;
+    /**
+     * Unregister a template
+     */
+    unregisterTemplate(templateId: string): boolean;
+    /**
+     * Get all templates
+     */
+    getTemplates(): IAgentTemplate[];
+    /**
+     * Get template by ID
+     */
+    getTemplate(templateId: string): IAgentTemplate | undefined;
+    /**
+     * Find templates by criteria
+     */
+    findTemplates(criteria: {
+        category?: string;
+        tags?: string[];
+        provider?: string;
+        model?: string;
+    }): IAgentTemplate[];
+    /**
+     * Apply template to configuration
+     */
+    applyTemplate(template: IAgentTemplate, overrides?: Partial<IAgentConfig>): ITemplateApplicationResult;
+    /**
+     * Destroy an agent
+     */
+    destroyAgent(agentId: string): Promise<boolean>;
+    /**
+     * Get creation statistics
+     */
+    getCreationStats(): IAgentCreationStats;
+    /**
+     * Get all active agents
+     */
+    getActiveAgents(): Map<string, IAgent<IAgentConfig>>;
+    /**
+     * Validate agent configuration
+     */
+    validateConfiguration(config: Partial<IAgentConfig>): {
+        isValid: boolean;
+        errors: string[];
+    };
+    /**
+     * Apply default configuration values
+     */
+    private applyDefaults;
+    /**
+     * Generate unique agent ID
+     */
+    private generateAgentId;
+    /**
+     * Update creation statistics
+     */
+    private updateCreationStats;
+}
+
+/**
+ * Conversation session implementations.
+ *
+ * Extracted from conversation-history-manager.ts.
+ */
+
+/** API message format for provider consumption */
+interface IProviderApiMessage {
+    role: string;
+    content: string | null;
+    tool_calls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    tool_call_id?: string;
+}
+/**
+ * Conversation session with duplicate prevention and API format conversion.
+ * @public
+ */
+declare class ConversationSession implements IConversationHistory {
+    private history;
+    private toolCallIds;
+    constructor(maxMessages?: number);
+    addMessage(message: TUniversalMessage): void;
+    addUserMessage(content: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    addAssistantMessage(content: string | null, toolCalls?: IToolCall[], metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    addSystemMessage(content: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    addToolMessage(content: string, toolCallId: string, toolName?: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    addToolMessageWithId(content: string, toolCallId: string, toolName: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    getMessages(): TUniversalMessage[];
+    getMessagesByRole(role: TUniversalMessageRole): TUniversalMessage[];
+    getRecentMessages(count: number): TUniversalMessage[];
+    getMessageCount(): number;
+    getMessagesForAPI(): IProviderApiMessage[];
+    clear(): void;
+}
+
+/** Interface for managing conversation history. @public */
+interface IConversationHistory {
+    addMessage(message: TUniversalMessage): void;
+    addUserMessage(content: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    addAssistantMessage(content: string | null, toolCalls?: IToolCall[], metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    addSystemMessage(content: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    addToolMessageWithId(content: string, toolCallId: string, toolName: string, metadata?: TUniversalMessageMetadata, parts?: TUniversalMessagePart[]): void;
+    getMessages(): TUniversalMessage[];
+    getMessagesByRole(role: TUniversalMessageRole): TUniversalMessage[];
+    getRecentMessages(count: number): TUniversalMessage[];
+    clear(): void;
+    getMessageCount(): number;
+}
+/** Configuration options for ConversationHistory manager */
+interface IConversationHistoryOptions {
+    maxMessagesPerConversation?: number;
+    maxConversations?: number;
+}
+/** Multi-session conversation history manager. @public */
+declare class ConversationHistory {
+    private conversations;
+    private logger;
+    private readonly maxMessagesPerConversation;
+    private readonly maxConversations;
+    constructor(options?: IConversationHistoryOptions);
+    getConversationSession(conversationId: string): ConversationSession;
+    hasConversation(conversationId: string): boolean;
+    removeConversation(conversationId: string): boolean;
+    clearAll(): void;
+    getStats(): {
+        totalConversations: number;
+        conversationIds: string[];
+        totalMessages: number;
+    };
+}
+
+declare class EventHistoryModule implements IEventHistoryModule {
+    private readonly store;
+    private readonly listener;
+    private sequenceId;
+    constructor(store: IEventHistoryModule, eventService: IEventService);
+    append(record: IEventHistoryRecord): void;
+    read(fromSequenceId: number, toSequenceId?: number): IEventHistoryRecord[];
+    readStream(fromSequenceId: number, toSequenceId?: number): AsyncIterable<IEventHistoryRecord>;
+    getSnapshot(): IEventHistorySnapshot | undefined;
+    detach(eventService: IEventService): void;
+    private nextSequenceId;
+}
+
+/**
+ * ExecutionService owned events.
+ * Local event names only (no dots). Full names are composed at emit time.
+ */
+declare const EXECUTION_EVENTS: {
+    readonly START: "start";
+    readonly COMPLETE: "complete";
+    readonly ERROR: "error";
+    readonly ASSISTANT_MESSAGE_START: "assistant_message_start";
+    readonly ASSISTANT_MESSAGE_COMPLETE: "assistant_message_complete";
+    readonly USER_MESSAGE: "user_message";
+    readonly TOOL_RESULTS_TO_LLM: "tool_results_to_llm";
+    readonly TOOL_RESULTS_READY: "tool_results_ready";
+};
+declare const EXECUTION_EVENT_PREFIX: "execution";
+
+/**
+ * ToolExecutionService owned events
+ * Local event names only (no dots). Full names are composed at emit time.
+ */
+declare const TOOL_EVENTS: {
+    readonly CALL_START: "call_start";
+    readonly CALL_COMPLETE: "call_complete";
+    readonly CALL_ERROR: "call_error";
+    readonly CALL_RESPONSE_READY: "call_response_ready";
+};
+declare const TOOL_EVENT_PREFIX: "tool";
+
+/**
+ * Agent event constants
+ *
+ * Events emitted by Agent instances themselves.
+ * Event names are local (no dots) and must be used via constants (no string literals).
+ */
+declare const AGENT_EVENTS: {
+    /** Agent instance has been created and initialized */
+    readonly CREATED: "created";
+    /** Agent execution lifecycle - start */
+    readonly EXECUTION_START: "execution_start";
+    /** Agent execution lifecycle - complete */
+    readonly EXECUTION_COMPLETE: "execution_complete";
+    /** Agent execution lifecycle - error */
+    readonly EXECUTION_ERROR: "execution_error";
+    /** Agent aggregation process completed */
+    readonly AGGREGATION_COMPLETE: "aggregation_complete";
+    /** Agent configuration (e.g., tools) has been updated by the agent */
+    readonly CONFIG_UPDATED: "config_updated";
+};
+declare const AGENT_EVENT_PREFIX: "agent";
+
+/**
+ * Workflow Converter Interface
+ *
+ * Defines the contract for all workflow converters in the Robota SDK.
+ * Follows Interface Segregation Principle by providing minimal, focused interface.
+ *
+ * @template TInput - Input workflow data type
+ * @template TOutput - Output workflow data type
+ */
+
+/**
+ * Workflow configuration - uses base type for cross-converter compatibility
+ * Step 1: ❌ Can't assign number/boolean to config value type directly (index signature conflict)
+ * Step 2: ✅ TConfigValue already includes primitive types (number, boolean)
+ * Step 3: ✅ Fix index signature to allow optional properties
+ * Step 4: ✅ Use proper intersection type for compatibility
+ */
+interface IWorkflowConfig {
+    timeout?: number;
+    retries?: number;
+    validateInput?: boolean;
+    validateOutput?: boolean;
+    [key: string]: TConfigValue | undefined;
+}
+/**
+ * Workflow metadata - uses base type for cross-converter compatibility
+ * Step 1: ❌ Can't assign Date/number/string to metadata value type directly (index signature conflict)
+ * Step 2: ✅ TMetadataValue already includes Date, primitive types
+ * Step 3: ✅ Fix index signature to allow optional properties
+ * Step 4: ✅ Use proper intersection type for compatibility
+ */
+interface IWorkflowMetadata {
+    convertedAt?: Date;
+    processingTime?: number;
+    executionId?: string;
+    [key: string]: TMetadataValue | undefined;
+}
+/**
+ * Base workflow data constraint with flexible typing
+ * All workflow data must extend this interface for type safety
+ */
+interface IWorkflowData {
+    readonly __workflowType?: string;
+    [key: string]: TUniversalValue | undefined;
+}
+/**
+ * Conversion options for workflow transformations
+ * Step 1: ❌ Can't assign IWorkflowConversionOptions to metadata value type (missing index signature)
+ * Step 2: ✅ Add index signature to make it compatible with MetadataValue
+ * Step 3: ✅ Maintain type safety while allowing metadata storage
+ * Step 4: ✅ Use MetadataValue compatibility for dynamic properties
+ */
+interface IWorkflowConversionOptions {
+    /** Include debug information in output */
+    includeDebug?: boolean;
+    /** Validate input before conversion */
+    validateInput?: boolean;
+    /** Validate output after conversion */
+    validateOutput?: boolean;
+    /** Custom logger for conversion process */
+    logger?: ILogger;
+    /** Additional metadata to include */
+    metadata?: IWorkflowMetadata;
+    /** Platform-specific options */
+    platformOptions?: IWorkflowConfig;
+    /** Additional dynamic options compatible with TUniversalValue */
+    [key: string]: TUniversalValue | ILogger | IWorkflowMetadata | IWorkflowConfig | undefined;
+}
+/**
+ * Conversion result with metadata and validation info
+ */
+interface IWorkflowConversionResult<TOutput> {
+    /** Converted workflow data */
+    data: TOutput;
+    /** Conversion success status */
+    success: boolean;
+    /** Validation errors (if any) */
+    errors: string[];
+    /** Validation warnings (if any) */
+    warnings: string[];
+    /** Conversion metadata */
+    metadata: IWorkflowConversionResultMetadata;
+}
+/**
+ * Workflow conversion metadata.
+ *
+ * IMPORTANT:
+ * - Do NOT intersect this object with `TMetadata`.
+ * - `TMetadata` has an index signature with a restricted value axis (`TMetadataValue`),
+ *   which would force every property on this object to be assignable to `TMetadataValue`.
+ * - Keep structured fields here, and store additional key/value pairs under `extensions`.
+ */
+interface IWorkflowConversionResultMetadata {
+    /** Conversion timestamp */
+    convertedAt: Date;
+    /** Processing time in milliseconds */
+    processingTime: number;
+    /** Input data statistics */
+    inputStats: {
+        nodeCount: number;
+        edgeCount: number;
+    };
+    /** Output data statistics */
+    outputStats: {
+        nodeCount: number;
+        edgeCount: number;
+    };
+    /** Converter name */
+    converter: string;
+    /** Converter version */
+    version: string;
+    /** Conversion options (optional, typically gated by includeDebug) */
+    options?: IWorkflowConversionOptions;
+    /**
+     * Additional key/value metadata (SSOT axis).
+     * Use this for dynamic metadata, not top-level ad-hoc fields.
+     */
+    extensions?: TMetadata;
+}
+/**
+ * Workflow Converter Interface
+ *
+ * Core interface for converting between different workflow representations.
+ * All workflow converters must implement this interface.
+ *
+ * @template TInput - Input workflow data type
+ * @template TOutput - Output workflow data type
+ */
+interface IWorkflowConverter<TInput extends IWorkflowData, TOutput extends IWorkflowData> {
+    /** Converter name for identification */
+    readonly name: string;
+    /** Converter version */
+    readonly version: string;
+    /** Source format that this converter accepts */
+    readonly sourceFormat: string;
+    /** Target format that this converter produces */
+    readonly targetFormat: string;
+    /**
+     * Convert workflow data from input format to output format
+     *
+     * @param input - Input workflow data
+     * @param options - Conversion options
+     * @returns Promise resolving to conversion result
+     */
+    convert(input: TInput, options?: IWorkflowConversionOptions): Promise<IWorkflowConversionResult<TOutput>>;
+    /**
+     * Validate input data before conversion
+     *
+     * @param input - Input workflow data
+     * @returns Promise resolving to validation result
+     */
+    validateInput(input: TInput): Promise<{
+        isValid: boolean;
+        errors: string[];
+        warnings: string[];
+    }>;
+    /**
+     * Validate output data after conversion
+     *
+     * @param output - Output workflow data
+     * @returns Promise resolving to validation result
+     */
+    validateOutput(output: TOutput): Promise<{
+        isValid: boolean;
+        errors: string[];
+        warnings: string[];
+    }>;
+    /**
+     * Check if this converter supports the given input format
+     *
+     * @param input - Input data to check
+     * @returns True if converter can handle this input
+     */
+    canConvert(input: IWorkflowData): input is TInput;
+    /**
+     * Get conversion statistics and metrics
+     *
+     * @returns Converter performance metrics
+     */
+    getStats(): {
+        totalConversions: number;
+        successfulConversions: number;
+        failedConversions: number;
+        averageProcessingTime: number;
+        lastConversionAt?: Date;
+    };
+    /**
+     * Reset converter statistics
+     */
+    resetStats(): void;
+}
+
+/**
+ * Workflow Validator Interface
+ *
+ * Defines the contract for workflow validation systems in the Robota SDK.
+ * Follows Single Responsibility Principle by focusing only on validation logic.
+ */
+
+/**
+ * Validation severity levels
+ */
+declare enum ValidationSeverity {
+    ERROR = "error",
+    WARNING = "warning",
+    INFO = "info"
+}
+/**
+ * Individual validation issue
+ */
+interface IValidationIssue {
+    /** Unique identifier for this issue */
+    id: string;
+    /** Issue severity level */
+    severity: ValidationSeverity;
+    /** Human-readable message */
+    message: string;
+    /** Technical details or suggestion */
+    details?: string;
+    /** Location where issue was found */
+    location?: {
+        nodeId?: string;
+        edgeId?: string;
+        field?: string;
+        line?: number;
+        column?: number;
+    };
+    /** Rule that triggered this issue */
+    rule: string;
+    /** Suggested fix (if available) */
+    suggestedFix?: {
+        description: string;
+        action: 'modify' | 'remove' | 'add';
+        target?: IWorkflowConfig;
+    };
+    /** Timestamp when issue was detected */
+    detectedAt: Date;
+}
+/**
+ * Validation options
+ */
+interface IValidationOptions {
+    /** Validation strictness level */
+    strict?: boolean;
+    /** Skip specific validation rules */
+    skipRules?: string[];
+    /** Include only specific validation rules */
+    includeRules?: string[];
+    /** Maximum number of errors to collect */
+    maxErrors?: number;
+    /** Include warnings in results */
+    includeWarnings?: boolean;
+    /** Include info messages in results */
+    includeInfo?: boolean;
+    /** Custom logger for validation process */
+    logger?: ILogger;
+    /** Additional validation context */
+    context?: IWorkflowMetadata;
+    /** Enable auto-recovery suggestions */
+    enableAutoRecovery?: boolean;
+}
+/**
+ * Validation result
+ */
+interface IValidationResult {
+    /** Overall validation success status */
+    isValid: boolean;
+    /** All validation issues found */
+    issues: IValidationIssue[];
+    /** Summary by severity */
+    summary: {
+        errorCount: number;
+        warningCount: number;
+        infoCount: number;
+        totalIssues: number;
+    };
+    /** Validation metadata */
+    metadata: {
+        /** Validation timestamp */
+        validatedAt: Date;
+        /** Processing time in milliseconds */
+        processingTime: number;
+        /** Validator used */
+        validator: string;
+        /** Validation rules applied */
+        rulesApplied: string[];
+        /** Data statistics */
+        dataStats: Record<string, string | number | boolean>;
+        /** Version */
+        version?: string;
+        /** Options */
+        options?: string | number | boolean | string[] | Date;
+        /** Additional metrics */
+        [key: string]: string | number | boolean | Date | string[] | Record<string, string | number | boolean> | undefined;
+    };
+    /** Auto-recovery suggestions (if enabled) */
+    recoveryOptions?: Array<{
+        description: string;
+        confidence: number;
+        action: () => Promise<IWorkflowConfig>;
+    }>;
+}
+/**
+ * Workflow Validator Interface
+ *
+ * Core interface for validating workflow data structures.
+ * All workflow validators must implement this interface.
+ *
+ * @template TWorkflowData - Type of workflow data to validate
+ */
+interface IWorkflowValidator<TWorkflowData extends IWorkflowData> {
+    /** Validator name for identification */
+    readonly name: string;
+    /** Validator version */
+    readonly version: string;
+    /** Data format that this validator handles */
+    readonly dataFormat: string;
+    /** Available validation rules */
+    readonly availableRules: string[];
+    /**
+     * Validate workflow data
+     *
+     * @param data - Workflow data to validate
+     * @param options - Validation options
+     * @returns Promise resolving to validation result
+     */
+    validate(data: TWorkflowData, options?: IValidationOptions): Promise<IValidationResult>;
+    /**
+     * Validate specific aspect of workflow data
+     *
+     * @param data - Workflow data to validate
+     * @param rule - Specific rule to apply
+     * @param options - Validation options
+     * @returns Promise resolving to validation result for this rule
+     */
+    validateRule(data: TWorkflowData, rule: string, options?: IValidationOptions): Promise<IValidationResult>;
+    /**
+     * Check if validator can handle the given data format
+     *
+     * @param data - Data to check
+     * @returns True if validator can handle this data
+     */
+    canValidate(data: IWorkflowData): data is TWorkflowData;
+    /**
+     * Get available validation rules with descriptions
+     *
+     * @returns Map of rule names to descriptions
+     */
+    getRuleDescriptions(): Map<string, {
+        description: string;
+        severity: ValidationSeverity;
+        category: string;
+        enabled: boolean;
+    }>;
+    /**
+     * Enable or disable specific validation rules
+     *
+     * @param rules - Map of rule names to enabled status
+     */
+    configureRules(rules: Map<string, boolean>): void;
+    /**
+     * Perform automatic recovery for validation issues
+     *
+     * @param data - Original workflow data
+     * @param issues - Validation issues to recover from
+     * @returns Promise resolving to recovered data and recovery result
+     */
+    autoRecover(data: TWorkflowData, issues: IValidationIssue[]): Promise<{
+        recoveredData: TWorkflowData;
+        recoveryResult: {
+            success: boolean;
+            issuesFixed: IValidationIssue[];
+            remainingIssues: IValidationIssue[];
+            appliedFixes: string[];
+        };
+    }>;
+    /**
+     * Get validator statistics and metrics
+     *
+     * @returns Validator performance metrics
+     */
+    getStats(): {
+        totalValidations: number;
+        successfulValidations: number;
+        failedValidations: number;
+        averageProcessingTime: number;
+        averageIssueCount: number;
+        mostCommonIssues: Array<{
+            rule: string;
+            count: number;
+            severity: ValidationSeverity;
+        }>;
+        lastValidationAt?: Date;
+    };
+    /**
+     * Reset validator statistics
+     */
+    resetStats(): void;
+}
+
+/**
+ * Configuration for execution proxy
+ */
+interface IExecutionProxyConfig {
+    eventService: IEventService;
+    sourceType: 'agent' | 'team' | 'tool';
+    sourceId: string;
+    enabledEvents?: {
+        execution?: boolean;
+        toolCall?: boolean;
+        task?: boolean;
+    };
+}
+/**
+ * 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
+ */
+interface IMethodConfig {
+    startEvent?: string;
+    completeEvent?: string;
+    errorEvent?: string;
+    extractMetadata?: TMetadataExtractor;
+    extractResult?: (result: TUniversalValue) => Record<string, TUniversalValue>;
+}
+/**
+ * ExecutionProxy - Automatic event emission using Proxy pattern
+ *
+ * This class wraps target objects and automatically emits events
+ * around method execution without modifying business logic.
+ *
+ * Benefits:
+ * - Zero business logic pollution
+ * - Automatic event emission
+ * - Configurable per method
+ * - AOP (Aspect-Oriented Programming) pattern
+ */
+declare class ExecutionProxy<T extends object = object> {
+    private config;
+    private methodConfigs;
+    constructor(config: IExecutionProxyConfig);
+    /**
+     * Configure specific methods for event emission
+     */
+    configureMethod(methodName: string, config: IMethodConfig): this;
+    /**
+     * Configure multiple methods with standard patterns
+     */
+    configureStandardMethods(): this;
+    /**
+     * Create a proxy wrapper around the target object
+     */
+    wrap(target: T): T;
+    /**
+     * Emit event with standard ServiceEventData format
+     */
+    private emitEvent;
+    /**
+     * Generate unique execution ID
+     */
+    private generateExecutionId;
+}
+/**
+ * Factory function to create execution proxy with standard configuration
+ */
+declare function createExecutionProxy<T extends object>(target: T, config: IExecutionProxyConfig): T;
+/**
+ * Decorator function for automatic event emission
+ * Usage: @withEventEmission(eventService, 'agent', 'agent-id')
+ */
+declare function withEventEmission(eventService: IEventService, sourceType: 'agent' | 'team' | 'tool', sourceId: string): <T extends object>(target: T) => T;
+
+/**
+ * Permission system types — Claude Code compatible permission model.
+ */
+/**
+ * Permission modes (Claude Code compatible)
+ * - plan: read-only tools only
+ * - default: reads auto, writes/bash need approval
+ * - acceptEdits: reads + writes auto, bash needs approval
+ * - bypassPermissions: all tools auto
+ */
+type TPermissionMode = 'plan' | 'default' | 'acceptEdits' | 'bypassPermissions';
+/**
+ * Friendly trust level aliases
+ * - safe   → plan
+ * - moderate → default
+ * - full   → acceptEdits
+ */
+type TTrustLevel = 'safe' | 'moderate' | 'full';
+declare const TRUST_TO_MODE: Record<TTrustLevel, TPermissionMode>;
+/**
+ * Outcome of a permission evaluation
+ * - auto: proceed without prompting
+ * - approve: prompt user for approval
+ * - deny: block the action
+ */
+type TPermissionDecision = 'auto' | 'approve' | 'deny';
+
+/**
+ * Permission gate — evaluates whether a tool call is auto-approved, needs user approval, or denied.
+ *
+ * Three-step deterministic policy (in order of precedence):
+ * 1. Deny list match → deny
+ * 2. Allow list match → auto
+ * 3. Mode policy lookup
+ *
+ * Pattern syntax (same as Claude Code):
+ * - `Bash(pnpm *)` — Bash tool whose command starts with "pnpm "
+ * - `Read(/src/**)` — Read tool whose filePath is under /src/
+ * - `Write(*)`      — Write tool with any argument
+ * - `ToolName`      — match any invocation of that tool
+ */
+
+/**
+ * Tool arguments passed from the LLM invocation.
+ * The values relevant to permission matching are strings.
+ */
+type TToolArgs = Record<string, string | number | boolean | object>;
+/**
+ * Permission list entries (allow / deny).
+ * Each entry is a pattern string such as "Bash(pnpm *)" or "Read(/src/**)".
+ */
+interface IPermissionLists {
+    allow?: string[];
+    deny?: string[];
+}
+/**
+ * Evaluate whether a tool invocation should be auto-approved, require user approval, or be denied.
+ *
+ * @param toolName   Name of the tool being invoked (e.g. "Bash", "Write")
+ * @param toolArgs   Arguments provided by the LLM
+ * @param mode       Active permission mode
+ * @param permissions Optional allow/deny lists from config
+ */
+declare function evaluatePermission(toolName: string, toolArgs: TToolArgs, mode: TPermissionMode, permissions?: IPermissionLists): TPermissionDecision;
+
+/**
+ * Permission mode definitions for Robota CLI
+ *
+ * Matches Claude Code-compatible permission modes:
+ * - plan: read-only tools only (Read, Glob, Grep auto; Write, Edit, Bash denied)
+ * - default: safe reads auto, writes and bash need approval
+ * - acceptEdits: reads + writes auto, bash needs approval
+ * - bypassPermissions: all tools auto
+ */
+
+/**
+ * Tool names known to the permission system
+ */
+type TKnownToolName = 'Bash' | 'Read' | 'Write' | 'Edit' | 'Glob' | 'Grep';
+/**
+ * Permission mode → tool policy matrix
+ * Maps each mode to a decision for each known tool.
+ */
+declare const MODE_POLICY: Record<TPermissionMode, Record<TKnownToolName, TPermissionDecision>>;
+/**
+ * Fallback decision when a tool name is not in the policy matrix.
+ * Unknown tools are treated as requiring approval (fail-safe).
+ */
+declare const UNKNOWN_TOOL_FALLBACK: Record<TPermissionMode, TPermissionDecision>;
+
+/**
+ * Context window tracking types.
+ *
+ * These types are used by agent-sessions (and downstream packages) to
+ * track token usage and context window state across conversation turns.
+ */
+/** Token usage from a single API call (Anthropic-style granularity) */
+interface IContextTokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+}
+/** Context window state snapshot */
+interface IContextWindowState {
+    /** Max tokens for the current model */
+    maxTokens: number;
+    /** Current estimated token usage (input + cache, excludes output) */
+    usedTokens: number;
+    /** Usage percentage (0-100) */
+    usedPercentage: number;
+    /** Remaining percentage (0-100) */
+    remainingPercentage: number;
+}
+
+/**
+ * Hook system types — Claude Code compatible event/hook model.
+ */
+/** Hook lifecycle events */
+type THookEvent = 'PreToolUse' | 'PostToolUse' | 'SessionStart' | 'Stop' | 'PreCompact' | 'PostCompact';
+/** A single hook definition */
+interface IHookDefinition {
+    /** Shell command to execute */
+    type: 'command';
+    command: string;
+}
+/** A hook group — matcher + array of hook definitions */
+interface IHookGroup {
+    /** Regex pattern to match tool name (empty string = match all) */
+    matcher: string;
+    hooks: IHookDefinition[];
+}
+/** Complete hooks configuration: event → array of hook groups */
+type THooksConfig = Partial<Record<THookEvent, IHookGroup[]>>;
+/** Input passed to hook commands via stdin */
+interface IHookInput {
+    session_id: string;
+    cwd: string;
+    hook_event_name: THookEvent;
+    tool_name?: string;
+    tool_input?: Record<string, string | number | boolean | object>;
+    tool_output?: string;
+    /** Compaction trigger source (PreCompact/PostCompact only) */
+    trigger?: 'auto' | 'manual';
+    /** Compaction summary text (PostCompact only) */
+    compact_summary?: string;
+}
+/** Hook execution result */
+interface IHookResult {
+    /** 0 = allow/proceed, 2 = block/deny, other = proceed with warning */
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+
+/**
+ * Hook runner — executes shell command hooks for lifecycle events.
+ *
+ * Hooks receive JSON input on stdin and communicate results via exit codes:
+ * - 0: allow/proceed
+ * - 2: block/deny (stderr contains reason)
+ * - other: proceed (logged as warning)
+ */
+
+/**
+ * Run all hooks for a given event.
+ *
+ * For PreToolUse: if any hook returns exit code 2, the tool call is blocked.
+ * Returns { blocked: true, reason: string } if blocked, { blocked: false } otherwise.
+ */
+declare function runHooks(config: THooksConfig | undefined, event: THookEvent, input: IHookInput): Promise<{
+    blocked: boolean;
+    reason?: string;
+}>;
+
+export { AGENT_EVENTS, AGENT_EVENT_PREFIX, AbstractAIProvider, AbstractAgent, AbstractExecutor, AbstractManager, AbstractPlugin, AbstractTool, AgentFactory, AgentTemplates, AuthenticationError, CacheIntegrityError, CircuitBreakerOpenError, ConfigurationError, ConversationHistory, ConversationSession, EVENT_EMITTER_EVENTS, EXECUTION_EVENTS, EXECUTION_EVENT_PREFIX, ErrorUtils, EventEmitterPlugin, EventHistoryModule, ExecutionProxy, type IAIProvider, type IAIProviderInstance, type IAIProviderManager, type IAbstractTool, type IAbstractToolOptions, type IAgent, type IAgentConfig, type IAgentCreationOptions, type IAgentCreationStats, type IAgentEventData, type IAgentFactory, type IAgentFactoryOptions, type IAgentLifecycleEvents, type IAgentTemplate, type IAssistantMessage, type IBaseEventData, type IBaseMessage, type ICacheEntry, type ICacheKey, type ICacheOptions, type ICacheStats, type ICacheStorage, type IChatExecutionRequest, type IChatOptions, type IConfigValidationResult, type IContextOptions, type IContextTokenUsage, type IContextWindowState, type IConversationContext, type IConversationResponse, type IConversationService, type IConversationServiceOptions, type IEventContext, type IEventEmitterEventData, type IEventEmitterHierarchicalEventData, type IEventEmitterMetrics, type IEventEmitterMetricsSnapshot, type IEventEmitterPlugin, type IEventEmitterPluginOptions, type IEventHistoryModule, type IEventHistoryRecord, type IEventHistorySnapshot, type IEventService, type IEventServiceOwnerBinding, type IExecutionEventData, type IExecutionService, type IExecutionServiceOptions, type IExecutor, type IExecutorAwareProviderConfig, type IFunctionTool, type IHookDefinition, type IHookGroup, type IHookInput, type IHookResult, type IImageComposeRequest, type IImageEditRequest, type IImageGenerationProvider, type IImageGenerationRequest, type IImageGenerationResult, type IInlineImageInputSource, type IInlineImageMessagePart, type ILocalExecutorConfig, type ILogger, type IMCPToolConfig, type IMediaOutputRef, type IOpenAPIToolConfig, type IOwnerPathSegment, type IParameterSchema, type IParameterValidationResult, type IPermissionLists, type IPlugin, type IPluginConfig, type IPluginContext, type IPluginContract, type IPluginData, type IPluginErrorContext, type IPluginExecutionContext, type IPluginExecutionResult, type IPluginHooks, type IPluginOptions, type IPluginStats, type IProgressReportingTool, type IProviderConfig, type IProviderMediaError, type IProviderOptions, type IProviderRequest, type IProviderSpecificOptions, type IRawProviderResponse, type IRemoteExecutorConfig, type IRunOptions, type ISimpleValidationResult, type IStreamExecutionRequest, type IStreamingChunk, type ISystemMessage, type ITemplateApplicationResult, type ITextMessagePart, type ITokenUsage, type ITool, type IToolCall, type IToolContract, type IToolEventData, type IToolExecutionContext, type IToolExecutionRequest, type IToolExecutionResult, type IToolExecutionService, type IToolExecutionStep, type IToolFactory, type IToolManager, type IToolMessage, type IToolRegistry, type IToolResult, type IToolSchema, type IToolWithEventService, type IUniversalObjectValue, type IUriImageInputSource, type IUriImageMessagePart, type IUserMessage, type IUtilLogEntry, type IValidationIssue, type IValidationOptions, type IValidationResult, type IVideoGenerationProvider, type IVideoGenerationRequest, type IVideoJobAccepted, type IVideoJobSnapshot, type IWorkflowConfig, type IWorkflowConversionOptions, type IWorkflowConversionResult, type IWorkflowConverter, type IWorkflowData, type IWorkflowMetadata, type IWorkflowValidator, InMemoryEventEmitterMetrics, LocalExecutor, MODE_POLICY, MessageConverter, ModelNotAvailableError, NetworkError, PluginCategory, PluginError, PluginPriority, ProviderError, RateLimitError, Robota, RobotaError, SilentLogger, StorageError, type TAgentCreationMetadata, type TComplexConfigValue, type TConfigData, type TConfigValue, type TContextData, type TConversationContextMetadata, type TErrorContextData, type TErrorExternalInput, type TEventEmitterListener, type TEventListener, type TEventName, type TExecutionEventName, type TExecutionMetadata, type THookEvent, type THooksConfig, type TImageInputSource, type TJSONSchemaEnum, type TJSONSchemaKind, type TKnownToolName, type TLoggerData, type TManagerToolParameters, type TMetadata, type TMetadataValue, TOOL_EVENTS, TOOL_EVENT_PREFIX, type TParameterDefaultValue, type TPermissionDecision, type TPermissionMode, type TPrimitiveValue, type TProviderConfigValue, type TProviderLoggingData, type TProviderMediaResult, type TProviderOptionValueBase, TRUST_TO_MODE, type TResponseMetadata, type TTextDeltaCallback, type TTimerId, type TToolArgs, type TToolExecutionFunction, type TToolExecutionParameters, type TToolExecutor, type TToolMetadata, type TToolParameters, type TToolProgressCallback, type TTrustLevel, type TUniversalArrayValue, type TUniversalMessage, type TUniversalMessageMetadata, type TUniversalMessagePart, type TUniversalMessageRole, type TUniversalValue, type TUtilLogLevel, ToolExecutionError, UNKNOWN_TOOL_FALLBACK, ValidationError, ValidationSeverity, Validator, createExecutionProxy, createLogger, evaluatePermission, getGlobalLogLevel, getToolEstimatedDuration, getToolExecutionSteps, isAssistantMessage, isImageGenerationProvider, isProgressReportingTool, isSystemMessage, isToolMessage, isUserMessage, isVideoGenerationProvider, logger, runHooks, setGlobalLogLevel, setToolProgressCallback, startPeriodicTask, stopPeriodicTask, validateAgentConfig, validateApiKey, validateModelName, validateProviderName, validateUserInput, withEventEmission };