refactor(agents): colocate KB-search tool with its sole consumer; fix report ImportError

shared/tools/knowledge_base.py had exactly one production consumer: the
report deliverable, which imported it via `from .knowledge_base import ...`
-- a sibling path that did not exist, so the report KB-search path would
raise ImportError at runtime.

Move the module next to report.py (subagents/builtins/deliverables/tools/)
which makes that relative import valid, and move its only dependency
(shared/utils.py date helpers) to multi_agent_chat/shared/date_filters.py,
shared between the KB tool and the knowledge_search middleware.

Drop the now-unused knowledge-base re-exports from the shared/tools barrel
and repoint the integration tests. import-all + error-contract stay green.

surfsense_backend/app/agents/multi_agent_chat/subagents/builtins/deliverables/tools/knowledge_base.py

@@ -692,7 +692,7 @@ async def search_knowledge_base_raw_async(
     # Preserve the public signature for compatibility even if values are unused.
     _ = (db_session, connector_service)
 
-    from app.agents.shared.utils import resolve_date_range
+    from app.agents.multi_agent_chat.shared.date_filters import resolve_date_range
 
     resolved_start_date, resolved_end_date = resolve_date_range(
         start_date=start_date,

surfsense_backend/app/agents/shared/middleware/knowledge_search.py

@@ -41,6 +41,10 @@ from litellm import token_counter
 from pydantic import BaseModel, Field, ValidationError
 from sqlalchemy import select
 
+from app.agents.multi_agent_chat.shared.date_filters import (
+    parse_date_or_datetime,
+    resolve_date_range,
+)
 from app.agents.shared.feature_flags import get_flags
 from app.agents.shared.filesystem_selection import FilesystemMode
 from app.agents.shared.filesystem_state import SurfSenseFilesystemState
@@ -49,7 +53,6 @@ from app.agents.shared.path_resolver import (
     build_path_index,
     doc_to_virtual_path,
 )
-from app.agents.shared.utils import parse_date_or_datetime, resolve_date_range
 from app.db import (
     NATIVE_TO_LEGACY_DOCTYPE,
     Chunk,

surfsense_backend/app/agents/shared/tools/__init__.py

@@ -1,24 +1,14 @@
 """Cross-agent shared tools and tool metadata.
 
 Tool *implementations* live with the agents that own them (e.g. deliverable
-generators under ``subagents/builtins/deliverables/tools``). This package
-holds only the genuinely shared pieces: the display-metadata catalog and the
-knowledge-base helpers used across agents.
+generators and their knowledge-base search helper under
+``subagents/builtins/deliverables/tools``). This package holds only the
+genuinely shared piece: the display-metadata catalog.
 """
 
 from .catalog import TOOL_CATALOG, ToolMetadata
-from .knowledge_base import (
-    CONNECTOR_DESCRIPTIONS,
-    format_documents_for_context,
-    search_knowledge_base_async,
-)
 
 __all__ = [
-    # Tool catalog (display metadata)
     "TOOL_CATALOG",
     "ToolMetadata",
-    # Knowledge base utilities
-    "CONNECTOR_DESCRIPTIONS",
-    "format_documents_for_context",
-    "search_knowledge_base_async",
 ]

surfsense_backend/tests/integration/google_unification/conftest.py

@@ -239,7 +239,7 @@ def patched_shielded_session(async_engine, monkeypatch):
             yield session
 
     monkeypatch.setattr(
-        "app.agents.shared.tools.knowledge_base.shielded_async_session",
+        "app.agents.multi_agent_chat.subagents.builtins.deliverables.tools.knowledge_base.shielded_async_session",
         _test_shielded,
     )
 

surfsense_backend/tests/integration/google_unification/test_browse_includes_legacy_docs.py

@@ -17,7 +17,9 @@ async def test_browse_recent_documents_with_list_type_returns_both(
     committed_google_data, patched_shielded_session
 ):
     """_browse_recent_documents returns docs of all types when given a list."""
-    from app.agents.shared.tools.knowledge_base import _browse_recent_documents
+    from app.agents.multi_agent_chat.subagents.builtins.deliverables.tools.knowledge_base import (
+        _browse_recent_documents,
+    )
 
     space_id = committed_google_data["search_space_id"]