edda-framework 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

edda/app.py

@@ -238,7 +238,9 @@ class EddaApp:
         Register a default CloudEvent handler for a workflow.
 
         The default handler extracts the CloudEvent data and passes it
-        as kwargs to workflow.start().
+        as kwargs to workflow.start(). If the CloudEvent contains
+        traceparent/tracestate extension attributes (for distributed tracing),
+        they are automatically injected into _trace_context.
 
         Args:
             event_type: CloudEvent type (same as workflow name)
@@ -250,11 +252,24 @@ class EddaApp:
             # Extract data from CloudEvent
             data = event.get_data()
 
+            # Extract trace context from CloudEvent extension attributes
+            # (W3C Trace Context: traceparent, tracestate)
+            trace_context: dict[str, str] = {}
+            attrs = event.get_attributes()
+            if "traceparent" in attrs:
+                trace_context["traceparent"] = str(attrs["traceparent"])
+            if "tracestate" in attrs:
+                trace_context["tracestate"] = str(attrs["tracestate"])
+
             # Start workflow with data as kwargs
             if isinstance(data, dict):
+                # Inject trace context if present
+                if trace_context:
+                    data = {**data, "_trace_context": trace_context}
                 await wf.start(**data)
             else:
                 # If data is not a dict, start without arguments
+                # (trace context cannot be injected)
                 await wf.start()
 
         # Register the handler

edda/hooks.py

@@ -12,8 +12,8 @@ Example:
     ...     async def on_workflow_start(self, instance_id, workflow_name, input_data):
     ...         print(f"Workflow {workflow_name} started: {instance_id}")
     ...
-    ...     async def on_activity_complete(self, instance_id, step, activity_name, result, cache_hit):
-    ...         print(f"Activity {activity_name} completed (cache_hit={cache_hit})")
+    ...     async def on_activity_complete(self, instance_id, activity_id, activity_name, result, cache_hit):
+    ...         print(f"Activity {activity_name} ({activity_id}) completed (cache_hit={cache_hit})")
     >>>
     >>> app = EddaApp(service_name="my-service", db_url="...", hooks=MyHooks())
 """
@@ -86,7 +86,7 @@ class WorkflowHooks(Protocol):
     async def on_activity_start(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         is_replaying: bool,
     ) -> None:
@@ -95,7 +95,7 @@ class WorkflowHooks(Protocol):
 
         Args:
             instance_id: Unique workflow instance ID
-            step: Step number in the workflow
+            activity_id: Activity ID (e.g., "reserve_inventory:1")
             activity_name: Name of the activity function
             is_replaying: True if this is a replay (cached result)
         """
