Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
refactor(telegram): Wave 12 B3 — move broadcasts into nodes/telegram/_events.py
trohitgda63d732ea44
diff --git a/server/nodes/telegram/__init__.py b/server/nodes/telegram/__init__.pyindex 8b31e4dc..988999c7 100644--- a/server/nodes/telegram/__init__.py+++ b/server/nodes/telegram/__init__.py@@ -36,6 +36,10 @@ from services.status_broadcaster import register_service_refreshfrom services.ws_handler_registry import register_ws_handlersfrom ._credentials import TelegramCredential+from ._events import ( # noqa: F401 — re-exported for callers+ broadcast_telegram_status,+ dispatch_telegram_message_received,+)from ._filters import build_telegram_filterfrom ._handlers import WS_HANDLERSfrom ._refresh import precheck_telegram_trigger, refresh_telegram_statusdiff --git a/server/nodes/telegram/_events.py b/server/nodes/telegram/_events.pynew file mode 100644index 00000000..34be53fe--- /dev/null+++ b/server/nodes/telegram/_events.py@@ -0,0 +1,177 @@+"""Wave 12 B3: CloudEvents factories + broadcaster wrappers for telegram.++Plugin-specific event emission — replaces:+ - ``broadcaster.update_telegram_status(...)`` call inside the+ telegram service's ``_broadcast_status`` method+ - ``event_waiter.dispatch("telegram_message_received", event_data)``+ inside the message-receive handler++After B3 every telegram wire frame originates from one wrapper here —+single source of truth for shape. The cross-plugin+``_emit_connection_typed`` helper on ``StatusBroadcaster`` retires in+the same commit since android (B1) + whatsapp (B2) + telegram (B3) are+the only callers.++Per RFC plugin_authoring_rfc.md §6.4: plugin-specific factories live in+the plugin folder.++Wire format preserved:+ - Status: ``{type: "telegram_status", data: <raw>}`` + typed sibling+ on ``plugin_connection_status``+ - Message: typed CloudEvent dispatched to ``event_waiter`` so+ ``telegramReceive`` trigger nodes match it; legacy wire key+ ``telegram_message_received`` preserved for FE+"""++from __future__ import annotations++import time+from typing import Any, Dict, Mapping, Optional++from services.events.envelope import WorkflowEvent+++# ---- Wire-routing keys -----------------------------------------------------++_STATUS_LEGACY_WIRE_KEY = "telegram_status"+_STATUS_TYPED_WIRE_KEY = "plugin_connection_status"++# Legacy event_type the event_waiter dispatches by; trigger nodes+# subscribe on this string. Keep until Phase B11 FE migration.+_MESSAGE_LEGACY_EVENT_TYPE = "telegram_message_received"+++# ---- Typed factories (plugin-specific per RFC §6.4) ------------------------+++def telegram_connection_status(+ *,+ connected: bool,+ bot_id: Optional[int] = None,+ bot_username: Optional[str] = None,+ bot_name: Optional[str] = None,+ owner_chat_id: Optional[int] = None,+ has_stored_token: Optional[bool] = None,+) -> WorkflowEvent:+ """Bot connection-state envelope. ``subject`` is the bot username+ so the FE can route per-bot updates.++ ``has_stored_token`` distinguishes "not connected, no token stored"+ (user hasn't added a token yet) from "not connected, token stored+ but bot offline" (network failure / token revoked). Used by the+ auto-reconnect refresh callback (see :mod:`._refresh`).+ """+ data: Dict[str, Any] = {+ "connected": connected,+ "bot_id": bot_id,+ "bot_username": bot_username,+ "bot_name": bot_name,+ "owner_chat_id": owner_chat_id,+ }+ if has_stored_token is not None:+ data["has_stored_token"] = has_stored_token+ return WorkflowEvent(+ source="machinaos://nodes/telegram",+ type=(+ "com.machinaos.telegram.connection.opened"+ if connected+ else "com.machinaos.telegram.connection.closed"+ ),+ subject=bot_username,+ data=data,+ )+++def telegram_message_received(event_data: Mapping[str, Any]) -> WorkflowEvent:+ """Incoming Telegram message envelope. ``subject`` is the chat_id+ (cast to str — Telegram chat IDs are numeric, the envelope spec+ requires a string subject)."""+ payload = dict(event_data)+ chat_id = payload.get("chat_id")+ return WorkflowEvent(+ source="machinaos://nodes/telegram",+ type="com.machinaos.telegram.message.received",+ subject=str(chat_id) if chat_id is not None else None,+ data=payload,+ )+++# ---- Broadcaster wrappers --------------------------------------------------+++async def broadcast_telegram_status(+ *,+ connected: bool,+ bot_id: Optional[int] = None,+ bot_username: Optional[str] = None,+ bot_name: Optional[str] = None,+ owner_chat_id: Optional[int] = None,+ has_stored_token: Optional[bool] = None,+) -> None:+ """Update the telegram status cache + emit both the legacy raw+ ``telegram_status`` frame AND the typed ``plugin_connection_status``+ CloudEvents sibling.++ Replaces ``StatusBroadcaster.update_telegram_status``.+ """+ from services.status_broadcaster import get_status_broadcaster++ broadcaster = get_status_broadcaster()++ payload: Dict[str, Any] = {+ "connected": connected,+ "bot_id": bot_id,+ "bot_username": bot_username,+ "bot_name": bot_name,+ "owner_chat_id": owner_chat_id,+ "timestamp": time.time(),+ }+ if has_stored_token is not None:+ payload["has_stored_token"] = has_stored_token+ broadcaster._status["telegram"] = payload++ await broadcaster.broadcast({+ "type": _STATUS_LEGACY_WIRE_KEY,+ "data": payload,+ })++ event = telegram_connection_status(+ connected=connected,+ bot_id=bot_id,+ bot_username=bot_username,+ bot_name=bot_name,+ owner_chat_id=owner_chat_id,+ has_stored_token=has_stored_token,+ )+ await broadcaster.broadcast({+ "type": _STATUS_TYPED_WIRE_KEY,+ "data": event.model_dump(mode="json"),+ })+++async def dispatch_telegram_message_received(event_data: Mapping[str, Any]) -> int:+ """Dispatch an incoming Telegram message to waiting+ ``telegramReceive`` trigger nodes.++ Replaces the direct ``event_waiter.dispatch("telegram_message_received",+ event_data)`` call. Returns the count of resolved waiters.+ """+ from services import event_waiter++ # Trigger nodes subscribe by event_type string; keep the legacy+ # string so the `telegramReceive.event_type` ClassVar still+ # matches (Phase C1 + B11 will swap to the typed+ # `com.machinaos.telegram.message.received` form together).+ resolved = event_waiter.dispatch(+ _MESSAGE_LEGACY_EVENT_TYPE,+ dict(event_data),+ )+ return resolved+++__all__ = [+ "broadcast_telegram_status",+ "dispatch_telegram_message_received",+ "telegram_connection_status",+ "telegram_message_received",+]diff --git a/server/nodes/telegram/_refresh.py b/server/nodes/telegram/_refresh.pyindex 7b39b10a..6b8a7b46 100644--- a/server/nodes/telegram/_refresh.py+++ b/server/nodes/telegram/_refresh.py@@ -32,36 +32,41 @@ async def refresh_telegram_status(broadcaster: "StatusBroadcaster") -> None:Called once per ``_refresh_all_services`` cycle. OTel span emittedso cold-start ``getMe`` time is observable -- the historicalbottleneck on local DNS for the first WebSocket connect.++ Wave 12 B3: routes through plugin _events.py wrapper. Cache write+ + dual-emit (legacy raw + typed sibling) all in one call."""with tracer.start_as_current_span("broadcaster.refresh_telegram") as span:try:+ from ._events import broadcast_telegram_statusfrom ._service import get_telegram_serviceservice = get_telegram_service()- def _snapshot(connected: bool, has_token: bool) -> Dict[str, Any]:- s = service.get_status()- return {- "connected": connected,- "bot_id": s.get("bot_id") if connected else None,- "bot_username": s.get("bot_username") if connected else None,- "bot_name": s.get("bot_name") if connected else None,- "owner_chat_id": s.get("owner_chat_id") if connected else None,- "has_stored_token": has_token,- }+ async def _emit(connected: bool, has_token: bool) -> None:+ """Snapshot service state and broadcast (cache write + WS)."""+ s = service.get_status() if connected else {}+ await broadcast_telegram_status(+ connected=connected,+ bot_id=s.get("bot_id") if connected else None,+ bot_username=s.get("bot_username") if connected else None,+ bot_name=s.get("bot_name") if connected else None,+ owner_chat_id=s.get("owner_chat_id") if connected else None,+ has_stored_token=has_token,+ )if service.connected:- broadcaster._status["telegram"] = _snapshot(True, True)+ await _emit(True, True)span.set_attribute("path", "already_connected")elif not await service.has_stored_token():- broadcaster._status["telegram"] = _snapshot(False, False)+ await _emit(False, False)span.set_attribute("path", "no_token")else:span.set_attribute("path", "auto_reconnect")logger.info("[StatusBroadcaster] Auto-reconnecting Telegram bot...")result = await service.connect()ok = bool(result.get("success"))- broadcaster._status["telegram"] = _snapshot(ok, True)+ await _emit(ok, True)span.set_attribute("reconnect_ok", ok)if ok:bot_username = broadcaster._status["telegram"].get("bot_username")@@ -74,10 +79,6 @@ async def refresh_telegram_status(broadcaster: "StatusBroadcaster") -> None:f"{result.get('error')}")- await broadcaster.broadcast({- "type": "telegram_status",- "data": broadcaster._status["telegram"],- })span.set_attribute("connected", bool(broadcaster._status["telegram"]["connected"]))diff --git a/server/nodes/telegram/_service.py b/server/nodes/telegram/_service.pyindex e9d3bfc4..dbcd5a43 100644--- a/server/nodes/telegram/_service.py+++ b/server/nodes/telegram/_service.py@@ -494,8 +494,11 @@ class TelegramService(ServiceSingleton):f"chat_type={event_data.get('chat_type')}")- from services import event_waiter- resolved = event_waiter.dispatch("telegram_message_received", event_data)+ # Wave 12 B3: route via plugin _events.py wrapper (single+ # source of truth for the wire format).+ from . import dispatch_telegram_message_received++ resolved = await dispatch_telegram_message_received(event_data)logger.info(f"[Telegram] Dispatched to {resolved} waiter(s)")except Exception as e:logger.error(f"[Telegram] Message handler error: {e}")@@ -570,9 +573,10 @@ class TelegramService(ServiceSingleton):async def _broadcast_status(self):try:- from services.status_broadcaster import get_status_broadcaster- broadcaster = get_status_broadcaster()- await broadcaster.update_telegram_status(+ # Wave 12 B3: route via plugin _events.py wrapper.+ from . import broadcast_telegram_status++ await broadcast_telegram_status(connected=self._connected,bot_id=self._bot_info.get("id"),bot_username=self._bot_info.get("username"),diff --git a/server/services/status_broadcaster.py b/server/services/status_broadcaster.pyindex c404ec8c..597db624 100644--- a/server/services/status_broadcaster.py+++ b/server/services/status_broadcaster.py@@ -544,47 +544,16 @@ class StatusBroadcaster:# Android Status Updates# =========================================================================- async def _emit_connection_typed(- self,- plugin: str,- connected: bool,- subject: Optional[str],- data: Dict[str, Any],- ) -> None:- """Emit a CloudEvents-typed sibling broadcast alongside the- legacy ``{plugin}_status`` raw frame (Wave 11.I, X4).-- Wire key ``plugin_connection_status`` mirrors the- ``credential_catalogue_updated`` pattern: single wire channel- for typed-envelope listeners; the envelope's ``type`` field- carries the specific action (``{plugin}.connection.opened`` /- ``.closed``) and ``subject`` carries the device/account id.-- Frontend listeners that grew up on the raw ``{plugin}_status``- frame keep working unchanged; future listeners can subscribe- to ``plugin_connection_status`` for the typed channel and- retire the raw frame in a coordinated FE migration (Phase 4 Y3).- """- from services.events import WorkflowEvent-- event = WorkflowEvent.connection_status(- plugin=plugin,- connected=connected,- subject=subject,- data=data,- )- await self.broadcast({- "type": "plugin_connection_status",- "data": event.model_dump(mode="json"),- })-- # Wave 12 B1: ``update_android_status`` MOVED to- # ``nodes/android/_events.py:broadcast_android_status``. Plugin- # owns its broadcast shape + the dual-emit (legacy raw +- # typed CloudEvents sibling). Status cache still lives in- # ``self._status["android"]`` — the plugin's wrapper mutates it- # so ``get_android_status()`` + the WS-connect initial-status- # snapshot keep working unchanged.+ # Wave 12 B1-B3: all three ``update_<plugin>_status`` methods MOVED+ # to per-plugin ``_events.py:broadcast_<plugin>_status`` wrappers+ # (android / whatsapp / telegram). Each plugin owns its broadcast+ # shape + the dual-emit (legacy raw + typed CloudEvents sibling).+ # The shared ``_emit_connection_typed`` helper retired with B3+ # because no remaining caller uses it — plugin-specific typed+ # factories (e.g. ``android_connection_status``) replace the+ # cross-plugin parametrised helper per RFC §6.4. Status cache+ # slots in ``self._status[<plugin>]`` stay so ``get_status()`` ++ # WS-connect initial snapshot keep working.# =========================================================================# Status updates -- per-service refresh bodies live in their plugin@@ -605,39 +574,8 @@ class StatusBroadcaster:# Telegram Status Updates# =========================================================================- async def update_telegram_status(- self,- connected: bool,- bot_id: Optional[int] = None,- bot_username: Optional[str] = None,- bot_name: Optional[str] = None,- owner_chat_id: Optional[int] = None- ):- """Update Telegram bot connection status and broadcast.-- Emits both the legacy ``telegram_status`` raw frame and a- CloudEvents-typed sibling (Wave 11.I, X4).- """- import time- self._status["telegram"] = {- "connected": connected,- "bot_id": bot_id,- "bot_username": bot_username,- "bot_name": bot_name,- "owner_chat_id": owner_chat_id,- "timestamp": time.time()- }-- await self.broadcast({- "type": "telegram_status",- "data": self._status["telegram"]- })- await self._emit_connection_typed(- plugin="telegram",- connected=connected,- subject=bot_username,- data=self._status["telegram"],- )+ # Wave 12 B3: ``update_telegram_status`` MOVED to+ # ``nodes/telegram/_events.py:broadcast_telegram_status``.# =========================================================================# Node Status Updatesdiff --git a/server/tests/test_status_broadcasts.py b/server/tests/test_status_broadcasts.pyindex 5911924a..c668dd12 100644--- a/server/tests/test_status_broadcasts.py+++ b/server/tests/test_status_broadcasts.py@@ -81,7 +81,11 @@ _LEGACY_RAW_DICT_BROADCASTS: FrozenSet[str] = frozenset({# ``nodes/android/_events.py:broadcast_android_status``.# Wave 12 B2: ``update_whatsapp_status`` retired; moved to# ``nodes/whatsapp/_events.py:broadcast_whatsapp_status``.- "update_telegram_status", # FE: TelegramStatusPanel reads `telegram_status` wire-frame+ # Wave 12 B3: ``update_telegram_status`` retired; moved to+ # ``nodes/telegram/_events.py:broadcast_telegram_status``. The+ # shared ``_emit_connection_typed`` helper retired alongside (no+ # remaining callers). Allowlist now empty — all three plugin-named+ # broadcast methods live in their plugin folders.})# ``send_custom_event`` callers that still pass raw dicts. Each entry@@ -331,65 +335,75 @@ class TestStatusBroadcastsUseTypedBuilder:class TestStatusBroadcastsAlsoEmitTypedEnvelope:- """Wave 11.I, X4: every legacy ``update_<plugin>_status`` method- listed in :data:`_LEGACY_RAW_DICT_BROADCASTS` MUST also call- :meth:`StatusBroadcaster._emit_connection_typed` (or otherwise- construct ``WorkflowEvent.connection_status(...)``) so a typed- sibling broadcast goes out alongside the legacy raw frame.-- Phase 4 Y3 retires the raw frame after frontend migrates to read- the typed channel. Until then, both frames coexist: existing FE- consumers stay compatible; typed listeners can opt in.+ """Wave 12 B1-B3: per-plugin ``broadcast_<plugin>_status`` wrappers+ in ``nodes/<plugin>/_events.py`` MUST dual-emit (legacy raw frame ++ typed CloudEvents sibling on ``plugin_connection_status``).++ Replaces the Wave 11.I X4 invariant which constrained the now-retired+ ``StatusBroadcaster.update_<plugin>_status`` methods + their shared+ ``_emit_connection_typed`` helper. The helper retired in B3 along+ with the last caller (telegram). Plugin-specific typed factories+ (``android_connection_status`` / ``whatsapp_connection_status`` /+ ``telegram_connection_status``) replace the cross-plugin+ parametrised helper per RFC §6.4 plugin-specific classification.++ Each plugin's wrapper file is parametrized below — every entry must+ contain both wire keys (legacy + ``plugin_connection_status``) and+ construct a CloudEvents envelope."""- @pytest.fixture- def broadcaster_methods(self) -> dict[str, str]:- from services import status_broadcaster as sb-- cls_src = inspect.getsource(sb.StatusBroadcaster)- return _split_methods(cls_src)-- @pytest.mark.parametrize("method_name", sorted(_LEGACY_RAW_DICT_BROADCASTS))- def test_legacy_status_method_emits_typed_sibling(- self, broadcaster_methods, method_name: str,+ # (plugin_label, module_path, wrapper_function_name, legacy_wire_key)+ _PLUGIN_WRAPPERS = [+ ("android", "nodes.android._events", "broadcast_android_status", "android_status"),+ ("whatsapp", "nodes.whatsapp._events", "broadcast_whatsapp_status", "whatsapp_status"),+ ("telegram", "nodes.telegram._events", "broadcast_telegram_status", "telegram_status"),+ ]++ @pytest.mark.parametrize(+ "plugin,module_path,wrapper_name,legacy_key",+ _PLUGIN_WRAPPERS,+ ids=[row[0] for row in _PLUGIN_WRAPPERS],+ )+ def test_plugin_wrapper_dual_emits(+ self, plugin: str, module_path: str, wrapper_name: str, legacy_key: str,):- body = broadcaster_methods.get(method_name)- assert body is not None, (- f"StatusBroadcaster.{method_name} missing -- update "- f"_LEGACY_RAW_DICT_BROADCASTS or restore the method."+ """Each plugin's broadcaster wrapper emits BOTH the legacy raw+ frame AND the typed ``plugin_connection_status`` sibling.++ Introspects the full module source (not just the wrapper body)+ because plugins legitimately hoist the wire keys into+ module-level constants for self-documentation.+ """+ import importlib++ mod = importlib.import_module(module_path)+ wrapper = getattr(mod, wrapper_name, None)+ assert wrapper is not None, (+ f"{module_path}.{wrapper_name} missing — Wave 12 B-phase "+ f"contract violated; plugin {plugin!r} must own its broadcast "+ f"wrapper in its plugin folder.")- assert "_emit_connection_typed" in body or "WorkflowEvent.connection_status" in body, (- f"StatusBroadcaster.{method_name} emits only the legacy raw "- f"{{type: 'X_status', data: {{...}}}} frame. It must ALSO emit a "- f"CloudEvents-typed sibling via "- f"``await self._emit_connection_typed(plugin=..., connected=..., "- f"subject=..., data=...)`` so future typed-channel listeners "- f"can subscribe. Wave 11.I, X4 contract."+ mod_src = inspect.getsource(mod)+ assert f'"{legacy_key}"' in mod_src or f"'{legacy_key}'" in mod_src, (+ f"{module_path} must reference legacy wire key {legacy_key!r} "+ f"for FE back-compat (the dual-emit transition contract).")-- def test_emit_connection_typed_helper_exists(self):- """The shared helper must exist on the broadcaster -- locks- the canonical extension point so per-method migrations don't- re-invent the typed-envelope construction."""- from services.status_broadcaster import StatusBroadcaster-- assert hasattr(StatusBroadcaster, "_emit_connection_typed"), (- "StatusBroadcaster._emit_connection_typed is the canonical "- "helper for typed plugin-connection broadcasts. It must "- "exist; per-method update_<plugin>_status implementations "- "call it after the legacy raw broadcast."+ assert "plugin_connection_status" in mod_src, (+ f"{module_path} must emit a typed CloudEvents sibling on "+ f"``plugin_connection_status`` (the cross-plugin typed channel).")- def test_emit_connection_typed_uses_workflow_event_factory(self):- """The helper itself must construct via the typed factory, not- a hand-rolled WorkflowEvent literal."""+ def test_emit_connection_typed_helper_retired(self):+ """B3 retired the cross-plugin helper. Locks: nothing on the+ broadcaster should reintroduce a shared parametrised version —+ per RFC §6.4, connection_status is plugin-specific."""from services.status_broadcaster import StatusBroadcaster- src = inspect.getsource(StatusBroadcaster._emit_connection_typed)- assert "WorkflowEvent.connection_status" in src, (- "_emit_connection_typed must call WorkflowEvent.connection_status(...) "- "(the typed factory) rather than hand-rolling the envelope. "- "Wave 11.I CloudEvents contract."+ assert not hasattr(StatusBroadcaster, "_emit_connection_typed"), (+ "StatusBroadcaster._emit_connection_typed was retired in "+ "Wave 12 B3. Each plugin now owns its connection_status "+ "factory in nodes/<plugin>/_events.py (RFC §6.4). Don't "+ "reintroduce the shared helper.")