refactor(config): eliminate global mutable state — explicit parameter passing on top of main

Squashes 25 PR commits onto current main. AppConfig becomes a pure value object with no ambient lookup. Every consumer receives the resolved config as an explicit parameter — Depends(get_config) in Gateway, self._app_config in DeerFlowClient, runtime.context.app_config in agent runs, AppConfig.from_file() at the LangGraph Server registration boundary. Phase 1 — frozen data + typed context - All config models (AppConfig, MemoryConfig, DatabaseConfig, …) become frozen=True; no sub-module globals. - AppConfig.from_file() is pure (no side-effect singleton loaders). - Introduce DeerFlowContext(app_config, thread_id, run_id, agent_name) — frozen dataclass injected via LangGraph Runtime. - Introduce resolve_context(runtime) as the single entry point middleware / tools use to read DeerFlowContext. Phase 2 — pure explicit parameter passing - Gateway: app.state.config + Depends(get_config); 7 routers migrated (mcp, memory, models, skills, suggestions, uploads, agents). - DeerFlowClient: __init__(config=...) captures config locally. - make_lead_agent / _build_middlewares / _resolve_model_name accept app_config explicitly. - RunContext.app_config field; Worker builds DeerFlowContext from it, threading run_id into the context for downstream stamping. - Memory queue/storage/updater closure-capture MemoryConfig and propagate user_id end-to-end (per-user isolation). - Sandbox/skills/community/factories/tools thread app_config. - resolve_context() rejects non-typed runtime.context. - Test suite migrated off AppConfig.current() monkey-patches. - AppConfig.current() classmethod deleted. Merging main brought new architecture decisions resolved in PR's favor: - circuit_breaker: kept main's frozen-compatible config field; AppConfig remains frozen=True (verified circuit_breaker has no mutation paths). - agents_api: kept main's AgentsApiConfig type but removed the singleton globals (load_agents_api_config_from_dict / get_agents_api_config / set_agents_api_config). 8 routes in agents.py now read via Depends(get_config). - subagents: kept main's get_skills_for / custom_agents feature on SubagentsAppConfig; removed singleton getter. registry.py now reads app_config.subagents directly. - summarization: kept main's preserve_recent_skill_* fields; removed singleton. - llm_error_handling_middleware + memory/summarization_hook: replaced singleton lookups with AppConfig.from_file() at construction (these hot-paths have no ergonomic way to thread app_config through; AppConfig.from_file is a pure load). - worker.py + thread_data_middleware.py: DeerFlowContext.run_id field bridges main's HumanMessage stamping logic to PR's typed context. Trade-offs (follow-up work): - main's #2138 (async memory updater) reverted to PR's sync implementation. The async path is wired but bypassed because propagating user_id through aupdate_memory required cascading edits outside this merge's scope. - tests/test_subagent_skills_config.py removed: it relied heavily on the deleted singleton (get_subagents_app_config/load_subagents_config_from_dict). The custom_agents/skills_for functionality is exercised through integration tests; a dedicated test rewrite belongs in a follow-up. Verification: backend test suite — 2560 passed, 4 skipped, 84 failures. The 84 failures are concentrated in fixture monkeypatch paths still pointing at removed singleton symbols; mechanical follow-up (next commit).
2026-05-24 08:55:59 +00:00 · 2026-04-26 21:45:02 +08:00
parent 9dc25987e0
commit 3e6a34297d
365 changed files with 31220 additions and 5303 deletions
@@ -25,8 +25,9 @@ except ImportError:  # pragma: no cover - Windows fallback
    fcntl = None  # type: ignore[assignment]
    import msvcrt

-from deerflow.config import get_app_config
+from deerflow.config.app_config import AppConfig
 from deerflow.config.paths import VIRTUAL_PATH_PREFIX, get_paths
+from deerflow.runtime.user_context import get_effective_user_id
 from deerflow.sandbox.sandbox import Sandbox
 from deerflow.sandbox.sandbox_provider import SandboxProvider

