fix: normalize path separators in FilesystemBackend for cross-platform(OS:Window) compatibility

[Yo-sure]

PR Description

Problem

On Windows, FilesystemBackend returns paths with mixed separators (e.g., /\.circleci/) causing display issues in agent tools.

[AS-IS]

[TO-BE]

Why This Matters

DeepAgents provides essential filesystem capabilities for LangGraph-based agents, and cross-platform reliability is crucial for production deployments. Mixed path separators like /\ can negatively impact agent performance in two ways:

1. User Experience: Inconsistent path displays reduce trust and usability, especially on Windows systems
2. LLM Interpretation: Language models rely on clean, consistent path formats to make accurate decisions about file operations

This fix ensures POSIX-style paths across all platforms, improving both the developer experience and agent reliability.

Root Cause

There were two related but distinct issues affecting different modes:

Issue 1: virtual_mode=True - Logic Bug (Functional Failure)

String slicing logic in ls_info() and glob_info() used raw string concatenation to construct virtual paths:

# Problematic code
cwd_str = str(self.cwd)  # "C:\workspace"
if not cwd_str.endswith("/"):
    cwd_str += "/"  # "C:\workspace/" (mixed separators!)

abs_path = str(child_path)  # "C:\workspace\file.txt"
relative_path = abs_path[len(cwd_str):]  # Slicing fails - length mismatch!
virt_path = "/" + relative_path  # Result: "/\file.txt"

The string slicing failed because:

1. cwd_str used backslashes: C:\workspace
2. Adding / created mixed separators: C:\workspace/
3. abs_path used different separators: C:\workspace\file.txt
4. Length calculation was incorrect, producing: /\.circleci/

Issue 2: virtual_mode=False - Display Bug (UX Issue)

In non-virtual mode, paths were functionally correct but displayed with Windows backslashes:

abs_path = str(child_path)  # "C:\workspace\file.txt"
results.append({"path": abs_path, ...})  # Backslashes in output

This was purely a display inconsistency - functionality was correct, but output didn't match POSIX conventions.

Solution

For virtual_mode=True (Logic Fix):

Replace fragile string slicing with robust pathlib operations:

# Fixed code
try:
    # Use pathlib for robust cross-platform path handling
    relative_path = Path(abs_path).resolve().relative_to(self.cwd).as_posix()
except ValueError:
    # Path is outside cwd - normalize to POSIX for error reporting
    relative_path = abs_path.replace("\\", "/")

# Ensure virtual path starts with /
virt_path = "/" + relative_path if not relative_path.startswith("/") else relative_path

Key improvements:

• Path.relative_to() correctly handles path differences
• .as_posix() ensures forward slashes on all platforms
• Security boundary (paths outside cwd) preserved for _resolve_path() validation

For virtual_mode=False (Display Fix):

Simple normalization for consistent output:

# Normalize path separators for cross-platform compatibility
normalized_path = abs_path.replace("\\", "/")
results.append({"path": normalized_path, ...})

Test Updates:

Updated test assertions to use platform-independent comparison:

# Before: assert str(f1) in paths
# After: assert str(f1).replace("\\", "/") in paths

Testing

• ✅ All 6 backend unit tests pass on Windows 10
• ✅ All 6 backend unit tests pass on Linux (WSL 2 Ubuntu 22.04)
• ✅ Cross-platform compatibility verified: pathlib.Path.as_posix() works consistently across platforms
• ✅ Security: Paths outside cwd are properly caught by _resolve_path() validation
• ✅ Verified in production with langgraph dev on both Windows and WSL environments

Test Results:

Changes

• libs/deepagents/deepagents/backends/filesystem.py: Updated ls_info() and glob_info() methods to use pathlib for path normalization
• libs/deepagents/tests/unit_tests/backends/test_filesystem_backend.py: Updated test assertions for platform-independent path comparison

Relationship to Issue #427

This PR and Issue #427 address complementary Windows path handling problems in different layers:

This PR (Backend Layer - Output):

• Scope: FilesystemBackend.ls_info() / glob_info() - path output formatting
• Problem: Mixed separators (/\) in displayed paths
• Impact: Display issues, UX degradation, potential LLM confusion
• Solution: Normalize output to POSIX format

PR #454 / Issue #427 (Middleware Layer - Input):

• Scope: _validate_path() - user input validation
• Problem: Windows absolute paths (F:\git\...) → invalid paths (/F:/git/...) → silent corruption
• Impact: Files saved to wrong locations without error
• Solution: Reject Windows absolute paths with clear error message
• Link: fix(middleware): prevent silent corruption from Windows absolute paths (Issue #427) #454

Both fixes are necessary for robust Windows support:

1. This PR (fix: normalize path separators in FilesystemBackend for cross-platform(OS:Window) compatibility #452) ensures clean path display (output normalization)
2. PR fix(middleware): prevent silent corruption from Windows absolute paths (Issue #427) #454 prevents corrupt path input (input validation)

Together, they provide end-to-end Windows path handling in DeepAgents' filesystem layer.