machinaos 0.0.76 → 0.0.78

package/server/services/deployment/manager.py

@@ -13,7 +13,7 @@ from datetime import datetime
 from typing import Dict, Any, List, Optional, Callable, TYPE_CHECKING
 
 from core.logging import get_logger
-from constants import WORKFLOW_TRIGGER_TYPES, POLLING_TRIGGER_TYPES
+from constants import POLLING_TRIGGER_TYPES, TOOLKIT_NODE_TYPES, WORKFLOW_TRIGGER_TYPES
 from services import event_waiter
 from .state import DeploymentState, TriggerInfo
 from .triggers import TriggerManager
@@ -418,17 +418,25 @@ class DeploymentManager:
         if not trigger_manager:
             raise RuntimeError(f"No trigger manager for workflow {workflow_id}")
 
-        # Polling triggers need active API polling instead of event_waiter
+        # Polling triggers need active API polling instead of event_waiter.
+        # Plugins register a factory via
+        # ``services.plugin.PollingTriggerNode.__init_subclass__`` →
+        # ``services.deployment.poll_registry.register_poll_coroutine_factory``.
         if node_type in POLLING_TRIGGER_TYPES:
-            poll_coroutine = self._create_poll_coroutine(node_type, node_id, params)
-            if poll_coroutine:
+            from services.deployment.poll_registry import (
+                get_poll_coroutine_factory,
+            )
+
+            factory = get_poll_coroutine_factory(node_type)
+            if factory is not None:
+                poll_coroutine = factory(node_id, params)
                 await trigger_manager.setup_polling_trigger(
                     node_id, node_type, params, poll_coroutine, on_event,
                     self._broadcaster, workflow_id=workflow_id
                 )
                 return TriggerInfo(node_id, node_type)
