@elizaos/app-core 2.0.0-beta.2 → 2.0.11-beta.5

package/api/server.js

@@ -1,66 +1,89 @@
-import "@elizaos/shared";
 import fs from "node:fs";
 import http from "node:http";
 import { createRequire } from "node:module";
 import path from "node:path";
-import { AGENT_EVENT_ALLOWED_STREAMS, CONFIG_WRITE_ALLOWED_TOP_KEYS, clearPersistedOnboardingConfig, cloneWithoutBlockedObjectKeys, discoverInstalledPlugins, discoverPluginsFromManifest, extractAuthToken, fetchWithTimeoutGuard, handleCloudBillingRoute, handleCloudCompatRoute, initStewardWalletCache, isAllowedHost, isAuthorized, loadElizaConfig, normalizeWsClientId, persistConversationRoomTitle, resolveDefaultAgentWorkspaceDir, resolveMcpServersRejection, resolvePluginConfigMutationRejections, resolveUserPath, routeAutonomyTextToUser, saveElizaConfig, streamResponseBodyWithByteLimit, startApiServer as upstreamStartApiServer, validateMcpServerConfig, } from "@elizaos/agent";
+import { AGENT_EVENT_ALLOWED_STREAMS, CONFIG_WRITE_ALLOWED_TOP_KEYS, clearPersistedFirstRunConfig, cloneWithoutBlockedObjectKeys, discoverInstalledPlugins, discoverPluginsFromManifest, extractAuthToken, fetchWithTimeoutGuard, handleCloudBillingRoute, handleCloudCompatRoute, isAllowedHost, isAuthorized, loadElizaConfig, normalizeWsClientId, persistConversationRoomTitle, resolveDefaultAgentWorkspaceDir, resolveMcpServersRejection, resolvePluginConfigMutationRejections, resolveUserPath, routeAutonomyTextToUser, saveElizaConfig, streamResponseBodyWithByteLimit, startApiServer as upstreamStartApiServer, validateMcpServerConfig, } from "@elizaos/agent";
 // Override the wallet export rejection function with the hardened version
 // that adds rate limiting, audit logging, and a forced confirmation delay.
 import { logger, resolveStateDir } from "@elizaos/core";
-import { resolveLinkedAccountsInConfig } from "@elizaos/shared";
+import { resolveLinkedAccountsInConfig } from "@elizaos/shared/contracts/first-run-options";
+import { forwardRemoteCloudMutation } from "../runtime/mode/remote-forwarder.js";
+import { applyRouteModeGuard } from "../runtime/mode/route-mode-guard.js";
 import { ensureCompatSensitiveRouteAuthorized, ensureRouteAuthorized, } from "./auth.js";
-import { handleAutomationsCompatRoutes } from "./automations-compat-routes";
-import { clearCompatRuntimeRestart, getConfiguredCompatAgentName, } from "./compat-route-shared";
-import { sendJson as sendJsonResponse } from "./response";
-import { applyRouteModeGuard } from "../runtime/mode/route-mode-guard";
-import { forwardRemoteCloudMutation } from "../runtime/mode/remote-forwarder";
-import { handleRuntimeModeRoute } from "./runtime-mode-routes";
-export { __resetCloudBaseUrlCache, ensureCloudTtsApiKeyAlias, resolveCloudTtsBaseUrl, resolveElevenLabsApiKeyForCloudMode, } from "@elizaos/plugin-elizacloud";
-export { DATABASE_UNAVAILABLE_MESSAGE, getConfiguredCompatAgentName, hasCompatPersistedOnboardingState, isLoopbackRemoteAddress, readCompatJsonBody, } from "./compat-route-shared";
-export { filterConfigEnvForResponse, SENSITIVE_ENV_RESPONSE_KEYS, } from "./server-config-filter";
-export { buildCorsAllowedPorts, invalidateCorsAllowedPorts, } from "./server-cors";
-export { injectApiBaseIntoHtml } from "./server-html";
-// Re-export helpers from split-out modules so tests can import from "./server"
-export { ensureApiTokenForBindHost, resolveMcpTerminalAuthorizationRejection, resolveTerminalRunClientId, resolveTerminalRunRejection, resolveWebSocketUpgradeRejection, } from "./server-security";
-export { findOwnPackageRoot, isSafeResetStateDir, resolveCorsOrigin, } from "./server-startup";
-export { resolveWalletExportRejection } from "./server-wallet-trade";
+import { handleAutomationsCompatRoutes } from "./automations-compat-routes.js";
+import { clearCompatRuntimeRestart, getConfiguredCompatAgentName, } from "./compat-route-shared.js";
+import { sendJson as sendJsonResponse } from "./response.js";
+import { handleRuntimeModeRoute } from "./runtime-mode-routes.js";
+export { __resetCloudBaseUrlCache, ensureCloudTtsApiKeyAlias, resolveCloudTtsBaseUrl, resolveElevenLabsApiKeyForCloudMode, } from "@elizaos/shared/elizacloud/server-cloud-tts";
+export { DATABASE_UNAVAILABLE_MESSAGE, getConfiguredCompatAgentName, hasCompatPersistedFirstRunState, isLoopbackRemoteAddress, readCompatJsonBody, } from "./compat-route-shared.js";
+export { filterConfigEnvForResponse, SENSITIVE_ENV_RESPONSE_KEYS, } from "./server-config-filter.js";
+export { buildCorsAllowedPorts, invalidateCorsAllowedPorts, } from "./server-cors.js";
+export { injectApiBaseIntoHtml } from "./server-html.js";
+// Re-export helpers from split-out modules so tests can import from "./server.js"
+export { ensureApiTokenForBindHost, resolveMcpTerminalAuthorizationRejection, resolveTerminalRunClientId, resolveTerminalRunRejection, resolveWebSocketUpgradeRejection, } from "./server-security.js";
+export { findOwnPackageRoot, isSafeResetStateDir, resolveCorsOrigin, } from "./server-startup.js";
+export { resolveWalletExportRejection } from "./server-wallet-trade.js";
 export { AGENT_EVENT_ALLOWED_STREAMS, CONFIG_WRITE_ALLOWED_TOP_KEYS, cloneWithoutBlockedObjectKeys, discoverInstalledPlugins, discoverPluginsFromManifest, extractAuthToken, fetchWithTimeoutGuard, isAllowedHost, isAuthorized, normalizeWsClientId, persistConversationRoomTitle, resolveMcpServersRejection, resolvePluginConfigMutationRejections, routeAutonomyTextToUser, streamResponseBodyWithByteLimit, validateMcpServerConfig, };
