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

package/src/logging/types.ts

@@ -0,0 +1,106 @@
+/**
+ * Logging strategy types
+ */
+export type TLoggingStrategy = 'console' | 'file' | 'remote' | 'silent';
+
+/**
+ * Log levels
+ */
+export type TLogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * Log entry structure
+ */
+export 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;
+  };
+}
+
+import type { IPluginOptions, IPluginStats, ILogger } from '@robota-sdk/agent-core';
+
+/**
+ * Configuration options for logging plugin
+ */
+export 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
+ */
+export interface ILogFormatter {
+  format(entry: ILogEntry): string;
+}
+
+/**
+ * Log storage interface
+ */
+export interface ILogStorage {
+  write(entry: ILogEntry): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+
+/** Structured context data for log entries */
+export 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
+ */
+export 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;
+}

package/src/performance/__tests__/memory-storage.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MemoryPerformanceStorage } from '../storages/memory-storage';
+import type { IPerformanceMetrics } from '../types';
+
+function makeMetric(overrides: Partial<IPerformanceMetrics> = {}): IPerformanceMetrics {
+  return {
+    operation: 'test-op',
+    duration: 100,
+    success: true,
+    errorCount: 0,
+    timestamp: new Date(),
+    ...overrides,
+  };
+}
+
+describe('MemoryPerformanceStorage', () => {
+  let storage: MemoryPerformanceStorage;
+
+  beforeEach(() => {
+    storage = new MemoryPerformanceStorage(100);
+  });
+
+  it('saves and retrieves entries', async () => {
+    await storage.save(makeMetric());
+    const metrics = await storage.getMetrics();
+    expect(metrics).toHaveLength(1);
+  });
+
+  it('evicts oldest when maxEntries exceeded', async () => {
+    storage = new MemoryPerformanceStorage(2);
+    await storage.save(makeMetric({ operation: 'first' }));
+    await storage.save(makeMetric({ operation: 'second' }));
+    await storage.save(makeMetric({ operation: 'third' }));
+    const metrics = await storage.getMetrics();
+    expect(metrics).toHaveLength(2);
+    expect(metrics.some((m) => m.operation === 'first')).toBe(false);
+  });
+
+  it('filters by operation', async () => {
+    await storage.save(makeMetric({ operation: 'op-a' }));
+    await storage.save(makeMetric({ operation: 'op-b' }));
+    const metrics = await storage.getMetrics('op-a');
+    expect(metrics).toHaveLength(1);
+    expect(metrics[0].operation).toBe('op-a');
+  });
+
+  it('filters by time range', async () => {
+    await storage.save(makeMetric({ timestamp: new Date('2024-01-01') }));
+    await storage.save(makeMetric({ timestamp: new Date('2025-06-01') }));
+    const metrics = await storage.getMetrics(undefined, {
+      start: new Date('2025-01-01'),
+      end: new Date('2026-01-01'),
+    });
+    expect(metrics).toHaveLength(1);
+  });
+
+  it('returns aggregated stats', async () => {
+    await storage.save(makeMetric({ duration: 100, success: true, errorCount: 0 }));
+    await storage.save(makeMetric({ duration: 300, success: false, errorCount: 2 }));
+    const stats = await storage.getAggregatedStats();
+    expect(stats.totalOperations).toBe(2);
+    expect(stats.averageDuration).toBe(200);
+    expect(stats.minDuration).toBe(100);
+    expect(stats.maxDuration).toBe(300);
+    expect(stats.successRate).toBe(0.5);
+    expect(stats.errorRate).toBe(1);
+  });
+
+  it('returns zeroed aggregated stats for empty data', async () => {
+    const stats = await storage.getAggregatedStats();
+    expect(stats.totalOperations).toBe(0);
+    expect(stats.averageDuration).toBe(0);
+  });
+
+  it('clear removes all entries', async () => {
+    await storage.save(makeMetric());
+    await storage.clear();
+    const metrics = await storage.getMetrics();
+    expect(metrics).toHaveLength(0);
+  });
+
+  it('flush and close are no-ops', async () => {
+    await expect(storage.flush()).resolves.toBeUndefined();
+    await expect(storage.close()).resolves.toBeUndefined();
+  });
+});

package/src/performance/__tests__/performance-plugin.test.ts

