@robota-sdk/agent-plugin 3.0.0-beta.64

package/dist/node/index.d.ts

@@ -0,0 +1,1724 @@
+import { AbstractPlugin, IEventEmitterEventData, ILogger, IPluginErrorContext, IPluginExecutionContext, IPluginExecutionResult, IPluginOptions, IPluginStats, IRunOptions, IToolExecutionResult, PluginCategory, TErrorContextData, TEventName, TExecutionEventName, TLoggerData, TToolParameters, TUniversalMessage } from "@robota-sdk/agent-core";
+
+//#region src/conversation-history/types.d.ts
+/**
+ * Storage strategy for conversation history
+ */
+type THistoryStorageStrategy = 'memory' | 'file' | 'database';
+/**
+ * Configuration options for conversation history plugin
+ */
+interface IConversationHistoryPluginOptions extends IPluginOptions {
+  /** Storage strategy to use */
+  storage: THistoryStorageStrategy;
+  /** Maximum number of conversations to store */
+  maxConversations?: number;
+  /** Maximum messages per conversation */
+  maxMessagesPerConversation?: number;
+  /** File path for file storage strategy */
+  filePath?: string;
+  /** Database connection string for database storage */
+  connectionString?: string;
+  /** Whether to auto-save after each message */
+  autoSave?: boolean;
+  /** Save interval in milliseconds for batch saving */
+  saveInterval?: number;
+}
+/**
+ * Conversation history entry
+ */
+interface IConversationHistoryEntry {
+  conversationId: string;
+  messages: TUniversalMessage[];
+  startTime: Date;
+  lastUpdated: Date;
+  metadata?: Record<string, string | number | boolean | Date>;
+}
+/**
+ * Storage interface for conversation history
+ */
+interface IHistoryStorage {
+  save(conversationId: string, entry: IConversationHistoryEntry): Promise<void>;
+  load(conversationId: string): Promise<IConversationHistoryEntry | undefined>;
+  list(): Promise<string[]>;
+  delete(conversationId: string): Promise<boolean>;
+  clear(): Promise<void>;
+}
+/**
+ * Conversation history plugin statistics
+ */
+interface IConversationHistoryPluginStats extends IPluginStats {
+  /** Total number of conversations stored */
+  totalConversations: number;
+  /** Total number of messages stored */
+  totalMessages: number;
+  /** Storage strategy in use */
+  storageStrategy: THistoryStorageStrategy;
+  /** Last save timestamp */
+  lastSaveTime?: Date;
+  /** Number of failed saves */
+  failedSaves: number;
+}
+//#endregion
+//#region src/conversation-history/conversation-history-plugin.d.ts
+/**
+ * Persists conversation history using configurable storage backends.
+ *
+ * Supports memory, file, and database storage strategies. Messages are
+ * automatically trimmed to {@link IConversationHistoryPluginOptions.maxMessagesPerConversation | maxMessagesPerConversation}.
+ * When {@link IConversationHistoryPluginOptions.autoSave | autoSave} is
+ * disabled, changes are batched and flushed on a timer.
+ *
+ * @extends AbstractPlugin
+ * @see IHistoryStorage - storage backend contract
+ * @see IConversationHistoryPluginOptions - configuration options
+ *
+ * @example
+ * ```ts
+ * const plugin = new ConversationHistoryPlugin({
+ *   storage: 'memory',
+ *   maxMessagesPerConversation: 500,
+ * });
+ * await plugin.startConversation('conv-1');
+ * await plugin.addMessage({ role: 'user', content: 'Hello' });
+ * ```
+ */
+declare class ConversationHistoryPlugin extends AbstractPlugin<IConversationHistoryPluginOptions, IConversationHistoryPluginStats> {
+  name: string;
+  version: string;
+  private storage;
+  private pluginOptions;
+  private logger;
+  private currentConversationId?;
+  private batchSaveTimer?;
+  private pendingSaves;
+  constructor(options: IConversationHistoryPluginOptions);
+  /**
+   * Creates a new conversation entry and persists it (or queues for batch save).
+   * @throws PluginError if the storage write fails
+   */
+  startConversation(conversationId: string): Promise<void>;
+  /**
+   * Appends a message to the active conversation, trimming to the maximum
+   * message limit if exceeded.
+   * @throws PluginError if no conversation is active or the storage write fails
+   */
+  addMessage(message: TUniversalMessage): Promise<void>;
+  /**
+   * Load conversation history
+   */
+  loadConversation(conversationId: string): Promise<IConversationHistoryEntry | undefined>;
+  /**
+   * Get conversation history as messages
+   */
+  getHistory(conversationId: string): Promise<TUniversalMessage[]>;
+  /**
+   * List all conversation IDs
+   */
+  listConversations(): Promise<string[]>;
+  /**
+   * Delete a conversation
+   */
+  deleteConversation(conversationId: string): Promise<boolean>;
+  /**
+   * Clear all conversations
+   */
+  clearAllConversations(): Promise<void>;
+  /**
+   * Persists all conversations queued since the last save (batch mode only).
+   * Individual save failures are logged but do not abort the remaining saves.
+   */
+  savePending(): Promise<void>;
+  /**
+   * Stops the batch-save timer and flushes any pending conversation saves.
+   */
+  destroy(): Promise<void>;
+  /**
+   * Setup batch saving timer
+   */
+  private setupBatchSaving;
+}
+//#endregion
+//#region src/conversation-history/storages/memory-storage.d.ts
+/**
+ * Memory storage implementation
+ */
+declare class MemoryHistoryStorage implements IHistoryStorage {
+  private conversations;
+  private maxConversations;
+  constructor(maxConversations?: number);
+  save(conversationId: string, entry: IConversationHistoryEntry): Promise<void>;
+  load(conversationId: string): Promise<IConversationHistoryEntry | undefined>;
+  list(): Promise<string[]>;
+  delete(conversationId: string): Promise<boolean>;
+  clear(): Promise<void>;
+}
+//#endregion
+//#region src/conversation-history/storages/file-storage.d.ts
+/**
+ * File storage implementation
+ */
+declare class FileHistoryStorage implements IHistoryStorage {
+  private filePath;
+  private logger;
+  constructor(filePath: string);
+  save(conversationId: string, _entry: IConversationHistoryEntry): Promise<void>;
+  load(conversationId: string): Promise<IConversationHistoryEntry | undefined>;
+  list(): Promise<string[]>;
+  delete(conversationId: string): Promise<boolean>;
+  clear(): Promise<void>;
+}
+//#endregion
+//#region src/conversation-history/storages/database-storage.d.ts
+/**
+ * Database storage implementation
+ */
+declare class DatabaseHistoryStorage implements IHistoryStorage {
+  private connectionString;
+  private logger;
+  constructor(connectionString: string);
+  save(conversationId: string, _entry: IConversationHistoryEntry): Promise<void>;
+  load(conversationId: string): Promise<IConversationHistoryEntry | undefined>;
+  list(): Promise<string[]>;
+  delete(conversationId: string): Promise<boolean>;
+  clear(): Promise<void>;
+  /**
+   * Mask sensitive information in connection string for logging
+   */
+  private maskConnectionString;
+}
+//#endregion
+//#region src/error-handling/types.d.ts
+/**
+ * ErrorHandling Plugin - Type definitions for Facade pattern implementation
+ *
+ * REASON: Complex ErrorContextData compatibility issues require type adapters and unified error handling
+ * ALTERNATIVES_CONSIDERED:
+ * 1. Modify ErrorContextData type globally (breaks other components)
+ * 2. Use type assertions everywhere (reduces type safety)
+ * 3. Create complex union types (causes circular dependencies)
+ * 4. Redesign PluginError constructor (breaks existing contracts)
+ * 5. Remove context from error handling (loses debugging capability)
+ * TODO: Consider unified error context system across all plugins
+ */
+/**
+ * Error handling strategy types
+ */
+type TErrorHandlingStrategy = 'simple' | 'circuit-breaker' | 'exponential-backoff' | 'silent';
+/**
+ * Base error context for internal operations
+ * REASON: Optional properties and index signature for compatibility with both exactOptionalPropertyTypes and logger constraints
+ * ALTERNATIVES_CONSIDERED: Union types (breaks interface compatibility), explicit undefined (still triggers index signature rules), removing optional properties (breaks existing usage), type assertions (loses safety), intersection types (complex propagation)
+ * TODO: Consider unified error context type system across all plugins
+ */
+interface IErrorHandlingContextData {
+  executionId?: string;
+  sessionId?: string;
+  userId?: string;
+  attempt?: number;
+  finalAttempt?: boolean;
+  originalError?: string;
+  [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Configuration options for error handling plugin
+ */
+interface IErrorHandlingPluginOptions extends IPluginOptions {
+  /** Error handling strategy to use */
+  strategy: TErrorHandlingStrategy;
+  /** Maximum number of retry attempts */
+  maxRetries?: number;
+  /** Initial delay between retries in milliseconds */
+  retryDelay?: number;
+  /** Whether to log errors */
+  logErrors?: boolean;
+  /** Circuit breaker failure threshold */
+  failureThreshold?: number;
+  /** Circuit breaker timeout in milliseconds */
+  circuitBreakerTimeout?: number;
+  /** Custom error handler function */
+  customErrorHandler?: (error: Error, context: IErrorHandlingContextData) => Promise<void>;
+}
+/**
+ * Error handling plugin statistics
+ */
+interface IErrorHandlingPluginStats extends IPluginStats {
+  failureCount: number;
+  circuitBreakerOpen: boolean;
+  lastFailureTime: number;
+  totalRetries: number;
+  successfulRecoveries: number;
+}
+/**
+ * Error context adapter for PluginError compatibility
+ */
+interface IErrorContextAdapter {
+  originalError?: string;
+  executionId?: string;
+  sessionId?: string;
+  userId?: string;
+  attempt?: number;
+  [key: string]: string | number | boolean | Date | Error | string[] | undefined;
+}
+//#endregion
+//#region src/error-handling/error-handling-plugin.d.ts
+/**
+ * Provides configurable error recovery using one of four strategies:
+ * simple logging, circuit breaker, exponential backoff, or silent.
+ *
+ * The circuit breaker opens after
+ * {@link IErrorHandlingPluginOptions.failureThreshold | failureThreshold}
+ * consecutive failures and automatically resets after
+ * {@link IErrorHandlingPluginOptions.circuitBreakerTimeout | circuitBreakerTimeout} ms.
+ * An optional custom error handler can be injected for application-specific
+ * recovery logic.
+ *
+ * @extends AbstractPlugin
+ * @see IErrorHandlingPluginOptions - configuration options
+ * @see IErrorHandlingContextData - error context contract
+ *
+ * @example
+ * ```ts
+ * const plugin = new ErrorHandlingPlugin({
+ *   strategy: 'circuit-breaker',
+ *   failureThreshold: 5,
+ *   circuitBreakerTimeout: 60000,
+ * });
+ * const result = await plugin.executeWithRetry(() => fetchData());
+ * ```
+ */
+declare class ErrorHandlingPlugin extends AbstractPlugin<IErrorHandlingPluginOptions, IErrorHandlingPluginStats> {
+  name: string;
+  version: string;
+  private pluginOptions;
+  private logger;
+  private failureCount;
+  private circuitBreakerOpen;
+  private lastFailureTime;
+  constructor(options: IErrorHandlingPluginOptions);
+  /**
+   * Dispatches the error to the active strategy handler. If a custom error
+   * handler is configured, it takes precedence over strategy-specific handling.
+   */
+  handleError(error: Error, context?: IErrorHandlingContextData): Promise<void>;
+  /**
+   * Executes a function with automatic retries up to
+   * {@link IErrorHandlingPluginOptions.maxRetries | maxRetries}. The delay
+   * between retries follows the configured strategy (fixed for simple /
+   * circuit-breaker, doubling for exponential-backoff).
+   *
+   * @throws PluginError after all retry attempts are exhausted
+   */
+  executeWithRetry<T>(fn: () => Promise<T>, context?: IErrorHandlingContextData): Promise<T>;
+  /**
+   * Resets the circuit breaker to closed state, clearing failure count and
+   * last failure timestamp.
+   */
+  resetCircuitBreaker(): void;
+  /**
+   * Get error handling statistics
+   */
+  getStats(): IErrorHandlingPluginStats;
+  /**
+   * Cleanup resources
+   */
+  destroy(): Promise<void>;
+  private handleSimple;
+  private handleCircuitBreaker;
+  private handleExponentialBackoff;
+}
+//#endregion
+//#region src/error-handling/context-adapter.d.ts
+/**
+ * Convert IErrorHandlingContextData to ErrorContextData-compatible format for PluginError
+ * REASON: Simple object spread with known properties to avoid index signature conflicts
+ * ALTERNATIVES_CONSIDERED: Complex type adapters (unnecessary), Object.assign (verbose), bracket notation (rejected by TS), type assertions (reduces safety)
+ * TODO: Consider unified error context type system across all plugins
+ */
+declare function toErrorContext(context: IErrorHandlingContextData): IErrorContextAdapter;
+/**
+ * Safe context extraction for PluginError with nested context structure
+ *
+ * REASON: PluginError context needs flexible data structure for debugging information
+ * ALTERNATIVES_CONSIDERED:
+ * 1. Strict primitive types (loses debugging information)
+ * 2. Interface definitions (too rigid for error contexts)
+ * 3. Union types (becomes unwieldy for error data)
+ * 4. Generic constraints (too complex for error handling)
+ * 5. Type assertions (decreases type safety)
+ * TODO: Consider standardized error context interface if patterns emerge
+ */
+declare function createPluginErrorContext(context: IErrorHandlingContextData, additionalData?: TErrorContextData): TErrorContextData;
+//#endregion
+//#region src/execution-analytics/types.d.ts
+/**
+ * Analytics context data for execution tracking
+ */
+interface IExecutionAnalyticsContextData {
+  executionId?: string;
+  sessionId?: string;
+  userId?: string;
+  operation?: string;
+  toolName?: string;
+  parameterCount?: number;
+  inputLength?: number;
+  responseLength?: number;
+  hasOptions?: boolean;
+  hasError?: boolean;
+  resultType?: string;
+  errorSource?: string;
+  contextType?: string;
+  hasContext?: boolean;
+  modelName?: string;
+}
+/**
+ * Execution statistics entry
+ */
+interface IExecutionStats {
+  executionId: string;
+  operation: string;
+  startTime: Date;
+  endTime: Date;
+  duration: number;
+  success: boolean;
+  error?: {
+    message: string;
+    stack?: string;
+    type: string;
+  };
+  metadata?: Record<string, string | number | boolean | Date | string[]>;
+}
+/**
+ * Aggregated execution statistics
+ */
+interface IAggregatedExecutionStats {
+  totalExecutions: number;
+  successfulExecutions: number;
+  failedExecutions: number;
+  successRate: number;
+  averageDuration: number;
+  totalDuration: number;
+  operationStats: Record<string, {
+    count: number;
+    successCount: number;
+    failureCount: number;
+    averageDuration: number;
+    totalDuration: number;
+  }>;
+  errorStats: Record<string, number>;
+  timeRange: {
+    start: Date;
+    end: Date;
+  };
+}
+/**
+ * Plugin options
+ */
+interface IExecutionAnalyticsOptions extends IPluginOptions {
+  /** Maximum number of entries to keep in memory */
+  maxEntries?: number;
+  /** Whether to track error details */
+  trackErrors?: boolean;
+  /** Performance threshold in milliseconds for warnings */
+  performanceThreshold?: number;
+  /** Enable performance warnings */
+  enableWarnings?: boolean;
+}
+/**
+ * Execution analytics plugin statistics
+ */
+interface IExecutionAnalyticsPluginStats extends IPluginStats {
+  /** Total number of executions recorded */
+  totalRecorded: number;
+  /** Number of active executions */
+  activeExecutions: number;
+  /** Memory usage in KB */
+  memoryUsage: number;
+  /** Oldest record timestamp */
+  oldestRecord?: Date;
+  /** Newest record timestamp */
+  newestRecord?: Date;
+}
+//#endregion
+//#region src/execution-analytics/execution-analytics-plugin.d.ts
+/**
+ * Tracks timing and success/failure of agent runs, provider calls, and tool executions.
+ * @extends AbstractPlugin
+ */
+declare class ExecutionAnalyticsPlugin extends AbstractPlugin<IExecutionAnalyticsOptions, IExecutionAnalyticsPluginStats> {
+  name: string;
+  version: string;
+  private pluginOptions;
+  private logger;
+  private activeExecutions;
+  private executionHistory;
+  private executionCounter;
+  private initialized;
+  constructor(options?: IExecutionAnalyticsOptions);
+  beforeRun: (input: string, _options?: IRunOptions) => Promise<void>;
+  afterRun: (input: string, response: string, options?: IRunOptions) => Promise<void>;
+  beforeProviderCall: (messages: TUniversalMessage[]) => Promise<void>;
+  afterProviderCall: (messages: TUniversalMessage[], response: TUniversalMessage) => Promise<void>;
+  beforeToolCall(toolName: string, _parameters: TToolParameters): Promise<void>;
+  afterToolCall(toolName: string, parameters: TToolParameters, result: IToolExecutionResult): Promise<void>;
+  onError(error: Error, context?: IPluginErrorContext): Promise<void>;
+  getExecutionStats(operation?: string, timeRange?: {
+    start: Date;
+    end: Date;
+  }): IExecutionStats[];
+  getAggregatedStats(timeRange?: {
+    start: Date;
+    end: Date;
+  }): IAggregatedExecutionStats;
+  clearStats(): void;
+  getActiveExecutions(): Array<{
+    executionId: string;
+    operation: string;
+    duration: number;
+  }>;
+  getPluginStats(): {
+    totalRecorded: number;
+    activeExecutions: number;
+    memoryUsage: number;
+    oldestRecord?: Date;
+    newestRecord?: Date;
+  };
+  destroy(): Promise<void>;
+  getExecutionData(): IExecutionStats[];
+  getAnalyticsStats(): IAggregatedExecutionStats;
+  clearExecutionData(): void;
+  getStatus(): {
+    name: string;
+    version: string;
+    enabled: boolean;
+    initialized: boolean;
+    category: PluginCategory;
+    priority: number;
+    subscribedEventsCount: number;
+    hasEventEmitter: boolean;
+  };
+  getStats(): IExecutionAnalyticsPluginStats;
+  private recordStats;
+}
+//#endregion
+//#region src/execution-analytics/analytics-aggregation.d.ts
+/** Compute aggregated analytics across recorded executions. @internal */
+declare function aggregateExecutionStats(stats: IExecutionStats[], timeRange?: {
+  start: Date;
+  end: Date;
+}): IAggregatedExecutionStats;
+//#endregion
+//#region src/limits/types.d.ts
+/**
+ * Rate limiting strategies
+ */
+type TLimitsStrategy = 'token-bucket' | 'sliding-window' | 'fixed-window' | 'none';
+/**
+ * Limits plugin configuration
+ */
+interface ILimitsPluginOptions extends IPluginOptions {
+  /** Rate limiting strategy */
+  strategy: TLimitsStrategy;
+  /** Maximum tokens per time window */
+  maxTokens?: number;
+  /** Maximum requests per time window */
+  maxRequests?: number;
+  /** Time window in milliseconds */
+  timeWindow?: number;
+  /** Maximum cost per time window (in USD) */
+  maxCost?: number;
+  /** Token cost per 1000 tokens (in USD) */
+  tokenCostPer1000?: number;
+  /** Bucket refill rate for token bucket strategy */
+  refillRate?: number;
+  /** Initial bucket size for token bucket strategy */
+  bucketSize?: number;
+  /** Custom cost calculator */
+  costCalculator?: (tokens: number, model: string) => number;
+}
+/**
+ * Plugin limits status data type - supports nested objects and null values for comprehensive status reporting
+ *
+ * REASON: Status data needs to include nested objects for bucket/window details and null values for missing data
+ * ALTERNATIVES_CONSIDERED:
+ * 1. Strict primitive types (loses nested status information)
+ * 2. Union types without null (breaks null handling)
+ * 3. Interface definitions (too rigid for dynamic status)
+ * 4. Generic constraints (too complex for status data)
+ * 5. Type assertions (decreases type safety)
+ * TODO: Consider specific status interfaces if patterns emerge
+ */
+type TPluginLimitsStatusData = Record<string, string | number | boolean | Array<string | number | boolean> | Record<string, string | number | boolean> | null>;
+/**
+ * Rate limiting window data
+ */
+interface ILimitWindow {
+  count: number;
+  tokens: number;
+  cost: number;
+  windowStart: number;
+}
+/**
+ * Token bucket state
+ */
+interface ITokenBucket {
+  tokens: number;
+  lastRefill: number;
+  requests: number;
+  cost: number;
+  windowStart: number;
+}
+//#endregion
+//#region src/limits/limits-plugin.d.ts
+interface ILimitsPluginExecutionContext extends IPluginExecutionContext {
+  config?: {
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+  };
+  conversationId?: string;
+}
+interface ILimitsPluginExecutionResult {
+  tokensUsed?: number;
+  cost?: number;
+  success?: boolean;
+  [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Enforces rate limiting on token usage, request frequency, and cost.
+ * @extends AbstractPlugin
+ */
+declare class LimitsPlugin extends AbstractPlugin<ILimitsPluginOptions> {
+  name: string;
+  version: string;
+  private pluginOptions;
+  private logger;
+  private windows;
+  private buckets;
+  constructor(options: ILimitsPluginOptions);
+  beforeExecution(context: IPluginExecutionContext): Promise<void>;
+  afterExecution(context: IPluginExecutionContext, result: IPluginExecutionResult): Promise<void>;
+  private getBucket;
+  private getWindow;
+  private getKey;
+  private resolveModelName;
+  getLimitsStatus(key?: string): TPluginLimitsStatusData;
+  resetLimits(key?: string): void;
+}
+//#endregion
+//#region src/logging/types.d.ts
+/**
+ * Logging strategy types
+ */
+type TLoggingStrategy = 'console' | 'file' | 'remote' | 'silent';
+/**
+ * Log levels
+ */
+type TLogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Log entry structure
+ */
+interface ILogEntry {
+  timestamp: Date;
+  level: TLogLevel;
+  message: string;
+  context?: Record<string, string | number | boolean | Date | undefined>;
+  metadata?: {
+    executionId?: string;
+    conversationId?: string;
+    userId?: string;
+    sessionId?: string;
+    operation?: string;
+    duration?: number;
+  };
+}
+/**
+ * Configuration options for logging plugin
+ */
+interface ILoggingPluginOptions extends IPluginOptions {
+  /** Logging strategy to use */
+  strategy: TLoggingStrategy;
+  /** Minimum log level to capture */
+  level?: TLogLevel;
+  /** File path for file strategy */
+  filePath?: string;
+  /** Remote endpoint for remote strategy */
+  remoteEndpoint?: string;
+  /** Headers for remote logging */
+  remoteHeaders?: Record<string, string>;
+  /** Maximum number of logs to keep in memory */
+  maxLogs?: number;
+  /** Whether to include stack traces in error logs */
+  includeStackTrace?: boolean;
+  /** Custom log formatter */
+  formatter?: ILogFormatter;
+  /** Logger instance for internal plugin logging */
+  logger?: ILogger;
+  /** Batch size for remote logging */
+  batchSize?: number;
+  /** Flush interval for batched logging in milliseconds */
+  flushInterval?: number;
+}
+/**
+ * Log formatter interface
+ */
+interface ILogFormatter {
+  format(entry: ILogEntry): string;
+}
+/**
+ * Log storage interface
+ */
+interface ILogStorage {
+  write(entry: ILogEntry): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+/** Structured context data for log entries */
+interface ILoggingContextData extends Record<string, string | number | boolean | Date | undefined> {
+  userInput?: string;
+  duration?: number;
+  toolName?: string;
+  success?: boolean;
+  executionId?: string;
+  operation?: string;
+  errorMessage?: string;
+  errorStack?: string;
+  inputLength?: number;
+  responseLength?: number;
+  hasOptions?: boolean;
+  modelName?: string;
+}
+/**
+ * Logging plugin statistics
+ */
+interface ILoggingPluginStats extends IPluginStats {
+  /** Total number of logs written */
+  logsWritten: number;
+  /** Number of failed log writes */
+  failedWrites: number;
+  /** Current log level */
+  currentLevel: TLogLevel;
+  /** Storage strategy in use */
+  strategy: TLoggingStrategy;
+  /** Last flush timestamp */
+  lastFlushTime?: Date;
+}
+//#endregion
+//#region src/logging/logging-plugin.d.ts
+/** Logs agent operations using configurable storage backends (console/file/remote/silent). */
+declare class LoggingPlugin extends AbstractPlugin<ILoggingPluginOptions, ILoggingPluginStats> {
+  name: string;
+  version: string;
+  private storage;
+  private pluginOptions;
+  private logger;
+  private simpleLogger;
+  private logLevels;
+  constructor(options: ILoggingPluginOptions);
+  /**
+   * Routes module lifecycle events (initialize, execute, dispose) to the
+   * appropriate log level. Errors are logged but never re-thrown.
+   */
+  onModuleEvent(eventName: TEventName, eventData: IEventEmitterEventData): Promise<void>;
+  /**
+   * Writes a log entry to the configured storage if the level meets the
+   * current threshold. Logging failures are swallowed to prevent cascading errors.
+   */
+  log(level: TLogLevel, message: string, context?: ILoggingContextData, metadata?: ILogEntry['metadata']): Promise<void>;
+  /** Log debug message */
+  debug(message: string, context?: ILoggingContextData, metadata?: ILogEntry['metadata']): Promise<void>;
+  /** Log info message */
+  info(message: string, context?: ILoggingContextData, metadata?: ILogEntry['metadata']): Promise<void>;
+  /** Log warning message */
+  warn(message: string, context?: ILoggingContextData, metadata?: ILogEntry['metadata']): Promise<void>;
+  /**
+   * Log error message
+   */
+  error(message: string, error?: Error, context?: ILoggingContextData, metadata?: ILogEntry['metadata']): Promise<void>;
+  /**
+   * Logs the start of an agent execution, truncating user input to 100 characters.
+   */
+  logExecutionStart(executionId: string, userInput: string, metadata?: ILogEntry['metadata']): Promise<void>;
+  /**
+   * Logs the completion of an agent execution with its duration.
+   */
+  logExecutionComplete(executionId: string, duration: number, metadata?: ILogEntry['metadata']): Promise<void>;
+  /**
+   * Logs a tool execution result at info (success) or error (failure) level.
+   */
+  logToolExecution(toolName: string, executionId: string, duration?: number, success?: boolean, metadata?: ILogEntry['metadata']): Promise<void>;
+  /**
+   * Flushes any buffered log entries to the underlying storage.
+   * @throws PluginError if the flush operation fails
+   */
+  flush(): Promise<void>;
+  /**
+   * Closes the underlying storage and releases resources.
+   */
+  destroy(): Promise<void>;
+  /** Check if message should be logged based on level */
+  private shouldLog;
+}
+//#endregion
+//#region src/logging/storages/console-storage.d.ts
+/**
+ * Console log storage
+ */
+declare class ConsoleLogStorage implements ILogStorage {
+  private formatter;
+  private logger;
+  constructor(formatter?: ILogFormatter, logger?: ILogger);
+  write(entry: ILogEntry): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/logging/storages/file-storage.d.ts
+/**
+ * File log storage (placeholder implementation)
+ */
+declare class FileLogStorage implements ILogStorage {
+  private filePath;
+  private formatter;
+  private logger;
+  constructor(filePath: string, formatter?: ILogFormatter);
+  write(entry: ILogEntry): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/logging/storages/remote-storage.d.ts
+/**
+ * Remote log storage with batching
+ */
+declare class RemoteLogStorage implements ILogStorage {
+  private url;
+  private formatter;
+  private batchSize;
+  private flushInterval;
+  private pendingLogs;
+  private flushTimer;
+  private logger;
+  constructor(url: string, _options?: {
+    timeout?: number;
+  });
+  write(entry: ILogEntry): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/logging/storages/silent-storage.d.ts
+/**
+ * Silent log storage (no-op)
+ */
+declare class SilentLogStorage implements ILogStorage {
+  write(_entry: ILogEntry): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/logging/formatters.d.ts
+/**
+ * Default console formatter
+ */
+declare class ConsoleLogFormatter implements ILogFormatter {
+  format(entry: ILogEntry): string;
+}
+/**
+ * JSON formatter for file/remote logging
+ */
+declare class JsonLogFormatter implements ILogFormatter {
+  format(entry: ILogEntry): string;
+}
+//#endregion
+//#region src/performance/types.d.ts
+/**
+ * Performance monitoring strategy types
+ */
+type TPerformanceMonitoringStrategy = 'memory' | 'file' | 'prometheus' | 'remote' | 'silent';
+/**
+ * Performance metrics entry
+ */
+interface IPerformanceMetrics {
+  executionId?: string;
+  conversationId?: string;
+  timestamp: Date;
+  operation: string;
+  duration: number;
+  memoryUsage?: {
+    used: number;
+    free: number;
+    total: number;
+    heap: {
+      used: number;
+      total: number;
+    };
+  };
+  cpuUsage?: {
+    user: number;
+    system: number;
+    percent: number;
+  };
+  networkStats?: {
+    requests: number;
+    bytesReceived: number;
+    bytesSent: number;
+    latency: number;
+  };
+  errorCount: number;
+  success: boolean;
+  metadata?: Record<string, string | number | boolean | Date>;
+}
+/**
+ * Aggregated performance statistics
+ */
+interface IAggregatedPerformanceStats {
+  totalOperations: number;
+  averageDuration: number;
+  minDuration: number;
+  maxDuration: number;
+  successRate: number;
+  errorRate: number;
+  memoryStats?: {
+    averageUsed: number;
+    maxUsed: number;
+    averageHeapUsed: number;
+    maxHeapUsed: number;
+  };
+  cpuStats?: {
+    averagePercent: number;
+    maxPercent: number;
+  };
+  networkStats?: {
+    totalRequests: number;
+    totalBytesReceived: number;
+    totalBytesSent: number;
+    averageLatency: number;
+  };
+  operationStats: Record<string, {
+    count: number;
+    averageDuration: number;
+    successRate: number;
+    errorCount: number;
+  }>;
+  timeRangeStats: {
+    startTime: Date;
+    endTime: Date;
+    period: string;
+  };
+}
+/**
+ * Configuration options for performance plugin
+ */
+interface IPerformancePluginOptions extends IPluginOptions {
+  /** Performance monitoring strategy to use */
+  strategy: TPerformanceMonitoringStrategy;
+  /** File path for file strategy */
+  filePath?: string;
+  /** Remote endpoint for remote strategy */
+  remoteEndpoint?: string;
+  /** Prometheus endpoint for prometheus strategy */
+  prometheusEndpoint?: string;
+  /** Headers for remote monitoring */
+  remoteHeaders?: Record<string, string>;
+  /** Maximum number of performance entries to keep in memory */
+  maxEntries?: number;
+  /** Whether to monitor memory usage */
+  monitorMemory?: boolean;
+  /** Whether to monitor CPU usage */
+  monitorCPU?: boolean;
+  /** Whether to monitor network stats */
+  monitorNetwork?: boolean;
+  /** Batch size for remote reporting */
+  batchSize?: number;
+  /** Flush interval for batched reporting in milliseconds */
+  flushInterval?: number;
+  /** Whether to aggregate statistics */
+  aggregateStats?: boolean;
+  /** Aggregation interval in milliseconds */
+  aggregationInterval?: number;
+  /** Performance threshold in milliseconds to log warnings */
+  performanceThreshold?: number;
+}
+/**
+ * Performance storage interface
+ */
+interface IPerformanceStorage {
+  save(entry: IPerformanceMetrics): Promise<void>;
+  getMetrics(operation?: string, timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IPerformanceMetrics[]>;
+  getAggregatedStats(timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IAggregatedPerformanceStats>;
+  clear(): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+/**
+ * System metrics collector interface
+ */
+interface ISystemMetricsCollector {
+  getMemoryUsage(): Promise<IPerformanceMetrics['memoryUsage']>;
+  getCPUUsage(): Promise<IPerformanceMetrics['cpuUsage']>;
+  getNetworkStats(): Promise<IPerformanceMetrics['networkStats']>;
+}
+/**
+ * Performance plugin statistics
+ */
+interface IPerformancePluginStats extends IPluginStats {
+  /** Total number of metrics recorded */
+  metricsRecorded: number;
+  /** Number of performance threshold violations */
+  thresholdViolations: number;
+  /** Current monitoring strategy */
+  strategy: TPerformanceMonitoringStrategy;
+  /** Monitoring status */
+  monitoring: {
+    memory: boolean;
+    cpu: boolean;
+    network: boolean;
+  };
+  /** Last metrics collection timestamp */
+  lastCollectionTime?: Date;
+}
+//#endregion
+//#region src/performance/performance-plugin.d.ts
+/**
+ * Collects application and system performance metrics during agent execution.
+ *
+ * Optionally monitors memory, CPU, and network via
+ * {@link ISystemMetricsCollector}. Logs a warning when an operation exceeds
+ * the configured {@link IPerformancePluginOptions.performanceThreshold | performanceThreshold}.
+ * Currently only the `memory` storage strategy is implemented.
+ *
+ * Lifecycle hooks used: {@link AbstractPlugin.onModuleEvent | onModuleEvent}
+ *
+ * @extends AbstractPlugin
+ * @see IPerformanceStorage - storage backend contract
+ * @see ISystemMetricsCollector - system metrics collection contract
+ * @see IPerformancePluginOptions - configuration options
+ *
+ * @example
+ * ```ts
+ * const plugin = new PerformancePlugin({
+ *   strategy: 'memory',
+ *   monitorMemory: true,
+ *   performanceThreshold: 2000,
+ * });
+ * await plugin.recordMetrics({ operation: 'run', duration: 1500, success: true, errorCount: 0 });
+ * ```
+ */
+declare class PerformancePlugin extends AbstractPlugin<IPerformancePluginOptions, IPerformancePluginStats> {
+  name: string;
+  version: string;
+  private storage;
+  private metricsCollector;
+  private pluginOptions;
+  private logger;
+  constructor(options: IPerformancePluginOptions);
+  /**
+   * Records performance metrics from module lifecycle events
+   * (initialization, execution, disposal) including duration and error counts.
+   */
+  onModuleEvent(eventName: TEventName, eventData: IEventEmitterEventData): Promise<void>;
+  /**
+   * Records performance metrics, enriching them with system metrics (memory,
+   * CPU, network) when the corresponding monitoring options are enabled.
+   * @throws PluginError if the storage write fails
+   */
+  recordMetrics(metrics: Omit<IPerformanceMetrics, 'timestamp' | 'memoryUsage' | 'cpuUsage' | 'networkStats'>): Promise<void>;
+  /**
+   * Retrieves recorded metrics, optionally filtered by operation name and time range.
+   * @throws PluginError if the storage read fails
+   */
+  getMetrics(operation?: string, timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IPerformanceMetrics[]>;
+  /**
+   * Get aggregated performance statistics
+   */
+  getAggregatedStats(timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IAggregatedPerformanceStats>;
+  /**
+   * Clear all performance metrics
+   */
+  clearMetrics(): Promise<void>;
+  /**
+   * Closes the underlying storage and releases resources.
+   */
+  destroy(): Promise<void>;
+}
+//#endregion
+//#region src/performance/storages/memory-storage.d.ts
+declare class MemoryPerformanceStorage implements IPerformanceStorage {
+  private entries;
+  private maxEntries;
+  constructor(maxEntries?: number);
+  save(entry: IPerformanceMetrics): Promise<void>;
+  getMetrics(operation?: string, timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IPerformanceMetrics[]>;
+  getAggregatedStats(timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IAggregatedPerformanceStats>;
+  clear(): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/performance/collectors/system-metrics-collector.d.ts
+/**
+ * Node.js system metrics collector
+ */
+declare class NodeSystemMetricsCollector implements ISystemMetricsCollector {
+  private logger;
+  constructor();
+  getMemoryUsage(): Promise<IPerformanceMetrics['memoryUsage']>;
+  getCPUUsage(): Promise<IPerformanceMetrics['cpuUsage']>;
+  getNetworkStats(): Promise<IPerformanceMetrics['networkStats']>;
+}
+//#endregion
+//#region src/usage/types.d.ts
+/**
+ * Usage tracking strategy types
+ */
+type TUsageTrackingStrategy = 'memory' | 'file' | 'remote' | 'silent';
+/**
+ * Usage statistics entry
+ */
+interface IUsageStats {
+  conversationId?: string;
+  executionId?: string;
+  timestamp: Date;
+  provider: string;
+  model: string;
+  tokensUsed: {
+    input: number;
+    output: number;
+    total: number;
+  };
+  cost?: {
+    input: number;
+    output: number;
+    total: number;
+  };
+  requestCount: number;
+  duration: number;
+  success: boolean;
+  toolsUsed?: string[];
+  metadata?: Record<string, string | number | boolean | Date>;
+}
+/**
+ * Aggregated usage statistics
+ */
+interface IAggregatedUsageStats {
+  totalRequests: number;
+  totalTokens: number;
+  totalCost: number;
+  totalDuration: number;
+  successRate: number;
+  providerStats: Record<string, {
+    requests: number;
+    tokens: number;
+    cost: number;
+    duration: number;
+  }>;
+  modelStats: Record<string, {
+    requests: number;
+    tokens: number;
+    cost: number;
+    duration: number;
+  }>;
+  toolStats: Record<string, {
+    usageCount: number;
+    successCount: number;
+    totalDuration: number;
+  }>;
+  timeRangeStats: {
+    startTime: Date;
+    endTime: Date;
+    period: string;
+  };
+}
+/**
+ * Configuration options for usage plugin
+ */
+interface IUsagePluginOptions extends IPluginOptions {
+  /** Usage tracking strategy to use */
+  strategy: TUsageTrackingStrategy;
+  /** File path for file strategy */
+  filePath?: string;
+  /** Remote endpoint for remote strategy */
+  remoteEndpoint?: string;
+  /** Headers for remote logging */
+  remoteHeaders?: Record<string, string>;
+  /** Maximum number of usage entries to keep in memory */
+  maxEntries?: number;
+  /** Whether to track token costs */
+  trackCosts?: boolean;
+  /** Cost per token rates for different models */
+  costRates?: Record<string, {
+    input: number;
+    output: number;
+  }>;
+  /** Batch size for remote reporting */
+  batchSize?: number;
+  /** Flush interval for batched reporting in milliseconds */
+  flushInterval?: number;
+  /** Whether to aggregate statistics */
+  aggregateStats?: boolean;
+  /** Aggregation interval in milliseconds */
+  aggregationInterval?: number;
+}
+/**
+ * Usage storage interface
+ */
+interface IUsageStorage {
+  save(entry: IUsageStats): Promise<void>;
+  getStats(conversationId?: string, timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IUsageStats[]>;
+  getAggregatedStats(timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IAggregatedUsageStats>;
+  clear(): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+/**
+ * Usage plugin statistics
+ */
+interface IUsagePluginStats extends IPluginStats {
+  /** Total number of usage entries tracked */
+  entriesTracked: number;
+  /** Total tokens tracked */
+  totalTokens: number;
+  /** Total cost tracked */
+  totalCost: number;
+  /** Current tracking strategy */
+  strategy: TUsageTrackingStrategy;
+  /** Last tracking timestamp */
+  lastTrackTime?: Date;
+  /** Number of failed tracking attempts */
+  failedTracking: number;
+}
+//#endregion
+//#region src/usage/usage-plugin.d.ts
+/**
+ * Tracks token usage, request counts, and costs across agent executions.
+ *
+ * Supports memory, file, remote, and silent storage strategies. When
+ * {@link IUsagePluginOptions.trackCosts | trackCosts} is enabled, per-model
+ * cost rates are applied automatically. Periodic aggregation can be enabled
+ * via {@link IUsagePluginOptions.aggregateStats | aggregateStats}.
+ *
+ * Lifecycle hooks used: {@link AbstractPlugin.onModuleEvent | onModuleEvent}
+ *
+ * @extends AbstractPlugin
+ * @see IUsageStorage - storage backend contract
+ * @see IUsagePluginOptions - configuration options
+ *
+ * @example
+ * ```ts
+ * const plugin = new UsagePlugin({
+ *   strategy: 'memory',
+ *   trackCosts: true,
+ *   costRates: { 'gpt-4': { input: 0.03, output: 0.06 } },
+ * });
+ * await plugin.recordUsage({ provider: 'openai', model: 'gpt-4', ... });
+ * ```
+ */
+declare class UsagePlugin extends AbstractPlugin<IUsagePluginOptions, IUsagePluginStats> {
+  name: string;
+  version: string;
+  private storage;
+  private pluginOptions;
+  private logger;
+  private aggregationTimer?;
+  constructor(options: IUsagePluginOptions);
+  /**
+   * Records usage statistics from module lifecycle events (completion and
+   * error events). Duration-bearing events are recorded with zero token
+   * counts as module events do not involve LLM calls.
+   */
+  onModuleEvent(eventName: TEventName, eventData: IEventEmitterEventData): Promise<void>;
+  private recordModuleUsage;
+  /**
+   * Records a usage entry, calculating cost if cost tracking is enabled and
+   * a rate is configured for the model.
+   * @throws PluginError if the storage write fails
+   */
+  recordUsage(usage: Omit<IUsageStats, 'timestamp' | 'cost'>): Promise<void>;
+  /**
+   * Retrieves usage entries, optionally filtered by conversation and time range.
+   * @throws PluginError if the storage read fails
+   */
+  getUsageStats(conversationId?: string, timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IUsageStats[]>;
+  /**
+   * Returns aggregated totals (requests, tokens, cost, success rate) across
+   * all recorded usage entries within the optional time range.
+   * @throws PluginError if the storage aggregation fails
+   */
+  getAggregatedStats(timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IAggregatedUsageStats>;
+  clearStats(): Promise<void>;
+  flush(): Promise<void>;
+  /**
+   * Stops the aggregation timer and closes the underlying storage.
+   */
+  destroy(): Promise<void>;
+  private createStorage;
+  private setupAggregation;
+}
+//#endregion
+//#region src/usage/aggregate-usage-stats.d.ts
+interface IUsageTimeRange {
+  start: Date;
+  end: Date;
+}
+/**
+ * Aggregate usage statistics into a single summary object.
+ * This is a shared SSOT utility (composition over inheritance).
+ */
+declare function aggregateUsageStats(stats: readonly IUsageStats[], timeRange?: IUsageTimeRange): IAggregatedUsageStats;
+//#endregion
+//#region src/usage/storages/memory-storage.d.ts
+/**
+ * Memory storage implementation for usage statistics
+ */
+declare class MemoryUsageStorage implements IUsageStorage {
+  private entries;
+  private maxEntries;
+  constructor(maxEntries?: number);
+  save(entry: IUsageStats): Promise<void>;
+  getStats(conversationId?: string, timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IUsageStats[]>;
+  getAggregatedStats(timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IAggregatedUsageStats>;
+  clear(): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/usage/storages/file-storage.d.ts
+/**
+ * File storage implementation for usage statistics
+ */
+declare class FileUsageStorage implements IUsageStorage {
+  private filePath;
+  private logger;
+  constructor(filePath: string);
+  save(entry: IUsageStats): Promise<void>;
+  getStats(conversationId?: string, timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IUsageStats[]>;
+  getAggregatedStats(timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IAggregatedUsageStats>;
+  clear(): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/usage/storages/remote-storage.d.ts
+/**
+ * Remote storage implementation for usage statistics with batching
+ */
+declare class RemoteUsageStorage implements IUsageStorage {
+  private apiUrl;
+  private batchSize;
+  private flushInterval;
+  private batch;
+  private timer?;
+  private logger;
+  constructor(apiUrl: string, _apiKey: string, _timeout: number, _headers?: Record<string, string>, batchSize?: number, flushInterval?: number);
+  save(entry: IUsageStats): Promise<void>;
+  getStats(conversationId?: string, timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IUsageStats[]>;
+  getAggregatedStats(timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IAggregatedUsageStats>;
+  clear(): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/usage/storages/silent-storage.d.ts
+/**
+ * Silent storage implementation for usage statistics (no-op)
+ */
+declare class SilentUsageStorage implements IUsageStorage {
+  save(_entry: IUsageStats): Promise<void>;
+  getStats(_conversationId?: string, _timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IUsageStats[]>;
+  getAggregatedStats(_timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IAggregatedUsageStats>;
+  clear(): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/webhook/types.d.ts
+/**
+ * Webhook plugin type definitions
+ * Clean separation of concerns with domain-specific types
+ */
+type TWebhookEventName = TExecutionEventName | 'conversation.complete' | 'tool.executed' | 'error.occurred' | 'custom';
+/**
+ * Base webhook context data
+ */
+interface IWebhookContextData {
+  executionId?: string | undefined;
+  sessionId?: string | undefined;
+  userId?: string | undefined;
+}
+/**
+ * Execution result data for webhooks
+ */
+interface IWebhookExecutionData {
+  response?: string | undefined;
+  duration?: number | undefined;
+  tokensUsed?: number | undefined;
+  toolsExecuted?: number | undefined;
+  success?: boolean | undefined;
+}
+/**
+ * Conversation result data for webhooks
+ */
+interface IWebhookConversationData {
+  response?: string | undefined;
+  tokensUsed?: number | undefined;
+  toolCalls?: IWebhookToolCallData[] | undefined;
+}
+/**
+ * Tool call data for webhooks
+ */
+interface IWebhookToolCallData {
+  id: string;
+  name: string;
+  arguments: string;
+  result: string;
+}
+/**
+ * Tool execution data for webhooks
+ */
+interface IWebhookToolData {
+  name: string;
+  id: string;
+  success: boolean;
+  duration?: number | undefined;
+  result?: string | undefined;
+  error?: string | undefined;
+}
+/**
+ * Error data for webhooks
+ */
+interface IWebhookErrorData {
+  message: string;
+  stack?: string | undefined;
+  context?: Record<string, string | number | boolean> | undefined;
+  type?: string | undefined;
+}
+/**
+ * Complete webhook event data structure
+ */
+interface IWebhookEventData extends IWebhookContextData {
+  result?: IWebhookExecutionData | undefined;
+  conversation?: IWebhookConversationData | undefined;
+  tool?: IWebhookToolData | undefined;
+  error?: IWebhookErrorData | undefined;
+}
+/**
+ * Webhook metadata for additional context
+ */
+type TWebhookMetadata = Record<string, string | number | boolean | Date | string[]>;
+/**
+ * Webhook execution context (simplified from base types)
+ */
+interface IWebhookExecutionContext {
+  executionId?: string | undefined;
+  sessionId?: string | undefined;
+  userId?: string | undefined;
+}
+/**
+ * Webhook execution result (simplified from base types)
+ */
+interface IWebhookExecutionResult {
+  response?: string | undefined;
+  content?: string | undefined;
+  duration?: number | undefined;
+  tokensUsed?: number | undefined;
+  toolsExecuted?: number | undefined;
+  success?: boolean | undefined;
+  usage?: {
+    totalTokens?: number | undefined;
+  } | undefined;
+  toolCalls?: import('@robota-sdk/agent-core').IPluginExecutionResult['toolCalls'];
+  results?: Array<{
+    toolName?: string | undefined;
+    toolId?: string | undefined;
+    executionId?: string | undefined;
+    error?: Error | undefined;
+    duration?: number | undefined;
+    result?: string | number | boolean | undefined;
+  }> | undefined;
+  error?: Error | undefined;
+}
+/**
+ * Webhook payload structure
+ */
+interface IWebhookPayload {
+  event: TWebhookEventName;
+  timestamp: string;
+  executionId?: string;
+  sessionId?: string;
+  userId?: string;
+  data: IWebhookEventData;
+  metadata?: TWebhookMetadata;
+}
+/**
+ * Webhook endpoint configuration
+ */
+interface IWebhookEndpoint {
+  url: string;
+  headers?: Record<string, string>;
+  events?: TWebhookEventName[];
+  retries?: number;
+  timeout?: number;
+  secret?: string;
+}
+/**
+ * Webhook plugin configuration options
+ */
+interface IWebhookPluginOptions extends IPluginOptions {
+  /** Webhook endpoints */
+  endpoints: IWebhookEndpoint[];
+  /** Events to send webhooks for */
+  events?: TWebhookEventName[];
+  /** Default timeout for webhook requests */
+  defaultTimeout?: number;
+  /** Default retry attempts */
+  defaultRetries?: number;
+  /** Whether to use async sending */
+  async?: boolean;
+  /** Maximum concurrent webhook requests */
+  maxConcurrency?: number;
+  /** Whether to batch webhook requests */
+  batching?: {
+    enabled: boolean;
+    maxSize: number;
+    flushInterval: number;
+  };
+  /** Custom payload transformer */
+  payloadTransformer?: (event: TWebhookEventName, data: IWebhookEventData) => IWebhookEventData;
+}
+/**
+ * Webhook plugin statistics
+ */
+interface IWebhookPluginStats extends IPluginStats {
+  endpointCount: number;
+  queueLength: number;
+  batchQueueLength: number;
+  activeConcurrency: number;
+  supportedEvents: TWebhookEventName[];
+  totalSent: number;
+  totalErrors: number;
+  averageResponseTime: number;
+}
+/**
+ * Internal webhook request structure
+ */
+interface IWebhookRequest {
+  endpoint: IWebhookEndpoint;
+  payload: IWebhookPayload;
+  attempt: number;
+  timestamp: Date;
+}
+//#endregion
+//#region src/webhook/webhook-plugin.d.ts
+/**
+ * Sends HTTP webhook notifications for agent execution lifecycle events.
+ *
+ * Routes events to configured {@link IWebhookEndpoint | endpoints} with
+ * optional event filtering per endpoint. Supports asynchronous delivery with
+ * configurable concurrency, automatic retries via {@link WebhookHttpClient},
+ * and optional payload batching.
+ *
+ * Lifecycle hooks used: {@link AbstractPlugin.afterExecution | afterExecution},
+ * {@link AbstractPlugin.afterConversation | afterConversation},
+ * {@link AbstractPlugin.afterToolExecution | afterToolExecution},
+ * {@link AbstractPlugin.onError | onError}
+ *
+ * @extends AbstractPlugin
+ * @see IWebhookPluginOptions - configuration options
+ * @see WebhookTransformer - payload transformation utilities
+ * @see WebhookHttpClient - HTTP delivery client
+ *
+ * @example
+ * ```ts
+ * const plugin = new WebhookPlugin({
+ *   endpoints: [{ url: 'https://example.com/hook' }],
+ *   async: true,
+ *   maxConcurrency: 3,
+ * });
+ * ```
+ */
+declare class WebhookPlugin extends AbstractPlugin<IWebhookPluginOptions, IWebhookPluginStats> {
+  name: string;
+  version: string;
+  private pluginOptions;
+  private logger;
+  private queue;
+  constructor(options: IWebhookPluginOptions);
+  /**
+   * Sends an execution-complete webhook after the agent finishes processing.
+   */
+  afterExecution(context: IPluginExecutionContext, result: IPluginExecutionResult): Promise<void>;
+  /**
+   * Sends a conversation-complete webhook after a conversation round finishes.
+   */
+  afterConversation(context: IPluginExecutionContext, result: IPluginExecutionResult): Promise<void>;
+  /**
+   * Sends a tool-executed webhook for each tool call in the result set.
+   */
+  afterToolExecution(context: IPluginExecutionContext, toolResults: IPluginExecutionResult): Promise<void>;
+  /**
+   * Sends both an error-occurred and execution-error webhook on failure.
+   */
+  onError(error: Error, context?: IPluginErrorContext): Promise<void>;
+  /**
+   * Builds a webhook payload and delivers it to all matching endpoints. When
+   * batching is enabled, payloads are queued and flushed at the configured interval.
+   */
+  sendWebhook(event: TWebhookEventName, data: IWebhookEventData, metadata?: TWebhookMetadata): Promise<void>;
+  /**
+   * Sends a webhook with the `custom` event type.
+   */
+  sendCustomWebhook(data: IWebhookEventData, metadata?: TWebhookMetadata): Promise<void>;
+  /**
+   * Get webhook plugin statistics
+   */
+  getStats(): IWebhookPluginStats;
+  /**
+   * Clear webhook queue
+   */
+  clearQueue(): void;
+  /**
+   * Flushes pending batches, clears request queues, and stops the batch timer.
+   */
+  destroy(): Promise<void>;
+  private getEndpointsForEvent;
+}
+//#endregion
+//#region src/webhook/transformer.d.ts
+/**
+ * Webhook data transformer utility class
+ */
+declare class WebhookTransformer {
+  /**
+   * Convert IPluginExecutionContext to WebhookExecutionContext
+   */
+  static contextToWebhook(context: IPluginExecutionContext): IWebhookExecutionContext;
+  /**
+   * Convert IPluginExecutionResult to WebhookExecutionResult
+   */
+  static resultToWebhook(result: IPluginExecutionResult): IWebhookExecutionResult;
+  /**
+   * Create execution event data
+   */
+  static createExecutionData(context: IWebhookExecutionContext, result: IWebhookExecutionResult): IWebhookEventData;
+  /**
+   * Create conversation event data
+   */
+  static createConversationData(context: IWebhookExecutionContext, result: IWebhookExecutionResult): IWebhookEventData;
+  /**
+   * Create tool execution event data
+   *
+   * REASON: Tool result structure varies by tool type and provider, needs flexible handling for webhook processing
+   * ALTERNATIVES_CONSIDERED:
+   * 1. Strict tool result interfaces (breaks tool compatibility)
+   * 2. Union types (insufficient for dynamic tool results)
+   * 3. Generic constraints (too complex for webhook processing)
+   * 4. Interface definitions (too rigid for varied tool results)
+   * 5. Type assertions (decreases type safety)
+   * TODO: Consider standardized tool result interface across tools
+   */
+  static createToolData(context: IWebhookExecutionContext, toolResult: TLoggerData): IWebhookEventData;
+  /**
+   * Create error event data
+   */
+  static createErrorData(context: IWebhookExecutionContext, error: Error): IWebhookEventData;
+  /**
+   * Safely get property from object (handles index signature issues)
+   *
+   * REASON: Safe property access for webhook data transformation needs flexible input/output types
+   * ALTERNATIVES_CONSIDERED:
+   * 1. Strict object types (breaks dynamic property access)
+   * 2. Union types (insufficient for property extraction)
+   * 3. Generic constraints (too complex for simple property access)
+   * 4. Interface definitions (too rigid for dynamic objects)
+   * 5. Type assertions (decreases type safety)
+   * TODO: Consider typed property access if patterns emerge
+   */
+  private static safeGetProperty;
+  /**
+   * Default payload transformer for webhook events
+   */
+  static defaultPayloadTransformer(_event: TWebhookEventName, data: IWebhookEventData): IWebhookEventData;
+}
+//#endregion
+//#region src/webhook/http-client.d.ts
+/**
+ * HTTP client for webhook requests
+ */
+declare class WebhookHttpClient {
+  private logger;
+  constructor(logger: ILogger);
+  /**
+   * Send a single webhook request with retries
+   */
+  sendRequest(request: IWebhookRequest): Promise<void>;
+  /**
+   * Generate HMAC signature for webhook security using jsSHA (browser compatible)
+   */
+  private generateSignature;
+  /**
+   * Make HTTP request with timeout support
+   */
+  private makeHttpRequest;
+  /**
+   * Delay utility for retry backoff
+   */
+  private delay;
+}
+//#endregion
+export { ConsoleLogFormatter, ConsoleLogStorage, ConversationHistoryPlugin, DatabaseHistoryStorage, ErrorHandlingPlugin, ExecutionAnalyticsPlugin, FileHistoryStorage, FileLogStorage, FileUsageStorage, type IAggregatedExecutionStats, type IAggregatedPerformanceStats, type IAggregatedUsageStats, type IConversationHistoryEntry, type IConversationHistoryPluginOptions, type IConversationHistoryPluginStats, type IErrorContextAdapter, type IErrorHandlingContextData, type IErrorHandlingPluginOptions, type IErrorHandlingPluginStats, type IExecutionAnalyticsContextData, type IExecutionAnalyticsOptions, type IExecutionAnalyticsPluginStats, type IExecutionStats, type IHistoryStorage, type ILimitWindow, type ILimitsPluginExecutionContext, type ILimitsPluginExecutionResult, type ILimitsPluginOptions, type ILogEntry, type ILogFormatter, type ILogStorage, type ILoggingPluginOptions, type ILoggingPluginStats, type IPerformanceMetrics, type IPerformancePluginOptions, type IPerformancePluginStats, type IPerformanceStorage, type ISystemMetricsCollector, type ITokenBucket, type IUsagePluginOptions, type IUsagePluginStats, type IUsageStats, type IUsageStorage, type IWebhookEndpoint, type IWebhookPayload, type IWebhookPluginOptions, JsonLogFormatter, LimitsPlugin, LoggingPlugin, MemoryHistoryStorage, MemoryPerformanceStorage, MemoryUsageStorage, NodeSystemMetricsCollector, PerformancePlugin, RemoteLogStorage, RemoteUsageStorage, SilentLogStorage, SilentUsageStorage, type TErrorHandlingStrategy, type THistoryStorageStrategy, type TLimitsStrategy, type TLogLevel, type TLoggingStrategy, type TPerformanceMonitoringStrategy, type TPluginLimitsStatusData, type TUsageTrackingStrategy, type TWebhookEventName, UsagePlugin, WebhookHttpClient, WebhookPlugin, WebhookTransformer, aggregateExecutionStats, aggregateUsageStats, createPluginErrorContext, toErrorContext };
+//# sourceMappingURL=index.d.ts.map