@elizaos/agent 2.0.0-alpha.97 → 2.0.0-beta.1

package/dist/packages/agent/src/api/plugin-runtime-apply.d.ts

@@ -0,0 +1,31 @@
+import { type AgentRuntime } from "@elizaos/core";
+import type { ElizaConfig } from "../config/config.ts";
+import type { ResolvedPlugin } from "../runtime/plugin-types.ts";
+export type PluginRuntimeApplyMode = "none" | "config_apply" | "plugin_reload" | "runtime_reload" | "restart_required";
+export interface PluginRuntimeApplyResult {
+    mode: PluginRuntimeApplyMode;
+    requiresRestart: boolean;
+    restartedRuntime: boolean;
+    loadedPackages: string[];
+    unloadedPackages: string[];
+    reloadedPackages: string[];
+    appliedConfigPackage: string | null;
+    reason: string;
+}
+interface ApplyPluginRuntimeMutationOptions {
+    runtime: AgentRuntime | null;
+    previousConfig: ElizaConfig;
+    nextConfig: ElizaConfig;
+    previousResolvedPlugins?: ResolvedPlugin[];
+    nextResolvedPlugins?: ResolvedPlugin[];
+    changedPluginId?: string;
+    changedPluginPackage?: string;
+    config?: Record<string, string>;
+    forceReloadPackages?: string[];
+    expectRuntimeGraphChange?: boolean;
+    reason: string;
+    restartRuntime?: (reason: string) => Promise<boolean>;
+}
+export declare function applyPluginRuntimeMutation(options: ApplyPluginRuntimeMutationOptions): Promise<PluginRuntimeApplyResult>;
+export {};
+//# sourceMappingURL=plugin-runtime-apply.d.ts.map

package/dist/packages/agent/src/api/plugin-runtime-apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-runtime-apply.d.ts","sourceRoot":"","sources":["../../../../../src/api/plugin-runtime-apply.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAU,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE,MAAM,MAAM,sBAAsB,GAC9B,MAAM,GACN,cAAc,GACd,eAAe,GACf,gBAAgB,GAChB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,eAAe,EAAE,OAAO,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,iCAAiC;IACzC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,WAAW,CAAC;IAC5B,UAAU,EAAE,WAAW,CAAC;IACxB,uBAAuB,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3C,mBAAmB,CAAC,EAAE,cAAc,EAAE,CAAC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD;AAqFD,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,wBAAwB,CAAC,CAmNnC"}

package/dist/packages/agent/src/api/plugin-runtime-apply.js

