griptape-nodes 0.71.0__py3-none-any.whl → 0.72.1__py3-none-any.whl

griptape_nodes/retained_mode/managers/library_manager.py

@@ -193,6 +193,7 @@ from griptape_nodes.utils.library_utils import (
     filter_old_xdg_library_paths,
     is_monorepo,
 )
+from griptape_nodes.utils.path_utils import resolve_workspace_path
 from griptape_nodes.utils.uv_utils import find_uv_bin
 from griptape_nodes.utils.version_utils import get_complete_version_string
 
@@ -2428,7 +2429,18 @@ class LibraryManager:
         # Collect results
         return dict(task.result() for task in tasks)
 
-    async def on_app_initialization_complete(self, _payload: AppInitializationComplete) -> None:
+    async def on_app_initialization_complete(self, payload: AppInitializationComplete) -> None:
+        if payload.skip_library_loading:
+            # Register all secrets even in headless mode
+            GriptapeNodes.SecretsManager().register_all_secrets()
+
+            # Still need to tell WorkflowManager to register workflows
+            # Pass the specific workflows if provided, otherwise it will scan workspace
+            GriptapeNodes.WorkflowManager().on_libraries_initialization_complete(
+                workflows_to_register=payload.workflows_to_register
+            )
+            return
+
         # Automatically migrate old XDG library paths from config
         # TODO: Remove https://github.com/griptape-ai/griptape-nodes/issues/3348
         self._migrate_old_xdg_library_paths()
@@ -2530,9 +2542,7 @@ class LibraryManager:
             return None
 
         # Resolve relative path to absolute path
-        advanced_library_module_path = Path(library_data.advanced_library_path)
-        if not advanced_library_module_path.is_absolute():
-            advanced_library_module_path = base_dir / advanced_library_module_path
+        advanced_library_module_path = resolve_workspace_path(Path(library_data.advanced_library_path), base_dir)
 
         # Load the module (supports hot reloading)
         try:
@@ -2624,9 +2634,7 @@ class LibraryManager:
         # Process each node in the metadata
         for node_definition in library_data.nodes:
             # Resolve relative path to absolute path
-            node_file_path = Path(node_definition.file_path)
-            if not node_file_path.is_absolute():
-                node_file_path = base_dir / node_file_path
+            node_file_path = resolve_workspace_path(Path(node_definition.file_path), base_dir)
 
             try:
                 # Dynamically load the module containing the node class
@@ -2987,6 +2995,37 @@ class LibraryManager:
         )
         return ReloadAllLibrariesResultSuccess(result_details=ResultDetails(message=details, level=logging.INFO))
 
