feat(graph_engine): Support pausing workflow graph executions (#26585)

Signed-off-by: -LAN- <laipz8200@outlook.com>

api/core/workflow/graph_events/__init__.py

@@ -13,6 +13,7 @@ from .graph import (
     GraphRunAbortedEvent,
     GraphRunFailedEvent,
     GraphRunPartialSucceededEvent,
+    GraphRunPausedEvent,
     GraphRunStartedEvent,
     GraphRunSucceededEvent,
 )
@@ -37,6 +38,7 @@ from .loop import (
 from .node import (
     NodeRunExceptionEvent,
     NodeRunFailedEvent,
+    NodeRunPauseRequestedEvent,
     NodeRunRetrieverResourceEvent,
     NodeRunRetryEvent,
     NodeRunStartedEvent,
@@ -51,6 +53,7 @@ __all__ = [
     "GraphRunAbortedEvent",
     "GraphRunFailedEvent",
     "GraphRunPartialSucceededEvent",
+    "GraphRunPausedEvent",
     "GraphRunStartedEvent",
     "GraphRunSucceededEvent",
     "NodeRunAgentLogEvent",
@@ -64,6 +67,7 @@ __all__ = [
     "NodeRunLoopNextEvent",
     "NodeRunLoopStartedEvent",
     "NodeRunLoopSucceededEvent",
+    "NodeRunPauseRequestedEvent",
     "NodeRunRetrieverResourceEvent",
     "NodeRunRetryEvent",
     "NodeRunStartedEvent",

api/core/workflow/graph_events/graph.py

@@ -8,7 +8,12 @@ class GraphRunStartedEvent(BaseGraphEvent):
 
 
 class GraphRunSucceededEvent(BaseGraphEvent):
-    outputs: dict[str, object] = Field(default_factory=dict)
+    """Event emitted when a run completes successfully with final outputs."""
+
+    outputs: dict[str, object] = Field(
+        default_factory=dict,
+        description="Final workflow outputs keyed by output selector.",
+    )
 
 
 class GraphRunFailedEvent(BaseGraphEvent):
@@ -17,12 +22,30 @@ class GraphRunFailedEvent(BaseGraphEvent):
 
 
 class GraphRunPartialSucceededEvent(BaseGraphEvent):
+    """Event emitted when a run finishes with partial success and failures."""
+
     exceptions_count: int = Field(..., description="exception count")
-    outputs: dict[str, object] = Field(default_factory=dict)
+    outputs: dict[str, object] = Field(
+        default_factory=dict,
+        description="Outputs that were materialised before failures occurred.",
+    )
 
 
 class GraphRunAbortedEvent(BaseGraphEvent):
     """Event emitted when a graph run is aborted by user command."""
 
     reason: str | None = Field(default=None, description="reason for abort")
-    outputs: dict[str, object] = Field(default_factory=dict, description="partial outputs if any")
+    outputs: dict[str, object] = Field(
+        default_factory=dict,
+        description="Outputs produced before the abort was requested.",
+    )
+
+
+class GraphRunPausedEvent(BaseGraphEvent):
+    """Event emitted when a graph run is paused by user command."""
+
+    reason: str | None = Field(default=None, description="reason for pause")
+    outputs: dict[str, object] = Field(
+        default_factory=dict,
+        description="Outputs available to the client while the run is paused.",
+    )

api/core/workflow/graph_events/node.py

@@ -51,3 +51,7 @@ class NodeRunExceptionEvent(GraphNodeEventBase):
 class NodeRunRetryEvent(NodeRunStartedEvent):
     error: str = Field(..., description="error")
     retry_index: int = Field(..., description="which retry attempt is about to be performed")
+
+
+class NodeRunPauseRequestedEvent(GraphNodeEventBase):
+    reason: str | None = Field(default=None, description="Optional pause reason")