refactor(agents): move mac-only modules out of the cross-agent shared kernel

app/agents/shared/ is a sibling of anonymous_chat/podcaster/multi_agent_chat/
video_presentation, so it should only hold code shared across 2+ of those
agents. In practice podcaster and video_presentation import nothing from it,
and anonymous_chat needs only context + compaction + retry_after + web_search.
Everything else was multi_agent_chat-only (the boundary just passes through).

Move the multi_agent_chat-only cluster into multi_agent_chat/shared/ (files
moved verbatim via git rename; ~116 import sites rewritten):

  errors, feature_flags, filesystem_selection, path_resolver, prompt_caching,
  sandbox, llm_config, mention_resolver
  middleware/busy_mutex, middleware/kb_persistence

busy_mutex/llm_config/mention_resolver are boundary-only but import the moved
modules, so they were folded in to avoid a backwards shared -> multi_agent_chat
dependency. main_agent builders now import the impls directly; the shared
middleware barrel keeps only the genuinely-shared compaction + retry_after.

Also delete the dead leftover shared/plugins and shared/skills dirs (live
copies already live under main_agent/).

Remaining in app/agents/shared/: context, system_prompt(+prompts), checkpointer,
middleware/{compaction,retry_after,dedup_tool_calls}, tools/. checkpointer and
system_prompt are boundary-only infra pending a dedicated home decision.

surfsense_backend/tests/e2e/run_backend.py

@@ -239,11 +239,11 @@ def _patch_llm_bindings() -> None:
 
     chat_targets = [
         (
-            "app.agents.shared.llm_config.create_chat_litellm_from_agent_config",
+            "app.agents.multi_agent_chat.shared.llm_config.create_chat_litellm_from_agent_config",
             fake_create_chat_litellm_from_agent_config,
         ),
         (
-            "app.agents.shared.llm_config.create_chat_litellm_from_config",
+            "app.agents.multi_agent_chat.shared.llm_config.create_chat_litellm_from_config",
             fake_create_chat_litellm_from_config,
         ),
         (

surfsense_backend/tests/e2e/run_celery.py

@@ -212,11 +212,11 @@ def _patch_llm_bindings() -> None:
 
     chat_targets = [
         (
-            "app.agents.shared.llm_config.create_chat_litellm_from_agent_config",
+            "app.agents.multi_agent_chat.shared.llm_config.create_chat_litellm_from_agent_config",
             fake_create_chat_litellm_from_agent_config,
         ),
         (
-            "app.agents.shared.llm_config.create_chat_litellm_from_config",
+            "app.agents.multi_agent_chat.shared.llm_config.create_chat_litellm_from_config",
             fake_create_chat_litellm_from_config,
         ),
         (

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

@@ -20,13 +20,16 @@ from langchain.agents import create_agent
 from langchain_core.messages import HumanMessage, ToolMessage
 from langgraph.checkpoint.memory import InMemorySaver
 
+from app.agents.multi_agent_chat.shared.filesystem_selection import (
+    FilesystemMode,
+    FilesystemSelection,
+)
 from app.agents.multi_agent_chat.shared.middleware.filesystem import (
     build_filesystem_mw,
 )
 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
 
 pytestmark = [pytest.mark.integration, pytest.mark.asyncio]

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

@@ -23,17 +23,17 @@ from langchain.agents import create_agent
 from langchain_core.messages import HumanMessage, ToolMessage
 from langgraph.checkpoint.memory import InMemorySaver
 
+from app.agents.multi_agent_chat.shared.filesystem_selection import (
+    FilesystemMode,
+    FilesystemSelection,
+    LocalFilesystemMount,
+)
 from app.agents.multi_agent_chat.shared.middleware.filesystem import (
     build_filesystem_mw,
 )
 from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.resolver import (
     build_backend_resolver,
 )
-from app.agents.shared.filesystem_selection import (
-    FilesystemMode,
-    FilesystemSelection,
-    LocalFilesystemMount,
-)
 from tests.integration.harness import ScriptedTurn, build_scripted_harness
 
 pytestmark = [pytest.mark.integration, pytest.mark.asyncio]

surfsense_backend/tests/unit/agents/multi_agent_chat/middleware/shared/permissions/test_permission_ask_mcp_context.py

@@ -13,6 +13,7 @@ from langgraph.graph.message import add_messages
 from pydantic import BaseModel
 from typing_extensions import TypedDict
 
+from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
 from app.agents.multi_agent_chat.shared.middleware.permissions import (
     build_permission_mw,
 )
@@ -20,7 +21,6 @@ from app.agents.multi_agent_chat.shared.middleware.permissions.ask.payload impor
     build_permission_ask_payload,
 )
 from app.agents.multi_agent_chat.shared.permissions import Rule, Ruleset
-from app.agents.shared.feature_flags import AgentFeatureFlags
 
 
 class _NoArgs(BaseModel):

surfsense_backend/tests/unit/agents/multi_agent_chat/middleware/shared/permissions/test_subagent_owned_ruleset.py

@@ -23,11 +23,11 @@ from langgraph.graph.message import add_messages
 from langgraph.types import Command
 from typing_extensions import TypedDict
 
+from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
 from app.agents.multi_agent_chat.shared.middleware.permissions import (
     build_permission_mw,
 )
 from app.agents.multi_agent_chat.shared.permissions import Rule, Ruleset
-from app.agents.shared.feature_flags import AgentFeatureFlags
 
 
 def _kb_style_ruleset() -> Ruleset:

surfsense_backend/tests/unit/agents/multi_agent_chat/middleware/shared/permissions/test_trusted_tool_save_on_always.py

@@ -14,11 +14,11 @@ from langgraph.types import Command
 from pydantic import BaseModel
 from typing_extensions import TypedDict
 
+from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
 from app.agents.multi_agent_chat.shared.middleware.permissions import (
     build_permission_mw,
 )
 from app.agents.multi_agent_chat.shared.permissions import Rule, Ruleset
-from app.agents.shared.feature_flags import AgentFeatureFlags
 
 
 class _NoArgs(BaseModel):

surfsense_backend/tests/unit/agents/multi_agent_chat/subagents/shared/test_subagent_builder.py

@@ -19,6 +19,7 @@ from langchain_core.language_models.fake_chat_models import (
 from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
 from langchain_core.outputs import ChatGeneration, ChatResult
 
+from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
 from app.agents.multi_agent_chat.shared.middleware.permissions.middleware.core import (
     PermissionMiddleware,
 )
@@ -26,7 +27,6 @@ from app.agents.multi_agent_chat.shared.permissions import Rule, Ruleset, evalua
 from app.agents.multi_agent_chat.subagents.shared.subagent_builder import (
     pack_subagent,
 )
-from app.agents.shared.feature_flags import AgentFeatureFlags
 
 
 class RateLimitError(Exception):

surfsense_backend/tests/unit/agents/new_chat/test_action_log.py

@@ -14,7 +14,7 @@ from app.agents.multi_agent_chat.main_agent.middleware.action_log.middleware imp
     ActionLogMiddleware,
     ToolDefinition,
 )
-from app.agents.shared.feature_flags import AgentFeatureFlags
+from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
 
 
 @dataclass

surfsense_backend/tests/unit/agents/new_chat/test_busy_mutex.py

@@ -4,8 +4,8 @@ from __future__ import annotations
 
 import pytest
 
-from app.agents.shared.errors import BusyError
-from app.agents.shared.middleware.busy_mutex import (
+from app.agents.multi_agent_chat.shared.errors import BusyError
+from app.agents.multi_agent_chat.shared.middleware.busy_mutex import (
     BusyMutexMiddleware,
     end_turn,
     get_cancel_event,

surfsense_backend/tests/unit/agents/new_chat/test_feature_flags.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import pytest
 
-from app.agents.shared.feature_flags import (
+from app.agents.multi_agent_chat.shared.feature_flags import (
     AgentFeatureFlags,
     reload_for_tests,
 )

surfsense_backend/tests/unit/agents/new_chat/test_mention_resolver.py

@@ -15,14 +15,14 @@ from unittest.mock import AsyncMock, MagicMock
 
 import pytest
 
-from app.agents.shared import mention_resolver
-from app.agents.shared.mention_resolver import (
+from app.agents.multi_agent_chat.shared.mention_resolver import (
     ResolvedMention,
     ResolvedMentionSet,
     resolve_mentions,
     substitute_in_text,
 )
-from app.agents.shared.path_resolver import DOCUMENTS_ROOT, PathIndex
+from app.agents.multi_agent_chat.shared.path_resolver import DOCUMENTS_ROOT, PathIndex
+from app.agents.multi_agent_chat.shared import mention_resolver
 from app.schemas.new_chat import MentionedDocumentInfo
 
 pytestmark = pytest.mark.unit

surfsense_backend/tests/unit/agents/new_chat/test_path_resolver.py

@@ -7,7 +7,7 @@ from unittest.mock import AsyncMock, MagicMock
 
 import pytest
 
-from app.agents.shared.path_resolver import (
+from app.agents.multi_agent_chat.shared.path_resolver import (
     DOCUMENTS_ROOT,
     PathIndex,
     doc_to_virtual_path,

surfsense_backend/tests/unit/agents/new_chat/test_prompt_caching.py

@@ -1,5 +1,5 @@
 r"""Tests for ``apply_litellm_prompt_caching`` in
-:mod:`app.agents.shared.prompt_caching`.
+:mod:`app.agents.multi_agent_chat.shared.prompt_caching`.
 
 The helper replaces the legacy ``AnthropicPromptCachingMiddleware`` (which
 never activated for our LiteLLM stack) with LiteLLM-native multi-provider
@@ -34,8 +34,10 @@ from typing import Any
 
 import pytest
 
-from app.agents.shared.llm_config import AgentConfig
-from app.agents.shared.prompt_caching import apply_litellm_prompt_caching
+from app.agents.multi_agent_chat.shared.llm_config import AgentConfig
+from app.agents.multi_agent_chat.shared.prompt_caching import (
+    apply_litellm_prompt_caching,
+)
 
 pytestmark = pytest.mark.unit
 

surfsense_backend/tests/unit/automations/services/test_model_policy.py

@@ -44,7 +44,7 @@ def patched_globals(monkeypatch: pytest.MonkeyPatch):
         -2: {"id": -2, "billing_tier": "free"},
     }
     monkeypatch.setattr(
-        "app.agents.shared.llm_config.load_global_llm_config_by_id",
+        "app.agents.multi_agent_chat.shared.llm_config.load_global_llm_config_by_id",
         lambda cid: llm_configs.get(cid),
     )
 

surfsense_backend/tests/unit/middleware/test_b_filesystem_path_resolution.py

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

surfsense_backend/tests/unit/middleware/test_b_filesystem_rm_rmdir_cloud.py

@@ -19,6 +19,10 @@ from unittest.mock import AsyncMock
 
 import pytest
 
+from app.agents.multi_agent_chat.shared.filesystem_selection import (
+    FilesystemMode,
+    FilesystemSelection,
+)
 from app.agents.multi_agent_chat.shared.middleware.filesystem import (
     build_filesystem_mw,
 )
@@ -29,7 +33,6 @@ from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.resolver
     build_backend_resolver,
 )
 from app.agents.multi_agent_chat.shared.state.reducers import _CLEAR
-from app.agents.shared.filesystem_selection import FilesystemMode, FilesystemSelection
 
 pytestmark = pytest.mark.unit
 

surfsense_backend/tests/unit/middleware/test_b_filesystem_system_prompt.py

@@ -18,10 +18,10 @@ from __future__ import annotations
 
 import pytest
 
+from app.agents.multi_agent_chat.shared.filesystem_selection import FilesystemMode
 from app.agents.multi_agent_chat.shared.middleware.filesystem.system_prompt import (
     build_system_prompt,
 )
-from app.agents.shared.filesystem_selection import FilesystemMode
 
 pytestmark = pytest.mark.unit
 

surfsense_backend/tests/unit/middleware/test_filesystem_backends.py

@@ -2,18 +2,18 @@ from pathlib import Path
 
 import pytest
 
+from app.agents.multi_agent_chat.shared.filesystem_selection import (
+    ClientPlatform,
+    FilesystemMode,
+    FilesystemSelection,
+    LocalFilesystemMount,
+)
 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,
-)
 
 pytestmark = pytest.mark.unit
 

surfsense_backend/tests/unit/middleware/test_kb_persistence_filesystem_parity.py

@@ -15,7 +15,7 @@ from unittest.mock import AsyncMock
 import numpy as np
 import pytest
 
-from app.agents.shared.middleware import kb_persistence
+from app.agents.multi_agent_chat.shared.middleware import kb_persistence
 from app.db import Document
 
 

surfsense_backend/tests/unit/middleware/test_kb_persistence_revisions.py

@@ -21,7 +21,7 @@ from unittest.mock import AsyncMock, MagicMock
 
 import pytest
 
-from app.agents.shared.middleware import kb_persistence
+from app.agents.multi_agent_chat.shared.middleware import kb_persistence
 
 pytestmark = pytest.mark.unit
 

surfsense_backend/tests/unit/middleware/test_knowledge_tree.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 from app.agents.multi_agent_chat.main_agent.middleware.knowledge_tree.middleware import (
     KnowledgeTreeMiddleware,
 )
-from app.agents.shared.path_resolver import DOCUMENTS_ROOT
+from app.agents.multi_agent_chat.shared.path_resolver import DOCUMENTS_ROOT
 
 
 def _compute(folder_paths: list[str], doc_paths: list[str]) -> set[str]:
@@ -88,7 +88,7 @@ class TestFormatTreeRendering:
         folder_paths: list[str],
         doc_specs: list[dict],
     ) -> str:
-        from app.agents.shared.path_resolver import PathIndex
+        from app.agents.multi_agent_chat.shared.path_resolver import PathIndex
 
         index = PathIndex(
             folder_paths={i + 1: p for i, p in enumerate(folder_paths)},

surfsense_backend/tests/unit/routes/test_revert_turn_route.py

@@ -18,7 +18,7 @@ from unittest.mock import AsyncMock, patch
 
 import pytest
 
-from app.agents.shared.feature_flags import AgentFeatureFlags
+from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
 from app.routes import agent_revert_route
 from app.services.revert_service import RevertOutcome
 

surfsense_backend/tests/unit/services/test_supports_image_input.py

@@ -227,7 +227,7 @@ global_llm_configs:
 
 
 def test_agent_config_from_yaml_explicit_overrides_resolver():
-    from app.agents.shared.llm_config import AgentConfig
+    from app.agents.multi_agent_chat.shared.llm_config import AgentConfig
 
     cfg_text_only = AgentConfig.from_yaml_config(
         {
@@ -256,7 +256,7 @@ def test_agent_config_from_yaml_explicit_overrides_resolver():
 def test_agent_config_from_yaml_unannotated_uses_resolver():
     """Without an explicit YAML key, AgentConfig defers to the catalog
     resolver — for ``gpt-4o`` LiteLLM's map says supports_vision=True."""
-    from app.agents.shared.llm_config import AgentConfig
+    from app.agents.multi_agent_chat.shared.llm_config import AgentConfig
 
     cfg = AgentConfig.from_yaml_config(
         {
@@ -275,7 +275,7 @@ def test_agent_config_auto_mode_supports_image_input():
     so users can keep their selection on Auto with a vision-capable
     deployment somewhere in the pool. The router's own `allowed_fails`
     handles non-vision deployments via fallback."""
-    from app.agents.shared.llm_config import AgentConfig
+    from app.agents.multi_agent_chat.shared.llm_config import AgentConfig
 
     auto = AgentConfig.from_auto_mode()
     assert auto.supports_image_input is True

surfsense_backend/tests/unit/services/test_vision_llm_api_base_defense.py

@@ -61,7 +61,7 @@ async def test_get_vision_llm_global_openrouter_sets_api_base():
             return_value=cfg,
         ),
         patch(
-            "app.agents.shared.llm_config.SanitizedChatLiteLLM",
+            "app.agents.multi_agent_chat.shared.llm_config.SanitizedChatLiteLLM",
             new=FakeSanitized,
         ),
     ):