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

surfsense_backend/app/agents/multi_agent_v1/__init__.py

@@ -0,0 +1,17 @@
+"""Multi-agent v1 architecture package."""
+
+from app.agents.multi_agent_v1.contracts import (
+    GroundingEvidence,
+    SubagentResult,
+    SubagentTaskPlan,
+    WorkerBudget,
+)
+from app.agents.multi_agent_v1.entrypoint import MultiAgentEntrypoint
+
+__all__ = [
+    "GroundingEvidence",
+    "MultiAgentEntrypoint",
+    "SubagentResult",
+    "SubagentTaskPlan",
+    "WorkerBudget",
+]

surfsense_backend/app/agents/multi_agent_v1/contracts.py

@@ -0,0 +1,36 @@
+"""Contracts for multi_agent_v1 orchestrator and subagent communication."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class WorkerBudget(BaseModel):
+    max_steps: int = Field(default=1, ge=1)
+    max_duration_ms: int = Field(default=15_000, ge=100)
+
+
+class SubagentTaskPlan(BaseModel):
+    domain: str = Field(..., min_length=1)
+    goal: str = Field(..., min_length=1)
+    constraints: list[str] = Field(default_factory=list)
+    budget: WorkerBudget = Field(default_factory=WorkerBudget)
+
+
+class GroundingEvidence(BaseModel):
+    claim: str = Field(..., min_length=1)
+    source_type: str = Field(..., min_length=1)
+    source_ref: str = Field(..., min_length=1)
+    confidence: float = Field(default=0.0, ge=0.0, le=1.0)
+    snippet: str = ""
+
+
+class SubagentResult(BaseModel):
+    status: Literal["success", "partial", "error"]
+    summary: str = ""
+    evidence: list[GroundingEvidence] = Field(default_factory=list)
+    artifacts: list[str] = Field(default_factory=list)
+    needs_human: bool = False
+    error_class: str | None = None

surfsense_backend/app/agents/multi_agent_v1/entrypoint.py

@@ -0,0 +1,24 @@
+"""Multi-agent v1 entrypoint scaffold with safe fallback behavior."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Callable
+from typing import Any
+
+
+class MultiAgentEntrypoint:
+    def stream_new_chat(
+        self,
+        *,
+        fallback_streamer: Callable[..., AsyncGenerator[str, None]],
+        fallback_kwargs: dict[str, Any],
+    ) -> AsyncGenerator[str, None]:
+        return fallback_streamer(**fallback_kwargs)
+
+    def stream_resume_chat(
+        self,
+        *,
+        fallback_streamer: Callable[..., AsyncGenerator[str, None]],
+        fallback_kwargs: dict[str, Any],
+    ) -> AsyncGenerator[str, None]:
+        return fallback_streamer(**fallback_kwargs)