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

griptape_nodes/retained_mode/managers/os_manager.py

@@ -7,7 +7,7 @@ import subprocess
 import sys
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any
+from typing import Any, NamedTuple
 
 from binaryornot.check import is_binary
 from rich.console import Console
@@ -18,6 +18,8 @@ from griptape_nodes.retained_mode.events.os_events import (
     CreateFileRequest,
     CreateFileResultFailure,
     CreateFileResultSuccess,
+    ExistingFilePolicy,
+    FileIOFailureReason,
     FileSystemEntry,
     ListDirectoryRequest,
     ListDirectoryResultFailure,
@@ -31,6 +33,9 @@ from griptape_nodes.retained_mode.events.os_events import (
     RenameFileRequest,
     RenameFileResultFailure,
     RenameFileResultSuccess,
+    WriteFileRequest,
+    WriteFileResultFailure,
+    WriteFileResultSuccess,
 )
 from griptape_nodes.retained_mode.events.resource_events import (
     CreateResourceInstanceRequest,
@@ -45,6 +50,9 @@ from griptape_nodes.retained_mode.managers.resource_types.os_resource import OSR
 
 console = Console()
 
+# Windows MAX_PATH limit - paths longer than this need \\?\ prefix
+WINDOWS_MAX_PATH = 260
+
 
 @dataclass
 class DiskSpaceInfo:
@@ -55,6 +63,16 @@ class DiskSpaceInfo:
     free: int
 
 
+class FileContentResult(NamedTuple):
+    """Result from reading file content."""
+
+    content: str | bytes
+    encoding: str | None
+    mime_type: str
+    compression_encoding: str | None
+    file_size: int
+
+
 class OSManager:
     """A class to manage OS-level scenarios.
 
@@ -83,6 +101,10 @@ class OSManager:
                 request_type=RenameFileRequest, callback=self.on_rename_file_request
             )
 
+            event_manager.assign_manager_to_request_type(
+                request_type=WriteFileRequest, callback=self.on_write_file_request
+            )
+
             # Register for app initialization event to setup system resources
             event_manager.add_listener_to_app_event(AppInitializationComplete, self.on_app_initialization_complete)
 
@@ -156,6 +178,31 @@ class OSManager:
         logger.debug(msg)
         return True, relative
 
+    def _normalize_path_for_platform(self, path: Path) -> str:
+        r"""Convert Path to string with Windows long path support if needed.
+
+        Windows has a 260 character path limit (MAX_PATH). Paths longer than this
+        need the \\?\ prefix to work correctly. This method transparently adds
+        the prefix when needed on Windows.
+
+        Args:
+            path: Path object to convert to string
+
+        Returns:
+            String representation of path, with Windows long path prefix if needed
+        """
+        path_str = str(path.resolve())
+
+        # Windows long path handling (paths > WINDOWS_MAX_PATH chars need \\?\ prefix)
+        if self.is_windows() and len(path_str) > WINDOWS_MAX_PATH and not path_str.startswith("\\\\?\\"):
+            # UNC paths (\\server\share) need \\?\UNC\ prefix
+            if path_str.startswith("\\\\"):
+                return f"\\\\?\\UNC\\{path_str[2:]}"
+            # Regular paths need \\?\ prefix
+            return f"\\\\?\\{path_str}"
+
+        return path_str
+
     def _validate_read_file_request(self, request: ReadFileRequest) -> tuple[Path, str]:
         """Validate read file request and return resolved file path and path string."""
         # Validate that exactly one of file_path or file_entry is provided
@@ -236,12 +283,12 @@ class OSManager:
         if request.path_to_file is None and request.file_entry is None:
             msg = "Either path_to_file or file_entry must be provided"
             logger.error(msg)
-            return OpenAssociatedFileResultFailure(result_details=msg)
+            return OpenAssociatedFileResultFailure(failure_reason=FileIOFailureReason.INVALID_PATH, result_details=msg)
 
         if request.path_to_file is not None and request.file_entry is not None:
             msg = "Only one of path_to_file or file_entry should be provided, not both"
             logger.error(msg)
-            return OpenAssociatedFileResultFailure(result_details=msg)
+            return OpenAssociatedFileResultFailure(failure_reason=FileIOFailureReason.INVALID_PATH, result_details=msg)
 
         # Get the file path to open
         if request.file_entry is not None:
@@ -254,13 +301,13 @@ class OSManager:
             # This should never happen due to validation above, but type checker needs it
             msg = "No valid file path provided"
             logger.error(msg)
-            return OpenAssociatedFileResultFailure(result_details=msg)
+            return OpenAssociatedFileResultFailure(failure_reason=FileIOFailureReason.INVALID_PATH, result_details=msg)
 
         # At this point, file_path_str is guaranteed to be a string
         if file_path_str is None:
             msg = "No valid file path provided"
             logger.error(msg)
-            return OpenAssociatedFileResultFailure(result_details=msg)
+            return OpenAssociatedFileResultFailure(failure_reason=FileIOFailureReason.INVALID_PATH, result_details=msg)
 
         # Sanitize and validate the path (file or directory)
         try:
@@ -269,12 +316,16 @@ class OSManager:
         except (ValueError, RuntimeError):
             details = f"Invalid file path: '{file_path_str}'"
             logger.info(details)
-            return OpenAssociatedFileResultFailure(result_details=details)
+            return OpenAssociatedFileResultFailure(
+                failure_reason=FileIOFailureReason.INVALID_PATH, result_details=details
+            )
 
         if not path.exists():
             details = f"Path does not exist: '{path}'"
             logger.info(details)
-            return OpenAssociatedFileResultFailure(result_details=details)
+            return OpenAssociatedFileResultFailure(
+                failure_reason=FileIOFailureReason.FILE_NOT_FOUND, result_details=details
+            )
 
         logger.info("Attempting to open path: %s on platform: %s", path, sys.platform)
 
@@ -283,12 +334,12 @@ class OSManager:
             if self.is_windows():
                 # Linter complains but this is the recommended way on Windows
                 # We can ignore this warning as we've validated the path
-                os.startfile(str(path))  # noqa: S606 # pyright: ignore[reportAttributeAccessIssue]
+                os.startfile(self._normalize_path_for_platform(path))  # noqa: S606 # pyright: ignore[reportAttributeAccessIssue]
                 logger.info("Opened path on Windows: %s", path)
             elif self.is_mac():
                 # On macOS, open should be in a standard location
                 subprocess.run(  # noqa: S603
-                    ["/usr/bin/open", str(path)],
+                    ["/usr/bin/open", self._normalize_path_for_platform(path)],
                     check=True,  # Explicitly use check
                     capture_output=True,
                     text=True,
@@ -303,10 +354,12 @@ class OSManager:
                 if not xdg_path:
                     details = "xdg-open not found in standard locations"
                     logger.info(details)
-                    return OpenAssociatedFileResultFailure(result_details=details)
+                    return OpenAssociatedFileResultFailure(
+                        failure_reason=FileIOFailureReason.IO_ERROR, result_details=details
+                    )
 
                 subprocess.run(  # noqa: S603
-                    [xdg_path, str(path)],
+                    [xdg_path, self._normalize_path_for_platform(path)],
                     check=True,  # Explicitly use check
                     capture_output=True,
                     text=True,
@@ -315,7 +368,9 @@ class OSManager:
             else:
                 details = f"Unsupported platform: '{platform_name}'"
                 logger.info(details)
-                return OpenAssociatedFileResultFailure(result_details=details)
+                return OpenAssociatedFileResultFailure(
+                    failure_reason=FileIOFailureReason.IO_ERROR, result_details=details
+                )
 
             return OpenAssociatedFileResultSuccess(result_details="File opened successfully in associated application.")
         except subprocess.CalledProcessError as e:
@@ -323,11 +378,11 @@ class OSManager:
                 f"Process error when opening file: return code={e.returncode}, stdout={e.stdout}, stderr={e.stderr}"
             )
             logger.error(details)
-            return OpenAssociatedFileResultFailure(result_details=details)
+            return OpenAssociatedFileResultFailure(failure_reason=FileIOFailureReason.IO_ERROR, result_details=details)
         except Exception as e:
             details = f"Exception occurred when trying to open path: {e}"
             logger.error(details)
-            return OpenAssociatedFileResultFailure(result_details=details)
+            return OpenAssociatedFileResultFailure(failure_reason=FileIOFailureReason.UNKNOWN, result_details=details)
 
     def _detect_mime_type(self, file_path: Path) -> str | None:
         """Detect MIME type for a file. Returns None for directories or if detection fails."""
@@ -335,7 +390,7 @@ class OSManager:
             return None
 
         try:
-            mime_type, _ = mimetypes.guess_type(str(file_path), strict=True)
+            mime_type, _ = mimetypes.guess_type(self._normalize_path_for_platform(file_path), strict=True)
             if mime_type is None:
                 mime_type = "text/plain"
             return mime_type  # noqa: TRY300
@@ -344,7 +399,7 @@ class OSManager:
             logger.warning(msg)
             return "text/plain"
 
-    def on_list_directory_request(self, request: ListDirectoryRequest) -> ResultPayload:  # noqa: C901, PLR0911
+    def on_list_directory_request(self, request: ListDirectoryRequest) -> ResultPayload:  # noqa: C901, PLR0911, PLR0912
         """Handle a request to list directory contents."""
         try:
             # Get the directory path to list
@@ -362,18 +417,18 @@ class OSManager:
             if not directory.exists():
                 msg = f"Directory does not exist: {directory}"
                 logger.error(msg)
-                return ListDirectoryResultFailure(result_details=msg)
+                return ListDirectoryResultFailure(failure_reason=FileIOFailureReason.FILE_NOT_FOUND, result_details=msg)
             if not directory.is_dir():
-                msg = f"Directory is not a directory: {directory}"
+                msg = f"Path is not a directory: {directory}"
                 logger.error(msg)
-                return ListDirectoryResultFailure(result_details=msg)
+                return ListDirectoryResultFailure(failure_reason=FileIOFailureReason.INVALID_PATH, result_details=msg)
 
             # Check workspace constraints
             is_workspace_path, relative_or_abs_path = self._validate_workspace_path(directory)
             if request.workspace_only and not is_workspace_path:
                 msg = f"Directory is outside workspace: {directory}"
                 logger.error(msg)
-                return ListDirectoryResultFailure(result_details=msg)
+                return ListDirectoryResultFailure(failure_reason=FileIOFailureReason.INVALID_PATH, result_details=msg)
 
             entries = []
             try:
@@ -403,10 +458,16 @@ class OSManager:
                         logger.warning(msg)
                         continue
 
-            except (OSError, PermissionError) as e:
-                msg = f"Error listing directory {directory}: {e}"
+            except PermissionError as e:
+                msg = f"Permission denied listing directory {directory}: {e}"
+                logger.error(msg)
+                return ListDirectoryResultFailure(
+                    failure_reason=FileIOFailureReason.PERMISSION_DENIED, result_details=msg
+                )
+            except OSError as e:
+                msg = f"I/O error listing directory {directory}: {e}"
                 logger.error(msg)
-                return ListDirectoryResultFailure(result_details=msg)
+                return ListDirectoryResultFailure(failure_reason=FileIOFailureReason.IO_ERROR, result_details=msg)
 
             # Return appropriate path format based on mode
             if request.workspace_only:
@@ -428,62 +489,78 @@ class OSManager:
         except Exception as e:
             msg = f"Unexpected error in list_directory: {type(e).__name__}: {e}"
             logger.error(msg)
-            return ListDirectoryResultFailure(result_details=msg)
+            return ListDirectoryResultFailure(failure_reason=FileIOFailureReason.UNKNOWN, result_details=msg)
 
-    def on_read_file_request(self, request: ReadFileRequest) -> ResultPayload:
+    def on_read_file_request(self, request: ReadFileRequest) -> ResultPayload:  # noqa: PLR0911
         """Handle a request to read file contents with automatic text/binary detection."""
-        # Initialize variables that might be used in exception handlers
-        file_path: Path | None = None
-        file_path_str: str | None = None
-
+        # Validate request and get file path
         try:
-            # Validate request and get file path
-            file_path, file_path_str = self._validate_read_file_request(request)
-
-            # Read file content
-            content, encoding, mime_type, compression_encoding, file_size = self._read_file_content(file_path, request)
-
-            return ReadFileResultSuccess(
-                content=content,
-                file_size=file_size,
-                mime_type=mime_type,
-                encoding=encoding,
-                compression_encoding=compression_encoding,
-                result_details="File read successfully.",
-            )
+            file_path, _file_path_str = self._validate_read_file_request(request)
+        except FileNotFoundError as e:
+            msg = f"File not found: {e}"
+            logger.error(msg)
+            return ReadFileResultFailure(failure_reason=FileIOFailureReason.FILE_NOT_FOUND, result_details=msg)
+        except PermissionError as e:
+            msg = f"Permission denied: {e}"
+            logger.error(msg)
+            return ReadFileResultFailure(failure_reason=FileIOFailureReason.PERMISSION_DENIED, result_details=msg)
+        except (ValueError, RuntimeError) as e:
+            msg = f"Invalid path: {e}"
+            logger.error(msg)
+            return ReadFileResultFailure(failure_reason=FileIOFailureReason.INVALID_PATH, result_details=msg)
+        except OSError as e:
+            msg = f"I/O error validating path: {e}"
+            logger.error(msg)
+            return ReadFileResultFailure(failure_reason=FileIOFailureReason.IO_ERROR, result_details=msg)
 
-        except (ValueError, FileNotFoundError) as e:
-            file_info = f" for file: {file_path}" if file_path is not None else ""
-            msg = f"Validation error in read_file{file_info}: {e}"
+        # Read file content
+        try:
+            result = self._read_file_content(file_path, request)
+        except PermissionError as e:
+            msg = f"Permission denied for file {file_path}: {e}"
+            logger.error(msg)
+            return ReadFileResultFailure(failure_reason=FileIOFailureReason.PERMISSION_DENIED, result_details=msg)
+        except IsADirectoryError:
+            msg = f"Path is a directory, not a file: {file_path}"
+            logger.error(msg)
+            return ReadFileResultFailure(failure_reason=FileIOFailureReason.IS_DIRECTORY, result_details=msg)
+        except UnicodeDecodeError as e:
+            msg = f"Encoding error for file {file_path}: {e}"
+            logger.error(msg)
+            return ReadFileResultFailure(failure_reason=FileIOFailureReason.ENCODING_ERROR, result_details=msg)
+        except OSError as e:
+            msg = f"I/O error for file {file_path}: {e}"
             logger.error(msg)
-            return ReadFileResultFailure(result_details=msg)
+            return ReadFileResultFailure(failure_reason=FileIOFailureReason.IO_ERROR, result_details=msg)
         except Exception as e:
-            # Try to include file path in error message if available
-            path_info = ""
-            if file_path is not None:
-                path_info = f" for {file_path}"
-            elif file_path_str is not None:
-                path_info = f" for {file_path_str}"
-
-            msg = f"Unexpected error in read_file{path_info}: {type(e).__name__}: {e}"
+            msg = f"Unexpected error reading file {file_path}: {type(e).__name__}: {e}"
             logger.error(msg)
-            return ReadFileResultFailure(result_details=msg)
+            return ReadFileResultFailure(failure_reason=FileIOFailureReason.UNKNOWN, result_details=msg)
+
+        # SUCCESS PATH - Only reached if no exceptions occurred
+        return ReadFileResultSuccess(
+            content=result.content,
+            file_size=result.file_size,
+            mime_type=result.mime_type,
+            encoding=result.encoding,
+            compression_encoding=result.compression_encoding,
+            result_details="File read successfully.",
+        )
 
-    def _read_file_content(
-        self, file_path: Path, request: ReadFileRequest
-    ) -> tuple[bytes | str, str | None, str, str | None, int]:
-        """Read file content and return content, encoding, mime_type, compression_encoding, and file_size."""
+    def _read_file_content(self, file_path: Path, request: ReadFileRequest) -> FileContentResult:
+        """Read file content and return FileContentResult with all file information."""
         # Get file size
         file_size = file_path.stat().st_size
 
         # Determine MIME type and compression encoding
-        mime_type, compression_encoding = mimetypes.guess_type(str(file_path), strict=True)
+        normalized_path = self._normalize_path_for_platform(file_path)
+        mime_type, compression_encoding = mimetypes.guess_type(normalized_path, strict=True)
         if mime_type is None:
             mime_type = "text/plain"
 
         # Determine if file is binary
         try:
-            is_binary_file = is_binary(str(file_path))
+            is_binary_file = is_binary(normalized_path)
         except Exception as e:
             msg = f"binaryornot detection failed for {file_path}: {e}"
             logger.warning(msg)
@@ -497,7 +574,13 @@ class OSManager:
         else:
             content, encoding = self._read_binary_file(file_path, mime_type)
 
-        return content, encoding, mime_type, compression_encoding, file_size
+        return FileContentResult(
+            content=content,
+            encoding=encoding,
+            mime_type=mime_type,
+            compression_encoding=compression_encoding,
+            file_size=file_size,
+        )
 
     def _read_text_file(self, file_path: Path, requested_encoding: str) -> tuple[bytes | str, str | None]:
         """Read file as text with fallback encodings."""
@@ -560,6 +643,148 @@ class OSManager:
         else:
             return static_url
 
+    def on_write_file_request(self, request: WriteFileRequest) -> ResultPayload:  # noqa: PLR0911, PLR0912, PLR0915, C901
+        """Handle a request to write content to a file."""
+        # Check for CREATE_NEW policy - not yet implemented
+        if request.existing_file_policy == ExistingFilePolicy.CREATE_NEW:
+            msg = "CREATE_NEW policy not yet implemented"
+            logger.error(msg)
+            return WriteFileResultFailure(
+                failure_reason=FileIOFailureReason.IO_ERROR,
+                result_details=msg,
+            )
+
+        # Resolve file path
+        try:
+            file_path = self._resolve_file_path(request.file_path, workspace_only=False)
+        except (ValueError, RuntimeError) as e:
+            msg = f"Invalid path: {e}"
+            logger.error(msg)
+            return WriteFileResultFailure(failure_reason=FileIOFailureReason.INVALID_PATH, result_details=msg)
+
+        # Get normalized path for file operations (handles Windows long paths)
+        normalized_path = self._normalize_path_for_platform(file_path)
+
+        # Check if path is a directory (must check before attempting to write)
+        try:
+            if Path(normalized_path).is_dir():
+                msg = f"Path is a directory, not a file: {file_path}"
+                logger.error(msg)
+                return WriteFileResultFailure(failure_reason=FileIOFailureReason.IS_DIRECTORY, result_details=msg)
+        except OSError as e:
+            msg = f"Error checking if path is directory {file_path}: {e}"
+            logger.error(msg)
+            return WriteFileResultFailure(failure_reason=FileIOFailureReason.IO_ERROR, result_details=msg)
+
+        # Check existing file policy (only if not appending)
+        if not request.append and request.existing_file_policy == ExistingFilePolicy.FAIL:
+            try:
+                # Use os.path.exists with normalized path to handle Windows long paths
+                if os.path.exists(normalized_path):  # noqa: PTH110
+                    msg = f"File exists and existing_file_policy is FAIL: {file_path}"
+                    logger.error(msg)
+                    return WriteFileResultFailure(
+                        failure_reason=FileIOFailureReason.POLICY_NO_OVERWRITE,
+                        result_details=msg,
+                    )
+            except OSError as e:
+                msg = f"Error checking if file exists {file_path}: {e}"
+                logger.error(msg)
+                return WriteFileResultFailure(failure_reason=FileIOFailureReason.IO_ERROR, result_details=msg)
+
+        # Check and create parent directory if needed
+        parent_normalized = self._normalize_path_for_platform(file_path.parent)
+        try:
+            if not os.path.exists(parent_normalized):  # noqa: PTH110
+                if not request.create_parents:
+                    msg = f"Parent directory does not exist and create_parents is False: {file_path.parent}"
+                    logger.error(msg)
+                    return WriteFileResultFailure(
+                        failure_reason=FileIOFailureReason.POLICY_NO_CREATE_PARENT_DIRS,
+                        result_details=msg,
+                    )
+
+                # Create parent directories using os.makedirs to handle Windows long paths
+                os.makedirs(parent_normalized, exist_ok=True)  # noqa: PTH103
+        except PermissionError as e:
+            msg = f"Permission denied creating parent directory {file_path.parent}: {e}"
+            logger.error(msg)
+            return WriteFileResultFailure(
+                failure_reason=FileIOFailureReason.PERMISSION_DENIED,
+                result_details=msg,
+            )
+        except OSError as e:
+            msg = f"Error creating parent directory {file_path.parent}: {e}"
+            logger.error(msg)
+            return WriteFileResultFailure(failure_reason=FileIOFailureReason.IO_ERROR, result_details=msg)
+
+        # Write file content
+        try:
+            bytes_written = self._write_file_content(
+                normalized_path, request.content, request.encoding, append=request.append
+            )
+        except PermissionError as e:
+            msg = f"Permission denied writing to file {file_path}: {e}"
+            logger.error(msg)
+            return WriteFileResultFailure(failure_reason=FileIOFailureReason.PERMISSION_DENIED, result_details=msg)
+        except IsADirectoryError:
+            msg = f"Path is a directory, not a file: {file_path}"
+            logger.error(msg)
+            return WriteFileResultFailure(failure_reason=FileIOFailureReason.IS_DIRECTORY, result_details=msg)
+        except UnicodeEncodeError as e:
+            msg = f"Encoding error writing to file {file_path}: {e}"
+            logger.error(msg)
+            return WriteFileResultFailure(failure_reason=FileIOFailureReason.ENCODING_ERROR, result_details=msg)
+        except OSError as e:
+            # Check for disk full
+            if "No space left" in str(e) or "Disk full" in str(e):
+                msg = f"Disk full writing to file {file_path}: {e}"
+                logger.error(msg)
+                return WriteFileResultFailure(failure_reason=FileIOFailureReason.DISK_FULL, result_details=msg)
+
+            msg = f"I/O error writing to file {file_path}: {e}"
+            logger.error(msg)
+            return WriteFileResultFailure(failure_reason=FileIOFailureReason.IO_ERROR, result_details=msg)
+        except Exception as e:
+            msg = f"Unexpected error writing to file {file_path}: {type(e).__name__}: {e}"
+            logger.error(msg)
+            return WriteFileResultFailure(failure_reason=FileIOFailureReason.UNKNOWN, result_details=msg)
+
+        # SUCCESS PATH - Only reached if no exceptions occurred
+        return WriteFileResultSuccess(
+            final_file_path=str(file_path),
+            bytes_written=bytes_written,
+            result_details=f"File written successfully: {file_path}",
+        )
+
+    def _write_file_content(self, normalized_path: str, content: str | bytes, encoding: str, *, append: bool) -> int:
+        """Write content to a file and return bytes written.
+
+        Args:
+            normalized_path: Normalized path string (with Windows long path prefix if needed)
+            content: Content to write (str for text, bytes for binary)
+            encoding: Text encoding (ignored for bytes)
+            append: If True, append to file; if False, overwrite
+
+        Returns:
+            Number of bytes written
+        """
+        # Determine mode based on content type and append flag
+        if isinstance(content, bytes):
+            mode = "ab" if append else "wb"
+            # Use open() instead of Path.open() to support Windows long paths with \\?\ prefix
+            with open(normalized_path, mode) as f:  # noqa: PTH123
+                f.write(content)
+            return len(content)
+
+        # Text content
+        mode = "a" if append else "w"
+        # Use open() instead of Path.open() to support Windows long paths with \\?\ prefix
+        with open(normalized_path, mode, encoding=encoding) as f:  # noqa: PTH123
+            f.write(content)
+        # Return byte count for text (encoded size)
+        return len(content.encode(encoding))
+
     @staticmethod
     def get_disk_space_info(path: Path) -> DiskSpaceInfo:
         """Get disk space information for a given path.
@@ -754,37 +979,52 @@ class OSManager:
 
         return removed_count > 0
 
-    def on_create_file_request(self, request: CreateFileRequest) -> ResultPayload:
+    def on_create_file_request(self, request: CreateFileRequest) -> ResultPayload:  # noqa: PLR0911, PLR0912, C901
         """Handle a request to create a file or directory."""
+        # Get the full path
         try:
-            # Get the full path using the new method
             full_path_str = request.get_full_path()
+        except ValueError as e:
+            msg = f"Invalid path specification: {e}"
+            logger.error(msg)
+            return CreateFileResultFailure(failure_reason=FileIOFailureReason.INVALID_PATH, result_details=msg)
 
-            # Determine if path is absolute (not constrained to workspace)
-            is_absolute = Path(full_path_str).is_absolute()
+        # Determine if path is absolute (not constrained to workspace)
+        is_absolute = Path(full_path_str).is_absolute()
 
-            # If workspace_only is True and path is absolute, it's outside workspace
-            if request.workspace_only and is_absolute:
-                msg = f"Absolute path is outside workspace: {full_path_str}"
-                logger.error(msg)
-                return CreateFileResultFailure(result_details=msg)
+        # If workspace_only is True and path is absolute, it's outside workspace
+        if request.workspace_only and is_absolute:
+            msg = f"Absolute path is outside workspace: {full_path_str}"
+            logger.error(msg)
+            return CreateFileResultFailure(failure_reason=FileIOFailureReason.INVALID_PATH, result_details=msg)
 
-            # Resolve path - if absolute, use as-is; if relative, align to workspace
-            if is_absolute:
-                file_path = Path(full_path_str).resolve()
-            else:
-                file_path = (self._get_workspace_path() / full_path_str).resolve()
+        # Resolve path - if absolute, use as-is; if relative, align to workspace
+        if is_absolute:
+            file_path = Path(full_path_str).resolve()
+        else:
+            file_path = (self._get_workspace_path() / full_path_str).resolve()
 
-            # Check if it already exists - warn but treat as success
-            if file_path.exists():
-                msg = f"Path already exists: {file_path}"
-                return CreateFileResultSuccess(
-                    created_path=str(file_path), result_details=ResultDetails(message=msg, level=logging.WARNING)
-                )
+        # Check if it already exists - warn but treat as success
+        if file_path.exists():
+            msg = f"Path already exists: {file_path}"
+            return CreateFileResultSuccess(
+                created_path=str(file_path), result_details=ResultDetails(message=msg, level=logging.WARNING)
+            )
 
-            # Create parent directories if needed
+        # Create parent directories if needed
+        try:
             file_path.parent.mkdir(parents=True, exist_ok=True)
+        except PermissionError as e:
+            msg = f"Permission denied creating parent directory for {file_path}: {e}"
+            logger.error(msg)
+            return CreateFileResultFailure(failure_reason=FileIOFailureReason.PERMISSION_DENIED, result_details=msg)
+        except OSError as e:
+            msg = f"I/O error creating parent directory for {file_path}: {e}"
+            logger.error(msg)
+            return CreateFileResultFailure(failure_reason=FileIOFailureReason.IO_ERROR, result_details=msg)
 
+        # Create file or directory
+        try:
             if request.is_directory:
                 file_path.mkdir()
                 logger.info("Created directory: %s", file_path)
@@ -796,65 +1036,104 @@ class OSManager:
             else:
                 file_path.touch()
                 logger.info("Created empty file: %s", file_path)
+        except PermissionError as e:
+            msg = f"Permission denied creating {file_path}: {e}"
+            logger.error(msg)
+            return CreateFileResultFailure(failure_reason=FileIOFailureReason.PERMISSION_DENIED, result_details=msg)
+        except OSError as e:
+            # Check for disk full
+            if "No space left" in str(e) or "Disk full" in str(e):
+                msg = f"Disk full creating {file_path}: {e}"
+                logger.error(msg)
+                return CreateFileResultFailure(failure_reason=FileIOFailureReason.DISK_FULL, result_details=msg)
 
-            return CreateFileResultSuccess(
-                created_path=str(file_path),
-                result_details=f"{'Directory' if request.is_directory else 'File'} created successfully at {file_path}",
-            )
-
+            msg = f"I/O error creating {file_path}: {e}"
+            logger.error(msg)
+            return CreateFileResultFailure(failure_reason=FileIOFailureReason.IO_ERROR, result_details=msg)
         except Exception as e:
-            path_info = request.get_full_path() if hasattr(request, "get_full_path") else str(request.path)
-            msg = f"Failed to create {'directory' if request.is_directory else 'file'} at {path_info}: {e}"
+            msg = f"Unexpected error creating {file_path}: {type(e).__name__}: {e}"
             logger.error(msg)
-            return CreateFileResultFailure(result_details=msg)
+            return CreateFileResultFailure(failure_reason=FileIOFailureReason.UNKNOWN, result_details=msg)
 
-    def on_rename_file_request(self, request: RenameFileRequest) -> ResultPayload:
+        # SUCCESS PATH
+        return CreateFileResultSuccess(
+            created_path=str(file_path),
+            result_details=f"{'Directory' if request.is_directory else 'File'} created successfully at {file_path}",
+        )
+
+    def on_rename_file_request(self, request: RenameFileRequest) -> ResultPayload:  # noqa: PLR0911, C901
         """Handle a request to rename a file or directory."""
+        # Resolve and validate paths
         try:
-            # Resolve and validate old path
             old_path = self._resolve_file_path(request.old_path, workspace_only=request.workspace_only is True)
+        except (ValueError, RuntimeError) as e:
+            msg = f"Invalid source path: {e}"
+            logger.error(msg)
+            return RenameFileResultFailure(failure_reason=FileIOFailureReason.INVALID_PATH, result_details=msg)
 
-            # Resolve and validate new path
+        try:
             new_path = self._resolve_file_path(request.new_path, workspace_only=request.workspace_only is True)
+        except (ValueError, RuntimeError) as e:
+            msg = f"Invalid destination path: {e}"
+            logger.error(msg)
+            return RenameFileResultFailure(failure_reason=FileIOFailureReason.INVALID_PATH, result_details=msg)
 
-            # Check if old path exists
-            if not old_path.exists():
-                msg = f"Source path does not exist: {old_path}"
-                logger.error(msg)
-                return RenameFileResultFailure(result_details=msg)
+        # Check if old path exists
+        if not old_path.exists():
+            msg = f"Source path does not exist: {old_path}"
+            logger.error(msg)
+            return RenameFileResultFailure(failure_reason=FileIOFailureReason.FILE_NOT_FOUND, result_details=msg)
 
-            # Check if new path already exists
-            if new_path.exists():
-                msg = f"Destination path already exists: {new_path}"
-                logger.error(msg)
-                return RenameFileResultFailure(result_details=msg)
+        # Check if new path already exists
+        if new_path.exists():
+            msg = f"Destination path already exists: {new_path}"
+            logger.error(msg)
+            return RenameFileResultFailure(failure_reason=FileIOFailureReason.INVALID_PATH, result_details=msg)
 
-            # Check workspace constraints for both paths
-            is_old_in_workspace, _ = self._validate_workspace_path(old_path)
-            is_new_in_workspace, _ = self._validate_workspace_path(new_path)
+        # Check workspace constraints for both paths
+        is_old_in_workspace, _ = self._validate_workspace_path(old_path)
+        is_new_in_workspace, _ = self._validate_workspace_path(new_path)
 
-            if request.workspace_only and (not is_old_in_workspace or not is_new_in_workspace):
-                msg = f"One or both paths are outside workspace: {old_path} -> {new_path}"
-                logger.error(msg)
-                return RenameFileResultFailure(result_details=msg)
+        if request.workspace_only and (not is_old_in_workspace or not is_new_in_workspace):
+            msg = f"One or both paths are outside workspace: {old_path} -> {new_path}"
+            logger.error(msg)
+            return RenameFileResultFailure(failure_reason=FileIOFailureReason.INVALID_PATH, result_details=msg)
 
-            # Create parent directories for new path if needed
+        # Create parent directories for new path if needed
+        try:
             new_path.parent.mkdir(parents=True, exist_ok=True)
+        except PermissionError as e:
+            msg = f"Permission denied creating parent directory for {new_path}: {e}"
+            logger.error(msg)
+            return RenameFileResultFailure(failure_reason=FileIOFailureReason.PERMISSION_DENIED, result_details=msg)
+        except OSError as e:
+            msg = f"I/O error creating parent directory for {new_path}: {e}"
+            logger.error(msg)
+            return RenameFileResultFailure(failure_reason=FileIOFailureReason.IO_ERROR, result_details=msg)
 
-            # Perform the rename operation
+        # Perform the rename operation
+        try:
             old_path.rename(new_path)
-            details = f"Renamed: {old_path} -> {new_path}"
-
-            return RenameFileResultSuccess(
-                old_path=str(old_path),
-                new_path=str(new_path),
-                result_details=ResultDetails(message=details, level=logging.INFO),
-            )
-
+        except PermissionError as e:
+            msg = f"Permission denied renaming {old_path} to {new_path}: {e}"
+            logger.error(msg)
+            return RenameFileResultFailure(failure_reason=FileIOFailureReason.PERMISSION_DENIED, result_details=msg)
+        except OSError as e:
+            msg = f"I/O error renaming {old_path} to {new_path}: {e}"
+            logger.error(msg)
+            return RenameFileResultFailure(failure_reason=FileIOFailureReason.IO_ERROR, result_details=msg)
         except Exception as e:
-            msg = f"Failed to rename {request.old_path} to {request.new_path}: {e}"
+            msg = f"Unexpected error renaming {old_path} to {new_path}: {type(e).__name__}: {e}"
             logger.error(msg)
-            return RenameFileResultFailure(result_details=msg)
+            return RenameFileResultFailure(failure_reason=FileIOFailureReason.UNKNOWN, result_details=msg)
+
+        # SUCCESS PATH
+        details = f"Renamed: {old_path} -> {new_path}"
+        return RenameFileResultSuccess(
+            old_path=str(old_path),
+            new_path=str(new_path),
+            result_details=ResultDetails(message=details, level=logging.INFO),
+        )
 
     def on_app_initialization_complete(self, _payload: AppInitializationComplete) -> None:
         """Handle app initialization complete event by registering system resources."""