@@ -104,7 +104,7 @@ class WorkflowHooks(Protocol):
     async def on_activity_complete(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         result: Any,
         cache_hit: bool,
@@ -114,7 +114,7 @@ class WorkflowHooks(Protocol):
 
         Args:
             instance_id: Unique workflow instance ID
-            step: Step number in the workflow
+            activity_id: Activity ID (e.g., "reserve_inventory:1")
             activity_name: Name of the activity function
             result: Return value from the activity
             cache_hit: True if result was retrieved from cache (replay)
@@ -124,7 +124,7 @@ class WorkflowHooks(Protocol):
     async def on_activity_failed(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         error: Exception,
     ) -> None:
@@ -133,7 +133,7 @@ class WorkflowHooks(Protocol):
 
         Args:
             instance_id: Unique workflow instance ID
-            step: Step number in the workflow
+            activity_id: Activity ID (e.g., "reserve_inventory:1")
             activity_name: Name of the activity function
             error: Exception that caused the failure
         """
@@ -231,7 +231,7 @@ class HooksBase(WorkflowHooks, ABC):
     async def on_activity_start(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         is_replaying: bool,
     ) -> None:
@@ -240,7 +240,7 @@ class HooksBase(WorkflowHooks, ABC):
     async def on_activity_complete(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         result: Any,
         cache_hit: bool,
@@ -250,7 +250,7 @@ class HooksBase(WorkflowHooks, ABC):
     async def on_activity_failed(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         error: Exception,
     ) -> None:

edda/integrations/mcp/decorators.py

@@ -19,14 +19,15 @@ def create_durable_tool(
     description: str = "",
 ) -> Workflow:
     """
-    Create a durable workflow tool with auto-generated status/result tools.
+    Create a durable workflow tool with auto-generated status/result/cancel tools.
 
     This function:
     1. Wraps the function as an Edda @workflow
-    2. Registers three MCP tools:
+    2. Registers four MCP tools:
        - {name}: Start workflow, return instance_id
        - {name}_status: Check workflow status
        - {name}_result: Get workflow result
+       - {name}_cancel: Cancel workflow (if running or waiting)
 
     Args:
         server: EddaMCPServer instance
@@ -93,9 +94,9 @@ def create_durable_tool(
     status_tool_name = f"{workflow_name}_status"
     status_tool_description = f"Check status of {workflow_name} workflow"
 
-    @server._mcp.tool(name=status_tool_name, description=status_tool_description)  # type: ignore[misc]
+    @server._mcp.tool(name=status_tool_name, description=status_tool_description)
     async def status_tool(instance_id: str) -> dict[str, Any]:
-        """Check workflow status."""
+        """Check workflow status with progress metadata."""
         try:
             instance = await server.storage.get_instance(instance_id)
             if instance is None:
@@ -112,9 +113,22 @@ def create_durable_tool(
             status = instance["status"]
             current_activity_id = instance.get("current_activity_id", "N/A")
 
+            # Get history to count completed activities
+            history = await server.storage.get_history(instance_id)
+            completed_activities = len(
+                [h for h in history if h["event_type"] == "ActivityCompleted"]
+            )
+
+            # Suggest poll interval based on status
+            # Running workflows need more frequent polling (5s)
+            # Waiting workflows need less frequent polling (10s)
+            suggested_poll_interval_ms = 5000 if status == "running" else 10000
+
             status_text = (
                 f"Workflow Status: {status}\n"
                 f"Current Activity: {current_activity_id}\n"
+                f"Completed Activities: {completed_activities}\n"
+                f"Suggested Poll Interval: {suggested_poll_interval_ms}ms\n"
                 f"Instance ID: {instance_id}"
             )
 
@@ -137,7 +151,7 @@ def create_durable_tool(
     result_tool_name = f"{workflow_name}_result"
     result_tool_description = f"Get result of {workflow_name} workflow (if completed)"
 
-    @server._mcp.tool(name=result_tool_name, description=result_tool_description)  # type: ignore[misc]
+    @server._mcp.tool(name=result_tool_name, description=result_tool_description)
     async def result_tool(instance_id: str) -> dict[str, Any]:
         """Get workflow result (if completed)."""
         try:
@@ -184,4 +198,86 @@ def create_durable_tool(
                 "isError": True,
             }
 
+    # 5. Generate cancel tool
+    cancel_tool_name = f"{workflow_name}_cancel"
+    cancel_tool_description = f"Cancel {workflow_name} workflow (if running or waiting)"
+
+    @server._mcp.tool(name=cancel_tool_name, description=cancel_tool_description)
+    async def cancel_tool(instance_id: str) -> dict[str, Any]:
+        """Cancel a running or waiting workflow."""
+        try:
+            # Check if instance exists
+            instance = await server.storage.get_instance(instance_id)
+            if instance is None:
+                return {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": f"Workflow instance not found: {instance_id}",
+                        }
+                    ],
+                    "isError": True,
+                }
+
+            current_status = instance["status"]
+
+            # Check if replay_engine is available
+            if server.replay_engine is None:
+                return {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "Server not initialized. Call server.initialize() first.",
+                        }
+                    ],
+                    "isError": True,
+                }
+
+            # Try to cancel
+            success = await server.replay_engine.cancel_workflow(
+                instance_id=instance_id,
+                cancelled_by="mcp_user",
+            )
+
+            if success:
+                return {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": (
+                                f"Workflow '{workflow_name}' cancelled successfully.\n"
+                                f"Instance ID: {instance_id}\n"
+                                f"Compensations executed.\n\n"
+                                f"The workflow has been stopped and any side effects "
+                                f"have been rolled back."
+                            ),
+                        }
+                    ],
+                    "isError": False,
+                }
+            else:
+                return {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": (
+                                f"Cannot cancel workflow: {instance_id}\n"
+                                f"Current status: {current_status}\n"
+                                f"Only running or waiting workflows can be cancelled."
+                            ),
+                        }
+                    ],
+                    "isError": True,
+                }
+        except Exception as e:
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": f"Error cancelling workflow: {str(e)}",
+                    }
+                ],
+                "isError": True,
+            }
+
     return workflow_instance

edda/integrations/mcp/server.py

@@ -9,10 +9,11 @@ from edda.app import EddaApp
 from edda.workflow import Workflow
 
 if TYPE_CHECKING:
+    from edda.replay import ReplayEngine
     from edda.storage.protocol import StorageProtocol
 
 try:
