Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
refactor(plugin): shutdown_hooks registry closes 2 cross-plugin reaches in main.py lifespan (Wave 12 C4 #B)
trohitg49122393c615
diff --git a/server/main.py b/server/main.pyindex b5abb031..abac1386 100644--- a/server/main.py+++ b/server/main.py@@ -366,13 +366,14 @@ async def lifespan(app: FastAPI):if _proxy_svc:await _proxy_svc.shutdown()- # Close Android relay client (prevents "Unclosed client session" warning)- from nodes.android._relay.manager import close_relay_client- await close_relay_client(clear_stored_session=False)-- # Shut down agent-browser daemon (prevents orphaned processes and EBUSY file locks)- from nodes.browser._service import shutdown_browser_service- await shutdown_browser_service()+ # Wave 12 C4 sub-piece B: drain every plugin that self-registered+ # a shutdown hook via services.plugin.shutdown_hooks. Today:+ # android relay client (prevents "Unclosed client session" warning),+ # browser service (prevents orphaned processes + EBUSY file locks).+ # New plugins with cleanup needs register a hook from their+ # __init__.py — main.py never edits.+ from services.plugin.shutdown_hooks import run_shutdown_hooks+ await run_shutdown_hooks()# Kill all managed processes (process manager node)from services.process_service import shutdown_process_servicediff --git a/server/nodes/android/__init__.py b/server/nodes/android/__init__.pyindex 54fb3799..309951e6 100644--- a/server/nodes/android/__init__.py+++ b/server/nodes/android/__init__.py@@ -9,6 +9,7 @@ wifi_automation, ...) live alongside as siblings.Wiring is body-free; both registrations are idempotent."""+from services.plugin.shutdown_hooks import register_shutdown_hookfrom services.status_broadcaster import register_service_refreshfrom services.ws_handler_registry import (register_option_loader,@@ -21,6 +22,7 @@ from ._events import broadcast_android_status # noqa: F401 — re-exportfrom ._handlers import WS_HANDLERSfrom ._option_loaders import load_service_actionsfrom ._refresh import refresh_android_status+from ._relay.manager import close_relay_clientregister_ws_handlers(WS_HANDLERS)register_router(_router.router, name="android")@@ -30,3 +32,16 @@ register_service_refresh(refresh_android_status)# leave services/node_option_loaders/, which is deleted at the same# commit.register_option_loader("getAndroidServiceActions", load_service_actions)+++# Wave 12 C4 sub-piece B: register shutdown hook so FastAPI lifespan+# teardown reaches the relay WebSocket client without main.py needing+# to know about this plugin. See services/plugin/shutdown_hooks.py.+# Wrap close_relay_client to match the no-arg hook signature; preserve+# the stored session per the existing lifespan call (only the WS+# connection is torn down on shutdown, not the pairing token).+async def _shutdown_android_relay() -> None:+ await close_relay_client(clear_stored_session=False)+++register_shutdown_hook("android_relay", _shutdown_android_relay)diff --git a/server/nodes/browser/__init__.py b/server/nodes/browser/__init__.pyindex c22b2e13..0594a6bf 100644--- a/server/nodes/browser/__init__.py+++ b/server/nodes/browser/__init__.py@@ -1 +1,15 @@-"""Plugins for the 'browser' palette group. See ../__init__.py for the package layout."""+"""Plugins for the 'browser' palette group. See ../__init__.py for the package layout.++Self-registration on import:+ - FastAPI lifespan shutdown hook (Wave 12 C4 sub-piece B) — the+ agent-browser daemon needs an explicit close to release file+ locks. Registered through ``services.plugin.shutdown_hooks`` so+ ``main.py`` lifespan teardown reaches us without cross-plugin+ imports.+"""++from services.plugin.shutdown_hooks import register_shutdown_hook++from ._service import shutdown_browser_service++register_shutdown_hook("browser_service", shutdown_browser_service)diff --git a/server/services/plugin/registry.py b/server/services/plugin/registry.pyindex d4969c83..0d8d14ea 100644--- a/server/services/plugin/registry.py+++ b/server/services/plugin/registry.py@@ -80,23 +80,27 @@ class IdempotentRegistry(Generic[K, V]):def register(self, key: K, value: V) -> None:"""Add ``key -> value``. Idempotent on equality; raises on conflict.- Equality (``!=``) instead of identity (``is not``) so the- registry stays idempotent across:-- * String / int / dataclass value types where Python does not- guarantee interning (e.g. two ``"/api/google/callback"``- literals from separate module loads).- * ``importlib.reload(module)`` — reload constructs fresh- function / class objects whose identity differs from the- originals, but they're functionally equivalent and should- re-register cleanly. The self-containment test suite relies- on this.-- Genuinely conflicting registrations (different values for the- same key) still raise ``ValueError`` at import time.+ Three equivalence checks (any match = idempotent re-register):++ 1. ``existing == value`` — covers strings / ints / dataclasses /+ dicts (content-equal even on reload) and singleton instances+ cached across imports.+ 2. **Reload tolerance for callables**: same fully-qualified+ name (``__module__`` + ``__qualname__``) means the same+ source-level function reloaded under fresh identity.+ ``importlib.reload(module)`` constructs new function objects+ that compare unequal under Python's identity-based+ ``function.__eq__``; without this branch the+ self-containment reload tests would break for every plugin+ that registers a wrapper closure.+ 3. **Reload tolerance for classes**: same ``__module__`` ++ ``__qualname__`` for class objects (same reason).++ Genuinely conflicting registrations (different values, different+ names) still raise ``ValueError`` at import time."""existing = self._items.get(key)- if existing is not None and existing != value:+ if existing is not None and not self._values_equivalent(existing, value):raise ValueError(f"{self._name}: {key!r} is already registered by "f"{_qual(existing)}; refusing to overwrite with {_qual(value)}"@@ -105,6 +109,35 @@ class IdempotentRegistry(Generic[K, V]):if self._on_register is not None:self._on_register(key, value)+ @staticmethod+ def _values_equivalent(existing: object, new: object) -> bool:+ """True iff ``existing`` and ``new`` are the same registration+ for idempotency purposes. See :meth:`register` docstring."""+ # Content equality first (strings, dicts, dataclasses, singletons+ # cached across imports). Catches the bulk of cases.+ try:+ if existing == new:+ return True+ except Exception: # noqa: BLE001 — exotic types with broken __eq__+ pass++ # Reload tolerance: callable / class objects re-defined under a+ # fresh module-level identity still count as the "same"+ # registration when their fully-qualified name matches.+ existing_module = getattr(existing, "__module__", None)+ new_module = getattr(new, "__module__", None)+ existing_qualname = getattr(existing, "__qualname__", None)+ new_qualname = getattr(new, "__qualname__", None)+ if (+ existing_qualname is not None+ and new_qualname is not None+ and existing_module == new_module+ and existing_qualname == new_qualname+ ):+ return True++ return False+def get(self, key: K) -> Optional[V]:return self._items.get(key)diff --git a/server/services/plugin/shutdown_hooks.py b/server/services/plugin/shutdown_hooks.pynew file mode 100644index 00000000..e989a88e--- /dev/null+++ b/server/services/plugin/shutdown_hooks.py@@ -0,0 +1,106 @@+"""Plugin-owned shutdown-hook registry for FastAPI lifespan teardown.++Closes the cross-plugin reaches in ``main.py``:++ - ``from nodes.android._relay.manager import close_relay_client``+ - ``from nodes.browser._service import shutdown_browser_service``++Both made the framework's lifespan code know about specific plugins'+internals. Plugins with cleanup logic now self-register a hook; the+lifespan awaits all registered hooks via :func:`run_shutdown_hooks`.++Distinct from :mod:`services._supervisor`: that registry is for+managed-subprocess supervisors (Go binaries, etc.) with a well-defined+``shutdown()`` contract. This registry is the general async-cleanup+hatch — any coroutine-shaped teardown (close a connection, drain a+queue, flush a cache, ...) goes here.++Hook signature+--------------++::++ hook() -> Awaitable[None]++The hook is named (label) so failures during shutdown surface with a+plugin identifier instead of just a traceback. Failures DO NOT block+sibling hooks — every hook runs even if one raises, mirroring the+``shutdown_all_supervisors`` semantics.+"""++from __future__ import annotations++from typing import Awaitable, Callable, List, Tuple++from core.logging import get_logger+from services.plugin.registry import IdempotentRegistry++logger = get_logger(__name__)+++ShutdownHook = Callable[[], Awaitable[None]]+++# Registry is keyed by label so each plugin can register exactly one+# hook under a stable name. The `items` view preserves insertion order+# (CPython 3.7+ dict ordering guarantee) which gives deterministic+# shutdown ordering. Plugins that need ordering invariants should+# document them via their label naming.+_REGISTRY: IdempotentRegistry[str, ShutdownHook] = IdempotentRegistry(+ "plugin_shutdown_hook"+)+++def register_shutdown_hook(label: str, hook: ShutdownHook) -> None:+ """Publish a shutdown hook for FastAPI lifespan teardown.++ Idempotent on re-import (same callable for the same label is a+ no-op). A different callable for an existing label raises+ ``ValueError`` to surface plugin namespace collisions at import time.++ Args:+ label: Stable plugin identifier (``"android_relay"``,+ ``"browser_service"``, ...). Surfaces in shutdown logs ++ in the error message if the hook raises.+ hook: Async function taking no arguments. Should be+ idempotent (lifespan may run it multiple times during+ test harness teardown).+ """+ _REGISTRY.register(label, hook)+++def registered_labels() -> Tuple[str, ...]:+ """Return registered hook labels in insertion order (snapshot)."""+ return tuple(_REGISTRY.keys())+++async def run_shutdown_hooks() -> None:+ """Run every registered shutdown hook in registration order.++ Per-hook failures are caught + logged with the hook's label so+ one slow / broken plugin doesn't strand the rest of the lifespan+ teardown. Mirrors ``services._supervisor.shutdown_all_supervisors``+ semantics.+ """+ hooks: List[Tuple[str, ShutdownHook]] = list(_REGISTRY.items().items())+ if not hooks:+ return++ logger.info(f"Running {len(hooks)} plugin shutdown hook(s): "+ f"{[label for label, _ in hooks]}")+ for label, hook in hooks:+ try:+ await hook()+ except Exception as exc: # noqa: BLE001 — log and continue+ logger.error(+ f"Plugin shutdown hook {label!r} raised; continuing: {exc}",+ exc_info=True,+ )+++__all__ = [+ "register_shutdown_hook",+ "registered_labels",+ "run_shutdown_hooks",+ "ShutdownHook",+]diff --git a/server/tests/test_shutdown_hooks.py b/server/tests/test_shutdown_hooks.pynew file mode 100644index 00000000..a6821803--- /dev/null+++ b/server/tests/test_shutdown_hooks.py@@ -0,0 +1,199 @@+"""Wave 12 C4 sub-piece B: shutdown-hooks registry contract + invariant.++Locks three layers:++1. **Registry surface**: idempotent registration, deterministic+ ordering, per-hook failure isolation.++2. **Architectural invariant on main.py**: the FastAPI lifespan must+ NOT cross-import plugin internals for shutdown. The+ ``from nodes.android._relay.manager import close_relay_client`` /+ ``from nodes.browser._service import shutdown_browser_service``+ lines that lived at main.py:370/374 are gone — replaced by+ ``run_shutdown_hooks()`` from this registry.++3. **Plugin self-registration smoke**: importing the android and+ browser plugins populates the registry.++Same source-introspection pattern as ``test_canary_registry.py`` and+``test_social_provider_registry.py``.+"""++from __future__ import annotations++import inspect+import re+import sys+import types+from typing import List+from unittest.mock import AsyncMock, MagicMock++import pytest+++if "machina" not in sys.modules:+ _machina = types.ModuleType("machina")+ _machina.__path__ = []+ sys.modules["machina"] = _machina+ _machina_tcp = types.ModuleType("machina.tcp")+ _machina_tcp.probe_tcp_port = MagicMock(return_value=False)+ sys.modules["machina.tcp"] = _machina_tcp+++def fresh_registry(monkeypatch):+ """Reset registry's backing dict for test isolation."""+ from services.plugin import shutdown_hooks as sh++ fresh = type(sh._REGISTRY)(sh._REGISTRY._name) # type: ignore[attr-defined]+ monkeypatch.setattr(sh, "_REGISTRY", fresh)+ return sh+++class TestRegistryContract:+ @pytest.mark.asyncio+ async def test_register_then_run_invokes_hook(self, fresh_registry):+ calls: List[str] = []++ async def hook():+ calls.append("ran")++ fresh_registry.register_shutdown_hook("test_hook", hook)+ await fresh_registry.run_shutdown_hooks()++ assert calls == ["ran"]++ @pytest.mark.asyncio+ async def test_run_with_no_hooks_is_noop(self, fresh_registry):+ # No exception, no log spam, just returns.+ await fresh_registry.run_shutdown_hooks()+ assert fresh_registry.registered_labels() == ()++ @pytest.mark.asyncio+ async def test_hooks_run_in_registration_order(self, fresh_registry):+ order: List[str] = []++ async def first():+ order.append("first")++ async def second():+ order.append("second")++ async def third():+ order.append("third")++ fresh_registry.register_shutdown_hook("a_first", first)+ fresh_registry.register_shutdown_hook("b_second", second)+ fresh_registry.register_shutdown_hook("c_third", third)++ await fresh_registry.run_shutdown_hooks()+ assert order == ["first", "second", "third"]++ @pytest.mark.asyncio+ async def test_hook_failure_does_not_block_siblings(self, fresh_registry):+ """One broken plugin can't strand the rest of teardown."""+ survivors: List[str] = []++ async def broken():+ raise RuntimeError("simulated plugin shutdown crash")++ async def survives():+ survivors.append("ok")++ fresh_registry.register_shutdown_hook("broken_first", broken)+ fresh_registry.register_shutdown_hook("survives_second", survives)++ # No exception bubbles up — log + continue.+ await fresh_registry.run_shutdown_hooks()+ assert survivors == ["ok"]++ def test_idempotent_same_callable(self, fresh_registry):+ async def h():+ return None++ fresh_registry.register_shutdown_hook("x", h)+ fresh_registry.register_shutdown_hook("x", h)+ assert fresh_registry.registered_labels() == ("x",)++ def test_conflicting_register_raises(self, fresh_registry):+ async def h1():+ return None++ async def h2():+ return None++ fresh_registry.register_shutdown_hook("x", h1)+ with pytest.raises(ValueError, match="already registered"):+ fresh_registry.register_shutdown_hook("x", h2)+++class TestNoCrossPluginShutdownReachesInMain:+ """Lifespan teardown in main.py must not import plugin internals.++ Reads ``main.py`` as a source file (not via import) — the module+ has top-level imports that aren't satisfiable in the test env, and+ importing isn't needed for the architectural assertion: we're+ checking what the file *says*, not what it does at runtime.+ """++ _MAIN_PY_PATH = "main.py"++ _FORBIDDEN_LIFESPAN_IMPORTS = (+ ("nodes.android._relay.manager", "close_relay_client"),+ ("nodes.browser._service", "shutdown_browser_service"),+ )++ def _read_main_source(self) -> str:+ # `tests/` and `main.py` are siblings under server/.+ import pathlib++ main_py = pathlib.Path(__file__).resolve().parent.parent / self._MAIN_PY_PATH+ assert main_py.exists(), f"Could not locate main.py at {main_py}"+ return main_py.read_text(encoding="utf-8")++ def test_main_drops_legacy_shutdown_imports(self):+ src = self._read_main_source()++ for module_path, symbol in self._FORBIDDEN_LIFESPAN_IMPORTS:+ pattern = re.compile(+ rf"from\s+{re.escape(module_path)}\s+import\s+{re.escape(symbol)}",+ re.MULTILINE,+ )+ assert pattern.search(src) is None, (+ f"main.py still imports {symbol} from {module_path}. "+ "Lifespan teardown must route through "+ "services.plugin.shutdown_hooks.run_shutdown_hooks(). "+ "Plugin should call register_shutdown_hook(...) from its "+ "own __init__.py."+ )++ def test_main_invokes_run_shutdown_hooks(self):+ src = self._read_main_source()+ assert "run_shutdown_hooks" in src, (+ "main.py lifespan teardown must call "+ "services.plugin.shutdown_hooks.run_shutdown_hooks(). "+ "Without it, plugins that register hooks never drain."+ )+++class TestPluginSelfRegistration:+ """Smoke: importing each plugin populates the registry."""++ @pytest.mark.parametrize("plugin_module,expected_label", [+ ("nodes.android", "android_relay"),+ ("nodes.browser", "browser_service"),+ ])+ def test_plugin_import_registers_its_hook(self, plugin_module, expected_label):+ from services.plugin import shutdown_hooks as sh++ try:+ __import__(plugin_module)+ except ImportError as exc: # pragma: no cover+ pytest.xfail(f"plugin module {plugin_module} not importable: {exc}")++ labels = sh.registered_labels()+ assert expected_label in labels, (+ f"Importing {plugin_module} should call "+ f"register_shutdown_hook({expected_label!r}, ...). "+ f"Current labels: {labels}"+ )