griptape-nodes 0.57.1__py3-none-any.whl → 0.58.1__py3-none-any.whl

griptape_nodes/machines/parallel_resolution.py

@@ -5,8 +5,9 @@ import logging
 from enum import StrEnum
 from typing import TYPE_CHECKING
 
-from griptape_nodes.exe_types.core_types import Parameter, ParameterType, ParameterTypeBuiltin
-from griptape_nodes.exe_types.node_types import BaseNode, NodeResolutionState
+from griptape_nodes.exe_types.connections import Direction
+from griptape_nodes.exe_types.core_types import Parameter, ParameterTypeBuiltin
+from griptape_nodes.exe_types.node_types import CONTROL_INPUT_PARAMETER, LOCAL_EXECUTION, BaseNode, NodeResolutionState
 from griptape_nodes.exe_types.type_validator import TypeValidator
 from griptape_nodes.machines.dag_builder import NodeState
 from griptape_nodes.machines.fsm import FSM, State
@@ -22,7 +23,10 @@ from griptape_nodes.retained_mode.events.execution_events import (
     NodeResolvedEvent,
     ParameterValueUpdateEvent,
 )
-from griptape_nodes.retained_mode.events.parameter_events import SetParameterValueRequest
+from griptape_nodes.retained_mode.events.parameter_events import (
+    SetParameterValueRequest,
+    SetParameterValueResultFailure,
+)
 from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
 if TYPE_CHECKING:
@@ -51,6 +55,7 @@ class ParallelResolutionContext:
     async_semaphore: asyncio.Semaphore
     task_to_node: dict[asyncio.Task, DagNode]
     dag_builder: DagBuilder | None
