@elizaos/app-core 2.0.0-alpha.85 → 2.0.0-beta.2

package/api/plugins-compat-routes.js

@@ -0,0 +1,1181 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { applyPluginRuntimeMutation, CONNECTOR_ENV_MAP, discoverPluginsFromManifest, findPrimaryEnvKey, isAdvancedCapabilityPluginId, isVaultRef, loadElizaConfig, parseVaultRef, readBundledPluginPackageMetadata, resolveAdvancedCapabilitiesEnabled, saveElizaConfig, } from "@elizaos/agent";
+import { logger } from "@elizaos/core";
+import { asRecord, CONNECTOR_PLUGINS, STREAMING_PLUGINS, } from "@elizaos/shared";
+import { VaultMissError } from "@elizaos/vault";
+import { loadRegistry } from "../registry";
+import { _resetSharedVaultForTesting, mirrorPluginSensitiveToVault, sharedVault, } from "../services/vault-mirror";
+import { ensureCompatSensitiveRouteAuthorized, ensureRouteAuthorized, } from "./auth.js";
+import { readCompatJsonBody, scheduleCompatRuntimeRestart, } from "./compat-route-shared";
+import { sendJsonError as sendJsonErrorResponse, sendJson as sendJsonResponse, } from "./response";
+const require = createRequire(import.meta.url);
+const FIELD_TYPE_TO_LEGACY = {
+    string: "string",
+    secret: "string",
+    url: "string",
+    "file-path": "string",
+    textarea: "string",
+    json: "string",
+    select: "string",
+    multiselect: "string",
+    boolean: "boolean",
+    number: "number",
+};
+function pluginSubtypeToCategory(entry) {
+    if (entry.kind !== "plugin")
+        return entry.kind;
+    if (entry.subtype === "ai-provider")
+        return "ai-provider";
+    if (entry.subtype === "database")
+        return "database";
+    return "feature";
+}
+function connectorSubtypeToCategory(entry) {
+    if (entry.kind !== "connector")
+        return "connector";
+    if (entry.subtype === "streaming")
+        return "streaming";
+    return "connector";
+}
+function categoryForRegistryEntry(entry) {
+    if (entry.kind === "plugin")
+        return pluginSubtypeToCategory(entry);
+    if (entry.kind === "connector")
+        return connectorSubtypeToCategory(entry);
+    return entry.kind;
+}
+function envKeyForRegistryEntry(entry) {
+    if (entry.kind === "connector" && entry.auth) {
+        const [first] = entry.auth.credentialKeys;
+        if (first)
+            return first;
+    }
+    for (const [key, field] of Object.entries(entry.config)) {
+        if (field.required && (field.type === "secret" || field.sensitive)) {
+            return key;
+        }
+    }
+    return undefined;
+}
+function fieldToManifestParameter(field) {
+    const param = {
+        type: FIELD_TYPE_TO_LEGACY[field.type],
+        description: field.help ?? field.label ?? "",
+        required: field.required,
+        sensitive: field.sensitive ?? field.type === "secret",
+    };
+    if (field.default !== undefined && field.default !== null) {
+        param.default = String(field.default);
+    }
+    if (field.options) {
+        param.options = field.options.map((option) => option.value);
+    }
+    return param;
+}
+function registryEntryToManifest(entry) {
+    const pluginParameters = {};
+    for (const [key, field] of Object.entries(entry.config)) {
+        pluginParameters[key] = fieldToManifestParameter(field);
+    }
+    return {
+        id: entry.id,
+        dirName: entry.npmName?.replace(/^@[^/]+\//, ""),
+        name: entry.name,
+        npmName: entry.npmName,
+        description: entry.description,
+        tags: entry.tags,
+        category: categoryForRegistryEntry(entry),
+        envKey: envKeyForRegistryEntry(entry),
+        configKeys: Object.keys(entry.config),
+        version: entry.version,
+        pluginParameters,
+        icon: entry.render.icon ?? null,
+        homepage: entry.resources.homepage,
+        repository: entry.resources.repository,
+        setupGuideUrl: entry.resources.setupGuideUrl,
+    };
+}
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const CAPABILITY_FEATURE_IDS = new Set([
+    "vision",
+    "browser",
+    "computeruse",
+    "coding-agent",
+]);
+const ADVANCED_CAPABILITY_SERVICE_BY_PLUGIN_ID = {
+    experience: "EXPERIENCE",
+    personality: "CHARACTER_MANAGEMENT",
+};
+// Key prefixes that contain wallet private keys or other high-value secrets
+// require the hardened sensitive-route auth (loopback + elevated checks).
+const SENSITIVE_KEY_PREFIXES = ["SOLANA_", "ETHEREUM_", "EVM_", "WALLET_"];
+const REVEALABLE_KEY_PREFIXES = [
+    "OPENAI_",
+    "ANTHROPIC_",
+    "GOOGLE_",
+    "GROQ_",
+    "MISTRAL_",
+    "PERPLEXITY_",
+    "COHERE_",
+    "TOGETHER_",
+    "FIREWORKS_",
+    "REPLICATE_",
+    "HUGGINGFACE_",
+    "ELEVENLABS_",
+    "DISCORD_",
+    "TELEGRAM_",
+    "TWITTER_",
+    "SLACK_",
+    "GITHUB_",
+    "REDIS_",
+    "POSTGRES_",
+    "DATABASE_",
+    "SUPABASE_",
+    "PINECONE_",
+    "QDRANT_",
+    "WEAVIATE_",
+    "CHROMADB_",
+    "AWS_",
+    "AZURE_",
+    "CLOUDFLARE_",
+    "ELIZA_",
+    "ELIZA_",
+    "PLUGIN_",
+    "XAI_",
+    "DEEPSEEK_",
+    "OLLAMA_",
+    "FAL_",
+    "LETZAI_",
+    "GAIANET_",
+    "LIVEPEER_",
+    ...SENSITIVE_KEY_PREFIXES,
+];
+const DRIFT_LOG_THROTTLE_MS = 5 * 60 * 1000;
+let _lastDriftWarningAt = 0;
+let _lastDriftWarningFingerprint = "";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+// Re-exported so existing call sites keep working. The implementations
+// live in services/vault-mirror.ts so unit tests can import them
+// without dragging in the @elizaos/agent runtime through this file.
+export { _resetSharedVaultForTesting, mirrorPluginSensitiveToVault };
+function maskValue(value) {
+    if (value.length <= 8)
+        return "****";
+    return `${value.slice(0, 4)}...${value.slice(-4)}`;
+}
+function normalizePluginCategory(value) {
+    switch (value) {
+        case "ai-provider":
+        case "connector":
+        case "streaming":
+        case "database":
+        case "app":
+            return value;
+        default:
+            return "feature";
+    }
+}
+function normalizePluginId(rawName) {
+    const scopedPackage = rawName.match(/^@[^/]+\/(?:plugin|app)-(.+)$/);
+    if (scopedPackage) {
+        return scopedPackage[1] ?? rawName;
+    }
+    return rawName.replace(/^@[^/]+\//, "").replace(/^(plugin|app)-/, "");
+}
+function resolveCompatConfigKey(pluginId, npmName, pluginMap) {
+    const candidates = new Set([pluginId, normalizePluginId(pluginId)]);
+    if (typeof npmName === "string" && npmName.length > 0) {
+        candidates.add(npmName);
+        candidates.add(normalizePluginId(npmName));
+    }
+    for (const [configKey, packageName] of Object.entries(pluginMap)) {
+        if (candidates.has(configKey) ||
+            candidates.has(packageName) ||
+            candidates.has(normalizePluginId(packageName))) {
+            return configKey;
+        }
+    }
+    return null;
+}
+function readCompatSectionEnabled(section, configKey) {
+    if (!configKey) {
+        return undefined;
+    }
+    const sectionRecord = asRecord(section);
+    if (!sectionRecord) {
+        return undefined;
+    }
+    const targetRecord = asRecord(sectionRecord[configKey]);
+    if (!targetRecord || typeof targetRecord.enabled !== "boolean") {
+        return undefined;
+    }
+    return targetRecord.enabled;
+}
+function writeCompatSectionEnabled(parent, sectionKey, configKey, enabled) {
+    if (!configKey) {
+        return;
+    }
+    const section = asRecord(parent[sectionKey]) ?? {};
+    const entry = asRecord(section[configKey]) ?? {};
+    entry.enabled = enabled;
+    section[configKey] = entry;
+    parent[sectionKey] = section;
+}
+function syncCompatConnectorConfigValues(config, pluginId, npmName, values) {
+    const connectorKey = resolveCompatConfigKey(pluginId, npmName, CONNECTOR_PLUGINS);
+    if (!connectorKey) {
+        return;
+    }
+    const envMap = CONNECTOR_ENV_MAP[connectorKey];
+    if (!envMap) {
+        return;
+    }
+    const typedEnvMap = envMap;
+    const connectors = asRecord(config.connectors) ?? {};
+    const connectorEntry = asRecord(connectors[connectorKey]) ?? {};
+    const envToField = new Map();
+    for (const [field, envKey] of Object.entries(typedEnvMap)) {
+        if (!envToField.has(envKey)) {
+            envToField.set(envKey, field);
+        }
+    }
+    let touched = false;
+    for (const [envKey, field] of envToField.entries()) {
+        if (!(envKey in values)) {
+            continue;
+        }
+        touched = true;
+        const value = values[envKey];
+        if (value.trim()) {
+            connectorEntry[field] = value;
+        }
+        else {
+            delete connectorEntry[field];
+        }
+    }
+    // Canonicalize Discord onto `connectors.discord.token`; keep the legacy
+    // `botToken` alias cleared so the config does not drift between fields.
+    if (connectorKey === "discord" && "DISCORD_API_TOKEN" in values) {
+        touched = true;
+        const tokenValue = values.DISCORD_API_TOKEN.trim();
+        if (tokenValue) {
+            connectorEntry.token = tokenValue;
+        }
+        else {
+            delete connectorEntry.token;
+        }
+        delete connectorEntry.botToken;
+    }
+    if (!touched) {
+        return;
+    }
+    connectors[connectorKey] = connectorEntry;
+    config.connectors = connectors;
+}
+function resolvePersistedPluginEnabled(pluginId, category, npmName, configEntries, config) {
+    const pluginEnabled = typeof configEntries[pluginId]?.enabled === "boolean"
+        ? Boolean(configEntries[pluginId]?.enabled)
+        : undefined;
+    if (category === "connector") {
+        const connectorEnabled = readCompatSectionEnabled(config.connectors, resolveCompatConfigKey(pluginId, npmName, CONNECTOR_PLUGINS));
+        return connectorEnabled ?? pluginEnabled;
+    }
+    if (category === "streaming") {
+        const streamingEnabled = readCompatSectionEnabled(config.streaming, resolveCompatConfigKey(pluginId, npmName, STREAMING_PLUGINS));
+        return streamingEnabled ?? pluginEnabled;
+    }
+    return pluginEnabled;
+}
+export function resolveCompatPluginEnabledForList(active, persistedEnabled, advancedCapabilityEnabled) {
+    return advancedCapabilityEnabled ?? persistedEnabled ?? active;
+}
+function shortPluginIdFromNpmName(npmName) {
+    if (!npmName || typeof npmName !== "string") {
+        return null;
+    }
+    if (npmName.startsWith("@elizaos/app-")) {
+        return npmName.slice("@elizaos/".length);
+    }
+    if (npmName.startsWith("@elizaos/plugin-")) {
+        return npmName.slice("@elizaos/plugin-".length);
+    }
+    return normalizePluginId(npmName);
+}
+export function analyzePluginStateDrift(pluginList, configRecord, configEntries, allowList) {
+    const diagnostics = pluginList.map((plugin) => {
+        const pluginId = String(plugin.id ?? "");
+        const category = normalizePluginCategory(plugin.category);
+        const npmName = typeof plugin.npmName === "string" && plugin.npmName.length > 0
+            ? plugin.npmName
+            : null;
+        const shortId = shortPluginIdFromNpmName(npmName) ?? pluginId;
+        const uiEnabled = Boolean(plugin.enabled);
+        const compatEnabled = category === "connector"
+            ? readCompatSectionEnabled(configRecord.connectors, resolveCompatConfigKey(pluginId, npmName ?? undefined, CONNECTOR_PLUGINS))
+            : category === "streaming"
+                ? readCompatSectionEnabled(configRecord.streaming, resolveCompatConfigKey(pluginId, npmName ?? undefined, STREAMING_PLUGINS))
+                : undefined;
+        const entryEnabled = typeof configEntries[pluginId]?.enabled === "boolean"
+            ? Boolean(configEntries[pluginId]?.enabled)
+            : undefined;
+        const enabledAllowList = allowList === null || npmName == null
+            ? null
+            : allowList.has(npmName) || allowList.has(shortId);
+        const isActive = Boolean(plugin.isActive);
+        const driftFlags = [];
+        if (compatEnabled !== undefined &&
+            entryEnabled !== undefined &&
+            compatEnabled !== entryEnabled) {
+            driftFlags.push("entries_vs_compat");
+        }
+        if (enabledAllowList !== null && entryEnabled !== undefined) {
+            if (enabledAllowList !== entryEnabled) {
+                driftFlags.push("entries_vs_allowlist");
+            }
+        }
+        if (uiEnabled && !isActive) {
+            driftFlags.push("inactive_but_enabled");
+        }
+        if (!uiEnabled && isActive) {
+            driftFlags.push("active_but_disabled");
+        }
+        return {
+            pluginId,
+            npmName,
+            category,
+            enabled_ui: uiEnabled,
+            enabled_allowlist: enabledAllowList,
+            is_active: isActive,
+            drift_flags: driftFlags,
+        };
+    });
+    const withDrift = diagnostics.filter((plugin) => plugin.drift_flags.length > 0);
+    const byFlag = {
+        entries_vs_compat: 0,
+        entries_vs_allowlist: 0,
+        inactive_but_enabled: 0,
+        active_but_disabled: 0,
+    };
+    for (const plugin of withDrift) {
+        for (const flag of plugin.drift_flags) {
+            byFlag[flag] += 1;
+        }
+    }
+    return {
+        summary: {
+            total: diagnostics.length,
+            withDrift: withDrift.length,
+            byFlag,
+        },
+        plugins: diagnostics,
+    };
+}
+function buildPluginDriftDiagnostics(runtime) {
+    const pluginList = buildPluginListResponse(runtime).plugins;
+    const config = loadElizaConfig();
+    const configRecord = config;
+    const configEntries = config.plugins?.entries ?? {};
+    const allowList = Array.isArray(config.plugins?.allow)
+        ? new Set(config.plugins.allow)
+        : null;
+    return analyzePluginStateDrift(pluginList, configRecord, configEntries, allowList);
+}
+function maybeLogPluginStateDrift(report) {
+    if (report.summary.withDrift === 0) {
+        return;
+    }
+    const drifted = report.plugins
+        .filter((plugin) => plugin.drift_flags.length > 0)
+        .map((plugin) => `${plugin.pluginId}:${plugin.drift_flags.join("+")}`)
+        .sort();
+    const fingerprint = drifted.join("|");
+    const now = Date.now();
+    if (fingerprint === _lastDriftWarningFingerprint &&
+        now - _lastDriftWarningAt < DRIFT_LOG_THROTTLE_MS) {
+        return;
+    }
+    _lastDriftWarningAt = now;
+    _lastDriftWarningFingerprint = fingerprint;
+    logger.warn({
+        src: "api:plugins",
+        driftCount: report.summary.withDrift,
+        byFlag: report.summary.byFlag,
+        plugins: drifted,
+    }, "Plugin enable-state drift detected between /api/plugins and /api/plugins/core models");
+}
+// ── Enabled-state drift reconciliation ────────────────────────────────
+//
+// The write path (persistCompatPluginMutation) always updates both
+// plugins.entries[id].enabled AND the compat connector/streaming section.
+// However drift can occur if the config file is edited externally or a
+// migration only touched one location.  This pass detects any mismatch
+// and re-synchronises the compat section from plugins.entries, which is
+// the canonical source for the Settings UI.
+//
+// Runs once per process on the first buildPluginListResponse() call.
+let _enabledStateReconciled = false;
+function reconcilePluginEnabledStates() {
+    if (_enabledStateReconciled)
+        return;
+    _enabledStateReconciled = true;
+    const config = loadElizaConfig();
+    const configRecord = config;
+    const entries = (config.plugins?.entries ?? {});
+    let dirty = false;
+    for (const [pluginId, entry] of Object.entries(entries)) {
+        if (typeof entry.enabled !== "boolean")
+            continue;
+        // Check connector section
+        const connectorKey = resolveCompatConfigKey(pluginId, undefined, CONNECTOR_PLUGINS);
+        if (connectorKey) {
+            const sectionEnabled = readCompatSectionEnabled(configRecord.connectors, connectorKey);
+            if (sectionEnabled !== undefined && sectionEnabled !== entry.enabled) {
+                writeCompatSectionEnabled(configRecord, "connectors", connectorKey, entry.enabled);
+                dirty = true;
+            }
+        }
+        // Check streaming section
+        const streamingKey = resolveCompatConfigKey(pluginId, undefined, STREAMING_PLUGINS);
+        if (streamingKey) {
+            const sectionEnabled = readCompatSectionEnabled(configRecord.streaming, streamingKey);
+            if (sectionEnabled !== undefined && sectionEnabled !== entry.enabled) {
+                writeCompatSectionEnabled(configRecord, "streaming", streamingKey, entry.enabled);
+                dirty = true;
+            }
+        }
+    }
+    if (dirty) {
+        saveElizaConfig(config);
+        logger.info("[plugins] Reconciled drifted plugin enabled states in config");
+    }
+}
+function compatMutationRequiresRestart(plugin, body) {
+    if (typeof body.enabled === "boolean") {
+        return true;
+    }
+    if (body.config !== undefined &&
+        (plugin.category === "connector" || plugin.category === "streaming")) {
+        return true;
+    }
+    return false;
+}
+function createCompatRuntimeApplyFallback(reason, requiresRestart) {
+    return {
+        mode: requiresRestart ? "restart_required" : "none",
+        requiresRestart,
+        restartedRuntime: false,
+        loadedPackages: [],
+        unloadedPackages: [],
+        reloadedPackages: [],
+        appliedConfigPackage: null,
+        reason,
+    };
+}
+async function applyCompatRuntimeMutation(options) {
+    const { state, pluginId, plugin, body, previousConfig, nextConfig } = options;
+    const reason = typeof body.enabled === "boolean"
+        ? `Plugin toggle: ${pluginId}`
+        : `Plugin config updated: ${pluginId}`;
+    const requiresRestartFallback = compatMutationRequiresRestart(plugin, body);
+    if (!state.current) {
+        return createCompatRuntimeApplyFallback(reason, requiresRestartFallback);
+    }
+    try {
+        return await applyPluginRuntimeMutation({
+            runtime: state.current,
+            previousConfig,
+            nextConfig,
+            changedPluginId: pluginId,
+            changedPluginPackage: plugin.npmName,
+            config: body.config &&
+                typeof body.config === "object" &&
+                !Array.isArray(body.config)
+                ? body.config
+                : undefined,
+            expectRuntimeGraphChange: typeof body.enabled === "boolean",
+            reason,
+        });
+    }
+    catch (error) {
+        logger.warn(`[api/plugins] Live runtime apply failed for "${pluginId}": ${error instanceof Error ? error.message : String(error)}`);
+        return createCompatRuntimeApplyFallback(reason, true);
+    }
+}
+function titleCasePluginId(id) {
+    return id
+        .split("-")
+        .filter((segment) => segment.length > 0)
+        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join(" ");
+}
+function inferSensitiveConfigKey(key) {
+    return /(?:_API_KEY|_SECRET|_TOKEN|_PASSWORD|_PRIVATE_KEY|_SIGNING_|ENCRYPTION_)/i.test(key);
+}
+function buildPluginParamDefs(parameters, savedValues) {
+    if (!parameters) {
+        return [];
+    }
+    // Drop generic fallback model keys (SMALL_MODEL, LARGE_MODEL, IMAGE_MODEL,
+    // EMBEDDING_MODEL) when a provider-prefixed equivalent (e.g.
+    // GOOGLE_SMALL_MODEL) is also declared. Plugins like @elizaos/plugin-google-genai
+    // declare both — surfacing both creates confusing duplicate fields in the UI.
+    const allKeys = Object.keys(parameters);
+    const GENERIC_FALLBACK_SUFFIXES = [
+        "SMALL_MODEL",
+        "LARGE_MODEL",
+        "IMAGE_MODEL",
+        "EMBEDDING_MODEL",
+    ];
+    const filteredEntries = Object.entries(parameters).filter(([key]) => {
+        if (!GENERIC_FALLBACK_SUFFIXES.includes(key))
+            return true;
+        return !allKeys.some((other) => other !== key && other.endsWith(`_${key}`));
+    });
+    return filteredEntries.map(([key, definition]) => {
+        const envValue = process.env[key]?.trim() || undefined;
+        const savedValue = savedValues?.[key];
+        const effectiveValue = envValue ?? (savedValue ? savedValue.trim() || undefined : undefined);
+        const isSet = Boolean(effectiveValue);
+        const sensitive = typeof definition.sensitive === "boolean"
+            ? definition.sensitive
+            : inferSensitiveConfigKey(key);
+        const currentValue = !isSet || !effectiveValue
+            ? null
+            : sensitive
+                ? maskValue(effectiveValue)
+                : effectiveValue;
+        return {
+            key,
+            type: definition.type ?? "string",
+            description: definition.description ?? "",
+            required: definition.required === true ||
+                (definition.optional === false && definition.required !== false),
+            sensitive,
+            default: definition.default === undefined
+                ? undefined
+                : String(definition.default),
+            options: Array.isArray(definition.options)
+                ? definition.options
+                : undefined,
+            currentValue,
+            isSet,
+        };
+    });
+}
+function findNearestFile(startDir, fileName, maxDepth = 12) {
+    let dir = path.resolve(startDir);
+    for (let depth = 0; depth <= maxDepth; depth += 1) {
+        const candidate = path.join(dir, fileName);
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return null;
+}
+export function resolvePluginManifestPath() {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        process.cwd(),
+        moduleDir,
+        path.dirname(process.execPath),
+        path.join(path.dirname(process.execPath), "..", "Resources", "app"),
+    ];
+    for (const candidate of candidates) {
+        const manifestPath = findNearestFile(candidate, "plugins.json");
+        if (manifestPath) {
+            return manifestPath;
+        }
+    }
+    return null;
+}
+function resolveInstalledPackageVersion(packageName) {
+    if (!packageName) {
+        return null;
+    }
+    try {
+        const packageJsonPath = require.resolve(`${packageName}/package.json`);
+        const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveLoadedPluginNames(runtime) {
+    const loadedNames = new Set();
+    for (const plugin of runtime?.plugins ?? []) {
+        const name = plugin.name;
+        if (typeof name === "string" && name.length > 0) {
+            loadedNames.add(name);
+        }
+    }
+    return loadedNames;
+}
+function isPluginLoaded(pluginId, npmName, loadedNames) {
+    const expectedNames = new Set([
+        pluginId,
+        `plugin-${pluginId}`,
+        `app-${pluginId}`,
+        npmName ?? "",
+    ]);
+    for (const loadedName of loadedNames) {
+        if (expectedNames.has(loadedName)) {
+            return true;
+        }
+        if (loadedName.endsWith(`/plugin-${pluginId}`) ||
+            loadedName.endsWith(`/app-${pluginId}`) ||
+            loadedName.includes(pluginId)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function resolveAdvancedCapabilityCompatStatus(pluginId, config, runtime) {
+    if (!isAdvancedCapabilityPluginId(pluginId)) {
+        return null;
+    }
+    const enabled = resolveAdvancedCapabilitiesEnabled(config);
+    if (!enabled) {
+        return { enabled: false, isActive: false };
+    }
+    const serviceType = ADVANCED_CAPABILITY_SERVICE_BY_PLUGIN_ID[pluginId];
+    return {
+        enabled: true,
+        isActive: serviceType
+            ? Boolean(runtime?.getService(serviceType))
+            : Boolean(runtime),
+    };
+}
+export function buildPluginListResponse(runtime) {
+    reconcilePluginEnabledStates();
+    const config = loadElizaConfig();
+    const configRecord = config;
+    const loadedNames = resolveLoadedPluginNames(runtime);
+    // Primary source: registry entries. Workspace plugin discovery fills gaps
+    // for local first-party plugin packages that have not been registered yet.
+    const registry = loadRegistry();
+    const manifestRoot = resolvePluginManifestPath()
+        ? path.dirname(resolvePluginManifestPath() ?? "")
+        : process.cwd();
+    const manifest = {
+        plugins: registry.all.map(registryEntryToManifest),
+    };
+    const configEntries = config.plugins?.entries ?? {};
+    const installEntries = config.plugins?.installs ?? {};
+    const plugins = new Map();
+    for (const entry of manifest?.plugins ?? []) {
+        const pluginId = normalizePluginId(entry.id);
+        const category = normalizePluginCategory(entry.category);
+        const bundledMeta = entry.dirName && manifestRoot
+            ? readBundledPluginPackageMetadata(manifestRoot, entry.dirName, entry.npmName)
+            : undefined;
+        const configKeys = Array.isArray(entry.configKeys) && entry.configKeys.length > 0
+            ? entry.configKeys
+            : (bundledMeta?.configKeys ?? []);
+        const envKey = entry.envKey ?? findPrimaryEnvKey(configKeys);
+        const parameters = buildPluginParamDefs(entry.pluginParameters ?? bundledMeta?.pluginParameters);
+        const advancedCapabilityStatus = resolveAdvancedCapabilityCompatStatus(pluginId, config, runtime);
+        const active = advancedCapabilityStatus?.isActive ??
+            isPluginLoaded(pluginId, entry.npmName, loadedNames);
+        const persistedEnabled = resolvePersistedPluginEnabled(pluginId, category, entry.npmName, configEntries, configRecord);
+        const enabled = resolveCompatPluginEnabledForList(active, persistedEnabled, advancedCapabilityStatus?.enabled);
+        const validationErrors = parameters
+            .filter((parameter) => parameter.required && !parameter.isSet)
+            .map((parameter) => ({
+            field: parameter.key,
+            message: "Required value is not configured.",
+        }));
+        const registryEntry = registry.byId.get(pluginId);
+        plugins.set(pluginId, {
+            id: pluginId,
+            name: entry.name ?? titleCasePluginId(pluginId),
+            description: entry.description ?? bundledMeta?.description ?? "",
+            tags: entry.tags ?? [],
+            enabled,
+            configured: validationErrors.length === 0,
+            envKey,
+            category,
+            source: "bundled",
+            configKeys,
+            parameters,
+            validationErrors,
+            validationWarnings: [],
+            npmName: entry.npmName,
+            version: resolveInstalledPackageVersion(entry.npmName) ??
+                entry.version ??
+                undefined,
+            pluginDeps: entry.pluginDeps,
+            isActive: active,
+            configUiHints: entry.configUiHints ?? bundledMeta?.configUiHints,
+            icon: entry.logoUrl ?? bundledMeta?.icon ?? null,
+            homepage: entry.homepage ?? bundledMeta?.homepage,
+            repository: entry.repository ?? bundledMeta?.repository,
+            setupGuideUrl: entry.setupGuideUrl,
+            iconName: registryEntry?.render.icon,
+            group: registryEntry?.render.group,
+            groupOrder: registryEntry?.render.groupOrder,
+            visible: registryEntry?.render.visible ?? true,
+        });
+    }
+    for (const entry of discoverPluginsFromManifest()) {
+        const pluginId = normalizePluginId(entry.id);
+        const category = normalizePluginCategory(entry.category);
+        if (category === "app" || plugins.has(pluginId)) {
+            continue;
+        }
+        const active = isPluginLoaded(pluginId, entry.npmName, loadedNames);
+        const persistedEnabled = resolvePersistedPluginEnabled(pluginId, category, entry.npmName, configEntries, configRecord);
+        plugins.set(pluginId, {
+            id: pluginId,
+            name: entry.name,
+            description: entry.description,
+            tags: entry.tags ?? [],
+            enabled: resolveCompatPluginEnabledForList(active, persistedEnabled),
+            configured: entry.configured,
+            envKey: entry.envKey,
+            category,
+            source: entry.source,
+            configKeys: entry.configKeys,
+            parameters: entry.parameters,
+            validationErrors: entry.validationErrors,
+            validationWarnings: entry.validationWarnings,
+            npmName: entry.npmName,
+            version: resolveInstalledPackageVersion(entry.npmName) ??
+                entry.version ??
+                undefined,
+            pluginDeps: entry.pluginDeps,
+            isActive: active,
+            configUiHints: entry.configUiHints,
+            icon: entry.icon ?? null,
+            homepage: entry.homepage,
+            repository: entry.repository,
+            setupGuideUrl: entry.setupGuideUrl,
+            visible: true,
+        });
+    }
+    for (const plugin of runtime?.plugins ?? []) {
+        const pluginName = typeof plugin.name === "string"
+            ? plugin.name
+            : "";
+        if (!pluginName) {
+            continue;
+        }
+        const pluginId = normalizePluginId(pluginName);
+        const existing = plugins.get(pluginId);
+        if (existing) {
+            existing.isActive = true;
+            if (existing.enabled !== true &&
+                configEntries[pluginId]?.enabled == null) {
+                existing.enabled = true;
+            }
+            if (!existing.version) {
+                existing.version =
+                    resolveInstalledPackageVersion(pluginName) ?? undefined;
+            }
+            continue;
+        }
+        plugins.set(pluginId, {
+            id: pluginId,
+            name: titleCasePluginId(pluginId),
+            description: plugin.description ??
+                "Loaded runtime plugin discovered without manifest metadata.",
+            tags: [],
+            enabled: typeof configEntries[pluginId]?.enabled === "boolean"
+                ? Boolean(configEntries[pluginId]?.enabled)
+                : true,
+            configured: true,
+            envKey: null,
+            category: "feature",
+            source: "bundled",
+            parameters: [],
+            validationErrors: [],
+            validationWarnings: [],
+            npmName: pluginName,
+            version: resolveInstalledPackageVersion(pluginName) ?? undefined,
+            isActive: true,
+            icon: null,
+        });
+    }
+    for (const [pluginName, installRecord] of Object.entries(installEntries)) {
+        const pluginId = normalizePluginId(pluginName);
+        if (plugins.has(pluginId)) {
+            continue;
+        }
+        plugins.set(pluginId, {
+            id: pluginId,
+            name: titleCasePluginId(pluginId),
+            description: "Installed store plugin.",
+            tags: [],
+            enabled: typeof configEntries[pluginId]?.enabled === "boolean"
+                ? Boolean(configEntries[pluginId]?.enabled)
+                : false,
+            configured: true,
+            envKey: null,
+            category: "feature",
+            source: "store",
+            parameters: [],
+            validationErrors: [],
+            validationWarnings: [],
+            npmName: pluginName,
+            version: typeof installRecord?.version === "string"
+                ? installRecord.version
+                : (resolveInstalledPackageVersion(pluginName) ?? undefined),
+            isActive: isPluginLoaded(pluginId, pluginName, loadedNames),
+            icon: null,
+        });
+    }
+    const pluginList = Array.from(plugins.values()).sort((left, right) => String(left.name ?? "").localeCompare(String(right.name ?? "")));
+    return { plugins: pluginList };
+}
+function validateCompatPluginConfig(plugin, config) {
+    const paramMap = new Map(plugin.parameters.map((parameter) => [parameter.key, parameter]));
+    const errors = [];
+    const values = {};
+    for (const [key, rawValue] of Object.entries(config)) {
+        const parameter = paramMap.get(key);
+        if (!parameter) {
+            errors.push({
+                field: key,
+                message: `${key} is not a declared config key for this plugin`,
+            });
+            continue;
+        }
+        if (typeof rawValue !== "string") {
+            errors.push({
+                field: key,
+                message: "Plugin config values must be strings.",
+            });
+            continue;
+        }
+        const trimmed = rawValue.trim();
+        if (parameter.required && trimmed.length === 0) {
+            errors.push({
+                field: key,
+                message: "Required value is not configured.",
+            });
+            continue;
+        }
+        values[key] = rawValue;
+    }
+    return { errors, values };
+}
+export function persistCompatPluginMutation(pluginId, body, plugin) {
+    const config = loadElizaConfig();
+    const configRecord = config;
+    config.plugins ??= {};
+    config.plugins.entries ??= {};
+    config.plugins.entries[pluginId] ??= {};
+    const pluginEntry = config.plugins.entries[pluginId];
+    if (typeof body.enabled === "boolean") {
+        pluginEntry.enabled = body.enabled;
+        if (CAPABILITY_FEATURE_IDS.has(pluginId)) {
+            config.features ??= {};
+            config.features[pluginId] = body.enabled;
+        }
+        if (plugin.category === "connector") {
+            writeCompatSectionEnabled(configRecord, "connectors", resolveCompatConfigKey(pluginId, plugin.npmName, CONNECTOR_PLUGINS), body.enabled);
+        }
+        if (plugin.category === "streaming") {
+            writeCompatSectionEnabled(configRecord, "streaming", resolveCompatConfigKey(pluginId, plugin.npmName, STREAMING_PLUGINS), body.enabled);
+        }
+    }
+    if (body.config !== undefined) {
+        if (!body.config ||
+            typeof body.config !== "object" ||
+            Array.isArray(body.config)) {
+            return {
+                status: 400,
+                payload: { ok: false, error: "Plugin config must be a JSON object." },
+            };
+        }
+        const configObject = body.config;
+        const { errors, values } = validateCompatPluginConfig(plugin, configObject);
+        if (errors.length > 0) {
+            return {
+                status: 422,
+                payload: { ok: false, plugin, validationErrors: errors },
+            };
+        }
+        const nextConfig = pluginEntry.config &&
+            typeof pluginEntry.config === "object" &&
+            !Array.isArray(pluginEntry.config)
+            ? { ...pluginEntry.config }
+            : {};
+        config.env ??= {};
+        for (const [key, value] of Object.entries(values)) {
+            if (value.trim()) {
+                config.env[key] = value;
+                nextConfig[key] = value;
+            }
+            else {
+                delete config.env[key];
+                delete nextConfig[key];
+            }
+        }
+        pluginEntry.config = nextConfig;
+        if (plugin.category === "connector") {
+            syncCompatConnectorConfigValues(configRecord, pluginId, plugin.npmName, values);
+        }
+        saveElizaConfig(config);
+        for (const [key, value] of Object.entries(values)) {
+            try {
+                if (value.trim()) {
+                    process.env[key] = value;
+                }
+                else {
+                    delete process.env[key];
+                }
+            }
+            catch {
+                // process.env may be read-only in sandboxed or frozen environments.
+                // Config is already persisted to disk above, so this is non-fatal.
+            }
+        }
+    }
+    else {
+        saveElizaConfig(config);
+    }
+    const refreshed = buildPluginListResponse(null).plugins.find((candidate) => candidate.id === pluginId);
+    return {
+        status: 200,
+        payload: {
+            ok: true,
+            plugin: refreshed ?? plugin,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Route handler
+// ---------------------------------------------------------------------------
+/**
+ * Plugin management routes.
+ *
+ * Contract note:
+ * - `/api/plugins` is the Settings/UI model.
+ * - `/api/plugins/core` is the optional-core allow-list model.
+ * - These can drift; use `/api/plugins/diagnostics` to inspect mismatches.
+ *
+ * - `GET  /api/plugins`             — returns filtered plugin list
+ * - `GET  /api/plugins/diagnostics` — returns drift diagnostics
+ * - `PUT  /api/plugins/:id`         — updates plugin config, writes env vars
+ * - `POST /api/plugins/:id/test`    — tests plugin connectivity
+ * - `POST /api/plugins/:id/reveal`  — reveals plugin env var value
+ */
+export async function handlePluginsCompatRoutes(req, res, state) {
+    const method = (req.method ?? "GET").toUpperCase();
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (!url.pathname.startsWith("/api/plugins")) {
+        return false;
+    }
+    if (method === "GET" && url.pathname === "/api/plugins") {
+        if (!(await ensureRouteAuthorized(req, res, state))) {
+            return true;
+        }
+        const pluginResponse = buildPluginListResponse(state.current);
+        logger.debug(`[api/plugins] source=registry total=${pluginResponse.plugins.length} runtime=${state.current ? "active" : "null"}`);
+        maybeLogPluginStateDrift(buildPluginDriftDiagnostics(state.current));
+        sendJsonResponse(res, 200, pluginResponse);
+        return true;
+    }
+    if (method === "GET" && url.pathname === "/api/plugins/diagnostics") {
+        if (!(await ensureRouteAuthorized(req, res, state))) {
+            return true;
+        }
+        const diagnostics = buildPluginDriftDiagnostics(state.current);
+        maybeLogPluginStateDrift(diagnostics);
+        sendJsonResponse(res, 200, diagnostics);
+        return true;
+    }
+    if (method === "PUT" && url.pathname.startsWith("/api/plugins/")) {
+        if (!(await ensureRouteAuthorized(req, res, state))) {
+            return true;
+        }
+        const body = await readCompatJsonBody(req, res);
+        if (body == null) {
+            return true;
+        }
+        const pluginId = normalizePluginId(decodeURIComponent(url.pathname.slice("/api/plugins/".length)));
+        const plugin = buildPluginListResponse(state.current).plugins.find((candidate) => candidate.id === pluginId);
+        if (!plugin) {
+            sendJsonErrorResponse(res, 404, `Plugin "${pluginId}" not found`);
+            return true;
+        }
+        const previousConfig = structuredClone(loadElizaConfig());
+        const result = persistCompatPluginMutation(pluginId, body, plugin);
+        if (result.status === 200) {
+            const nextConfig = loadElizaConfig();
+            const runtimeApply = await applyCompatRuntimeMutation({
+                state,
+                pluginId,
+                plugin,
+                body,
+                previousConfig,
+                nextConfig,
+            });
+            if (runtimeApply.requiresRestart) {
+                scheduleCompatRuntimeRestart(state, runtimeApply.reason);
+            }
+            const refreshed = buildPluginListResponse(state.current).plugins.find((candidate) => candidate.id === pluginId);
+            result.payload.plugin = refreshed ?? result.payload.plugin ?? plugin;
+            result.payload.applied = runtimeApply.mode;
+            result.payload.requiresRestart = runtimeApply.requiresRestart;
+            result.payload.restartedRuntime = runtimeApply.restartedRuntime;
+            result.payload.loadedPackages = runtimeApply.loadedPackages;
+            result.payload.unloadedPackages = runtimeApply.unloadedPackages;
+            result.payload.reloadedPackages = runtimeApply.reloadedPackages;
+            // Write-through mirror to @elizaos/vault. Sensitive fields the
+            // user just saved are copied into the vault (encrypted at rest
+            // via the OS-keychain master key). The legacy `config.env.X` /
+            // `config.env.vars.X` writes still happen above — vault is a
+            // SHADOW of those for now. The runtime continues to read from
+            // process.env via the legacy hydration path; vault becomes the
+            // canonical source in a follow-up PR.
+            //
+            // Failure mode: if vault.set throws for some keys (OS keychain
+            // locked, file ENOSPC, missing master key, etc.), the save is
+            // NOT rolled back — legacy storage already succeeded above. We
+            // surface the failed keys back to the UI under
+            // `vaultMirrorFailures` so the user knows the vault mirror
+            // didn't take, instead of silently swallowing the error and
+            // showing a green "Saved" toast over an empty vault.
+            const mirrorResult = await mirrorPluginSensitiveToVault(plugin, body);
+            if (mirrorResult.failures.length > 0) {
+                result.payload.vaultMirrorFailures = mirrorResult.failures;
+            }
+            const diagnostics = buildPluginDriftDiagnostics(state.current);
+            if (diagnostics.summary.withDrift > 0) {
+                result.payload.diagnostics = diagnostics;
+            }
+        }
+        sendJsonResponse(res, result.status, result.payload);
+        return true;
+    }
+    const testMatch = method === "POST" && url.pathname.match(/^\/api\/plugins\/([^/]+)\/test$/);
+    if (testMatch) {
+        if (!(await ensureRouteAuthorized(req, res, state)))
+            return true;
+        const testPluginId = normalizePluginId(decodeURIComponent(testMatch[1]));
+        const startMs = Date.now();
+        if (testPluginId === "telegram") {
+            const token = process.env.TELEGRAM_BOT_TOKEN;
+            if (!token) {
+                sendJsonResponse(res, 422, {
+                    success: false,
+                    pluginId: testPluginId,
+                    error: "No bot token configured",
+                    durationMs: Date.now() - startMs,
+                });
+                return true;
+            }
+            try {
+                const apiRoot = process.env.TELEGRAM_API_ROOT || "https://api.telegram.org";
+                const tgResp = await fetch(`${apiRoot}/bot${token}/getMe`);
+                const tgData = (await tgResp.json());
+                sendJsonResponse(res, tgData.ok ? 200 : 422, {
+                    success: tgData.ok,
+                    pluginId: testPluginId,
+                    message: tgData.ok
+                        ? `Connected as @${tgData.result?.username}`
+                        : `Telegram API error: ${tgData.description}`,
+                    durationMs: Date.now() - startMs,
+                });
+            }
+            catch (err) {
+                sendJsonResponse(res, 422, {
+                    success: false,
+                    pluginId: testPluginId,
+                    error: err instanceof Error ? err.message : String(err),
+                    durationMs: Date.now() - startMs,
+                });
+            }
+            return true;
+        }
+        sendJsonResponse(res, 200, {
+            success: true,
+            pluginId: testPluginId,
+            message: "Plugin is loaded (no custom test available)",
+            durationMs: Date.now() - startMs,
+        });
+        return true;
+    }
+    const revealMatch = method === "POST" &&
+        url.pathname.match(/^\/api\/plugins\/([^/]+)\/reveal$/);
+    if (revealMatch) {
+        if (!(await ensureRouteAuthorized(req, res, state)))
+            return true;
+        const revealBody = await readCompatJsonBody(req, res);
+        if (revealBody == null)
+            return true;
+        const key = revealBody.key?.trim();
+        if (!key) {
+            sendJsonErrorResponse(res, 400, "Missing key parameter");
+            return true;
+        }
+        const upperKey = key.toUpperCase();
+        if (!REVEALABLE_KEY_PREFIXES.some((prefix) => upperKey.startsWith(prefix))) {
+            sendJsonErrorResponse(res, 403, "Key is not in the allowlist of revealable plugin config keys");
+            return true;
+        }
+        // Wallet / private-key prefixes require elevated auth to prevent
+        // accidental exposure through the general plugin config UI.
+        if (SENSITIVE_KEY_PREFIXES.some((prefix) => upperKey.startsWith(prefix))) {
+            if (!ensureCompatSensitiveRouteAuthorized(req, res))
+                return true;
+        }
+        // Prefer the vault: post-write-through wiring means the user's
+        // actual saved value lives there. Fall back to env/config only when
+        // the vault has no entry; vault/keychain failures surface instead
+        // of pretending the legacy value is canonical.
+        try {
+            const vaultValue = await sharedVault().reveal(key, `plugins:${decodeURIComponent(revealMatch[1])}:reveal`);
+            sendJsonResponse(res, 200, { ok: true, value: vaultValue });
+            return true;
+        }
+        catch (err) {
+            if (!(err instanceof VaultMissError)) {
+                logger.warn(`[api/plugins] Vault reveal failed for ${key}: ${err instanceof Error ? err.message : String(err)}`);
+                sendJsonErrorResponse(res, 500, "Vault reveal failed");
+                return true;
+            }
+        }
+        const config = loadElizaConfig();
+        const fallbackValue = process.env[key] ??
+            config.env?.[key] ??
+            null;
+        // The legacy fallback may itself be a `vault://KEY` sentinel — in that
+        // case the real value is back in the vault. Resolve it once. If the
+        // vault still misses, return null rather than the sentinel string.
+        if (typeof fallbackValue === "string" && isVaultRef(fallbackValue)) {
+            const innerKey = parseVaultRef(fallbackValue);
+            if (innerKey) {
+                try {
+                    const inner = await sharedVault().get(innerKey);
+                    if (inner) {
+                        sendJsonResponse(res, 200, { ok: true, value: inner });
+                        return true;
+                    }
+                }
+                catch {
+                    // fall through to null
+                }
+            }
+            sendJsonResponse(res, 200, { ok: true, value: null });
+            return true;
+        }
+        sendJsonResponse(res, 200, { ok: true, value: fallbackValue });
+        return true;
+    }
+    return false;
+}