@elizaos/autonomous 2.0.0-alpha.37

package/dist/packages/autonomous/src/services/app-manager.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 type { IAgentRuntime } from "@elizaos/core";
+import type { AppLaunchResult, AppStopResult, InstalledAppInfo } from "../contracts/apps";
+import type { InstallProgressLike, PluginManagerLike, RegistryPluginInfo, RegistrySearchResult } from "./plugin-manager-types";
+export type { AppLaunchResult, AppStopResult, AppViewerAuthMessage, InstalledAppInfo, } from "../contracts/apps";
+export declare class AppManager {
+    private readonly activeSessions;
+    listAvailable(pluginManager: PluginManagerLike): Promise<RegistryPluginInfo[]>;
+    search(pluginManager: PluginManagerLike, query: string, limit?: number): Promise<RegistrySearchResult[]>;
+    getInfo(pluginManager: PluginManagerLike, name: string): Promise<RegistryPluginInfo | null>;
+    /**
+     * 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.
+     */
+    launch(pluginManager: PluginManagerLike, name: string, onProgress?: (progress: InstallProgressLike) => void, runtime?: IAgentRuntime | null): Promise<AppLaunchResult>;
+    stop(pluginManager: PluginManagerLike, name: string): Promise<AppStopResult>;
+    /** List apps whose plugins are currently installed on the agent. */
+    listInstalled(pluginManager: PluginManagerLike): Promise<InstalledAppInfo[]>;
+}
+//# sourceMappingURL=app-manager.d.ts.map

package/dist/packages/autonomous/src/services/app-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-manager.d.ts","sourceRoot":"","sources":["../../../../../src/services/app-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EAEb,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAEV,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC;AAKhC,YAAY,EACV,eAAe,EACf,aAAa,EACb,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AA8a3B,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuC;IAEhE,aAAa,CACjB,aAAa,EAAE,iBAAiB,GAC/B,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAwC1B,MAAM,CACV,aAAa,EAAE,iBAAiB,EAChC,KAAK,EAAE,MAAM,EACb,KAAK,SAAK,GACT,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAU5B,OAAO,CACX,aAAa,EAAE,iBAAiB,EAChC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAIrC;;;;;;;;OAQG;IACG,MAAM,CACV,aAAa,EAAE,iBAAiB,EAChC,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,EACpD,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,GAC7B,OAAO,CAAC,eAAe,CAAC;IA6HrB,IAAI,CACR,aAAa,EAAE,iBAAiB,EAChC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,aAAa,CAAC;IAyDzB,oEAAoE;IAC9D,aAAa,CACjB,aAAa,EAAE,iBAAiB,GAC/B,OAAO,CAAC,gBAAgB,EAAE,CAAC;CAkB/B"}

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

