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

package/packages/typescript/src/features/secrets/onboarding/service.js

@@ -0,0 +1,436 @@
+/**
+ * Onboarding Service
+ *
+ * Manages the secrets onboarding flow across platforms (Discord, Telegram, etc.)
+ * Supports both conversational and form-based collection modes.
+ *
+ * Integrates with the OnboardingStateMachine for
+ * consistent state management across CLI and conversational interfaces.
+ */
+import { logger } from "../../../logger.js";
+import { isOnboardingComplete as isStateMachineComplete, OnboardingStateMachine, } from "../../../services/onboarding-state.js";
+import { Service } from "../../../types/index.js";
+import { DEFAULT_ONBOARDING_MESSAGES, getNextSetting, getUnconfiguredRequired, isOnboardingComplete, } from "./config.js";
+export const ONBOARDING_SERVICE_TYPE = "SECRETS_ONBOARDING";
+/**
+ * Onboarding Service for secrets collection.
+ */
+export class OnboardingService extends Service {
+    static serviceType = ONBOARDING_SERVICE_TYPE;
+    capabilityDescription = "Manage secrets onboarding across chat platforms";
+    secretsService = null;
+    sessions = new Map();
+    /** State machine instances keyed by worldId */
+    stateMachines = new Map();
+    /**
+     * Start the service
+     */
+    static async start(runtime) {
+        const service = new OnboardingService(runtime);
+        await service.initialize();
+        return service;
+    }
+    /**
+     * Initialize the service
+     */
+    async initialize() {
+        logger.info("[OnboardingService] Starting");
+        // Get secrets service
+        this.secretsService = this.runtime.getService("SECRETS");
+        // Register platform events
+        this.registerEvents();
+        logger.info("[OnboardingService] Started");
+    }
+    async stop() {
+        logger.info("[OnboardingService] Stopping");
+        this.sessions.clear();
+        this.stateMachines.clear();
+        logger.info("[OnboardingService] Stopped");
+    }
+    /**
+     * Get or create a state machine for a specific world.
+     * This ensures state is persisted per world and can resume across restarts.
+     */
+    async getOrCreateStateMachine(worldId, userId, platform = "other") {
+        // Check if we already have a state machine for this world
+        const existing = this.stateMachines.get(worldId);
+        if (existing) {
+            return existing;
+        }
+        // Try to restore from world metadata
+        const world = await this.runtime.getWorld(worldId);
+        const metadata = world?.metadata;
+        const savedState = metadata?.onboardingStateMachine;
+        const config = {
+            platform,
+            mode: "conversational",
+            worldId,
+            userId,
+            onStepChange: async (oldStep, newStep, _context) => {
+                logger.info(`[OnboardingService] Step changed: ${oldStep} -> ${newStep} for world ${worldId}`);
+                // Persist state on each step change
+                await this.persistStateMachine(worldId);
+            },
+            onComplete: async (_context) => {
+                logger.info(`[OnboardingService] Onboarding complete for world ${worldId}`);
+                // Final persistence
+                await this.persistStateMachine(worldId);
+            },
+            onError: (error, _context) => {
+                logger.error({ error, worldId }, `[OnboardingService] Onboarding error: ${error.message}`);
+            },
+        };
+        let stateMachine;
+        if (savedState) {
+            // Restore from saved state
+            logger.info(`[OnboardingService] Restoring state machine for world ${worldId}`);
+            stateMachine = OnboardingStateMachine.fromJSON(savedState, config);
+        }
+        else {
+            // Create new state machine
+            logger.info(`[OnboardingService] Creating new state machine for world ${worldId}`);
+            stateMachine = new OnboardingStateMachine(config);
+        }
+        this.stateMachines.set(worldId, stateMachine);
+        return stateMachine;
+    }
+    /**
+     * Persist the state machine state to world metadata.
+     */
+    async persistStateMachine(worldId) {
+        const stateMachine = this.stateMachines.get(worldId);
+        if (!stateMachine) {
+            return;
+        }
+        const world = await this.runtime.getWorld(worldId);
+        if (!world) {
+            logger.warn(`[OnboardingService] Cannot persist state machine - world ${worldId} not found`);
+            return;
+        }
+        const metadata = (world.metadata || {});
+        metadata.onboardingStateMachine = stateMachine.toJSON();
+        world.metadata = metadata;
+        await this.runtime.updateWorld(world);
+        logger.debug(`[OnboardingService] Persisted state machine for world ${worldId}`);
+    }
+    /**
+     * Get the current onboarding step from the state machine.
+     */
+    getOnboardingStep(worldId) {
+        const stateMachine = this.stateMachines.get(worldId);
+        return stateMachine?.getCurrentStep() ?? null;
+    }
+    /**
+     * Get the full onboarding context from the state machine.
+     */
+    getOnboardingContext(worldId) {
+        const stateMachine = this.stateMachines.get(worldId);
+        return stateMachine?.getContext() ?? null;
+    }
+    /**
+     * Check if onboarding is complete via the state machine.
+     */
+    isStateMachineComplete(worldId) {
+        const stateMachine = this.stateMachines.get(worldId);
+        if (!stateMachine) {
+            return false;
+        }
+        return isStateMachineComplete(stateMachine.getContext());
+    }
+    /**
+     * Register platform-specific event handlers.
+     */
+    registerEvents() {
+        // Discord: Bot joins a server
+        this.runtime.registerEvent("DISCORD_WORLD_JOINED", async (params) => {
+            const server = params.server;
+            if (server) {
+                logger.info(`[OnboardingService] Discord world joined: ${server.id}`);
+            }
+            // Onboarding will be triggered when owner sends DM
+        });
+        // Discord: Server connected (bot already in server)
+        this.runtime.registerEvent("DISCORD_SERVER_CONNECTED", async (params) => {
+            const server = params.server;
+            if (server) {
+                logger.info(`[OnboardingService] Discord server connected: ${server.id}`);
+            }
+        });
+        // Telegram: Bot joins a group
+        this.runtime.registerEvent("TELEGRAM_WORLD_JOINED", async (params) => {
+            const typedParams = params;
+            if (typedParams.world &&
+                typedParams.chat &&
+                typedParams.entities &&
+                typedParams.botUsername) {
+                logger.info(`[OnboardingService] Telegram world joined: ${typedParams.world.id}`);
+                await this.startTelegramOnboarding(typedParams.world, typedParams.chat, typedParams.entities, typedParams.botUsername);
+            }
+        });
+    }
+    /**
+     * Initialize onboarding for a world with the given config.
+     */
+    async initializeOnboarding(world, config) {
+        logger.info(`[OnboardingService] Initializing onboarding for world: ${world.id}`);
+        // Store config in world metadata
+        if (!world.metadata) {
+            world.metadata = {};
+        }
+        // Initialize settings state from config
+        const settingsState = {};
+        for (const [key, setting] of Object.entries(config.settings)) {
+            settingsState[key] = {
+                ...setting,
+                value: null,
+            };
+        }
+        // Store settings using dynamic property access
+        const metadata = world.metadata;
+        metadata.settings = settingsState;
+        metadata.onboardingConfig = config;
+        await this.runtime.updateWorld(world);
+        logger.info(`[OnboardingService] Onboarding initialized for world: ${world.id}`);
+    }
+    /**
+     * Start onboarding via DM (Discord).
+     */
+    async startDiscordOnboardingDM(serverId, ownerId, worldId, config) {
+        const messages = config.messages?.welcome || DEFAULT_ONBOARDING_MESSAGES.welcome;
+        const _randomMessage = messages[Math.floor(Math.random() * messages.length)];
+        // This would be called by the Discord plugin after it sends the DM
+        // The actual DM sending is done by the Discord plugin
+        logger.info(`[OnboardingService] Discord DM onboarding started - server: ${serverId}, owner: ${ownerId}, world: ${worldId}`);
+    }
+    /**
+     * Start onboarding via deep link (Telegram).
+     */
+    async startTelegramOnboarding(_world, chat, entities, botUsername) {
+        // Find the owner
+        let ownerId = null;
+        let ownerUsername = null;
+        for (const entity of entities) {
+            if (entity.metadata?.telegram?.adminTitle === "Owner") {
+                ownerId = entity.metadata.telegram.id;
+                ownerUsername = entity.metadata.telegram.username;
+                break;
+            }
+        }
+        if (!ownerId) {
+            logger.warn("[OnboardingService] No owner found for Telegram group");
+            return;
+        }
+        // Send deep link message to group
+        const telegramService = this.runtime.getService("telegram");
+        if (telegramService?.messageManager) {
+            const deepLinkMessage = [
+                `Hello @${ownerUsername}! Could we take a few minutes to get everything set up?`,
+                `Please click this link to start chatting with me: https://t.me/${botUsername}?start=onboarding`,
+            ].join(" ");
+            await telegramService.messageManager.sendMessage(chat.id, {
+                text: deepLinkMessage,
+            });
+            logger.info(`[OnboardingService] Sent Telegram deep link - chatId: ${chat.id}, ownerId: ${ownerId}`);
+        }
+    }
+    /**
+     * Start a new onboarding session.
+     */
+    async startSession(worldId, userId, roomId, config, platform = "other", mode = "conversational") {
+        // Get or create state machine for this world
+        const stateMachine = await this.getOrCreateStateMachine(worldId, userId, platform);
+        const session = {
+            worldId,
+            userId,
+            roomId,
+            config,
+            currentSettingKey: null,
+            startedAt: Date.now(),
+            lastActivityAt: Date.now(),
+            platform,
+            mode,
+            stateMachine,
+        };
+        this.sessions.set(roomId, session);
+        logger.info(`[OnboardingService] Session started - roomId: ${roomId}, worldId: ${worldId}, userId: ${userId}, step: ${stateMachine.getCurrentStep()}`);
+        return session;
+    }
+    /**
+     * Get an active session by room ID.
+     */
+    getSession(roomId) {
+        return this.sessions.get(roomId) || null;
+    }
+    /**
+     * Process a user message during onboarding.
+     */
+    async processMessage(roomId, message) {
+        const session = this.sessions.get(roomId);
+        if (!session) {
+            return { shouldRespond: false };
+        }
+        session.lastActivityAt = Date.now();
+        // Get current state
+        const unconfigured = getUnconfiguredRequired(session.config);
+        if (unconfigured.length === 0) {
+            // All required settings configured
+            return {
+                shouldRespond: true,
+                response: session.config.messages?.allComplete ||
+                    DEFAULT_ONBOARDING_MESSAGES.allComplete,
+                complete: true,
+            };
+        }
+        // Try to extract a setting value from the message
+        const text = message.content?.text || "";
+        const currentSetting = session.currentSettingKey
+            ? session.config.settings[session.currentSettingKey]
+            : null;
+        // If we have a current setting being asked, try to match the response
+        if (currentSetting && text.trim()) {
+            const value = text.trim();
+            const currentSettingKey = session.currentSettingKey;
+            if (!currentSettingKey) {
+                return {
+                    shouldRespond: true,
+                    response: "I lost track of which setting I was collecting. Let's try that again.",
+                };
+            }
+            // Validate if validation exists
+            if (currentSetting.validation && !currentSetting.validation(value)) {
+                return {
+                    shouldRespond: true,
+                    response: `That doesn't look like a valid ${currentSetting.name}. ${currentSetting.usageDescription || "Please try again."}`,
+                };
+            }
+            // Store the value
+            if (this.secretsService) {
+                const context = {
+                    level: "world",
+                    agentId: this.runtime.agentId,
+                    worldId: session.worldId,
+                    userId: session.userId,
+                };
+                await this.secretsService.set(currentSettingKey, value, context, {
+                    description: currentSetting.description,
+                    type: currentSetting.type,
+                    encrypted: currentSetting.secret,
+                });
+            }
+            // Update local state
+            session.config.settings[currentSettingKey].value = value;
+            // Check if complete
+            if (isOnboardingComplete(session.config)) {
+                this.sessions.delete(roomId);
+                return {
+                    shouldRespond: true,
+                    response: session.config.messages?.allComplete ||
+                        DEFAULT_ONBOARDING_MESSAGES.allComplete,
+                    updatedKey: currentSettingKey,
+                    complete: true,
+                };
+            }
+            // Get next setting
+            const next = getNextSetting(session.config);
+            if (next) {
+                const [nextKey, nextSetting] = next;
+                session.currentSettingKey = nextKey;
+                const askMessage = (session.config.messages?.askSetting ||
+                    DEFAULT_ONBOARDING_MESSAGES.askSetting)
+                    .replace("{{settingName}}", nextSetting.name)
+                    .replace("{{usageDescription}}", nextSetting.usageDescription || nextSetting.description);
+                return {
+                    shouldRespond: true,
+                    response: `${session.config.messages?.settingUpdated || DEFAULT_ONBOARDING_MESSAGES.settingUpdated.replace("{{settingName}}", currentSetting.name)}\n\n${askMessage}`,
+                    updatedKey: session.currentSettingKey,
+                };
+            }
+        }
+        // Start asking for the first/next setting
+        const next = getNextSetting(session.config);
+        if (next) {
+            const [nextKey, nextSetting] = next;
+            session.currentSettingKey = nextKey;
+            const askMessage = (session.config.messages?.askSetting ||
+                DEFAULT_ONBOARDING_MESSAGES.askSetting)
+                .replace("{{settingName}}", nextSetting.name)
+                .replace("{{usageDescription}}", nextSetting.usageDescription || nextSetting.description);
+            return {
+                shouldRespond: true,
+                response: askMessage,
+            };
+        }
+        return { shouldRespond: false };
+    }
+    /**
+     * End an onboarding session.
+     */
+    endSession(roomId) {
+        this.sessions.delete(roomId);
+        logger.info(`[OnboardingService] Session ended - roomId: ${roomId}`);
+    }
+    /**
+     * Get the onboarding status for a world.
+     */
+    async getOnboardingStatus(worldId) {
+        const world = await this.runtime.getWorld(worldId);
+        if (!world?.metadata?.settings) {
+            return {
+                initialized: false,
+                complete: false,
+                configuredCount: 0,
+                requiredCount: 0,
+                missingRequired: [],
+            };
+        }
+        const settings = world.metadata.settings;
+        const entries = Object.entries(settings);
+        const required = entries.filter(([_, s]) => s.required);
+        const configured = required.filter(([_, s]) => s.value !== null);
+        const missing = required
+            .filter(([_, s]) => s.value === null)
+            .map(([k, _]) => k);
+        return {
+            initialized: true,
+            complete: missing.length === 0,
+            configuredCount: configured.length,
+            requiredCount: required.length,
+            missingRequired: missing,
+        };
+    }
+    /**
+     * Generate the SETTINGS provider context for LLM.
+     */
+    generateSettingsContext(config, isOnboarding, agentName) {
+        const entries = Object.entries(config.settings);
+        const unconfigured = getUnconfiguredRequired(config);
+        const settingsList = entries
+            .map(([key, setting]) => {
+            const _status = setting.value !== null ? "Configured" : "Not set";
+            const required = setting.required ? "(Required)" : "(Optional)";
+            const value = setting.secret && setting.value
+                ? "****************"
+                : setting.value || "Not set";
+            return `${key}: ${value} ${required}\n(${setting.name}) ${setting.usageDescription || setting.description}`;
+        })
+            .join("\n\n");
+        const validKeys = `Valid setting keys: ${entries.map(([k, _]) => k).join(", ")}`;
+        if (isOnboarding && unconfigured.length > 0) {
+            return `# PRIORITY TASK: Onboarding
+
+${agentName} needs to help the user configure ${unconfigured.length} required settings:
+
+${settingsList}
+
+${validKeys}
+
+Instructions for ${agentName}:
+- Only update settings if the user is clearly responding to a setting you are currently asking about.
+- If the user's reply clearly maps to a setting and a valid value, you **must** call the UPDATE_SETTINGS action.
+- Never hallucinate settings or respond with values not listed above.
+- Prioritize configuring required settings before optional ones.`;
+        }
+        return `## Current Configuration
+${unconfigured.length > 0 ? `IMPORTANT: ${unconfigured.length} required settings still need configuration.\n\n` : "All required settings are configured.\n\n"}${settingsList}`;
+    }
+}

