Skip to content

Self-improving AI Employees for everyone

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.py
index 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_service
diff --git a/server/nodes/android/__init__.py b/server/nodes/android/__init__.py
index 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_hook
from services.status_broadcaster import register_service_refresh
from services.ws_handler_registry import (
register_option_loader,
@@ -21,6 +22,7 @@ from ._events import broadcast_android_status # noqa: F401 — re-export
from ._handlers import WS_HANDLERS
from ._option_loaders import load_service_actions
from ._refresh import refresh_android_status
+from ._relay.manager import close_relay_client
register_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__.py
index 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.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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}"
+ )