fix(sandbox): resolve paths in read_file/write_file content for LocalSandbox

[JasonOA888]

Fixes #1778

Problem

In LocalSandbox mode, read_file and write_file do not transform container paths in file content. This causes issues when:

1. Agent writes a Python script with /mnt/user-data/... paths
2. Agent executes the script via bash tool
3. Script fails because the paths are virtual, not real system paths

The bash tool already resolves paths in commands and reverse-resolves in output, but file tools do not.

Solution

• write_file: resolve virtual paths in content to system paths before writing
• read_file: reverse-resolve system paths back to virtual paths in returned content

This makes path handling consistent across all LocalSandbox tools.

Example

Before:

# Agent writes file with virtual path
write_file("/mnt/user-data/workspace/test.py", "open("/mnt/user-data/outputs/out.txt")")
# bash executes: python /mnt/user-data/workspace/test.py
# → FAILS: /mnt/user-data/outputs does not exist

After:

# write_file converts content paths to system paths
write_file("/mnt/user-data/workspace/test.py", "open("/mnt/user-data/outputs/out.txt")")
# File now contains real path, e.g. "/home/user/deer-flow/user-data/outputs/out.txt"
# bash executes: python /mnt/user-data/workspace/test.py
# → WORKS: output path resolves correctly

Notes

• Same transformation logic as execute_command uses
• read_file reverses the transformation so agents see consistent virtual paths
• No change to non-LocalSandbox modes

[Copilot]

Pull request overview

This PR fixes inconsistent path handling in LocalSandbox by making read_file/write_file transform virtual container paths inside file contents, aligning their behavior with execute_command’s path resolution so scripts written with /mnt/user-data/... paths can run correctly on the host.

Changes:

• write_file: resolves container-path strings inside content to host-local paths before writing.
• read_file: reverse-resolves host-local paths back to container paths in returned file content.

[Copilot]

On Windows hosts, self._resolve_path() will typically return paths with backslashes (because LocalSandboxProvider stores local_path as Path(...).resolve()), so resolved_content can inject sequences like C:\Users\... into source files. In common cases (e.g. Python scripts), those backslashes inside string literals can create invalid escape sequences (e.g. \U...) and break execution. Consider normalizing resolved paths inserted into file content to a safer representation (e.g. forward slashes) and ensure read_file’s reverse-resolver also recognizes that normalized form so agents don’t see leaked host paths.

[Copilot]

_resolve_paths_in_command() is documented and tuned for shell command parsing (boundary chars, quoting, etc.), but it’s now being reused to transform arbitrary file contents. That coupling is easy to miss and makes future tweaks to command parsing potentially break file IO semantics. Consider extracting a dedicated helper for “resolve paths in text content” (or renaming/generalizing the helper) so the intent and constraints are explicit.

[Copilot]

This change alters core LocalSandbox behavior by rewriting paths inside written file content and rewriting them back when reading. There are existing unit tests for path mapping / command replacement in test_local_sandbox_provider_mounts.py, but nothing asserting the new read/write content transformations. Adding focused tests for write_file (content path resolution) and read_file (reverse resolution) would help prevent regressions, especially across different mount mappings.

[WillemJiang]

@JasonOA888 thanks for the contribution. Please take some time to address the Copilot review comments.

[JasonOA888]

@WillemJiang Thanks for the nudge! I have addressed all three Copilot review points in commit 19c3f0d:

1. Extracted _resolve_paths_in_content() — separate from _resolve_paths_in_command() to decouple file-content resolution from shell-command parsing.
2. Forward-slash normalization — resolved paths in content always use / to avoid Windows backslash escape issues (e.g. \U in Python string literals).
3. Added 4 focused tests — write resolves content, forward-slash guarantee, read reverse-resolves, and write→read roundtrip consistency.

Please take another look when you get a chance.

[WillemJiang]

@JasonOA888, please run the following command to fix the lint error.

cd backend
make format

[WillemJiang]

@JasonOA888
read_file reverse-resolves ALL file content, not just agent-written files (significant)

read_file now unconditionally applies _reverse_resolve_paths_in_output to everything it reads. This means:

• User-uploaded files containing paths that happen to match a local_path mapping will be silently rewritten
• Files generated by external tools (formatters, linters, build systems) that emit real filesystem paths will have those paths replaced with virtual ones
• If someone reads /etc/fstab or a log file, any path matching a mapping gets rewritten

Example: A user uploads a config containing /Users/jiangning/.../user-data/outputs — if that local path maps to /mnt/user-data, read_file would corrupt it to /mnt/user-data/outputs.

This is different from bash output, which is ephemeral. File content is persistent and read for many reasons (searching, parsing, forwarding to users).

Suggestion: Consider only reverse-resolving in read_file if the file was previously written through write_file (e.g., track a set of "agent-written" paths). Or accept the risk and document it clearly.

[JasonOA888]

@WillemJiang Great catch. You're right — unconditionally reverse-resolving in read_file is too aggressive.

Pushed a fix (beb4e20) that addresses this:

1. _agent_written_paths set — write_file now tracks every path it writes to
2. Conditional reverse-resolve — read_file only applies _reverse_resolve_paths_in_output if the file was previously written through write_file
3. Non-agent files untouched — user uploads, external tool output, config files, logs — all returned as-is

Added a test that verifies: writing a file directly to the filesystem (simulating a user upload) with a local path → read_file returns content unchanged.

This preserves the roundtrip behavior for agent-authored content while protecting everything else from silent path corruption.