@elizaos/agent 2.0.0-beta.2 → 2.0.3-beta.3

package/api/views-registry.d.ts

@@ -0,0 +1,100 @@
+/**
+ * View Registry — discovers, catalogs, and resolves view bundles from plugins.
+ *
+ * Views are declared by plugins via `Plugin.views`. Each declaration is
+ * registered here at plugin load time and assigned runtime URLs. The HTTP
+ * layer (`views-routes.ts`) delegates all path resolution back to this module.
+ */
+import type { IAgentRuntime } from "@elizaos/core";
+import { type Plugin, type ViewType } from "@elizaos/core";
+export type { ViewRegistryEntry } from "./view-registry-types.js";
+import type { ViewRegistryEntry } from "./view-registry-types.js";
+/**
+ * Resolve the absolute on-disk path for a view bundle.
+ * Returns `null` when the entry has no `bundlePath` or no `pluginDir`.
+ */
+export declare function getBundleDiskPath(entry: ViewRegistryEntry): string | null;
+/**
+ * Resolve the absolute on-disk path for a hero image.
+ * Returns `null` when the entry has no `heroImagePath` or no `pluginDir`.
+ * This only handles declared paths; for extension-probing see `findHeroOnDisk`.
+ */
+type HeroLookup = Pick<ViewRegistryEntry, "pluginDir" | "heroImagePath">;
+export declare function getHeroDiskPath(entry: HeroLookup): string | null;
+/**
+ * Find the first existing hero image file for an entry, probing extensions
+ * in preference order. Returns the absolute path and its content type, or
+ * `null` when nothing is found.
+ */
+export declare function findHeroOnDisk(entry: HeroLookup): Promise<{
+    absolutePath: string;
+    contentType: string;
+} | null>;
+/**
+ * Build a branded generated SVG fallback when no hero image is on disk. Shares
+ * the exact art (frame, no-blue palette, line-icon glyph) used for the heroes
+ * committed into plugins, so a view without a packaged hero still renders a
+ * cohesive card instead of a placeholder. `icon` is the view's Lucide icon name,
+ * used as a hint to pick the matching glyph.
+ */
+export declare function generateViewHeroSvg(label: string, icon?: string): string;
+/**
+ * Register all views declared by `plugin`. Safe to call multiple times for the
+ * same plugin — subsequent calls update existing entries.
+ *
+ * @param plugin    - The Plugin object whose `views` array to register.
+ * @param pluginDir - Absolute path to the plugin's package root. When omitted,
+ *   the registry attempts to resolve it via `require.resolve`.
+ * @param runtime   - Optional agent runtime. When provided, embeddings for the
+ *   newly registered views are queued in the background search index.
+ */
+export declare function registerPluginViews(plugin: Plugin, pluginDir?: string, runtime?: IAgentRuntime): Promise<void>;
+/**
+ * Remove all views registered for `pluginName`. Called when a plugin is
+ * unloaded via `runtime.unloadPlugin`.
+ */
+export declare function unregisterPluginViews(pluginName: string): void;
+/**
+ * Register all built-in first-party shell views.
+ *
+ * These views are declared in `builtin-views.ts` and live in the main shell
+ * bundle — no separate bundle file is required. Called once at server startup
+ * before any plugin views are registered, so plugin views can override them
+ * by registering the same id only when a conflict is logged (built-in wins
+ * under the existing conflict resolution rule).
+ *
+ * Safe to call multiple times — subsequent calls have no additional effect
+ * because the conflict guard in `registerPluginViews` keeps the first
+ * registration.
+ *
+ * @param runtime - Optional agent runtime. When provided, embeddings for the
+ *   built-in views are queued in the background search index.
+ */
+export declare function registerBuiltinViews(runtime?: IAgentRuntime): void;
+/**
+ * List all registered views.
+ *
+ * Visibility follows the four-kind taxonomy ({@link resolveViewKind}):
+ * `system`/`release` views are always listed. `developer` views are listed
+ * only when `developerMode` is true. `preview` views are listed only when
+ * `includeAllKinds` is true. The dashboard's `GET /api/views` passes
+ * `includeAllKinds: true` so the client receives every view (with its
+ * `viewKind`) and applies the user's Settings toggles itself — the server
+ * cannot know whether it is talking to a dev build or which toggles are on.
+ *
+ * @param filter.developerMode - Include `developer`-kind views. Default false.
+ * @param filter.includeAllKinds - Include every kind regardless of toggle
+ *   (developer + preview). Default false.
+ */
+export declare function listViews(filter?: {
+    developerMode?: boolean;
+    includeAllKinds?: boolean;
+    viewType?: ViewType;
+}): ViewRegistryEntry[];
+/**
+ * Look up a single view by its stable id.
+ */
+export declare function getView(id: string, filter?: {
+    viewType?: ViewType;
+}): ViewRegistryEntry | undefined;
+//# sourceMappingURL=views-registry.d.ts.map

