griptape-nodes 0.64.11__py3-none-any.whl → 0.65.0__py3-none-any.whl

griptape_nodes/retained_mode/managers/flow_manager.py

@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING, Any, NamedTuple, cast
 from uuid import uuid4
 
 from griptape_nodes.common.node_executor import NodeExecutor
+from griptape_nodes.exe_types.base_iterative_nodes import BaseIterativeStartNode
 from griptape_nodes.exe_types.connections import Connections
 from griptape_nodes.exe_types.core_types import (
     Parameter,
@@ -22,7 +23,6 @@ from griptape_nodes.exe_types.node_types import (
     NodeDependencies,
     NodeGroupNode,
     NodeResolutionState,
-    StartLoopNode,
     StartNode,
 )
 from griptape_nodes.machines.control_flow import CompleteState, ControlFlowMachine
@@ -75,6 +75,9 @@ from griptape_nodes.retained_mode.events.execution_events import (
     StartFlowRequest,
     StartFlowResultFailure,
     StartFlowResultSuccess,
+    StartLocalSubflowRequest,
+    StartLocalSubflowResultFailure,
+    StartLocalSubflowResultSuccess,
     UnresolveFlowRequest,
     UnresolveFlowResultFailure,
     UnresolveFlowResultSuccess,
@@ -125,6 +128,7 @@ from griptape_nodes.retained_mode.events.node_events import (
     DeleteNodeRequest,
     DeleteNodeResultFailure,
     DeserializeNodeFromCommandsRequest,
+    DeserializeNodeFromCommandsResultSuccess,
     SerializedNodeCommands,
     SerializedParameterValueTracker,
     SerializeNodeToCommandsRequest,
@@ -199,6 +203,8 @@ class PackagingStartNodeResult(NamedTuple):
     start_to_package_connections: list[SerializedFlowCommands.IndirectConnectionSerialization]
     input_shape_data: WorkflowShapeNodes
     start_node_parameter_value_commands: list[SerializedNodeCommands.IndirectSetParameterValueCommand]
+    parameter_name_mappings: dict[SanitizedParameterName, OriginalNodeParameter]
+    start_node_name: str
 
 
 class PackagingEndNodeResult(NamedTuple):
@@ -215,6 +221,7 @@ class MultiNodeEndNodeResult(NamedTuple):
     packaging_result: PackagingEndNodeResult
     parameter_name_mappings: dict[SanitizedParameterName, OriginalNodeParameter]
     alter_parameter_commands: list[AlterParameterDetailsRequest]
+    end_node_name: str
 
 
 class FlowManager:
@@ -265,7 +272,7 @@ class FlowManager:
         event_manager.assign_manager_to_request_type(
             PackageNodesAsSerializedFlowRequest, self.on_package_nodes_as_serialized_flow_request
         )
-
+        event_manager.assign_manager_to_request_type(StartLocalSubflowRequest, self.on_start_local_subflow_request)
         self._name_to_parent_name = {}
         self._flow_to_referenced_workflow_name = {}
         self._connections = Connections()
@@ -323,14 +330,35 @@ class FlowManager:
         return connections
 
     def _get_connections_for_flow(self, flow: ControlFlow) -> list:
-        """Get connections where both nodes are in the specified flow."""
+        """Get connections where both nodes are in the specified flow or its child flows.
+
+        For parent flows, this includes cross-flow connections between the parent and its children.
+        For child flows, this only includes connections within that specific flow.
+        """
         flow_connections = []
+        flow_name = flow.name
+
+        # Get all child flow names for this flow
+        child_flow_names = set()
+        for child_name, parent_name in self._name_to_parent_name.items():
+            if parent_name == flow_name:
+                child_flow_names.add(child_name)
+
+        # Build set of all node names in this flow and its direct children
+        all_node_names = set(flow.nodes.keys())
+        for child_flow_name in child_flow_names:
+            child_flow = GriptapeNodes.ObjectManager().attempt_get_object_by_name_as_type(child_flow_name, ControlFlow)
+            if child_flow is not None:
+                all_node_names.update(child_flow.nodes.keys())
+
+        # Include connections where both nodes are in this flow hierarchy
         for connection in self._connections.connections.values():
-            source_in_flow = connection.source_node.name in flow.nodes
-            target_in_flow = connection.target_node.name in flow.nodes
-            # Only include connection if BOTH nodes are in this flow (for serialization)
-            if source_in_flow and target_in_flow:
+            source_in_hierarchy = connection.source_node.name in all_node_names
+            target_in_hierarchy = connection.target_node.name in all_node_names
+
+            if source_in_hierarchy and target_in_hierarchy:
                 flow_connections.append(connection)
+
         return flow_connections
 
     def get_parent_flow(self, flow_name: str) -> str | None:
@@ -550,9 +578,17 @@ class FlowManager:
             details = f"Attempted to delete Flow '{flow_name}', but no Flow with that name could be found."
             result = DeleteFlowResultFailure(result_details=details)
             return result
-        if self.check_for_existing_running_flow():
+
+        # Only cancel if the flow being deleted is the one tracked by the global control flow machine.
+        # Isolated subflows (e.g., ForEach loop iterations) have their own separate ControlFlowMachine
+        # and should not trigger cancellation of the global machine.
+        if (
+            self.check_for_existing_running_flow()
+            and self._global_control_flow_machine is not None
+            and self._global_control_flow_machine.context.flow_name == flow.name
+        ):
             result = GriptapeNodes.handle_request(CancelFlowRequest(flow_name=flow.name))
-            if not result.succeeded():
+            if result.failed():
                 details = f"Attempted to delete flow '{flow_name}'. Failed because running flow could not cancel."
                 return DeleteFlowResultFailure(result_details=details)
 
@@ -612,9 +648,14 @@ class FlowManager:
             if flow in self._flow_to_referenced_workflow_name:
                 del self._flow_to_referenced_workflow_name[flow]
 
-            # Clean up ControlFlowMachine and DAG orchestrator for this flow
-            self._global_control_flow_machine = None
-            self._global_dag_builder.clear()
+            # Clean up ControlFlowMachine and DAG orchestrator only if this is the global flow.
+            # Isolated subflows have their own machines and should not clear the global state.
+            if (
+                self._global_control_flow_machine is not None
+                and self._global_control_flow_machine.context.flow_name == flow.name
+            ):
+                self._global_control_flow_machine = None
+                self._global_dag_builder.clear()
 
         details = f"Successfully deleted Flow '{flow_name}'."
         result = DeleteFlowResultSuccess(result_details=details)
@@ -876,13 +917,23 @@ class FlowManager:
             details = f"Deleted the previous connection from '{old_source_node_name}.{old_source_param_name}' to '{old_target_node_name}.{old_target_param_name}' to make room for the new connection."
         try:
             # Actually create the Connection.
+            if (isinstance(source_node, NodeGroupNode) and target_node.parent_group == source_node) or (
+                isinstance(target_node, NodeGroupNode) and source_node.parent_group == target_node
+            ):
+                # Here we're checking if it's an internal connection. (from the NodeGroup to a node within it.)
+                # If that's true, we set that automatically.
+                is_node_group_internal = True
+            else:
+                # If not true, we default to the request
+                is_node_group_internal = request.is_node_group_internal
             conn = self._connections.add_connection(
                 source_node=source_node,
                 source_parameter=source_param,
                 target_node=target_node,
                 target_parameter=target_param,
+                is_node_group_internal=is_node_group_internal,
             )
-            conn_id = id(conn)
+            id(conn)
         except ValueError as e:
             details = f'Connection failed: "{e}"'
 
@@ -923,26 +974,36 @@ class FlowManager:
         target_parent = target_node.parent_group
 
         # If source is in a group, this is an outgoing external connection
-        if source_parent is not None and isinstance(source_parent, NodeGroupNode) and target_parent != source_parent:
-            source_parent.track_external_connection(
+        if (
+            source_parent is not None
+            and isinstance(source_parent, NodeGroupNode)
+            and source_parent not in (target_parent, target_node)
+        ):
+            success = source_parent.map_external_connection(
                 conn=conn,
-                conn_id=conn_id,
                 is_incoming=False,
-                grouped_node=source_node,
             )
+            if success:
+                details = f'Connected "{source_node_name}.{request.source_parameter_name}" to "{target_node_name}.{request.target_parameter_name}, remapped with proxy parameter."'
+                return CreateConnectionResultSuccess(result_details=details)
+            details = f'Failed to connect "{source_node_name}.{request.source_parameter_name}" to "{target_node_name}.{request.target_parameter_name} by remapping to proxy."'
+            return CreateConnectionResultFailure(result_details=details)
 
         # If target is in a group, this is an incoming external connection
-        if target_parent is not None and isinstance(target_parent, NodeGroupNode) and source_parent != target_parent:
-            target_parent.track_external_connection(
+        if (
+            target_parent is not None
+            and isinstance(target_parent, NodeGroupNode)
+            and target_parent not in (source_parent, source_node)
+        ):
+            success = target_parent.map_external_connection(
                 conn=conn,
-                conn_id=conn_id,
                 is_incoming=True,
-                grouped_node=target_node,
             )
-
-        # If both in same group, track as internal connection
-        if source_parent is not None and source_parent == target_parent and isinstance(source_parent, NodeGroupNode):
-            source_parent.track_internal_connection(conn)
+            if success:
+                details = f'Connected "{source_node_name}.{request.source_parameter_name}" to "{target_node_name}.{request.target_parameter_name}, remapped with proxy parameter."'
+                return CreateConnectionResultSuccess(result_details=details)
+            details = f'Failed to connect "{source_node_name}.{request.source_parameter_name}" to "{target_node_name}.{request.target_parameter_name} by remapping to proxy."'
+            return CreateConnectionResultFailure(result_details=details)
 
         details = f'Connected "{source_node_name}.{request.source_parameter_name}" to "{target_node_name}.{request.target_parameter_name}"'
 
@@ -1084,12 +1145,7 @@ class FlowManager:
 
         # Check if either node is in a NodeGroup and untrack connections BEFORE removing connection
 
-        source_parent = source_node.parent_group
-        target_parent = target_node.parent_group
-
         # Find the connection before it's deleted
-        conn = None
-        conn_id = None
         if (
             source_node.name in self._connections.outgoing_index
             and source_param.name in self._connections.outgoing_index[source_node.name]
@@ -1101,47 +1157,8 @@ class FlowManager:
                     candidate.target_node.name == target_node.name
                     and candidate.target_parameter.name == target_param.name
                 ):
-                    conn = candidate
-                    conn_id = candidate_id
                     break
 
-        # If source is in a group, untrack outgoing external connection
-        if (
-            conn
-            and conn_id
-            and source_parent is not None
-            and isinstance(source_parent, NodeGroupNode)
-            and target_parent != source_parent
-        ):
-            source_parent.untrack_external_connection(
-                conn=conn,
-                conn_id=conn_id,
-                is_incoming=False,
-            )
-
-        # If target is in a group, untrack incoming external connection
-        if (
-            conn
-            and conn_id
-            and target_parent is not None
-            and isinstance(target_parent, NodeGroupNode)
-            and source_parent != target_parent
-        ):
-            target_parent.untrack_external_connection(
-                conn=conn,
-                conn_id=conn_id,
-                is_incoming=True,
-            )
-
-        # If both in same group, untrack internal connection
-        if (
-            conn
-            and source_parent is not None
-            and source_parent == target_parent
-            and isinstance(source_parent, NodeGroupNode)
-        ):
-            source_parent.untrack_internal_connection(conn)
-
         # Remove the connection.
         if not self._connections.remove_connection(
             source_node=source_node.name,
@@ -1204,7 +1221,7 @@ class FlowManager:
         result = DeleteConnectionResultSuccess(result_details=details)
         return result
 
-    def on_package_nodes_as_serialized_flow_request(  # noqa: C901, PLR0911, PLR0912
+    def on_package_nodes_as_serialized_flow_request(  # noqa: C901, PLR0911, PLR0912, PLR0915
         self, request: PackageNodesAsSerializedFlowRequest
     ) -> ResultPayload:
         """Handle request to package multiple nodes as a serialized flow.
@@ -1274,7 +1291,17 @@ class FlowManager:
         if isinstance(node_connections_dict, PackageNodesAsSerializedFlowResultFailure):
             return node_connections_dict
 
-        # Step 8: Create start node with parameters for external incoming connections
+        # Step 8: Retrieve NodeGroupNode if node_group_name was provided
+        node_group_node: NodeGroupNode | None = None
+        if request.node_group_name:
+            try:
+                node = GriptapeNodes.NodeManager().get_node_by_name(request.node_group_name)
+                if isinstance(node, NodeGroupNode):
+                    node_group_node = node
+            except Exception as e:
+                logger.debug("Failed to retrieve NodeGroupNode '%s': %s", request.node_group_name, e)
+
+        # Step 9: Create start node with parameters for external incoming connections
         start_node_result = self._create_multi_node_start_node_with_connections(
             request=request,
             library_version=library_version,
@@ -1282,11 +1309,12 @@ class FlowManager:
             serialized_parameter_value_tracker=serialized_parameter_value_tracker,
             node_name_to_uuid=node_name_to_uuid,
             external_connections_dict=node_connections_dict,
+            node_group_node=node_group_node,
         )
         if isinstance(start_node_result, PackageNodesAsSerializedFlowResultFailure):
             return start_node_result
 
-        # Step 9: Create end node with parameters for external outgoing connections and parameter mappings
+        # Step 10: Create end node with parameters for external outgoing connections and parameter mappings
         end_node_result = self._create_multi_node_end_node_with_connections(
             request=request,
             package_nodes=nodes_to_package,
@@ -1298,9 +1326,32 @@ class FlowManager:
             return end_node_result
 
         end_node_packaging_result = end_node_result.packaging_result
-        parameter_name_mappings = end_node_result.parameter_name_mappings
 
-        # Step 10: Assemble final SerializedFlowCommands
+        # If no entry control node specified, connect start directly to end
+        if not request.entry_control_node_name and not request.entry_control_parameter_name:
+            start_to_end_control_connection = SerializedFlowCommands.IndirectConnectionSerialization(
+                source_node_uuid=start_node_result.start_node_commands.node_uuid,
+                source_parameter_name="exec_out",
+                target_node_uuid=end_node_packaging_result.end_node_commands.node_uuid,
+                target_parameter_name="exec_in",
+            )
+            start_node_result.start_to_package_connections.append(start_to_end_control_connection)
+
+        # Combine parameter mappings as a list: [Start node (index 0), End node (index 1)]
+        from griptape_nodes.retained_mode.events.flow_events import PackagedNodeParameterMapping
+
+        parameter_name_mappings = [
+            PackagedNodeParameterMapping(
+                node_name=start_node_result.start_node_name,
+                parameter_mappings=start_node_result.parameter_name_mappings,
+            ),
+            PackagedNodeParameterMapping(
+                node_name=end_node_result.end_node_name,
+                parameter_mappings=end_node_result.parameter_name_mappings,
+            ),
+        ]
+
+        # Step 11: Assemble final SerializedFlowCommands
         # Collect all connections from start/end nodes and internal package connections
         all_connections = self._collect_all_connections_for_multi_node_package(
             start_node_result=start_node_result,
@@ -1432,7 +1483,7 @@ class FlowManager:
 
         return None
 
-    def _serialize_package_nodes_for_local_execution(  # noqa: PLR0913
+    def _serialize_package_nodes_for_local_execution(  # noqa: PLR0913, C901
         self,
         nodes_to_package: list[BaseNode],
         unique_parameter_uuid_to_values: dict[SerializedNodeCommands.UniqueParameterValueUUID, Any],
@@ -1496,6 +1547,21 @@ class FlowManager:
                     serialize_result.set_parameter_value_commands
                 )
 
+        # Update NodeGroupNode commands to use UUIDs instead of names in node_names_to_add
+        # This allows workflow generation to directly look up variable names from UUIDs
+
+        for node_group_command in serialized_node_group_commands:
+            create_cmd = node_group_command.create_node_command
+
+            if isinstance(create_cmd, CreateNodeGroupRequest) and create_cmd.node_names_to_add:
+                node_uuids = []
+                for child_node_name in create_cmd.node_names_to_add:
+                    if child_node_name in node_name_to_uuid:
+                        uuid = node_name_to_uuid[child_node_name]
+                        node_uuids.append(uuid)
+                # Replace the list with UUIDs (as strings since that's what the field expects)
+                create_cmd.node_names_to_add = node_uuids
+
         # Build internal connections between package nodes
         package_node_names_set = {n.name for n in nodes_to_package}
 
@@ -1801,6 +1867,7 @@ class FlowManager:
             packaging_result=end_node_result,
             parameter_name_mappings=parameter_name_mappings,
             alter_parameter_commands=[],
+            end_node_name=end_node_name,
         )
 
     def _create_end_node_control_connections(  # noqa: PLR0913
@@ -1947,10 +2014,15 @@ class FlowManager:
             output_shape_data[end_node_name][sanitized_param_name] = param_shape_info
 
         # Create parameter command for end node
+        # Use flexible input types for data parameters to prevent type mismatch errors
+        # Control parameters must keep their exact types (cannot use "any")
+        is_control_param = parameter.output_type == ParameterTypeBuiltin.CONTROL_TYPE.value
+
         add_param_request = AddParameterToNodeRequest(
             node_name=end_node_name,
             parameter_name=sanitized_param_name,
-            type=parameter.output_type,
+            input_types=parameter.input_types if is_control_param else ["any"],  # Control: exact types; Data: any
+            output_type=parameter.output_type,  # Preserve original output type
             default_value=None,
             tooltip=tooltip,
             initial_setup=True,
@@ -1976,11 +2048,14 @@ class FlowManager:
         external_connections_dict: dict[
             str, ConnectionAnalysis
         ],  # Contains EXTERNAL connections only - used to determine which parameters need start node inputs
+        node_group_node: NodeGroupNode | None = None,
     ) -> PackagingStartNodeResult | PackageNodesAsSerializedFlowResultFailure:
         """Create start node commands and connections for external incoming connections."""
         # Generate UUID and name for start node
         start_node_uuid = SerializedNodeCommands.NodeUUID(str(uuid4()))
         start_node_name = "Start_Package_MultiNode"
+        # Parameter name mappings are essential to know which inputs are necessary on the start node given.
+        parameter_name_mappings: dict[SanitizedParameterName, OriginalNodeParameter] = {}
 
         # Build start node CreateNodeRequest
         start_create_node_command = CreateNodeRequest(
@@ -2021,6 +2096,7 @@ class FlowManager:
                 node_name_to_uuid=node_name_to_uuid,
                 unique_parameter_uuid_to_values=unique_parameter_uuid_to_values,
                 serialized_parameter_value_tracker=serialized_parameter_value_tracker,
+                parameter_name_mappings=parameter_name_mappings,
             )
             if isinstance(result, PackageNodesAsSerializedFlowResultFailure):
                 return result
@@ -2047,6 +2123,17 @@ class FlowManager:
         # Add control connections to the same list as data connections
         start_to_package_connections.extend(control_connections)
 
+        # Set parameter values from NodeGroupNode if provided
+        if node_group_node is not None:
+            self._apply_node_group_parameters_to_start_node(
+                node_group_node=node_group_node,
+                start_node_library_name=request.start_node_library_name,
+                start_node_type=request.start_node_type,  # type: ignore[arg-type]  # Guaranteed non-None
+                start_node_parameter_value_commands=start_node_parameter_value_commands,
+                unique_parameter_uuid_to_values=unique_parameter_uuid_to_values,
+                serialized_parameter_value_tracker=serialized_parameter_value_tracker,
+            )
+
         # Build complete SerializedNodeCommands for start node
         start_node_dependencies = NodeDependencies()
         start_node_dependencies.libraries.add(start_node_library_details)
@@ -2063,8 +2150,101 @@ class FlowManager:
             start_to_package_connections=start_to_package_connections,
             input_shape_data=input_shape_data,
             start_node_parameter_value_commands=start_node_parameter_value_commands,
+            parameter_name_mappings=parameter_name_mappings,
+            start_node_name=start_node_name,
         )
 
+    def _apply_node_group_parameters_to_start_node(  # noqa: PLR0913
+        self,
+        node_group_node: NodeGroupNode,
+        start_node_library_name: str,
+        start_node_type: str,
+        start_node_parameter_value_commands: list[SerializedNodeCommands.IndirectSetParameterValueCommand],
+        unique_parameter_uuid_to_values: dict[SerializedNodeCommands.UniqueParameterValueUUID, Any],
+        serialized_parameter_value_tracker: SerializedParameterValueTracker,
+    ) -> None:
+        """Apply parameter values from NodeGroupNode to the StartFlow node.
+
+        This method reads the execution environment metadata from the NodeGroupNode,
+        extracts parameter values for the specified StartFlow node type, and creates
+        set parameter value commands for those parameters.
+
+        Args:
+            node_group_node: The NodeGroupNode containing parameter values
+            start_node_library_name: Name of the library containing the StartFlow node
+            start_node_type: Type of the StartFlow node
+            start_node_parameter_value_commands: List to append parameter value commands to
+            unique_parameter_uuid_to_values: Dict to track unique parameter values
+            serialized_parameter_value_tracker: Tracker for serialized parameter values
+
+        Raises:
+            ValueError: If required metadata is missing from NodeGroupNode
+        """
+        # Get execution environment metadata from NodeGroupNode
+        if not node_group_node.metadata:
+            msg = f"NodeGroupNode '{node_group_node.name}' is missing metadata. Cannot apply parameters to StartFlow node."
+            raise ValueError(msg)
+
+        execution_env_metadata = node_group_node.metadata.get("execution_environment")
+        if not execution_env_metadata:
+            msg = f"NodeGroupNode '{node_group_node.name}' metadata is missing 'execution_environment'. Cannot apply parameters to StartFlow node."
+            raise ValueError(msg)
+
+        # Find the metadata for the current library
+        library_metadata = execution_env_metadata.get(start_node_library_name)
+        if library_metadata is None:
+            msg = f"NodeGroupNode '{node_group_node.name}' metadata does not contain library '{start_node_library_name}'. Available libraries: {list(execution_env_metadata.keys())}"
+            raise ValueError(msg)
+
+        # Verify this is the correct StartFlow node type
+        registered_start_flow_node = library_metadata.get("start_flow_node")
+        if registered_start_flow_node != start_node_type:
+            msg = f"NodeGroupNode '{node_group_node.name}' has mismatched StartFlow node type. Expected '{start_node_type}', but metadata has '{registered_start_flow_node}'"
+            raise ValueError(msg)
+
+        # Get the list of parameter names that belong to this StartFlow node
+        parameter_names = library_metadata.get("parameter_names", [])
+        if not parameter_names:
+            # This is not an error - it's valid for a StartFlow node to have no parameters
+            logger.debug(
+                "NodeGroupNode '%s' has no parameters registered for StartFlow node '%s'",
+                node_group_node.name,
+                start_node_type,
+            )
+            return
+
+        # For each parameter, get its value from the NodeGroupNode and create a set value command
+        for prefixed_param_name in parameter_names:
+            # Get the value from the NodeGroupNode parameter
+            param_value = node_group_node.get_parameter_value(param_name=prefixed_param_name)
+
+            # Skip if no value is set
+            if param_value is None:
+                continue
+
+            # Strip the prefix to get the original parameter name for the StartFlow node
+            class_name_prefix = start_node_type.lower()
+            original_param_name = prefixed_param_name.removeprefix(f"{class_name_prefix}_")
+
+            # Create unique parameter UUID for this value
+            value_id = id(param_value)
+            unique_param_uuid = SerializedNodeCommands.UniqueParameterValueUUID(str(uuid4()))
+            unique_parameter_uuid_to_values[unique_param_uuid] = param_value
+            serialized_parameter_value_tracker.add_as_serializable(value_id, unique_param_uuid)
+
+            # Create set parameter value command
+            set_value_request = SetParameterValueRequest(
+                parameter_name=original_param_name,
+                value=None,  # Will be overridden when instantiated
+                is_output=False,
+                initial_setup=True,
+            )
+            indirect_set_value_command = SerializedNodeCommands.IndirectSetParameterValueCommand(
+                set_parameter_value_command=set_value_request,
+                unique_value_uuid=unique_param_uuid,
+            )
+            start_node_parameter_value_commands.append(indirect_set_value_command)
+
     def _create_start_node_parameters_and_connections_for_incoming_data(  # noqa: PLR0913
         self,
         target_node_name: str,
@@ -2076,6 +2256,7 @@ class FlowManager:
         node_name_to_uuid: dict[str, SerializedNodeCommands.NodeUUID],
         unique_parameter_uuid_to_values: dict[SerializedNodeCommands.UniqueParameterValueUUID, Any],
         serialized_parameter_value_tracker: SerializedParameterValueTracker,
+        parameter_name_mappings: dict[SanitizedParameterName, OriginalNodeParameter],
     ) -> StartNodeIncomingDataResult | PackageNodesAsSerializedFlowResultFailure:
         """Create parameters and connections for incoming data connections to a specific target node."""
         start_node_parameter_commands = []
@@ -2093,6 +2274,10 @@ class FlowManager:
                 parameter_name=target_parameter_name,
             )
 
+            parameter_name_mappings[param_name] = OriginalNodeParameter(
+                node_name=target_node_name, parameter_name=target_parameter_name
+            )
+
             # Get the source node to determine parameter type (from the external connection)
             try:
                 source_node = GriptapeNodes.NodeManager().get_node_by_name(connection.source_node_name)
@@ -2339,7 +2524,7 @@ class FlowManager:
             ValidateFlowDependenciesRequest(flow_name=flow_name, flow_node_name=start_node.name if start_node else None)
         )
         try:
-            if not result.succeeded():
+            if result.failed():
                 details = f"Couldn't start flow with name {flow_name}. Flow Validation Failed"
                 return StartFlowResultFailure(validation_exceptions=[], result_details=details)
             result = cast("ValidateFlowDependenciesResultSuccess", result)
@@ -2398,7 +2583,7 @@ class FlowManager:
             ValidateFlowDependenciesRequest(flow_name=flow_name, flow_node_name=start_node.name if start_node else None)
         )
         try:
-            if not result.succeeded():
+            if result.failed():
                 details = f"Couldn't start flow with name {flow_name}. Flow Validation Failed"
                 return StartFlowFromNodeResultFailure(validation_exceptions=[], result_details=details)
             result = cast("ValidateFlowDependenciesResultSuccess", result)
@@ -2428,6 +2613,151 @@ class FlowManager:
 
         return StartFlowFromNodeResultSuccess(result_details=details)
 
+    def get_start_nodes_in_flow(self, flow: ControlFlow) -> list[BaseNode]:  # noqa: C901, PLR0912, PLR0915
+        """Find start nodes in a specific flow.
+
+        A start node is defined as:
+        1. An explicit StartNode instance, OR
+        2. A control node with no incoming control connections, OR
+        3. A data node with no outgoing connections
+
+        Nodes that are children of NodeGroupNodes are excluded.
+
+        Args:
+            flow: The flow to search for start nodes
+
+        Returns:
+            List of start nodes, prioritized as: StartNodes, control nodes, data nodes
+        """
+        connections = self.get_connections()
+        all_nodes = list(flow.nodes.values())
+        if not all_nodes:
+            return []
+
+        start_nodes = []
+        control_nodes = []
+        data_nodes = []
+
+        for node in all_nodes:
+            if isinstance(node, StartNode):
+                start_nodes.append(node)
+                continue
+
+            has_control_param = False
+            for parameter in node.parameters:
+                if ParameterTypeBuiltin.CONTROL_TYPE.value == parameter.output_type:
+                    incoming_control = (
+                        node.name in connections.incoming_index
+                        and parameter.name in connections.incoming_index[node.name]
+                    )
+                    outgoing_control = (
+                        node.name in connections.outgoing_index
+                        and parameter.name in connections.outgoing_index[node.name]
+                    )
+                    if incoming_control or outgoing_control:
+                        has_control_param = True
+                        break
+
+            if not has_control_param:
+                data_nodes.append(node)
+                continue
+
+            has_incoming_control = False
+            if node.name in connections.incoming_index:
+                for param_name in connections.incoming_index[node.name]:
+                    param = node.get_parameter_by_name(param_name)
+                    if param and ParameterTypeBuiltin.CONTROL_TYPE.value == param.output_type:
+                        connection_ids = connections.incoming_index[node.name][param_name]
+                        has_external_control_connection = False
+                        for connection_id in connection_ids:
+                            connection = connections.connections[connection_id]
+                            # Skip internal NodeGroup connections
+                            if connection.is_node_group_internal:
+                                continue
+                            if isinstance(node, BaseIterativeStartNode):
+                                connected_node = connection.get_source_node()
+                                if connected_node == node.end_node:
+                                    continue
+                            has_external_control_connection = True
+                            break
+                        if has_external_control_connection:
+                            has_incoming_control = True
+                            break
+
+            if has_incoming_control:
+                continue
+
+            if node.name in connections.outgoing_index:
+                for param_name in connections.outgoing_index[node.name]:
+                    param = node.get_parameter_by_name(param_name)
+                    if param and ParameterTypeBuiltin.CONTROL_TYPE.value == param.output_type:
+                        control_nodes.append(node)
+                        break
+            else:
+                control_nodes.append(node)
+
+        valid_data_nodes = []
+        for node in data_nodes:
+            # Check if the node has any non-internal outgoing connections
+            has_external_outgoing = False
+            if node.name in connections.outgoing_index:
+                for param_name in connections.outgoing_index[node.name]:
+                    connection_ids = connections.outgoing_index[node.name][param_name]
+                    for connection_id in connection_ids:
+                        connection = connections.connections[connection_id]
+                        # Skip internal NodeGroup connections
+                        if connection.is_node_group_internal:
+                            continue
+                        has_external_outgoing = True
+                        break
+                    if has_external_outgoing:
+                        break
+            # Only add nodes that have no non-internal outgoing connections
+            if not has_external_outgoing:
+                valid_data_nodes.append(node)
+
+        return start_nodes + control_nodes + valid_data_nodes
+
+    async def on_start_local_subflow_request(self, request: StartLocalSubflowRequest) -> ResultPayload:
+        flow_name = request.flow_name
+        if not flow_name:
+            details = "Must provide flow name to start a flow."
+            return StartFlowResultFailure(validation_exceptions=[], result_details=details)
+
+        try:
+            flow = self.get_flow_by_name(flow_name)
+        except KeyError as err:
+            details = f"Cannot start flow. Error: {err}"
+            return StartFlowFromNodeResultFailure(validation_exceptions=[err], result_details=details)
+
+        if not self.check_for_existing_running_flow():
+            msg = "There must be a flow going to start a Subflow"
+            return StartLocalSubflowResultFailure(result_details=msg)
+
+        start_node_name = request.start_node
+        if start_node_name is None:
+            start_nodes = self.get_start_nodes_in_flow(flow)
+            if not start_nodes:
+                details = f"Cannot start subflow '{flow_name}'. No start nodes found in flow."
+                return StartLocalSubflowResultFailure(result_details=details)
+            start_node = start_nodes[0]
+        else:
+            try:
+                start_node = GriptapeNodes.NodeManager().get_node_by_name(start_node_name)
+            except ValueError as err:
+                details = f"Cannot start subflow '{flow_name}'. Start node '{start_node_name}' not found: {err}"
+                return StartLocalSubflowResultFailure(result_details=details)
+
+        subflow_machine = ControlFlowMachine(
+            flow.name,
+            pickle_control_flow_result=request.pickle_control_flow_result,
+            is_isolated=True,
+        )
+
+        await subflow_machine.start_flow(start_node)
+
+        return StartLocalSubflowResultSuccess(result_details=f"Successfully executed local subflow '{flow_name}'")
+
     def on_get_flow_state_request(self, event: GetFlowStateRequest) -> ResultPayload:
         flow_name = event.flow_name
         if not flow_name:
@@ -2674,6 +3004,78 @@ class FlowManager:
 
         return node_types_used
 
+    def _aggregate_connections(
+        self,
+        flow_connections: list[SerializedFlowCommands.IndirectConnectionSerialization],
+        sub_flows_commands: list[SerializedFlowCommands],
+    ) -> list[SerializedFlowCommands.IndirectConnectionSerialization]:
+        """Aggregate connections from this flow and all sub-flows into a single list.
+
+        Args:
+            flow_connections: List of connections from the current flow
+            sub_flows_commands: List of sub-flow commands to aggregate from
+
+        Returns:
+            List of all connections from this flow and all sub-flows combined
+        """
+        aggregated_connections = list(flow_connections)
+
+        # Aggregate connections from all sub-flows
+        for sub_flow_cmd in sub_flows_commands:
+            aggregated_connections.extend(sub_flow_cmd.serialized_connections)
+
+        return aggregated_connections
+
+    def _aggregate_unique_parameter_values(
+        self,
+        unique_parameter_uuid_to_values: dict[SerializedNodeCommands.UniqueParameterValueUUID, Any],
+        sub_flows_commands: list[SerializedFlowCommands],
+    ) -> dict[SerializedNodeCommands.UniqueParameterValueUUID, Any]:
+        """Aggregate unique parameter values from this flow and all sub-flows.
+
+        Args:
+            unique_parameter_uuid_to_values: Unique parameter values from current flow
+            sub_flows_commands: List of sub-flow commands to aggregate from
+
+        Returns:
+            Dictionary with all unique parameter values merged
+        """
+        aggregated_values = dict(unique_parameter_uuid_to_values)
+
+        # Merge unique values from all sub-flows
+        for sub_flow_cmd in sub_flows_commands:
+            aggregated_values.update(sub_flow_cmd.unique_parameter_uuid_to_values)
+
+        return aggregated_values
+
+    def _aggregate_set_parameter_value_commands(
+        self,
+        set_parameter_value_commands: dict[
+            SerializedNodeCommands.NodeUUID, list[SerializedNodeCommands.IndirectSetParameterValueCommand]
+        ],
+        sub_flows_commands: list[SerializedFlowCommands],
+    ) -> dict[SerializedNodeCommands.NodeUUID, list[SerializedNodeCommands.IndirectSetParameterValueCommand]]:
+        """Aggregate set parameter value commands from this flow and all sub-flows.
+
+        Args:
+            set_parameter_value_commands: Set parameter value commands from current flow
+            sub_flows_commands: List of sub-flow commands to aggregate from
+
+        Returns:
+            Dictionary with all set parameter value commands merged
+        """
+        aggregated_commands = dict(set_parameter_value_commands)
+
+        # Merge commands from all sub-flows
+        for sub_flow_cmd in sub_flows_commands:
+            for node_uuid, commands in sub_flow_cmd.set_parameter_value_commands.items():
+                if node_uuid in aggregated_commands:
+                    aggregated_commands[node_uuid].extend(commands)
+                else:
+                    aggregated_commands[node_uuid] = list(commands)
+
+        return aggregated_commands
+
     # TODO: https://github.com/griptape-ai/griptape-nodes/issues/861
     # similar manager refactors: https://github.com/griptape-ai/griptape-nodes/issues/806
     def on_serialize_flow_to_commands(self, request: SerializeFlowToCommandsRequest) -> ResultPayload:  # noqa: C901, PLR0911, PLR0912, PLR0915
@@ -2713,8 +3115,13 @@ class FlowManager:
                 else:
                     # Always set set_as_new_context=False during serialization - let the workflow manager
                     # that loads this serialized flow decide whether to push it to context or not
+                    # Get parent flow name from the flow manager's tracking
+                    parent_name = self.get_parent_flow(flow_name)
                     create_flow_request = CreateFlowRequest(
-                        parent_flow_name=None, set_as_new_context=False, metadata=flow.metadata
+                        flow_name=flow_name,
+                        parent_flow_name=parent_name,
+                        set_as_new_context=False,
+                        metadata=flow.metadata,
                     )
             else:
                 create_flow_request = None
@@ -2772,22 +3179,8 @@ class FlowManager:
                         )
                     set_parameter_value_commands_per_node[serialized_node.node_uuid] = set_value_commands_list
 
-            # We'll have to do a patch-up of all the connections, since we can't predict all of the node names being accurate
-            # when we're restored.
-            # Create all of the connections
-            create_connection_commands = []
-            for connection in self._get_connections_for_flow(flow):
-                source_node_uuid = node_name_to_uuid[connection.source_node.name]
-                target_node_uuid = node_name_to_uuid[connection.target_node.name]
-                create_connection_command = SerializedFlowCommands.IndirectConnectionSerialization(
-                    source_node_uuid=source_node_uuid,
-                    source_parameter_name=connection.source_parameter.name,
-                    target_node_uuid=target_node_uuid,
-                    target_parameter_name=connection.target_parameter.name,
-                )
-                create_connection_commands.append(create_connection_command)
-
-            # Now sub-flows.
+            # Serialize sub-flows first, before creating connections.
+            # We need the complete UUID map from all flows to handle cross-flow connections.
             parent_flow = GriptapeNodes.ContextManager().get_current_flow()
             parent_flow_name = parent_flow.name
             flows_in_flow_request = ListFlowsInFlowRequest(parent_flow_name=parent_flow_name)
@@ -2798,18 +3191,20 @@ class FlowManager:
 
             sub_flow_commands = []
             for child_flow in flows_in_flow_result.flow_names:
-                flow = GriptapeNodes.ObjectManager().attempt_get_object_by_name_as_type(child_flow, ControlFlow)
-                if flow is None:
+                child_flow_obj = GriptapeNodes.ObjectManager().attempt_get_object_by_name_as_type(
+                    child_flow, ControlFlow
+                )
+                if child_flow_obj is None:
                     details = f"Attempted to serialize Flow '{flow_name}', but no Flow with that name could be found."
                     return SerializeFlowToCommandsResultFailure(result_details=details)
 
                 # Check if this is a referenced workflow
-                if self.is_referenced_workflow(flow):
+                if self.is_referenced_workflow(child_flow_obj):
                     # For referenced workflows, create a minimal SerializedFlowCommands with just the import command
-                    referenced_workflow_name = self.get_referenced_workflow_name(flow)
+                    referenced_workflow_name = self.get_referenced_workflow_name(child_flow_obj)
                     import_command = ImportWorkflowAsReferencedSubFlowRequest(
                         workflow_name=referenced_workflow_name,  # type: ignore[arg-type] # is_referenced_workflow() guarantees this is not None
-                        imported_flow_metadata=flow.metadata,
+                        imported_flow_metadata=child_flow_obj.metadata,
                     )
 
                     # Create NodeDependencies with just the referenced workflow
@@ -2831,7 +3226,7 @@ class FlowManager:
                     sub_flow_commands.append(serialized_flow)
                 else:
                     # For standalone sub-flows, use the existing recursive serialization
-                    with GriptapeNodes.ContextManager().flow(flow=flow):
+                    with GriptapeNodes.ContextManager().flow(flow=child_flow_obj):
                         child_flow_request = SerializeFlowToCommandsRequest()
                         child_flow_result = GriptapeNodes().handle_request(child_flow_request)
                         if not isinstance(child_flow_result, SerializeFlowToCommandsResultSuccess):
@@ -2844,6 +3239,65 @@ class FlowManager:
         # This ensures child nodes exist before their parent NodeGroups are created during deserialization
         serialized_node_commands.extend(serialized_node_group_commands)
 
+        # Update NodeGroupNode commands to use UUIDs instead of names in node_names_to_add
+        # This allows workflow generation to directly look up variable names from UUIDs
+        # Build a complete node name to UUID map including nodes from all subflows
+        complete_node_name_to_uuid = dict(node_name_to_uuid)  # Start with current flow's nodes
+
+        def collect_subflow_node_uuids(subflow_commands_list: list[SerializedFlowCommands]) -> None:
+            """Recursively collect node name-to-UUID mappings from subflows."""
+            for subflow_cmd in subflow_commands_list:
+                for node_cmd in subflow_cmd.serialized_node_commands:
+                    # Extract node name from the create command
+                    create_cmd = node_cmd.create_node_command
+                    if isinstance(create_cmd, CreateNodeRequest) and create_cmd.node_name:
+                        complete_node_name_to_uuid[create_cmd.node_name] = node_cmd.node_uuid
+                    elif isinstance(create_cmd, CreateNodeGroupRequest) and create_cmd.node_group_name:
+                        complete_node_name_to_uuid[create_cmd.node_group_name] = node_cmd.node_uuid
+                # Recursively process nested subflows
+                if subflow_cmd.sub_flows_commands:
+                    collect_subflow_node_uuids(subflow_cmd.sub_flows_commands)
+
+        collect_subflow_node_uuids(sub_flow_commands)
+
+        for node_group_command in serialized_node_group_commands:
+            create_cmd = node_group_command.create_node_command
+
+            if isinstance(create_cmd, CreateNodeGroupRequest) and create_cmd.node_names_to_add:
+                # Convert node names to UUIDs using the complete map (including subflows)
+                node_uuids = []
+                for child_node_name in create_cmd.node_names_to_add:
+                    if child_node_name in complete_node_name_to_uuid:
+                        uuid = complete_node_name_to_uuid[child_node_name]
+                        node_uuids.append(uuid)
+                # Replace the list with UUIDs (as strings since that's what the field expects)
+                create_cmd.node_names_to_add = node_uuids
+
+        # Now create the connections using the complete UUID map (includes all flows).
+        # This must happen after subflows are serialized so we have all UUIDs available.
+        create_connection_commands = []
+        for connection in self._get_connections_for_flow(flow):
+            source_node_name = connection.source_node.name
+            target_node_name = connection.target_node.name
+
+            # Use the complete UUID map that includes nodes from all subflows
+            if source_node_name not in complete_node_name_to_uuid:
+                details = f"Attempted to serialize Flow '{flow_name}'. Connection source node '{source_node_name}' not found in UUID map."
+                return SerializeFlowToCommandsResultFailure(result_details=details)
+            if target_node_name not in complete_node_name_to_uuid:
+                details = f"Attempted to serialize Flow '{flow_name}'. Connection target node '{target_node_name}' not found in UUID map."
+                return SerializeFlowToCommandsResultFailure(result_details=details)
+
+            source_node_uuid = complete_node_name_to_uuid[source_node_name]
+            target_node_uuid = complete_node_name_to_uuid[target_node_name]
+            create_connection_command = SerializedFlowCommands.IndirectConnectionSerialization(
+                source_node_uuid=source_node_uuid,
+                source_parameter_name=connection.source_parameter.name,
+                target_node_uuid=target_node_uuid,
+                target_parameter_name=connection.target_parameter.name,
+            )
+            create_connection_commands.append(create_connection_command)
+
         # Aggregate all dependencies from nodes and sub-flows
         aggregated_dependencies = self._aggregate_flow_dependencies(serialized_node_commands, sub_flow_commands)
 
@@ -2854,16 +3308,30 @@ class FlowManager:
             details = f"Attempted to serialize Flow '{flow_name}' to commands. Failed while aggregating node types: {e}"
             return SerializeFlowToCommandsResultFailure(result_details=details)
 
+        # Aggregate unique parameter values from this flow and all sub-flows
+        aggregated_unique_values = self._aggregate_unique_parameter_values(
+            unique_parameter_uuid_to_values, sub_flow_commands
+        )
+
+        # Aggregate all connections from this flow and all sub-flows
+        aggregated_connections = self._aggregate_connections(create_connection_commands, sub_flow_commands)
+
+        # Extract flow name from initialization command if available
+        extracted_flow_name = None
+        if create_flow_request is not None and hasattr(create_flow_request, "flow_name"):
+            extracted_flow_name = create_flow_request.flow_name
+
         serialized_flow = SerializedFlowCommands(
             flow_initialization_command=create_flow_request,
             serialized_node_commands=serialized_node_commands,
-            serialized_connections=create_connection_commands,
-            unique_parameter_uuid_to_values=unique_parameter_uuid_to_values,
+            serialized_connections=aggregated_connections,
+            unique_parameter_uuid_to_values=aggregated_unique_values,
             set_parameter_value_commands=set_parameter_value_commands_per_node,
             set_lock_commands_per_node=set_lock_commands_per_node,
             sub_flows_commands=sub_flow_commands,
             node_dependencies=aggregated_dependencies,
             node_types_used=aggregated_node_types_used,
+            flow_name=extracted_flow_name,
         )
         details = f"Successfully serialized Flow '{flow_name}' into commands."
         result = SerializeFlowToCommandsResultSuccess(serialized_flow_commands=serialized_flow, result_details=details)
@@ -2910,16 +3378,52 @@ class FlowManager:
 
         # Create the nodes.
         # Preserve the node UUIDs because we will need to tie these back together with the Connections later.
+        # Also build a mapping from original node names to deserialized node names.
         node_uuid_to_deserialized_node_result = {}
+        node_name_mappings = {}
         for serialized_node in request.serialized_flow_commands.serialized_node_commands:
-            deserialize_node_request = DeserializeNodeFromCommandsRequest(serialized_node_commands=serialized_node)
+            # Get the node name from the CreateNodeGroupRequest command if necessary
+            create_cmd = serialized_node.create_node_command
+            original_node_name = (
+                create_cmd.node_group_name if isinstance(create_cmd, CreateNodeGroupRequest) else create_cmd.node_name
+            )
+
+            # For NodeGroupNodes, remap node_names_to_add from UUIDs to actual node names
+            # Create a copy to avoid mutating the original serialized data
+            serialized_node_for_deserialization = serialized_node
+            if isinstance(create_cmd, CreateNodeGroupRequest) and create_cmd.node_names_to_add:
+                # Use list comprehension to remap UUIDs to deserialized node names
+                remapped_names = [
+                    node_uuid_to_deserialized_node_result[node_uuid].node_name
+                    for node_uuid in create_cmd.node_names_to_add
+                    if node_uuid in node_uuid_to_deserialized_node_result
+                ]
+                # Create a copy of the command with remapped names instead of mutating original
+                create_cmd_copy = CreateNodeGroupRequest(
+                    node_group_name=create_cmd.node_group_name,
+                    node_names_to_add=remapped_names,
+                    metadata=create_cmd.metadata,
+                )
+                # Create a copy of serialized_node with the new command
+                serialized_node_for_deserialization = SerializedNodeCommands(
+                    node_uuid=serialized_node.node_uuid,
+                    create_node_command=create_cmd_copy,
+                    element_modification_commands=serialized_node.element_modification_commands,
+                    node_dependencies=serialized_node.node_dependencies,
+                    lock_node_command=serialized_node.lock_node_command,
+                )
+
+            deserialize_node_request = DeserializeNodeFromCommandsRequest(
+                serialized_node_commands=serialized_node_for_deserialization
+            )
             deserialized_node_result = GriptapeNodes.handle_request(deserialize_node_request)
-            if deserialized_node_result.failed():
+            if not isinstance(deserialized_node_result, DeserializeNodeFromCommandsResultSuccess):
                 details = (
                     f"Attempted to deserialize a Flow '{flow_name}'. Failed while deserializing a node within the flow."
                 )
                 return DeserializeFlowFromCommandsResultFailure(result_details=details)
             node_uuid_to_deserialized_node_result[serialized_node.node_uuid] = deserialized_node_result
+            node_name_mappings[original_node_name] = deserialized_node_result.node_name
 
         # Now apply the connections.
         # We didn't know the exact name that would be used for the nodes, but we knew the node's creation UUID.
@@ -2992,7 +3496,9 @@ class FlowManager:
                 return DeserializeFlowFromCommandsResultFailure(result_details=details)
 
         details = f"Successfully deserialized Flow '{flow_name}'."
-        return DeserializeFlowFromCommandsResultSuccess(flow_name=flow_name, result_details=details)
+        return DeserializeFlowFromCommandsResultSuccess(
+            flow_name=flow_name, result_details=details, node_name_mappings=node_name_mappings
+        )
 
     async def start_flow(
         self,
@@ -3098,9 +3604,10 @@ class FlowManager:
         self._global_flow_queue.task_done()
         return queue_item.node
 
-    def clear_execution_queue(self) -> None:
+    def clear_execution_queue(self, flow: ControlFlow) -> None:
         """Clear all nodes from the global execution queue."""
-        self._global_flow_queue.queue.clear()
+        if self._global_control_flow_machine and self._global_control_flow_machine.context.flow_name == flow.name:
+            self._global_flow_queue.queue.clear()
 
     def has_connection(
         self,
@@ -3303,10 +3810,13 @@ class FlowManager:
                     connection_ids = connections.incoming_index[node.name][parameter_name]
                     for connection_id in connection_ids:
                         connection = connections.connections[connection_id]
+                        # Skip internal NodeGroup connections
+                        if connection.is_node_group_internal:
+                            continue
                         return connection.get_source_node()
         return None
 
-    def get_start_node_queue(self) -> Queue | None:  # noqa: C901, PLR0912
+    def get_start_node_queue(self) -> Queue | None:  # noqa: C901, PLR0912, PLR0915
         # For cross-flow execution, we need to consider ALL nodes across ALL flows
         # Clear and use the global execution queue
         self._global_flow_queue.queue.clear()
@@ -3327,6 +3837,10 @@ class FlowManager:
         control_nodes = []
         cn_mgr = self.get_connections()
         for node in all_nodes:
+            # Skip nodes that are children of a NodeGroupNode - they should not be start nodes
+            if node.parent_group is not None and isinstance(node.parent_group, NodeGroupNode):
+                continue
+
             # if it's a start node, start here! Return the first one!
             if isinstance(node, StartNode):
                 start_nodes.append(node)
@@ -3358,17 +3872,26 @@ class FlowManager:
                     param = node.get_parameter_by_name(param_name)
                     if param and ParameterTypeBuiltin.CONTROL_TYPE.value == param.output_type:
                         # there is a control connection coming in
-                        # If the node is a StartLoopNode, it may have an incoming hidden connection from it's EndLoopNode for iteration.
-                        if isinstance(node, StartLoopNode):
-                            connection_id = cn_mgr.incoming_index[node.name][param_name][0]
+                        # Check each connection to see if it's an internal NodeGroup connection
+                        connection_ids = cn_mgr.incoming_index[node.name][param_name]
+                        has_external_control_connection = False
+                        for connection_id in connection_ids:
                             connection = cn_mgr.connections[connection_id]
-                            connected_node = connection.get_source_node()
-                            # Check if the source node is the end loop node associated with this StartLoopNode.
-                            # If it is, then this could still be the first node in the control flow.
-                            if connected_node == node.end_node:
+                            # Skip internal NodeGroup connections - they shouldn't disqualify a node from being a start node
+                            if connection.is_node_group_internal:
                                 continue
-                        has_control_connection = True
-                        break
+                            # If the node is a BaseIterativeStartNode, it may have an incoming hidden connection from it's BaseIterativeEndNode for iteration.
+                            if isinstance(node, BaseIterativeStartNode):
+                                connected_node = connection.get_source_node()
+                                # Check if the source node is the end loop node associated with this BaseIterativeStartNode.
+                                # If it is, then this could still be the first node in the control flow.
+                                if connected_node == node.end_node:
+                                    continue
+                            has_external_control_connection = True
+                            break
+                        if has_external_control_connection:
+                            has_control_connection = True
+                            break
             # if there is a connection coming in, isn't a start.
             if has_control_connection:
                 continue
@@ -3387,8 +3910,22 @@ class FlowManager:
         # Let's return a data node that has no OUTGOING data connections!
         for node in data_nodes:
             cn_mgr = self.get_connections()
-            # check if it has an outgoing connection. We don't want it to (that means we get the most resolution)
-            if node.name not in cn_mgr.outgoing_index:
+            # Check if the node has any non-internal outgoing connections
+            has_external_outgoing = False
+            if node.name in cn_mgr.outgoing_index:
+                for param_name in cn_mgr.outgoing_index[node.name]:
+                    connection_ids = cn_mgr.outgoing_index[node.name][param_name]
+                    for connection_id in connection_ids:
+                        connection = cn_mgr.connections[connection_id]
+                        # Skip internal NodeGroup connections
+                        if connection.is_node_group_internal:
+                            continue
+                        has_external_outgoing = True
+                        break
+                    if has_external_outgoing:
+                        break
+            # Only add nodes that have no non-internal outgoing connections
+            if not has_external_outgoing:
                 valid_data_nodes.append(node)
         # ok now - populate the global flow queue with node type information
         for node in start_nodes:
@@ -3440,7 +3977,7 @@ class FlowManager:
                     connections.append((connection.source_node, connection.source_parameter))
         return connections
 
-    def get_connections_on_node(self, flow: ControlFlow, node: BaseNode) -> list[BaseNode] | None:  # noqa: ARG002
+    def get_connections_on_node(self, node: BaseNode) -> list[BaseNode] | None:
         connections = self.get_connections()
         # get all of the connection ids
         connected_nodes = []
@@ -3467,7 +4004,7 @@ class FlowManager:
         # Return all connected nodes. No duplicates
         return connected_nodes
 
-    def get_all_connected_nodes(self, flow: ControlFlow, node: BaseNode) -> list[BaseNode]:
+    def get_all_connected_nodes(self, node: BaseNode) -> list[BaseNode]:
         discovered = {}
         processed = {}
         queue = Queue()
@@ -3476,7 +4013,7 @@ class FlowManager:
         while not queue.empty():
             curr_node = queue.get()
             processed[curr_node] = True
-            next_nodes = self.get_connections_on_node(flow, curr_node)
+            next_nodes = self.get_connections_on_node(curr_node)
             if next_nodes:
                 for next_node in next_nodes:
                     if next_node not in discovered:
@@ -3484,6 +4021,10 @@ class FlowManager:
                         queue.put(next_node)
         return list(processed.keys())
 
+    def is_node_connected(self, start_node: BaseNode, node: BaseNode) -> bool:
+        nodes = self.get_all_connected_nodes(start_node)
+        return node in nodes
+
     def get_node_dependencies(self, flow: ControlFlow, node: BaseNode) -> list[BaseNode]:
         """Get all upstream nodes that the given node depends on.