@elizaos/agent 2.0.0-alpha.97 → 2.0.0-beta.1

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

@@ -0,0 +1,1678 @@
+/**
+ * App Manager — manages app lifecycle: discover, install plugin, show viewer.
+ *
+ * Apps are hosted services. The manager's job is:
+ * 1. List/search apps from the registry
+ * 2. Install the game's plugin onto the agent (triggers restart)
+ * 3. Return the viewer URL so the UI can embed the game client in an iframe
+ *
+ * @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 { 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 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 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;
+}
+function mergeAppMeta(appInfo, meta) {
+    if (!meta)
+        return;
+    appInfo.viewer = meta.viewer ?? appInfo.viewer;
+    appInfo.launchUrl = meta.launchUrl ?? appInfo.launchUrl;
+    appInfo.launchType = meta.launchType ?? appInfo.launchType;
+    appInfo.displayName = meta.displayName ?? appInfo.displayName;
+    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;
+    const hasVersion = Boolean(appInfo.npm.v0Version || appInfo.npm.v1Version || appInfo.npm.v2Version);
+    return supportsRuntime && hasVersion;
+}
+/**
+ * Check if a plugin exists locally in the plugins/ directory.
+ * Local plugins don't need to be installed - they're already available.
+ */
+function isLocalPlugin(appInfo) {
+    const pluginsDir = path.resolve(process.cwd(), LOCAL_PLUGINS_DIR);
+    if (!fs.existsSync(pluginsDir)) {
+        return false;
+    }
+    // Check for directory names that match the app
+    // E.g., @elizaos/app-babylon -> app-babylon
+    const bareName = appInfo.name.replace(/^@[^/]+\//, "");
+    const possibleDirs = [bareName, appInfo.name.replace("/", "-")];
+    for (const dirName of possibleDirs) {
+        const pluginPath = path.join(pluginsDir, dirName);
+        const pluginJsonPath = path.join(pluginPath, "elizaos.plugin.json");
+        if (fs.existsSync(pluginJsonPath)) {
+            return true;
+        }
+    }
+    return false;
+}
+function getTemplateFallbackValue(key) {
+    if (key === "RS_SDK_BOT_NAME") {
+        const runtimeBotName = process.env.BOT_NAME?.trim();
+        if (runtimeBotName && runtimeBotName.length > 0) {
+            return runtimeBotName;
+        }
+        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 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) => {
+        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;
+        }
+        return preserveUnknown ? `{${key}}` : "";
+    });
+}
+function buildViewerUrl(baseUrl, embedParams, runtime) {
+    if (!embedParams || Object.keys(embedParams).length === 0) {
+        return substituteTemplateVars(baseUrl, {
+            preserveUnknown: false,
+            hyperscapeClientDefault: true,
+            runtime,
+        });
+    }
+    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)) {
+        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)
+        return null;
+    if (trimmed.startsWith("/")) {
+        // Disallow protocol-relative form (`//evil.test`) which escapes same-origin.
+        return trimmed.startsWith("//") ? null : trimmed;
+    }
+    try {
+        const parsed = new URL(trimmed);
+        if (!SAFE_APP_URL_PROTOCOLS.has(parsed.protocol)) {
+            return null;
+        }
+        return trimmed;
+    }
+    catch {
+        return null;
+    }
+}
+async function buildViewerAuthMessage(appInfo, launchUrl, runtime) {
+    const postMessageAuth = appInfo.viewer?.postMessageAuth;
+    if (!postMessageAuth)
+        return undefined;
+    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;
+}
+async function buildViewerConfig(appInfo, launchUrl, runtime) {
+    const viewerInfo = appInfo.viewer;
+    if (viewerInfo) {
+        const requestedPostMessageAuth = Boolean(viewerInfo.postMessageAuth);
+        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 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: finalEmbedParams,
+            postMessageAuth,
+            sandbox: viewerInfo.sandbox ?? DEFAULT_VIEWER_SANDBOX,
+            authMessage,
+        };
+    }
+    if ((appInfo.launchType === "connect" || appInfo.launchType === "local") &&
+        launchUrl) {
+        const viewerUrl = normalizeSafeAppUrl(launchUrl);
+        if (!viewerUrl) {
+            throw new Error(`Refusing to launch app "${appInfo.name}": unsafe launch URL`);
+        }
+        return {
+            url: viewerUrl,
+            sandbox: DEFAULT_VIEWER_SANDBOX,
+        };
+    }
+    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);
+}
+/**
+ * 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.
+ */
+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 {
+            plugin = await importAppPlugin(pluginPackageName);
+        }
+        catch (err) {
+            logger.warn(`[app-manager] importAppPlugin(${pluginPackageName}) threw: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        if (!plugin) {
+            continue;
+        }
+        try {
+            await runtime.registerPlugin(plugin);
+        }
+        catch (err) {
+            logger.warn(`[app-manager] registerPlugin(${plugin.name}) threw: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        if (isRuntimePluginReady(appInfo, runtime)) {
+            return true;
+        }
+    }
+    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();
+    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 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;
+            }
+        }
+        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;
+        }
+        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 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 ((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.
+     *
+     * The plugin connects the agent to the game server. The viewer URL is what
+     * the UI shows in an iframe so the user can watch the agent play.
+     *
+     * After installing a new plugin, the agent needs to restart. The UI should
+     * handle this by showing "connecting..." while the runtime restarts.
+     */
+    async launch(pluginManager, name, onProgress, _runtime) {
+        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 = appInfo.runtimePlugin ?? resolvePluginPackageName(appInfo);
+        // Check if this is a local plugin (already present in plugins/ directory)
+        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);
+        let pluginInstalled = alreadyInstalled || isLocal;
+        let needsRestart = false;
+        if (isLocal) {
+            // Local plugins are already available, no installation needed
+            logger.info(`[app-manager] Using local plugin for ${name}: ${pluginName}`);
+        }
+        else if (!alreadyInstalled) {
+            if (isAutoInstallable(appInfo)) {
+                logger.info(`[app-manager] Installing plugin for app: ${pluginName}`);
+                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}`);
+            }
+            else {
+                logger.info(`[app-manager] Skipping plugin install for ${name}: no installable runtime package/version in registry metadata.`);
+            }
+        }
+        else {
+            logger.info(`[app-manager] Plugin already installed: ${pluginName}`);
+        }
+        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, {
+                preserveUnknown: false,
+                hyperscapeClientDefault: true,
+            })
+            : null;
+        const launchUrl = resolvedLaunchUrl
+            ? normalizeSafeAppUrl(resolvedLaunchUrl)
+            : null;
+        if (resolvedLaunchUrl && !launchUrl) {
+            throw new Error(`Refusing to launch app "${appInfo.name}": unsafe launch URL`);
+        }
+        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: run.startedAt,
+        });
+        restoreAgentsListAfterAppLaunchIfNeeded(agentsListBeforeLaunch, name, "launch");
+        return {
+            pluginInstalled,
+            needsRestart,
+            displayName: appInfo.displayName ?? appInfo.name,
+            launchType: appInfo.launchType ?? "connect",
+            launchUrl,
+            viewer,
+            session,
+            run,
+            diagnostics,
+        };
+    }
+    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: true,
+                appName: removedRun.appName,
+                runId: removedRun.runId,
+                stoppedAt,
+                pluginUninstalled: false,
+                needsRestart: false,
+                stopScope: "viewer-session",
+                message: `${removedRun.displayName} stopped.`,
+            };
+        }
+        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: false,
+                appName: name,
+                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,
+            runId: null,
+            stoppedAt,
+            pluginUninstalled: false,
+            needsRestart: false,
+            stopScope: "viewer-session",
+            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();
+        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);
+    }
+}