@elizaos/agent 2.0.0-beta.2 → 2.0.11-beta.5

package/api/first-run-routes.js

@@ -0,0 +1,570 @@
+import { logger, stringToUuid } from "@elizaos/core";
+import { asRecord, isCloudInferenceSelectedInConfig, migrateLegacyRuntimeConfig, normalizeDeploymentTargetConfig, normalizeFirstRunCredentialInputs, normalizeLinkedAccountFlagsConfig, normalizeServiceRoutingConfig, PostFirstRunRequestSchema, } from "@elizaos/shared";
+import { configFileExists, loadElizaConfig } from "../config/config.js";
+import { resolveDefaultAgentWorkspaceDir } from "../shared/workspace-resolution.js";
+import { applyCanonicalFirstRunConfig, applyFirstRunCredentialPersistence, } from "./provider-switch-config.js";
+// ---------------------------------------------------------------------------
+// Cloud container character default bootstrapping
+// ---------------------------------------------------------------------------
+/**
+ * Cloud-provisioned containers skip first-run entirely, which means the
+ * character preset (ui.presetId, ui.avatarIndex) and the matching TTS voice
+ * are never written to the config file.  This helper ensures that the first
+ * GET /api/first-run/status from a cloud container writes sensible defaults
+ * so the frontend hydrates with the correct character and voice.
+ *
+ * Only runs once: subsequent requests see ui.presetId already set and bail.
+ */
+let _cloudDefaultsApplied = false;
+function normalizeCanonicalRuntimeConfigForCurrentServer(args) {
+    const llmRoute = args.serviceRouting?.llmText;
+    if (args.deploymentTarget?.runtime !== "remote" ||
+        args.deploymentTarget.provider !== "remote" ||
+        llmRoute?.transport !== "remote" ||
+        !llmRoute.backend ||
+        !args.credentialInputs?.llmApiKey) {
+        return {
+            deploymentTarget: args.deploymentTarget,
+            serviceRouting: args.serviceRouting,
+        };
+    }
+    return {
+        deploymentTarget: { runtime: "local" },
+        serviceRouting: {
+            ...(args.serviceRouting ?? {}),
+            llmText: {
+                backend: llmRoute.backend,
+                transport: "direct",
+                ...(llmRoute.primaryModel
+                    ? { primaryModel: llmRoute.primaryModel }
+                    : {}),
+            },
+        },
+    };
+}
+function ensureCloudContainerCharacterDefaults(ctx) {
+    if (_cloudDefaultsApplied)
+        return;
+    let config;
+    try {
+        config = loadElizaConfig();
+    }
+    catch {
+        return; // No config file yet — nothing to patch
+    }
+    const ui = (config.ui ?? {});
+    if (ui.presetId) {
+        // Already has a character preset — previous first-run or manual config
+        _cloudDefaultsApplied = true;
+        return;
+    }
+    // Resolve the default style preset for the configured language
+    const language = ctx.resolveConfiguredCharacterLanguage(config, ctx.req);
+    const presets = ctx.getStylePresets(language);
+    const defaultPreset = presets[0];
+    if (!defaultPreset) {
+        _cloudDefaultsApplied = true;
+        return;
+    }
+    // Apply the default character to config
+    if (!config.ui)
+        config.ui = {};
+    const configUi = config.ui;
+    configUi.presetId = defaultPreset.id;
+    configUi.avatarIndex = defaultPreset.avatarIndex;
+    if (!configUi.assistant || typeof configUi.assistant !== "object") {
+        configUi.assistant = {};
+    }
+    const assistant = configUi.assistant;
+    if (!assistant.name) {
+        assistant.name = defaultPreset.name;
+    }
+    // Apply the matching voice preset so TTS uses the correct voice.
+    // First try the standard path (requires ELEVENLABS_API_KEY for direct mode).
+    ctx.applyFirstRunVoicePreset(config, { presetId: defaultPreset.id, avatarIndex: defaultPreset.avatarIndex }, language);
+    // Cloud containers typically use cloud-proxy TTS without a direct API key.
+    // If applyFirstRunVoicePreset bailed (no ELEVENLABS_API_KEY), write the
+    // voice config anyway so resolveCharacterVoiceConfigFromAppConfig on the
+    // client picks up the correct voiceId via the ui.presetId -> preset lookup.
+    // The client-side voice resolver reads config.ui.presetId and maps it to the
+    // character's voicePresetId, so having presetId set is sufficient.
+    // Ensure serviceRouting is set for cloud inference so the cloud topology
+    // resolver recognises this as a cloud-inference container and keeps the
+    // ELIZAOS_CLOUD_* env vars alive (applyCloudConfigToEnv deletes them when
+    // shouldLoadPlugin is false).
+    const configRecord = config;
+    if (!configRecord.serviceRouting) {
+        configRecord.serviceRouting = {
+            llmText: { backend: "elizacloud", transport: "cloud-proxy" },
+            tts: { backend: "elizacloud", transport: "cloud-proxy" },
+        };
+    }
+    // Ensure agent list has the default character's personality
+    if (!config.agents || typeof config.agents !== "object") {
+        config.agents = {};
+    }
+    const agents = config.agents;
+    if (!Array.isArray(agents.list) || agents.list.length === 0) {
+        agents.list = [{ id: "main", default: true }];
+    }
+    const agentEntry = agents.list[0];
+    if (!agentEntry.name && defaultPreset.name) {
+        agentEntry.name = defaultPreset.name;
+    }
+    if (!agentEntry.bio && defaultPreset.bio) {
+        agentEntry.bio = defaultPreset.bio;
+    }
+    if (!agentEntry.system && defaultPreset.system) {
+        agentEntry.system = defaultPreset.system;
+    }
+    try {
+        ctx.saveElizaConfig(config);
+        logger.info(`[first-run] Applied default character preset "${defaultPreset.id}" for cloud container`);
+    }
+    catch (err) {
+        logger.warn(`[first-run] Failed to persist cloud container character defaults: ${err}`);
+    }
+    _cloudDefaultsApplied = true;
+}
+// ---------------------------------------------------------------------------
+// Route handler
+// ---------------------------------------------------------------------------
+export async function handleFirstRunRoutes(ctx) {
+    const { req, res, method, pathname, state, json, error, readJsonBody } = ctx;
+    // ── GET /api/first-run/status ──────────────────────────────────────
+    if (method === "GET" && pathname === "/api/first-run/status") {
+        if (ctx.isCloudProvisionedContainer()) {
+            // Ensure the config file has the default character preset + voice so
+            // the frontend hydrates with the correct character instead of a bare
+            // fallback.  This is idempotent and only writes once.
+            ensureCloudContainerCharacterDefaults(ctx);
+            json(res, { complete: true, cloudProvisioned: true });
+            return true;
+        }
+        let config = state.config;
+        let complete = configFileExists() && ctx.hasPersistedFirstRunState(config);
+        if (!complete && configFileExists()) {
+            try {
+                config = loadElizaConfig();
+                complete = ctx.hasPersistedFirstRunState(config);
+                if (complete) {
+                    state.config = config;
+                }
+            }
+            catch (err) {
+                logger.warn(`[eliza-api] Failed to refresh config for first-run status: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        json(res, { complete });
+        return true;
+    }
+    // ── GET /api/wallet/keys (first-run only) ─────────────────────────
+    if (method === "GET" && pathname === "/api/wallet/keys") {
+        if (ctx.hasPersistedFirstRunState(state.config)) {
+            json(res, { error: "Wallet keys are only available during first-run" }, 403);
+            return true;
+        }
+        logger.warn(`[eliza-api] Wallet keys requested during first-run (ip=${req.socket.remoteAddress ?? "unknown"})`);
+        ctx.ensureWalletKeysInEnvAndConfig(state.config);
+        try {
+            ctx.saveElizaConfig(state.config);
+        }
+        catch {
+            // Non-fatal
+        }
+        const evmPrivateKey = process.env.EVM_PRIVATE_KEY ?? "";
+        const solanaPrivateKey = process.env.SOLANA_PRIVATE_KEY ?? "";
+        const addresses = ctx.getWalletAddresses();
+        const maskKey = (key) => {
+            if (!key || key.length <= 4)
+                return key ? "****" : "";
+            return `****${key.slice(-4)}`;
+        };
+        json(res, {
+            evmPrivateKey: maskKey(evmPrivateKey),
+            evmAddress: addresses.evmAddress ?? "",
+            solanaPrivateKey: maskKey(solanaPrivateKey),
+            solanaAddress: addresses.solanaAddress ?? "",
+        });
+        return true;
+    }
+    // ── GET /api/first-run/options ─────────────────────────────────────
+    if (method === "GET" && pathname === "/api/first-run/options") {
+        json(res, {
+            names: ctx.pickRandomNames(5),
+            styles: ctx.getStylePresets(ctx.resolveConfiguredCharacterLanguage(state.config, req)),
+            providers: ctx.getProviderOptions(),
+            cloudProviders: ctx.getCloudProviderOptions(),
+            models: ctx.getModelOptions(),
+            inventoryProviders: ctx.getInventoryProviderOptions(),
+            sharedStyleRules: "Keep responses brief. Be helpful and concise.",
+            githubOAuthAvailable: Boolean(process.env.GITHUB_OAUTH_CLIENT_ID?.trim()),
+        });
+        return true;
+    }
+    // ── POST /api/first-run ────────────────────────────────────────────
+    if (method === "POST" && pathname === "/api/first-run") {
+        const rawFirstRun = await readJsonBody(req, res);
+        if (rawFirstRun === null)
+            return true;
+        const parsedFirstRun = PostFirstRunRequestSchema.safeParse(rawFirstRun);
+        if (!parsedFirstRun.success) {
+            error(res, parsedFirstRun.error.issues[0]?.message ?? "Invalid request body", 400);
+            return true;
+        }
+        const body = parsedFirstRun.data;
+        let config = state.config;
+        try {
+            config = loadElizaConfig();
+        }
+        catch (err) {
+            logger.warn(`[eliza-api] Failed to reload config before first-run: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const configuredLanguage = ctx.normalizeCharacterLanguage(body.language ??
+            ctx.readUiLanguageHeader(req) ??
+            config.ui?.language);
+        if (!config.agents)
+            config.agents = {};
+        if (!config.agents.defaults)
+            config.agents.defaults = {};
+        config.agents.defaults.workspace = resolveDefaultAgentWorkspaceDir();
+        const firstRunAdminEntityId = stringToUuid(`${body.name.trim()}-admin-entity`);
+        config.agents.defaults.adminEntityId = firstRunAdminEntityId;
+        state.adminEntityId = firstRunAdminEntityId;
+        state.chatUserId = firstRunAdminEntityId;
+        state.chatConnectionReady = null;
+        state.chatConnectionPromise = null;
+        if (!config.agents.list)
+            config.agents.list = [];
+        if (config.agents.list.length === 0) {
+            config.agents.list.push({ id: "main", default: true });
+        }
+        const agent = config.agents.list[0];
+        agent.name = body.name.trim();
+        agent.workspace = resolveDefaultAgentWorkspaceDir();
+        let normalizedMessageExamples;
+        if (body.bio)
+            agent.bio = body.bio;
+        if (body.systemPrompt)
+            agent.system = body.systemPrompt;
+        if (body.style)
+            agent.style = body.style;
+        if (body.adjectives)
+            agent.adjectives = body.adjectives;
+        if (body.topics) {
+            agent.topics = body.topics;
+        }
+        if (body.postExamples)
+            agent.postExamples = body.postExamples;
+        if (body.messageExamples) {
+            const raw = body.messageExamples;
+            normalizedMessageExamples = raw.map((item) => {
+                if (item &&
+                    typeof item === "object" &&
+                    "examples" in item) {
+                    return item;
+                }
+                const arr = item;
+                return {
+                    examples: arr.map((m) => ({
+                        name: m.name ?? m.user ?? "",
+                        content: m.content,
+                    })),
+                };
+            });
+            agent.messageExamples = normalizedMessageExamples;
+        }
+        if (!config.ui) {
+            config.ui = {};
+        }
+        config.ui.assistant = {
+            ...(config.ui.assistant ?? {}),
+            name: agent.name,
+        };
+        if (typeof body.avatarIndex === "number" &&
+            Number.isFinite(body.avatarIndex)) {
+            config.ui.avatarIndex = Number(body.avatarIndex);
+        }
+        config.ui.language = configuredLanguage;
+        if (typeof body.presetId === "string" && body.presetId.trim()) {
+            config.ui.presetId = body.presetId.trim();
+        }
+        ctx.applyFirstRunVoicePreset(config, body, configuredLanguage);
+        // ── Theme preference ──────────────────────────────────────────────────
+        if (body.theme) {
+            if (!config.ui)
+                config.ui = {};
+            config.ui.theme = body.theme;
+        }
+        const explicitDeploymentTargetRequested = Object.hasOwn(body, "deploymentTarget");
+        const explicitDeploymentTarget = explicitDeploymentTargetRequested
+            ? normalizeDeploymentTargetConfig(body.deploymentTarget)
+            : null;
+        if (explicitDeploymentTargetRequested && !explicitDeploymentTarget) {
+            error(res, "Invalid deploymentTarget", 400);
+            return true;
+        }
+        const explicitLinkedAccountsRequested = Object.hasOwn(body, "linkedAccounts");
+        const explicitLinkedAccounts = explicitLinkedAccountsRequested
+            ? normalizeLinkedAccountFlagsConfig(body.linkedAccounts)
+            : null;
+        const explicitServiceRoutingRequested = Object.hasOwn(body, "serviceRouting");
+        const explicitServiceRouting = explicitServiceRoutingRequested
+            ? normalizeServiceRoutingConfig(body.serviceRouting)
+            : null;
+        const explicitCredentialInputsRequested = Object.hasOwn(body, "credentialInputs");
+        const explicitCredentialInputs = explicitCredentialInputsRequested
+            ? normalizeFirstRunCredentialInputs(body.credentialInputs)
+            : null;
+        if (explicitCredentialInputsRequested && !explicitCredentialInputs) {
+            error(res, "Invalid credentialInputs", 400);
+            return true;
+        }
+        const hasCanonicalRuntimeConfig = explicitDeploymentTargetRequested ||
+            explicitLinkedAccountsRequested ||
+            explicitServiceRoutingRequested ||
+            explicitCredentialInputsRequested;
+        const normalizedCanonicalRuntimeConfig = normalizeCanonicalRuntimeConfigForCurrentServer({
+            deploymentTarget: explicitDeploymentTarget,
+            serviceRouting: explicitServiceRouting,
+            credentialInputs: explicitCredentialInputs,
+        });
+        const normalizedDeploymentTarget = normalizedCanonicalRuntimeConfig.deploymentTarget;
+        const normalizedServiceRouting = normalizedCanonicalRuntimeConfig.serviceRouting;
+        // ── Sandbox mode (from first-run runtime setup: off / light / standard / max)
+        const sandboxMode = body.sandboxMode || "off";
+        if (sandboxMode !== "off") {
+            if (!config.agents)
+                config.agents = {};
+            if (!config.agents.defaults)
+                config.agents.defaults = {};
+            if (!config.agents.defaults.sandbox) {
+                config.agents.defaults.sandbox = {};
+            }
+            config.agents.defaults.sandbox.mode = sandboxMode;
+            logger.info(`[eliza-api] Sandbox mode set to: ${sandboxMode}`);
+        }
+        if (hasCanonicalRuntimeConfig) {
+            applyCanonicalFirstRunConfig(config, {
+                deploymentTarget: normalizedDeploymentTarget,
+                linkedAccounts: explicitLinkedAccounts,
+                serviceRouting: normalizedServiceRouting,
+                clearRoutes: explicitServiceRoutingRequested && !normalizedServiceRouting?.llmText
+                    ? ["llmText"]
+                    : [],
+            });
+            await applyFirstRunCredentialPersistence(config, {
+                credentialInputs: explicitCredentialInputs,
+                deploymentTarget: normalizedDeploymentTarget ??
+                    normalizeDeploymentTargetConfig(config.deploymentTarget),
+                serviceRouting: normalizedServiceRouting ??
+                    normalizeServiceRoutingConfig(config.serviceRouting),
+            });
+            delete process.env.ELIZAOS_CLOUD_ENABLED;
+            delete process.env.ELIZAOS_CLOUD_NANO_MODEL;
+            delete process.env.ELIZAOS_CLOUD_MEDIUM_MODEL;
+            delete process.env.ELIZAOS_CLOUD_SMALL_MODEL;
+            delete process.env.ELIZAOS_CLOUD_LARGE_MODEL;
+            delete process.env.ELIZAOS_CLOUD_MEGA_MODEL;
+            delete process.env.ELIZAOS_CLOUD_RESPONSE_HANDLER_MODEL;
+            delete process.env.ELIZAOS_CLOUD_SHOULD_RESPOND_MODEL;
+            delete process.env.ELIZAOS_CLOUD_ACTION_PLANNER_MODEL;
+            delete process.env.ELIZAOS_CLOUD_PLANNER_MODEL;
+            if (config.models && typeof config.models === "object") {
+                const legacyModels = config.models;
+                delete legacyModels.nano;
+                delete config.models.small;
+                delete legacyModels.medium;
+                delete config.models.large;
+                delete legacyModels.mega;
+            }
+            if (!isCloudInferenceSelectedInConfig(config)) {
+                delete process.env.ELIZAOS_CLOUD_API_KEY;
+            }
+        }
+        if (hasCanonicalRuntimeConfig && config.agents.defaults.model) {
+            delete config.agents.defaults.model.primary;
+        }
+        // ── GitHub token ────────────────────────────────────────────────────
+        if (body.githubToken &&
+            typeof body.githubToken === "string" &&
+            body.githubToken.trim()) {
+            if (!config.env)
+                config.env = {};
+            config.env.GITHUB_TOKEN =
+                body.githubToken.trim();
+            process.env.GITHUB_TOKEN = body.githubToken.trim();
+        }
+        // ── Connectors (Telegram, Discord, WhatsApp, Twilio, Blooio) ────────
+        if (!config.connectors)
+            config.connectors = {};
+        const explicitConnectors = asRecord(body.connectors);
+        if (explicitConnectors) {
+            for (const [connectorName, connectorValue] of Object.entries(explicitConnectors)) {
+                const nextConnector = asRecord(connectorValue);
+                if (!nextConnector) {
+                    continue;
+                }
+                const currentConnector = asRecord(config.connectors[connectorName]);
+                config.connectors[connectorName] = {
+                    ...(currentConnector ?? {}),
+                    ...nextConnector,
+                };
+            }
+        }
+        if (body.telegramToken &&
+            typeof body.telegramToken === "string" &&
+            body.telegramToken.trim()) {
+            config.connectors.telegram = { botToken: body.telegramToken.trim() };
+        }
+        if (body.discordToken &&
+            typeof body.discordToken === "string" &&
+            body.discordToken.trim()) {
+            config.connectors.discord = { token: body.discordToken.trim() };
+        }
+        if (body.whatsappSessionPath &&
+            typeof body.whatsappSessionPath === "string" &&
+            body.whatsappSessionPath.trim()) {
+            config.connectors.whatsapp = {
+                sessionPath: body.whatsappSessionPath.trim(),
+            };
+        }
+        if (body.twilioAccountSid &&
+            typeof body.twilioAccountSid === "string" &&
+            body.twilioAccountSid.trim() &&
+            body.twilioAuthToken &&
+            typeof body.twilioAuthToken === "string" &&
+            body.twilioAuthToken.trim()) {
+            if (!config.env)
+                config.env = {};
+            config.env.TWILIO_ACCOUNT_SID = body.twilioAccountSid.trim();
+            config.env.TWILIO_AUTH_TOKEN = body.twilioAuthToken.trim();
+            process.env.TWILIO_ACCOUNT_SID = body.twilioAccountSid.trim();
+            process.env.TWILIO_AUTH_TOKEN = body.twilioAuthToken.trim();
+            if (body.twilioPhoneNumber &&
+                typeof body.twilioPhoneNumber === "string" &&
+                body.twilioPhoneNumber.trim()) {
+                config.env.TWILIO_PHONE_NUMBER = body.twilioPhoneNumber.trim();
+                process.env.TWILIO_PHONE_NUMBER = body.twilioPhoneNumber.trim();
+            }
+        }
+        if (body.blooioApiKey &&
+            typeof body.blooioApiKey === "string" &&
+            body.blooioApiKey.trim()) {
+            if (!config.env)
+                config.env = {};
+            const trimmedKey = body.blooioApiKey.trim();
+            config.env.BLOOIO_API_KEY = trimmedKey;
+            process.env.BLOOIO_API_KEY = trimmedKey;
+            const blooioConnector = { apiKey: trimmedKey };
+            if (body.blooioPhoneNumber &&
+                typeof body.blooioPhoneNumber === "string" &&
+                body.blooioPhoneNumber.trim()) {
+                const trimmedPhone = body.blooioPhoneNumber.trim();
+                config.env.BLOOIO_PHONE_NUMBER =
+                    trimmedPhone;
+                process.env.BLOOIO_PHONE_NUMBER = trimmedPhone;
+                blooioConnector.fromNumber = trimmedPhone;
+            }
+            config.connectors.blooio = blooioConnector;
+        }
+        const explicitFeatures = asRecord(body.features);
+        if (explicitFeatures) {
+            config.features = {
+                ...(asRecord(config.features) ?? {}),
+                ...explicitFeatures,
+            };
+        }
+        // ── Inventory / RPC providers ─────────────────────────────────────────
+        if (Array.isArray(body.inventoryProviders)) {
+            if (!config.env)
+                config.env = {};
+            const allInventory = ctx.getInventoryProviderOptions();
+            for (const inv of body.inventoryProviders) {
+                const chainDef = allInventory.find((ip) => ip.id === inv.chain);
+                if (!chainDef)
+                    continue;
+                const rpcDef = chainDef.rpcProviders.find((rp) => rp.id === inv.rpcProvider);
+                if (rpcDef?.envKey && inv.rpcApiKey) {
+                    config.env[rpcDef.envKey] = inv.rpcApiKey;
+                    process.env[rpcDef.envKey] = inv.rpcApiKey;
+                }
+            }
+        }
+        // ── Ensure wallet keys exist so inventory can resolve addresses ───────
+        ctx.ensureWalletKeysInEnvAndConfig(config);
+        if (!config.meta) {
+            config.meta = {};
+        }
+        config.meta.firstRunComplete = true;
+        if (state.runtime) {
+            const runtimeCharacter = state.runtime.character;
+            const agentTopics = agent.topics;
+            runtimeCharacter.name = agent.name ?? runtimeCharacter.name;
+            if (Array.isArray(agent.bio)) {
+                runtimeCharacter.bio = [...agent.bio];
+            }
+            if (typeof agent.system === "string" && agent.system) {
+                runtimeCharacter.system = agent.system;
+            }
+            if (Array.isArray(agent.adjectives)) {
+                runtimeCharacter.adjectives = [...agent.adjectives];
+            }
+            if (Array.isArray(agentTopics)) {
+                runtimeCharacter.topics = [...agentTopics];
+            }
+            if (agent.style) {
+                runtimeCharacter.style = JSON.parse(JSON.stringify(agent.style));
+            }
+            if (normalizedMessageExamples) {
+                runtimeCharacter.messageExamples = normalizedMessageExamples;
+            }
+            if (Array.isArray(agent.postExamples)) {
+                runtimeCharacter.postExamples = [...agent.postExamples];
+            }
+            try {
+                await state.runtime.updateAgent(state.runtime.agentId, {
+                    name: runtimeCharacter.name,
+                    metadata: {
+                        ...runtimeCharacter.metadata,
+                        character: {
+                            name: runtimeCharacter.name,
+                            bio: runtimeCharacter.bio,
+                            system: runtimeCharacter.system,
+                            adjectives: runtimeCharacter.adjectives,
+                            topics: runtimeCharacter.topics,
+                            style: runtimeCharacter.style,
+                            messageExamples: runtimeCharacter.messageExamples,
+                            postExamples: runtimeCharacter.postExamples,
+                        },
+                    },
+                });
+            }
+            catch (err) {
+                logger.warn(`[character-db] Failed to persist first-run character to DB: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        state.config = config;
+        state.agentName = body.name ?? state.agentName;
+        migrateLegacyRuntimeConfig(config);
+        try {
+            ctx.saveElizaConfig(config);
+        }
+        catch (err) {
+            logger.error(`[eliza-api] Failed to save config after first-run: ${err}`);
+            error(res, "Failed to save configuration", 500);
+            return true;
+        }
+        if (!configFileExists()) {
+            logger.error(`[eliza-api] Config file does not exist after save — first-run data will be lost on restart`);
+            error(res, "Configuration file was not persisted to disk", 500);
+            return true;
+        }
+        const resolvedRuntime = normalizeDeploymentTargetConfig(config.deploymentTarget)?.runtime ??
+            "local";
+        logger.info(`[eliza-api] First run complete for agent "${body.name}" (runtime: ${resolvedRuntime})`);
+        json(res, { ok: true });
+        return true;
+    }
+    return false;
+}

package/api/health-routes.d.ts

@@ -0,0 +1,58 @@
+import type http from "node:http";
+import type { AgentRuntime } from "@elizaos/core";
+import type { ElizaConfig } from "../config/config.ts";
+import type { ConnectorHealthMonitor } from "./connector-health.ts";
+interface PluginEntryLike {
+    enabled: boolean;
+    configured: boolean;
+    isActive?: boolean;
+    loadError?: string | null;
+}
+interface AgentStartupDiagnostics {
+    phase: string;
+    attempt: number;
+    lastError?: string;
+    lastErrorAt?: number;
+    nextRetryAt?: number;
+}
+export interface HealthRouteState {
+    runtime: AgentRuntime | null;
+    config: ElizaConfig;
+    agentState: string;
+    agentName: string;
+    model: string | undefined;
+    startedAt: number | undefined;
+    startup: AgentStartupDiagnostics;
+    plugins: PluginEntryLike[];
+    pendingRestartReasons: string[];
+    connectorHealthMonitor: ConnectorHealthMonitor | null;
+}
+export interface HealthRouteContext {
+    req: http.IncomingMessage;
+    res: http.ServerResponse;
+    method: string;
+    pathname: string;
+    url: URL;
+    state: HealthRouteState;
+    json: (res: http.ServerResponse, data: unknown, status?: number) => void;
+    error: (res: http.ServerResponse, message: string, status?: number) => void;
+}
+/**
+ * "First-turn capability online": the agent can actually produce a response.
+ *
+ * Distinct from `ready` (which is `true` even for stopped/error/paused states —
+ * it only negates `starting`/`restarting`). `canRespond` ANDs a live runtime, a
+ * `running` state, AND a registered TEXT_GENERATION handler — so it is `false`
+ * when no model provider is wired (local-inference is optional) and only flips
+ * `true` at the exact moment the agent can answer a first turn. This is the
+ * signal the UI uses to fade in first-turn capability: the shell paints early
+ * (agentState "starting"), and the composer goes live when this flips.
+ */
+export declare function computeCanRespond(runtime: AgentRuntime | null, agentState: string): boolean;
+/**
+ * Handle health / status / runtime introspection routes.
+ * Returns `true` if the request was handled.
+ */
+export declare function handleHealthRoutes(ctx: HealthRouteContext): Promise<boolean>;
+export {};
+//# sourceMappingURL=health-routes.d.ts.map

package/api/health-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-routes.d.ts","sourceRoot":"","sources":["../../src/api/health-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AA4CpE,UAAU,eAAe;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,UAAU,uBAAuB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,uBAAuB,CAAC;IACjC,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,sBAAsB,EAAE,sBAAsB,GAAG,IAAI,CAAC;CACvD;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,IAAI,CAAC,eAAe,CAAC;IAC1B,GAAG,EAAE,IAAI,CAAC,cAAc,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;IACT,KAAK,EAAE,gBAAgB,CAAC;IACxB,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzE,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7E;AA2WD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,GAAG,IAAI,EAC5B,UAAU,EAAE,MAAM,GACjB,OAAO,CAST;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,kBAAkB,GACtB,OAAO,CAAC,OAAO,CAAC,CA6RlB"}