dank-ai 1.0.41 → 1.0.42

package/lib/plugins/base.js

@@ -0,0 +1,324 @@
+/**
+ * PluginBase - Abstract base class for all Dank plugins
+ * 
+ * Provides lifecycle hooks, event handling, tool registration, and state management
+ * for plugins that integrate with Dank agents.
+ */
+
+const EventEmitter = require('events');
+const { v4: uuidv4 } = require('uuid');
+
+class PluginBase extends EventEmitter {
+  constructor(name, config = {}) {
+    super();
+    
+    if (!name || typeof name !== 'string') {
+      throw new Error('Plugin name must be a non-empty string');
+    }
+    
+    this.name = name;
+    this.id = uuidv4();
+    this.config = config;
+    this.state = new Map();
+    this.tools = new Map();
+    this.handlers = new Map();
+    this.status = 'initialized'; // initialized, starting, running, stopping, stopped, error
+    this.agentContext = null;
+    this.pluginManager = null;
+    this.createdAt = new Date().toISOString();
+    this.startedAt = null;
+    this.stoppedAt = null;
+  }
+
+  /**
+   * Initialize the plugin
+   * Override this method to set up connections, validate config, etc.
+   */
+  async init() {
+    this.status = 'initialized';
+    return this;
+  }
+
+  /**
+   * Start the plugin
+   * Override this method to start services, begin listening, etc.
+   */
+  async start() {
+    if (this.status === 'running') {
+      return this;
+    }
+    
+    this.status = 'starting';
+    this.startedAt = new Date().toISOString();
+    
+    try {
+      await this.onStart();
+      this.status = 'running';
+      this.emit('started');
+      return this;
+    } catch (error) {
+      this.status = 'error';
+      this.emit('error', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Stop the plugin
+   * Override this method to clean up resources, close connections, etc.
+   */
+  async stop() {
+    if (this.status === 'stopped' || this.status === 'stopping') {
+      return this;
+    }
+    
+    this.status = 'stopping';
+    
+    try {
+      await this.onStop();
+      this.status = 'stopped';
+      this.stoppedAt = new Date().toISOString();
+      this.emit('stopped');
+      return this;
+    } catch (error) {
+      this.status = 'error';
+      this.emit('error', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Destroy the plugin (cleanup)
+   * Override this method for final cleanup
+   */
+  async destroy() {
+    if (this.status !== 'stopped') {
+      await this.stop();
+    }
+    
+    await this.onDestroy();
+    this.removeAllListeners();
+    this.state.clear();
+    this.tools.clear();
+    this.handlers.clear();
+    return this;
+  }
+
+  /**
+   * Lifecycle hooks (override these in subclasses)
+   */
+  async onStart() {
+    // Override in subclass
+  }
+
+  async onStop() {
+    // Override in subclass
+  }
+
+  async onDestroy() {
+    // Override in subclass
+  }
+
+  /**
+   * Register an event handler
+   * Uses the same pattern as agent handlers
+   */
+  on(eventType, handler) {
+    if (typeof handler !== 'function') {
+      throw new Error('Handler must be a function');
+    }
+
+    if (!this.handlers.has(eventType)) {
+      this.handlers.set(eventType, []);
+    }
+
+    this.handlers.get(eventType).push({
+      handler,
+      plugin: this.name
+    });
+
+    // Also register with EventEmitter for compatibility
+    super.on(eventType, handler);
+    
+    return this;
+  }
+
+  /**
+   * Remove an event handler
+   */
+  off(eventType, handler) {
+    if (this.handlers.has(eventType)) {
+      const handlers = this.handlers.get(eventType);
+      const index = handlers.findIndex(h => h.handler === handler);
+      if (index !== -1) {
+        handlers.splice(index, 1);
+      }
+    }
+    
+    super.off(eventType, handler);
+    return this;
+  }
+
+  /**
+   * Emit an event (delegates to EventEmitter)
+   */
+  emit(eventName, ...args) {
+    // Prefix plugin events with plugin name
+    const prefixedEvent = `plugin:${this.name}:${eventName}`;
+    super.emit(prefixedEvent, ...args);
+    super.emit(eventName, ...args);
+    return this;
+  }
+
+  /**
+   * Register a tool that agents can use
+   */
+  registerTool(name, definition) {
+    if (typeof name !== 'string' || name.trim().length === 0) {
+      throw new Error('Tool name must be a non-empty string');
+    }
+
+    // Prefix tool name with plugin name
+    const prefixedName = `plugin:${this.name}:${name}`;
+    
+    this.tools.set(prefixedName, {
+      ...definition,
+      name: prefixedName,
+      plugin: this.name,
+      registeredAt: new Date().toISOString()
+    });
+
+    // Emit event for tool registration
+    this.emit('tool:registered', { name: prefixedName, definition });
+    
+    return this;
+  }
+
+  /**
+   * Get all registered tools
+   */
+  getTools() {
+    return Array.from(this.tools.values());
+  }
+
+  /**
+   * Get a specific tool
+   */
+  getTool(name) {
+    const prefixedName = name.startsWith(`plugin:${this.name}:`) 
+      ? name 
+      : `plugin:${this.name}:${name}`;
+    return this.tools.get(prefixedName);
+  }
+
+  /**
+   * Set plugin state (key-value store)
+   */
+  setState(key, value) {
+    this.state.set(key, value);
+    this.emit('state:changed', { key, value });
+    return this;
+  }
+
+  /**
+   * Get plugin state
+   */
+  getState(key) {
+    return this.state.get(key);
+  }
+
+  /**
+   * Get all plugin state
+   */
+  getAllState() {
+    return Object.fromEntries(this.state);
+  }
+
+  /**
+   * Clear plugin state
+   */
+  clearState() {
+    this.state.clear();
+    this.emit('state:cleared');
+    return this;
+  }
+
+  /**
+   * Get agent context (set by PluginManager)
+   */
+  getAgentContext() {
+    return this.agentContext;
+  }
+
+  /**
+   * Set agent context (called by PluginManager)
+   */
+  setAgentContext(context) {
+    this.agentContext = context;
+    return this;
+  }
+
+  /**
+   * Get plugin manager reference
+   */
+  getPluginManager() {
+    return this.pluginManager;
+  }
+
+  /**
+   * Set plugin manager reference (called by PluginManager)
+   */
+  setPluginManager(manager) {
+    this.pluginManager = manager;
+    return this;
+  }
+
+  /**
+   * Get another plugin by name
+   */
+  getPlugin(name) {
+    if (!this.pluginManager) {
+      throw new Error('Plugin manager not available');
+    }
+    return this.pluginManager.getPlugin(name);
+  }
+
+  /**
+   * Get all other plugins
+   */
+  getPlugins() {
+    if (!this.pluginManager) {
+      throw new Error('Plugin manager not available');
+    }
+    return this.pluginManager.getAllPlugins();
+  }
+
+  /**
+   * Get plugin metadata
+   */
+  getMetadata() {
+    return {
+      name: this.name,
+      id: this.id,
+      status: this.status,
+      createdAt: this.createdAt,
+      startedAt: this.startedAt,
+      stoppedAt: this.stoppedAt,
+      toolCount: this.tools.size,
+      handlerCount: this.handlers.size,
+      stateSize: this.state.size
+    };
+  }
+
+  /**
+   * Validate plugin configuration
+   * Override this method to add custom validation
+   */
+  validateConfig(config) {
+    // Override in subclass for custom validation
+    return true;
+  }
+}
+
+module.exports = { PluginBase };
+

package/lib/plugins/config.js

@@ -0,0 +1,171 @@
+/**
+ * Plugin Configuration - Schema validation and management
+ * 
+ * Provides Joi-based schema validation for plugin configurations,
+ * environment variable injection, and secret management.
+ */
+
+const Joi = require('joi');
+
+class PluginConfig {
+  /**
+   * Validate plugin configuration against schema
+   */
+  static validate(name, config, schema) {
+    if (!schema) {
+      // No schema provided, just return config as-is
+      return config;
+    }
+
+    const { error, value } = schema.validate(config, {
+      stripUnknown: true,
+      abortEarly: false
+    });
+
+    if (error) {
+      const details = error.details.map(d => d.message).join(', ');
+      throw new Error(`Invalid configuration for plugin '${name}': ${details}`);
+    }
+
+    return value;
+  }
+
+  /**
+   * Inject environment variables into config
+   * Replaces ${ENV_VAR} or ${ENV_VAR:default} patterns
+   */
+  static injectEnvVars(config) {
+    if (typeof config === 'string') {
+      return this._replaceEnvVars(config);
+    }
+
+    if (Array.isArray(config)) {
+      return config.map(item => this.injectEnvVars(item));
+    }
+
+    if (config && typeof config === 'object') {
+      const result = {};
+      for (const [key, value] of Object.entries(config)) {
+        result[key] = this.injectEnvVars(value);
+      }
+      return result;
+    }
+
+    return config;
+  }
+
+  /**
+   * Replace environment variable patterns in string
+   */
+  static _replaceEnvVars(str) {
+    if (typeof str !== 'string') {
+      return str;
+    }
+
+    // Match ${ENV_VAR} or ${ENV_VAR:default}
+    return str.replace(/\$\{([^}:]+)(?::([^}]+))?\}/g, (match, envVar, defaultValue) => {
+      const value = process.env[envVar];
+      if (value !== undefined) {
+        return value;
+      }
+      if (defaultValue !== undefined) {
+        return defaultValue;
+      }
+      return match; // Keep original if no replacement found
+    });
+  }
+
+  /**
+   * Common configuration schemas for plugin types
+   */
+  static schemas = {
+    /**
+     * Database connection schema
+     */
+    database: Joi.object({
+      connectionString: Joi.string().optional(),
+      host: Joi.string().optional(),
+      port: Joi.number().optional(),
+      database: Joi.string().optional(),
+      username: Joi.string().optional(),
+      password: Joi.string().optional(),
+      poolSize: Joi.number().min(1).max(100).default(10),
+      timeout: Joi.number().min(1000).default(30000),
+      ssl: Joi.boolean().default(false)
+    }).or('connectionString', 'host'),
+
+    /**
+     * API key schema
+     */
+    apiKey: Joi.object({
+      apiKey: Joi.string().required(),
+      baseURL: Joi.string().uri().optional(),
+      timeout: Joi.number().min(1000).default(30000),
+      retries: Joi.number().min(0).max(5).default(2)
+    }),
+
+    /**
+     * Vector database schema
+     */
+    vectorDB: Joi.object({
+      apiKey: Joi.string().required(),
+      environment: Joi.string().optional(),
+      index: Joi.string().optional(),
+      dimension: Joi.number().optional(),
+      timeout: Joi.number().min(1000).default(30000)
+    }),
+
+    /**
+     * File storage schema
+     */
+    fileStorage: Joi.object({
+      path: Joi.string().required(),
+      maxSize: Joi.number().min(0).optional(),
+      allowedExtensions: Joi.array().items(Joi.string()).optional()
+    }),
+
+    /**
+     * Redis schema
+     */
+    redis: Joi.object({
+      host: Joi.string().default('localhost'),
+      port: Joi.number().min(1).max(65535).default(6379),
+      password: Joi.string().optional(),
+      db: Joi.number().min(0).default(0),
+      keyPrefix: Joi.string().optional()
+    })
+  };
+
+  /**
+   * Get a schema by name
+   */
+  static getSchema(name) {
+    return this.schemas[name];
+  }
+
+  /**
+   * Merge multiple schemas
+   */
+  static mergeSchemas(...schemas) {
+    return schemas.reduce((merged, schema) => {
+      return merged ? merged.concat(schema) : schema;
+    }, null);
+  }
+
+  /**
+   * Create a schema with environment variable support
+   */
+  static createEnvSchema(baseSchema) {
+    return baseSchema.custom((value, helpers) => {
+      const injected = this.injectEnvVars(value);
+      const { error } = baseSchema.validate(injected);
+      if (error) {
+        return helpers.error('any.custom', { message: error.message });
+      }
+      return injected;
+    });
+  }
+}
+
+module.exports = { PluginConfig };
+

package/lib/plugins/events.js

@@ -0,0 +1,186 @@
+/**
+ * Plugin Event System Utilities
+ * 
+ * Provides utilities for plugin event handling, pattern matching,
+ * and event routing between plugins and agents.
+ */
+
+class PluginEventSystem {
+  /**
+   * Check if an event name matches a handler pattern
+   * Supports wildcards and specific patterns (same as agent handlers)
+   */
+  static matchesEventPattern(eventName, pattern) {
+    // Exact match
+    if (eventName === pattern) {
+      return true;
+    }
+
+    // Wildcard patterns
+    if (pattern.includes('*')) {
+      const regexPattern = pattern.replace(/\*/g, '.*').replace(/:/g, ':');
+      const regex = new RegExp(`^${regexPattern}$`);
+      return regex.test(eventName);
+    }
+
+    // Prefix match (e.g., 'plugin:postgres:*' matches 'plugin:postgres:query')
+    if (pattern.endsWith(':*')) {
+      const prefix = pattern.slice(0, -2);
+      return eventName.startsWith(prefix + ':');
+    }
+
+    return false;
+  }
+
+  /**
+   * Normalize event name (add plugin prefix if needed)
+   */
+  static normalizeEventName(eventName, pluginName) {
+    if (eventName.startsWith('plugin:')) {
+      return eventName;
+    }
+    return `plugin:${pluginName}:${eventName}`;
+  }
+
+  /**
+   * Extract plugin name from event name
+   */
+  static extractPluginName(eventName) {
+    const match = eventName.match(/^plugin:([^:]+):/);
+    return match ? match[1] : null;
+  }
+
+  /**
+   * Create event name for plugin
+   */
+  static createPluginEvent(pluginName, eventName) {
+    return `plugin:${pluginName}:${eventName}`;
+  }
+
+  /**
+   * Create tool event name
+   */
+  static createToolEvent(toolName, action) {
+    return `tool:${toolName}:${action}`;
+  }
+
+  /**
+   * Create plugin tool event name
+   */
+  static createPluginToolEvent(pluginName, toolName, action) {
+    return `plugin:${pluginName}:tool:${toolName}:${action}`;
+  }
+
+  /**
+   * Find all matching handlers for an event
+   */
+  static findMatchingHandlers(eventName, handlersMap) {
+    const matchingHandlers = [];
+
+    for (const [handlerPattern, handlers] of handlersMap) {
+      if (this.matchesEventPattern(eventName, handlerPattern)) {
+        matchingHandlers.push(...handlers);
+      }
+    }
+
+    return matchingHandlers;
+  }
+
+  /**
+   * Execute handlers and collect responses
+   */
+  static async executeHandlers(handlers, data) {
+    let modifiedData = { ...data };
+
+    for (const handlerObj of handlers) {
+      try {
+        const handler = typeof handlerObj === 'function' 
+          ? handlerObj 
+          : handlerObj.handler;
+
+        if (typeof handler !== 'function') {
+          continue;
+        }
+
+        const result = await handler(modifiedData);
+
+        // If handler returns an object, merge it with the current data
+        if (result && typeof result === 'object' && !Array.isArray(result)) {
+          modifiedData = { ...modifiedData, ...result };
+        }
+      } catch (error) {
+        console.error(`Error in event handler:`, error);
+        // Continue executing other handlers even if one fails
+      }
+    }
+
+    return modifiedData;
+  }
+
+  /**
+   * Emit event to multiple targets
+   */
+  static emitToTargets(targets, eventName, data) {
+    targets.forEach(target => {
+      if (target && typeof target.emit === 'function') {
+        target.emit(eventName, data);
+      }
+    });
+  }
+
+  /**
+   * Create event router for plugin-to-plugin communication
+   */
+  static createEventRouter() {
+    const routes = new Map();
+
+    return {
+      /**
+       * Register a route from event pattern to target
+       */
+      route(pattern, target) {
+        if (!routes.has(pattern)) {
+          routes.set(pattern, []);
+        }
+        routes.get(pattern).push(target);
+      },
+
+      /**
+       * Remove a route
+       */
+      unroute(pattern, target) {
+        if (routes.has(pattern)) {
+          const targets = routes.get(pattern);
+          const index = targets.indexOf(target);
+          if (index !== -1) {
+            targets.splice(index, 1);
+          }
+        }
+      },
+
+      /**
+       * Route an event
+       */
+      emit(eventName, data) {
+        for (const [pattern, targets] of routes) {
+          if (this.matchesEventPattern(eventName, pattern)) {
+            this.emitToTargets(targets, eventName, data);
+          }
+        }
+      },
+
+      /**
+       * Get all routes
+       */
+      getRoutes() {
+        return Array.from(routes.entries()).map(([pattern, targets]) => ({
+          pattern,
+          targets: targets.length
+        }));
+      }
+    };
+  }
+}
+
+module.exports = { PluginEventSystem };
+

package/lib/plugins/index.js

@@ -0,0 +1,29 @@
+/**
+ * Dank Plugin System - Main Exports
+ * 
+ * Provides the plugin system infrastructure for extending Dank agents
+ * with third-party plugins for databases, vector stores, and other services.
+ */
+
+const { PluginBase } = require('./base');
+const { PluginRegistry } = require('./registry');
+const { PluginManager } = require('./manager');
+const { PluginConfig } = require('./config');
+const { PluginEventSystem } = require('./events');
+
+module.exports = {
+  // Core classes
+  PluginBase,
+  PluginRegistry,
+  PluginManager,
+  PluginConfig,
+  PluginEventSystem,
+
+  // Convenience exports
+  createPlugin: (name, config) => {
+    // This is a helper for creating plugins, but typically plugins
+    // should extend PluginBase directly
+    throw new Error('Plugins must extend PluginBase. Use: class MyPlugin extends PluginBase { ... }');
+  }
+};
+