test: add agent refactor guardrail suite

surfsense_backend/tests/unit/agents/multi_agent_chat/test_prompt_resources.py

@@ -0,0 +1,59 @@
+"""Guardrail C: package-relative prompt/snippet resources must resolve.
+
+Prompt fragments are loaded by *package name* via ``importlib.resources`` — not
+by import, so the import-all smoke test (guardrail A) cannot see them, and not
+by mocked unit tests. A move that relocates a package without its ``.md`` files,
+or that leaves a hardcoded package string stale, returns an empty string and
+silently degrades the system prompt. These tests assert the resources still
+resolve to non-empty content.
+
+(Builtin skill resources are covered separately by ``test_skills_backends.py``.)
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from app.agents.multi_agent_chat.main_agent.system_prompt.builder.load_md import (
+    read_prompt_md,
+)
+from app.agents.multi_agent_chat.subagents.registry import (
+    SUBAGENT_BUILDERS_BY_NAME,
+    _route_resource_package,
+)
+from app.agents.multi_agent_chat.subagents.shared.md_file_reader import (
+    read_md_file,
+    read_shared_snippet,
+)
+
+pytestmark = pytest.mark.unit
+
+
+@pytest.mark.parametrize("name", sorted(SUBAGENT_BUILDERS_BY_NAME))
+def test_every_subagent_has_description_md(name: str):
+    """Each specialist ships a non-empty ``description.md`` next to its agent."""
+    package = _route_resource_package(SUBAGENT_BUILDERS_BY_NAME[name])
+    assert read_md_file(package, "description").strip(), (
+        f"{name}: description.md missing/empty at package {package}"
+    )
+
+
+# Real fragments under the hardcoded main-agent prompts package, including a
+# nested path — guards both the package string and nested resource resolution.
+@pytest.mark.parametrize(
+    "filename",
+    [
+        "core_behavior.md",
+        "routing.md",
+        "tools/web_search/description.md",
+    ],
+)
+def test_main_agent_prompt_fragments_resolve(filename: str):
+    """Main-agent prompt fragments resolve to non-empty content."""
+    assert read_prompt_md(filename).strip(), f"prompt fragment {filename} is empty"
+
+
+@pytest.mark.parametrize("snippet", ["output_contract_base", "verifiable_handle"])
+def test_shared_snippets_resolve(snippet: str):
+    """Shared subagent snippets resolve from the snippets package."""
+    assert read_shared_snippet(snippet).strip(), f"snippet {snippet} is empty"

surfsense_backend/tests/unit/agents/multi_agent_chat/test_subagent_composition.py

@@ -0,0 +1,72 @@
+"""Guardrail B: the subagent registry composition must stay intact.
+
+A structural move can silently drop, rename, or mis-wire a subagent builder
+(e.g. a forgotten import line). The compiled agent would then quietly lose a
+specialist with no ImportError. This test pins the exact registry contents and
+their cross-references so any such drift fails loudly.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from app.agents.multi_agent_chat.constants import (
+    SUBAGENT_TO_REQUIRED_CONNECTOR_MAP,
+)
+from app.agents.multi_agent_chat.subagents.registry import (
+    SUBAGENT_BUILDERS_BY_NAME,
+)
+
+pytestmark = pytest.mark.unit
+
+# The full specialist roster the main agent composes from: 4 builtins + 15
+# connector routes. Adding/removing a specialist is a deliberate product change
+# and must be reflected here.
+_EXPECTED_SUBAGENTS = frozenset(
+    {
+        "airtable",
+        "calendar",
+        "clickup",
+        "confluence",
+        "deliverables",
+        "discord",
+        "dropbox",
+        "gmail",
+        "google_drive",
+        "jira",
+        "knowledge_base",
+        "linear",
+        "luma",
+        "memory",
+        "notion",
+        "onedrive",
+        "research",
+        "slack",
+        "teams",
+    }
+)
+
+# Specialists that are always available regardless of connected sources, so they
+# carry no required-connector entry.
+_CONNECTORLESS = frozenset({"memory", "research"})
+
+
+def test_registry_contains_exactly_expected_subagents():
+    """No specialist is silently added, dropped, or renamed by a move."""
+    assert set(SUBAGENT_BUILDERS_BY_NAME) == _EXPECTED_SUBAGENTS
+
+
+def test_every_builder_is_callable_route_agent():
+    """Each registry value is a callable defined in its route's ``agent`` module."""
+    for name, builder in SUBAGENT_BUILDERS_BY_NAME.items():
+        assert callable(builder), f"{name} builder is not callable"
+        assert builder.__module__.endswith(".agent"), (
+            f"{name} builder lives in {builder.__module__}, expected a *.agent module"
+        )
+
+
+def test_required_connector_map_covers_connector_subagents():
+    """The connector-gating map stays in lockstep with the registry."""
+    assert set(SUBAGENT_TO_REQUIRED_CONNECTOR_MAP) == (
+        _EXPECTED_SUBAGENTS - _CONNECTORLESS
+    )

surfsense_backend/tests/unit/agents/test_import_all.py

@@ -0,0 +1,53 @@
+"""Guardrail A: every agent module (and its prod entrypoints) must import.
+
+Static reachability analysis and mocked unit tests cannot catch a module that
+fails to import after files move or imports are rewritten. This smoke test
+imports every submodule under ``app.agents`` plus the production entrypoints
+that consume agents, turning a move-time ``ImportError`` into a fast, local CI
+signal instead of a runtime failure in prod.
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+
+import pytest
+
+import app.agents as agents_pkg
+
+pytestmark = pytest.mark.unit
+
+# Prod consumers of app.agents that live OUTSIDE the agents tree; a broken
+# importer here would not be caught by walking app.agents alone.
+_PROD_ENTRYPOINTS = [
+    "app.tasks.chat.streaming.flows.new_chat.orchestrator",
+    "app.tasks.chat.streaming.agent.builder",
+    "app.gateway.agent_invoke",
+    "app.routes.new_chat_routes",
+]
+
+
+def _iter_agent_modules() -> list[str]:
+    names: list[str] = []
+
+    def _record(name: str) -> None:
+        names.append(name)
+
+    for info in pkgutil.walk_packages(
+        agents_pkg.__path__, prefix=agents_pkg.__name__ + ".", onerror=_record
+    ):
+        names.append(info.name)
+    return sorted(set(names))
+
+
+@pytest.mark.parametrize("module_name", _iter_agent_modules())
+def test_agent_module_imports(module_name: str) -> None:
+    """Importing the module must not raise (no broken or missed imports)."""
+    importlib.import_module(module_name)
+
+
+@pytest.mark.parametrize("module_name", _PROD_ENTRYPOINTS)
+def test_prod_entrypoint_imports(module_name: str) -> None:
+    """The production code paths that build/invoke agents must import."""
+    importlib.import_module(module_name)