Merge remote-tracking branch 'origin/rayhpeng/persistence-scaffold' into rayhpeng/persistence-scaffold

Following the rename/delete bug fix in PR1, migrate the remaining direct
LangGraph Store reads/writes in the threads router and services to the
ThreadMetaStore abstraction so that the sqlite and memory backends behave
identically and the legacy dual-write paths can be removed.

Migrated endpoints (threads.py):
- create_thread: idempotency check + write now use thread_meta_repo.get/create
  instead of dual-writing the LangGraph Store and the SQL row.
- get_thread: reads from thread_meta_repo.get; the checkpoint-only fallback
  for legacy threads is preserved.
- patch_thread: replaced _store_get/_store_put with thread_meta_repo.update_metadata.
- delete_thread_data: dropped the legacy store.adelete; thread_meta_repo.delete
  already covers it.

Removed dead code (services.py):
- _upsert_thread_in_store — redundant with the immediately following
  thread_meta_repo.create() call.
- _sync_thread_title_after_run — worker.py's finally block already syncs
  the title via thread_meta_repo.update_display_name() after each run.

Removed dead code (threads.py):
- _store_get / _store_put / _store_upsert helpers (no remaining callers).
- THREADS_NS constant.
- get_store import (router no longer touches the LangGraph Store directly).

New abstract method:
- ThreadMetaStore.update_metadata(thread_id, metadata) merges metadata into
  the thread's metadata field. Implemented in both ThreadMetaRepository (SQL,
  read-modify-write inside one session) and MemoryThreadMetaStore. Three new
  unit tests cover merge / empty / nonexistent behaviour.

Net change: -134 lines. Full test suite: 1693 passed, 14 skipped.
Verified end-to-end with curl in gateway mode against sqlite backend
(create / patch / get / rename / search / delete).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.agent/skills/smoke-test/SKILL.md

@@ -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

.agent/skills/smoke-test/references/SOP.md

@@ -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.

.agent/skills/smoke-test/references/troubleshooting.md

@@ -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

.agent/skills/smoke-test/scripts/check_docker.sh

@@ -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 "=========================================="

.agent/skills/smoke-test/scripts/check_local_env.sh

@@ -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

.agent/skills/smoke-test/scripts/deploy_docker.sh

@@ -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"

.agent/skills/smoke-test/scripts/deploy_local.sh

@@ -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"

.agent/skills/smoke-test/scripts/frontend_check.sh

@@ -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

.agent/skills/smoke-test/scripts/health_check.sh

@@ -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

.agent/skills/smoke-test/scripts/pull_code.sh

@@ -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 "=========================================="

.agent/skills/smoke-test/templates/report.docker.template.md

@@ -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}}*

.agent/skills/smoke-test/templates/report.local.template.md

@@ -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}}*

.env.example

@@ -24,7 +24,6 @@ INFOQUEST_API_KEY=your-infoquest-api-key
 # 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 +33,9 @@ INFOQUEST_API_KEY=your-infoquest-api-key
 
 # GitHub API Token
 # GITHUB_TOKEN=your-github-token
+
+# Database (only needed when config.yaml has database.backend: postgres)
+# DATABASE_URL=postgresql://deerflow:password@localhost:5432/deerflow
+#
 # WECOM_BOT_ID=your-wecom-bot-id
 # WECOM_BOT_SECRET=your-wecom-bot-secret

.github/workflows/e2e-tests.yml

@@ -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

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

@@ -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

.gitignore

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

CODE_OF_CONDUCT.md

@@ -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.

CONTRIBUTING.md

@@ -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:
@@ -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
-
-# Frontend E2E tests (requires Chromium; builds and auto-starts the Next.js production server)
-cd frontend
-make test-e2e
+pnpm check
 ```
 
 ### 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)
-- **Frontend unit tests** — [.github/workflows/frontend-unit-tests.yml](.github/workflows/frontend-unit-tests.yml)
-- **Frontend E2E tests** — [.github/workflows/e2e-tests.yml](.github/workflows/e2e-tests.yml) (triggered only when `frontend/` files change)
+- `tests/test_provisioner_kubeconfig.py`
+- `tests/test_docker_sandbox_mode_detection.py`
 
 ## Code Style
 

Makefile

@@ -1,25 +1,19 @@
 # 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-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
 
 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"
@@ -50,18 +44,11 @@ help:
 	@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:
@@ -119,46 +106,78 @@ setup-sandbox:
 # Start all services in development mode (with hot-reloading)
 dev:
 	@$(PYTHON) ./scripts/check.py
-	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --dev
+ifeq ($(OS),Windows_NT)
+	@call scripts\run-with-git-bash.cmd ./scripts/serve.sh --dev
+else
+	@./scripts/serve.sh --dev
+endif
 
 # Start all services in dev + Gateway mode (experimental: agent runtime embedded in Gateway)
 dev-pro:
 	@$(PYTHON) ./scripts/check.py
-	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --dev --gateway
+ifeq ($(OS),Windows_NT)
+	@call scripts\run-with-git-bash.cmd ./scripts/serve.sh --dev --gateway
+else
+	@./scripts/serve.sh --dev --gateway
+endif
 
 # Start all services in production mode (with optimizations)
 start:
 	@$(PYTHON) ./scripts/check.py
-	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --prod
+ifeq ($(OS),Windows_NT)
+	@call scripts\run-with-git-bash.cmd ./scripts/serve.sh --prod
+else
+	@./scripts/serve.sh --prod
+endif
 
 # Start all services in prod + Gateway mode (experimental)
 start-pro:
 	@$(PYTHON) ./scripts/check.py
-	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --prod --gateway
+ifeq ($(OS),Windows_NT)
+	@call scripts\run-with-git-bash.cmd ./scripts/serve.sh --prod --gateway
+else
+	@./scripts/serve.sh --prod --gateway
+endif
 
 # Start all services in daemon mode (background)
 dev-daemon:
 	@$(PYTHON) ./scripts/check.py
-	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --dev --daemon
+ifeq ($(OS),Windows_NT)
+	@call scripts\run-with-git-bash.cmd ./scripts/serve.sh --dev --daemon
+else
+	@./scripts/serve.sh --dev --daemon
+endif
 
 # Start daemon + Gateway mode (experimental)
 dev-daemon-pro:
 	@$(PYTHON) ./scripts/check.py
-	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --dev --gateway --daemon
+ifeq ($(OS),Windows_NT)
+	@call scripts\run-with-git-bash.cmd ./scripts/serve.sh --dev --gateway --daemon
+else
+	@./scripts/serve.sh --dev --gateway --daemon
+endif
 
 # Start prod services in daemon mode (background)
 start-daemon:
 	@$(PYTHON) ./scripts/check.py
-	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --prod --daemon
+ifeq ($(OS),Windows_NT)
+	@call scripts\run-with-git-bash.cmd ./scripts/serve.sh --prod --daemon
+else
+	@./scripts/serve.sh --prod --daemon
+endif
 
 # Start prod daemon + Gateway mode (experimental)
 start-daemon-pro:
 	@$(PYTHON) ./scripts/check.py
-	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --prod --gateway --daemon
+ifeq ($(OS),Windows_NT)
+	@call scripts\run-with-git-bash.cmd ./scripts/serve.sh --prod --gateway --daemon
+else
+	@./scripts/serve.sh --prod --gateway --daemon
+endif
 
 # Stop all services
 stop:
-	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --stop
+	@./scripts/serve.sh --stop
 
 # Clean up
 clean: stop
@@ -174,29 +193,29 @@ 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
+	@./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
@@ -204,12 +223,12 @@ 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
+	@./scripts/deploy.sh --gateway
 
 # Stop and remove production containers
 down:
-	@$(RUN_WITH_GIT_BASH) ./scripts/deploy.sh down
+	@./scripts/deploy.sh down

README.md

@@ -53,7 +53,6 @@ DeerFlow has newly integrated the intelligent search and crawling toolset indepe
   - [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)
@@ -104,38 +103,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.
-
-   > **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>
+   Edit `config.yaml` and define at least one model:
 
    ```yaml
    models:
-     - name: gpt-4o
-       display_name: GPT-4o
-       use: langchain_openai:ChatOpenAI
-       model: gpt-4o
-       api_key: $OPENAI_API_KEY
+     - name: gpt-4                       # Internal identifier
+       display_name: GPT-4               # Human-readable name
+       use: langchain_openai:ChatOpenAI  # LangChain class path
+       model: gpt-4                      # Model identifier for API
+       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
@@ -185,39 +181,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`
-   - 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`
-   - On macOS, export Claude Code auth explicitly if needed:
+   - The Codex Responses endpoint currently rejects `max_tokens` and `max_output_tokens`, so `CodexChatModel` does not expose a request-level token cap
+   - 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`
+   - 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)"
    ```
+   
+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)
 
-   API keys can also be set manually in `.env` (recommended) or exported in your shell:
 
    ```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,7 +261,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**:
@@ -368,7 +375,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`:**
@@ -413,19 +419,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
@@ -459,10 +452,6 @@ SLACK_APP_TOKEN=xapp-...
 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
@@ -488,14 +477,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`.
@@ -658,8 +639,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.

README_zh.md

@@ -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（推荐）
 
 **开发模式**（支持热更新，挂载源码）：

backend/CLAUDE.md

@@ -156,26 +156,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"]`
-5. **LLMErrorHandlingMiddleware** - Normalizes provider/model invocation failures into recoverable assistant-facing errors before later middleware/tool stages run
-6. **GuardrailMiddleware** - Pre-tool-call authorization via pluggable `GuardrailProvider` protocol (optional, if `guardrails.enabled` in config). Evaluates each tool call and returns error ToolMessage on deny. Three provider options: built-in `AllowlistProvider` (zero deps), OAP policy providers (e.g. `aport-agent-guardrails`), or custom providers. See [docs/GUARDRAILS.md](docs/GUARDRAILS.md) for setup, usage, and how to implement a provider.
-7. **SandboxAuditMiddleware** - Audits sandboxed shell/file operations for security logging before tool execution continues
-8. **ToolErrorHandlingMiddleware** - Converts tool exceptions into error `ToolMessage`s so the run can continue instead of aborting
-9. **SummarizationMiddleware** - Context reduction when approaching token limits (optional, if enabled)
-10. **TodoListMiddleware** - Task tracking with `write_todos` tool (optional, if plan_mode)
-11. **TokenUsageMiddleware** - Records token usage metrics when token tracking is enabled (optional)
-12. **TitleMiddleware** - Auto-generates thread title after first complete exchange and normalizes structured message content before prompting the title model
-13. **MemoryMiddleware** - Queues conversations for async memory update (filters to user + final AI responses)
-14. **ViewImageMiddleware** - Injects base64 image data before LLM call (conditional on vision support)
-15. **DeferredToolFilterMiddleware** - Hides deferred tool schemas from the bound model until tool search is enabled (optional)
-16. **SubagentLimitMiddleware** - Truncates excess `task` tool calls from model response to enforce `MAX_CONCURRENT_SUBAGENTS` limit (optional, if `subagent_enabled`)
-17. **LoopDetectionMiddleware** - Detects repeated tool-call loops; hard-stop responses clear both structured `tool_calls` and raw provider tool-call metadata before forcing a final text answer
-18. **ClarificationMiddleware** - Intercepts `ask_clarification` tool calls, interrupts via `Command(goto=END)` (must be last)
+4. **DanglingToolCallMiddleware** - Injects placeholder ToolMessages for AIMessage tool_calls that lack responses (e.g., due to user interruption)
+5. **GuardrailMiddleware** - Pre-tool-call authorization via pluggable `GuardrailProvider` protocol (optional, if `guardrails.enabled` in config). Evaluates each tool call and returns error ToolMessage on deny. Three provider options: built-in `AllowlistProvider` (zero deps), OAP policy providers (e.g. `aport-agent-guardrails`), or custom providers. See [docs/GUARDRAILS.md](docs/GUARDRAILS.md) for setup, usage, and how to implement a provider.
+6. **SummarizationMiddleware** - Context reduction when approaching token limits (optional, if enabled)
+7. **TodoListMiddleware** - Task tracking with `write_todos` tool (optional, if plan_mode)
+8. **TitleMiddleware** - Auto-generates thread title after first complete exchange and normalizes structured message content before prompting the title model
+9. **MemoryMiddleware** - Queues conversations for async memory update (filters to user + final AI responses)
+10. **ViewImageMiddleware** - Injects base64 image data before LLM call (conditional on vision support)
+11. **SubagentLimitMiddleware** - Truncates excess `task` tool calls from model response to enforce `MAX_CONCURRENT_SUBAGENTS` limit (optional, if subagent_enabled)
+12. **ClarificationMiddleware** - Intercepts `ask_clarification` tool calls, interrupts via `Command(goto=END)` (must be last)
 
 ### Configuration System
 
