Skip to content

The agent that grows with you

feat(webapp): copy agent+desktop packages' desktop halves on the serving host

Adolaniumf9e923f190b1
diff --git a/apps/desktop/src/lib/browser-desktop-plugins.ts b/apps/desktop/src/lib/browser-desktop-plugins.ts
index 1e721c049ab..c8509ddc2c0 100644
--- a/apps/desktop/src/lib/browser-desktop-plugins.ts
+++ b/apps/desktop/src/lib/browser-desktop-plugins.ts
@@ -2,7 +2,7 @@ import type { HermesApiRequest, HermesReadFileTextResult } from '@/global'
type DesktopPluginsBridge = Pick<
Window['hermesDesktop'],
- 'desktopPluginsRoot' | 'readDir' | 'readFileText' | 'readPluginSource'
+ 'desktopPluginsRoot' | 'readDir' | 'readFileText' | 'readPluginSource' | 'reconcileDesktopPlugins'
>
interface BrowserDesktopPluginsOptions {
@@ -35,6 +35,9 @@ export function createBrowserDesktopPluginsBridge({ api, files }: BrowserDesktop
},
readDir: path => (inside(path) ? get('list', path) : files.readDir(path)),
readFileText: path => (inside(path) ? readFile(path) : files.readFileText(path)),
- readPluginSource: readFile
+ readPluginSource: readFile,
+ // The server copies agent+desktop packages' desktop halves into the folder, as Electron does.
+ reconcileDesktopPlugins: async () =>
+ (await api<{ touched: string[] }>({ method: 'POST', path: '/api/desktop-plugins/reconcile' })).touched
}
}
diff --git a/hermes_cli/desktop_plugin_halves.py b/hermes_cli/desktop_plugin_halves.py
new file mode 100644
index 00000000000..14c330c418f
--- /dev/null
+++ b/hermes_cli/desktop_plugin_halves.py
@@ -0,0 +1,201 @@
+"""Copy each unified agent+desktop package's ``desktop/`` half into the app-level desktop-plugins folder.
+
+A unified package keeps its agent half in ``<home>/plugins/<name>/`` (the default home and every
+profile). Its desktop half is loaded from ``<root>/desktop-plugins/<name>/``, with a
+``.hermes-package.json`` marker that pairs it back to the agent row. Native Desktop does this copy
+in Electron (``reconcileUnifiedDesktopHalves`` in ``apps/desktop/electron/desktop-plugins-root.ts``),
+so a host that Desktop only reaches over SSH never gets it. The Webapp serves that host's folder,
+so its routes (``web_routers/desktop_plugins.py``) run this pass at the same points Electron does:
+whenever the loader asks for the root, and on demand after an install.
+
+Both writers share the folder on a host that runs native Desktop too, so this keeps Electron's
+on-disk contract exactly: the marker's fields, the first-home-wins order, adoption of a byte-equal
+marker-less copy, a byte compare for linked dev checkouts, staged publication, and a prune that
+only fires when the source is really gone.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import shutil
+import stat
+import tempfile
+import threading
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+PACKAGE_MARKER = ".hermes-package.json"
+_GIT_ORIGIN = re.compile(r'\[remote "origin"\][^[]*?url\s*=\s*(\S+)')
+#: Electron serializes every writer of the root in its main process; the server's threads do here.
+_ROOT_WRITER = threading.Lock()
+
+
+def _list_dirs(folder: Path, *, follow_links: bool = False) -> list[str]:
+ """Folder names in *folder*. A package root follows links to folders (``ln -s ~/src/pkg
+ ~/.hermes/plugins/`` is how a package is developed in place), the app root does not."""
+ try:
+ entries = list(os.scandir(folder))
+ except OSError:
+ return []
+ names = []
+ for entry in entries:
+ try:
+ if entry.is_dir(follow_symlinks=False) or (follow_links and entry.is_symlink() and entry.is_dir()):
+ names.append(entry.name)
+ except OSError:
+ continue
+ return names
+
+
+def _package_origin(package_dir: Path) -> dict:
+ """Where the package came from (catalog sidecar first, then the git remote), for "Install here"."""
+ try:
+ sidecar = json.loads((package_dir / ".hermes-catalog.json").read_text(encoding="utf-8-sig"))
+ if sidecar.get("repo"):
+ origin = {"catalogName": sidecar.get("catalog_name"), "repo": sidecar["repo"], "sha": sidecar.get("sha")}
+ return {key: value for key, value in origin.items() if value is not None}
+ except (OSError, ValueError, AttributeError):
+ pass
+ try:
+ match = _GIT_ORIGIN.search((package_dir / ".git" / "config").read_text(encoding="utf-8-sig"))
+ except OSError:
+ return {}
+ return {"repo": match.group(1)} if match else {}
+
+
+def _read_marker(folder: Path) -> dict | None:
+ try:
+ marker = json.loads((folder / PACKAGE_MARKER).read_text(encoding="utf-8-sig"))
+ except (OSError, ValueError):
+ return None
+ return marker if isinstance(marker, dict) and marker.get("package") and marker.get("source") else None
+
+
+def _write_marker(folder: Path, marker: dict) -> None:
+ (folder / PACKAGE_MARKER).write_text(json.dumps(marker, indent=2) + "\n", encoding="utf-8")
+
+
+def _same_file(a: Path, b: Path) -> bool:
+ """Same bytes on both paths. A comparison that cannot be made is never a match."""
+ try:
+ return a.read_bytes() == b.read_bytes()
+ except OSError:
+ return False
+
+
+def _publish(source_dir: Path, target: Path, marker: dict) -> None:
+ """Copy through a staging sibling and rename the finished tree into place, marker included, so a
+ failure leaves the old folder or none: never a partial, marker-less one that a later pass would
+ take for a hand install."""
+ target.parent.mkdir(parents=True, exist_ok=True)
+ staging = Path(tempfile.mkdtemp(prefix=f".{target.name}.staging-", dir=target.parent))
+ staged = staging / target.name
+ try:
+ shutil.copytree(source_dir, staged, symlinks=True)
+ _write_marker(staged, marker)
+ if target.is_symlink():
+ target.unlink()
+ elif target.exists():
+ shutil.rmtree(target)
+ os.rename(staged, target)
+ finally:
+ shutil.rmtree(staging, ignore_errors=True)
+
+
+def materialize_desktop_half(package_dir: Path, app_root: Path, name: str) -> Path | None:
+ """Copy *package_dir*'s ``desktop/`` half to ``<app_root>/<name>/``. Returns the folder when it
+ was copied or adopted, ``None`` when it is already current, absent, or a user's own plugin."""
+ source_dir = package_dir / "desktop"
+ entry = source_dir / "plugin.js"
+ try:
+ entry_stat = entry.stat()
+ except (FileNotFoundError, NotADirectoryError):
+ return None
+ except OSError as exc:
+ logger.warning("desktop-plugins: cannot read %s: %s", name, exc)
+ return None
+ if not stat.S_ISREG(entry_stat.st_mode):
+ return None
+
+ target = app_root / name
+ existing = _read_marker(target)
+ linked = package_dir.is_symlink()
+ marker = {
+ "package": name,
+ "source": str(source_dir),
+ "sourceMtimeMs": entry_stat.st_mtime_ns / 1_000_000,
+ **({"linked": True} if linked else {}),
+ **_package_origin(package_dir),
+ }
+
+ if target.exists():
+ if existing is None and (target / "plugin.js").exists():
+ # Our own pre-marker copy still matches byte for byte: adopt it. Anything else is a
+ # standalone plugin the user put there, and stays exactly as it is (#112450).
+ if _same_file(target / "plugin.js", entry):
+ _write_marker(target, marker)
+ return target
+ return None
+ if (
+ existing is not None
+ and existing["source"] == str(source_dir)
+ and bool(existing.get("linked")) == linked
+ and (
+ _same_file(target / "plugin.js", entry)
+ if linked
+ else existing.get("sourceMtimeMs", 0) >= marker["sourceMtimeMs"]
+ )
+ ):
+ return None
+
+ _publish(source_dir, target, marker)
+ return target
+
+
+def _source_gone(name: str, entry: Path) -> bool:
+ """True only when the source ``plugin.js`` is really gone. A source we may not stat is not an
+ uninstall: pruning its copy would silently drop the pane."""
+ try:
+ entry.stat()
+ except (FileNotFoundError, NotADirectoryError):
+ return True
+ except OSError as exc:
+ logger.warning("desktop-plugins: keeping desktop half of unreadable package %s: %s", name, exc)
+ return False
+
+
+def reconcile_desktop_halves(hermes_root: Path, app_root: Path) -> list[str]:
+ """Materialize every local home's desktop halves into *app_root* (first home wins for a name in
+ several profiles, the default home first) and drop copies whose package is gone. Returns the
+ folders it wrote or removed."""
+ with _ROOT_WRITER:
+ touched: list[str] = []
+ seen: set[str] = set()
+ homes = [hermes_root, *(hermes_root / "profiles" / name for name in _list_dirs(hermes_root / "profiles"))]
+ for home in homes:
+ plugins_root = home / "plugins"
+ for name in _list_dirs(plugins_root, follow_links=True):
+ if name in seen:
+ continue
+ try:
+ result = materialize_desktop_half(plugins_root / name, app_root, name)
+ except OSError as exc:
+ # One unreadable package must not stop every other half from loading.
+ logger.warning("desktop-plugins: skipping unreadable package %s: %s", name, exc)
+ continue
+ if result is not None or (plugins_root / name / "desktop" / "plugin.js").exists():
+ seen.add(name)
+ if result is not None:
+ touched.append(str(result))
+
+ for name in _list_dirs(app_root):
+ folder = app_root / name
+ marker = _read_marker(folder)
+ if marker and _source_gone(name, Path(marker["source"]) / "plugin.js"):
+ shutil.rmtree(folder, ignore_errors=True)
+ touched.append(str(folder))
+ return touched
diff --git a/hermes_cli/web_routers/desktop_plugins.py b/hermes_cli/web_routers/desktop_plugins.py
index 519040cc08c..ae6436dca8d 100644
--- a/hermes_cli/web_routers/desktop_plugins.py
+++ b/hermes_cli/web_routers/desktop_plugins.py
@@ -8,7 +8,9 @@ The routes answer only what the loader reads: the root, its plugin folders, and
``plugin.js`` and ``.hermes-package.json``. Containment is checked on the path as written, then
symlinks are followed as Electron's ``readDir`` does, so ``desktop-plugins/foo -> ~/src/foo`` loads
here too. They never go through ``/api/fs``, which follows the profile's SSH workspace and truncates
-at the preview cap. Webapp only (``SurfacePolicy.desktop_plugins``; 404 elsewhere).
+at the preview cap. Like Electron, resolving the root first copies agent+desktop packages' desktop
+halves into it (``desktop_plugin_halves.py``), the one write these routes make. Webapp only
+(``SurfacePolicy.desktop_plugins``; 404 elsewhere).
"""
from __future__ import annotations
@@ -20,6 +22,7 @@ from pathlib import Path
from fastapi import APIRouter, HTTPException
+from hermes_cli.desktop_plugin_halves import reconcile_desktop_halves
from hermes_constants import get_default_hermes_root
router = APIRouter()
@@ -102,9 +105,24 @@ def _read(raw: str) -> dict:
return {"byteSize": st.st_size, "path": str(target), "text": text, "truncated": False}
+def _root_reconciled() -> str:
+ """The root, after copying unified packages' desktop halves into it: what Electron's
+ ``desktopPluginsRoot`` does before every scan. On a host native Desktop only reaches over SSH,
+ nothing else ever makes that copy."""
+ root = desktop_plugins_root()
+ reconcile_desktop_halves(get_default_hermes_root(), root)
+ return str(root)
+
+
@router.get("/api/desktop-plugins/root")
async def desktop_plugins_root_route() -> dict:
- return {"root": str(await asyncio.to_thread(desktop_plugins_root))}
+ return {"root": await asyncio.to_thread(_root_reconciled)}
+
+
[email protected]("/api/desktop-plugins/reconcile")
+async def reconcile_desktop_plugins() -> dict:
+ """Electron's ``reconcileDesktopPlugins``: re-run the copy after an install, update or removal."""
+ return {"touched": await asyncio.to_thread(reconcile_desktop_halves, get_default_hermes_root(), desktop_plugins_root())}
@router.get("/api/desktop-plugins/list")
diff --git a/tests/hermes_cli/test_webapp_desktop_plugin_halves.py b/tests/hermes_cli/test_webapp_desktop_plugin_halves.py
new file mode 100644
index 00000000000..384b5181423
--- /dev/null
+++ b/tests/hermes_cli/test_webapp_desktop_plugin_halves.py
@@ -0,0 +1,99 @@
+"""On a headless host the Webapp itself copies agent+desktop packages' desktop halves into
+``<root>/desktop-plugins``, the copy native Desktop makes in Electron
+(``reconcileUnifiedDesktopHalves``) and nothing else makes when Desktop never runs there.
+"""
+import json
+import os
+
+import pytest
+from starlette.testclient import TestClient
+
+from hermes_cli import web_server
+
+
+def hermes_root(monkeypatch, tmp_path):
+ root = tmp_path / "hermes"
+ (root / "profiles" / "work").mkdir(parents=True)
+ monkeypatch.setenv("HERMES_HOME", str(root / "profiles" / "work"))
+ return root
+
+
+def webapp(monkeypatch, hermes_root):
+ for key, value in (("auth_required", False), ("bound_host", None), ("ui_surface", "webapp")):
+ monkeypatch.setattr(web_server.app.state, key, value, raising=False)
+ client = TestClient(web_server.app)
+ client.headers[web_server._SESSION_HEADER_NAME] = web_server._SESSION_TOKEN
+ yield client
+ client.close()
+
+
+def _package(home, name, source):
+ desktop = home / "plugins" / name / "desktop"
+ desktop.mkdir(parents=True)
+ (desktop / "plugin.js").write_text(source, encoding="utf-8")
+ return desktop
+
+
+def _loaded(webapp):
+ """What the browser's loader sees: each folder's plugin.js text and package marker."""
+ root = webapp.get("/api/desktop-plugins/root").json()["root"]
+ seen = {}
+ for folder in webapp.get("/api/desktop-plugins/list", params={"path": root}).json()["entries"]:
+ files = {e["name"]: e["path"] for e in webapp.get("/api/desktop-plugins/list", params={"path": folder["path"]}).json()["entries"]}
+ read = lambda name: webapp.get("/api/desktop-plugins/read", params={"path": files[name]}).json()["text"]
+ marker = json.loads(read(".hermes-package.json")) if ".hermes-package.json" in files else None
+ seen[folder["name"]] = (read("plugin.js"), marker)
+ return seen
+
+
+def test_a_package_installed_on_a_headless_host_brings_its_desktop_half(webapp, hermes_root):
+ source = _package(hermes_root / "profiles" / "work", "radar", "export default { id: 'radar' }")
+
+ text, marker = _loaded(webapp)["radar"]
+
+ assert text == "export default { id: 'radar' }"
+ # The marker is what pairs the half with its agent row and keeps it off until enabled.
+ assert (marker["package"], marker["source"]) == ("radar", str(source))
+
+
+def test_the_copy_follows_its_package_until_it_is_uninstalled(webapp, hermes_root):
+ source = _package(hermes_root, "radar", "export default { v: 1 }")
+ assert _loaded(webapp)["radar"][0] == "export default { v: 1 }"
+
+ (source / "plugin.js").write_text("export default { v: 2 }", encoding="utf-8")
+ later = os.stat(source / "plugin.js").st_mtime + 5
+ os.utime(source / "plugin.js", (later, later))
+ touched = webapp.post("/api/desktop-plugins/reconcile").json()["touched"]
+ assert touched == [str((hermes_root / "desktop-plugins" / "radar").resolve())]
+ assert _loaded(webapp)["radar"][0] == "export default { v: 2 }"
+
+ (source / "plugin.js").unlink()
+ webapp.post("/api/desktop-plugins/reconcile")
+ assert _loaded(webapp) == {}
+
+
+def test_a_users_own_plugin_is_never_overwritten_and_the_default_home_wins(webapp, hermes_root):
+ mine = hermes_root / "desktop-plugins" / "notes"
+ mine.mkdir(parents=True)
+ (mine / "plugin.js").write_text("mine", encoding="utf-8")
+ _package(hermes_root, "notes", "a package that happens to share the name")
+ _package(hermes_root, "radar", "from the default home")
+ _package(hermes_root / "profiles" / "work", "radar", "from a profile")
+
+ loaded = _loaded(webapp)
+
+ assert loaded["notes"] == ("mine", None)
+ assert loaded["radar"][0] == "from the default home"
+
+
+def test_a_copy_made_before_markers_existed_is_adopted_in_place(webapp, hermes_root):
+ _package(hermes_root, "radar", "export default { id: 'radar' }")
+ old_copy = hermes_root / "desktop-plugins" / "radar"
+ old_copy.mkdir(parents=True)
+ (old_copy / "plugin.js").write_text("export default { id: 'radar' }", encoding="utf-8")
+
+ _, marker = _loaded(webapp)["radar"]
+
+ assert marker["package"] == "radar"
diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md
index b8c2384cfb5..c1de9ee675e 100644
--- a/website/docs/user-guide/desktop.md
+++ b/website/docs/user-guide/desktop.md
@@ -718,7 +718,8 @@ The [Webapp](#use-the-desktop-workspace-from-a-browser) loads the desktop plugin
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.
+an agent+desktop package is copied into the folder by the host itself, so it also appears on a
+headless host that native Desktop never runs on.
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.