Skip to content

The agent that grows with you

fix(plugins): the dependency restart hint names the process that cannot import

Teknium5570f5f5d097
diff --git a/apps/shared/src/gateway-contract.generated.ts b/apps/shared/src/gateway-contract.generated.ts
index d2e99944548..4ea5cbeed91 100644
--- a/apps/shared/src/gateway-contract.generated.ts
+++ b/apps/shared/src/gateway-contract.generated.ts
@@ -4464,7 +4464,7 @@ export interface PluginSettingField {
has_value?: boolean | null
}
export type PluginSettingFieldType = 'string' | 'number' | 'boolean' | 'enum' | 'secret' | 'json'
-/** What a plugin loaded mid-run does NOW vs later (``hermes_cli.plugins_activation``). ``activated_now`` kinds (``{kind: [names]}``): ``gateway_commands`` (slash names), ``locales`` (``<lang>.<surface>`` language-pack layers), ``gateway_transforms`` / ``hooks`` (hook names), ``callbacks`` (platforms / ``slack:<action_id>``) — live in the running gateway once it reloaded (``gateway_reloaded``). ``live_now``: the plugin's MCP servers (connected, with their tools, or the error) and skills, usable in every open chat of the profile from its next turn — the chats also get a note listing them. ``deferred`` kinds: ``tools`` (Python tool names) and ``prompt`` (section ids) apply from the next session. ``missing_dependencies``: the plugin's declared Python requirements the process that answered cannot import (installed after it booted, or never) — only a restart loads them. */
+/** What a plugin loaded mid-run does NOW vs later (``hermes_cli.plugins_activation``). ``activated_now`` kinds (``{kind: [names]}``): ``gateway_commands`` (slash names), ``locales`` (``<lang>.<surface>`` language-pack layers), ``gateway_transforms`` / ``hooks`` (hook names), ``callbacks`` (platforms / ``slack:<action_id>``) — live in the running gateway once it reloaded (``gateway_reloaded``). ``live_now``: the plugin's MCP servers (connected, with their tools, or the error) and skills, usable in every open chat of the profile from its next turn — the chats also get a note listing them. ``deferred`` kinds: ``tools`` (Python tool names) and ``prompt`` (section ids) apply from the next session. ``missing_dependencies``: the plugin's declared Python requirements a running process cannot import (installed after it booted, or never); ``missing_in`` names which processes (``gateway``, ``backend`` = the Desktop / dashboard process) — only restarting them loads them. */
export interface PluginActivation {
name: string
key: string
@@ -4472,6 +4472,7 @@ export interface PluginActivation {
live_now?: PluginLiveNow | null
deferred?: Record<string, string[]>
missing_dependencies?: string[]
+ missing_in?: PluginRestartTarget[]
}
export interface PluginLiveNow {
mcp_servers?: PluginLiveServer[]
@@ -4489,6 +4490,7 @@ export interface PluginLiveSkill {
name: string
description?: string
}
+export type PluginRestartTarget = 'gateway' | 'backend'
/** One security-scan finding (``tools.plugin_guard``) on a plugin tree the scan blocked. */
export interface PluginScanFinding {
pattern_id: string
diff --git a/apps/shared/src/gateway-contract.openrpc.json b/apps/shared/src/gateway-contract.openrpc.json
index c7d2481454d..21701deb5e7 100644
--- a/apps/shared/src/gateway-contract.openrpc.json
+++ b/apps/shared/src/gateway-contract.openrpc.json
@@ -27032,7 +27032,7 @@
},
"PluginActivation": {
"additionalProperties": false,
- "description": "What a plugin loaded mid-run does NOW vs later (``hermes_cli.plugins_activation``). ``activated_now``\nkinds (``{kind: [names]}``): ``gateway_commands`` (slash names), ``locales`` (``<lang>.<surface>``\nlanguage-pack layers), ``gateway_transforms`` / ``hooks`` (hook\nnames), ``callbacks`` (platforms / ``slack:<action_id>``) \u2014 live in the running gateway once it reloaded\n(``gateway_reloaded``). ``live_now``: the plugin's MCP servers (connected, with their tools, or the\nerror) and skills, usable in every open chat of the profile from its next turn \u2014 the chats also get a\nnote listing them. ``deferred`` kinds: ``tools`` (Python tool names) and ``prompt`` (section ids)\napply from the next session. ``missing_dependencies``: the plugin's declared Python requirements the\nprocess that answered cannot import (installed after it booted, or never) \u2014 only a restart loads them.",
+ "description": "What a plugin loaded mid-run does NOW vs later (``hermes_cli.plugins_activation``). ``activated_now``\nkinds (``{kind: [names]}``): ``gateway_commands`` (slash names), ``locales`` (``<lang>.<surface>``\nlanguage-pack layers), ``gateway_transforms`` / ``hooks`` (hook\nnames), ``callbacks`` (platforms / ``slack:<action_id>``) \u2014 live in the running gateway once it reloaded\n(``gateway_reloaded``). ``live_now``: the plugin's MCP servers (connected, with their tools, or the\nerror) and skills, usable in every open chat of the profile from its next turn \u2014 the chats also get a\nnote listing them. ``deferred`` kinds: ``tools`` (Python tool names) and ``prompt`` (section ids)\napply from the next session. ``missing_dependencies``: the plugin's declared Python requirements a\nrunning process cannot import (installed after it booted, or never); ``missing_in`` names which\nprocesses (``gateway``, ``backend`` = the Desktop / dashboard process) \u2014 only restarting them loads them.",
"properties": {
"name": {
"title": "Name",
@@ -27079,6 +27079,13 @@
},
"title": "Missing Dependencies",
"type": "array"
+ },
+ "missing_in": {
+ "items": {
+ "$ref": "#/components/schemas/PluginRestartTarget"
+ },
+ "title": "Missing In",
+ "type": "array"
}
},
"required": [
@@ -27264,6 +27271,14 @@
"title": "PluginLiveSkill",
"type": "object"
},
+ "PluginRestartTarget": {
+ "enum": [
+ "gateway",
+ "backend"
+ ],
+ "title": "PluginRestartTarget",
+ "type": "string"
+ },
"PluginScanFinding": {
"additionalProperties": false,
"description": "One security-scan finding (``tools.plugin_guard``) on a plugin tree the scan blocked.",
diff --git a/hermes_cli/plugins_activation.py b/hermes_cli/plugins_activation.py
index d409d752f9f..3cf63e06a90 100644
--- a/hermes_cli/plugins_activation.py
+++ b/hermes_cli/plugins_activation.py
@@ -127,8 +127,9 @@ def activate_plugin_now(name: str, *, in_process: bool = True) -> dict[str, Any]
``activation.live_now`` lists what is usable in open chats now; ``activation.deferred`` what waits
for the next session. ``restart_required`` is True when no gateway answered (old gateway, not
running), or when this process or the gateway cannot import the plugin's Python dependencies
- (``activation.missing_dependencies``): a running process never switches to the dependency
- generation an enable just installed, so only a restart loads them."""
+ (``activation.missing_dependencies``; ``activation.missing_in`` names which: ``gateway`` and/or
+ ``backend``, the Desktop / dashboard process): a running process never switches to the dependency
+ generation an enable just installed, so only restarting that process loads them."""
from hermes_constants import get_hermes_home
activation: Optional[dict[str, Any]] = load_and_go_live(name) if in_process else None
if not in_process:
@@ -136,12 +137,14 @@ def activate_plugin_now(name: str, *, in_process: bool = True) -> dict[str, Any]
answer = reload_running_gateway()
reloaded = bool(answer and answer.get("reloaded"))
gateway_activation = find_activation((answer or {}).get("activations"), name) if reloaded else None
+ gaps = {"gateway": (gateway_activation or {}).get("missing_dependencies") or [],
+ "backend": (activation or {}).get("missing_dependencies") or []}
if reloaded and activation is None:
activation = gateway_activation
- missing = sorted({*((activation or {}).get("missing_dependencies") or ()),
- *((gateway_activation or {}).get("missing_dependencies") or ())})
+ missing = sorted({*gaps["gateway"], *gaps["backend"]})
if missing:
- activation = {**(activation or {"name": name, "key": name}), "missing_dependencies": missing}
+ activation = {**(activation or {"name": name, "key": name}), "missing_dependencies": missing,
+ "missing_in": [process for process, deps in gaps.items() if deps]}
return {"gateway_reloaded": reloaded, "activation": activation,
"restart_required": not reloaded or bool(missing)}
@@ -274,14 +277,16 @@ def _gateway_present() -> bool:
or _installed_service_kind() is not None)
-def dependency_restart_hint(missing: list[str], *, gateway: bool) -> str:
- """What to do when the running gateway / backend cannot import a plugin's dependencies. *gateway*:
- the messaging gateway answered; otherwise only the Desktop / dashboard backend did, and restarting
- a gateway that does not run would apply to nothing."""
+_RESTART_LINES = {"gateway": " hermes gateway restart",
+ "backend": " quit and reopen the Hermes desktop app (or restart hermes dashboard)"}
+
+
+def dependency_restart_hint(missing: list[str], processes: list[str]) -> str:
+ """What to do when running processes cannot import a plugin's dependencies: one restart line per
+ process that reported the gap (``gateway`` / ``backend``), never one that can already import them."""
from hermes_cli.plugins_loader import installed_in_selected_environment
deps = ", ".join(missing)
- restart = (" hermes gateway restart" if gateway
- else " quit and reopen the Hermes desktop app (or restart hermes dashboard)")
+ restart = "\n".join(_RESTART_LINES[p] for p in processes)
if installed_in_selected_environment(missing):
return (f"Its Python dependencies ({deps}) were installed after the running gateway or dashboard "
"started, and a running process never switches dependency environments. Restart them to "
@@ -309,7 +314,7 @@ def activation_hint(result: dict[str, Any]) -> str:
lines.extend(f"MCP server {s['name']} not connected: {s.get('error') or 'unknown error'}"
for s in live.get("mcp_servers") or () if not s.get("connected"))
if missing := act.get("missing_dependencies"):
- return "\n".join([*lines, dependency_restart_hint(missing, gateway=bool(result.get("gateway_reloaded")))])
+ return "\n".join([*lines, dependency_restart_hint(missing, act.get("missing_in") or [])])
if not result.get("gateway_reloaded"):
# Live in open chats, or no gateway runs or is installed for this profile (first-time setup):
# a messaging gateway that starts later loads it at boot, so a restart applies to nothing.
diff --git a/tests/hermes_cli/test_plugin_dependency_restart.py b/tests/hermes_cli/test_plugin_dependency_restart.py
index 7d7f17e2e1f..7fe47592176 100644
--- a/tests/hermes_cli/test_plugin_dependency_restart.py
+++ b/tests/hermes_cli/test_plugin_dependency_restart.py
@@ -126,10 +126,26 @@ def test_enable_reports_restart_when_the_running_gateway_cannot_import_the_depen
assert result["gateway_reloaded"] is True
assert result["restart_required"] is True
assert result["activation"]["missing_dependencies"] == [REQ]
+ assert result["activation"]["missing_in"] == ["gateway"]
assert "nothing of this plugin needs" not in hint
assert "installed after the running gateway" in hint and "hermes gateway restart" in hint
+def test_restart_names_only_the_process_that_cannot_import(home, monkeypatch):
+ """A gateway restarted since the install imports the dependency; the Desktop backend booted
+ before it does not. The remedy is reopening the app, not restarting the gateway."""
+ _select_generation(home, with_dist=True)
+ _gateway_answers(monkeypatch, [{"name": "depprobe", "key": "depprobe", "activated_now": {}, "deferred": {}}])
+ monkeypatch.setattr(plugins_activation, "notify_serve_backend", lambda name, home: {"activation": {
+ "name": "depprobe", "key": "depprobe", "activated_now": {}, "deferred": {}, "missing_dependencies": [REQ]}})
+
+ result = plugins_activation.activate_plugin_now("depprobe", in_process=False)
+ hint = plugins_activation.activation_hint(result)
+
+ assert result["restart_required"] is True and result["activation"]["missing_in"] == ["backend"]
+ assert "desktop app" in hint and "hermes gateway restart" not in hint
+
+
def test_enable_reports_repair_when_the_dependency_was_never_installed(home, monkeypatch):
_select_generation(home, with_dist=False)
_gateway_answers(monkeypatch, [{"name": "depprobe", "key": "depprobe", "activated_now": {},
diff --git a/tui_gateway/contracts/tools_mcp_plugins.py b/tui_gateway/contracts/tools_mcp_plugins.py
index 035c92306d5..d47f04c2a68 100644
--- a/tui_gateway/contracts/tools_mcp_plugins.py
+++ b/tui_gateway/contracts/tools_mcp_plugins.py
@@ -736,6 +736,11 @@ class PluginLiveNow(Result):
skills: list[PluginLiveSkill] = Field(default_factory=list)
+class PluginRestartTarget(WireEnum):
+ gateway = "gateway"
+ backend = "backend"
+
+
class PluginActivation(Result):
"""What a plugin loaded mid-run does NOW vs later (``hermes_cli.plugins_activation``). ``activated_now``
kinds (``{kind: [names]}``): ``gateway_commands`` (slash names), ``locales`` (``<lang>.<surface>``
@@ -744,8 +749,9 @@ class PluginActivation(Result):
(``gateway_reloaded``). ``live_now``: the plugin's MCP servers (connected, with their tools, or the
error) and skills, usable in every open chat of the profile from its next turn — the chats also get a
note listing them. ``deferred`` kinds: ``tools`` (Python tool names) and ``prompt`` (section ids)
- apply from the next session. ``missing_dependencies``: the plugin's declared Python requirements the
- process that answered cannot import (installed after it booted, or never) — only a restart loads them."""
+ apply from the next session. ``missing_dependencies``: the plugin's declared Python requirements a
+ running process cannot import (installed after it booted, or never); ``missing_in`` names which
+ processes (``gateway``, ``backend`` = the Desktop / dashboard process) — only restarting them loads them."""
name: str
key: str
@@ -753,6 +759,7 @@ class PluginActivation(Result):
live_now: PluginLiveNow | None = None
deferred: dict[str, list[str]] = Field(default_factory=dict)
missing_dependencies: list[str] = Field(default_factory=list)
+ missing_in: list[PluginRestartTarget] = Field(default_factory=list)
class OnboardingCatalogPlugin(Result):