fix(tools): introduce Runtime type alias to eliminate Pydantic serialization warning (#2774)

* fix(tools): introduce Runtime type alias to eliminate Pydantic serialization warning Add deerflow/tools/types.py with: Runtime = ToolRuntime[dict[str, Any], ThreadState] Replace every runtime: ToolRuntime[ContextT, ThreadState] and runtime: ToolRuntime[dict[str, Any], ThreadState] annotation in sandbox/tools.py, present_file_tool.py, task_tool.py, view_image_tool.py, and skill_manage_tool.py with the new Runtime alias. The unbound ContextT TypeVar (default None) caused PydanticSerializationUnexpectedValue warnings on every tool call because LangChain's BaseTool._parse_input calls model_dump() on the auto-generated args_schema while DeerFlow passes a dict as runtime context. Binding the context to dict[str, Any] aligns Pydantic's serialization expectations with reality and removes the noise from all run modes. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com> * fix(tools): extend Runtime alias to setup_agent and update_agent tools Replace bare ToolRuntime annotations in setup_agent_tool.py and update_agent_tool.py with the shared Runtime alias introduced in the previous commit, and add both tools to the Pydantic serialization warning regression test (13 cases total). Co-authored-by: Cursor <cursoragent@cursor.com> * test(tools): loosen Pydantic warning filter to avoid version-specific format Replace the brittle "field_name='context'" substring check with a looser "context" match so the assertion stays valid if Pydantic changes its internal warning format across versions. Co-authored-by: Cursor <cursoragent@cursor.com> * test(tools): simplify warning filter and clean up docstring Remove the "context" substring condition from the Pydantic warning filter — asserting that no PydanticSerializationUnexpectedValue fires at all is both simpler and more comprehensive, since the test payload contains only the tool's own args plus runtime. Also update the module docstring to remove the version-specific warning format example that was inconsistent with the looser filter. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-24 17:06:00 +00:00 · 2026-05-08 14:50:33 +08:00
parent 37db689349
commit 7de9b5828b
9 changed files with 139 additions and 40 deletions
@@ -3,10 +3,9 @@ import re
 import shlex
 from pathlib import Path

-from langchain.tools import ToolRuntime, tool
-from langgraph.typing import ContextT
+from langchain.tools import tool

-from deerflow.agents.thread_state import ThreadDataState, ThreadState
+from deerflow.agents.thread_state import ThreadDataState
 from deerflow.config import get_app_config
 from deerflow.config.paths import VIRTUAL_PATH_PREFIX
 from deerflow.sandbox.exceptions import (
@@ -19,6 +18,7 @@ from deerflow.sandbox.sandbox import Sandbox
 from deerflow.sandbox.sandbox_provider import get_sandbox_provider
 from deerflow.sandbox.search import GrepMatch
 from deerflow.sandbox.security import LOCAL_HOST_BASH_DISABLED_MESSAGE, is_host_bash_allowed
+from deerflow.tools.types import Runtime

 _ABSOLUTE_PATH_PATTERN = re.compile(r"(?<![:\w])(?<!:/)/(?:[^\s\"'`;&|<>()]+)")
 _FILE_URL_PATTERN = re.compile(r"\bfile://\S+", re.IGNORECASE)
@@ -419,7 +419,7 @@ def _join_path_preserving_style(base: str, relative: str) -> str:
    return f"{stripped_base}{separator}{normalized_relative}"


-def _sanitize_error(error: Exception, runtime: "ToolRuntime[ContextT, ThreadState] | None" = None) -> str:
+def _sanitize_error(error: Exception, runtime: Runtime | None = None) -> str:
    """Sanitize an error message to avoid leaking host filesystem paths.

    In local-sandbox mode, resolved host paths in the error string are masked
@@ -994,7 +994,7 @@ def _apply_cwd_prefix(command: str, thread_data: ThreadDataState | None) -> str:
    return command


-def get_thread_data(runtime: ToolRuntime[ContextT, ThreadState] | None) -> ThreadDataState | None:
+def get_thread_data(runtime: Runtime | None) -> ThreadDataState | None:
    """Extract thread_data from runtime state."""
    if runtime is None:
        return None
@@ -1003,7 +1003,7 @@ def get_thread_data(runtime: ToolRuntime[ContextT, ThreadState] | None) -> Threa
    return runtime.state.get("thread_data")


-def is_local_sandbox(runtime: ToolRuntime[ContextT, ThreadState] | None) -> bool:
+def is_local_sandbox(runtime: Runtime | None) -> bool:
    """Check if the current sandbox is a local sandbox.

    Path replacement is only needed for local sandbox since aio sandbox
@@ -1019,7 +1019,7 @@ def is_local_sandbox(runtime: ToolRuntime[ContextT, ThreadState] | None) -> bool
    return sandbox_state.get("sandbox_id") == "local"


-def sandbox_from_runtime(runtime: ToolRuntime[ContextT, ThreadState] | None = None) -> Sandbox:
+def sandbox_from_runtime(runtime: Runtime | None = None) -> Sandbox:
    """Extract sandbox instance from tool runtime.

    DEPRECATED: Use ensure_sandbox_initialized() for lazy initialization support.
@@ -1048,7 +1048,7 @@ def sandbox_from_runtime(runtime: ToolRuntime[ContextT, ThreadState] | None = No
    return sandbox


-def ensure_sandbox_initialized(runtime: ToolRuntime[ContextT, ThreadState] | None = None) -> Sandbox:
+def ensure_sandbox_initialized(runtime: Runtime | None = None) -> Sandbox:
    """Ensure sandbox is initialized, acquiring lazily if needed.

    On first call, acquires a sandbox from the provider and stores it in runtime state.
@@ -1107,7 +1107,7 @@ def ensure_sandbox_initialized(runtime: ToolRuntime[ContextT, ThreadState] | Non
    return sandbox


-def ensure_thread_directories_exist(runtime: ToolRuntime[ContextT, ThreadState] | None) -> None:
+def ensure_thread_directories_exist(runtime: Runtime | None) -> None:
    """Ensure thread data directories (workspace, uploads, outputs) exist.

    This function is called lazily when any sandbox tool is first used.
@@ -1221,7 +1221,7 @@ def _truncate_ls_output(output: str, max_chars: int) -> str:


@tool("bash", parse_docstring=True)
-def bash_tool(runtime: ToolRuntime[ContextT, ThreadState], description: str, command: str) -> str:
+def bash_tool(runtime: Runtime, description: str, command: str) -> str:
    """Execute a bash command in a Linux environment.


@@ -1270,7 +1270,7 @@ def bash_tool(runtime: ToolRuntime[ContextT, ThreadState], description: str, com


@tool("ls", parse_docstring=True)
-def ls_tool(runtime: ToolRuntime[ContextT, ThreadState], description: str, path: str) -> str:
+def ls_tool(runtime: Runtime, description: str, path: str) -> str:
    """List the contents of a directory up to 2 levels deep in tree format.

    Args:
@@ -1318,7 +1318,7 @@ def ls_tool(runtime: ToolRuntime[ContextT, ThreadState], description: str, path:

@tool("glob", parse_docstring=True)
 def glob_tool(
-    runtime: ToolRuntime[ContextT, ThreadState],
+    runtime: Runtime,
    description: str,
    pattern: str,
    path: str,
@@ -1368,7 +1368,7 @@ def glob_tool(

@tool("grep", parse_docstring=True)
 def grep_tool(
-    runtime: ToolRuntime[ContextT, ThreadState],
+    runtime: Runtime,
    description: str,
    pattern: str,
    path: str,
@@ -1438,7 +1438,7 @@ def grep_tool(

@tool("read_file", parse_docstring=True)
 def read_file_tool(
-    runtime: ToolRuntime[ContextT, ThreadState],
+    runtime: Runtime,
    description: str,
    path: str,
    start_line: int | None = None,
@@ -1493,7 +1493,7 @@ def read_file_tool(

@tool("write_file", parse_docstring=True)
 def write_file_tool(
-    runtime: ToolRuntime[ContextT, ThreadState],
+    runtime: Runtime,
    description: str,
    path: str,
    content: str,
@@ -1533,7 +1533,7 @@ def write_file_tool(

@tool("str_replace", parse_docstring=True)
 def str_replace_tool(
-    runtime: ToolRuntime[ContextT, ThreadState],
+    runtime: Runtime,
    description: str,
    path: str,
    old_str: str,