@@ -401,16 +395,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
-- `stream(message, thread_id)` — subscribes to LangGraph `stream_mode=["values", "messages", "custom"]` and yields `StreamEvent`:
-  - `"values"` — full state snapshot (title, messages, artifacts); AI text already delivered via `messages` mode is **not** re-synthesized here to avoid duplicate deliveries
-  - `"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
-  - `"custom"` — forwarded from `StreamWriter`
-  - `"end"` — stream finished (carries cumulative `usage` counted once per message id)
+- `chat(message, thread_id)` — synchronous, returns final text
+- `stream(message, thread_id)` — yields `StreamEvent` aligned with LangGraph SSE protocol:
+  - `"values"` — full state snapshot (title, messages, artifacts)
+  - `"messages-tuple"` — per-message update (AI text, tool calls, tool results)
+  - `"end"` — stream finished
 - 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):
 

backend/Dockerfile

@@ -13,6 +13,9 @@ FROM python:3.12-slim-bookworm AS builder
 ARG NODE_MAJOR=22
 ARG APT_MIRROR
 ARG UV_INDEX_URL
+# Optional extras to install (e.g. "postgres" for PostgreSQL support)
+# Usage: docker build --build-arg UV_EXTRAS=postgres ...
+ARG UV_EXTRAS
 
 # Optionally override apt mirror for restricted networks (e.g. APT_MIRROR=mirrors.aliyun.com)
 RUN if [ -n "${APT_MIRROR}" ]; then \
@@ -43,8 +46,9 @@ WORKDIR /app
 COPY backend ./backend
 
 # Install dependencies with cache mount
+# When UV_EXTRAS is set (e.g. "postgres"), installs optional dependencies.
 RUN --mount=type=cache,target=/root/.cache/uv \
-    sh -c "cd backend && UV_INDEX_URL=${UV_INDEX_URL:-https://pypi.org/simple} uv sync"
+    sh -c "cd backend && UV_INDEX_URL=${UV_INDEX_URL:-https://pypi.org/simple} uv sync ${UV_EXTRAS:+--extra $UV_EXTRAS}"
 
 # ── Stage 2: Dev ──────────────────────────────────────────────────────────────
 # Retains compiler toolchain from builder so startup-time `uv sync` can build
@@ -84,4 +88,4 @@ COPY --from=builder /app/backend ./backend
 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"]

backend/app/channels/discord.py

@@ -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

backend/app/channels/manager.py

@@ -8,7 +8,6 @@ import mimetypes
 import re
 import time
 from collections.abc import Awaitable, Callable, Mapping
-from pathlib import Path
 from typing import Any
 
 import httpx
@@ -35,11 +34,9 @@ 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},
 }
 
@@ -81,24 +78,7 @@ async def _read_wecom_inbound_file(file_info: dict[str, Any], client: httpx.Asyn
     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):

backend/app/channels/service.py

@@ -15,11 +15,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",
 }
 

backend/app/gateway/app.py

@@ -11,6 +11,7 @@ from app.gateway.routers import (
     artifacts,
     assistants_compat,
     channels,
+    feedback,
     mcp,
     memory,
     models,
@@ -199,6 +200,9 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
     # Assistants compatibility API (LangGraph Platform stub)
     app.include_router(assistants_compat.router)
 
+    # Feedback API is mounted at /api/threads/{thread_id}/runs/{run_id}/feedback
+    app.include_router(feedback.router)
+
     # Thread Runs API (LangGraph Platform-compatible runs lifecycle)
     app.include_router(thread_runs.router)
 

backend/app/gateway/deps.py

@@ -1,7 +1,8 @@
 """Centralized accessors for singleton objects stored on ``app.state``.
 
 **Getters** (used by routers): raise 503 when a required dependency is
-missing, except ``get_store`` which returns ``None``.
+missing, except ``get_store`` and ``get_thread_meta_repo`` which return
+``None``.
 
 Initialization is handled directly in ``app.py`` via :class:`AsyncExitStack`.
 """
@@ -13,7 +14,7 @@ from contextlib import AsyncExitStack, asynccontextmanager
 
 from fastapi import FastAPI, HTTPException, Request
 
-from deerflow.runtime import RunManager, StreamBridge
+from deerflow.runtime import RunContext, RunManager
 
 
 @asynccontextmanager
@@ -26,45 +27,110 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
             yield
     """
     from deerflow.agents.checkpointer.async_provider import make_checkpointer
+    from deerflow.config import get_app_config
+    from deerflow.persistence.engine import close_engine, get_session_factory, init_engine_from_config
     from deerflow.runtime import make_store, make_stream_bridge
+    from deerflow.runtime.events.store import make_run_event_store
 
     async with AsyncExitStack() as stack:
         app.state.stream_bridge = await stack.enter_async_context(make_stream_bridge())
+
+        # Initialize persistence engine BEFORE checkpointer so that
+        # auto-create-database logic runs first (postgres backend).
+        config = get_app_config()
+        await init_engine_from_config(config.database)
+
         app.state.checkpointer = await stack.enter_async_context(make_checkpointer())
         app.state.store = await stack.enter_async_context(make_store())
-        app.state.run_manager = RunManager()
-        yield
+
+        # Initialize repositories — one get_session_factory() call for all.
+        sf = get_session_factory()
+        if sf is not None:
+            from deerflow.persistence.feedback import FeedbackRepository
+            from deerflow.persistence.run import RunRepository
+            from deerflow.persistence.thread_meta import ThreadMetaRepository
+
+            app.state.run_store = RunRepository(sf)
+            app.state.feedback_repo = FeedbackRepository(sf)
+            app.state.thread_meta_repo = ThreadMetaRepository(sf)
+        else:
+            from deerflow.persistence.thread_meta import MemoryThreadMetaStore
+            from deerflow.runtime.runs.store.memory import MemoryRunStore
+
+            app.state.run_store = MemoryRunStore()
+            app.state.feedback_repo = None
+            app.state.thread_meta_repo = MemoryThreadMetaStore(app.state.store)
+
+        # Run event store (has its own factory with config-driven backend selection)
+        run_events_config = getattr(config, "run_events", None)
+        app.state.run_event_store = make_run_event_store(run_events_config)
+
+        # RunManager with store backing for persistence
+        app.state.run_manager = RunManager(store=app.state.run_store)
+
+        try:
+            yield
+        finally:
+            await close_engine()
 
 
 # ---------------------------------------------------------------------------
-# Getters – called by routers per-request
+# Getters -- called by routers per-request
 # ---------------------------------------------------------------------------
 
 
-def get_stream_bridge(request: Request) -> StreamBridge:
-    """Return the global :class:`StreamBridge`, or 503."""
-    bridge = getattr(request.app.state, "stream_bridge", None)
-    if bridge is None:
-        raise HTTPException(status_code=503, detail="Stream bridge not available")
-    return bridge
+def _require(attr: str, label: str):
+    """Create a FastAPI dependency that returns ``app.state.<attr>`` or 503."""
+
+    def dep(request: Request):
+        val = getattr(request.app.state, attr, None)
+        if val is None:
+            raise HTTPException(status_code=503, detail=f"{label} not available")
+        return val
+
+    dep.__name__ = dep.__qualname__ = f"get_{attr}"
+    return dep
 
 
-def get_run_manager(request: Request) -> RunManager:
-    """Return the global :class:`RunManager`, or 503."""
-    mgr = getattr(request.app.state, "run_manager", None)
-    if mgr is None:
-        raise HTTPException(status_code=503, detail="Run manager not available")
-    return mgr
-
-
-def get_checkpointer(request: Request):
-    """Return the global checkpointer, or 503."""
-    cp = getattr(request.app.state, "checkpointer", None)
-    if cp is None:
-        raise HTTPException(status_code=503, detail="Checkpointer not available")
-    return cp
+get_stream_bridge = _require("stream_bridge", "Stream bridge")
+get_run_manager = _require("run_manager", "Run manager")
+get_checkpointer = _require("checkpointer", "Checkpointer")
+get_run_event_store = _require("run_event_store", "Run event store")
+get_feedback_repo = _require("feedback_repo", "Feedback")
+get_run_store = _require("run_store", "Run store")
 
 
 def get_store(request: Request):
     """Return the global store (may be ``None`` if not configured)."""
     return getattr(request.app.state, "store", None)
+
+
+get_thread_meta_repo = _require("thread_meta_repo", "Thread metadata store")
+
+
+def get_run_context(request: Request) -> RunContext:
+    """Build a :class:`RunContext` from ``app.state`` singletons.
+
+    Returns a *base* context with infrastructure dependencies.  Callers that
+    need per-run fields (e.g. ``follow_up_to_run_id``) should use
+    ``dataclasses.replace(ctx, follow_up_to_run_id=...)`` before passing it
+    to :func:`run_agent`.
+    """
+    from deerflow.config import get_app_config
+
+    return RunContext(
+        checkpointer=get_checkpointer(request),
+        store=get_store(request),
+        event_store=get_run_event_store(request),
+        run_events_config=getattr(get_app_config(), "run_events", None),
+        thread_meta_repo=get_thread_meta_repo(request),
+    )
+
+
+async def get_current_user(request: Request) -> str | None:
+    """Extract user identity from request.
+
+    Phase 2: always returns None (no authentication).
+    Phase 3: extract user_id from JWT / session / API key header.
+    """
+    return None

backend/app/gateway/routers/agents.py

@@ -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
 
@@ -74,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
@@ -110,8 +100,6 @@ async def list_agents() -> AgentsListResponse:
     Returns:
         List of all custom agents with their metadata and soul content.
     """
-    _require_agents_api_enabled()
-
     try:
         agents = list_custom_agents()
         return AgentsListResponse(agents=[_agent_config_to_response(a, include_soul=True) for a in agents])
@@ -137,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()
@@ -162,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)
 
@@ -195,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)
 
@@ -258,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)
 
@@ -331,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():
@@ -359,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)
@@ -387,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)
 

backend/app/gateway/routers/feedback.py

@@ -0,0 +1,127 @@
+"""Feedback endpoints — create, list, stats, delete.
+
+Allows users to submit thumbs-up/down feedback on runs,
+optionally scoped to a specific message.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from app.gateway.deps import get_current_user, get_feedback_repo, get_run_store
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/threads", tags=["feedback"])
+
+
+# ---------------------------------------------------------------------------
+# Request / response models
+# ---------------------------------------------------------------------------
+
+
+class FeedbackCreateRequest(BaseModel):
+    rating: int = Field(..., description="Feedback rating: +1 (positive) or -1 (negative)")
+    comment: str | None = Field(default=None, description="Optional text feedback")
+    message_id: str | None = Field(default=None, description="Optional: scope feedback to a specific message")
+
+
+class FeedbackResponse(BaseModel):
+    feedback_id: str
+    run_id: str
+    thread_id: str
+    owner_id: str | None = None
+    message_id: str | None = None
+    rating: int
+    comment: str | None = None
+    created_at: str = ""
+
+
+class FeedbackStatsResponse(BaseModel):
+    run_id: str
+    total: int = 0
+    positive: int = 0
+    negative: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.post("/{thread_id}/runs/{run_id}/feedback", response_model=FeedbackResponse)
+async def create_feedback(
+    thread_id: str,
+    run_id: str,
+    body: FeedbackCreateRequest,
+    request: Request,
+) -> dict[str, Any]:
+    """Submit feedback (thumbs-up/down) for a run."""
+    if body.rating not in (1, -1):
+        raise HTTPException(status_code=400, detail="rating must be +1 or -1")
+
+    user_id = await get_current_user(request)
+
+    # Validate run exists and belongs to thread
+    run_store = get_run_store(request)
+    run = await run_store.get(run_id)
+    if run is None:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+    if run.get("thread_id") != thread_id:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found in thread {thread_id}")
+
+    feedback_repo = get_feedback_repo(request)
+    return await feedback_repo.create(
+        run_id=run_id,
+        thread_id=thread_id,
+        rating=body.rating,
+        owner_id=user_id,
+        message_id=body.message_id,
+        comment=body.comment,
+    )
+
+
+@router.get("/{thread_id}/runs/{run_id}/feedback", response_model=list[FeedbackResponse])
+async def list_feedback(
+    thread_id: str,
+    run_id: str,
+    request: Request,
+) -> list[dict[str, Any]]:
+    """List all feedback for a run."""
+    feedback_repo = get_feedback_repo(request)
+    return await feedback_repo.list_by_run(thread_id, run_id)
+
+
+@router.get("/{thread_id}/runs/{run_id}/feedback/stats", response_model=FeedbackStatsResponse)
+async def feedback_stats(
+    thread_id: str,
+    run_id: str,
+    request: Request,
+) -> dict[str, Any]:
+    """Get aggregated feedback stats (positive/negative counts) for a run."""
+    feedback_repo = get_feedback_repo(request)
+    return await feedback_repo.aggregate_by_run(thread_id, run_id)
+
+
+@router.delete("/{thread_id}/runs/{run_id}/feedback/{feedback_id}")
+async def delete_feedback(
+    thread_id: str,
+    run_id: str,
+    feedback_id: str,
+    request: Request,
+) -> dict[str, bool]:
+    """Delete a feedback record."""
+    feedback_repo = get_feedback_repo(request)
+    # Verify feedback belongs to the specified thread/run before deleting
+    existing = await feedback_repo.get(feedback_id)
+    if existing is None:
+        raise HTTPException(status_code=404, detail=f"Feedback {feedback_id} not found")
+    if existing.get("thread_id") != thread_id or existing.get("run_id") != run_id:
+        raise HTTPException(status_code=404, detail=f"Feedback {feedback_id} not found in run {run_id}")
+    deleted = await feedback_repo.delete(feedback_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail=f"Feedback {feedback_id} not found")
+    return {"success": True}

backend/app/gateway/routers/models.py

@@ -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_reasoning_effort": false
+                    "supports_thinking": false
                 },
                 {
                     "name": "claude-3-opus",
-                    "model": "claude-3-opus",
                     "display_name": "Claude 3 Opus",
                     "description": "Anthropic Claude 3 Opus model",
-                    "supports_thinking": true,
-                    "supports_reasoning_effort": false
+                    "supports_thinking": true
                 }
-            ],
-            "token_usage": {
-                "enabled": true
-            }
+            ]
         }
         ```
     """
@@ -84,10 +70,7 @@ async def list_models() -> ModelsListResponse:
         )
         for model in config.models
     ]
-    return ModelsListResponse(
-        models=models,
-        token_usage=TokenUsageResponse(enabled=config.token_usage.enabled),
-    )
+    return ModelsListResponse(models=models)
 
 
 @router.get(

backend/app/gateway/routers/skills.py

@@ -1,4 +1,3 @@
-import errno
 import json
 import logging
 import shutil
@@ -8,7 +7,7 @@ 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.agents.lead_agent.prompt import clear_skills_system_prompt_cache
 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
@@ -120,7 +119,6 @@ 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))
@@ -183,7 +181,7 @@ async def update_custom_skill(skill_name: str, request: CustomSkillUpdateRequest
                 "scanner": {"decision": scan.decision, "reason": scan.reason},
             },
         )
-        await refresh_skills_system_prompt_cache_async()
+        clear_skills_system_prompt_cache()
         return await get_custom_skill(skill_name)
     except HTTPException:
         raise
@@ -202,25 +200,20 @@ async def delete_custom_skill(skill_name: str) -> dict[str, bool]:
         ensure_custom_skill_is_editable(skill_name)
         skill_dir = get_custom_skill_dir(skill_name)
         prev_content = read_custom_skill_content(skill_name)
-        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)
+        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."},
+            },
+        )
         shutil.rmtree(skill_dir)
-        await refresh_skills_system_prompt_cache_async()
+        clear_skills_system_prompt_cache()
         return {"success": True}
     except FileNotFoundError as e:
         raise HTTPException(status_code=404, detail=str(e))
@@ -275,7 +268,7 @@ async def rollback_custom_skill(skill_name: str, request: SkillRollbackRequest)
             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()
+        clear_skills_system_prompt_cache()
         return await get_custom_skill(skill_name)
     except HTTPException:
         raise
@@ -344,7 +337,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)

backend/app/gateway/routers/thread_runs.py

@@ -19,7 +19,7 @@ from fastapi import APIRouter, HTTPException, Query, Request
 from fastapi.responses import Response, StreamingResponse
 from pydantic import BaseModel, Field
 
-from app.gateway.deps import get_checkpointer, get_run_manager, get_stream_bridge
+from app.gateway.deps import get_checkpointer, get_run_event_store, get_run_manager, get_run_store, get_stream_bridge
 from app.gateway.services import sse_consumer, start_run
 from deerflow.runtime import RunRecord, serialize_channel_values
 
@@ -53,6 +53,7 @@ class RunCreateRequest(BaseModel):
     after_seconds: float | None = Field(default=None, description="Delayed execution")
     if_not_exists: Literal["reject", "create"] = Field(default="create", description="Thread creation policy")
     feedback_keys: list[str] | None = Field(default=None, description="LangSmith feedback keys")
+    follow_up_to_run_id: str | None = Field(default=None, description="Run ID this message follows up on. Auto-detected from latest successful run if not provided.")
 
 
 class RunResponse(BaseModel):
@@ -265,3 +266,50 @@ async def stream_existing_run(
             "X-Accel-Buffering": "no",
         },
     )
+
+
+# ---------------------------------------------------------------------------
+# Messages / Events / Token usage endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.get("/{thread_id}/messages")
+async def list_thread_messages(
+    thread_id: str,
+    request: Request,
+    limit: int = Query(default=50, le=200),
+    before_seq: int | None = Query(default=None),
+    after_seq: int | None = Query(default=None),
+) -> list[dict]:
+    """Return displayable messages for a thread (across all runs)."""
+    event_store = get_run_event_store(request)
+    return await event_store.list_messages(thread_id, limit=limit, before_seq=before_seq, after_seq=after_seq)
+
+
+@router.get("/{thread_id}/runs/{run_id}/messages")
+async def list_run_messages(thread_id: str, run_id: str, request: Request) -> list[dict]:
+    """Return displayable messages for a specific run."""
+    event_store = get_run_event_store(request)
+    return await event_store.list_messages_by_run(thread_id, run_id)
+
+
+@router.get("/{thread_id}/runs/{run_id}/events")
+async def list_run_events(
+    thread_id: str,
+    run_id: str,
+    request: Request,
+    event_types: str | None = Query(default=None),
+    limit: int = Query(default=500, le=2000),
+) -> list[dict]:
+    """Return the full event stream for a run (debug/audit)."""
+    event_store = get_run_event_store(request)
+    types = event_types.split(",") if event_types else None
+    return await event_store.list_events(thread_id, run_id, event_types=types, limit=limit)
+
+
+@router.get("/{thread_id}/token-usage")
+async def thread_token_usage(thread_id: str, request: Request) -> dict:
+    """Thread-level token usage aggregation."""
+    run_store = get_run_store(request)
+    agg = await run_store.aggregate_tokens_by_thread(thread_id)
+    return {"thread_id": thread_id, **agg}

backend/app/gateway/routers/threads.py

@@ -20,17 +20,11 @@ from typing import Any
 from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel, Field
 
-from app.gateway.deps import get_checkpointer, get_store
+from app.gateway.deps import get_checkpointer
+from app.gateway.utils import sanitize_log_param
 from deerflow.config.paths import Paths, get_paths
 from deerflow.runtime import serialize_channel_values
 
-# ---------------------------------------------------------------------------
-# Store namespace
-# ---------------------------------------------------------------------------
-
-THREADS_NS: tuple[str, ...] = ("threads",)
-"""Namespace used by the Store for thread metadata records."""
-
 logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api/threads", tags=["threads"])
 
@@ -63,6 +57,7 @@ class ThreadCreateRequest(BaseModel):
     """Request body for creating a thread."""
 
     thread_id: str | None = Field(default=None, description="Optional thread ID (auto-generated if omitted)")
+    assistant_id: str | None = Field(default=None, description="Associate thread with an assistant")
     metadata: dict[str, Any] = Field(default_factory=dict, description="Initial metadata")
 
 
@@ -135,61 +130,16 @@ def _delete_thread_data(thread_id: str, paths: Paths | None = None) -> ThreadDel
         raise HTTPException(status_code=422, detail=str(exc)) from exc
     except FileNotFoundError:
         # Not critical — thread data may not exist on disk
-        logger.debug("No local thread data to delete for %s", thread_id)
+        logger.debug("No local thread data to delete for %s", sanitize_log_param(thread_id))
         return ThreadDeleteResponse(success=True, message=f"No local data for {thread_id}")
     except Exception as exc:
-        logger.exception("Failed to delete thread data for %s", thread_id)
+        logger.exception("Failed to delete thread data for %s", sanitize_log_param(thread_id))
         raise HTTPException(status_code=500, detail="Failed to delete local thread data.") from exc
 
-    logger.info("Deleted local thread data for %s", thread_id)
+    logger.info("Deleted local thread data for %s", sanitize_log_param(thread_id))
     return ThreadDeleteResponse(success=True, message=f"Deleted local thread data for {thread_id}")
 
 
-async def _store_get(store, thread_id: str) -> dict | None:
-    """Fetch a thread record from the Store; returns ``None`` if absent."""
-    item = await store.aget(THREADS_NS, thread_id)
-    return item.value if item is not None else None
-
-
-async def _store_put(store, record: dict) -> None:
-    """Write a thread record to the Store."""
-    await store.aput(THREADS_NS, record["thread_id"], record)
-
-
-async def _store_upsert(store, thread_id: str, *, metadata: dict | None = None, values: dict | None = None) -> None:
-    """Create or refresh a thread record in the Store.
-
-    On creation the record is written with ``status="idle"``.  On update only
-    ``updated_at`` (and optionally ``metadata`` / ``values``) are changed so
-    that existing fields are preserved.
-
-    ``values`` carries the agent-state snapshot exposed to the frontend
-    (currently just ``{"title": "..."}``).
-    """
-    now = time.time()
-    existing = await _store_get(store, thread_id)
-    if existing is None:
-        await _store_put(
-            store,
-            {
-                "thread_id": thread_id,
-                "status": "idle",
-                "created_at": now,
-                "updated_at": now,
-                "metadata": metadata or {},
-                "values": values or {},
-            },
-        )
-    else:
-        val = dict(existing)
-        val["updated_at"] = now
-        if metadata:
-            val.setdefault("metadata", {}).update(metadata)
-        if values:
-            val.setdefault("values", {}).update(values)
-        await _store_put(store, val)
-
-
 def _derive_thread_status(checkpoint_tuple) -> str:
     """Derive thread status from checkpoint metadata."""
     if checkpoint_tuple is None:
@@ -219,19 +169,14 @@ async def delete_thread_data(thread_id: str, request: Request) -> ThreadDeleteRe
     """Delete local persisted filesystem data for a thread.
 
     Cleans DeerFlow-managed thread directories, removes checkpoint data,
-    and removes the thread record from the Store.
+    and removes the thread_meta row from the configured ThreadMetaStore
+    (sqlite or memory).
     """
+    from app.gateway.deps import get_thread_meta_repo
+
     # Clean local filesystem
     response = _delete_thread_data(thread_id)
 
-    # Remove from Store (best-effort)
-    store = get_store(request)
-    if store is not None:
-        try:
-            await store.adelete(THREADS_NS, thread_id)
-        except Exception:
-            logger.debug("Could not delete store record for thread %s (not critical)", thread_id)
-
     # Remove checkpoints (best-effort)
     checkpointer = getattr(request.app.state, "checkpointer", None)
     if checkpointer is not None:
@@ -239,7 +184,15 @@ async def delete_thread_data(thread_id: str, request: Request) -> ThreadDeleteRe
             if hasattr(checkpointer, "adelete_thread"):
                 await checkpointer.adelete_thread(thread_id)
         except Exception:
-            logger.debug("Could not delete checkpoints for thread %s (not critical)", thread_id)
+            logger.debug("Could not delete checkpoints for thread %s (not critical)", sanitize_log_param(thread_id))
+
+    # Remove thread_meta row (best-effort) — required for sqlite backend
+    # so the deleted thread no longer appears in /threads/search.
+    try:
+        thread_meta_repo = get_thread_meta_repo(request)
+        await thread_meta_repo.delete(thread_id)
+    except Exception:
+        logger.debug("Could not delete thread_meta for %s (not critical)", sanitize_log_param(thread_id))
 
     return response
 
@@ -248,43 +201,38 @@ async def delete_thread_data(thread_id: str, request: Request) -> ThreadDeleteRe
 async def create_thread(body: ThreadCreateRequest, request: Request) -> ThreadResponse:
     """Create a new thread.
 