package/packages/typescript/src/features/secrets/providers/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Providers module exports
+ */
+export { secretsInfoProvider, secretsStatusProvider, } from "./secrets-status.ts";
+//# sourceMappingURL=index.d.ts.map

package/packages/typescript/src/features/secrets/providers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../typescript/src/features/secrets/providers/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACN,mBAAmB,EACnB,qBAAqB,GACrB,MAAM,qBAAqB,CAAC"}

package/packages/typescript/src/features/secrets/providers/index.js

@@ -0,0 +1,4 @@
+/**
+ * Providers module exports
+ */
+export { secretsInfoProvider, secretsStatusProvider, } from "./secrets-status.js";

package/packages/typescript/src/features/secrets/providers/secrets-status.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Secrets Status Provider
+ *
+ * Provides context about the agent's secret configuration status
+ * to help the LLM understand what capabilities are available.
+ */
+import type { Provider } from "../../../types/index.ts";
+/**
+ * Secrets Status Provider
+ *
+ * Adds information about configured secrets to the agent's context,
+ * without exposing actual secret values.
+ */
+export declare const secretsStatusProvider: Provider;
+/**
+ * Secrets Info Provider
+ *
+ * Provides detailed information about specific secrets when relevant
+ * to the current conversation context.
+ */
+export declare const secretsInfoProvider: Provider;
+//# sourceMappingURL=secrets-status.d.ts.map

