feat(api): Human Input Node (backend part) (#31646)

The backend part of the human in the loop (HITL) feature and relevant architecture / workflow engine changes.

Signed-off-by: yihong0618 <zouzou0208@gmail.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: -LAN- <laipz8200@outlook.com>
Co-authored-by: 盐粒 Yanli <yanli@dify.ai>
Co-authored-by: CrabSAMA <40541269+CrabSAMA@users.noreply.github.com>
Co-authored-by: Stephen Zhou <38493346+hyoban@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: yihong <zouzou0208@gmail.com>
Co-authored-by: Joel <iamjoel007@gmail.com>

api/core/workflow/nodes/base/node.py

@@ -18,6 +18,8 @@ from core.workflow.graph_events import (
     GraphNodeEventBase,
     NodeRunAgentLogEvent,
     NodeRunFailedEvent,
+    NodeRunHumanInputFormFilledEvent,
+    NodeRunHumanInputFormTimeoutEvent,
     NodeRunIterationFailedEvent,
     NodeRunIterationNextEvent,
     NodeRunIterationStartedEvent,
@@ -34,6 +36,8 @@ from core.workflow.graph_events import (
 )
 from core.workflow.node_events import (
     AgentLogEvent,
+    HumanInputFormFilledEvent,
+    HumanInputFormTimeoutEvent,
     IterationFailedEvent,
     IterationNextEvent,
     IterationStartedEvent,
@@ -61,6 +65,15 @@ logger = logging.getLogger(__name__)
 
 
 class Node(Generic[NodeDataT]):
+    """BaseNode serves as the foundational class for all node implementations.
+
+    Nodes are allowed to maintain transient states (e.g., `LLMNode` uses the `_file_output`
+    attribute to track files generated by the LLM). However, these states are not persisted
+    when the workflow is suspended or resumed. If a node needs its state to be preserved
+    across workflow suspension and resumption, it should include the relevant state data
+    in its output.
+    """
+
     node_type: ClassVar[NodeType]
     execution_type: NodeExecutionType = NodeExecutionType.EXECUTABLE
     _node_data_type: ClassVar[type[BaseNodeData]] = BaseNodeData
@@ -251,10 +264,33 @@ class Node(Generic[NodeDataT]):
         return self._node_execution_id
 
     def ensure_execution_id(self) -> str:
-        if not self._node_execution_id:
-            self._node_execution_id = str(uuid4())
+        if self._node_execution_id:
+            return self._node_execution_id
+
+        resumed_execution_id = self._restore_execution_id_from_runtime_state()
+        if resumed_execution_id:
+            self._node_execution_id = resumed_execution_id
+            return self._node_execution_id
+
+        self._node_execution_id = str(uuid4())
         return self._node_execution_id
 
+    def _restore_execution_id_from_runtime_state(self) -> str | None:
+        graph_execution = self.graph_runtime_state.graph_execution
+        try:
+            node_executions = graph_execution.node_executions
+        except AttributeError:
+            return None
+        if not isinstance(node_executions, dict):
+            return None
+        node_execution = node_executions.get(self._node_id)
+        if node_execution is None:
+            return None
+        execution_id = node_execution.execution_id
+        if not execution_id:
+            return None
+        return str(execution_id)
+
     def _hydrate_node_data(self, data: Mapping[str, Any]) -> NodeDataT:
         return cast(NodeDataT, self._node_data_type.model_validate(data))
 
@@ -620,6 +656,28 @@ class Node(Generic[NodeDataT]):
             metadata=event.metadata,
         )
 
+    @_dispatch.register
+    def _(self, event: HumanInputFormFilledEvent):
+        return NodeRunHumanInputFormFilledEvent(
+            id=self.execution_id,
+            node_id=self._node_id,
+            node_type=self.node_type,
+            node_title=event.node_title,
+            rendered_content=event.rendered_content,
+            action_id=event.action_id,
+            action_text=event.action_text,
+        )
+
+    @_dispatch.register
+    def _(self, event: HumanInputFormTimeoutEvent):
+        return NodeRunHumanInputFormTimeoutEvent(
+            id=self.execution_id,
+            node_id=self._node_id,
+            node_type=self.node_type,
+            node_title=event.node_title,
+            expiration_time=event.expiration_time,
+        )
+
     @_dispatch.register
     def _(self, event: LoopStartedEvent) -> NodeRunLoopStartedEvent:
         return NodeRunLoopStartedEvent(