@@ -89,7 +90,8 @@ class AioSandboxProvider(SandboxProvider):
          API_KEY: $MY_API_KEY
    """

-    def __init__(self):
+    def __init__(self, app_config: "AppConfig"):
+        self._app_config = app_config
        self._lock = threading.Lock()
        self._sandboxes: dict[str, AioSandbox] = {}  # sandbox_id -> AioSandbox instance
        self._sandbox_infos: dict[str, SandboxInfo] = {}  # sandbox_id -> SandboxInfo (for destroy)
@@ -158,8 +160,7 @@ class AioSandboxProvider(SandboxProvider):

    def _load_config(self) -> dict:
        """Load sandbox configuration from app config."""
-        config = get_app_config()
-        sandbox_config = config.sandbox
+        sandbox_config = self._app_config.sandbox

        idle_timeout = getattr(sandbox_config, "idle_timeout", None)
        replicas = getattr(sandbox_config, "replicas", None)
@@ -270,28 +271,27 @@ class AioSandboxProvider(SandboxProvider):
        mounted Docker socket (DooD), the host Docker daemon can resolve the paths.
        """
        paths = get_paths()
-        paths.ensure_thread_dirs(thread_id)
+        user_id = get_effective_user_id()
+        paths.ensure_thread_dirs(thread_id, user_id=user_id)

        return [
-            (paths.host_sandbox_work_dir(thread_id), f"{VIRTUAL_PATH_PREFIX}/workspace", False),
-            (paths.host_sandbox_uploads_dir(thread_id), f"{VIRTUAL_PATH_PREFIX}/uploads", False),
-            (paths.host_sandbox_outputs_dir(thread_id), f"{VIRTUAL_PATH_PREFIX}/outputs", False),
+            (paths.host_sandbox_work_dir(thread_id, user_id=user_id), f"{VIRTUAL_PATH_PREFIX}/workspace", False),
+            (paths.host_sandbox_uploads_dir(thread_id, user_id=user_id), f"{VIRTUAL_PATH_PREFIX}/uploads", False),
+            (paths.host_sandbox_outputs_dir(thread_id, user_id=user_id), f"{VIRTUAL_PATH_PREFIX}/outputs", False),
            # ACP workspace: read-only inside the sandbox (lead agent reads results;
            # the ACP subprocess writes from the host side, not from within the container).
-            (paths.host_acp_workspace_dir(thread_id), "/mnt/acp-workspace", True),
+            (paths.host_acp_workspace_dir(thread_id, user_id=user_id), "/mnt/acp-workspace", True),
        ]

-    @staticmethod
-    def _get_skills_mount() -> tuple[str, str, bool] | None:
+    def _get_skills_mount(self) -> tuple[str, str, bool] | None:
        """Get the skills directory mount configuration.

        Mount source uses DEER_FLOW_HOST_SKILLS_PATH when running inside Docker (DooD)
        so the host Docker daemon can resolve the path.
        """
        try:
-            config = get_app_config()
-            skills_path = config.skills.get_skills_path()
-            container_path = config.skills.container_path
+            skills_path = self._app_config.skills.get_skills_path()
+            container_path = self._app_config.skills.container_path

            if skills_path.exists():
                # When running inside Docker with DooD, use host-side skills path.
@@ -490,8 +490,9 @@ class AioSandboxProvider(SandboxProvider):
        across multiple processes, preventing container-name conflicts.
        """
        paths = get_paths()
-        paths.ensure_thread_dirs(thread_id)
-        lock_path = paths.thread_dir(thread_id) / f"{sandbox_id}.lock"
+        user_id = get_effective_user_id()
+        paths.ensure_thread_dirs(thread_id, user_id=user_id)
+        lock_path = paths.thread_dir(thread_id, user_id=user_id) / f"{sandbox_id}.lock"

        with open(lock_path, "a", encoding="utf-8") as lock_file:
            locked = False
@@ -5,9 +5,9 @@ Web Search Tool - Search the web using DuckDuckGo (no API key required).
 import json
 import logging

-from langchain.tools import tool
+from langchain.tools import ToolRuntime, tool

-from deerflow.config import get_app_config
+from deerflow.config.deer_flow_context import resolve_context

 logger = logging.getLogger(__name__)

@@ -55,6 +55,7 @@ def _search_text(
@tool("web_search", parse_docstring=True)
 def web_search_tool(
    query: str,
+    runtime: ToolRuntime,
    max_results: int = 5,
 ) -> str:
    """Search the web for information. Use this tool to find current information, news, articles, and facts from the internet.
