refactor(agents): introduce chat/ category; dissolve top-level agents/shared

Recursive shared-folder rule: a shared/ must be shared by ALL siblings at its
level. The kernel (context, compaction, retry_after, web_search) was shared by
only 2 of the agents -- anonymous_chat + multi_agent_chat -- never by podcaster
or video_presentation. Those 2 are the "chat" category, so their shared code
belongs in that category's shared/, not the top-level one.

  app/agents/anonymous_chat/   -> app/agents/chat/anonymous_chat/
  app/agents/multi_agent_chat/ -> app/agents/chat/multi_agent_chat/
  app/agents/shared/           -> app/agents/chat/shared/   (anon<->mac kernel)

Top-level app/agents/shared/ is gone: nothing was shared across all three
categories (chat / podcaster / video_presentation).

~289 import sites rewritten (app.agents.{anonymous_chat,multi_agent_chat,shared}
-> app.agents.chat.*); all moves are git renames (history preserved).
app/agents/ now: chat/, podcaster/, video_presentation/, runtime/.

surfsense_backend/app/agents/chat/__init__.py

@@ -0,0 +1,5 @@
+"""Chat agents category.
+
+Groups the conversational agents that share a kernel: ``anonymous_chat`` and
+``multi_agent_chat``. Code shared by *both* lives in ``chat/shared/``.
+"""

surfsense_backend/app/agents/chat/anonymous_chat/__init__.py

