fix(actor): harden lifecycle, supervision, Redis mailbox, and add comprehensive tests

- Fix spawn() zombie cell: clean up registry on start() failure - Fix shutdown(): cancel + await tasks that exceed graceful timeout - Fix _shutdown(): await mailbox.close() to release backend resources - Fix escalate directive: stop failing child before propagating to grandparent - Fix RedisMailbox.put(): wrap Redis errors in try/except, return False on failure - Fix retry.py: replace assert with proper raise for last_exc - Add put_batch() to Mailbox abstraction for single-roundtrip bulk enqueue - Add RedisMailbox.put_batch() with atomic Lua script for bounded queues - Add MailboxFullError exception type for semantic backpressure handling - Add redis>=7.4.0 dependency with public PyPI sources in uv.lock Tests added (31 total, up from 27): - test_middleware_on_restart_hook: verifies middleware.on_restart() on supervision restart - test_ask_propagates_actor_exception: ask() re-raises original exception type - test_ask_propagates_exception_while_supervised: exception propagates; root actor survives - test_ask_timeout_late_reply_no_exception: late reply after timeout is silent no-op - test_actor_backpressure.py: MailboxFullError + dead letter on full mailbox - test_actor_retry.py: ask_with_retry with exponential backoff - test_mailbox_redis.py: RedisMailbox put/get/batch/close - bench_actor_redis.py: RedisMailbox throughput benchmarks
feat: asyncio-native Actor framework with supervision, middleware, and pluggable mailbox
2026-05-20 15:11:09 +00:00 · 2026-03-31 10:09:05 +08:00 · 2026-03-30 23:50:54 +08:00
441 changed files with 7623 additions and 44622 deletions
@@ -1,181 +0,0 @@
 ---
 name: smoke-test
 description: End-to-end smoke test skill for DeerFlow. Guides through: 1) Pulling latest code, 2) Docker OR Local installation and deployment (user preference, default to Local if Docker network issues), 3) Service availability verification, 4) Health check, 5) Final test report. Use when the user says "run smoke test", "smoke test deployment", "verify installation", "test service availability", "end-to-end test", or similar.
 ---
 # DeerFlow Smoke Test Skill
 This skill guides the Agent through DeerFlow's full end-to-end smoke test workflow, including code updates, deployment (supporting both Docker and local installation modes), service availability verification, and health checks.
 ## Deployment Mode Selection
 This skill supports two deployment modes:
 - **Local installation mode** (recommended, especially when network issues occur) - Run all services directly on the local machine
 - **Docker mode** - Run all services inside Docker containers
 **Selection strategy**:
 - If the user explicitly asks for Docker mode, use Docker
 - If network issues occur (such as slow image pulls), automatically switch to local mode
 - Default to local mode whenever possible
 ## Structure
 ```
 smoke-test/
 ├── SKILL.md                          ← You are here - core workflow and logic
 ├── scripts/
 │   ├── check_docker.sh               ← Check the Docker environment
 │   ├── check_local_env.sh            ← Check local environment dependencies
 │   ├── frontend_check.sh             ← Frontend page smoke check
 │   ├── pull_code.sh                  ← Pull the latest code
 │   ├── deploy_docker.sh              ← Docker deployment
 │   ├── deploy_local.sh               ← Local deployment
 │   └── health_check.sh               ← Service health check
 ├── references/
 │   ├── SOP.md                        ← Standard operating procedure
 │   └── troubleshooting.md            ← Troubleshooting guide
 └── templates/
    ├── report.local.template.md      ← Local mode smoke test report template
    └── report.docker.template.md     ← Docker mode smoke test report template
 ```
 ## Standard Operating Procedure (SOP)
 ### Phase 1: Code Update Check
 1. **Confirm current directory** - Verify that the current working directory is the DeerFlow project root
 2. **Check Git status** - See whether there are uncommitted changes
 3. **Pull the latest code** - Use `git pull origin main` to get the latest updates
 4. **Confirm code update** - Verify that the latest code was pulled successfully
 ### Phase 2: Deployment Mode Selection and Environment Check
 **Choose deployment mode**:
 - Ask for user preference, or choose automatically based on network conditions
 - Default to local installation mode
 **Local mode environment check**:
 1. **Check Node.js version** - Requires 22+
 2. **Check pnpm** - Package manager
 3. **Check uv** - Python package manager
 4. **Check nginx** - Reverse proxy
 5. **Check required ports** - Confirm that ports 2026, 3000, 8001, and 2024 are not occupied
 **Docker mode environment check** (if Docker is selected):
 1. **Check whether Docker is installed** - Run `docker --version`
 2. **Check Docker daemon status** - Run `docker info`
 3. **Check Docker Compose availability** - Run `docker compose version`
 4. **Check required ports** - Confirm that port 2026 is not occupied
 ### Phase 3: Configuration Preparation
 1. **Check whether config.yaml exists**
   - If it does not exist, run `make config` to generate it
   - If it already exists, check whether it needs an upgrade with `make config-upgrade`
 2. **Check the .env file**
   - Verify that required environment variables are configured
   - Especially model API keys such as `OPENAI_API_KEY`
 ### Phase 4: Deployment Execution
 **Local mode deployment**:
 1. **Check dependencies** - Run `make check`
 2. **Install dependencies** - Run `make install`
 3. **(Optional) Pre-pull the sandbox image** - If needed, run `make setup-sandbox`
 4. **Start services** - Run `make dev-daemon` (background mode, recommended) or `make dev` (foreground mode)
 5. **Wait for startup** - Give all services enough time to start completely (90-120 seconds recommended)
 **Docker mode deployment** (if Docker is selected):
 1. **Initialize Docker environment** - Run `make docker-init`
 2. **Start Docker services** - Run `make docker-start`
 3. **Wait for startup** - Give all containers enough time to start completely (60 seconds recommended)
 ### Phase 5: Service Health Check
 **Local mode health check**:
 1. **Check process status** - Confirm that LangGraph, Gateway, Frontend, and Nginx processes are all running
 2. **Check frontend service** - Visit `http://localhost:2026` and verify that the page loads
 3. **Check API Gateway** - Verify the `http://localhost:2026/health` endpoint
 4. **Check LangGraph service** - Verify the availability of relevant endpoints
 5. **Frontend route smoke check** - Run `bash .agent/skills/smoke-test/scripts/frontend_check.sh` to verify key routes under `/workspace`
 **Docker mode health check** (when using Docker):
 1. **Check container status** - Run `docker ps` and confirm that all containers are running
 2. **Check frontend service** - Visit `http://localhost:2026` and verify that the page loads
 3. **Check API Gateway** - Verify the `http://localhost:2026/health` endpoint
 4. **Check LangGraph service** - Verify the availability of relevant endpoints
 5. **Frontend route smoke check** - Run `bash .agent/skills/smoke-test/scripts/frontend_check.sh` to verify key routes under `/workspace`
 ### Optional Functional Verification
 1. **List available models** - Verify that model configuration loads correctly
 2. **List available skills** - Verify that the skill directory is mounted correctly
 3. **Simple chat test** - Send a simple message to verify the end-to-end flow
 ### Phase 6: Generate Test Report
 1. **Collect all test results** - Summarize execution status for each phase
 2. **Record encountered issues** - If anything fails, record the error details
 3. **Generate the final report** - Use the template that matches the selected deployment mode to create the complete test report, including overall conclusion, detailed key test cases, and explicit frontend page / route results
 4. **Provide follow-up recommendations** - Offer suggestions based on the test results
 ## Execution Rules
 - **Follow the sequence** - Execute strictly in the order described above
 - **Idempotency** - Every step should be safe to repeat
 - **Error handling** - If a step fails, stop and report the issue, then provide troubleshooting suggestions
 - **Detailed logging** - Record the execution result and status of each step
 - **User confirmation** - Ask for confirmation before potentially risky operations such as overwriting config
 - **Mode preference** - Prefer local mode to avoid network-related issues
 - **Template requirement** - The final report must use the matching template under `templates/`; do not output a free-form summary instead of the template-based report
 - **Report clarity** - The execution summary must include the overall pass/fail conclusion plus per-case result explanations, and frontend smoke check results must be listed explicitly in the report
 - **Optional phase handling** - If functional verification is not executed, do not present it as a separate skipped phase in the final report
 ## Known Acceptable Warnings
 The following warnings can appear during smoke testing and do not block a successful result:
 - Feishu/Lark SSL errors in Gateway logs (certificate verification failure) can be ignored if that channel is not enabled
 - Warnings in LangGraph logs about missing methods in the custom checkpointer, such as `adelete_for_runs` or `aprune`, do not affect the core functionality
 ## Key Tools
 Use the following tools during execution:
 1. **bash** - Run shell commands
 2. **present_file** - Show generated reports and important files
 3. **task_tool** - Organize complex steps with subtasks when needed
 ## Success Criteria
 Smoke test pass criteria (local mode):
 - [x] Latest code is pulled successfully
 - [x] Local environment check passes (Node.js 22+, pnpm, uv, nginx)
 - [x] Configuration files are set up correctly
 - [x] `make check` passes
 - [x] `make install` completes successfully
 - [x] `make dev` starts successfully
 - [x] All service processes run normally
 - [x] Frontend page is accessible
 - [x] Frontend route smoke check passes (`/workspace` key routes)
 - [x] API Gateway health check passes
 - [x] Test report is generated completely
 Smoke test pass criteria (Docker mode):
 - [x] Latest code is pulled successfully
 - [x] Docker environment check passes
 - [x] Configuration files are set up correctly
 - [x] `make docker-init` completes successfully
 - [x] `make docker-start` completes successfully
 - [x] All Docker containers run normally
 - [x] Frontend page is accessible
 - [x] Frontend route smoke check passes (`/workspace` key routes)
 - [x] API Gateway health check passes
 - [x] Test report is generated completely
 ## Read Reference Files
 Before starting execution, read the following reference files:
 1. `references/SOP.md` - Detailed step-by-step operating instructions
 2. `references/troubleshooting.md` - Common issues and solutions
 3. `templates/report.local.template.md` - Local mode test report template
 4. `templates/report.docker.template.md` - Docker mode test report template
@@ -1,452 +0,0 @@
 # DeerFlow Smoke Test Standard Operating Procedure (SOP)
 This document describes the detailed operating steps for each phase of the DeerFlow smoke test.
 ## Phase 1: Code Update Check
 ### 1.1 Confirm Current Directory
 **Objective**: Verify that the current working directory is the DeerFlow project root.
 **Steps**:
 1. Run `pwd` to view the current working directory
 2. Check whether the directory contains the following files/directories:
   - `Makefile`
   - `backend/`
   - `frontend/`
   - `config.example.yaml`
 **Success Criteria**: The current directory contains all of the files/directories listed above.
 ---
 ### 1.2 Check Git Status
 **Objective**: Check whether there are uncommitted changes.
 **Steps**:
 1. Run `git status`
 2. Check whether the output includes "Changes not staged for commit" or "Untracked files"
 **Notes**:
 - If there are uncommitted changes, recommend that the user commit or stash them first to avoid conflicts while pulling
 - If the user confirms that they want to continue, this step can be skipped
 ---
 ### 1.3 Pull the Latest Code
 **Objective**: Fetch the latest code updates.
 **Steps**:
 1. Run `git fetch origin main`
 2. Run `git pull origin main`
 **Success Criteria**:
 - The commands succeed without errors
 - The output shows "Already up to date" or indicates that new commits were pulled successfully
 ---
 ### 1.4 Confirm Code Update
 **Objective**: Verify that the latest code was pulled successfully.
 **Steps**:
 1. Run `git log -1 --oneline` to view the latest commit
 2. Record the commit hash and message
 ---
 ## Phase 2: Deployment Mode Selection and Environment Check
 ### 2.1 Choose Deployment Mode
 **Objective**: Decide whether to use local mode or Docker mode.
 **Decision Flow**:
 1. Prefer local mode first to avoid network-related issues
 2. If the user explicitly requests Docker, use Docker
 3. If Docker network issues occur, switch to local mode automatically
 ---
 ### 2.2 Local Mode Environment Check
 **Objective**: Verify that local development environment dependencies are satisfied.
 #### 2.2.1 Check Node.js Version
 **Steps**:
 1. If nvm is used, run `nvm use 22` to switch to Node 22+
 2. Run `node --version`
 **Success Criteria**: Version >= 22.x
 **Failure Handling**:
 - If the version is too low, ask the user to install/switch Node.js with nvm:
  ```bash
  nvm install 22
  nvm use 22
  ```
 - Or install it from the official website: https://nodejs.org/
 ---
 #### 2.2.2 Check pnpm
 **Steps**:
 1. Run `pnpm --version`
 **Success Criteria**: The command returns pnpm version information.
 **Failure Handling**:
 - If pnpm is not installed, ask the user to install it with `npm install -g pnpm`
 ---
 #### 2.2.3 Check uv
 **Steps**:
 1. Run `uv --version`
 **Success Criteria**: The command returns uv version information.
 **Failure Handling**:
 - If uv is not installed, ask the user to install uv
 ---
 #### 2.2.4 Check nginx
 **Steps**:
 1. Run `nginx -v`
 **Success Criteria**: The command returns nginx version information.
 **Failure Handling**:
 - macOS: install with Homebrew using `brew install nginx`
 - Linux: install using the system package manager
 ---
 #### 2.2.5 Check Required Ports
 **Steps**:
 1. Run the following commands to check ports:
   ```bash
   lsof -i :2026  # Main port
   lsof -i :3000  # Frontend
   lsof -i :8001  # Gateway
   lsof -i :2024  # LangGraph
   ```
 **Success Criteria**: All ports are free, or they are occupied only by DeerFlow-related processes.
 **Failure Handling**:
 - If a port is occupied, ask the user to stop the related process
 ---
 ### 2.3 Docker Mode Environment Check (If Docker Is Selected)
 #### 2.3.1 Check Whether Docker Is Installed
 **Steps**:
 1. Run `docker --version`
 **Success Criteria**: The command returns Docker version information, such as "Docker version 24.x.x".
 ---
 #### 2.3.2 Check Docker Daemon Status
 **Steps**:
 1. Run `docker info`
 **Success Criteria**: The command runs successfully and shows Docker system information.
 **Failure Handling**:
 - If it fails, ask the user to start Docker Desktop or the Docker service
 ---
 #### 2.3.3 Check Docker Compose Availability
 **Steps**:
 1. Run `docker compose version`
 **Success Criteria**: The command returns Docker Compose version information.
 ---
 #### 2.3.4 Check Required Ports
 **Steps**:
 1. Run `lsof -i :2026` (macOS/Linux) or `netstat -ano | findstr :2026` (Windows)
 **Success Criteria**: Port 2026 is free, or it is occupied only by a DeerFlow-related process.
 **Failure Handling**:
 - If the port is occupied by another process, ask the user to stop that process or change the configuration
 ---
 ## Phase 3: Configuration Preparation
 ### 3.1 Check config.yaml
 **Steps**:
 1. Check whether `config.yaml` exists
 2. If it does not exist, run `make config`
 3. If it already exists, consider running `make config-upgrade` to merge new fields
 **Validation**:
 - Check whether at least one model is configured in config.yaml
 - Check whether the model configuration references the correct environment variables
 ---
 ### 3.2 Check the .env File
 **Steps**:
 1. Check whether the `.env` file exists
 2. If it does not exist, copy it from `.env.example`
 3. Check whether the following environment variables are configured:
   - `OPENAI_API_KEY` (or other model API keys)
   - Other required settings
 ---
 ## Phase 4: Deployment Execution
 ### 4.1 Local Mode Deployment
 #### 4.1.1 Check Dependencies
 **Steps**:
 1. Run `make check`
 **Description**: This command validates all required tools (Node.js 22+, pnpm, uv, nginx).
 ---
 #### 4.1.2 Install Dependencies
 **Steps**:
 1. Run `make install`
 **Description**: This command installs both backend and frontend dependencies.
 **Notes**:
 - This step may take some time
 - If network issues cause failures, try using a closer or mirrored package registry
 ---
 #### 4.1.3 (Optional) Pre-pull the Sandbox Image
 **Steps**:
 1. If Docker / Container sandbox is used, run `make setup-sandbox`
 **Description**: This step is optional and not needed for local sandbox mode.
 ---
 #### 4.1.4 Start Services
 **Steps**:
 1. Run `make dev-daemon` (background mode)
 **Description**: This command starts all services (LangGraph, Gateway, Frontend, Nginx).
 **Notes**:
 - `make dev` runs in the foreground and stops with Ctrl+C
 - `make dev-daemon` runs in the background
 - Use `make stop` to stop services
 ---
 #### 4.1.5 Wait for Services to Start
 **Steps**:
 1. Wait 90-120 seconds for all services to start completely
 2. You can monitor startup progress by checking these log files:
   - `logs/langgraph.log`
   - `logs/gateway.log`
   - `logs/frontend.log`
   - `logs/nginx.log`
 ---
 ### 4.2 Docker Mode Deployment (If Docker Is Selected)
 #### 4.2.1 Initialize the Docker Environment
 **Steps**:
 1. Run `make docker-init`
 **Description**: This command pulls the sandbox image if needed.
 ---
 #### 4.2.2 Start Docker Services
 **Steps**:
 1. Run `make docker-start`
 **Description**: This command builds and starts all required Docker containers.
 ---
 #### 4.2.3 Wait for Services to Start
 **Steps**:
 1. Wait 60-90 seconds for all services to start completely
 2. You can run `make docker-logs` to monitor startup progress
 ---
 ## Phase 5: Service Health Check
 ### 5.1 Local Mode Health Check
 #### 5.1.1 Check Process Status
 **Steps**:
 1. Run the following command to check processes:
   ```bash
   ps aux | grep -E "(langgraph|uvicorn|next|nginx)" | grep -v grep
   ```
 **Success Criteria**: Confirm that the following processes are running:
 - LangGraph (`langgraph dev`)
 - Gateway (`uvicorn app.gateway.app:app`)
 - Frontend (`next dev` or `next start`)
 - Nginx (`nginx`)
 ---
 #### 5.1.2 Check Frontend Service
 **Steps**:
 1. Use curl or a browser to visit `http://localhost:2026`
 2. Verify that the page loads normally
 **Example curl command**:
 ```bash
 curl -I http://localhost:2026
 ```
 **Success Criteria**: Returns an HTTP 200 status code.
 ---
 #### 5.1.3 Check API Gateway
 **Steps**:
 1. Visit `http://localhost:2026/health`
 **Example curl command**:
 ```bash
 curl http://localhost:2026/health
 ```
 **Success Criteria**: Returns health status JSON.
 ---
 #### 5.1.4 Check LangGraph Service
 **Steps**:
 1. Visit relevant LangGraph endpoints to verify availability
 ---
 ### 5.2 Docker Mode Health Check (When Using Docker)
 #### 5.2.1 Check Container Status
 **Steps**:
 1. Run `docker ps`
 2. Confirm that the following containers are running:
   - `deer-flow-nginx`
   - `deer-flow-frontend`
   - `deer-flow-gateway`
   - `deer-flow-langgraph` (if not in gateway mode)
 ---
 #### 5.2.2 Check Frontend Service
 **Steps**:
 1. Use curl or a browser to visit `http://localhost:2026`
 2. Verify that the page loads normally
 **Example curl command**:
 ```bash
 curl -I http://localhost:2026
 ```
 **Success Criteria**: Returns an HTTP 200 status code.
 ---
 #### 5.2.3 Check API Gateway
 **Steps**:
 1. Visit `http://localhost:2026/health`
 **Example curl command**:
 ```bash
 curl http://localhost:2026/health
 ```
 **Success Criteria**: Returns health status JSON.
 ---
 #### 5.2.4 Check LangGraph Service
 **Steps**:
 1. Visit relevant LangGraph endpoints to verify availability
 ---
 ## Optional Functional Verification
 ### 6.1 List Available Models
 **Steps**: Verify the model list through the API or UI.
 ---
 ### 6.2 List Available Skills
 **Steps**: Verify the skill list through the API or UI.
 ---
 ### 6.3 Simple Chat Test
 **Steps**: Send a simple message to test the complete workflow.
 ---
 ## Phase 6: Generate the Test Report
 ### 6.1 Collect Test Results
 Summarize the execution status of each phase and record successful and failed items.
 ### 6.2 Record Issues
 If anything fails, record detailed error information.
 ### 6.3 Generate the Report
 Use the template to create a complete test report.
 ### 6.4 Provide Recommendations
 Provide follow-up recommendations based on the test results.
@@ -1,612 +0,0 @@
 # Troubleshooting Guide
 This document lists common issues encountered during DeerFlow smoke testing and how to resolve them.
 ## Code Update Issues
 ### Issue: `git pull` Fails with a Merge Conflict Warning
 **Symptoms**:
 ```
 error: Your local changes to the following files would be overwritten by merge
 ```
 **Solutions**:
 1. Option A: Commit local changes first
   ```bash
   git add .
   git commit -m "Save local changes"
   git pull origin main
   ```
 2. Option B: Stash local changes
   ```bash
   git stash
   git pull origin main
   git stash pop  # Restore changes later if needed
   ```
 3. Option C: Discard local changes (use with caution)
   ```bash
   git reset --hard HEAD
   git pull origin main
   ```
 ---
 ## Local Mode Environment Issues
 ### Issue: Node.js Version Is Too Old
 **Symptoms**:
 ```
 Node.js version is too old. Requires 22+, got x.x.x
 ```
 **Solutions**:
 1. Install or upgrade Node.js with nvm:
   ```bash
   nvm install 22
   nvm use 22
   ```
 2. Or download and install it from the official website: https://nodejs.org/
 3. Verify the version:
   ```bash
   node --version
   ```
 ---
 ### Issue: pnpm Is Not Installed
 **Symptoms**:
 ```
 command not found: pnpm
 ```
 **Solutions**:
 1. Install pnpm with npm:
   ```bash
   npm install -g pnpm
   ```
 2. Or use the official installation script:
   ```bash
   curl -fsSL https://get.pnpm.io/install.sh | sh -
   ```
 3. Verify the installation:
   ```bash
   pnpm --version
   ```
 ---
 ### Issue: uv Is Not Installed
 **Symptoms**:
 ```
 command not found: uv
 ```
 **Solutions**:
 1. Use the official installation script:
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```
 2. macOS users can also install it with Homebrew:
   ```bash
   brew install uv
   ```
 3. Verify the installation:
   ```bash
   uv --version
   ```
 ---
 ### Issue: nginx Is Not Installed
 **Symptoms**:
 ```
 command not found: nginx
 ```
 **Solutions**:
 1. macOS (Homebrew):
   ```bash
   brew install nginx
   ```
 2. Ubuntu/Debian:
   ```bash
   sudo apt update
   sudo apt install nginx
   ```
 3. CentOS/RHEL:
   ```bash
   sudo yum install nginx
   ```
 4. Verify the installation:
   ```bash
   nginx -v
   ```
 ---
 ### Issue: Port Is Already in Use
 **Symptoms**:
 ```
 Error: listen EADDRINUSE: address already in use :::2026
 ```
 **Solutions**:
 1. Find the process using the port:
   ```bash
   lsof -i :2026  # macOS/Linux
   netstat -ano | findstr :2026  # Windows
   ```
 2. Stop that process:
   ```bash
   kill -9 <PID>  # macOS/Linux
   taskkill /PID <PID> /F  # Windows
   ```
 3. Or stop DeerFlow services first:
   ```bash
   make stop
   ```
 ---
 ## Local Mode Dependency Installation Issues
 ### Issue: `make install` Fails Due to Network Timeout
 **Symptoms**:
 Network timeouts or connection failures occur during dependency installation.
 **Solutions**:
 1. Configure pnpm to use a mirror registry:
   ```bash
   pnpm config set registry https://registry.npmmirror.com
   ```
 2. Configure uv to use a mirror registry:
   ```bash
   uv pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
   ```
 3. Retry the installation:
   ```bash
   make install
   ```
 ---
 ### Issue: Python Dependency Installation Fails
 **Symptoms**:
 Errors occur during `uv sync`.
 **Solutions**:
 1. Clean the uv cache:
   ```bash
   cd backend
   uv cache clean
   ```
 2. Resync dependencies:
   ```bash
   cd backend
   uv sync
   ```
 3. View detailed error logs:
   ```bash
   cd backend
   uv sync --verbose
   ```
 ---
 ### Issue: Frontend Dependency Installation Fails
 **Symptoms**:
 Errors occur during `pnpm install`.
 **Solutions**:
 1. Clean the pnpm cache:
   ```bash
   cd frontend
   pnpm store prune
   ```
 2. Remove node_modules and the lock file:
   ```bash
   cd frontend
   rm -rf node_modules pnpm-lock.yaml
   ```
 3. Reinstall:
   ```bash
   cd frontend
   pnpm install
   ```
 ---
 ## Local Mode Service Startup Issues
 ### Issue: Services Exit Immediately After Startup
 **Symptoms**:
 Processes exit quickly after running `make dev-daemon`.
 **Solutions**:
 1. Check log files:
   ```bash
   tail -f logs/langgraph.log
   tail -f logs/gateway.log
   tail -f logs/frontend.log
   tail -f logs/nginx.log
   ```
 2. Check whether config.yaml is configured correctly
 3. Check environment variables in the .env file
 4. Confirm that required ports are not occupied
 5. Stop all services and restart:
   ```bash
   make stop
   make dev-daemon
   ```
 ---
 ### Issue: Nginx Fails to Start Because Temp Directories Do Not Exist
 **Symptoms**:
 ```
 nginx: [emerg] mkdir() "/opt/homebrew/var/run/nginx/client_body_temp" failed (2: No such file or directory)
 ```
 **Solutions**:
 Add local temp directory configuration to `docker/nginx/nginx.local.conf` so nginx uses the repository's temp directory.
 Add the following at the beginning of the `http` block:
 ```nginx
 client_body_temp_path temp/client_body_temp;
 proxy_temp_path temp/proxy_temp;
 fastcgi_temp_path temp/fastcgi_temp;
 uwsgi_temp_path temp/uwsgi_temp;
 scgi_temp_path temp/scgi_temp;
 ```
 Note: The `temp/` directory under the repository root is created automatically by `make dev` or `make dev-daemon`.
 ---
 ### Issue: Nginx Fails to Start (General)
 **Symptoms**:
 The nginx process fails to start or reports an error.
 **Solutions**:
 1. Check the nginx configuration:
   ```bash
   nginx -t -c docker/nginx/nginx.local.conf -p .
   ```
 2. Check nginx logs:
   ```bash
   tail -f logs/nginx.log
   ```
 3. Ensure no other nginx process is running:
   ```bash
   ps aux | grep nginx
   ```
 4. If needed, stop existing nginx processes:
   ```bash
   pkill -9 nginx
   ```
 ---
 ### Issue: Frontend Compilation Fails
 **Symptoms**:
 Compilation errors appear in `frontend.log`.
 **Solutions**:
 1. Check frontend logs:
   ```bash
   tail -f logs/frontend.log
   ```
 2. Check whether Node.js version is 22+
 3. Reinstall frontend dependencies:
   ```bash
   cd frontend
   rm -rf node_modules .next
   pnpm install
   ```
 4. Restart services:
   ```bash
   make stop
   make dev-daemon
   ```
 ---
 ### Issue: Gateway Fails to Start
 **Symptoms**:
 Errors appear in `gateway.log`.
 **Solutions**:
 1. Check gateway logs:
   ```bash
   tail -f logs/gateway.log
   ```
 2. Check whether config.yaml exists and has valid formatting
 3. Check whether Python dependencies are complete:
   ```bash
   cd backend
   uv sync
   ```
 4. Confirm that the LangGraph service is running normally (if not in gateway mode)
 ---
 ### Issue: LangGraph Fails to Start
 **Symptoms**:
 Errors appear in `langgraph.log`.
 **Solutions**:
 1. Check LangGraph logs:
   ```bash
   tail -f logs/langgraph.log
   ```
 2. Check config.yaml
 3. Check whether Python dependencies are complete
 4. Confirm that port 2024 is not occupied
 ---
 ## Docker-Related Issues
 ### Issue: Docker Commands Cannot Run
 **Symptoms**:
 ```
 Cannot connect to the Docker daemon
 ```
 **Solutions**:
 1. Confirm that Docker Desktop is running
 2. macOS: check whether the Docker icon appears in the top menu bar
 3. Linux: run `sudo systemctl start docker`
 4. Run `docker info` again to verify
 ---
 ### Issue: `make docker-init` Fails to Pull the Image
 **Symptoms**:
 ```
 Error pulling image: connection refused
 ```
 **Solutions**:
 1. Check network connectivity
 2. Configure a Docker image mirror if needed
 3. Check whether a proxy is required
 4. Switch to local installation mode if necessary (recommended)
 ---
 ## Configuration File Issues
 ### Issue: config.yaml Is Missing or Invalid
 **Symptoms**:
 ```
 Error: could not read config.yaml
 ```
 **Solutions**:
 1. Regenerate the configuration file:
   ```bash
   make config
   ```
 2. Check YAML syntax:
   - Make sure indentation is correct (use 2 spaces)
   - Make sure there are no tab characters
   - Check that there is a space after each colon
 3. Use a YAML validation tool to check the format
 ---
 ### Issue: Model API Key Is Not Configured
 **Symptoms**:
 After services start, API requests fail with authentication errors.
 **Solutions**:
 1. Edit the .env file and add the API key:
   ```bash
   OPENAI_API_KEY=your-actual-api-key-here
   ```
 2. Restart services (local mode):
   ```bash
   make stop
   make dev-daemon
   ```
 3. Restart services (Docker mode):
   ```bash
   make docker-stop
   make docker-start
   ```
 4. Confirm that the model configuration in config.yaml references the environment variable correctly
 ---
 ## Service Health Check Issues
 ### Issue: Frontend Page Is Not Accessible
 **Symptoms**:
 The browser shows a connection failure when visiting http://localhost:2026.
 **Solutions** (local mode):
 1. Confirm that the nginx process is running:
   ```bash
   ps aux | grep nginx
   ```
 2. Check nginx logs:
   ```bash
   tail -f logs/nginx.log
   ```
 3. Check firewall settings
 **Solutions** (Docker mode):
 1. Confirm that the nginx container is running:
   ```bash
   docker ps | grep nginx
   ```
 2. Check nginx logs:
   ```bash
   cd docker && docker compose -p deer-flow-dev -f docker-compose-dev.yaml logs nginx
   ```
 3. Check firewall settings
 ---
 ### Issue: API Gateway Health Check Fails
 **Symptoms**:
 Accessing `/health` returns an error or times out.
 **Solutions** (local mode):
 1. Check gateway logs:
   ```bash
   tail -f logs/gateway.log
   ```
 2. Confirm that config.yaml exists and has valid formatting
 3. Check whether Python dependencies are complete
 4. Confirm that the LangGraph service is running normally
 **Solutions** (Docker mode):
 1. Check gateway container logs:
   ```bash
   make docker-logs-gateway
   ```
 2. Confirm that config.yaml is mounted correctly
 3. Check whether Python dependencies are complete
 4. Confirm that the LangGraph service is running normally
 ---
 ## Common Diagnostic Commands
 ### Local Mode Diagnostics
 #### View All Service Processes
 ```bash
 ps aux | grep -E "(langgraph|uvicorn|next|nginx)" | grep -v grep
 ```
 #### View Service Logs
 ```bash
 # View all logs
 tail -f logs/*.log
 # View specific service logs
 tail -f logs/langgraph.log
 tail -f logs/gateway.log
 tail -f logs/frontend.log
 tail -f logs/nginx.log
 ```
 #### Stop All Services
 ```bash
 make stop
 ```
 #### Fully Reset the Local Environment
 ```bash
 make stop
 make clean
 make config
 make install
 make dev-daemon
 ```
 ---
 ### Docker Mode Diagnostics
 #### View All Container Status
 ```bash
 docker ps -a
 ```
 #### View Container Resource Usage
 ```bash
 docker stats
 ```
 #### Enter a Container for Debugging
 ```bash
 docker exec -it deer-flow-gateway sh
 ```
 #### Clean Up All DeerFlow-Related Containers and Images
 ```bash
 make docker-stop
 cd docker && docker compose -p deer-flow-dev -f docker-compose-dev.yaml down -v
 ```
 #### Fully Reset the Docker Environment
 ```bash
 make docker-stop
 make clean
 make config
 make docker-init
 make docker-start
 ```
 ---
 ## Get More Help
 If the solutions above do not resolve the issue:
 1. Check the GitHub issues for the project: https://github.com/bytedance/deer-flow/issues
 2. Review the project documentation: README.md and the `backend/docs/` directory
 3. Open a new issue and include detailed error logs
@@ -1,80 +0,0 @@
 #!/usr/bin/env bash
 set -e
 echo "=========================================="
 echo "  Checking Docker Environment"
 echo "=========================================="
 echo ""
 # Check whether Docker is installed
 if command -v docker >/dev/null 2>&1; then
    echo "✓ Docker is installed"
    docker --version
 else
    echo "✗ Docker is not installed"
    exit 1
 fi
 echo ""
 # Check the Docker daemon
 if docker info >/dev/null 2>&1; then
    echo "✓ Docker daemon is running normally"
 else
    echo "✗ Docker daemon is not running"
    echo "  Please start Docker Desktop or the Docker service"
    exit 1
 fi
 echo ""
 # Check Docker Compose
 if docker compose version >/dev/null 2>&1; then
    echo "✓ Docker Compose is available"
    docker compose version
 else
    echo "✗ Docker Compose is not available"
    exit 1
 fi
 echo ""
 # Check port 2026
 if ! command -v lsof >/dev/null 2>&1; then
    echo "✗ lsof is required to check whether port 2026 is available"
    exit 1
 fi
 port_2026_usage="$(lsof -nP -iTCP:2026 -sTCP:LISTEN 2>/dev/null || true)"
 if [ -n "$port_2026_usage" ]; then
    echo "⚠  Port 2026 is already in use"
    echo "  Occupying process:"
    echo "$port_2026_usage"
    deerflow_process_found=0
    while IFS= read -r pid; do
        if [ -z "$pid" ]; then
            continue
        fi
        process_command="$(ps -p "$pid" -o command= 2>/dev/null || true)"
        case "$process_command" in
            *[Dd]eer[Ff]low*|*[Dd]eerflow*|*[Nn]ginx*deerflow*|*deerflow/*[Nn]ginx*)
                deerflow_process_found=1
                ;;
        esac
    done <<EOF
 $(printf '%s\n' "$port_2026_usage" | awk 'NR > 1 {print $2}')
 EOF
    if [ "$deerflow_process_found" -eq 1 ]; then
        echo "✓ Port 2026 is occupied by DeerFlow"
    else
        echo "✗ Port 2026 must be free before starting DeerFlow"
        exit 1
    fi
 else
    echo "✓ Port 2026 is available"
 fi
 echo ""
 echo "=========================================="
 echo "  Docker Environment Check Complete"
 echo "=========================================="
@@ -1,93 +0,0 @@
 #!/usr/bin/env bash
 set -e
 echo "=========================================="
 echo "  Checking Local Development Environment"
 echo "=========================================="
 echo ""
 all_passed=true
 # Check Node.js
 echo "1. Checking Node.js..."
 if command -v node >/dev/null 2>&1; then
    NODE_VERSION=$(node --version | sed 's/v//')
    NODE_MAJOR=$(echo "$NODE_VERSION" | cut -d. -f1)
    if [ "$NODE_MAJOR" -ge 22 ]; then
        echo "✓ Node.js is installed (version: $NODE_VERSION)"
    else
        echo "✗ Node.js version is too old (current: $NODE_VERSION, required: 22+)"
        all_passed=false
    fi
 else
    echo "✗ Node.js is not installed"
    all_passed=false
 fi
 echo ""
 # Check pnpm
 echo "2. Checking pnpm..."
 if command -v pnpm >/dev/null 2>&1; then
    echo "✓ pnpm is installed (version: $(pnpm --version))"
 else
    echo "✗ pnpm is not installed"
    echo "  Install command: npm install -g pnpm"
    all_passed=false
 fi
 echo ""
 # Check uv
 echo "3. Checking uv..."
 if command -v uv >/dev/null 2>&1; then
    echo "✓ uv is installed (version: $(uv --version))"
 else
    echo "✗ uv is not installed"
    all_passed=false
 fi
 echo ""
 # Check nginx
 echo "4. Checking nginx..."
 if command -v nginx >/dev/null 2>&1; then
    echo "✓ nginx is installed (version: $(nginx -v 2>&1))"
 else
    echo "✗ nginx is not installed"
    echo "  macOS: brew install nginx"
    echo "  Linux: install it with the system package manager"
    all_passed=false
 fi
 echo ""
 # Check ports
 echo "5. Checking ports..."
 if ! command -v lsof >/dev/null 2>&1; then
    echo "✗ lsof is not installed, so port availability cannot be verified"
    echo "  Install lsof and rerun this check"
    all_passed=false
 else
    for port in 2026 3000 8001 2024; do
        if lsof -i :$port >/dev/null 2>&1; then
            echo "⚠  Port $port is already in use:"
            lsof -i :$port | head -2
            all_passed=false
        else
            echo "✓ Port $port is available"
        fi
    done
 fi
 echo ""
 # Summary
 echo "=========================================="
 echo "  Environment Check Summary"
 echo "=========================================="
 echo ""
 if [ "$all_passed" = true ]; then
    echo "✅ All environment checks passed!"
    echo ""
    echo "Next step: run make install to install dependencies"
    exit 0
 else
    echo "❌ Some checks failed. Please fix the issues above first"
    exit 1
 fi
@@ -1,65 +0,0 @@
 #!/usr/bin/env bash
 set -e
 echo "=========================================="
 echo "  Docker Deployment"
 echo "=========================================="
 echo ""
 # Check config.yaml
 if [ ! -f "config.yaml" ]; then
    echo "config.yaml does not exist. Generating it..."
    make config
    echo ""
    echo "⚠  Please edit config.yaml to configure your models and API keys"
    echo "  Then run this script again"
    exit 1
 else
    echo "✓ config.yaml exists"
 fi
 echo ""
 # Check the .env file
 if [ ! -f ".env" ]; then
    echo ".env does not exist. Copying it from the example..."
    if [ -f ".env.example" ]; then
        cp .env.example .env
        echo "✓ Created the .env file"
    else
        echo "⚠  .env.example does not exist. Please create the .env file manually"
    fi
 else
    echo "✓ .env file exists"
 fi
 echo ""
 # Check the frontend .env file
 if [ ! -f "frontend/.env" ]; then
    echo "frontend/.env does not exist. Copying it from the example..."
    if [ -f "frontend/.env.example" ]; then
        cp frontend/.env.example frontend/.env
        echo "✓ Created the frontend/.env file"
    else
        echo "⚠  frontend/.env.example does not exist. Please create frontend/.env manually"
    fi
 else
    echo "✓ frontend/.env file exists"
 fi
 echo ""
 # Initialize the Docker environment
 echo "Initializing the Docker environment..."
 make docker-init
 echo ""
 # Start Docker services
 echo "Starting Docker services..."
 make docker-start
 echo ""
 echo "=========================================="
 echo "  Deployment Complete"
 echo "=========================================="
 echo ""
 echo "🌐 Access URL: http://localhost:2026"
 echo "📋 View logs: make docker-logs"
 echo "🛑 Stop services: make docker-stop"
@@ -1,63 +0,0 @@
 #!/usr/bin/env bash
 set -e
 echo "=========================================="
 echo "  Local Mode Deployment"
 echo "=========================================="
 echo ""
 # Check config.yaml
 if [ ! -f "config.yaml" ]; then
    echo "config.yaml does not exist. Generating it..."
    make config
    echo ""
    echo "⚠  Please edit config.yaml to configure your models and API keys"
    echo "  Then run this script again"
    exit 1
 else
    echo "✓ config.yaml exists"
 fi
 echo ""
 # Check the .env file
 if [ ! -f ".env" ]; then
    echo ".env does not exist. Copying it from the example..."
    if [ -f ".env.example" ]; then
        cp .env.example .env
        echo "✓ Created the .env file"
    else
        echo "⚠  .env.example does not exist. Please create the .env file manually"
    fi
 else
    echo "✓ .env file exists"
 fi
 echo ""
 # Check dependencies
 echo "Checking dependencies..."
 make check
 echo ""
 # Install dependencies
 echo "Installing dependencies..."
 make install
 echo ""
 # Start services
 echo "Starting services (background mode)..."
 make dev-daemon
 echo ""
 echo "=========================================="
 echo "  Deployment Complete"
 echo "=========================================="
 echo ""
 echo "🌐 Access URL: http://localhost:2026"
 echo "📋 View logs:"
 echo "   - logs/langgraph.log"
 echo "   - logs/gateway.log"
 echo "   - logs/frontend.log"
 echo "   - logs/nginx.log"
 echo "🛑 Stop services: make stop"
 echo ""
 echo "Please wait 90-120 seconds for all services to start completely, then run the health check"
@@ -1,70 +0,0 @@
 #!/usr/bin/env bash
 set +e
 echo "=========================================="
 echo "  Frontend Page Smoke Check"
 echo "=========================================="
 echo ""
 BASE_URL="${BASE_URL:-http://localhost:2026}"
 DOC_PATH="${DOC_PATH:-/en/docs}"
 all_passed=true
 check_status() {
    local name="$1"
    local url="$2"
    local expected_re="$3"
    local status
    status="$(curl -s -o /dev/null -w "%{http_code}" -L "$url")"
    if echo "$status" | grep -Eq "$expected_re"; then
        echo "✓ $name ($url) -> $status"
    else
        echo "✗ $name ($url) -> $status (expected: $expected_re)"
        all_passed=false
    fi
 }
 check_final_url() {
    local name="$1"
    local url="$2"
    local expected_path_re="$3"
    local effective
    effective="$(curl -s -o /dev/null -w "%{url_effective}" -L "$url")"
    if echo "$effective" | grep -Eq "$expected_path_re"; then
        echo "✓ $name redirect target -> $effective"
    else
        echo "✗ $name redirect target -> $effective (expected path: $expected_path_re)"
        all_passed=false
    fi
 }
 echo "1. Checking entry pages..."
 check_status "Landing page" "${BASE_URL}/" "200"
 check_status "Workspace redirect" "${BASE_URL}/workspace" "200|301|302|307|308"
 check_final_url "Workspace redirect" "${BASE_URL}/workspace" "/workspace/chats/"
 echo ""
 echo "2. Checking key workspace routes..."
 check_status "New chat page" "${BASE_URL}/workspace/chats/new" "200"
 check_status "Chats list page" "${BASE_URL}/workspace/chats" "200"
 check_status "Agents gallery page" "${BASE_URL}/workspace/agents" "200"
 echo ""
 echo "3. Checking docs route (optional)..."
 check_status "Docs page" "${BASE_URL}${DOC_PATH}" "200|404"
 echo ""
 echo "=========================================="
 echo "  Frontend Smoke Check Summary"
 echo "=========================================="
 echo ""
 if [ "$all_passed" = true ]; then
    echo "✅ Frontend smoke checks passed!"
    exit 0
 else
    echo "❌ Frontend smoke checks failed"
    exit 1
 fi
@@ -1,125 +0,0 @@
 #!/usr/bin/env bash
 set +e
 echo "=========================================="
 echo "  Service Health Check"
 echo "=========================================="
 echo ""
 all_passed=true
 mode="${SMOKE_TEST_MODE:-auto}"
 summary_hint="make logs"
 print_step() {
    echo "$1"
 }
 check_http_status() {
    local name="$1"
    local url="$2"
    local expected_re="$3"
    local status
    status="$(curl -s -o /dev/null -w "%{http_code}" "$url" 2>/dev/null)"
    if echo "$status" | grep -Eq "$expected_re"; then
        echo "✓ $name is accessible ($url -> $status)"
    else
        echo "✗ $name is not accessible ($url -> ${status:-000})"
        all_passed=false
    fi
 }
 check_listen_port() {
    local name="$1"
    local port="$2"
    if lsof -nP -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; then
        echo "✓ $name is listening on port $port"
    else
        echo "✗ $name is not listening on port $port"
        all_passed=false
    fi
 }
 docker_available() {
    command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1
 }
 detect_mode() {
    case "$mode" in
        local|docker)
            echo "$mode"
            return
            ;;
    esac
    if docker_available && docker ps --format "{{.Names}}" | grep -q "deer-flow"; then
        echo "docker"
    else
        echo "local"
    fi
 }
 mode="$(detect_mode)"
 echo "Deployment mode: $mode"
 echo ""
 if [ "$mode" = "docker" ]; then
    summary_hint="make docker-logs"
    print_step "1. Checking container status..."
    if docker ps --format "{{.Names}}" | grep -q "deer-flow"; then
        echo "✓ Containers are running:"
        docker ps --format "  - {{.Names}} ({{.Status}})"
    else
        echo "✗ No DeerFlow-related containers are running"
        all_passed=false
    fi
 else
    summary_hint="logs/{langgraph,gateway,frontend,nginx}.log"
    print_step "1. Checking local service ports..."
    check_listen_port "Nginx" 2026
    check_listen_port "Frontend" 3000
    check_listen_port "Gateway" 8001
    check_listen_port "LangGraph" 2024
 fi
 echo ""
 echo "2. Waiting for services to fully start (30 seconds)..."
 sleep 30
 echo ""
 echo "3. Checking frontend service..."
 check_http_status "Frontend service" "http://localhost:2026" "200|301|302|307|308"
 echo ""
 echo "4. Checking API Gateway..."
 health_response=$(curl -s http://localhost:2026/health 2>/dev/null)
 if [ $? -eq 0 ] && [ -n "$health_response" ]; then
    echo "✓ API Gateway health check passed"
    echo "  Response: $health_response"
 else
    echo "✗ API Gateway health check failed"
    all_passed=false
 fi
 echo ""
 echo "5. Checking LangGraph service..."
 check_http_status "LangGraph service" "http://localhost:2024/" "200|301|302|307|308|404"
 echo ""
 echo "=========================================="
 echo "  Health Check Summary"
 echo "=========================================="
 echo ""
 if [ "$all_passed" = true ]; then
    echo "✅ All checks passed!"
    echo ""
    echo "🌐 Application URL: http://localhost:2026"
    exit 0
 else
    echo "❌ Some checks failed"
    echo ""
    echo "Please review: $summary_hint"
    exit 1
 fi
@@ -1,49 +0,0 @@
 #!/usr/bin/env bash
 set -e
 echo "=========================================="
 echo "  Pulling the Latest Code"
 echo "=========================================="
 echo ""
 # Check whether the current directory is a Git repository
 if [ ! -d ".git" ]; then
    echo "✗ The current directory is not a Git repository"
    exit 1
 fi
 # Check Git status
 echo "Checking Git status..."
 if git status --porcelain | grep -q .; then
    echo "⚠  Uncommitted changes detected:"
    git status --short
    echo ""
    echo "Please commit or stash your changes before continuing"
    echo "Options:"
    echo "  1. git add . && git commit -m 'Save changes'"
    echo "  2. git stash (stash changes and restore them later)"
    echo "  3. git reset --hard HEAD (discard local changes - use with caution)"
    exit 1
 else
    echo "✓ Working tree is clean"
 fi
 echo ""
 # Fetch remote updates
 echo "Fetching remote updates..."
 git fetch origin main
 echo ""
 # Pull the latest code
 echo "Pulling the latest code..."
 git pull origin main
 echo ""
 # Show the latest commit
 echo "Latest commit:"
 git log -1 --oneline
 echo ""
 echo "=========================================="
 echo "  Code Update Complete"
 echo "=========================================="
@@ -1,180 +0,0 @@
 # DeerFlow Smoke Test Report
 **Test Date**: {{test_date}}  
 **Test Environment**: {{test_environment}}  
 **Deployment Mode**: Docker  
 **Test Version**: {{git_commit}}
 ---
 ## Execution Summary
 | Metric | Status |
 |------|------|
 | Total Test Phases | 6 |
 | Passed Phases | {{passed_stages}} |
 | Failed Phases | {{failed_stages}} |
 | Overall Conclusion | **{{overall_status}}** |
 ### Key Test Cases
 | Case | Result | Details |
 |------|--------|---------|
 | Code update check | {{case_code_update}} | {{case_code_update_details}} |
 | Environment check | {{case_env_check}} | {{case_env_check_details}} |
 | Configuration preparation | {{case_config_prep}} | {{case_config_prep_details}} |
 | Deployment | {{case_deploy}} | {{case_deploy_details}} |
 | Health check | {{case_health_check}} | {{case_health_check_details}} |
 | Frontend routes | {{case_frontend_routes_overall}} | {{case_frontend_routes_details}} |
 ---
 ## Detailed Test Results
 ### Phase 1: Code Update Check
 - [x] Confirm current directory - {{status_dir_check}}
 - [x] Check Git status - {{status_git_status}}
 - [x] Pull latest code - {{status_git_pull}}
 - [x] Confirm code update - {{status_git_verify}}
 **Phase Status**: {{stage1_status}}
 ---
 ### Phase 2: Docker Environment Check
 - [x] Docker version - {{status_docker_version}}
 - [x] Docker daemon - {{status_docker_daemon}}
 - [x] Docker Compose - {{status_docker_compose}}
 - [x] Port check - {{status_port_check}}
 **Phase Status**: {{stage2_status}}
 ---
 ### Phase 3: Configuration Preparation
 - [x] config.yaml - {{status_config_yaml}}
 - [x] .env file - {{status_env_file}}
 - [x] Model configuration - {{status_model_config}}
 **Phase Status**: {{stage3_status}}
 ---
 ### Phase 4: Docker Deployment
 - [x] docker-init - {{status_docker_init}}
 - [x] docker-start - {{status_docker_start}}
 - [x] Service startup wait - {{status_wait_startup}}
 **Phase Status**: {{stage4_status}}
 ---
 ### Phase 5: Service Health Check
 - [x] Container status - {{status_containers}}
 - [x] Frontend service - {{status_frontend}}
 - [x] API Gateway - {{status_api_gateway}}
 - [x] LangGraph service - {{status_langgraph}}
 **Phase Status**: {{stage5_status}}
 ---
 ### Frontend Routes Smoke Results
 | Route | Status | Details |
 |-------|--------|---------|
 | Landing `/` | {{landing_status}} | {{landing_details}} |
 | Workspace redirect `/workspace` | {{workspace_redirect_status}} | target {{workspace_redirect_target}} |
 | New chat `/workspace/chats/new` | {{new_chat_status}} | {{new_chat_details}} |
 | Chats list `/workspace/chats` | {{chats_list_status}} | {{chats_list_details}} |
 | Agents gallery `/workspace/agents` | {{agents_gallery_status}} | {{agents_gallery_details}} |
 | Docs `{{docs_path}}` | {{docs_status}} | {{docs_details}} |
 **Summary**: {{frontend_routes_summary}}
 ---
 ### Phase 6: Test Report Generation
 - [x] Result summary - {{status_summary}}
 - [x] Issue log - {{status_issues}}
 - [x] Report generation - {{status_report}}
 **Phase Status**: {{stage6_status}}
 ---
 ## Issue Log
 ### Issue 1
 **Description**: {{issue1_description}}  
 **Severity**: {{issue1_severity}}  
 **Solution**: {{issue1_solution}}
 ---
 ## Environment Information
 ### Docker Version
 ```text
 {{docker_version_output}}
 ```
 ### Git Information
 ```text
 Repository: {{git_repo}}
 Branch: {{git_branch}}
 Commit: {{git_commit}}
 Commit Message: {{git_commit_message}}
 ```
 ### Configuration Summary
 - config.yaml exists: {{config_exists}}
 - .env file exists: {{env_exists}}
 - Number of configured models: {{model_count}}
 ---
 ## Container Status
 | Container Name | Status | Uptime |
 |----------|------|----------|
 | deer-flow-nginx | {{nginx_status}} | {{nginx_uptime}} |
 | deer-flow-frontend | {{frontend_status}} | {{frontend_uptime}} |
 | deer-flow-gateway | {{gateway_status}} | {{gateway_uptime}} |
 | deer-flow-langgraph | {{langgraph_status}} | {{langgraph_uptime}} |
 ---
 ## Recommendations and Next Steps
 ### If the Test Passes
 1. [ ] Visit http://localhost:2026 to start using DeerFlow
 2. [ ] Configure your preferred model if it is not configured yet
 3. [ ] Explore available skills
 4. [ ] Refer to the documentation to learn more features
 ### If the Test Fails
 1. [ ] Review references/troubleshooting.md for common solutions
 2. [ ] Check Docker logs: `make docker-logs`
 3. [ ] Verify configuration file format and content
 4. [ ] If needed, fully reset the environment: `make clean && make config && make docker-init && make docker-start`
 ---
 ## Appendix
 ### Full Logs
 {{full_logs}}
 ### Tester
 {{tester_name}}
 ---
 *Report generated at: {{report_time}}*
@@ -1,185 +0,0 @@
 # DeerFlow Smoke Test Report
 **Test Date**: {{test_date}}  
 **Test Environment**: {{test_environment}}  
 **Deployment Mode**: Local  
 **Test Version**: {{git_commit}}
 ---
 ## Execution Summary
 | Metric | Status |
 |------|------|
 | Total Test Phases | 6 |
 | Passed Phases | {{passed_stages}} |
 | Failed Phases | {{failed_stages}} |
 | Overall Conclusion | **{{overall_status}}** |
 ### Key Test Cases
 | Case | Result | Details |
 |------|--------|---------|
 | Code update check | {{case_code_update}} | {{case_code_update_details}} |
 | Environment check | {{case_env_check}} | {{case_env_check_details}} |
 | Configuration preparation | {{case_config_prep}} | {{case_config_prep_details}} |
 | Deployment | {{case_deploy}} | {{case_deploy_details}} |
 | Health check | {{case_health_check}} | {{case_health_check_details}} |
 | Frontend routes | {{case_frontend_routes_overall}} | {{case_frontend_routes_details}} |
 ---
 ## Detailed Test Results
 ### Phase 1: Code Update Check
 - [x] Confirm current directory - {{status_dir_check}}
 - [x] Check Git status - {{status_git_status}}
 - [x] Pull latest code - {{status_git_pull}}
 - [x] Confirm code update - {{status_git_verify}}
 **Phase Status**: {{stage1_status}}
 ---
 ### Phase 2: Local Environment Check
 - [x] Node.js version - {{status_node_version}}
 - [x] pnpm - {{status_pnpm}}
 - [x] uv - {{status_uv}}
 - [x] nginx - {{status_nginx}}
 - [x] Port check - {{status_port_check}}
 **Phase Status**: {{stage2_status}}
 ---
 ### Phase 3: Configuration Preparation
 - [x] config.yaml - {{status_config_yaml}}
 - [x] .env file - {{status_env_file}}
 - [x] Model configuration - {{status_model_config}}
 **Phase Status**: {{stage3_status}}
 ---
 ### Phase 4: Local Deployment
 - [x] make check - {{status_make_check}}
 - [x] make install - {{status_make_install}}
 - [x] make dev-daemon / make dev - {{status_local_start}}
 - [x] Service startup wait - {{status_wait_startup}}
 **Phase Status**: {{stage4_status}}
 ---
 ### Phase 5: Service Health Check
 - [x] Process status - {{status_processes}}
 - [x] Frontend service - {{status_frontend}}
 - [x] API Gateway - {{status_api_gateway}}
 - [x] LangGraph service - {{status_langgraph}}
 **Phase Status**: {{stage5_status}}
 ---
 ### Frontend Routes Smoke Results
 | Route | Status | Details |
 |-------|--------|---------|
 | Landing `/` | {{landing_status}} | {{landing_details}} |
 | Workspace redirect `/workspace` | {{workspace_redirect_status}} | target {{workspace_redirect_target}} |
 | New chat `/workspace/chats/new` | {{new_chat_status}} | {{new_chat_details}} |
 | Chats list `/workspace/chats` | {{chats_list_status}} | {{chats_list_details}} |
 | Agents gallery `/workspace/agents` | {{agents_gallery_status}} | {{agents_gallery_details}} |
 | Docs `{{docs_path}}` | {{docs_status}} | {{docs_details}} |
 **Summary**: {{frontend_routes_summary}}
 ---
 ### Phase 6: Test Report Generation
 - [x] Result summary - {{status_summary}}
 - [x] Issue log - {{status_issues}}
 - [x] Report generation - {{status_report}}
 **Phase Status**: {{stage6_status}}
 ---
 ## Issue Log
 ### Issue 1
 **Description**: {{issue1_description}}  
 **Severity**: {{issue1_severity}}  
 **Solution**: {{issue1_solution}}
 ---
 ## Environment Information
 ### Local Dependency Versions
 ```text
 Node.js: {{node_version_output}}
 pnpm: {{pnpm_version_output}}
 uv: {{uv_version_output}}
 nginx: {{nginx_version_output}}
 ```
 ### Git Information
 ```text
 Repository: {{git_repo}}
 Branch: {{git_branch}}
 Commit: {{git_commit}}
 Commit Message: {{git_commit_message}}
 ```
 ### Configuration Summary
 - config.yaml exists: {{config_exists}}
 - .env file exists: {{env_exists}}
 - Number of configured models: {{model_count}}
 ---
 ## Local Service Status
 | Service | Status | Endpoint |
 |---------|--------|----------|
 | Nginx | {{nginx_status}} | {{nginx_endpoint}} |
 | Frontend | {{frontend_status}} | {{frontend_endpoint}} |
 | Gateway | {{gateway_status}} | {{gateway_endpoint}} |
 | LangGraph | {{langgraph_status}} | {{langgraph_endpoint}} |
 ---
 ## Recommendations and Next Steps
 ### If the Test Passes
 1. [ ] Visit http://localhost:2026 to start using DeerFlow
 2. [ ] Configure your preferred model if it is not configured yet
 3. [ ] Explore available skills
 4. [ ] Refer to the documentation to learn more features
 ### If the Test Fails
 1. [ ] Review references/troubleshooting.md for common solutions
 2. [ ] Check local logs: `logs/{langgraph,gateway,frontend,nginx}.log`
 3. [ ] Verify configuration file format and content
 4. [ ] If needed, fully reset the environment: `make stop && make clean && make install && make dev-daemon`
 ---
 ## Appendix
 ### Full Logs
 {{full_logs}}
 ### Tester
 {{tester_name}}
 ---
 *Report generated at: {{report_time}}*
@@ -17,14 +17,12 @@ INFOQUEST_API_KEY=your-infoquest-api-key
 # DEEPSEEK_API_KEY=your-deepseek-api-key
 # NOVITA_API_KEY=your-novita-api-key  # OpenAI-compatible, see https://novita.ai
 # MINIMAX_API_KEY=your-minimax-api-key  # OpenAI-compatible, see https://platform.minimax.io
 # VLLM_API_KEY=your-vllm-api-key  # OpenAI-compatible
 # FEISHU_APP_ID=your-feishu-app-id
 # FEISHU_APP_SECRET=your-feishu-app-secret
 # SLACK_BOT_TOKEN=your-slack-bot-token
 # SLACK_APP_TOKEN=your-slack-app-token
 # TELEGRAM_BOT_TOKEN=your-telegram-bot-token
 # DISCORD_BOT_TOKEN=your-discord-bot-token
 # Enable LangSmith to monitor and debug your LLM calls, agent runs, and tool executions.
 # LANGSMITH_TRACING=true
@@ -34,5 +32,3 @@ INFOQUEST_API_KEY=your-infoquest-api-key
 # GitHub API Token
 # GITHUB_TOKEN=your-github-token
 # WECOM_BOT_ID=your-wecom-bot-id
 # WECOM_BOT_SECRET=your-wecom-bot-secret
@@ -1,63 +0,0 @@
 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
@@ -1,43 +0,0 @@
 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
@@ -2,6 +2,8 @@
 docker/.cache/
 # oh-my-claudecode state
 .omc/
 # Collaborator plugin state
 .collaborator/
 # OS generated files
 .DS_Store
 *.local
@@ -40,7 +42,6 @@ coverage/
 skills/custom/*
 logs/
 log/
 debug.log
 # Local git hooks (keep only on this machine, do not push)
 .githooks/
@@ -55,8 +56,3 @@ web/
 # Deployment artifacts
 backend/Dockerfile.langgraph
 config.yaml.bak
 .playwright-mcp
 /frontend/test-results/
 /frontend/playwright-report/
 .gstack/
 .worktrees
@@ -1,33 +0,0 @@
 repos:
  # Backend: ruff lint + format via uv (uses the same ruff version as backend deps)
  - repo: local
    hooks:
      - id: ruff
        name: ruff lint
        entry: bash -c 'cd backend && uv run ruff check --fix "${@/#backend\//}"' --
        language: system
        types_or: [python]
        files: ^backend/
      - id: ruff-format
        name: ruff format
        entry: bash -c 'cd backend && uv run ruff format "${@/#backend\//}"' --
        language: system
        types_or: [python]
        files: ^backend/
  # Frontend: eslint + prettier (must run from frontend/ for node_modules resolution)
  - repo: local
    hooks:
      - id: frontend-eslint
        name: eslint (frontend)
        entry: bash -c 'cd frontend && npx eslint --fix "${@/#frontend\//}"' --
        language: system
        types_or: [javascript, tsx, ts]
        files: ^frontend/
      - id: frontend-prettier
        name: prettier (frontend)
        entry: bash -c 'cd frontend && npx prettier --write "${@/#frontend\//}"' --
        language: system
        files: ^frontend/
        types_or: [javascript, tsx, ts, json, css]
@@ -1,128 +0,0 @@
 # Contributor Covenant Code of Conduct
 ## Our Pledge
 We as members, contributors, and leaders pledge to make participation in our
 community a harassment-free experience for everyone, regardless of age, body
 size, visible or invisible disability, ethnicity, sex characteristics, gender
 identity and expression, level of experience, education, socio-economic status,
 nationality, personal appearance, race, religion, or sexual identity
 and orientation.
 We pledge to act and interact in ways that contribute to an open, welcoming,
 diverse, inclusive, and healthy community.
 ## Our Standards
 Examples of behavior that contributes to a positive environment for our
 community include:
 * Demonstrating empathy and kindness toward other people
 * Being respectful of differing opinions, viewpoints, and experiences
 * Giving and gracefully accepting constructive feedback
 * Accepting responsibility and apologizing to those affected by our mistakes,
  and learning from the experience
 * Focusing on what is best not just for us as individuals, but for the
  overall community
 Examples of unacceptable behavior include:
 * The use of sexualized language or imagery, and sexual attention or
  advances of any kind
 * Trolling, insulting or derogatory comments, and personal or political attacks
 * Public or private harassment
 * Publishing others' private information, such as a physical or email
  address, without their explicit permission
 * Other conduct which could reasonably be considered inappropriate in a
  professional setting
 ## Enforcement Responsibilities
 Community leaders are responsible for clarifying and enforcing our standards of
 acceptable behavior and will take appropriate and fair corrective action in
 response to any behavior that they deem inappropriate, threatening, offensive,
 or harmful.
 Community leaders have the right and responsibility to remove, edit, or reject
 comments, commits, code, wiki edits, issues, and other contributions that are
 not aligned to this Code of Conduct, and will communicate reasons for moderation
 decisions when appropriate.
 ## Scope
 This Code of Conduct applies within all community spaces, and also applies when
 an individual is officially representing the community in public spaces.
 Examples of representing our community include using an official e-mail address,
 posting via an official social media account, or acting as an appointed
 representative at an online or offline event.
 ## Enforcement
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
 willem.jiang@gmail.com.
 All complaints will be reviewed and investigated promptly and fairly.
 All community leaders are obligated to respect the privacy and security of the
 reporter of any incident.
 ## Enforcement Guidelines
 Community leaders will follow these Community Impact Guidelines in determining
 the consequences for any action they deem in violation of this Code of Conduct:
 ### 1. Correction
 **Community Impact**: Use of inappropriate language or other behavior deemed
 unprofessional or unwelcome in the community.
 **Consequence**: A private, written warning from community leaders, providing
 clarity around the nature of the violation and an explanation of why the
 behavior was inappropriate. A public apology may be requested.
 ### 2. Warning
 **Community Impact**: A violation through a single incident or series
 of actions.
 **Consequence**: A warning with consequences for continued behavior. No
 interaction with the people involved, including unsolicited interaction with
 those enforcing the Code of Conduct, for a specified period of time. This
 includes avoiding interactions in community spaces as well as external channels
 like social media. Violating these terms may lead to a temporary or
 permanent ban.
 ### 3. Temporary Ban
 **Community Impact**: A serious violation of community standards, including
 sustained inappropriate behavior.
 **Consequence**: A temporary ban from any sort of interaction or public
 communication with the community for a specified period of time. No public or
 private interaction with the people involved, including unsolicited interaction
 with those enforcing the Code of Conduct, is allowed during this period.
 Violating these terms may lead to a permanent ban.
 ### 4. Permanent Ban
 **Community Impact**: Demonstrating a pattern of violation of community
 standards, including sustained inappropriate behavior,  harassment of an
 individual, or aggression toward or disparagement of classes of individuals.
 **Consequence**: A permanent ban from any sort of public interaction within
 the community.
 ## Attribution
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.0, available at
 https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).
 [homepage]: https://www.contributor-covenant.org
 For answers to common questions about this code of conduct, see the FAQ at
 https://www.contributor-covenant.org/faq. Translations are available at
 https://www.contributor-covenant.org/translations.
@@ -77,18 +77,6 @@ export UV_INDEX_URL=https://pypi.org/simple
 export NPM_REGISTRY=https://registry.npmjs.org
 ```
 #### Recommended host resources
 Use these as practical starting points for development and review environments:
 | Scenario | Starting point | Recommended | Notes |
 |---------|-----------|------------|-------|
 | `make dev` on one machine | 4 vCPU, 8 GB RAM | 8 vCPU, 16 GB RAM | Best when DeerFlow uses hosted model APIs. |
 | `make docker-start` review environment | 4 vCPU, 8 GB RAM | 8 vCPU, 16 GB RAM | Docker image builds and sandbox containers need extra headroom. |
 | Shared Linux test server | 8 vCPU, 16 GB RAM | 16 vCPU, 32 GB RAM | Prefer this for heavier multi-agent runs or multiple reviewers. |
 `2 vCPU / 4 GB` environments often fail to start reliably or become unresponsive under normal DeerFlow workloads.
 #### Linux: Docker daemon permission denied
 If `make docker-init`, `make docker-start`, or `make docker-stop` fails on Linux with an error like below, your current user likely does not have permission to access the Docker daemon socket:
@@ -166,7 +154,7 @@ Required tools:
 1. **Configure the application** (same as Docker setup above)
-2. **Install dependencies** (this also sets up pre-commit hooks):
+2. **Install dependencies**:
   ```bash
   make install
   ```
@@ -298,24 +286,19 @@ Nginx (port 2026) ← Unified entry point
 ```bash
 # Backend tests
 cd backend
-make test
+uv run pytest
-# Frontend unit tests
+# Frontend checks
 cd frontend
-make test
+pnpm check
 # 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 triggers the following CI workflows:
+Every pull request runs the backend regression workflow at [.github/workflows/backend-unit-tests.yml](.github/workflows/backend-unit-tests.yml), including:
- **Backend unit tests** — [.github/workflows/backend-unit-tests.yml](.github/workflows/backend-unit-tests.yml)
+- `tests/test_provisioner_kubeconfig.py`
- **Frontend unit tests** — [.github/workflows/frontend-unit-tests.yml](.github/workflows/frontend-unit-tests.yml)
+- `tests/test_docker_sandbox_mode_detection.py`
 - **Frontend E2E tests** — [.github/workflows/e2e-tests.yml](.github/workflows/e2e-tests.yml) (triggered only when `frontend/` files change)
 ## Code Style
@@ -327,7 +310,7 @@ Every pull request triggers the following CI workflows:
 - [Configuration Guide](backend/docs/CONFIGURATION.md) - Setup and configuration
 - [Architecture Overview](backend/CLAUDE.md) - Technical architecture
- [MCP Setup Guide](backend/docs/MCP_SERVER.md) - Model Context Protocol configuration
+- [MCP Setup Guide](MCP_SETUP.md) - Model Context Protocol configuration
 ## Need Help?
@@ -1,67 +1,45 @@
 # DeerFlow - Unified Development Environment
-.PHONY: help config config-upgrade check install setup doctor dev dev-pro dev-daemon dev-daemon-pro start start-pro start-daemon start-daemon-pro stop up up-pro down clean docker-init docker-start docker-start-pro docker-stop docker-logs docker-logs-frontend docker-logs-gateway
+.PHONY: help config config-upgrade check install dev dev-daemon start stop up down clean docker-init docker-start docker-stop docker-logs docker-logs-frontend docker-logs-gateway
 PYTHON ?= python
 BASH ?= bash
 BACKEND_UV_RUN = cd backend && uv run
 # Detect OS for Windows compatibility
 ifeq ($(OS),Windows_NT)
    SHELL := cmd.exe
    PYTHON ?= python
    # Run repo shell scripts through Git Bash when Make is launched from cmd.exe / PowerShell.
    RUN_WITH_GIT_BASH = call scripts\run-with-git-bash.cmd
 else
    PYTHON ?= python3
    RUN_WITH_GIT_BASH =
 endif
 help:
 	@echo "DeerFlow Development Commands:"
 	@echo "  make setup           - Interactive setup wizard (recommended for new users)"
 	@echo "  make doctor          - Check configuration and system requirements"
 	@echo "  make config          - Generate local config files (aborts if config already exists)"
 	@echo "  make config-upgrade  - Merge new fields from config.example.yaml into config.yaml"
 	@echo "  make check           - Check if all required tools are installed"
-	@echo "  make install         - Install all dependencies (frontend + backend + pre-commit hooks)"
+	@echo "  make install         - Install all dependencies (frontend + backend)"
 	@echo "  make setup-sandbox   - Pre-pull sandbox container image (recommended)"
 	@echo "  make dev             - Start all services in development mode (with hot-reloading)"
-	@echo "  make dev-pro         - Start in dev + Gateway mode (experimental, no LangGraph server)"
+	@echo "  make dev-daemon      - Start all services in background (daemon mode)"
 	@echo "  make dev-daemon      - Start dev services in background (daemon mode)"
 	@echo "  make dev-daemon-pro  - Start dev daemon + Gateway mode (experimental)"
 	@echo "  make start           - Start all services in production mode (optimized, no hot-reloading)"
 	@echo "  make start-pro       - Start in prod + Gateway mode (experimental)"
 	@echo "  make start-daemon    - Start prod services in background (daemon mode)"
 	@echo "  make start-daemon-pro - Start prod daemon + Gateway mode (experimental)"
 	@echo "  make stop            - Stop all running services"
 	@echo "  make clean           - Clean up processes and temporary files"
 	@echo ""
 	@echo "Docker Production Commands:"
 	@echo "  make up              - Build and start production Docker services (localhost:2026)"
 	@echo "  make up-pro          - Build and start production Docker in Gateway mode (experimental)"
 	@echo "  make down            - Stop and remove production Docker containers"
 	@echo ""
 	@echo "Docker Development Commands:"
 	@echo "  make docker-init     - Pull the sandbox image"
 	@echo "  make docker-start    - Start Docker services (mode-aware from config.yaml, localhost:2026)"
 	@echo "  make docker-start-pro - Start Docker in Gateway mode (experimental, no LangGraph container)"
 	@echo "  make docker-stop     - Stop Docker development services"
 	@echo "  make docker-logs     - View Docker development logs"
 	@echo "  make docker-logs-frontend - View Docker frontend logs"
 	@echo "  make docker-logs-gateway - View Docker gateway logs"
 ## Setup & Diagnosis
 setup:
 	@$(BACKEND_UV_RUN) python ../scripts/setup_wizard.py
 doctor:
 	@$(BACKEND_UV_RUN) python ../scripts/doctor.py
 config:
 	@$(PYTHON) ./scripts/configure.py
 config-upgrade:
-	@$(RUN_WITH_GIT_BASH) ./scripts/config-upgrade.sh
+	@./scripts/config-upgrade.sh
 # Check required tools
 check:
@@ -73,8 +51,6 @@ install:
 	@cd backend && uv sync
 	@echo "Installing frontend dependencies..."
 	@cd frontend && pnpm install
 	@echo "Installing pre-commit hooks..."
 	@$(BACKEND_UV_RUN) --with pre-commit pre-commit install
 	@echo "✓ All dependencies installed"
 	@echo ""
 	@echo "=========================================="
@@ -101,7 +77,7 @@ setup-sandbox:
 	echo ""; \
 	if command -v container >/dev/null 2>&1 && [ "$$(uname)" = "Darwin" ]; then \
 		echo "Detected Apple Container on macOS, pulling image..."; \
-		container image pull "$$IMAGE" || echo "⚠ Apple Container pull failed, will try Docker"; \
+		container pull "$$IMAGE" || echo "⚠ Apple Container pull failed, will try Docker"; \
 	fi; \
 	if command -v docker >/dev/null 2>&1; then \
 		echo "Pulling image using Docker..."; \
@@ -120,47 +96,39 @@ setup-sandbox:
 # Start all services in development mode (with hot-reloading)
 dev:
-	@$(PYTHON) ./scripts/check.py
+ifeq ($(OS),Windows_NT)
-	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --dev
+	@call scripts\run-with-git-bash.cmd ./scripts/serve.sh --dev
-
+else
-# Start all services in dev + Gateway mode (experimental: agent runtime embedded in Gateway)
+	@./scripts/serve.sh --dev
-dev-pro:
+endif
 	@$(PYTHON) ./scripts/check.py
 	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --dev --gateway
 # Start all services in production mode (with optimizations)
 start:
-	@$(PYTHON) ./scripts/check.py
+ifeq ($(OS),Windows_NT)
-	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --prod
+	@call scripts\run-with-git-bash.cmd ./scripts/serve.sh --prod
-
+else
-# Start all services in prod + Gateway mode (experimental)
+	@./scripts/serve.sh --prod
-start-pro:
+endif
 	@$(PYTHON) ./scripts/check.py
 	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --prod --gateway
 # Start all services in daemon mode (background)
 dev-daemon:
-	@$(PYTHON) ./scripts/check.py
+	@./scripts/start-daemon.sh
 	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --dev --daemon
 # Start daemon + Gateway mode (experimental)
 dev-daemon-pro:
 	@$(PYTHON) ./scripts/check.py
 	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --dev --gateway --daemon
 # Start prod services in daemon mode (background)
 start-daemon:
 	@$(PYTHON) ./scripts/check.py
 	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --prod --daemon
 # Start prod daemon + Gateway mode (experimental)
 start-daemon-pro:
 	@$(PYTHON) ./scripts/check.py
 	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --prod --gateway --daemon
 # Stop all services
 stop:
-	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --stop
+	@echo "Stopping all services..."
 	@-pkill -f "langgraph dev" 2>/dev/null || true
 	@-pkill -f "uvicorn app.gateway.app:app" 2>/dev/null || true
 	@-pkill -f "next dev" 2>/dev/null || true
 	@-pkill -f "next start" 2>/dev/null || true
 	@-pkill -f "next-server" 2>/dev/null || true
 	@-pkill -f "next-server" 2>/dev/null || true
 	@-nginx -c $(PWD)/docker/nginx/nginx.local.conf -p $(PWD) -s quit 2>/dev/null || true
 	@sleep 1
 	@-pkill -9 nginx 2>/dev/null || true
 	@echo "Cleaning up sandbox containers..."
 	@-./scripts/cleanup-containers.sh deer-flow-sandbox 2>/dev/null || true
 	@echo "✓ All services stopped"
 # Clean up
 clean: stop
@@ -176,29 +144,25 @@ clean: stop
 # Initialize Docker containers and install dependencies
 docker-init:
-	@$(RUN_WITH_GIT_BASH) ./scripts/docker.sh init
+	@./scripts/docker.sh init
 # Start Docker development environment
 docker-start:
-	@$(RUN_WITH_GIT_BASH) ./scripts/docker.sh start
+	@./scripts/docker.sh start
 # Start Docker in Gateway mode (experimental)
 docker-start-pro:
 	@$(RUN_WITH_GIT_BASH) ./scripts/docker.sh start --gateway
 # Stop Docker development environment
 docker-stop:
-	@$(RUN_WITH_GIT_BASH) ./scripts/docker.sh stop
+	@./scripts/docker.sh stop
 # View Docker development logs
 docker-logs:
-	@$(RUN_WITH_GIT_BASH) ./scripts/docker.sh logs
+	@./scripts/docker.sh logs
 # View Docker development logs
 docker-logs-frontend:
-	@$(RUN_WITH_GIT_BASH) ./scripts/docker.sh logs --frontend
+	@./scripts/docker.sh logs --frontend
 docker-logs-gateway:
-	@$(RUN_WITH_GIT_BASH) ./scripts/docker.sh logs --gateway
+	@./scripts/docker.sh logs --gateway
 # ==========================================
 # Production Docker Commands
@@ -206,12 +170,8 @@ docker-logs-gateway:
 # Build and start production services
 up:
-	@$(RUN_WITH_GIT_BASH) ./scripts/deploy.sh
+	@./scripts/deploy.sh
 # Build and start production services in Gateway mode
 up-pro:
 	@$(RUN_WITH_GIT_BASH) ./scripts/deploy.sh --gateway
 # Stop and remove production containers
 down:
-	@$(RUN_WITH_GIT_BASH) ./scripts/deploy.sh down
+	@./scripts/deploy.sh down
@@ -46,14 +46,12 @@ DeerFlow has newly integrated the intelligent search and crawling toolset indepe
 - [🦌 DeerFlow - 2.0](#-deerflow---20)
  - [Official Website](#official-website)
  - [Coding Plan from ByteDance Volcengine](#coding-plan-from-bytedance-volcengine)
  - [InfoQuest](#infoquest)
  - [Table of Contents](#table-of-contents)
  - [One-Line Agent Setup](#one-line-agent-setup)
  - [Quick Start](#quick-start)
    - [Configuration](#configuration)
    - [Running the Application](#running-the-application)
      - [Deployment Sizing](#deployment-sizing)
      - [Option 1: Docker (Recommended)](#option-1-docker-recommended)
      - [Option 2: Local Development](#option-2-local-development)
    - [Advanced](#advanced)
@@ -61,8 +59,6 @@ DeerFlow has newly integrated the intelligent search and crawling toolset indepe
      - [MCP Server](#mcp-server)
      - [IM Channels](#im-channels)
      - [LangSmith Tracing](#langsmith-tracing)
      - [Langfuse Tracing](#langfuse-tracing)
      - [Using Both Providers](#using-both-providers)
  - [From Deep Research to Super Agent Harness](#from-deep-research-to-super-agent-harness)
  - [Core Features](#core-features)
    - [Skills \& Tools](#skills--tools)
@@ -75,8 +71,6 @@ DeerFlow has newly integrated the intelligent search and crawling toolset indepe
  - [Embedded Python Client](#embedded-python-client)
  - [Documentation](#documentation)
  - [⚠️ Security Notice](#️-security-notice)
    - [Improper Deployment May Introduce Security Risks](#improper-deployment-may-introduce-security-risks)
    - [Security Recommendations](#security-recommendations)
  - [Contributing](#contributing)
  - [License](#license)
  - [Acknowledgments](#acknowledgments)
@@ -104,38 +98,35 @@ That prompt is intended for coding agents. It tells the agent to clone the repo
   cd deer-flow
   ```
-2. **Run the setup wizard**
+2. **Generate local configuration files**
   From the project root directory (`deer-flow/`), run:
   ```bash
-   make setup
+   make config
   ```
-   This launches an interactive wizard that guides you through choosing an LLM provider, optional web search, and execution/safety preferences such as sandbox mode, bash access, and file-write tools. It generates a minimal `config.yaml` and writes your keys to `.env`. Takes about 2 minutes.
+   This command creates local configuration files based on the provided example templates.
-   The wizard also lets you configure an optional web search provider, or skip it for now.
+3. **Configure your preferred model(s)**
-   Run `make doctor` at any time to verify your setup and get actionable fix hints.
+   Edit `config.yaml` and define at least one model:
   > **Advanced / manual configuration**: If you prefer to edit `config.yaml` directly, run `make config` instead to copy the full template. See `config.example.yaml` for the complete reference including CLI-backed providers (Codex CLI, Claude Code OAuth), OpenRouter, Responses API, and more.
   <details>
   <summary>Manual model configuration examples</summary>
   ```yaml
   models:
-     - name: gpt-4o
+     - name: gpt-4                       # Internal identifier
-       display_name: GPT-4o
+       display_name: GPT-4               # Human-readable name
-       use: langchain_openai:ChatOpenAI
+       use: langchain_openai:ChatOpenAI  # LangChain class path
-       model: gpt-4o
+       model: gpt-4                      # Model identifier for API
-       api_key: $OPENAI_API_KEY
+       api_key: $OPENAI_API_KEY          # API key (recommended: use env var)
       max_tokens: 4096                  # Maximum tokens per request
       temperature: 0.7                  # Sampling temperature
     - name: openrouter-gemini-2.5-flash
       display_name: Gemini 2.5 Flash (OpenRouter)
       use: langchain_openai:ChatOpenAI
       model: google/gemini-2.5-flash-preview
-       api_key: $OPENROUTER_API_KEY
+       api_key: $OPENAI_API_KEY          # OpenRouter still uses the OpenAI-compatible field name here
       base_url: https://openrouter.ai/api/v1
     - name: gpt-5-responses
@@ -145,26 +136,12 @@ That prompt is intended for coding agents. It tells the agent to clone the repo
       api_key: $OPENAI_API_KEY
       use_responses_api: true
       output_version: responses/v1
     - name: qwen3-32b-vllm
       display_name: Qwen3 32B (vLLM)
       use: deerflow.models.vllm_provider:VllmChatModel
       model: Qwen/Qwen3-32B
       api_key: $VLLM_API_KEY
       base_url: http://localhost:8000/v1
       supports_thinking: true
       when_thinking_enabled:
         extra_body:
           chat_template_kwargs:
             enable_thinking: true
   ```
   OpenRouter and similar OpenAI-compatible gateways should be configured with `langchain_openai:ChatOpenAI` plus `base_url`. If you prefer a provider-specific environment variable name, point `api_key` at that variable explicitly (for example `api_key: $OPENROUTER_API_KEY`).
   To route OpenAI models through `/v1/responses`, keep using `langchain_openai:ChatOpenAI` and set `use_responses_api: true` with `output_version: responses/v1`.
   For vLLM 0.19.0, use `deerflow.models.vllm_provider:VllmChatModel`. For Qwen-style reasoning models, DeerFlow toggles reasoning with `extra_body.chat_template_kwargs.enable_thinking` and preserves vLLM's non-standard `reasoning` field across multi-turn tool-call conversations. Legacy `thinking` configs are normalized automatically for backward compatibility. Reasoning models may also require the server to be started with `--reasoning-parser ...`. If your local vLLM deployment accepts any non-empty API key, you can still set `VLLM_API_KEY` to a placeholder value.
   CLI-backed provider examples:
   ```yaml
@@ -185,39 +162,50 @@ That prompt is intended for coding agents. It tells the agent to clone the repo
   ```
   - Codex CLI reads `~/.codex/auth.json`
-   - Claude Code accepts `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_CREDENTIALS_PATH`, or `~/.claude/.credentials.json`
+   - The Codex Responses endpoint currently rejects `max_tokens` and `max_output_tokens`, so `CodexChatModel` does not expose a request-level token cap
-   - ACP agent entries are separate from model providers — if you configure `acp_agents.codex`, point it at a Codex ACP adapter such as `npx -y @zed-industries/codex-acp`
+   - Claude Code accepts `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR`, `CLAUDE_CODE_CREDENTIALS_PATH`, or plaintext `~/.claude/.credentials.json`
-   - On macOS, export Claude Code auth explicitly if needed:
+   - ACP agent entries are separate from model providers. If you configure `acp_agents.codex`, point it at a Codex ACP adapter such as `npx -y @zed-industries/codex-acp`; the standard `codex` CLI binary is not ACP-compatible by itself
   - On macOS, DeerFlow does not probe Keychain automatically. Export Claude Code auth explicitly if needed:
   ```bash
   eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"
   ```
-   API keys can also be set manually in `.env` (recommended) or exported in your shell:
+4. **Set API keys for your configured model(s)**
   Choose one of the following methods:
 - Option A: Edit the `.env` file in the project root (Recommended)
   ```bash
   OPENAI_API_KEY=your-openai-api-key
   TAVILY_API_KEY=your-tavily-api-key
   OPENAI_API_KEY=your-openai-api-key
   # OpenRouter also uses OPENAI_API_KEY when your config uses langchain_openai:ChatOpenAI + base_url.
   # Add other provider keys as needed
   INFOQUEST_API_KEY=your-infoquest-api-key
   ```
-   </details>
+- Option B: Export environment variables in your shell
   ```bash
   export OPENAI_API_KEY=your-openai-api-key
   ```
   For CLI-backed providers:
   - Codex CLI: `~/.codex/auth.json`
   - Claude Code OAuth: explicit env/file handoff or `~/.claude/.credentials.json`
 - Option C: Edit `config.yaml` directly (Not recommended for production)
   ```yaml
   models:
     - name: gpt-4
       api_key: your-actual-api-key-here  # Replace placeholder
   ```
 ### Running the Application
 #### Deployment Sizing
 Use the table below as a practical starting point when choosing how to run DeerFlow:
 | Deployment target | Starting point | Recommended | Notes |
 |---------|-----------|------------|-------|
 | Local evaluation / `make dev` | 4 vCPU, 8 GB RAM, 20 GB free SSD | 8 vCPU, 16 GB RAM | Good for one developer or one light session with hosted model APIs. `2 vCPU / 4 GB` is usually not enough. |
 | Docker development / `make docker-start` | 4 vCPU, 8 GB RAM, 25 GB free SSD | 8 vCPU, 16 GB RAM | Image builds, bind mounts, and sandbox containers need more headroom than pure local dev. |
 | Long-running server / `make up` | 8 vCPU, 16 GB RAM, 40 GB free SSD | 16 vCPU, 32 GB RAM | Preferred for shared use, multi-agent runs, report generation, or heavier sandbox workloads. |
 - These numbers cover DeerFlow itself. If you also host a local LLM, size that service separately.
 - Linux plus Docker is the recommended deployment target for a persistent server. macOS and Windows are best treated as development or evaluation environments.
 - If CPU or memory usage stays pinned, reduce concurrent runs first, then move to the next sizing tier.
 #### Option 1: Docker (Recommended)
 **Development** (hot-reload, source mounts):
@@ -254,8 +242,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed Docker development guide.
 If you prefer running services locally:
-Prerequisite: complete the "Configuration" steps above first (`make setup`). `make dev` requires a valid `config.yaml` in the project root (can be overridden via `DEER_FLOW_CONFIG_PATH`). Run `make doctor` to verify your setup before starting.
+Prerequisite: complete the "Configuration" steps above first (`make config` and model API keys). `make dev` requires a valid configuration file (defaults to `config.yaml` in the project root; can be overridden via `DEER_FLOW_CONFIG_PATH`).
 On Windows, run the local development flow from Git Bash. Native `cmd.exe` and PowerShell shells are not supported for the bash-based service scripts, and WSL is not guaranteed because some scripts rely on Git for Windows utilities such as `cygpath`.
 1. **Check prerequisites**:
   ```bash
@@ -264,7 +251,7 @@ On Windows, run the local development flow from Git Bash. Native `cmd.exe` and P
 2. **Install dependencies**:
   ```bash
-   make install  # Install backend + frontend dependencies + pre-commit hooks
+   make install  # Install backend + frontend dependencies
   ```
 3. **(Optional) Pre-pull sandbox image**:
@@ -287,60 +274,6 @@ On Windows, run the local development flow from Git Bash. Native `cmd.exe` and P
 6. **Access**: http://localhost:2026
 #### Startup Modes
 DeerFlow supports multiple startup modes across two dimensions:
 - **Dev / Prod** — dev enables hot-reload; prod uses pre-built frontend
 - **Standard / Gateway** — standard uses a separate LangGraph server (4 processes); Gateway mode (experimental) embeds the agent runtime in the Gateway API (3 processes)
 | | **Local Foreground** | **Local Daemon** | **Docker Dev** | **Docker Prod** |
 |---|---|---|---|---|
 | **Dev** | `./scripts/serve.sh --dev`<br/>`make dev` | `./scripts/serve.sh --dev --daemon`<br/>`make dev-daemon` | `./scripts/docker.sh start`<br/>`make docker-start` | — |
 | **Dev + Gateway** | `./scripts/serve.sh --dev --gateway`<br/>`make dev-pro` | `./scripts/serve.sh --dev --gateway --daemon`<br/>`make dev-daemon-pro` | `./scripts/docker.sh start --gateway`<br/>`make docker-start-pro` | — |
 | **Prod** | `./scripts/serve.sh --prod`<br/>`make start` | `./scripts/serve.sh --prod --daemon`<br/>`make start-daemon` | — | `./scripts/deploy.sh`<br/>`make up` |
 | **Prod + Gateway** | `./scripts/serve.sh --prod --gateway`<br/>`make start-pro` | `./scripts/serve.sh --prod --gateway --daemon`<br/>`make start-daemon-pro` | — | `./scripts/deploy.sh --gateway`<br/>`make up-pro` |
 | Action | Local | Docker Dev | Docker Prod |
 |---|---|---|---|
 | **Stop** | `./scripts/serve.sh --stop`<br/>`make stop` | `./scripts/docker.sh stop`<br/>`make docker-stop` | `./scripts/deploy.sh down`<br/>`make down` |
 | **Restart** | `./scripts/serve.sh --restart [flags]` | `./scripts/docker.sh restart` | — |
 > **Gateway mode** eliminates the LangGraph server process — the Gateway API handles agent execution directly via async tasks, managing its own concurrency.
 #### Why Gateway Mode?
 In standard mode, DeerFlow runs a dedicated [LangGraph Platform](https://langchain-ai.github.io/langgraph/) server alongside the Gateway API. This architecture works well but has trade-offs:
 | | Standard Mode | Gateway Mode |
 |---|---|---|
 | **Architecture** | Gateway (REST API) + LangGraph (agent runtime) | Gateway embeds agent runtime |
 | **Concurrency** | `--n-jobs-per-worker` per worker (requires license) | `--workers` × async tasks (no per-worker cap) |
 | **Containers / Processes** | 4 (frontend, gateway, langgraph, nginx) | 3 (frontend, gateway, nginx) |
 | **Resource usage** | Higher (two Python runtimes) | Lower (single Python runtime) |
 | **LangGraph Platform license** | Required for production images | Not required |
 | **Cold start** | Slower (two services to initialize) | Faster |
 Both modes are functionally equivalent — the same agents, tools, and skills work in either mode.
 #### Docker Production Deployment
 `deploy.sh` supports building and starting separately. Images are mode-agnostic — runtime mode is selected at start time:
 ```bash
 # One-step (build + start)
 deploy.sh                    # standard mode (default)
 deploy.sh --gateway          # gateway mode
 # Two-step (build once, start with any mode)
 deploy.sh build              # build all images
 deploy.sh start              # start in standard mode
 deploy.sh start --gateway    # start in gateway mode
 # Stop
 deploy.sh down
 ```
 ### Advanced
 #### Sandbox Mode
@@ -368,8 +301,6 @@ DeerFlow supports receiving tasks from messaging apps. Channels auto-start when
 | Telegram | Bot API (long-polling) | Easy |
 | Slack | Socket Mode | Moderate |
 | Feishu / Lark | WebSocket | Moderate |
 | WeChat | Tencent iLink (long-polling) | Moderate |
 | WeCom | WebSocket | Moderate |
 **Configuration in `config.yaml`:**
@@ -397,11 +328,6 @@ channels:
    # domain: https://open.feishu.cn       # China (default)
    # domain: https://open.larksuite.com   # International
  wecom:
    enabled: true
    bot_id: $WECOM_BOT_ID
    bot_secret: $WECOM_BOT_SECRET
  slack:
    enabled: true
    bot_token: $SLACK_BOT_TOKEN     # xoxb-...
@@ -413,19 +339,6 @@ channels:
    bot_token: $TELEGRAM_BOT_TOKEN
    allowed_users: []               # empty = allow all
  wechat:
    enabled: false
    bot_token: $WECHAT_BOT_TOKEN
    ilink_bot_id: $WECHAT_ILINK_BOT_ID
    qrcode_login_enabled: true      # optional: allow first-time QR bootstrap when bot_token is absent
    allowed_users: []               # empty = allow all
    polling_timeout: 35
    state_dir: ./.deer-flow/wechat/state
    max_inbound_image_bytes: 20971520
    max_outbound_image_bytes: 20971520
    max_inbound_file_bytes: 52428800
    max_outbound_file_bytes: 52428800
    # Optional: per-channel / per-user session settings
    session:
      assistant_id: mobile-agent  # custom agent names are also supported here
@@ -458,14 +371,6 @@ SLACK_APP_TOKEN=xapp-...
 # Feishu / Lark
 FEISHU_APP_ID=cli_xxxx
 FEISHU_APP_SECRET=your_app_secret
 # WeChat iLink
 WECHAT_BOT_TOKEN=your_ilink_bot_token
 WECHAT_ILINK_BOT_ID=your_ilink_bot_id
 # WeCom
 WECOM_BOT_ID=your_bot_id
 WECOM_BOT_SECRET=your_bot_secret
 ```
 **Telegram Setup**
@@ -488,22 +393,6 @@ WECOM_BOT_SECRET=your_bot_secret
 3. Under **Events**, subscribe to `im.message.receive_v1` and select **Long Connection** mode.
 4. Copy the App ID and App Secret. Set `FEISHU_APP_ID` and `FEISHU_APP_SECRET` in `.env` and enable the channel in `config.yaml`.
 **WeChat Setup**
 1. Enable the `wechat` channel in `config.yaml`.
 2. Either set `WECHAT_BOT_TOKEN` in `.env`, or set `qrcode_login_enabled: true` for first-time QR bootstrap.
 3. When `bot_token` is absent and QR bootstrap is enabled, watch backend logs for the QR content returned by iLink and complete the binding flow.
 4. After the QR flow succeeds, DeerFlow persists the acquired token under `state_dir` for later restarts.
 5. For Docker Compose deployments, keep `state_dir` on a persistent volume so the `get_updates_buf` cursor and saved auth state survive restarts.
 **WeCom Setup**
 1. Create a bot on the WeCom AI Bot platform and obtain the `bot_id` and `bot_secret`.
 2. Enable `channels.wecom` in `config.yaml` and fill in `bot_id` / `bot_secret`.
 3. Set `WECOM_BOT_ID` and `WECOM_BOT_SECRET` in `.env`.
 4. Make sure backend dependencies include `wecom-aibot-python-sdk`. The channel uses a WebSocket long connection and does not require a public callback URL.
 5. The current integration supports inbound text, image, and file messages. Final images/files generated by the agent are also sent back to the WeCom conversation.
 When DeerFlow runs in Docker Compose, IM channels execute inside the `gateway` container. In that case, do not point `channels.langgraph_url` or `channels.gateway_url` at `localhost`; use container service names such as `http://langgraph:2024` and `http://gateway:8001`, or set `DEER_FLOW_CHANNELS_LANGGRAPH_URL` and `DEER_FLOW_CHANNELS_GATEWAY_URL`.
 **Commands**
@@ -533,27 +422,6 @@ LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
 LANGSMITH_PROJECT=xxx
 ```
 #### Langfuse Tracing
 DeerFlow also supports [Langfuse](https://langfuse.com) observability for LangChain-compatible runs.
 Add the following to your `.env` file:
 ```bash
 LANGFUSE_TRACING=true
 LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxx
 LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxx
 LANGFUSE_BASE_URL=https://cloud.langfuse.com
 ```
 If you are using a self-hosted Langfuse instance, set `LANGFUSE_BASE_URL` to your deployment URL.
 #### Using Both Providers
 If both LangSmith and Langfuse are enabled, DeerFlow attaches both tracing callbacks and reports the same model activity to both systems.
 If a provider is explicitly enabled but missing required credentials, or if its callback fails to initialize, DeerFlow fails fast when tracing is initialized during model creation and the error message names the provider that caused the failure.
 For Docker deployments, tracing is disabled by default. Set `LANGSMITH_TRACING=true` and `LANGSMITH_API_KEY` in your `.env` to enable it.
 ## From Deep Research to Super Agent Harness
@@ -658,8 +526,6 @@ 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.
@@ -40,7 +40,6 @@ https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18
  - [快速开始](#快速开始)
    - [配置](#配置)
    - [运行应用](#运行应用)
      - [部署建议与资源规划](#部署建议与资源规划)
      - [方式一：Docker（推荐）](#方式一docker推荐)
      - [方式二：本地开发](#方式二本地开发)
    - [进阶配置](#进阶配置)
@@ -151,20 +150,6 @@ https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18
 ### 运行应用
 #### 部署建议与资源规划
 可以先按下面的资源档位来选择 DeerFlow 的运行方式：
 | 部署场景 | 起步配置 | 推荐配置 | 说明 |
 |---------|-----------|------------|-------|
 | 本地体验 / `make dev` | 4 vCPU、8 GB 内存、20 GB SSD 可用空间 | 8 vCPU、16 GB 内存 | 适合单个开发者或单个轻量会话，且模型走外部 API。`2 核 / 4 GB` 通常跑不稳。 |
 | Docker 开发 / `make docker-start` | 4 vCPU、8 GB 内存、25 GB SSD 可用空间 | 8 vCPU、16 GB 内存 | 镜像构建、源码挂载和 sandbox 容器都会比纯本地模式更吃资源。 |
 | 长期运行服务 / `make up` | 8 vCPU、16 GB 内存、40 GB SSD 可用空间 | 16 vCPU、32 GB 内存 | 更适合共享环境、多 agent 任务、报告生成或更重的 sandbox 负载。 |
 - 上面的配置只覆盖 DeerFlow 本身；如果你还要本机部署本地大模型，请单独为模型服务预留资源。
 - 持续运行的服务更推荐使用 Linux + Docker。macOS 和 Windows 更适合作为开发机或体验环境。
 - 如果 CPU 或内存长期打满，先降低并发会话或重任务数量，再考虑升级到更高一档配置。
 #### 方式一：Docker（推荐）
 **开发模式**（支持热更新，挂载源码）：
@@ -195,7 +180,6 @@ make down   # 停止并移除容器
 如果你更希望直接在本地启动各个服务：
 前提：先完成上面的“配置”步骤（`make config` 和模型 API key 配置）。`make dev` 需要有效配置文件，默认读取项目根目录下的 `config.yaml`，也可以通过 `DEER_FLOW_CONFIG_PATH` 覆盖。
 在 Windows 上，请使用 Git Bash 运行本地开发流程。基于 bash 的服务脚本不支持直接在原生 `cmd.exe` 或 PowerShell 中执行，且 WSL 也不保证可用，因为部分脚本依赖 Git for Windows 的 `cygpath` 等工具。
 1. **检查依赖环境**：
   ```bash
@@ -247,7 +231,6 @@ DeerFlow 支持从即时通讯应用接收任务。只要配置完成，对应
 | Telegram | Bot API（long-polling） | 简单 |
 | Slack | Socket Mode | 中等 |
 | Feishu / Lark | WebSocket | 中等 |
 | 企业微信智能机器人 | WebSocket | 中等 |
 **`config.yaml` 中的配置示例：**
@@ -275,11 +258,6 @@ channels:
    # domain: https://open.feishu.cn       # 国内版（默认）
    # domain: https://open.larksuite.com   # 国际版
  wecom:
    enabled: true
    bot_id: $WECOM_BOT_ID
    bot_secret: $WECOM_BOT_SECRET
  slack:
    enabled: true
    bot_token: $SLACK_BOT_TOKEN     # xoxb-...
@@ -323,10 +301,6 @@ SLACK_APP_TOKEN=xapp-...
 # Feishu / Lark
 FEISHU_APP_ID=cli_xxxx
 FEISHU_APP_SECRET=your_app_secret
 # 企业微信智能机器人
 WECOM_BOT_ID=your_bot_id
 WECOM_BOT_SECRET=your_bot_secret
 ```
 **Telegram 配置**
@@ -349,14 +323,6 @@ WECOM_BOT_SECRET=your_bot_secret
 3. 在 **事件订阅** 中订阅 `im.message.receive_v1`，连接方式选择 **长连接**。
 4. 复制 App ID 和 App Secret，在 `.env` 中设置 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET`，并在 `config.yaml` 中启用该渠道。
 **企业微信智能机器人配置**
 1. 在企业微信智能机器人平台创建机器人，获取 `bot_id` 和 `bot_secret`。
 2. 在 `config.yaml` 中启用 `channels.wecom`，并填入 `bot_id` / `bot_secret`。
 3. 在 `.env` 中设置 `WECOM_BOT_ID` 和 `WECOM_BOT_SECRET`。
 4. 安装后端依赖时确保包含 `wecom-aibot-python-sdk`，渠道会通过 WebSocket 长连接接收消息，无需公网回调地址。
 5. 当前支持文本、图片和文件入站消息；agent 生成的最终图片/文件也会回传到企业微信会话中。
 **命令**
 渠道连接完成后，你可以直接在聊天窗口里和 DeerFlow 交互：
@@ -13,10 +13,6 @@ DeerFlow is a LangGraph-based AI super agent system with a full-stack architectu
 - **Nginx** (port 2026): Unified reverse proxy entry point
 - **Provisioner** (port 8002, optional in Docker dev): Started only when sandbox is configured for provisioner/Kubernetes mode
 **Runtime Modes**:
 - **Standard mode** (`make dev`): LangGraph Server handles agent execution as a separate process. 4 processes total.
 - **Gateway mode** (`make dev-pro`, experimental): Agent runtime embedded in Gateway via `RunManager` + `run_agent()` + `StreamBridge` (`packages/harness/deerflow/runtime/`). Service manages its own concurrency via async tasks. 3 processes total, no LangGraph Server.
 **Project Structure**:
 ```
 deer-flow/
@@ -84,8 +80,6 @@ When making code changes, you MUST update the relevant documentation:
 make check      # Check system requirements
 make install    # Install all dependencies (frontend + backend)
 make dev        # Start all services (LangGraph + Gateway + Frontend + Nginx), with config.yaml preflight
 make dev-pro    # Gateway mode (experimental): skip LangGraph, agent runtime embedded in Gateway
 make start-pro  # Production + Gateway mode (experimental)
 make stop       # Stop all services
 ```
@@ -156,26 +150,20 @@ from deerflow.config import get_app_config
 ### Middleware Chain
-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`):
+Middlewares execute in strict order in `packages/harness/deerflow/agents/lead_agent/agent.py`:
 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), including raw provider tool-call payloads preserved only in `additional_kwargs["tool_calls"]`
+4. **DanglingToolCallMiddleware** - Injects placeholder ToolMessages for AIMessage tool_calls that lack responses (e.g., due to user interruption)
-5. **LLMErrorHandlingMiddleware** - Normalizes provider/model invocation failures into recoverable assistant-facing errors before later middleware/tool stages run
+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. **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. **SandboxAuditMiddleware** - Audits sandboxed shell/file operations for security logging before tool execution continues
+7. **TodoListMiddleware** - Task tracking with `write_todos` tool (optional, if plan_mode)
-8. **ToolErrorHandlingMiddleware** - Converts tool exceptions into error `ToolMessage`s so the run can continue instead of aborting
+8. **TitleMiddleware** - Auto-generates thread title after first complete exchange and normalizes structured message content before prompting the title model
-9. **SummarizationMiddleware** - Context reduction when approaching token limits (optional, if enabled)
+9. **MemoryMiddleware** - Queues conversations for async memory update (filters to user + final AI responses)
-10. **TodoListMiddleware** - Task tracking with `write_todos` tool (optional, if plan_mode)
+10. **ViewImageMiddleware** - Injects base64 image data before LLM call (conditional on vision support)
-11. **TokenUsageMiddleware** - Records token usage metrics when token tracking is enabled (optional)
+11. **SubagentLimitMiddleware** - Truncates excess `task` tool calls from model response to enforce `MAX_CONCURRENT_SUBAGENTS` limit (optional, if subagent_enabled)
-12. **TitleMiddleware** - Auto-generates thread title after first complete exchange and normalizes structured message content before prompting the title model
+12. **ClarificationMiddleware** - Intercepts `ask_clarification` tool calls, interrupts via `Command(goto=END)` (must be last)
 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
@@ -244,7 +232,7 @@ Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` →
 - `ls` - Directory listing (tree format, max 2 levels)
 - `read_file` - Read file contents with optional line range
 - `write_file` - Write/append to files, creates directories
- `str_replace` - Substring replacement (single or all occurrences); same-path serialization is scoped to `(sandbox.id, path)` so isolated sandboxes do not contend on identical virtual paths inside one process
+- `str_replace` - Substring replacement (single or all occurrences)
 ### Subagent System (`packages/harness/deerflow/subagents/`)
@@ -299,17 +287,10 @@ Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` →
 - `create_chat_model(name, thinking_enabled)` instantiates LLM from config via reflection
 - Supports `thinking_enabled` flag with per-model `when_thinking_enabled` overrides
 - Supports vLLM-style thinking toggles via `when_thinking_enabled.extra_body.chat_template_kwargs.enable_thinking` for Qwen reasoning models, while normalizing legacy `thinking` configs for backward compatibility
 - Supports `supports_vision` flag for image understanding models
 - Config values starting with `$` resolved as environment variables
 - Missing provider modules surface actionable install hints from reflection resolvers (for example `uv add langchain-google-genai`)
 ### vLLM Provider (`packages/harness/deerflow/models/vllm_provider.py`)
 - `VllmChatModel` subclasses `langchain_openai:ChatOpenAI` for vLLM 0.19.0 OpenAI-compatible endpoints
 - Preserves vLLM's non-standard assistant `reasoning` field on full responses, streaming deltas, and follow-up tool-call turns
 - Designed for configs that enable thinking through `extra_body.chat_template_kwargs.enable_thinking` on vLLM 0.19.0 Qwen reasoning models, while accepting the older `thinking` alias
 ### IM Channels System (`app/channels/`)
 Bridges external messaging platforms (Feishu, Slack, Telegram) to the DeerFlow agent via the LangGraph Server.
@@ -378,7 +359,6 @@ Focused regression coverage for the updater lives in `backend/tests/test_memory_
 **`config.yaml`** key sections:
 - `models[]` - LLM configs with `use` class path, `supports_thinking`, `supports_vision`, provider-specific fields
 - vLLM reasoning models should use `deerflow.models.vllm_provider:VllmChatModel`; for Qwen-style parsers prefer `when_thinking_enabled.extra_body.chat_template_kwargs.enable_thinking`, and DeerFlow will also normalize the older `thinking` alias
 - `tools[]` - Tool configs with `use` variable path and `group`
 - `tool_groups[]` - Logical groupings for tools
 - `sandbox.use` - Sandbox provider class path
@@ -401,16 +381,14 @@ Both can be modified at runtime via Gateway API endpoints or `DeerFlowClient` me
 **Architecture**: Imports the same `deerflow` modules that LangGraph Server and Gateway API use. Shares the same config files and data directories. No FastAPI dependency.
 **Agent Conversation** (replaces LangGraph Server):
- `chat(message, thread_id)` — synchronous, accumulates streaming deltas per message-id and returns the final AI text
+- `chat(message, thread_id)` — synchronous, returns final text
- `stream(message, thread_id)` — subscribes to LangGraph `stream_mode=["values", "messages", "custom"]` and yields `StreamEvent`:
+- `stream(message, thread_id)` — yields `StreamEvent` aligned with LangGraph SSE protocol:
-  - `"values"` — full state snapshot (title, messages, artifacts); AI text already delivered via `messages` mode is **not** re-synthesized here to avoid duplicate deliveries
+  - `"values"` — full state snapshot (title, messages, artifacts)
-  - `"messages-tuple"` — per-chunk update: for AI text this is a **delta** (concat per `id` to rebuild the full message); tool calls and tool results are emitted once each
+  - `"messages-tuple"` — per-message update (AI text, tool calls, tool results)
-  - `"custom"` — forwarded from `StreamWriter`
+  - `"end"` — stream finished
  - `"end"` — stream finished (carries cumulative `usage` counted once per message id)
 - Agent created lazily via `create_agent()` + `_build_middlewares()`, same as `make_lead_agent`
 - Supports `checkpointer` parameter for state persistence across turns
 - `reset_agent()` forces agent recreation (e.g. after memory or skill changes)
 - See [docs/STREAMING.md](docs/STREAMING.md) for the full design: why Gateway and DeerFlowClient are parallel paths, LangGraph's `stream_mode` semantics, the per-id dedup invariants, and regression testing strategy
 **Gateway Equivalent Methods** (replaces Gateway API):
@@ -458,25 +436,8 @@ make dev
 This starts all services and makes the application available at `http://localhost:2026`.
 **All startup modes:**
 | | **Local Foreground** | **Local Daemon** | **Docker Dev** | **Docker Prod** |
 |---|---|---|---|---|
 | **Dev** | `./scripts/serve.sh --dev`<br/>`make dev` | `./scripts/serve.sh --dev --daemon`<br/>`make dev-daemon` | `./scripts/docker.sh start`<br/>`make docker-start` | — |
 | **Dev + Gateway** | `./scripts/serve.sh --dev --gateway`<br/>`make dev-pro` | `./scripts/serve.sh --dev --gateway --daemon`<br/>`make dev-daemon-pro` | `./scripts/docker.sh start --gateway`<br/>`make docker-start-pro` | — |
 | **Prod** | `./scripts/serve.sh --prod`<br/>`make start` | `./scripts/serve.sh --prod --daemon`<br/>`make start-daemon` | — | `./scripts/deploy.sh`<br/>`make up` |
 | **Prod + Gateway** | `./scripts/serve.sh --prod --gateway`<br/>`make start-pro` | `./scripts/serve.sh --prod --gateway --daemon`<br/>`make start-daemon-pro` | — | `./scripts/deploy.sh --gateway`<br/>`make up-pro` |
 | Action | Local | Docker Dev | Docker Prod |
 |---|---|---|---|
 | **Stop** | `./scripts/serve.sh --stop`<br/>`make stop` | `./scripts/docker.sh stop`<br/>`make docker-stop` | `./scripts/deploy.sh down`<br/>`make down` |
 | **Restart** | `./scripts/serve.sh --restart [flags]` | `./scripts/docker.sh restart` | — |
 Gateway mode embeds the agent runtime in Gateway, no LangGraph server.
 **Nginx routing**:
- Standard mode: `/api/langgraph/*` → LangGraph Server (2024)
+- `/api/langgraph/*` → LangGraph Server (2024)
 - Gateway mode: `/api/langgraph/*` → Gateway embedded runtime (8001) (via envsubst)
 - `/api/*` (other) → Gateway API (8001)
 - `/` (non-API) → Frontend (3000)
@@ -1,14 +1,10 @@
-# Backend Dockerfile — multi-stage build
+# Backend Development Dockerfile
 # Stage 1 (builder): compiles native Python extensions with build-essential
 # Stage 2 (dev):     retains toolchain for dev containers (uv sync at startup)
 # Stage 3 (runtime): clean image without compiler toolchain for production
 # UV source image (override for restricted networks that cannot reach ghcr.io)
 ARG UV_IMAGE=ghcr.io/astral-sh/uv:0.7.20
 FROM ${UV_IMAGE} AS uv-source
-# ── Stage 1: Builder ──────────────────────────────────────────────────────────
+FROM python:3.12-slim-bookworm
 FROM python:3.12-slim-bookworm AS builder
 ARG NODE_MAJOR=22
 ARG APT_MIRROR
@@ -20,7 +16,7 @@ RUN if [ -n "${APT_MIRROR}" ]; then \
      sed -i "s|deb.debian.org|${APT_MIRROR}|g" /etc/apt/sources.list 2>/dev/null || true; \
    fi
-# Install build tools + Node.js (build-essential needed for native Python extensions)
+# Install system dependencies + Node.js (provides npx for MCP servers)
 RUN apt-get update && apt-get install -y \
    curl \
    build-essential \
@@ -33,55 +29,24 @@ RUN apt-get update && apt-get install -y \
    && apt-get install -y nodejs \
    && rm -rf /var/lib/apt/lists/*
 # Install Docker CLI (for DooD: allows starting sandbox containers via host Docker socket)
 COPY --from=docker:cli /usr/local/bin/docker /usr/local/bin/docker
 # Install uv (source image overridable via UV_IMAGE build arg)
 COPY --from=uv-source /uv /uvx /usr/local/bin/
 # Set working directory
 WORKDIR /app
-# Copy backend source code
+# Copy frontend source code
 COPY backend ./backend
 # Install dependencies with cache mount
 RUN --mount=type=cache,target=/root/.cache/uv \
    sh -c "cd backend && UV_INDEX_URL=${UV_INDEX_URL:-https://pypi.org/simple} uv sync"
 # ── Stage 2: Dev ──────────────────────────────────────────────────────────────
 # Retains compiler toolchain from builder so startup-time `uv sync` can build
 # source distributions in development containers.
 FROM builder AS dev
 # Install Docker CLI (for DooD: allows starting sandbox containers via host Docker socket)
 COPY --from=docker:cli /usr/local/bin/docker /usr/local/bin/docker
 EXPOSE 8001 2024
 CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]
 # ── Stage 3: Runtime ──────────────────────────────────────────────────────────
 # Clean image without build-essential — reduces size (~200 MB) and attack surface.
 FROM python:3.12-slim-bookworm
 # Copy Node.js runtime from builder (provides npx for MCP servers)
 COPY --from=builder /usr/bin/node /usr/bin/node
 COPY --from=builder /usr/lib/node_modules /usr/lib/node_modules
 RUN ln -s ../lib/node_modules/npm/bin/npm-cli.js /usr/bin/npm \
    && ln -s ../lib/node_modules/npm/bin/npx-cli.js /usr/bin/npx
 # Install Docker CLI (for DooD: allows starting sandbox containers via host Docker socket)
 COPY --from=docker:cli /usr/local/bin/docker /usr/local/bin/docker
 # Install uv (source image overridable via UV_IMAGE build arg)
 COPY --from=uv-source /uv /uvx /usr/local/bin/
 # Set working directory
 WORKDIR /app
 # Copy backend with pre-built virtualenv from builder
 COPY --from=builder /app/backend ./backend
 # Expose ports (gateway: 8001, langgraph: 2024)
 EXPOSE 8001 2024
 # Default command (can be overridden in docker-compose)
-CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run --no-sync uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]
+CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]
@@ -2,7 +2,7 @@ install:
 	uv sync
 dev:
-	uv run langgraph dev --no-browser --no-reload --n-jobs-per-worker 10
+	uv run langgraph dev --no-browser --allow-blocking --no-reload
 gateway:
 	PYTHONPATH=. uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
@@ -78,7 +78,6 @@ Per-thread isolated execution with virtual path translation:
 - **Virtual paths**: `/mnt/user-data/{workspace,uploads,outputs}` → thread-specific physical directories
 - **Skills path**: `/mnt/skills` → `deer-flow/skills/` directory
 - **Skills loading**: Recursively discovers nested `SKILL.md` files under `skills/{public,custom}` and preserves nested container paths
 - **File-write safety**: `str_replace` serializes read-modify-write per `(sandbox.id, path)` so isolated sandboxes keep concurrency even when virtual paths match
 - **Tools**: `bash`, `ls`, `read_file`, `write_file`, `str_replace` (`bash` is disabled by default when using `LocalSandboxProvider`; use `AioSandboxProvider` for isolated shell access)
 ### Subagent System
@@ -331,28 +330,7 @@ LANGSMITH_PROJECT=xxx
 **Legacy variables:** The `LANGCHAIN_TRACING_V2`, `LANGCHAIN_API_KEY`, `LANGCHAIN_PROJECT`, and `LANGCHAIN_ENDPOINT` variables are also supported for backward compatibility. `LANGSMITH_*` variables take precedence when both are set.
-### Langfuse Tracing
+**Docker:** In `docker-compose.yaml`, tracing is disabled by default (`LANGSMITH_TRACING=false`). Set `LANGSMITH_TRACING=true` and provide `LANGSMITH_API_KEY` in your `.env` to enable it in containerized deployments.
 DeerFlow also supports [Langfuse](https://langfuse.com) observability for LangChain-compatible runs.
 Add the following to your `.env` file:
 ```bash
 LANGFUSE_TRACING=true
 LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxx
 LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxx
 LANGFUSE_BASE_URL=https://cloud.langfuse.com
 ```
 If you are using a self-hosted Langfuse deployment, set `LANGFUSE_BASE_URL` to your Langfuse host.
 ### Dual Provider Behavior
 If both LangSmith and Langfuse are enabled, DeerFlow initializes and attaches both callbacks so the same run data is reported to both systems.
 If a provider is explicitly enabled but required credentials are missing, or the provider callback cannot be initialized, DeerFlow raises an error when tracing is initialized during model creation instead of silently disabling tracing.
 **Docker:** In `docker-compose.yaml`, tracing is disabled by default (`LANGSMITH_TRACING=false`). Set `LANGSMITH_TRACING=true` and/or `LANGFUSE_TRACING=true` in your `.env`, together with the required credentials, to enable tracing in containerized deployments.
 ---
@@ -106,21 +106,3 @@ class Channel(ABC):
                        logger.warning("[%s] file upload skipped for %s", self.name, attachment.filename)
                except Exception:
                    logger.exception("[%s] failed to upload file %s", self.name, attachment.filename)
    async def receive_file(self, msg: InboundMessage, thread_id: str) -> InboundMessage:
        """
        Optionally process and materialize inbound file attachments for this channel.
        By default, this method does nothing and simply returns the original message.
        Subclasses (e.g. FeishuChannel) may override this to download files (images, documents, etc)
        referenced in msg.files, save them to the sandbox, and update msg.text to include
        the sandbox file paths for downstream model consumption.
        Args:
            msg: The inbound message, possibly containing file metadata in msg.files.
            thread_id: The resolved DeerFlow thread ID for sandbox path context.
        Returns:
            The (possibly modified) InboundMessage, with text and/or files updated as needed.
        """
        return msg
@@ -1,20 +0,0 @@
 """Shared command definitions used by all channel implementations.
 Keeping the authoritative command set in one place ensures that channel
 parsers (e.g. Feishu) and the ChannelManager dispatcher stay in sync
 automatically — adding or removing a command here is the single edit
 required.
 """
 from __future__ import annotations
 KNOWN_CHANNEL_COMMANDS: frozenset[str] = frozenset(
    {
        "/bootstrap",
        "/new",
        "/status",
        "/models",
        "/memory",
        "/help",
    }
 )
@@ -1,273 +0,0 @@
 """Discord channel integration using discord.py."""
 from __future__ import annotations
 import asyncio
 import logging
 import threading
 from typing import Any
 from app.channels.base import Channel
 from app.channels.message_bus import InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
 logger = logging.getLogger(__name__)
 _DISCORD_MAX_MESSAGE_LEN = 2000
 class DiscordChannel(Channel):
    """Discord bot channel.
    Configuration keys (in ``config.yaml`` under ``channels.discord``):
        - ``bot_token``: Discord Bot token.
        - ``allowed_guilds``: (optional) List of allowed Discord guild IDs. Empty = allow all.
    """
    def __init__(self, bus: MessageBus, config: dict[str, Any]) -> None:
        super().__init__(name="discord", bus=bus, config=config)
        self._bot_token = str(config.get("bot_token", "")).strip()
        self._allowed_guilds: set[int] = set()
        for guild_id in config.get("allowed_guilds", []):
            try:
                self._allowed_guilds.add(int(guild_id))
            except (TypeError, ValueError):
                continue
        self._client = None
        self._thread: threading.Thread | None = None
        self._discord_loop: asyncio.AbstractEventLoop | None = None
        self._main_loop: asyncio.AbstractEventLoop | None = None
        self._discord_module = None
    async def start(self) -> None:
        if self._running:
            return
        try:
            import discord
        except ImportError:
            logger.error("discord.py is not installed. Install it with: uv add discord.py")
            return
        if not self._bot_token:
            logger.error("Discord channel requires bot_token")
            return
        intents = discord.Intents.default()
        intents.messages = True
        intents.guilds = True
        intents.message_content = True
        client = discord.Client(
            intents=intents,
            allowed_mentions=discord.AllowedMentions.none(),
        )
        self._client = client
        self._discord_module = discord
        self._main_loop = asyncio.get_event_loop()
        @client.event
        async def on_message(message) -> None:
            await self._on_message(message)
        self._running = True
        self.bus.subscribe_outbound(self._on_outbound)
        self._thread = threading.Thread(target=self._run_client, daemon=True)
        self._thread.start()
        logger.info("Discord channel started")
    async def stop(self) -> None:
        self._running = False
        self.bus.unsubscribe_outbound(self._on_outbound)
        if self._client and self._discord_loop and self._discord_loop.is_running():
            close_future = asyncio.run_coroutine_threadsafe(self._client.close(), self._discord_loop)
            try:
                await asyncio.wait_for(asyncio.wrap_future(close_future), timeout=10)
            except TimeoutError:
                logger.warning("[Discord] client close timed out after 10s")
            except Exception:
                logger.exception("[Discord] error while closing client")
        if self._thread:
            self._thread.join(timeout=10)
            self._thread = None
        self._client = None
        self._discord_loop = None
        self._discord_module = None
        logger.info("Discord channel stopped")
    async def send(self, msg: OutboundMessage) -> None:
        target = await self._resolve_target(msg)
        if target is None:
            logger.error("[Discord] target not found for chat_id=%s thread_ts=%s", msg.chat_id, msg.thread_ts)
            return
        text = msg.text or ""
        for chunk in self._split_text(text):
            send_future = asyncio.run_coroutine_threadsafe(target.send(chunk), self._discord_loop)
            await asyncio.wrap_future(send_future)
    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
        target = await self._resolve_target(msg)
        if target is None:
            logger.error("[Discord] target not found for file upload chat_id=%s thread_ts=%s", msg.chat_id, msg.thread_ts)
            return False
        if self._discord_module is None:
            return False
        try:
            fp = open(str(attachment.actual_path), "rb")  # noqa: SIM115
            file = self._discord_module.File(fp, filename=attachment.filename)
            send_future = asyncio.run_coroutine_threadsafe(target.send(file=file), self._discord_loop)
            await asyncio.wrap_future(send_future)
            logger.info("[Discord] file uploaded: %s", attachment.filename)
            return True
        except Exception:
            logger.exception("[Discord] failed to upload file: %s", attachment.filename)
            return False
    async def _on_message(self, message) -> None:
        if not self._running or not self._client:
            return
        if message.author.bot:
            return
        if self._client.user and message.author.id == self._client.user.id:
            return
        guild = message.guild
        if self._allowed_guilds:
            if guild is None or guild.id not in self._allowed_guilds:
                return
        text = (message.content or "").strip()
        if not text:
            return
        if self._discord_module is None:
            return
        if isinstance(message.channel, self._discord_module.Thread):
            chat_id = str(message.channel.parent_id or message.channel.id)
            thread_id = str(message.channel.id)
        else:
            thread = await self._create_thread(message)
            if thread is None:
                return
            chat_id = str(message.channel.id)
            thread_id = str(thread.id)
        msg_type = InboundMessageType.COMMAND if text.startswith("/") else InboundMessageType.CHAT
        inbound = self._make_inbound(
            chat_id=chat_id,
            user_id=str(message.author.id),
            text=text,
            msg_type=msg_type,
            thread_ts=thread_id,
            metadata={
                "guild_id": str(guild.id) if guild else None,
                "channel_id": str(message.channel.id),
                "message_id": str(message.id),
            },
        )
        inbound.topic_id = thread_id
        if self._main_loop and self._main_loop.is_running():
            future = asyncio.run_coroutine_threadsafe(self.bus.publish_inbound(inbound), self._main_loop)
            future.add_done_callback(lambda f: logger.exception("[Discord] publish_inbound failed", exc_info=f.exception()) if f.exception() else None)
    def _run_client(self) -> None:
        self._discord_loop = asyncio.new_event_loop()
        asyncio.set_event_loop(self._discord_loop)
        try:
            self._discord_loop.run_until_complete(self._client.start(self._bot_token))
        except Exception:
            if self._running:
                logger.exception("Discord client error")
        finally:
            try:
                if self._client and not self._client.is_closed():
                    self._discord_loop.run_until_complete(self._client.close())
            except Exception:
                logger.exception("Error during Discord shutdown")
    async def _create_thread(self, message):
        try:
            thread_name = f"deerflow-{message.author.display_name}-{message.id}"[:100]
            return await message.create_thread(name=thread_name)
        except Exception:
            logger.exception("[Discord] failed to create thread for message=%s (threads may be disabled or missing permissions)", message.id)
            try:
                await message.channel.send("Could not create a thread for your message. Please check that threads are enabled in this channel.")
            except Exception:
                pass
            return None
    async def _resolve_target(self, msg: OutboundMessage):
        if not self._client or not self._discord_loop:
            return None
        target_ids: list[str] = []
        if msg.thread_ts:
            target_ids.append(msg.thread_ts)
        if msg.chat_id and msg.chat_id not in target_ids:
            target_ids.append(msg.chat_id)
        for raw_id in target_ids:
            target = await self._get_channel_or_thread(raw_id)
            if target is not None:
                return target
        return None
    async def _get_channel_or_thread(self, raw_id: str):
        if not self._client or not self._discord_loop:
            return None
        try:
            target_id = int(raw_id)
        except (TypeError, ValueError):
            return None
        get_future = asyncio.run_coroutine_threadsafe(self._fetch_channel(target_id), self._discord_loop)
        try:
            return await asyncio.wrap_future(get_future)
        except Exception:
            logger.exception("[Discord] failed to resolve target id=%s", raw_id)
            return None
    async def _fetch_channel(self, target_id: int):
        if not self._client:
            return None
        channel = self._client.get_channel(target_id)
        if channel is not None:
            return channel
        try:
            return await self._client.fetch_channel(target_id)
        except Exception:
            return None
    @staticmethod
    def _split_text(text: str) -> list[str]:
        if not text:
            return [""]
        chunks: list[str] = []
        remaining = text
        while len(remaining) > _DISCORD_MAX_MESSAGE_LEN:
            split_at = remaining.rfind("\n", 0, _DISCORD_MAX_MESSAGE_LEN)
            if split_at <= 0:
                split_at = _DISCORD_MAX_MESSAGE_LEN
            chunks.append(remaining[:split_at])
            remaining = remaining[split_at:].lstrip("\n")
        if remaining:
            chunks.append(remaining)
        return chunks
@@ -5,25 +5,15 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
 import re
 import threading
-from typing import Any, Literal
+from typing import Any
 from app.channels.base import Channel
-from app.channels.commands import KNOWN_CHANNEL_COMMANDS
+from app.channels.message_bus import InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
 from app.channels.message_bus import InboundMessage, InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
 from deerflow.config.paths import VIRTUAL_PATH_PREFIX, get_paths
 from deerflow.sandbox.sandbox_provider import get_sandbox_provider
 logger = logging.getLogger(__name__)
 def _is_feishu_command(text: str) -> bool:
    if not text.startswith("/"):
        return False
    return text.split(maxsplit=1)[0].lower() in KNOWN_CHANNEL_COMMANDS
 class FeishuChannel(Channel):
    """Feishu/Lark IM channel using the ``lark-oapi`` WebSocket client.
@@ -59,8 +49,6 @@ class FeishuChannel(Channel):
        self._CreateFileRequestBody = None
        self._CreateImageRequest = None
        self._CreateImageRequestBody = None
        self._GetMessageResourceRequest = None
        self._thread_lock = threading.Lock()
    async def start(self) -> None:
        if self._running:
@@ -78,7 +66,6 @@ class FeishuChannel(Channel):
                CreateMessageRequest,
                CreateMessageRequestBody,
                Emoji,
                GetMessageResourceRequest,
                PatchMessageRequest,
                PatchMessageRequestBody,
                ReplyMessageRequest,
@@ -102,7 +89,6 @@ class FeishuChannel(Channel):
        self._CreateFileRequestBody = CreateFileRequestBody
        self._CreateImageRequest = CreateImageRequest
        self._CreateImageRequestBody = CreateImageRequestBody
        self._GetMessageResourceRequest = GetMessageResourceRequest
        app_id = self.config.get("app_id", "")
        app_secret = self.config.get("app_secret", "")
@@ -213,9 +199,7 @@ class FeishuChannel(Channel):
                    await asyncio.sleep(delay)
        logger.error("[Feishu] send failed after %d attempts: %s", _max_retries, last_exc)
-        if last_exc is None:
+        raise last_exc  # type: ignore[misc]
            raise RuntimeError("Feishu send failed without an exception from any attempt")
        raise last_exc
    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
        if not self._api_client:
@@ -282,112 +266,6 @@ class FeishuChannel(Channel):
            raise RuntimeError(f"Feishu file upload failed: code={response.code}, msg={response.msg}")
        return response.data.file_key
    async def receive_file(self, msg: InboundMessage, thread_id: str) -> InboundMessage:
        """Download a Feishu file into the thread uploads directory.
        Returns the sandbox virtual path when the image is persisted successfully.
        """
        if not msg.thread_ts:
            logger.warning("[Feishu] received file message without thread_ts, cannot associate with conversation: %s", msg)
            return msg
        files = msg.files
        if not files:
            logger.warning("[Feishu] received message with no files: %s", msg)
            return msg
        text = msg.text
        for file in files:
            if file.get("image_key"):
                virtual_path = await self._receive_single_file(msg.thread_ts, file["image_key"], "image", thread_id)
                text = text.replace("[image]", virtual_path, 1)
            elif file.get("file_key"):
                virtual_path = await self._receive_single_file(msg.thread_ts, file["file_key"], "file", thread_id)
                text = text.replace("[file]", virtual_path, 1)
        msg.text = text
        return msg
    async def _receive_single_file(self, message_id: str, file_key: str, type: Literal["image", "file"], thread_id: str) -> str:
        request = self._GetMessageResourceRequest.builder().message_id(message_id).file_key(file_key).type(type).build()
        def inner():
            return self._api_client.im.v1.message_resource.get(request)
        try:
            response = await asyncio.to_thread(inner)
        except Exception:
            logger.exception("[Feishu] resource get request failed for resource_key=%s type=%s", file_key, type)
            return f"Failed to obtain the [{type}]"
        if not response.success():
            logger.warning(
                "[Feishu] resource get failed: resource_key=%s, type=%s, code=%s, msg=%s, log_id=%s ",
                file_key,
                type,
                response.code,
                response.msg,
                response.get_log_id(),
            )
            return f"Failed to obtain the [{type}]"
        image_stream = getattr(response, "file", None)
        if image_stream is None:
            logger.warning("[Feishu] resource get returned no file stream: resource_key=%s, type=%s", file_key, type)
            return f"Failed to obtain the [{type}]"
        try:
            content: bytes = await asyncio.to_thread(image_stream.read)
        except Exception:
            logger.exception("[Feishu] failed to read resource stream: resource_key=%s, type=%s", file_key, type)
            return f"Failed to obtain the [{type}]"
        if not content:
            logger.warning("[Feishu] empty resource content: resource_key=%s, type=%s", file_key, type)
            return f"Failed to obtain the [{type}]"
        paths = get_paths()
        paths.ensure_thread_dirs(thread_id)
        uploads_dir = paths.sandbox_uploads_dir(thread_id).resolve()
        ext = "png" if type == "image" else "bin"
        raw_filename = getattr(response, "file_name", "") or f"feishu_{file_key[-12:]}.{ext}"
        # Sanitize filename: preserve extension, replace path chars in name part
        if "." in raw_filename:
            name_part, ext = raw_filename.rsplit(".", 1)
            name_part = re.sub(r"[./\\]", "_", name_part)
            filename = f"{name_part}.{ext}"
        else:
            filename = re.sub(r"[./\\]", "_", raw_filename)
        resolved_target = uploads_dir / filename
        def down_load():
            # use thread_lock to avoid filename conflicts when writing
            with self._thread_lock:
                resolved_target.write_bytes(content)
        try:
            await asyncio.to_thread(down_load)
        except Exception:
            logger.exception("[Feishu] failed to persist downloaded resource: %s, type=%s", resolved_target, type)
            return f"Failed to obtain the [{type}]"
        virtual_path = f"{VIRTUAL_PATH_PREFIX}/uploads/{resolved_target.name}"
        try:
            sandbox_provider = get_sandbox_provider()
            sandbox_id = sandbox_provider.acquire(thread_id)
            if sandbox_id != "local":
                sandbox = sandbox_provider.get(sandbox_id)
                if sandbox is None:
                    logger.warning("[Feishu] sandbox not found for thread_id=%s", thread_id)
                    return f"Failed to obtain the [{type}]"
                sandbox.update_file(virtual_path, content)
        except Exception:
            logger.exception("[Feishu] failed to sync resource into non-local sandbox: %s", virtual_path)
            return f"Failed to obtain the [{type}]"
        logger.info("[Feishu] downloaded resource mapped: file_key=%s -> %s", file_key, virtual_path)
        return virtual_path
    # -- message formatting ------------------------------------------------
    @staticmethod
@@ -592,28 +470,9 @@ class FeishuChannel(Channel):
            # Parse message content
            content = json.loads(message.content)
            # files_list store the any-file-key in feishu messages, which can be used to download the file content later
            # In Feishu channel, image_keys are independent of file_keys.
            # The file_key includes files, videos, and audio, but does not include stickers.
            files_list = []
            if "text" in content:
                # Handle plain text messages
                text = content["text"]
            elif "file_key" in content:
                file_key = content.get("file_key")
                if isinstance(file_key, str) and file_key:
                    files_list.append({"file_key": file_key})
                    text = "[file]"
                else:
                    text = ""
            elif "image_key" in content:
                image_key = content.get("image_key")
                if isinstance(image_key, str) and image_key:
                    files_list.append({"image_key": image_key})
                    text = "[image]"
                else:
                    text = ""
            elif "content" in content and isinstance(content["content"], list):
                # Handle rich-text messages with a top-level "content" list (e.g., topic groups/posts)
                text_paragraphs: list[str] = []
@@ -627,16 +486,6 @@ class FeishuChannel(Channel):
                                    text_value = element.get("text", "")
                                    if text_value:
                                        paragraph_text_parts.append(text_value)
                                elif element.get("tag") == "img":
                                    image_key = element.get("image_key")
                                    if isinstance(image_key, str) and image_key:
                                        files_list.append({"image_key": image_key})
                                        paragraph_text_parts.append("[image]")
                                elif element.get("tag") in ("file", "media"):
                                    file_key = element.get("file_key")
                                    if isinstance(file_key, str) and file_key:
                                        files_list.append({"file_key": file_key})
                                        paragraph_text_parts.append("[file]")
                        if paragraph_text_parts:
                            # Join text segments within a paragraph with spaces to avoid "helloworld"
                            text_paragraphs.append(" ".join(paragraph_text_parts))
@@ -656,13 +505,12 @@ class FeishuChannel(Channel):
                text[:100] if text else "",
            )
-            if not (text or files_list):
+            if not text:
                logger.info("[Feishu] empty text, ignoring message")
                return
-            # Only treat known slash commands as commands; absolute paths and
+            # Check if it's a command
-            # other slash-prefixed text should be handled as normal chat.
+            if text.startswith("/"):
            if _is_feishu_command(text):
                msg_type = InboundMessageType.COMMAND
            else:
                msg_type = InboundMessageType.CHAT
@@ -676,7 +524,6 @@ class FeishuChannel(Channel):
                text=text,
                msg_type=msg_type,
                thread_ts=msg_id,
                files=files_list,
                metadata={"message_id": msg_id, "root_id": root_id},
            )
            inbound.topic_id = topic_id
@@ -7,14 +7,11 @@ import logging
 import mimetypes
 import re
 import time
-from collections.abc import Awaitable, Callable, Mapping
+from collections.abc import Mapping
 from pathlib import Path
 from typing import Any
 import httpx
 from langgraph_sdk.errors import ConflictError
 from app.channels.commands import KNOWN_CHANNEL_COMMANDS
 from app.channels.message_bus import InboundMessage, InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
 from app.channels.store import ChannelStore
@@ -35,71 +32,11 @@ STREAM_UPDATE_MIN_INTERVAL_SECONDS = 0.35
 THREAD_BUSY_MESSAGE = "This conversation is already processing another request. Please wait for it to finish and try again."
 CHANNEL_CAPABILITIES = {
    "discord": {"supports_streaming": False},
    "feishu": {"supports_streaming": True},
    "slack": {"supports_streaming": False},
    "telegram": {"supports_streaming": False},
    "wechat": {"supports_streaming": False},
    "wecom": {"supports_streaming": True},
 }
 InboundFileReader = Callable[[dict[str, Any], httpx.AsyncClient], Awaitable[bytes | None]]
 INBOUND_FILE_READERS: dict[str, InboundFileReader] = {}
 def register_inbound_file_reader(channel_name: str, reader: InboundFileReader) -> None:
    INBOUND_FILE_READERS[channel_name] = reader
 async def _read_http_inbound_file(file_info: dict[str, Any], client: httpx.AsyncClient) -> bytes | None:
    url = file_info.get("url")
    if not isinstance(url, str) or not url:
        return None
    resp = await client.get(url)
    resp.raise_for_status()
    return resp.content
 async def _read_wecom_inbound_file(file_info: dict[str, Any], client: httpx.AsyncClient) -> bytes | None:
    data = await _read_http_inbound_file(file_info, client)
    if data is None:
        return None
    aeskey = file_info.get("aeskey") if isinstance(file_info.get("aeskey"), str) else None
    if not aeskey:
        return data
    try:
        from aibot.crypto_utils import decrypt_file
    except Exception:
        logger.exception("[Manager] failed to import WeCom decrypt_file")
        return None
    return decrypt_file(data, aeskey)
 async def _read_wechat_inbound_file(file_info: dict[str, Any], client: httpx.AsyncClient) -> bytes | None:
    raw_path = file_info.get("path")
    if isinstance(raw_path, str) and raw_path.strip():
        try:
            return await asyncio.to_thread(Path(raw_path).read_bytes)
        except OSError:
            logger.exception("[Manager] failed to read WeChat inbound file from local path: %s", raw_path)
            return None
    full_url = file_info.get("full_url")
    if isinstance(full_url, str) and full_url.strip():
        return await _read_http_inbound_file({"url": full_url}, client)
    return None
 register_inbound_file_reader("wecom", _read_wecom_inbound_file)
 register_inbound_file_reader("wechat", _read_wechat_inbound_file)
 class InvalidChannelSessionConfigError(ValueError):
    """Raised when IM channel session overrides contain invalid agent config."""
@@ -404,105 +341,6 @@ def _prepare_artifact_delivery(
    return response_text, attachments
 async def _ingest_inbound_files(thread_id: str, msg: InboundMessage) -> list[dict[str, Any]]:
    if not msg.files:
        return []
    from deerflow.uploads.manager import claim_unique_filename, ensure_uploads_dir, normalize_filename
    uploads_dir = ensure_uploads_dir(thread_id)
    seen_names = {entry.name for entry in uploads_dir.iterdir() if entry.is_file()}
    created: list[dict[str, Any]] = []
    file_reader = INBOUND_FILE_READERS.get(msg.channel_name, _read_http_inbound_file)
    async with httpx.AsyncClient(timeout=httpx.Timeout(20.0)) as client:
        for idx, f in enumerate(msg.files):
            if not isinstance(f, dict):
                continue
            ftype = f.get("type") if isinstance(f.get("type"), str) else "file"
            filename = f.get("filename") if isinstance(f.get("filename"), str) else ""
            try:
                data = await file_reader(f, client)
            except Exception:
                logger.exception(
                    "[Manager] failed to read inbound file: channel=%s, file=%s",
                    msg.channel_name,
                    f.get("url") or filename or idx,
                )
                continue
            if data is None:
                logger.warning(
                    "[Manager] inbound file reader returned no data: channel=%s, file=%s",
                    msg.channel_name,
                    f.get("url") or filename or idx,
                )
                continue
            if not filename:
                ext = ".bin"
                if ftype == "image":
                    ext = ".png"
                filename = f"{msg.thread_ts or 'msg'}_{idx}{ext}"
            try:
                safe_name = claim_unique_filename(normalize_filename(filename), seen_names)
            except ValueError:
                logger.warning(
                    "[Manager] skipping inbound file with unsafe filename: channel=%s, file=%r",
                    msg.channel_name,
                    filename,
                )
                continue
            dest = uploads_dir / safe_name
            try:
                dest.write_bytes(data)
            except Exception:
                logger.exception("[Manager] failed to write inbound file: %s", dest)
                continue
            created.append(
                {
                    "filename": safe_name,
                    "size": len(data),
                    "path": f"/mnt/user-data/uploads/{safe_name}",
                    "is_image": ftype == "image",
                }
            )
    return created
 def _format_uploaded_files_block(files: list[dict[str, Any]]) -> str:
    lines = [
        "<uploaded_files>",
        "The following files were uploaded in this message:",
        "",
    ]
    if not files:
        lines.append("(empty)")
    else:
        for f in files:
            filename = f.get("filename", "")
            size = int(f.get("size") or 0)
            size_kb = size / 1024 if size else 0
            size_str = f"{size_kb:.1f} KB" if size_kb < 1024 else f"{size_kb / 1024:.1f} MB"
            path = f.get("path", "")
            is_image = bool(f.get("is_image"))
            file_kind = "image" if is_image else "file"
            lines.append(f"- {filename} ({size_str})")
            lines.append(f"  Type: {file_kind}")
            lines.append(f"  Path: {path}")
            lines.append("")
    lines.append("Use `read_file` for text-based files and documents.")
    lines.append("Use `view_image` for image files (jpg, jpeg, png, webp) so the model can inspect the image content.")
    lines.append("</uploaded_files>")
    return "\n".join(lines)
 class ChannelManager:
    """Core dispatcher that bridges IM channels to the DeerFlow agent.
@@ -695,25 +533,8 @@ class ChannelManager:
            thread_id = await self._create_thread(client, msg)
        assistant_id, run_config, run_context = self._resolve_run_params(msg, thread_id)
        # If the inbound message contains file attachments, let the channel
        # materialize (download) them and update msg.text to include sandbox file paths.
        # This enables downstream models to access user-uploaded files by path.
        # Channels that do not support file download will simply return the original message.
        if msg.files:
            from .service import get_channel_service
            service = get_channel_service()
            channel = service.get_channel(msg.channel_name) if service else None
            logger.info("[Manager] preparing receive file context for %d attachments", len(msg.files))
            msg = await channel.receive_file(msg, thread_id) if channel else msg
        if extra_context:
            run_context.update(extra_context)
        uploaded = await _ingest_inbound_files(thread_id, msg)
        if uploaded:
            msg.text = f"{_format_uploaded_files_block(uploaded)}\n\n{msg.text}".strip()
        if self._channel_supports_streaming(msg.channel_name):
            await self._handle_streaming_chat(
                client,
@@ -914,8 +735,7 @@ class ChannelManager:
                "/help — Show this help"
            )
        else:
-            available = " | ".join(sorted(KNOWN_CHANNEL_COMMANDS))
+            reply = f"Unknown command: /{command}. Type /help for available commands."
            reply = f"Unknown command: /{command}. Available commands: {available}"
        outbound = OutboundMessage(
            channel_name=msg.channel_name,
@@ -6,7 +6,6 @@ import logging
 import os
 from typing import Any
 from app.channels.base import Channel
 from app.channels.manager import DEFAULT_GATEWAY_URL, DEFAULT_LANGGRAPH_URL, ChannelManager
 from app.channels.message_bus import MessageBus
 from app.channels.store import ChannelStore
@@ -15,22 +14,9 @@ logger = logging.getLogger(__name__)
 # Channel name → import path for lazy loading
 _CHANNEL_REGISTRY: dict[str, str] = {
    "discord": "app.channels.discord:DiscordChannel",
    "feishu": "app.channels.feishu:FeishuChannel",
    "slack": "app.channels.slack:SlackChannel",
    "telegram": "app.channels.telegram:TelegramChannel",
    "wechat": "app.channels.wechat:WechatChannel",
    "wecom": "app.channels.wecom:WeComChannel",
 }
 # Keys that indicate a user has configured credentials for a channel.
 _CHANNEL_CREDENTIAL_KEYS: dict[str, list[str]] = {
    "discord": ["bot_token"],
    "feishu": ["app_id", "app_secret"],
    "slack": ["bot_token", "app_token"],
    "telegram": ["bot_token"],
    "wecom": ["bot_id", "bot_secret"],
    "wechat": ["bot_token"],
 }
 _CHANNELS_LANGGRAPH_URL_ENV = "DEER_FLOW_CHANNELS_LANGGRAPH_URL"
@@ -98,16 +84,7 @@ class ChannelService:
            if not isinstance(channel_config, dict):
                continue
            if not channel_config.get("enabled", False):
-                cred_keys = _CHANNEL_CREDENTIAL_KEYS.get(name, [])
+                logger.info("Channel %s is disabled, skipping", name)
                has_creds = any(not isinstance(channel_config.get(k), bool) and channel_config.get(k) is not None and str(channel_config[k]).strip() for k in cred_keys)
                if has_creds:
                    logger.warning(
                        "Channel '%s' has credentials configured but is disabled. Set enabled: true under channels.%s in config.yaml to activate it.",
                        name,
                        name,
                    )
                else:
                    logger.info("Channel %s is disabled, skipping", name)
                continue
            await self._start_channel(name, channel_config)
@@ -186,10 +163,6 @@ class ChannelService:
            "channels": channels_status,
        }
    def get_channel(self, name: str) -> Channel | None:
        """Return a running channel instance by name when available."""
        return self._channels.get(name)
 # -- singleton access -------------------------------------------------------
@@ -16,31 +16,13 @@ logger = logging.getLogger(__name__)
 _slack_md_converter = SlackMarkdownConverter()
 def _normalize_allowed_users(allowed_users: Any) -> set[str]:
    if allowed_users is None:
        return set()
    if isinstance(allowed_users, str):
        values = [allowed_users]
    elif isinstance(allowed_users, list | tuple | set):
        values = allowed_users
    else:
        logger.warning(
            "Slack allowed_users should be a list of Slack user IDs or a single Slack user ID string; treating %s as one string value",
            type(allowed_users).__name__,
        )
        values = [allowed_users]
    return {str(user_id) for user_id in values if str(user_id)}
 class SlackChannel(Channel):
    """Slack IM channel using Socket Mode (WebSocket, no public IP).
    Configuration keys (in ``config.yaml`` under ``channels.slack``):
        - ``bot_token``: Slack Bot User OAuth Token (xoxb-...).
        - ``app_token``: Slack App-Level Token (xapp-...) for Socket Mode.
-        - ``allowed_users``: (optional) List of allowed Slack user IDs, or a
+        - ``allowed_users``: (optional) List of allowed Slack user IDs. Empty = allow all.
          single Slack user ID string as shorthand. Empty = allow all. Other
          scalar values are treated as a single string with a warning.
    """
    def __init__(self, bus: MessageBus, config: dict[str, Any]) -> None:
@@ -48,7 +30,7 @@ class SlackChannel(Channel):
        self._socket_client = None
        self._web_client = None
        self._loop: asyncio.AbstractEventLoop | None = None
-        self._allowed_users = _normalize_allowed_users(config.get("allowed_users", []))
+        self._allowed_users: set[str] = set(config.get("allowed_users", []))
    async def start(self) -> None:
        if self._running:
@@ -144,9 +126,7 @@ class SlackChannel(Channel):
                )
            except Exception:
                pass
-        if last_exc is None:
+        raise last_exc  # type: ignore[misc]
            raise RuntimeError("Slack send failed without an exception from any attempt")
        raise last_exc
    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
        if not self._web_client:
@@ -125,9 +125,7 @@ class TelegramChannel(Channel):
                    await asyncio.sleep(delay)
        logger.error("[Telegram] send failed after %d attempts: %s", _max_retries, last_exc)
-        if last_exc is None:
+        raise last_exc  # type: ignore[misc]
            raise RuntimeError("Telegram send failed without an exception from any attempt")
        raise last_exc
    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
        if not self._application:
@@ -1,394 +0,0 @@
 from __future__ import annotations
 import asyncio
 import base64
 import hashlib
 import logging
 from collections.abc import Awaitable, Callable
 from typing import Any, cast
 from app.channels.base import Channel
 from app.channels.message_bus import (
    InboundMessageType,
    MessageBus,
    OutboundMessage,
    ResolvedAttachment,
 )
 logger = logging.getLogger(__name__)
 class WeComChannel(Channel):
    def __init__(self, bus: MessageBus, config: dict[str, Any]) -> None:
        super().__init__(name="wecom", bus=bus, config=config)
        self._bot_id: str | None = None
        self._bot_secret: str | None = None
        self._ws_client = None
        self._ws_task: asyncio.Task | None = None
        self._ws_frames: dict[str, dict[str, Any]] = {}
        self._ws_stream_ids: dict[str, str] = {}
        self._working_message = "Working on it..."
    def _clear_ws_context(self, thread_ts: str | None) -> None:
        if not thread_ts:
            return
        self._ws_frames.pop(thread_ts, None)
        self._ws_stream_ids.pop(thread_ts, None)
    async def _send_ws_upload_command(self, req_id: str, body: dict[str, Any], cmd: str) -> dict[str, Any]:
        if not self._ws_client:
            raise RuntimeError("WeCom WebSocket client is not available")
        ws_manager = getattr(self._ws_client, "_ws_manager", None)
        send_reply = getattr(ws_manager, "send_reply", None)
        if not callable(send_reply):
            raise RuntimeError("Installed wecom-aibot-python-sdk does not expose the WebSocket media upload API expected by DeerFlow. Use wecom-aibot-python-sdk==0.1.6 or update the adapter.")
        send_reply_async = cast(Callable[[str, dict[str, Any], str], Awaitable[dict[str, Any]]], send_reply)
        return await send_reply_async(req_id, body, cmd)
    async def start(self) -> None:
        if self._running:
            return
        bot_id = self.config.get("bot_id")
        bot_secret = self.config.get("bot_secret")
        working_message = self.config.get("working_message")
        self._bot_id = bot_id if isinstance(bot_id, str) and bot_id else None
        self._bot_secret = bot_secret if isinstance(bot_secret, str) and bot_secret else None
        self._working_message = working_message if isinstance(working_message, str) and working_message else "Working on it..."
        if not self._bot_id or not self._bot_secret:
            logger.error("WeCom channel requires bot_id and bot_secret")
            return
        try:
            from aibot import WSClient, WSClientOptions
        except ImportError:
            logger.error("wecom-aibot-python-sdk is not installed. Install it with: uv add wecom-aibot-python-sdk")
            return
        else:
            self._ws_client = WSClient(WSClientOptions(bot_id=self._bot_id, secret=self._bot_secret, logger=logger))
            self._ws_client.on("message.text", self._on_ws_text)
            self._ws_client.on("message.mixed", self._on_ws_mixed)
            self._ws_client.on("message.image", self._on_ws_image)
            self._ws_client.on("message.file", self._on_ws_file)
            self._ws_task = asyncio.create_task(self._ws_client.connect())
            self._running = True
            self.bus.subscribe_outbound(self._on_outbound)
        logger.info("WeCom channel started")
    async def stop(self) -> None:
        self._running = False
        self.bus.unsubscribe_outbound(self._on_outbound)
        if self._ws_task:
            try:
                self._ws_task.cancel()
            except Exception:
                pass
            self._ws_task = None
        if self._ws_client:
            try:
                self._ws_client.disconnect()
            except Exception:
                pass
        self._ws_client = None
        self._ws_frames.clear()
        self._ws_stream_ids.clear()
        logger.info("WeCom channel stopped")
    async def send(self, msg: OutboundMessage, *, _max_retries: int = 3) -> None:
        if self._ws_client:
            await self._send_ws(msg, _max_retries=_max_retries)
            return
        logger.warning("[WeCom] send called but WebSocket client is not available")
    async def _on_outbound(self, msg: OutboundMessage) -> None:
        if msg.channel_name != self.name:
            return
        try:
            await self.send(msg)
        except Exception:
            logger.exception("Failed to send outbound message on channel %s", self.name)
            if msg.is_final:
                self._clear_ws_context(msg.thread_ts)
            return
        for attachment in msg.attachments:
            try:
                success = await self.send_file(msg, attachment)
                if not success:
                    logger.warning("[%s] file upload skipped for %s", self.name, attachment.filename)
            except Exception:
                logger.exception("[%s] failed to upload file %s", self.name, attachment.filename)
        if msg.is_final:
            self._clear_ws_context(msg.thread_ts)
    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
        if not msg.is_final:
            return True
        if not self._ws_client:
            return False
        if not msg.thread_ts:
            return False
        frame = self._ws_frames.get(msg.thread_ts)
        if not frame:
            return False
        media_type = "image" if attachment.is_image else "file"
        size_limit = 2 * 1024 * 1024 if attachment.is_image else 20 * 1024 * 1024
        if attachment.size > size_limit:
            logger.warning(
                "[WeCom] %s too large (%d bytes), skipping: %s",
                media_type,
                attachment.size,
                attachment.filename,
            )
            return False
        try:
            media_id = await self._upload_media_ws(
                media_type=media_type,
                filename=attachment.filename,
                path=str(attachment.actual_path),
                size=attachment.size,
            )
            if not media_id:
                return False
            body = {media_type: {"media_id": media_id}, "msgtype": media_type}
            await self._ws_client.reply(frame, body)
            logger.debug("[WeCom] %s sent via ws: %s", media_type, attachment.filename)
            return True
        except Exception:
            logger.exception("[WeCom] failed to upload/send file via ws: %s", attachment.filename)
            return False
    async def _on_ws_text(self, frame: dict[str, Any]) -> None:
        body = frame.get("body", {}) or {}
        text = ((body.get("text") or {}).get("content") or "").strip()
        quote = body.get("quote", {}).get("text", {}).get("content", "").strip()
        if not text and not quote:
            return
        await self._publish_ws_inbound(frame, text + (f"\nQuote message: {quote}" if quote else ""))
    async def _on_ws_mixed(self, frame: dict[str, Any]) -> None:
        body = frame.get("body", {}) or {}
        mixed = body.get("mixed") or {}
        items = mixed.get("msg_item") or []
        parts: list[str] = []
        files: list[dict[str, Any]] = []
        for item in items:
            item_type = (item or {}).get("msgtype")
            if item_type == "text":
                content = (((item or {}).get("text") or {}).get("content") or "").strip()
                if content:
                    parts.append(content)
            elif item_type in ("image", "file"):
                payload = (item or {}).get(item_type) or {}
                url = payload.get("url")
                aeskey = payload.get("aeskey")
                if isinstance(url, str) and url:
                    files.append(
                        {
                            "type": item_type,
                            "url": url,
                            "aeskey": (aeskey if isinstance(aeskey, str) and aeskey else None),
                        }
                    )
        text = "\n\n".join(parts).strip()
        if not text and not files:
            return
        if not text:
            text = "（receive image/file）"
        await self._publish_ws_inbound(frame, text, files=files)
    async def _on_ws_image(self, frame: dict[str, Any]) -> None:
        body = frame.get("body", {}) or {}
        image = body.get("image") or {}
        url = image.get("url")
        aeskey = image.get("aeskey")
        if not isinstance(url, str) or not url:
            return
        await self._publish_ws_inbound(
            frame,
            "（receive image ）",
            files=[
                {
                    "type": "image",
                    "url": url,
                    "aeskey": aeskey if isinstance(aeskey, str) and aeskey else None,
                }
            ],
        )
    async def _on_ws_file(self, frame: dict[str, Any]) -> None:
        body = frame.get("body", {}) or {}
        file_obj = body.get("file") or {}
        url = file_obj.get("url")
        aeskey = file_obj.get("aeskey")
        if not isinstance(url, str) or not url:
            return
        await self._publish_ws_inbound(
            frame,
            "（receive file）",
            files=[
                {
                    "type": "file",
                    "url": url,
                    "aeskey": aeskey if isinstance(aeskey, str) and aeskey else None,
                }
            ],
        )
    async def _publish_ws_inbound(
        self,
        frame: dict[str, Any],
        text: str,
        *,
        files: list[dict[str, Any]] | None = None,
    ) -> None:
        if not self._ws_client:
            return
        try:
            from aibot import generate_req_id
        except Exception:
            return
        body = frame.get("body", {}) or {}
        msg_id = body.get("msgid")
        if not msg_id:
            return
        user_id = (body.get("from") or {}).get("userid")
        inbound_type = InboundMessageType.COMMAND if text.startswith("/") else InboundMessageType.CHAT
        inbound = self._make_inbound(
            chat_id=user_id,  # keep user's conversation in memory
            user_id=user_id,
            text=text,
            msg_type=inbound_type,
            thread_ts=msg_id,
            files=files or [],
            metadata={"aibotid": body.get("aibotid"), "chattype": body.get("chattype")},
        )
        inbound.topic_id = user_id  # keep the same thread
        stream_id = generate_req_id("stream")
        self._ws_frames[msg_id] = frame
        self._ws_stream_ids[msg_id] = stream_id
        try:
            await self._ws_client.reply_stream(frame, stream_id, self._working_message, False)
        except Exception:
            pass
        await self.bus.publish_inbound(inbound)
    async def _send_ws(self, msg: OutboundMessage, *, _max_retries: int = 3) -> None:
        if not self._ws_client:
            return
        try:
            from aibot import generate_req_id
        except Exception:
            generate_req_id = None
        if msg.thread_ts and msg.thread_ts in self._ws_frames:
            frame = self._ws_frames[msg.thread_ts]
            stream_id = self._ws_stream_ids.get(msg.thread_ts)
            if not stream_id and generate_req_id:
                stream_id = generate_req_id("stream")
                self._ws_stream_ids[msg.thread_ts] = stream_id
            if not stream_id:
                return
            last_exc: Exception | None = None
            for attempt in range(_max_retries):
                try:
                    await self._ws_client.reply_stream(frame, stream_id, msg.text, bool(msg.is_final))
                    return
                except Exception as exc:
                    last_exc = exc
                    if attempt < _max_retries - 1:
                        await asyncio.sleep(2**attempt)
            if last_exc:
                raise last_exc
        body = {"msgtype": "markdown", "markdown": {"content": msg.text}}
        last_exc = None
        for attempt in range(_max_retries):
            try:
                await self._ws_client.send_message(msg.chat_id, body)
                return
            except Exception as exc:
                last_exc = exc
                if attempt < _max_retries - 1:
                    await asyncio.sleep(2**attempt)
        if last_exc:
            raise last_exc
    async def _upload_media_ws(
        self,
        *,
        media_type: str,
        filename: str,
        path: str,
        size: int,
    ) -> str | None:
        if not self._ws_client:
            return None
        try:
            from aibot import generate_req_id
        except Exception:
            return None
        chunk_size = 512 * 1024
        total_chunks = (size + chunk_size - 1) // chunk_size
        if total_chunks < 1 or total_chunks > 100:
            logger.warning("[WeCom] invalid total_chunks=%d for %s", total_chunks, filename)
            return None
        md5_hasher = hashlib.md5()
        with open(path, "rb") as f:
            for chunk in iter(lambda: f.read(1024 * 1024), b""):
                md5_hasher.update(chunk)
        md5 = md5_hasher.hexdigest()
        init_req_id = generate_req_id("aibot_upload_media_init")
        init_body = {
            "type": media_type,
            "filename": filename,
            "total_size": int(size),
            "total_chunks": int(total_chunks),
            "md5": md5,
        }
        init_ack = await self._send_ws_upload_command(init_req_id, init_body, "aibot_upload_media_init")
        upload_id = (init_ack.get("body") or {}).get("upload_id")
        if not upload_id:
            logger.warning("[WeCom] upload init returned no upload_id: %s", init_ack)
            return None
        with open(path, "rb") as f:
            for idx in range(total_chunks):
                data = f.read(chunk_size)
                if not data:
                    break
                chunk_req_id = generate_req_id("aibot_upload_media_chunk")
                chunk_body = {
                    "upload_id": upload_id,
                    "chunk_index": int(idx),
                    "base64_data": base64.b64encode(data).decode("utf-8"),
                }
                await self._send_ws_upload_command(chunk_req_id, chunk_body, "aibot_upload_media_chunk")
        finish_req_id = generate_req_id("aibot_upload_media_finish")
        finish_ack = await self._send_ws_upload_command(finish_req_id, {"upload_id": upload_id}, "aibot_upload_media_finish")
        media_id = (finish_ack.get("body") or {}).get("media_id")
        if not media_id:
            logger.warning("[WeCom] upload finish returned no media_id: %s", finish_ack)
            return None
        return media_id
@@ -1,4 +1,3 @@
 import asyncio
 import logging
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
@@ -33,11 +32,6 @@ logging.basicConfig(
 logger = logging.getLogger(__name__)
 # Upper bound (seconds) each lifespan shutdown hook is allowed to run.
 # Bounds worker exit time so uvicorn's reload supervisor does not keep
 # firing signals into a worker that is stuck waiting for shutdown cleanup.
 _SHUTDOWN_HOOK_TIMEOUT_SECONDS = 5.0
@asynccontextmanager
 async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
@@ -69,19 +63,11 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
        yield
-        # Stop channel service on shutdown (bounded to prevent worker hang)
+        # Stop channel service on shutdown
        try:
            from app.channels.service import stop_channel_service
-            await asyncio.wait_for(
+            await stop_channel_service()
                stop_channel_service(),
                timeout=_SHUTDOWN_HOOK_TIMEOUT_SECONDS,
            )
        except TimeoutError:
            logger.warning(
                "Channel service shutdown exceeded %.1fs; proceeding with worker exit.",
                _SHUTDOWN_HOOK_TIMEOUT_SECONDS,
            )
        except Exception:
            logger.exception("Failed to stop channel service")
@@ -8,7 +8,6 @@ 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
@@ -25,8 +24,7 @@ class AgentResponse(BaseModel):
    description: str = Field(default="", description="Agent description")
    model: str | None = Field(default=None, description="Optional model override")
    tool_groups: list[str] | None = Field(default=None, description="Optional tool group whitelist")
-    skills: list[str] | None = Field(default=None, description="Optional skill whitelist (None=all, []=none)")
+    soul: str | None = Field(default=None, description="SOUL.md content (included on GET /{name})")
    soul: str | None = Field(default=None, description="SOUL.md content")
 class AgentsListResponse(BaseModel):
@@ -42,7 +40,6 @@ class AgentCreateRequest(BaseModel):
    description: str = Field(default="", description="Agent description")
    model: str | None = Field(default=None, description="Optional model override")
    tool_groups: list[str] | None = Field(default=None, description="Optional tool group whitelist")
    skills: list[str] | None = Field(default=None, description="Optional skill whitelist (None=all enabled, []=none)")
    soul: str = Field(default="", description="SOUL.md content — agent personality and behavioral guardrails")
@@ -52,7 +49,6 @@ class AgentUpdateRequest(BaseModel):
    description: str | None = Field(default=None, description="Updated description")
    model: str | None = Field(default=None, description="Updated model override")
    tool_groups: list[str] | None = Field(default=None, description="Updated tool group whitelist")
    skills: list[str] | None = Field(default=None, description="Updated skill whitelist (None=all, []=none)")
    soul: str | None = Field(default=None, description="Updated SOUL.md content")
@@ -77,15 +73,6 @@ 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
@@ -97,7 +84,6 @@ def _agent_config_to_response(agent_cfg: AgentConfig, include_soul: bool = False
        description=agent_cfg.description,
        model=agent_cfg.model,
        tool_groups=agent_cfg.tool_groups,
        skills=agent_cfg.skills,
        soul=soul,
    )
@@ -106,19 +92,17 @@ def _agent_config_to_response(agent_cfg: AgentConfig, include_soul: bool = False
    "/agents",
    response_model=AgentsListResponse,
    summary="List Custom Agents",
-    description="List all custom agents available in the agents directory, including their soul content.",
+    description="List all custom agents available in the agents directory.",
 )
 async def list_agents() -> AgentsListResponse:
    """List all custom agents.
    Returns:
-        List of all custom agents with their metadata and soul content.
+        List of all custom agents with their metadata (without 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])
+        return AgentsListResponse(agents=[_agent_config_to_response(a) for a in agents])
    except Exception as e:
        logger.error(f"Failed to list agents: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to list agents: {str(e)}")
@@ -141,7 +125,6 @@ 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()
@@ -166,7 +149,6 @@ 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)
@@ -199,7 +181,6 @@ 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)
@@ -219,8 +200,6 @@ async def create_agent_endpoint(request: AgentCreateRequest) -> AgentResponse:
            config_data["model"] = request.model
        if request.tool_groups is not None:
            config_data["tool_groups"] = request.tool_groups
        if request.skills is not None:
            config_data["skills"] = request.skills
        config_file = agent_dir / "config.yaml"
        with open(config_file, "w", encoding="utf-8") as f:
@@ -264,7 +243,6 @@ 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)
@@ -277,32 +255,21 @@ async def update_agent(name: str, request: AgentUpdateRequest) -> AgentResponse:
    try:
        # Update config if any config fields changed
-        # Use model_fields_set to distinguish "field omitted" from "explicitly set to null".
+        config_changed = any(v is not None for v in [request.description, request.model, request.tool_groups])
        # This is critical for skills where None means "inherit all" (not "don't change").
        fields_set = request.model_fields_set
        config_changed = bool(fields_set & {"description", "model", "tool_groups", "skills"})
        if config_changed:
            updated: dict = {
                "name": agent_cfg.name,
-                "description": request.description if "description" in fields_set else agent_cfg.description,
+                "description": request.description if request.description is not None else agent_cfg.description,
            }
-            new_model = request.model if "model" in fields_set else agent_cfg.model
+            new_model = request.model if request.model is not None else agent_cfg.model
            if new_model is not None:
                updated["model"] = new_model
-            new_tool_groups = request.tool_groups if "tool_groups" in fields_set else agent_cfg.tool_groups
+            new_tool_groups = request.tool_groups if request.tool_groups is not None else agent_cfg.tool_groups
            if new_tool_groups is not None:
                updated["tool_groups"] = new_tool_groups
            # skills: None = inherit all, [] = no skills, ["a","b"] = whitelist
            if "skills" in fields_set:
                new_skills = request.skills
            else:
                new_skills = agent_cfg.skills
            if new_skills is not None:
                updated["skills"] = new_skills
            config_file = agent_dir / "config.yaml"
            with open(config_file, "w", encoding="utf-8") as f:
                yaml.dump(updated, f, default_flow_style=False, allow_unicode=True)
@@ -348,8 +315,6 @@ 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():
@@ -376,8 +341,6 @@ 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)
@@ -404,7 +367,6 @@ 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)
@@ -49,7 +49,6 @@ class Fact(BaseModel):
    confidence: float = Field(default=0.5, description="Confidence score (0-1)")
    createdAt: str = Field(default="", description="Creation timestamp")
    source: str = Field(default="unknown", description="Source thread ID")
    sourceError: str | None = Field(default=None, description="Optional description of the prior mistake or wrong approach")
 class MemoryResponse(BaseModel):
@@ -109,7 +108,6 @@ class MemoryStatusResponse(BaseModel):
@router.get(
    "/memory",
    response_model=MemoryResponse,
    response_model_exclude_none=True,
    summary="Get Memory Data",
    description="Retrieve the current global memory data including user context, history, and facts.",
 )
@@ -154,7 +152,6 @@ async def get_memory() -> MemoryResponse:
@router.post(
    "/memory/reload",
    response_model=MemoryResponse,
    response_model_exclude_none=True,
    summary="Reload Memory Data",
    description="Reload memory data from the storage file, refreshing the in-memory cache.",
 )
@@ -174,7 +171,6 @@ async def reload_memory() -> MemoryResponse:
@router.delete(
    "/memory",
    response_model=MemoryResponse,
    response_model_exclude_none=True,
    summary="Clear All Memory Data",
    description="Delete all saved memory data and reset the memory structure to an empty state.",
 )
@@ -191,7 +187,6 @@ async def clear_memory() -> MemoryResponse:
@router.post(
    "/memory/facts",
    response_model=MemoryResponse,
    response_model_exclude_none=True,
    summary="Create Memory Fact",
    description="Create a single saved memory fact manually.",
 )
@@ -214,7 +209,6 @@ async def create_memory_fact_endpoint(request: FactCreateRequest) -> MemoryRespo
@router.delete(
    "/memory/facts/{fact_id}",
    response_model=MemoryResponse,
    response_model_exclude_none=True,
    summary="Delete Memory Fact",
    description="Delete a single saved memory fact by its fact id.",
 )
@@ -233,7 +227,6 @@ async def delete_memory_fact_endpoint(fact_id: str) -> MemoryResponse:
@router.patch(
    "/memory/facts/{fact_id}",
    response_model=MemoryResponse,
    response_model_exclude_none=True,
    summary="Patch Memory Fact",
    description="Partially update a single saved memory fact by its fact id while preserving omitted fields.",
 )
@@ -259,7 +252,6 @@ async def update_memory_fact_endpoint(fact_id: str, request: FactPatchRequest) -
@router.get(
    "/memory/export",
    response_model=MemoryResponse,
    response_model_exclude_none=True,
    summary="Export Memory Data",
    description="Export the current global memory data as JSON for backup or transfer.",
 )
@@ -272,7 +264,6 @@ async def export_memory() -> MemoryResponse:
@router.post(
    "/memory/import",
    response_model=MemoryResponse,
    response_model_exclude_none=True,
    summary="Import Memory Data",
    description="Import and overwrite the current global memory data from a JSON payload.",
 )
@@ -326,7 +317,6 @@ async def get_memory_config_endpoint() -> MemoryConfigResponse:
@router.get(
    "/memory/status",
    response_model=MemoryStatusResponse,
    response_model_exclude_none=True,
    summary="Get Memory Status",
    description="Retrieve both memory configuration and current data in a single request.",
 )
@@ -17,17 +17,10 @@ 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(
@@ -43,7 +36,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 and token usage display settings.
+        A list of all configured models with their metadata.
    Example Response:
        ```json
@@ -51,24 +44,17 @@ 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
            }
        }
        ```
    """
@@ -84,10 +70,7 @@ async def list_models() -> ModelsListResponse:
        )
        for model in config.models
    ]
-    return ModelsListResponse(
+    return ModelsListResponse(models=models)
        models=models,
        token_usage=TokenUsageResponse(enabled=config.token_usage.enabled),
    )
@router.get(
@@ -51,7 +51,6 @@ async def stateless_stream(body: RunCreateRequest, request: Request) -> Streamin
            "Cache-Control": "no-cache",
            "Connection": "keep-alive",
            "X-Accel-Buffering": "no",
            "Content-Location": f"/api/threads/{thread_id}/runs/{record.run_id}",
        },
    )
@@ -1,30 +1,14 @@
 import errno
 import json
 import logging
 import shutil
 from pathlib import Path
 from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel, Field
 from app.gateway.path_utils import resolve_thread_virtual_path
 from deerflow.agents.lead_agent.prompt import refresh_skills_system_prompt_cache_async
 from deerflow.config.extensions_config import ExtensionsConfig, SkillStateConfig, get_extensions_config, reload_extensions_config
 from deerflow.skills import Skill, load_skills
 from deerflow.skills.installer import SkillAlreadyExistsError, install_skill_from_archive
 from deerflow.skills.manager import (
    append_history,
    atomic_write,
    custom_skill_exists,
    ensure_custom_skill_is_editable,
    get_custom_skill_dir,
    get_custom_skill_file,
    get_skill_history_file,
    read_custom_skill_content,
    read_history,
    validate_skill_markdown_content,
 )
 from deerflow.skills.security_scanner import scan_skill_content
 logger = logging.getLogger(__name__)
@@ -68,22 +52,6 @@ class SkillInstallResponse(BaseModel):
    message: str = Field(..., description="Installation result message")
 class CustomSkillContentResponse(SkillResponse):
    content: str = Field(..., description="Raw SKILL.md content")
 class CustomSkillUpdateRequest(BaseModel):
    content: str = Field(..., description="Replacement SKILL.md content")
 class CustomSkillHistoryResponse(BaseModel):
    history: list[dict]
 class SkillRollbackRequest(BaseModel):
    history_index: int = Field(default=-1, description="History entry index to restore from, defaulting to the latest change.")
 def _skill_to_response(skill: Skill) -> SkillResponse:
    """Convert a Skill object to a SkillResponse."""
    return SkillResponse(
@@ -110,186 +78,6 @@ async def list_skills() -> SkillsListResponse:
        raise HTTPException(status_code=500, detail=f"Failed to load skills: {str(e)}")
@router.post(
    "/skills/install",
    response_model=SkillInstallResponse,
    summary="Install Skill",
    description="Install a skill from a .skill file (ZIP archive) located in the thread's user-data directory.",
 )
 async def install_skill(request: SkillInstallRequest) -> SkillInstallResponse:
    try:
        skill_file_path = resolve_thread_virtual_path(request.thread_id, request.path)
        result = install_skill_from_archive(skill_file_path)
        await refresh_skills_system_prompt_cache_async()
        return SkillInstallResponse(**result)
    except FileNotFoundError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except SkillAlreadyExistsError as e:
        raise HTTPException(status_code=409, detail=str(e))
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Failed to install skill: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to install skill: {str(e)}")
@router.get("/skills/custom", response_model=SkillsListResponse, summary="List Custom Skills")
 async def list_custom_skills() -> SkillsListResponse:
    try:
        skills = [skill for skill in load_skills(enabled_only=False) if skill.category == "custom"]
        return SkillsListResponse(skills=[_skill_to_response(skill) for skill in skills])
    except Exception as e:
        logger.error("Failed to list custom skills: %s", e, exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to list custom skills: {str(e)}")
@router.get("/skills/custom/{skill_name}", response_model=CustomSkillContentResponse, summary="Get Custom Skill Content")
 async def get_custom_skill(skill_name: str) -> CustomSkillContentResponse:
    try:
        skills = load_skills(enabled_only=False)
        skill = next((s for s in skills if s.name == skill_name and s.category == "custom"), None)
        if skill is None:
            raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
        return CustomSkillContentResponse(**_skill_to_response(skill).model_dump(), content=read_custom_skill_content(skill_name))
    except HTTPException:
        raise
    except Exception as e:
        logger.error("Failed to get custom skill %s: %s", skill_name, e, exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to get custom skill: {str(e)}")
@router.put("/skills/custom/{skill_name}", response_model=CustomSkillContentResponse, summary="Edit Custom Skill")
 async def update_custom_skill(skill_name: str, request: CustomSkillUpdateRequest) -> CustomSkillContentResponse:
    try:
        ensure_custom_skill_is_editable(skill_name)
        validate_skill_markdown_content(skill_name, request.content)
        scan = await scan_skill_content(request.content, executable=False, location=f"{skill_name}/SKILL.md")
        if scan.decision == "block":
            raise HTTPException(status_code=400, detail=f"Security scan blocked the edit: {scan.reason}")
        skill_file = get_custom_skill_dir(skill_name) / "SKILL.md"
        prev_content = skill_file.read_text(encoding="utf-8")
        atomic_write(skill_file, request.content)
        append_history(
            skill_name,
            {
                "action": "human_edit",
                "author": "human",
                "thread_id": None,
                "file_path": "SKILL.md",
                "prev_content": prev_content,
                "new_content": request.content,
                "scanner": {"decision": scan.decision, "reason": scan.reason},
            },
        )
        await refresh_skills_system_prompt_cache_async()
        return await get_custom_skill(skill_name)
    except HTTPException:
        raise
    except FileNotFoundError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))
    except Exception as e:
        logger.error("Failed to update custom skill %s: %s", skill_name, e, exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to update custom skill: {str(e)}")
@router.delete("/skills/custom/{skill_name}", summary="Delete Custom Skill")
 async def delete_custom_skill(skill_name: str) -> dict[str, bool]:
    try:
        ensure_custom_skill_is_editable(skill_name)
        skill_dir = get_custom_skill_dir(skill_name)
        prev_content = read_custom_skill_content(skill_name)
        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}
    except FileNotFoundError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))
    except Exception as e:
        logger.error("Failed to delete custom skill %s: %s", skill_name, e, exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to delete custom skill: {str(e)}")
@router.get("/skills/custom/{skill_name}/history", response_model=CustomSkillHistoryResponse, summary="Get Custom Skill History")
 async def get_custom_skill_history(skill_name: str) -> CustomSkillHistoryResponse:
    try:
        if not custom_skill_exists(skill_name) and not get_skill_history_file(skill_name).exists():
            raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
        return CustomSkillHistoryResponse(history=read_history(skill_name))
    except HTTPException:
        raise
    except Exception as e:
        logger.error("Failed to read history for %s: %s", skill_name, e, exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to read history: {str(e)}")
@router.post("/skills/custom/{skill_name}/rollback", response_model=CustomSkillContentResponse, summary="Rollback Custom Skill")
 async def rollback_custom_skill(skill_name: str, request: SkillRollbackRequest) -> CustomSkillContentResponse:
    try:
        if not custom_skill_exists(skill_name) and not get_skill_history_file(skill_name).exists():
            raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
        history = read_history(skill_name)
        if not history:
            raise HTTPException(status_code=400, detail=f"Custom skill '{skill_name}' has no history")
        record = history[request.history_index]
        target_content = record.get("prev_content")
        if target_content is None:
            raise HTTPException(status_code=400, detail="Selected history entry has no previous content to roll back to")
        validate_skill_markdown_content(skill_name, target_content)
        scan = await scan_skill_content(target_content, executable=False, location=f"{skill_name}/SKILL.md")
        skill_file = get_custom_skill_file(skill_name)
        current_content = skill_file.read_text(encoding="utf-8") if skill_file.exists() else None
        history_entry = {
            "action": "rollback",
            "author": "human",
            "thread_id": None,
            "file_path": "SKILL.md",
            "prev_content": current_content,
            "new_content": target_content,
            "rollback_from_ts": record.get("ts"),
            "scanner": {"decision": scan.decision, "reason": scan.reason},
        }
        if scan.decision == "block":
            append_history(skill_name, history_entry)
            raise HTTPException(status_code=400, detail=f"Rollback blocked by security scanner: {scan.reason}")
        atomic_write(skill_file, target_content)
        append_history(skill_name, history_entry)
        await refresh_skills_system_prompt_cache_async()
        return await get_custom_skill(skill_name)
    except HTTPException:
        raise
    except IndexError:
        raise HTTPException(status_code=400, detail="history_index is out of range")
    except FileNotFoundError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))
    except Exception as e:
        logger.error("Failed to roll back custom skill %s: %s", skill_name, e, exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to roll back custom skill: {str(e)}")
@router.get(
    "/skills/{skill_name}",
    response_model=SkillResponse,
@@ -344,7 +132,6 @@ async def update_skill(skill_name: str, request: SkillUpdateRequest) -> SkillRes
        logger.info(f"Skills configuration updated and saved to: {config_path}")
        reload_extensions_config()
        await refresh_skills_system_prompt_cache_async()
        skills = load_skills(enabled_only=False)
        updated_skill = next((s for s in skills if s.name == skill_name), None)
@@ -360,3 +147,27 @@ async def update_skill(skill_name: str, request: SkillUpdateRequest) -> SkillRes
    except Exception as e:
        logger.error(f"Failed to update skill {skill_name}: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to update skill: {str(e)}")
@router.post(
    "/skills/install",
    response_model=SkillInstallResponse,
    summary="Install Skill",
    description="Install a skill from a .skill file (ZIP archive) located in the thread's user-data directory.",
 )
 async def install_skill(request: SkillInstallRequest) -> SkillInstallResponse:
    try:
        skill_file_path = resolve_thread_virtual_path(request.thread_id, request.path)
        result = install_skill_from_archive(skill_file_path)
        return SkillInstallResponse(**result)
    except FileNotFoundError as e:
        raise HTTPException(status_code=404, detail=str(e))
    except SkillAlreadyExistsError as e:
        raise HTTPException(status_code=409, detail=str(e))
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Failed to install skill: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to install skill: {str(e)}")
@@ -2,7 +2,6 @@ import json
 import logging
 from fastapi import APIRouter
 from langchain_core.messages import HumanMessage, SystemMessage
 from pydantic import BaseModel, Field
 from deerflow.models import create_chat_model
@@ -107,21 +106,22 @@ async def generate_suggestions(thread_id: str, request: SuggestionsRequest) -> S
    if not conversation:
        return SuggestionsResponse(suggestions=[])
-    system_instruction = (
+    prompt = (
        "You are generating follow-up questions to help the user continue the conversation.\n"
        f"Based on the conversation below, produce EXACTLY {n} short questions the user might ask next.\n"
        "Requirements:\n"
-        "- Questions must be relevant to the preceding conversation.\n"
+        "- Questions must be relevant to the conversation.\n"
        "- Questions must be written in the same language as the user.\n"
        "- Keep each question concise (ideally <= 20 words / <= 40 Chinese characters).\n"
        "- Do NOT include numbering, markdown, or any extra text.\n"
-        "- Output MUST be a JSON array of strings only.\n"
+        "- Output MUST be a JSON array of strings only.\n\n"
        "Conversation:\n"
        f"{conversation}\n"
    )
    user_content = f"Conversation Context:\n{conversation}\n\nGenerate {n} follow-up questions"
    try:
        model = create_chat_model(name=request.model_name, thinking_enabled=False)
-        response = await model.ainvoke([SystemMessage(content=system_instruction), HumanMessage(content=user_content)], config={"run_name": "suggest_agent"})
+        response = model.invoke(prompt)
        raw = _extract_response_text(response.content)
        suggestions = _parse_json_string_list(raw) or []
        cleaned = [s.replace("\n", " ").strip() for s in suggestions if s.strip()]
@@ -38,7 +38,6 @@ class RunCreateRequest(BaseModel):
    command: dict[str, Any] | None = Field(default=None, description="LangGraph Command")
    metadata: dict[str, Any] | None = Field(default=None, description="Run metadata")
    config: dict[str, Any] | None = Field(default=None, description="RunnableConfig overrides")
    context: dict[str, Any] | None = Field(default=None, description="DeerFlow context overrides (model_name, thinking_enabled, etc.)")
    webhook: str | None = Field(default=None, description="Completion callback URL")
    checkpoint_id: str | None = Field(default=None, description="Resume from checkpoint")
    checkpoint: dict[str, Any] | None = Field(default=None, description="Full checkpoint object")
@@ -118,9 +117,8 @@ async def stream_run(thread_id: str, body: RunCreateRequest, request: Request) -
            "Connection": "keep-alive",
            "X-Accel-Buffering": "no",
            # LangGraph Platform includes run metadata in this header.
-            # The SDK uses a greedy regex to extract the run id from this path,
+            # The SDK's _get_run_metadata_from_response() parses it.
-            # so it must point at the canonical run resource without extra suffixes.
+            "Content-Location": (f"/api/threads/{thread_id}/runs/{record.run_id}/stream?thread_id={thread_id}&run_id={record.run_id}"),
            "Content-Location": f"/api/threads/{thread_id}/runs/{record.run_id}",
        },
    )
@@ -488,19 +488,16 @@ async def get_thread(thread_id: str, request: Request) -> ThreadResponse:
            "metadata": {k: v for k, v in ckpt_meta.items() if k not in ("created_at", "updated_at", "step", "source", "writes", "parents")},
        }
-    if record is None:
+    status = _derive_thread_status(checkpoint_tuple) if checkpoint_tuple is not None else record.get("status", "idle")  # type: ignore[union-attr]
        raise HTTPException(status_code=404, detail=f"Thread {thread_id} not found")
    status = _derive_thread_status(checkpoint_tuple) if checkpoint_tuple is not None else record.get("status", "idle")
    checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {} if checkpoint_tuple is not None else {}
    channel_values = checkpoint.get("channel_values", {})
    return ThreadResponse(
        thread_id=thread_id,
        status=status,
-        created_at=str(record.get("created_at", "")),
+        created_at=str(record.get("created_at", "")),  # type: ignore[union-attr]
-        updated_at=str(record.get("updated_at", "")),
+        updated_at=str(record.get("updated_at", "")),  # type: ignore[union-attr]
-        metadata=record.get("metadata", {}),
+        metadata=record.get("metadata", {}),  # type: ignore[union-attr]
        values=serialize_channel_values(channel_values),
    )
@@ -7,9 +7,8 @@ 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 SandboxProvider, get_sandbox_provider
+from deerflow.sandbox.sandbox_provider import get_sandbox_provider
 from deerflow.uploads.manager import (
    PathTraversalError,
    delete_file_safe,
@@ -54,34 +53,6 @@ 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,
@@ -99,12 +70,8 @@ async def upload_files(
    uploaded_files = []
    sandbox_provider = get_sandbox_provider()
-    sync_to_sandbox = not _uses_thread_data_mounts(sandbox_provider)
+    sandbox_id = sandbox_provider.acquire(thread_id)
-    sandbox = None
+    sandbox = sandbox_provider.get(sandbox_id)
    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:
@@ -123,7 +90,7 @@ async def upload_files(
            virtual_path = upload_virtual_path(safe_filename)
-            if sync_to_sandbox and sandbox is not None:
+            if sandbox_id != "local":
                _make_file_sandbox_writable(file_path)
                sandbox.update_file(virtual_path, content)
@@ -138,12 +105,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 auto_convert_documents and file_ext in CONVERTIBLE_EXTENSIONS:
+            if 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 sync_to_sandbox and sandbox is not None:
+                    if sandbox_id != "local":
                        _make_file_sandbox_writable(md_path)
                        sandbox.update_file(md_virtual_path, md_path.read_bytes())
@@ -10,9 +10,7 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
 import re
 import time
 from collections.abc import Mapping
 from typing import Any
 from fastapi import HTTPException, Request
@@ -95,89 +93,25 @@ def normalize_input(raw_input: dict[str, Any] | None) -> dict[str, Any]:
    return raw_input
 _DEFAULT_ASSISTANT_ID = "lead_agent"
 def resolve_agent_factory(assistant_id: str | None):
-    """Resolve the agent factory callable from config.
+    """Resolve the agent factory callable from config."""
    Custom agents are implemented as ``lead_agent`` + an ``agent_name``
    injected into ``configurable`` or ``context`` — see
    :func:`build_run_config`.  All ``assistant_id`` values therefore map to the
    same factory; the routing happens inside ``make_lead_agent`` when it reads
    ``cfg["agent_name"]``.
    """
    from deerflow.agents.lead_agent.agent import make_lead_agent
    if assistant_id and assistant_id != "lead_agent":
        logger.info("assistant_id=%s requested; falling back to lead_agent", assistant_id)
    return make_lead_agent
-def build_run_config(
+def build_run_config(thread_id: str, request_config: dict[str, Any] | None, metadata: dict[str, Any] | None) -> dict[str, Any]:
-    thread_id: str,
+    """Build a RunnableConfig dict for the agent."""
-    request_config: dict[str, Any] | None,
+    configurable = {"thread_id": thread_id}
-    metadata: dict[str, Any] | None,
+    if request_config:
-    *,
+        configurable.update(request_config.get("configurable", {}))
-    assistant_id: str | None = None,
+    config: dict[str, Any] = {"configurable": configurable, "recursion_limit": 100}
 ) -> dict[str, Any]:
    """Build a RunnableConfig dict for the agent.
    When *assistant_id* refers to a custom agent (anything other than
    ``"lead_agent"`` / ``None``), the name is forwarded as ``agent_name`` in
    whichever runtime options container is active: ``context`` for
    LangGraph >= 0.6.0 requests, otherwise ``configurable``.
    ``make_lead_agent`` reads this key to load the matching
    ``agents/<name>/SOUL.md`` and per-agent config — without it the agent
    silently runs as the default lead agent.
    This mirrors the channel manager's ``_resolve_run_params`` logic so that
    the LangGraph Platform-compatible HTTP API and the IM channel path behave
    identically.
    """
    config: dict[str, Any] = {"recursion_limit": 100}
    if request_config:
        # LangGraph >= 0.6.0 introduced ``context`` as the preferred way to
        # pass thread-level data and rejects requests that include both
        # ``configurable`` and ``context``.  If the caller already sends
        # ``context``, honour it and skip our own ``configurable`` dict.
        if "context" in request_config:
            if "configurable" in request_config:
                logger.warning(
                    "build_run_config: client sent both 'context' and 'configurable'; preferring 'context' (LangGraph >= 0.6.0). thread_id=%s, caller_configurable keys=%s",
                    thread_id,
                    list(request_config.get("configurable", {}).keys()),
                )
            context_value = request_config["context"]
            if context_value is None:
                context = {}
            elif isinstance(context_value, Mapping):
                context = dict(context_value)
            else:
                raise ValueError("request config 'context' must be a mapping or null.")
            config["context"] = context
        else:
            configurable = {"thread_id": thread_id}
            configurable.update(request_config.get("configurable", {}))
            config["configurable"] = configurable
        for k, v in request_config.items():
-            if k not in ("configurable", "context"):
+            if k != "configurable":
                config[k] = v
    else:
        config["configurable"] = {"thread_id": thread_id}
    # Inject custom agent name when the caller specified a non-default assistant.
    # Honour an explicit agent_name in the active runtime options container.
    if assistant_id and assistant_id != _DEFAULT_ASSISTANT_ID:
        normalized = assistant_id.strip().lower().replace("_", "-")
        if not normalized or not re.fullmatch(r"[a-z0-9-]+", normalized):
            raise ValueError(f"Invalid assistant_id {assistant_id!r}: must contain only letters, digits, and hyphens after normalization.")
        if "configurable" in config:
            target = config["configurable"]
        elif "context" in config:
            target = config["context"]
        else:
            target = config.setdefault("configurable", {})
        if target is not None and "agent_name" not in target:
            target["agent_name"] = normalized
    if metadata:
        config.setdefault("metadata", {}).update(metadata)
    return config
@@ -299,30 +233,7 @@ async def start_run(
    agent_factory = resolve_agent_factory(body.assistant_id)
    graph_input = normalize_input(body.input)
-    config = build_run_config(thread_id, body.config, body.metadata, assistant_id=body.assistant_id)
+    config = build_run_config(thread_id, body.config, body.metadata)
    # Merge DeerFlow-specific context overrides into configurable.
    # The ``context`` field is a custom extension for the langgraph-compat layer
    # that carries agent configuration (model_name, thinking_enabled, etc.).
    # Only agent-relevant keys are forwarded; unknown keys (e.g. thread_id) are ignored.
    context = getattr(body, "context", None)
    if context:
        _CONTEXT_CONFIGURABLE_KEYS = {
            "model_name",
            "mode",
            "thinking_enabled",
            "reasoning_effort",
            "is_plan_mode",
            "subagent_enabled",
            "max_concurrent_subagents",
            "agent_name",
            "is_bootstrap",
        }
        configurable = config.setdefault("configurable", {})
        for key in _CONTEXT_CONFIGURABLE_KEYS:
            if key in context:
                configurable.setdefault(key, context[key])
    stream_modes = normalize_stream_modes(body.stream_mode)
    task = asyncio.create_task(
@@ -364,9 +275,8 @@ async def sse_consumer(
    - ``cancel``: abort the background task on client disconnect.
    - ``continue``: let the task run; events are discarded.
    """
    last_event_id = request.headers.get("Last-Event-ID")
    try:
-        async for entry in bridge.subscribe(record.run_id, last_event_id=last_event_id):
+        async for entry in bridge.subscribe(record.run_id):
            if await request.is_disconnected():
                break
@@ -19,78 +19,24 @@ import asyncio
 import logging
 from dotenv import load_dotenv
 from langchain_core.messages import HumanMessage
-try:
+from deerflow.agents import make_lead_agent
    from prompt_toolkit import PromptSession
    from prompt_toolkit.history import InMemoryHistory
    _HAS_PROMPT_TOOLKIT = True
 except ImportError:
    _HAS_PROMPT_TOOLKIT = False
 load_dotenv()
-_LOG_FMT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+logging.basicConfig(
-_LOG_DATEFMT = "%Y-%m-%d %H:%M:%S"
+    level=logging.INFO,
-
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-
+    datefmt="%Y-%m-%d %H:%M:%S",
-def _logging_level_from_config(name: str) -> int:
+)
    """Map ``config.yaml`` ``log_level`` string to a ``logging`` level constant."""
    mapping = logging.getLevelNamesMapping()
    return mapping.get((name or "info").strip().upper(), logging.INFO)
 def _setup_logging(log_level: str) -> None:
    """Send application logs to ``debug.log`` at *log_level*; do not print them on the console.
    Idempotent: any pre-existing handlers on the root logger (e.g. installed by
    ``logging.basicConfig`` in transitively imported modules) are removed so the
    debug session output only lands in ``debug.log``.
    """
    level = _logging_level_from_config(log_level)
    root = logging.root
    for h in list(root.handlers):
        root.removeHandler(h)
        h.close()
    root.setLevel(level)
    file_handler = logging.FileHandler("debug.log", mode="a", encoding="utf-8")
    file_handler.setLevel(level)
    file_handler.setFormatter(logging.Formatter(_LOG_FMT, datefmt=_LOG_DATEFMT))
    root.addHandler(file_handler)
 def _update_logging_level(log_level: str) -> None:
    """Update the root logger and existing handlers to *log_level*."""
    level = _logging_level_from_config(log_level)
    root = logging.root
    root.setLevel(level)
    for handler in root.handlers:
        handler.setLevel(level)
 async def main():
    # Install file logging first so warnings emitted while loading config do not
    # leak onto the interactive terminal via Python's lastResort handler.
    _setup_logging("info")
    from deerflow.config import get_app_config
    app_config = get_app_config()
    _update_logging_level(app_config.log_level)
    # Delay the rest of the deerflow imports until *after* logging is installed
    # so that any import-time side effects (e.g. deerflow.agents starts a
    # background skill-loader thread on import) emit logs to debug.log instead
    # of leaking onto the interactive terminal via Python's lastResort handler.
    from langchain_core.messages import HumanMessage
    from langgraph.runtime import Runtime
    from deerflow.agents import make_lead_agent
    from deerflow.mcp import initialize_mcp_tools
    # Initialize MCP tools at startup
    try:
        from deerflow.mcp import initialize_mcp_tools
        await initialize_mcp_tools()
    except Exception as e:
        print(f"Warning: Failed to initialize MCP tools: {e}")
@@ -106,27 +52,16 @@ async def main():
        }
    }
    runtime = Runtime(context={"thread_id": config["configurable"]["thread_id"]})
    config["configurable"]["__pregel_runtime"] = runtime
    agent = make_lead_agent(config)
    session = PromptSession(history=InMemoryHistory()) if _HAS_PROMPT_TOOLKIT else None
    print("=" * 50)
    print("Lead Agent Debug Mode")
    print("Type 'quit' or 'exit' to stop")
    print(f"Logs: debug.log (log_level={app_config.log_level})")
    if not _HAS_PROMPT_TOOLKIT:
        print("Tip: `uv sync --group dev` to enable arrow-key & history support")
    print("=" * 50)
    while True:
        try:
-            if session:
+            user_input = input("\nYou: ").strip()
                user_input = (await session.prompt_async("\nYou: ")).strip()
            else:
                user_input = input("\nYou: ").strip()
            if not user_input:
                continue
            if user_input.lower() in ("quit", "exit"):
@@ -135,15 +70,15 @@ async def main():
            # Invoke the agent
            state = {"messages": [HumanMessage(content=user_input)]}
-            result = await agent.ainvoke(state, config=config)
+            result = await agent.ainvoke(state, config=config, context={"thread_id": "debug-thread-001"})
            # Print the response
            if result.get("messages"):
                last_message = result["messages"][-1]
                print(f"\nAgent: {last_message.content}")
-        except (KeyboardInterrupt, EOFError):
+        except KeyboardInterrupt:
-            print("\nGoodbye!")
+            print("\nInterrupted. Goodbye!")
            break
        except Exception as e:
            print(f"\nError: {e}")
@@ -86,7 +86,6 @@ Content-Type: application/json
    ]
  },
  "config": {
    "recursion_limit": 100,
    "configurable": {
      "model_name": "gpt-4",
      "thinking_enabled": false,
@@ -101,21 +100,6 @@ Content-Type: application/json
 - Use: `values`, `messages-tuple`, `custom`, `updates`, `events`, `debug`, `tasks`, `checkpoints`
 - Do not use: `tools` (deprecated/invalid in current `langgraph-api` and will trigger schema validation errors)
 **Recursion Limit:**
 `config.recursion_limit` caps the number of graph steps LangGraph will execute
 in a single run. The `/api/langgraph/*` endpoints go straight to the LangGraph
 server and therefore inherit LangGraph's native default of **25**, which is
 too low for plan-mode or subagent-heavy runs — the agent typically errors out
 with `GraphRecursionError` after the first round of subagent results comes
 back, before the lead agent can synthesize the final answer.
 DeerFlow's own Gateway and IM-channel paths mitigate this by defaulting to
 `100` in `build_run_config` (see `backend/app/gateway/services.py`), but
 clients calling the LangGraph API directly must set `recursion_limit`
 explicitly in the request body. `100` matches the Gateway default and is a
 safe starting point; increase it if you run deeply nested subagent graphs.
 **Configurable Options:**
 - `model_name` (string): Override the default model
 - `thinking_enabled` (boolean): Enable extended thinking for supported models
@@ -642,14 +626,6 @@ curl -X POST http://localhost:2026/api/langgraph/threads/abc123/runs \
  -H "Content-Type: application/json" \
  -d '{
    "input": {"messages": [{"role": "user", "content": "Hello"}]},
-    "config": {
+    "config": {"configurable": {"model_name": "gpt-4"}}
      "recursion_limit": 100,
      "configurable": {"model_name": "gpt-4"}
    }
  }'
 ```
 > The `/api/langgraph/*` endpoints bypass DeerFlow's Gateway and inherit
 > LangGraph's native `recursion_limit` default of 25, which is too low for
 > plan-mode or subagent runs. Set `config.recursion_limit` explicitly — see
 > the [Create Run](#create-run) section for details.
@@ -199,7 +199,7 @@ class ThreadState(AgentState):
 │   Built-in Tools    │  │  Configured Tools   │  │     MCP Tools       │
 │  (packages/harness/deerflow/tools/)       │  │  (config.yaml)      │  │  (extensions.json)  │
 ├─────────────────────┤  ├─────────────────────┤  ├─────────────────────┤
-│ - present_files     │  │ - web_search        │  │ - github            │
+│ - present_file      │  │ - web_search        │  │ - github            │
 │ - ask_clarification │  │ - web_fetch         │  │ - filesystem        │
 │ - view_image        │  │ - bash              │  │ - postgres          │
 │                     │  │ - read_file         │  │ - brave-search      │
@@ -248,7 +248,7 @@ def after_agent(self, state: TitleMiddlewareState, runtime: Runtime) -> dict | N
 - [`packages/harness/deerflow/agents/thread_state.py`](../packages/harness/deerflow/agents/thread_state.py) - ThreadState 定义
 - [`packages/harness/deerflow/agents/middlewares/title_middleware.py`](../packages/harness/deerflow/agents/middlewares/title_middleware.py) - TitleMiddleware 实现
 - [`packages/harness/deerflow/config/title_config.py`](../packages/harness/deerflow/config/title_config.py) - 配置管理
- [`config.yaml`](../../config.example.yaml) - 配置文件
+- [`config.yaml`](../config.yaml) - 配置文件
 - [`packages/harness/deerflow/agents/lead_agent/agent.py`](../packages/harness/deerflow/agents/lead_agent/agent.py) - Middleware 注册
 ## 参考资料
@@ -192,8 +192,8 @@ tools:
 ```
 **Built-in Tools**:
- `web_search` - Search the web (DuckDuckGo, Tavily, Exa, InfoQuest, Firecrawl)
+- `web_search` - Search the web (Tavily)
- `web_fetch` - Fetch web pages (Jina AI, Exa, InfoQuest, Firecrawl)
+- `web_fetch` - Fetch web pages (Jina AI)
 - `ls` - List directory contents
 - `read_file` - Read file contents
 - `write_file` - Write file contents
@@ -257,8 +257,6 @@ sandbox:
      read_only: false
 ```
 When you configure `sandbox.mounts`, DeerFlow exposes those `container_path` values in the agent prompt so the agent can discover and operate on mounted directories directly instead of assuming everything must live under `/mnt/user-data`.
 ### Skills
 Configure the skills directory for specialized workflows:
@@ -278,12 +276,6 @@ skills:
 - Skills are automatically discovered and loaded
 - Available in both local and Docker sandbox via path mapping
 **Per-Agent Skill Filtering**:
 Custom agents can restrict which skills they load by defining a `skills` field in their `config.yaml` (located at `workspace/agents/<agent_name>/config.yaml`):
 - **Omitted or `null`**: Loads all globally enabled skills (default fallback).
 - **`[]` (empty list)**: Disables all skills for this specific agent.
 - **`["skill-name"]`**: Loads only the explicitly specified skills.
 ### Title Generation
 Automatic conversation title generation:
@@ -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}
 ## 支持的文档格式
-以下格式在显式启用 `uploads.auto_convert_documents: true` 时会自动转换为 Markdown：
+以下格式会自动转换为 Markdown：
 - PDF (`.pdf`)
 - PowerPoint (`.ppt`, `.pptx`)
 - Excel (`.xls`, `.xlsx`)
@@ -94,8 +94,6 @@ DELETE /api/threads/{thread_id}/uploads/{filename}
 转换后的 Markdown 文件会保存在同一目录下，文件名为原文件名 + `.md` 扩展名。
 默认情况下，自动转换是关闭的，以避免在网关主机上对不受信任的 Office/PDF 上传执行解析。只有在受信任部署中明确接受此风险时，才应将 `uploads.auto_convert_documents` 设置为 `true`。
 ## Agent 集成
 ### 自动文件列举
@@ -209,7 +207,6 @@ backend/.deer-flow/threads/
 - 最大文件大小：100MB（可在 nginx.conf 中配置 `client_max_body_size`）
 - 文件名安全性：系统会自动验证文件路径，防止目录遍历攻击
 - 线程隔离：每个线程的上传文件相互隔离，无法跨线程访问
 - 自动文档转换默认关闭；如需启用，需在 `config.yaml` 中显式设置 `uploads.auto_convert_documents: true`
 ## 技术实现
@@ -296,7 +296,7 @@ These are the tool names your provider will see in `request.tool_name`:
 | `web_search` | Web search query |
 | `web_fetch` | Fetch URL content |
 | `image_search` | Image search |
-| `present_files` | Present file to user |
+| `present_file` | Present file to user |
 | `view_image` | Display image |
 | `ask_clarification` | Ask user a question |
 | `task` | Delegate to subagent |
@@ -45,41 +45,6 @@ Example:
 }
 ```
 ## Custom Tool Interceptors
 You can register custom interceptors that run before every MCP tool call. This is useful for injecting per-request headers (e.g., user auth tokens from the LangGraph execution context), logging, or metrics.
 Declare interceptors in `extensions_config.json` using the `mcpInterceptors` field:
 ```json
 {
  "mcpInterceptors": [
    "my_package.mcp.auth:build_auth_interceptor"
  ],
  "mcpServers": { ... }
 }
 ```
 Each entry is a Python import path in `module:variable` format (resolved via `resolve_variable`). The variable must be a **no-arg builder function** that returns an async interceptor compatible with `MultiServerMCPClient`’s `tool_interceptors` interface, or `None` to skip.
 Example interceptor that injects auth headers from LangGraph metadata:
 ```python
 def build_auth_interceptor():
    async def interceptor(request, handler):
        from langgraph.config import get_config
        metadata = get_config().get("metadata", {})
        headers = dict(request.headers or {})
        if token := metadata.get("auth_token"):
            headers["X-Auth-Token"] = token
        return await handler(request.override(headers=headers))
    return interceptor
 ```
 - A single string value is accepted and normalized to a one-element list.
 - Invalid paths or builder failures are logged as warnings without blocking other interceptors.
 - The builder return value must be `callable`; non-callable values are skipped with a warning.
 ## How It Works
 MCP servers expose tools that are automatically discovered and integrated into DeerFlow’s agent system at runtime. Once enabled, these tools become available to agents without additional code changes.
@@ -15,7 +15,6 @@ This directory contains detailed documentation for the DeerFlow backend.
 | Document | Description |
 |----------|-------------|
 | [STREAMING.md](STREAMING.md) | Token-level streaming design: Gateway vs DeerFlowClient paths, `stream_mode` semantics, per-id dedup |
 | [FILE_UPLOAD.md](FILE_UPLOAD.md) | File upload functionality |
 | [PATH_EXAMPLES.md](PATH_EXAMPLES.md) | Path types and usage examples |
 | [summarization.md](summarization.md) | Context summarization feature |
@@ -48,7 +47,6 @@ docs/
 ├── PATH_EXAMPLES.md           # Path usage examples
 ├── summarization.md           # Summarization feature
 ├── plan_mode_usage.md         # Plan mode feature
 ├── STREAMING.md               # Token-level streaming design
 ├── AUTO_TITLE_GENERATION.md   # Title generation
 ├── TITLE_GENERATION_IMPLEMENTATION.md  # Title implementation details
 └── TODO.md                    # Roadmap and issues
@@ -1,351 +0,0 @@
 # DeerFlow 流式输出设计
 本文档解释 DeerFlow 是如何把 LangGraph agent 的事件流端到端送到两类消费者（HTTP 客户端、嵌入式 Python 调用方）的：两条路径为什么**必须**并存、它们各自的契约是什么、以及设计里那些 non-obvious 的不变式。
 ---
 ## TL;DR
 - DeerFlow 有**两条并行**的流式路径：**Gateway 路径**（async / HTTP SSE / JSON 序列化）服务浏览器和 IM 渠道；**DeerFlowClient 路径**（sync / in-process / 原生 LangChain 对象）服务 Jupyter、脚本、测试。它们**无法合并**——消费者模型不同。
 - 两条路径都从 `create_agent()` 工厂出发，核心都是订阅 LangGraph 的 `stream_mode=["values", "messages", "custom"]`。`values` 是节点级 state 快照，`messages` 是 LLM token 级 delta，`custom` 是显式 `StreamWriter` 事件。**这三种模式不是详细程度的梯度，是三个独立的事件源**，要 token 流就必须显式订阅 `messages`。
 - 嵌入式 client 为每个 `stream()` 调用维护三个 `set[str]`：`seen_ids` / `streamed_ids` / `counted_usage_ids`。三者看起来相似但管理**三个独立的不变式**，不能合并。
 ---
 ## 为什么有两条流式路径
 两条路径服务的消费者模型根本不同：
 | 维度 | Gateway 路径 | DeerFlowClient 路径 |
 |---|---|---|
 | 入口 | FastAPI `/runs/stream` endpoint | `DeerFlowClient.stream(message)` |
 | 触发层 | `runtime/runs/worker.py::run_agent` | `packages/harness/deerflow/client.py::DeerFlowClient.stream` |
 | 执行模型 | `async def` + `agent.astream()` | sync generator + `agent.stream()` |
 | 事件传输 | `StreamBridge`（asyncio Queue）+ `sse_consumer` | 直接 `yield` |
 | 序列化 | `serialize(chunk)` → 纯 JSON dict，匹配 LangGraph Platform wire 格式 | `StreamEvent.data`，携带原生 LangChain 对象 |
 | 消费者 | 前端 `useStream` React hook、飞书/Slack/Telegram channel、LangGraph SDK 客户端 | Jupyter notebook、集成测试、内部 Python 脚本 |
 | 生命周期管理 | `RunManager`：run_id 跟踪、disconnect 语义、multitask 策略、heartbeat | 无；函数返回即结束 |
 | 断连恢复 | `Last-Event-ID` SSE 重连 | 无需要 |
 **两条路径的存在是 DRY 的刻意妥协**：Gateway 的全部基础设施（async + Queue + JSON + RunManager）**都是为了跨网络边界把事件送给 HTTP 消费者**。当生产者（agent）和消费者（Python 调用栈）在同一个进程时，这整套东西都是纯开销。
 ### 为什么不能让 DeerFlowClient 复用 Gateway
 曾经考虑过三种复用方案，都被否决：
 1. **让 `client.stream()` 变成 `async def client.astream()`**  
   breaking change。用户用不上的 `async for` / `asyncio.run()` 要硬塞进 Jupyter notebook 和同步脚本。DeerFlowClient 的一大卖点（"把 agent 当普通函数调用"）直接消失。
 2. **在 `client.stream()` 内部起一个独立事件循环线程，用 `StreamBridge` 在 sync/async 之间做桥接**  
   引入线程池、队列、信号量。为了"消除重复"，把**复杂度**代替代码行数引进来。是典型的"wrong abstraction"——开销高于复用收益。
 3. **让 `run_agent` 自己兼容 sync mode**  
   给 Gateway 加一条用不到的死分支，污染 worker.py 的焦点。
 所以两条路径的事件处理逻辑会**相似但不共享**。这是刻意设计，不是疏忽。
 ---
 ## LangGraph `stream_mode` 三层语义
 LangGraph 的 `agent.stream(stream_mode=[...])` 是**多路复用**接口：一次订阅多个 mode，每个 mode 是一个独立的事件源。三种核心 mode：
 ```mermaid
 flowchart LR
    classDef values fill:#B8C5D1,stroke:#5A6B7A,color:#2C3E50
    classDef messages fill:#C9B8A8,stroke:#7A6B5A,color:#2C3E50
    classDef custom fill:#B5C4B1,stroke:#5A7A5A,color:#2C3E50
    subgraph LG["LangGraph agent graph"]
        direction TB
        Node1["node: LLM call"]
        Node2["node: tool call"]
        Node3["node: reducer"]
    end
    LG -->|"每个节点完成后"| V["values: 完整 state 快照"]
    Node1 -->|"LLM 每产生一个 token"| M["messages: (AIMessageChunk, meta)"]
    Node1 -->|"StreamWriter.write()"| C["custom: 任意 dict"]
    class V values
    class M messages
    class C custom
 ```
 | Mode | 发射时机 | Payload | 粒度 |
 |---|---|---|---|
 | `values` | 每个 graph 节点完成后 | 完整 state dict（title、messages、artifacts）| 节点级 |
 | `messages` | LLM 每次 yield 一个 chunk；tool 节点完成时 | `(AIMessageChunk \| ToolMessage, metadata_dict)` | token 级 |
 | `custom` | 用户代码显式调用 `StreamWriter.write()` | 任意 dict | 应用定义 |
 ### 两套命名的由来
 同一件事在**三个协议层**有三个名字：
 ```
 Application                    HTTP / SSE                    LangGraph Graph
 ┌──────────────┐               ┌──────────────┐              ┌──────────────┐
 │ frontend     │               │ LangGraph    │              │ agent.astream│
 │ useStream    │──"messages-   │ Platform SDK │──"messages"──│ graph.astream│
 │ Feishu IM    │   tuple"──────│ HTTP wire    │              │              │
 └──────────────┘               └──────────────┘              └──────────────┘
 ```
 - **Graph 层**（`agent.stream` / `agent.astream`）：LangGraph Python 直接 API，mode 叫 **`"messages"`**。
 - **Platform SDK 层**（`langgraph-sdk` HTTP client）：跨进程 HTTP 契约，mode 叫 **`"messages-tuple"`**。
 - **Gateway worker** 显式做翻译：`if m == "messages-tuple": lg_modes.append("messages")`（`runtime/runs/worker.py:117-121`）。
 **后果**：`DeerFlowClient.stream()` 直接调 `agent.stream()`（Graph 层），所以必须传 `"messages"`。`app/channels/manager.py` 通过 `langgraph-sdk` 走 HTTP SDK，所以传 `"messages-tuple"`。**这两个字符串不能互相替代**，也不能抽成"一个共享常量"——它们是不同协议层的 type alias，共享只会让某一层说不是它母语的话。
 ---
 ## Gateway 路径：async + HTTP SSE
 ```mermaid
 sequenceDiagram
    participant Client as HTTP Client
    participant API as FastAPI<br/>thread_runs.py
    participant Svc as services.py<br/>start_run
    participant Worker as worker.py<br/>run_agent (async)
    participant Bridge as StreamBridge<br/>(asyncio.Queue)
    participant Agent as LangGraph<br/>agent.astream
    participant SSE as sse_consumer
    Client->>API: POST /runs/stream
    API->>Svc: start_run(body)
    Svc->>Bridge: create bridge
    Svc->>Worker: asyncio.create_task(run_agent(...))
    Svc-->>API: StreamingResponse(sse_consumer)
    API-->>Client: event-stream opens
    par worker (producer)
        Worker->>Agent: astream(stream_mode=lg_modes)
        loop 每个 chunk
            Agent-->>Worker: (mode, chunk)
            Worker->>Bridge: publish(run_id, event, serialize(chunk))
        end
        Worker->>Bridge: publish_end(run_id)
    and sse_consumer (consumer)
        SSE->>Bridge: subscribe(run_id)
        loop 每个 event
            Bridge-->>SSE: StreamEvent
            SSE-->>Client: "event: <name>\ndata: <json>\n\n"
        end
    end
 ```
 关键组件：
 - `runtime/runs/worker.py::run_agent` — 在 `asyncio.Task` 里跑 `agent.astream()`，把每个 chunk 通过 `serialize(chunk, mode=mode)` 转成 JSON，再 `bridge.publish()`。
 - `runtime/stream_bridge` — 抽象 Queue。`publish/subscribe` 解耦生产者和消费者，支持 `Last-Event-ID` 重连、心跳、多订阅者 fan-out。
 - `app/gateway/services.py::sse_consumer` — 从 bridge 订阅，格式化为 SSE wire 帧。
 - `runtime/serialization.py::serialize` — mode-aware 序列化；`messages` mode 下 `serialize_messages_tuple` 把 `(chunk, metadata)` 转成 `[chunk.model_dump(), metadata]`。
 **`StreamBridge` 的存在价值**：当生产者（`run_agent` 任务）和消费者（HTTP 连接）在不同的 asyncio task 里运行时，需要一个可以跨 task 传递事件的中介。Queue 同时还承担断连重连的 buffer 和多订阅者的 fan-out。
 ---
 ## DeerFlowClient 路径：sync + in-process
 ```mermaid
 sequenceDiagram
    participant User as Python caller
    participant Client as DeerFlowClient.stream
    participant Agent as LangGraph<br/>agent.stream (sync)
    User->>Client: for event in client.stream("hi"):
    Client->>Agent: stream(stream_mode=["values","messages","custom"])
    loop 每个 chunk
        Agent-->>Client: (mode, chunk)
        Client->>Client: 分发 mode<br/>构建 StreamEvent
        Client-->>User: yield StreamEvent
    end
    Client-->>User: yield StreamEvent(type="end")
 ```
 对比之下，sync 路径的每个环节都是显著更少的移动部件：
 - 没有 `RunManager` —— 一次 `stream()` 调用对应一次生命周期，无需 run_id。
 - 没有 `StreamBridge` —— 直接 `yield`，生产和消费在同一个 Python 调用栈，不需要跨 task 中介。
 - 没有 JSON 序列化 —— `StreamEvent.data` 直接装原生 LangChain 对象（`AIMessage.content`、`usage_metadata` 的 `UsageMetadata` TypedDict）。Jupyter 用户拿到的是真正的类型，不是匿名 dict。
 - 没有 asyncio —— 调用者可以直接 `for event in ...`，不必写 `async for`。
 ---
 ## 消费语义：delta vs cumulative
 LangGraph `messages` mode 给出的是 **delta**：每个 `AIMessageChunk.content` 只包含这一次新 yield 的 token，**不是**从头的累计文本。
 这个语义和 LangChain 的 `fs2 Stream` 风格一致：**上游发增量，下游负责累加**。Gateway 路径里前端 `useStream` React hook 自己维护累加器；DeerFlowClient 路径里 `chat()` 方法替调用者做累加。
 ### `DeerFlowClient.chat()` 的 O(n) 累加器
 ```python
 chunks: dict[str, list[str]] = {}
 last_id: str = ""
 for event in self.stream(message, thread_id=thread_id, **kwargs):
    if event.type == "messages-tuple" and event.data.get("type") == "ai":
        msg_id = event.data.get("id") or ""
        delta = event.data.get("content", "")
        if delta:
            chunks.setdefault(msg_id, []).append(delta)
            last_id = msg_id
 return "".join(chunks.get(last_id, ()))
 ```
 **为什么不是 `buffers[id] = buffers.get(id,"") + delta`**：CPython 的字符串 in-place concat 优化仅在 refcount=1 且 LHS 是 local name 时生效；这里字符串存在 dict 里被 reassign，优化失效，每次都是 O(n) 拷贝 → 总体 O(n²)。实测 50 KB / 5000 chunk 的回复要 100-300ms 纯拷贝开销。用 `list` + `"".join()` 是 O(n)。
 ---
 ## 三个 id set 为什么不能合并
 `DeerFlowClient.stream()` 在一次调用生命周期内维护三个 `set[str]`：
 ```python
 seen_ids: set[str] = set()           # values 路径内部 dedup
 streamed_ids: set[str] = set()       # messages → values 跨模式 dedup
 counted_usage_ids: set[str] = set()  # usage_metadata 幂等计数
 ```
 乍看像是"三份几乎一样的东西"，实际每个管**不同的不变式**。
 | Set | 负责的不变式 | 被谁填充 | 被谁查询 |
 |---|---|---|---|
 | `seen_ids` | 连续两个 `values` 快照里同一条 message 只生成一个 `messages-tuple` 事件 | values 分支每处理一条消息就加入 | values 分支处理下一条消息前检查 |
 | `streamed_ids` | 如果一条消息已经通过 `messages` 模式 token 级流过，values 快照到达时**不要**再合成一次完整 `messages-tuple` | messages 分支每发一个 AI/tool 事件就加入 | values 分支看到消息时检查 |
 | `counted_usage_ids` | 同一个 `usage_metadata` 在 messages 末尾 chunk 和 values 快照的 final AIMessage 里各带一份，**累计总量只算一次** | `_account_usage()` 每次接受 usage 就加入 | `_account_usage()` 每次调用时检查 |
 ### 为什么不能只用一个 set
 关键观察：**同一个 message id 在这三个 set 里的加入时机不同**。
 ```mermaid
 sequenceDiagram
    participant M as messages mode
    participant V as values mode
    participant SS as streamed_ids
    participant SU as counted_usage_ids
    participant SE as seen_ids
    Note over M: 第一个 AI text chunk 到达
    M->>SS: add(msg_id)
    Note over M: 最后一个 chunk 带 usage
    M->>SU: add(msg_id)
    Note over V: snapshot 到达，包含同一条 AI message
    V->>SE: add(msg_id)
    V->>SS: 查询 → 已存在，跳过文本合成
    V->>SU: 查询 → 已存在，不重复计数
 ```
 - `seen_ids` **永远在 values 快照到达时**加入，所以它是 "values 已处理" 的标记。一条只出现在 messages 流里的消息（罕见但可能），`seen_ids` 里永远没有它。
 - `streamed_ids` **在 messages 流的第一个有效事件时**加入。一条只通过 values 快照到达的非 AI 消息（HumanMessage、被 truncate 的 tool 消息），`streamed_ids` 里永远没有它。
 - `counted_usage_ids` **只在看到非空 `usage_metadata` 时**加入。一条完全没有 usage 的消息（tool message、错误消息）永远不会进去。
 **集合包含关系**：`counted_usage_ids ⊆ (streamed_ids ∪ seen_ids)` 大致成立，但**不是严格子集**，因为一条消息可以在 messages 模式流完 text 但**在最后那个带 usage 的 chunk 之前**就被 values snapshot 赶上——此时它已经在 `streamed_ids` 里，但还不在 `counted_usage_ids` 里。把它们合并成一个 dict-of-flags 会让这个微妙的时序依赖**从类型系统里消失**，变成注释里的一句话。三个独立的 set 把不变式显式化了：每个 set 名对应一个可以口头回答的问题。
 ---
 ## 端到端：一次真实对话的事件时序
 假设调用 `client.stream("Count from 1 to 15")`，LLM 给出 "one\ntwo\n...\nfifteen"（88 字符），tokenizer 把它拆成 ~35 个 BPE chunk。下面是事件到达序列的精简版：
 ```mermaid
 sequenceDiagram
    participant U as User
    participant C as DeerFlowClient
    participant A as LangGraph<br/>agent.stream
    U->>C: stream("Count ... 15")
    C->>A: stream(mode=["values","messages","custom"])
    A-->>C: ("values", {messages: [HumanMessage]})
    C-->>U: StreamEvent(type="values", ...)
    Note over A,C: LLM 开始 yield token
    loop 35 次，约 476ms
        A-->>C: ("messages", (AIMessageChunk(content="ele"), meta))
        C->>C: streamed_ids.add(ai-1)
        C-->>U: StreamEvent(type="messages-tuple",<br/>data={type:ai, content:"ele", id:ai-1})
    end
    Note over A: LLM finish_reason=stop，最后一个 chunk 带 usage
    A-->>C: ("messages", (AIMessageChunk(content="", usage_metadata={...}), meta))
    C->>C: counted_usage_ids.add(ai-1)<br/>(无文本，不 yield)
    A-->>C: ("values", {messages: [..., AIMessage(complete)]})
    C->>C: ai-1 in streamed_ids → 跳过合成
    C->>C: 捕获 usage (已在 counted_usage_ids，no-op)
    C-->>U: StreamEvent(type="values", ...)
    C-->>U: StreamEvent(type="end", data={usage:{...}})
 ```
 关键观察：
 1. 用户看到 **35 个 messages-tuple 事件**，跨越约 476ms，每个事件带一个 token delta 和同一个 `id=ai-1`。
 2. 最后一个 `values` 快照里的 `AIMessage` **不会**再触发一个完整的 `messages-tuple` 事件——因为 `ai-1 in streamed_ids` 跳过了合成。
 3. `end` 事件里的 `usage` 正好等于那一份 cumulative usage，**不是它的两倍**——`counted_usage_ids` 在 messages 末尾 chunk 上已经吸收了，values 分支的重复访问是 no-op。
 4. 消费者拿到的 `content` 是**增量**："ele" 只包含 3 个字符，不是 "one\ntwo\n...ele"。想要完整文本要按 `id` 累加，`chat()` 已经帮你做了。
 ---
 ## 为什么这个设计容易出 bug，以及测试策略
 本文档的直接起因是 bytedance/deer-flow#1969：`DeerFlowClient.stream()` 原本只订阅 `["values", "custom"]`，**漏了 `"messages"`**。结果 `client.stream("hello")` 等价于一次性返回，视觉上和 `chat()` 没区别。
 这类 bug 有三个结构性原因：
 1. **多协议层命名**：`messages` / `messages-tuple` / HTTP SSE `messages` 是同一概念的三个名字。在其中一层出错不会在另外两层报错。
 2. **多消费者模型**：Gateway 和 DeerFlowClient 是两套独立实现，**没有单一的"订阅哪些 mode"的 single source of truth**。前者订阅对了不代表后者也订阅对了。
 3. **mock 测试绕开了真实路径**：老测试用 `agent.stream.return_value = iter([dict_chunk, ...])` 喂 values 形状的 dict 模拟 state 快照。这样构造的输入**永远不会进入 `messages` mode 分支**，所以即使 `stream_mode` 里少一个元素，CI 依然全绿。
 ### 防御手段
 真正的防线是**显式断言 "messages" mode 被订阅 + 用真实 chunk shape mock**：
 ```python
 # tests/test_client.py::test_messages_mode_emits_token_deltas
 agent.stream.return_value = iter([
    ("messages", (AIMessageChunk(content="Hel", id="ai-1"), {})),
    ("messages", (AIMessageChunk(content="lo ", id="ai-1"), {})),
    ("messages", (AIMessageChunk(content="world!", id="ai-1"), {})),
    ("values", {"messages": [HumanMessage(...), AIMessage(content="Hello world!", id="ai-1")]}),
 ])
 # ...
 assert [e.data["content"] for e in ai_text_events] == ["Hel", "lo ", "world!"]
 assert len(ai_text_events) == 3  # values snapshot must NOT re-synthesize
 assert "messages" in agent.stream.call_args.kwargs["stream_mode"]
 ```
 **为什么这比"抽一个共享常量"更有效**：共享常量只能保证"用它的人写对字符串"，但新增消费者的人可能根本不知道常量在哪。行为断言强制任何改动都要穿过**实际执行路径**，改回 `["values", "custom"]` 会立刻让 `assert "messages" in ...` 失败。
 ### 活体信号：BPE 子词边界
 回归的最终验证是让真实 LLM 数 1-15，然后看是否能在输出里看到 tokenizer 的子词切分：
 ```
 [5.460s] 'ele' / 'ven'      eleven 被拆成两个 token
 [5.508s] 'tw'  / 'elve'     twelve 拆两个
 [5.568s] 'th'  / 'irteen'   thirteen 拆两个
 [5.623s] 'four'/ 'teen'     fourteen 拆两个
 [5.677s] 'f'   / 'if' / 'teen'  fifteen 拆三个
 ```
 子词切分是 tokenizer 的外部事实，**无法伪造**。能看到它就说明数据流**逐 chunk** 地穿过了整条管道，没有被任何中间层缓冲成整段。这种"活体信号"在流式系统里是比单元测试更高置信度的证据。
 ---
 ## 相关源码定位
 | 关心什么 | 看这里 |
 |---|---|
 | DeerFlowClient 嵌入式流 | `packages/harness/deerflow/client.py::DeerFlowClient.stream` |
 | `chat()` 的 delta 累加器 | `packages/harness/deerflow/client.py::DeerFlowClient.chat` |
 | Gateway async 流 | `packages/harness/deerflow/runtime/runs/worker.py::run_agent` |
 | HTTP SSE 帧输出 | `app/gateway/services.py::sse_consumer` / `format_sse` |
 | 序列化到 wire 格式 | `packages/harness/deerflow/runtime/serialization.py` |
 | LangGraph mode 命名翻译 | `packages/harness/deerflow/runtime/runs/worker.py:117-121` |
 | 飞书渠道的增量卡片更新 | `app/channels/manager.py::_handle_streaming_chat` |
 | Channels 自带的 delta/cumulative 防御性累加 | `app/channels/manager.py::_merge_stream_text` |
 | Frontend useStream 支持的 mode 集合 | `frontend/src/core/api/stream-mode.ts` |
 | 核心回归测试 | `backend/tests/test_client.py::TestStream::test_messages_mode_emits_token_deltas` |
@@ -30,7 +30,7 @@
 ### 2. 配置文件
-#### [`config.yaml`](../../config.example.yaml)
+#### [`config.yaml`](../config.yaml)
 - ✅ 添加 title 配置段：
 ```yaml
 title:
@@ -51,7 +51,7 @@ title:
 - ✅ 故障排查指南
 - ✅ State vs Metadata 对比
-#### [`TODO.md`](TODO.md)
+#### [`BACKEND_TODO.md`](../BACKEND_TODO.md)
 - ✅ 添加功能完成记录
 ### 4. 测试
@@ -11,7 +11,6 @@
 - [x] Add Plan Mode with TodoList middleware
 - [x] Add vision model support with ViewImageMiddleware
 - [x] Skills system with SKILL.md format
 - [x] Replace `time.sleep(5)` with `asyncio.sleep()` in `packages/harness/deerflow/tools/builtins/task_tool.py` (subagent polling)
 ## Planned Features
@@ -22,9 +21,10 @@
 - [ ] Support for more document formats in upload
 - [ ] Skill marketplace / remote skill installation
 - [ ] 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 `time.sleep(5)` with `asyncio.sleep()` in `packages/harness/deerflow/tools/builtins/task_tool.py` (subagent polling)
  - 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)
-  - [x] Replace sync `model.invoke()` with async `model.ainvoke()` in title_middleware and memory updater
+  - 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)
@@ -1,446 +0,0 @@
 # [RFC] 在 DeerFlow 中增加 `grep` 与 `glob` 文件搜索工具
 ## Summary
 我认为这个方向是对的，而且值得做。
 如果 DeerFlow 想更接近 Claude Code 这类 coding agent 的实际工作流，仅有 `ls` / `read_file` / `write_file` / `str_replace` 还不够。模型在进入修改前，通常还需要两类能力：
 - `glob`: 快速按路径模式找文件
 - `grep`: 快速按内容模式找候选位置
 这两类工具的价值，不是“功能上 bash 也能做”，而是它们能以更低 token 成本、更强约束、更稳定的输出格式，替代模型频繁走 `bash find` / `bash grep` / `rg` 的习惯。
 但前提是实现方式要对：**它们应该是只读、结构化、受限、可审计的原生工具，而不是对 shell 命令的简单包装。**
 ## Problem
 当前 DeerFlow 的文件工具层主要覆盖：
 - `ls`: 浏览目录结构
 - `read_file`: 读取文件内容
 - `write_file`: 写文件
 - `str_replace`: 做局部字符串替换
 - `bash`: 兜底执行命令
 这套能力能完成任务，但在代码库探索阶段效率不高。
 典型问题：
 1. 模型想找 “所有 `*.tsx` 的 page 文件” 时，只能反复 `ls` 多层目录，或者退回 `bash find`
 2. 模型想找 “某个 symbol / 文案 / 配置键在哪里出现” 时，只能逐文件 `read_file`，或者退回 `bash grep` / `rg`
 3. 一旦退回 `bash`，工具调用就失去结构化输出，结果也更难做裁剪、分页、审计和跨 sandbox 一致化
 4. 对没有开启 host bash 的本地模式，`bash` 甚至可能不可用，此时缺少足够强的只读检索能力
 结论：DeerFlow 现在缺的不是“再多一个 shell 命令”，而是**文件系统检索层**。
 ## Goals
 - 为 agent 提供稳定的路径搜索和内容搜索能力
 - 减少对 `bash` 的依赖，特别是在仓库探索阶段
 - 保持与现有 sandbox 安全模型一致
 - 输出格式结构化，便于模型后续串联 `read_file` / `str_replace`
 - 让本地 sandbox、容器 sandbox、未来 MCP 文件系统工具都能遵守同一语义
 ## Non-Goals
 - 不做通用 shell 兼容层
 - 不暴露完整 grep/find/rg CLI 语法
 - 不在第一版支持二进制检索、复杂 PCRE 特性、上下文窗口高亮渲染等重功能
 - 不把它做成“任意磁盘搜索”，仍然只允许在 DeerFlow 已授权的路径内执行
 ## Why This Is Worth Doing
 参考 Claude Code 这一类 agent 的设计思路，`glob` 和 `grep` 的核心价值不是新能力本身，而是把“探索代码库”的常见动作从开放式 shell 降到受控工具层。
 这样有几个直接收益：
 1. **更低的模型负担**
   模型不需要自己拼 `find`, `grep`, `rg`, `xargs`, quoting 等命令细节。
 2. **更稳定的跨环境行为**
   本地、Docker、AIO sandbox 不必依赖容器里是否装了 `rg`，也不会因为 shell 差异导致行为漂移。
 3. **更强的安全与审计**
   调用参数就是“搜索什么、在哪搜、最多返回多少”，天然比任意命令更容易审计和限流。
 4. **更好的 token 效率**
   `grep` 返回的是命中摘要而不是整段文件，模型只对少数候选路径再调用 `read_file`。
 5. **对 `tool_search` 友好**
   当 DeerFlow 持续扩展工具集时，`grep` / `glob` 会成为非常高频的基础工具，值得保留为 built-in，而不是让模型总是退回通用 bash。
 ## Proposal
 增加两个 built-in sandbox tools：
 - `glob`
 - `grep`
 推荐继续放在：
 - `backend/packages/harness/deerflow/sandbox/tools.py`
 并在 `config.example.yaml` 中默认加入 `file:read` 组。
 ### 1. `glob` 工具
 用途：按路径模式查找文件或目录。
 建议 schema：
 ```python
@tool("glob", parse_docstring=True)
 def glob_tool(
    runtime: ToolRuntime[ContextT, ThreadState],
    description: str,
    pattern: str,
    path: str,
    include_dirs: bool = False,
    max_results: int = 200,
 ) -> str:
    ...
 ```
 参数语义：
 - `description`: 与现有工具保持一致
 - `pattern`: glob 模式，例如 `**/*.py`、`src/**/test_*.ts`
 - `path`: 搜索根目录，必须是绝对路径
 - `include_dirs`: 是否返回目录
 - `max_results`: 最大返回条数，防止一次性打爆上下文
 建议返回格式：
 ```text
 Found 3 paths under /mnt/user-data/workspace
 1. /mnt/user-data/workspace/backend/app.py
 2. /mnt/user-data/workspace/backend/tests/test_app.py
 3. /mnt/user-data/workspace/scripts/build.py
 ```
 如果后续想更适合前端消费，也可以改成 JSON 字符串；但第一版为了兼容现有工具风格，返回可读文本即可。
 ### 2. `grep` 工具
 用途：按内容模式搜索文件，返回命中位置摘要。
 建议 schema：
 ```python
@tool("grep", parse_docstring=True)
 def grep_tool(
    runtime: ToolRuntime[ContextT, ThreadState],
    description: str,
    pattern: str,
    path: str,
    glob: str | None = None,
    literal: bool = False,
    case_sensitive: bool = False,
    max_results: int = 100,
 ) -> str:
    ...
 ```
 参数语义：
 - `pattern`: 搜索词或正则
 - `path`: 搜索根目录，必须是绝对路径
 - `glob`: 可选路径过滤，例如 `**/*.py`
 - `literal`: 为 `True` 时按普通字符串匹配，不解释为正则
 - `case_sensitive`: 是否大小写敏感
 - `max_results`: 最大返回命中数，不是文件数
 建议返回格式：
 ```text
 Found 4 matches under /mnt/user-data/workspace
 /mnt/user-data/workspace/backend/config.py:12: TOOL_GROUPS = [...]
 /mnt/user-data/workspace/backend/config.py:48: def load_tool_config(...):
 /mnt/user-data/workspace/backend/tools.py:91: "tool_groups"
 /mnt/user-data/workspace/backend/tests/test_config.py:22: assert "tool_groups" in data
 ```
 第一版建议只返回：
 - 文件路径
 - 行号
 - 命中行摘要
 不返回上下文块，避免结果过大。模型如果需要上下文，再调用 `read_file(path, start_line, end_line)`。
 ## Design Principles
 ### A. 不做 shell wrapper
 不建议把 `grep` 实现为：
 ```python
 subprocess.run("grep ...")
 ```
 也不建议在容器里直接拼 `find` / `rg` 命令。
 原因：
 - 会引入 shell quoting 和注入面
 - 会依赖不同 sandbox 内镜像是否安装同一套命令
 - Windows / macOS / Linux 行为不一致
 - 很难稳定控制输出条数与格式
 正确方向是：
 - `glob` 使用 Python 标准库路径遍历
 - `grep` 使用 Python 逐文件扫描
 - 输出由 DeerFlow 自己格式化
 如果未来为了性能考虑要优先调用 `rg`，也应该封装在 provider 内部，并保证外部语义不变，而不是把 CLI 暴露给模型。
 ### B. 继续沿用 DeerFlow 的路径权限模型
 这两个工具必须复用当前 `ls` / `read_file` 的路径校验逻辑：
 - 本地模式走 `validate_local_tool_path(..., read_only=True)`
 - 支持 `/mnt/skills/...`
 - 支持 `/mnt/acp-workspace/...`
 - 支持 thread workspace / uploads / outputs 的虚拟路径解析
 - 明确拒绝越权路径与 path traversal
 也就是说，它们属于 **file:read**，不是 `bash` 的替代越权入口。
 ### C. 结果必须硬限制
 没有硬限制的 `glob` / `grep` 很容易炸上下文。
 建议第一版至少限制：
 - `glob.max_results` 默认 200，最大 1000
 - `grep.max_results` 默认 100，最大 500
 - 单行摘要最大长度，例如 200 字符
 - 二进制文件跳过
 - 超大文件跳过，例如单文件大于 1 MB 或按配置控制
 此外，命中数超过阈值时应返回：
 - 已展示的条数
 - 被截断的事实
 - 建议用户缩小搜索范围
 例如：
 ```text
 Found more than 100 matches, showing first 100. Narrow the path or add a glob filter.
 ```
 ### D. 工具语义要彼此互补
 推荐模型工作流应该是：
 1. `glob` 找候选文件
 2. `grep` 找候选位置
 3. `read_file` 读局部上下文
 4. `str_replace` / `write_file` 执行修改
 这样工具边界清晰，也更利于 prompt 中教模型形成稳定习惯。
 ## Implementation Approach
 ## Option A: 直接在 `sandbox/tools.py` 实现第一版
 这是我推荐的起步方案。
 做法：
 - 在 `sandbox/tools.py` 新增 `glob_tool` 与 `grep_tool`
 - 在 local sandbox 场景直接使用 Python 文件系统 API
 - 在非 local sandbox 场景，优先也通过 DeerFlow 自己控制的路径访问层实现
 优点：
 - 改动小
 - 能尽快验证 agent 效果
 - 不需要先改 `Sandbox` 抽象
 缺点：
 - `tools.py` 会继续变胖
 - 如果未来想在 provider 侧做性能优化，需要再抽象一次
 ## Option B: 先扩展 `Sandbox` 抽象
 例如新增：
 ```python
 class Sandbox(ABC):
    def glob(self, path: str, pattern: str, include_dirs: bool = False, max_results: int = 200) -> list[str]:
        ...
    def grep(
        self,
        path: str,
        pattern: str,
        *,
        glob: str | None = None,
        literal: bool = False,
        case_sensitive: bool = False,
        max_results: int = 100,
    ) -> list[GrepMatch]:
        ...
 ```
 优点：
 - 抽象更干净
 - 容器 / 远程 sandbox 可以各自优化
 缺点：
 - 首次引入成本更高
 - 需要同步改所有 sandbox provider
 结论：
 **第一版建议走 Option A，等工具价值验证后再下沉到 `Sandbox` 抽象层。**
 ## Detailed Behavior
 ### `glob` 行为
 - 输入根目录不存在：返回清晰错误
 - 根路径不是目录：返回清晰错误
 - 模式非法：返回清晰错误
 - 结果为空：返回 `No files matched`
 - 默认忽略项应尽量与当前 `list_dir` 对齐，例如：
  - `.git`
  - `node_modules`
  - `__pycache__`
  - `.venv`
  - 构建产物目录
 这里建议抽一个共享 ignore 集，避免 `ls` 与 `glob` 结果风格不一致。
 ### `grep` 行为
 - 默认只扫描文本文件
 - 检测到二进制文件直接跳过
 - 对超大文件直接跳过或只扫前 N KB
 - regex 编译失败时返回参数错误
 - 输出中的路径继续使用虚拟路径，而不是暴露宿主真实路径
 - 建议默认按文件路径、行号排序，保持稳定输出
 ## Prompting Guidance
 如果引入这两个工具，建议同步更新系统提示中的文件操作建议：
 - 查找文件名模式时优先用 `glob`
 - 查找代码符号、配置项、文案时优先用 `grep`
 - 只有在工具不足以完成目标时才退回 `bash`
 否则模型仍会习惯性先调用 `bash`。
 ## Risks
 ### 1. 与 `bash` 能力重叠
 这是事实，但不是问题。
 `ls` 和 `read_file` 也都能被 `bash` 替代，但我们仍然保留它们，因为结构化工具更适合 agent。
 ### 2. 性能问题
 在大仓库上，纯 Python `grep` 可能比 `rg` 慢。
 缓解方式：
 - 第一版先加结果上限和文件大小上限
 - 路径上强制要求 root path
 - 提供 `glob` 过滤缩小扫描范围
 - 后续如有必要，在 provider 内部做 `rg` 优化，但保持同一 schema
 ### 3. 忽略规则不一致
 如果 `ls` 能看到的路径，`glob` 却看不到，模型会困惑。
 缓解方式：
 - 统一 ignore 规则
 - 在文档里明确“默认跳过常见依赖和构建目录”
 ### 4. 正则搜索过于复杂
 如果第一版就支持大量 grep 方言，边界会很乱。
 缓解方式：
 - 第一版只支持 Python `re`
 - 并提供 `literal=True` 的简单模式
 ## Alternatives Considered
 ### A. 不增加工具，完全依赖 `bash`
 不推荐。
 这会让 DeerFlow 在代码探索体验上持续落后，也削弱无 bash 或受限 bash 场景下的能力。
 ### B. 只加 `glob`，不加 `grep`
 不推荐。
 只解决“找文件”，没有解决“找位置”。模型最终还是会退回 `bash grep`。
 ### C. 只加 `grep`，不加 `glob`
 也不推荐。
 `grep` 缺少路径模式过滤时，扫描范围经常太大；`glob` 是它的天然前置工具。
 ### D. 直接接入 MCP filesystem server 的搜索能力
 短期不推荐作为主路径。
 MCP 可以是补充，但 `glob` / `grep` 作为 DeerFlow 的基础 coding tool，最好仍然是 built-in，这样才能在默认安装中稳定可用。
 ## Acceptance Criteria
 - `config.example.yaml` 中可默认启用 `glob` 与 `grep`
 - 两个工具归属 `file:read` 组
 - 本地 sandbox 下严格遵守现有路径权限
 - 输出不泄露宿主机真实路径
 - 大结果集会被截断并明确提示
 - 模型可以通过 `glob -> grep -> read_file -> str_replace` 完成典型改码流
 - 在禁用 host bash 的本地模式下，仓库探索能力明显提升
 ## Rollout Plan
 1. 在 `sandbox/tools.py` 中实现 `glob_tool` 与 `grep_tool`
 2. 抽取与 `list_dir` 一致的 ignore 规则，避免行为漂移
 3. 在 `config.example.yaml` 默认加入工具配置
 4. 为本地路径校验、虚拟路径映射、结果截断、二进制跳过补测试
 5. 更新 README / backend docs / prompt guidance
 6. 收集实际 agent 调用数据，再决定是否下沉到 `Sandbox` 抽象
 ## Suggested Config
 ```yaml
 tools:
  - name: glob
    group: file:read
    use: deerflow.sandbox.tools:glob_tool
  - name: grep
    group: file:read
    use: deerflow.sandbox.tools:grep_tool
 ```
 ## Final Recommendation
 结论是：**可以加，而且应该加。**
 但我会明确卡三个边界：
 1. `grep` / `glob` 必须是 built-in 的只读结构化工具
 2. 第一版不要做 shell wrapper，不要把 CLI 方言直接暴露给模型
 3. 先在 `sandbox/tools.py` 验证价值，再考虑是否下沉到 `Sandbox` provider 抽象
 如果按这个方向做，它会明显提升 DeerFlow 在 coding / repo exploration 场景下的可用性，而且风险可控。
@@ -41,13 +41,6 @@ summarization:
  # Custom summary prompt (optional)
  summary_prompt: null
  # Tool names treated as skill file reads for skill rescue
  skill_file_read_tool_names:
    - read_file
    - read
    - view
    - cat
 ```
 ### Configuration Options
@@ -132,26 +125,6 @@ keep:
 - **Default**: `null` (uses LangChain's default prompt)
 - **Description**: Custom prompt template for generating summaries. The prompt should guide the model to extract the most important context.
 #### `preserve_recent_skill_count`
 - **Type**: Integer (≥ 0)
 - **Default**: `5`
 - **Description**: Number of most-recently-loaded skill files (tool results whose tool name is in `skill_file_read_tool_names` and whose target path is under `skills.container_path`, e.g. `/mnt/skills/...`) that are rescued from summarization. Prevents the agent from losing skill instructions after compression. Set to `0` to disable skill rescue entirely.
 #### `preserve_recent_skill_tokens`
 - **Type**: Integer (≥ 0)
 - **Default**: `25000`
 - **Description**: Total token budget reserved for rescued skill reads. Once this budget is exhausted, older skill bundles are allowed to be summarized.
 #### `preserve_recent_skill_tokens_per_skill`
 - **Type**: Integer (≥ 0)
 - **Default**: `5000`
 - **Description**: Per-skill token cap. Any individual skill read whose tool result exceeds this size is not rescued (it falls through to the summarizer like ordinary content).
 #### `skill_file_read_tool_names`
 - **Type**: List of strings
 - **Default**: `["read_file", "read", "view", "cat"]`
 - **Description**: Tool names treated as skill file reads during summarization rescue. A tool call is only eligible for skill rescue when its name appears in this list and its target path is under `skills.container_path`.
 **Default Prompt Behavior:**
 The default LangChain prompt instructs the model to:
 - Extract highest quality/most relevant context
@@ -174,7 +147,6 @@ The default LangChain prompt instructs the model to:
   - A single summary message is added
   - Recent messages are preserved
 6. **AI/Tool Pair Protection**: The system ensures AI messages and their corresponding tool messages stay together
 7. **Skill Rescue**: Before the summary is generated, the most recently loaded skill files (tool results whose tool name is in `skill_file_read_tool_names` and whose target path is under `skills.container_path`) are lifted out of the summarization set and prepended to the preserved tail. Selection walks newest-first under three budgets: `preserve_recent_skill_count`, `preserve_recent_skill_tokens`, and `preserve_recent_skill_tokens_per_skill`. The triggering AIMessage and all of its paired ToolMessages move together so tool_call ↔ tool_result pairing stays intact.
 ### Token Counting
@@ -0,0 +1,46 @@
 """Async Actor framework — lightweight, asyncio-native, supervision-ready.
 Usage::
    from deerflow.actor import Actor, ActorSystem
    class Greeter(Actor):
        async def on_receive(self, message):
            return f"Hello, {message}!"
    async def main():
        system = ActorSystem("app")
        ref = await system.spawn(Greeter, "greeter")
        reply = await ref.ask("World", timeout=5.0)
        print(reply)  # Hello, World!
        await system.shutdown()
 """
 from .actor import Actor, ActorContext
 from .mailbox import Mailbox, MemoryMailbox
 from .middleware import Middleware
 from .ref import ActorRef, MailboxFullError, ReplyChannel
 from .retry import IdempotentActorMixin, IdempotencyStore, RetryEnvelope, ask_with_retry
 from .supervision import AllForOneStrategy, Directive, OneForOneStrategy, SupervisorStrategy
 from .system import ActorSystem, DeadLetter
 __all__ = [
    "Actor",
    "ActorContext",
    "ActorRef",
    "ActorSystem",
    "AllForOneStrategy",
    "DeadLetter",
    "Directive",
    "Mailbox",
    "MailboxFullError",
    "MemoryMailbox",
    "Middleware",
    "OneForOneStrategy",
    "ReplyChannel",
    "RetryEnvelope",
    "SupervisorStrategy",
    "IdempotentActorMixin",
    "IdempotencyStore",
    "ask_with_retry",
 ]
@@ -0,0 +1,109 @@
 """Actor base class and per-actor context."""
 from __future__ import annotations
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any, Generic, TypeVar
 from .supervision import OneForOneStrategy, SupervisorStrategy
 if TYPE_CHECKING:
    from .ref import ActorRef
 # Message type variable — use Actor[MyMsg] for typed actors
 M = TypeVar("M")
 R = TypeVar("R")
 class ActorContext:
    """Per-actor runtime context, injected before ``on_started``.
    Provides access to the actor's identity, parent, children,
    and the ability to spawn child actors.
    """
    __slots__ = ("_cell",)
    def __init__(self, cell: Any) -> None:
        self._cell = cell
    @property
    def self_ref(self) -> ActorRef:
        return self._cell.ref
    @property
    def parent(self) -> ActorRef | None:
        p = self._cell.parent
        return p.ref if p is not None else None
    @property
    def children(self) -> dict[str, ActorRef]:
        return {name: c.ref for name, c in self._cell.children.items()}
    @property
    def system(self) -> Any:
        return self._cell.system
    async def spawn(
        self,
        actor_cls: type[Actor],
        name: str,
        *,
        mailbox_size: int = 256,
        middlewares: list | None = None,
    ) -> ActorRef:
        """Spawn a child actor supervised by this actor."""
        return await self._cell.spawn_child(actor_cls, name, mailbox_size=mailbox_size, middlewares=middlewares)
    async def run_in_executor(self, fn: Callable[..., Any], *args: Any) -> Any:
        """Run a blocking function in the system's thread pool.
        Usage::
            result = await self.context.run_in_executor(requests.get, url)
        """
        import asyncio
        executor = self._cell.system._executor
        return await asyncio.get_running_loop().run_in_executor(executor, fn, *args)
 class Actor(Generic[M]):
    """Base class for all actors.
    Type parameter ``M`` constrains the message type::
        class Greeter(Actor[str]):
            async def on_receive(self, message: str) -> str:
                return f"Hello, {message}!"
        class Calculator(Actor[int | tuple[str, int, int]]):
            async def on_receive(self, message: int | tuple[str, int, int]) -> int:
                ...
    Unparameterized ``Actor`` accepts ``Any`` (backward-compatible).
    """
    context: ActorContext
    async def on_receive(self, message: M) -> Any:
        """Handle an incoming message.
        Return value is sent back as reply for ``ask`` calls.
        For ``tell`` calls, the return value is discarded.
        """
    async def on_started(self) -> None:
        """Called after creation, before receiving messages."""
    async def on_stopped(self) -> None:
        """Called on graceful shutdown. Release resources here."""
    async def on_restart(self, error: Exception) -> None:
        """Called on the *new* instance before resuming after a crash."""
    def supervisor_strategy(self) -> SupervisorStrategy:
        """Override to customize how this actor supervises its children.
        Default: OneForOne, up to 3 restarts per 60 seconds, always restart.
        """
        return OneForOneStrategy()
@@ -0,0 +1,121 @@
 """Pluggable mailbox abstraction — Akka-inspired enqueue/dequeue interface.
 Built-in implementations:
 - ``MemoryMailbox``: asyncio.Queue backed (default)
 - Extend ``Mailbox`` for Redis, RabbitMQ, Kafka, etc.
 """
 from __future__ import annotations
 import abc
 import asyncio
 from typing import Any
 BACKPRESSURE_BLOCK = "block"
 BACKPRESSURE_DROP_NEW = "drop_new"
 BACKPRESSURE_FAIL = "fail"
 BACKPRESSURE_POLICIES = {BACKPRESSURE_BLOCK, BACKPRESSURE_DROP_NEW, BACKPRESSURE_FAIL}
 class Mailbox(abc.ABC):
    """Abstract mailbox — the message queue for an actor.
    Implementations must be async-safe for single-consumer usage.
    Multiple producers may call ``put`` concurrently.
    """
    @abc.abstractmethod
    async def put(self, msg: Any) -> bool:
        """Enqueue a message. Returns True if accepted, False if dropped."""
    @abc.abstractmethod
    def put_nowait(self, msg: Any) -> bool:
        """Non-blocking enqueue. Returns True if accepted, False if dropped."""
    @abc.abstractmethod
    async def get(self) -> Any:
        """Dequeue the next message. Blocks until available."""
    @abc.abstractmethod
    def get_nowait(self) -> Any:
        """Non-blocking dequeue. Raises ``Empty`` if no message."""
    @abc.abstractmethod
    def empty(self) -> bool:
        """Return True if no messages are queued."""
    @property
    @abc.abstractmethod
    def full(self) -> bool:
        """Return True if mailbox is at capacity."""
    async def put_batch(self, msgs: list[Any]) -> int:
        """Enqueue multiple messages. Returns count accepted.
        Default implementation falls back to sequential ``put`` calls.
        Backends like Redis should override this for efficient bulk push.
        """
        count = 0
        for msg in msgs:
            if await self.put(msg):
                count += 1
        return count
    async def close(self) -> None:
        """Release resources. Default is no-op."""
 class Empty(Exception):
    """Raised by ``get_nowait`` when mailbox is empty."""
 class MemoryMailbox(Mailbox):
    """In-process mailbox backed by ``asyncio.Queue``."""
    def __init__(self, maxsize: int = 256, *, backpressure_policy: str = BACKPRESSURE_BLOCK) -> None:
        if backpressure_policy not in BACKPRESSURE_POLICIES:
            raise ValueError(
                f"Invalid backpressure_policy={backpressure_policy!r}, "
                f"expected one of {sorted(BACKPRESSURE_POLICIES)}"
            )
        self._queue: asyncio.Queue[Any] = asyncio.Queue(maxsize=maxsize)
        self._maxsize = maxsize
        self._backpressure_policy = backpressure_policy
    async def put(self, msg: Any) -> bool:
        if self._backpressure_policy == BACKPRESSURE_BLOCK:
            await self._queue.put(msg)
            return True
        if self._backpressure_policy in (BACKPRESSURE_DROP_NEW, BACKPRESSURE_FAIL):
            if self._queue.full():
                return False
            self._queue.put_nowait(msg)
            return True
        return False
    def put_nowait(self, msg: Any) -> bool:
        if self._queue.full():
            return False
        self._queue.put_nowait(msg)
        return True
    async def get(self) -> Any:
        return await self._queue.get()
    def get_nowait(self) -> Any:
        try:
            return self._queue.get_nowait()
        except asyncio.QueueEmpty:
            raise Empty("mailbox empty")
    def empty(self) -> bool:
        return self._queue.empty()
    @property
    def full(self) -> bool:
        return self._queue.full()
 # Type alias for mailbox factory
 MailboxFactory = type[Mailbox] | Any  # Callable[[], Mailbox]
@@ -0,0 +1,184 @@
 """Redis-backed mailbox — persistent, survives process restart.
 Requires ``redis[hiredis]`` (``uv add redis[hiredis]``).
 Usage::
    import redis.asyncio as redis
    from deerflow.actor import ActorSystem
    from deerflow.actor.mailbox_redis import RedisMailbox
    pool = redis.ConnectionPool.from_url("redis://localhost:6379")
    system = ActorSystem("app")
    ref = await system.spawn(
        MyActor, "worker",
        mailbox=RedisMailbox(pool, "actor:inbox:worker"),
    )
 """
 from __future__ import annotations
 import json
 import logging
 from typing import Any
 from .mailbox import Empty, Mailbox
 from .ref import _Envelope, _Stop
 logger = logging.getLogger(__name__)
 def _serialize(msg: _Envelope | _Stop) -> str:
    """Serialize an envelope to JSON for Redis storage.
    Raises ``TypeError`` if the payload is not JSON-serializable.
    """
    if isinstance(msg, _Stop):
        return json.dumps({"__type__": "stop"})
    try:
        return json.dumps({
            "__type__": "envelope",
            "payload": msg.payload,
            "correlation_id": msg.correlation_id,
            "reply_to": msg.reply_to,
        })
    except (TypeError, ValueError) as e:
        raise TypeError(f"Payload is not JSON-serializable: {e}. RedisMailbox requires JSON-compatible messages.") from e
 def _deserialize(data: str | bytes) -> _Envelope | _Stop:
    """Deserialize a JSON string back to an envelope or stop sentinel."""
    if isinstance(data, bytes):
        data = data.decode("utf-8")
    d = json.loads(data)
    if d.get("__type__") == "stop":
        return _Stop()
    return _Envelope(
        payload=d.get("payload"),
        sender=None,
        correlation_id=d.get("correlation_id"),
        reply_to=d.get("reply_to"),
    )
 class RedisMailbox(Mailbox):
    """Mailbox backed by a Redis LIST.
    Each actor gets its own Redis key (the ``queue_name``).
    Messages are serialized as JSON, so payloads must be JSON-compatible.
    Args:
        pool: A ``redis.asyncio.ConnectionPool`` instance.
        queue_name: Redis key for this actor's inbox (e.g. ``"actor:inbox:worker"``).
        maxlen: Maximum queue length. 0 = unbounded. When exceeded, ``put_nowait`` returns False.
        brpop_timeout: Seconds to block on ``get()`` before retrying. Default 1s.
    """
    def __init__(
        self,
        pool: Any,
        queue_name: str,
        *,
        maxlen: int = 0,
        brpop_timeout: float = 1.0,
    ) -> None:
        self._queue_name = queue_name
        self._maxlen = maxlen
        self._brpop_timeout = brpop_timeout
        self._closed = False
        # Lazy import to avoid hard dependency on redis
        try:
            import redis.asyncio as aioredis
            self._redis: aioredis.Redis = aioredis.Redis(connection_pool=pool)
        except ImportError:
            raise ImportError("RedisMailbox requires 'redis' package. Install with: uv add redis[hiredis]")
    # Lua script for atomic bounded push: check length then push
    _LUA_BOUNDED_PUSH = """
    if tonumber(ARGV[2]) > 0 and redis.call('llen', KEYS[1]) >= tonumber(ARGV[2]) then
        return 0
    end
    redis.call('lpush', KEYS[1], ARGV[1])
    return 1
    """
    async def put(self, msg: Any) -> bool:
        if self._closed:
            return False
        data = _serialize(msg)
        try:
            if self._maxlen > 0:
                # Atomic check+push via Lua script to avoid TOCTOU race
                result = await self._redis.eval(self._LUA_BOUNDED_PUSH, 1, self._queue_name, data, self._maxlen)
                return bool(result)
            await self._redis.lpush(self._queue_name, data)
            return True
        except Exception as e:
            logger.warning("RedisMailbox.put failed for %s: %s", self._queue_name, e)
            return False
    def put_nowait(self, msg: Any) -> bool:
        """Redis cannot do synchronous non-blocking enqueue reliably.
        Returns False so the caller uses dead-letter or task.cancel() fallback.
        Use ``put()`` (async) for reliable delivery.
        """
        return False
    async def put_batch(self, msgs: list[Any]) -> int:
        """Push multiple messages in a single LPUSH command (one round-trip).
        Unbounded queues: all messages sent atomically in one LPUSH.
        Bounded queues: sequential puts to respect maxlen (no batch Lua script needed).
        """
        if self._closed or not msgs:
            return 0
        data_list = []
        for msg in msgs:
            try:
                data_list.append(_serialize(msg))
            except TypeError as e:
                logger.warning("Skipping non-serializable message in put_batch: %s", e)
        if not data_list:
            return 0
        if self._maxlen > 0:
            count = 0
            for data in data_list:
                # Reuse the Lua script for TOCTOU-safe bounded check (same as put())
                result = await self._redis.eval(self._LUA_BOUNDED_PUSH, 1, self._queue_name, data, self._maxlen)
                if result:
                    count += 1
                else:
                    break  # queue full — stop early
            return count
        # Unbounded: single LPUSH with all values — one network round-trip
        await self._redis.lpush(self._queue_name, *data_list)
        return len(data_list)
    async def get(self) -> Any:
        """Blocking dequeue via BRPOP. Retries until a message arrives."""
        while not self._closed:
            result = await self._redis.brpop(self._queue_name, timeout=self._brpop_timeout)
            if result is not None:
                _, data = result
                return _deserialize(data)
        raise Empty("mailbox closed")
    def get_nowait(self) -> Any:
        raise Empty("Redis mailbox does not support synchronous get_nowait")
    def empty(self) -> bool:
        # Cannot query Redis synchronously. Return True so drain loops
        # terminate immediately and rely on get_nowait raising Empty.
        return True
    @property
    def full(self) -> bool:
        # Cannot query Redis synchronously. Backpressure enforced
        # atomically inside put() via Lua script.
        return False
    async def close(self) -> None:
        self._closed = True
        await self._redis.aclose()
@@ -0,0 +1,79 @@
 """Middleware pipeline — cross-cutting concerns for actors.
 Inspired by Proto.Actor's sender/receiver middleware model.
 Middleware intercepts messages before/after the actor processes them.
 Usage::
    class LoggingMiddleware(Middleware):
        async def on_receive(self, ctx, message, next_fn):
            logger.info("Received: %s", message)
            result = await next_fn(ctx, message)
            logger.info("Replied: %s", result)
            return result
    system = ActorSystem("app")
    ref = await system.spawn(MyActor, "a", middlewares=[LoggingMiddleware()])
 """
 from __future__ import annotations
 from collections.abc import Awaitable, Callable
 from typing import Any
 class ActorMailboxContext:
    """Context passed to middleware on each message."""
    __slots__ = ("actor_ref", "sender", "message_type")
    def __init__(self, actor_ref: Any, sender: Any, message_type: str) -> None:
        self.actor_ref = actor_ref
        self.sender = sender
        self.message_type = message_type  # "tell" or "ask"
 # The inner handler signature: (ctx, message) -> result
 NextFn = Callable[[ActorMailboxContext, Any], Awaitable[Any]]
 class Middleware:
    """Base class for actor middleware.
    Override ``on_receive`` to intercept inbound messages.
    Must call ``await next_fn(ctx, message)`` to continue the chain.
    """
    async def on_receive(self, ctx: ActorMailboxContext, message: Any, next_fn: NextFn) -> Any:
        """Intercept a message. Call next_fn to continue the chain."""
        return await next_fn(ctx, message)
    async def on_started(self, actor_ref: Any) -> None:
        """Called when the actor starts."""
    async def on_stopped(self, actor_ref: Any) -> None:
        """Called when the actor stops."""
    async def on_restart(self, actor_ref: Any, error: Exception) -> None:
        """Called when the actor restarts after a crash.
        Override to reset per-actor-instance state (caches, counters, etc.)
        that should not bleed across restarts.
        """
 def build_middleware_chain(middlewares: list[Middleware], handler: NextFn) -> NextFn:
    """Build a nested middleware chain ending with *handler*.
    Execution order: first middleware in list wraps outermost.
    ``[A, B, C]`` → ``A(B(C(handler)))``
    """
    chain = handler
    for mw in reversed(middlewares):
        outer = chain
        async def _wrap(ctx: ActorMailboxContext, msg: Any, _mw: Middleware = mw, _next: NextFn = outer) -> Any:
            return await _mw.on_receive(ctx, msg, _next)
        chain = _wrap
    return chain
@@ -0,0 +1,220 @@
 """ActorRef — immutable, serializable reference to an actor."""
 from __future__ import annotations
 import asyncio
 import uuid
 from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:
    from .system import _ActorCell
 class ActorRef:
    """Immutable handle for sending messages to an actor.
    Users never construct this directly — it is returned by
    ``ActorSystem.spawn`` or ``ActorContext.spawn``.
    """
    __slots__ = ("_cell",)
    def __init__(self, cell: _ActorCell) -> None:
        self._cell = cell
    @property
    def name(self) -> str:
        return self._cell.name
    @property
    def path(self) -> str:
        return self._cell.path
    @property
    def is_alive(self) -> bool:
        return not self._cell.stopped
    async def tell(self, message: Any, *, sender: ActorRef | None = None) -> None:
        """Fire-and-forget message delivery."""
        if self._cell.stopped:
            self._cell.system._dead_letter(self, message, sender)
            return
        await self._cell.enqueue(_Envelope(message, sender))
    async def ask(self, message: Any, *, timeout: float = 5.0) -> Any:
        """Request-response with timeout.
        Uses correlation ID + ReplyRegistry instead of passing a Future
        through the mailbox. This makes ask work with any Mailbox backend
        (memory, Redis, RabbitMQ, etc.).
        Raises ``asyncio.TimeoutError`` if the actor doesn't reply in time.
        Raises the actor's exception if ``on_receive`` fails.
        """
        if self._cell.stopped:
            raise ActorStoppedError(f"Actor {self.path} is stopped")
        corr_id = uuid.uuid4().hex
        future = self._cell.system._replies.register(corr_id)
        try:
            envelope = _Envelope(message, sender=None, correlation_id=corr_id, reply_to=self._cell.system.system_id)
            await self._cell.enqueue(envelope)
            return await asyncio.wait_for(future, timeout=timeout)
        finally:
            self._cell.system._replies.discard(corr_id)
    def stop(self) -> None:
        """Request graceful shutdown."""
        self._cell.request_stop()
    def __repr__(self) -> str:
        alive = "alive" if self.is_alive else "dead"
        return f"ActorRef({self.path}, {alive})"
    def __eq__(self, other: object) -> bool:
        if isinstance(other, ActorRef):
            return self._cell is other._cell
        return NotImplemented
    def __hash__(self) -> int:
        return id(self._cell)
 class ActorStoppedError(Exception):
    """Raised when sending to a stopped actor via ask."""
 class MailboxFullError(RuntimeError):
    """Raised when a message is rejected because the mailbox is at capacity."""
 # ---------------------------------------------------------------------------
 # Internal message wrappers (serializable — no Future objects)
 # ---------------------------------------------------------------------------
 class _Envelope:
    """Message envelope flowing through mailboxes.
    All fields are serializable (no asyncio.Future). This is what
    enables ask() to work across MQ-backed mailboxes.
    """
    __slots__ = ("payload", "sender", "correlation_id", "reply_to")
    def __init__(
        self,
        payload: Any,
        sender: ActorRef | None = None,
        correlation_id: str | None = None,
        reply_to: str | None = None,
    ) -> None:
        self.payload = payload
        self.sender = sender
        self.correlation_id = correlation_id
        self.reply_to = reply_to  # System ID of the caller (for cross-process reply routing)
 class _Stop:
    """Sentinel placed on the mailbox to trigger graceful shutdown."""
 # ---------------------------------------------------------------------------
 # ReplyRegistry — maps correlation_id → Future (lives on ActorSystem)
 # ---------------------------------------------------------------------------
 class _ReplyRegistry:
    """In-memory registry mapping correlation IDs to Futures.
    Used by ask() to receive replies without putting Futures in the mailbox.
    """
    def __init__(self) -> None:
        self._pending: dict[str, asyncio.Future[Any]] = {}
    def register(self, corr_id: str) -> asyncio.Future[Any]:
        """Create and register a Future for a correlation ID."""
        future: asyncio.Future[Any] = asyncio.get_running_loop().create_future()
        self._pending[corr_id] = future
        return future
    def resolve(self, corr_id: str, result: Any) -> None:
        """Complete a pending ask with a result."""
        future = self._pending.pop(corr_id, None)
        if future is not None and not future.done():
            future.set_result(result)
    def reject(self, corr_id: str, error: Exception) -> None:
        """Complete a pending ask with an error."""
        future = self._pending.pop(corr_id, None)
        if future is not None and not future.done():
            future.set_exception(error)
    def discard(self, corr_id: str) -> None:
        """Remove a pending entry (e.g. on timeout)."""
        self._pending.pop(corr_id, None)
    def reject_all(self, error: Exception) -> None:
        """Reject all pending asks (e.g. on system shutdown)."""
        for future in self._pending.values():
            if not future.done():
                future.set_exception(error)
        self._pending.clear()
 # ---------------------------------------------------------------------------
 # ReplyChannel — abstraction for routing replies (local or cross-process)
 # ---------------------------------------------------------------------------
 class _ReplyMessage:
    """Reply payload sent through ReplyChannel.
    Carries the original exception object for local delivery (preserves type).
    For cross-process serialization, use ``to_dict``/``from_dict``.
    """
    __slots__ = ("correlation_id", "result", "error", "exception")
    def __init__(self, correlation_id: str, result: Any = None, error: str | None = None, exception: Exception | None = None) -> None:
        self.correlation_id = correlation_id
        self.result = result
        self.error = error
        self.exception = exception  # Original exception (local only, not serializable)
    def to_dict(self) -> dict[str, Any]:
        """Serialize for cross-process transport (exception becomes string)."""
        return {"correlation_id": self.correlation_id, "result": self.result, "error": self.error}
    @classmethod
    def from_dict(cls, d: dict[str, Any]) -> _ReplyMessage:
        return cls(d["correlation_id"], d.get("result"), d.get("error"))
 class ReplyChannel:
    """Routes replies from actor back to the caller's ReplyRegistry.
    Default implementation: resolve locally (same process).
    Override ``send_reply`` for cross-process routing (e.g. via Redis pub/sub).
    """
    async def send_reply(self, reply_to: str, reply: _ReplyMessage, local_registry: _ReplyRegistry) -> None:
        """Deliver a reply to the system identified by *reply_to*.
        Default: assumes reply_to is the local system → resolve directly.
        Override for MQ-backed cross-process delivery.
        """
        if reply.exception is not None:
            # Local: preserve original exception type
            local_registry.reject(reply.correlation_id, reply.exception)
        elif reply.error is not None:
            # Cross-process: exception was serialized to string
            local_registry.reject(reply.correlation_id, RuntimeError(reply.error))
        else:
            local_registry.resolve(reply.correlation_id, reply.result)
    async def start_listener(self, system_id: str, registry: _ReplyRegistry) -> None:
        """Start listening for inbound replies (no-op for local)."""
    async def stop_listener(self) -> None:
        """Stop the reply listener (no-op for local)."""
@@ -0,0 +1,142 @@
 """Retry + idempotency helpers for Actor ask/tell patterns.
 This module provides:
 - Message envelope carrying retry/idempotency metadata
 - In-memory idempotency store (process-local)
 - ask_with_retry helper (bounded retries + exponential backoff + jitter)
 Design notes:
 - Keep transport-agnostic; works with current in-memory mailbox.
 - Business handlers must opt in by using ``IdempotentActorMixin`` and
  wrapping logic with ``handle_idempotent``.
 """
 from __future__ import annotations
 import asyncio
 import random
 import time
 import uuid
 from dataclasses import dataclass, field
 from typing import Any
@dataclass(slots=True)
 class RetryEnvelope:
    """Metadata wrapper for idempotent/retriable messages."""
    payload: Any
    message_id: str = field(default_factory=lambda: uuid.uuid4().hex)
    idempotency_key: str | None = None
    attempt: int = 1
    max_attempts: int = 1
    created_at_ms: int = field(default_factory=lambda: int(time.time() * 1000))
    @classmethod
    def wrap(
        cls,
        payload: Any,
        *,
        idempotency_key: str | None = None,
        attempt: int = 1,
        max_attempts: int = 1,
    ) -> "RetryEnvelope":
        return cls(
            payload=payload,
            idempotency_key=idempotency_key,
            attempt=attempt,
            max_attempts=max_attempts,
        )
 class IdempotencyStore:
    """Process-local idempotency result store."""
    def __init__(self) -> None:
        self._results: dict[str, Any] = {}
    def has(self, key: str) -> bool:
        return key in self._results
    def get(self, key: str) -> Any:
        return self._results[key]
    def set(self, key: str, value: Any) -> None:
        self._results[key] = value
 class IdempotentActorMixin:
    """Mixin adding idempotent handling utility for actors.
    Usage in actor::
        class MyActor(IdempotentActorMixin, Actor):
            async def on_receive(self, message):
                return await self.handle_idempotent(message, self._handle)
            async def _handle(self, payload):
                ...
    """
    def _idempotency_store(self) -> IdempotencyStore:
        store = getattr(self, "_idem_store", None)
        if store is None:
            store = IdempotencyStore()
            setattr(self, "_idem_store", store)
        return store
    async def handle_idempotent(self, message: Any, handler):
        if not isinstance(message, RetryEnvelope):
            return await handler(message)
        key = message.idempotency_key
        if not key:
            return await handler(message.payload)
        store = self._idempotency_store()
        if store.has(key):
            return store.get(key)
        result = await handler(message.payload)
        store.set(key, result)
        return result
 async def ask_with_retry(
    ref,
    payload: Any,
    *,
    timeout: float = 5.0,
    max_attempts: int = 3,
    base_backoff_s: float = 0.1,
    max_backoff_s: float = 5.0,
    jitter_ratio: float = 0.3,
    retry_exceptions: tuple[type[BaseException], ...] = (asyncio.TimeoutError,),
    idempotency_key: str | None = None,
 ) -> Any:
    """Ask actor with bounded retries and envelope metadata."""
    if max_attempts < 1:
        raise ValueError("max_attempts must be >= 1")
    key = idempotency_key or uuid.uuid4().hex
    last_exc: BaseException | None = None
    for attempt in range(1, max_attempts + 1):
        msg = RetryEnvelope.wrap(
            payload,
            idempotency_key=key,
            attempt=attempt,
            max_attempts=max_attempts,
        )
        try:
            return await ref.ask(msg, timeout=timeout)
        except retry_exceptions as exc:
            last_exc = exc
            if attempt >= max_attempts:
                break
            backoff = min(max_backoff_s, base_backoff_s * (2 ** (attempt - 1)))
            jitter = backoff * jitter_ratio * random.random()
            await asyncio.sleep(backoff + jitter)
    raise last_exc  # type: ignore[misc]  # always set: loop runs ≥1 time and sets on last iteration
@@ -0,0 +1,75 @@
 """Supervision strategies — Erlang/Akka-inspired fault tolerance."""
 from __future__ import annotations
 import enum
 import time
 from collections import deque
 from collections.abc import Callable
 from typing import Any
 class Directive(enum.Enum):
    """What a supervisor should do when a child fails."""
    resume = "resume"  # ignore error, keep processing
    restart = "restart"  # discard state, create fresh instance
    stop = "stop"  # terminate the child permanently
    escalate = "escalate"  # propagate to grandparent
 class SupervisorStrategy:
    """Base class for supervision strategies.
    Args:
        max_restarts: Maximum restarts allowed within *within_seconds*.
            Exceeding this limit stops the child permanently.
        within_seconds: Time window for restart counting.
        decider: Maps exception → Directive. Default: always restart.
    """
    def __init__(
        self,
        *,
        max_restarts: int = 3,
        within_seconds: float = 60.0,
        decider: Callable[[Exception], Directive] | None = None,
    ) -> None:
        self.max_restarts = max_restarts
        self.within_seconds = within_seconds
        self.decider = decider or (lambda _: Directive.restart)
        self._restart_timestamps: dict[str, deque[float]] = {}
    def decide(self, error: Exception) -> Directive:
        return self.decider(error)
    def record_restart(self, child_name: str) -> bool:
        """Record a restart and return True if within limits."""
        now = time.monotonic()
        if child_name not in self._restart_timestamps:
            self._restart_timestamps[child_name] = deque()
        ts = self._restart_timestamps[child_name]
        # Purge old entries outside the window
        cutoff = now - self.within_seconds
        while ts and ts[0] < cutoff:
            ts.popleft()
        ts.append(now)
        return len(ts) <= self.max_restarts
    def apply_to_children(self, failed_child: str, all_children: list[str]) -> list[str]:
        """Return which children should be affected by the directive."""
        raise NotImplementedError
 class OneForOneStrategy(SupervisorStrategy):
    """Only the failed child is affected."""
    def apply_to_children(self, failed_child: str, all_children: list[str]) -> list[str]:
        return [failed_child]
 class AllForOneStrategy(SupervisorStrategy):
    """All children are affected when any one fails."""
    def apply_to_children(self, failed_child: str, all_children: list[str]) -> list[str]:
        return list(all_children)
@@ -0,0 +1,416 @@
 """ActorSystem — top-level actor container and lifecycle manager."""
 from __future__ import annotations
 import asyncio
 import logging
 from collections import deque
 from dataclasses import dataclass
 from typing import Any
 from .actor import Actor, ActorContext
 from .mailbox import Empty, Mailbox, MemoryMailbox
 from .middleware import ActorMailboxContext, Middleware, NextFn, build_middleware_chain
 from .ref import ActorRef, ActorStoppedError, MailboxFullError, ReplyChannel, _Envelope, _ReplyMessage, _ReplyRegistry, _Stop
 from .supervision import Directive, SupervisorStrategy
 logger = logging.getLogger(__name__)
 # Timeout for middleware lifecycle hooks (on_started/on_stopped)
 _MIDDLEWARE_HOOK_TIMEOUT = 10.0
 # Maximum dead letters kept in memory
 _MAX_DEAD_LETTERS = 10000
 # Maximum consecutive failures before a root actor poison-quarantines a message
 _MAX_CONSECUTIVE_FAILURES = 10
@dataclass
 class DeadLetter:
    """A message that could not be delivered."""
    recipient: ActorRef
    message: Any
    sender: ActorRef | None
 class ActorSystem:
    """Top-level actor container.
    Manages root actors and provides the dead letter sink.
    """
    def __init__(
        self,
        name: str = "system",
        *,
        max_dead_letters: int = _MAX_DEAD_LETTERS,
        executor_workers: int | None = 4,
        reply_channel: ReplyChannel | None = None,
    ) -> None:
        import uuid as _uuid
        self.name = name
        self.system_id = f"{name}-{_uuid.uuid4().hex[:8]}"
        self._root_cells: dict[str, _ActorCell] = {}
        self._dead_letters: deque[DeadLetter] = deque(maxlen=max_dead_letters)
        self._on_dead_letter: list[Any] = []
        self._shutting_down = False
        self._replies = _ReplyRegistry()
        self._reply_channel = reply_channel or ReplyChannel()
        # Shared thread pool for actors to run blocking I/O
        from concurrent.futures import ThreadPoolExecutor
        self._executor = ThreadPoolExecutor(max_workers=executor_workers, thread_name_prefix=f"actor-{name}") if executor_workers else None
    async def spawn(
        self,
        actor_cls: type[Actor],
        name: str,
        *,
        mailbox_size: int = 256,
        mailbox: Mailbox | None = None,
        middlewares: list[Middleware] | None = None,
    ) -> ActorRef:
        """Spawn a root-level actor.
        Args:
            mailbox: Custom mailbox instance. If None, uses MemoryMailbox(mailbox_size).
        """
        if name in self._root_cells:
            raise ValueError(f"Root actor '{name}' already exists")
        cell = _ActorCell(
            actor_cls=actor_cls,
            name=name,
            parent=None,
            system=self,
            mailbox=mailbox or MemoryMailbox(mailbox_size),
            middlewares=middlewares or [],
        )
        self._root_cells[name] = cell
        try:
            await cell.start()
        except Exception:
            del self._root_cells[name]
            raise
        return cell.ref
    async def shutdown(self, *, timeout: float = 10.0) -> None:
        """Gracefully stop all actors."""
        self._shutting_down = True
        tasks = []
        for cell in list(self._root_cells.values()):
            cell.request_stop()
            if cell.task is not None:
                tasks.append(cell.task)
        if tasks:
            _, pending = await asyncio.wait(tasks, timeout=timeout)
            # Cancel tasks that didn't finish within the timeout to prevent zombie tasks
            for t in pending:
                t.cancel()
            if pending:
                await asyncio.wait(pending, timeout=2.0)
        self._root_cells.clear()
        self._replies.reject_all(ActorStoppedError("ActorSystem shutting down"))
        await self._reply_channel.stop_listener()
        if self._executor is not None:
            self._executor.shutdown(wait=False)
        logger.info("ActorSystem '%s' shut down (%d dead letters)", self.name, len(self._dead_letters))
    def _dead_letter(self, recipient: ActorRef, message: Any, sender: ActorRef | None) -> None:
        dl = DeadLetter(recipient=recipient, message=message, sender=sender)
        self._dead_letters.append(dl)
        for cb in self._on_dead_letter:
            try:
                cb(dl)
            except Exception:
                pass
        logger.debug("Dead letter: %s → %s", type(message).__name__, recipient.path)
    def on_dead_letter(self, callback: Any) -> None:
        """Register a dead letter listener."""
        self._on_dead_letter.append(callback)
    @property
    def dead_letters(self) -> list[DeadLetter]:
        return list(self._dead_letters)
 # ---------------------------------------------------------------------------
 # _ActorCell — internal runtime wrapper
 # ---------------------------------------------------------------------------
 class _ActorCell:
    """Runtime container for a single actor instance.
    Manages the mailbox, processing loop, children, and supervision.
    Not part of the public API.
    """
    def __init__(
        self,
        actor_cls: type[Actor],
        name: str,
        parent: _ActorCell | None,
        system: ActorSystem,
        mailbox: Mailbox,
        middlewares: list[Middleware] | None = None,
    ) -> None:
        self.actor_cls = actor_cls
        self.name = name
        self.parent = parent
        self.system = system
        self.children: dict[str, _ActorCell] = {}
        self.mailbox = mailbox
        self.ref = ActorRef(self)
        self.actor: Actor | None = None
        self.task: asyncio.Task[None] | None = None
        self.stopped = False
        self._supervisor_strategy: SupervisorStrategy | None = None
        self._middlewares = middlewares or []
        self._receive_chain: NextFn | None = None
        # Cache path (immutable after init — parent never changes)
        parts: list[str] = []
        cell: _ActorCell | None = self
        while cell is not None:
            parts.append(cell.name)
            cell = cell.parent
        parts.append(system.name)
        self.path = "/" + "/".join(reversed(parts))
    async def start(self) -> None:
        self.actor = self.actor_cls()
        self.actor.context = ActorContext(self)
        async def _inner_handler(_ctx: ActorMailboxContext, message: Any) -> Any:
            return await self.actor.on_receive(message)  # type: ignore[union-attr]
        if self._middlewares:
            self._receive_chain = build_middleware_chain(self._middlewares, _inner_handler)
        else:
            self._receive_chain = _inner_handler
        # Notify middleware of start (with timeout to prevent blocking)
        for mw in self._middlewares:
            try:
                await asyncio.wait_for(mw.on_started(self.ref), timeout=_MIDDLEWARE_HOOK_TIMEOUT)
            except asyncio.TimeoutError:
                logger.warning("Middleware %s.on_started timed out for %s", type(mw).__name__, self.path)
        await self.actor.on_started()
        self.task = asyncio.create_task(self._run(), name=f"actor:{self.path}")
    async def enqueue(self, msg: _Envelope | _Stop) -> None:
        # Try non-blocking first (fast path for MemoryMailbox)
        if self.mailbox.put_nowait(msg):
            return
        # Fallback to async put (required for Redis and other async backends)
        if not await self.mailbox.put(msg):
            if isinstance(msg, _Envelope) and msg.correlation_id is not None:
                self.system._replies.reject(msg.correlation_id, MailboxFullError(f"Mailbox full: {self.path}"))
            elif isinstance(msg, _Envelope):
                self.system._dead_letter(self.ref, msg.payload, msg.sender)
    def request_stop(self) -> None:
        """Request graceful shutdown.
        Tries put_nowait first. If that fails (full or unsupported backend),
        cancels the task directly so _run exits via CancelledError → finally → _shutdown.
        """
        if not self.stopped:
            if not self.mailbox.put_nowait(_Stop()):
                # Redis/async backends can't put_nowait — cancel the task
                if self.task is not None and not self.task.done():
                    self.task.cancel()
                else:
                    self.stopped = True
    async def spawn_child(
        self,
        actor_cls: type[Actor],
        name: str,
        *,
        mailbox_size: int = 256,
        mailbox: Mailbox | None = None,
        middlewares: list[Middleware] | None = None,
    ) -> ActorRef:
        if name in self.children:
            raise ValueError(f"Child '{name}' already exists under {self.path}")
        child = _ActorCell(
            actor_cls=actor_cls,
            name=name,
            parent=self,
            system=self.system,
            mailbox=mailbox or MemoryMailbox(mailbox_size),
            middlewares=middlewares or [],
        )
        self.children[name] = child
        try:
            await child.start()
        except Exception:
            del self.children[name]
            raise
        return child.ref
    # -- Processing loop -------------------------------------------------------
    async def _run(self) -> None:
        consecutive_failures = 0
        try:
            while not self.stopped:
                try:
                    msg = await self.mailbox.get()
                except asyncio.CancelledError:
                    break
                if isinstance(msg, _Stop):
                    break
                try:
                    if not isinstance(msg, _Envelope):
                        continue
                    msg_type = "ask" if msg.correlation_id else "tell"
                    ctx = ActorMailboxContext(self.ref, msg.sender, msg_type)
                    result = await self._receive_chain(ctx, msg.payload)  # type: ignore[misc]
                    if msg.correlation_id is not None:
                        reply = _ReplyMessage(msg.correlation_id, result=result)
                        await self.system._reply_channel.send_reply(msg.reply_to or self.system.system_id, reply, self.system._replies)
                    consecutive_failures = 0
                except Exception as exc:
                    if isinstance(msg, _Envelope) and msg.correlation_id is not None:
                        reply = _ReplyMessage(msg.correlation_id, error=str(exc), exception=exc)
                        await self.system._reply_channel.send_reply(msg.reply_to or self.system.system_id, reply, self.system._replies)
                    if self.parent is not None:
                        await self.parent._handle_child_failure(self, exc)
                    else:
                        consecutive_failures += 1
                        logger.error("Uncaught error in root actor %s (%d/%d): %s", self.path, consecutive_failures, _MAX_CONSECUTIVE_FAILURES, exc)
                        if consecutive_failures >= _MAX_CONSECUTIVE_FAILURES:
                            logger.error("Root actor %s hit consecutive failure limit — stopping", self.path)
                            break
        except asyncio.CancelledError:
            pass  # Fall through to _shutdown
        finally:
            await self._shutdown()
    async def _shutdown(self) -> None:
        self.stopped = True
        # Parallel child shutdown prevents cascading timeouts.
        child_tasks = []
        for child in list(self.children.values()):
            child.request_stop()
            if child.task is not None:
                child_tasks.append(child.task)
        if child_tasks:
            _, pending = await asyncio.wait(child_tasks, timeout=10.0)
            for t in pending:
                t.cancel()
                # Mark leaked children as stopped
                for child in self.children.values():
                    if child.task is t:
                        child.stopped = True
        # Drain mailbox → dead letters (use try/except to handle all backends)
        while True:
            try:
                msg = self.mailbox.get_nowait()
            except Empty:
                break
            if isinstance(msg, _Envelope):
                if msg.correlation_id is not None:
                    self.system._replies.reject(msg.correlation_id, ActorStoppedError(f"Actor {self.path} stopped"))
                else:
                    self.system._dead_letter(self.ref, msg.payload, msg.sender)
        # Lifecycle hook
        for mw in self._middlewares:
            try:
                await asyncio.wait_for(mw.on_stopped(self.ref), timeout=_MIDDLEWARE_HOOK_TIMEOUT)
            except asyncio.TimeoutError:
                logger.warning("Middleware %s.on_stopped timed out for %s", type(mw).__name__, self.path)
            except Exception:
                logger.exception("Error in middleware on_stopped for %s", self.path)
        if self.actor is not None:
            try:
                await self.actor.on_stopped()
            except Exception:
                logger.exception("Error in on_stopped for %s", self.path)
        # Remove from parent
        if self.parent is not None:
            self.parent.children.pop(self.name, None)
        # Close mailbox to release backend resources (e.g. Redis connections)
        try:
            await self.mailbox.close()
        except Exception:
            logger.exception("Error closing mailbox for %s", self.path)
    # -- Supervision -----------------------------------------------------------
    def _get_supervisor_strategy(self) -> SupervisorStrategy:
        if self._supervisor_strategy is None:
            self._supervisor_strategy = self.actor.supervisor_strategy()  # type: ignore[union-attr]
        return self._supervisor_strategy
    async def _handle_child_failure(self, child: _ActorCell, error: Exception) -> None:
        strategy = self._get_supervisor_strategy()
        directive = strategy.decide(error)
        affected = strategy.apply_to_children(child.name, list(self.children.keys()))
        if directive == Directive.resume:
            logger.info("Supervisor %s: resume %s after %s", self.path, child.path, type(error).__name__)
            return
        if directive == Directive.stop:
            for name in affected:
                c = self.children.get(name)
                if c is not None:
                    c.request_stop()
            logger.info("Supervisor %s: stop %s after %s", self.path, [self.children[n].path for n in affected if n in self.children], type(error).__name__)
            return
        if directive == Directive.escalate:
            # Stop the failing child, then propagate failure up the supervision chain.
            # We cannot use `raise error` here — that would crash the child's _run
            # loop instead of notifying the grandparent's supervisor.
            child.request_stop()
            if self.parent is not None:
                logger.info("Supervisor %s: escalate %s to grandparent %s", self.path, type(error).__name__, self.parent.path)
                await self.parent._handle_child_failure(self, error)
            else:
                logger.error("Uncaught escalation at root actor %s: %s", self.path, error)
            return
        if directive == Directive.restart:
            for name in affected:
                c = self.children.get(name)
                if c is None:
                    continue
                if not strategy.record_restart(name):
                    logger.warning("Supervisor %s: child %s exceeded restart limit — stopping", self.path, c.path)
                    c.request_stop()
                    continue
                await self._restart_child(c, error)
    async def _restart_child(self, child: _ActorCell, error: Exception) -> None:
        logger.info("Supervisor %s: restarting %s after %s", self.path, child.path, type(error).__name__)
        # Stop the old actor (but keep the cell and mailbox)
        old_actor = child.actor
        if old_actor is not None:
            try:
                await old_actor.on_stopped()
            except Exception:
                logger.exception("Error in on_stopped during restart of %s", child.path)
        # Notify middleware of restart (reset per-instance state)
        for mw in child._middlewares:
            try:
                await asyncio.wait_for(mw.on_restart(child.ref, error), timeout=_MIDDLEWARE_HOOK_TIMEOUT)
            except asyncio.TimeoutError:
                logger.warning("Middleware %s.on_restart timed out for %s", type(mw).__name__, child.path)
            except Exception:
                logger.exception("Error in middleware on_restart for %s", child.path)
        # Create fresh instance
        new_actor = child.actor_cls()
        new_actor.context = ActorContext(child)
        child.actor = new_actor
        try:
            await new_actor.on_restart(error)
            await new_actor.on_started()
        except Exception:
            logger.exception("Error during restart initialization of %s", child.path)
            child.request_stop()
@@ -2,14 +2,8 @@ from .checkpointer import get_checkpointer, make_checkpointer, reset_checkpointe
 from .factory import create_deerflow_agent
 from .features import Next, Prev, RuntimeFeatures
 from .lead_agent import make_lead_agent
 from .lead_agent.prompt import prime_enabled_skills_cache
 from .thread_state import SandboxState, ThreadState
 # LangGraph imports deerflow.agents when registering the graph. Prime the
 # enabled-skills cache here so the request path can usually read a warm cache
 # without forcing synchronous filesystem work during prompt module import.
 prime_enabled_skills_cache()
 __all__ = [
    "create_deerflow_agent",
    "RuntimeFeatures",
@@ -17,7 +17,6 @@ For sync usage see :mod:`deerflow.agents.checkpointer.provider`.
 from __future__ import annotations
 import asyncio
 import contextlib
 import logging
 from collections.abc import AsyncIterator
@@ -55,7 +54,7 @@ async def _async_checkpointer(config) -> AsyncIterator[Checkpointer]:
            raise ImportError(SQLITE_INSTALL) from exc
        conn_str = resolve_sqlite_conn_str(config.connection_string or "store.db")
-        await asyncio.to_thread(ensure_sqlite_parent_dir, conn_str)
+        ensure_sqlite_parent_dir(conn_str)
        async with AsyncSqliteSaver.from_conn_string(conn_str) as saver:
            await saver.setup()
            yield saver
@@ -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 ensure_sqlite_parent_dir, resolve_sqlite_conn_str
+from deerflow.runtime.store._sqlite_utils import resolve_sqlite_conn_str
 logger = logging.getLogger(__name__)
@@ -67,7 +67,6 @@ 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)
@@ -1,40 +1,28 @@
 import logging
 from langchain.agents import create_agent
-from langchain.agents.middleware import AgentMiddleware
+from langchain.agents.middleware import AgentMiddleware, SummarizationMiddleware
 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, validate_agent_name
+from deerflow.config.agents_config import load_agent_config
 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
 logger = logging.getLogger(__name__)
 def _get_runtime_config(config: RunnableConfig) -> dict:
    """Merge legacy configurable options with LangGraph runtime context."""
    cfg = dict(config.get("configurable", {}) or {})
    context = config.get("context", {}) or {}
    if isinstance(context, dict):
        cfg.update(context)
    return cfg
 def _resolve_model_name(requested_model_name: str | None = None) -> str:
    """Resolve a runtime model name safely, falling back to default if invalid. Returns None if no models are configured."""
    app_config = get_app_config()
@@ -50,7 +38,7 @@ def _resolve_model_name(requested_model_name: str | None = None) -> str:
    return default_model_name
-def _create_summarization_middleware() -> DeerFlowSummarizationMiddleware | None:
+def _create_summarization_middleware() -> SummarizationMiddleware | None:
    """Create and configure the summarization middleware from config."""
    config = get_summarization_config()
@@ -89,28 +77,7 @@ def _create_summarization_middleware() -> DeerFlowSummarizationMiddleware | None
    if config.summary_prompt is not None:
        kwargs["summary_prompt"] = config.summary_prompt
-    hooks: list[BeforeSummarizationHook] = []
+    return SummarizationMiddleware(**kwargs)
    if get_memory_config().enabled:
        hooks.append(memory_flush_hook)
    # The logic below relies on two assumptions holding true: this factory is
    # the sole entry point for DeerFlowSummarizationMiddleware, and the runtime
    # config is not expected to change after startup.
    try:
        skills_container_path = get_app_config().skills.container_path or "/mnt/skills"
    except Exception:
        logger.exception("Failed to resolve skills container path; falling back to default")
        skills_container_path = "/mnt/skills"
    return DeerFlowSummarizationMiddleware(
        **kwargs,
        skills_container_path=skills_container_path,
        skill_file_read_tool_names=config.skill_file_read_tool_names,
        before_summarization=hooks,
        preserve_recent_skill_count=config.preserve_recent_skill_count,
        preserve_recent_skill_tokens=config.preserve_recent_skill_tokens,
        preserve_recent_skill_tokens_per_skill=config.preserve_recent_skill_tokens_per_skill,
    )
 def _create_todo_list_middleware(is_plan_mode: bool) -> TodoMiddleware | None:
@@ -257,8 +224,7 @@ def _build_middlewares(config: RunnableConfig, model_name: str | None, agent_nam
        middlewares.append(summarization_middleware)
    # Add TodoList middleware if plan mode is enabled
-    cfg = _get_runtime_config(config)
+    is_plan_mode = config.get("configurable", {}).get("is_plan_mode", False)
    is_plan_mode = cfg.get("is_plan_mode", False)
    todo_list_middleware = _create_todo_list_middleware(is_plan_mode)
    if todo_list_middleware is not None:
        middlewares.append(todo_list_middleware)
@@ -287,9 +253,9 @@ def _build_middlewares(config: RunnableConfig, model_name: str | None, agent_nam
        middlewares.append(DeferredToolFilterMiddleware())
    # Add SubagentLimitMiddleware to truncate excess parallel task calls
-    subagent_enabled = cfg.get("subagent_enabled", False)
+    subagent_enabled = config.get("configurable", {}).get("subagent_enabled", False)
    if subagent_enabled:
-        max_concurrent_subagents = cfg.get("max_concurrent_subagents", 3)
+        max_concurrent_subagents = config.get("configurable", {}).get("max_concurrent_subagents", 3)
        middlewares.append(SubagentLimitMiddleware(max_concurrent=max_concurrent_subagents))
    # LoopDetectionMiddleware — detect and break repetitive tool call loops
@@ -309,7 +275,7 @@ def make_lead_agent(config: RunnableConfig):
    from deerflow.tools import get_available_tools
    from deerflow.tools.builtins import setup_agent
-    cfg = _get_runtime_config(config)
+    cfg = config.get("configurable", {})
    thinking_enabled = cfg.get("thinking_enabled", True)
    reasoning_effort = cfg.get("reasoning_effort", None)
@@ -318,17 +284,17 @@ 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 = validate_agent_name(cfg.get("agent_name"))
+    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
+    # Custom agent model or fallback to global/default model resolution
-    agent_model_name = agent_config.model if agent_config and agent_config.model else None
+    agent_model_name = agent_config.model if agent_config and agent_config.model else _resolve_model_name()
-    # Final model name resolution: request → agent config → global default, with fallback for unknown names
+    # Final model name resolution with request override, then agent config, then global default
-    model_name = _resolve_model_name(requested_model_name or agent_model_name)
+    model_name = requested_model_name or agent_model_name
    app_config = get_app_config()
-    model_config = app_config.get_model_config(model_name)
+    model_config = app_config.get_model_config(model_name) if model_name else None
    if model_config is None:
        raise ValueError("No chat model could be resolved. Please configure at least one model in config.yaml or provide a valid 'model_name'/'model' in the request.")
@@ -359,8 +325,6 @@ 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,
            "available_skills": ["bootstrap"] if is_bootstrap else (agent_config.skills if agent_config and agent_config.skills is not None else None),
        }
    )
@@ -379,8 +343,6 @@ def make_lead_agent(config: RunnableConfig):
        model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, reasoning_effort=reasoning_effort),
        tools=get_available_tools(model_name=model_name, groups=agent_config.tool_groups if agent_config else None, subagent_enabled=subagent_enabled),
        middleware=_build_middlewares(config, model_name=model_name, agent_name=agent_name),
-        system_prompt=apply_prompt_template(
+        system_prompt=apply_prompt_template(subagent_enabled=subagent_enabled, max_concurrent_subagents=max_concurrent_subagents, agent_name=agent_name),
            subagent_enabled=subagent_enabled, max_concurrent_subagents=max_concurrent_subagents, agent_name=agent_name, available_skills=set(agent_config.skills) if agent_config and agent_config.skills is not None else None
        ),
        state_schema=ThreadState,
    )
@@ -1,198 +1,12 @@
 import asyncio
 import logging
 import threading
 from datetime import datetime
 from functools import lru_cache
 from deerflow.config.agents_config import load_agent_soul
 from deerflow.skills import load_skills
 from deerflow.skills.types import Skill
 from deerflow.subagents import get_available_subagent_names
 logger = logging.getLogger(__name__)
 _ENABLED_SKILLS_REFRESH_WAIT_TIMEOUT_SECONDS = 5.0
 _enabled_skills_lock = threading.Lock()
 _enabled_skills_cache: list[Skill] | None = None
 _enabled_skills_refresh_active = False
 _enabled_skills_refresh_version = 0
 _enabled_skills_refresh_event = threading.Event()
 def _load_enabled_skills_sync() -> list[Skill]:
    return list(load_skills(enabled_only=True))
 def _start_enabled_skills_refresh_thread() -> None:
    threading.Thread(
        target=_refresh_enabled_skills_cache_worker,
        name="deerflow-enabled-skills-loader",
        daemon=True,
    ).start()
 def _refresh_enabled_skills_cache_worker() -> None:
    global _enabled_skills_cache, _enabled_skills_refresh_active
    while True:
        with _enabled_skills_lock:
            target_version = _enabled_skills_refresh_version
        try:
            skills = _load_enabled_skills_sync()
        except Exception:
            logger.exception("Failed to load enabled skills for prompt injection")
            skills = []
        with _enabled_skills_lock:
            if _enabled_skills_refresh_version == target_version:
                _enabled_skills_cache = skills
                _enabled_skills_refresh_active = False
                _enabled_skills_refresh_event.set()
                return
            # A newer invalidation happened while loading. Keep the worker alive
            # and loop again so the cache always converges on the latest version.
            _enabled_skills_cache = None
 def _ensure_enabled_skills_cache() -> threading.Event:
    global _enabled_skills_refresh_active
    with _enabled_skills_lock:
        if _enabled_skills_cache is not None:
            _enabled_skills_refresh_event.set()
            return _enabled_skills_refresh_event
        if _enabled_skills_refresh_active:
            return _enabled_skills_refresh_event
        _enabled_skills_refresh_active = True
        _enabled_skills_refresh_event.clear()
    _start_enabled_skills_refresh_thread()
    return _enabled_skills_refresh_event
 def _invalidate_enabled_skills_cache() -> threading.Event:
    global _enabled_skills_cache, _enabled_skills_refresh_active, _enabled_skills_refresh_version
    _get_cached_skills_prompt_section.cache_clear()
    with _enabled_skills_lock:
        _enabled_skills_cache = None
        _enabled_skills_refresh_version += 1
        _enabled_skills_refresh_event.clear()
        if _enabled_skills_refresh_active:
            return _enabled_skills_refresh_event
        _enabled_skills_refresh_active = True
    _start_enabled_skills_refresh_thread()
    return _enabled_skills_refresh_event
 def prime_enabled_skills_cache() -> None:
    _ensure_enabled_skills_cache()
 def warm_enabled_skills_cache(timeout_seconds: float = _ENABLED_SKILLS_REFRESH_WAIT_TIMEOUT_SECONDS) -> bool:
    if _ensure_enabled_skills_cache().wait(timeout=timeout_seconds):
        return True
    logger.warning("Timed out waiting %.1fs for enabled skills cache warm-up", timeout_seconds)
    return False
 def _get_enabled_skills():
    with _enabled_skills_lock:
        cached = _enabled_skills_cache
    if cached is not None:
        return list(cached)
    _ensure_enabled_skills_cache()
    return []
 def _skill_mutability_label(category: str) -> str:
    return "[custom, editable]" if category == "custom" else "[built-in]"
 def clear_skills_system_prompt_cache() -> None:
    _invalidate_enabled_skills_cache()
 async def refresh_skills_system_prompt_cache_async() -> None:
    await asyncio.to_thread(_invalidate_enabled_skills_cache().wait)
 def _reset_skills_system_prompt_cache_state() -> None:
    global _enabled_skills_cache, _enabled_skills_refresh_active, _enabled_skills_refresh_version
    _get_cached_skills_prompt_section.cache_clear()
    with _enabled_skills_lock:
        _enabled_skills_cache = None
        _enabled_skills_refresh_active = False
        _enabled_skills_refresh_version = 0
        _enabled_skills_refresh_event.clear()
 def _refresh_enabled_skills_cache() -> None:
    """Backward-compatible test helper for direct synchronous reload."""
    try:
        skills = _load_enabled_skills_sync()
    except Exception:
        logger.exception("Failed to load enabled skills for prompt injection")
        skills = []
    with _enabled_skills_lock:
        _enabled_skills_cache = skills
        _enabled_skills_refresh_active = False
        _enabled_skills_refresh_event.set()
 def _build_skill_evolution_section(skill_evolution_enabled: bool) -> str:
    if not skill_evolution_enabled:
        return ""
    return """
 ## Skill Self-Evolution
 After completing a task, consider creating or updating a skill when:
 - The task required 5+ tool calls to resolve
 - You overcame non-obvious errors or pitfalls
 - The user corrected your approach and the corrected version worked
 - You discovered a non-trivial, recurring workflow
 If you used a skill and encountered issues not covered by it, patch it immediately.
 Prefer patch over edit. Before creating a new skill, confirm with the user first.
 Skip simple one-off tasks.
 """
 def _build_available_subagents_description(available_names: list[str], bash_available: bool) -> str:
    """Dynamically build subagent type descriptions from registry.
    Mirrors Codex's pattern where agent_type_description is dynamically generated
    from all registered roles, so the LLM knows about every available type.
    """
    # Built-in descriptions (kept for backward compatibility with existing prompt quality)
    builtin_descriptions = {
        "general-purpose": "For ANY non-trivial task - web research, code exploration, file operations, analysis, etc.",
        "bash": (
            "For command execution (git, build, test, deploy operations)" if bash_available else "Not available in the current sandbox configuration. Use direct file/web tools or switch to AioSandboxProvider for isolated shell access."
        ),
    }
    # Lazy import moved outside loop to avoid repeated import overhead
    from deerflow.subagents.registry import get_subagent_config
    lines = []
    for name in available_names:
        if name in builtin_descriptions:
            lines.append(f"- **{name}**: {builtin_descriptions[name]}")
        else:
            config = get_subagent_config(name)
            if config is not None:
                desc = config.description.split("\n")[0].strip()  # First line only for brevity
                lines.append(f"- **{name}**: {desc}")
    return "\n".join(lines)
 def _build_subagent_section(max_concurrent: int) -> str:
    """Build the subagent system prompt section with dynamic concurrency limit.
@@ -204,12 +18,13 @@ def _build_subagent_section(max_concurrent: int) -> str:
        Formatted subagent section string.
    """
    n = max_concurrent
-    available_names = get_available_subagent_names()
+    bash_available = "bash" in get_available_subagent_names()
-    bash_available = "bash" in available_names
+    available_subagents = (
-
+        "- **general-purpose**: For ANY non-trivial task - web research, code exploration, file operations, analysis, etc.\n- **bash**: For command execution (git, build, test, deploy operations)"
-    # Dynamically build subagent type descriptions from registry (aligned with Codex's
+        if bash_available
-    # agent_type_description pattern where all registered roles are listed in the tool spec).
+        else "- **general-purpose**: For ANY non-trivial task - web research, code exploration, file operations, analysis, etc.\n"
-    available_subagents = _build_available_subagents_description(available_names, bash_available)
+        "- **bash**: Not available in the current sandbox configuration. Use direct file/web tools or switch to AioSandboxProvider for isolated shell access."
    )
    direct_tool_examples = "bash, ls, read_file, web_search, etc." if bash_available else "ls, read_file, web_search, etc."
    direct_execution_example = (
        '# User asks: "Run the tests"\n# Thinking: Cannot decompose into parallel sub-tasks\n# → Execute directly\n\nbash("npm test")  # Direct execution, not task()'
@@ -446,10 +261,7 @@ You: "Deploying to staging..." [proceed]
 - Use `read_file` tool to read uploaded files using their paths from the list
 - For PDF, PPT, Excel, and Word files, converted Markdown versions (*.md) are available alongside originals
 - All temporary work happens in `/mnt/user-data/workspace`
- Treat `/mnt/user-data/workspace` as your default current working directory for coding and file-editing tasks
+- Final deliverables must be copied to `/mnt/user-data/outputs` and presented using `present_file` tool
 - When writing scripts or commands that create/read files from the workspace, prefer relative paths such as `hello.txt`, `../uploads/data.csv`, and `../outputs/report.md`
 - Avoid hardcoding `/mnt/user-data/...` inside generated scripts when a relative path from the workspace is enough
 - Final deliverables must be copied to `/mnt/user-data/outputs` and presented using `present_files` tool
 {acp_section}
 </working_directory>
@@ -568,21 +380,33 @@ def _get_memory_context(agent_name: str | None = None) -> str:
        return ""
-@lru_cache(maxsize=32)
+def get_skills_prompt_section(available_skills: set[str] | None = None) -> str:
-def _get_cached_skills_prompt_section(
+    """Generate the skills prompt section with available skills list.
-    skill_signature: tuple[tuple[str, str, str, str], ...],
+
-    available_skills_key: tuple[str, ...] | None,
+    Returns the <skill_system>...</skill_system> block listing all enabled skills,
-    container_base_path: str,
+    suitable for injection into any agent's system prompt.
-    skill_evolution_section: str,
+    """
-) -> str:
+    skills = load_skills(enabled_only=True)
-    filtered = [(name, description, category, location) for name, description, category, location in skill_signature if available_skills_key is None or name in available_skills_key]
+
-    skills_list = ""
+    try:
-    if filtered:
+        from deerflow.config import get_app_config
-        skill_items = "\n".join(
+
-            f"    <skill>\n        <name>{name}</name>\n        <description>{description} {_skill_mutability_label(category)}</description>\n        <location>{location}</location>\n    </skill>"
+        config = get_app_config()
-            for name, description, category, location in filtered
+        container_base_path = config.skills.container_path
-        )
+    except Exception:
-        skills_list = f"<available_skills>\n{skill_items}\n</available_skills>"
+        container_base_path = "/mnt/skills"
    if not skills:
        return ""
    if available_skills is not None:
        skills = [skill for skill in skills if skill.name in available_skills]
    skill_items = "\n".join(
        f"    <skill>\n        <name>{skill.name}</name>\n        <description>{skill.description}</description>\n        <location>{skill.get_container_file_path(container_base_path)}</location>\n    </skill>" for skill in skills
    )
    skills_list = f"<available_skills>\n{skill_items}\n</available_skills>"
    return f"""<skill_system>
 You have access to skills that provide optimized workflows for specific tasks. Each skill contains best practices, frameworks, and references to additional resources.
@@ -594,40 +418,12 @@ You have access to skills that provide optimized workflows for specific tasks. E
 5. Follow the skill's instructions precisely
 **Skills are located at:** {container_base_path}
-{skill_evolution_section}
+
 {skills_list}
 </skill_system>"""
 def get_skills_prompt_section(available_skills: set[str] | None = None) -> str:
    """Generate the skills prompt section with available skills list."""
    skills = _get_enabled_skills()
    try:
        from deerflow.config import get_app_config
        config = get_app_config()
        container_base_path = config.skills.container_path
        skill_evolution_enabled = config.skill_evolution.enabled
    except Exception:
        container_base_path = "/mnt/skills"
        skill_evolution_enabled = False
    if not skills and not skill_evolution_enabled:
        return ""
    if available_skills is not None and not any(skill.name in available_skills for skill in skills):
        return ""
    skill_signature = tuple((skill.name, skill.description, skill.category, skill.get_container_file_path(container_base_path)) for skill in skills)
    available_key = tuple(sorted(available_skills)) if available_skills is not None else None
    if not skill_signature and available_key is not None:
        return ""
    skill_evolution_section = _build_skill_evolution_section(skill_evolution_enabled)
    return _get_cached_skills_prompt_section(skill_signature, available_key, container_base_path, skill_evolution_section)
 def get_agent_soul(agent_name: str | None) -> str:
    # Append SOUL.md (agent personality) if present
    soul = load_agent_soul(agent_name)
@@ -650,7 +446,7 @@ def get_deferred_tools_prompt_section() -> str:
        if not get_app_config().tool_search.enabled:
            return ""
-    except Exception:
+    except FileNotFoundError:
        return ""
    registry = get_deferred_registry()
@@ -677,32 +473,10 @@ def _build_acp_section() -> str:
        "- ACP agents (e.g. codex, claude_code) run in their own independent workspace — NOT in `/mnt/user-data/`\n"
        "- When writing prompts for ACP agents, describe the task only — do NOT reference `/mnt/user-data` paths\n"
        "- ACP agent results are accessible at `/mnt/acp-workspace/` (read-only) — use `ls`, `read_file`, or `bash cp` to retrieve output files\n"
-        "- To deliver ACP output to the user: copy from `/mnt/acp-workspace/<file>` to `/mnt/user-data/outputs/<file>`, then use `present_files`"
+        "- To deliver ACP output to the user: copy from `/mnt/acp-workspace/<file>` to `/mnt/user-data/outputs/<file>`, then use `present_file`"
    )
 def _build_custom_mounts_section() -> str:
    """Build a prompt section for explicitly configured sandbox mounts."""
    try:
        from deerflow.config import get_app_config
        mounts = get_app_config().sandbox.mounts or []
    except Exception:
        logger.exception("Failed to load configured sandbox mounts for the lead-agent prompt")
        return ""
    if not mounts:
        return ""
    lines = []
    for mount in mounts:
        access = "read-only" if mount.read_only else "read-write"
        lines.append(f"- Custom mount: `{mount.container_path}` - Host directory mapped into the sandbox ({access})")
    mounts_list = "\n".join(lines)
    return f"\n**Custom Mounted Directories:**\n{mounts_list}\n- If the user needs files outside `/mnt/user-data`, use these absolute container paths directly when they match the requested directory"
 def apply_prompt_template(subagent_enabled: bool = False, max_concurrent_subagents: int = 3, *, agent_name: str | None = None, available_skills: set[str] | None = None) -> str:
    # Get memory context
    memory_context = _get_memory_context(agent_name)
@@ -737,8 +511,6 @@ def apply_prompt_template(subagent_enabled: bool = False, max_concurrent_subagen
    # Build ACP agent section only if ACP agents are configured
    acp_section = _build_acp_section()
    custom_mounts_section = _build_custom_mounts_section()
    acp_and_mounts_section = "\n".join(section for section in (acp_section, custom_mounts_section) if section)
    # Format the prompt with dynamic skills and memory
    prompt = SYSTEM_PROMPT_TEMPLATE.format(
@@ -750,7 +522,7 @@ def apply_prompt_template(subagent_enabled: bool = False, max_concurrent_subagen
        subagent_section=subagent_section,
        subagent_reminder=subagent_reminder,
        subagent_thinking=subagent_thinking,
-        acp_section=acp_and_mounts_section,
+        acp_section=acp_section,
    )
    return prompt + f"\n<current_date>{datetime.now().strftime('%Y-%m-%d, %A')}</current_date>"
@@ -1,109 +0,0 @@
 """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
@@ -29,17 +29,6 @@ Instructions:
 2. Extract relevant facts, preferences, and context with specific details (numbers, names, technologies)
 3. Update the memory sections as needed following the detailed length guidelines below
 Before extracting facts, perform a structured reflection on the conversation:
 1. Error/Retry Detection: Did the agent encounter errors, require retries, or produce incorrect results?
   If yes, record the root cause and correct approach as a high-confidence fact with category "correction".
 2. User Correction Detection: Did the user correct the agent's direction, understanding, or output?
   If yes, record the correct interpretation or approach as a high-confidence fact with category "correction".
   Include what went wrong in "sourceError" only when category is "correction" and the mistake is explicit in the conversation.
 3. Project Constraint Discovery: Were any project-specific constraints discovered during the conversation?
   If yes, record them as facts with the most appropriate category and confidence.
 {correction_hint}
 Memory Section Guidelines:
 **User Context** (Current state - concise summaries):
@@ -73,7 +62,6 @@ Memory Section Guidelines:
  * context: Background facts (job title, projects, locations, languages)
  * behavior: Working patterns, communication habits, problem-solving approaches
  * goal: Stated objectives, learning targets, project ambitions
  * correction: Explicit agent mistakes or user corrections, including the correct approach
 - Confidence levels:
  * 0.9-1.0: Explicitly stated facts ("I work on X", "My role is Y")
  * 0.7-0.8: Strongly implied from actions/discussions
@@ -106,7 +94,7 @@ Output Format (JSON):
    "longTermBackground": {{ "summary": "...", "shouldUpdate": true/false }}
  }},
  "newFacts": [
-    {{ "content": "...", "category": "preference|knowledge|context|behavior|goal|correction", "confidence": 0.0-1.0 }}
+    {{ "content": "...", "category": "preference|knowledge|context|behavior|goal", "confidence": 0.0-1.0 }}
  ],
  "factsToRemove": ["fact_id_1", "fact_id_2"]
 }}
@@ -116,8 +104,6 @@ Important Rules:
 - Follow length guidelines: workContext/personalContext are concise (1-3 sentences), topOfMind and history sections are detailed (paragraphs)
 - Include specific metrics, version numbers, and proper nouns in facts
 - Only add facts that are clearly stated (0.9+) or strongly implied (0.7+)
 - Use category "correction" for explicit agent mistakes or user corrections; assign confidence >= 0.95 when the correction is explicit
 - Include "sourceError" only for explicit correction facts when the prior mistake or wrong approach is clearly stated; omit it otherwise
 - Remove facts that are contradicted by new information
 - When updating topOfMind, integrate new focus areas while removing completed/abandoned ones
  Keep 3-5 concurrent focus themes that are still active and relevant
@@ -140,7 +126,7 @@ Message:
 Extract facts in this JSON format:
 {{
  "facts": [
-    {{ "content": "...", "category": "preference|knowledge|context|behavior|goal|correction", "confidence": 0.0-1.0 }}
+    {{ "content": "...", "category": "preference|knowledge|context|behavior|goal", "confidence": 0.0-1.0 }}
  ]
 }}
@@ -150,7 +136,6 @@ Categories:
 - context: Background context (location, job, projects)
 - behavior: Behavioral patterns
 - goal: User's goals or objectives
 - correction: Explicit corrections or mistakes to avoid repeating
 Rules:
 - Only extract clear, specific facts
@@ -246,10 +231,6 @@ def format_memory_for_injection(memory_data: dict[str, Any], max_tokens: int = 2
        if earlier.get("summary"):
            history_sections.append(f"Earlier: {earlier['summary']}")
        background = history_data.get("longTermBackground", {})
        if background.get("summary"):
            history_sections.append(f"Background: {background['summary']}")
        if history_sections:
            sections.append("History:\n" + "\n".join(f"- {s}" for s in history_sections))
@@ -281,11 +262,7 @@ def format_memory_for_injection(memory_data: dict[str, Any], max_tokens: int = 2
                continue
            category = str(fact.get("category", "context")).strip() or "context"
            confidence = _coerce_confidence(fact.get("confidence"), default=0.0)
-            source_error = fact.get("sourceError")
+            line = f"- [{category} | {confidence:.2f}] {content}"
            if category == "correction" and isinstance(source_error, str) and source_error.strip():
                line = f"- [{category} | {confidence:.2f}] {content} (avoid: {source_error.strip()})"
            else:
                line = f"- [{category} | {confidence:.2f}] {content}"
            # Each additional line is preceded by a newline (except the first).
            line_text = ("\n" + line) if fact_lines else line
@@ -4,7 +4,7 @@ import logging
 import threading
 import time
 from dataclasses import dataclass, field
-from datetime import UTC, datetime
+from datetime import datetime
 from typing import Any
 from deerflow.config.memory_config import get_memory_config
@@ -18,10 +18,8 @@ class ConversationContext:
    thread_id: str
    messages: list[Any]
-    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    timestamp: datetime = field(default_factory=datetime.utcnow)
    agent_name: str | None = None
    correction_detected: bool = False
    reinforcement_detected: bool = False
 class MemoryUpdateQueue:
@@ -39,110 +37,53 @@ class MemoryUpdateQueue:
        self._timer: threading.Timer | None = None
        self._processing = False
-    def add(
+    def add(self, thread_id: str, messages: list[Any], agent_name: str | None = None) -> None:
        self,
        thread_id: str,
        messages: list[Any],
        agent_name: str | None = None,
        correction_detected: bool = False,
        reinforcement_detected: bool = False,
    ) -> None:
        """Add a conversation to the update queue.
        Args:
            thread_id: The thread ID.
            messages: The conversation messages.
            agent_name: If provided, memory is stored per-agent. If None, uses global memory.
            correction_detected: Whether recent turns include an explicit correction signal.
            reinforcement_detected: Whether recent turns include a positive reinforcement signal.
        """
        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._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]
+        with self._lock:
-        self._queue.append(context)
+            # 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 _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(
-            delay_seconds,
+            config.debounce_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
@@ -150,8 +91,8 @@ class MemoryUpdateQueue:
        with self._lock:
            if self._processing:
-                # Preserve immediate flush semantics even if another worker is active.
+                # Already processing, reschedule
-                self._schedule_timer(0)
+                self._reset_timer()
                return
            if not self._queue:
@@ -174,8 +115,6 @@ class MemoryUpdateQueue:
                        messages=context.messages,
                        thread_id=context.thread_id,
                        agent_name=context.agent_name,
                        correction_detected=context.correction_detected,
                        reinforcement_detected=context.reinforcement_detected,
                    )
                    if success:
                        logger.info("Memory updated successfully for thread %s", context.thread_id)
@@ -204,13 +143,6 @@ 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.
@@ -4,8 +4,7 @@ import abc
 import json
 import logging
 import threading
-import uuid
+from datetime import datetime
 from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
@@ -16,16 +15,11 @@ from deerflow.config.paths import get_paths
 logger = logging.getLogger(__name__)
 def utc_now_iso_z() -> str:
    """Current UTC time as ISO-8601 with ``Z`` suffix (matches prior naive-UTC output)."""
    return datetime.now(UTC).isoformat().removesuffix("+00:00") + "Z"
 def create_empty_memory() -> dict[str, Any]:
    """Create an empty memory structure."""
    return {
        "version": "1.0",
-        "lastUpdated": utc_now_iso_z(),
+        "lastUpdated": datetime.utcnow().isoformat() + "Z",
        "user": {
            "workContext": {"summary": "", "updatedAt": ""},
            "personalContext": {"summary": "", "updatedAt": ""},
@@ -67,8 +61,6 @@ 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.
@@ -117,17 +109,14 @@ class FileMemoryStorage(MemoryStorage):
        except OSError:
            current_mtime = None
-        with self._cache_lock:
+        cached = self._memory_cache.get(agent_name)
            cached = self._memory_cache.get(agent_name)
            if cached is not None and cached[1] == current_mtime:
                return cached[0]
-        memory_data = self._load_memory_from_file(agent_name)
+        if cached is None or cached[1] != current_mtime:
-
+            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 memory_data
+        return cached[0]
    def reload(self, agent_name: str | None = None) -> dict[str, Any]:
        """Reload memory data from file, forcing cache invalidation."""
@@ -139,8 +128,7 @@ class FileMemoryStorage(MemoryStorage):
        except OSError:
            mtime = None
-        with self._cache_lock:
+        self._memory_cache[agent_name] = (memory_data, mtime)
            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:
@@ -149,12 +137,9 @@ class FileMemoryStorage(MemoryStorage):
        try:
            file_path.parent.mkdir(parents=True, exist_ok=True)
-            # Shallow-copy before adding lastUpdated so the caller's dict is not
+            memory_data["lastUpdated"] = datetime.utcnow().isoformat() + "Z"
            # 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(f".{uuid.uuid4().hex}.tmp")
+            temp_path = file_path.with_suffix(".tmp")
            with open(temp_path, "w", encoding="utf-8") as f:
                json.dump(memory_data, f, indent=2, ensure_ascii=False)
@@ -165,8 +150,7 @@ class FileMemoryStorage(MemoryStorage):
            except OSError:
                mtime = None
-            with self._cache_lock:
+            self._memory_cache[agent_name] = (memory_data, mtime)
                self._memory_cache[agent_name] = (memory_data, mtime)
            logger.info("Memory saved to %s", file_path)
            return True
        except OSError as e:
@@ -1,31 +0,0 @@
 """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,
    )
@@ -1,37 +1,23 @@
 """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 datetime import datetime
 from typing import Any
 from deerflow.agents.memory.prompt import (
    MEMORY_UPDATE_PROMPT,
    format_conversation_for_update,
 )
-from deerflow.agents.memory.storage import (
+from deerflow.agents.memory.storage import create_empty_memory, get_memory_storage
    create_empty_memory,
    get_memory_storage,
    utc_now_iso_z,
 )
 from deerflow.config.memory_config import get_memory_config
 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."""
@@ -100,7 +86,7 @@ def create_memory_fact(
    normalized_category = category.strip() or "context"
    validated_confidence = _validate_confidence(confidence)
-    now = utc_now_iso_z()
+    now = datetime.utcnow().isoformat() + "Z"
    memory_data = get_memory_data(agent_name)
    updated_memory = dict(memory_data)
    facts = list(memory_data.get("facts", []))
@@ -217,39 +203,6 @@ 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".
@@ -293,7 +246,7 @@ def _fact_content_key(content: Any) -> str | None:
    stripped = content.strip()
    if not stripped:
        return None
-    return stripped.casefold()
+    return stripped
 class MemoryUpdater:
@@ -313,110 +266,65 @@ 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(
+    def update_memory(self, messages: list[Any], thread_id: str | None = None, agent_name: str | None = None) -> bool:
-        self,
+        """Update memory based on conversation messages.
        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
+        Args:
            messages: List of conversation messages.
            thread_id: Optional thread ID for tracking source.
            agent_name: If provided, updates per-agent memory. If None, updates global memory.
-    def _prepare_update_prompt(
+        Returns:
-        self,
+            True if update was successful, False otherwise.
-        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:
+        if not config.enabled:
-            return None
+            return False
-        current_memory = get_memory_data(agent_name)
+        if not messages:
-        conversation_text = format_conversation_for_update(messages)
+            return False
        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(
+            # Get current memory
-                self._prepare_update_prompt,
+            current_memory = get_memory_data(agent_name)
-                messages=messages,
+
-                agent_name=agent_name,
+            # Format conversation for prompt
-                correction_detected=correction_detected,
+            conversation_text = format_conversation_for_update(messages)
-                reinforcement_detected=reinforcement_detected,
+
-            )
+            if not conversation_text.strip():
            if prepared is None:
                return False
-            current_memory, prompt = prepared
+            # Build prompt
-            model = self._get_model()
+            prompt = MEMORY_UPDATE_PROMPT.format(
-            response = await model.ainvoke(prompt, config={"run_name": "memory_agent"})
+                current_memory=json.dumps(current_memory, indent=2),
-            return await asyncio.to_thread(
+                conversation=conversation_text,
                self._finalize_update,
                current_memory=current_memory,
                response_content=response.content,
                thread_id=thread_id,
                agent_name=agent_name,
            )
            # 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
@@ -424,36 +332,6 @@ class MemoryUpdater:
            logger.exception("Memory update failed: %s", e)
            return False
    def update_memory(
        self,
        messages: list[Any],
        thread_id: str | None = None,
        agent_name: str | None = None,
        correction_detected: bool = False,
        reinforcement_detected: bool = False,
    ) -> bool:
        """Synchronously update memory via the async updater path.
        Args:
            messages: List of conversation messages.
            thread_id: Optional thread ID for tracking source.
            agent_name: If provided, updates per-agent memory. If None, updates global memory.
            correction_detected: Whether recent turns include an explicit correction signal.
            reinforcement_detected: Whether recent turns include a positive reinforcement signal.
        Returns:
            True if update was successful, False otherwise.
        """
        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,
            )
        )
    def _apply_updates(
        self,
        current_memory: dict[str, Any],
@@ -471,7 +349,7 @@ class MemoryUpdater:
            Updated memory data.
        """
        config = get_memory_config()
-        now = utc_now_iso_z()
+        now = datetime.utcnow().isoformat() + "Z"
        # Update user sections
        user_updates = update_data.get("user", {})
@@ -505,8 +383,6 @@ class MemoryUpdater:
            confidence = fact.get("confidence", 0.5)
            if confidence >= config.fact_confidence_threshold:
                raw_content = fact.get("content", "")
                if not isinstance(raw_content, str):
                    continue
                normalized_content = raw_content.strip()
                fact_key = _fact_content_key(normalized_content)
                if fact_key is not None and fact_key in existing_fact_keys:
@@ -520,11 +396,6 @@ class MemoryUpdater:
                    "createdAt": now,
                    "source": thread_id or "unknown",
                }
                source_error = fact.get("sourceError")
                if isinstance(source_error, str):
                    normalized_source_error = source_error.strip()
                    if normalized_source_error:
                        fact_entry["sourceError"] = normalized_source_error
                current_memory["facts"].append(fact_entry)
                if fact_key is not None:
                    existing_fact_keys.add(fact_key)
@@ -541,24 +412,16 @@ class MemoryUpdater:
        return current_memory
-def update_memory_from_conversation(
+def update_memory_from_conversation(messages: list[Any], thread_id: str | None = None, agent_name: str | None = None) -> bool:
    messages: list[Any],
    thread_id: str | None = None,
    agent_name: str | None = None,
    correction_detected: bool = False,
    reinforcement_detected: bool = False,
 ) -> bool:
    """Convenience function to update memory from a conversation.
    Args:
        messages: List of conversation messages.
        thread_id: Optional thread ID.
        agent_name: If provided, updates per-agent memory. If None, updates global memory.
        correction_detected: Whether recent turns include an explicit correction signal.
        reinforcement_detected: Whether recent turns include a positive reinforcement signal.
    Returns:
        True if successful, False otherwise.
    """
    updater = MemoryUpdater()
-    return updater.update_memory(messages, thread_id, agent_name, correction_detected, reinforcement_detected)
+    return updater.update_memory(messages, thread_id, agent_name)
@@ -1,9 +1,7 @@
 """Middleware for intercepting clarification requests and presenting them to the user."""
 import json
 import logging
 from collections.abc import Callable
 from hashlib import sha256
 from typing import override
 from langchain.agents import AgentState
@@ -37,13 +35,6 @@ class ClarificationMiddleware(AgentMiddleware[ClarificationMiddlewareState]):
    state_schema = ClarificationMiddlewareState
    def _stable_message_id(self, tool_call_id: str, formatted_message: str) -> str:
        """Build a deterministic message ID so retried clarification calls replace, not append."""
        if tool_call_id:
            return f"clarification:{tool_call_id}"
        digest = sha256(formatted_message.encode("utf-8")).hexdigest()[:16]
        return f"clarification:{digest}"
    def _is_chinese(self, text: str) -> bool:
        """Check if text contains Chinese characters.
@@ -69,20 +60,6 @@ class ClarificationMiddleware(AgentMiddleware[ClarificationMiddlewareState]):
        context = args.get("context")
        options = args.get("options", [])
        # Some models (e.g. Qwen3-Max) serialize array parameters as JSON strings
        # instead of native arrays. Deserialize and normalize so `options`
        # is always a list for the rendering logic below.
        if isinstance(options, str):
            try:
                options = json.loads(options)
            except (json.JSONDecodeError, TypeError):
                options = [options]
        if options is None:
            options = []
        elif not isinstance(options, list):
            options = [options]
        # Type-specific icons
        type_icons = {
            "missing_info": "❓",
@@ -139,7 +116,6 @@ class ClarificationMiddleware(AgentMiddleware[ClarificationMiddlewareState]):
        # Create a ToolMessage with the formatted question
        # This will be added to the message history
        tool_message = ToolMessage(
            id=self._stable_message_id(tool_call_id, formatted_message),
            content=formatted_message,
            tool_call_id=tool_call_id,
            name="ask_clarification",
@@ -13,7 +13,6 @@ 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
@@ -34,44 +33,6 @@ 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.
@@ -90,7 +51,7 @@ class DanglingToolCallMiddleware(AgentMiddleware[AgentState]):
        for msg in messages:
            if getattr(msg, "type", None) != "ai":
                continue
-            for tc in self._message_tool_calls(msg):
+            for tc in getattr(msg, "tool_calls", None) or []:
                tc_id = tc.get("id")
                if tc_id and tc_id not in existing_tool_msg_ids:
                    needs_patch = True
@@ -109,7 +70,7 @@ class DanglingToolCallMiddleware(AgentMiddleware[AgentState]):
            patched.append(msg)
            if getattr(msg, "type", None) != "ai":
                continue
-            for tc in self._message_tool_calls(msg):
+            for tc in getattr(msg, "tool_calls", None) or []:
                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(
@@ -16,9 +16,6 @@ from typing import override
 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
 from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
 from langchain_core.messages import ToolMessage
 from langgraph.prebuilt.tool_node import ToolCallRequest
 from langgraph.types import Command
 logger = logging.getLogger(__name__)
@@ -38,7 +35,7 @@ class DeferredToolFilterMiddleware(AgentMiddleware[AgentState]):
        if not registry:
            return request
-        deferred_names = registry.deferred_names
+        deferred_names = {e.name for e in registry.entries}
        active_tools = [t for t in request.tools if getattr(t, "name", None) not in deferred_names]
        if len(active_tools) < len(request.tools):
@@ -46,28 +43,6 @@ class DeferredToolFilterMiddleware(AgentMiddleware[AgentState]):
        return request.override(tools=active_tools)
    def _blocked_tool_message(self, request: ToolCallRequest) -> ToolMessage | None:
        from deerflow.tools.builtins.tool_search import get_deferred_registry
        registry = get_deferred_registry()
        if not registry:
            return None
        tool_name = str(request.tool_call.get("name") or "")
        if not tool_name:
            return None
        if not registry.contains(tool_name):
            return None
        tool_call_id = str(request.tool_call.get("id") or "missing_tool_call_id")
        return ToolMessage(
            content=(f"Error: Tool '{tool_name}' is deferred and has not been promoted yet. Call tool_search first to expose and promote this tool's schema, then retry."),
            tool_call_id=tool_call_id,
            name=tool_name,
            status="error",
        )
    @override
    def wrap_model_call(
        self,
@@ -76,17 +51,6 @@ class DeferredToolFilterMiddleware(AgentMiddleware[AgentState]):
    ) -> ModelCallResult:
        return handler(self._filter_tools(request))
    @override
    def wrap_tool_call(
        self,
        request: ToolCallRequest,
        handler: Callable[[ToolCallRequest], ToolMessage | Command],
    ) -> ToolMessage | Command:
        blocked = self._blocked_tool_message(request)
        if blocked is not None:
            return blocked
        return handler(request)
    @override
    async def awrap_model_call(
        self,
@@ -94,14 +58,3 @@ class DeferredToolFilterMiddleware(AgentMiddleware[AgentState]):
        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
    ) -> ModelCallResult:
        return await handler(self._filter_tools(request))
    @override
    async def awrap_tool_call(
        self,
        request: ToolCallRequest,
        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
    ) -> ToolMessage | Command:
        blocked = self._blocked_tool_message(request)
        if blocked is not None:
            return blocked
        return await handler(request)
@@ -1,377 +0,0 @@
 """LLM error handling middleware with retry/backoff and user-facing fallbacks."""
 from __future__ import annotations
 import asyncio
 import logging
 import threading
 import time
 from collections.abc import Awaitable, Callable
 from email.utils import parsedate_to_datetime
 from typing import Any, override
 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
 from langchain.agents.middleware.types import (
    ModelCallResult,
    ModelRequest,
    ModelResponse,
 )
 from langchain_core.messages import AIMessage
 from langgraph.errors import GraphBubbleUp
 from deerflow.config import get_app_config
 logger = logging.getLogger(__name__)
 _RETRIABLE_STATUS_CODES = {408, 409, 425, 429, 500, 502, 503, 504}
 _BUSY_PATTERNS = (
    "server busy",
    "temporarily unavailable",
    "try again later",
    "please retry",
    "please try again",
    "overloaded",
    "high demand",
    "rate limit",
    "负载较高",
    "服务繁忙",
    "稍后重试",
    "请稍后重试",
 )
 _QUOTA_PATTERNS = (
    "insufficient_quota",
    "quota",
    "billing",
    "credit",
    "payment",
    "余额不足",
    "超出限额",
    "额度不足",
    "欠费",
 )
 _AUTH_PATTERNS = (
    "authentication",
    "unauthorized",
    "invalid api key",
    "invalid_api_key",
    "permission",
    "forbidden",
    "access denied",
    "无权",
    "未授权",
 )
 class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
    """Retry transient LLM errors and surface graceful assistant messages."""
    retry_max_attempts: int = 3
    retry_base_delay_ms: int = 1000
    retry_cap_delay_ms: int = 8000
    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()
        error_code = _extract_error_code(exc)
        status_code = _extract_status_code(exc)
        if _matches_any(lowered, _QUOTA_PATTERNS) or _matches_any(str(error_code).lower(), _QUOTA_PATTERNS):
            return False, "quota"
        if _matches_any(lowered, _AUTH_PATTERNS):
            return False, "auth"
        exc_name = exc.__class__.__name__
        if exc_name in {
            "APITimeoutError",
            "APIConnectionError",
            "InternalServerError",
            "ReadError",  # httpx.ReadError: connection dropped mid-stream
            "RemoteProtocolError",  # httpx: server closed connection unexpectedly
        }:
            return True, "transient"
        if status_code in _RETRIABLE_STATUS_CODES:
            return True, "transient"
        if _matches_any(lowered, _BUSY_PATTERNS):
            return True, "busy"
        return False, "generic"
    def _build_retry_delay_ms(self, attempt: int, exc: BaseException) -> int:
        retry_after = _extract_retry_after_ms(exc)
        if retry_after is not None:
            return retry_after
        backoff = self.retry_base_delay_ms * (2 ** max(0, attempt - 1))
        return min(backoff, self.retry_cap_delay_ms)
    def _build_retry_message(self, attempt: int, wait_ms: int, reason: str) -> str:
        seconds = max(1, round(wait_ms / 1000))
        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":
            return "The configured LLM provider rejected the request because the account is out of quota, billing is unavailable, or usage is restricted. Please fix the provider account and try again."
        if reason == "auth":
            return "The configured LLM provider rejected the request because authentication or access is invalid. Please check the provider credentials and try again."
        if reason in {"busy", "transient"}:
            return "The configured LLM provider is temporarily unavailable after multiple retries. Please wait a moment and continue the conversation."
        return f"LLM request failed: {detail}"
    def _emit_retry_event(self, attempt: int, wait_ms: int, reason: str) -> None:
        try:
            from langgraph.config import get_stream_writer
            writer = get_stream_writer()
            writer(
                {
                    "type": "llm_retry",
                    "attempt": attempt,
                    "max_attempts": self.retry_max_attempts,
                    "wait_ms": wait_ms,
                    "reason": reason,
                    "message": self._build_retry_message(attempt, wait_ms, reason),
                }
            )
        except Exception:
            logger.debug("Failed to emit llm_retry event", exc_info=True)
    @override
    def wrap_model_call(
        self,
        request: ModelRequest,
        handler: Callable[[ModelRequest], ModelResponse],
    ) -> ModelCallResult:
        if self._check_circuit():
            return AIMessage(content=self._build_circuit_breaker_message())
        attempt = 1
        while True:
            try:
                response = handler(request)
                self._record_success()
                return response
            except GraphBubbleUp:
                # Preserve LangGraph control-flow signals (interrupt/pause/resume).
                with self._circuit_lock:
                    if self._circuit_state == "half_open":
                        self._circuit_probe_in_flight = False
                raise
            except Exception as exc:
                retriable, reason = self._classify_error(exc)
                if retriable and attempt < self.retry_max_attempts:
                    wait_ms = self._build_retry_delay_ms(attempt, exc)
                    logger.warning(
                        "Transient LLM error on attempt %d/%d; retrying in %dms: %s",
                        attempt,
                        self.retry_max_attempts,
                        wait_ms,
                        _extract_error_detail(exc),
                    )
                    self._emit_retry_event(attempt, wait_ms, reason)
                    time.sleep(wait_ms / 1000)
                    attempt += 1
                    continue
                logger.warning(
                    "LLM call failed after %d attempt(s): %s",
                    attempt,
                    _extract_error_detail(exc),
                    exc_info=exc,
                )
                if retriable:
                    self._record_failure()
                return AIMessage(content=self._build_user_message(exc, reason))
    @override
    async def awrap_model_call(
        self,
        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:
                response = await handler(request)
                self._record_success()
                return response
            except GraphBubbleUp:
                # Preserve LangGraph control-flow signals (interrupt/pause/resume).
                with self._circuit_lock:
                    if self._circuit_state == "half_open":
                        self._circuit_probe_in_flight = False
                raise
            except Exception as exc:
                retriable, reason = self._classify_error(exc)
                if retriable and attempt < self.retry_max_attempts:
                    wait_ms = self._build_retry_delay_ms(attempt, exc)
                    logger.warning(
                        "Transient LLM error on attempt %d/%d; retrying in %dms: %s",
                        attempt,
                        self.retry_max_attempts,
                        wait_ms,
                        _extract_error_detail(exc),
                    )
                    self._emit_retry_event(attempt, wait_ms, reason)
                    await asyncio.sleep(wait_ms / 1000)
                    attempt += 1
                    continue
                logger.warning(
                    "LLM call failed after %d attempt(s): %s",
                    attempt,
                    _extract_error_detail(exc),
                    exc_info=exc,
                )
                if retriable:
                    self._record_failure()
                return AIMessage(content=self._build_user_message(exc, reason))
 def _matches_any(detail: str, patterns: tuple[str, ...]) -> bool:
    return any(pattern in detail for pattern in patterns)
 def _extract_error_code(exc: BaseException) -> Any:
    for attr in ("code", "error_code"):
        value = getattr(exc, attr, None)
        if value not in (None, ""):
            return value
    body = getattr(exc, "body", None)
    if isinstance(body, dict):
        error = body.get("error")
        if isinstance(error, dict):
            for key in ("code", "type"):
                value = error.get(key)
                if value not in (None, ""):
                    return value
    return None
 def _extract_status_code(exc: BaseException) -> int | None:
    for attr in ("status_code", "status"):
        value = getattr(exc, attr, None)
        if isinstance(value, int):
            return value
    response = getattr(exc, "response", None)
    status = getattr(response, "status_code", None)
    return status if isinstance(status, int) else None
 def _extract_retry_after_ms(exc: BaseException) -> int | None:
    response = getattr(exc, "response", None)
    headers = getattr(response, "headers", None)
    if headers is None:
        return None
    raw = None
    header_name = ""
    for key in ("retry-after-ms", "Retry-After-Ms", "retry-after", "Retry-After"):
        header_name = key
        if hasattr(headers, "get"):
            raw = headers.get(key)
        if raw:
            break
    if not raw:
        return None
    try:
        multiplier = 1 if "ms" in header_name.lower() else 1000
        return max(0, int(float(raw) * multiplier))
    except (TypeError, ValueError):
        try:
            target = parsedate_to_datetime(str(raw))
            delta = target.timestamp() - time.time()
            return max(0, int(delta * 1000))
        except (TypeError, ValueError, OverflowError):
            return None
 def _extract_error_detail(exc: BaseException) -> str:
    detail = str(exc).strip()
    if detail:
        return detail
    message = getattr(exc, "message", None)
    if isinstance(message, str) and message.strip():
        return message.strip()
    return exc.__class__.__name__
@@ -17,7 +17,6 @@ import json
 import logging
 import threading
 from collections import OrderedDict, defaultdict
 from copy import deepcopy
 from typing import override
 from langchain.agents import AgentState
@@ -25,8 +24,6 @@ from langchain.agents.middleware import AgentMiddleware
 from langchain_core.messages import HumanMessage
 from langgraph.runtime import Runtime
 from deerflow.utils.runtime import get_thread_id
 logger = logging.getLogger(__name__)
 # Defaults — can be overridden via constructor
@@ -34,110 +31,40 @@ _DEFAULT_WARN_THRESHOLD = 3  # inject warning after 3 identical calls
 _DEFAULT_HARD_LIMIT = 5  # force-stop after 5 identical calls
 _DEFAULT_WINDOW_SIZE = 20  # track last N tool calls
 _DEFAULT_MAX_TRACKED_THREADS = 100  # LRU eviction limit
 _DEFAULT_TOOL_FREQ_WARN = 30  # warn after 30 calls to the same tool type
 _DEFAULT_TOOL_FREQ_HARD_LIMIT = 50  # force-stop after 50 calls to the same tool type
 def _normalize_tool_call_args(raw_args: object) -> tuple[dict, str | None]:
    """Normalize tool call args to a dict plus an optional fallback key.
    Some providers serialize ``args`` as a JSON string instead of a dict.
    We defensively parse those cases so loop detection does not crash while
    still preserving a stable fallback key for non-dict payloads.
    """
    if isinstance(raw_args, dict):
        return raw_args, None
    if isinstance(raw_args, str):
        try:
            parsed = json.loads(raw_args)
        except (TypeError, ValueError, json.JSONDecodeError):
            return {}, raw_args
        if isinstance(parsed, dict):
            return parsed, None
        return {}, json.dumps(parsed, sort_keys=True, default=str)
    if raw_args is None:
        return {}, None
    return {}, json.dumps(raw_args, sort_keys=True, default=str)
 def _stable_tool_key(name: str, args: dict, fallback_key: str | None) -> str:
    """Derive a stable key from salient args without overfitting to noise."""
    if name == "read_file" and fallback_key is None:
        path = args.get("path") or ""
        start_line = args.get("start_line")
        end_line = args.get("end_line")
        bucket_size = 200
        try:
            start_line = int(start_line) if start_line is not None else 1
        except (TypeError, ValueError):
            start_line = 1
        try:
            end_line = int(end_line) if end_line is not None else start_line
        except (TypeError, ValueError):
            end_line = start_line
        start_line, end_line = sorted((start_line, end_line))
        bucket_start = max(start_line, 1)
        bucket_end = max(end_line, 1)
        bucket_start = (bucket_start - 1) // bucket_size
        bucket_end = (bucket_end - 1) // bucket_size
        return f"{path}:{bucket_start}-{bucket_end}"
    # write_file / str_replace are content-sensitive: same path may be updated
    # with different payloads during iteration. Using only salient fields (path)
    # can collapse distinct calls, so we hash full args to reduce false positives.
    if name in {"write_file", "str_replace"}:
        if fallback_key is not None:
            return fallback_key
        return json.dumps(args, sort_keys=True, default=str)
    salient_fields = ("path", "url", "query", "command", "pattern", "glob", "cmd")
    stable_args = {field: args[field] for field in salient_fields if args.get(field) is not None}
    if stable_args:
        return json.dumps(stable_args, sort_keys=True, default=str)
    if fallback_key is not None:
        return fallback_key
    return json.dumps(args, sort_keys=True, default=str)
 def _hash_tool_calls(tool_calls: list[dict]) -> str:
-    """Deterministic hash of a set of tool calls (name + stable key).
+    """Deterministic hash of a set of tool calls (name + args).
    This is intended to be order-independent: the same multiset of tool calls
    should always produce the same hash, regardless of their input order.
    """
-    # Normalize each tool call to a stable (name, key) structure.
+    # First normalize each tool call to a minimal (name, args) structure.
-    normalized: list[str] = []
+    normalized: list[dict] = []
    for tc in tool_calls:
-        name = tc.get("name", "")
+        normalized.append(
-        args, fallback_key = _normalize_tool_call_args(tc.get("args", {}))
+            {
-        key = _stable_tool_key(name, args, fallback_key)
+                "name": tc.get("name", ""),
                "args": tc.get("args", {}),
            }
        )
-        normalized.append(f"{name}:{key}")
+    # Sort by both name and a deterministic serialization of args so that
-
+    # permutations of the same multiset of calls yield the same ordering.
-    # Sort so permutations of the same multiset of calls yield the same ordering.
+    normalized.sort(
-    normalized.sort()
+        key=lambda tc: (
            tc["name"],
            json.dumps(tc["args"], sort_keys=True, default=str),
        )
    )
    blob = json.dumps(normalized, sort_keys=True, default=str)
    return hashlib.md5(blob.encode()).hexdigest()[:12]
 _WARNING_MSG = "[LOOP DETECTED] You are repeating the same tool calls. Stop calling tools and produce your final answer now. If you cannot complete the task, summarize what you accomplished so far."
 _TOOL_FREQ_WARNING_MSG = (
    "[LOOP DETECTED] You have called {tool_name} {count} times without producing a final answer. Stop calling tools and produce your final answer now. If you cannot complete the task, summarize what you accomplished so far."
 )
 _HARD_STOP_MSG = "[FORCED STOP] Repeated tool calls exceeded the safety limit. Producing final answer with results collected so far."
 _TOOL_FREQ_HARD_STOP_MSG = "[FORCED STOP] Tool {tool_name} called {count} times — exceeded the per-tool safety limit. Producing final answer with results collected so far."
 class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
    """Detects and breaks repetitive tool call loops.
@@ -151,12 +78,6 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
            Default: 20.
        max_tracked_threads: Maximum number of threads to track before
            evicting the least recently used. Default: 100.
        tool_freq_warn: Number of calls to the same tool *type* (regardless
            of arguments) before injecting a frequency warning. Catches
            cross-file read loops that hash-based detection misses.
            Default: 30.
        tool_freq_hard_limit: Number of calls to the same tool type before
            forcing a stop. Default: 50.
    """
    def __init__(
@@ -165,27 +86,23 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
        hard_limit: int = _DEFAULT_HARD_LIMIT,
        window_size: int = _DEFAULT_WINDOW_SIZE,
        max_tracked_threads: int = _DEFAULT_MAX_TRACKED_THREADS,
        tool_freq_warn: int = _DEFAULT_TOOL_FREQ_WARN,
        tool_freq_hard_limit: int = _DEFAULT_TOOL_FREQ_HARD_LIMIT,
    ):
        super().__init__()
        self.warn_threshold = warn_threshold
        self.hard_limit = hard_limit
        self.window_size = window_size
        self.max_tracked_threads = max_tracked_threads
        self.tool_freq_warn = tool_freq_warn
        self.tool_freq_hard_limit = tool_freq_hard_limit
        self._lock = threading.Lock()
        # Per-thread tracking using OrderedDict for LRU eviction
        self._history: OrderedDict[str, list[str]] = OrderedDict()
        self._warned: dict[str, set[str]] = defaultdict(set)
        # Per-thread, per-tool-type cumulative call counts
        self._tool_freq: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
        self._tool_freq_warned: dict[str, set[str]] = defaultdict(set)
    def _get_thread_id(self, runtime: Runtime) -> str:
        """Extract thread_id from runtime context for per-thread tracking."""
-        return get_thread_id(runtime) or "default"
+        thread_id = runtime.context.get("thread_id") if runtime.context else None
        if thread_id:
            return thread_id
        return "default"
    def _evict_if_needed(self) -> None:
        """Evict least recently used threads if over the limit.
@@ -195,19 +112,11 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
        while len(self._history) > self.max_tracked_threads:
            evicted_id, _ = self._history.popitem(last=False)
            self._warned.pop(evicted_id, None)
            self._tool_freq.pop(evicted_id, None)
            self._tool_freq_warned.pop(evicted_id, None)
            logger.debug("Evicted loop tracking for thread %s (LRU)", evicted_id)
    def _track_and_check(self, state: AgentState, runtime: Runtime) -> tuple[str | None, bool]:
        """Track tool calls and check for loops.
        Two detection layers:
          1. **Hash-based** (existing): catches identical tool call sets.
          2. **Frequency-based** (new): catches the same *tool type* being
             called many times with varying arguments (e.g. ``read_file``
             on 40 different files).
        Returns:
            (warning_message_or_none, should_hard_stop)
        """
@@ -242,7 +151,6 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
            count = history.count(call_hash)
            tool_names = [tc.get("name", "?") for tc in tool_calls]
            # --- Layer 1: hash-based (identical call sets) ---
            if count >= self.hard_limit:
                logger.error(
                    "Loop hard limit reached — forcing stop",
@@ -269,80 +177,11 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
                        },
                    )
                    return _WARNING_MSG, False
-
+                # Warning already injected for this hash — suppress
-            # --- Layer 2: per-tool-type frequency ---
+                return None, False
            freq = self._tool_freq[thread_id]
            for tc in tool_calls:
                name = tc.get("name", "")
                if not name:
                    continue
                freq[name] += 1
                tc_count = freq[name]
                if tc_count >= self.tool_freq_hard_limit:
                    logger.error(
                        "Tool frequency hard limit reached — forcing stop",
                        extra={
                            "thread_id": thread_id,
                            "tool_name": name,
                            "count": tc_count,
                        },
                    )
                    return _TOOL_FREQ_HARD_STOP_MSG.format(tool_name=name, count=tc_count), True
                if tc_count >= self.tool_freq_warn:
                    warned = self._tool_freq_warned[thread_id]
                    if name not in warned:
                        warned.add(name)
                        logger.warning(
                            "Tool frequency warning — too many calls to same tool type",
                            extra={
                                "thread_id": thread_id,
                                "tool_name": name,
                                "count": tc_count,
                            },
                        )
                        return _TOOL_FREQ_WARNING_MSG.format(tool_name=name, count=tc_count), False
        return None, False
    @staticmethod
    def _append_text(content: str | list | None, text: str) -> str | list:
        """Append *text* to AIMessage content, handling str, list, and None.
        When content is a list of content blocks (e.g. Anthropic thinking mode),
        we append a new ``{"type": "text", ...}`` block instead of concatenating
        a string to a list, which would raise ``TypeError``.
        """
        if content is None:
            return text
        if isinstance(content, list):
            return [*content, {"type": "text", "text": f"\n\n{text}"}]
        if isinstance(content, str):
            return content + f"\n\n{text}"
        # Fallback: coerce unexpected types to str to avoid TypeError
        return str(content) + f"\n\n{text}"
    @staticmethod
    def _build_hard_stop_update(last_msg, content: str | list) -> dict:
        """Clear tool-call metadata so forced-stop messages serialize as plain assistant text."""
        update = {
            "tool_calls": [],
            "content": content,
        }
        additional_kwargs = dict(getattr(last_msg, "additional_kwargs", {}) or {})
        for key in ("tool_calls", "function_call"):
            additional_kwargs.pop(key, None)
        update["additional_kwargs"] = additional_kwargs
        response_metadata = deepcopy(getattr(last_msg, "response_metadata", {}) or {})
        if response_metadata.get("finish_reason") == "tool_calls":
            response_metadata["finish_reason"] = "stop"
        update["response_metadata"] = response_metadata
        return update
    def _apply(self, state: AgentState, runtime: Runtime) -> dict | None:
        warning, hard_stop = self._track_and_check(state, runtime)
@@ -350,8 +189,12 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
            # Strip tool_calls from the last AIMessage to force text output
            messages = state.get("messages", [])
            last_msg = messages[-1]
-            content = self._append_text(last_msg.content, warning or _HARD_STOP_MSG)
+            stripped_msg = last_msg.model_copy(
-            stripped_msg = last_msg.model_copy(update=self._build_hard_stop_update(last_msg, content))
+                update={
                    "tool_calls": [],
                    "content": (last_msg.content or "") + f"\n\n{_HARD_STOP_MSG}",
                }
            )
            return {"messages": [stripped_msg]}
        if warning:
@@ -379,10 +222,6 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
            if thread_id:
                self._history.pop(thread_id, None)
                self._warned.pop(thread_id, None)
                self._tool_freq.pop(thread_id, None)
                self._tool_freq_warned.pop(thread_id, None)
            else:
                self._history.clear()
                self._warned.clear()
                self._tool_freq.clear()
                self._tool_freq_warned.clear()
@@ -1,16 +1,16 @@
 """Middleware for memory mechanism."""
 import logging
-from typing import override
+import re
 from typing import Any, 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
 from deerflow.utils.runtime import get_thread_id
 logger = logging.getLogger(__name__)
@@ -21,6 +21,72 @@ class MemoryMiddlewareState(AgentState):
    pass
 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.
    """
    _UPLOAD_BLOCK_RE = re.compile(r"<uploaded_files>[\s\S]*?</uploaded_files>\n*", re.IGNORECASE)
    filtered = []
    skip_next_ai = False
    for msg in messages:
        msg_type = getattr(msg, "type", None)
        if msg_type == "human":
            content = getattr(msg, "content", "")
            if isinstance(content, list):
                content = " ".join(p.get("text", "") for p in content if isinstance(p, dict))
            content_str = str(content)
            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
 class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
    """Middleware that queues conversation for memory update after agent execution.
@@ -57,10 +123,13 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
        if not config.enabled:
            return None
-        # Resolve thread ID from the runtime or configured fallback sources
+        # Get thread ID from runtime context first, then fall back to LangGraph's configurable metadata
-        thread_id = get_thread_id(runtime)
+        thread_id = runtime.context.get("thread_id") if runtime.context else None
        if thread_id is None:
            config_data = get_config()
            thread_id = config_data.get("configurable", {}).get("thread_id")
        if not thread_id:
-            logger.debug("No thread_id could be resolved from runtime/config, skipping memory update")
+            logger.debug("No thread_id in context, skipping memory update")
            return None
        # Get messages from state
@@ -70,7 +139,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
@@ -81,15 +150,7 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
            return None
        # Queue the filtered conversation for memory update
        correction_detected = detect_correction(filtered_messages)
        reinforcement_detected = not correction_detected and detect_reinforcement(filtered_messages)
        queue = get_memory_queue()
-        queue.add(
+        queue.add(thread_id=thread_id, messages=filtered_messages, agent_name=self._agent_name)
            thread_id=thread_id,
            messages=filtered_messages,
            agent_name=self._agent_name,
            correction_detected=correction_detected,
            reinforcement_detected=reinforcement_detected,
        )
        return None
@@ -14,7 +14,6 @@ from langgraph.prebuilt.tool_node import ToolCallRequest
 from langgraph.types import Command
 from deerflow.agents.thread_state import ThreadState
 from deerflow.utils.runtime import get_thread_id
 logger = logging.getLogger(__name__)
@@ -24,119 +23,25 @@ logger = logging.getLogger(__name__)
 # Each pattern is compiled once at import time.
 _HIGH_RISK_PATTERNS: list[re.Pattern[str]] = [
-    # --- original rules (retained) ---
+    re.compile(r"rm\s+-[^\s]*r[^\s]*\s+(/\*?|~/?\*?|/home\b|/root\b)\s*$"),  # rm -rf / /* ~ /home /root
-    re.compile(r"rm\s+-[^\s]*r[^\s]*\s+(/\*?|~/?\*?|/home\b|/root\b)\s*$"),
+    re.compile(r"(curl|wget).+\|\s*(ba)?sh"),  # curl|sh, wget|sh
    re.compile(r"dd\s+if="),
    re.compile(r"mkfs"),
    re.compile(r"cat\s+/etc/shadow"),
-    re.compile(r">+\s*/etc/"),
+    re.compile(r">\s*/etc/"),  # overwrite /etc/ files
    # --- pipe to sh/bash (generalised, replaces old curl|sh rule) ---
    re.compile(r"\|\s*(ba)?sh\b"),
    # --- command substitution (targeted – only dangerous executables) ---
    re.compile(r"[`$]\(?\s*(curl|wget|bash|sh|python|ruby|perl|base64)"),
    # --- base64 decode piped to execution ---
    re.compile(r"base64\s+.*-d.*\|"),
    # --- overwrite system binaries ---
    re.compile(r">+\s*(/usr/bin/|/bin/|/sbin/)"),
    # --- overwrite shell startup files ---
    re.compile(r">+\s*~/?\.(bashrc|profile|zshrc|bash_profile)"),
    # --- process environment leakage ---
    re.compile(r"/proc/[^/]+/environ"),
    # --- dynamic linker hijack (one-step escalation) ---
    re.compile(r"\b(LD_PRELOAD|LD_LIBRARY_PATH)\s*="),
    # --- bash built-in networking (bypasses tool allowlists) ---
    re.compile(r"/dev/tcp/"),
    # --- fork bomb ---
    re.compile(r"\S+\(\)\s*\{[^}]*\|\s*\S+\s*&"),  # :(){ :|:& };:
    re.compile(r"while\s+true.*&\s*done"),  # while true; do bash & done
 ]
 _MEDIUM_RISK_PATTERNS: list[re.Pattern[str]] = [
-    re.compile(r"chmod\s+777"),
+    re.compile(r"chmod\s+777"),  # overly permissive, but reversible
-    re.compile(r"pip3?\s+install"),
+    re.compile(r"pip\s+install"),
    re.compile(r"pip3\s+install"),
    re.compile(r"apt(-get)?\s+install"),
    # sudo/su: no-op under Docker root; warn so LLM is aware
    re.compile(r"\b(sudo|su)\b"),
    # PATH modification: long attack chain, warn rather than block
    re.compile(r"\bPATH\s*="),
 ]
-def _split_compound_command(command: str) -> list[str]:
+def _classify_command(command: str) -> str:
-    """Split a compound command into sub-commands (quote-aware).
+    """Return 'block', 'warn', or 'pass'."""
-
+    # Normalize for matching (collapse whitespace)
    Scans the raw command string so unquoted shell control operators are
    recognised even when they are not surrounded by whitespace
    (e.g. ``safe;rm -rf /`` or ``rm -rf /&&echo ok``). Operators inside
    quotes are ignored. If the command ends with an unclosed quote or a
    dangling escape, return the whole command unchanged (fail-closed —
    safer to classify the unsplit string than silently drop parts).
    """
    parts: list[str] = []
    current: list[str] = []
    in_single_quote = False
    in_double_quote = False
    escaping = False
    index = 0
    while index < len(command):
        char = command[index]
        if escaping:
            current.append(char)
            escaping = False
            index += 1
            continue
        if char == "\\" and not in_single_quote:
            current.append(char)
            escaping = True
            index += 1
            continue
        if char == "'" and not in_double_quote:
            in_single_quote = not in_single_quote
            current.append(char)
            index += 1
            continue
        if char == '"' and not in_single_quote:
            in_double_quote = not in_double_quote
            current.append(char)
            index += 1
            continue
        if not in_single_quote and not in_double_quote:
            if command.startswith("&&", index) or command.startswith("||", index):
                part = "".join(current).strip()
                if part:
                    parts.append(part)
                current = []
                index += 2
                continue
            if char == ";":
                part = "".join(current).strip()
                if part:
                    parts.append(part)
                current = []
                index += 1
                continue
        current.append(char)
        index += 1
    # Unclosed quote or dangling escape → fail-closed, return whole command
    if in_single_quote or in_double_quote or escaping:
        return [command]
    part = "".join(current).strip()
    if part:
        parts.append(part)
    return parts if parts else [command]
 def _classify_single_command(command: str) -> str:
    """Classify a single (non-compound) command. Return 'block', 'warn', or 'pass'."""
    normalized = " ".join(command.split())
    for pattern in _HIGH_RISK_PATTERNS:
@@ -161,35 +66,6 @@ def _classify_single_command(command: str) -> str:
    return "pass"
 def _classify_command(command: str) -> str:
    """Return 'block', 'warn', or 'pass'.
    Strategy:
    1. First scan the *whole* raw command against high-risk patterns. This
       catches structural attacks like ``while true; do bash & done`` or
       ``:(){ :|:& };:`` that span multiple shell statements — splitting them
       on ``;`` would destroy the pattern context.
    2. Then split compound commands (e.g. ``cmd1 && cmd2 ; cmd3``) and
       classify each sub-command independently. The most severe verdict wins.
    """
    # Pass 1: whole-command high-risk scan (catches multi-statement patterns)
    normalized = " ".join(command.split())
    for pattern in _HIGH_RISK_PATTERNS:
        if pattern.search(normalized):
            return "block"
    # Pass 2: per-sub-command classification
    sub_commands = _split_compound_command(command)
    worst = "pass"
    for sub in sub_commands:
        verdict = _classify_single_command(sub)
        if verdict == "block":
            return "block"  # short-circuit: can't get worse
        if verdict == "warn":
            worst = "warn"
    return worst
 # ---------------------------------------------------------------------------
 # Middleware
 # ---------------------------------------------------------------------------
@@ -219,18 +95,21 @@ class SandboxAuditMiddleware(AgentMiddleware[ThreadState]):
    # ------------------------------------------------------------------
    def _get_thread_id(self, request: ToolCallRequest) -> str | None:
-        return get_thread_id(request.runtime)
+        runtime = request.runtime  # ToolRuntime; may be None-like in tests
        if runtime is None:
            return None
        ctx = getattr(runtime, "context", None) or {}
        thread_id = ctx.get("thread_id") if isinstance(ctx, dict) else None
        if thread_id is None:
            cfg = getattr(runtime, "config", None) or {}
            thread_id = cfg.get("configurable", {}).get("thread_id")
        return thread_id
-    _AUDIT_COMMAND_LIMIT = 200
+    def _write_audit(self, thread_id: str | None, command: str, verdict: str) -> None:
    def _write_audit(self, thread_id: str | None, command: str, verdict: str, *, truncate: bool = False) -> None:
        audited_command = command
        if truncate and len(command) > self._AUDIT_COMMAND_LIMIT:
            audited_command = f"{command[: self._AUDIT_COMMAND_LIMIT]}... ({len(command)} chars)"
        record = {
            "timestamp": datetime.now(UTC).isoformat(),
            "thread_id": thread_id or "unknown",
-            "command": audited_command,
+            "command": command,
            "verdict": verdict,
        }
        logger.info("[SandboxAudit] %s", json.dumps(record, ensure_ascii=False))
@@ -260,52 +139,23 @@ class SandboxAuditMiddleware(AgentMiddleware[ThreadState]):
            status=result.status,
        )
    # ------------------------------------------------------------------
    # Input sanitisation
    # ------------------------------------------------------------------
    # Normal bash commands rarely exceed a few hundred characters.  10 000 is
    # well above any legitimate use case yet a tiny fraction of Linux ARG_MAX.
    # Anything longer is almost certainly a payload injection or base64-encoded
    # attack string.
    _MAX_COMMAND_LENGTH = 10_000
    def _validate_input(self, command: str) -> str | None:
        """Return ``None`` if *command* is acceptable, else a rejection reason."""
        if not command.strip():
            return "empty command"
        if len(command) > self._MAX_COMMAND_LENGTH:
            return "command too long"
        if "\x00" in command:
            return "null byte detected"
        return None
    # ------------------------------------------------------------------
    # Core logic (shared between sync and async paths)
    # ------------------------------------------------------------------
-    def _pre_process(self, request: ToolCallRequest) -> tuple[str, str | None, str, str | None]:
+    def _pre_process(self, request: ToolCallRequest) -> tuple[str, str | None, str]:
        """
-        Returns (command, thread_id, verdict, reject_reason).
+        Returns (command, thread_id, verdict).
        verdict is 'block', 'warn', or 'pass'.
        reject_reason is non-None only for input sanitisation rejections.
        """
        args = request.tool_call.get("args", {})
-        raw_command = args.get("command")
+        command: str = args.get("command", "")
        command = raw_command if isinstance(raw_command, str) else ""
        thread_id = self._get_thread_id(request)
-        # ① input sanitisation — reject malformed input before regex analysis
+        # ① classify command
        reject_reason = self._validate_input(command)
        if reject_reason:
            self._write_audit(thread_id, command, "block", truncate=True)
            logger.warning("[SandboxAudit] INVALID INPUT thread=%s reason=%s", thread_id, reject_reason)
            return command, thread_id, "block", reject_reason
        # ② classify command
        verdict = _classify_command(command)
-        # ③ audit log
+        # ② audit log
        self._write_audit(thread_id, command, verdict)
        if verdict == "block":
@@ -313,7 +163,7 @@ class SandboxAuditMiddleware(AgentMiddleware[ThreadState]):
        elif verdict == "warn":
            logger.warning("[SandboxAudit] WARN (medium-risk) thread=%s cmd=%r", thread_id, command)
-        return command, thread_id, verdict, None
+        return command, thread_id, verdict
    # ------------------------------------------------------------------
    # wrap_tool_call hooks
@@ -328,10 +178,9 @@ class SandboxAuditMiddleware(AgentMiddleware[ThreadState]):
        if request.tool_call.get("name") != "bash":
            return handler(request)
-        command, _, verdict, reject_reason = self._pre_process(request)
+        command, _, verdict = self._pre_process(request)
        if verdict == "block":
-            reason = reject_reason or "security violation detected"
+            return self._build_block_message(request, "security violation detected")
            return self._build_block_message(request, reason)
        result = handler(request)
        if verdict == "warn":
            result = self._append_warn_to_result(result, command)
@@ -346,10 +195,9 @@ class SandboxAuditMiddleware(AgentMiddleware[ThreadState]):
        if request.tool_call.get("name") != "bash":
            return await handler(request)
-        command, _, verdict, reject_reason = self._pre_process(request)
+        command, _, verdict = self._pre_process(request)
        if verdict == "block":
-            reason = reject_reason or "security violation detected"
+            return self._build_block_message(request, "security violation detected")
            return self._build_block_message(request, reason)
        result = await handler(request)
        if verdict == "warn":
            result = self._append_warn_to_result(result, command)
@@ -1,337 +0,0 @@
 """Summarization middleware extensions for DeerFlow."""
 from __future__ import annotations
 import logging
 from collections.abc import Collection
 from dataclasses import dataclass
 from typing import Any, Protocol, runtime_checkable
 from langchain.agents import AgentState
 from langchain.agents.middleware import SummarizationMiddleware
 from langchain_core.messages import AIMessage, AnyMessage, RemoveMessage, ToolMessage
 from langgraph.config import get_config
 from langgraph.graph.message import REMOVE_ALL_MESSAGES
 from langgraph.runtime import Runtime
 from deerflow.utils.runtime import get_thread_id
 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_agent_name(runtime: Runtime) -> str | None:
    """Resolve the current agent name from runtime context or LangGraph config."""
    agent_name = runtime.context.get("agent_name") if runtime.context else None
    if agent_name is None:
        try:
            config_data = get_config()
        except RuntimeError:
            return None
        agent_name = config_data.get("configurable", {}).get("agent_name")
    return agent_name
 def _tool_call_path(tool_call: dict[str, Any]) -> str | None:
    """Best-effort extraction of a file path argument from a read_file-like tool call."""
    args = tool_call.get("args") or {}
    if not isinstance(args, dict):
        return None
    for key in ("path", "file_path", "filepath"):
        value = args.get(key)
        if isinstance(value, str) and value:
            return value
    return None
 def _clone_ai_message(
    message: AIMessage,
    tool_calls: list[dict[str, Any]],
    *,
    content: Any | None = None,
 ) -> AIMessage:
    """Clone an AIMessage while replacing its tool_calls list and optional content."""
    update: dict[str, Any] = {"tool_calls": tool_calls}
    if content is not None:
        update["content"] = content
    return message.model_copy(update=update)
@dataclass
 class _SkillBundle:
    """Skill-related tool calls and tool results associated with one AIMessage."""
    ai_index: int
    skill_tool_indices: tuple[int, ...]
    skill_tool_call_ids: frozenset[str]
    skill_tool_tokens: int
    skill_key: str
 class DeerFlowSummarizationMiddleware(SummarizationMiddleware):
    """Summarization middleware with pre-compression hook dispatch and skill rescue."""
    def __init__(
        self,
        *args,
        skills_container_path: str | None = None,
        skill_file_read_tool_names: Collection[str] | None = None,
        before_summarization: list[BeforeSummarizationHook] | None = None,
        preserve_recent_skill_count: int = 5,
        preserve_recent_skill_tokens: int = 25_000,
        preserve_recent_skill_tokens_per_skill: int = 5_000,
        **kwargs,
    ) -> None:
        super().__init__(*args, **kwargs)
        self._skills_container_path = skills_container_path or "/mnt/skills"
        self._skill_file_read_tool_names = frozenset(skill_file_read_tool_names or {"read_file", "read", "view", "cat"})
        self._before_summarization_hooks = before_summarization or []
        self._preserve_recent_skill_count = max(0, preserve_recent_skill_count)
        self._preserve_recent_skill_tokens = max(0, preserve_recent_skill_tokens)
        self._preserve_recent_skill_tokens_per_skill = max(0, preserve_recent_skill_tokens_per_skill)
    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_with_skill_rescue(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_with_skill_rescue(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 _partition_with_skill_rescue(
        self,
        messages: list[AnyMessage],
        cutoff_index: int,
    ) -> tuple[list[AnyMessage], list[AnyMessage]]:
        """Partition like the parent, then rescue recently-loaded skill bundles."""
        to_summarize, preserved = self._partition_messages(messages, cutoff_index)
        if self._preserve_recent_skill_count == 0 or self._preserve_recent_skill_tokens == 0 or not to_summarize:
            return to_summarize, preserved
        try:
            bundles = self._find_skill_bundles(to_summarize, self._skills_container_path)
        except Exception:
            logger.exception("Skill-preserving summarization rescue failed; falling back to default partition")
            return to_summarize, preserved
        if not bundles:
            return to_summarize, preserved
        rescue_bundles = self._select_bundles_to_rescue(bundles)
        if not rescue_bundles:
            return to_summarize, preserved
        bundles_by_ai_index = {bundle.ai_index: bundle for bundle in rescue_bundles}
        rescue_tool_indices = {idx for bundle in rescue_bundles for idx in bundle.skill_tool_indices}
        rescued: list[AnyMessage] = []
        remaining: list[AnyMessage] = []
        for i, msg in enumerate(to_summarize):
            bundle = bundles_by_ai_index.get(i)
            if bundle is not None and isinstance(msg, AIMessage):
                rescued_tool_calls = [tc for tc in msg.tool_calls if tc.get("id") in bundle.skill_tool_call_ids]
                remaining_tool_calls = [tc for tc in msg.tool_calls if tc.get("id") not in bundle.skill_tool_call_ids]
                if rescued_tool_calls:
                    rescued.append(_clone_ai_message(msg, rescued_tool_calls, content=""))
                if remaining_tool_calls or msg.content:
                    remaining.append(_clone_ai_message(msg, remaining_tool_calls))
                continue
            if i in rescue_tool_indices:
                rescued.append(msg)
                continue
            remaining.append(msg)
        return remaining, rescued + preserved
    def _find_skill_bundles(
        self,
        messages: list[AnyMessage],
        skills_root: str,
    ) -> list[_SkillBundle]:
        """Locate AIMessage + paired ToolMessage groups that load skill files."""
        bundles: list[_SkillBundle] = []
        n = len(messages)
        i = 0
        while i < n:
            msg = messages[i]
            if not (isinstance(msg, AIMessage) and msg.tool_calls):
                i += 1
                continue
            tool_calls = list(msg.tool_calls)
            skill_paths_by_id: dict[str, str] = {}
            for tc in tool_calls:
                if self._is_skill_tool_call(tc, skills_root):
                    tc_id = tc.get("id")
                    path = _tool_call_path(tc)
                    if tc_id and path:
                        skill_paths_by_id[tc_id] = path
            if not skill_paths_by_id:
                i += 1
                continue
            skill_tool_tokens = 0
            skill_key_parts: list[str] = []
            skill_tool_indices: list[int] = []
            matched_skill_call_ids: set[str] = set()
            j = i + 1
            while j < n and isinstance(messages[j], ToolMessage):
                j += 1
            for k in range(i + 1, j):
                tool_msg = messages[k]
                if isinstance(tool_msg, ToolMessage) and tool_msg.tool_call_id in skill_paths_by_id:
                    skill_tool_tokens += self.token_counter([tool_msg])
                    skill_key_parts.append(skill_paths_by_id[tool_msg.tool_call_id])
                    skill_tool_indices.append(k)
                    matched_skill_call_ids.add(tool_msg.tool_call_id)
            if not skill_tool_indices:
                i = j
                continue
            bundles.append(
                _SkillBundle(
                    ai_index=i,
                    skill_tool_indices=tuple(skill_tool_indices),
                    skill_tool_call_ids=frozenset(matched_skill_call_ids),
                    skill_tool_tokens=skill_tool_tokens,
                    skill_key="|".join(sorted(skill_key_parts)),
                )
            )
            i = j
        return bundles
    def _select_bundles_to_rescue(self, bundles: list[_SkillBundle]) -> list[_SkillBundle]:
        """Pick bundles to keep, walking newest-first under count/token budgets."""
        selected: list[_SkillBundle] = []
        if not bundles:
            return selected
        seen_skill_keys: set[str] = set()
        total_tokens = 0
        kept = 0
        for bundle in reversed(bundles):
            if kept >= self._preserve_recent_skill_count:
                break
            if bundle.skill_key in seen_skill_keys:
                continue
            if bundle.skill_tool_tokens > self._preserve_recent_skill_tokens_per_skill:
                continue
            if total_tokens + bundle.skill_tool_tokens > self._preserve_recent_skill_tokens:
                continue
            selected.append(bundle)
            total_tokens += bundle.skill_tool_tokens
            kept += 1
            seen_skill_keys.add(bundle.skill_key)
        selected.reverse()
        return selected
    def _is_skill_tool_call(self, tool_call: dict[str, Any], skills_root: str) -> bool:
        """Return True when ``tool_call`` reads a file under the configured skills root."""
        name = tool_call.get("name") or ""
        if name not in self._skill_file_read_tool_names:
            return False
        path = _tool_call_path(tool_call)
        if not path:
            return False
        normalized_root = skills_root.rstrip("/")
        return path == normalized_root or path.startswith(normalized_root + "/")
    def _fire_hooks(
        self,
        messages_to_summarize: list[AnyMessage],
        preserved_messages: list[AnyMessage],
        runtime: Runtime,
    ) -> None:
        if not self._before_summarization_hooks:
            return
        event = SummarizationEvent(
            messages_to_summarize=tuple(messages_to_summarize),
            preserved_messages=tuple(preserved_messages),
            thread_id=get_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)
@@ -3,11 +3,11 @@ from typing import NotRequired, 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.thread_state import ThreadDataState
 from deerflow.config.paths import Paths, get_paths
 from deerflow.utils.runtime import get_thread_id
 logger = logging.getLogger(__name__)
@@ -75,7 +75,11 @@ class ThreadDataMiddleware(AgentMiddleware[ThreadDataMiddlewareState]):
    @override
    def before_agent(self, state: ThreadDataMiddlewareState, runtime: Runtime) -> dict | None:
-        thread_id = get_thread_id(runtime)
+        context = runtime.context or {}
        thread_id = context.get("thread_id")
        if thread_id is None:
            config = get_config()
            thread_id = config.get("configurable", {}).get("thread_id")
        if thread_id is None:
            raise ValueError("Thread ID is required in runtime context or config.configurable")
@@ -1,7 +1,6 @@
 """Middleware for automatic thread title generation."""
 import logging
 import re
 from typing import NotRequired, override
 from langchain.agents import AgentState
@@ -78,7 +77,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._strip_think_tags(self._normalize_content(assistant_msg_content))
+        assistant_msg = self._normalize_content(assistant_msg_content)
        prompt = config.prompt_template.format(
            max_words=config.max_words,
@@ -87,15 +86,10 @@ 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
@@ -107,33 +101,44 @@ class TitleMiddleware(AgentMiddleware[TitleMiddlewareState]):
        return user_msg if user_msg else "New Conversation"
    def _generate_title_result(self, state: TitleMiddlewareState) -> dict | None:
-        """Generate a local fallback title without blocking on an LLM call."""
+        """Synchronously generate a title. Returns state update or None."""
        if not self._should_generate_title(state):
            return None
        _, user_msg = self._build_title_prompt(state)
        return {"title": self._fallback_title(user_msg)}
    async def _agenerate_title_result(self, state: TitleMiddlewareState) -> dict | None:
        """Generate a title asynchronously and fall back locally on failure."""
        if not self._should_generate_title(state):
            return None
        config = get_title_config()
        prompt, user_msg = self._build_title_prompt(state)
        config = get_title_config()
        model = create_chat_model(name=config.model_name, thinking_enabled=False)
        try:
-            if config.model_name:
+            response = model.invoke(prompt)
                model = create_chat_model(name=config.model_name, thinking_enabled=False)
            else:
                model = create_chat_model(thinking_enabled=False)
            response = await model.ainvoke(prompt, config={"run_name": "title_agent"})
            title = self._parse_title(response.content)
-            if title:
+            if not title:
-                return {"title": title}
+                title = self._fallback_title(user_msg)
        except Exception:
-            logger.debug("Failed to generate async title; falling back to local title", exc_info=True)
+            logger.exception("Failed to generate title (sync)")
-        return {"title": self._fallback_title(user_msg)}
+            title = self._fallback_title(user_msg)
        return {"title": title}
    async def _agenerate_title_result(self, state: TitleMiddlewareState) -> dict | None:
        """Asynchronously generate a title. Returns state update or None."""
        if not self._should_generate_title(state):
            return None
        prompt, user_msg = self._build_title_prompt(state)
        config = get_title_config()
        model = create_chat_model(name=config.model_name, thinking_enabled=False)
        try:
            response = await model.ainvoke(prompt)
            title = self._parse_title(response.content)
            if not title:
                title = self._fallback_title(user_msg)
        except Exception:
            logger.exception("Failed to generate title (async)")
            title = self._fallback_title(user_msg)
        return {"title": title}
    @override
    def after_model(self, state: TitleMiddlewareState, runtime: Runtime) -> dict | None:
@@ -1,14 +1,9 @@
-"""Middleware that extends TodoListMiddleware with context-loss detection and premature-exit prevention.
+"""Middleware that extends TodoListMiddleware with context-loss detection.
 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
@@ -17,7 +12,6 @@ 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
@@ -40,11 +34,6 @@ 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] = []
@@ -68,7 +57,7 @@ class TodoMiddleware(TodoListMiddleware):
    def before_model(
        self,
        state: PlanningState,
-        runtime: Runtime,
+        runtime: Runtime,  # noqa: ARG002
    ) -> 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]
@@ -109,71 +98,3 @@ 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)
@@ -72,7 +72,6 @@ def _build_runtime_middlewares(
    lazy_init: bool = True,
 ) -> list[AgentMiddleware]:
    """Build shared base middlewares for agent execution."""
    from deerflow.agents.middlewares.llm_error_handling_middleware import LLMErrorHandlingMiddleware
    from deerflow.agents.middlewares.thread_data_middleware import ThreadDataMiddleware
    from deerflow.sandbox.middleware import SandboxMiddleware
@@ -91,8 +90,6 @@ def _build_runtime_middlewares(
        middlewares.append(DanglingToolCallMiddleware())
    middlewares.append(LLMErrorHandlingMiddleware())
    # Guardrail middleware (if configured)
    from deerflow.config.guardrails_config import get_guardrails_config
@@ -138,6 +135,6 @@ def build_subagent_runtime_middlewares(*, lazy_init: bool = True) -> list[AgentM
    """Middlewares shared by subagent runtime before subagent-only middlewares."""
    return _build_runtime_middlewares(
        include_uploads=False,
-        include_dangling_tool_call_patch=True,
+        include_dangling_tool_call_patch=False,
        lazy_init=lazy_init,
    )
@@ -10,53 +10,10 @@ from langchain_core.messages import HumanMessage
 from langgraph.runtime import Runtime
 from deerflow.config.paths import Paths, get_paths
 from deerflow.utils.file_conversion import extract_outline
 from deerflow.utils.runtime import get_thread_id
 logger = logging.getLogger(__name__)
 _OUTLINE_PREVIEW_LINES = 5
 def _extract_outline_for_file(file_path: Path) -> tuple[list[dict], list[str]]:
    """Return the document outline and fallback preview for *file_path*.
    Looks for a sibling ``<stem>.md`` file produced by the upload conversion
    pipeline.
    Returns:
        (outline, preview) where:
        - outline: list of ``{title, line}`` dicts (plus optional sentinel).
          Empty when no headings are found or no .md exists.
        - preview: first few non-empty lines of the .md, used as a content
          anchor when outline is empty so the agent has some context.
          Empty when outline is non-empty (no fallback needed).
    """
    md_path = file_path.with_suffix(".md")
    if not md_path.is_file():
        return [], []
    outline = extract_outline(md_path)
    if outline:
        logger.debug("Extracted %d outline entries from %s", len(outline), file_path.name)
        return outline, []
    # outline is empty — read the first few non-empty lines as a content preview
    preview: list[str] = []
    try:
        with md_path.open(encoding="utf-8") as f:
            for line in f:
                stripped = line.strip()
                if stripped:
                    preview.append(stripped)
                if len(preview) >= _OUTLINE_PREVIEW_LINES:
                    break
    except Exception:
        logger.debug("Failed to read preview lines from %s", md_path, exc_info=True)
    return [], preview
 class UploadsMiddlewareState(AgentState):
    """State schema for uploads middleware."""
@@ -82,38 +39,12 @@ class UploadsMiddleware(AgentMiddleware[UploadsMiddlewareState]):
        super().__init__()
        self._paths = Paths(base_dir) if base_dir else get_paths()
    def _format_file_entry(self, file: dict, lines: list[str]) -> None:
        """Append a single file entry (name, size, path, optional outline) to lines."""
        size_kb = file["size"] / 1024
        size_str = f"{size_kb:.1f} KB" if size_kb < 1024 else f"{size_kb / 1024:.1f} MB"
        lines.append(f"- {file['filename']} ({size_str})")
        lines.append(f"  Path: {file['path']}")
        outline = file.get("outline") or []
        if outline:
            truncated = outline[-1].get("truncated", False)
            visible = [e for e in outline if not e.get("truncated")]
            lines.append("  Document outline (use `read_file` with line ranges to read sections):")
            for entry in visible:
                lines.append(f"    L{entry['line']}: {entry['title']}")
            if truncated:
                lines.append(f"    ... (showing first {len(visible)} headings; use `read_file` to explore further)")
        else:
            preview = file.get("outline_preview") or []
            if preview:
                lines.append("  No structural headings detected. Document begins with:")
                for text in preview:
                    lines.append(f"    > {text}")
            lines.append("  Use `grep` to search for keywords (e.g. `grep(pattern='keyword', path='/mnt/user-data/uploads/')`).")
        lines.append("")
    def _create_files_message(self, new_files: list[dict], historical_files: list[dict]) -> str:
        """Create a formatted message listing uploaded files.
        Args:
            new_files: Files uploaded in the current message.
            historical_files: Files uploaded in previous messages.
                Each file dict may contain an optional ``outline`` key — a list of
                ``{title, line}`` dicts extracted from the converted Markdown file.
        Returns:
            Formatted string inside <uploaded_files> tags.
@@ -124,24 +55,25 @@ class UploadsMiddleware(AgentMiddleware[UploadsMiddlewareState]):
        lines.append("")
        if new_files:
            for file in new_files:
-                self._format_file_entry(file, lines)
+                size_kb = file["size"] / 1024
                size_str = f"{size_kb:.1f} KB" if size_kb < 1024 else f"{size_kb / 1024:.1f} MB"
                lines.append(f"- {file['filename']} ({size_str})")
                lines.append(f"  Path: {file['path']}")
                lines.append("")
        else:
            lines.append("(empty)")
            lines.append("")
        if historical_files:
            lines.append("The following files were uploaded in previous messages and are still available:")
            lines.append("")
            for file in historical_files:
-                self._format_file_entry(file, lines)
+                size_kb = file["size"] / 1024
                size_str = f"{size_kb:.1f} KB" if size_kb < 1024 else f"{size_kb / 1024:.1f} MB"
                lines.append(f"- {file['filename']} ({size_str})")
                lines.append(f"  Path: {file['path']}")
                lines.append("")
-        lines.append("To work with these files:")
+        lines.append("You can read these files using the `read_file` tool with the paths shown above.")
        lines.append("- Read from the file first — use the outline line numbers and `read_file` to locate relevant sections.")
        lines.append("- Use `grep` to search for keywords when you are not sure which section to look at")
        lines.append("  (e.g. `grep(pattern='revenue', path='/mnt/user-data/uploads/')`).")
        lines.append("- Use `glob` to find files by name pattern")
        lines.append("  (e.g. `glob(pattern='**/*.md', path='/mnt/user-data/uploads/')`).")
        lines.append("- Only fall back to web search if the file content is clearly insufficient to answer the question.")
        lines.append("</uploaded_files>")
        return "\n".join(lines)
@@ -214,7 +146,7 @@ class UploadsMiddleware(AgentMiddleware[UploadsMiddlewareState]):
            return None
        # Resolve uploads directory for existence checks
-        thread_id = get_thread_id(runtime)
+        thread_id = (runtime.context or {}).get("thread_id")
        uploads_dir = self._paths.sandbox_uploads_dir(thread_id) if thread_id else None
        # Get newly uploaded files from the current message's additional_kwargs.files
@@ -227,26 +159,15 @@ class UploadsMiddleware(AgentMiddleware[UploadsMiddlewareState]):
            for file_path in sorted(uploads_dir.iterdir()):
                if file_path.is_file() and file_path.name not in new_filenames:
                    stat = file_path.stat()
                    outline, preview = _extract_outline_for_file(file_path)
                    historical_files.append(
                        {
                            "filename": file_path.name,
                            "size": stat.st_size,
                            "path": f"/mnt/user-data/uploads/{file_path.name}",
                            "extension": file_path.suffix,
                            "outline": outline,
                            "outline_preview": preview,
                        }
                    )
        # Attach outlines to new files as well
        if uploads_dir:
            for file in new_files:
                phys_path = uploads_dir / file["filename"]
                outline, preview = _extract_outline_for_file(phys_path)
                file["outline"] = outline
                file["outline_preview"] = preview
        if not new_files and not historical_files:
            return None
@@ -256,25 +177,21 @@ class UploadsMiddleware(AgentMiddleware[UploadsMiddlewareState]):
        files_message = self._create_files_message(new_files, historical_files)
        # Extract original content - handle both string and list formats
-        original_content = last_message.content
+        original_content = ""
-        if isinstance(original_content, str):
+        if isinstance(last_message.content, str):
-            # Simple case: string content, just prepend files message
+            original_content = last_message.content
-            updated_content = f"{files_message}\n\n{original_content}"
+        elif isinstance(last_message.content, list):
-        elif isinstance(original_content, list):
+            text_parts = []
-            # Complex case: list content (multimodal), preserve all blocks
+            for block in last_message.content:
-            # Prepend files message as the first text block
+                if isinstance(block, dict) and block.get("type") == "text":
-            files_block = {"type": "text", "text": f"{files_message}\n\n"}
+                    text_parts.append(block.get("text", ""))
-            # Keep all original blocks (including images)
+            original_content = "\n".join(text_parts)
            updated_content = [files_block, *original_content]
        else:
            # Other types, preserve as-is
            updated_content = original_content
        # Create new message with combined content.
        # Preserve additional_kwargs (including files metadata) so the frontend
        # can read structured file info from the streamed message.
        updated_message = HumanMessage(
-            content=updated_content,
+            content=f"{files_message}\n\n{original_content}",
            id=last_message.id,
            additional_kwargs=last_message.additional_kwargs,
        )
@@ -1,19 +1,22 @@
 """Middleware for injecting image details into conversation before LLM call."""
 import logging
-from typing import override
+from typing import NotRequired, override
 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
 from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
 from langgraph.runtime import Runtime
-from deerflow.agents.thread_state import ThreadState
+from deerflow.agents.thread_state import ViewedImageData
 logger = logging.getLogger(__name__)
-class ViewImageMiddlewareState(ThreadState):
+class ViewImageMiddlewareState(AgentState):
-    """Reuse the thread state so reducer-backed keys keep their annotations."""
+    """Compatible with the `ThreadState` schema."""
    viewed_images: NotRequired[dict[str, ViewedImageData] | None]
 class ViewImageMiddleware(AgentMiddleware[ViewImageMiddlewareState]):
@@ -25,7 +25,7 @@ import uuid
 from collections.abc import Generator, Sequence
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Literal
+from typing import Any
 from langchain.agents import create_agent
 from langchain.agents.middleware import AgentMiddleware
@@ -55,9 +55,6 @@ from deerflow.uploads.manager import (
 logger = logging.getLogger(__name__)
 StreamEventType = Literal["values", "messages-tuple", "custom", "end"]
@dataclass
 class StreamEvent:
    """A single event from the streaming agent response.
@@ -72,7 +69,7 @@ class StreamEvent:
        data: Event payload. Contents vary by type.
    """
-    type: StreamEventType
+    type: str
    data: dict[str, Any] = field(default_factory=dict)
@@ -120,7 +117,6 @@ class DeerFlowClient:
        subagent_enabled: bool = False,
        plan_mode: bool = False,
        agent_name: str | None = None,
        available_skills: set[str] | None = None,
        middlewares: Sequence[AgentMiddleware] | None = None,
    ):
        """Initialize the client.
@@ -137,7 +133,6 @@ class DeerFlowClient:
            subagent_enabled: Enable subagent delegation.
            plan_mode: Enable TodoList middleware for plan mode.
            agent_name: Name of the agent to use.
            available_skills: Optional set of skill names to make available. If None (default), all scanned skills are available.
            middlewares: Optional list of custom middlewares to inject into the agent.
        """
        if config_path is not None:
@@ -153,7 +148,6 @@ class DeerFlowClient:
        self._subagent_enabled = subagent_enabled
        self._plan_mode = plan_mode
        self._agent_name = agent_name
        self._available_skills = set(available_skills) if available_skills is not None else None
        self._middlewares = list(middlewares) if middlewares else []
        # Lazy agent — created on first call, recreated when config changes.
@@ -214,8 +208,6 @@ class DeerFlowClient:
            cfg.get("thinking_enabled"),
            cfg.get("is_plan_mode"),
            cfg.get("subagent_enabled"),
            self._agent_name,
            frozenset(self._available_skills) if self._available_skills is not None else None,
        )
        if self._agent is not None and self._agent_config_key == key:
@@ -234,7 +226,6 @@ class DeerFlowClient:
                subagent_enabled=subagent_enabled,
                max_concurrent_subagents=max_concurrent_subagents,
                agent_name=self._agent_name,
                available_skills=self._available_skills,
            ),
            "state_schema": ThreadState,
        }
@@ -257,53 +248,13 @@ class DeerFlowClient:
        return get_available_tools(model_name=model_name, subagent_enabled=subagent_enabled)
    @staticmethod
    def _serialize_tool_calls(tool_calls) -> list[dict]:
        """Reshape LangChain tool_calls into the wire format used in events."""
        return [{"name": tc["name"], "args": tc["args"], "id": tc.get("id")} for tc in tool_calls]
    @staticmethod
    def _ai_text_event(msg_id: str | None, text: str, usage: dict | None) -> "StreamEvent":
        """Build a ``messages-tuple`` AI text event, attaching usage when present."""
        data: dict[str, Any] = {"type": "ai", "content": text, "id": msg_id}
        if usage:
            data["usage_metadata"] = usage
        return StreamEvent(type="messages-tuple", data=data)
    @staticmethod
    def _ai_tool_calls_event(msg_id: str | None, tool_calls) -> "StreamEvent":
        """Build a ``messages-tuple`` AI tool-calls event."""
        return StreamEvent(
            type="messages-tuple",
            data={
                "type": "ai",
                "content": "",
                "id": msg_id,
                "tool_calls": DeerFlowClient._serialize_tool_calls(tool_calls),
            },
        )
    @staticmethod
    def _tool_message_event(msg: ToolMessage) -> "StreamEvent":
        """Build a ``messages-tuple`` tool-result event from a ToolMessage."""
        return StreamEvent(
            type="messages-tuple",
            data={
                "type": "tool",
                "content": DeerFlowClient._extract_text(msg.content),
                "name": msg.name,
                "tool_call_id": msg.tool_call_id,
                "id": msg.id,
            },
        )
    @staticmethod
    def _serialize_message(msg) -> dict:
        """Serialize a LangChain message to a plain dict for values events."""
        if isinstance(msg, AIMessage):
            d: dict[str, Any] = {"type": "ai", "content": msg.content, "id": getattr(msg, "id", None)}
            if msg.tool_calls:
-                d["tool_calls"] = DeerFlowClient._serialize_tool_calls(msg.tool_calls)
+                d["tool_calls"] = [{"name": tc["name"], "args": tc["args"], "id": tc.get("id")} for tc in msg.tool_calls]
            if getattr(msg, "usage_metadata", None):
                d["usage_metadata"] = msg.usage_metadata
            return d
@@ -358,108 +309,6 @@ class DeerFlowClient:
            return "\n".join(pieces) if pieces else ""
        return str(content)
    # ------------------------------------------------------------------
    # Public API — threads
    # ------------------------------------------------------------------
    def list_threads(self, limit: int = 10) -> dict:
        """List the recent N threads.
        Args:
            limit: Maximum number of threads to return. Default is 10.
        Returns:
            Dict with "thread_list" key containing list of thread info dicts,
            sorted by thread creation time descending.
        """
        checkpointer = self._checkpointer
        if checkpointer is None:
            from deerflow.agents.checkpointer.provider import get_checkpointer
            checkpointer = get_checkpointer()
        thread_info_map = {}
        for cp in checkpointer.list(config=None, limit=limit):
            cfg = cp.config.get("configurable", {})
            thread_id = cfg.get("thread_id")
            if not thread_id:
                continue
            ts = cp.checkpoint.get("ts")
            checkpoint_id = cfg.get("checkpoint_id")
            if thread_id not in thread_info_map:
                channel_values = cp.checkpoint.get("channel_values", {})
                thread_info_map[thread_id] = {
                    "thread_id": thread_id,
                    "created_at": ts,
                    "updated_at": ts,
                    "latest_checkpoint_id": checkpoint_id,
                    "title": channel_values.get("title"),
                }
            else:
                # Explicitly compare timestamps to ensure accuracy when iterating over unordered namespaces.
                # Treat None as "missing" and only compare when existing values are non-None.
                if ts is not None:
                    current_created = thread_info_map[thread_id]["created_at"]
                    if current_created is None or ts < current_created:
                        thread_info_map[thread_id]["created_at"] = ts
                    current_updated = thread_info_map[thread_id]["updated_at"]
                    if current_updated is None or ts > current_updated:
                        thread_info_map[thread_id]["updated_at"] = ts
                        thread_info_map[thread_id]["latest_checkpoint_id"] = checkpoint_id
                        channel_values = cp.checkpoint.get("channel_values", {})
                        thread_info_map[thread_id]["title"] = channel_values.get("title")
        threads = list(thread_info_map.values())
        threads.sort(key=lambda x: x.get("created_at") or "", reverse=True)
        return {"thread_list": threads[:limit]}
    def get_thread(self, thread_id: str) -> dict:
        """Get the complete thread record, including all node execution records.
        Args:
            thread_id: Thread ID.
        Returns:
            Dict containing the thread's full checkpoint history.
        """
        checkpointer = self._checkpointer
        if checkpointer is None:
            from deerflow.agents.checkpointer.provider import get_checkpointer
            checkpointer = get_checkpointer()
        config = {"configurable": {"thread_id": thread_id}}
        checkpoints = []
        for cp in checkpointer.list(config):
            channel_values = dict(cp.checkpoint.get("channel_values", {}))
            if "messages" in channel_values:
                channel_values["messages"] = [self._serialize_message(m) if hasattr(m, "content") else m for m in channel_values["messages"]]
            cfg = cp.config.get("configurable", {})
            parent_cfg = cp.parent_config.get("configurable", {}) if cp.parent_config else {}
            checkpoints.append(
                {
                    "checkpoint_id": cfg.get("checkpoint_id"),
                    "parent_checkpoint_id": parent_cfg.get("checkpoint_id"),
                    "ts": cp.checkpoint.get("ts"),
                    "metadata": cp.metadata,
                    "values": channel_values,
                    "pending_writes": [{"task_id": w[0], "channel": w[1], "value": w[2]} for w in getattr(cp, "pending_writes", [])],
                }
            )
        # Sort globally by timestamp to prevent partial ordering issues caused by different namespaces (e.g., subgraphs)
        checkpoints.sort(key=lambda x: x["ts"] if x["ts"] else "")
        return {"thread_id": thread_id, "checkpoints": checkpoints}
    # ------------------------------------------------------------------
    # Public API — conversation
    # ------------------------------------------------------------------
@@ -481,53 +330,6 @@ class DeerFlowClient:
        consumers can switch between HTTP streaming and embedded mode
        without changing their event-handling logic.
        Token-level streaming
        ~~~~~~~~~~~~~~~~~~~~~
        This method subscribes to LangGraph's ``messages`` stream mode, so
        ``messages-tuple`` events for AI text are emitted as **deltas** as
        the model generates tokens, not as one cumulative dump at node
        completion.  Each delta carries a stable ``id`` — consumers that
        want the full text must accumulate ``content`` per ``id``.
        ``chat()`` already does this for you.
        Tool calls and tool results are still emitted once per logical
        message.  ``values`` events continue to carry full state snapshots
        after each graph node finishes; AI text already delivered via the
        ``messages`` stream is **not** re-synthesized from the snapshot to
        avoid duplicate deliveries.
        Why not reuse Gateway's ``run_agent``?
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        Gateway (``runtime/runs/worker.py``) has a complete streaming
        pipeline: ``run_agent`` → ``StreamBridge`` → ``sse_consumer``.  It
        looks like this client duplicates that work, but the two paths
        serve different audiences and **cannot** share execution:
        * ``run_agent`` is ``async def`` and uses ``agent.astream()``;
          this method is a sync generator using ``agent.stream()`` so
          callers can write ``for event in client.stream(...)`` without
          touching asyncio.  Bridging the two would require spinning up
          an event loop + thread per call.
        * Gateway events are JSON-serialized by ``serialize()`` for SSE
          wire transmission.  This client yields in-process stream event
          payloads directly as Python data structures (``StreamEvent``
          with ``data`` as a plain ``dict``), without the extra
          JSON/SSE serialization layer used for HTTP delivery.
        * ``StreamBridge`` is an asyncio-queue decoupling producers from
          consumers across an HTTP boundary (``Last-Event-ID`` replay,
          heartbeats, multi-subscriber fan-out).  A single in-process
          caller with a direct iterator needs none of that.
        So ``DeerFlowClient.stream()`` is a parallel, sync, in-process
        consumer of the same ``create_agent()`` factory — not a wrapper
        around Gateway.  The two paths **should** stay in sync on which
        LangGraph stream modes they subscribe to; that invariant is
        enforced by ``tests/test_client.py::test_messages_mode_emits_token_deltas``
        rather than by a shared constant, because the three layers
        (Graph, Platform SDK, HTTP) each use their own naming
        (``messages`` vs ``messages-tuple``) and cannot literally share
        a string.
        Args:
            message: User message text.
            thread_id: Thread ID for conversation context. Auto-generated if None.
@@ -537,9 +339,8 @@ class DeerFlowClient:
        Yields:
            StreamEvent with one of:
            - type="values"          data={"title": str|None, "messages": [...], "artifacts": [...]}
-            - type="custom"          data={...}
+            - type="messages-tuple"  data={"type": "ai", "content": str, "id": str}
-            - type="messages-tuple"  data={"type": "ai", "content": <delta>, "id": str}
+            - type="messages-tuple"  data={"type": "ai", "content": str, "id": str, "usage_metadata": {...}}
            - type="messages-tuple"  data={"type": "ai", "content": <delta>, "id": str, "usage_metadata": {...}}
            - type="messages-tuple"  data={"type": "ai", "content": "", "id": str, "tool_calls": [...]}
            - type="messages-tuple"  data={"type": "tool", "content": str, "name": str, "tool_call_id": str, "id": str}
            - type="end"             data={"usage": {"input_tokens": int, "output_tokens": int, "total_tokens": int}}
@@ -556,88 +357,9 @@ class DeerFlowClient:
            context["agent_name"] = self._agent_name
        seen_ids: set[str] = set()
        # Cross-mode handoff: ids already streamed via LangGraph ``messages``
        # mode so the ``values`` path skips re-synthesis of the same message.
        streamed_ids: set[str] = set()
        # The same message id carries identical cumulative ``usage_metadata``
        # in both the final ``messages`` chunk and the values snapshot —
        # count it only on whichever arrives first.
        counted_usage_ids: set[str] = set()
        cumulative_usage: dict[str, int] = {"input_tokens": 0, "output_tokens": 0, "total_tokens": 0}
-        def _account_usage(msg_id: str | None, usage: Any) -> dict | None:
+        for chunk in self._agent.stream(state, config=config, context=context, stream_mode="values"):
            """Add *usage* to cumulative totals if this id has not been counted.
            ``usage`` is a ``langchain_core.messages.UsageMetadata`` TypedDict
            or ``None``; typed as ``Any`` because TypedDicts are not
            structurally assignable to plain ``dict`` under strict type
            checking.  Returns the normalized usage dict (for attaching
            to an event) when we accepted it, otherwise ``None``.
            """
            if not usage:
                return None
            if msg_id and msg_id in counted_usage_ids:
                return None
            if msg_id:
                counted_usage_ids.add(msg_id)
            input_tokens = usage.get("input_tokens", 0) or 0
            output_tokens = usage.get("output_tokens", 0) or 0
            total_tokens = usage.get("total_tokens", 0) or 0
            cumulative_usage["input_tokens"] += input_tokens
            cumulative_usage["output_tokens"] += output_tokens
            cumulative_usage["total_tokens"] += total_tokens
            return {
                "input_tokens": input_tokens,
                "output_tokens": output_tokens,
                "total_tokens": total_tokens,
            }
        for item in self._agent.stream(
            state,
            config=config,
            context=context,
            stream_mode=["values", "messages", "custom"],
        ):
            if isinstance(item, tuple) and len(item) == 2:
                mode, chunk = item
                mode = str(mode)
            else:
                mode, chunk = "values", item
            if mode == "custom":
                yield StreamEvent(type="custom", data=chunk)
                continue
            if mode == "messages":
                # LangGraph ``messages`` mode emits ``(message_chunk, metadata)``.
                if isinstance(chunk, tuple) and len(chunk) == 2:
                    msg_chunk, _metadata = chunk
                else:
                    msg_chunk = chunk
                msg_id = getattr(msg_chunk, "id", None)
                if isinstance(msg_chunk, AIMessage):
                    text = self._extract_text(msg_chunk.content)
                    counted_usage = _account_usage(msg_id, msg_chunk.usage_metadata)
                    if text:
                        if msg_id:
                            streamed_ids.add(msg_id)
                        yield self._ai_text_event(msg_id, text, counted_usage)
                    if msg_chunk.tool_calls:
                        if msg_id:
                            streamed_ids.add(msg_id)
                        yield self._ai_tool_calls_event(msg_id, msg_chunk.tool_calls)
                elif isinstance(msg_chunk, ToolMessage):
                    if msg_id:
                        streamed_ids.add(msg_id)
                    yield self._tool_message_event(msg_chunk)
                continue
            # mode == "values"
            messages = chunk.get("messages", [])
            for msg in messages:
@@ -647,25 +369,47 @@ class DeerFlowClient:
                if msg_id:
                    seen_ids.add(msg_id)
                # Already streamed via ``messages`` mode; only (defensively)
                # capture usage here and skip re-synthesizing the event.
                if msg_id and msg_id in streamed_ids:
                    if isinstance(msg, AIMessage):
                        _account_usage(msg_id, getattr(msg, "usage_metadata", None))
                    continue
                if isinstance(msg, AIMessage):
-                    counted_usage = _account_usage(msg_id, msg.usage_metadata)
+                    # Track token usage from AI messages
                    usage = getattr(msg, "usage_metadata", None)
                    if usage:
                        cumulative_usage["input_tokens"] += usage.get("input_tokens", 0) or 0
                        cumulative_usage["output_tokens"] += usage.get("output_tokens", 0) or 0
                        cumulative_usage["total_tokens"] += usage.get("total_tokens", 0) or 0
                    if msg.tool_calls:
-                        yield self._ai_tool_calls_event(msg_id, msg.tool_calls)
+                        yield StreamEvent(
                            type="messages-tuple",
                            data={
                                "type": "ai",
                                "content": "",
                                "id": msg_id,
                                "tool_calls": [{"name": tc["name"], "args": tc["args"], "id": tc.get("id")} for tc in msg.tool_calls],
                            },
                        )
                    text = self._extract_text(msg.content)
                    if text:
-                        yield self._ai_text_event(msg_id, text, counted_usage)
+                        event_data: dict[str, Any] = {"type": "ai", "content": text, "id": msg_id}
                        if usage:
                            event_data["usage_metadata"] = {
                                "input_tokens": usage.get("input_tokens", 0) or 0,
                                "output_tokens": usage.get("output_tokens", 0) or 0,
                                "total_tokens": usage.get("total_tokens", 0) or 0,
                            }
                        yield StreamEvent(type="messages-tuple", data=event_data)
                elif isinstance(msg, ToolMessage):
-                    yield self._tool_message_event(msg)
+                    yield StreamEvent(
                        type="messages-tuple",
                        data={
                            "type": "tool",
                            "content": self._extract_text(msg.content),
                            "name": getattr(msg, "name", None),
                            "tool_call_id": getattr(msg, "tool_call_id", None),
                            "id": msg_id,
                        },
                    )
            # Emit a values event for each state snapshot
            yield StreamEvent(
@@ -682,12 +426,10 @@ class DeerFlowClient:
    def chat(self, message: str, *, thread_id: str | None = None, **kwargs) -> str:
        """Send a message and return the final text response.
-        Convenience wrapper around :meth:`stream` that accumulates delta
+        Convenience wrapper around :meth:`stream` that returns only the
-        ``messages-tuple`` events per ``id`` and returns the text of the
+        **last** AI text from ``messages-tuple`` events. If the agent emits
-        **last** AI message to complete.  Intermediate AI messages (e.g.
+        multiple text segments in one turn, intermediate segments are
-        planner drafts) are discarded — only the final id's accumulated
+        discarded. Use :meth:`stream` directly to capture all events.
        text is returned.  Use :meth:`stream` directly if you need every
        delta as it arrives.
        Args:
            message: User message text.
@@ -695,21 +437,15 @@ class DeerFlowClient:
            **kwargs: Override client defaults (same as stream()).
        Returns:
-            The accumulated text of the last AI message, or empty string
+            The last AI message text, or empty string if no response.
            if no AI text was produced.
        """
-        # Per-id delta lists joined once at the end — avoids the O(n²) cost
+        last_text = ""
        # of repeated ``str + str`` on a growing buffer for long responses.
        chunks: dict[str, list[str]] = {}
        last_id: str = ""
        for event in self.stream(message, thread_id=thread_id, **kwargs):
            if event.type == "messages-tuple" and event.data.get("type") == "ai":
-                msg_id = event.data.get("id") or ""
+                content = event.data.get("content", "")
-                delta = event.data.get("content", "")
+                if content:
-                if delta:
+                    last_text = content
-                    chunks.setdefault(msg_id, []).append(delta)
+        return last_text
                    last_id = msg_id
        return "".join(chunks.get(last_id, ()))
    # ------------------------------------------------------------------
    # Public API — configuration queries
@@ -722,10 +458,6 @@ 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": [
                {
@@ -737,8 +469,7 @@ 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:
@@ -1,25 +1,17 @@
 import base64
 import logging
 import shlex
 import threading
 import uuid
 from agent_sandbox import Sandbox as AioSandboxClient
 from deerflow.sandbox.sandbox import Sandbox
 from deerflow.sandbox.search import GrepMatch, path_matches, should_ignore_path, truncate_line
 logger = logging.getLogger(__name__)
 _ERROR_OBSERVATION_SIGNATURE = "'ErrorObservation' object has no attribute 'exit_code'"
 class AioSandbox(Sandbox):
    """Sandbox implementation using the agent-infra/sandbox Docker container.
    This sandbox connects to a running AIO sandbox container via HTTP API.
    A threading lock serializes shell commands to prevent concurrent requests
    from corrupting the container's single persistent session (see #1433).
    """
    def __init__(self, id: str, base_url: str, home_dir: str | None = None):
@@ -34,7 +26,6 @@ class AioSandbox(Sandbox):
        self._base_url = base_url
        self._client = AioSandboxClient(base_url=base_url, timeout=600)
        self._home_dir = home_dir
        self._lock = threading.Lock()
    @property
    def base_url(self) -> str:
@@ -51,34 +42,19 @@ class AioSandbox(Sandbox):
    def execute_command(self, command: str) -> str:
        """Execute a shell command in the sandbox.
        Uses a lock to serialize concurrent requests. The AIO sandbox
        container maintains a single persistent shell session that
        corrupts when hit with concurrent exec_command calls (returns
        ``ErrorObservation`` instead of real output). If corruption is
        detected despite the lock (e.g. multiple processes sharing a
        sandbox), the command is retried on a fresh session.
        Args:
            command: The command to execute.
        Returns:
            The output of the command.
        """
-        with self._lock:
+        try:
-            try:
+            result = self._client.shell.exec_command(command=command)
-                result = self._client.shell.exec_command(command=command)
+            output = result.data.output if result.data else ""
-                output = result.data.output if result.data else ""
+            return output if output else "(no output)"
-
+        except Exception as e:
-                if output and _ERROR_OBSERVATION_SIGNATURE in output:
+            logger.error(f"Failed to execute command in sandbox: {e}")
-                    logger.warning("ErrorObservation detected in sandbox output, retrying with a fresh session")
+            return f"Error: {e}"
                    fresh_id = str(uuid.uuid4())
                    result = self._client.shell.exec_command(command=command, id=fresh_id)
                    output = result.data.output if result.data else ""
                return output if output else "(no output)"
            except Exception as e:
                logger.error(f"Failed to execute command in sandbox: {e}")
                return f"Error: {e}"
    def read_file(self, path: str) -> str:
        """Read the content of a file in the sandbox.
@@ -106,16 +82,17 @@ class AioSandbox(Sandbox):
        Returns:
            The contents of the directory.
        """
-        with self._lock:
+        try:
-            try:
+            # Use shell command to list directory with depth limit
-                result = self._client.shell.exec_command(command=f"find {shlex.quote(path)} -maxdepth {max_depth} -type f -o -type d 2>/dev/null | head -500")
+            # The -L flag limits the depth for the tree command
-                output = result.data.output if result.data else ""
+            result = self._client.shell.exec_command(command=f"find {path} -maxdepth {max_depth} -type f -o -type d 2>/dev/null | head -500")
-                if output:
+            output = result.data.output if result.data else ""
-                    return [line.strip() for line in output.strip().split("\n") if line.strip()]
+            if output:
-                return []
+                return [line.strip() for line in output.strip().split("\n") if line.strip()]
-            except Exception as e:
+            return []
-                logger.error(f"Failed to list directory in sandbox: {e}")
+        except Exception as e:
-                return []
+            logger.error(f"Failed to list directory in sandbox: {e}")
            return []
    def write_file(self, path: str, content: str, append: bool = False) -> None:
        """Write content to a file in the sandbox.
@@ -125,96 +102,16 @@ class AioSandbox(Sandbox):
            content: The text content to write to the file.
            append: Whether to append the content to the file.
        """
-        with self._lock:
+        try:
-            try:
+            if append:
-                if append:
+                # Read existing content first and append
-                    existing = self.read_file(path)
+                existing = self.read_file(path)
-                    if not existing.startswith("Error:"):
+                if not existing.startswith("Error:"):
-                        content = existing + content
+                    content = existing + content
-                self._client.file.write_file(file=path, content=content)
+            self._client.file.write_file(file=path, content=content)
-            except Exception as e:
+        except Exception as e:
-                logger.error(f"Failed to write file in sandbox: {e}")
+            logger.error(f"Failed to write file in sandbox: {e}")
-                raise
+            raise
    def glob(self, path: str, pattern: str, *, include_dirs: bool = False, max_results: int = 200) -> tuple[list[str], bool]:
        if not include_dirs:
            result = self._client.file.find_files(path=path, glob=pattern)
            files = result.data.files if result.data and result.data.files else []
            filtered = [file_path for file_path in files if not should_ignore_path(file_path)]
            truncated = len(filtered) > max_results
            return filtered[:max_results], truncated
        result = self._client.file.list_path(path=path, recursive=True, show_hidden=False)
        entries = result.data.files if result.data and result.data.files else []
        matches: list[str] = []
        root_path = path.rstrip("/") or "/"
        root_prefix = root_path if root_path == "/" else f"{root_path}/"
        for entry in entries:
            if entry.path != root_path and not entry.path.startswith(root_prefix):
                continue
            if should_ignore_path(entry.path):
                continue
            rel_path = entry.path[len(root_path) :].lstrip("/")
            if path_matches(pattern, rel_path):
                matches.append(entry.path)
                if len(matches) >= max_results:
                    return matches, True
        return matches, False
    def grep(
        self,
        path: str,
        pattern: str,
        *,
        glob: str | None = None,
        literal: bool = False,
        case_sensitive: bool = False,
        max_results: int = 100,
    ) -> tuple[list[GrepMatch], bool]:
        import re as _re
        regex_source = _re.escape(pattern) if literal else pattern
        # Validate the pattern locally so an invalid regex raises re.error
        # (caught by grep_tool's except re.error handler) rather than a
        # generic remote API error.
        _re.compile(regex_source, 0 if case_sensitive else _re.IGNORECASE)
        regex = regex_source if case_sensitive else f"(?i){regex_source}"
        if glob is not None:
            find_result = self._client.file.find_files(path=path, glob=glob)
            candidate_paths = find_result.data.files if find_result.data and find_result.data.files else []
        else:
            list_result = self._client.file.list_path(path=path, recursive=True, show_hidden=False)
            entries = list_result.data.files if list_result.data and list_result.data.files else []
            candidate_paths = [entry.path for entry in entries if not entry.is_directory]
        matches: list[GrepMatch] = []
        truncated = False
        for file_path in candidate_paths:
            if should_ignore_path(file_path):
                continue
            search_result = self._client.file.search_in_file(file=file_path, regex=regex)
            data = search_result.data
            if data is None:
                continue
            line_numbers = data.line_numbers or []
            matched_lines = data.matches or []
            for line_number, line in zip(line_numbers, matched_lines):
                matches.append(
                    GrepMatch(
                        path=file_path,
                        line_number=line_number if isinstance(line_number, int) else 0,
                        line=truncate_line(line),
                    )
                )
                if len(matches) >= max_results:
                    truncated = True
                    return matches, truncated
        return matches, truncated
    def update_file(self, path: str, content: bytes) -> None:
        """Update a file with binary content in the sandbox.
@@ -223,10 +120,9 @@ class AioSandbox(Sandbox):
            path: The absolute path of the file to update.
            content: The binary content to write to the file.
        """
-        with self._lock:
+        try:
-            try:
+            base64_content = base64.b64encode(content).decode("utf-8")
-                base64_content = base64.b64encode(content).decode("utf-8")
+            self._client.file.write_file(file=path, content=base64_content, encoding="base64")
-                self._client.file.write_file(file=path, content=base64_content, encoding="base64")
+        except Exception as e:
-            except Exception as e:
+            logger.error(f"Failed to update file in sandbox: {e}")
-                logger.error(f"Failed to update file in sandbox: {e}")
+            raise
                raise
@@ -26,7 +26,7 @@ except ImportError:  # pragma: no cover - Windows fallback
    import msvcrt
 from deerflow.config import get_app_config
-from deerflow.config.paths import VIRTUAL_PATH_PREFIX, get_paths
+from deerflow.config.paths import VIRTUAL_PATH_PREFIX, Paths, get_paths
 from deerflow.sandbox.sandbox import Sandbox
 from deerflow.sandbox.sandbox_provider import SandboxProvider
@@ -112,23 +112,10 @@ class AioSandboxProvider(SandboxProvider):
        atexit.register(self.shutdown)
        self._register_signal_handlers()
        # Reconcile orphaned containers from previous process lifecycles
        self._reconcile_orphans()
        # Start idle checker if enabled
        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:
@@ -188,51 +175,6 @@ class AioSandboxProvider(SandboxProvider):
                resolved[key] = str(value)
        return resolved
    # ── Startup reconciliation ────────────────────────────────────────────
    def _reconcile_orphans(self) -> None:
        """Reconcile orphaned containers left by previous process lifecycles.
        On startup, enumerate all running containers matching our prefix
        and adopt them all into the warm pool.  The idle checker will reclaim
        containers that nobody re-acquires within ``idle_timeout``.
        All containers are adopted unconditionally because we cannot
        distinguish "orphaned" from "actively used by another process"
        based on age alone — ``idle_timeout`` represents inactivity, not
        uptime.  Adopting into the warm pool and letting the idle checker
        decide avoids destroying containers that a concurrent process may
        still be using.
        This closes the fundamental gap where in-memory state loss (process
        restart, crash, SIGKILL) leaves Docker containers running forever.
        """
        try:
            running = self._backend.list_running()
        except Exception as e:
            logger.warning(f"Failed to enumerate running containers during startup reconciliation: {e}")
            return
        if not running:
            return
        current_time = time.time()
        adopted = 0
        for info in running:
            age = current_time - info.created_at if info.created_at > 0 else float("inf")
            # Single lock acquisition per container: atomic check-and-insert.
            # Avoids a TOCTOU window between the "already tracked?" check and
            # the warm-pool insert.
            with self._lock:
                if info.sandbox_id in self._sandboxes or info.sandbox_id in self._warm_pool:
                    continue
                self._warm_pool[info.sandbox_id] = (info, current_time)
            adopted += 1
            logger.info(f"Adopted container {info.sandbox_id} into warm pool (age: {age:.0f}s)")
        logger.info(f"Startup reconciliation complete: {adopted} adopted into warm pool, {len(running)} total found")
    # ── Deterministic ID ─────────────────────────────────────────────────
    @staticmethod
@@ -272,13 +214,17 @@ class AioSandboxProvider(SandboxProvider):
        paths = get_paths()
        paths.ensure_thread_dirs(thread_id)
        # host_paths resolves to the host-side base dir when DEER_FLOW_HOST_BASE_DIR
        # is set, otherwise falls back to the container's own base dir (native mode).
        host_paths = Paths(base_dir=paths.host_base_dir)
        return [
-            (paths.host_sandbox_work_dir(thread_id), f"{VIRTUAL_PATH_PREFIX}/workspace", False),
+            (str(host_paths.sandbox_work_dir(thread_id)), f"{VIRTUAL_PATH_PREFIX}/workspace", False),
-            (paths.host_sandbox_uploads_dir(thread_id), f"{VIRTUAL_PATH_PREFIX}/uploads", False),
+            (str(host_paths.sandbox_uploads_dir(thread_id)), f"{VIRTUAL_PATH_PREFIX}/uploads", False),
-            (paths.host_sandbox_outputs_dir(thread_id), f"{VIRTUAL_PATH_PREFIX}/outputs", False),
+            (str(host_paths.sandbox_outputs_dir(thread_id)), f"{VIRTUAL_PATH_PREFIX}/outputs", False),
            # ACP workspace: read-only inside the sandbox (lead agent reads results;
            # the ACP subprocess writes from the host side, not from within the container).
-            (paths.host_acp_workspace_dir(thread_id), "/mnt/acp-workspace", True),
+            (str(host_paths.acp_workspace_dir(thread_id)), "/mnt/acp-workspace", True),
        ]
    @staticmethod
@@ -374,23 +320,13 @@ class AioSandboxProvider(SandboxProvider):
    # ── Signal handling ──────────────────────────────────────────────────
    def _register_signal_handlers(self) -> None:
-        """Register signal handlers for graceful shutdown.
+        """Register signal handlers for graceful shutdown."""
        Handles SIGTERM, SIGINT, and SIGHUP (terminal close) to ensure
        sandbox containers are cleaned up even when the user closes the terminal.
        """
        self._original_sigterm = signal.getsignal(signal.SIGTERM)
        self._original_sigint = signal.getsignal(signal.SIGINT)
        self._original_sighup = signal.getsignal(signal.SIGHUP) if hasattr(signal, "SIGHUP") else None
        def signal_handler(signum, frame):
            self.shutdown()
-            if signum == signal.SIGTERM:
+            original = self._original_sigterm if signum == signal.SIGTERM else self._original_sigint
                original = self._original_sigterm
            elif hasattr(signal, "SIGHUP") and signum == signal.SIGHUP:
                original = self._original_sighup
            else:
                original = self._original_sigint
            if callable(original):
                original(signum, frame)
            elif original == signal.SIG_DFL:
@@ -400,8 +336,6 @@ class AioSandboxProvider(SandboxProvider):
        try:
            signal.signal(signal.SIGTERM, signal_handler)
            signal.signal(signal.SIGINT, signal_handler)
            if hasattr(signal, "SIGHUP"):
                signal.signal(signal.SIGHUP, signal_handler)
        except ValueError:
            logger.debug("Could not register signal handlers (not main thread)")
@@ -96,19 +96,3 @@ class SandboxBackend(ABC):
            SandboxInfo if found and healthy, None otherwise.
        """
        ...
    def list_running(self) -> list[SandboxInfo]:
        """Enumerate all running sandboxes managed by this backend.
        Used for startup reconciliation: when the process restarts, it needs
        to discover containers started by previous processes so they can be
        adopted into the warm pool or destroyed if idle too long.
        The default implementation returns an empty list, which is correct
        for backends that don't manage local containers (e.g., RemoteSandboxBackend
        delegates lifecycle to the provisioner which handles its own cleanup).
        Returns:
            A list of SandboxInfo for all currently running sandboxes.
        """
        return []
@@ -6,11 +6,9 @@ Handles container lifecycle, port allocation, and cross-process container discov
 from __future__ import annotations
 import json
 import logging
 import os
 import subprocess
 from datetime import datetime
 from deerflow.utils.network import get_free_port, release_port
@@ -20,72 +18,6 @@ from .sandbox_info import SandboxInfo
 logger = logging.getLogger(__name__)
 def _parse_docker_timestamp(raw: str) -> float:
    """Parse Docker's ISO 8601 timestamp into a Unix epoch float.
    Docker returns timestamps with nanosecond precision and a trailing ``Z``
    (e.g. ``2026-04-08T01:22:50.123456789Z``).  Python's ``fromisoformat``
    accepts at most microseconds and (pre-3.11) does not accept ``Z``, so the
    string is normalized before parsing.  Returns ``0.0`` on empty input or
    parse failure so callers can use ``0.0`` as a sentinel for "unknown age".
    """
    if not raw:
        return 0.0
    try:
        s = raw.strip()
        if "." in s:
            dot_pos = s.index(".")
            tz_start = dot_pos + 1
            while tz_start < len(s) and s[tz_start].isdigit():
                tz_start += 1
            frac = s[dot_pos + 1 : tz_start][:6]  # truncate to microseconds
            tz_suffix = s[tz_start:]
            s = s[: dot_pos + 1] + frac + tz_suffix
        if s.endswith("Z"):
            s = s[:-1] + "+00:00"
        return datetime.fromisoformat(s).timestamp()
    except (ValueError, TypeError) as e:
        logger.debug(f"Could not parse docker timestamp {raw!r}: {e}")
        return 0.0
 def _extract_host_port(inspect_entry: dict, container_port: int) -> int | None:
    """Extract the host port mapped to ``container_port/tcp`` from a docker inspect entry.
    Returns None if the container has no port mapping for that port.
    """
    try:
        ports = (inspect_entry.get("NetworkSettings") or {}).get("Ports") or {}
        bindings = ports.get(f"{container_port}/tcp") or []
        if bindings:
            host_port = bindings[0].get("HostPort")
            if host_port:
                return int(host_port)
    except (ValueError, TypeError, AttributeError):
        pass
    return None
 def _format_container_mount(runtime: str, host_path: str, container_path: str, read_only: bool) -> list[str]:
    """Format a bind-mount argument for the selected runtime.
    Docker's ``-v host:container`` syntax is ambiguous for Windows drive-letter
    paths like ``D:/...`` because ``:`` is both the drive separator and the
    volume separator. Use ``--mount type=bind,...`` for Docker to avoid that
    parsing ambiguity. Apple Container keeps using ``-v``.
    """
    if runtime == "docker":
        mount_spec = f"type=bind,src={host_path},dst={container_path}"
        if read_only:
            mount_spec += ",readonly"
        return ["--mount", mount_spec]
    mount_spec = f"{host_path}:{container_path}"
    if read_only:
        mount_spec += ":ro"
    return ["-v", mount_spec]
 class LocalContainerBackend(SandboxBackend):
    """Backend that manages sandbox containers locally using Docker or Apple Container.
@@ -220,12 +152,8 @@ class LocalContainerBackend(SandboxBackend):
    def destroy(self, info: SandboxInfo) -> None:
        """Stop the container and release its port."""
-        # Prefer container_id, fall back to container_name (both accepted by docker stop).
+        if info.container_id:
-        # This ensures containers discovered via list_running() (which only has the name)
+            self._stop_container(info.container_id)
        # can also be stopped.
        stop_target = info.container_id or info.container_name
        if stop_target:
            self._stop_container(stop_target)
        # Extract port from sandbox_url for release
        try:
            from urllib.parse import urlparse
@@ -274,129 +202,6 @@ class LocalContainerBackend(SandboxBackend):
            container_name=container_name,
        )
    def list_running(self) -> list[SandboxInfo]:
        """Enumerate all running containers matching the configured prefix.
        Uses a single ``docker ps`` call to list container names, then a
        single batched ``docker inspect`` call to retrieve creation timestamp
        and port mapping for all containers at once.  Total subprocess calls:
        2 (down from 2N+1 in the naive per-container approach).
        Note: Docker's ``--filter name=`` performs *substring* matching,
        so a secondary ``startswith`` check is applied to ensure only
        containers with the exact prefix are included.
        Containers without port mappings are still included (with empty
        sandbox_url) so that startup reconciliation can adopt orphans
        regardless of their port state.
        """
        # Step 1: enumerate container names via docker ps
        try:
            result = subprocess.run(
                [
                    self._runtime,
                    "ps",
                    "--filter",
                    f"name={self._container_prefix}-",
                    "--format",
                    "{{.Names}}",
                ],
                capture_output=True,
                text=True,
                timeout=10,
            )
            if result.returncode != 0:
                stderr = (result.stderr or "").strip()
                logger.warning(
                    "Failed to list running containers with %s ps (returncode=%s, stderr=%s)",
                    self._runtime,
                    result.returncode,
                    stderr or "<empty>",
                )
                return []
            if not result.stdout.strip():
                return []
        except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError, OSError) as e:
            logger.warning(f"Failed to list running containers: {e}")
            return []
        # Filter to names matching our exact prefix (docker filter is substring-based)
        container_names = [name.strip() for name in result.stdout.strip().splitlines() if name.strip().startswith(self._container_prefix + "-")]
        if not container_names:
            return []
        # Step 2: batched docker inspect — single subprocess call for all containers
        inspections = self._batch_inspect(container_names)
        infos: list[SandboxInfo] = []
        sandbox_host = os.environ.get("DEER_FLOW_SANDBOX_HOST", "localhost")
        for container_name in container_names:
            data = inspections.get(container_name)
            if data is None:
                # Container disappeared between ps and inspect, or inspect failed
                continue
            created_at, host_port = data
            sandbox_id = container_name[len(self._container_prefix) + 1 :]
            sandbox_url = f"http://{sandbox_host}:{host_port}" if host_port else ""
            infos.append(
                SandboxInfo(
                    sandbox_id=sandbox_id,
                    sandbox_url=sandbox_url,
                    container_name=container_name,
                    created_at=created_at,
                )
            )
        logger.info(f"Found {len(infos)} running sandbox container(s)")
        return infos
    def _batch_inspect(self, container_names: list[str]) -> dict[str, tuple[float, int | None]]:
        """Batch-inspect containers in a single subprocess call.
        Returns a mapping of ``container_name -> (created_at, host_port)``.
        Missing containers or parse failures are silently dropped from the result.
        """
        if not container_names:
            return {}
        try:
            result = subprocess.run(
                [self._runtime, "inspect", *container_names],
                capture_output=True,
                text=True,
                timeout=15,
            )
        except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError, OSError) as e:
            logger.warning(f"Failed to batch-inspect containers: {e}")
            return {}
        if result.returncode != 0:
            stderr = (result.stderr or "").strip()
            logger.warning(
                "Failed to batch-inspect containers with %s inspect (returncode=%s, stderr=%s)",
                self._runtime,
                result.returncode,
                stderr or "<empty>",
            )
            return {}
        try:
            payload = json.loads(result.stdout or "[]")
        except json.JSONDecodeError as e:
            logger.warning(f"Failed to parse docker inspect output as JSON: {e}")
            return {}
        out: dict[str, tuple[float, int | None]] = {}
        for entry in payload:
            # ``Name`` is prefixed with ``/`` in the docker inspect response
            name = (entry.get("Name") or "").lstrip("/")
            if not name:
                continue
            created_at = _parse_docker_timestamp(entry.get("Created", ""))
            host_port = _extract_host_port(entry, 8080)
            out[name] = (created_at, host_port)
        return out
    # ── Container operations ─────────────────────────────────────────────
    def _start_container(
@@ -441,26 +246,18 @@ class LocalContainerBackend(SandboxBackend):
        # Config-level volume mounts
        for mount in self._config_mounts:
-            cmd.extend(
+            mount_spec = f"{mount.host_path}:{mount.container_path}"
-                _format_container_mount(
+            if mount.read_only:
-                    self._runtime,
+                mount_spec += ":ro"
-                    mount.host_path,
+            cmd.extend(["-v", mount_spec])
                    mount.container_path,
                    mount.read_only,
                )
            )
        # Extra mounts (thread-specific, skills, etc.)
        if extra_mounts:
            for host_path, container_path, read_only in extra_mounts:
-                cmd.extend(
+                mount_spec = f"{host_path}:{container_path}"
-                    _format_container_mount(
+                if read_only:
-                        self._runtime,
+                    mount_spec += ":ro"
-                        host_path,
+                cmd.extend(["-v", mount_spec])
                        container_path,
                        read_only,
                    )
                )
        cmd.append(self._image)
--- a/Show More
+++ b/Show More