-    The thread record is written to the Store (for fast listing) and an
-    empty checkpoint is written to the checkpointer (for state reads).
+    Writes a thread_meta record (so the thread appears in /threads/search)
+    and an empty checkpoint (so state endpoints work immediately).
     Idempotent: returns the existing record when ``thread_id`` already exists.
     """
-    store = get_store(request)
+    from app.gateway.deps import get_thread_meta_repo
+
     checkpointer = get_checkpointer(request)
+    thread_meta_repo = get_thread_meta_repo(request)
     thread_id = body.thread_id or str(uuid.uuid4())
     now = time.time()
 
-    # Idempotency: return existing record from Store when already present
-    if store is not None:
-        existing_record = await _store_get(store, thread_id)
-        if existing_record is not None:
-            return ThreadResponse(
-                thread_id=thread_id,
-                status=existing_record.get("status", "idle"),
-                created_at=str(existing_record.get("created_at", "")),
-                updated_at=str(existing_record.get("updated_at", "")),
-                metadata=existing_record.get("metadata", {}),
-            )
+    # Idempotency: return existing record when already present
+    existing_record = await thread_meta_repo.get(thread_id)
+    if existing_record is not None:
+        return ThreadResponse(
+            thread_id=thread_id,
+            status=existing_record.get("status", "idle"),
+            created_at=str(existing_record.get("created_at", "")),
+            updated_at=str(existing_record.get("updated_at", "")),
+            metadata=existing_record.get("metadata", {}),
+        )
 
-    # Write thread record to Store
-    if store is not None:
-        try:
-            await _store_put(
-                store,
-                {
-                    "thread_id": thread_id,
-                    "status": "idle",
-                    "created_at": now,
-                    "updated_at": now,
-                    "metadata": body.metadata,
-                },
-            )
-        except Exception:
-            logger.exception("Failed to write thread %s to store", thread_id)
-            raise HTTPException(status_code=500, detail="Failed to create thread")
+    # Write thread_meta so the thread appears in /threads/search immediately
+    try:
+        await thread_meta_repo.create(
+            thread_id,
+            assistant_id=getattr(body, "assistant_id", None),
+            metadata=body.metadata,
+        )
+    except Exception:
+        logger.exception("Failed to write thread_meta for %s", sanitize_log_param(thread_id))
+        raise HTTPException(status_code=500, detail="Failed to create thread")
 
     # Write an empty checkpoint so state endpoints work immediately
     config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
@@ -301,10 +249,10 @@ async def create_thread(body: ThreadCreateRequest, request: Request) -> ThreadRe
         }
         await checkpointer.aput(config, empty_checkpoint(), ckpt_metadata, {})
     except Exception:
-        logger.exception("Failed to create checkpoint for thread %s", thread_id)
+        logger.exception("Failed to create checkpoint for thread %s", sanitize_log_param(thread_id))
         raise HTTPException(status_code=500, detail="Failed to create thread")
 
-    logger.info("Thread created: %s", thread_id)
+    logger.info("Thread created: %s", sanitize_log_param(thread_id))
     return ThreadResponse(
         thread_id=thread_id,
         status="idle",
@@ -318,135 +266,56 @@ async def create_thread(body: ThreadCreateRequest, request: Request) -> ThreadRe
 async def search_threads(body: ThreadSearchRequest, request: Request) -> list[ThreadResponse]:
     """Search and list threads.
 
-    Two-phase approach:
-
-    **Phase 1 — Store (fast path, O(threads))**: returns threads that were
-    created or run through this Gateway.  Store records are tiny metadata
-    dicts so fetching all of them at once is cheap.
-
-    **Phase 2 — Checkpointer supplement (lazy migration)**: threads that
-    were created directly by LangGraph Server (and therefore absent from the
-    Store) are discovered here by iterating the shared checkpointer.  Any
-    newly found thread is immediately written to the Store so that the next
-    search skips Phase 2 for that thread — the Store converges to a full
-    index over time without a one-shot migration job.
+    Delegates to the configured ThreadMetaStore implementation
+    (SQL-backed for sqlite/postgres, Store-backed for memory mode).
     """
-    store = get_store(request)
-    checkpointer = get_checkpointer(request)
+    from app.gateway.deps import get_thread_meta_repo
 
-    # -----------------------------------------------------------------------
-    # Phase 1: Store
-    # -----------------------------------------------------------------------
-    merged: dict[str, ThreadResponse] = {}
-
-    if store is not None:
-        try:
-            items = await store.asearch(THREADS_NS, limit=10_000)
-        except Exception:
-            logger.warning("Store search failed — falling back to checkpointer only", exc_info=True)
-            items = []
-
-        for item in items:
-            val = item.value
-            merged[val["thread_id"]] = ThreadResponse(
-                thread_id=val["thread_id"],
-                status=val.get("status", "idle"),
-                created_at=str(val.get("created_at", "")),
-                updated_at=str(val.get("updated_at", "")),
-                metadata=val.get("metadata", {}),
-                values=val.get("values", {}),
-            )
-
-    # -----------------------------------------------------------------------
-    # Phase 2: Checkpointer supplement
-    # Discovers threads not yet in the Store (e.g. created by LangGraph
-    # Server) and lazily migrates them so future searches skip this phase.
-    # -----------------------------------------------------------------------
-    try:
-        async for checkpoint_tuple in checkpointer.alist(None):
-            cfg = getattr(checkpoint_tuple, "config", {})
-            thread_id = cfg.get("configurable", {}).get("thread_id")
-            if not thread_id or thread_id in merged:
-                continue
-
-            # Skip sub-graph checkpoints (checkpoint_ns is non-empty for those)
-            if cfg.get("configurable", {}).get("checkpoint_ns", ""):
-                continue
-
-            ckpt_meta = getattr(checkpoint_tuple, "metadata", {}) or {}
-            # Strip LangGraph internal keys from the user-visible metadata dict
-            user_meta = {k: v for k, v in ckpt_meta.items() if k not in ("created_at", "updated_at", "step", "source", "writes", "parents")}
-
-            # Extract state values (title) from the checkpoint's channel_values
-            checkpoint_data = getattr(checkpoint_tuple, "checkpoint", {}) or {}
-            channel_values = checkpoint_data.get("channel_values", {})
-            ckpt_values = {}
-            if title := channel_values.get("title"):
-                ckpt_values["title"] = title
-
-            thread_resp = ThreadResponse(
-                thread_id=thread_id,
-                status=_derive_thread_status(checkpoint_tuple),
-                created_at=str(ckpt_meta.get("created_at", "")),
-                updated_at=str(ckpt_meta.get("updated_at", ckpt_meta.get("created_at", ""))),
-                metadata=user_meta,
-                values=ckpt_values,
-            )
-            merged[thread_id] = thread_resp
-
-            # Lazy migration — write to Store so the next search finds it there
-            if store is not None:
-                try:
-                    await _store_upsert(store, thread_id, metadata=user_meta, values=ckpt_values or None)
-                except Exception:
-                    logger.debug("Failed to migrate thread %s to store (non-fatal)", thread_id)
-    except Exception:
-        logger.exception("Checkpointer scan failed during thread search")
-        # Don't raise — return whatever was collected from Store + partial scan
-
-    # -----------------------------------------------------------------------
-    # Phase 3: Filter → sort → paginate
-    # -----------------------------------------------------------------------
-    results = list(merged.values())
-
-    if body.metadata:
-        results = [r for r in results if all(r.metadata.get(k) == v for k, v in body.metadata.items())]
-
-    if body.status:
-        results = [r for r in results if r.status == body.status]
-
-    results.sort(key=lambda r: r.updated_at, reverse=True)
-    return results[body.offset : body.offset + body.limit]
+    repo = get_thread_meta_repo(request)
+    rows = await repo.search(
+        metadata=body.metadata or None,
+        status=body.status,
+        limit=body.limit,
+        offset=body.offset,
+    )
+    return [
+        ThreadResponse(
+            thread_id=r["thread_id"],
+            status=r.get("status", "idle"),
+            created_at=r.get("created_at", ""),
+            updated_at=r.get("updated_at", ""),
+            metadata=r.get("metadata", {}),
+            values={"title": r["display_name"]} if r.get("display_name") else {},
+            interrupts={},
+        )
+        for r in rows
+    ]
 
 
 @router.patch("/{thread_id}", response_model=ThreadResponse)
 async def patch_thread(thread_id: str, body: ThreadPatchRequest, request: Request) -> ThreadResponse:
     """Merge metadata into a thread record."""
-    store = get_store(request)
-    if store is None:
-        raise HTTPException(status_code=503, detail="Store not available")
+    from app.gateway.deps import get_thread_meta_repo
 
-    record = await _store_get(store, thread_id)
+    thread_meta_repo = get_thread_meta_repo(request)
+    record = await thread_meta_repo.get(thread_id)
     if record is None:
         raise HTTPException(status_code=404, detail=f"Thread {thread_id} not found")
 
-    now = time.time()
-    updated = dict(record)
-    updated.setdefault("metadata", {}).update(body.metadata)
-    updated["updated_at"] = now
-
     try:
-        await _store_put(store, updated)
+        await thread_meta_repo.update_metadata(thread_id, body.metadata)
     except Exception:
-        logger.exception("Failed to patch thread %s", thread_id)
+        logger.exception("Failed to patch thread %s", sanitize_log_param(thread_id))
         raise HTTPException(status_code=500, detail="Failed to update thread")
 
+    # Re-read to get the merged metadata + refreshed updated_at
+    record = await thread_meta_repo.get(thread_id) or record
     return ThreadResponse(
         thread_id=thread_id,
-        status=updated.get("status", "idle"),
-        created_at=str(updated.get("created_at", "")),
-        updated_at=str(now),
-        metadata=updated.get("metadata", {}),
+        status=record.get("status", "idle"),
+        created_at=str(record.get("created_at", "")),
+        updated_at=str(record.get("updated_at", "")),
+        metadata=record.get("metadata", {}),
     )
 
 
@@ -454,30 +323,31 @@ async def patch_thread(thread_id: str, body: ThreadPatchRequest, request: Reques
 async def get_thread(thread_id: str, request: Request) -> ThreadResponse:
     """Get thread info.
 
-    Reads metadata from the Store and derives the accurate execution
-    status from the checkpointer.  Falls back to the checkpointer alone
-    for threads that pre-date Store adoption (backward compat).
+    Reads metadata from the ThreadMetaStore and derives the accurate
+    execution status from the checkpointer.  Falls back to the checkpointer
+    alone for threads that pre-date ThreadMetaStore adoption (backward compat).
     """
-    store = get_store(request)
+    from app.gateway.deps import get_thread_meta_repo
+
+    thread_meta_repo = get_thread_meta_repo(request)
     checkpointer = get_checkpointer(request)
 
-    record: dict | None = None
-    if store is not None:
-        record = await _store_get(store, thread_id)
+    record: dict | None = await thread_meta_repo.get(thread_id)
 
     # Derive accurate status from the checkpointer
     config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
     try:
         checkpoint_tuple = await checkpointer.aget_tuple(config)
     except Exception:
-        logger.exception("Failed to get checkpoint for thread %s", thread_id)
+        logger.exception("Failed to get checkpoint for thread %s", sanitize_log_param(thread_id))
         raise HTTPException(status_code=500, detail="Failed to get thread")
 
     if record is None and checkpoint_tuple is None:
         raise HTTPException(status_code=404, detail=f"Thread {thread_id} not found")
 
-    # If the thread exists in the checkpointer but not the store (e.g. legacy
-    # data), synthesize a minimal store record from the checkpoint metadata.
+    # If the thread exists in the checkpointer but not in thread_meta (e.g.
+    # legacy data created before thread_meta adoption), synthesize a minimal
+    # record from the checkpoint metadata.
     if record is None and checkpoint_tuple is not None:
         ckpt_meta = getattr(checkpoint_tuple, "metadata", {}) or {}
         record = {
@@ -518,7 +388,7 @@ async def get_thread_state(thread_id: str, request: Request) -> ThreadStateRespo
     try:
         checkpoint_tuple = await checkpointer.aget_tuple(config)
     except Exception:
-        logger.exception("Failed to get state for thread %s", thread_id)
+        logger.exception("Failed to get state for thread %s", sanitize_log_param(thread_id))
         raise HTTPException(status_code=500, detail="Failed to get thread state")
 
     if checkpoint_tuple is None:
@@ -559,11 +429,14 @@ async def update_thread_state(thread_id: str, body: ThreadStateUpdateRequest, re
     """Update thread state (e.g. for human-in-the-loop resume or title rename).
 
     Writes a new checkpoint that merges *body.values* into the latest
-    channel values, then syncs any updated ``title`` field back to the Store
-    so that ``/threads/search`` reflects the change immediately.
+    channel values, then syncs any updated ``title`` field through the
+    ThreadMetaStore abstraction so that ``/threads/search`` reflects the
+    change immediately in both sqlite and memory backends.
     """
+    from app.gateway.deps import get_thread_meta_repo
+
     checkpointer = get_checkpointer(request)
-    store = get_store(request)
+    thread_meta_repo = get_thread_meta_repo(request)
 
     # checkpoint_ns must be present in the config for aput — default to ""
     # (the root graph namespace).  checkpoint_id is optional; omitting it
@@ -580,7 +453,7 @@ async def update_thread_state(thread_id: str, body: ThreadStateUpdateRequest, re
     try:
         checkpoint_tuple = await checkpointer.aget_tuple(read_config)
     except Exception:
-        logger.exception("Failed to get state for thread %s", thread_id)
+        logger.exception("Failed to get state for thread %s", sanitize_log_param(thread_id))
         raise HTTPException(status_code=500, detail="Failed to get thread state")
 
     if checkpoint_tuple is None:
@@ -614,19 +487,22 @@ async def update_thread_state(thread_id: str, body: ThreadStateUpdateRequest, re
     try:
         new_config = await checkpointer.aput(write_config, checkpoint, metadata, {})
     except Exception:
-        logger.exception("Failed to update state for thread %s", thread_id)
+        logger.exception("Failed to update state for thread %s", sanitize_log_param(thread_id))
         raise HTTPException(status_code=500, detail="Failed to update thread state")
 
     new_checkpoint_id: str | None = None
     if isinstance(new_config, dict):
         new_checkpoint_id = new_config.get("configurable", {}).get("checkpoint_id")
 
-    # Sync title changes to the Store so /threads/search reflects them immediately.
-    if store is not None and body.values and "title" in body.values:
-        try:
-            await _store_upsert(store, thread_id, values={"title": body.values["title"]})
-        except Exception:
-            logger.debug("Failed to sync title to store for thread %s (non-fatal)", thread_id)
+    # Sync title changes through the ThreadMetaStore abstraction so /threads/search
+    # reflects them immediately in both sqlite and memory backends.
+    if body.values and "title" in body.values:
+        new_title = body.values["title"]
+        if new_title:  # Skip empty strings and None
+            try:
+                await thread_meta_repo.update_display_name(thread_id, new_title)
+            except Exception:
+                logger.debug("Failed to sync title to thread_meta for %s (non-fatal)", sanitize_log_param(thread_id))
 
     return ThreadStateResponse(
         values=serialize_channel_values(channel_values),
@@ -639,7 +515,14 @@ async def update_thread_state(thread_id: str, body: ThreadStateUpdateRequest, re
 
 @router.post("/{thread_id}/history", response_model=list[HistoryEntry])
 async def get_thread_history(thread_id: str, body: ThreadHistoryRequest, request: Request) -> list[HistoryEntry]:
-    """Get checkpoint history for a thread."""
+    """Get checkpoint history for a thread.
+
+    Messages are read from the checkpointer's channel values (the
+    authoritative source) and serialized via
+    :func:`~deerflow.runtime.serialization.serialize_channel_values`.
+    Only the latest (first) checkpoint carries the ``messages`` key to
+    avoid duplicating them across every entry.
+    """
     checkpointer = get_checkpointer(request)
 
     config: dict[str, Any] = {"configurable": {"thread_id": thread_id}}
@@ -647,6 +530,7 @@ async def get_thread_history(thread_id: str, body: ThreadHistoryRequest, request
         config["configurable"]["checkpoint_id"] = body.before
 
     entries: list[HistoryEntry] = []
+    is_latest_checkpoint = True
     try:
         async for checkpoint_tuple in checkpointer.alist(config, limit=body.limit):
             ckpt_config = getattr(checkpoint_tuple, "config", {})
@@ -661,22 +545,42 @@ async def get_thread_history(thread_id: str, body: ThreadHistoryRequest, request
 
             channel_values = checkpoint.get("channel_values", {})
 
+            # Build values from checkpoint channel_values
+            values: dict[str, Any] = {}
+            if title := channel_values.get("title"):
+                values["title"] = title
+            if thread_data := channel_values.get("thread_data"):
+                values["thread_data"] = thread_data
+
+            # Attach messages from checkpointer only for the latest checkpoint
+            if is_latest_checkpoint:
+                messages = channel_values.get("messages")
+                if messages:
+                    values["messages"] = serialize_channel_values({"messages": messages}).get("messages", [])
+            is_latest_checkpoint = False
+
             # Derive next tasks
             tasks_raw = getattr(checkpoint_tuple, "tasks", []) or []
             next_tasks = [t.name for t in tasks_raw if hasattr(t, "name")]
 
+            # Strip LangGraph internal keys from metadata
+            user_meta = {k: v for k, v in metadata.items() if k not in ("created_at", "updated_at", "step", "source", "writes", "parents")}
+            # Keep step for ordering context
+            if "step" in metadata:
+                user_meta["step"] = metadata["step"]
+
             entries.append(
                 HistoryEntry(
                     checkpoint_id=checkpoint_id,
                     parent_checkpoint_id=parent_id,
-                    metadata=metadata,
-                    values=serialize_channel_values(channel_values),
+                    metadata=user_meta,
+                    values=values,
                     created_at=str(metadata.get("created_at", "")),
                     next=next_tasks,
                 )
             )
     except Exception:
-        logger.exception("Failed to get history for thread %s", thread_id)
+        logger.exception("Failed to get history for thread %s", sanitize_log_param(thread_id))
         raise HTTPException(status_code=500, detail="Failed to get thread history")
 
     return entries

backend/app/gateway/routers/uploads.py

@@ -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 = None
-    if sync_to_sandbox:
-        sandbox_id = sandbox_provider.acquire(thread_id)
-        sandbox = sandbox_provider.get(sandbox_id)
-    auto_convert_documents = _auto_convert_documents_enabled()
+    sandbox_id = sandbox_provider.acquire(thread_id)
+    sandbox = sandbox_provider.get(sandbox_id)
 
     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())
 

backend/app/gateway/services.py

@@ -8,16 +8,17 @@ frames, and consuming stream bridge events.  Router modules
 from __future__ import annotations
 
 import asyncio
+import dataclasses
 import json
 import logging
 import re
-import time
 from typing import Any
 
 from fastapi import HTTPException, Request
 from langchain_core.messages import HumanMessage
 
-from app.gateway.deps import get_checkpointer, get_run_manager, get_store, get_stream_bridge
+from app.gateway.deps import get_run_context, get_run_manager, get_run_store, get_stream_bridge
+from app.gateway.utils import sanitize_log_param
 from deerflow.runtime import (
     END_SENTINEL,
     HEARTBEAT_SENTINEL,
@@ -171,71 +172,6 @@ def build_run_config(
 # ---------------------------------------------------------------------------
 
 
-async def _upsert_thread_in_store(store, thread_id: str, metadata: dict | None) -> None:
-    """Create or refresh the thread record in the Store.
-
-    Called from :func:`start_run` so that threads created via the stateless
-    ``/runs/stream`` endpoint (which never calls ``POST /threads``) still
-    appear in ``/threads/search`` results.
-    """
-    # Deferred import to avoid circular import with the threads router module.
-    from app.gateway.routers.threads import _store_upsert
-
-    try:
-        await _store_upsert(store, thread_id, metadata=metadata)
-    except Exception:
-        logger.warning("Failed to upsert thread %s in store (non-fatal)", thread_id)
-
-
-async def _sync_thread_title_after_run(
-    run_task: asyncio.Task,
-    thread_id: str,
-    checkpointer: Any,
-    store: Any,
-) -> None:
-    """Wait for *run_task* to finish, then persist the generated title to the Store.
-
-    TitleMiddleware writes the generated title to the LangGraph agent state
-    (checkpointer) but the Gateway's Store record is not updated automatically.
-    This coroutine closes that gap by reading the final checkpoint after the
-    run completes and syncing ``values.title`` into the Store record so that
-    subsequent ``/threads/search`` responses include the correct title.
-
-    Runs as a fire-and-forget :func:`asyncio.create_task`; failures are
-    logged at DEBUG level and never propagate.
-    """
-    # Wait for the background run task to complete (any outcome).
-    # asyncio.wait does not propagate task exceptions — it just returns
-    # when the task is done, cancelled, or failed.
-    await asyncio.wait({run_task})
-
-    # Deferred import to avoid circular import with the threads router module.
-    from app.gateway.routers.threads import _store_get, _store_put
-
-    try:
-        ckpt_config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
-        ckpt_tuple = await checkpointer.aget_tuple(ckpt_config)
-        if ckpt_tuple is None:
-            return
-
-        channel_values = ckpt_tuple.checkpoint.get("channel_values", {})
-        title = channel_values.get("title")
-        if not title:
-            return
-
-        existing = await _store_get(store, thread_id)
-        if existing is None:
-            return
-
-        updated = dict(existing)
-        updated.setdefault("values", {})["title"] = title
-        updated["updated_at"] = time.time()
-        await _store_put(store, updated)
-        logger.debug("Synced title %r for thread %s", title, thread_id)
-    except Exception:
-        logger.debug("Failed to sync title for thread %s (non-fatal)", thread_id, exc_info=True)
-
-
 async def start_run(
     body: Any,
     thread_id: str,
@@ -255,11 +191,25 @@ async def start_run(
     """
     bridge = get_stream_bridge(request)
     run_mgr = get_run_manager(request)
