Skip to content

Self-improving AI Employees for everyone

feat(temporal): PollingTriggerWorkflow canary on googleGmailReceive (Wave 12 C2)

trohitg00dbf10fe087
diff --git a/docs-internal/event_framework.md b/docs-internal/event_framework.md
index 634f7e23..b6e9921c 100644
--- a/docs-internal/event_framework.md
+++ b/docs-internal/event_framework.md
@@ -16,6 +16,7 @@ phase plan lives in `~/.claude/plans/properly-fix-the-tech-dreamy-tarjan.md`.
| 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 (chat / task / telegram / whatsapp) — plugin-self-registered via `canary_registry` | ✅ shipped 2026-05-14 |
+| C2 canary (googleGmailReceive) — `PollingTriggerWorkflow` + `as_poll_activity` per-cycle activity | ✅ shipped 2026-05-15 (10 tests) |
| C2 — Polling triggers as long-lived workflows | ⏳ pending |
| C3 — APScheduler → Temporal Schedules | ⏳ pending |
| C4 — Close cross-plugin `_service` reaches (4 sites) | ⏳ pending |
diff --git a/server/nodes/google/__init__.py b/server/nodes/google/__init__.py
index 7207b20f..32a95ddd 100644
--- a/server/nodes/google/__init__.py
+++ b/server/nodes/google/__init__.py
@@ -24,6 +24,7 @@ the FastAPI app pick up the plugin's surface without ever importing
this module by name.
"""
+from services.deployment.canary_registry import register_canary_trigger_type
from services.event_waiter import register_filter_builder
from services.status_broadcaster import register_service_refresh
from services.ws_handler_registry import (
@@ -56,3 +57,12 @@ register_option_loader("gmailLabels", load_gmail_labels)
register_option_loader("googleCalendarList", load_calendar_list)
register_option_loader("googleDriveFolders", load_drive_folders)
register_option_loader("googleTasklists", load_tasklists)
+
+# Wave 12 C2: opt googleGmailReceive into the PollingTriggerWorkflow
+# consumer path. DeploymentManager detects the PollingTriggerNode
+# subclass and routes to PollingTriggerWorkflow (vs the push-side
+# TriggerListenerWorkflow) automatically. Producer side: the per-cycle
+# Temporal activity is emitted by GmailReceiveNode.as_poll_activity()
+# and registered via collect_polling_activities() in the worker. See
+# services/deployment/canary_registry.py.
+register_canary_trigger_type("googleGmailReceive")
diff --git a/server/services/deployment/manager.py b/server/services/deployment/manager.py
index def5f979..da43454f 100644
--- a/server/services/deployment/manager.py
+++ b/server/services/deployment/manager.py
@@ -24,9 +24,22 @@ if TYPE_CHECKING:
logger = get_logger(__name__)
-# Listener Temporal workflow type-name. Used both for ``start_workflow``
-# and as the Visibility filter for cancellation discovery.
-_LISTENER_WORKFLOW_TYPE = "TriggerListenerWorkflow"
+# Listener Temporal workflow type-names. Used both for ``start_workflow``
+# and as the Visibility filter for cancellation discovery. Push-based
+# triggers (webhook, chat, task, telegram, whatsapp) use the
+# signal-driven listener; polling triggers (gmail, twitter) use the
+# workflow.sleep-driven listener (Wave 12 C2). Cancel queries both via
+# an OR clause so deployment cancel reaches every canary listener
+# without per-type code.
+_PUSH_LISTENER_WORKFLOW_TYPE = "TriggerListenerWorkflow"
+_POLLING_LISTENER_WORKFLOW_TYPE = "PollingTriggerWorkflow"
+_LISTENER_WORKFLOW_TYPES = (
+ _PUSH_LISTENER_WORKFLOW_TYPE,
+ _POLLING_LISTENER_WORKFLOW_TYPE,
+)
+# Kept for back-compat with any reader that still imports the old
+# single-type constant. Equals the push workflow name.
+_LISTENER_WORKFLOW_TYPE = _PUSH_LISTENER_WORKFLOW_TYPE
# Wave 12 C1 canary: which trigger types route to TriggerListenerWorkflow
# instead of the legacy in-process collector/processor is owned by the
@@ -558,13 +571,37 @@ class DeploymentManager:
return bool(Settings().event_framework_enabled)
+ @staticmethod
+ def _is_polling_trigger_class(node_type: str) -> bool:
+ """True iff ``node_type`` resolves to a
+ :class:`services.plugin.PollingTriggerNode` subclass.
+
+ Used by :meth:`_start_canary_listener` to dispatch between the
+ push-driven :class:`TriggerListenerWorkflow` and the poll-driven
+ :class:`PollingTriggerWorkflow`. Lazy imports the registry +
+ base class to keep the manager free of top-level cycles.
+ """
+ try:
+ from services.node_registry import get_node_class
+ from services.plugin import PollingTriggerNode
+ except Exception: # noqa: BLE001
+ return False
+ cls = get_node_class(node_type)
+ return isinstance(cls, type) and issubclass(cls, PollingTriggerNode)
+
async def _start_canary_listener(
self,
node: Dict,
workflow_id: str,
params: Dict,
) -> Optional[str]:
- """Start a TriggerListenerWorkflow for a canary trigger.
+ """Start the canary listener workflow for a trigger.
+
+ Dispatches by plugin class:
+ - :class:`PollingTriggerNode` subclasses → :class:`PollingTriggerWorkflow`
+ (Wave 12 C2 — workflow.sleep loop + per-cycle activity).
+ - Everything else → :class:`TriggerListenerWorkflow`
+ (Wave 12 C1 — signal-driven wait_condition).
Returns the Temporal listener workflow_id on success, or
``None`` if the Temporal client isn't connected (caller falls
@@ -603,8 +640,44 @@ class DeploymentManager:
config = event_waiter.get_trigger_config(node_type)
event_type = config.event_type if config else f"unknown_{node_type}"
+ # Pick workflow type by plugin class. EventTriggerKind picks up
+ # the "polling" classification for ops dashboards independent
+ # of the per-plugin kind (gmail / twitter / ...).
+ is_polling = self._is_polling_trigger_class(node_type)
+ workflow_type_name = (
+ _POLLING_LISTENER_WORKFLOW_TYPE if is_polling
+ else _PUSH_LISTENER_WORKFLOW_TYPE
+ )
+ trigger_kind = "polling" if is_polling else self._trigger_kind_for(node_type)
+
listener_id = self._listener_workflow_id(workflow_id, node_id)
+ # Common payload shape for both workflow types (signal-driven
+ # TriggerListenerWorkflow ignores poll-specific fields like
+ # ``version`` / ``seen_ids``; polling workflow reads them).
+ listener_args: Dict[str, Any] = {
+ "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,
+ }
+ if is_polling:
+ # ``version`` feeds the polling workflow's activity-name
+ # construction (``poll.{type}.v{version}``). Pulled from the
+ # plugin class — single source of truth.
+ from services.node_registry import get_node_class
+
+ cls = get_node_class(node_type)
+ listener_args["version"] = getattr(cls, "version", 1) if cls else 1
+ # First start: empty seen_ids; the workflow runs a
+ # baseline-only cycle to establish the seen set without
+ # emitting events.
+ listener_args["seen_ids"] = []
+
# 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")
@@ -613,17 +686,8 @@ class DeploymentManager:
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,
- }],
+ workflow_type_name,
+ args=[listener_args],
id=listener_id,
task_queue="machina-tasks",
id_conflict_policy=WorkflowIDConflictPolicy.USE_EXISTING,
@@ -631,7 +695,7 @@ class DeploymentManager:
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, self._trigger_kind_for(node_type)),
+ SearchAttributePair(event_trigger_kind_key, trigger_kind),
]),
)
@@ -676,9 +740,13 @@ class DeploymentManager:
return 0
# Visibility List Filter query — operators per docs.temporal.io/list-filter.
+ # Match BOTH workflow types via ``WorkflowType IN (...)`` so push
+ # (TriggerListenerWorkflow) and polling (PollingTriggerWorkflow)
+ # listeners drain in one sweep.
+ wf_types_in = ", ".join(f"'{t}'" for t in _LISTENER_WORKFLOW_TYPES)
query = (
f"EventWorkflowId='{workflow_id}' "
- f"AND WorkflowType='{_LISTENER_WORKFLOW_TYPE}' "
+ f"AND WorkflowType IN ({wf_types_in}) "
f"AND ExecutionStatus='Running'"
)
diff --git a/server/services/plugin/polling.py b/server/services/plugin/polling.py
index 7575b2b4..2dcb00b2 100644
--- a/server/services/plugin/polling.py
+++ b/server/services/plugin/polling.py
@@ -166,6 +166,104 @@ class PollingTriggerNode(TriggerNode, abstract=True):
value = self.default_poll_interval
return max(lo, min(hi, value))
+ # ---- Wave 12 C2: per-cycle Temporal activity --------------------------
+ #
+ # The asyncio coroutine version above feeds the legacy
+ # ``setup_polling_trigger`` collector/processor task pair (dies on
+ # FastAPI restart). The Temporal-durable version below — yielded by
+ # :meth:`as_poll_activity` — does ONE cycle and returns events,
+ # called per ``workflow.sleep`` tick in
+ # :class:`services.temporal.polling_trigger_workflow.PollingTriggerWorkflow`.
+ # The seen-id baseline survives via workflow state (carried across
+ # ``continueAsNew``) rather than living inside the asyncio task.
+
+ @classmethod
+ def as_poll_activity(cls):
+ """Return a ``@activity.defn`` wrapping one poll cycle.
+
+ Stable activity name: ``poll.{type}.v{version}``.
+
+ Activity payload (in)::
+
+ {
+ "node_id": str,
+ "params": Dict[str, Any],
+ "seen_ids": List[str], # provider-side IDs from prior cycle
+ "baseline_only": bool, # True on the first call after start
+ }
+
+ Activity result (out)::
+
+ {
+ "events": List[Dict], # NEW event payloads this cycle
+ "seen_ids": List[str], # union of prior seen + current
+ }
+
+ Determinism: every operation runs inside the activity (network
+ I/O, mutable state) — the workflow body only sees the serialised
+ result so replay stays deterministic. Per-cycle errors raise
+ out of the activity; the workflow's ``RetryPolicy`` / try-except
+ owns retry semantics.
+ """
+ from temporalio import activity
+
+ activity_name = f"poll.{cls.type}.v{cls.version}"
+
+ @activity.defn(name=activity_name)
+ async def _poll_cycle_activity(payload: Dict[str, Any]) -> Dict[str, Any]:
+ node_id = payload.get("node_id", "")
+ params = payload.get("params", {}) or {}
+ prior_seen: Set[str] = set(payload.get("seen_ids") or [])
+ baseline_only = bool(payload.get("baseline_only"))
+
+ instance = cls()
+ try:
+ service = await instance.setup_service(params)
+ except Exception as exc: # noqa: BLE001
+ logger.error(
+ "Polling activity setup failed",
+ node_id=node_id, node_type=cls.type, error=str(exc),
+ )
+ raise
+
+ current = await instance.fetch_ids(service, params)
+
+ if baseline_only:
+ # First call after workflow start: establish the seen
+ # baseline without emitting anything. Matches the
+ # pre-Temporal collector's baseline pass.
+ return {"events": [], "seen_ids": list(current)}
+
+ new_ids = current - prior_seen
+ events: list[Dict[str, Any]] = []
+ for msg_id in new_ids:
+ try:
+ detail = await instance.fetch_detail(service, msg_id, params)
+ except Exception as exc: # noqa: BLE001
+ logger.warning(
+ "Polling activity fetch_detail failed; skipping id",
+ node_id=node_id, node_type=cls.type,
+ msg_id=msg_id, error=str(exc),
+ )
+ continue
+ # The workflow needs a stable event.id for cross-cycle
+ # dedup. Fall back to the provider id when fetch_detail
+ # doesn't supply one.
+ if "id" not in detail:
+ detail["id"] = msg_id
+ events.append(detail)
+ # post_emit side effect (e.g. mark-as-read). Failures
+ # MUST NOT block the next emit or kill the cycle —
+ # mirror the legacy coroutine semantics.
+ try:
+ await instance.post_emit(service, msg_id, params)
+ except Exception:
+ pass
+
+ return {"events": events, "seen_ids": list(prior_seen | current)}
+
+ return _poll_cycle_activity
+
def _build_poll_coroutine(
self, node_id: str, params: Dict[str, Any]
) -> Callable[[asyncio.Queue, Callable[[], bool]], Any]:
diff --git a/server/services/temporal/plugin_activities.py b/server/services/temporal/plugin_activities.py
index 684df78b..ed1428d6 100644
--- a/server/services/temporal/plugin_activities.py
+++ b/server/services/temporal/plugin_activities.py
@@ -87,6 +87,37 @@ def collect_plugin_activities_for_queue(task_queue: str) -> List[Callable]:
return collect_plugin_activities(task_queue=task_queue)
+def collect_polling_activities() -> List[Callable]:
+ """Return ``@activity.defn``-decorated per-cycle activities for every
+ :class:`services.plugin.PollingTriggerNode` subclass.
+
+ Wave 12 C2: each polling plugin's
+ :meth:`PollingTriggerNode.as_poll_activity` produces an activity that
+ does ONE poll cycle (vs ``cls.as_activity()`` which does ONE workflow
+ execution). The new :class:`PollingTriggerWorkflow` calls these per
+ ``workflow.sleep`` tick.
+
+ Stable activity name: ``poll.{type}.v{version}``. Registered alongside
+ the regular per-type activities in the Temporal worker.
+ """
+ from services.node_registry import registered_node_classes
+ from services.plugin import PollingTriggerNode
+
+ activities: List[Callable] = []
+ for node_type, cls in registered_node_classes().items():
+ if not isinstance(cls, type) or not issubclass(cls, PollingTriggerNode):
+ continue
+ try:
+ activities.append(cls.as_poll_activity())
+ except Exception as exc: # noqa: BLE001
+ logger.warning(
+ "Failed to build poll activity for %s: %s", node_type, exc,
+ )
+
+ logger.info("Collected %d polling activities", len(activities))
+ return activities
+
+
def distinct_task_queues() -> List[str]:
"""Return every task_queue string declared by any registered plugin.
diff --git a/server/services/temporal/polling_trigger_workflow.py b/server/services/temporal/polling_trigger_workflow.py
new file mode 100644
index 00000000..519f92fc
--- /dev/null
+++ b/server/services/temporal/polling_trigger_workflow.py
@@ -0,0 +1,248 @@
+"""Wave 12 C2: long-lived Temporal workflow for polling triggers.
+
+Closes the durability gap on polling triggers (gmailReceive,
+twitterReceive, …) the same way :class:`TriggerListenerWorkflow`
+closed it for push triggers. Today's polling lives in
+``services/deployment/triggers.py::setup_polling_trigger`` —
+a collector/processor ``asyncio.Task`` pair that dies on FastAPI
+restart, losing the seen-ID baseline and any in-flight cycle.
+
+This workflow owns the poll loop INSIDE Temporal:
+
+- ``workflow.sleep(interval)`` between cycles → replayable, no
+ per-cycle heartbeat overhead, survives worker restarts
+ (per temporal.io/blog/very-long-running-workflows).
+- Per-cycle Temporal activity (``poll.{type}.v{version}``, emitted
+ by :meth:`PollingTriggerNode.as_poll_activity`) does ONE cycle and
+ returns new events + the updated seen-id set.
+- For each new event, spawn a child :class:`MachinaWorkflow` with
+ the trigger pre-executed (same ``_build_run_graph`` helper as
+ the push-trigger listener — single source of truth for run-filter
+ semantics).
+- ``continueAsNew`` every ~16K processed events to keep Event
+ History bounded.
+
+Cross-confirmed pattern with Temporal docs + samples-python:
+- Long-lived workflow with sleep+continueAsNew: temporal.io/blog/
+ very-long-running-workflows
+- Activities for external I/O (Gmail / Twitter API calls): docs.
+ temporal.io/develop/python/core-application#activities
+- ParentClosePolicy.ABANDON for child run workflows so listener
+ cancel never strands in-flight executions
+"""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Any, Dict, List, Set
+
+from temporalio import workflow
+from temporalio.common import WorkflowIDReusePolicy
+from temporalio.workflow import ParentClosePolicy
+
+
+# Same continueAsNew threshold as TriggerListenerWorkflow — keeps Event
+# History under Temporal's soft ceiling. The actual count depends on
+# both cycles AND events spawned per cycle; 16K events ≈ 16K spawn
+# entries + N cycles, well below the 50K guidance.
+_MAX_EVENTS_BEFORE_CONTINUE_AS_NEW = 16_000
+
+# Default poll interval (seconds) if listener_data doesn't supply one.
+# Mirrors PollingTriggerNode.default_poll_interval defaults.
+_DEFAULT_POLL_INTERVAL_S = 60
+
+# Activity timeout: 4× the poll interval gives the activity plenty of
+# headroom for slow Gmail / Twitter responses without hanging forever.
+# Workflow ``RetryPolicy`` (default) handles transient failures.
+_ACTIVITY_TIMEOUT_MULT = 4
+
+
[email protected](name="PollingTriggerWorkflow", sandboxed=False)
+class PollingTriggerWorkflow:
+ """Long-lived polling-trigger workflow.
+
+ Determinism note: all state lives on ``self`` and is reconstructed
+ from Event History on replay. Provider-side ``seen_ids`` (e.g.
+ Gmail message IDs) is the activity's output → workflow state →
+ next activity's input — never mutated mid-workflow. Event-id dedup
+ set drains on ``continueAsNew`` (intentional; events arriving in
+ the new run are by definition not duplicates of the prior run).
+ """
+
+ def __init__(self) -> None:
+ self._seen_event_ids: Set[str] = set()
+ self._processed_count: int = 0
+
+ @workflow.run
+ async def run(self, listener_data: Dict[str, Any]) -> Dict[str, Any]:
+ """Poll loop body.
+
+ ``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. "googleGmailReceive"
+ "version": int, # plugin class version (for activity name)
+ "filter_params": Dict, # plugin params (poll_interval etc.)
+ "nodes": List[Dict], # full deployment graph snapshot
+ "edges": List[Dict],
+ "session_id": str,
+ "tenant_id": Optional[str],
+ "seen_ids": List[str], # carried across continueAsNew; empty on first start
+ }
+
+ Returns when ``continueAsNew`` fires. Deployment cancel uses
+ a graceful ``workflow.cancel()`` — the loop's
+ ``CancelledError`` propagates and the workflow ends.
+ """
+ node_type = listener_data["node_type"]
+ version = listener_data.get("version", 1)
+ activity_name = f"poll.{node_type}.v{version}"
+
+ params = listener_data.get("filter_params", {}) or {}
+ poll_interval = int(params.get("poll_interval") or _DEFAULT_POLL_INTERVAL_S)
+ activity_timeout_s = max(30, poll_interval * _ACTIVITY_TIMEOUT_MULT)
+
+ # Carry seen_ids across continueAsNew. First-start payload has
+ # ``seen_ids=[]`` and the first activity call is baseline-only.
+ seen_ids: Set[str] = set(listener_data.get("seen_ids") or [])
+ is_baseline = not seen_ids
+
+ workflow.logger.info(
+ f"PollingTriggerWorkflow started: workflow_id={listener_data.get('workflow_id')} "
+ f"node={listener_data.get('trigger_node_id')} type={node_type} "
+ f"interval={poll_interval}s baseline={is_baseline}"
+ )
+
+ while True:
+ if is_baseline:
+ # Establish seen baseline immediately on first run so we
+ # don't re-emit items the user has had since before deploy.
+ is_baseline = False
+ cycle_payload = {
+ "node_id": listener_data["trigger_node_id"],
+ "params": params,
+ "seen_ids": [],
+ "baseline_only": True,
+ }
+ else:
+ await workflow.sleep(timedelta(seconds=poll_interval))
+ cycle_payload = {
+ "node_id": listener_data["trigger_node_id"],
+ "params": params,
+ "seen_ids": list(seen_ids),
+ "baseline_only": False,
+ }
+
+ try:
+ result = await workflow.execute_activity(
+ activity_name,
+ cycle_payload,
+ start_to_close_timeout=timedelta(seconds=activity_timeout_s),
+ )
+ except Exception as exc: # noqa: BLE001
+ # Activity exhausted its RetryPolicy. Log + continue —
+ # don't terminate the listener over one bad cycle.
+ # Workflow Event History records the failure for ops.
+ workflow.logger.error(
+ f"PollingTriggerWorkflow cycle failed (will retry next interval): {exc}"
+ )
+ continue
+
+ seen_ids = set(result.get("seen_ids") or [])
+ events = result.get("events") or []
+
+ for event in events:
+ event_id = event.get("id")
+ if not event_id or event_id in self._seen_event_ids:
+ continue
+ self._seen_event_ids.add(event_id)
+ try:
+ await self._spawn_child_run(event, listener_data)
+ except Exception as spawn_exc: # noqa: BLE001
+ # Per-event spawn failure logged; subsequent events
+ # still try. Same isolation contract as the push
+ # listener.
+ workflow.logger.error(
+ f"PollingTriggerWorkflow spawn failed for event.id={event_id}: {spawn_exc}"
+ )
+ self._processed_count += 1
+
+ if self._processed_count >= _MAX_EVENTS_BEFORE_CONTINUE_AS_NEW:
+ workflow.logger.info(
+ f"PollingTriggerWorkflow continue_as_new: processed={self._processed_count}"
+ )
+ # Carry seen_ids forward so the new run doesn't re-emit
+ # what's already been seen by the provider.
+ listener_data["seen_ids"] = list(seen_ids)
+ workflow.continue_as_new(listener_data)
+
+ async def _spawn_child_run(
+ self,
+ event: Dict[str, Any],
+ listener_data: Dict[str, Any],
+ ) -> None:
+ """Start a child :class:`MachinaWorkflow` with the trigger
+ pre-executed against this event payload.
+
+ Reuses ``_build_run_graph`` from
+ :mod:`services.temporal.trigger_listener_workflow` so the
+ filtered-graph semantics (n8n stop-at-trigger downstream walk,
+ config nodes via input handles, toolkit sub-nodes, agent tool
+ nodes) stay single-source. Mirrors
+ :meth:`TriggerListenerWorkflow._spawn_child_run` exactly.
+ """
+ from services.temporal.trigger_listener_workflow import _build_run_graph
+
+ 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")
+
+ # Polling activity returns plugin-native payload dicts (Gmail
+ # email envelope, Twitter tweet payload). For Temporal-side
+ # introspection we pass the dict as both the trigger output
+ # AND nest it under ``_event_envelope`` so downstream nodes
+ # can route off the original shape — matches the push-listener
+ # contract.
+ trigger_output = {**event, "_event_envelope": event}
+
+ filtered_nodes, filtered_edges = _build_run_graph(
+ trigger_node_id=trigger_node_id,
+ trigger_output=trigger_output,
+ nodes=nodes,
+ edges=edges,
+ )
+
+ # Lazy fallback to workflow.uuid4() only when event.id is missing —
+ # eager-eval default-arg form would trip _NotInWorkflowEventLoopError
+ # in unit tests + waste entropy on the hot path.
+ 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"PollingTriggerWorkflow spawned child run: child_id={child_id} "
+ f"event.id={event.get('id')}"
+ )
+
+
+__all__ = ["PollingTriggerWorkflow"]
diff --git a/server/services/temporal/worker.py b/server/services/temporal/worker.py
index 37d4fed0..9c8641ac 100644
--- a/server/services/temporal/worker.py
+++ b/server/services/temporal/worker.py
@@ -28,6 +28,7 @@ from temporalio.worker import Worker
from core.logging import get_logger
from .workflow import MachinaWorkflow
from .trigger_listener_workflow import TriggerListenerWorkflow
+from .polling_trigger_workflow import PollingTriggerWorkflow
from .activities import (
NodeExecutionActivities,
create_shared_session,
@@ -132,20 +133,30 @@ class TemporalWorkerManager:
# orchestrator schedules AgentWorkflow as a child workflow
# for the 15 migrating agent types when
# ``temporal_agent_workflow_enabled`` is on.
- from services.temporal.plugin_activities import collect_plugin_activities
+ from services.temporal.plugin_activities import (
+ collect_plugin_activities,
+ collect_polling_activities,
+ )
from services.temporal.agent_activities import collect_agent_activities
from services.temporal.agent_workflow import AgentWorkflow
per_type = collect_plugin_activities() # no queue filter; all plugins
agent_activities = collect_agent_activities()
+ polling_activities = collect_polling_activities()
self._worker = Worker(
self.client,
task_queue=self.task_queue,
- workflows=[MachinaWorkflow, AgentWorkflow, TriggerListenerWorkflow],
+ workflows=[
+ MachinaWorkflow,
+ AgentWorkflow,
+ TriggerListenerWorkflow,
+ PollingTriggerWorkflow,
+ ],
activities=[
self._activities.execute_node_activity,
*per_type,
*agent_activities,
+ *polling_activities,
],
# Allow concurrent activity execution for parallel branches
max_concurrent_activities=self.pool_size,
@@ -368,7 +379,11 @@ async def run_standalone_worker(
worker = Worker(
client,
task_queue=task_queue,
- workflows=[MachinaWorkflow, TriggerListenerWorkflow],
+ workflows=[
+ MachinaWorkflow,
+ TriggerListenerWorkflow,
+ PollingTriggerWorkflow,
+ ],
activities=[activities.execute_node_activity], # Pass bound method
max_concurrent_activities=pool_size,
max_concurrent_workflow_tasks=10,
@@ -407,7 +422,11 @@ async def create_worker(
return Worker(
client,
task_queue=task_queue,
- workflows=[MachinaWorkflow, TriggerListenerWorkflow],
+ workflows=[
+ MachinaWorkflow,
+ TriggerListenerWorkflow,
+ PollingTriggerWorkflow,
+ ],
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
index cab3ba41..50105488 100644
--- a/server/tests/test_deployment_canary_listener.py
+++ b/server/tests/test_deployment_canary_listener.py
@@ -414,11 +414,17 @@ class TestCancelCanaryListeners:
cancelled = await mgr._cancel_canary_listeners("wf-1")
- # Query shape: EventWorkflowId + WorkflowType + ExecutionStatus.
+ # Query shape: EventWorkflowId + WorkflowType IN (...) +
+ # ExecutionStatus. The IN clause covers both push
+ # (TriggerListenerWorkflow) and polling (PollingTriggerWorkflow)
+ # listener workflow types since Wave 12 C2 — deployment cancel
+ # drains both in one sweep.
assert len(recorded_queries) == 1
q = recorded_queries[0]
assert "EventWorkflowId='wf-1'" in q
- assert "WorkflowType='TriggerListenerWorkflow'" in q
+ assert "'TriggerListenerWorkflow'" in q
+ assert "'PollingTriggerWorkflow'" in q
+ assert "WorkflowType IN" in q
assert "ExecutionStatus='Running'" in q
assert cancelled == 2
diff --git a/server/tests/test_polling_trigger_workflow.py b/server/tests/test_polling_trigger_workflow.py
new file mode 100644
index 00000000..7082baa6
--- /dev/null
+++ b/server/tests/test_polling_trigger_workflow.py
@@ -0,0 +1,438 @@
+"""Wave 12 C2: tests for :class:`PollingTriggerWorkflow` + the
+per-plugin poll-activity generator + DeploymentManager polling-vs-push
+routing.
+
+Unit-style — no live Temporal cluster needed. ``workflow.logger`` /
+``workflow.sleep`` / ``workflow.execute_activity`` /
+``workflow.start_child_workflow`` are patched per-test so the workflow
+body runs synchronously.
+
+Covered invariants:
+
+C2a — :meth:`PollingTriggerNode.as_poll_activity` wraps the four hooks
+ (``setup_service`` / ``fetch_ids`` / ``fetch_detail`` / ``post_emit``)
+ into one @activity.defn that does ONE cycle and returns
+ ``{events, seen_ids}``.
+
+C2b — Baseline-only call returns no events + the current seen set.
+
+C2c — Subsequent call returns only the diff (new IDs) as detail
+ payloads; each carries an ``id`` for dedup.
+
+C2d — :class:`PollingTriggerWorkflow` runs baseline first, then loops:
+ sleep → execute_activity → spawn child per new event. Dedup via
+ ``_seen_event_ids``. ``continueAsNew`` at the configured cap.
+
+C2e — :meth:`DeploymentManager._is_polling_trigger_class` returns True
+ iff the node_type resolves to a PollingTriggerNode subclass.
+
+C2f — :func:`collect_polling_activities` only yields activities for
+ PollingTriggerNode subclasses (not regular nodes).
+"""
+
+from __future__ import annotations
+
+import sys
+import types
+from typing import Any, Dict, List, Set
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+
+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 — patch it out for unit tests."""
+ from temporalio import workflow as temporal_workflow
+
+ monkeypatch.setattr(temporal_workflow, "logger", MagicMock())
+
+
+# ---------------------------------------------------------------------------
+# C2a/b/c — as_poll_activity wraps the hooks correctly
+# ---------------------------------------------------------------------------
+
+
+class _FakeService:
+ """Stand-in for an SDK handle so we can verify hook-flow plumbing."""
+
+ def __init__(self):
+ self.detail_calls: List[str] = []
+ self.post_emit_calls: List[str] = []
+
+
+def _make_fake_polling_class(
+ cls_type: str,
+ *,
+ current_ids: Set[str],
+ detail_payload_fn=None,
+ fail_on_post_emit: bool = False,
+):
+ """Build a PollingTriggerNode subclass with override-able hooks.
+
+ Keeps the class definition local to each test so global registry
+ state is clean (the parent's __init_subclass__ won't auto-register
+ because we pass abstract=False but the class is never imported
+ outside the test).
+ """
+ from services.plugin import PollingTriggerNode
+
+ class _TestPolling(PollingTriggerNode, abstract=True):
+ type = cls_type
+ display_name = "Test"
+ # abstract=True suppresses registration
+
+ async def setup_service(self, params):
+ return _FakeService()
+
+ async def fetch_ids(self, service, params):
+ return set(current_ids)
+
+ async def fetch_detail(self, service, msg_id, params):
+ service.detail_calls.append(msg_id)
+ if detail_payload_fn is not None:
+ return detail_payload_fn(msg_id)
+ return {"id": msg_id, "payload": f"detail-{msg_id}"}
+
+ async def post_emit(self, service, msg_id, params):
+ service.post_emit_calls.append(msg_id)
+ if fail_on_post_emit:
+ raise RuntimeError("simulated post_emit failure")
+
+ return _TestPolling
+
+
+class TestAsPollActivity:
+ """The classmethod returns a @activity.defn-decorated coroutine that
+ does ONE cycle. Smoke tests bypass the Temporal decorator and call
+ the underlying coroutine via __wrapped__."""
+
+ def _underlying(self, activity_fn):
+ # Temporal wraps the function but keeps the original under
+ # __wrapped__-style attrs depending on SDK version. Pick the
+ # first attribute that points at the original coroutine.
+ for attr in ("__wrapped__", "fn", "_fn"):
+ inner = getattr(activity_fn, attr, None)
+ if inner is not None:
+ return inner
+ return activity_fn
+
+ @pytest.mark.asyncio
+ async def test_baseline_only_returns_no_events(self):
+ cls = _make_fake_polling_class("test.baseline", current_ids={"a", "b", "c"})
+ activity_fn = cls.as_poll_activity()
+ inner = self._underlying(activity_fn)
+
+ result = await inner({
+ "node_id": "n1",
+ "params": {},
+ "seen_ids": [],
+ "baseline_only": True,
+ })
+
+ assert result["events"] == []
+ assert set(result["seen_ids"]) == {"a", "b", "c"}
+
+ @pytest.mark.asyncio
+ async def test_subsequent_cycle_emits_only_new(self):
+ cls = _make_fake_polling_class("test.diff", current_ids={"a", "b", "c", "d"})
+ activity_fn = cls.as_poll_activity()
+ inner = self._underlying(activity_fn)
+
+ result = await inner({
+ "node_id": "n1",
+ "params": {},
+ "seen_ids": ["a", "b"], # b is seen; a/b not new; c/d new
+ "baseline_only": False,
+ })
+
+ new_ids = {e["id"] for e in result["events"]}
+ assert new_ids == {"c", "d"}
+ # seen_ids is the union of prior + current.
+ assert set(result["seen_ids"]) == {"a", "b", "c", "d"}
+
+ @pytest.mark.asyncio
+ async def test_detail_payload_id_fallback(self):
+ """When fetch_detail returns a payload without 'id', the
+ provider id is injected so workflow-level dedup has a key."""
+
+ def detail(msg_id):
+ return {"subject": f"subject-{msg_id}"} # no 'id' field
+
+ cls = _make_fake_polling_class(
+ "test.idfallback",
+ current_ids={"x"},
+ detail_payload_fn=detail,
+ )
+ activity_fn = cls.as_poll_activity()
+ inner = self._underlying(activity_fn)
+
+ result = await inner({
+ "node_id": "n1",
+ "params": {},
+ "seen_ids": [],
+ "baseline_only": False,
+ })
+
+ assert len(result["events"]) == 1
+ assert result["events"][0]["id"] == "x"
+ assert result["events"][0]["subject"] == "subject-x"
+
+ @pytest.mark.asyncio
+ async def test_post_emit_failure_does_not_block_cycle(self):
+ """A post_emit failure (e.g. mark-as-read API timeout) must not
+ prevent subsequent emits or kill the cycle. Mirrors the legacy
+ coroutine semantics."""
+ cls = _make_fake_polling_class(
+ "test.postemit",
+ current_ids={"x", "y"},
+ fail_on_post_emit=True,
+ )
+ activity_fn = cls.as_poll_activity()
+ inner = self._underlying(activity_fn)
+
+ result = await inner({
+ "node_id": "n1",
+ "params": {},
+ "seen_ids": [],
+ "baseline_only": False,
+ })
+
+ # Both events still came through even though post_emit raised.
+ assert {e["id"] for e in result["events"]} == {"x", "y"}
+
+
+# ---------------------------------------------------------------------------
+# C2d — PollingTriggerWorkflow body
+# ---------------------------------------------------------------------------
+
+
+class TestPollingTriggerWorkflowBody:
+ """The workflow's signal/sleep/spawn loop runs deterministically."""
+
+ @pytest.mark.asyncio
+ async def test_baseline_then_dedup_then_spawn(self, monkeypatch):
+ from services.temporal import polling_trigger_workflow as pmod
+
+ # Activity returns scripted responses per call.
+ responses = iter([
+ # Baseline cycle.
+ {"events": [], "seen_ids": ["a", "b"]},
+ # Second cycle: new id 'c'.
+ {"events": [{"id": "c", "payload": "hello"}], "seen_ids": ["a", "b", "c"]},
+ # Third cycle: same id 'c' (dedup test) + new 'd'.
+ {
+ "events": [
+ {"id": "c", "payload": "dup"},
+ {"id": "d", "payload": "fresh"},
+ ],
+ "seen_ids": ["a", "b", "c", "d"],
+ },
+ ])
+
+ from temporalio import workflow as temporal_workflow
+
+ async def fake_execute_activity(name, payload, **kwargs):
+ return next(responses)
+
+ sleep_calls: List[Any] = []
+
+ async def fake_sleep(td):
+ sleep_calls.append(td)
+
+ spawn_calls: List[Dict[str, Any]] = []
+
+ async def fake_start_child(name, **kwargs):
+ spawn_calls.append({"name": name, **kwargs})
+ return MagicMock()
+
+ # Stub `continue_as_new` so we can stop the loop after a fixed
+ # number of cycles instead of running forever. Raising the
+ # SDK's intended exception isn't possible without the
+ # workflow runtime, so we monkeypatch the cap to a value the
+ # test will trip after 2 spawns.
+ monkeypatch.setattr(pmod, "_MAX_EVENTS_BEFORE_CONTINUE_AS_NEW", 2)
+
+ # continueAsNew is a Temporal sentinel — emulate by raising
+ # a unique exception we can catch.
+ class _StopLoop(Exception):
+ pass
+
+ def fake_continue_as_new(arg):
+ raise _StopLoop()
+
+ monkeypatch.setattr(temporal_workflow, "execute_activity", fake_execute_activity)
+ monkeypatch.setattr(temporal_workflow, "sleep", fake_sleep)
+ monkeypatch.setattr(temporal_workflow, "start_child_workflow", fake_start_child)
+ monkeypatch.setattr(temporal_workflow, "continue_as_new", fake_continue_as_new)
+
+ wf = pmod.PollingTriggerWorkflow()
+ listener_data = {
+ "workflow_id": "wf-1",
+ "trigger_node_id": "gm-1",
+ "node_type": "googleGmailReceive",
+ "version": 1,
+ "filter_params": {"poll_interval": 30},
+ "nodes": [
+ {"id": "gm-1", "type": "googleGmailReceive", "data": {}},
+ {"id": "agent-1", "type": "aiAgent", "data": {}},
+ ],
+ "edges": [{"source": "gm-1", "target": "agent-1", "targetHandle": "input-main"}],
+ "session_id": "sess",
+ "seen_ids": [],
+ }
+
+ with pytest.raises(_StopLoop):
+ await wf.run(listener_data)
+
+ # 3 activity calls (baseline + 2 polling cycles).
+ # Sleep skipped on baseline; called before each non-baseline cycle.
+ assert len(sleep_calls) == 2
+
+ # Spawn called for 'c' (cycle 2), 'd' (cycle 3). The duplicate
+ # 'c' in cycle 3 is deduped via _seen_event_ids.
+ spawn_ids = [c["id"] for c in spawn_calls]
+ assert spawn_ids == ["run-wf-1-c", "run-wf-1-d"]
+
+ @pytest.mark.asyncio
+ async def test_cycle_failure_does_not_break_loop(self, monkeypatch):
+ """Activity error is logged + the loop continues."""
+ from services.temporal import polling_trigger_workflow as pmod
+ from temporalio import workflow as temporal_workflow
+
+ call_count = [0]
+
+ async def fake_execute_activity(name, payload, **kwargs):
+ call_count[0] += 1
+ if call_count[0] == 2: # second call fails
+ raise RuntimeError("transient API timeout")
+ if call_count[0] == 1:
+ return {"events": [], "seen_ids": ["a"]} # baseline
+ return {"events": [{"id": f"e{call_count[0]}", "x": 1}], "seen_ids": ["a"]}
+
+ sleep_count = [0]
+
+ async def fake_sleep(td):
+ sleep_count[0] += 1
+ # After 2 sleeps (= 3 cycles total: baseline + good + fail + good),
+ # bail out so the test terminates.
+ if sleep_count[0] >= 3:
+ raise StopAsyncIteration()
+
+ async def fake_start_child(name, **kwargs):
+ return MagicMock()
+
+ monkeypatch.setattr(temporal_workflow, "execute_activity", fake_execute_activity)
+ monkeypatch.setattr(temporal_workflow, "sleep", fake_sleep)
+ monkeypatch.setattr(temporal_workflow, "start_child_workflow", fake_start_child)
+
+ wf = pmod.PollingTriggerWorkflow()
+ listener_data = {
+ "workflow_id": "wf-1",
+ "trigger_node_id": "n",
+ "node_type": "googleGmailReceive",
+ "version": 1,
+ "filter_params": {"poll_interval": 5},
+ "nodes": [{"id": "n", "type": "googleGmailReceive", "data": {}}],
+ "edges": [],
+ "session_id": "s",
+ "seen_ids": [],
+ }
+
+ with pytest.raises(StopAsyncIteration):
+ await wf.run(listener_data)
+
+ # 3 activity calls: baseline (call 1, no sleep) + good (call 2,
+ # after sleep 1) + fail (call 3, after sleep 2 — raises). The
+ # third sleep (between the failed retry and a hypothetical 4th
+ # call) trips StopAsyncIteration and bails the test. What we're
+ # asserting is that the failed cycle DID NOT kill the loop —
+ # the loop kept running past the failure, only ending because
+ # we forced sleep to raise.
+ assert call_count[0] == 3
+
+
+# ---------------------------------------------------------------------------
+# C2e — DeploymentManager polling-vs-push dispatch
+# ---------------------------------------------------------------------------
+
+
+class TestPollingTriggerDispatch:
+ """``_is_polling_trigger_class`` correctly classifies plugin types."""
+
+ def test_polling_trigger_class_detected(self):
+ """googleGmailReceive is a PollingTriggerNode subclass.
+
+ Depends on plugin discovery having happened (other tests in the
+ suite import nodes.google). If the plugin isn't importable in
+ this env, the test xfails.
+ """
+ try:
+ __import__("nodes.google")
+ except ImportError as exc: # pragma: no cover
+ pytest.xfail(f"nodes.google not importable: {exc}")
+
+ from services.deployment.manager import DeploymentManager
+
+ assert DeploymentManager._is_polling_trigger_class("googleGmailReceive") is True
+
+ def test_push_trigger_class_not_polling(self):
+ try:
+ __import__("nodes.trigger.webhook_trigger")
+ except ImportError as exc: # pragma: no cover
+ pytest.xfail(f"webhook_trigger not importable: {exc}")
+
+ from services.deployment.manager import DeploymentManager
+
+ assert DeploymentManager._is_polling_trigger_class("webhookTrigger") is False
+
+ def test_unknown_type_is_not_polling(self):
+ from services.deployment.manager import DeploymentManager
+
+ assert DeploymentManager._is_polling_trigger_class("totally-fake-type") is False
+
+
+# ---------------------------------------------------------------------------
+# C2f — collect_polling_activities only walks polling subclasses
+# ---------------------------------------------------------------------------
+
+
+class TestCollectPollingActivities:
+ """The collector emits activities ONLY for PollingTriggerNode
+ subclasses. Regular plugin nodes (ActionNode / ToolNode / push
+ TriggerNode) don't appear in the result."""
+
+ def test_collects_only_polling_nodes(self):
+ try:
+ __import__("nodes.google")
+ __import__("nodes.trigger.webhook_trigger")
+ except ImportError as exc: # pragma: no cover
+ pytest.xfail(f"plugin imports failed: {exc}")
+
+ from services.temporal.plugin_activities import collect_polling_activities
+
+ activities = collect_polling_activities()
+ # Activity name format: "poll.{type}.v{version}"
+ names = {getattr(a, "__temporal_activity_definition", None) and
+ getattr(a, "__temporal_activity_definition").name
+ or getattr(a, "_name", None) for a in activities}
+ # We can't always extract the activity name (Temporal stores
+ # it on a metadata attribute that varies by SDK version) — at
+ # minimum assert the gmail polling activity is present by
+ # inspecting any name-like attribute.
+ flat = " ".join(str(n) for n in names)
+ assert "poll.googleGmailReceive" in flat or any(
+ "googleGmailReceive" in str(n) for n in names
+ ), (
+ "collect_polling_activities() should include the gmail "
+ f"polling activity. Got names: {names}"
+ )