@elizaos/agent 0.25.9 → 2.0.0-alpha.151

package/packages/agent/src/api/plugin-routes.js

@@ -0,0 +1,1140 @@
+import { logger } from "@elizaos/core";
+import { isElizaSettingsDebugEnabled, sanitizeForSettingsDebug, settingsDebugCloudSummary, } from "@elizaos/shared";
+import { loadElizaConfig, saveElizaConfig } from "../config/config.js";
+import { getPluginWidgets, } from "../config/plugin-widgets.js";
+import { resolveDefaultAgentWorkspaceDir } from "../providers/workspace.js";
+import { CORE_PLUGINS, OPTIONAL_CORE_PLUGINS, } from "../runtime/core-plugins.js";
+import { applyPluginRuntimeMutation } from "./plugin-runtime-apply.js";
+import { validatePluginConfig, } from "./plugin-validation.js";
+/** Workspace packages use `@elizaos/plugin-*` or `@elizaos/app-*` — normalize list/toggle ids. */
+function optionalPluginListId(npmName) {
+    if (npmName.startsWith("@elizaos/app-")) {
+        return npmName.slice("@elizaos/".length);
+    }
+    return npmName.replace("@elizaos/plugin-", "");
+}
+const pluginsListInFlight = new WeakMap();
+// ---------------------------------------------------------------------------
+// Route handler
+// ---------------------------------------------------------------------------
+/**
+ * Handle plugin management routes (/api/plugins/*, /api/secrets, /api/core/*).
+ * Returns `true` if the request was handled.
+ */
+export async function handlePluginRoutes(ctx) {
+    const { req, res, method, pathname, state, json, error, readJsonBody, scheduleRuntimeRestart, restartRuntime, BLOCKED_ENV_KEYS, discoverInstalledPlugins, maskValue, aggregateSecrets, readProviderCache, paramKeyToCategory, buildPluginEvmDiagnosticEntry, EVM_PLUGIN_PACKAGE, applyWhatsAppQrOverride, applySignalQrOverride, signalAuthExists, resolvePluginConfigMutationRejections, requirePluginManager, requireCoreManager, } = ctx;
+    const buildPluginsListSnapshot = async () => {
+        let freshConfig;
+        try {
+            freshConfig = loadElizaConfig();
+        }
+        catch {
+            freshConfig = state.config;
+        }
+        const bundledIds = new Set(state.plugins.map((p) => p.id));
+        const installedEntries = discoverInstalledPlugins(freshConfig, bundledIds);
+        const allPlugins = [...state.plugins, ...installedEntries];
+        let installedMetadataByName = new Map();
+        try {
+            const pluginManager = requirePluginManager(state.runtime);
+            const installed = await pluginManager.listInstalledPlugins();
+            installedMetadataByName = new Map(installed.map((plugin) => [
+                plugin.name,
+                {
+                    version: plugin.version,
+                    releaseStream: plugin.releaseStream,
+                    requestedVersion: plugin.requestedVersion,
+                    latestVersion: plugin.latestVersion,
+                    alphaVersion: plugin.alphaVersion,
+                },
+            ]));
+        }
+        catch {
+            // Keep the plugin list working even when the plugin-manager service is unavailable.
+        }
+        const evmDiagnostic = buildPluginEvmDiagnosticEntry({
+            config: state.config,
+            runtime: state.runtime,
+        });
+        const existingEvmPlugin = allPlugins.find((plugin) => plugin.id === "evm" || plugin.npmName === EVM_PLUGIN_PACKAGE);
+        if (existingEvmPlugin) {
+            existingEvmPlugin.autoEnabled = evmDiagnostic.autoEnabled;
+            existingEvmPlugin.managementMode = "core-optional";
+            existingEvmPlugin.capabilityStatus = evmDiagnostic.capabilityStatus;
+            existingEvmPlugin.capabilityReason = evmDiagnostic.capabilityReason;
+            existingEvmPlugin.prerequisites = evmDiagnostic.prerequisites;
+            existingEvmPlugin.setupGuideUrl =
+                existingEvmPlugin.setupGuideUrl ?? evmDiagnostic.setupGuideUrl;
+            existingEvmPlugin.tags = Array.from(new Set([...(existingEvmPlugin.tags ?? []), ...evmDiagnostic.tags]));
+        }
+        else {
+            allPlugins.push(evmDiagnostic);
+        }
+        const configEntries = freshConfig.plugins?.entries;
+        const loadedNames = state.runtime
+            ? state.runtime.plugins.map((p) => p.name)
+            : [];
+        for (const plugin of allPlugins) {
+            const installedMetadata = (plugin.npmName ? installedMetadataByName.get(plugin.npmName) : null) ??
+                installedMetadataByName.get(plugin.name);
+            if (installedMetadata) {
+                plugin.version = installedMetadata.version ?? plugin.version;
+                plugin.releaseStream =
+                    installedMetadata.releaseStream ?? plugin.releaseStream;
+                plugin.requestedVersion =
+                    installedMetadata.requestedVersion ?? plugin.requestedVersion;
+                plugin.latestVersion =
+                    installedMetadata.latestVersion ?? plugin.latestVersion ?? null;
+                plugin.alphaVersion =
+                    installedMetadata.alphaVersion ?? plugin.alphaVersion ?? null;
+            }
+            const suffix = `plugin-${plugin.id}`;
+            const packageName = `@elizaos/plugin-${plugin.id}`;
+            const npmPkgName = plugin.npmName;
+            const isLoaded = loadedNames.length > 0 &&
+                loadedNames.some((name) => {
+                    return (name === plugin.id ||
+                        name === suffix ||
+                        name === packageName ||
+                        (npmPkgName != null && name === npmPkgName) ||
+                        name.endsWith(`/${suffix}`) ||
+                        name.includes(plugin.id));
+                });
+            plugin.isActive = isLoaded;
+            const configEntry = configEntries?.[plugin.id];
+            if (configEntry && typeof configEntry.enabled === "boolean") {
+                plugin.enabled = configEntry.enabled;
+            }
+            else {
+                plugin.enabled = isLoaded;
+            }
+            plugin.loadError = undefined;
+            if (plugin.enabled && !isLoaded && state.runtime) {
+                const installs = freshConfig.plugins?.installs;
+                const packageName = `@elizaos/plugin-${plugin.id}`;
+                const hasInstallRecord = installs?.[packageName] || installs?.[plugin.id];
+                if (hasInstallRecord) {
+                    plugin.loadError =
+                        "Plugin installed but failed to load — the package may be missing compiled files.";
+                }
+            }
+            if (plugin.id === "evm" || plugin.npmName === EVM_PLUGIN_PACKAGE) {
+                plugin.enabled = evmDiagnostic.enabled;
+                plugin.isActive = evmDiagnostic.isActive;
+                plugin.autoEnabled = evmDiagnostic.autoEnabled;
+                plugin.managementMode = "core-optional";
+                plugin.capabilityStatus = evmDiagnostic.capabilityStatus;
+                plugin.capabilityReason = evmDiagnostic.capabilityReason;
+                plugin.prerequisites = evmDiagnostic.prerequisites;
+            }
+        }
+        for (const plugin of allPlugins) {
+            for (const param of plugin.parameters) {
+                const envValue = process.env[param.key];
+                param.isSet = Boolean(envValue?.trim());
+                param.currentValue = param.isSet
+                    ? param.sensitive
+                        ? maskValue(envValue ?? "")
+                        : (envValue ?? "")
+                    : null;
+            }
+            const paramInfos = plugin.parameters.map((p) => ({
+                key: p.key,
+                required: p.required,
+                sensitive: p.sensitive,
+                type: p.type,
+                description: p.description,
+                default: p.default,
+            }));
+            const validation = validatePluginConfig(plugin.id, plugin.category, plugin.envKey, plugin.configKeys, undefined, paramInfos);
+            plugin.validationErrors = validation.errors;
+            plugin.validationWarnings = validation.warnings;
+        }
+        applyWhatsAppQrOverride(allPlugins, resolveDefaultAgentWorkspaceDir());
+        applySignalQrOverride(allPlugins, resolveDefaultAgentWorkspaceDir(), signalAuthExists);
+        for (const plugin of allPlugins) {
+            const providerModels = readProviderCache(plugin.id)?.models ?? [];
+            for (const param of plugin.parameters) {
+                if (!param.key.toUpperCase().includes("MODEL"))
+                    continue;
+                const expectedCat = paramKeyToCategory(param.key);
+                const filtered = providerModels.filter((m) => m.category === expectedCat);
+                if (!plugin.configUiHints)
+                    plugin.configUiHints = {};
+                plugin.configUiHints[param.key] = {
+                    ...plugin.configUiHints[param.key],
+                    type: "select",
+                    options: filtered.map((m) => ({
+                        value: m.id,
+                        label: m.name !== m.id ? `${m.name} (${m.id})` : m.id,
+                    })),
+                };
+            }
+        }
+        // Attach widget declarations from the static plugin widget map.
+        for (const plugin of allPlugins) {
+            const widgets = getPluginWidgets(plugin.id);
+            if (widgets.length > 0) {
+                plugin.widgets = widgets;
+            }
+        }
+        return allPlugins;
+    };
+    const resolvePluginsSnapshot = async (config) => {
+        const { resolvePlugins } = await import("../runtime/plugin-resolver.js");
+        return await resolvePlugins(config, { quiet: true });
+    };
+    const resolvePluginsSnapshotSafe = async (config, reason) => {
+        try {
+            return await resolvePluginsSnapshot(config);
+        }
+        catch (err) {
+            logger.warn(`[plugin-routes] Failed to resolve plugin snapshot for ${reason}: ${err instanceof Error ? err.message : String(err)}`);
+            return undefined;
+        }
+    };
+    const npmNamePattern = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+    const validateRegistryPluginPackageName = (pluginName) => {
+        const trimmedName = pluginName.trim();
+        if (!trimmedName) {
+            return "Request body must include 'name' (plugin package name)";
+        }
+        if (!npmNamePattern.test(trimmedName)) {
+            return "Invalid plugin name format";
+        }
+        return null;
+    };
+    // ── GET /api/plugins ────────────────────────────────────────────────────
+    if (method === "GET" && pathname === "/api/plugins") {
+        let inFlight = pluginsListInFlight.get(state);
+        if (!inFlight) {
+            inFlight = buildPluginsListSnapshot();
+            pluginsListInFlight.set(state, inFlight);
+        }
+        const allPlugins = await inFlight.finally(() => {
+            pluginsListInFlight.delete(state);
+        });
+        json(res, { plugins: allPlugins });
+        return true;
+    }
+    // ── PUT /api/plugins/:id ────────────────────────────────────────────────
+    if (method === "PUT" && pathname.startsWith("/api/plugins/")) {
+        const pluginId = pathname.slice("/api/plugins/".length);
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        if (isElizaSettingsDebugEnabled()) {
+            logger.debug(`[eliza][settings][api] PUT /api/plugins/${pluginId} body=${JSON.stringify(sanitizeForSettingsDebug({
+                enabled: body.enabled,
+                configKeys: body.config ? Object.keys(body.config).sort() : [],
+                config: body.config ?? {},
+            }))}`);
+        }
+        // Search both bundled plugins AND store-installed plugins
+        let plugin = state.plugins.find((p) => p.id === pluginId);
+        if (!plugin) {
+            // Check store-installed plugins from config
+            let freshCfg;
+            try {
+                freshCfg = loadElizaConfig();
+            }
+            catch {
+                freshCfg = state.config;
+            }
+            const bundledIds = new Set(state.plugins.map((p) => p.id));
+            const installed = discoverInstalledPlugins(freshCfg, bundledIds);
+            const found = installed.find((p) => p.id === pluginId);
+            if (found) {
+                // Temporarily add to state.plugins so toggle logic works the same way
+                state.plugins.push(found);
+                plugin = found;
+            }
+        }
+        if (!plugin) {
+            error(res, `Plugin "${pluginId}" not found`, 404);
+            return true;
+        }
+        const previousConfig = structuredClone(state.config);
+        const previousResolvedPlugins = state.runtime
+            ? await resolvePluginsSnapshotSafe(previousConfig, "plugin update")
+            : undefined;
+        if (body.enabled !== undefined) {
+            plugin.enabled = body.enabled;
+        }
+        if (body.config) {
+            const configRejections = resolvePluginConfigMutationRejections(plugin.parameters, body.config);
+            if (configRejections.length > 0) {
+                json(res, { ok: false, plugin, validationErrors: configRejections }, 422);
+                return true;
+            }
+            // Only validate the fields actually being submitted — not all required
+            // fields. Users may save partial config (e.g. just the API key) from
+            // the Settings page; blocking the save because OTHER required fields
+            // aren't set yet is counterproductive.
+            const configObj = body.config;
+            const submittedParamInfos = plugin.parameters
+                .filter((p) => p.key in configObj)
+                .map((p) => ({
+                key: p.key,
+                required: p.required,
+                sensitive: p.sensitive,
+                type: p.type,
+                description: p.description,
+                default: p.default,
+            }));
+            const configValidation = validatePluginConfig(pluginId, plugin.category, plugin.envKey, plugin.configKeys, body.config, submittedParamInfos);
+            if (!configValidation.valid) {
+                json(res, { ok: false, plugin, validationErrors: configValidation.errors }, 422);
+                return true;
+            }
+            const allowedParamKeys = new Set(plugin.parameters.map((p) => p.key));
+            // Persist config values to state.config.env so they survive restarts
+            if (!state.config.env) {
+                state.config.env = {};
+            }
+            for (const [key, value] of Object.entries(body.config)) {
+                if (allowedParamKeys.has(key) &&
+                    !BLOCKED_ENV_KEYS.has(key.toUpperCase()) &&
+                    typeof value === "string" &&
+                    value.trim()) {
+                    process.env[key] = value;
+                    state.config.env[key] = value;
+                }
+            }
+            plugin.configured = true;
+            // Save config even when only config values changed (no enable toggle)
+            if (body.enabled === undefined) {
+                try {
+                    saveElizaConfig(state.config);
+                }
+                catch (err) {
+                    logger.warn(`[eliza-api] Failed to save config: ${err instanceof Error ? err.message : err}`);
+                }
+            }
+        }
+        // Refresh validation
+        const refreshParamInfos = plugin.parameters.map((p) => ({
+            key: p.key,
+            required: p.required,
+            sensitive: p.sensitive,
+            type: p.type,
+            description: p.description,
+            default: p.default,
+        }));
+        const updated = validatePluginConfig(pluginId, plugin.category, plugin.envKey, plugin.configKeys, undefined, refreshParamInfos);
+        plugin.validationErrors = updated.errors;
+        plugin.validationWarnings = updated.warnings;
+        // Update config.plugins.entries so the runtime loads/skips this plugin
+        if (body.enabled !== undefined) {
+            const packageName = `@elizaos/plugin-${pluginId}`;
+            if (!state.config.plugins) {
+                state.config.plugins = {};
+            }
+            if (!state.config.plugins.entries) {
+                state.config.plugins.entries = {};
+            }
+            const entries = state.config.plugins
+                .entries;
+            entries[pluginId] = { enabled: body.enabled };
+            logger.info(`[eliza-api] ${body.enabled ? "Enabled" : "Disabled"} plugin: ${packageName}`);
+            // Persist capability toggle state in config.features so the runtime
+            // can gate related behaviour (e.g. disabling image description when
+            // vision is toggled off).
+            const CAPABILITY_FEATURE_IDS = new Set([
+                "vision",
+                "browser",
+                "computeruse",
+                "coding-agent",
+            ]);
+            if (CAPABILITY_FEATURE_IDS.has(pluginId)) {
+                if (!state.config.features) {
+                    state.config.features = {};
+                }
+                state.config.features[pluginId] = body.enabled;
+            }
+            // Save updated config
+            try {
+                saveElizaConfig(state.config);
+            }
+            catch (err) {
+                logger.warn(`[eliza-api] Failed to save config: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        const runtimeApply = await applyPluginRuntimeMutation({
+            runtime: state.runtime,
+            previousConfig,
+            nextConfig: state.config,
+            previousResolvedPlugins,
+            changedPluginId: pluginId,
+            changedPluginPackage: plugin.npmName,
+            config: body.config,
+            expectRuntimeGraphChange: body.enabled !== undefined,
+            reason: body.enabled !== undefined
+                ? `Plugin toggle: ${pluginId}`
+                : `Plugin config updated: ${pluginId}`,
+            restartRuntime,
+        });
+        if (runtimeApply.requiresRestart) {
+            scheduleRuntimeRestart(runtimeApply.reason);
+        }
+        if (isElizaSettingsDebugEnabled()) {
+            const cloud = state.config.cloud;
+            logger.debug(`[eliza][settings][api] PUT /api/plugins/${pluginId} → done configured=${plugin.configured} enabled=${plugin.enabled} cloud=${JSON.stringify(settingsDebugCloudSummary(cloud))}`);
+        }
+        json(res, {
+            ok: true,
+            plugin,
+            applied: runtimeApply.mode,
+            requiresRestart: runtimeApply.requiresRestart,
+            restartedRuntime: runtimeApply.restartedRuntime,
+            loadedPackages: runtimeApply.loadedPackages,
+            unloadedPackages: runtimeApply.unloadedPackages,
+            reloadedPackages: runtimeApply.reloadedPackages,
+        });
+        return true;
+    }
+    // ── GET /api/secrets ─────────────────────────────────────────────────
+    if (method === "GET" && pathname === "/api/secrets") {
+        // Merge bundled + installed plugins for full parameter coverage
+        const bundledIds = new Set(state.plugins.map((p) => p.id));
+        const installedEntries = discoverInstalledPlugins(state.config, bundledIds);
+        const allPlugins = [...state.plugins, ...installedEntries];
+        // Sync enabled status from runtime (same logic as GET /api/plugins)
+        if (state.runtime) {
+            const loadedNames = state.runtime.plugins.map((p) => p.name);
+            for (const plugin of allPlugins) {
+                const suffix = `plugin-${plugin.id}`;
+                const packageName = `@elizaos/plugin-${plugin.id}`;
+                plugin.enabled = loadedNames.some((name) => name === plugin.id ||
+                    name === suffix ||
+                    name === packageName ||
+                    name.endsWith(`/${suffix}`) ||
+                    name.includes(plugin.id));
+            }
+        }
+        const secrets = aggregateSecrets(allPlugins);
+        json(res, { secrets });
+        return true;
+    }
+    // ── PUT /api/secrets ─────────────────────────────────────────────────
+    if (method === "PUT" && pathname === "/api/secrets") {
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        if (!body.secrets || typeof body.secrets !== "object") {
+            error(res, "Missing or invalid 'secrets' object", 400);
+            return true;
+        }
+        // Build allowlist from all plugin-declared sensitive params
+        const bundledIds = new Set(state.plugins.map((p) => p.id));
+        const installedEntries = discoverInstalledPlugins(state.config, bundledIds);
+        const allPlugins = [...state.plugins, ...installedEntries];
+        const allowedKeys = new Set();
+        for (const plugin of allPlugins) {
+            for (const param of plugin.parameters) {
+                if (param.sensitive)
+                    allowedKeys.add(param.key);
+            }
+        }
+        const updatedKeys = [];
+        for (const [key, value] of Object.entries(body.secrets)) {
+            if (typeof value !== "string" || !value.trim())
+                continue;
+            if (!allowedKeys.has(key))
+                continue;
+            if (BLOCKED_ENV_KEYS.has(key.toUpperCase()))
+                continue;
+            process.env[key] = value;
+            updatedKeys.push(key);
+        }
+        // Mark affected plugins as configured
+        for (const plugin of allPlugins) {
+            const pluginKeys = new Set(plugin.parameters.map((p) => p.key));
+            if (updatedKeys.some((k) => pluginKeys.has(k))) {
+                plugin.configured = true;
+            }
+        }
+        json(res, { ok: true, updated: updatedKeys });
+        return true;
+    }
+    // ── POST /api/plugins/:id/test ────────────────────────────────────────
+    // Test a plugin's connection / configuration validity.
+    const pluginTestMatch = method === "POST" && pathname.match(/^\/api\/plugins\/([^/]+)\/test$/);
+    if (pluginTestMatch) {
+        const pluginId = decodeURIComponent(pluginTestMatch[1]);
+        const startMs = Date.now();
+        try {
+            // Find the plugin in the runtime
+            const allPlugins = state.runtime?.plugins ?? [];
+            const normalizePluginId = (value) => value.replace(/^@[^/]+\//, "").replace(/^plugin-/, "");
+            const normalizedPluginId = normalizePluginId(pluginId);
+            const plugin = allPlugins.find((p) => {
+                const runtimeName = p.name ?? "";
+                const runtimeId = normalizePluginId(runtimeName);
+                return (p.id === pluginId ||
+                    p.name === pluginId ||
+                    runtimeId === pluginId ||
+                    runtimeId === normalizedPluginId);
+            });
+            if (!plugin) {
+                json(res, {
+                    success: false,
+                    pluginId,
+                    error: "Plugin not found or not loaded",
+                    durationMs: Date.now() - startMs,
+                }, 404);
+                return true;
+            }
+            // Check if plugin exposes a test/health method
+            const testFn = plugin.testConnection ??
+                plugin.healthCheck;
+            if (typeof testFn === "function") {
+                const result = await testFn();
+                json(res, {
+                    success: result.ok !== false,
+                    pluginId,
+                    message: result.message ??
+                        (result.ok !== false
+                            ? "Connection successful"
+                            : "Connection failed"),
+                    durationMs: Date.now() - startMs,
+                });
+                return true;
+            }
+            // No test function — return a basic "plugin is loaded" status
+            json(res, {
+                success: true,
+                pluginId,
+                message: "Plugin is loaded and active (no custom test available)",
+                durationMs: Date.now() - startMs,
+            });
+        }
+        catch (err) {
+            json(res, {
+                success: false,
+                pluginId,
+                error: err instanceof Error ? err.message : String(err),
+                durationMs: Date.now() - startMs,
+            }, 500);
+        }
+        return true;
+    }
+    // ── POST /api/plugins/install ───────────────────────────────────────────
+    // Install a plugin from the registry and restart the agent.
+    if (method === "POST" && pathname === "/api/plugins/install") {
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        const pluginName = body.name?.trim();
+        if (!pluginName) {
+            error(res, "Request body must include 'name' (plugin package name)", 400);
+            return true;
+        }
+        const installValidationError = validateRegistryPluginPackageName(pluginName);
+        if (installValidationError) {
+            error(res, installValidationError, 400);
+            return true;
+        }
+        try {
+            const previousConfig = structuredClone(state.config);
+            const previousResolvedPlugins = state.runtime
+                ? await resolvePluginsSnapshotSafe(previousConfig, "plugin install")
+                : undefined;
+            const pluginManager = requirePluginManager(state.runtime);
+            const result = await pluginManager.installPlugin(pluginName, (progress) => {
+                logger.info(`[install] ${progress.phase}: ${progress.message}`);
+                state.broadcastWs?.({
+                    type: "install-progress",
+                    pluginName: progress.pluginName,
+                    phase: progress.phase,
+                    message: progress.message,
+                });
+            }, {
+                releaseStream: body.stream,
+                version: body.version,
+            });
+            if (!result.success) {
+                json(res, { ok: false, error: result.error }, 422);
+                return true;
+            }
+            // Auto-enable the newly installed plugin so the runtime loads it after restart.
+            const installedId = (result.pluginName ?? pluginName)
+                .replace(/^@[^/]+\/plugin-/, "")
+                .replace(/^@[^/]+\//, "")
+                .replace(/^plugin-/, "");
+            if (!state.config.plugins) {
+                state.config.plugins = {};
+            }
+            if (!state.config.plugins.entries) {
+                state.config.plugins.entries = {};
+            }
+            const pluginEntries = state.config.plugins
+                .entries;
+            pluginEntries[installedId] = { enabled: true };
+            // Record the install path so plugin-resolver can find the package.
+            // Without this, the downloaded package in ~/.eliza/plugins/installed/
+            // is invisible to the runtime loader.
+            if (result.installPath) {
+                if (!state.config.plugins.installs ||
+                    typeof state.config.plugins.installs !==
+                        "object") {
+                    state.config.plugins.installs = {};
+                }
+                const installs = state.config.plugins
+                    .installs;
+                installs[result.pluginName ?? pluginName] = {
+                    source: "npm",
+                    requestedVersion: result.requestedVersion,
+                    releaseStream: result.releaseStream,
+                    installPath: result.installPath,
+                    version: result.version ?? "unknown",
+                    installedAt: new Date().toISOString(),
+                };
+            }
+            try {
+                saveElizaConfig(state.config);
+            }
+            catch (err) {
+                logger.warn(`[eliza-api] Failed to save config after install: ${err instanceof Error ? err.message : err}`);
+            }
+            const runtimeApply = await applyPluginRuntimeMutation({
+                runtime: state.runtime,
+                previousConfig,
+                nextConfig: state.config,
+                previousResolvedPlugins,
+                changedPluginId: installedId,
+                changedPluginPackage: result.pluginName,
+                expectRuntimeGraphChange: true,
+                reason: `Plugin ${result.pluginName} installed`,
+                restartRuntime,
+            });
+            if (runtimeApply.requiresRestart && body.autoRestart !== false) {
+                scheduleRuntimeRestart(runtimeApply.reason);
+            }
+            json(res, {
+                ok: true,
+                pluginName: result.pluginName,
+                plugin: {
+                    name: result.pluginName,
+                    version: result.version,
+                    installPath: result.installPath,
+                },
+                applied: runtimeApply.mode,
+                requiresRestart: runtimeApply.requiresRestart,
+                restartedRuntime: runtimeApply.restartedRuntime,
+                loadedPackages: runtimeApply.loadedPackages,
+                unloadedPackages: runtimeApply.unloadedPackages,
+                reloadedPackages: runtimeApply.reloadedPackages,
+                releaseStream: result.releaseStream,
+                requestedVersion: result.requestedVersion,
+                latestVersion: result.latestVersion,
+                alphaVersion: result.alphaVersion,
+                message: runtimeApply.requiresRestart
+                    ? `${result.pluginName} installed. Restart required to activate.`
+                    : `${result.pluginName} installed.`,
+            });
+        }
+        catch (err) {
+            error(res, `Install failed: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+        return true;
+    }
+    // ── POST /api/plugins/update ────────────────────────────────────────────
+    if (method === "POST" && pathname === "/api/plugins/update") {
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        const pluginName = body.name?.trim();
+        const updateValidationError = validateRegistryPluginPackageName(pluginName ?? "");
+        if (updateValidationError) {
+            error(res, updateValidationError, 400);
+            return true;
+        }
+        try {
+            const previousConfig = structuredClone(state.config);
+            const previousResolvedPlugins = state.runtime
+                ? await resolvePluginsSnapshotSafe(previousConfig, "plugin update")
+                : undefined;
+            const pluginManager = requirePluginManager(state.runtime);
+            const updatePlugin = typeof pluginManager.updatePlugin === "function"
+                ? pluginManager.updatePlugin.bind(pluginManager)
+                : pluginManager.installPlugin.bind(pluginManager);
+            const result = await updatePlugin(pluginName, (progress) => {
+                logger.info(`[update] ${progress.phase}: ${progress.message}`);
+                state.broadcastWs?.({
+                    type: "install-progress",
+                    pluginName: progress.pluginName,
+                    phase: progress.phase,
+                    message: progress.message,
+                });
+            }, {
+                releaseStream: body.stream,
+                version: body.version,
+            });
+            if (!result.success) {
+                json(res, { ok: false, error: result.error }, 422);
+                return true;
+            }
+            if (!state.config.plugins) {
+                state.config.plugins = {};
+            }
+            if (!state.config.plugins.entries) {
+                state.config.plugins.entries = {};
+            }
+            const updatedId = (result.pluginName ?? pluginName)
+                .replace(/^@[^/]+\/plugin-/, "")
+                .replace(/^@[^/]+\//, "")
+                .replace(/^plugin-/, "");
+            state.config.plugins.entries[updatedId] = { enabled: true };
+            state.config.plugins.installs = state.config.plugins.installs ?? {};
+            state.config.plugins.installs[result.pluginName ?? pluginName] = {
+                source: "npm",
+                requestedVersion: result.requestedVersion,
+                releaseStream: result.releaseStream,
+                installPath: result.installPath,
+                version: result.version ?? "unknown",
+                installedAt: new Date().toISOString(),
+            };
+            try {
+                saveElizaConfig(state.config);
+            }
+            catch (err) {
+                logger.warn(`[eliza-api] Failed to save config after update: ${err instanceof Error ? err.message : err}`);
+            }
+            const runtimeApply = await applyPluginRuntimeMutation({
+                runtime: state.runtime,
+                previousConfig,
+                nextConfig: state.config,
+                previousResolvedPlugins,
+                changedPluginId: updatedId,
+                changedPluginPackage: result.pluginName,
+                forceReloadPackages: [result.pluginName],
+                expectRuntimeGraphChange: true,
+                reason: `Plugin ${result.pluginName} updated`,
+                restartRuntime,
+            });
+            if (runtimeApply.requiresRestart && body.autoRestart !== false) {
+                scheduleRuntimeRestart(runtimeApply.reason);
+            }
+            json(res, {
+                ok: true,
+                pluginName: result.pluginName,
+                plugin: {
+                    name: result.pluginName,
+                    version: result.version,
+                    installPath: result.installPath,
+                },
+                applied: runtimeApply.mode,
+                requiresRestart: runtimeApply.requiresRestart,
+                restartedRuntime: runtimeApply.restartedRuntime,
+                loadedPackages: runtimeApply.loadedPackages,
+                unloadedPackages: runtimeApply.unloadedPackages,
+                reloadedPackages: runtimeApply.reloadedPackages,
+                releaseStream: result.releaseStream,
+                requestedVersion: result.requestedVersion,
+                latestVersion: result.latestVersion,
+                alphaVersion: result.alphaVersion,
+                message: runtimeApply.requiresRestart
+                    ? `${result.pluginName} updated. Restart required to activate.`
+                    : `${result.pluginName} updated.`,
+            });
+        }
+        catch (err) {
+            error(res, `Update failed: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+        return true;
+    }
+    // ── POST /api/plugins/uninstall ─────────────────────────────────────────
+    if (method === "POST" && pathname === "/api/plugins/uninstall") {
+        const body = await readJsonBody(req, res);
+        if (!body)
+            return true;
+        const pluginName = body.name?.trim();
+        const uninstallValidationError = validateRegistryPluginPackageName(pluginName ?? "");
+        if (uninstallValidationError) {
+            error(res, uninstallValidationError, 400);
+            return true;
+        }
+        try {
+            const previousConfig = structuredClone(state.config);
+            const previousResolvedPlugins = state.runtime
+                ? await resolvePluginsSnapshotSafe(previousConfig, "plugin uninstall")
+                : undefined;
+            const pluginManager = requirePluginManager(state.runtime);
+            const result = await pluginManager.uninstallPlugin(pluginName);
+            if (!result.success) {
+                json(res, { ok: false, error: result.error }, 422);
+                return true;
+            }
+            const removedId = (result.pluginName ?? pluginName)
+                .replace(/^@[^/]+\/plugin-/, "")
+                .replace(/^@[^/]+\//, "")
+                .replace(/^plugin-/, "");
+            const installs = state.config.plugins?.installs;
+            if (installs && typeof installs === "object") {
+                delete installs[result.pluginName ?? pluginName];
+            }
+            const entries = state.config.plugins?.entries;
+            if (entries && typeof entries === "object") {
+                delete entries[removedId];
+            }
+            try {
+                saveElizaConfig(state.config);
+            }
+            catch (err) {
+                logger.warn(`[eliza-api] Failed to save config after uninstall: ${err instanceof Error ? err.message : err}`);
+            }
+            const runtimeApply = await applyPluginRuntimeMutation({
+                runtime: state.runtime,
+                previousConfig,
+                nextConfig: state.config,
+                previousResolvedPlugins,
+                changedPluginId: removedId,
+                changedPluginPackage: result.pluginName,
+                expectRuntimeGraphChange: true,
+                reason: `Plugin ${pluginName} uninstalled`,
+                restartRuntime,
+            });
+            if (runtimeApply.requiresRestart && body.autoRestart !== false) {
+                scheduleRuntimeRestart(runtimeApply.reason);
+            }
+            json(res, {
+                ok: true,
+                pluginName: result.pluginName,
+                applied: runtimeApply.mode,
+                requiresRestart: runtimeApply.requiresRestart,
+                restartedRuntime: runtimeApply.restartedRuntime,
+                loadedPackages: runtimeApply.loadedPackages,
+                unloadedPackages: runtimeApply.unloadedPackages,
+                reloadedPackages: runtimeApply.reloadedPackages,
+                message: runtimeApply.requiresRestart
+                    ? `${pluginName} uninstalled. Restart required.`
+                    : `${pluginName} uninstalled.`,
+            });
+        }
+        catch (err) {
+            error(res, `Uninstall failed: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+        return true;
+    }
+    // ── POST /api/plugins/:id/eject ─────────────────────────────────────────
+    if (method === "POST" && pathname.match(/^\/api\/plugins\/[^/]+\/eject$/)) {
+        const pluginName = decodeURIComponent(pathname.slice("/api/plugins/".length, pathname.length - "/eject".length));
+        try {
+            const previousConfig = structuredClone(state.config);
+            const previousResolvedPlugins = state.runtime
+                ? await resolvePluginsSnapshotSafe(previousConfig, "plugin eject")
+                : undefined;
+            const pluginManager = requirePluginManager(state.runtime);
+            // Ensure the method exists on the service (it should)
+            if (typeof pluginManager.ejectPlugin !== "function") {
+                throw new Error("Plugin manager does not support ejecting plugins");
+            }
+            const result = await pluginManager.ejectPlugin(pluginName);
+            if (!result.success) {
+                json(res, { ok: false, error: result.error }, 422);
+                return true;
+            }
+            const runtimeApply = await applyPluginRuntimeMutation({
+                runtime: state.runtime,
+                previousConfig,
+                nextConfig: state.config,
+                previousResolvedPlugins,
+                changedPluginId: pluginName,
+                changedPluginPackage: result.pluginName,
+                forceReloadPackages: [result.pluginName],
+                expectRuntimeGraphChange: true,
+                reason: `Plugin ${pluginName} ejected`,
+                restartRuntime,
+            });
+            if (runtimeApply.requiresRestart) {
+                scheduleRuntimeRestart(runtimeApply.reason);
+            }
+            json(res, {
+                ok: true,
+                pluginName: result.pluginName,
+                applied: runtimeApply.mode,
+                requiresRestart: runtimeApply.requiresRestart,
+                restartedRuntime: runtimeApply.restartedRuntime,
+                loadedPackages: runtimeApply.loadedPackages,
+                unloadedPackages: runtimeApply.unloadedPackages,
+                reloadedPackages: runtimeApply.reloadedPackages,
+                message: `${pluginName} ejected to local source.`,
+            });
+        }
+        catch (err) {
+            error(res, `Eject failed: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+        return true;
+    }
+    // ── POST /api/plugins/:id/sync ──────────────────────────────────────────
+    if (method === "POST" && pathname.match(/^\/api\/plugins\/[^/]+\/sync$/)) {
+        const pluginName = decodeURIComponent(pathname.slice("/api/plugins/".length, pathname.length - "/sync".length));
+        try {
+            const previousConfig = structuredClone(state.config);
+            const previousResolvedPlugins = state.runtime
+                ? await resolvePluginsSnapshotSafe(previousConfig, "plugin sync")
+                : undefined;
+            const pluginManager = requirePluginManager(state.runtime);
+            if (typeof pluginManager.syncPlugin !== "function") {
+                throw new Error("Plugin manager does not support syncing plugins");
+            }
+            const result = await pluginManager.syncPlugin(pluginName);
+            if (!result.success) {
+                json(res, { ok: false, error: result.error }, 422);
+                return true;
+            }
+            const runtimeApply = await applyPluginRuntimeMutation({
+                runtime: state.runtime,
+                previousConfig,
+                nextConfig: state.config,
+                previousResolvedPlugins,
+                changedPluginId: pluginName,
+                changedPluginPackage: result.pluginName,
+                forceReloadPackages: result.requiresRestart ? [result.pluginName] : [],
+                expectRuntimeGraphChange: true,
+                reason: `Plugin ${pluginName} synced`,
+                restartRuntime,
+            });
+            if (runtimeApply.requiresRestart) {
+                scheduleRuntimeRestart(runtimeApply.reason);
+            }
+            json(res, {
+                ok: true,
+                pluginName: result.pluginName,
+                applied: runtimeApply.mode,
+                requiresRestart: runtimeApply.requiresRestart,
+                restartedRuntime: runtimeApply.restartedRuntime,
+                loadedPackages: runtimeApply.loadedPackages,
+                unloadedPackages: runtimeApply.unloadedPackages,
+                reloadedPackages: runtimeApply.reloadedPackages,
+                message: `${pluginName} synced with upstream.`,
+            });
+        }
+        catch (err) {
+            error(res, `Sync failed: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+        return true;
+    }
+    // ── POST /api/plugins/:id/reinject ──────────────────────────────────────
+    if (method === "POST" &&
+        pathname.match(/^\/api\/plugins\/[^/]+\/reinject$/)) {
+        const pluginName = decodeURIComponent(pathname.slice("/api/plugins/".length, pathname.length - "/reinject".length));
+        try {
+            const previousConfig = structuredClone(state.config);
+            const previousResolvedPlugins = state.runtime
+                ? await resolvePluginsSnapshotSafe(previousConfig, "plugin reinject")
+                : undefined;
+            const pluginManager = requirePluginManager(state.runtime);
+            if (typeof pluginManager.reinjectPlugin !== "function") {
+                throw new Error("Plugin manager does not support reinjecting plugins");
+            }
+            const result = await pluginManager.reinjectPlugin(pluginName);
+            if (!result.success) {
+                json(res, { ok: false, error: result.error }, 422);
+                return true;
+            }
+            const runtimeApply = await applyPluginRuntimeMutation({
+                runtime: state.runtime,
+                previousConfig,
+                nextConfig: state.config,
+                previousResolvedPlugins,
+                changedPluginId: pluginName,
+                changedPluginPackage: result.pluginName,
+                forceReloadPackages: [result.pluginName],
+                expectRuntimeGraphChange: true,
+                reason: `Plugin ${pluginName} reinjected`,
+                restartRuntime,
+            });
+            if (runtimeApply.requiresRestart) {
+                scheduleRuntimeRestart(runtimeApply.reason);
+            }
+            json(res, {
+                ok: true,
+                pluginName: result.pluginName,
+                applied: runtimeApply.mode,
+                requiresRestart: runtimeApply.requiresRestart,
+                restartedRuntime: runtimeApply.restartedRuntime,
+                loadedPackages: runtimeApply.loadedPackages,
+                unloadedPackages: runtimeApply.unloadedPackages,
+                reloadedPackages: runtimeApply.reloadedPackages,
+                message: `${pluginName} restored to registry version.`,
+            });
+        }
+        catch (err) {
+            error(res, `Reinject failed: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+        return true;
+    }
+    // ── GET /api/plugins/installed ──────────────────────────────────────────
+    // List plugins that were installed from the registry at runtime.
+    if (method === "GET" && pathname === "/api/plugins/installed") {
+        try {
+            const pluginManager = requirePluginManager(state.runtime);
+            const installed = await pluginManager.listInstalledPlugins();
+            json(res, { count: installed.length, plugins: installed });
+        }
+        catch (err) {
+            error(res, `Failed to list installed plugins: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+        return true;
+    }
+    // ── GET /api/plugins/ejected ────────────────────────────────────────────
+    // List plugins ejected to local source checkouts with upstream metadata.
+    if (method === "GET" && pathname === "/api/plugins/ejected") {
+        try {
+            const pluginManager = requirePluginManager(state.runtime);
+            if (typeof pluginManager.listEjectedPlugins !== "function") {
+                throw new Error("Plugin manager does not support listing ejected plugins");
+            }
+            const plugins = await pluginManager.listEjectedPlugins();
+            json(res, { count: plugins.length, plugins });
+        }
+        catch (err) {
+            error(res, `Failed to list ejected plugins: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+        return true;
+    }
+    // ── GET /api/core/status ────────────────────────────────────────────────
+    // Returns whether @elizaos/core is ejected or resolved from npm.
+    if (method === "GET" && pathname === "/api/core/status") {
+        try {
+            const coreManager = requireCoreManager(state.runtime);
+            const coreStatus = await coreManager.getCoreStatus();
+            json(res, coreStatus);
+        }
+        catch (err) {
+            error(res, `Failed to get core status: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+        return true;
+    }
+    // ── GET /api/plugins/core ────────────────────────────────────────────
+    // Returns all core and optional core plugins with their loaded/running status.
+    if (method === "GET" && pathname === "/api/plugins/core") {
+        // Build a set of loaded plugin names for robust matching.
+        // Plugin internal names vary wildly (e.g. "local-ai" for plugin-local-embedding,
+        // "eliza-coder" for plugin-code), so we check loaded names against multiple
+        // derived forms of the npm package name.
+        const loadedNames = state.runtime
+            ? new Set(state.runtime.plugins.map((p) => p.name))
+            : new Set();
+        const isLoaded = (npmName) => {
+            if (loadedNames.has(npmName))
+                return true;
+            // @elizaos/plugin-foo -> plugin-foo
+            const withoutScope = npmName.replace("@elizaos/", "");
+            if (loadedNames.has(withoutScope))
+                return true;
+            // plugin-foo -> foo
+            const shortId = withoutScope.replace("plugin-", "");
+            if (loadedNames.has(shortId))
+                return true;
+            // Check if ANY loaded name contains the short id or vice versa
+            for (const n of loadedNames) {
+                if (n.includes(shortId) || shortId.includes(n))
+                    return true;
+            }
+            return false;
+        };
+        // Check which optional plugins are currently in the allow list
+        const allowList = new Set(state.config.plugins?.allow ?? []);
+        const makeEntry = (npm, isCore) => {
+            const id = optionalPluginListId(npm);
+            return {
+                npmName: npm,
+                id,
+                name: id
+                    .split("-")
+                    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+                    .join(" "),
+                isCore,
+                loaded: isLoaded(npm),
+                enabled: isCore || allowList.has(npm) || allowList.has(id),
+            };
+        };
+        const coreList = CORE_PLUGINS.map((npm) => makeEntry(npm, true));
+        const optionalList = OPTIONAL_CORE_PLUGINS.map((npm) => makeEntry(npm, false));
+        json(res, { core: coreList, optional: optionalList });
+        return true;
+    }
+    // ── POST /api/plugins/core/toggle ─────────────────────────────────────
+    // Enable or disable an optional core plugin by updating the allow list.
+    if (method === "POST" && pathname === "/api/plugins/core/toggle") {
+        const body = await readJsonBody(req, res);
+        if (!body?.npmName)
+            return true;
+        // Only allow toggling optional plugins, not core
+        const isCorePlugin = CORE_PLUGINS.includes(body.npmName);
+        if (isCorePlugin) {
+            error(res, "Core plugins cannot be disabled");
+            return true;
+        }
+        const isOptional = OPTIONAL_CORE_PLUGINS.includes(body.npmName);
+        if (!isOptional) {
+            error(res, "Unknown optional plugin");
+            return true;
+        }
+        const previousConfig = structuredClone(state.config);
+        const previousResolvedPlugins = state.runtime
+            ? await resolvePluginsSnapshotSafe(previousConfig, "core plugin toggle")
+            : undefined;
+        // Update the allow list in config
+        state.config.plugins = state.config.plugins ?? {};
+        state.config.plugins.allow = state.config.plugins.allow ?? [];
+        const allow = state.config.plugins.allow;
+        const shortId = optionalPluginListId(body.npmName);
+        if (body.enabled) {
+            if (!allow.includes(body.npmName) && !allow.includes(shortId)) {
+                allow.push(body.npmName);
+            }
+        }
+        else {
+            state.config.plugins.allow = allow.filter((p) => p !== body.npmName && p !== shortId);
+        }
+        // Keep plugins.entries.enabled aligned with the toggle so optional baked-in
+        // plugins that use strict `enabled === true` entry rules stay consistent.
+        const pluginsRoot = state.config.plugins;
+        const prevEntries = pluginsRoot.entries ?? {};
+        pluginsRoot.entries = {
+            ...prevEntries,
+            [shortId]: {
+                ...prevEntries[shortId],
+                enabled: body.enabled,
+            },
+        };
+        try {
+            saveElizaConfig(state.config);
+        }
+        catch (err) {
+            logger.warn(`[api] Config save failed: ${err instanceof Error ? err.message : err}`);
+        }
+        const runtimeApply = await applyPluginRuntimeMutation({
+            runtime: state.runtime,
+            previousConfig,
+            nextConfig: state.config,
+            previousResolvedPlugins,
+            changedPluginId: shortId,
+            changedPluginPackage: body.npmName,
+            expectRuntimeGraphChange: true,
+            reason: `Plugin ${shortId} ${body.enabled ? "enabled" : "disabled"}`,
+            restartRuntime,
+        });
+        if (runtimeApply.requiresRestart) {
+            scheduleRuntimeRestart(runtimeApply.reason);
+        }
+        json(res, {
+            ok: true,
+            applied: runtimeApply.mode,
+            requiresRestart: runtimeApply.requiresRestart,
+            restartedRuntime: runtimeApply.restartedRuntime,
+            loadedPackages: runtimeApply.loadedPackages,
+            unloadedPackages: runtimeApply.unloadedPackages,
+            reloadedPackages: runtimeApply.reloadedPackages,
+            message: runtimeApply.requiresRestart
+                ? `${shortId} ${body.enabled ? "enabled" : "disabled"}. Restart required.`
+                : `${shortId} ${body.enabled ? "enabled" : "disabled"}.`,
+        });
+        return true;
+    }
+    return false;
+}