-    checkpointer = get_checkpointer(request)
-    store = get_store(request)
+    run_ctx = get_run_context(request)
 
     disconnect = DisconnectMode.cancel if body.on_disconnect == "cancel" else DisconnectMode.continue_
 
+    # Resolve follow_up_to_run_id: explicit from request, or auto-detect from latest successful run
+    follow_up_to_run_id = getattr(body, "follow_up_to_run_id", None)
+    if follow_up_to_run_id is None:
+        run_store = get_run_store(request)
+        try:
+            recent_runs = await run_store.list_by_thread(thread_id, limit=1)
+            if recent_runs and recent_runs[0].get("status") == "success":
+                follow_up_to_run_id = recent_runs[0]["run_id"]
+        except Exception:
+            pass  # Don't block run creation
+
+    # Enrich base context with per-run field
+    if follow_up_to_run_id:
+        run_ctx = dataclasses.replace(run_ctx, follow_up_to_run_id=follow_up_to_run_id)
+
     try:
         record = await run_mgr.create_or_reject(
             thread_id,
@@ -268,17 +218,28 @@ async def start_run(
             metadata=body.metadata or {},
             kwargs={"input": body.input, "config": body.config},
             multitask_strategy=body.multitask_strategy,
+            follow_up_to_run_id=follow_up_to_run_id,
         )
     except ConflictError as exc:
         raise HTTPException(status_code=409, detail=str(exc)) from exc
     except UnsupportedStrategyError as exc:
         raise HTTPException(status_code=501, detail=str(exc)) from exc
 
-    # Ensure the thread is visible in /threads/search, even for threads that
-    # were never explicitly created via POST /threads (e.g. stateless runs).
-    store = get_store(request)
-    if store is not None:
-        await _upsert_thread_in_store(store, thread_id, body.metadata)
+    # Upsert thread metadata so the thread appears in /threads/search,
+    # even for threads that were never explicitly created via POST /threads
+    # (e.g. stateless runs).
+    try:
+        existing = await run_ctx.thread_meta_repo.get(thread_id)
+        if existing is None:
+            await run_ctx.thread_meta_repo.create(
+                thread_id,
+                assistant_id=body.assistant_id,
+                metadata=body.metadata,
+            )
+        else:
+            await run_ctx.thread_meta_repo.update_status(thread_id, "running")
+    except Exception:
+        logger.warning("Failed to upsert thread_meta for %s (non-fatal)", sanitize_log_param(thread_id))
 
     agent_factory = resolve_agent_factory(body.assistant_id)
     graph_input = normalize_input(body.input)
@@ -298,8 +259,6 @@ async def start_run(
             "is_plan_mode",
             "subagent_enabled",
             "max_concurrent_subagents",
-            "agent_name",
-            "is_bootstrap",
         }
         configurable = config.setdefault("configurable", {})
         for key in _CONTEXT_CONFIGURABLE_KEYS:
@@ -313,8 +272,7 @@ async def start_run(
             bridge,
             run_mgr,
             record,
-            checkpointer=checkpointer,
-            store=store,
+            ctx=run_ctx,
             agent_factory=agent_factory,
             graph_input=graph_input,
             config=config,
@@ -326,11 +284,9 @@ async def start_run(
     )
     record.task = task
 
-    # After the run completes, sync the title generated by TitleMiddleware from
-    # the checkpointer into the Store record so that /threads/search returns the
-    # correct title instead of an empty values dict.
-    if store is not None:
-        asyncio.create_task(_sync_thread_title_after_run(task, thread_id, checkpointer, store))
+    # Title sync is handled by worker.py's finally block which reads the
+    # title from the checkpoint and calls thread_meta_repo.update_display_name
+    # after the run completes.
 
     return record
 

backend/app/gateway/utils.py

@@ -0,0 +1,6 @@
+"""Shared utility helpers for the Gateway layer."""
+
+
+def sanitize_log_param(value: str) -> str:
+    """Strip control characters to prevent log injection."""
+    return value.replace("\n", "").replace("\r", "").replace("\x00", "")

backend/docs/API.md

@@ -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": {
-      "recursion_limit": 100,
-      "configurable": {"model_name": "gpt-4"}
-    }
+    "config": {"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.

backend/docs/CONFIGURATION.md

@@ -192,8 +192,8 @@ tools:
 ```
 
 **Built-in Tools**:
-- `web_search` - Search the web (DuckDuckGo, Tavily, Exa, InfoQuest, Firecrawl)
-- `web_fetch` - Fetch web pages (Jina AI, Exa, InfoQuest, Firecrawl)
+- `web_search` - Search the web (Tavily)
+- `web_fetch` - Fetch web pages (Jina AI)
 - `ls` - List directory contents
 - `read_file` - Read file contents
 - `write_file` - Write file contents

backend/docs/FILE_UPLOAD.md

@@ -2,12 +2,12 @@
 
 ## 概述
 
-DeerFlow 后端提供了完整的文件上传功能，支持多文件上传，并可选地将 Office 文档和 PDF 转换为 Markdown 格式。
+DeerFlow 后端提供了完整的文件上传功能，支持多文件上传，并自动将 Office 文档和 PDF 转换为 Markdown 格式。
 
 ## 功能特性
 
 - ✅ 支持多文件同时上传
-- ✅ 可选地转换文档为 Markdown（PDF、PPT、Excel、Word）
+- ✅ 自动转换文档为 Markdown（PDF、PPT、Excel、Word）
 - ✅ 文件存储在线程隔离的目录中
 - ✅ Agent 自动感知已上传的文件
 - ✅ 支持文件列表查询和删除
@@ -86,7 +86,7 @@ DELETE /api/threads/{thread_id}/uploads/{filename}
 
 ## 支持的文档格式
 
-以下格式在显式启用 `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`
 
 ## 技术实现
 

backend/docs/README.md

@@ -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

backend/docs/STREAMING.md

@@ -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` |

backend/docs/TODO.md

@@ -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)
 

backend/packages/harness/deerflow/agents/__init__.py

@@ -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",

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

@@ -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
@@ -84,23 +83,76 @@ async def _async_checkpointer(config) -> AsyncIterator[Checkpointer]:
 
 
 @contextlib.asynccontextmanager
-async def make_checkpointer() -> AsyncIterator[Checkpointer]:
-    """Async context manager that yields a checkpointer for the caller's lifetime.
-    Resources are opened on enter and closed on exit — no global state::
-
-        async with make_checkpointer() as checkpointer:
-            app.state.checkpointer = checkpointer
-
-    Yields an ``InMemorySaver`` when no checkpointer is configured in *config.yaml*.
-    """
-
-    config = get_app_config()
-
-    if config.checkpointer is None:
+async def _async_checkpointer_from_database(db_config) -> AsyncIterator[Checkpointer]:
+    """Async context manager that constructs a checkpointer from unified DatabaseConfig."""
+    if db_config.backend == "memory":
         from langgraph.checkpoint.memory import InMemorySaver
 
         yield InMemorySaver()
         return
 
-    async with _async_checkpointer(config.checkpointer) as saver:
-        yield saver
+    if db_config.backend == "sqlite":
+        try:
+            from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
+        except ImportError as exc:
+            raise ImportError(SQLITE_INSTALL) from exc
+
+        conn_str = db_config.checkpointer_sqlite_path
+        ensure_sqlite_parent_dir(conn_str)
+        async with AsyncSqliteSaver.from_conn_string(conn_str) as saver:
+            await saver.setup()
+            yield saver
+        return
+
+    if db_config.backend == "postgres":
+        try:
+            from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+        except ImportError as exc:
+            raise ImportError(POSTGRES_INSTALL) from exc
+
+        if not db_config.postgres_url:
+            raise ValueError("database.postgres_url is required for the postgres backend")
+
+        async with AsyncPostgresSaver.from_conn_string(db_config.postgres_url) as saver:
+            await saver.setup()
+            yield saver
+        return
+
+    raise ValueError(f"Unknown database backend: {db_config.backend!r}")
+
+
+@contextlib.asynccontextmanager
+async def make_checkpointer() -> AsyncIterator[Checkpointer]:
+    """Async context manager that yields a checkpointer for the caller's lifetime.
+    Resources are opened on enter and closed on exit -- no global state::
+
+        async with make_checkpointer() as checkpointer:
+            app.state.checkpointer = checkpointer
+
+    Yields an ``InMemorySaver`` when no checkpointer is configured in *config.yaml*.
+
+    Priority:
+    1. Legacy ``checkpointer:`` config section (backward compatible)
+    2. Unified ``database:`` config section
+    3. Default InMemorySaver
+    """
+
+    config = get_app_config()
+
+    # Legacy: standalone checkpointer config takes precedence
+    if config.checkpointer is not None:
+        async with _async_checkpointer(config.checkpointer) as saver:
+            yield saver
+            return
+
+    # Unified database config
+    db_config = getattr(config, "database", None)
+    if db_config is not None and db_config.backend != "memory":
+        async with _async_checkpointer_from_database(db_config) as saver:
+            yield saver
+            return
+
+    # Default: in-memory
+    from langgraph.checkpoint.memory import InMemorySaver
+
+    yield InMemorySaver()

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

@@ -27,7 +27,7 @@ from langgraph.types import Checkpointer
 
 from deerflow.config.app_config import get_app_config
 from deerflow.config.checkpointer_config import CheckpointerConfig
-from deerflow.runtime.store._sqlite_utils import 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)

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

@@ -1,25 +1,22 @@
 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
 
@@ -41,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()
 
@@ -59,13 +56,15 @@ def _create_summarization_middleware() -> DeerFlowSummarizationMiddleware | None
     # Prepare keep parameter
     keep = config.keep.to_tuple()
 
-    # Prepare model parameter
+    # Prepare model parameter.
+    # Bind "middleware:summarize" tag so RunJournal identifies these LLM calls
+    # as middleware rather than lead_agent (SummarizationMiddleware is a
+    # LangChain built-in, so we tag the model at creation time).
     if config.model_name:
         model = create_chat_model(name=config.model_name, thinking_enabled=False)
     else:
-        # Use a lightweight model for summarization to save costs
-        # Falls back to default model if not explicitly specified
         model = create_chat_model(thinking_enabled=False)
+    model = model.with_config(tags=["middleware:summarize"])
 
     # Prepare kwargs
     kwargs = {
@@ -80,11 +79,7 @@ def _create_summarization_middleware() -> DeerFlowSummarizationMiddleware | None
     if config.summary_prompt is not None:
         kwargs["summary_prompt"] = config.summary_prompt
 
-    hooks: list[BeforeSummarizationHook] = []
-    if get_memory_config().enabled:
-        hooks.append(memory_flush_hook)
-
-    return DeerFlowSummarizationMiddleware(**kwargs, before_summarization=hooks)
+    return SummarizationMiddleware(**kwargs)
 
 
 def _create_todo_list_middleware(is_plan_mode: bool) -> TodoMiddleware | None:
@@ -291,17 +286,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
-    agent_model_name = agent_config.model if agent_config and agent_config.model else None
+    # Custom agent model or fallback to global/default model resolution
+    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
-    model_name = _resolve_model_name(requested_model_name or agent_model_name)
+    # Final model name resolution with request override, then agent config, then global default
+    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.")
@@ -332,7 +327,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,
         }
     )
 

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

@@ -1,114 +1,20 @@
-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 []
+    try:
+        return list(load_skills(enabled_only=True))
+    except Exception:
+        logger.exception("Failed to load enabled skills for prompt injection")
+        return []
 
 
 def _skill_mutability_label(category: str) -> str:
@@ -116,36 +22,7 @@ def _skill_mutability_label(category: str) -> str:
 
 
 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:
@@ -417,9 +294,6 @@ 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
-- 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_file` tool
 {acp_section}
 </working_directory>

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

@@ -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

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

@@ -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,7 +18,7 @@ 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
@@ -61,88 +61,48 @@ class MemoryUpdateQueue:
             return
 
         with self._lock:
-            self._enqueue_locked(
+            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=correction_detected,
-                reinforcement_detected=reinforcement_detected,
+                correction_detected=merged_correction_detected,
+                reinforcement_detected=merged_reinforcement_detected,
             )
+
+            # Check if this thread already has a pending update
+            # If so, replace it with the newer one
+            self._queue = [c for c in self._queue if c.thread_id != thread_id]
+            self._queue.append(context)
+
+            # Reset or start the debounce timer
             self._reset_timer()
 
         logger.info("Memory update queued for thread %s, queue size: %d", thread_id, len(self._queue))
 
-    def add_nowait(
-        self,
-        thread_id: str,
-        messages: list[Any],
-        agent_name: str | None = None,
-        correction_detected: bool = False,
-        reinforcement_detected: bool = False,
-    ) -> None:
-        """Add a conversation and start processing immediately in the background."""
-        config = get_memory_config()
-        if not config.enabled:
-            return
-
-        with self._lock:
-            self._enqueue_locked(
-                thread_id=thread_id,
-                messages=messages,
-                agent_name=agent_name,
-                correction_detected=correction_detected,
-                reinforcement_detected=reinforcement_detected,
-            )
-            self._schedule_timer(0)
-
-        logger.info("Memory update queued for immediate processing on thread %s, queue size: %d", thread_id, len(self._queue))
-
-    def _enqueue_locked(
-        self,
-        *,
-        thread_id: str,
-        messages: list[Any],
-        agent_name: str | None,
-        correction_detected: bool,
-        reinforcement_detected: bool,
-    ) -> None:
-        existing_context = next(
-            (context for context in self._queue if context.thread_id == thread_id),
-            None,
-        )
-        merged_correction_detected = correction_detected or (existing_context.correction_detected if existing_context is not None else False)
-        merged_reinforcement_detected = reinforcement_detected or (existing_context.reinforcement_detected if existing_context is not None else False)
-        context = ConversationContext(
-            thread_id=thread_id,
-            messages=messages,
-            agent_name=agent_name,
-            correction_detected=merged_correction_detected,
-            reinforcement_detected=merged_reinforcement_detected,
-        )
-
-        self._queue = [c for c in self._queue if c.thread_id != thread_id]
-        self._queue.append(context)
-
     def _reset_timer(self) -> None:
         """Reset the debounce timer."""
         config = get_memory_config()
-        self._schedule_timer(config.debounce_seconds)
 
-        logger.debug("Memory update timer set for %ss", config.debounce_seconds)
-
-    def _schedule_timer(self, delay_seconds: float) -> None:
-        """Schedule queue processing after the provided delay."""
         # Cancel existing timer if any
         if self._timer is not None:
             self._timer.cancel()
 
+        # Start new timer
         self._timer = threading.Timer(
-            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 +110,8 @@ class MemoryUpdateQueue:
 
         with self._lock:
             if self._processing:
-                # Preserve immediate flush semantics even if another worker is active.
-                self._schedule_timer(0)
+                # Already processing, reschedule
+                self._reset_timer()
                 return
 
             if not self._queue:
@@ -204,13 +164,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.
 

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

@@ -4,8 +4,7 @@ import abc
 import json
 import logging
 import threading
-import uuid
-from datetime import UTC, datetime
+from datetime import 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)
-            if cached is not None and cached[1] == current_mtime:
-                return cached[0]
+        cached = self._memory_cache.get(agent_name)
 
-        memory_data = self._load_memory_from_file(agent_name)
-
-        with self._cache_lock:
+        if cached is None or cached[1] != current_mtime:
+            memory_data = self._load_memory_from_file(agent_name)
             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
-            # 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()}
+            memory_data["lastUpdated"] = datetime.utcnow().isoformat() + "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:

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

@@ -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,
-    )

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

@@ -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 (
-    create_empty_memory,
-    get_memory_storage,
-    utc_now_iso_z,
-)
+from deerflow.agents.memory.storage import create_empty_memory, get_memory_storage
 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".
@@ -313,117 +266,6 @@ class MemoryUpdater:
         model_name = self._model_name or config.model_name
         return create_chat_model(name=model_name, thinking_enabled=False)
 
-    def _build_correction_hint(
-        self,
-        correction_detected: bool,
-        reinforcement_detected: bool,
-    ) -> str:
-        """Build optional prompt hints for correction and reinforcement signals."""
-        correction_hint = ""
-        if correction_detected:
-            correction_hint = (
-                "IMPORTANT: Explicit correction signals were detected in this conversation. "
-                "Pay special attention to what the agent got wrong, what the user corrected, "
-                "and record the correct approach as a fact with category "
-                '"correction" and confidence >= 0.95 when appropriate.'
-            )
-        if reinforcement_detected:
-            reinforcement_hint = (
-                "IMPORTANT: Positive reinforcement signals were detected in this conversation. "
-                "The user explicitly confirmed the agent's approach was correct or helpful. "
-                "Record the confirmed approach, style, or preference as a fact with category "
-                '"preference" or "behavior" and confidence >= 0.9 when appropriate.'
-            )
-            correction_hint = (correction_hint + "\n" + reinforcement_hint).strip() if correction_hint else reinforcement_hint
-
-        return correction_hint
-
-    def _prepare_update_prompt(
-        self,
-        messages: list[Any],
-        agent_name: str | None,
-        correction_detected: bool,
-        reinforcement_detected: bool,
-    ) -> tuple[dict[str, Any], str] | None:
-        """Load memory and build the update prompt for a conversation."""
-        config = get_memory_config()
-        if not config.enabled or not messages:
-            return None
-
-        current_memory = get_memory_data(agent_name)
-        conversation_text = format_conversation_for_update(messages)
-        if not conversation_text.strip():
-            return None
-
-        correction_hint = self._build_correction_hint(
-            correction_detected=correction_detected,
-            reinforcement_detected=reinforcement_detected,
-        )
-        prompt = MEMORY_UPDATE_PROMPT.format(
-            current_memory=json.dumps(current_memory, indent=2),
-            conversation=conversation_text,
-            correction_hint=correction_hint,
-        )
-        return current_memory, prompt
-
-    def _finalize_update(
-        self,
-        current_memory: dict[str, Any],
-        response_content: Any,
-        thread_id: str | None,
-        agent_name: str | None,
-    ) -> bool:
-        """Parse the model response, apply updates, and persist memory."""
-        response_text = _extract_text(response_content).strip()
-
-        if response_text.startswith("```"):
-            lines = response_text.split("\n")
-            response_text = "\n".join(lines[1:-1] if lines[-1] == "```" else lines[1:])
-
-        update_data = json.loads(response_text)
-        # Deep-copy before in-place mutation so a subsequent save() failure
-        # cannot corrupt the still-cached original object reference.
-        updated_memory = self._apply_updates(copy.deepcopy(current_memory), update_data, thread_id)
-        updated_memory = _strip_upload_mentions_from_memory(updated_memory)
-        return get_memory_storage().save(updated_memory, agent_name)
-
-    async def aupdate_memory(
-        self,
-        messages: list[Any],
-        thread_id: str | None = None,
-        agent_name: str | None = None,
-        correction_detected: bool = False,
-        reinforcement_detected: bool = False,
-    ) -> bool:
-        """Update memory asynchronously based on conversation messages."""
-        try:
-            prepared = await asyncio.to_thread(
-                self._prepare_update_prompt,
-                messages=messages,
-                agent_name=agent_name,
-                correction_detected=correction_detected,
-                reinforcement_detected=reinforcement_detected,
-            )
-            if prepared is None:
-                return False
-
-            current_memory, prompt = prepared
-            model = self._get_model()
-            response = await model.ainvoke(prompt)
-            return await asyncio.to_thread(
-                self._finalize_update,
-                current_memory=current_memory,
-                response_content=response.content,
-                thread_id=thread_id,
-                agent_name=agent_name,
-            )
-        except json.JSONDecodeError as e:
-            logger.warning("Failed to parse LLM response for memory update: %s", e)
-            return False
-        except Exception as e:
-            logger.exception("Memory update failed: %s", e)
-            return False
-
     def update_memory(
         self,
         messages: list[Any],
@@ -432,7 +274,7 @@ class MemoryUpdater:
         correction_detected: bool = False,
         reinforcement_detected: bool = False,
     ) -> bool:
-        """Synchronously update memory via the async updater path.
+        """Update memory based on conversation messages.
 
         Args:
             messages: List of conversation messages.
@@ -444,15 +286,78 @@ class MemoryUpdater:
         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,
+        config = get_memory_config()
+        if not config.enabled:
+            return False
+
+        if not messages:
+            return False
+
+        try:
+            # Get current memory
+            current_memory = get_memory_data(agent_name)
+
+            # Format conversation for prompt
+            conversation_text = format_conversation_for_update(messages)
+
+            if not conversation_text.strip():
+                return False
+
+            # Build prompt
+            correction_hint = ""
+            if correction_detected:
+                correction_hint = (
+                    "IMPORTANT: Explicit correction signals were detected in this conversation. "
+                    "Pay special attention to what the agent got wrong, what the user corrected, "
+                    "and record the correct approach as a fact with category "
+                    '"correction" and confidence >= 0.95 when appropriate.'
+                )
+            if reinforcement_detected:
+                reinforcement_hint = (
+                    "IMPORTANT: Positive reinforcement signals were detected in this conversation. "
+                    "The user explicitly confirmed the agent's approach was correct or helpful. "
+                    "Record the confirmed approach, style, or preference as a fact with category "
+                    '"preference" or "behavior" and confidence >= 0.9 when appropriate.'
+                )
+                correction_hint = (correction_hint + "\n" + reinforcement_hint).strip() if correction_hint else reinforcement_hint
+
+            prompt = MEMORY_UPDATE_PROMPT.format(
+                current_memory=json.dumps(current_memory, indent=2),
+                conversation=conversation_text,
+                correction_hint=correction_hint,
             )
-        )
+
+            # Call LLM
+            model = self._get_model()
+            response = model.invoke(prompt)
+            response_text = _extract_text(response.content).strip()
+
+            # Parse response
+            # Remove markdown code blocks if present
+            if response_text.startswith("```"):
+                lines = response_text.split("\n")
+                response_text = "\n".join(lines[1:-1] if lines[-1] == "```" else lines[1:])
+
+            update_data = json.loads(response_text)
+
+            # Apply updates
+            updated_memory = self._apply_updates(current_memory, update_data, thread_id)
+
+            # Strip file-upload mentions from all summaries before saving.
+            # Uploaded files are session-scoped and won't exist in future sessions,
+            # so recording upload events in long-term memory causes the agent to
+            # try (and fail) to locate those files in subsequent conversations.
+            updated_memory = _strip_upload_mentions_from_memory(updated_memory)
+
+            # Save
+            return get_memory_storage().save(updated_memory, agent_name)
+
+        except json.JSONDecodeError as e:
+            logger.warning("Failed to parse LLM response for memory update: %s", e)
+            return False
+        except Exception as e:
+            logger.exception("Memory update failed: %s", e)
+            return False
 
     def _apply_updates(
         self,
@@ -471,7 +376,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", {})

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

@@ -1,6 +1,5 @@
 """Middleware for intercepting clarification requests and presenting them to the user."""
 
-import json
 import logging
 from collections.abc import Callable
 from typing import override
@@ -61,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": "❓",

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

@@ -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(

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

@@ -4,7 +4,6 @@ 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
@@ -20,8 +19,6 @@ from langchain.agents.middleware.types import (
 from langchain_core.messages import AIMessage
 from langgraph.errors import GraphBubbleUp
 
-from deerflow.config import get_app_config
-
 logger = logging.getLogger(__name__)
 
 _RETRIABLE_STATUS_CODES = {408, 409, 425, 429, 500, 502, 503, 504}
@@ -70,80 +67,6 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
     retry_base_delay_ms: int = 1000
     retry_cap_delay_ms: int = 8000
 
-    circuit_failure_threshold: int = 5
-    circuit_recovery_timeout_sec: int = 60
-
-    def __init__(self, **kwargs: Any) -> None:
-        super().__init__(**kwargs)
-
-        # Load Circuit Breaker configs from app config if available, fall back to defaults
-        try:
-            app_config = get_app_config()
-            self.circuit_failure_threshold = app_config.circuit_breaker.failure_threshold
-            self.circuit_recovery_timeout_sec = app_config.circuit_breaker.recovery_timeout_sec
-        except (FileNotFoundError, RuntimeError):
-            # Gracefully fall back to class defaults in test environments
-            pass
-
-        # Circuit Breaker state
-        self._circuit_lock = threading.Lock()
-        self._circuit_failure_count = 0
-        self._circuit_open_until = 0.0
-        self._circuit_state = "closed"
-        self._circuit_probe_in_flight = False
-
-    def _check_circuit(self) -> bool:
-        """Returns True if circuit is OPEN (fast fail), False otherwise."""
-        with self._circuit_lock:
-            now = time.time()
-
-            if self._circuit_state == "open":
-                if now < self._circuit_open_until:
-                    return True
-                self._circuit_state = "half_open"
-                self._circuit_probe_in_flight = False
-
-            if self._circuit_state == "half_open":
-                if self._circuit_probe_in_flight:
-                    return True
-                self._circuit_probe_in_flight = True
-                return False
-
-            return False
-
-    def _record_success(self) -> None:
-        with self._circuit_lock:
-            if self._circuit_state != "closed" or self._circuit_failure_count > 0:
-                logger.info("Circuit breaker reset (Closed). LLM service recovered.")
-            self._circuit_failure_count = 0
-            self._circuit_open_until = 0.0
-            self._circuit_state = "closed"
-            self._circuit_probe_in_flight = False
-
-    def _record_failure(self) -> None:
-        with self._circuit_lock:
-            if self._circuit_state == "half_open":
-                self._circuit_open_until = time.time() + self.circuit_recovery_timeout_sec
-                self._circuit_state = "open"
-                self._circuit_probe_in_flight = False
-                logger.error(
-                    "Circuit breaker probe failed (Open). Will probe again after %ds.",
-                    self.circuit_recovery_timeout_sec,
-                )
-                return
-
-            self._circuit_failure_count += 1
-            if self._circuit_failure_count >= self.circuit_failure_threshold:
-                self._circuit_open_until = time.time() + self.circuit_recovery_timeout_sec
-                if self._circuit_state != "open":
-                    self._circuit_state = "open"
-                    self._circuit_probe_in_flight = False
-                    logger.error(
-                        "Circuit breaker tripped (Open). Threshold reached (%d). Will probe after %ds.",
-                        self.circuit_failure_threshold,
-                        self.circuit_recovery_timeout_sec,
-                    )
-
     def _classify_error(self, exc: BaseException) -> tuple[bool, str]:
         detail = _extract_error_detail(exc)
         lowered = detail.lower()
@@ -181,9 +104,6 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
         reason_text = "provider is busy" if reason == "busy" else "provider request failed temporarily"
         return f"LLM request retry {attempt}/{self.retry_max_attempts}: {reason_text}. Retrying in {seconds}s."
 
-    def _build_circuit_breaker_message(self) -> str:
-        return "The configured LLM provider is currently unavailable due to continuous failures. Circuit breaker is engaged to protect the system. Please wait a moment before trying again."
-
     def _build_user_message(self, exc: BaseException, reason: str) -> str:
         detail = _extract_error_detail(exc)
         if reason == "quota":
@@ -218,20 +138,12 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
         request: ModelRequest,
         handler: Callable[[ModelRequest], ModelResponse],
     ) -> ModelCallResult:
-        if self._check_circuit():
-            return AIMessage(content=self._build_circuit_breaker_message())
-
         attempt = 1
         while True:
             try:
-                response = handler(request)
-                self._record_success()
-                return response
+                return handler(request)
             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)
@@ -254,8 +166,6 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
                     _extract_error_detail(exc),
                     exc_info=exc,
                 )
-                if retriable:
-                    self._record_failure()
                 return AIMessage(content=self._build_user_message(exc, reason))
 
     @override
@@ -264,20 +174,12 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
         request: ModelRequest,
         handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
     ) -> ModelCallResult:
-        if self._check_circuit():
-            return AIMessage(content=self._build_circuit_breaker_message())
-
         attempt = 1
         while True:
             try:
-                response = await handler(request)
-                self._record_success()
-                return response
+                return await handler(request)
             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)
@@ -300,8 +202,6 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
                     _extract_error_detail(exc),
                     exc_info=exc,
                 )
-                if retriable:
-                    self._record_failure()
                 return AIMessage(content=self._build_user_message(exc, reason))
 
 

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

@@ -17,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
@@ -32,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.
-    normalized: list[str] = []
+    # First normalize each tool call to a minimal (name, args) structure.
+    normalized: list[dict] = []
     for tc in tool_calls:
-        name = tc.get("name", "")
-        args, fallback_key = _normalize_tool_call_args(tc.get("args", {}))
-        key = _stable_tool_key(name, args, fallback_key)
+        normalized.append(
+            {
+                "name": tc.get("name", ""),
+                "args": tc.get("args", {}),
+            }
+        )
 
-        normalized.append(f"{name}:{key}")
-
-    # Sort so permutations of the same multiset of calls yield the same ordering.
-    normalized.sort()
+    # Sort by both name and a deterministic serialization of args so that
+    # permutations of the same multiset of calls yield the same ordering.
+    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.
@@ -149,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__(
@@ -163,23 +86,16 @@ 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."""
@@ -196,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)
         """
@@ -243,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",
@@ -270,40 +177,8 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
                         },
                     )
                     return _WARNING_MSG, False
-
-            # --- Layer 2: per-tool-type frequency ---
-            freq = self._tool_freq[thread_id]
-            for tc in tool_calls:
-                name = tc.get("name", "")
-                if not name:
-                    continue
-                freq[name] += 1
-                tc_count = freq[name]
-
-                if tc_count >= self.tool_freq_hard_limit:
-                    logger.error(
-                        "Tool frequency hard limit reached — forcing stop",
-                        extra={
-                            "thread_id": thread_id,
-                            "tool_name": name,
-                            "count": tc_count,
-                        },
-                    )
-                    return _TOOL_FREQ_HARD_STOP_MSG.format(tool_name=name, count=tc_count), True
-
-                if tc_count >= self.tool_freq_warn:
-                    warned = self._tool_freq_warned[thread_id]
-                    if name not in warned:
-                        warned.add(name)
-                        logger.warning(
-                            "Tool frequency warning — too many calls to same tool type",
-                            extra={
-                                "thread_id": thread_id,
-                                "tool_name": name,
-                                "count": tc_count,
-                            },
-                        )
-                        return _TOOL_FREQ_WARNING_MSG.format(tool_name=name, count=tc_count), False
+                # Warning already injected for this hash — suppress
+                return None, False
 
         return None, False
 
@@ -324,26 +199,6 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
         # Fallback: coerce unexpected types to str to avoid TypeError
         return str(content) + f"\n\n{text}"
 
-    @staticmethod
-    def _build_hard_stop_update(last_msg, content: str | list) -> dict:
-        """Clear tool-call metadata so forced-stop messages serialize as plain assistant text."""
-        update = {
-            "tool_calls": [],
-            "content": content,
-        }
-
-        additional_kwargs = dict(getattr(last_msg, "additional_kwargs", {}) or {})
-        for key in ("tool_calls", "function_call"):
-            additional_kwargs.pop(key, None)
-        update["additional_kwargs"] = additional_kwargs
-
-        response_metadata = deepcopy(getattr(last_msg, "response_metadata", {}) or {})
-        if response_metadata.get("finish_reason") == "tool_calls":
-            response_metadata["finish_reason"] = "stop"
-        update["response_metadata"] = response_metadata
-
-        return update
-
     def _apply(self, state: AgentState, runtime: Runtime) -> dict | None:
         warning, hard_stop = self._track_and_check(state, runtime)
 
@@ -351,8 +206,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(update=self._build_hard_stop_update(last_msg, content))
+            stripped_msg = last_msg.model_copy(
+                update={
+                    "tool_calls": [],
+                    "content": self._append_text(last_msg.content, _HARD_STOP_MSG),
+                }
+            )
             return {"messages": [stripped_msg]}
 
         if warning:
@@ -380,10 +239,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()

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

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

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

@@ -23,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*$"),
+    re.compile(r"rm\s+-[^\s]*r[^\s]*\s+(/\*?|~/?\*?|/home\b|/root\b)\s*$"),  # rm -rf / /* ~ /home /root
+    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/"),
-    # --- 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
+    re.compile(r">\s*/etc/"),  # overwrite /etc/ files
 ]
 
 _MEDIUM_RISK_PATTERNS: list[re.Pattern[str]] = [
-    re.compile(r"chmod\s+777"),
-    re.compile(r"pip3?\s+install"),
+    re.compile(r"chmod\s+777"),  # overly permissive, but reversible
+    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]:
-    """Split a compound command into sub-commands (quote-aware).
-
-    Scans the raw command string so unquoted shell control operators are
-    recognised even when they are not surrounded by whitespace
-    (e.g. ``safe;rm -rf /`` or ``rm -rf /&&echo ok``). Operators inside
-    quotes are ignored. If the command ends with an unclosed quote or a
-    dangling escape, return the whole command unchanged (fail-closed —
-    safer to classify the unsplit string than silently drop parts).
-    """
-    parts: list[str] = []
-    current: list[str] = []
-    in_single_quote = False
-    in_double_quote = False
-    escaping = False
-    index = 0
-
-    while index < len(command):
-        char = command[index]
-
-        if escaping:
-            current.append(char)
-            escaping = False
-            index += 1
-            continue
-
-        if char == "\\" and not in_single_quote:
-            current.append(char)
-            escaping = True
-            index += 1
-            continue
-
-        if char == "'" and not in_double_quote:
-            in_single_quote = not in_single_quote
-            current.append(char)
-            index += 1
-            continue
-
-        if char == '"' and not in_single_quote:
-            in_double_quote = not in_double_quote
-            current.append(char)
-            index += 1
-            continue
-
-        if not in_single_quote and not in_double_quote:
-            if command.startswith("&&", index) or command.startswith("||", index):
-                part = "".join(current).strip()
-                if part:
-                    parts.append(part)
-                current = []
-                index += 2
-                continue
-            if char == ";":
-                part = "".join(current).strip()
-                if part:
-                    parts.append(part)
-                current = []
-                index += 1
-                continue
-
-        current.append(char)
-        index += 1
-
-    # Unclosed quote or dangling escape → fail-closed, return whole command
-    if in_single_quote or in_double_quote or escaping:
-        return [command]
-
-    part = "".join(current).strip()
-    if part:
-        parts.append(part)
-    return parts if parts else [command]
-
-
-def _classify_single_command(command: str) -> str:
-    """Classify a single (non-compound) command. Return 'block', 'warn', or 'pass'."""
+def _classify_command(command: str) -> str:
+    """Return 'block', 'warn', or 'pass'."""
+    # Normalize for matching (collapse whitespace)
     normalized = " ".join(command.split())
 
     for pattern in _HIGH_RISK_PATTERNS:
@@ -160,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
 # ---------------------------------------------------------------------------

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

@@ -1,151 +0,0 @@
-"""Summarization middleware extensions for DeerFlow."""
-
-from __future__ import annotations
-
-import logging
-from dataclasses import dataclass
-from typing import Protocol, runtime_checkable
-
-from langchain.agents import AgentState
-from langchain.agents.middleware import SummarizationMiddleware
-from langchain_core.messages import AnyMessage, RemoveMessage
-from langgraph.config import get_config
-from langgraph.graph.message import REMOVE_ALL_MESSAGES
-from langgraph.runtime import Runtime
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass(frozen=True)
-class SummarizationEvent:
-    """Context emitted before conversation history is summarized away."""
-
-    messages_to_summarize: tuple[AnyMessage, ...]
-    preserved_messages: tuple[AnyMessage, ...]
-    thread_id: str | None
-    agent_name: str | None
-    runtime: Runtime
-
-
-@runtime_checkable
-class BeforeSummarizationHook(Protocol):
-    """Hook invoked before summarization removes messages from state."""
-
-    def __call__(self, event: SummarizationEvent) -> None: ...
-
-
-def _resolve_thread_id(runtime: Runtime) -> str | None:
-    """Resolve the current thread ID from runtime context or LangGraph config."""
-    thread_id = runtime.context.get("thread_id") if runtime.context else None
-    if thread_id is None:
-        try:
-            config_data = get_config()
-        except RuntimeError:
-            return None
-        thread_id = config_data.get("configurable", {}).get("thread_id")
-    return thread_id
-
-
-def _resolve_agent_name(runtime: Runtime) -> str | None:
-    """Resolve the current agent name from runtime context or LangGraph config."""
-    agent_name = runtime.context.get("agent_name") if runtime.context else None
-    if agent_name is None:
-        try:
-            config_data = get_config()
-        except RuntimeError:
-            return None
-        agent_name = config_data.get("configurable", {}).get("agent_name")
-    return agent_name
-
-
-class DeerFlowSummarizationMiddleware(SummarizationMiddleware):
-    """Summarization middleware with pre-compression hook dispatch."""
-
-    def __init__(
-        self,
-        *args,
-        before_summarization: list[BeforeSummarizationHook] | None = None,
-        **kwargs,
-    ) -> None:
-        super().__init__(*args, **kwargs)
-        self._before_summarization_hooks = before_summarization or []
-
-    def before_model(self, state: AgentState, runtime: Runtime) -> dict | None:
-        return self._maybe_summarize(state, runtime)
-
-    async def abefore_model(self, state: AgentState, runtime: Runtime) -> dict | None:
-        return await self._amaybe_summarize(state, runtime)
-
-    def _maybe_summarize(self, state: AgentState, runtime: Runtime) -> dict | None:
-        messages = state["messages"]
-        self._ensure_message_ids(messages)
-
-        total_tokens = self.token_counter(messages)
-        if not self._should_summarize(messages, total_tokens):
-            return None
-
-        cutoff_index = self._determine_cutoff_index(messages)
-        if cutoff_index <= 0:
-            return None
-
-        messages_to_summarize, preserved_messages = self._partition_messages(messages, cutoff_index)
-        self._fire_hooks(messages_to_summarize, preserved_messages, runtime)
-        summary = self._create_summary(messages_to_summarize)
-        new_messages = self._build_new_messages(summary)
-
-        return {
-            "messages": [
-                RemoveMessage(id=REMOVE_ALL_MESSAGES),
-                *new_messages,
-                *preserved_messages,
-            ]
-        }
-
-    async def _amaybe_summarize(self, state: AgentState, runtime: Runtime) -> dict | None:
-        messages = state["messages"]
-        self._ensure_message_ids(messages)
-
-        total_tokens = self.token_counter(messages)
-        if not self._should_summarize(messages, total_tokens):
-            return None
-
-        cutoff_index = self._determine_cutoff_index(messages)
-        if cutoff_index <= 0:
-            return None
-
-        messages_to_summarize, preserved_messages = self._partition_messages(messages, cutoff_index)
-        self._fire_hooks(messages_to_summarize, preserved_messages, runtime)
-        summary = await self._acreate_summary(messages_to_summarize)
-        new_messages = self._build_new_messages(summary)
-
-        return {
-            "messages": [
-                RemoveMessage(id=REMOVE_ALL_MESSAGES),
-                *new_messages,
-                *preserved_messages,
-            ]
-        }
-
-    def _fire_hooks(
-        self,
-        messages_to_summarize: list[AnyMessage],
-        preserved_messages: list[AnyMessage],
-        runtime: Runtime,
-    ) -> None:
-        if not self._before_summarization_hooks:
-            return
-
-        event = SummarizationEvent(
-            messages_to_summarize=tuple(messages_to_summarize),
-            preserved_messages=tuple(preserved_messages),
-            thread_id=_resolve_thread_id(runtime),
-            agent_name=_resolve_agent_name(runtime),
-            runtime=runtime,
-        )
-
-        for hook in self._before_summarization_hooks:
-            try:
-                hook(event)
-            except Exception:
-                hook_name = getattr(hook, "__name__", None) or type(hook).__name__
-                logger.exception("before_summarization hook %s failed", hook_name)

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