-import { ensureRuntimeSqlCompatibility, executeRawSql, isElizaSettingsDebugEnabled, sanitizeIdentifier, settingsDebugCloudSummary, sqlLiteral, } from "@elizaos/shared";
-import { buildCharacterFromConfig } from "../runtime/build-character-from-config";
-import { deviceBridge } from "../services/local-inference/device-bridge";
-import { handleAuthBootstrapRoutes } from "./auth-bootstrap-routes";
-import { handleAuthPairingCompatRoutes } from "./auth-pairing-compat-routes";
-import { handleAuthSessionRoutes } from "./auth-session-routes";
-import { handleCatalogRoutes } from "./catalog-routes";
-import { handleDatabaseRowsCompatRoute } from "./database-rows-compat-routes";
-import { handleDevCompatRoutes } from "./dev-compat-routes";
-// Local-inference routes intentionally remain in app-core (no plugin-local-inference exists).
-import { handleLocalInferenceCompatRoutes } from "./local-inference-compat-routes";
-import { handleOnboardingCompatRoute } from "./onboarding-compat-routes";
-import { handlePluginsCompatRoutes } from "./plugins-compat-routes";
-import { handleSecretsInventoryRoute } from "./secrets-inventory-routes";
-import { handleSecretsManagerRoute } from "./secrets-manager-routes";
-import { getCorsAllowedPorts, isAllowedOrigin } from "./server-cors";
+// Lazy reference to @elizaos/plugin-local-inference/routes — avoids a static
+// boundary violation. The module is memoized by the JS engine after the first
+// await so per-request cost is a single Map lookup after warm-up.
+let _localInferenceRoutes;
+async function getLocalInferenceRoutes() {
+    if (!_localInferenceRoutes) {
+        _localInferenceRoutes = await import("@elizaos/plugin-local-inference/routes");
+    }
+    return _localInferenceRoutes;
+}
+import { isElizaSettingsDebugEnabled, settingsDebugCloudSummary, } from "@elizaos/shared/settings-debug";
+import { ensureRuntimeSqlCompatibility, executeRawSql, sanitizeIdentifier, sqlLiteral, } from "@elizaos/shared/utils/sql-compat";
+import { buildCharacterFromConfig } from "../runtime/build-character-from-config.js";
+import { handleAuthBootstrapRoutes } from "./auth-bootstrap-routes.js";
+import { handleAuthPairingCompatRoutes } from "./auth-pairing-routes.js";
+import { handleAuthSessionRoutes } from "./auth-session-routes.js";
+import { handleBackgroundTasksRoute } from "./background-tasks-routes.js";
+import { handleCatalogRoutes } from "./catalog-routes.js";
+import { handleCloudPairRoute } from "./cloud-pair-route.js";
+import { handleDatabaseRowsCompatRoute } from "./database-rows-compat-routes.js";
+import { handleDevCompatRoutes } from "./dev-compat-routes.js";
+import { handleFirstRunRoute } from "./first-run-routes.js";
+import { handleFirstRunTtsRoute } from "./first-run-tts-route.js";
+import { handleInternalWakeRoute } from "./internal-routes.js";
+import { isPerfInstrumentEnabled, normalizeRouteKey, recordRouteTiming, } from "./perf-instrument.js";
+import { handleSecretsInventoryRoute } from "./secrets-inventory-routes.js";
+import { handleSecretsManagerRoute } from "./secrets-manager-routes.js";
+import { handleSensitiveRequestRoutes } from "./sensitive-request-routes.js";
+import { getCorsAllowedPorts, isAllowedOrigin } from "./server-cors.js";
 // Wallet market overview route extracted to @elizaos/plugin-wallet/routes/wallet-market-overview-route.
 // Now served via walletRoutePlugin.routes (rawPath) on the runtime plugin route system.
 // Phase 2 extraction: Steward compat routes → app-steward/src/plugin.ts (stewardPlugin)
 // Includes: handleWalletBrowserCompatRoutes, handleWalletTradeCompatRoutes,
 //           handleStewardCompatRoutes, handleWalletCompatRoutes