package/api/views-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"views-registry.d.ts","sourceRoot":"","sources":["../../src/api/views-registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAEL,KAAK,MAAM,EAGX,KAAK,QAAQ,EACd,MAAM,eAAe,CAAC;AAIvB,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAyIlE;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAOzE;AAED;;;;GAIG;AACH,KAAK,UAAU,GAAG,IAAI,CAAC,iBAAiB,EAAE,WAAW,GAAG,eAAe,CAAC,CAAC;AAEzE,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAMhE;AASD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CA0B/D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAExE;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CAiDf;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAW9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,CAuDlE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,GAAG,iBAAiB,EAAE,CAoCtB;AAED;;GAEG;AACH,wBAAgB,OAAO,CACrB,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,GAC/B,iBAAiB,GAAG,SAAS,CAM/B"}

package/api/views-registry.js

@@ -0,0 +1,495 @@
+/**
+ * View Registry — discovers, catalogs, and resolves view bundles from plugins.
+ *
+ * Views are declared by plugins via `Plugin.views`. Each declaration is
+ * registered here at plugin load time and assigned runtime URLs. The HTTP
+ * layer (`views-routes.ts`) delegates all path resolution back to this module.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { logger, resolveViewKind, } from "@elizaos/core";
+import { generateViewHeroSvgFor } from "@elizaos/shared";
+import { BUILTIN_VIEWS } from "./builtin-views.js";
+import { viewSearchIndex } from "./views-search-index.js";
+/** Hero image extensions checked in order when `heroImagePath` is not set. */
+const HERO_EXTENSIONS = [".webp", ".png", ".jpg", ".jpeg", ".svg"];
+/** MIME types for hero image extensions. */
+const HERO_CONTENT_TYPES = {
+    ".webp": "image/webp",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".svg": "image/svg+xml",
+};
+const DEFAULT_VIEW_TYPE = "gui";
+const AGENT_PACKAGE_DIR = resolveNearestPackageDirSync(path.dirname(fileURLToPath(import.meta.url)));
+function normalizeViewType(viewType) {
+    return viewType ?? DEFAULT_VIEW_TYPE;
+}
+function viewRegistryKey(id, viewType) {
+    return `${viewType}:${id}`;
+}
+/** Module-level registry storage. Keyed by view type + view id. */
+const registry = new Map();
+/** View ids already warned about for oversized bundles — warn once per process. */
+const warnedLargeBundles = new Set();
+/**
+ * Attempt to resolve the package root dir for a plugin by name using
+ * `require.resolve`. Returns `undefined` when the package is not reachable
+ * from the current module (e.g. workspace-linked but not installed).
+ */
+async function resolvePluginPackageDir(pluginName) {
+    const { createRequire } = await import("node:module");
+    const req = createRequire(import.meta.url);
+    const packageNames = pluginName.startsWith("@")
+        ? [pluginName]
+        : [pluginName, `@elizaos/plugin-${pluginName}`];
+    for (const packageName of packageNames) {
+        // Preferred: resolve the package's own package.json directly. Requires the
+        // package to expose "./package.json" in its exports map.
+        try {
+            return path.dirname(req.resolve(`${packageName}/package.json`));
+        }
+        catch {
+            // Fall through to resolving the package entry instead.
+        }
+    }
+    // Fallback: resolve the package main entry (the "." export always exists for
+    // a loadable plugin) and walk up to the directory that owns its package.json.
+    // This keeps view bundles resolvable for plugins that don't export
+    // "./package.json".
+    for (const packageName of packageNames) {
+        try {
+            let dir = path.dirname(req.resolve(packageName));
+            for (let depth = 0; depth < 8; depth++) {
+                if (await fileExists(path.join(dir, "package.json")))
+                    return dir;
+                const parent = path.dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+        }
+        catch {
+            // Package is not reachable from this module under this name.
+        }
+    }
+    for (const packageName of packageNames) {
+        const workspaceDir = await resolveWorkspacePluginPackageDir(packageName);
+        if (workspaceDir)
+            return workspaceDir;
+    }
+    logger.warn({ src: "ViewRegistry", pluginName }, `Could not resolve package directory for plugin "${pluginName}"; its view bundle will be unavailable`);
+    return undefined;
+}
+async function resolveWorkspacePluginPackageDir(pluginName) {
+    if (!pluginName.startsWith("@elizaos/plugin-"))
+        return undefined;
+    const shortName = pluginName.slice("@elizaos/".length);
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 14; depth += 1) {
+        const candidate = path.join(dir, "plugins", shortName);
+        if (await fileExists(path.join(candidate, "package.json"))) {
+            return candidate;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    const cwdCandidate = path.join(process.cwd(), "plugins", shortName);
+    if (await fileExists(path.join(cwdCandidate, "package.json"))) {
+        return cwdCandidate;
+    }
+    return undefined;
+}
+/**
+ * Check whether a file exists on disk (non-throwing).
+ */
+async function fileExists(absolutePath) {
+    try {
+        await fs.access(absolutePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveNearestPackageDirSync(startDir) {
+    let dir = startDir;
+    for (let depth = 0; depth < 10; depth += 1) {
+        if (existsSync(path.join(dir, "package.json")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * Resolve the absolute on-disk path for a view bundle.
+ * Returns `null` when the entry has no `bundlePath` or no `pluginDir`.
+ */
+export function getBundleDiskPath(entry) {
+    if (!entry.bundlePath || !entry.pluginDir)
+        return null;
+    const resolved = path.resolve(entry.pluginDir, entry.bundlePath);
+    // Prevent path traversal outside the plugin package root.
+    const packageRoot = `${path.resolve(entry.pluginDir)}${path.sep}`;
+    if (!resolved.startsWith(packageRoot))
+        return null;
+    return resolved;
+}
+export function getHeroDiskPath(entry) {
+    if (!entry.heroImagePath || !entry.pluginDir)
+        return null;
+    const resolved = path.resolve(entry.pluginDir, entry.heroImagePath);
+    const packageRoot = `${path.resolve(entry.pluginDir)}${path.sep}`;
+    if (!resolved.startsWith(packageRoot))
+        return null;
+    return resolved;
+}
+function hasDeclaredHeroOnDiskSync(entry) {
+    const declaredPath = getHeroDiskPath(entry);
+    if (!declaredPath)
+        return false;
+    const ext = path.extname(declaredPath).toLowerCase();
+    return Boolean(HERO_CONTENT_TYPES[ext] && existsSync(declaredPath));
+}
+/**
+ * Find the first existing hero image file for an entry, probing extensions
+ * in preference order. Returns the absolute path and its content type, or
+ * `null` when nothing is found.
+ */
+export async function findHeroOnDisk(entry) {
+    if (!entry.pluginDir)
+        return null;
+    // If a specific path was declared, try it first.
+    const declaredPath = getHeroDiskPath(entry);
+    if (declaredPath) {
+        const ext = path.extname(declaredPath).toLowerCase();
+        const contentType = HERO_CONTENT_TYPES[ext];
+        if (contentType && (await fileExists(declaredPath))) {
+            return { absolutePath: declaredPath, contentType };
+        }
+    }
+    // Fall back to probing `assets/hero.<ext>` in the plugin dir.
+    const packageRoot = path.resolve(entry.pluginDir);
+    for (const ext of HERO_EXTENSIONS) {
+        const candidate = path.join(packageRoot, "assets", `hero${ext}`);
+        if (await fileExists(candidate)) {
+            return {
+                absolutePath: candidate,
+                contentType: HERO_CONTENT_TYPES[ext] ?? "image/png",
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Build a branded generated SVG fallback when no hero image is on disk. Shares
+ * the exact art (frame, no-blue palette, line-icon glyph) used for the heroes
+ * committed into plugins, so a view without a packaged hero still renders a
+ * cohesive card instead of a placeholder. `icon` is the view's Lucide icon name,
+ * used as a hint to pick the matching glyph.
+ */
+export function generateViewHeroSvg(label, icon) {
+    return generateViewHeroSvgFor({ label, icon });
+}
+/**
+ * Register all views declared by `plugin`. Safe to call multiple times for the
+ * same plugin — subsequent calls update existing entries.
+ *
+ * @param plugin    - The Plugin object whose `views` array to register.
+ * @param pluginDir - Absolute path to the plugin's package root. When omitted,
+ *   the registry attempts to resolve it via `require.resolve`.
+ * @param runtime   - Optional agent runtime. When provided, embeddings for the
+ *   newly registered views are queued in the background search index.
+ */
+export async function registerPluginViews(plugin, pluginDir, runtime) {
+    const views = plugin.views;
+    if (!views || views.length === 0)
+        return;
+    // A plugin can be hot-reloaded with a changed views array. Remove the old
+    // entries first so deleted or renamed views do not survive the reload.
+    unregisterPluginViews(plugin.name);
+    // Resolve plugin directory once for all views in this plugin.
+    const resolvedDir = pluginDir ?? (await resolvePluginPackageDir(plugin.name));
+    const registered = [];
+    for (const view of views) {
+        const entry = await buildEntry(view, plugin.name, resolvedDir);
+        const key = viewRegistryKey(entry.id, entry.viewType);
+        const existing = registry.get(key);
+        if (existing && existing.pluginName !== plugin.name) {
+            logger.warn({
+                src: "ViewRegistry",
+                viewId: entry.id,
+                existingPlugin: existing.pluginName,
+                incomingPlugin: plugin.name,
+            }, `View id "${entry.id}" from plugin "${plugin.name}" conflicts with plugin "${existing.pluginName}"; keeping existing entry`);
+            continue;
+        }
+        registry.set(key, entry);
+        registered.push(entry);
+        logger.debug({
+            src: "ViewRegistry",
+            viewId: entry.id,
+            pluginName: entry.pluginName,
+            available: entry.available,
+        }, `Registered view "${entry.id}" from plugin "${plugin.name}"`);
+    }
+    // Queue embedding computation in the background — non-blocking.
+    if (runtime && registered.length > 0) {
+        setImmediate(() => {
+            for (const entry of registered) {
+                void viewSearchIndex.indexView(entry, runtime).catch(() => { });
+            }
+        });
+    }
+}
+/**
+ * Remove all views registered for `pluginName`. Called when a plugin is
+ * unloaded via `runtime.unloadPlugin`.
+ */
+export function unregisterPluginViews(pluginName) {
+    for (const [key, entry] of registry) {
+        if (entry.pluginName === pluginName) {
+            registry.delete(key);
+            viewSearchIndex.removeView(entry.id, entry.viewType);
+            logger.debug({ src: "ViewRegistry", viewId: entry.id, pluginName }, `Unregistered view "${entry.id}" from plugin "${pluginName}"`);
+        }
+    }
+}
+/**
+ * Register all built-in first-party shell views.
+ *
+ * These views are declared in `builtin-views.ts` and live in the main shell
+ * bundle — no separate bundle file is required. Called once at server startup
+ * before any plugin views are registered, so plugin views can override them
+ * by registering the same id only when a conflict is logged (built-in wins
+ * under the existing conflict resolution rule).
+ *
+ * Safe to call multiple times — subsequent calls have no additional effect
+ * because the conflict guard in `registerPluginViews` keeps the first
+ * registration.
+ *
+ * @param runtime - Optional agent runtime. When provided, embeddings for the
+ *   built-in views are queued in the background search index.
+ */
+export function registerBuiltinViews(runtime) {
+    const loadedAt = Date.now();
+    const pluginName = "@elizaos/builtin";
+    const registered = [];
+    for (const view of BUILTIN_VIEWS) {
+        const viewType = normalizeViewType(view.viewType);
+        const key = viewRegistryKey(view.id, viewType);
+        if (registry.has(key)) {
+            // Already registered (e.g. called twice at startup). Skip silently.
+            continue;
+        }
+        const platform = view.platforms?.[0] ?? "web";
+        const pluginDir = AGENT_PACKAGE_DIR;
+        const hasHeroImage = pluginDir
+            ? hasDeclaredHeroOnDiskSync({
+                pluginDir,
+                heroImagePath: view.heroImagePath,
+            })
+            : false;
+        const entry = {
+            ...view,
+            viewType,
+            pluginName,
+            pluginDir,
+            bundleUrl: undefined,
+            bundleUrlVersioned: undefined,
+            heroImageUrl: `/api/views/${encodeURIComponent(view.id)}/hero`,
+            hasHeroImage,
+            available: true,
+            loadedAt,
+            platform,
+            builtin: true,
+        };
+        registry.set(key, entry);
+        registered.push(entry);
+    }
+    // Called on every /api/views request and again during deferred startup, but
+    // registration is idempotent — only the first call adds entries. Stay silent
+    // on idempotent re-calls so the boot log isn't spammed with the same line.
+    if (registered.length > 0) {
+        logger.info({ src: "ViewRegistry", count: registered.length }, `Registered ${registered.length} built-in views`);
+    }
+    // Queue embedding computation in the background — non-blocking.
+    if (runtime && registered.length > 0) {
+        setImmediate(() => {
+            for (const entry of registered) {
+                void viewSearchIndex.indexView(entry, runtime).catch(() => { });
+            }
+        });
+    }
+}
+/**
+ * List all registered views.
+ *
+ * Visibility follows the four-kind taxonomy ({@link resolveViewKind}):
+ * `system`/`release` views are always listed. `developer` views are listed
+ * only when `developerMode` is true. `preview` views are listed only when
+ * `includeAllKinds` is true. The dashboard's `GET /api/views` passes
+ * `includeAllKinds: true` so the client receives every view (with its
+ * `viewKind`) and applies the user's Settings toggles itself — the server
+ * cannot know whether it is talking to a dev build or which toggles are on.
+ *
+ * @param filter.developerMode - Include `developer`-kind views. Default false.
+ * @param filter.includeAllKinds - Include every kind regardless of toggle
+ *   (developer + preview). Default false.
+ */
+export function listViews(filter) {
+    const developerMode = filter?.developerMode ?? false;
+    const includeAllKinds = filter?.includeAllKinds ?? false;
+    const requestedViewType = filter?.viewType ?? DEFAULT_VIEW_TYPE;
+    const byId = new Map();
+    for (const entry of registry.values()) {
+        if (!includeAllKinds) {
+            const kind = resolveViewKind(entry);
+            if (kind === "preview")
+                continue;
+            if (kind === "developer" && !developerMode)
+                continue;
+        }
+        const existing = byId.get(entry.id);
+        if (!existing) {
+            if (entry.viewType === requestedViewType ||
+                entry.viewType === DEFAULT_VIEW_TYPE) {
+                byId.set(entry.id, entry);
+            }
+            continue;
+        }
+        if (existing.viewType !== requestedViewType &&
+            entry.viewType === requestedViewType) {
+            byId.set(entry.id, entry);
+        }
+    }
+    const results = [...byId.values()];
+    results.sort((a, b) => (a.order ?? 100) - (b.order ?? 100) ||
+        a.label.localeCompare(b.label) ||
+        a.id.localeCompare(b.id));
+    return results;
+}
+/**
+ * Look up a single view by its stable id.
+ */
+export function getView(id, filter) {
+    const requestedViewType = filter?.viewType ?? DEFAULT_VIEW_TYPE;
+    return (registry.get(viewRegistryKey(id, requestedViewType)) ??
+        registry.get(viewRegistryKey(id, DEFAULT_VIEW_TYPE)));
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Compute a short content hash for a bundle file. Returns `null` on any I/O error. */
+async function computeBundleHash(filePath) {
+    try {
+        const content = await fs.readFile(filePath);
+        return createHash("sha256").update(content).digest("hex").slice(0, 12);
+    }
+    catch {
+        return null;
+    }
+}
+async function buildEntry(view, pluginName, pluginDir) {
+    const loadedAt = Date.now();
+    const normalizedViewType = normalizeViewType(view.viewType);
+    const registryKey = viewRegistryKey(view.id, normalizedViewType);
+    // Check bundle availability and collect hash + size when resolvable.
+    let available = Boolean(view.bundleUrl);
+    let bundleHash;
+    let bundleSize;
+    if (!view.bundleUrl && pluginDir && view.bundlePath) {
+        const bundleAbs = path.resolve(pluginDir, view.bundlePath);
+        const packageRoot = `${path.resolve(pluginDir)}${path.sep}`;
+        if (bundleAbs.startsWith(packageRoot)) {
+            available = await fileExists(bundleAbs);
+            if (available) {
+                const [hash, stat] = await Promise.all([
+                    computeBundleHash(bundleAbs),
+                    fs.stat(bundleAbs).catch(() => null),
+                ]);
+                if (hash)
+                    bundleHash = hash;
+                if (stat)
+                    bundleSize = stat.size;
+                // buildEntry runs on every (re-)registration, so a plugin loaded into
+                // multiple runtimes logs this repeatedly. Keep the per-view size at
+                // debug and warn at most once per registry key about oversized bundles.
+                const sizeKb = stat ? stat.size / 1024 : 0;
+                if (stat && stat.size > 512 * 1024) {
+                    if (!warnedLargeBundles.has(registryKey)) {
+                        warnedLargeBundles.add(registryKey);
+                        logger.warn({
+                            src: "ViewRegistry",
+                            viewId: view.id,
+                            viewType: normalizedViewType,
+                            sizeKb: sizeKb.toFixed(0),
+                        }, `View ${registryKey} bundle is large (${sizeKb.toFixed(0)}KB) — consider code splitting`);
+                    }
+                }
+                else if (stat) {
+                    logger.debug({ src: "ViewRegistry", viewId: view.id, sizeKb: sizeKb.toFixed(1) }, `Registered view ${view.id} — bundle: ${sizeKb.toFixed(1)}KB`);
+                }
+            }
+        }
+    }
+    const encodedId = encodeURIComponent(view.id);
+    // bundleUrl uses a timestamp ?v= param for backwards-compat; bundleUrlVersioned
+    // uses the content hash when available (allows immutable long-lived caching).
+    const buildAssetUrl = (asset, version) => {
+        const params = new URLSearchParams();
+        if (normalizedViewType !== DEFAULT_VIEW_TYPE) {
+            params.set("viewType", normalizedViewType);
+        }
+        if (version !== undefined) {
+            params.set("v", String(version));
+        }
+        const query = params.toString();
+        return `/api/views/${encodedId}/${asset}${query ? `?${query}` : ""}`;
+    };
+    const bundleUrl = view.bundleUrl
+        ? view.bundleUrl
+        : view.bundlePath
+            ? buildAssetUrl("bundle.js", loadedAt)
+            : undefined;
+    const bundleUrlVersioned = view.bundleUrl
+        ? view.bundleUrl
+        : view.bundlePath && bundleHash
+            ? buildAssetUrl("bundle.js", bundleHash)
+            : bundleUrl;
+    const heroImageUrl = buildAssetUrl("hero");
+    // Probe for a real hero asset so the client can choose a photo vs. its icon.
+    const hasHeroImage = pluginDir
+        ? (await findHeroOnDisk({
+            pluginDir,
+            heroImagePath: view.heroImagePath,
+        })) !== null
+        : false;
+    // Derive a representative platform from the declaration's platforms list.
+    // When multiple platforms are declared, the first entry wins. Absent the
+    // field, treat the view as "web" (no platform restriction).
+    const platform = view.platforms?.[0] ?? "web";
+    return {
+        ...view,
+        viewType: normalizedViewType,
+        pluginName,
+        pluginDir,
+        bundleUrl,
+        bundleUrlVersioned,
+        heroImageUrl,
+        hasHeroImage,
+        available,
+        loadedAt,
+        platform,
+        bundleHash,
+        bundleSize,
+    };
+}

package/api/views-routes.d.ts

@@ -0,0 +1,66 @@
+/**
+ * HTTP route handlers for the View Registry API.
+ *
+ * Mounted on the agent's HTTP server. Serves view metadata, compiled bundles,
+ * and hero images contributed by plugins via `Plugin.views`.
+ *
+ * Routes:
+ *   GET  /api/views                    — list all registered views (JSON)
+ *   GET  /api/views/platform-info      — platform detection info (JSON)
+ *   GET  /api/views/search?q=&limit=   — hybrid keyword+semantic ranked search (JSON)
+ *   GET  /api/views/:id                — single view metadata (JSON)
+ *   GET  /api/views/:id/bundle.js      — compiled view bundle (JS)
+ *   GET  /api/views/:id/<asset>        — compiled bundle chunk/asset
+ *   GET  /api/views/:id/hero           — hero image (image/*)
+ *   POST /api/views/:id/navigate       — broadcast shell navigation event (JSON)
+ *   POST /api/views/:id/elements       — report the view's addressable element snapshot
+ *   POST /api/views/:id/interact       — agent-view interaction (capability dispatch)
+ *   POST /api/views/interact-result    — frontend result callback (resolves pending interact)
+ */
+import { type IAgentRuntime, type RouteRequestMeta, type ViewType } from "@elizaos/core";
+import { type RouteHelpers } from "@elizaos/shared";
+import { type ViewInteractResult } from "./pending-request-map.js";
+export interface CurrentViewState {
+    viewId: string;
+    viewPath: string | null;
+    viewLabel: string;
+    viewType: ViewType;
+    action?: string;
+    views?: string[];
+    layout?: string;
+    placement?: string;
+    /**
+     * ISO timestamp of the navigate that *switched* into this view (distinct from
+     * `updatedAt`, which also moves on same-view re-stamps). Read by the
+     * `current_view` acknowledgement provider to know a switch *just happened*.
+     */
+    switchedAt?: string;
+    /** Who initiated the switch: the agent (default) or the user clicking the UI. */
+    source?: "agent" | "user";
+    updatedAt: string;
+}
+/**
+ * A view switch is treated as "just happened" for this long after navigate, so
+ * the acknowledgement provider only references it on the turn(s) immediately
+ * following the switch and never re-acknowledges a stale switch forever.
+ */
+export declare const VIEW_SWITCH_FRESH_MS = 15000;
+/** True when `state` reflects a switch within {@link VIEW_SWITCH_FRESH_MS}. */
+export declare function isViewSwitchFresh(state: CurrentViewState | null, now?: number): boolean;
+export declare function getCurrentViewState(): CurrentViewState | null;
+export declare function clearCurrentViewState(): void;
+/**
+ * Resolve a pending interact request from a WS `view:interact:result` message.
+ * Called by the WebSocket message handler in server.ts.
+ */
+export declare function resolveViewInteractResult(result: ViewInteractResult): void;
+export interface ViewsRouteContext extends RouteRequestMeta, Pick<RouteHelpers, "json" | "error"> {
+    url: URL;
+    developerMode?: boolean;
+    /** Broadcast an arbitrary payload to all connected WebSocket clients. */
+    broadcastWs?: (payload: object) => void;
+    /** Agent runtime — used by the semantic search endpoint. */
+    runtime?: IAgentRuntime | null;
+}
+export declare function handleViewsRoutes(ctx: ViewsRouteContext): Promise<boolean>;
+//# sourceMappingURL=views-routes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"views-routes.d.ts","sourceRoot":"","sources":["../../src/api/views-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,OAAO,EAEL,KAAK,aAAa,EAElB,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,YAAY,EAAgB,MAAM,iBAAiB,CAAC;AAUlE,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AA6LlC,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,gBAAgB,GAAG,IAAI,EAC9B,GAAG,GAAE,MAAmB,GACvB,OAAO,CAKT;AAID,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,IAAI,CAE7D;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAE1E;AAED,MAAM,WAAW,iBACf,SAAQ,gBAAgB,EACtB,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC,GAAG,EAAE,GAAG,CAAC;IACT,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,yEAAyE;IACzE,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,4DAA4D;IAC5D,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;CAChC;AAID,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,OAAO,CAAC,CA82BlB"}