feat(new-chat): add filesystem backend interfaces and selection helpers

surfsense_backend/app/agents/new_chat/filesystem_backends.py

@@ -0,0 +1,38 @@
+"""Filesystem backend resolver for cloud and desktop-local modes."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import lru_cache
+
+from deepagents.backends.state import StateBackend
+from langgraph.prebuilt.tool_node import ToolRuntime
+
+from app.agents.new_chat.filesystem_selection import FilesystemMode, FilesystemSelection
+from app.agents.new_chat.middleware.local_folder_backend import LocalFolderBackend
+
+
+@lru_cache(maxsize=64)
+def _cached_local_backend(root_path: str) -> LocalFolderBackend:
+    return LocalFolderBackend(root_path)
+
+
+def build_backend_resolver(
+    selection: FilesystemSelection,
+) -> Callable[[ToolRuntime], StateBackend | LocalFolderBackend]:
+    """Create deepagents backend resolver for the selected filesystem mode."""
+
+    if (
+        selection.mode == FilesystemMode.DESKTOP_LOCAL_FOLDER
+        and selection.local_root_path is not None
+    ):
+
+        def _resolve_local(_runtime: ToolRuntime) -> LocalFolderBackend:
+            return _cached_local_backend(selection.local_root_path or "")
+
+        return _resolve_local
+
+    def _resolve_cloud(runtime: ToolRuntime) -> StateBackend:
+        return StateBackend(runtime)
+
+    return _resolve_cloud

surfsense_backend/app/agents/new_chat/filesystem_selection.py

@@ -0,0 +1,33 @@
+"""Filesystem mode contracts and selection helpers for chat sessions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class FilesystemMode(StrEnum):
+    """Supported filesystem backends for agent tool execution."""
+
+    CLOUD = "cloud"
+    DESKTOP_LOCAL_FOLDER = "desktop_local_folder"
+
+
+class ClientPlatform(StrEnum):
+    """Client runtime reported by the caller."""
+
+    WEB = "web"
+    DESKTOP = "desktop"
+
+
+@dataclass(slots=True)
+class FilesystemSelection:
+    """Resolved filesystem selection for a single chat request."""
+
+    mode: FilesystemMode = FilesystemMode.CLOUD
+    client_platform: ClientPlatform = ClientPlatform.WEB
+    local_root_path: str | None = None
+
+    @property
+    def is_local_mode(self) -> bool:
+        return self.mode == FilesystemMode.DESKTOP_LOCAL_FOLDER

surfsense_backend/app/agents/new_chat/middleware/__init__.py

@@ -6,6 +6,9 @@ from app.agents.new_chat.middleware.dedup_tool_calls import (
 from app.agents.new_chat.middleware.filesystem import (
     SurfSenseFilesystemMiddleware,
 )
+from app.agents.new_chat.middleware.file_intent import (
+    FileIntentMiddleware,
+)
 from app.agents.new_chat.middleware.knowledge_search import (
     KnowledgeBaseSearchMiddleware,
 )
@@ -15,6 +18,7 @@ from app.agents.new_chat.middleware.memory_injection import (
 
 __all__ = [
     "DedupHITLToolCallsMiddleware",
+    "FileIntentMiddleware",
     "KnowledgeBaseSearchMiddleware",
     "MemoryInjectionMiddleware",
     "SurfSenseFilesystemMiddleware",