-import { handleWorkbenchCompatRoutes } from "./workbench-compat-routes";
+import { handleWorkbenchCompatRoutes } from "./workbench-compat-routes.js";
 const _require = createRequire(import.meta.url);
-import { syncAppEnvToEliza, syncElizaEnvAliases } from "@elizaos/shared";
+import { syncAppEnvToEliza, syncElizaEnvAliases, } from "@elizaos/shared/utils/env";
 // Lazy-imported to avoid circular dependency with runtime/eliza.ts
 const lazyEnsureTTS = () => import("../runtime/ensure-text-to-speech-handler.js").then((m) => m.ensureTextToSpeechHandler);
-import { clearCloudSecrets, getCloudSecret } from "@elizaos/plugin-elizacloud";
+const _LOCAL_TTS_PROVIDER_IDS = [
+    "eliza-local-inference",
+    "capacitor-llama",
+    "eliza-device-bridge",
+    "eliza-aosp-llama",
+];
+let pluginRegistryApiPromise;
+function getPluginRegistryApi() {
+    pluginRegistryApiPromise ??= import("@elizaos/plugin-registry");
+    return pluginRegistryApiPromise;
+}
+import { clearCloudSecrets, getCloudSecret, } from "@elizaos/shared/elizacloud/cloud-secrets";
 import { getStartupEmbeddingAugmentation } from "../runtime/startup-overlay.js";
-import { hydrateWalletKeysFromNodePlatformSecureStore } from "../security/hydrate-wallet-keys-from-platform-store";
-import { isNodePlatformSecureStoreDefaultAvailable } from "../security/platform-secure-store-node";
-import { deleteWalletSecretsFromOsStore } from "../security/wallet-os-store-actions";
+import { hydrateWalletKeysFromNodePlatformSecureStore } from "../security/hydrate-wallet-keys-from-platform-store.js";
+import { isNodePlatformSecureStoreDefaultAvailable } from "../security/platform-secure-store-node.js";
+import { deleteWalletSecretsFromOsStore } from "../security/wallet-os-store-actions.js";
 // ---------------------------------------------------------------------------
 // Import from extracted modules for use within this file
 // ---------------------------------------------------------------------------
-import { handleCloudTtsPreviewRoute as _handleCloudTtsPreviewRoute, ensureCloudTtsApiKeyAlias, mirrorCompatHeaders, } from "@elizaos/plugin-elizacloud";
-import { filterConfigEnvForResponse as _filterConfigEnvForResponse } from "./server-config-filter";
+import { ensureCloudTtsApiKeyAlias, mirrorCompatHeaders, } from "@elizaos/shared/elizacloud/server-cloud-tts";
+import { filterConfigEnvForResponse as _filterConfigEnvForResponse } from "./server-config-filter.js";
 // ---------------------------------------------------------------------------
 // Module-level constants and types that stay in server.ts
 // ---------------------------------------------------------------------------
@@ -70,7 +93,7 @@ const _PACKAGE_ROOT_NAMES = new Set(["eliza", "elizaai", "elizaos"]);
 // ---------------------------------------------------------------------------
 // extractHeaderValue — now imported from ./auth
 // tokenMatches — now imported from ./auth
