Skip to content

The agent that grows with you

feat(webapp): load desktop plugins in a browser tab

Adolanium2b10dd274c55
diff --git a/apps/desktop/src/lib/browser-desktop-bridge.ts b/apps/desktop/src/lib/browser-desktop-bridge.ts
index 31d8eda9d36..dbf4d25283f 100644
--- a/apps/desktop/src/lib/browser-desktop-bridge.ts
+++ b/apps/desktop/src/lib/browser-desktop-bridge.ts
@@ -4,6 +4,7 @@ import type { HermesApiRequest } from '@/global'
import { BROWSER_BRIDGE_STUBS } from '@/lib/browser-bridge-stubs'
import { createBrowserClipboardBridge } from '@/lib/browser-clipboard'
import { createBrowserConnectionBridge } from '@/lib/browser-connection'
+import { createBrowserDesktopPluginsBridge } from '@/lib/browser-desktop-plugins'
import { createBrowserFilesBridge } from '@/lib/browser-files'
import { WEBAPP_LAUNCH_REQUIRED } from '@/lib/browser-launch-session'
import { createBrowserProfileBridge } from '@/lib/browser-profile'
@@ -72,12 +73,14 @@ export function installBrowserDesktopBridge(): boolean {
}
const uploads = createBrowserUploadsBridge({ api, bootstrap, currentProfile, objectUrls, previewUrls })
+ const files = createBrowserFilesBridge({ api, bootstrap, currentProfile })
const bridge: Window['hermesDesktop'] = {
...BROWSER_BRIDGE_STUBS,
...createBrowserClipboardBridge({ saveBuffer: uploads.saveImageBuffer }),
...createBrowserConnectionBridge({ api, bootstrap }),
- ...createBrowserFilesBridge({ api, bootstrap, currentProfile }),
+ ...files,
+ ...createBrowserDesktopPluginsBridge({ api, files }),
...uploads,
api,
// This renderer is built from the serving checkout, so its version is the
diff --git a/apps/desktop/src/lib/browser-desktop-plugins.test.ts b/apps/desktop/src/lib/browser-desktop-plugins.test.ts
new file mode 100644
index 00000000000..f15b5c30a6e
--- /dev/null
+++ b/apps/desktop/src/lib/browser-desktop-plugins.test.ts
@@ -0,0 +1,84 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { $pluginRecords } from '@/contrib/plugins-store'
+import { discoverRuntimePlugins } from '@/contrib/runtime-loader'
+import { clearWebappSession, seedWebappSession } from '@/test/webapp-session'
+
+import { installBrowserDesktopBridge } from './browser-desktop-bridge'
+
+// The server half (hermes_cli/web_routers/desktop_plugins.py) is pinned in
+// tests/hermes_cli/test_webapp_desktop_plugins.py; this is the server's answer for one plugin.
+const ROOT = 'C:\\Users\\me\\.hermes\\desktop-plugins'
+const FOLDER = `${ROOT}\\notes`
+
+const SERVER: Record<string, unknown> = {
+ '/api/desktop-plugins/root': { root: ROOT },
+ [`/api/desktop-plugins/list?path=${encodeURIComponent(ROOT)}`]: {
+ entries: [{ isDirectory: true, name: 'notes', path: FOLDER }]
+ },
+ [`/api/desktop-plugins/list?path=${encodeURIComponent(FOLDER)}`]: {
+ entries: [{ isDirectory: false, name: 'plugin.js', path: `${FOLDER}\\plugin.js` }]
+ },
+ [`/api/desktop-plugins/read?path=${encodeURIComponent(`${FOLDER}\\plugin.js`)}`]: {
+ path: `${FOLDER}\\plugin.js`,
+ text: 'export default { id: "notes", register: globalThis.__notesRegister }',
+ truncated: false
+ }
+}
+
+afterEach(() => {
+ clearWebappSession()
+ Reflect.deleteProperty(window, 'hermesDesktop')
+ document.documentElement.removeAttribute('data-hermes-desktop-host')
+ delete (globalThis as { __notesRegister?: unknown }).__notesRegister
+ vi.unstubAllGlobals()
+ vi.restoreAllMocks()
+})
+
+describe('browser-hosted Desktop plugins', () => {
+ it("loads a plugin from the serving host's desktop-plugins folder, never through /api/fs", async () => {
+ seedWebappSession('served-token')
+ const requested: string[] = []
+
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async (input: RequestInfo | URL) => {
+ const url = new URL(String(input), window.location.href)
+ const route = `${url.pathname}${url.search}`
+ requested.push(route)
+
+ return route in SERVER
+ ? new Response(JSON.stringify(SERVER[route]), { status: 200 })
+ : new Response('Not Found', { status: 404 })
+ })
+ )
+
+ const register = vi.fn()
+
+ ;(globalThis as { __notesRegister?: unknown }).__notesRegister = register
+
+ // The loader evaluates plugins via blob-URL import(), which vite's module runner can't resolve
+ // in tests; a data: URL goes through node's own ESM loader (as in runtime-loader.test.ts).
+ vi.spyOn(URL, 'createObjectURL').mockImplementation(
+ blob =>
+ `data:text/javascript;base64,${Buffer.from((blob as unknown as { parts: string[] }).parts.join('')).toString('base64')}`
+ )
+ vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => undefined)
+ vi.stubGlobal(
+ 'Blob',
+ class {
+ parts: string[]
+ constructor(parts: string[]) {
+ this.parts = parts
+ }
+ }
+ )
+
+ expect(installBrowserDesktopBridge()).toBe(true)
+ await discoverRuntimePlugins()
+
+ expect($pluginRecords.get().notes).toMatchObject({ file: `${FOLDER}\\plugin.js`, kind: 'disk', status: 'loaded' })
+ expect(register).toHaveBeenCalledTimes(1)
+ expect(requested.filter(route => route.startsWith('/api/fs/'))).toEqual([])
+ })
+})
diff --git a/apps/desktop/src/lib/browser-desktop-plugins.ts b/apps/desktop/src/lib/browser-desktop-plugins.ts
new file mode 100644
index 00000000000..1e721c049ab
--- /dev/null
+++ b/apps/desktop/src/lib/browser-desktop-plugins.ts
@@ -0,0 +1,40 @@
+import type { HermesApiRequest, HermesReadFileTextResult } from '@/global'
+
+type DesktopPluginsBridge = Pick<
+ Window['hermesDesktop'],
+ 'desktopPluginsRoot' | 'readDir' | 'readFileText' | 'readPluginSource'
+>
+
+interface BrowserDesktopPluginsOptions {
+ api: <T>(request: HermesApiRequest) => Promise<T>
+ /** The page's /api/fs readers, kept for every path outside the plugins folder. */
+ files: Pick<Window['hermesDesktop'], 'readDir' | 'readFileText'>
+}
+
+/** The runtime loader's disk door, answered by the server that serves this page: its app-level
+ * desktop-plugins folder (hermes_cli/web_routers/desktop_plugins.py). /api/fs is the wrong
+ * reader there: it follows the profile's SSH workspace and truncates at the preview cap. */
+export function createBrowserDesktopPluginsBridge({ api, files }: BrowserDesktopPluginsOptions): DesktopPluginsBridge {
+ let root: null | string = null
+
+ const get = <T>(route: string, path: string) =>
+ api<T>({ path: `/api/desktop-plugins/${route}?${new URLSearchParams({ path })}` })
+
+ // The server resolves the folder and builds every path it returns from it, so a path is inside
+ // exactly when it starts with the root and a separator. The loader asks for the root first.
+ const inside = (path: string) =>
+ root !== null && (path === root || path.startsWith(`${root}/`) || path.startsWith(`${root}\\`))
+
+ const readFile = (path: string) => get<HermesReadFileTextResult>('read', path)
+
+ return {
+ desktopPluginsRoot: async () => {
+ root = (await api<{ root: string }>({ path: '/api/desktop-plugins/root' })).root
+
+ return root
+ },
+ readDir: path => (inside(path) ? get('list', path) : files.readDir(path)),
+ readFileText: path => (inside(path) ? readFile(path) : files.readFileText(path)),
+ readPluginSource: readFile
+ }
+}
diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md
index 71e2c9f6290..3ce45ce8912 100644
--- a/website/docs/user-guide/desktop.md
+++ b/website/docs/user-guide/desktop.md
@@ -706,6 +706,14 @@ SHA-pinned) plus an import allowlist — not isolation. A plugin whose
row; **⌘K → Reload desktop plugins** re-reads every installed `plugin.js`,
including one an installer replaced in place.
+The [Webapp](#use-the-desktop-workspace-from-a-browser) loads the desktop plugins installed on the
+host that serves it, from the `desktop-plugins` folder of that host's Hermes root, whichever profile
+the tab is on. A new or removed plugin folder shows up within seconds; an edited `plugin.js` loads on
+**⌘K → Reload desktop plugins**, since a browser cannot watch the host's files. The desktop half of
+an agent+desktop package appears once native Desktop on that host has copied it into the folder.
+Install and remove desktop plugins from native Desktop or in the folder itself; a plugin's folder
+access (`ctx.files`) is not available in a browser.
+
**Capabilities → Plugins** is the one place for everything that extends
Hermes: **one row per plugin**, with two switch columns.