@elizaos/agent 0.25.9 → 2.0.0-alpha.151

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

@@ -0,0 +1,337 @@
+/**
+ * Update Settings Action
+ *
+ * Extracts and saves setting values from natural language user messages.
+ * Uses LLM to parse user responses and map them to settings.
+ */
+import { logger } from "../../../logger.js";
+import { ChannelType, ModelType } from "../../../types/index.js";
+import { validateSecret } from "../validation.js";
+/**
+ * Extract setting values from user message using LLM.
+ */
+async function extractSettingValues(runtime, message, state, settings) {
+    // Find unconfigured settings
+    const unconfigured = Object.entries(settings).filter(([_, s]) => s.value === null);
+    if (unconfigured.length === 0) {
+        return [];
+    }
+    // Build context for LLM
+    const settingsContext = unconfigured
+        .map(([key, setting]) => {
+        const requiredStr = setting.required ? "Required." : "Optional.";
+        return `${key}: ${setting.description} ${requiredStr}`;
+    })
+        .join("\n");
+    const prompt = `I need to extract settings values from the user's message.
+
+Available settings:
+${settingsContext}
+
+User message: ${state.text || message.content?.text || ""}
+
+For each setting mentioned in the user's message, extract the value.
+
+Only return settings that are clearly mentioned in the user's message.
+If a setting is mentioned but no clear value is provided, do not include it.`;
+    // Use LLM to extract settings
+    const result = await runtime.useModel(ModelType.OBJECT_LARGE, {
+        prompt,
+        output: "array",
+        schema: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    key: { type: "string" },
+                    value: { type: "string" },
+                },
+                required: ["key", "value"],
+            },
+        },
+    });
+    if (!result) {
+        return [];
+    }
+    // Validate extracted settings exist in our config
+    const validUpdates = [];
+    const extractFromResult = (obj) => {
+        if (Array.isArray(obj)) {
+            for (const item of obj) {
+                extractFromResult(item);
+            }
+        }
+        else if (typeof obj === "object" && obj !== null) {
+            for (const [key, value] of Object.entries(obj)) {
+                if (settings[key] && typeof value !== "object") {
+                    validUpdates.push({ key, value: value });
+                }
+                else {
+                    extractFromResult(value);
+                }
+            }
+        }
+    };
+    extractFromResult(result);
+    return validUpdates;
+}
+/**
+ * Process setting updates and save to storage.
+ */
+async function processSettingUpdates(runtime, world, settings, updates, secretsService) {
+    if (!updates.length) {
+        return { updatedAny: false, messages: [] };
+    }
+    const messages = [];
+    let updatedAny = false;
+    const updatedSettings = { ...settings };
+    for (const update of updates) {
+        const setting = updatedSettings[update.key];
+        if (!setting)
+            continue;
+        // Check dependencies
+        if (setting.dependsOn?.length) {
+            const dependenciesMet = setting.dependsOn.every((dep) => {
+                const depSetting = updatedSettings[dep];
+                return depSetting && depSetting.value !== null;
+            });
+            if (!dependenciesMet) {
+                messages.push(`Cannot update ${setting.name} - dependencies not met`);
+                continue;
+            }
+        }
+        // Validate
+        const valueStr = String(update.value);
+        if (setting.validation && !setting.validation(valueStr)) {
+            messages.push(`Invalid value for ${setting.name}`);
+            continue;
+        }
+        if (setting.validationMethod) {
+            const validation = await validateSecret(update.key, valueStr, setting.validationMethod);
+            if (!validation.isValid) {
+                messages.push(`Validation failed for ${setting.name}: ${validation.error}`);
+                continue;
+            }
+        }
+        // Update local state
+        updatedSettings[update.key] = {
+            ...setting,
+            value: valueStr,
+        };
+        // Store in secrets service if available
+        if (secretsService) {
+            const context = {
+                level: "world",
+                agentId: runtime.agentId,
+                worldId: world.id,
+            };
+            await secretsService.set(update.key, valueStr, context, {
+                description: setting.description,
+                type: setting.type,
+                encrypted: setting.secret,
+            });
+        }
+        messages.push(`Updated ${setting.name} successfully`);
+        updatedAny = true;
+        // Execute onSetAction if defined
+        if (setting.onSetAction) {
+            const actionMessage = setting.onSetAction(update.value);
+            if (actionMessage) {
+                messages.push(actionMessage);
+            }
+        }
+    }
+    // Save updated settings to world metadata
+    if (updatedAny) {
+        if (!world.metadata) {
+            world.metadata = {};
+        }
+        // Cast to allow storing our extended settings type
+        world.metadata.settings = updatedSettings;
+        await runtime.updateWorld(world);
+    }
+    return { updatedAny, messages };
+}
+/**
+ * Get the next setting to configure.
+ */
+function getNextRequiredSetting(settings) {
+    const entries = Object.entries(settings);
+    // Find unconfigured required settings
+    for (const [key, setting] of entries) {
+        if (!setting.required || setting.value !== null)
+            continue;
+        // Check dependencies
+        const dependenciesMet = (setting.dependsOn || []).every((dep) => {
+            const depSetting = settings[dep];
+            return depSetting && depSetting.value !== null;
+        });
+        if (dependenciesMet) {
+            return [key, setting];
+        }
+    }
+    return null;
+}
+/**
+ * Count unconfigured required settings.
+ */
+function countUnconfiguredRequired(settings) {
+    return Object.values(settings).filter((s) => s.required && s.value === null)
+        .length;
+}
+/**
+ * UPDATE_SETTINGS Action - extracts and saves settings from natural language.
+ */
+export const updateSettingsAction = {
+    name: "UPDATE_SETTINGS",
+    similes: ["UPDATE_SETTING", "SAVE_SETTING", "SET_CONFIGURATION", "CONFIGURE"],
+    description: "Saves a configuration setting during the onboarding process. Use when onboarding with a world owner or admin.",
+    validate: async (runtime, message, _state, _options) => {
+        const text = message.content?.text?.toLowerCase() ?? "";
+        const hasUpdateIntent = ["update", "settings"].some((keyword) => text.includes(keyword)) &&
+            /\b(?:update|settings)\b/i.test(text);
+        if (!hasUpdateIntent || message.content.channelType !== ChannelType.DM) {
+            return false;
+        }
+        const room = await runtime.getRoom(message.roomId);
+        if (!room?.worldId)
+            return false;
+        const world = await runtime.getWorld(room.worldId);
+        if (!world?.metadata?.settings)
+            return false;
+        const settings = world.metadata.settings;
+        return Object.values(settings).some((setting) => setting.value === null);
+    },
+    handler: async (runtime, message, state, _options, callback) => {
+        if (!state || !callback) {
+            return {
+                text: "State and callback required",
+                values: { success: false },
+                data: { actionName: "UPDATE_SETTINGS" },
+                success: false,
+            };
+        }
+        // Get room and world
+        const room = await runtime.getRoom(message.roomId);
+        if (!room?.worldId) {
+            await callback({ text: "Unable to find room configuration." });
+            return {
+                text: "Room not found",
+                values: { success: false },
+                data: { actionName: "UPDATE_SETTINGS" },
+                success: false,
+            };
+        }
+        const world = await runtime.getWorld(room.worldId);
+        if (!world?.metadata?.settings) {
+            await callback({ text: "No settings configured for this world." });
+            return {
+                text: "No settings found",
+                values: { success: false },
+                data: { actionName: "UPDATE_SETTINGS" },
+                success: false,
+            };
+        }
+        const settings = world.metadata.settings;
+        // Get secrets service
+        const secretsService = runtime.getService("SECRETS");
+        // Extract settings from message
+        logger.info("[UpdateSettings] Extracting settings from message");
+        const extractedSettings = await extractSettingValues(runtime, message, state, settings);
+        logger.info(`[UpdateSettings] Extracted ${extractedSettings.length} settings`);
+        // Process updates
+        const results = await processSettingUpdates(runtime, world, settings, extractedSettings, secretsService);
+        // Get updated settings
+        const updatedWorld = await runtime.getWorld(room.worldId);
+        const updatedSettings = updatedWorld?.metadata?.settings;
+        if (results.updatedAny) {
+            const remaining = countUnconfiguredRequired(updatedSettings || settings);
+            if (remaining === 0) {
+                // All required settings configured
+                await callback({
+                    text: `${results.messages.join("\n")}\n\nAll required settings have been configured! You're all set.`,
+                    actions: ["ONBOARDING_COMPLETE"],
+                });
+                return {
+                    text: "Onboarding complete",
+                    values: { success: true, onboardingComplete: true },
+                    data: {
+                        actionName: "UPDATE_SETTINGS",
+                        action: "ONBOARDING_COMPLETE",
+                    },
+                    success: true,
+                };
+            }
+            // More settings needed
+            const next = getNextRequiredSetting(updatedSettings || settings);
+            const nextPrompt = next
+                ? `\n\nNext, I need your ${next[1].name}. ${next[1].usageDescription || next[1].description}`
+                : "";
+            await callback({
+                text: `${results.messages.join("\n")}${nextPrompt}`,
+                actions: ["SETTING_UPDATED"],
+            });
+            return {
+                text: "Settings updated",
+                values: { success: true, remainingRequired: remaining },
+                data: {
+                    actionName: "UPDATE_SETTINGS",
+                    action: "SETTING_UPDATED",
+                    updated: extractedSettings.map((s) => s.key),
+                },
+                success: true,
+            };
+        }
+        // No settings extracted
+        const next = getNextRequiredSetting(settings);
+        const prompt = next
+            ? `I couldn't understand that. I need your ${next[1].name}. ${next[1].usageDescription || next[1].description}`
+            : "I couldn't extract any settings from your message. Could you try again?";
+        await callback({
+            text: prompt,
+            actions: ["SETTING_UPDATE_FAILED"],
+        });
+        return {
+            text: "No settings updated",
+            values: { success: false },
+            data: { actionName: "UPDATE_SETTINGS", action: "SETTING_UPDATE_FAILED" },
+            success: false,
+        };
+    },
+    examples: [
+        [
+            {
+                name: "{{name1}}",
+                content: {
+                    text: "My OpenAI key is sk-abc123def456",
+                    source: "discord",
+                },
+            },
+            {
+                name: "{{name2}}",
+                content: {
+                    text: "Got it! I've saved your OpenAI API Key. Next, I need your Anthropic API Key.",
+                    actions: ["SETTING_UPDATED"],
+                    source: "discord",
+                },
+            },
+        ],
+        [
+            {
+                name: "{{name1}}",
+                content: {
+                    text: "Here's my Twitter login: @myhandle with password secret123",
+                    source: "discord",
+                },
+            },
+            {
+                name: "{{name2}}",
+                content: {
+                    text: "Perfect! I've updated your Twitter Username and Twitter Password. We're all set!",
+                    actions: ["ONBOARDING_COMPLETE"],
+                    source: "discord",
+                },
+            },
+        ],
+    ],
+};

