edda-framework 0.3.1__py3-none-any.whl → 0.5.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

@@ -6,11 +6,10 @@ import inspect
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any, cast
 
-from edda.workflow import workflow
+from edda.workflow import Workflow, workflow
 
 if TYPE_CHECKING:
     from edda.integrations.mcp.server import EddaMCPServer
-    from edda.workflow import Workflow
 
 
 def create_durable_tool(
@@ -98,7 +97,7 @@ def create_durable_tool(
     async def status_tool(instance_id: str) -> dict[str, Any]:
         """Check workflow status."""
         try:
-            instance = await server._edda_app.storage.get_instance(instance_id)
+            instance = await server.storage.get_instance(instance_id)
             if instance is None:
                 return {
                     "content": [
@@ -142,7 +141,7 @@ def create_durable_tool(
     async def result_tool(instance_id: str) -> dict[str, Any]:
         """Get workflow result (if completed)."""
         try:
-            instance = await server._edda_app.storage.get_instance(instance_id)
+            instance = await server.storage.get_instance(instance_id)
             if instance is None:
                 return {
                     "content": [

edda/integrations/mcp/server.py

@@ -3,11 +3,14 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from edda.app import EddaApp
 from edda.workflow import Workflow
 
+if TYPE_CHECKING:
+    from edda.storage.protocol import StorageProtocol
+
 try:
     from mcp.server.fastmcp import FastMCP  # type: ignore[import-not-found]
 except ImportError as e:
@@ -45,7 +48,13 @@ class EddaMCPServer:
 
         # Deploy with uvicorn (HTTP transport)
         if __name__ == "__main__":
+            import asyncio
             import uvicorn
+
+            async def startup():
+                await server.initialize()
+
+            asyncio.run(startup())
             uvicorn.run(server.asgi_app(), host="0.0.0.0", port=8000)
 
         # Or deploy with stdio (for MCP clients, e.g., Claude Desktop)
@@ -97,6 +106,22 @@ class EddaMCPServer:
         # Registry of durable tools (workflow_name -> Workflow instance)
         self._workflows: dict[str, Workflow] = {}
 
+    @property
+    def storage(self) -> StorageProtocol:
+        """
+        Access workflow storage for querying instances and history.
+
+        Returns:
+            StorageProtocol: Storage backend for workflow state
+
+        Example:
+            ```python
+            instance = await server.storage.get_instance(instance_id)
+            history = await server.storage.get_history(instance_id)
+            ```
+        """
+        return self._edda_app.storage
+
     def durable_tool(
         self,
         func: Callable[..., Any] | None = None,
@@ -135,6 +160,59 @@ class EddaMCPServer:
             return decorator
         return decorator(func)
 
+    def prompt(
+        self,
+        func: Callable[..., Any] | None = None,
+        *,
+        description: str = "",
+    ) -> Callable[..., Any]:
+        """
+                Decorator to define a prompt template.
+
+                Prompts can access workflow state to generate dynamic, context-aware
+                prompts for AI clients (Claude Desktop, etc.).
+
+                Args:
+                    func: Prompt function (async or sync)
+                    description: Prompt description for MCP clients
+
+                Returns:
+                    Decorated function
+
+                Example:
+                    ```python
+                    from fastmcp.prompts.prompt import PromptMessage, TextContent
+
+                    @server.prompt(description="Analyze workflow results")
+                    async def analyze_workflow(instance_id: str) -> PromptMessage:
+                        '''Generate a prompt to analyze a specific workflow execution.'''
+                        instance = await server.storage.get_instance(instance_id)
+                        history = await server.storage.get_history(instance_id)
+
+                        text = f'''Analyze this workflow:
+
+        Instance ID: {instance_id}
+        Status: {instance['status']}
+        Activities: {len(history)}
+
+        Please identify any issues or optimization opportunities.'''
+
+                        return PromptMessage(
+                            role="user",
+                            content=TextContent(type="text", text=text)
+                        )
+                    ```
+        """
+
+        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))
+
+        if func is None:
+            return decorator
+        return decorator(func)
+
     def asgi_app(self) -> Callable[..., Any]:
         """
         Create ASGI application with MCP + CloudEvents support.
@@ -221,11 +299,9 @@ class EddaMCPServer:
         """
         Initialize the EddaApp (setup replay engine, storage, etc.).
 
-        This method must be called before running the server in stdio mode.
-        For HTTP mode (asgi_app()), initialization happens automatically
-        when the ASGI app is deployed.
+        This method must be called before running the server in either stdio or HTTP mode.
 
-        Example:
+        Example (stdio mode):
             ```python
             async def main():
                 await server.initialize()
@@ -235,9 +311,85 @@ class EddaMCPServer:
                 import asyncio
                 asyncio.run(main())
             ```
+
+        Example (HTTP mode):
+            ```python
+            import asyncio
+            import uvicorn
+
+            async def startup():
+                await server.initialize()
+
+            asyncio.run(startup())
+            uvicorn.run(server.asgi_app(), host="0.0.0.0", port=8000)
+            ```
         """
         await self._edda_app.initialize()
 
+    async def shutdown(self) -> None:
+        """
+        Shutdown the server and cleanup resources.
+
+        Stops background tasks (auto-resume, timer checks, event timeouts),
+        closes storage connections, and performs graceful shutdown.
+
+        This method should be called when the server is shutting down.
+
+        Example (stdio mode):
+            ```python
+            import signal
+            import asyncio
+
+            async def main():
+                server = EddaMCPServer(...)
+                await server.initialize()
+
+                # Setup signal handlers for graceful shutdown
+                loop = asyncio.get_running_loop()
+                shutdown_event = asyncio.Event()
+
+                def signal_handler():
+                    shutdown_event.set()
+
+                for sig in (signal.SIGTERM, signal.SIGINT):
+                    loop.add_signal_handler(sig, signal_handler)
+
+                # Run server
+                try:
+                    await server.run_stdio()
+                finally:
+                    await server.shutdown()
+
+            if __name__ == "__main__":
+                asyncio.run(main())
+            ```
+
+        Example (HTTP mode with uvicorn):
+            ```python
+            import asyncio
+            import uvicorn
+
+            async def startup():
+                await server.initialize()
+
+            async def shutdown_handler():
+                await server.shutdown()
+
+            # Use uvicorn lifecycle events
+            config = uvicorn.Config(
+                server.asgi_app(),
+                host="0.0.0.0",
+                port=8000,
+            )
+            server_instance = uvicorn.Server(config)
+
+            # Uvicorn handles SIGTERM/SIGINT automatically
+            await server_instance.serve()
+            await shutdown_handler()
+            ```
+        """
+        await self._edda_app.shutdown()
+
     async def run_stdio(self) -> None:
         """
         Run MCP server with stdio transport (for MCP clients, e.g., Claude Desktop).

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.3.1.dist-info → edda_framework-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.3.1
+Version: 0.5.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
@@ -730,6 +756,32 @@ Each `@durable_tool` automatically generates **three MCP tools**:
 
 This enables AI assistants to work with workflows that take minutes, hours, or even days to complete.
 
+### MCP Prompts
+
+Define reusable prompt templates that can access workflow state:
+
+```python
+from mcp.server.fastmcp.prompts.base import UserMessage
+from mcp.types import TextContent
+
+@server.prompt(description="Analyze a workflow execution")
+async def analyze_workflow(instance_id: str) -> UserMessage:
+    """Generate analysis prompt for a specific workflow."""
+    instance = await server.storage.get_instance(instance_id)
+    history = await server.storage.get_history(instance_id)
+
+    text = f"""Analyze this workflow:
+**Status**: {instance['status']}
+**Activities**: {len(history)}
+**Result**: {instance.get('output_data')}
+
+Please provide insights and optimization suggestions."""
+
+    return UserMessage(content=TextContent(type="text", text=text))
+```
+
+AI clients can use these prompts to generate context-aware analysis of your workflows.
+
 **For detailed documentation**, see [MCP Integration Guide](docs/integrations/mcp.md).
 
 ## Observability Hooks

{edda_framework-0.3.1.dist-info → edda_framework-0.5.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=MIHDrcP_OelxOXISkX6a561Gl3DcVNT9yRakd4O4COo,6333
-edda/integrations/mcp/server.py,sha256=sSemdl7uR133YgZn34uUWzjJUqnPi13HauzXOrf8Kq8,9175
+edda/integrations/mcp/decorators.py,sha256=UTBb-Un2JK938pDZmANOvfsdKOMI2AF9yGtfSuy8VrE,6284
+edda/integrations/mcp/server.py,sha256=pzCG46Zko9hHmQ3REbo1w3A23SjrGFLiZupwSkIPhOA,13942
+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.3.1.dist-info/METADATA,sha256=uOiXJuq8Xy4fgfyblF3FwbJpo-cJrXVWgHhoIjdIi9s,29421
-edda_framework-0.3.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-edda_framework-0.3.1.dist-info/entry_points.txt,sha256=dPH47s6UoJgUZxHoeSMqZsQkLaSE-SGLi-gh88k2WrU,48
-edda_framework-0.3.1.dist-info/licenses/LICENSE,sha256=udxb-V7_cYKTHqW7lNm48rxJ-Zpf0WAY_PyGDK9BPCo,1069
-edda_framework-0.3.1.dist-info/RECORD,,
+edda_framework-0.5.0.dist-info/METADATA,sha256=GfZ0zYUy_g4zjV_OkYPPmNRTwIxZb77nh-aaS6Z_OYE,31503
+edda_framework-0.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+edda_framework-0.5.0.dist-info/entry_points.txt,sha256=dPH47s6UoJgUZxHoeSMqZsQkLaSE-SGLi-gh88k2WrU,48
+edda_framework-0.5.0.dist-info/licenses/LICENSE,sha256=udxb-V7_cYKTHqW7lNm48rxJ-Zpf0WAY_PyGDK9BPCo,1069
+edda_framework-0.5.0.dist-info/RECORD,,