Skip to content

Self-improving AI Employees for everyone

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__.py
index 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_refresh
from services.ws_handler_registry import register_ws_handlers
from ._credentials import TelegramCredential
+from ._events import ( # noqa: F401 — re-exported for callers
+ broadcast_telegram_status,
+ dispatch_telegram_message_received,
+)
from ._filters import build_telegram_filter
from ._handlers import WS_HANDLERS
from ._refresh import precheck_telegram_trigger, refresh_telegram_status
diff --git a/server/nodes/telegram/_events.py b/server/nodes/telegram/_events.py
new file mode 100644
index 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.py
index 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 emitted
so cold-start ``getMe`` time is observable -- the historical
bottleneck 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_status
from ._service import get_telegram_service
service = 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.py
index 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.py
index 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 Updates
diff --git a/server/tests/test_status_broadcasts.py b/server/tests/test_status_broadcasts.py
index 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."
)