package/packages/typescript/src/features/secrets/onboarding/config.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Onboarding configuration types and utilities.
+ *
+ * Provides the structure for defining secret requirements per agent/plugin,
+ * supporting both conversational and form-based collection flows.
+ */
+import type { SecretType } from "../types.ts";
+/**
+ * Setting definition for onboarding.
+ * Compatible with the-org OnboardingConfig format.
+ */
+export interface OnboardingSetting {
+    /** Display name */
+    name: string;
+    /** Description for LLM context */
+    description: string;
+    /** Prompt shown when asking user for this setting */
+    usageDescription?: string;
+    /** Whether this is a secret (should be encrypted) */
+    secret: boolean;
+    /** Whether this should be visible in non-onboarding contexts */
+    public: boolean;
+    /** Whether this setting is required */
+    required: boolean;
+    /** Settings that must be configured first */
+    dependsOn: string[];
+    /** Validation function */
+    validation?: (value: string) => boolean;
+    /** Validation method name (openai, anthropic, url, etc.) */
+    validationMethod?: string;
+    /** Secret type */
+    type?: SecretType;
+    /** Environment variable to sync to */
+    envVar?: string;
+    /** Default value if not set */
+    defaultValue?: string;
+    /** Current value (set during onboarding) */
+    value?: string | null;
+    /** Conditional visibility based on other settings */
+    visibleIf?: (settings: Record<string, OnboardingSetting>) => boolean;
+    /** Callback when value is set */
+    onSetAction?: (value: string | boolean) => string | undefined;
+}
+/**
+ * Onboarding configuration for an agent or plugin.
+ */
+export interface OnboardingConfig {
+    /** Setting definitions */
+    settings: Record<string, OnboardingSetting>;
+    /** Optional platform-specific messages */
+    messages?: {
+        welcome?: string[];
+        askSetting?: string;
+        settingUpdated?: string;
+        allComplete?: string;
+        error?: string;
+    };
+    /** Onboarding flow mode */
+    mode?: "conversational" | "form" | "hybrid";
+}
+/**
+ * Default onboarding messages.
+ */
+export declare const DEFAULT_ONBOARDING_MESSAGES: {
+    welcome: string[];
+    askSetting: string;
+    settingUpdated: string;
+    allComplete: string;
+    error: string;
+};
+/**
+ * Common API key settings for quick setup.
+ */
+export declare const COMMON_API_KEY_SETTINGS: Record<string, Partial<OnboardingSetting>>;
+/**
+ * Create an onboarding config from a list of required secret keys.
+ */
+export declare function createOnboardingConfig(requiredKeys: string[], optionalKeys?: string[], customSettings?: Record<string, Partial<OnboardingSetting>>): OnboardingConfig;
+/**
+ * Get unconfigured required settings from an onboarding config.
+ */
+export declare function getUnconfiguredRequired(config: OnboardingConfig): Array<[string, OnboardingSetting]>;
+/**
+ * Get unconfigured optional settings from an onboarding config.
+ */
+export declare function getUnconfiguredOptional(config: OnboardingConfig): Array<[string, OnboardingSetting]>;
+/**
+ * Check if all required settings are configured.
+ */
+export declare function isOnboardingComplete(config: OnboardingConfig): boolean;
+/**
+ * Get the next setting to configure (respects dependencies).
+ */
+export declare function getNextSetting(config: OnboardingConfig): [string, OnboardingSetting] | null;
+/**
+ * Generate a prompt for the LLM to ask for a specific setting.
+ */
+export declare function generateSettingPrompt(_key: string, setting: OnboardingSetting, agentName: string): string;
+//# sourceMappingURL=config.d.ts.map

