[security] fix(uploads): require explicit opt-in for host-side document conversion (#2332)

* fix: disable host-side upload conversion by default

* fix: address PR review comments on upload conversion gate

.github/workflows/e2e-tests.yml

@@ -0,0 +1,63 @@
+name: E2E Tests
+
+on:
+  push:
+    branches: [ 'main' ]
+    paths:
+      - 'frontend/**'
+      - '.github/workflows/e2e-tests.yml'
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - 'frontend/**'
+      - '.github/workflows/e2e-tests.yml'
+
+concurrency:
+  group: e2e-tests-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  e2e-tests:
+    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Use pinned pnpm version
+        run: corepack prepare pnpm@10.26.2 --activate
+
+      - name: Install frontend dependencies
+        working-directory: frontend
+        run: pnpm install --frozen-lockfile
+
+      - name: Install Playwright Chromium
+        working-directory: frontend
+        run: npx playwright install chromium --with-deps
+
+      - name: Run E2E tests
+        working-directory: frontend
+        run: pnpm exec playwright test
+        env:
+          SKIP_ENV_VALIDATION: '1'
+
+      - name: Upload Playwright report
+        uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}
+        with:
+          name: playwright-report
+          path: frontend/playwright-report/
+          retention-days: 7

.github/workflows/frontend-unit-tests.yml

@@ -0,0 +1,43 @@
+name: Frontend Unit Tests
+
+on:
+  push:
+    branches: [ 'main' ]
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+concurrency:
+  group: frontend-unit-tests-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  frontend-unit-tests:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Use pinned pnpm version
+        run: corepack prepare pnpm@10.26.2 --activate
+
+      - name: Install frontend dependencies
+        working-directory: frontend
+        run: pnpm install --frozen-lockfile
+
+      - name: Run unit tests of frontend
+        working-directory: frontend
+        run: make test

.gitignore

@@ -55,5 +55,7 @@ web/
 backend/Dockerfile.langgraph
 config.yaml.bak
 .playwright-mcp
+/frontend/test-results/
+/frontend/playwright-report/
 .gstack/
 .worktrees

CONTRIBUTING.md

@@ -298,19 +298,24 @@ Nginx (port 2026) ← Unified entry point
 ```bash
 # Backend tests
 cd backend
-uv run pytest
+make test
 
-# Frontend checks
+# Frontend unit tests
 cd frontend
-pnpm check
+make test
+
+# Frontend E2E tests (requires Chromium; builds and auto-starts the Next.js production server)
+cd frontend
+make test-e2e
 ```
 
 ### PR Regression Checks
 
-Every pull request runs the backend regression workflow at [.github/workflows/backend-unit-tests.yml](.github/workflows/backend-unit-tests.yml), including:
+Every pull request triggers the following CI workflows:
 
-- `tests/test_provisioner_kubeconfig.py`
-- `tests/test_docker_sandbox_mode_detection.py`
+- **Backend unit tests** — [.github/workflows/backend-unit-tests.yml](.github/workflows/backend-unit-tests.yml)
+- **Frontend unit tests** — [.github/workflows/frontend-unit-tests.yml](.github/workflows/frontend-unit-tests.yml)
+- **Frontend E2E tests** — [.github/workflows/e2e-tests.yml](.github/workflows/e2e-tests.yml) (triggered only when `frontend/` files change)
 
 ## Code Style
 

README.md

@@ -658,6 +658,8 @@ This is the difference between a chatbot with tool access and an agent with an a
 
 **Summarization**: Within a session, DeerFlow manages context aggressively — summarizing completed sub-tasks, offloading intermediate results to the filesystem, compressing what's no longer immediately relevant. This lets it stay sharp across long, multi-step tasks without blowing the context window.
 
+**Strict Tool-Call Recovery**: When a provider or middleware interrupts a tool-call loop, DeerFlow now strips provider-level raw tool-call metadata on forced-stop assistant messages and injects placeholder tool results for dangling calls before the next model invocation. This keeps OpenAI-compatible reasoning models that strictly validate `tool_call_id` sequences from failing with malformed history errors.
+
 ### Long-Term Memory
 
 Most agents forget everything the moment a conversation ends. DeerFlow remembers.

backend/CLAUDE.md

@@ -156,20 +156,26 @@ from deerflow.config import get_app_config
 
 ### Middleware Chain
 
-Middlewares execute in strict order in `packages/harness/deerflow/agents/lead_agent/agent.py`:
+Lead-agent middlewares are assembled in strict append order across `packages/harness/deerflow/agents/middlewares/tool_error_handling_middleware.py` (`build_lead_runtime_middlewares`) and `packages/harness/deerflow/agents/lead_agent/agent.py` (`_build_middlewares`):
 
 1. **ThreadDataMiddleware** - Creates per-thread directories (`backend/.deer-flow/threads/{thread_id}/user-data/{workspace,uploads,outputs}`); Web UI thread deletion now follows LangGraph thread removal with Gateway cleanup of the local `.deer-flow/threads/{thread_id}` directory
 2. **UploadsMiddleware** - Tracks and injects newly uploaded files into conversation
 3. **SandboxMiddleware** - Acquires sandbox, stores `sandbox_id` in state
-4. **DanglingToolCallMiddleware** - Injects placeholder ToolMessages for AIMessage tool_calls that lack responses (e.g., due to user interruption)
-5. **GuardrailMiddleware** - Pre-tool-call authorization via pluggable `GuardrailProvider` protocol (optional, if `guardrails.enabled` in config). Evaluates each tool call and returns error ToolMessage on deny. Three provider options: built-in `AllowlistProvider` (zero deps), OAP policy providers (e.g. `aport-agent-guardrails`), or custom providers. See [docs/GUARDRAILS.md](docs/GUARDRAILS.md) for setup, usage, and how to implement a provider.
-6. **SummarizationMiddleware** - Context reduction when approaching token limits (optional, if enabled)
-7. **TodoListMiddleware** - Task tracking with `write_todos` tool (optional, if plan_mode)
-8. **TitleMiddleware** - Auto-generates thread title after first complete exchange and normalizes structured message content before prompting the title model
-9. **MemoryMiddleware** - Queues conversations for async memory update (filters to user + final AI responses)
-10. **ViewImageMiddleware** - Injects base64 image data before LLM call (conditional on vision support)
-11. **SubagentLimitMiddleware** - Truncates excess `task` tool calls from model response to enforce `MAX_CONCURRENT_SUBAGENTS` limit (optional, if subagent_enabled)
-12. **ClarificationMiddleware** - Intercepts `ask_clarification` tool calls, interrupts via `Command(goto=END)` (must be last)
+4. **DanglingToolCallMiddleware** - Injects placeholder ToolMessages for AIMessage tool_calls that lack responses (e.g., due to user interruption), including raw provider tool-call payloads preserved only in `additional_kwargs["tool_calls"]`
+5. **LLMErrorHandlingMiddleware** - Normalizes provider/model invocation failures into recoverable assistant-facing errors before later middleware/tool stages run
+6. **GuardrailMiddleware** - Pre-tool-call authorization via pluggable `GuardrailProvider` protocol (optional, if `guardrails.enabled` in config). Evaluates each tool call and returns error ToolMessage on deny. Three provider options: built-in `AllowlistProvider` (zero deps), OAP policy providers (e.g. `aport-agent-guardrails`), or custom providers. See [docs/GUARDRAILS.md](docs/GUARDRAILS.md) for setup, usage, and how to implement a provider.
+7. **SandboxAuditMiddleware** - Audits sandboxed shell/file operations for security logging before tool execution continues
+8. **ToolErrorHandlingMiddleware** - Converts tool exceptions into error `ToolMessage`s so the run can continue instead of aborting
+9. **SummarizationMiddleware** - Context reduction when approaching token limits (optional, if enabled)
+10. **TodoListMiddleware** - Task tracking with `write_todos` tool (optional, if plan_mode)
+11. **TokenUsageMiddleware** - Records token usage metrics when token tracking is enabled (optional)
+12. **TitleMiddleware** - Auto-generates thread title after first complete exchange and normalizes structured message content before prompting the title model
+13. **MemoryMiddleware** - Queues conversations for async memory update (filters to user + final AI responses)
+14. **ViewImageMiddleware** - Injects base64 image data before LLM call (conditional on vision support)
+15. **DeferredToolFilterMiddleware** - Hides deferred tool schemas from the bound model until tool search is enabled (optional)
+16. **SubagentLimitMiddleware** - Truncates excess `task` tool calls from model response to enforce `MAX_CONCURRENT_SUBAGENTS` limit (optional, if `subagent_enabled`)
+17. **LoopDetectionMiddleware** - Detects repeated tool-call loops; hard-stop responses clear both structured `tool_calls` and raw provider tool-call metadata before forcing a final text answer
+18. **ClarificationMiddleware** - Intercepts `ask_clarification` tool calls, interrupts via `Command(goto=END)` (must be last)
 
 ### Configuration System
 

backend/app/gateway/routers/agents.py

@@ -8,6 +8,7 @@ import yaml
 from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel, Field
 
+from deerflow.config.agents_api_config import get_agents_api_config
 from deerflow.config.agents_config import AgentConfig, list_custom_agents, load_agent_config, load_agent_soul
 from deerflow.config.paths import get_paths
 
@@ -73,6 +74,15 @@ def _normalize_agent_name(name: str) -> str:
     return name.lower()
 
 
+def _require_agents_api_enabled() -> None:
+    """Reject access unless the custom-agent management API is explicitly enabled."""
+    if not get_agents_api_config().enabled:
+        raise HTTPException(
+            status_code=403,
+            detail=("Custom-agent management API is disabled. Set agents_api.enabled=true to expose agent and user-profile routes over HTTP."),
+        )
+
+
 def _agent_config_to_response(agent_cfg: AgentConfig, include_soul: bool = False) -> AgentResponse:
     """Convert AgentConfig to AgentResponse."""
     soul: str | None = None
@@ -100,6 +110,8 @@ async def list_agents() -> AgentsListResponse:
     Returns:
         List of all custom agents with their metadata and soul content.
     """
+    _require_agents_api_enabled()
+
     try:
         agents = list_custom_agents()
         return AgentsListResponse(agents=[_agent_config_to_response(a, include_soul=True) for a in agents])
@@ -125,6 +137,7 @@ async def check_agent_name(name: str) -> dict:
     Raises:
         HTTPException: 422 if the name is invalid.
     """
+    _require_agents_api_enabled()
     _validate_agent_name(name)
     normalized = _normalize_agent_name(name)
     available = not get_paths().agent_dir(normalized).exists()
@@ -149,6 +162,7 @@ async def get_agent(name: str) -> AgentResponse:
     Raises:
         HTTPException: 404 if agent not found.
     """
+    _require_agents_api_enabled()
     _validate_agent_name(name)
     name = _normalize_agent_name(name)
 
@@ -181,6 +195,7 @@ async def create_agent_endpoint(request: AgentCreateRequest) -> AgentResponse:
     Raises:
         HTTPException: 409 if agent already exists, 422 if name is invalid.
     """
+    _require_agents_api_enabled()
     _validate_agent_name(request.name)
     normalized_name = _normalize_agent_name(request.name)
 
@@ -243,6 +258,7 @@ async def update_agent(name: str, request: AgentUpdateRequest) -> AgentResponse:
     Raises:
         HTTPException: 404 if agent not found.
     """
+    _require_agents_api_enabled()
     _validate_agent_name(name)
     name = _normalize_agent_name(name)
 
@@ -315,6 +331,8 @@ async def get_user_profile() -> UserProfileResponse:
     Returns:
         UserProfileResponse with content=None if USER.md does not exist yet.
     """
+    _require_agents_api_enabled()
+
     try:
         user_md_path = get_paths().user_md_file
         if not user_md_path.exists():
@@ -341,6 +359,8 @@ async def update_user_profile(request: UserProfileUpdateRequest) -> UserProfileR
     Returns:
         UserProfileResponse with the saved content.
     """
+    _require_agents_api_enabled()
+
     try:
         paths = get_paths()
         paths.base_dir.mkdir(parents=True, exist_ok=True)
@@ -367,6 +387,7 @@ async def delete_agent(name: str) -> None:
     Raises:
         HTTPException: 404 if agent not found.
     """
+    _require_agents_api_enabled()
     _validate_agent_name(name)
     name = _normalize_agent_name(name)
 

backend/app/gateway/routers/models.py

@@ -17,10 +17,17 @@ class ModelResponse(BaseModel):
     supports_reasoning_effort: bool = Field(default=False, description="Whether model supports reasoning effort")
 
 
+class TokenUsageResponse(BaseModel):
+    """Token usage display configuration."""
+
+    enabled: bool = Field(default=False, description="Whether token usage display is enabled")
+
+
 class ModelsListResponse(BaseModel):
     """Response model for listing all models."""
 
     models: list[ModelResponse]
+    token_usage: TokenUsageResponse
 
 
 @router.get(
@@ -36,7 +43,7 @@ async def list_models() -> ModelsListResponse:
     excluding sensitive fields like API keys and internal configuration.
 
     Returns:
-        A list of all configured models with their metadata.
+        A list of all configured models with their metadata and token usage display settings.
 
     Example Response:
         ```json
@@ -44,17 +51,24 @@ async def list_models() -> ModelsListResponse:
             "models": [
                 {
                     "name": "gpt-4",
+                    "model": "gpt-4",
                     "display_name": "GPT-4",
                     "description": "OpenAI GPT-4 model",
-                    "supports_thinking": false
+                    "supports_thinking": false,
+                    "supports_reasoning_effort": false
                 },
                 {
                     "name": "claude-3-opus",
+                    "model": "claude-3-opus",
                     "display_name": "Claude 3 Opus",
                     "description": "Anthropic Claude 3 Opus model",
-                    "supports_thinking": true
+                    "supports_thinking": true,
+                    "supports_reasoning_effort": false
                 }
-            ]
+            ],
+            "token_usage": {
+                "enabled": true
+            }
         }
         ```
     """
@@ -70,7 +84,10 @@ async def list_models() -> ModelsListResponse:
         )
         for model in config.models
     ]
-    return ModelsListResponse(models=models)
+    return ModelsListResponse(
+        models=models,
+        token_usage=TokenUsageResponse(enabled=config.token_usage.enabled),
+    )
 
 
 @router.get(

backend/app/gateway/routers/skills.py

@@ -1,3 +1,4 @@
+import errno
 import json
 import logging
 import shutil
@@ -201,18 +202,23 @@ async def delete_custom_skill(skill_name: str) -> dict[str, bool]:
         ensure_custom_skill_is_editable(skill_name)
         skill_dir = get_custom_skill_dir(skill_name)
         prev_content = read_custom_skill_content(skill_name)
-        append_history(
-            skill_name,
-            {
-                "action": "human_delete",
-                "author": "human",
-                "thread_id": None,
-                "file_path": "SKILL.md",
-                "prev_content": prev_content,
-                "new_content": None,
-                "scanner": {"decision": "allow", "reason": "Deletion requested."},
-            },
-        )
+        try:
+            append_history(
+                skill_name,
+                {
+                    "action": "human_delete",
+                    "author": "human",
+                    "thread_id": None,
+                    "file_path": "SKILL.md",
+                    "prev_content": prev_content,
+                    "new_content": None,
+                    "scanner": {"decision": "allow", "reason": "Deletion requested."},
+                },
+            )
+        except OSError as e:
+            if not isinstance(e, PermissionError) and e.errno not in {errno.EACCES, errno.EPERM, errno.EROFS}:
+                raise
+            logger.warning("Skipping delete history write for custom skill %s due to readonly/permission failure; continuing with skill directory removal: %s", skill_name, e)
         shutil.rmtree(skill_dir)
         await refresh_skills_system_prompt_cache_async()
         return {"success": True}

backend/app/gateway/routers/uploads.py

@@ -7,8 +7,9 @@ import stat
 from fastapi import APIRouter, File, HTTPException, UploadFile
 from pydantic import BaseModel
 
+from deerflow.config.app_config import get_app_config
 from deerflow.config.paths import get_paths
-from deerflow.sandbox.sandbox_provider import get_sandbox_provider
+from deerflow.sandbox.sandbox_provider import SandboxProvider, get_sandbox_provider
 from deerflow.uploads.manager import (
     PathTraversalError,
     delete_file_safe,
@@ -53,6 +54,34 @@ def _make_file_sandbox_writable(file_path: os.PathLike[str] | str) -> None:
     os.chmod(file_path, writable_mode, **chmod_kwargs)
 
 
+def _uses_thread_data_mounts(sandbox_provider: SandboxProvider) -> bool:
+    return bool(getattr(sandbox_provider, "uses_thread_data_mounts", False))
+
+
+def _get_uploads_config_value(key: str, default: object) -> object:
+    """Read a value from the uploads config, supporting dict and attribute access."""
+    cfg = get_app_config()
+    uploads_cfg = getattr(cfg, "uploads", None)
+    if isinstance(uploads_cfg, dict):
+        return uploads_cfg.get(key, default)
+    return getattr(uploads_cfg, key, default)
+
+
+def _auto_convert_documents_enabled() -> bool:
+    """Return whether automatic host-side document conversion is enabled.
+
+    The secure default is disabled unless an operator explicitly opts in via
+    uploads.auto_convert_documents in config.yaml.
+    """
+    try:
+        raw = _get_uploads_config_value("auto_convert_documents", False)
+        if isinstance(raw, str):
+            return raw.strip().lower() in {"1", "true", "yes", "on"}
+        return bool(raw)
+    except Exception:
+        return False
+
+
 @router.post("", response_model=UploadResponse)
 async def upload_files(
     thread_id: str,
@@ -70,8 +99,12 @@ async def upload_files(
     uploaded_files = []
 
     sandbox_provider = get_sandbox_provider()
-    sandbox_id = sandbox_provider.acquire(thread_id)
-    sandbox = sandbox_provider.get(sandbox_id)
+    sync_to_sandbox = not _uses_thread_data_mounts(sandbox_provider)
+    sandbox = None
+    if sync_to_sandbox:
+        sandbox_id = sandbox_provider.acquire(thread_id)
+        sandbox = sandbox_provider.get(sandbox_id)
+    auto_convert_documents = _auto_convert_documents_enabled()
 
     for file in files:
         if not file.filename:
@@ -90,7 +123,7 @@ async def upload_files(
 
             virtual_path = upload_virtual_path(safe_filename)
 
-            if sandbox_id != "local":
+            if sync_to_sandbox and sandbox is not None:
                 _make_file_sandbox_writable(file_path)
                 sandbox.update_file(virtual_path, content)
 
@@ -105,12 +138,12 @@ async def upload_files(
             logger.info(f"Saved file: {safe_filename} ({len(content)} bytes) to {file_info['path']}")
 
             file_ext = file_path.suffix.lower()
-            if file_ext in CONVERTIBLE_EXTENSIONS:
+            if auto_convert_documents and file_ext in CONVERTIBLE_EXTENSIONS:
                 md_path = await convert_file_to_markdown(file_path)
                 if md_path:
                     md_virtual_path = upload_virtual_path(md_path.name)
 
-                    if sandbox_id != "local":
+                    if sync_to_sandbox and sandbox is not None:
                         _make_file_sandbox_writable(md_path)
                         sandbox.update_file(md_virtual_path, md_path.read_bytes())
 

backend/app/gateway/services.py

@@ -298,6 +298,8 @@ async def start_run(
             "is_plan_mode",
             "subagent_enabled",
             "max_concurrent_subagents",
+            "agent_name",
+            "is_bootstrap",
         }
         configurable = config.setdefault("configurable", {})
         for key in _CONTEXT_CONFIGURABLE_KEYS:

backend/docs/FILE_UPLOAD.md

@@ -2,12 +2,12 @@
 
 ## 概述
 
-DeerFlow 后端提供了完整的文件上传功能，支持多文件上传，并自动将 Office 文档和 PDF 转换为 Markdown 格式。
+DeerFlow 后端提供了完整的文件上传功能，支持多文件上传，并可选地将 Office 文档和 PDF 转换为 Markdown 格式。
 
 ## 功能特性
 
 - ✅ 支持多文件同时上传
-- ✅ 自动转换文档为 Markdown（PDF、PPT、Excel、Word）
+- ✅ 可选地转换文档为 Markdown（PDF、PPT、Excel、Word）
 - ✅ 文件存储在线程隔离的目录中
 - ✅ Agent 自动感知已上传的文件
 - ✅ 支持文件列表查询和删除
@@ -86,7 +86,7 @@ DELETE /api/threads/{thread_id}/uploads/{filename}
 
 ## 支持的文档格式
 
-以下格式会自动转换为 Markdown：
+以下格式在显式启用 `uploads.auto_convert_documents: true` 时会自动转换为 Markdown：
 - PDF (`.pdf`)
 - PowerPoint (`.ppt`, `.pptx`)
 - Excel (`.xls`, `.xlsx`)
@@ -94,6 +94,8 @@ DELETE /api/threads/{thread_id}/uploads/{filename}
 
 转换后的 Markdown 文件会保存在同一目录下，文件名为原文件名 + `.md` 扩展名。
 
+默认情况下，自动转换是关闭的，以避免在网关主机上对不受信任的 Office/PDF 上传执行解析。只有在受信任部署中明确接受此风险时，才应将 `uploads.auto_convert_documents` 设置为 `true`。
+
 ## Agent 集成
 
 ### 自动文件列举
@@ -207,6 +209,7 @@ backend/.deer-flow/threads/
 - 最大文件大小：100MB（可在 nginx.conf 中配置 `client_max_body_size`）
 - 文件名安全性：系统会自动验证文件路径，防止目录遍历攻击
 - 线程隔离：每个线程的上传文件相互隔离，无法跨线程访问
+- 自动文档转换默认关闭；如需启用，需在 `config.yaml` 中显式设置 `uploads.auto_convert_documents: true`
 
 ## 技术实现
 

backend/docs/TODO.md

@@ -24,7 +24,7 @@
 - [ ] Optimize async concurrency in agent hot path (IM channels multi-task scenario)
 - [ ] Replace `subprocess.run()` with `asyncio.create_subprocess_shell()` in `packages/harness/deerflow/sandbox/local/local_sandbox.py`
   - Replace sync `requests` with `httpx.AsyncClient` in community tools (tavily, jina_ai, firecrawl, infoquest, image_search)
-  - Replace sync `model.invoke()` with async `model.ainvoke()` in title_middleware and memory updater
+  - [x] Replace sync `model.invoke()` with async `model.ainvoke()` in title_middleware and memory updater
   - Consider `asyncio.to_thread()` wrapper for remaining blocking file I/O
   - For production: use `langgraph up` (multi-worker) instead of `langgraph dev` (single-worker)
 

backend/packages/harness/deerflow/agents/checkpointer/provider.py

@@ -27,7 +27,7 @@ from langgraph.types import Checkpointer
 
 from deerflow.config.app_config import get_app_config
 from deerflow.config.checkpointer_config import CheckpointerConfig
-from deerflow.runtime.store._sqlite_utils import resolve_sqlite_conn_str
+from deerflow.runtime.store._sqlite_utils import ensure_sqlite_parent_dir, resolve_sqlite_conn_str
 
 logger = logging.getLogger(__name__)
 
@@ -67,6 +67,7 @@ def _sync_checkpointer_cm(config: CheckpointerConfig) -> Iterator[Checkpointer]:
             raise ImportError(SQLITE_INSTALL) from exc
 
         conn_str = resolve_sqlite_conn_str(config.connection_string or "store.db")
+        ensure_sqlite_parent_dir(conn_str)
         with SqliteSaver.from_conn_string(conn_str) as saver:
             saver.setup()
             logger.info("Checkpointer: using SqliteSaver (%s)", conn_str)

backend/packages/harness/deerflow/agents/lead_agent/agent.py

@@ -1,22 +1,25 @@
 import logging
 
 from langchain.agents import create_agent
-from langchain.agents.middleware import AgentMiddleware, SummarizationMiddleware
+from langchain.agents.middleware import AgentMiddleware
 from langchain_core.runnables import RunnableConfig
 
 from deerflow.agents.lead_agent.prompt import apply_prompt_template
+from deerflow.agents.memory.summarization_hook import memory_flush_hook
 from deerflow.agents.middlewares.clarification_middleware import ClarificationMiddleware
 from deerflow.agents.middlewares.loop_detection_middleware import LoopDetectionMiddleware
 from deerflow.agents.middlewares.memory_middleware import MemoryMiddleware
 from deerflow.agents.middlewares.subagent_limit_middleware import SubagentLimitMiddleware
+from deerflow.agents.middlewares.summarization_middleware import BeforeSummarizationHook, DeerFlowSummarizationMiddleware
 from deerflow.agents.middlewares.title_middleware import TitleMiddleware
 from deerflow.agents.middlewares.todo_middleware import TodoMiddleware
 from deerflow.agents.middlewares.token_usage_middleware import TokenUsageMiddleware
 from deerflow.agents.middlewares.tool_error_handling_middleware import build_lead_runtime_middlewares
 from deerflow.agents.middlewares.view_image_middleware import ViewImageMiddleware
 from deerflow.agents.thread_state import ThreadState
-from deerflow.config.agents_config import load_agent_config
+from deerflow.config.agents_config import load_agent_config, validate_agent_name
 from deerflow.config.app_config import get_app_config
+from deerflow.config.memory_config import get_memory_config
 from deerflow.config.summarization_config import get_summarization_config
 from deerflow.models import create_chat_model
 
@@ -38,7 +41,7 @@ def _resolve_model_name(requested_model_name: str | None = None) -> str:
     return default_model_name
 
 
-def _create_summarization_middleware() -> SummarizationMiddleware | None:
+def _create_summarization_middleware() -> DeerFlowSummarizationMiddleware | None:
     """Create and configure the summarization middleware from config."""
     config = get_summarization_config()
 
@@ -77,7 +80,11 @@ def _create_summarization_middleware() -> SummarizationMiddleware | None:
     if config.summary_prompt is not None:
         kwargs["summary_prompt"] = config.summary_prompt
 
-    return SummarizationMiddleware(**kwargs)
+    hooks: list[BeforeSummarizationHook] = []
+    if get_memory_config().enabled:
+        hooks.append(memory_flush_hook)
+
+    return DeerFlowSummarizationMiddleware(**kwargs, before_summarization=hooks)
 
 
 def _create_todo_list_middleware(is_plan_mode: bool) -> TodoMiddleware | None:
@@ -284,7 +291,7 @@ def make_lead_agent(config: RunnableConfig):
     subagent_enabled = cfg.get("subagent_enabled", False)
     max_concurrent_subagents = cfg.get("max_concurrent_subagents", 3)
     is_bootstrap = cfg.get("is_bootstrap", False)
-    agent_name = cfg.get("agent_name")
+    agent_name = validate_agent_name(cfg.get("agent_name"))
 
     agent_config = load_agent_config(agent_name) if not is_bootstrap else None
     # Custom agent model from agent config (if any), or None to let _resolve_model_name pick the default
@@ -325,6 +332,7 @@ def make_lead_agent(config: RunnableConfig):
             "reasoning_effort": reasoning_effort,
             "is_plan_mode": is_plan_mode,
             "subagent_enabled": subagent_enabled,
+            "tool_groups": agent_config.tool_groups if agent_config else None,
         }
     )
 

backend/packages/harness/deerflow/agents/memory/message_processing.py

@@ -0,0 +1,109 @@
+"""Shared helpers for turning conversations into memory update inputs."""
+
+from __future__ import annotations
+
+import re
+from copy import copy
+from typing import Any
+
+_UPLOAD_BLOCK_RE = re.compile(r"<uploaded_files>[\s\S]*?</uploaded_files>\n*", re.IGNORECASE)
+_CORRECTION_PATTERNS = (
+    re.compile(r"\bthat(?:'s| is) (?:wrong|incorrect)\b", re.IGNORECASE),
+    re.compile(r"\byou misunderstood\b", re.IGNORECASE),
+    re.compile(r"\btry again\b", re.IGNORECASE),
+    re.compile(r"\bredo\b", re.IGNORECASE),
+    re.compile(r"不对"),
+    re.compile(r"你理解错了"),
+    re.compile(r"你理解有误"),
+    re.compile(r"重试"),
+    re.compile(r"重新来"),
+    re.compile(r"换一种"),
+    re.compile(r"改用"),
+)
+_REINFORCEMENT_PATTERNS = (
+    re.compile(r"\byes[,.]?\s+(?:exactly|perfect|that(?:'s| is) (?:right|correct|it))\b", re.IGNORECASE),
+    re.compile(r"\bperfect(?:[.!?]|$)", re.IGNORECASE),
+    re.compile(r"\bexactly\s+(?:right|correct)\b", re.IGNORECASE),
+    re.compile(r"\bthat(?:'s| is)\s+(?:exactly\s+)?(?:right|correct|what i (?:wanted|needed|meant))\b", re.IGNORECASE),
+    re.compile(r"\bkeep\s+(?:doing\s+)?that\b", re.IGNORECASE),
+    re.compile(r"\bjust\s+(?:like\s+)?(?:that|this)\b", re.IGNORECASE),
+    re.compile(r"\bthis is (?:great|helpful)\b(?:[.!?]|$)", re.IGNORECASE),
+    re.compile(r"\bthis is what i wanted\b(?:[.!?]|$)", re.IGNORECASE),
+    re.compile(r"对[，,]?\s*就是这样(?:[。！？!?.]|$)"),
+    re.compile(r"完全正确(?:[。！？!?.]|$)"),
+    re.compile(r"(?:对[，,]?\s*)?就是这个意思(?:[。！？!?.]|$)"),
+    re.compile(r"正是我想要的(?:[。！？!?.]|$)"),
+    re.compile(r"继续保持(?:[。！？!?.]|$)"),
+)
+
+
+def extract_message_text(message: Any) -> str:
+    """Extract plain text from message content for filtering and signal detection."""
+    content = getattr(message, "content", "")
+    if isinstance(content, list):
+        text_parts: list[str] = []
+        for part in content:
+            if isinstance(part, str):
+                text_parts.append(part)
+            elif isinstance(part, dict):
+                text_val = part.get("text")
+                if isinstance(text_val, str):
+                    text_parts.append(text_val)
+        return " ".join(text_parts)
+    return str(content)
+
+
+def filter_messages_for_memory(messages: list[Any]) -> list[Any]:
+    """Keep only user inputs and final assistant responses for memory updates."""
+    filtered = []
+    skip_next_ai = False
+    for msg in messages:
+        msg_type = getattr(msg, "type", None)
+
+        if msg_type == "human":
+            content_str = extract_message_text(msg)
+            if "<uploaded_files>" in content_str:
+                stripped = _UPLOAD_BLOCK_RE.sub("", content_str).strip()
+                if not stripped:
+                    skip_next_ai = True
+                    continue
+                clean_msg = copy(msg)
+                clean_msg.content = stripped
+                filtered.append(clean_msg)
+                skip_next_ai = False
+            else:
+                filtered.append(msg)
+                skip_next_ai = False
+        elif msg_type == "ai":
+            tool_calls = getattr(msg, "tool_calls", None)
+            if not tool_calls:
+                if skip_next_ai:
+                    skip_next_ai = False
+                    continue
+                filtered.append(msg)
+
+    return filtered
+
+
+def detect_correction(messages: list[Any]) -> bool:
+    """Detect explicit user corrections in recent conversation turns."""
+    recent_user_msgs = [msg for msg in messages[-6:] if getattr(msg, "type", None) == "human"]
+
+    for msg in recent_user_msgs:
+        content = extract_message_text(msg).strip()
+        if content and any(pattern.search(content) for pattern in _CORRECTION_PATTERNS):
+            return True
+
+    return False
+
+
+def detect_reinforcement(messages: list[Any]) -> bool:
+    """Detect explicit positive reinforcement signals in recent conversation turns."""
+    recent_user_msgs = [msg for msg in messages[-6:] if getattr(msg, "type", None) == "human"]
+
+    for msg in recent_user_msgs:
+        content = extract_message_text(msg).strip()
+        if content and any(pattern.search(content) for pattern in _REINFORCEMENT_PATTERNS):
+            return True
+
+    return False

backend/packages/harness/deerflow/agents/memory/queue.py

@@ -61,48 +61,88 @@ class MemoryUpdateQueue:
             return
 
         with self._lock:
-            existing_context = next(
-                (context for context in self._queue if context.thread_id == thread_id),
-                None,
-            )
-            merged_correction_detected = correction_detected or (existing_context.correction_detected if existing_context is not None else False)
-            merged_reinforcement_detected = reinforcement_detected or (existing_context.reinforcement_detected if existing_context is not None else False)
-            context = ConversationContext(
+            self._enqueue_locked(
                 thread_id=thread_id,
                 messages=messages,
                 agent_name=agent_name,
-                correction_detected=merged_correction_detected,
-                reinforcement_detected=merged_reinforcement_detected,
+                correction_detected=correction_detected,
+                reinforcement_detected=reinforcement_detected,
             )
-
-            # Check if this thread already has a pending update
-            # If so, replace it with the newer one
-            self._queue = [c for c in self._queue if c.thread_id != thread_id]
-            self._queue.append(context)
-
-            # Reset or start the debounce timer
             self._reset_timer()
 
         logger.info("Memory update queued for thread %s, queue size: %d", thread_id, len(self._queue))
 
+    def add_nowait(
+        self,
+        thread_id: str,
+        messages: list[Any],
+        agent_name: str | None = None,
+        correction_detected: bool = False,
+        reinforcement_detected: bool = False,
+    ) -> None:
+        """Add a conversation and start processing immediately in the background."""
+        config = get_memory_config()
+        if not config.enabled:
+            return
+
+        with self._lock:
+            self._enqueue_locked(
+                thread_id=thread_id,
+                messages=messages,
+                agent_name=agent_name,
+                correction_detected=correction_detected,
+                reinforcement_detected=reinforcement_detected,
+            )
+            self._schedule_timer(0)
+
+        logger.info("Memory update queued for immediate processing on thread %s, queue size: %d", thread_id, len(self._queue))
+
+    def _enqueue_locked(
+        self,
+        *,
+        thread_id: str,
+        messages: list[Any],
+        agent_name: str | None,
+        correction_detected: bool,
+        reinforcement_detected: bool,
+    ) -> None:
+        existing_context = next(
+            (context for context in self._queue if context.thread_id == thread_id),
+            None,
+        )
+        merged_correction_detected = correction_detected or (existing_context.correction_detected if existing_context is not None else False)
+        merged_reinforcement_detected = reinforcement_detected or (existing_context.reinforcement_detected if existing_context is not None else False)
+        context = ConversationContext(
+            thread_id=thread_id,
+            messages=messages,
+            agent_name=agent_name,
+            correction_detected=merged_correction_detected,
+            reinforcement_detected=merged_reinforcement_detected,
+        )
+
+        self._queue = [c for c in self._queue if c.thread_id != thread_id]
+        self._queue.append(context)
+
     def _reset_timer(self) -> None:
         """Reset the debounce timer."""
         config = get_memory_config()
+        self._schedule_timer(config.debounce_seconds)
 
+        logger.debug("Memory update timer set for %ss", config.debounce_seconds)
+
+    def _schedule_timer(self, delay_seconds: float) -> None:
+        """Schedule queue processing after the provided delay."""
         # Cancel existing timer if any
         if self._timer is not None:
             self._timer.cancel()
 
-        # Start new timer
         self._timer = threading.Timer(
-            config.debounce_seconds,
+            delay_seconds,
             self._process_queue,
         )
         self._timer.daemon = True
         self._timer.start()
 
-        logger.debug("Memory update timer set for %ss", config.debounce_seconds)
-
     def _process_queue(self) -> None:
         """Process all queued conversation contexts."""
         # Import here to avoid circular dependency
@@ -110,8 +150,8 @@ class MemoryUpdateQueue:
 
         with self._lock:
             if self._processing:
-                # Already processing, reschedule
-                self._reset_timer()
+                # Preserve immediate flush semantics even if another worker is active.
+                self._schedule_timer(0)
                 return
 
             if not self._queue:
@@ -164,6 +204,13 @@ class MemoryUpdateQueue:
 
         self._process_queue()
 
+    def flush_nowait(self) -> None:
+        """Start queue processing immediately in a background thread."""
+        with self._lock:
+            # Daemon thread: queued messages may be lost if the process exits
+            # before _process_queue completes. Acceptable for best-effort memory updates.
+            self._schedule_timer(0)
+
     def clear(self) -> None:
         """Clear the queue without processing.
 

backend/packages/harness/deerflow/agents/memory/storage.py

@@ -4,6 +4,7 @@ import abc
 import json
 import logging
 import threading
+import uuid
 from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
@@ -66,6 +67,8 @@ class FileMemoryStorage(MemoryStorage):
         # Per-agent memory cache: keyed by agent_name (None = global)
         # Value: (memory_data, file_mtime)
         self._memory_cache: dict[str | None, tuple[dict[str, Any], float | None]] = {}
+        # Guards all reads and writes to _memory_cache across concurrent callers.
+        self._cache_lock = threading.Lock()
 
     def _validate_agent_name(self, agent_name: str) -> None:
         """Validate that the agent name is safe to use in filesystem paths.
@@ -114,14 +117,17 @@ class FileMemoryStorage(MemoryStorage):
         except OSError:
             current_mtime = None
 
-        cached = self._memory_cache.get(agent_name)
+        with self._cache_lock:
+            cached = self._memory_cache.get(agent_name)
+            if cached is not None and cached[1] == current_mtime:
+                return cached[0]
 
-        if cached is None or cached[1] != current_mtime:
-            memory_data = self._load_memory_from_file(agent_name)
+        memory_data = self._load_memory_from_file(agent_name)
+
+        with self._cache_lock:
             self._memory_cache[agent_name] = (memory_data, current_mtime)
-            return memory_data
 
-        return cached[0]
+        return memory_data
 
     def reload(self, agent_name: str | None = None) -> dict[str, Any]:
         """Reload memory data from file, forcing cache invalidation."""
@@ -133,7 +139,8 @@ class FileMemoryStorage(MemoryStorage):
         except OSError:
             mtime = None
 
-        self._memory_cache[agent_name] = (memory_data, mtime)
+        with self._cache_lock:
+            self._memory_cache[agent_name] = (memory_data, mtime)
         return memory_data
 
     def save(self, memory_data: dict[str, Any], agent_name: str | None = None) -> bool:
@@ -142,9 +149,12 @@ class FileMemoryStorage(MemoryStorage):
 
         try:
             file_path.parent.mkdir(parents=True, exist_ok=True)
-            memory_data["lastUpdated"] = utc_now_iso_z()
+            # Shallow-copy before adding lastUpdated so the caller's dict is not
+            # mutated as a side-effect, and the cache reference is not silently
+            # updated before the file write succeeds.
+            memory_data = {**memory_data, "lastUpdated": utc_now_iso_z()}
 
-            temp_path = file_path.with_suffix(".tmp")
+            temp_path = file_path.with_suffix(f".{uuid.uuid4().hex}.tmp")
             with open(temp_path, "w", encoding="utf-8") as f:
                 json.dump(memory_data, f, indent=2, ensure_ascii=False)
 
@@ -155,7 +165,8 @@ class FileMemoryStorage(MemoryStorage):
             except OSError:
                 mtime = None
 
-            self._memory_cache[agent_name] = (memory_data, mtime)
+            with self._cache_lock:
+                self._memory_cache[agent_name] = (memory_data, mtime)
             logger.info("Memory saved to %s", file_path)
             return True
         except OSError as e:

backend/packages/harness/deerflow/agents/memory/summarization_hook.py

@@ -0,0 +1,31 @@
+"""Hooks fired before summarization removes messages from state."""
+
+from __future__ import annotations
+
+from deerflow.agents.memory.message_processing import detect_correction, detect_reinforcement, filter_messages_for_memory
+from deerflow.agents.memory.queue import get_memory_queue
+from deerflow.agents.middlewares.summarization_middleware import SummarizationEvent
+from deerflow.config.memory_config import get_memory_config
+
+
+def memory_flush_hook(event: SummarizationEvent) -> None:
+    """Flush messages about to be summarized into the memory queue."""
+    if not get_memory_config().enabled or not event.thread_id:
+        return
+
+    filtered_messages = filter_messages_for_memory(list(event.messages_to_summarize))
+    user_messages = [message for message in filtered_messages if getattr(message, "type", None) == "human"]
+    assistant_messages = [message for message in filtered_messages if getattr(message, "type", None) == "ai"]
+    if not user_messages or not assistant_messages:
+        return
+
+    correction_detected = detect_correction(filtered_messages)
+    reinforcement_detected = not correction_detected and detect_reinforcement(filtered_messages)
+    queue = get_memory_queue()
+    queue.add_nowait(
+        thread_id=event.thread_id,
+        messages=filtered_messages,
+        agent_name=event.agent_name,
+        correction_detected=correction_detected,
+        reinforcement_detected=reinforcement_detected,
+    )

backend/packages/harness/deerflow/agents/memory/updater.py

@@ -1,10 +1,15 @@
 """Memory updater for reading, writing, and updating memory data."""
 
+import asyncio
+import atexit
+import concurrent.futures
+import copy
 import json
 import logging
 import math
 import re
 import uuid
+from collections.abc import Awaitable
 from typing import Any
 
 from deerflow.agents.memory.prompt import (
@@ -21,6 +26,12 @@ from deerflow.models import create_chat_model
 
 logger = logging.getLogger(__name__)
 
+_SYNC_MEMORY_UPDATER_EXECUTOR = concurrent.futures.ThreadPoolExecutor(
+    max_workers=4,
+    thread_name_prefix="memory-updater-sync",
+)
+atexit.register(lambda: _SYNC_MEMORY_UPDATER_EXECUTOR.shutdown(wait=False))
+
 
 def _create_empty_memory() -> dict[str, Any]:
     """Backward-compatible wrapper around the storage-layer empty-memory factory."""
@@ -206,6 +217,39 @@ def _extract_text(content: Any) -> str:
     return str(content)
 
 
+def _run_async_update_sync(coro: Awaitable[bool]) -> bool:
+    """Run an async memory update from sync code, including nested-loop contexts."""
+    handed_off = False
+
+    try:
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+        if loop is not None and loop.is_running():
+            future = _SYNC_MEMORY_UPDATER_EXECUTOR.submit(asyncio.run, coro)
+            handed_off = True
+            return future.result()
+
+        handed_off = True
+        return asyncio.run(coro)
+    except Exception:
+        if not handed_off:
+            close = getattr(coro, "close", None)
+            if callable(close):
+                try:
+                    close()
+                except Exception:
+                    logger.debug(
+                        "Failed to close un-awaited memory update coroutine",
+                        exc_info=True,
+                    )
+
+        logger.exception("Failed to run async memory update from sync context")
+        return False
+
+
 # Matches sentences that describe a file-upload *event* rather than general
 # file-related work.  Deliberately narrow to avoid removing legitimate facts
 # such as "User works with CSV files" or "prefers PDF export".
@@ -269,6 +313,117 @@ class MemoryUpdater:
         model_name = self._model_name or config.model_name
         return create_chat_model(name=model_name, thinking_enabled=False)
 
+    def _build_correction_hint(
+        self,
+        correction_detected: bool,
+        reinforcement_detected: bool,
+    ) -> str:
+        """Build optional prompt hints for correction and reinforcement signals."""
+        correction_hint = ""
+        if correction_detected:
+            correction_hint = (
+                "IMPORTANT: Explicit correction signals were detected in this conversation. "
+                "Pay special attention to what the agent got wrong, what the user corrected, "
+                "and record the correct approach as a fact with category "
+                '"correction" and confidence >= 0.95 when appropriate.'
+            )
+        if reinforcement_detected:
+            reinforcement_hint = (
+                "IMPORTANT: Positive reinforcement signals were detected in this conversation. "
+                "The user explicitly confirmed the agent's approach was correct or helpful. "
+                "Record the confirmed approach, style, or preference as a fact with category "
+                '"preference" or "behavior" and confidence >= 0.9 when appropriate.'
+            )
+            correction_hint = (correction_hint + "\n" + reinforcement_hint).strip() if correction_hint else reinforcement_hint
+
+        return correction_hint
+
+    def _prepare_update_prompt(
+        self,
+        messages: list[Any],
+        agent_name: str | None,
+        correction_detected: bool,
+        reinforcement_detected: bool,
+    ) -> tuple[dict[str, Any], str] | None:
+        """Load memory and build the update prompt for a conversation."""
+        config = get_memory_config()
+        if not config.enabled or not messages:
+            return None
+
+        current_memory = get_memory_data(agent_name)
+        conversation_text = format_conversation_for_update(messages)
+        if not conversation_text.strip():
+            return None
+
+        correction_hint = self._build_correction_hint(
+            correction_detected=correction_detected,
+            reinforcement_detected=reinforcement_detected,
+        )
+        prompt = MEMORY_UPDATE_PROMPT.format(
+            current_memory=json.dumps(current_memory, indent=2),
+            conversation=conversation_text,
+            correction_hint=correction_hint,
+        )
+        return current_memory, prompt
+
+    def _finalize_update(
+        self,
+        current_memory: dict[str, Any],
+        response_content: Any,
+        thread_id: str | None,
+        agent_name: str | None,
+    ) -> bool:
+        """Parse the model response, apply updates, and persist memory."""
+        response_text = _extract_text(response_content).strip()
+
+        if response_text.startswith("```"):
+            lines = response_text.split("\n")
+            response_text = "\n".join(lines[1:-1] if lines[-1] == "```" else lines[1:])
+
+        update_data = json.loads(response_text)
+        # Deep-copy before in-place mutation so a subsequent save() failure
+        # cannot corrupt the still-cached original object reference.
+        updated_memory = self._apply_updates(copy.deepcopy(current_memory), update_data, thread_id)
+        updated_memory = _strip_upload_mentions_from_memory(updated_memory)
+        return get_memory_storage().save(updated_memory, agent_name)
+
+    async def aupdate_memory(
+        self,
+        messages: list[Any],
+        thread_id: str | None = None,
+        agent_name: str | None = None,
+        correction_detected: bool = False,
+        reinforcement_detected: bool = False,
+    ) -> bool:
+        """Update memory asynchronously based on conversation messages."""
+        try:
+            prepared = await asyncio.to_thread(
+                self._prepare_update_prompt,
+                messages=messages,
+                agent_name=agent_name,
+                correction_detected=correction_detected,
+                reinforcement_detected=reinforcement_detected,
+            )
+            if prepared is None:
+                return False
+
+            current_memory, prompt = prepared
+            model = self._get_model()
+            response = await model.ainvoke(prompt)
+            return await asyncio.to_thread(
+                self._finalize_update,
+                current_memory=current_memory,
+                response_content=response.content,
+                thread_id=thread_id,
+                agent_name=agent_name,
+            )
+        except json.JSONDecodeError as e:
+            logger.warning("Failed to parse LLM response for memory update: %s", e)
+            return False
+        except Exception as e:
+            logger.exception("Memory update failed: %s", e)
+            return False
+
     def update_memory(
         self,
         messages: list[Any],
@@ -277,7 +432,7 @@ class MemoryUpdater:
         correction_detected: bool = False,
         reinforcement_detected: bool = False,
     ) -> bool:
-        """Update memory based on conversation messages.
+        """Synchronously update memory via the async updater path.
 
         Args:
             messages: List of conversation messages.
@@ -289,78 +444,15 @@ class MemoryUpdater:
         Returns:
             True if update was successful, False otherwise.
         """
-        config = get_memory_config()
-        if not config.enabled:
-            return False
-
-        if not messages:
-            return False
-
-        try:
-            # Get current memory
-            current_memory = get_memory_data(agent_name)
-
-            # Format conversation for prompt
-            conversation_text = format_conversation_for_update(messages)
-
-            if not conversation_text.strip():
-                return False
-
-            # Build prompt
-            correction_hint = ""
-            if correction_detected:
-                correction_hint = (
-                    "IMPORTANT: Explicit correction signals were detected in this conversation. "
-                    "Pay special attention to what the agent got wrong, what the user corrected, "
-                    "and record the correct approach as a fact with category "
-                    '"correction" and confidence >= 0.95 when appropriate.'
-                )
-            if reinforcement_detected:
-                reinforcement_hint = (
-                    "IMPORTANT: Positive reinforcement signals were detected in this conversation. "
-                    "The user explicitly confirmed the agent's approach was correct or helpful. "
-                    "Record the confirmed approach, style, or preference as a fact with category "
-                    '"preference" or "behavior" and confidence >= 0.9 when appropriate.'
-                )
-                correction_hint = (correction_hint + "\n" + reinforcement_hint).strip() if correction_hint else reinforcement_hint
-
-            prompt = MEMORY_UPDATE_PROMPT.format(
-                current_memory=json.dumps(current_memory, indent=2),
-                conversation=conversation_text,
-                correction_hint=correction_hint,
+        return _run_async_update_sync(
+            self.aupdate_memory(
+                messages=messages,
+                thread_id=thread_id,
+                agent_name=agent_name,
+                correction_detected=correction_detected,
+                reinforcement_detected=reinforcement_detected,
             )
-
-            # Call LLM
-            model = self._get_model()
-            response = model.invoke(prompt)
-            response_text = _extract_text(response.content).strip()
-
-            # Parse response
-            # Remove markdown code blocks if present
-            if response_text.startswith("```"):
-                lines = response_text.split("\n")
-                response_text = "\n".join(lines[1:-1] if lines[-1] == "```" else lines[1:])
-
-            update_data = json.loads(response_text)
-
-            # Apply updates
-            updated_memory = self._apply_updates(current_memory, update_data, thread_id)
-
-            # Strip file-upload mentions from all summaries before saving.
-            # Uploaded files are session-scoped and won't exist in future sessions,
-            # so recording upload events in long-term memory causes the agent to
-            # try (and fail) to locate those files in subsequent conversations.
-            updated_memory = _strip_upload_mentions_from_memory(updated_memory)
-
-            # Save
-            return get_memory_storage().save(updated_memory, agent_name)
-
-        except json.JSONDecodeError as e:
-            logger.warning("Failed to parse LLM response for memory update: %s", e)
-            return False
-        except Exception as e:
-            logger.exception("Memory update failed: %s", e)
-            return False
+        )
 
     def _apply_updates(
         self,

backend/packages/harness/deerflow/agents/middlewares/dangling_tool_call_middleware.py

@@ -13,6 +13,7 @@ at the correct positions (immediately after each dangling AIMessage), not append
 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
@@ -33,6 +34,44 @@ class DanglingToolCallMiddleware(AgentMiddleware[AgentState]):
     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.
 
@@ -51,7 +90,7 @@ class DanglingToolCallMiddleware(AgentMiddleware[AgentState]):
         for msg in messages:
             if getattr(msg, "type", None) != "ai":
                 continue
-            for tc in getattr(msg, "tool_calls", None) or []:
+            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
@@ -70,7 +109,7 @@ class DanglingToolCallMiddleware(AgentMiddleware[AgentState]):
             patched.append(msg)
             if getattr(msg, "type", None) != "ai":
                 continue
-            for tc in getattr(msg, "tool_calls", None) or []:
+            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(

backend/packages/harness/deerflow/agents/middlewares/llm_error_handling_middleware.py

@@ -4,6 +4,7 @@ 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
@@ -19,6 +20,8 @@ from langchain.agents.middleware.types import (
 from langchain_core.messages import AIMessage
 from langgraph.errors import GraphBubbleUp
 
+from deerflow.config import get_app_config
+
 logger = logging.getLogger(__name__)
 
 _RETRIABLE_STATUS_CODES = {408, 409, 425, 429, 500, 502, 503, 504}
@@ -67,6 +70,80 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
     retry_base_delay_ms: int = 1000
     retry_cap_delay_ms: int = 8000
 
+    circuit_failure_threshold: int = 5
+    circuit_recovery_timeout_sec: int = 60
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+
+        # Load Circuit Breaker configs from app config if available, fall back to defaults
+        try:
+            app_config = get_app_config()
+            self.circuit_failure_threshold = app_config.circuit_breaker.failure_threshold
+            self.circuit_recovery_timeout_sec = app_config.circuit_breaker.recovery_timeout_sec
+        except (FileNotFoundError, RuntimeError):
+            # Gracefully fall back to class defaults in test environments
+            pass
+
+        # 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()
@@ -104,6 +181,9 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
         reason_text = "provider is busy" if reason == "busy" else "provider request failed temporarily"
         return f"LLM request retry {attempt}/{self.retry_max_attempts}: {reason_text}. Retrying in {seconds}s."
 
+    def _build_circuit_breaker_message(self) -> str:
+        return "The configured LLM provider is currently unavailable due to continuous failures. Circuit breaker is engaged to protect the system. Please wait a moment before trying again."
+
     def _build_user_message(self, exc: BaseException, reason: str) -> str:
         detail = _extract_error_detail(exc)
         if reason == "quota":
@@ -138,12 +218,20 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
         request: ModelRequest,
         handler: Callable[[ModelRequest], ModelResponse],
     ) -> ModelCallResult:
+        if self._check_circuit():
+            return AIMessage(content=self._build_circuit_breaker_message())
+
         attempt = 1
         while True:
             try:
-                return handler(request)
+                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)
@@ -166,6 +254,8 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
                     _extract_error_detail(exc),
                     exc_info=exc,
                 )
+                if retriable:
+                    self._record_failure()
                 return AIMessage(content=self._build_user_message(exc, reason))
 
     @override
@@ -174,12 +264,20 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
         request: ModelRequest,
         handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
     ) -> ModelCallResult:
+        if self._check_circuit():
+            return AIMessage(content=self._build_circuit_breaker_message())
+
         attempt = 1
         while True:
             try:
-                return await handler(request)
+                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)
@@ -202,6 +300,8 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
                     _extract_error_detail(exc),
                     exc_info=exc,
                 )
