Skip to content

Self-improving AI Employees for everyone

refactor(events): remove dead WorkflowEvent.message + reclassify connection_status

trohitgc2d49af04325
diff --git a/docs-internal/plugin_authoring_rfc.md b/docs-internal/plugin_authoring_rfc.md
index 4b0cf169..5eef3726 100644
--- a/docs-internal/plugin_authoring_rfc.md
+++ b/docs-internal/plugin_authoring_rfc.md
@@ -167,11 +167,14 @@ A new plugin in group `X` checks `nodes/X/_base.py` for a domain base first; inh
**Definition — plugin-specific vs cross-cutting:**
-A factory is **plugin-specific** if its `type` string names a single plugin (`com.machinaos.telegram.message.received`, `com.machinaos.stripe.payment.succeeded`, `com.machinaos.whatsapp.group.joined`). These move to `_events.py` in the plugin folder.
+A factory is **plugin-specific** if its `type` string names a single plugin AND its payload shape differs from peers in the same domain (`com.machinaos.telegram.message.received` carries `chat_id`; `com.machinaos.whatsapp.message.received` carries `phone_number` + `group_jid`). These belong in `_events.py` in the plugin folder.
-A factory is **cross-cutting** if its `type` follows a shape parameterized by plugin name and uses identical payload structure across plugins: `credential.<action>` (every plugin with credentials), `oauth.completed` (every OAuth plugin), `agent.progress` (every agent), `task.completed` (every delegated task), `workflow.<stage>` (workflow lifecycle), `deployment.snapshot` (deployment state). These stay in central `envelope.py`.
+A factory is **cross-cutting** if either (a) its `type` is the same shape across plugins and the payload is identical, OR (b) its construction is invoked from a single centralized helper that fans out per plugin: `credential.<action>` (every plugin with credentials), `oauth.completed` (every OAuth plugin), `agent.progress` (every agent), `task.completed` (every delegated task), `workflow.<stage>` (workflow lifecycle), `deployment.snapshot` (deployment state), `connection_status` (single `_emit_connection_typed` helper in `StatusBroadcaster` fans out to every plugin status method). These stay in central `envelope.py`.
-The current `WorkflowEvent.message(plugin, direction, data)` and `WorkflowEvent.connection_status(plugin, ...)` factories are borderline — they're parameterized but each plugin emits its own type-string variant (`telegram.message.received`, `whatsapp.message.received`). Phase 5b moves these into per-plugin `_events.py` files because each plugin's message payload differs (Telegram messages have chat_id; WhatsApp messages have phone_number + group_jid) — the central parametrized factory was lossy.
+**Phase 5b audit outcome:**
+- `WorkflowEvent.message(plugin, direction, data)` — **removed** in Phase 5b. Zero callers in the codebase; it was speculative. Plugins that later need to emit message envelopes add a typed factory in their own `_events.py`.
+- `WorkflowEvent.connection_status(plugin, ...)` — **kept** in central `envelope.py`. Single call site (`StatusBroadcaster._emit_connection_typed`); the parametrization is genuinely shared. Moving per-plugin would duplicate the broadcast helper across plugins with no payload divergence.
+- `nodes/stripe/_source.py` hand-constructs `WorkflowEvent(...)` directly. Stripe webhook events keep their producer-side type (`stripe.charge.succeeded` — no `com.machinaos.` prefix since MachinaOs isn't the producer). Already in the plugin folder. No move needed.
### 6.5 Icon and media handling — backend owns, frontend consumes
diff --git a/server/services/events/envelope.py b/server/services/events/envelope.py
index a691a1a5..9290a97b 100644
--- a/server/services/events/envelope.py
+++ b/server/services/events/envelope.py
@@ -154,27 +154,11 @@ class WorkflowEvent(BaseModel):
data=dict(data) if data else {"identifier": identifier},
)
- @classmethod
- def message(
- cls,
- plugin: str,
- direction: Literal["sent", "received"],
- data: Mapping[str, Any],
- ) -> "WorkflowEvent":
- """Plugin-emitted message event (whatsapp / telegram / email
- send + receive). ``subject`` defaults to the chat / sender id
- in the payload (cast to str — Telegram uses numeric chat ids),
- falling back to None."""
- payload = dict(data)
- raw_subject = (
- payload.get("chat_id") or payload.get("from_id") or payload.get("sender")
- )
- return cls(
- source=f"machinaos://nodes/{plugin}",
- type=f"{_TYPE_PREFIX}{plugin}.message.{direction}",
- subject=str(raw_subject) if raw_subject is not None else None,
- data=payload,
- )
+ # ``WorkflowEvent.message(...)`` previously lived here as a
+ # parameterized factory but had zero callers. Plugin-specific
+ # message events belong in ``server/nodes/<plugin>/_events.py``
+ # (see RFC §6.4) since each plugin's message payload diverges
+ # (telegram: chat_id; whatsapp: phone_number + group_jid; ...).
@classmethod
def team_event(
diff --git a/server/tests/test_plugin_self_containment.py b/server/tests/test_plugin_self_containment.py
index f781da6e..a45b5183 100644
--- a/server/tests/test_plugin_self_containment.py
+++ b/server/tests/test_plugin_self_containment.py
@@ -435,12 +435,13 @@ class TestPluginsUseTypedEventFactories:
"""Wave 11.I, milestone Q (locked in U).
Plugins must construct :class:`WorkflowEvent` directly via the
- typed factory classmethods (``WorkflowEvent.credential(...)``,
- ``WorkflowEvent.message(...)``, etc.) -- not via the
- ``WorkflowEvent.from_legacy(event_type, data)`` shim. The shim
- exists so :func:`event_waiter.dispatch` can still accept the legacy
- ``(str, dict)`` form at the framework boundary; lifting it inside
- plugin code defeats the purpose.
+ typed factory classmethods on ``WorkflowEvent`` (cross-cutting:
+ ``credential``, ``connection_status``, ``oauth_completed``, ...) or
+ via plugin-local typed factories in ``_events.py`` (plugin-specific
+ payloads) -- not via the ``WorkflowEvent.from_legacy(event_type,
+ data)`` shim. The shim exists so :func:`event_waiter.dispatch` can
+ still accept the legacy ``(str, dict)`` form at the framework
+ boundary; lifting it inside plugin code defeats the purpose.
"""
@pytest.mark.parametrize("plugin", _MIGRATED_PLUGINS)