package/packages/typescript/src/features/secrets/providers/secrets-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets-status.d.ts","sourceRoot":"","sources":["../../../../../../../../typescript/src/features/secrets/providers/secrets-status.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAGX,QAAQ,EAGR,MAAM,yBAAyB,CAAC;AASjC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,QAmGnC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAkFjC,CAAC"}

package/packages/typescript/src/features/secrets/providers/secrets-status.js

@@ -0,0 +1,160 @@
+/**
+ * Secrets Status Provider
+ *
+ * Provides context about the agent's secret configuration status
+ * to help the LLM understand what capabilities are available.
+ */
+import { logger } from "../../../logger.js";
+import { PLUGIN_ACTIVATOR_SERVICE_TYPE, } from "../services/plugin-activator.js";
+import { SECRETS_SERVICE_TYPE, } from "../services/secrets.js";
+/**
+ * Secrets Status Provider
+ *
+ * Adds information about configured secrets to the agent's context,
+ * without exposing actual secret values.
+ */
+export const secretsStatusProvider = {
+    name: "SECRETS_STATUS",
+    description: "Provides information about configured secrets and their status",
+    dynamic: true,
+    get: async (runtime, _message, _state) => {
+        const secretsService = runtime.getService(SECRETS_SERVICE_TYPE);
+        if (!secretsService) {
+            return { text: "" };
+        }
+        try {
+            // Get global secrets status
+            const globalSecrets = await secretsService.list({
+                level: "global",
+                agentId: runtime.agentId,
+            });
+            const secretKeys = Object.keys(globalSecrets);
+            if (secretKeys.length === 0) {
+                return {
+                    text: `[Secrets Status]
+No secrets are currently configured. The agent may need API keys or other credentials to access certain services.`,
+                };
+            }
+            // Categorize secrets by status
+            const valid = [];
+            const missing = [];
+            const invalid = [];
+            for (const [key, config] of Object.entries(globalSecrets)) {
+                switch (config.status) {
+                    case "valid":
+                        valid.push(key);
+                        break;
+                    case "missing":
+                        missing.push(key);
+                        break;
+                    case "invalid":
+                    case "expired":
+                    case "revoked":
+                        invalid.push(key);
+                        break;
+                    default:
+                        valid.push(key);
+                }
+            }
+            // Build status message
+            const lines = ["[Secrets Status]"];
+            if (valid.length > 0) {
+                lines.push(`Configured secrets: ${valid.join(", ")}`);
+            }
+            if (invalid.length > 0) {
+                lines.push(`Invalid/expired secrets: ${invalid.join(", ")}`);
+            }
+            if (missing.length > 0) {
+                lines.push(`Missing required secrets: ${missing.join(", ")}`);
+            }
+            // Check plugin activator for pending plugins
+            const activatorService = runtime.getService(PLUGIN_ACTIVATOR_SERVICE_TYPE);
+            if (activatorService) {
+                const pendingPlugins = activatorService.getPendingPlugins();
+                if (pendingPlugins.length > 0) {
+                    lines.push(`Plugins waiting for secrets: ${pendingPlugins.join(", ")}`);
+                    const requiredSecrets = activatorService.getRequiredSecrets();
+                    if (requiredSecrets.size > 0) {
+                        lines.push(`Secrets needed for pending plugins: ${Array.from(requiredSecrets).join(", ")}`);
+                    }
+                }
+            }
+            return { text: lines.join("\n") };
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            logger.error(`[SecretsStatusProvider] Error getting secrets status: ${errorMsg}`);
+            return { text: "" };
+        }
+    },
+};
+/**
+ * Secrets Info Provider
+ *
+ * Provides detailed information about specific secrets when relevant
+ * to the current conversation context.
+ */
+export const secretsInfoProvider = {
+    name: "SECRETS_INFO",
+    description: "Provides detailed secret information based on conversation context",
+    dynamic: true,
+    get: async (runtime, message, _state) => {
+        const secretsService = runtime.getService(SECRETS_SERVICE_TYPE);
+        if (!secretsService) {
+            return { text: "" };
+        }
+        const text = message.content.text?.toLowerCase() ?? "";
+        // Check if message is about secrets
+        const isAboutSecrets = /\b(secret|key|token|credential|api|password|configure)\b/i.test(text);
+        if (!isAboutSecrets) {
+            return { text: "" };
+        }
+        try {
+            const globalSecrets = await secretsService.list({
+                level: "global",
+                agentId: runtime.agentId,
+            });
+            const secretCount = Object.keys(globalSecrets).length;
+            if (secretCount === 0) {
+                return {
+                    text: `[Secrets Info]
+No secrets configured. User can set secrets by saying things like "Set my OPENAI_API_KEY to sk-..."`,
+                };
+            }
+            // Build detailed info
+            const lines = ["[Secrets Info]"];
+            lines.push(`Total configured secrets: ${secretCount}`);
+            // Group by type
+            const byType = {};
+            for (const [key, config] of Object.entries(globalSecrets)) {
+                const type = config.type ?? "secret";
+                if (!byType[type]) {
+                    byType[type] = [];
+                }
+                byType[type].push(key);
+            }
+            for (const [type, keys] of Object.entries(byType)) {
+                lines.push(`${type}: ${keys.join(", ")}`);
+            }
+            // Check for common missing secrets that might be relevant
+            const commonSecrets = [
+                "OPENAI_API_KEY",
+                "ANTHROPIC_API_KEY",
+                "DISCORD_BOT_TOKEN",
+                "TELEGRAM_BOT_TOKEN",
+                "TWITTER_API_KEY",
+            ];
+            const missingCommon = commonSecrets.filter((key) => !globalSecrets[key]);
+            if (missingCommon.length > 0 &&
+                missingCommon.length < commonSecrets.length) {
+                lines.push(`Common secrets not set: ${missingCommon.join(", ")}`);
+            }
+            return { text: lines.join("\n") };
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            logger.error(`[SecretsInfoProvider] Error: ${errorMsg}`);
+            return { text: "" };
+        }
+    },
+};