@elizaos/autonomous 2.0.0-alpha.37

package/dist/packages/autonomous/src/runtime/eliza.js

@@ -0,0 +1,3767 @@
+/**
+ * elizaOS runtime entry point for Milady.
+ *
+ * Starts the elizaOS agent runtime with Milady's plugin configuration.
+ * Can be run directly via: node --import tsx src/runtime/eliza.ts
+ * Or via the CLI: milady start
+ *
+ * @module eliza
+ */
+import crypto from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, symlinkSync, unlinkSync, } from "node:fs";
+import fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import * as readline from "node:readline";
+import { fileURLToPath, pathToFileURL } from "node:url";
+let _clack = null;
+async function loadClack() {
+    if (!_clack)
+        _clack = await import("@clack/prompts");
+    return _clack;
+}
+import { AgentRuntime, AutonomyService, addLogListener, ChannelType, createMessageMemory, logger, 
+// loggerScope, // removed
+mergeCharacterDefaults, stringToUuid, } from "@elizaos/core";
+import * as pluginAgentOrchestrator from "@elizaos/plugin-agent-orchestrator";
+import * as pluginAgentSkills from "@elizaos/plugin-agent-skills";
+import * as pluginAnthropic from "@elizaos/plugin-anthropic";
+import * as pluginCron from "@elizaos/plugin-cron";
+import * as pluginElizacloud from "@elizaos/plugin-elizacloud";
+import * as pluginExperience from "@elizaos/plugin-experience";
+import * as pluginForm from "@elizaos/plugin-form";
+import * as pluginKnowledge from "@elizaos/plugin-knowledge";
+import * as pluginLocalEmbedding from "@elizaos/plugin-local-embedding";
+import * as pluginOllama from "@elizaos/plugin-ollama";
+import * as pluginOpenai from "@elizaos/plugin-openai";
+import * as pluginPdf from "@elizaos/plugin-pdf";
+import * as pluginPersonality from "@elizaos/plugin-personality";
+import * as pluginPluginManager from "@elizaos/plugin-plugin-manager";
+import * as pluginRolodex from "@elizaos/plugin-rolodex";
+import * as pluginSecretsManager from "@elizaos/plugin-secrets-manager";
+import * as pluginShell from "@elizaos/plugin-shell";
+import * as pluginSql from "@elizaos/plugin-sql";
+import * as pluginTodo from "@elizaos/plugin-todo";
+import * as pluginTrajectoryLogger from "@elizaos/plugin-trajectory-logger";
+import * as pluginTrust from "@elizaos/plugin-trust";
+import { debugLogResolvedContext, validateRuntimeContext, } from "../api/plugin-validation";
+import { configFileExists, loadMiladyConfig, saveMiladyConfig, } from "../config/config";
+import { collectConfigEnvVars } from "../config/env-vars";
+import { resolveStateDir, resolveUserPath } from "../config/paths";
+import { applyPluginAutoEnable, } from "../config/plugin-auto-enable";
+import { createHookEvent, loadHooks, triggerHook, } from "../hooks/index";
+import { ensureAgentWorkspace, resolveDefaultAgentWorkspaceDir, } from "../providers/workspace";
+import { SandboxAuditLog } from "../security/audit-log";
+import { SandboxManager } from "../services/sandbox-manager";
+import { diagnoseNoAIProvider } from "../services/version-compat";
+import { createAutonomousPlugin } from "./autonomous-plugin";
+import { CORE_PLUGINS, OPTIONAL_CORE_PLUGINS } from "./core-plugins";
+import { detectEmbeddingPreset } from "./embedding-presets";
+import { installDatabaseTrajectoryLogger, shouldEnableTrajectoryLoggingByDefault, } from "./trajectory-persistence";
+/**
+ * Map of baseline bundled @elizaos plugin names to their statically imported
+ * modules.
+ *
+ * Post-release plugins are intentionally excluded so the packaged runtime can
+ * ship a smaller baseline bundle. Those plugins fall through to dynamic
+ * import() and can be installed later via the plugin installer.
+ */
+const STATIC_ELIZA_PLUGINS = {
+    "@elizaos/plugin-sql": pluginSql,
+    "@elizaos/plugin-local-embedding": pluginLocalEmbedding,
+    "@elizaos/plugin-secrets-manager": pluginSecretsManager,
+    "@elizaos/plugin-form": pluginForm,
+    "@elizaos/plugin-knowledge": pluginKnowledge,
+    "@elizaos/plugin-rolodex": pluginRolodex,
+    "@elizaos/plugin-trajectory-logger": pluginTrajectoryLogger,
+    "@elizaos/plugin-agent-orchestrator": pluginAgentOrchestrator,
+    "@elizaos/plugin-cron": pluginCron,
+    "@elizaos/plugin-shell": pluginShell,
+    "@elizaos/plugin-plugin-manager": pluginPluginManager,
+    "@elizaos/plugin-agent-skills": pluginAgentSkills,
+    "@elizaos/plugin-pdf": pluginPdf,
+    "@elizaos/plugin-openai": pluginOpenai,
+    "@elizaos/plugin-anthropic": pluginAnthropic,
+    "@elizaos/plugin-ollama": pluginOllama,
+    "@elizaos/plugin-elizacloud": pluginElizacloud,
+    "@elizaos/plugin-trust": pluginTrust,
+    "@elizaos/plugin-todo": pluginTodo,
+    "@elizaos/plugin-personality": pluginPersonality,
+    "@elizaos/plugin-experience": pluginExperience,
+};
+// NODE_PATH so dynamic plugin imports (e.g. @elizaos/plugin-agent-orchestrator) resolve.
+// WHY: When eliza is loaded from dist/ or by a test runner, Node's resolution does not
+// search repo root node_modules; import("@elizaos/plugin-*") then fails. We prepend
+// repo root node_modules only if not already in NODE_PATH (run-node.mjs may have set it)
+// to avoid duplicate entries; _initPaths() makes Node re-read NODE_PATH. See docs/plugin-resolution-and-node-path.md.
+// We walk up from this file to find node_modules — we do not assume a fixed depth
+// (e.g. two levels for src/runtime/ or dist/runtime/) so we still work if build
+// output structure changes (e.g. flat dist). First directory with node_modules wins.
+const _elizaDir = path.dirname(fileURLToPath(import.meta.url));
+let _dir = _elizaDir;
+let _rootModules = null;
+while (_dir !== path.dirname(_dir)) {
+    const candidate = path.join(_dir, "node_modules");
+    if (existsSync(candidate)) {
+        _rootModules = candidate;
+        break;
+    }
+    _dir = path.dirname(_dir);
+}
+if (_rootModules) {
+    const prev = process.env.NODE_PATH ?? "";
+    const entries = prev ? prev.split(path.delimiter) : [];
+    const normalizedRoot = path.resolve(_rootModules);
+    if (!entries.some((e) => path.resolve(e) === normalizedRoot)) {
+        process.env.NODE_PATH = prev
+            ? `${_rootModules}${path.delimiter}${prev}`
+            : _rootModules;
+        createRequire(import.meta.url)("node:module").Module._initPaths();
+    }
+}
+export function configureLocalEmbeddingPlugin(_plugin, config) {
+    const detectedPreset = detectEmbeddingPreset();
+    const embeddingConfig = config?.embedding;
+    const configuredModel = embeddingConfig?.model?.trim();
+    const configuredRepo = embeddingConfig?.modelRepo?.trim();
+    const configuredDimensions = typeof embeddingConfig?.dimensions === "number" &&
+        Number.isInteger(embeddingConfig.dimensions) &&
+        embeddingConfig.dimensions > 0
+        ? String(embeddingConfig.dimensions)
+        : undefined;
+    const configuredContextSize = typeof embeddingConfig?.contextSize === "number" &&
+        Number.isInteger(embeddingConfig.contextSize) &&
+        embeddingConfig.contextSize > 0
+        ? String(embeddingConfig.contextSize)
+        : undefined;
+    const configuredGpuLayers = (() => {
+        const value = embeddingConfig?.gpuLayers;
+        if (typeof value === "number" && Number.isInteger(value) && value >= 0) {
+            return String(value);
+        }
+        if (value === "auto" || value === "max") {
+            // plugin-local-embedding understands "auto" and treats it as runtime max
+            return "auto";
+        }
+        return undefined;
+    })();
+    const setEnvIfMissing = (key, value) => {
+        if (!value || process.env[key])
+            return;
+        process.env[key] = value;
+    };
+    const setEnvFromConfig = (key, value) => {
+        if (!value)
+            return;
+        process.env[key] = value;
+    };
+    // Keep plugin-local-embedding aligned with Milady's hardware-adaptive preset
+    // selection. Hard-coding the standard preset here forces slower first-run
+    // downloads on Windows and low-spec machines.
+    setEnvIfMissing("LOCAL_EMBEDDING_MODEL", configuredModel || detectedPreset.model);
+    if (configuredRepo) {
+        setEnvFromConfig("LOCAL_EMBEDDING_MODEL_REPO", configuredRepo);
+    }
+    else if (!configuredModel) {
+        setEnvIfMissing("LOCAL_EMBEDDING_MODEL_REPO", detectedPreset.modelRepo);
+    }
+    if (configuredDimensions) {
+        setEnvFromConfig("LOCAL_EMBEDDING_DIMENSIONS", configuredDimensions);
+    }
+    else if (!configuredModel) {
+        setEnvIfMissing("LOCAL_EMBEDDING_DIMENSIONS", String(detectedPreset.dimensions));
+    }
+    if (configuredContextSize) {
+        setEnvFromConfig("LOCAL_EMBEDDING_CONTEXT_SIZE", configuredContextSize);
+    }
+    else if (!configuredModel) {
+        setEnvIfMissing("LOCAL_EMBEDDING_CONTEXT_SIZE", String(detectedPreset.contextSize));
+    }
+    if (configuredGpuLayers) {
+        process.env.LOCAL_EMBEDDING_GPU_LAYERS = configuredGpuLayers;
+    }
+    else if (!process.env.LOCAL_EMBEDDING_GPU_LAYERS) {
+        process.env.LOCAL_EMBEDDING_GPU_LAYERS = String(detectedPreset.gpuLayers);
+    }
+    // Performance tuning
+    // Disable mmap on Metal to prevent "different text" errors with some models
+    setEnvIfMissing("LOCAL_EMBEDDING_USE_MMAP", detectedPreset.gpuLayers === "auto" ? "false" : "true");
+    // Set default models directory if not present
+    setEnvIfMissing("MODELS_DIR", path.join(os.homedir(), ".eliza", "models"));
+    // Normalize Google AI API key aliases — the elizaOS plugin and @google/genai
+    // SDK expect different env var names. Canonicalize to the long form that
+    // @elizaos/plugin-google-genai reads via runtime.getSetting(). Users can set
+    // any of: GEMINI_API_KEY, GOOGLE_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY.
+    setEnvIfMissing("GOOGLE_GENERATIVE_AI_API_KEY", process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY);
+    // Default Google model names — the Google GenAI plugin's getSetting() returns
+    // null (not undefined) for missing keys, but the plugin checks !== undefined
+    // causing String(null) = "null" to be sent as the model name. Set sensible
+    // defaults so the plugin always has valid model names.
+    setEnvIfMissing("GOOGLE_SMALL_MODEL", "gemini-3-flash-preview");
+    setEnvIfMissing("GOOGLE_LARGE_MODEL", "gemini-3.1-pro-preview");
+    logger.info(`[milady] Configured local embedding env: ${process.env.LOCAL_EMBEDDING_MODEL} (repo: ${process.env.LOCAL_EMBEDDING_MODEL_REPO ?? "auto"}, dims: ${process.env.LOCAL_EMBEDDING_DIMENSIONS ?? "auto"}, ctx: ${process.env.LOCAL_EMBEDDING_CONTEXT_SIZE ?? "auto"}, GPU: ${process.env.LOCAL_EMBEDDING_GPU_LAYERS}, mmap: ${process.env.LOCAL_EMBEDDING_USE_MMAP})`);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Extract a human-readable error message from an unknown thrown value. */
+function formatError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Best-effort runtime shutdown that also closes the database adapter.
+ *
+ * AgentRuntime.stop() only stops services. plugin-sql keeps a process-global
+ * PGlite manager, so restarts must close the adapter or the next runtime can
+ * silently reuse the same broken manager instance.
+ */
+export async function shutdownRuntime(runtime, context) {
+    if (!runtime)
+        return;
+    const adapter = runtime.adapter;
+    let firstError = null;
+    try {
+        await runtime.stop();
+    }
+    catch (err) {
+        firstError = err;
+        logger.warn(`[milady] ${context}: runtime stop failed: ${formatError(err)}`);
+    }
+    if (adapter && typeof adapter.close === "function") {
+        try {
+            await adapter.close();
+        }
+        catch (err) {
+            if (!firstError) {
+                firstError = err;
+            }
+            logger.warn(`[milady] ${context}: database adapter close failed: ${formatError(err)}`);
+        }
+    }
+    if (firstError) {
+        throw firstError;
+    }
+}
+/**
+ * Remove duplicate actions across an ordered list of plugins.
+ *
+ * When multiple plugins define an action with the same `name`, only the first
+ * occurrence is kept.  This prevents "Action already registered" warnings from
+ * elizaOS core.  The function mutates each plugin's `actions` array in-place.
+ */
+export function deduplicatePluginActions(plugins) {
+    const seen = new Set();
+    for (const plugin of plugins) {
+        if (plugin.actions) {
+            plugin.actions = plugin.actions.filter((action) => {
+                if (seen.has(action.name)) {
+                    logger.debug(`[milady] Skipping duplicate action "${action.name}" from plugin "${plugin.name}"`);
+                    return false;
+                }
+                seen.add(action.name);
+                return true;
+            });
+        }
+    }
+}
+function collectTrajectoryLoggerCandidates(runtimeLike) {
+    const candidates = [];
+    if (typeof runtimeLike.getServicesByType === "function") {
+        const byType = runtimeLike.getServicesByType("trajectory_logger");
+        if (Array.isArray(byType) && byType.length > 0) {
+            for (const service of byType) {
+                if (service)
+                    candidates.push(service);
+            }
+        }
+        else if (byType && !Array.isArray(byType)) {
+            candidates.push(byType);
+        }
+    }
+    if (typeof runtimeLike.getService === "function") {
+        const single = runtimeLike.getService("trajectory_logger");
+        if (single)
+            candidates.push(single);
+    }
+    return candidates;
+}
+async function waitForTrajectoryLoggerService(runtime, context, timeoutMs = 3000) {
+    const runtimeLike = runtime;
+    if (collectTrajectoryLoggerCandidates(runtimeLike).length > 0)
+        return;
+    const registrationStatus = typeof runtimeLike.getServiceRegistrationStatus === "function"
+        ? runtimeLike.getServiceRegistrationStatus("trajectory_logger")
+        : "unknown";
+    if (registrationStatus !== "pending" &&
+        registrationStatus !== "registering") {
+        return;
+    }
+    if (typeof runtimeLike.getServiceLoadPromise !== "function")
+        return;
+    let timedOut = false;
+    let timeoutHandle;
+    const timeoutPromise = new Promise((resolve) => {
+        timeoutHandle = setTimeout(() => {
+            timedOut = true;
+            resolve();
+        }, timeoutMs);
+    });
+    try {
+        await Promise.race([
+            runtimeLike.getServiceLoadPromise("trajectory_logger").then(() => { }),
+            timeoutPromise,
+        ]);
+        if (timedOut) {
+            logger.debug(`[milady] trajectory_logger still ${registrationStatus} after ${timeoutMs}ms (${context})`);
+        }
+    }
+    catch (err) {
+        logger.debug(`[milady] trajectory_logger registration failed while waiting (${context}): ${formatError(err)}`);
+    }
+    finally {
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
+    }
+}
+function ensureTrajectoryLoggerEnabled(runtime, context) {
+    const runtimeLike = runtime;
+    const candidates = collectTrajectoryLoggerCandidates(runtimeLike);
+    let trajectoryLogger = null;
+    let bestScore = -1;
+    for (const candidate of candidates) {
+        const candidateWithRuntime = candidate;
+        let score = 0;
+        if (typeof candidate.isEnabled === "function")
+            score += 2;
+        if (typeof candidateWithRuntime.setEnabled === "function")
+            score += 2;
+        if (candidateWithRuntime.initialized === true)
+            score += 3;
+        if (candidateWithRuntime.runtime?.adapter)
+            score += 3;
+        const enabled = typeof candidate.isEnabled === "function" ? candidate.isEnabled() : true;
+        if (enabled)
+            score += 1;
+        if (score > bestScore) {
+            trajectoryLogger = candidate;
+            bestScore = score;
+        }
+    }
+    if (!trajectoryLogger) {
+        logger.warn(`[milady] trajectory_logger service unavailable (${context}); trajectory capture disabled`);
+        return;
+    }
+    const isEnabled = typeof trajectoryLogger.isEnabled === "function"
+        ? trajectoryLogger.isEnabled()
+        : shouldEnableTrajectoryLoggingByDefault();
+    const shouldEnable = shouldEnableTrajectoryLoggingByDefault();
+    if (isEnabled !== shouldEnable &&
+        typeof trajectoryLogger.setEnabled === "function") {
+        trajectoryLogger.setEnabled(shouldEnable);
+        logger.info(`[milady] trajectory_logger defaulted ${shouldEnable ? "on" : "off"} (${context})`);
+    }
+}
+function patchTrajectoryLoggerAliasCompatibility(runtime) {
+    const runtimeLike = runtime;
+    const primary = collectTrajectoryLoggerCandidates(runtimeLike)[0];
+    if (!primary)
+        return;
+    if (typeof runtimeLike.getService !== "function")
+        return;
+    const aliases = [
+        runtimeLike.getService("logger5"),
+        runtimeLike.getService("logger"),
+    ];
+    for (const alias of aliases) {
+        if (!alias || typeof alias !== "object" || alias === primary)
+            continue;
+        const aliasOps = alias;
+        if (typeof aliasOps.startTrajectory !== "function") {
+            aliasOps.startTrajectory = async (...args) => {
+                if (typeof primary.startTrajectory === "function") {
+                    return primary.startTrajectory(...args);
+                }
+                return `step-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            };
+        }
+        if (typeof aliasOps.startStep !== "function") {
+            aliasOps.startStep = (trajectoryId) => {
+                if (typeof primary.startStep === "function") {
+                    return primary.startStep(trajectoryId);
+                }
+                return `step-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            };
+        }
+        if (typeof aliasOps.endTrajectory !== "function") {
+            aliasOps.endTrajectory = async (...args) => {
+                if (typeof primary.endTrajectory === "function") {
+                    await primary.endTrajectory(...args);
+                }
+            };
+        }
+    }
+}
+/**
+ * Cancel the onboarding flow and exit cleanly.
+ * Extracted to avoid duplicating the cancel+exit pattern 7 times.
+ */
+function cancelOnboarding() {
+    // _clack is guaranteed to be loaded by the time onboarding calls this.
+    _clack?.cancel("Maybe next time!");
+    process.exit(0);
+}
+// ---------------------------------------------------------------------------
+// Channel secret mapping
+// ---------------------------------------------------------------------------
+/**
+ * Maps Milady channel config fields to the environment variable names
+ * that elizaOS plugins expect.
+ *
+ * Milady stores channel credentials under `config.channels.<name>.<field>`,
+ * while elizaOS plugins read them from process.env.
+ */
+const RETAKE_CHANNEL_ACCESS_TOKEN_ENV = "RETAKE_AGENT_TOKEN";
+const CHANNEL_ENV_MAP = {
+    discord: {
+        token: "DISCORD_API_TOKEN",
+        botToken: "DISCORD_API_TOKEN",
+        applicationId: "DISCORD_APPLICATION_ID",
+    },
+    telegram: {
+        botToken: "TELEGRAM_BOT_TOKEN",
+    },
+    slack: {
+        botToken: "SLACK_BOT_TOKEN",
+        appToken: "SLACK_APP_TOKEN",
+        userToken: "SLACK_USER_TOKEN",
+    },
+    signal: {
+        authDir: "SIGNAL_AUTH_DIR",
+        account: "SIGNAL_ACCOUNT_NUMBER",
+        httpUrl: "SIGNAL_HTTP_URL",
+        cliPath: "SIGNAL_CLI_PATH",
+    },
+    msteams: {
+        appId: "MSTEAMS_APP_ID",
+        appPassword: "MSTEAMS_APP_PASSWORD",
+    },
+    mattermost: {
+        botToken: "MATTERMOST_BOT_TOKEN",
+        baseUrl: "MATTERMOST_BASE_URL",
+    },
+    googlechat: {
+        serviceAccountKey: "GOOGLE_CHAT_SERVICE_ACCOUNT_KEY",
+    },
+    blooio: {
+        apiKey: "BLOOIO_API_KEY",
+        fromNumber: "BLOOIO_PHONE_NUMBER",
+        webhookSecret: "BLOOIO_WEBHOOK_SECRET",
+        webhookUrl: "BLOOIO_WEBHOOK_URL",
+        webhookPort: "BLOOIO_WEBHOOK_PORT",
+    },
+    retake: {
+        accessToken: RETAKE_CHANNEL_ACCESS_TOKEN_ENV,
+        apiUrl: "RETAKE_API_URL",
+    },
+};
+// ---------------------------------------------------------------------------
+// Plugin resolution
+// ---------------------------------------------------------------------------
+export { CORE_PLUGINS, OPTIONAL_CORE_PLUGINS };
+/**
+ * Optional plugins that require native binaries or specific config.
+ * These are only loaded when explicitly enabled via features config,
+ * NOT by default — they crash if their prerequisites are missing.
+ */
+const _OPTIONAL_NATIVE_PLUGINS = [
+    "@elizaos/plugin-browser", // requires browser server binary
+    "@elizaos/plugin-vision", // requires @tensorflow/tfjs-node native addon
+    "@elizaos/plugin-computeruse", // requires platform-specific binaries
+];
+/** Maps Milady channel names to plugin package names. */
+export const CHANNEL_PLUGIN_MAP = {
+    discord: "@elizaos/plugin-discord",
+    telegram: "@elizaos/plugin-telegram",
+    slack: "@elizaos/plugin-slack",
+    twitter: "@elizaos/plugin-twitter",
+    // Internal connector built from src/plugins/whatsapp (not an npm package).
+    whatsapp: "@elizaos/plugin-whatsapp",
+    // Internal connector built from src/plugins/signal (not an npm package).
+    signal: "@elizaos/plugin-signal",
+    imessage: "@elizaos/plugin-imessage",
+    bluebubbles: "@elizaos/plugin-bluebubbles",
+    farcaster: "@elizaos/plugin-farcaster",
+    lens: "@elizaos/plugin-lens",
+    msteams: "@elizaos/plugin-msteams",
+    mattermost: "@elizaos/plugin-mattermost",
+    googlechat: "@elizaos/plugin-google-chat",
+    feishu: "@elizaos/plugin-feishu",
+    matrix: "@elizaos/plugin-matrix",
+    nostr: "@elizaos/plugin-nostr",
+    retake: "@elizaos/plugin-retake",
+    blooio: "@elizaos/plugin-blooio",
+    twitch: "@elizaos/plugin-twitch",
+};
+const PI_AI_PLUGIN_PACKAGE = "@elizaos/plugin-pi-ai";
+function isPiAiEnabledFromEnv(env = process.env) {
+    const raw = env.MILADY_USE_PI_AI;
+    if (!raw)
+        return false;
+    const value = String(raw).trim().toLowerCase();
+    return value === "1" || value === "true" || value === "yes";
+}
+/** Maps environment variable names to model-provider plugin packages. */
+const PROVIDER_PLUGIN_MAP = {
+    ANTHROPIC_API_KEY: "@elizaos/plugin-anthropic",
+    OPENAI_API_KEY: "@elizaos/plugin-openai",
+    GEMINI_API_KEY: "@elizaos/plugin-google-genai",
+    GOOGLE_API_KEY: "@elizaos/plugin-google-genai",
+    GOOGLE_GENERATIVE_AI_API_KEY: "@elizaos/plugin-google-genai",
+    GROQ_API_KEY: "@elizaos/plugin-groq",
+    XAI_API_KEY: "@elizaos/plugin-xai",
+    OPENROUTER_API_KEY: "@elizaos/plugin-openrouter",
+    AI_GATEWAY_API_KEY: "@elizaos/plugin-vercel-ai-gateway",
+    AIGATEWAY_API_KEY: "@elizaos/plugin-vercel-ai-gateway",
+    OLLAMA_BASE_URL: "@elizaos/plugin-ollama",
+    ZAI_API_KEY: "@homunculuslabs/plugin-zai",
+    MILADY_USE_PI_AI: PI_AI_PLUGIN_PACKAGE,
+    // ElizaCloud — loaded when API key is present OR cloud is explicitly enabled
+    ELIZAOS_CLOUD_API_KEY: "@elizaos/plugin-elizacloud",
+    ELIZAOS_CLOUD_ENABLED: "@elizaos/plugin-elizacloud",
+};
+/**
+ * Optional feature plugins keyed by feature name.
+ *
+ * Mappings here support short IDs in allow-lists and feature toggles.
+ * Keep this map in sync with optional plugin registration and tests.
+ */
+const OPTIONAL_PLUGIN_MAP = {
+    browser: "@elizaos/plugin-browser",
+    vision: "@elizaos/plugin-vision",
+    cron: "@elizaos/plugin-cron",
+    cua: "@elizaos/plugin-cua",
+    computeruse: "@elizaos/plugin-computeruse",
+    obsidian: "@elizaos/plugin-obsidian",
+    repoprompt: "@elizaos/plugin-repoprompt",
+    repoPrompt: "@elizaos/plugin-repoprompt",
+    "pi-ai": PI_AI_PLUGIN_PACKAGE,
+    piAi: PI_AI_PLUGIN_PACKAGE,
+    x402: "@elizaos/plugin-x402",
+    "coding-agent": "@elizaos/plugin-agent-orchestrator",
+    "streaming-base": "@elizaos/plugin-streaming-base",
+    "twitch-streaming": "@elizaos/plugin-twitch-streaming",
+    "youtube-streaming": "@elizaos/plugin-youtube-streaming",
+    "custom-rtmp": "@elizaos/plugin-custom-rtmp",
+    "pumpfun-streaming": "@elizaos/plugin-pumpfun-streaming",
+    "x-streaming": "@elizaos/plugin-x-streaming",
+};
+function looksLikePlugin(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const obj = value;
+    if (typeof obj.name !== "string" || typeof obj.description !== "string") {
+        return false;
+    }
+    // Providers also expose { name, description } so we require at least one
+    // plugin-like capability field before accepting named exports as plugins.
+    return (Array.isArray(obj.services) ||
+        Array.isArray(obj.providers) ||
+        Array.isArray(obj.actions) ||
+        Array.isArray(obj.routes) ||
+        Array.isArray(obj.events) ||
+        typeof obj.init === "function");
+}
+function looksLikePluginBasic(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const obj = value;
+    return typeof obj.name === "string" && typeof obj.description === "string";
+}
+export function findRuntimePluginExport(mod) {
+    // 1. Prefer explicit default export
+    if (looksLikePlugin(mod.default))
+        return mod.default;
+    // 2. Check for a named `plugin` export
+    if (looksLikePlugin(mod.plugin))
+        return mod.plugin;
+    // 3. Check if the module itself looks like a Plugin (CJS default pattern).
+    if (looksLikePlugin(mod))
+        return mod;
+    // 4. Scan named exports in a deterministic order.
+    // Prefer keys ending with "Plugin" before generic exports like providers.
+    const namedKeys = Object.keys(mod).filter((key) => key !== "default" && key !== "plugin");
+    const preferredKeys = namedKeys.filter((key) => /plugin$/i.test(key) || /^plugin/i.test(key));
+    const fallbackKeys = namedKeys.filter((key) => !preferredKeys.includes(key));
+    for (const key of [...preferredKeys, ...fallbackKeys]) {
+        const value = mod[key];
+        if (looksLikePlugin(value))
+            return value;
+    }
+    // 5. Final compatibility fallback: accept minimal plugin-like exports only
+    // when the export name itself indicates it's a plugin.
+    for (const key of preferredKeys) {
+        const value = mod[key];
+        if (looksLikePluginBasic(value))
+            return value;
+    }
+    // 6. Legacy CJS compatibility for modules that export only { name, description }.
+    if (looksLikePluginBasic(mod))
+        return mod;
+    if (looksLikePluginBasic(mod.default))
+        return mod.default;
+    if (looksLikePluginBasic(mod.plugin))
+        return mod.plugin;
+    return null;
+}
+/**
+ * Collect the set of plugin package names that should be loaded
+ * based on config, environment variables, and feature flags.
+ */
+/** @internal Exported for testing. */
+export function collectPluginNames(config) {
+    const shellPluginDisabled = config.features?.shellEnabled === false;
+    const cloudMode = config.cloud?.enabled;
+    const cloudHasApiKey = Boolean(config.cloud?.apiKey);
+    const cloudExplicitlyDisabled = cloudMode === false;
+    // Note: this is intentionally broader than the inference-path check in
+    // applyCloudConfigToEnv (which requires explicit `enabled: true`).  Here
+    // hasApiKey acts as an implicit enable signal so the cloud *plugin* gets
+    // loaded for RPC/services (auth, credits, billing) even when inference
+    // itself is handled by the user's own keys (BYOK).  The inference and
+    // persistence paths gate on `cloud.enabled === true` separately.
+    const cloudEffectivelyEnabled = cloudMode === true || (!cloudExplicitlyDisabled && cloudHasApiKey);
+    // When inferenceMode is "byok" or "local", OR services.inference is false,
+    // the user wants their own AI provider keys — cloud stays enabled for
+    // RPC/services but does NOT hijack model inference.
+    //
+    // If the user chose a subscription provider (e.g. anthropic-subscription)
+    // during onboarding and never explicitly set inferenceMode, treat that as
+    // "byok" — the subscription IS the user's inference choice.
+    const hasSubscriptionProvider = Boolean(config.agents?.defaults?.subscriptionProvider);
+    const explicitInferenceMode = config.cloud?.inferenceMode;
+    const cloudInferenceMode = explicitInferenceMode ?? (hasSubscriptionProvider ? "byok" : "cloud");
+    const cloudInferenceToggle = config.cloud?.services?.inference ?? true;
+    const cloudHandlesInference = cloudEffectivelyEnabled &&
+        cloudInferenceMode === "cloud" &&
+        cloudInferenceToggle !== false;
+    const configEnv = config.env;
+    const configPiAiFlag = (configEnv?.vars &&
+        typeof configEnv.vars === "object" &&
+        !Array.isArray(configEnv.vars)
+        ? configEnv.vars.MILADY_USE_PI_AI
+        : undefined) ?? configEnv?.MILADY_USE_PI_AI;
+    const piAiEnabled = isPiAiEnabledFromEnv(process.env) ||
+        (typeof configPiAiFlag === "string" &&
+            isPiAiEnabledFromEnv({
+                MILADY_USE_PI_AI: configPiAiFlag,
+            }));
+    const pluginEntries = config.plugins
+        ?.entries;
+    const isPluginExplicitlyDisabled = (pluginPackageName) => {
+        const marker = "/plugin-";
+        const markerIndex = pluginPackageName.lastIndexOf(marker);
+        const pluginId = markerIndex >= 0
+            ? pluginPackageName.slice(markerIndex + marker.length)
+            : pluginPackageName;
+        return pluginEntries?.[pluginId]?.enabled === false;
+    };
+    const providerPluginIdSet = new Set(Object.values(PROVIDER_PLUGIN_MAP).map((pluginPackageName) => {
+        const marker = "/plugin-";
+        const markerIndex = pluginPackageName.lastIndexOf(marker);
+        return markerIndex >= 0
+            ? pluginPackageName.slice(markerIndex + marker.length)
+            : pluginPackageName;
+    }));
+    const explicitProviderEntries = Object.entries(pluginEntries ?? {}).filter(([pluginId]) => providerPluginIdSet.has(pluginId));
+    const hasExplicitEnabledProvider = explicitProviderEntries.some(([, entry]) => entry?.enabled === true);
+    // Allow-list entries are additive (extra plugins), not exclusive.
+    const allowList = config.plugins?.allow;
+    const pluginsToLoad = new Set(CORE_PLUGINS);
+    // Allow list is additive — extra plugins on top of auto-detection,
+    // not an exclusive whitelist that blocks everything else.
+    if (allowList && allowList.length > 0) {
+        for (const item of allowList) {
+            const pluginName = CHANNEL_PLUGIN_MAP[item] ?? OPTIONAL_PLUGIN_MAP[item] ?? item;
+            pluginsToLoad.add(pluginName);
+        }
+    }
+    // Connector plugins — load when connector has config entries
+    // Prefer config.connectors, fall back to config.channels for backward compatibility
+    const connectors = config.connectors ?? config.channels ?? {};
+    for (const [channelName, channelConfig] of Object.entries(connectors)) {
+        if (channelConfig && typeof channelConfig === "object") {
+            const pluginName = CHANNEL_PLUGIN_MAP[channelName];
+            if (pluginName) {
+                pluginsToLoad.add(pluginName);
+            }
+        }
+    }
+    // Model-provider plugins — load when env key is present
+    for (const [envKey, pluginName] of Object.entries(PROVIDER_PLUGIN_MAP)) {
+        if (envKey === "MILADY_USE_PI_AI") {
+            // pi-ai enablement uses dedicated boolean parsing + precedence logic below.
+            continue;
+        }
+        if (cloudExplicitlyDisabled &&
+            (envKey === "ELIZAOS_CLOUD_API_KEY" || envKey === "ELIZAOS_CLOUD_ENABLED")) {
+            continue;
+        }
+        if (isPluginExplicitlyDisabled(pluginName)) {
+            continue;
+        }
+        if (hasExplicitEnabledProvider) {
+            const marker = "/plugin-";
+            const markerIndex = pluginName.lastIndexOf(marker);
+            const pluginId = markerIndex >= 0
+                ? pluginName.slice(markerIndex + marker.length)
+                : pluginName;
+            if (pluginEntries?.[pluginId]?.enabled !== true) {
+                continue;
+            }
+        }
+        if (process.env[envKey]?.trim()) {
+            pluginsToLoad.add(pluginName);
+        }
+    }
+    const shouldEnablePiAi = piAiEnabled && pluginEntries?.["pi-ai"]?.enabled !== false;
+    const applyProviderPrecedence = () => {
+        // Provider precedence:
+        // 1) ElizaCloud for inference (when enabled AND inferenceMode is "cloud")
+        // 2) pi-ai (when enabled and cloud inference is not active)
+        // 3) direct provider plugins (api-key/env based)
+        //
+        // When inferenceMode is "byok" or "local", cloud stays loaded for
+        // RPC/services but direct AI provider plugins are preserved so the
+        // user's own API keys (e.g. Anthropic) handle model inference.
+        if (cloudEffectivelyEnabled) {
+            pluginsToLoad.add("@elizaos/plugin-elizacloud");
+            if (cloudHandlesInference) {
+                // Cloud handles ALL model calls — remove direct AI provider plugins.
+                const directProviders = new Set(Object.values(PROVIDER_PLUGIN_MAP));
+                directProviders.delete("@elizaos/plugin-elizacloud");
+                for (const p of directProviders) {
+                    pluginsToLoad.delete(p);
+                }
+                return;
+            }
+            // inferenceMode is "byok" or "local" — keep direct provider plugins.
+            // Cloud plugin stays loaded for non-inference cloud services (RPC, media, etc.)
+            // Pi-ai takes priority over direct providers when cloud inference is disabled.
+            if (shouldEnablePiAi) {
+                pluginsToLoad.add(PI_AI_PLUGIN_PACKAGE);
+                // Remove direct provider plugins — pi-ai handles inference selection.
+                const directProviders = new Set(Object.values(PROVIDER_PLUGIN_MAP));
+                directProviders.delete(PI_AI_PLUGIN_PACKAGE);
+                directProviders.delete("@elizaos/plugin-elizacloud");
+                for (const p of directProviders) {
+                    pluginsToLoad.delete(p);
+                }
+            }
+            return;
+        }
+        if (shouldEnablePiAi) {
+            pluginsToLoad.add(PI_AI_PLUGIN_PACKAGE);
+            // When pi-ai is active, remove direct provider plugins + cloud plugin.
+            // pi-ai performs the upstream provider selection itself.
+            const directProviders = new Set(Object.values(PROVIDER_PLUGIN_MAP));
+            directProviders.delete(PI_AI_PLUGIN_PACKAGE);
+            for (const p of directProviders) {
+                pluginsToLoad.delete(p);
+            }
+            pluginsToLoad.delete("@elizaos/plugin-elizacloud");
+            return;
+        }
+        if (cloudExplicitlyDisabled) {
+            // Cloud was explicitly disabled — remove elizacloud even though it's
+            // in CORE_PLUGINS, so it cannot intercept model calls.
+            pluginsToLoad.delete("@elizaos/plugin-elizacloud");
+        }
+    };
+    // Apply once before additive plugin-entry/feature paths.
+    applyProviderPrecedence();
+    // Optional feature plugins from config.plugins.entries
+    const pluginsConfig = config.plugins;
+    if (pluginsConfig?.entries) {
+        for (const [key, entry] of Object.entries(pluginsConfig.entries)) {
+            if (entry &&
+                typeof entry === "object" &&
+                entry.enabled !== false) {
+                // Connector keys (telegram, discord, etc.) must use CHANNEL_PLUGIN_MAP
+                // so the correct variant loads.
+                const pluginName = CHANNEL_PLUGIN_MAP[key] ??
+                    OPTIONAL_PLUGIN_MAP[key] ??
+                    (key.includes("/") ? key : `@elizaos/plugin-${key}`);
+                pluginsToLoad.add(pluginName);
+            }
+        }
+    }
+    // Feature flags (config.features)
+    const features = config.features;
+    if (features && typeof features === "object") {
+        for (const [featureName, featureValue] of Object.entries(features)) {
+            const isEnabled = featureValue === true ||
+                (typeof featureValue === "object" &&
+                    featureValue !== null &&
+                    featureValue.enabled !== false);
+            if (isEnabled) {
+                const pluginName = OPTIONAL_PLUGIN_MAP[featureName];
+                if (pluginName) {
+                    pluginsToLoad.add(pluginName);
+                }
+            }
+        }
+    }
+    // x402 plugin — auto-load when config section enabled
+    if (config.x402?.enabled) {
+        pluginsToLoad.add("@elizaos/plugin-x402");
+    }
+    // Opinion plugin — auto-load when API key is present.
+    // NOT in PROVIDER_PLUGIN_MAP because it is a feature plugin, not a model
+    // provider, and would be incorrectly removed during provider precedence.
+    if (process.env.OPINION_API_KEY?.trim()) {
+        pluginsToLoad.add("@elizaos/plugin-opinion");
+    }
+    // User-installed plugins from config.plugins.installs
+    // These are plugins that were installed via the plugin-manager at runtime
+    // and tracked in milady.json so they persist across restarts.
+    const installs = config.plugins?.installs;
+    if (installs && typeof installs === "object") {
+        for (const [packageName, record] of Object.entries(installs)) {
+            if (record && typeof record === "object") {
+                pluginsToLoad.add(packageName);
+            }
+        }
+    }
+    // Re-apply provider precedence so later additive paths (entries, features,
+    // installs) cannot accidentally re-introduce suppressed providers.
+    applyProviderPrecedence();
+    // Enforce feature gating last so allow-list entries cannot bypass it.
+    if (shellPluginDisabled) {
+        pluginsToLoad.delete("@elizaos/plugin-shell");
+    }
+    if (isPluginExplicitlyDisabled("@elizaos/plugin-agent-orchestrator")) {
+        pluginsToLoad.delete("@elizaos/plugin-agent-orchestrator");
+    }
+    return pluginsToLoad;
+}
+// ---------------------------------------------------------------------------
+// Custom / drop-in plugin discovery
+// ---------------------------------------------------------------------------
+/** Subdirectory under the Milady state dir for drop-in custom plugins. */
+export const CUSTOM_PLUGINS_DIRNAME = "plugins/custom";
+/** Subdirectory under the Milady state dir for ejected plugins. */
+export const EJECTED_PLUGINS_DIRNAME = "plugins/ejected";
+/**
+ * Scan a directory for drop-in plugin packages. Each immediate subdirectory
+ * is treated as a plugin; name comes from package.json or the directory name.
+ */
+export async function scanDropInPlugins(dir) {
+    const records = {};
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return records;
+        }
+        throw err;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const pluginDir = path.join(dir, entry.name);
+        let pluginName = entry.name;
+        let version = "0.0.0";
+        try {
+            const raw = await fs.readFile(path.join(pluginDir, "package.json"), "utf-8");
+            const pkg = JSON.parse(raw);
+            if (typeof pkg.name === "string" && pkg.name.trim())
+                pluginName = pkg.name.trim();
+            if (typeof pkg.version === "string" && pkg.version.trim())
+                version = pkg.version.trim();
+        }
+        catch (err) {
+            if (err.code !== "ENOENT" &&
+                !(err instanceof SyntaxError)) {
+                throw err;
+            }
+        }
+        records[pluginName] = { source: "path", installPath: pluginDir, version };
+    }
+    return records;
+}
+/**
+ * Merge drop-in plugins into the load set. Filters out denied, core-colliding,
+ * and already-installed names. Mutates `pluginsToLoad` and `installRecords`.
+ */
+export function mergeDropInPlugins(params) {
+    const { dropInRecords, installRecords, corePluginNames, denyList, pluginsToLoad, } = params;
+    const accepted = [];
+    const skipped = [];
+    for (const [name, record] of Object.entries(dropInRecords)) {
+        if (denyList.has(name) || installRecords[name])
+            continue;
+        if (corePluginNames.has(name)) {
+            skipped.push(`[milady] Custom plugin "${name}" collides with core plugin — skipping`);
+            continue;
+        }
+        pluginsToLoad.add(name);
+        installRecords[name] = record;
+        accepted.push(name);
+    }
+    return { accepted, skipped };
+}
+const WORKSPACE_PLUGIN_OVERRIDES = new Set([
+    // "@elizaos/plugin-trajectory-logger",
+    // "@elizaos/plugin-plugin-manager",
+    // "@elizaos/plugin-media-generation",
+    "@elizaos/plugin-twitch-streaming",
+    "@elizaos/plugin-youtube-streaming",
+    "@elizaos/plugin-retake",
+]);
+function getWorkspacePluginOverridePath(pluginName) {
+    if (process.env.MILADY_DISABLE_WORKSPACE_PLUGIN_OVERRIDES === "1") {
+        return null;
+    }
+    if (!WORKSPACE_PLUGIN_OVERRIDES.has(pluginName)) {
+        return null;
+    }
+    const pluginSegmentMatch = pluginName.match(/^@[^/]+\/(plugin-[^/]+)$/);
+    const pluginSegment = pluginSegmentMatch?.[1];
+    if (!pluginSegment)
+        return null;
+    const thisDir = path.dirname(fileURLToPath(import.meta.url));
+    const miladyRoot = path.resolve(thisDir, "..", "..");
+    const workspaceRoot = path.resolve(miladyRoot, "..");
+    const candidates = [
+        path.join(miladyRoot, "plugins", pluginSegment, "typescript"),
+        path.join(workspaceRoot, "plugins", pluginSegment, "typescript"),
+        path.join(miladyRoot, "plugins", pluginSegment),
+        path.join(workspaceRoot, "plugins", pluginSegment),
+        path.join(miladyRoot, "packages", pluginSegment),
+        path.join(workspaceRoot, "packages", pluginSegment),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(path.join(candidate, "package.json"))) {
+            return candidate;
+        }
+    }
+    return null;
+}
+export function resolveMiladyPluginImportSpecifier(pluginName, runtimeModuleUrl = import.meta.url) {
+    if (!pluginName.startsWith("@elizaos/plugin-")) {
+        return pluginName;
+    }
+    const shortName = pluginName.replace("@elizaos/plugin-", "");
+    const thisDir = path.dirname(fileURLToPath(runtimeModuleUrl));
+    const distRoot = thisDir.endsWith("runtime")
+        ? path.resolve(thisDir, "..")
+        : thisDir;
+    const indexPath = path.resolve(distRoot, "plugins", shortName, "index.js");
+    return existsSync(indexPath) ? pathToFileURL(indexPath).href : pluginName;
+}
+export function shouldIgnoreMissingPluginExport(pluginName) {
+    return pluginName === "@elizaos/plugin-streaming-base";
+}
+// ---------------------------------------------------------------------------
+// Plugin resolution
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Browser server pre-flight
+// ---------------------------------------------------------------------------
+/**
+ * The `@elizaos/plugin-browser` npm package expects a `dist/server/` directory
+ * containing the compiled stagehand-server, but the npm publish doesn't include
+ * it.  The actual source/build lives in the workspace at
+ * `plugins/plugin-browser/stagehand-server/`.
+ *
+ * This function checks whether the server is reachable from the installed
+ * package and, if not, creates a symlink so the plugin's process-manager can
+ * find it.  Returns `true` when the server index.js is available (or was made
+ * available via symlink), `false` otherwise.
+ */
+/**
+ * Returns true if the given env var key is safe to forward to runtime.settings.
+ * Blocks blockchain private keys, secrets, passwords, tokens, credentials,
+ * mnemonics, and seed phrases while allowing API keys that plugins need.
+ */
+export function isEnvKeyAllowedForForwarding(key) {
+    const upper = key.toUpperCase();
+    // Block blockchain private keys
+    if (upper.includes("PRIVATE_KEY"))
+        return false;
+    if (upper.startsWith("EVM_") || upper.startsWith("SOLANA_"))
+        return false;
+    // Block secrets, passwords, tokens, and seed phrases (but not API_KEY which plugins need)
+    if (/(SECRET|PASSWORD|CREDENTIAL|MNEMONIC|SEED_PHRASE)/i.test(key))
+        return false;
+    if (/(ACCESS_TOKEN|REFRESH_TOKEN|SESSION_TOKEN|AUTH_TOKEN)$/i.test(key))
+        return false;
+    return true;
+}
+export function ensureBrowserServerLink() {
+    try {
+        // Resolve the plugin-browser package root via its package.json.
+        const req = createRequire(import.meta.url);
+        const pkgJsonPath = req.resolve("@elizaos/plugin-browser/package.json");
+        const pluginRoot = path.dirname(pkgJsonPath);
+        const serverDir = path.join(pluginRoot, "dist", "server");
+        const serverIndex = path.join(serverDir, "dist", "index");
+        // Already linked / available — nothing to do.
+        if (existsSync(serverIndex))
+            return true;
+        // Walk upward from this file to find the eliza-workspace root.
+        // Layout: <workspace>/milady/src/runtime/eliza.ts
+        const thisDir = path.dirname(fileURLToPath(import.meta.url));
+        const miladyRoot = path.resolve(thisDir, "..", "..");
+        const workspaceRoot = path.resolve(miladyRoot, "..");
+        const stagehandDir = path.join(workspaceRoot, "plugins", "plugin-browser", "stagehand-server");
+        const stagehandIndex = path.join(stagehandDir, "dist", "index");
+        if (!existsSync(stagehandIndex)) {
+            logger.info(`[milady] Browser server not found at ${stagehandDir} — ` +
+                `@elizaos/plugin-browser will not be loaded`);
+            return false;
+        }
+        // Create symlink: dist/server -> stagehand-server
+        symlinkSync(stagehandDir, serverDir, "dir");
+        logger.info(`[milady] Linked browser server: ${serverDir} -> ${stagehandDir}`);
+        return true;
+    }
+    catch (err) {
+        logger.debug(`[milady] Could not link browser server: ${formatError(err)}`);
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve Milady plugins from config and auto-enable logic.
+ * Returns an array of elizaOS Plugin instances ready for AgentRuntime.
+ *
+ * Handles three categories of plugins:
+ * 1. Built-in/npm plugins — imported by package name
+ * 2. User-installed plugins — from ~/.milady/plugins/installed/
+ * 3. Custom/drop-in plugins — from ~/.milady/plugins/custom/ and plugins.load.paths
+ *
+ * Each plugin is loaded inside an error boundary so a single failing plugin
+ * cannot crash the entire agent startup.
+ */
+/**
+ * Resolve a statically-imported @elizaos plugin by name.
+ * Returns the module if found in STATIC_ELIZA_PLUGINS, otherwise null.
+ */
+function resolveStaticElizaPlugin(pluginName) {
+    return STATIC_ELIZA_PLUGINS[pluginName] ?? null;
+}
+async function resolvePlugins(config, opts) {
+    const plugins = [];
+    const failedPlugins = [];
+    const repairedInstallRecords = new Set();
+    applyPluginAutoEnable({
+        config,
+        env: process.env,
+    });
+    const pluginsToLoad = collectPluginNames(config);
+    const corePluginSet = new Set(CORE_PLUGINS);
+    // Build a mutable map of install records so we can merge drop-in discoveries
+    const installRecords = {
+        ...(config.plugins?.installs ?? {}),
+    };
+    const denyList = new Set(config.plugins?.deny ?? []);
+    // ── Auto-discover ejected plugins ───────────────────────────────────────
+    // Ejected plugins override npm/core versions, so they are tracked
+    // separately and consulted first at import time.
+    const ejectedRecords = await scanDropInPlugins(path.join(resolveStateDir(), EJECTED_PLUGINS_DIRNAME));
+    const ejectedPluginNames = [];
+    for (const [name, _record] of Object.entries(ejectedRecords)) {
+        if (denyList.has(name))
+            continue;
+        pluginsToLoad.add(name);
+        ejectedPluginNames.push(name);
+    }
+    if (ejectedPluginNames.length > 0) {
+        logger.info(`[milady] Discovered ${ejectedPluginNames.length} ejected plugin(s): ${ejectedPluginNames.join(", ")}`);
+    }
+    // ── Auto-discover drop-in custom plugins ────────────────────────────────
+    // Scan well-known dir + any extra dirs from plugins.load.paths (first wins).
+    const scanDirs = [
+        path.join(resolveStateDir(), CUSTOM_PLUGINS_DIRNAME),
+        ...(config.plugins?.load?.paths ?? []).map(resolveUserPath),
+    ];
+    const dropInRecords = {};
+    for (const dir of scanDirs) {
+        for (const [name, record] of Object.entries(await scanDropInPlugins(dir))) {
+            if (!dropInRecords[name])
+                dropInRecords[name] = record;
+        }
+    }
+    // Merge into load set — deny list and core collisions are filtered out.
+    const { accepted: customPluginNames, skipped } = mergeDropInPlugins({
+        dropInRecords,
+        installRecords,
+        corePluginNames: corePluginSet,
+        denyList,
+        pluginsToLoad,
+    });
+    for (const msg of skipped)
+        logger.warn(msg);
+    if (customPluginNames.length > 0) {
+        logger.info(`[milady] Discovered ${customPluginNames.length} custom plugin(s): ${customPluginNames.join(", ")}`);
+    }
+    logger.info(`[milady] Resolving ${pluginsToLoad.size} plugins...`);
+    const loadStartTime = Date.now();
+    // Built once so we don't rebuild on every optional plugin failure.
+    const optionalPluginNames = new Set([
+        ...Object.values(OPTIONAL_PLUGIN_MAP),
+        ...Object.values(CHANNEL_PLUGIN_MAP),
+        ...OPTIONAL_CORE_PLUGINS,
+    ]);
+    // Load a single plugin - returns result or null on skip/failure
+    async function loadSinglePlugin(pluginName) {
+        const isCore = corePluginSet.has(pluginName);
+        const ejectedRecord = ejectedRecords[pluginName];
+        const installRecord = installRecords[pluginName];
+        const workspaceOverridePath = getWorkspacePluginOverridePath(pluginName);
+        // Pre-flight: ensure native dependencies are available for special plugins.
+        if (pluginName === "@elizaos/plugin-browser") {
+            if (!ensureBrowserServerLink()) {
+                failedPlugins.push({
+                    name: pluginName,
+                    error: "browser server binary not found",
+                });
+                logger.warn(`[milady] Skipping ${pluginName}: browser server not available. ` +
+                    `Build the stagehand-server or remove the plugin from plugins.allow.`);
+                return null;
+            }
+        }
+        try {
+            let mod;
+            if (ejectedRecord?.installPath) {
+                // Ejected plugin — always prefer local source over npm/core.
+                logger.debug(`[milady] Loading ejected plugin: ${pluginName} from ${ejectedRecord.installPath}`);
+                mod = await importFromPath(ejectedRecord.installPath, pluginName);
+            }
+            else if (workspaceOverridePath) {
+                logger.debug(`[milady] Loading workspace plugin override: ${pluginName} from ${workspaceOverridePath}`);
+                mod = await importFromPath(workspaceOverridePath, pluginName);
+            }
+            else if (installRecord?.installPath) {
+                // Prefer bundled/node_modules copies for official Eliza plugins.
+                const isOfficialElizaPlugin = pluginName.startsWith("@elizaos/plugin-");
+                if (isOfficialElizaPlugin) {
+                    try {
+                        const staticMod = await resolveStaticElizaPlugin(pluginName);
+                        mod = staticMod
+                            ? staticMod
+                            : (await import(pluginName));
+                        if (repairBrokenInstallRecord(config, pluginName)) {
+                            repairedInstallRecords.add(pluginName);
+                        }
+                    }
+                    catch (npmErr) {
+                        logger.warn(`[milady] Node_modules resolution failed for ${pluginName} (${formatError(npmErr)}). Trying installed path at ${installRecord.installPath}.`);
+                        mod = await importFromPath(installRecord.installPath, pluginName);
+                    }
+                }
+                else {
+                    // User-installed plugin — load from its install directory on disk.
+                    try {
+                        mod = await importFromPath(installRecord.installPath, pluginName);
+                    }
+                    catch (installErr) {
+                        logger.warn(`[milady] Installed plugin ${pluginName} failed at ${installRecord.installPath} (${formatError(installErr)}). Falling back to node_modules resolution.`);
+                        const staticMod = await resolveStaticElizaPlugin(pluginName);
+                        mod = staticMod
+                            ? staticMod
+                            : (await import(pluginName));
+                        if (repairBrokenInstallRecord(config, pluginName)) {
+                            repairedInstallRecords.add(pluginName);
+                        }
+                    }
+                }
+            }
+            else if (pluginName.startsWith("@elizaos/plugin-")) {
+                // Milady plugins can resolve either from bundled local wrappers
+                // under milady-dist/plugins/* or from packaged node_modules.
+                mod = (await import(resolveMiladyPluginImportSpecifier(pluginName)));
+            }
+            else {
+                // Built-in/npm plugin — try bundled static import first, then
+                // fall back to bare node_modules resolution.
+                const staticMod = pluginName.startsWith("@elizaos/plugin-")
+                    ? await resolveStaticElizaPlugin(pluginName)
+                    : null;
+                mod = staticMod
+                    ? staticMod
+                    : (await import(pluginName));
+            }
+            const pluginInstance = findRuntimePluginExport(mod);
+            if (pluginInstance) {
+                // Wrap the plugin's init function with an error boundary
+                const wrappedPlugin = wrapPluginWithErrorBoundary(pluginName, pluginInstance);
+                logger.debug(`[milady] ✓ Loaded plugin: ${pluginName}`);
+                return { name: pluginName, plugin: wrappedPlugin };
+            }
+            else {
+                if (shouldIgnoreMissingPluginExport(pluginName)) {
+                    logger.info(`[milady] Skipping helper package ${pluginName}: no Plugin export is expected`);
+                    return null;
+                }
+                const msg = `[milady] Plugin ${pluginName} did not export a valid Plugin object`;
+                failedPlugins.push({
+                    name: pluginName,
+                    error: "no valid Plugin export",
+                });
+                if (isCore) {
+                    logger.error(msg);
+                }
+                else {
+                    logger.warn(msg);
+                }
+                return null;
+            }
+        }
+        catch (err) {
+            const msg = formatError(err);
+            failedPlugins.push({ name: pluginName, error: msg });
+            if (isCore) {
+                logger.error(`[milady] Failed to load core plugin ${pluginName}: ${msg}`);
+            }
+            else {
+                if (optionalPluginNames.has(pluginName)) {
+                    logger.debug(`[milady] Optional plugin ${pluginName} not available: ${msg}`);
+                }
+                else {
+                    logger.info(`[milady] Could not load plugin ${pluginName}: ${msg}`);
+                }
+            }
+            return null;
+        }
+    }
+    // Load all plugins in parallel for faster startup
+    const pluginResults = await Promise.all(Array.from(pluginsToLoad).map(loadSinglePlugin));
+    // Collect successful loads
+    for (const result of pluginResults) {
+        if (result) {
+            plugins.push(result);
+        }
+    }
+    const loadDuration = Date.now() - loadStartTime;
+    logger.info(`[milady] Plugin loading took ${loadDuration}ms`);
+    // Summary logging
+    logger.info(`[milady] Plugin resolution complete: ${plugins.length}/${pluginsToLoad.size} loaded` +
+        (failedPlugins.length > 0 ? `, ${failedPlugins.length} failed` : ""));
+    if (failedPlugins.length > 0) {
+        logger.info(`[milady] Failed plugins: ${failedPlugins.map((f) => `${f.name} (${f.error})`).join(", ")}`);
+    }
+    // Diagnose version-skew issues when AI providers failed to load (#10)
+    const loadedNames = plugins.map((p) => p.name);
+    const diagnostic = diagnoseNoAIProvider(loadedNames, failedPlugins);
+    if (diagnostic) {
+        if (opts?.quiet) {
+            // In headless/GUI mode before onboarding, this is expected — the user
+            // will configure a provider through the onboarding wizard and restart.
+            logger.info(`[milady] ${diagnostic}`);
+        }
+        else {
+            logger.error(`[milady] ${diagnostic}`);
+        }
+    }
+    // Persist repaired install records so future startups do not keep trying
+    // to import from stale install directories.
+    if (repairedInstallRecords.size > 0) {
+        try {
+            saveMiladyConfig(config);
+            logger.info(`[milady] Repaired ${repairedInstallRecords.size} plugin install record(s): ${Array.from(repairedInstallRecords).join(", ")}`);
+        }
+        catch (err) {
+            logger.warn(`[milady] Failed to persist plugin install repairs: ${formatError(err)}`);
+        }
+    }
+    return plugins;
+}
+/** @internal Exported for testing. */
+export function repairBrokenInstallRecord(config, pluginName) {
+    const record = config.plugins?.installs?.[pluginName];
+    if (!record || typeof record.installPath !== "string")
+        return false;
+    if (!record.installPath.trim())
+        return false;
+    // Keep the plugin listed as installed but force node_modules resolution.
+    record.installPath = "";
+    record.source = "npm";
+    return true;
+}
+/**
+ * Wrap a plugin's `init` and `providers` with error boundaries so that a
+ * crash in any single plugin does not take down the entire agent or GUI.
+ *
+ * NOTE: Actions are NOT wrapped here because elizaOS's action dispatch
+ * already has its own error boundary.  Only `init` (startup) and
+ * `providers` (called every turn) need protection at this layer.
+ *
+ * The wrapper catches errors, logs them with the plugin name for easy
+ * debugging, and continues execution.
+ */
+function wrapPluginWithErrorBoundary(pluginName, plugin) {
+    const wrapped = { ...plugin };
+    // Wrap init if present
+    if (plugin.init) {
+        const originalInit = plugin.init;
+        wrapped.init = async (...args) => {
+            try {
+                return await originalInit(...args);
+            }
+            catch (err) {
+                logger.error(`[milady] Plugin "${pluginName}" crashed during init: ${formatError(err)}`);
+                // Surface the error but don't rethrow — the agent continues
+                // without this plugin's init having completed.
+                logger.warn(`[milady] Plugin "${pluginName}" will run in degraded mode (init failed)`);
+            }
+        };
+    }
+    // Wrap providers with error boundaries
+    if (plugin.providers && plugin.providers.length > 0) {
+        wrapped.providers = plugin.providers.map((provider) => ({
+            ...provider,
+            get: async (...args) => {
+                try {
+                    return await provider.get(...args);
+                }
+                catch (err) {
+                    const msg = formatError(err);
+                    logger.error(`[milady] Provider "${provider.name}" (plugin: ${pluginName}) crashed: ${msg}`);
+                    // Return an error marker so downstream consumers can detect
+                    // the failure rather than silently using empty data.
+                    return {
+                        text: `[Provider ${provider.name} error: ${msg}]`,
+                        data: { _providerError: true },
+                    };
+                }
+            },
+        }));
+    }
+    return wrapped;
+}
+/**
+ * Import a plugin module from its install directory on disk.
+ *
+ * Handles two install layouts:
+ *   1. npm layout:  <installPath>/node_modules/@scope/package/  (from `bun add`)
+ *   2. git layout:  <installPath>/ is the package root directly  (from `git clone`)
+ *
+ * @param installPath  Root directory of the installation (e.g. ~/.milady/plugins/installed/foo/).
+ * @param packageName  The npm package name (e.g. "@elizaos/plugin-discord") — used
+ *                     to navigate directly into node_modules when present.
+ */
+async function importFromPath(installPath, packageName) {
+    const absPath = path.resolve(installPath);
+    // npm/bun layout:  installPath/node_modules/@scope/name/
+    // git layout:      installPath/ is the package itself
+    const nmCandidate = path.join(absPath, "node_modules", ...packageName.split("/"));
+    let pkgRoot = absPath;
+    try {
+        if ((await fs.stat(nmCandidate)).isDirectory())
+            pkgRoot = nmCandidate;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+        /* git layout — pkgRoot stays as absPath */
+    }
+    // Resolve entry point from package.json
+    const entryPoint = await resolvePackageEntry(pkgRoot);
+    return (await import(pathToFileURL(entryPoint).href));
+}
+/** Read package.json exports/main to find the importable entry file. */
+/** @internal Exported for testing. */
+export async function resolvePackageEntry(pkgRoot) {
+    const fallback = path.join(pkgRoot, "dist", "index");
+    const fallbackCandidates = [
+        fallback,
+        path.join(pkgRoot, "index"),
+        path.join(pkgRoot, "index.mjs"),
+        path.join(pkgRoot, "index.ts"),
+        path.join(pkgRoot, "src", "index"),
+        path.join(pkgRoot, "src", "index.mjs"),
+        path.join(pkgRoot, "src", "index.ts"),
+    ];
+    const chooseExisting = (...paths) => {
+        const seen = new Set();
+        for (const p of paths) {
+            const resolved = path.resolve(p);
+            if (seen.has(resolved))
+                continue;
+            seen.add(resolved);
+            if (existsSync(resolved))
+                return resolved;
+        }
+        // Return first candidate even when missing so callers still get a useful path in errors.
+        return path.resolve(paths[0] ?? fallback);
+    };
+    try {
+        const raw = await fs.readFile(path.join(pkgRoot, "package.json"), "utf-8");
+        const pkg = JSON.parse(raw);
+        if (typeof pkg.exports === "object" && pkg.exports["."] !== undefined) {
+            const dot = pkg.exports["."];
+            const resolved = typeof dot === "string" ? dot : dot.import || dot.default;
+            if (typeof resolved === "string") {
+                return chooseExisting(path.resolve(pkgRoot, resolved), ...fallbackCandidates);
+            }
+        }
+        if (typeof pkg.exports === "string") {
+            return chooseExisting(path.resolve(pkgRoot, pkg.exports), ...fallbackCandidates);
+        }
+        if (pkg.main) {
+            return chooseExisting(path.resolve(pkgRoot, pkg.main), ...fallbackCandidates);
+        }
+        return chooseExisting(...fallbackCandidates);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return chooseExisting(...fallbackCandidates);
+        }
+        throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// Config → Character mapping
+// ---------------------------------------------------------------------------
+/**
+ * Propagate channel credentials from Milady config into process.env so
+ * that elizaOS plugins can find them.
+ */
+/** @internal Exported for testing. */
+export function applyConnectorSecretsToEnv(config) {
+    // Prefer config.connectors, fall back to config.channels for backward compatibility
+    const connectors = config.connectors ?? config.channels ?? {};
+    for (const [channelName, channelConfig] of Object.entries(connectors)) {
+        if (!channelConfig || typeof channelConfig !== "object")
+            continue;
+        const configObj = channelConfig;
+        // Discord plugins in the ecosystem use both DISCORD_API_TOKEN and
+        // DISCORD_BOT_TOKEN across versions. Mirror to both when available.
+        if (channelName === "discord") {
+            const tokenValue = (typeof configObj.token === "string" && configObj.token.trim()) ||
+                (typeof configObj.botToken === "string" && configObj.botToken.trim()) ||
+                "";
+            if (tokenValue) {
+                if (!process.env.DISCORD_API_TOKEN) {
+                    process.env.DISCORD_API_TOKEN = tokenValue;
+                }
+                if (!process.env.DISCORD_BOT_TOKEN) {
+                    process.env.DISCORD_BOT_TOKEN = tokenValue;
+                }
+            }
+        }
+        const envMap = CHANNEL_ENV_MAP[channelName];
+        if (!envMap)
+            continue;
+        for (const [configField, envKey] of Object.entries(envMap)) {
+            const value = configObj[configField];
+            if (typeof value === "string" && value.trim()) {
+                // Set if unset, or overwrite stale [REDACTED] placeholders
+                const existing = process.env[envKey];
+                if (!existing || existing.startsWith("[REDACT")) {
+                    process.env[envKey] = value;
+                }
+            }
+        }
+    }
+}
+/**
+ * Auto-resolve Discord Application ID from the bot token via Discord API.
+ * Called during async runtime init so that users only need a bot token.
+ */
+/** @internal Exported for testing. */
+export async function autoResolveDiscordAppId() {
+    if (process.env.DISCORD_APPLICATION_ID)
+        return;
+    const discordToken = process.env.DISCORD_API_TOKEN || process.env.DISCORD_BOT_TOKEN;
+    if (!discordToken)
+        return;
+    try {
+        const res = await fetch("https://discord.com/api/v10/oauth2/applications/@me", { headers: { Authorization: `Bot ${discordToken}` } });
+        if (!res.ok) {
+            logger.warn(`[milady] Failed to auto-resolve Discord Application ID: ${res.status}`);
+            return;
+        }
+        const app = (await res.json());
+        if (!app.id)
+            return;
+        process.env.DISCORD_APPLICATION_ID = app.id;
+        logger.info(`[milady] Auto-resolved Discord Application ID: ${app.id}`);
+    }
+    catch (err) {
+        logger.warn(`[milady] Could not auto-resolve Discord Application ID: ${err}`);
+    }
+}
+/**
+ * Propagate cloud config from Milady config into process.env so the
+ * ElizaCloud plugin can discover settings at startup.
+ */
+/** @internal Exported for testing. */
+export function applyCloudConfigToEnv(config) {
+    const cloud = config.cloud;
+    if (!cloud)
+        return;
+    const cloudMode = cloud.enabled;
+    // Require explicit cloud.enabled = true. Previously, undefined + apiKey
+    // would count as enabled, causing the model to revert to cloud on restart.
+    const effectivelyEnabled = cloudMode === true;
+    if (effectivelyEnabled) {
+        process.env.ELIZAOS_CLOUD_ENABLED = "true";
+        logger.info(`[milady] Cloud config: enabled=${cloud.enabled}, hasApiKey=${Boolean(cloud.apiKey)}, baseUrl=${cloud.baseUrl ?? "(default)"}`);
+    }
+    else {
+        delete process.env.ELIZAOS_CLOUD_ENABLED;
+        delete process.env.ELIZAOS_CLOUD_SMALL_MODEL;
+        delete process.env.ELIZAOS_CLOUD_LARGE_MODEL;
+    }
+    if (cloud.apiKey) {
+        process.env.ELIZAOS_CLOUD_API_KEY = cloud.apiKey;
+    }
+    else {
+        delete process.env.ELIZAOS_CLOUD_API_KEY;
+    }
+    if (cloud.baseUrl) {
+        process.env.ELIZAOS_CLOUD_BASE_URL = cloud.baseUrl;
+    }
+    else {
+        delete process.env.ELIZAOS_CLOUD_BASE_URL;
+    }
+    // Propagate model names so the cloud plugin picks them up.  Falls back to
+    // sensible defaults when cloud is enabled but no explicit selection exists.
+    // Skip when inferenceMode is "byok"/"local" or services.inference is off —
+    // user's own keys handle models.
+    // If the user chose a subscription provider, treat that as "byok" unless
+    // they explicitly set inferenceMode to "cloud".
+    const hasSubProvider = Boolean(config.agents?.defaults?.subscriptionProvider);
+    const explicitMode = cloud.inferenceMode;
+    const inferenceMode = explicitMode ?? (hasSubProvider ? "byok" : "cloud");
+    const inferenceToggle = cloud.services?.inference ?? true;
+    const cloudDoesInference = inferenceMode === "cloud" && inferenceToggle !== false;
+    const models = config.models;
+    if (effectivelyEnabled && cloudDoesInference) {
+        const small = models?.small || "openai/gpt-5-mini";
+        const large = models?.large || "anthropic/claude-sonnet-4.5";
+        process.env.SMALL_MODEL = small;
+        process.env.LARGE_MODEL = large;
+        process.env.ELIZAOS_CLOUD_SMALL_MODEL = small;
+        process.env.ELIZAOS_CLOUD_LARGE_MODEL = large;
+    }
+    else if (effectivelyEnabled) {
+        // Cloud enabled but inference handled by user's own keys — clean cloud
+        // model env vars so the cloud plugin doesn't intercept model calls.
+        delete process.env.ELIZAOS_CLOUD_SMALL_MODEL;
+        delete process.env.ELIZAOS_CLOUD_LARGE_MODEL;
+    }
+    // Propagate per-service disable flags so downstream code can check them
+    // without needing direct access to the MiladyConfig object.
+    const services = cloud.services;
+    if (services) {
+        if (services.tts === false) {
+            process.env.MILADY_CLOUD_TTS_DISABLED = "true";
+        }
+        else {
+            delete process.env.MILADY_CLOUD_TTS_DISABLED;
+        }
+        if (services.media === false) {
+            process.env.MILADY_CLOUD_MEDIA_DISABLED = "true";
+        }
+        else {
+            delete process.env.MILADY_CLOUD_MEDIA_DISABLED;
+        }
+        if (services.embeddings === false) {
+            process.env.MILADY_CLOUD_EMBEDDINGS_DISABLED = "true";
+        }
+        else {
+            delete process.env.MILADY_CLOUD_EMBEDDINGS_DISABLED;
+        }
+        if (services.rpc === false) {
+            process.env.MILADY_CLOUD_RPC_DISABLED = "true";
+        }
+        else {
+            delete process.env.MILADY_CLOUD_RPC_DISABLED;
+        }
+    }
+}
+/**
+ * Translate `config.database` into the environment variables that
+ * `@elizaos/plugin-sql` reads at init time (`POSTGRES_URL`, `PGLITE_DATA_DIR`).
+ *
+ * When the provider is "postgres", we build a connection string from the
+ * credentials (or use the explicit `connectionString` field) and set
+ * `POSTGRES_URL`. When the provider is "pglite" (the default), we set
+ * `PGLITE_DATA_DIR` to either the configured value or a stable workspace
+ * default (`~/.milady/workspace/.eliza/.elizadb`) and remove any stale
+ * `POSTGRES_URL`.
+ */
+/** @internal Exported for testing. */
+export function applyX402ConfigToEnv(config) {
+    const x402 = config.x402;
+    if (!x402?.enabled)
+        return;
+    if (!process.env.X402_ENABLED)
+        process.env.X402_ENABLED = "true";
+    if (x402.apiKey && !process.env.X402_API_KEY)
+        process.env.X402_API_KEY = x402.apiKey;
+    if (x402.baseUrl && !process.env.X402_BASE_URL)
+        process.env.X402_BASE_URL = x402.baseUrl;
+}
+function resolveDefaultPgliteDataDir(config) {
+    const workspaceDir = config.agents?.defaults?.workspace ?? resolveDefaultAgentWorkspaceDir();
+    return path.join(resolveUserPath(workspaceDir), ".eliza", ".elizadb");
+}
+/** @internal Exported for testing. */
+export function applyDatabaseConfigToEnv(config) {
+    const db = config.database;
+    const provider = db?.provider ?? "pglite";
+    if (provider === "postgres" && db?.postgres) {
+        const pg = db.postgres;
+        let url = pg.connectionString;
+        if (!url) {
+            const host = pg.host ?? "localhost";
+            const port = pg.port ?? 5432;
+            const user = encodeURIComponent(pg.user ?? "postgres");
+            const password = pg.password ? encodeURIComponent(pg.password) : "";
+            const database = pg.database ?? "postgres";
+            const auth = password ? `${user}:${password}` : user;
+            const sslParam = pg.ssl ? "?sslmode=require" : "";
+            url = `postgresql://${auth}@${host}:${port}/${database}${sslParam}`;
+        }
+        process.env.POSTGRES_URL = url;
+        // Clear PGLite dir so plugin-sql does not fall back to PGLite
+        delete process.env.PGLITE_DATA_DIR;
+    }
+    else {
+        // PGLite mode (default): ensure no leftover POSTGRES_URL and pin
+        // PGLite to the workspace path unless overridden by config/env.
+        delete process.env.POSTGRES_URL;
+        const configuredDataDir = db?.pglite?.dataDir?.trim();
+        if (configuredDataDir) {
+            process.env.PGLITE_DATA_DIR = resolveUserPath(configuredDataDir);
+            // Fall through to directory creation below instead of returning early
+        }
+        const envDataDir = process.env.PGLITE_DATA_DIR?.trim();
+        if (!envDataDir) {
+            process.env.PGLITE_DATA_DIR = resolveDefaultPgliteDataDir(config);
+        }
+        // Ensure the PGlite data directory exists before init so PGlite does
+        // not silently fall back to in-memory mode on first run.
+        const dataDir = process.env.PGLITE_DATA_DIR;
+        if (dataDir) {
+            const alreadyExisted = existsSync(dataDir);
+            mkdirSync(dataDir, { recursive: true });
+            logger.info(`[milady] PGlite data dir: ${dataDir} (${alreadyExisted ? "existed" : "created"})`);
+            // Remove stale postmaster.pid left by a crashed process. Without this,
+            // PGlite sees the lock and either fails or triggers the destructive
+            // resetPgliteDataDir path, wiping all conversation history.
+            cleanStalePglitePid(dataDir);
+        }
+    }
+}
+function reconcilePglitePidFile(dataDir) {
+    const pidPath = path.join(dataDir, "postmaster.pid");
+    if (!existsSync(pidPath))
+        return "missing";
+    try {
+        const content = readFileSync(pidPath, "utf-8");
+        const firstLine = content.split("\n")[0]?.trim();
+        const pid = parseInt(firstLine, 10);
+        if (Number.isNaN(pid) || pid <= 0) {
+            // Malformed pid file — remove it
+            unlinkSync(pidPath);
+            logger.warn(`[milady] Removed malformed PGlite postmaster.pid`);
+            return "cleared-malformed";
+        }
+        // Check if the process is still alive
+        try {
+            process.kill(pid, 0); // signal 0 = existence check, doesn't kill
+            // Process exists — pid file is NOT stale, leave it alone
+            logger.info(`[milady] PGlite postmaster.pid references running process ${pid} — leaving intact`);
+            return "active";
+        }
+        catch (killErr) {
+            const code = killErr.code;
+            if (code === "ESRCH") {
+                // Process doesn't exist — stale pid file, safe to remove
+                unlinkSync(pidPath);
+                logger.warn(`[milady] Removed stale PGlite postmaster.pid (process ${pid} not running)`);
+                return "cleared-stale";
+            }
+            else {
+                // EPERM or other — process may be alive under a different user,
+                // leave the file alone to avoid data directory corruption
+                logger.warn(`[milady] Cannot confirm postmaster.pid staleness (${code}) — leaving intact`);
+                return "active-unconfirmed";
+            }
+        }
+    }
+    catch (err) {
+        logger.warn(`[milady] Failed to check PGlite postmaster.pid: ${formatError(err)}`);
+        return "check-failed";
+    }
+}
+/**
+ * Check for and remove a stale postmaster.pid in the PGlite data directory.
+ * The pid file is stale if the recorded process is no longer running.
+ */
+export function cleanStalePglitePid(dataDir) {
+    void reconcilePglitePidFile(dataDir);
+}
+function collectErrorMessages(err) {
+    const messages = [];
+    const seen = new Set();
+    let current = err;
+    while (current && !seen.has(current)) {
+        seen.add(current);
+        if (typeof current === "string") {
+            messages.push(current);
+            break;
+        }
+        if (current instanceof Error) {
+            if (current.message)
+                messages.push(current.message);
+            if (current.stack)
+                messages.push(current.stack);
+            current = current.cause;
+            continue;
+        }
+        if (typeof current === "object") {
+            const maybeErr = current;
+            if (typeof maybeErr.message === "string" && maybeErr.message) {
+                messages.push(maybeErr.message);
+            }
+            if (maybeErr.cause !== undefined) {
+                current = maybeErr.cause;
+                continue;
+            }
+        }
+        break;
+    }
+    return messages;
+}
+function isPgliteLockError(err) {
+    const haystack = collectErrorMessages(err).join("\n").toLowerCase();
+    if (!haystack)
+        return false;
+    const hasPglite = haystack.includes("pglite");
+    const hasSqlite = haystack.includes("sqlite");
+    const hasLockSignal = haystack.includes("database is locked") ||
+        haystack.includes("lock file already exists");
+    return hasLockSignal && (hasPglite || hasSqlite);
+}
+/** @internal Exported for testing. */
+export function isRecoverablePgliteInitError(err) {
+    const haystack = collectErrorMessages(err).join("\n").toLowerCase();
+    if (!haystack)
+        return false;
+    const hasAbort = haystack.includes("aborted(). build with -sassertions");
+    const hasPglite = haystack.includes("pglite");
+    const hasSqlite = haystack.includes("sqlite");
+    const hasMigrationsSchema = haystack.includes("create schema if not exists migrations") ||
+        haystack.includes("failed query: create schema if not exists migrations");
+    const hasRecoverableStorageSignal = [
+        "database disk image is malformed",
+        "file is not a database",
+        "malformed database schema",
+        "database is locked",
+        "lock file already exists",
+        "wal file",
+        "checkpoint failed",
+        "checksum mismatch",
+        "corrupt",
+    ].some((needle) => haystack.includes(needle));
+    if (hasMigrationsSchema)
+        return true;
+    if (hasAbort && hasPglite)
+        return true;
+    if (hasRecoverableStorageSignal && (hasPglite || hasSqlite))
+        return true;
+    return false;
+}
+/** @internal Exported for testing. */
+export function getPgliteRecoveryAction(err, dataDir) {
+    if (!isRecoverablePgliteInitError(err))
+        return "none";
+    if (!isPgliteLockError(err))
+        return "reset-data-dir";
+    const pidStatus = reconcilePglitePidFile(dataDir);
+    if (pidStatus === "active" ||
+        pidStatus === "active-unconfirmed" ||
+        pidStatus === "check-failed") {
+        return "fail-active-lock";
+    }
+    if (pidStatus === "cleared-stale" || pidStatus === "cleared-malformed") {
+        return "retry-without-reset";
+    }
+    return "reset-data-dir";
+}
+function createActivePgliteLockError(dataDir, err) {
+    return new Error(`PGLite data dir is already in use at ${dataDir}. Close the other Milady process or set a different PGLITE_DATA_DIR before retrying.`, { cause: err });
+}
+function resolveActivePgliteDataDir(config) {
+    const provider = config.database?.provider ?? "pglite";
+    if (provider === "postgres")
+        return null;
+    const configured = process.env.PGLITE_DATA_DIR?.trim();
+    const dataDir = configured || resolveDefaultPgliteDataDir(config);
+    return resolveUserPath(dataDir);
+}
+async function resetPgliteDataDir(dataDir) {
+    const normalized = path.resolve(dataDir);
+    const root = path.parse(normalized).root;
+    if (normalized === root) {
+        throw new Error(`Refusing to reset unsafe PGLite path: ${normalized}`);
+    }
+    const stamp = new Date()
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(/\..*$/, "")
+        .replace("T", "-");
+    const backupDir = `${normalized}.corrupt-${stamp}`;
+    if (existsSync(normalized)) {
+        try {
+            await fs.rename(normalized, backupDir);
+            logger.warn(`[milady] Backed up existing PGLite data dir to ${backupDir}`);
+        }
+        catch (err) {
+            logger.warn(`[milady] Failed to back up PGLite data dir (${formatError(err)}); deleting ${normalized} instead`);
+            await fs.rm(normalized, { recursive: true, force: true });
+        }
+    }
+    await fs.mkdir(normalized, { recursive: true });
+}
+async function initializeDatabaseAdapter(runtime, config) {
+    if (!runtime.adapter || (await runtime.adapter.isReady()))
+        return;
+    try {
+        await runtime.adapter.init();
+        logger.info("[milady] Database adapter initialized early (before plugin inits)");
+    }
+    catch (err) {
+        const pgliteDataDir = resolveActivePgliteDataDir(config);
+        if (!pgliteDataDir) {
+            throw err;
+        }
+        const recoveryAction = getPgliteRecoveryAction(err, pgliteDataDir);
+        if (recoveryAction === "none") {
+            throw err;
+        }
+        if (recoveryAction === "fail-active-lock") {
+            throw createActivePgliteLockError(pgliteDataDir, err);
+        }
+        if (recoveryAction === "retry-without-reset") {
+            logger.warn(`[milady] PGLite init failed (${formatError(err)}). Cleared a stale PGLite lock in ${pgliteDataDir} and retrying without resetting data.`);
+        }
+        else {
+            logger.warn(`[milady] PGLite init failed (${formatError(err)}). Resetting local DB at ${pgliteDataDir} and retrying once.`);
+            await resetPgliteDataDir(pgliteDataDir);
+            process.env.PGLITE_DATA_DIR = pgliteDataDir;
+        }
+        await runtime.adapter.init();
+        logger.info(recoveryAction === "retry-without-reset"
+            ? "[milady] Database adapter recovered after clearing a stale PGLite lock"
+            : "[milady] Database adapter recovered after resetting PGLite data");
+    }
+    // Health check: verify PGlite data directory has files after init.
+    // Runs on BOTH the happy path and the recovery path.
+    await verifyPgliteDataDir(config);
+}
+/**
+ * Verify PGlite data directory contains files after init.
+ * Warns if the directory is empty (suggests ephemeral/in-memory fallback).
+ */
+async function verifyPgliteDataDir(config) {
+    const pgliteDataDir = resolveActivePgliteDataDir(config);
+    if (!pgliteDataDir || !existsSync(pgliteDataDir))
+        return;
+    try {
+        const files = await fs.readdir(pgliteDataDir);
+        logger.info(`[milady] PGlite health check: ${files.length} file(s) in ${pgliteDataDir}`);
+        if (files.length === 0) {
+            logger.warn(`[milady] PGlite data directory is empty after init — data may not persist across restarts`);
+        }
+    }
+    catch (err) {
+        logger.warn(`[milady] PGlite health check failed: ${formatError(err)}`);
+    }
+}
+function isPluginAlreadyRegisteredError(err) {
+    return formatError(err).toLowerCase().includes("already registered");
+}
+function getConstraintName(error) {
+    if (!error || typeof error !== "object")
+        return null;
+    const err = error;
+    if (typeof err.constraint === "string" && err.constraint.length > 0) {
+        return err.constraint;
+    }
+    if (err.cause)
+        return getConstraintName(err.cause);
+    return null;
+}
+function isComponentsWorldFkViolation(error) {
+    return getConstraintName(error) === "components_world_id_worlds_id_fk";
+}
+function toErrorDetails(error, depth = 0) {
+    if (!error || typeof error !== "object") {
+        return { value: String(error) };
+    }
+    const err = error;
+    const details = {};
+    for (const key of [
+        "name",
+        "message",
+        "code",
+        "detail",
+        "hint",
+        "constraint",
+        "schema",
+        "table",
+        "column",
+        "where",
+    ]) {
+        const value = err[key];
+        if (typeof value === "string" || typeof value === "number") {
+            details[key] = value;
+        }
+    }
+    if (depth < 2 && err.cause) {
+        details.cause = toErrorDetails(err.cause, depth + 1);
+    }
+    return details;
+}
+async function withEntityCreateMutex(runtimeWithBindings, fn) {
+    const previous = runtimeWithBindings.__miladyEntityCreateMutex;
+    let release = () => { };
+    runtimeWithBindings.__miladyEntityCreateMutex = new Promise((resolve) => {
+        release = resolve;
+    });
+    if (previous) {
+        await previous;
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+    }
+}
+function summarizeComponentWrite(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        return { inputType: typeof input };
+    }
+    const record = input;
+    const data = record.data;
+    const dataKeys = data && typeof data === "object" && !Array.isArray(data)
+        ? Object.keys(data).slice(0, 20)
+        : [];
+    return {
+        id: record.id,
+        type: record.type,
+        entityId: record.entityId ?? record.entity_id,
+        sourceEntityId: record.sourceEntityId ?? record.source_entity_id,
+        roomId: record.roomId ?? record.room_id,
+        worldId: record.worldId ?? record.world_id,
+        agentId: record.agentId ?? record.agent_id,
+        dataKeys,
+    };
+}
+export function installRuntimeMethodBindings(runtime) {
+    const runtimeWithBindings = runtime;
+    if (runtimeWithBindings.__miladyMethodBindingsInstalled) {
+        return;
+    }
+    // Some plugin builds store this method and invoke it later without the
+    // runtime receiver, which breaks private-field access in AgentRuntime.
+    runtime.getConversationLength = runtime.getConversationLength.bind(runtime);
+    // Wrap getSetting() to fall back to process.env for known keys when the
+    // core returns null. elizaOS core returns null for missing keys, but some
+    // plugins (e.g. @elizaos/plugin-google-genai) check `!== undefined` and
+    // convert null to the string "null", causing API calls like `models/null`.
+    // Scoped to an allowlist to avoid leaking arbitrary env vars to plugins.
+    const GETSETTING_ENV_ALLOWLIST = new Set([
+        // Model provider API keys
+        "ANTHROPIC_API_KEY",
+        "OPENAI_API_KEY",
+        "GOOGLE_GENERATIVE_AI_API_KEY",
+        "GOOGLE_API_KEY",
+        "GEMINI_API_KEY",
+        "GROQ_API_KEY",
+        "XAI_API_KEY",
+        "DEEPSEEK_API_KEY",
+        "OPENROUTER_API_KEY",
+        // Google model defaults
+        "GOOGLE_SMALL_MODEL",
+        "GOOGLE_LARGE_MODEL",
+        // GitHub
+        "GITHUB_TOKEN",
+        "GITHUB_OAUTH_CLIENT_ID",
+        // Coding agent model preferences
+        "PARALLAX_CLAUDE_MODEL_POWERFUL",
+        "PARALLAX_CLAUDE_MODEL_FAST",
+        "PARALLAX_GEMINI_MODEL_POWERFUL",
+        "PARALLAX_GEMINI_MODEL_FAST",
+        "PARALLAX_CODEX_MODEL_POWERFUL",
+        "PARALLAX_CODEX_MODEL_FAST",
+        "PARALLAX_AIDER_PROVIDER",
+        "PARALLAX_AIDER_MODEL_POWERFUL",
+        "PARALLAX_AIDER_MODEL_FAST",
+        // Custom credential forwarding — intentionally broad: users configure which env vars
+        // to forward to coding agents via this comma-separated key list (e.g. MCP server tokens).
+        "CUSTOM_CREDENTIAL_KEYS",
+    ]);
+    const originalGetSetting = runtime.getSetting.bind(runtime);
+    runtime.getSetting = (key) => {
+        const result = originalGetSetting(key);
+        if (result !== null && result !== undefined)
+            return result;
+        if (GETSETTING_ENV_ALLOWLIST.has(key)) {
+            const envVal = process.env[key];
+            if (envVal !== undefined && envVal.trim() !== "")
+                return envVal;
+        }
+        return result;
+    };
+    // Add targeted diagnostics around component writes. Rolodex reflection and
+    // relationship extraction rely heavily on components; when inserts fail,
+    // upstream logs often hide the concrete DB cause/constraint.
+    if (!runtimeWithBindings.__miladyComponentWriteDiagnosticsInstalled) {
+        const runtimeWithComponentWrites = runtime;
+        if (typeof runtimeWithComponentWrites.createComponent === "function") {
+            const originalCreate = runtimeWithComponentWrites.createComponent.bind(runtime);
+            runtimeWithComponentWrites.createComponent = async (input) => {
+                try {
+                    return await originalCreate(input);
+                }
+                catch (error) {
+                    // Recovery path: some evaluators (e.g. relationship extraction)
+                    // compute a synthetic worldId that may not exist yet. If we hit the
+                    // components->worlds FK, retry once with the room's canonical worldId.
+                    if (isComponentsWorldFkViolation(error) &&
+                        input.roomId &&
+                        typeof runtime.getRoom === "function") {
+                        try {
+                            const room = await runtime.getRoom(input.roomId);
+                            if (room?.worldId && room.worldId !== input.worldId) {
+                                logger.warn(`[milady] createComponent retry with room worldId (${room.worldId}) after FK violation`);
+                                const recovered = {
+                                    ...input,
+                                    worldId: room.worldId,
+                                };
+                                return await originalCreate(recovered);
+                            }
+                        }
+                        catch (retryLookupError) {
+                            logger.warn(`[milady] createComponent recovery lookup failed: ${formatError(retryLookupError)}`);
+                        }
+                    }
+                    const component = summarizeComponentWrite(input);
+                    logger.error(`[milady] createComponent failed: ${formatError(error)} | component=${JSON.stringify(component)}`);
+                    logger.error(`[milady] createComponent db details: ${JSON.stringify(toErrorDetails(error))}`);
+                    throw error;
+                }
+            };
+        }
+        if (typeof runtimeWithComponentWrites.updateComponent === "function") {
+            const originalUpdate = runtimeWithComponentWrites.updateComponent.bind(runtime);
+            runtimeWithComponentWrites.updateComponent = async (input) => {
+                try {
+                    return await originalUpdate(input);
+                }
+                catch (error) {
+                    const component = summarizeComponentWrite(input);
+                    logger.error(`[milady] updateComponent failed: ${formatError(error)} | component=${JSON.stringify(component)}`);
+                    logger.error(`[milady] updateComponent db details: ${JSON.stringify(toErrorDetails(error))}`);
+                    throw error;
+                }
+            };
+        }
+        runtimeWithBindings.__miladyComponentWriteDiagnosticsInstalled = true;
+    }
+    // Proactive guard for plugin-sql entity creation. Some evaluators may attempt
+    // to create the same entity in rapid succession; plugin-sql's batch insert is
+    // non-idempotent and can fail entire writes on duplicate/conflicting rows.
+    if (!runtimeWithBindings.__miladyEntityWriteDiagnosticsInstalled) {
+        const runtimeWithEntityWrites = runtime;
+        if (typeof runtimeWithEntityWrites.createEntities === "function") {
+            const originalCreateEntities = runtimeWithEntityWrites.createEntities.bind(runtime);
+            runtimeWithEntityWrites.createEntities = async (entities) => {
+                return withEntityCreateMutex(runtimeWithBindings, async () => {
+                    const uniqueById = new Map();
+                    for (const entity of entities) {
+                        if (entity?.id)
+                            uniqueById.set(entity.id, entity);
+                    }
+                    const deduped = Array.from(uniqueById.values());
+                    if (deduped.length === 0)
+                        return true;
+                    let missing = deduped;
+                    if (typeof runtimeWithEntityWrites.getEntitiesByIds === "function") {
+                        try {
+                            const existing = (await runtimeWithEntityWrites.getEntitiesByIds(deduped.map((e) => e.id))) ?? [];
+                            const existingIds = new Set();
+                            for (const entity of existing) {
+                                if (entity?.id)
+                                    existingIds.add(entity.id);
+                            }
+                            missing = deduped.filter((entity) => !existingIds.has(entity.id));
+                        }
+                        catch (err) {
+                            logger.warn(`[milady] createEntities precheck failed; proceeding with guarded insert: ${formatError(err)}`);
+                        }
+                    }
+                    if (missing.length === 0)
+                        return true;
+                    const ok = await originalCreateEntities(missing);
+                    if (ok)
+                        return true;
+                    if (typeof runtimeWithEntityWrites.ensureEntityExists === "function") {
+                        let allRecovered = true;
+                        for (const entity of missing) {
+                            try {
+                                const ensured = await runtimeWithEntityWrites.ensureEntityExists(entity);
+                                allRecovered = allRecovered && ensured;
+                            }
+                            catch (err) {
+                                allRecovered = false;
+                                logger.warn(`[milady] ensureEntityExists recovery failed for ${String(entity.id)}: ${formatError(err)}`);
+                            }
+                        }
+                        if (allRecovered)
+                            return true;
+                    }
+                    logger.warn(`[milady] createEntities unresolved after guarded retries (requested=${entities.length}, deduped=${deduped.length}, missing=${missing.length})`);
+                    return false;
+                });
+            };
+        }
+        runtimeWithBindings.__miladyEntityWriteDiagnosticsInstalled = true;
+    }
+    runtimeWithBindings.__miladyMethodBindingsInstalled = true;
+}
+function installActionAliases(runtime) {
+    const runtimeWithAliases = runtime;
+    if (runtimeWithAliases.__miladyActionAliasesInstalled) {
+        return;
+    }
+    const actions = Array.isArray(runtimeWithAliases.actions)
+        ? runtimeWithAliases.actions
+        : [];
+    // Keep compaction automatic-only; do not allow manual COMPACT_SESSION invokes.
+    const compactSessionIndex = actions.findIndex((action) => action?.name?.toUpperCase() === "COMPACT_SESSION");
+    if (compactSessionIndex !== -1) {
+        actions.splice(compactSessionIndex, 1);
+        logger.info("[milady] Disabled manual COMPACT_SESSION action; auto-compaction remains enabled");
+    }
+    // Compatibility alias: older prompts/docs still reference CODE_TASK,
+    // while plugin-agent-orchestrator exposes CREATE_TASK.
+    const createTaskAction = actions.find((action) => action?.name?.toUpperCase() === "CREATE_TASK");
+    if (createTaskAction) {
+        const similes = Array.isArray(createTaskAction.similes)
+            ? createTaskAction.similes
+            : [];
+        const hasCodeTaskAlias = similes.some((simile) => simile.toUpperCase() === "CODE_TASK");
+        if (!hasCodeTaskAlias) {
+            createTaskAction.similes = [...similes, "CODE_TASK"];
+            logger.info("[milady] Added action alias CODE_TASK -> CREATE_TASK for agent-orchestrator");
+        }
+    }
+    runtimeWithAliases.__miladyActionAliasesInstalled = true;
+}
+async function registerSqlPluginWithRecovery(runtime, sqlPlugin, config) {
+    let registerError = null;
+    try {
+        await runtime.registerPlugin(sqlPlugin.plugin);
+    }
+    catch (err) {
+        registerError = err;
+    }
+    if (registerError) {
+        const pgliteDataDir = resolveActivePgliteDataDir(config);
+        if (!pgliteDataDir) {
+            throw registerError;
+        }
+        const recoveryAction = getPgliteRecoveryAction(registerError, pgliteDataDir);
+        if (recoveryAction === "none") {
+            throw registerError;
+        }
+        if (recoveryAction === "fail-active-lock") {
+            throw createActivePgliteLockError(pgliteDataDir, registerError);
+        }
+        if (recoveryAction === "retry-without-reset") {
+            logger.warn(`[milady] SQL plugin registration failed (${formatError(registerError)}). Cleared a stale PGLite lock in ${pgliteDataDir} and retrying without resetting data.`);
+        }
+        else {
+            logger.warn(`[milady] SQL plugin registration failed (${formatError(registerError)}). Resetting local PGLite DB at ${pgliteDataDir} and retrying once.`);
+            await resetPgliteDataDir(pgliteDataDir);
+            process.env.PGLITE_DATA_DIR = pgliteDataDir;
+        }
+        try {
+            await runtime.registerPlugin(sqlPlugin.plugin);
+        }
+        catch (retryErr) {
+            if (!isPluginAlreadyRegisteredError(retryErr)) {
+                throw retryErr;
+            }
+        }
+    }
+    await initializeDatabaseAdapter(runtime, config);
+}
+/**
+ * Build an elizaOS Character from the Milady config.
+ *
+ * Resolves the agent name from `config.agents.list` (first entry) or
+ * `config.ui.assistant.name`, falling back to "Milady".  Character
+ * personality data (bio, system prompt, style, etc.) is stored in the
+ * database — not the config file — so we only provide sensible defaults
+ * here for the initial bootstrap.
+ */
+/** @internal Exported for testing. */
+export function buildCharacterFromConfig(config) {
+    // Resolve name: agents list → ui assistant → "Milady"
+    const agentEntry = config.agents?.list?.[0];
+    const name = agentEntry?.name ?? config.ui?.assistant?.name ?? "Milady";
+    const bundledPreset = (() => {
+        const presetByName = {
+            Reimu: "uwu~",
+            Marisa: "hell yeah",
+            Yukari: "lol k",
+            Sakuya: "Noted.",
+            Koishi: "hehe~",
+            Remilia: "...",
+            Reisen: "locked in",
+        };
+        const presetCatchphrase = presetByName[name.trim()];
+        if (!presetCatchphrase)
+            return undefined;
+        return STYLE_PRESETS.find((preset) => preset.catchphrase === presetCatchphrase);
+    })();
+    // Read personality fields from the agent config entry (set during
+    // onboarding from the chosen style preset).  Fall back to generic
+    // defaults when the preset data is not present (e.g. pre-onboarding
+    // bootstrap or configs created before this change). For built-in default
+    // characters, fall back to the bundled preset so legacy name-only configs
+    // still retain their default posts/messages.
+    const bio = agentEntry?.bio ??
+        bundledPreset?.bio ?? [
+        "{{name}} is an AI assistant powered by Milady and elizaOS.",
+    ];
+    const systemPrompt = agentEntry?.system ??
+        bundledPreset?.system ??
+        "You are {{name}}, an autonomous AI agent powered by elizaOS.";
+    const style = agentEntry?.style ?? bundledPreset?.style;
+    const adjectives = agentEntry?.adjectives ?? bundledPreset?.adjectives;
+    const postExamples = agentEntry?.postExamples ?? bundledPreset?.postExamples;
+    const messageExamples = agentEntry?.messageExamples ?? bundledPreset?.messageExamples;
+    // Collect secrets from process.env (API keys the plugins need)
+    const secretKeys = [
+        "ANTHROPIC_API_KEY",
+        "OPENAI_API_KEY",
+        "GEMINI_API_KEY",
+        "GOOGLE_API_KEY",
+        "GOOGLE_GENERATIVE_AI_API_KEY",
+        "GROQ_API_KEY",
+        "XAI_API_KEY",
+        "OPENROUTER_API_KEY",
+        "AI_GATEWAY_API_KEY",
+        "AIGATEWAY_API_KEY",
+        "AI_GATEWAY_BASE_URL",
+        "AI_GATEWAY_SMALL_MODEL",
+        "AI_GATEWAY_LARGE_MODEL",
+        "AI_GATEWAY_EMBEDDING_MODEL",
+        "AI_GATEWAY_EMBEDDING_DIMENSIONS",
+        "AI_GATEWAY_IMAGE_MODEL",
+        "AI_GATEWAY_TIMEOUT_MS",
+        "OLLAMA_BASE_URL",
+        "DISCORD_API_TOKEN",
+        "DISCORD_APPLICATION_ID",
+        "DISCORD_BOT_TOKEN",
+        "TELEGRAM_BOT_TOKEN",
+        "SLACK_BOT_TOKEN",
+        "SLACK_APP_TOKEN",
+        "SLACK_USER_TOKEN",
+        "SIGNAL_ACCOUNT_NUMBER",
+        "MSTEAMS_APP_ID",
+        "MSTEAMS_APP_PASSWORD",
+        "MATTERMOST_BOT_TOKEN",
+        "MATTERMOST_BASE_URL",
+        // ElizaCloud secrets
+        "ELIZAOS_CLOUD_API_KEY",
+        "ELIZAOS_CLOUD_BASE_URL",
+        "ELIZAOS_CLOUD_ENABLED",
+        // Wallet / blockchain secrets
+        "EVM_PRIVATE_KEY",
+        "SOLANA_PRIVATE_KEY",
+        "ALCHEMY_API_KEY",
+        "HELIUS_API_KEY",
+        "BIRDEYE_API_KEY",
+        "SOLANA_RPC_URL",
+        "X402_PRIVATE_KEY",
+        "X402_NETWORK",
+        "X402_PAY_TO",
+        "X402_FACILITATOR_URL",
+        "X402_MAX_PAYMENT_USD",
+        "X402_MAX_TOTAL_USD",
+        "X402_ENABLED",
+        "X402_DB_PATH",
+        // GitHub access for coding agent plugin
+        "GITHUB_TOKEN",
+        "GITHUB_OAUTH_CLIENT_ID",
+    ];
+    const secrets = {};
+    for (const key of secretKeys) {
+        const value = process.env[key];
+        if (value?.trim()) {
+            secrets[key] = value;
+        }
+    }
+    // Normalise messageExamples to the {examples: [{name,content}]} shape
+    // that @elizaos/core expects.  Config may contain EITHER format:
+    //   OLD (preset/onboarding): [[{user, content}, ...], ...]
+    //   NEW (@elizaos/core):     [{examples: [{name, content}, ...]}, ...]
+    const mappedExamples = messageExamples?.map((item) => {
+        // Already in new format — pass through
+        if (item &&
+            typeof item === "object" &&
+            "examples" in item) {
+            return item;
+        }
+        // Old format — array of {user, content} entries
+        const arr = item;
+        return {
+            examples: arr.map((msg) => ({
+                name: msg.name ?? msg.user ?? "",
+                content: msg.content,
+            })),
+        };
+    });
+    return mergeCharacterDefaults({
+        name,
+        bio,
+        system: systemPrompt,
+        ...(style ? { style } : {}),
+        ...(adjectives ? { adjectives } : {}),
+        ...(postExamples ? { postExamples } : {}),
+        ...(mappedExamples ? { messageExamples: mappedExamples } : {}),
+        secrets,
+    });
+}
+/**
+ * Resolve the primary model identifier from Milady config.
+ *
+ * Milady stores the model under `agents.defaults.model.primary` as an
+ * AgentModelListConfig object. Returns undefined when no model is
+ * explicitly configured (elizaOS falls back to whichever model
+ * plugin is loaded).
+ */
+/** @internal Exported for testing. */
+export function resolvePrimaryModel(config) {
+    const modelConfig = config.agents?.defaults?.model;
+    if (!modelConfig)
+        return undefined;
+    // AgentDefaultsConfig.model is AgentModelListConfig: { primary?, fallbacks? }
+    return modelConfig.primary;
+}
+/**
+ * Vision is a heavy optional plugin. When Milady enables it, keep the service
+ * loaded but idle until the user explicitly selects CAMERA, SCREEN, or BOTH.
+ * This avoids background capture loops during normal app startup.
+ */
+export function resolveVisionModeSetting(config, env = process.env) {
+    const explicitMode = env.VISION_MODE?.trim();
+    if (explicitMode)
+        return explicitMode;
+    if (config.features?.vision === true)
+        return "OFF";
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// First-run onboarding
+// ---------------------------------------------------------------------------
+// Name pool + random picker shared with the web UI API server.
+// See src/runtime/onboarding-names.ts for the canonical list.
+import { pickRandomNames } from "./onboarding-names";
+// ---------------------------------------------------------------------------
+// Style presets — shared between CLI and GUI onboarding
+// ---------------------------------------------------------------------------
+import { STYLE_PRESETS } from "../onboarding-presets";
+/**
+ * Detect whether this is the first run (no agent name configured)
+ * and run the onboarding flow:
+ *
+ *   1. Welcome banner
+ *   2. Name selector (4 random + Custom)
+ *   3. Catchphrase / writing-style selector
+ *   4. Persist agent name to `agents.list[0]` in config
+ *
+ * Character personality (bio, system prompt, style) is stored in the
+ * database at runtime — only the agent name lives in config.
+ *
+ * Subsequent runs skip this entirely.
+ */
+async function runFirstTimeSetup(config) {
+    const agentEntry = config.agents?.list?.[0];
+    const hasName = Boolean(agentEntry?.name || config.ui?.assistant?.name);
+    if (hasName)
+        return config;
+    // Only prompt when stdin is a TTY (interactive terminal)
+    if (!process.stdin.isTTY)
+        return config;
+    // Load @clack/prompts lazily — only needed for interactive CLI onboarding.
+    const clack = await loadClack();
+    // ── Step 1: Welcome ────────────────────────────────────────────────────
+    clack.intro("WELCOME TO MILADY!");
+    // ── Step 2: Name ───────────────────────────────────────────────────────
+    const randomNames = pickRandomNames(4);
+    const nameChoice = await clack.select({
+        message: "♡♡milady♡♡: Hey there, I'm.... err, what was my name again?",
+        options: [
+            ...randomNames.map((n) => ({ value: n, label: n })),
+            { value: "_custom_", label: "Custom...", hint: "type your own" },
+        ],
+    });
+    if (clack.isCancel(nameChoice))
+        cancelOnboarding();
+    let name;
+    if (nameChoice === "_custom_") {
+        const customName = await clack.text({
+            message: "OK, what should I be called?",
+            placeholder: "Milady",
+        });
+        if (clack.isCancel(customName))
+            cancelOnboarding();
+        name = customName.trim() || "Milady";
+    }
+    else {
+        name = nameChoice;
+    }
+    clack.log.message(`♡♡${name}♡♡: Oh that's right, I'm ${name}!`);
+    // ── Step 3: Catchphrase / writing style ────────────────────────────────
+    const styleChoice = await clack.select({
+        message: `${name}: Now... how do I like to talk again?`,
+        options: STYLE_PRESETS.map((preset) => ({
+            value: preset.catchphrase,
+            label: preset.catchphrase,
+            hint: preset.hint,
+        })),
+    });
+    if (clack.isCancel(styleChoice))
+        cancelOnboarding();
+    const chosenTemplate = STYLE_PRESETS.find((p) => p.catchphrase === styleChoice);
+    // ── Step 4: Model provider ───────────────────────────────────────────────
+    // Skip provider selection in cloud mode — Eliza Cloud handles inference.
+    // Check whether an API key is already set in the environment (from .env or
+    // shell).  If none is found, ask the user to pick a provider and enter a key.
+    const PROVIDER_OPTIONS = [
+        {
+            id: "anthropic",
+            label: "Anthropic (Claude)",
+            envKey: "ANTHROPIC_API_KEY",
+            detectKeys: ["ANTHROPIC_API_KEY"],
+            hint: "sk-ant-...",
+        },
+        {
+            id: "openai",
+            label: "OpenAI (GPT)",
+            envKey: "OPENAI_API_KEY",
+            detectKeys: ["OPENAI_API_KEY"],
+            hint: "sk-...",
+        },
+        {
+            id: "openrouter",
+            label: "OpenRouter",
+            envKey: "OPENROUTER_API_KEY",
+            detectKeys: ["OPENROUTER_API_KEY"],
+            hint: "sk-or-...",
+        },
+        {
+            id: "vercel-ai-gateway",
+            label: "Vercel AI Gateway",
+            envKey: "AI_GATEWAY_API_KEY",
+            detectKeys: ["AI_GATEWAY_API_KEY", "AIGATEWAY_API_KEY"],
+            hint: "aigw_...",
+        },
+        {
+            id: "gemini",
+            label: "Google Gemini",
+            envKey: "GOOGLE_GENERATIVE_AI_API_KEY",
+            detectKeys: [
+                "GOOGLE_GENERATIVE_AI_API_KEY",
+                "GOOGLE_API_KEY",
+                "GEMINI_API_KEY",
+            ],
+            hint: "AI...",
+        },
+        {
+            id: "grok",
+            label: "xAI (Grok)",
+            envKey: "XAI_API_KEY",
+            detectKeys: ["XAI_API_KEY"],
+            hint: "xai-...",
+        },
+        {
+            id: "groq",
+            label: "Groq",
+            envKey: "GROQ_API_KEY",
+            detectKeys: ["GROQ_API_KEY"],
+            hint: "gsk_...",
+        },
+        {
+            id: "deepseek",
+            label: "DeepSeek",
+            envKey: "DEEPSEEK_API_KEY",
+            detectKeys: ["DEEPSEEK_API_KEY"],
+            hint: "sk-...",
+        },
+        {
+            id: "mistral",
+            label: "Mistral",
+            envKey: "MISTRAL_API_KEY",
+            detectKeys: ["MISTRAL_API_KEY"],
+            hint: "",
+        },
+        {
+            id: "together",
+            label: "Together AI",
+            envKey: "TOGETHER_API_KEY",
+            detectKeys: ["TOGETHER_API_KEY"],
+            hint: "",
+        },
+        {
+            id: "ollama",
+            label: "Ollama (local, free)",
+            envKey: "OLLAMA_BASE_URL",
+            detectKeys: ["OLLAMA_BASE_URL"],
+            hint: "http://localhost:11434",
+        },
+    ];
+    // Detect if any provider key is already configured
+    const detectedProvider = PROVIDER_OPTIONS.find((p) => p.detectKeys.some((key) => process.env[key]?.trim()));
+    let providerEnvKey;
+    let providerApiKey;
+    if (detectedProvider) {
+        clack.log.success(`Found existing ${detectedProvider.label} key in environment (${detectedProvider.envKey})`);
+    }
+    else {
+        const providerChoice = await clack.select({
+            message: `${name}: One more thing — which AI provider should I use?`,
+            options: [
+                ...PROVIDER_OPTIONS.map((p) => ({
+                    value: p.id,
+                    label: p.label,
+                    hint: p.id === "ollama" ? "no API key needed" : undefined,
+                })),
+                {
+                    value: "_skip_",
+                    label: "Skip for now",
+                    hint: "set an API key later via env or config",
+                },
+            ],
+        });
+        if (clack.isCancel(providerChoice))
+            cancelOnboarding();
+        if (providerChoice !== "_skip_") {
+            const chosen = PROVIDER_OPTIONS.find((p) => p.id === providerChoice);
+            if (chosen) {
+                providerEnvKey = chosen.envKey;
+                if (chosen.id === "ollama") {
+                    // Ollama just needs a base URL, default to localhost
+                    const ollamaUrl = await clack.text({
+                        message: "Ollama base URL:",
+                        placeholder: "http://localhost:11434",
+                        defaultValue: "http://localhost:11434",
+                    });
+                    if (clack.isCancel(ollamaUrl))
+                        cancelOnboarding();
+                    providerApiKey = ollamaUrl.trim() || "http://localhost:11434";
+                }
+                else {
+                    const apiKeyInput = await clack.password({
+                        message: `Paste your ${chosen.label} API key:`,
+                    });
+                    if (clack.isCancel(apiKeyInput))
+                        cancelOnboarding();
+                    providerApiKey = apiKeyInput.trim();
+                }
+            }
+        }
+    }
+    // ── Step 4b: Embedding model preset ────────────────────────────────────
+    // (Simplified: always use the standard/reliable model preset. No user choice.)
+    // ── Step 5: Wallet setup ───────────────────────────────────────────────
+    // Offer to generate or import wallets for EVM and Solana. Keys are
+    // stored in config.env and process.env, making them available to
+    // plugins at runtime.
+    const { generateWalletKeys, importWallet } = await import("../api/wallet");
+    const hasEvmKey = Boolean(process.env.EVM_PRIVATE_KEY?.trim());
+    const hasSolKey = Boolean(process.env.SOLANA_PRIVATE_KEY?.trim());
+    if (!hasEvmKey || !hasSolKey) {
+        const walletAction = await clack.select({
+            message: `${name}: Do you want me to set up crypto wallets? (for trading, NFTs, DeFi)`,
+            options: [
+                {
+                    value: "generate",
+                    label: "Generate new wallets",
+                    hint: "creates fresh EVM + Solana keypairs",
+                },
+                {
+                    value: "import",
+                    label: "Import existing wallets",
+                    hint: "paste your private keys",
+                },
+                {
+                    value: "skip",
+                    label: "Skip for now",
+                    hint: "wallets can be added later",
+                },
+            ],
+        });
+        if (clack.isCancel(walletAction))
+            cancelOnboarding();
+        if (walletAction === "generate") {
+            const keys = generateWalletKeys();
+            if (!hasEvmKey) {
+                process.env.EVM_PRIVATE_KEY = keys.evmPrivateKey;
+                clack.log.success(`Generated EVM wallet: ${keys.evmAddress}`);
+            }
+            if (!hasSolKey) {
+                process.env.SOLANA_PRIVATE_KEY = keys.solanaPrivateKey;
+                clack.log.success(`Generated Solana wallet: ${keys.solanaAddress}`);
+            }
+        }
+        else if (walletAction === "import") {
+            // EVM import
+            if (!hasEvmKey) {
+                const evmKeyInput = await clack.password({
+                    message: "Paste your EVM private key (0x... hex, or skip):",
+                });
+                if (!clack.isCancel(evmKeyInput) && evmKeyInput.trim()) {
+                    const result = importWallet("evm", evmKeyInput.trim());
+                    if (result.success) {
+                        clack.log.success(`Imported EVM wallet: ${result.address}`);
+                    }
+                    else {
+                        clack.log.warn(`EVM import failed: ${result.error}`);
+                    }
+                }
+            }
+            // Solana import
+            if (!hasSolKey) {
+                const solKeyInput = await clack.password({
+                    message: "Paste your Solana private key (base58, or skip):",
+                });
+                if (!clack.isCancel(solKeyInput) && solKeyInput.trim()) {
+                    const result = importWallet("solana", solKeyInput.trim());
+                    if (result.success) {
+                        clack.log.success(`Imported Solana wallet: ${result.address}`);
+                    }
+                    else {
+                        clack.log.warn(`Solana import failed: ${result.error}`);
+                    }
+                }
+            }
+        }
+        // "skip" — do nothing
+    }
+    // ── Step 6: Skills Registry (ClawHub default) ──────────────────────────
+    const hasSkillsRegistry = Boolean(process.env.SKILLS_REGISTRY?.trim() || process.env.CLAWHUB_REGISTRY?.trim());
+    const hasSkillsmpKey = Boolean(process.env.SKILLSMP_API_KEY?.trim());
+    if (!hasSkillsRegistry) {
+        process.env.SKILLS_REGISTRY = "https://clawhub.ai";
+    }
+    // ── Step 7: GitHub access (for coding agents, issue management) ─────────
+    const hasGithubToken = Boolean(process.env.GITHUB_TOKEN?.trim());
+    const hasGithubOAuth = Boolean(process.env.GITHUB_OAUTH_CLIENT_ID?.trim());
+    if (!hasGithubToken) {
+        const options = [
+            { value: "skip", label: "Skip for now", hint: "you can add this later" },
+            {
+                value: "pat",
+                label: "Paste a Personal Access Token",
+                hint: "github.com/settings/tokens",
+            },
+        ];
+        if (hasGithubOAuth) {
+            options.push({
+                value: "oauth",
+                label: "Use OAuth (authorize in browser)",
+                hint: "recommended",
+            });
+        }
+        const githubChoice = await clack.select({
+            message: "Configure GitHub access? (needed for coding agents, issue management, PRs)",
+            options,
+        });
+        if (!clack.isCancel(githubChoice) && githubChoice === "pat") {
+            const tokenInput = await clack.password({
+                message: "Paste your GitHub token (or skip):",
+            });
+            if (!clack.isCancel(tokenInput) && tokenInput.trim()) {
+                process.env.GITHUB_TOKEN = tokenInput.trim();
+                clack.log.success("GitHub token configured.");
+            }
+        }
+        else if (!clack.isCancel(githubChoice) && githubChoice === "oauth") {
+            clack.log.info("GitHub OAuth will activate when coding agents need access.");
+        }
+    }
+    // ── Step 8: Persist agent + style + provider + embedding config ─────────
+    // Save the agent name and chosen personality template into config so that
+    // the same character data is used regardless of whether the user onboarded
+    // via CLI or GUI.  This ensures full parity between onboarding surfaces.
+    const existingList = config.agents?.list ?? [];
+    const mainEntry = existingList[0] ?? {
+        id: "main",
+        default: true,
+    };
+    const agentConfigEntry = { ...mainEntry, name };
+    // Apply the chosen style template to the agent config entry so the
+    // personality is persisted — not just the name.
+    if (chosenTemplate) {
+        agentConfigEntry.bio = chosenTemplate.bio;
+        agentConfigEntry.system = chosenTemplate.system;
+        agentConfigEntry.style = chosenTemplate.style;
+        agentConfigEntry.adjectives = chosenTemplate.adjectives;
+        agentConfigEntry.postExamples = chosenTemplate.postExamples;
+        agentConfigEntry.messageExamples = chosenTemplate.messageExamples;
+    }
+    const updatedList = [
+        agentConfigEntry,
+        ...existingList.slice(1),
+    ];
+    const updated = {
+        ...config,
+        agents: {
+            ...config.agents,
+            list: updatedList,
+        },
+    };
+    // Persist the provider API key and wallet keys in config.env so they
+    // survive restarts.  Initialise the env bucket once to avoid the
+    // repeated `if (!updated.env)` pattern.
+    if (!updated.env)
+        updated.env = {};
+    const envBucket = updated.env;
+    if (providerEnvKey && providerApiKey) {
+        envBucket[providerEnvKey] = providerApiKey;
+        // Also set immediately in process.env for the current run
+        process.env[providerEnvKey] = providerApiKey;
+    }
+    if (process.env.EVM_PRIVATE_KEY && !hasEvmKey) {
+        envBucket.EVM_PRIVATE_KEY = process.env.EVM_PRIVATE_KEY;
+    }
+    if (process.env.SOLANA_PRIVATE_KEY && !hasSolKey) {
+        envBucket.SOLANA_PRIVATE_KEY = process.env.SOLANA_PRIVATE_KEY;
+    }
+    if (process.env.SKILLS_REGISTRY && !hasSkillsRegistry) {
+        envBucket.SKILLS_REGISTRY = process.env.SKILLS_REGISTRY;
+    }
+    if (process.env.SKILLSMP_API_KEY && !hasSkillsmpKey) {
+        envBucket.SKILLSMP_API_KEY = process.env.SKILLSMP_API_KEY;
+    }
+    if (process.env.GITHUB_TOKEN && !hasGithubToken) {
+        envBucket.GITHUB_TOKEN = process.env.GITHUB_TOKEN;
+    }
+    if (process.env.GITHUB_OAUTH_CLIENT_ID && !hasGithubOAuth) {
+        envBucket.GITHUB_OAUTH_CLIENT_ID = process.env.GITHUB_OAUTH_CLIENT_ID;
+    }
+    try {
+        saveMiladyConfig(updated);
+    }
+    catch (err) {
+        // Non-fatal: the agent can still start, but choices won't persist.
+        clack.log.warn(`Could not save config: ${formatError(err)}`);
+    }
+    clack.log.message(`${name}: ${styleChoice} Alright, that's me.`);
+    clack.outro("Let's get started!");
+    return updated;
+}
+/**
+ * Boot the elizaOS runtime without starting the readline chat loop.
+ *
+ * This is a convenience wrapper around {@link startEliza} in headless mode,
+ * with optional config guards.
+ */
+export async function bootElizaRuntime(opts = {}) {
+    if (opts.requireConfig && !configFileExists()) {
+        throw new Error("No config found. Run `milady start` once to complete setup.");
+    }
+    const runtime = await startEliza({ headless: true });
+    if (!runtime) {
+        throw new Error("Failed to boot runtime");
+    }
+    return runtime;
+}
+const LEVEL_TO_NAME = {
+    10: "trace",
+    20: "debug",
+    27: "success",
+    28: "progress",
+    29: "log",
+    30: "info",
+    40: "warn",
+    50: "error",
+    60: "fatal",
+};
+export const logToChatListener = (entry) => {
+    if (entry.roomId && entry.runtime) {
+        const runtime = entry.runtime;
+        // access dynamic property
+        const overrides = runtime.logLevelOverrides;
+        const overrideLevel = overrides?.get(String(entry.roomId));
+        if (overrideLevel) {
+            const levelKey = entry.level;
+            const levelName = (levelKey && LEVEL_TO_NAME[levelKey] ? LEVEL_TO_NAME[levelKey] : "log").toUpperCase();
+            const prefix = `[${levelName}]`;
+            const content = `${prefix} ${entry.msg}`;
+            // Prevent infinite loops by suppressing logs from this action
+            runtime
+                .sendMessageToTarget({ roomId: entry.roomId }, {
+                text: `\`\`\`\n${content}\n\`\`\``,
+                source: "system",
+                isLog: "true",
+            })
+                .catch(() => { });
+        }
+    }
+};
+/**
+ * Start the elizaOS runtime with Milady's configuration.
+ *
+ * In headless mode the runtime is returned instead of entering the
+ * interactive readline loop.
+ */
+export async function startEliza(opts) {
+    // Start buffering logs early so startup messages appear in the UI log viewer
+    const { captureEarlyLogs } = await import("../api/early-logs");
+    captureEarlyLogs();
+    // Register log listener for chat mirroring
+    addLogListener(logToChatListener);
+    // 1. Load Milady config from ~/.milady/milady.json
+    let config;
+    try {
+        config = loadMiladyConfig();
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            logger.warn("[milady] No config found, using defaults");
+            // All MiladyConfig fields are optional, so an empty object is
+            // structurally valid. The `as` cast is safe here.
+            config = {};
+        }
+        else {
+            throw err;
+        }
+    }
+    // 1b. First-run onboarding — ask for agent name if not configured.
+    //     In headless mode (GUI) the onboarding is handled by the web UI,
+    //     so we skip the interactive CLI prompt and let the runtime start
+    //     with defaults.  The GUI will restart the agent after onboarding.
+    if (!opts?.headless) {
+        config = await runFirstTimeSetup(config);
+    }
+    // 1c. Apply logging level from config to process.env so the global
+    //     @elizaos/core logger (used by plugins) respects it.
+    //     config.logging.level is guaranteed to be set (defaults to "error").
+    //     Users can still opt into noisy logs via config.logging.level or
+    //     an explicit LOG_LEVEL environment variable.
+    if (!process.env.LOG_LEVEL) {
+        process.env.LOG_LEVEL = config.logging?.level ?? "error";
+    }
+    // 2. Push channel secrets into process.env for plugin discovery
+    applyConnectorSecretsToEnv(config);
+    await autoResolveDiscordAppId();
+    // 2b. Propagate cloud config into process.env for ElizaCloud plugin
+    applyCloudConfigToEnv(config);
+    // 2c. Propagate x402 config into process.env
+    applyX402ConfigToEnv(config);
+    // 2d. Propagate database config into process.env for plugin-sql
+    applyDatabaseConfigToEnv(config);
+    // 2e. Propagate arbitrary env vars from config.env into process.env.
+    // Milady stores user-defined env vars (plugin settings, API URLs, etc.)
+    // in config.env; elizaOS plugins read them via process.env / getSetting.
+    if (config.env &&
+        typeof config.env === "object" &&
+        !Array.isArray(config.env)) {
+        for (const [key, value] of Object.entries(config.env)) {
+            if (typeof value === "string" && !process.env[key]) {
+                process.env[key] = value;
+            }
+        }
+    }
+    // Log active database configuration for debugging persistence issues
+    {
+        const dbProvider = config.database?.provider ?? "pglite";
+        const pgliteDir = process.env.PGLITE_DATA_DIR;
+        const postgresUrl = process.env.POSTGRES_URL;
+        logger.info(`[milady] Database provider: ${dbProvider}` +
+            (dbProvider === "pglite" && pgliteDir
+                ? ` | data dir: ${pgliteDir}`
+                : "") +
+            (dbProvider === "postgres" && postgresUrl
+                ? ` | connection: ${postgresUrl.replace(/:\/\/([^:]+):([^@]+)@/, "://$1:***@")}`
+                : ""));
+    }
+    // 2d-iii. OG tracking code initialization
+    try {
+        const { initializeOGCode } = await import("../api/og-tracker");
+        initializeOGCode();
+    }
+    catch {
+        // Silent — OG tracking is non-critical
+    }
+    // 2d-ii. Allow destructive migrations (e.g. dropping tables removed between
+    //        plugin versions) so the runtime doesn't silently stall.  Without this
+    //        the migration system throws an error that gets swallowed, leaving the
+    //        app hanging indefinitely with no output.
+    if (!process.env.ELIZA_ALLOW_DESTRUCTIVE_MIGRATIONS) {
+        process.env.ELIZA_ALLOW_DESTRUCTIVE_MIGRATIONS = "true";
+    }
+    // 2e. Prevent @elizaos/core from auto-loading @elizaos/plugin-bootstrap.
+    //     Milady uses @elizaos/plugin-trust which provides the settings/roles
+    //     providers and actions.  plugin-bootstrap (v1.x) is incompatible with
+    //     the 2.0.0-alpha.x runtime used here.
+    if (!process.env.IGNORE_BOOTSTRAP) {
+        process.env.IGNORE_BOOTSTRAP = "true";
+    }
+    // 2e-ii. Ensure SECRET_SALT is set to suppress the @elizaos/core default
+    //        warning and avoid using a predictable value in production.
+    if (!process.env.SECRET_SALT) {
+        process.env.SECRET_SALT = crypto.randomBytes(32).toString("hex");
+        logger.info("[milady] Generated random SECRET_SALT for this session");
+    }
+    // 2e-iii. Pre-flight validation for Google AI API keys.  If the key looks
+    //         obviously invalid (too short, placeholder, wrong prefix), clear it
+    //         to prevent plugin-google-genai from making a failing API call.
+    for (const gkey of [
+        "GEMINI_API_KEY",
+        "GOOGLE_API_KEY",
+        "GOOGLE_GENERATIVE_AI_API_KEY",
+    ]) {
+        const val = process.env[gkey]?.trim();
+        if (val &&
+            (val.length < 20 || val === "your-key-here" || val.startsWith("sk-"))) {
+            logger.warn(`[milady] ${gkey} appears invalid (length/format), clearing to skip Google AI plugin`);
+            delete process.env[gkey];
+        }
+    }
+    // 2f. Apply subscription-based credentials (Claude Max, Codex Max)
+    try {
+        const { applySubscriptionCredentials } = await import("../auth/index");
+        await applySubscriptionCredentials(config);
+    }
+    catch (err) {
+        logger.warn(`[milady] Failed to apply subscription credentials: ${err}`);
+    }
+    // 3. Build elizaOS Character from Milady config
+    const character = buildCharacterFromConfig(config);
+    const primaryModel = resolvePrimaryModel(config);
+    // 4. Ensure workspace exists with bootstrap files
+    const workspaceDir = config.agents?.defaults?.workspace ?? resolveDefaultAgentWorkspaceDir();
+    await ensureAgentWorkspace({ dir: workspaceDir, ensureBootstrapFiles: true });
+    // 4b. Ensure custom plugins directory exists for drop-in plugins
+    await fs.mkdir(path.join(resolveStateDir(), CUSTOM_PLUGINS_DIRNAME), {
+        recursive: true,
+    });
+    // 5. Create the Milady bridge plugin (workspace context + session keys + compaction)
+    const agentId = character.name?.toLowerCase().replace(/\s+/g, "-") ?? "main";
+    const miladyPlugin = createAutonomousPlugin({
+        workspaceDir,
+        bootstrapMaxChars: config.agents?.defaults?.bootstrapMaxChars,
+        agentId,
+    });
+    // 6. Resolve and load plugins
+    // In headless (GUI) mode before onboarding, the user hasn't configured a
+    // provider yet.  Downgrade diagnostics so the expected "no AI provider"
+    // state doesn't appear as a scary Error in the terminal.
+    const preOnboarding = opts?.headless && !config.agents;
+    const resolvedPlugins = await resolvePlugins(config, {
+        quiet: preOnboarding,
+    });
+    if (resolvedPlugins.length === 0) {
+        if (preOnboarding) {
+            logger.info("[milady] No plugins loaded yet — the onboarding wizard will configure a model provider");
+        }
+        else {
+            logger.error("[milady] No plugins loaded — at least one model provider plugin is required");
+            logger.error("[milady] Set an API key (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY) in your environment");
+            throw new Error("No plugins loaded");
+        }
+    }
+    // 6b. Debug logging — print full context after provider + plugin resolution
+    {
+        const pluginNames = resolvedPlugins.map((p) => p.name);
+        const providerNames = resolvedPlugins
+            .flatMap((p) => p.plugin.providers ?? [])
+            .map((prov) => prov.name);
+        // Build a context summary for validation
+        const contextSummary = {
+            agentName: character.name,
+            pluginCount: resolvedPlugins.length,
+            providerCount: providerNames.length,
+            primaryModel: primaryModel ?? "(auto-detect)",
+            workspaceDir,
+        };
+        debugLogResolvedContext(pluginNames, providerNames, contextSummary, (msg) => logger.debug(msg));
+        // Validate the context and surface issues early
+        const contextValidation = validateRuntimeContext(contextSummary);
+        if (!contextValidation.valid) {
+            const issues = [];
+            if (contextValidation.nullFields.length > 0) {
+                issues.push(`null: ${contextValidation.nullFields.join(", ")}`);
+            }
+            if (contextValidation.undefinedFields.length > 0) {
+                issues.push(`undefined: ${contextValidation.undefinedFields.join(", ")}`);
+            }
+            if (contextValidation.emptyFields.length > 0) {
+                issues.push(`empty: ${contextValidation.emptyFields.join(", ")}`);
+            }
+            logger.warn(`[milady] Context validation issues detected: ${issues.join("; ")}`);
+        }
+    }
+    // 7. Create the AgentRuntime with Milady plugin + resolved plugins
+    //    All CORE_PLUGINS are pre-registered sequentially (in CORE_PLUGINS
+    //    order) before runtime.initialize() so that cross-plugin getService()
+    //    calls always resolve.  runtime.initialize() registers remaining
+    //    characterPlugins (connectors, providers, custom) in parallel — those
+    //    are NOT core and don't have ordering dependencies.
+    const PREREGISTER_PLUGINS = new Set(CORE_PLUGINS);
+    const sqlPlugin = resolvedPlugins.find((p) => p.name === "@elizaos/plugin-sql");
+    const localEmbeddingPlugin = resolvedPlugins.find((p) => p.name === "@elizaos/plugin-local-embedding");
+    const otherPlugins = resolvedPlugins.filter((p) => !PREREGISTER_PLUGINS.has(p.name));
+    // Resolve the runtime log level from config (AgentRuntime doesn't support
+    // "silent", so we map it to "fatal" as the quietest supported level).
+    const runtimeLogLevel = (() => {
+        // process.env.LOG_LEVEL is already resolved (set explicitly or from
+        // config.logging.level above), so prefer it to honour the dev-mode
+        // LOG_LEVEL=error override set by scripts/dev-ui.mjs.
+        const lvl = process.env.LOG_LEVEL ?? config.logging?.level ?? "error";
+        if (lvl === "silent")
+            return "fatal";
+        return lvl;
+    })();
+    // 7a. Resolve bundled skills directory from @elizaos/skills so
+    //     plugin-agent-skills auto-loads them on startup.
+    let bundledSkillsDir = null;
+    try {
+        const { getSkillsDir } = (await import("@elizaos/skills"));
+        bundledSkillsDir = getSkillsDir();
+        logger.info(`[milady] Bundled skills dir: ${bundledSkillsDir}`);
+    }
+    catch {
+        logger.debug("[milady] @elizaos/skills not available — bundled skills will not be loaded");
+    }
+    // Workspace skills directory (highest precedence for overrides)
+    const workspaceSkillsDir = workspaceDir ? `${workspaceDir}/skills` : null;
+    const managedSkillsDir = path.join(resolveStateDir(), "skills");
+    // ── Sandbox mode setup ──────────────────────────────────────────────────
+    const sandboxConfig = config.agents?.defaults?.sandbox;
+    const sandboxModeStr = sandboxConfig
+        ?.mode;
+    const sandboxMode = sandboxModeStr === "light" ||
+        sandboxModeStr === "standard" ||
+        sandboxModeStr === "max"
+        ? sandboxModeStr
+        : "off";
+    const isSandboxActive = sandboxMode !== "off";
+    let sandboxManager = null;
+    let sandboxAuditLog = null;
+    if (isSandboxActive) {
+        logger.info(`[milady] Sandbox mode: ${sandboxMode}`);
+        sandboxAuditLog = new SandboxAuditLog({ console: true });
+        // Standard/max modes also start the container sandbox manager
+        if (sandboxMode === "standard" || sandboxMode === "max") {
+            const dockerSettings = sandboxConfig?.docker;
+            const browserSettings = sandboxConfig?.browser;
+            sandboxManager = new SandboxManager({
+                mode: sandboxMode,
+                image: dockerSettings?.image ?? undefined,
+                containerPrefix: dockerSettings?.containerPrefix ?? undefined,
+                network: dockerSettings?.network ?? undefined,
+                memory: dockerSettings?.memory ?? undefined,
+                cpus: dockerSettings?.cpus ?? undefined,
+                workspaceRoot: workspaceDir ?? undefined,
+                browser: browserSettings
+                    ? {
+                        enabled: browserSettings.enabled ?? false,
+                        image: browserSettings.image ?? undefined,
+                        cdpPort: browserSettings.cdpPort ?? undefined,
+                        vncPort: browserSettings.vncPort ?? undefined,
+                        noVncPort: browserSettings.noVncPort ?? undefined,
+                        headless: browserSettings.headless ?? undefined,
+                        enableNoVnc: browserSettings.enableNoVnc ?? undefined,
+                        autoStart: browserSettings.autoStart ?? true,
+                        autoStartTimeoutMs: browserSettings.autoStartTimeoutMs ?? undefined,
+                    }
+                    : undefined,
+            });
+            try {
+                await sandboxManager.start();
+                logger.info("[milady] Sandbox manager started");
+            }
+            catch (err) {
+                logger.error(`[milady] Sandbox manager failed to start: ${err instanceof Error ? err.message : String(err)}`);
+                // Non-fatal: light mode fallback
+            }
+        }
+        sandboxAuditLog.record({
+            type: "sandbox_lifecycle",
+            summary: `Sandbox initialized: mode=${sandboxMode}`,
+            severity: "info",
+        });
+    }
+    // ── End sandbox setup ───────────────────────────────────────────────────
+    // ── Boost preferred model plugin priority ─────────────────────────────
+    // elizaOS selects the model handler with the highest `priority` for each
+    // ModelType.  All provider plugins default to priority 0, so whichever
+    // registers first wins — essentially random when using Promise.all.
+    // When the user has explicitly chosen a primary model provider (via
+    // `model.primary` in config), we bump that plugin's priority so its
+    // handlers are always selected over other providers.
+    const pluginsForRuntime = otherPlugins.map((p) => p.plugin);
+    const visionModeSetting = resolveVisionModeSetting(config);
+    if (primaryModel) {
+        for (const plugin of pluginsForRuntime) {
+            if (plugin.name === primaryModel) {
+                plugin.priority = (plugin.priority ?? 0) + 10;
+                logger.info(`[milady] Boosted plugin "${plugin.name}" priority to ${plugin.priority} (model.primary)`);
+                break;
+            }
+        }
+    }
+    // Deduplicate actions across all plugins to avoid "Action already registered"
+    // warnings from elizaOS core. First plugin wins (miladyPlugin is first).
+    deduplicatePluginActions([miladyPlugin, ...pluginsForRuntime]);
+    let runtime = new AgentRuntime({
+        character,
+        // advancedCapabilities: true,
+        actionPlanning: true,
+        // advancedMemory: true, // Not supported in this version of AgentRuntime
+        plugins: [miladyPlugin, ...pluginsForRuntime],
+        ...(runtimeLogLevel ? { logLevel: runtimeLogLevel } : {}),
+        // Sandbox options — only active when mode != "off"
+        ...(isSandboxActive
+            ? {
+                sandboxMode: true,
+                sandboxAuditHandler: sandboxAuditLog
+                    ? (event) => {
+                        sandboxAuditLog.recordTokenReplacement(event.direction, event.url, event.tokenIds);
+                    }
+                    : undefined,
+            }
+            : {}),
+        settings: {
+            VALIDATION_LEVEL: "fast",
+            // Forward non-sensitive Milady config.env vars as runtime settings so
+            // plugins can access them via runtime.getSetting(). This fixes a bug where
+            // plugins (e.g. @elizaos/plugin-google-genai) call runtime.getSetting()
+            // which returns null for keys not in settings, but the plugin checks
+            // !== undefined causing it to use "null" as the model name.
+            //
+            // Security: Filter out blockchain private keys and secrets. API keys are
+            // allowed since plugins need them via runtime.getSetting(). Private keys
+            // should only be accessed via process.env by signing services.
+            ...Object.fromEntries(Object.entries(collectConfigEnvVars(config)).filter(([key]) => isEnvKeyAllowedForForwarding(key))),
+            // Forward Milady config env vars as runtime settings
+            ...(primaryModel ? { MODEL_PROVIDER: primaryModel } : {}),
+            ...(visionModeSetting ? { VISION_MODE: visionModeSetting } : {}),
+            // Forward skills config so plugin-agent-skills can apply allow/deny filtering
+            ...(config.skills?.allowBundled
+                ? { SKILLS_ALLOWLIST: config.skills.allowBundled.join(",") }
+                : {}),
+            ...(config.skills?.denyBundled
+                ? { SKILLS_DENYLIST: config.skills.denyBundled.join(",") }
+                : {}),
+            // Managed skills are stored in the Milady state dir (~/.milady/skills).
+            SKILLS_DIR: managedSkillsDir,
+            // Tell plugin-agent-skills where to find bundled + workspace skills
+            ...(bundledSkillsDir ? { BUNDLED_SKILLS_DIRS: bundledSkillsDir } : {}),
+            ...(workspaceSkillsDir
+                ? { WORKSPACE_SKILLS_DIR: workspaceSkillsDir }
+                : {}),
+            // Also forward extra dirs from config
+            ...(config.skills?.load?.extraDirs?.length
+                ? { EXTRA_SKILLS_DIRS: config.skills.load.extraDirs.join(",") }
+                : {}),
+            // Disable image description when vision is explicitly toggled off.
+            // The cloud plugin always registers IMAGE_DESCRIPTION, so we need a
+            // runtime setting to prevent the message service from calling it.
+            ...(config.features?.vision === false
+                ? { DISABLE_IMAGE_DESCRIPTION: "true" }
+                : {}),
+        },
+    });
+    installRuntimeMethodBindings(runtime);
+    // 7b. Pre-register plugin-sql so the adapter is ready before other plugins init.
+    //     This is OPTIONAL — without it, some features (memory, todos) won't work.
+    //     runtime.db is a getter that returns this.adapter.db and throws when
+    //     this.adapter is undefined, so plugins that use runtime.db will fail.
+    if (sqlPlugin) {
+        // 7c. Eagerly initialize the database adapter so it's fully ready
+        //     BEFORE other plugins run their init(). When legacy/corrupt PGLite
+        //     state causes startup aborts, reset the local DB dir and retry once.
+        await registerSqlPluginWithRecovery(runtime, sqlPlugin, config);
+    }
+    else {
+        const loadedNames = resolvedPlugins.map((p) => p.name).join(", ");
+        logger.error(`[milady] @elizaos/plugin-sql was NOT found among resolved plugins. ` +
+            `Loaded: [${loadedNames}]`);
+        throw new Error("@elizaos/plugin-sql is required but was not loaded. " +
+            "Ensure the package is installed and built (check for import errors above).");
+    }
+    // 7d. Pre-register plugin-local-embedding so its TEXT_EMBEDDING handler
+    //     (priority 10) is available before runtime.initialize() starts all
+    //     plugins in parallel.  Without this, the bootstrap plugin's services
+    //     (ActionFilterService, EmbeddingGenerationService) race ahead and use
+    //     the cloud plugin's TEXT_EMBEDDING handler — which hits a paid API —
+    //     because local-embedding's heavier init hasn't completed yet.
+    if (localEmbeddingPlugin) {
+        configureLocalEmbeddingPlugin(localEmbeddingPlugin.plugin, config);
+        await runtime.registerPlugin(localEmbeddingPlugin.plugin);
+        logger.info("[milady] plugin-local-embedding pre-registered (TEXT_EMBEDDING ready)");
+    }
+    else {
+        logger.warn("[milady] @elizaos/plugin-local-embedding not found — embeddings " +
+            "will fall back to whatever TEXT_EMBEDDING handler is registered by " +
+            "other plugins (may incur cloud API costs)");
+    }
+    // 7e. Pre-register remaining core plugins sequentially in CORE_PLUGINS order.
+    //     Each registerPlugin() call runs the plugin's init() before proceeding
+    //     to the next, guaranteeing that cross-plugin getService() calls resolve.
+    {
+        const alreadyPreRegistered = new Set([
+            "@elizaos/plugin-sql",
+            "@elizaos/plugin-local-embedding",
+        ]);
+        for (const name of CORE_PLUGINS) {
+            if (alreadyPreRegistered.has(name))
+                continue;
+            const resolved = resolvedPlugins.find((p) => p.name === name);
+            if (!resolved) {
+                logger.debug(`[milady] Core plugin ${name} not resolved — skipping pre-registration`);
+                continue;
+            }
+            try {
+                await runtime.registerPlugin(resolved.plugin);
+            }
+            catch (err) {
+                logger.warn(`[milady] Core plugin ${name} pre-registration failed: ${formatError(err)}`);
+            }
+        }
+    }
+    const warmAgentSkillsService = async () => {
+        // Let runtime startup complete first; this warm-up runs asynchronously
+        // so API + agent come online immediately.
+        try {
+            const skillServicePromise = runtime.getServiceLoadPromise("AGENT_SKILLS_SERVICE");
+            const timeout = new Promise((_resolve, reject) => {
+                setTimeout(() => {
+                    reject(new Error("AgentSkillsService warm-up timed out (10s) — non-blocking, agent will function without skills"));
+                }, 10_000);
+            });
+            await Promise.race([skillServicePromise, timeout]);
+            const svc = runtime.getService("AGENT_SKILLS_SERVICE");
+            if (svc?.getCatalogStats) {
+                const stats = svc.getCatalogStats();
+                logger.info(`[milady] AgentSkills ready — ${stats.loaded} skills loaded, ` +
+                    `${stats.total} in catalog (storage: ${stats.storageType})`);
+            }
+            // Guard against non-string skill.description values.
+            // The bundled YAML parser produces {} for multi-line descriptions, which
+            // crashes findBestLocalMatch / scoreSkillMatch (call .toLowerCase() on it).
+            // Instead of a one-shot sanitize (which misses skills loaded later by
+            // syncCatalog / autoRefresh), we monkey-patch getLoadedSkills to always
+            // return sanitized values.
+            const svcAny = svc;
+            const origGetLoaded = svcAny?.getLoadedSkills;
+            if (origGetLoaded && svcAny) {
+                svcAny.getLoadedSkills = function (...args) {
+                    const skills = origGetLoaded.apply(this, args);
+                    for (const skill of skills) {
+                        if (typeof skill.description !== "string") {
+                            skill.description =
+                                skill.description == null
+                                    ? ""
+                                    : JSON.stringify(skill.description);
+                        }
+                    }
+                    return skills;
+                };
+                logger.debug("[milady] Patched getLoadedSkills to guard descriptions");
+            }
+        }
+        catch (err) {
+            // Non-fatal — the agent can operate without skills. This warm-up runs
+            // async so it doesn't block startup.
+            logger.debug(`[milady] AgentSkillsService warm-up: ${formatError(err)}`);
+        }
+    };
+    const initializeRuntimeServices = async () => {
+        // 8. Initialize the runtime (registers remaining plugins, starts services)
+        await runtime.initialize();
+        await waitForTrajectoryLoggerService(runtime, "runtime.initialize()");
+        ensureTrajectoryLoggerEnabled(runtime, "runtime.initialize()");
+        installDatabaseTrajectoryLogger(runtime);
+        patchTrajectoryLoggerAliasCompatibility(runtime);
+        // 8b. Ensure AutonomyService is available for trigger dispatch.
+        // IGNORE_BOOTSTRAP=true prevents the bootstrap plugin (which normally
+        // registers this service) from loading, so we start it explicitly.
+        if (!runtime.getService("AUTONOMY")) {
+            try {
+                await AutonomyService.start(runtime);
+                logger.info("[milady] AutonomyService started for trigger dispatch");
+            }
+            catch (err) {
+                logger.warn(`[milady] AutonomyService failed to start: ${formatError(err)}`);
+            }
+        }
+        // Do not block runtime startup on skills warm-up.
+        void warmAgentSkillsService();
+    };
+    try {
+        await initializeRuntimeServices();
+    }
+    catch (err) {
+        const pgliteDataDir = resolveActivePgliteDataDir(config);
+        const recoveryAction = !opts?.pgliteRecoveryAttempted && pgliteDataDir
+            ? getPgliteRecoveryAction(err, pgliteDataDir)
+            : "none";
+        if (!pgliteDataDir || recoveryAction === "none") {
+            throw err;
+        }
+        if (recoveryAction === "fail-active-lock") {
+            throw createActivePgliteLockError(pgliteDataDir, err);
+        }
+        logger.warn(recoveryAction === "retry-without-reset"
+            ? `[milady] Runtime migrations failed (${formatError(err)}). Cleared a stale PGLite lock in ${pgliteDataDir} and retrying startup once without resetting data.`
+            : `[milady] Runtime migrations failed (${formatError(err)}). Resetting local PGLite DB at ${pgliteDataDir} and retrying startup once.`);
+        try {
+            await shutdownRuntime(runtime, "PGLite recovery");
+        }
+        catch {
+            // Ignore cleanup errors — retry creates a fresh runtime anyway.
+        }
+        if (recoveryAction === "reset-data-dir") {
+            await resetPgliteDataDir(pgliteDataDir);
+            process.env.PGLITE_DATA_DIR = pgliteDataDir;
+        }
+        return await startEliza({
+            ...opts,
+            pgliteRecoveryAttempted: true,
+        });
+    }
+    installActionAliases(runtime);
+    // 9. Graceful shutdown handler
+    //
+    // In headless mode the caller (dev-server / Electron) owns the process
+    // lifecycle, so we must NOT register signal handlers here — they would
+    // stack on every hot-restart, close over stale runtime references, and
+    // race with bun --watch's own process teardown.
+    if (!opts?.headless) {
+        let isShuttingDown = false;
+        const shutdown = async () => {
+            if (isShuttingDown)
+                return;
+            isShuttingDown = true;
+            try {
+                // Stop sandbox manager before runtime
+                if (sandboxManager) {
+                    try {
+                        await sandboxManager.stop();
+                        logger.info("[milady] Sandbox manager stopped");
+                    }
+                    catch (err) {
+                        logger.warn(`[milady] Sandbox stop error: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+            }
+            catch (err) {
+                logger.warn(`[milady] Sandbox shutdown error: ${formatError(err)}`);
+            }
+            try {
+                await shutdownRuntime(runtime, "signal shutdown");
+            }
+            catch (err) {
+                logger.warn(`[milady] Error during shutdown: ${formatError(err)}`);
+            }
+            process.exit(0);
+        };
+        process.on("SIGINT", () => void shutdown());
+        process.on("SIGTERM", () => void shutdown());
+    }
+    const loadHooksSystem = async () => {
+        try {
+            const internalHooksConfig = config.hooks
+                ?.internal;
+            await loadHooks({
+                workspacePath: workspaceDir,
+                internalConfig: internalHooksConfig,
+                miladyConfig: config,
+            });
+            const startupEvent = createHookEvent("gateway", "startup", "system", {
+                cfg: config,
+            });
+            await triggerHook(startupEvent);
+        }
+        catch (err) {
+            logger.warn(`[milady] Hooks system could not load: ${formatError(err)}`);
+        }
+    };
+    // ── Headless mode — return runtime for API server wiring ──────────────
+    if (opts?.headless) {
+        void loadHooksSystem();
+        logger.info("[milady] Runtime initialised in headless mode (autonomy enabled)");
+        return runtime;
+    }
+    // 10. Load hooks system
+    await loadHooksSystem();
+    // ── Start API server for GUI access ──────────────────────────────────────
+    // In CLI mode (non-headless), start the API server in the background so
+    // the GUI can connect to the running agent.  This ensures full feature
+    // parity: whether started via `npx miladyai`, `bun run dev`, or the
+    // desktop app, the API server is always available for the GUI admin
+    // surface.
+    try {
+        const { startApiServer } = await import("../api/server");
+        const apiPort = Number(process.env.MILADY_PORT) || 2138;
+        const { port: actualApiPort } = await startApiServer({
+            port: apiPort,
+            runtime,
+            onRestart: async () => {
+                logger.info("[milady] Hot-reload: Restarting runtime...");
+                try {
+                    // Stop the old runtime to release resources (DB connections, timers, etc.)
+                    try {
+                        await shutdownRuntime(runtime, "hot-reload cleanup");
+                    }
+                    catch (stopErr) {
+                        logger.warn(`[milady] Hot-reload: old runtime stop failed: ${formatError(stopErr)}`);
+                    }
+                    // Reload config from disk (updated by API)
+                    const freshConfig = loadMiladyConfig();
+                    // Propagate secrets & cloud config into process.env so plugins
+                    // (especially plugin-elizacloud) can discover them.  The initial
+                    // startup does this in startEliza(); the hot-reload must repeat it
+                    // because the config may have changed (e.g. cloud enabled during
+                    // onboarding).
+                    applyConnectorSecretsToEnv(freshConfig);
+                    await autoResolveDiscordAppId();
+                    applyCloudConfigToEnv(freshConfig);
+                    applyX402ConfigToEnv(freshConfig);
+                    applyDatabaseConfigToEnv(freshConfig);
+                    // Apply subscription-based credentials (Claude Max, Codex Max)
+                    // that may have been set up during onboarding.
+                    try {
+                        const { applySubscriptionCredentials } = await import("../auth/index");
+                        await applySubscriptionCredentials(freshConfig);
+                    }
+                    catch (subErr) {
+                        logger.warn(`[milady] Hot-reload: subscription credentials: ${formatError(subErr)}`);
+                    }
+                    // Resolve plugins using same function as startup
+                    const resolvedPlugins = await resolvePlugins(freshConfig);
+                    // Rebuild character from the fresh config so onboarding changes
+                    // (name, bio, style, etc.) are picked up on restart.
+                    const freshCharacter = buildCharacterFromConfig(freshConfig);
+                    // Recreate Milady plugin with fresh workspace
+                    const freshMiladyPlugin = createAutonomousPlugin({
+                        workspaceDir: freshConfig.agents?.defaults?.workspace ?? workspaceDir,
+                        bootstrapMaxChars: freshConfig.agents?.defaults?.bootstrapMaxChars,
+                        agentId: freshCharacter.name?.toLowerCase().replace(/\s+/g, "-") ?? "main",
+                    });
+                    // Create new runtime with updated plugins.
+                    // Filter out pre-registered plugins so they aren't double-loaded
+                    // inside initialize()'s Promise.all — same pattern as the initial
+                    // startup to avoid the TEXT_EMBEDDING race condition.
+                    const freshPrimaryModel = resolvePrimaryModel(freshConfig);
+                    const freshOtherPlugins = resolvedPlugins.filter((p) => !PREREGISTER_PLUGINS.has(p.name));
+                    // Boost preferred model plugin priority (same as initial startup)
+                    const freshPluginsForRuntime = freshOtherPlugins.map((p) => p.plugin);
+                    const freshVisionModeSetting = resolveVisionModeSetting(freshConfig);
+                    if (freshPrimaryModel) {
+                        for (const plugin of freshPluginsForRuntime) {
+                            if (plugin.name === freshPrimaryModel) {
+                                plugin.priority = (plugin.priority ?? 0) + 10;
+                                break;
+                            }
+                        }
+                    }
+                    const newRuntime = new AgentRuntime({
+                        character: freshCharacter,
+                        plugins: [freshMiladyPlugin, ...freshPluginsForRuntime],
+                        ...(runtimeLogLevel ? { logLevel: runtimeLogLevel } : {}),
+                        settings: {
+                            ...(freshPrimaryModel
+                                ? { MODEL_PROVIDER: freshPrimaryModel }
+                                : {}),
+                            ...(freshVisionModeSetting
+                                ? { VISION_MODE: freshVisionModeSetting }
+                                : {}),
+                            // Disable image description when vision is explicitly toggled off.
+                            ...(freshConfig.features?.vision === false
+                                ? { DISABLE_IMAGE_DESCRIPTION: "true" }
+                                : {}),
+                        },
+                    });
+                    installRuntimeMethodBindings(newRuntime);
+                    // Pre-register plugin-sql + local-embedding before initialize()
+                    // to avoid the same race condition as the initial startup.
+                    // Re-derive from freshly resolved plugins (not outer closure) so
+                    // hot-reload picks up any plugin updates.
+                    const freshSqlPlugin = resolvedPlugins.find((p) => p.name === "@elizaos/plugin-sql");
+                    const freshLocalEmbeddingPlugin = resolvedPlugins.find((p) => p.name === "@elizaos/plugin-local-embedding");
+                    if (freshSqlPlugin) {
+                        await registerSqlPluginWithRecovery(newRuntime, freshSqlPlugin, freshConfig);
+                    }
+                    if (freshLocalEmbeddingPlugin) {
+                        configureLocalEmbeddingPlugin(freshLocalEmbeddingPlugin.plugin, freshConfig);
+                        await newRuntime.registerPlugin(freshLocalEmbeddingPlugin.plugin);
+                    }
+                    // Pre-register remaining core plugins sequentially (same as startup)
+                    {
+                        const alreadyPreRegistered = new Set([
+                            "@elizaos/plugin-sql",
+                            "@elizaos/plugin-local-embedding",
+                        ]);
+                        for (const name of CORE_PLUGINS) {
+                            if (alreadyPreRegistered.has(name))
+                                continue;
+                            const resolved = resolvedPlugins.find((p) => p.name === name);
+                            if (!resolved)
+                                continue;
+                            try {
+                                await newRuntime.registerPlugin(resolved.plugin);
+                            }
+                            catch (err) {
+                                logger.warn(`[milady] Hot-reload: core plugin ${name} pre-registration failed: ${formatError(err)}`);
+                            }
+                        }
+                    }
+                    await newRuntime.initialize();
+                    await waitForTrajectoryLoggerService(newRuntime, "hot-reload runtime.initialize()");
+                    ensureTrajectoryLoggerEnabled(newRuntime, "hot-reload runtime.initialize()");
+                    // Ensure AutonomyService survives hot-reload
+                    if (!newRuntime.getService("AUTONOMY")) {
+                        try {
+                            await AutonomyService.start(newRuntime);
+                        }
+                        catch (err) {
+                            logger.warn(`[milady] AutonomyService failed to start after hot-reload: ${formatError(err)}`);
+                        }
+                    }
+                    installActionAliases(newRuntime);
+                    runtime = newRuntime;
+                    logger.info("[milady] Hot-reload: Runtime restarted successfully");
+                    return newRuntime;
+                }
+                catch (err) {
+                    logger.error(`[milady] Hot-reload failed: ${formatError(err)}`);
+                    return null;
+                }
+            },
+        });
+        const dashboardUrl = `http://localhost:${actualApiPort}`;
+        console.log(`[milady] Control UI: ${dashboardUrl}`);
+        logger.info(`[milady] API server listening on ${dashboardUrl}`);
+    }
+    catch (apiErr) {
+        logger.warn(`[milady] Could not start API server: ${formatError(apiErr)}`);
+        // Non-fatal — CLI chat loop still works without the API server.
+    }
+    // ── Server-only mode — keep running without chat loop ────────────────────
+    if (opts?.serverOnly) {
+        logger.info("[milady] Running in server-only mode (no interactive chat)");
+        console.log("[milady] Server running. Press Ctrl+C to stop.");
+        // Keep process alive — the API server handles all interaction
+        const keepAlive = setInterval(() => { }, 1 << 30); // ~12 days
+        // Cleanup on exit
+        const cleanup = async () => {
+            clearInterval(keepAlive);
+            try {
+                await shutdownRuntime(runtime, "server-only shutdown");
+            }
+            catch (err) {
+                logger.warn(`[milady] Error stopping runtime: ${formatError(err)}`);
+            }
+            process.exit(0);
+        };
+        process.on("SIGINT", () => void cleanup());
+        process.on("SIGTERM", () => void cleanup());
+        return runtime;
+    }
+    // ── Interactive chat loop ────────────────────────────────────────────────
+    const agentName = character.name ?? "Milady";
+    const userId = crypto.randomUUID();
+    // Use `let` so the fallback path can reassign to fresh IDs.
+    let roomId = stringToUuid(`${agentName}-chat-room`);
+    try {
+        const worldId = stringToUuid(`${agentName}-chat-world`);
+        // Use a deterministic messageServerId so the settings provider
+        // can reference the world by serverId after it is found.
+        const messageServerId = stringToUuid(`${agentName}-cli-server`);
+        await runtime.ensureConnection({
+            entityId: userId,
+            roomId,
+            worldId,
+            userName: "User",
+            source: "cli",
+            channelId: `${agentName}-chat`,
+            type: ChannelType.DM,
+            messageServerId,
+            metadata: { ownership: { ownerId: userId } },
+        });
+        // Ensure the world has ownership metadata so the settings
+        // provider can locate it via findWorldsForOwner during onboarding.
+        // This also handles worlds that already exist from a prior session
+        // but were created without ownership metadata.
+        const world = await runtime.getWorld(worldId);
+        if (world) {
+            let needsUpdate = false;
+            if (!world.metadata) {
+                world.metadata = {};
+                needsUpdate = true;
+            }
+            if (!world.metadata.ownership ||
+                typeof world.metadata.ownership !== "object" ||
+                world.metadata.ownership.ownerId !== userId) {
+                world.metadata.ownership = { ownerId: userId };
+                needsUpdate = true;
+            }
+            if (needsUpdate) {
+                await runtime.updateWorld(world);
+            }
+        }
+    }
+    catch (err) {
+        logger.warn(`[milady] Could not establish chat room, retrying with fresh IDs: ${formatError(err)}`);
+        // Fall back to unique IDs if deterministic ones conflict with stale data.
+        // IMPORTANT: reassign roomId so the message loop below uses the same room.
+        roomId = crypto.randomUUID();
+        const freshWorldId = crypto.randomUUID();
+        const freshServerId = crypto.randomUUID();
+        try {
+            await runtime.ensureConnection({
+                entityId: userId,
+                roomId,
+                worldId: freshWorldId,
+                userName: "User",
+                source: "cli",
+                channelId: `${agentName}-chat`,
+                type: ChannelType.DM,
+                messageServerId: freshServerId,
+                metadata: { ownership: { ownerId: userId } },
+            });
+            // Same ownership metadata fix for the fallback world.
+            const fallbackWorld = await runtime.getWorld(freshWorldId);
+            if (fallbackWorld) {
+                let needsUpdate = false;
+                if (!fallbackWorld.metadata) {
+                    fallbackWorld.metadata = {};
+                    needsUpdate = true;
+                }
+                if (!fallbackWorld.metadata.ownership ||
+                    typeof fallbackWorld.metadata.ownership !== "object" ||
+                    fallbackWorld.metadata.ownership.ownerId !==
+                        userId) {
+                    fallbackWorld.metadata.ownership = { ownerId: userId };
+                    needsUpdate = true;
+                }
+                if (needsUpdate) {
+                    await runtime.updateWorld(fallbackWorld);
+                }
+            }
+        }
+        catch (retryErr) {
+            logger.error(`[milady] Chat room setup failed after retry: ${formatError(retryErr)}`);
+            throw retryErr;
+        }
+    }
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    console.log(`\n💬 Chat with ${agentName} (type 'exit' to quit)\n`);
+    const prompt = () => {
+        rl.question("You: ", async (input) => {
+            const text = input.trim();
+            if (text.toLowerCase() === "exit" || text.toLowerCase() === "quit") {
+                console.log("\nGoodbye!");
+                rl.close();
+                try {
+                    await shutdownRuntime(runtime, "cli shutdown");
+                }
+                catch (err) {
+                    logger.warn(`[milady] Error stopping runtime: ${formatError(err)}`);
+                }
+                process.exit(0);
+            }
+            if (!text) {
+                prompt();
+                return;
+            }
+            try {
+                const message = createMessageMemory({
+                    id: crypto.randomUUID(),
+                    entityId: userId,
+                    roomId,
+                    content: {
+                        text,
+                        source: "client_chat",
+                        channelType: ChannelType.DM,
+                    },
+                });
+                process.stdout.write(`${agentName}: `);
+                if (!runtime.messageService) {
+                    logger.error("[milady] runtime.messageService is not available — cannot process messages");
+                    console.log("[Error: message service unavailable]\n");
+                    prompt();
+                    return;
+                }
+                await runtime.messageService.handleMessage(runtime, message, async (content) => {
+                    if (content?.text) {
+                        process.stdout.write(content.text);
+                    }
+                    return [];
+                });
+                console.log("\n");
+            }
+            catch (err) {
+                // Log the error and continue the prompt loop — don't let a single
+                // failed message kill the interactive session.
+                console.log(`\n[Error: ${formatError(err)}]\n`);
+                logger.error(`[milady] Chat message handling failed: ${formatError(err)}`);
+            }
+            prompt();
+        });
+    };
+    prompt();
+}
+// When run directly (not imported), start immediately.
+// Use path.resolve to normalise both sides before comparing so that
+// symlinks, trailing slashes, and relative paths don't cause false negatives.
+const isDirectRun = (() => {
+    const scriptArg = process.argv[1];
+    if (!scriptArg)
+        return false;
+    const normalised = path.resolve(scriptArg);
+    // Exact match against this module's file URL
+    if (import.meta.url === pathToFileURL(normalised).href)
+        return true;
+    // Fallback: match the specific filename (handles tsx rewriting)
+    const base = path.basename(normalised);
+    return base === "eliza.ts" || base === "eliza";
+})();
+if (isDirectRun) {
+    startEliza().catch((err) => {
+        console.error("[milady] Fatal error:", err instanceof Error ? (err.stack ?? err.message) : err);
+        process.exit(1);
+    });
+}