@elizaos/agent 2.0.0-alpha.98 → 2.0.0-beta.2

package/packages/agent/src/services/app-manager.js

@@ -8,21 +8,281 @@
  *
  * @module services/app-manager
  */
+import crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { logger } from "@elizaos/core";
-import { deriveEvmAddress, deriveSolanaAddress } from "../api/wallet";
-import { getPluginInfo, getRegistryPlugins } from "./registry-client";
+import { getElizaCuratedAppCatalogOrder, getElizaCuratedAppLookupNames, hasAppInterface, normalizeElizaCuratedAppName, packageNameToAppDisplayName, packageNameToAppRouteSlug, } from "@elizaos/shared";
+import { loadElizaConfig, saveElizaConfig } from "../config/config.js";
+import { shouldRestoreAgentsListAfterAppLaunch } from "./app-manager-agents-list-guard.js";
+import { importAppPlugin, importAppRouteModule, } from "./app-package-modules.js";
+import { readAppRunStore, writeAppRunStore } from "./app-run-store.js";
+import { getPluginInfo, getRegistryPlugins } from "./registry-client.js";
+import { mergeAppMeta as mergeRegistryAppMeta, resolveAppOverride, } from "./registry-client-app-meta.js";
+import { resolveAppHeroImage, scoreEntries, toSearchResults, } from "./registry-client-queries.js";
 const LOCAL_PLUGINS_DIR = "plugins";
 const DEFAULT_VIEWER_SANDBOX = "allow-scripts allow-same-origin allow-popups";
-const RS_2004SCAPE_APP_NAME = "@elizaos/app-2004scape";
-const RS_2004SCAPE_AUTH_MESSAGE_TYPE = "RS_2004SCAPE_AUTH";
+const DEFAULT_RS_SDK_SERVER_URL = "https://rs-sdk-demo.fly.dev";
+const HYPERSCAPE_APP_ROUTE_SLUG = "hyperscape";
+const LOCAL_DEV_HYPERSCAPE_CLIENT_URL = "http://localhost:3333";
+const PRODUCTION_HYPERSCAPE_CLIENT_URL = "https://hyperscape.gg";
 const SAFE_APP_URL_PROTOCOLS = new Set(["http:", "https:"]);