-// Pairing infrastructure — now in ./auth-pairing-compat-routes
+// Pairing infrastructure — now in ./auth-pairing-routes
 // getProvidedApiToken, ensureCompatApiAuthorized, isDevEnvironment,
 // ensureCompatSensitiveRouteAuthorized — now imported from ./auth
 function hydrateWalletOsStoreFlagFromConfig() {
@@ -97,8 +120,7 @@ function hydrateWalletOsStoreFlagFromConfig() {
 }
 function resolveCompatConfigPaths() {
     const explicitConfig = process.env.ELIZA_CONFIG_PATH?.trim();
-    const hasStateOverride = Boolean(process.env.MILADY_STATE_DIR?.trim()) ||
-        Boolean(process.env.ELIZA_STATE_DIR?.trim());
+    const hasStateOverride = Boolean(process.env.ELIZA_STATE_DIR?.trim());
     const configPath = explicitConfig ||
         (hasStateOverride ? path.join(resolveStateDir(), "eliza.json") : undefined);
     return { elizaConfigPath: configPath, appConfigPath: configPath };
@@ -141,6 +163,7 @@ export function syncCompatConfigFiles() {
     fs.mkdirSync(path.dirname(targetPath), { recursive: true });
     fs.copyFileSync(sourcePath, targetPath);
 }
+const RUNTIME_STOP_RESET_TIMEOUT_MS = 20_000;
 function resolveCompatPgliteDataDir(config) {
     const explicitDataDir = process.env.PGLITE_DATA_DIR?.trim();
     if (explicitDataDir) {
@@ -151,7 +174,7 @@ function resolveCompatPgliteDataDir(config) {
         return resolveUserPath(configuredDataDir);
     }
     const workspaceDir = config.agents?.defaults?.workspace ?? resolveDefaultAgentWorkspaceDir();
-    return path.join(resolveUserPath(workspaceDir), ".eliza", ".elizadb");
+    return path.join(resolveUserPath(workspaceDir), ".elizadb");
 }
 /**
  * Reset hop for `POST /api/agent/reset`. Deliberately operates entirely
@@ -166,7 +189,36 @@ function resolveCompatPgliteDataDir(config) {
  */
 async function clearCompatPgliteDataDir(runtime, config) {
     if (typeof runtime?.stop === "function") {
-        await runtime.stop();
+        // `runtime.stop()` releases plugins/services to drop the PGlite write lock
+        // before we delete the data dir. On mobile CPU with many plugins loaded it
+        // can take a while, and a hung plugin shutdown must not wedge reset forever.
+        // POSIX `rm` succeeds with open file handles, so if stop overruns we log and
+        // proceed to delete anyway; the lingering runtime is torn down by the
+        // first-run restart that follows on the client.
+        let stopTimedOut = false;
+        let timeoutHandle = null;
+        try {
+            await Promise.race([
+                Promise.resolve(runtime.stop()),
+                new Promise((resolve) => {
+                    timeoutHandle = setTimeout(() => {
+                        stopTimedOut = true;
+                        resolve();
+                    }, RUNTIME_STOP_RESET_TIMEOUT_MS);
+                }),
+            ]);
+        }
+        catch (err) {
+            logger.warn(`[eliza][reset] runtime.stop() failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+        }
+        if (stopTimedOut) {
+            logger.warn(`[eliza][reset] runtime.stop() exceeded ${RUNTIME_STOP_RESET_TIMEOUT_MS}ms; deleting PGlite data dir anyway`);
+        }
     }
     const dataDir = resolveCompatPgliteDataDir(config);
     if (path.basename(dataDir) !== ".elizadb") {
@@ -305,7 +357,7 @@ async function _getTableColumnNames(runtime, tableName, schemaName = "public") {
 // buildPluginParamDefs, findNearestFile, resolvePluginManifestPath,
 // resolveInstalledPackageVersion, resolveLoadedPluginNames, isPluginLoaded,
 // buildPluginListResponse, validateCompatPluginConfig, persistCompatPluginMutation
-// — extracted to ./plugins-compat-routes
+// — extracted to ./plugins-routes
 /**
  * Load config from disk and backfill `cloud.apiKey` from sealed secrets when the
  * user is still linked to Eliza Cloud but a stale write dropped the key.
@@ -343,7 +395,7 @@ function resolveCloudConfig(runtime) {
                 config.cloud = {};
             }
             config.cloud.apiKey = backfillKey;
-            // Persist the backfilled key so future reads find it on disk
+            // Persist the backfilled key so later reads find it on disk.
             try {
                 saveElizaConfig(config);
                 logger.info("[cloud] Backfilled missing cloud.apiKey to config file");
@@ -363,6 +415,19 @@ function resolveCloudConfig(runtime) {
 // cloud route handlers into plugin-elizacloud (see plugins/plugin-elizacloud/
 // plugin.ts → compatLoopbackConfigPut + makeCloudRouteHandler).
 async function handleCompatRoute(req, res, state) {
+    if (!isPerfInstrumentEnabled()) {
+        return handleCompatRouteInner(req, res, state);
+    }
+    const start = performance.now();
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const routeKey = normalizeRouteKey((req.method ?? "GET").toUpperCase(), url.pathname);
+    const handled = await handleCompatRouteInner(req, res, state);
+    if (handled) {
+        recordRouteTiming(routeKey, performance.now() - start);
+    }
+    return handled;
+}
+async function handleCompatRouteInner(req, res, state) {
     const method = (req.method ?? "GET").toUpperCase();
     const url = new URL(req.url ?? "/", "http://localhost");
     // ── Mode visibility gate ──────────────────────────────────────────────
@@ -410,21 +475,48 @@ async function handleCompatRoute(req, res, state) {
     // Dev observability routes — extracted to dev-compat-routes.ts
     if (await handleDevCompatRoutes(req, res, state))
         return true;
-    // Bootstrap-token exchange (P0 cloud-provisioned auth) — must precede the
-    // legacy auth-pairing handler so the dedicated rate-limited route owns
-    // `/api/auth/bootstrap/exchange`.
+    // Cloud SSO popup landing — `/pair?token=X` calls cloud-api server-side,
+    // serves HTML that pins the API token on the SPA's window global. Mounted
+    // before any other auth handler so it owns the root `/pair` URL.
+    if (await handleCloudPairRoute(req, res))
+        return true;
+    // Must precede the auth-pairing handler so the rate-limited route owns /api/auth/bootstrap/exchange.
     if (await handleAuthBootstrapRoutes(req, res, state))
         return true;
-    // P1 session routes: setup, login/password, logout, me, sessions list/revoke.
-    // These own cookie + CSRF lifecycle for the dashboard.
+    // Cookie + CSRF session lifecycle (setup, login, logout, me, sessions).
     if (await handleAuthSessionRoutes(req, res, state))
         return true;
-    // Auth / pairing / onboarding status — extracted to auth-pairing-compat-routes.ts
+    // Auth / pairing / first-run status — extracted to auth-pairing-routes.ts
     if (await handleAuthPairingCompatRoutes(req, res, state))
         return true;
-    // Computer-use compat routes — extracted to plugin-computeruse via Plugin.routes (rawPath).
-    if (await handleLocalInferenceCompatRoutes(req, res, state))
+    // Sensitive-request REST surface (create/get/submit/cancel) for owner secret
+    // collection — e.g. orchestrator provider keys land in the shared vault
+    // instead of plain config. Each branch self-authorizes via
+    // ensureCallerAuthorized (trusted-local, API token, or session), matching the
+    // sibling compat handlers, so mounting it does not widen the unauth surface.
+    if (await handleSensitiveRequestRoutes(req, res, state))
+        return true;
+    if (await handleBackgroundTasksRoute(req, res, state))
+        return true;
+    // Internal wake route called by Capacitor BackgroundRunner JSContexts on
+    // iOS/Android. Bearer-authed via the device secret; not part of the
+    // cookie session pipeline.
+    if (await handleInternalWakeRoute(req, res, state))
         return true;
+    // Local-inference compat routes — loaded via lazy getter to avoid a static
+    // boundary violation (app-core must not statically import plugin packages).
+    {
+        const { handleLiveDiarizationRoute, handleLocalInferenceAsrRoute, handleLocalInferenceCompatRoutes, handleLocalInferenceTtsRoute, } = await getLocalInferenceRoutes();
+        if (await handleLocalInferenceCompatRoutes(req, res, state))
+            return true;
+        if (await handleLocalInferenceAsrRoute(req, res, state))
+            return true;
+        if (await handleLocalInferenceTtsRoute(req, res, state))
+            return true;
+        // WebView → agent PCM transport for live on-device speaker diarization.
+        if (await handleLiveDiarizationRoute(req, res, state))
+            return true;
+    }
     if (await handleAutomationsCompatRoutes(req, res, state))
         return true;
     // workflow routes — extracted to plugins/plugin-workflow/src/plugin-routes.ts.
@@ -435,7 +527,17 @@ async function handleCompatRoute(req, res, state) {
     if (method === "POST" && url.pathname === "/api/tts/cloud") {
         if (!(await ensureRouteAuthorized(req, res, state)))
             return true;
-        return await _handleCloudTtsPreviewRoute(req, res);
+        const { handleCloudTtsPreviewRoute } = await import("@elizaos/plugin-elizacloud");
+        return handleCloudTtsPreviewRoute(req, res);
+    }
+    // Onboarding voice: serve the pre-generated OmniVoice presets for the fixed
+    // first-run lines (committed WAVs) before any agent exists. The client falls
+    // back to browser speechSynthesis if this route fails, so onboarding never
+    // goes silent.
+    if (method === "POST" && url.pathname === "/api/tts/first-run/speak") {
+        if (!(await ensureRouteAuthorized(req, res, state)))
+            return true;
+        return handleFirstRunTtsRoute(req, res);
     }
     if (method === "POST" && url.pathname === "/api/tts/elevenlabs") {
         // Intentional passthrough: ElevenLabs TTS is handled by the upstream
@@ -478,8 +580,8 @@ async function handleCompatRoute(req, res, state) {
             whitelistMintOpen: false,
             mintedOut: false,
             currentSupply: 0,
-            maxSupply: 2138,
-            shinyPrice: "0.1",
+            maxSupply: 0,
+            shinyPrice: "0",
             userHasMinted: false,
         });
         return true;
@@ -496,12 +598,12 @@ async function handleCompatRoute(req, res, state) {
             return true;
         }
         try {
-            logger.info("[eliza][reset] POST /api/agent/reset: loading config, will clear onboarding state, persisted provider config, and cloud keys (GGUF / MODELS_DIR untouched)");
+            logger.info("[eliza][reset] POST /api/agent/reset: loading config, will clear first-run state, persisted provider config, and cloud keys (GGUF / MODELS_DIR untouched)");
             const config = loadElizaConfig();
             logger.info("[eliza][reset] Skipping loopback API cleanup; runtime stop plus PGlite data-dir removal clears conversations, knowledge, and trajectories without re-entering the HTTP server.");
             await clearCompatPgliteDataDir(state.current, config);
             state.current = null;
-            clearPersistedOnboardingConfig(config);
+            clearPersistedFirstRunConfig(config);
             saveElizaConfig(config);
             clearCloudSecrets();
             try {
@@ -525,13 +627,18 @@ async function handleCompatRoute(req, res, state) {
     // All four handler groups (wallet-compat, wallet-browser-compat,
     // steward-compat, wallet-trade-compat) are now served via
     // stewardPlugin.routes (rawPath) on the runtime plugin route system.
-    // Plugin routes — extracted to plugins-compat-routes.ts
-    if (await handlePluginsCompatRoutes(req, res, state))
-        return true;
+    // Plugin routes — extracted to @elizaos/plugin-registry. That package pulls
+    // in heavyweight registry/install code, so keep it out of the startup path
+    // and only load it for plugin-management requests.
+    if (url.pathname.startsWith("/api/plugins")) {
+        const { handlePluginsCompatRoutes } = await getPluginRegistryApi();
+        if (await handlePluginsCompatRoutes(req, res, state))
+            return true;
+    }
     // Catalog routes — registry SoT projections (apps, plugins, connectors)
     if (await handleCatalogRoutes(req, res, state))
         return true;
-    if (await handleOnboardingCompatRoute(req, res, state))
+    if (await handleFirstRunRoute(req, res, state))
         return true;
     // GET /api/plugins/:id/ui-spec — generate a UiSpec for plugin configuration.
     // Used by the agent to spawn interactive config forms in chat.
@@ -541,8 +648,8 @@ async function handleCompatRoute(req, res, state) {
         if (!(await ensureRouteAuthorized(req, res, state)))
             return true;
         const pluginId = decodeURIComponent(uiSpecMatch[1]);
-        const { buildPluginConfigUiSpec } = await import("@elizaos/shared");
-        const { buildPluginListResponse } = await import("./plugins-compat-routes");
+        const { buildPluginConfigUiSpec } = await import("@elizaos/shared/config/plugin-ui-spec");
+        const { buildPluginListResponse } = await getPluginRegistryApi();
         const pluginList = buildPluginListResponse(state.current);
         const plugin = pluginList.plugins.find((p) => p.id === pluginId);
         if (!plugin) {
@@ -586,9 +693,29 @@ async function handleCompatRoute(req, res, state) {
     return handleDatabaseRowsCompatRoute(req, res, state);
 }
 export async function handleElizaCompatRoute(req, res, state) {
-    return await handleCompatRoute(req, res, state);
+    return handleCompatRoute(req, res, state);
 }
-export function patchHttpCreateServerForCompat(state) {
+/**
+ * Module-scoped singleton compat-state. Both the early
+ * `patchHttpCreateServerForCompat()` call (from `startEliza` before upstream's
+ * boot binds the listener) AND the later `startApiServer` wrapper need to
+ * share the SAME state object — otherwise the early-bound listener captures
+ * an empty state by closure and never sees the runtime that `startApiServer`
+ * assigns to its own local state. `getSharedCompatRuntimeState()` returns
+ * this singleton so both call sites can read/mutate the same reference.
+ */
+const sharedCompatRuntimeState = {
+    current: null,
+    pendingAgentName: null,
+    pendingRestartReasons: [],
+};
+export function getSharedCompatRuntimeState() {
+    return sharedCompatRuntimeState;
+}
+export function patchHttpCreateServerForCompat() {
+    // Always capture the shared singleton. A caller-local CompatRuntimeState
+    // would split early and late patch sites back into different state objects.
+    const effectiveState = sharedCompatRuntimeState;
     const originalCreateServer = http.createServer.bind(http);
     http.createServer = ((...args) => {
         const [firstArg, secondArg] = args;
@@ -607,9 +734,7 @@ export function patchHttpCreateServerForCompat(state) {
             // is picked up without a restart.
             ensureCloudTtsApiKeyAlias();
             mirrorCompatHeaders(req);
-            if (state) {
-                patchCompatStatusResponse(req, res, state);
-            }
+            patchCompatStatusResponse(req, res, effectiveState);
             // CORS: allow local renderer servers (Vite, static loopback, WKWebView).
             // WKWebView sometimes omits `Origin` on cross-port fetches; allow Referer
             // only when Origin is absent so we never reflect an arbitrary Origin.
@@ -645,7 +770,7 @@ export function patchHttpCreateServerForCompat(state) {
             if (allowOrigin) {
                 res.setHeader("Access-Control-Allow-Origin", allowOrigin);
                 res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS");
-                res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-API-Token, X-Api-Key, X-ElizaOS-Client-Id, X-ElizaOS-UI-Language, X-ElizaOS-Token, X-Eliza-Export-Token, X-Eliza-Terminal-Token, X-Eliza-CSRF");
+                res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-API-Token, X-Api-Key, X-ElizaOS-Client-Id, X-ElizaOS-UI-Language, X-ElizaOS-Token, X-Eliza-Export-Token, X-Eliza-Terminal-Token, X-Eliza-Platform, X-Eliza-CSRF");
                 res.setHeader("Access-Control-Allow-Credentials", "true");
             }
             if (req.method === "OPTIONS") {
@@ -657,14 +782,14 @@ export function patchHttpCreateServerForCompat(state) {
                 syncElizaEnvAliases();
                 syncCompatConfigFiles();
             });
-            if (state) {
+            {
                 const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
                 if (pathname.startsWith("/api/database") ||
                     pathname.startsWith("/api/trajectories")) {
-                    await ensureRuntimeSqlCompatibility(state.current);
+                    await ensureRuntimeSqlCompatibility(effectiveState.current);
                 }
                 try {
-                    if (await handleCompatRoute(req, res, state)) {
+                    if (await handleCompatRoute(req, res, effectiveState)) {
                         return;
                     }
                 }
@@ -699,8 +824,10 @@ export function patchHttpCreateServerForCompat(state) {
         // Attach the local-inference device-bridge WS upgrade handler to every
         // HTTP server created through this patched factory. Safe to call on
         // every server — `attachToHttpServer` is idempotent and only installs
-        // the upgrade listener once.
-        void deviceBridge.attachToHttpServer(created).catch((err) => {
+        // the upgrade listener once. Imported dynamically to avoid static boundary violation.
+        void import("@elizaos/plugin-local-inference/services")
+            .then(({ deviceBridge }) => deviceBridge.attachToHttpServer(created))
+            .catch((err) => {
             logger.warn("[compat] Failed to attach device-bridge WS handler:", err instanceof Error ? err.message : String(err));
         });
         return created;
@@ -718,21 +845,28 @@ export async function startApiServer(...args) {
     ensureCloudTtsApiKeyAlias();
     hydrateWalletOsStoreFlagFromConfig();
     await hydrateWalletKeysFromNodePlatformSecureStore();
-    // Pre-load steward wallet addresses so getWalletAddresses() has them
-    // available synchronously from the start.
-    await initStewardWalletCache();
-    const compatState = {
-        current: args[0]?.runtime ?? null,
-        pendingAgentName: null,
-        pendingRestartReasons: [],
-    };
-    const restoreCreateServer = patchHttpCreateServerForCompat(compatState);
+    // Use the module-scoped shared state instead of a fresh local object so
+    // any earlier patch installation (e.g. the `startEliza` boot-time install
+    // that ensures upstream's listener engages the compat dispatcher) sees the
+    // runtime once we receive it here. The shared state is created at module
+    // load with `current: null`; we seed it now from the caller's optional
+    // runtime arg, then upstream's `server.updateRuntime` wrapper continues to
+    // mutate the same reference per hot-swap.
+    const compatState = sharedCompatRuntimeState;
+    clearCompatRuntimeRestart(compatState);
+    if (args[0]?.runtime) {
+        compatState.current = args[0].runtime;
+        compatState.pendingAgentName = null;
+    }
+    const restoreCreateServer = patchHttpCreateServerForCompat();
     try {
         if (compatState.current) {
             await ensureRuntimeSqlCompatibility(compatState.current);
             await (await lazyEnsureTTS())(compatState.current);
         }
+        const upstreamStart = Date.now();
         const server = await upstreamStartApiServer(...args);
+        logger.info(`[eliza-api] upstreamStartApiServer took ${Date.now() - upstreamStart}ms`);
         const originalUpdateRuntime = server.updateRuntime;
         server.updateRuntime = (runtime) => {
             compatState.current = runtime;

package/api/setup-contract.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared contract for connector setup HTTP routes.
+ *
+ * Every connector plugin's setup-routes export MUST satisfy:
+ *
+ *   GET  /api/setup/<connector>/status   → SetupStatusResponse
+ *   POST /api/setup/<connector>/start    → SetupStatusResponse (state: 'configuring')
+ *   POST /api/setup/<connector>/cancel   → SetupStatusResponse (state: 'idle')
+ *
+ * Error responses follow `{ error: { code, message } }` — never bare strings.
+ *
+ * This contract is pinned by `eliza/plugins/__tests__/setup-routes-contract.test.ts`.
+ * `docs/first-run-contracts.md` covers the connector setup surface.
+ */
+/** Setup lifecycle states a connector can be in. */
+export type SetupState = "idle" | "configuring" | "paired" | "error";
+/**
+ * Canonical status response shape returned by every setup endpoint.
+ *
+ * `detail` is connector-specific (QR code data, pairing phone number,
+ * subscription channel IDs, etc.). Callers narrow on `state` first and
+ * then read the typed detail.
+ */
+export interface SetupStatusResponse<TDetail = unknown> {
+    connector: string;
+    state: SetupState;
+    detail?: TDetail;
+}
+/**
+ * Structured error envelope returned when a setup endpoint fails.
+ *
+ * `code` is a stable machine-readable identifier (e.g. `bad_request`,
+ * `service_unavailable`, `internal_error`); `message` is human-readable.
+ */
+export interface SetupErrorResponse {
+    error: {
+        code: string;
+        message: string;
+    };
+}
+/** Common error codes used across connector setup routes. */
+export declare const SETUP_ERROR_CODES: {
+    readonly BAD_REQUEST: "bad_request";
+    readonly SERVICE_UNAVAILABLE: "service_unavailable";
+    readonly INTERNAL_ERROR: "internal_error";
+    readonly TOO_MANY_SESSIONS: "too_many_sessions";
+};
+export type SetupErrorCode = (typeof SETUP_ERROR_CODES)[keyof typeof SETUP_ERROR_CODES];
+/**
+ * Build a structured error envelope.
+ *
+ * Use this on every error path in connector setup handlers so the UI
+ * layer can branch on `error.code` rather than substring-matching
+ * `error.message`.
+ */
+export declare function buildSetupError(code: SetupErrorCode | string, message: string): SetupErrorResponse;
+/**
+ * Compose the canonical path for a connector setup endpoint.
+ *
+ * `setupPath("signal", "start")` → `/api/setup/signal/start`.
+ */
+export declare function setupPath(connector: string, action: "status" | "start" | "cancel"): string;
+//# sourceMappingURL=setup-contract.d.ts.map

package/api/setup-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-contract.d.ts","sourceRoot":"","sources":["../../../../../src/api/setup-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB,CAAC,OAAO,GAAG,OAAO;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,6DAA6D;AAC7D,eAAO,MAAM,iBAAiB;;;;;CAKpB,CAAC;AAEX,MAAM,MAAM,cAAc,GACxB,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAE7D;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,cAAc,GAAG,MAAM,EAC7B,OAAO,EAAE,MAAM,GACd,kBAAkB,CAEpB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GACpC,MAAM,CAER"}

package/api/setup-contract.js

@@ -0,0 +1,39 @@
+/**
+ * Shared contract for connector setup HTTP routes.
+ *
+ * Every connector plugin's setup-routes export MUST satisfy:
+ *
+ *   GET  /api/setup/<connector>/status   → SetupStatusResponse
+ *   POST /api/setup/<connector>/start    → SetupStatusResponse (state: 'configuring')
+ *   POST /api/setup/<connector>/cancel   → SetupStatusResponse (state: 'idle')
+ *
+ * Error responses follow `{ error: { code, message } }` — never bare strings.
+ *
+ * This contract is pinned by `eliza/plugins/__tests__/setup-routes-contract.test.ts`.
+ * `docs/first-run-contracts.md` covers the connector setup surface.
+ */
+/** Common error codes used across connector setup routes. */
+export const SETUP_ERROR_CODES = {
+    BAD_REQUEST: "bad_request",
+    SERVICE_UNAVAILABLE: "service_unavailable",
+    INTERNAL_ERROR: "internal_error",
+    TOO_MANY_SESSIONS: "too_many_sessions",
+};
+/**
+ * Build a structured error envelope.
+ *
+ * Use this on every error path in connector setup handlers so the UI
+ * layer can branch on `error.code` rather than substring-matching
+ * `error.message`.
+ */
+export function buildSetupError(code, message) {
+    return { error: { code, message } };
+}
+/**
+ * Compose the canonical path for a connector setup endpoint.
+ *
+ * `setupPath("signal", "start")` → `/api/setup/signal/start`.
+ */
+export function setupPath(connector, action) {
+    return `/api/setup/${connector}/${action}`;
+}