@elizaos/ui 2.0.0-alpha.25 → 2.0.0-alpha.334

package/packages/typescript/src/features/secrets/services/plugin-activator.js

@@ -0,0 +1,617 @@
+/**
+ * Plugin Activator Service
+ *
+ * Enables dynamic plugin activation when required secrets become available.
+ * Plugins can register for activation with their secret requirements,
+ * and will be activated automatically once all secrets are present.
+ */
+import { logger } from "../../../logger.js";
+import { Service, } from "../../../types/index.js";
+import { SECRETS_SERVICE_TYPE } from "./secrets.js";
+/**
+ * Service type identifier
+ */
+export const PLUGIN_ACTIVATOR_SERVICE_TYPE = "PLUGIN_ACTIVATOR";
+/**
+ * Default configuration
+ */
+const DEFAULT_CONFIG = {
+    enableAutoActivation: true,
+    pollingIntervalMs: 5000,
+    maxWaitMs: 0, // 0 = wait forever
+};
+/**
+ * Plugin Activator Service
+ *
+ * Manages the lifecycle of plugins that depend on secrets:
+ * - Tracks plugins waiting for secrets
+ * - Automatically activates plugins when requirements are met
+ * - Notifies plugins when their secrets change
+ * - Supports onSecretsReady and onSecretChanged callbacks
+ */
+export class PluginActivatorService extends Service {
+    static serviceType = PLUGIN_ACTIVATOR_SERVICE_TYPE;
+    capabilityDescription = "Activate plugins dynamically when their required secrets become available";
+    activatorConfig;
+    secretsService = null;
+    pendingPlugins = new Map();
+    activatedPlugins = new Set();
+    pluginSecretMapping = new Map();
+    pollingInterval = null;
+    unsubscribeSecretChanges = null;
+    /** Registered plugins with their callbacks */
+    registeredPlugins = new Map();
+    /** Listeners for secrets ready events */
+    secretsReadyListeners = new Map();
+    /** Listeners for secret changed events */
+    secretChangedListeners = new Map();
+    constructor(runtime, config) {
+        super(runtime);
+        this.activatorConfig = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Start the service
+     */
+    static async start(runtime, config) {
+        const service = new PluginActivatorService(runtime, config);
+        await service.initialize();
+        return service;
+    }
+    /**
+     * Initialize the service
+     */
+    async initialize() {
+        logger.info("[PluginActivator] Initializing");
+        // Try to get secrets service synchronously first
+        this.secretsService =
+            this.runtime.getService(SECRETS_SERVICE_TYPE);
+        if (!this.secretsService) {
+            // Service not ready yet - use getServiceLoadPromise if available
+            await this.waitForSecretsService();
+        }
+        else {
+            this.bindToSecretsService();
+        }
+        // Start polling if auto-activation enabled
+        if (this.activatorConfig.enableAutoActivation &&
+            this.activatorConfig.pollingIntervalMs > 0) {
+            this.startPolling();
+        }
+        logger.info("[PluginActivator] Initialized");
+    }
+    /**
+     * Wait for SecretsService to become available using runtime's service load promise
+     */
+    async waitForSecretsService() {
+        // Prefer runtime's promise-based service loading if available
+        if (typeof this.runtime.getServiceLoadPromise === "function") {
+            try {
+                logger.debug("[PluginActivator] Awaiting SecretsService via getServiceLoadPromise");
+                const service = await this.runtime.getServiceLoadPromise(SECRETS_SERVICE_TYPE);
+                if (service) {
+                    this.secretsService = service;
+                    logger.info("[PluginActivator] SecretsService now available");
+                    this.bindToSecretsService();
+                    return;
+                }
+            }
+            catch (err) {
+                logger.debug(`[PluginActivator] getServiceLoadPromise failed: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        // Fallback to polling if getServiceLoadPromise not available or failed
+        const maxAttempts = 20;
+        const delayMs = 250;
+        for (let i = 0; i < maxAttempts; i++) {
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+            this.secretsService =
+                this.runtime.getService(SECRETS_SERVICE_TYPE);
+            if (this.secretsService) {
+                logger.info("[PluginActivator] SecretsService now available");
+                this.bindToSecretsService();
+                return;
+            }
+        }
+        logger.warn("[PluginActivator] SecretsService not available after waiting, activation will be limited");
+    }
+    /**
+     * Bind to the SecretsService for change notifications
+     */
+    bindToSecretsService() {
+        if (!this.secretsService || this.unsubscribeSecretChanges)
+            return;
+        this.unsubscribeSecretChanges = this.secretsService.onAnySecretChanged(async (key, value, context) => {
+            await this.onSecretChanged(key, value, context);
+        });
+    }
+    /**
+     * Stop the service
+     */
+    async stop() {
+        logger.info("[PluginActivator] Stopping");
+        if (this.pollingInterval) {
+            clearInterval(this.pollingInterval);
+            this.pollingInterval = null;
+        }
+        if (this.unsubscribeSecretChanges) {
+            this.unsubscribeSecretChanges();
+            this.unsubscribeSecretChanges = null;
+        }
+        this.pendingPlugins.clear();
+        this.activatedPlugins.clear();
+        this.pluginSecretMapping.clear();
+        this.registeredPlugins.clear();
+        this.secretsReadyListeners.clear();
+        this.secretChangedListeners.clear();
+        logger.info("[PluginActivator] Stopped");
+    }
+    // ============================================================================
+    // Plugin Registration
+    // ============================================================================
+    /**
+     * Register a plugin for activation when secrets are ready
+     */
+    async registerPlugin(plugin, activationCallback) {
+        const pluginId = plugin.name;
+        if (this.activatedPlugins.has(pluginId)) {
+            logger.debug(`[PluginActivator] Plugin ${pluginId} already activated`);
+            return true;
+        }
+        // Collect all secret keys this plugin depends on
+        const allSecretKeys = plugin.requiredSecrets
+            ? Object.keys(plugin.requiredSecrets)
+            : [];
+        // Store plugin reference for later notifications
+        this.registeredPlugins.set(pluginId, {
+            plugin,
+            secretKeys: allSecretKeys,
+            activationCallback,
+        });
+        if (!plugin.requiredSecrets ||
+            Object.keys(plugin.requiredSecrets).length === 0) {
+            // No secrets required, activate immediately
+            logger.info(`[PluginActivator] Plugin ${pluginId} has no secret requirements, activating`);
+            return this.activatePlugin(pluginId, plugin, activationCallback);
+        }
+        // Check current secret status
+        const status = await this.checkPluginRequirements(plugin);
+        if (status.ready) {
+            // All secrets available, activate now
+            logger.info(`[PluginActivator] Plugin ${pluginId} has all required secrets, activating`);
+            return this.activatePlugin(pluginId, plugin, activationCallback);
+        }
+        // Queue for later activation
+        logger.info(`[PluginActivator] Plugin ${pluginId} queued, waiting for: ${status.missingRequired.join(", ")}`);
+        const requiredSecrets = Object.entries(plugin.requiredSecrets)
+            .filter(([_, req]) => req.required)
+            .map(([key]) => key);
+        this.pendingPlugins.set(pluginId, {
+            pluginId,
+            requiredSecrets,
+            callback: async () => {
+                await this.activatePlugin(pluginId, plugin, activationCallback);
+            },
+            registeredAt: Date.now(),
+        });
+        // Track which secrets this plugin needs
+        for (const secretKey of requiredSecrets) {
+            const plugins = this.pluginSecretMapping.get(secretKey) ?? new Set();
+            plugins.add(pluginId);
+            this.pluginSecretMapping.set(secretKey, plugins);
+        }
+        return false;
+    }
+    /**
+     * Unregister a pending plugin
+     */
+    unregisterPlugin(pluginId) {
+        const pending = this.pendingPlugins.get(pluginId);
+        if (!pending) {
+            return false;
+        }
+        // Remove from secret mapping
+        for (const secretKey of pending.requiredSecrets) {
+            const plugins = this.pluginSecretMapping.get(secretKey);
+            if (plugins) {
+                plugins.delete(pluginId);
+                if (plugins.size === 0) {
+                    this.pluginSecretMapping.delete(secretKey);
+                }
+            }
+        }
+        this.pendingPlugins.delete(pluginId);
+        logger.info(`[PluginActivator] Unregistered plugin ${pluginId}`);
+        return true;
+    }
+    // ============================================================================
+    // Plugin Activation
+    // ============================================================================
+    /**
+     * Activate a plugin
+     */
+    async activatePlugin(pluginId, plugin, callback) {
+        try {
+            // Call the activation callback
+            if (callback) {
+                await callback();
+            }
+            // Call plugin's onSecretsReady if defined
+            if (plugin.onSecretsReady) {
+                await plugin.onSecretsReady(this.runtime);
+            }
+            this.activatedPlugins.add(pluginId);
+            this.pendingPlugins.delete(pluginId);
+            logger.info(`[PluginActivator] Activated plugin ${pluginId}`);
+            // Notify secretsReady listeners
+            const listeners = this.secretsReadyListeners.get(pluginId);
+            if (listeners) {
+                for (const listener of listeners) {
+                    try {
+                        await listener(this.runtime);
+                    }
+                    catch (error) {
+                        const errorMessage = error instanceof Error ? error.message : String(error);
+                        logger.error(`[PluginActivator] onSecretsReady listener failed for ${pluginId}: ${errorMessage}`);
+                    }
+                }
+            }
+            return true;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.error(`[PluginActivator] Failed to activate plugin ${pluginId}: ${errorMessage}`);
+            return false;
+        }
+    }
+    /**
+     * Check requirements for a plugin
+     */
+    async checkPluginRequirements(plugin) {
+        if (!plugin.requiredSecrets) {
+            return {
+                pluginId: plugin.name,
+                ready: true,
+                missingRequired: [],
+                missingOptional: [],
+                invalid: [],
+                message: "No secrets required",
+            };
+        }
+        if (!this.secretsService) {
+            // Can't check without secrets service
+            const required = Object.entries(plugin.requiredSecrets)
+                .filter(([_, req]) => req.required)
+                .map(([key]) => key);
+            return {
+                pluginId: plugin.name,
+                ready: required.length === 0,
+                missingRequired: required,
+                missingOptional: [],
+                invalid: [],
+                message: "SecretsService not available",
+            };
+        }
+        const result = await this.secretsService.checkPluginRequirements(plugin.name, plugin.requiredSecrets);
+        return {
+            pluginId: plugin.name,
+            ...result,
+            message: result.ready
+                ? "All secrets available"
+                : `Missing: ${result.missingRequired.join(", ")}`,
+        };
+    }
+    /**
+     * Get status of all registered plugins
+     */
+    getPluginStatuses() {
+        const statuses = new Map();
+        for (const [pluginId, pending] of this.pendingPlugins) {
+            statuses.set(pluginId, {
+                pending: true,
+                activated: false,
+                missingSecrets: pending.requiredSecrets,
+            });
+        }
+        for (const pluginId of this.activatedPlugins) {
+            statuses.set(pluginId, {
+                pending: false,
+                activated: true,
+                missingSecrets: [],
+            });
+        }
+        return statuses;
+    }
+    // ============================================================================
+    // Secret Change Handling
+    // ============================================================================
+    /**
+     * Handle secret change event
+     */
+    async onSecretChanged(key, value, context) {
+        // Only process global secret changes for plugin activation
+        if (context.level !== "global") {
+            return;
+        }
+        // Check if any pending plugins need this secret
+        const affectedPlugins = this.pluginSecretMapping.get(key);
+        // First, check pending plugins for activation
+        if (affectedPlugins && affectedPlugins.size > 0) {
+            logger.debug(`[PluginActivator] Secret ${key} changed, checking ${affectedPlugins.size} plugins`);
+            for (const pluginId of affectedPlugins) {
+                const pending = this.pendingPlugins.get(pluginId);
+                if (!pending) {
+                    continue;
+                }
+                // Check if all required secrets are now available
+                const missing = await this.getMissingSecrets(pending.requiredSecrets);
+                if (missing.length === 0) {
+                    logger.info(`[PluginActivator] All secrets available for ${pluginId}, activating`);
+                    await pending.callback();
+                }
+            }
+        }
+        // Notify all activated plugins that depend on this secret
+        await this.notifySecretChanged(key, value);
+    }
+    /**
+     * Notify activated plugins about a secret change.
+     */
+    async notifySecretChanged(key, value) {
+        // Notify registered plugins with onSecretChanged callback
+        for (const [pluginId, registered] of this.registeredPlugins) {
+            // Only notify if this plugin depends on this secret
+            if (!registered.secretKeys.includes(key)) {
+                continue;
+            }
+            // Only notify activated plugins
+            if (!this.activatedPlugins.has(pluginId)) {
+                continue;
+            }
+            const plugin = registered.plugin;
+            if (plugin.onSecretChanged) {
+                try {
+                    logger.debug(`[PluginActivator] Notifying plugin ${pluginId} of secret change: ${key}`);
+                    await plugin.onSecretChanged(key, value, this.runtime);
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    logger.error(`[PluginActivator] Plugin ${pluginId} onSecretChanged failed: ${errorMessage}`);
+                }
+            }
+        }
+        // Notify registered listeners for this specific secret
+        const specificListeners = this.secretChangedListeners.get(key);
+        if (specificListeners) {
+            for (const listener of specificListeners) {
+                try {
+                    await listener(key, value, this.runtime);
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    logger.error(`[PluginActivator] Secret changed listener failed for ${key}: ${errorMessage}`);
+                }
+            }
+        }
+        // Notify global listeners (subscribed to all secrets)
+        const globalListeners = this.secretChangedListeners.get("__ALL_SECRETS__");
+        if (globalListeners) {
+            for (const listener of globalListeners) {
+                try {
+                    await listener(key, value, this.runtime);
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    logger.error(`[PluginActivator] Global secret changed listener failed for ${key}: ${errorMessage}`);
+                }
+            }
+        }
+    }
+    /**
+     * Get missing secrets from a list
+     */
+    async getMissingSecrets(keys) {
+        if (!this.secretsService) {
+            return keys;
+        }
+        return this.secretsService.getMissingSecrets(keys, "global");
+    }
+    // ============================================================================
+    // Polling
+    // ============================================================================
+    /**
+     * Start polling for pending plugins
+     */
+    startPolling() {
+        if (this.pollingInterval) {
+            return;
+        }
+        this.pollingInterval = setInterval(async () => {
+            await this.checkPendingPlugins();
+        }, this.activatorConfig.pollingIntervalMs);
+        logger.debug(`[PluginActivator] Started polling every ${this.activatorConfig.pollingIntervalMs}ms`);
+    }
+    /**
+     * Check all pending plugins
+     */
+    async checkPendingPlugins() {
+        if (this.pendingPlugins.size === 0) {
+            return;
+        }
+        const now = Date.now();
+        for (const [pluginId, pending] of this.pendingPlugins) {
+            // Check timeout
+            if (this.activatorConfig.maxWaitMs > 0) {
+                const elapsed = now - pending.registeredAt;
+                if (elapsed > this.activatorConfig.maxWaitMs) {
+                    logger.warn(`[PluginActivator] Plugin ${pluginId} timed out waiting for secrets`);
+                    this.unregisterPlugin(pluginId);
+                    continue;
+                }
+            }
+            // Check if secrets are now available
+            const missing = await this.getMissingSecrets(pending.requiredSecrets);
+            if (missing.length === 0) {
+                logger.info(`[PluginActivator] Secrets now available for ${pluginId}`);
+                await pending.callback();
+            }
+        }
+    }
+    // ============================================================================
+    // Utility Methods
+    // ============================================================================
+    /**
+     * Get list of pending plugins
+     */
+    getPendingPlugins() {
+        return Array.from(this.pendingPlugins.keys());
+    }
+    /**
+     * Get list of activated plugins
+     */
+    getActivatedPlugins() {
+        return Array.from(this.activatedPlugins);
+    }
+    /**
+     * Check if a plugin is pending
+     */
+    isPending(pluginId) {
+        return this.pendingPlugins.has(pluginId);
+    }
+    /**
+     * Check if a plugin is activated
+     */
+    isActivated(pluginId) {
+        return this.activatedPlugins.has(pluginId);
+    }
+    /**
+     * Get secrets required by pending plugins
+     */
+    getRequiredSecrets() {
+        const secrets = new Set();
+        for (const pending of this.pendingPlugins.values()) {
+            for (const key of pending.requiredSecrets) {
+                secrets.add(key);
+            }
+        }
+        return secrets;
+    }
+    /**
+     * Get plugins waiting for a specific secret
+     */
+    getPluginsWaitingFor(secretKey) {
+        const plugins = this.pluginSecretMapping.get(secretKey);
+        return plugins ? Array.from(plugins) : [];
+    }
+    // ============================================================================
+    // Callback Subscription Methods
+    // ============================================================================
+    /**
+     * Subscribe to secrets ready event for a specific plugin.
+     * The callback will be invoked when all required secrets for the plugin become available.
+     *
+     * @param pluginId - Plugin identifier to subscribe to
+     * @param callback - Callback to invoke when secrets are ready
+     * @returns Unsubscribe function
+     */
+    onSecretsReady(pluginId, callback) {
+        const listeners = this.secretsReadyListeners.get(pluginId) ?? [];
+        listeners.push(callback);
+        this.secretsReadyListeners.set(pluginId, listeners);
+        // If already activated, call immediately
+        if (this.activatedPlugins.has(pluginId)) {
+            callback(this.runtime).catch((error) => {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.error(`[PluginActivator] onSecretsReady callback failed for ${pluginId}: ${errorMessage}`);
+            });
+        }
+        return () => {
+            const currentListeners = this.secretsReadyListeners.get(pluginId);
+            if (currentListeners) {
+                const index = currentListeners.indexOf(callback);
+                if (index !== -1) {
+                    currentListeners.splice(index, 1);
+                }
+                if (currentListeners.length === 0) {
+                    this.secretsReadyListeners.delete(pluginId);
+                }
+            }
+        };
+    }
+    /**
+     * Subscribe to secret changed events for a specific secret key.
+     * The callback will be invoked whenever the specified secret changes.
+     *
+     * @param secretKey - Secret key to subscribe to
+     * @param callback - Callback to invoke when secret changes
+     * @returns Unsubscribe function
+     */
+    onSecretChangedKey(secretKey, callback) {
+        const listeners = this.secretChangedListeners.get(secretKey) ?? [];
+        listeners.push(callback);
+        this.secretChangedListeners.set(secretKey, listeners);
+        return () => {
+            const currentListeners = this.secretChangedListeners.get(secretKey);
+            if (currentListeners) {
+                const index = currentListeners.indexOf(callback);
+                if (index !== -1) {
+                    currentListeners.splice(index, 1);
+                }
+                if (currentListeners.length === 0) {
+                    this.secretChangedListeners.delete(secretKey);
+                }
+            }
+        };
+    }
+    /**
+     * Subscribe to all secret changed events.
+     * The callback will be invoked whenever any secret changes.
+     *
+     * @param callback - Callback to invoke when any secret changes
+     * @returns Unsubscribe function
+     */
+    onAnySecretChanged(callback) {
+        // Use a special key for global listeners
+        const globalKey = "__ALL_SECRETS__";
+        const listeners = this.secretChangedListeners.get(globalKey) ?? [];
+        listeners.push(callback);
+        this.secretChangedListeners.set(globalKey, listeners);
+        return () => {
+            const currentListeners = this.secretChangedListeners.get(globalKey);
+            if (currentListeners) {
+                const index = currentListeners.indexOf(callback);
+                if (index !== -1) {
+                    currentListeners.splice(index, 1);
+                }
+                if (currentListeners.length === 0) {
+                    this.secretChangedListeners.delete(globalKey);
+                }
+            }
+        };
+    }
+    /**
+     * Get the registered plugin by ID.
+     */
+    getRegisteredPlugin(pluginId) {
+        return this.registeredPlugins.get(pluginId)?.plugin;
+    }
+    /**
+     * Get all registered plugin IDs.
+     */
+    getRegisteredPluginIds() {
+        return Array.from(this.registeredPlugins.keys());
+    }
+    /**
+     * Check if a plugin has the onSecretChanged callback.
+     */
+    hasSecretChangedCallback(pluginId) {
+        const registered = this.registeredPlugins.get(pluginId);
+        return registered?.plugin.onSecretChanged !== undefined;
+    }
+    /**
+     * Check if a plugin has the onSecretsReady callback.
+     */
+    hasSecretsReadyCallback(pluginId) {
+        const registered = this.registeredPlugins.get(pluginId);
+        return registered?.plugin.onSecretsReady !== undefined;
+    }
+}