@@ -6,7 +6,7 @@ subagents, skills, memory) and answers with an optional ``web_search`` tool and
 an optional read-only uploaded document. See :mod:`.agent` for details.
 """
 
-from app.agents.anonymous_chat.agent import (
+from app.agents.chat.anonymous_chat.agent import (
     build_anonymous_system_prompt,
     create_anonymous_chat_agent,
 )

surfsense_backend/app/agents/chat/anonymous_chat/agent.py

@@ -27,12 +27,12 @@ from langchain.agents.middleware import (
 from langchain_core.language_models import BaseChatModel
 from langgraph.types import Checkpointer
 
-from app.agents.shared.context import SurfSenseContextSchema
-from app.agents.shared.middleware import (
+from app.agents.chat.shared.context import SurfSenseContextSchema
+from app.agents.chat.shared.middleware import (
     RetryAfterMiddleware,
     create_surfsense_compaction_middleware,
 )
-from app.agents.shared.tools.web_search import create_web_search_tool
+from app.agents.chat.shared.tools.web_search import create_web_search_tool
 
 # Cap how much of an uploaded document we inline into the system prompt. The
 # upload endpoint allows files up to several MB, but the doc is re-sent on

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/graph/compile_graph_sync.py

@@ -11,12 +11,12 @@ from langchain_core.language_models import BaseChatModel
 from langchain_core.tools import BaseTool
 from langgraph.types import Checkpointer
 
-from app.agents.multi_agent_chat.main_agent.middleware.stack import (
+from app.agents.chat.multi_agent_chat.main_agent.middleware.stack import (
     build_main_agent_deepagent_middleware,
 )
-from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
-from app.agents.multi_agent_chat.shared.filesystem_selection import FilesystemMode
-from app.agents.shared.context import SurfSenseContextSchema
+from app.agents.chat.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
+from app.agents.chat.multi_agent_chat.shared.filesystem_selection import FilesystemMode
+from app.agents.chat.shared.context import SurfSenseContextSchema
 from app.db import ChatVisibility
 
 

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/action_log/builder.py

@@ -4,8 +4,8 @@ from __future__ import annotations
 
 import logging
 
-from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
-from app.agents.multi_agent_chat.shared.middleware.flags import enabled
+from app.agents.chat.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
+from app.agents.chat.multi_agent_chat.shared.middleware.flags import enabled
 
 from .middleware import ActionLogMiddleware
 

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/action_log/middleware.py

@@ -34,7 +34,7 @@ from langchain.agents.middleware import AgentMiddleware
 from langchain_core.callbacks import adispatch_custom_event
 from langchain_core.messages import ToolMessage
 
-from app.agents.multi_agent_chat.shared.feature_flags import get_flags
+from app.agents.chat.multi_agent_chat.shared.feature_flags import get_flags
 
 if TYPE_CHECKING:  # pragma: no cover - type-only
     from langchain.agents.middleware.types import ToolCallRequest

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/anonymous_document/builder.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from app.agents.multi_agent_chat.shared.filesystem_selection import FilesystemMode
+from app.agents.chat.multi_agent_chat.shared.filesystem_selection import FilesystemMode
 
 from .middleware import AnonymousDocumentMiddleware
 

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/anonymous_document/middleware.py

@@ -24,11 +24,11 @@ from typing import Any
 from langchain.agents.middleware import AgentMiddleware, AgentState
 from langgraph.runtime import Runtime
 
-from app.agents.multi_agent_chat.shared.path_resolver import (
+from app.agents.chat.multi_agent_chat.shared.path_resolver import (
     DOCUMENTS_ROOT,
     safe_filename,
 )
-from app.agents.multi_agent_chat.shared.state.filesystem_state import (
+from app.agents.chat.multi_agent_chat.shared.state.filesystem_state import (
     SurfSenseFilesystemState,
 )
 

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/busy_mutex.py

@@ -0,0 +1,13 @@
+"""Per-thread cooperative lock around the whole turn."""
+
+from __future__ import annotations
+
+from app.agents.chat.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
+from app.agents.chat.multi_agent_chat.shared.middleware.busy_mutex import (
+    BusyMutexMiddleware,
+)
+from app.agents.chat.multi_agent_chat.shared.middleware.flags import enabled
+
+
+def build_busy_mutex_mw(flags: AgentFeatureFlags) -> BusyMutexMiddleware | None:
+    return BusyMutexMiddleware() if enabled(flags, "enable_busy_mutex") else None

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/checkpointed_subagent_middleware/middleware.py

@@ -16,7 +16,7 @@ from langchain.agents import create_agent
 from langchain.chat_models import init_chat_model
 from langgraph.types import Checkpointer
 
-from app.agents.multi_agent_chat.subagents.shared.spec import (
+from app.agents.chat.multi_agent_chat.subagents.shared.spec import (
     SURF_CONTEXT_HINT_PROVIDER_KEY,
 )
 from app.utils.perf import get_perf_logger

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/checkpointed_subagent_middleware/task_description.py

@@ -6,7 +6,7 @@ and the ``<tools>`` block render from the same source.
 
 from __future__ import annotations
 
-from app.agents.multi_agent_chat.main_agent.system_prompt.builder.load_md import (
+from app.agents.chat.multi_agent_chat.main_agent.system_prompt.builder.load_md import (
     read_prompt_md,
 )
 

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/checkpointed_subagent_middleware/task_tool.py

@@ -23,7 +23,7 @@ from langchain_core.tools import StructuredTool
 from langgraph.errors import GraphInterrupt
 from langgraph.types import Command, Interrupt
 
-from app.agents.multi_agent_chat.subagents.shared.spec import (
+from app.agents.chat.multi_agent_chat.subagents.shared.spec import (
     SURF_CONTEXT_HINT_PROVIDER_KEY,
     ContextHintProvider,
 )

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/context_editing/builder.py

@@ -7,11 +7,11 @@ from typing import Any
 
 from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.main_agent.context_prune.prune_tool_names import (
+from app.agents.chat.multi_agent_chat.main_agent.context_prune.prune_tool_names import (
     safe_exclude_tools,
 )
-from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
-from app.agents.multi_agent_chat.shared.middleware.flags import enabled
+from app.agents.chat.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
+from app.agents.chat.multi_agent_chat.shared.middleware.flags import enabled
 
 from .middleware import (
     ClearToolUsesEdit,

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/dedup_hitl.py

@@ -29,7 +29,7 @@ from langchain.agents.middleware import AgentMiddleware, AgentState
 from langchain_core.tools import BaseTool
 from langgraph.runtime import Runtime
 
-from app.agents.multi_agent_chat.shared.middleware.dedup_tool_calls import (
+from app.agents.chat.multi_agent_chat.shared.middleware.dedup_tool_calls import (
     DedupResolver,
     wrap_dedup_key_by_arg_name,
 )

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/doom_loop/builder.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
-from app.agents.multi_agent_chat.shared.middleware.flags import enabled
+from app.agents.chat.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
+from app.agents.chat.multi_agent_chat.shared.middleware.flags import enabled
 
 from .middleware import DoomLoopMiddleware
 

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/kb_persistence.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-from app.agents.multi_agent_chat.shared.filesystem_selection import FilesystemMode
-from app.agents.multi_agent_chat.shared.middleware.kb_persistence import (
+from app.agents.chat.multi_agent_chat.shared.filesystem_selection import FilesystemMode
+from app.agents.chat.multi_agent_chat.shared.middleware.kb_persistence import (
     KnowledgeBasePersistenceMiddleware,
 )
 

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/knowledge_priority.py

@@ -4,8 +4,8 @@ from __future__ import annotations
 
 from langchain_core.language_models import BaseChatModel
 
-from app.agents.multi_agent_chat.shared.filesystem_selection import FilesystemMode
-from app.agents.multi_agent_chat.shared.middleware.knowledge_search import (
+from app.agents.chat.multi_agent_chat.shared.filesystem_selection import FilesystemMode
+from app.agents.chat.multi_agent_chat.shared.middleware.knowledge_search import (
     KnowledgePriorityMiddleware,
 )
 from app.services.llm_service import get_planner_llm

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/knowledge_tree/builder.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from langchain_core.language_models import BaseChatModel
 
-from app.agents.multi_agent_chat.shared.filesystem_selection import FilesystemMode
+from app.agents.chat.multi_agent_chat.shared.filesystem_selection import FilesystemMode
 
 from .middleware import KnowledgeTreeMiddleware
 

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/knowledge_tree/middleware.py

@@ -33,14 +33,14 @@ from langchain_core.messages import SystemMessage
 from langgraph.runtime import Runtime
 from sqlalchemy import select
 
-from app.agents.multi_agent_chat.shared.filesystem_selection import FilesystemMode
-from app.agents.multi_agent_chat.shared.path_resolver import (
+from app.agents.chat.multi_agent_chat.shared.filesystem_selection import FilesystemMode
+from app.agents.chat.multi_agent_chat.shared.path_resolver import (
     DOCUMENTS_ROOT,
     PathIndex,
     build_path_index,
     doc_to_virtual_path,
 )
-from app.agents.multi_agent_chat.shared.state.filesystem_state import (
+from app.agents.chat.multi_agent_chat.shared.state.filesystem_state import (
     SurfSenseFilesystemState,
 )
 from app.db import Document, shielded_async_session

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/noop_injection/builder.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
-from app.agents.multi_agent_chat.shared.middleware.flags import enabled
+from app.agents.chat.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
+from app.agents.chat.multi_agent_chat.shared.middleware.flags import enabled
 
 from .middleware import NoopInjectionMiddleware
 

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/otel_span/builder.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
-from app.agents.multi_agent_chat.shared.middleware.flags import enabled
+from app.agents.chat.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
+from app.agents.chat.multi_agent_chat.shared.middleware.flags import enabled
 
 from .middleware import OtelSpanMiddleware
 

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/plugins.py

@@ -7,8 +7,8 @@ from typing import Any
 
 from langchain_core.language_models import BaseChatModel
 
-from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
-from app.agents.multi_agent_chat.shared.middleware.flags import enabled
+from app.agents.chat.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
+from app.agents.chat.multi_agent_chat.shared.middleware.flags import enabled
 from app.db import ChatVisibility
 
 from ..plugins.loader import (

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/skills.py

@@ -6,9 +6,9 @@ import logging
 
 from deepagents.middleware.skills import SkillsMiddleware
 
-from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
-from app.agents.multi_agent_chat.shared.filesystem_selection import FilesystemMode
-from app.agents.multi_agent_chat.shared.middleware.flags import enabled
+from app.agents.chat.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
+from app.agents.chat.multi_agent_chat.shared.filesystem_selection import FilesystemMode
+from app.agents.chat.multi_agent_chat.shared.middleware.flags import enabled
 
 from ..skills.backends import build_skills_backend_factory, default_skills_sources
 

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/stack.py

@@ -20,38 +20,40 @@ from langchain_core.language_models import BaseChatModel
 from langchain_core.tools import BaseTool
 from langgraph.types import Checkpointer
 
-from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
-from app.agents.multi_agent_chat.shared.filesystem_selection import FilesystemMode
-from app.agents.multi_agent_chat.shared.middleware.anthropic_cache import (
+from app.agents.chat.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
+from app.agents.chat.multi_agent_chat.shared.filesystem_selection import FilesystemMode
+from app.agents.chat.multi_agent_chat.shared.middleware.anthropic_cache import (
     build_anthropic_cache_mw,
 )
-from app.agents.multi_agent_chat.shared.middleware.compaction import build_compaction_mw
-from app.agents.multi_agent_chat.shared.middleware.kb_context_projection import (
+from app.agents.chat.multi_agent_chat.shared.middleware.compaction import (
+    build_compaction_mw,
+)
+from app.agents.chat.multi_agent_chat.shared.middleware.kb_context_projection import (
     build_kb_context_projection_mw,
 )
-from app.agents.multi_agent_chat.shared.middleware.memory import build_memory_mw
-from app.agents.multi_agent_chat.shared.middleware.patch_tool_calls import (
+from app.agents.chat.multi_agent_chat.shared.middleware.memory import build_memory_mw
+from app.agents.chat.multi_agent_chat.shared.middleware.patch_tool_calls import (
     build_patch_tool_calls_mw,
 )
-from app.agents.multi_agent_chat.shared.middleware.permissions import (
+from app.agents.chat.multi_agent_chat.shared.middleware.permissions import (
     build_permission_mw,
 )
-from app.agents.multi_agent_chat.shared.middleware.resilience import (
+from app.agents.chat.multi_agent_chat.shared.middleware.resilience import (
     build_resilience_middlewares,
 )
-from app.agents.multi_agent_chat.shared.middleware.todos import build_todos_mw
-from app.agents.multi_agent_chat.subagents import (
+from app.agents.chat.multi_agent_chat.shared.middleware.todos import build_todos_mw
+from app.agents.chat.multi_agent_chat.subagents import (
     build_subagents,
     get_subagents_to_exclude,
 )
-from app.agents.multi_agent_chat.subagents.builtins.knowledge_base.agent import (
+from app.agents.chat.multi_agent_chat.subagents.builtins.knowledge_base.agent import (
     READONLY_NAME as KB_READONLY_NAME,
     build_readonly_subagent as build_kb_readonly_subagent,
 )
-from app.agents.multi_agent_chat.subagents.builtins.knowledge_base.ask_knowledge_base_tool import (
+from app.agents.chat.multi_agent_chat.subagents.builtins.knowledge_base.ask_knowledge_base_tool import (
     build_ask_knowledge_base_tool,
 )
-from app.agents.multi_agent_chat.subagents.shared.middleware.middleware_stack import (
+from app.agents.chat.multi_agent_chat.subagents.shared.middleware.middleware_stack import (
     build_subagent_middleware_stack,
 )
 from app.db import ChatVisibility

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/tool_call_repair/builder.py

@@ -6,8 +6,8 @@ from collections.abc import Sequence
 
 from langchain_core.tools import BaseTool
 
-from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
-from app.agents.multi_agent_chat.shared.middleware.flags import enabled
+from app.agents.chat.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
+from app.agents.chat.multi_agent_chat.shared.middleware.flags import enabled
 
 from .middleware import ToolCallNameRepairMiddleware
 

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/middleware/tool_call_repair/middleware.py

@@ -120,7 +120,7 @@ class ToolCallNameRepairMiddleware(
         # Stage 2 — invalid fallback
         # Local import keeps the middleware module import-light and avoids any
         # tools <-> middleware import-order coupling at module scope.
-        from app.agents.multi_agent_chat.main_agent.tools.invalid_tool import (
+        from app.agents.chat.multi_agent_chat.main_agent.tools.invalid_tool import (
             INVALID_TOOL_NAME,
         )
 

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/plugins/year_substituter.py

@@ -17,7 +17,7 @@ Wire-up in ``pyproject.toml`` (illustrative; the in-repo plugin doesn't
 need this -- it's already on the import path)::
 
     [project.entry-points."surfsense.plugins"]
-    year_substituter = "app.agents.multi_agent_chat.main_agent.plugins.year_substituter:make_middleware"
+    year_substituter = "app.agents.chat.multi_agent_chat.main_agent.plugins.year_substituter:make_middleware"
 """
 
 from __future__ import annotations

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/runtime/agent_cache.py

