Skip to content

Self-improving AI Employees for everyone

feat(events): CloudEvents type prefix + dataschema auto-population

trohitg6c2cedc85c40
diff --git a/client/src/types/__tests__/cloudEvents.test.ts b/client/src/types/__tests__/cloudEvents.test.ts
index 6b64b2b7..a819f9c0 100644
--- a/client/src/types/__tests__/cloudEvents.test.ts
+++ b/client/src/types/__tests__/cloudEvents.test.ts
@@ -68,18 +68,21 @@ describe('WorkflowEvent shape', () => {
specversion: '1.0',
id: 'a1b2c3d4',
source: 'machinaos://services/credentials',
- type: 'credential.api_key.saved',
+ type: 'com.machinaos.credential.api_key.saved',
time: '2026-05-06T12:34:56.789Z',
subject: 'openai',
datacontenttype: 'application/json',
+ dataschema: 'machinaos://schemas/events/credential.api_key.saved.json',
data: { provider: 'openai' },
},
};
const envelope = payload.data as WorkflowEvent<{ provider: string }>;
expect(envelope.specversion).toBe('1.0');
- expect(envelope.type).toBe('credential.api_key.saved');
+ expect(envelope.type).toBe('com.machinaos.credential.api_key.saved');
expect(envelope.subject).toBe('openai');
expect(envelope.data.provider).toBe('openai');
+ // matchesType strips the com.machinaos. prefix, so callers write
+ // patterns without it.
expect(matchesType(envelope, 'credential.api_key.*')).toBe(true);
expect(matchesType(envelope, 'credential.*')).toBe(true);
expect(matchesType(envelope, 'stripe.*')).toBe(false);
diff --git a/client/src/types/cloudEvents.ts b/client/src/types/cloudEvents.ts
index 65f26a00..b80bc23e 100644
--- a/client/src/types/cloudEvents.ts
+++ b/client/src/types/cloudEvents.ts
@@ -14,17 +14,19 @@
* "specversion": "1.0",
* "id": "<uuid>",
* "source": "machinaos://services/credentials",
- * "type": "credential.api_key.saved", // CloudEvents `type`
+ * "type": "com.machinaos.credential.api_key.saved", // reverse-DNS per Primer
* "time": "2026-05-06T12:34:56.789Z",
* "subject": "openai",
* "datacontenttype": "application/json",
+ * "dataschema": "machinaos://schemas/events/credential.api_key.saved.json",
* "data": { "provider": "openai", ... }
* }
* }
*
* Future Wave 12 sources (`stripe.*`, `telegram.*`, `task.*`) will use the
* same envelope. The `matchesType` helper provides server-parity glob
- * dispatch (mirrors `WorkflowEvent.matches_type` in envelope.py).
+ * dispatch (mirrors `WorkflowEvent.matches_type` in envelope.py) — patterns
+ * match against the type with the `com.machinaos.` prefix stripped.
*
* Pytest invariant `server/tests/test_credential_broadcasts.py` locks the
* backend shape; the FE vitest counterpart locks this interface.
@@ -55,24 +57,34 @@ export interface WorkflowEvent<TData = unknown> {
correlation_id?: string | null;
}
+const TYPE_PREFIX = 'com.machinaos.';
+
/**
* Glob-style match on the CloudEvents `type` field.
*
* Mirrors `WorkflowEvent.matches_type` in `server/services/events/envelope.py`.
+ * Patterns are matched against the type with the `com.machinaos.` reverse-DNS
+ * prefix stripped, so callers can write `'credential.api_key.*'` and still
+ * hit `com.machinaos.credential.api_key.saved`. External-producer types
+ * (e.g. `stripe.charge.succeeded` from a Stripe webhook) have no prefix
+ * and match directly.
+ *
* Test parity is locked by `client/src/types/__tests__/cloudEvents.test.ts`
* vs the corresponding pytest cases.
*
- * matchesType(e, 'stripe.charge.succeeded') // exact
- * matchesType(e, 'stripe.charge.*') // prefix glob
- * matchesType(e, 'stripe.*') // prefix glob (1 segment)
+ * matchesType(e, 'stripe.charge.succeeded') // exact (external)
+ * matchesType(e, 'credential.api_key.*') // prefix glob (internal)
+ * matchesType(e, 'agent.*') // prefix glob (1 segment)
* matchesType(e, 'all') // wildcard
* matchesType(e, '') // wildcard
*/
export function matchesType(event: WorkflowEvent, pattern: string): boolean {
if (!pattern || pattern === 'all') return true;
+ const raw = event.type ?? '';
+ const normalized = raw.startsWith(TYPE_PREFIX) ? raw.slice(TYPE_PREFIX.length) : raw;
if (pattern.endsWith('.*')) {
const prefix = pattern.slice(0, -2);
- return event.type === prefix || event.type.startsWith(prefix + '.');
+ return normalized === prefix || normalized.startsWith(prefix + '.');
}
- return event.type === pattern;
+ return normalized === pattern;
}
diff --git a/server/services/events/envelope.py b/server/services/events/envelope.py
index 082299b7..a691a1a5 100644
--- a/server/services/events/envelope.py
+++ b/server/services/events/envelope.py
@@ -2,8 +2,19 @@
Field set mirrors https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md
verbatim so future interop with EventBridge / Knative is a JSON-schema swap.
-The MachinaOs extensions (workflow_id, trigger_node_id, correlation_id)
-ride as CloudEvents extension attributes — fully compliant with the spec.
+The MachinaOs extensions (``workflow_id``, ``trigger_node_id``,
+``correlation_id``) ride as CloudEvents extension attributes. Spec §3.1
+SHOULDs lowercase-alphanumeric extension names; we deliberately keep
+Python snake_case for codebase consistency — the rest of the project
+uses snake_case as a strict naming convention and the readability win
+outweighs the spec recommendation. Internal interop only; if we ever
+publish events to an external CloudEvents broker, an alias layer can
+translate at the producer boundary.
+
+Type strings carry the reverse-DNS prefix ``com.machinaos.`` per
+Primer guidance. ``dataschema`` is auto-populated from ``type`` so
+every typed factory produces a schema URI the consumer can validate
+against.
"""
from __future__ import annotations
@@ -12,7 +23,23 @@ from datetime import datetime, timezone
from typing import Any, Literal, Mapping, Optional
from uuid import uuid4
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+_TYPE_PREFIX = "com.machinaos."
+_DATASCHEMA_BASE = "machinaos://schemas/events/"
+
+
+def _dataschema_for(event_type: str) -> str:
+ """Compute the ``dataschema`` URI for a given event ``type``.
+
+ Strips the ``com.machinaos.`` prefix when present so the URI segment
+ matches the un-prefixed type (e.g. ``credential.api_key.saved``).
+ External-producer events (e.g. ``stripe.charge.succeeded`` from a
+ Stripe webhook) keep their type verbatim in the URI segment.
+ """
+ seg = event_type.removeprefix(_TYPE_PREFIX) if event_type else event_type
+ return f"{_DATASCHEMA_BASE}{seg}.json"
class WorkflowEvent(BaseModel):
@@ -28,12 +55,25 @@ class WorkflowEvent(BaseModel):
dataschema: Optional[str] = None
data: Any = None
+ # CloudEvents extension attributes. Snake-case (Python convention)
+ # rather than lowercase-alphanumeric (CloudEvents §3.1 SHOULD) —
+ # see module docstring.
workflow_id: Optional[str] = None
trigger_node_id: Optional[str] = None
correlation_id: Optional[str] = None
model_config = ConfigDict(extra="allow")
+ @model_validator(mode="after")
+ def _auto_dataschema(self) -> "WorkflowEvent":
+ """Auto-populate ``dataschema`` from ``type`` so every envelope
+ carries the URI a consumer can use to fetch its payload schema.
+ Explicit ``dataschema`` values are preserved.
+ """
+ if self.dataschema is None and self.type:
+ self.dataschema = _dataschema_for(self.type)
+ return self
+
@classmethod
def from_legacy(cls, event_type: str, payload: dict) -> "WorkflowEvent":
"""Wrap a legacy Dict payload from the pre-framework dispatch path.
@@ -74,7 +114,7 @@ class WorkflowEvent(BaseModel):
``test_credential_broadcasts.py``)."""
return cls(
source="machinaos://services/credentials",
- type=f"credential.{action}",
+ type=f"{_TYPE_PREFIX}credential.{action}",
subject=provider,
data={"provider": provider, **extra} if extra else {"provider": provider},
)
@@ -92,7 +132,7 @@ class WorkflowEvent(BaseModel):
/ twitter / google connect-disconnect)."""
return cls(
source=f"machinaos://nodes/{plugin}",
- type=f"{plugin}.connection.{'opened' if connected else 'closed'}",
+ type=f"{_TYPE_PREFIX}{plugin}.connection.{'opened' if connected else 'closed'}",
subject=subject,
data=dict(data) if data else {},
)
@@ -109,7 +149,7 @@ class WorkflowEvent(BaseModel):
handle (email / username) used as ``subject``."""
return cls(
source=f"machinaos://nodes/{provider}",
- type=f"{provider}.oauth.completed",
+ type=f"{_TYPE_PREFIX}{provider}.oauth.completed",
subject=identifier,
data=dict(data) if data else {"identifier": identifier},
)
@@ -131,7 +171,7 @@ class WorkflowEvent(BaseModel):
)
return cls(
source=f"machinaos://nodes/{plugin}",
- type=f"{plugin}.message.{direction}",
+ type=f"{_TYPE_PREFIX}{plugin}.message.{direction}",
subject=str(raw_subject) if raw_subject is not None else None,
data=payload,
)
@@ -148,7 +188,7 @@ class WorkflowEvent(BaseModel):
message.sent)."""
return cls(
source="machinaos://services/agent_team",
- type=f"team.{kind}",
+ type=f"{_TYPE_PREFIX}team.{kind}",
subject=team_id,
data=dict(data),
)
@@ -174,7 +214,7 @@ class WorkflowEvent(BaseModel):
contract)."""
return cls(
source="machinaos://services/workflow",
- type=f"workflow.{stage}",
+ type=f"{_TYPE_PREFIX}workflow.{stage}",
subject=workflow_id,
workflow_id=workflow_id,
data=dict(data) if data else {},
@@ -207,7 +247,7 @@ class WorkflowEvent(BaseModel):
"""
return cls(
source="machinaos://services/agent",
- type="agent.progress",
+ type=f"{_TYPE_PREFIX}agent.progress",
subject=node_id,
workflow_id=workflow_id,
data={
@@ -242,7 +282,7 @@ class WorkflowEvent(BaseModel):
"""
return cls(
source="machinaos://services/workflow",
- type="workflow.deployment.snapshot",
+ type=f"{_TYPE_PREFIX}workflow.deployment.snapshot",
data={"running_workflow_ids": list(running_workflow_ids)},
)
@@ -259,7 +299,7 @@ class WorkflowEvent(BaseModel):
succeeded vs failed; ``taskTrigger`` filters by both."""
return cls(
source="machinaos://services/agent",
- type=f"agent.task.{'succeeded' if status == 'completed' else 'failed'}",
+ type=f"{_TYPE_PREFIX}agent.task.{'succeeded' if status == 'completed' else 'failed'}",
subject=task_id,
data=dict(data) if data else {"task_id": task_id, "agent": agent, "status": status},
)
@@ -267,15 +307,23 @@ class WorkflowEvent(BaseModel):
def matches_type(self, pattern: str) -> bool:
"""Glob-style match on event type. ``"all"``/empty matches any.
+ Patterns are matched against the type with the
+ ``com.machinaos.`` reverse-DNS prefix stripped, so callers can
+ write ``"credential.api_key.*"`` and still hit
+ ``com.machinaos.credential.api_key.saved``. External-producer
+ types (e.g. ``stripe.charge.succeeded`` from a Stripe webhook)
+ have no prefix and match directly.
+
Examples:
"stripe.charge.succeeded" matches itself
- "stripe.charge.*" matches "stripe.charge.succeeded"
- "stripe.*" matches "stripe.charge.succeeded"
- "all" or "" matches everything
+ "credential.api_key.*" matches "com.machinaos.credential.api_key.saved"
+ "agent.*" matches "com.machinaos.agent.progress"
+ "all" or "" matches everything
"""
if not pattern or pattern == "all":
return True
+ normalized = (self.type or "").removeprefix(_TYPE_PREFIX)
if pattern.endswith(".*"):
prefix = pattern[:-2]
- return self.type.startswith(prefix + ".") or self.type == prefix
- return self.type == pattern
+ return normalized.startswith(prefix + ".") or normalized == prefix
+ return normalized == pattern
diff --git a/server/tests/credentials/test_credential_broadcasts.py b/server/tests/credentials/test_credential_broadcasts.py
index 1e377c9a..214e0d46 100644
--- a/server/tests/credentials/test_credential_broadcasts.py
+++ b/server/tests/credentials/test_credential_broadcasts.py
@@ -129,7 +129,7 @@ class TestCredentialEventCloudEventsShape:
event = WorkflowEvent(
source="machinaos://services/credentials",
- type="credential.api_key.saved",
+ type="com.machinaos.credential.api_key.saved",
subject="openai",
data={"provider": "openai"},
)
@@ -147,8 +147,9 @@ class TestCredentialEventCloudEventsShape:
assert envelope["subject"] == "openai"
def test_event_type_namespaced(self, envelope):
- # Convention: credential.<area>.<action>
- assert envelope["type"].startswith("credential."), envelope["type"]
+ # Convention: com.machinaos.credential.<area>.<action>
+ # (reverse-DNS prefix per CloudEvents Primer)
+ assert envelope["type"].startswith("com.machinaos.credential."), envelope["type"]
class TestAuthServiceDbCanonicalInvariant: