edda-framework 0.5.0__tar.gz → 0.6.0__tar.gz

{edda_framework-0.5.0 → edda_framework-0.6.0}/.github/workflows/ci.yml

@@ -53,8 +53,8 @@ jobs:
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
 
-      - name: Install dependencies (all database drivers)
-        run: uv sync --extra dev --extra postgresql --extra mysql
+      - name: Install dependencies (all database drivers and opentelemetry)
+        run: uv sync --extra dev --extra postgresql --extra mysql --extra opentelemetry
 
       - name: Run tests (all databases)
         env:

{edda_framework-0.5.0 → edda_framework-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.5.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
@@ -709,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
 ```
 
@@ -748,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.5.0 → edda_framework-0.6.0}/README.md

@@ -653,7 +653,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
 ```
 
@@ -692,13 +692,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.5.0 → edda_framework-0.6.0}/docs/integrations/mcp.md

@@ -7,10 +7,11 @@ Edda provides seamless integration with the [Model Context Protocol (MCP)](https
 MCP is a standardized protocol for AI tool integration. Edda's MCP integration automatically converts your durable workflows into MCP-compliant tools that:
 
 - **Start workflows** and return instance IDs immediately
-- **Check workflow status** to monitor progress
+- **Check workflow status** to monitor progress with completed activity count and suggested poll interval
 - **Retrieve results** when workflows complete
+- **Cancel workflows** if running or waiting, with automatic compensation execution
 
-This enables AI assistants to work with long-running processes that may take minutes, hours, or even days to complete.
+This enables AI assistants to work with long-running processes that may take minutes, hours, or even days to complete, with full control over the workflow lifecycle.
 
 ## Installation
 
@@ -97,7 +98,7 @@ Add to your MCP client configuration (e.g., Claude Desktop: `~/Library/Applicati
 
 ## Auto-Generated Tools
 
-Each `@durable_tool` automatically generates **three MCP tools**:
+Each `@durable_tool` automatically generates **four MCP tools**:
 
 ### 1. Main Tool: Start Workflow
 
@@ -125,12 +126,16 @@ Input: {"instance_id": "abc123..."}
 Output: {
   "content": [{
     "type": "text",
-    "text": "Workflow Status: running\nCurrent Activity: payment:1\nInstance ID: abc123..."
+    "text": "Workflow Status: running\nCurrent Activity: payment:1\nCompleted Activities: 1\nSuggested Poll Interval: 5000ms\nInstance ID: abc123..."
   }],
   "isError": false
 }
 ```
 
+The status tool provides progress metadata for efficient polling:
+- **Completed Activities**: Number of activities that have finished
+- **Suggested Poll Interval**: Recommended wait time before checking again (5000ms for running, 10000ms for waiting)
+
 ### 3. Result Tool: Get Final Result
 
 ```
@@ -147,6 +152,27 @@ Output: {
 }
 ```
 
+### 4. Cancel Tool: Stop Workflow
+
+```
+Tool Name: process_order_cancel
+Description: Cancel process_order workflow (if running or waiting)
+
+Input: {"instance_id": "abc123..."}
+Output: {
+  "content": [{
+    "type": "text",
+    "text": "Workflow 'process_order' cancelled successfully.\nInstance ID: abc123...\nCompensations executed.\n\nThe workflow has been stopped and any side effects have been rolled back."
+  }],
+  "isError": false
+}
+```
+
+The cancel tool:
+- Only works on workflows with status `running`, `waiting_for_event`, or `waiting_for_timer`
+- Automatically executes SAGA compensation transactions to roll back side effects
+- Returns an error for already completed, failed, or cancelled workflows
+
 ## Advanced Configuration
 
 ### Authentication

{edda_framework-0.5.0 → edda_framework-0.6.0}/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_framework-0.5.0 → edda_framework-0.6.0}/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_framework-0.5.0 → edda_framework-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "edda-framework"
-version = "0.5.0"
+version = "0.6.0"
 description = "Lightweight Durable Execution Framework"
 authors = [
     { name = "Yasushi Itoh", email = "6240399+i2y@users.noreply.github.com" }

edda_framework-0.6.0/tests/integrations/mcp/test_cancel.py

@@ -0,0 +1,166 @@
+"""Tests for MCP cancel tool functionality."""
+
+import asyncio
+
+import pytest
+
+# Skip all tests if mcp is not installed
+pytest.importorskip("mcp")
+
+from edda import WorkflowContext, activity
+from edda.compensation import register_compensation
+from edda.events import wait_event
+from edda.integrations.mcp import EddaMCPServer
+
+
+@pytest.fixture
+async def mcp_server_with_cancellable_tool():
+    """Create MCP server with a cancellable durable tool."""
+    server = EddaMCPServer(
+        name="Cancel Test Service",
+        db_url="sqlite+aiosqlite:///:memory:",
+    )
+
+    # Track compensation execution
+    compensations_executed: list[str] = []
+
+    @activity
+    async def process_step(ctx: WorkflowContext, value: str):
+        return {"processed": value.upper()}
+
+    @activity
+    async def compensate_step(ctx: WorkflowContext):
+        compensations_executed.append("step_compensated")
+
+    @server.durable_tool(description="Cancellable workflow")
+    async def cancellable_workflow(ctx: WorkflowContext, value: str):
+        result = await process_step(ctx, value)
+        await register_compensation(ctx, compensate_step)
+        # Wait for an event that won't come (workflow will be cancelled)
+        await wait_event(ctx, "test_event")
+        return result
+
+    @server.durable_tool(description="Quick workflow")
+    async def quick_workflow(ctx: WorkflowContext, value: str):
+        result = await process_step(ctx, value)
+        return result
+
+    # Initialize the EddaApp
+    await server._edda_app.initialize()
+    server._compensations_executed = compensations_executed
+    yield server
+    # Cleanup after tests
+    await server.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_cancel_tool_registered(mcp_server_with_cancellable_tool):
+    """Test that cancel tool is registered for durable_tool."""
+    server = mcp_server_with_cancellable_tool
+
+    # Check that 4 tools are registered per workflow
+    # cancellable_workflow: main, status, result, cancel
+    # quick_workflow: main, status, result, cancel
+    # We verify by checking if the workflows exist in registry
+    assert "cancellable_workflow" in server._workflows
+    assert "quick_workflow" in server._workflows
+
+
+@pytest.mark.asyncio
+async def test_cancel_waiting_workflow(mcp_server_with_cancellable_tool):
+    """Test cancelling a workflow waiting for an event."""
+    server = mcp_server_with_cancellable_tool
+    workflow = server._workflows["cancellable_workflow"]
+
+    # Start workflow (will start processing and wait for event)
+    instance_id = await workflow.start(value="test")
+
+    # Give it time to reach wait_event
+    await asyncio.sleep(0.2)
+
+    # Verify workflow is waiting
+    instance = await server.storage.get_instance(instance_id)
+    assert instance["status"] == "waiting_for_event"
+
+    # Cancel the workflow
+    success = await server.replay_engine.cancel_workflow(instance_id, "mcp_user")
+
+    assert success is True
+
+    # Verify workflow is cancelled
+    instance = await server.storage.get_instance(instance_id)
+    assert instance["status"] == "cancelled"
+
+
+@pytest.mark.asyncio
+async def test_cancel_nonexistent_instance(mcp_server_with_cancellable_tool):
+    """Test cancelling a workflow that doesn't exist returns False."""
+    server = mcp_server_with_cancellable_tool
+
+    # Try to cancel non-existent workflow
+    success = await server.replay_engine.cancel_workflow("nonexistent-id", "mcp_user")
+
+    assert success is False
+
+
+@pytest.mark.asyncio
+async def test_cancel_completed_workflow(mcp_server_with_cancellable_tool):
+    """Test that completed workflows cannot be cancelled."""
+    server = mcp_server_with_cancellable_tool
+    workflow = server._workflows["quick_workflow"]
+
+    # Start and wait for completion
+    instance_id = await workflow.start(value="complete")
+
+    # Give it time to complete
+    await asyncio.sleep(0.2)
+
+    # Verify workflow is completed
+    instance = await server.storage.get_instance(instance_id)
+    assert instance["status"] == "completed"
+
+    # Try to cancel - should return False
+    success = await server.replay_engine.cancel_workflow(instance_id, "mcp_user")
+
+    assert success is False
+
+    # Status should still be completed
+    instance = await server.storage.get_instance(instance_id)
+    assert instance["status"] == "completed"
+
+
+@pytest.mark.asyncio
+async def test_cancel_already_cancelled_workflow(mcp_server_with_cancellable_tool):
+    """Test that cancelling already cancelled workflow is idempotent."""
+    server = mcp_server_with_cancellable_tool
+    workflow = server._workflows["cancellable_workflow"]
+
+    # Start workflow
+    instance_id = await workflow.start(value="idempotent")
+
+    # Give it time to reach wait_event
+    await asyncio.sleep(0.2)
+
+    # Cancel first time
+    success1 = await server.replay_engine.cancel_workflow(instance_id, "mcp_user")
+    assert success1 is True
+
+    # Cancel second time - should return False (already cancelled)
+    success2 = await server.replay_engine.cancel_workflow(instance_id, "mcp_user")
+    assert success2 is False
+
+    # Status should still be cancelled
+    instance = await server.storage.get_instance(instance_id)
+    assert instance["status"] == "cancelled"
+
+
+@pytest.mark.asyncio
+async def test_replay_engine_property(mcp_server_with_cancellable_tool):
+    """Test that replay_engine property is accessible on EddaMCPServer."""
+    server = mcp_server_with_cancellable_tool
+
+    # replay_engine should be accessible after initialization
+    assert server.replay_engine is not None
+
+    # Should be the same instance as EddaApp's replay_engine
+    assert server.replay_engine is server._edda_app.replay_engine

{edda_framework-0.5.0 → edda_framework-0.6.0}/tests/integrations/mcp/test_integration.py

@@ -26,7 +26,7 @@ async def mcp_server_with_tool():
 
     @server.durable_tool(description="Process input value")
     async def process_value(ctx: WorkflowContext, value: str):
-        result = await process_step(ctx, value, activity_id="process:1")
+        result = await process_step(ctx, value)
         return result
 
     # Initialize the EddaApp
@@ -132,7 +132,7 @@ async def test_result_tool_before_completion(mcp_server_with_tool):
 
     @server.durable_tool(description="Long workflow")
     async def long_workflow(ctx: WorkflowContext):
-        result = await long_running_step(ctx, activity_id="long:1")
+        result = await long_running_step(ctx)
         return result
 
     workflow = server._workflows["long_workflow"]

{edda_framework-0.5.0 → edda_framework-0.6.0}/tests/integrations/mcp/test_jsonrpc.py

@@ -26,7 +26,7 @@ async def mcp_server():
 
     @server.durable_tool(description="Greet a user")
     async def greet_workflow(ctx: WorkflowContext, name: str):
-        result = await greet_user(ctx, name, activity_id="greet:1")
+        result = await greet_user(ctx, name)
         return result
 
     # Initialize the EddaApp

{edda_framework-0.5.0 → edda_framework-0.6.0}/tests/integrations/mcp/test_prompts.py

@@ -54,7 +54,7 @@ async def test_prompt_with_workflow_state(mcp_server):
 
     @mcp_server.durable_tool(description="Test workflow")
     async def test_workflow(ctx: WorkflowContext, value: str):
-        result = await test_activity(ctx, value, activity_id="test:1")
+        result = await test_activity(ctx, value)
         return result
 
     # Start workflow
@@ -182,8 +182,8 @@ async def test_prompt_accesses_workflow_history(mcp_server):
 
     @mcp_server.durable_tool(description="Multi-step workflow")
     async def multi_step(ctx: WorkflowContext):
-        await step_one(ctx, activity_id="step1:1")
-        await step_two(ctx, activity_id="step2:1")
+        await step_one(ctx)
+        await step_two(ctx)
         return {"completed": True}
 
     # Start and complete workflow