feat: enhance workspace backend and agent configuration

- Introduced new constants for skills and memories paths in `workspace_backend.py`.
- Updated `build_agent` to utilize these constants for backend configuration, ensuring proper mounting of skills and memories.
- Refactored path normalization functions to support new virtual paths for skills and memories.
- Enhanced tests to validate the integration of skills and memories in the agent's backend setup.
- Improved overall path handling to reject invalid host paths and ensure compliance with workspace rules.

Author: knqiufan

agent/app/agent.py

@@ -14,7 +14,11 @@
     SYSTEM_PROMPT,
     build_system_prompt,
 )
-from app.workspace_backend import make_workspace_backend_factory
+from app.workspace_backend import (
+    MEMORY_FILE,
+    SKILLS_PREFIX,
+    make_workspace_backend_factory,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -54,6 +58,7 @@ def build_agent(
         from deepagents import create_deep_agent
         from deepagents.backends import (
             CompositeBackend,
+            FilesystemBackend,
             LocalShellBackend,
             StateBackend,
         )
@@ -77,10 +82,18 @@ def build_agent(
         "store": store,
     }
 
-    kwargs["skills"] = [str(settings.skills_dir)]
-    kwargs["memory"] = [str(settings.memories_dir)]
+    # DeepAgents skills/memory paths are backend-virtual, not host absolute paths.
+    # Host dirs are mounted at /skills and /memories via CompositeBackend routes.
+    kwargs["skills"] = [f"{SKILLS_PREFIX}/"]
+    kwargs["memory"] = [MEMORY_FILE]
     kwargs["backend"] = make_workspace_backend_factory(
-        validated, LocalShellBackend, StateBackend, CompositeBackend
+        validated,
+        LocalShellBackend,
+        StateBackend,
+        CompositeBackend,
+        filesystem_cls=FilesystemBackend,
+        skills_dir=settings.skills_dir,
+        memories_dir=settings.memories_dir,
     )
 
     with _HARNESS_LOCK:

agent/app/workspace_backend.py

@@ -4,11 +4,17 @@
 
 import logging
 import re
+from pathlib import Path
 from typing import Any
 
 logger = logging.getLogger(__name__)
 
 WORKSPACE_PREFIX = "/workspace"
+SKILLS_PREFIX = "/skills"
+MEMORIES_PREFIX = "/memories"
+MEMORY_FILE = f"{MEMORIES_PREFIX}/AGENTS.md"
+
+_SYSTEM_PREFIXES = (SKILLS_PREFIX, MEMORIES_PREFIX)
 _DRIVE_IN_WORKSPACE = re.compile(r"^/workspace([A-Za-z]:)")
 _WINDOWS_ABS = re.compile(r"^[A-Za-z]:[\\/]")
 
@@ -23,21 +29,12 @@ def normalize_workspace_path(path: str | None) -> str:
 
     Rejects Windows absolute paths, ``/workspaceD:...`` concatenations, and ``..``.
     """
-    if path is None or not str(path).strip():
-        raise ValueError("Path is required; use /workspace/<relative-path>")
-
-    raw = str(path).strip().replace("\\", "/")
-    if _WINDOWS_ABS.match(raw) or raw.startswith("//"):
-        raise ValueError(
-            "Host absolute paths are not allowed. Use /workspace/<relative-path>."
-        )
+    raw = _normalize_slashes(path)
     if _DRIVE_IN_WORKSPACE.match(raw):
         raise ValueError(
             "Invalid path: do not concatenate /workspace with a Windows drive path "
             "(e.g. /workspaceD:\\...). Use /workspace/<relative-path>."
         )
-    if not raw.startswith("/"):
-        raw = f"/{raw}"
 
     if raw == "/workspace" or raw.startswith("/workspace/"):
         virtual = raw
@@ -46,12 +43,41 @@ def normalize_workspace_path(path: str | None) -> str:
     else:
         virtual = f"/workspace{raw}" if raw.startswith("/") else f"/workspace/{raw}"
 
+    return _finalize_virtual_path(virtual, required_root="workspace")
+
+
+def normalize_backend_path(path: str | None) -> str:
+    """Normalize paths for workspace tools and system mounts.
+
+    Allows ``/workspace``, ``/skills``, and ``/memories`` virtual trees.
+    Rejects host absolute paths and ``..`` traversal.
+    """
+    raw = _normalize_slashes(path)
+    for prefix in _SYSTEM_PREFIXES:
+        if raw == prefix or raw.startswith(f"{prefix}/"):
+            return _finalize_virtual_path(raw, required_root=prefix.lstrip("/"))
+    return normalize_workspace_path(path)
+
+
+def _normalize_slashes(path: str | None) -> str:
+    if path is None or not str(path).strip():
+        raise ValueError("Path is required; use /workspace/<relative-path>")
+    raw = str(path).strip().replace("\\", "/")
+    if _WINDOWS_ABS.match(raw) or raw.startswith("//"):
+        raise ValueError(
+            "Host absolute paths are not allowed. Use /workspace/<relative-path>."
+        )
+    if not raw.startswith("/"):
+        raw = f"/{raw}"
+    return raw
+
+
+def _finalize_virtual_path(virtual: str, *, required_root: str) -> str:
     parts = [p for p in virtual.split("/") if p]
     if ".." in parts:
         raise ValueError("Path traversal ('..') is not allowed.")
-    if not parts or parts[0] != "workspace":
+    if not parts or parts[0] != required_root:
         raise ValueError("Filesystem tools must use /workspace/<relative-path>.")
-
     return "/" + "/".join(parts)
 
 
@@ -98,7 +124,7 @@ def __getattr__(self, name: str) -> Any:
         return getattr(self._inner, name)
 
     def _guard(self, path: str | None) -> str:
-        return normalize_workspace_path(path)
+        return normalize_backend_path(path)
 
     def read(self, file_path: str, offset: int = 0, limit: int = 2000) -> Any:
         return coerce_read_result(
@@ -125,6 +151,9 @@ def edit(
     def ls(self, path: str = "/workspace") -> Any:
         return self._inner.ls(self._guard(path))
 
+    async def als(self, path: str = "/workspace") -> Any:
+        return await self._inner.als(self._guard(path))
+
     def glob(self, pattern: str, path: str = "/workspace") -> Any:
         return self._inner.glob(pattern, self._guard(path))
 
@@ -137,16 +166,53 @@ def grep(
         safe = self._guard(path) if path else "/workspace"
         return self._inner.grep(pattern, path=safe, glob=glob)
 
+    def download_files(self, paths: list[str]) -> Any:
+        return self._inner.download_files([self._guard(p) for p in paths])
+
+    async def adownload_files(self, paths: list[str]) -> Any:
+        return await self._inner.adownload_files([self._guard(p) for p in paths])
+
+
+def _mount_system_routes(
+    routes: dict[str, Any],
+    filesystem_cls: Any | None,
+    skills_dir: Path | None,
+    memories_dir: Path | None,
+) -> None:
+    if filesystem_cls is None:
+        return
+    if skills_dir is not None:
+        root = Path(skills_dir)
+        root.mkdir(parents=True, exist_ok=True)
+        routes[f"{SKILLS_PREFIX}/"] = filesystem_cls(
+            root_dir=str(root),
+            virtual_mode=True,
+        )
+    if memories_dir is not None:
+        root = Path(memories_dir)
+        root.mkdir(parents=True, exist_ok=True)
+        routes[f"{MEMORIES_PREFIX}/"] = filesystem_cls(
+            root_dir=str(root),
+            virtual_mode=True,
+        )
+
 
 def make_workspace_backend_factory(
     validated_root,
     local_shell_cls,
     state_cls,
     composite_cls,
+    *,
+    filesystem_cls=None,
+    skills_dir: Path | None = None,
+    memories_dir: Path | None = None,
 ):
-    """Bind project dir under /workspace with LocalShellBackend + CompositeBackend."""
+    """Bind project dir under /workspace; mount global skills/memories separately."""
 
     def factory(rt):
+        routes: dict[str, Any] = {}
+        _mount_system_routes(routes, filesystem_cls, skills_dir, memories_dir)
+
         if validated_root is not None:
             shell = local_shell_cls(
                 root_dir=str(validated_root),
@@ -155,21 +221,24 @@ def factory(rt):
             )
             # Route /workspace/* onto the same shell-backed root. default=shell
             # keeps execute() cwd at the project directory.
-            composite = composite_cls(
-                default=shell,
-                routes={f"{WORKSPACE_PREFIX}/": shell},
-            )
+            routes[f"{WORKSPACE_PREFIX}/"] = shell
+            composite = composite_cls(default=shell, routes=routes)
             return WorkspacePathBackend(composite)
-        return composite_cls(default=state_cls(rt), routes={})
+
+        return composite_cls(default=state_cls(rt), routes=routes)
 
     return factory
 
 
 __all__ = [
+    "MEMORY_FILE",
+    "MEMORIES_PREFIX",
+    "SKILLS_PREFIX",
     "WORKSPACE_PREFIX",
     "WorkspacePathBackend",
     "coerce_file_data",
     "coerce_read_result",
     "make_workspace_backend_factory",
+    "normalize_backend_path",
     "normalize_workspace_path",
 ]

agent/tests/test_build_agent.py

@@ -6,7 +6,7 @@
 from app.agent import _apply_mode_harness_profile, _build_subagents, build_agent
 from app.config import get_settings
 from app.prompts import build_system_prompt
-from app.workspace_backend import WorkspacePathBackend
+from app.workspace_backend import MEMORY_FILE, SKILLS_PREFIX, WorkspacePathBackend
 
 
 def test_build_agent_mounts_workspace_for_valid_dir(tmp_path: Path):
@@ -22,12 +22,14 @@ def fake_create_deep_agent(**kwargs):
     with (
         patch("deepagents.create_deep_agent", side_effect=fake_create_deep_agent),
         patch("deepagents.backends.LocalShellBackend") as local_shell,
+        patch("deepagents.backends.FilesystemBackend") as filesystem,
         patch("deepagents.backends.CompositeBackend") as composite,
         patch("deepagents.backends.StateBackend"),
         patch("app.agent._apply_mode_harness_profile") as apply_profile,
     ):
         shell = MagicMock(name="local-shell")
         local_shell.return_value = shell
+        filesystem.side_effect = lambda **kwargs: MagicMock(name="fs", kwargs=kwargs)
         composite.return_value = MagicMock(name="composite")
         agent = build_agent(
             session_id="s1",
@@ -47,6 +49,10 @@ def fake_create_deep_agent(**kwargs):
     composite.assert_called_once()
     routes = composite.call_args.kwargs.get("routes") or composite.call_args.args[1]
     assert "/workspace/" in routes
+    assert f"{SKILLS_PREFIX}/" in routes
+    assert "/memories/" in routes
+    assert captured["skills"] == [f"{SKILLS_PREFIX}/"]
+    assert captured["memory"] == [MEMORY_FILE]
     assert captured["subagents"] == []
     assert "/workspace" in captured["system_prompt"]
     assert str(tmp_path.resolve()) not in captured["system_prompt"]
@@ -63,6 +69,7 @@ def fake_create_deep_agent(**kwargs):
     with (
         patch("deepagents.create_deep_agent", side_effect=fake_create_deep_agent),
         patch("deepagents.backends.LocalShellBackend"),
+        patch("deepagents.backends.FilesystemBackend"),
         patch("deepagents.backends.CompositeBackend"),
         patch("deepagents.backends.StateBackend"),
         patch("app.agent._apply_mode_harness_profile") as apply_profile,
@@ -92,6 +99,7 @@ def fake_create_deep_agent(**kwargs):
     with (
         patch("deepagents.create_deep_agent", side_effect=fake_create_deep_agent),
         patch("deepagents.backends.LocalShellBackend") as local_shell,
+        patch("deepagents.backends.FilesystemBackend"),
         patch("deepagents.backends.CompositeBackend") as composite,
         patch("deepagents.backends.StateBackend") as state_backend,
         patch("app.agent._apply_mode_harness_profile"),
@@ -111,6 +119,9 @@ def fake_create_deep_agent(**kwargs):
     assert backend is composite.return_value
     local_shell.assert_not_called()
     state_backend.assert_called_once()
+    routes = composite.call_args.kwargs.get("routes") or {}
+    assert f"{SKILLS_PREFIX}/" in routes
+    assert captured["skills"] == [f"{SKILLS_PREFIX}/"]
     assert captured["system_prompt"] == build_system_prompt(has_workspace=False)
 
 
@@ -126,6 +137,7 @@ def fake_create_deep_agent(**kwargs):
     with (
         patch("deepagents.create_deep_agent", side_effect=fake_create_deep_agent),
         patch("deepagents.backends.LocalShellBackend") as local_shell,
+        patch("deepagents.backends.FilesystemBackend"),
         patch("deepagents.backends.CompositeBackend") as composite,
         patch("deepagents.backends.StateBackend") as state_backend,
         patch("app.agent._apply_mode_harness_profile"),
@@ -154,6 +166,7 @@ def fake_create_deep_agent(**kwargs):
 
     with (
         patch("deepagents.create_deep_agent", side_effect=fake_create_deep_agent),
+        patch("deepagents.backends.FilesystemBackend"),
         patch("deepagents.backends.CompositeBackend"),
         patch("deepagents.backends.StateBackend"),
         patch("app.agent._apply_mode_harness_profile"),