@@ -0,0 +1,208 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { PerformancePlugin } from '../performance-plugin';
+import { ConfigurationError, PluginError } from '@robota-sdk/agent-core';
+
+describe('PerformancePlugin', () => {
+  let plugin: PerformancePlugin;
+
+  afterEach(async () => {
+    if (plugin) {
+      await plugin.destroy();
+    }
+  });
+
+  describe('constructor', () => {
+    it('creates plugin with memory strategy', () => {
+      plugin = new PerformancePlugin({ strategy: 'memory' });
+      expect(plugin.name).toBe('PerformancePlugin');
+      expect(plugin.version).toBe('1.0.0');
+    });
+
+    it('throws ConfigurationError for missing strategy', () => {
+      expect(() => new PerformancePlugin({ strategy: '' as any })).toThrow(ConfigurationError);
+    });
+
+    it('throws ConfigurationError for invalid strategy', () => {
+      expect(() => new PerformancePlugin({ strategy: 'invalid' as any })).toThrow(
+        ConfigurationError,
+      );
+    });
+
+    it('throws ConfigurationError for unimplemented strategy', () => {
+      // file, prometheus, remote, silent are valid but not implemented
+      expect(() => new PerformancePlugin({ strategy: 'file' })).toThrow(ConfigurationError);
+    });
+  });
+
+  describe('recordMetrics', () => {
+    beforeEach(() => {
+      plugin = new PerformancePlugin({
+        strategy: 'memory',
+        monitorMemory: false,
+        monitorCPU: false,
+      });
+    });
+
+    it('records a metric entry', async () => {
+      await plugin.recordMetrics({
+        operation: 'test-op',
+        duration: 100,
+        success: true,
+        errorCount: 0,
+      });
+      const metrics = await plugin.getMetrics();
+      expect(metrics).toHaveLength(1);
+      expect(metrics[0].operation).toBe('test-op');
+      expect(metrics[0].duration).toBe(100);
+    });
+
+    it('records with system metrics when monitoring enabled', async () => {
+      plugin = new PerformancePlugin({
+        strategy: 'memory',
+        monitorMemory: true,
+        monitorCPU: true,
+        monitorNetwork: true,
+      });
+      await plugin.recordMetrics({
+        operation: 'test-op',
+        duration: 50,
+        success: true,
+        errorCount: 0,
+      });
+      const metrics = await plugin.getMetrics();
+      expect(metrics).toHaveLength(1);
+      // Memory and CPU should be populated from NodeSystemMetricsCollector
+      // Network will be undefined as it is not fully implemented
+    });
+  });
+
+  describe('getMetrics', () => {
+    beforeEach(async () => {
+      plugin = new PerformancePlugin({
+        strategy: 'memory',
+        monitorMemory: false,
+        monitorCPU: false,
+      });
+      await plugin.recordMetrics({
+        operation: 'op-a',
+        duration: 100,
+        success: true,
+        errorCount: 0,
+      });
+      await plugin.recordMetrics({
+        operation: 'op-b',
+        duration: 200,
+        success: false,
+        errorCount: 1,
+      });
+    });
+
+    it('returns all metrics with no filter', async () => {
+      const metrics = await plugin.getMetrics();
+      expect(metrics).toHaveLength(2);
+    });
+
+    it('filters by operation', async () => {
+      const metrics = await plugin.getMetrics('op-a');
+      expect(metrics).toHaveLength(1);
+      expect(metrics[0].operation).toBe('op-a');
+    });
+  });
+
+  describe('getAggregatedStats', () => {
+    beforeEach(async () => {
+      plugin = new PerformancePlugin({
+        strategy: 'memory',
+        monitorMemory: false,
+        monitorCPU: false,
+      });
+      await plugin.recordMetrics({ operation: 'op', duration: 100, success: true, errorCount: 0 });
+      await plugin.recordMetrics({ operation: 'op', duration: 300, success: false, errorCount: 2 });
+    });
+
+    it('aggregates correctly', async () => {
+      const stats = await plugin.getAggregatedStats();
+      expect(stats.totalOperations).toBe(2);
+      expect(stats.averageDuration).toBe(200);
+      expect(stats.minDuration).toBe(100);
+      expect(stats.maxDuration).toBe(300);
+      expect(stats.successRate).toBe(0.5);
+    });
+
+    it('returns zeroed stats for empty data', async () => {
+      await plugin.clearMetrics();
+      const stats = await plugin.getAggregatedStats();
+      expect(stats.totalOperations).toBe(0);
+      expect(stats.averageDuration).toBe(0);
+    });
+  });
+
+  describe('clearMetrics', () => {
+    it('clears all metrics', async () => {
+      plugin = new PerformancePlugin({
+        strategy: 'memory',
+        monitorMemory: false,
+        monitorCPU: false,
+      });
+      await plugin.recordMetrics({ operation: 'op', duration: 100, success: true, errorCount: 0 });
+      await plugin.clearMetrics();
+      const metrics = await plugin.getMetrics();
+      expect(metrics).toHaveLength(0);
+    });
+  });
+
+  describe('onModuleEvent', () => {
+    beforeEach(() => {
+      plugin = new PerformancePlugin({
+        strategy: 'memory',
+        monitorMemory: false,
+        monitorCPU: false,
+      });
+    });
+
+    it('records metrics from module execution complete event', async () => {
+      await plugin.onModuleEvent('module.execution.complete', {
+        type: 'module.execution.complete',
+        data: { moduleName: 'test-module', moduleType: 'processing', duration: 250, success: true },
+        timestamp: new Date(),
+      });
+      const metrics = await plugin.getMetrics();
+      expect(metrics).toHaveLength(1);
+      expect(metrics[0].operation).toBe('module_execution');
+      expect(metrics[0].duration).toBe(250);
+    });
+
+    it('records error metrics from module error events', async () => {
+      await plugin.onModuleEvent('module.execution.error', {
+        type: 'module.execution.error',
+        data: { moduleName: 'test-module', moduleType: 'processing', duration: 50 },
+        error: new Error('module failed'),
+        timestamp: new Date(),
+      });
+      const metrics = await plugin.getMetrics();
+      expect(metrics).toHaveLength(1);
+      expect(metrics[0].errorCount).toBe(1);
+      expect(metrics[0].success).toBe(false);
+    });
+
+    it('ignores unrecognized events', async () => {
+      await plugin.onModuleEvent('some.unknown.event' as any, {
+        type: 'module.execution.complete' as any,
+        data: { duration: 100 },
+        timestamp: new Date(),
+      });
+      const metrics = await plugin.getMetrics();
+      expect(metrics).toHaveLength(0);
+    });
+
+    it('ignores events without duration', async () => {
+      await plugin.onModuleEvent('module.execution.complete', {
+        type: 'module.execution.complete',
+        data: { moduleName: 'test-module', moduleType: 'processing' },
+        timestamp: new Date(),
+      });
+      const metrics = await plugin.getMetrics();
+      expect(metrics).toHaveLength(0);
+    });
+  });
+});