-    from mcp.server.fastmcp import FastMCP  # type: ignore[import-not-found]
+    from mcp.server.fastmcp import FastMCP
 except ImportError as e:
     raise ImportError(
         "MCP Python SDK is required for MCP integration. "
@@ -68,10 +69,11 @@ class EddaMCPServer:
             asyncio.run(main())
         ```
 
-    The server automatically generates three MCP tools for each @durable_tool:
+    The server automatically generates four MCP tools for each @durable_tool:
     - `tool_name`: Start the workflow, returns instance_id
     - `tool_name_status`: Check workflow status
     - `tool_name_result`: Get workflow result (if completed)
+    - `tool_name_cancel`: Cancel workflow (if running or waiting)
     """
 
     def __init__(
@@ -122,6 +124,24 @@ class EddaMCPServer:
         """
         return self._edda_app.storage
 
+    @property
+    def replay_engine(self) -> ReplayEngine | None:
+        """
+        Access replay engine for workflow operations (cancel, resume, etc.).
+
+        Returns:
+            ReplayEngine or None if not initialized
+
+        Example:
+            ```python
+            # Cancel a running workflow
+            success = await server.replay_engine.cancel_workflow(
+                instance_id, "mcp_user"
+            )
+            ```
+        """
+        return self._edda_app.replay_engine
+
     def durable_tool(
         self,
         func: Callable[..., Any] | None = None,
@@ -131,10 +151,11 @@ class EddaMCPServer:
         """
         Decorator to define a durable workflow tool.
 
-        Automatically generates three MCP tools:
+        Automatically generates four MCP tools:
         1. Main tool: Starts the workflow, returns instance_id
         2. Status tool: Checks workflow status
         3. Result tool: Gets workflow result (if completed)
+        4. Cancel tool: Cancels workflow (if running or waiting)
 
         Args:
             func: Workflow function (async)
@@ -207,7 +228,7 @@ class EddaMCPServer:
         def decorator(f: Callable[..., Any]) -> Callable[..., Any]:
             # Use FastMCP's native prompt decorator
             prompt_desc = description or f.__doc__ or f"Prompt: {f.__name__}"
-            return cast(Callable[..., Any], self._mcp.prompt(description=prompt_desc)(f))
+            return self._mcp.prompt(description=prompt_desc)(f)
 
         if func is None:
             return decorator
@@ -228,8 +249,8 @@ class EddaMCPServer:
         Returns:
             ASGI callable (Starlette app)
         """
-        from starlette.requests import Request  # type: ignore[import-not-found]
-        from starlette.responses import Response  # type: ignore[import-not-found]
+        from starlette.requests import Request
+        from starlette.responses import Response
 
         # Get MCP's Starlette app (Issue #1367 workaround: use directly)
         app = self._mcp.streamable_http_app()
@@ -270,14 +291,13 @@ class EddaMCPServer:
         app.router.add_route("/cancel/{instance_id}", edda_cancel_handler, methods=["POST"])
 
         # Add authentication middleware if token_verifier provided (AFTER adding routes)
+        result_app: Any = app
         if self._token_verifier is not None:
-            from starlette.middleware.base import (  # type: ignore[import-not-found]
-                BaseHTTPMiddleware,
-            )
+            from starlette.middleware.base import BaseHTTPMiddleware
 
-            class AuthMiddleware(BaseHTTPMiddleware):  # type: ignore[misc]
-                def __init__(self, app: Any, token_verifier: Callable[[str], bool]):
-                    super().__init__(app)
+            class AuthMiddleware(BaseHTTPMiddleware):
+                def __init__(self, app_inner: Any, token_verifier: Callable[[str], bool]) -> None:
+                    super().__init__(app_inner)
                     self.token_verifier = token_verifier
 
                 async def dispatch(
@@ -288,12 +308,13 @@ class EddaMCPServer:
                         token = auth_header[7:]
                         if not self.token_verifier(token):
                             return Response("Unauthorized", status_code=401)
-                    return await call_next(request)
+                    response: Response = await call_next(request)
+                    return response
 
             # Wrap app with auth middleware
-            app = AuthMiddleware(app, self._token_verifier)
+            result_app = AuthMiddleware(app, self._token_verifier)
 
-        return cast(Callable[..., Any], app)
+        return cast(Callable[..., Any], result_app)
 
     async def initialize(self) -> None:
         """

edda/integrations/opentelemetry/__init__.py

@@ -0,0 +1,39 @@
+"""
+Edda OpenTelemetry Integration.
+
+Provides OpenTelemetry tracing and optional metrics for Edda workflows.
+
+Example:
+    ```python
+    from edda import EddaApp
+    from edda.integrations.opentelemetry import OpenTelemetryHooks
+
+    hooks = OpenTelemetryHooks(
+        service_name="order-service",
+        otlp_endpoint="http://localhost:4317",  # Optional
+        enable_metrics=True,  # Optional
+    )
+
+    app = EddaApp(
+        service_name="order-service",
+        db_url="sqlite:///workflow.db",
+        hooks=hooks,
+    )
+    ```
+
+Installation:
+    ```bash
+    pip install edda-framework[opentelemetry]
+
+    # Or using uv
+    uv add edda-framework --extra opentelemetry
+    ```
+"""
+
+from edda.integrations.opentelemetry.hooks import (
+    OpenTelemetryHooks,
+    extract_trace_context,
+    inject_trace_context,
+)
+
+__all__ = ["OpenTelemetryHooks", "inject_trace_context", "extract_trace_context"]

edda/integrations/opentelemetry/hooks.py

@@ -0,0 +1,579 @@
+"""
+OpenTelemetry hooks implementation for Edda workflows.
+
+This module provides the OpenTelemetryHooks class that integrates OpenTelemetry
+tracing and optional metrics with Edda's workflow execution.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any
+
+from edda.hooks import HooksBase
+
+if TYPE_CHECKING:
+    from opentelemetry.context import Context
+    from opentelemetry.trace import Span, Tracer
+
+# Check if OpenTelemetry is available
+try:
+    from opentelemetry import trace
+    from opentelemetry.context import Context
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
+    from opentelemetry.trace import Span, Status, StatusCode, Tracer
+    from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+    _OPENTELEMETRY_AVAILABLE = True
+except ImportError:
+    _OPENTELEMETRY_AVAILABLE = False
+
+
+class OpenTelemetryHooks(HooksBase):
+    """
+    OpenTelemetry tracing and metrics integration for Edda workflows.
+
+    Creates distributed traces with:
+    - Workflow spans as parent spans
+    - Activity spans as child spans
+    - Error recording and status propagation
+    - Retry event tracking
+    - Optional metrics (counters, histograms)
+
+    Span Hierarchy::
+
+        workflow:order_workflow (parent)
+        ├── activity:reserve_inventory (child)
+        │   └── [event: retry] (if retry occurs)
+        ├── activity:process_payment (child)
+        └── activity:ship_order (child)
+            └── [event: event_received] (if wait_event used)
+
+    Example::
+
+        from edda import EddaApp
+        from edda.integrations.opentelemetry import OpenTelemetryHooks
+
+        hooks = OpenTelemetryHooks(
+            service_name="order-service",
+            otlp_endpoint="http://localhost:4317",  # Optional
+            enable_metrics=True,  # Optional
+        )
+
+        app = EddaApp(
+            service_name="order-service",
+            db_url="sqlite:///workflow.db",
+            hooks=hooks,
+        )
+
+    Attributes:
+        service.name: Service name for resource identification
+        service.version: Service version (default: "1.0.0")
+        edda.framework: Always "true" to identify Edda workflows
+
+    Installation::
+
+        pip install edda-framework[opentelemetry]
+    """
+
+    def __init__(
+        self,
+        service_name: str = "edda",
+        otlp_endpoint: str | None = None,
+        enable_metrics: bool = False,
+    ) -> None:
+        """
+        Initialize OpenTelemetry hooks.
+
+        Args:
+            service_name: Service name for resource identification
+            otlp_endpoint: OTLP endpoint URL (e.g., "http://localhost:4317").
+                          If None, uses ConsoleSpanExporter for local development.
+            enable_metrics: Enable OpenTelemetry metrics (counters, histograms)
+
+        Raises:
+            ImportError: If OpenTelemetry packages are not installed
+        """
+        if not _OPENTELEMETRY_AVAILABLE:
+            raise ImportError(
+                "OpenTelemetry packages are not installed. "
+                "Install them with: pip install edda-framework[opentelemetry]"
+            )
+
+        self._tracer = self._setup_tracing(service_name, otlp_endpoint)
+        self._propagator = TraceContextTextMapPropagator()
+
+        # Span lifecycle management
+        self._workflow_spans: dict[str, Span] = {}
+        self._activity_spans: dict[str, Span] = {}
+        self._workflow_start_times: dict[str, float] = {}
+        self._activity_start_times: dict[str, float] = {}
+
+        # Optional metrics
+        self._enable_metrics = enable_metrics
+        if enable_metrics:
+            self._setup_metrics(service_name, otlp_endpoint)
+
+    def _setup_tracing(self, service_name: str, otlp_endpoint: str | None) -> Tracer:
+        """Configure OpenTelemetry tracing.
+
+        If a TracerProvider is already configured (e.g., by ASGI/WSGI middleware),
+        it will be reused instead of creating a new one. This enables trace context
+        propagation from external sources.
+        """
+        from opentelemetry.trace import NoOpTracerProvider
+
+        # Check if a TracerProvider is already configured
+        existing_provider = trace.get_tracer_provider()
+
+        # Only create new provider if none exists (NoOpTracerProvider is the default)
+        if isinstance(existing_provider, NoOpTracerProvider):
+            resource = Resource.create(
+                {
+                    "service.name": service_name,
+                    "service.version": "1.0.0",
+                    "edda.framework": "true",
+                }
+            )
+
+            provider = TracerProvider(resource=resource)
+
+            if otlp_endpoint:
+                # Production: OTLP exporter
+                try:
+                    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+                        OTLPSpanExporter,
+                    )
+
+                    exporter = OTLPSpanExporter(endpoint=otlp_endpoint, insecure=True)
+                    provider.add_span_processor(BatchSpanProcessor(exporter))
+                except ImportError:
+                    # Fallback to console if OTLP exporter not installed
+                    provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+            else:
+                # Development: Console exporter
+                provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+
+            trace.set_tracer_provider(provider)
+
+        # Always get tracer from current provider (whether new or existing)
+        return trace.get_tracer("edda.opentelemetry", "1.0.0")
+
+    def _setup_metrics(self, service_name: str, otlp_endpoint: str | None) -> None:
+        """Configure OpenTelemetry metrics (optional)."""
+        try:
+            from opentelemetry import metrics
+            from opentelemetry.sdk.metrics import MeterProvider
+            from opentelemetry.sdk.metrics.export import (
+                ConsoleMetricExporter,
+                MetricExporter,
+                PeriodicExportingMetricReader,
+            )
+
+            exporter: MetricExporter
+            if otlp_endpoint:
+                try:
+                    from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import (
+                        OTLPMetricExporter,
+                    )
+
+                    exporter = OTLPMetricExporter(endpoint=otlp_endpoint, insecure=True)
+                except ImportError:
+                    exporter = ConsoleMetricExporter()
+            else:
+                exporter = ConsoleMetricExporter()
+
+            reader = PeriodicExportingMetricReader(exporter, export_interval_millis=10000)
+            resource = Resource.create({"service.name": service_name})
+            provider = MeterProvider(resource=resource, metric_readers=[reader])
+            metrics.set_meter_provider(provider)
+
+            meter = metrics.get_meter("edda.opentelemetry", "1.0.0")
+
+            # Counters
+            self._workflow_started_counter = meter.create_counter(
+                "edda.workflow.started",
+                description="Number of workflows started",
+                unit="1",
+            )
+            self._workflow_completed_counter = meter.create_counter(
+                "edda.workflow.completed",
+                description="Number of workflows completed",
+                unit="1",
+            )
+            self._workflow_failed_counter = meter.create_counter(
+                "edda.workflow.failed",
+                description="Number of workflows failed",
+                unit="1",
+            )
+            self._activity_executed_counter = meter.create_counter(
+                "edda.activity.executed",
+                description="Number of activities executed (not cache hit)",
+                unit="1",
+            )
+            self._activity_cache_hit_counter = meter.create_counter(
+                "edda.activity.cache_hit",
+                description="Number of activity cache hits (replay)",
+                unit="1",
+            )
+
+            # Histograms
+            self._workflow_duration_histogram = meter.create_histogram(
+                "edda.workflow.duration",
+                description="Workflow execution duration",
+                unit="s",
+            )
+            self._activity_duration_histogram = meter.create_histogram(
+                "edda.activity.duration",
+                description="Activity execution duration",
+                unit="s",
+            )
+        except ImportError:
+            self._enable_metrics = False
+
+    # =========================================================================
+    # Workflow Hooks
+    # =========================================================================
+
+    async def on_workflow_start(
+        self, instance_id: str, workflow_name: str, input_data: dict[str, Any]
+    ) -> None:
+        """Start a workflow span (parent for all activities).
+
+        Trace context is inherited in the following priority:
+        1. Explicit _trace_context in input_data (e.g., from CloudEvents)
+        2. Current active span (e.g., from ASGI/WSGI middleware)
+        3. None (creates a new root span)
+        """
+        # Priority 1: Extract trace context from input_data (CloudEvents, manual)
+        parent_context = self._extract_trace_context(input_data)
+
+        # Priority 2: Inherit from current active span (ASGI/WSGI middleware)
+        if parent_context is None:
+            current_span = trace.get_current_span()
+            if current_span.is_recording():
+                parent_context = trace.set_span_in_context(current_span)
+
+        span = self._tracer.start_span(
+            name=f"workflow:{workflow_name}",
+            context=parent_context,
+            attributes={
+                "edda.workflow.instance_id": instance_id,
+                "edda.workflow.name": workflow_name,
+                "edda.workflow.input_keys": str(list(input_data.keys())),
+            },
+        )
+        self._workflow_spans[instance_id] = span
+        self._workflow_start_times[instance_id] = time.time()
+
+        # Metrics
+        if self._enable_metrics:
+            self._workflow_started_counter.add(1, {"workflow_name": workflow_name})
+
+    async def on_workflow_complete(
+        self, instance_id: str, workflow_name: str, result: Any  # noqa: ARG002
+    ) -> None:
+        """End workflow span with success status."""
+        span = self._workflow_spans.pop(instance_id, None)
+        if span:
+            span.set_status(Status(StatusCode.OK))
+            span.end()
+
+        # Always cleanup start time
+        start_time = self._workflow_start_times.pop(instance_id, None)
+
+        # Metrics
+        if self._enable_metrics:
+            self._workflow_completed_counter.add(1, {"workflow_name": workflow_name})
+            if start_time:
+                duration = time.time() - start_time
+                self._workflow_duration_histogram.record(
+                    duration, {"workflow_name": workflow_name, "status": "completed"}
+                )
+
+    async def on_workflow_failed(
+        self, instance_id: str, workflow_name: str, error: Exception
+    ) -> None:
+        """End workflow span with error status."""
+        span = self._workflow_spans.pop(instance_id, None)
+        if span:
+            span.set_status(Status(StatusCode.ERROR, str(error)))
+            span.record_exception(error)
+            span.end()
+
+        # Always cleanup start time
+        start_time = self._workflow_start_times.pop(instance_id, None)
+
+        # Metrics
+        if self._enable_metrics:
+            self._workflow_failed_counter.add(
+                1,
+                {"workflow_name": workflow_name, "error_type": type(error).__name__},
+            )
+            if start_time:
+                duration = time.time() - start_time
+                self._workflow_duration_histogram.record(
+                    duration, {"workflow_name": workflow_name, "status": "failed"}
+                )
+
+    async def on_workflow_cancelled(
+        self, instance_id: str, workflow_name: str  # noqa: ARG002
+    ) -> None:
+        """End workflow span with cancelled status."""
+        span = self._workflow_spans.pop(instance_id, None)
+        if span:
+            span.set_attribute("edda.workflow.cancelled", True)
+            span.set_status(Status(StatusCode.OK, "Cancelled"))
+            span.end()
+
+        self._workflow_start_times.pop(instance_id, None)
+
+    # =========================================================================
+    # Activity Hooks
+    # =========================================================================
+
+    async def on_activity_start(
+        self,
+        instance_id: str,
+        activity_id: str,
+        activity_name: str,
+        is_replaying: bool,
+    ) -> None:
+        """Start an activity span as child of workflow span."""
+        parent_span = self._workflow_spans.get(instance_id)
+
+        # Create activity span with parent context
+        if parent_span:
+            ctx = trace.set_span_in_context(parent_span)
+            span = self._tracer.start_span(
+                name=f"activity:{activity_name}",
+                context=ctx,
+                attributes={
+                    "edda.activity.id": activity_id,
+                    "edda.activity.name": activity_name,
+                    "edda.activity.is_replaying": is_replaying,
+                    "edda.workflow.instance_id": instance_id,
+                },
+            )
+        else:
+            # No parent workflow span (edge case)
+            span = self._tracer.start_span(
+                name=f"activity:{activity_name}",
+                attributes={
+                    "edda.activity.id": activity_id,
+                    "edda.activity.name": activity_name,
+                    "edda.activity.is_replaying": is_replaying,
+                    "edda.workflow.instance_id": instance_id,
+                },
+            )
+
+        key = f"{instance_id}:{activity_id}"
+        self._activity_spans[key] = span
+        self._activity_start_times[key] = time.time()
+
+    async def on_activity_complete(
+        self,
+        instance_id: str,
+        activity_id: str,
+        activity_name: str,
+        result: Any,  # noqa: ARG002
+        cache_hit: bool,
+    ) -> None:
+        """End activity span with success status."""
+        key = f"{instance_id}:{activity_id}"
+        span = self._activity_spans.pop(key, None)
+        if span:
+            span.set_attribute("edda.activity.cache_hit", cache_hit)
+            span.set_status(Status(StatusCode.OK))
+            span.end()
+
+        # Metrics
+        if self._enable_metrics:
+            if cache_hit:
+                self._activity_cache_hit_counter.add(1, {"activity_name": activity_name})
+            else:
+                self._activity_executed_counter.add(1, {"activity_name": activity_name})
+                start_time = self._activity_start_times.pop(key, None)
+                if start_time:
+                    duration = time.time() - start_time
+                    self._activity_duration_histogram.record(
+                        duration, {"activity_name": activity_name}
+                    )
+
+    async def on_activity_failed(
+        self,
+        instance_id: str,
+        activity_id: str,
+        activity_name: str,  # noqa: ARG002
+        error: Exception,
+    ) -> None:
+        """End activity span with error status."""
+        key = f"{instance_id}:{activity_id}"
+        span = self._activity_spans.pop(key, None)
+        if span:
+            span.set_status(Status(StatusCode.ERROR, str(error)))
+            span.record_exception(error)
+            span.end()
+
+        self._activity_start_times.pop(key, None)
+
+    async def on_activity_retry(
+        self,
+        instance_id: str,
+        activity_id: str,
+        activity_name: str,  # noqa: ARG002
+        error: Exception,
+        attempt: int,
+        delay: float,
+    ) -> None:
+        """Record retry event on current activity span."""
+        key = f"{instance_id}:{activity_id}"
+        span = self._activity_spans.get(key)
+        if span:
+            span.add_event(
+                "retry",
+                attributes={
+                    "edda.retry.attempt": attempt,
+                    "edda.retry.delay_seconds": delay,
+                    "edda.retry.error": str(error),
+                    "edda.retry.error_type": type(error).__name__,
+                },
+            )
+
+    # =========================================================================
+    # Event Hooks
+    # =========================================================================
+
+    async def on_event_sent(
+        self,
+        event_type: str,
+        event_source: str,
+        event_data: dict[str, Any],  # noqa: ARG002
+    ) -> None:
+        """Record event sent as a short-lived span."""
+        with self._tracer.start_as_current_span(
+            name=f"event:send:{event_type}",
+            attributes={
+                "edda.event.type": event_type,
+                "edda.event.source": event_source,
+            },
+        ) as span:
+            span.set_status(Status(StatusCode.OK))
+
+    async def on_event_received(
+        self,
+        instance_id: str,
+        event_type: str,
+        event_data: dict[str, Any],  # noqa: ARG002
+    ) -> None:
+        """Record event received as an event on workflow span."""
+        parent_span = self._workflow_spans.get(instance_id)
+        if parent_span:
+            parent_span.add_event(
+                "event_received",
+                attributes={
+                    "edda.event.type": event_type,
+                },
+            )
+
+    # =========================================================================
+    # Trace Context Propagation
+    # =========================================================================
+
+    def _extract_trace_context(self, data: dict[str, Any]) -> Context | None:
+        """Extract W3C Trace Context from data dict."""
+        carrier: dict[str, str] = {}
+
+        # Check _trace_context nested dict (recommended)
+        if "_trace_context" in data:
+            tc = data["_trace_context"]
+            if isinstance(tc, dict):
+                carrier.update({k: v for k, v in tc.items() if k in ("traceparent", "tracestate")})
+
+        # Also check top-level keys
+        if "traceparent" in data:
+            carrier["traceparent"] = str(data["traceparent"])
+        if "tracestate" in data:
+            carrier["tracestate"] = str(data["tracestate"])
+
+        return self._propagator.extract(carrier) if carrier else None
+
+    def get_trace_context(self, instance_id: str) -> dict[str, str]:
+        """
+        Get W3C Trace Context for a workflow instance.
+
+        Use this to propagate trace context to external services or CloudEvents.
+
+        Args:
+            instance_id: Workflow instance ID
+
+        Returns:
+            dict with 'traceparent' and optionally 'tracestate' keys
+        """
+        carrier: dict[str, str] = {}
+        span = self._workflow_spans.get(instance_id)
+        if span:
+            ctx = trace.set_span_in_context(span)
+            self._propagator.inject(carrier, context=ctx)
+        return carrier
+
+
+# =============================================================================
+# Trace Context Propagation Helpers
+# =============================================================================
+
+
+def inject_trace_context(
+    hooks: OpenTelemetryHooks, instance_id: str, event_data: dict[str, Any]
+) -> dict[str, Any]:
+    """
+    Inject W3C Trace Context into event data for CloudEvents propagation.
+
+    Use this before calling send_event_transactional() to propagate trace
+    context across service boundaries.
+
+    Example::
+
+        from edda.integrations.opentelemetry import inject_trace_context
+        from edda.outbox.transactional import send_event_transactional
+
+        event_data = {"order_id": "ORD-123", "amount": 99.99}
+        event_data = inject_trace_context(hooks, ctx.instance_id, event_data)
+        await send_event_transactional(ctx, "payment.completed", "payment-service", event_data)
+
+    Args:
+        hooks: OpenTelemetryHooks instance
+        instance_id: Workflow instance ID
+        event_data: Event data dict to inject trace context into
+
+    Returns:
+        Updated event_data with _trace_context key
+    """
+    trace_context = hooks.get_trace_context(instance_id)
+    if trace_context:
+        event_data["_trace_context"] = trace_context
+    return event_data
+
+
+def extract_trace_context(event_data: dict[str, Any]) -> Context | None:
+    """
+    Extract W3C Trace Context from event data.
+
+    This is called automatically by OpenTelemetryHooks.on_workflow_start(),
+    but can also be used manually if needed.
+
+    Args:
+        event_data: Event data dict containing _trace_context
+
+    Returns:
+        OpenTelemetry Context or None if no trace context found
+    """
+    if not _OPENTELEMETRY_AVAILABLE:
+        return None
+
+    if "_trace_context" in event_data:
+        propagator = TraceContextTextMapPropagator()
+        return propagator.extract(event_data["_trace_context"])
+    return None

{edda_framework-0.4.0.dist-info → edda_framework-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.4.0
+Version: 0.6.0
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme
@@ -42,6 +42,10 @@ Provides-Extra: mcp
 Requires-Dist: mcp>=1.22.0; extra == 'mcp'
 Provides-Extra: mysql
 Requires-Dist: aiomysql>=0.2.0; extra == 'mysql'
+Provides-Extra: opentelemetry
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'opentelemetry'
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == 'opentelemetry'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'opentelemetry'
 Provides-Extra: postgresql
 Requires-Dist: asyncpg>=0.30.0; extra == 'postgresql'
 Provides-Extra: server
@@ -91,6 +95,28 @@ Edda excels at orchestrating **long-running workflows** that must survive failur
 - **🤖 AI Agent Workflows**: Orchestrate multi-step AI tasks (LLM calls, tool usage, long-running inference)
 - **📡 Event-Driven Workflows**: React to external events with guaranteed delivery and automatic retry
 
+### Business Process Automation
+
+Edda's waiting functions make it ideal for time-based and event-driven business processes:
+
+- **📧 User Onboarding**: Send reminders if users haven't completed setup after N days
+- **🎁 Campaign Processing**: Evaluate conditions and notify winners after campaign ends
+- **💳 Payment Reminders**: Send escalating reminders before payment deadlines
+- **📦 Scheduled Notifications**: Shipping updates, subscription renewals, appointment reminders
+
+**Waiting functions**:
+- `wait_timer(duration_seconds)`: Wait for a relative duration
+- `wait_until(until_time)`: Wait until an absolute datetime (e.g., campaign end date)
+- `wait_event(event_type)`: Wait for external events (near real-time response)
+
+```python
+@workflow
+async def onboarding_reminder(ctx: WorkflowContext, user_id: str):
+    await wait_timer(ctx, duration_seconds=3*24*60*60)  # Wait 3 days
+    if not await check_completed(ctx, user_id):
+        await send_reminder(ctx, user_id)
+```
+
 **Key benefit**: Workflows **never lose progress** - crashes and restarts are handled automatically through deterministic replay.
 
 ## Architecture
@@ -683,7 +709,7 @@ def process_payment(ctx: WorkflowContext, amount: float) -> dict:
 @workflow
 async def payment_workflow(ctx: WorkflowContext, order_id: str) -> dict:
     # Workflows still use async (for deterministic replay)
-    result = await process_payment(ctx, 99.99, activity_id="pay:1")
+    result = await process_payment(ctx, 99.99)
     return result
 ```
 
@@ -722,13 +748,14 @@ if __name__ == "__main__":
 
 ### Auto-Generated Tools
 
-Each `@durable_tool` automatically generates **three MCP tools**:
+Each `@durable_tool` automatically generates **four MCP tools**:
 
 1. **Main tool** (`process_order`): Starts the workflow, returns instance ID
-2. **Status tool** (`process_order_status`): Checks workflow progress
+2. **Status tool** (`process_order_status`): Checks workflow progress with completed activity count and suggested poll interval
 3. **Result tool** (`process_order_result`): Gets final result when completed
+4. **Cancel tool** (`process_order_cancel`): Cancels workflow if running or waiting, executes compensation handlers
 
-This enables AI assistants to work with workflows that take minutes, hours, or even days to complete.
+This enables AI assistants to work with workflows that take minutes, hours, or even days to complete, with full control over the workflow lifecycle.
 
 ### MCP Prompts
 

{edda_framework-0.4.0.dist-info → edda_framework-0.6.0.dist-info}/RECORD

@@ -1,11 +1,11 @@
 edda/__init__.py,sha256=gmJd0ooVbGNMOLlSj-r6rEt3IkY-FZYCFjhWjIltqlk,1657
 edda/activity.py,sha256=nRm9eBrr0lFe4ZRQ2whyZ6mo5xd171ITIVhqytUhOpw,21025
-edda/app.py,sha256=YxURvhaC1dKcymOwuS1PHU6_iOl_5cZWse2vAKSyX8w,37471
+edda/app.py,sha256=8FKx9Kspbm5Fz-QDz4DgncNkkgdZkij209LHllWkRw4,38288
 edda/compensation.py,sha256=CmnyJy4jAklVrtLJodNOcj6vxET6pdarxM1Yx2RHlL4,11898
 edda/context.py,sha256=YZKBNtblRcaFqte1Y9t2cIP3JHzK-5Tu40x5i5FHtnU,17789
 edda/events.py,sha256=KN06o-Umkwkg9-TwbN4jr1uBZrBrvVSc6m8mOlQGXkA,18043
 edda/exceptions.py,sha256=-ntBLGpVQgPFG5N1o8m_7weejAYkNrUdxTkOP38vsHk,1766
-edda/hooks.py,sha256=eryLQMU1wwfeJkWUPBnq9olFigU6d4TKSRgcWK77a5U,8065
+edda/hooks.py,sha256=HUZ6FTM__DZjwuomDfTDEroQ3mugEPuJHcGm7CTQNvg,8193
 edda/locking.py,sha256=l3YM7zdERizw27jQXfLN7EmcMcrJSVzd7LD8hhsXvIM,11003
 edda/pydantic_utils.py,sha256=dGVPNrrttDeq1k233PopCtjORYjZitsgASPfPnO6R10,9056
 edda/replay.py,sha256=5RIRd0q2ZrH9iiiy35eOUii2cipYg9dlua56OAXvIk4,32499
@@ -14,8 +14,10 @@ edda/workflow.py,sha256=daSppYAzgXkjY_9-HS93Zi7_tPR6srmchxY5YfwgU-4,7239
 edda/wsgi.py,sha256=1pGE5fhHpcsYnDR8S3NEFKWUs5P0JK4roTAzX9BsIj0,2391
 edda/integrations/__init__.py,sha256=F_CaTvlDEbldfOpPKq_U9ve1E573tS6XzqXnOtyHcXI,33
 edda/integrations/mcp/__init__.py,sha256=YK-8m0DIdP-RSqewlIX7xnWU7TD3NioCiW2_aZSgnn8,1232
-edda/integrations/mcp/decorators.py,sha256=UTBb-Un2JK938pDZmANOvfsdKOMI2AF9yGtfSuy8VrE,6284
-edda/integrations/mcp/server.py,sha256=pzCG46Zko9hHmQ3REbo1w3A23SjrGFLiZupwSkIPhOA,13942
+edda/integrations/mcp/decorators.py,sha256=31SmbDwmHEGvUNa3aaatW91hBkpnS5iN9uy47dID3J4,10037
+edda/integrations/mcp/server.py,sha256=Q5r4AbMn-9gBcy2CZocbgW7O0fn7Qb4e9CBJa1FEmzU,14507
+edda/integrations/opentelemetry/__init__.py,sha256=x1_PyyygGDW-rxQTwoIrGzyjKErXHOOKdquFAMlCOAo,906
+edda/integrations/opentelemetry/hooks.py,sha256=FBYnSZBh8_0vw9M1E2AbJrx1cTTsKeiHf5wspr0UnzU,21288
 edda/outbox/__init__.py,sha256=azXG1rtheJEjOyoWmMsBeR2jp8Bz02R3wDEd5tQnaWA,424
 edda/outbox/relayer.py,sha256=2tnN1aOQ8pKWfwEGIlYwYLLwyOKXBjZ4XZsIr1HjgK4,9454
 edda/outbox/transactional.py,sha256=LFfUjunqRlGibaINi-efGXFFivWGO7v3mhqrqyGW6Nw,3808
@@ -33,8 +35,8 @@ edda/viewer_ui/data_service.py,sha256=mXV6bL6REa_UKsk8xMGBIFbsbLpIxe91lX3wgn-FOj
 edda/visualizer/__init__.py,sha256=DOpDstNhR0VcXAs_eMKxaL30p_0u4PKZ4o2ndnYhiRo,343
 edda/visualizer/ast_analyzer.py,sha256=plmx7C9X_X35xLY80jxOL3ljg3afXxBePRZubqUIkxY,13663
 edda/visualizer/mermaid_generator.py,sha256=XWa2egoOTNDfJEjPcwoxwQmblUqXf7YInWFjFRI1QGo,12457
-edda_framework-0.4.0.dist-info/METADATA,sha256=YEsevYgVMtBEBJlAhQL1lALOOiNrejsC9Z6QpyZsFRg,30272
-edda_framework-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-edda_framework-0.4.0.dist-info/entry_points.txt,sha256=dPH47s6UoJgUZxHoeSMqZsQkLaSE-SGLi-gh88k2WrU,48
-edda_framework-0.4.0.dist-info/licenses/LICENSE,sha256=udxb-V7_cYKTHqW7lNm48rxJ-Zpf0WAY_PyGDK9BPCo,1069
-edda_framework-0.4.0.dist-info/RECORD,,
+edda_framework-0.6.0.dist-info/METADATA,sha256=sxR8GtZNOzswVHIh8n_uAojtOrUEn_mXbT9Li5IvTnk,31702
+edda_framework-0.6.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+edda_framework-0.6.0.dist-info/entry_points.txt,sha256=dPH47s6UoJgUZxHoeSMqZsQkLaSE-SGLi-gh88k2WrU,48
+edda_framework-0.6.0.dist-info/licenses/LICENSE,sha256=udxb-V7_cYKTHqW7lNm48rxJ-Zpf0WAY_PyGDK9BPCo,1069
+edda_framework-0.6.0.dist-info/RECORD,,