+    last_resolved_node: BaseNode | None  # Track the last node that was resolved
 
     def __init__(
         self, flow_name: str, max_nodes_in_parallel: int | None = None, dag_builder: DagBuilder | None = None
@@ -60,6 +65,7 @@ class ParallelResolutionContext:
         self.error_message = None
         self.workflow_state = WorkflowState.NO_ERROR
         self.dag_builder = dag_builder
+        self.last_resolved_node = None
 
         # Initialize execution fields
         max_nodes_in_parallel = max_nodes_in_parallel if max_nodes_in_parallel is not None else 5
@@ -94,6 +100,7 @@ class ParallelResolutionContext:
             self.workflow_state = WorkflowState.NO_ERROR
             self.error_message = None
             self.task_to_node.clear()
+            self.last_resolved_node = None
 
         # Clear DAG builder state to allow re-adding nodes on subsequent runs
         if self.dag_builder:
@@ -116,6 +123,8 @@ class ExecuteDagState(State):
 
         # Publish all parameter updates.
         current_node.state = NodeResolutionState.RESOLVED
+        # Track this as the last resolved node
+        context.last_resolved_node = current_node
         # Serialization can be slow so only do it if the user wants debug details.
         if logger.level <= logging.DEBUG:
             logger.debug(
@@ -167,6 +176,23 @@ class ExecuteDagState(State):
         # Now the final thing to do, is to take their directed graph and update it.
         ExecuteDagState.get_next_control_graph(context, current_node, network_name)
 
+    # Method is mirrored in Control_flow.py. If you update one, update the other.
+    @staticmethod
+    def get_next_control_output_for_non_local_execution(node: BaseNode) -> Parameter | None:
+        for param_name, value in node.parameter_output_values.items():
+            parameter = node.get_parameter_by_name(param_name)
+            if (
+                parameter is not None
+                and parameter.type == ParameterTypeBuiltin.CONTROL_TYPE.value
+                and value == CONTROL_INPUT_PARAMETER
+            ):
+                # This is the parameter
+                logger.debug(
+                    "Parallel Resolution: Found control output parameter '%s' for non-local execution", param_name
+                )
+                return parameter
+        return None
+
     @staticmethod
     def get_next_control_graph(context: ParallelResolutionContext, node: BaseNode, network_name: str) -> None:
         """Get next control flow nodes and add them to the DAG graph."""
@@ -175,8 +201,10 @@ class ExecuteDagState(State):
         # Early returns for various conditions
         if ExecuteDagState._should_skip_control_flow(context, node, network_name, flow_manager):
             return
-
-        next_output = node.get_next_control_output()
+        if node.get_parameter_value(node.execution_environment.name) != LOCAL_EXECUTION:
+            next_output = ExecuteDagState.get_next_control_output_for_non_local_execution(node)
+        else:
+            next_output = node.get_next_control_output()
         if next_output is not None:
             ExecuteDagState._process_next_control_node(context, node, next_output, network_name, flow_manager)
 
@@ -213,8 +241,14 @@ class ExecuteDagState(State):
         """Process the next control node in the flow."""
         node_connection = flow_manager.get_connections().get_connected_node(node, next_output)
         if node_connection is not None:
-            next_node, _ = node_connection
-
+            next_node, next_parameter = node_connection
+            # Set entry control parameter
+            logger.debug(
+                "Parallel Resolution: Setting entry control parameter for node '%s' to '%s'",
+                next_node.name,
+                next_parameter.name if next_parameter else None,
+            )
+            next_node.set_entry_control_parameter(next_parameter)
             # Prepare next node for execution
             if not next_node.lock:
                 next_node.make_node_unresolved(
@@ -291,12 +325,8 @@ class ExecuteDagState(State):
         connections = GriptapeNodes.FlowManager().get_connections()
 
         for parameter in current_node.parameters:
-            # Skip control type parameters
-            if ParameterTypeBuiltin.CONTROL_TYPE.value.lower() == parameter.output_type:
-                continue
-
             # Get the connected upstream node for this parameter
-            upstream_connection = connections.get_connected_node(current_node, parameter)
+            upstream_connection = connections.get_connected_node(current_node, parameter, direction=Direction.UPSTREAM)
             if upstream_connection:
                 upstream_node, upstream_parameter = upstream_connection
 
@@ -307,21 +337,20 @@ class ExecuteDagState(State):
                     output_value = upstream_node.get_parameter_value(upstream_parameter.name)
 
                 # Pass the value through using the same mechanism as normal resolution
-                # Skip propagation for Control Parameters as they should not receive values
-                if (
-                    ParameterType.attempt_get_builtin(upstream_parameter.output_type)
-                    != ParameterTypeBuiltin.CONTROL_TYPE
-                ):
-                    await GriptapeNodes.get_instance().ahandle_request(
-                        SetParameterValueRequest(
-                            parameter_name=parameter.name,
-                            node_name=current_node.name,
-                            value=output_value,
-                            data_type=upstream_parameter.output_type,
-                            incoming_connection_source_node_name=upstream_node.name,
-                            incoming_connection_source_parameter_name=upstream_parameter.name,
-                        )
+                result = await GriptapeNodes.get_instance().ahandle_request(
+                    SetParameterValueRequest(
+                        parameter_name=parameter.name,
+                        node_name=current_node.name,
+                        value=output_value,
+                        data_type=upstream_parameter.output_type,
+                        incoming_connection_source_node_name=upstream_node.name,
+                        incoming_connection_source_parameter_name=upstream_parameter.name,
                     )
+                )
+                if isinstance(result, SetParameterValueResultFailure):
+                    msg = f"Failed to set value for parameter '{parameter.name}' on node '{current_node.name}': {result.result_details}"
+                    logger.error(msg)
+                    raise RuntimeError(msg)
 
     @staticmethod
     def build_node_states(context: ParallelResolutionContext) -> tuple[set[str], set[str], set[str]]:
@@ -382,7 +411,10 @@ class ExecuteDagState(State):
     @staticmethod
     async def execute_node(current_node: DagNode, semaphore: asyncio.Semaphore) -> None:
         async with semaphore:
-            await current_node.node_reference.aprocess()
+            from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
+
+            executor = GriptapeNodes.FlowManager().node_executor
+            await executor.execute(current_node.node_reference)
 
     @staticmethod
     async def on_enter(context: ParallelResolutionContext) -> type[State] | None:
@@ -472,11 +504,29 @@ class ExecuteDagState(State):
             done, _ = await asyncio.wait(context.task_to_node.keys(), return_when=asyncio.FIRST_COMPLETED)
             # Check for task exceptions and handle them properly
             for task in done:
+                if task.cancelled():
+                    # Task was cancelled - this is expected during flow cancellation
+                    context.task_to_node.pop(task)
+                    logger.info("Task execution was cancelled.")
+                    return ErrorState
                 if task.exception():
-                    # Get the actual exception and re-raise it
                     exc = task.exception()
+                    dag_node = context.task_to_node.get(task)
+                    node_name = dag_node.node_reference.name if dag_node else "Unknown"
+                    node_type = dag_node.node_reference.__class__.__name__ if dag_node else "Unknown"
+
+                    logger.exception(
+                        "Task execution failed for node '%s' (type: %s) in flow '%s'. Exception: %s",
+                        node_name,
+                        node_type,
+                        context.flow_name,
+                        exc,
+                    )
+
                     context.task_to_node.pop(task)
-                    raise RuntimeError(exc)
+                    context.error_message = f"Task execution failed for node '{node_name}': {exc}"
+                    context.workflow_state = WorkflowState.ERRORED
+                    return ErrorState
                 context.task_to_node.pop(task)
         # Once a task has finished, loop back to the top.
         await ExecuteDagState.pop_done_states(context)
@@ -563,6 +613,21 @@ class ParallelResolutionMachine(FSM[ParallelResolutionContext]):
             self.context.dag_builder = GriptapeNodes.FlowManager().global_dag_builder
         await self.start(ExecuteDagState)
 
+    async def cancel_all_nodes(self) -> None:
+        """Cancel all executing tasks and set cancellation flags on all nodes."""
+        # Set cancellation flag on all nodes being tracked
+        for dag_node in self.context.node_to_reference.values():
+            dag_node.node_reference.request_cancellation()
+
+        # Cancel all running tasks
+        tasks = list(self.context.task_to_node.keys())
+        for task in tasks:
+            if not task.done():
+                task.cancel()
+
+        # Wait for all tasks to complete
+        await asyncio.gather(*tasks, return_exceptions=True)
+
     def change_debug_mode(self, *, debug_mode: bool) -> None:
         self._context.paused = debug_mode
 
@@ -575,3 +640,7 @@ class ParallelResolutionMachine(FSM[ParallelResolutionContext]):
     def reset_machine(self, *, cancel: bool = False) -> None:
         self._context.reset(cancel=cancel)
         self._current_state = None
+
+    def get_last_resolved_node(self) -> BaseNode | None:
+        """Get the last node that was resolved in the DAG execution."""
+        return self._context.last_resolved_node

griptape_nodes/machines/sequential_resolution.py

@@ -1,9 +1,11 @@
 from __future__ import annotations
 
+import asyncio
 import logging
 from dataclasses import dataclass
 
-from griptape_nodes.exe_types.core_types import ParameterType, ParameterTypeBuiltin
+from griptape_nodes.exe_types.connections import Direction
+from griptape_nodes.exe_types.core_types import ParameterTypeBuiltin
 from griptape_nodes.exe_types.node_types import BaseNode, NodeResolutionState
 from griptape_nodes.exe_types.type_validator import TypeValidator
 from griptape_nodes.machines.fsm import FSM, State
@@ -22,6 +24,7 @@ from griptape_nodes.retained_mode.events.execution_events import (
 )
 from griptape_nodes.retained_mode.events.parameter_events import (
     SetParameterValueRequest,
+    SetParameterValueResultFailure,
 )
 from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
@@ -31,6 +34,7 @@ logger = logging.getLogger("griptape_nodes")
 @dataclass
 class Focus:
     node: BaseNode
+    task: asyncio.Task[None] | None = None
 
 
 # This is on a per-node basis
@@ -163,12 +167,8 @@ class ExecuteNodeState(State):
         connections = GriptapeNodes.FlowManager().get_connections()
 
         for parameter in current_node.parameters:
-            # Skip control type parameters
-            if ParameterTypeBuiltin.CONTROL_TYPE.value.lower() == parameter.output_type:
-                continue
-
             # Get the connected upstream node for this parameter
-            upstream_connection = connections.get_connected_node(current_node, parameter)
+            upstream_connection = connections.get_connected_node(current_node, parameter, direction=Direction.UPSTREAM)
             if upstream_connection:
                 upstream_node, upstream_parameter = upstream_connection
 
@@ -179,21 +179,20 @@ class ExecuteNodeState(State):
                     output_value = upstream_node.get_parameter_value(upstream_parameter.name)
 
                 # Pass the value through using the same mechanism as normal resolution
-                # Skip propagation for Control Parameters as they should not receive values
-                if (
-                    ParameterType.attempt_get_builtin(upstream_parameter.output_type)
-                    != ParameterTypeBuiltin.CONTROL_TYPE
-                ):
-                    GriptapeNodes.get_instance().handle_request(
-                        SetParameterValueRequest(
-                            parameter_name=parameter.name,
-                            node_name=current_node.name,
-                            value=output_value,
-                            data_type=upstream_parameter.output_type,
-                            incoming_connection_source_node_name=upstream_node.name,
-                            incoming_connection_source_parameter_name=upstream_parameter.name,
-                        )
+                result = GriptapeNodes.get_instance().handle_request(
+                    SetParameterValueRequest(
+                        parameter_name=parameter.name,
+                        node_name=current_node.name,
+                        value=output_value,
+                        data_type=upstream_parameter.output_type,
+                        incoming_connection_source_node_name=upstream_node.name,
+                        incoming_connection_source_parameter_name=upstream_parameter.name,
                     )
+                )
+                if isinstance(result, SetParameterValueResultFailure):
+                    msg = f"Failed to set parameter value for node '{current_node.name}' and parameter '{parameter.name}'. Details: {result.result_details}"
+                    logger.error(msg)
+                    raise RuntimeError(msg)
 
     @staticmethod
     async def on_enter(context: ResolutionContext) -> type[State] | None:
@@ -270,7 +269,26 @@ class ExecuteNodeState(State):
             current_node = current_focus.node
 
             try:
-                await current_node.aprocess()
+                from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
+
+                executor = GriptapeNodes.FlowManager().node_executor
+                # Create and track task in Focus for cancellation support
+                execution_task = asyncio.create_task(executor.execute(current_node))
+                current_focus.task = execution_task
+                await execution_task
+            except asyncio.CancelledError:
+                logger.info("Node '%s' processing was cancelled.", current_node.name)
+                current_node.make_node_unresolved(
+                    current_states_to_trigger_change_event=set(
+                        {NodeResolutionState.UNRESOLVED, NodeResolutionState.RESOLVED, NodeResolutionState.RESOLVING}
+                    )
+                )
+                GriptapeNodes.EventManager().put_event(
+                    ExecutionGriptapeNodeEvent(
+                        wrapped_event=ExecutionEvent(payload=NodeFinishProcessEvent(node_name=current_node.name))
+                    )
+                )
+                return CompleteState
             except Exception as e:
                 logger.exception("Error processing node '%s", current_node.name)
                 msg = f"Canceling flow run. Node '{current_node.name}' encountered a problem: {e}"
@@ -283,7 +301,7 @@ class ExecuteNodeState(State):
 
                 from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
-                GriptapeNodes.FlowManager().cancel_flow_run()
+                await GriptapeNodes.FlowManager().cancel_flow_run()
 
                 GriptapeNodes.EventManager().put_event(
                     ExecutionGriptapeNodeEvent(
@@ -381,6 +399,27 @@ class SequentialResolutionMachine(FSM[ResolutionContext]):
         self._context.focus_stack.append(Focus(node=node))
         await self.start(InitializeSpotlightState)
 
+    async def cancel_all_nodes(self) -> None:
+        """Cancel the currently executing node and set cancellation flags on all nodes in focus stack."""
+        # Set cancellation flag on all nodes in the focus stack
+        for focus in self._context.focus_stack:
+            focus.node.request_cancellation()
+
+        # Collect tasks that need to be cancelled
+        tasks = []
+        if self._context.focus_stack:
+            current_focus = self._context.focus_stack[-1]
+            if current_focus.task and not current_focus.task.done():
+                tasks.append(current_focus.task)
+
+        # Cancel all tasks
+        for task in tasks:
+            task.cancel()
+
+        # Wait for all tasks to complete
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+
     def change_debug_mode(self, debug_mode: bool) -> None:  # noqa: FBT001
         self._context.paused = debug_mode
 

griptape_nodes/node_library/library_registry.py

@@ -50,6 +50,13 @@ class IconVariant(BaseModel):
     dark: str
 
 
+class NodeDeprecationMetadata(BaseModel):
+    """Metadata about a deprecated node."""
+
+    deprecation_message: str | None = None
+    removal_version: str | None = None
+
+
 class NodeMetadata(BaseModel):
     """Metadata about each node within the library, which informs where in the hierarchy it sits, details on usage, and tags to assist search."""
 
@@ -60,6 +67,7 @@ class NodeMetadata(BaseModel):
     icon: str | IconVariant | None = None
     color: str | None = None
     group: str | None = None
+    deprecation: NodeDeprecationMetadata | None = None
 
 
 class CategoryDefinition(BaseModel):
@@ -99,7 +107,7 @@ class LibrarySchema(BaseModel):
     library itself.
     """
 
-    LATEST_SCHEMA_VERSION: ClassVar[str] = "0.2.0"
+    LATEST_SCHEMA_VERSION: ClassVar[str] = "0.3.0"
 
     name: str
     library_schema_version: str
@@ -359,3 +367,18 @@ class Library:
             The AdvancedNodeLibrary instance, or None if not set
         """
         return self._advanced_library
+
+    def get_nodes_by_base_type(self, base_type: type) -> list[str]:
+        """Get all node types in this library that are subclasses of the specified base type.
+
+        Args:
+            base_type: The base class to filter by (e.g., StartNode, ControlNode)
+
+        Returns:
+            List of node type names that extend the base type
+        """
+        matching_nodes = []
+        for node_type, node_class in self._node_types.items():
+            if issubclass(node_class, base_type):
+                matching_nodes.append(node_type)
+        return matching_nodes

griptape_nodes/node_library/workflow_registry.py

@@ -4,7 +4,7 @@ import json
 import logging
 from datetime import datetime  # noqa: TC003 (can't put into type checking block as Pydantic model relies on it)
 from pathlib import Path
-from typing import Any, ClassVar
+from typing import Any, ClassVar, NamedTuple
 
 from pydantic import BaseModel, Field, field_serializer, field_validator
 
@@ -15,6 +15,12 @@ from griptape_nodes.utils.metaclasses import SingletonMeta
 
 logger = logging.getLogger("griptape_nodes")
 
+
+class LibraryNameAndNodeType(NamedTuple):
+    library_name: str
+    node_type: str
+
+
 # Type aliases for clarity
 type NodeName = str
 type ParameterName = str
@@ -39,12 +45,13 @@ class WorkflowShape(BaseModel):
 
 
 class WorkflowMetadata(BaseModel):
-    LATEST_SCHEMA_VERSION: ClassVar[str] = "0.8.0"
+    LATEST_SCHEMA_VERSION: ClassVar[str] = "0.9.0"
 
     name: str
     schema_version: str
     engine_version_created_with: str
     node_libraries_referenced: list[LibraryNameAndVersion]
+    node_types_used: set[LibraryNameAndNodeType] = Field(default_factory=set)
     workflows_referenced: list[str] | None = None
     description: str | None = None
     image: str | None = None
@@ -55,6 +62,35 @@ class WorkflowMetadata(BaseModel):
     branched_from: str | None = Field(default=None)
     workflow_shape: WorkflowShape | None = Field(default=None)
 
+    @field_serializer("node_types_used")
+    def serialize_node_types_used(self, node_types_used: set[LibraryNameAndNodeType]) -> list[list[str]]:
+        """Serialize node_types_used as list of tuples for TOML compatibility.
+
+        Sets and NamedTuples are not directly supported by TOML, so we convert the set
+        to a list of lists (each inner list represents [library_name, node_type]).
+        """
+        return [[nt.library_name, nt.node_type] for nt in sorted(node_types_used)]
+
+    @field_validator("node_types_used", mode="before")
+    @classmethod
+    def validate_node_types_used(cls, value: Any) -> set[LibraryNameAndNodeType]:
+        """Deserialize node_types_used from list of lists during TOML loading.
+
+        When loading workflow metadata from TOML files, the node_types_used field
+        is stored as a list of [library_name, node_type] pairs that needs to be
+        converted back to a set of LibraryNameAndNodeType objects. This validator
+        handles the expected input formats:
+        - List of lists (from TOML deserialization)
+        - Set of LibraryNameAndNodeType (from direct Python construction)
+        - Empty list (for workflows with no nodes)
+        """
+        if isinstance(value, set):
+            return value
+        if isinstance(value, list):
+            return {LibraryNameAndNodeType(library_name=item[0], node_type=item[1]) for item in value}
+        msg = f"Expected list or set for node_types_used, got {type(value)}"
+        raise ValueError(msg)
+
     @field_serializer("workflow_shape")
     def serialize_workflow_shape(self, workflow_shape: WorkflowShape | None) -> str | None:
         """Serialize WorkflowShape as JSON string to avoid TOML serialization issues.

griptape_nodes/retained_mode/events/execution_events.py

@@ -1,4 +1,4 @@
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any
 
 from griptape_nodes.retained_mode.events.base_events import (
@@ -10,6 +10,7 @@ from griptape_nodes.retained_mode.events.base_events import (
     WorkflowAlteredMixin,
     WorkflowNotAlteredMixin,
 )
+from griptape_nodes.retained_mode.events.node_events import SerializedNodeCommands
 from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 
 # Requests and Results TO/FROM USER! These begin requests - and are not fully Execution Events.
@@ -72,6 +73,8 @@ class StartFlowRequest(RequestPayload):
     flow_name: str | None = None
     flow_node_name: str | None = None
     debug_mode: bool = False
+    # If this is true, the final ControlFLowResolvedEvent will be pickled to be picked up from inside a subprocess.
+    pickle_control_flow_result: bool = False
 
 
 @dataclass
@@ -303,6 +306,10 @@ class ParameterSpotlightEvent(ExecutionPayload):
 class ControlFlowResolvedEvent(ExecutionPayload):
     end_node_name: str
     parameter_output_values: dict
+    # Optional field for pickled parameter values - when present, parameter_output_values contains UUID references
+    unique_parameter_uuid_to_values: dict[SerializedNodeCommands.UniqueParameterValueUUID, Any] | None = field(
+        default=None
+    )
 
 
 @dataclass

griptape_nodes/retained_mode/events/flow_events.py

@@ -1,8 +1,8 @@
-from dataclasses import dataclass
-from typing import Any
+from dataclasses import dataclass, field
+from typing import Any, NamedTuple
 
 from griptape_nodes.exe_types.node_types import NodeDependencies
-from griptape_nodes.node_library.workflow_registry import WorkflowShape
+from griptape_nodes.node_library.workflow_registry import LibraryNameAndNodeType, WorkflowShape
 from griptape_nodes.retained_mode.events.base_events import (
     RequestPayload,
     ResultPayloadFailure,
@@ -201,6 +201,8 @@ class SerializedFlowCommands:
         node_dependencies (NodeDependencies): Aggregated dependencies from all nodes in this flow and its sub-flows.
             Includes referenced workflows, static files, Python imports, and libraries. Used for workflow packaging,
             dependency resolution, and deployment planning.
+        node_types_used (set[LibraryNameAndNodeType]): Set of all node types used in this flow and its sub-flows.
+            Each entry contains the library name and node type name pair, used for tracking which node types are utilized.
     """
 
     @dataclass
@@ -231,6 +233,7 @@ class SerializedFlowCommands:
     set_lock_commands_per_node: dict[SerializedNodeCommands.NodeUUID, SetLockNodeStateRequest]
     sub_flows_commands: list["SerializedFlowCommands"]
     node_dependencies: NodeDependencies
+    node_types_used: set[LibraryNameAndNodeType]
 
 
 @dataclass
@@ -438,3 +441,87 @@ class PackageNodeAsSerializedFlowResultFailure(WorkflowNotAlteredMixin, ResultPa
     Common causes: node not found, no current context, serialization error,
     connection analysis failed, node has no valid flow context.
     """
+
+
+# Type aliases for parameter mapping clarity
+SanitizedParameterName = str  # What appears in the serialized flow
+OriginalNodeName = str  # Original node name (can have spaces, dots, etc.)
+OriginalParameterName = str  # Original parameter name
+
+
+class OriginalNodeParameter(NamedTuple):
+    """Represents the original source of a parameter before sanitization."""
+
+    node_name: OriginalNodeName
+    parameter_name: OriginalParameterName
+
+
+class ParameterNameMapping(NamedTuple):
+    """Maps a sanitized parameter name back to its original node and parameter."""
+
+    output_sanitized_parameter_name: SanitizedParameterName
+    original: OriginalNodeParameter
+
+
+@dataclass
+@PayloadRegistry.register
+class PackageNodesAsSerializedFlowRequest(RequestPayload):
+    """Package multiple nodes as a complete flow with artificial start and end nodes.
+
+    Creates a serialized flow where:
+    - Start node has output parameters matching all selected nodes' incoming connections
+    - All selected nodes maintain their existing connections between each other
+    - End node has input parameters matching all selected nodes' outgoing connections
+    - Flow structure: Start → [Selected Nodes with internal connections] → End
+
+    Use when: Creating complex reusable components, exporting node groups for templates,
+    building multi-step sub-workflows, packaging interconnected functionality.
+
+    Args:
+        node_names: List of node names to package as a flow (empty list will create StartFlow→EndFlow only with warning)
+        start_node_type: Node type name for the artificial start node (defaults to "StartFlow")
+        end_node_type: Node type name for the artificial end node (defaults to "EndFlow")
+        start_end_specific_library_name: Library name containing the start/end nodes (defaults to "Griptape Nodes Library")
+        entry_control_node_name: Name of the node that should receive the control flow entry (required if entry_control_parameter_name specified)
+        entry_control_parameter_name: Name of the control parameter on the entry node (None for auto-detection of first available control parameter)
+        output_parameter_prefix: Prefix for parameter names on the generated end node to avoid collisions (defaults to "packaged_node_")
+
+    Results: PackageNodesAsSerializedFlowResultSuccess (with serialized flow and node name mapping) | PackageNodesAsSerializedFlowResultFailure
+    """
+
+    # List of node names to package (empty list creates StartFlow→EndFlow only with warning)
+    node_names: list[str] = field(default_factory=list)
+    start_node_type: str = "StartFlow"
+    end_node_type: str = "EndFlow"
+    start_end_specific_library_name: str = "Griptape Nodes Library"
+    entry_control_node_name: str | None = None
+    entry_control_parameter_name: str | None = None
+    output_parameter_prefix: str = "packaged_node_"
+
+
+@dataclass
+@PayloadRegistry.register
+class PackageNodesAsSerializedFlowResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Multiple nodes successfully packaged as serialized flow.
+
+    Args:
+        serialized_flow_commands: The complete serialized flow with StartFlow, selected nodes with preserved connections, and EndFlow
+        workflow_shape: The workflow shape defining inputs and outputs for external callers
+        packaged_node_names: List of node names that were included in the package
+        parameter_name_mappings: Dict mapping sanitized parameter names to original node and parameter names for O(1) lookup
+    """
+
+    serialized_flow_commands: SerializedFlowCommands
+    workflow_shape: WorkflowShape
+    packaged_node_names: list[str]
+    parameter_name_mappings: dict[SanitizedParameterName, OriginalNodeParameter]
+
+
+@dataclass
+@PayloadRegistry.register
+class PackageNodesAsSerializedFlowResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Multiple nodes packaging failed.
+
+    Common causes: one or more nodes not found, no current context, serialization error,
+    entry control node/parameter not found, connection analysis failed.
+    """