Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
9.3 KB
Raw Blame
"""Tests for the bridge's parent-death spawn seam.

Hermes 0.23 replaced the per-child ``tools.mcp_stdio_watchdog`` wrapper with one
owner-death supervisor per process (hermes-agent commit 2d783a15); the seam it
exposes is ``hermes_cli.process_identity.spawn_owned``. These tests pin the
three-way precedence the bridge promises, in the order a host can offer it:

1. a host with ``spawn_owned`` - the child is spawned through it, so its process
   group reaches the supervisor;
2. an older Hermes with only ``tools.mcp_stdio_watchdog`` - argv is wrapped in
   that poller, exactly as before;
3. neither (a standalone checkout, or any non-Hermes harness) - a plain spawn,
   with one warning that the guarantee is unavailable.

The imports are simulated through ``sys.modules`` so the tests never require a
Hermes checkout, and the same code runs on the CI Python that has no host at all.
"""

import logging
import os
import subprocess
import sys
import types
import unittest
from pathlib import Path
from unittest import mock

ROOT = Path(__file__).resolve().parents[2]
if str(ROOT) not in sys.path:
    sys.path.insert(0, str(ROOT))

from plugins.hermes import bridge as bridge_mod  # noqa: E402
from plugins.hermes.bridge import McpBrainBridge, SPAWN_PURPOSE  # noqa: E402

_MANAGED_MODULES = ("hermes_cli", "hermes_cli.process_identity", "tools", "tools.mcp_stdio_watchdog")


class SpawnSeamTests(unittest.TestCase):
    def setUp(self) -> None:
        self._saved = {name: sys.modules.get(name) for name in _MANAGED_MODULES}
        # A None entry makes the import raise ImportError even on a machine
        # with Hermes installed, so "absent" means absent; a test that needs
        # a host installs its fake modules over these entries.
        for name in _MANAGED_MODULES:
            sys.modules[name] = None
        McpBrainBridge._watchdog_absent_warned = False
        self.bridge = McpBrainBridge(vault=None)

    def tearDown(self) -> None:
        for name, module in self._saved.items():
            if module is None:
                sys.modules.pop(name, None)
            else:
                sys.modules[name] = module
        McpBrainBridge._watchdog_absent_warned = False

    def _install_spawn_owned(self, recorder):
        package = types.ModuleType("hermes_cli")
        package.__path__ = []  # a package, so the submodule import resolves
        identity = types.ModuleType("hermes_cli.process_identity")
        setattr(identity, "spawn_owned", recorder)
        setattr(package, "process_identity", identity)
        sys.modules["hermes_cli"] = package
        sys.modules["hermes_cli.process_identity"] = identity

    def _install_legacy_watchdog(self):
        package = types.ModuleType("tools")
        package.__path__ = []
        watchdog = types.ModuleType("tools.mcp_stdio_watchdog")
        watchdog.__file__ = "/host/tools/mcp_stdio_watchdog.py"
        setattr(package, "mcp_stdio_watchdog", watchdog)
        sys.modules["tools"] = package
        sys.modules["tools.mcp_stdio_watchdog"] = watchdog

    def test_spawn_owned_is_preferred_when_the_host_provides_it(self) -> None:
        calls = []

        def spawn_owned(argv, *, purpose, **popen_kwargs):
            calls.append((argv, purpose, popen_kwargs))
            return mock.sentinel.process

        self._install_spawn_owned(spawn_owned)
        with mock.patch("subprocess.Popen", side_effect=AssertionError("plain Popen must not run")):
            process = self.bridge._default_spawn(["o2b", "mcp"])

        self.assertIs(process, mock.sentinel.process)
        self.assertEqual(len(calls), 1)
        argv, purpose, popen_kwargs = calls[0]
        self.assertEqual(argv, ["o2b", "mcp"])
        self.assertEqual(purpose, SPAWN_PURPOSE)
        self.assertEqual(popen_kwargs["bufsize"], 0)
        self.assertIn("cwd", popen_kwargs)
        self.assertIn("env", popen_kwargs)

    @unittest.skipIf(os.name != "posix", "the legacy watchdog wraps POSIX children only; Windows relies on the layer-3 job object")
    def test_legacy_watchdog_wraps_argv_when_spawn_owned_is_absent(self) -> None:
        self._install_legacy_watchdog()
        with mock.patch("subprocess.Popen", return_value=mock.sentinel.process) as popen:
            process = self.bridge._default_spawn(["o2b", "mcp"])

        self.assertIs(process, mock.sentinel.process)
        spawned = popen.call_args.args[0]
        self.assertEqual(
            spawned,
            [
                sys.executable,
                "/host/tools/mcp_stdio_watchdog.py",
                "--ppid",
                str(os.getpid()),
                "--",
                "o2b",
                "mcp",
            ],
        )

    @unittest.skipIf(os.name != "posix", "the legacy watchdog wraps POSIX children only; Windows relies on the layer-3 job object")
    def test_plain_spawn_warns_once_when_no_host_seam_exists(self) -> None:
        with mock.patch("subprocess.Popen", return_value=mock.sentinel.process) as popen:
            with self.assertLogs(bridge_mod.logger, level=logging.WARNING) as logs:
                self.bridge._default_spawn(["o2b", "mcp"])
                self.bridge._default_spawn(["o2b", "mcp"])

        self.assertEqual(popen.call_args.args[0], ["o2b", "mcp"])
        warnings = [line for line in logs.output if "parent-death watchdog module unavailable" in line]
        self.assertEqual(len(warnings), 1, "the absence is a property of the install, not of the call")

    def test_broken_host_import_degrades_to_plain_spawn(self) -> None:
        package = types.ModuleType("hermes_cli")
        package.__path__ = []
        sys.modules["hermes_cli"] = package

        class Broken(types.ModuleType):
            def __getattr__(self, name):  # noqa: D105 - attribute access is the failure
                raise RuntimeError("host import is broken")

        sys.modules["hermes_cli.process_identity"] = Broken("hermes_cli.process_identity")

        with mock.patch("subprocess.Popen", return_value=mock.sentinel.process) as popen:
            process = self.bridge._default_spawn(["o2b", "mcp"])

        self.assertIs(process, mock.sentinel.process)
        self.assertEqual(popen.call_args.args[0], ["o2b", "mcp"])


