Plugin Migration Guide

This guide documents the migration of platform integrations from standalone clients to the unified plugin architecture.

Overview

We've migrated platform integrations (Twitter and Telegram) from being standalone applications in the clients/ directory to being plugins in the agent/plugins/ directory. This provides better integration with the agent runtime and consistent architecture across all platforms.

Architecture Changes

Before: Standalone Clients

clients/
├── twitter-client/     # Standalone Node.js app
│   ├── package.json    # Own dependencies
│   ├── src/           # Independent codebase
│   └── ...
└── telegram-client/    # (Would have been similar)

After: Unified Plugins

agent/plugins/
├── twitter/           # Twitter plugin module
│   ├── twitter-plugin.ts  # Plugin implementation
│   ├── services/         # Twitter-specific services
│   ├── auth/            # OAuth handling
│   ├── models/          # Data models
│   ├── package.json     # Dependencies
│   ├── index.ts         # Module exports
│   └── README.md        # Documentation
├── telegram/          # Telegram plugin module
│   ├── telegram-plugin.ts # Plugin implementation
│   ├── package.json      # Dependencies
│   ├── index.ts          # Module exports
│   └── README.md         # Documentation
├── example-plugin.ts  # Simple example plugin
└── content-plugin.ts  # Content generation plugin

Key Differences

1. Plugin Interface

All plugins now implement the standard Plugin interface:

interface Plugin {
  name: string;
  version: string;
  platforms: string[];
  
  // Lifecycle
  initialize(): Promise<void>;
  shutdown(): Promise<void>;
  
  // Message handling
  canHandle(message: AgentMessage): boolean;
  handle(message: AgentMessage): Promise<AgentResponse>;
}

2. Message-Based Communication

Instead of direct API calls, plugins communicate through messages:

// Before (standalone client)
await twitterClient.postTweet("Hello world");

// After (plugin through runtime)
await runtime.processMessage({
  platform: "twitter",
  content: "Hello world",
  metadata: { type: "post_request" }
});

3. Shared Services

Plugins can now use shared agent services:

• LLM Service for content generation

• Logging Service for consistent logging

• Character Manager for personality consistency

4. Unified Configuration

All plugins are configured through the agent runtime:

const runtime = new AgentRuntime();

// Register plugins
runtime.registerPlugin(new TwitterPlugin(config));
runtime.registerPlugin(new TelegramPlugin(config));

// Initialize all at once
await runtime.initialize();

Migration Steps

For Twitter Client

1. Code Migration

   • Moved from clients/twitter-client/ to agent/plugins/twitter/

   • Wrapped standalone functionality in TwitterPlugin class

   • Implemented Plugin interface methods

2. Dependencies

   • Kept Twitter-specific dependencies in plugin's package.json

   • Shared dependencies use agent's versions

3. Authentication

   • OAuth flow remains the same

   • Tokens stored in agent/plugins/twitter/tokens/

4. Usage Changes

   // Before
   const client = new BillTwitterAgent();
   await client.start();
   
   // After
   const plugin = new TwitterPlugin(config);
   runtime.registerPlugin(plugin);

For Telegram Integration

1. Structure Change

   • Moved from single file to organized module

   • Created agent/plugins/telegram/ directory

   • Added proper documentation and package.json

2. No Functional Changes

   • Already implemented Plugin interface

   • Message handling remains the same

Benefits of Plugin Architecture

1. Consistency: All platform integrations follow the same pattern

2. Modularity: Easy to add/remove platforms

3. Testability: Plugins can be tested in isolation

4. Shared Resources: Reuse services across platforms

5. Centralized Management: Single runtime manages all plugins

Creating New Plugins

To create a new platform plugin:

1. Create directory: agent/plugins/your-platform/

2. Implement the Plugin interface

3. Add necessary services and models

4. Create index.ts and README.md

5. Export from agent/index.ts

Example structure:

export class YourPlugin implements Plugin {
  name = "your-plugin";
  version = "1.0.0";
  platforms = ["your-platform"];
  
  async initialize() {
    // Setup connection
  }
  
  async shutdown() {
    // Cleanup
  }
  
  canHandle(message: AgentMessage) {
    return message.platform === "your-platform";
  }
  
  async handle(message: AgentMessage) {
    // Process message and return response
  }
}

Best Practices

1. Error Handling: Implement comprehensive error handling

2. Rate Limiting: Respect platform API limits

3. Logging: Use consistent logging patterns

4. Configuration: Use environment variables

5. Documentation: Provide clear setup instructions

Future Improvements

1. Plugin Discovery: Auto-discovery of plugins in directory

2. Hot Reloading: Reload plugins without restart

3. Plugin Dependencies: Better dependency management

4. Shared State: Cross-plugin communication

5. Plugin Store: Repository of community plugins