Skip to content

Self-improving AI Employees for everyone

feat(temporal): TriggerListenerWorkflow canary on webhookTrigger (Wave 12 C1)

trohitgc24bc626a352
diff --git a/docs-internal/event_framework.md b/docs-internal/event_framework.md
index 6e0a8d29..0c6bbf1c 100644
--- a/docs-internal/event_framework.md
+++ b/docs-internal/event_framework.md
@@ -7,6 +7,22 @@ Temporal-native event-routing layer for MachinaOs. Implements RFC sections
This doc is the operator + plugin-author reference. The design rationale +
phase plan lives in `~/.claude/plans/properly-fix-the-tech-dreamy-tarjan.md`.
+## Status (2026-05-14)
+
+| Phase | State |
+|---|---|
+| A1-A9 — Temporal primitives + CloudEvents spec compliance | ✅ shipped (commit `c3dc85a`) |
+| B1-B10 — plugin-owned `_events.py` modules (9 plugin folders) | ✅ shipped (commits `7e4ff7b`, `c4d9428`, `da63d73`, `de8be88`) |
+| B11 — FE handler migration to envelope-aware readers | ⏳ deferred to FE session |
+| C1 canary (webhookTrigger) — `TriggerListenerWorkflow` + Visibility-API registry | ✅ shipped 2026-05-14 (25 tests) |
+| C1 rollout — promote remaining event triggers | ⏳ pending |
+| C2 — Polling triggers as long-lived workflows | ⏳ pending |
+| C3 — APScheduler → Temporal Schedules | ⏳ pending |
+| C4 — Close cross-plugin `_service` reaches (4 sites) | ⏳ pending |
+| D1-D5 — Visibility / retry / DLQ / drain / Y5 | ⏳ pending |
+
+`Settings.event_framework_enabled` gates the new dispatch path (default off in Phase A). When off, `services.events.dispatch.emit` is a no-op pass-through; plugin emitters still call `status_broadcaster.broadcast(...)` directly, so the FE fan-out is unchanged. Turn on per-callsite for opt-in dogfooding without flipping the flag globally.
+
## What this framework does
Every inbound event (HTTP webhook, Telegram message, Gmail poll result,
diff --git a/server/nodes/trigger/webhook_trigger/_events.py b/server/nodes/trigger/webhook_trigger/_events.py
index 48e313cd..7b16a531 100644
--- a/server/nodes/trigger/webhook_trigger/_events.py
+++ b/server/nodes/trigger/webhook_trigger/_events.py
@@ -52,21 +52,37 @@ def webhook_received(webhook_data: Mapping[str, Any]) -> WorkflowEvent:
async def broadcast_webhook_received(webhook_data: Mapping[str, Any]) -> None:
"""Broadcast an incoming webhook to ``webhookTrigger`` nodes.
- Routes through ``broadcaster.send_custom_event`` (the existing
- transport that does both the WS legacy broadcast AND the
- ``event_waiter`` dispatch). Wire shape unchanged from pre-B9.
-
- The typed envelope is constructed for future log/audit use even
- though no FE listener consumes it today.
+ Three delivery paths (kept in this order for back-compat):
+
+ 1. **Legacy WS broadcast + asyncio.Future waiters** via
+ ``broadcaster.send_custom_event`` (the in-process collector /
+ processor path; default while the canary flag is off).
+ 2. **Temporal Signal fan-out** via ``services.events.dispatch.emit``
+ (Wave 12 C1 canary). Gated by ``Settings.event_framework_enabled``;
+ inside :func:`emit` the flag-off branch is a no-op pass-through
+ so it's cheap to always invoke. When on, the dispatch helper
+ runs a Visibility query and signals every running
+ :class:`TriggerListenerWorkflow` whose ``EventType`` matches
+ the envelope.
+
+ Both paths are non-overlapping consumers — legacy reaches the
+ in-process collector/processor task pair; the Temporal path
+ reaches the durable listener workflow. Producer doesn't need to
+ pick one.
"""
from services.status_broadcaster import get_status_broadcaster
broadcaster = get_status_broadcaster()
- # Build the typed envelope (currently unused on the wire, but
- # available for any future audit log / DLQ replay).
- _ = webhook_received(webhook_data)
+ envelope = webhook_received(webhook_data)
await broadcaster.send_custom_event(_LEGACY_EVENT_TYPE, dict(webhook_data))
+ # Temporal-durable fan-out (Wave 12 C1 canary). Always-call;
+ # dispatch.emit is a no-op when the feature flag is off, so the
+ # legacy path keeps working unchanged.
+ from services.events.dispatch import emit
+
+ await emit(envelope, wire_routing_key=_LEGACY_EVENT_TYPE)
+
__all__ = [
"broadcast_webhook_received",
diff --git a/server/services/deployment/manager.py b/server/services/deployment/manager.py
index 09b6c5c6..85feec99 100644
--- a/server/services/deployment/manager.py
+++ b/server/services/deployment/manager.py
@@ -24,6 +24,18 @@ if TYPE_CHECKING:
logger = get_logger(__name__)
+# Wave 12 C1 canary: trigger types that route to TriggerListenerWorkflow
+# instead of the in-process collector/processor. Gated by
+# Settings.event_framework_enabled. When the flag is off the canary set
+# is irrelevant; when on, types outside this set stay on the legacy path.
+# Expansion path: add types here as each is proven Temporal-durable.
+_CANARY_LISTENER_TRIGGER_TYPES = frozenset(["webhookTrigger"])
+
+# Listener Temporal workflow type-name. Used both for ``start_workflow``
+# and as the Visibility filter for cancellation discovery.
+_LISTENER_WORKFLOW_TYPE = "TriggerListenerWorkflow"
+
+
class DeploymentManager:
"""Manages event-driven workflow deployment.
@@ -246,6 +258,10 @@ class DeploymentManager:
for node in state.nodes:
waiter_count += event_waiter.cancel_for_node(node['id'])
+ # Wave 12 C1 canary: cancel Temporal-durable listeners for this
+ # deployment. Visibility-query-based; no local handle dict.
+ canary_count = await self._cancel_canary_listeners(workflow_id)
+
# Clear cron iteration counters for this workflow's cron nodes
for node_id in cron_node_ids:
self._cron_iterations.pop(node_id, None)
@@ -265,6 +281,7 @@ class DeploymentManager:
"listeners_cancelled": listener_count,
"crons_cancelled": cron_count,
"waiters_cancelled": waiter_count,
+ "canary_listeners_cancelled": canary_count,
"cancelled_listener_node_ids": listener_nodes
}
@@ -400,11 +417,35 @@ class DeploymentManager:
return TriggerInfo(node_id, "start", fired=True)
async def _setup_event_trigger(self, node: Dict, workflow_id: str) -> TriggerInfo:
- """Setup event-based trigger."""
+ """Setup event-based trigger.
+
+ Three dispatch paths (in priority order):
+
+ 1. **Wave 12 C1 canary**: when ``Settings.event_framework_enabled``
+ is on AND ``node_type`` is in :data:`_CANARY_LISTENER_TRIGGER_TYPES`,
+ start a Temporal-durable :class:`TriggerListenerWorkflow`.
+ Survives FastAPI process restart via Temporal Event-History replay.
+
+ 2. **Polling triggers** (Gmail, Twitter): API-polling factory
+ registered by the plugin's ``PollingTriggerNode`` subclass.
+
+ 3. **Legacy**: in-process collector/processor task pair via
+ ``trigger_manager.setup_event_trigger``. Dies on process
+ restart — pre-Wave-12 behaviour, kept for triggers not yet
+ on the canary list.
+ """
node_id = node['id']
node_type = node.get('type', '')
params = await self.database.get_node_parameters(node_id) or {}
+ # Path 1: Wave 12 C1 canary — Temporal-durable listener.
+ if await self._canary_listener_enabled_for(node_type):
+ listener_id = await self._start_canary_listener(node, workflow_id, params)
+ if listener_id is not None:
+ return TriggerInfo(node_id, node_type, job_id=listener_id)
+ # Fall through to legacy path if Temporal client unavailable
+ # (already logged inside _start_canary_listener).
+
async def on_event(event_data: Dict):
trigger_data = {
'node_id': node_id,
@@ -444,6 +485,203 @@ class DeploymentManager:
)
return TriggerInfo(node_id, node_type)
+ # =========================================================================
+ # WAVE 12 C1 CANARY: TEMPORAL-DURABLE LISTENERS
+ # =========================================================================
+ #
+ # Pattern (cross-confirmed across Temporal docs, samples-python,
+ # Inngest, Prefect, n8n): deterministic workflow_id mapped to
+ # business entity (deployment + node), WorkflowIDConflictPolicy.
+ # USE_EXISTING for idempotent re-deploy, Search Attributes set at
+ # start, Visibility API queries for cross-workflow discovery on
+ # cancel. The Temporal server's Visibility store IS the registry —
+ # no Python dict of handles, no instance state to drift on
+ # FastAPI restart. Cancellation uses ``cancel()`` (graceful) over
+ # ``terminate()`` per docs.temporal.io/develop/python/cancellation.
+ #
+ # Refs:
+ # - https://docs.temporal.io/develop/python/temporal-clients
+ # ("Workflow ID mapped to business entities")
+ # - https://docs.temporal.io/visibility + /list-filter
+ # - https://docs.temporal.io/develop/python/cancellation
+ # - https://github.com/temporalio/samples-python/blob/main/hello/hello_search_attributes.py
+ # =========================================================================
+
+ @staticmethod
+ def _listener_workflow_id(workflow_id: str, node_id: str) -> str:
+ """Deterministic Temporal workflow_id for a canary listener.
+
+ Mapped to the business entity (deployment workflow_id + trigger
+ node_id) so re-deploy of the same workflow produces the same
+ listener id. Pairs with ``WorkflowIDConflictPolicy.USE_EXISTING``
+ for idempotent start.
+ """
+ return f"trigger-listener-{workflow_id}-{node_id}"
+
+ @staticmethod
+ async def _canary_listener_enabled_for(node_type: str) -> bool:
+ """Whether the C1 canary applies to this trigger type.
+
+ Lazy ``Settings()`` call so a runtime flag flip takes effect on
+ the next deploy without restart.
+ """
+ if node_type not in _CANARY_LISTENER_TRIGGER_TYPES:
+ return False
+ from core.config import Settings
+
+ return bool(Settings().event_framework_enabled)
+
+ async def _start_canary_listener(
+ self,
+ node: Dict,
+ workflow_id: str,
+ params: Dict,
+ ) -> Optional[str]:
+ """Start a TriggerListenerWorkflow for a canary trigger.
+
+ Returns the Temporal listener workflow_id on success, or
+ ``None`` if the Temporal client isn't connected (caller falls
+ through to the legacy collector/processor path).
+
+ Idempotent: re-deploying the same MachinaOs workflow re-runs
+ this with the same deterministic id; Temporal returns the
+ existing handle via ``WorkflowIDConflictPolicy.USE_EXISTING``
+ instead of erroring. Search Attributes provide the registry
+ used by :meth:`_cancel_canary_listeners`.
+ """
+ from core.container import container
+ from temporalio.common import (
+ SearchAttributeKey,
+ SearchAttributePair,
+ TypedSearchAttributes,
+ WorkflowIDConflictPolicy,
+ )
+
+ node_id = node["id"]
+ node_type = node.get("type", "")
+
+ wrapper = container.temporal_client()
+ if wrapper is None or wrapper.client is None:
+ logger.warning(
+ "Canary listener requested but Temporal not connected; "
+ "falling back to legacy collector/processor path",
+ node_id=node_id, workflow_id=workflow_id, node_type=node_type,
+ )
+ return None
+
+ state = self._deployments.get(workflow_id)
+ if state is None:
+ raise RuntimeError(f"No deployment state for workflow {workflow_id}")
+
+ config = event_waiter.get_trigger_config(node_type)
+ event_type = config.event_type if config else f"unknown_{node_type}"
+
+ listener_id = self._listener_workflow_id(workflow_id, node_id)
+
+ # Search Attribute keys mirror services/temporal/search_attributes.py
+ # (the A4 registration spec). All Keyword-typed; values are scalars.
+ event_type_key = SearchAttributeKey.for_keyword("EventType")
+ trigger_node_id_key = SearchAttributeKey.for_keyword("TriggerNodeId")
+ event_workflow_id_key = SearchAttributeKey.for_keyword("EventWorkflowId")
+ event_trigger_kind_key = SearchAttributeKey.for_keyword("EventTriggerKind")
+
+ await wrapper.client.start_workflow(
+ _LISTENER_WORKFLOW_TYPE,
+ args=[{
+ "workflow_id": workflow_id,
+ "trigger_node_id": node_id,
+ "node_type": node_type,
+ "event_type": event_type,
+ "filter_params": params,
+ "nodes": state.nodes,
+ "edges": state.edges,
+ "session_id": state.session_id,
+ }],
+ id=listener_id,
+ task_queue="machina-tasks",
+ id_conflict_policy=WorkflowIDConflictPolicy.USE_EXISTING,
+ search_attributes=TypedSearchAttributes([
+ SearchAttributePair(event_type_key, event_type),
+ SearchAttributePair(trigger_node_id_key, node_id),
+ SearchAttributePair(event_workflow_id_key, workflow_id),
+ SearchAttributePair(event_trigger_kind_key, "webhook"),
+ ]),
+ )
+
+ # Broadcast waiting status (parity with legacy path).
+ await self._broadcaster.update_node_status(
+ node_id, "waiting",
+ {
+ "message": f"Waiting for {config.display_name if config else node_type} (Temporal-durable)...",
+ "event_type": event_type,
+ "listener_id": listener_id,
+ },
+ workflow_id=workflow_id,
+ )
+
+ logger.info(
+ "Canary listener started",
+ listener_id=listener_id,
+ workflow_id=workflow_id,
+ node_id=node_id,
+ event_type=event_type,
+ )
+ return listener_id
+
+ async def _cancel_canary_listeners(self, workflow_id: str) -> int:
+ """Cancel all canary listeners for this deployment.
+
+ Uses Visibility API query — the Temporal server's Visibility
+ store IS the registry, no local dict. ``cancel()`` is graceful;
+ listeners drain in-flight child spawns before exiting.
+
+ Visibility is eventually consistent
+ (https://docs.temporal.io/visibility) — a freshly-started listener
+ might not appear in the query result for a few seconds. Acceptable
+ here: the listener will eventually surface in a subsequent cancel
+ sweep, AND its parent_close_policy=ABANDON means in-flight runs
+ complete regardless.
+ """
+ from core.container import container
+
+ wrapper = container.temporal_client()
+ if wrapper is None or wrapper.client is None:
+ return 0
+
+ # Visibility List Filter query — operators per docs.temporal.io/list-filter.
+ query = (
+ f"EventWorkflowId='{workflow_id}' "
+ f"AND WorkflowType='{_LISTENER_WORKFLOW_TYPE}' "
+ f"AND ExecutionStatus='Running'"
+ )
+
+ cancelled = 0
+ try:
+ async for wf in wrapper.client.list_workflows(query=query):
+ try:
+ await wrapper.client.get_workflow_handle(wf.id).cancel()
+ cancelled += 1
+ except Exception as exc: # noqa: BLE001
+ # Per-listener failures don't block sweep of the rest.
+ logger.warning(
+ f"Failed to cancel canary listener {wf.id}: {exc}",
+ workflow_id=workflow_id,
+ )
+ except Exception as exc: # noqa: BLE001
+ logger.warning(
+ f"Visibility query for canary listeners failed: {exc} "
+ f"(query={query!r})",
+ workflow_id=workflow_id,
+ )
+
+ if cancelled:
+ logger.info(
+ "Canary listeners cancelled",
+ workflow_id=workflow_id,
+ count=cancelled,
+ )
+ return cancelled
+
# =========================================================================
# EXECUTION RUNS
# =========================================================================
diff --git a/server/services/temporal/trigger_listener_workflow.py b/server/services/temporal/trigger_listener_workflow.py
new file mode 100644
index 00000000..8fced073
--- /dev/null
+++ b/server/services/temporal/trigger_listener_workflow.py
@@ -0,0 +1,313 @@
+"""Wave 12 C1 (canary): long-lived Temporal workflow that owns a trigger's wait.
+
+One :class:`TriggerListenerWorkflow` runs per (deployment, event-trigger)
+pair. It survives FastAPI process restarts because Temporal replays its
+state from Event History — the durability gap that the in-process
+``services/deployment/triggers.py:setup_event_trigger`` collector/processor
+``asyncio.Task`` pair leaves open.
+
+Flow per signal:
+
+1. ``dispatch.emit(event)`` runs a Visibility query
+ ``EventType='<type>' AND ExecutionStatus='Running'`` and signals each
+ matching listener (this class) with ``on_event``.
+2. ``on_event`` dedups by ``event.id`` (per-run state, reconstructed
+ deterministically from Event History on replay) and queues the
+ payload.
+3. The main ``run`` loop ``wait_condition``s for any queued event, pops
+ the head, builds the filtered downstream graph, and starts a child
+ :class:`MachinaWorkflow` with the trigger node marked ``_pre_executed``.
+4. Child workflow uses ``parent_close_policy=ABANDON`` so listener
+ cancellation never kills in-flight execution runs.
+
+Canary scope (2026-05-14): only ``webhookTrigger`` ships with this
+wiring on the deployment-manager side. Other trigger types stay on the
+legacy collector/processor path until the canary proves out. The
+workflow itself is type-agnostic — the listener treats the event
+payload as opaque and the filter shape is provided by the deployment
+at workflow start.
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Any, Dict, List, Optional, Set
+
+from temporalio import workflow
+from temporalio.common import WorkflowIDReusePolicy
+from temporalio.workflow import ParentClosePolicy
+
+
+# 50K events is the Temporal Event-History soft ceiling per the
+# very-long-running-workflows blog post — past it the workflow
+# spends more time replaying history than doing work. The listener
+# does ~2-3 events per inbound trigger (signal accept + child spawn),
+# so this caps at ~16K triggers between continueAsNew checkpoints.
+# Per-event histogram is empirical; tune later.
+_MAX_EVENTS_BEFORE_CONTINUE_AS_NEW = 16_000
+
+
[email protected](name="TriggerListenerWorkflow", sandboxed=False)
+class TriggerListenerWorkflow:
+ """Long-lived listener that funnels signals into child MachinaWorkflow runs.
+
+ Determinism note: all state lives on ``self`` and is reconstructed
+ from Event History on replay. The ``_seen_event_ids`` set drains
+ on ``continueAsNew`` (intentional — different listener runs are
+ different consumers).
+ """
+
+ def __init__(self) -> None:
+ self._seen_event_ids: Set[str] = set()
+ self._matched_events: List[Dict[str, Any]] = []
+ self._processed_count: int = 0
+
+ @workflow.signal
+ async def on_event(self, event_payload: Dict[str, Any]) -> None:
+ """Receive an event from ``services.events.dispatch.emit``.
+
+ Same shape + dedup contract as :meth:`MachinaWorkflow.on_event`.
+ Malformed payloads (missing ``id``) are dropped — every other
+ path mints an id at envelope construction, so missing-id means
+ a producer wired itself wrong.
+ """
+ event_id = event_payload.get("id")
+ if not event_id:
+ workflow.logger.warning(
+ "TriggerListener.on_event: skipping malformed envelope without 'id'"
+ )
+ return
+ if event_id in self._seen_event_ids:
+ workflow.logger.debug(
+ f"TriggerListener.on_event: dedup hit for event.id={event_id}"
+ )
+ return
+ self._seen_event_ids.add(event_id)
+ self._matched_events.append(event_payload)
+
+ @workflow.run
+ async def run(self, listener_data: Dict[str, Any]) -> Dict[str, Any]:
+ """Loop forever spawning a child :class:`MachinaWorkflow` per matched event.
+
+ ``listener_data`` shape (deployment-supplied):
+ {
+ "workflow_id": str, # MachinaOs deployment workflow_id
+ "trigger_node_id": str, # node id that "fires" on each event
+ "node_type": str, # e.g. "webhookTrigger"
+ "event_type": str, # e.g. "com.machinaos.webhook.received"
+ "filter_params": Dict, # used by the event-side filter via dispatch.emit
+ "nodes": List[Dict], # full deployment graph snapshot
+ "edges": List[Dict],
+ "session_id": str,
+ "tenant_id": Optional[str],
+ }
+
+ Returns when ``continueAsNew`` fires — the new run picks up
+ immediately under the same workflow-id. Cancellation by the
+ deployment manager cancels the workflow normally.
+ """
+ workflow.logger.info(
+ f"TriggerListener started: workflow_id={listener_data.get('workflow_id')} "
+ f"node={listener_data.get('trigger_node_id')} "
+ f"event_type={listener_data.get('event_type')}"
+ )
+
+ while True:
+ await workflow.wait_condition(lambda: bool(self._matched_events))
+ event = self._matched_events.pop(0) if self._matched_events else None
+ if event is None:
+ continue
+
+ try:
+ await self._spawn_child_run(event, listener_data)
+ except Exception as exc: # noqa: BLE001
+ # Per-event spawn failures don't kill the listener.
+ # Log and move on; the rejected event still counts as
+ # "seen" so a producer retry with the same id won't
+ # re-fire (correct: server-side dedup applies even on
+ # downstream failure).
+ workflow.logger.error(
+ f"TriggerListener spawn failed for event.id={event.get('id')}: {exc}"
+ )
+
+ self._processed_count += 1
+ if self._processed_count >= _MAX_EVENTS_BEFORE_CONTINUE_AS_NEW:
+ workflow.logger.info(
+ f"TriggerListener continue_as_new: processed={self._processed_count}"
+ )
+ workflow.continue_as_new(args=[listener_data])
+
+ async def _spawn_child_run(
+ self,
+ event: Dict[str, Any],
+ listener_data: Dict[str, Any],
+ ) -> None:
+ """Build the filtered downstream graph + start a child MachinaWorkflow.
+
+ The trigger node is marked ``_pre_executed=True`` with the event
+ envelope's ``data`` payload as its output. Sibling triggers in
+ the same deployment are marked ``_pre_executed=True`` with
+ ``{not_triggered: True}`` so MachinaWorkflow doesn't block on
+ them (mirrors ``DeploymentManager._execute_from_trigger``).
+ """
+ trigger_node_id = listener_data["trigger_node_id"]
+ nodes = listener_data["nodes"]
+ edges = listener_data["edges"]
+ session_id = listener_data.get("session_id", "default")
+ workflow_id = listener_data.get("workflow_id")
+ tenant_id = listener_data.get("tenant_id")
+
+ # event.data is the producer-supplied payload (webhook body /
+ # message details / etc.). The full envelope (specversion, type,
+ # subject, …) stays in event for any downstream introspection
+ # via the agent layer, but the trigger output is the data dict.
+ trigger_output = event.get("data") if isinstance(event.get("data"), dict) else {}
+ trigger_output = {**trigger_output, "_event_envelope": event}
+
+ filtered_nodes, filtered_edges = _build_run_graph(
+ trigger_node_id=trigger_node_id,
+ trigger_output=trigger_output,
+ nodes=nodes,
+ edges=edges,
+ )
+
+ # Stable child workflow ID derived from event.id gives free
+ # idempotency via WorkflowIDReusePolicy.ALLOW_DUPLICATE_FAILED_ONLY:
+ # if the same event.id arrives twice (producer retry across
+ # listener restart), Temporal rejects the duplicate start.
+ # Lazy fallback to workflow.uuid4() only if event.id is missing
+ # (shouldn't happen — on_event drops malformed payloads).
+ event_id = event.get("id") or workflow.uuid4().hex
+ child_id = f"run-{workflow_id}-{event_id}"
+
+ await workflow.start_child_workflow(
+ "MachinaWorkflow",
+ args=[{
+ "nodes": filtered_nodes,
+ "edges": filtered_edges,
+ "session_id": session_id,
+ "workflow_id": workflow_id,
+ "tenant_id": tenant_id,
+ }],
+ id=child_id,
+ parent_close_policy=ParentClosePolicy.ABANDON,
+ id_reuse_policy=WorkflowIDReusePolicy.ALLOW_DUPLICATE_FAILED_ONLY,
+ execution_timeout=timedelta(hours=1),
+ run_timeout=timedelta(hours=1),
+ )
+
+ workflow.logger.info(
+ f"TriggerListener spawned child run: child_id={child_id} "
+ f"event.id={event.get('id')} event.type={event.get('type')}"
+ )
+
+
+# ---------------------------------------------------------------------------
+# Pure graph builder — kept in this module on purpose: the only consumer is
+# this workflow class, and inlining keeps the import surface deterministic
+# (workflow.defn(sandboxed=False) still benefits from minimal imports).
+# Mirrors the logic in DeploymentManager._execute_from_trigger + ._get_downstream_nodes
+# but specialised for the listener's "trigger fires once, spawn run" path.
+# ---------------------------------------------------------------------------
+
+
+def _build_run_graph(
+ *,
+ trigger_node_id: str,
+ trigger_output: Dict[str, Any],
+ nodes: List[Dict[str, Any]],
+ edges: List[Dict[str, Any]],
+) -> tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+ """Build filtered (nodes, edges) for one execution run.
+
+ Marks the firing trigger ``_pre_executed=True`` with ``trigger_output``;
+ marks sibling triggers ``_pre_executed=True`` with ``{not_triggered:
+ True}`` so MachinaWorkflow doesn't try to wait on them.
+ """
+ from constants import (
+ AI_AGENT_TYPES,
+ TOOLKIT_NODE_TYPES,
+ WORKFLOW_TRIGGER_TYPES,
+ )
+
+ node_types = {n["id"]: n.get("type", "") for n in nodes}
+
+ downstream_ids: Set[str] = set()
+
+ def _collect(current_id: str) -> None:
+ for edge in edges:
+ if edge.get("source") != current_id:
+ continue
+ target_id = edge.get("target")
+ if not target_id or target_id in downstream_ids:
+ continue
+ target_type = node_types.get(target_id, "")
+ if target_type in WORKFLOW_TRIGGER_TYPES:
+ # Stop at trigger nodes — independent event listeners.
+ continue
+ downstream_ids.add(target_id)
+ _collect(target_id)
+
+ _collect(trigger_node_id)
+
+ # Config nodes (memory, tools, etc.) connected to downstream nodes.
+ for edge in edges:
+ target = edge.get("target")
+ source = edge.get("source")
+ handle = edge.get("targetHandle", "")
+ is_config = handle and handle.startswith("input-") and handle != "input-main"
+ if is_config and target in downstream_ids and source not in downstream_ids:
+ if node_types.get(source, "") in WORKFLOW_TRIGGER_TYPES:
+ continue
+ downstream_ids.add(source)
+
+ # Sub-nodes connected to toolkit nodes (n8n Sub-Node pattern).
+ toolkit_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")
+ if target in toolkit_ids and source not in downstream_ids:
+ downstream_ids.add(source)
+
+ # Tool nodes connected to AI Agent's input-tools handle.
+ agent_ids = {
+ n["id"] for n in nodes
+ if n.get("type") in AI_AGENT_TYPES and n["id"] in downstream_ids
+ }
+ for edge in edges:
+ target = edge.get("target")
+ source = edge.get("source")
+ if (
+ target in agent_ids
+ and edge.get("targetHandle", "") == "input-tools"
+ and source not in downstream_ids
+ ):
+ downstream_ids.add(source)
+
+ run_filter = {trigger_node_id} | downstream_ids
+ filtered_nodes: List[Dict[str, Any]] = []
+ for node in nodes:
+ if node["id"] not in run_filter:
+ continue
+ node_copy = dict(node)
+ node_type = node.get("type", "")
+ if node["id"] == trigger_node_id:
+ node_copy["_pre_executed"] = True
+ node_copy["_trigger_output"] = trigger_output
+ elif node_type in WORKFLOW_TRIGGER_TYPES:
+ node_copy["_pre_executed"] = True
+ node_copy["_trigger_output"] = {"not_triggered": True}
+ filtered_nodes.append(node_copy)
+
+ filtered_edges = [
+ e for e in edges
+ if e.get("source") in run_filter and e.get("target") in run_filter
+ ]
+
+ return filtered_nodes, filtered_edges
+
+
+__all__ = ["TriggerListenerWorkflow", "_build_run_graph"]
diff --git a/server/services/temporal/worker.py b/server/services/temporal/worker.py
index 612a3155..37d4fed0 100644
--- a/server/services/temporal/worker.py
+++ b/server/services/temporal/worker.py
@@ -27,6 +27,7 @@ from temporalio.worker import Worker
from core.logging import get_logger
from .workflow import MachinaWorkflow
+from .trigger_listener_workflow import TriggerListenerWorkflow
from .activities import (
NodeExecutionActivities,
create_shared_session,
@@ -140,7 +141,7 @@ class TemporalWorkerManager:
self._worker = Worker(
self.client,
task_queue=self.task_queue,
- workflows=[MachinaWorkflow, AgentWorkflow],
+ workflows=[MachinaWorkflow, AgentWorkflow, TriggerListenerWorkflow],
activities=[
self._activities.execute_node_activity,
*per_type,
@@ -367,7 +368,7 @@ async def run_standalone_worker(
worker = Worker(
client,
task_queue=task_queue,
- workflows=[MachinaWorkflow],
+ workflows=[MachinaWorkflow, TriggerListenerWorkflow],
activities=[activities.execute_node_activity], # Pass bound method
max_concurrent_activities=pool_size,
max_concurrent_workflow_tasks=10,
@@ -406,7 +407,7 @@ async def create_worker(
return Worker(
client,
task_queue=task_queue,
- workflows=[MachinaWorkflow],
+ workflows=[MachinaWorkflow, TriggerListenerWorkflow],
activities=[activities.execute_node_activity], # Pass bound method
max_concurrent_activities=100,
max_concurrent_workflow_tasks=10,
diff --git a/server/tests/test_deployment_canary_listener.py b/server/tests/test_deployment_canary_listener.py
new file mode 100644
index 00000000..78f5b2fd
--- /dev/null
+++ b/server/tests/test_deployment_canary_listener.py
@@ -0,0 +1,463 @@
+"""Wave 12 C1 canary: DeploymentManager Temporal-listener integration tests.
+
+These tests exercise the canary plumbing inside :class:`DeploymentManager`
+WITHOUT a live Temporal cluster — the ``container.temporal_client()``
+call is monkeypatched to return a stub whose ``client.start_workflow``
+and ``client.list_workflows`` calls are captured and asserted.
+
+The canonical pattern under test:
+
+1. **Deterministic listener id** = ``trigger-listener-{workflow_id}-{node_id}``.
+ Re-deploy of the same MachinaOs workflow targets the same Temporal id.
+2. **WorkflowIDConflictPolicy.USE_EXISTING** — Temporal returns the existing
+ handle instead of erroring on a duplicate-id start. Idempotent re-deploy.
+3. **TypedSearchAttributes set at start** — ``EventType``, ``TriggerNodeId``,
+ ``EventWorkflowId``, ``EventTriggerKind``. These ARE the registry the
+ cancel path queries.
+4. **Cancel via ``list_workflows(query=...) + handle.cancel()``** — no
+ instance-state dict, no handle caching. The Temporal server's
+ Visibility store is the source of truth.
+
+Cross-confirmed across three official sources (Temporal docs, samples-python,
+Inngest/Prefect/n8n source analysis). Locking the implementation against
+these invariants here prevents future drift back to tribal in-memory tracking.
+"""
+
+from __future__ import annotations
+
+import sys
+import types
+from typing import Any, Dict, List
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+# Stub `machina` namespace — same pattern as other event-framework tests.
+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
+
+
+# ---------------------------------------------------------------------------
+# Helpers — build a DeploymentManager with the minimum scaffolding to drive
+# the canary code paths. Database / status broadcaster are pure mocks.
+# ---------------------------------------------------------------------------
+
+
+def _build_manager_with_state(workflow_id: str, nodes, edges, session_id="sess"):
+ """Build a DeploymentManager populated with one in-flight deployment.
+
+ The canary methods read ``self._deployments[workflow_id]`` for nodes/edges
+ snapshots, so we register that state explicitly.
+ """
+ from services.deployment.manager import DeploymentManager
+ from services.deployment.state import DeploymentState
+
+ database = MagicMock()
+ database.get_node_parameters = AsyncMock(return_value={})
+ broadcaster = MagicMock()
+ broadcaster.update_node_status = AsyncMock()
+
+ mgr = DeploymentManager(
+ database=database,
+ execute_workflow_fn=AsyncMock(return_value={"success": True}),
+ store_output_fn=AsyncMock(),
+ broadcaster=broadcaster,
+ )
+ mgr._deployments[workflow_id] = DeploymentState(
+ deployment_id=f"deploy_{workflow_id}",
+ workflow_id=workflow_id,
+ is_running=True,
+ nodes=nodes,
+ edges=edges,
+ session_id=session_id,
+ )
+ return mgr, broadcaster
+
+
+def _node(node_id: str, node_type: str) -> Dict[str, Any]:
+ return {"id": node_id, "type": node_type, "data": {}}
+
+
+# ---------------------------------------------------------------------------
+# C1d.1 — deterministic listener id
+# ---------------------------------------------------------------------------
+
+
+class TestDeterministicListenerId:
+ """Re-deploy targets the same Temporal id; downstream USE_EXISTING
+ policy handles the duplicate gracefully."""
+
+ def test_id_format_is_stable(self):
+ from services.deployment.manager import DeploymentManager
+
+ first = DeploymentManager._listener_workflow_id("wf-1", "wh-1")
+ second = DeploymentManager._listener_workflow_id("wf-1", "wh-1")
+ assert first == second == "trigger-listener-wf-1-wh-1"
+
+ def test_id_differs_per_node_in_same_workflow(self):
+ from services.deployment.manager import DeploymentManager
+
+ a = DeploymentManager._listener_workflow_id("wf-1", "wh-1")
+ b = DeploymentManager._listener_workflow_id("wf-1", "wh-2")
+ assert a != b
+
+
+# ---------------------------------------------------------------------------
+# C1d.2 — canary scope: flag + type
+# ---------------------------------------------------------------------------
+
+
+class TestCanaryScope:
+ """Canary only activates for whitelisted trigger types AND when the
+ feature flag is on."""
+
+ @pytest.mark.asyncio
+ async def test_disabled_when_flag_off(self, monkeypatch):
+ from services.deployment.manager import DeploymentManager
+
+ class _Off:
+ event_framework_enabled = False
+
+ import core.config
+ monkeypatch.setattr(core.config, "Settings", lambda: _Off())
+
+ result = await DeploymentManager._canary_listener_enabled_for("webhookTrigger")
+ assert result is False
+
+ @pytest.mark.asyncio
+ async def test_disabled_for_non_canary_type(self, monkeypatch):
+ from services.deployment.manager import DeploymentManager
+
+ class _On:
+ event_framework_enabled = True
+
+ import core.config
+ monkeypatch.setattr(core.config, "Settings", lambda: _On())
+
+ # whatsappReceive isn't in the canary set yet.
+ result = await DeploymentManager._canary_listener_enabled_for("whatsappReceive")
+ assert result is False
+
+ @pytest.mark.asyncio
+ async def test_enabled_for_webhook_when_flag_on(self, monkeypatch):
+ from services.deployment.manager import DeploymentManager
+
+ class _On:
+ event_framework_enabled = True
+
+ import core.config
+ monkeypatch.setattr(core.config, "Settings", lambda: _On())
+
+ result = await DeploymentManager._canary_listener_enabled_for("webhookTrigger")
+ assert result is True
+
+
+# ---------------------------------------------------------------------------
+# C1d.3 — _start_canary_listener: deterministic id + USE_EXISTING + search attrs
+# ---------------------------------------------------------------------------
+
+
+class TestStartCanaryListener:
+ """The canonical start-workflow shape: deterministic id +
+ WorkflowIDConflictPolicy.USE_EXISTING + TypedSearchAttributes."""
+
+ @pytest.mark.asyncio
+ async def test_starts_with_deterministic_id_and_use_existing_policy(
+ self, monkeypatch
+ ):
+ from services.deployment.manager import DeploymentManager
+ from temporalio.common import WorkflowIDConflictPolicy
+
+ mgr, _ = _build_manager_with_state(
+ "wf-abc",
+ nodes=[_node("wh-1", "webhookTrigger"), _node("agent-1", "aiAgent")],
+ edges=[{"source": "wh-1", "target": "agent-1", "targetHandle": "input-main"}],
+ )
+
+ recorded_start: List[Dict[str, Any]] = []
+
+ async def fake_start_workflow(workflow_name, **kwargs):
+ recorded_start.append({"name": workflow_name, **kwargs})
+ return MagicMock()
+
+ client = MagicMock()
+ client.start_workflow = fake_start_workflow
+
+ wrapper = MagicMock()
+ wrapper.client = client
+
+ from core import container as container_mod
+ monkeypatch.setattr(container_mod.container, "temporal_client", lambda: wrapper)
+
+ node = _node("wh-1", "webhookTrigger")
+ listener_id = await mgr._start_canary_listener(
+ node, "wf-abc", params={"path": "hook"}
+ )
+
+ assert listener_id == "trigger-listener-wf-abc-wh-1"
+ assert len(recorded_start) == 1
+ call = recorded_start[0]
+ assert call["name"] == "TriggerListenerWorkflow"
+ assert call["id"] == "trigger-listener-wf-abc-wh-1"
+ assert call["id_conflict_policy"] == WorkflowIDConflictPolicy.USE_EXISTING
+ assert call["task_queue"] == "machina-tasks"
+
+ @pytest.mark.asyncio
+ async def test_search_attributes_include_event_workflow_id(self, monkeypatch):
+ """Cancel path queries by EventWorkflowId — start must set it."""
+ from services.deployment.manager import DeploymentManager
+ from temporalio.common import (
+ SearchAttributeKey,
+ TypedSearchAttributes,
+ )
+
+ mgr, _ = _build_manager_with_state(
+ "wf-xyz",
+ nodes=[_node("wh-1", "webhookTrigger")],
+ edges=[],
+ )
+
+ recorded: List[Dict[str, Any]] = []
+
+ async def fake_start_workflow(workflow_name, **kwargs):
+ recorded.append(kwargs)
+ return MagicMock()
+
+ client = MagicMock()
+ client.start_workflow = fake_start_workflow
+ wrapper = MagicMock()
+ wrapper.client = client
+
+ from core import container as container_mod
+ monkeypatch.setattr(container_mod.container, "temporal_client", lambda: wrapper)
+
+ await mgr._start_canary_listener(
+ _node("wh-1", "webhookTrigger"), "wf-xyz", params={}
+ )
+
+ sa = recorded[0]["search_attributes"]
+ assert isinstance(sa, TypedSearchAttributes)
+
+ # Extract by key — TypedSearchAttributes is iterable over Pair objects.
+ attrs_by_name = {pair.key.name: pair.value for pair in sa}
+ assert attrs_by_name["EventWorkflowId"] == "wf-xyz"
+ assert attrs_by_name["TriggerNodeId"] == "wh-1"
+ assert attrs_by_name["EventTriggerKind"] == "webhook"
+ # EventType comes from event_waiter.TRIGGER_REGISTRY['webhookTrigger'].
+ assert attrs_by_name["EventType"] == "webhook_received"
+
+ @pytest.mark.asyncio
+ async def test_returns_none_when_temporal_not_connected(self, monkeypatch):
+ """Falls through to legacy path; doesn't raise."""
+ from services.deployment.manager import DeploymentManager
+
+ mgr, _ = _build_manager_with_state(
+ "wf-1", nodes=[_node("wh-1", "webhookTrigger")], edges=[]
+ )
+
+ wrapper = MagicMock()
+ wrapper.client = None
+
+ from core import container as container_mod
+ monkeypatch.setattr(container_mod.container, "temporal_client", lambda: wrapper)
+
+ result = await mgr._start_canary_listener(
+ _node("wh-1", "webhookTrigger"), "wf-1", params={}
+ )
+ assert result is None
+
+
+# ---------------------------------------------------------------------------
+# C1d.4 — _cancel_canary_listeners: Visibility query + handle.cancel()
+# ---------------------------------------------------------------------------
+
+
+class TestCancelCanaryListeners:
+ """Cancel uses Visibility query — NO local dict — and graceful cancel()."""
+
+ @pytest.mark.asyncio
+ async def test_query_filters_by_workflow_id_and_listener_type(self, monkeypatch):
+ from services.deployment.manager import DeploymentManager
+
+ mgr, _ = _build_manager_with_state("wf-1", nodes=[], edges=[])
+
+ recorded_queries: List[str] = []
+ cancelled_ids: List[str] = []
+
+ async def fake_list_workflows(query):
+ recorded_queries.append(query)
+ for wf_id in ["trigger-listener-wf-1-wh-1", "trigger-listener-wf-1-wh-2"]:
+ yield MagicMock(id=wf_id)
+
+ handles_by_id: Dict[str, MagicMock] = {}
+
+ def fake_get_handle(wf_id):
+ handle = MagicMock()
+
+ async def fake_cancel():
+ cancelled_ids.append(wf_id)
+
+ handle.cancel = fake_cancel
+ handles_by_id[wf_id] = handle
+ return handle
+
+ client = MagicMock()
+ client.list_workflows = fake_list_workflows
+ client.get_workflow_handle = fake_get_handle
+
+ wrapper = MagicMock()
+ wrapper.client = client
+
+ from core import container as container_mod
+ monkeypatch.setattr(container_mod.container, "temporal_client", lambda: wrapper)
+
+ cancelled = await mgr._cancel_canary_listeners("wf-1")
+
+ # Query shape: EventWorkflowId + WorkflowType + ExecutionStatus.
+ assert len(recorded_queries) == 1
+ q = recorded_queries[0]
+ assert "EventWorkflowId='wf-1'" in q
+ assert "WorkflowType='TriggerListenerWorkflow'" in q
+ assert "ExecutionStatus='Running'" in q
+
+ assert cancelled == 2
+ assert sorted(cancelled_ids) == [
+ "trigger-listener-wf-1-wh-1",
+ "trigger-listener-wf-1-wh-2",
+ ]
+
+ @pytest.mark.asyncio
+ async def test_zero_listeners_returns_zero(self, monkeypatch):
+ """Visibility query with no results is the steady-state — must not raise."""
+ from services.deployment.manager import DeploymentManager
+
+ mgr, _ = _build_manager_with_state("wf-1", nodes=[], edges=[])
+
+ async def empty_list(query):
+ if False:
+ yield None # make this an async generator
+
+ client = MagicMock()
+ client.list_workflows = empty_list
+ wrapper = MagicMock()
+ wrapper.client = client
+
+ from core import container as container_mod
+ monkeypatch.setattr(container_mod.container, "temporal_client", lambda: wrapper)
+
+ cancelled = await mgr._cancel_canary_listeners("wf-1")
+ assert cancelled == 0
+
+ @pytest.mark.asyncio
+ async def test_per_listener_failure_doesnt_block_sweep(self, monkeypatch):
+ """One listener failing to cancel shouldn't strand the others —
+ each handle.cancel() is wrapped in its own try/except."""
+ from services.deployment.manager import DeploymentManager
+
+ mgr, _ = _build_manager_with_state("wf-1", nodes=[], edges=[])
+
+ cancelled_ids: List[str] = []
+
+ async def list_two(query):
+ for wf_id in ["trigger-listener-wf-1-wh-1", "trigger-listener-wf-1-wh-2"]:
+ yield MagicMock(id=wf_id)
+
+ def get_handle(wf_id):
+ handle = MagicMock()
+ if wf_id == "trigger-listener-wf-1-wh-1":
+ async def boom():
+ raise RuntimeError("simulated handle.cancel failure")
+ handle.cancel = boom
+ else:
+ async def ok():
+ cancelled_ids.append(wf_id)
+ handle.cancel = ok
+ return handle
+
+ client = MagicMock()
+ client.list_workflows = list_two
+ client.get_workflow_handle = get_handle
+ wrapper = MagicMock()
+ wrapper.client = client
+
+ from core import container as container_mod
+ monkeypatch.setattr(container_mod.container, "temporal_client", lambda: wrapper)
+
+ cancelled = await mgr._cancel_canary_listeners("wf-1")
+ # Only the second one succeeded.
+ assert cancelled == 1
+ assert cancelled_ids == ["trigger-listener-wf-1-wh-2"]
+
+ @pytest.mark.asyncio
+ async def test_returns_zero_when_temporal_disconnected(self, monkeypatch):
+ from services.deployment.manager import DeploymentManager
+
+ mgr, _ = _build_manager_with_state("wf-1", nodes=[], edges=[])
+
+ wrapper = MagicMock()
+ wrapper.client = None
+
+ from core import container as container_mod
+ monkeypatch.setattr(container_mod.container, "temporal_client", lambda: wrapper)
+
+ cancelled = await mgr._cancel_canary_listeners("wf-1")
+ assert cancelled == 0
+
+
+# ---------------------------------------------------------------------------
+# C1d.5 — invariant: DeploymentManager has NO instance state for canary listeners
+# ---------------------------------------------------------------------------
+
+
+class TestNoInstanceStateForCanaryListeners:
+ """Lock the architectural decision: DeploymentManager does NOT keep
+ a Python dict of canary listener handles or ids. Temporal's Visibility
+ store IS the registry. Adding such state would defeat the entire
+ durability guarantee (the dict dies on FastAPI restart, same gap the
+ canary is meant to close)."""
+
+ def test_no_canary_listeners_attribute(self):
+ from services.deployment.manager import DeploymentManager
+
+ database = MagicMock()
+ broadcaster = MagicMock()
+
+ mgr = DeploymentManager(
+ database=database,
+ execute_workflow_fn=AsyncMock(),
+ store_output_fn=AsyncMock(),
+ broadcaster=broadcaster,
+ )
+
+ forbidden_attrs = {
+ "_canary_listeners",
+ "_listener_handles",
+ "_temporal_handles",
+ "_active_listener_workflows",
+ }
+ present = {a for a in forbidden_attrs if hasattr(mgr, a)}
+ assert not present, (
+ f"DeploymentManager has tribal listener-tracking state: {present}. "
+ "Use Visibility API queries instead — Temporal's server IS the registry. "
+ "Otherwise FastAPI restart drops the dict and the canary's durability "
+ "guarantee evaporates."
+ )
+
+ def test_helper_methods_are_static_or_stateless(self):
+ """``_listener_workflow_id`` and ``_canary_listener_enabled_for``
+ are intentionally @staticmethod — they don't read instance state.
+ Helper code that needs to know the listener id reconstructs it
+ from (workflow_id, node_id) deterministically.
+ """
+ from services.deployment.manager import DeploymentManager
+
+ # Both helpers can be called on the class without an instance.
+ assert (
+ DeploymentManager._listener_workflow_id("wf", "node")
+ == "trigger-listener-wf-node"
+ )
diff --git a/server/tests/test_trigger_listener_workflow.py b/server/tests/test_trigger_listener_workflow.py
new file mode 100644
index 00000000..c134af54
--- /dev/null
+++ b/server/tests/test_trigger_listener_workflow.py
@@ -0,0 +1,348 @@
+"""Wave 12 C1 canary: tests for :class:`TriggerListenerWorkflow`.
+
+Unit-style tests that exercise the workflow class as a regular Python
+object — no live Temporal cluster required. ``workflow.logger`` calls
+are patched to a MagicMock so the handlers run outside a workflow
+event loop. ``workflow.start_child_workflow`` is patched to a recorder
+in the child-spawn tests.
+
+Tested invariants:
+
+C1a — ``on_event`` signal dedups by ``event.id`` (same contract as
+ :meth:`MachinaWorkflow.on_event`).
+C1b — Malformed envelopes (missing ``id``) are dropped silently
+ with one warning log.
+C1c — ``_build_run_graph`` produces the correct filtered (nodes, edges)
+ pair: trigger node carries ``_pre_executed=True`` + the event
+ payload; sibling triggers carry ``_pre_executed=True`` +
+ ``{not_triggered: True}``; downstream nodes are reachable;
+ cross-graph nodes are excluded.
+C1d — Spawned child workflows use a stable ``run-<workflow_id>-<event.id>``
+ ID so server-side dedup catches producer retries.
+"""
+
+from __future__ import annotations
+
+import sys
+import types
+from typing import Any, Dict, List
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+# Stub the `machina` package (lives at project root, outside server/) so
+# services.temporal.__init__ → _runtime.py → from machina.tcp import
+# probe_tcp_port doesn't crash collection.
+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
+
+
[email protected](autouse=True)
+def _patch_workflow_logger(monkeypatch):
+ """Workflow handlers call ``workflow.logger.<level>`` which requires a
+ Temporal event loop. Replace with a MagicMock so handlers run
+ synchronously in unit tests."""
+ from temporalio import workflow as temporal_workflow
+
+ monkeypatch.setattr(temporal_workflow, "logger", MagicMock())
+
+
+# ---------------------------------------------------------------------------
+# C1a + C1b — signal handler
+# ---------------------------------------------------------------------------
+
+
+class TestSignalHandlerDedup:
+ """Same dedup + drop-malformed contract as MachinaWorkflow.on_event."""
+
+ def test_init_empty_state(self):
+ from services.temporal.trigger_listener_workflow import TriggerListenerWorkflow
+
+ wf = TriggerListenerWorkflow()
+ assert wf._seen_event_ids == set()
+ assert wf._matched_events == []
+ assert wf._processed_count == 0
+
+ @pytest.mark.asyncio
+ async def test_on_event_dedups_by_id(self):
+ from services.temporal.trigger_listener_workflow import TriggerListenerWorkflow
+
+ wf = TriggerListenerWorkflow()
+ payload = {"id": "evt-1", "type": "com.machinaos.webhook.received", "data": {}}
+
+ await wf.on_event(payload)
+ await wf.on_event(payload) # duplicate
+
+ assert wf._seen_event_ids == {"evt-1"}
+ assert len(wf._matched_events) == 1
+
+ @pytest.mark.asyncio
+ async def test_on_event_drops_malformed_envelope(self):
+ from services.temporal.trigger_listener_workflow import TriggerListenerWorkflow
+
+ wf = TriggerListenerWorkflow()
+ await wf.on_event({"type": "com.machinaos.webhook.received"}) # no 'id'
+ assert wf._matched_events == []
+ assert wf._seen_event_ids == set()
+
+ @pytest.mark.asyncio
+ async def test_on_event_preserves_fifo_order(self):
+ from services.temporal.trigger_listener_workflow import TriggerListenerWorkflow
+
+ wf = TriggerListenerWorkflow()
+ for n in range(3):
+ await wf.on_event({"id": f"evt-{n}", "type": "x", "data": {"n": n}})
+
+ ids = [e["id"] for e in wf._matched_events]
+ assert ids == ["evt-0", "evt-1", "evt-2"]
+
+
+# ---------------------------------------------------------------------------
+# C1c — _build_run_graph
+# ---------------------------------------------------------------------------
+
+
+def _node(node_id: str, node_type: str) -> Dict[str, Any]:
+ return {"id": node_id, "type": node_type, "data": {}}
+
+
+def _edge(src: str, tgt: str, target_handle: str = "input-main") -> Dict[str, Any]:
+ return {"source": src, "target": tgt, "targetHandle": target_handle}
+
+
+class TestBuildRunGraph:
+ """Filtered-graph builder reproduces DeploymentManager._spawn_run semantics."""
+
+ def test_trigger_marked_pre_executed_with_output(self):
+ from services.temporal.trigger_listener_workflow import _build_run_graph
+
+ nodes: List[Dict[str, Any]] = [
+ _node("wh-1", "webhookTrigger"),
+ _node("agent-1", "aiAgent"),
+ ]
+ edges = [_edge("wh-1", "agent-1")]
+ output_payload = {"method": "POST", "body": '{"hello": "world"}'}
+
+ filtered_nodes, filtered_edges = _build_run_graph(
+ trigger_node_id="wh-1",
+ trigger_output=output_payload,
+ nodes=nodes,
+ edges=edges,
+ )
+
+ wh = next(n for n in filtered_nodes if n["id"] == "wh-1")
+ assert wh["_pre_executed"] is True
+ assert wh["_trigger_output"] == output_payload
+ # Downstream included.
+ ids = {n["id"] for n in filtered_nodes}
+ assert ids == {"wh-1", "agent-1"}
+ assert len(filtered_edges) == 1
+
+ def test_sibling_triggers_excluded_from_run_graph(self):
+ """Mirrors DeploymentManager._get_downstream_nodes: trigger nodes
+ are independent event listeners, NOT pulled into another trigger's
+ execution run. Each trigger fires its own run when its own event
+ arrives — n8n pattern. The defensive ``_pre_executed=not_triggered``
+ branch in MachinaWorkflow only fires for the edge case where a
+ non-firing trigger somehow lands in the filtered graph; that
+ doesn't happen under the canonical downstream-collection."""
+ from services.temporal.trigger_listener_workflow import _build_run_graph
+
+ nodes = [
+ _node("wh-1", "webhookTrigger"),
+ _node("wh-2", "webhookTrigger"),
+ _node("agent-1", "aiAgent"),
+ ]
+ # Both triggers feed the same agent. wh-1 fires; wh-2 is a sibling.
+ edges = [_edge("wh-1", "agent-1"), _edge("wh-2", "agent-1")]
+
+ filtered_nodes, _ = _build_run_graph(
+ trigger_node_id="wh-1",
+ trigger_output={"path": "/hook"},
+ nodes=nodes,
+ edges=edges,
+ )
+
+ ids = {n["id"] for n in filtered_nodes}
+ # wh-2 is NOT in the filtered run.
+ assert ids == {"wh-1", "agent-1"}
+
+ def test_cross_graph_nodes_excluded(self):
+ from services.temporal.trigger_listener_workflow import _build_run_graph
+
+ # wh-1 → agent-1; orphan-1 → orphan-2 (separate component).
+ nodes = [
+ _node("wh-1", "webhookTrigger"),
+ _node("agent-1", "aiAgent"),
+ _node("orphan-1", "aiAgent"),
+ _node("orphan-2", "console"),
+ ]
+ edges = [
+ _edge("wh-1", "agent-1"),
+ _edge("orphan-1", "orphan-2"),
+ ]
+
+ filtered_nodes, filtered_edges = _build_run_graph(
+ trigger_node_id="wh-1",
+ trigger_output={},
+ nodes=nodes,
+ edges=edges,
+ )
+
+ ids = {n["id"] for n in filtered_nodes}
+ assert ids == {"wh-1", "agent-1"}
+ # Orphan edge dropped.
+ for edge in filtered_edges:
+ assert edge["source"] in ids
+ assert edge["target"] in ids
+
+ def test_config_node_included_via_input_memory_handle(self):
+ from services.temporal.trigger_listener_workflow import _build_run_graph
+
+ # Memory node connects to agent via input-memory; must be pulled
+ # in despite being upstream of the trigger.
+ nodes = [
+ _node("wh-1", "webhookTrigger"),
+ _node("agent-1", "aiAgent"),
+ _node("mem-1", "simpleMemory"),
+ ]
+ edges = [
+ _edge("wh-1", "agent-1"),
+ _edge("mem-1", "agent-1", target_handle="input-memory"),
+ ]
+
+ filtered_nodes, _ = _build_run_graph(
+ trigger_node_id="wh-1",
+ trigger_output={},
+ nodes=nodes,
+ edges=edges,
+ )
+
+ assert {n["id"] for n in filtered_nodes} == {"wh-1", "agent-1", "mem-1"}
+
+ def test_stops_at_downstream_trigger_nodes(self):
+ """Downstream collection stops at trigger nodes (n8n pattern):
+ each trigger is an independent event listener. taskTrigger fires
+ when its own event (``task_completed``) arrives; collection
+ from the upstream webhook trigger doesn't traverse through it.
+ Children of the downstream trigger don't appear in this run's
+ filtered graph either."""
+ from services.temporal.trigger_listener_workflow import _build_run_graph
+
+ nodes = [
+ _node("wh-1", "webhookTrigger"),
+ _node("agent-1", "aiAgent"),
+ _node("task-1", "taskTrigger"),
+ _node("downstream-of-task", "console"),
+ ]
+ edges = [
+ _edge("wh-1", "agent-1"),
+ _edge("agent-1", "task-1"),
+ _edge("task-1", "downstream-of-task"),
+ ]
+
+ filtered_nodes, _ = _build_run_graph(
+ trigger_node_id="wh-1",
+ trigger_output={},
+ nodes=nodes,
+ edges=edges,
+ )
+
+ ids = {n["id"] for n in filtered_nodes}
+ # Collection stops at task-1 (downstream trigger).
+ assert ids == {"wh-1", "agent-1"}
+
+
+# ---------------------------------------------------------------------------
+# C1d — _spawn_child_run uses stable workflow ID derived from event.id
+# ---------------------------------------------------------------------------
+
+
+class TestSpawnChildRun:
+ """Child workflows are started with deterministic IDs so server-side
+ dedup catches producer retries across listener restarts."""
+
+ @pytest.mark.asyncio
+ async def test_child_id_derived_from_event_id(self, monkeypatch):
+ from services.temporal import trigger_listener_workflow as tlw
+
+ recorded: List[Dict[str, Any]] = []
+
+ async def fake_start_child_workflow(workflow_name, **kwargs):
+ recorded.append({"name": workflow_name, **kwargs})
+ return MagicMock()
+
+ from temporalio import workflow as temporal_workflow
+
+ monkeypatch.setattr(
+ temporal_workflow,
+ "start_child_workflow",
+ fake_start_child_workflow,
+ )
+
+ wf = tlw.TriggerListenerWorkflow()
+ event = {
+ "id": "evt-42",
+ "type": "com.machinaos.webhook.received",
+ "data": {"path": "/hook", "method": "POST"},
+ }
+ listener_data = {
+ "workflow_id": "wf-abc",
+ "trigger_node_id": "wh-1",
+ "node_type": "webhookTrigger",
+ "event_type": "com.machinaos.webhook.received",
+ "filter_params": {},
+ "nodes": [_node("wh-1", "webhookTrigger"), _node("agent-1", "aiAgent")],
+ "edges": [_edge("wh-1", "agent-1")],
+ "session_id": "sess-1",
+ }
+
+ await wf._spawn_child_run(event, listener_data)
+
+ assert len(recorded) == 1
+ call = recorded[0]
+ assert call["name"] == "MachinaWorkflow"
+ assert call["id"] == "run-wf-abc-evt-42"
+ # Trigger output carries both the user data AND the envelope for
+ # downstream introspection.
+ child_args = call["args"][0]
+ wh = next(n for n in child_args["nodes"] if n["id"] == "wh-1")
+ assert wh["_pre_executed"] is True
+ assert wh["_trigger_output"]["path"] == "/hook"
+ assert wh["_trigger_output"]["_event_envelope"]["id"] == "evt-42"
+
+ @pytest.mark.asyncio
+ async def test_spawn_failure_does_not_kill_listener(self, monkeypatch):
+ """An exception inside _spawn_child_run propagates back to the
+ main loop, which catches it — the listener stays alive. This
+ test asserts the exception surfaces (the loop's catch is in
+ run(), not in _spawn_child_run)."""
+ from services.temporal import trigger_listener_workflow as tlw
+
+ async def boom(*args, **kwargs):
+ raise RuntimeError("temporal unreachable")
+
+ from temporalio import workflow as temporal_workflow
+
+ monkeypatch.setattr(
+ temporal_workflow,
+ "start_child_workflow",
+ boom,
+ )
+
+ wf = tlw.TriggerListenerWorkflow()
+ event = {"id": "evt-1", "type": "x", "data": {}}
+ listener_data = {
+ "workflow_id": "wf-1",
+ "trigger_node_id": "wh-1",
+ "nodes": [_node("wh-1", "webhookTrigger")],
+ "edges": [],
+ }
+
+ with pytest.raises(RuntimeError, match="temporal unreachable"):
+ await wf._spawn_child_run(event, listener_data)