+                if retriable:
+                    self._record_failure()
                 return AIMessage(content=self._build_user_message(exc, reason))
 
 

backend/packages/harness/deerflow/agents/middlewares/loop_detection_middleware.py

@@ -17,6 +17,7 @@ import json
 import logging
 import threading
 from collections import OrderedDict, defaultdict
+from copy import deepcopy
 from typing import override
 
 from langchain.agents import AgentState
@@ -323,6 +324,26 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
         # 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)
 
@@ -330,12 +351,8 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
             # Strip tool_calls from the last AIMessage to force text output
             messages = state.get("messages", [])
             last_msg = messages[-1]
-            stripped_msg = last_msg.model_copy(
-                update={
-                    "tool_calls": [],
-                    "content": self._append_text(last_msg.content, warning),
-                }
-            )
+            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:

backend/packages/harness/deerflow/agents/middlewares/memory_middleware.py

@@ -1,50 +1,19 @@
 """Middleware for memory mechanism."""
 
 import logging
-import re
-from typing import Any, override
+from typing import override
 
 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
 from langgraph.config import get_config
 from langgraph.runtime import Runtime
 
+from deerflow.agents.memory.message_processing import detect_correction, detect_reinforcement, filter_messages_for_memory
 from deerflow.agents.memory.queue import get_memory_queue
 from deerflow.config.memory_config import get_memory_config
 
 logger = logging.getLogger(__name__)
 
-_UPLOAD_BLOCK_RE = re.compile(r"<uploaded_files>[\s\S]*?</uploaded_files>\n*", re.IGNORECASE)
-_CORRECTION_PATTERNS = (
-    re.compile(r"\bthat(?:'s| is) (?:wrong|incorrect)\b", re.IGNORECASE),
-    re.compile(r"\byou misunderstood\b", re.IGNORECASE),
-    re.compile(r"\btry again\b", re.IGNORECASE),
-    re.compile(r"\bredo\b", re.IGNORECASE),
-    re.compile(r"不对"),
-    re.compile(r"你理解错了"),
-    re.compile(r"你理解有误"),
-    re.compile(r"重试"),
-    re.compile(r"重新来"),
-    re.compile(r"换一种"),
-    re.compile(r"改用"),
-)
-
-_REINFORCEMENT_PATTERNS = (
-    re.compile(r"\byes[,.]?\s+(?:exactly|perfect|that(?:'s| is) (?:right|correct|it))\b", re.IGNORECASE),
-    re.compile(r"\bperfect(?:[.!?]|$)", re.IGNORECASE),
-    re.compile(r"\bexactly\s+(?:right|correct)\b", re.IGNORECASE),
-    re.compile(r"\bthat(?:'s| is)\s+(?:exactly\s+)?(?:right|correct|what i (?:wanted|needed|meant))\b", re.IGNORECASE),
-    re.compile(r"\bkeep\s+(?:doing\s+)?that\b", re.IGNORECASE),
-    re.compile(r"\bjust\s+(?:like\s+)?(?:that|this)\b", re.IGNORECASE),
-    re.compile(r"\bthis is (?:great|helpful)\b(?:[.!?]|$)", re.IGNORECASE),
-    re.compile(r"\bthis is what i wanted\b(?:[.!?]|$)", re.IGNORECASE),
-    re.compile(r"对[，,]?\s*就是这样(?:[。！？!?.]|$)"),
-    re.compile(r"完全正确(?:[。！？!?.]|$)"),
-    re.compile(r"(?:对[，,]?\s*)?就是这个意思(?:[。！？!?.]|$)"),
-    re.compile(r"正是我想要的(?:[。！？!?.]|$)"),
-    re.compile(r"继续保持(?:[。！？!?.]|$)"),
-)
-
 
 class MemoryMiddlewareState(AgentState):
     """Compatible with the `ThreadState` schema."""
@@ -52,125 +21,6 @@ class MemoryMiddlewareState(AgentState):
     pass
 
 
-def _extract_message_text(message: Any) -> str:
-    """Extract plain text from message content for filtering and signal detection."""
-    content = getattr(message, "content", "")
-    if isinstance(content, list):
-        text_parts: list[str] = []
-        for part in content:
-            if isinstance(part, str):
-                text_parts.append(part)
-            elif isinstance(part, dict):
-                text_val = part.get("text")
-                if isinstance(text_val, str):
-                    text_parts.append(text_val)
-        return " ".join(text_parts)
-    return str(content)
-
-
-def _filter_messages_for_memory(messages: list[Any]) -> list[Any]:
-    """Filter messages to keep only user inputs and final assistant responses.
-
-    This filters out:
-    - Tool messages (intermediate tool call results)
-    - AI messages with tool_calls (intermediate steps, not final responses)
-    - The <uploaded_files> block injected by UploadsMiddleware into human messages
-      (file paths are session-scoped and must not persist in long-term memory).
-      The user's actual question is preserved; only turns whose content is entirely
-      the upload block (nothing remains after stripping) are dropped along with
-      their paired assistant response.
-
-    Only keeps:
-    - Human messages (with the ephemeral upload block removed)
-    - AI messages without tool_calls (final assistant responses), unless the
-      paired human turn was upload-only and had no real user text.
-
-    Args:
-        messages: List of all conversation messages.
-
-    Returns:
-        Filtered list containing only user inputs and final assistant responses.
-    """
-    filtered = []
-    skip_next_ai = False
-    for msg in messages:
-        msg_type = getattr(msg, "type", None)
-
-        if msg_type == "human":
-            content_str = _extract_message_text(msg)
-            if "<uploaded_files>" in content_str:
-                # Strip the ephemeral upload block; keep the user's real question.
-                stripped = _UPLOAD_BLOCK_RE.sub("", content_str).strip()
-                if not stripped:
-                    # Nothing left — the entire turn was upload bookkeeping;
-                    # skip it and the paired assistant response.
-                    skip_next_ai = True
-                    continue
-                # Rebuild the message with cleaned content so the user's question
-                # is still available for memory summarisation.
-                from copy import copy
-
-                clean_msg = copy(msg)
-                clean_msg.content = stripped
-                filtered.append(clean_msg)
-                skip_next_ai = False
-            else:
-                filtered.append(msg)
-                skip_next_ai = False
-        elif msg_type == "ai":
-            tool_calls = getattr(msg, "tool_calls", None)
-            if not tool_calls:
-                if skip_next_ai:
-                    skip_next_ai = False
-                    continue
-                filtered.append(msg)
-        # Skip tool messages and AI messages with tool_calls
-
-    return filtered
-
-
-def detect_correction(messages: list[Any]) -> bool:
-    """Detect explicit user corrections in recent conversation turns.
-
-    The queue keeps only one pending context per thread, so callers pass the
-    latest filtered message list. Checking only recent user turns keeps signal
-    detection conservative while avoiding stale corrections from long histories.
-    """
-    recent_user_msgs = [msg for msg in messages[-6:] if getattr(msg, "type", None) == "human"]
-
-    for msg in recent_user_msgs:
-        content = _extract_message_text(msg).strip()
-        if not content:
-            continue
-        if any(pattern.search(content) for pattern in _CORRECTION_PATTERNS):
-            return True
-
-    return False
-
-
-def detect_reinforcement(messages: list[Any]) -> bool:
-    """Detect explicit positive reinforcement signals in recent conversation turns.
-
-    Complements detect_correction() by identifying when the user confirms the
-    agent's approach was correct. This allows the memory system to record what
-    worked well, not just what went wrong.
-
-    The queue keeps only one pending context per thread, so callers pass the
-    latest filtered message list. Checking only recent user turns keeps signal
-    detection conservative while avoiding stale signals from long histories.
-    """
-    recent_user_msgs = [msg for msg in messages[-6:] if getattr(msg, "type", None) == "human"]
-
-    for msg in recent_user_msgs:
-        content = _extract_message_text(msg).strip()
-        if not content:
-            continue
-        if any(pattern.search(content) for pattern in _REINFORCEMENT_PATTERNS):
-            return True
-
-    return False
-
-
 class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
     """Middleware that queues conversation for memory update after agent execution.
 
@@ -223,7 +73,7 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
             return None
 
         # Filter to only keep user inputs and final assistant responses
-        filtered_messages = _filter_messages_for_memory(messages)
+        filtered_messages = filter_messages_for_memory(messages)
 
         # Only queue if there's meaningful conversation
         # At minimum need one user message and one assistant response

backend/packages/harness/deerflow/agents/middlewares/summarization_middleware.py

@@ -0,0 +1,151 @@
+"""Summarization middleware extensions for DeerFlow."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+from langchain.agents import AgentState
+from langchain.agents.middleware import SummarizationMiddleware
+from langchain_core.messages import AnyMessage, RemoveMessage
+from langgraph.config import get_config
+from langgraph.graph.message import REMOVE_ALL_MESSAGES
+from langgraph.runtime import Runtime
+
+logger = logging.getLogger(__name__)
+
+
+@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
+
+
+class DeerFlowSummarizationMiddleware(SummarizationMiddleware):
+    """Summarization middleware with pre-compression hook dispatch."""
+
+    def __init__(
+        self,
+        *args,
+        before_summarization: list[BeforeSummarizationHook] | None = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self._before_summarization_hooks = before_summarization or []
+
+    def before_model(self, state: AgentState, runtime: Runtime) -> dict | None:
+        return self._maybe_summarize(state, runtime)
+
+    async def abefore_model(self, state: AgentState, runtime: Runtime) -> dict | None:
+        return await self._amaybe_summarize(state, runtime)
+
+    def _maybe_summarize(self, state: AgentState, runtime: Runtime) -> dict | None:
+        messages = state["messages"]
+        self._ensure_message_ids(messages)
+
+        total_tokens = self.token_counter(messages)
+        if not self._should_summarize(messages, total_tokens):
+            return None
+
+        cutoff_index = self._determine_cutoff_index(messages)
+        if cutoff_index <= 0:
+            return None
+
+        messages_to_summarize, preserved_messages = self._partition_messages(messages, cutoff_index)
+        self._fire_hooks(messages_to_summarize, preserved_messages, runtime)
+        summary = self._create_summary(messages_to_summarize)
+        new_messages = self._build_new_messages(summary)
+
+        return {
+            "messages": [
+                RemoveMessage(id=REMOVE_ALL_MESSAGES),
+                *new_messages,
+                *preserved_messages,
+            ]
+        }
+
+    async def _amaybe_summarize(self, state: AgentState, runtime: Runtime) -> dict | None:
+        messages = state["messages"]
+        self._ensure_message_ids(messages)
+
+        total_tokens = self.token_counter(messages)
+        if not self._should_summarize(messages, total_tokens):
+            return None
+
+        cutoff_index = self._determine_cutoff_index(messages)
+        if cutoff_index <= 0:
+            return None
+
+        messages_to_summarize, preserved_messages = self._partition_messages(messages, cutoff_index)
+        self._fire_hooks(messages_to_summarize, preserved_messages, runtime)
+        summary = await self._acreate_summary(messages_to_summarize)
+        new_messages = self._build_new_messages(summary)
+
+        return {
+            "messages": [
+                RemoveMessage(id=REMOVE_ALL_MESSAGES),
+                *new_messages,
+                *preserved_messages,
+            ]
+        }
+
+    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)

backend/packages/harness/deerflow/agents/middlewares/title_middleware.py

@@ -1,6 +1,7 @@
 """Middleware for automatic thread title generation."""
 
 import logging
+import re
 from typing import NotRequired, override
 
 from langchain.agents import AgentState
@@ -77,7 +78,7 @@ class TitleMiddleware(AgentMiddleware[TitleMiddlewareState]):
         assistant_msg_content = next((m.content for m in messages if m.type == "ai"), "")
 
         user_msg = self._normalize_content(user_msg_content)
-        assistant_msg = self._normalize_content(assistant_msg_content)
+        assistant_msg = self._strip_think_tags(self._normalize_content(assistant_msg_content))
 
         prompt = config.prompt_template.format(
             max_words=config.max_words,
@@ -86,10 +87,15 @@ class TitleMiddleware(AgentMiddleware[TitleMiddlewareState]):
         )
         return prompt, user_msg
 
+    def _strip_think_tags(self, text: str) -> str:
+        """Remove <think>...</think> blocks emitted by reasoning models (e.g. minimax, DeepSeek-R1)."""
+        return re.sub(r"<think>[\s\S]*?</think>", "", text, flags=re.IGNORECASE).strip()
+
     def _parse_title(self, content: object) -> str:
         """Normalize model output into a clean title string."""
         config = get_title_config()
         title_content = self._normalize_content(content)
+        title_content = self._strip_think_tags(title_content)
         title = title_content.strip().strip('"').strip("'")
         return title[: config.max_chars] if len(title) > config.max_chars else title
 

backend/packages/harness/deerflow/agents/middlewares/todo_middleware.py

@@ -1,9 +1,14 @@
-"""Middleware that extends TodoListMiddleware with context-loss detection.
+"""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
@@ -12,6 +17,7 @@ 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
 
@@ -34,6 +40,11 @@ def _reminder_in_messages(messages: list[Any]) -> bool:
     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] = []
@@ -57,7 +68,7 @@ class TodoMiddleware(TodoListMiddleware):
     def before_model(
         self,
         state: PlanningState,
-        runtime: Runtime,  # noqa: ARG002
+        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]
@@ -98,3 +109,71 @@ class TodoMiddleware(TodoListMiddleware):
     ) -> 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)

backend/packages/harness/deerflow/client.py