@@ -0,0 +1,543 @@
+/**
+ * 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 * 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";
+const LOCAL_PLUGINS_DIR = "plugins";
+const DEFAULT_VIEWER_SANDBOX = "allow-scripts allow-same-origin allow-popups";
+const HYPERSCAPE_APP_NAME = "@elizaos/app-hyperscape";
+const HYPERSCAPE_AUTH_MESSAGE_TYPE = "HYPERSCAPE_AUTH";
+const RS_2004SCAPE_APP_NAME = "@elizaos/app-2004scape";
+const RS_2004SCAPE_AUTH_MESSAGE_TYPE = "RS_2004SCAPE_AUTH";
+const SAFE_APP_URL_PROTOCOLS = new Set(["http:", "https:"]);
+const ALLOWED_APP_URL_TEMPLATE_KEYS = new Set([
+    // Public display identity only.
+    "BOT_NAME",
+    "RS_SDK_BOT_NAME",
+    // Non-secret endpoint routing values.
+    "HYPERSCAPE_CLIENT_URL",
+    "HYPERSCAPE_SERVER_URL",
+]);
+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;
+}
+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-hyperscape -> app-hyperscape
+    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 "testbot";
+    }
+    // Hyperscape client URL defaults to localhost:3333
+    if (key === "HYPERSCAPE_CLIENT_URL") {
+        return "http://localhost:3333";
+    }
+    // Hyperscape server URL defaults to localhost:5555
+    if (key === "HYPERSCAPE_SERVER_URL") {
+        return "ws://localhost:5555/ws";
+    }
+    return undefined;
+}
+function substituteTemplateVars(raw) {
+    return raw.replace(/\{([A-Z0-9_]+)\}/g, (_full, key) => {
+        if (!ALLOWED_APP_URL_TEMPLATE_KEYS.has(key)) {
+            return getTemplateFallbackValue(key) ?? "";
+        }
+        const value = process.env[key];
+        if (value && value.trim().length > 0) {
+            return value.trim();
+        }
+        return getTemplateFallbackValue(key) ?? "";
+    });
+}
+function buildViewerUrl(baseUrl, embedParams) {
+    if (!embedParams || Object.keys(embedParams).length === 0) {
+        return substituteTemplateVars(baseUrl);
+    }
+    const resolvedBaseUrl = substituteTemplateVars(baseUrl);
+    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 query = queryParams.toString();
+    const hash = hashPartRaw ? `#${hashPartRaw}` : "";
+    return `${pathPart}${query.length > 0 ? `?${query}` : ""}${hash}`;
+}
+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;
+    }
+}
+function buildViewerAuthMessage(appName, postMessageAuth) {
+    if (!postMessageAuth)
+        return undefined;
+    // Hyperscape auth
+    if (appName === HYPERSCAPE_APP_NAME) {
+        const authToken = process.env.HYPERSCAPE_AUTH_TOKEN?.trim();
+        const characterId = process.env.HYPERSCAPE_CHARACTER_ID?.trim();
+        // Need at least authToken OR characterId for spectator mode
+        if (!authToken && !characterId)
+            return undefined;
+        const sessionToken = process.env.HYPERSCAPE_SESSION_TOKEN?.trim();
+        const agentId = process.env.HYPERSCAPE_EMBED_AGENT_ID?.trim();
+        return {
+            type: HYPERSCAPE_AUTH_MESSAGE_TYPE,
+            authToken: authToken || undefined,
+            characterId: characterId || undefined,
+            sessionToken: sessionToken && sessionToken.length > 0 ? sessionToken : undefined,
+            agentId: agentId && agentId.length > 0 ? agentId : 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
+        };
+    }
+    return undefined;
+}
+function buildViewerConfig(appInfo, launchUrl) {
+    const viewerInfo = appInfo.viewer;
+    if (viewerInfo) {
+        const requestedPostMessageAuth = Boolean(viewerInfo.postMessageAuth);
+        const authMessage = buildViewerAuthMessage(appInfo.name, requestedPostMessageAuth);
+        const postMessageAuth = requestedPostMessageAuth && Boolean(authMessage);
+        if (requestedPostMessageAuth && !authMessage) {
+            if (appInfo.name === HYPERSCAPE_APP_NAME) {
+                logger.info(`[app-manager] ${appInfo.name} auth token not configured; launching embedded viewer without postMessage auth.`);
+            }
+            else {
+                logger.warn(`[app-manager] ${appInfo.name} requires postMessage auth but no auth payload was generated.`);
+            }
+        }
+        const viewerUrl = normalizeSafeAppUrl(buildViewerUrl(viewerInfo.url, viewerInfo.embedParams));
+        if (!viewerUrl) {
+            throw new Error(`Refusing to launch app "${appInfo.name}": unsafe viewer URL`);
+        }
+        return {
+            url: viewerUrl,
+            embedParams: viewerInfo.embedParams,
+            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;
+}
+/**
+ * Get wallet addresses from agent runtime settings (character secrets).
+ * Falls back to process.env if runtime is not available.
+ */
+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)) {
+        try {
+            evmAddress = deriveEvmAddress(evmKey);
+        }
+        catch (e) {
+            logger.warn(`[app-manager] Bad EVM key: ${e}`);
+        }
+    }
+    const solKey = runtime?.getSetting?.("SOLANA_PRIVATE_KEY")?.trim() || process.env.SOLANA_PRIVATE_KEY?.trim();
+    if (solKey && !PLACEHOLDER_RE.test(solKey)) {
+        try {
+            solanaAddress = deriveSolanaAddress(solKey);
+        }
+        catch (e) {
+            logger.warn(`[app-manager] Bad SOL key: ${e}`);
+        }
+    }
+    return { evmAddress, solanaAddress };
+}
+/**
+ * Auto-provision a hyperscape agent using wallet-based authentication.
+ * The agent's wallet address becomes its identity - no manual registration needed.
+ * Uses agent.character.settings.secrets for wallet credentials.
+ */
+async function autoProvisionHyperscapeAgent(runtime) {
+    // Check if already configured (from runtime settings or env)
+    const existingCharId = runtime?.getSetting?.("HYPERSCAPE_CHARACTER_ID")?.trim() || process.env.HYPERSCAPE_CHARACTER_ID?.trim();
+    const existingToken = runtime?.getSetting?.("HYPERSCAPE_AUTH_TOKEN")?.trim() || process.env.HYPERSCAPE_AUTH_TOKEN?.trim();
+    if (existingCharId && existingToken) {
+        logger.info(`[app-manager] Hyperscape already configured with character: ${existingCharId}`);
+        return { characterId: existingCharId, authToken: existingToken };
+    }
+    // Derive wallet addresses from runtime settings (character secrets)
+    const walletAddresses = getWalletAddressesFromRuntime(runtime);
+    const walletAddress = walletAddresses.evmAddress || walletAddresses.solanaAddress;
+    if (!walletAddress) {
+        logger.warn("[app-manager] No wallet address found for hyperscape auto-auth (need EVM_PRIVATE_KEY or SOLANA_PRIVATE_KEY in character secrets)");
+        return null;
+    }
+    const walletType = walletAddresses.evmAddress ? "evm" : "solana";
+    // Get server URL for API calls (from runtime settings or env)
+    const serverUrl = runtime?.getSetting?.("HYPERSCAPE_SERVER_URL")?.trim() ||
+        process.env.HYPERSCAPE_SERVER_URL?.trim() ||
+        "ws://localhost:5555/ws";
+    const apiBaseUrl = serverUrl
+        .replace(/^ws:/, "http:")
+        .replace(/^wss:/, "https:")
+        .replace(/\/ws$/, "");
+    // Get agent name from runtime or env
+    const agentName = runtime?.character?.name ||
+        runtime?.getSetting?.("BOT_NAME")?.trim() ||
+        process.env.BOT_NAME ||
+        "Agent";
+    try {
+        logger.info(`[app-manager] Auto-provisioning hyperscape agent with wallet: ${walletAddress.slice(0, 10)}...`);
+        // Authenticate using wallet address
+        const response = await fetch(`${apiBaseUrl}/api/agents/wallet-auth`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                walletAddress,
+                walletType,
+                agentName,
+            }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => "Unknown error");
+            logger.warn(`[app-manager] Hyperscape wallet auth failed: ${response.status} ${errorText}`);
+            return null;
+        }
+        const result = (await response.json());
+        if (!result.success || !result.authToken || !result.characterId) {
+            logger.warn("[app-manager] Hyperscape wallet auth returned failure");
+            return null;
+        }
+        // Set environment variables for the plugin and viewer
+        // (These are still needed for other parts of the system that read from env)
+        process.env.HYPERSCAPE_CHARACTER_ID = result.characterId;
+        process.env.HYPERSCAPE_AUTH_TOKEN = result.authToken;
+        logger.info(`[app-manager] Auto-provisioned hyperscape agent: ${result.characterId}`);
+        return { characterId: result.characterId, authToken: result.authToken };
+    }
+    catch (error) {
+        logger.warn(`[app-manager] Failed to auto-provision hyperscape agent: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+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.
+        try {
+            const localRegistry = await getRegistryPlugins();
+            for (const [name, info] of localRegistry) {
+                if (!registry.has(name) && info.kind === "app") {
+                    registry.set(name, info);
+                }
+            }
+        }
+        catch {
+            // local discovery is best-effort
+        }
+        // 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,
+            };
+        });
+    }
+    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-");
+        });
+    }
+    async getInfo(pluginManager, name) {
+        return pluginManager.getRegistryPlugin(name);
+    }
+    /**
+     * 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 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
+        }
+        if (!appInfo) {
+            throw new Error(`App "${name}" not found in the registry.`);
+        }
+        // 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);
+        // Check if this is a local plugin (already present in plugins/ directory)
+        const isLocal = 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}`);
+                const result = await pluginManager.installPlugin(pluginName, onProgress);
+                if (!result.success) {
+                    throw new Error(`Failed to install plugin "${pluginName}": ${result.error}`);
+                }
+                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}`);
+        }
+        // Auto-provision hyperscape agent if needed
+        if (name === HYPERSCAPE_APP_NAME) {
+            const provisionResult = await autoProvisionHyperscapeAgent(runtime);
+            // If auto-provisioning failed and no credentials exist, don't launch viewer
+            if (!provisionResult &&
+                !process.env.HYPERSCAPE_CHARACTER_ID?.trim() &&
+                !process.env.HYPERSCAPE_AUTH_TOKEN?.trim()) {
+                logger.warn("[app-manager] Hyperscape requires authentication but auto-provisioning failed. " +
+                    "Set HYPERSCAPE_CHARACTER_ID and HYPERSCAPE_AUTH_TOKEN, or ensure the hyperscape server is running.");
+                throw new Error("Hyperscape authentication required. Set HYPERSCAPE_CHARACTER_ID and HYPERSCAPE_AUTH_TOKEN, " +
+                    "or ensure the hyperscape server is running at " +
+                    (process.env.HYPERSCAPE_SERVER_URL || "localhost:5555") +
+                    " for auto-provisioning.");
+            }
+        }
+        // Build viewer config from registry app metadata
+        const resolvedLaunchUrl = appInfo.launchUrl
+            ? substituteTemplateVars(appInfo.launchUrl)
+            : null;
+        const launchUrl = resolvedLaunchUrl
+            ? normalizeSafeAppUrl(resolvedLaunchUrl)
+            : null;
+        if (resolvedLaunchUrl && !launchUrl) {
+            throw new Error(`Refusing to launch app "${appInfo.name}": unsafe launch URL`);
+        }
+        const viewer = buildViewerConfig(appInfo, launchUrl);
+        this.activeSessions.set(name, {
+            appName: name,
+            pluginName,
+            launchType: appInfo.launchType ?? "connect",
+            launchUrl,
+            viewerUrl: viewer?.url ?? null,
+            startedAt: new Date().toISOString(),
+        });
+        return {
+            pluginInstalled,
+            needsRestart,
+            displayName: appInfo.displayName ?? appInfo.name,
+            launchType: appInfo.launchType ?? "connect",
+            launchUrl,
+            viewer,
+        };
+    }
+    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) {
+            return {
+                success: false,
+                appName: name,
+                stoppedAt: new Date().toISOString(),
+                pluginUninstalled: false,
+                needsRestart: false,
+                stopScope: "no-op",
+                message: `No active session or installed plugin found for "${name}".`,
+            };
+        }
+        if (isPluginInstalled) {
+            const uninstallResult = await pluginManager.uninstallPlugin(pluginName);
+            if (!uninstallResult.success) {
+                throw new Error(`Failed to stop "${name}": ${uninstallResult.error ?? "plugin uninstall failed"}`);
+            }
+            return {
+                success: true,
+                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.`,
+            };
+        }
+        return {
+            success: true,
+            appName: name,
+            stoppedAt: new Date().toISOString(),
+            pluginUninstalled: false,
+            needsRestart: false,
+            stopScope: "viewer-session",
+            message: `${name} viewer session stopped.`,
+        };
+    }
+    /** 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
+        }));
+    }
+}

package/dist/packages/autonomous/src/services/browser-capture.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Headless browser capture — opens the StreamView in headless Chrome and
+ * saves screenshots to a temp file. FFmpeg reads the temp file using
+ * -loop 1 to continuously re-read the latest frame.
+ *
+ * This approach avoids the pipe bottleneck — FFmpeg reads at its own
+ * pace while the browser updates the file independently.
+ *
+ * Visual parity with Electron:
+ * - Appends `?popout` to the URL so the app renders StreamView directly
+ *   (skips onboarding, auth gates, navigation chrome).
+ * - Enables SwiftShader for WebGL so VRM avatar renders identically.
+ * - Seeds localStorage with overlay layout, theme, and avatar index so
+ *   the first rendered frame matches the configured appearance.
+ * - Uses `waitUntil: "networkidle0"` to ensure all assets load before capture.
+ * - Keeps CSS animations/transitions enabled for visual parity.
+ */
+/** Path to the temp frame file that FFmpeg reads */
+export declare const FRAME_FILE: string;
+export interface BrowserCaptureConfig {
+    url: string;
+    width?: number;
+    height?: number;
+    fps?: number;
+    quality?: number;
+    /** Optional overlay layout JSON to seed into localStorage before page load. */
+    overlayLayout?: string;
+    /** Theme name to apply (e.g. "milady", "haxor", "psycho"). */
+    theme?: string;
+    /** Avatar VRM index (1–8). */
+    avatarIndex?: number;
+    /** Destination ID — seeds the destination-specific localStorage key. */
+    destinationId?: string;
+}
+export declare function startBrowserCapture(config: BrowserCaptureConfig): Promise<void>;
+export declare function stopBrowserCapture(): Promise<void>;
+export declare function isBrowserCaptureRunning(): boolean;
+export declare function hasFrameFile(): boolean;
+//# sourceMappingURL=browser-capture.d.ts.map

package/dist/packages/autonomous/src/services/browser-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-capture.d.ts","sourceRoot":"","sources":["../../../../../src/services/browser-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAiBH,oDAAoD;AACpD,eAAO,MAAM,UAAU,QAA4C,CAAC;AAEpE,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAgCD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,iBAiHrE;AAED,wBAAsB,kBAAkB,kBASvC;AAED,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD;AAED,wBAAgB,YAAY,IAAI,OAAO,CAEtC"}