Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
feat(plugin): @ws_response decorator + lazy DI helpers + reference adopters (Wave 11.I, T-residual)
trohitgdac74c5b7107
diff --git a/server/nodes/android/_handlers.py b/server/nodes/android/_handlers.pyindex 338b3c57..f657bfbe 100644--- a/server/nodes/android/_handlers.py+++ b/server/nodes/android/_handlers.py@@ -23,6 +23,7 @@ from typing import Any, Dictfrom starlette.websockets import WebSocketfrom core.logging import get_logger+from services.plugin.ws import ws_responsefrom services.status_broadcaster import get_status_broadcasterlogger = get_logger(__name__)@@ -61,6 +62,7 @@ async def handle_execute_android_action(data: Dict[str, Any], websocket: WebSockreturn result+@ws_responseasync def handle_android_relay_connect(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:"""Connect to the Android relay server.@@ -79,44 +81,37 @@ async def handle_android_relay_connect(data: Dict[str, Any], websocket: WebSockelogger.info(f"[WebSocket] Android relay connect: {url}")- try:- client, error = await get_relay_client(url, api_key)- if client:- logger.info(- f"[WebSocket] Android relay connect success, qr_data present: "- f"{bool(client.qr_data)}, session_token: {client.session_token}"- )- return {- "success": True,- "connected": True,- "session_token": client.session_token,- "qr_data": client.qr_data,- "message": "Connected to relay server",- }+ client, error = await get_relay_client(url, api_key)+ if client:+ logger.info(+ f"[WebSocket] Android relay connect success, qr_data present: "+ f"{bool(client.qr_data)}, session_token: {client.session_token}"+ )return {- "success": False,- "connected": False,- "error": error or "Failed to connect to relay server",+ "success": True,+ "connected": True,+ "session_token": client.session_token,+ "qr_data": client.qr_data,+ "message": "Connected to relay server",}- except Exception as e:- logger.error(f"[WebSocket] Android relay connect error: {e}")- return {"success": False, "error": str(e)}+ return {+ "success": False,+ "connected": False,+ "error": error or "Failed to connect to relay server",+ }+@ws_responseasync def handle_android_relay_disconnect(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:"""Disconnect from the Android relay server."""from ._relay import close_relay_clientlogger.info("[WebSocket] Android relay disconnect requested")-- try:- await close_relay_client()- return {"success": True, "connected": False, "message": "Disconnected from relay server"}- except Exception as e:- logger.error(f"[WebSocket] Android relay disconnect error: {e}")- return {"success": False, "error": str(e)}+ await close_relay_client()+ return {"success": True, "connected": False, "message": "Disconnected from relay server"}+@ws_responseasync def handle_android_relay_reconnect(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:"""Reconnect to the relay with a fresh session token + QR code."""from ._relay import close_relay_client, get_relay_client@@ -131,27 +126,23 @@ async def handle_android_relay_reconnect(data: Dict[str, Any], websocket: WebSoclogger.info("[WebSocket] Android relay reconnect: forcing new session")- try:- await close_relay_client()- await asyncio.sleep(0.5) # ensure clean disconnect-- client, error = await get_relay_client(url, api_key)- if client:- return {- "success": True,- "connected": True,- "session_token": client.session_token,- "qr_data": client.qr_data,- "message": "Reconnected with new session token",- }+ await close_relay_client()+ await asyncio.sleep(0.5) # ensure clean disconnect++ client, error = await get_relay_client(url, api_key)+ if client:return {- "success": False,- "connected": False,- "error": error or "Failed to reconnect to relay server",+ "success": True,+ "connected": True,+ "session_token": client.session_token,+ "qr_data": client.qr_data,+ "message": "Reconnected with new session token",}- except Exception as e:- logger.error(f"[WebSocket] Android relay reconnect error: {e}")- return {"success": False, "error": str(e)}+ return {+ "success": False,+ "connected": False,+ "error": error or "Failed to reconnect to relay server",+ }WS_HANDLERS = {diff --git a/server/nodes/telegram/_handlers.py b/server/nodes/telegram/_handlers.pyindex 66622253..a0155edd 100644--- a/server/nodes/telegram/_handlers.py+++ b/server/nodes/telegram/_handlers.py@@ -19,6 +19,8 @@ from typing import Any, Awaitable, Callable, Dictfrom fastapi import WebSocket+from services.plugin.ws import ws_response+from ._credentials import TelegramCredentialfrom ._service import get_telegram_service@@ -112,8 +114,15 @@ async def handle_telegram_status(data: Dict[str, Any], websocket: WebSocket) ->return {"success": True, "status": status}+@ws_responseasync def handle_telegram_send(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:- """Direct send via WebSocket (not via workflow node)."""+ """Direct send via WebSocket (not via workflow node).++ ``@ws_response`` collapses the catch-all ``try / except Exception``+ block at the bottom of the function -- exceptions become+ ``{success: False, error: str(e)}`` automatically. Early-return+ validation stays since those are deterministic input checks.+ """service = get_telegram_service()if not service.connected:return {"success": False, "error": "Telegram bot not connected"}@@ -125,15 +134,11 @@ async def handle_telegram_send(data: Dict[str, Any], websocket: WebSocket) -> Diif dispatch is None:return {"success": False, "error": f"Unsupported message type: {message_type}"}- try:- coro_or_none, err = dispatch(service, data, data.get("parse_mode"))- if err:- return {"success": False, "error": err}- result = await coro_or_none- return {"success": True, "result": result}- except Exception as e:- logger.error(f"[Telegram] Send error: {e}")- return {"success": False, "error": str(e)}+ coro_or_none, err = dispatch(service, data, data.get("parse_mode"))+ if err:+ return {"success": False, "error": err}+ result = await coro_or_none+ return {"success": True, "result": result}async def handle_telegram_reconnect(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:@@ -155,26 +160,22 @@ async def handle_telegram_reconnect(data: Dict[str, Any], websocket: WebSocket)return await get_telegram_service().connect(secrets["api_key"])+@ws_responseasync def handle_telegram_get_me(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:service = get_telegram_service()if not service.connected:return {"success": False, "error": "Telegram bot not connected"}- try:- return {"success": True, "result": await service.get_me()}- except Exception as e:- return {"success": False, "error": str(e)}+ return {"success": True, "result": await service.get_me()}+@ws_responseasync def handle_telegram_get_chat(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:service = get_telegram_service()if not service.connected:return {"success": False, "error": "Telegram bot not connected"}if not data.get("chat_id"):return {"success": False, "error": "chat_id required"}- try:- return {"success": True, "result": await service.get_chat(data["chat_id"])}- except Exception as e:- return {"success": False, "error": str(e)}+ return {"success": True, "result": await service.get_chat(data["chat_id"])}# ---------------------------------------------------------------------------diff --git a/server/services/plugin/deps.py b/server/services/plugin/deps.pynew file mode 100644index 00000000..01565195--- /dev/null+++ b/server/services/plugin/deps.py@@ -0,0 +1,68 @@+"""Lazy dependency-injection helpers (Wave 11.I, milestone T-residual).++Plugin packages need lazy imports of singletons from+:mod:`core.container` to avoid the+``nodes/<plugin>/__init__ -> core.container -> nodes.android._dispatcher+-> nodes.android.__init__ -> _router`` import cycle that bites at+package load time. Pre-T-residual the codebase had 53 inline+``from core.container import container`` statements scattered across+plugin handlers + services. These helpers consolidate the pattern+into one place.++**Important: NOT memoised.** Both helpers re-resolve the singleton on+every call. Test fixtures swap the auth-service / database instances+mid-test via the dependency-injection container's ``override``+mechanism; a memoised cache would lock in the originally-resolved+instance and the override would be silently ignored. The lookup is+a dict access -- caching adds nothing measurable.++Usage::++ from services.plugin.deps import get_auth_service++ async def handle_thing(data, websocket):+ auth_service = get_auth_service()+ client_id = await auth_service.get_api_key("twitter_client_id")+ ...+"""++from __future__ import annotations++from typing import TYPE_CHECKING++if TYPE_CHECKING:+ from core.cache import CacheService+ from core.database import Database+ from services.auth import AuthService+++def get_auth_service() -> "AuthService":+ """Resolve the singleton :class:`services.auth.AuthService`.++ Lazy import + call-time lookup. Test monkeypatching depends on+ the container override being read at call time, not at module+ import time -- do NOT memoise.+ """+ from core.container import container++ return container.auth_service()+++def get_database() -> "Database":+ """Resolve the singleton :class:`core.database.Database`.++ Same NOT-memoised contract as :func:`get_auth_service`.+ """+ from core.container import container++ return container.database()+++def get_cache() -> "CacheService":+ """Resolve the singleton :class:`core.cache.CacheService`."""+ from core.container import container++ return container.cache()+++__all__ = ["get_auth_service", "get_database", "get_cache"]diff --git a/server/services/plugin/ws.py b/server/services/plugin/ws.pynew file mode 100644index 00000000..8658a6dd--- /dev/null+++ b/server/services/plugin/ws.py@@ -0,0 +1,81 @@+"""WebSocket handler helpers (Wave 11.I, milestone T-residual).++Single helper today: :func:`ws_response`, an opt-in decorator that+collapses the duplicated ``try / except / return {success: False,+error: str(e)}`` block at the bottom of every plugin WS handler.++Audited 79 instances of this exact pattern across ``nodes/<plugin>/``+in the pre-T-residual codebase. The decorator is **opt-in** because+not every handler returns the ``{success: bool}`` envelope -- OAuth+lifecycle handlers built by+:mod:`services.events.oauth_lifecycle` return ``{connected: bool}``,+auto-wrapping would clobber that. Plugin authors decorate per-handler.++Honors the :class:`services.plugin.base.NodeUserError` contract: when+a handler raises ``NodeUserError`` (user-correctable failure -- bad+input, unknown enum value, missing required field), the wrapper logs+at WARN without a traceback. Genuinely unexpected exceptions log at+ERROR with full traceback via ``logger.exception``.+"""++from __future__ import annotations++from functools import wraps+from typing import Any, Awaitable, Callable, Dict++from fastapi import WebSocket++from core.logging import get_logger+from services.plugin.base import NodeUserError++logger = get_logger(__name__)++WSHandlerFn = Callable[[Dict[str, Any], WebSocket], Awaitable[Dict[str, Any]]]+++def ws_response(handler: WSHandlerFn) -> WSHandlerFn:+ """Wrap a WS handler to convert exceptions into a ``{success: False,+ error: ...}`` envelope.++ Successful return values pass through untouched -- the wrapper+ only intervenes on exceptions. Extra fields the handler adds to+ the success envelope (``connected``, ``message``, ``result``, ...)+ are preserved.++ Two log levels:++ * :class:`NodeUserError` -> WARN, no traceback. Reason: these are+ expected and user-correctable; a stack trace just clutters the+ operator log without adding signal.+ * Anything else -> ERROR via ``logger.exception`` (full traceback).+ Reason: it's a server bug, the trace is the diagnostic.++ Usage::++ from services.plugin.ws import ws_response++ @ws_response+ async def handle_thing(data, websocket):+ ...+ return {"success": True, "result": ...}+ """++ handler_name = getattr(handler, "__name__", repr(handler))++ @wraps(handler)+ async def wrapper(+ data: Dict[str, Any], websocket: WebSocket,+ ) -> Dict[str, Any]:+ try:+ return await handler(data, websocket)+ except NodeUserError as exc:+ logger.warning(f"[{handler_name}] {type(exc).__name__}: {exc}")+ return {"success": False, "error": str(exc)}+ except Exception as exc: # noqa: BLE001 -- surface as envelope+ logger.exception(f"[{handler_name}] unexpected error")+ return {"success": False, "error": str(exc)}++ return wrapper+++__all__ = ["ws_response"]diff --git a/server/tests/test_plugin_helpers.py b/server/tests/test_plugin_helpers.pynew file mode 100644index 00000000..6b44dca6--- /dev/null+++ b/server/tests/test_plugin_helpers.py@@ -0,0 +1,116 @@+"""Unit tests for :mod:`services.plugin.ws` + :mod:`services.plugin.deps`.++Locks the contract for the two T-residual helpers added in Wave 11.I:++* :func:`services.plugin.ws.ws_response` -- exception-to-envelope wrapper+ with ``NodeUserError`` carve-out.+* :func:`services.plugin.deps.get_auth_service` /+ ``get_database`` / ``get_cache`` -- NOT memoised; re-resolve on+ every call so test container overrides take effect.+"""++from __future__ import annotations++from unittest.mock import MagicMock, patch++import pytest++from services.plugin.base import NodeUserError+from services.plugin.deps import get_auth_service, get_cache, get_database+from services.plugin.ws import ws_response+++# ----------------------------------------------------------------------------+# ws_response+# ----------------------------------------------------------------------------+++class TestWsResponse:+ """``@ws_response`` -- opt-in exception-to-envelope decorator."""++ async def test_success_path_passes_through_unchanged(self):+ @ws_response+ async def handler(data, websocket):+ return {"success": True, "result": "ok", "extra": 42}++ out = await handler({}, MagicMock())+ assert out == {"success": True, "result": "ok", "extra": 42}++ async def test_unexpected_exception_returns_error_envelope(self):+ @ws_response+ async def handler(data, websocket):+ raise RuntimeError("server bug")++ out = await handler({}, MagicMock())+ assert out == {"success": False, "error": "server bug"}++ async def test_node_user_error_returns_error_envelope(self):+ @ws_response+ async def handler(data, websocket):+ raise NodeUserError("missing required field")++ out = await handler({}, MagicMock())+ assert out == {"success": False, "error": "missing required field"}++ async def test_decorator_preserves_handler_metadata(self):+ @ws_response+ async def documented_handler(data, websocket):+ """Original docstring."""+ return {"success": True}++ assert documented_handler.__name__ == "documented_handler"+ assert documented_handler.__doc__ == "Original docstring."+++# ----------------------------------------------------------------------------+# deps -- get_auth_service / get_database / get_cache+# ----------------------------------------------------------------------------+++class TestLazyDependencyHelpers:+ """The lazy DI helpers MUST NOT memoise -- test fixtures rely on+ call-time container resolution to swap singletons mid-test."""++ def test_get_auth_service_returns_container_singleton(self):+ fake_auth = MagicMock(name="auth_service_singleton")+ with patch("core.container.container") as fake_container:+ fake_container.auth_service.return_value = fake_auth+ assert get_auth_service() is fake_auth++ def test_get_database_returns_container_singleton(self):+ fake_db = MagicMock(name="database_singleton")+ with patch("core.container.container") as fake_container:+ fake_container.database.return_value = fake_db+ assert get_database() is fake_db++ def test_get_cache_returns_container_singleton(self):+ fake_cache = MagicMock(name="cache_singleton")+ with patch("core.container.container") as fake_container:+ fake_container.cache.return_value = fake_cache+ assert get_cache() is fake_cache++ def test_get_auth_service_is_not_memoised(self):+ """Two consecutive calls must each re-query the container.++ Test monkeypatching swaps the container's auth-service mid-test.+ A memoised cache would lock in the first instance and the swap+ would be silently ignored.+ """+ first = MagicMock(name="first_auth_service")+ second = MagicMock(name="second_auth_service")+ with patch("core.container.container") as fake_container:+ fake_container.auth_service.side_effect = [first, second]+ assert get_auth_service() is first+ assert get_auth_service() is second+ # Verify the container was queried twice -- not a single cached+ # lookup (which would mean side_effect's second value is unused).+ assert fake_container.auth_service.call_count == 2++ def test_get_database_is_not_memoised(self):+ first = MagicMock(name="first_db")+ second = MagicMock(name="second_db")+ with patch("core.container.container") as fake_container:+ fake_container.database.side_effect = [first, second]+ assert get_database() is first+ assert get_database() is second+ assert fake_container.database.call_count == 2