edda-framework 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

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/storage/protocol.py

@@ -238,20 +238,34 @@ class StorageProtocol(Protocol):
     async def list_instances(
         self,
         limit: int = 50,
+        page_token: str | None = None,
         status_filter: str | None = None,
-    ) -> list[dict[str, Any]]:
+        workflow_name_filter: str | None = None,
+        instance_id_filter: str | None = None,
+        started_after: datetime | None = None,
+        started_before: datetime | None = None,
+    ) -> dict[str, Any]:
         """
-        List workflow instances with optional filtering.
+        List workflow instances with cursor-based pagination and filtering.
 
         This method JOINs workflow_instances with workflow_definitions to
         return instances along with their source code.
 
         Args:
-            limit: Maximum number of instances to return
+            limit: Maximum number of instances to return per page
+            page_token: Cursor for pagination (format: "ISO_DATETIME||INSTANCE_ID")
             status_filter: Optional status filter (e.g., "running", "completed", "failed")
+            workflow_name_filter: Optional workflow name filter (partial match, case-insensitive)
+            instance_id_filter: Optional instance ID filter (partial match, case-insensitive)
+            started_after: Filter instances started after this datetime (inclusive)
+            started_before: Filter instances started before this datetime (inclusive)
 
         Returns:
-            List of workflow instances, ordered by started_at DESC.
+            Dictionary containing:
+            - instances: List of workflow instances, ordered by started_at DESC
+            - next_page_token: Cursor for the next page, or None if no more pages
+            - has_more: Boolean indicating if there are more pages
+
             Each instance contains: instance_id, workflow_name, source_hash,
             owner_service, status, current_activity_id, started_at, updated_at,
             input_data, source_code, output_data, locked_by, locked_at

edda/storage/sqlalchemy_storage.py

@@ -774,11 +774,17 @@ class SQLAlchemyStorage:
     async def list_instances(
         self,
         limit: int = 50,
+        page_token: str | None = None,
         status_filter: str | None = None,
-    ) -> list[dict[str, Any]]:
-        """List workflow instances with optional filtering."""
+        workflow_name_filter: str | None = None,
+        instance_id_filter: str | None = None,
+        started_after: datetime | None = None,
+        started_before: datetime | None = None,
+    ) -> dict[str, Any]:
+        """List workflow instances with cursor-based pagination and filtering."""
         session = self._get_session_for_operation()
         async with self._session_scope(session) as session:
+            # Base query with JOIN
             stmt = (
                 select(WorkflowInstance, WorkflowDefinition.source_code)
                 .join(
@@ -788,17 +794,105 @@ class SQLAlchemyStorage:
                         WorkflowInstance.source_hash == WorkflowDefinition.source_hash,
                     ),
                 )
-                .order_by(WorkflowInstance.started_at.desc())
-                .limit(limit)
+                .order_by(
+                    WorkflowInstance.started_at.desc(),
+                    WorkflowInstance.instance_id.desc(),
+                )
             )
 
+            # Apply cursor-based pagination (page_token format: "ISO_DATETIME||INSTANCE_ID")
+            if page_token:
+                # Parse page_token: || separates datetime and instance_id
+                separator = "||"
+                if separator in page_token:
+                    cursor_time_str, cursor_id = page_token.split(separator, 1)
+                    cursor_time = datetime.fromisoformat(cursor_time_str)
+                    # Use _make_datetime_comparable for SQLite compatibility
+                    started_at_comparable = self._make_datetime_comparable(
+                        WorkflowInstance.started_at
+                    )
+                    # For SQLite, also wrap the cursor_time in func.datetime()
+                    cursor_time_comparable: Any
+                    if self.engine.dialect.name == "sqlite":
+                        cursor_time_comparable = func.datetime(cursor_time_str)
+                    else:
+                        cursor_time_comparable = cursor_time
+                    # For DESC order, we want rows where (started_at, instance_id) < cursor
+                    stmt = stmt.where(
+                        or_(
+                            started_at_comparable < cursor_time_comparable,
+                            and_(
+                                started_at_comparable == cursor_time_comparable,
+                                WorkflowInstance.instance_id < cursor_id,
+                            ),
+                        )
+                    )
+
+            # Apply status filter
             if status_filter:
                 stmt = stmt.where(WorkflowInstance.status == status_filter)
 
+            # Apply workflow name and/or instance ID filter (partial match, case-insensitive)
+            # When both filters have the same value (unified search), use OR logic
+            if workflow_name_filter and instance_id_filter:
+                if workflow_name_filter == instance_id_filter:
+                    # Unified search: match either workflow name OR instance ID
+                    stmt = stmt.where(
+                        or_(
+                            WorkflowInstance.workflow_name.ilike(f"%{workflow_name_filter}%"),
+                            WorkflowInstance.instance_id.ilike(f"%{instance_id_filter}%"),
+                        )
+                    )
+                else:
+                    # Separate filters: match both (AND logic)
+                    stmt = stmt.where(
+                        WorkflowInstance.workflow_name.ilike(f"%{workflow_name_filter}%")
+                    )
+                    stmt = stmt.where(WorkflowInstance.instance_id.ilike(f"%{instance_id_filter}%"))
+            elif workflow_name_filter:
+                stmt = stmt.where(WorkflowInstance.workflow_name.ilike(f"%{workflow_name_filter}%"))
+            elif instance_id_filter:
+                stmt = stmt.where(WorkflowInstance.instance_id.ilike(f"%{instance_id_filter}%"))
+
+            # Apply date range filters (use _make_datetime_comparable for SQLite)
+            if started_after or started_before:
+                started_at_comparable = self._make_datetime_comparable(WorkflowInstance.started_at)
+                if started_after:
+                    started_after_comparable: Any
+                    if self.engine.dialect.name == "sqlite":
+                        started_after_comparable = func.datetime(started_after.isoformat())
+                    else:
+                        started_after_comparable = started_after
+                    stmt = stmt.where(started_at_comparable >= started_after_comparable)
+                if started_before:
+                    started_before_comparable: Any
+                    if self.engine.dialect.name == "sqlite":
+                        started_before_comparable = func.datetime(started_before.isoformat())
+                    else:
+                        started_before_comparable = started_before
+                    stmt = stmt.where(started_at_comparable <= started_before_comparable)
+
+            # Fetch limit+1 to determine if there are more pages
+            stmt = stmt.limit(limit + 1)
+
             result = await session.execute(stmt)
             rows = result.all()
 
-            return [
+            # Determine has_more and next_page_token
+            has_more = len(rows) > limit
+            if has_more:
+                rows = rows[:limit]  # Trim to actual limit
+
+            # Generate next_page_token from last row
+            next_page_token: str | None = None
+            if has_more and rows:
+                last_instance = rows[-1][0]
+                # Format: ISO_DATETIME||INSTANCE_ID (using || as separator)
+                next_page_token = (
+                    f"{last_instance.started_at.isoformat()}||{last_instance.instance_id}"
+                )
+
+            instances = [
                 {
                     "instance_id": instance.instance_id,
                     "workflow_name": instance.workflow_name,
@@ -820,6 +914,12 @@ class SQLAlchemyStorage:
                 for instance, source_code in rows
             ]
 
+            return {
+                "instances": instances,
+                "next_page_token": next_page_token,
+                "has_more": has_more,
+            }
+
     # -------------------------------------------------------------------------
     # Distributed Locking Methods (ALWAYS use separate session/transaction)
     # -------------------------------------------------------------------------