初始化

This commit is contained in:
gozeros committed 2026-09-07 18:24:55 +08:00
1 parent 34474bd5fc
commit b638b541d0
3008 files changed
+837699

No files matched your search

@@ -0,0 +1,333 @@
"""Middleware for intercepting clarification requests and presenting them to the user."""
import json
import logging
from collections.abc import Callable
from hashlib import sha256
from typing import Any, override
from deerflow.tools.builtins.clarification_utils import resolve_allow_multiple
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware, hook_config
from langchain_core.messages import AIMessage, ToolMessage
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.types import Command
logger = logging.getLogger(__name__)
class ClarificationMiddlewareState(AgentState):
"""Compatible with the `ThreadState` schema."""
pass
class ClarificationMiddleware(AgentMiddleware[ClarificationMiddlewareState]):
"""Intercepts clarification tool calls and interrupts execution to present questions to the user.
When the model calls the `ask_clarification` tool, this middleware:
1. Intercepts the tool call before execution
2. Extracts the clarification question and metadata
3. Formats a user-friendly message
4. Returns a Command that interrupts execution and presents the question
5. Waits for user response before continuing
This replaces the tool-based approach where clarification continued the conversation flow.
"""
state_schema = ClarificationMiddlewareState
def _stable_message_id(self, tool_call_id: str, formatted_message: str) -> str:
"""Build a deterministic message ID so retried clarification calls replace, not append."""
if tool_call_id:
return f"clarification:{tool_call_id}"
digest = sha256(formatted_message.encode("utf-8")).hexdigest()[:16]
return f"clarification:{digest}"
def _is_chinese(self, text: str) -> bool:
"""Check if text contains Chinese characters.
Args:
text: Text to check
Returns:
True if text contains Chinese characters
"""
return any("\u4e00" <= char <= "\u9fff" for char in text)
def _format_clarification_message(self, args: dict) -> str:
"""Format the clarification arguments into a user-friendly message.
Args:
args: The tool call arguments containing clarification details
Returns:
Formatted message string
"""
question = args.get("question", "")
clarification_type = args.get("clarification_type", "missing_info")
context = args.get("context")
options = self._normalize_options(args.get("options", []))
# Type-specific icons
type_icons = {
"missing_info": "❓",
"ambiguous_requirement": "🤔",
"approach_choice": "🔀",
"risk_confirmation": "⚠️",
"suggestion": "💡",
}
icon = type_icons.get(clarification_type, "❓")
# Build the message naturally
message_parts = []
# Add icon and question together for a more natural flow
if context:
# If there's context, present it first as background
message_parts.append(f"{icon} {context}")
message_parts.append(f"\n{question}")
else:
# Just the question with icon
message_parts.append(f"{icon} {question}")
# Add options in a cleaner format
if options and len(options) > 0:
message_parts.append("") # blank line for spacing
for i, option in enumerate(options, 1):
label = option.get("label") or option.get("id") or ""
message_parts.append(f" {i}. {label}")
return "\n".join(message_parts)
def _normalize_options(self, raw_options: object) -> list[dict[str, str]]:
"""Normalize model-produced options into a stable UI-friendly shape."""
options = raw_options
# Some models serialize array parameters as JSON strings instead of native arrays.
if isinstance(options, str):
try:
options = json.loads(options)
except (json.JSONDecodeError, TypeError):
options = [options]
if options is None:
values: list[object] = []
elif isinstance(options, list):
values = options
else:
values = [options]
normalized: list[dict[str, str]] = []
for index, value in enumerate(values, 1):
if isinstance(value, dict):
raw_label = value.get("label") or value.get("title") or value.get("name") or value.get("value") or value.get("id")
label = str(raw_label).strip() if raw_label is not None else ""
if not label:
continue
raw_id = value.get("id") or value.get("value") or f"option-{index}"
option = {
"id": str(raw_id).strip() or f"option-{index}",
"label": label,
}
description = value.get("description")
if description is not None and str(description).strip():
option["description"] = str(description).strip()
normalized.append(option)
else:
label = str(value).strip()
if label:
normalized.append({"id": f"option-{index}", "label": label})
return normalized
def _build_payload(self, args: dict) -> dict:
"""Build structured clarification data for rich clients."""
return {
"question": str(args.get("question", "")).strip(),
"clarification_type": args.get("clarification_type", "missing_info"),
"context": args.get("context"),
"options": self._normalize_options(args.get("options", [])),
"allow_custom": True,
"allow_multiple": resolve_allow_multiple(args),
}
def _parse_tool_args(self, tool_call: Any) -> dict[str, Any]:
args = self._tool_field(tool_call, "args") or {}
if isinstance(args, dict):
return args
if isinstance(args, str):
try:
parsed = json.loads(args)
return parsed if isinstance(parsed, dict) else {}
except (json.JSONDecodeError, TypeError):
return {}
return {}
def _handle_clarification(self, request: ToolCallRequest) -> ToolMessage:
"""Return the clarification ToolMessage without Command(goto=END).
Stopping the turn is ``after_model`` + ``jump_to=end``. Returning a
Command here used to mix with parallel tool results and loop the graph.
If the tools node still runs (jump_to not honored), a ToolMessage with
the same stable id replaces rather than appends.
"""
args = self._parse_tool_args(request.tool_call)
tool_call_id = str(self._tool_field(request.tool_call, "id") or "")
logger.info("Intercepted clarification request in wrap_tool_call")
return self._clarification_tool_message(tool_call_id, args)
def _tool_field(self, tool_call: Any, key: str, default: Any = None) -> Any:
if isinstance(tool_call, dict):
return tool_call.get(key, default)
getter = getattr(tool_call, "get", None)
if callable(getter):
return getter(key, default)
return getattr(tool_call, key, default)
def _tool_name(self, tool_call: Any) -> str:
"""Normalize tool names from dict / object / OpenAI-style nested function."""
raw = self._tool_field(tool_call, "name")
if raw is None and isinstance(tool_call, dict):
fn = tool_call.get("function")
if isinstance(fn, dict):
raw = fn.get("name")
name = str(raw or "").strip()
if "." in name:
name = name.rsplit(".", 1)[-1]
return name
def _is_clarification_call(self, tool_call: Any) -> bool:
return self._tool_name(tool_call).casefold() == "ask_clarification"
def _clarification_tool_message(self, tool_call_id: str, args: dict[str, Any]) -> ToolMessage:
formatted_message = self._format_clarification_message(args)
return ToolMessage(
id=self._stable_message_id(tool_call_id, formatted_message),
content=formatted_message,
tool_call_id=tool_call_id,
name="ask_clarification",
additional_kwargs={"clarification": self._build_payload(args)},
)
def _after_model_intercept(self, last: AIMessage) -> dict[str, Any] | None:
"""Stop the run as soon as the model emits ask_clarification.
Applies to **all** lead-agent chats (通用问答 / 智能体 / 写作配置 / 报告结构…)。
``wrap_tool_call`` + ``Command(goto=END)`` is unreliable with parallel
tool calls (weak models often emit two clarifications, or clarification
plus another tool): the Command mixes with other tool results and the
graph loops back to the model, which then treats the question ToolMessage
as "the user still hasn't answered" and keeps generating.
"""
tool_calls = list(last.tool_calls or [])
clarification_calls = [tc for tc in tool_calls if self._is_clarification_call(tc)]
if not clarification_calls:
return None
messages: list[ToolMessage] = []
for tc in tool_calls:
name = self._tool_name(tc) or "unknown"
tool_call_id = str(self._tool_field(tc, "id") or "")
args = self._parse_tool_args(tc)
if self._is_clarification_call(tc):
messages.append(self._clarification_tool_message(tool_call_id, args))
else:
messages.append(
ToolMessage(
id=f"clarification-skip:{tool_call_id or name}",
content="已暂停:需要先等待用户回答澄清问题,本工具未执行。",
tool_call_id=tool_call_id,
name=name,
)
)
logger.info(
"Intercepted %s clarification tool call(s) in after_model; ending turn",
len(clarification_calls),
)
return {"messages": messages, "jump_to": "end"}
@hook_config(can_jump_to=["end"])
@override
def after_model(
self,
state: ClarificationMiddlewareState,
runtime: object,
) -> dict[str, Any] | None:
messages = state.get("messages") or []
if not messages:
return None
last = messages[-1]
if not isinstance(last, AIMessage):
return None
return self._after_model_intercept(last)
@hook_config(can_jump_to=["end"])
@override
async def aafter_model(
self,
state: ClarificationMiddlewareState,
runtime: object,
) -> dict[str, Any] | None:
return self.after_model(state, runtime)
@override
def _stub_sibling_tool(self, request: ToolCallRequest) -> ToolMessage:
name = self._tool_name(request.tool_call) or "unknown"
tool_call_id = str(self._tool_field(request.tool_call, "id") or "")
return ToolMessage(
id=f"clarification-skip:{tool_call_id or name}",
content="已暂停:需要先等待用户回答澄清问题,本工具未执行。",
tool_call_id=tool_call_id,
name=name,
)
def _request_has_sibling_clarification(self, request: ToolCallRequest) -> bool:
state = getattr(request, "state", None)
messages: Any = None
if isinstance(state, dict):
messages = state.get("messages")
elif state is not None:
getter = getattr(state, "get", None)
if callable(getter):
messages = getter("messages")
else:
messages = getattr(state, "messages", None)
if not messages:
return False
last = messages[-1]
tool_calls = getattr(last, "tool_calls", None) or []
return any(self._is_clarification_call(tc) for tc in tool_calls)
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
"""Complete clarification tool calls; do not Command(goto=END).
Turn-stop is ``after_model`` + ``jump_to=end``. If the tools node still
runs, return a ToolMessage so parallel tools do not mix Commands.
"""
if self._is_clarification_call(request.tool_call):
return self._handle_clarification(request)
if self._request_has_sibling_clarification(request):
return self._stub_sibling_tool(request)
return handler(request)
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
if self._is_clarification_call(request.tool_call):
return self._handle_clarification(request)
if self._request_has_sibling_clarification(request):
return self._stub_sibling_tool(request)
return await handler(request)
@@ -0,0 +1,149 @@
"""Middleware to fix dangling tool calls in message history.
A dangling tool call occurs when an AIMessage contains tool_calls but there are
no corresponding ToolMessages in the history (e.g., due to user interruption or
request cancellation). This causes LLM errors due to incomplete message format.
This middleware intercepts the model call to detect and patch such gaps by
inserting synthetic ToolMessages with an error indicator immediately after the
AIMessage that made the tool calls, ensuring correct message ordering.
Note: Uses wrap_model_call instead of before_model to ensure patches are inserted
at the correct positions (immediately after each dangling AIMessage), not appended
to the end of the message list as before_model + add_messages reducer would do.
"""
import json
import logging
from collections.abc import Awaitable, Callable
from typing import override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
from langchain_core.messages import ToolMessage
logger = logging.getLogger(__name__)
class DanglingToolCallMiddleware(AgentMiddleware[AgentState]):
"""Inserts placeholder ToolMessages for dangling tool calls before model invocation.
Scans the message history for AIMessages whose tool_calls lack corresponding
ToolMessages, and injects synthetic error responses immediately after the
offending AIMessage so the LLM receives a well-formed conversation.
"""
@staticmethod
def _message_tool_calls(msg) -> list[dict]:
"""Return normalized tool calls from structured fields or raw provider payloads."""
tool_calls = getattr(msg, "tool_calls", None) or []
if tool_calls:
return list(tool_calls)
raw_tool_calls = (getattr(msg, "additional_kwargs", None) or {}).get("tool_calls") or []
normalized: list[dict] = []
for raw_tc in raw_tool_calls:
if not isinstance(raw_tc, dict):
continue
function = raw_tc.get("function")
name = raw_tc.get("name")
if not name and isinstance(function, dict):
name = function.get("name")
args = raw_tc.get("args", {})
if not args and isinstance(function, dict):
raw_args = function.get("arguments")
if isinstance(raw_args, str):
try:
parsed_args = json.loads(raw_args)
except (TypeError, ValueError, json.JSONDecodeError):
parsed_args = {}
args = parsed_args if isinstance(parsed_args, dict) else {}
normalized.append(
{
"id": raw_tc.get("id"),
"name": name or "unknown",
"args": args if isinstance(args, dict) else {},
}
)
return normalized
def _build_patched_messages(self, messages: list) -> list | None:
"""Return a new message list with patches inserted at the correct positions.
For each AIMessage with dangling tool_calls (no corresponding ToolMessage),
a synthetic ToolMessage is inserted immediately after that AIMessage.
Returns None if no patches are needed.
"""
# Collect IDs of all existing ToolMessages
existing_tool_msg_ids: set[str] = set()
for msg in messages:
if isinstance(msg, ToolMessage):
existing_tool_msg_ids.add(msg.tool_call_id)
# Check if any patching is needed
needs_patch = False
for msg in messages:
if getattr(msg, "type", None) != "ai":
continue
for tc in self._message_tool_calls(msg):
tc_id = tc.get("id")
if tc_id and tc_id not in existing_tool_msg_ids:
needs_patch = True
break
if needs_patch:
break
if not needs_patch:
return None
# Build new list with patches inserted right after each dangling AIMessage
patched: list = []
patched_ids: set[str] = set()
patch_count = 0
for msg in messages:
patched.append(msg)
if getattr(msg, "type", None) != "ai":
continue
for tc in self._message_tool_calls(msg):
tc_id = tc.get("id")
if tc_id and tc_id not in existing_tool_msg_ids and tc_id not in patched_ids:
patched.append(
ToolMessage(
content="[Tool call was interrupted and did not return a result.]",
tool_call_id=tc_id,
name=tc.get("name", "unknown"),
status="error",
)
)
patched_ids.add(tc_id)
patch_count += 1
logger.warning(f"Injecting {patch_count} placeholder ToolMessage(s) for dangling tool calls")
return patched
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
patched = self._build_patched_messages(request.messages)
if patched is not None:
request = request.override(messages=patched)
return handler(request)
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
patched = self._build_patched_messages(request.messages)
if patched is not None:
request = request.override(messages=patched)
return await handler(request)
@@ -0,0 +1,107 @@
"""Middleware to filter deferred tool schemas from model binding.
When tool_search is enabled, MCP tools are registered in the DeferredToolRegistry
and passed to ToolNode for execution, but their schemas should NOT be sent to the
LLM via bind_tools (that's the whole point of deferral — saving context tokens).
This middleware intercepts wrap_model_call and removes deferred tools from
request.tools so that model.bind_tools only receives active tool schemas.
The agent discovers deferred tools at runtime via the tool_search tool.
"""
import logging
from collections.abc import Awaitable, Callable
from typing import override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
from langchain_core.messages import ToolMessage
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.types import Command
logger = logging.getLogger(__name__)
class DeferredToolFilterMiddleware(AgentMiddleware[AgentState]):
"""Remove deferred tools from request.tools before model binding.
ToolNode still holds all tools (including deferred) for execution routing,
but the LLM only sees active tool schemas — deferred tools are discoverable
via tool_search at runtime.
"""
def _filter_tools(self, request: ModelRequest) -> ModelRequest:
from deerflow.tools.builtins.tool_search import get_deferred_registry
registry = get_deferred_registry()
if not registry:
return request
deferred_names = registry.deferred_names
active_tools = [t for t in request.tools if getattr(t, "name", None) not in deferred_names]
if len(active_tools) < len(request.tools):
logger.debug(f"Filtered {len(request.tools) - len(active_tools)} deferred tool schema(s) from model binding")
return request.override(tools=active_tools)
def _blocked_tool_message(self, request: ToolCallRequest) -> ToolMessage | None:
from deerflow.tools.builtins.tool_search import get_deferred_registry
registry = get_deferred_registry()
if not registry:
return None
tool_name = str(request.tool_call.get("name") or "")
if not tool_name:
return None
if not registry.contains(tool_name):
return None
tool_call_id = str(request.tool_call.get("id") or "missing_tool_call_id")
return ToolMessage(
content=(f"Error: Tool '{tool_name}' is deferred and has not been promoted yet. Call tool_search first to expose and promote this tool's schema, then retry."),
tool_call_id=tool_call_id,
name=tool_name,
status="error",
)
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
return handler(self._filter_tools(request))
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
blocked = self._blocked_tool_message(request)
if blocked is not None:
return blocked
return handler(request)
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
return await handler(self._filter_tools(request))
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command:
blocked = self._blocked_tool_message(request)
if blocked is not None:
return blocked
return await handler(request)
@@ -0,0 +1,382 @@
"""Hard runtime policy for the built-in forced-research responder.
The ordinary custom-agent skill allowlist only makes skills visible to the
model; it does not guarantee that a model will use one before answering. This
middleware turns that behavioural preference into a per-user-turn runtime
contract:
* before a successful information-gathering tool result exists, every model
call is made with ``tool_choice=required``;
* a provider that ignores ``tool_choice`` and emits text is sent back to the
model node (with the premature text hidden);
* after a bounded number of failed attempts the model may only report the
collection failure instead of looping forever;
* ``write_file`` / ``str_replace`` are restricted to temporary ``.py`` files
under ``/mnt/user-data/workspace`` and ``bash`` may only execute Python
scripts. Markdown/document deliverables and ``present_files`` are denied.
The policy is mounted only for :data:`FORCED_RESEARCH_AGENT_ID`.
"""
from __future__ import annotations
import json
import re
from collections.abc import Awaitable, Callable
from copy import deepcopy
from pathlib import PurePosixPath
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware, hook_config
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.runtime import Runtime
from langgraph.types import Command
FORCED_RESEARCH_AGENT_ID = "forced-research-responder"
_WORKSPACE_PREFIX = "/mnt/user-data/workspace"
_MAX_COLLECTION_ATTEMPTS = 8
# These tools prepare/discover capabilities but do not themselves return the
# information requested by the user. Unknown tools (not in this set) are
# intentionally accepted so configured MCP/skill-specific retrieval tools work.
_NON_EVIDENCE_TOOLS = {
"agent_orchestration",
"ask_clarification",
"bash",
"glob",
"grep",
"ls",
"memory",
"present_files",
"read_file",
"scheduled_task",
"search_skills",
"skill_list",
"skill_manage",
"skill_view",
"str_replace",
"task",
"tool_search",
"write_file",
"write_todos",
}
_TOOLS_REMOVED_FROM_FORCED_RESEARCH = {
"agent_orchestration",
"ask_clarification",
"memory",
"present_files",
"scheduled_task",
"skill_manage",
"task",
}
_FAILED_RESULT_MARKERS = (
"error:",
"no results found",
"no result found",
"success\": false",
"success': false",
"未找到",
"没有找到",
"检索失败",
"查询失败",
)
_FORCE_COLLECTION_TEXT = """<forced_research_gate>
【运行时强制】本轮尚未取得任何有效的信息采集结果,禁止直接回答用户。
请先分析用户意图,拆分检索方向和具体检索词,然后立即调用已配置技能所需的工具、检索工具、知识库工具或技能 Python 脚本。
读取 SKILL.md、搜索技能、编写临时 Python 脚本都只是准备步骤,不能替代实际信息采集。
至少取得一次有效工具结果后,才能按照用户指定的格式直接在聊天中回答。
</forced_research_gate>"""
_COLLECTION_FAILED_TEXT = """<forced_research_gate>
【运行时强制】本轮已经多次尝试调用工具,但仍未取得有效的信息采集结果。
现在不要继续循环,也不得凭模型记忆补写事实。请直接用用户要求的格式如实说明本轮检索失败、已经尝试的方向以及仍缺少的信息。
禁止生成或呈现任何文件。
</forced_research_gate>"""
def filter_forced_research_tools(tools: list[Any]) -> list[Any]:
"""Remove unrelated/write-capable built-ins while retaining skill tools.
``write_file`` and ``str_replace`` stay available because the policy below
narrows them to temporary Python source files. ``bash`` stays available so
script-backed skills can execute their own or those temporary scripts.
"""
return [tool for tool in tools if getattr(tool, "name", "") not in _TOOLS_REMOVED_FROM_FORCED_RESEARCH]
def _normalize_args(raw: object) -> dict[str, Any]:
if isinstance(raw, dict):
return raw
if isinstance(raw, str):
try:
parsed = json.loads(raw)
except (TypeError, ValueError, json.JSONDecodeError):
return {}
return parsed if isinstance(parsed, dict) else {}
return {}
def _tool_field(tool_call: object, key: str, default: Any = None) -> Any:
if isinstance(tool_call, dict):
return tool_call.get(key, default)
getter = getattr(tool_call, "get", None)
if callable(getter):
return getter(key, default)
return getattr(tool_call, key, default)
def _normalized_container_path(value: object) -> str:
text = str(value or "").strip().replace("\\", "/")
if not text:
return ""
try:
return str(PurePosixPath(text))
except Exception: # noqa: BLE001 - invalid model-provided path is denied
return ""
def _is_workspace_python_path(value: object) -> bool:
path = _normalized_container_path(value)
return path.startswith(f"{_WORKSPACE_PREFIX}/") and path.lower().endswith(".py")
_PYTHON_EXECUTABLE_RE = re.compile(r"(?:^|[\s;&|])(?:python(?:3(?:\.\d+)?)?|py)(?:\.exe)?(?:\s|$)", re.IGNORECASE)
_PYTHON_FILE_RE = re.compile(r"(?:^|[\s\"'])([^\s\"']+\.py)(?=$|[\s\"'])", re.IGNORECASE)
_SHELL_WRITE_RE = re.compile(r"(?:>|\b(?:tee|touch|cp|mv|rm|del|erase|out-file|set-content|add-content)\b)", re.IGNORECASE)
_FORBIDDEN_DELIVERABLE_RE = re.compile(r"(?:/mnt/user-data/outputs|\.(?:md|markdown|docx?|pdf|xlsx?|pptx?|html?)(?:\s|$|[\"']))", re.IGNORECASE)
def _validate_python_command(command: object) -> str | None:
text = str(command or "").strip()
if not text:
return "bash 仅允许执行技能所需的 Python 脚本,command 不能为空。"
if _FORBIDDEN_DELIVERABLE_RE.search(text):
return "禁止通过 bash 创建、修改或处理 Markdown/文档交付物及 outputs 目录。"
if _SHELL_WRITE_RE.search(text):
return "bash 仅允许执行 Python 脚本,禁止使用 shell 重定向或文件管理命令。"
if not _PYTHON_EXECUTABLE_RE.search(text) or not _PYTHON_FILE_RE.search(text):
return "bash 仅允许执行 .py 脚本(例如 cd <技能目录> && python scripts/search.py ...)。"
return None
def validate_forced_research_tool_call(tool_call: object) -> str | None:
"""Return a rejection reason, or ``None`` when the call is permitted."""
name = str(_tool_field(tool_call, "name", "") or "")
args = _normalize_args(_tool_field(tool_call, "args", {}))
if name == "present_files":
return "本智能体只在聊天中输出,禁止呈现沙箱文件。"
if name in {"write_file", "str_replace"}:
if not _is_workspace_python_path(args.get("path")):
return "只允许在 /mnt/user-data/workspace/ 下创建或修改临时 .py 文件。"
if name == "bash":
return _validate_python_command(args.get("command"))
return None
def _is_visible_human(message: Any) -> bool:
if not isinstance(message, HumanMessage):
return False
kwargs = getattr(message, "additional_kwargs", None) or {}
if kwargs.get("hide_from_ui"):
return False
return getattr(message, "name", None) != "forced_research_gate"
def _turn_start(messages: list[Any]) -> int:
for index in range(len(messages) - 1, -1, -1):
if _is_visible_human(messages[index]):
return index
return 0
def _call_map(messages: list[Any], start: int) -> dict[str, tuple[str, dict[str, Any]]]:
calls: dict[str, tuple[str, dict[str, Any]]] = {}
for message in messages[start:]:
if not isinstance(message, AIMessage):
continue
for call in message.tool_calls or []:
call_id = str(_tool_field(call, "id", "") or "")
if call_id:
calls[call_id] = (
str(_tool_field(call, "name", "") or ""),
_normalize_args(_tool_field(call, "args", {})),
)
return calls
def _tool_result_succeeded(message: ToolMessage) -> bool:
status = str(getattr(message, "status", "") or "").lower()
if status == "error":
return False
content = str(getattr(message, "content", "") or "").strip()
if not content:
return False
lowered = content.lower()
return not any(marker in lowered for marker in _FAILED_RESULT_MARKERS)
def _is_information_result(name: str, args: dict[str, Any], message: ToolMessage) -> bool:
if name in _NON_EVIDENCE_TOOLS:
if name == "read_file":
path = str(args.get("path") or "").replace("\\", "/").lower()
if path.endswith("/skill.md") or path.endswith(".py"):
return False
elif name == "bash":
# bash is evidence only when it actually executed a Python skill
# script; policy validation has already rejected other commands.
if _validate_python_command(args.get("command")) is not None:
return False
else:
return False
return _tool_result_succeeded(message)
def _turn_collection_state(messages: list[Any]) -> tuple[bool, int]:
start = _turn_start(messages)
calls = _call_map(messages, start)
attempts = 0
for message in messages[start:]:
if not isinstance(message, ToolMessage):
continue
call_id = str(getattr(message, "tool_call_id", "") or "")
call = calls.get(call_id)
if call is None:
continue
attempts += 1
if _is_information_result(call[0], call[1], message):
return True, attempts
return False, attempts
def _hidden_reminder(text: str) -> HumanMessage:
return HumanMessage(
name="forced_research_gate",
content=text,
additional_kwargs={"hide_from_ui": True, "lc_source": "forced_research_gate"},
)
class ForcedResearchMiddleware(AgentMiddleware[AgentState]):
"""Require information collection and enforce temporary-Python-only IO."""
state_schema = AgentState
def _patch_model_request(self, request: ModelRequest) -> ModelRequest:
messages = list(request.messages or [])
collected, attempts = _turn_collection_state(messages)
if collected:
return request
if attempts >= _MAX_COLLECTION_ATTEMPTS:
return request.override(messages=[*messages, _hidden_reminder(_COLLECTION_FAILED_TEXT)])
return request.override(
messages=[*messages, _hidden_reminder(_FORCE_COLLECTION_TEXT)],
tool_choice="required",
)
def _prevent_premature_exit(self, state: AgentState) -> dict[str, Any] | None:
messages = list(state.get("messages") or [])
if not messages:
return None
last = messages[-1]
if not isinstance(last, AIMessage) or last.tool_calls:
return None
collected, attempts = _turn_collection_state(messages)
if collected or attempts >= _MAX_COLLECTION_ATTEMPTS:
return None
# Some OpenAI-compatible gateways ignore ``tool_choice=required``.
# Hide/blank that premature answer and explicitly jump back to model.
additional_kwargs = dict(last.additional_kwargs or {})
additional_kwargs["hide_from_ui"] = True
additional_kwargs["lc_source"] = "forced_research_suppressed_answer"
response_metadata = deepcopy(last.response_metadata or {})
if response_metadata.get("finish_reason") == "stop":
response_metadata["finish_reason"] = "tool_calls"
suppressed = last.model_copy(
update={
"content": "",
"additional_kwargs": additional_kwargs,
"response_metadata": response_metadata,
}
)
return {
"jump_to": "model",
"messages": [suppressed, _hidden_reminder(_FORCE_COLLECTION_TEXT)],
}
def _reject_tool_call(self, request: ToolCallRequest) -> ToolMessage | None:
tool_call = getattr(request, "tool_call", None) or {}
reason = validate_forced_research_tool_call(tool_call)
if reason is None:
return None
return ToolMessage(
content=f"Error: {reason}",
tool_call_id=str(_tool_field(tool_call, "id", "") or ""),
name=str(_tool_field(tool_call, "name", "") or ""),
status="error",
)
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
return handler(self._patch_model_request(request))
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
return await handler(self._patch_model_request(request))
@hook_config(can_jump_to=["model"])
@override
def after_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
return self._prevent_premature_exit(state)
@hook_config(can_jump_to=["model"])
@override
async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
return self._prevent_premature_exit(state)
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
rejected = self._reject_tool_call(request)
if rejected is not None:
return rejected
return handler(request)
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command:
rejected = self._reject_tool_call(request)
if rejected is not None:
return rejected
return await handler(request)
__all__ = [
"FORCED_RESEARCH_AGENT_ID",
"ForcedResearchMiddleware",
"filter_forced_research_tools",
"validate_forced_research_tool_call",
]
@@ -0,0 +1,190 @@
"""KnowledgeRagMiddleware — inject knowledge-base recall before the model call.
Phase 2 of the product knowledge base. When enabled (per-conversation runtime
flag ``knowledge_rag_enabled``, falling back to the global
``knowledge.rag_enabled`` config), the latest user question is used to retrieve
the most relevant knowledge notes, which are injected as a transient
``<knowledge-context>`` system message — not persisted to state, so it never
leaks to the frontend transcript.
Retrieval is hybrid (vector + keyword) when an embedding endpoint is
configured, else keyword/wiki-query layered search. Failures are swallowed: RAG
must never break a conversation.
"""
from __future__ import annotations
import asyncio
import logging
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import HumanMessage
from langgraph.runtime import Runtime
logger = logging.getLogger(__name__)
_TAG = "knowledge-context"
def _coerce_text(content: Any) -> str:
if isinstance(content, str):
return content
if isinstance(content, list):
parts = []
for block in content:
if isinstance(block, str):
parts.append(block)
elif isinstance(block, dict) and block.get("type") == "text":
parts.append(str(block.get("text", "")))
return " ".join(parts)
return str(content or "")
def _latest_human_text(messages: list) -> str:
for msg in reversed(messages or []):
if isinstance(msg, HumanMessage):
return _coerce_text(msg.content).strip()
return ""
class KnowledgeRagMiddleware(AgentMiddleware[AgentState]):
"""Inject knowledge-base recall as transient system context."""
state_schema = AgentState
def __init__(self, *, limit: int = 5, default_enabled: bool = False) -> None:
super().__init__()
self._limit = limit
self._default_enabled = default_enabled
self._service = None # lazy
def _get_service(self):
if self._service is not None:
return self._service
try:
from deerflow.config import get_app_config
from deerflow.knowledge import make_knowledge_service
from deerflow.persistence.engine import get_session_factory
config = get_app_config()
self._service = make_knowledge_service(get_session_factory(), config.knowledge)
except Exception:
logger.exception("KnowledgeRagMiddleware: failed to build knowledge service")
self._service = None
return self._service
def _enabled_for(self, request: Any) -> bool:
runtime = getattr(request, "runtime", None)
if runtime is not None and getattr(runtime, "context", None):
flag = runtime.context.get("knowledge_rag_enabled")
if flag is not None:
return bool(flag)
return self._default_enabled
async def _build_context_message(self, request: Any) -> HumanMessage | None:
if not self._enabled_for(request):
return None
service = self._get_service()
if service is None:
return None
query = _latest_human_text(getattr(request, "messages", None) or [])
if not query:
return None
try:
result = await service.build_rag_context(query, limit=self._limit)
except Exception:
logger.exception("KnowledgeRagMiddleware: recall failed (non-fatal)")
return None
text = result.get("text") if isinstance(result, dict) else ""
if not text:
return None
fenced = (
f"<{_TAG}>\n"
"[系统提示:以下是知识库召回的背景资料,不是用户的新输入。回答时优先参考,"
"并在使用到时标注来源 note_id。]\n\n"
f"{text}\n"
f"</{_TAG}>"
)
return HumanMessage(content=fenced)
@override
async def awrap_model_call(self, request: Any, handler: Any) -> Any:
msg = await self._build_context_message(request)
if msg is not None:
request = request.override(messages=[*request.messages, msg])
return await handler(request)
@override
def wrap_model_call(self, request: Any, handler: Any) -> Any:
# Sync path: best-effort. The gateway runtime is async, so this is rarely
# hit; run the async recall in a private loop when there is none.
if not self._enabled_for(request):
return handler(request)
try:
loop = asyncio.get_event_loop()
if loop.is_running():
# Cannot block a running loop from sync code; skip injection.
return handler(request)
msg = loop.run_until_complete(self._build_context_message(request))
except Exception:
msg = None
if msg is not None:
request = request.override(messages=[*request.messages, msg])
return handler(request)
# ---- after_agent: enqueue background auto-sedimentation -------------
def _resolve_thread_id(self, runtime: Runtime | None) -> str | None:
if runtime is not None and getattr(runtime, "context", None):
tid = runtime.context.get("thread_id")
if tid:
return str(tid)
try:
from langgraph.config import get_config
return get_config().get("configurable", {}).get("thread_id")
except Exception:
return None
@override
def after_agent(self, state: AgentState, runtime: Runtime) -> dict | None:
"""When auto-ingest is on, hand the finished turn to the background queue."""
try:
from deerflow.config import get_app_config
knowledge_cfg = getattr(get_app_config(), "knowledge", None)
if knowledge_cfg is None or not knowledge_cfg.enabled or not knowledge_cfg.auto_ingest_enabled:
return None
from deerflow.knowledge.auto_ingest import AutoIngestItem, get_auto_ingest_queue
queue = get_auto_ingest_queue()
if queue is None:
return None
messages = state.get("messages") if isinstance(state, dict) else getattr(state, "messages", None)
if not messages:
return None
from deerflow.runtime.references import build_reference_batches
from deerflow.runtime.serialization import serialize_lc_object
from deerflow.runtime.user_context import get_effective_user_id
serialized = [serialize_lc_object(m) for m in messages]
thread_id = self._resolve_thread_id(runtime)
if not thread_id:
return None
title = state.get("title") if isinstance(state, dict) else getattr(state, "title", None)
queue.enqueue(
AutoIngestItem(
thread_id=thread_id,
user_id=get_effective_user_id(),
messages=serialized,
thread_title=title if isinstance(title, str) else None,
reference_batches=build_reference_batches(serialized),
)
)
except Exception:
logger.exception("KnowledgeRagMiddleware.after_agent enqueue failed (non-fatal)")
return None
@@ -0,0 +1,464 @@
"""LLM error handling middleware with retry/backoff and user-facing fallbacks."""
from __future__ import annotations
import asyncio
import logging
import threading
import time
from collections.abc import Awaitable, Callable
from email.utils import parsedate_to_datetime
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain.agents.middleware.types import (
ModelCallResult,
ModelRequest,
ModelResponse,
)
from langchain_core.messages import AIMessage
from langgraph.errors import GraphBubbleUp
from deerflow.config.app_config import AppConfig
logger = logging.getLogger(__name__)
# 兜底/熔断的 AIMessage 会带上 ``additional_kwargs[LLM_ERROR_MARKER] = reason``,
# 让下游(圆桌会商的单轮执行器等)能**可靠识别**「这条 AI 回复其实是模型调用失败的
# 兜底文案」而不是真实交付——据此触发自动换模型。``reason`` ∈ {quota, auth, busy,
# transient, upstream, generic, circuit}。注意:model_dump() 会保留 additional_kwargs,
# 故经 checkpointer 序列化后仍在;万一被剥离,``is_llm_error_message`` 还会回退按已知
# 兜底文案精确匹配。
LLM_ERROR_MARKER = "deerflow_llm_error"
# 各 reason 对应的用户可见兜底文案(单一数据源:构造与识别都用它)。
_USER_MESSAGES: dict[str, str] = {
"quota": "大模型因账户额度不足、账单异常或使用受限而拒绝请求,请检查模型账户后再试。",
"auth": "大模型因鉴权失败或无访问权限而拒绝请求,请检查模型的 API Key 与权限配置后再试。",
"busy": "大模型服务暂时繁忙,多次自动重试后仍未恢复,请稍候再继续。",
"transient": "大模型响应暂时中断或超时,多次自动重试后仍未恢复,请稍候再继续。",
"upstream": "大模型当前响应异常(上游模型或网关临时故障),多次重试后仍未恢复,请稍后再试或更换模型。",
"generic": "大模型本次调用未能成功完成,请稍后再试或更换模型。",
}
_CIRCUIT_MESSAGE = "大模型因连续多次调用失败已被熔断保护,请稍候再试。"
# 全部兜底文案集合,供 ``is_llm_error_message`` 在 additional_kwargs 被剥离时按正文回退识别。
_ALL_ERROR_MESSAGES: frozenset[str] = frozenset({*_USER_MESSAGES.values(), _CIRCUIT_MESSAGE})
def is_llm_error_message(message: Any) -> str | None:
"""判断一条 AI 消息是否为「模型调用失败的兜底文案」,是则返回 reason,否则 None。
入参可为 LangChain ``BaseMessage``,或 checkpointer 序列化后的 dict(两种都支持)。
优先看 ``additional_kwargs[LLM_ERROR_MARKER]``(最可靠);万一被序列化剥离,再回退
按正文是否精确等于已知兜底文案识别(容忍前后空白)。
"""
if message is None:
return None
# additional_kwargs(dict 或对象属性两种形态)。
extra: Any = None
if isinstance(message, dict):
extra = message.get("additional_kwargs")
else:
extra = getattr(message, "additional_kwargs", None)
if isinstance(extra, dict):
reason = extra.get(LLM_ERROR_MARKER)
if reason:
return str(reason)
# 正文回退匹配。
if isinstance(message, dict):
content = message.get("content")
else:
content = getattr(message, "content", None)
text = ""
if isinstance(content, str):
text = content
elif isinstance(content, list):
text = "\n".join(p.get("text", "") for p in content if isinstance(p, dict) and p.get("type") == "text")
text = text.strip()
if text and text in _ALL_ERROR_MESSAGES:
return "generic"
return None
_RETRIABLE_STATUS_CODES = {408, 409, 425, 429, 500, 502, 503, 504}
_BUSY_PATTERNS = (
"server busy",
"temporarily unavailable",
"try again later",
"please retry",
"please try again",
"overloaded",
"high demand",
"rate limit",
"负载较高",
"服务繁忙",
"稍后重试",
"请稍后重试",
)
_QUOTA_PATTERNS = (
"insufficient_quota",
"quota",
"billing",
"credit",
"payment",
"余额不足",
"超出限额",
"额度不足",
"欠费",
)
_AUTH_PATTERNS = (
"authentication",
"unauthorized",
"invalid api key",
"invalid_api_key",
"permission",
"forbidden",
"access denied",
"无权",
"未授权",
)
# Upstream model gateway returned a malformed payload (typically a JSON decode
# error wrapped as `bad_response_status_code`, or a truncated/garbled inference
# response). These are almost always transient inference-side issues and safe
# to retry.
_UPSTREAM_GARBAGE_PATTERNS = (
"bad_response_status_code",
"bad response status",
"expecting ',' delimiter",
"expecting value",
"expecting property name",
"unexpected character",
"unterminated string",
"extra data",
"jsondecodeerror",
)
class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
"""Retry transient LLM errors and surface graceful assistant messages."""
retry_max_attempts: int = 3
retry_base_delay_ms: int = 1000
retry_cap_delay_ms: int = 8000
def __init__(self, *, app_config: AppConfig, **kwargs: Any) -> None:
super().__init__(**kwargs)
self.circuit_failure_threshold = app_config.circuit_breaker.failure_threshold
self.circuit_recovery_timeout_sec = app_config.circuit_breaker.recovery_timeout_sec
# Circuit Breaker state
self._circuit_lock = threading.Lock()
self._circuit_failure_count = 0
self._circuit_open_until = 0.0
self._circuit_state = "closed"
self._circuit_probe_in_flight = False
def _check_circuit(self) -> bool:
"""Returns True if circuit is OPEN (fast fail), False otherwise."""
with self._circuit_lock:
now = time.time()
if self._circuit_state == "open":
if now < self._circuit_open_until:
return True
self._circuit_state = "half_open"
self._circuit_probe_in_flight = False
if self._circuit_state == "half_open":
if self._circuit_probe_in_flight:
return True
self._circuit_probe_in_flight = True
return False
return False
def _record_success(self) -> None:
with self._circuit_lock:
if self._circuit_state != "closed" or self._circuit_failure_count > 0:
logger.info("Circuit breaker reset (Closed). LLM service recovered.")
self._circuit_failure_count = 0
self._circuit_open_until = 0.0
self._circuit_state = "closed"
self._circuit_probe_in_flight = False
def _record_failure(self) -> None:
with self._circuit_lock:
if self._circuit_state == "half_open":
self._circuit_open_until = time.time() + self.circuit_recovery_timeout_sec
self._circuit_state = "open"
self._circuit_probe_in_flight = False
logger.error(
"Circuit breaker probe failed (Open). Will probe again after %ds.",
self.circuit_recovery_timeout_sec,
)
return
self._circuit_failure_count += 1
if self._circuit_failure_count >= self.circuit_failure_threshold:
self._circuit_open_until = time.time() + self.circuit_recovery_timeout_sec
if self._circuit_state != "open":
self._circuit_state = "open"
self._circuit_probe_in_flight = False
logger.error(
"Circuit breaker tripped (Open). Threshold reached (%d). Will probe after %ds.",
self.circuit_failure_threshold,
self.circuit_recovery_timeout_sec,
)
def _classify_error(self, exc: BaseException) -> tuple[bool, str]:
detail = _extract_error_detail(exc)
lowered = detail.lower()
error_code = _extract_error_code(exc)
error_code_lower = str(error_code).lower() if error_code is not None else ""
status_code = _extract_status_code(exc)
if _matches_any(lowered, _QUOTA_PATTERNS) or _matches_any(error_code_lower, _QUOTA_PATTERNS):
return False, "quota"
if _matches_any(lowered, _AUTH_PATTERNS):
return False, "auth"
exc_name = exc.__class__.__name__
if exc_name in {
"APITimeoutError",
"APIConnectionError",
"InternalServerError",
"ReadError", # httpx.ReadError: connection dropped mid-stream
"RemoteProtocolError", # httpx: server closed connection unexpectedly
# httpx.TimeoutException family escapes the streaming path unwrapped
# (seen live: httpx.ReadTimeout mid-generation after 200 OK — the
# provider stalled ~17s; that must retry, not fail the whole run).
"ReadTimeout",
"ConnectTimeout",
"WriteTimeout",
"PoolTimeout",
"TimeoutError", # asyncio chunk timeout / builtin timeout
"ConnectError", # httpx: connection refused / DNS blip
}:
return True, "transient"
if status_code in _RETRIABLE_STATUS_CODES:
return True, "transient"
if _matches_any(lowered, _BUSY_PATTERNS):
return True, "busy"
# Treat upstream gateway garbage (malformed JSON, truncated responses)
# as a retriable transient — the deterministic char-position errors we
# see from vLLM/proxy layers usually clear on a re-roll.
if _matches_any(lowered, _UPSTREAM_GARBAGE_PATTERNS) or _matches_any(error_code_lower, _UPSTREAM_GARBAGE_PATTERNS):
return True, "upstream"
return False, "generic"
def _build_retry_delay_ms(self, attempt: int, exc: BaseException) -> int:
retry_after = _extract_retry_after_ms(exc)
if retry_after is not None:
return retry_after
backoff = self.retry_base_delay_ms * (2 ** max(0, attempt - 1))
return min(backoff, self.retry_cap_delay_ms)
def _build_retry_message(self, attempt: int, wait_ms: int, reason: str) -> str:
seconds = max(1, round(wait_ms / 1000))
if reason == "busy":
reason_text = "服务繁忙"
elif reason == "upstream":
reason_text = "上游响应异常"
else:
reason_text = "响应中断或超时"
return f"大模型因{reason_text}暂未返回,正在第 {attempt}/{self.retry_max_attempts} 次自动重试,{seconds} 秒后继续…"
def _build_circuit_breaker_message(self) -> str:
return _CIRCUIT_MESSAGE
def _build_user_message(self, reason: str) -> str:
# NOTE: We intentionally do NOT embed the raw exception detail into the
# user-facing message. Raw `Error code: 400 - {...}` strings — especially
# Python repr-style dict literals — get persisted as AI messages and then
# re-fed to the model on the next turn, where their unescaped quotes /
# braces can corrupt the upstream JSON payload and cause deterministic
# JSONDecodeError loops. Keep the user message clean; full detail is
# already in the backend log via `logger.warning(..., exc_info=exc)`.
return _USER_MESSAGES.get(reason, _USER_MESSAGES["generic"])
def _error_message(self, content: str, reason: str) -> AIMessage:
"""构造带 ``LLM_ERROR_MARKER`` 标记的兜底 AIMessage(供下游识别+换模型)。"""
return AIMessage(content=content, additional_kwargs={LLM_ERROR_MARKER: reason})
def _emit_retry_event(self, attempt: int, wait_ms: int, reason: str) -> None:
try:
from langgraph.config import get_stream_writer
writer = get_stream_writer()
writer(
{
"type": "llm_retry",
"attempt": attempt,
"max_attempts": self.retry_max_attempts,
"wait_ms": wait_ms,
"reason": reason,
"message": self._build_retry_message(attempt, wait_ms, reason),
}
)
except Exception:
logger.debug("Failed to emit llm_retry event", exc_info=True)
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
if self._check_circuit():
return self._error_message(self._build_circuit_breaker_message(), "circuit")
attempt = 1
while True:
try:
response = handler(request)
self._record_success()
return response
except GraphBubbleUp:
# Preserve LangGraph control-flow signals (interrupt/pause/resume).
with self._circuit_lock:
if self._circuit_state == "half_open":
self._circuit_probe_in_flight = False
raise
except Exception as exc:
retriable, reason = self._classify_error(exc)
if retriable and attempt < self.retry_max_attempts:
wait_ms = self._build_retry_delay_ms(attempt, exc)
logger.warning(
"Transient LLM error on attempt %d/%d; retrying in %dms: %s",
attempt,
self.retry_max_attempts,
wait_ms,
_extract_error_detail(exc),
)
self._emit_retry_event(attempt, wait_ms, reason)
time.sleep(wait_ms / 1000)
attempt += 1
continue
logger.warning(
"LLM call failed after %d attempt(s): %s",
attempt,
_extract_error_detail(exc),
exc_info=exc,
)
if retriable:
self._record_failure()
return self._error_message(self._build_user_message(reason), reason)
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
if self._check_circuit():
return self._error_message(self._build_circuit_breaker_message(), "circuit")
attempt = 1
while True:
try:
response = await handler(request)
self._record_success()
return response
except GraphBubbleUp:
# Preserve LangGraph control-flow signals (interrupt/pause/resume).
with self._circuit_lock:
if self._circuit_state == "half_open":
self._circuit_probe_in_flight = False
raise
except Exception as exc:
retriable, reason = self._classify_error(exc)
if retriable and attempt < self.retry_max_attempts:
wait_ms = self._build_retry_delay_ms(attempt, exc)
logger.warning(
"Transient LLM error on attempt %d/%d; retrying in %dms: %s",
attempt,
self.retry_max_attempts,
wait_ms,
_extract_error_detail(exc),
)
self._emit_retry_event(attempt, wait_ms, reason)
await asyncio.sleep(wait_ms / 1000)
attempt += 1
continue
logger.warning(
"LLM call failed after %d attempt(s): %s",
attempt,
_extract_error_detail(exc),
exc_info=exc,
)
if retriable:
self._record_failure()
return self._error_message(self._build_user_message(reason), reason)
def _matches_any(detail: str, patterns: tuple[str, ...]) -> bool:
return any(pattern in detail for pattern in patterns)
def _extract_error_code(exc: BaseException) -> Any:
for attr in ("code", "error_code"):
value = getattr(exc, attr, None)
if value not in (None, ""):
return value
body = getattr(exc, "body", None)
if isinstance(body, dict):
error = body.get("error")
if isinstance(error, dict):
for key in ("code", "type"):
value = error.get(key)
if value not in (None, ""):
return value
return None
def _extract_status_code(exc: BaseException) -> int | None:
for attr in ("status_code", "status"):
value = getattr(exc, attr, None)
if isinstance(value, int):
return value
response = getattr(exc, "response", None)
status = getattr(response, "status_code", None)
return status if isinstance(status, int) else None
def _extract_retry_after_ms(exc: BaseException) -> int | None:
response = getattr(exc, "response", None)
headers = getattr(response, "headers", None)
if headers is None:
return None
raw = None
header_name = ""
for key in ("retry-after-ms", "Retry-After-Ms", "retry-after", "Retry-After"):
header_name = key
if hasattr(headers, "get"):
raw = headers.get(key)
if raw:
break
if not raw:
return None
try:
multiplier = 1 if "ms" in header_name.lower() else 1000
return max(0, int(float(raw) * multiplier))
except (TypeError, ValueError):
try:
target = parsedate_to_datetime(str(raw))
delta = target.timestamp() - time.time()
return max(0, int(delta * 1000))
except (TypeError, ValueError, OverflowError):
return None
def _extract_error_detail(exc: BaseException) -> str:
detail = str(exc).strip()
if detail:
return detail
message = getattr(exc, "message", None)
if isinstance(message, str) and message.strip():
return message.strip()
return exc.__class__.__name__
@@ -0,0 +1,331 @@
"""Middleware that records per-LLM-call metrics for the admin audit page.
Captures **every** provider invocation regardless of the frontend speed-meter
toggle: the goal is a complete admin-side audit log of LLM usage, including
failures. The user-facing speed indicator (controlled by
``LocalSettings.display.streamSpeedMeterEnabled``) is a separate, purely
cosmetic feature — turning it off does not stop this recording.
Each call ends with one row in ``llm_call_metrics``:
- Successes record duration, token counts, and ``tokens_per_sec``.
- Errors record the duration spent before the failure, the exception class as
``error_type`` and a one-line ``error_message``.
Writes go through a best-effort store: a DB outage logs a warning and the
agent runtime keeps streaming. We intentionally place this middleware
*inside* :class:`LLMErrorHandlingMiddleware` (i.e. nested deeper in the
``wrap_model_call`` chain) so we observe the **real** provider call timings —
not the retry-wrapped successful response.
"""
from __future__ import annotations
import logging
import time
import uuid
from collections.abc import Awaitable, Callable
from datetime import UTC, datetime
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain.agents.middleware.types import (
ModelCallResult,
ModelRequest,
ModelResponse,
)
from langchain_core.messages import AIMessage
from langgraph.errors import GraphBubbleUp
from deerflow.persistence.engine import fire_and_forget_db_write, get_session_factory
from deerflow.persistence.llm_metrics import LlmMetricRecord, make_llm_metrics_store
from deerflow.persistence.llm_metrics.base import LlmMetricsStore
from deerflow.runtime.user_context import get_effective_user_id
logger = logging.getLogger(__name__)
def _now() -> datetime:
return datetime.now(UTC)
def _safe_get_thread_id(request: ModelRequest) -> str | None:
state = getattr(request, "state", None)
if isinstance(state, dict):
thread_id = state.get("thread_id")
if isinstance(thread_id, str) and thread_id:
return thread_id
runtime = getattr(request, "runtime", None)
if runtime is None:
return None
config = getattr(runtime, "config", None)
configurable = (config or {}).get("configurable", {}) if isinstance(config, dict) else {}
thread_id = configurable.get("thread_id") if isinstance(configurable, dict) else None
if isinstance(thread_id, str) and thread_id:
return thread_id
return None
def _safe_get_run_id(request: ModelRequest) -> str | None:
runtime = getattr(request, "runtime", None)
if runtime is None:
return None
context = getattr(runtime, "context", None)
if isinstance(context, dict):
for key in ("run_id", "langgraph_run_id"):
value = context.get(key)
if isinstance(value, str) and value:
return value
config = getattr(runtime, "config", None)
if isinstance(config, dict):
metadata = config.get("metadata") if isinstance(config.get("metadata"), dict) else {}
if isinstance(metadata, dict):
for key in ("run_id", "langgraph_run_id"):
value = metadata.get(key)
if isinstance(value, str) and value:
return value
return None
def _safe_get_model_name(request: ModelRequest) -> str | None:
model = getattr(request, "model", None)
for attr in ("model_name", "model", "name"):
value = getattr(model, attr, None)
if isinstance(value, str) and value:
return value
return None
def _safe_get_agent_name(request: ModelRequest) -> str | None:
runtime = getattr(request, "runtime", None)
if runtime is None:
return None
context = getattr(runtime, "context", None)
if isinstance(context, dict):
for key in ("agent_name", "agent_id"):
value = context.get(key)
if isinstance(value, str) and value:
return value
return None
def _coerce_int(value: Any) -> int | None:
if isinstance(value, bool):
return None
if isinstance(value, int):
return value
if isinstance(value, float):
return int(value)
if isinstance(value, str):
try:
return int(value)
except (TypeError, ValueError):
return None
return None
def _extract_usage(response: Any) -> dict[str, int]:
"""Pull token counts out of an AIMessage, falling back to provider-native shapes.
The handler in ``wrap_model_call`` actually hands us a
:class:`langchain.agents.middleware.types.ModelResponse` dataclass whose
``.result`` is a ``list[BaseMessage]``. Earlier versions of this helper
only matched ``AIMessage`` and ``list``, which meant we silently dropped
every successful call and stored None for input/output/total. To stay
robust we now also handle ``ModelResponse`` (and ``ExtendedModelResponse``,
which wraps a ModelResponse), and we walk the messages list for the first
``AIMessage``.
LangChain normalises usage into ``message.usage_metadata`` with the keys
``input_tokens`` / ``output_tokens`` / ``total_tokens``. Several
OpenAI-compatible providers (DeepSeek, vLLM, some Azure deployments) leave
that dict partial — typically only ``total_tokens`` is populated — and the
real breakdown sits under ``response_metadata.token_usage`` with the
provider-native key names ``prompt_tokens`` / ``completion_tokens``. We
merge both so the admin audit view always has the most complete numbers
available.
"""
message: AIMessage | None = None
def _find_ai(candidate: Any) -> AIMessage | None:
if isinstance(candidate, AIMessage):
return candidate
if isinstance(candidate, list):
for item in candidate:
found = _find_ai(item)
if found is not None:
return found
return None
message = _find_ai(response)
if message is None:
# ModelResponse / ExtendedModelResponse — defined as dataclasses with a
# ``result`` field holding ``list[BaseMessage]``. Recurse via attribute
# access so we don't tightly couple to the dataclass class itself.
for attr in ("result", "model_response"):
inner = getattr(response, attr, None)
if inner is None:
continue
message = _find_ai(inner)
if message is None and attr == "model_response":
inner_result = getattr(inner, "result", None)
message = _find_ai(inner_result)
if message is not None:
break
if message is None:
return {}
out: dict[str, int] = {}
usage = getattr(message, "usage_metadata", None) or {}
if isinstance(usage, dict):
for key in ("input_tokens", "output_tokens", "total_tokens"):
coerced = _coerce_int(usage.get(key))
if coerced is not None:
out[key] = coerced
response_metadata = getattr(message, "response_metadata", None) or {}
token_usage = response_metadata.get("token_usage") if isinstance(response_metadata, dict) else None
if isinstance(token_usage, dict):
# Map both the LangChain-canonical names and OpenAI-native names; later
# writes win so a more-precise provider-native value can override a
# zero placeholder from usage_metadata.
candidates = {
"input_tokens": ("input_tokens", "prompt_tokens"),
"output_tokens": ("output_tokens", "completion_tokens"),
"total_tokens": ("total_tokens",),
}
for canonical, keys in candidates.items():
for key in keys:
coerced = _coerce_int(token_usage.get(key))
if coerced is not None and coerced > 0:
out[canonical] = coerced
break
# Derive a missing or implausibly-zero field if the other two are present.
# Some providers report ``input_tokens=0`` / ``output_tokens=0`` next to a
# real ``total_tokens`` — treat those zeros as missing so we don't silently
# store nonsense breakdowns.
def _missing_or_zero(key: str) -> bool:
return out.get(key) in (None, 0)
if "total_tokens" not in out and out.get("input_tokens") and out.get("output_tokens"):
out["total_tokens"] = out["input_tokens"] + out["output_tokens"]
if _missing_or_zero("output_tokens") and out.get("total_tokens") and out.get("input_tokens"):
derived = out["total_tokens"] - out["input_tokens"]
if derived > 0:
out["output_tokens"] = derived
if _missing_or_zero("input_tokens") and out.get("total_tokens") and out.get("output_tokens"):
derived = out["total_tokens"] - out["output_tokens"]
if derived > 0:
out["input_tokens"] = derived
return out
def _classify_exception(exc: BaseException) -> tuple[str, str]:
"""Return (error_type, error_message). Message is trimmed to 500 chars."""
name = exc.__class__.__name__
raw = (str(exc) or name).strip()
return name, (raw[:500] if len(raw) > 500 else raw)
class LlmMetricsMiddleware(AgentMiddleware[AgentState]):
"""Wrap each model call to time it and persist a metric row."""
def __init__(self, *, store: LlmMetricsStore | None = None, **kwargs: Any) -> None:
super().__init__(**kwargs)
self._store_override = store
def _store(self) -> LlmMetricsStore | None:
if self._store_override is not None:
return self._store_override
try:
sf = get_session_factory()
except Exception:
return None
return make_llm_metrics_store(sf)
def _build_base_record(self, request: ModelRequest) -> LlmMetricRecord:
return LlmMetricRecord(
id=uuid.uuid4().hex,
created_at=_now(),
user_id=get_effective_user_id(),
thread_id=_safe_get_thread_id(request),
run_id=_safe_get_run_id(request),
agent_name=_safe_get_agent_name(request),
model_name=_safe_get_model_name(request),
)
def _finalize_success(self, record: LlmMetricRecord, response: ModelResponse, started: float) -> None:
elapsed = max(0.0, time.monotonic() - started)
record.duration_ms = int(elapsed * 1000)
usage = _extract_usage(response)
record.input_tokens = usage.get("input_tokens")
record.output_tokens = usage.get("output_tokens")
record.total_tokens = usage.get("total_tokens") or (
(record.input_tokens or 0) + (record.output_tokens or 0) or None
)
if record.output_tokens is not None and elapsed > 0:
record.tokens_per_sec = round(record.output_tokens / elapsed, 3)
record.status = "success"
def _finalize_error(self, record: LlmMetricRecord, exc: BaseException, started: float) -> None:
record.duration_ms = int(max(0.0, time.monotonic() - started) * 1000)
record.status = "error"
record.error_type, record.error_message = _classify_exception(exc)
def _flush(self, record: LlmMetricRecord) -> None:
store = self._store()
if store is None:
return
# Route the best-effort write onto the engine's home loop. Doing
# ``asyncio.run(store.record(...))`` here (when the model call ran in a worker
# thread) would reuse the global engine's pooled connections on a fresh loop and
# raise "got Future attached to a different loop" — harmless (caught below) but
# log-spammy and pool-churning under concurrency. See ``fire_and_forget_db_write``.
try:
fire_and_forget_db_write(store.record(record))
except Exception:
logger.warning("LlmMetricsMiddleware: failed to flush metric %s", record.id, exc_info=True)
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
record = self._build_base_record(request)
started = time.monotonic()
try:
response = handler(request)
except GraphBubbleUp:
# LangGraph control flow — not a real LLM failure.
raise
except Exception as exc:
self._finalize_error(record, exc, started)
self._flush(record)
raise
self._finalize_success(record, response, started)
self._flush(record)
return response
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
record = self._build_base_record(request)
started = time.monotonic()
try:
response = await handler(request)
except GraphBubbleUp:
raise
except Exception as exc:
self._finalize_error(record, exc, started)
self._flush(record)
raise
self._finalize_success(record, response, started)
self._flush(record)
return response
@@ -0,0 +1,389 @@
"""Middleware to detect and break repetitive tool call loops.
P0 safety: prevents the agent from calling the same tool with the same
arguments indefinitely until the recursion limit kills the run.
Detection strategy:
1. After each model response, hash the tool calls (name + args).
2. Track recent hashes in a sliding window.
3. If the same hash appears >= warn_threshold times, inject a
"you are repeating yourself — wrap up" system message (once per hash).
4. If it appears >= hard_limit times, strip all tool_calls from the
response so the agent is forced to produce a final text answer.
"""
import hashlib
import json
import logging
import threading
from collections import OrderedDict, defaultdict
from copy import deepcopy
from typing import override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import HumanMessage
from langgraph.runtime import Runtime
logger = logging.getLogger(__name__)
# Defaults — can be overridden via constructor
_DEFAULT_WARN_THRESHOLD = 8 # inject warning after 8 identical calls
_DEFAULT_HARD_LIMIT = 20 # force-stop after 20 identical calls
_DEFAULT_WINDOW_SIZE = 60 # track last N tool calls (must be >= hard_limit)
_DEFAULT_MAX_TRACKED_THREADS = 100 # LRU eviction limit
_DEFAULT_TOOL_FREQ_WARN = 80 # warn after 80 calls to the same tool type
_DEFAULT_TOOL_FREQ_HARD_LIMIT = 120 # force-stop after 120 calls to the same tool type
def _normalize_tool_call_args(raw_args: object) -> tuple[dict, str | None]:
"""Normalize tool call args to a dict plus an optional fallback key.
Some providers serialize ``args`` as a JSON string instead of a dict.
We defensively parse those cases so loop detection does not crash while
still preserving a stable fallback key for non-dict payloads.
"""
if isinstance(raw_args, dict):
return raw_args, None
if isinstance(raw_args, str):
try:
parsed = json.loads(raw_args)
except (TypeError, ValueError, json.JSONDecodeError):
return {}, raw_args
if isinstance(parsed, dict):
return parsed, None
return {}, json.dumps(parsed, sort_keys=True, default=str)
if raw_args is None:
return {}, None
return {}, json.dumps(raw_args, sort_keys=True, default=str)
def _stable_tool_key(name: str, args: dict, fallback_key: str | None) -> str:
"""Derive a stable key from salient args without overfitting to noise."""
if name == "read_file" and fallback_key is None:
path = args.get("path") or ""
start_line = args.get("start_line")
end_line = args.get("end_line")
bucket_size = 200
try:
start_line = int(start_line) if start_line is not None else 1
except (TypeError, ValueError):
start_line = 1
try:
end_line = int(end_line) if end_line is not None else start_line
except (TypeError, ValueError):
end_line = start_line
start_line, end_line = sorted((start_line, end_line))
bucket_start = max(start_line, 1)
bucket_end = max(end_line, 1)
bucket_start = (bucket_start - 1) // bucket_size
bucket_end = (bucket_end - 1) // bucket_size
return f"{path}:{bucket_start}-{bucket_end}"
# write_file / str_replace are content-sensitive: same path may be updated
# with different payloads during iteration. Using only salient fields (path)
# can collapse distinct calls, so we hash full args to reduce false positives.
if name in {"write_file", "str_replace"}:
if fallback_key is not None:
return fallback_key
return json.dumps(args, sort_keys=True, default=str)
salient_fields = ("path", "url", "query", "command", "pattern", "glob", "cmd")
stable_args = {field: args[field] for field in salient_fields if args.get(field) is not None}
if stable_args:
return json.dumps(stable_args, sort_keys=True, default=str)
if fallback_key is not None:
return fallback_key
return json.dumps(args, sort_keys=True, default=str)
def _hash_tool_calls(tool_calls: list[dict]) -> str:
"""Deterministic hash of a set of tool calls (name + stable key).
This is intended to be order-independent: the same multiset of tool calls
should always produce the same hash, regardless of their input order.
"""
# Normalize each tool call to a stable (name, key) structure.
normalized: list[str] = []
for tc in tool_calls:
name = tc.get("name", "")
args, fallback_key = _normalize_tool_call_args(tc.get("args", {}))
key = _stable_tool_key(name, args, fallback_key)
normalized.append(f"{name}:{key}")
# Sort so permutations of the same multiset of calls yield the same ordering.
normalized.sort()
blob = json.dumps(normalized, sort_keys=True, default=str)
return hashlib.md5(blob.encode()).hexdigest()[:12]
_WARNING_MSG = "[LOOP DETECTED] You are repeating the same tool calls. Stop calling tools and produce your final answer now. If you cannot complete the task, summarize what you accomplished so far."
_TOOL_FREQ_WARNING_MSG = (
"[LOOP DETECTED] You have called {tool_name} {count} times without producing a final answer. Stop calling tools and produce your final answer now. If you cannot complete the task, summarize what you accomplished so far."
)
_HARD_STOP_MSG = "[FORCED STOP] Repeated tool calls exceeded the safety limit. Producing final answer with results collected so far."
_TOOL_FREQ_HARD_STOP_MSG = "[FORCED STOP] Tool {tool_name} called {count} times — exceeded the per-tool safety limit. Producing final answer with results collected so far."
class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
"""Detects and breaks repetitive tool call loops.
Args:
warn_threshold: Number of identical tool call sets before injecting
a warning message. Default: 8.
hard_limit: Number of identical tool call sets before stripping
tool_calls entirely. Default: 20.
window_size: Size of the sliding window for tracking calls.
Default: 60.
max_tracked_threads: Maximum number of threads to track before
evicting the least recently used. Default: 100.
tool_freq_warn: Number of calls to the same tool *type* (regardless
of arguments) before injecting a frequency warning. Catches
cross-file read loops that hash-based detection misses.
Default: 80.
tool_freq_hard_limit: Number of calls to the same tool type before
forcing a stop. Default: 120.
"""
def __init__(
self,
warn_threshold: int = _DEFAULT_WARN_THRESHOLD,
hard_limit: int = _DEFAULT_HARD_LIMIT,
window_size: int = _DEFAULT_WINDOW_SIZE,
max_tracked_threads: int = _DEFAULT_MAX_TRACKED_THREADS,
tool_freq_warn: int = _DEFAULT_TOOL_FREQ_WARN,
tool_freq_hard_limit: int = _DEFAULT_TOOL_FREQ_HARD_LIMIT,
):
super().__init__()
self.warn_threshold = warn_threshold
self.hard_limit = hard_limit
self.window_size = window_size
self.max_tracked_threads = max_tracked_threads
self.tool_freq_warn = tool_freq_warn
self.tool_freq_hard_limit = tool_freq_hard_limit
self._lock = threading.Lock()
# Per-thread tracking using OrderedDict for LRU eviction
self._history: OrderedDict[str, list[str]] = OrderedDict()
self._warned: dict[str, set[str]] = defaultdict(set)
# Per-thread, per-tool-type cumulative call counts
self._tool_freq: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
self._tool_freq_warned: dict[str, set[str]] = defaultdict(set)
def _get_thread_id(self, runtime: Runtime) -> str:
"""Extract thread_id from runtime context for per-thread tracking."""
thread_id = runtime.context.get("thread_id") if runtime.context else None
if thread_id:
return thread_id
return "default"
def _evict_if_needed(self) -> None:
"""Evict least recently used threads if over the limit.
Must be called while holding self._lock.
"""
while len(self._history) > self.max_tracked_threads:
evicted_id, _ = self._history.popitem(last=False)
self._warned.pop(evicted_id, None)
self._tool_freq.pop(evicted_id, None)
self._tool_freq_warned.pop(evicted_id, None)
logger.debug("Evicted loop tracking for thread %s (LRU)", evicted_id)
def _track_and_check(self, state: AgentState, runtime: Runtime) -> tuple[str | None, bool]:
"""Track tool calls and check for loops.
Two detection layers:
1. **Hash-based** (existing): catches identical tool call sets.
2. **Frequency-based** (new): catches the same *tool type* being
called many times with varying arguments (e.g. ``read_file``
on 40 different files).
Returns:
(warning_message_or_none, should_hard_stop)
"""
messages = state.get("messages", [])
if not messages:
return None, False
last_msg = messages[-1]
if getattr(last_msg, "type", None) != "ai":
return None, False
tool_calls = getattr(last_msg, "tool_calls", None)
if not tool_calls:
return None, False
thread_id = self._get_thread_id(runtime)
call_hash = _hash_tool_calls(tool_calls)
with self._lock:
# Touch / create entry (move to end for LRU)
if thread_id in self._history:
self._history.move_to_end(thread_id)
else:
self._history[thread_id] = []
self._evict_if_needed()
history = self._history[thread_id]
history.append(call_hash)
if len(history) > self.window_size:
history[:] = history[-self.window_size :]
count = history.count(call_hash)
tool_names = [tc.get("name", "?") for tc in tool_calls]
# --- Layer 1: hash-based (identical call sets) ---
if count >= self.hard_limit:
logger.error(
"Loop hard limit reached — forcing stop",
extra={
"thread_id": thread_id,
"call_hash": call_hash,
"count": count,
"tools": tool_names,
},
)
return _HARD_STOP_MSG, True
if count >= self.warn_threshold:
warned = self._warned[thread_id]
if call_hash not in warned:
warned.add(call_hash)
logger.warning(
"Repetitive tool calls detected — injecting warning",
extra={
"thread_id": thread_id,
"call_hash": call_hash,
"count": count,
"tools": tool_names,
},
)
return _WARNING_MSG, False
# --- Layer 2: per-tool-type frequency ---
freq = self._tool_freq[thread_id]
for tc in tool_calls:
name = tc.get("name", "")
if not name:
continue
freq[name] += 1
tc_count = freq[name]
if tc_count >= self.tool_freq_hard_limit:
logger.error(
"Tool frequency hard limit reached — forcing stop",
extra={
"thread_id": thread_id,
"tool_name": name,
"count": tc_count,
},
)
return _TOOL_FREQ_HARD_STOP_MSG.format(tool_name=name, count=tc_count), True
if tc_count >= self.tool_freq_warn:
warned = self._tool_freq_warned[thread_id]
if name not in warned:
warned.add(name)
logger.warning(
"Tool frequency warning — too many calls to same tool type",
extra={
"thread_id": thread_id,
"tool_name": name,
"count": tc_count,
},
)
return _TOOL_FREQ_WARNING_MSG.format(tool_name=name, count=tc_count), False
return None, False
@staticmethod
def _append_text(content: str | list | None, text: str) -> str | list:
"""Append *text* to AIMessage content, handling str, list, and None.
When content is a list of content blocks (e.g. Anthropic thinking mode),
we append a new ``{"type": "text", ...}`` block instead of concatenating
a string to a list, which would raise ``TypeError``.
"""
if content is None:
return text
if isinstance(content, list):
return [*content, {"type": "text", "text": f"\n\n{text}"}]
if isinstance(content, str):
return content + f"\n\n{text}"
# Fallback: coerce unexpected types to str to avoid TypeError
return str(content) + f"\n\n{text}"
@staticmethod
def _build_hard_stop_update(last_msg, content: str | list) -> dict:
"""Clear tool-call metadata so forced-stop messages serialize as plain assistant text."""
update = {
"tool_calls": [],
"content": content,
}
additional_kwargs = dict(getattr(last_msg, "additional_kwargs", {}) or {})
for key in ("tool_calls", "function_call"):
additional_kwargs.pop(key, None)
update["additional_kwargs"] = additional_kwargs
response_metadata = deepcopy(getattr(last_msg, "response_metadata", {}) or {})
if response_metadata.get("finish_reason") == "tool_calls":
response_metadata["finish_reason"] = "stop"
update["response_metadata"] = response_metadata
return update
def _apply(self, state: AgentState, runtime: Runtime) -> dict | None:
warning, hard_stop = self._track_and_check(state, runtime)
if hard_stop:
# Strip tool_calls from the last AIMessage to force text output
messages = state.get("messages", [])
last_msg = messages[-1]
content = self._append_text(last_msg.content, warning or _HARD_STOP_MSG)
stripped_msg = last_msg.model_copy(update=self._build_hard_stop_update(last_msg, content))
return {"messages": [stripped_msg]}
if warning:
# Inject as HumanMessage instead of SystemMessage to avoid
# Anthropic's "multiple non-consecutive system messages" error.
# Anthropic models require system messages only at the start of
# the conversation; injecting one mid-conversation crashes
# langchain_anthropic's _format_messages(). HumanMessage works
# with all providers. See #1299.
return {"messages": [HumanMessage(content=warning, name="loop_warning")]}
return None
@override
def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
return self._apply(state, runtime)
@override
async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict | None:
return self._apply(state, runtime)
def reset(self, thread_id: str | None = None) -> None:
"""Clear tracking state. If thread_id given, clear only that thread."""
with self._lock:
if thread_id:
self._history.pop(thread_id, None)
self._warned.pop(thread_id, None)
self._tool_freq.pop(thread_id, None)
self._tool_freq_warned.pop(thread_id, None)
else:
self._history.clear()
self._warned.clear()
self._tool_freq.clear()
self._tool_freq_warned.clear()
@@ -0,0 +1,262 @@
"""记忆机制中间件 (Memory V2)。
本中间件负责两件事:
1. **wrap_model_call** —— Hindsight 动态召回注入。
每次 LLM 调用前,用最近一条用户消息作为 query 召回 Hindsight 记忆,
作为一条带 ``<memory-context>`` 标签的消息**临时**追加到本次模型请求里。
关键:用 ``wrap_model_call`` 而非 ``before_model`` —— 注入只作用于这一次
模型调用,不写入持久 state,因此不会泄漏给前端、也不会在历史里堆积。
仅在 ``provider="hindsight"`` 且配置允许时生效;builtin 的 frozen
snapshot 走系统提示词,不在这里。
2. **after_agent** —— Hindsight 自动 retain。
Hindsight ``auto_retain`` 开启时,把本轮对话写入工作 bank。
LLM 主动写入走 ``memory`` / ``hindsight_*`` 工具,不经过本中间件。
"""
import asyncio
import logging
from typing import TYPE_CHECKING, Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import AIMessage, HumanMessage
from langgraph.config import get_config
from langgraph.runtime import Runtime
from deerflow.agents.memory.manager import build_memory_manager
from deerflow.agents.memory.message_processing import count_user_turns, filter_messages_for_memory
from deerflow.config.memory_config import get_effective_memory_config, get_memory_config
from deerflow.runtime.user_context import get_effective_user_id
if TYPE_CHECKING:
from deerflow.config.memory_config import MemoryConfig
logger = logging.getLogger(__name__)
def _coerce_text(content: Any) -> str:
"""把消息 content (可能是 str 或多模态 block 列表) 压成纯文本。"""
if isinstance(content, str):
return content
if isinstance(content, list):
parts: list[str] = []
for block in content:
if isinstance(block, str):
parts.append(block)
elif isinstance(block, dict) and block.get("type") == "text":
parts.append(str(block.get("text", "")))
return " ".join(parts)
return str(content or "")
def _latest_human_text(messages: list) -> str:
"""返回最近一条用户消息的纯文本。"""
for msg in reversed(messages):
if isinstance(msg, HumanMessage):
return _coerce_text(msg.content).strip()
return ""
def _last_exchange(filtered_messages: list) -> tuple[str, str]:
"""从过滤后的消息里取最后一轮 (用户输入, 助手回复) 的纯文本。"""
user_text = ""
assistant_text = ""
for msg in reversed(filtered_messages):
if not assistant_text and isinstance(msg, AIMessage):
assistant_text = _coerce_text(msg.content).strip()
elif not user_text and isinstance(msg, HumanMessage):
user_text = _coerce_text(msg.content).strip()
if user_text and assistant_text:
break
return user_text, assistant_text
class MemoryMiddlewareState(AgentState):
"""Compatible with the `ThreadState` schema."""
pass
class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
"""记忆中间件:wrap_model_call 注入 Hindsight 召回,after_agent 自动 retain。
Memory V2 说明:
- builtin 本地记忆的 frozen snapshot 走系统提示词 (``_get_memory_context``)。
- Hindsight 动态召回走本中间件 ``wrap_model_call`` —— 临时注入,不落 state。
"""
state_schema = MemoryMiddlewareState
def __init__(self, agent_name: str | None = None, *, memory_config: "MemoryConfig | None" = None, injection_enabled: bool = True):
"""初始化 MemoryMiddleware。
Args:
agent_name: 提供时记忆按 agent 隔离;None 用默认 agent。
memory_config: 显式记忆配置;省略时用全局配置。
injection_enabled: 运行时开关;``False`` 时跳过 Hindsight 动态召回注入。
"""
super().__init__()
self._agent_name = agent_name
self._memory_config = memory_config
self._injection_enabled = injection_enabled
# ---- 运行时上下文解析 -------------------------------------------------
def _resolve_thread_id(self, runtime: Runtime | None) -> str | None:
"""从 runtime context 取 thread_id,回退到 LangGraph configurable。"""
thread_id = None
if runtime is not None and getattr(runtime, "context", None):
thread_id = runtime.context.get("thread_id")
if thread_id:
return thread_id
try:
return get_config().get("configurable", {}).get("thread_id")
except RuntimeError:
return None
def _resolve_agent_id(self, runtime: Runtime | None) -> str | None:
"""解析 agent_id;优先 middleware 构造时的 agent_name,再 runtime context。
无 agent 上下文时返回 None,使 V1 记忆存入全局文件(users/{id}/memory.json)。
"""
if self._agent_name:
return self._agent_name
if runtime is not None and getattr(runtime, "context", None):
agent_id = runtime.context.get("agent_id")
if agent_id:
return str(agent_id)
return None
# ---- wrap_model_call:Hindsight 动态召回注入 -------------------------
def _build_recall_message(self, request: Any) -> HumanMessage | None:
"""按本次模型请求构建一条 Hindsight 召回消息;无召回内容时返回 None。
召回结果包在 ``<memory-context>`` 标签里并带系统提示,告诉模型这是
背景信息而非用户的新输入。
**跳过开关**:若 ``runtime.context.memory_recall_disabled`` 为真,直接
返回 None。圆桌规划等临时性任务(intent / recommend / leader / special)
不需要从用户个人记忆里召回,Hindsight HTTP 同步阻塞会显著增加 LLM 首
字节延迟(前端"调度中"卡顿);由路由层通过 ``_run_payload`` 的 context
字段统一关闭。
"""
runtime = getattr(request, "runtime", None)
if runtime is not None and getattr(runtime, "context", None):
if runtime.context.get("memory_recall_disabled"):
return None
if not self._injection_enabled:
return None
config = self._memory_config or get_memory_config()
if not config.enabled:
return None
user_id = get_effective_user_id()
effective_config = get_effective_memory_config(user_id)
if not effective_config.enabled or not effective_config.injection.enabled:
return None
# 只有 Hindsight 提供动态召回;builtin 走系统提示词。
if effective_config.provider != "hindsight" or not effective_config.injection.include_hindsight:
return None
messages = getattr(request, "messages", None) or []
query = _latest_human_text(messages)
if not query:
return None
runtime = getattr(request, "runtime", None)
thread_id = self._resolve_thread_id(runtime)
try:
manager = build_memory_manager(
user_id=user_id,
agent_id=self._resolve_agent_id(runtime),
thread_id=thread_id,
config=effective_config,
)
recall = manager.prefetch_all(query, thread_id=thread_id or "")
except Exception as exc: # noqa: BLE001 - 召回失败不能阻断对话
logger.debug("Hindsight 召回注入失败 (非致命):%s", exc)
return None
if not recall or not recall.strip():
return None
tag = effective_config.injection.context_tag
fenced = (
f"<{tag}>\n"
"[系统提示:以下是召回的记忆上下文,不是用户的新输入,作为背景信息参考。]\n\n"
f"{recall}\n"
f"</{tag}>"
)
return HumanMessage(content=fenced)
@override
def wrap_model_call(self, request: Any, handler: Any) -> Any:
"""模型调用前临时注入 Hindsight 召回 (同步路径)。"""
recall_msg = self._build_recall_message(request)
if recall_msg is not None:
request = request.override(messages=[*request.messages, recall_msg])
return handler(request)
@override
async def awrap_model_call(self, request: Any, handler: Any) -> Any:
"""模型调用前临时注入 Hindsight 召回 (异步路径)。
召回过程是同步阻塞 (含 Hindsight HTTP),放到线程池里跑以免阻塞事件循环。
"""
recall_msg = await asyncio.to_thread(self._build_recall_message, request)
if recall_msg is not None:
request = request.override(messages=[*request.messages, recall_msg])
return await handler(request)
# ---- after_agent:Hindsight 自动 retain -------------------------------
@override
def after_agent(self, state: MemoryMiddlewareState, runtime: Runtime) -> dict | None:
"""agent 完成后把本轮对话写入 Hindsight 工作 bank。
Returns:
None (本中间件不改状态)。
"""
config = self._memory_config or get_memory_config()
if not config.enabled:
return None
user_id = get_effective_user_id()
effective_config = get_effective_memory_config(user_id)
if effective_config.provider != "hindsight" or not effective_config.hindsight.auto_retain:
return None
messages = state.get("messages", [])
if not messages:
return None
filtered_messages = filter_messages_for_memory(messages)
user_text, assistant_text = _last_exchange(filtered_messages)
if not user_text or not assistant_text:
return None
# 轮次序号按对话历史算出 —— provider 每轮被重建、无法自行计数,
# retain_every_n_turns 的节流必须靠这个外部传入的值。
turn_index = count_user_turns(filtered_messages)
thread_id = self._resolve_thread_id(runtime)
try:
manager = build_memory_manager(
user_id=user_id,
agent_id=self._resolve_agent_id(runtime),
thread_id=thread_id,
config=effective_config,
)
manager.sync_all(
user_text,
assistant_text,
thread_id=thread_id or "",
turn_index=turn_index,
)
except Exception as exc: # noqa: BLE001 - 写入失败不能阻断对话
logger.warning("Hindsight retain 失败:%s", exc)
return None
@@ -0,0 +1,468 @@
"""Cap deliverable tools for position-roundtable seats.
Weak models (especially after a first successful Markdown write) often call
``write_file`` again with another copy of the same report, or call
``present_files`` twice for the same path, and loop until the recursion
limit kills the run. The UI then shows two identical "Successfully
presented files" cards even though only one file exists on disk.
When the run context carries ``position_artifact_cap`` (set by the position-
roundtable UI for ordinary seats and the summary agent — **not** for
action-plan, which must emit report + JSON), this middleware:
1. Truncates excess outputs ``write_file`` **and** ``present_files`` calls in
a single model response (keeps only the first *N* of each), including
raw provider metadata.
2. Rejects further such calls once *N* successful *or* earlier in-batch
calls already exist in the current user turn (so parallel tool calls
cannot race past the cap).
3. Ends the turn when the only remaining calls were excess writes/presents.
4. Injects a brief hidden reminder before the next model call:
- write done, not yet presented → present once, then wrap up;
- write **and** present already done → wrap up, do **not** present again.
"""
from __future__ import annotations
import json
import logging
from collections.abc import Awaitable, Callable
from copy import deepcopy
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware, hook_config
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
from langchain_core.messages import HumanMessage, ToolMessage
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.runtime import Runtime
from langgraph.types import Command
logger = logging.getLogger(__name__)
_CONTEXT_KEY = "position_artifact_cap"
_OUTPUTS_PREFIX = "/mnt/user-data/outputs"
_WRITE_TOOL = "write_file"
_PRESENT_TOOL = "present_files"
_REJECT_WRITE = (
"本席位本轮产物上限已达:outputs 下只允许写入一份交付文件。"
"请勿再次调用 write_file;若尚未呈现文件请调用 present_files,"
"然后用简短文字说明交付已完成。"
)
_REJECT_PRESENT = (
"本席位本轮产物已经呈现过一次,请勿再次调用 present_files。"
"用一两句话说明交付已完成即可,不要再调用任何文件工具。"
)
_REMINDER_NEED_PRESENT = (
"【系统提示】本席位本轮产物文件已成功写入 outputs。"
"禁止再次调用 write_file 生成第二份(或相同)产物。"
"请立即 present_files(仅此一次,如尚未呈现),并给出简短收尾回复后结束本轮。"
)
_REMINDER_DONE = (
"【系统提示】本席位本轮产物已写入 outputs 并且已经 present_files 呈现过。"
"禁止再次调用 write_file 或 present_files。"
"请只用一两句话收尾说明交付已完成,不要再调用任何工具。"
)
def _normalize_args(raw_args: object) -> dict[str, Any]:
if isinstance(raw_args, dict):
return raw_args
if isinstance(raw_args, str):
try:
parsed = json.loads(raw_args)
except (TypeError, ValueError, json.JSONDecodeError):
return {}
return parsed if isinstance(parsed, dict) else {}
return {}
def _tool_field(tool_call: Any, key: str, default: Any = None) -> Any:
if isinstance(tool_call, dict):
return tool_call.get(key, default)
getter = getattr(tool_call, "get", None)
if callable(getter):
return getter(key, default)
return getattr(tool_call, key, default)
def _is_outputs_path(path: object) -> bool:
text = str(path or "").strip().replace("\\", "/")
if not text:
return False
if text == _OUTPUTS_PREFIX or text.startswith(f"{_OUTPUTS_PREFIX}/"):
return True
lowered = text.lstrip("./")
return lowered == "outputs" or lowered.startswith("outputs/")
def _tool_call_writes_outputs(tool_call: Any) -> bool:
if _tool_field(tool_call, "name") != _WRITE_TOOL:
return False
args = _normalize_args(_tool_field(tool_call, "args"))
return _is_outputs_path(args.get("path"))
def _tool_call_is_present(tool_call: Any) -> bool:
return _tool_field(tool_call, "name") == _PRESENT_TOOL
def _is_successful_tool_result(content: str) -> bool:
text = content.strip()
if not text or text.startswith("Error"):
return False
return True
def _cap_from_mapping(mapping: object) -> int | None:
if not isinstance(mapping, dict):
return None
raw = mapping.get(_CONTEXT_KEY)
if raw is None or raw is False:
return None
try:
value = int(raw)
except (TypeError, ValueError):
return None
return value if value > 0 else None
def _cap_from_runtime(runtime: object | None) -> int | None:
if runtime is None:
return None
context = getattr(runtime, "context", None)
cap = _cap_from_mapping(context)
if cap is not None:
return cap
config = getattr(runtime, "config", None)
if not isinstance(config, dict):
return None
for bucket_key in ("configurable", "metadata", "context"):
cap = _cap_from_mapping(config.get(bucket_key))
if cap is not None:
return cap
return None
def _is_visible_human(message: Any) -> bool:
if getattr(message, "type", None) != "human":
return False
kwargs = getattr(message, "additional_kwargs", None) or {}
if kwargs.get("hide_from_ui"):
return False
name = getattr(message, "name", None)
if name in {"loop_warning", "position_artifact_cap"}:
return False
return True
def _current_turn_start(messages: list[Any]) -> int:
for index in range(len(messages) - 1, -1, -1):
if _is_visible_human(messages[index]):
return index
return 0
def _collect_call_ids(messages: list[Any], *, turn_start: int, match: Callable[[Any], bool]) -> set[str]:
ids: set[str] = set()
for message in messages[turn_start:]:
if getattr(message, "type", None) != "ai":
continue
for tool_call in getattr(message, "tool_calls", None) or []:
if not match(tool_call):
continue
call_id = _tool_field(tool_call, "id")
if isinstance(call_id, str) and call_id:
ids.add(call_id)
return ids
def _count_successful_tools(
messages: list[Any],
*,
turn_start: int,
match: Callable[[Any], bool],
) -> int:
matching_ids = _collect_call_ids(messages, turn_start=turn_start, match=match)
success = 0
for message in messages[turn_start:]:
if getattr(message, "type", None) != "tool":
continue
call_id = getattr(message, "tool_call_id", None)
if not isinstance(call_id, str) or call_id not in matching_ids:
continue
content = str(getattr(message, "content", "") or "")
if _is_successful_tool_result(content):
success += 1
return success
def _successful_outputs_writes(messages: list[Any], *, turn_start: int) -> int:
"""Count successful outputs ``write_file`` calls in the current user turn."""
return _count_successful_tools(messages, turn_start=turn_start, match=_tool_call_writes_outputs)
def _successful_presents(messages: list[Any], *, turn_start: int) -> int:
"""Count successful ``present_files`` calls in the current user turn."""
return _count_successful_tools(messages, turn_start=turn_start, match=_tool_call_is_present)
def _kept_call_ids(tool_calls: list[Any]) -> set[str]:
ids: set[str] = set()
for tool_call in tool_calls:
call_id = _tool_field(tool_call, "id")
if isinstance(call_id, str) and call_id:
ids.add(call_id)
return ids
def _build_truncated_update(last_msg: Any, kept: list[Any]) -> dict[str, Any]:
"""Replace structured tool_calls and keep raw provider metadata in sync."""
update: dict[str, Any] = {"tool_calls": kept}
additional_kwargs = dict(getattr(last_msg, "additional_kwargs", {}) or {})
raw_calls = additional_kwargs.get("tool_calls")
kept_ids = _kept_call_ids(kept)
if isinstance(raw_calls, list) and raw_calls:
if not kept:
additional_kwargs.pop("tool_calls", None)
additional_kwargs.pop("function_call", None)
else:
filtered = [item for item in raw_calls if isinstance(item, dict) and item.get("id") in kept_ids]
if filtered:
additional_kwargs["tool_calls"] = filtered
else:
additional_kwargs.pop("tool_calls", None)
additional_kwargs.pop("function_call", None)
elif not kept:
additional_kwargs.pop("tool_calls", None)
additional_kwargs.pop("function_call", None)
update["additional_kwargs"] = additional_kwargs
if not kept:
response_metadata = deepcopy(getattr(last_msg, "response_metadata", {}) or {})
if response_metadata.get("finish_reason") == "tool_calls":
response_metadata["finish_reason"] = "stop"
update["response_metadata"] = response_metadata
return update
def _in_flight_siblings(
messages: list[Any],
*,
current_id: str | None,
match: Callable[[Any], bool],
) -> int:
"""Earlier same-batch tool calls that would consume the same budget."""
if not current_id:
return 0
last_ai = None
for message in reversed(messages):
if getattr(message, "type", None) == "ai":
last_ai = message
break
if last_ai is None:
return 0
batch = list(getattr(last_ai, "tool_calls", None) or [])
if current_id not in {str(_tool_field(tool_call, "id") or "") for tool_call in batch}:
return 0
used = 0
for tool_call in batch:
call_id = str(_tool_field(tool_call, "id") or "")
if call_id == current_id:
break
if match(tool_call):
used += 1
return used
def _outputs_budget_used(messages: list[Any], *, turn_start: int, current_id: str | None) -> int:
return _successful_outputs_writes(messages, turn_start=turn_start) + _in_flight_siblings(
messages, current_id=current_id, match=_tool_call_writes_outputs
)
def _present_budget_used(messages: list[Any], *, turn_start: int, current_id: str | None) -> int:
return _successful_presents(messages, turn_start=turn_start) + _in_flight_siblings(
messages, current_id=current_id, match=_tool_call_is_present
)
def _reminder_for(*, writes_done: bool, presents_done: bool) -> str | None:
if not writes_done:
return None
if presents_done:
return _REMINDER_DONE
return _REMINDER_NEED_PRESENT
class PositionArtifactCapMiddleware(AgentMiddleware[AgentState]):
"""Enforce a per-turn outputs write/present budget for position roundtable."""
state_schema = AgentState
def _truncate_excess(self, state: AgentState, runtime: Runtime) -> dict | None:
cap = _cap_from_runtime(runtime)
if cap is None:
return None
messages = list(state.get("messages") or [])
if not messages:
return None
last_msg = messages[-1]
if getattr(last_msg, "type", None) != "ai":
return None
tool_calls = list(getattr(last_msg, "tool_calls", None) or [])
if not tool_calls:
return None
turn_start = _current_turn_start(messages)
prior = messages[:-1]
remaining_writes = max(0, cap - _successful_outputs_writes(prior, turn_start=turn_start))
remaining_presents = max(0, cap - _successful_presents(prior, turn_start=turn_start))
kept: list[Any] = []
dropped = 0
kept_writes = 0
kept_presents = 0
for tool_call in tool_calls:
if _tool_call_writes_outputs(tool_call):
if kept_writes >= remaining_writes:
dropped += 1
continue
kept_writes += 1
elif _tool_call_is_present(tool_call):
if kept_presents >= remaining_presents:
dropped += 1
continue
kept_presents += 1
kept.append(tool_call)
if dropped == 0:
return None
logger.warning(
"Position artifact cap truncated %s excess write_file/present_files call(s) "
"(cap=%s, remaining_writes=%s, remaining_presents=%s)",
dropped,
cap,
remaining_writes,
remaining_presents,
)
updated = last_msg.model_copy(update=_build_truncated_update(last_msg, kept))
result: dict[str, Any] = {"messages": [updated]}
if not kept:
# No remaining tools — stop instead of looping back to the model
# which would just emit another copy of write_file / present_files.
result["jump_to"] = "end"
return result
def _reject_over_cap(self, request: ToolCallRequest) -> ToolMessage | None:
tool_call = getattr(request, "tool_call", None) or {}
is_write = _tool_call_writes_outputs(tool_call)
is_present = _tool_call_is_present(tool_call)
if not is_write and not is_present:
return None
runtime = getattr(request, "runtime", None)
cap = _cap_from_runtime(runtime)
if cap is None:
return None
state = getattr(request, "state", None) or {}
messages = list(state.get("messages") or []) if isinstance(state, dict) else []
current_id = str(_tool_field(tool_call, "id") or "")
turn_start = _current_turn_start(messages)
if is_write:
used = _outputs_budget_used(messages, turn_start=turn_start, current_id=current_id or None)
reject_text = _REJECT_WRITE
tool_name = _WRITE_TOOL
else:
used = _present_budget_used(messages, turn_start=turn_start, current_id=current_id or None)
reject_text = _REJECT_PRESENT
tool_name = _PRESENT_TOOL
if used < cap:
return None
logger.warning(
"Position artifact cap rejected %s (cap=%s, used=%s, id=%s)",
tool_name,
cap,
used,
current_id,
)
return ToolMessage(
content=f"Error: {reject_text}",
tool_call_id=current_id,
name=tool_name,
)
def _maybe_remind(self, request: ModelRequest) -> ModelRequest:
cap = _cap_from_runtime(getattr(request, "runtime", None))
if cap is None:
return request
messages = list(getattr(request, "messages", None) or [])
turn_start = _current_turn_start(messages)
writes_done = _successful_outputs_writes(messages, turn_start=turn_start) >= cap
presents_done = _successful_presents(messages, turn_start=turn_start) >= cap
text = _reminder_for(writes_done=writes_done, presents_done=presents_done)
if text is None:
return request
reminder = HumanMessage(
content=text,
name="position_artifact_cap",
additional_kwargs={"hide_from_ui": True, "lc_source": "position_artifact_cap"},
)
return request.override(messages=[*messages, reminder])
@hook_config(can_jump_to=["end"])
@override
def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
return self._truncate_excess(state, runtime)
@hook_config(can_jump_to=["end"])
@override
async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict | None:
return self._truncate_excess(state, runtime)
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
rejected = self._reject_over_cap(request)
if rejected is not None:
return rejected
return handler(request)
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command:
rejected = self._reject_over_cap(request)
if rejected is not None:
return rejected
return await handler(request)
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
return handler(self._maybe_remind(request))
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
return await handler(self._maybe_remind(request))
@@ -0,0 +1,78 @@
"""Middleware that injects the admin-configured prompt prefix at model-call time.
The prompt-prefix feature lets an admin prepend a fixed instruction to the
user's question before it reaches the LLM. To keep the prefix invisible in the
chat UI, the Gateway does **not** concatenate it into the persisted
``HumanMessage.content``; instead it tags the first human message with
``additional_kwargs["prompt_prefix"]`` (see ``app.gateway.services``).
This middleware reads that tag and prepends the prefix to the message content
*only in the request handed to the model*. The persisted state — and therefore
what the frontend renders — keeps the clean, prefix-free content.
"""
from collections.abc import Awaitable, Callable
from typing import override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
from langchain_core.messages import HumanMessage
PROMPT_PREFIX_KEY = "prompt_prefix"
class PromptPrefixMiddleware(AgentMiddleware[AgentState]):
"""Prepends ``additional_kwargs['prompt_prefix']`` to human messages for the LLM only.
The transformation is applied to the model request copy, never written back
to state, so it is naturally idempotent across the multiple model calls of a
single turn.
"""
@staticmethod
def _apply(messages: list) -> list | None:
"""Return a patched copy with prefixes prepended, or None if nothing to do."""
patched: list | None = None
for idx, msg in enumerate(messages):
if not isinstance(msg, HumanMessage):
continue
raw_prefix = (getattr(msg, "additional_kwargs", None) or {}).get(PROMPT_PREFIX_KEY)
prefix = str(raw_prefix).strip() if raw_prefix else ""
if not prefix:
continue
content = msg.content
if isinstance(content, str):
new_content: object = f"{prefix}\n\n{content}".strip("\n")
elif isinstance(content, list):
# Structured content (text blocks + media): prepend a text block.
new_content = [{"type": "text", "text": prefix}, *content]
else:
new_content = f"{prefix}\n\n{content!s}"
if patched is None:
patched = list(messages)
# model_copy preserves the message id so streaming dedup is unaffected.
patched[idx] = msg.model_copy(update={"content": new_content})
return patched
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
patched = self._apply(request.messages)
if patched is not None:
request = request.override(messages=patched)
return handler(request)
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
patched = self._apply(request.messages)
if patched is not None:
request = request.override(messages=patched)
return await handler(request)
@@ -0,0 +1,131 @@
"""Inject stable citation numbering before RAG final answers."""
from __future__ import annotations
import json
import logging
import os
from pathlib import Path
from collections.abc import Awaitable, Callable
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
from langchain_core.messages import HumanMessage
from deerflow.runtime.references import (
build_latest_reference_prompt,
build_reference_debug_payload,
build_reference_debug_summary,
)
logger = logging.getLogger(__name__)
_RAG_DEBUG_LOGGER_NAME = "rag_citation_debug"
def _get_rag_debug_logger() -> logging.Logger:
debug_logger = logging.getLogger(_RAG_DEBUG_LOGGER_NAME)
if getattr(debug_logger, "_rag_file_configured", False):
return debug_logger
log_path = Path(os.environ.get("RAG_CITATION_DEBUG_LOG", "logs/rag_citation_debug.log"))
if not log_path.is_absolute():
log_path = Path.cwd() / log_path
log_path.parent.mkdir(parents=True, exist_ok=True)
handler = logging.FileHandler(log_path, encoding="utf-8")
handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
debug_logger.addHandler(handler)
debug_logger.setLevel(logging.INFO)
debug_logger.propagate = False
setattr(debug_logger, "_rag_file_configured", True)
setattr(debug_logger, "_rag_file_path", str(log_path))
return debug_logger
def _log_rag_debug(message: str, *args: Any) -> None:
logger.info(message, *args)
_get_rag_debug_logger().info(message, *args)
class RagCitationMiddleware(AgentMiddleware[AgentState]):
"""Give the model the same numbered references the frontend will render."""
@staticmethod
def _enabled(request: ModelRequest) -> bool:
runtime = getattr(request, "runtime", None)
context = getattr(runtime, "context", None) if runtime is not None else None
if isinstance(context, dict) and context.get("rag_mode_enabled"):
return True
config = getattr(runtime, "config", None) if runtime is not None else None
if isinstance(config, dict):
configurable = config.get("configurable")
if isinstance(configurable, dict) and configurable.get("rag_mode_enabled"):
return True
runtime_context = config.get("context")
if isinstance(runtime_context, dict) and runtime_context.get("rag_mode_enabled"):
return True
return False
@staticmethod
def _patch(request: ModelRequest) -> ModelRequest | None:
if not RagCitationMiddleware._enabled(request):
return None
messages = list(request.messages)
prompt, batch = build_latest_reference_prompt(messages)
if not prompt:
_log_rag_debug(
"middleware reference-prompt enabled=true prompt=false messages=%s",
len(messages),
)
return None
summary = build_reference_debug_summary(messages, [batch] if batch else None)
_log_rag_debug(
"middleware reference-prompt enabled=true prompt=true single_batch=true messages=%s "
"tool_messages=%s raw_items=%s normalized_items=%s kept_items=%s latest_batch_id=%s "
"latest_batch_sources=%s",
summary["messages"],
summary["tool_messages"],
summary["raw_items"],
summary["normalized_items"],
summary["kept_items"],
(batch or {}).get("id"),
len((batch or {}).get("sources") or []),
)
_log_rag_debug(
"middleware reference-prompt-payload %s",
json.dumps(
build_reference_debug_payload(
messages=messages,
batch=batch,
prompt=prompt,
),
ensure_ascii=False,
default=str,
),
)
patched_messages = [
*messages,
HumanMessage(
content=prompt,
additional_kwargs={"hide_from_ui": True, "lc_source": "rag_citation"},
),
]
return request.override(messages=patched_messages)
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
patched = self._patch(request)
return handler(patched or request)
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
patched = self._patch(request)
return await handler(patched or request)
@@ -0,0 +1,363 @@
"""SandboxAuditMiddleware - bash command security auditing."""
import json
import logging
import re
import shlex
from collections.abc import Awaitable, Callable
from datetime import UTC, datetime
from typing import override
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import ToolMessage
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.types import Command
from deerflow.agents.thread_state import ThreadState
logger = logging.getLogger(__name__)
# ---------------------------------------------------------------------------
# Command classification rules
# ---------------------------------------------------------------------------
# Each pattern is compiled once at import time.
_HIGH_RISK_PATTERNS: list[re.Pattern[str]] = [
# --- original rules (retained) ---
re.compile(r"rm\s+-[^\s]*r[^\s]*\s+(/\*?|~/?\*?|/home\b|/root\b)\s*$"),
re.compile(r"dd\s+if="),
re.compile(r"mkfs"),
re.compile(r"cat\s+/etc/shadow"),
re.compile(r">+\s*/etc/"),
# --- pipe to sh/bash (generalised, replaces old curl|sh rule) ---
re.compile(r"\|\s*(ba)?sh\b"),
# --- command substitution (targeted – only dangerous executables) ---
re.compile(r"[`$]\(?\s*(curl|wget|bash|sh|python|ruby|perl|base64)"),
# --- base64 decode piped to execution ---
re.compile(r"base64\s+.*-d.*\|"),
# --- overwrite system binaries ---
re.compile(r">+\s*(/usr/bin/|/bin/|/sbin/)"),
# --- overwrite shell startup files ---
re.compile(r">+\s*~/?\.(bashrc|profile|zshrc|bash_profile)"),
# --- process environment leakage ---
re.compile(r"/proc/[^/]+/environ"),
# --- dynamic linker hijack (one-step escalation) ---
re.compile(r"\b(LD_PRELOAD|LD_LIBRARY_PATH)\s*="),
# --- bash built-in networking (bypasses tool allowlists) ---
re.compile(r"/dev/tcp/"),
# --- fork bomb ---
re.compile(r"\S+\(\)\s*\{[^}]*\|\s*\S+\s*&"), # :(){ :|:& };:
re.compile(r"while\s+true.*&\s*done"), # while true; do bash & done
]
_MEDIUM_RISK_PATTERNS: list[re.Pattern[str]] = [
re.compile(r"chmod\s+777"),
re.compile(r"pip3?\s+install"),
re.compile(r"apt(-get)?\s+install"),
# sudo/su: no-op under Docker root; warn so LLM is aware
re.compile(r"\b(sudo|su)\b"),
# PATH modification: long attack chain, warn rather than block
re.compile(r"\bPATH\s*="),
]
def _split_compound_command(command: str) -> list[str]:
"""Split a compound command into sub-commands (quote-aware).
Scans the raw command string so unquoted shell control operators are
recognised even when they are not surrounded by whitespace
(e.g. ``safe;rm -rf /`` or ``rm -rf /&&echo ok``). Operators inside
quotes are ignored. If the command ends with an unclosed quote or a
dangling escape, return the whole command unchanged (fail-closed —
safer to classify the unsplit string than silently drop parts).
"""
parts: list[str] = []
current: list[str] = []
in_single_quote = False
in_double_quote = False
escaping = False
index = 0
while index < len(command):
char = command[index]
if escaping:
current.append(char)
escaping = False
index += 1
continue
if char == "\\" and not in_single_quote:
current.append(char)
escaping = True
index += 1
continue
if char == "'" and not in_double_quote:
in_single_quote = not in_single_quote
current.append(char)
index += 1
continue
if char == '"' and not in_single_quote:
in_double_quote = not in_double_quote
current.append(char)
index += 1
continue
if not in_single_quote and not in_double_quote:
if command.startswith("&&", index) or command.startswith("||", index):
part = "".join(current).strip()
if part:
parts.append(part)
current = []
index += 2
continue
if char == ";":
part = "".join(current).strip()
if part:
parts.append(part)
current = []
index += 1
continue
current.append(char)
index += 1
# Unclosed quote or dangling escape → fail-closed, return whole command
if in_single_quote or in_double_quote or escaping:
return [command]
part = "".join(current).strip()
if part:
parts.append(part)
return parts if parts else [command]
def _classify_single_command(command: str) -> str:
"""Classify a single (non-compound) command. Return 'block', 'warn', or 'pass'."""
normalized = " ".join(command.split())
for pattern in _HIGH_RISK_PATTERNS:
if pattern.search(normalized):
return "block"
# Also try shlex-parsed tokens for high-risk detection
try:
tokens = shlex.split(command)
joined = " ".join(tokens)
for pattern in _HIGH_RISK_PATTERNS:
if pattern.search(joined):
return "block"
except ValueError:
# shlex.split fails on unclosed quotes — treat as suspicious
return "block"
for pattern in _MEDIUM_RISK_PATTERNS:
if pattern.search(normalized):
return "warn"
return "pass"
def _classify_command(command: str) -> str:
"""Return 'block', 'warn', or 'pass'.
Strategy:
1. First scan the *whole* raw command against high-risk patterns. This
catches structural attacks like ``while true; do bash & done`` or
``:(){ :|:& };:`` that span multiple shell statements — splitting them
on ``;`` would destroy the pattern context.
2. Then split compound commands (e.g. ``cmd1 && cmd2 ; cmd3``) and
classify each sub-command independently. The most severe verdict wins.
"""
# Pass 1: whole-command high-risk scan (catches multi-statement patterns)
normalized = " ".join(command.split())
for pattern in _HIGH_RISK_PATTERNS:
if pattern.search(normalized):
return "block"
# Pass 2: per-sub-command classification
sub_commands = _split_compound_command(command)
worst = "pass"
for sub in sub_commands:
verdict = _classify_single_command(sub)
if verdict == "block":
return "block" # short-circuit: can't get worse
if verdict == "warn":
worst = "warn"
return worst
# ---------------------------------------------------------------------------
# Middleware
# ---------------------------------------------------------------------------
class SandboxAuditMiddleware(AgentMiddleware[ThreadState]):
"""Bash command security auditing middleware.
For every ``bash`` tool call:
1. **Command classification**: regex + shlex analysis grades commands as
high-risk (block), medium-risk (warn), or safe (pass).
2. **Audit log**: every bash call is recorded as a structured JSON entry
via the standard logger (visible in langgraph.log).
High-risk commands (e.g. ``rm -rf /``, ``curl url | bash``) are blocked:
the handler is not called and an error ``ToolMessage`` is returned so the
agent loop can continue gracefully.
Medium-risk commands (e.g. ``pip install``, ``chmod 777``) are executed
normally; a warning is appended to the tool result so the LLM is aware.
"""
state_schema = ThreadState
# ------------------------------------------------------------------
# Helpers
# ------------------------------------------------------------------
def _get_thread_id(self, request: ToolCallRequest) -> str | None:
runtime = request.runtime # ToolRuntime; may be None-like in tests
if runtime is None:
return None
ctx = getattr(runtime, "context", None) or {}
thread_id = ctx.get("thread_id") if isinstance(ctx, dict) else None
if thread_id is None:
cfg = getattr(runtime, "config", None) or {}
thread_id = cfg.get("configurable", {}).get("thread_id")
return thread_id
_AUDIT_COMMAND_LIMIT = 200
def _write_audit(self, thread_id: str | None, command: str, verdict: str, *, truncate: bool = False) -> None:
audited_command = command
if truncate and len(command) > self._AUDIT_COMMAND_LIMIT:
audited_command = f"{command[: self._AUDIT_COMMAND_LIMIT]}... ({len(command)} chars)"
record = {
"timestamp": datetime.now(UTC).isoformat(),
"thread_id": thread_id or "unknown",
"command": audited_command,
"verdict": verdict,
}
logger.info("[SandboxAudit] %s", json.dumps(record, ensure_ascii=False))
def _build_block_message(self, request: ToolCallRequest, reason: str) -> ToolMessage:
tool_call_id = str(request.tool_call.get("id") or "missing_id")
return ToolMessage(
content=f"Command blocked: {reason}. Please use a safer alternative approach.",
tool_call_id=tool_call_id,
name="bash",
status="error",
)
def _append_warn_to_result(self, result: ToolMessage | Command, command: str) -> ToolMessage | Command:
"""Append a warning note to the tool result for medium-risk commands."""
if not isinstance(result, ToolMessage):
return result
warning = f"\n\n⚠️ Warning: `{command}` is a medium-risk command that may modify the runtime environment."
if isinstance(result.content, list):
new_content = list(result.content) + [{"type": "text", "text": warning}]
else:
new_content = str(result.content) + warning
return ToolMessage(
content=new_content,
tool_call_id=result.tool_call_id,
name=result.name,
status=result.status,
)
# ------------------------------------------------------------------
# Input sanitisation
# ------------------------------------------------------------------
# Normal bash commands rarely exceed a few hundred characters. 10 000 is
# well above any legitimate use case yet a tiny fraction of Linux ARG_MAX.
# Anything longer is almost certainly a payload injection or base64-encoded
# attack string.
_MAX_COMMAND_LENGTH = 10_000
def _validate_input(self, command: str) -> str | None:
"""Return ``None`` if *command* is acceptable, else a rejection reason."""
if not command.strip():
return "empty command"
if len(command) > self._MAX_COMMAND_LENGTH:
return "command too long"
if "\x00" in command:
return "null byte detected"
return None
# ------------------------------------------------------------------
# Core logic (shared between sync and async paths)
# ------------------------------------------------------------------
def _pre_process(self, request: ToolCallRequest) -> tuple[str, str | None, str, str | None]:
"""
Returns (command, thread_id, verdict, reject_reason).
verdict is 'block', 'warn', or 'pass'.
reject_reason is non-None only for input sanitisation rejections.
"""
args = request.tool_call.get("args", {})
raw_command = args.get("command")
command = raw_command if isinstance(raw_command, str) else ""
thread_id = self._get_thread_id(request)
# ① input sanitisation — reject malformed input before regex analysis
reject_reason = self._validate_input(command)
if reject_reason:
self._write_audit(thread_id, command, "block", truncate=True)
logger.warning("[SandboxAudit] INVALID INPUT thread=%s reason=%s", thread_id, reject_reason)
return command, thread_id, "block", reject_reason
# ② classify command
verdict = _classify_command(command)
# ③ audit log
self._write_audit(thread_id, command, verdict)
if verdict == "block":
logger.warning("[SandboxAudit] BLOCKED thread=%s cmd=%r", thread_id, command)
elif verdict == "warn":
logger.warning("[SandboxAudit] WARN (medium-risk) thread=%s cmd=%r", thread_id, command)
return command, thread_id, verdict, None
# ------------------------------------------------------------------
# wrap_tool_call hooks
# ------------------------------------------------------------------
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
if request.tool_call.get("name") != "bash":
return handler(request)
command, _, verdict, reject_reason = self._pre_process(request)
if verdict == "block":
reason = reject_reason or "security violation detected"
return self._build_block_message(request, reason)
result = handler(request)
if verdict == "warn":
result = self._append_warn_to_result(result, command)
return result
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command:
if request.tool_call.get("name") != "bash":
return await handler(request)
command, _, verdict, reject_reason = self._pre_process(request)
if verdict == "block":
reason = reject_reason or "security violation detected"
return self._build_block_message(request, reason)
result = await handler(request)
if verdict == "warn":
result = self._append_warn_to_result(result, command)
return result
@@ -0,0 +1,118 @@
"""Approval middleware for the custom-agent setup tool."""
from __future__ import annotations
import logging
from hashlib import sha256
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware, hook_config
from langchain_core.messages import AIMessage, ToolMessage
from langgraph.runtime import Runtime
logger = logging.getLogger(__name__)
class SetupAgentApprovalMiddlewareState(AgentState):
"""Compatible with the DeerFlow thread state schema."""
pass
class SetupAgentApprovalMiddleware(AgentMiddleware[SetupAgentApprovalMiddlewareState]):
"""Stop before ``setup_agent`` writes files and ask the user to approve.
The interception runs in ``after_model``: as soon as the model emits an
AIMessage that contains a ``setup_agent`` tool call (and the run has not
been pre-approved via ``setup_agent_approved=True`` in runtime context),
we append a structured approval ``ToolMessage`` and return
``jump_to="end"`` to terminate the LangGraph run *before* the tool node
executes. This is the LangChain-recommended way to short-circuit after
the model; using ``wrap_tool_call`` + ``Command(goto=END)`` proved
unreliable when the AIMessage contained multiple parallel tool calls
(the ``Command`` got mixed with normal tool outputs and the graph
looped back to the model instead of terminating).
"""
state_schema = SetupAgentApprovalMiddlewareState
def _is_approved(self, runtime: Runtime) -> bool:
context = getattr(runtime, "context", None) or {}
if not isinstance(context, dict):
return False
return context.get("setup_agent_approved") is True
def _stable_message_id(self, tool_call_id: str, args: dict[str, Any]) -> str:
if tool_call_id:
return f"setup-agent-approval:{tool_call_id}"
digest = sha256(repr(sorted(args.items())).encode("utf-8")).hexdigest()[:16]
return f"setup-agent-approval:{digest}"
def _build_payload(self, args: dict[str, Any]) -> dict[str, Any]:
skills = args.get("skills")
return {
"name": str(args.get("name") or "").strip(),
"description": str(args.get("description") or "").strip(),
"soul": str(args.get("soul") or "").strip(),
"skills": skills if isinstance(skills, list) else [],
}
def _intercept(self, last: AIMessage) -> dict[str, Any] | None:
"""Return a state update if setup_agent must be gated; None to passthrough."""
tool_calls = list(last.tool_calls or [])
setup_call = next((tc for tc in tool_calls if tc.get("name") == "setup_agent"), None)
if setup_call is None:
return None
args = setup_call.get("args") or {}
tool_call_id = setup_call.get("id") or ""
if isinstance(args.get("skills"), list) and len(args["skills"]) > 5:
args = {**args, "skills": args["skills"][:5]}
payload = self._build_payload(args)
logger.info("Setup agent approval requested before writing agent files")
approval_msg = ToolMessage(
id=self._stable_message_id(tool_call_id, args),
content="请确认是否创建/更新这个智能体配置。",
tool_call_id=tool_call_id,
name="setup_agent",
additional_kwargs={"setup_agent_approval": payload},
)
# Any other tool_calls on the same AIMessage are left dangling; the
# existing DanglingToolCallMiddleware will inject placeholder
# ToolMessages on the next model invocation, which matches the
# desired semantics: every action pauses until the user approves.
return {
"messages": [approval_msg],
"jump_to": "end",
}
@hook_config(can_jump_to=["end"])
@override
def after_model(
self,
state: SetupAgentApprovalMiddlewareState,
runtime: Runtime,
) -> dict[str, Any] | None:
if self._is_approved(runtime):
return None
messages = state.get("messages") or []
if not messages:
return None
last = messages[-1]
if not isinstance(last, AIMessage):
return None
return self._intercept(last)
@hook_config(can_jump_to=["end"])
@override
async def aafter_model(
self,
state: SetupAgentApprovalMiddlewareState,
runtime: Runtime,
) -> dict[str, Any] | None:
return self.after_model(state, runtime)
@@ -0,0 +1,113 @@
"""Approval middleware for the report-structure setup tool.
与 ``SetupWritingApprovalMiddleware`` 同构:模型在「智能新增报告结构」里调用
``setup_report_structure`` 时,于 ``after_model`` 拦截,附上一条结构化审批 ToolMessage
(建议字段打包在 ``additional_kwargs["setup_report_structure_approval"]``)并
``jump_to="end"`` 立即结束本轮——前端据此渲染确认卡,用户点「应用到表单」后回填右侧表单。
"""
from __future__ import annotations
import logging
from hashlib import sha256
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware, hook_config
from langchain_core.messages import AIMessage, ToolMessage
from langgraph.runtime import Runtime
from deerflow.persistence.report_structures.directions import normalize_retrieval_directions
from deerflow.persistence.report_structures.skills import normalize_retrieval_skills
logger = logging.getLogger(__name__)
class SetupReportStructureApprovalMiddlewareState(AgentState):
"""Compatible with the DeerFlow thread state schema."""
pass
class SetupReportStructureApprovalMiddleware(AgentMiddleware[SetupReportStructureApprovalMiddlewareState]):
"""Stop before ``setup_report_structure`` and ask the user to apply the proposed config."""
state_schema = SetupReportStructureApprovalMiddlewareState
def _is_approved(self, runtime: Runtime) -> bool:
context = getattr(runtime, "context", None) or {}
if not isinstance(context, dict):
return False
return context.get("setup_report_structure_approved") is True
def _stable_message_id(self, tool_call_id: str, args: dict[str, Any]) -> str:
if tool_call_id:
return f"setup-report-structure-approval:{tool_call_id}"
digest = sha256(repr(sorted(args.items())).encode("utf-8")).hexdigest()[:16]
return f"setup-report-structure-approval:{digest}"
def _normalize_mode(self, raw: Any) -> str:
text = str(raw or "").strip().lower()
if text in {"fixed", "固定", "固定大纲"}:
return "fixed"
return "adaptive"
def _build_payload(self, args: dict[str, Any]) -> dict[str, Any]:
return {
"title": str(args.get("title") or "").strip()[:256],
"name": str(args.get("name") or "").strip()[:256],
"content": str(args.get("content") or "").strip(),
"structure_mode": self._normalize_mode(args.get("structure_mode")),
"retrieval_directions": normalize_retrieval_directions(args.get("retrieval_directions")),
"retrieval_skills": normalize_retrieval_skills(args.get("retrieval_skills")),
}
def _intercept(self, last: AIMessage) -> dict[str, Any] | None:
tool_calls = list(last.tool_calls or [])
setup_call = next((tc for tc in tool_calls if tc.get("name") == "setup_report_structure"), None)
if setup_call is None:
return None
args = setup_call.get("args") or {}
tool_call_id = setup_call.get("id") or ""
payload = self._build_payload(args)
logger.info("Setup report-structure approval requested before applying config")
approval_msg = ToolMessage(
id=self._stable_message_id(tool_call_id, args),
content="请确认是否把这份报告结构应用到表单。",
tool_call_id=tool_call_id,
name="setup_report_structure",
additional_kwargs={"setup_report_structure_approval": payload},
)
return {
"messages": [approval_msg],
"jump_to": "end",
}
@hook_config(can_jump_to=["end"])
@override
def after_model(
self,
state: SetupReportStructureApprovalMiddlewareState,
runtime: Runtime,
) -> dict[str, Any] | None:
if self._is_approved(runtime):
return None
messages = state.get("messages") or []
if not messages:
return None
last = messages[-1]
if not isinstance(last, AIMessage):
return None
return self._intercept(last)
@hook_config(can_jump_to=["end"])
@override
async def aafter_model(
self,
state: SetupReportStructureApprovalMiddlewareState,
runtime: Runtime,
) -> dict[str, Any] | None:
return self.after_model(state, runtime)
@@ -0,0 +1,135 @@
"""Approval middleware for the AI-writing config setup tool.
与 ``SetupAgentApprovalMiddleware`` 同构:模型在「写作配置 Q&A」里调用 ``setup_writing``
时,于 ``after_model`` 拦截,附上一条结构化审批 ToolMessage(建议的写作配置打包在
``additional_kwargs["setup_writing_approval"]``)并 ``jump_to="end"`` 立即结束本轮运行——
前端据此渲染审批卡,用户点「应用到表单」后把这些字段回填到左侧写作表单。
"""
from __future__ import annotations
import logging
from hashlib import sha256
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware, hook_config
from langchain_core.messages import AIMessage, ToolMessage
from langgraph.runtime import Runtime
logger = logging.getLogger(__name__)
class SetupWritingApprovalMiddlewareState(AgentState):
"""Compatible with the DeerFlow thread state schema."""
pass
class SetupWritingApprovalMiddleware(AgentMiddleware[SetupWritingApprovalMiddlewareState]):
"""Stop before ``setup_writing`` and ask the user to apply the proposed config.
See ``SetupAgentApprovalMiddleware`` for the rationale behind intercepting in
``after_model`` + ``jump_to="end"`` (robust against parallel tool calls).
"""
state_schema = SetupWritingApprovalMiddlewareState
def _is_approved(self, runtime: Runtime) -> bool:
context = getattr(runtime, "context", None) or {}
if not isinstance(context, dict):
return False
return context.get("setup_writing_approved") is True
def _stable_message_id(self, tool_call_id: str, args: dict[str, Any]) -> str:
if tool_call_id:
return f"setup-writing-approval:{tool_call_id}"
digest = sha256(repr(sorted(args.items())).encode("utf-8")).hexdigest()[:16]
return f"setup-writing-approval:{digest}"
def _coerce_word_count(self, raw: Any) -> int | None:
if isinstance(raw, bool): # bool 是 int 子类,先排除
return None
if isinstance(raw, int):
return raw if raw > 0 else None
if isinstance(raw, float):
return int(raw) if raw > 0 else None
if isinstance(raw, str):
import re
m = re.search(r"\d[\d,]*", raw)
if m:
try:
value = int(m.group().replace(",", ""))
return value if value > 0 else None
except ValueError:
return None
return None
def _build_payload(self, args: dict[str, Any]) -> dict[str, Any]:
# 素材来源:仅当模型明确给出 "skill" 时才用技能检索;用户没明确要求就一律默认知识库。
material_source = (
"skill" if str(args.get("material_source") or "").strip() == "skill" else "knowledge_base"
)
return {
"user_intent": str(args.get("user_intent") or "").strip(),
"article_type": str(args.get("article_type") or "").strip(),
# 新(列表外)文章类型的一句话特征说明;命中已有类型时为空。
"article_type_detail": str(args.get("article_type_detail") or "").strip(),
"word_count_target": self._coerce_word_count(args.get("word_count_target")),
"target_audience": str(args.get("target_audience") or "").strip(),
"writing_mode": str(args.get("writing_mode") or "").strip(),
"material_source": material_source,
"outline": str(args.get("outline") or "").strip(),
}
def _intercept(self, last: AIMessage) -> dict[str, Any] | None:
"""Return a state update if setup_writing must be gated; None to passthrough."""
tool_calls = list(last.tool_calls or [])
setup_call = next((tc for tc in tool_calls if tc.get("name") == "setup_writing"), None)
if setup_call is None:
return None
args = setup_call.get("args") or {}
tool_call_id = setup_call.get("id") or ""
payload = self._build_payload(args)
logger.info("Setup writing approval requested before applying writing config")
approval_msg = ToolMessage(
id=self._stable_message_id(tool_call_id, args),
content="请确认是否把这份写作配置应用到表单。",
tool_call_id=tool_call_id,
name="setup_writing",
additional_kwargs={"setup_writing_approval": payload},
)
return {
"messages": [approval_msg],
"jump_to": "end",
}
@hook_config(can_jump_to=["end"])
@override
def after_model(
self,
state: SetupWritingApprovalMiddlewareState,
runtime: Runtime,
) -> dict[str, Any] | None:
if self._is_approved(runtime):
return None
messages = state.get("messages") or []
if not messages:
return None
last = messages[-1]
if not isinstance(last, AIMessage):
return None
return self._intercept(last)
@hook_config(can_jump_to=["end"])
@override
async def aafter_model(
self,
state: SetupWritingApprovalMiddlewareState,
runtime: Runtime,
) -> dict[str, Any] | None:
return self.after_model(state, runtime)
@@ -0,0 +1,54 @@
"""SkillReviewMiddleware — triggers background skill review after each agent turn.
Hooks into ``after_agent``: once the lead agent graph has finished a full turn,
this middleware counts the tool calls made and, if the threshold is met, hands
the conversation messages to the SkillReviewWorker as a background asyncio task.
No blocking I/O or LLM calls happen in-band — the review runs fully in the
background and never delays the HTTP response.
"""
from __future__ import annotations
import logging
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langgraph.runtime import Runtime
from deerflow.config.app_config import get_app_config
from deerflow.runtime.user_context import get_effective_user_id
from deerflow.skills.review_worker import maybe_start_review
logger = logging.getLogger(__name__)
class SkillReviewMiddlewareState(AgentState):
"""Minimal state schema — only needs ``messages``."""
pass
class SkillReviewMiddleware(AgentMiddleware[SkillReviewMiddlewareState]):
"""Dispatch a background skill review after every substantial agent turn.
'Substantial' is defined by ``skill_evolution.review_worker.min_tool_calls``
(default 5). Turns below the threshold are silently skipped to avoid
wasting LLM tokens on trivial exchanges.
"""
state_schema = SkillReviewMiddlewareState
@override
def after_agent(self, state: Any, runtime: Runtime) -> None:
"""Fire background review; never raises — failures are logged only."""
try:
app_config = get_app_config()
messages = state.get("messages", []) if hasattr(state, "get") else []
thread_id: str = runtime.context.get("thread_id", "") if runtime.context else ""
if not thread_id:
return
user_id = get_effective_user_id()
maybe_start_review(thread_id, messages, app_config, user_id)
except Exception:
logger.exception("SkillReviewMiddleware.after_agent: unexpected error (ignored)")
@@ -0,0 +1,158 @@
"""Middleware for intercepting skill calls and stopping execution when specific skills are invoked."""
import logging
import re
from collections.abc import Callable
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import ToolMessage
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.types import Command, interrupt
logger = logging.getLogger(__name__)
def extract_name_task(text: str) -> tuple[str, str]:
"""Extract `agent_name` and `task_content` from a bash invocation that triggers
a sub-agent via ``python3 scripts/agent_orchestration.py "<agent>" "<task>"``.
Returns empty strings when no match is found so the caller can treat the
absence of a match as "not a target skill call".
"""
try:
pattern = r'\.py\s+"([^"]*)"\s+"([^"]*)"'
match = re.search(pattern, text)
if match:
return match.group(1), match.group(2)
return "", ""
except Exception:
return "", ""
class SkillStopMiddlewareState(AgentState):
"""Compatible with the `ThreadState` schema."""
pass
class SkillStopMiddleware(AgentMiddleware[SkillStopMiddlewareState]):
"""Intercepts skill file reads and stops execution when specific skills are invoked.
When the model reads a file from a skill directory that matches one of the
configured skill names, this middleware:
1. Intercepts the tool call before execution
2. Returns a Command that stops execution (goes to END)
3. Optionally returns a message indicating which skill was triggered
This is useful for implementing "skill triggers" that pause the agent
when certain skills are about to be used.
"""
state_schema = SkillStopMiddlewareState
def __init__(
self,
*,
skill_names: list[str],
skills_root: str = "/mnt/skills",
stop_message: str | None = None,
stop_on_match: bool = True,
):
"""Initialize the skill stop middleware.
Args:
skill_names: List of skill names to intercept (e.g., ["newsletter-generation", "podcast-generation"]).
skills_root: Root directory where skills are located (default: "/mnt/skills").
stop_message: Optional message to return when stopping. If None, a default message is used.
stop_on_match: If True, stop when skill matches. If False, continue execution (for logging only).
"""
super().__init__()
self._skill_names = set(skill_names)
self._skills_root = skills_root.rstrip("/")
self._stop_message = stop_message
self._stop_on_match = stop_on_match
def _is_target_skill_call(self, tool_call: dict[str, Any]) -> str | None:
"""Return the matched skill name if this tool call invokes one of the
configured target skills, otherwise ``None``.
Two invocation patterns are recognized:
1. **Structured tool call** — the model emits a tool call whose ``name``
literally matches one of the configured skill names (e.g. the
multi-agent leader calling
``agent_orchestration({"agent_name": "...", "task": "..."})``).
This is the natural form most LLMs produce when told to "use a
skill", and it's the form that drives the roundtable dispatch.
2. **Bash + argv** — the legacy form where the lead agent reaches into
a skill by running ``python3 scripts/<skill-name>.py "<arg1>" "<arg2>"``.
Kept for backward compatibility with skills that use bash for
dispatch.
"""
name = tool_call.get("name") or ""
lowered_targets = {s.lower() for s in self._skill_names}
# Pattern 1: structured tool call whose tool name IS the skill name.
if name and (name in self._skill_names or name.lower() in lowered_targets):
logger.info("SkillStopMiddleware: matched structured skill call name=%s", name)
return name
# Pattern 2: bash invocation with argv-style skill name.
if name == "bash" and "args" in tool_call:
skill_name, _ = extract_name_task(str(tool_call["args"]))
if skill_name and (skill_name in self._skill_names or skill_name.lower() in lowered_targets):
logger.info("SkillStopMiddleware: matched bash skill call name=%s", skill_name)
return skill_name
return None
def _handle_skill_stop(self, request: ToolCallRequest, skill_name: str) -> Command:
"""Build the stop response — an interrupt that includes a ToolMessage
describing which skill was triggered."""
logger.info("Skill stop triggered: skill_name=%s", skill_name)
tool_call_id = request.tool_call.get("id", "")
message_content = self._stop_message or f"⏹️ Skill '{skill_name}' triggered. Execution stopped."
tool_message = ToolMessage(
id=f"skill_stop:{tool_call_id}",
content=message_content,
tool_call_id=tool_call_id,
name="skill_stop",
)
return interrupt(
{
"messages": [tool_message],
"skill_name": skill_name,
}
)
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
matched_skill = self._is_target_skill_call(request.tool_call)
if matched_skill:
if self._stop_on_match:
return self._handle_skill_stop(request, matched_skill)
logger.info("Skill detected (not stopping): skill_name=%s", matched_skill)
return handler(request)
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
matched_skill = self._is_target_skill_call(request.tool_call)
if matched_skill:
if self._stop_on_match:
return self._handle_skill_stop(request, matched_skill)
logger.info("Skill detected (not stopping): skill_name=%s", matched_skill)
return await handler(request)
@@ -0,0 +1,75 @@
"""Middleware to enforce maximum concurrent subagent tool calls per model response."""
import logging
from typing import override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langgraph.runtime import Runtime
from deerflow.subagents.executor import MAX_CONCURRENT_SUBAGENTS
logger = logging.getLogger(__name__)
# Valid range for max_concurrent_subagents
MIN_SUBAGENT_LIMIT = 2
MAX_SUBAGENT_LIMIT = 4
def _clamp_subagent_limit(value: int) -> int:
"""Clamp subagent limit to valid range [2, 4]."""
return max(MIN_SUBAGENT_LIMIT, min(MAX_SUBAGENT_LIMIT, value))
class SubagentLimitMiddleware(AgentMiddleware[AgentState]):
"""Truncates excess 'task' tool calls from a single model response.
When an LLM generates more than max_concurrent parallel task tool calls
in one response, this middleware keeps only the first max_concurrent and
discards the rest. This is more reliable than prompt-based limits.
Args:
max_concurrent: Maximum number of concurrent subagent calls allowed.
Defaults to MAX_CONCURRENT_SUBAGENTS (3). Clamped to [2, 4].
"""
def __init__(self, max_concurrent: int = MAX_CONCURRENT_SUBAGENTS):
super().__init__()
self.max_concurrent = _clamp_subagent_limit(max_concurrent)
def _truncate_task_calls(self, state: AgentState) -> dict | None:
messages = state.get("messages", [])
if not messages:
return None
last_msg = messages[-1]
if getattr(last_msg, "type", None) != "ai":
return None
tool_calls = getattr(last_msg, "tool_calls", None)
if not tool_calls:
return None
# Count task tool calls
task_indices = [i for i, tc in enumerate(tool_calls) if tc.get("name") == "task"]
if len(task_indices) <= self.max_concurrent:
return None
# Build set of indices to drop (excess task calls beyond the limit)
indices_to_drop = set(task_indices[self.max_concurrent :])
truncated_tool_calls = [tc for i, tc in enumerate(tool_calls) if i not in indices_to_drop]
dropped_count = len(indices_to_drop)
logger.warning(f"Truncated {dropped_count} excess task tool call(s) from model response (limit: {self.max_concurrent})")
# Replace the AIMessage with truncated tool_calls (same id triggers replacement)
updated_msg = last_msg.model_copy(update={"tool_calls": truncated_tool_calls})
return {"messages": [updated_msg]}
@override
def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
return self._truncate_task_calls(state)
@override
async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict | None:
return self._truncate_task_calls(state)
@@ -0,0 +1,821 @@
"""Summarization middleware extensions for DeerFlow.
Unlike LangChain's stock ``SummarizationMiddleware`` (which runs in
``before_model`` and **persists** a destructive ``RemoveMessage(REMOVE_ALL_MESSAGES)``
to the checkpoint — wiping the original Q&A from both the model context *and*
the conversation the frontend renders), this middleware compresses the history
**transiently in ``wrap_model_call``**. The full original messages stay in state
(so the UI keeps showing the user's real conversation); only the message list
handed to the model for a single call is replaced with ``[summary, *recent]``.
The generated summary is cached per-thread so we don't pay an extra LLM call on
every model invocation: once a thread is summarized, the cached summary is reused
until enough *new* messages accumulate to push the compressed context back over
the trigger threshold (sticky boundary, mirroring the stock middleware's
post-compaction behavior).
"""
from __future__ import annotations
import logging
import threading
from collections import OrderedDict
from collections.abc import Awaitable, Callable, Collection
from dataclasses import dataclass
from typing import Any, Protocol, override, runtime_checkable
from langchain.agents import AgentState
from langchain.agents.middleware import SummarizationMiddleware
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
from langchain_core.messages import (
AIMessage,
AnyMessage,
HumanMessage,
SystemMessage,
ToolMessage,
message_to_dict,
messages_from_dict,
)
from langgraph.config import get_config
from langgraph.runtime import Runtime
logger = logging.getLogger(__name__)
# Upper bound on the per-thread summary cache so a long-lived process serving
# many threads can't grow it without limit. Oldest entries are evicted first.
_SUMMARY_CACHE_MAX_THREADS = 512
# After compaction the preserved window must land *comfortably* below every
# trigger threshold, otherwise the "compressed" context is still over the
# trigger and re-summarizes on the very next turn (the sticky boundary never
# sticks). We force the kept suffix down to this fraction of each trigger so a
# re-compaction only happens once meaningfully *new* content accumulates — not
# on every follow-up question. ``keep`` only sets a *target*; this is the hard
# headroom guarantee on top of it.
_KEEP_HEADROOM_FRACTION = 0.75
@dataclass(frozen=True)
class SummarizationEvent:
"""Context emitted before conversation history is summarized away."""
messages_to_summarize: tuple[AnyMessage, ...]
preserved_messages: tuple[AnyMessage, ...]
thread_id: str | None
agent_name: str | None
runtime: Runtime
@runtime_checkable
class BeforeSummarizationHook(Protocol):
"""Hook invoked before summarization removes messages from state."""
def __call__(self, event: SummarizationEvent) -> None: ...
def _resolve_thread_id(runtime: Runtime) -> str | None:
"""Resolve the current thread ID from runtime context or LangGraph config."""
thread_id = runtime.context.get("thread_id") if runtime.context else None
if thread_id is None:
try:
config_data = get_config()
except RuntimeError:
return None
thread_id = config_data.get("configurable", {}).get("thread_id")
return thread_id
def _resolve_agent_name(runtime: Runtime) -> str | None:
"""Resolve the current agent name from runtime context or LangGraph config."""
agent_name = runtime.context.get("agent_name") if runtime.context else None
if agent_name is None:
try:
config_data = get_config()
except RuntimeError:
return None
agent_name = config_data.get("configurable", {}).get("agent_name")
return agent_name
def _tool_call_path(tool_call: dict[str, Any]) -> str | None:
"""Best-effort extraction of a file path argument from a read_file-like tool call."""
args = tool_call.get("args") or {}
if not isinstance(args, dict):
return None
for key in ("path", "file_path", "filepath"):
value = args.get(key)
if isinstance(value, str) and value:
return value
return None
def _clone_ai_message(
message: AIMessage,
tool_calls: list[dict[str, Any]],
*,
content: Any | None = None,
) -> AIMessage:
"""Clone an AIMessage while replacing its tool_calls list and optional content."""
update: dict[str, Any] = {"tool_calls": tool_calls}
if content is not None:
update["content"] = content
return message.model_copy(update=update)
@dataclass
class _SkillBundle:
"""Skill-related tool calls and tool results associated with one AIMessage."""
ai_index: int
skill_tool_indices: tuple[int, ...]
skill_tool_call_ids: frozenset[str]
skill_tool_tokens: int
skill_key: str
@dataclass(frozen=True)
class _SummaryCacheEntry:
"""A cached, reusable summary for one thread.
``summarized_ids`` are the ids of the original messages folded into
``summary_text``. The cache is only reusable while every one of those ids is
still present in the live message list and no AIMessage/ToolMessage pair was
split when the boundary was drawn (``reusable``) — otherwise filtering by id
could orphan a tool result, so we fall back to re-summarizing.
"""
summarized_ids: frozenset[str]
summary_text: str
preserved_ids: frozenset[str] = frozenset()
preserved_messages: tuple[AnyMessage, ...] = ()
# Process-wide summary cache shared across every middleware instance.
#
# ``make_lead_agent`` rebuilds the agent — and therefore a *fresh*
# ``DeerFlowSummarizationMiddleware`` — on every run. If the cache lived on the
# instance (``self._summary_cache``) it would be empty at the start of each
# user turn, forcing a brand-new (blocking) summarization LLM call on *every*
# turn of a long conversation. Hoisting it to module scope, keyed by
# ``thread_id``, lets a summary computed on one turn be reused on the next,
# so only the first threshold crossing (or a genuine re-compaction) pays for an
# LLM call. A lock guards the non-atomic LRU eviction against concurrent
# threads (subagents / parallel conversations share this process).
_GLOBAL_SUMMARY_CACHE: OrderedDict[str, _SummaryCacheEntry] = OrderedDict()
_GLOBAL_SUMMARY_CACHE_LOCK = threading.Lock()
_STATE_CACHE_KEY = "context_summary_cache"
def _clear_global_summary_cache() -> None:
"""Drop every cached summary. Intended for tests/diagnostics only."""
with _GLOBAL_SUMMARY_CACHE_LOCK:
_GLOBAL_SUMMARY_CACHE.clear()
def _serialize_cache_entry(entry: _SummaryCacheEntry) -> dict[str, Any]:
"""Serialize a summary cache entry so it can live in LangGraph state."""
return {
"version": 1,
"summarized_ids": sorted(entry.summarized_ids),
"summary_text": entry.summary_text,
"preserved_ids": sorted(entry.preserved_ids),
"preserved_messages": [message_to_dict(message) for message in entry.preserved_messages],
}
def _deserialize_cache_entry(raw: Any) -> _SummaryCacheEntry | None:
"""Best-effort restore of a state-backed summary cache entry."""
if not isinstance(raw, dict):
return None
try:
summary_text = raw.get("summary_text")
if not isinstance(summary_text, str) or not summary_text:
return None
summarized_ids = raw.get("summarized_ids") or []
preserved_ids = raw.get("preserved_ids") or []
preserved_messages_raw = raw.get("preserved_messages") or []
if not isinstance(summarized_ids, list) or not isinstance(preserved_ids, list) or not isinstance(preserved_messages_raw, list):
return None
preserved_messages = tuple(messages_from_dict(preserved_messages_raw))
return _SummaryCacheEntry(
summarized_ids=frozenset(str(item) for item in summarized_ids if item is not None),
summary_text=summary_text,
preserved_ids=frozenset(str(item) for item in preserved_ids if item is not None),
preserved_messages=preserved_messages,
)
except Exception:
logger.debug("summarization: failed to restore state-backed summary cache", exc_info=True)
return None
def _has_nonempty_human_message(message: AnyMessage) -> bool:
"""Whether a message is a real, non-empty user turn.
Some OpenAI-compatible gateways reject a completion request that contains
only ``system`` / ``assistant`` / ``tool`` roles. That can legitimately
happen after compaction: the active model call is continuing a tool turn,
while the user request that started the turn has already moved into the
internal summary.
"""
if not isinstance(message, HumanMessage):
return False
content = message.content
if isinstance(content, str):
return bool(content.strip())
if isinstance(content, list):
return any(bool(block.strip()) if isinstance(block, str) else bool((block.get("text") or block.get("content") or "").strip()) if isinstance(block, dict) else False for block in content)
return bool(str(content).strip())
def _ensure_latest_human_message(
source_messages: list[AnyMessage],
compressed_messages: list[AnyMessage],
) -> list[AnyMessage]:
"""Keep the latest real user request visible to strict chat gateways.
The message is inserted after leading system messages, so it neither
exposes the internal summary to the UI nor splits an AI tool-call from its
following ToolMessages. When there was no user turn in the source at all,
do not fabricate one: that is an upstream caller bug and should remain
diagnosable rather than silently changing the task.
"""
if any(_has_nonempty_human_message(message) for message in compressed_messages):
return compressed_messages
latest_human = next(
(message for message in reversed(source_messages) if _has_nonempty_human_message(message)),
None,
)
if latest_human is None:
logger.warning("summarization: compressed model request has no user message and source history contains none; passing it through unchanged")
return compressed_messages
insert_at = 0
while insert_at < len(compressed_messages) and isinstance(compressed_messages[insert_at], SystemMessage):
insert_at += 1
return [*compressed_messages[:insert_at], latest_human, *compressed_messages[insert_at:]]
class DeerFlowSummarizationMiddleware(SummarizationMiddleware):
"""Summarization middleware with pre-compression hook dispatch and skill rescue."""
def __init__(
self,
*args,
skills_container_path: str | None = None,
skill_file_read_tool_names: Collection[str] | None = None,
before_summarization: list[BeforeSummarizationHook] | None = None,
preserve_recent_skill_count: int = 5,
preserve_recent_skill_tokens: int = 25_000,
preserve_recent_skill_tokens_per_skill: int = 5_000,
**kwargs,
) -> None:
super().__init__(*args, **kwargs)
self._skills_container_path = skills_container_path or "/mnt/skills"
self._skill_file_read_tool_names = frozenset(skill_file_read_tool_names or {"read_file", "read", "view", "cat"})
self._before_summarization_hooks = before_summarization or []
self._preserve_recent_skill_count = max(0, preserve_recent_skill_count)
self._preserve_recent_skill_tokens = max(0, preserve_recent_skill_tokens)
self._preserve_recent_skill_tokens_per_skill = max(0, preserve_recent_skill_tokens_per_skill)
# Per-thread cache of the most recent summary: thread_id -> (summarized message ids, summary text).
# Points at the *process-wide* cache (not a fresh per-instance dict) so a
# summary survives across runs/turns — see ``_GLOBAL_SUMMARY_CACHE``.
self._summary_cache: OrderedDict[str, _SummaryCacheEntry] = _GLOBAL_SUMMARY_CACHE
self._pending_state_cache_update: dict[str, Any] | None = None
@override
def before_model(self, state: AgentState, runtime: Runtime) -> dict | None:
"""Disable the stock middleware's destructive ``before_model`` compaction.
Compression now happens transiently in :meth:`wrap_model_call`, so the
persisted conversation (and the frontend's view of it) is never mutated.
"""
return None
@override
async def abefore_model(self, state: AgentState, runtime: Runtime) -> dict | None:
"""Async counterpart of :meth:`before_model` — also a no-op."""
return None
@override
def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
"""Persist the latest reusable summary cache into thread state."""
if self._pending_state_cache_update is None:
return None
update = self._pending_state_cache_update
self._pending_state_cache_update = None
return {_STATE_CACHE_KEY: update}
@override
async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict | None:
"""Async counterpart of :meth:`after_model`."""
return self.after_model(state, runtime)
# ---- wrap_model_call: transient, display-preserving compression ----------
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
compressed = self._compressed_messages(request)
if compressed is not None:
request = request.override(messages=compressed)
return handler(request)
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
compressed = await self._acompressed_messages(request)
if compressed is not None:
request = request.override(messages=compressed)
return await handler(request)
def _compressed_messages(self, request: ModelRequest) -> list[AnyMessage] | None:
"""Build the compressed message list for this call (sync summary path).
Returns ``None`` when no compression is needed (the request is passed
through untouched).
"""
plan = self._plan_compression(request)
if plan is None:
return None
action, payload = plan
if action == "reuse":
return payload # type: ignore[return-value]
# action == "summarize"
messages_to_summarize, preserved, thread_id = payload # type: ignore[misc]
self._emit_compacting_notice()
self._fire_hooks(messages_to_summarize, preserved, getattr(request, "runtime", None))
summary = self._create_summary(messages_to_summarize)
return self._finish_summarize(messages_to_summarize, preserved, summary, thread_id)
async def _acompressed_messages(self, request: ModelRequest) -> list[AnyMessage] | None:
"""Async counterpart of :meth:`_compressed_messages`."""
plan = self._plan_compression(request)
if plan is None:
return None
action, payload = plan
if action == "reuse":
return payload # type: ignore[return-value]
messages_to_summarize, preserved, thread_id = payload # type: ignore[misc]
self._emit_compacting_notice()
self._fire_hooks(messages_to_summarize, preserved, getattr(request, "runtime", None))
summary = await self._acreate_summary(messages_to_summarize)
return self._finish_summarize(messages_to_summarize, preserved, summary, thread_id)
@staticmethod
def _emit_compacting_notice() -> None:
"""Best-effort UI hint that a (blocking) summarization LLM call is starting.
Only the genuine summarize path calls this — the cheap cache-reuse path
does no LLM work and stays silent. Emitted on LangGraph's ``custom``
stream channel; the chat frontend renders it as a transient toast. A
no-op when there is no active stream writer (e.g. unit tests, non-stream
runs), so callers never branch.
"""
# Always leave a backend trace of the genuine (blocking) compaction, even
# when there is no stream writer to render the frontend toast (scheduled
# runs, channels, tests). Grep ``上下文压缩`` / ``context compaction`` in
# the Gateway log to confirm a real summarization LLM call fired.
logger.info("summarization: 上下文压缩(真正摘要,触发一次 LLM 调用) context compaction firing")
try:
from langgraph.config import get_stream_writer
writer = get_stream_writer()
except Exception:
return
if writer is None:
return
try:
writer({"type": "context_compacting", "message": "正在压缩上下文以容纳更长对话…"})
except Exception:
logger.debug("summarization: failed to emit context_compacting notice", exc_info=True)
def _plan_compression(
self,
request: ModelRequest,
) -> tuple[str, Any] | None:
"""Decide what to do for this model call, doing **no** LLM work.
Returns one of:
- ``None`` — pass the request through unchanged (no compression needed).
- ``("reuse", compressed_messages)`` — reuse the cached summary.
- ``("summarize", (messages_to_summarize, preserved, thread_id))`` — the
caller must run the (a)sync summarizer, then call
:meth:`_finish_summarize`.
"""
messages = list(getattr(request, "messages", None) or [])
if not messages:
return None
self._ensure_message_ids(messages)
# Threshold is the first gate: while the *full* current conversation is
# still under the configured trigger, there is nothing to compress —
# pass it through untouched. No cache lookup, no summary substitution.
# Compression only ever engages once the real context crosses the
# trigger, which is exactly when it is needed.
if not self._should_summarize(messages, self.token_counter(messages)):
return None
thread_id = self._resolve_request_thread_id(request)
if thread_id is None:
logger.debug("summarization: thread_id unresolved; cross-turn summary cache disabled for this call")
cached = self._get_cache_entry(thread_id) if thread_id else None
if cached is None:
cached = _deserialize_cache_entry(getattr(request, "state", {}).get(_STATE_CACHE_KEY))
if cached is not None and thread_id:
self._store_cache_entry(thread_id, cached)
present_ids = {m.id for m in messages}
cache_usable = cached is not None and cached.summarized_ids <= present_ids and cached.preserved_ids <= present_ids
if cache_usable:
preserved = list(cached.preserved_messages)
excluded_ids = cached.summarized_ids | cached.preserved_ids
preserved.extend(m for m in messages if m.id not in excluded_ids)
effective = [self._summary_message(cached.summary_text), *preserved]
effective = _ensure_latest_human_message(messages, effective)
# Decide re-summarization on the *counted* size of the compressed
# context only — NOT ``_should_summarize`` — because that folds in the
# last AIMessage's reported ``usage_metadata`` (system prompt + tool
# schemas, fixed overhead compression can't shrink). Using it here
# would re-summarize on every single turn once that overhead alone
# approaches the trigger.
if not self._exceeds_trigger_by_count(effective):
# Refresh LRU recency and reuse without an LLM call.
self._touch_cache_entry(thread_id)
logger.info(
"summarization: 上下文压缩(复用缓存摘要,无 LLM 调用) context compaction reusing cached summary thread=%s full_tokens=%d compressed_tokens=%d preserved_msgs=%d",
thread_id,
self.token_counter(messages),
self.token_counter(effective),
len(preserved),
)
return ("reuse", effective)
# New messages have pushed the compressed context back over the
# threshold — fall through and re-summarize a larger prefix.
# Genuine (blocking) LLM summarize path. Log *why* we are paying for it so
# an "it compacts every turn" report is diagnosable straight from the
# backend log: cache=miss → thread_id/key problem; unusable → message-id
# instability; stale → preserved genuinely grew back over the trigger.
cache_state = "miss" if cached is None else "stale"
logger.info(
"summarization: compacting thread=%s cache=%s counted_tokens=%d msgs=%d",
thread_id,
cache_state,
self.token_counter(messages),
len(messages),
)
cutoff_index = self._determine_cutoff_index(messages)
if cutoff_index <= 0:
return None
# Force the preserved window below every trigger (with headroom) so the
# post-compaction context doesn't immediately re-trigger. Without this,
# a ``keep`` expressed in *messages* (e.g. 20) can itself blow past a
# *token* trigger (e.g. 60000) when recent messages are large (tool
# outputs, pasted docs) — and then every follow-up question re-summarizes.
cutoff_index = self._apply_stickiness_headroom(messages, cutoff_index)
if cutoff_index <= 0:
return None
messages_to_summarize, preserved = self._partition_with_skill_rescue(messages, cutoff_index)
if not messages_to_summarize:
return None
return ("summarize", (messages_to_summarize, preserved, thread_id))
def _finish_summarize(
self,
messages_to_summarize: list[AnyMessage],
preserved: list[AnyMessage],
summary: str,
thread_id: str | None,
) -> list[AnyMessage]:
"""Assemble the compressed message list and update the per-thread cache."""
compressed = [self._summary_message(summary), *preserved]
compressed = _ensure_latest_human_message([*messages_to_summarize, *preserved], compressed)
if thread_id:
summarized_ids = frozenset(m.id for m in messages_to_summarize if m.id is not None)
preserved_ids = {m.id for m in preserved if m.id is not None}
self._store_cache_entry(
thread_id,
entry := _SummaryCacheEntry(
summarized_ids=summarized_ids,
summary_text=summary,
preserved_ids=frozenset(preserved_ids),
preserved_messages=tuple(preserved),
),
)
self._pending_state_cache_update = _serialize_cache_entry(entry)
return compressed
def _get_cache_entry(self, thread_id: str) -> _SummaryCacheEntry | None:
"""Return the cached entry for ``thread_id`` (thread-safe read)."""
with _GLOBAL_SUMMARY_CACHE_LOCK:
return self._summary_cache.get(thread_id)
def _touch_cache_entry(self, thread_id: str) -> None:
"""Refresh LRU recency for ``thread_id`` if still present (thread-safe)."""
with _GLOBAL_SUMMARY_CACHE_LOCK:
if thread_id in self._summary_cache:
self._summary_cache.move_to_end(thread_id)
def _store_cache_entry(self, thread_id: str, entry: _SummaryCacheEntry) -> None:
"""Insert/refresh a cache entry, evicting the oldest thread if over capacity."""
with _GLOBAL_SUMMARY_CACHE_LOCK:
self._summary_cache[thread_id] = entry
self._summary_cache.move_to_end(thread_id)
while len(self._summary_cache) > _SUMMARY_CACHE_MAX_THREADS:
self._summary_cache.popitem(last=False)
def _exceeds_trigger_by_count(self, messages: list[AnyMessage]) -> bool:
"""Trigger check using only the *counted* size of ``messages``.
Deliberately ignores the stock middleware's reported-``usage_metadata``
heuristic: that number includes fixed system-prompt + tool-schema
overhead which compression can never shrink, so relying on it to decide
*re*-summarization makes a long, tool-heavy thread re-compact on every
turn. The first-ever decision to compress still uses the full
``_should_summarize`` (reported usage is a fair signal there); only the
cache-reuse-vs-recompact decision uses this stricter, content-only check.
"""
total = self.token_counter(messages)
for kind, value in getattr(self, "_trigger_conditions", []):
if kind == "messages" and len(messages) >= value:
return True
if kind == "tokens" and total >= value:
return True
return False
def _apply_stickiness_headroom(self, messages: list[AnyMessage], cutoff_index: int) -> int:
"""Advance ``cutoff_index`` (keep fewer recent messages) so the preserved
suffix lands below every trigger threshold with headroom.
Only ever *raises* the cutoff (summarizes more / keeps less); never keeps
more than the caller's ``keep`` policy already chose. This is what makes
the sticky boundary actually stick: after compaction the kept context is
guaranteed under ~``_KEEP_HEADROOM_FRACTION`` of each trigger, so a
re-compaction waits for genuinely new content instead of firing every turn.
"""
n = len(messages)
if n <= 1:
return cutoff_index
for kind, value in getattr(self, "_trigger_conditions", []):
if kind == "messages":
keep_cap = max(1, int(int(value) * _KEEP_HEADROOM_FRACTION))
cutoff_index = max(cutoff_index, n - keep_cap)
elif kind == "tokens":
target = max(1, int(int(value) * _KEEP_HEADROOM_FRACTION))
cutoff_index = max(cutoff_index, self._suffix_token_cutoff(messages, target))
# "fraction" triggers depend on model profile limits; the message/token
# caps above (when present) already bound the window, so skip them here.
# Always keep at least the final message, and re-snap to a safe AI/Tool
# boundary so we never orphan a tool result.
cutoff_index = min(cutoff_index, n - 1)
return self._find_safe_cutoff_point(messages, cutoff_index)
def _suffix_token_cutoff(self, messages: list[AnyMessage], target_tokens: int) -> int:
"""Smallest index ``i`` such that ``token_counter(messages[i:]) <= target_tokens``.
Binary search mirroring the stock token-based cutoff; returns 0 when the
whole list already fits, and never returns the full length (keeps ≥1).
"""
n = len(messages)
if n == 0:
return 0
if self.token_counter(messages) <= target_tokens:
return 0
left, right = 0, n
cutoff = n
for _ in range(n.bit_length() + 1):
if left >= right:
break
mid = (left + right) // 2
if self.token_counter(messages[mid:]) <= target_tokens:
cutoff = mid
right = mid
else:
left = mid + 1
if cutoff == n:
cutoff = left
return min(cutoff, n - 1)
@staticmethod
def _resolve_request_thread_id(request: ModelRequest) -> str | None:
"""Best-effort thread id from the model request's runtime."""
runtime = getattr(request, "runtime", None)
if runtime is None:
return None
return _resolve_thread_id(runtime)
def _summary_message(self, summary: str) -> SystemMessage:
"""Build the summary message handed to the model.
It is named ``summary`` and flagged ``hide_from_ui`` defensively. Because
it only ever lives in the transient model request (never in persisted
state), the frontend never receives it — the user keeps seeing the
original conversation.
"""
return SystemMessage(
content=(
"Internal conversation summary for continuity only. Use it silently "
"to answer the user's latest request. Never reveal, quote, mention, "
"or describe this summary or the fact that context was compacted.\n\n"
"<internal_context_summary>\n"
f"{summary}\n"
"</internal_context_summary>"
),
name="summary",
additional_kwargs={"hide_from_ui": True, "lc_source": "summarization"},
)
@override
def _build_new_messages(self, summary: str) -> list[AnyMessage]:
"""Kept for backwards compatibility; delegates to :meth:`_summary_message`."""
return [self._summary_message(summary)]
def _partition_with_skill_rescue(
self,
messages: list[AnyMessage],
cutoff_index: int,
) -> tuple[list[AnyMessage], list[AnyMessage]]:
"""Partition like the parent, then rescue recently-loaded skill bundles."""
to_summarize, preserved = self._partition_messages(messages, cutoff_index)
if self._preserve_recent_skill_count == 0 or self._preserve_recent_skill_tokens == 0 or not to_summarize:
return to_summarize, preserved
try:
bundles = self._find_skill_bundles(to_summarize, self._skills_container_path)
except Exception:
logger.exception("Skill-preserving summarization rescue failed; falling back to default partition")
return to_summarize, preserved
if not bundles:
return to_summarize, preserved
rescue_bundles = self._select_bundles_to_rescue(bundles)
if not rescue_bundles:
return to_summarize, preserved
bundles_by_ai_index = {bundle.ai_index: bundle for bundle in rescue_bundles}
rescue_tool_indices = {idx for bundle in rescue_bundles for idx in bundle.skill_tool_indices}
rescued: list[AnyMessage] = []
remaining: list[AnyMessage] = []
for i, msg in enumerate(to_summarize):
bundle = bundles_by_ai_index.get(i)
if bundle is not None and isinstance(msg, AIMessage):
rescued_tool_calls = [tc for tc in msg.tool_calls if tc.get("id") in bundle.skill_tool_call_ids]
remaining_tool_calls = [tc for tc in msg.tool_calls if tc.get("id") not in bundle.skill_tool_call_ids]
if rescued_tool_calls:
rescued.append(_clone_ai_message(msg, rescued_tool_calls, content=""))
if remaining_tool_calls or msg.content:
remaining.append(_clone_ai_message(msg, remaining_tool_calls))
continue
if i in rescue_tool_indices:
rescued.append(msg)
continue
remaining.append(msg)
return remaining, rescued + preserved
def _find_skill_bundles(
self,
messages: list[AnyMessage],
skills_root: str,
) -> list[_SkillBundle]:
"""Locate AIMessage + paired ToolMessage groups that load skill files."""
bundles: list[_SkillBundle] = []
n = len(messages)
i = 0
while i < n:
msg = messages[i]
if not (isinstance(msg, AIMessage) and msg.tool_calls):
i += 1
continue
tool_calls = list(msg.tool_calls)
skill_paths_by_id: dict[str, str] = {}
for tc in tool_calls:
if self._is_skill_tool_call(tc, skills_root):
tc_id = tc.get("id")
path = _tool_call_path(tc)
if tc_id and path:
skill_paths_by_id[tc_id] = path
if not skill_paths_by_id:
i += 1
continue
skill_tool_tokens = 0
skill_key_parts: list[str] = []
skill_tool_indices: list[int] = []
matched_skill_call_ids: set[str] = set()
j = i + 1
while j < n and isinstance(messages[j], ToolMessage):
j += 1
for k in range(i + 1, j):
tool_msg = messages[k]
if isinstance(tool_msg, ToolMessage) and tool_msg.tool_call_id in skill_paths_by_id:
skill_tool_tokens += self.token_counter([tool_msg])
skill_key_parts.append(skill_paths_by_id[tool_msg.tool_call_id])
skill_tool_indices.append(k)
matched_skill_call_ids.add(tool_msg.tool_call_id)
if not skill_tool_indices:
i = j
continue
bundles.append(
_SkillBundle(
ai_index=i,
skill_tool_indices=tuple(skill_tool_indices),
skill_tool_call_ids=frozenset(matched_skill_call_ids),
skill_tool_tokens=skill_tool_tokens,
skill_key="|".join(sorted(skill_key_parts)),
)
)
i = j
return bundles
def _select_bundles_to_rescue(self, bundles: list[_SkillBundle]) -> list[_SkillBundle]:
"""Pick bundles to keep, walking newest-first under count/token budgets."""
selected: list[_SkillBundle] = []
if not bundles:
return selected
seen_skill_keys: set[str] = set()
total_tokens = 0
kept = 0
for bundle in reversed(bundles):
if kept >= self._preserve_recent_skill_count:
break
if bundle.skill_key in seen_skill_keys:
continue
if bundle.skill_tool_tokens > self._preserve_recent_skill_tokens_per_skill:
continue
if total_tokens + bundle.skill_tool_tokens > self._preserve_recent_skill_tokens:
continue
selected.append(bundle)
total_tokens += bundle.skill_tool_tokens
kept += 1
seen_skill_keys.add(bundle.skill_key)
selected.reverse()
return selected
def _is_skill_tool_call(self, tool_call: dict[str, Any], skills_root: str) -> bool:
"""Return True when ``tool_call`` reads a file under the configured skills root."""
name = tool_call.get("name") or ""
if name not in self._skill_file_read_tool_names:
return False
path = _tool_call_path(tool_call)
if not path:
return False
normalized_root = skills_root.rstrip("/")
return path == normalized_root or path.startswith(normalized_root + "/")
def _fire_hooks(
self,
messages_to_summarize: list[AnyMessage],
preserved_messages: list[AnyMessage],
runtime: Runtime,
) -> None:
if not self._before_summarization_hooks:
return
event = SummarizationEvent(
messages_to_summarize=tuple(messages_to_summarize),
preserved_messages=tuple(preserved_messages),
thread_id=_resolve_thread_id(runtime),
agent_name=_resolve_agent_name(runtime),
runtime=runtime,
)
for hook in self._before_summarization_hooks:
try:
hook(event)
except Exception:
hook_name = getattr(hook, "__name__", None) or type(hook).__name__
logger.exception("before_summarization hook %s failed", hook_name)
@@ -0,0 +1,88 @@
"""Inject task-specific external context into the model request.
The web task workspace can pass business data through LangGraph run context
without showing it in the chat transcript. This middleware converts that
context into a transient message right before model invocation, so it is
available to the agent but never persisted as user-visible conversation state.
"""
from __future__ import annotations
import json
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import HumanMessage
_CONTEXT_KEY = "task_external_context"
_TAG = "task_external_context"
_MAX_CONTEXT_CHARS = 18000
_TAIL_CONTEXT_CHARS = 2500
def _truncate_middle(text: str, max_chars: int = _MAX_CONTEXT_CHARS) -> str:
if len(text) <= max_chars:
return text
marker = "\n\n...[隐藏任务上下文过长,已截断中间部分]...\n\n"
tail_chars = min(_TAIL_CONTEXT_CHARS, max_chars // 4)
head_chars = max(0, max_chars - len(marker) - tail_chars)
return f"{text[:head_chars]}{marker}{text[-tail_chars:]}"
def _render_context(value: Any) -> str:
if value is None:
return ""
if isinstance(value, str):
return value.strip()
try:
text = json.dumps(value, ensure_ascii=False, indent=2, default=str).strip()
except Exception:
text = str(value).strip()
return _truncate_middle(text)
def _task_context_from_request(request: Any) -> Any:
runtime = getattr(request, "runtime", None)
context = getattr(runtime, "context", None)
if isinstance(context, dict):
return context.get(_CONTEXT_KEY)
return None
def _build_context_message(value: Any) -> HumanMessage | None:
text = _render_context(value)
if not text:
return None
content = (
f"<{_TAG}>\n"
"[系统提示:以下是业务系统随本次运行提供的隐藏任务上下文,不是用户的新输入。"
"回答当前任务时应作为背景资料参考;不要主动说明这些内容来自隐藏上下文,"
"也不要在回答中暴露本标签本身。]\n\n"
f"{text}\n"
f"</{_TAG}>"
)
return HumanMessage(
content=content,
additional_kwargs={"hide_from_ui": True, _CONTEXT_KEY: True},
)
class TaskExternalContextMiddleware(AgentMiddleware[AgentState]):
"""Append hidden task context as a transient model-call message."""
state_schema = AgentState
@override
async def awrap_model_call(self, request: Any, handler: Any) -> Any:
msg = _build_context_message(_task_context_from_request(request))
if msg is not None:
request = request.override(messages=[*request.messages, msg])
return await handler(request)
@override
def wrap_model_call(self, request: Any, handler: Any) -> Any:
msg = _build_context_message(_task_context_from_request(request))
if msg is not None:
request = request.override(messages=[*request.messages, msg])
return handler(request)
@@ -0,0 +1,129 @@
import logging
from datetime import UTC, datetime
from typing import NotRequired, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import HumanMessage
from langgraph.config import get_config
from langgraph.runtime import Runtime
from deerflow.agents.thread_state import ThreadDataState
from deerflow.config.paths import Paths, get_paths
from deerflow.runtime.thread_paths import resolve_path_user_id
from deerflow.runtime.user_context import get_effective_user_id
logger = logging.getLogger(__name__)
class ThreadDataMiddlewareState(AgentState):
"""Compatible with the `ThreadState` schema."""
thread_data: NotRequired[ThreadDataState | None]
class ThreadDataMiddleware(AgentMiddleware[ThreadDataMiddlewareState]):
"""Create thread data directories for each thread execution.
Creates the following directory structure:
- {base_dir}/threads/{thread_id}/user-data/workspace
- {base_dir}/threads/{thread_id}/user-data/uploads
- {base_dir}/threads/{thread_id}/user-data/outputs
Lifecycle Management:
- With lazy_init=True (default): Only compute paths, directories created on-demand
- With lazy_init=False: Eagerly create directories in before_agent()
"""
state_schema = ThreadDataMiddlewareState
def __init__(self, base_dir: str | None = None, lazy_init: bool = True):
"""Initialize the middleware.
Args:
base_dir: Base directory for thread data. Defaults to Paths resolution.
lazy_init: If True, defer directory creation until needed.
If False, create directories eagerly in before_agent().
Default is True for optimal performance.
"""
super().__init__()
self._paths = Paths(base_dir) if base_dir else get_paths()
self._lazy_init = lazy_init
def _get_thread_paths(self, thread_id: str, user_id: str | None = None) -> dict[str, str]:
"""Get the paths for a thread's data directories.
Args:
thread_id: The thread ID.
user_id: Optional user ID for per-user path isolation.
Returns:
Dictionary with workspace_path, uploads_path, and outputs_path.
"""
return {
"workspace_path": str(self._paths.sandbox_work_dir(thread_id, user_id=user_id)),
"uploads_path": str(self._paths.sandbox_uploads_dir(thread_id, user_id=user_id)),
"outputs_path": str(self._paths.sandbox_outputs_dir(thread_id, user_id=user_id)),
}
def _create_thread_directories(self, thread_id: str, user_id: str | None = None) -> dict[str, str]:
"""Create the thread data directories.
Args:
thread_id: The thread ID.
user_id: Optional user ID for per-user path isolation.
Returns:
Dictionary with the created directory paths.
"""
self._paths.ensure_thread_dirs(thread_id, user_id=user_id)
return self._get_thread_paths(thread_id, user_id=user_id)
@override
def before_agent(self, state: ThreadDataMiddlewareState, runtime: Runtime) -> dict | None:
context = runtime.context or {}
configurable = {}
try:
config = get_config()
configurable = config.get("configurable", {}) or {}
except RuntimeError:
pass
thread_id = context.get("thread_id")
if thread_id is None:
thread_id = configurable.get("thread_id")
if thread_id is None:
raise ValueError("Thread ID is required in runtime context or config.configurable")
# Task-shared threads (rwfx/3qfx/xdfx, metadata.taskId) resolve to the
# thread creator so every account that shares the conversation writes to
# the same physical user-data directory. Personal threads resolve to the
# current login unchanged.
is_ephemeral = bool(context.get("ephemeral") or configurable.get("ephemeral"))
user_id = get_effective_user_id() if is_ephemeral else resolve_path_user_id(thread_id)
if self._lazy_init:
# Lazy initialization: only compute paths, don't create directories
paths = self._get_thread_paths(thread_id, user_id=user_id)
else:
# Eager initialization: create directories immediately
paths = self._create_thread_directories(thread_id, user_id=user_id)
logger.debug("Created thread data directories for thread %s", thread_id)
messages = list(state.get("messages", []))
last_message = messages[-1] if messages else None
if last_message and isinstance(last_message, HumanMessage):
messages[-1] = HumanMessage(
content=last_message.content,
id=last_message.id,
name=last_message.name,
additional_kwargs={**last_message.additional_kwargs, "run_id": (runtime.context or {}).get("run_id"), "timestamp": datetime.now(UTC).isoformat()},
)
return {
"thread_data": {
**paths,
},
"messages": messages,
}
@@ -0,0 +1,396 @@
"""Middleware for automatic thread title generation."""
import copy
import logging
import re
from pathlib import Path
from typing import TYPE_CHECKING, Any, NotRequired, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langgraph.runtime import Runtime
from deerflow.config.title_config import get_title_config
from deerflow.models import create_chat_model
from deerflow.utils.time import now_iso
if TYPE_CHECKING:
from deerflow.config.app_config import AppConfig
from deerflow.config.title_config import TitleConfig
logger = logging.getLogger(__name__)
_TITLE_DEBUG_LOGGER_NAME = "title_generation_debug"
def _get_title_debug_logger() -> logging.Logger:
debug_logger = logging.getLogger(_TITLE_DEBUG_LOGGER_NAME)
if getattr(debug_logger, "_title_file_configured", False):
return debug_logger
log_path = Path("logs/title_generation_debug.log")
if not log_path.is_absolute():
log_path = Path.cwd() / log_path
log_path.parent.mkdir(parents=True, exist_ok=True)
handler = logging.FileHandler(log_path, encoding="utf-8")
handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
debug_logger.addHandler(handler)
debug_logger.setLevel(logging.INFO)
debug_logger.propagate = False
setattr(debug_logger, "_title_file_configured", True)
return debug_logger
def log_title_debug(message: str, *args: Any) -> None:
logger.warning(message, *args)
_get_title_debug_logger().info(message, *args)
class TitleMiddlewareState(AgentState):
"""Compatible with the `ThreadState` schema."""
title: NotRequired[str | None]
title_provisional: NotRequired[bool]
class TitleMiddleware(AgentMiddleware[TitleMiddlewareState]):
"""Automatically generate a title for the thread after the first user message."""
state_schema = TitleMiddlewareState
def __init__(self, *, app_config: "AppConfig | None" = None, title_config: "TitleConfig | None" = None):
super().__init__()
self._app_config = app_config
self._title_config = title_config
def _get_title_config(self):
if self._title_config is not None:
return self._title_config
if self._app_config is not None:
return self._app_config.title
return get_title_config()
def _normalize_content(self, content: object) -> str:
if isinstance(content, str):
return content
if isinstance(content, list):
parts = [self._normalize_content(item) for item in content]
return "\n".join(part for part in parts if part)
if isinstance(content, dict):
text_value = content.get("text")
if isinstance(text_value, str):
return text_value
nested_content = content.get("content")
if nested_content is not None:
return self._normalize_content(nested_content)
return ""
def _message_type(self, message: object) -> str:
if isinstance(message, dict):
return str(message.get("type") or message.get("role") or "").lower()
return str(getattr(message, "type", "") or getattr(message, "role", "") or "").lower()
def _message_content(self, message: object) -> object:
if isinstance(message, dict):
return message.get("content", "")
return getattr(message, "content", "")
def _should_set_provisional_title(self, state: TitleMiddlewareState) -> bool:
"""Check if we should set an instant, question-derived placeholder title.
Runs in ``before_model`` so the thread shows a sensible title the moment
the user sends their first message — eliminating the "untitled" window
while the (possibly long) first answer streams. No LLM call, no latency.
"""
config = self._get_title_config()
if not config.enabled:
return False
# Already has a title (provisional or final) — nothing to do.
if state.get("title"):
return False
# Only on the very first turn, as soon as the user message arrives.
messages = state.get("messages", [])
user_messages = [m for m in messages if self._message_type(m) in {"human", "user"}]
return len(user_messages) == 1
def _should_generate_title(self, state: TitleMiddlewareState) -> bool:
"""Check if we should generate the final LLM title for this thread."""
config = self._get_title_config()
if not config.enabled:
return False
# Skip only if we already have a *finalized* title. A provisional
# placeholder set in before_model should still be upgraded by the LLM.
if state.get("title") and not state.get("title_provisional"):
return False
# Check if this is the first turn (has at least one user message and one assistant response)
messages = state.get("messages", [])
if len(messages) < 2:
return False
# Count user and assistant messages
user_messages = [m for m in messages if self._message_type(m) in {"human", "user"}]
assistant_messages = [m for m in messages if self._message_type(m) in {"ai", "assistant"}]
# Generate title after first complete exchange
return len(user_messages) == 1 and len(assistant_messages) >= 1
def _build_title_prompt(self, state: TitleMiddlewareState) -> tuple[str, str]:
"""Extract user/assistant messages and build the title prompt.
Returns (prompt_string, user_msg) so callers can use user_msg as fallback.
"""
config = self._get_title_config()
messages = state.get("messages", [])
user_msg_content = next((self._message_content(m) for m in messages if self._message_type(m) in {"human", "user"}), "")
assistant_msg_content = next((self._message_content(m) for m in messages if self._message_type(m) in {"ai", "assistant"}), "")
user_msg = self._normalize_content(user_msg_content)
assistant_msg = self._strip_think_tags(self._normalize_content(assistant_msg_content))
prompt = config.prompt_template.format(
max_words=config.max_words,
user_msg=user_msg[:500],
assistant_msg=assistant_msg[:500],
)
return prompt, user_msg
def _strip_think_tags(self, text: str) -> str:
"""Remove <think>...</think> blocks emitted by reasoning models (e.g. minimax, GLM, DeepSeek-R1).
Also handles malformed cases: an unclosed `<think>` (response truncated mid-reasoning)
or a stray `</think>` (open tag eaten by upstream parsing) — both can otherwise leak
raw reasoning into the title.
"""
text = re.sub(r"<think>[\s\S]*?</think>", "", text, flags=re.IGNORECASE)
text = re.sub(r"<think>[\s\S]*$", "", text, flags=re.IGNORECASE)
text = re.sub(r"^[\s\S]*?</think>", "", text, flags=re.IGNORECASE)
return text.strip()
def _parse_title(self, content: object) -> str:
"""Normalize model output into a clean title string (strips <think> blocks)."""
config = self._get_title_config()
title_content = self._strip_think_tags(self._normalize_content(content))
title = title_content.strip().strip('"').strip("'")
return title[: config.max_chars] if len(title) > config.max_chars else title
def _isolated_config(self) -> dict[str, Any]:
"""Build a RunnableConfig that does NOT inherit the parent's streaming callbacks.
The leak that pushed title-generation reasoning into the live UI stream came
from inheriting the parent RunnableConfig (and with it the SSE/streaming
callbacks) for the title model call. Here we deliberately start from an empty
config with ``callbacks: []`` so the title model's tokens — including any
``<think>`` reasoning from a reasoning-only deployment — never reach the
frontend stream or the run journal as conversation output. The stored title
is additionally cleaned by ``_parse_title``/``_strip_think_tags``.
"""
return {
"run_name": "title_agent",
"tags": ["middleware:title"],
"callbacks": [],
}
def _fallback_title(self, user_msg: str) -> str:
config = self._get_title_config()
fallback_chars = min(config.max_chars, 50)
if len(user_msg) > fallback_chars:
return user_msg[:fallback_chars].rstrip() + "..."
return user_msg if user_msg else "New Conversation"
def _provisional_title_result(self, state: TitleMiddlewareState) -> dict | None:
"""Set an instant placeholder title from the first user message (no LLM)."""
if not self._should_set_provisional_title(state):
return None
messages = state.get("messages", [])
user_msg_content = next((self._message_content(m) for m in messages if self._message_type(m) in {"human", "user"}), "")
user_msg = self._normalize_content(user_msg_content)
if not user_msg.strip():
return None
title = self._fallback_title(user_msg)
logger.debug("TitleMiddleware: set provisional title %r before first model call", title)
return {"title": title, "title_provisional": True}
def _generate_title_result(self, state: TitleMiddlewareState) -> dict | None:
"""Generate a local fallback title without blocking on an LLM call."""
if not self._should_generate_title(state):
return None
_, user_msg = self._build_title_prompt(state)
return {"title": self._fallback_title(user_msg), "title_provisional": False}
def _force_disable_thinking(self, model: object) -> None:
"""Force-disable thinking on the title model via `extra_body` overrides.
Title generation never needs reasoning. The model factory only emits
disable params when the model config declares `when_thinking_disabled`
or a matching `when_thinking_enabled` shape — many user-added reasoning
models (e.g. GLM-4.5/5) only set `supports_thinking: true` and would
otherwise keep thinking on, which is slow and leaks <think> tags into
the title prompt response. Injecting both common OpenAI-compatible
disable shapes covers Zhipu GLM (`thinking.type`) and Qwen/vLLM
(`chat_template_kwargs.enable_thinking`); other providers ignore
unknown body fields.
"""
if not hasattr(model, "extra_body"):
return
current = getattr(model, "extra_body", None) or {}
merged_chat_template_kwargs = {
**(current.get("chat_template_kwargs") or {}),
"enable_thinking": False,
}
merged = {
**current,
"thinking": {**(current.get("thinking") or {}), "type": "disabled"},
"chat_template_kwargs": merged_chat_template_kwargs,
}
try:
model.extra_body = merged
except Exception:
logger.debug("Could not override extra_body to disable thinking on title model", exc_info=True)
async def _agenerate_title_result(self, state: TitleMiddlewareState) -> dict | None:
"""Polish the title with an LLM, without leaking its reasoning to the UI.
The title model is invoked with an *isolated* config (``_isolated_config``)
that does not inherit the parent's streaming callbacks, so even a
reasoning-only deployment's ``<think>`` tokens never reach the live UI
stream or the run journal. Thinking is also force-disabled on the model,
and the final stored title is stripped of any residual ``<think>`` blocks.
On any failure we fall back to the local question-derived title.
"""
if not self._should_generate_title(state):
return None
config = self._get_title_config()
prompt, user_msg = self._build_title_prompt(state)
try:
model_kwargs: dict[str, Any] = {"thinking_enabled": False, "force_disable_thinking": True}
if self._app_config is not None:
model_kwargs["app_config"] = self._app_config
if config.model_name:
model = create_chat_model(name=config.model_name, **model_kwargs)
else:
model = create_chat_model(**model_kwargs)
self._force_disable_thinking(model)
response = await model.ainvoke(prompt, config=self._isolated_config())
title = self._parse_title(response.content)
if title:
return {"title": title, "title_provisional": False}
except Exception:
logger.debug("Failed to generate async title via LLM; falling back to local title", exc_info=True)
return {"title": self._fallback_title(user_msg), "title_provisional": False}
@override
def before_model(self, state: TitleMiddlewareState, runtime: Runtime) -> dict | None:
return self._provisional_title_result(state)
@override
async def abefore_model(self, state: TitleMiddlewareState, runtime: Runtime) -> dict | None:
return self._provisional_title_result(state)
@override
def after_model(self, state: TitleMiddlewareState, runtime: Runtime) -> dict | None:
# Keep the provisional title in place during the main run. The gateway
# worker finalizes it in a background task after the answer is complete.
return None
@override
async def aafter_model(self, state: TitleMiddlewareState, runtime: Runtime) -> dict | None:
# Keep the provisional title in place during the main async run so the
# worker's post-run background finalizer can replace it with the real
# LLM-generated title without blocking the input box.
return None
async def finalize_thread_title(
*,
checkpointer: Any,
thread_store: Any | None,
thread_id: str,
source_state: dict[str, Any],
app_config: "AppConfig | None" = None,
) -> bool:
"""Finalize a provisional thread title in the background.
``source_state`` must be the checkpoint snapshot captured when the first run
completed. That avoids races where the user asks a second question before
the background title task starts, which would otherwise make the current
checkpoint fail the "first exchange only" predicate and leave the title
provisional forever.
"""
log_title_debug("Title finalize: evaluating background title generation for thread %s", thread_id)
middleware = TitleMiddleware(app_config=app_config)
source_snapshot = copy.deepcopy(source_state)
if not middleware._should_generate_title(source_snapshot):
log_title_debug(
"Title finalize: skipped for thread %s because source snapshot is not eligible",
thread_id,
)
return False
log_title_debug("Title finalize: starting background title generation for thread %s", thread_id)
result = await middleware._agenerate_title_result(source_snapshot)
if not result:
log_title_debug("Title finalize: no title result produced for thread %s", thread_id)
return False
read_config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
checkpoint_tuple = await checkpointer.aget_tuple(read_config)
if checkpoint_tuple is None:
log_title_debug("Title finalize: skipped for thread %s because checkpoint was not found", thread_id)
return False
checkpoint: dict[str, Any] = dict(getattr(checkpoint_tuple, "checkpoint", {}) or {})
metadata: dict[str, Any] = dict(getattr(checkpoint_tuple, "metadata", {}) or {})
channel_values: dict[str, Any] = dict(checkpoint.get("channel_values", {}) or {})
# If another path already finalized or manually renamed the title, keep it.
if channel_values.get("title_provisional") is not True:
log_title_debug(
"Title finalize: skipped for thread %s because title is no longer provisional",
thread_id,
)
return False
channel_values.update(result)
checkpoint["channel_values"] = channel_values
metadata["updated_at"] = now_iso()
write_config = {
"configurable": {
"thread_id": thread_id,
"checkpoint_ns": "",
}
}
new_versions: dict[str, Any] = {}
get_next_version = getattr(checkpointer, "get_next_version", None)
if callable(get_next_version):
versions = dict(checkpoint.get("channel_versions", {}) or {})
for key in ("title", "title_provisional"):
next_version = get_next_version(versions.get(key), None)
versions[key] = next_version
new_versions[key] = next_version
checkpoint["channel_versions"] = versions
await checkpointer.aput(write_config, checkpoint, metadata, new_versions)
title = result.get("title")
if title and thread_store is not None:
await thread_store.update_display_name(thread_id, title, user_id=None)
log_title_debug("Title finalize: completed for thread %s with title %r", thread_id, title)
return True
@@ -0,0 +1,179 @@
"""Middleware that extends TodoListMiddleware with context-loss detection and premature-exit prevention.
When the message history is truncated (e.g., by SummarizationMiddleware), the
original `write_todos` tool call and its ToolMessage can be scrolled out of the
active context window. This middleware detects that situation and injects a
reminder message so the model still knows about the outstanding todo list.
Additionally, this middleware prevents the agent from exiting the loop while
there are still incomplete todo items. When the model produces a final response
(no tool calls) but todos are not yet complete, the middleware injects a reminder
and jumps back to the model node to force continued engagement.
"""
from __future__ import annotations
from typing import Any, override
from langchain.agents.middleware import TodoListMiddleware
from langchain.agents.middleware.todo import PlanningState, Todo
from langchain.agents.middleware.types import hook_config
from langchain_core.messages import AIMessage, HumanMessage
from langgraph.runtime import Runtime
def _todos_in_messages(messages: list[Any]) -> bool:
"""Return True if any AIMessage in *messages* contains a write_todos tool call."""
for msg in messages:
if isinstance(msg, AIMessage) and msg.tool_calls:
for tc in msg.tool_calls:
if tc.get("name") == "write_todos":
return True
return False
def _reminder_in_messages(messages: list[Any]) -> bool:
"""Return True if a todo_reminder HumanMessage is already present in *messages*."""
for msg in messages:
if isinstance(msg, HumanMessage) and getattr(msg, "name", None) == "todo_reminder":
return True
return False
def _completion_reminder_count(messages: list[Any]) -> int:
"""Return the number of todo_completion_reminder HumanMessages in *messages*."""
return sum(1 for msg in messages if isinstance(msg, HumanMessage) and getattr(msg, "name", None) == "todo_completion_reminder")
def _format_todos(todos: list[Todo]) -> str:
"""Format a list of Todo items into a human-readable string."""
lines: list[str] = []
for todo in todos:
status = todo.get("status", "pending")
content = todo.get("content", "")
lines.append(f"- [{status}] {content}")
return "\n".join(lines)
class TodoMiddleware(TodoListMiddleware):
"""Extends TodoListMiddleware with `write_todos` context-loss detection.
When the original `write_todos` tool call has been truncated from the message
history (e.g., after summarization), the model loses awareness of the current
todo list. This middleware detects that gap in `before_model` / `abefore_model`
and injects a reminder message so the model can continue tracking progress.
"""
@override
def before_model(
self,
state: PlanningState,
runtime: Runtime,
) -> dict[str, Any] | None:
"""Inject a todo-list reminder when write_todos has left the context window."""
todos: list[Todo] = state.get("todos") or [] # type: ignore[assignment]
if not todos:
return None
messages = state.get("messages") or []
if _todos_in_messages(messages):
# write_todos is still visible in context — nothing to do.
return None
if _reminder_in_messages(messages):
# A reminder was already injected and hasn't been truncated yet.
return None
# The todo list exists in state but the original write_todos call is gone.
# Inject a reminder as a HumanMessage so the model stays aware.
formatted = _format_todos(todos)
reminder = HumanMessage(
name="todo_reminder",
content=(
"<system_reminder>\n"
"Your todo list from earlier is no longer visible in the current context window, "
"but it is still active. Here is the current state:\n\n"
f"{formatted}\n\n"
"Continue tracking and updating this todo list as you work. "
"Call `write_todos` whenever the status of any item changes.\n"
"</system_reminder>"
),
)
return {"messages": [reminder]}
@override
async def abefore_model(
self,
state: PlanningState,
runtime: Runtime,
) -> dict[str, Any] | None:
"""Async version of before_model."""
return self.before_model(state, runtime)
# Maximum number of completion reminders before allowing the agent to exit.
# This prevents infinite loops when the agent cannot make further progress.
_MAX_COMPLETION_REMINDERS = 2
@hook_config(can_jump_to=["model"])
@override
def after_model(
self,
state: PlanningState,
runtime: Runtime,
) -> dict[str, Any] | None:
"""Prevent premature agent exit when todo items are still incomplete.
In addition to the base class check for parallel ``write_todos`` calls,
this override intercepts model responses that have no tool calls while
there are still incomplete todo items. It injects a reminder
``HumanMessage`` and jumps back to the model node so the agent
continues working through the todo list.
A retry cap of ``_MAX_COMPLETION_REMINDERS`` (default 2) prevents
infinite loops when the agent cannot make further progress.
"""
# 1. Preserve base class logic (parallel write_todos detection).
base_result = super().after_model(state, runtime)
if base_result is not None:
return base_result
# 2. Only intervene when the agent wants to exit (no tool calls).
messages = state.get("messages") or []
last_ai = next((m for m in reversed(messages) if isinstance(m, AIMessage)), None)
if not last_ai or last_ai.tool_calls:
return None
# 3. Allow exit when all todos are completed or there are no todos.
todos: list[Todo] = state.get("todos") or [] # type: ignore[assignment]
if not todos or all(t.get("status") == "completed" for t in todos):
return None
# 4. Enforce a reminder cap to prevent infinite re-engagement loops.
if _completion_reminder_count(messages) >= self._MAX_COMPLETION_REMINDERS:
return None
# 5. Inject a reminder and force the agent back to the model.
incomplete = [t for t in todos if t.get("status") != "completed"]
incomplete_text = "\n".join(f"- [{t.get('status', 'pending')}] {t.get('content', '')}" for t in incomplete)
reminder = HumanMessage(
name="todo_completion_reminder",
content=(
"<system_reminder>\n"
"You have incomplete todo items that must be finished before giving your final response:\n\n"
f"{incomplete_text}\n\n"
"Please continue working on these tasks. Call `write_todos` to mark items as completed "
"as you finish them, and only respond when all items are done.\n"
"</system_reminder>"
),
)
return {"jump_to": "model", "messages": [reminder]}
@override
@hook_config(can_jump_to=["model"])
async def aafter_model(
self,
state: PlanningState,
runtime: Runtime,
) -> dict[str, Any] | None:
"""Async version of after_model."""
return self.after_model(state, runtime)
@@ -0,0 +1,37 @@
"""Middleware for logging LLM token usage."""
import logging
from typing import override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langgraph.runtime import Runtime
logger = logging.getLogger(__name__)
class TokenUsageMiddleware(AgentMiddleware):
"""Logs token usage from model response usage_metadata."""
@override
def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
return self._log_usage(state)
@override
async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict | None:
return self._log_usage(state)
def _log_usage(self, state: AgentState) -> None:
messages = state.get("messages", [])
if not messages:
return None
last = messages[-1]
usage = getattr(last, "usage_metadata", None)
if usage:
logger.info(
"LLM token usage: input=%s output=%s total=%s",
usage.get("input_tokens", "?"),
usage.get("output_tokens", "?"),
usage.get("total_tokens", "?"),
)
return None
@@ -0,0 +1,183 @@
"""Tool error handling middleware and shared runtime middleware builders."""
import logging
from collections.abc import Awaitable, Callable
from typing import override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import ToolMessage
from langgraph.errors import GraphBubbleUp
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.types import Command
from deerflow.config.app_config import AppConfig
logger = logging.getLogger(__name__)
_MISSING_TOOL_CALL_ID = "missing_tool_call_id"
class ToolErrorHandlingMiddleware(AgentMiddleware[AgentState]):
"""Convert tool exceptions into error ToolMessages so the run can continue."""
def _build_error_message(self, request: ToolCallRequest, exc: Exception) -> ToolMessage:
tool_name = str(request.tool_call.get("name") or "unknown_tool")
tool_call_id = str(request.tool_call.get("id") or _MISSING_TOOL_CALL_ID)
detail = str(exc).strip() or exc.__class__.__name__
if len(detail) > 500:
detail = detail[:497] + "..."
content = f"Error: Tool '{tool_name}' failed with {exc.__class__.__name__}: {detail}. Continue with available context, or choose an alternative tool."
return ToolMessage(
content=content,
tool_call_id=tool_call_id,
name=tool_name,
status="error",
)
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
try:
return handler(request)
except GraphBubbleUp:
# Preserve LangGraph control-flow signals (interrupt/pause/resume).
raise
except Exception as exc:
logger.exception("Tool execution failed (sync): name=%s id=%s", request.tool_call.get("name"), request.tool_call.get("id"))
return self._build_error_message(request, exc)
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command:
try:
return await handler(request)
except GraphBubbleUp:
# Preserve LangGraph control-flow signals (interrupt/pause/resume).
raise
except Exception as exc:
logger.exception("Tool execution failed (async): name=%s id=%s", request.tool_call.get("name"), request.tool_call.get("id"))
return self._build_error_message(request, exc)
def _build_runtime_middlewares(
*,
app_config: AppConfig,
include_uploads: bool,
include_dangling_tool_call_patch: bool,
lazy_init: bool = True,
) -> list[AgentMiddleware]:
"""Build shared base middlewares for agent execution."""
from deerflow.agents.middlewares.llm_error_handling_middleware import LLMErrorHandlingMiddleware
from deerflow.agents.middlewares.thread_data_middleware import ThreadDataMiddleware
from deerflow.sandbox.middleware import SandboxMiddleware
middlewares: list[AgentMiddleware] = [
ThreadDataMiddleware(lazy_init=lazy_init),
SandboxMiddleware(lazy_init=lazy_init),
]
if include_uploads:
from deerflow.agents.middlewares.uploads_middleware import UploadsMiddleware
middlewares.insert(1, UploadsMiddleware())
if include_dangling_tool_call_patch:
from deerflow.agents.middlewares.dangling_tool_call_middleware import DanglingToolCallMiddleware
middlewares.append(DanglingToolCallMiddleware())
middlewares.append(LLMErrorHandlingMiddleware(app_config=app_config))
# LLM call metrics — always on, even when the user-facing speed indicator
# is disabled. We append *after* the retry middleware so the metrics
# middleware sits deeper in the wrap chain and observes individual provider
# attempts (including the failed ones).
from deerflow.agents.middlewares.llm_metrics_middleware import LlmMetricsMiddleware
middlewares.append(LlmMetricsMiddleware())
# Guardrail middleware (if configured)
guardrails_config = app_config.guardrails
if guardrails_config.enabled and guardrails_config.provider:
import inspect
from deerflow.guardrails.middleware import GuardrailMiddleware
from deerflow.reflection import resolve_variable
provider_cls = resolve_variable(guardrails_config.provider.use)
provider_kwargs = dict(guardrails_config.provider.config) if guardrails_config.provider.config else {}
# Pass framework hint if the provider accepts it (e.g. for config discovery).
# Built-in providers like AllowlistProvider don't need it, so only inject
# when the constructor accepts 'framework' or '**kwargs'.
if "framework" not in provider_kwargs:
try:
sig = inspect.signature(provider_cls.__init__)
if "framework" in sig.parameters or any(p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()):
provider_kwargs["framework"] = "deerflow"
except (ValueError, TypeError):
pass
provider = provider_cls(**provider_kwargs)
middlewares.append(GuardrailMiddleware(provider, fail_closed=guardrails_config.fail_closed, passport=guardrails_config.passport))
from deerflow.agents.middlewares.sandbox_audit_middleware import SandboxAuditMiddleware
middlewares.append(SandboxAuditMiddleware())
middlewares.append(ToolErrorHandlingMiddleware())
# Tool / skill call metrics — appended last so it sits *deepest* in the
# wrap_tool_call chain: its handler is the raw tool, so it observes the
# unconverted exception (before ToolErrorHandlingMiddleware turns it into
# an error ToolMessage) and the raw return value.
from deerflow.agents.middlewares.tool_metrics_middleware import ToolMetricsMiddleware
middlewares.append(ToolMetricsMiddleware())
return middlewares
def build_lead_runtime_middlewares(*, app_config: AppConfig, lazy_init: bool = True) -> list[AgentMiddleware]:
"""Middlewares shared by lead agent runtime before lead-only middlewares."""
return _build_runtime_middlewares(
app_config=app_config,
include_uploads=True,
include_dangling_tool_call_patch=True,
lazy_init=lazy_init,
)
def build_subagent_runtime_middlewares(
*,
app_config: AppConfig | None = None,
model_name: str | None = None,
lazy_init: bool = True,
) -> list[AgentMiddleware]:
"""Middlewares shared by subagent runtime before subagent-only middlewares."""
if app_config is None:
from deerflow.config import get_app_config
app_config = get_app_config()
middlewares = _build_runtime_middlewares(
app_config=app_config,
include_uploads=False,
include_dangling_tool_call_patch=True,
lazy_init=lazy_init,
)
if model_name is None and app_config.models:
model_name = app_config.models[0].name
model_config = app_config.get_model_config(model_name) if model_name else None
if model_config is not None and model_config.supports_vision:
from deerflow.agents.middlewares.view_image_middleware import ViewImageMiddleware
middlewares.append(ViewImageMiddleware())
return middlewares
@@ -0,0 +1,314 @@
"""Middleware that records per-tool-call metrics for the admin audit page.
Every tool / skill invocation ends with one row in ``tool_call_metrics``:
- Successes record the wall-clock duration.
- Failures record a coarse ``error_category`` plus a one-line message.
Two failure shapes are captured:
1. **Raised exceptions** — the tool blew up. We record, then re-raise so the
outer :class:`ToolErrorHandlingMiddleware` still converts it into an error
``ToolMessage`` for the model.
2. **Self-handled errors** — search/retrieval tools (Serper, Tavily, Jina, …)
catch their own HTTP 429/403/timeout and *return* an error payload instead
of raising. Those never reach an ``except`` block, so we also inspect the
returned ``ToolMessage``: an ``status == "error"`` message, or content that
looks like an error string, is bucketed too.
This middleware is appended **after** ``ToolErrorHandlingMiddleware`` so it
sits deepest in the ``wrap_tool_call`` chain — its handler is the raw tool, so
it observes the unconverted exception and the raw return value.
Writes go through a best-effort store: a DB outage logs a warning and the
agent runtime keeps running.
"""
from __future__ import annotations
import logging
import re
import time
import uuid
from collections.abc import Awaitable, Callable
from datetime import UTC, datetime
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import ToolMessage
from langgraph.errors import GraphBubbleUp
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.types import Command
from deerflow.persistence.engine import fire_and_forget_db_write, get_session_factory
from deerflow.persistence.tool_metrics import ToolMetricRecord, make_tool_metrics_store
from deerflow.persistence.tool_metrics.base import ToolMetricsStore
from deerflow.runtime.user_context import get_effective_user_id
logger = logging.getLogger(__name__)
def _now() -> datetime:
return datetime.now(UTC)
def _trim(text: str, limit: int = 500) -> str:
text = (text or "").strip()
return text if len(text) <= limit else text[: limit - 3] + "..."
def _classify_error(text: str) -> str:
"""Bucket an error string into a coarse, admin-friendly category."""
t = (text or "").lower()
if any(k in t for k in ("429", "rate limit", "ratelimit", "too many request", "quota")):
return "rate_limited"
if any(k in t for k in ("403", "forbidden", "ip ban", "ip block", "blocked", "access denied", "banned")):
return "ip_blocked"
if any(k in t for k in ("401", "unauthorized", "api key", "apikey", "invalid key", "authentication", "credential")):
return "auth_error"
if any(k in t for k in ("timeout", "timed out", "deadline")):
return "timeout"
if any(k in t for k in ("connecterror", "connection error", "connection refused", "network", "dns", "unreachable", "ssl", "proxy")):
return "network_error"
if any(k in t for k in ("404", "not found")):
return "not_found"
if any(k in t for k in ("no results", "no result", "0 results", "empty result")):
return "empty_result"
return "tool_error"
def _content_text(content: Any) -> str:
"""Flatten a tool result's content (string or block list) into text."""
if content is None:
return ""
if isinstance(content, str):
return content
if isinstance(content, list):
parts: list[str] = []
for block in content:
if isinstance(block, str):
parts.append(block)
elif isinstance(block, dict):
text = block.get("text")
if isinstance(text, str):
parts.append(text)
return " ".join(parts)
return str(content)
def _looks_like_error(text: str) -> bool:
"""Heuristically detect a self-handled error payload returned as content.
Deliberately conservative — only an explicit ``Error:`` prefix or a JSON
object whose first key is ``error`` counts, so a normal result that merely
mentions the word "error" is not misclassified.
"""
head = (text or "").lstrip()[:64].lower()
return head.startswith("error:") or head.startswith('{"error"') or head.startswith("{'error'")
# Skill tools whose ``name`` argument names one specific Agent Skill directly.
_SKILL_NAME_ARG_TOOLS = {"skill_view", "skill_manage", "skill_archive"}
# Matches a skill directory embedded in any tool-argument path. Skills live
# under ``skills/{public,custom}/{name}/`` — both inside the sandbox
# (``/mnt/skills/...``) and on the host. The lead agent's system prompt tells
# it to load a skill by calling ``read_file`` on that SKILL.md path (it does
# NOT call a dedicated "use skill" tool), so the skill name has to be recovered
# from the path argument of whatever tool touched it (read_file / bash / ls /
# str_replace / write_file ...).
_SKILL_PATH_RE = re.compile(r"[\\/]skills[\\/](?:public|custom)[\\/]([^\\/]+)(?:[\\/]|$)")
def _skill_name_from_call(tool_name: str | None, tool_call: Any) -> str | None:
"""Recover the Agent Skill a tool call targets, or ``None``.
Two detection paths:
1. ``skill_view`` / ``skill_manage`` / ``skill_archive`` take an explicit
``name`` argument.
2. Every other tool references a skill by *path*. The canonical skill
invocation is ``read_file('/mnt/skills/<cat>/<name>/SKILL.md')``; helper
files and ``bash`` script runs hit the same directory. So we scan the
string arguments for the ``skills/{public,custom}/{name}/`` shape.
"""
if not isinstance(tool_call, dict):
return None
args = tool_call.get("args")
if not isinstance(args, dict):
return None
# Case 1 — explicit ``name`` argument on the skill tools.
if tool_name in _SKILL_NAME_ARG_TOOLS:
raw = args.get("name")
if isinstance(raw, str) and raw.strip():
return raw.strip()
# Case 2 — a skill path inside any string argument.
for value in args.values():
if isinstance(value, str):
match = _SKILL_PATH_RE.search(value)
if match:
return match.group(1)
return None
def _evaluate_skill_view(text: str) -> tuple[str, str | None, str | None]:
"""Classify a ``skill_view`` return.
``skill_view`` never raises — on failure it returns a plain string
(``Skill 'x' not found.`` / ``Error reading skill 'x': ...``); on success
it returns the SKILL.md content. So success/failure must be read off the
returned text, not an exception or ``status`` flag.
"""
head = (text or "").lstrip()
low = head[:200].lower()
if head.startswith("Skill '") and "not found" in low:
return "error", "not_found", _trim(text)
if low.startswith("error reading skill"):
return "error", _classify_error(text), _trim(text)
return "success", None, None
def _evaluate_result(result: Any, tool_name: str | None) -> tuple[str, str | None, str | None]:
"""Return ``(status, error_category, error_message)`` for a tool return."""
if isinstance(result, ToolMessage):
text = _content_text(result.content)
if getattr(result, "status", None) == "error":
return "error", _classify_error(text), _trim(text)
# skill_view swallows its own failures into a plain string return.
if tool_name == "skill_view":
return _evaluate_skill_view(text)
if _looks_like_error(text):
return "error", _classify_error(text), _trim(text)
return "success", None, None
# Command (control flow) or any other shape — treat as a successful call.
return "success", None, None
class ToolMetricsMiddleware(AgentMiddleware[AgentState]):
"""Wrap each tool call to time it and persist a metric row."""
def __init__(self, *, store: ToolMetricsStore | None = None, **kwargs: Any) -> None:
super().__init__(**kwargs)
self._store_override = store
# -- store / context ----------------------------------------------------
def _store(self) -> ToolMetricsStore | None:
if self._store_override is not None:
return self._store_override
try:
sf = get_session_factory()
except Exception:
return None
return make_tool_metrics_store(sf)
@staticmethod
def _runtime_lookup(request: ToolCallRequest, keys: tuple[str, ...]) -> str | None:
runtime = getattr(request, "runtime", None)
if runtime is None:
return None
context = getattr(runtime, "context", None)
if isinstance(context, dict):
for key in keys:
value = context.get(key)
if isinstance(value, str) and value:
return value
config = getattr(runtime, "config", None)
if isinstance(config, dict):
configurable = config.get("configurable") if isinstance(config.get("configurable"), dict) else {}
metadata = config.get("metadata") if isinstance(config.get("metadata"), dict) else {}
for bucket in (configurable, metadata):
for key in keys:
value = bucket.get(key)
if isinstance(value, str) and value:
return value
return None
def _build_base_record(self, request: ToolCallRequest) -> ToolMetricRecord:
tool_call = getattr(request, "tool_call", None) or {}
tool_name = tool_call.get("name") if isinstance(tool_call, dict) else None
tool_name = str(tool_name) if tool_name else None
return ToolMetricRecord(
id=uuid.uuid4().hex,
created_at=_now(),
user_id=get_effective_user_id(),
thread_id=self._runtime_lookup(request, ("thread_id",)),
run_id=self._runtime_lookup(request, ("run_id", "langgraph_run_id")),
agent_name=self._runtime_lookup(request, ("agent_name", "agent_id")),
skill_name=_skill_name_from_call(tool_name, tool_call),
tool_name=tool_name,
)
# -- finalize -----------------------------------------------------------
def _finalize_result(self, record: ToolMetricRecord, result: Any, started: float) -> None:
record.duration_ms = int(max(0.0, time.monotonic() - started) * 1000)
record.status, record.error_category, record.error_message = _evaluate_result(
result, record.tool_name
)
def _finalize_error(self, record: ToolMetricRecord, exc: BaseException, started: float) -> None:
record.duration_ms = int(max(0.0, time.monotonic() - started) * 1000)
record.status = "error"
name = exc.__class__.__name__
combined = f"{name}: {(str(exc) or name).strip()}"
record.error_category = _classify_error(combined)
record.error_message = _trim(combined)
def _flush(self, record: ToolMetricRecord) -> None:
store = self._store()
if store is None:
return
# Route the best-effort write onto the engine's home loop (a tool call that ran
# in a worker thread would otherwise do ``asyncio.run(store.record(...))`` and reuse
# the global engine's pooled connections cross-loop → "got Future attached to a
# different loop"). See ``fire_and_forget_db_write``.
try:
fire_and_forget_db_write(store.record(record))
except Exception:
logger.warning("ToolMetricsMiddleware: failed to flush metric %s", record.id, exc_info=True)
# -- wrap ---------------------------------------------------------------
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
record = self._build_base_record(request)
started = time.monotonic()
try:
result = handler(request)
except GraphBubbleUp:
# LangGraph control flow — not a tool failure.
raise
except Exception as exc:
self._finalize_error(record, exc, started)
self._flush(record)
raise
self._finalize_result(record, result, started)
self._flush(record)
return result
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command:
record = self._build_base_record(request)
started = time.monotonic()
try:
result = await handler(request)
except GraphBubbleUp:
raise
except Exception as exc:
self._finalize_error(record, exc, started)
self._flush(record)
raise
self._finalize_result(record, result, started)
self._flush(record)
return result
@@ -0,0 +1,382 @@
"""Middleware to inject uploaded files information into agent context."""
import logging
import shutil
from pathlib import Path
from typing import NotRequired, override
from urllib.parse import unquote
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import HumanMessage
from langgraph.runtime import Runtime
from deerflow.config.paths import Paths, get_paths
from deerflow.runtime.thread_paths import resolve_path_user_id
from deerflow.utils.file_conversion import extract_outline
logger = logging.getLogger(__name__)
_OUTLINE_PREVIEW_LINES = 5
# Image files are understood via the `view_image` tool (which routes to the
# configured vision model), never by reading their bytes. Listing them with the
# generic read_file/grep guidance made the agent try to parse image binaries
# with bash/python, which fails and wastes turns.
_IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp"}
_ARTIFACT_URL_MARKER = "/artifacts/"
def _extract_outline_for_file(file_path: Path) -> tuple[list[dict], list[str]]:
"""Return the document outline and fallback preview for *file_path*.
Looks for a sibling ``<stem>.md`` file produced by the upload conversion
pipeline.
Returns:
(outline, preview) where:
- outline: list of ``{title, line}`` dicts (plus optional sentinel).
Empty when no headings are found or no .md exists.
- preview: first few non-empty lines of the .md, used as a content
anchor when outline is empty so the agent has some context.
Empty when outline is non-empty (no fallback needed).
"""
md_path = file_path.with_suffix(".md")
if not md_path.is_file():
return [], []
outline = extract_outline(md_path)
if outline:
logger.debug("Extracted %d outline entries from %s", len(outline), file_path.name)
return outline, []
# outline is empty — read the first few non-empty lines as a content preview
preview: list[str] = []
try:
with md_path.open(encoding="utf-8") as f:
for line in f:
stripped = line.strip()
if stripped:
preview.append(stripped)
if len(preview) >= _OUTLINE_PREVIEW_LINES:
break
except Exception:
logger.debug("Failed to read preview lines from %s", md_path, exc_info=True)
return [], preview
class UploadsMiddlewareState(AgentState):
"""State schema for uploads middleware."""
uploaded_files: NotRequired[list[dict] | None]
class UploadsMiddleware(AgentMiddleware[UploadsMiddlewareState]):
"""Middleware to inject uploaded files information into the agent context.
Reads file metadata from the current message's additional_kwargs.files
(set by the frontend after upload) and prepends an <uploaded_files> block
to the last human message so the model knows which files are available.
"""
state_schema = UploadsMiddlewareState
def __init__(self, base_dir: str | None = None):
"""Initialize the middleware.
Args:
base_dir: Base directory for thread data. Defaults to Paths resolution.
"""
super().__init__()
self._paths = Paths(base_dir) if base_dir else get_paths()
def _format_file_entry(self, file: dict, lines: list[str]) -> None:
"""Append a single file entry (name, size, path, optional outline) to lines."""
size_kb = file["size"] / 1024
size_str = f"{size_kb:.1f} KB" if size_kb < 1024 else f"{size_kb / 1024:.1f} MB"
lines.append(f"- {file['filename']} ({size_str})")
lines.append(f" Path: {file['path']}")
# Images must be understood through the vision model, not by reading bytes.
extension = str(file.get("extension") or Path(file["filename"]).suffix).lower()
if extension in _IMAGE_EXTENSIONS:
lines.append(f" This is an image. To understand it, call the `view_image` tool with image_path='{file['path']}' (optionally pass a `question`).")
lines.append(" The configured vision model will analyze it and return a description — trust that result.")
lines.append(" Do NOT read, open, or parse the image with read_file, grep, bash, python, PIL, or any byte-level inspection; those cannot interpret image content.")
lines.append("")
return
outline = file.get("outline") or []
if outline:
truncated = outline[-1].get("truncated", False)
visible = [e for e in outline if not e.get("truncated")]
lines.append(" Document outline (use `read_file` with line ranges to read sections):")
for entry in visible:
lines.append(f" L{entry['line']}: {entry['title']}")
if truncated:
lines.append(f" ... (showing first {len(visible)} headings; use `read_file` to explore further)")
else:
preview = file.get("outline_preview") or []
if preview:
lines.append(" No structural headings detected. Document begins with:")
for text in preview:
lines.append(f" > {text}")
lines.append(" Use `grep` to search for keywords (e.g. `grep(pattern='keyword', path='/mnt/user-data/uploads/')`).")
lines.append("")
def _create_files_message(self, new_files: list[dict], historical_files: list[dict]) -> str:
"""Create a formatted message listing uploaded files.
Args:
new_files: Files uploaded in the current message.
historical_files: Files uploaded in previous messages.
Each file dict may contain an optional ``outline`` key — a list of
``{title, line}`` dicts extracted from the converted Markdown file.
Returns:
Formatted string inside <uploaded_files> tags.
"""
lines = ["<uploaded_files>"]
lines.append("The following files were uploaded in this message:")
lines.append("")
if new_files:
for file in new_files:
self._format_file_entry(file, lines)
else:
lines.append("(empty)")
lines.append("")
if historical_files:
lines.append("The following files were uploaded in previous messages and are still available:")
lines.append("")
for file in historical_files:
self._format_file_entry(file, lines)
lines.append("To work with these files:")
lines.append("- Read from the file first — use the outline line numbers and `read_file` to locate relevant sections.")
lines.append("- Use `grep` to search for keywords when you are not sure which section to look at")
lines.append(" (e.g. `grep(pattern='revenue', path='/mnt/user-data/uploads/')`).")
lines.append("- Use `glob` to find files by name pattern")
lines.append(" (e.g. `glob(pattern='**/*.md', path='/mnt/user-data/uploads/')`).")
lines.append("- Only fall back to web search if the file content is clearly insufficient to answer the question.")
lines.append("</uploaded_files>")
return "\n".join(lines)
def _import_file_from_artifact_url(
self,
file_info: dict,
uploads_dir: Path | None,
) -> bool:
"""Copy a previously uploaded file into the current thread when possible.
iframe-style callers may pass file metadata that points at an upload
from another DeerFlow thread. The current run thread still needs a real
file under its own ``/mnt/user-data/uploads`` directory, otherwise this
middleware will filter the entry out during existence checks.
"""
filename = file_info.get("filename") or ""
artifact_url = str(file_info.get("artifact_url") or "").strip()
if not filename or uploads_dir is None or not artifact_url:
return False
if not artifact_url.startswith("/api/threads/") or _ARTIFACT_URL_MARKER not in artifact_url:
return False
prefix, encoded_virtual_path = artifact_url.split(_ARTIFACT_URL_MARKER, 1)
source_thread_id = prefix.removeprefix("/api/threads/").strip("/")
if not source_thread_id or not encoded_virtual_path:
return False
virtual_path = "/" + unquote(encoded_virtual_path.lstrip("/"))
if Path(virtual_path).name != filename:
return False
try:
source_path = self._paths.resolve_virtual_path(
source_thread_id,
virtual_path,
user_id=resolve_path_user_id(source_thread_id),
)
except ValueError:
logger.debug("Failed to resolve uploaded artifact path: %s", artifact_url, exc_info=True)
return False
if not source_path.is_file():
return False
uploads_dir.mkdir(parents=True, exist_ok=True)
target_path = uploads_dir / filename
shutil.copy2(source_path, target_path)
source_markdown = source_path.with_suffix(".md")
if source_markdown.is_file() and source_markdown != source_path:
shutil.copy2(source_markdown, target_path.with_suffix(".md"))
return True
def _files_from_kwargs(self, message: HumanMessage, uploads_dir: Path | None = None) -> list[dict] | None:
"""Extract file info from message additional_kwargs.files.
The frontend sends uploaded file metadata in additional_kwargs.files
after a successful upload. Each entry has: filename, size (bytes),
path (virtual path), status.
Args:
message: The human message to inspect.
uploads_dir: Physical uploads directory used to verify file existence.
When provided, entries whose files no longer exist are skipped.
Returns:
List of file dicts with virtual paths, or None if the field is absent or empty.
"""
kwargs_files = (message.additional_kwargs or {}).get("files")
if not isinstance(kwargs_files, list) or not kwargs_files:
return None
files = []
for f in kwargs_files:
if not isinstance(f, dict):
continue
filename = f.get("filename") or ""
if not filename or Path(filename).name != filename:
continue
if uploads_dir is not None and not (uploads_dir / filename).is_file():
if not self._import_file_from_artifact_url(f, uploads_dir):
continue
files.append(
{
"filename": filename,
"size": int(f.get("size") or 0),
"path": f"/mnt/user-data/uploads/{filename}",
"extension": Path(filename).suffix,
}
)
return files if files else None
@override
def before_agent(self, state: UploadsMiddlewareState, runtime: Runtime) -> dict | None:
"""Inject uploaded files information before agent execution.
New files come from the current message's additional_kwargs.files.
Historical files are scanned from the thread's uploads directory,
excluding the new ones.
Prepends <uploaded_files> context to the last human message content.
The original additional_kwargs (including files metadata) is preserved
on the updated message so the frontend can read it from the stream.
Args:
state: Current agent state.
runtime: Runtime context containing thread_id.
Returns:
State updates including uploaded files list.
"""
messages = list(state.get("messages", []))
if not messages:
return None
last_message_index = len(messages) - 1
last_message = messages[last_message_index]
if not isinstance(last_message, HumanMessage):
return None
# Only turns with fresh upload metadata need the uploads directory.
# Avoid resolving the thread owner (which may hit the DB) for ordinary
# no-file chat turns, including ephemeral open-chat requests.
kwargs_files = (last_message.additional_kwargs or {}).get("files")
if not isinstance(kwargs_files, list) or not kwargs_files:
return None
# Resolve uploads directory for existence checks
thread_id = (runtime.context or {}).get("thread_id")
if thread_id is None:
try:
from langgraph.config import get_config
thread_id = get_config().get("configurable", {}).get("thread_id")
except RuntimeError:
pass # get_config() raises outside a runnable context (e.g. unit tests)
uploads_dir = self._paths.sandbox_uploads_dir(thread_id, user_id=resolve_path_user_id(thread_id)) if thread_id else None
# Get newly uploaded files from the current message's additional_kwargs.files
new_files = self._files_from_kwargs(last_message, uploads_dir) or []
# Only inject when the *current* message actually carries new uploads.
# Turns without a fresh upload must not re-inject previously uploaded
# files: the original upload turn already injected (and persisted) their
# <uploaded_files> block, and the files remain physically available for
# read_file/grep/view_image. Re-injecting on every later message made the
# agent re-reference old images/docs, and — since the frontend parses
# files out of the <uploaded_files> content when additional_kwargs.files
# is empty — re-rendered the old attachment on each new question.
if not new_files:
return None
# Collect historical files from the uploads directory (all except the new ones)
new_filenames = {f["filename"] for f in new_files}
historical_files: list[dict] = []
if uploads_dir and uploads_dir.exists():
for file_path in sorted(uploads_dir.iterdir()):
if file_path.is_file() and file_path.name not in new_filenames:
stat = file_path.stat()
outline, preview = _extract_outline_for_file(file_path)
historical_files.append(
{
"filename": file_path.name,
"size": stat.st_size,
"path": f"/mnt/user-data/uploads/{file_path.name}",
"extension": file_path.suffix,
"outline": outline,
"outline_preview": preview,
}
)
# Attach outlines to new files as well
if uploads_dir:
for file in new_files:
phys_path = uploads_dir / file["filename"]
outline, preview = _extract_outline_for_file(phys_path)
file["outline"] = outline
file["outline_preview"] = preview
logger.debug(f"New files: {[f['filename'] for f in new_files]}, historical: {[f['filename'] for f in historical_files]}")
# Create files message and prepend to the last human message content
files_message = self._create_files_message(new_files, historical_files)
# Extract original content - handle both string and list formats
original_content = last_message.content
if isinstance(original_content, str):
# Simple case: string content, just prepend files message
updated_content = f"{files_message}\n\n{original_content}"
elif isinstance(original_content, list):
# Complex case: list content (multimodal), preserve all blocks
# Prepend files message as the first text block
files_block = {"type": "text", "text": f"{files_message}\n\n"}
# Keep all original blocks (including images)
updated_content = [files_block, *original_content]
else:
# Other types, preserve as-is
updated_content = original_content
# Create new message with combined content.
# Preserve additional_kwargs (including files metadata) so the frontend
# can read structured file info from the streamed message.
updated_message = HumanMessage(
content=updated_content,
id=last_message.id,
name=last_message.name,
additional_kwargs=last_message.additional_kwargs,
)
messages[last_message_index] = updated_message
return {
"uploaded_files": new_files,
"messages": messages,
}
@@ -0,0 +1,228 @@
"""Middleware for injecting image details into conversation before LLM call."""
import logging
from typing import override
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
from langgraph.runtime import Runtime
from deerflow.agents.thread_state import ThreadState
logger = logging.getLogger(__name__)
class ViewImageMiddlewareState(ThreadState):
"""Reuse the thread state so reducer-backed keys keep their annotations."""
class ViewImageMiddleware(AgentMiddleware[ViewImageMiddlewareState]):
"""Injects image details as a human message before LLM calls when view_image tools have completed.
This middleware:
1. Runs before each LLM call
2. Checks if the last assistant message contains view_image tool calls
3. Verifies all tool calls in that message have been completed (have corresponding ToolMessages)
4. If conditions are met, creates a human message with all viewed image details (including base64 data)
5. Adds the message to state so the LLM can see and analyze the images
This enables the LLM to automatically receive and analyze images that were loaded via view_image tool,
without requiring explicit user prompts to describe the images.
"""
state_schema = ViewImageMiddlewareState
def _get_last_assistant_message(self, messages: list) -> AIMessage | None:
"""Get the last assistant message from the message list.
Args:
messages: List of messages
Returns:
Last AIMessage or None if not found
"""
for msg in reversed(messages):
if isinstance(msg, AIMessage):
return msg
return None
def _has_view_image_tool(self, message: AIMessage) -> bool:
"""Check if the assistant message contains view_image tool calls.
Args:
message: Assistant message to check
Returns:
True if message contains view_image tool calls
"""
if not hasattr(message, "tool_calls") or not message.tool_calls:
return False
return any(tool_call.get("name") == "view_image" for tool_call in message.tool_calls)
def _all_tools_completed(self, messages: list, assistant_msg: AIMessage) -> bool:
"""Check if all tool calls in the assistant message have been completed.
Args:
messages: List of all messages
assistant_msg: The assistant message containing tool calls
Returns:
True if all tool calls have corresponding ToolMessages
"""
if not hasattr(assistant_msg, "tool_calls") or not assistant_msg.tool_calls:
return False
# Get all tool call IDs from the assistant message
tool_call_ids = {tool_call.get("id") for tool_call in assistant_msg.tool_calls if tool_call.get("id")}
# Find the index of the assistant message
try:
assistant_idx = messages.index(assistant_msg)
except ValueError:
return False
# Get all ToolMessages after the assistant message
completed_tool_ids = set()
for msg in messages[assistant_idx + 1 :]:
if isinstance(msg, ToolMessage) and msg.tool_call_id:
completed_tool_ids.add(msg.tool_call_id)
# Check if all tool calls have been completed
return tool_call_ids.issubset(completed_tool_ids)
def _create_image_details_message(self, state: ViewImageMiddlewareState) -> list[str | dict]:
"""Create a formatted message with all viewed image details.
Args:
state: Current state containing viewed_images
Returns:
List of content blocks (text and images) for the HumanMessage
"""
viewed_images = state.get("viewed_images", {})
if not viewed_images:
# Return a properly formatted text block, not a plain string array
return [{"type": "text", "text": "No images have been viewed."}]
# Build the message with image information
content_blocks: list[str | dict] = [{"type": "text", "text": "Here are the images you've viewed:"}]
for image_path, image_data in viewed_images.items():
mime_type = image_data.get("mime_type", "unknown")
base64_data = image_data.get("base64", "")
# Add text description
content_blocks.append({"type": "text", "text": f"\n- **{image_path}** ({mime_type})"})
# Add the actual image data so LLM can "see" it
if base64_data:
content_blocks.append(
{
"type": "image_url",
"image_url": {"url": f"data:{mime_type};base64,{base64_data}"},
}
)
return content_blocks
def _should_inject_image_message(self, state: ViewImageMiddlewareState) -> bool:
"""Determine if we should inject an image details message.
Args:
state: Current state
Returns:
True if we should inject the message
"""
messages = state.get("messages", [])
if not messages:
return False
# Nothing to inject when no image data was captured (e.g. delegated
# recognition handled the image in the tool and stored no base64).
# Avoids injecting a useless "No images have been viewed." message.
if not state.get("viewed_images"):
return False
# Get the last assistant message
last_assistant_msg = self._get_last_assistant_message(messages)
if not last_assistant_msg:
return False
# Check if it has view_image tool calls
if not self._has_view_image_tool(last_assistant_msg):
return False
# Check if all tools have been completed
if not self._all_tools_completed(messages, last_assistant_msg):
return False
# Check if we've already added an image details message
# Look for a human message after the last assistant message that contains image details
assistant_idx = messages.index(last_assistant_msg)
for msg in messages[assistant_idx + 1 :]:
if isinstance(msg, HumanMessage):
content_str = str(msg.content)
if "Here are the images you've viewed" in content_str or "Here are the details of the images you've viewed" in content_str:
# Already added, don't add again
return False
return True
def _inject_image_message(self, state: ViewImageMiddlewareState) -> dict | None:
"""Internal helper to inject image details message.
Args:
state: Current state
Returns:
State update with additional human message, or None if no update needed
"""
if not self._should_inject_image_message(state):
return None
# Create the image details message with text and image content
image_content = self._create_image_details_message(state)
# Create a new human message with mixed content (text + images)
human_msg = HumanMessage(content=image_content)
logger.debug("Injecting image details message with images before LLM call")
# Return state update with the new message
return {"messages": [human_msg]}
@override
def before_model(self, state: ViewImageMiddlewareState, runtime: Runtime) -> dict | None:
"""Inject image details message before LLM call if view_image tools have completed (sync version).
This runs before each LLM call, checking if the previous turn included view_image
tool calls that have all completed. If so, it injects a human message with the image
details so the LLM can see and analyze the images.
Args:
state: Current state
runtime: Runtime context (unused but required by interface)
Returns:
State update with additional human message, or None if no update needed
"""
return self._inject_image_message(state)
@override
async def abefore_model(self, state: ViewImageMiddlewareState, runtime: Runtime) -> dict | None:
"""Inject image details message before LLM call if view_image tools have completed (async version).
This runs before each LLM call, checking if the previous turn included view_image
tool calls that have all completed. If so, it injects a human message with the image
details so the LLM can see and analyze the images.
Args:
state: Current state
runtime: Runtime context (unused but required by interface)
Returns:
State update with additional human message, or None if no update needed
"""
return self._inject_image_message(state)
@@ -0,0 +1,588 @@
"""Redirect writing-mode Markdown deliverables onto ``deep_research_report``.
Writing mode still allows normal chat, search, and clarification. The report
only comes from the pipeline, and no hand-write path can even start:
1. ``wrap_model_call`` removes ``write_file`` / ``str_replace`` / ``bash``
from the model binding for the whole first-report run. ``after_model``
rewrites can only fire AFTER a model response completes, so any write tool
left bound lets weak models stream the full essay into its arguments first
(``write_file`` content or a bash ``cat > report.md << EOF`` heredoc) for
tens of seconds, invisible to the user. bash is the only execution tool
that writes files, so excluding it too leaves NO tool the model could use
to start a file write — at delivery time the only path is the
``deep_research_report`` call itself.
2. Hallucinated calls (emitted despite not being bound) are still handled:
bash heredoc / ``python open(..., 'w')`` / ``tee`` writes and leftover
``write_file`` / ``str_replace`` calls are rewritten to the pipeline by
``after_model``, and ``wrap_tool_call`` rejects whatever reaches the tool
layer.
The rewritten pipeline call carries ``topic`` = the user's original request
(clarification answers skipped) plus ``focus`` = the clarification answers
(direction/type/length), so the pipeline writes the refined subject instead of
the raw prompt text.
After the pipeline has succeeded once in this thread, further
``deep_research_report`` / hand-written report writes / ``read_file`` of the
report are dropped. The first time that happens, a hidden summary nudge is
injected and the graph jumps back to the model so it can write the 2–3
sentence wrap-up. If it still tries to loop after that nudge, the dropped
message is patched to a fallback summary and the turn ends — the user always
sees a closing message.
This middleware never sets ``tool_choice``. Thinking-mode providers (Aliyun
compatible-mode) reject ``required`` / object ``tool_choice`` with HTTP 400.
"""
from __future__ import annotations
import json
import logging
import re
from collections.abc import Awaitable, Callable
from copy import deepcopy
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware, hook_config
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.runtime import Runtime
from langgraph.types import Command
from deerflow.tools.builtins.deep_research_report_tool import is_writing_mode_report_path
logger = logging.getLogger(__name__)
TOOL_NAME = "deep_research_report"
_WRITE_TOOLS = frozenset({"write_file", "str_replace"})
_READ_TOOLS = frozenset({"read_file", "read_multiple_files"})
_PRESENT_TOOL = "present_files"
_BASH_TOOL = "bash"
_OUTPUTS_PREFIX = "/mnt/user-data/outputs"
_MAX_TOPIC_CHARS = 500
_MAX_FOCUS_CHARS = 600
_NUDGE_KWARG = "writing_mode_summary_nudge"
_FALLBACK_SUMMARY = "写作管线已完成,报告已写入 /mnt/user-data/outputs/report.md 并展示在右侧沙箱,可直接查看。如需调整内容,请在下一条消息中告诉我具体要求。"
_REJECT_HANDWRITTEN = "写作模式的报告文件必须由 `deep_research_report` 生成,禁止用 write_file / str_replace / bash 命令(cat > 重定向、python open(..., 'w')、tee 等)手写报告。请立即调用 `deep_research_report`(topic=用户课题原文)。"
_REJECT_AFTER_SUCCESS = (
"写作管线已经完成,报告已写入 /mnt/user-data/outputs/report.md 并展示给用户。"
"禁止再次调用 deep_research_report,也禁止用 write_file / str_replace / bash / "
"read_file 读写该报告。请只用 2-3 句话总结核心结论后结束本轮,不要再调用任何文件或写作工具。"
)
_SUMMARY_NUDGE = (
"<system_reminder>\n写作管线已经完成,报告已写入 /mnt/user-data/outputs/report.md 并展示给用户。\n请只用 2-3 句话总结核心结论,不要再调用任何工具,不要阅读或重写该文件。\n不要评价材料是否不足,不要计划重写。\n</system_reminder>"
)
def _is_visible_human(message: Any) -> bool:
if not isinstance(message, HumanMessage):
return False
kwargs = getattr(message, "additional_kwargs", None) or {}
return not kwargs.get("hide_from_ui")
def _normalize_args(raw: object) -> dict[str, Any]:
if isinstance(raw, dict):
return raw
if isinstance(raw, str):
try:
parsed = json.loads(raw)
except (TypeError, ValueError, json.JSONDecodeError):
return {}
return parsed if isinstance(parsed, dict) else {}
return {}
def _tool_field(tool_call: object, key: str, default: Any = None) -> Any:
if isinstance(tool_call, dict):
return tool_call.get(key, default)
getter = getattr(tool_call, "get", None)
if callable(getter):
return getter(key, default)
return getattr(tool_call, key, default)
def _tool_name(tool_call: object) -> str:
return str(_tool_field(tool_call, "name", "") or "")
def _tool_path(tool_call: object) -> str:
args = _normalize_args(_tool_field(tool_call, "args", {}))
path = args.get("path")
if path is None:
files = args.get("files") or args.get("filepaths") or args.get("paths")
if isinstance(files, list) and files:
path = files[0]
return str(path or "").strip().replace("\\", "/")
def _is_outputs_markdown_path(path: str) -> bool:
if is_writing_mode_report_path(path):
return True
if not path:
return False
lowered = path.lower()
if not (lowered.endswith(".md") or lowered.endswith(".markdown")):
return False
if path == _OUTPUTS_PREFIX or path.startswith(f"{_OUTPUTS_PREFIX}/"):
return True
relative = path.lstrip("./")
return relative == "outputs" or relative.startswith("outputs/")
# bash 手写报告的识别:写入动作(重定向 / tee / python 只写打开 / write_text)
# 的目标本身是交付物 Markdown。纯读取(mkdir、wc、cat 输出)不拦。
_BASH_MD_PATH = re.compile(r"""['"]([^'"]{0,200}\.md)['"]|(^|[\s;|&<>()=])([^\s;'"&|<>(){},]{0,200}\.md)\b""")
_BASH_MD_REDIRECT = re.compile(r">{1,2}\s*([^\s;|&>]{0,200}\.md)\b")
_BASH_MD_TEE = re.compile(r"\btee\s+(?:-[A-Za-z]+\s+)*([^\s;|&<>]{0,200}\.md)\b")
_BASH_MD_PY_WRITE = re.compile(r"""open\s*\(\s*['"][^'"]{0,200}\.md['"]\s*,\s*['"]w""")
def _bash_command_writes_report(command: str) -> bool:
"""True 当 bash 命令在向写作模式的 Markdown 交付物写入内容。
实测弱模型被禁用手写工具后会绕道 bash:``cat > report.md << 'EOF'``、
``python3 << PYEOF`` + ``open(..., 'w')``、``tee`` 等。按「写入动作的
目标(或命令提到的路径)是 outputs Markdown / report.md」判定;
mkdir、wc、cat 读取这类无写入动作的命令不受影响。
"""
if not command or ".md" not in command:
return False
for pattern in (_BASH_MD_REDIRECT, _BASH_MD_TEE):
if any(_is_outputs_markdown_path(match.group(1)) for match in pattern.finditer(command)):
return True
paths = [quoted or bare or "" for quoted, _, bare in _BASH_MD_PATH.findall(command)]
if not any(_is_outputs_markdown_path(path) for path in paths):
return False
return bool(_BASH_MD_PY_WRITE.search(command)) or "write_text" in command or "write_bytes" in command
def is_handwritten_report_call(tool_call: object) -> bool:
"""True when the model is about to hand-write the writing-mode Markdown file."""
name = _tool_name(tool_call)
if name in _WRITE_TOOLS:
return _is_outputs_markdown_path(_tool_path(tool_call))
if name == _BASH_TOOL:
args = _normalize_args(_tool_field(tool_call, "args", {}))
return _bash_command_writes_report(str(args.get("command") or ""))
return False
def is_report_present_call(tool_call: object) -> bool:
if _tool_name(tool_call) != _PRESENT_TOOL:
return False
path = _tool_path(tool_call)
if path:
return _is_outputs_markdown_path(path)
args = _normalize_args(_tool_field(tool_call, "args", {}))
files = args.get("files") or args.get("filepaths") or args.get("paths") or []
if isinstance(files, list):
return any(_is_outputs_markdown_path(str(item or "").strip().replace("\\", "/")) for item in files)
return False
def is_pipeline_call(tool_call: object) -> bool:
return _tool_name(tool_call) == TOOL_NAME
def is_report_reread_call(tool_call: object) -> bool:
"""True when the model is about to re-read the writing-mode Markdown file."""
if _tool_name(tool_call) not in _READ_TOOLS:
return False
path = _tool_path(tool_call)
if path:
return _is_outputs_markdown_path(path)
args = _normalize_args(_tool_field(tool_call, "args", {}))
files = args.get("files") or args.get("filepaths") or args.get("paths") or []
if isinstance(files, list):
return any(_is_outputs_markdown_path(str(item or "").strip().replace("\\", "/")) for item in files)
return False
def is_deliverable_loop_call(tool_call: object) -> bool:
"""Pipeline, hand-written report, or presenting the report — all loop fuel."""
return is_pipeline_call(tool_call) or is_handwritten_report_call(tool_call) or is_report_present_call(tool_call)
def is_post_success_loop_call(tool_call: object) -> bool:
"""After a successful pipeline, re-reading the report is also a loop."""
return is_deliverable_loop_call(tool_call) or is_report_reread_call(tool_call)
def _already_nudged_summary(messages: list[Any]) -> bool:
for message in messages:
if not isinstance(message, HumanMessage):
continue
kwargs = getattr(message, "additional_kwargs", None) or {}
if kwargs.get(_NUDGE_KWARG):
return True
return False
def _summary_nudge_message() -> HumanMessage:
return HumanMessage(
content=_SUMMARY_NUDGE,
additional_kwargs={"hide_from_ui": True, _NUDGE_KWARG: True},
)
def _report_tool_succeeded(message: ToolMessage) -> bool:
if str(getattr(message, "name", "") or "") != TOOL_NAME:
return False
status = str(getattr(message, "status", "") or "").lower()
if status == "error":
return False
content = str(getattr(message, "content", "") or "").strip()
if not content:
return False
return not content.lower().startswith("error")
def pipeline_already_succeeded(messages: list[Any]) -> bool:
"""True after any successful ``deep_research_report`` in this thread."""
return any(isinstance(message, ToolMessage) and _report_tool_succeeded(message) for message in messages)
def _message_text(message: Any) -> str:
content = getattr(message, "content", "")
if isinstance(content, list):
parts: list[str] = []
for part in content:
if isinstance(part, str):
parts.append(part)
elif isinstance(part, dict):
text = part.get("text")
if isinstance(text, str):
parts.append(text)
return " ".join(parts).strip()
return str(content or "").strip()
def _is_clarification_result(message: Any) -> bool:
return isinstance(message, ToolMessage) and str(getattr(message, "name", "") or "") == "ask_clarification"
def extract_report_topic(messages: list[Any]) -> str:
"""Use the latest visible user text that is not a clarification answer.
澄清轮里用户对 ask_clarification 的回答(紧跟着澄清 ToolMessage 的人类
消息,如「方向:AI Agent;用途:学术期刊论文」)不是课题本身;拿它当
topic 会让管线给「回答本身」写报告。向上跳过所有回答,取真正的课题原文
(最新一条非回答的用户消息)。
"""
for index in range(len(messages) - 1, -1, -1):
message = messages[index]
if not _is_visible_human(message):
continue
if index > 0 and _is_clarification_result(messages[index - 1]):
continue
text = " ".join(_message_text(message).split())
if text:
return text[:_MAX_TOPIC_CHARS]
return "当前课题"
def extract_report_focus(messages: list[Any], topic: str = "") -> str:
"""Join the user's clarification answers as the pipeline's ``focus``.
澄清回答(方向/类型/篇幅/语气等)不是课题本身,但正是写作要求;
topic 取课题原文的同时把它们汇总进 focus,管线才能按澄清后的
精确主题(如「LLM 的能力边界…」+ 观点评论型 + 3000-5000 字)成稿,
而不是只拿原始请求一句泛写。
"""
parts: list[str] = []
for index, message in enumerate(messages):
if not _is_visible_human(message):
continue
if index == 0 or not _is_clarification_result(messages[index - 1]):
continue
text = " ".join(_message_text(message).split())
if text and text != topic:
parts.append(text)
return ";".join(parts).strip()[:_MAX_FOCUS_CHARS]
def _as_report_call(tool_call: object, topic: str, focus: str = "") -> dict[str, Any]:
call_id = str(_tool_field(tool_call, "id") or "")
args: dict[str, Any] = {"topic": topic}
if focus:
args["focus"] = focus
return {
"name": TOOL_NAME,
"args": args,
"id": call_id,
"type": "tool_call",
}
def _kept_call_ids(calls: list[Any]) -> set[str]:
return {str(_tool_field(call, "id") or "") for call in calls if _tool_field(call, "id")}
def _sync_raw_tool_calls(last: AIMessage, kept: list[Any]) -> dict[str, Any]:
update: dict[str, Any] = {"tool_calls": kept}
additional_kwargs = dict(getattr(last, "additional_kwargs", {}) or {})
raw_calls = additional_kwargs.get("tool_calls")
kept_ids = _kept_call_ids(kept)
rewritten_by_id = {str(_tool_field(call, "id") or ""): call for call in kept if _tool_field(call, "id")}
if isinstance(raw_calls, list) and raw_calls:
synced: list[Any] = []
for item in raw_calls:
if not isinstance(item, dict):
continue
item_id = str(item.get("id") or "")
if item_id not in kept_ids:
continue
replacement = rewritten_by_id.get(item_id)
if replacement is not None and _tool_name(replacement) == TOOL_NAME:
function = dict(item.get("function") or {})
function["name"] = TOOL_NAME
function["arguments"] = json.dumps(
_normalize_args(_tool_field(replacement, "args", {})),
ensure_ascii=False,
)
synced.append({**item, "function": function})
else:
synced.append(item)
if synced:
additional_kwargs["tool_calls"] = synced
else:
additional_kwargs.pop("tool_calls", None)
additional_kwargs.pop("function_call", None)
elif not kept:
additional_kwargs.pop("tool_calls", None)
additional_kwargs.pop("function_call", None)
update["additional_kwargs"] = additional_kwargs
if not kept:
response_metadata = deepcopy(getattr(last, "response_metadata", {}) or {})
if response_metadata.get("finish_reason") == "tool_calls":
response_metadata["finish_reason"] = "stop"
update["response_metadata"] = response_metadata
return update
def rewrite_handwritten_report_calls(
last: AIMessage,
*,
topic: str,
focus: str = "",
pipeline_already_done: bool = False,
) -> AIMessage | None:
"""Rewrite or drop report deliverable tool calls.
Before the pipeline has succeeded: rewrite the first hand-written report
write to ``deep_research_report`` (carrying ``topic`` + ``focus``) and drop
sibling presents.
After it has succeeded: drop every pipeline / hand-written / present /
report-reread call so the model cannot start another writing loop.
"""
tool_calls = list(getattr(last, "tool_calls", None) or [])
if not tool_calls:
return None
if pipeline_already_done:
kept = [call for call in tool_calls if not is_post_success_loop_call(call)]
if len(kept) == len(tool_calls):
return None
update = _sync_raw_tool_calls(last, kept)
if not kept:
update["content"] = ""
return last.model_copy(update=update)
has_pipeline = any(is_pipeline_call(call) for call in tool_calls)
rewritten: list[Any] = []
changed = False
redirected = has_pipeline
for call in tool_calls:
if is_pipeline_call(call):
rewritten.append(call)
continue
if is_handwritten_report_call(call):
changed = True
if redirected:
continue
rewritten.append(_as_report_call(call, topic, focus))
redirected = True
continue
if is_report_present_call(call) and (has_pipeline or redirected or any(is_handwritten_report_call(item) for item in tool_calls)):
changed = True
continue
rewritten.append(call)
if not changed:
return None
return last.model_copy(update=_sync_raw_tool_calls(last, rewritten))
def _messages_from_tool_request(request: ToolCallRequest) -> list[Any]:
state = getattr(request, "state", None) or {}
if isinstance(state, dict):
return list(state.get("messages") or [])
messages = getattr(state, "messages", None)
return list(messages or [])
class WritingModeReportMiddleware(AgentMiddleware[AgentState]):
"""The first-report run's report only comes from ``deep_research_report``.
``wrap_model_call`` 把 write_file / str_replace / bash 一并从模型绑定中
剥离(本中间件只在首报轮挂载)——after_model 的改写只能在整个模型响应
结束后触发,任何留在绑定里的写入口都会被弱模型用来先把全文起草进参数
(write_file 内容或 bash heredoc 命令),流式几十秒前端不可见后才被拦
截。bash 是唯一能写文件的执行类工具,剥离后模型没有任何可发起文件写
入的工具,交付只能直接调管线;幻觉出的调用仍由 after_model 改写/丢弃、
wrap_tool_call 拒绝兜底,管线成功后再写会被丢弃并保证一段收尾总结。
"""
state_schema = AgentState
@staticmethod
def _binding_tool_name(tool: Any) -> str:
if isinstance(tool, str):
return tool
return str(getattr(tool, "name", "") or "")
def _strip_handwrite_tools(self, request: ModelRequest) -> ModelRequest:
"""Remove ``write_file`` / ``str_replace`` / ``bash`` from the model binding.
``after_model`` 的改写只能在模型整个响应结束后触发,所以任何留在绑定里
的写入口都会被弱模型用来先把全文起草进参数(write_file 参数、bash
heredoc 命令),流式输出几十秒且前端不可见后才被拦截。bash 是唯一能
写文件的执行类工具,一并剥离后首报轮**不存在可发起文件写入的工具**,
交付只能直接调 ``deep_research_report``。ToolNode 仍持有全部工具;
模型幻觉出的调用由 after_model 改写/丢弃、wrap_tool_call 拒绝兜底。
"""
tools = list(getattr(request, "tools", None) or [])
if not tools:
return request
excluded = _WRITE_TOOLS | {_BASH_TOOL}
removed = sorted({self._binding_tool_name(tool) for tool in tools if self._binding_tool_name(tool) in excluded})
if not removed:
return request
logger.info("Writing-mode first-report run: removed hand-write tools %s from model binding", removed)
return request.override(tools=[tool for tool in tools if self._binding_tool_name(tool) not in excluded])
def _redirect_or_stop(self, state: AgentState) -> dict[str, Any] | None:
messages = list(state.get("messages") or [])
if not messages:
return None
last = messages[-1]
if not isinstance(last, AIMessage):
return None
already_done = pipeline_already_succeeded(messages)
topic = extract_report_topic(messages)
patched = rewrite_handwritten_report_calls(
last,
topic=topic,
focus=extract_report_focus(messages, topic),
pipeline_already_done=already_done,
)
if patched is None:
return None
result: dict[str, Any] = {"messages": [patched]}
if already_done:
if not (patched.tool_calls or []):
if _already_nudged_summary(messages):
logger.info("Writing-mode pipeline already succeeded; summary nudge ignored, ending turn")
# 模型无视总结提示仍要继续读写:丢弃其调用后补一段兜底
# 总结再结束,保证用户总能看到收尾消息而不是静默结束。
if not _message_text(patched):
patched = patched.model_copy(update={"content": _FALLBACK_SUMMARY})
result["messages"] = [patched]
result["jump_to"] = "end"
return result
logger.info("Writing-mode pipeline already succeeded; dropping deliverable tools and nudging summary")
result["messages"] = [patched, _summary_nudge_message()]
result["jump_to"] = "model"
else:
redirected_names = sorted({_tool_name(call) for call in getattr(last, "tool_calls", None) or [] if is_handwritten_report_call(call)})
if redirected_names:
logger.info(
"Writing-mode: redirected hand-written report call(s) %s to %s",
redirected_names,
TOOL_NAME,
)
return result
def _reject_loop_tool(self, request: ToolCallRequest) -> ToolMessage | None:
tool_call = getattr(request, "tool_call", None) or {}
already_done = pipeline_already_succeeded(_messages_from_tool_request(request))
if already_done and is_post_success_loop_call(tool_call):
return ToolMessage(
content=f"Error: {_REJECT_AFTER_SUCCESS}",
tool_call_id=str(_tool_field(tool_call, "id") or ""),
name=str(_tool_name(tool_call) or TOOL_NAME),
)
if not already_done and is_handwritten_report_call(tool_call):
return ToolMessage(
content=f"Error: {_REJECT_HANDWRITTEN}",
tool_call_id=str(_tool_field(tool_call, "id") or ""),
name=str(_tool_name(tool_call) or "write_file"),
)
return None
@hook_config(can_jump_to=["end", "model"])
@override
def after_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
return self._redirect_or_stop(state)
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
return handler(self._strip_handwrite_tools(request))
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
return await handler(self._strip_handwrite_tools(request))
@hook_config(can_jump_to=["end", "model"])
@override
async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
return self._redirect_or_stop(state)
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
rejected = self._reject_loop_tool(request)
if rejected is not None:
return rejected
return handler(request)
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command:
rejected = self._reject_loop_tool(request)
if rejected is not None:
return rejected
return await handler(request)
__all__ = [
"TOOL_NAME",
"WritingModeReportMiddleware",
"extract_report_focus",
"extract_report_topic",
"is_handwritten_report_call",
"is_post_success_loop_call",
"is_report_present_call",
"is_report_reread_call",
"pipeline_already_succeeded",
"rewrite_handwritten_report_calls",
]
@@ -0,0 +1,80 @@
"""写作配置 Q&A 的「轮数上限」中间件。
意图阶段允许与用户来回澄清确认,但**最多 N 轮后必须出结果**:到上限时,在模型请求里
注入强制指令 + 用 ``tool_choice`` 锁定 ``setup_writing``,逼模型立刻提交配置卡,不再提问。
「一轮」= 一条用户消息(HumanMessage)。达到 ``max_rounds`` 条用户消息时强制提交。
"""
from __future__ import annotations
from collections.abc import Awaitable, Callable
from typing import override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
from langchain_core.messages import HumanMessage
class WritingSetupRoundCapMiddleware(AgentMiddleware[AgentState]):
"""达到澄清轮数上限时,强制模型调用 ``setup_writing`` 提交。
软约束(注入隐藏 HumanMessage)+ 硬约束(``tool_choice`` 锁定工具)双保险:即使个别模型
无视提示,``tool_choice`` 也会逼它产出一次 ``setup_writing`` 调用。
"""
def __init__(
self,
max_rounds: int = 3,
tool_name: str = "setup_writing",
force_instruction: str | None = None,
) -> None:
super().__init__()
self._max_rounds = max(1, max_rounds)
self._tool_name = tool_name
self._force_instruction = force_instruction
def _should_force(self, messages: list) -> bool:
human_count = sum(1 for m in messages if isinstance(m, HumanMessage))
return human_count >= self._max_rounds
def _reminder(self) -> HumanMessage:
content = self._force_instruction or (
f"【系统强制】意图澄清已达 {self._max_rounds} 轮上限。"
"现在必须立即调用 setup_writing 提交写作配置,禁止再向用户提任何问题。"
"缺失或不确定的字段一律用合理默认值:"
"word_count_target 默认 800、target_audience 默认「普通读者」、"
"writing_mode 默认 loose、material_source 默认 knowledge_base、"
"article_type 不确定就留空。"
)
return HumanMessage(
content=content,
additional_kwargs={"hide_from_ui": True, "lc_source": "writing_setup_round_cap"},
)
def _patch(self, request: ModelRequest) -> ModelRequest:
return request.override(
messages=[*request.messages, self._reminder()],
tool_choice=self._tool_name,
)
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
if self._should_force(request.messages):
request = self._patch(request)
return handler(request)
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
if self._should_force(request.messages):
request = self._patch(request)
return await handler(request)