refactor(agents): group filesystem backends under filesystem/backends/

The concrete filesystem backends are consumed only by the MAC filesystem
layer (tools, path-resolution middleware, the resolver, skills backend) and
tests -- no external app code. Group them next to the filesystem middleware
they serve:

- filesystem_backends.py            -> filesystem/backends/resolver.py
- middleware/kb_postgres_backend.py -> filesystem/backends/kb_postgres.py
- middleware/local_folder_backend.py -> filesystem/backends/local_folder.py
- middleware/multi_root_local_folder_backend.py -> .../multi_root_local_folder.py
- document_xml.py                   -> filesystem/backends/document_xml.py

Repoint all 21 importers. No behavior change; import-all + filesystem
backend/path-resolution/knowledge-search unit tests stay green (478).

surfsense_backend/app/agents/multi_agent_chat/main_agent/runtime/factory.py

@@ -12,6 +12,9 @@ from langchain_core.tools import BaseTool
 from langgraph.types import Checkpointer
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.resolver import (
+    build_backend_resolver,
+)
 from app.agents.multi_agent_chat.subagents import (
     get_subagents_to_exclude,
     main_prompt_registry_subagent_lines,
@@ -20,7 +23,6 @@ from app.agents.multi_agent_chat.subagents.mcp_tools.index import (
     load_mcp_tools_by_connector,
 )
 from app.agents.shared.feature_flags import AgentFeatureFlags, get_flags
-from app.agents.shared.filesystem_backends import build_backend_resolver
 from app.agents.shared.filesystem_selection import FilesystemMode, FilesystemSelection
 from app.agents.shared.llm_config import AgentConfig
 from app.agents.shared.prompt_caching import apply_litellm_prompt_caching

surfsense_backend/app/agents/multi_agent_chat/main_agent/skills/backends.py

@@ -47,7 +47,9 @@ from deepagents.backends.state import StateBackend
 if TYPE_CHECKING:
     from langchain.tools import ToolRuntime
 
-    from app.agents.shared.middleware.kb_postgres_backend import KBPostgresBackend
+    from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.kb_postgres import (
+        KBPostgresBackend,
+    )
 
 logger = logging.getLogger(__name__)
 
@@ -308,7 +310,7 @@ def build_skills_backend_factory(
         # Imported lazily to avoid a hard dependency at module import time:
         # ``KBPostgresBackend`` pulls in DB models, which are unnecessary for
         # the unit-tested builtin path.
-        from app.agents.shared.middleware.kb_postgres_backend import (
+        from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.kb_postgres import (
             KBPostgresBackend,
         )
 

surfsense_backend/app/agents/multi_agent_chat/shared/middleware/filesystem/backends/kb_postgres.py

@@ -42,7 +42,9 @@ from langchain.tools import ToolRuntime
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.agents.shared.document_xml import build_document_xml
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.document_xml import (
+    build_document_xml,
+)
 from app.agents.shared.path_resolver import (
     DOCUMENTS_ROOT,
     build_path_index,

surfsense_backend/app/agents/multi_agent_chat/shared/middleware/filesystem/backends/multi_root_local_folder.py

@@ -15,7 +15,9 @@ from deepagents.backends.protocol import (
     WriteResult,
 )
 
-from app.agents.shared.middleware.local_folder_backend import LocalFolderBackend
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.local_folder import (
+    LocalFolderBackend,
+)
 
 _INVALID_PATH = "invalid_path"
 _FILE_NOT_FOUND = "file_not_found"

surfsense_backend/app/agents/multi_agent_chat/shared/middleware/filesystem/backends/resolver.py

@@ -9,11 +9,13 @@ from deepagents.backends.protocol import BackendProtocol
 from deepagents.backends.state import StateBackend
 from langgraph.prebuilt.tool_node import ToolRuntime
 
-from app.agents.shared.filesystem_selection import FilesystemMode, FilesystemSelection
-from app.agents.shared.middleware.kb_postgres_backend import KBPostgresBackend
-from app.agents.shared.middleware.multi_root_local_folder_backend import (
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.kb_postgres import (
+    KBPostgresBackend,
+)
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.multi_root_local_folder import (
     MultiRootLocalFolderBackend,
 )
+from app.agents.shared.filesystem_selection import FilesystemMode, FilesystemSelection
 
 
 @lru_cache(maxsize=64)

surfsense_backend/app/agents/multi_agent_chat/shared/middleware/filesystem/middleware/path_resolution.py

@@ -7,13 +7,13 @@ from typing import TYPE_CHECKING
 
 from langchain.tools import ToolRuntime
 
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.multi_root_local_folder import (
+    MultiRootLocalFolderBackend,
+)
 from app.agents.multi_agent_chat.shared.state.filesystem_state import (
     SurfSenseFilesystemState,
 )
 from app.agents.shared.filesystem_selection import FilesystemMode
-from app.agents.shared.middleware.multi_root_local_folder_backend import (
-    MultiRootLocalFolderBackend,
-)
 
 from ..shared.paths import (
     extract_mount_from_path,

surfsense_backend/app/agents/multi_agent_chat/shared/middleware/filesystem/tools/edit_file/index.py

@@ -11,10 +11,12 @@ from langchain_core.messages import ToolMessage
 from langchain_core.tools import BaseTool, StructuredTool
 from langgraph.types import Command
 
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.kb_postgres import (
+    KBPostgresBackend,
+)
 from app.agents.multi_agent_chat.shared.state.filesystem_state import (
     SurfSenseFilesystemState,
 )
-from app.agents.shared.middleware.kb_postgres_backend import KBPostgresBackend
 
 from ...middleware.async_dispatch import run_async_blocking
 from ...middleware.mode import is_cloud

surfsense_backend/app/agents/multi_agent_chat/shared/middleware/filesystem/tools/list_tree/index.py

@@ -9,10 +9,12 @@ from deepagents.backends.utils import validate_path
 from langchain.tools import ToolRuntime
 from langchain_core.tools import BaseTool, StructuredTool
 
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.kb_postgres import (
+    KBPostgresBackend,
+)
 from app.agents.multi_agent_chat.shared.state.filesystem_state import (
     SurfSenseFilesystemState,
 )
-from app.agents.shared.middleware.kb_postgres_backend import KBPostgresBackend
 
 from ...middleware.async_dispatch import run_async_blocking
 from ...middleware.path_resolution import resolve_list_target_path

surfsense_backend/app/agents/multi_agent_chat/shared/middleware/filesystem/tools/ls/index.py

@@ -8,10 +8,12 @@ from deepagents.backends.utils import validate_path
 from langchain.tools import ToolRuntime
 from langchain_core.tools import BaseTool, StructuredTool
 
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.kb_postgres import (
+    paginate_listing,
+)
 from app.agents.multi_agent_chat.shared.state.filesystem_state import (
     SurfSenseFilesystemState,
 )
-from app.agents.shared.middleware.kb_postgres_backend import paginate_listing
 
 from ...middleware.async_dispatch import run_async_blocking
 from ...middleware.path_resolution import resolve_list_target_path

surfsense_backend/app/agents/multi_agent_chat/shared/middleware/filesystem/tools/move_file/helpers.py

@@ -8,11 +8,13 @@ from langchain.tools import ToolRuntime
 from langchain_core.messages import ToolMessage
 from langgraph.types import Command
 
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.kb_postgres import (
+    KBPostgresBackend,
+)
 from app.agents.multi_agent_chat.shared.state.filesystem_state import (
     SurfSenseFilesystemState,
 )
 from app.agents.multi_agent_chat.shared.state.reducers import _CLEAR
-from app.agents.shared.middleware.kb_postgres_backend import KBPostgresBackend
 from app.agents.shared.path_resolver import DOCUMENTS_ROOT
 
 if TYPE_CHECKING:

surfsense_backend/app/agents/multi_agent_chat/shared/middleware/filesystem/tools/read_file/index.py

@@ -10,10 +10,12 @@ from langchain_core.messages import ToolMessage
 from langchain_core.tools import BaseTool, StructuredTool
 from langgraph.types import Command
 
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.kb_postgres import (
+    KBPostgresBackend,
+)
 from app.agents.multi_agent_chat.shared.state.filesystem_state import (
     SurfSenseFilesystemState,
 )
-from app.agents.shared.middleware.kb_postgres_backend import KBPostgresBackend
 
 from ...middleware.async_dispatch import run_async_blocking
 from ...middleware.path_resolution import resolve_relative

surfsense_backend/app/agents/multi_agent_chat/shared/middleware/filesystem/tools/rm/helpers.py

@@ -12,11 +12,13 @@ from langchain.tools import ToolRuntime
 from langchain_core.messages import ToolMessage
 from langgraph.types import Command
 
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.kb_postgres import (
+    KBPostgresBackend,
+)
 from app.agents.multi_agent_chat.shared.state.filesystem_state import (
     SurfSenseFilesystemState,
 )
 from app.agents.multi_agent_chat.shared.state.reducers import _CLEAR
-from app.agents.shared.middleware.kb_postgres_backend import KBPostgresBackend
 from app.agents.shared.path_resolver import DOCUMENTS_ROOT
 
 if TYPE_CHECKING:

surfsense_backend/app/agents/multi_agent_chat/shared/middleware/filesystem/tools/rmdir/helpers.py

@@ -13,11 +13,13 @@ from langchain.tools import ToolRuntime
 from langchain_core.messages import ToolMessage
 from langgraph.types import Command
 
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.kb_postgres import (
+    KBPostgresBackend,
+)
 from app.agents.multi_agent_chat.shared.state.filesystem_state import (
     SurfSenseFilesystemState,
 )
 from app.agents.multi_agent_chat.shared.state.reducers import _CLEAR
-from app.agents.shared.middleware.kb_postgres_backend import KBPostgresBackend
 from app.agents.shared.path_resolver import DOCUMENTS_ROOT
 
 from ...middleware.path_resolution import current_cwd

surfsense_backend/tests/integration/agents/multi_agent_chat/test_kb_filesystem_cloud.py

@@ -23,7 +23,9 @@ from langgraph.checkpoint.memory import InMemorySaver
 from app.agents.multi_agent_chat.shared.middleware.filesystem import (
     build_filesystem_mw,
 )
-from app.agents.shared.filesystem_backends import build_backend_resolver
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.resolver import (
+    build_backend_resolver,
+)
 from app.agents.shared.filesystem_selection import FilesystemMode, FilesystemSelection
 from tests.integration.harness import ScriptedTurn, build_scripted_harness
 

surfsense_backend/tests/integration/agents/multi_agent_chat/test_kb_filesystem_desktop.py

@@ -26,7 +26,9 @@ from langgraph.checkpoint.memory import InMemorySaver
 from app.agents.multi_agent_chat.shared.middleware.filesystem import (
     build_filesystem_mw,
 )
-from app.agents.shared.filesystem_backends import build_backend_resolver
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.resolver import (
+    build_backend_resolver,
+)
 from app.agents.shared.filesystem_selection import (
     FilesystemMode,
     FilesystemSelection,

surfsense_backend/tests/unit/middleware/test_b_filesystem_path_resolution.py

@@ -20,6 +20,9 @@ from types import SimpleNamespace
 
 import pytest
 
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.multi_root_local_folder import (
+    MultiRootLocalFolderBackend,
+)
 from app.agents.multi_agent_chat.shared.middleware.filesystem.middleware.mode import (
     default_cwd,
 )
@@ -33,9 +36,6 @@ from app.agents.multi_agent_chat.shared.middleware.filesystem.middleware.path_re
     resolve_relative,
 )
 from app.agents.shared.filesystem_selection import FilesystemMode
-from app.agents.shared.middleware.multi_root_local_folder_backend import (
-    MultiRootLocalFolderBackend,
-)
 
 pytestmark = pytest.mark.unit
 

surfsense_backend/tests/unit/middleware/test_b_filesystem_rm_rmdir_cloud.py

@@ -22,10 +22,14 @@ import pytest
 from app.agents.multi_agent_chat.shared.middleware.filesystem import (
     build_filesystem_mw,
 )
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.kb_postgres import (
+    KBPostgresBackend,
+)
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.resolver import (
+    build_backend_resolver,
+)
 from app.agents.multi_agent_chat.shared.state.reducers import _CLEAR
-from app.agents.shared.filesystem_backends import build_backend_resolver
 from app.agents.shared.filesystem_selection import FilesystemMode, FilesystemSelection
-from app.agents.shared.middleware.kb_postgres_backend import KBPostgresBackend
 
 pytestmark = pytest.mark.unit
 

surfsense_backend/tests/unit/middleware/test_filesystem_backends.py

@@ -2,16 +2,18 @@ from pathlib import Path
 
 import pytest
 
-from app.agents.shared.filesystem_backends import build_backend_resolver
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.multi_root_local_folder import (
+    MultiRootLocalFolderBackend,
+)
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.resolver import (
+    build_backend_resolver,
+)
 from app.agents.shared.filesystem_selection import (
     ClientPlatform,
     FilesystemMode,
     FilesystemSelection,
     LocalFilesystemMount,
 )
-from app.agents.shared.middleware.multi_root_local_folder_backend import (
-    MultiRootLocalFolderBackend,
-)
 
 pytestmark = pytest.mark.unit
 

surfsense_backend/tests/unit/middleware/test_knowledge_search.py

@@ -5,7 +5,9 @@ import json
 import pytest
 from langchain_core.messages import AIMessage, HumanMessage
 
-from app.agents.shared.document_xml import build_document_xml as _build_document_xml
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.document_xml import (
+    build_document_xml as _build_document_xml,
+)
 from app.agents.shared.middleware.knowledge_search import (
     KBSearchPlan,
     KnowledgeBaseSearchMiddleware,

surfsense_backend/tests/unit/middleware/test_local_folder_backend.py

@@ -2,7 +2,9 @@ from pathlib import Path
 
 import pytest
 
-from app.agents.shared.middleware.local_folder_backend import LocalFolderBackend
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.local_folder import (
+    LocalFolderBackend,
+)
 
 pytestmark = pytest.mark.unit
 

surfsense_backend/tests/unit/middleware/test_multi_root_local_folder_backend.py

@@ -2,7 +2,7 @@ from pathlib import Path
 
 import pytest
 
-from app.agents.shared.middleware.multi_root_local_folder_backend import (
+from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.multi_root_local_folder import (
     MultiRootLocalFolderBackend,
 )