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

package/src/logging/logging-helpers.ts

@@ -0,0 +1,223 @@
+/**
+ * Logging Plugin - Validation and storage factory helpers.
+ *
+ * Extracted from logging-plugin.ts to keep each file under 300 lines.
+ * @internal
+ */
+
+import { ConfigurationError, EVENT_EMITTER_EVENTS } from '@robota-sdk/agent-core';
+import {
+  ConsoleLogStorage,
+  FileLogStorage,
+  RemoteLogStorage,
+  SilentLogStorage,
+} from './storages/index';
+import type { ILoggingPluginOptions, ILogStorage, TLogLevel, ILogEntry } from './types';
+
+/** Validate LoggingPlugin constructor options. @internal */
+export function validateLoggingOptions(options: ILoggingPluginOptions): void {
+  if (!options.strategy) {
+    throw new ConfigurationError('Logging strategy is required');
+  }
+
+  if (!['console', 'file', 'remote', 'silent'].includes(options.strategy)) {
+    throw new ConfigurationError('Invalid logging strategy', {
+      validStrategies: ['console', 'file', 'remote', 'silent'],
+      provided: options.strategy,
+    });
+  }
+
+  if (options.level && !['debug', 'info', 'warn', 'error'].includes(options.level)) {
+    throw new ConfigurationError('Invalid log level', {
+      validLevels: ['debug', 'info', 'warn', 'error'],
+      provided: options.level,
+    });
+  }
+
+  if (options.strategy === 'file' && !options.filePath) {
+    throw new ConfigurationError('File path is required for file logging strategy');
+  }
+
+  if (options.strategy === 'remote' && !options.remoteEndpoint) {
+    throw new ConfigurationError('Remote endpoint is required for remote logging strategy');
+  }
+
+  if (options.maxLogs !== undefined && options.maxLogs <= 0) {
+    throw new ConfigurationError('Max logs must be positive');
+  }
+
+  if (options.batchSize !== undefined && options.batchSize <= 0) {
+    throw new ConfigurationError('Batch size must be positive');
+  }
+
+  if (options.flushInterval !== undefined && options.flushInterval <= 0) {
+    throw new ConfigurationError('Flush interval must be positive');
+  }
+}
+
+/** Create ILogStorage instance for the given strategy. @internal */
+export function createLoggingStorage(
+  strategy: string,
+  filePath: string,
+  remoteEndpoint: string,
+  flushInterval: number,
+  formatter?: ILoggingPluginOptions['formatter'],
+): ILogStorage {
+  switch (strategy) {
+    case 'console':
+      return new ConsoleLogStorage(formatter);
+    case 'file':
+      return new FileLogStorage(filePath, formatter);
+    case 'remote':
+      return new RemoteLogStorage(remoteEndpoint, { timeout: flushInterval });
+    case 'silent':
+      return new SilentLogStorage();
+    default:
+      throw new ConfigurationError('Unknown logging strategy', { strategy });
+  }
+}
+
+/** Event name → log descriptor mapping for module lifecycle events. @internal */
+export const LOGGING_MODULE_EVENT_MAP: ReadonlyMap<
+  string,
+  { level: TLogLevel; message: string; operation: string }
+> = new Map([
+  [
+    EVENT_EMITTER_EVENTS.MODULE_INITIALIZE_START,
+    {
+      level: 'info',
+      message: 'Module initialization started',
+      operation: 'module_initialize_start',
+    },
+  ],
+  [
+    EVENT_EMITTER_EVENTS.MODULE_INITIALIZE_COMPLETE,
+    {
+      level: 'info',
+      message: 'Module initialization completed',
+      operation: 'module_initialize_complete',
+    },
+  ],
+  [
+    EVENT_EMITTER_EVENTS.MODULE_INITIALIZE_ERROR,
+    {
+      level: 'error',
+      message: 'Module initialization failed',
+      operation: 'module_initialize_error',
+    },
+  ],
+  [
+    EVENT_EMITTER_EVENTS.MODULE_EXECUTION_START,
+    { level: 'debug', message: 'Module execution started', operation: 'module_execution_start' },
+  ],
+  [
+    EVENT_EMITTER_EVENTS.MODULE_EXECUTION_COMPLETE,
+    {
+      level: 'debug',
+      message: 'Module execution completed',
+      operation: 'module_execution_complete',
+    },
+  ],
+  [
+    EVENT_EMITTER_EVENTS.MODULE_EXECUTION_ERROR,
+    { level: 'error', message: 'Module execution failed', operation: 'module_execution_error' },
+  ],
+  [
+    EVENT_EMITTER_EVENTS.MODULE_DISPOSE_START,
+    { level: 'debug', message: 'Module disposal started', operation: 'module_dispose_start' },
+  ],
+  [
+    EVENT_EMITTER_EVENTS.MODULE_DISPOSE_COMPLETE,
+    { level: 'info', message: 'Module disposal completed', operation: 'module_dispose_complete' },
+  ],
+  [
+    EVENT_EMITTER_EVENTS.MODULE_DISPOSE_ERROR,
+    { level: 'error', message: 'Module disposal failed', operation: 'module_dispose_error' },
+  ],
+]);
+
+/** Safely extract module data fields from untyped event payload. @internal */
+export function extractLoggingModuleData(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'] }),
+  };
+}
+
+/** Narrow interface for the log methods needed by convenience helpers. @internal */
+export interface ILogWriter {
+  info(
+    message: string,
+    context?: Record<string, string | number | boolean | Date | undefined>,
+    metadata?: ILogEntry['metadata'],
+  ): Promise<void>;
+  log(
+    level: TLogLevel,
+    message: string,
+    context?: Record<string, string | number | boolean | Date | undefined>,
+    metadata?: ILogEntry['metadata'],
+  ): Promise<void>;
+}
+
+const PREVIEW_LENGTH_HELPER = 100;
+
+/** Log execution start with truncated user input. @internal */
+export async function logExecutionStartHelper(
+  writer: ILogWriter,
+  executionId: string,
+  userInput: string,
+  metadata?: ILogEntry['metadata'],
+): Promise<void> {
+  await writer.info(
+    'Execution started',
+    { userInput: userInput.substring(0, PREVIEW_LENGTH_HELPER) },
+    { executionId, operation: 'execution_start', ...metadata },
+  );
+}
+
+/** Log execution completion with duration. @internal */
+export async function logExecutionCompleteHelper(
+  writer: ILogWriter,
+  executionId: string,
+  duration: number,
+  metadata?: ILogEntry['metadata'],
+): Promise<void> {
+  await writer.info(
+    'Execution completed',
+    { duration },
+    {
+      executionId,
+      operation: 'execution_complete',
+      ...(duration !== undefined && { duration }),
+      ...metadata,
+    },
+  );
+}
+
+/** Log a tool execution result at info (success) or error (failure) level. @internal */
+export async function logToolExecutionHelper(
+  writer: ILogWriter,
+  toolName: string,
+  executionId: string,
+  duration?: number,
+  success?: boolean,
+  metadata?: ILogEntry['metadata'],
+): Promise<void> {
+  const message = success ? 'Tool executed successfully' : 'Tool execution failed';
+  const level: TLogLevel = success ? 'info' : 'error';
+  const logMetadata = {
+    executionId,
+    operation: 'tool_execution',
+    ...(duration !== undefined && { duration }),
+    ...(metadata && typeof metadata === 'object' ? metadata : {}),
+  } as ILogEntry['metadata'];
+  await writer.log(level, message, { toolName, success: success ?? false }, logMetadata);
+}