@@ -0,0 +1,217 @@
+import { logger } from "@elizaos/core";
+import { supportsRuntimePluginLifecycle } from "../runtime/plugin-lifecycle.js";
+function normalizePluginIdentity(value) {
+    return value
+        .replace(/^@[^/]+\//, "")
+        .replace(/^plugin-/, "")
+        .trim()
+        .toLowerCase();
+}
+function buildResolvedPluginMap(plugins) {
+    return new Map(plugins.map((plugin) => [plugin.name, plugin]));
+}
+function resolveTargetPackageName(runtime, previousResolvedMap, nextResolvedMap, changedPluginId, changedPluginPackage) {
+    if (changedPluginPackage &&
+        (previousResolvedMap.has(changedPluginPackage) ||
+            nextResolvedMap.has(changedPluginPackage))) {
+        return changedPluginPackage;
+    }
+    const targetId = changedPluginId
+        ? normalizePluginIdentity(changedPluginId)
+        : null;
+    if (!targetId)
+        return null;
+    for (const packageName of [
+        ...previousResolvedMap.keys(),
+        ...nextResolvedMap.keys(),
+    ]) {
+        if (normalizePluginIdentity(packageName) === targetId) {
+            return packageName;
+        }
+    }
+    const runtimePlugins = Array.isArray(runtime.plugins)
+        ? runtime.plugins
+        : [];
+    for (const plugin of runtimePlugins) {
+        if (normalizePluginIdentity(plugin.name) !== targetId)
+            continue;
+        for (const [packageName, resolvedPlugin] of nextResolvedMap) {
+            if (resolvedPlugin.plugin.name === plugin.name) {
+                return packageName;
+            }
+        }
+        for (const [packageName, resolvedPlugin] of previousResolvedMap) {
+            if (resolvedPlugin.plugin.name === plugin.name) {
+                return packageName;
+            }
+        }
+    }
+    return null;
+}
+async function resolvePluginsForConfig(config) {
+    const { resolvePlugins } = await import("../runtime/plugin-resolver.js");
+    return await resolvePlugins(config, { quiet: true });
+}
+function packageRequiresRuntimeReload(packageName, previousResolvedMap, nextResolvedMap) {
+    const previousPlugin = previousResolvedMap.get(packageName)?.plugin;
+    const nextPlugin = nextResolvedMap.get(packageName)?.plugin;
+    return Boolean(previousPlugin?.adapter || nextPlugin?.adapter);
+}
+export async function applyPluginRuntimeMutation(options) {
+    const { runtime, previousConfig, nextConfig, changedPluginId, changedPluginPackage, config, forceReloadPackages = [], expectRuntimeGraphChange = false, reason, restartRuntime, } = options;
+    if (!runtime) {
+        return {
+            mode: "none",
+            requiresRestart: false,
+            restartedRuntime: false,
+            loadedPackages: [],
+            unloadedPackages: [],
+            reloadedPackages: [],
+            appliedConfigPackage: null,
+            reason,
+        };
+    }
+    const tryRuntimeRestart = async () => {
+        if (!restartRuntime) {
+            return {
+                mode: "restart_required",
+                requiresRestart: true,
+                restartedRuntime: false,
+                loadedPackages: [],
+                unloadedPackages: [],
+                reloadedPackages: [],
+                appliedConfigPackage: null,
+                reason,
+            };
+        }
+        const restartedRuntime = await restartRuntime(reason);
+        return {
+            mode: restartedRuntime ? "runtime_reload" : "restart_required",
+            requiresRestart: !restartedRuntime,
+            restartedRuntime,
+            loadedPackages: [],
+            unloadedPackages: [],
+            reloadedPackages: [],
+            appliedConfigPackage: null,
+            reason,
+        };
+    };
+    let previousResolvedPlugins;
+    let nextResolvedPlugins;
+    try {
+        previousResolvedPlugins =
+            options.previousResolvedPlugins ??
+                (await resolvePluginsForConfig(previousConfig));
+        nextResolvedPlugins =
+            options.nextResolvedPlugins ??
+                (await resolvePluginsForConfig(nextConfig));
+    }
+    catch (error) {
+        logger.warn(`[plugin-runtime-apply] Failed to resolve plugin graph for "${reason}": ${error instanceof Error ? error.message : String(error)}`);
+        return await tryRuntimeRestart();
+    }
+    const previousResolvedMap = buildResolvedPluginMap(previousResolvedPlugins);
+    const nextResolvedMap = buildResolvedPluginMap(nextResolvedPlugins);
+    const previousPackages = new Set(previousResolvedMap.keys());
+    const nextPackages = new Set(nextResolvedMap.keys());
+    const removedPackages = [...previousPackages].filter((packageName) => !nextPackages.has(packageName));
+    const addedPackages = [...nextPackages].filter((packageName) => !previousPackages.has(packageName));
+    const targetPackageName = resolveTargetPackageName(runtime, previousResolvedMap, nextResolvedMap, changedPluginId, changedPluginPackage);
+    let appliedConfigPackage = null;
+    const reloadPackages = new Set(forceReloadPackages);
+    if (config &&
+        targetPackageName &&
+        nextResolvedMap.has(targetPackageName) &&
+        !removedPackages.includes(targetPackageName)) {
+        const runtimePluginName = nextResolvedMap.get(targetPackageName)?.plugin.name;
+        let appliedConfig = false;
+        try {
+            if (runtimePluginName &&
+                supportsRuntimePluginLifecycle(runtime) &&
+                (await runtime.applyPluginConfig?.(runtimePluginName, config))) {
+                appliedConfig = true;
+            }
+        }
+        catch (error) {
+            logger.warn(`[plugin-runtime-apply] In-place config apply failed for ${targetPackageName}: ${error instanceof Error ? error.message : String(error)}`);
+            appliedConfig = false;
+        }
+        if (appliedConfig) {
+            appliedConfigPackage = targetPackageName;
+        }
+        else {
+            reloadPackages.add(targetPackageName);
+        }
+    }
+    if (removedPackages.length === 0 &&
+        addedPackages.length === 0 &&
+        reloadPackages.size === 0) {
+        if (expectRuntimeGraphChange && !appliedConfigPackage) {
+            return await tryRuntimeRestart();
+        }
+        return {
+            mode: appliedConfigPackage ? "config_apply" : "none",
+            requiresRestart: false,
+            restartedRuntime: false,
+            loadedPackages: [],
+            unloadedPackages: [],
+            reloadedPackages: [],
+            appliedConfigPackage,
+            reason,
+        };
+    }
+    const allChangedPackages = new Set([
+        ...removedPackages,
+        ...addedPackages,
+        ...reloadPackages,
+    ]);
+    const needsRuntimeReload = [...allChangedPackages].some((packageName) => packageRequiresRuntimeReload(packageName, previousResolvedMap, nextResolvedMap));
+    if (!supportsRuntimePluginLifecycle(runtime) || needsRuntimeReload) {
+        const restartResult = await tryRuntimeRestart();
+        return { ...restartResult, appliedConfigPackage };
+    }
+    const unloadedPackages = [];
+    const loadedPackages = [];
+    const reloadedPackages = [];
+    try {
+        for (const packageName of [
+            ...removedPackages,
+            ...[...reloadPackages].filter((name) => previousResolvedMap.has(name)),
+        ]) {
+            const runtimePluginName = previousResolvedMap.get(packageName)?.plugin.name;
+            if (!runtimePluginName)
+                continue;
+            await runtime.unloadPlugin?.(runtimePluginName);
+            unloadedPackages.push(packageName);
+        }
+        for (const packageName of reloadPackages) {
+            const nextResolved = nextResolvedMap.get(packageName);
+            if (!nextResolved)
+                continue;
+            await runtime.registerPlugin(nextResolved.plugin);
+            reloadedPackages.push(packageName);
+        }
+        for (const packageName of addedPackages) {
+            const nextResolved = nextResolvedMap.get(packageName);
+            if (!nextResolved)
+                continue;
+            await runtime.registerPlugin(nextResolved.plugin);
+            loadedPackages.push(packageName);
+        }
+        return {
+            mode: "plugin_reload",
+            requiresRestart: false,
+            restartedRuntime: false,
+            loadedPackages,
+            unloadedPackages,
+            reloadedPackages,
+            appliedConfigPackage,
+            reason,
+        };
+    }
+    catch (error) {
+        logger.warn(`[plugin-runtime-apply] Plugin reload failed for "${reason}": ${error instanceof Error ? error.message : String(error)}`);
+        const restartResult = await tryRuntimeRestart();
+        return { ...restartResult, appliedConfigPackage };
+    }
+}

package/dist/packages/agent/src/api/plugin-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-validation.d.ts","sourceRoot":"","sources":["../../../../../src/api/plugin-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,MAAM,WAAW,sBAAsB;IACrC,6DAA6D;IAC7D,KAAK,EAAE,OAAO,CAAC;IACf,wDAAwD;IACxD,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,wDAAwD;IACxD,QAAQ,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,4CAA4C;AAC5C,MAAM,WAAW,8BAA8B;IAC7C,0EAA0E;IAC1E,KAAK,EAAE,OAAO,CAAC;IACf,sDAAsD;IACtD,YAAY,EAAE,OAAO,CAAC;IACtB,iCAAiC;IACjC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sCAAsC;IACtC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,0CAA0C;IAC1C,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mFAAmF;IACnF,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC;AAED,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAsBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,UAAU,EAAE,MAAM,EAAE,EACpB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACvC,SAAS,CAAC,EAAE,eAAe,EAAE,GAC5B,sBAAsB,CAqGxB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,GAAE,MAAU,GACnB,8BAA8B,CAsFhC;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,MAAM,EAAE,EACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAoB,GACzC,IAAI,CAoCN"}

package/dist/packages/agent/src/api/plugin-validation.js

@@ -0,0 +1,261 @@
+/**
+ * Plugin configuration validation.
+ *
+ * Validates plugin configuration by checking all required parameters
+ * from the plugin's agentConfig.pluginParameters definition, plus
+ * provider-specific API key format checks.
+ *
+ * Also provides runtime context validation to detect null, undefined,
+ * empty, and non-serializable fields in context objects.
+ */
+// ---------------------------------------------------------------------------
+// API key prefix patterns for format validation
+// ---------------------------------------------------------------------------
+const KEY_PREFIX_HINTS = {
+    ANTHROPIC_API_KEY: { prefix: "sk-ant-", label: "Anthropic" },
+    OPENAI_API_KEY: { prefix: "sk-", label: "OpenAI" },
+    GROQ_API_KEY: { prefix: "gsk_", label: "Groq" },
+    XAI_API_KEY: { prefix: "xai-", label: "xAI" },
+    OPENROUTER_API_KEY: { prefix: "sk-or-", label: "OpenRouter" },
+    DEEPSEEK_API_KEY: { prefix: "sk-", label: "DeepSeek" },
+    MOONSHOT_API_KEY: { prefix: "sk-", label: "Kimi / Moonshot" },
+};
+// ---------------------------------------------------------------------------
+// Validation logic
+// ---------------------------------------------------------------------------
+/**
+ * Validate a plugin's configuration.
+ *
+ * Checks all required parameters (from the plugin's package.json metadata)
+ * and applies format-specific warnings for known API key patterns.
+ *
+ * @param pluginId - The plugin identifier (e.g. "anthropic", "discord")
+ * @param category - Plugin category
+ * @param envKey - Primary environment variable key (legacy, used as fallback)
+ * @param configKeys - All known config key names for this plugin
+ * @param providedConfig - Config values being set (for PUT validation)
+ * @param paramDefs - Full parameter definitions with required/sensitive metadata
+ */
+export function validatePluginConfig(_pluginId, _category, envKey, configKeys, providedConfig, paramDefs) {
+    const errors = [];
+    const warnings = [];
+    const allowedConfigKeys = new Set(configKeys);
+    const canonicalKeyByNormalized = new Map(configKeys.map((key) => [key.trim().toUpperCase(), key]));
+    if (providedConfig) {
+        for (const key of Object.keys(providedConfig)) {
+            if (allowedConfigKeys.has(key))
+                continue;
+            const canonical = canonicalKeyByNormalized.get(key.trim().toUpperCase());
+            if (canonical) {
+                errors.push({
+                    field: key,
+                    message: `${key} does not match declared config key casing; use ${canonical}`,
+                });
+                continue;
+            }
+            errors.push({
+                field: key,
+                message: `${key} is not a declared config key for this plugin`,
+            });
+        }
+    }
+    // ── Check all required parameters ─────────────────────────────────────
+    if (paramDefs && paramDefs.length > 0) {
+        for (const param of paramDefs) {
+            if (!param.required)
+                continue;
+            // Value source: provided config > process.env > undefined
+            const value = providedConfig?.[param.key] ?? process.env[param.key];
+            if (!value?.trim()) {
+                // Required param with a default is a warning, not an error
+                if (param.default) {
+                    warnings.push({
+                        field: param.key,
+                        message: `${param.key} is not set (will use default: ${param.default})`,
+                    });
+                }
+                else {
+                    errors.push({
+                        field: param.key,
+                        message: `${param.key} is required but not set`,
+                    });
+                }
+                continue;
+            }
+            // Format validation for known key patterns
+            const hint = KEY_PREFIX_HINTS[param.key];
+            if (hint && !value.startsWith(hint.prefix)) {
+                warnings.push({
+                    field: param.key,
+                    message: `${hint.label} key should start with "${hint.prefix}" — the current value may be invalid`,
+                });
+            }
+            // Length sanity check for sensitive keys (API keys / tokens)
+            if (param.sensitive && value.trim().length < 10) {
+                warnings.push({
+                    field: param.key,
+                    message: `${param.key} looks too short (${value.trim().length} chars)`,
+                });
+            }
+        }
+    }
+    else if (envKey) {
+        // Fallback: no param definitions, but we know the primary env key
+        const currentValue = providedConfig?.[envKey] ?? process.env[envKey];
+        if (!currentValue?.trim()) {
+            errors.push({
+                field: envKey,
+                message: `${envKey} is required but not set`,
+            });
+        }
+        else {
+            const hint = KEY_PREFIX_HINTS[envKey];
+            if (hint && !currentValue.startsWith(hint.prefix)) {
+                warnings.push({
+                    field: envKey,
+                    message: `${hint.label} key should start with "${hint.prefix}" — the current value may be invalid`,
+                });
+            }
+            // Length sanity check for keys/tokens that look suspiciously short
+            if (currentValue.trim().length < 10) {
+                warnings.push({
+                    field: envKey,
+                    message: `${envKey} looks too short (${currentValue.trim().length} chars)`,
+                });
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+// ---------------------------------------------------------------------------
+// Runtime context validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate a runtime context object for null, undefined, empty, and
+ * non-serializable fields.
+ *
+ * Used after provider + plugin resolution to detect and surface invalid
+ * or malformed context early — before it reaches the agent runtime.
+ *
+ * @param context - The context object to validate.
+ * @param maxDepth - Maximum nesting depth to inspect (default: 5).
+ */
+export function validateRuntimeContext(context, maxDepth = 5) {
+    const nullFields = [];
+    const undefinedFields = [];
+    const emptyFields = [];
+    const nonSerializableFields = [];
+    function walk(obj, prefix, depth) {
+        if (depth > maxDepth)
+            return;
+        for (const [key, value] of Object.entries(obj)) {
+            const path = prefix ? `${prefix}.${key}` : key;
+            if (value === null) {
+                nullFields.push(path);
+                continue;
+            }
+            if (value === undefined) {
+                undefinedFields.push(path);
+                continue;
+            }
+            if (typeof value === "string" && value.trim() === "") {
+                emptyFields.push(path);
+                continue;
+            }
+            // Check for non-serializable values
+            if (typeof value === "function") {
+                nonSerializableFields.push(path);
+                continue;
+            }
+            if (typeof value === "symbol") {
+                nonSerializableFields.push(path);
+                continue;
+            }
+            if (typeof value === "bigint") {
+                nonSerializableFields.push(path);
+                continue;
+            }
+            // Recurse into plain objects
+            if (typeof value === "object" &&
+                !Array.isArray(value) &&
+                !(value instanceof Date) &&
+                !(value instanceof RegExp)) {
+                walk(value, path, depth + 1);
+            }
+        }
+    }
+    walk(context, "", 0);
+    // Check overall serialization
+    let serializable = true;
+    if (nonSerializableFields.length > 0) {
+        serializable = false;
+    }
+    else {
+        try {
+            JSON.stringify(context);
+        }
+        catch {
+            serializable = false;
+        }
+    }
+    const valid = nullFields.length === 0 &&
+        undefinedFields.length === 0 &&
+        emptyFields.length === 0;
+    return {
+        valid,
+        serializable,
+        nullFields,
+        undefinedFields,
+        emptyFields,
+        nonSerializableFields,
+    };
+}
+// ---------------------------------------------------------------------------
+// Plugin context debug logging
+// ---------------------------------------------------------------------------
+/**
+ * Log the full resolved plugin/provider context for debugging.
+ *
+ * Prints a structured summary of all loaded plugins, providers,
+ * and any validation issues detected in the context.
+ *
+ * @param plugins - Array of resolved plugin names.
+ * @param providers - Array of resolved provider names.
+ * @param context - The runtime context object to inspect.
+ * @param log - Logger function (defaults to console.debug).
+ */
+export function debugLogResolvedContext(plugins, providers, context, log = console.debug) {
+    log("[eliza:debug] ══════ Resolved Plugin/Provider Context ══════");
+    log(`[eliza:debug] Plugins loaded (${plugins.length}):`);
+    for (const name of plugins) {
+        log(`[eliza:debug]   • ${name}`);
+    }
+    log(`[eliza:debug] Providers loaded (${providers.length}):`);
+    for (const name of providers) {
+        log(`[eliza:debug]   • ${name}`);
+    }
+    const validation = validateRuntimeContext(context);
+    if (validation.valid && validation.serializable) {
+        log("[eliza:debug] Context validation: ✓ PASS (all fields valid, serializable)");
+    }
+    else {
+        log("[eliza:debug] Context validation: ✗ ISSUES DETECTED");
+        if (validation.nullFields.length > 0) {
+            log(`[eliza:debug]   null fields: ${validation.nullFields.join(", ")}`);
+        }
+        if (validation.undefinedFields.length > 0) {
+            log(`[eliza:debug]   undefined fields: ${validation.undefinedFields.join(", ")}`);
+        }
+        if (validation.emptyFields.length > 0) {
+            log(`[eliza:debug]   empty fields: ${validation.emptyFields.join(", ")}`);
+        }
+        if (validation.nonSerializableFields.length > 0) {
+            log(`[eliza:debug]   non-serializable fields: ${validation.nonSerializableFields.join(", ")}`);
+        }
+    }
+    log("[eliza:debug] ══════════════════════════════════════════════");
+}

package/dist/packages/agent/src/api/provider-switch-config.d.ts

@@ -0,0 +1,62 @@
+import type { DeploymentTargetConfig, LinkedAccountFlagsConfig, ServiceCapability, ServiceRoutingConfig } from "@elizaos/shared";
+import { type OnboardingConnection, type OnboardingCredentialInputs } from "@elizaos/shared";
+import type { ElizaConfig } from "../config/types.eliza.ts";
+type MutableElizaConfig = Partial<ElizaConfig> & {
+    cloud?: Record<string, unknown>;
+    models?: Record<string, unknown>;
+    wallet?: {
+        rpcProviders?: Record<string, string>;
+    };
+    deploymentTarget?: DeploymentTargetConfig;
+    linkedAccounts?: LinkedAccountFlagsConfig;
+    serviceRouting?: ServiceRoutingConfig;
+};
+export declare function applyCanonicalOnboardingConfig(config: MutableElizaConfig, args: {
+    deploymentTarget?: DeploymentTargetConfig | null;
+    linkedAccounts?: LinkedAccountFlagsConfig | null;
+    serviceRouting?: ServiceRoutingConfig | null;
+    clearRoutes?: readonly ServiceCapability[];
+}): void;
+/**
+ * Apply subscription provider configuration to the config object.
+ *
+ * Sets `agents.defaults.subscriptionProvider` so the task-agent orchestrator
+ * knows which subscription is active.
+ *
+ * For providers with a runtime model-provider plugin, also sets
+ * `agents.defaults.model.primary`. Anthropic subscriptions are restricted to
+ * Claude Code CLI (TOS), so `model.primary` is NOT set for that provider.
+ *
+ * Mutates `config` in place.
+ */
+export declare function applySubscriptionProviderConfig(config: Partial<ElizaConfig>, provider: string): void;
+/**
+ * Clear subscription provider configuration from the config object.
+ *
+ * Removes `agents.defaults.subscriptionProvider` so the runtime
+ * doesn't try to auto-detect a subscription provider on restart.
+ *
+ * Mutates `config` in place.
+ */
+export declare function clearSubscriptionProviderConfig(config: Partial<ElizaConfig>): void;
+/**
+ * Clear persisted onboarding state that should force the UI back through the
+ * onboarding flow on the next load/reset.
+ */
+export declare function clearPersistedOnboardingConfig(config: MutableElizaConfig): void;
+export declare function createProviderSwitchConnection(args: {
+    provider: string;
+    apiKey?: string;
+    primaryModel?: string;
+}): OnboardingConnection | null;
+export interface ApplyOnboardingConnectionOptions {
+    useLocalEmbeddings?: boolean;
+}
+export declare function applyOnboardingConnectionConfig(config: MutableElizaConfig, connection: OnboardingConnection, options?: ApplyOnboardingConnectionOptions): Promise<void>;
+export declare function applyOnboardingCredentialPersistence(config: MutableElizaConfig, args: {
+    credentialInputs?: OnboardingCredentialInputs | null;
+    deploymentTarget?: DeploymentTargetConfig | null;
+    serviceRouting?: ServiceRoutingConfig | null;
+}): Promise<string | null>;
+export {};
+//# sourceMappingURL=provider-switch-config.d.ts.map

package/dist/packages/agent/src/api/provider-switch-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-switch-config.d.ts","sourceRoot":"","sources":["../../../../../src/api/provider-switch-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,wBAAwB,EACxB,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAgBL,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAIhC,MAAM,iBAAiB,CAAC;AASzB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,KAAK,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IACnD,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAC1C,cAAc,CAAC,EAAE,wBAAwB,CAAC;IAC1C,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC,CAAC;AAuHF,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE;IACJ,gBAAgB,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACjD,cAAc,CAAC,EAAE,wBAAwB,GAAG,IAAI,CAAC;IACjD,cAAc,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC7C,WAAW,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC5C,GACA,IAAI,CAUN;AAmWD;;;;;;;;;;;GAWG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,EAC5B,QAAQ,EAAE,MAAM,GACf,IAAI,CAyBN;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,GAC3B,IAAI,CAIN;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,kBAAkB,GACzB,IAAI,CAgFN;AAED,wBAAgB,8BAA8B,CAAC,IAAI,EAAE;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,oBAAoB,GAAG,IAAI,CAmB9B;AAED,MAAM,WAAW,gCAAgC;IAC/C,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,kBAAkB,EAC1B,UAAU,EAAE,oBAAoB,EAChC,OAAO,GAAE,gCAAqC,GAC7C,OAAO,CAAC,IAAI,CAAC,CA0Lf;AAED,wBAAsB,oCAAoC,CACxD,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE;IACJ,gBAAgB,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAAC;IACrD,gBAAgB,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACjD,cAAc,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC9C,GACA,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAkCxB"}