package/src/performance/__tests__/system-metrics-collector.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest';
+import { NodeSystemMetricsCollector } from '../collectors/system-metrics-collector';
+
+describe('NodeSystemMetricsCollector', () => {
+  const collector = new NodeSystemMetricsCollector();
+
+  describe('getMemoryUsage', () => {
+    it('returns memory usage data', async () => {
+      const usage = await collector.getMemoryUsage();
+      expect(usage).toBeDefined();
+      expect(usage!.used).toBeGreaterThan(0);
+      expect(usage!.heap.used).toBeGreaterThan(0);
+      expect(usage!.heap.total).toBeGreaterThan(0);
+    });
+  });
+
+  describe('getCPUUsage', () => {
+    it('returns CPU usage data', async () => {
+      const usage = await collector.getCPUUsage();
+      expect(usage).toBeDefined();
+      expect(typeof usage!.user).toBe('number');
+      expect(typeof usage!.system).toBe('number');
+      expect(usage!.percent).toBe(0); // Basic implementation returns 0
+    });
+  });
+
+  describe('getNetworkStats', () => {
+    it('returns undefined (not fully implemented)', async () => {
+      const stats = await collector.getNetworkStats();
+      expect(stats).toBeUndefined();
+    });
+  });
+});

package/src/performance/collectors/system-metrics-collector.ts