-const ALLOWED_APP_URL_TEMPLATE_KEYS = new Set([
-    // Public display identity only.
+const SAFE_APP_TEMPLATE_ENV_KEYS = new Set([
     "BOT_NAME",
+    "HYPERSCAPE_CHARACTER_ID",
+    "HYPERSCAPE_CLIENT_URL",
     "RS_SDK_BOT_NAME",
+    "RS_SDK_BOT_PASSWORD",
+    "RS_SDK_SERVER_URL",
 ]);
+const RUN_REFRESH_MIN_INTERVAL_MS = 5_000;
+const MAX_RUN_EVENTS = 20;
+/**
+ * How long a run can go without a heartbeat (UI ping or session refresh)
+ * before the sweeper considers it abandoned and stops it. Tuned to comfortably
+ * tolerate the 3s session-refresh poll + a few missed ticks on a slow tab,
+ * while still reaping a closed/crashed browser within ~1.5 minutes.
+ */
+const RUN_HEARTBEAT_TIMEOUT_MS = 90_000;
+/** How often the sweeper wakes to look for stale runs. */
+const RUN_HEARTBEAT_SWEEP_INTERVAL_MS = 30_000;
+const DEFAULT_REGISTRY_REFRESH_TIMEOUT_MS = 5_000;
+function cloneJsonValue(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function readAgentsListSnapshot() {
+    const list = loadElizaConfig().agents?.list;
+    return Array.isArray(list) ? cloneJsonValue(list) : undefined;
+}
+function restoreAgentsListAfterAppLaunchIfNeeded(before, appName, phase) {
+    const config = loadElizaConfig();
+    const current = config.agents?.list;
+    if (!shouldRestoreAgentsListAfterAppLaunch(before, current)) {
+        return;
+    }
+    config.agents ??= {};
+    if (!before) {
+        delete config.agents.list;
+    }
+    else {
+        config.agents.list = cloneJsonValue(before);
+    }
+    saveElizaConfig(config);
+    logger.warn(`[app-manager] Restored agents.list after ${appName} ${phase}; app launch must not replace the user's active character config.`);
+}
+function isProductionRuntime() {
+    return process.env.NODE_ENV === "production";
+}
+function resolveRegistryRefreshTimeoutMs() {
+    const raw = process.env.ELIZA_APPS_REGISTRY_REFRESH_TIMEOUT_MS?.trim();
+    if (!raw)
+        return DEFAULT_REGISTRY_REFRESH_TIMEOUT_MS;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed >= 250
+        ? parsed
+        : DEFAULT_REGISTRY_REFRESH_TIMEOUT_MS;
+}
+async function withTimeout(promise, timeoutMs, label) {
+    let timeout;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeout = setTimeout(() => {
+                    reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+function isAppRegistryPlugin(plugin) {
+    return hasAppInterface(plugin);
+}
+function isHyperscapeAppName(appName) {
+    return packageNameToAppRouteSlug(appName) === HYPERSCAPE_APP_ROUTE_SLUG;
+}
+function resolveDisplayViewerInfo(viewer) {
+    if (!viewer)
+        return viewer;
+    const embedParams = viewer.embedParams
+        ? Object.fromEntries(Object.entries(viewer.embedParams)
+            .map(([key, value]) => [key, substituteTemplateVars(value).trim()])
+            .filter(([, value]) => value.length > 0))
+        : undefined;
+    return {
+        ...viewer,
+        url: substituteTemplateVars(viewer.url),
+        embedParams,
+    };
+}
+function flattenAppInfo(appInfo) {
+    const meta = appInfo.appMeta;
+    if (!meta)
+        return appInfo;
+    return {
+        ...appInfo,
+        displayName: meta.displayName ?? appInfo.displayName,
+        launchType: meta.launchType ?? appInfo.launchType,
+        launchUrl: substituteTemplateVars(meta.launchUrl ?? appInfo.launchUrl ?? "") || null,
+        icon: meta.icon ?? appInfo.icon,
+        heroImage: resolveAppHeroImage(appInfo.name, meta.heroImage ?? null),
+        category: meta.category ?? appInfo.category,
+        capabilities: meta.capabilities ?? appInfo.capabilities,
+        uiExtension: meta.uiExtension ?? appInfo.uiExtension,
+        viewer: resolveDisplayViewerInfo(meta.viewer ?? appInfo.viewer),
+        session: meta.session ?? appInfo.session,
+    };
+}
+function cloneRegistryPluginInfo(appInfo) {
+    return {
+        ...appInfo,
+        topics: [...appInfo.topics],
+        npm: { ...appInfo.npm },
+        git: { ...appInfo.git },
+        supports: { ...appInfo.supports },
+        appMeta: appInfo.appMeta
+            ? {
+                ...appInfo.appMeta,
+                capabilities: [...appInfo.appMeta.capabilities],
+                viewer: appInfo.appMeta.viewer
+                    ? {
+                        ...appInfo.appMeta.viewer,
+                        embedParams: appInfo.appMeta.viewer.embedParams
+                            ? { ...appInfo.appMeta.viewer.embedParams }
+                            : undefined,
+                    }
+                    : undefined,
+                session: appInfo.appMeta.session
+                    ? {
+                        ...appInfo.appMeta.session,
+                        features: appInfo.appMeta.session.features
+                            ? [...appInfo.appMeta.session.features]
+                            : undefined,
+                    }
+                    : undefined,
+            }
+            : undefined,
+    };
+}
+function canonicalizeCuratedRegistryPlugin(appInfo, canonicalName) {
+    if (appInfo.name === canonicalName && appInfo.npm.package === canonicalName) {
+        return cloneRegistryPluginInfo(appInfo);
+    }
+    const next = cloneRegistryPluginInfo(appInfo);
+    next.name = canonicalName;
+    // Only rewrite npm.package if it was derived from the name (no separate
+    // runtime plugin). When npm.package differs from name (e.g. Hyperscape:
+    // app=@hyperscape/plugin-hyperscape, plugin=@elizaos/plugin-hyperscape),
+    // preserve the original so resolvePluginPackageName stays correct.
+    if (!next.npm.package || next.npm.package === appInfo.name) {
+        next.npm = {
+            ...next.npm,
+            package: canonicalName,
+        };
+    }
+    return next;
+}
+function mergeCatalogVariant(target, candidate) {
+    mergeLocalRegistryInfo(target, candidate);
+    target.stars = Math.max(target.stars, candidate.stars);
+    return target;
+}
+function compareCuratedCatalogCandidates(left, right) {
+    const orderDiff = getElizaCuratedAppCatalogOrder(left.name) -
+        getElizaCuratedAppCatalogOrder(right.name);
+    if (orderDiff !== 0) {
+        return orderDiff;
+    }
+    const leftCanonicalName = normalizeElizaCuratedAppName(left.name);
+    const rightCanonicalName = normalizeElizaCuratedAppName(right.name);
+    const leftCanonicalPenalty = left.name === leftCanonicalName ? 0 : 1;
+    const rightCanonicalPenalty = right.name === rightCanonicalName ? 0 : 1;
+    if (leftCanonicalPenalty !== rightCanonicalPenalty) {
+        return leftCanonicalPenalty - rightCanonicalPenalty;
+    }
+    const leftLocalPenalty = left.localPath ? 0 : 1;
+    const rightLocalPenalty = right.localPath ? 0 : 1;
+    if (leftLocalPenalty !== rightLocalPenalty) {
+        return leftLocalPenalty - rightLocalPenalty;
+    }
+    return right.stars - left.stars || left.name.localeCompare(right.name);
+}
+function curateCatalogApps(apps) {
+    const curated = new Map();
+    const candidates = Array.from(apps).sort(compareCuratedCatalogCandidates);
+    for (const app of candidates) {
+        const canonicalName = normalizeElizaCuratedAppName(app.name);
+        if (!canonicalName) {
+            continue;
+        }
+        const normalized = canonicalizeCuratedRegistryPlugin(app, canonicalName);
+        const existing = curated.get(canonicalName);
+        if (!existing) {
+            curated.set(canonicalName, normalized);
+            continue;
+        }
+        mergeCatalogVariant(existing, normalized);
+    }
+    return Array.from(curated.values()).sort(compareCuratedCatalogCandidates);
+}
+async function resolveCuratedAppInfo(pluginManager, name) {
+    const canonicalName = normalizeElizaCuratedAppName(name);
+    if (!canonicalName) {
+        return null;
+    }
+    const lookupNames = getElizaCuratedAppLookupNames(name);
+    let appInfo = null;
+    for (const candidateName of lookupNames) {
+        const remote = (await pluginManager.getRegistryPlugin(candidateName));
+        if (!remote) {
+            continue;
+        }
+        const normalized = canonicalizeCuratedRegistryPlugin(remote, canonicalName);
+        if (!appInfo) {
+            appInfo = normalized;
+            continue;
+        }
+        mergeCatalogVariant(appInfo, normalized);
+    }
+    for (const candidateName of lookupNames) {
+        const localPluginInfo = await getPluginInfo(candidateName).catch(() => null);
+        if (!localPluginInfo) {
+            continue;
+        }
+        const normalized = canonicalizeCuratedRegistryPlugin(localPluginInfo, canonicalName);
+        if (!appInfo) {
+            appInfo = mergeLocalRegistryInfo(normalized, normalized);
+            continue;
+        }
+        mergeCatalogVariant(appInfo, normalized);
+    }
+    if (!appInfo) {
+        return null;
+    }
+    appInfo.appMeta = resolveEffectiveAppMeta(canonicalName, appInfo);
+    return flattenAppInfo(appInfo);
+}
+async function resolveNamedAppInfo(pluginManager, name) {
+    let appInfo = (await pluginManager.getRegistryPlugin(name));
+    const localPluginInfo = await getPluginInfo(name).catch(() => null);
+    if (localPluginInfo) {
+        if (!appInfo) {
+            appInfo = mergeLocalRegistryInfo(cloneRegistryPluginInfo(localPluginInfo), localPluginInfo);
+        }
+        else {
+            mergeLocalRegistryInfo(appInfo, localPluginInfo);
+        }
+    }
+    if (!appInfo) {
+        return null;
+    }
+    appInfo.appMeta = resolveEffectiveAppMeta(name, appInfo);
+    return flattenAppInfo(appInfo);
+}
 function resolvePluginPackageName(appInfo) {
     const npmPackage = appInfo.npm.package.trim();
     return npmPackage && npmPackage.length > 0 ? npmPackage : appInfo.name;
@@ -37,6 +297,60 @@ function mergeAppMeta(appInfo, meta) {
     appInfo.category = meta.category ?? appInfo.category;
     appInfo.capabilities = meta.capabilities ?? appInfo.capabilities;
     appInfo.icon = meta.icon ?? appInfo.icon;
+    appInfo.runtimePlugin = meta.runtimePlugin ?? appInfo.runtimePlugin;
+    appInfo.session = meta.session ?? appInfo.session;
+}
+function mergeLocalRegistryInfo(appInfo, localInfo) {
+    appInfo.localPath = localInfo.localPath ?? appInfo.localPath;
+    appInfo.kind = localInfo.kind ?? appInfo.kind;
+    appInfo.appMeta = localInfo.appMeta ?? appInfo.appMeta;
+    if (!appInfo.description && localInfo.description) {
+        appInfo.description = localInfo.description;
+    }
+    if (!appInfo.homepage && localInfo.homepage) {
+        appInfo.homepage = localInfo.homepage;
+    }
+    mergeAppMeta(appInfo, localInfo.appMeta);
+    return appInfo;
+}
+function deriveAppMetaFromPluginInfo(appInfo) {
+    const hasTopLevelAppMeta = appInfo.displayName !== undefined ||
+        appInfo.category !== undefined ||
+        appInfo.launchType !== undefined ||
+        appInfo.launchUrl !== undefined ||
+        appInfo.icon !== undefined ||
+        appInfo.heroImage !== undefined ||
+        appInfo.capabilities !== undefined ||
+        appInfo.runtimePlugin !== undefined ||
+        appInfo.uiExtension !== undefined ||
+        appInfo.viewer !== undefined ||
+        appInfo.session !== undefined;
+    if (!hasTopLevelAppMeta) {
+        return undefined;
+    }
+    return {
+        displayName: appInfo.displayName ?? packageNameToAppDisplayName(appInfo.name),
+        category: appInfo.category ?? "game",
+        launchType: appInfo.launchType ?? "url",
+        launchUrl: appInfo.launchUrl ?? null,
+        icon: appInfo.icon ?? null,
+        heroImage: appInfo.heroImage ?? null,
+        capabilities: appInfo.capabilities ?? [],
+        minPlayers: null,
+        maxPlayers: null,
+        runtimePlugin: appInfo.runtimePlugin,
+        uiExtension: appInfo.uiExtension,
+        viewer: appInfo.viewer,
+        session: appInfo.session,
+    };
+}
+function resolveEffectiveAppMeta(packageName, appInfo) {
+    const derivedAppMeta = deriveAppMetaFromPluginInfo(appInfo);
+    const baseAppMeta = mergeRegistryAppMeta(derivedAppMeta, appInfo.appMeta);
+    if (baseAppMeta) {
+        return resolveAppOverride(packageName, baseAppMeta) ?? baseAppMeta;
+    }
+    return resolveAppOverride(packageName, undefined);
 }
 function isAutoInstallable(appInfo) {
     const supportsRuntime = appInfo.supports.v0 || appInfo.supports.v1 || appInfo.supports.v2;
@@ -71,37 +385,107 @@ function getTemplateFallbackValue(key) {
         if (runtimeBotName && runtimeBotName.length > 0) {
             return runtimeBotName;
         }
-        return "testbot";
+        return undefined;
+    }
+    if (key === "RS_SDK_BOT_PASSWORD") {
+        const runtimeBotPassword = process.env.BOT_PASSWORD?.trim();
+        if (runtimeBotPassword && runtimeBotPassword.length > 0) {
+            return runtimeBotPassword;
+        }
+        return undefined;
+    }
+    if (key === "RS_SDK_SERVER_URL") {
+        return DEFAULT_RS_SDK_SERVER_URL;
+    }
+    return undefined;
+}
+function resolveSettingLike(runtime, key) {
+    const fromRuntime = runtime?.getSetting?.(key);
+    if (typeof fromRuntime === "string" && fromRuntime.trim().length > 0) {
+        return fromRuntime.trim();
+    }
+    const fromEnv = process.env[key];
+    if (typeof fromEnv === "string" && fromEnv.trim().length > 0) {
+        return fromEnv.trim();
     }
     return undefined;
 }
-function substituteTemplateVars(raw) {
+function readSafeTemplateEnv(key) {
+    if (!SAFE_APP_TEMPLATE_ENV_KEYS.has(key)) {
+        return undefined;
+    }
+    const value = process.env[key];
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}
+function substituteTemplateVars(raw, options) {
+    const preserveUnknown = options?.preserveUnknown ?? true;
+    const hyperscapeClientDefault = options?.hyperscapeClientDefault === true;
     return raw.replace(/\{([A-Z0-9_]+)\}/g, (_full, key) => {
-        if (!ALLOWED_APP_URL_TEMPLATE_KEYS.has(key)) {
-            return getTemplateFallbackValue(key) ?? "";
+        const value = (SAFE_APP_TEMPLATE_ENV_KEYS.has(key)
+            ? resolveSettingLike(options?.runtime, key)
+            : undefined) ??
+            readSafeTemplateEnv(key) ??
+            (hyperscapeClientDefault && key === "HYPERSCAPE_CLIENT_URL"
+                ? isProductionRuntime()
+                    ? PRODUCTION_HYPERSCAPE_CLIENT_URL
+                    : LOCAL_DEV_HYPERSCAPE_CLIENT_URL
+                : undefined) ??
+            getTemplateFallbackValue(key);
+        if (value !== undefined) {
+            return value;
         }
-        const value = process.env[key];
-        if (value && value.trim().length > 0) {
-            return value.trim();
-        }
-        return getTemplateFallbackValue(key) ?? "";
+        return preserveUnknown ? `{${key}}` : "";
     });
 }
-function buildViewerUrl(baseUrl, embedParams) {
+function buildViewerUrl(baseUrl, embedParams, runtime) {
     if (!embedParams || Object.keys(embedParams).length === 0) {
-        return substituteTemplateVars(baseUrl);
+        return substituteTemplateVars(baseUrl, {
+            preserveUnknown: false,
+            hyperscapeClientDefault: true,
+            runtime,
+        });
     }
-    const resolvedBaseUrl = substituteTemplateVars(baseUrl);
+    const resolvedBaseUrl = substituteTemplateVars(baseUrl, {
+        preserveUnknown: false,
+        hyperscapeClientDefault: true,
+        runtime,
+    });
     const [beforeHash, hashPartRaw] = resolvedBaseUrl.split("#", 2);
     const [pathPart, queryPartRaw] = beforeHash.split("?", 2);
     const queryParams = new URLSearchParams(queryPartRaw ?? "");
     for (const [key, rawValue] of Object.entries(embedParams)) {
-        queryParams.set(key, substituteTemplateVars(rawValue));
+        const nextValue = substituteTemplateVars(rawValue, {
+            preserveUnknown: false,
+            hyperscapeClientDefault: true,
+            runtime,
+        }).trim();
+        if (!nextValue) {
+            queryParams.delete(key);
+            continue;
+        }
+        queryParams.set(key, nextValue);
     }
     const query = queryParams.toString();
     const hash = hashPartRaw ? `#${hashPartRaw}` : "";
     return `${pathPart}${query.length > 0 ? `?${query}` : ""}${hash}`;
 }
+function resolveViewerEmbedParams(embedParams, runtime) {
+    if (!embedParams)
+        return undefined;
+    const resolved = Object.fromEntries(Object.entries(embedParams)
+        .map(([key, value]) => [
+        key,
+        substituteTemplateVars(value, {
+            preserveUnknown: false,
+            hyperscapeClientDefault: true,
+            runtime,
+        }).trim(),
+    ])
+        .filter(([, value]) => value.length > 0));
+    return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
 function normalizeSafeAppUrl(url) {
     const trimmed = url.trim();
     if (!trimmed)
@@ -121,43 +505,46 @@ function normalizeSafeAppUrl(url) {
         return null;
     }
 }
-function buildViewerAuthMessage(appName, postMessageAuth) {
+async function buildViewerAuthMessage(appInfo, launchUrl, runtime) {
+    const postMessageAuth = appInfo.viewer?.postMessageAuth;
     if (!postMessageAuth)
         return undefined;
-    // 2004scape auth - uses bot name and password from environment
-    if (appName === RS_2004SCAPE_APP_NAME) {
-        // Get username from RS_SDK_BOT_NAME or BOT_NAME, fallback to testbot
-        const username = process.env.RS_SDK_BOT_NAME?.trim() ||
-            process.env.BOT_NAME?.trim() ||
-            "testbot";
-        // Get password from RS_SDK_BOT_PASSWORD or BOT_PASSWORD
-        const password = process.env.RS_SDK_BOT_PASSWORD?.trim() ||
-            process.env.BOT_PASSWORD?.trim() ||
-            "";
-        return {
-            type: RS_2004SCAPE_AUTH_MESSAGE_TYPE,
-            authToken: username, // Using authToken field for username
-            sessionToken: password, // Using sessionToken field for password
-        };
+    const routeModule = await importAppRouteModule(appInfo.name);
+    if (typeof routeModule?.resolveViewerAuthMessage === "function") {
+        return ((await routeModule.resolveViewerAuthMessage({
+            appName: appInfo.name,
+            launchUrl,
+            runtime: runtime ?? null,
+            viewer: null,
+        })) ?? undefined);
     }
     return undefined;
 }
-function buildViewerConfig(appInfo, launchUrl) {
+async function buildViewerConfig(appInfo, launchUrl, runtime) {
     const viewerInfo = appInfo.viewer;
     if (viewerInfo) {
         const requestedPostMessageAuth = Boolean(viewerInfo.postMessageAuth);
-        const authMessage = buildViewerAuthMessage(appInfo.name, requestedPostMessageAuth);
+        const authMessage = await buildViewerAuthMessage(appInfo, launchUrl, runtime);
         const postMessageAuth = requestedPostMessageAuth && Boolean(authMessage);
         if (requestedPostMessageAuth && !authMessage) {
             logger.warn(`[app-manager] ${appInfo.name} requires postMessage auth but no auth payload was generated.`);
         }
-        const viewerUrl = normalizeSafeAppUrl(buildViewerUrl(viewerInfo.url, viewerInfo.embedParams));
+        const resolvedEmbedParams = {
+            ...(resolveViewerEmbedParams(viewerInfo.embedParams, runtime) ?? {}),
+        };
+        if (authMessage?.followEntity && !resolvedEmbedParams.followEntity) {
+            resolvedEmbedParams.followEntity = authMessage.followEntity;
+        }
+        const finalEmbedParams = Object.keys(resolvedEmbedParams).length > 0
+            ? resolvedEmbedParams
+            : undefined;
+        const viewerUrl = normalizeSafeAppUrl(buildViewerUrl(viewerInfo.url, finalEmbedParams, runtime));
         if (!viewerUrl) {
             throw new Error(`Refusing to launch app "${appInfo.name}": unsafe viewer URL`);
         }
         return {
             url: viewerUrl,
-            embedParams: viewerInfo.embedParams,
+            embedParams: finalEmbedParams,
             postMessageAuth,
             sandbox: viewerInfo.sandbox ?? DEFAULT_VIEWER_SANDBOX,
             authMessage,
@@ -176,91 +563,831 @@ function buildViewerConfig(appInfo, launchUrl) {
     }
     return null;
 }
+function buildAppSession(appInfo, authMessage, runtime) {
+    if (!appInfo.session)
+        return null;
+    const runtimeAgentId = typeof runtime?.agentId === "string" && runtime.agentId.trim().length > 0
+        ? runtime.agentId
+        : undefined;
+    const sessionId = authMessage?.agentId || authMessage?.characterId || runtimeAgentId;
+    if (!sessionId)
+        return null;
+    const features = new Set(appInfo.session.features ?? []);
+    const controls = [];
+    if (features.has("pause")) {
+        controls.push("pause");
+    }
+    if (features.has("resume")) {
+        controls.push("resume");
+    }
+    const canSendCommands = features.has("commands") || features.has("suggestions");
+    const characterId = authMessage?.characterId ??
+        (isHyperscapeAppName(appInfo.name)
+            ? resolveSettingLike(runtime, "HYPERSCAPE_CHARACTER_ID")
+            : undefined);
+    const followEntity = authMessage?.followEntity ?? characterId ?? undefined;
+    return {
+        sessionId,
+        appName: appInfo.name,
+        mode: appInfo.session.mode,
+        status: "connecting",
+        displayName: appInfo.displayName ?? appInfo.name,
+        agentId: authMessage?.agentId ?? runtimeAgentId,
+        characterId,
+        followEntity,
+        canSendCommands,
+        controls,
+        summary: "Connecting session...",
+    };
+}
+function buildUnavailableSession(run, status, summary) {
+    if (!run.session)
+        return null;
+    return {
+        ...run.session,
+        status,
+        canSendCommands: false,
+        controls: [],
+        goalLabel: null,
+        suggestedPrompts: [],
+        telemetry: null,
+        summary,
+    };
+}
+async function resolveLaunchSession(appInfo, viewer, launchUrl, runtime) {
+    const routeModule = await importAppRouteModule(appInfo.name);
+    if (typeof routeModule?.resolveLaunchSession === "function") {
+        return routeModule.resolveLaunchSession({
+            appName: appInfo.name,
+            launchUrl,
+            runtime,
+            viewer,
+        });
+    }
+    return buildAppSession(appInfo, viewer?.authMessage, runtime);
+}
 /**
- * Get wallet addresses from agent runtime settings (character secrets).
- * Falls back to process.env if runtime is not available.
+ * Invoke the plugin's `stopRun` bridge hook (if defined) when an app run is
+ * removed. Plugins use this to tear down per-run resources (WebSocket
+ * connections, game-loop timers, bot sessions, embedded servers).
+ *
+ * Errors are logged but never re-thrown — removal from the app-manager
+ * registry is authoritative.
  */
-function _getWalletAddressesFromRuntime(runtime) {
-    const PLACEHOLDER_RE = /^\[?\s*(REDACTED|PLACEHOLDER|TODO|CHANGEME|EMPTY)\s*]?$/i;
-    let evmAddress = null;
-    let solanaAddress = null;
-    // Try runtime settings first (character secrets), fall back to process.env
-    const evmKey = runtime?.getSetting?.("EVM_PRIVATE_KEY")?.trim() ||
-        process.env.EVM_PRIVATE_KEY?.trim();
-    if (evmKey && !PLACEHOLDER_RE.test(evmKey)) {
+async function invokeAppStopRunHook(run, runtime) {
+    try {
+        const routeModule = await importAppRouteModule(run.appName);
+        if (typeof routeModule?.stopRun !== "function") {
+            return;
+        }
+        await routeModule.stopRun({
+            appName: run.appName,
+            launchUrl: run.launchUrl,
+            runtime,
+            viewer: run.viewer,
+            runId: run.runId,
+            session: run.session,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.warn(`[app-manager] stopRun hook for "${run.appName}" (runId=${run.runId}) failed: ${message}`);
+    }
+}
+async function prepareLaunch(appInfo, launchUrl, runtime) {
+    const routeModule = await importAppRouteModule(appInfo.name);
+    if (typeof routeModule?.prepareLaunch === "function") {
+        return ((await routeModule.prepareLaunch({
+            appName: appInfo.name,
+            launchUrl,
+            runtime,
+            viewer: null,
+        })) ?? {});
+    }
+    return {};
+}
+function mergePreparedViewer(base, override) {
+    return {
+        ...(base ?? {}),
+        ...override,
+        embedParams: {
+            ...(base?.embedParams ?? {}),
+            ...(override.embedParams ?? {}),
+        },
+    };
+}
+function applyLaunchPreparation(appInfo, preparation) {
+    const launchUrl = preparation.launchUrl !== undefined
+        ? (preparation.launchUrl ?? undefined)
+        : appInfo.launchUrl;
+    const viewer = preparation.viewer === undefined
+        ? appInfo.viewer
+        : preparation.viewer === null
+            ? undefined
+            : mergePreparedViewer(appInfo.viewer, preparation.viewer);
+    return {
+        ...appInfo,
+        launchUrl,
+        viewer,
+    };
+}
+function isRuntimePluginActive(appInfo, runtime) {
+    if (!runtime || !Array.isArray(runtime.plugins)) {
+        return false;
+    }
+    const pluginNames = new Set([
+        appInfo.name,
+        appInfo.runtimePlugin ?? resolvePluginPackageName(appInfo),
+    ]);
+    return runtime.plugins.some((plugin) => typeof plugin?.name === "string" && pluginNames.has(plugin.name));
+}
+function isRuntimePluginReady(appInfo, runtime) {
+    if (!isRuntimePluginActive(appInfo, runtime)) {
+        return false;
+    }
+    if (isHyperscapeAppName(appInfo.name)) {
+        return Boolean(runtime?.hasService?.("hyperscapeService") ||
+            runtime?.getService?.("hyperscapeService"));
+    }
+    return true;
+}
+function getRuntimePluginCandidates(appInfo) {
+    const candidates = [
+        appInfo.runtimePlugin,
+        appInfo.name,
+        resolvePluginPackageName(appInfo),
+    ];
+    return Array.from(new Set(candidates.filter((candidate) => typeof candidate === "string" && candidate.trim().length > 0)));
+}
+async function collectLaunchDiagnostics(appInfo, viewer, session, launchUrl, runtime) {
+    const routeModule = await importAppRouteModule(appInfo.name);
+    const diagnosticViewer = viewer && appInfo.viewer?.postMessageAuth && !viewer.authMessage
+        ? { ...viewer, postMessageAuth: true }
+        : viewer;
+    if (typeof routeModule?.collectLaunchDiagnostics === "function") {
+        return routeModule.collectLaunchDiagnostics({
+            appName: appInfo.name,
+            launchUrl,
+            runtime,
+            viewer: diagnosticViewer,
+            session,
+        });
+    }
+    return [];
+}
+async function ensureRuntimePluginRegistered(appInfo, runtime, isLocal) {
+    if (!runtime) {
+        return false;
+    }
+    if (isRuntimePluginReady(appInfo, runtime)) {
+        return true;
+    }
+    const pluginNames = getRuntimePluginCandidates(appInfo);
+    for (const pluginPackageName of pluginNames) {
+        let plugin = null;
         try {
-            evmAddress = deriveEvmAddress(evmKey);
+            plugin = await importAppPlugin(pluginPackageName);
         }
-        catch (e) {
-            logger.warn(`[app-manager] Bad EVM key: ${e}`);
+        catch (err) {
+            logger.warn(`[app-manager] importAppPlugin(${pluginPackageName}) threw: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        if (!plugin) {
+            continue;
         }
-    }
-    const solKey = runtime?.getSetting?.("SOLANA_PRIVATE_KEY")?.trim() || process.env.SOLANA_PRIVATE_KEY?.trim();
-    if (solKey && !PLACEHOLDER_RE.test(solKey)) {
         try {
-            solanaAddress = deriveSolanaAddress(solKey);
+            await runtime.registerPlugin(plugin);
         }
-        catch (e) {
-            logger.warn(`[app-manager] Bad SOL key: ${e}`);
+        catch (err) {
+            logger.warn(`[app-manager] registerPlugin(${plugin.name}) threw: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        if (isRuntimePluginReady(appInfo, runtime)) {
+            return true;
         }
     }
-    return { evmAddress, solanaAddress };
+    if (!isLocal) {
+        return false;
+    }
+    throw new Error(`Local runtime plugin for "${appInfo.name}" could not be loaded.`);
+}
+async function ensureRuntimeReady(appInfo, viewer, launchUrl, runtime) {
+    if (!runtime) {
+        return;
+    }
+    const routeModule = await importAppRouteModule(appInfo.name);
+    if (typeof routeModule?.ensureRuntimeReady !== "function") {
+        return;
+    }
+    const ctx = {
+        appName: appInfo.name,
+        launchUrl,
+        runtime,
+        viewer,
+    };
+    try {
+        await routeModule.ensureRuntimeReady(ctx);
+    }
+    catch (error) {
+        const pluginNames = getRuntimePluginCandidates(appInfo);
+        let recovered = false;
+        for (const pluginPackageName of pluginNames) {
+            const plugin = await importAppPlugin(pluginPackageName);
+            if (!plugin) {
+                continue;
+            }
+            await runtime.registerPlugin(plugin);
+            recovered = true;
+        }
+        if (!recovered) {
+            throw error;
+        }
+        await routeModule.ensureRuntimeReady(ctx);
+    }
+}
+function deriveRunHealth(status, summary) {
+    const normalized = status.trim().toLowerCase();
+    if (normalized === "running" ||
+        normalized === "connected" ||
+        normalized === "active") {
+        return {
+            state: "healthy",
+            message: summary,
+        };
+    }
+    if (normalized === "stopped" ||
+        normalized === "offline" ||
+        normalized === "error" ||
+        normalized === "failed") {
+        return {
+            state: "offline",
+            message: summary,
+        };
+    }
+    return {
+        state: "degraded",
+        message: summary,
+    };
+}
+function buildRunEvent(input) {
+    return {
+        eventId: crypto.randomUUID(),
+        kind: input.kind,
+        severity: input.severity ?? "info",
+        message: input.message,
+        createdAt: input.createdAt ?? new Date().toISOString(),
+        status: input.status ?? null,
+        details: input.details ?? null,
+    };
+}
+function normalizeRunEvents(events) {
+    return [...events]
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+        .slice(0, MAX_RUN_EVENTS);
+}
+function deriveChatAvailability(session) {
+    if (!session) {
+        return "unknown";
+    }
+    return session.canSendCommands ? "available" : "unavailable";
+}
+function deriveControlAvailability(session) {
+    if (!session) {
+        return "unknown";
+    }
+    return session.canSendCommands || (session.controls?.length ?? 0) > 0
+        ? "available"
+        : "unavailable";
+}
+function deriveHealthFacetState(availability) {
+    if (availability === "available") {
+        return "healthy";
+    }
+    if (availability === "unavailable") {
+        return "degraded";
+    }
+    return "unknown";
+}
+function deriveRunHealthDetails(run) {
+    const viewerState = !run.viewer
+        ? "unknown"
+        : run.viewerAttachment === "attached"
+            ? "healthy"
+            : run.viewerAttachment === "detached"
+                ? "degraded"
+                : "offline";
+    const authState = run.session
+        ? run.viewerAttachment === "attached" || run.viewer == null
+            ? "healthy"
+            : "degraded"
+        : "unknown";
+    return {
+        checkedAt: run.updatedAt,
+        auth: {
+            state: authState,
+            message: run.session?.summary ?? run.summary,
+        },
+        runtime: {
+            state: run.health.state,
+            message: run.health.message,
+        },
+        viewer: {
+            state: viewerState,
+            message: run.viewerAttachment === "attached"
+                ? "Viewer attached."
+                : run.viewerAttachment === "detached"
+                    ? "Viewer detached."
+                    : "Viewer unavailable.",
+        },
+        chat: {
+            state: deriveHealthFacetState(run.chatAvailability),
+            message: run.chatAvailability === "available"
+                ? "Operator chat is available."
+                : run.chatAvailability === "unavailable"
+                    ? "Operator chat is unavailable."
+                    : "Operator chat availability is unknown.",
+        },
+        control: {
+            state: deriveHealthFacetState(run.controlAvailability),
+            message: run.controlAvailability === "available"
+                ? "Control actions are available."
+                : run.controlAvailability === "unavailable"
+                    ? "Control actions are unavailable."
+                    : "Control availability is unknown.",
+        },
+        message: run.health.message,
+    };
+}
+function deriveAwaySummary(run) {
+    const recent = run.recentEvents.slice(0, 3).map((event) => event.message);
+    return {
+        generatedAt: run.updatedAt,
+        message: recent.length > 0
+            ? recent.join(" ")
+            : (run.summary ?? `${run.displayName} is ${run.status}.`),
+        eventCount: run.recentEvents.length,
+        since: run.recentEvents.at(-1)?.createdAt ?? run.startedAt,
+        until: run.recentEvents[0]?.createdAt ?? run.updatedAt,
+    };
+}
+function normalizeRunSummary(run) {
+    const status = run.session?.status ?? run.status;
+    const summary = run.session?.summary ?? run.summary;
+    const next = {
+        ...run,
+        characterId: run.characterId ?? run.session?.characterId ?? null,
+        agentId: run.agentId ?? run.session?.agentId ?? null,
+        chatAvailability: deriveChatAvailability(run.session),
+        controlAvailability: deriveControlAvailability(run.session),
+        supportsViewerDetach: typeof run.supportsViewerDetach === "boolean"
+            ? run.supportsViewerDetach
+            : Boolean(run.supportsBackground),
+        recentEvents: normalizeRunEvents(run.recentEvents),
+        status,
+        summary,
+        lastHeartbeatAt: run.session ? run.updatedAt : run.lastHeartbeatAt,
+        health: deriveRunHealth(status, summary),
+    };
+    return {
+        ...next,
+        awaySummary: deriveAwaySummary(next),
+        healthDetails: deriveRunHealthDetails(next),
+    };
+}
+function buildRunSummary(input) {
+    const now = new Date().toISOString();
+    const status = input.session?.status ?? (input.viewer ? "running" : "launching");
+    const summary = input.session?.summary ?? null;
+    const health = deriveRunHealth(status, summary);
+    return normalizeRunSummary({
+        runId: input.runId,
+        appName: input.appName,
+        displayName: input.displayName,
+        pluginName: input.pluginName,
+        launchType: input.launchType,
+        launchUrl: input.launchUrl,
+        viewer: input.viewer,
+        session: input.session,
+        characterId: input.session?.characterId ?? null,
+        agentId: input.session?.agentId ?? null,
+        status,
+        summary,
+        startedAt: input.startedAt ?? now,
+        updatedAt: now,
+        lastHeartbeatAt: input.session ? now : null,
+        supportsBackground: true,
+        viewerAttachment: input.viewerAttachment ?? (input.viewer ? "attached" : "unavailable"),
+        chatAvailability: deriveChatAvailability(input.session),
+        controlAvailability: deriveControlAvailability(input.session),
+        supportsViewerDetach: true,
+        recentEvents: [
+            buildRunEvent({
+                kind: "launch",
+                message: summary ??
+                    `${input.displayName} launched with ${input.viewer ? "a viewer" : "no viewer"}.`,
+                status,
+                details: {
+                    runId: input.runId,
+                    appName: input.appName,
+                    viewerAttachment: input.viewerAttachment ??
+                        (input.viewer ? "attached" : "unavailable"),
+                    characterId: input.session?.characterId ?? null,
+                    agentId: input.session?.agentId ?? null,
+                },
+            }),
+        ],
+        awaySummary: null,
+        health,
+        healthDetails: {
+            checkedAt: now,
+            auth: {
+                state: "unknown",
+                message: summary,
+            },
+            runtime: {
+                state: health.state,
+                message: summary,
+            },
+            viewer: {
+                state: "unknown",
+                message: null,
+            },
+            chat: {
+                state: "unknown",
+                message: null,
+            },
+            control: {
+                state: "unknown",
+                message: null,
+            },
+            message: summary,
+        },
+    });
+}
+function updateRunSummary(run, patch, event) {
+    const updatedAt = new Date().toISOString();
+    const next = normalizeRunSummary({
+        ...run,
+        ...patch,
+        updatedAt,
+        lastHeartbeatAt: patch.session ? updatedAt : run.lastHeartbeatAt,
+        recentEvents: event
+            ? normalizeRunEvents([
+                buildRunEvent({
+                    ...event,
+                    createdAt: updatedAt,
+                }),
+                ...run.recentEvents,
+            ])
+            : run.recentEvents,
+    });
+    return next;
+}
+function sameRunIdentity(run, appName, session, viewer) {
+    if (run.appName !== appName)
+        return false;
+    if (session?.sessionId && run.session?.sessionId === session.sessionId) {
+        return true;
+    }
+    return Boolean(viewer?.url && run.viewer?.url === viewer.url);
 }
 export class AppManager {
     activeSessions = new Map();
-    async listAvailable(pluginManager) {
-        const registry = await pluginManager.refreshRegistry();
-        // Merge in local workspace app entries that are discovered by our
-        // registry-client but not by the elizaos
-        // plugin-manager service.
+    knownAppNames = new Set();
+    runRefreshAt = new Map();
+    runRefreshInFlight = new Map();
+    stateDir;
+    heartbeatTimeoutMs;
+    heartbeatSweepIntervalMs;
+    appRuns = new Map();
+    sweeperTimer = null;
+    sweeperRuntimeFn = null;
+    sweeperReapInFlight = false;
+    constructor(options = {}) {
+        this.stateDir = options.stateDir;
+        this.heartbeatTimeoutMs =
+            options.heartbeatTimeoutMs ?? RUN_HEARTBEAT_TIMEOUT_MS;
+        this.heartbeatSweepIntervalMs =
+            options.heartbeatSweepIntervalMs ?? RUN_HEARTBEAT_SWEEP_INTERVAL_MS;
+        for (const run of readAppRunStore(this.stateDir)) {
+            this.appRuns.set(run.runId, run);
+            this.knownAppNames.add(run.appName);
+        }
+    }
+    /**
+     * Bump a run's `lastHeartbeatAt` to "now" without invoking any plugin
+     * routes. Returns the updated run, or `null` if the runId is unknown.
+     *
+     * The UI calls this on a short interval while the GameView is mounted so
+     * the sweeper knows the tab is still alive. When the tab goes away the
+     * heartbeat stops and {@link reapStaleRuns} reclaims the run after
+     * `heartbeatTimeoutMs`.
+     */
+    recordHeartbeat(runId) {
+        const run = this.appRuns.get(runId);
+        if (!run)
+            return null;
+        const now = new Date().toISOString();
+        const next = {
+            ...run,
+            lastHeartbeatAt: now,
+        };
+        this.appRuns.set(runId, next);
+        this.persistRuns();
+        return next;
+    }
+    /**
+     * Stop and remove every run whose last heartbeat is older than
+     * `heartbeatTimeoutMs`. Runs that never received a heartbeat (no UI ever
+     * attached) are reaped only once they are also older than the timeout to
+     * avoid racing with the launch -> first-poll window.
+     *
+     * For each reaped run the route module's `stopRun` hook is invoked the
+     * same way the explicit Stop button does — so plugins get a single,
+     * uniform shutdown path regardless of why a run is going away.
+     */
+    async reapStaleRuns(runtime, nowMs = Date.now()) {
+        const reaped = [];
+        for (const run of [...this.appRuns.values()]) {
+            const heartbeat = run.lastHeartbeatAt
+                ? Date.parse(run.lastHeartbeatAt)
+                : null;
+            const startedAt = Date.parse(run.startedAt);
+            const reference = heartbeat ?? startedAt;
+            if (!Number.isFinite(reference))
+                continue;
+            if (nowMs - reference < this.heartbeatTimeoutMs)
+                continue;
+            const removed = this.removeRun(run.runId);
+            if (!removed)
+                continue;
+            reaped.push(removed);
+            await invokeAppStopRunHook(removed, runtime);
+            logger.info(`[app-manager] Reaped stale app run "${removed.runId}" (${removed.appName}); ` +
+                `last heartbeat ${run.lastHeartbeatAt ?? "never"}`);
+        }
+        return reaped;
+    }
+    /**
+     * Start the periodic stale-run sweeper. Idempotent — calling twice does
+     * not start two timers. The runtime is resolved lazily via `getRuntime`
+     * so the sweeper picks up runtime changes (e.g. agent restart) without
+     * needing to be re-wired.
+     *
+     * The interval is wrapped in `unref()` so a stuck sweeper never keeps a
+     * Node process alive on shutdown.
+     */
+    startStaleRunSweeper(getRuntime) {
+        this.sweeperRuntimeFn = getRuntime;
+        if (this.sweeperTimer)
+            return;
+        this.sweeperTimer = setInterval(() => {
+            void this.runSweeperTick();
+        }, this.heartbeatSweepIntervalMs);
+        if (typeof this.sweeperTimer.unref === "function") {
+            this.sweeperTimer.unref();
+        }
+    }
+    /** Stop the periodic stale-run sweeper. Safe to call multiple times. */
+    stopStaleRunSweeper() {
+        if (!this.sweeperTimer)
+            return;
+        clearInterval(this.sweeperTimer);
+        this.sweeperTimer = null;
+    }
+    async runSweeperTick() {
+        if (this.sweeperReapInFlight)
+            return;
+        this.sweeperReapInFlight = true;
         try {
-            const localRegistry = await getRegistryPlugins();
-            for (const [name, info] of localRegistry) {
-                if (!registry.has(name) && info.kind === "app") {
-                    registry.set(name, info);
-                }
+            const runtime = this.sweeperRuntimeFn?.() ?? null;
+            await this.reapStaleRuns(runtime);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warn(`[app-manager] Stale-run sweeper failed: ${message}`);
+        }
+        finally {
+            this.sweeperReapInFlight = false;
+        }
+    }
+    persistRuns() {
+        writeAppRunStore(Array.from(this.appRuns.values()), this.stateDir);
+    }
+    listRunsSorted() {
+        return [...this.appRuns.values()].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }
+    storeRun(run) {
+        this.knownAppNames.add(run.appName);
+        this.appRuns.set(run.runId, run);
+        this.persistRuns();
+        return run;
+    }
+    removeRun(runId) {
+        const run = this.appRuns.get(runId) ?? null;
+        if (!run)
+            return null;
+        this.appRuns.delete(runId);
+        this.activeSessions.delete(runId);
+        this.runRefreshAt.delete(runId);
+        this.runRefreshInFlight.delete(runId);
+        this.persistRuns();
+        return run;
+    }
+    findRun(runId) {
+        return this.appRuns.get(runId) ?? null;
+    }
+    findMatchingRun(appName, session, viewer) {
+        for (const run of this.listRunsSorted()) {
+            if (sameRunIdentity(run, appName, session, viewer)) {
+                return run;
             }
         }
-        catch {
-            // local discovery is best-effort
+        return null;
+    }
+    shouldSkipRunRefresh(run, force) {
+        if (force)
+            return false;
+        const lastRefreshAt = this.runRefreshAt.get(run.runId) ?? 0;
+        return Date.now() - lastRefreshAt < RUN_REFRESH_MIN_INTERVAL_MS;
+    }
+    async refreshRunSession(run, runtime) {
+        const routeModule = await importAppRouteModule(run.appName);
+        if (typeof routeModule?.refreshRunSession !== "function") {
+            return run;
         }
-        // Include app packages: those with "/app-" in the name OR kind === "app"
-        const apps = Array.from(registry.values()).filter((plugin) => {
-            if (plugin.kind === "app")
-                return true;
-            const name = plugin.name.toLowerCase();
-            const npmPackage = plugin.npm.package.toLowerCase();
-            return name.includes("/app-") || npmPackage.includes("/app-");
-        });
-        // Flatten appMeta into top-level fields for the frontend
-        return apps.map((p) => {
-            const meta = p.appMeta;
-            if (!meta)
-                return p;
-            return {
-                ...p,
-                displayName: meta.displayName,
-                launchType: meta.launchType,
-                launchUrl: meta.launchUrl,
-                icon: meta.icon,
-                category: meta.category,
-                capabilities: meta.capabilities,
-                uiExtension: meta.uiExtension,
-                viewer: meta.viewer,
-            };
+        try {
+            const nextSession = await routeModule.refreshRunSession({
+                appName: run.appName,
+                launchUrl: run.launchUrl,
+                runtime,
+                viewer: run.viewer,
+                runId: run.runId,
+                session: run.session,
+            });
+            if (!nextSession) {
+                const summary = "Run session is no longer available.";
+                const nextRun = this.storeRun(updateRunSummary(run, {
+                    session: buildUnavailableSession(run, "offline", summary),
+                    status: "offline",
+                    summary,
+                }, {
+                    kind: "health",
+                    severity: "warning",
+                    message: summary,
+                    status: "offline",
+                    details: {
+                        runId: run.runId,
+                        appName: run.appName,
+                    },
+                }));
+                return nextRun;
+            }
+            const nextRun = this.storeRun(updateRunSummary(run, {
+                session: nextSession,
+                status: nextSession.status,
+                summary: nextSession.summary ?? run.summary,
+            }, {
+                kind: "refresh",
+                severity: nextSession.status === "running" ? "info" : "warning",
+                message: nextSession.summary ?? `${run.displayName} session refreshed.`,
+                status: nextSession.status,
+                details: {
+                    runId: run.runId,
+                    appName: run.appName,
+                    sessionId: nextSession.sessionId,
+                },
+            }));
+            return nextRun;
+        }
+        catch (error) {
+            const message = error instanceof Error
+                ? `Run verification failed: ${error.message}`
+                : "Run verification failed.";
+            const nextStatus = run.session ? "disconnected" : "offline";
+            const nextRun = this.storeRun(updateRunSummary(run, {
+                session: buildUnavailableSession(run, nextStatus, message),
+                status: nextStatus,
+                summary: message,
+            }, {
+                kind: "health",
+                severity: "error",
+                message,
+                status: nextStatus,
+                details: {
+                    runId: run.runId,
+                    appName: run.appName,
+                },
+            }));
+            return nextRun;
+        }
+    }
+    async refreshRun(run, runtime, options = {}) {
+        const force = options.force === true;
+        if (this.shouldSkipRunRefresh(run, force)) {
+            return this.findRun(run.runId) ?? run;
+        }
+        const inFlight = this.runRefreshInFlight.get(run.runId);
+        if (inFlight) {
+            return inFlight;
+        }
+        this.runRefreshAt.set(run.runId, Date.now());
+        const refreshPromise = this.refreshRunSession(run, runtime).finally(() => {
+            this.runRefreshInFlight.delete(run.runId);
         });
+        this.runRefreshInFlight.set(run.runId, refreshPromise);
+        return refreshPromise;
+    }
+    async listAvailable(pluginManager) {
+        void pluginManager;
+        const registry = await getRegistryPlugins();
+        const apps = curateCatalogApps(Array.from(registry.values()).filter(isAppRegistryPlugin));
+        return apps.map(flattenAppInfo);
     }
     async search(pluginManager, query, limit = 15) {
-        const results = await pluginManager.searchRegistry(query, limit);
-        // Filter to only include app packages
-        return results.filter((result) => {
-            const name = result.name.toLowerCase();
-            const npmPackage = result.npmPackage.toLowerCase();
-            return name.includes("/app-") || npmPackage.includes("/app-");
-        });
+        const appEntries = (await this.listAvailable(pluginManager)).map(flattenAppInfo);
+        const results = scoreEntries(appEntries, query, limit, (p) => [
+            p.appMeta?.displayName?.toLowerCase() ??
+                p.displayName?.toLowerCase() ??
+                "",
+        ], (p) => p.appMeta?.capabilities ?? p.capabilities ?? []);
+        return toSearchResults(results);
     }
     async getInfo(pluginManager, name) {
-        return pluginManager.getRegistryPlugin(name);
+        return ((await resolveCuratedAppInfo(pluginManager, name)) ??
+            (await resolveNamedAppInfo(pluginManager, name)));
+    }
+    async listRuns(runtime = null) {
+        const runs = this.listRunsSorted();
+        if (runs.length === 0) {
+            return runs;
+        }
+        const refreshed = await Promise.all(runs.map((run) => this.refreshRun(run, runtime)));
+        return refreshed.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }
+    async getRun(runId, runtime = null) {
+        const run = this.findRun(runId);
+        if (!run) {
+            return null;
+        }
+        return this.refreshRun(run, runtime, { force: true });
+    }
+    async attachRun(runId, runtime = null) {
+        const existingRun = this.findRun(runId);
+        const run = existingRun
+            ? await this.refreshRun(existingRun, runtime, { force: true })
+            : null;
+        if (!run) {
+            return {
+                success: false,
+                message: `App run "${runId}" was not found.`,
+            };
+        }
+        const updated = this.storeRun(updateRunSummary(run, {
+            viewerAttachment: run.viewer ? "attached" : "unavailable",
+        }, {
+            kind: "attach",
+            message: run.viewer
+                ? `${run.displayName} viewer attached.`
+                : `${run.displayName} viewer is unavailable.`,
+            status: run.session?.status ?? run.status,
+            details: {
+                runId: run.runId,
+                appName: run.appName,
+            },
+        }));
+        return {
+            success: true,
+            message: `${updated.displayName} attached.`,
+            run: updated,
+        };
+    }
+    async detachRun(runId) {
+        const run = this.findRun(runId);
+        if (!run) {
+            return {
+                success: false,
+                message: `App run "${runId}" was not found.`,
+            };
+        }
+        const updated = this.storeRun(updateRunSummary(run, {
+            viewerAttachment: run.viewer ? "detached" : "unavailable",
+        }, {
+            kind: "detach",
+            message: run.viewer
+                ? `${run.displayName} viewer detached.`
+                : `${run.displayName} viewer is unavailable.`,
+            status: run.session?.status ?? run.status,
+            details: {
+                runId: run.runId,
+                appName: run.appName,
+            },
+        }));
+        return {
+            success: true,
+            message: `${updated.displayName} detached.`,
+            run: updated,
+        };
     }
     /**
      * Launch an app: install its plugin (if needed) and return the viewer URL.
@@ -272,35 +1399,17 @@ export class AppManager {
      * handle this by showing "connecting..." while the runtime restarts.
      */
     async launch(pluginManager, name, onProgress, _runtime) {
-        let appInfo = (await pluginManager.getRegistryPlugin(name));
-        // Supplement with local registry metadata since the elizaos plugin-manager
-        // service doesn't include our local workspace app discovery.
-        try {
-            const localInfo = await getPluginInfo(name);
-            if (localInfo) {
-                const meta = localInfo.appMeta;
-                if (!appInfo) {
-                    appInfo = { ...localInfo };
-                    mergeAppMeta(appInfo, meta);
-                }
-                else if (meta && !appInfo.viewer) {
-                    // Merge local metadata into existing registry entry
-                    mergeAppMeta(appInfo, meta);
-                    appInfo.kind = localInfo.kind ?? appInfo.kind;
-                }
-            }
-        }
-        catch {
-            // local lookup is best-effort
-        }
+        let appInfo = (await resolveCuratedAppInfo(pluginManager, name)) ??
+            (await resolveNamedAppInfo(pluginManager, name));
         if (!appInfo) {
             throw new Error(`App "${name}" not found in the registry.`);
         }
+        const agentsListBeforeLaunch = readAgentsListSnapshot();
         // The app's plugin is what the agent needs to play the game.
         // It's the same npm package name as the app, or a separate plugin ref.
-        const pluginName = resolvePluginPackageName(appInfo);
+        const pluginName = appInfo.runtimePlugin ?? resolvePluginPackageName(appInfo);
         // Check if this is a local plugin (already present in plugins/ directory)
-        const isLocal = isLocalPlugin(appInfo);
+        const isLocal = Boolean(appInfo.localPath) || isLocalPlugin(appInfo);
         // Check if the plugin is already installed
         const installed = await pluginManager.listInstalledPlugins();
         const alreadyInstalled = installed.some((p) => p.name === pluginName);
@@ -313,10 +1422,30 @@ export class AppManager {
         else if (!alreadyInstalled) {
             if (isAutoInstallable(appInfo)) {
                 logger.info(`[app-manager] Installing plugin for app: ${pluginName}`);
-                const result = await pluginManager.installPlugin(pluginName, onProgress);
+                let result = await pluginManager
+                    .installPlugin(pluginName, onProgress)
+                    .catch((err) => ({
+                    success: false,
+                    pluginName,
+                    version: "",
+                    installPath: "",
+                    requiresRestart: false,
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+                if (!result.success &&
+                    (result.error?.includes("requires a running agent runtime") ||
+                        !_runtime)) {
+                    // Runtime plugin manager unavailable — fall back to the direct
+                    // installer which writes to ~/.eliza/plugins/installed and can be
+                    // picked up by the app-package-modules resolver without restart.
+                    const { installPlugin: installPluginDirect } = await import(
+                    /* webpackIgnore: true */ "./plugin-installer.js");
+                    result = await installPluginDirect(pluginName, onProgress);
+                }
                 if (!result.success) {
                     throw new Error(`Failed to install plugin "${pluginName}": ${result.error}`);
                 }
+                restoreAgentsListAfterAppLaunchIfNeeded(agentsListBeforeLaunch, name, "plugin install");
                 pluginInstalled = true;
                 needsRestart = result.requiresRestart;
                 logger.info(`[app-manager] Plugin installed: ${pluginName} v${result.version}`);
@@ -328,9 +1457,21 @@ export class AppManager {
         else {
             logger.info(`[app-manager] Plugin already installed: ${pluginName}`);
         }
-        // Build viewer config from registry app metadata
+        const initialLaunchUrl = appInfo.launchUrl
+            ? normalizeSafeAppUrl(substituteTemplateVars(appInfo.launchUrl, {
+                preserveUnknown: false,
+                hyperscapeClientDefault: true,
+            }))
+            : null;
+        const launchPreparation = await prepareLaunch(appInfo, initialLaunchUrl, _runtime ?? null);
+        restoreAgentsListAfterAppLaunchIfNeeded(agentsListBeforeLaunch, name, "launch preparation");
+        const launchPreparationDiagnostics = launchPreparation.diagnostics ?? [];
+        appInfo = applyLaunchPreparation(appInfo, launchPreparation);
         const resolvedLaunchUrl = appInfo.launchUrl
-            ? substituteTemplateVars(appInfo.launchUrl)
+            ? substituteTemplateVars(appInfo.launchUrl, {
+                preserveUnknown: false,
+                hyperscapeClientDefault: true,
+            })
             : null;
         const launchUrl = resolvedLaunchUrl
             ? normalizeSafeAppUrl(resolvedLaunchUrl)
@@ -338,15 +1479,94 @@ export class AppManager {
         if (resolvedLaunchUrl && !launchUrl) {
             throw new Error(`Refusing to launch app "${appInfo.name}": unsafe launch URL`);
         }
-        const viewer = buildViewerConfig(appInfo, launchUrl);
-        this.activeSessions.set(name, {
+        const skipPluginRegistration = launchPreparation.skipRuntimePluginRegistration === true;
+        let runtimePluginRegistered = false;
+        if (!skipPluginRegistration) {
+            runtimePluginRegistered = await ensureRuntimePluginRegistered(appInfo, _runtime ?? null, isLocal);
+            restoreAgentsListAfterAppLaunchIfNeeded(agentsListBeforeLaunch, name, "runtime plugin registration");
+        }
+        if (runtimePluginRegistered) {
+            pluginInstalled = true;
+        }
+        const viewer = await buildViewerConfig(appInfo, launchUrl, _runtime);
+        const runtimeReadyDiagnostics = [];
+        try {
+            await ensureRuntimeReady(appInfo, viewer, launchUrl, _runtime ?? null);
+        }
+        catch (readyError) {
+            const message = readyError instanceof Error ? readyError.message : String(readyError);
+            logger.warn(`[app-manager] ensureRuntimeReady(${appInfo.name}) failed: ${message}`);
+            runtimeReadyDiagnostics.push({
+                code: "runtime-service-unavailable",
+                severity: "warning",
+                message: `${appInfo.displayName ?? appInfo.name} runtime service could not initialize: ${message}. The viewer will open but live agent control may be unavailable until the underlying service is reachable.`,
+            });
+        }
+        // Build viewer config from registry app metadata
+        let session;
+        try {
+            session = viewer
+                ? await resolveLaunchSession(appInfo, viewer, launchUrl, _runtime ?? null)
+                : buildAppSession(appInfo, undefined, _runtime);
+        }
+        catch (sessionError) {
+            const message = sessionError instanceof Error
+                ? sessionError.message
+                : String(sessionError);
+            logger.warn(`[app-manager] resolveLaunchSession(${appInfo.name}) failed: ${message}`);
+            runtimeReadyDiagnostics.push({
+                code: "session-resolve-failed",
+                severity: "warning",
+                message: `Could not resolve launch session for ${appInfo.displayName ?? appInfo.name}: ${message}.`,
+            });
+            session = buildAppSession(appInfo, undefined, _runtime);
+        }
+        const diagnostics = [
+            ...launchPreparationDiagnostics,
+            ...runtimeReadyDiagnostics,
+            ...(await collectLaunchDiagnostics(appInfo, viewer, session, launchUrl, _runtime ?? null)),
+        ];
+        const existingRun = this.findMatchingRun(name, session, viewer);
+        const run = this.storeRun(existingRun
+            ? updateRunSummary(existingRun, {
+                displayName: appInfo.displayName ?? appInfo.name,
+                pluginName,
+                launchType: appInfo.launchType ?? "connect",
+                launchUrl,
+                viewer,
+                session,
+                viewerAttachment: viewer ? "attached" : "unavailable",
+            }, {
+                kind: "refresh",
+                message: session?.summary ??
+                    `${appInfo.displayName ?? appInfo.name} launch state refreshed.`,
+                status: session?.status ?? (viewer ? "running" : "launching"),
+                details: {
+                    runId: existingRun.runId,
+                    appName: name,
+                    sessionId: session?.sessionId ?? null,
+                },
+            })
+            : buildRunSummary({
+                runId: crypto.randomUUID(),
+                appName: name,
+                displayName: appInfo.displayName ?? appInfo.name,
+                pluginName,
+                launchType: appInfo.launchType ?? "connect",
+                launchUrl,
+                viewer,
+                session,
+            }));
+        this.activeSessions.set(run.runId, {
+            runId: run.runId,
             appName: name,
             pluginName,
             launchType: appInfo.launchType ?? "connect",
             launchUrl,
             viewerUrl: viewer?.url ?? null,
-            startedAt: new Date().toISOString(),
+            startedAt: run.startedAt,
         });
+        restoreAgentsListAfterAppLaunchIfNeeded(agentsListBeforeLaunch, name, "launch");
         return {
             pluginInstalled,
             needsRestart,
@@ -354,72 +1574,105 @@ export class AppManager {
             launchType: appInfo.launchType ?? "connect",
             launchUrl,
             viewer,
+            session,
+            run,
+            diagnostics,
         };
     }
-    async stop(pluginManager, name) {
-        const appInfo = (await pluginManager.getRegistryPlugin(name));
-        if (!appInfo) {
-            throw new Error(`App "${name}" not found in the registry.`);
-        }
-        const hadSession = this.activeSessions.delete(name);
-        const pluginName = resolvePluginPackageName(appInfo);
-        const installed = await pluginManager.listInstalledPlugins();
-        const isPluginInstalled = installed.some((plugin) => plugin.name === pluginName);
-        if (!hadSession && !isPluginInstalled) {
+    async stop(pluginManager, name, runId, runtime) {
+        const stoppedAt = new Date().toISOString();
+        if (runId) {
+            const removedRun = this.removeRun(runId);
+            if (!removedRun) {
+                return {
+                    success: false,
+                    appName: name,
+                    runId,
+                    stoppedAt,
+                    pluginUninstalled: false,
+                    needsRestart: false,
+                    stopScope: "no-op",
+                    message: `App run "${runId}" was not found.`,
+                };
+            }
+            await invokeAppStopRunHook(removedRun, runtime ?? null);
             return {
-                success: false,
-                appName: name,
-                stoppedAt: new Date().toISOString(),
+                success: true,
+                appName: removedRun.appName,
+                runId: removedRun.runId,
+                stoppedAt,
                 pluginUninstalled: false,
                 needsRestart: false,
-                stopScope: "no-op",
-                message: `No active session or installed plugin found for "${name}".`,
+                stopScope: "viewer-session",
+                message: `${removedRun.displayName} stopped.`,
             };
         }
-        if (isPluginInstalled) {
-            const uninstallResult = await pluginManager.uninstallPlugin(pluginName);
-            if (!uninstallResult.success) {
-                throw new Error(`Failed to stop "${name}": ${uninstallResult.error ?? "plugin uninstall failed"}`);
+        const runsForApp = this.listRunsSorted().filter((run) => run.appName === name);
+        if (runsForApp.length === 0) {
+            if (!this.knownAppNames.has(name)) {
+                const appInfo = (await pluginManager.getRegistryPlugin(name));
+                if (!appInfo) {
+                    throw new Error(`App "${name}" not found in the registry.`);
+                }
+                this.knownAppNames.add(name);
             }
             return {
-                success: true,
+                success: false,
                 appName: name,
-                stoppedAt: new Date().toISOString(),
-                pluginUninstalled: true,
-                needsRestart: uninstallResult.requiresRestart,
-                stopScope: "plugin-uninstalled",
-                message: uninstallResult.requiresRestart
-                    ? `${name} disconnected and plugin uninstalled. Agent restart required.`
-                    : `${name} disconnected and plugin uninstalled.`,
+                runId: null,
+                stoppedAt,
+                pluginUninstalled: false,
+                needsRestart: false,
+                stopScope: "no-op",
+                message: `No active app run found for "${name}".`,
             };
         }
+        for (const run of runsForApp) {
+            this.removeRun(run.runId);
+            await invokeAppStopRunHook(run, runtime ?? null);
+        }
         return {
             success: true,
             appName: name,
-            stoppedAt: new Date().toISOString(),
+            runId: null,
+            stoppedAt,
             pluginUninstalled: false,
             needsRestart: false,
             stopScope: "viewer-session",
-            message: `${name} viewer session stopped.`,
+            message: runsForApp.length === 1
+                ? `${runsForApp[0]?.displayName ?? name} stopped.`
+                : `${runsForApp.length} app runs stopped for "${name}".`,
         };
     }
     /** List apps whose plugins are currently installed on the agent. */
     async listInstalled(pluginManager) {
         const installed = await pluginManager.listInstalledPlugins();
-        // Filter to only include app plugins (by name convention or known game plugins)
-        const appPlugins = installed.filter((p) => {
-            const name = p.name.toLowerCase();
-            return name.includes("/app-");
-        });
-        return appPlugins.map((p) => ({
-            name: p.name,
-            displayName: p.name
-                .replace(/^@elizaos\/(app-|plugin-)/, "")
-                .replace(/-/g, " ")
-                .replace(/\b\w/g, (c) => c.toUpperCase()),
-            pluginName: p.name,
-            version: p.version ?? "unknown",
-            installedAt: new Date().toISOString(), // Ejected plugins don't track install time yet
-        }));
+        const registry = await getRegistryPlugins();
+        const refreshedRegistry = await withTimeout(pluginManager.refreshRegistry(), resolveRegistryRefreshTimeoutMs(), "app registry refresh").catch(() => new Map());
+        const mergedRegistry = new Map(registry);
+        for (const [name, info] of refreshedRegistry.entries()) {
+            if (!mergedRegistry.has(name)) {
+                mergedRegistry.set(name, info);
+            }
+        }
+        const installedByName = new Map(installed.map((plugin) => [plugin.name, plugin]));
+        const appEntries = Array.from(mergedRegistry.values())
+            .filter(isAppRegistryPlugin)
+            .map(flattenAppInfo);
+        return appEntries
+            .map((appInfo) => {
+            const pluginName = appInfo.runtimePlugin ?? resolvePluginPackageName(appInfo);
+            const installedPlugin = installedByName.get(pluginName) ?? installedByName.get(appInfo.name);
+            if (!installedPlugin)
+                return null;
+            return {
+                name: appInfo.name,
+                displayName: appInfo.displayName ?? packageNameToAppDisplayName(appInfo.name),
+                pluginName,
+                version: installedPlugin.version ?? "unknown",
+                installedAt: installedPlugin.installedAt ?? "",
+            };
+        })
+            .filter((app) => app !== null);
     }
 }