-            # Fall through to event_waiter if no polling implementation available
-            logger.warning("No polling implementation for trigger", node_type=node_type)
+            # Fall through to event_waiter if no polling factory registered
+            logger.warning("No polling factory registered for trigger", node_type=node_type)
 
         await trigger_manager.setup_event_trigger(
             node_id, node_type, params, on_event, self._broadcaster,
@@ -641,10 +649,12 @@ class DeploymentManager:
                     continue
                 downstream_ids.add(source)
 
-        # Include sub-nodes connected to toolkit nodes (n8n Sub-Node pattern)
-        # Android service nodes connect to androidTool's input-main, not config handles
-        # These need to be included so the toolkit can discover its connected services
-        toolkit_node_ids = {n['id'] for n in nodes if n.get('type') == 'androidTool' and n['id'] in downstream_ids}
+        # Include sub-nodes connected to toolkit nodes (n8n Sub-Node pattern).
+        # Service nodes connect to a toolkit's input-main (not a config
+        # handle) and need to be included so the toolkit can discover
+        # them. ``TOOLKIT_NODE_TYPES`` is the canonical set; today only
+        # ``androidTool`` is in it.
+        toolkit_node_ids = {n['id'] for n in nodes if n.get('type') in TOOLKIT_NODE_TYPES and n['id'] in downstream_ids}
         for edge in edges:
             target = edge.get('target')
             source = edge.get('source')
@@ -677,141 +687,12 @@ class DeploymentManager:
     # POLLING TRIGGER FACTORIES
     # =========================================================================
 
-    def _create_poll_coroutine(self, node_type: str, node_id: str,
-                                params: Dict[str, Any]) -> Optional[Callable]:
-        """Create a polling coroutine for polling-based triggers.
-
-        Returns an async function(queue, is_running_fn) or None if not supported.
-        """
-        if node_type == 'gmailReceive':
-            return self._create_gmail_poll_coroutine(node_id, params)
-        elif node_type == 'emailReceive':
-            return self._create_email_poll_coroutine(node_id, params)
-        elif node_type == 'twitterReceive':
-            logger.warning("Twitter polling trigger not yet implemented for deployment")
-            return None
-        return None
-
-    def _create_gmail_poll_coroutine(self, node_id: str,
-                                      params: Dict[str, Any]) -> Callable:
-        """Create Gmail API polling coroutine for deployment mode.
-
-        Polls Gmail API at configured intervals for new emails matching the filter.
-        Establishes a baseline of existing emails to avoid triggering on old messages.
-        """
-        async def poll(queue: asyncio.Queue, is_running_fn: Callable):
-            from nodes.google._base import build_google_service
-            from nodes.google._gmail import (
-                poll_gmail_ids as _poll_gmail_ids,
-                fetch_email_details as _fetch_email_details,
-                mark_email_as_read as _mark_email_as_read,
-            )
-
-            # Authenticate with Gmail API
-            service = await build_google_service("gmail", "v1", params, {})
-
-            poll_interval = max(10, min(3600, params.get('poll_interval', 60)))
-            filter_query = params.get('filter_query', 'is:unread')
-            label_filter = params.get('label_filter', 'INBOX')
-            mark_as_read = params.get('mark_as_read', False)
-
-            # Build Gmail query
-            query = filter_query
-            if label_filter and label_filter != 'all':
-                query = f"label:{label_filter} {query}"
-
-            logger.info("Gmail poller starting",
-                       node_id=node_id, query=query,
-                       poll_interval=poll_interval)
-
-            # Establish baseline (avoid triggering on existing emails)
-            seen_ids: set = set()
-            try:
-                baseline = await _poll_gmail_ids(service, query)
-                seen_ids.update(baseline)
-                logger.info("Gmail poller baseline established",
-                           node_id=node_id, count=len(seen_ids))
-            except Exception as e:
-                logger.warning("Gmail poller baseline failed",
-                              node_id=node_id, error=str(e))
-
-            # Poll loop
-            poll_count = 0
-            while is_running_fn():
-                await asyncio.sleep(poll_interval)
-                if not is_running_fn():
-                    break
-
-                poll_count += 1
-                try:
-                    current_ids = await _poll_gmail_ids(service, query)
-                    new_ids = current_ids - seen_ids
-                    logger.debug("Gmail poll cycle",
-                                node_id=node_id, cycle=poll_count,
-                                current=len(current_ids),
-                                seen=len(seen_ids),
-                                new=len(new_ids))
-
-                    for msg_id in new_ids:
-                        seen_ids.add(msg_id)
-                        email_data = await _fetch_email_details(service, msg_id)
-
-                        if mark_as_read:
-                            try:
-                                await _mark_email_as_read(service, msg_id)
-                            except Exception:
-                                pass
-
-                        await queue.put(email_data)
-                        logger.info("Gmail poller: new email queued",
-                                   node_id=node_id,
-                                   subject=email_data.get('subject', ''))
-
-                except asyncio.CancelledError:
-                    break
-                except Exception as e:
-                    logger.error("Gmail poll error",
-                                node_id=node_id, error=str(e))
-
-        return poll
-
-    def _create_email_poll_coroutine(self, node_id: str,
-                                      params: Dict[str, Any]) -> Callable:
-        """Create Himalaya email polling coroutine for deployment mode."""
-        async def poll(queue: asyncio.Queue, is_running_fn: Callable):
-            from services.email_service import get_email_service
-
-            svc = get_email_service()
-            creds = await svc.resolve_credentials(params)
-            cfg = svc.resolve_poll_params(params)
-
-            seen = await svc.poll_ids(creds, cfg["folder"])
-            logger.info("Email poller starting",
-                       node_id=node_id, folder=cfg["folder"], seen=len(seen))
-
-            while is_running_fn():
-                await asyncio.sleep(cfg["interval"])
-                if not is_running_fn():
-                    break
-                try:
-                    for msg_id in await svc.poll_ids(creds, cfg["folder"]) - seen:
-                        seen.add(msg_id)
-                        email_data = await svc.fetch_detail(creds, msg_id, cfg["folder"])
-                        if cfg["mark_as_read"]:
-                            try:
-                                d = svc.defaults
-                                await svc.himalaya.flag_message(
-                                    creds, msg_id, d.get("flag"), d.get("flag_action"), cfg["folder"])
-                            except Exception:
-                                pass
-                        await queue.put(email_data)
-                except asyncio.CancelledError:
-                    break
-                except Exception as e:
-                    logger.error("Email poll error",
-                                node_id=node_id, error=str(e))
-
-        return poll
+    # _create_poll_coroutine + _create_gmail_poll_coroutine +
+    # _create_email_poll_coroutine REMOVED in Wave 11.I, milestone L.
+    # Polling-coroutine factories now self-register from each plugin's
+    # PollingTriggerNode subclass (services.plugin.PollingTriggerNode)
+    # via services.deployment.poll_registry.register_poll_coroutine_factory.
+    # The dispatch path lives ~140 lines up in _setup_event_trigger.
 
     async def _load_settings(self):
         """Load deployment settings from database."""

package/server/services/deployment/poll_registry.py

@@ -0,0 +1,59 @@
+"""Polling-coroutine factory registry (Wave 11.I, milestone L).
+
+Plugin packages register a factory that produces an async polling
+coroutine for a given trigger node type. ``DeploymentManager`` looks
+up the factory at deploy time and hands the produced coroutine to
+``TriggerManager.setup_polling_trigger`` -- the deployment manager no
+longer hardcodes per-plugin polling switches.
+
+Mirror of :func:`services.event_waiter.register_filter_builder`:
+same idempotency contract, same audience (plugin ``__init__.py``
+modules), built on the shared :class:`IdempotentRegistry`.
+
+Factory signature
+-----------------
+
+    factory(node_id: str, params: Dict[str, Any]) -> async (
+        queue: asyncio.Queue, is_running_fn: Callable[[], bool]
+    ) -> None
+
+The factory closes over node-specific config (auth, query, poll
+interval); the returned coroutine drains until ``is_running_fn()``
+returns False or the task is cancelled. New events go on ``queue``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Awaitable, Callable, Dict, Optional
+
+from services.plugin.registry import IdempotentRegistry
+
+
+# (queue, is_running) -> awaitable. The poll coroutine itself.
+PollCoroutine = Callable[[asyncio.Queue, Callable[[], bool]], Awaitable[None]]
+
+# (node_id, params) -> the bound poll coroutine.
+PollCoroutineFactory = Callable[[str, Dict[str, Any]], PollCoroutine]
+
+
+_REGISTRY: IdempotentRegistry[str, PollCoroutineFactory] = IdempotentRegistry(
+    "poll_coroutine_factory"
+)
+
+
+def register_poll_coroutine_factory(
+    node_type: str, factory: PollCoroutineFactory
+) -> None:
+    """Publish a polling-coroutine factory for a trigger node type.
+
+    Idempotent on re-import (same callable for the same key is a
+    no-op). A different callable for an existing key raises
+    ``ValueError`` to surface plugin namespace collisions early.
+    """
+    _REGISTRY.register(node_type, factory)
+
+
+def get_poll_coroutine_factory(node_type: str) -> Optional[PollCoroutineFactory]:
+    """Return the factory for ``node_type``, or ``None`` if unregistered."""
+    return _REGISTRY.get(node_type)

package/server/services/event_waiter.py

@@ -85,16 +85,12 @@ class TriggerConfig:
 # Registry of supported trigger types (event-based triggers only)
 # Note: cronScheduler is NOT an event-based trigger - it uses APScheduler directly
 TRIGGER_REGISTRY: Dict[str, TriggerConfig] = {
+    # Framework-level triggers — not owned by any plugin domain.
     'start': TriggerConfig(
         node_type='start',
         event_type='deploy_triggered',
         display_name='Deploy Start'
     ),
-    'whatsappReceive': TriggerConfig(
-        node_type='whatsappReceive',
-        event_type='whatsapp_message_received',
-        display_name='WhatsApp Message'
-    ),
     'webhookTrigger': TriggerConfig(
         node_type='webhookTrigger',
         event_type='webhook_received',
@@ -110,24 +106,14 @@ TRIGGER_REGISTRY: Dict[str, TriggerConfig] = {
         event_type='task_completed',
         display_name='Task Completed'
     ),
-    'twitterReceive': TriggerConfig(
-        node_type='twitterReceive',
-        event_type='twitter_event_received',
-        display_name='Twitter Event'
-    ),
-    'gmailReceive': TriggerConfig(
-        node_type='gmailReceive',
-        event_type='gmail_email_received',
-        display_name='Gmail Email'
-    ),
-    # 'telegramReceive' moved to nodes/telegram/ — backfilled here from
-    # the plugin's ``event_type`` class attribute via
-    # ``_auto_populate_from_plugins`` on first access.
-    'emailReceive': TriggerConfig(
-        node_type='emailReceive',
-        event_type='email_received',
-        display_name='Email'
-    ),
+    # Plugin-owned trigger entries (whatsappReceive, twitterReceive,
+    # telegramReceive, emailReceive, googleGmailReceive) live in their
+    # plugin folders' ``_filters.py`` and are backfilled here from each
+    # plugin's ``event_type`` ClassVar via
+    # ``_auto_populate_from_plugins`` (Wave 11.I, milestone K). Gmail's
+    # explicit alias entry was retired in milestone P after the
+    # downstream callers (POLLING_TRIGGER_TYPES, deployment manager,
+    # frontend trigger list) were renamed to the canonical class type.
     # Future triggers - just add to registry:
     # 'mqttTrigger': TriggerConfig('mqttTrigger', 'mqtt_message', 'MQTT Message'),
 }
@@ -213,126 +199,6 @@ def get_trigger_config(node_type: str) -> Optional[TriggerConfig]:
 # FILTER BUILDERS - One per trigger type
 # =============================================================================
 
-def build_whatsapp_filter(params: Dict) -> Callable[[Dict], bool]:
-    """Build filter function for WhatsApp messages.
-
-    Based on Go RPC handleIncomingMessage() event fields (service.go):
-    - message_id: string - unique message ID
-    - sender: string - Sender JID (may be LID for groups)
-    - sender_phone: string - RESOLVED phone number (LID already resolved by Go RPC!)
-    - chat_id: string - Chat JID (same as sender for DMs, group JID for groups)
-    - timestamp: time - message timestamp
-    - is_from_me: boolean - true if sent by connected account
-    - is_group: boolean - true if message is in a group chat
-    - message_type: string - text, image, video, audio, document, sticker, location, contact, contacts
-    - text: string - text content (for text messages)
-    - is_forwarded: boolean - true if message is forwarded
-    - forwarding_score: int - forwarding count
-    - group_info: object - present for group messages:
-      - group_jid: string
-      - sender_jid: string
-      - sender_phone: string - RESOLVED phone number
-      - sender_name: string - push name if available
-
-    Note: The Go RPC already resolves LIDs to phone numbers before sending the event.
-    The sender_phone field contains the resolved phone number - no manual LID resolution needed!
-    """
-    # Snake_case throughout — matches plugin Params (no camelCase aliases).
-    msg_type = params.get('message_type_filter', 'all')
-    sender_filter = params.get('filter', 'all')
-    contact_phone = params.get('phone_number', '')
-    group_id = params.get('group_id', '')
-    sender_number = params.get('sender_number', '')
-    keywords = [k.strip().lower() for k in params.get('keywords', '').split(',') if k.strip()]
-    ignore_own = params.get('ignore_own_messages', True)
-    forwarded_filter = params.get('forwarded_filter', 'all')
-
-    logger.debug(f"[WhatsAppFilter] Built: type={msg_type}, filter={sender_filter}, group_id='{group_id}', forwarded={forwarded_filter}")
-
-    def matches(m: Dict) -> bool:
-        msg_chat_id = m.get('chat_id', '')
-        is_group = m.get('is_group', False)
-        group_info = m.get('group_info', {})
-
-        # Use sender_phone directly - Go RPC already resolves LIDs to phone numbers!
-        # For group messages, prefer group_info.sender_phone, fall back to root sender_phone
-        if is_group:
-            sender_phone = group_info.get('sender_phone', '') or m.get('sender_phone', '')
-        else:
-            sender_phone = m.get('sender_phone', '')
-
-        # Fallback: extract phone from sender JID if sender_phone not available
-        if not sender_phone:
-            sender = m.get('sender', '')
-            sender_phone = sender.split('@')[0] if '@' in sender else sender
-
-        # Message type filter (schema field: message_type)
-        if msg_type != 'all' and m.get('message_type') != msg_type:
-            return False
-
-        # Sender filter - for contact filter, use actual phone number
-        if sender_filter == 'self':
-            # Only accept messages in self-chat (notes to self)
-            # Must be from me AND in a chat with myself (not replies to others)
-            if not m.get('is_from_me'):
-                return False
-            # Check chat_id matches sender (self-chat)
-            chat_id = m.get('chat_id', '')
-            sender = m.get('sender', '')
-            if chat_id != sender:
-                return False
-
-        if sender_filter == 'any_contact':
-            # Only accept non-group messages (individual/contact messages)
-            if is_group:
-                return False
-
-        if sender_filter == 'contact':
-            if contact_phone not in sender_phone:
-                return False
-
-        if sender_filter == 'group':
-            # For group filter, check if message is from that group
-            if not is_group:
-                return False
-            if msg_chat_id != group_id:
-                return False
-            # Optional: filter by specific sender within group using resolved phone number
-            if sender_number:
-                if sender_number not in sender_phone:
-                    return False
-
-        if sender_filter == 'channel':
-            # Only accept messages from newsletter channels (chat_id ends with @newsletter)
-            if not msg_chat_id.endswith('@newsletter'):
-                return False
-            # If specific channel JID provided, match exactly
-            channel_jid = params.get('channel_jid', '')
-            if channel_jid and msg_chat_id != channel_jid:
-                return False
-
-        if sender_filter == 'keywords':
-            text = (m.get('text') or '').lower()
-            if not any(kw in text for kw in keywords):
-                return False
-
-        # Ignore own messages (schema field: is_from_me) - but not when filtering for 'self'
-        if ignore_own and sender_filter != 'self' and m.get('is_from_me'):
-            return False
-
-        # Forwarded message filter (schema field: is_forwarded)
-        is_forwarded = m.get('is_forwarded', False)
-        if forwarded_filter == 'only_forwarded' and not is_forwarded:
-            return False
-        if forwarded_filter == 'ignore_forwarded' and is_forwarded:
-            return False
-
-        logger.debug(f"[WhatsAppFilter] Matched message from {sender_phone}")
-        return True
-
-    return matches
-
-
 def build_webhook_filter(params: Dict) -> Callable[[Dict], bool]:
     """Build filter function for webhook requests.
 
@@ -425,96 +291,29 @@ def build_task_completed_filter(params: Dict) -> Callable[[Dict], bool]:
     return matches
 
 
-def build_twitter_filter(params: Dict) -> Callable[[Dict], bool]:
-    """Build filter function for Twitter events.
-
-    Filters by:
-    - trigger_type: 'mentions', 'search', 'user_timeline'
-    - search_query: Search query for 'search' trigger type
-    - user_id: User ID for 'user_timeline' trigger type
-
-    Args:
-        params: Node parameters
-
-    Returns:
-        Filter function that checks if event matches criteria
-    """
-    trigger_type = params.get('trigger_type', 'mentions')
-    search_query = params.get('search_query', '')
-    user_id = params.get('user_id', '')
-
-    def matches(data: Dict) -> bool:
-        event_type = data.get('trigger_type', '')
-        if trigger_type != 'all' and event_type != trigger_type:
-            return False
-        if trigger_type == 'search' and search_query:
-            # Check if search query matches
-            event_query = data.get('query', '')
-            if search_query.lower() not in event_query.lower():
-                return False
-        if trigger_type == 'user_timeline' and user_id:
-            if data.get('user_id') != user_id:
-                return False
-        return True
-
-    return matches
-
-
-def build_gmail_filter(params: Dict) -> Callable[[Dict], bool]:
-    """Build filter function for Gmail email events.
-
-    Filters by label to ensure the event matches the trigger's label filter.
-    The filter_query is applied at the Gmail API level during polling,
-    so this filter only checks labels for events dispatched via event_waiter.
-
-    Args:
-        params: Node parameters with 'label_filter' field
-
-    Returns:
-        Filter function that checks if event labels match
-    """
-    label_filter = params.get('label_filter', 'INBOX')
-
-    def matches(data: Dict) -> bool:
-        if label_filter and label_filter != 'all':
-            labels = data.get('labels', [])
-            if label_filter not in labels:
-                return False
-        return True
-
-    return matches
-
-
-def build_email_filter(params: Dict) -> Callable[[Dict], bool]:
-    """Build filter for email events (Himalaya IMAP polling)."""
-    folder_filter = params.get('folder', 'INBOX')
-    filter_query = params.get('filter_query', '')
-
-    def matches(data: Dict) -> bool:
-        if folder_filter and folder_filter != 'all':
-            if data.get('folder', '') != folder_filter:
-                return False
-        return True
-
-    return matches
-
-
 # Registry of filter builders per trigger type. Plugin packages
 # (nodes/<group>/) call :func:`register_filter_builder` from their
 # package ``__init__.py`` to publish per-trigger filters without this
-# module needing to import them. The hardcoded entries below are core
-# triggers that don't yet live in their own plugin folder; once they
-# do, this dict shrinks to ``{}`` and everything is registry-driven.
+# module needing to import them. The hardcoded entries below are
+# **framework-level** triggers (webhook + chat + delegated-task) --
+# they don't belong to any one plugin domain and intentionally stay
+# here. The plugin entries (whatsappReceive, twitterReceive,
+# googleGmailReceive, emailReceive) live in their plugin folders'
+# ``_filters.py`` and self-register at import time.
 FILTER_BUILDERS: Dict[str, Callable[[Dict], Callable[[Dict], bool]]] = {
-    'whatsappReceive': build_whatsapp_filter,
     'webhookTrigger': build_webhook_filter,
     'chatTrigger': build_chat_filter,
     'taskTrigger': build_task_completed_filter,
-    'twitterReceive': build_twitter_filter,
-    'gmailReceive': build_gmail_filter,
-    'emailReceive': build_email_filter,
 }
 
+from services.plugin.registry import IdempotentRegistry as _IdempotentRegistry  # noqa: E402
+
+# Backed by the module-level FILTER_BUILDERS dict so existing readers
+# (e.g. build_filter, _ensure_populated, tests) keep working.
+_FILTER_REGISTRY: _IdempotentRegistry[str, Callable[[Dict], Callable[[Dict], bool]]] = (
+    _IdempotentRegistry("filter_builder", items=FILTER_BUILDERS)
+)
+
 
 def register_filter_builder(
     node_type: str,
@@ -526,13 +325,7 @@ def register_filter_builder(
     Used by plugin packages to keep all per-node-type knowledge inside
     the plugin folder instead of hardcoding it here.
     """
-    existing = FILTER_BUILDERS.get(node_type)
-    if existing is not None and existing is not builder:
-        raise ValueError(
-            f"Filter builder for '{node_type}' is already registered by "
-            f"{existing.__module__}.{existing.__qualname__}"
-        )
-    FILTER_BUILDERS[node_type] = builder
+    _FILTER_REGISTRY.register(node_type, builder)
 
 
 def build_filter(node_type: str, params: Dict) -> Callable[[Dict], bool]:
@@ -568,6 +361,9 @@ import inspect as _inspect
 
 _TriggerPrecheck = Callable[[Dict[str, Any]], Any]
 _TRIGGER_PRECHECKS: Dict[str, _TriggerPrecheck] = {}
+_TRIGGER_PRECHECK_REGISTRY: _IdempotentRegistry[str, _TriggerPrecheck] = (
+    _IdempotentRegistry("trigger_precheck", items=_TRIGGER_PRECHECKS)
+)
 
 
 def register_trigger_precheck(node_type: str, fn: _TriggerPrecheck) -> None:
@@ -576,13 +372,7 @@ def register_trigger_precheck(node_type: str, fn: _TriggerPrecheck) -> None:
     Idempotent on re-import. The callback may be sync or async; ``run_trigger_precheck``
     awaits the coroutine when needed.
     """
-    existing = _TRIGGER_PRECHECKS.get(node_type)
-    if existing is not None and existing is not fn:
-        raise ValueError(
-            f"Trigger precheck for '{node_type}' is already registered by "
-            f"{existing.__module__}.{existing.__qualname__}"
-        )
-    _TRIGGER_PRECHECKS[node_type] = fn
+    _TRIGGER_PRECHECK_REGISTRY.register(node_type, fn)
 
 
 async def run_trigger_precheck(node_type: str, parameters: Dict) -> Any:
@@ -826,43 +616,83 @@ def _cleanup_waiter(waiter_id: str) -> None:
 # EVENT DISPATCH
 # =============================================================================
 
-async def dispatch_async(event_type: str, data: Dict) -> int:
+def _unpack_event(
+    event: "Any",
+    data: Optional[Dict] = None,
+) -> tuple[str, Dict]:
+    """Normalise either ``(WorkflowEvent,)`` or ``(event_type, data)`` to
+    the underlying ``(event_type, data)`` pair the dispatcher uses.
+
+    Wave 11.I, milestone Q: ``dispatch`` and ``dispatch_async`` accept a
+    ``WorkflowEvent`` directly so the ``WorkflowEvent(**event)`` rewrap
+    in ``events/triggers.py`` becomes a no-op. The legacy
+    ``(event_type, data)`` shape stays supported via
+    :meth:`WorkflowEvent.from_legacy` upstream of the dispatcher (the
+    public API just forwards either form).
+    """
+    # Lazy import: services.events imports event_waiter for trigger
+    # adaptation, so a top-level import would be circular.
+    from services.events.envelope import WorkflowEvent
+
+    if isinstance(event, WorkflowEvent):
+        return event.type, event.data if isinstance(event.data, dict) else {"data": event.data}
+    if isinstance(event, str):
+        return event, data or {}
+    raise TypeError(
+        f"dispatch expects a WorkflowEvent or (event_type: str, data: Dict); "
+        f"got {type(event).__name__}"
+    )
+
+
+async def dispatch_async(
+    event: "Any",
+    data: Optional[Dict] = None,
+) -> int:
     """Dispatch event asynchronously (for Redis mode).
 
     Args:
-        event_type: Type of event (e.g., 'whatsapp_message_received')
-        data: Event data
+        event: Either a :class:`WorkflowEvent` (preferred, Wave 11.I) or
+            an event-type string. The legacy ``(event_type, data)`` form
+            stays supported.
+        data: Event payload (when ``event`` is a string).
 
     Returns:
         1 if event was added to stream, 0 otherwise
     """
+    event_type, payload = _unpack_event(event, data)
     logger.debug(f"[EventWaiter] dispatch_async: event_type='{event_type}'")
 
     if is_redis_mode():
         cache = get_cache_service()
         stream_name = _get_stream_name(event_type)
-        msg_id = await cache.stream_add(stream_name, data)
+        msg_id = await cache.stream_add(stream_name, payload)
         if msg_id:
             logger.debug(f"[EventWaiter] Added event to stream {stream_name}: {msg_id}")
             return 1
         return 0
     else:
         # Fall back to sync dispatch for memory mode
-        return dispatch(event_type, data)
+        return dispatch(event_type, payload)
 
 
-def dispatch(event_type: str, data: Dict) -> int:
+def dispatch(
+    event: "Any",
+    data: Optional[Dict] = None,
+) -> int:
     """Dispatch event to matching waiters (synchronous, memory mode).
 
     Thread-safe: Can be called from APScheduler threads or async context.
 
     Args:
-        event_type: Type of event (e.g., 'whatsapp_message_received')
-        data: Event data
+        event: Either a :class:`WorkflowEvent` (preferred, Wave 11.I) or
+            an event-type string. The legacy ``(event_type, data)`` form
+            stays supported.
+        data: Event payload (when ``event`` is a string).
 
     Returns:
         Number of waiters resolved
     """
+    event_type, data = _unpack_event(event, data)
     if is_redis_mode():
         # In Redis mode, use async dispatch
         # Handle both async context and thread context (e.g., APScheduler callbacks)