@@ -10,8 +10,8 @@ from langchain_core.language_models import BaseChatModel
 from langchain_core.tools import BaseTool
 from langgraph.types import Checkpointer
 
-from app.agents.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
-from app.agents.multi_agent_chat.shared.filesystem_selection import FilesystemMode
+from app.agents.chat.multi_agent_chat.shared.feature_flags import AgentFeatureFlags
+from app.agents.chat.multi_agent_chat.shared.filesystem_selection import FilesystemMode
 from app.db import ChatVisibility
 
 from ..graph.compile_graph_sync import build_compiled_agent_graph_sync

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

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

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

@@ -47,7 +47,7 @@ from deepagents.backends.state import StateBackend
 if TYPE_CHECKING:
     from langchain.tools import ToolRuntime
 
-    from app.agents.multi_agent_chat.shared.middleware.filesystem.backends.kb_postgres import (
+    from app.agents.chat.multi_agent_chat.shared.middleware.filesystem.backends.kb_postgres import (
         KBPostgresBackend,
     )
 
@@ -310,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.multi_agent_chat.shared.middleware.filesystem.backends.kb_postgres import (
+        from app.agents.chat.multi_agent_chat.shared.middleware.filesystem.backends.kb_postgres import (
             KBPostgresBackend,
         )
 

surfsense_backend/app/agents/chat/multi_agent_chat/main_agent/system_prompt/builder/load_md.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from importlib import resources
 
-_PROMPTS_PACKAGE = "app.agents.multi_agent_chat.main_agent.system_prompt.prompts"
+_PROMPTS_PACKAGE = "app.agents.chat.multi_agent_chat.main_agent.system_prompt.prompts"
 
 
 def read_prompt_md(filename: str) -> str: