Skip to content

The agent that grows with you

fix(terminal): a plugin backend in the plugin host refuses with the isolation setting

Teknium02f46d981830
diff --git a/hermes_cli/plugin_host.py b/hermes_cli/plugin_host.py
index 70167192f30..3f4a6693bff 100644
--- a/hermes_cli/plugin_host.py
+++ b/hermes_cli/plugin_host.py
@@ -535,6 +535,13 @@ def _holds_live_handle(value: Any) -> bool:
return found or (isinstance(encoded, dict) and "__opaque__" in encoded)
+def is_hosted_object(obj: Any) -> bool:
+ """``obj`` is a proxy for a plugin object whose code runs in the plugin host (``plugins.isolation:
+ host``): its methods run there and anything they return that is not plain data arrives as an
+ :class:`Opaque` placeholder."""
+ return "__hermes_plugin_host_ref__" in vars(type(obj))
+
+
def _run_on_gateway_loop(coro: Any) -> Any:
"""A facade coroutine (``platform_actions``) uses adapters bound to the gateway's event loop, so
it runs there when a gateway is up; otherwise on a private loop. Always called off-loop (a
diff --git a/tests/tools/test_terminal_plugin_host_isolation.py b/tests/tools/test_terminal_plugin_host_isolation.py
new file mode 100644
index 00000000000..7d6c8d340bc
--- /dev/null
+++ b/tests/tools/test_terminal_plugin_host_isolation.py
@@ -0,0 +1,84 @@
+"""A user terminal backend under ``plugins.isolation: host``: the plugin's environment object cannot cross
+the host boundary (its methods would run outside the Hermes process's interrupt, activity and terminal-scope
+state), so creating it refuses with the setting to change before the host starts a sandbox nobody can use
+or clean up. Real plugin, real host process, real loader against a temp HERMES_HOME.
+"""
+
+from __future__ import annotations
+
+import hermes_yaml as yaml
+import pytest
+
+from hermes_cli import plugins as plugins_mod
+from hermes_cli.plugins import PluginManager
+
+BACKEND_PLUGIN = '''
+from pathlib import Path
+from agent.terminal_env_provider import TerminalEnvironmentProvider
+
+MARKER = Path(__file__).with_name("created")
+
+class Env:
+ def execute(self, command, **kw):
+ return {"output": command, "returncode": 0}
+ def cleanup(self):
+ pass
+
+class Box(TerminalEnvironmentProvider):
+ @property
+ def name(self):
+ return "hostbox"
+ def is_available(self):
+ return True
+ def create_environment(self, *, cwd, timeout, task_id="default", image=None, container_config=None, **kw):
+ MARKER.write_text("sandbox started")
+ return Env()
+
+def register(ctx):
+ ctx.register_terminal_environment_provider(Box())
+'''
+
+
+def _load(tmp_path, monkeypatch, isolation):
+ home = tmp_path / ".hermes"
+ plugin_dir = home / "plugins" / "hostbox"
+ plugin_dir.mkdir(parents=True)
+ (plugin_dir / "plugin.yaml").write_text(yaml.safe_dump({"name": "hostbox", "version": "1.0"}), encoding="utf-8")
+ (plugin_dir / "__init__.py").write_text(BACKEND_PLUGIN, encoding="utf-8")
+ (home / "config.yaml").write_text(yaml.safe_dump(
+ {"plugins": {"enabled": ["hostbox"], "isolation": isolation}, "terminal": {"backend": "hostbox"}}),
+ encoding="utf-8")
+ empty_bundled = tmp_path / "bundled"
+ empty_bundled.mkdir()
+ monkeypatch.setenv("HOME", str(tmp_path / "os-home"))
+ monkeypatch.setenv("HERMES_HOME", str(home))
+ monkeypatch.setattr(plugins_mod, "get_bundled_plugins_dir", lambda: empty_bundled)
+ manager = PluginManager()
+ manager.discover_and_load()
+ assert manager._plugins["hostbox"].error is None
+ return manager, plugin_dir / "created"
+
+
+def test_a_hosted_terminal_backend_refuses_with_the_isolation_setting(tmp_path, monkeypatch):
+ from tools.terminal_tool_backends import _create_environment
+
+ manager, marker = _load(tmp_path, monkeypatch, "host")
+ try:
+ with pytest.raises(ValueError, match=r"plugins\.isolation: in_process"):
+ _create_environment("hostbox", image="", cwd="/", timeout=10)
+ assert not marker.exists() # no sandbox started in the host
+ finally:
+ manager.unload()
+ manager._plugin_host().shutdown()
+
+
+def test_the_same_backend_in_process_runs_commands(tmp_path, monkeypatch):
+ from tools.terminal_tool_backends import _create_environment
+
+ manager, marker = _load(tmp_path, monkeypatch, "in_process")
+ try:
+ env = _create_environment("hostbox", image="", cwd="/", timeout=10)
+ assert env.execute("echo hi") == {"output": "echo hi", "returncode": 0}
+ assert marker.exists()
+ finally:
+ manager.unload()
diff --git a/tools/terminal_tool_backends.py b/tools/terminal_tool_backends.py
index 0436b10a46b..5c752c5b14a 100644
--- a/tools/terminal_tool_backends.py
+++ b/tools/terminal_tool_backends.py
@@ -236,6 +236,15 @@ def _stamp_sandbox_home(env_obj, provider, cwd) -> None:
def _build_plugin_env(*, env_type, image, cwd, timeout, cc, task_id, **_):
provider = _get_plugin_env_provider(env_type)
if provider is not None:
+ from hermes_cli.plugin_host import is_hosted_object
+ if is_hosted_object(provider):
+ # The environment would come back as an opaque placeholder, and its execute() would run outside
+ # this process's interrupt, activity and terminal-scope state: refuse before the host starts a
+ # sandbox nothing here could use or clean up.
+ raise ValueError(
+ f"terminal.backend is {env_type}, a plugin that runs in the plugin host (plugins.isolation: host), "
+ f"and the host cannot hand its environment to Hermes, so commands cannot run in it. Set "
+ f"plugins.isolation: in_process to use this backend.")
env_obj = provider.create_environment(cwd=cwd, timeout=timeout, task_id=task_id, image=image,
container_config=cc)
# Stamp the backend name so path-resolution and progress surfaces can identify plugin
diff --git a/website/docs/developer-guide/terminal-environment-plugin.md b/website/docs/developer-guide/terminal-environment-plugin.md
index b25175b2707..a25924fd9c8 100644
--- a/website/docs/developer-guide/terminal-environment-plugin.md
+++ b/website/docs/developer-guide/terminal-environment-plugin.md
@@ -207,11 +207,12 @@ the browser keep their scratch files under the environment's
`get_temp_dir()`. An environment that doesn't subclass `BaseEnvironment` and
has no such method gets the same default `BaseEnvironment` uses.
-Both `exec_prefix()` and the `~` home resolution read the environment object
-itself, so they work only for plugins loaded in-process. Under
-`plugins.isolation: host` the environment reaches Hermes as an opaque
-placeholder: Bot Desktop refuses a `supports_streams` backend with a message
-naming the setting, and `default_cwd = "~"` stays a literal `~`.
+A terminal backend runs only in-process: its environment object is what the
+terminal tool, file tools, `exec_prefix()` and the `~` home resolution all
+drive. Under `plugins.isolation: host` the object cannot cross the host
+boundary, so creating the environment refuses with a message naming
+`plugins.isolation: in_process` (before the host starts a sandbox), and Bot
+Desktop refuses a `supports_streams` backend the same way.
## Session isolation semantics
diff --git a/website/docs/user-guide/features/plugins.md b/website/docs/user-guide/features/plugins.md
index a9cb9b48098..3899f0cf5e2 100644
--- a/website/docs/user-guide/features/plugins.md
+++ b/website/docs/user-guide/features/plugins.md
@@ -887,7 +887,8 @@ What changes in `host` mode:
flight returns a tool error and Hermes restarts the host and reloads its plugins (bounded retries).
- **A few surfaces need in-process code** and fail that plugin with a clear reason instead of loading:
gateway platform adapters (`register_platform`), approval transports, Telegram/platform handlers,
- model-provider profiles that build their own SDK client (`create_client`), streaming and websocket
+ model-provider profiles that build their own SDK client (`create_client`), terminal backends (the
+ backend's commands fail with this reason; the `singularity` plugin is one), streaming and websocket
dashboard endpoints, and plugins that monkeypatch Hermes modules. Run those with `isolation: in_process`.
**Locking it for a shared deployment.** `plugins.isolation` is ordinary profile config, so whoever can