@@ -722,6 +722,10 @@ class DeerFlowClient:
             Dict with "models" key containing list of model info dicts,
             matching the Gateway API ``ModelsListResponse`` schema.
         """
+        token_usage_enabled = getattr(getattr(self._app_config, "token_usage", None), "enabled", False)
+        if not isinstance(token_usage_enabled, bool):
+            token_usage_enabled = False
+
         return {
             "models": [
                 {
@@ -733,7 +737,8 @@ class DeerFlowClient:
                     "supports_reasoning_effort": getattr(model, "supports_reasoning_effort", False),
                 }
                 for model in self._app_config.models
-            ]
+            ],
+            "token_usage": {"enabled": token_usage_enabled},
         }
 
     def list_skills(self, enabled_only: bool = False) -> dict:

backend/packages/harness/deerflow/community/aio_sandbox/aio_sandbox_provider.py

@@ -119,6 +119,16 @@ class AioSandboxProvider(SandboxProvider):
         if self._config.get("idle_timeout", DEFAULT_IDLE_TIMEOUT) > 0:
             self._start_idle_checker()
 
+    @property
+    def uses_thread_data_mounts(self) -> bool:
+        """Whether thread workspace/uploads/outputs are visible via mounts.
+
+        Local container backends bind-mount the thread data directories, so files
+        written by the gateway are already visible when the sandbox starts.
+        Remote backends may require explicit file sync.
+        """
+        return isinstance(self._backend, LocalContainerBackend)
+
     # ── Factory methods ──────────────────────────────────────────────────
 
     def _create_backend(self) -> SandboxBackend:

backend/packages/harness/deerflow/community/jina_ai/tools.py

@@ -1,3 +1,5 @@
+import asyncio
+
 from langchain.tools import tool
 
 from deerflow.community.jina_ai.jina_client import JinaClient
@@ -26,5 +28,5 @@ async def web_fetch_tool(url: str) -> str:
     html_content = await jina_client.crawl(url, return_format="html", timeout=timeout)
     if isinstance(html_content, str) and html_content.startswith("Error:"):
         return html_content
-    article = readability_extractor.extract_article(html_content)
+    article = await asyncio.to_thread(readability_extractor.extract_article, html_content)
     return article.to_markdown()[:4096]

backend/packages/harness/deerflow/config/agents_api_config.py

@@ -0,0 +1,32 @@
+"""Configuration for the custom agents management API."""
+
+from pydantic import BaseModel, Field
+
+
+class AgentsApiConfig(BaseModel):
+    """Configuration for custom-agent and user-profile management routes."""
+
+    enabled: bool = Field(
+        default=False,
+        description=("Whether to expose the custom-agent management API over HTTP. When disabled, the gateway rejects read/write access to custom agent SOUL.md, config, and USER.md prompt-management routes."),
+    )
+
+
+_agents_api_config: AgentsApiConfig = AgentsApiConfig()
+
+
+def get_agents_api_config() -> AgentsApiConfig:
+    """Get the current agents API configuration."""
+    return _agents_api_config
+
+
+def set_agents_api_config(config: AgentsApiConfig) -> None:
+    """Set the agents API configuration."""
+    global _agents_api_config
+    _agents_api_config = config
+
+
+def load_agents_api_config_from_dict(config_dict: dict) -> None:
+    """Load agents API configuration from a dictionary."""
+    global _agents_api_config
+    _agents_api_config = AgentsApiConfig(**config_dict)

backend/packages/harness/deerflow/config/agents_config.py

@@ -15,6 +15,17 @@ SOUL_FILENAME = "SOUL.md"
 AGENT_NAME_PATTERN = re.compile(r"^[A-Za-z0-9-]+$")
 
 
+def validate_agent_name(name: str | None) -> str | None:
+    """Validate a custom agent name before using it in filesystem paths."""
+    if name is None:
+        return None
+    if not isinstance(name, str):
+        raise ValueError("Invalid agent name. Expected a string or None.")
+    if not AGENT_NAME_PATTERN.fullmatch(name):
+        raise ValueError(f"Invalid agent name '{name}'. Must match pattern: {AGENT_NAME_PATTERN.pattern}")
+    return name
+
+
 class AgentConfig(BaseModel):
     """Configuration for a custom agent."""
 
@@ -46,8 +57,7 @@ def load_agent_config(name: str | None) -> AgentConfig | None:
     if name is None:
         return None
 
-    if not AGENT_NAME_PATTERN.match(name):
-        raise ValueError(f"Invalid agent name '{name}'. Must match pattern: {AGENT_NAME_PATTERN.pattern}")
+    name = validate_agent_name(name)
     agent_dir = get_paths().agent_dir(name)
     config_file = agent_dir / "config.yaml"
 

backend/packages/harness/deerflow/config/app_config.py

@@ -9,6 +9,7 @@ from dotenv import load_dotenv
 from pydantic import BaseModel, ConfigDict, Field
 
 from deerflow.config.acp_config import load_acp_config_from_dict
+from deerflow.config.agents_api_config import AgentsApiConfig, load_agents_api_config_from_dict
 from deerflow.config.checkpointer_config import CheckpointerConfig, load_checkpointer_config_from_dict
 from deerflow.config.extensions_config import ExtensionsConfig
 from deerflow.config.guardrails_config import GuardrailsConfig, load_guardrails_config_from_dict
@@ -30,6 +31,13 @@ load_dotenv()
 logger = logging.getLogger(__name__)
 
 
+class CircuitBreakerConfig(BaseModel):
+    """Configuration for the LLM Circuit Breaker."""
+
+    failure_threshold: int = Field(default=5, description="Number of consecutive failures before tripping the circuit")
+    recovery_timeout_sec: int = Field(default=60, description="Time in seconds before attempting to recover the circuit")
+
+
 def _default_config_candidates() -> tuple[Path, ...]:
     """Return deterministic config.yaml locations without relying on cwd."""
     backend_dir = Path(__file__).resolve().parents[4]
@@ -53,8 +61,10 @@ class AppConfig(BaseModel):
     title: TitleConfig = Field(default_factory=TitleConfig, description="Automatic title generation configuration")
     summarization: SummarizationConfig = Field(default_factory=SummarizationConfig, description="Conversation summarization configuration")
     memory: MemoryConfig = Field(default_factory=MemoryConfig, description="Memory subsystem configuration")
+    agents_api: AgentsApiConfig = Field(default_factory=AgentsApiConfig, description="Custom-agent management API configuration")
     subagents: SubagentsAppConfig = Field(default_factory=SubagentsAppConfig, description="Subagent runtime configuration")
     guardrails: GuardrailsConfig = Field(default_factory=GuardrailsConfig, description="Guardrail middleware configuration")
+    circuit_breaker: CircuitBreakerConfig = Field(default_factory=CircuitBreakerConfig, description="LLM circuit breaker configuration")
     model_config = ConfigDict(extra="allow", frozen=False)
     checkpointer: CheckpointerConfig | None = Field(default=None, description="Checkpointer configuration")
     stream_bridge: StreamBridgeConfig | None = Field(default=None, description="Stream bridge configuration")
@@ -117,6 +127,10 @@ class AppConfig(BaseModel):
         if "memory" in config_data:
             load_memory_config_from_dict(config_data["memory"])
 
+        # Always refresh agents API config so removed config sections reset
+        # singleton-backed state to its default/disabled values on reload.
+        load_agents_api_config_from_dict(config_data.get("agents_api") or {})
+
         # Load subagents config if present
         if "subagents" in config_data:
             load_subagents_config_from_dict(config_data["subagents"])
@@ -129,6 +143,10 @@ class AppConfig(BaseModel):
         if "guardrails" in config_data:
             load_guardrails_config_from_dict(config_data["guardrails"])
 
+        # Load circuit_breaker config if present
+        if "circuit_breaker" in config_data:
+            config_data["circuit_breaker"] = config_data["circuit_breaker"]
+
         # Load checkpointer config if present
         if "checkpointer" in config_data:
             load_checkpointer_config_from_dict(config_data["checkpointer"])

backend/packages/harness/deerflow/mcp/cache.py

@@ -118,9 +118,13 @@ def get_cached_mcp_tools() -> list[BaseTool]:
                 loop.run_until_complete(initialize_mcp_tools())
         except RuntimeError:
             # No event loop exists, create one
-            asyncio.run(initialize_mcp_tools())
-        except Exception as e:
-            logger.error(f"Failed to lazy-initialize MCP tools: {e}")
+            try:
+                asyncio.run(initialize_mcp_tools())
+            except Exception:
+                logger.exception("Failed to lazy-initialize MCP tools")
+                return []
+        except Exception:
+            logger.exception("Failed to lazy-initialize MCP tools")
             return []
 
     return _mcp_tools_cache or []

backend/packages/harness/deerflow/sandbox/local/local_sandbox_provider.py

@@ -11,6 +11,8 @@ _singleton: LocalSandbox | None = None
 
 
 class LocalSandboxProvider(SandboxProvider):
+    uses_thread_data_mounts = True
+
     def __init__(self):
         """Initialize the local sandbox provider with path mappings."""
         self._path_mappings = self._setup_path_mappings()

backend/packages/harness/deerflow/sandbox/sandbox_provider.py

@@ -8,6 +8,8 @@ from deerflow.sandbox.sandbox import Sandbox
 class SandboxProvider(ABC):
     """Abstract base class for sandbox providers"""
 
+    uses_thread_data_mounts: bool = False
+
     @abstractmethod
     def acquire(self, thread_id: str | None = None) -> str:
         """Acquire a sandbox environment and return its ID.

backend/packages/harness/deerflow/sandbox/tools.py

