refactor(agents): consolidate chat runtime infra under chat/runtime

Move the lower-level runtime/infra modules out of multi_agent_chat/shared/
(they were never used by subagents, so they failed the shared-by-all-siblings
rule) and unify them with the already-relocated checkpointer:

  agents/runtime/                      -> agents/chat/runtime/
  mac/shared/errors.py                 -> chat/runtime/errors.py
  mac/shared/llm_config.py             -> chat/runtime/llm_config.py
  mac/shared/prompt_caching.py         -> chat/runtime/prompt_caching.py
  mac/shared/mention_resolver.py       -> chat/runtime/mention_resolver.py
  mac/shared/path_resolver.py          -> chat/runtime/path_resolver.py

These sit below the agent packages: the boundary + agent factory + shared
middleware depend on them, and they import no agent code (acyclic).

surfsense_backend/tests/e2e/run_backend.py

@@ -239,11 +239,11 @@ def _patch_llm_bindings() -> None:
 
     chat_targets = [
         (
-            "app.agents.chat.multi_agent_chat.shared.llm_config.create_chat_litellm_from_agent_config",
+            "app.agents.chat.runtime.llm_config.create_chat_litellm_from_agent_config",
             fake_create_chat_litellm_from_agent_config,
         ),
         (
-            "app.agents.chat.multi_agent_chat.shared.llm_config.create_chat_litellm_from_config",
+            "app.agents.chat.runtime.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.chat.multi_agent_chat.shared.llm_config.create_chat_litellm_from_agent_config",
+            "app.agents.chat.runtime.llm_config.create_chat_litellm_from_agent_config",
             fake_create_chat_litellm_from_agent_config,
         ),
         (
-            "app.agents.chat.multi_agent_chat.shared.llm_config.create_chat_litellm_from_config",
+            "app.agents.chat.runtime.llm_config.create_chat_litellm_from_config",
             fake_create_chat_litellm_from_config,
         ),
         (

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

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import pytest
 
-from app.agents.chat.multi_agent_chat.shared.errors import BusyError
 from app.agents.chat.multi_agent_chat.shared.middleware.busy_mutex import (
     BusyMutexMiddleware,
     end_turn,
@@ -14,6 +13,7 @@ from app.agents.chat.multi_agent_chat.shared.middleware.busy_mutex import (
     request_cancel,
     reset_cancel,
 )
+from app.agents.chat.runtime.errors import BusyError
 
 pytestmark = pytest.mark.unit
 

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.chat.multi_agent_chat.shared import mention_resolver
-from app.agents.chat.multi_agent_chat.shared.mention_resolver import (
+from app.agents.chat.runtime import mention_resolver
+from app.agents.chat.runtime.mention_resolver import (
     ResolvedMention,
     ResolvedMentionSet,
     resolve_mentions,
     substitute_in_text,
 )
-from app.agents.chat.multi_agent_chat.shared.path_resolver import (
+from app.agents.chat.runtime.path_resolver import (
     DOCUMENTS_ROOT,
     PathIndex,
 )

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.chat.multi_agent_chat.shared.path_resolver import (
+from app.agents.chat.runtime.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.chat.multi_agent_chat.shared.prompt_caching`.
+:mod:`app.agents.chat.runtime.prompt_caching`.
 
 The helper replaces the legacy ``AnthropicPromptCachingMiddleware`` (which
 never activated for our LiteLLM stack) with LiteLLM-native multi-provider
@@ -34,8 +34,8 @@ from typing import Any
 
 import pytest
 
-from app.agents.chat.multi_agent_chat.shared.llm_config import AgentConfig
-from app.agents.chat.multi_agent_chat.shared.prompt_caching import (
+from app.agents.chat.runtime.llm_config import AgentConfig
+from app.agents.chat.runtime.prompt_caching import (
     apply_litellm_prompt_caching,
 )
 

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.chat.multi_agent_chat.shared.llm_config.load_global_llm_config_by_id",
+        "app.agents.chat.runtime.llm_config.load_global_llm_config_by_id",
         lambda cid: llm_configs.get(cid),
     )
 

surfsense_backend/tests/unit/middleware/test_knowledge_tree.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 from app.agents.chat.multi_agent_chat.main_agent.middleware.knowledge_tree.middleware import (
     KnowledgeTreeMiddleware,
 )
-from app.agents.chat.multi_agent_chat.shared.path_resolver import DOCUMENTS_ROOT
+from app.agents.chat.runtime.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.chat.multi_agent_chat.shared.path_resolver import PathIndex
+        from app.agents.chat.runtime.path_resolver import PathIndex
 
         index = PathIndex(
             folder_paths={i + 1: p for i, p in enumerate(folder_paths)},

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.chat.multi_agent_chat.shared.llm_config import AgentConfig
+    from app.agents.chat.runtime.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.chat.multi_agent_chat.shared.llm_config import AgentConfig
+    from app.agents.chat.runtime.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.chat.multi_agent_chat.shared.llm_config import AgentConfig
+    from app.agents.chat.runtime.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.chat.multi_agent_chat.shared.llm_config.SanitizedChatLiteLLM",
+            "app.agents.chat.runtime.llm_config.SanitizedChatLiteLLM",
             new=FakeSanitized,
         ),
     ):