package/src/logging/logging-plugin.ts

@@ -0,0 +1,288 @@
+import {
+  AbstractPlugin,
+  PluginCategory,
+  PluginPriority,
+  createLogger,
+  type ILogger,
+  SilentLogger,
+  PluginError,
+  type IEventEmitterEventData,
+  type TEventName,
+} from '@robota-sdk/agent-core';
+
+import {
+  TLogLevel,
+  ILogEntry,
+  ILoggingContextData,
+  ILoggingPluginOptions,
+  ILoggingPluginStats,
+  ILogStorage,
+  ILogFormatter,
+} from './types';
+import {
+  validateLoggingOptions,
+  createLoggingStorage,
+  extractLoggingModuleData,
+  LOGGING_MODULE_EVENT_MAP,
+  logExecutionStartHelper,
+  logExecutionCompleteHelper,
+  logToolExecutionHelper,
+} from './logging-helpers';
+
+export type { ILoggingContextData } from './types';
+
+const DEFAULT_MAX_LOGS = 10000;
+const DEFAULT_BATCH_SIZE = 100;
+const DEFAULT_FLUSH_INTERVAL_MS = 30000;
+
+/** Logs agent operations using configurable storage backends (console/file/remote/silent). */
+export class LoggingPlugin extends AbstractPlugin<ILoggingPluginOptions, ILoggingPluginStats> {
+  name = 'LoggingPlugin';
+  version = '1.0.0';
+
+  private storage: ILogStorage;
+  private pluginOptions: Required<Omit<ILoggingPluginOptions, 'formatter' | 'logger'>> & {
+    formatter?: ILogFormatter;
+    logger?: ILogger;
+  };
+  private logger: ILogger;
+  private simpleLogger: ILogger;
+  private logLevels: TLogLevel[] = ['debug', 'info', 'warn', 'error'];
+
+  constructor(options: ILoggingPluginOptions) {
+    super();
+    this.logger = createLogger('LoggingPlugin');
+    this.simpleLogger = options.logger || SilentLogger;
+
+    // Set plugin classification
+    this.category = PluginCategory.LOGGING;
+    this.priority = PluginPriority.HIGH;
+
+    // Validate options
+    validateLoggingOptions(options);
+
+    // Set defaults
+    this.pluginOptions = {
+      enabled: options.enabled ?? true,
+      strategy: options.strategy,
+      level: options.level ?? 'info',
+      filePath: options.filePath ?? './agent.log',
+      remoteEndpoint: options.remoteEndpoint ?? '',
+      remoteHeaders: options.remoteHeaders ?? {},
+      maxLogs: options.maxLogs ?? DEFAULT_MAX_LOGS,
+      includeStackTrace: options.includeStackTrace ?? true,
+      ...(options.formatter && { formatter: options.formatter }),
+      batchSize: options.batchSize ?? DEFAULT_BATCH_SIZE,
+      flushInterval: options.flushInterval ?? DEFAULT_FLUSH_INTERVAL_MS,
+      // Add plugin options defaults
+      category: options.category ?? PluginCategory.LOGGING,
+      priority: options.priority ?? PluginPriority.HIGH,
+      moduleEvents: options.moduleEvents ?? [],
+      subscribeToAllModuleEvents: options.subscribeToAllModuleEvents ?? false,
+    };
+
+    // Initialize storage
+    this.storage = createLoggingStorage(
+      this.pluginOptions.strategy,
+      this.pluginOptions.filePath,
+      this.pluginOptions.remoteEndpoint,
+      this.pluginOptions.flushInterval,
+      this.pluginOptions.formatter,
+    );
+
+    this.logger.info('LoggingPlugin initialized', {
+      strategy: this.pluginOptions.strategy,
+      level: this.pluginOptions.level,
+      maxLogs: this.pluginOptions.maxLogs,
+    });
+  }
+
+  /**
+   * Routes module lifecycle events (initialize, execute, dispose) to the
+   * appropriate log level. Errors are logged but never re-thrown.
+   */
+  override async onModuleEvent(
+    eventName: TEventName,
+    eventData: IEventEmitterEventData,
+  ): Promise<void> {
+    try {
+      const descriptor = LOGGING_MODULE_EVENT_MAP.get(eventName);
+      if (!descriptor) return;
+
+      const { moduleName, moduleType, duration, success } = extractLoggingModuleData(
+        eventData.data,
+      );
+      const context: ILoggingContextData = { moduleName, moduleType };
+      if (duration !== undefined) context.duration = duration;
+      if (success !== undefined) context.success = success;
+
+      const metadata: ILogEntry['metadata'] = { operation: descriptor.operation };
+      if (eventData.executionId) metadata.executionId = eventData.executionId;
+      if (duration !== undefined) metadata.duration = duration;
+
+      const isErrorEvent = descriptor.level === 'error';
+      if (isErrorEvent) {
+        await this.error(descriptor.message, eventData.error, context, metadata);
+      } else {
+        await this.log(descriptor.level, descriptor.message, context, metadata);
+      }
+    } catch (error) {
+      this.simpleLogger.error(
+        `LoggingPlugin failed to handle module event ${eventName}:`,
+        error instanceof Error ? error : new Error(String(error)),
+      );
+    }
+  }
+
+  /**
+   * Writes a log entry to the configured storage if the level meets the
+   * current threshold. Logging failures are swallowed to prevent cascading errors.
+   */
+  async log(
+    level: TLogLevel,
+    message: string,
+    context?: ILoggingContextData,
+    metadata?: ILogEntry['metadata'],
+  ): Promise<void> {
+    if (!this.shouldLog(level)) {
+      return;
+    }
+
+    try {
+      const entry: ILogEntry = {
+        timestamp: new Date(),
+        level,
+        message,
+        ...(context && { context }),
+        ...(metadata && { metadata }),
+      };
+
+      await this.storage.write(entry);
+    } catch (error) {
+      // Don't throw errors from logging to avoid infinite loops
+      this.simpleLogger.error(
+        'Logging failed:',
+        error instanceof Error ? error : new Error(String(error)),
+      );
+    }
+  }
+
+  /** Log debug message */
+  async debug(
+    message: string,
+    context?: ILoggingContextData,
+    metadata?: ILogEntry['metadata'],
+  ): Promise<void> {
+    await this.log('debug', message, context, metadata);
+  }
+
+  /** Log info message */
+  async info(
+    message: string,
+    context?: ILoggingContextData,
+    metadata?: ILogEntry['metadata'],
+  ): Promise<void> {
+    await this.log('info', message, context, metadata);
+  }
+
+  /** Log warning message */
+  async warn(
+    message: string,
+    context?: ILoggingContextData,
+    metadata?: ILogEntry['metadata'],
+  ): Promise<void> {
+    await this.log('warn', message, context, metadata);
+  }
+
+  /**
+   * Log error message
+   */
+  async error(
+    message: string,
+    error?: Error,
+    context?: ILoggingContextData,
+    metadata?: ILogEntry['metadata'],
+  ): Promise<void> {
+    const errorContext = {
+      ...context,
+      ...(error && this.pluginOptions.includeStackTrace
+        ? {
+            errorMessage: error.message,
+            errorStack: error.stack,
+          }
+        : {}),
+    };
+
+    await this.log('error', message, errorContext, metadata);
+  }
+
+  /**
+   * Logs the start of an agent execution, truncating user input to 100 characters.
+   */
+  async logExecutionStart(
+    executionId: string,
+    userInput: string,
+    metadata?: ILogEntry['metadata'],
+  ): Promise<void> {
+    await logExecutionStartHelper(this, executionId, userInput, metadata);
+  }
+
+  /**
+   * Logs the completion of an agent execution with its duration.
+   */
+  async logExecutionComplete(
+    executionId: string,
+    duration: number,
+    metadata?: ILogEntry['metadata'],
+  ): Promise<void> {
+    await logExecutionCompleteHelper(this, executionId, duration, metadata);
+  }
+
+  /**
+   * Logs a tool execution result at info (success) or error (failure) level.
+   */
+  async logToolExecution(
+    toolName: string,
+    executionId: string,
+    duration?: number,
+    success?: boolean,
+    metadata?: ILogEntry['metadata'],
+  ): Promise<void> {
+    await logToolExecutionHelper(this, toolName, executionId, duration, success, metadata);
+  }
+
+  /**
+   * Flushes any buffered log entries to the underlying storage.
+   * @throws PluginError if the flush operation fails
+   */
+  async flush(): Promise<void> {
+    try {
+      await this.storage.flush();
+    } catch (error) {
+      throw new PluginError('Failed to flush logs', 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('LoggingPlugin destroyed');
+    } catch (error) {
+      this.logger.error('Error during plugin cleanup', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /** Check if message should be logged based on level */
+  private shouldLog(level: TLogLevel): boolean {
+    const currentLevelIndex = this.logLevels.indexOf(this.pluginOptions.level);
+    const messageLevelIndex = this.logLevels.indexOf(level);
+    return messageLevelIndex >= currentLevelIndex;
+  }
+}

package/src/logging/storages/console-storage.ts

@@ -0,0 +1,44 @@
+import type { ILogEntry, ILogStorage, ILogFormatter, TLogLevel } from '../types';
+import { ConsoleLogFormatter } from '../formatters';
+import { SilentLogger, type ILogger } from '@robota-sdk/agent-core';
+
+/**
+ * Console log storage
+ */
+export class ConsoleLogStorage implements ILogStorage {
+  private formatter: ILogFormatter;
+  private logger: ILogger;
+
+  constructor(formatter?: ILogFormatter, logger?: ILogger) {
+    this.formatter = formatter || new ConsoleLogFormatter();
+    this.logger = logger || SilentLogger;
+  }
+
+  async write(entry: ILogEntry): Promise<void> {
+    const formatted = this.formatter.format(entry);
+
+    const level: TLogLevel = entry.level;
+    switch (level) {
+      case 'debug':
+        this.logger.debug(formatted);
+        break;
+      case 'info':
+        this.logger.info(formatted);
+        break;
+      case 'warn':
+        this.logger.warn(formatted);
+        break;
+      case 'error':
+        this.logger.error(formatted);
+        break;
+    }
+  }
+
+  async flush(): Promise<void> {
+    // Console doesn't need flushing
+  }
+
+  async close(): Promise<void> {
+    // Console doesn't need closing
+  }
+}

package/src/logging/storages/file-storage.ts

@@ -0,0 +1,44 @@
+import type { ILogEntry, ILogStorage, ILogFormatter } from '../types';
+import { JsonLogFormatter } from '../formatters';
+import { createLogger, type ILogger, PluginError } from '@robota-sdk/agent-core';
+
+/**
+ * File log storage (placeholder implementation)
+ */
+export class FileLogStorage implements ILogStorage {
+  private filePath: string;
+  private formatter: ILogFormatter;
+  private logger: ILogger;
+
+  constructor(filePath: string, formatter?: ILogFormatter) {
+    this.filePath = filePath;
+    this.formatter = formatter || new JsonLogFormatter();
+    this.logger = createLogger('FileLogStorage');
+  }
+
+  async write(entry: ILogEntry): Promise<void> {
+    try {
+      // File writing would be implemented here
+      // This is a placeholder for actual file system operations
+      this.logger.warn('File logging not fully implemented yet', {
+        filePath: this.filePath,
+        entry: this.formatter.format(entry),
+      });
+    } catch (error) {
+      throw new PluginError('Failed to write log to file', 'LoggingPlugin', {
+        filePath: this.filePath,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  async flush(): Promise<void> {
+    // File flushing would be implemented here
+    this.logger.warn('File flush not fully implemented yet');
+  }
+
+  async close(): Promise<void> {
+    // File closing would be implemented here
+    this.logger.warn('File close not fully implemented yet');
+  }
+}

package/src/logging/storages/index.ts

@@ -0,0 +1,4 @@
+export { ConsoleLogStorage } from './console-storage';
+export { FileLogStorage } from './file-storage';
+export { RemoteLogStorage } from './remote-storage';
+export { SilentLogStorage } from './silent-storage';

package/src/logging/storages/remote-storage.ts

@@ -0,0 +1,78 @@
+import type { ILogEntry, ILogStorage, ILogFormatter } from '../types';
+import { JsonLogFormatter } from '../formatters';
+import {
+  createLogger,
+  type ILogger,
+  PluginError,
+  type TTimerId,
+  startPeriodicTask,
+  stopPeriodicTask,
+} from '@robota-sdk/agent-core';
+
+/**
+ * Remote log storage with batching
+ */
+export class RemoteLogStorage implements ILogStorage {
+  private url: string;
+  private formatter: ILogFormatter;
+  private batchSize: number;
+  private flushInterval: number;
+  private pendingLogs: ILogEntry[] = [];
+  private flushTimer: TTimerId | undefined;
+  private logger: ILogger;
+
+  constructor(url: string, _options: { timeout?: number } = {}) {
+    this.url = url;
+    this.formatter = new JsonLogFormatter();
+    this.batchSize = 10;
+    this.flushInterval = 5000;
+    this.logger = createLogger('RemoteLogStorage');
+
+    // Start flush timer
+    this.flushTimer = startPeriodicTask(
+      this.logger,
+      { name: 'RemoteLogStorage.flush', intervalMs: this.flushInterval },
+      async () => {
+        await this.flush();
+      },
+    );
+  }
+
+  async write(entry: ILogEntry): Promise<void> {
+    this.pendingLogs.push(entry);
+
+    if (this.pendingLogs.length >= this.batchSize) {
+      await this.flush();
+    }
+  }
+
+  async flush(): Promise<void> {
+    if (this.pendingLogs.length === 0) return;
+
+    const logsToSend = [...this.pendingLogs];
+    this.pendingLogs = [];
+
+    try {
+      // Remote sending would be implemented here
+      // This is a placeholder for actual HTTP requests
+      this.logger.warn('Remote logging not fully implemented yet', {
+        url: this.url,
+        logCount: logsToSend.length,
+        logs: logsToSend.map((log) => this.formatter.format(log)),
+      });
+    } catch (error) {
+      throw new PluginError('Failed to send logs to remote endpoint', 'LoggingPlugin', {
+        url: this.url,
+        logCount: logsToSend.length,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  async close(): Promise<void> {
+    stopPeriodicTask(this.flushTimer);
+    this.flushTimer = undefined;
+
+    await this.flush();
+  }
+}

package/src/logging/storages/silent-storage.ts

@@ -0,0 +1,18 @@
+import type { ILogEntry, ILogStorage } from '../types';
+
+/**
+ * Silent log storage (no-op)
+ */
+export class SilentLogStorage implements ILogStorage {
+  async write(_entry: ILogEntry): Promise<void> {
+    // Silent mode - do nothing
+  }
+
+  async flush(): Promise<void> {
+    // Silent mode - do nothing
+  }
+
+  async close(): Promise<void> {
+    // Silent mode - do nothing
+  }
+}