@@ -1,11 +1,11 @@
 """Middleware for automatic thread title generation."""
 
 import logging
-import re
-from typing import NotRequired, override
+from typing import Any, 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.config.title_config import get_title_config
@@ -78,7 +78,7 @@ class TitleMiddleware(AgentMiddleware[TitleMiddlewareState]):
         assistant_msg_content = next((m.content for m in messages if m.type == "ai"), "")
 
         user_msg = self._normalize_content(user_msg_content)
-        assistant_msg = self._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 +87,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
 
@@ -106,6 +101,20 @@ class TitleMiddleware(AgentMiddleware[TitleMiddlewareState]):
             return user_msg[:fallback_chars].rstrip() + "..."
         return user_msg if user_msg else "New Conversation"
 
+    def _get_runnable_config(self) -> dict[str, Any]:
+        """Inherit the parent RunnableConfig and add middleware tag.
+
+        This ensures RunJournal identifies LLM calls from this middleware
+        as ``middleware:title`` instead of ``lead_agent``.
+        """
+        try:
+            parent = get_config()
+        except Exception:
+            parent = {}
+        config = {**parent}
+        config["tags"] = [*(config.get("tags") or []), "middleware:title"]
+        return config
+
     def _generate_title_result(self, state: TitleMiddlewareState) -> dict | None:
         """Generate a local fallback title without blocking on an LLM call."""
         if not self._should_generate_title(state):
@@ -127,7 +136,7 @@ class TitleMiddleware(AgentMiddleware[TitleMiddlewareState]):
                 model = create_chat_model(name=config.model_name, thinking_enabled=False)
             else:
                 model = create_chat_model(thinking_enabled=False)
-            response = await model.ainvoke(prompt)
+            response = await model.ainvoke(prompt, config=self._get_runnable_config())
             title = self._parse_title(response.content)
             if title:
                 return {"title": title}

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

@@ -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)

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

@@ -262,25 +262,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
-        if isinstance(original_content, str):
-            # Simple case: string content, just prepend files message
-            updated_content = f"{files_message}\n\n{original_content}"
-        elif isinstance(original_content, list):
-            # Complex case: list content (multimodal), preserve all blocks
-            # Prepend files message as the first text block
-            files_block = {"type": "text", "text": f"{files_message}\n\n"}
-            # Keep all original blocks (including images)
-            updated_content = [files_block, *original_content]
-        else:
-            # Other types, preserve as-is
-            updated_content = original_content
+        original_content = ""
+        if isinstance(last_message.content, str):
+            original_content = last_message.content
+        elif isinstance(last_message.content, list):
+            text_parts = []
+            for block in last_message.content:
+                if isinstance(block, dict) and block.get("type") == "text":
+                    text_parts.append(block.get("text", ""))
+            original_content = "\n".join(text_parts)
 
         # 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,
         )

backend/packages/harness/deerflow/client.py

@@ -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)
 
 
@@ -257,53 +254,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 +315,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 +336,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.
@@ -538,8 +346,8 @@ class DeerFlowClient:
             StreamEvent with one of:
             - type="values"          data={"title": str|None, "messages": [...], "artifacts": [...]}
             - type="custom"          data={...}
-            - type="messages-tuple"  data={"type": "ai", "content": <delta>, "id": str}
-            - type="messages-tuple"  data={"type": "ai", "content": <delta>, "id": str, "usage_metadata": {...}}
+            - type="messages-tuple"  data={"type": "ai", "content": str, "id": str}
+            - type="messages-tuple"  data={"type": "ai", "content": str, "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,47 +364,13 @@ 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:
-            """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"],
+            stream_mode=["values", "custom"],
         ):
             if isinstance(item, tuple) and len(item) == 2:
                 mode, chunk = item
@@ -608,36 +382,6 @@ class DeerFlowClient:
                 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 +391,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 +448,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
-        ``messages-tuple`` events per ``id`` and returns the text of the
-        **last** AI message to complete.  Intermediate AI messages (e.g.
-        planner drafts) are discarded — only the final id's accumulated
-        text is returned.  Use :meth:`stream` directly if you need every
-        delta as it arrives.
+        Convenience wrapper around :meth:`stream` that returns only the
+        **last** AI text from ``messages-tuple`` events. If the agent emits
+        multiple text segments in one turn, intermediate segments are
+        discarded. Use :meth:`stream` directly to capture all events.
 
         Args:
             message: User message text.
@@ -695,21 +459,15 @@ class DeerFlowClient:
             **kwargs: Override client defaults (same as stream()).
 
         Returns:
-            The accumulated text of the last AI message, or empty string
-            if no AI text was produced.
+            The last AI message text, or empty string if no response.
         """
-        # Per-id delta lists joined once at the end — avoids the O(n²) cost
-        # of repeated ``str + str`` on a growing buffer for long responses.
-        chunks: dict[str, list[str]] = {}
-        last_id: str = ""
+        last_text = ""
         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, ()))
+                content = event.data.get("content", "")
+                if content:
+                    last_text = content
+        return last_text
 
     # ------------------------------------------------------------------
     # Public API — configuration queries
@@ -722,10 +480,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 +491,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:

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

@@ -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
@@ -374,23 +316,13 @@ class AioSandboxProvider(SandboxProvider):
     # ── Signal handling ──────────────────────────────────────────────────
 
     def _register_signal_handlers(self) -> None:
-        """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.
-        """
+        """Register signal handlers for graceful shutdown."""
         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
-            elif hasattr(signal, "SIGHUP") and signum == signal.SIGHUP:
-                original = self._original_sighup
-            else:
-                original = self._original_sigint
+            original = self._original_sigterm if signum == signal.SIGTERM else self._original_sigint
             if callable(original):
                 original(signum, frame)
             elif original == signal.SIG_DFL:
@@ -400,8 +332,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)")
 

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

@@ -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 []

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

@@ -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,52 +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.
 
@@ -220,12 +172,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).
-        # This ensures containers discovered via list_running() (which only has the name)
-        # can also be stopped.
-        stop_target = info.container_id or info.container_name
-        if stop_target:
-            self._stop_container(stop_target)
+        if info.container_id:
+            self._stop_container(info.container_id)
         # Extract port from sandbox_url for release
         try:
             from urllib.parse import urlparse
@@ -274,129 +222,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(

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

@@ -1,79 +0,0 @@
-import json
-
-from exa_py import Exa
-from langchain.tools import tool
-
-from deerflow.config import get_app_config
-
-
-def _get_exa_client(tool_name: str = "web_search") -> Exa:
-    config = get_app_config().get_tool_config(tool_name)
-    api_key = None
-    if config is not None and "api_key" in config.model_extra:
-        api_key = config.model_extra.get("api_key")
-    return Exa(api_key=api_key)
-
-
-@tool("web_search", parse_docstring=True)
-def web_search_tool(query: str) -> str:
-    """Search the web.
-
-    Args:
-        query: The query to search for.
-    """
-    try:
-        config = get_app_config().get_tool_config("web_search")
-        max_results = 5
-        search_type = "auto"
-        contents_max_characters = 1000
-        if config is not None:
-            max_results = config.model_extra.get("max_results", max_results)
-            search_type = config.model_extra.get("search_type", search_type)
-            contents_max_characters = config.model_extra.get("contents_max_characters", contents_max_characters)
-
-        client = _get_exa_client()
-        res = client.search(
-            query,
-            type=search_type,
-            num_results=max_results,
-            contents={"highlights": {"max_characters": contents_max_characters}},
-        )
-
-        normalized_results = [
-            {
-                "title": result.title or "",
-                "url": result.url or "",
-                "snippet": "\n".join(result.highlights) if result.highlights else "",
-            }
-            for result in res.results
-        ]
-        json_results = json.dumps(normalized_results, indent=2, ensure_ascii=False)
-        return json_results
-    except Exception as e:
-        return f"Error: {str(e)}"
-
-
-@tool("web_fetch", parse_docstring=True)
-def web_fetch_tool(url: str) -> str:
-    """Fetch the contents of a web page at a given URL.
-    Only fetch EXACT URLs that have been provided directly by the user or have been returned in results from the web_search and web_fetch tools.
-    This tool can NOT access content that requires authentication, such as private Google Docs or pages behind login walls.
-    Do NOT add www. to URLs that do NOT have them.
-    URLs must include the schema: https://example.com is a valid URL while example.com is an invalid URL.
-
-    Args:
-        url: The URL to fetch the contents of.
-    """
-    try:
-        client = _get_exa_client("web_fetch")
-        res = client.get_contents([url], text={"max_characters": 4096})
-
-        if res.results:
-            result = res.results[0]
-            title = result.title or "Untitled"
-            text = result.text or ""
-            return f"# {title}\n\n{text[:4096]}"
-        else:
-            return "Error: No results found"
-    except Exception as e:
-        return f"Error: {str(e)}"

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

@@ -6,10 +6,10 @@ from langchain.tools import tool
 from deerflow.config import get_app_config
 
 
-def _get_firecrawl_client(tool_name: str = "web_search") -> FirecrawlApp:
-    config = get_app_config().get_tool_config(tool_name)
+def _get_firecrawl_client() -> FirecrawlApp:
+    config = get_app_config().get_tool_config("web_search")
     api_key = None
-    if config is not None and "api_key" in config.model_extra:
+    if config is not None:
         api_key = config.model_extra.get("api_key")
     return FirecrawlApp(api_key=api_key)  # type: ignore[arg-type]
 
@@ -27,7 +27,7 @@ def web_search_tool(query: str) -> str:
         if config is not None:
             max_results = config.model_extra.get("max_results", max_results)
 
-        client = _get_firecrawl_client("web_search")
+        client = _get_firecrawl_client()
         result = client.search(query, limit=max_results)
 
         # result.web contains list of SearchResultWeb objects
@@ -58,7 +58,7 @@ def web_fetch_tool(url: str) -> str:
         url: The URL to fetch the contents of.
     """
     try:
-        client = _get_firecrawl_client("web_fetch")
+        client = _get_firecrawl_client()
         result = client.scrape(url, formats=["markdown"])
 
         markdown_content = result.markdown or ""

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,92 @@
+"""Unified database backend configuration.
+
+Controls BOTH the LangGraph checkpointer and the DeerFlow application
+persistence layer (runs, threads metadata, users, etc.). The user
+configures one backend; the system handles physical separation details.
+
+SQLite mode: checkpointer and app use different .db files in the same
+directory to avoid write-lock contention. This is automatic.
+
+Postgres mode: both use the same database URL but maintain independent
+connection pools with different lifecycles.
+
+Memory mode: checkpointer uses MemorySaver, app uses in-memory stores.
+No database is initialized.
+
+Sensitive values (postgres_url) should use $VAR syntax in config.yaml
+to reference environment variables from .env:
+
+    database:
+      backend: postgres
+      postgres_url: $DATABASE_URL
+
+The $VAR resolution is handled by AppConfig.resolve_env_variables()
+before this config is instantiated -- DatabaseConfig itself does not
+need to do any environment variable processing.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class DatabaseConfig(BaseModel):
+    backend: Literal["memory", "sqlite", "postgres"] = Field(
+        default="memory",
+        description=("Storage backend for both checkpointer and application data. 'memory' for development (no persistence across restarts), 'sqlite' for single-node deployment, 'postgres' for production multi-node deployment."),
+    )
+    sqlite_dir: str = Field(
+        default=".deer-flow/data",
+        description=("Directory for SQLite database files. Checkpointer uses {sqlite_dir}/checkpoints.db, application data uses {sqlite_dir}/app.db."),
+    )
+    postgres_url: str = Field(
+        default="",
+        description=(
+            "PostgreSQL connection URL, shared by checkpointer and app. "
+            "Use $DATABASE_URL in config.yaml to reference .env. "
+            "Example: postgresql://user:pass@host:5432/deerflow "
+            "(the +asyncpg driver suffix is added automatically where needed)."
+        ),
+    )
+    echo_sql: bool = Field(
+        default=False,
+        description="Echo all SQL statements to log (debug only).",
+    )
+    pool_size: int = Field(
+        default=5,
+        description="Connection pool size for the app ORM engine (postgres only).",
+    )
+
+    # -- Derived helpers (not user-configured) --
+
+    @property
+    def _resolved_sqlite_dir(self) -> str:
+        """Resolve sqlite_dir to an absolute path (relative to CWD)."""
+        from pathlib import Path
+
+        return str(Path(self.sqlite_dir).resolve())
+
+    @property
+    def checkpointer_sqlite_path(self) -> str:
+        """SQLite file path for the LangGraph checkpointer."""
+        return os.path.join(self._resolved_sqlite_dir, "checkpoints.db")
+
+    @property
+    def app_sqlite_path(self) -> str:
+        """SQLite file path for application ORM data."""
+        return os.path.join(self._resolved_sqlite_dir, "app.db")
+
+    @property
+    def app_sqlalchemy_url(self) -> str:
+        """SQLAlchemy async URL for the application ORM engine."""
+        if self.backend == "sqlite":
+            return f"sqlite+aiosqlite:///{self.app_sqlite_path}"
+        if self.backend == "postgres":
+            url = self.postgres_url
+            if url.startswith("postgresql://"):
+                url = url.replace("postgresql://", "postgresql+asyncpg://", 1)
+            return url
+        raise ValueError(f"No SQLAlchemy URL for backend={self.backend!r}")

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

@@ -27,10 +27,6 @@ class ModelConfig(BaseModel):
         default_factory=lambda: None,
         description="Extra settings to be passed to the model when thinking is enabled",
     )
