feat(chat): add multi-agent mode routing scaffold and telemetry.

surfsense_backend/app/agents/new_chat/architecture_mode.py

@@ -0,0 +1,40 @@
+"""Architecture mode contracts and resolution helpers for chat sessions."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from app.config import config
+
+
+class ArchitectureMode(StrEnum):
+    SINGLE_AGENT = "single_agent"
+    SHADOW_MULTI_AGENT_V1 = "shadow_multi_agent_v1"
+    MULTI_AGENT_V1 = "multi_agent_v1"
+
+
+def parse_architecture_mode(value: str | None) -> ArchitectureMode | None:
+    if not value:
+        return None
+    normalized = value.strip().lower()
+    if not normalized:
+        return None
+    try:
+        return ArchitectureMode(normalized)
+    except ValueError:
+        return None
+
+
+def resolve_architecture_mode(request_override: str | None = None) -> ArchitectureMode:
+    if config.FORCE_SINGLE_AGENT:
+        return ArchitectureMode.SINGLE_AGENT
+
+    override_mode = parse_architecture_mode(request_override)
+    if override_mode is not None:
+        return override_mode
+
+    default_mode = parse_architecture_mode(config.AGENT_ARCHITECTURE_MODE)
+    if default_mode is not None:
+        return default_mode
+
+    return ArchitectureMode.SINGLE_AGENT

surfsense_backend/app/agents/new_chat/telemetry.py

@@ -0,0 +1,43 @@
+"""Architecture telemetry logging for chat execution modes."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from app.utils.perf import get_perf_logger
+
+_perf_log = get_perf_logger()
+
+
+def log_architecture_telemetry(
+    *,
+    phase: str,
+    architecture_mode: str,
+    orchestrator_used: bool,
+    worker_count: int,
+    retry_count: int,
+    latency_ms: float,
+    token_total: int,
+    request_id: str | None = None,
+    turn_id: str | None = None,
+    status: str = "ok",
+    source: str = "new_chat",
+    extra: dict[str, Any] | None = None,
+) -> None:
+    payload: dict[str, Any] = {
+        "phase": phase,
+        "source": source,
+        "status": status,
+        "architecture_mode": architecture_mode,
+        "orchestrator_used": orchestrator_used,
+        "worker_count": worker_count,
+        "retry_count": retry_count,
+        "latency_ms": round(latency_ms, 2),
+        "token_total": token_total,
+        "request_id": request_id or "unknown",
+        "turn_id": turn_id or "unknown",
+    }
+    if extra:
+        payload.update(extra)
+    _perf_log.info("[architecture_telemetry] %s", json.dumps(payload, ensure_ascii=False))