Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""WorkflowEvent — CloudEvents v1.0 envelope (in-house, no external dep).
The core field set mirrors
https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md. New
factories must keep application scope in ``data`` unless they use a valid
lowercase-alphanumeric extension name. CloudEvents 1.0 makes that spelling a
MUST, not a recommendation.
The historical ``workflow_id``, ``trigger_node_id`` and ``correlation_id``
model fields remain readable for wire compatibility, but their underscores
make them non-conformant extension attributes. They are legacy debt, not the
template for new event types. ``agent_capability`` demonstrates the current
contract: standards-shaped context attributes plus snake_case application
fields nested under ``data``.
Type strings carry the reverse-DNS prefix ``com.opencompany.`` 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
from datetime import datetime, timezone
from typing import Any, Literal, Mapping, Optional
from uuid import uuid4
from pydantic import BaseModel, ConfigDict, Field, model_validator
_TYPE_PREFIX = "com.opencompany."
_LEGACY_TYPE_PREFIX = "com.machinaos."
_DATASCHEMA_BASE = "opencompany://schemas/events/"
def _unprefixed_event_type(event_type: str) -> str:
"""Strip either the canonical or legacy product namespace."""
for prefix in (_TYPE_PREFIX, _LEGACY_TYPE_PREFIX):
if event_type.startswith(prefix):
return event_type.removeprefix(prefix)
return event_type
def equivalent_event_types(event_type: str) -> tuple[str, ...]:
"""Return canonical/legacy equivalents for Temporal replay routing.
Running listener workflows may still have ``com.machinaos.*`` stored in
their ``EventType`` Search Attribute. New producers emit
``com.opencompany.*``; dispatch queries both during the transition.
"""
if event_type.startswith(_TYPE_PREFIX):
suffix = event_type.removeprefix(_TYPE_PREFIX)
return event_type, f"{_LEGACY_TYPE_PREFIX}{suffix}"
if event_type.startswith(_LEGACY_TYPE_PREFIX):
suffix = event_type.removeprefix(_LEGACY_TYPE_PREFIX)
return f"{_TYPE_PREFIX}{suffix}", event_type
return (event_type,)
def event_type_matches(event_type: str, pattern: str) -> bool:
"""Glob-style match on an event type. ``"all"``/empty matches any.
The pattern is matched against the type with the ``com.opencompany.``
reverse-DNS prefix stripped. ``"x.*"`` matches ``x`` and every type under
it; anything else must match exactly. :meth:`WorkflowEvent.matches_type`
applies this to an envelope's ``type``; a trigger whose events share one
CloudEvents type applies it to the type it carries in ``data``.
"""
if not pattern or pattern == "all":
return True
normalized = _unprefixed_event_type(event_type or "")
if pattern.endswith(".*"):
prefix = pattern[:-2]
return normalized.startswith(prefix + ".") or normalized == prefix
return normalized == pattern
def _dataschema_for(event_type: str) -> str:
"""Compute the ``dataschema`` URI for a given event ``type``.
Strips the ``com.opencompany.`` 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 = _unprefixed_event_type(event_type) if event_type else event_type
return f"{_DATASCHEMA_BASE}{seg}.json"
class WorkflowEvent(BaseModel):
"""Unified event envelope used by every EventSource."""
specversion: str = "1.0"
id: str = Field(default_factory=lambda: uuid4().hex)
source: str
type: str
time: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
subject: Optional[str] = None
datacontenttype: str = "application/json"
dataschema: Optional[str] = None
data: Any = None
# Legacy non-conformant extension attributes. CloudEvents §3.1 requires
# lowercase-alphanumeric names; do not add more snake_case fields here.
# New application scope belongs in ``data`` until these compatibility
# fields receive a coordinated wire migration.
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.
Used by the back-compat shim in event_waiter.dispatch so existing
plugins (telegram, whatsapp, gmail, etc.) keep working until they
migrate to native WorkflowEvent emission.
"""
return cls(
source=f"legacy://{event_type}",
type=event_type,
data=payload,
)
# ---- Typed factory classmethods (Wave 11.I, milestone Q) -----------
#
# Mirrors the official `cloudevents` Python SDK's `from_http` /
# `to_http` convenience pattern. Each factory enforces the same
# source/type/subject conventions across the codebase so callers
# don't hand-construct envelopes with drifting URI shapes.
@classmethod
def credential(
cls,
provider: str,
action: Literal[
"api_key.saved",
"api_key.deleted",
"api_key.validated",
"oauth.connected",
"oauth.disconnected",
"oauth.validated",
],
**extra: Any,
) -> "WorkflowEvent":
"""Credential mutation event (matches the existing
``broadcast_credential_event`` contract locked by
``test_credential_broadcasts.py``)."""
return cls(
source="opencompany://services/credentials",
type=f"{_TYPE_PREFIX}credential.{action}",
subject=provider,
data={"provider": provider, **extra} if extra else {"provider": provider},
)
# ``WorkflowEvent.connection_status(...)`` previously lived here as a
# parameterized factory but had zero callers after Wave-12 B1-B3 gave
# each plugin its own typed factory (``android_connection_status`` /
# ``whatsapp_connection_status`` / ``telegram_connection_status`` in
# ``server/nodes/<plugin>/_events.py``). Removed in Wave 15.1.
@classmethod
def oauth_completed(
cls,
provider: str,
*,
identifier: str,
data: Optional[Mapping[str, Any]] = None,
) -> "WorkflowEvent":
"""OAuth callback completion. ``identifier`` is the user-facing
handle (email / username) used as ``subject``."""
return cls(
source=f"opencompany://nodes/{provider}",
type=f"{_TYPE_PREFIX}{provider}.oauth.completed",
subject=identifier,
data=dict(data) if data else {"identifier": identifier},
)
# ``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(
cls,
team_id: str,
kind: str,
data: Mapping[str, Any],
) -> "WorkflowEvent":
"""Agent-team lifecycle / task event (created / dissolved /
task.added / task.claimed / task.completed / task.failed /
message.sent)."""
return cls(
source="opencompany://services/agent_team",
type=f"{_TYPE_PREFIX}team.{kind}",
subject=team_id,
data=dict(data),
)
@classmethod
def workflow_lifecycle(
cls,
stage: Literal[
"deployment.started",
"deployment.stopped",
"lock.acquired",
"lock.released",
"execution.started",
"execution.stopped",
"imported",
"renamed",
"created",
"deleted",
],
*,
workflow_id: str,
data: Optional[Mapping[str, Any]] = None,
) -> "WorkflowEvent":
"""Workflow lifecycle event. Carries ``workflow_id`` both as
``subject`` (CloudEvents convention) and as the
``workflow_id`` extension attribute (existing reader
contract).
``imported`` fires from ``services.workflow_import.import_workflow``
after the new workflow is persisted. Frontend listeners invalidate
the workflows query so the sidebar picks up the new entry across
all connected clients (browser tabs).
``created`` / ``deleted`` fire from the workflow storage handlers
(a brand-new save, a delete through either surface) so every
client's workflow list refreshes: the editor sidebar and Normal
mode's team, where each workflow is an employee.
``renamed`` fires from the ``rename_workflow`` WebSocket
handler. ``data`` carries ``{name, slug, old_slug}`` so the
frontend updates the open workflow's display + invalidates the
workflows query for the sidebar. The ``workflow_id`` (UUID) is
unchanged across the rename — only the human-readable fields
change.
"""
return cls(
source="opencompany://services/workflow",
type=f"{_TYPE_PREFIX}workflow.{stage}",
subject=workflow_id,
workflow_id=workflow_id,
data=dict(data) if data else {},
)
@classmethod
def agent_progress(
cls,
node_id: str,
*,
workflow_id: Optional[str],
iteration: int,
max_iterations: int,
phase: Optional[str] = None,
data: Optional[Mapping[str, Any]] = None,
) -> "WorkflowEvent":
"""Live agent-loop progress for one agent node.
Emitted from inside the agent loop in
``services/ai.py:execute_agent`` and ``execute_chat_agent`` after
each LLM turn. ``iteration`` advances on every model invocation;
``max_iterations`` mirrors the loop's hard cap (sourced from
``llm_defaults.json:agent.recursion_limit``).
``subject`` carries the executing node id so the FE routes the
update straight to ``nodeStatusStore`` for that node. The
``workflow_id`` extension attribute scopes per-workflow displays
the same way ``node_status`` broadcasts do.
"""
return cls(
source="opencompany://services/agent",
type=f"{_TYPE_PREFIX}agent.progress",
subject=node_id,
workflow_id=workflow_id,
data={
"node_id": node_id,
"iteration": iteration,
"max_iterations": max_iterations,
**({"phase": phase} if phase else {}),
**(dict(data) if data else {}),
},
)
@classmethod
def agent_capability(
cls,
agent_node_id: str,
*,
capability_kind: Literal["skill", "tool"],
capability_name: str,
state: Literal[
"loading",
"loaded",
"resource_read",
"cleared",
"started",
"completed",
"failed",
],
workflow_id: Optional[str] = None,
execution_id: Optional[str] = None,
root_execution_id: Optional[str] = None,
target_node_id: Optional[str] = None,
action: Optional[str] = None,
provider: Optional[str] = None,
invocation_source: Optional[str] = None,
tool_call_id: Optional[str] = None,
duration_ms: Optional[int] = None,
returned_characters: Optional[int] = None,
token_estimate: Optional[int] = None,
content_hash: Optional[str] = None,
error_code: Optional[str] = None,
event_id: Optional[str] = None,
) -> "WorkflowEvent":
"""One safe, node-owned skill/tool lifecycle occurrence.
This is observability telemetry, not a trigger input. Operational
scope stays inside ``data`` rather than becoming custom top-level
attributes: CloudEvents 1.0 requires extension attribute names to be
lowercase ASCII letters/digits, while OpenCompany's application
payload convention intentionally uses snake_case.
Prompts, tool arguments, instruction/resource contents, results,
secrets, and raw errors are deliberately absent from this contract.
``subject`` is always the exact invoking agent; ``target_node_id`` is
the exact connected Master Skill or tool node.
"""
valid_states = {
"skill": {"loading", "loaded", "resource_read", "failed", "cleared"},
"tool": {"started", "completed", "failed"},
}
if capability_kind not in valid_states:
raise ValueError(f"Invalid capability kind: {capability_kind}")
if not agent_node_id or not capability_name:
raise ValueError("agent_node_id and capability_name are required")
if state not in valid_states[capability_kind]:
raise ValueError(
f"Invalid {capability_kind} capability state: {state}"
)
payload = {
"workflow_id": workflow_id,
"execution_id": execution_id,
"root_execution_id": root_execution_id,
"agent_node_id": agent_node_id,
"author_node_id": agent_node_id,
"target_node_id": target_node_id,
"capability_kind": capability_kind,
"capability_name": capability_name,
"state": state,
"action": action,
"provider": provider,
"invocation_source": invocation_source,
"tool_call_id": tool_call_id,
"duration_ms": duration_ms,
"returned_characters": returned_characters,
"token_estimate": token_estimate,
"content_hash": content_hash,
"error_code": error_code,
}
event_kwargs: dict[str, Any] = {
"source": "opencompany://services/agent",
"type": f"{_TYPE_PREFIX}agent.{capability_kind}.{state}",
"subject": agent_node_id,
"data": {key: value for key, value in payload.items() if value is not None},
}
if event_id:
event_kwargs["id"] = event_id
return cls(**event_kwargs)
@classmethod
def node_parameters_updated(
cls,
node_id: str,
*,
parameters: Mapping[str, Any],
workflow_id: Optional[str] = None,
version: int = 1,
source_hint: str = "user",
) -> "WorkflowEvent":
"""Server-pushed notification that a node's parameters changed.
Three emission sites today:
- ``routers/websocket.py:handle_save_node_parameters`` — user
edited the parameter panel.
- ``services/cli_agent/service.py:_persist_memory`` — Claude
Code CLI memory bridge appended a turn to ``simpleMemory``.
- ``services/temporal/agent_activities.py:persist_agent_turn``
— F4.B AgentWorkflow's per-turn memory append.
``subject`` is the node_id so the FE routes the refetch to the
right parameter panel. ``source_hint`` distinguishes user edits
(``"user"``) from autonomous writes (``"agent"`` / ``"cli"``)
so the panel can choose whether to confirm a re-render against
the user's in-progress local edits.
"""
return cls(
source="opencompany://services/parameters",
type=f"{_TYPE_PREFIX}node.parameters.updated",
subject=node_id,
workflow_id=workflow_id,
data={
"node_id": node_id,
"parameters": dict(parameters),
"version": version,
"source": source_hint,
},
)
@classmethod
def deployment_snapshot(
cls,
running_workflow_ids: list[str],
paused_workflow_ids: Optional[list[str]] = None,
) -> "WorkflowEvent":
"""Push-on-connect snapshot of every currently-running deployment.
Emitted by ``broadcaster.broadcast_deployment_snapshot()`` to a
single WebSocket target right after ``initial_status``. Lets the
FE reconcile its local ``deploymentStatus`` / ``runningWorkflows``
cache against the backend's source of truth on every (re)connect,
instead of carrying stale "isRunning=true" forward through a
backend restart that wiped the in-memory deployment dict.
Distinct from ``workflow_lifecycle("deployment.started")`` —
that fires when a deployment STARTS (one-shot edge event).
``deployment.snapshot`` is an idempotent state dump tied to
client connect, not to a state transition. Empty list is
meaningful: "no deployments are running, drop your stale
local state."
"""
return cls(
source="opencompany://services/workflow",
type=f"{_TYPE_PREFIX}workflow.deployment.snapshot",
data={
"running_workflow_ids": list(running_workflow_ids),
# Armed-but-paused deployments: still deployed (they stay
# in running_workflow_ids) but must not render as
# executing on the client.
"paused_workflow_ids": list(paused_workflow_ids or []),
},
)
@classmethod
def task_completed(
cls,
task_id: str,
*,
status: Literal["completed", "error"],
agent: str,
data: Optional[Mapping[str, Any]] = None,
) -> "WorkflowEvent":
"""Delegated child-agent completion.
Both success and failure share one ``type``
(``com.opencompany.agent.task.completed``) so the
``TriggerListenerWorkflow`` for ``taskTrigger`` can register a
single ``EventType`` Search Attribute and match every
completion event via :func:`services.events.dispatch.emit`'s
Visibility query. Status discrimination lives in ``data.status``
(``"completed"`` or ``"error"``) — :class:`TaskTriggerNode`'s
filter already keys off this field.
Pre-fix (commit ?) the type split into ``.succeeded`` /
``.failed`` which left the listener's SA value matching only
one branch and silently lost the other half of events.
"""
return cls(
source="opencompany://services/agent",
type=f"{_TYPE_PREFIX}agent.task.completed",
subject=task_id,
data=dict(data) if data else {"task_id": task_id, "agent": agent, "status": status},
)
@classmethod
def claude_session_spawned(
cls,
memory_node_id: str,
*,
session_uuid: str,
pid: int,
workflow_id: Optional[str] = None,
) -> "WorkflowEvent":
"""Pool-managed claude session spawned fresh.
Fired once per cold-start of a pooled session — the warm-reuse
path emits ``claude.session.cleared`` instead. ``subject`` is
the simpleMemory node so the FE can wire a per-memory-node
status badge.
"""
return cls(
source="opencompany://services/cli_agent",
type=f"{_TYPE_PREFIX}claude.session.spawned",
subject=memory_node_id,
workflow_id=workflow_id,
data={
"memory_node_id": memory_node_id,
"session_uuid": session_uuid,
"pid": pid,
},
)
@classmethod
def claude_session_cleared(
cls,
memory_node_id: str,
*,
old_session_uuid: str,
new_session_uuid: str,
workflow_id: Optional[str] = None,
) -> "WorkflowEvent":
"""Pool sent ``/clear``; claude minted a fresh session UUID.
Per issue `claude-code#32871
<https://github.com/anthropics/claude-code/issues/32871>`_,
``/clear`` creates a NEW session UUID with a NEW JSONL file
rather than clearing in-place. The pool captures the new UUID
via :class:`JsonlDirWatcher` and emits this event so the memory
bridge + UI can track the rotation.
"""
return cls(
source="opencompany://services/cli_agent",
type=f"{_TYPE_PREFIX}claude.session.cleared",
subject=memory_node_id,
workflow_id=workflow_id,
data={
"memory_node_id": memory_node_id,
"old_session_uuid": old_session_uuid,
"new_session_uuid": new_session_uuid,
},
)
@classmethod
def claude_session_terminated(
cls,
memory_node_id: str,
*,
reason: Literal["idle", "crashed", "evicted", "shutdown", "explicit"],
session_uuid: Optional[str] = None,
workflow_id: Optional[str] = None,
) -> "WorkflowEvent":
"""Pool-managed claude session ended.
``reason`` discriminates the cause: ``idle`` (reaper exceeded
TTL), ``crashed`` (process died unexpectedly), ``evicted`` (LRU
eviction at max pool size), ``shutdown`` (FastAPI lifespan stop),
``explicit`` (caller-driven terminate).
"""
return cls(
source="opencompany://services/cli_agent",
type=f"{_TYPE_PREFIX}claude.session.terminated",
subject=memory_node_id,
workflow_id=workflow_id,
data={
"memory_node_id": memory_node_id,
"reason": reason,
**({"session_uuid": session_uuid} if session_uuid else {}),
},
)
@classmethod
def claude_session_usage(
cls,
memory_node_id: str,
*,
session_uuid: str,
total_cost_usd: Optional[float] = None,
input_tokens: int = 0,
output_tokens: int = 0,
cache_read_input_tokens: int = 0,
cache_creation_input_tokens: int = 0,
duration_ms: Optional[int] = None,
num_turns: Optional[int] = None,
workflow_id: Optional[str] = None,
) -> "WorkflowEvent":
"""Per-turn cost / token usage from a claude ``result`` event.
Sourced directly from the JSONL ``result.usage`` block —
same data ``/usage`` displays in the TUI, but structured. The
FE wires a usage panel onto simpleMemory by listening for this
type (rather than scraping the TUI's ``/usage`` output, which
is plain text per Anthropic's docs and not parseable).
"""
return cls(
source="opencompany://services/cli_agent",
type=f"{_TYPE_PREFIX}claude.session.usage",
subject=memory_node_id,
workflow_id=workflow_id,
data={
"memory_node_id": memory_node_id,
"session_uuid": session_uuid,
"total_cost_usd": total_cost_usd,
"usage": {
"input_tokens": input_tokens,
"output_tokens": output_tokens,
"cache_read_input_tokens": cache_read_input_tokens,
"cache_creation_input_tokens": cache_creation_input_tokens,
},
**({"duration_ms": duration_ms} if duration_ms is not None else {}),
**({"num_turns": num_turns} if num_turns is not None else {}),
},
)
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.opencompany.`` reverse-DNS prefix stripped, so callers can
write ``"credential.api_key.*"`` and still hit
``com.opencompany.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
"credential.api_key.*" matches "com.opencompany.credential.api_key.saved"
"agent.*" matches "com.opencompany.agent.progress"
"all" or "" matches everything
"""
return event_type_matches(self.type or "", pattern)