Skip to content

The agent that grows with you

fix(plugins): an agent half is a manifest with something to load

Teknium41e6cddfa550
diff --git a/apps/desktop/electron/desktop-plugin-install.ts b/apps/desktop/electron/desktop-plugin-install.ts
index 0e7a7474eab..90c28636c7e 100644
--- a/apps/desktop/electron/desktop-plugin-install.ts
+++ b/apps/desktop/electron/desktop-plugin-install.ts
@@ -10,6 +10,8 @@ import fsp from 'node:fs/promises'
import os from 'node:os'
import path from 'node:path'
+import { parse as parseYaml } from 'yaml'
+
import {
PACKAGE_MARKER,
publishDesktopTree,
@@ -199,18 +201,46 @@ export function findDesktopEntry(pluginRoot: string): { entryFile: string; sourc
return null
}
+/** Files beside a `plugin.yaml` that the agent side loads: a `register(ctx)` package, or a dashboard
+ * tab/backend (`dashboard/manifest.json`, often with a `plugin_api.py`) the gateway mounts. */
+const AGENT_PAYLOAD_FILES = ['__init__.py', path.join('dashboard', 'manifest.json')]
+
+/** Whether a `plugin.yaml` folder has something for the agent side to load. A manifest alone is not
+ * enough: desktop-only plugins ship one beside `desktop/plugin.js` for metadata. Same rule as the
+ * gateway's `_yaml_ships_agent_payload` (hermes_cli/plugins_cmd_inspect.py); the shared cases live in
+ * tests/fixtures/plugin_component_detection.json. */
+async function yamlShipsAgentPayload(pluginRoot: string, yamlPath: string): Promise<boolean> {
+ if (AGENT_PAYLOAD_FILES.some(rel => pathExistsSync(path.join(pluginRoot, rel)))) {
+ return true
+ }
+
+ // The loader's manifest-only language pack: declared locales plus the folder that holds them.
+ if (!(await pathIsDirectory(path.join(pluginRoot, 'locales')))) {
+ return false
+ }
+
+ try {
+ const manifest: unknown = parseYaml(await fsp.readFile(yamlPath, 'utf8'))
+ const locales = (manifest as { provides_locales?: unknown } | null)?.provides_locales
+
+ // Python truthiness, as the gateway judges it: an empty list or mapping declares nothing.
+ return locales !== null && typeof locales === 'object' ? Object.keys(locales).length > 0 : Boolean(locales)
+ } catch {
+ return false
+ }
+}
+
export async function detectPluginComponents(pluginRoot: string): Promise<PluginComponentDetection> {
- const hasYaml =
- pathExistsSync(path.join(pluginRoot, 'plugin.yaml')) || pathExistsSync(path.join(pluginRoot, 'plugin.yml'))
+ const yamlPath = ['plugin.yaml', 'plugin.yml']
+ .map(name => path.join(pluginRoot, name))
+ .find(candidate => pathExistsSync(candidate))
+ const hasYaml = yamlPath !== undefined
const hasPortable = pathExistsSync(path.join(pluginRoot, 'plugin.json'))
- // A package IS an agent half as soon as it carries a manifest. `__init__.py` is optional:
- // manifest-only plugins are legitimate (`hermes plugins validate` admits them — they ship a
- // `dashboard/plugin_api.py` backend and no `register(ctx)`). Requiring the Python entry point
- // hid those packages from the install plan entirely: `installAgentHalf` never ran, the app
- // landed the desktop half alone, and every `ctx.rest` call 404'd — on a local backend and on a
- // remote gateway alike.
- const agent = hasYaml || hasPortable
+ // `__init__.py` is one agent payload, not a requirement: a manifest-only package with a
+ // `dashboard/plugin_api.py` backend must install its agent half, or its desktop half lands alone and
+ // every `ctx.rest` call 404s.
+ const agent = (hasYaml && (await yamlShipsAgentPayload(pluginRoot, yamlPath))) || hasPortable
const desktopEntry = findDesktopEntry(pluginRoot)
const desktop = desktopEntry !== null
@@ -222,10 +252,6 @@ export async function detectPluginComponents(pluginRoot: string): Promise<Plugin
if (hasYaml) {
try {
- const yamlPath = pathExistsSync(path.join(pluginRoot, 'plugin.yaml'))
- ? path.join(pluginRoot, 'plugin.yaml')
- : path.join(pluginRoot, 'plugin.yml')
-
const text = await fsp.readFile(yamlPath, 'utf8')
const match = text.match(/^name:\s*['"]?([^'"\n]+)['"]?\s*$/m)
diff --git a/hermes_cli/plugins_cmd_inspect.py b/hermes_cli/plugins_cmd_inspect.py
index 7c44e2ce88d..7391e55b1a8 100644
--- a/hermes_cli/plugins_cmd_inspect.py
+++ b/hermes_cli/plugins_cmd_inspect.py
@@ -36,35 +36,54 @@ def _pc():
return plugins_cmd
-def _manifest_name(path: Path, loads) -> Optional[str]:
- """The manifest's ``name`` when the file is a small regular file that parses, else None."""
+def _read_manifest(path: Optional[Path], loads) -> dict[str, Any]:
+ """The manifest as a dict when the file is a small regular file that parses, else ``{}``."""
+ if path is None:
+ return {}
try:
if path.is_symlink() or not path.is_file() or path.stat().st_size > _MANIFEST_MAX_BYTES:
- return None
+ return {}
data = loads(path.read_text(encoding="utf-8-sig"))
except (OSError, UnicodeDecodeError, ValueError, yaml.YAMLError):
- return None
- name = data.get("name") if isinstance(data, dict) else None
+ return {}
+ return data if isinstance(data, dict) else {}
+
+
+def _manifest_name(data: dict[str, Any]) -> Optional[str]:
+ name = data.get("name")
return name.strip() if isinstance(name, str) and name.strip() else None
+#: Files beside a ``plugin.yaml`` that the agent side loads: a ``register(ctx)`` package, or a dashboard
+#: tab/backend (``dashboard/manifest.json``, often with a ``plugin_api.py``) the gateway mounts.
+_AGENT_PAYLOAD_FILES = ("__init__.py", "dashboard/manifest.json")
+
+
+def _yaml_ships_agent_payload(root: Path, manifest: dict[str, Any]) -> bool:
+ """Whether a ``plugin.yaml`` folder has something for the agent side to load. A manifest alone is not
+ enough: desktop-only plugins ship one beside ``desktop/plugin.js`` for metadata, and installing those
+ into the backend's ``plugins/`` puts down a package that loads nothing."""
+ if any((root / rel).is_file() for rel in _AGENT_PAYLOAD_FILES):
+ return True
+ # The loader's manifest-only language pack (``_is_manifest_only_language_pack``), judged the way
+ # ``hermes plugins validate`` does: declared locales plus the folder that holds them.
+ return bool(manifest.get("provides_locales")) and (root / "locales").is_dir()
+
+
def detect_components(root: Path, fallback_name: str) -> dict[str, Any]:
- """Electron's ``detectPluginComponents``: an agent half is a ``plugin.yaml``/``plugin.yml`` manifest
- or a portable ``plugin.json``; a desktop half is ``plugin.js`` at the root or in ``desktop/``.
-
- ``__init__.py`` is not part of the rule: manifest-only plugins are real packages (a
- ``dashboard/plugin_api.py`` backend and no ``register(ctx)``), which ``hermes plugins validate``
- admits and the installer puts down. Requiring the Python entry point made both inspectors report
- such a repository as desktop-only, so a Desktop install skipped the agent half and every
- ``ctx.rest`` call answered 404."""
+ """Electron's ``detectPluginComponents``: an agent half is a portable ``plugin.json``, or a
+ ``plugin.yaml``/``plugin.yml`` with an agent payload beside it (:func:`_yaml_ships_agent_payload`);
+ a desktop half is ``plugin.js`` at the root or in ``desktop/``. ``__init__.py`` is one payload, not
+ a requirement: a manifest-only package with a ``dashboard/plugin_api.py`` backend is installable."""
yaml_path = next((root / n for n in ("plugin.yaml", "plugin.yml") if (root / n).is_file()), None)
+ yaml_manifest = _read_manifest(yaml_path, yaml.safe_load)
portable = root / "plugin.json"
- agent = yaml_path is not None or portable.is_file()
+ agent = (yaml_path is not None and _yaml_ships_agent_payload(root, yaml_manifest)) or portable.is_file()
desktop = (root / "plugin.js").is_file() or (root / "desktop" / "plugin.js").is_file()
agent_name = None
if agent:
- agent_name = (_manifest_name(yaml_path, yaml.safe_load) if yaml_path is not None else None) or (
- _manifest_name(portable, json.loads) if portable.is_file() else None) or fallback_name
+ agent_name = (_manifest_name(yaml_manifest) or _manifest_name(_read_manifest(portable, json.loads))
+ or fallback_name)
return {"agent": agent, "desktop": desktop, "agent_name": agent_name}
diff --git a/tests/fixtures/plugin_component_detection.json b/tests/fixtures/plugin_component_detection.json
index c18c6e8935a..34271320886 100644
--- a/tests/fixtures/plugin_component_detection.json
+++ b/tests/fixtures/plugin_component_detection.json
@@ -27,10 +27,46 @@
"expect": { "agent": true, "desktop": false, "agent_name": "unnamed-plugin" }
},
{
- "name": "a yaml manifest without __init__.py is still an agent package",
+ "name": "a yaml manifest without __init__.py is not an agent half",
"root": "manifest-only",
"files": { "plugin.yaml": "name: manifest-only\n" },
- "expect": { "agent": true, "desktop": false, "agent_name": "manifest-only" }
+ "expect": { "agent": false, "desktop": false, "agent_name": null }
+ },
+ {
+ "name": "a manifest-only package with a dashboard backend and a desktop half installs both halves",
+ "root": "bulletin-repo",
+ "files": { "plugin.yaml": "name: bulletin\n", "dashboard/manifest.json": "{\"name\": \"bulletin\", \"api\": \"plugin_api.py\"}", "dashboard/plugin_api.py": "", "desktop/plugin.js": "export default {}\n" },
+ "expect": { "agent": true, "desktop": true, "agent_name": "bulletin" }
+ },
+ {
+ "name": "a manifest-only dashboard package without a desktop half is an agent half",
+ "root": "dashboard-only",
+ "files": { "plugin.yaml": "name: dash\n", "dashboard/manifest.json": "{}" },
+ "expect": { "agent": true, "desktop": false, "agent_name": "dash" }
+ },
+ {
+ "name": "a desktop plugin whose plugin.yaml is metadata stays desktop-only",
+ "root": "titlebar-widget",
+ "files": { "plugin.yaml": "name: titlebar-widget\nkind: standalone\n", "desktop/plugin.js": "export default {}\n" },
+ "expect": { "agent": false, "desktop": true, "agent_name": null }
+ },
+ {
+ "name": "a manifest-only language pack is an agent half",
+ "root": "lang-pack",
+ "files": { "plugin.yaml": "name: hermes-lang-xx\nprovides_locales:\n - id: xx\n endonym: Xx\n", "locales/xx.yaml": "common.save: Xx\n" },
+ "expect": { "agent": true, "desktop": false, "agent_name": "hermes-lang-xx" }
+ },
+ {
+ "name": "declared locales without a locales folder are not an agent half",
+ "root": "lang-no-folder",
+ "files": { "plugin.yaml": "name: lang-no-folder\nprovides_locales: [xx]\n" },
+ "expect": { "agent": false, "desktop": false, "agent_name": null }
+ },
+ {
+ "name": "an empty provides_locales declares no language pack",
+ "root": "lang-empty",
+ "files": { "plugin.yaml": "name: lang-empty\nprovides_locales: []\n", "locales/xx.yaml": "common.save: Xx\n" },
+ "expect": { "agent": false, "desktop": false, "agent_name": null }
},
{
"name": "a portable plugin.json is an agent half named by it",