+    def _create_library_info_entry(self, file_path_str: str, *, is_sandbox: bool) -> None:
+        """Create a LibraryInfo entry for a discovered library.
+
+        Loads metadata if possible and creates the entry in the appropriate lifecycle state.
+        Only creates the entry if it doesn't already exist in tracking.
+        """
+        if file_path_str in self._library_file_path_to_info:
+            return
+
+        metadata_result = self.load_library_metadata_from_file_request(
+            LoadLibraryMetadataFromFileRequest(file_path=file_path_str)
+        )
+
+        library_name = None
+        library_version = None
+        lifecycle_state = LibraryManager.LibraryLifecycleState.DISCOVERED
+
+        if isinstance(metadata_result, LoadLibraryMetadataFromFileResultSuccess):
+            library_name = metadata_result.library_schema.name
+            library_version = metadata_result.library_schema.metadata.library_version
+            lifecycle_state = LibraryManager.LibraryLifecycleState.METADATA_LOADED
+
+        self._library_file_path_to_info[file_path_str] = LibraryManager.LibraryInfo(
+            lifecycle_state=lifecycle_state,
+            fitness=LibraryManager.LibraryFitness.NOT_EVALUATED,
+            library_path=file_path_str,
+            is_sandbox=is_sandbox,
+            library_name=library_name,
+            library_version=library_version,
+        )
+
     def discover_libraries_request(
         self,
         request: DiscoverLibrariesRequest,
@@ -2997,14 +3036,15 @@ class LibraryManager:
         Scans configured library paths and creates LibraryInfo entries in DISCOVERED state.
         """
         try:
-            config_library_paths = set(self._discover_library_files())
+            config_library_paths = self._discover_library_files()
         except Exception as e:
             logger.exception("Failed to discover library files")
             return DiscoverLibrariesResultFailure(
                 result_details=f"Failed to discover library files: {e}",
             )
 
-        discovered_libraries = set()
+        discovered_libraries = []
+        seen_libraries = set()
 
         # Process sandbox library first if requested
         if request.include_sandbox:
@@ -3033,39 +3073,24 @@ class LibraryManager:
                     # Continue anyway if write failed - lifecycle will fail gracefully
 
                     # Add to discovered libraries with is_sandbox=True
-                    discovered_libraries.add(DiscoveredLibrary(path=sandbox_json_path, is_sandbox=True))
-
-                    # Create minimal LibraryInfo entry in discovered state if not already tracked
-                    if sandbox_json_path_str not in self._library_file_path_to_info:
-                        self._library_file_path_to_info[sandbox_json_path_str] = LibraryManager.LibraryInfo(
-                            lifecycle_state=LibraryManager.LibraryLifecycleState.DISCOVERED,
-                            fitness=LibraryManager.LibraryFitness.NOT_EVALUATED,
-                            library_path=sandbox_json_path_str,
-                            is_sandbox=True,
-                            library_name=None,
-                            library_version=None,
-                        )
+                    if sandbox_json_path not in seen_libraries:
+                        seen_libraries.add(sandbox_json_path)
+                        discovered_libraries.append(DiscoveredLibrary(path=sandbox_json_path, is_sandbox=True))
+
+                    # Create LibraryInfo entry for the sandbox library
+                    self._create_library_info_entry(sandbox_json_path_str, is_sandbox=True)
 
         # Add all regular libraries from config
         for file_path in config_library_paths:
             file_path_str = str(file_path)
 
             # Add to discovered libraries with is_sandbox=False
-            discovered_libraries.add(DiscoveredLibrary(path=file_path, is_sandbox=False))
+            if file_path not in seen_libraries:
+                seen_libraries.add(file_path)
+                discovered_libraries.append(DiscoveredLibrary(path=file_path, is_sandbox=False))
 
-            # Skip if already tracked
-            if file_path_str in self._library_file_path_to_info:
-                continue
-
-            # Create minimal LibraryInfo entry in discovered state
-            self._library_file_path_to_info[file_path_str] = LibraryManager.LibraryInfo(
-                lifecycle_state=LibraryManager.LibraryLifecycleState.DISCOVERED,
-                fitness=LibraryManager.LibraryFitness.NOT_EVALUATED,
-                library_path=file_path_str,
-                is_sandbox=False,
-                library_name=None,
-                library_version=None,
-            )
+            # Create LibraryInfo entry for the library
+            self._create_library_info_entry(file_path_str, is_sandbox=False)
 
         # Success path at the end
         return DiscoverLibrariesResultSuccess(
@@ -3230,20 +3255,25 @@ class LibraryManager:
         """Discover library JSON files from config and workspace recursively.
 
         Returns:
-            List of library file paths found
+            List of library file paths found, in the order they appear in config
         """
         config_mgr = GriptapeNodes.ConfigManager()
         user_libraries_section = LIBRARIES_TO_REGISTER_KEY
 
-        discovered_libraries = set()
+        discovered_libraries = []
+        seen_libraries = set()
 
         def process_path(path: Path) -> None:
             """Process a path, handling both files and directories."""
             if path.is_dir():
                 # Recursively find library files, skipping hidden directories
-                discovered_libraries.update(find_files_recursive(path, LibraryManager.LIBRARY_CONFIG_GLOB_PATTERN))
-            elif path.suffix == ".json":
-                discovered_libraries.add(path)
+                for lib_path in find_files_recursive(path, LibraryManager.LIBRARY_CONFIG_GLOB_PATTERN):
+                    if lib_path not in seen_libraries:
+                        seen_libraries.add(lib_path)
+                        discovered_libraries.append(lib_path)
+            elif path.suffix == ".json" and path not in seen_libraries:
+                seen_libraries.add(path)
+                discovered_libraries.append(path)
 
         # Add from config
         config_libraries = config_mgr.get_config_value(user_libraries_section, default=[])
@@ -3254,7 +3284,7 @@ class LibraryManager:
                 if library_path.exists():
                     process_path(library_path)
 
-        return list(discovered_libraries)
+        return discovered_libraries
 
     async def check_library_update_request(self, request: CheckLibraryUpdateRequest) -> ResultPayload:  # noqa: C901, PLR0911, PLR0912, PLR0915
         """Check if a library has updates available via git."""

griptape_nodes/retained_mode/managers/model_manager.py

@@ -1119,6 +1119,7 @@ class ModelManager:
             msg = f"Download status file not found for model '{model_id}'"
             raise FileNotFoundError(msg)
 
+        # TODO: Replace with DeleteFileRequest https://github.com/griptape-ai/griptape-nodes/issues/3765
         status_file.unlink()
         return str(status_file)
 

griptape_nodes/retained_mode/managers/node_manager.py

@@ -402,9 +402,7 @@ class NodeManager:
             )
         # modifying to exception to try to catch all possible issues with node creation.
         except Exception as err:
-            import traceback
-
-            traceback.print_exc()
+            logger.error(err)
             details = f"Could not create Node '{final_node_name}' of type '{request.node_type}': {err}"
 
             # Check if we should create an Error Proxy node instead of failing
@@ -3291,6 +3289,7 @@ class NodeManager:
         create_node_request: CreateNodeRequest,
         *,
         use_pickling: bool = False,
+        serialize_all_parameter_values: bool = False,
     ) -> list[SerializedNodeCommands.IndirectSetParameterValueCommand] | None:
         """Generates code to save a parameter value for a node in a Griptape workflow.
 
@@ -3309,6 +3308,7 @@ class NodeManager:
             serialized_parameter_value_tracker (SerializedParameterValueTracker): Object mapping maintaining value hashes to unique value UUIDs, and non-serializable values
             create_node_request (CreateNodeRequest): The node creation request that will be modified if serialization fails
             use_pickling (bool): If True, use pickle-based serialization; if False, use deep copy
+            serialize_all_parameter_values (bool): If True, save all parameter values regardless of whether they were explicitly set or match defaults
 
         Returns:
             None (if no value to be serialized) or an IndirectSetParameterValueCommand linking the value to the unique value map
@@ -3329,8 +3329,11 @@ class NodeManager:
         # Save the value if it was explicitly set OR if it equals the default value.
         # The latter ensures the default is preserved when loading workflows,
         # even if the code's default value changes later.
-        if parameter.name in node.parameter_values or (
-            parameter.default_value is not None and effective_value == parameter.default_value
+        # If serialize_all_parameter_values is True, save all parameter values regardless.
+        if (
+            serialize_all_parameter_values
+            or parameter.name in node.parameter_values
+            or (parameter.default_value is not None and effective_value == parameter.default_value)
         ):
             internal_value = effective_value
         # We have a value. Attempt to get a hash for it to see if it matches one

griptape_nodes/retained_mode/managers/os_manager.py

@@ -1,4 +1,6 @@
+import asyncio
 import base64
+import ctypes
 import logging
 import mimetypes
 import os
@@ -7,12 +9,14 @@ import shutil
 import stat
 import subprocess
 import sys
+from ctypes import wintypes
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, NamedTuple
+from typing import Any, ClassVar, NamedTuple
 
 import aioshutil
 import portalocker
+import send2trash
 from binaryornot.check import is_binary
 from rich.console import Console
 
@@ -35,6 +39,8 @@ from griptape_nodes.retained_mode.events.os_events import (
     DeleteFileRequest,
     DeleteFileResultFailure,
     DeleteFileResultSuccess,
+    DeletionBehavior,
+    DeletionOutcome,
     ExistingFilePolicy,
     FileIOFailureReason,
     FileSystemEntry,
@@ -139,6 +145,14 @@ class FilenameParts(NamedTuple):
     extension: str
 
 
+class WindowsSpecialFolderError(OSError):
+    """Raised when Windows Shell API (SHGetFolderPathW) fails for a special folder.
+
+    Callers (e.g. try_resolve_windows_special_folder) catch this to fall back
+    to expanduser or other resolution.
+    """
+
+
 class FilePathValidationError(Exception):
     """Raised when file path validation fails before write operation.
 
@@ -170,6 +184,19 @@ class CopyTreeStats:
     total_bytes_copied: int
 
 
+class WindowsSpecialFolderResult(NamedTuple):
+    """Result of resolving a Windows special folder from path parts.
+
+    Invariant: either both fields are None (not resolved), or both are set
+    (resolved). When resolved, special_path is the folder Path and
+    remaining_parts is the list of path components after the folder (may be
+    empty). We never return (None, list) or (Path, None).
+    """
+
+    special_path: Path | None
+    remaining_parts: list[str] | None
+
+
 class OSManager:
     """A class to manage OS-level scenarios.
 
@@ -177,6 +204,80 @@ class OSManager:
     This lays the groundwork to exclude specific functionality on a configuration basis.
     """
 
+    # Windows CSIDL constants for special folders (used by _expand_path)
+    # https://learn.microsoft.com/en-us/windows/win32/shell/csidl
+    WINDOWS_CSIDL_MAP: ClassVar[dict[str, int]] = {
+        "desktop": 0x0000,  # CSIDL_DESKTOP
+        "documents": 0x0005,  # CSIDL_PERSONAL (My Documents)
+        "downloads": 0x0033,  # CSIDL_DOWNLOADS
+        "pictures": 0x0027,  # CSIDL_MYPICTURES
+        "videos": 0x000E,  # CSIDL_MYVIDEO
+        "music": 0x000D,  # CSIDL_MYMUSIC
+    }
+
+    @staticmethod
+    def normalize_path_parts_for_special_folder(path_str: str) -> list[str]:
+        r"""Parse a path string into normalized parts for special folder detection.
+
+        Strips leading ~ or ~/, or %UserProfile% / %USERPROFILE% (case-insensitive);
+        expands env vars when %UserProfile% is present; returns lowercased path
+        parts. Used to detect Windows special folder names (e.g. ~/Downloads,
+        %UserProfile%/Desktop). Also strips Windows long path prefix (\\?\ or
+        \\?\UNC\) so prefixed paths parse correctly instead of producing "?"
+        as the first part.
+
+        Args:
+            path_str: Path string that may contain ~ or %UserProfile% (case-insensitive).
+
+        Returns:
+            List of lowercased path parts, e.g. ["downloads"] for "~/Downloads".
+        """
+        normalized = path_str.replace("\\", "/")
+        # Strip Windows long path prefix so we don't get "?" as first part
+        if normalized.upper().startswith("//?/UNC/"):
+            normalized = "//" + normalized[8:]  # Keep UNC as //server/share
+        elif normalized.startswith("//?/"):
+            normalized = normalized[4:]
+        if normalized.startswith("~/"):
+            normalized = normalized[2:]
+        elif normalized.startswith("~"):
+            normalized = normalized[1:]
+        if "%USERPROFILE%" in normalized.upper():
+            normalized = os.path.expandvars(normalized)
+            normalized = normalized.replace("\\", "/")  # expandvars can return backslashes on Windows
+            userprofile = os.environ.get("USERPROFILE", "")
+            if userprofile and normalized.lower().startswith(userprofile.lower().replace("\\", "/")):
+                normalized = normalized[len(userprofile) :].lstrip("/\\")
+        parts = [p.lower() for p in normalized.split("/") if p]
+        return parts
+
+    def try_resolve_windows_special_folder(self, parts: list[str]) -> WindowsSpecialFolderResult | None:
+        """Resolve Windows special folder from path parts.
+
+        If the first part matches a known special folder name (e.g. "desktop",
+        "downloads"), calls _get_windows_special_folder_path and returns a
+        result with special_path and remaining_parts. Returns None if parts are
+        empty, the first part is unknown, or the Shell API raises
+        WindowsSpecialFolderError (caller catches and falls back).
+
+        Args:
+            parts: Lowercased path parts from normalize_path_parts_for_special_folder.
+
+        Returns:
+            WindowsSpecialFolderResult when resolved (special_path and remaining_parts),
+            or None when no special folder could be resolved.
+        """
+        if not parts or parts[0] not in OSManager.WINDOWS_CSIDL_MAP:
+            return None
+        csidl = OSManager.WINDOWS_CSIDL_MAP[parts[0]]
+        try:
+            special_path = self._get_windows_special_folder_path(csidl)
+        except WindowsSpecialFolderError:
+            # No warning: Shell API failure is an expected fallback path; not useful to users.
+            return None
+        remaining = parts[1:] if len(parts) > 1 else []
+        return WindowsSpecialFolderResult(special_path=special_path, remaining_parts=remaining)
+
     def __init__(self, event_manager: EventManager | None = None):
         if event_manager is not None:
             event_manager.assign_manager_to_request_type(
@@ -230,18 +331,89 @@ class OSManager:
         """Get the workspace path from config."""
         return GriptapeNodes.ConfigManager().workspace_path
 
+    def _get_windows_special_folder_path(self, csidl: int) -> Path:
+        """Get Windows special folder path using Shell API.
+
+        Source: https://stackoverflow.com/a/30924555
+        Uses SHGetFolderPathW to get the actual location of special folders,
+        handling OneDrive redirections and other Windows folder redirections.
+        Callers (e.g. try_resolve_windows_special_folder) should catch
+        WindowsSpecialFolderError and fall back to expanduser.
+
+        Args:
+            csidl: CSIDL constant for the special folder (e.g., CSIDL_DESKTOP)
+
+        Returns:
+            Path to the special folder.
+
+        Raises:
+            RuntimeError: If not on Windows (programming error).
+            WindowsSpecialFolderError: If the Shell API fails (HRESULT or ctypes exception).
+        """
+        if not self.is_windows():
+            msg = "_get_windows_special_folder_path may only be called on Windows"
+            raise RuntimeError(msg)
+
+        # Argtypes for SHGetFolderPathW (Windows Shell API)
+        # https://learn.microsoft.com/en-us/windows/win32/shell/csidl
+        sh_get_folder_path_argtypes = (
+            wintypes.HWND,
+            ctypes.c_int,
+            wintypes.HANDLE,
+            wintypes.DWORD,
+            wintypes.LPCWSTR,
+        )
+
+        def _call_shell_api() -> Path:
+            # windll is Windows-only; code path is guarded by is_windows()
+            sh_get_folder_path = ctypes.windll.shell32.SHGetFolderPathW  # pyright: ignore[reportAttributeAccessIssue]
+            sh_get_folder_path.argtypes = sh_get_folder_path_argtypes
+
+            path_buf = ctypes.create_unicode_buffer(wintypes.MAX_PATH)
+            result = sh_get_folder_path(0, csidl, 0, 0, path_buf)
+            if result != 0:  # S_OK is 0; non-zero is an HRESULT error code
+                msg = f"Windows Shell API SHGetFolderPathW failed for CSIDL {csidl}: HRESULT {result}"
+                raise WindowsSpecialFolderError(msg)
+            return Path(path_buf.value)
+
+        try:
+            return _call_shell_api()
+        except WindowsSpecialFolderError:
+            raise
+        except Exception as e:  # Broad catch: ctypes/Shell API can raise many types
+            msg = f"Windows Shell API SHGetFolderPathW failed for CSIDL {csidl}: {e}"
+            raise WindowsSpecialFolderError(msg) from e
+
     def _expand_path(self, path_str: str) -> Path:
-        """Expand a path string, handling tilde and environment variables.
+        """Expand a path string, handling tilde, environment variables, and special folders.
+
+        Handles Windows special folders (like Desktop) that may be redirected to OneDrive
+        by using Windows Shell API (SHGetFolderPathW) to get the actual system paths.
 
         Args:
-            path_str: Path string that may contain ~ or environment variables
+            path_str: Path string that may contain ~, environment variables, or special folder names
 
         Returns:
             Expanded Path object
         """
-        # Expand environment variables first, then tilde
-        expanded_vars = os.path.expandvars(path_str)
-        return self.resolve_path_safely(Path(expanded_vars).expanduser())
+        resolved = None
+        if self.is_windows():
+            parts = self.normalize_path_parts_for_special_folder(path_str)
+            resolved = self.try_resolve_windows_special_folder(parts)
+
+        # Success path at the end - compute final path and return
+        if resolved is not None and resolved.special_path is not None:
+            extra_parts: list[str] = resolved.remaining_parts if resolved.remaining_parts else []
+            if extra_parts:
+                final_path = resolved.special_path / Path(*extra_parts)
+            else:
+                final_path = resolved.special_path
+        else:
+            expanded_vars = os.path.expandvars(path_str)
+            expanded_user = os.path.expanduser(expanded_vars)  # noqa: PTH111
+            final_path = Path(expanded_user)
+
+        return self.resolve_path_safely(final_path)
 
     def resolve_path_safely(self, path: Path) -> Path:
         """Resolve a path consistently across platforms.
@@ -285,6 +457,13 @@ class OSManager:
         # This works consistently even for non-existent paths on Windows
         return Path(os.path.normpath(path))
 
+    def _path_needs_expansion(self, path_str: str) -> bool:
+        """Return True if path contains env vars, is absolute, or starts with ~ (needs _expand_path)."""
+        has_env_vars = "%" in path_str or "$" in path_str
+        is_absolute = Path(path_str).is_absolute()
+        starts_with_tilde = path_str.startswith("~")
+        return has_env_vars or is_absolute or starts_with_tilde
+
     def _resolve_file_path(self, path_str: str, *, workspace_only: bool = False) -> Path:
         """Resolve a file path, handling absolute, relative, and tilde paths.
 
@@ -296,10 +475,8 @@ class OSManager:
             Resolved Path object
         """
         try:
-            if Path(path_str).is_absolute() or path_str.startswith("~"):
-                # Expand tilde and environment variables for absolute paths or paths starting with ~
+            if self._path_needs_expansion(path_str):
                 return self._expand_path(path_str)
-            # Both workspace and system-wide modes resolve relative to current directory
             return self.resolve_path_safely(self._get_workspace_path() / path_str)
         except (ValueError, RuntimeError):
             if workspace_only:
@@ -1199,12 +1376,9 @@ class OSManager:
             # Get the directory path to list
             if request.directory_path is None:
                 directory = self._get_workspace_path()
-            # Handle paths consistently - always resolve relative paths relative to current directory
-            elif Path(request.directory_path).is_absolute() or request.directory_path.startswith("~"):
-                # Expand tilde and environment variables for absolute paths or paths starting with ~
+            elif self._path_needs_expansion(request.directory_path):
                 directory = self._expand_path(request.directory_path)
             else:
-                # Both workspace and system-wide modes resolve relative to current directory
                 directory = self.resolve_path_safely(self._get_workspace_path() / request.directory_path)
 
             # Check if directory exists
@@ -2036,6 +2210,8 @@ class OSManager:
                 flags=portalocker.LockFlags.EXCLUSIVE | portalocker.LockFlags.NON_BLOCKING,
             ) as fh:
                 fh.write(content)
+                fh.flush()
+                os.fsync(fh.fileno())
 
             # Calculate bytes written
             if isinstance(content, bytes):
@@ -2251,6 +2427,7 @@ class OSManager:
         for file_path, _ in files_with_times:
             try:
                 # Delete the file.
+                # TODO: Replace with DeleteFileRequest https://github.com/griptape-ai/griptape-nodes/issues/3765
                 file_path.unlink()
                 removed_count += 1
 
@@ -2538,10 +2715,10 @@ class OSManager:
             console.print(f"[red]Details: {e}[/red]")
             raise
 
-    async def on_delete_file_request(self, request: DeleteFileRequest) -> ResultPayload:  # noqa: PLR0911, PLR0912, C901
+    async def on_delete_file_request(  # noqa: PLR0911, PLR0912, PLR0915, C901
+        self, request: DeleteFileRequest
+    ) -> DeleteFileResultSuccess | DeleteFileResultFailure:
         """Handle a request to delete a file or directory."""
-        # FAILURE CASES FIRST (per CLAUDE.md)
-
         # Validate exactly one of path or file_entry provided and determine path to delete
         if request.path is not None and request.file_entry is not None:
             msg = "Attempted to delete file with both path and file_entry. Failed due to invalid parameters"
@@ -2578,28 +2755,88 @@ class OSManager:
         else:
             deleted_paths = [str(resolved_path)]
 
-        # Perform deletion
-        try:
-            if is_directory:
-                await aioshutil.rmtree(resolved_path, onexc=OSManager.remove_readonly)
-            else:
-                resolved_path.unlink()
-        except PermissionError as e:
-            msg = f"Attempted to delete {'directory' if is_directory else 'file'} at path {path_to_delete}. Failed due to permission denied: {e}"
-            return DeleteFileResultFailure(failure_reason=FileIOFailureReason.PERMISSION_DENIED, result_details=msg)
-        except OSError as e:
-            msg = f"Attempted to delete {'directory' if is_directory else 'file'} at path {path_to_delete}. Failed due to I/O error: {e}"
-            return DeleteFileResultFailure(failure_reason=FileIOFailureReason.IO_ERROR, result_details=msg)
-        except Exception as e:
-            msg = f"Attempted to delete {'directory' if is_directory else 'file'} at path {path_to_delete}. Failed due to unexpected error: {type(e).__name__}: {e}"
-            return DeleteFileResultFailure(failure_reason=FileIOFailureReason.UNKNOWN, result_details=msg)
+        # Helper function for permanent deletion
+        async def attempt_permanent_delete() -> DeleteFileResultFailure | None:
+            """Permanently delete the file/directory. Returns failure result or None on success."""
+            try:
+                if is_directory:
+                    await aioshutil.rmtree(resolved_path, onexc=OSManager.remove_readonly)
+                else:
+                    resolved_path.unlink()
+            except PermissionError as e:
+                msg = f"Attempted to delete {'directory' if is_directory else 'file'} at path {path_to_delete}. Failed due to permission denied: {e}"
+                return DeleteFileResultFailure(failure_reason=FileIOFailureReason.PERMISSION_DENIED, result_details=msg)
+            except OSError as e:
+                msg = f"Attempted to delete {'directory' if is_directory else 'file'} at path {path_to_delete}. Failed due to I/O error: {e}"
+                return DeleteFileResultFailure(failure_reason=FileIOFailureReason.IO_ERROR, result_details=msg)
+            except Exception as e:
+                msg = f"Attempted to delete {'directory' if is_directory else 'file'} at path {path_to_delete}. Failed due to unexpected error: {type(e).__name__}: {e}"
+                return DeleteFileResultFailure(failure_reason=FileIOFailureReason.UNKNOWN, result_details=msg)
+            return None
+
+        # Helper function for recycle bin deletion
+        async def attempt_recycle_bin_delete() -> DeleteFileResultFailure | None:
+            """Send to recycle bin. Returns failure result or None on success."""
+            try:
+                await asyncio.to_thread(send2trash.send2trash, str(resolved_path))
+            except send2trash.TrashPermissionError as e:
+                msg = f"Attempted to send {'directory' if is_directory else 'file'} at path {path_to_delete} to the recycle bin. Failed due to recycle bin unavailable: {e}"
+                return DeleteFileResultFailure(
+                    failure_reason=FileIOFailureReason.RECYCLE_BIN_UNAVAILABLE, result_details=msg
+                )
+            except OSError as e:
+                msg = f"Attempted to send {'directory' if is_directory else 'file'} at path {path_to_delete} to the recycle bin. Failed due to I/O error: {e}"
+                return DeleteFileResultFailure(failure_reason=FileIOFailureReason.IO_ERROR, result_details=msg)
+            except Exception as e:
+                msg = f"Attempted to send {'directory' if is_directory else 'file'} at path {path_to_delete} to the recycle bin. Failed due to unexpected error: {type(e).__name__}: {e}"
+                return DeleteFileResultFailure(failure_reason=FileIOFailureReason.UNKNOWN, result_details=msg)
+            return None
+
+        # Perform deletion based on requested behavior
+        match request.deletion_behavior:
+            case DeletionBehavior.PERMANENTLY_DELETE:
+                failure = await attempt_permanent_delete()
+                if failure:
+                    return failure
+                outcome = DeletionOutcome.PERMANENTLY_DELETED
+                result_details = (
+                    f"Successfully deleted {'directory' if is_directory else 'file'} at path {path_to_delete}"
+                )
+
+            case DeletionBehavior.RECYCLE_BIN_ONLY:
+                failure = await attempt_recycle_bin_delete()
+                if failure:
+                    return failure
+                outcome = DeletionOutcome.SENT_TO_RECYCLE_BIN
+                result_details = f"Successfully sent {'directory' if is_directory else 'file'} at path {path_to_delete} to the recycle bin"
+
+            case DeletionBehavior.PREFER_RECYCLE_BIN:
+                failure = await attempt_recycle_bin_delete()
+                if failure:
+                    # Fall back to permanent deletion
+                    failure = await attempt_permanent_delete()
+                    if failure:
+                        return failure
+                    outcome = DeletionOutcome.PERMANENTLY_DELETED
+                    result_details = ResultDetails(
+                        message=f"Attempted to send {'directory' if is_directory else 'file'} at path {path_to_delete} to the recycle bin, but this failed; fell back to permanent deletion, which succeeded.",
+                        level=logging.WARNING,
+                    )
+                else:
+                    outcome = DeletionOutcome.SENT_TO_RECYCLE_BIN
+                    result_details = f"Successfully sent {'directory' if is_directory else 'file'} at path {path_to_delete} to the recycle bin"
+
+            case _:
+                msg = f"Unknown/unsupported deletion behavior: {request.deletion_behavior}"
+                raise ValueError(msg)
 
         # SUCCESS PATH AT END
         return DeleteFileResultSuccess(
             deleted_path=str(resolved_path),
             was_directory=is_directory,
             deleted_paths=deleted_paths,
-            result_details=f"Successfully deleted {'directory' if is_directory else 'file'} at path {path_to_delete}",
+            outcome=outcome,
+            result_details=result_details,
         )
 
     def on_get_file_info_request(  # noqa: PLR0911