Winston Logger Plugin

Winston-based logging plugin for Fractal Synapse agents that provides comprehensive logging capabilities with both console and persistent storage options.

Features

• Multiple log levels: info, warn, error, debug with winston
• Persistent storage: Integration with PluginStorageInterface for file-based logs
• Fallback logging: Console logger when winston plugin not available
• Tool integration: Easy access via experimental_context
• Plugin integration: Simple access via getLogger() helper
• Zero configuration: Works out of the box with sensible defaults
• Agent lifecycle: Proper cleanup and resource management

Installation

npm install @fractal-synapse/winston-logger

Usage Examples

Tool Usage Example

// In any tool implementation
import { tool } from 'ai';
import { z } from 'zod';
import { getLoggerFromContext } from '@fractal-synapse/agent-core';

const myTool = tool({
  description: 'Example tool that uses logging',
  inputSchema: z.object({
    action: z.string().describe('Action to perform')
  }),
  execute: async (input, { experimental_context }) => {
    const logger = getLoggerFromContext(experimental_context);

    // No await needed for logging calls
    logger.info('Tool execution started', {
      tool: 'myTool',
      action: input.action
    });

    try {
      // Tool logic here
      const result = performAction(input.action);

      logger.info('Tool execution completed successfully', {
        tool: 'myTool',
        result
      });

      return result;
    } catch (error) {
      logger.error('Tool execution failed', {
        tool: 'myTool',
        error: error.message
      });
      throw error;
    }
  }
});

Plugin Usage Example

// In another plugin that needs logging
import { AgentPlugin, Agent, getLogger } from '@fractal-synapse/agent-core';

export class MyOtherPlugin implements AgentPlugin {
  readonly name = 'my-other-plugin';
  private logger = getLogger(); // Gets console logger fallback

  async initializeAgent(agent: Agent): Promise<void> {
    this.logger.info('MyOtherPlugin initialized');
  }

  async cleanupAgent(agent: Agent): Promise<void> {
    this.logger.info('MyOtherPlugin cleaned up');
  }
}

Application Registration Example

// In an application (e.g., agent-cli)
import { PluginRegistry, Agent, AgentDefinition } from '@fractal-synapse/agent-core';
import { WinstonLoggerPlugin } from '@fractal-synapse/winston-logger';
import { FileStorage } from './storage/file-storage'; // Custom storage implementation

const storage = new FileStorage('./logs');
const pluginRegistry = new PluginRegistry();

// With both storage and console logging
pluginRegistry.register(new WinstonLoggerPlugin({
  storage,
  logToConsole: true
}));

// Or with only file logging (no console)
// pluginRegistry.register(new WinstonLoggerPlugin({
//   storage,
//   logToConsole: false
// }));

// Or with only console logging (no storage)
// pluginRegistry.register(new WinstonLoggerPlugin({
//   logToConsole: true
// }));

const agentDefinition = new AgentDefinition(
  'Agent with Logging',
  'An agent that logs everything',
  'You are a helpful assistant',
  ['my-tool'], // tool names
  'openai-gpt-4o',
  ['winston-logger'] // plugin names
);

const agent = new Agent({ agentDefinition, pluginRegistry });

Configuration

WinstonLoggerConfig

interface WinstonLoggerConfig {
  storage?: PluginStorageInterface;  // Optional storage for persistent logs
  logToConsole?: boolean;            // Enable/disable console logging (default: true)
}

Log Levels

• info() - General information messages
• warn() - Warning messages
• error() - Error messages (accepts string or Error object)
• debug() - Debug messages
• log() - Alias for info()

Advanced Methods

• profile(id) - Start/end profiling timer
• startTimer(id) - Start a timer
• endTimer(id) - End a timer

Architecture

The logging system follows these principles:

• LoggingInterface in agent-core defines the contract
• WinstonLoggerPlugin implements both AgentPlugin and LoggingInterface
• Helper functions provide easy access from tools and plugins
• Fallback console logger when no logging plugin is available
• Integration with PluginStorageInterface for persistent log storage

Plugin Lifecycle

1. Registration: Plugin is registered in the PluginRegistry
2. Agent Creation: Agent is created with plugin names in AgentDefinition
3. Initialization: Plugin's initializeAgent method is called with agent instance
4. Usage: Plugin can access agent throughout agent lifetime
5. Cleanup: Plugin's cleanup method is called when agent is destroyed

Dependencies

• winston: Winston logging library
• @fractal-synapse/agent-core: Core agent functionality
• winston-transport: Custom transport support

Benefits

• Modular: Logging can be completely removed by not registering the plugin
• Flexible: Different applications can use different logging configurations
• Extensible: Easy to create other logging plugins (e.g., for Datadog, CloudWatch)
• Type-safe: Full TypeScript support with proper interfaces
• Consistent: Follows existing plugin patterns in the project