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

package/src/performance/performance-plugin.ts

@@ -0,0 +1,274 @@
+import {
+  AbstractPlugin,
+  PluginCategory,
+  PluginPriority,
+  createLogger,
+  type ILogger,
+  PluginError,
+  type IEventEmitterEventData,
+  type TEventName,
+} from '@robota-sdk/agent-core';
+import {
+  IPerformanceMetrics,
+  IAggregatedPerformanceStats,
+  IPerformancePluginOptions,
+  IPerformancePluginStats,
+  IPerformanceStorage,
+  ISystemMetricsCollector,
+} from './types';
+import { NodeSystemMetricsCollector } from './collectors/system-metrics-collector';
+import {
+  validatePerformanceOptions,
+  createPerformanceStorage,
+  extractPerformanceModuleData,
+  PERFORMANCE_MODULE_EVENT_MAP,
+} from './performance-helpers';
+
+const DEFAULT_MAX_ENTRIES = 5000;
+const DEFAULT_BATCH_SIZE = 100;
+const DEFAULT_FLUSH_INTERVAL_MS = 30000;
+const DEFAULT_AGGREGATION_INTERVAL_MS = 60000;
+const DEFAULT_PERFORMANCE_THRESHOLD_MS = 1000;
+
+/**
+ * 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 });
+ * ```
+ */
+export class PerformancePlugin extends AbstractPlugin<
+  IPerformancePluginOptions,
+  IPerformancePluginStats
+> {
+  name = 'PerformancePlugin';
+  version = '1.0.0';
+
+  private storage: IPerformanceStorage;
+  private metricsCollector: ISystemMetricsCollector;
+  private pluginOptions: Required<IPerformancePluginOptions>;
+  private logger: ILogger;
+
+  constructor(options: IPerformancePluginOptions) {
+    super();
+    this.logger = createLogger('PerformancePlugin');
+
+    // Set plugin classification
+    this.category = PluginCategory.MONITORING;
+    this.priority = PluginPriority.NORMAL;
+
+    // Validate options
+    validatePerformanceOptions(options);
+
+    // Set defaults
+    this.pluginOptions = {
+      enabled: options.enabled ?? true,
+      strategy: options.strategy,
+      filePath: options.filePath ?? './performance-metrics.json',
+      remoteEndpoint: options.remoteEndpoint ?? '',
+      prometheusEndpoint: options.prometheusEndpoint ?? '/metrics',
+      remoteHeaders: options.remoteHeaders ?? {},
+      maxEntries: options.maxEntries ?? DEFAULT_MAX_ENTRIES,
+      monitorMemory: options.monitorMemory ?? true,
+      monitorCPU: options.monitorCPU ?? true,
+      monitorNetwork: options.monitorNetwork ?? false,
+      batchSize: options.batchSize ?? DEFAULT_BATCH_SIZE,
+      flushInterval: options.flushInterval ?? DEFAULT_FLUSH_INTERVAL_MS,
+      aggregateStats: options.aggregateStats ?? true,
+      aggregationInterval: options.aggregationInterval ?? DEFAULT_AGGREGATION_INTERVAL_MS,
+      performanceThreshold: options.performanceThreshold ?? DEFAULT_PERFORMANCE_THRESHOLD_MS,
+      // Add plugin options defaults
+      category: options.category ?? PluginCategory.MONITORING,
+      priority: options.priority ?? PluginPriority.NORMAL,
+      moduleEvents: options.moduleEvents ?? [],
+      subscribeToAllModuleEvents: options.subscribeToAllModuleEvents ?? false,
+    };
+
+    // Initialize storage and metrics collector
+    this.storage = createPerformanceStorage(
+      this.pluginOptions.strategy,
+      this.pluginOptions.maxEntries,
+    );
+    this.metricsCollector = new NodeSystemMetricsCollector();
+
+    this.logger.info('PerformancePlugin initialized', {
+      strategy: this.pluginOptions.strategy,
+      monitorMemory: this.pluginOptions.monitorMemory,
+      monitorCPU: this.pluginOptions.monitorCPU,
+      performanceThreshold: this.pluginOptions.performanceThreshold,
+    });
+  }
+
+  /**
+   * Records performance metrics from module lifecycle events
+   * (initialization, execution, disposal) including duration and error counts.
+   */
+  override async onModuleEvent(
+    eventName: TEventName,
+    eventData: IEventEmitterEventData,
+  ): Promise<void> {
+    try {
+      const descriptor = PERFORMANCE_MODULE_EVENT_MAP.get(eventName);
+      if (!descriptor) return;
+
+      const { moduleName, moduleType, duration, success } = extractPerformanceModuleData(
+        eventData.data,
+      );
+      if (duration === undefined) return;
+
+      await this.recordMetrics({
+        operation: descriptor.operation,
+        duration,
+        success: descriptor.isError ? false : (success ?? true),
+        errorCount: descriptor.isError ? 1 : 0,
+        ...(eventData.executionId && { executionId: eventData.executionId }),
+        metadata: {
+          moduleName,
+          moduleType,
+          phase: descriptor.phase,
+          ...(descriptor.isError && { error: eventData.error?.message || 'unknown error' }),
+        },
+      });
+    } catch (_error) {
+      // Swallow to avoid breaking module event processing
+    }
+  }
+
+  /**
+   * 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
+   */
+  async recordMetrics(
+    metrics: Omit<IPerformanceMetrics, 'timestamp' | 'memoryUsage' | 'cpuUsage' | 'networkStats'>,
+  ): Promise<void> {
+    try {
+      const memoryUsage = this.pluginOptions.monitorMemory
+        ? await this.metricsCollector.getMemoryUsage()
+        : undefined;
+      const cpuUsage = this.pluginOptions.monitorCPU
+        ? await this.metricsCollector.getCPUUsage()
+        : undefined;
+      const networkStats = this.pluginOptions.monitorNetwork
+        ? await this.metricsCollector.getNetworkStats()
+        : undefined;
+
+      const entry: IPerformanceMetrics = {
+        ...metrics,
+        timestamp: new Date(),
+        ...(memoryUsage && { memoryUsage }),
+        ...(cpuUsage && { cpuUsage }),
+        ...(networkStats && { networkStats }),
+      };
+
+      await this.storage.save(entry);
+
+      // Log warning if performance threshold exceeded
+      if (entry.duration > this.pluginOptions.performanceThreshold) {
+        this.logger.warn('Performance threshold exceeded', {
+          operation: entry.operation,
+          duration: entry.duration,
+          threshold: this.pluginOptions.performanceThreshold,
+          executionId: entry.executionId,
+        });
+      }
+
+      this.logger.debug('Performance metrics recorded', {
+        operation: entry.operation,
+        duration: entry.duration,
+        success: entry.success,
+        memoryUsed: entry.memoryUsage?.heap.used,
+      });
+    } catch (error) {
+      throw new PluginError('Failed to record performance metrics', this.name, {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Retrieves recorded metrics, optionally filtered by operation name and time range.
+   * @throws PluginError if the storage read fails
+   */
+  async getMetrics(
+    operation?: string,
+    timeRange?: { start: Date; end: Date },
+  ): Promise<IPerformanceMetrics[]> {
+    try {
+      return await this.storage.getMetrics(operation, timeRange);
+    } catch (error) {
+      throw new PluginError('Failed to get performance metrics', this.name, {
+        operation: operation || 'all',
+        timeRange: timeRange
+          ? `${timeRange.start.toISOString()}-${timeRange.end.toISOString()}`
+          : 'all',
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Get aggregated performance statistics
+   */
+  async getAggregatedStats(timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IAggregatedPerformanceStats> {
+    try {
+      return await this.storage.getAggregatedStats(timeRange);
+    } catch (error) {
+      throw new PluginError('Failed to get aggregated performance stats', this.name, {
+        timeRange: timeRange
+          ? `${timeRange.start.toISOString()}-${timeRange.end.toISOString()}`
+          : 'all',
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Clear all performance metrics
+   */
+  async clearMetrics(): Promise<void> {
+    try {
+      await this.storage.clear();
+      this.logger.info('Performance metrics cleared');
+    } catch (error) {
+      throw new PluginError('Failed to clear performance metrics', this.name, {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Closes the underlying storage and releases resources.
+   */
+  async destroy(): Promise<void> {
+    try {
+      await this.storage.close();
+      this.logger.info('PerformancePlugin destroyed');
+    } catch (error) {
+      this.logger.error('Error during plugin cleanup', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+}

package/src/performance/storages/index.ts

@@ -0,0 +1 @@
+export { MemoryPerformanceStorage } from './memory-storage';

package/src/performance/storages/memory-storage.ts

@@ -0,0 +1,88 @@
+import { IPerformanceStorage, IPerformanceMetrics, IAggregatedPerformanceStats } from '../types';
+
+export class MemoryPerformanceStorage implements IPerformanceStorage {
+  private entries: IPerformanceMetrics[] = [];
+  private maxEntries: number;
+
+  constructor(maxEntries: number = 5000) {
+    this.maxEntries = maxEntries;
+  }
+
+  async save(entry: IPerformanceMetrics): Promise<void> {
+    if (this.entries.length >= this.maxEntries) {
+      this.entries = this.entries.slice(-this.maxEntries + 1);
+    }
+    this.entries.push({ ...entry });
+  }
+
+  async getMetrics(
+    operation?: string,
+    timeRange?: { start: Date; end: Date },
+  ): Promise<IPerformanceMetrics[]> {
+    let filtered = [...this.entries];
+    if (operation) {
+      filtered = filtered.filter((entry) => entry.operation === operation);
+    }
+    if (timeRange) {
+      filtered = filtered.filter(
+        (entry) => entry.timestamp >= timeRange.start && entry.timestamp <= timeRange.end,
+      );
+    }
+    return filtered;
+  }
+
+  async getAggregatedStats(timeRange?: {
+    start: Date;
+    end: Date;
+  }): Promise<IAggregatedPerformanceStats> {
+    const metrics = await this.getMetrics(undefined, timeRange);
+
+    if (metrics.length === 0) {
+      return {
+        totalOperations: 0,
+        averageDuration: 0,
+        minDuration: 0,
+        maxDuration: 0,
+        successRate: 0,
+        errorRate: 0,
+        operationStats: {},
+        timeRangeStats: {
+          startTime: timeRange?.start || new Date(),
+          endTime: timeRange?.end || new Date(),
+          period: 'empty',
+        },
+      };
+    }
+
+    const durations = metrics.map((m) => m.duration);
+    const successCount = metrics.filter((m) => m.success).length;
+    const errorCount = metrics.reduce((sum, m) => sum + m.errorCount, 0);
+
+    return {
+      totalOperations: metrics.length,
+      averageDuration: durations.reduce((sum, d) => sum + d, 0) / durations.length,
+      minDuration: Math.min(...durations),
+      maxDuration: Math.max(...durations),
+      successRate: successCount / metrics.length,
+      errorRate: errorCount / metrics.length,
+      operationStats: {},
+      timeRangeStats: {
+        startTime: timeRange?.start || metrics[0]?.timestamp || new Date(),
+        endTime: timeRange?.end || metrics[metrics.length - 1]?.timestamp || new Date(),
+        period: 'memory',
+      },
+    };
+  }
+
+  async clear(): Promise<void> {
+    this.entries = [];
+  }
+
+  async flush(): Promise<void> {
+    // Memory storage doesn't need flushing
+  }
+
+  async close(): Promise<void> {
+    // Memory storage doesn't need closing
+  }
+}

package/src/performance/types.ts

@@ -0,0 +1,160 @@
+/**
+ * Performance monitoring strategy types
+ */
+export type TPerformanceMonitoringStrategy = 'memory' | 'file' | 'prometheus' | 'remote' | 'silent';
+
+/**
+ * Performance metrics entry
+ */
+export interface IPerformanceMetrics {
+  executionId?: string;
+  conversationId?: string;
+  timestamp: Date;
+  operation: string; // 'conversation', 'tool_execution', 'provider_call', etc.
+  duration: number; // in milliseconds
+  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
+ */
+export 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;
+  };
+}
+
+import type { IPluginOptions, IPluginStats } from '@robota-sdk/agent-core';
+
+/**
+ * Configuration options for performance plugin
+ */
+export 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
+ */
+export 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
+ */
+export interface ISystemMetricsCollector {
+  getMemoryUsage(): Promise<IPerformanceMetrics['memoryUsage']>;
+  getCPUUsage(): Promise<IPerformanceMetrics['cpuUsage']>;
+  getNetworkStats(): Promise<IPerformanceMetrics['networkStats']>;
+}
+
+/**
+ * Performance plugin statistics
+ */
+export 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;
+}

package/src/usage/__tests__/aggregate-usage-stats.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from 'vitest';
+import { aggregateUsageStats } from '../aggregate-usage-stats';
+import type { IUsageStats } from '../types';
+
+function makeEntry(overrides: Partial<IUsageStats> = {}): IUsageStats {
+  return {
+    provider: 'openai',
+    model: 'gpt-4',
+    tokensUsed: { input: 100, output: 50, total: 150 },
+    requestCount: 1,
+    duration: 500,
+    success: true,
+    timestamp: new Date('2025-01-01T10:00:00Z'),
+    ...overrides,
+  };
+}
+
+describe('aggregateUsageStats', () => {
+  it('returns empty aggregation for no entries', () => {
+    const result = aggregateUsageStats([]);
+    expect(result.totalRequests).toBe(0);
+    expect(result.totalTokens).toBe(0);
+    expect(result.totalCost).toBe(0);
+    expect(result.successRate).toBe(0);
+    expect(result.timeRangeStats.period).toBe('all');
+  });
+
+  it('aggregates single entry correctly', () => {
+    const entry = makeEntry({ cost: { input: 1, output: 2, total: 3 } });
+    const result = aggregateUsageStats([entry]);
+    expect(result.totalRequests).toBe(1);
+    expect(result.totalTokens).toBe(150);
+    expect(result.totalCost).toBe(3);
+    expect(result.totalDuration).toBe(500);
+    expect(result.successRate).toBe(1);
+  });
+
+  it('aggregates multiple entries', () => {
+    const entries = [
+      makeEntry({ success: true }),
+      makeEntry({
+        provider: 'anthropic',
+        model: 'claude-3',
+        success: false,
+        tokensUsed: { input: 200, output: 100, total: 300 },
+      }),
+    ];
+    const result = aggregateUsageStats(entries);
+    expect(result.totalRequests).toBe(2);
+    expect(result.totalTokens).toBe(450);
+    expect(result.successRate).toBe(0.5);
+  });
+
+  it('aggregates by provider', () => {
+    const entries = [
+      makeEntry({
+        provider: 'openai',
+        requestCount: 1,
+        tokensUsed: { input: 100, output: 50, total: 150 },
+      }),
+      makeEntry({
+        provider: 'openai',
+        requestCount: 2,
+        tokensUsed: { input: 200, output: 100, total: 300 },
+      }),
+      makeEntry({
+        provider: 'anthropic',
+        requestCount: 1,
+        tokensUsed: { input: 50, output: 25, total: 75 },
+      }),
+    ];
+    const result = aggregateUsageStats(entries);
+    expect(result.providerStats['openai']?.requests).toBe(3);
+    expect(result.providerStats['openai']?.tokens).toBe(450);
+    expect(result.providerStats['anthropic']?.requests).toBe(1);
+  });
+
+  it('aggregates by model', () => {
+    const entries = [
+      makeEntry({ model: 'gpt-4', requestCount: 1 }),
+      makeEntry({ model: 'gpt-3.5', requestCount: 2 }),
+    ];
+    const result = aggregateUsageStats(entries);
+    expect(result.modelStats['gpt-4']?.requests).toBe(1);
+    expect(result.modelStats['gpt-3.5']?.requests).toBe(2);
+  });
+
+  it('aggregates by tools', () => {
+    const entries = [
+      makeEntry({ toolsUsed: ['search', 'calc'], success: true, duration: 100 }),
+      makeEntry({ toolsUsed: ['search'], success: false, duration: 200 }),
+    ];
+    const result = aggregateUsageStats(entries);
+    expect(result.toolStats['search']?.usageCount).toBe(2);
+    expect(result.toolStats['search']?.successCount).toBe(1);
+    expect(result.toolStats['calc']?.usageCount).toBe(1);
+  });
+
+  it('determines period from time range', () => {
+    const now = new Date();
+    const halfHourAgo = new Date(now.getTime() - 30 * 60 * 1000);
+    const result = aggregateUsageStats([], { start: halfHourAgo, end: now });
+    expect(result.timeRangeStats.period).toBe('hour');
+  });
+
+  it('determines day period', () => {
+    const now = new Date();
+    const sixHoursAgo = new Date(now.getTime() - 6 * 60 * 60 * 1000);
+    const result = aggregateUsageStats([], { start: sixHoursAgo, end: now });
+    expect(result.timeRangeStats.period).toBe('day');
+  });
+
+  it('determines week period', () => {
+    const now = new Date();
+    const threeDaysAgo = new Date(now.getTime() - 3 * 24 * 60 * 60 * 1000);
+    const result = aggregateUsageStats([], { start: threeDaysAgo, end: now });
+    expect(result.timeRangeStats.period).toBe('week');
+  });
+
+  it('determines month period', () => {
+    const now = new Date();
+    const twoWeeksAgo = new Date(now.getTime() - 14 * 24 * 60 * 60 * 1000);
+    const result = aggregateUsageStats([], { start: twoWeeksAgo, end: now });
+    expect(result.timeRangeStats.period).toBe('month');
+  });
+
+  it('uses entry timestamps when no time range given', () => {
+    const entries = [
+      makeEntry({ timestamp: new Date('2025-01-01') }),
+      makeEntry({ timestamp: new Date('2025-01-05') }),
+    ];
+    const result = aggregateUsageStats(entries);
+    expect(result.timeRangeStats.startTime).toEqual(new Date('2025-01-01'));
+    expect(result.timeRangeStats.endTime).toEqual(new Date('2025-01-05'));
+  });
+});