griptape-nodes 0.59.2__py3-none-any.whl → 0.60.0__py3-none-any.whl

griptape_nodes/retained_mode/events/os_events.py

@@ -1,4 +1,5 @@
 from dataclasses import dataclass
+from enum import StrEnum
 
 from griptape_nodes.retained_mode.events.base_events import (
     RequestPayload,
@@ -9,6 +10,43 @@ from griptape_nodes.retained_mode.events.base_events import (
 from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 
 
+class ExistingFilePolicy(StrEnum):
+    """Policy for handling existing files during write operations."""
+
+    OVERWRITE = "overwrite"  # Replace existing file content
+    FAIL = "fail"  # Fail if file exists
+    CREATE_NEW = "create_new"  # Create new file with modified name (e.g., file_1.txt)
+
+
+class FileIOFailureReason(StrEnum):
+    """Classification of file I/O failure reasons.
+
+    Used by read and write operations to provide structured error information.
+    """
+
+    # Policy violations
+    POLICY_NO_OVERWRITE = "policy_no_overwrite"  # File exists and policy prohibits overwrite
+    POLICY_NO_CREATE_PARENT_DIRS = "policy_no_create_parent_dirs"  # Parent dir missing and policy prohibits creation
+
+    # Permission/access errors
+    PERMISSION_DENIED = "permission_denied"  # No read/write permission
+    FILE_NOT_FOUND = "file_not_found"  # File doesn't exist (read operations)
+
+    # Resource errors
+    DISK_FULL = "disk_full"  # Insufficient disk space
+
+    # Path errors
+    INVALID_PATH = "invalid_path"  # Malformed or invalid path
+    IS_DIRECTORY = "is_directory"  # Path is a directory, not a file
+
+    # Content errors
+    ENCODING_ERROR = "encoding_error"  # Text encoding/decoding failed
+
+    # Generic errors
+    IO_ERROR = "io_error"  # Generic I/O error
+    UNKNOWN = "unknown"  # Unexpected error
+
+
 @dataclass
 class FileSystemEntry:
     """Represents a file or directory in the file system."""
@@ -50,7 +88,14 @@ class OpenAssociatedFileResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSucc
 @dataclass
 @PayloadRegistry.register
 class OpenAssociatedFileResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    """File or directory opening failed. Common causes: path not found, no associated application, permission denied."""
+    """File or directory opening failed.
+
+    Attributes:
+        failure_reason: Classification of why the open failed
+        result_details: Human-readable error message (inherited from ResultPayloadFailure)
+    """
+
+    failure_reason: FileIOFailureReason
 
 
 @dataclass
@@ -88,7 +133,14 @@ class ListDirectoryResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
 @dataclass
 @PayloadRegistry.register
 class ListDirectoryResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    """Directory listing failed. Common causes: access denied, path not found."""
+    """Directory listing failed.
+
+    Attributes:
+        failure_reason: Classification of why the listing failed
+        result_details: Human-readable error message (inherited from ResultPayloadFailure)
+    """
+
+    failure_reason: FileIOFailureReason
 
 
 @dataclass
@@ -105,6 +157,7 @@ class ReadFileRequest(RequestPayload):
         encoding: Text encoding to use if file is detected as text (default: 'utf-8')
         workspace_only: If True, constrain to workspace directory. If False, allow system-wide access.
                         If None, workspace constraints don't apply (e.g., cloud environments).
+                        TODO: Remove workspace_only parameter - see https://github.com/griptape-ai/griptape-nodes/issues/2753
 
     Results: ReadFileResultSuccess (with content) | ReadFileResultFailure (file not found, permission denied)
     """
@@ -112,7 +165,7 @@ class ReadFileRequest(RequestPayload):
     file_path: str | None = None
     file_entry: FileSystemEntry | None = None
     encoding: str = "utf-8"
-    workspace_only: bool | None = True
+    workspace_only: bool | None = True  # TODO: Remove - see https://github.com/griptape-ai/griptape-nodes/issues/2753
 
 
 @dataclass
@@ -139,7 +192,14 @@ class ReadFileResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
 @dataclass
 @PayloadRegistry.register
 class ReadFileResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    """File reading failed. Common causes: file not found, permission denied, encoding error."""
+    """File reading failed.
+
+    Attributes:
+        failure_reason: Classification of why the read failed
+        result_details: Human-readable error message (inherited from ResultPayloadFailure)
+    """
+
+    failure_reason: FileIOFailureReason
 
 
 @dataclass
@@ -193,7 +253,14 @@ class CreateFileResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
 @dataclass
 @PayloadRegistry.register
 class CreateFileResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    """File/directory creation failed."""
+    """File/directory creation failed.
+
+    Attributes:
+        failure_reason: Classification of why the creation failed
+        result_details: Human-readable error message (inherited from ResultPayloadFailure)
+    """
+
+    failure_reason: FileIOFailureReason
 
 
 @dataclass
@@ -229,4 +296,73 @@ class RenameFileResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
 @dataclass
 @PayloadRegistry.register
 class RenameFileResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    """File/directory rename failed."""
+    """File/directory rename failed.
+
+    Attributes:
+        failure_reason: Classification of why the rename failed
+        result_details: Human-readable error message (inherited from ResultPayloadFailure)
+    """
+
+    failure_reason: FileIOFailureReason
+
+
+@dataclass
+@PayloadRegistry.register
+class WriteFileRequest(RequestPayload):
+    """Write content to a file.
+
+    Automatically detects text vs binary mode based on content type.
+
+    Use when: Saving generated content, writing output files,
+    creating configuration files, writing binary data.
+
+    Args:
+        file_path: Path to the file to write
+        content: Content to write (str for text files, bytes for binary files)
+        encoding: Text encoding for str content (default: 'utf-8', ignored for bytes)
+        append: If True, append to existing file; if False, use existing_file_policy (default: False)
+        existing_file_policy: How to handle existing files when append=False:
+            - "overwrite": Replace file content (default)
+            - "fail": Return failure if file exists
+            - "create_new": Create new file with modified name (NOT YET IMPLEMENTED)
+        create_parents: If True, create parent directories if missing (default: True)
+
+    Results: WriteFileResultSuccess | WriteFileResultFailure
+
+    Note: existing_file_policy is ignored when append=True (append always allows existing files)
+    """
+
+    file_path: str
+    content: str | bytes
+    encoding: str = "utf-8"  # Ignored for bytes
+    append: bool = False
+    existing_file_policy: ExistingFilePolicy = ExistingFilePolicy.OVERWRITE
+    create_parents: bool = True
+
+
+@dataclass
+@PayloadRegistry.register
+class WriteFileResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """File written successfully.
+
+    Attributes:
+        final_file_path: The actual path where file was written
+                        (may differ from requested path if create_new policy used)
+        bytes_written: Number of bytes written to the file
+    """
+
+    final_file_path: str
+    bytes_written: int
+
+
+@dataclass
+@PayloadRegistry.register
+class WriteFileResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """File write failed.
+
+    Attributes:
+        failure_reason: Classification of why the write failed
+        result_details: Human-readable error message (inherited from ResultPayloadFailure)
+    """
+
+    failure_reason: FileIOFailureReason

griptape_nodes/retained_mode/events/parameter_events.py

@@ -47,6 +47,7 @@ class AddParameterToNodeRequest(RequestPayload):
         mode_allowed_output: Whether parameter can be used as output
         is_user_defined: Whether this is a user-defined parameter (affects serialization)
         parent_container_name: Name of parent container if nested
+        parent_element_name: Name of parent element if nested
         initial_setup: Skip setup work when loading from file
         settable: Whether parameter can be set directly by the user or not
 
@@ -71,6 +72,7 @@ class AddParameterToNodeRequest(RequestPayload):
     is_user_defined: bool = Field(default=True)
     settable: bool = Field(default=True)
     parent_container_name: str | None = None
+    parent_element_name: str | None = None
     # initial_setup prevents unnecessary work when we are loading a workflow from a file.
     initial_setup: bool = False
 

griptape_nodes/retained_mode/griptape_nodes.py

@@ -58,6 +58,7 @@ if TYPE_CHECKING:
         StaticFilesManager,
     )
     from griptape_nodes.retained_mode.managers.sync_manager import SyncManager
+    from griptape_nodes.retained_mode.managers.user_manager import UserManager
     from griptape_nodes.retained_mode.managers.variable_manager import (
         VariablesManager,
     )
@@ -93,6 +94,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
     _mcp_manager: MCPManager
     _resource_manager: ResourceManager
     _sync_manager: SyncManager
+    _user_manager: UserManager
 
     def __init__(self) -> None:
         from griptape_nodes.retained_mode.managers.agent_manager import AgentManager
@@ -120,6 +122,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
             StaticFilesManager,
         )
         from griptape_nodes.retained_mode.managers.sync_manager import SyncManager
+        from griptape_nodes.retained_mode.managers.user_manager import UserManager
         from griptape_nodes.retained_mode.managers.variable_manager import (
             VariablesManager,
         )
@@ -156,6 +159,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
             self._session_manager = SessionManager(self._engine_identity_manager, self._event_manager)
             self._mcp_manager = MCPManager(self._event_manager, self._config_manager)
             self._sync_manager = SyncManager(self._event_manager, self._config_manager)
+            self._user_manager = UserManager(self._secrets_manager)
 
             # Assign handlers now that these are created.
             self._event_manager.assign_manager_to_request_type(
@@ -322,6 +326,10 @@ class GriptapeNodes(metaclass=SingletonMeta):
     def VariablesManager(cls) -> VariablesManager:
         return GriptapeNodes.get_instance()._workflow_variables_manager
 
+    @classmethod
+    def UserManager(cls) -> UserManager:
+        return GriptapeNodes.get_instance()._user_manager
+
     @classmethod
     def clear_data(cls) -> None:
         # Get canvas
@@ -374,6 +382,10 @@ class GriptapeNodes(metaclass=SingletonMeta):
             # Get engine name
             engine_name = GriptapeNodes.EngineIdentityManager().engine_name
 
+            # Get user and organization
+            user = GriptapeNodes.UserManager().user
+            user_organization = GriptapeNodes.UserManager().user_organization
+
             return EngineHeartbeatResultSuccess(
                 heartbeat_id=request.heartbeat_id,
                 engine_version=engine_version,
@@ -381,6 +393,8 @@ class GriptapeNodes(metaclass=SingletonMeta):
                 engine_id=GriptapeNodes.EngineIdentityManager().active_engine_id,
                 session_id=GriptapeNodes.SessionManager().active_session_id,
                 timestamp=datetime.now(tz=UTC).isoformat(),
+                user=user,
+                user_organization=user_organization,
                 result_details="Engine heartbeat successful",
                 **instance_info,
                 **workflow_info,

griptape_nodes/retained_mode/managers/agent_manager.py

@@ -208,8 +208,8 @@ class AgentManager:
     def _create_agent(self, additional_mcp_servers: list[str] | None = None) -> Agent:
         output_schema = Schema(
             {
-                "generated_image_urls": [str],
                 "conversation_output": str,
+                "generated_image_urls": [str],
             }
         )
 
@@ -249,10 +249,11 @@ class AgentManager:
                 if url_artifact["type"] == "ImageUrlArtifact"
             ]
             agent = self._create_agent(additional_mcp_servers=request.additional_mcp_servers)
-            *events, last_event = agent.run_stream([request.input, *artifacts])
+            event_stream = agent.run_stream([request.input, *artifacts])
             full_result = ""
             last_conversation_output = ""
-            for event in events:
+            last_event = None
+            for event in event_stream:
                 if isinstance(event, TextChunkEvent):
                     full_result += event.token
                     try:
@@ -273,6 +274,7 @@ class AgentManager:
                                 last_conversation_output = new_conversation_output
                     except json.JSONDecodeError:
                         pass  # Ignore incomplete JSON
+                last_event = event
             if isinstance(last_event, FinishTaskEvent):
                 if isinstance(last_event.task_output, ErrorArtifact):
                     return RunAgentResultFailure(

griptape_nodes/retained_mode/managers/arbitrary_code_exec_manager.py

@@ -40,7 +40,25 @@ class ArbitraryCodeExecManager:
         try:
             string_buffer = io.StringIO()
             with redirect_stdout(string_buffer):
-                python_output = exec(request.python_string)  # noqa: S102
+                # Use a shared namespace for both globals and locals in exec() to make some behavior possible and more intuitive:
+                #
+                # 1. RECURSION: Without this namespace, recursive functions defined inside exec() fail with
+                #    "NameError: name 'function_name' is not defined" when they try to call themselves.
+                #    Why? When exec() runs with default parameters, functions defined in the exec'd code
+                #    exist in this method's local scope. But inside the exec'd functions, Python looks in the program's
+                #    global scope (outside this method) and the function's own local scope - neither of which
+                #    contains the recursive function definition. By passing the same dict as both globals and locals,
+                #    any function defined in exec'd code becomes visible in what exec'd code sees as
+                #    "global" scope, allowing recursive calls to find the function definition.
+                #
+                # 2. ISOLATION: An isolated namespace prevents exec'd code from accessing or modifying
+                #    variables in the outer program scope, protecting read/write access to sensitive engine data.
+                # For the PR that implements this behavior alongside an Execute Python and List Files node, see https://github.com/griptape-ai/griptape-nodes/pull/2087
+
+                namespace = {"__builtins__": __builtins__}
+                python_output = exec(  # noqa: S102
+                    request.python_string, namespace, namespace
+                )
 
             captured_output = strip_ansi_codes(string_buffer.getvalue())
             result = RunArbitraryPythonStringResultSuccess(

griptape_nodes/retained_mode/managers/library_manager.py

@@ -169,8 +169,6 @@ class LibraryManager:
         self._library_event_handler_mappings: dict[type[Payload], dict[str, LibraryManager.RegisteredEventHandler]] = {}
         # LibraryDirectory owns the FSMs and manages library lifecycle
         self._library_directory = LibraryDirectory()
-        # Lock for synchronizing sys.path modifications during parallel library installation
-        self._sys_path_lock = asyncio.Lock()
 
         event_manager.assign_manager_to_request_type(
             ListRegisteredLibrariesRequest, self.on_list_registered_libraries_request
@@ -726,8 +724,7 @@ class LibraryManager:
         # Get the directory containing the JSON file to resolve relative paths
         base_dir = json_path.parent.absolute()
         # Add the directory to the Python path to allow for relative imports
-        async with self._sys_path_lock:
-            sys.path.insert(0, str(base_dir))
+        sys.path.insert(0, str(base_dir))
 
         # Load the advanced library module if specified
         advanced_library_instance = None
@@ -1060,8 +1057,7 @@ class LibraryManager:
                 )
             )
         )
-        async with self._sys_path_lock:
-            sys.path.insert(0, site_packages)
+        sys.path.insert(0, site_packages)
 
         return library_venv_python_path
 
@@ -1503,27 +1499,6 @@ class LibraryManager:
 
         return node_class
 
-    async def _register_single_library(self, library_result: LoadLibraryMetadataFromFileResultSuccess) -> None:
-        """Register a single library (sandbox or config-based) and handle errors.
-
-        Args:
-            library_result: The metadata result for the library to register
-        """
-        try:
-            if library_result.library_schema.name == LibraryManager.SANDBOX_LIBRARY_NAME:
-                await self._attempt_generate_sandbox_library_from_schema(
-                    library_schema=library_result.library_schema, sandbox_directory=library_result.file_path
-                )
-            else:
-                register_request = RegisterLibraryFromFileRequest(
-                    file_path=library_result.file_path, load_as_default_library=False
-                )
-                register_result = await self.register_library_from_file_request(register_request)
-                if isinstance(register_result, RegisterLibraryFromFileResultFailure):
-                    logger.warning("Failed to register library from %s", library_result.file_path)
-        except Exception as e:
-            logger.warning("Failed to register library from %s with exception: %s", library_result.file_path, e)
-
     async def load_all_libraries_from_config(self) -> None:
         # Load metadata for all libraries to determine which ones can be safely loaded
         metadata_request = LoadMetadataForAllLibrariesRequest()
@@ -1543,10 +1518,23 @@ class LibraryManager:
                 problems=failed_library.problems,
             )
 
-        # Use task group for parallel library loading
-        async with asyncio.TaskGroup() as tg:
-            for library_result in metadata_result.successful_libraries:
-                tg.create_task(self._register_single_library(library_result))
+        # Use metadata results to selectively load libraries
+        for library_result in metadata_result.successful_libraries:
+            if library_result.library_schema.name == LibraryManager.SANDBOX_LIBRARY_NAME:
+                # Handle sandbox library - use the schema we already have
+                await self._attempt_generate_sandbox_library_from_schema(
+                    library_schema=library_result.library_schema, sandbox_directory=library_result.file_path
+                )
+            else:
+                # Handle config-based library - register it directly using the file path
+                register_request = RegisterLibraryFromFileRequest(
+                    file_path=library_result.file_path, load_as_default_library=False
+                )
+                register_result = await self.register_library_from_file_request(register_request)
+                if isinstance(register_result, RegisterLibraryFromFileResultFailure):
+                    # Registration failed - the failure info is already recorded in _library_file_path_to_info
+                    # by register_library_from_file_request, so we just log it here for visibility
+                    logger.warning("Failed to register library from %s", library_result.file_path)
 
         # Print 'em all pretty
         self.print_library_load_status()
@@ -1604,6 +1592,13 @@ class LibraryManager:
         session_id = GriptapeNodes.get_session_id()
         session_info = f" | Session: {session_id[:8]}..." if session_id else " | No Session"
 
+        # Get user and organization
+        user = GriptapeNodes.UserManager().user
+        user_info = f" | User: {user.email if user else 'Not available'}"
+
+        user_organization = GriptapeNodes.UserManager().user_organization
+        org_info = f" | Org: {user_organization.name if user_organization else 'Not available'}"
+
         nodes_app_url = os.getenv("GRIPTAPE_NODES_UI_BASE_URL", "https://nodes.griptape.ai")
         message = Panel(
             Align.center(
@@ -1612,7 +1607,7 @@ class LibraryManager:
                 vertical="middle",
             ),
             title="Griptape Nodes Engine Started",
-            subtitle=f"[green]{engine_version}{session_info}[/green]",
+            subtitle=f"[green]Version: {engine_version}{session_info}{user_info}{org_info}[/green]",
             border_style="green",
             padding=(1, 4),
         )

griptape_nodes/retained_mode/managers/node_manager.py

@@ -918,6 +918,7 @@ class NodeManager:
     def on_add_parameter_to_node_request(self, request: AddParameterToNodeRequest) -> ResultPayload:  # noqa: C901, PLR0911, PLR0912, PLR0915
         node_name = request.node_name
         node = None
+        parent_group: ParameterGroup | None = None
 
         if node_name is None:
             # Get from the current context.
@@ -968,6 +969,15 @@ class NodeManager:
                 node_name=node_name,
                 result_details=f"Successfully added parameter '{new_param.name}' to container parameter '{request.parent_container_name}' in node '{node_name}'.",
             )
+        if request.parent_element_name is not None:
+            parent_element = node.get_element_by_name_and_type(request.parent_element_name)
+            if parent_element is None:
+                details = f"Attempted to add Parameter to Parent Element '{request.parent_element_name}' in node '{node_name}'. Failed because element didn't exist."
+                result = AddParameterToNodeResultFailure(result_details=details)
+                return result
+            # Handle ParameterGroup parentage with potential to expand in future to other element types.
+            if isinstance(parent_element, ParameterGroup):
+                parent_group = parent_element
         if request.parameter_name is None or request.tooltip is None:
             details = f"Attempted to add Parameter to node '{node_name}'. Failed because default_value, tooltip, or parameter_name was not defined."
             result = AddParameterToNodeResultFailure(result_details=details)
@@ -1032,6 +1042,7 @@ class NodeManager:
             allowed_modes=allowed_modes,
             ui_options=request.ui_options,
             parent_container_name=request.parent_container_name,
+            parent_element_name=parent_group.name if parent_group is not None else None,
             settable=request.settable,
         )
         try:
@@ -1039,6 +1050,8 @@ class NodeManager:
                 parameter_parent = node.get_parameter_by_name(request.parent_container_name)
                 if parameter_parent is not None:
                     parameter_parent.add_child(new_param)
+            elif parent_group is not None:
+                parent_group.add_child(new_param)
             else:
                 node.add_parameter(new_param)
         except Exception as e:
@@ -2586,7 +2599,7 @@ class NodeManager:
     ) -> SerializedNodeCommands.IndirectSetParameterValueCommand | None:
         try:
             hash(value)
-            value_id = value
+            value_id = (type(value), value)
         except TypeError:
             # Couldn't get a hash. Use the object's ID
             value_id = id(value)