Skip to content

Self-improving AI Employees for everyone

fix(filesystem): surface path-sandbox violations as user-correctable errors

trohitg4aa499fad94a
diff --git a/server/nodes/filesystem/_backend.py b/server/nodes/filesystem/_backend.py
index 94261dae..5a0d0d5f 100644
--- a/server/nodes/filesystem/_backend.py
+++ b/server/nodes/filesystem/_backend.py
@@ -41,7 +41,14 @@ def normalize_virtual_path(path: str) -> str:
drives, UNC, and POSIX absolutes uniformly on any host OS. Strip
the anchor here, then delegate to :func:`validate_path` for traversal
rejection (``..``, ``~``) and canonical normalisation.
+
+ A rejected path is an LLM/user-correctable input error, not a server
+ bug — it surfaces as :class:`NodeUserError` (single WARN line, no
+ traceback) with guidance the LLM can act on, instead of leaking
+ deepagents' bare ``ValueError`` through the generic-exception path.
"""
+ from services.plugin import NodeUserError
+
if not path:
return path
pw = PureWindowsPath(path)
@@ -49,7 +56,15 @@ def normalize_virtual_path(path: str) -> str:
rel = "/" + "/".join(pw.parts[1:]) if len(pw.parts) > 1 else "/"
else:
rel = path.replace("\\", "/")
- return validate_path(rel)
+ try:
+ return validate_path(rel)
+ except ValueError as e:
+ raise NodeUserError(
+ f"{e}. The filesystem is sandboxed to the per-workflow workspace "
+ "root — use a path relative to the workspace (e.g. "
+ "'reports/data.csv'); '..' and '~' segments are rejected. To see "
+ "what exists, use fs_search with mode='ls'."
+ ) from e
def _find_nu() -> Optional[str]:
diff --git a/server/nodes/filesystem/file_modify/__init__.py b/server/nodes/filesystem/file_modify/__init__.py
index 0d9e7972..0d745eca 100644
--- a/server/nodes/filesystem/file_modify/__init__.py
+++ b/server/nodes/filesystem/file_modify/__init__.py
@@ -39,7 +39,10 @@ class FileModifyNode(ActionNode):
description = "Write new files or edit existing files"
tool_name = "file_modify"
tool_description = (
- "Write a new file or edit an existing file with string replacement. Operations: write (create/overwrite), edit (find and replace)."
+ "Write a new file or edit an existing file with string replacement. "
+ "Operations: write (create/overwrite), edit (find and replace). "
+ "Paths resolve inside the per-workflow workspace — use "
+ "workspace-relative paths; '..' is not allowed."
)
component_kind = "square"
handles = (
diff --git a/server/nodes/filesystem/file_read/__init__.py b/server/nodes/filesystem/file_read/__init__.py
index c8e58e09..1f116fe7 100644
--- a/server/nodes/filesystem/file_read/__init__.py
+++ b/server/nodes/filesystem/file_read/__init__.py
@@ -31,7 +31,12 @@ class FileReadNode(ActionNode):
group = ("filesystem", "tool")
description = "Read file contents with line numbers and pagination"
tool_name = "file_read"
- tool_description = "Read file contents with pagination. Returns line-numbered text."
+ tool_description = (
+ "Read file contents with pagination. Returns line-numbered text. "
+ "Paths resolve inside the per-workflow workspace — use "
+ "workspace-relative paths (e.g. 'reports/data.csv'); '..' is not "
+ "allowed."
+ )
component_kind = "square"
handles = (
{"name": "input-main", "kind": "input", "position": "left", "label": "Input", "role": "main"},
diff --git a/server/nodes/filesystem/fs_search/__init__.py b/server/nodes/filesystem/fs_search/__init__.py
index 5366bfdc..8bf9060c 100644
--- a/server/nodes/filesystem/fs_search/__init__.py
+++ b/server/nodes/filesystem/fs_search/__init__.py
@@ -32,7 +32,10 @@ class FsSearchNode(ActionNode):
description = "Search the filesystem (ls, glob, grep)"
tool_name = "fs_search"
tool_description = (
- "Search the filesystem. Modes: ls (list directory), glob (pattern match files), grep (search file contents for text)."
+ "Search the filesystem. Modes: ls (list directory), glob (pattern "
+ "match files), grep (search file contents for text). Paths resolve "
+ "inside the per-workflow workspace — use workspace-relative paths; "
+ "'..' is not allowed."
)
component_kind = "square"
handles = (
diff --git a/server/skills/coding_agent/file-modify-skill/SKILL.md b/server/skills/coding_agent/file-modify-skill/SKILL.md
index 01a3ba84..2be0a163 100644
--- a/server/skills/coding_agent/file-modify-skill/SKILL.md
+++ b/server/skills/coding_agent/file-modify-skill/SKILL.md
@@ -13,6 +13,8 @@ metadata:
Write new files or edit existing files with exact string replacement. Uses deepagents filesystem backend.
+**Path sandbox:** all paths resolve inside the per-workflow workspace root. Use workspace-relative paths (e.g. `reports/summary.md`); `..` and `~` segments are rejected, and absolute paths are remapped into the workspace.
+
## file_modify Tool
### Schema Fields
diff --git a/server/skills/coding_agent/file-read-skill/SKILL.md b/server/skills/coding_agent/file-read-skill/SKILL.md
index 4bff964f..f067c235 100644
--- a/server/skills/coding_agent/file-read-skill/SKILL.md
+++ b/server/skills/coding_agent/file-read-skill/SKILL.md
@@ -13,6 +13,8 @@ metadata:
Read file contents with line-numbered output and pagination. Uses deepagents filesystem backend.
+**Path sandbox:** all paths resolve inside the per-workflow workspace root. Use workspace-relative paths (e.g. `reports/data.csv`); `..` and `~` segments are rejected, and absolute paths are remapped into the workspace. Use `fs_search` with `mode: "ls"` to discover what exists.
+
## file_read Tool
### Schema Fields
diff --git a/server/skills/coding_agent/fs-search-skill/SKILL.md b/server/skills/coding_agent/fs-search-skill/SKILL.md
index 52f65782..2e5849fb 100644
--- a/server/skills/coding_agent/fs-search-skill/SKILL.md
+++ b/server/skills/coding_agent/fs-search-skill/SKILL.md
@@ -13,6 +13,8 @@ metadata:
Search the filesystem: list directories, glob pattern match files, or grep file contents. Uses deepagents filesystem backend.
+**Path sandbox:** all paths resolve inside the per-workflow workspace root. Use workspace-relative paths; `..` and `~` segments are rejected, and absolute paths are remapped into the workspace.
+
## fs_search Tool
### Schema Fields
diff --git a/server/tests/nodes/test_code_fs_process.py b/server/tests/nodes/test_code_fs_process.py
index f21126a6..900e4343 100644
--- a/server/tests/nodes/test_code_fs_process.py
+++ b/server/tests/nodes/test_code_fs_process.py
@@ -349,6 +349,31 @@ class TestFileRead:
# backend is even called, so the error comes from deepagents'
# ``validate_path`` helper, not the (unreached) FileNotFoundError.
assert "path traversal not allowed" in result["error"].lower()
+ # LLM-correctable input error: NodeUserError path (single WARN,
+ # no traceback) carrying actionable sandbox guidance — not the
+ # generic-exception path that leaks deepagents' bare ValueError.
+ assert result.get("error_type") == "NodeUserError"
+ assert "workspace" in result["error"].lower()
+
+ def test_normalize_virtual_path_traversal_raises_user_error(self):
+ """Central contract on the shared helper — all three filesystem
+ plugins (fileRead / fileModify / fsSearch) call it outside their
+ operation try-blocks, so the conversion to NodeUserError must
+ happen inside the helper itself."""
+ import pytest
+
+ from nodes.filesystem._backend import normalize_virtual_path
+ from services.plugin import NodeUserError
+
+ with pytest.raises(NodeUserError) as excinfo:
+ normalize_virtual_path("../../package.json")
+ msg = str(excinfo.value).lower()
+ assert "path traversal not allowed" in msg
+ assert "workspace" in msg
+
+ # Valid flavours still normalise (no raise).
+ assert normalize_virtual_path("reports/data.csv") == "/reports/data.csv"
+ assert normalize_virtual_path("C:\\tmp\\x.txt") == "/tmp/x.txt"
# ============================================================================