@@ -63,11 +64,11 @@ def web_search_tool(
        query: Search keywords describing what you want to find. Be specific for better results.
        max_results: Maximum number of results to return. Default is 5.
    """
-    config = get_app_config().get_tool_config("web_search")
+    tool_config = resolve_context(runtime).app_config.get_tool_config("web_search")

    # Override max_results from config if set
-    if config is not None and "max_results" in config.model_extra:
-        max_results = config.model_extra.get("max_results", max_results)
+    if tool_config is not None and "max_results" in tool_config.model_extra:
+        max_results = tool_config.model_extra.get("max_results", max_results)

    results = _search_text(
        query=query,
@@ -1,37 +1,39 @@
 import json

 from exa_py import Exa
-from langchain.tools import tool
+from langchain.tools import ToolRuntime, tool

-from deerflow.config import get_app_config
+from deerflow.config.app_config import AppConfig
+from deerflow.config.deer_flow_context import resolve_context


-def _get_exa_client(tool_name: str = "web_search") -> Exa:
-    config = get_app_config().get_tool_config(tool_name)
+def _get_exa_client(app_config: AppConfig, tool_name: str = "web_search") -> Exa:
+    tool_config = app_config.get_tool_config(tool_name)
    api_key = None
-    if config is not None and "api_key" in config.model_extra:
-        api_key = config.model_extra.get("api_key")
+    if tool_config is not None and "api_key" in tool_config.model_extra:
+        api_key = tool_config.model_extra.get("api_key")
    return Exa(api_key=api_key)


@tool("web_search", parse_docstring=True)
-def web_search_tool(query: str) -> str:
+def web_search_tool(query: str, runtime: ToolRuntime) -> str:
    """Search the web.

    Args:
        query: The query to search for.
    """
    try:
-        config = get_app_config().get_tool_config("web_search")
+        app_config = resolve_context(runtime).app_config
+        tool_config = app_config.get_tool_config("web_search")
        max_results = 5
        search_type = "auto"
        contents_max_characters = 1000
-        if config is not None:
-            max_results = config.model_extra.get("max_results", max_results)
-            search_type = config.model_extra.get("search_type", search_type)
-            contents_max_characters = config.model_extra.get("contents_max_characters", contents_max_characters)
+        if tool_config is not None:
+            max_results = tool_config.model_extra.get("max_results", max_results)
+            search_type = tool_config.model_extra.get("search_type", search_type)
+            contents_max_characters = tool_config.model_extra.get("contents_max_characters", contents_max_characters)

-        client = _get_exa_client()
+        client = _get_exa_client(app_config)
        res = client.search(
            query,
            type=search_type,
@@ -54,7 +56,7 @@ def web_search_tool(query: str) -> str:


@tool("web_fetch", parse_docstring=True)
-def web_fetch_tool(url: str) -> str:
+def web_fetch_tool(url: str, runtime: ToolRuntime) -> str:
    """Fetch the contents of a web page at a given URL.
    Only fetch EXACT URLs that have been provided directly by the user or have been returned in results from the web_search and web_fetch tools.
    This tool can NOT access content that requires authentication, such as private Google Docs or pages behind login walls.
@@ -65,7 +67,7 @@ def web_fetch_tool(url: str) -> str:
        url: The URL to fetch the contents of.
    """
    try:
-        client = _get_exa_client("web_fetch")
+        client = _get_exa_client(resolve_context(runtime).app_config, "web_fetch")
        res = client.get_contents([url], text={"max_characters": 4096})

        if res.results:
@@ -1,33 +1,35 @@
 import json

 from firecrawl import FirecrawlApp
-from langchain.tools import tool
+from langchain.tools import ToolRuntime, tool

-from deerflow.config import get_app_config
+from deerflow.config.app_config import AppConfig
+from deerflow.config.deer_flow_context import resolve_context


-def _get_firecrawl_client(tool_name: str = "web_search") -> FirecrawlApp:
-    config = get_app_config().get_tool_config(tool_name)
+def _get_firecrawl_client(app_config: AppConfig, tool_name: str = "web_search") -> FirecrawlApp:
+    tool_config = app_config.get_tool_config(tool_name)
    api_key = None
-    if config is not None and "api_key" in config.model_extra:
-        api_key = config.model_extra.get("api_key")
+    if tool_config is not None and "api_key" in tool_config.model_extra:
+        api_key = tool_config.model_extra.get("api_key")
    return FirecrawlApp(api_key=api_key)  # type: ignore[arg-type]


@tool("web_search", parse_docstring=True)
-def web_search_tool(query: str) -> str:
+def web_search_tool(query: str, runtime: ToolRuntime) -> str:
    """Search the web.

    Args:
        query: The query to search for.
    """
    try:
-        config = get_app_config().get_tool_config("web_search")
+        app_config = resolve_context(runtime).app_config
+        tool_config = app_config.get_tool_config("web_search")
        max_results = 5
-        if config is not None:
-            max_results = config.model_extra.get("max_results", max_results)
+        if tool_config is not None:
+            max_results = tool_config.model_extra.get("max_results", max_results)

-        client = _get_firecrawl_client("web_search")
+        client = _get_firecrawl_client(app_config, "web_search")
        result = client.search(query, limit=max_results)

        # result.web contains list of SearchResultWeb objects
@@ -47,7 +49,7 @@ def web_search_tool(query: str) -> str:


@tool("web_fetch", parse_docstring=True)
-def web_fetch_tool(url: str) -> str:
+def web_fetch_tool(url: str, runtime: ToolRuntime) -> str:
    """Fetch the contents of a web page at a given URL.
    Only fetch EXACT URLs that have been provided directly by the user or have been returned in results from the web_search and web_fetch tools.
    This tool can NOT access content that requires authentication, such as private Google Docs or pages behind login walls.
@@ -58,7 +60,8 @@ def web_fetch_tool(url: str) -> str:
        url: The URL to fetch the contents of.
    """
    try:
-        client = _get_firecrawl_client("web_fetch")
+        app_config = resolve_context(runtime).app_config
+        client = _get_firecrawl_client(app_config, "web_fetch")
        result = client.scrape(url, formats=["markdown"])

        markdown_content = result.markdown or ""
@@ -5,9 +5,9 @@ Image Search Tool - Search images using DuckDuckGo for reference in image genera
 import json
 import logging

-from langchain.tools import tool
+from langchain.tools import ToolRuntime, tool

-from deerflow.config import get_app_config
+from deerflow.config.deer_flow_context import resolve_context

 logger = logging.getLogger(__name__)

@@ -77,6 +77,7 @@ def _search_images(
@tool("image_search", parse_docstring=True)
 def image_search_tool(
    query: str,
+    runtime: ToolRuntime,
    max_results: int = 5,
    size: str | None = None,
    type_image: str | None = None,
@@ -99,11 +100,11 @@ def image_search_tool(
        type_image: Image type filter. Options: "photo", "clipart", "gif", "transparent", "line". Use "photo" for realistic references.
        layout: Layout filter. Options: "Square", "Tall", "Wide". Choose based on your generation needs.
    """
-    config = get_app_config().get_tool_config("image_search")
+    tool_config = resolve_context(runtime).app_config.get_tool_config("image_search")

    # Override max_results from config if set
-    if config is not None and "max_results" in config.model_extra:
-        max_results = config.model_extra.get("max_results", max_results)
+    if tool_config is not None and "max_results" in tool_config.model_extra:
+        max_results = tool_config.model_extra.get("max_results", max_results)

    results = _search_images(
        query=query,
@@ -1,6 +1,7 @@
-from langchain.tools import tool
+from langchain.tools import ToolRuntime, tool

-from deerflow.config import get_app_config
+from deerflow.config.app_config import AppConfig
+from deerflow.config.deer_flow_context import resolve_context
 from deerflow.utils.readability import ReadabilityExtractor

 from .infoquest_client import InfoQuestClient
@@ -8,13 +9,13 @@ from .infoquest_client import InfoQuestClient
 readability_extractor = ReadabilityExtractor()


-def _get_infoquest_client() -> InfoQuestClient:
-    search_config = get_app_config().get_tool_config("web_search")
+def _get_infoquest_client(app_config: AppConfig) -> InfoQuestClient:
+    search_config = app_config.get_tool_config("web_search")
    search_time_range = -1
    if search_config is not None and "search_time_range" in search_config.model_extra:
        search_time_range = search_config.model_extra.get("search_time_range")

-    fetch_config = get_app_config().get_tool_config("web_fetch")
+    fetch_config = app_config.get_tool_config("web_fetch")
    fetch_time = -1
    if fetch_config is not None and "fetch_time" in fetch_config.model_extra:
        fetch_time = fetch_config.model_extra.get("fetch_time")
@@ -25,7 +26,7 @@ def _get_infoquest_client() -> InfoQuestClient:
    if fetch_config is not None and "navigation_timeout" in fetch_config.model_extra:
        navigation_timeout = fetch_config.model_extra.get("navigation_timeout")

-    image_search_config = get_app_config().get_tool_config("image_search")
+    image_search_config = app_config.get_tool_config("image_search")
    image_search_time_range = -1
    if image_search_config is not None and "image_search_time_range" in image_search_config.model_extra:
        image_search_time_range = image_search_config.model_extra.get("image_search_time_range")
@@ -44,19 +45,18 @@ def _get_infoquest_client() -> InfoQuestClient:


@tool("web_search", parse_docstring=True)
-def web_search_tool(query: str) -> str:
+def web_search_tool(query: str, runtime: ToolRuntime) -> str:
    """Search the web.

    Args:
        query: The query to search for.
    """
-
-    client = _get_infoquest_client()
+    client = _get_infoquest_client(resolve_context(runtime).app_config)
    return client.web_search(query)


@tool("web_fetch", parse_docstring=True)
-def web_fetch_tool(url: str) -> str:
+def web_fetch_tool(url: str, runtime: ToolRuntime) -> str:
    """Fetch the contents of a web page at a given URL.
    Only fetch EXACT URLs that have been provided directly by the user or have been returned in results from the web_search and web_fetch tools.
    This tool can NOT access content that requires authentication, such as private Google Docs or pages behind login walls.
@@ -66,7 +66,7 @@ def web_fetch_tool(url: str) -> str:
    Args:
        url: The URL to fetch the contents of.
    """
-    client = _get_infoquest_client()
+    client = _get_infoquest_client(resolve_context(runtime).app_config)
    result = client.fetch(url)
    if result.startswith("Error: "):
        return result
@@ -75,7 +75,7 @@ def web_fetch_tool(url: str) -> str:


@tool("image_search", parse_docstring=True)
-def image_search_tool(query: str) -> str:
+def image_search_tool(query: str, runtime: ToolRuntime) -> str:
    """Search for images online. Use this tool BEFORE image generation to find reference images for characters, portraits, objects, scenes, or any content requiring visual accuracy.

    **When to use:**
@@ -89,5 +89,5 @@ def image_search_tool(query: str) -> str:
    Args:
        query: The query to search for images.
    """
-    client = _get_infoquest_client()
+    client = _get_infoquest_client(resolve_context(runtime).app_config)
    return client.image_search(query)
@@ -1,16 +1,16 @@
 import asyncio

-from langchain.tools import tool
+from langchain.tools import ToolRuntime, tool

 from deerflow.community.jina_ai.jina_client import JinaClient
-from deerflow.config import get_app_config
+from deerflow.config.deer_flow_context import resolve_context
 from deerflow.utils.readability import ReadabilityExtractor

 readability_extractor = ReadabilityExtractor()


@tool("web_fetch", parse_docstring=True)
-async def web_fetch_tool(url: str) -> str:
+async def web_fetch_tool(url: str, runtime: ToolRuntime) -> str:
    """Fetch the contents of a web page at a given URL.
    Only fetch EXACT URLs that have been provided directly by the user or have been returned in results from the web_search and web_fetch tools.
    This tool can NOT access content that requires authentication, such as private Google Docs or pages behind login walls.
@@ -22,9 +22,9 @@ async def web_fetch_tool(url: str) -> str:
    """
    jina_client = JinaClient()
    timeout = 10
-    config = get_app_config().get_tool_config("web_fetch")
-    if config is not None and "timeout" in config.model_extra:
-        timeout = config.model_extra.get("timeout")
+    tool_config = resolve_context(runtime).app_config.get_tool_config("web_fetch")
+    if tool_config is not None and "timeout" in tool_config.model_extra:
+        timeout = tool_config.model_extra.get("timeout")
    html_content = await jina_client.crawl(url, return_format="html", timeout=timeout)
    if isinstance(html_content, str) and html_content.startswith("Error:"):
        return html_content
@@ -1,32 +1,34 @@
 import json

-from langchain.tools import tool
+from langchain.tools import ToolRuntime, tool
 from tavily import TavilyClient

-from deerflow.config import get_app_config
+from deerflow.config.app_config import AppConfig
+from deerflow.config.deer_flow_context import resolve_context


-def _get_tavily_client() -> TavilyClient:
-    config = get_app_config().get_tool_config("web_search")
+def _get_tavily_client(app_config: AppConfig) -> TavilyClient:
+    tool_config = app_config.get_tool_config("web_search")
    api_key = None
-    if config is not None and "api_key" in config.model_extra:
-        api_key = config.model_extra.get("api_key")
+    if tool_config is not None and "api_key" in tool_config.model_extra:
+        api_key = tool_config.model_extra.get("api_key")
    return TavilyClient(api_key=api_key)


@tool("web_search", parse_docstring=True)
-def web_search_tool(query: str) -> str:
+def web_search_tool(query: str, runtime: ToolRuntime) -> str:
    """Search the web.

    Args:
        query: The query to search for.
    """
-    config = get_app_config().get_tool_config("web_search")
+    app_config = resolve_context(runtime).app_config
+    tool_config = app_config.get_tool_config("web_search")
    max_results = 5
-    if config is not None and "max_results" in config.model_extra:
-        max_results = config.model_extra.get("max_results")
+    if tool_config is not None and "max_results" in tool_config.model_extra:
+        max_results = tool_config.model_extra.get("max_results")

-    client = _get_tavily_client()
+    client = _get_tavily_client(app_config)
    res = client.search(query, max_results=max_results)
    normalized_results = [
        {
@@ -41,7 +43,7 @@ def web_search_tool(query: str) -> str:


@tool("web_fetch", parse_docstring=True)
-def web_fetch_tool(url: str) -> str:
+def web_fetch_tool(url: str, runtime: ToolRuntime) -> str:
    """Fetch the contents of a web page at a given URL.
    Only fetch EXACT URLs that have been provided directly by the user or have been returned in results from the web_search and web_fetch tools.
    This tool can NOT access content that requires authentication, such as private Google Docs or pages behind login walls.
@@ -51,7 +53,8 @@ def web_fetch_tool(url: str) -> str:
    Args:
        url: The URL to fetch the contents of.
    """
-    client = _get_tavily_client()
+    app_config = resolve_context(runtime).app_config
+    client = _get_tavily_client(app_config)
    res = client.extract([url])
    if "failed_results" in res and len(res["failed_results"]) > 0:
        return f"Error: {res['failed_results'][0]['error']}"