@@ -1047,6 +1047,7 @@ def ls_tool(runtime: ToolRuntime[ContextT, ThreadState], description: str, path:
         sandbox = ensure_sandbox_initialized(runtime)
         ensure_thread_directories_exist(runtime)
         requested_path = path
+        thread_data = None
         if is_local_sandbox(runtime):
             thread_data = get_thread_data(runtime)
             validate_local_tool_path(path, thread_data, read_only=True)
@@ -1061,6 +1062,8 @@ def ls_tool(runtime: ToolRuntime[ContextT, ThreadState], description: str, path:
         if not children:
             return "(empty)"
         output = "\n".join(children)
+        if thread_data is not None:
+            output = mask_local_paths_in_output(output, thread_data)
         try:
             from deerflow.config.app_config import get_app_config
 

backend/packages/harness/deerflow/tools/builtins/present_file_tool.py

@@ -3,6 +3,7 @@ from typing import Annotated
 
 from langchain.tools import InjectedToolCallId, ToolRuntime, tool
 from langchain_core.messages import ToolMessage
+from langgraph.config import get_config
 from langgraph.types import Command
 from langgraph.typing import ContextT
 
@@ -12,6 +13,23 @@ from deerflow.config.paths import VIRTUAL_PATH_PREFIX, get_paths
 OUTPUTS_VIRTUAL_PREFIX = f"{VIRTUAL_PATH_PREFIX}/outputs"
 
 
+def _get_thread_id(runtime: ToolRuntime[ContextT, ThreadState]) -> str | None:
+    """Resolve the current thread id from runtime context or RunnableConfig."""
+    thread_id = runtime.context.get("thread_id") if runtime.context else None
+    if thread_id:
+        return thread_id
+
+    runtime_config = getattr(runtime, "config", None) or {}
+    thread_id = runtime_config.get("configurable", {}).get("thread_id")
+    if thread_id:
+        return thread_id
+
+    try:
+        return get_config().get("configurable", {}).get("thread_id")
+    except RuntimeError:
+        return None
+
+
 def _normalize_presented_filepath(
     runtime: ToolRuntime[ContextT, ThreadState],
     filepath: str,
@@ -33,9 +51,9 @@ def _normalize_presented_filepath(
     if runtime.state is None:
         raise ValueError("Thread runtime state is not available")
 
-    thread_id = runtime.context.get("thread_id") if runtime.context else None
+    thread_id = _get_thread_id(runtime)
     if not thread_id:
-        raise ValueError("Thread ID is not available in runtime context")
+        raise ValueError("Thread ID is not available in runtime context or runtime config")
 
     thread_data = runtime.state.get("thread_data") or {}
     outputs_path = thread_data.get("outputs_path")

backend/packages/harness/deerflow/tools/builtins/setup_agent_tool.py

@@ -6,6 +6,7 @@ from langchain_core.tools import tool
 from langgraph.prebuilt import ToolRuntime
 from langgraph.types import Command
 
+from deerflow.config.agents_config import validate_agent_name
 from deerflow.config.paths import get_paths
 
 logger = logging.getLogger(__name__)
@@ -25,8 +26,10 @@ def setup_agent(
     """
 
     agent_name: str | None = runtime.context.get("agent_name") if runtime.context else None
+    agent_dir = None
 
     try:
+        agent_name = validate_agent_name(agent_name)
         paths = get_paths()
         agent_dir = paths.agent_dir(agent_name) if agent_name else paths.base_dir
         agent_dir.mkdir(parents=True, exist_ok=True)
@@ -55,7 +58,7 @@ def setup_agent(
     except Exception as e:
         import shutil
 
-        if agent_name and agent_dir.exists():
+        if agent_name and agent_dir is not None and agent_dir.exists():
             # Cleanup the custom agent directory only if it was created but an error occurred during setup
             shutil.rmtree(agent_dir)
         logger.error(f"[agent_creator] Failed to create agent '{agent_name}': {e}", exc_info=True)

backend/packages/harness/deerflow/tools/builtins/task_tool.py

@@ -88,6 +88,7 @@ async def task_tool(
     thread_id = None
     parent_model = None
     trace_id = None
+    metadata: dict = {}
 
     if runtime is not None:
         sandbox_state = runtime.state.get("sandbox")
@@ -107,8 +108,11 @@ async def task_tool(
     # Lazy import to avoid circular dependency
     from deerflow.tools import get_available_tools
 
+    # Inherit parent agent's tool_groups so subagents respect the same restrictions
+    parent_tool_groups = metadata.get("tool_groups")
+
     # Subagents should not have subagent tools enabled (prevent recursive nesting)
-    tools = get_available_tools(model_name=parent_model, subagent_enabled=False)
+    tools = get_available_tools(model_name=parent_model, groups=parent_tool_groups, subagent_enabled=False)
 
     # Create executor
     executor = SubagentExecutor(

backend/packages/harness/deerflow/utils/file_conversion.py

@@ -19,6 +19,8 @@ import logging
 import re
 from pathlib import Path
 
+from deerflow.config.app_config import get_app_config
+
 logger = logging.getLogger(__name__)
 
 # File extensions that should be converted to markdown
@@ -286,6 +288,15 @@ def extract_outline(md_path: Path) -> list[dict]:
     return outline
 
 
+def _get_uploads_config_value(key: str, default: object) -> object:
+    """Read a value from the uploads config, supporting dict and attribute access."""
+    cfg = get_app_config()
+    uploads_cfg = getattr(cfg, "uploads", None)
+    if isinstance(uploads_cfg, dict):
+        return uploads_cfg.get(key, default)
+    return getattr(uploads_cfg, key, default)
+
+
 def _get_pdf_converter() -> str:
     """Read pdf_converter setting from app config, defaulting to 'auto'.
 
@@ -294,16 +305,11 @@ def _get_pdf_converter() -> str:
     fall through to unexpected behaviour.
     """
     try:
-        from deerflow.config.app_config import get_app_config
-
-        cfg = get_app_config()
-        uploads_cfg = getattr(cfg, "uploads", None)
-        if uploads_cfg is not None:
-            raw = str(getattr(uploads_cfg, "pdf_converter", "auto")).strip().lower()
-            if raw not in _ALLOWED_PDF_CONVERTERS:
-                logger.warning("Invalid pdf_converter value %r; falling back to 'auto'", raw)
-                return "auto"
-            return raw
+        raw = str(_get_uploads_config_value("pdf_converter", "auto")).strip().lower()
+        if raw not in _ALLOWED_PDF_CONVERTERS:
+            logger.warning("Invalid pdf_converter value %r; falling back to 'auto'", raw)
+            return "auto"
+        return raw
     except Exception:
         pass
     return "auto"

backend/pyproject.toml

@@ -8,7 +8,7 @@ dependencies = [
     "deerflow-harness",
     "fastapi>=0.115.0",
     "httpx>=0.28.0",
-    "python-multipart>=0.0.20",
+    "python-multipart>=0.0.26",
     "sse-starlette>=2.1.0",
     "uvicorn[standard]>=0.34.0",
     "lark-oapi>=1.4.0",
@@ -20,7 +20,7 @@ dependencies = [
 ]
 
 [dependency-groups]
-dev = ["pytest>=8.0.0", "ruff>=0.14.11"]
+dev = ["pytest>=9.0.3", "ruff>=0.14.11"]
 
 [tool.uv.workspace]
 members = ["packages/harness"]

backend/tests/test_app_config_reload.py

@@ -6,6 +6,7 @@ from pathlib import Path
 
 import yaml
 
+from deerflow.config.agents_api_config import get_agents_api_config
 from deerflow.config.app_config import get_app_config, reset_app_config
 
 
@@ -28,6 +29,30 @@ def _write_config(path: Path, *, model_name: str, supports_thinking: bool) -> No
     )
 
 
+def _write_config_with_agents_api(
+    path: Path,
+    *,
+    model_name: str,
+    supports_thinking: bool,
+    agents_api: dict | None = None,
+) -> None:
+    config = {
+        "sandbox": {"use": "deerflow.sandbox.local:LocalSandboxProvider"},
+        "models": [
+            {
+                "name": model_name,
+                "use": "langchain_openai:ChatOpenAI",
+                "model": "gpt-test",
+                "supports_thinking": supports_thinking,
+            }
+        ],
+    }
+    if agents_api is not None:
+        config["agents_api"] = agents_api
+
+    path.write_text(yaml.safe_dump(config), encoding="utf-8")
+
+
 def _write_extensions_config(path: Path) -> None:
     path.write_text(json.dumps({"mcpServers": {}, "skills": {}}), encoding="utf-8")
 
@@ -79,3 +104,38 @@ def test_get_app_config_reloads_when_config_path_changes(tmp_path, monkeypatch):
         assert second is not first
     finally:
         reset_app_config()
+
+
+def test_get_app_config_resets_agents_api_config_when_section_removed(tmp_path, monkeypatch):
+    config_path = tmp_path / "config.yaml"
+    extensions_path = tmp_path / "extensions_config.json"
+    _write_extensions_config(extensions_path)
+    _write_config_with_agents_api(
+        config_path,
+        model_name="first-model",
+        supports_thinking=False,
+        agents_api={"enabled": True},
+    )
+
+    monkeypatch.setenv("DEER_FLOW_CONFIG_PATH", str(config_path))
+    monkeypatch.setenv("DEER_FLOW_EXTENSIONS_CONFIG_PATH", str(extensions_path))
+    reset_app_config()
+
+    try:
+        initial = get_app_config()
+        assert initial.models[0].name == "first-model"
+        assert get_agents_api_config().enabled is True
+
+        _write_config_with_agents_api(
+            config_path,
+            model_name="first-model",
+            supports_thinking=False,
+        )
+        next_mtime = config_path.stat().st_mtime + 5
+        os.utime(config_path, (next_mtime, next_mtime))
+
+        reloaded = get_app_config()
+        assert reloaded is not initial
+        assert get_agents_api_config().enabled is False
+    finally:
+        reset_app_config()

backend/tests/test_check_script.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+CHECK_SCRIPT_PATH = REPO_ROOT / "scripts" / "check.py"
+
+
+spec = importlib.util.spec_from_file_location("deerflow_check_script", CHECK_SCRIPT_PATH)
+assert spec is not None
+assert spec.loader is not None
+check_script = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(check_script)
+
+
+def test_find_pnpm_command_prefers_resolved_executable(monkeypatch):
+    def fake_which(name: str) -> str | None:
+        if name == "pnpm":
+            return r"C:\Users\tester\AppData\Roaming\npm\pnpm.CMD"
+        if name == "pnpm.cmd":
+            return r"C:\Users\tester\AppData\Roaming\npm\pnpm.cmd"
+        return None
+
+    monkeypatch.setattr(check_script.shutil, "which", fake_which)
+
+    assert check_script.find_pnpm_command() == [r"C:\Users\tester\AppData\Roaming\npm\pnpm.CMD"]
+
+
+def test_find_pnpm_command_falls_back_to_corepack(monkeypatch):
+    def fake_which(name: str) -> str | None:
+        if name == "corepack":
+            return r"C:\Program Files\nodejs\corepack.exe"
+        return None
+
+    monkeypatch.setattr(check_script.shutil, "which", fake_which)
+
+    assert check_script.find_pnpm_command() == [
+        r"C:\Program Files\nodejs\corepack.exe",
+        "pnpm",
+    ]
+
+
+def test_find_pnpm_command_falls_back_to_corepack_cmd(monkeypatch):
+    def fake_which(name: str) -> str | None:
+        if name == "corepack":
+            return None
+        if name == "corepack.cmd":
+            return r"C:\Program Files\nodejs\corepack.cmd"
+        return None
+
+    monkeypatch.setattr(check_script.shutil, "which", fake_which)
+
+    assert check_script.find_pnpm_command() == [
+        r"C:\Program Files\nodejs\corepack.cmd",
+        "pnpm",
+    ]

backend/tests/test_checkpointer.py

@@ -150,6 +150,79 @@ class TestGetCheckpointer:
         mock_saver_cls.from_conn_string.assert_called_once()
         mock_saver_instance.setup.assert_called_once()
 
+    def test_sqlite_creates_parent_dir(self):
+        """Sync SQLite checkpointer should call ensure_sqlite_parent_dir before connecting.
+
+        This mirrors the async checkpointer's behaviour and prevents
+        'sqlite3.OperationalError: unable to open database file' when the
+        parent directory for the database file does not yet exist (e.g. when
+        using the harness package from an external virtualenv where the
+        .deer-flow directory has not been created).
+        """
+        load_checkpointer_config_from_dict({"type": "sqlite", "connection_string": "relative/test.db"})
+
+        mock_saver_instance = MagicMock()
+        mock_cm = MagicMock()
+        mock_cm.__enter__ = MagicMock(return_value=mock_saver_instance)
+        mock_cm.__exit__ = MagicMock(return_value=False)
+
+        mock_saver_cls = MagicMock()
+        mock_saver_cls.from_conn_string = MagicMock(return_value=mock_cm)
+
+        mock_module = MagicMock()
+        mock_module.SqliteSaver = mock_saver_cls
+
+        with (
+            patch.dict(sys.modules, {"langgraph.checkpoint.sqlite": mock_module}),
+            patch("deerflow.agents.checkpointer.provider.ensure_sqlite_parent_dir") as mock_ensure,
+            patch(
+                "deerflow.agents.checkpointer.provider.resolve_sqlite_conn_str",
+                return_value="/tmp/resolved/relative/test.db",
+            ),
+        ):
+            reset_checkpointer()
+            cp = get_checkpointer()
+
+        assert cp is mock_saver_instance
+        mock_ensure.assert_called_once_with("/tmp/resolved/relative/test.db")
+        mock_saver_cls.from_conn_string.assert_called_once_with("/tmp/resolved/relative/test.db")
+
+    def test_sqlite_ensure_parent_dir_before_connect(self):
+        """ensure_sqlite_parent_dir must be called before from_conn_string."""
+        load_checkpointer_config_from_dict({"type": "sqlite", "connection_string": "relative/test.db"})
+
+        call_order = []
+
+        mock_saver_instance = MagicMock()
+        mock_cm = MagicMock()
+        mock_cm.__enter__ = MagicMock(return_value=mock_saver_instance)
+        mock_cm.__exit__ = MagicMock(return_value=False)
+
+        mock_saver_cls = MagicMock()
+        mock_saver_cls.from_conn_string = MagicMock(side_effect=lambda *a, **kw: (call_order.append("connect"), mock_cm)[1])
+
+        mock_module = MagicMock()
+        mock_module.SqliteSaver = mock_saver_cls
+
+        def record_ensure(*a, **kw):
+            call_order.append("ensure")
+
+        with (
+            patch.dict(sys.modules, {"langgraph.checkpoint.sqlite": mock_module}),
+            patch(
+                "deerflow.agents.checkpointer.provider.ensure_sqlite_parent_dir",
+                side_effect=record_ensure,
+            ),
+            patch(
+                "deerflow.agents.checkpointer.provider.resolve_sqlite_conn_str",
+                return_value="/tmp/resolved/relative/test.db",
+            ),
+        ):
+            reset_checkpointer()
+            get_checkpointer()
+
+        assert call_order == ["ensure", "connect"]
+
     def test_postgres_creates_saver(self):
         """Postgres checkpointer is created when packages are available."""
         load_checkpointer_config_from_dict({"type": "postgres", "connection_string": "postgresql://localhost/db"})

backend/tests/test_client.py

@@ -38,6 +38,7 @@ def mock_app_config():
 
     config = MagicMock()
     config.models = [model]
+    config.token_usage.enabled = False
     return config
 
 
@@ -107,6 +108,7 @@ class TestConfigQueries:
     def test_list_models(self, client):
         result = client.list_models()
         assert "models" in result
+        assert result["token_usage"] == {"enabled": False}
         assert len(result["models"]) == 1
         assert result["models"][0]["name"] == "test-model"
         # Verify Gateway-aligned fields are present
@@ -2196,7 +2198,9 @@ class TestGatewayConformance:
         model.display_name = "Test Model"
         model.description = "A test model"
         model.supports_thinking = False
+        model.supports_reasoning_effort = False
         mock_app_config.models = [model]
+        mock_app_config.token_usage.enabled = True
 
         with patch("deerflow.client.get_app_config", return_value=mock_app_config):
             client = DeerFlowClient()
@@ -2206,6 +2210,7 @@ class TestGatewayConformance:
         assert len(parsed.models) == 1
         assert parsed.models[0].name == "test-model"
         assert parsed.models[0].model == "gpt-test"
+        assert parsed.token_usage.enabled is True
 
     def test_get_model(self, mock_app_config):
         model = MagicMock()

backend/tests/test_custom_agent.py

@@ -9,6 +9,8 @@ import pytest
 import yaml
 from fastapi.testclient import TestClient
 
+from deerflow.config.agents_api_config import AgentsApiConfig, get_agents_api_config, set_agents_api_config
+
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
@@ -387,13 +389,38 @@ def _make_test_app(tmp_path: Path):
 @pytest.fixture()
 def agent_client(tmp_path):
     """TestClient with agents router, using tmp_path as base_dir."""
-    paths_instance = _make_paths(tmp_path)
+    import app.gateway.routers.agents as agents_router
 
-    with patch("deerflow.config.agents_config.get_paths", return_value=paths_instance), patch("app.gateway.routers.agents.get_paths", return_value=paths_instance):
-        app = _make_test_app(tmp_path)
-        with TestClient(app) as client:
-            client._tmp_path = tmp_path  # type: ignore[attr-defined]
-            yield client
+    paths_instance = _make_paths(tmp_path)
+    previous_config = AgentsApiConfig(**get_agents_api_config().model_dump())
+
+    with patch("deerflow.config.agents_config.get_paths", return_value=paths_instance), patch.object(agents_router, "get_paths", return_value=paths_instance):
+        set_agents_api_config(AgentsApiConfig(enabled=True))
+        try:
+            app = _make_test_app(tmp_path)
+            with TestClient(app) as client:
+                client._tmp_path = tmp_path  # type: ignore[attr-defined]
+                yield client
+        finally:
+            set_agents_api_config(previous_config)
+
+
+@pytest.fixture()
+def disabled_agent_client(tmp_path):
+    """TestClient with agents router while the management API is disabled."""
+    import app.gateway.routers.agents as agents_router
+
+    paths_instance = _make_paths(tmp_path)
+    previous_config = AgentsApiConfig(**get_agents_api_config().model_dump())
+
+    with patch("deerflow.config.agents_config.get_paths", return_value=paths_instance), patch.object(agents_router, "get_paths", return_value=paths_instance):
+        set_agents_api_config(AgentsApiConfig(enabled=False))
+        try:
+            app = _make_test_app(tmp_path)
+            with TestClient(app) as client:
+                yield client
+        finally:
+            set_agents_api_config(previous_config)
 
 
 class TestAgentsAPI:
@@ -559,3 +586,37 @@ class TestUserProfileAPI:
         response = agent_client.put("/api/user-profile", json={"content": ""})
         assert response.status_code == 200
         assert response.json()["content"] is None
+
+
+class TestAgentsApiDisabled:
+    def test_agents_list_returns_403(self, disabled_agent_client):
+        response = disabled_agent_client.get("/api/agents")
+        assert response.status_code == 403
+        assert "agents_api.enabled=true" in response.json()["detail"]
+
+    def test_agent_get_returns_403(self, disabled_agent_client):
+        response = disabled_agent_client.get("/api/agents/example-agent")
+        assert response.status_code == 403
+
+    def test_agent_name_check_returns_403(self, disabled_agent_client):
+        response = disabled_agent_client.get("/api/agents/check", params={"name": "example-agent"})
+        assert response.status_code == 403
+
+    def test_agent_create_returns_403(self, disabled_agent_client):
+        response = disabled_agent_client.post("/api/agents", json={"name": "example-agent", "soul": "blocked"})
+        assert response.status_code == 403
+
+    def test_agent_update_returns_403(self, disabled_agent_client):
+        response = disabled_agent_client.put("/api/agents/example-agent", json={"description": "blocked"})
+        assert response.status_code == 403
+
+    def test_agent_delete_returns_403(self, disabled_agent_client):
+        response = disabled_agent_client.delete("/api/agents/example-agent")
+        assert response.status_code == 403
+
+    def test_user_profile_routes_return_403(self, disabled_agent_client):
+        get_response = disabled_agent_client.get("/api/user-profile")
+        put_response = disabled_agent_client.put("/api/user-profile", json={"content": "blocked"})
+
+        assert get_response.status_code == 403
+        assert put_response.status_code == 403

backend/tests/test_dangling_tool_call_middleware.py

@@ -119,6 +119,31 @@ class TestBuildPatchedMessagesPatching:
         assert "interrupted" in tool_msg.content.lower()
         assert tool_msg.name == "bash"
 
+    def test_raw_provider_tool_calls_are_patched(self):
+        mw = DanglingToolCallMiddleware()
+        msgs = [
+            AIMessage(
+                content="",
+                tool_calls=[],
+                additional_kwargs={
+                    "tool_calls": [
+                        {
+                            "id": "call_1",
+                            "type": "function",
+                            "function": {"name": "bash", "arguments": '{"command":"ls"}'},
+                        }
+                    ]
+                },
+            )
+        ]
+        patched = mw._build_patched_messages(msgs)
+        assert patched is not None
+        assert len(patched) == 2
+        assert isinstance(patched[1], ToolMessage)
+        assert patched[1].tool_call_id == "call_1"
+        assert patched[1].name == "bash"
+        assert patched[1].status == "error"
+
 
 class TestWrapModelCall:
     def test_no_patch_passthrough(self):

backend/tests/test_file_conversion.py

@@ -12,6 +12,7 @@ from deerflow.utils.file_conversion import (
     _MIN_CHARS_PER_PAGE,
     MAX_OUTLINE_ENTRIES,
     _do_convert,
+    _get_pdf_converter,
     _pymupdf_output_too_sparse,
     convert_file_to_markdown,
     extract_outline,
@@ -214,9 +215,27 @@ class TestDoConvert:
         assert result == "MarkItDown fallback"
 
 
-# ---------------------------------------------------------------------------
-# convert_file_to_markdown — async + file writing
-# ---------------------------------------------------------------------------
+class TestGetPdfConverter:
+    def test_reads_dict_backed_uploads_config(self):
+        cfg = MagicMock()
+        cfg.uploads = {"pdf_converter": "markitdown"}
+
+        with patch("deerflow.utils.file_conversion.get_app_config", return_value=cfg):
+            assert _get_pdf_converter() == "markitdown"
+
+    def test_reads_attribute_backed_uploads_config(self):
+        cfg = MagicMock()
+        cfg.uploads = MagicMock(pdf_converter="pymupdf4llm")
+
+        with patch("deerflow.utils.file_conversion.get_app_config", return_value=cfg):
+            assert _get_pdf_converter() == "pymupdf4llm"
+
+    def test_invalid_value_falls_back_to_auto(self):
+        cfg = MagicMock()
+        cfg.uploads = {"pdf_converter": "not-a-real-converter"}
+
+        with patch("deerflow.utils.file_conversion.get_app_config", return_value=cfg):
+            assert _get_pdf_converter() == "auto"
 
 
 class TestConvertFileToMarkdown:

backend/tests/test_jina_client.py

@@ -175,3 +175,30 @@ async def test_web_fetch_tool_returns_markdown_on_success(monkeypatch):
     result = await web_fetch_tool.ainvoke("https://example.com")
     assert "Hello world" in result
     assert not result.startswith("Error:")
+
+
+@pytest.mark.anyio
+async def test_web_fetch_tool_offloads_extraction_to_thread(monkeypatch):
+    """Test that readability extraction is offloaded via asyncio.to_thread to avoid blocking the event loop."""
+    import asyncio
+
+    async def mock_crawl(self, url, **kwargs):
+        return "<html><body><p>threaded</p></body></html>"
+
+    mock_config = MagicMock()
+    mock_config.get_tool_config.return_value = None
+    monkeypatch.setattr("deerflow.community.jina_ai.tools.get_app_config", lambda: mock_config)
+    monkeypatch.setattr(JinaClient, "crawl", mock_crawl)
+
+    to_thread_called = False
+    original_to_thread = asyncio.to_thread
+
+    async def tracking_to_thread(func, *args, **kwargs):
+        nonlocal to_thread_called
+        to_thread_called = True
+        return await original_to_thread(func, *args, **kwargs)
+
+    monkeypatch.setattr("deerflow.community.jina_ai.tools.asyncio.to_thread", tracking_to_thread)
+    result = await web_fetch_tool.ainvoke("https://example.com")
+    assert to_thread_called, "extract_article must be called via asyncio.to_thread to avoid blocking the event loop"
+    assert "threaded" in result

backend/tests/test_lead_agent_model_resolution.py

@@ -8,6 +8,7 @@ import pytest
 
 from deerflow.agents.lead_agent import agent as lead_agent_module
 from deerflow.config.app_config import AppConfig
+from deerflow.config.memory_config import MemoryConfig
 from deerflow.config.model_config import ModelConfig
 from deerflow.config.sandbox_config import SandboxConfig
 from deerflow.config.summarization_config import SummarizationConfig
@@ -112,6 +113,26 @@ def test_make_lead_agent_disables_thinking_when_model_does_not_support_it(monkey
     assert result["model"] is not None
 
 
+def test_make_lead_agent_rejects_invalid_bootstrap_agent_name(monkeypatch):
+    app_config = _make_app_config([_make_model("safe-model", supports_thinking=False)])
+
+    monkeypatch.setattr(lead_agent_module, "get_app_config", lambda: app_config)
+
+    with pytest.raises(ValueError, match="Invalid agent name"):
+        lead_agent_module.make_lead_agent(
+            {
+                "configurable": {
+                    "model_name": "safe-model",
+                    "thinking_enabled": False,
+                    "is_plan_mode": False,
+                    "subagent_enabled": False,
+                    "is_bootstrap": True,
+                    "agent_name": "../../../tmp/evil",
+                }
+            }
+        )
+
+
 def test_build_middlewares_uses_resolved_model_name_for_vision(monkeypatch):
     app_config = _make_app_config(
         [
@@ -145,6 +166,7 @@ def test_create_summarization_middleware_uses_configured_model_alias(monkeypatch
         "get_summarization_config",
         lambda: SummarizationConfig(enabled=True, model_name="model-masswork"),
     )
+    monkeypatch.setattr(lead_agent_module, "get_memory_config", lambda: MemoryConfig(enabled=False))
 
     captured: dict[str, object] = {}
     fake_model = object()
@@ -156,10 +178,32 @@ def test_create_summarization_middleware_uses_configured_model_alias(monkeypatch
         return fake_model
 
     monkeypatch.setattr(lead_agent_module, "create_chat_model", _fake_create_chat_model)
-    monkeypatch.setattr(lead_agent_module, "SummarizationMiddleware", lambda **kwargs: kwargs)
+    monkeypatch.setattr(lead_agent_module, "DeerFlowSummarizationMiddleware", lambda **kwargs: kwargs)
 
     middleware = lead_agent_module._create_summarization_middleware()
 
     assert captured["name"] == "model-masswork"
     assert captured["thinking_enabled"] is False
     assert middleware["model"] is fake_model
+
+
+def test_create_summarization_middleware_registers_memory_flush_hook_when_memory_enabled(monkeypatch):
+    monkeypatch.setattr(
+        lead_agent_module,
+        "get_summarization_config",
+        lambda: SummarizationConfig(enabled=True),
+    )
+    monkeypatch.setattr(lead_agent_module, "get_memory_config", lambda: MemoryConfig(enabled=True))
+    monkeypatch.setattr(lead_agent_module, "create_chat_model", lambda **kwargs: object())
+
+    captured: dict[str, object] = {}
+
+    def _fake_middleware(**kwargs):
+        captured.update(kwargs)
+        return kwargs
+
+    monkeypatch.setattr(lead_agent_module, "DeerFlowSummarizationMiddleware", _fake_middleware)
+
+    lead_agent_module._create_summarization_middleware()
+
+    assert captured["before_summarization"] == [lead_agent_module.memory_flush_hook]

backend/tests/test_llm_error_handling_middleware.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 from types import SimpleNamespace
+from typing import Any
 
 import pytest
 from langchain_core.messages import AIMessage
@@ -134,3 +135,227 @@ def test_async_model_call_propagates_graph_bubble_up() -> None:
 
     with pytest.raises(GraphBubbleUp):
         asyncio.run(middleware.awrap_model_call(SimpleNamespace(), handler))
+
+
+def test_circuit_half_open_graph_bubble_up_resets_probe() -> None:
+    """Verify that GraphBubbleUp in half_open state resets probe_in_flight."""
+    middleware = _build_middleware()
+
+    # Step 1: Manually set state to half_open and check_circuit() to set probe_in_flight=True
+    middleware._circuit_state = "half_open"
+    middleware._circuit_probe_in_flight = False
+    # Call _check_circuit() once to simulate the probe being allowed through
+    assert middleware._check_circuit() is False
+    assert middleware._circuit_probe_in_flight is True
+
+    # Step 2: Now trigger handler that raises GraphBubbleUp
+    def handler(_request) -> AIMessage:
+        raise GraphBubbleUp()
+
+    # Mock _check_circuit() to return False (since we already did the probe check)
+    import unittest.mock
+
+    with unittest.mock.patch.object(middleware, "_check_circuit", return_value=False):
+        with pytest.raises(GraphBubbleUp):
+            middleware.wrap_model_call(SimpleNamespace(), handler)
+
+    # Verify probe_in_flight was reset, state should remain half_open
+    assert middleware._circuit_probe_in_flight is False
+    assert middleware._circuit_state == "half_open"
+
+
+@pytest.mark.anyio
+async def test_async_circuit_half_open_graph_bubble_up_resets_probe() -> None:
+    """Verify that GraphBubbleUp in half_open state resets probe_in_flight (async version)."""
+    middleware = _build_middleware()
+
+    # Step 1: Manually set state to half_open and check_circuit() to set probe_in_flight=True
+    middleware._circuit_state = "half_open"
+    middleware._circuit_probe_in_flight = False
+    # Call _check_circuit() once to simulate the probe being allowed through
+    assert middleware._check_circuit() is False
+    assert middleware._circuit_probe_in_flight is True
+
+    # Step 2: Now trigger handler that raises GraphBubbleUp
+    async def handler(_request) -> AIMessage:
+        raise GraphBubbleUp()
+
+    # Mock _check_circuit() to return False (since we already did the probe check)
+    import unittest.mock
+
+    with unittest.mock.patch.object(middleware, "_check_circuit", return_value=False):
+        with pytest.raises(GraphBubbleUp):
+            await middleware.awrap_model_call(SimpleNamespace(), handler)
+
+    # Verify probe_in_flight was reset, state should remain half_open
+    assert middleware._circuit_probe_in_flight is False
+    assert middleware._circuit_state == "half_open"
+
+
+# ---------- Circuit Breaker Tests ----------
+
+
+def transient_failing_handler(request: Any) -> Any:
+    raise FakeError("Server Error", status_code=502)  # Used for transient error
+
+
+def quota_failing_handler(request: Any) -> Any:
+    raise FakeError("Quota exceeded", body={"error": {"code": "insufficient_quota"}})  # Used for quota error
+
+
+def success_handler(request: Any) -> Any:
+    return AIMessage(content="Success")
+
+
+def mock_classify_retriable(exc: BaseException) -> tuple[bool, str]:
+    return True, "transient"
+
+
+def mock_classify_non_retriable(exc: BaseException) -> tuple[bool, str]:
+    return False, "quota"
+
+
+def test_circuit_breaker_trips_and_recovers(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Verify that circuit breaker trips, fast fails, correctly transitions to Half-Open, and recovers or re-opens."""
+
+    # Mock time.sleep to avoid slow tests during retry loops (Speed up from ~4s to 0.1s)
+    waits: list[float] = []
+    monkeypatch.setattr("time.sleep", lambda d: waits.append(d))
+
+    # Mock time.time to decouple from private implementation details and enable time travel
+    current_time = 1000.0
+    monkeypatch.setattr("time.time", lambda: current_time)
+
+    middleware = LLMErrorHandlingMiddleware()
+    middleware.circuit_failure_threshold = 3
+    middleware.circuit_recovery_timeout_sec = 10
+    monkeypatch.setattr(middleware, "_classify_error", mock_classify_retriable)
+
+    request: Any = {"messages": []}
+
+    # --- 0. Test initial state & Success ---
+    # Success handler does not increase count. If it's already 0, it stays 0.
+    middleware.wrap_model_call(request, success_handler)
+    assert middleware._circuit_failure_count == 0
+    assert middleware._check_circuit() is False
+
+    # --- 1. Trip the circuit ---
+    # Fails 3 overall calls. Threshold (3) is reached.
+    middleware.wrap_model_call(request, transient_failing_handler)
+    assert middleware._circuit_failure_count == 1
+    middleware.wrap_model_call(request, transient_failing_handler)
+    assert middleware._circuit_failure_count == 2
+    middleware.wrap_model_call(request, transient_failing_handler)
+    assert middleware._circuit_failure_count == 3
+    assert middleware._check_circuit() is True  # Circuit is OPEN
+
+    # --- 2. Fast Fail ---
+    # 2nd call: fast fail immediately without calling handler.
+    # Count should not increase during OPEN state.
+    result = middleware.wrap_model_call(request, success_handler)
+    assert result.content == middleware._build_circuit_breaker_message()
+    assert middleware._circuit_failure_count == 3
+
+    # --- 3. Half-Open -> Fail -> Re-Open ---
+    # Time travel 11 seconds (timeout is 10s). Current time becomes 1011.0
+    current_time += 11.0
+
+    # Verify that the timeout was set EXACTLY relative to current_time + timeout_sec
+    assert middleware._circuit_open_until == current_time - 11.0 + middleware.circuit_recovery_timeout_sec
+
+    # Fails again! The request will go through the 3-attempt retry loop again.
+    middleware.wrap_model_call(request, transient_failing_handler)
+    assert middleware._circuit_failure_count == middleware.circuit_failure_threshold
+    assert middleware._circuit_state == "open"  # Re-OPENed
+
+    # --- 4. Half-Open -> Success -> Reset ---
+    # Time travel another 11 seconds
+    current_time += 11.0
+
+    # Succeeds this time! Should completely reset.
+    result = middleware.wrap_model_call(request, success_handler)
+    assert result.content == "Success"
+    assert middleware._circuit_failure_count == 0  # Fully RESET!
+    assert middleware._check_circuit() is False
+
+
+def test_circuit_breaker_does_not_trip_on_non_retriable_errors(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Verify that circuit breaker ignores business errors like Quota or Auth."""
+    waits: list[float] = []
+    monkeypatch.setattr("time.sleep", lambda d: waits.append(d))
+
+    middleware = LLMErrorHandlingMiddleware()
+    middleware.circuit_failure_threshold = 3
+    monkeypatch.setattr(middleware, "_classify_error", mock_classify_non_retriable)
+
+    request: Any = {"messages": []}
+
+    for _ in range(3):
+        middleware.wrap_model_call(request, quota_failing_handler)
+
+    assert middleware._circuit_failure_count == 0
+    assert middleware._check_circuit() is False
+
+
+@pytest.mark.anyio
+async def test_async_circuit_breaker_trips_and_recovers(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Verify async version of circuit breaker correctly handles state transitions."""
+    waits: list[float] = []
+
+    async def fake_sleep(d: float) -> None:
+        waits.append(d)
+
+    monkeypatch.setattr(asyncio, "sleep", fake_sleep)
+
+    current_time = 1000.0
+    monkeypatch.setattr("time.time", lambda: current_time)
+
+    middleware = LLMErrorHandlingMiddleware()
+    middleware.circuit_failure_threshold = 3
+    middleware.circuit_recovery_timeout_sec = 10
+    monkeypatch.setattr(middleware, "_classify_error", mock_classify_retriable)
+
+    async def async_failing_handler(request: Any) -> Any:
+        raise FakeError("Server Error", status_code=502)
+
+    request: Any = {"messages": []}
+
+    # --- 1. Trip the circuit ---
+    # Fails 3 overall calls. Threshold (3) is reached.
+    await middleware.awrap_model_call(request, async_failing_handler)
+    assert middleware._circuit_failure_count == 1
+    await middleware.awrap_model_call(request, async_failing_handler)
+    assert middleware._circuit_failure_count == 2
+    await middleware.awrap_model_call(request, async_failing_handler)
+    assert middleware._circuit_failure_count == 3
+    assert middleware._check_circuit() is True
+
+    # --- 2. Fast Fail ---
+    # 2nd call: fast fail immediately without calling handler
+    async def async_success_handler(request: Any) -> Any:
+        return AIMessage(content="Success")
+
+    result = await middleware.awrap_model_call(request, async_success_handler)
+    assert result.content == middleware._build_circuit_breaker_message()
+    assert middleware._circuit_failure_count == 3  # Unchanged
+
+    # --- 3. Half-Open -> Fail -> Re-Open ---
+    # Time travel 11 seconds
+    current_time += 11.0
+
+    # Verify timeout formula
+    assert middleware._circuit_open_until == current_time - 11.0 + middleware.circuit_recovery_timeout_sec
+
+    # Fails again! The request goes through the 3-attempt retry loop.
+    await middleware.awrap_model_call(request, async_failing_handler)
+    assert middleware._circuit_failure_count == middleware.circuit_failure_threshold
+    assert middleware._circuit_state == "open"  # Re-OPENed
+
+    # --- 4. Half-Open -> Success -> Reset ---
+    # Time travel another 11 seconds
+    current_time += 11.0
+
+    result = await middleware.awrap_model_call(request, async_success_handler)
+    assert result.content == "Success"
+    assert middleware._circuit_failure_count == 0  # RESET
+    assert middleware._check_circuit() is False

backend/tests/test_loop_detection_middleware.py

@@ -413,6 +413,45 @@ class TestHardStopWithListContent:
         assert msg.content.startswith("thinking...")
         assert _HARD_STOP_MSG in msg.content
 
+    def test_hard_stop_clears_raw_tool_call_metadata(self):
+        """Forced-stop messages must not retain provider-level raw tool-call payloads."""
+        mw = LoopDetectionMiddleware(warn_threshold=2, hard_limit=4)
+        runtime = _make_runtime()
+        call = [_bash_call("ls")]
+
+        def _make_provider_state():
+            return {
+                "messages": [
+                    AIMessage(
+                        content="thinking...",
+                        tool_calls=call,
+                        additional_kwargs={
+                            "tool_calls": [
+                                {
+                                    "id": "call_ls",
+                                    "type": "function",
+                                    "function": {"name": "bash", "arguments": '{"command":"ls"}'},
+                                    "thought_signature": "sig-1",
+                                }
+                            ],
+                            "function_call": {"name": "bash", "arguments": '{"command":"ls"}'},
+                        },
+                        response_metadata={"finish_reason": "tool_calls"},
+                    )
+                ]
+            }
+
+        for _ in range(3):
+            mw._apply(_make_provider_state(), runtime)
+
+        result = mw._apply(_make_provider_state(), runtime)
+        assert result is not None
+        msg = result["messages"][0]
+        assert msg.tool_calls == []
+        assert "tool_calls" not in msg.additional_kwargs
+        assert "function_call" not in msg.additional_kwargs
+        assert msg.response_metadata["finish_reason"] == "stop"
+
 
 class TestToolFrequencyDetection:
     """Tests for per-tool-type frequency detection (Layer 2).

backend/tests/test_memory_queue.py

@@ -1,3 +1,5 @@
+import threading
+import time
 from unittest.mock import MagicMock, patch
 
 from deerflow.agents.memory.queue import ConversationContext, MemoryUpdateQueue
@@ -89,3 +91,74 @@ def test_process_queue_forwards_reinforcement_flag_to_updater() -> None:
         correction_detected=False,
         reinforcement_detected=True,
     )
+
+
+def test_flush_nowait_cancels_existing_timer_and_starts_immediate_timer() -> None:
+    queue = MemoryUpdateQueue()
+    existing_timer = MagicMock()
+    queue._timer = existing_timer
+    created_timer = MagicMock()
+
+    with patch("deerflow.agents.memory.queue.threading.Timer", return_value=created_timer) as timer_cls:
+        queue.flush_nowait()
+
+    existing_timer.cancel.assert_called_once_with()
+    timer_cls.assert_called_once_with(0, queue._process_queue)
+    assert created_timer.daemon is True
+    created_timer.start.assert_called_once_with()
+    assert queue._timer is created_timer
+
+
+def test_add_nowait_cancels_existing_timer_and_starts_immediate_timer() -> None:
+    queue = MemoryUpdateQueue()
+    existing_timer = MagicMock()
+    queue._timer = existing_timer
+    created_timer = MagicMock()
+
+    with (
+        patch("deerflow.agents.memory.queue.get_memory_config", return_value=_memory_config(enabled=True)),
+        patch("deerflow.agents.memory.queue.threading.Timer", return_value=created_timer) as timer_cls,
+    ):
+        queue.add_nowait(thread_id="thread-1", messages=["conversation"], agent_name="lead-agent")
+
+    existing_timer.cancel.assert_called_once_with()
+    timer_cls.assert_called_once_with(0, queue._process_queue)
+    assert queue.pending_count == 1
+    assert queue._queue[0].agent_name == "lead-agent"
+    assert created_timer.daemon is True
+    created_timer.start.assert_called_once_with()
+
+
+def test_process_queue_reschedules_immediately_when_already_processing() -> None:
+    queue = MemoryUpdateQueue()
+    queue._processing = True
+    created_timer = MagicMock()
+
+    with patch("deerflow.agents.memory.queue.threading.Timer", return_value=created_timer) as timer_cls:
+        queue._process_queue()
+
+    timer_cls.assert_called_once_with(0, queue._process_queue)
+    assert created_timer.daemon is True
+    created_timer.start.assert_called_once_with()
+
+
+def test_flush_nowait_is_non_blocking() -> None:
+    queue = MemoryUpdateQueue()
+    started = threading.Event()
+    finished = threading.Event()
+
+    def _slow_process_queue() -> None:
+        started.set()
+        time.sleep(0.2)
+        finished.set()
+
+    queue._process_queue = _slow_process_queue
+
+    start = time.perf_counter()
+    queue.flush_nowait()
+    elapsed = time.perf_counter() - start
+
+    assert started.wait(0.1) is True
+    assert elapsed < 0.1
+    assert finished.is_set() is False
+    assert finished.wait(1.0) is True

backend/tests/test_memory_storage.py

@@ -110,6 +110,93 @@ class TestFileMemoryStorage:
                 assert result is True
                 assert memory_file.exists()
 
+    def test_save_does_not_mutate_caller_dict(self, tmp_path):
+        """save() must not mutate the caller's dict (lastUpdated side-effect)."""
+        memory_file = tmp_path / "memory.json"
+
+        def mock_get_paths():
+            mock_paths = MagicMock()
+            mock_paths.memory_file = memory_file
+            return mock_paths
+
+        with patch("deerflow.agents.memory.storage.get_paths", side_effect=mock_get_paths):
+            with patch("deerflow.agents.memory.storage.get_memory_config", return_value=MemoryConfig(storage_path="")):
+                storage = FileMemoryStorage()
+                original = {"version": "1.0", "facts": []}
+                before_keys = set(original.keys())
+                storage.save(original)
+                assert set(original.keys()) == before_keys, "save() must not add keys to caller's dict"
+                assert "lastUpdated" not in original
+
+    def test_cache_not_corrupted_when_save_fails(self, tmp_path):
+        """Cache must remain clean when save() raises OSError.
+
+        If save() fails, the cache must NOT be updated with the new data.
+        Together with the deepcopy in updater._finalize_update(), this prevents
+        stale mutations from leaking into the cache when persistence fails.
+        """
+        memory_file = tmp_path / "memory.json"
+        memory_file.parent.mkdir(parents=True, exist_ok=True)
+        original_data = {"version": "1.0", "facts": [{"content": "original"}]}
+        import json as _json
+
+        memory_file.write_text(_json.dumps(original_data))
+
+        def mock_get_paths():
+            mock_paths = MagicMock()
+            mock_paths.memory_file = memory_file
+            return mock_paths
+
+        with patch("deerflow.agents.memory.storage.get_paths", side_effect=mock_get_paths):
+            with patch("deerflow.agents.memory.storage.get_memory_config", return_value=MemoryConfig(storage_path="")):
+                storage = FileMemoryStorage()
+                # Warm the cache
+                cached = storage.load()
+                assert cached["facts"][0]["content"] == "original"
+
+                # Simulate save failure: mkdir succeeds but open() raises
+                modified = {"version": "1.0", "facts": [{"content": "mutated"}]}
+                with patch("builtins.open", side_effect=OSError("disk full")):
+                    result = storage.save(modified)
+                assert result is False
+
+                # Cache must still reflect the original data, not the failed write
+                after = storage.load()
+                assert after["facts"][0]["content"] == "original"
+
+    def test_cache_thread_safety(self, tmp_path):
+        """Concurrent load/reload calls must not race on _memory_cache."""
+        memory_file = tmp_path / "memory.json"
+        memory_file.parent.mkdir(parents=True, exist_ok=True)
+        import json as _json
+
+        memory_file.write_text(_json.dumps({"version": "1.0", "facts": []}))
+
+        def mock_get_paths():
+            mock_paths = MagicMock()
+            mock_paths.memory_file = memory_file
+            return mock_paths
+
+        errors: list[Exception] = []
+
+        def load_many(storage: FileMemoryStorage) -> None:
+            try:
+                for _ in range(50):
+                    storage.load()
+            except Exception as exc:
+                errors.append(exc)
+
+        with patch("deerflow.agents.memory.storage.get_paths", side_effect=mock_get_paths):
+            with patch("deerflow.agents.memory.storage.get_memory_config", return_value=MemoryConfig(storage_path="")):
+                storage = FileMemoryStorage()
+                threads = [threading.Thread(target=load_many, args=(storage,)) for _ in range(8)]
+                for t in threads:
+                    t.start()
+                for t in threads:
+                    t.join()
+
+        assert not errors, f"Thread-safety errors: {errors}"
+
     def test_reload_forces_cache_invalidation(self, tmp_path):
         """Should force reload from file and invalidate cache."""
         memory_file = tmp_path / "memory.json"

backend/tests/test_memory_updater.py

@@ -1,9 +1,13 @@
-from unittest.mock import MagicMock, patch
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
 
 from deerflow.agents.memory.prompt import format_conversation_for_update
 from deerflow.agents.memory.updater import (
     MemoryUpdater,
     _extract_text,
+    _run_async_update_sync,
     clear_memory_data,
     create_memory_fact,
     delete_memory_fact,
@@ -523,15 +527,16 @@ class TestUpdateMemoryStructuredResponse:
         model = MagicMock()
         response = MagicMock()
         response.content = content
-        model.invoke.return_value = response
+        model.ainvoke = AsyncMock(return_value=response)
         return model
 
     def test_string_response_parses(self):
         updater = MemoryUpdater()
         valid_json = '{"user": {}, "history": {}, "newFacts": [], "factsToRemove": []}'
+        model = self._make_mock_model(valid_json)
 
         with (
-            patch.object(updater, "_get_model", return_value=self._make_mock_model(valid_json)),
+            patch.object(updater, "_get_model", return_value=model),
             patch("deerflow.agents.memory.updater.get_memory_config", return_value=_memory_config(enabled=True)),
             patch("deerflow.agents.memory.updater.get_memory_data", return_value=_make_memory()),
             patch("deerflow.agents.memory.updater.get_memory_storage", return_value=MagicMock(save=MagicMock(return_value=True))),
@@ -546,6 +551,7 @@ class TestUpdateMemoryStructuredResponse:
             result = updater.update_memory([msg, ai_msg])
 
         assert result is True
+        model.ainvoke.assert_awaited_once()
 
     def test_list_content_response_parses(self):
         """LLM response as list-of-blocks should be extracted, not repr'd."""
@@ -570,6 +576,29 @@ class TestUpdateMemoryStructuredResponse:
 
         assert result is True
 
+    def test_async_update_memory_uses_ainvoke(self):
+        updater = MemoryUpdater()
+        valid_json = '{"user": {}, "history": {}, "newFacts": [], "factsToRemove": []}'
+        model = self._make_mock_model(valid_json)
+
+        with (
+            patch.object(updater, "_get_model", return_value=model),
+            patch("deerflow.agents.memory.updater.get_memory_config", return_value=_memory_config(enabled=True)),
+            patch("deerflow.agents.memory.updater.get_memory_data", return_value=_make_memory()),
+            patch("deerflow.agents.memory.updater.get_memory_storage", return_value=MagicMock(save=MagicMock(return_value=True))),
+        ):
+            msg = MagicMock()
+            msg.type = "human"
+            msg.content = "Hello"
+            ai_msg = MagicMock()
+            ai_msg.type = "ai"
+            ai_msg.content = "Hi there"
+            ai_msg.tool_calls = []
+            result = asyncio.run(updater.aupdate_memory([msg, ai_msg]))
+
+        assert result is True
+        model.ainvoke.assert_awaited_once()
+
     def test_correction_hint_injected_when_detected(self):
         updater = MemoryUpdater()
         valid_json = '{"user": {}, "history": {}, "newFacts": [], "factsToRemove": []}'
@@ -592,7 +621,7 @@ class TestUpdateMemoryStructuredResponse:
             result = updater.update_memory([msg, ai_msg], correction_detected=True)
 
         assert result is True
-        prompt = model.invoke.call_args[0][0]
+        prompt = model.ainvoke.await_args.args[0]
         assert "Explicit correction signals were detected" in prompt
 
     def test_correction_hint_empty_when_not_detected(self):
@@ -617,9 +646,89 @@ class TestUpdateMemoryStructuredResponse:
             result = updater.update_memory([msg, ai_msg], correction_detected=False)
 
         assert result is True
-        prompt = model.invoke.call_args[0][0]
+        prompt = model.ainvoke.await_args.args[0]
         assert "Explicit correction signals were detected" not in prompt
 
+    def test_sync_update_memory_wrapper_works_in_running_loop(self):
+        updater = MemoryUpdater()
+        valid_json = '{"user": {}, "history": {}, "newFacts": [], "factsToRemove": []}'
+        model = self._make_mock_model(valid_json)
+
+        with (
+            patch.object(updater, "_get_model", return_value=model),
+            patch("deerflow.agents.memory.updater.get_memory_config", return_value=_memory_config(enabled=True)),
+            patch("deerflow.agents.memory.updater.get_memory_data", return_value=_make_memory()),
+            patch("deerflow.agents.memory.updater.get_memory_storage", return_value=MagicMock(save=MagicMock(return_value=True))),
+        ):
+            msg = MagicMock()
+            msg.type = "human"
+            msg.content = "Hello from loop"
+            ai_msg = MagicMock()
+            ai_msg.type = "ai"
+            ai_msg.content = "Hi"
+            ai_msg.tool_calls = []
+
+            async def run_in_loop():
+                return updater.update_memory([msg, ai_msg])
+
+            result = asyncio.run(run_in_loop())
+
+        assert result is True
+        model.ainvoke.assert_awaited_once()
+
+    def test_sync_update_memory_returns_false_when_bridge_submit_fails(self):
+        updater = MemoryUpdater()
+
+        with (
+            patch(
+                "deerflow.agents.memory.updater._SYNC_MEMORY_UPDATER_EXECUTOR.submit",
+                side_effect=RuntimeError("executor down"),
+            ),
+        ):
+            msg = MagicMock()
+            msg.type = "human"
+            msg.content = "Hello from loop"
+            ai_msg = MagicMock()
+            ai_msg.type = "ai"
+            ai_msg.content = "Hi"
+            ai_msg.tool_calls = []
+
+            async def run_in_loop():
+                return updater.update_memory([msg, ai_msg])
+
+            result = asyncio.run(run_in_loop())
+
+        assert result is False
+
+
+class TestRunAsyncUpdateSync:
+    def test_closes_unawaited_awaitable_when_bridge_fails_before_handoff(self):
+        class CloseableAwaitable:
+            def __init__(self):
+                self.closed = False
+
+            def __await__(self):
+                pytest.fail("awaitable should not have been awaited")
+                yield
+
+            def close(self):
+                self.closed = True
+
+        awaitable = CloseableAwaitable()
+
+        with patch(
+            "deerflow.agents.memory.updater._SYNC_MEMORY_UPDATER_EXECUTOR.submit",
+            side_effect=RuntimeError("executor down"),
+        ):
+
+            async def run_in_loop():
+                return _run_async_update_sync(awaitable)
+
+            result = asyncio.run(run_in_loop())
+
+        assert result is False
+        assert awaitable.closed is True
+
 
 class TestFactDeduplicationCaseInsensitive:
     """Tests that fact deduplication is case-insensitive."""
@@ -694,7 +803,7 @@ class TestReinforcementHint:
         model = MagicMock()
         response = MagicMock()
         response.content = f"```json\n{json_response}\n```"
-        model.invoke.return_value = response
+        model.ainvoke = AsyncMock(return_value=response)
         return model
 
     def test_reinforcement_hint_injected_when_detected(self):
@@ -719,7 +828,7 @@ class TestReinforcementHint:
             result = updater.update_memory([msg, ai_msg], reinforcement_detected=True)
 
         assert result is True
-        prompt = model.invoke.call_args[0][0]
+        prompt = model.ainvoke.await_args.args[0]
         assert "Positive reinforcement signals were detected" in prompt
 
     def test_reinforcement_hint_absent_when_not_detected(self):
@@ -744,7 +853,7 @@ class TestReinforcementHint:
             result = updater.update_memory([msg, ai_msg], reinforcement_detected=False)
 
         assert result is True
-        prompt = model.invoke.call_args[0][0]
+        prompt = model.ainvoke.await_args.args[0]
         assert "Positive reinforcement signals were detected" not in prompt
 
     def test_both_hints_present_when_both_detected(self):
@@ -769,6 +878,56 @@ class TestReinforcementHint:
             result = updater.update_memory([msg, ai_msg], correction_detected=True, reinforcement_detected=True)
 
         assert result is True
-        prompt = model.invoke.call_args[0][0]
+        prompt = model.ainvoke.await_args.args[0]
         assert "Explicit correction signals were detected" in prompt
         assert "Positive reinforcement signals were detected" in prompt
+
+
+class TestFinalizeCacheIsolation:
+    """_finalize_update must not mutate the cached memory object."""
+
+    def test_deepcopy_prevents_cache_corruption_on_save_failure(self):
+        """If save() fails, the in-memory snapshot used by _finalize_update
+        must remain independent of any object the storage layer may still hold in
+        its cache.  The deepcopy in _finalize_update achieves this — the object
+        passed to _apply_updates is always a fresh copy, never the cache reference.
+        """
+        updater = MemoryUpdater()
+        original_memory = _make_memory(facts=[{"id": "fact_orig", "content": "original", "category": "context", "confidence": 0.9, "createdAt": "2024-01-01T00:00:00Z", "source": "t1"}])
+
+        import json as _json
+
+        new_fact_json = _json.dumps(
+            {
+                "user": {},
+                "history": {},
+                "newFacts": [{"content": "new fact", "category": "context", "confidence": 0.9}],
+                "factsToRemove": [],
+            }
+        )
+        mock_response = MagicMock()
+        mock_response.content = new_fact_json
+        mock_model = AsyncMock()
+        mock_model.ainvoke = AsyncMock(return_value=mock_response)
+
+        saved_objects: list[dict] = []
+        save_mock = MagicMock(side_effect=lambda m, a=None: saved_objects.append(m) or False)  # always fails
+
+        with (
+            patch.object(updater, "_get_model", return_value=mock_model),
+            patch("deerflow.agents.memory.updater.get_memory_config", return_value=_memory_config(enabled=True, fact_confidence_threshold=0.7)),
+            patch("deerflow.agents.memory.updater.get_memory_data", return_value=original_memory),
+            patch("deerflow.agents.memory.updater.get_memory_storage", return_value=MagicMock(save=save_mock)),
+        ):
+            msg = MagicMock()
+            msg.type = "human"
+            msg.content = "hello"
+            ai_msg = MagicMock()
+            ai_msg.type = "ai"
+            ai_msg.content = "world"
+            ai_msg.tool_calls = []
+            updater.update_memory([msg, ai_msg], thread_id="t1")
+
+        # original_memory must not have been mutated — deepcopy isolates the mutation
+        assert len(original_memory["facts"]) == 1, "original_memory must not be mutated by _apply_updates"
+        assert original_memory["facts"][0]["content"] == "original"

backend/tests/test_memory_upload_filtering.py

@@ -3,14 +3,14 @@
 Covers two functions introduced to prevent ephemeral file-upload context from
 persisting in long-term memory:
 
-  - _filter_messages_for_memory  (memory_middleware)
+  - filter_messages_for_memory  (message_processing)
   - _strip_upload_mentions_from_memory  (updater)
 """
 
 from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
 
+from deerflow.agents.memory.message_processing import detect_correction, detect_reinforcement, filter_messages_for_memory
 from deerflow.agents.memory.updater import _strip_upload_mentions_from_memory
-from deerflow.agents.middlewares.memory_middleware import _filter_messages_for_memory, detect_correction, detect_reinforcement
 
 # ---------------------------------------------------------------------------
 # Helpers
@@ -31,7 +31,7 @@ def _ai(text: str, tool_calls=None) -> AIMessage:
 
 
 # ===========================================================================
-# _filter_messages_for_memory
+# filter_messages_for_memory
 # ===========================================================================
 
 
@@ -45,7 +45,7 @@ class TestFilterMessagesForMemory:
             _human(_UPLOAD_BLOCK),
             _ai("I have read the file. It says: Hello."),
         ]
-        result = _filter_messages_for_memory(msgs)
+        result = filter_messages_for_memory(msgs)
         assert result == []
 
     def test_upload_with_real_question_preserves_question(self):
@@ -56,7 +56,7 @@ class TestFilterMessagesForMemory:
             _human(combined),
             _ai("The file contains: Hello DeerFlow."),
         ]
-        result = _filter_messages_for_memory(msgs)
+        result = filter_messages_for_memory(msgs)
 
         assert len(result) == 2
         human_result = result[0]
@@ -71,7 +71,7 @@ class TestFilterMessagesForMemory:
             _human("What is the capital of France?"),
             _ai("The capital of France is Paris."),
         ]
-        result = _filter_messages_for_memory(msgs)
+        result = filter_messages_for_memory(msgs)
         assert len(result) == 2
         assert result[0].content == "What is the capital of France?"
         assert result[1].content == "The capital of France is Paris."
@@ -84,7 +84,7 @@ class TestFilterMessagesForMemory:
             ToolMessage(content="Search results", tool_call_id="1"),
             _ai("Here are the results."),
         ]
-        result = _filter_messages_for_memory(msgs)
+        result = filter_messages_for_memory(msgs)
         human_msgs = [m for m in result if m.type == "human"]
         ai_msgs = [m for m in result if m.type == "ai"]
         assert len(human_msgs) == 1
@@ -101,7 +101,7 @@ class TestFilterMessagesForMemory:
             _human("What is 2 + 2?"),
             _ai("4"),
         ]
-        result = _filter_messages_for_memory(msgs)
+        result = filter_messages_for_memory(msgs)
         human_contents = [m.content for m in result if m.type == "human"]
         ai_contents = [m.content for m in result if m.type == "ai"]
 
@@ -121,14 +121,14 @@ class TestFilterMessagesForMemory:
             ]
         )
         msgs = [msg, _ai("Done.")]
-        result = _filter_messages_for_memory(msgs)
+        result = filter_messages_for_memory(msgs)
         assert result == []
 
     def test_file_path_not_in_filtered_content(self):
         """After filtering, no upload file path should appear in any message."""
         combined = _UPLOAD_BLOCK + "\n\nSummarise the file please."
         msgs = [_human(combined), _ai("It says hello.")]
-        result = _filter_messages_for_memory(msgs)
+        result = filter_messages_for_memory(msgs)
         all_content = " ".join(m.content for m in result if isinstance(m.content, str))
         assert "/mnt/user-data/uploads/" not in all_content
         assert "<uploaded_files>" not in all_content

backend/tests/test_present_file_tool_core_logic.py

@@ -10,6 +10,7 @@ def _make_runtime(outputs_path: str) -> SimpleNamespace:
     return SimpleNamespace(
         state={"thread_data": {"outputs_path": outputs_path}},
         context={"thread_id": "thread-1"},
+        config={},
     )
 
 
@@ -50,6 +51,34 @@ def test_present_files_keeps_virtual_outputs_path(tmp_path, monkeypatch):
     assert result.update["artifacts"] == ["/mnt/user-data/outputs/summary.json"]
 
 
+def test_present_files_uses_config_thread_id_when_context_missing(tmp_path, monkeypatch):
+    outputs_dir = tmp_path / "threads" / "thread-from-config" / "user-data" / "outputs"
+    outputs_dir.mkdir(parents=True)
+    artifact_path = outputs_dir / "summary.json"
+    artifact_path.write_text("{}")
+
+    monkeypatch.setattr(
+        present_file_tool_module,
+        "get_paths",
+        lambda: SimpleNamespace(resolve_virtual_path=lambda thread_id, path: artifact_path),
+    )
+
+    runtime = SimpleNamespace(
+        state={"thread_data": {"outputs_path": str(outputs_dir)}},
+        context={},
+        config={"configurable": {"thread_id": "thread-from-config"}},
+    )
+
+    result = present_file_tool_module.present_file_tool.func(
+        runtime=runtime,
+        filepaths=["/mnt/user-data/outputs/summary.json"],
+        tool_call_id="tc-config",
+    )
+
+    assert result.update["artifacts"] == ["/mnt/user-data/outputs/summary.json"]
+    assert result.update["messages"][0].content == "Successfully presented files"
+
+
 def test_present_files_rejects_paths_outside_outputs(tmp_path):
     outputs_dir = tmp_path / "threads" / "thread-1" / "user-data" / "outputs"
     workspace_dir = tmp_path / "threads" / "thread-1" / "user-data" / "workspace"

backend/tests/test_sandbox_search_tools.py

@@ -4,7 +4,7 @@ from unittest.mock import patch
 from deerflow.community.aio_sandbox.aio_sandbox import AioSandbox
 from deerflow.sandbox.local.local_sandbox import LocalSandbox
 from deerflow.sandbox.search import GrepMatch, find_glob_matches, find_grep_matches
-from deerflow.sandbox.tools import glob_tool, grep_tool
+from deerflow.sandbox.tools import glob_tool, grep_tool, ls_tool
 
 
 def _make_runtime(tmp_path):
@@ -391,3 +391,71 @@ def test_aio_sandbox_grep_skips_mismatched_line_number_payloads(monkeypatch) ->
 
     assert matches == [GrepMatch(path="/mnt/user-data/workspace/app.py", line_number=7, line="TODO = True")]
     assert truncated is False
+
+
+# ---------------------------------------------------------------------------
+# ls_tool — path masking
+# ---------------------------------------------------------------------------
+
+
+def test_ls_tool_masks_user_data_host_paths(tmp_path, monkeypatch) -> None:
+    """ls_tool output must not leak host user-data paths; they should be virtual."""
+    runtime = _make_runtime(tmp_path)
+    workspace = tmp_path / "workspace"
+    (workspace / "report.txt").write_text("hello\n", encoding="utf-8")
+    (workspace / "subdir").mkdir()
+
+    monkeypatch.setattr("deerflow.sandbox.tools.ensure_sandbox_initialized", lambda runtime: LocalSandbox(id="local"))
+
+    result = ls_tool.func(
+        runtime=runtime,
+        description="list workspace",
+        path="/mnt/user-data/workspace",
+    )
+
+    # Virtual paths must be present
+    assert "/mnt/user-data/workspace" in result
+    # Host paths must NOT leak
+    assert str(workspace) not in result
+    assert str(tmp_path) not in result
+
+
+def test_ls_tool_masks_skills_host_paths(tmp_path, monkeypatch) -> None:
+    """ls_tool output must not leak host skills paths; they should be virtual."""
+    runtime = _make_runtime(tmp_path)
+    skills_dir = tmp_path / "skills"
+    (skills_dir / "public").mkdir(parents=True)
+    (skills_dir / "public" / "SKILL.md").write_text("# Skill\n", encoding="utf-8")
+
+    monkeypatch.setattr("deerflow.sandbox.tools.ensure_sandbox_initialized", lambda runtime: LocalSandbox(id="local"))
+
+    with (
+        patch("deerflow.sandbox.tools._get_skills_container_path", return_value="/mnt/skills"),
+        patch("deerflow.sandbox.tools._get_skills_host_path", return_value=str(skills_dir)),
+    ):
+        result = ls_tool.func(
+            runtime=runtime,
+            description="list skills",
+            path="/mnt/skills",
+        )
+
+    # Virtual paths must be present
+    assert "/mnt/skills" in result
+    # Host paths must NOT leak
+    assert str(skills_dir) not in result
+    assert str(tmp_path) not in result
+
+
+def test_ls_tool_returns_empty_for_empty_directory(tmp_path, monkeypatch) -> None:
+    """ls_tool should return '(empty)' for an empty directory."""
+    runtime = _make_runtime(tmp_path)
+
+    monkeypatch.setattr("deerflow.sandbox.tools.ensure_sandbox_initialized", lambda runtime: LocalSandbox(id="local"))
+
+    result = ls_tool.func(
+        runtime=runtime,
+        description="list empty dir",
+        path="/mnt/user-data/workspace",
+    )
+
+    assert result == "(empty)"

backend/tests/test_setup_agent_tool.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+
+from deerflow.tools.builtins.setup_agent_tool import setup_agent
+
+
+class _DummyRuntime(SimpleNamespace):
+    context: dict
+    tool_call_id: str
+
+
+def test_setup_agent_rejects_invalid_agent_name_before_writing(tmp_path, monkeypatch):
+    monkeypatch.setenv("DEER_FLOW_HOME", str(tmp_path))
+    outside_dir = tmp_path.parent / "outside-target"
+    traversal_agent = f"../../../{outside_dir.name}/evil"
+    runtime = _DummyRuntime(context={"agent_name": traversal_agent}, tool_call_id="tool-1")
+
+    result = setup_agent.func(soul="test soul", description="desc", runtime=runtime)
+
+    messages = result.update["messages"]
+    assert len(messages) == 1
+    assert "Invalid agent name" in messages[0].content
+    assert not (tmp_path / "agents").exists()
+    assert not (outside_dir / "evil" / "SOUL.md").exists()
+
+
+def test_setup_agent_rejects_absolute_agent_name_before_writing(tmp_path, monkeypatch):
+    monkeypatch.setenv("DEER_FLOW_HOME", str(tmp_path))
+    absolute_agent = str(tmp_path / "outside-agent")
+    runtime = _DummyRuntime(context={"agent_name": absolute_agent}, tool_call_id="tool-2")
+
+    result = setup_agent.func(soul="test soul", description="desc", runtime=runtime)
+
+    messages = result.update["messages"]
+    assert len(messages) == 1
+    assert "Invalid agent name" in messages[0].content
+    assert not (tmp_path / "agents").exists()
+    assert not (Path(absolute_agent) / "SOUL.md").exists()

backend/tests/test_skills_custom_router.py

@@ -1,3 +1,4 @@
+import errno
 import json
 from pathlib import Path
 from types import SimpleNamespace
@@ -164,6 +165,74 @@ def test_custom_skill_delete_preserves_history_and_allows_restore(monkeypatch, t
         assert refresh_calls == ["refresh", "refresh"]
 
 
+def test_custom_skill_delete_continues_when_history_write_is_readonly(monkeypatch, tmp_path):
+    skills_root = tmp_path / "skills"
+    custom_dir = skills_root / "custom" / "demo-skill"
+    custom_dir.mkdir(parents=True, exist_ok=True)
+    (custom_dir / "SKILL.md").write_text(_skill_content("demo-skill"), encoding="utf-8")
+    config = SimpleNamespace(
+        skills=SimpleNamespace(get_skills_path=lambda: skills_root, container_path="/mnt/skills"),
+        skill_evolution=SimpleNamespace(enabled=True, moderation_model_name=None),
+    )
+    monkeypatch.setattr("deerflow.config.get_app_config", lambda: config)
+    monkeypatch.setattr("deerflow.skills.manager.get_app_config", lambda: config)
+    refresh_calls = []
+
+    async def _refresh():
+        refresh_calls.append("refresh")
+
+    def _readonly_history(*args, **kwargs):
+        raise OSError(errno.EROFS, "Read-only file system", str(skills_root / "custom" / ".history"))
+
+    monkeypatch.setattr("app.gateway.routers.skills.append_history", _readonly_history)
+    monkeypatch.setattr("app.gateway.routers.skills.refresh_skills_system_prompt_cache_async", _refresh)
+
+    app = FastAPI()
+    app.include_router(skills_router.router)
+
+    with TestClient(app) as client:
+        delete_response = client.delete("/api/skills/custom/demo-skill")
+
+    assert delete_response.status_code == 200
+    assert delete_response.json() == {"success": True}
+    assert not custom_dir.exists()
+    assert refresh_calls == ["refresh"]
+
+
+def test_custom_skill_delete_fails_when_skill_dir_removal_fails(monkeypatch, tmp_path):
+    skills_root = tmp_path / "skills"
+    custom_dir = skills_root / "custom" / "demo-skill"
+    custom_dir.mkdir(parents=True, exist_ok=True)
+    (custom_dir / "SKILL.md").write_text(_skill_content("demo-skill"), encoding="utf-8")
+    config = SimpleNamespace(
+        skills=SimpleNamespace(get_skills_path=lambda: skills_root, container_path="/mnt/skills"),
+        skill_evolution=SimpleNamespace(enabled=True, moderation_model_name=None),
+    )
+    monkeypatch.setattr("deerflow.config.get_app_config", lambda: config)
+    monkeypatch.setattr("deerflow.skills.manager.get_app_config", lambda: config)
+    refresh_calls = []
+
+    async def _refresh():
+        refresh_calls.append("refresh")
+
+    def _fail_rmtree(*args, **kwargs):
+        raise PermissionError(errno.EACCES, "Permission denied", str(custom_dir))
+
+    monkeypatch.setattr("app.gateway.routers.skills.shutil.rmtree", _fail_rmtree)
+    monkeypatch.setattr("app.gateway.routers.skills.refresh_skills_system_prompt_cache_async", _refresh)
+
+    app = FastAPI()
+    app.include_router(skills_router.router)
+
+    with TestClient(app) as client:
+        delete_response = client.delete("/api/skills/custom/demo-skill")
+
+    assert delete_response.status_code == 500
+    assert "Failed to delete custom skill" in delete_response.json()["detail"]
+    assert custom_dir.exists()
+    assert refresh_calls == []
+
+
 def test_update_skill_refreshes_prompt_cache_before_return(monkeypatch, tmp_path):
     config_path = tmp_path / "extensions_config.json"
     enabled_state = {"value": True}

backend/tests/test_summarization_middleware.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+from langchain_core.messages import AIMessage, HumanMessage, RemoveMessage
+
+from deerflow.agents.memory.summarization_hook import memory_flush_hook
+from deerflow.agents.middlewares.summarization_middleware import DeerFlowSummarizationMiddleware, SummarizationEvent
+from deerflow.config.memory_config import MemoryConfig
+
+
+def _messages() -> list:
+    return [
+        HumanMessage(content="user-1"),
+        AIMessage(content="assistant-1"),
+        HumanMessage(content="user-2"),
+        AIMessage(content="assistant-2"),
+    ]
+
+
+def _runtime(thread_id: str | None = "thread-1", agent_name: str | None = None) -> SimpleNamespace:
+    context = {}
+    if thread_id is not None:
+        context["thread_id"] = thread_id
+    if agent_name is not None:
+        context["agent_name"] = agent_name
+    return SimpleNamespace(context=context)
+
+
+def _middleware(*, before_summarization=None, trigger=("messages", 4), keep=("messages", 2)) -> DeerFlowSummarizationMiddleware:
+    model = MagicMock()
+    model.invoke.return_value = SimpleNamespace(text="compressed summary")
+    return DeerFlowSummarizationMiddleware(
+        model=model,
+        trigger=trigger,
+        keep=keep,
+        token_counter=len,
+        before_summarization=before_summarization,
+    )
+
+
+def test_before_summarization_hook_receives_messages_before_compression() -> None:
+    captured: list[SummarizationEvent] = []
+    middleware = _middleware(before_summarization=[captured.append])
+
+    result = middleware.before_model({"messages": _messages()}, _runtime())
+
+    assert len(captured) == 1
+    assert [message.content for message in captured[0].messages_to_summarize] == ["user-1", "assistant-1"]
+    assert [message.content for message in captured[0].preserved_messages] == ["user-2", "assistant-2"]
+    assert captured[0].thread_id == "thread-1"
+    assert captured[0].agent_name is None
+    assert isinstance(result["messages"][0], RemoveMessage)
+    assert result["messages"][1].content.startswith("Here is a summary")
+
+
+def test_before_summarization_hook_not_called_when_threshold_not_met() -> None:
+    captured: list[SummarizationEvent] = []
+    middleware = _middleware(before_summarization=[captured.append], trigger=("messages", 10))
+
+    result = middleware.before_model({"messages": _messages()}, _runtime())
+
+    assert captured == []
+    assert result is None
+
+
+def test_before_summarization_hook_exception_does_not_block_compression(caplog: pytest.LogCaptureFixture) -> None:
+    def _broken_hook(_: SummarizationEvent) -> None:
+        raise RuntimeError("hook failure")
+
+    middleware = _middleware(before_summarization=[_broken_hook])
+
+    with caplog.at_level("ERROR"):
+        result = middleware.before_model({"messages": _messages()}, _runtime())
+
+    assert "before_summarization hook _broken_hook failed" in caplog.text
+    assert isinstance(result["messages"][0], RemoveMessage)
+
+
+def test_multiple_before_summarization_hooks_run_in_registration_order() -> None:
+    call_order: list[str] = []
+
+    def _hook(name: str):
+        return lambda _: call_order.append(name)
+
+    middleware = _middleware(before_summarization=[_hook("first"), _hook("second"), _hook("third")])
+
+    middleware.before_model({"messages": _messages()}, _runtime())
+
+    assert call_order == ["first", "second", "third"]
+
+
+@pytest.mark.anyio
+async def test_abefore_model_calls_hooks_same_as_sync() -> None:
+    captured: list[SummarizationEvent] = []
+    middleware = _middleware(before_summarization=[captured.append])
+
+    await middleware.abefore_model({"messages": _messages()}, _runtime())
+
+    assert len(captured) == 1
+    assert [message.content for message in captured[0].messages_to_summarize] == ["user-1", "assistant-1"]
+
+
+def test_memory_flush_hook_skips_when_memory_disabled(monkeypatch: pytest.MonkeyPatch) -> None:
+    queue = MagicMock()
+    monkeypatch.setattr("deerflow.agents.memory.summarization_hook.get_memory_config", lambda: MemoryConfig(enabled=False))
+    monkeypatch.setattr("deerflow.agents.memory.summarization_hook.get_memory_queue", lambda: queue)
+
+    memory_flush_hook(
+        SummarizationEvent(
+            messages_to_summarize=tuple(_messages()[:2]),
+            preserved_messages=(),
+            thread_id="thread-1",
+            agent_name=None,
+            runtime=_runtime(),
+        )
+    )
+
+    queue.add_nowait.assert_not_called()
+
+
+def test_memory_flush_hook_skips_when_thread_id_missing(monkeypatch: pytest.MonkeyPatch) -> None:
+    queue = MagicMock()
+    monkeypatch.setattr("deerflow.agents.memory.summarization_hook.get_memory_config", lambda: MemoryConfig(enabled=True))
+    monkeypatch.setattr("deerflow.agents.memory.summarization_hook.get_memory_queue", lambda: queue)
+
+    memory_flush_hook(
+        SummarizationEvent(
+            messages_to_summarize=tuple(_messages()[:2]),
+            preserved_messages=(),
+            thread_id=None,
+            agent_name=None,
+            runtime=_runtime(None),
+        )
+    )
+
+    queue.add_nowait.assert_not_called()
+
+
+def test_memory_flush_hook_enqueues_filtered_messages_and_flushes(monkeypatch: pytest.MonkeyPatch) -> None:
+    queue = MagicMock()
+    messages = [
+        HumanMessage(content="Question"),
+        AIMessage(content="Calling tool", tool_calls=[{"name": "search", "id": "tool-1", "args": {}}]),
+        AIMessage(content="Final answer"),
+    ]
+    monkeypatch.setattr("deerflow.agents.memory.summarization_hook.get_memory_config", lambda: MemoryConfig(enabled=True))
+    monkeypatch.setattr("deerflow.agents.memory.summarization_hook.get_memory_queue", lambda: queue)
+
+    memory_flush_hook(
+        SummarizationEvent(
+            messages_to_summarize=tuple(messages),
+            preserved_messages=(),
+            thread_id="thread-1",
+            agent_name=None,
+            runtime=_runtime(),
+        )
+    )
+
+    queue.add_nowait.assert_called_once()
+    add_kwargs = queue.add_nowait.call_args.kwargs
+    assert add_kwargs["thread_id"] == "thread-1"
+    assert [message.content for message in add_kwargs["messages"]] == ["Question", "Final answer"]
+    assert add_kwargs["correction_detected"] is False
+    assert add_kwargs["reinforcement_detected"] is False
+
+
+def test_memory_flush_hook_preserves_agent_scoped_memory(monkeypatch: pytest.MonkeyPatch) -> None:
+    queue = MagicMock()
+    monkeypatch.setattr("deerflow.agents.memory.summarization_hook.get_memory_config", lambda: MemoryConfig(enabled=True))
+    monkeypatch.setattr("deerflow.agents.memory.summarization_hook.get_memory_queue", lambda: queue)
+
+    memory_flush_hook(
+        SummarizationEvent(
+            messages_to_summarize=tuple(_messages()[:2]),
+            preserved_messages=(),
+            thread_id="thread-1",
+            agent_name="research-agent",
+            runtime=_runtime(agent_name="research-agent"),
+        )
+    )
+
+    queue.add_nowait.assert_called_once()
+    assert queue.add_nowait.call_args.kwargs["agent_name"] == "research-agent"

backend/tests/test_task_tool_core_logic.py

@@ -167,14 +167,140 @@ def test_task_tool_emits_running_and_completed_events(monkeypatch):
     assert captured["executor_kwargs"]["config"].max_turns == 7
     assert "Skills Appendix" in captured["executor_kwargs"]["config"].system_prompt
 
-    get_available_tools.assert_called_once_with(model_name="ark-model", subagent_enabled=False)
+    get_available_tools.assert_called_once_with(model_name="ark-model", groups=None, subagent_enabled=False)
 
     event_types = [e["type"] for e in events]
     assert event_types == ["task_started", "task_running", "task_running", "task_completed"]
     assert events[-1]["result"] == "all done"
 
 
-def test_task_tool_returns_failed_message(monkeypatch):
+def test_task_tool_propagates_tool_groups_to_subagent(monkeypatch):
+    """Verify tool_groups from parent metadata are passed to get_available_tools(groups=...)."""
+    config = _make_subagent_config()
+    parent_tool_groups = ["file:read", "file:write", "bash"]
+    runtime = SimpleNamespace(
+        state={
+            "sandbox": {"sandbox_id": "local"},
+            "thread_data": {"workspace_path": "/tmp/workspace"},
+        },
+        context={"thread_id": "thread-1"},
+        config={"metadata": {"model_name": "ark-model", "trace_id": "trace-1", "tool_groups": parent_tool_groups}},
+    )
+    events = []
+    get_available_tools = MagicMock(return_value=["tool-a"])
+
+    class DummyExecutor:
+        def __init__(self, **kwargs):
+            pass
+
+        def execute_async(self, prompt, task_id=None):
+            return task_id or "generated-task-id"
+
+    monkeypatch.setattr(task_tool_module, "SubagentStatus", FakeSubagentStatus)
+    monkeypatch.setattr(task_tool_module, "SubagentExecutor", DummyExecutor)
+    monkeypatch.setattr(task_tool_module, "get_subagent_config", lambda _: config)
+    monkeypatch.setattr(task_tool_module, "get_skills_prompt_section", lambda: "")
+    monkeypatch.setattr(
+        task_tool_module,
+        "get_background_task_result",
+        lambda _: _make_result(FakeSubagentStatus.COMPLETED, result="done"),
+    )
+    monkeypatch.setattr(task_tool_module, "get_stream_writer", lambda: events.append)
+    monkeypatch.setattr(task_tool_module.asyncio, "sleep", _no_sleep)
+    monkeypatch.setattr("deerflow.tools.get_available_tools", get_available_tools)
+
+    output = _run_task_tool(
+        runtime=runtime,
+        description="执行任务",
+        prompt="file work only",
+        subagent_type="general-purpose",
+        tool_call_id="tc-groups",
+    )
+
+    assert output == "Task Succeeded. Result: done"
+    # The key assertion: groups should be propagated from parent metadata
+    get_available_tools.assert_called_once_with(model_name="ark-model", groups=parent_tool_groups, subagent_enabled=False)
+
+
+def test_task_tool_no_tool_groups_passes_none(monkeypatch):
+    """Verify that when metadata has no tool_groups, groups=None is passed (backward compat)."""
+    config = _make_subagent_config()
+    # Default _make_runtime() has no tool_groups in metadata
+    runtime = _make_runtime()
+    events = []
+    get_available_tools = MagicMock(return_value=[])
+
+    class DummyExecutor:
+        def __init__(self, **kwargs):
+            pass
+
+        def execute_async(self, prompt, task_id=None):
+            return task_id or "generated-task-id"
+
+    monkeypatch.setattr(task_tool_module, "SubagentStatus", FakeSubagentStatus)
+    monkeypatch.setattr(task_tool_module, "SubagentExecutor", DummyExecutor)
+    monkeypatch.setattr(task_tool_module, "get_subagent_config", lambda _: config)
+    monkeypatch.setattr(task_tool_module, "get_skills_prompt_section", lambda: "")
+    monkeypatch.setattr(
+        task_tool_module,
+        "get_background_task_result",
+        lambda _: _make_result(FakeSubagentStatus.COMPLETED, result="ok"),
+    )
+    monkeypatch.setattr(task_tool_module, "get_stream_writer", lambda: events.append)
+    monkeypatch.setattr(task_tool_module.asyncio, "sleep", _no_sleep)
+    monkeypatch.setattr("deerflow.tools.get_available_tools", get_available_tools)
+
+    output = _run_task_tool(
+        runtime=runtime,
+        description="执行任务",
+        prompt="normal work",
+        subagent_type="general-purpose",
+        tool_call_id="tc-no-groups",
+    )
+
+    assert output == "Task Succeeded. Result: ok"
+    # No tool_groups in metadata → groups=None (default behavior preserved)
+    get_available_tools.assert_called_once_with(model_name="ark-model", groups=None, subagent_enabled=False)
+
+
+def test_task_tool_runtime_none_passes_groups_none(monkeypatch):
+    """Verify that when runtime is None, groups=None is passed (e.g., unknown subagent path exits early, but tools still load correctly)."""
+    config = _make_subagent_config()
+    events = []
+    get_available_tools = MagicMock(return_value=[])
+
+    class DummyExecutor:
+        def __init__(self, **kwargs):
+            pass
+
+        def execute_async(self, prompt, task_id=None):
+            return task_id or "generated-task-id"
+
+    monkeypatch.setattr(task_tool_module, "SubagentStatus", FakeSubagentStatus)
+    monkeypatch.setattr(task_tool_module, "SubagentExecutor", DummyExecutor)
+    monkeypatch.setattr(task_tool_module, "get_subagent_config", lambda _: config)
+    monkeypatch.setattr(task_tool_module, "get_skills_prompt_section", lambda: "")
+    monkeypatch.setattr(
+        task_tool_module,
+        "get_background_task_result",
+        lambda _: _make_result(FakeSubagentStatus.COMPLETED, result="ok"),
+    )
+    monkeypatch.setattr(task_tool_module, "get_stream_writer", lambda: events.append)
+    monkeypatch.setattr(task_tool_module.asyncio, "sleep", _no_sleep)
+    monkeypatch.setattr("deerflow.tools.get_available_tools", get_available_tools)
+
+    output = _run_task_tool(
+        runtime=None,
+        description="执行任务",
+        prompt="no runtime",
+        subagent_type="general-purpose",
+        tool_call_id="tc-no-runtime",
+    )
+
+    assert output == "Task Succeeded. Result: ok"
+    # runtime is None → metadata is empty dict → groups=None
+    get_available_tools.assert_called_once_with(model_name=None, groups=None, subagent_enabled=False)
+
     config = _make_subagent_config()
     events = []
 

backend/tests/test_title_middleware_core_logic.py

@@ -181,3 +181,50 @@ class TestTitleMiddlewareCoreLogic:
         result = middleware._generate_title_result(state)
         assert result["title"].endswith("...")
         assert result["title"].startswith("这是一个非常长的问题描述")
+
+    def test_parse_title_strips_think_tags(self):
+        """Title model responses with <think>...</think> blocks are stripped before use."""
+        middleware = TitleMiddleware()
+        raw = "<think>用户想要研究贵阳发展情况。我需要使用 deep-research skill。</think>贵阳近5年发展报告研究"
+        result = middleware._parse_title(raw)
+        assert "<think>" not in result
+        assert result == "贵阳近5年发展报告研究"
+
+    def test_parse_title_strips_think_tags_only_response(self):
+        """If model only outputs a think block and nothing else, title is empty string."""
+        middleware = TitleMiddleware()
+        raw = "<think>just thinking, no real title</think>"
+        result = middleware._parse_title(raw)
+        assert result == ""
+
+    def test_build_title_prompt_strips_assistant_think_tags(self):
+        """<think> blocks in assistant messages are stripped before being included in the title prompt."""
+        _set_test_title_config(enabled=True)
+        middleware = TitleMiddleware()
+        state = {
+            "messages": [
+                HumanMessage(content="贵阳发展报告研究"),
+                AIMessage(content="<think>分析用户需求</think>我将为您研究贵阳的发展情况。"),
+            ]
+        }
+        prompt, _ = middleware._build_title_prompt(state)
+        assert "<think>" not in prompt
+
+    def test_generate_title_async_strips_think_tags_in_response(self, monkeypatch):
+        """Async title generation strips <think> blocks from the model response."""
+        _set_test_title_config(max_chars=50)
+        middleware = TitleMiddleware()
+        model = MagicMock()
+        model.ainvoke = AsyncMock(return_value=AIMessage(content="<think>用户想研究贵阳。</think>贵阳发展研究"))
+        monkeypatch.setattr(title_middleware_module, "create_chat_model", MagicMock(return_value=model))
+
+        state = {
+            "messages": [
+                HumanMessage(content="请帮我研究贵阳近5年发展情况"),
+                AIMessage(content="好的"),
+            ]
+        }
+        result = asyncio.run(middleware._agenerate_title_result(state))
+        assert result is not None
+        assert "<think>" not in result["title"]
+        assert result["title"] == "贵阳发展研究"

backend/tests/test_todo_middleware.py

@@ -7,6 +7,7 @@ from langchain_core.messages import AIMessage, HumanMessage
 
 from deerflow.agents.middlewares.todo_middleware import (
     TodoMiddleware,
+    _completion_reminder_count,
     _format_todos,
     _reminder_in_messages,
     _todos_in_messages,
@@ -154,3 +155,148 @@ class TestAbeforeModel:
         result = asyncio.run(mw.abefore_model(state, _make_runtime()))
         assert result is not None
         assert result["messages"][0].name == "todo_reminder"
+
+
+def _completion_reminder_msg():
+    return HumanMessage(name="todo_completion_reminder", content="finish your todos")
+
+
+def _ai_no_tool_calls():
+    return AIMessage(content="I'm done!")
+
+
+def _incomplete_todos():
+    return [
+        {"status": "completed", "content": "Step 1"},
+        {"status": "in_progress", "content": "Step 2"},
+        {"status": "pending", "content": "Step 3"},
+    ]
+
+
+def _all_completed_todos():
+    return [
+        {"status": "completed", "content": "Step 1"},
+        {"status": "completed", "content": "Step 2"},
+    ]
+
+
+class TestCompletionReminderCount:
+    def test_zero_when_no_reminders(self):
+        msgs = [HumanMessage(content="hi"), _ai_no_tool_calls()]
+        assert _completion_reminder_count(msgs) == 0
+
+    def test_counts_completion_reminders(self):
+        msgs = [_completion_reminder_msg(), _completion_reminder_msg()]
+        assert _completion_reminder_count(msgs) == 2
+
+    def test_does_not_count_todo_reminders(self):
+        msgs = [_reminder_msg(), _completion_reminder_msg()]
+        assert _completion_reminder_count(msgs) == 1
+
+
+class TestAfterModel:
+    def test_returns_none_when_agent_still_using_tools(self):
+        mw = TodoMiddleware()
+        state = {
+            "messages": [_ai_with_write_todos()],
+            "todos": _incomplete_todos(),
+        }
+        assert mw.after_model(state, _make_runtime()) is None
+
+    def test_returns_none_when_no_todos(self):
+        mw = TodoMiddleware()
+        state = {
+            "messages": [_ai_no_tool_calls()],
+            "todos": [],
+        }
+        assert mw.after_model(state, _make_runtime()) is None
+
+    def test_returns_none_when_todos_is_none(self):
+        mw = TodoMiddleware()
+        state = {
+            "messages": [_ai_no_tool_calls()],
+            "todos": None,
+        }
+        assert mw.after_model(state, _make_runtime()) is None
+
+    def test_returns_none_when_all_completed(self):
+        mw = TodoMiddleware()
+        state = {
+            "messages": [_ai_no_tool_calls()],
+            "todos": _all_completed_todos(),
+        }
+        assert mw.after_model(state, _make_runtime()) is None
+
+    def test_returns_none_when_no_messages(self):
+        mw = TodoMiddleware()
+        state = {
+            "messages": [],
+            "todos": _incomplete_todos(),
+        }
+        assert mw.after_model(state, _make_runtime()) is None
+
+    def test_injects_reminder_and_jumps_to_model_when_incomplete(self):
+        mw = TodoMiddleware()
+        state = {
+            "messages": [HumanMessage(content="hi"), _ai_no_tool_calls()],
+            "todos": _incomplete_todos(),
+        }
+        result = mw.after_model(state, _make_runtime())
+        assert result is not None
+        assert result["jump_to"] == "model"
+        assert len(result["messages"]) == 1
+        reminder = result["messages"][0]
+        assert isinstance(reminder, HumanMessage)
+        assert reminder.name == "todo_completion_reminder"
+        assert "Step 2" in reminder.content
+        assert "Step 3" in reminder.content
+
+    def test_reminder_lists_only_incomplete_items(self):
+        mw = TodoMiddleware()
+        state = {
+            "messages": [_ai_no_tool_calls()],
+            "todos": _incomplete_todos(),
+        }
+        result = mw.after_model(state, _make_runtime())
+        content = result["messages"][0].content
+        assert "Step 1" not in content  # completed — should not appear
+        assert "Step 2" in content
+        assert "Step 3" in content
+
+    def test_allows_exit_after_max_reminders(self):
+        mw = TodoMiddleware()
+        state = {
+            "messages": [
+                _completion_reminder_msg(),
+                _completion_reminder_msg(),
+                _ai_no_tool_calls(),
+            ],
+            "todos": _incomplete_todos(),
+        }
+        assert mw.after_model(state, _make_runtime()) is None
+
+    def test_still_sends_reminder_before_cap(self):
+        mw = TodoMiddleware()
+        state = {
+            "messages": [
+                _completion_reminder_msg(),  # 1 reminder so far
+                _ai_no_tool_calls(),
+            ],
+            "todos": _incomplete_todos(),
+        }
+        result = mw.after_model(state, _make_runtime())
+        assert result is not None
+        assert result["jump_to"] == "model"
+
+
+class TestAafterModel:
+    def test_delegates_to_sync(self):
+        mw = TodoMiddleware()
+        state = {
+            "messages": [_ai_no_tool_calls()],
+            "todos": _incomplete_todos(),
+        }
+        result = asyncio.run(mw.aafter_model(state, _make_runtime()))
+        assert result is not None
+        assert result["jump_to"] == "model"
+        assert result["messages"][0].name == "todo_completion_reminder"

backend/tests/test_uploads_router.py

@@ -14,6 +14,7 @@ def test_upload_files_writes_thread_storage_and_skips_local_sandbox_sync(tmp_pat
     thread_uploads_dir.mkdir(parents=True)
 
     provider = MagicMock()
+    provider.uses_thread_data_mounts = True
     provider.acquire.return_value = "local"
     sandbox = MagicMock()
     provider.get.return_value = sandbox
@@ -34,11 +35,61 @@ def test_upload_files_writes_thread_storage_and_skips_local_sandbox_sync(tmp_pat
     sandbox.update_file.assert_not_called()
 
 
+def test_upload_files_skips_acquire_when_thread_data_is_mounted(tmp_path):
+    thread_uploads_dir = tmp_path / "uploads"
+    thread_uploads_dir.mkdir(parents=True)
+
+    provider = MagicMock()
+    provider.uses_thread_data_mounts = True
+
+    with (
+        patch.object(uploads, "get_uploads_dir", return_value=thread_uploads_dir),
+        patch.object(uploads, "ensure_uploads_dir", return_value=thread_uploads_dir),
+        patch.object(uploads, "get_sandbox_provider", return_value=provider),
+    ):
+        file = UploadFile(filename="notes.txt", file=BytesIO(b"hello uploads"))
+        result = asyncio.run(uploads.upload_files("thread-mounted", files=[file]))
+
+    assert result.success is True
+    assert (thread_uploads_dir / "notes.txt").read_bytes() == b"hello uploads"
+    provider.acquire.assert_not_called()
+    provider.get.assert_not_called()
+
+
+def test_upload_files_does_not_auto_convert_documents_by_default(tmp_path):
+    thread_uploads_dir = tmp_path / "uploads"
+    thread_uploads_dir.mkdir(parents=True)
+
+    provider = MagicMock()
+    provider.uses_thread_data_mounts = True
+    provider.acquire.return_value = "local"
+    sandbox = MagicMock()
+    provider.get.return_value = sandbox
+
+    with (
+        patch.object(uploads, "get_uploads_dir", return_value=thread_uploads_dir),
+        patch.object(uploads, "ensure_uploads_dir", return_value=thread_uploads_dir),
+        patch.object(uploads, "get_sandbox_provider", return_value=provider),
+        patch.object(uploads, "_auto_convert_documents_enabled", return_value=False),
+        patch.object(uploads, "convert_file_to_markdown", AsyncMock()) as convert_mock,
+    ):
+        file = UploadFile(filename="report.pdf", file=BytesIO(b"pdf-bytes"))
+        result = asyncio.run(uploads.upload_files("thread-local", files=[file]))
+
+    assert result.success is True
+    assert len(result.files) == 1
+    assert result.files[0]["filename"] == "report.pdf"
+    assert "markdown_file" not in result.files[0]
+    convert_mock.assert_not_called()
+    assert not (thread_uploads_dir / "report.md").exists()
+
+
 def test_upload_files_syncs_non_local_sandbox_and_marks_markdown_file(tmp_path):
     thread_uploads_dir = tmp_path / "uploads"
     thread_uploads_dir.mkdir(parents=True)
 
     provider = MagicMock()
+    provider.uses_thread_data_mounts = False
     provider.acquire.return_value = "aio-1"
     sandbox = MagicMock()
     provider.get.return_value = sandbox
@@ -52,6 +103,7 @@ def test_upload_files_syncs_non_local_sandbox_and_marks_markdown_file(tmp_path):
         patch.object(uploads, "get_uploads_dir", return_value=thread_uploads_dir),
         patch.object(uploads, "ensure_uploads_dir", return_value=thread_uploads_dir),
         patch.object(uploads, "get_sandbox_provider", return_value=provider),
+        patch.object(uploads, "_auto_convert_documents_enabled", return_value=True),
         patch.object(uploads, "convert_file_to_markdown", AsyncMock(side_effect=fake_convert)),
     ):
         file = UploadFile(filename="report.pdf", file=BytesIO(b"pdf-bytes"))
@@ -75,6 +127,7 @@ def test_upload_files_makes_non_local_files_sandbox_writable(tmp_path):
     thread_uploads_dir.mkdir(parents=True)
 
     provider = MagicMock()
+    provider.uses_thread_data_mounts = False
     provider.acquire.return_value = "aio-1"
     sandbox = MagicMock()
     provider.get.return_value = sandbox
@@ -88,6 +141,7 @@ def test_upload_files_makes_non_local_files_sandbox_writable(tmp_path):
         patch.object(uploads, "get_uploads_dir", return_value=thread_uploads_dir),
         patch.object(uploads, "ensure_uploads_dir", return_value=thread_uploads_dir),
         patch.object(uploads, "get_sandbox_provider", return_value=provider),
+        patch.object(uploads, "_auto_convert_documents_enabled", return_value=True),
         patch.object(uploads, "convert_file_to_markdown", AsyncMock(side_effect=fake_convert)),
         patch.object(uploads, "_make_file_sandbox_writable") as make_writable,
     ):
@@ -104,6 +158,7 @@ def test_upload_files_does_not_adjust_permissions_for_local_sandbox(tmp_path):
     thread_uploads_dir.mkdir(parents=True)
 
     provider = MagicMock()
+    provider.uses_thread_data_mounts = True
     provider.acquire.return_value = "local"
     sandbox = MagicMock()
     provider.get.return_value = sandbox
@@ -193,3 +248,39 @@ def test_delete_uploaded_file_removes_generated_markdown_companion(tmp_path):
     assert result == {"success": True, "message": "Deleted report.pdf"}
     assert not (thread_uploads_dir / "report.pdf").exists()
     assert not (thread_uploads_dir / "report.md").exists()
+
+
+def test_auto_convert_documents_enabled_defaults_to_false_on_config_errors():
+    with patch.object(uploads, "get_app_config", side_effect=RuntimeError("boom")):
+        assert uploads._auto_convert_documents_enabled() is False
+
+
+def test_auto_convert_documents_enabled_reads_dict_backed_uploads_config():
+    cfg = MagicMock()
+    cfg.uploads = {"auto_convert_documents": True}
+
+    with patch.object(uploads, "get_app_config", return_value=cfg):
+        assert uploads._auto_convert_documents_enabled() is True
+
+
+def test_auto_convert_documents_enabled_accepts_boolean_and_string_truthy_values():
+    false_cfg = MagicMock()
+    false_cfg.uploads = MagicMock(auto_convert_documents=False)
+
+    true_cfg = MagicMock()
+    true_cfg.uploads = MagicMock(auto_convert_documents=True)
+
+    string_true_cfg = MagicMock()
+    string_true_cfg.uploads = MagicMock(auto_convert_documents="YES")
+
+    string_false_cfg = MagicMock()
+    string_false_cfg.uploads = MagicMock(auto_convert_documents="false")
+
+    with patch.object(uploads, "get_app_config", return_value=false_cfg):
+        assert uploads._auto_convert_documents_enabled() is False
+    with patch.object(uploads, "get_app_config", return_value=true_cfg):
+        assert uploads._auto_convert_documents_enabled() is True
+    with patch.object(uploads, "get_app_config", return_value=string_true_cfg):
+        assert uploads._auto_convert_documents_enabled() is True
+    with patch.object(uploads, "get_app_config", return_value=string_false_cfg):
+        assert uploads._auto_convert_documents_enabled() is False

backend/tests/test_view_image_middleware.py

@@ -0,0 +1,398 @@
+"""Unit tests for ViewImageMiddleware.
+
+Tests cover the middleware's ability to inject image details (including base64
+payloads) as a HumanMessage before the next LLM call, triggered only when the
+previous assistant turn contained `view_image` tool calls that have all been
+completed with corresponding ToolMessages.
+
+Covered behavior:
+- `_get_last_assistant_message` returns the most recent AIMessage (or None).
+- `_has_view_image_tool` only matches assistant messages with `view_image` tool calls.
+- `_all_tools_completed` verifies every tool call id has a matching ToolMessage.
+- `_create_image_details_message` produces correctly structured content blocks.
+- `_should_inject_image_message` gates injection on all preconditions, including
+  deduplication when an image-details message was already added.
+- `_inject_image_message` returns a state update with a HumanMessage, or None
+  when injection is not warranted.
+- `before_model` and `abefore_model` expose the same behavior sync/async.
+"""
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, ToolMessage
+
+from deerflow.agents.middlewares.view_image_middleware import ViewImageMiddleware
+
+
+def _view_image_call(call_id: str = "call_1", path: str = "/mnt/user-data/uploads/img.png") -> dict:
+    return {"name": "view_image", "id": call_id, "args": {"image_path": path}}
+
+
+def _other_tool_call(call_id: str = "call_other", name: str = "bash") -> dict:
+    return {"name": name, "id": call_id, "args": {"command": "ls"}}
+
+
+def _runtime() -> MagicMock:
+    """Minimal Runtime stub. The middleware doesn't use it today, but the
+    interface requires it."""
+    return MagicMock()
+
+
+class TestGetLastAssistantMessage:
+    def test_returns_none_on_empty_list(self):
+        mw = ViewImageMiddleware()
+        assert mw._get_last_assistant_message([]) is None
+
+    def test_returns_none_when_no_ai_message(self):
+        mw = ViewImageMiddleware()
+        messages = [
+            SystemMessage(content="sys"),
+            HumanMessage(content="hi"),
+        ]
+        assert mw._get_last_assistant_message(messages) is None
+
+    def test_returns_most_recent_ai_message(self):
+        mw = ViewImageMiddleware()
+        older = AIMessage(content="older")
+        newer = AIMessage(content="newer")
+        messages = [HumanMessage(content="q"), older, HumanMessage(content="q2"), newer]
+        assert mw._get_last_assistant_message(messages) is newer
+
+
+class TestHasViewImageTool:
+    def test_returns_false_when_tool_calls_attr_missing(self):
+        """Exercise the `not hasattr(message, "tool_calls")` guard.
+
+        AIMessage always has a `tool_calls` attribute, so we use a plain
+        object that truly lacks the attribute to cover this branch.
+        """
+        mw = ViewImageMiddleware()
+        msg = SimpleNamespace(content="just text")  # no tool_calls attribute
+        assert not hasattr(msg, "tool_calls")  # precondition
+        assert mw._has_view_image_tool(msg) is False
+
+    def test_returns_false_when_ai_message_has_no_tool_calls(self):
+        """AIMessage without tool_calls kwarg defaults to an empty list."""
+        mw = ViewImageMiddleware()
+        msg = AIMessage(content="just text")
+        assert mw._has_view_image_tool(msg) is False
+
+    def test_returns_false_when_tool_calls_empty(self):
+        mw = ViewImageMiddleware()
+        msg = AIMessage(content="", tool_calls=[])
+        assert mw._has_view_image_tool(msg) is False
+
+    def test_returns_true_when_view_image_present(self):
+        mw = ViewImageMiddleware()
+        msg = AIMessage(content="", tool_calls=[_view_image_call()])
+        assert mw._has_view_image_tool(msg) is True
+
+    def test_returns_true_when_view_image_mixed_with_others(self):
+        mw = ViewImageMiddleware()
+        msg = AIMessage(
+            content="",
+            tool_calls=[_other_tool_call(), _view_image_call(call_id="call_vi")],
+        )
+        assert mw._has_view_image_tool(msg) is True
+
+    def test_returns_false_when_only_other_tools(self):
+        mw = ViewImageMiddleware()
+        msg = AIMessage(content="", tool_calls=[_other_tool_call()])
+        assert mw._has_view_image_tool(msg) is False
+
+
+class TestAllToolsCompleted:
+    def test_returns_false_when_no_tool_calls(self):
+        mw = ViewImageMiddleware()
+        assistant = AIMessage(content="", tool_calls=[])
+        assert mw._all_tools_completed([assistant], assistant) is False
+
+    def test_returns_true_when_all_completed(self):
+        mw = ViewImageMiddleware()
+        assistant = AIMessage(
+            content="",
+            tool_calls=[_view_image_call("c1"), _view_image_call("c2", "/p2.png")],
+        )
+        messages = [
+            assistant,
+            ToolMessage(content="ok", tool_call_id="c1"),
+            ToolMessage(content="ok", tool_call_id="c2"),
+        ]
+        assert mw._all_tools_completed(messages, assistant) is True
+
+    def test_returns_false_when_some_tool_call_unanswered(self):
+        mw = ViewImageMiddleware()
+        assistant = AIMessage(
+            content="",
+            tool_calls=[_view_image_call("c1"), _view_image_call("c2", "/p2.png")],
+        )
+        messages = [assistant, ToolMessage(content="ok", tool_call_id="c1")]
+        assert mw._all_tools_completed(messages, assistant) is False
+
+    def test_returns_false_when_assistant_not_in_messages(self):
+        mw = ViewImageMiddleware()
+        assistant = AIMessage(content="", tool_calls=[_view_image_call("c1")])
+        # assistant is not part of the list, so messages.index() will raise and be caught
+        messages = [HumanMessage(content="hi")]
+        assert mw._all_tools_completed(messages, assistant) is False
+
+    def test_ignores_tool_messages_before_assistant(self):
+        mw = ViewImageMiddleware()
+        assistant = AIMessage(content="", tool_calls=[_view_image_call("c1")])
+        # A stale ToolMessage with matching id appears BEFORE the assistant turn.
+        # It should not count — only ToolMessages after the assistant close the call.
+        messages = [
+            ToolMessage(content="stale", tool_call_id="c1"),
+            assistant,
+        ]
+        assert mw._all_tools_completed(messages, assistant) is False
+
+
+class TestCreateImageDetailsMessage:
+    def test_returns_placeholder_when_no_images(self):
+        mw = ViewImageMiddleware()
+        state = {"viewed_images": {}}
+        blocks = mw._create_image_details_message(state)
+        assert blocks == [{"type": "text", "text": "No images have been viewed."}]
+
+    def test_returns_placeholder_when_state_missing_key(self):
+        mw = ViewImageMiddleware()
+        blocks = mw._create_image_details_message({})
+        assert blocks == [{"type": "text", "text": "No images have been viewed."}]
+
+    def test_builds_blocks_for_single_image(self):
+        mw = ViewImageMiddleware()
+        state = {
+            "viewed_images": {
+                "/path/to/cat.png": {"base64": "BASE64DATA", "mime_type": "image/png"},
+            }
+        }
+        blocks = mw._create_image_details_message(state)
+
+        # header text + per-image description text + per-image image_url block
+        assert len(blocks) == 3
+        assert blocks[0] == {"type": "text", "text": "Here are the images you've viewed:"}
+        assert blocks[1]["type"] == "text"
+        assert "/path/to/cat.png" in blocks[1]["text"]
+        assert "image/png" in blocks[1]["text"]
+        assert blocks[2] == {
+            "type": "image_url",
+            "image_url": {"url": "data:image/png;base64,BASE64DATA"},
+        }
+
+    def test_builds_blocks_for_multiple_images(self):
+        mw = ViewImageMiddleware()
+        state = {
+            "viewed_images": {
+                "/a.png": {"base64": "AAA", "mime_type": "image/png"},
+                "/b.jpg": {"base64": "BBB", "mime_type": "image/jpeg"},
+            }
+        }
+        blocks = mw._create_image_details_message(state)
+
+        # 1 header + (1 description + 1 image_url) per image = 5 blocks
+        assert len(blocks) == 5
+        image_url_blocks = [b for b in blocks if isinstance(b, dict) and b.get("type") == "image_url"]
+        assert len(image_url_blocks) == 2
+        urls = {b["image_url"]["url"] for b in image_url_blocks}
+        assert "data:image/png;base64,AAA" in urls
+        assert "data:image/jpeg;base64,BBB" in urls
+
+    def test_omits_image_url_block_when_base64_missing(self):
+        mw = ViewImageMiddleware()
+        state = {
+            "viewed_images": {
+                "/broken.png": {"base64": "", "mime_type": "image/png"},
+            }
+        }
+        blocks = mw._create_image_details_message(state)
+        # header + description only (no image_url since base64 is empty)
+        assert len(blocks) == 2
+        assert all(not (isinstance(b, dict) and b.get("type") == "image_url") for b in blocks)
+
+    def test_uses_unknown_mime_type_when_missing(self):
+        mw = ViewImageMiddleware()
+        state = {
+            "viewed_images": {
+                "/mystery.bin": {"base64": "XYZ"},  # no mime_type key
+            }
+        }
+        blocks = mw._create_image_details_message(state)
+        # The description block should mention unknown
+        description_blocks = [b for b in blocks if b.get("type") == "text" and "/mystery.bin" in b.get("text", "")]
+        assert len(description_blocks) == 1
+        assert "unknown" in description_blocks[0]["text"]
+
+
+class TestShouldInjectImageMessage:
+    def test_false_when_no_messages(self):
+        mw = ViewImageMiddleware()
+        assert mw._should_inject_image_message({"messages": []}) is False
+
+    def test_false_when_messages_key_missing(self):
+        mw = ViewImageMiddleware()
+        assert mw._should_inject_image_message({}) is False
+
+    def test_false_when_no_assistant_message(self):
+        mw = ViewImageMiddleware()
+        state = {"messages": [HumanMessage(content="hello")]}
+        assert mw._should_inject_image_message(state) is False
+
+    def test_false_when_no_view_image_tool_call(self):
+        mw = ViewImageMiddleware()
+        assistant = AIMessage(content="", tool_calls=[_other_tool_call()])
+        state = {
+            "messages": [assistant, ToolMessage(content="ok", tool_call_id="call_other")],
+        }
+        assert mw._should_inject_image_message(state) is False
+
+    def test_false_when_tool_not_completed(self):
+        mw = ViewImageMiddleware()
+        assistant = AIMessage(content="", tool_calls=[_view_image_call("c1")])
+        state = {"messages": [assistant]}  # no ToolMessage yet
+        assert mw._should_inject_image_message(state) is False
+
+    def test_true_when_all_preconditions_met(self):
+        mw = ViewImageMiddleware()
+        assistant = AIMessage(content="", tool_calls=[_view_image_call("c1")])
+        state = {
+            "messages": [assistant, ToolMessage(content="ok", tool_call_id="c1")],
+            "viewed_images": {
+                "/img.png": {"base64": "AAA", "mime_type": "image/png"},
+            },
+        }
+        assert mw._should_inject_image_message(state) is True
+
+    def test_false_when_already_injected(self):
+        """If a HumanMessage with the recognized header is already present after
+        the assistant turn, we must not inject a duplicate."""
+        mw = ViewImageMiddleware()
+        assistant = AIMessage(content="", tool_calls=[_view_image_call("c1")])
+        already_injected = HumanMessage(content="Here are the images you've viewed: /img.png")
+        state = {
+            "messages": [
+                assistant,
+                ToolMessage(content="ok", tool_call_id="c1"),
+                already_injected,
+            ],
+            "viewed_images": {
+                "/img.png": {"base64": "AAA", "mime_type": "image/png"},
+            },
+        }
+        assert mw._should_inject_image_message(state) is False
+
+    def test_false_when_already_injected_with_list_content(self):
+        """Deduplication must recognize the real injected payload shape.
+
+        The middleware's own `_inject_image_message` creates a HumanMessage
+        whose `.content` is a *list* of dicts (text + image_url blocks), not a
+        plain string. This test reuses `_create_image_details_message` output
+        to reproduce the realistic shape and confirms `_should_inject_image_message`
+        still detects the marker via `str(msg.content)`.
+        """
+        mw = ViewImageMiddleware()
+        assistant = AIMessage(content="", tool_calls=[_view_image_call("c1")])
+        viewed_images = {"/img.png": {"base64": "AAA", "mime_type": "image/png"}}
+        # Build content the same way the middleware would.
+        real_injected_content = mw._create_image_details_message({"viewed_images": viewed_images})
+        # Sanity: this is a list of blocks, not a plain string.
+        assert isinstance(real_injected_content, list)
+        already_injected = HumanMessage(content=real_injected_content)
+
+        state = {
+            "messages": [
+                assistant,
+                ToolMessage(content="ok", tool_call_id="c1"),
+                already_injected,
+            ],
+            "viewed_images": viewed_images,
+        }
+        assert mw._should_inject_image_message(state) is False
+
+    def test_false_when_legacy_details_marker_present(self):
+        """The middleware also recognizes the legacy 'Here are the details of the
+        images you've viewed' marker as an already-injected signal."""
+        mw = ViewImageMiddleware()
+        assistant = AIMessage(content="", tool_calls=[_view_image_call("c1")])
+        legacy = HumanMessage(content="Here are the details of the images you've viewed: ...")
+        state = {
+            "messages": [
+                assistant,
+                ToolMessage(content="ok", tool_call_id="c1"),
+                legacy,
+            ],
+            "viewed_images": {
+                "/img.png": {"base64": "AAA", "mime_type": "image/png"},
+            },
+        }
+        assert mw._should_inject_image_message(state) is False
+
+
+class TestInjectImageMessage:
+    def test_returns_none_when_should_not_inject(self):
+        mw = ViewImageMiddleware()
+        state = {"messages": []}
+        assert mw._inject_image_message(state) is None
+
+    def test_returns_state_update_with_human_message(self):
+        mw = ViewImageMiddleware()
+        assistant = AIMessage(content="", tool_calls=[_view_image_call("c1")])
+        state = {
+            "messages": [assistant, ToolMessage(content="ok", tool_call_id="c1")],
+            "viewed_images": {
+                "/img.png": {"base64": "AAA", "mime_type": "image/png"},
+            },
+        }
+
+        result = mw._inject_image_message(state)
+
+        assert isinstance(result, dict)
+        assert "messages" in result
+        assert len(result["messages"]) == 1
+        injected = result["messages"][0]
+        assert isinstance(injected, HumanMessage)
+        # Mixed-content payload: list of text + image_url blocks
+        assert isinstance(injected.content, list)
+        assert any(isinstance(b, dict) and b.get("type") == "image_url" for b in injected.content)
+
+
+class TestBeforeModel:
+    def test_before_model_returns_none_when_preconditions_not_met(self):
+        mw = ViewImageMiddleware()
+        state = {"messages": [HumanMessage(content="hi")]}
+        assert mw.before_model(state, _runtime()) is None
+
+    def test_before_model_returns_injection_when_ready(self):
+        mw = ViewImageMiddleware()
+        assistant = AIMessage(content="", tool_calls=[_view_image_call("c1")])
+        state = {
+            "messages": [assistant, ToolMessage(content="ok", tool_call_id="c1")],
+            "viewed_images": {
+                "/img.png": {"base64": "AAA", "mime_type": "image/png"},
+            },
+        }
+        result = mw.before_model(state, _runtime())
+        assert result is not None
+        assert isinstance(result["messages"][0], HumanMessage)
+
+    @pytest.mark.anyio
+    async def test_abefore_model_matches_sync_behavior(self):
+        mw = ViewImageMiddleware()
+        assistant = AIMessage(content="", tool_calls=[_view_image_call("c1")])
+        state = {
+            "messages": [assistant, ToolMessage(content="ok", tool_call_id="c1")],
+            "viewed_images": {
+                "/img.png": {"base64": "AAA", "mime_type": "image/png"},
+            },
+        }
+        result = await mw.abefore_model(state, _runtime())
+        assert result is not None
+        assert isinstance(result["messages"][0], HumanMessage)
+
+    @pytest.mark.anyio
+    async def test_abefore_model_returns_none_when_no_injection(self):
+        mw = ViewImageMiddleware()
+        state = {"messages": []}
+        assert await mw.abefore_model(state, _runtime()) is None

backend/uv.lock

@@ -698,7 +698,7 @@ requires-dist = [
     { name = "langgraph-sdk", specifier = ">=0.1.51" },
     { name = "lark-oapi", specifier = ">=1.4.0" },
     { name = "markdown-to-mrkdwn", specifier = ">=0.3.1" },
-    { name = "python-multipart", specifier = ">=0.0.20" },
+    { name = "python-multipart", specifier = ">=0.0.26" },
     { name = "python-telegram-bot", specifier = ">=21.0" },
     { name = "slack-sdk", specifier = ">=3.33.0" },
     { name = "sse-starlette", specifier = ">=2.1.0" },
@@ -708,7 +708,7 @@ requires-dist = [
 
 [package.metadata.requires-dev]
 dev = [
-    { name = "pytest", specifier = ">=8.0.0" },
+    { name = "pytest", specifier = ">=9.0.3" },
     { name = "ruff", specifier = ">=0.14.11" },
 ]
 
@@ -1814,7 +1814,7 @@ wheels = [
 
 [[package]]
 name = "langsmith"
-version = "0.6.4"
+version = "0.7.31"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "httpx" },
@@ -1824,11 +1824,12 @@ dependencies = [
     { name = "requests" },
     { name = "requests-toolbelt" },
     { name = "uuid-utils" },
+    { name = "xxhash" },
     { name = "zstandard" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/e7/85/9c7933052a997da1b85bc5c774f3865e9b1da1c8d71541ea133178b13229/langsmith-0.6.4.tar.gz", hash = "sha256:36f7223a01c218079fbb17da5e536ebbaf5c1468c028abe070aa3ae59bc99ec8", size = 919964, upload-time = "2026-01-15T20:02:28.873Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/e6/11/696019490992db5c87774dc20515529ef42a01e1d770fb754ed6d9b12fb0/langsmith-0.7.31.tar.gz", hash = "sha256:331ee4f7c26bb5be4022b9859b7d7b122cbf8c9d01d9f530114c1914b0349ffb", size = 1178480, upload-time = "2026-04-14T17:55:41.242Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/66/0f/09a6637a7ba777eb307b7c80852d9ee26438e2bdafbad6fcc849ff9d9192/langsmith-0.6.4-py3-none-any.whl", hash = "sha256:ac4835860160be371042c7adbba3cb267bcf8d96a5ea976c33a8a4acad6c5486", size = 283503, upload-time = "2026-01-15T20:02:26.662Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/a1/a013cf458c301cda86a213dd153ce0a01c93f1ab5833f951e6a44c9763ce/langsmith-0.7.31-py3-none-any.whl", hash = "sha256:0291d49203f6e80dda011af1afda61eb0595a4d697adb684590a8805e1d61fb6", size = 373276, upload-time = "2026-04-14T17:55:39.677Z" },
 ]
 
 [package.optional-dependencies]
@@ -2614,71 +2615,71 @@ wheels = [
 
 [[package]]
 name = "pillow"
-version = "12.1.1"
+version = "12.2.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/1f/42/5c74462b4fd957fcd7b13b04fb3205ff8349236ea74c7c375766d6c82288/pillow-12.1.1.tar.gz", hash = "sha256:9ad8fa5937ab05218e2b6a4cff30295ad35afd2f83ac592e68c0d871bb0fdbc4", size = 46980264, upload-time = "2026-02-11T04:23:07.146Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/8c/21/c2bcdd5906101a30244eaffc1b6e6ce71a31bd0742a01eb89e660ebfac2d/pillow-12.2.0.tar.gz", hash = "sha256:a830b1a40919539d07806aa58e1b114df53ddd43213d9c8b75847eee6c0182b5", size = 46987819, upload-time = "2026-04-01T14:46:17.687Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/07/d3/8df65da0d4df36b094351dce696f2989bec731d4f10e743b1c5f4da4d3bf/pillow-12.1.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:ab323b787d6e18b3d91a72fc99b1a2c28651e4358749842b8f8dfacd28ef2052", size = 5262803, upload-time = "2026-02-11T04:20:47.653Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/71/5026395b290ff404b836e636f51d7297e6c83beceaa87c592718747e670f/pillow-12.1.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:adebb5bee0f0af4909c30db0d890c773d1a92ffe83da908e2e9e720f8edf3984", size = 4657601, upload-time = "2026-02-11T04:20:49.328Z" },
-    { url = "https://files.pythonhosted.org/packages/b1/2e/1001613d941c67442f745aff0f7cc66dd8df9a9c084eb497e6a543ee6f7e/pillow-12.1.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:bb66b7cc26f50977108790e2456b7921e773f23db5630261102233eb355a3b79", size = 6234995, upload-time = "2026-02-11T04:20:51.032Z" },
-    { url = "https://files.pythonhosted.org/packages/07/26/246ab11455b2549b9233dbd44d358d033a2f780fa9007b61a913c5b2d24e/pillow-12.1.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:aee2810642b2898bb187ced9b349e95d2a7272930796e022efaf12e99dccd293", size = 8045012, upload-time = "2026-02-11T04:20:52.882Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/8b/07587069c27be7535ac1fe33874e32de118fbd34e2a73b7f83436a88368c/pillow-12.1.1-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a0b1cd6232e2b618adcc54d9882e4e662a089d5768cd188f7c245b4c8c44a397", size = 6349638, upload-time = "2026-02-11T04:20:54.444Z" },
-    { url = "https://files.pythonhosted.org/packages/ff/79/6df7b2ee763d619cda2fb4fea498e5f79d984dae304d45a8999b80d6cf5c/pillow-12.1.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7aac39bcf8d4770d089588a2e1dd111cbaa42df5a94be3114222057d68336bd0", size = 7041540, upload-time = "2026-02-11T04:20:55.97Z" },
-    { url = "https://files.pythonhosted.org/packages/2c/5e/2ba19e7e7236d7529f4d873bdaf317a318896bac289abebd4bb00ef247f0/pillow-12.1.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:ab174cd7d29a62dd139c44bf74b698039328f45cb03b4596c43473a46656b2f3", size = 6462613, upload-time = "2026-02-11T04:20:57.542Z" },
-    { url = "https://files.pythonhosted.org/packages/03/03/31216ec124bb5c3dacd74ce8efff4cc7f52643653bad4825f8f08c697743/pillow-12.1.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:339ffdcb7cbeaa08221cd401d517d4b1fe7a9ed5d400e4a8039719238620ca35", size = 7166745, upload-time = "2026-02-11T04:20:59.196Z" },
-    { url = "https://files.pythonhosted.org/packages/1f/e7/7c4552d80052337eb28653b617eafdef39adfb137c49dd7e831b8dc13bc5/pillow-12.1.1-cp312-cp312-win32.whl", hash = "sha256:5d1f9575a12bed9e9eedd9a4972834b08c97a352bd17955ccdebfeca5913fa0a", size = 6328823, upload-time = "2026-02-11T04:21:01.385Z" },
-    { url = "https://files.pythonhosted.org/packages/3d/17/688626d192d7261bbbf98846fc98995726bddc2c945344b65bec3a29d731/pillow-12.1.1-cp312-cp312-win_amd64.whl", hash = "sha256:21329ec8c96c6e979cd0dfd29406c40c1d52521a90544463057d2aaa937d66a6", size = 7033367, upload-time = "2026-02-11T04:21:03.536Z" },
-    { url = "https://files.pythonhosted.org/packages/ed/fe/a0ef1f73f939b0eca03ee2c108d0043a87468664770612602c63266a43c4/pillow-12.1.1-cp312-cp312-win_arm64.whl", hash = "sha256:af9a332e572978f0218686636610555ae3defd1633597be015ed50289a03c523", size = 2453811, upload-time = "2026-02-11T04:21:05.116Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/11/6db24d4bd7685583caeae54b7009584e38da3c3d4488ed4cd25b439de486/pillow-12.1.1-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:d242e8ac078781f1de88bf823d70c1a9b3c7950a44cdf4b7c012e22ccbcd8e4e", size = 4062689, upload-time = "2026-02-11T04:21:06.804Z" },
-    { url = "https://files.pythonhosted.org/packages/33/c0/ce6d3b1fe190f0021203e0d9b5b99e57843e345f15f9ef22fcd43842fd21/pillow-12.1.1-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:02f84dfad02693676692746df05b89cf25597560db2857363a208e393429f5e9", size = 4138535, upload-time = "2026-02-11T04:21:08.452Z" },
-    { url = "https://files.pythonhosted.org/packages/a0/c6/d5eb6a4fb32a3f9c21a8c7613ec706534ea1cf9f4b3663e99f0d83f6fca8/pillow-12.1.1-cp313-cp313-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:e65498daf4b583091ccbb2556c7000abf0f3349fcd57ef7adc9a84a394ed29f6", size = 3601364, upload-time = "2026-02-11T04:21:10.194Z" },
-    { url = "https://files.pythonhosted.org/packages/14/a1/16c4b823838ba4c9c52c0e6bbda903a3fe5a1bdbf1b8eb4fff7156f3e318/pillow-12.1.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:6c6db3b84c87d48d0088943bf33440e0c42370b99b1c2a7989216f7b42eede60", size = 5262561, upload-time = "2026-02-11T04:21:11.742Z" },
-    { url = "https://files.pythonhosted.org/packages/bb/ad/ad9dc98ff24f485008aa5cdedaf1a219876f6f6c42a4626c08bc4e80b120/pillow-12.1.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:8b7e5304e34942bf62e15184219a7b5ad4ff7f3bb5cca4d984f37df1a0e1aee2", size = 4657460, upload-time = "2026-02-11T04:21:13.786Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/1b/f1a4ea9a895b5732152789326202a82464d5254759fbacae4deea3069334/pillow-12.1.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:18e5bddd742a44b7e6b1e773ab5db102bd7a94c32555ba656e76d319d19c3850", size = 6232698, upload-time = "2026-02-11T04:21:15.949Z" },
-    { url = "https://files.pythonhosted.org/packages/95/f4/86f51b8745070daf21fd2e5b1fe0eb35d4db9ca26e6d58366562fb56a743/pillow-12.1.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:fc44ef1f3de4f45b50ccf9136999d71abb99dca7706bc75d222ed350b9fd2289", size = 8041706, upload-time = "2026-02-11T04:21:17.723Z" },
-    { url = "https://files.pythonhosted.org/packages/29/9b/d6ecd956bb1266dd1045e995cce9b8d77759e740953a1c9aad9502a0461e/pillow-12.1.1-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5a8eb7ed8d4198bccbd07058416eeec51686b498e784eda166395a23eb99138e", size = 6346621, upload-time = "2026-02-11T04:21:19.547Z" },
-    { url = "https://files.pythonhosted.org/packages/71/24/538bff45bde96535d7d998c6fed1a751c75ac7c53c37c90dc2601b243893/pillow-12.1.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:47b94983da0c642de92ced1702c5b6c292a84bd3a8e1d1702ff923f183594717", size = 7038069, upload-time = "2026-02-11T04:21:21.378Z" },
-    { url = "https://files.pythonhosted.org/packages/94/0e/58cb1a6bc48f746bc4cb3adb8cabff73e2742c92b3bf7a220b7cf69b9177/pillow-12.1.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:518a48c2aab7ce596d3bf79d0e275661b846e86e4d0e7dec34712c30fe07f02a", size = 6460040, upload-time = "2026-02-11T04:21:23.148Z" },
-    { url = "https://files.pythonhosted.org/packages/6c/57/9045cb3ff11eeb6c1adce3b2d60d7d299d7b273a2e6c8381a524abfdc474/pillow-12.1.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:a550ae29b95c6dc13cf69e2c9dc5747f814c54eeb2e32d683e5e93af56caa029", size = 7164523, upload-time = "2026-02-11T04:21:25.01Z" },
-    { url = "https://files.pythonhosted.org/packages/73/f2/9be9cb99f2175f0d4dbadd6616ce1bf068ee54a28277ea1bf1fbf729c250/pillow-12.1.1-cp313-cp313-win32.whl", hash = "sha256:a003d7422449f6d1e3a34e3dd4110c22148336918ddbfc6a32581cd54b2e0b2b", size = 6332552, upload-time = "2026-02-11T04:21:27.238Z" },
-    { url = "https://files.pythonhosted.org/packages/3f/eb/b0834ad8b583d7d9d42b80becff092082a1c3c156bb582590fcc973f1c7c/pillow-12.1.1-cp313-cp313-win_amd64.whl", hash = "sha256:344cf1e3dab3be4b1fa08e449323d98a2a3f819ad20f4b22e77a0ede31f0faa1", size = 7040108, upload-time = "2026-02-11T04:21:29.462Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/7d/fc09634e2aabdd0feabaff4a32f4a7d97789223e7c2042fd805ea4b4d2c2/pillow-12.1.1-cp313-cp313-win_arm64.whl", hash = "sha256:5c0dd1636633e7e6a0afe7bf6a51a14992b7f8e60de5789018ebbdfae55b040a", size = 2453712, upload-time = "2026-02-11T04:21:31.072Z" },
-    { url = "https://files.pythonhosted.org/packages/19/2a/b9d62794fc8a0dd14c1943df68347badbd5511103e0d04c035ffe5cf2255/pillow-12.1.1-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:0330d233c1a0ead844fc097a7d16c0abff4c12e856c0b325f231820fee1f39da", size = 5264880, upload-time = "2026-02-11T04:21:32.865Z" },
-    { url = "https://files.pythonhosted.org/packages/26/9d/e03d857d1347fa5ed9247e123fcd2a97b6220e15e9cb73ca0a8d91702c6e/pillow-12.1.1-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:5dae5f21afb91322f2ff791895ddd8889e5e947ff59f71b46041c8ce6db790bc", size = 4660616, upload-time = "2026-02-11T04:21:34.97Z" },
-    { url = "https://files.pythonhosted.org/packages/f7/ec/8a6d22afd02570d30954e043f09c32772bfe143ba9285e2fdb11284952cd/pillow-12.1.1-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:2e0c664be47252947d870ac0d327fea7e63985a08794758aa8af5b6cb6ec0c9c", size = 6269008, upload-time = "2026-02-11T04:21:36.623Z" },
-    { url = "https://files.pythonhosted.org/packages/3d/1d/6d875422c9f28a4a361f495a5f68d9de4a66941dc2c619103ca335fa6446/pillow-12.1.1-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:691ab2ac363b8217f7d31b3497108fb1f50faab2f75dfb03284ec2f217e87bf8", size = 8073226, upload-time = "2026-02-11T04:21:38.585Z" },
-    { url = "https://files.pythonhosted.org/packages/a1/cd/134b0b6ee5eda6dc09e25e24b40fdafe11a520bc725c1d0bbaa5e00bf95b/pillow-12.1.1-cp313-cp313t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e9e8064fb1cc019296958595f6db671fba95209e3ceb0c4734c9baf97de04b20", size = 6380136, upload-time = "2026-02-11T04:21:40.562Z" },
-    { url = "https://files.pythonhosted.org/packages/7a/a9/7628f013f18f001c1b98d8fffe3452f306a70dc6aba7d931019e0492f45e/pillow-12.1.1-cp313-cp313t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:472a8d7ded663e6162dafdf20015c486a7009483ca671cece7a9279b512fcb13", size = 7067129, upload-time = "2026-02-11T04:21:42.521Z" },
-    { url = "https://files.pythonhosted.org/packages/1e/f8/66ab30a2193b277785601e82ee2d49f68ea575d9637e5e234faaa98efa4c/pillow-12.1.1-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:89b54027a766529136a06cfebeecb3a04900397a3590fd252160b888479517bf", size = 6491807, upload-time = "2026-02-11T04:21:44.22Z" },
-    { url = "https://files.pythonhosted.org/packages/da/0b/a877a6627dc8318fdb84e357c5e1a758c0941ab1ddffdafd231983788579/pillow-12.1.1-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:86172b0831b82ce4f7877f280055892b31179e1576aa00d0df3bb1bbf8c3e524", size = 7190954, upload-time = "2026-02-11T04:21:46.114Z" },
-    { url = "https://files.pythonhosted.org/packages/83/43/6f732ff85743cf746b1361b91665d9f5155e1483817f693f8d57ea93147f/pillow-12.1.1-cp313-cp313t-win32.whl", hash = "sha256:44ce27545b6efcf0fdbdceb31c9a5bdea9333e664cda58a7e674bb74608b3986", size = 6336441, upload-time = "2026-02-11T04:21:48.22Z" },
-    { url = "https://files.pythonhosted.org/packages/3b/44/e865ef3986611bb75bfabdf94a590016ea327833f434558801122979cd0e/pillow-12.1.1-cp313-cp313t-win_amd64.whl", hash = "sha256:a285e3eb7a5a45a2ff504e31f4a8d1b12ef62e84e5411c6804a42197c1cf586c", size = 7045383, upload-time = "2026-02-11T04:21:50.015Z" },
-    { url = "https://files.pythonhosted.org/packages/a8/c6/f4fb24268d0c6908b9f04143697ea18b0379490cb74ba9e8d41b898bd005/pillow-12.1.1-cp313-cp313t-win_arm64.whl", hash = "sha256:cc7d296b5ea4d29e6570dabeaed58d31c3fea35a633a69679fb03d7664f43fb3", size = 2456104, upload-time = "2026-02-11T04:21:51.633Z" },
-    { url = "https://files.pythonhosted.org/packages/03/d0/bebb3ffbf31c5a8e97241476c4cf8b9828954693ce6744b4a2326af3e16b/pillow-12.1.1-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:417423db963cb4be8bac3fc1204fe61610f6abeed1580a7a2cbb2fbda20f12af", size = 4062652, upload-time = "2026-02-11T04:21:53.19Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/c0/0e16fb0addda4851445c28f8350d8c512f09de27bbb0d6d0bbf8b6709605/pillow-12.1.1-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:b957b71c6b2387610f556a7eb0828afbe40b4a98036fc0d2acfa5a44a0c2036f", size = 4138823, upload-time = "2026-02-11T04:22:03.088Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/fb/6170ec655d6f6bb6630a013dd7cf7bc218423d7b5fa9071bf63dc32175ae/pillow-12.1.1-cp314-cp314-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:097690ba1f2efdeb165a20469d59d8bb03c55fb6621eb2041a060ae8ea3e9642", size = 3601143, upload-time = "2026-02-11T04:22:04.909Z" },
-    { url = "https://files.pythonhosted.org/packages/59/04/dc5c3f297510ba9a6837cbb318b87dd2b8f73eb41a43cc63767f65cb599c/pillow-12.1.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:2815a87ab27848db0321fb78c7f0b2c8649dee134b7f2b80c6a45c6831d75ccd", size = 5266254, upload-time = "2026-02-11T04:22:07.656Z" },
-    { url = "https://files.pythonhosted.org/packages/05/30/5db1236b0d6313f03ebf97f5e17cda9ca060f524b2fcc875149a8360b21c/pillow-12.1.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:f7ed2c6543bad5a7d5530eb9e78c53132f93dfa44a28492db88b41cdab885202", size = 4657499, upload-time = "2026-02-11T04:22:09.613Z" },
-    { url = "https://files.pythonhosted.org/packages/6f/18/008d2ca0eb612e81968e8be0bbae5051efba24d52debf930126d7eaacbba/pillow-12.1.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:652a2c9ccfb556235b2b501a3a7cf3742148cd22e04b5625c5fe057ea3e3191f", size = 6232137, upload-time = "2026-02-11T04:22:11.434Z" },
-    { url = "https://files.pythonhosted.org/packages/70/f1/f14d5b8eeb4b2cd62b9f9f847eb6605f103df89ef619ac68f92f748614ea/pillow-12.1.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:d6e4571eedf43af33d0fc233a382a76e849badbccdf1ac438841308652a08e1f", size = 8042721, upload-time = "2026-02-11T04:22:13.321Z" },
-    { url = "https://files.pythonhosted.org/packages/5a/d6/17824509146e4babbdabf04d8171491fa9d776f7061ff6e727522df9bd03/pillow-12.1.1-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b574c51cf7d5d62e9be37ba446224b59a2da26dc4c1bb2ecbe936a4fb1a7cb7f", size = 6347798, upload-time = "2026-02-11T04:22:15.449Z" },
-    { url = "https://files.pythonhosted.org/packages/d1/ee/c85a38a9ab92037a75615aba572c85ea51e605265036e00c5b67dfafbfe2/pillow-12.1.1-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a37691702ed687799de29a518d63d4682d9016932db66d4e90c345831b02fb4e", size = 7039315, upload-time = "2026-02-11T04:22:17.24Z" },
-    { url = "https://files.pythonhosted.org/packages/ec/f3/bc8ccc6e08a148290d7523bde4d9a0d6c981db34631390dc6e6ec34cacf6/pillow-12.1.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:f95c00d5d6700b2b890479664a06e754974848afaae5e21beb4d83c106923fd0", size = 6462360, upload-time = "2026-02-11T04:22:19.111Z" },
-    { url = "https://files.pythonhosted.org/packages/f6/ab/69a42656adb1d0665ab051eec58a41f169ad295cf81ad45406963105408f/pillow-12.1.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:559b38da23606e68681337ad74622c4dbba02254fc9cb4488a305dd5975c7eeb", size = 7165438, upload-time = "2026-02-11T04:22:21.041Z" },
-    { url = "https://files.pythonhosted.org/packages/02/46/81f7aa8941873f0f01d4b55cc543b0a3d03ec2ee30d617a0448bf6bd6dec/pillow-12.1.1-cp314-cp314-win32.whl", hash = "sha256:03edcc34d688572014ff223c125a3f77fb08091e4607e7745002fc214070b35f", size = 6431503, upload-time = "2026-02-11T04:22:22.833Z" },
-    { url = "https://files.pythonhosted.org/packages/40/72/4c245f7d1044b67affc7f134a09ea619d4895333d35322b775b928180044/pillow-12.1.1-cp314-cp314-win_amd64.whl", hash = "sha256:50480dcd74fa63b8e78235957d302d98d98d82ccbfac4c7e12108ba9ecbdba15", size = 7176748, upload-time = "2026-02-11T04:22:24.64Z" },
-    { url = "https://files.pythonhosted.org/packages/e4/ad/8a87bdbe038c5c698736e3348af5c2194ffb872ea52f11894c95f9305435/pillow-12.1.1-cp314-cp314-win_arm64.whl", hash = "sha256:5cb1785d97b0c3d1d1a16bc1d710c4a0049daefc4935f3a8f31f827f4d3d2e7f", size = 2544314, upload-time = "2026-02-11T04:22:26.685Z" },
-    { url = "https://files.pythonhosted.org/packages/6c/9d/efd18493f9de13b87ede7c47e69184b9e859e4427225ea962e32e56a49bc/pillow-12.1.1-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:1f90cff8aa76835cba5769f0b3121a22bd4eb9e6884cfe338216e557a9a548b8", size = 5268612, upload-time = "2026-02-11T04:22:29.884Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/f1/4f42eb2b388eb2ffc660dcb7f7b556c1015c53ebd5f7f754965ef997585b/pillow-12.1.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:1f1be78ce9466a7ee64bfda57bdba0f7cc499d9794d518b854816c41bf0aa4e9", size = 4660567, upload-time = "2026-02-11T04:22:31.799Z" },
-    { url = "https://files.pythonhosted.org/packages/01/54/df6ef130fa43e4b82e32624a7b821a2be1c5653a5fdad8469687a7db4e00/pillow-12.1.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:42fc1f4677106188ad9a55562bbade416f8b55456f522430fadab3cef7cd4e60", size = 6269951, upload-time = "2026-02-11T04:22:33.921Z" },
-    { url = "https://files.pythonhosted.org/packages/a9/48/618752d06cc44bb4aae8ce0cd4e6426871929ed7b46215638088270d9b34/pillow-12.1.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:98edb152429ab62a1818039744d8fbb3ccab98a7c29fc3d5fcef158f3f1f68b7", size = 8074769, upload-time = "2026-02-11T04:22:35.877Z" },
-    { url = "https://files.pythonhosted.org/packages/c3/bd/f1d71eb39a72fa088d938655afba3e00b38018d052752f435838961127d8/pillow-12.1.1-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d470ab1178551dd17fdba0fef463359c41aaa613cdcd7ff8373f54be629f9f8f", size = 6381358, upload-time = "2026-02-11T04:22:37.698Z" },
-    { url = "https://files.pythonhosted.org/packages/64/ef/c784e20b96674ed36a5af839305f55616f8b4f8aa8eeccf8531a6e312243/pillow-12.1.1-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6408a7b064595afcab0a49393a413732a35788f2a5092fdc6266952ed67de586", size = 7068558, upload-time = "2026-02-11T04:22:39.597Z" },
-    { url = "https://files.pythonhosted.org/packages/73/cb/8059688b74422ae61278202c4e1ad992e8a2e7375227be0a21c6b87ca8d5/pillow-12.1.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:5d8c41325b382c07799a3682c1c258469ea2ff97103c53717b7893862d0c98ce", size = 6493028, upload-time = "2026-02-11T04:22:42.73Z" },
-    { url = "https://files.pythonhosted.org/packages/c6/da/e3c008ed7d2dd1f905b15949325934510b9d1931e5df999bb15972756818/pillow-12.1.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:c7697918b5be27424e9ce568193efd13d925c4481dd364e43f5dff72d33e10f8", size = 7191940, upload-time = "2026-02-11T04:22:44.543Z" },
-    { url = "https://files.pythonhosted.org/packages/01/4a/9202e8d11714c1fc5951f2e1ef362f2d7fbc595e1f6717971d5dd750e969/pillow-12.1.1-cp314-cp314t-win32.whl", hash = "sha256:d2912fd8114fc5545aa3a4b5576512f64c55a03f3ebcca4c10194d593d43ea36", size = 6438736, upload-time = "2026-02-11T04:22:46.347Z" },
-    { url = "https://files.pythonhosted.org/packages/f3/ca/cbce2327eb9885476b3957b2e82eb12c866a8b16ad77392864ad601022ce/pillow-12.1.1-cp314-cp314t-win_amd64.whl", hash = "sha256:4ceb838d4bd9dab43e06c363cab2eebf63846d6a4aeaea283bbdfd8f1a8ed58b", size = 7182894, upload-time = "2026-02-11T04:22:48.114Z" },
-    { url = "https://files.pythonhosted.org/packages/ec/d2/de599c95ba0a973b94410477f8bf0b6f0b5e67360eb89bcb1ad365258beb/pillow-12.1.1-cp314-cp314t-win_arm64.whl", hash = "sha256:7b03048319bfc6170e93bd60728a1af51d3dd7704935feb228c4d4faab35d334", size = 2546446, upload-time = "2026-02-11T04:22:50.342Z" },
+    { url = "https://files.pythonhosted.org/packages/58/be/7482c8a5ebebbc6470b3eb791812fff7d5e0216c2be3827b30b8bb6603ed/pillow-12.2.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:2d192a155bbcec180f8564f693e6fd9bccff5a7af9b32e2e4bf8c9c69dbad6b5", size = 5308279, upload-time = "2026-04-01T14:43:13.246Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/95/0a351b9289c2b5cbde0bacd4a83ebc44023e835490a727b2a3bd60ddc0f4/pillow-12.2.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:f3f40b3c5a968281fd507d519e444c35f0ff171237f4fdde090dd60699458421", size = 4695490, upload-time = "2026-04-01T14:43:15.584Z" },
+    { url = "https://files.pythonhosted.org/packages/de/af/4e8e6869cbed569d43c416fad3dc4ecb944cb5d9492defaed89ddd6fe871/pillow-12.2.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:03e7e372d5240cc23e9f07deca4d775c0817bffc641b01e9c3af208dbd300987", size = 6284462, upload-time = "2026-04-01T14:43:18.268Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/9e/c05e19657fd57841e476be1ab46c4d501bffbadbafdc31a6d665f8b737b6/pillow-12.2.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:b86024e52a1b269467a802258c25521e6d742349d760728092e1bc2d135b4d76", size = 8094744, upload-time = "2026-04-01T14:43:20.716Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/54/1789c455ed10176066b6e7e6da1b01e50e36f94ba584dc68d9eebfe9156d/pillow-12.2.0-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7371b48c4fa448d20d2714c9a1f775a81155050d383333e0a6c15b1123dda005", size = 6398371, upload-time = "2026-04-01T14:43:23.443Z" },
+    { url = "https://files.pythonhosted.org/packages/43/e3/fdc657359e919462369869f1c9f0e973f353f9a9ee295a39b1fea8ee1a77/pillow-12.2.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:62f5409336adb0663b7caa0da5c7d9e7bdbaae9ce761d34669420c2a801b2780", size = 7087215, upload-time = "2026-04-01T14:43:26.758Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/f8/2f6825e441d5b1959d2ca5adec984210f1ec086435b0ed5f52c19b3b8a6e/pillow-12.2.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:01afa7cf67f74f09523699b4e88c73fb55c13346d212a59a2db1f86b0a63e8c5", size = 6509783, upload-time = "2026-04-01T14:43:29.56Z" },
+    { url = "https://files.pythonhosted.org/packages/67/f9/029a27095ad20f854f9dba026b3ea6428548316e057e6fc3545409e86651/pillow-12.2.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fc3d34d4a8fbec3e88a79b92e5465e0f9b842b628675850d860b8bd300b159f5", size = 7212112, upload-time = "2026-04-01T14:43:32.091Z" },
+    { url = "https://files.pythonhosted.org/packages/be/42/025cfe05d1be22dbfdb4f264fe9de1ccda83f66e4fc3aac94748e784af04/pillow-12.2.0-cp312-cp312-win32.whl", hash = "sha256:58f62cc0f00fd29e64b29f4fd923ffdb3859c9f9e6105bfc37ba1d08994e8940", size = 6378489, upload-time = "2026-04-01T14:43:34.601Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/7b/25a221d2c761c6a8ae21bfa3874988ff2583e19cf8a27bf2fee358df7942/pillow-12.2.0-cp312-cp312-win_amd64.whl", hash = "sha256:7f84204dee22a783350679a0333981df803dac21a0190d706a50475e361c93f5", size = 7084129, upload-time = "2026-04-01T14:43:37.213Z" },
+    { url = "https://files.pythonhosted.org/packages/10/e1/542a474affab20fd4a0f1836cb234e8493519da6b76899e30bcc5d990b8b/pillow-12.2.0-cp312-cp312-win_arm64.whl", hash = "sha256:af73337013e0b3b46f175e79492d96845b16126ddf79c438d7ea7ff27783a414", size = 2463612, upload-time = "2026-04-01T14:43:39.421Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/01/53d10cf0dbad820a8db274d259a37ba50b88b24768ddccec07355382d5ad/pillow-12.2.0-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:8297651f5b5679c19968abefd6bb84d95fe30ef712eb1b2d9b2d31ca61267f4c", size = 4100837, upload-time = "2026-04-01T14:43:41.506Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/98/f3a6657ecb698c937f6c76ee564882945f29b79bad496abcba0e84659ec5/pillow-12.2.0-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:50d8520da2a6ce0af445fa6d648c4273c3eeefbc32d7ce049f22e8b5c3daecc2", size = 4176528, upload-time = "2026-04-01T14:43:43.773Z" },
+    { url = "https://files.pythonhosted.org/packages/69/bc/8986948f05e3ea490b8442ea1c1d4d990b24a7e43d8a51b2c7d8b1dced36/pillow-12.2.0-cp313-cp313-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:766cef22385fa1091258ad7e6216792b156dc16d8d3fa607e7545b2b72061f1c", size = 3640401, upload-time = "2026-04-01T14:43:45.87Z" },
+    { url = "https://files.pythonhosted.org/packages/34/46/6c717baadcd62bc8ed51d238d521ab651eaa74838291bda1f86fe1f864c9/pillow-12.2.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:5d2fd0fa6b5d9d1de415060363433f28da8b1526c1c129020435e186794b3795", size = 5308094, upload-time = "2026-04-01T14:43:48.438Z" },
+    { url = "https://files.pythonhosted.org/packages/71/43/905a14a8b17fdb1ccb58d282454490662d2cb89a6bfec26af6d3520da5ec/pillow-12.2.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:56b25336f502b6ed02e889f4ece894a72612fe885889a6e8c4c80239ff6e5f5f", size = 4695402, upload-time = "2026-04-01T14:43:51.292Z" },
+    { url = "https://files.pythonhosted.org/packages/73/dd/42107efcb777b16fa0393317eac58f5b5cf30e8392e266e76e51cff28c3d/pillow-12.2.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:f1c943e96e85df3d3478f7b691f229887e143f81fedab9b20205349ab04d73ed", size = 6280005, upload-time = "2026-04-01T14:43:54.242Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/68/b93e09e5e8549019e61acf49f65b1a8530765a7f812c77a7461bca7e4494/pillow-12.2.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:03f6fab9219220f041c74aeaa2939ff0062bd5c364ba9ce037197f4c6d498cd9", size = 8090669, upload-time = "2026-04-01T14:43:57.335Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/6e/3ccb54ce8ec4ddd1accd2d89004308b7b0b21c4ac3d20fa70af4760a4330/pillow-12.2.0-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5cdfebd752ec52bf5bb4e35d9c64b40826bc5b40a13df7c3cda20a2c03a0f5ed", size = 6395194, upload-time = "2026-04-01T14:43:59.864Z" },
+    { url = "https://files.pythonhosted.org/packages/67/ee/21d4e8536afd1a328f01b359b4d3997b291ffd35a237c877b331c1c3b71c/pillow-12.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:eedf4b74eda2b5a4b2b2fb4c006d6295df3bf29e459e198c90ea48e130dc75c3", size = 7082423, upload-time = "2026-04-01T14:44:02.74Z" },
+    { url = "https://files.pythonhosted.org/packages/78/5f/e9f86ab0146464e8c133fe85df987ed9e77e08b29d8d35f9f9f4d6f917ba/pillow-12.2.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:00a2865911330191c0b818c59103b58a5e697cae67042366970a6b6f1b20b7f9", size = 6505667, upload-time = "2026-04-01T14:44:05.381Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/1e/409007f56a2fdce61584fd3acbc2bbc259857d555196cedcadc68c015c82/pillow-12.2.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:1e1757442ed87f4912397c6d35a0db6a7b52592156014706f17658ff58bbf795", size = 7208580, upload-time = "2026-04-01T14:44:08.39Z" },
+    { url = "https://files.pythonhosted.org/packages/23/c4/7349421080b12fb35414607b8871e9534546c128a11965fd4a7002ccfbee/pillow-12.2.0-cp313-cp313-win32.whl", hash = "sha256:144748b3af2d1b358d41286056d0003f47cb339b8c43a9ea42f5fea4d8c66b6e", size = 6375896, upload-time = "2026-04-01T14:44:11.197Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/82/8a3739a5e470b3c6cbb1d21d315800d8e16bff503d1f16b03a4ec3212786/pillow-12.2.0-cp313-cp313-win_amd64.whl", hash = "sha256:390ede346628ccc626e5730107cde16c42d3836b89662a115a921f28440e6a3b", size = 7081266, upload-time = "2026-04-01T14:44:13.947Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/25/f968f618a062574294592f668218f8af564830ccebdd1fa6200f598e65c5/pillow-12.2.0-cp313-cp313-win_arm64.whl", hash = "sha256:8023abc91fba39036dbce14a7d6535632f99c0b857807cbbbf21ecc9f4717f06", size = 2463508, upload-time = "2026-04-01T14:44:16.312Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/a4/b342930964e3cb4dce5038ae34b0eab4653334995336cd486c5a8c25a00c/pillow-12.2.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:042db20a421b9bafecc4b84a8b6e444686bd9d836c7fd24542db3e7df7baad9b", size = 5309927, upload-time = "2026-04-01T14:44:18.89Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/de/23198e0a65a9cf06123f5435a5d95cea62a635697f8f03d134d3f3a96151/pillow-12.2.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:dd025009355c926a84a612fecf58bb315a3f6814b17ead51a8e48d3823d9087f", size = 4698624, upload-time = "2026-04-01T14:44:21.115Z" },
+    { url = "https://files.pythonhosted.org/packages/01/a6/1265e977f17d93ea37aa28aa81bad4fa597933879fac2520d24e021c8da3/pillow-12.2.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:88ddbc66737e277852913bd1e07c150cc7bb124539f94c4e2df5344494e0a612", size = 6321252, upload-time = "2026-04-01T14:44:23.663Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/83/5982eb4a285967baa70340320be9f88e57665a387e3a53a7f0db8231a0cd/pillow-12.2.0-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:d362d1878f00c142b7e1a16e6e5e780f02be8195123f164edf7eddd911eefe7c", size = 8126550, upload-time = "2026-04-01T14:44:26.772Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/48/6ffc514adce69f6050d0753b1a18fd920fce8cac87620d5a31231b04bfc5/pillow-12.2.0-cp313-cp313t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2c727a6d53cb0018aadd8018c2b938376af27914a68a492f59dfcaca650d5eea", size = 6433114, upload-time = "2026-04-01T14:44:29.615Z" },
+    { url = "https://files.pythonhosted.org/packages/36/a3/f9a77144231fb8d40ee27107b4463e205fa4677e2ca2548e14da5cf18dce/pillow-12.2.0-cp313-cp313t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:efd8c21c98c5cc60653bcb311bef2ce0401642b7ce9d09e03a7da87c878289d4", size = 7115667, upload-time = "2026-04-01T14:44:32.773Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/fc/ac4ee3041e7d5a565e1c4fd72a113f03b6394cc72ab7089d27608f8aaccb/pillow-12.2.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:9f08483a632889536b8139663db60f6724bfcb443c96f1b18855860d7d5c0fd4", size = 6538966, upload-time = "2026-04-01T14:44:35.252Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/a8/27fb307055087f3668f6d0a8ccb636e7431d56ed0750e07a60547b1e083e/pillow-12.2.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:dac8d77255a37e81a2efcbd1fc05f1c15ee82200e6c240d7e127e25e365c39ea", size = 7238241, upload-time = "2026-04-01T14:44:37.875Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/4b/926ab182c07fccae9fcb120043464e1ff1564775ec8864f21a0ebce6ac25/pillow-12.2.0-cp313-cp313t-win32.whl", hash = "sha256:ee3120ae9dff32f121610bb08e4313be87e03efeadfc6c0d18f89127e24d0c24", size = 6379592, upload-time = "2026-04-01T14:44:40.336Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/c4/f9e476451a098181b30050cc4c9a3556b64c02cf6497ea421ac047e89e4b/pillow-12.2.0-cp313-cp313t-win_amd64.whl", hash = "sha256:325ca0528c6788d2a6c3d40e3568639398137346c3d6e66bb61db96b96511c98", size = 7085542, upload-time = "2026-04-01T14:44:43.251Z" },
+    { url = "https://files.pythonhosted.org/packages/00/a4/285f12aeacbe2d6dc36c407dfbbe9e96d4a80b0fb710a337f6d2ad978c75/pillow-12.2.0-cp313-cp313t-win_arm64.whl", hash = "sha256:2e5a76d03a6c6dcef67edabda7a52494afa4035021a79c8558e14af25313d453", size = 2465765, upload-time = "2026-04-01T14:44:45.996Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/98/4595daa2365416a86cb0d495248a393dfc84e96d62ad080c8546256cb9c0/pillow-12.2.0-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:3adc9215e8be0448ed6e814966ecf3d9952f0ea40eb14e89a102b87f450660d8", size = 4100848, upload-time = "2026-04-01T14:44:48.48Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/79/40184d464cf89f6663e18dfcf7ca21aae2491fff1a16127681bf1fa9b8cf/pillow-12.2.0-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:6a9adfc6d24b10f89588096364cc726174118c62130c817c2837c60cf08a392b", size = 4176515, upload-time = "2026-04-01T14:44:51.353Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/63/703f86fd4c422a9cf722833670f4f71418fb116b2853ff7da722ea43f184/pillow-12.2.0-cp314-cp314-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:6a6e67ea2e6feda684ed370f9a1c52e7a243631c025ba42149a2cc5934dec295", size = 3640159, upload-time = "2026-04-01T14:44:53.588Z" },
+    { url = "https://files.pythonhosted.org/packages/71/e0/fb22f797187d0be2270f83500aab851536101b254bfa1eae10795709d283/pillow-12.2.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:2bb4a8d594eacdfc59d9e5ad972aa8afdd48d584ffd5f13a937a664c3e7db0ed", size = 5312185, upload-time = "2026-04-01T14:44:56.039Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/8c/1a9e46228571de18f8e28f16fabdfc20212a5d019f3e3303452b3f0a580d/pillow-12.2.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:80b2da48193b2f33ed0c32c38140f9d3186583ce7d516526d462645fd98660ae", size = 4695386, upload-time = "2026-04-01T14:44:58.663Z" },
+    { url = "https://files.pythonhosted.org/packages/70/62/98f6b7f0c88b9addd0e87c217ded307b36be024d4ff8869a812b241d1345/pillow-12.2.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:22db17c68434de69d8ecfc2fe821569195c0c373b25cccb9cbdacf2c6e53c601", size = 6280384, upload-time = "2026-04-01T14:45:01.5Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/03/688747d2e91cfbe0e64f316cd2e8005698f76ada3130d0194664174fa5de/pillow-12.2.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7b14cc0106cd9aecda615dd6903840a058b4700fcb817687d0ee4fc8b6e389be", size = 8091599, upload-time = "2026-04-01T14:45:04.5Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/35/577e22b936fcdd66537329b33af0b4ccfefaeabd8aec04b266528cddb33c/pillow-12.2.0-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8cbeb542b2ebc6fcdacabf8aca8c1a97c9b3ad3927d46b8723f9d4f033288a0f", size = 6396021, upload-time = "2026-04-01T14:45:07.117Z" },
+    { url = "https://files.pythonhosted.org/packages/11/8d/d2532ad2a603ca2b93ad9f5135732124e57811d0168155852f37fbce2458/pillow-12.2.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4bfd07bc812fbd20395212969e41931001fd59eb55a60658b0e5710872e95286", size = 7083360, upload-time = "2026-04-01T14:45:09.763Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/26/d325f9f56c7e039034897e7380e9cc202b1e368bfd04d4cbe6a441f02885/pillow-12.2.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:9aba9a17b623ef750a4d11b742cbafffeb48a869821252b30ee21b5e91392c50", size = 6507628, upload-time = "2026-04-01T14:45:12.378Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/f7/769d5632ffb0988f1c5e7660b3e731e30f7f8ec4318e94d0a5d674eb65a4/pillow-12.2.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:deede7c263feb25dba4e82ea23058a235dcc2fe1f6021025dc71f2b618e26104", size = 7209321, upload-time = "2026-04-01T14:45:15.122Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/7a/c253e3c645cd47f1aceea6a8bacdba9991bf45bb7dfe927f7c893e89c93c/pillow-12.2.0-cp314-cp314-win32.whl", hash = "sha256:632ff19b2778e43162304d50da0181ce24ac5bb8180122cbe1bf4673428328c7", size = 6479723, upload-time = "2026-04-01T14:45:17.797Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/8b/601e6566b957ca50e28725cb6c355c59c2c8609751efbecd980db44e0349/pillow-12.2.0-cp314-cp314-win_amd64.whl", hash = "sha256:4e6c62e9d237e9b65fac06857d511e90d8461a32adcc1b9065ea0c0fa3a28150", size = 7217400, upload-time = "2026-04-01T14:45:20.529Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/94/220e46c73065c3e2951bb91c11a1fb636c8c9ad427ac3ce7d7f3359b9b2f/pillow-12.2.0-cp314-cp314-win_arm64.whl", hash = "sha256:b1c1fbd8a5a1af3412a0810d060a78b5136ec0836c8a4ef9aa11807f2a22f4e1", size = 2554835, upload-time = "2026-04-01T14:45:23.162Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/ab/1b426a3974cb0e7da5c29ccff4807871d48110933a57207b5a676cccc155/pillow-12.2.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:57850958fe9c751670e49b2cecf6294acc99e562531f4bd317fa5ddee2068463", size = 5314225, upload-time = "2026-04-01T14:45:25.637Z" },
+    { url = "https://files.pythonhosted.org/packages/19/1e/dce46f371be2438eecfee2a1960ee2a243bbe5e961890146d2dee1ff0f12/pillow-12.2.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:d5d38f1411c0ed9f97bcb49b7bd59b6b7c314e0e27420e34d99d844b9ce3b6f3", size = 4698541, upload-time = "2026-04-01T14:45:28.355Z" },
+    { url = "https://files.pythonhosted.org/packages/55/c3/7fbecf70adb3a0c33b77a300dc52e424dc22ad8cdc06557a2e49523b703d/pillow-12.2.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:5c0a9f29ca8e79f09de89293f82fc9b0270bb4af1d58bc98f540cc4aedf03166", size = 6322251, upload-time = "2026-04-01T14:45:30.924Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/3c/7fbc17cfb7e4fe0ef1642e0abc17fc6c94c9f7a16be41498e12e2ba60408/pillow-12.2.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:1610dd6c61621ae1cf811bef44d77e149ce3f7b95afe66a4512f8c59f25d9ebe", size = 8127807, upload-time = "2026-04-01T14:45:33.908Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/c3/a8ae14d6defd2e448493ff512fae903b1e9bd40b72efb6ec55ce0048c8ce/pillow-12.2.0-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0a34329707af4f73cf1782a36cd2289c0368880654a2c11f027bcee9052d35dd", size = 6433935, upload-time = "2026-04-01T14:45:36.623Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/32/2880fb3a074847ac159d8f902cb43278a61e85f681661e7419e6596803ed/pillow-12.2.0-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8e9c4f5b3c546fa3458a29ab22646c1c6c787ea8f5ef51300e5a60300736905e", size = 7116720, upload-time = "2026-04-01T14:45:39.258Z" },
+    { url = "https://files.pythonhosted.org/packages/46/87/495cc9c30e0129501643f24d320076f4cc54f718341df18cc70ec94c44e1/pillow-12.2.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:fb043ee2f06b41473269765c2feae53fc2e2fbf96e5e22ca94fb5ad677856f06", size = 6540498, upload-time = "2026-04-01T14:45:41.879Z" },
+    { url = "https://files.pythonhosted.org/packages/18/53/773f5edca692009d883a72211b60fdaf8871cbef075eaa9d577f0a2f989e/pillow-12.2.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:f278f034eb75b4e8a13a54a876cc4a5ab39173d2cdd93a638e1b467fc545ac43", size = 7239413, upload-time = "2026-04-01T14:45:44.705Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/e4/4b64a97d71b2a83158134abbb2f5bd3f8a2ea691361282f010998f339ec7/pillow-12.2.0-cp314-cp314t-win32.whl", hash = "sha256:6bb77b2dcb06b20f9f4b4a8454caa581cd4dd0643a08bacf821216a16d9c8354", size = 6482084, upload-time = "2026-04-01T14:45:47.568Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/13/306d275efd3a3453f72114b7431c877d10b1154014c1ebbedd067770d629/pillow-12.2.0-cp314-cp314t-win_amd64.whl", hash = "sha256:6562ace0d3fb5f20ed7290f1f929cae41b25ae29528f2af1722966a0a02e2aa1", size = 7225152, upload-time = "2026-04-01T14:45:50.032Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/6e/cf826fae916b8658848d7b9f38d88da6396895c676e8086fc0988073aaf8/pillow-12.2.0-cp314-cp314t-win_arm64.whl", hash = "sha256:aa88ccfe4e32d362816319ed727a004423aab09c5cea43c01a4b435643fa34eb", size = 2556579, upload-time = "2026-04-01T14:45:52.529Z" },
 ]
 
 [[package]]
@@ -3098,7 +3099,7 @@ wheels = [
 
 [[package]]
 name = "pytest"
-version = "9.0.2"
+version = "9.0.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "colorama", marker = "sys_platform == 'win32'" },
@@ -3107,9 +3108,9 @@ dependencies = [
     { name = "pluggy" },
     { name = "pygments" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/d1/db/7ef3487e0fb0049ddb5ce41d3a49c235bf9ad299b6a25d5780a89f19230f/pytest-9.0.2.tar.gz", hash = "sha256:75186651a92bd89611d1d9fc20f0b4345fd827c41ccd5c299a868a05d70edf11", size = 1568901, upload-time = "2025-12-06T21:30:51.014Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/7d/0d/549bd94f1a0a402dc8cf64563a117c0f3765662e2e668477624baeec44d5/pytest-9.0.3.tar.gz", hash = "sha256:b86ada508af81d19edeb213c681b1d48246c1a91d304c6c81a427674c17eb91c", size = 1572165, upload-time = "2026-04-07T17:16:18.027Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/3b/ab/b3226f0bd7cdcf710fbede2b3548584366da3b19b5021e74f5bde2a8fa3f/pytest-9.0.2-py3-none-any.whl", hash = "sha256:711ffd45bf766d5264d487b917733b453d917afd2b0ad65223959f59089f875b", size = 374801, upload-time = "2025-12-06T21:30:49.154Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl", hash = "sha256:2c5efc453d45394fdd706ade797c0a81091eccd1d6e4bccfcd476e2b8e0ab5d9", size = 375249, upload-time = "2026-04-07T17:16:16.13Z" },
 ]
 
 [[package]]
@@ -3135,11 +3136,11 @@ wheels = [
 
 [[package]]
 name = "python-multipart"
-version = "0.0.22"
+version = "0.0.26"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/94/01/979e98d542a70714b0cb2b6728ed0b7c46792b695e3eaec3e20711271ca3/python_multipart-0.0.22.tar.gz", hash = "sha256:7340bef99a7e0032613f56dc36027b959fd3b30a787ed62d310e951f7c3a3a58", size = 37612, upload-time = "2026-01-25T10:15:56.219Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/88/71/b145a380824a960ebd60e1014256dbb7d2253f2316ff2d73dfd8928ec2c3/python_multipart-0.0.26.tar.gz", hash = "sha256:08fadc45918cd615e26846437f50c5d6d23304da32c341f289a617127b081f17", size = 43501, upload-time = "2026-04-10T14:09:59.473Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/1b/d0/397f9626e711ff749a95d96b7af99b9c566a9bb5129b8e4c10fc4d100304/python_multipart-0.0.22-py3-none-any.whl", hash = "sha256:2b2cd894c83d21bf49d702499531c7bafd057d730c201782048f7945d82de155", size = 24579, upload-time = "2026-01-25T10:15:54.811Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/22/f1925cdda983ab66fc8ec6ec8014b959262747e58bdca26a4e3d1da29d56/python_multipart-0.0.26-py3-none-any.whl", hash = "sha256:c0b169f8c4484c13b0dcf2ef0ec3a4adb255c4b7d18d8e420477d2b1dd03f185", size = 28847, upload-time = "2026-04-10T14:09:58.131Z" },
 ]
 
 [[package]]

config.example.yaml

@@ -12,7 +12,7 @@
 # ============================================================================
 # Bump this number when the config schema changes.
 # Run `make config-upgrade` to merge new fields into your local config.yaml.
-config_version: 6
+config_version: 7
 
 # ============================================================================
 # Logging
@@ -21,10 +21,11 @@ config_version: 6
 log_level: info
 
 # ============================================================================
-# Token Usage Tracking
+# Token Usage
 # ============================================================================
-# Track LLM token usage per model call (input/output/total tokens)
-# Logs at info level via TokenUsageMiddleware
+# Enable token usage collection and display.
+# When enabled, DeerFlow records input/output/total tokens per model call
+# and shows usage metadata in the workspace UI when providers return it.
 token_usage:
   enabled: false
 
@@ -479,7 +480,13 @@ tool_search:
 # Option 1: Local Sandbox (Default)
 # Executes commands directly on the host machine
 uploads:
-  # PDF-to-Markdown converter used when a PDF is uploaded.
+  # Automatic Office/PDF conversion runs on the backend host before sandbox
+  # isolation applies. Keep this disabled unless uploads come from a fully
+  # trusted source and you intentionally accept host-side parser risk.
+  auto_convert_documents: false
+  # Controls which PDF-to-Markdown converter is used whenever PDF conversion
+  # runs. Automatic upload conversion is gated separately by
+  # auto_convert_documents.
   # auto        — prefer pymupdf4llm when installed; fall back to MarkItDown for
   #               image-based or encrypted PDFs (recommended default).
   # pymupdf4llm — always use pymupdf4llm (must be installed: uv add pymupdf4llm).
@@ -708,6 +715,14 @@ memory:
   injection_enabled: true # Whether to inject memory into system prompt
   max_injection_tokens: 2000 # Maximum tokens for memory injection
 
+# ============================================================================
+# Custom Agent Management API
+# ============================================================================
+# Controls whether the HTTP gateway exposes custom-agent SOUL/USER.md management.
+# Keep this disabled unless the gateway is behind a trusted authenticated admin boundary.
+agents_api:
+  enabled: false
+
 # ============================================================================
 # Skill Self-Evolution Configuration
 # ============================================================================
@@ -883,3 +898,20 @@ checkpointer:
 #     use: my_package:MyGuardrailProvider
 #     config:
 #       key: value
+
+# ============================================================================
+# Circuit Breaker Configuration
+# ============================================================================
+# Circuit breaker for LLM calls prevents repeated requests to a failing provider.
+# When the failure threshold is reached, subsequent calls fast-fail until recovery.
+#
+# This is useful for:
+# - Avoiding rate-limit bans during provider outages
+# - Reducing resource exhaustion from retry loops
+# - Gracefully degrading when LLM services are unavailable
+
+# circuit_breaker:
+#   # Number of consecutive failures before opening the circuit (default: 5)
+#   failure_threshold: 5
+#   # Time in seconds before attempting to recover (default: 60)
+#   recovery_timeout_sec: 60

frontend/AGENTS.md

@@ -36,6 +36,9 @@ DeerFlow is built on a sophisticated agent-based architecture using the [LangGra
 ## Project Structure
 
 ```
+tests/
+├── e2e/                    # E2E tests (Playwright, Chromium, mocked backend)
+└── unit/                   # Unit tests (mirrors src/ layout, powered by Vitest)
 src/
 ├── app/                    # Next.js App Router pages
 │   ├── api/                # API routes
@@ -96,7 +99,7 @@ When adding new agent features:
 1. Follow the established project structure
 2. Add comprehensive TypeScript types
 3. Implement proper error handling
-4. Write tests for new functionality
+4. Write unit tests under `tests/unit/` (run with `pnpm test`) and E2E tests under `tests/e2e/` (run with `pnpm test:e2e`)
 5. Update this documentation
 6. Follow the code style guide (ESLint + Prettier)
 

frontend/CLAUDE.md

@@ -17,10 +17,14 @@ DeerFlow Frontend is a Next.js 16 web interface for an AI agent system. It commu
 | `pnpm check`     | Lint + type check (run before committing)         |
 | `pnpm lint`      | ESLint only                                       |
 | `pnpm lint:fix`  | ESLint with auto-fix                              |
+| `pnpm test`      | Run unit tests with Vitest                        |
+| `pnpm test:e2e`  | Run E2E tests with Playwright (Chromium)          |
 | `pnpm typecheck` | TypeScript type check (`tsc --noEmit`)            |
 | `pnpm start`     | Start production server                           |
 
-No test framework is configured.
+Unit tests live under `tests/unit/` and mirror the `src/` layout (e.g., `tests/unit/core/api/stream-mode.test.ts` tests `src/core/api/stream-mode.ts`). Powered by Vitest; import source modules via the `@/` path alias.
+
+E2E tests live under `tests/e2e/` and use Playwright with Chromium. They mock all backend APIs via `page.route()` network interception and test real page interactions (navigation, chat input, streaming responses). Config: `playwright.config.ts`.
 
 ## Architecture
 

frontend/Makefile

@@ -7,6 +7,12 @@ build:
 dev:
 	pnpm dev
 
+test:
+	pnpm test
+
+test-e2e:
+	pnpm test:e2e
+
 lint:
 	pnpm lint
 

frontend/README.md

@@ -35,7 +35,7 @@ pnpm dev
 # The app will be available at http://localhost:3000
 ```
 
-### Build
+### Build & Test
 
 ```bash
 # Type check
@@ -50,6 +50,15 @@ pnpm format:write
 # Lint
 pnpm lint
 
+# Run unit tests
+pnpm test
+
+# One-time setup: install Playwright Chromium browser
+pnpm exec playwright install chromium
+
+# Run E2E tests (builds and starts production server automatically)
+pnpm test:e2e
+
 # Build for production
 pnpm build
 
@@ -82,6 +91,9 @@ NEXT_PUBLIC_LANGGRAPH_BASE_URL="http://localhost:2024"
 ## Project Structure
 
 ```
+tests/
+├── e2e/                    # E2E tests (Playwright, Chromium, mocked backend)
+└── unit/                   # Unit tests (mirrors src/ layout)
 src/
 ├── app/                    # Next.js App Router pages
 │   ├── api/                # API routes
@@ -119,6 +131,8 @@ src/
 | `pnpm dev`          | Start development server with Turbopack |
 | `pnpm build`        | Build for production                    |
 | `pnpm start`        | Start production server                 |
+| `pnpm test`         | Run unit tests with Vitest              |
+| `pnpm test:e2e`     | Run E2E tests with Playwright           |
 | `pnpm format`       | Check formatting with Prettier          |
 | `pnpm format:write` | Apply formatting with Prettier          |
 | `pnpm lint`         | Run ESLint                              |

frontend/next.config.js

@@ -52,6 +52,26 @@ const config = {
         source: "/api/agents/:path*",
         destination: `${gatewayURL}/api/agents/:path*`,
       });
+      rewrites.push({
+        source: "/api/skills",
+        destination: `${gatewayURL}/api/skills`,
+      });
+      rewrites.push({
+        source: "/api/skills/:path*",
+        destination: `${gatewayURL}/api/skills/:path*`,
+      });
+
+      // Catch-all for remaining gateway API routes (models, threads, memory,
+      // mcp, artifacts, uploads, suggestions, runs, etc.) that don't have
+      // their own NEXT_PUBLIC_* env var toggle.
+      //
+      // NOTE: this must come AFTER the /api/langgraph rewrite above so that
+      // LangGraph routes are matched first when NEXT_PUBLIC_LANGGRAPH_BASE_URL
+      // is unset.
+      rewrites.push({
+        source: "/api/:path*",
+        destination: `${gatewayURL}/api/:path*`,
+      });
     }
 
     return rewrites;

frontend/package.json

@@ -14,6 +14,8 @@
     "lint:fix": "eslint . --ext .ts,.tsx --fix",
     "preview": "next build && next start",
     "start": "next start",
+    "test": "vitest run",
+    "test:e2e": "playwright test",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
@@ -92,6 +94,7 @@
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
+    "@playwright/test": "^1.59.1",
     "@tailwindcss/postcss": "^4.0.15",
     "@types/gsap": "^3.0.0",
     "@types/node": "^20.14.10",
@@ -105,7 +108,8 @@
     "tailwindcss": "^4.0.15",
     "tw-animate-css": "^1.4.0",
     "typescript": "^5.8.2",
-    "typescript-eslint": "^8.27.0"
+    "typescript-eslint": "^8.27.0",
+    "vitest": "^4.1.4"
   },
   "ct3aMetadata": {
     "initVersion": "7.40.0"

frontend/playwright.config.ts

@@ -0,0 +1,33 @@
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./tests/e2e",
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: process.env.CI ? "github" : "html",
+  timeout: 30_000,
+
+  use: {
+    baseURL: "http://localhost:3000",
+    trace: "on-first-retry",
+  },
+
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+
+  webServer: {
+    command: "pnpm build && pnpm start",
+    url: "http://localhost:3000",
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+    env: {
+      SKIP_ENV_VALIDATION: "1",
+    },
+  },
+});

frontend/src/app/workspace/agents/[agent_name]/chats/[thread_id]/page.tsx

@@ -23,6 +23,7 @@ import { TokenUsageIndicator } from "@/components/workspace/token-usage-indicato
 import { Tooltip } from "@/components/workspace/tooltip";
 import { useAgent } from "@/core/agents";
 import { useI18n } from "@/core/i18n/hooks";
+import { useModels } from "@/core/models/hooks";
 import { useNotification } from "@/core/notification/hooks";
 import { useThreadSettings } from "@/core/settings";
 import { useThreadStream } from "@/core/threads/hooks";
@@ -44,6 +45,7 @@ export default function AgentChatPage() {
   const { threadId, setThreadId, isNewThread, setIsNewThread } =
     useThreadChat();
   const [settings, setSettings] = useThreadSettings(threadId);
+  const { tokenUsageEnabled } = useModels();
 
   const { showNotification } = useNotification();
   const [thread, sendMessage] = useThreadStream({
@@ -128,7 +130,10 @@ export default function AgentChatPage() {
                   <PlusSquare /> {t.agents.newChat}
                 </Button>
               </Tooltip>
-              <TokenUsageIndicator messages={thread.messages} />
+              <TokenUsageIndicator
+                enabled={tokenUsageEnabled}
+                messages={thread.messages}
+              />
               <ExportTrigger threadId={threadId} />
               <ArtifactTrigger />
             </div>
@@ -141,6 +146,7 @@ export default function AgentChatPage() {
                 threadId={threadId}
                 thread={thread}
                 paddingBottom={messageListPaddingBottom}
+                tokenUsageEnabled={tokenUsageEnabled}
               />
             </div>
 

frontend/src/app/workspace/chats/[thread_id]/page.tsx

@@ -22,6 +22,7 @@ import { TodoList } from "@/components/workspace/todo-list";
 import { TokenUsageIndicator } from "@/components/workspace/token-usage-indicator";
 import { Welcome } from "@/components/workspace/welcome";
 import { useI18n } from "@/core/i18n/hooks";
+import { useModels } from "@/core/models/hooks";
 import { useNotification } from "@/core/notification/hooks";
 import { useThreadSettings } from "@/core/settings";
 import { useThreadStream } from "@/core/threads/hooks";
@@ -36,6 +37,7 @@ export default function ChatPage() {
     useThreadChat();
   const [settings, setSettings] = useThreadSettings(threadId);
   const [mounted, setMounted] = useState(false);
+  const { tokenUsageEnabled } = useModels();
   useSpecificChatMode();
 
   useEffect(() => {
@@ -103,7 +105,10 @@ export default function ChatPage() {
               <ThreadTitle threadId={threadId} thread={thread} />
             </div>
             <div className="flex items-center gap-2">
-              <TokenUsageIndicator messages={thread.messages} />
+              <TokenUsageIndicator
+                enabled={tokenUsageEnabled}
+                messages={thread.messages}
+              />
               <ExportTrigger threadId={threadId} />
               <ArtifactTrigger />
             </div>
@@ -115,6 +120,7 @@ export default function ChatPage() {
                 threadId={threadId}
                 thread={thread}
                 paddingBottom={messageListPaddingBottom}
+                tokenUsageEnabled={tokenUsageEnabled}
               />
             </div>
             <div className="absolute right-0 bottom-0 left-0 z-30 flex justify-center px-4">

frontend/src/components/ai-elements/suggestion.tsx

@@ -64,7 +64,7 @@ export const Suggestion = ({
   return (
     <Button
       className={cn(
-        "text-muted-foreground h-auto max-w-full cursor-pointer rounded-full px-4 py-2 text-center text-xs font-normal whitespace-normal",
+        "text-muted-foreground dark:bg-background h-auto max-w-full cursor-pointer rounded-full px-4 py-2 text-center text-xs font-normal whitespace-normal",
         className,
       )}
       onClick={handleClick}

frontend/src/components/workspace/messages/message-group.tsx

@@ -336,7 +336,7 @@ function ToolCall({
       description = t.toolCalls.writeFile;
     }
     const path: string | undefined = (args as { path: string })?.path;
-    if (isLoading && isLast && autoOpen && autoSelect && path) {
+    if (isLoading && isLast && autoOpen && autoSelect && path && !result) {
       setTimeout(() => {
         const url = new URL(
           `write-file:${path}?message_id=${messageId}&tool_call_id=${id}`,

frontend/src/components/workspace/messages/message-list-item.tsx

@@ -1,6 +1,11 @@
 import type { Message } from "@langchain/langgraph-sdk";
 import { FileIcon, Loader2Icon } from "lucide-react";
-import { memo, useMemo, type ImgHTMLAttributes } from "react";
+import {
+  memo,
+  useMemo,
+  type AnchorHTMLAttributes,
+  type ImgHTMLAttributes,
+} from "react";
 import rehypeKatex from "rehype-katex";
 
 import { Loader } from "@/components/ai-elements/loader";
@@ -33,17 +38,20 @@ import { cn } from "@/lib/utils";
 import { CopyButton } from "../copy-button";
 
 import { MarkdownContent } from "./markdown-content";
+import { MessageTokenUsage } from "./message-token-usage";
 
 export function MessageListItem({
   className,
   message,
   isLoading,
   threadId,
+  tokenUsageEnabled = false,
 }: {
   className?: string;
   message: Message;
   isLoading?: boolean;
   threadId: string;
+  tokenUsageEnabled?: boolean;
 }) {
   const isHuman = message.type === "human";
   return (
@@ -56,6 +64,7 @@ export function MessageListItem({
         message={message}
         isLoading={isLoading}
         threadId={threadId}
+        tokenUsageEnabled={tokenUsageEnabled}
       />
       {!isLoading && (
         <MessageToolbar
@@ -114,11 +123,13 @@ function MessageContent_({
   message,
   isLoading = false,
   threadId,
+  tokenUsageEnabled = false,
 }: {
   className?: string;
   message: Message;
   isLoading?: boolean;
   threadId: string;
+  tokenUsageEnabled?: boolean;
 }) {
   const rehypePlugins = useRehypeSplitWordsIntoSpans(isLoading);
   const isHuman = message.type === "human";
@@ -127,6 +138,20 @@ function MessageContent_({
       img: (props: ImgHTMLAttributes<HTMLImageElement>) => (
         <MessageImage {...props} threadId={threadId} maxWidth="90%" />
       ),
+      a: ({ href, ...props }: AnchorHTMLAttributes<HTMLAnchorElement>) => {
+        if (href?.startsWith("/mnt/")) {
+          const url = resolveArtifactURL(href, threadId);
+          return (
+            <a
+              {...props}
+              href={url}
+              target="_blank"
+              rel="noopener noreferrer"
+            />
+          );
+        }
+        return <a {...props} href={href} />;
+      },
     }),
     [threadId],
   );
@@ -182,6 +207,11 @@ function MessageContent_({
           <ReasoningTrigger />
           <ReasoningContent>{reasoningContent}</ReasoningContent>
         </Reasoning>
+        <MessageTokenUsage
+          enabled={tokenUsageEnabled}
+          isLoading={isLoading}
+          message={message}
+        />
       </AIElementMessageContent>
     );
   }
@@ -219,6 +249,11 @@ function MessageContent_({
         className="my-3"
         components={components}
       />
+      <MessageTokenUsage
+        enabled={tokenUsageEnabled}
+        isLoading={isLoading}
+        message={message}
+      />
     </AIElementMessageContent>
   );
 }

frontend/src/components/workspace/messages/message-list.tsx

@@ -13,6 +13,7 @@ import {
   hasContent,
   hasPresentFiles,
   hasReasoning,
+  hasToolCalls,
 } from "@/core/messages/utils";
 import { useRehypeSplitWordsIntoSpans } from "@/core/rehype";
 import type { Subtask } from "@/core/tasks";
@@ -26,6 +27,7 @@ import { StreamingIndicator } from "../streaming-indicator";
 import { MarkdownContent } from "./markdown-content";
 import { MessageGroup } from "./message-group";
 import { MessageListItem } from "./message-list-item";
+import { MessageTokenUsageList } from "./message-token-usage";
 import { MessageListSkeleton } from "./skeleton";
 import { SubtaskCard } from "./subtask-card";
 
@@ -37,11 +39,13 @@ export function MessageList({
   threadId,
   thread,
   paddingBottom = MESSAGE_LIST_DEFAULT_PADDING_BOTTOM,
+  tokenUsageEnabled = false,
 }: {
   className?: string;
   threadId: string;
   thread: BaseStream<AgentThreadState>;
   paddingBottom?: number;
+  tokenUsageEnabled?: boolean;
 }) {
   const { t } = useI18n();
   const rehypePlugins = useRehypeSplitWordsIntoSpans(thread.isLoading);
@@ -64,6 +68,7 @@ export function MessageList({
                   message={msg}
                   isLoading={thread.isLoading}
                   threadId={threadId}
+                  tokenUsageEnabled={tokenUsageEnabled}
                 />
               );
             });
@@ -71,12 +76,18 @@ export function MessageList({
             const message = group.messages[0];
             if (message && hasContent(message)) {
               return (
-                <MarkdownContent
-                  key={group.id}
-                  content={extractContentFromMessage(message)}
-                  isLoading={thread.isLoading}
-                  rehypePlugins={rehypePlugins}
-                />
+                <div key={group.id} className="w-full">
+                  <MarkdownContent
+                    content={extractContentFromMessage(message)}
+                    isLoading={thread.isLoading}
+                    rehypePlugins={rehypePlugins}
+                  />
+                  <MessageTokenUsageList
+                    enabled={tokenUsageEnabled}
+                    isLoading={thread.isLoading}
+                    messages={group.messages}
+                  />
+                </div>
               );
             }
             return null;
@@ -99,6 +110,11 @@ export function MessageList({
                   />
                 )}
                 <ArtifactFileList files={files} threadId={threadId} />
+                <MessageTokenUsageList
+                  enabled={tokenUsageEnabled}
+                  isLoading={thread.isLoading}
+                  messages={group.messages}
+                />
               </div>
             );
           } else if (group.type === "assistant:subagent") {
@@ -191,15 +207,31 @@ export function MessageList({
                 className="relative z-1 flex flex-col gap-2"
               >
                 {results}
+                <MessageTokenUsageList
+                  enabled={tokenUsageEnabled}
+                  isLoading={thread.isLoading}
+                  messages={group.messages}
+                />
               </div>
             );
           }
+          const tokenUsageMessages = group.messages.filter(
+            (message) =>
+              message.type === "ai" &&
+              (hasToolCalls(message) ? true : !hasContent(message)),
+          );
           return (
-            <MessageGroup
-              key={"group-" + group.id}
-              messages={group.messages}
-              isLoading={thread.isLoading}
-            />
+            <div key={"group-" + group.id} className="w-full">
+              <MessageGroup
+                messages={group.messages}
+                isLoading={thread.isLoading}
+              />
+              <MessageTokenUsageList
+                enabled={tokenUsageEnabled}
+                isLoading={thread.isLoading}
+                messages={tokenUsageMessages}
+              />
+            </div>
           );
         })}
         {thread.isLoading && <StreamingIndicator className="my-4" />}

frontend/src/components/workspace/messages/message-token-usage.tsx

@@ -0,0 +1,91 @@
+import type { Message } from "@langchain/langgraph-sdk";
+import { CoinsIcon } from "lucide-react";
+
+import { useI18n } from "@/core/i18n/hooks";
+import { formatTokenCount, getUsageMetadata } from "@/core/messages/usage";
+import { cn } from "@/lib/utils";
+
+export function MessageTokenUsage({
+  className,
+  enabled = false,
+  isLoading = false,
+  message,
+}: {
+  className?: string;
+  enabled?: boolean;
+  isLoading?: boolean;
+  message: Message;
+}) {
+  const { t } = useI18n();
+
+  if (!enabled || isLoading || message.type !== "ai") {
+    return null;
+  }
+
+  const usage = getUsageMetadata(message);
+
+  return (
+    <div
+      className={cn(
+        "text-muted-foreground border-border/60 mt-1 flex flex-wrap items-center gap-x-3 gap-y-1 border-t pt-2 text-[11px]",
+        className,
+      )}
+    >
+      <span className="inline-flex items-center gap-1 font-medium">
+        <CoinsIcon className="size-3" />
+        {t.tokenUsage.label}
+      </span>
+      {usage ? (
+        <>
+          <span>
+            {t.tokenUsage.input}: {formatTokenCount(usage.inputTokens)}
+          </span>
+          <span>
+            {t.tokenUsage.output}: {formatTokenCount(usage.outputTokens)}
+          </span>
+          <span className="font-medium">
+            {t.tokenUsage.total}: {formatTokenCount(usage.totalTokens)}
+          </span>
+        </>
+      ) : (
+        <span>{t.tokenUsage.unavailableShort}</span>
+      )}
+    </div>
+  );
+}
+
+export function MessageTokenUsageList({
+  className,
+  enabled = false,
+  isLoading = false,
+  messages,
+}: {
+  className?: string;
+  enabled?: boolean;
+  isLoading?: boolean;
+  messages: Message[];
+}) {
+  if (!enabled || isLoading) {
+    return null;
+  }
+
+  const aiMessages = messages.filter((message) => message.type === "ai");
+
+  if (aiMessages.length === 0) {
+    return null;
+  }
+
+  return (
+    <>
+      {aiMessages.map((message, index) => (
+        <MessageTokenUsage
+          className={className}
+          enabled={enabled}
+          isLoading={isLoading}
+          key={message.id ?? index}
+          message={message}
+        />
+      ))}
+    </>
+  );
+}

frontend/src/components/workspace/token-usage-indicator.tsx

@@ -15,18 +15,20 @@ import { cn } from "@/lib/utils";
 
 interface TokenUsageIndicatorProps {
   messages: Message[];
+  enabled?: boolean;
   className?: string;
 }
 
 export function TokenUsageIndicator({
   messages,
+  enabled = false,
   className,
 }: TokenUsageIndicatorProps) {
   const { t } = useI18n();
 
   const usage = useMemo(() => accumulateUsage(messages), [messages]);
 
-  if (!usage) {
+  if (!enabled) {
     return null;
   }
 
@@ -36,37 +38,49 @@ export function TokenUsageIndicator({
         <button
           type="button"
           className={cn(
-            "text-muted-foreground flex cursor-default items-center gap-1 text-xs",
+            "text-muted-foreground bg-background/70 flex cursor-default items-center gap-1.5 rounded-full border px-2 py-1 text-xs",
+            !usage && "opacity-60",
             className,
           )}
         >
           <CoinsIcon size={14} />
-          <span>{formatTokenCount(usage.totalTokens)}</span>
+          <span>{t.tokenUsage.label}</span>
+          <span className="font-mono">
+            {usage ? formatTokenCount(usage.totalTokens) : "-"}
+          </span>
         </button>
       </TooltipTrigger>
       <TooltipContent side="bottom" align="end">
         <div className="space-y-1 text-xs">
           <div className="font-medium">{t.tokenUsage.title}</div>
-          <div className="flex justify-between gap-4">
-            <span>{t.tokenUsage.input}</span>
-            <span className="font-mono">
-              {formatTokenCount(usage.inputTokens)}
-            </span>
-          </div>
-          <div className="flex justify-between gap-4">
-            <span>{t.tokenUsage.output}</span>
-            <span className="font-mono">
-              {formatTokenCount(usage.outputTokens)}
-            </span>
-          </div>
-          <div className="border-t pt-1">
-            <div className="flex justify-between gap-4">
-              <span>{t.tokenUsage.total}</span>
-              <span className="font-mono font-medium">
-                {formatTokenCount(usage.totalTokens)}
-              </span>
+          {usage ? (
+            <>
+              <div className="flex justify-between gap-4">
+                <span>{t.tokenUsage.input}</span>
+                <span className="font-mono">
+                  {formatTokenCount(usage.inputTokens)}
+                </span>
+              </div>
+              <div className="flex justify-between gap-4">
+                <span>{t.tokenUsage.output}</span>
+                <span className="font-mono">
+                  {formatTokenCount(usage.outputTokens)}
+                </span>
+              </div>
+              <div className="border-t pt-1">
+                <div className="flex justify-between gap-4">
+                  <span>{t.tokenUsage.total}</span>
+                  <span className="font-mono font-medium">
+                    {formatTokenCount(usage.totalTokens)}
+                  </span>
+                </div>
+              </div>
+            </>
+          ) : (
+            <div className="text-muted-foreground max-w-56">
+              {t.tokenUsage.unavailable}
             </div>
-          </div>
+          )}
         </div>
       </TooltipContent>
     </Tooltip>

frontend/src/core/api/stream-mode.test.ts

@@ -1,43 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-
-const { sanitizeRunStreamOptions } = await import(
-  new URL("./stream-mode.ts", import.meta.url).href
-);
-
-void test("drops unsupported stream modes from array payloads", () => {
-  const sanitized = sanitizeRunStreamOptions({
-    streamMode: [
-      "values",
-      "messages-tuple",
-      "custom",
-      "updates",
-      "events",
-      "tools",
-    ],
-  });
-
-  assert.deepEqual(sanitized.streamMode, [
-    "values",
-    "messages-tuple",
-    "custom",
-    "updates",
-    "events",
-  ]);
-});
-
-void test("drops unsupported stream modes from scalar payloads", () => {
-  const sanitized = sanitizeRunStreamOptions({
-    streamMode: "tools",
-  });
-
-  assert.equal(sanitized.streamMode, undefined);
-});
-
-void test("keeps payloads without streamMode untouched", () => {
-  const options = {
-    streamSubgraphs: true,
-  };
-
-  assert.equal(sanitizeRunStreamOptions(options), options);
-});

frontend/src/core/i18n/locales/en-US.ts

@@ -298,9 +298,13 @@ export const enUS: Translations = {
   // Token Usage
   tokenUsage: {
     title: "Token Usage",
+    label: "Tokens",
     input: "Input",
     output: "Output",
     total: "Total",
+    unavailable:
+      "No token usage yet. Usage appears only after a successful model response when the provider returns usage_metadata.",
+    unavailableShort: "No usage returned",
   },
 
   // Shortcuts

frontend/src/core/i18n/locales/types.ts

@@ -229,9 +229,12 @@ export interface Translations {
   // Token Usage
   tokenUsage: {
     title: string;
+    label: string;
     input: string;
     output: string;
     total: string;
+    unavailable: string;
+    unavailableShort: string;
   };
 
   // Shortcuts

frontend/src/core/i18n/locales/zh-CN.ts

@@ -284,9 +284,13 @@ export const zhCN: Translations = {
   // Token Usage
   tokenUsage: {
     title: "Token 用量",
+    label: "Tokens",
     input: "输入",
     output: "输出",
     total: "总计",
+    unavailable:
+      "暂无 Token 用量。只有模型成功返回且供应商提供 usage_metadata 时才会显示。",
+    unavailableShort: "未返回用量",
   },
 
   // Shortcuts

frontend/src/core/messages/usage.ts

@@ -10,7 +10,7 @@ export interface TokenUsage {
  * Extract usage_metadata from an AI message if present.
  * The field is added by the backend (PR #1218) but not typed in the SDK.
  */
-function getUsageMetadata(message: Message): TokenUsage | null {
+export function getUsageMetadata(message: Message): TokenUsage | null {
   if (message.type !== "ai") {
     return null;
   }

frontend/src/core/models/api.ts

@@ -1,9 +1,12 @@
 import { getBackendBaseURL } from "../config";
 
-import type { Model } from "./types";
+import type { ModelsResponse } from "./types";
 
-export async function loadModels() {
+export async function loadModels(): Promise<ModelsResponse> {
   const res = await fetch(`${getBackendBaseURL()}/api/models`);
-  const { models } = (await res.json()) as { models: Model[] };
-  return models;
+  const data = (await res.json()) as Partial<ModelsResponse>;
+  return {
+    models: data.models ?? [],
+    token_usage: data.token_usage ?? { enabled: false },
+  };
 }

frontend/src/core/models/hooks.ts

@@ -9,5 +9,10 @@ export function useModels({ enabled = true }: { enabled?: boolean } = {}) {
     enabled,
     refetchOnWindowFocus: false,
   });
-  return { models: data ?? [], isLoading, error };
+  return {
+    models: data?.models ?? [],
+    tokenUsageEnabled: data?.token_usage.enabled ?? false,
+    isLoading,
+    error,
+  };
 }

frontend/src/core/models/types.ts

@@ -7,3 +7,12 @@ export interface Model {
   supports_thinking?: boolean;
   supports_reasoning_effort?: boolean;
 }
+
+export interface TokenUsageSettings {
+  enabled: boolean;
+}
+
+export interface ModelsResponse {
+  models: Model[];
+  token_usage: TokenUsageSettings;
+}

frontend/src/core/threads/utils.test.ts

@@ -1,54 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-
-const { pathOfThread } = await import(
-  new URL("./utils.ts", import.meta.url).href
-);
-
-void test("uses standard chat route when thread has no agent context", () => {
-  assert.equal(pathOfThread("thread-123"), "/workspace/chats/thread-123");
-  assert.equal(
-    pathOfThread({
-      thread_id: "thread-123",
-    }),
-    "/workspace/chats/thread-123",
-  );
-});
-
-void test("uses agent chat route when thread context has agent_name", () => {
-  assert.equal(
-    pathOfThread({
-      thread_id: "thread-123",
-      context: { agent_name: "researcher" },
-    }),
-    "/workspace/agents/researcher/chats/thread-123",
-  );
-});
-
-void test("uses provided context when pathOfThread is called with a thread id", () => {
-  assert.equal(
-    pathOfThread("thread-123", { agent_name: "ops agent" }),
-    "/workspace/agents/ops%20agent/chats/thread-123",
-  );
-});
-
-void test("uses agent chat route when thread metadata has agent_name", () => {
-  assert.equal(
-    pathOfThread({
-      thread_id: "thread-456",
-      metadata: { agent_name: "coder" },
-    }),
-    "/workspace/agents/coder/chats/thread-456",
-  );
-});
-
-void test("prefers context.agent_name over metadata.agent_name", () => {
-  assert.equal(
-    pathOfThread({
-      thread_id: "thread-789",
-      context: { agent_name: "from-context" },
-      metadata: { agent_name: "from-metadata" },
-    }),
-    "/workspace/agents/from-context/chats/thread-789",
-  );
-});

frontend/src/core/uploads/prompt-input-files.test.mjs

@@ -1,150 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-
-async function loadModule() {
-  try {
-    return await import("./prompt-input-files.ts");
-  } catch (error) {
-    return { error };
-  }
-}
-
-test("exports the prompt-input file conversion helper", async () => {
-  const loaded = await loadModule();
-
-  assert.ok(
-    !("error" in loaded),
-    loaded.error instanceof Error
-      ? loaded.error.message
-      : "prompt-input-files module is missing",
-  );
-  assert.equal(typeof loaded.promptInputFilePartToFile, "function");
-});
-
-test("reuses the original File when a prompt attachment already has one", async () => {
-  const { promptInputFilePartToFile } = await import("./prompt-input-files.ts");
-  const file = new File(["hello"], "note.txt", { type: "text/plain" });
-  const originalFetch = globalThis.fetch;
-
-  globalThis.fetch = async () => {
-    throw new Error("fetch should not run when File is already present");
-  };
-
-  try {
-    const converted = await promptInputFilePartToFile({
-      type: "file",
-      filename: file.name,
-      mediaType: file.type,
-      url: "blob:http://localhost:2026/stale-preview-url",
-      file,
-    });
-
-    assert.equal(converted, file);
-  } finally {
-    globalThis.fetch = originalFetch;
-  }
-});
-
-test("reconstructs a File from a data URL when no original File is present", async () => {
-  const { promptInputFilePartToFile } = await import("./prompt-input-files.ts");
-  const converted = await promptInputFilePartToFile({
-    type: "file",
-    filename: "note.txt",
-    mediaType: "text/plain",
-    url: "data:text/plain;base64,aGVsbG8=",
-  });
-
-  assert.ok(converted);
-  assert.equal(converted.name, "note.txt");
-  assert.equal(converted.type, "text/plain");
-  assert.equal(await converted.text(), "hello");
-});
-
-test("rewraps the original File when the prompt metadata changes", async () => {
-  const { promptInputFilePartToFile } = await import("./prompt-input-files.ts");
-  const file = new File(["hello"], "note.txt", { type: "text/plain" });
-
-  const converted = await promptInputFilePartToFile({
-    type: "file",
-    filename: "renamed.txt",
-    mediaType: "text/markdown",
-    file,
-  });
-
-  assert.ok(converted);
-  assert.notEqual(converted, file);
-  assert.equal(converted.name, "renamed.txt");
-  assert.equal(converted.type, "text/markdown");
-  assert.equal(await converted.text(), "hello");
-});
-
-test("returns null when upload preparation is missing required data", async () => {
-  const { promptInputFilePartToFile } = await import("./prompt-input-files.ts");
-
-  const converted = await promptInputFilePartToFile({
-    type: "file",
-    mediaType: "text/plain",
-  });
-
-  assert.equal(converted, null);
-});
-
-test("returns null when the URL fallback fetch fails", async () => {
-  const { promptInputFilePartToFile } = await import("./prompt-input-files.ts");
-  const originalFetch = globalThis.fetch;
-  const originalWarn = console.warn;
-  const warnCalls = [];
-
-  console.warn = (...args) => {
-    warnCalls.push(args);
-  };
-
-  globalThis.fetch = async () => {
-    throw new Error("network down");
-  };
-
-  try {
-    const converted = await promptInputFilePartToFile({
-      type: "file",
-      filename: "note.txt",
-      url: "blob:http://localhost:2026/missing-preview-url",
-    });
-
-    assert.equal(converted, null);
-    assert.equal(warnCalls.length, 1);
-  } finally {
-    globalThis.fetch = originalFetch;
-    console.warn = originalWarn;
-  }
-});
-
-test("returns null when the URL fallback fetch response is non-ok", async () => {
-  const { promptInputFilePartToFile } = await import("./prompt-input-files.ts");
-  const originalFetch = globalThis.fetch;
-  const originalWarn = console.warn;
-  const warnCalls = [];
-
-  console.warn = (...args) => {
-    warnCalls.push(args);
-  };
-
-  globalThis.fetch = async () =>
-    new Response("missing", {
-      status: 404,
-      statusText: "Not Found",
-    });
-
-  try {
-    const converted = await promptInputFilePartToFile({
-      type: "file",
-      filename: "note.txt",
-      url: "blob:http://localhost:2026/missing-preview-url",
-    });
-
-    assert.equal(converted, null);
-    assert.equal(warnCalls.length, 1);
-  } finally {
-    globalThis.fetch = originalFetch;
-    console.warn = originalWarn;
-  }
-});

frontend/tests/e2e/agent-chat.spec.ts

@@ -0,0 +1,46 @@
+import { expect, test } from "@playwright/test";
+
+import { mockLangGraphAPI } from "./utils/mock-api";
+
+const MOCK_AGENTS = [
+  {
+    name: "test-agent",
+    description: "A test agent for E2E tests",
+    system_prompt: "You are a test agent.",
+  },
+];
+
+test.describe("Agent chat", () => {
+  test("agent gallery page loads and shows agents", async ({ page }) => {
+    mockLangGraphAPI(page, { agents: MOCK_AGENTS });
+
+    await page.goto("/workspace/agents");
+
+    // The agent card should appear with the agent name
+    await expect(page.getByText("test-agent")).toBeVisible({
+      timeout: 15_000,
+    });
+  });
+
+  test("agent chat page loads with input box", async ({ page }) => {
+    mockLangGraphAPI(page, { agents: MOCK_AGENTS });
+
+    await page.goto("/workspace/agents/test-agent/chats/new");
+
+    // The prompt input textarea should be visible
+    const textarea = page.getByPlaceholder(/how can i assist you/i);
+    await expect(textarea).toBeVisible({ timeout: 15_000 });
+  });
+
+  test("agent chat page shows agent badge", async ({ page }) => {
+    mockLangGraphAPI(page, { agents: MOCK_AGENTS });
+
+    await page.goto("/workspace/agents/test-agent/chats/new");
+
+    // The agent badge should display in the header (scoped to header to avoid
+    // matching the welcome area which also shows the agent name)
+    await expect(
+      page.locator("header span", { hasText: "test-agent" }),
+    ).toBeVisible({ timeout: 15_000 });
+  });
+});

frontend/tests/e2e/chat.spec.ts

@@ -0,0 +1,51 @@
+import { expect, test } from "@playwright/test";
+
+import { handleRunStream, mockLangGraphAPI } from "./utils/mock-api";
+
+test.describe("Chat workspace", () => {
+  test.beforeEach(async ({ page }) => {
+    mockLangGraphAPI(page);
+  });
+
+  test("new chat page loads with input box", async ({ page }) => {
+    await page.goto("/workspace/chats/new");
+
+    const textarea = page.getByPlaceholder(/how can i assist you/i);
+    await expect(textarea).toBeVisible({ timeout: 15_000 });
+  });
+
+  test("can type a message in the input box", async ({ page }) => {
+    await page.goto("/workspace/chats/new");
+
+    const textarea = page.getByPlaceholder(/how can i assist you/i);
+    await expect(textarea).toBeVisible({ timeout: 15_000 });
+
+    await textarea.fill("Hello, DeerFlow!");
+    await expect(textarea).toHaveValue("Hello, DeerFlow!");
+  });
+
+  test("sending a message triggers API call and shows response", async ({
+    page,
+  }) => {
+    let streamCalled = false;
+    await page.route("**/runs/stream", (route) => {
+      streamCalled = true;
+      return handleRunStream(route);
+    });
+
+    await page.goto("/workspace/chats/new");
+
+    const textarea = page.getByPlaceholder(/how can i assist you/i);
+    await expect(textarea).toBeVisible({ timeout: 15_000 });
+
+    await textarea.fill("Hello");
+    await textarea.press("Enter");
+
+    await expect.poll(() => streamCalled, { timeout: 10_000 }).toBeTruthy();
+
+    // The AI response should appear in the chat
+    await expect(page.getByText("Hello from DeerFlow!")).toBeVisible({
+      timeout: 10_000,
+    });
+  });
+});

frontend/tests/e2e/landing.spec.ts

@@ -0,0 +1,32 @@
+import { expect, test } from "@playwright/test";
+
+import { mockLangGraphAPI } from "./utils/mock-api";
+
+test.describe("Landing page", () => {
+  test("renders the header and hero section", async ({ page }) => {
+    await page.goto("/");
+
+    // Header brand name
+    await expect(
+      page.locator("header h1", { hasText: "DeerFlow" }),
+    ).toBeVisible();
+
+    // "Get Started" call-to-action button in hero
+    await expect(
+      page.getByRole("link", { name: /get started/i }),
+    ).toBeVisible();
+  });
+
+  test("Get Started link navigates to workspace", async ({ page }) => {
+    mockLangGraphAPI(page);
+
+    await page.goto("/");
+
+    const getStarted = page.getByRole("link", { name: /get started/i });
+    await getStarted.click();
+
+    // Should redirect to /workspace/chats/new
+    await page.waitForURL("**/workspace/chats/new");
+    await expect(page).toHaveURL(/\/workspace\/chats\/new/);
+  });
+});

frontend/tests/e2e/sidebar.spec.ts

@@ -0,0 +1,32 @@
+import { expect, test } from "@playwright/test";
+
+import { mockLangGraphAPI } from "./utils/mock-api";
+
+test.describe("Sidebar navigation", () => {
+  test("sidebar contains Chats and Agents nav links", async ({ page }) => {
+    mockLangGraphAPI(page);
+
+    await page.goto("/workspace/chats/new");
+
+    // Sidebar uses data-sidebar="menu-button" with asChild rendering on <Link>
+    const sidebar = page.locator("[data-sidebar='sidebar']");
+    await expect(sidebar.locator("a[href='/workspace/chats']")).toBeVisible({
+      timeout: 15_000,
+    });
+    await expect(sidebar.locator("a[href='/workspace/agents']")).toBeVisible();
+  });
+
+  test("Agents link navigates to agents page", async ({ page }) => {
+    mockLangGraphAPI(page);
+
+    await page.goto("/workspace/chats/new");
+
+    const sidebar = page.locator("[data-sidebar='sidebar']");
+    const agentsLink = sidebar.locator("a[href='/workspace/agents']");
+    await expect(agentsLink).toBeVisible({ timeout: 15_000 });
+    await agentsLink.click();
+
+    await page.waitForURL("**/workspace/agents");
+    await expect(page).toHaveURL(/\/workspace\/agents/);
+  });
+});

frontend/tests/e2e/thread-history.spec.ts

@@ -0,0 +1,76 @@
+import { expect, test } from "@playwright/test";
+
+import {
+  mockLangGraphAPI,
+  MOCK_THREAD_ID,
+  MOCK_THREAD_ID_2,
+} from "./utils/mock-api";
+
+const THREADS = [
+  {
+    thread_id: MOCK_THREAD_ID,
+    title: "First conversation",
+    updated_at: "2025-06-01T12:00:00Z",
+  },
+  {
+    thread_id: MOCK_THREAD_ID_2,
+    title: "Second conversation",
+    updated_at: "2025-06-02T12:00:00Z",
+  },
+];
+
+test.describe("Thread history", () => {
+  test("sidebar shows existing threads", async ({ page }) => {
+    mockLangGraphAPI(page, { threads: THREADS });
+
+    await page.goto("/workspace/chats/new");
+
+    // Both thread titles should appear in the sidebar
+    await expect(page.getByText("First conversation")).toBeVisible({
+      timeout: 15_000,
+    });
+    await expect(page.getByText("Second conversation")).toBeVisible();
+  });
+
+  test("clicking a thread in sidebar navigates to it", async ({ page }) => {
+    mockLangGraphAPI(page, { threads: THREADS });
+
+    await page.goto("/workspace/chats/new");
+
+    // Wait for sidebar to populate
+    const firstThread = page.getByText("First conversation");
+    await expect(firstThread).toBeVisible({ timeout: 15_000 });
+
+    // Click on the first thread
+    await firstThread.click();
+
+    // Should navigate to that thread's URL
+    await page.waitForURL(`**/workspace/chats/${MOCK_THREAD_ID}`);
+    await expect(page).toHaveURL(new RegExp(MOCK_THREAD_ID));
+  });
+
+  test("existing thread loads historical messages", async ({ page }) => {
+    mockLangGraphAPI(page, { threads: THREADS });
+
+    // Navigate directly to an existing thread
+    await page.goto(`/workspace/chats/${MOCK_THREAD_ID}`);
+
+    // The historical AI response should be displayed
+    await expect(
+      page.getByText("Response in thread First conversation"),
+    ).toBeVisible({ timeout: 15_000 });
+  });
+
+  test("chats list page shows all threads", async ({ page }) => {
+    mockLangGraphAPI(page, { threads: THREADS });
+
+    await page.goto("/workspace/chats");
+
+    // Both threads should be listed in the main content area
+    const main = page.locator("main");
+    await expect(main.getByText("First conversation")).toBeVisible({
+      timeout: 15_000,
+    });
+    await expect(main.getByText("Second conversation")).toBeVisible();
+  });
+});