@@ -0,0 +1,69 @@
+import { type ISystemMetricsCollector, type IPerformanceMetrics } from '../types';
+import { createLogger, type ILogger } from '@robota-sdk/agent-core';
+
+/**
+ * Node.js system metrics collector
+ */
+export class NodeSystemMetricsCollector implements ISystemMetricsCollector {
+  private logger: ILogger;
+
+  constructor() {
+    this.logger = createLogger('NodeSystemMetricsCollector');
+  }
+
+  async getMemoryUsage(): Promise<IPerformanceMetrics['memoryUsage']> {
+    try {
+      const memoryUsage = process.memoryUsage();
+
+      // Note: This is a basic implementation for Node.js
+      // In production, you might want to use more sophisticated system monitoring libraries
+      return {
+        used: memoryUsage.rss,
+        free: 0, // Not directly available in Node.js without additional libraries
+        total: memoryUsage.rss + memoryUsage.external,
+        heap: {
+          used: memoryUsage.heapUsed,
+          total: memoryUsage.heapTotal,
+        },
+      };
+    } catch (error) {
+      this.logger.warn('Failed to get memory usage', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return undefined;
+    }
+  }
+
+  async getCPUUsage(): Promise<IPerformanceMetrics['cpuUsage']> {
+    try {
+      const cpuUsage = process.cpuUsage();
+
+      // Note: This is a basic implementation for Node.js
+      // For more accurate CPU percentage, you'd need to measure over time intervals
+      return {
+        user: cpuUsage.user,
+        system: cpuUsage.system,
+        percent: 0, // Would need time-based calculation for actual percentage
+      };
+    } catch (error) {
+      this.logger.warn('Failed to get CPU usage', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return undefined;
+    }
+  }
+
+  async getNetworkStats(): Promise<IPerformanceMetrics['networkStats']> {
+    try {
+      // Note: Network stats are not directly available in Node.js without additional monitoring
+      // This would typically require integrating with system monitoring tools or libraries
+      this.logger.warn('Network stats monitoring not fully implemented yet');
+      return undefined;
+    } catch (error) {
+      this.logger.warn('Failed to get network stats', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return undefined;
+    }
+  }
+}

package/src/performance/index.ts

@@ -0,0 +1,12 @@
+export { PerformancePlugin } from './performance-plugin';
+export { MemoryPerformanceStorage } from './storages/memory-storage';
+export { NodeSystemMetricsCollector } from './collectors/system-metrics-collector';
+export type {
+  TPerformanceMonitoringStrategy,
+  IPerformanceMetrics,
+  IAggregatedPerformanceStats,
+  IPerformancePluginOptions,
+  IPerformancePluginStats,
+  IPerformanceStorage,
+  ISystemMetricsCollector,
+} from './types';

package/src/performance/performance-helpers.ts

@@ -0,0 +1,86 @@
+/**
+ * Performance Plugin - Validation, storage factory, and module data extraction helpers.
+ *
+ * Extracted from performance-plugin.ts to keep each file under 300 lines.
+ * @internal
+ */
+
+import { ConfigurationError, EVENT_EMITTER_EVENTS } from '@robota-sdk/agent-core';
+import { MemoryPerformanceStorage } from './storages/index';
+import type { IPerformancePluginOptions, IPerformanceStorage } from './types';
+
+/** Validate PerformancePlugin constructor options. @internal */
+export function validatePerformanceOptions(options: IPerformancePluginOptions): void {
+  if (!options.strategy) {
+    throw new ConfigurationError('Performance monitoring strategy is required');
+  }
+
+  if (!['memory', 'file', 'prometheus', 'remote', 'silent'].includes(options.strategy)) {
+    throw new ConfigurationError('Invalid performance monitoring strategy', {
+      validStrategies: ['memory', 'file', 'prometheus', 'remote', 'silent'],
+      provided: options.strategy,
+    });
+  }
+}
+
+/** Create IPerformanceStorage instance for the given strategy. @internal */
+export function createPerformanceStorage(
+  strategy: string,
+  maxEntries: number,
+): IPerformanceStorage {
+  switch (strategy) {
+    case 'memory':
+      return new MemoryPerformanceStorage(maxEntries);
+    default:
+      throw new ConfigurationError('Performance monitoring strategy is not implemented', {
+        provided: strategy,
+      });
+  }
+}
+
+/** Event name → performance metrics descriptor mapping. @internal */
+export const PERFORMANCE_MODULE_EVENT_MAP: ReadonlyMap<
+  string,
+  { operation: string; phase: string; isError: boolean }
+> = new Map([
+  [
+    EVENT_EMITTER_EVENTS.MODULE_INITIALIZE_COMPLETE,
+    { operation: 'module_initialization', phase: 'initialization', isError: false },
+  ],
+  [
+    EVENT_EMITTER_EVENTS.MODULE_INITIALIZE_ERROR,
+    { operation: 'module_initialization', phase: 'initialization', isError: true },
+  ],
+  [
+    EVENT_EMITTER_EVENTS.MODULE_EXECUTION_COMPLETE,
+    { operation: 'module_execution', phase: 'execution', isError: false },
+  ],
+  [
+    EVENT_EMITTER_EVENTS.MODULE_EXECUTION_ERROR,
+    { operation: 'module_execution', phase: 'execution', isError: true },
+  ],
+  [
+    EVENT_EMITTER_EVENTS.MODULE_DISPOSE_COMPLETE,
+    { operation: 'module_disposal', phase: 'disposal', isError: false },
+  ],
+  [
+    EVENT_EMITTER_EVENTS.MODULE_DISPOSE_ERROR,
+    { operation: 'module_disposal', phase: 'disposal', isError: true },
+  ],
+]);
+
+/** Safely extract module data fields from untyped event payload. @internal */
+export function extractPerformanceModuleData(data: unknown): {
+  moduleName: string;
+  moduleType: string;
+  duration?: number;
+  success?: boolean;
+} {
+  const record = typeof data === 'object' && data !== null ? (data as Record<string, unknown>) : {};
+  return {
+    moduleName: typeof record['moduleName'] === 'string' ? record['moduleName'] : 'unknown',
+    moduleType: typeof record['moduleType'] === 'string' ? record['moduleType'] : 'unknown',
+    ...(typeof record['duration'] === 'number' && { duration: record['duration'] }),
+    ...(typeof record['success'] === 'boolean' && { success: record['success'] }),
+  };
+}