@robota-sdk/agent-core 3.0.0-beta.63 → 3.0.0-beta.65

package/dist/node/index.d.cts

@@ -1,4675 +0,0 @@
-/**
- * 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[] | Record<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;
-    };
-}
-/** State of a message in conversation history */
-type TMessageState = 'complete' | 'interrupted';
-/**
- * Base message contract shared by all message variants.
- */
-interface IBaseMessage {
-    /** Unique message identifier */
-    id: string;
-    /** Message creation timestamp */
-    timestamp: Date;
-    /** Whether this message is complete or was interrupted */
-    state: TMessageState;
-    /** 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.
- * Used for AI provider communication. Extracted from IHistoryEntry[] via filtering.
- */
-type TUniversalMessage = IUserMessage | IAssistantMessage | ISystemMessage | IToolMessage;
-/**
- * Universal history entry — the base type for all records in conversation history.
- *
- * History is a universal timeline that records everything: AI chat messages,
- * system events, skill invocations, permission decisions, etc.
- * AI provider receives only chat entries (filtered and converted to TUniversalMessage).
- * TUI can render any range of entries.
- *
- * - append-only, read-only
- * - category + type for classification (free-form strings, no pre-defined enum)
- * - data holds type-specific structured content
- */
-interface IHistoryEntry<T = unknown> {
-    /** Unique entry identifier */
-    id: string;
-    /** Entry creation timestamp */
-    timestamp: Date;
-    /** Top-level classification: 'chat', 'event', etc. */
-    category: string;
-    /** Sub-classification within category. Free-form, not pre-defined. */
-    type: string;
-    /** Type-specific structured data */
-    data?: T;
-}
-/** Check if a history entry is a chat message (for AI provider filtering). */
-declare function isChatEntry(entry: IHistoryEntry): boolean;
-/**
- * Convert a chat history entry to TUniversalMessage for AI provider consumption.
- * Only call on entries where isChatEntry() returns true.
- */
-declare function chatEntryToMessage(entry: IHistoryEntry): TUniversalMessage;
-/**
- * Convert a TUniversalMessage to an IHistoryEntry for storage.
- */
-declare function messageToHistoryEntry(message: TUniversalMessage): IHistoryEntry;
-/**
- * Filter history entries and convert chat entries to TUniversalMessage[].
- * Used when passing conversation to AI provider.
- */
-declare function getMessagesForAPI(history: IHistoryEntry[]): TUniversalMessage[];
-/**
- * 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;
-}
-/**
- * Type utility functions for safe type checking and validation
- * @internal
- */
-declare const TypeUtils: {
-    isPrimitive: (value: TUniversalValue) => value is TPrimitiveValue;
-    isArray: (value: TUniversalValue) => value is TUniversalArrayValue;
-    isObject: (value: TUniversalValue) => value is IUniversalObjectValue;
-    isUniversalValue: (value: TUniversalValue) => value is TUniversalValue;
-};
-
-interface IProviderFunctionCallingCapability {
-    supported: boolean;
-    reason?: string;
-}
-interface IProviderNativeWebToolCapability {
-    supported: boolean;
-    enabled: boolean;
-    source?: string;
-    reason?: string;
-}
-interface IProviderNativeWebToolCapabilities {
-    webSearch: IProviderNativeWebToolCapability;
-    webFetch: IProviderNativeWebToolCapability;
-}
-interface IProviderCapabilities {
-    functionCalling: IProviderFunctionCallingCapability;
-    nativeWebTools: IProviderNativeWebToolCapabilities;
-}
-interface IProviderNativeWebToolRequest {
-    webSearch?: boolean;
-    webFetch?: boolean;
-}
-declare function createDefaultProviderCapabilities(functionCallingSupported: boolean): IProviderCapabilities;
-declare function getProviderCapabilities(provider: IAIProvider): IProviderCapabilities;
-declare function assertProviderNativeWebToolsAvailable(providerName: string, capabilities: IProviderCapabilities, request: IProviderNativeWebToolRequest | undefined): void;
-
-/**
- * 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[];
-        additionalProperties?: boolean | IParameterSchema;
-    };
-}
-/**
- * Parameter schema for tools
- */
-interface IParameterSchema {
-    type: TJSONSchemaKind;
-    description?: string;
-    enum?: TJSONSchemaEnum;
-    items?: IParameterSchema;
-    properties?: Record<string, IParameterSchema>;
-    additionalProperties?: 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;
-type TProviderNativeRawPayloadKind = 'request' | 'response' | 'stream_event';
-type TProviderNativeRawPayload = string | number | boolean | object | null | undefined;
-interface IProviderNativeRawPayloadEvent {
-    provider: string;
-    apiSurface?: string;
-    payloadKind: TProviderNativeRawPayloadKind;
-    payload: TProviderNativeRawPayload;
-    sequence?: number;
-    metadata?: Record<string, TProviderConfigValue>;
-}
-type TProviderNativeRawPayloadCallback = (event: IProviderNativeRawPayloadEvent) => 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;
-    /** Callback for provider-owned native SDK request/response/stream payload capture. */
-    onProviderNativeRawPayload?: TProviderNativeRawPayloadCallback;
-    /** AbortSignal for cancelling the provider call */
-    signal?: AbortSignal;
-    /** Provider-native hosted web tools requested for this call */
-    nativeWebTools?: IProviderNativeWebToolRequest;
-}
-/**
- * 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;
-    /**
-     * Report provider-neutral capability state.
-     * Providers without native web support can omit this and use default capability helpers.
-     */
-    getCapabilities?(): IProviderCapabilities;
-    /**
-     * Optional generic hook for enabling provider-native hosted web behavior.
-     */
-    configureNativeWebTools?(request: IProviderNativeWebToolRequest): IProviderCapabilities;
-    /**
-     * 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[];
-}
-
-/**
- * Abstract base for event services.
- * Concrete implementations decide how events are delivered.
- */
-declare abstract class AbstractEventService implements IEventService {
-    private listeners;
-    abstract emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
-    subscribe(listener: TEventListener): void;
-    unsubscribe(listener: TEventListener): void;
-    protected notifyListeners(eventType: string, data: IBaseEventData, context?: IEventContext): void;
-}
-/**
- * Default no-op event service (production-safe).
- * When injected, emit() intentionally does nothing.
- */
-declare class DefaultEventService extends AbstractEventService {
-    emit(_eventType: string, _data: IBaseEventData, _context?: IEventContext): void;
-}
-/**
- * Singleton default event service instance.
- */
-declare const DEFAULT_ABSTRACT_EVENT_SERVICE: IEventService;
-/**
- * Check if a given service is the default no-op implementation.
- */
-declare function isDefaultEventService(service: IEventService): boolean;
-/**
- * Compose a full event name from owner prefix and local name.
- * Local names must not contain dots.
- */
-declare function composeEventName(ownerType: string, localName: string): string;
-/**
- * A scoped event service that always emits with an owner binding applied.
- */
-declare class StructuredEventService extends AbstractEventService {
-    private readonly base;
-    private readonly binding;
-    constructor(base: IEventService, binding: IEventServiceOwnerBinding);
-    emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
-    subscribe(listener: TEventListener): void;
-    unsubscribe(listener: TEventListener): void;
-}
-/**
- * Bind an EventService to an explicit owner path.
- * This is the standard entry point for scoped emission (path-only architecture).
- */
-declare function bindWithOwnerPath(base: IEventService, binding: IEventServiceOwnerBinding): IEventService;
-/**
- * Alias for bindWithOwnerPath for historical call sites.
- * Intentionally forwards to the single authoritative implementation.
- */
-declare function bindEventServiceOwner(base: IEventService, binding: IEventServiceOwnerBinding): IEventService;
-/**
- * Observable EventService that notifies subscribed listeners.
- */
-declare class ObservableEventService extends AbstractEventService {
-    emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
-}
-
-declare const TASK_EVENTS: {
-    readonly ASSIGNED: "assigned";
-    readonly COMPLETED: "completed";
-};
-declare const TASK_EVENT_PREFIX: "task";
-
-declare const USER_EVENTS: {
-    readonly MESSAGE: "message";
-    readonly INPUT: "input";
-};
-declare const USER_EVENT_PREFIX: "user";
-type TUserEvent = (typeof USER_EVENTS)[keyof typeof USER_EVENTS];
-
-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>;
-/**
- * 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;
-}
-
-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;
-/**
- * Console logger implementation
- * @internal
- */
-declare class ConsoleLogger implements ILogger {
-    private level?;
-    private packageName;
-    private sinkLogger;
-    constructor(packageName: string, logger?: 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;
-    private getLevel;
-    private shouldLog;
-    private forward;
-}
-/**
- * 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;
-    maxExecutionRounds?: 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;
-    /** AbortSignal for cancelling execution */
-    signal?: AbortSignal;
-    /** Per-run streaming text callback. Prefer this over mutating provider callback state. */
-    onTextDelta?: TTextDeltaCallback;
-    /** Per-run replay event callback for provider/tool execution boundaries. */
-    onExecutionEvent?: TExecutionEventCallback;
-    /**
-     * Maximum model/tool rounds for this run.
-     * Use 0 for no core round cap.
-     */
-    maxExecutionRounds?: number;
-}
-type TExecutionEventData = Record<string, unknown>;
-type TExecutionEventCallback = (event: string, data: TExecutionEventData) => void;
-/**
- * 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;
-}
-
-interface IProviderConfig$1 {
-    name: string;
-    model: string;
-    apiKey?: string;
-    baseURL?: string;
-    timeout?: number;
-    options?: Record<string, TUniversalValue>;
-}
-interface IProviderProfileDefaults {
-    model?: string;
-    apiKey?: string;
-    baseURL?: string;
-    timeout?: number;
-    options?: Record<string, TUniversalValue>;
-}
-interface IProviderProfileConfig {
-    type?: string;
-    model?: string;
-    apiKey?: string;
-    baseURL?: string;
-    timeout?: number;
-    options?: Record<string, TUniversalValue>;
-}
-interface IProviderProbeResult {
-    ok: boolean;
-    message: string;
-    models?: string[];
-}
-type TProviderCredentialField = 'apiKey';
-type TProviderSetupField = 'baseURL' | 'model' | TProviderCredentialField;
-type TProviderSetupHelpLinkKind = 'api-key' | 'console' | 'official';
-interface IProviderCredentialRequirement {
-    anyOf: readonly TProviderCredentialField[];
-}
-interface IProviderSetupHelpLink {
-    kind: TProviderSetupHelpLinkKind;
-    label: string;
-    url: string;
-    sourceUrl?: string;
-    lastVerifiedAt?: string;
-}
-type TProviderModelCatalogStatus = 'live' | 'generated' | 'fallback' | 'unavailable';
-type TProviderModelLifecycle = 'active' | 'preview' | 'deprecated' | 'unavailable';
-type TProviderModelCapability = 'tools' | 'vision' | 'json_schema' | 'reasoning' | 'native_web' | 'streaming';
-interface IProviderModelCatalogEntry {
-    id: string;
-    displayName: string;
-    aliases?: readonly string[];
-    contextWindow?: number;
-    capabilities?: readonly TProviderModelCapability[];
-    lifecycle?: TProviderModelLifecycle;
-    lastVerifiedAt?: string;
-    sourceUrl?: string;
-}
-interface IProviderModelCatalog {
-    status: TProviderModelCatalogStatus;
-    entries?: readonly IProviderModelCatalogEntry[];
-    lastVerifiedAt?: string;
-    sourceUrl?: string;
-    message?: string;
-}
-interface IProviderModelCatalogRefreshOptions {
-    profile: IProviderProfileConfig;
-}
-type TProviderModelCatalogRefresh = (options: IProviderModelCatalogRefreshOptions) => Promise<IProviderModelCatalog>;
-interface IProviderSetupStepDefinition {
-    key: TProviderSetupField;
-    title: string;
-    defaultValue?: string;
-    required?: boolean;
-    masked?: boolean;
-}
-interface IProviderDefinition {
-    type: string;
-    aliases?: readonly string[];
-    displayName?: string;
-    description?: string;
-    defaults?: IProviderProfileDefaults;
-    modelCatalog?: IProviderModelCatalog;
-    refreshModelCatalog?: TProviderModelCatalogRefresh;
-    setupHelpLinks?: readonly IProviderSetupHelpLink[];
-    setupSteps?: readonly IProviderSetupStepDefinition[];
-    credentialRequirement?: IProviderCredentialRequirement;
-    requiresApiKey?: boolean;
-    createProvider: (config: IProviderConfig$1) => IAIProvider;
-    probeProfile?: (profile: IProviderProfileConfig) => Promise<IProviderProbeResult>;
-}
-declare function findProviderDefinition(definitions: readonly IProviderDefinition[], type: string): IProviderDefinition | undefined;
-declare function formatSupportedProviderTypes(definitions: readonly IProviderDefinition[]): string;
-declare function getProviderCredentialRequirement(definition: IProviderDefinition | undefined): IProviderCredentialRequirement | undefined;
-
-/**
- * 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;
-}
-
-/**
- * OpenAPI specification configuration
- */
-interface IOpenAPIToolConfig {
-    /** OpenAPI 3.0 specification */
-    spec: {
-        openapi: string;
-        info: {
-            title: string;
-            version: string;
-            description?: string;
-        };
-        servers?: Array<{
-            url: string;
-            description?: string;
-        }>;
-        paths: Record<string, Record<string, string | number | boolean | Record<string, string | number | boolean>>>;
-        components?: Record<string, Record<string, string | number | boolean>>;
-    };
-    /** Operation ID from the OpenAPI spec */
-    operationId: string;
-    /** Base URL for API calls */
-    baseURL: string;
-    /** Authentication configuration */
-    auth?: {
-        type: 'bearer' | 'apiKey' | 'basic';
-        token?: string;
-        apiKey?: string;
-        header?: string;
-        username?: string;
-        password?: string;
-    };
-}
-/**
- * MCP (Model Context Protocol) configuration
- */
-interface IMCPToolConfig {
-    /** MCP server endpoint */
-    endpoint: string;
-    /** Protocol version */
-    version?: string;
-    /** Authentication configuration */
-    auth?: {
-        type: 'bearer' | 'apiKey';
-        token: string;
-    };
-    /** Tool-specific configuration */
-    toolConfig?: Record<string, string | number | boolean>;
-    /** Timeout in milliseconds */
-    timeout?: number;
-}
-/**
- * Tool factory interface
- */
-interface IToolFactory {
-    /**
-     * Create function tool from schema and function
-     */
-    createFunctionTool(schema: IToolSchema, fn: TToolExecutor): IFunctionTool;
-    /**
-     * Create tool from OpenAPI specification
-     */
-    createOpenAPITool(config: IOpenAPIToolConfig): ITool;
-    /**
-     * Create MCP tool
-     */
-    createMCPTool(config: IMCPToolConfig): ITool;
-}
-
-/**
- * Execution step definition for tools that support step-by-step progress reporting
- */
-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;
-}
-
-/**
- * Terminal output abstraction — port interface for components that need I/O.
- * Owned by agent-core as a domain port. Implemented by agent-cli.
- */
-interface ISpinner {
-    stop(): void;
-    update(message: string): void;
-}
-interface ITerminalOutput {
-    write(text: string): void;
-    writeLine(text: string): void;
-    writeMarkdown(md: string): void;
-    writeError(text: string): void;
-    prompt(question: string): Promise<string>;
-    select(options: string[], initialIndex?: number): Promise<number>;
-    spinner(message: string): ISpinner;
-}
-
-/**
- * Minimal session abstraction shared across contract layers.
- * Lives in agent-core (Domain) so interface-level packages can reference it
- * without depending on agent-sessions (Session services layer).
- */
-interface ISession {
-    readonly sessionId: string;
-}
-
-/**
- * @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.
- *
- * Subclasses MUST: extend this class, use override keyword, call super() in constructor,
- * not redefine types that exist in agent-core, handle null message content correctly.
- *
- * @template TConfig - Provider configuration type
- */
-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>;
-    /**
-     * Wrap an async iterable to yield to the macrotask queue periodically.
-     * Providers MUST use this when iterating over streaming events to ensure
-     * the main thread event loop stays responsive (ESC abort, Ctrl+C, etc.).
-     *
-     * Usage in provider:
-     *   for await (const event of this.streamWithAbort(stream, signal)) { ... }
-     */
-    protected streamWithAbort<T>(source: AsyncIterable<T>, signal?: AbortSignal): AsyncGenerator<T>;
-    /**
-     * 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;
-    getCapabilities(): IProviderCapabilities;
-    /**
-     * Default implementation - providers can override for specific validation
-     * @returns true if configuration is valid
-     */
-    validateConfig(): boolean;
-    /** Validate that messages is a non-empty array with valid roles. */
-    protected validateMessages(messages: TUniversalMessage[]): void;
-    /** Validate tool schemas. No-ops if tools is undefined. */
-    protected validateTools(tools?: IToolSchema[]): void;
-    protected validateNativeWebTools(request?: IProviderNativeWebToolRequest): 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;
-}
-
-/**
- * Provider message format type.
- *
- * Provider packages own concrete message shapes. Core only carries the generic
- * conversion hook and never branches on provider names.
- */
-type TProviderMessage = TUniversalMessage | IUniversalObjectValue;
-type TMessageFormatConverter<TMessage extends TProviderMessage = TProviderMessage> = (messages: readonly TUniversalMessage[]) => TMessage[];
-type TMessageConverterRegistry = Readonly<Record<string, TMessageFormatConverter>>;
-/**
- * Universal message converter utility
- *
- * The converter is registry-based so provider-specific message conversion is
- * injected by provider packages or callers instead of being hardcoded in core.
- */
-declare class MessageConverter {
-    /**
-     * Convert messages using an injected converter or converter registry.
-     */
-    static toProviderFormat(messages: TUniversalMessage[], converter?: TMessageFormatConverter | string, registry?: TMessageConverterRegistry): TProviderMessage[];
-    /**
-     * 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): 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>;
-
-/** Create a user message. */
-declare function createUserMessage(content: string, options?: {
-    name?: string;
-    metadata?: TUniversalMessageMetadata;
-    parts?: TUniversalMessagePart[];
-}): IUserMessage;
-/** Create an assistant message. */
-declare function createAssistantMessage(content: string | null, options?: {
-    toolCalls?: IToolCall[];
-    metadata?: TUniversalMessageMetadata;
-    parts?: TUniversalMessagePart[];
-    state?: TMessageState;
-}): IAssistantMessage;
-/** Create a system message. */
-declare function createSystemMessage(content: string, options?: {
-    name?: string;
-    metadata?: TUniversalMessageMetadata;
-    parts?: TUniversalMessagePart[];
-}): ISystemMessage;
-/** Create a tool message. */
-declare function createToolMessage(content: string, options: {
-    toolCallId: string;
-    name?: string;
-    metadata?: TUniversalMessageMetadata;
-    parts?: TUniversalMessagePart[];
-}): IToolMessage;
-
-/** 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 store with duplicate prevention and API format conversion.
- * @public
- */
-declare class ConversationStore implements IConversationHistory {
-    private history;
-    private pendingAssistant;
-    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;
-    /** Add a raw history entry (events, etc.) */
-    addEntry(entry: IHistoryEntry): void;
-    /** Get all history entries (universal timeline) */
-    getHistory(): IHistoryEntry[];
-    getMessages(): TUniversalMessage[];
-    getMessagesByRole(role: TUniversalMessageRole): TUniversalMessage[];
-    getRecentMessages(count: number): TUniversalMessage[];
-    getMessageCount(): number;
-    /** Begin a new assistant response. Must be called before provider call.
-     *  Ensures pendingAssistant exists so commitAssistant always has data to save. */
-    beginAssistant(): void;
-    /** Append streaming text delta to pending assistant response */
-    appendStreaming(delta: string): void;
-    /** Append a tool call to pending assistant response (deduplicates by id) */
-    appendToolCall(toolCall: IToolCall): void;
-    /**
-     * Commit pending assistant response to history.
-     * Precondition: beginAssistant() must have been called before the provider call.
-     * History is append-only — this always adds a message.
-     */
-    commitAssistant(state: TMessageState, metadata?: TUniversalMessageMetadata): void;
-    /** Discard pending assistant response without saving */
-    discardPending(): void;
-    /** Returns true if there is accumulated pending assistant state (streaming or tool calls) */
-    hasPendingAssistant(): boolean;
-    /** Get pending assistant content (empty string if no content streamed yet) */
-    getPendingContent(): string;
-    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;
-    addEntry(entry: IHistoryEntry): void;
-    getHistory(): IHistoryEntry[];
-    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);
-    getConversationStore(conversationId: string): ConversationStore;
-    hasConversation(conversationId: string): boolean;
-    removeConversation(conversationId: string): boolean;
-    clearAll(): void;
-    getStats(): {
-        totalConversations: number;
-        conversationIds: string[];
-        totalMessages: number;
-    };
-    /** @internal */
-    private cleanupOldConversations;
-}
-
-/**
- * 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;
-    flushBuffer(): Promise<void>;
-    getStats(): IEventEmitterPluginStats;
-    clearAllListeners(): void;
-    destroy(): Promise<void>;
-}
-
-/**
- * Configuration and tool management delegate for the Robota agent.
- *
- * Extracted from robota.ts to keep the main class under 300 lines.
- */
-
-/** Agent statistics metadata type */
-type TAgentStatsMetadata = Record<string, string | number | boolean | Date | string[]>;
-
-/** Shared model configuration shape used in setModel / getModel. */
-type TModelConfig = {
-    provider: string;
-    model: string;
-    temperature?: number;
-    maxTokens?: number;
-    topP?: number;
-    systemMessage?: string;
-};
-/** Return shape of getConfiguration(). */
-type TConfigurationSnapshot = {
-    version: number;
-    tools: Array<{
-        name: string;
-        parameters?: string[];
-    }>;
-    updatedAt: number;
-};
-/** Return shape of getModuleStats(). */
-type TModuleStats = {
-    totalExecutions: number;
-    successfulExecutions: number;
-    failedExecutions: number;
-    averageExecutionTime: number;
-    lastExecutionTime?: Date;
-} | undefined;
-/** Shorthand for the plugin contract type used throughout this class. */
-type TPlugin = IPluginContract<IPluginOptions, IPluginStats> & IPluginHooks;
-/**
- * Core AI agent integrating multiple AI providers, tools, and plugins
- * into a unified conversational interface.
- * @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);
-    run(input: string, options?: IRunOptions): Promise<string>;
-    runStream(input: string, options?: IRunOptions): AsyncGenerator<string, void, undefined>;
-    private executionDeps;
-    getHistory(): TUniversalMessage[];
-    getFullHistory(): IHistoryEntry[];
-    addHistoryEntry(entry: IHistoryEntry): void;
-    clearHistory(): void;
-    injectMessage(role: 'user' | 'assistant' | 'system' | 'tool', content: string, options?: {
-        toolCallId?: string;
-        name?: string;
-    }): void;
-    updateTools(next: Array<IToolWithEventService>): Promise<{
-        version: number;
-    }>;
-    updateConfiguration(patch: Partial<IAgentConfig>): Promise<{
-        version: number;
-    }>;
-    getConfiguration(): Promise<TConfigurationSnapshot>;
-    setModel(mc: TModelConfig): void;
-    getModel(): TModelConfig;
-    registerTool(tool: AbstractTool): void;
-    unregisterTool(toolName: string): void;
-    getConfig(): IAgentConfig;
-    addPlugin(plugin: TPlugin): void;
-    removePlugin(pluginName: string): boolean;
-    getPlugin(pluginName: string): TPlugin | undefined;
-    getPlugins(): TPlugin[];
-    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): TModuleStats;
-    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;
-}
-
-/**
- * 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[];
-    };
-}
-
-interface IAssistantUsageMetadata {
-    inputTokens: number;
-    outputTokens: number;
-    usage: {
-        totalTokens: number;
-        inputTokens: number;
-        outputTokens: number;
-    };
-}
-declare function collectAssistantUsageMetadata(message: TUniversalMessage): IAssistantUsageMetadata | undefined;
-
-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;
-    };
-}
-/** Internal target shape for proxy interception */
-type TExecutionProxyTarget = Record<string, TUniversalValue>;
-/** Internal args shape for proxy interception */
-type TExecutionProxyArgs = TUniversalValue[];
-/**
- * Metadata extractor function type
- */
-type 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, WebFetch, WebSearch 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' | 'WebFetch' | 'WebSearch';
-/**
- * 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;
-}
-
-declare const CONTEXT_ESTIMATE_CHARS_PER_TOKEN = 4;
-interface IContextTokenEstimateOptions {
-    readonly usageFloorTokens?: number;
-}
-interface IContextTokenEstimate {
-    readonly usedTokens: number;
-    readonly serializedTokens: number;
-    readonly providerTokens?: number;
-    readonly usageFloorTokens?: number;
-}
-declare function estimateSerializedContextTokens(messages: readonly TUniversalMessage[]): number;
-declare function estimateContextTokensFromMessages(messages: readonly TUniversalMessage[], options?: IContextTokenEstimateOptions): IContextTokenEstimate;
-
-interface IMessageTokenUsage {
-    readonly inputTokens: number;
-    readonly outputTokens: number;
-    readonly totalTokens?: number;
-}
-/** Read normalized provider usage from a universal message when present. */
-declare function readTokenUsageFromMessage(message: TUniversalMessage): IMessageTokenUsage | undefined;
-declare function readTokenUsageFromMetadata(metadata: TUniversalMessageMetadata | undefined): IMessageTokenUsage | undefined;
-
-/**
- * Claude model definitions — SSOT for model metadata.
- * Source: https://platform.claude.com/docs/en/about-claude/models/overview
- */
-interface IModelDefinition {
-    /** Human-readable model name */
-    name: string;
-    /** API model identifier */
-    id: string;
-    /** Context window size in tokens */
-    contextWindow: number;
-    /** Maximum output tokens */
-    maxOutput: number;
-}
-/**
- * Known Claude models (4.5+).
- * Keyed by API model ID for fast lookup.
- */
-declare const CLAUDE_MODELS: Record<string, IModelDefinition>;
-declare const DEFAULT_CONTEXT_WINDOW = 200000;
-/** Get context window size for a model ID. Falls back to DEFAULT_CONTEXT_WINDOW. */
-declare function getModelContextWindow(modelId: string): number;
-declare const DEFAULT_MAX_OUTPUT = 16384;
-/** Get max output tokens for a model ID. Falls back to DEFAULT_MAX_OUTPUT. */
-declare function getModelMaxOutput(modelId: string): number;
-/** Get human-readable model name for a model ID. Falls back to the ID itself. */
-declare function getModelName(modelId: string): string;
-/** Format token count as human-readable (e.g., 200K, 1M, 1.2M). Minimum unit is K. */
-declare function formatTokenCount(tokens: number): string;
-
-/**
- * Hook system types — Claude Code compatible event/hook model.
- */
-/** Hook lifecycle events */
-type THookEvent = 'PreToolUse' | 'PostToolUse' | 'SessionStart' | 'SessionEnd' | 'Stop' | 'StopFailure' | 'PreCompact' | 'PostCompact' | 'UserPromptSubmit' | 'SubagentStart' | 'SubagentStop' | 'WorktreeCreate' | 'WorktreeRemove';
-/** Claude Code compatible session end reasons. */
-type TSessionEndReason = 'clear' | 'resume' | 'logout' | 'prompt_input_exit' | 'bypass_permissions_disabled' | 'other';
-/** Command hook — executes a shell command */
-interface ICommandHookDefinition {
-    type: 'command';
-    command: string;
-    timeout?: number;
-}
-/** HTTP hook — sends an HTTP request */
-interface IHttpHookDefinition {
-    type: 'http';
-    url: string;
-    headers?: Record<string, string>;
-    timeout?: number;
-}
-/** Prompt hook — evaluates a prompt via an AI model */
-interface IPromptHookDefinition {
-    type: 'prompt';
-    prompt: string;
-    model?: string;
-}
-/** Agent hook — delegates to a sub-agent */
-interface IAgentHookDefinition {
-    type: 'agent';
-    agent: string;
-    maxTurns?: number;
-    timeout?: number;
-}
-/** Discriminated union of all hook definition types */
-type IHookDefinition = ICommandHookDefinition | IHttpHookDefinition | IPromptHookDefinition | IAgentHookDefinition;
-/** A hook group — matcher + array of hook definitions */
-interface IHookGroup {
-    /** Regex pattern to match tool name (empty string = match all) */
-    matcher: string;
-    hooks: IHookDefinition[];
-    /** Environment variables injected into hook child processes for this group */
-    env?: Record<string, string>;
-}
-/** 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;
-    /** User message text (UserPromptSubmit only) */
-    user_message?: string;
-    /** User prompt text — Claude Code compatible alias for user_message (UserPromptSubmit only) */
-    prompt?: string;
-    /** Assistant response text (Stop only) */
-    response?: string;
-    /** Last assistant message text (StopFailure only) */
-    last_assistant_message?: string;
-    /** Stop hook recursion guard (Stop/StopFailure only) */
-    stop_hook_active?: boolean;
-    /** Session end reason (SessionEnd only) */
-    reason?: TSessionEndReason | string;
-    /** Session transcript path when available (SessionEnd/SubagentStop only) */
-    transcript_path?: string;
-    /** Subagent identifier (SubagentStart/SubagentStop only) */
-    agent_id?: string;
-    /** Subagent type/name (SubagentStart/SubagentStop only) */
-    agent_type?: string;
-    /** Subagent transcript path when available (SubagentStop only) */
-    agent_transcript_path?: string;
-    /** Claude Code permission mode at time of event (e.g. "default", "plan", "acceptEdits", "bypassPermissions") */
-    permission_mode?: string;
-    /** Additional environment variables to pass to hook child processes */
-    env?: Record<string, string>;
-}
-/** Hook execution result */
-interface IHookResult {
-    /** 0 = allow/proceed, 2 = block/deny, other = proceed with warning */
-    exitCode: number;
-    stdout: string;
-    stderr: string;
-}
-/** Strategy interface for hook type executors */
-interface IHookTypeExecutor {
-    /** The hook type this executor handles */
-    type: IHookDefinition['type'];
-    /** Execute a hook definition with the given input */
-    execute(definition: IHookDefinition, input: IHookInput): Promise<IHookResult>;
-}
-
-/**
- * Hook runner — executes hooks for lifecycle events using the strategy pattern.
- *
- * Dispatches to registered IHookTypeExecutor implementations by definition type.
- * Default executors: CommandExecutor (shell), HttpExecutor (HTTP POST).
- *
- * Exit code semantics:
- * - 0: allow/proceed
- * - 2: block/deny (stderr contains reason)
- * - other: proceed (logged as warning)
- *
- * stdout JSON semantics (Claude Code compatible):
- * - { continue: false } → block, regardless of exit code
- * - PreToolUse: { hookSpecificOutput: { permissionDecision, updatedInput } }
- * - UserPromptSubmit: { decision: "block" } → block; hookSpecificOutput.additionalContext → injected into stdout
- */
-
-/** Result of running hooks for an event. */
-interface IRunHooksResult {
-    blocked: boolean;
-    reason?: string;
-    /** Collected stdout from all successful hooks (exit code 0). */
-    stdout: string;
-    /** Parsed updatedInput from PreToolUse hookSpecificOutput (PreToolUse only). */
-    updatedInput?: Record<string, unknown>;
-    /** Highest-priority permissionDecision from PreToolUse hooks (PreToolUse only). */
-    permissionDecision?: 'allow' | 'deny' | 'ask' | 'defer';
-}
-/**
- * Run all hooks for a given event.
- *
- * For PreToolUse: if any hook returns exit code 2 or JSON deny, the tool call is blocked.
- * JSON stdout responses are parsed and applied per Claude Code spec.
- * Returns { blocked: true, reason } if blocked, otherwise { blocked: false, stdout }.
- *
- * @param config - Hooks configuration mapping events to hook groups
- * @param event - The lifecycle event being fired
- * @param input - Hook input data passed to executors
- * @param executors - Optional array of hook type executors (defaults to command + http)
- */
-declare function runHooks(config: THooksConfig | undefined, event: THookEvent, input: IHookInput, executors?: IHookTypeExecutor[]): Promise<IRunHooksResult>;
-
-export { AGENT_EVENTS, AGENT_EVENT_PREFIX, AbstractAIProvider, AbstractAgent, AbstractEventService, AbstractExecutor, AbstractManager, AbstractPlugin, AbstractTool, AgentFactory, AgentTemplates, AuthenticationError, CLAUDE_MODELS, CONTEXT_ESTIMATE_CHARS_PER_TOKEN, CacheIntegrityError, CircuitBreakerOpenError, ConfigurationError, ConsoleLogger, ConversationHistory, ConversationStore, DEFAULT_ABSTRACT_EVENT_SERVICE, DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_OUTPUT, DefaultEventService, 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 IAgentHookDefinition, type IAgentLifecycleEvents, type IAgentTemplate, type IAssistantMessage, type IAssistantUsageMetadata, type IBaseEventData, type IBaseMessage, type ICacheEntry, type ICacheKey, type ICacheOptions, type ICacheStats, type ICacheStorage, type IChatExecutionRequest, type IChatOptions, type ICommandHookDefinition, type IConfigValidationResult, type IContextOptions, type IContextTokenEstimate, type IContextTokenEstimateOptions, 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 IEventObjectValue, type IEventService, type IEventServiceOwnerBinding, type IExecutionEventData, type IExecutionService, type IExecutionServiceOptions, type IExecutor, type IExecutorAwareProviderConfig, type IFunctionTool, type IHistoryEntry, type IHookDefinition, type IHookGroup, type IHookInput, type IHookResult, type IHookTypeExecutor, type IHttpHookDefinition, type IImageComposeRequest, type IImageEditRequest, type IImageGenerationProvider, type IImageGenerationRequest, type IImageGenerationResult, type IInlineImageInputSource, type IInlineImageMessagePart, type ILocalExecutorConfig, type ILogger, type IMCPToolConfig, type IMediaOutputRef, type IMessageTokenUsage, type IModelDefinition, 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 IPromptHookDefinition, type IProviderCapabilities, type IProviderConfig$1 as IProviderConfig, type IProviderCredentialRequirement, type IProviderDefinition, type IProviderFunctionCallingCapability, type IProviderMediaError, type IProviderModelCatalog, type IProviderModelCatalogEntry, type IProviderModelCatalogRefreshOptions, type IProviderNativeRawPayloadEvent, type IProviderNativeWebToolCapabilities, type IProviderNativeWebToolCapability, type IProviderNativeWebToolRequest, type IProviderOptions, type IProviderProbeResult, type IProviderProfileConfig, type IProviderProfileDefaults, type IProviderRequest, type IProviderSetupHelpLink, type IProviderSetupStepDefinition, type IProviderSpecificOptions, type IRawProviderResponse, type IRemoteExecutorConfig, type IRunOptions, type ISession, type ISimpleValidationResult, type ISpinner, type IStreamExecutionRequest, type IStreamingChunk, type ISystemMessage, type ITemplateApplicationResult, type ITerminalOutput, 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, ObservableEventService, PluginCategory, PluginError, PluginPriority, ProviderError, RateLimitError, Robota, RobotaError, SilentLogger, StorageError, StructuredEventService, TASK_EVENTS, TASK_EVENT_PREFIX, type TAgentCreationMetadata, type TComplexConfigValue, type TConfigData, type TConfigValue, type TContextData, type TConversationContextMetadata, type TErrorContextData, type TErrorExternalInput, type TEventEmitterListener, type TEventExtensionValue, type TEventListener, type TEventLoggerData, type TEventName, type TEventUniversalValue, type TExecutionEventCallback, type TExecutionEventData, type TExecutionEventName, type TExecutionMetadata, type THookEvent, type THooksConfig, type TImageInputSource, type TJSONSchemaEnum, type TJSONSchemaKind, type TKnownToolName, type TLoggerData, type TManagerToolParameters, type TMessageConverterRegistry, type TMessageFormatConverter, type TMessageState, type TMetadata, type TMetadataValue, TOOL_EVENTS, TOOL_EVENT_PREFIX, type TParameterDefaultValue, type TPermissionDecision, type TPermissionMode, type TPrimitiveValue, type TProviderConfigValue, type TProviderCredentialField, type TProviderLoggingData, type TProviderMediaResult, type TProviderMessage, type TProviderModelCapability, type TProviderModelCatalogRefresh, type TProviderModelCatalogStatus, type TProviderModelLifecycle, type TProviderNativeRawPayload, type TProviderNativeRawPayloadCallback, type TProviderNativeRawPayloadKind, type TProviderOptionValueBase, type TProviderSetupField, type TProviderSetupHelpLinkKind, TRUST_TO_MODE, type TResponseMetadata, type TSessionEndReason, 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 TUserEvent, type TUtilLogLevel, ToolExecutionError, TypeUtils, UNKNOWN_TOOL_FALLBACK, USER_EVENTS, USER_EVENT_PREFIX, ValidationError, ValidationSeverity, Validator, assertProviderNativeWebToolsAvailable, bindEventServiceOwner, bindWithOwnerPath, chatEntryToMessage, collectAssistantUsageMetadata, composeEventName, createAssistantMessage, createDefaultProviderCapabilities, createExecutionProxy, createLogger, createSystemMessage, createToolMessage, createUserMessage, estimateContextTokensFromMessages, estimateSerializedContextTokens, evaluatePermission, findProviderDefinition, formatSupportedProviderTypes, formatTokenCount, getGlobalLogLevel, getMessagesForAPI, getModelContextWindow, getModelMaxOutput, getModelName, getProviderCapabilities, getProviderCredentialRequirement, getToolEstimatedDuration, getToolExecutionSteps, isAssistantMessage, isChatEntry, isDefaultEventService, isImageGenerationProvider, isProgressReportingTool, isSystemMessage, isToolMessage, isUserMessage, isVideoGenerationProvider, logger, messageToHistoryEntry, readTokenUsageFromMessage, readTokenUsageFromMetadata, runHooks, setGlobalLogLevel, setToolProgressCallback, startPeriodicTask, stopPeriodicTask, validateAgentConfig, validateApiKey, validateModelName, validateProviderName, validateUserInput, withEventEmission };