package/packages/typescript/src/features/secrets/onboarding/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../../../../../typescript/src/features/secrets/onboarding/config.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,240 @@
+/**
+ * Onboarding configuration types and utilities.
+ *
+ * Provides the structure for defining secret requirements per agent/plugin,
+ * supporting both conversational and form-based collection flows.
+ */
+/**
+ * Default onboarding messages.
+ */
+export const DEFAULT_ONBOARDING_MESSAGES = {
+    welcome: [
+        "Hi! I need to collect some information to get set up. Is now a good time?",
+        "Hey there! I need to configure a few things. Do you have a moment?",
+        "Hello! Could we take a few minutes to get everything set up?",
+    ],
+    askSetting: "I need your {{settingName}}. {{usageDescription}}",
+    settingUpdated: "Got it! I've saved your {{settingName}}.",
+    allComplete: "Great! All required settings have been configured. You're all set!",
+    error: "I had trouble understanding that. Could you try again?",
+};
+/**
+ * Common API key settings for quick setup.
+ */
+export const COMMON_API_KEY_SETTINGS = {
+    OPENAI_API_KEY: {
+        name: "OpenAI API Key",
+        description: "API key for OpenAI services (GPT models)",
+        usageDescription: 'Your OpenAI API key starts with "sk-"',
+        secret: true,
+        public: false,
+        required: false,
+        dependsOn: [],
+        validationMethod: "openai",
+        type: "api_key",
+        envVar: "OPENAI_API_KEY",
+    },
+    ANTHROPIC_API_KEY: {
+        name: "Anthropic API Key",
+        description: "API key for Anthropic services (Claude models)",
+        usageDescription: 'Your Anthropic API key starts with "sk-ant-"',
+        secret: true,
+        public: false,
+        required: false,
+        dependsOn: [],
+        validationMethod: "anthropic",
+        type: "api_key",
+        envVar: "ANTHROPIC_API_KEY",
+    },
+    GROQ_API_KEY: {
+        name: "Groq API Key",
+        description: "API key for Groq inference services",
+        usageDescription: 'Your Groq API key starts with "gsk_"',
+        secret: true,
+        public: false,
+        required: false,
+        dependsOn: [],
+        validationMethod: "groq",
+        type: "api_key",
+        envVar: "GROQ_API_KEY",
+    },
+    GOOGLE_API_KEY: {
+        name: "Google API Key",
+        description: "API key for Google AI services (Gemini)",
+        usageDescription: "Your Google API key for Gemini models",
+        secret: true,
+        public: false,
+        required: false,
+        dependsOn: [],
+        validationMethod: "google",
+        type: "api_key",
+        envVar: "GOOGLE_API_KEY",
+    },
+    DISCORD_BOT_TOKEN: {
+        name: "Discord Bot Token",
+        description: "Bot token for Discord integration",
+        usageDescription: "Your Discord bot token from the developer portal",
+        secret: true,
+        public: false,
+        required: false,
+        dependsOn: [],
+        validationMethod: "discord",
+        type: "token",
+        envVar: "DISCORD_BOT_TOKEN",
+    },
+    TELEGRAM_BOT_TOKEN: {
+        name: "Telegram Bot Token",
+        description: "Bot token for Telegram integration",
+        usageDescription: "Your Telegram bot token from @BotFather",
+        secret: true,
+        public: false,
+        required: false,
+        dependsOn: [],
+        validationMethod: "telegram",
+        type: "token",
+        envVar: "TELEGRAM_BOT_TOKEN",
+    },
+    TWITTER_USERNAME: {
+        name: "Twitter Username",
+        description: "Twitter/X username for posting",
+        usageDescription: "The Twitter username (without @)",
+        secret: false,
+        public: true,
+        required: false,
+        dependsOn: [],
+        type: "credential",
+    },
+    TWITTER_PASSWORD: {
+        name: "Twitter Password",
+        description: "Twitter/X account password",
+        usageDescription: "The password for your Twitter account",
+        secret: true,
+        public: false,
+        required: false,
+        dependsOn: ["TWITTER_USERNAME"],
+        type: "credential",
+    },
+    TWITTER_EMAIL: {
+        name: "Twitter Email",
+        description: "Email associated with Twitter account",
+        usageDescription: "The email address linked to your Twitter account",
+        secret: false,
+        public: false,
+        required: false,
+        dependsOn: ["TWITTER_USERNAME"],
+        type: "credential",
+        validation: (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value),
+    },
+    TWITTER_2FA_SECRET: {
+        name: "Twitter 2FA Secret",
+        description: "2FA secret for Twitter account",
+        usageDescription: "The 2FA/TOTP secret (if 2FA is enabled)",
+        secret: true,
+        public: false,
+        required: false,
+        dependsOn: ["TWITTER_USERNAME", "TWITTER_PASSWORD"],
+        type: "credential",
+    },
+};
+/**
+ * Create an onboarding config from a list of required secret keys.
+ */
+export function createOnboardingConfig(requiredKeys, optionalKeys = [], customSettings = {}) {
+    const settings = {};
+    for (const key of requiredKeys) {
+        const common = COMMON_API_KEY_SETTINGS[key] || {};
+        const custom = customSettings[key] || {};
+        settings[key] = {
+            name: custom.name || common.name || key,
+            description: custom.description || common.description || `Configure ${key}`,
+            usageDescription: custom.usageDescription || common.usageDescription,
+            secret: custom.secret ?? common.secret ?? true,
+            public: custom.public ?? common.public ?? false,
+            required: true,
+            dependsOn: custom.dependsOn || common.dependsOn || [],
+            validationMethod: custom.validationMethod || common.validationMethod,
+            type: custom.type || common.type || "api_key",
+            envVar: custom.envVar || common.envVar || key,
+            value: null,
+            ...custom,
+        };
+    }
+    for (const key of optionalKeys) {
+        const common = COMMON_API_KEY_SETTINGS[key] || {};
+        const custom = customSettings[key] || {};
+        settings[key] = {
+            name: custom.name || common.name || key,
+            description: custom.description || common.description || `Configure ${key}`,
+            usageDescription: custom.usageDescription || common.usageDescription,
+            secret: custom.secret ?? common.secret ?? true,
+            public: custom.public ?? common.public ?? false,
+            required: false,
+            dependsOn: custom.dependsOn || common.dependsOn || [],
+            validationMethod: custom.validationMethod || common.validationMethod,
+            type: custom.type || common.type || "api_key",
+            envVar: custom.envVar || common.envVar || key,
+            value: null,
+            ...custom,
+        };
+    }
+    return { settings };
+}
+/**
+ * Get unconfigured required settings from an onboarding config.
+ */
+export function getUnconfiguredRequired(config) {
+    return Object.entries(config.settings).filter(([_, setting]) => setting.required && setting.value === null);
+}
+/**
+ * Get unconfigured optional settings from an onboarding config.
+ */
+export function getUnconfiguredOptional(config) {
+    return Object.entries(config.settings).filter(([_, setting]) => !setting.required && setting.value === null);
+}
+/**
+ * Check if all required settings are configured.
+ */
+export function isOnboardingComplete(config) {
+    return getUnconfiguredRequired(config).length === 0;
+}
+/**
+ * Get the next setting to configure (respects dependencies).
+ */
+export function getNextSetting(config) {
+    const unconfigured = getUnconfiguredRequired(config);
+    for (const [key, setting] of unconfigured) {
+        // Check if dependencies are met
+        const dependenciesMet = setting.dependsOn.every((dep) => {
+            const depSetting = config.settings[dep];
+            return depSetting && depSetting.value !== null;
+        });
+        // Check visibility condition
+        const isVisible = !setting.visibleIf || setting.visibleIf(config.settings);
+        if (dependenciesMet && isVisible) {
+            return [key, setting];
+        }
+    }
+    // If no required settings, try optional
+    const optionalUnconfigured = getUnconfiguredOptional(config);
+    for (const [key, setting] of optionalUnconfigured) {
+        const dependenciesMet = setting.dependsOn.every((dep) => {
+            const depSetting = config.settings[dep];
+            return depSetting && depSetting.value !== null;
+        });
+        const isVisible = !setting.visibleIf || setting.visibleIf(config.settings);
+        if (dependenciesMet && isVisible) {
+            return [key, setting];
+        }
+    }
+    return null;
+}
+/**
+ * Generate a prompt for the LLM to ask for a specific setting.
+ */
+export function generateSettingPrompt(_key, setting, agentName) {
+    const required = setting.required ? "(Required)" : "(Optional)";
+    const usage = setting.usageDescription || setting.description;
+    return (`${agentName} needs to collect the ${setting.name} ${required}.\n` +
+        `Description: ${usage}\n` +
+        `Ask the user for their ${setting.name} in a natural, conversational way.`);
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Onboarding Module
+ *
+ * Provides secrets onboarding functionality for collecting credentials
+ * from users through Discord, Telegram, and other platforms.
+ *
+ * Supports both conversational and form-based collection flows.
+ */
+export * from "./action.ts";
+export * from "./config.ts";
+export * from "./provider.ts";
+export * from "./service.ts";
+//# sourceMappingURL=index.d.ts.map