class SpawnOwnedProbeTests(unittest.TestCase):
    def test_probe_returns_none_without_the_host_module(self) -> None:
        names = ("hermes_cli", "hermes_cli.process_identity")
        saved = {name: sys.modules.get(name) for name in names}
        for name in names:
            sys.modules[name] = None  # blocks a real install too
        try:
            self.assertIsNone(bridge_mod._hermes_spawn_owned())
        finally:
            for name, module in saved.items():
                if module is None:
                    sys.modules.pop(name, None)
                else:
                    sys.modules[name] = module

    def test_probe_returns_the_host_callable(self) -> None:
        package = types.ModuleType("hermes_cli")
        package.__path__ = []
        identity = types.ModuleType("hermes_cli.process_identity")
        setattr(identity, "spawn_owned", lambda *a, **k: None)
        sys.modules["hermes_cli"] = package
        sys.modules["hermes_cli.process_identity"] = identity
        try:
            self.assertIs(bridge_mod._hermes_spawn_owned(), identity.spawn_owned)
        finally:
            sys.modules.pop("hermes_cli", None)
            sys.modules.pop("hermes_cli.process_identity", None)



class _FakeProc:
    """A child that reports clean exit, so stop() reaches its release path."""

    def __init__(self, pid: int = 4242) -> None:
        self.pid = pid
        self.terminated = False
        self.stdin = None
        self.stdout = None
        self.stderr = None

    def poll(self):
        return None

    def terminate(self) -> None:
        self.terminated = True

    def wait(self, timeout=None):
        return 0

    def kill(self) -> None:  # pragma: no cover - terminate/wait succeed first
        pass


class OwnedChildReleaseTests(unittest.TestCase):
    """A supervised child's process group is handed back when the bridge stops."""

    def setUp(self) -> None:
        self.proc = _FakeProc()
        self.released = []
        package = types.ModuleType("hermes_cli")
        package.__path__ = []
        identity = types.ModuleType("hermes_cli.process_identity")
        setattr(identity, "spawn_owned", lambda argv, *, purpose, **kw: self.proc)

        def release(pid, *, proc=None):
            self.released.append((pid, proc))

        setattr(identity, "release_process_group_once_empty", release)
        setattr(package, "process_identity", identity)
        sys.modules["hermes_cli"] = package
        sys.modules["hermes_cli.process_identity"] = identity
        self.bridge = McpBrainBridge(vault=None)

    def tearDown(self) -> None:
        sys.modules.pop("hermes_cli", None)
        sys.modules.pop("hermes_cli.process_identity", None)

    def test_stop_releases_the_supervised_group_once(self) -> None:
        self.bridge._proc = self.bridge._default_spawn(["o2b", "mcp"])
        self.assertTrue(self.bridge._spawned_owned)
        self.bridge.stop()
        self.assertEqual(self.released, [(self.proc.pid, self.proc)])
        self.assertFalse(self.bridge._spawned_owned)

    def test_stop_without_a_supervised_child_releases_nothing(self) -> None:
        self.bridge._proc = _FakeProc()
        self.bridge.stop()
        self.assertEqual(self.released, [])


if __name__ == "__main__":
    unittest.main()