-    when_thinking_disabled: dict | None = Field(
-        default_factory=lambda: None,
-        description="Extra settings to be passed to the model when thinking is disabled",
-    )
     supports_vision: bool = Field(default_factory=lambda: False, description="Whether the model supports vision/image inputs")
     thinking: dict | None = Field(
         default_factory=lambda: None,

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

@@ -0,0 +1,33 @@
+"""Run event storage configuration.
+
+Controls where run events (messages + execution traces) are persisted.
+
+Backends:
+- memory: In-memory storage, data lost on restart. Suitable for
+  development and testing.
+- db: SQL database via SQLAlchemy ORM. Provides full query capability.
+  Suitable for production deployments.
+- jsonl: Append-only JSONL files. Lightweight alternative for
+  single-node deployments that need persistence without a database.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class RunEventsConfig(BaseModel):
+    backend: Literal["memory", "db", "jsonl"] = Field(
+        default="memory",
+        description="Storage backend for run events. 'memory' for development (no persistence), 'db' for production (SQL queries), 'jsonl' for lightweight single-node persistence.",
+    )
+    max_trace_content: int = Field(
+        default=10240,
+        description="Maximum trace content size in bytes before truncation (db backend only).",
+    )
+    track_token_usage: bool = Field(
+        default=True,
+        description="Whether RunJournal should accumulate token counts to RunRow.",
+    )

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

@@ -20,11 +20,6 @@ class SubagentOverrideConfig(BaseModel):
         ge=1,
         description="Maximum turns for this subagent (None = use global or builtin default)",
     )
-    model: str | None = Field(
-        default=None,
-        min_length=1,
-        description="Model name for this subagent (None = inherit from parent agent)",
-    )
 
 
 class SubagentsAppConfig(BaseModel):
@@ -59,20 +54,6 @@ class SubagentsAppConfig(BaseModel):
             return override.timeout_seconds
         return self.timeout_seconds
 
-    def get_model_for(self, agent_name: str) -> str | None:
-        """Get the model override for a specific agent.
-
-        Args:
-            agent_name: The name of the subagent.
-
-        Returns:
-            Model name if overridden, None otherwise (subagent will inherit parent model).
-        """
-        override = self.agents.get(agent_name)
-        if override is not None and override.model is not None:
-            return override.model
-        return None
-
     def get_max_turns_for(self, agent_name: str, builtin_default: int) -> int:
         """Get the effective max_turns for a specific agent."""
         override = self.agents.get(agent_name)
@@ -103,8 +84,6 @@ def load_subagents_config_from_dict(config_dict: dict) -> None:
             parts.append(f"timeout={override.timeout_seconds}s")
         if override.max_turns is not None:
             parts.append(f"max_turns={override.max_turns}")
-        if override.model is not None:
-            parts.append(f"model={override.model}")
         if parts:
             overrides_summary[name] = ", ".join(parts)
 

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

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

backend/packages/harness/deerflow/models/factory.py

@@ -56,7 +56,6 @@ def create_chat_model(name: str | None = None, thinking_enabled: bool = False, *
             "supports_thinking",
             "supports_reasoning_effort",
             "when_thinking_enabled",
-            "when_thinking_disabled",
             "thinking",
             "supports_vision",
         },
@@ -73,24 +72,21 @@ def create_chat_model(name: str | None = None, thinking_enabled: bool = False, *
             raise ValueError(f"Model {name} does not support thinking. Set `supports_thinking` to true in the `config.yaml` to enable thinking.") from None
         if effective_wte:
             model_settings_from_config.update(effective_wte)
-    if not thinking_enabled:
-        if model_config.when_thinking_disabled is not None:
-            # User-provided disable settings take full precedence
-            model_settings_from_config.update(model_config.when_thinking_disabled)
-        elif has_thinking_settings and effective_wte.get("extra_body", {}).get("thinking", {}).get("type"):
+    if not thinking_enabled and has_thinking_settings:
+        if effective_wte.get("extra_body", {}).get("thinking", {}).get("type"):
             # OpenAI-compatible gateway: thinking is nested under extra_body
             model_settings_from_config["extra_body"] = _deep_merge_dicts(
                 model_settings_from_config.get("extra_body"),
                 {"thinking": {"type": "disabled"}},
             )
             model_settings_from_config["reasoning_effort"] = "minimal"
-        elif has_thinking_settings and (disable_chat_template_kwargs := _vllm_disable_chat_template_kwargs(effective_wte.get("extra_body", {}).get("chat_template_kwargs") or {})):
+        elif disable_chat_template_kwargs := _vllm_disable_chat_template_kwargs(effective_wte.get("extra_body", {}).get("chat_template_kwargs") or {}):
             # vLLM uses chat template kwargs to switch thinking on/off.
             model_settings_from_config["extra_body"] = _deep_merge_dicts(
                 model_settings_from_config.get("extra_body"),
                 {"chat_template_kwargs": disable_chat_template_kwargs},
             )
-        elif has_thinking_settings and effective_wte.get("thinking", {}).get("type"):
+        elif effective_wte.get("thinking", {}).get("type"):
             # Native langchain_anthropic: thinking is a direct constructor parameter
             model_settings_from_config["thinking"] = {"type": "disabled"}
     if not model_config.supports_reasoning_effort:
@@ -113,7 +109,16 @@ def create_chat_model(name: str | None = None, thinking_enabled: bool = False, *
         elif "reasoning_effort" not in model_settings_from_config:
             model_settings_from_config["reasoning_effort"] = "medium"
 
-    model_instance = model_class(**{**model_settings_from_config, **kwargs})
+    # Ensure stream_usage is enabled so that token usage metadata is available
+    # in streaming responses.  LangChain's BaseChatOpenAI only defaults
+    # stream_usage=True when no custom base_url/api_base is set, so models
+    # hitting third-party endpoints (e.g. doubao, deepseek) silently lose
+    # usage data.  We default it to True unless explicitly configured.
+    if "stream_usage" not in model_settings_from_config and "stream_usage" not in kwargs:
+        if "stream_usage" in getattr(model_class, "model_fields", {}):
+            model_settings_from_config["stream_usage"] = True
+
+    model_instance = model_class(**kwargs, **model_settings_from_config)
 
     callbacks = build_tracing_callbacks()
     if callbacks:

backend/packages/harness/deerflow/models/openai_codex_provider.py

@@ -48,10 +48,6 @@ class CodexChatModel(BaseChatModel):
 
     model_config = {"arbitrary_types_allowed": True}
 
-    @classmethod
-    def is_lc_serializable(cls) -> bool:
-        return True
-
     @property
     def _llm_type(self) -> str:
         return "codex-responses"
@@ -220,48 +216,18 @@ class CodexChatModel(BaseChatModel):
     def _stream_response(self, headers: dict, payload: dict) -> dict:
         """Stream SSE from Codex API and collect the final response."""
         completed_response = None
-        streamed_output_items: dict[int, dict[str, Any]] = {}
 
         with httpx.Client(timeout=300) as client:
             with client.stream("POST", f"{CODEX_BASE_URL}/responses", headers=headers, json=payload) as resp:
                 resp.raise_for_status()
                 for line in resp.iter_lines():
                     data = self._parse_sse_data_line(line)
-                    if not data:
-                        continue
-
-                    event_type = data.get("type")
-                    if event_type == "response.output_item.done":
-                        output_index = data.get("output_index")
-                        output_item = data.get("item")
-                        if isinstance(output_index, int) and isinstance(output_item, dict):
-                            streamed_output_items[output_index] = output_item
-                    elif event_type == "response.completed":
+                    if data and data.get("type") == "response.completed":
                         completed_response = data["response"]
 
         if not completed_response:
             raise RuntimeError("Codex API stream ended without response.completed event")
 
-        # ChatGPT Codex can emit the final assistant content only in stream events.
-        # When response.completed arrives, response.output may still be empty.
-        if streamed_output_items:
-            merged_output = []
-            response_output = completed_response.get("output")
-            if isinstance(response_output, list):
-                merged_output = list(response_output)
-
-            max_index = max(max(streamed_output_items), len(merged_output) - 1)
-            if max_index >= 0 and len(merged_output) <= max_index:
-                merged_output.extend([None] * (max_index + 1 - len(merged_output)))
-
-            for output_index, output_item in streamed_output_items.items():
-                existing_item = merged_output[output_index]
-                if not isinstance(existing_item, dict):
-                    merged_output[output_index] = output_item
-
-            completed_response = dict(completed_response)
-            completed_response["output"] = [item for item in merged_output if isinstance(item, dict)]
-
         return completed_response
 
     @staticmethod

backend/packages/harness/deerflow/models/patched_deepseek.py

@@ -23,14 +23,6 @@ class PatchedChatDeepSeek(ChatDeepSeek):
     request payload.
     """
 
-    @classmethod
-    def is_lc_serializable(cls) -> bool:
-        return True
-
-    @property
-    def lc_secrets(self) -> dict[str, str]:
-        return {"api_key": "DEEPSEEK_API_KEY", "openai_api_key": "DEEPSEEK_API_KEY"}
-
     def _get_request_payload(
         self,
         input_: LanguageModelInput,

backend/packages/harness/deerflow/persistence/__init__.py

@@ -0,0 +1,13 @@
+"""DeerFlow application persistence layer (SQLAlchemy 2.0 async ORM).
+
+This module manages DeerFlow's own application data -- runs metadata,
+thread ownership, cron jobs, users. It is completely separate from
+LangGraph's checkpointer, which manages graph execution state.
+
+Usage:
+    from deerflow.persistence import init_engine, close_engine, get_session_factory
+"""
+
+from deerflow.persistence.engine import close_engine, get_engine, get_session_factory, init_engine
+
+__all__ = ["close_engine", "get_engine", "get_session_factory", "init_engine"]

backend/packages/harness/deerflow/persistence/base.py

@@ -0,0 +1,40 @@
+"""SQLAlchemy declarative base with automatic to_dict support.
+
+All DeerFlow ORM models inherit from this Base. It provides a generic
+to_dict() method via SQLAlchemy's inspect() so individual models don't
+need to write their own serialization logic.
+
+LangGraph's checkpointer tables are NOT managed by this Base.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import inspect as sa_inspect
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    """Base class for all DeerFlow ORM models.
+
+    Provides:
+    - Automatic to_dict() via SQLAlchemy column inspection.
+    - Standard __repr__() showing all column values.
+    """
+
+    def to_dict(self, *, exclude: set[str] | None = None) -> dict:
+        """Convert ORM instance to plain dict.
+
+        Uses SQLAlchemy's inspect() to iterate mapped column attributes.
+
+        Args:
+            exclude: Optional set of column keys to omit.
+
+        Returns:
+            Dict of {column_key: value} for all mapped columns.
+        """
+        exclude = exclude or set()
+        return {c.key: getattr(self, c.key) for c in sa_inspect(type(self)).mapper.column_attrs if c.key not in exclude}
+
+    def __repr__(self) -> str:
+        cols = ", ".join(f"{c.key}={getattr(self, c.key)!r}" for c in sa_inspect(type(self)).mapper.column_attrs)
+        return f"{type(self).__name__}({cols})"

backend/packages/harness/deerflow/persistence/engine.py

@@ -0,0 +1,166 @@
+"""Async SQLAlchemy engine lifecycle management.
+
+Initializes at Gateway startup, provides session factory for
+repositories, disposes at shutdown.
+
+When database.backend="memory", init_engine is a no-op and
+get_session_factory() returns None. Repositories must check for
+None and fall back to in-memory implementations.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+
+
+def _json_serializer(obj: object) -> str:
+    """JSON serializer with ensure_ascii=False for Chinese character support."""
+    return json.dumps(obj, ensure_ascii=False)
+
+
+logger = logging.getLogger(__name__)
+
+_engine: AsyncEngine | None = None
+_session_factory: async_sessionmaker[AsyncSession] | None = None
+
+
+async def _auto_create_postgres_db(url: str) -> None:
+    """Connect to the ``postgres`` maintenance DB and CREATE DATABASE.
+
+    The target database name is extracted from *url*.  The connection is
+    made to the default ``postgres`` database on the same server using
+    ``AUTOCOMMIT`` isolation (CREATE DATABASE cannot run inside a
+    transaction).
+    """
+    from sqlalchemy import text
+    from sqlalchemy.engine.url import make_url
+
+    parsed = make_url(url)
+    db_name = parsed.database
+    if not db_name:
+        raise ValueError("Cannot auto-create database: no database name in URL")
+
+    # Connect to the default 'postgres' database to issue CREATE DATABASE
+    maint_url = parsed.set(database="postgres")
+    maint_engine = create_async_engine(maint_url, isolation_level="AUTOCOMMIT")
+    try:
+        async with maint_engine.connect() as conn:
+            await conn.execute(text(f'CREATE DATABASE "{db_name}"'))
+        logger.info("Auto-created PostgreSQL database: %s", db_name)
+    finally:
+        await maint_engine.dispose()
+
+
+async def init_engine(
+    backend: str,
+    *,
+    url: str = "",
+    echo: bool = False,
+    pool_size: int = 5,
+    sqlite_dir: str = "",
+) -> None:
+    """Create the async engine and session factory, then auto-create tables.
+
+    Args:
+        backend: "memory", "sqlite", or "postgres".
+        url: SQLAlchemy async URL (for sqlite/postgres).
+        echo: Echo SQL to log.
+        pool_size: Postgres connection pool size.
+        sqlite_dir: Directory to create for SQLite (ensured to exist).
+    """
+    global _engine, _session_factory
+
+    if backend == "memory":
+        logger.info("Persistence backend=memory -- ORM engine not initialized")
+        return
+
+    if backend == "postgres":
+        try:
+            import asyncpg  # noqa: F401
+        except ImportError:
+            raise ImportError("database.backend is set to 'postgres' but asyncpg is not installed.\nInstall it with:\n    uv sync --extra postgres\nOr switch to backend: sqlite in config.yaml for single-node deployment.") from None
+
+    if backend == "sqlite":
+        import os
+
+        os.makedirs(sqlite_dir or ".", exist_ok=True)
+        _engine = create_async_engine(url, echo=echo, json_serializer=_json_serializer)
+    elif backend == "postgres":
+        _engine = create_async_engine(
+            url,
+            echo=echo,
+            pool_size=pool_size,
+            pool_pre_ping=True,
+            json_serializer=_json_serializer,
+        )
+    else:
+        raise ValueError(f"Unknown persistence backend: {backend!r}")
+
+    _session_factory = async_sessionmaker(_engine, expire_on_commit=False)
+
+    # Auto-create tables (dev convenience). Production should use Alembic.
+    from deerflow.persistence.base import Base
+
+    # Import all models so Base.metadata discovers them.
+    # When no models exist yet (scaffolding phase), this is a no-op.
+    try:
+        import deerflow.persistence.models  # noqa: F401
+    except ImportError:
+        # Models package not yet available — tables won't be auto-created.
+        # This is expected during initial scaffolding or minimal installs.
+        logger.debug("deerflow.persistence.models not found; skipping auto-create tables")
+
+    try:
+        async with _engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+    except Exception as exc:
+        if backend == "postgres" and "does not exist" in str(exc):
+            # Database not yet created — attempt to auto-create it, then retry.
+            await _auto_create_postgres_db(url)
+            # Rebuild engine against the now-existing database
+            await _engine.dispose()
+            _engine = create_async_engine(url, echo=echo, pool_size=pool_size, pool_pre_ping=True, json_serializer=_json_serializer)
+            _session_factory = async_sessionmaker(_engine, expire_on_commit=False)
+            async with _engine.begin() as conn:
+                await conn.run_sync(Base.metadata.create_all)
+        else:
+            raise
+
+    logger.info("Persistence engine initialized: backend=%s", backend)
+
+
+async def init_engine_from_config(config) -> None:
+    """Convenience: init engine from a DatabaseConfig object."""
+    if config.backend == "memory":
+        await init_engine("memory")
+        return
+    await init_engine(
+        backend=config.backend,
+        url=config.app_sqlalchemy_url,
+        echo=config.echo_sql,
+        pool_size=config.pool_size,
+        sqlite_dir=config.sqlite_dir if config.backend == "sqlite" else "",
+    )
+
+
+def get_session_factory() -> async_sessionmaker[AsyncSession] | None:
+    """Return the async session factory, or None if backend=memory."""
+    return _session_factory
+
+
+def get_engine() -> AsyncEngine | None:
+    """Return the async engine, or None if not initialized."""
+    return _engine
+
+
+async def close_engine() -> None:
+    """Dispose the engine, release all connections."""
+    global _engine, _session_factory
+    if _engine is not None:
+        await _engine.dispose()
+        logger.info("Persistence engine closed")
+    _engine = None
+    _session_factory = None

backend/packages/harness/deerflow/persistence/feedback/__init__.py

@@ -0,0 +1,6 @@
+"""Feedback persistence — ORM and SQL repository."""
+
+from deerflow.persistence.feedback.model import FeedbackRow
+from deerflow.persistence.feedback.sql import FeedbackRepository
+
+__all__ = ["FeedbackRepository", "FeedbackRow"]

backend/packages/harness/deerflow/persistence/feedback/model.py

@@ -0,0 +1,30 @@
+"""ORM model for user feedback on runs."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from sqlalchemy import DateTime, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from deerflow.persistence.base import Base
+
+
+class FeedbackRow(Base):
+    __tablename__ = "feedback"
+
+    feedback_id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    run_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    thread_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    owner_id: Mapped[str | None] = mapped_column(String(64), index=True)
+    message_id: Mapped[str | None] = mapped_column(String(64))
+    # message_id is an optional RunEventStore event identifier —
+    # allows feedback to target a specific message or the entire run
+
+    rating: Mapped[int] = mapped_column(nullable=False)
+    # +1 (thumbs-up) or -1 (thumbs-down)
+
+    comment: Mapped[str | None] = mapped_column(Text)
+    # Optional text feedback from the user
+
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC))

backend/packages/harness/deerflow/persistence/feedback/sql.py

@@ -0,0 +1,98 @@
+"""SQLAlchemy-backed feedback storage.
+
+Each method acquires its own short-lived session.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+
+from sqlalchemy import case, func, select
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from deerflow.persistence.feedback.model import FeedbackRow
+
+
+class FeedbackRepository:
+    def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
+        self._sf = session_factory
+
+    @staticmethod
+    def _row_to_dict(row: FeedbackRow) -> dict:
+        d = row.to_dict()
+        val = d.get("created_at")
+        if isinstance(val, datetime):
+            d["created_at"] = val.isoformat()
+        return d
+
+    async def create(
+        self,
+        *,
+        run_id: str,
+        thread_id: str,
+        rating: int,
+        owner_id: str | None = None,
+        message_id: str | None = None,
+        comment: str | None = None,
+    ) -> dict:
+        """Create a feedback record. rating must be +1 or -1."""
+        if rating not in (1, -1):
+            raise ValueError(f"rating must be +1 or -1, got {rating}")
+        row = FeedbackRow(
+            feedback_id=str(uuid.uuid4()),
+            run_id=run_id,
+            thread_id=thread_id,
+            owner_id=owner_id,
+            message_id=message_id,
+            rating=rating,
+            comment=comment,
+            created_at=datetime.now(UTC),
+        )
+        async with self._sf() as session:
+            session.add(row)
+            await session.commit()
+            await session.refresh(row)
+            return self._row_to_dict(row)
+
+    async def get(self, feedback_id: str) -> dict | None:
+        async with self._sf() as session:
+            row = await session.get(FeedbackRow, feedback_id)
+            return self._row_to_dict(row) if row else None
+
+    async def list_by_run(self, thread_id: str, run_id: str, *, limit: int = 100) -> list[dict]:
+        stmt = select(FeedbackRow).where(FeedbackRow.thread_id == thread_id, FeedbackRow.run_id == run_id).order_by(FeedbackRow.created_at.asc()).limit(limit)
+        async with self._sf() as session:
+            result = await session.execute(stmt)
+            return [self._row_to_dict(r) for r in result.scalars()]
+
+    async def list_by_thread(self, thread_id: str, *, limit: int = 100) -> list[dict]:
+        stmt = select(FeedbackRow).where(FeedbackRow.thread_id == thread_id).order_by(FeedbackRow.created_at.asc()).limit(limit)
+        async with self._sf() as session:
+            result = await session.execute(stmt)
+            return [self._row_to_dict(r) for r in result.scalars()]
+
+    async def delete(self, feedback_id: str) -> bool:
+        async with self._sf() as session:
+            row = await session.get(FeedbackRow, feedback_id)
+            if row is None:
+                return False
+            await session.delete(row)
+            await session.commit()
+            return True
+
+    async def aggregate_by_run(self, thread_id: str, run_id: str) -> dict:
+        """Aggregate feedback stats for a run using database-side counting."""
+        stmt = select(
+            func.count().label("total"),
+            func.coalesce(func.sum(case((FeedbackRow.rating == 1, 1), else_=0)), 0).label("positive"),
+            func.coalesce(func.sum(case((FeedbackRow.rating == -1, 1), else_=0)), 0).label("negative"),
+        ).where(FeedbackRow.thread_id == thread_id, FeedbackRow.run_id == run_id)
+        async with self._sf() as session:
+            row = (await session.execute(stmt)).one()
+            return {
+                "run_id": run_id,
+                "total": row.total,
+                "positive": row.positive,
+                "negative": row.negative,
+            }

backend/packages/harness/deerflow/persistence/migrations/alembic.ini

@@ -0,0 +1,38 @@
+[alembic]
+script_location = %(here)s
+# Default URL for offline mode / autogenerate.
+# Runtime uses engine from DeerFlow config.
+sqlalchemy.url = sqlite+aiosqlite:///./data/app.db
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

backend/packages/harness/deerflow/persistence/migrations/env.py

@@ -0,0 +1,65 @@
+"""Alembic environment for DeerFlow application tables.
+
+ONLY manages DeerFlow's tables (runs, threads_meta, cron_jobs, users).
+LangGraph's checkpointer tables are managed by LangGraph itself -- they
+have their own schema lifecycle and must not be touched by Alembic.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from deerflow.persistence.base import Base
+
+# Import all models so metadata is populated.
+try:
+    import deerflow.persistence.models  # noqa: F401 — register ORM models with Base.metadata
+except ImportError:
+    # Models not available — migration will work with existing metadata only.
+    logging.getLogger(__name__).warning("Could not import deerflow.persistence.models; Alembic may not detect all tables")
+
+config = context.config
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        render_as_batch=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection):
+    context.configure(
+        connection=connection,
+        target_metadata=target_metadata,
+        render_as_batch=True,  # Required for SQLite ALTER TABLE support
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_migrations_online() -> None:
+    connectable = create_async_engine(config.get_main_option("sqlalchemy.url"))
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+    await connectable.dispose()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    asyncio.run(run_migrations_online())

backend/packages/harness/deerflow/persistence/models/__init__.py

@@ -0,0 +1,21 @@
+"""ORM model registration entry point.
+
+Importing this module ensures all ORM models are registered with
+``Base.metadata`` so Alembic autogenerate detects every table.
+
+The actual ORM classes have moved to entity-specific subpackages:
+- ``deerflow.persistence.thread_meta``
+- ``deerflow.persistence.run``
+- ``deerflow.persistence.feedback``
+
+``RunEventRow`` remains in ``deerflow.persistence.models.run_event`` because
+its storage implementation lives in ``deerflow.runtime.events.store.db`` and
+there is no matching entity directory.
+"""
+
+from deerflow.persistence.feedback.model import FeedbackRow
+from deerflow.persistence.models.run_event import RunEventRow
+from deerflow.persistence.run.model import RunRow
+from deerflow.persistence.thread_meta.model import ThreadMetaRow
+
+__all__ = ["FeedbackRow", "RunEventRow", "RunRow", "ThreadMetaRow"]

backend/packages/harness/deerflow/persistence/models/run_event.py

@@ -0,0 +1,31 @@
+"""ORM model for run events."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from sqlalchemy import JSON, DateTime, Index, String, Text, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+
+from deerflow.persistence.base import Base
+
+
+class RunEventRow(Base):
+    __tablename__ = "run_events"
+
+    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+    thread_id: Mapped[str] = mapped_column(String(64), nullable=False)
+    run_id: Mapped[str] = mapped_column(String(64), nullable=False)
+    event_type: Mapped[str] = mapped_column(String(32), nullable=False)
+    category: Mapped[str] = mapped_column(String(16), nullable=False)
+    # "message" | "trace" | "lifecycle"
+    content: Mapped[str] = mapped_column(Text, default="")
+    event_metadata: Mapped[dict] = mapped_column(JSON, default=dict)
+    seq: Mapped[int] = mapped_column(nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC))
+
+    __table_args__ = (
+        UniqueConstraint("thread_id", "seq", name="uq_events_thread_seq"),
+        Index("ix_events_thread_cat_seq", "thread_id", "category", "seq"),
+        Index("ix_events_run", "thread_id", "run_id", "seq"),
+    )

backend/packages/harness/deerflow/persistence/run/__init__.py

@@ -0,0 +1,6 @@
+"""Run metadata persistence — ORM and SQL repository."""
+
+from deerflow.persistence.run.model import RunRow
+from deerflow.persistence.run.sql import RunRepository
+
+__all__ = ["RunRepository", "RunRow"]

backend/packages/harness/deerflow/persistence/run/model.py

@@ -0,0 +1,49 @@
+"""ORM model for run metadata."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from sqlalchemy import JSON, DateTime, Index, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from deerflow.persistence.base import Base
+
+
+class RunRow(Base):
+    __tablename__ = "runs"
+
+    run_id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    thread_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
+    assistant_id: Mapped[str | None] = mapped_column(String(128))
+    owner_id: Mapped[str | None] = mapped_column(String(64), index=True)
+    status: Mapped[str] = mapped_column(String(20), default="pending")
+    # "pending" | "running" | "success" | "error" | "timeout" | "interrupted"
+
+    model_name: Mapped[str | None] = mapped_column(String(128))
+    multitask_strategy: Mapped[str] = mapped_column(String(20), default="reject")
+    metadata_json: Mapped[dict] = mapped_column(JSON, default=dict)
+    kwargs_json: Mapped[dict] = mapped_column(JSON, default=dict)
+    error: Mapped[str | None] = mapped_column(Text)
+
+    # Convenience fields (for listing pages without querying RunEventStore)
+    message_count: Mapped[int] = mapped_column(default=0)
+    first_human_message: Mapped[str | None] = mapped_column(Text)
+    last_ai_message: Mapped[str | None] = mapped_column(Text)
+
+    # Token usage (accumulated in-memory by RunJournal, written on run completion)
+    total_input_tokens: Mapped[int] = mapped_column(default=0)
+    total_output_tokens: Mapped[int] = mapped_column(default=0)
+    total_tokens: Mapped[int] = mapped_column(default=0)
+    llm_call_count: Mapped[int] = mapped_column(default=0)
+    lead_agent_tokens: Mapped[int] = mapped_column(default=0)
+    subagent_tokens: Mapped[int] = mapped_column(default=0)
+    middleware_tokens: Mapped[int] = mapped_column(default=0)
+
+    # Follow-up association
+    follow_up_to_run_id: Mapped[str | None] = mapped_column(String(64))
+
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC))
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC), onupdate=lambda: datetime.now(UTC))
+
+    __table_args__ = (Index("ix_runs_thread_status", "thread_id", "status"),)

backend/packages/harness/deerflow/persistence/run/sql.py

@@ -0,0 +1,227 @@
+"""SQLAlchemy-backed RunStore implementation.
+
+Each method acquires and releases its own short-lived session.
+Run status updates happen from background workers that may live
+minutes -- we don't hold connections across long execution.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from typing import Any
+
+from sqlalchemy import func, select, update
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from deerflow.persistence.run.model import RunRow
+from deerflow.runtime.runs.store.base import RunStore
+
+
+class RunRepository(RunStore):
+    def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
+        self._sf = session_factory
+
+    @staticmethod
+    def _safe_json(obj: Any) -> Any:
+        """Ensure obj is JSON-serializable. Falls back to model_dump() or str()."""
+        if obj is None:
+            return None
+        if isinstance(obj, (str, int, float, bool)):
+            return obj
+        if isinstance(obj, dict):
+            return {k: RunRepository._safe_json(v) for k, v in obj.items()}
+        if isinstance(obj, (list, tuple)):
+            return [RunRepository._safe_json(v) for v in obj]
+        if hasattr(obj, "model_dump"):
+            try:
+                return obj.model_dump()
+            except Exception:
+                pass
+        if hasattr(obj, "dict"):
+            try:
+                return obj.dict()
+            except Exception:
+                pass
+        try:
+            json.dumps(obj)
+            return obj
+        except (TypeError, ValueError):
+            return str(obj)
+
+    @staticmethod
+    def _row_to_dict(row: RunRow) -> dict[str, Any]:
+        d = row.to_dict()
+        # Remap JSON columns to match RunStore interface
+        d["metadata"] = d.pop("metadata_json", {})
+        d["kwargs"] = d.pop("kwargs_json", {})
+        # Convert datetime to ISO string for consistency with MemoryRunStore
+        for key in ("created_at", "updated_at"):
+            val = d.get(key)
+            if isinstance(val, datetime):
+                d[key] = val.isoformat()
+        return d
+
+    async def put(
+        self,
+        run_id,
+        *,
+        thread_id,
+        assistant_id=None,
+        owner_id=None,
+        status="pending",
+        multitask_strategy="reject",
+        metadata=None,
+        kwargs=None,
+        error=None,
+        created_at=None,
+        follow_up_to_run_id=None,
+    ):
+        now = datetime.now(UTC)
+        row = RunRow(
+            run_id=run_id,
+            thread_id=thread_id,
+            assistant_id=assistant_id,
+            owner_id=owner_id,
+            status=status,
+            multitask_strategy=multitask_strategy,
+            metadata_json=self._safe_json(metadata) or {},
+            kwargs_json=self._safe_json(kwargs) or {},
+            error=error,
+            follow_up_to_run_id=follow_up_to_run_id,
+            created_at=datetime.fromisoformat(created_at) if created_at else now,
+            updated_at=now,
+        )
+        async with self._sf() as session:
+            session.add(row)
+            await session.commit()
+
+    async def get(self, run_id):
+        async with self._sf() as session:
+            row = await session.get(RunRow, run_id)
+            return self._row_to_dict(row) if row else None
+
+    async def list_by_thread(self, thread_id, *, owner_id=None, limit=100):
+        stmt = select(RunRow).where(RunRow.thread_id == thread_id)
+        if owner_id is not None:
+            stmt = stmt.where(RunRow.owner_id == owner_id)
+        stmt = stmt.order_by(RunRow.created_at.desc()).limit(limit)
+        async with self._sf() as session:
+            result = await session.execute(stmt)
+            return [self._row_to_dict(r) for r in result.scalars()]
+
+    async def update_status(self, run_id, status, *, error=None):
+        values: dict[str, Any] = {"status": status, "updated_at": datetime.now(UTC)}
+        if error is not None:
+            values["error"] = error
+        async with self._sf() as session:
+            await session.execute(update(RunRow).where(RunRow.run_id == run_id).values(**values))
+            await session.commit()
+
+    async def delete(self, run_id):
+        async with self._sf() as session:
+            row = await session.get(RunRow, run_id)
+            if row is not None:
+                await session.delete(row)
+                await session.commit()
+
+    async def list_pending(self, *, before=None):
+        if before is None:
+            before_dt = datetime.now(UTC)
+        elif isinstance(before, datetime):
+            before_dt = before
+        else:
+            before_dt = datetime.fromisoformat(before)
+        stmt = select(RunRow).where(RunRow.status == "pending", RunRow.created_at <= before_dt).order_by(RunRow.created_at.asc())
+        async with self._sf() as session:
+            result = await session.execute(stmt)
+            return [self._row_to_dict(r) for r in result.scalars()]
+
+    async def update_run_completion(
+        self,
+        run_id: str,
+        *,
+        status: str,
+        total_input_tokens: int = 0,
+        total_output_tokens: int = 0,
+        total_tokens: int = 0,
+        llm_call_count: int = 0,
+        lead_agent_tokens: int = 0,
+        subagent_tokens: int = 0,
+        middleware_tokens: int = 0,
+        message_count: int = 0,
+        last_ai_message: str | None = None,
+        first_human_message: str | None = None,
+        error: str | None = None,
+    ) -> None:
+        """Update status + token usage + convenience fields on run completion."""
+        values: dict[str, Any] = {
+            "status": status,
+            "total_input_tokens": total_input_tokens,
+            "total_output_tokens": total_output_tokens,
+            "total_tokens": total_tokens,
+            "llm_call_count": llm_call_count,
+            "lead_agent_tokens": lead_agent_tokens,
+            "subagent_tokens": subagent_tokens,
+            "middleware_tokens": middleware_tokens,
+            "message_count": message_count,
+            "updated_at": datetime.now(UTC),
+        }
+        if last_ai_message is not None:
+            values["last_ai_message"] = last_ai_message[:2000]
+        if first_human_message is not None:
+            values["first_human_message"] = first_human_message[:2000]
+        if error is not None:
+            values["error"] = error
+        async with self._sf() as session:
+            await session.execute(update(RunRow).where(RunRow.run_id == run_id).values(**values))
+            await session.commit()
+
+    async def aggregate_tokens_by_thread(self, thread_id: str) -> dict[str, Any]:
+        """Aggregate token usage via a single SQL GROUP BY query."""
+        _completed = RunRow.status.in_(("success", "error"))
+        _thread = RunRow.thread_id == thread_id
+
+        stmt = (
+            select(
+                func.coalesce(RunRow.model_name, "unknown").label("model"),
+                func.count().label("runs"),
+                func.coalesce(func.sum(RunRow.total_tokens), 0).label("total_tokens"),
+                func.coalesce(func.sum(RunRow.total_input_tokens), 0).label("total_input_tokens"),
+                func.coalesce(func.sum(RunRow.total_output_tokens), 0).label("total_output_tokens"),
+                func.coalesce(func.sum(RunRow.lead_agent_tokens), 0).label("lead_agent"),
+                func.coalesce(func.sum(RunRow.subagent_tokens), 0).label("subagent"),
+                func.coalesce(func.sum(RunRow.middleware_tokens), 0).label("middleware"),
+            )
+            .where(_thread, _completed)
+            .group_by(func.coalesce(RunRow.model_name, "unknown"))
+        )
+
+        async with self._sf() as session:
+            rows = (await session.execute(stmt)).all()
+
+        total_tokens = total_input = total_output = total_runs = 0
+        lead_agent = subagent = middleware = 0
+        by_model: dict[str, dict] = {}
+        for r in rows:
+            by_model[r.model] = {"tokens": r.total_tokens, "runs": r.runs}
+            total_tokens += r.total_tokens
+            total_input += r.total_input_tokens
+            total_output += r.total_output_tokens
+            total_runs += r.runs
+            lead_agent += r.lead_agent
+            subagent += r.subagent
+            middleware += r.middleware
+
+        return {
+            "total_tokens": total_tokens,
+            "total_input_tokens": total_input,
+            "total_output_tokens": total_output,
+            "total_runs": total_runs,
+            "by_model": by_model,
+            "by_caller": {
+                "lead_agent": lead_agent,
+                "subagent": subagent,
+                "middleware": middleware,
+            },
+        }

backend/packages/harness/deerflow/persistence/thread_meta/__init__.py

@@ -0,0 +1,13 @@
+"""Thread metadata persistence — ORM, abstract store, and concrete implementations."""
+
+from deerflow.persistence.thread_meta.base import ThreadMetaStore
+from deerflow.persistence.thread_meta.memory import MemoryThreadMetaStore
+from deerflow.persistence.thread_meta.model import ThreadMetaRow
+from deerflow.persistence.thread_meta.sql import ThreadMetaRepository
+
+__all__ = [
+    "MemoryThreadMetaStore",
+    "ThreadMetaRepository",
+    "ThreadMetaRow",
+    "ThreadMetaStore",
+]

backend/packages/harness/deerflow/persistence/thread_meta/base.py

@@ -0,0 +1,60 @@
+"""Abstract interface for thread metadata storage.
+
+Implementations:
+- ThreadMetaRepository: SQL-backed (sqlite / postgres via SQLAlchemy)
+- MemoryThreadMetaStore: wraps LangGraph BaseStore (memory mode)
+"""
+
+from __future__ import annotations
+
+import abc
+
+
+class ThreadMetaStore(abc.ABC):
+    @abc.abstractmethod
+    async def create(
+        self,
+        thread_id: str,
+        *,
+        assistant_id: str | None = None,
+        owner_id: str | None = None,
+        display_name: str | None = None,
+        metadata: dict | None = None,
+    ) -> dict:
+        pass
+
+    @abc.abstractmethod
+    async def get(self, thread_id: str) -> dict | None:
+        pass
+
+    @abc.abstractmethod
+    async def search(
+        self,
+        *,
+        metadata: dict | None = None,
+        status: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[dict]:
+        pass
+
+    @abc.abstractmethod
+    async def update_display_name(self, thread_id: str, display_name: str) -> None:
+        pass
+
+    @abc.abstractmethod
+    async def update_status(self, thread_id: str, status: str) -> None:
+        pass
+
+    @abc.abstractmethod
+    async def update_metadata(self, thread_id: str, metadata: dict) -> None:
+        """Merge ``metadata`` into the thread's metadata field.
+
+        Existing keys are overwritten by the new values; keys absent from
+        ``metadata`` are preserved. No-op if the thread does not exist.
+        """
+        pass
+
+    @abc.abstractmethod
+    async def delete(self, thread_id: str) -> None:
+        pass

backend/packages/harness/deerflow/persistence/thread_meta/memory.py

@@ -0,0 +1,120 @@
+"""In-memory ThreadMetaStore backed by LangGraph BaseStore.
+
+Used when database.backend=memory. Delegates to the LangGraph Store's
+``("threads",)`` namespace — the same namespace used by the Gateway
+router for thread records.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from langgraph.store.base import BaseStore
+
+from deerflow.persistence.thread_meta.base import ThreadMetaStore
+
+THREADS_NS: tuple[str, ...] = ("threads",)
+
+
+class MemoryThreadMetaStore(ThreadMetaStore):
+    def __init__(self, store: BaseStore) -> None:
+        self._store = store
+
+    async def create(
+        self,
+        thread_id: str,
+        *,
+        assistant_id: str | None = None,
+        owner_id: str | None = None,
+        display_name: str | None = None,
+        metadata: dict | None = None,
+    ) -> dict:
+        now = time.time()
+        record: dict[str, Any] = {
+            "thread_id": thread_id,
+            "assistant_id": assistant_id,
+            "owner_id": owner_id,
+            "display_name": display_name,
+            "status": "idle",
+            "metadata": metadata or {},
+            "values": {},
+            "created_at": now,
+            "updated_at": now,
+        }
+        await self._store.aput(THREADS_NS, thread_id, record)
+        return record
+
+    async def get(self, thread_id: str) -> dict | None:
+        item = await self._store.aget(THREADS_NS, thread_id)
+        return item.value if item is not None else None
+
+    async def search(
+        self,
+        *,
+        metadata: dict | None = None,
+        status: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[dict]:
+        filter_dict: dict[str, Any] = {}
+        if metadata:
+            filter_dict.update(metadata)
+        if status:
+            filter_dict["status"] = status
+
+        items = await self._store.asearch(
+            THREADS_NS,
+            filter=filter_dict or None,
+            limit=limit,
+            offset=offset,
+        )
+        return [self._item_to_dict(item) for item in items]
+
+    async def update_display_name(self, thread_id: str, display_name: str) -> None:
+        item = await self._store.aget(THREADS_NS, thread_id)
+        if item is None:
+            return
+        record = dict(item.value)
+        record["display_name"] = display_name
+        record["updated_at"] = time.time()
+        await self._store.aput(THREADS_NS, thread_id, record)
+
+    async def update_status(self, thread_id: str, status: str) -> None:
+        item = await self._store.aget(THREADS_NS, thread_id)
+        if item is None:
+            return
+        record = dict(item.value)
+        record["status"] = status
+        record["updated_at"] = time.time()
+        await self._store.aput(THREADS_NS, thread_id, record)
+
+    async def update_metadata(self, thread_id: str, metadata: dict) -> None:
+        """Merge ``metadata`` into the in-memory record. No-op if absent."""
+        item = await self._store.aget(THREADS_NS, thread_id)
+        if item is None:
+            return
+        record = dict(item.value)
+        merged = dict(record.get("metadata") or {})
+        merged.update(metadata)
+        record["metadata"] = merged
+        record["updated_at"] = time.time()
+        await self._store.aput(THREADS_NS, thread_id, record)
+
+    async def delete(self, thread_id: str) -> None:
+        await self._store.adelete(THREADS_NS, thread_id)
+
+    @staticmethod
+    def _item_to_dict(item) -> dict[str, Any]:
+        """Convert a Store SearchItem to the dict format expected by callers."""
+        val = item.value
+        return {
+            "thread_id": item.key,
+            "assistant_id": val.get("assistant_id"),
+            "owner_id": val.get("owner_id"),
+            "display_name": val.get("display_name"),
+            "status": val.get("status", "idle"),
+            "metadata": val.get("metadata", {}),
+            "created_at": str(val.get("created_at", "")),
+            "updated_at": str(val.get("updated_at", "")),
+        }

backend/packages/harness/deerflow/persistence/thread_meta/model.py

@@ -0,0 +1,23 @@
+"""ORM model for thread metadata."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from sqlalchemy import JSON, DateTime, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from deerflow.persistence.base import Base
+
+
+class ThreadMetaRow(Base):
+    __tablename__ = "threads_meta"
+
+    thread_id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    assistant_id: Mapped[str | None] = mapped_column(String(128), index=True)
+    owner_id: Mapped[str | None] = mapped_column(String(64), index=True)
+    display_name: Mapped[str | None] = mapped_column(String(256))
+    status: Mapped[str] = mapped_column(String(20), default="idle")
+    metadata_json: Mapped[dict] = mapped_column(JSON, default=dict)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC))
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC), onupdate=lambda: datetime.now(UTC))