The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
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.tsindex 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.pynew file mode 100644index 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 toucheddiff --git a/hermes_cli/web_routers/desktop_plugins.py b/hermes_cli/web_routers/desktop_plugins.pyindex 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, thensymlinks are followed as Electron's ``readDir`` does, so ``desktop-plugins/foo -> ~/src/foo`` loadshere 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 Pathfrom fastapi import APIRouter, HTTPException+from hermes_cli.desktop_plugin_halves import reconcile_desktop_halvesfrom hermes_constants import get_default_hermes_rootrouter = 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.pynew file mode 100644index 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.mdindex 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 pluginhost that serves it, from the `desktop-plugins` folder of that host's Hermes root, whichever profilethe 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 folderaccess (`ctx.files`) is not available in a browser.