fix(sandbox): preserve PermissionError messages and allow /mnt/user-data root in resolve_local_tool_path

Co-authored-by: WillemJiang <219644+WillemJiang@users.noreply.github.com>

.env.example

@@ -4,8 +4,6 @@ TAVILY_API_KEY=your-tavily-api-key
 # Jina API Key
 JINA_API_KEY=your-jina-api-key
 
-# InfoQuest API Key
-INFOQUEST_API_KEY=your-infoquest-api-key
 # CORS Origins (comma-separated) - e.g., http://localhost:3000,http://localhost:3001
 # CORS_ORIGINS=http://localhost:3000
 
@@ -15,20 +13,4 @@ INFOQUEST_API_KEY=your-infoquest-api-key
 # OPENAI_API_KEY=your-openai-api-key
 # GEMINI_API_KEY=your-gemini-api-key
 # DEEPSEEK_API_KEY=your-deepseek-api-key
-# NOVITA_API_KEY=your-novita-api-key  # OpenAI-compatible, see https://novita.ai
-# MINIMAX_API_KEY=your-minimax-api-key  # OpenAI-compatible, see https://platform.minimax.io
-# FEISHU_APP_ID=your-feishu-app-id
-# FEISHU_APP_SECRET=your-feishu-app-secret
-
-# SLACK_BOT_TOKEN=your-slack-bot-token
-# SLACK_APP_TOKEN=your-slack-app-token
-# TELEGRAM_BOT_TOKEN=your-telegram-bot-token
-
-# Enable LangSmith to monitor and debug your LLM calls, agent runs, and tool executions.
-# LANGSMITH_TRACING=true
-# LANGSMITH_ENDPOINT=https://api.smith.langchain.com
-# LANGSMITH_API_KEY=your-langsmith-api-key
-# LANGSMITH_PROJECT=your-langsmith-project
-
-# GitHub API Token
-# GITHUB_TOKEN=your-github-token
+# NOVITA_API_KEY=your-novita-api-key  # OpenAI-compatible, see https://novita.ai

.github/ISSUE_TEMPLATE/runtime-information.yml

@@ -1,128 +0,0 @@
-name: Runtime Information
-description: Report runtime/environment details to help reproduce an issue.
-title: "[runtime] "
-labels:
-  - needs-triage
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Thanks for sharing runtime details.
-        Complete this form so maintainers can quickly reproduce and diagnose the problem.
-
-  - type: input
-    id: summary
-    attributes:
-      label: Problem summary
-      description: Short summary of the issue.
-      placeholder: e.g. make dev fails to start gateway service
-    validations:
-      required: true
-
-  - type: textarea
-    id: expected
-    attributes:
-      label: Expected behavior
-      placeholder: What did you expect to happen?
-    validations:
-      required: true
-
-  - type: textarea
-    id: actual
-    attributes:
-      label: Actual behavior
-      placeholder: What happened instead? Include key error lines.
-    validations:
-      required: true
-
-  - type: dropdown
-    id: os
-    attributes:
-      label: Operating system
-      options:
-        - macOS
-        - Linux
-        - Windows
-        - Other
-    validations:
-      required: true
-
-  - type: input
-    id: platform_details
-    attributes:
-      label: Platform details
-      description: Add architecture and shell if relevant.
-      placeholder: e.g. arm64, zsh
-
-  - type: input
-    id: python_version
-    attributes:
-      label: Python version
-      placeholder: e.g. Python 3.12.9
-
-  - type: input
-    id: node_version
-    attributes:
-      label: Node.js version
-      placeholder: e.g. v23.11.0
-
-  - type: input
-    id: pnpm_version
-    attributes:
-      label: pnpm version
-      placeholder: e.g. 10.26.2
-
-  - type: input
-    id: uv_version
-    attributes:
-      label: uv version
-      placeholder: e.g. 0.7.20
-
-  - type: dropdown
-    id: run_mode
-    attributes:
-      label: How are you running DeerFlow?
-      options:
-        - Local (make dev)
-        - Docker (make docker-dev)
-        - CI
-        - Other
-    validations:
-      required: true
-
-  - type: textarea
-    id: reproduce
-    attributes:
-      label: Reproduction steps
-      description: Provide exact commands and sequence.
-      placeholder: |
-        1. make check
-        2. make install
-        3. make dev
-        4. ...
-    validations:
-      required: true
-
-  - type: textarea
-    id: logs
-    attributes:
-      label: Relevant logs
-      description: Paste key lines from logs (for example logs/gateway.log, logs/frontend.log).
-      render: shell
-    validations:
-      required: true
-
-  - type: textarea
-    id: git_info
-    attributes:
-      label: Git state
-      description: Share output of git branch and latest commit SHA.
-      placeholder: |
-        branch: feature/my-branch
-        commit: abcdef1
-
-  - type: textarea
-    id: additional
-    attributes:
-      label: Additional context
-      description: Add anything else that might help triage.

.github/copilot-instructions.md

@@ -1,213 +0,0 @@
-# Copilot Onboarding Instructions for DeerFlow
-
-Use this file as the default operating guide for this repository. Follow it first, and only search the codebase when this file is incomplete or incorrect.
-
-## 1) Repository Summary
-
-DeerFlow is a full-stack "super agent harness".
-
-- Backend: Python 3.12, LangGraph + FastAPI gateway, sandbox/tool system, memory, MCP integration.
-- Frontend: Next.js 16 + React 19 + TypeScript + pnpm.
-- Local dev entrypoint: root `Makefile` starts backend + frontend + nginx on `http://localhost:2026`.
-- Docker dev entrypoint: `make docker-*` (mode-aware provisioner startup from `config.yaml`).
-
-Current repo footprint is medium-large (backend service, frontend app, docker stack, skills library, docs).
-
-## 2) Runtime and Toolchain Requirements
-
-Validated in this repo on macOS:
-
-- Node.js `>=22` (validated with Node `23.11.0`)
-- pnpm (repo expects lockfile generated by pnpm 10; validated with pnpm `10.26.2` and `10.15.0`)
-- Python `>=3.12` (CI uses `3.12`)
-- `uv` (validated with `0.7.20`)
-- `nginx` (required for `make dev` unified local endpoint)
-
-Always run from repo root unless a command explicitly says otherwise.
-
-## 3) Build/Test/Lint/Run - Verified Command Sequences
-
-These were executed and validated in this repository.
-
-### A. Bootstrap and install
-
-1. Check prerequisites:
-
-```bash
-make check
-```
-
-Observed: passes when required tools are installed.
-
-2. Install dependencies (recommended order: backend then frontend, as implemented by `make install`):
-
-```bash
-make install
-```
-
-### B. Backend CI-equivalent validation
-
-Run from `backend/`:
-
-```bash
-make lint
-make test
-```
-
-Validated results:
-
-- `make lint`: pass (`ruff check .`)
-- `make test`: pass (`277 passed, 15 warnings in ~76.6s`)
-
-CI parity:
-
-- `.github/workflows/backend-unit-tests.yml` runs on pull requests.
-- CI executes `uv sync --group dev`, then `make lint`, then `make test` in `backend/`.
-
-### C. Frontend validation
-
-Run from `frontend/`.
-
-Recommended reliable sequence:
-
-```bash
-pnpm lint
-pnpm typecheck
-BETTER_AUTH_SECRET=local-dev-secret pnpm build
-```
-
-Observed failure modes and workarounds:
-
-- `pnpm build` fails without `BETTER_AUTH_SECRET` in production-mode env validation.
-- Workaround: set `BETTER_AUTH_SECRET` (best) or set `SKIP_ENV_VALIDATION=1`.
-- Even with `SKIP_ENV_VALIDATION=1`, Better Auth can still warn/error in logs about default secret; prefer setting a real non-default secret.
-- `pnpm check` currently fails (`next lint` invocation is incompatible here and resolves to an invalid directory). Do not rely on `pnpm check`; run `pnpm lint` and `pnpm typecheck` explicitly.
-
-### D. Run locally (all services)
-
-From root:
-
-```bash
-make dev
-```
-
-Behavior:
-
-- Stops existing local services first.
-- Starts LangGraph (`2024`), Gateway (`8001`), Frontend (`3000`), nginx (`2026`).
-- Unified app endpoint: `http://localhost:2026`.
-- Logs: `logs/langgraph.log`, `logs/gateway.log`, `logs/frontend.log`, `logs/nginx.log`.
-
-Stop services:
-
-```bash
-make stop
-```
-
-If tool sessions/timeouts interrupt `make dev`, run `make stop` again to ensure cleanup.
-
-### E. Config bootstrap
-
-From root:
-
-```bash
-make config
-```
-
-Important behavior:
-
-- This intentionally aborts if `config.yaml` (or `config.yml`/`configure.yml`) already exists.
-- Use `make config` only for first-time setup in a clean clone.
-
-## 4) Command Order That Minimizes Failures
-
-Use this exact order for local code changes:
-
-1. `make check`
-2. `make install` (if frontend fails with proxy errors, rerun frontend install with proxy vars unset)
-3. Backend checks: `cd backend && make lint && make test`
-4. Frontend checks: `cd frontend && pnpm lint && pnpm typecheck`
-5. Frontend build (if UI changes or release-sensitive changes): `BETTER_AUTH_SECRET=... pnpm build`
-
-Always run backend lint/tests before opening PRs because that is what CI enforces.
-
-## 5) Project Layout and Architecture (High-Value Paths)
-
-Root-level orchestration and config:
-
-- `Makefile` - main local/dev/docker command entrypoints
-- `config.example.yaml` - primary app config template
-- `config.yaml` - local active config (gitignored)
-- `docker/docker-compose-dev.yaml` - Docker dev topology
-- `.github/workflows/backend-unit-tests.yml` - PR validation workflow
-
-Backend core:
-
-- `backend/packages/harness/deerflow/agents/` - lead agent, middleware chain, memory
-- `backend/app/gateway/` - FastAPI gateway API
-- `backend/packages/harness/deerflow/sandbox/` - sandbox provider + tool wrappers
-- `backend/packages/harness/deerflow/subagents/` - subagent registry/execution
-- `backend/packages/harness/deerflow/mcp/` - MCP integration
-- `backend/langgraph.json` - graph entrypoint (`deerflow.agents:make_lead_agent`)
-- `backend/pyproject.toml` - Python deps and `requires-python`
-- `backend/ruff.toml` - lint/format policy
-- `backend/tests/` - backend unit and integration-like tests
-
-Frontend core:
-
-- `frontend/src/app/` - Next.js routes/pages
-- `frontend/src/components/` - UI components
-- `frontend/src/core/` - app logic (threads, tools, API, models)
-- `frontend/src/env.js` - env schema/validation (critical for build behavior)
-- `frontend/package.json` - scripts/deps
-- `frontend/eslint.config.js` - lint rules
-- `frontend/tsconfig.json` - TS config
-
-Skills and assets:
-
-- `skills/public/` - built-in skill packs loaded by agent runtime
-
-## 6) Pre-Checkin / Validation Expectations
-
-Before submitting changes, run at minimum:
-
-- Backend: `cd backend && make lint && make test`
-- Frontend (if touched): `cd frontend && pnpm lint && pnpm typecheck`
-- Frontend build when changing env/auth/routing/build-sensitive files: `BETTER_AUTH_SECRET=... pnpm build`
-
-If touching orchestration/config (`Makefile`, `docker/*`, `config*.yaml`), also run `make dev` and verify the four services start.
-
-## 7) Non-Obvious Dependencies and Gotchas
-
-- Proxy env vars can silently break frontend network operations (`pnpm install`/registry access).
-- `BETTER_AUTH_SECRET` is effectively required for reliable frontend production build validation.
-- Next.js may warn about multiple lockfiles and workspace root inference; this is currently a warning, not a build blocker.
-- `make config` is non-idempotent by design when config already exists.
-- `make dev` includes process cleanup and can emit shutdown logs/noise if interrupted; this is expected.
-
-## 8) Root Inventory (quick reference)
-
-Important root entries:
-
-- `.github/`
-- `backend/`
-- `frontend/`
-- `docker/`
-- `skills/`
-- `scripts/`
-- `docs/`
-- `README.md`
-- `CONTRIBUTING.md`
-- `Makefile`
-- `config.example.yaml`
-- `extensions_config.example.json`
-
-## 9) Instruction Priority
-
-Trust this onboarding guide first.
-
-Only do broad repo searches (`grep/find/code search`) when:
-
-- you need file-level implementation details not listed here,
-- a command here fails and you need updated replacement behavior,
-- or CI/workflow definitions have changed since this file was written.

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

@@ -1,8 +1,6 @@
 name: Unit Tests
 
 on:
-  push:
-    branches: [ 'main' ]
   pull_request:
     types: [opened, synchronize, reopened, ready_for_review]
 
@@ -10,9 +8,6 @@ concurrency:
   group: unit-tests-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
-permissions:
-  contents: read
-
 jobs:
   backend-unit-tests:
     if: github.event.pull_request.draft == false
@@ -35,6 +30,10 @@ jobs:
         working-directory: backend
         run: uv sync --group dev
 
+      - name: Lint backend
+        working-directory: backend
+        run: make lint
+
       - name: Run unit tests of backend
         working-directory: backend
         run: make test

.github/workflows/lint-check.yml

@@ -1,74 +0,0 @@
-name: Lint Check
-
-on:
-  push:
-    branches: [ 'main' ]
-  pull_request:
-    branches: [ '*' ]
-
-permissions:
-  contents: read
-
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: '3.12'
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v7
-
-      - name: Install dependencies
-        working-directory: backend
-        run: |
-          uv sync --group dev
-
-      - name: Lint backend
-        working-directory: backend
-        run: make lint
-
-  lint-frontend:
-    runs-on: ubuntu-latest
-    steps:
-      - 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
-        run: |
-          cd frontend
-          pnpm install --frozen-lockfile
-
-      - name: Check frontend formatting
-        run: |
-          cd frontend
-          pnpm format
-
-      - name: Run frontend linting
-        run: |
-          cd frontend
-          pnpm lint
-
-      - name: Check TypeScript types
-        run: |
-          cd frontend
-          pnpm typecheck
-
-      - name: Build frontend
-        run: |
-          cd frontend
-          BETTER_AUTH_SECRET=local-dev-secret pnpm build

.gitignore

@@ -1,7 +1,5 @@
 # DeerFlow docker image cache
 docker/.cache/
-# oh-my-claudecode state
-.omc/
 # OS generated files
 .DS_Store
 *.local
@@ -50,7 +48,3 @@ sandbox_image_cache.tar
 
 # ignore the legacy `web` folder
 web/
-
-# Deployment artifacts
-backend/Dockerfile.langgraph
-config.yaml.bak

CONTRIBUTING.md

@@ -70,47 +70,6 @@ make docker-logs-frontend
 make docker-logs-gateway
 ```
 
-If Docker builds are slow in your network, you can override the default package registries before running `make docker-init` or `make docker-start`:
-
-```bash
-export UV_INDEX_URL=https://pypi.org/simple
-export NPM_REGISTRY=https://registry.npmjs.org
-```
-
-#### 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:
-
-```text
-unable to get image 'deer-flow-dev-langgraph': permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock
-```
-
-Recommended fix: add your current user to the `docker` group so Docker commands work without `sudo`.
-
-1. Confirm the `docker` group exists:
-   ```bash
-   getent group docker
-   ```
-2. Add your current user to the `docker` group:
-   ```bash
-   sudo usermod -aG docker $USER
-   ```
-3. Apply the new group membership. The most reliable option is to log out completely and then log back in. If you want to refresh the current shell session instead, run:
-   ```bash
-   newgrp docker
-   ```
-4. Verify Docker access:
-   ```bash
-   docker ps
-   ```
-5. Retry the DeerFlow command:
-   ```bash
-   make docker-stop
-   make docker-start
-   ```
-
-If `docker ps` still reports a permission error after `usermod`, fully log out and log back in before retrying.
-
 #### Docker Architecture
 
 ```
@@ -257,26 +216,15 @@ Nginx (port 2026) ← Unified entry point
 
 2. **Make your changes** with hot-reload enabled
 
-3. **Format and lint your code** (CI will reject unformatted code):
-   ```bash
-   # Backend
-   cd backend
-   make format   # ruff check --fix + ruff format
+3. **Test your changes** thoroughly
 
-   # Frontend
-   cd frontend
-   pnpm format:write   # Prettier
-   ```
-
-4. **Test your changes** thoroughly
-
-5. **Commit your changes**:
+4. **Commit your changes**:
    ```bash
    git add .
    git commit -m "feat: description of your changes"
    ```
 
-6. **Push and create a Pull Request**:
+5. **Push and create a Pull Request**:
    ```bash
    git push origin feature/your-feature-name
    ```
@@ -288,9 +236,9 @@ Nginx (port 2026) ← Unified entry point
 cd backend
 uv run pytest
 
-# Frontend checks
+# Frontend tests
 cd frontend
-pnpm check
+pnpm test
 ```
 
 ### PR Regression Checks
@@ -302,9 +250,8 @@ Every pull request runs the backend regression workflow at [.github/workflows/ba
 
 ## Code Style
 
-- **Backend (Python)**: We use `ruff` for linting and formatting. Run `make format` before committing.
-- **Frontend (TypeScript)**: We use ESLint and Prettier. Run `pnpm format:write` before committing.
-- CI enforces formatting — PRs with unformatted code will fail the lint check.
+- **Backend (Python)**: We use `ruff` for linting and formatting
+- **Frontend (TypeScript)**: We use ESLint and Prettier
 
 ## Documentation
 

Install.md

@@ -1,87 +0,0 @@
-# DeerFlow Install
-
-This file is for coding agents. If the DeerFlow repository is not already cloned and open, clone `https://github.com/bytedance/deer-flow.git` first, then continue from the repository root.
-
-## Goal
-
-Bootstrap a DeerFlow local development workspace on the user's machine with the least risky path available.
-
-Default preference:
-
-1. Docker development environment
-2. Local development environment
-
-Do not assume API keys or model credentials exist. Set up everything that can be prepared safely, then stop with a concise summary of what the user still needs to provide.
-
-## Operating Rules
-
-- Be idempotent. Re-running this document should not damage an existing setup.
-- Prefer existing repo commands over ad hoc shell commands.
-- Do not use `sudo` or install system packages without explicit user approval.
-- Do not overwrite existing user config values unless the user asks.
-- If a step fails, stop, explain the blocker, and provide the smallest next action.
-- If multiple setup paths are possible, prefer Docker when Docker is already available.
-
-## Success Criteria
-
-Consider the setup successful when all of the following are true:
-
-- The DeerFlow repository is cloned and the current working directory is the repo root.
-- `config.yaml` exists.
-- For Docker setup, `make docker-init` completed successfully and Docker prerequisites are prepared, but services are not assumed to be running yet.
-- For local setup, `make check` passed or reported no missing prerequisites, and `make install` completed successfully.
-- The user receives the exact next command to launch DeerFlow.
-- The user also receives any missing model configuration or referenced environment variable names from `config.yaml`, without inspecting secret-bearing files for actual values.
-
-## Steps
-
-- If the current directory is not the DeerFlow repository root, clone `https://github.com/bytedance/deer-flow.git` if needed, then change into the repository root.
-- Confirm the current directory is the DeerFlow repository root by checking that `Makefile`, `backend/`, `frontend/`, and `config.example.yaml` exist.
-- Detect whether `config.yaml` already exists.
-- If `config.yaml` does not exist, run `make config`.
-- Detect whether Docker is available and the daemon is reachable with `docker info`.
-- If Docker is available:
-  - Run `make docker-init`.
-  - Treat this as Docker prerequisite preparation only. Do not claim that app services, compose validation, or image builds have already succeeded.
-  - Do not start long-running services unless the user explicitly asks or this setup request clearly includes launch verification.
-  - Tell the user the recommended next command is `make docker-start`.
-- If Docker is not available:
-  - Run `make check`.
-  - If `make check` reports missing system dependencies such as `node`, `pnpm`, `uv`, or `nginx`, stop and report the missing tools instead of attempting privileged installs.
-  - If prerequisites are satisfied, run `make install`.
-  - Tell the user the recommended next command is `make dev`.
-- Inspect `config.yaml` only for missing model entries or referenced environment variable placeholders. Do not read `.env`, `frontend/.env`, or other secret-bearing files.
-- If no model is configured, tell the user they must add at least one entry under `models` in `config.yaml`.
-- If `config.yaml` references variables such as `$OPENAI_API_KEY`, tell the user which variable names still need real values, but do not verify them by opening secret-bearing files.
-- If the repository already appears configured, avoid repeating expensive work unless it is necessary to verify the environment.
-
-## Verification
-
-Use the lightest verification that matches the chosen setup path.
-
-For Docker setup:
-
-- Confirm `make docker-init` completed successfully.
-- Confirm `config.yaml` exists.
-- State explicitly that Docker services were not started and `make docker-start` is still the first real launch step.
-- Do not leave background services running unless the user asked for that.
-
-For local setup:
-
-- Confirm `make install` completed successfully.
-- Confirm `config.yaml` exists.
-- Do not leave background services running unless the user asked for that.
-
-## Final Response Format
-
-Return a short status report with:
-
-1. Setup path used: Docker or local
-2. Setup level reached: Docker prerequisites prepared or local dependencies installed
-3. Files created or detected: for example `config.yaml`
-4. Remaining user action: model config, env var values, auth files, or nothing
-5. Exact next command to start DeerFlow
-
-## EXECUTE NOW
-
-Complete the steps above. When finished, stop after the setup boundary and report status instead of continuing into unrelated project work.

Makefile

@@ -1,34 +1,19 @@
 # DeerFlow - Unified Development Environment
 
-.PHONY: help config config-upgrade check install dev dev-daemon start stop up down clean docker-init docker-start docker-stop docker-logs docker-logs-frontend docker-logs-gateway
-
-PYTHON ?= python
-BASH ?= bash
-
-# Detect OS for Windows compatibility
-ifeq ($(OS),Windows_NT)
-    SHELL := cmd.exe
-endif
+.PHONY: help config check install dev stop clean docker-init docker-start docker-stop docker-logs docker-logs-frontend docker-logs-gateway
 
 help:
 	@echo "DeerFlow Development Commands:"
 	@echo "  make config          - Generate local config files (aborts if config already exists)"
-	@echo "  make config-upgrade  - Merge new fields from config.example.yaml into config.yaml"
 	@echo "  make check           - Check if all required tools are installed"
 	@echo "  make install         - Install all dependencies (frontend + backend)"
 	@echo "  make setup-sandbox   - Pre-pull sandbox container image (recommended)"
-	@echo "  make dev             - Start all services in development mode (with hot-reloading)"
-	@echo "  make dev-daemon      - Start all services in background (daemon mode)"
-	@echo "  make start           - Start all services in production mode (optimized, no hot-reloading)"
+	@echo "  make dev             - Start all services (frontend + backend + nginx on localhost:2026)"
 	@echo "  make stop            - Stop all running services"
 	@echo "  make clean           - Clean up processes and temporary files"
 	@echo ""
-	@echo "Docker Production Commands:"
-	@echo "  make up              - Build and start production Docker services (localhost:2026)"
-	@echo "  make down            - Stop and remove production Docker containers"
-	@echo ""
 	@echo "Docker Development Commands:"
-	@echo "  make docker-init     - Pull the sandbox image"
+	@echo "  make docker-init     - Build the custom k3s image (with pre-cached sandbox image)"
 	@echo "  make docker-start    - Start Docker services (mode-aware from config.yaml, localhost:2026)"
 	@echo "  make docker-stop     - Stop Docker development services"
 	@echo "  make docker-logs     - View Docker development logs"
@@ -36,14 +21,88 @@ help:
 	@echo "  make docker-logs-gateway - View Docker gateway logs"
 
 config:
-	@$(PYTHON) ./scripts/configure.py
-
-config-upgrade:
-	@./scripts/config-upgrade.sh
+	@if [ -f config.yaml ] || [ -f config.yml ] || [ -f configure.yml ]; then \
+		echo "Error: configuration file already exists (config.yaml/config.yml/configure.yml). Aborting."; \
+		exit 1; \
+	fi
+	@cp config.example.yaml config.yaml
+	@test -f .env || cp .env.example .env
+	@test -f frontend/.env || cp frontend/.env.example frontend/.env
 
 # Check required tools
 check:
-	@$(PYTHON) ./scripts/check.py
+	@echo "=========================================="
+	@echo "  Checking Required Dependencies"
+	@echo "=========================================="
+	@echo ""
+	@FAILED=0; \
+	echo "Checking Node.js..."; \
+	if command -v node >/dev/null 2>&1; then \
+		NODE_VERSION=$$(node -v | sed 's/v//'); \
+		NODE_MAJOR=$$(echo $$NODE_VERSION | cut -d. -f1); \
+		if [ $$NODE_MAJOR -ge 22 ]; then \
+			echo "  ✓ Node.js $$NODE_VERSION (>= 22 required)"; \
+		else \
+			echo "  ✗ Node.js $$NODE_VERSION found, but version 22+ is required"; \
+			echo "    Install from: https://nodejs.org/"; \
+			FAILED=1; \
+		fi; \
+	else \
+		echo "  ✗ Node.js not found (version 22+ required)"; \
+		echo "    Install from: https://nodejs.org/"; \
+		FAILED=1; \
+	fi; \
+	echo ""; \
+	echo "Checking pnpm..."; \
+	if command -v pnpm >/dev/null 2>&1; then \
+		PNPM_VERSION=$$(pnpm -v); \
+		echo "  ✓ pnpm $$PNPM_VERSION"; \
+	else \
+		echo "  ✗ pnpm not found"; \
+		echo "    Install: npm install -g pnpm"; \
+		echo "    Or visit: https://pnpm.io/installation"; \
+		FAILED=1; \
+	fi; \
+	echo ""; \
+	echo "Checking uv..."; \
+	if command -v uv >/dev/null 2>&1; then \
+		UV_VERSION=$$(uv --version | awk '{print $$2}'); \
+		echo "  ✓ uv $$UV_VERSION"; \
+	else \
+		echo "  ✗ uv not found"; \
+		echo "    Install: curl -LsSf https://astral.sh/uv/install.sh | sh"; \
+		echo "    Or visit: https://docs.astral.sh/uv/getting-started/installation/"; \
+		FAILED=1; \
+	fi; \
+	echo ""; \
+	echo "Checking nginx..."; \
+	if command -v nginx >/dev/null 2>&1; then \
+		NGINX_VERSION=$$(nginx -v 2>&1 | awk -F'/' '{print $$2}'); \
+		echo "  ✓ nginx $$NGINX_VERSION"; \
+	else \
+		echo "  ✗ nginx not found"; \
+		echo "    macOS:   brew install nginx"; \
+		echo "    Ubuntu:  sudo apt install nginx"; \
+		echo "    Or visit: https://nginx.org/en/download.html"; \
+		FAILED=1; \
+	fi; \
+	echo ""; \
+	if [ $$FAILED -eq 0 ]; then \
+		echo "=========================================="; \
+		echo "  ✓ All dependencies are installed!"; \
+		echo "=========================================="; \
+		echo ""; \
+		echo "You can now run:"; \
+		echo "  make install  - Install project dependencies"; \
+		echo "  make dev      - Start development server"; \
+	else \
+		echo "=========================================="; \
+		echo "  ✗ Some dependencies are missing"; \
+		echo "=========================================="; \
+		echo ""; \
+		echo "Please install the missing tools and run 'make check' again."; \
+		exit 1; \
+	fi
 
 # Install all dependencies
 install:
@@ -81,48 +140,99 @@ setup-sandbox:
 	fi; \
 	if command -v docker >/dev/null 2>&1; then \
 		echo "Pulling image using Docker..."; \
-		if docker pull "$$IMAGE"; then \
-			echo ""; \
-			echo "✓ Sandbox image pulled successfully"; \
-		else \
-			echo ""; \
-			echo "⚠ Failed to pull sandbox image (this is OK for local sandbox mode)"; \
-		fi; \
+		docker pull "$$IMAGE"; \
+		echo ""; \
+		echo "✓ Sandbox image pulled successfully"; \
 	else \
 		echo "✗ Neither Docker nor Apple Container is available"; \
 		echo "  Please install Docker: https://docs.docker.com/get-docker/"; \
 		exit 1; \
 	fi
 
-# Start all services in development mode (with hot-reloading)
+# Start all services
 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 production mode (with optimizations)
-start:
-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 daemon mode (background)
-dev-daemon:
-	@./scripts/start-daemon.sh
+	@echo "Stopping existing services if any..."
+	@-pkill -f "langgraph dev" 2>/dev/null || true
+	@-pkill -f "uvicorn src.gateway.app:app" 2>/dev/null || true
+	@-pkill -f "next dev" 2>/dev/null || true
+	@-nginx -c $(PWD)/docker/nginx/nginx.local.conf -p $(PWD) -s quit 2>/dev/null || true
+	@sleep 1
+	@-pkill -9 nginx 2>/dev/null || true
+	@-./scripts/cleanup-containers.sh deer-flow-sandbox 2>/dev/null || true
+	@sleep 1
+	@echo ""
+	@echo "=========================================="
+	@echo "  Starting DeerFlow Development Server"
+	@echo "=========================================="
+	@echo ""
+	@echo "Services starting up..."
+	@echo "  → Backend: LangGraph + Gateway"
+	@echo "  → Frontend: Next.js"
+	@echo "  → Nginx: Reverse Proxy"
+	@echo ""
+	@cleanup() { \
+		trap - INT TERM; \
+		echo ""; \
+		echo "Shutting down services..."; \
+		pkill -f "langgraph dev" 2>/dev/null || true; \
+		pkill -f "uvicorn src.gateway.app:app" 2>/dev/null || true; \
+		pkill -f "next dev" 2>/dev/null || true; \
+		nginx -c $(PWD)/docker/nginx/nginx.local.conf -p $(PWD) -s quit 2>/dev/null || true; \
+		sleep 1; \
+		pkill -9 nginx 2>/dev/null || true; \
+		echo "Cleaning up sandbox containers..."; \
+		./scripts/cleanup-containers.sh deer-flow-sandbox 2>/dev/null || true; \
+		echo "✓ All services stopped"; \
+		exit 0; \
+	}; \
+	trap cleanup INT TERM; \
+	mkdir -p logs; \
+	echo "Starting LangGraph server..."; \
+	cd backend && NO_COLOR=1 uv run langgraph dev --no-browser --allow-blocking --no-reload > ../logs/langgraph.log 2>&1 & \
+	sleep 3; \
+	echo "✓ LangGraph server started on localhost:2024"; \
+	echo "Starting Gateway API..."; \
+	cd backend && uv run uvicorn src.gateway.app:app --host 0.0.0.0 --port 8001 > ../logs/gateway.log 2>&1 & \
+	sleep 3; \
+	if ! lsof -i :8001 -sTCP:LISTEN -t >/dev/null 2>&1; then \
+		echo "✗ Gateway API failed to start. Last log output:"; \
+		tail -30 logs/gateway.log; \
+		cleanup; \
+	fi; \
+	echo "✓ Gateway API started on localhost:8001"; \
+	echo "Starting Frontend..."; \
+	cd frontend && pnpm run dev > ../logs/frontend.log 2>&1 & \
+	sleep 3; \
+	echo "✓ Frontend started on localhost:3000"; \
+	echo "Starting Nginx reverse proxy..."; \
+	mkdir -p logs && nginx -g 'daemon off;' -c $(PWD)/docker/nginx/nginx.local.conf -p $(PWD) > logs/nginx.log 2>&1 & \
+	sleep 2; \
+	echo "✓ Nginx started on localhost:2026"; \
+	echo ""; \
+	echo "=========================================="; \
+	echo "  DeerFlow is ready!"; \
+	echo "=========================================="; \
+	echo ""; \
+	echo "  🌐 Application: http://localhost:2026"; \
+	echo "  📡 API Gateway: http://localhost:2026/api/*"; \
+	echo "  🤖 LangGraph:   http://localhost:2026/api/langgraph/*"; \
+	echo ""; \
+	echo "  📋 Logs:"; \
+	echo "     - LangGraph: logs/langgraph.log"; \
+	echo "     - Gateway:   logs/gateway.log"; \
+	echo "     - Frontend:  logs/frontend.log"; \
+	echo "     - Nginx:     logs/nginx.log"; \
+	echo ""; \
+	echo "Press Ctrl+C to stop all services"; \
+	echo ""; \
+	wait
 
 # Stop all services
 stop:
 	@echo "Stopping all services..."
 	@-pkill -f "langgraph dev" 2>/dev/null || true
-	@-pkill -f "uvicorn app.gateway.app:app" 2>/dev/null || true
+	@-pkill -f "uvicorn src.gateway.app:app" 2>/dev/null || true
 	@-pkill -f "next dev" 2>/dev/null || true
-	@-pkill -f "next start" 2>/dev/null || true
-	@-pkill -f "next-server" 2>/dev/null || true
-	@-pkill -f "next-server" 2>/dev/null || true
 	@-nginx -c $(PWD)/docker/nginx/nginx.local.conf -p $(PWD) -s quit 2>/dev/null || true
 	@sleep 1
 	@-pkill -9 nginx 2>/dev/null || true
@@ -133,8 +243,6 @@ stop:
 # Clean up
 clean: stop
 	@echo "Cleaning up..."
-	@-rm -rf backend/.deer-flow 2>/dev/null || true
-	@-rm -rf backend/.langgraph_api 2>/dev/null || true
 	@-rm -rf logs/*.log 2>/dev/null || true
 	@echo "✓ Cleanup complete"
 
@@ -162,16 +270,4 @@ docker-logs:
 docker-logs-frontend:
 	@./scripts/docker.sh logs --frontend
 docker-logs-gateway:
-	@./scripts/docker.sh logs --gateway
-
-# ==========================================
-# Production Docker Commands
-# ==========================================
-
-# Build and start production services
-up:
-	@./scripts/deploy.sh
-
-# Stop and remove production containers
-down:
-	@./scripts/deploy.sh down
+	@./scripts/docker.sh logs --gateway

README.md

@@ -1,11 +1,5 @@
 # 🦌 DeerFlow - 2.0
 
-English | [中文](./README_zh.md) | [日本語](./README_ja.md) | [Français](./README_fr.md) | [Русский](./README_ru.md)
-
-[![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)](./backend/pyproject.toml)
-[![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?logo=node.js&logoColor=white)](./Makefile)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-
 <a href="https://trendshift.io/repositories/14699" target="_blank"><img src="https://trendshift.io/api/badge/repositories/14699" alt="bytedance%2Fdeer-flow | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 > On February 28th, 2026, DeerFlow claimed the 🏆 #1 spot on GitHub Trending following the launch of version 2. Thanks a million to our incredible community — you made this happen! 💪🔥
 
@@ -18,27 +12,9 @@ https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18
 
 ## Official Website
 
-[<img width="2880" height="1600" alt="image" src="https://github.com/user-attachments/assets/a598c49f-3b2f-41ea-a052-05e21349188a" />](https://deerflow.tech)
+Learn more and see **real demos** on our official website.
 
-Learn more and see **real demos** on our [**official website**](https://deerflow.tech).
-
-## Coding Plan from ByteDance Volcengine
-
-<img width="4808" height="2400" alt="英文方舟" src="https://github.com/user-attachments/assets/2ecc7b9d-50be-4185-b1f7-5542d222fb2d" />
-
-- We strongly recommend using Doubao-Seed-2.0-Code, DeepSeek v3.2 and Kimi 2.5 to run DeerFlow
-- [Learn more](https://www.byteplus.com/en/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
-- [中国大陆地区的开发者请点击这里](https://www.volcengine.com/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
-
-## InfoQuest
-
-DeerFlow has newly integrated the intelligent search and crawling toolset independently developed by BytePlus--[InfoQuest (supports free online experience)](https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest)
-
-<a href="https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest" target="_blank">
-  <img
-    src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/hubseh7bsbps/20251208-160108.png"   alt="InfoQuest_banner"
-  />
-</a>
+**[deerflow.tech](https://deerflow.tech/)**
 
 ---
 
@@ -46,9 +22,7 @@ DeerFlow has newly integrated the intelligent search and crawling toolset indepe
 
 - [🦌 DeerFlow - 2.0](#-deerflow---20)
   - [Official Website](#official-website)
-  - [InfoQuest](#infoquest)
   - [Table of Contents](#table-of-contents)
-  - [One-Line Agent Setup](#one-line-agent-setup)
   - [Quick Start](#quick-start)
     - [Configuration](#configuration)
     - [Running the Application](#running-the-application)
@@ -57,36 +31,21 @@ DeerFlow has newly integrated the intelligent search and crawling toolset indepe
     - [Advanced](#advanced)
       - [Sandbox Mode](#sandbox-mode)
       - [MCP Server](#mcp-server)
-      - [IM Channels](#im-channels)
-      - [LangSmith Tracing](#langsmith-tracing)
   - [From Deep Research to Super Agent Harness](#from-deep-research-to-super-agent-harness)
   - [Core Features](#core-features)
     - [Skills \& Tools](#skills--tools)
-      - [Claude Code Integration](#claude-code-integration)
     - [Sub-Agents](#sub-agents)
     - [Sandbox \& File System](#sandbox--file-system)
     - [Context Engineering](#context-engineering)
     - [Long-Term Memory](#long-term-memory)
   - [Recommended Models](#recommended-models)
-  - [Embedded Python Client](#embedded-python-client)
   - [Documentation](#documentation)
-  - [⚠️ Security Notice](#️-security-notice)
   - [Contributing](#contributing)
   - [License](#license)
   - [Acknowledgments](#acknowledgments)
     - [Key Contributors](#key-contributors)
   - [Star History](#star-history)
 
-## One-Line Agent Setup
-
-If you use Claude Code, Codex, Cursor, Windsurf, or another coding agent, you can hand it the setup instructions in one sentence:
-
-```text
-Help me clone DeerFlow if needed, then bootstrap it for local development by following https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md
-```
-
-That prompt is intended for coding agents. It tells the agent to clone the repo if needed, choose Docker when available, and stop with the exact next command plus any missing config the user still needs to provide.
-
 ## Quick Start
 
 ### Configuration
@@ -121,56 +80,9 @@ That prompt is intended for coding agents. It tells the agent to clone the repo
        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: $OPENAI_API_KEY          # OpenRouter still uses the OpenAI-compatible field name here
-       base_url: https://openrouter.ai/api/v1
-
-     - name: gpt-5-responses
-       display_name: GPT-5 (Responses API)
-       use: langchain_openai:ChatOpenAI
-       model: gpt-5
-       api_key: $OPENAI_API_KEY
-       use_responses_api: true
-       output_version: responses/v1
    ```
 
-   OpenRouter and similar OpenAI-compatible gateways should be configured with `langchain_openai:ChatOpenAI` plus `base_url`. If you prefer a provider-specific environment variable name, point `api_key` at that variable explicitly (for example `api_key: $OPENROUTER_API_KEY`).
-
-   To route OpenAI models through `/v1/responses`, keep using `langchain_openai:ChatOpenAI` and set `use_responses_api: true` with `output_version: responses/v1`.
-
-   CLI-backed provider examples:
-
-   ```yaml
-   models:
-     - name: gpt-5.4
-       display_name: GPT-5.4 (Codex CLI)
-       use: deerflow.models.openai_codex_provider:CodexChatModel
-       model: gpt-5.4
-       supports_thinking: true
-       supports_reasoning_effort: true
-
-     - name: claude-sonnet-4.6
-       display_name: Claude Sonnet 4.6 (Claude Code OAuth)
-       use: deerflow.models.claude_provider:ClaudeChatModel
-       model: claude-sonnet-4-6
-       max_tokens: 4096
-       supports_thinking: true
-   ```
-
-   - Codex CLI reads `~/.codex/auth.json`
-   - 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:
@@ -181,9 +93,7 @@ That prompt is intended for coding agents. It tells the agent to clone the repo
    ```bash
    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
    ```
 
 - Option B: Export environment variables in your shell
@@ -192,10 +102,6 @@ That prompt is intended for coding agents. It tells the agent to clone the repo
    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
@@ -208,33 +114,17 @@ That prompt is intended for coding agents. It tells the agent to clone the repo
 
 #### Option 1: Docker (Recommended)
 
-**Development** (hot-reload, source mounts):
+The fastest way to get started with a consistent environment:
 
-```bash
-make docker-init    # Pull sandbox image (only once or when image updates)
-make docker-start   # Start services (auto-detects sandbox mode from config.yaml)
-```
+1. **Initialize and start**:
+   ```bash
+   make docker-init    # Pull sandbox image (Only once or when image updates)
+   make docker-start   # Start services (auto-detects sandbox mode from config.yaml)
+   ```
 
-`make docker-start` starts `provisioner` only when `config.yaml` uses provisioner mode (`sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider` with `provisioner_url`).
+   `make docker-start` now starts `provisioner` only when `config.yaml` uses provisioner mode (`sandbox.use: src.community.aio_sandbox:AioSandboxProvider` with `provisioner_url`).
 
-Docker builds use the upstream `uv` registry by default. If you need faster mirrors in restricted networks, export `UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple` and `NPM_REGISTRY=https://registry.npmmirror.com` before running `make docker-init` or `make docker-start`.
-
-Backend processes automatically pick up `config.yaml` changes on the next config access, so model metadata updates do not require a manual restart during development.
-
-> [!TIP]
-> On Linux, if Docker-based commands fail with `permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock`, add your user to the `docker` group and re-login before retrying. See [CONTRIBUTING.md](CONTRIBUTING.md#linux-docker-daemon-permission-denied) for the full fix.
-
-**Production** (builds images locally, mounts runtime config and data):
-
-```bash
-make up     # Build images and start all production services
-make down   # Stop and remove containers
-```
-
-> [!NOTE]
-> The LangGraph agent server currently runs via `langgraph dev` (the open-source CLI server).
-
-Access: http://localhost:2026
+2. **Access**: http://localhost:2026
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed Docker development guide.
 
@@ -242,8 +132,6 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed Docker development guide.
 
 If you prefer running services locally:
 
-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`).
-
 1. **Check prerequisites**:
    ```bash
    make check  # Verifies Node.js 22+, pnpm, uv, nginx
@@ -260,19 +148,12 @@ Prerequisite: complete the "Configuration" steps above first (`make config` and
    make setup-sandbox
    ```
 
-4. **(Optional) Load sample memory data for local review**:
-   ```bash
-   python scripts/load_memory_sample.py
-   ```
-   This copies the sample fixture into the default local runtime memory file so reviewers can immediately test `Settings > Memory`.
-   See [backend/docs/MEMORY_SETTINGS_REVIEW.md](backend/docs/MEMORY_SETTINGS_REVIEW.md) for the shortest review flow.
-
-5. **Start services**:
+4. **Start services**:
    ```bash
    make dev
    ```
 
-6. **Access**: http://localhost:2026
+5. **Access**: http://localhost:2026
 
 ### Advanced
 #### Sandbox Mode
@@ -292,138 +173,6 @@ DeerFlow supports configurable MCP servers and skills to extend its capabilities
 For HTTP/SSE MCP servers, OAuth token flows are supported (`client_credentials`, `refresh_token`).
 See the [MCP Server Guide](backend/docs/MCP_SERVER.md) for detailed instructions.
 
-#### IM Channels
-
-DeerFlow supports receiving tasks from messaging apps. Channels auto-start when configured — no public IP required for any of them.
-
-| Channel | Transport | Difficulty |
-|---------|-----------|------------|
-| Telegram | Bot API (long-polling) | Easy |
-| Slack | Socket Mode | Moderate |
-| Feishu / Lark | WebSocket | Moderate |
-
-**Configuration in `config.yaml`:**
-
-```yaml
-channels:
-  # LangGraph Server URL (default: http://localhost:2024)
-  langgraph_url: http://localhost:2024
-  # Gateway API URL (default: http://localhost:8001)
-  gateway_url: http://localhost:8001
-
-  # Optional: global session defaults for all mobile channels
-  session:
-    assistant_id: lead_agent  # or a custom agent name; custom agents are routed via lead_agent + agent_name
-    config:
-      recursion_limit: 100
-    context:
-      thinking_enabled: true
-      is_plan_mode: false
-      subagent_enabled: false
-
-  feishu:
-    enabled: true
-    app_id: $FEISHU_APP_ID
-    app_secret: $FEISHU_APP_SECRET
-    # domain: https://open.feishu.cn       # China (default)
-    # domain: https://open.larksuite.com   # International
-
-  slack:
-    enabled: true
-    bot_token: $SLACK_BOT_TOKEN     # xoxb-...
-    app_token: $SLACK_APP_TOKEN     # xapp-... (Socket Mode)
-    allowed_users: []               # empty = allow all
-
-  telegram:
-    enabled: true
-    bot_token: $TELEGRAM_BOT_TOKEN
-    allowed_users: []               # empty = allow all
-
-    # Optional: per-channel / per-user session settings
-    session:
-      assistant_id: mobile-agent  # custom agent names are also supported here
-      context:
-        thinking_enabled: false
-      users:
-        "123456789":
-          assistant_id: vip-agent
-          config:
-            recursion_limit: 150
-          context:
-            thinking_enabled: true
-            subagent_enabled: true
-```
-
-Notes:
-- `assistant_id: lead_agent` calls the default LangGraph assistant directly.
-- If `assistant_id` is set to a custom agent name, DeerFlow still routes through `lead_agent` and injects that value as `agent_name`, so the custom agent's SOUL/config takes effect for IM channels.
-
-Set the corresponding API keys in your `.env` file:
-
-```bash
-# Telegram
-TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
-
-# Slack
-SLACK_BOT_TOKEN=xoxb-...
-SLACK_APP_TOKEN=xapp-...
-
-# Feishu / Lark
-FEISHU_APP_ID=cli_xxxx
-FEISHU_APP_SECRET=your_app_secret
-```
-
-**Telegram Setup**
-
-1. Chat with [@BotFather](https://t.me/BotFather), send `/newbot`, and copy the HTTP API token.
-2. Set `TELEGRAM_BOT_TOKEN` in `.env` and enable the channel in `config.yaml`.
-
-**Slack Setup**
-
-1. Create a Slack App at [api.slack.com/apps](https://api.slack.com/apps) → Create New App → From scratch.
-2. Under **OAuth & Permissions**, add Bot Token Scopes: `app_mentions:read`, `chat:write`, `im:history`, `im:read`, `im:write`, `files:write`.
-3. Enable **Socket Mode** → generate an App-Level Token (`xapp-…`) with `connections:write` scope.
-4. Under **Event Subscriptions**, subscribe to bot events: `app_mention`, `message.im`.
-5. Set `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN` in `.env` and enable the channel in `config.yaml`.
-
-**Feishu / Lark Setup**
-
-1. Create an app on [Feishu Open Platform](https://open.feishu.cn/) → enable **Bot** capability.
-2. Add permissions: `im:message`, `im:message.p2p_msg:readonly`, `im:resource`.
-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`.
-
-When DeerFlow runs in Docker Compose, IM channels execute inside the `gateway` container. In that case, do not point `channels.langgraph_url` or `channels.gateway_url` at `localhost`; use container service names such as `http://langgraph:2024` and `http://gateway:8001`, or set `DEER_FLOW_CHANNELS_LANGGRAPH_URL` and `DEER_FLOW_CHANNELS_GATEWAY_URL`.
-
-**Commands**
-
-Once a channel is connected, you can interact with DeerFlow directly from the chat:
-
-| Command | Description |
-|---------|-------------|
-| `/new` | Start a new conversation |
-| `/status` | Show current thread info |
-| `/models` | List available models |
-| `/memory` | View memory |
-| `/help` | Show help |
-
-> Messages without a command prefix are treated as regular chat — DeerFlow creates a thread and responds conversationally.
-
-#### LangSmith Tracing
-
-DeerFlow has built-in [LangSmith](https://smith.langchain.com) integration for observability. When enabled, all LLM calls, agent runs, and tool executions are traced and visible in the LangSmith dashboard.
-
-Add the following to your `.env` file:
-
-```bash
-LANGSMITH_TRACING=true
-LANGSMITH_ENDPOINT=https://api.smith.langchain.com
-LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
-LANGSMITH_PROJECT=xxx
-```
-
-For Docker deployments, tracing is disabled by default. Set `LANGSMITH_TRACING=true` and `LANGSMITH_API_KEY` in your `.env` to enable it.
-
 ## From Deep Research to Super Agent Harness
 
 DeerFlow started as a Deep Research framework — and the community ran with it. Since launch, developers have pushed it far beyond research: building data pipelines, generating slide decks, spinning up dashboards, automating content workflows. Things we never anticipated.
@@ -432,7 +181,7 @@ That told us something important: DeerFlow wasn't just a research tool. It was a
 
 So we rebuilt it from scratch.
 
-DeerFlow 2.0 is no longer a framework you wire together. It's a super agent harness — batteries included, fully extensible. Built on LangGraph and LangChain, it ships with everything an agent needs out of the box: a filesystem, memory, skills, sandbox-aware execution, and the ability to plan and spawn sub-agents for complex, multi-step tasks.
+DeerFlow 2.0 is no longer a framework you wire together. It's a super agent harness — batteries included, fully extensible. Built on LangGraph and LangChain, it ships with everything an agent needs out of the box: a filesystem, memory, skills, sandboxed execution, and the ability to plan and spawn sub-agents for complex, multi-step tasks.
 
 Use it as-is. Or tear it apart and make it yours.
 
@@ -446,12 +195,8 @@ A standard Agent Skill is a structured capability module — a Markdown file tha
 
 Skills are loaded progressively — only when the task needs them, not all at once. This keeps the context window lean and makes DeerFlow work well even with token-sensitive models.
 
-When you install `.skill` archives through the Gateway, DeerFlow accepts standard optional frontmatter metadata such as `version`, `author`, and `compatibility` instead of rejecting otherwise valid external skills.
-
 Tools follow the same philosophy. DeerFlow comes with a core toolset — web search, web fetch, file operations, bash execution — and supports custom tools via MCP servers and Python functions. Swap anything. Add anything.
 
-Gateway-generated follow-up suggestions now normalize both plain-string model output and block/list-style rich content before parsing the JSON array response, so provider-specific content wrappers do not silently drop suggestions.
-
 ```
 # Paths inside the sandbox container
 /mnt/skills/public
@@ -465,35 +210,6 @@ Gateway-generated follow-up suggestions now normalize both plain-string model ou
 └── your-custom-skill/SKILL.md      ← yours
 ```
 
-#### Claude Code Integration
-
-The `claude-to-deerflow` skill lets you interact with a running DeerFlow instance directly from [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Send research tasks, check status, manage threads — all without leaving the terminal.
-
-**Install the skill**:
-
-```bash
-npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow
-```
-
-Then make sure DeerFlow is running (default at `http://localhost:2026`) and use the `/claude-to-deerflow` command in Claude Code.
-
-**What you can do**:
-- Send messages to DeerFlow and get streaming responses
-- Choose execution modes: flash (fast), standard, pro (planning), ultra (sub-agents)
-- Check DeerFlow health, list models/skills/agents
-- Manage threads and conversation history
-- Upload files for analysis
-
-**Environment variables** (optional, for custom endpoints):
-
-```bash
-DEERFLOW_URL=http://localhost:2026            # Unified proxy base URL
-DEERFLOW_GATEWAY_URL=http://localhost:2026    # Gateway API
-DEERFLOW_LANGGRAPH_URL=http://localhost:2026/api/langgraph  # LangGraph API
-```
-
-See [`skills/public/claude-to-deerflow/SKILL.md`](skills/public/claude-to-deerflow/SKILL.md) for the full API reference.
-
 ### Sub-Agents
 
 Complex tasks rarely fit in a single pass. DeerFlow decomposes them.
@@ -506,9 +222,7 @@ This is how DeerFlow handles tasks that take minutes to hours: a research task m
 
 DeerFlow doesn't just *talk* about doing things. It has its own computer.
 
-Each task gets its own execution environment with a full filesystem view — skills, workspace, uploads, outputs. The agent reads, writes, and edits files. It can view images and, when configured safely, execute shell commands.
-
-With `AioSandboxProvider`, shell execution runs inside isolated containers. With `LocalSandboxProvider`, file tools still map to per-thread directories on the host, but host `bash` is disabled by default because it is not a secure isolation boundary. Re-enable host bash only for fully trusted local workflows.
+Each task runs inside an isolated Docker container with a full filesystem — skills, workspace, uploads, outputs. The agent reads, writes, and edits files. It executes bash commands and codes. It views images. All sandboxed, all auditable, zero contamination between sessions.
 
 This is the difference between a chatbot with tool access and an agent with an actual execution environment.
 
@@ -532,8 +246,6 @@ Most agents forget everything the moment a conversation ends. DeerFlow remembers
 
 Across sessions, DeerFlow builds a persistent memory of your profile, preferences, and accumulated knowledge. The more you use it, the better it knows you — your writing style, your technical stack, your recurring workflows. Memory is stored locally and stays under your control.
 
-Memory updates now skip duplicate fact entries at apply time, so repeated preferences and context do not accumulate endlessly across sessions.
-
 ## Recommended Models
 
 DeerFlow is model-agnostic — it works with any LLM that implements the OpenAI-compatible API. That said, it performs best with models that support:
@@ -545,10 +257,10 @@ DeerFlow is model-agnostic — it works with any LLM that implements the OpenAI-
 
 ## Embedded Python Client
 
-DeerFlow can be used as an embedded Python library without running the full HTTP services. The `DeerFlowClient` provides direct in-process access to all agent and Gateway capabilities, returning the same response schemas as the HTTP Gateway API. The HTTP Gateway also exposes `DELETE /api/threads/{thread_id}` to remove DeerFlow-managed local thread data after the LangGraph thread itself has been deleted:
+DeerFlow can be used as an embedded Python library without running the full HTTP services. The `DeerFlowClient` provides direct in-process access to all agent and Gateway capabilities, returning the same response schemas as the HTTP Gateway API:
 
 ```python
-from deerflow.client import DeerFlowClient
+from src.client import DeerFlowClient
 
 client = DeerFlowClient()
 
@@ -567,7 +279,7 @@ client.update_skill("web-search", enabled=True)
 client.upload_files("thread-1", ["./report.pdf"])  # {"success": True, "files": [...]}
 ```
 
-All dict-returning methods are validated against Gateway Pydantic response models in CI (`TestGatewayConformance`), ensuring the embedded client stays in sync with the HTTP API schemas. See `backend/packages/harness/deerflow/client.py` for full API documentation.
+All dict-returning methods are validated against Gateway Pydantic response models in CI (`TestGatewayConformance`), ensuring the embedded client stays in sync with the HTTP API schemas. See `backend/src/client.py` for full API documentation.
 
 ## Documentation
 
@@ -576,30 +288,11 @@ All dict-returning methods are validated against Gateway Pydantic response model
 - [Architecture Overview](backend/CLAUDE.md) - Technical architecture details
 - [Backend Architecture](backend/README.md) - Backend architecture and API reference
 
-## ⚠️ Security Notice
-
-### Improper Deployment May Introduce Security Risks
-
-DeerFlow has key high-privilege capabilities including **system command execution, resource operations, and business logic invocation**, and is designed by default to be **deployed in a local trusted environment (accessible only via the 127.0.0.1 loopback interface)**. If you deploy the agent in untrusted environments — such as LAN networks, public cloud servers, or other multi-endpoint accessible environments — without strict security measures, it may introduce security risks, including:
-
-- **Unauthorized illegal invocation**: Agent functionality could be discovered by unauthorized third parties or malicious internet scanners, triggering bulk unauthorized requests that execute high-risk operations such as system commands and file read/write, potentially causing serious security consequences.
-- **Compliance and legal risks**: If the agent is illegally invoked to conduct cyberattacks, data theft, or other illegal activities, it may result in legal liability and compliance risks.
-
-### Security Recommendations
-
-**Note: We strongly recommend deploying DeerFlow in a local trusted network environment.** If you need cross-device or cross-network deployment, you must implement strict security measures, such as:
-
-- **IP allowlist**: Use `iptables`, or deploy hardware firewalls / switches with Access Control Lists (ACL), to **configure IP allowlist rules** and deny access from all other IP addresses.
-- **Authentication gateway**: Configure a reverse proxy (e.g., nginx) and **enable strong pre-authentication**, blocking any unauthenticated access.
-- **Network isolation**: Where possible, place the agent and trusted devices in the **same dedicated VLAN**, isolated from other network devices.
-- **Stay updated**: Continue to follow DeerFlow's security feature updates.
-
 ## Contributing
 
 We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, workflow, and guidelines.
 
 Regression coverage includes Docker sandbox mode detection and provisioner kubeconfig-path handling tests in `backend/tests/`.
-Gateway artifact serving now forces active web content types (`text/html`, `application/xhtml+xml`, `image/svg+xml`) to download as attachments instead of inline rendering, reducing XSS risk for generated artifacts.
 
 ## License
 

README_fr.md

@@ -1,610 +0,0 @@
-# 🦌 DeerFlow - 2.0
-
-[English](./README.md) | [中文](./README_zh.md) | [日本語](./README_ja.md) | Français | [Русский](./README_ru.md)
-
-[![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)](./backend/pyproject.toml)
-[![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?logo=node.js&logoColor=white)](./Makefile)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-
-<a href="https://trendshift.io/repositories/14699" target="_blank"><img src="https://trendshift.io/api/badge/repositories/14699" alt="bytedance%2Fdeer-flow | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
-> Le 28 février 2026, DeerFlow a décroché la 🏆 1re place sur GitHub Trending suite au lancement de la version 2. Un immense merci à notre incroyable communauté — c'est grâce à vous ! 💪🔥
-
-DeerFlow (**D**eep **E**xploration and **E**fficient **R**esearch **Flow**) est un **super agent harness** open source qui orchestre des **sub-agents**, de la **mémoire** et des **sandboxes** pour accomplir pratiquement n'importe quelle tâche — le tout propulsé par des **skills extensibles**.
-
-https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18
-
-> [!NOTE]
-> **DeerFlow 2.0 est une réécriture complète.** Il ne partage aucun code avec la v1. Si vous cherchez le framework Deep Research original, il est maintenu sur la [branche `1.x`](https://github.com/bytedance/deer-flow/tree/main-1.x) — les contributions y sont toujours les bienvenues. Le développement actif a migré vers la 2.0.
-
-## Site officiel
-
-[<img width="2880" height="1600" alt="image" src="https://github.com/user-attachments/assets/a598c49f-3b2f-41ea-a052-05e21349188a" />](https://deerflow.tech)
-
-Découvrez-en plus et regardez des **démos réelles** sur notre [**site officiel**](https://deerflow.tech).
-
-## Coding Plan de ByteDance Volcengine
-
-<img width="4808" height="2400" alt="英文方舟" src="https://github.com/user-attachments/assets/2ecc7b9d-50be-4185-b1f7-5542d222fb2d" />
-
-- Nous recommandons fortement d'utiliser Doubao-Seed-2.0-Code, DeepSeek v3.2 et Kimi 2.5 pour exécuter DeerFlow
-- [En savoir plus](https://www.byteplus.com/en/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
-- [Développeurs en Chine continentale, cliquez ici](https://www.volcengine.com/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
-
-## InfoQuest
-
-DeerFlow intègre désormais le toolkit de recherche et de crawling intelligent développé par BytePlus — [InfoQuest (essai gratuit en ligne)](https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest)
-
-<a href="https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest" target="_blank">
-  <img
-    src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/hubseh7bsbps/20251208-160108.png"   alt="InfoQuest_banner"
-  />
-</a>
-
----
-
-## Table des matières
-
-- [🦌 DeerFlow - 2.0](#-deerflow---20)
-  - [Site officiel](#site-officiel)
-  - [InfoQuest](#infoquest)
-  - [Table des matières](#table-des-matières)
-  - [Installation en une phrase pour un coding agent](#installation-en-une-phrase-pour-un-coding-agent)
-  - [Démarrage rapide](#démarrage-rapide)
-    - [Configuration](#configuration)
-    - [Lancer l'application](#lancer-lapplication)
-      - [Option 1 : Docker (recommandé)](#option-1--docker-recommandé)
-      - [Option 2 : Développement local](#option-2--développement-local)
-    - [Avancé](#avancé)
-      - [Mode Sandbox](#mode-sandbox)
-      - [Serveur MCP](#serveur-mcp)
-      - [Canaux de messagerie](#canaux-de-messagerie)
-      - [Traçage LangSmith](#traçage-langsmith)
-  - [Du Deep Research au Super Agent Harness](#du-deep-research-au-super-agent-harness)
-  - [Fonctionnalités principales](#fonctionnalités-principales)
-    - [Skills et outils](#skills-et-outils)
-      - [Intégration Claude Code](#intégration-claude-code)
-    - [Sub-Agents](#sub-agents)
-    - [Sandbox et système de fichiers](#sandbox-et-système-de-fichiers)
-    - [Context Engineering](#context-engineering)
-    - [Mémoire à long terme](#mémoire-à-long-terme)
-  - [Modèles recommandés](#modèles-recommandés)
-  - [Client Python intégré](#client-python-intégré)
-  - [Documentation](#documentation)
-  - [⚠️ Avertissement de sécurité](#️-avertissement-de-sécurité)
-  - [Contribuer](#contribuer)
-  - [Licence](#licence)
-  - [Remerciements](#remerciements)
-    - [Contributeurs principaux](#contributeurs-principaux)
-  - [Star History](#star-history)
-
-## Installation en une phrase pour un coding agent
-
-Si vous utilisez Claude Code, Codex, Cursor, Windsurf ou un autre coding agent, vous pouvez simplement lui envoyer cette phrase :
-
-```text
-Aide-moi à cloner DeerFlow si nécessaire, puis à initialiser son environnement de développement local en suivant https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md
-```
-
-Ce prompt est destiné aux coding agents. Il leur demande de cloner le dépôt si nécessaire, de privilégier Docker quand il est disponible, puis de s'arrêter avec la commande exacte pour lancer DeerFlow et la liste des configurations encore manquantes.
-
-## Démarrage rapide
-
-### Configuration
-
-1. **Cloner le dépôt DeerFlow**
-
-   ```bash
-   git clone https://github.com/bytedance/deer-flow.git
-   cd deer-flow
-   ```
-
-2. **Générer les fichiers de configuration locaux**
-
-   Depuis le répertoire racine du projet (`deer-flow/`), exécutez :
-
-   ```bash
-   make config
-   ```
-
-   Cette commande crée les fichiers de configuration locaux à partir des templates fournis.
-
-3. **Configurer le(s) modèle(s) de votre choix**
-
-   Éditez `config.yaml` et définissez au moins un modèle :
-
-   ```yaml
-   models:
-     - 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: $OPENAI_API_KEY          # OpenRouter still uses the OpenAI-compatible field name here
-       base_url: https://openrouter.ai/api/v1
-
-     - name: gpt-5-responses
-       display_name: GPT-5 (Responses API)
-       use: langchain_openai:ChatOpenAI
-       model: gpt-5
-       api_key: $OPENAI_API_KEY
-       use_responses_api: true
-       output_version: responses/v1
-   ```
-
-   OpenRouter et les passerelles compatibles OpenAI similaires doivent être configurés avec `langchain_openai:ChatOpenAI` et `base_url`. Si vous préférez utiliser un nom de variable d'environnement propre au fournisseur, pointez `api_key` vers cette variable explicitement (par exemple `api_key: $OPENROUTER_API_KEY`).
-
-   Pour router les modèles OpenAI via `/v1/responses`, continuez d'utiliser `langchain_openai:ChatOpenAI` et définissez `use_responses_api: true` avec `output_version: responses/v1`.
-
-   Exemples de providers basés sur un CLI :
-
-   ```yaml
-   models:
-     - name: gpt-5.4
-       display_name: GPT-5.4 (Codex CLI)
-       use: deerflow.models.openai_codex_provider:CodexChatModel
-       model: gpt-5.4
-       supports_thinking: true
-       supports_reasoning_effort: true
-
-     - name: claude-sonnet-4.6
-       display_name: Claude Sonnet 4.6 (Claude Code OAuth)
-       use: deerflow.models.claude_provider:ClaudeChatModel
-       model: claude-sonnet-4-6
-       max_tokens: 4096
-       supports_thinking: true
-   ```
-
-   - Codex CLI lit `~/.codex/auth.json`
-   - L'endpoint Responses de Codex rejette actuellement `max_tokens` et `max_output_tokens`, donc `CodexChatModel` n'expose pas de limite de tokens par requête
-   - Claude Code accepte `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR`, `CLAUDE_CODE_CREDENTIALS_PATH`, ou en clair `~/.claude/.credentials.json`
-   - Sur macOS, DeerFlow ne sonde pas le Keychain automatiquement. Exportez l'auth Claude Code explicitement si nécessaire :
-
-   ```bash
-   eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"
-   ```
-
-4. **Définir les clés API pour le(s) modèle(s) configuré(s)**
-
-   Choisissez l'une des méthodes suivantes :
-
-- Option A : Éditer le fichier `.env` à la racine du projet (recommandé)
-
-
-   ```bash
-   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
-   ```
-
-- Option B : Exporter les variables d'environnement dans votre shell
-
-   ```bash
-   export OPENAI_API_KEY=your-openai-api-key
-   ```
-
-   Pour les providers basés sur un CLI :
-   - Codex CLI : `~/.codex/auth.json`
-   - Claude Code OAuth : handoff explicite via env/fichier ou `~/.claude/.credentials.json`
-
-- Option C : Éditer `config.yaml` directement (non recommandé en production)
-
-   ```yaml
-   models:
-     - name: gpt-4
-       api_key: your-actual-api-key-here  # Replace placeholder
-   ```
-
-### Lancer l'application
-
-#### Option 1 : Docker (recommandé)
-
-**Développement** (hot-reload, montage des sources) :
-
-```bash
-make docker-init    # Pull sandbox image (only once or when image updates)
-make docker-start   # Start services (auto-detects sandbox mode from config.yaml)
-```
-
-`make docker-start` ne lance `provisioner` que si `config.yaml` utilise le mode provisioner (`sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider` avec `provisioner_url`).
-Les processus backend récupèrent automatiquement les changements dans `config.yaml` au prochain accès à la configuration, donc les mises à jour de métadonnées des modèles ne nécessitent pas de redémarrage manuel en développement.
-
-> [!TIP]
-> Sous Linux, si les commandes Docker échouent avec `permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock`, ajoutez votre utilisateur au groupe `docker` et reconnectez-vous avant de réessayer. Voir [CONTRIBUTING.md](CONTRIBUTING.md#linux-docker-daemon-permission-denied) pour la solution complète.
-
-**Production** (build des images en local, montage de la config et des données) :
-
-```bash
-make up     # Build images and start all production services
-make down   # Stop and remove containers
-```
-
-> [!NOTE]
-> Le serveur d'agents LangGraph fonctionne actuellement via `langgraph dev` (le serveur CLI open source).
-
-Accès : http://localhost:2026
-
-Voir [CONTRIBUTING.md](CONTRIBUTING.md) pour le guide complet de développement avec Docker.
-
-#### Option 2 : Développement local
-
-Si vous préférez lancer les services en local :
-
-Prérequis : complétez d'abord les étapes de « Configuration » ci-dessus (`make config` et clés API des modèles). `make dev` nécessite un fichier de configuration valide (par défaut `config.yaml` à la racine du projet ; modifiable via `DEER_FLOW_CONFIG_PATH`).
-
-1. **Vérifier les prérequis** :
-   ```bash
-   make check  # Verifies Node.js 22+, pnpm, uv, nginx
-   ```
-
-2. **Installer les dépendances** :
-   ```bash
-   make install  # Install backend + frontend dependencies
-   ```
-
-3. **(Optionnel) Pré-télécharger l'image sandbox** :
-   ```bash
-   # Recommended if using Docker/Container-based sandbox
-   make setup-sandbox
-   ```
-
-4. **Démarrer les services** :
-   ```bash
-   make dev
-   ```
-
-5. **Accès** : http://localhost:2026
-
-### Avancé
-#### Mode Sandbox
-
-DeerFlow supporte plusieurs modes d'exécution sandbox :
-- **Exécution locale** (exécute le code sandbox directement sur la machine hôte)
-- **Exécution Docker** (exécute le code sandbox dans des conteneurs Docker isolés)
-- **Exécution Docker avec Kubernetes** (exécute le code sandbox dans des pods Kubernetes via le service provisioner)
-
-En développement Docker, le démarrage des services suit le mode sandbox défini dans `config.yaml`. En mode Local/Docker, `provisioner` n'est pas démarré.
-
-Voir le [Guide de configuration Sandbox](backend/docs/CONFIGURATION.md#sandbox) pour configurer le mode de votre choix.
-
-#### Serveur MCP
-
-DeerFlow supporte des serveurs MCP et des skills configurables pour étendre ses capacités.
-Pour les serveurs MCP HTTP/SSE, les flux de tokens OAuth sont supportés (`client_credentials`, `refresh_token`).
-Voir le [Guide MCP Server](backend/docs/MCP_SERVER.md) pour les instructions détaillées.
-
-#### Canaux de messagerie
-
-DeerFlow peut recevoir des tâches depuis des applications de messagerie. Les canaux démarrent automatiquement une fois configurés — aucune IP publique n'est requise.
-
-| Canal | Transport | Difficulté |
-|---------|-----------|------------|
-| Telegram | Bot API (long-polling) | Facile |
-| Slack | Socket Mode | Modérée |
-| Feishu / Lark | WebSocket | Modérée |
-
-**Configuration dans `config.yaml` :**
-
-```yaml
-channels:
-  # LangGraph Server URL (default: http://localhost:2024)
-  langgraph_url: http://localhost:2024
-  # Gateway API URL (default: http://localhost:8001)
-  gateway_url: http://localhost:8001
-
-  # Optional: global session defaults for all mobile channels
-  session:
-    assistant_id: lead_agent
-    config:
-      recursion_limit: 100
-    context:
-      thinking_enabled: true
-      is_plan_mode: false
-      subagent_enabled: false
-
-  feishu:
-    enabled: true
-    app_id: $FEISHU_APP_ID
-    app_secret: $FEISHU_APP_SECRET
-    # domain: https://open.feishu.cn       # China (default)
-    # domain: https://open.larksuite.com   # International
-
-  slack:
-    enabled: true
-    bot_token: $SLACK_BOT_TOKEN     # xoxb-...
-    app_token: $SLACK_APP_TOKEN     # xapp-... (Socket Mode)
-    allowed_users: []               # empty = allow all
-
-  telegram:
-    enabled: true
-    bot_token: $TELEGRAM_BOT_TOKEN
-    allowed_users: []               # empty = allow all
-
-    # Optional: per-channel / per-user session settings
-    session:
-      assistant_id: mobile_agent
-      context:
-        thinking_enabled: false
-      users:
-        "123456789":
-          assistant_id: vip_agent
-          config:
-            recursion_limit: 150
-          context:
-            thinking_enabled: true
-            subagent_enabled: true
-```
-
-Définissez les clés API correspondantes dans votre fichier `.env` :
-
-```bash
-# Telegram
-TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
-
-# Slack
-SLACK_BOT_TOKEN=xoxb-...
-SLACK_APP_TOKEN=xapp-...
-
-# Feishu / Lark
-FEISHU_APP_ID=cli_xxxx
-FEISHU_APP_SECRET=your_app_secret
-```
-
-**Configuration Telegram**
-
-1. Ouvrez une conversation avec [@BotFather](https://t.me/BotFather), envoyez `/newbot`, et copiez le token HTTP API.
-2. Définissez `TELEGRAM_BOT_TOKEN` dans `.env` et activez le canal dans `config.yaml`.
-
-**Configuration Slack**
-
-1. Créez une Slack App sur [api.slack.com/apps](https://api.slack.com/apps) → Create New App → From scratch.
-2. Dans **OAuth & Permissions**, ajoutez les Bot Token Scopes : `app_mentions:read`, `chat:write`, `im:history`, `im:read`, `im:write`, `files:write`.
-3. Activez le **Socket Mode** → générez un App-Level Token (`xapp-…`) avec le scope `connections:write`.
-4. Dans **Event Subscriptions**, abonnez-vous aux bot events : `app_mention`, `message.im`.
-5. Définissez `SLACK_BOT_TOKEN` et `SLACK_APP_TOKEN` dans `.env` et activez le canal dans `config.yaml`.
-
-**Configuration Feishu / Lark**
-
-1. Créez une application sur [Feishu Open Platform](https://open.feishu.cn/) → activez la capacité **Bot**.
-2. Ajoutez les permissions : `im:message`, `im:message.p2p_msg:readonly`, `im:resource`.
-3. Dans **Events**, abonnez-vous à `im.message.receive_v1` et sélectionnez le mode **Long Connection**.
-4. Copiez l'App ID et l'App Secret. Définissez `FEISHU_APP_ID` et `FEISHU_APP_SECRET` dans `.env` et activez le canal dans `config.yaml`.
-
-**Commandes**
-
-Une fois un canal connecté, vous pouvez interagir avec DeerFlow directement depuis le chat :
-
-| Commande | Description |
-|---------|-------------|
-| `/new` | Démarrer une nouvelle conversation |
-| `/status` | Afficher les infos du thread en cours |
-| `/models` | Lister les modèles disponibles |
-| `/memory` | Consulter la mémoire |
-| `/help` | Afficher l'aide |
-
-> Les messages sans préfixe de commande sont traités comme du chat classique — DeerFlow crée un thread et répond de manière conversationnelle.
-
-#### Traçage LangSmith
-
-DeerFlow intègre nativement [LangSmith](https://smith.langchain.com) pour l'observabilité. Une fois activé, tous les appels LLM, les exécutions d'agents et les exécutions d'outils sont tracés et visibles dans le tableau de bord LangSmith.
-
-Ajoutez les lignes suivantes à votre fichier `.env` :
-
-```bash
-LANGSMITH_TRACING=true
-LANGSMITH_ENDPOINT=https://api.smith.langchain.com
-LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
-LANGSMITH_PROJECT=xxx
-```
-
-Pour les déploiements Docker, le traçage est désactivé par défaut. Définissez `LANGSMITH_TRACING=true` et `LANGSMITH_API_KEY` dans votre `.env` pour l'activer.
-
-## Du Deep Research au Super Agent Harness
-
-DeerFlow a démarré comme un framework de Deep Research — et la communauté s'en est emparée. Depuis le lancement, les développeurs l'ont poussé bien au-delà de la recherche : construction de pipelines de données, génération de présentations, mise en place de dashboards, automatisation de workflows de contenu. Des usages qu'on n'avait jamais anticipés.
-
-Ça nous a révélé quelque chose d'important : DeerFlow n'était pas qu'un simple outil de recherche. C'était un **harness** — un runtime qui donne aux agents l'infrastructure nécessaire pour vraiment accomplir du travail.
-
-On l'a donc reconstruit de zéro.
-
-DeerFlow 2.0 n'est plus un framework à assembler soi-même. C'est un super agent harness — clé en main et entièrement extensible. Construit sur LangGraph et LangChain, il embarque tout ce dont un agent a besoin out of the box : un système de fichiers, de la mémoire, des skills, une exécution sandboxée, et la capacité de planifier et de lancer des sub-agents pour les tâches complexes et multi-étapes.
-
-Utilisez-le tel quel. Ou démontez-le et faites-en le vôtre.
-
-## Fonctionnalités principales
-
-### Skills et outils
-
-Les skills sont ce qui permet à DeerFlow de faire *pratiquement n'importe quoi*.
-
-Un Agent Skill standard est un module de capacité structuré — un fichier Markdown qui définit un workflow, des bonnes pratiques et des références vers des ressources associées. DeerFlow est livré avec des skills intégrés pour la recherche, la génération de rapports, la création de présentations, les pages web, la génération d'images et de vidéos, et bien plus. Mais la vraie force réside dans l'extensibilité : ajoutez vos propres skills, remplacez ceux fournis, ou combinez-les en workflows composites.
-
-Les skills sont chargés progressivement — uniquement quand la tâche le nécessite, pas tous en même temps. Ça permet de garder la fenêtre de contexte légère et de bien fonctionner même avec des modèles sensibles au nombre de tokens.
-
-Quand vous installez des archives `.skill` via le Gateway, DeerFlow accepte les métadonnées frontmatter optionnelles standard comme `version`, `author` et `compatibility`, plutôt que de rejeter des skills externes par ailleurs valides.
-
-Les outils suivent la même philosophie. DeerFlow est livré avec un ensemble d'outils de base — recherche web, fetch de pages web, opérations sur les fichiers, exécution bash — et supporte les outils custom via des serveurs MCP et des fonctions Python. Remplacez n'importe quoi. Ajoutez n'importe quoi.
-
-Les suggestions de suivi générées par le Gateway normalisent désormais aussi bien la sortie texte brut du modèle que le contenu riche au format bloc/liste avant de parser la réponse en tableau JSON, de sorte que les wrappers de contenu propres à chaque provider ne suppriment plus silencieusement les suggestions.
-
-```
-# Paths inside the sandbox container
-/mnt/skills/public
-├── research/SKILL.md
-├── report-generation/SKILL.md
-├── slide-creation/SKILL.md
-├── web-page/SKILL.md
-└── image-generation/SKILL.md
-
-/mnt/skills/custom
-└── your-custom-skill/SKILL.md      ← yours
-```
-
-#### Intégration Claude Code
-
-Le skill `claude-to-deerflow` vous permet d'interagir avec une instance DeerFlow en cours d'exécution directement depuis [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Envoyez des tâches de recherche, vérifiez le statut, gérez les threads — le tout sans quitter le terminal.
-
-**Installer le skill** :
-
-```bash
-npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow
-```
-
-Assurez-vous ensuite que DeerFlow tourne (par défaut sur `http://localhost:2026`) et utilisez la commande `/claude-to-deerflow` dans Claude Code.
-
-**Ce que vous pouvez faire** :
-- Envoyer des messages à DeerFlow et recevoir des réponses en streaming
-- Choisir le mode d'exécution : flash (rapide), standard, pro (planification), ultra (sub-agents)
-- Vérifier la santé de DeerFlow, lister les modèles/skills/agents
-- Gérer les threads et l'historique des conversations
-- Upload des fichiers pour analyse
-
-**Variables d'environnement** (optionnel, pour des endpoints custom) :
-
-```bash
-DEERFLOW_URL=http://localhost:2026            # Unified proxy base URL
-DEERFLOW_GATEWAY_URL=http://localhost:2026    # Gateway API
-DEERFLOW_LANGGRAPH_URL=http://localhost:2026/api/langgraph  # LangGraph API
-```
-
-Voir [`skills/public/claude-to-deerflow/SKILL.md`](skills/public/claude-to-deerflow/SKILL.md) pour la référence API complète.
-
-### Sub-Agents
-
-Les tâches complexes tiennent rarement en une seule passe. DeerFlow les décompose.
-
-L'agent principal peut lancer des sub-agents à la volée — chacun avec son propre contexte délimité, ses outils et ses conditions d'arrêt. Les sub-agents s'exécutent en parallèle quand c'est possible, remontent des résultats structurés, et l'agent principal synthétise le tout en une sortie cohérente.
-
-C'est comme ça que DeerFlow gère les tâches qui prennent de quelques minutes à plusieurs heures : une tâche de recherche peut se déployer en une dizaine de sub-agents, chacun explorant un angle différent, puis converger vers un seul rapport — ou un site web — ou un jeu de slides avec des visuels générés. Un seul harness, de nombreuses mains.
-
-### Sandbox et système de fichiers
-
-DeerFlow ne se contente pas de *parler* de faire les choses. Il dispose de son propre ordinateur.
-
-Chaque tâche s'exécute dans un conteneur Docker isolé avec un système de fichiers complet — skills, workspace, uploads, outputs. L'agent lit, écrit et édite des fichiers. Il exécute des commandes bash et du code. Il visualise des images. Le tout sandboxé, le tout auditable, zéro contamination entre les sessions.
-
-C'est la différence entre un chatbot avec accès à des outils et un agent doté d'un véritable environnement d'exécution.
-
-```
-# Paths inside the sandbox container
-/mnt/user-data/
-├── uploads/          ← your files
-├── workspace/        ← agents' working directory
-└── outputs/          ← final deliverables
-```
-
-### Context Engineering
-
-**Contexte isolé des Sub-Agents** : chaque sub-agent s'exécute dans son propre contexte isolé. Il ne peut voir ni le contexte de l'agent principal, ni celui des autres sub-agents. L'objectif est de garantir que chaque sub-agent reste concentré sur sa tâche sans être parasité par des informations non pertinentes.
-
-**Résumé** : au sein d'une session, DeerFlow gère le contexte de manière agressive — en résumant les sous-tâches terminées, en déchargeant les résultats intermédiaires vers le système de fichiers, en compressant ce qui n'est plus immédiatement pertinent. Ça lui permet de rester efficace sur des tâches longues et multi-étapes sans faire exploser la fenêtre de contexte.
-
-### Mémoire à long terme
-
-La plupart des agents oublient tout dès qu'une conversation se termine. DeerFlow, lui, se souvient.
-
-D'une session à l'autre, DeerFlow construit une mémoire persistante de votre profil, de vos préférences et de vos connaissances accumulées. Plus vous l'utilisez, mieux il vous connaît — votre style d'écriture, votre stack technique, vos workflows récurrents. La mémoire est stockée localement et reste sous votre contrôle.
-
-Les mises à jour de la mémoire ignorent désormais les entrées de faits en double au moment de l'application, de sorte que les préférences et le contexte répétés ne s'accumulent plus indéfiniment entre les sessions.
-
-## Modèles recommandés
-
-DeerFlow est agnostique en termes de modèle — il fonctionne avec n'importe quel LLM implémentant l'API compatible OpenAI. Cela dit, il offre de meilleures performances avec des modèles qui supportent :
-
-- **De longues fenêtres de contexte** (100k+ tokens) pour la recherche approfondie et les tâches multi-étapes
-- **Des capacités de raisonnement** pour la planification adaptative et la décomposition de tâches complexes
-- **Des entrées multimodales** pour la compréhension d'images et de vidéos
-- **Un usage fiable des outils (tool use)** pour des appels de fonctions et des sorties structurées fiables
-
-## Client Python intégré
-
-DeerFlow peut être utilisé comme bibliothèque Python intégrée sans lancer l'ensemble des services HTTP. Le `DeerFlowClient` fournit un accès direct in-process à toutes les capacités d'agent et de Gateway, en retournant les mêmes schémas de réponse que l'API HTTP Gateway. Le HTTP Gateway expose également `DELETE /api/threads/{thread_id}` pour supprimer les données de thread locales gérées par DeerFlow après la suppression du thread LangGraph :
-
-```python
-from deerflow.client import DeerFlowClient
-
-client = DeerFlowClient()
-
-# Chat
-response = client.chat("Analyze this paper for me", thread_id="my-thread")
-
-# Streaming (LangGraph SSE protocol: values, messages-tuple, end)
-for event in client.stream("hello"):
-    if event.type == "messages-tuple" and event.data.get("type") == "ai":
-        print(event.data["content"])
-
-# Configuration & management — returns Gateway-aligned dicts
-models = client.list_models()        # {"models": [...]}
-skills = client.list_skills()        # {"skills": [...]}
-client.update_skill("web-search", enabled=True)
-client.upload_files("thread-1", ["./report.pdf"])  # {"success": True, "files": [...]}
-```
-
-Toutes les méthodes retournant des dicts sont validées en CI contre les modèles de réponse Pydantic du Gateway (`TestGatewayConformance`), garantissant que le client intégré reste synchronisé avec les schémas de l'API HTTP. Voir `backend/packages/harness/deerflow/client.py` pour la documentation API complète.
-
-## Documentation
-
-- [Guide de contribution](CONTRIBUTING.md) - Mise en place de l'environnement de développement et workflow
-- [Guide de configuration](backend/docs/CONFIGURATION.md) - Instructions d'installation et de configuration
-- [Vue d'ensemble de l'architecture](backend/CLAUDE.md) - Détails de l'architecture technique
-- [Architecture backend](backend/README.md) - Architecture backend et référence API
-
-## ⚠️ Avertissement de sécurité
-
-### Un déploiement inapproprié peut introduire des risques de sécurité
-
-DeerFlow dispose de capacités clés à hauts privilèges, notamment **l'exécution de commandes système, les opérations sur les ressources et l'invocation de logique métier**. Il est conçu par défaut pour être **déployé dans un environnement local de confiance (accessible uniquement via l'interface de loopback 127.0.0.1)**. Si vous déployez l'agent dans des environnements non fiables — tels que des réseaux LAN, des serveurs cloud publics ou d'autres environnements accessibles depuis plusieurs terminaux — sans mesures de sécurité strictes, cela peut introduire des risques, notamment :
-
-- **Invocation non autorisée** : les fonctionnalités de l'agent pourraient être découvertes par des tiers non autorisés ou des scanners malveillants, déclenchant des requêtes non autorisées en masse qui exécutent des opérations à haut risque (commandes système, lecture/écriture de fichiers), pouvant causer de graves conséquences.
-- **Risques juridiques et de conformité** : si l'agent est utilisé illégalement pour mener des cyberattaques, du vol de données ou d'autres activités illicites, cela peut entraîner des responsabilités juridiques et des risques de conformité.
-
-### Recommandations de sécurité
-
-**Note : nous recommandons fortement de déployer DeerFlow dans un environnement réseau local de confiance.** Si vous avez besoin d'un déploiement multi-appareils ou multi-réseaux, vous devez mettre en place des mesures de sécurité strictes, par exemple :
-
-- **Liste blanche d'IP** : utilisez `iptables`, ou déployez des pare-feux matériels / commutateurs avec ACL, pour **configurer des règles de liste blanche d'IP** et refuser l'accès à toutes les autres adresses IP.
-- **Passerelle d'authentification** : configurez un proxy inverse (ex. nginx) et **activez une authentification forte en amont**, bloquant tout accès non authentifié.
-- **Isolation réseau** : si possible, placez l'agent et les appareils de confiance dans le **même VLAN dédié**, isolé des autres équipements réseau.
-- **Restez informé** : continuez à suivre les mises à jour de sécurité du projet DeerFlow.
-
-## Contribuer
-
-Les contributions sont les bienvenues ! Consultez [CONTRIBUTING.md](CONTRIBUTING.md) pour la mise en place de l'environnement de développement, le workflow et les conventions.
-
-La couverture de tests de régression inclut la détection du mode sandbox Docker et les tests de gestion du kubeconfig-path du provisioner dans `backend/tests/`.
-
-## Licence
-
-Ce projet est open source et disponible sous la [Licence MIT](./LICENSE).
-
-## Remerciements
-
-DeerFlow est construit sur le travail remarquable de la communauté open source. Nous sommes profondément reconnaissants envers tous les projets et contributeurs dont les efforts ont rendu DeerFlow possible. Nous nous tenons véritablement sur les épaules de géants.
-
-Nous tenons à exprimer notre sincère gratitude aux projets suivants pour leurs contributions inestimables :
-
-- **[LangChain](https://github.com/langchain-ai/langchain)** : leur excellent framework propulse nos interactions LLM et nos chaînes, permettant une intégration et des fonctionnalités fluides.
-- **[LangGraph](https://github.com/langchain-ai/langgraph)** : leur approche innovante de l'orchestration multi-agents a été déterminante pour les workflows sophistiqués de DeerFlow.
-
-Ces projets illustrent le pouvoir transformateur de la collaboration open source, et nous sommes fiers de bâtir sur leurs fondations.
-
-### Contributeurs principaux
-
-Un grand merci aux auteurs principaux de `DeerFlow`, dont la vision, la passion et le dévouement ont donné vie à ce projet :
-
-- **[Daniel Walnut](https://github.com/hetaoBackend/)**
-- **[Henry Li](https://github.com/magiccube/)**
-
-Votre engagement sans faille et votre expertise sont le moteur du succès de DeerFlow. Nous sommes honorés de vous avoir à la barre de cette aventure.
-
-## Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=bytedance/deer-flow&type=Date)](https://star-history.com/#bytedance/deer-flow&Date)

README_ja.md

@@ -1,563 +0,0 @@
-# 🦌 DeerFlow - 2.0
-
-[English](./README.md) | [中文](./README_zh.md) | 日本語 | [Français](./README_fr.md) | [Русский](./README_ru.md)
-
-[![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)](./backend/pyproject.toml)
-[![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?logo=node.js&logoColor=white)](./Makefile)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-
-<a href="https://trendshift.io/repositories/14699" target="_blank"><img src="https://trendshift.io/api/badge/repositories/14699" alt="bytedance%2Fdeer-flow | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
-> 2026年2月28日、バージョン2のリリースに伴い、DeerFlowはGitHub Trendingで🏆 第1位を獲得しました。素晴らしいコミュニティの皆さん、ありがとうございます！💪🔥
-
-DeerFlow（**D**eep **E**xploration and **E**fficient **R**esearch **Flow**）は、**サブエージェント**、**メモリ**、**サンドボックス**を統合し、**拡張可能なスキル**によってあらゆるタスクを実行できるオープンソースの**スーパーエージェントハーネス**です。
-
-https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18
-
-> [!NOTE]
-> **DeerFlow 2.0はゼロからの完全な書き直しです。** v1とコードを共有していません。オリジナルのDeep Researchフレームワークをお探しの場合は、[`1.x`ブランチ](https://github.com/bytedance/deer-flow/tree/main-1.x)で引き続きメンテナンスされています。現在の開発は2.0に移行しています。
-
-## 公式ウェブサイト
-
-[<img width="2880" height="1600" alt="image" src="https://github.com/user-attachments/assets/a598c49f-3b2f-41ea-a052-05e21349188a" />](https://deerflow.tech)
-
-**実際のデモ**は[**公式ウェブサイト**](https://deerflow.tech)でご覧いただけます。
-
-## ByteDance Volcengine のコーディングプラン
-
-<img width="4808" height="2400" alt="英文方舟" src="https://github.com/user-attachments/assets/2ecc7b9d-50be-4185-b1f7-5542d222fb2d" />
-
-- DeerFlowの実行には、Doubao-Seed-2.0-Code、DeepSeek v3.2、Kimi 2.5の使用を強く推奨します
-- [詳細はこちら](https://www.byteplus.com/en/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
-- [中国大陸の開発者はこちらをクリック](https://www.volcengine.com/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
-
-## InfoQuest
-
-DeerFlowは、BytePlusが独自に開発したインテリジェント検索・クローリングツールセット「[InfoQuest（無料オンライン体験対応）](https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest)」を新たに統合しました。
-
-<a href="https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest" target="_blank">
-  <img
-    src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/hubseh7bsbps/20251208-160108.png"   alt="InfoQuest_banner"
-  />
-</a>
-
----
-
-## 目次
-
-- [🦌 DeerFlow - 2.0](#-deerflow---20)
-  - [公式ウェブサイト](#公式ウェブサイト)
-  - [InfoQuest](#infoquest)
-  - [目次](#目次)
-  - [Coding Agent に一文でセットアップを依頼](#coding-agent-に一文でセットアップを依頼)
-  - [クイックスタート](#クイックスタート)
-    - [設定](#設定)
-    - [アプリケーションの実行](#アプリケーションの実行)
-      - [オプション1: Docker（推奨）](#オプション1-docker推奨)
-      - [オプション2: ローカル開発](#オプション2-ローカル開発)
-    - [詳細設定](#詳細設定)
-      - [サンドボックスモード](#サンドボックスモード)
-      - [MCPサーバー](#mcpサーバー)
-      - [IMチャネル](#imチャネル)
-      - [LangSmithトレーシング](#langsmithトレーシング)
-  - [Deep Researchからスーパーエージェントハーネスへ](#deep-researchからスーパーエージェントハーネスへ)
-  - [コア機能](#コア機能)
-    - [スキルとツール](#スキルとツール)
-      - [Claude Code連携](#claude-code連携)
-    - [サブエージェント](#サブエージェント)
-    - [サンドボックスとファイルシステム](#サンドボックスとファイルシステム)
-    - [コンテキストエンジニアリング](#コンテキストエンジニアリング)
-    - [長期メモリ](#長期メモリ)
-  - [推奨モデル](#推奨モデル)
-  - [組み込みPythonクライアント](#組み込みpythonクライアント)
-  - [ドキュメント](#ドキュメント)
-  - [⚠️ セキュリティに関する注意](#️-セキュリティに関する注意)
-  - [コントリビュート](#コントリビュート)
-  - [ライセンス](#ライセンス)
-  - [謝辞](#謝辞)
-    - [主要コントリビューター](#主要コントリビューター)
-  - [Star History](#star-history)
-
-## Coding Agent に一文でセットアップを依頼
-
-Claude Code、Codex、Cursor、Windsurf などの coding agent を使っているなら、次の一文をそのまま渡せます。
-
-```text
-DeerFlow がまだ clone されていなければ先に clone してから、https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md に従ってローカル開発環境を初期化してください
-```
-
-このプロンプトは coding agent 向けです。必要なら先にリポジトリを clone し、Docker が使える場合は Docker を優先して初期セットアップを行い、最後に次の起動コマンドと不足している設定項目だけを返します。
-
-## クイックスタート
-
-### 設定
-
-1. **DeerFlowリポジトリをクローン**
-
-   ```bash
-   git clone https://github.com/bytedance/deer-flow.git
-   cd deer-flow
-   ```
-
-2. **ローカル設定ファイルの生成**
-
-   プロジェクトルートディレクトリ（`deer-flow/`）から以下を実行します：
-
-   ```bash
-   make config
-   ```
-
-   このコマンドは、提供されたテンプレートに基づいてローカル設定ファイルを作成します。
-
-3. **使用するモデルの設定**
-
-   `config.yaml`を編集し、少なくとも1つのモデルを定義します：
-
-   ```yaml
-   models:
-     - name: gpt-4                       # 内部識別子
-       display_name: GPT-4               # 表示名
-       use: langchain_openai:ChatOpenAI  # LangChainクラスパス
-       model: gpt-4                      # API用モデル識別子
-       api_key: $OPENAI_API_KEY          # APIキー（推奨：環境変数を使用）
-       max_tokens: 4096                  # リクエストあたりの最大トークン数
-       temperature: 0.7                  # サンプリング温度
-
-     - 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: $OPENAI_API_KEY          # OpenRouterもここではOpenAI互換のフィールド名を使用
-       base_url: https://openrouter.ai/api/v1
-   ```
-
-   OpenRouterやOpenAI互換のゲートウェイは、`langchain_openai:ChatOpenAI`と`base_url`で設定します。プロバイダー固有の環境変数名を使用したい場合は、`api_key`でその変数を明示的に指定してください（例：`api_key: $OPENROUTER_API_KEY`）。
-
-4. **設定したモデルのAPIキーを設定**
-
-   以下のいずれかの方法を選択してください：
-
-- オプションA：プロジェクトルートの`.env`ファイルを編集（推奨）
-
-   ```bash
-   TAVILY_API_KEY=your-tavily-api-key
-   OPENAI_API_KEY=your-openai-api-key
-   # OpenRouterもlangchain_openai:ChatOpenAI + base_url使用時はOPENAI_API_KEYを使用します。
-   # 必要に応じて他のプロバイダーキーを追加
-   INFOQUEST_API_KEY=your-infoquest-api-key
-   ```
-
-- オプションB：シェルで環境変数をエクスポート
-
-   ```bash
-   export OPENAI_API_KEY=your-openai-api-key
-   ```
-
-- オプションC：`config.yaml`を直接編集（本番環境には非推奨）
-
-   ```yaml
-   models:
-     - name: gpt-4
-       api_key: your-actual-api-key-here  # プレースホルダーを置換
-   ```
-
-### アプリケーションの実行
-
-#### オプション1: Docker（推奨）
-
-**開発環境**（ホットリロード、ソースマウント）：
-
-```bash
-make docker-init    # サンドボックスイメージをプル（初回またはイメージ更新時のみ）
-make docker-start   # サービスを開始（config.yamlからサンドボックスモードを自動検出）
-```
-
-`make docker-start`は、`config.yaml`がプロビジョナーモード（`sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider`と`provisioner_url`）を使用している場合にのみ`provisioner`を起動します。
-
-**本番環境**（ローカルでイメージをビルドし、ランタイム設定とデータをマウント）：
-
-```bash
-make up     # イメージをビルドして全本番サービスを開始
-make down   # コンテナを停止して削除
-```
-
-> [!NOTE]
-> LangGraphエージェントサーバーは現在`langgraph dev`（オープンソースCLIサーバー）経由で実行されます。
-
-アクセス: http://localhost:2026
-
-詳細なDocker開発ガイドは[CONTRIBUTING.md](CONTRIBUTING.md)をご覧ください。
-
-#### オプション2: ローカル開発
-
-サービスをローカルで実行する場合：
-
-前提条件：上記の「設定」手順を先に完了してください（`make config`とモデルAPIキー）。`make dev`には有効な設定ファイルが必要です（デフォルトはプロジェクトルートの`config.yaml`。`DEER_FLOW_CONFIG_PATH`で上書き可能）。
-
-1. **前提条件の確認**：
-   ```bash
-   make check  # Node.js 22+、pnpm、uv、nginxを検証
-   ```
-
-2. **依存関係のインストール**：
-   ```bash
-   make install  # バックエンド＋フロントエンドの依存関係をインストール
-   ```
-
-3. **（オプション）サンドボックスイメージの事前プル**：
-   ```bash
-   # Docker/コンテナベースのサンドボックス使用時に推奨
-   make setup-sandbox
-   ```
-
-4. **サービスの開始**：
-   ```bash
-   make dev
-   ```
-
-5. **アクセス**: http://localhost:2026
-
-### 詳細設定
-#### サンドボックスモード
-
-DeerFlowは複数のサンドボックス実行モードをサポートしています：
-- **ローカル実行**（ホストマシン上で直接サンドボックスコードを実行）
-- **Docker実行**（分離されたDockerコンテナ内でサンドボックスコードを実行）
-- **KubernetesによるDocker実行**（プロビジョナーサービス経由でKubernetesポッドでサンドボックスコードを実行）
-
-Docker開発では、サービスの起動は`config.yaml`のサンドボックスモードに従います。ローカル/Dockerモードでは`provisioner`は起動されません。
-
-お好みのモードの設定については[サンドボックス設定ガイド](backend/docs/CONFIGURATION.md#sandbox)をご覧ください。
-
-#### MCPサーバー
-
-DeerFlowは、機能を拡張するための設定可能なMCPサーバーとスキルをサポートしています。
-HTTP/SSE MCPサーバーでは、OAuthトークンフロー（`client_credentials`、`refresh_token`）がサポートされています。
-詳細な手順は[MCPサーバーガイド](backend/docs/MCP_SERVER.md)をご覧ください。
-
-#### IMチャネル
-
-DeerFlowはメッセージングアプリからのタスク受信をサポートしています。チャネルは設定時に自動的に開始されます。いずれもパブリックIPは不要です。
-
-| チャネル | トランスポート | 難易度 |
-|---------|-----------|------------|
-| Telegram | Bot API（ロングポーリング） | 簡単 |
-| Slack | Socket Mode | 中程度 |
-| Feishu / Lark | WebSocket | 中程度 |
-
-**`config.yaml`での設定：**
-
-```yaml
-channels:
-  # LangGraphサーバーURL（デフォルト: http://localhost:2024）
-  langgraph_url: http://localhost:2024
-  # Gateway API URL（デフォルト: http://localhost:8001）
-  gateway_url: http://localhost:8001
-
-  # オプション: 全モバイルチャネルのグローバルセッションデフォルト
-  session:
-    assistant_id: lead_agent
-    config:
-      recursion_limit: 100
-    context:
-      thinking_enabled: true
-      is_plan_mode: false
-      subagent_enabled: false
-
-  feishu:
-    enabled: true
-    app_id: $FEISHU_APP_ID
-    app_secret: $FEISHU_APP_SECRET
-    # domain: https://open.feishu.cn       # China (default)
-    # domain: https://open.larksuite.com   # International
-
-  slack:
-    enabled: true
-    bot_token: $SLACK_BOT_TOKEN     # xoxb-...
-    app_token: $SLACK_APP_TOKEN     # xapp-...（Socket Mode）
-    allowed_users: []               # 空 = 全員許可
-
-  telegram:
-    enabled: true
-    bot_token: $TELEGRAM_BOT_TOKEN
-    allowed_users: []               # 空 = 全員許可
-
-    # オプション: チャネル/ユーザーごとのセッション設定
-    session:
-      assistant_id: mobile_agent
-      context:
-        thinking_enabled: false
-      users:
-        "123456789":
-          assistant_id: vip_agent
-          config:
-            recursion_limit: 150
-          context:
-            thinking_enabled: true
-            subagent_enabled: true
-```
-
-対応するAPIキーを`.env`ファイルに設定します：
-
-```bash
-# Telegram
-TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
-
-# Slack
-SLACK_BOT_TOKEN=xoxb-...
-SLACK_APP_TOKEN=xapp-...
-
-# Feishu / Lark
-FEISHU_APP_ID=cli_xxxx
-FEISHU_APP_SECRET=your_app_secret
-```
-
-**Telegramのセットアップ**
-
-1. [@BotFather](https://t.me/BotFather)とチャットし、`/newbot`を送信してHTTP APIトークンをコピーします。
-2. `.env`に`TELEGRAM_BOT_TOKEN`を設定し、`config.yaml`でチャネルを有効にします。
-
-**Slackのセットアップ**
-
-1. [api.slack.com/apps](https://api.slack.com/apps)でSlackアプリを作成 → 新規アプリ作成 → 最初から作成。
-2. **OAuth & Permissions**で、Botトークンスコープを追加：`app_mentions:read`、`chat:write`、`im:history`、`im:read`、`im:write`、`files:write`。
-3. **Socket Mode**を有効化 → `connections:write`スコープのApp-Levelトークン（`xapp-…`）を生成。
-4. **Event Subscriptions**で、ボットイベントを購読：`app_mention`、`message.im`。
-5. `.env`に`SLACK_BOT_TOKEN`と`SLACK_APP_TOKEN`を設定し、`config.yaml`でチャネルを有効にします。
-
-**Feishu / Larkのセットアップ**
-
-1. [Feishu Open Platform](https://open.feishu.cn/)でアプリを作成 → **ボット**機能を有効化。
-2. 権限を追加：`im:message`、`im:message.p2p_msg:readonly`、`im:resource`。
-3. **イベント**で`im.message.receive_v1`を購読し、**ロングコネクション**モードを選択。
-4. App IDとApp Secretをコピー。`.env`に`FEISHU_APP_ID`と`FEISHU_APP_SECRET`を設定し、`config.yaml`でチャネルを有効にします。
-
-**コマンド**
-
-チャネル接続後、チャットから直接DeerFlowと対話できます：
-
-| コマンド | 説明 |
-|---------|-------------|
-| `/new` | 新しい会話を開始 |
-| `/status` | 現在のスレッド情報を表示 |
-| `/models` | 利用可能なモデルを一覧表示 |
-| `/memory` | メモリを表示 |
-| `/help` | ヘルプを表示 |
-
-> コマンドプレフィックスのないメッセージは通常のチャットとして扱われ、DeerFlowがスレッドを作成して会話形式で応答します。
-
-#### LangSmithトレーシング
-
-DeerFlowには[LangSmith](https://smith.langchain.com)による可観測性が組み込まれています。有効にすると、すべてのLLM呼び出し、エージェント実行、ツール実行がトレースされ、LangSmithダッシュボードで確認できます。
-
-`.env`ファイルに以下を追加します：
-
-```bash
-LANGSMITH_TRACING=true
-LANGSMITH_ENDPOINT=https://api.smith.langchain.com
-LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
-LANGSMITH_PROJECT=xxx
-```
-
-Dockerデプロイでは、トレーシングはデフォルトで無効です。`.env`で`LANGSMITH_TRACING=true`と`LANGSMITH_API_KEY`を設定して有効にします。
-
-## Deep Researchからスーパーエージェントハーネスへ
-
-DeerFlowはDeep Researchフレームワークとして始まり、コミュニティがそれを大きく発展させました。リリース以来、開発者たちはリサーチを超えて活用してきました：データパイプラインの構築、スライドデッキの生成、ダッシュボードの立ち上げ、コンテンツワークフローの自動化。私たちが予想もしなかったことです。
-
-これは重要なことを示していました：DeerFlowは単なるリサーチツールではなかったのです。それは**ハーネス**——エージェントが実際に仕事をこなすためのインフラを提供するランタイムでした。
-
-そこで、ゼロから再構築しました。
-
-DeerFlow 2.0は、もはやつなぎ合わせるフレームワークではありません。バッテリー同梱、完全に拡張可能なスーパーエージェントハーネスです。LangGraphとLangChainの上に構築され、エージェントが必要とするすべてを標準搭載しています：ファイルシステム、メモリ、スキル、サンドボックス実行、そして複雑なマルチステップタスクのためのプランニングとサブエージェントの生成機能。
-
-そのまま使うもよし。分解して自分のものにするもよし。
-
-## コア機能
-
-### スキルとツール
-
-スキルこそが、DeerFlowを*ほぼ何でもできる*ものにしています。
-
-標準的なエージェントスキルは構造化された機能モジュールです——ワークフロー、ベストプラクティス、サポートリソースへの参照を定義するMarkdownファイルです。DeerFlowにはリサーチ、レポート生成、スライド作成、Webページ、画像・動画生成などの組み込みスキルが付属しています。しかし、真の力は拡張性にあります：独自のスキルを追加し、組み込みスキルを置き換え、複合ワークフローに組み合わせることができます。
-
-スキルはプログレッシブに読み込まれます——タスクが必要とする時にのみ、一度にすべてではありません。これによりコンテキストウィンドウを軽量に保ち、トークンに敏感なモデルでもDeerFlowがうまく動作します。
-
-Gateway経由で`.skill`アーカイブをインストールする際、DeerFlowは`version`、`author`、`compatibility`などの標準的なオプショナルフロントマターメタデータを受け入れ、有効な外部スキルを拒否しません。
-
-ツールも同じ哲学に従います。DeerFlowにはコアツールセット——Web検索、Webフェッチ、ファイル操作、bash実行——が付属し、MCPサーバーやPython関数によるカスタムツールをサポートしています。何でも入れ替え可能、何でも追加可能です。
-
-Gatewayが生成するフォローアップ提案は、プレーン文字列のモデル出力とブロック/リスト形式のリッチコンテンツの両方をJSON配列レスポンスの解析前に正規化するため、プロバイダー固有のコンテンツラッパーが提案をサイレントにドロップすることはありません。
-
-```
-# サンドボックスコンテナ内のパス
-/mnt/skills/public
-├── research/SKILL.md
-├── report-generation/SKILL.md
-├── slide-creation/SKILL.md
-├── web-page/SKILL.md
-└── image-generation/SKILL.md
-
-/mnt/skills/custom
-└── your-custom-skill/SKILL.md      ← あなたのカスタムスキル
-```
-
-#### Claude Code連携
-
-`claude-to-deerflow`スキルを使えば、[Claude Code](https://docs.anthropic.com/en/docs/claude-code)から直接、実行中のDeerFlowインスタンスと対話できます。リサーチタスクの送信、ステータスの確認、スレッドの管理——すべてターミナルから離れずに実行できます。
-
-**スキルのインストール**：
-
-```bash
-npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow
-```
-
-DeerFlowが実行中であることを確認し（デフォルトは`http://localhost:2026`）、Claude Codeで`/claude-to-deerflow`コマンドを使用します。
-
-**できること**：
-- DeerFlowにメッセージを送信してストリーミングレスポンスを取得
-- 実行モードの選択：flash（高速）、standard、pro（プランニング）、ultra（サブエージェント）
-- DeerFlowのヘルスチェック、モデル/スキル/エージェントの一覧表示
-- スレッドと会話履歴の管理
-- 分析用ファイルのアップロード
-
-**環境変数**（オプション、カスタムエンドポイント用）：
-
-```bash
-DEERFLOW_URL=http://localhost:2026            # 統合プロキシベースURL
-DEERFLOW_GATEWAY_URL=http://localhost:2026    # Gateway API
-DEERFLOW_LANGGRAPH_URL=http://localhost:2026/api/langgraph  # LangGraph API
-```
-
-完全なAPIリファレンスは[`skills/public/claude-to-deerflow/SKILL.md`](skills/public/claude-to-deerflow/SKILL.md)をご覧ください。
-
-### サブエージェント
-
-複雑なタスクは単一のパスに収まりません。DeerFlowはそれを分解します。
-
-リードエージェントはオンザフライでサブエージェントを生成できます——それぞれ独自のスコープ付きコンテキスト、ツール、終了条件を持ちます。サブエージェントは可能な限り並列で実行され、構造化された結果を報告し、リードエージェントがすべてを一貫した出力に統合します。
-
-これがDeerFlowが数分から数時間かかるタスクを処理する方法です：リサーチタスクが十数のサブエージェントに展開され、それぞれが異なる角度を探索し、1つのレポート——またはWebサイト——または生成されたビジュアル付きのスライドデッキに収束します。1つのハーネス、多くの手。
-
-### サンドボックスとファイルシステム
-
-DeerFlowは物事を*語る*だけではありません。自分のコンピューターを持っています。
-
-各タスクは、完全なファイルシステムを持つ分離されたDockerコンテナ内で実行されます——スキル、ワークスペース、アップロード、出力。エージェントはファイルの読み書き・編集を行います。bashコマンドを実行し、コーディングを行います。画像を表示します。すべてサンドボックス化され、すべて監査可能で、セッション間の汚染はゼロです。
-
-これが、ツールアクセスのあるチャットボットと、実際の実行環境を持つエージェントの違いです。
-
-```
-# サンドボックスコンテナ内のパス
-/mnt/user-data/
-├── uploads/          ← あなたのファイル
-├── workspace/        ← エージェントの作業ディレクトリ
-└── outputs/          ← 最終成果物
-```
-
-### コンテキストエンジニアリング
-
-**分離されたサブエージェントコンテキスト**：各サブエージェントは独自の分離されたコンテキストで実行されます。これにより、サブエージェントはメインエージェントや他のサブエージェントのコンテキストを見ることができません。これは、サブエージェントが目の前のタスクに集中し、メインエージェントや他のサブエージェントのコンテキストに気を取られないようにするために重要です。
-
-**要約化**：セッション内で、DeerFlowはコンテキストを積極的に管理します——完了したサブタスクの要約、中間結果のファイルシステムへのオフロード、もはや直接関係のないものの圧縮。これにより、コンテキストウィンドウを超えることなく、長いマルチステップタスク全体を通じてシャープさを維持します。
-
-### 長期メモリ
-
-ほとんどのエージェントは、会話が終わるとすべてを忘れます。DeerFlowは記憶します。
-
-セッションをまたいで、DeerFlowはあなたのプロフィール、好み、蓄積された知識の永続的なメモリを構築します。使えば使うほど、あなたのことをよく知るようになります——あなたの文体、技術スタック、繰り返されるワークフロー。メモリはローカルに保存され、あなたの管理下にあります。
-
-メモリ更新は適用時に重複するファクトエントリをスキップするようになり、繰り返される好みやコンテキストがセッションをまたいで際限なく蓄積されることはありません。
-
-## 推奨モデル
-
-DeerFlowはモデルに依存しません——OpenAI互換APIを実装する任意のLLMで動作します。とはいえ、以下をサポートするモデルで最高のパフォーマンスを発揮します：
-
-- **長いコンテキストウィンドウ**（10万トークン以上）：深いリサーチとマルチステップタスク向け
-- **推論能力**：適応的なプランニングと複雑な分解向け
-- **マルチモーダル入力**：画像理解と動画理解向け
-- **強力なツール使用**：信頼性の高いファンクションコーリングと構造化された出力向け
-
-## 組み込みPythonクライアント
-
-DeerFlowは、完全なHTTPサービスを実行せずに組み込みPythonライブラリとして使用できます。`DeerFlowClient`は、すべてのエージェントとGateway機能へのプロセス内直接アクセスを提供し、HTTP Gateway APIと同じレスポンススキーマを返します：
-
-```python
-from deerflow.client import DeerFlowClient
-
-client = DeerFlowClient()
-
-# チャット
-response = client.chat("Analyze this paper for me", thread_id="my-thread")
-
-# ストリーミング（LangGraph SSEプロトコル：values、messages-tuple、end）
-for event in client.stream("hello"):
-    if event.type == "messages-tuple" and event.data.get("type") == "ai":
-        print(event.data["content"])
-
-# 設定＆管理 — Gateway準拠のdictを返す
-models = client.list_models()        # {"models": [...]}
-skills = client.list_skills()        # {"skills": [...]}
-client.update_skill("web-search", enabled=True)
-client.upload_files("thread-1", ["./report.pdf"])  # {"success": True, "files": [...]}
-```
-
-すべてのdict返却メソッドはCIでGateway Pydanticレスポンスモデルに対して検証されており（`TestGatewayConformance`）、組み込みクライアントがHTTP APIスキーマと同期していることを保証します。完全なAPIドキュメントは`backend/packages/harness/deerflow/client.py`をご覧ください。
-
-## ドキュメント
-
-- [コントリビュートガイド](CONTRIBUTING.md) - 開発環境のセットアップとワークフロー
-- [設定ガイド](backend/docs/CONFIGURATION.md) - セットアップと設定の手順
-- [アーキテクチャ概要](backend/CLAUDE.md) - 技術的なアーキテクチャの詳細
-- [バックエンドアーキテクチャ](backend/README.md) - バックエンドアーキテクチャとAPIリファレンス
-
-## ⚠️ セキュリティに関する注意
-
-### 不適切なデプロイはセキュリティリスクを引き起こす可能性があります
-
-DeerFlowは**システムコマンドの実行、リソース操作、ビジネスロジックの呼び出し**などの重要な高権限機能を備えており、デフォルトでは**ローカルの信頼できる環境（127.0.0.1のループバックアクセスのみ）にデプロイされる設計**になっています。信頼できないLAN、公開クラウドサーバー、または複数のエンドポイントからアクセス可能なネットワーク環境にエージェントをデプロイし、厳格なセキュリティ対策を講じない場合、以下のようなセキュリティリスクが生じる可能性があります：
-
-- **不正な違法呼び出し**：エージェントの機能が権限のない第三者や悪意のあるインターネットスキャナーに発見され、システムコマンドやファイル読み書きなどの高リスク操作を実行する不正な一括リクエストが引き起こされ、重大なセキュリティ上の問題が発生する可能性があります。
-- **コンプライアンスおよび法的リスク**：エージェントがサイバー攻撃やデータ窃取などの違法行為に不正使用された場合、法的責任やコンプライアンス上のリスクが生じる可能性があります。
-
-### セキュリティ推奨事項
-
-**注意：DeerFlowはローカルの信頼できるネットワーク環境にデプロイすることを強く推奨します。** クロスデバイス・クロスネットワークのデプロイが必要な場合は、以下のような厳格なセキュリティ対策を実装する必要があります：
-
-- **IPホワイトリストの設定**：`iptables`を使用するか、ハードウェアファイアウォール / ACL機能付きスイッチをデプロイして**IPホワイトリストルールを設定**し、他のすべてのIPアドレスからのアクセスを拒否します。
-- **前置認証**：リバースプロキシ（nginxなど）を設定し、**強力な前置認証を有効化**して、認証なしのアクセスをブロックします。
-- **ネットワーク分離**：可能であれば、エージェントと信頼できるデバイスを**同一の専用VLAN**に配置し、他のネットワークデバイスから隔離します。
-- **アップデートを継続的に確認**：DeerFlowのセキュリティ機能のアップデートを継続的にフォローしてください。
-
-## コントリビュート
-
-コントリビューションを歓迎します！開発環境のセットアップ、ワークフロー、ガイドラインについては[CONTRIBUTING.md](CONTRIBUTING.md)をご覧ください。
-
-回帰テストのカバレッジには、`backend/tests/`でのDockerサンドボックスモード検出とプロビジョナーkubeconfig-pathハンドリングテストが含まれます。
-
-## ライセンス
-
-このプロジェクトはオープンソースであり、[MITライセンス](./LICENSE)の下で提供されています。
-
-## 謝辞
-
-DeerFlowはオープンソースコミュニティの素晴らしい成果の上に構築されています。DeerFlowを可能にしてくれたすべてのプロジェクトとコントリビューターに深く感謝いたします。まさに、巨人の肩の上に立っています。
-
-以下のプロジェクトの貴重な貢献に心からの感謝を申し上げます：
-
-- **[LangChain](https://github.com/langchain-ai/langchain)**：その優れたフレームワークがLLMのインタラクションとチェーンを支え、シームレスな統合と機能を実現しています。
-- **[LangGraph](https://github.com/langchain-ai/langgraph)**：マルチエージェントオーケストレーションへの革新的なアプローチが、DeerFlowの洗練されたワークフローの実現に大きく貢献しています。
-
-これらのプロジェクトはオープンソースコラボレーションの変革的な力を体現しており、その基盤の上に構築できることを誇りに思います。
-
-### 主要コントリビューター
-
-`DeerFlow`のコア著者に心からの感謝を捧げます。そのビジョン、情熱、献身がこのプロジェクトに命を吹き込みました：
-
-- **[Daniel Walnut](https://github.com/hetaoBackend/)**
-- **[Henry Li](https://github.com/magiccube/)**
-
-揺るぎないコミットメントと専門知識が、DeerFlowの成功の原動力です。この旅の先頭に立ってくださっていることを光栄に思います。
-
-## Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=bytedance/deer-flow&type=Date)](https://star-history.com/#bytedance/deer-flow&Date)

README_ru.md

@@ -1,490 +0,0 @@
-# 🦌 DeerFlow - 2.0
-
-[English](./README.md) | [中文](./README_zh.md) | [日本語](./README_ja.md) | [Français](./README_fr.md) | Русский
-
-[![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)](./backend/pyproject.toml)
-[![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?logo=node.js&logoColor=white)](./Makefile)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-
-<a href="https://trendshift.io/repositories/14699" target="_blank"><img src="https://trendshift.io/api/badge/repositories/14699" alt="bytedance%2Fdeer-flow | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
-
-> 28 февраля 2026 года DeerFlow занял 🏆 #1 в GitHub Trending после релиза версии 2. Спасибо огромное нашему сообществу — всё благодаря вам! 💪🔥
-
-DeerFlow (**D**eep **E**xploration and **E**fficient **R**esearch **Flow**) — open-source **Super Agent Harness**, который управляет **Sub-Agents**, **Memory** и **Sandbox** для решения почти любой задачи. Всё на основе расширяемых **Skills**.
-
-https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18
-
-> [!NOTE]
-> **DeerFlow 2.0 — проект переписан с нуля.** Общего кода с v1 нет. Если нужен оригинальный Deep Research фреймворк — он живёт в ветке [`1.x`](https://github.com/bytedance/deer-flow/tree/main-1.x), туда тоже принимают контрибьюты. Активная разработка идёт в 2.0.
-
-## Официальный сайт
-
-[<img width="2880" height="1600" alt="image" src="https://github.com/user-attachments/assets/a598c49f-3b2f-41ea-a052-05e21349188a" />](https://deerflow.tech)
-
-Больше информации и живые демо на [**официальном сайте**](https://deerflow.tech).
-
-## Coding Plan от ByteDance Volcengine
-
-<img width="4808" height="2400" alt="英文方舟" src="https://github.com/user-attachments/assets/2ecc7b9d-50be-4185-b1f7-5542d222fb2d" />
-
-- Рекомендуем Doubao-Seed-2.0-Code, DeepSeek v3.2 и Kimi 2.5 для запуска DeerFlow
-- [Подробнее](https://www.byteplus.com/en/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
-- [Для разработчиков из материкового Китая](https://www.volcengine.com/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
-
-## InfoQuest
-
-DeerFlow интегрирован с инструментарием для умного поиска и краулинга от BytePlus — [InfoQuest (есть бесплатный онлайн-доступ)](https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest)
-
-<a href="https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest" target="_blank">
-  <img
-    src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/hubseh7bsbps/20251208-160108.png"
-    alt="InfoQuest_banner"
-  />
-</a>
-
----
-
-## Содержание
-
-- [🦌 DeerFlow - 2.0](#-deerflow---20)
-  - [Официальный сайт](#официальный-сайт)
-  - [InfoQuest](#infoquest)
-  - [Содержание](#содержание)
-  - [Установка одной фразой для coding agent](#установка-одной-фразой-для-coding-agent)
-  - [Быстрый старт](#быстрый-старт)
-    - [Конфигурация](#конфигурация)
-    - [Запуск](#запуск)
-      - [Вариант 1: Docker (рекомендуется)](#вариант-1-docker-рекомендуется)
-      - [Вариант 2: Локальная разработка](#вариант-2-локальная-разработка)
-    - [Дополнительно](#дополнительно)
-      - [Режим Sandbox](#режим-sandbox)
-      - [MCP-сервер](#mcp-сервер)
-      - [Мессенджеры](#мессенджеры)
-      - [Трассировка LangSmith](#трассировка-langsmith)
-  - [От Deep Research к Super Agent Harness](#от-deep-research-к-super-agent-harness)
-  - [Core Features](#core-features)
-    - [Skills & Tools](#skills--tools)
-      - [Интеграция с Claude Code](#интеграция-с-claude-code)
-    - [Sub-Agents](#sub-agents)
-    - [Sandbox & файловая система](#sandbox--файловая-система)
-    - [Context Engineering](#context-engineering)
-    - [Long-Term Memory](#long-term-memory)
-  - [Рекомендуемые модели](#рекомендуемые-модели)
-  - [Встроенный Python-клиент](#встроенный-python-клиент)
-  - [Документация](#документация)
-  - [⚠️ Безопасность](#️-безопасность)
-  - [Участие в разработке](#участие-в-разработке)
-  - [Лицензия](#лицензия)
-  - [Благодарности](#благодарности)
-    - [Ключевые контрибьюторы](#ключевые-контрибьюторы)
-  - [История звёзд](#история-звёзд)
-
-## Установка одной фразой для coding agent
-
-Если вы используете Claude Code, Codex, Cursor, Windsurf или другой coding agent, просто отправьте ему эту фразу:
-
-```text
-Если DeerFlow еще не клонирован, сначала клонируй его, а затем подготовь локальное окружение разработки по инструкции https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md
-```
-
-Этот prompt предназначен для coding agent. Он просит агента при необходимости сначала клонировать репозиторий, предпочесть Docker, если он доступен, и в конце вернуть точную команду запуска и список недостающих настроек.
-
-## Быстрый старт
-
-### Конфигурация
-
-1. **Склонировать репозиторий DeerFlow**
-
-   ```bash
-   git clone https://github.com/bytedance/deer-flow.git
-   cd deer-flow
-   ```
-
-2. **Сгенерировать локальные конфиги**
-
-   Из корня проекта (`deer-flow/`) запустите:
-
-   ```bash
-   make config
-   ```
-
-   Команда создаёт локальные конфиги на основе шаблонов.
-
-3. **Настроить модель**
-
-   Отредактируйте `config.yaml` и задайте хотя бы одну модель:
-
-   ```yaml
-   models:
-     - name: gpt-4                       # Внутренний идентификатор
-       display_name: GPT-4               # Отображаемое имя
-       use: langchain_openai:ChatOpenAI  # Путь к классу LangChain
-       model: gpt-4                      # Идентификатор модели для API
-       api_key: $OPENAI_API_KEY          # API-ключ (рекомендуется: переменная окружения)
-       max_tokens: 4096                  # Максимальное количество токенов на запрос
-       temperature: 0.7                  # Температура сэмплирования
-
-     - 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: $OPENAI_API_KEY
-       base_url: https://openrouter.ai/api/v1
-
-     - name: gpt-5-responses
-       display_name: GPT-5 (Responses API)
-       use: langchain_openai:ChatOpenAI
-       model: gpt-5
-       api_key: $OPENAI_API_KEY
-       use_responses_api: true
-       output_version: responses/v1
-   ```
-
-   OpenRouter и аналогичные OpenAI-совместимые шлюзы настраиваются через `langchain_openai:ChatOpenAI` с параметром `base_url`. Для CLI-провайдеров:
-
-   ```yaml
-   models:
-     - name: gpt-5.4
-       display_name: GPT-5.4 (Codex CLI)
-       use: deerflow.models.openai_codex_provider:CodexChatModel
-       model: gpt-5.4
-       supports_thinking: true
-       supports_reasoning_effort: true
-
-     - name: claude-sonnet-4.6
-       display_name: Claude Sonnet 4.6 (Claude Code OAuth)
-       use: deerflow.models.claude_provider:ClaudeChatModel
-       model: claude-sonnet-4-6
-       max_tokens: 4096
-       supports_thinking: true
-   ```
-
-   - Codex CLI читает `~/.codex/auth.json`
-   - Claude Code принимает `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_AUTH_TOKEN` или `~/.claude/.credentials.json`
-   - На macOS при необходимости экспортируйте аутентификацию Claude Code явно:
-
-   ```bash
-   eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"
-   ```
-
-4. **Указать API-ключи**
-
-   - **Вариант А**: файл `.env` в корне проекта (рекомендуется)
-
-   ```bash
-   TAVILY_API_KEY=your-tavily-api-key
-   OPENAI_API_KEY=your-openai-api-key
-   INFOQUEST_API_KEY=your-infoquest-api-key
-   ```
-
-   - **Вариант Б**: переменные окружения в терминале
-
-   ```bash
-   export OPENAI_API_KEY=your-openai-api-key
-   ```
-
-   - **Вариант В**: напрямую в `config.yaml` (не рекомендуется для продакшена)
-
-### Запуск
-
-#### Вариант 1: Docker (рекомендуется)
-
-**Разработка** (hot-reload, монтирование исходников):
-
-```bash
-make docker-init    # Загрузить образ Sandbox (один раз или при обновлении)
-make docker-start   # Запустить сервисы
-```
-
-**Продакшен** (собирает образы локально):
-
-```bash
-make up     # Собрать образы и запустить все сервисы
-make down   # Остановить и удалить контейнеры
-```
-
-> [!TIP]
-> На Linux при ошибке `permission denied` для Docker daemon добавьте пользователя в группу `docker` и перелогиньтесь. Подробнее в [CONTRIBUTING.md](CONTRIBUTING.md#linux-docker-daemon-permission-denied).
-
-Адрес: http://localhost:2026
-
-#### Вариант 2: Локальная разработка
-
-1. **Проверить зависимости**:
-   ```bash
-   make check  # Проверяет Node.js 22+, pnpm, uv, nginx
-   ```
-
-2. **Установить зависимости**:
-   ```bash
-   make install
-   ```
-
-3. **(Опционально) Загрузить образ Sandbox заранее**:
-   ```bash
-   make setup-sandbox
-   ```
-
-4. **Запустить сервисы**:
-   ```bash
-   make dev
-   ```
-
-5. **Адрес**: http://localhost:2026
-
-### Дополнительно
-
-#### Режим Sandbox
-
-DeerFlow поддерживает несколько режимов выполнения:
-- **Локальное выполнение** — код запускается прямо на хосте
-- **Docker** — код выполняется в изолированных Docker-контейнерах
-- **Docker + Kubernetes** — выполнение в Kubernetes-подах через provisioner
-
-Подробнее в [руководстве по конфигурации Sandbox](backend/docs/CONFIGURATION.md#sandbox).
-
-#### MCP-сервер
-
-DeerFlow поддерживает настраиваемые MCP-серверы для расширения возможностей. Для HTTP/SSE MCP-серверов поддерживаются OAuth-токены (`client_credentials`, `refresh_token`). Подробнее в [руководстве по MCP-серверу](backend/docs/MCP_SERVER.md).
-
-#### Мессенджеры
-
-DeerFlow принимает задачи прямо из мессенджеров. Каналы запускаются автоматически при настройке, публичный IP не нужен.
-
-| Канал | Транспорт | Сложность |
-|-------|-----------|-----------|
-| Telegram | Bot API (long-polling) | Просто |
-| Slack | Socket Mode | Средне |
-| Feishu / Lark | WebSocket | Средне |
-
-**Конфигурация в `config.yaml`:**
-
-```yaml
-channels:
-  feishu:
-    enabled: true
-    app_id: $FEISHU_APP_ID
-    app_secret: $FEISHU_APP_SECRET
-    # domain: https://open.feishu.cn       # China (default)
-    # domain: https://open.larksuite.com   # International
-
-  slack:
-    enabled: true
-    bot_token: $SLACK_BOT_TOKEN
-    app_token: $SLACK_APP_TOKEN
-    allowed_users: []
-
-  telegram:
-    enabled: true
-    bot_token: $TELEGRAM_BOT_TOKEN
-    allowed_users: []
-```
-
-**Настройка Telegram**
-
-1. Напишите [@BotFather](https://t.me/BotFather), отправьте `/newbot` и скопируйте HTTP API-токен.
-2. Укажите `TELEGRAM_BOT_TOKEN` в `.env` и включите канал в `config.yaml`.
-
-**Доступные команды**
-
-| Команда | Описание |
-|---------|----------|
-| `/new` | Начать новый диалог |
-| `/status` | Показать информацию о текущем треде |
-| `/models` | Список доступных моделей |
-| `/memory` | Просмотреть память |
-| `/help` | Показать справку |
-
-> Сообщения без команды воспринимаются как обычный чат — DeerFlow создаёт тред и отвечает.
-
-#### Трассировка LangSmith
-
-DeerFlow имеет встроенную интеграцию с [LangSmith](https://smith.langchain.com) для наблюдаемости. При включении все вызовы LLM, запуски агентов и выполнения инструментов отслеживаются и отображаются в дашборде LangSmith.
-
-Добавьте в файл `.env` в корне проекта:
-
-```bash
-LANGSMITH_TRACING=true
-LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
-LANGSMITH_PROJECT=deer-flow
-```
-
-`LANGSMITH_ENDPOINT` по умолчанию `https://api.smith.langchain.com` и может быть переопределён при необходимости. Устаревшие переменные `LANGCHAIN_*` (`LANGCHAIN_TRACING_V2`, `LANGCHAIN_API_KEY` и т.д.) также поддерживаются для обратной совместимости; `LANGSMITH_*` имеет приоритет, когда заданы обе.
-
-В Docker-развёртываниях трассировка отключена по умолчанию. Установите `LANGSMITH_TRACING=true` и `LANGSMITH_API_KEY` в `.env` для включения.
-
-## От Deep Research к Super Agent Harness
-
-DeerFlow начинался как фреймворк для Deep Research, и сообщество вышло далеко за эти рамки. После запуска разработчики строили пайплайны, генерировали презентации, поднимали дашборды, автоматизировали контент. То, чего мы не ожидали.
-
-Стало понятно: DeerFlow не просто research-инструмент. Это **harness**: runtime, который даёт агентам необходимую инфраструктуру.
-
-Поэтому мы переписали всё с нуля.
-
-DeerFlow 2.0 — это Super Agent Harness «из коробки». Batteries included, полностью расширяемый. Построен на LangGraph и LangChain. По умолчанию есть всё, что нужно агенту: файловая система, memory, skills, sandbox-выполнение и возможность планировать и запускать sub-agents для сложных многошаговых задач.
-
-Используйте как есть. Или разберите и переделайте под себя.
-
-## Core Features
-
-### Skills & Tools
-
-Skills — это то, что позволяет DeerFlow делать почти что угодно.
-
-Agent Skill — это структурированный модуль: Markdown-файл с описанием воркфлоу, лучших практик и ссылок на ресурсы. DeerFlow поставляется со встроенными skills для ресёрча, генерации отчётов, слайдов, веб-страниц, изображений и видео. Но главное — расширяемость: добавляйте свои skills, заменяйте встроенные или собирайте из них составные воркфлоу.
-
-Skills загружаются по мере необходимости, только когда задача их требует. Это держит контекстное окно чистым.
-
-```
-# Пути внутри контейнера sandbox
-/mnt/skills/public
-├── research/SKILL.md
-├── report-generation/SKILL.md
-├── slide-creation/SKILL.md
-├── web-page/SKILL.md
-└── image-generation/SKILL.md
-
-/mnt/skills/custom
-└── your-custom-skill/SKILL.md      ← ваш skill
-```
-
-#### Интеграция с Claude Code
-
-Skill `claude-to-deerflow` позволяет работать с DeerFlow прямо из [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Отправляйте задачи, проверяйте статус, управляйте тредами, не выходя из терминала.
-
-**Установка скилла**:
-
-```bash
-npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow
-```
-
-**Что можно делать**:
-- Отправлять сообщения в DeerFlow и получать потоковые ответы
-- Выбирать режимы выполнения: flash (быстро), standard, pro (planning), ultra (sub-agents)
-- Проверять статус DeerFlow, просматривать модели, скиллы, агентов
-- Управлять тредами и историей диалога
-- Загружать файлы для анализа
-
-Полный справочник API в [`skills/public/claude-to-deerflow/SKILL.md`](skills/public/claude-to-deerflow/SKILL.md).
-
-### Sub-Agents
-
-Сложные задачи редко решаются за один проход. DeerFlow их декомпозирует.
-
-Lead agent запускает sub-agents на лету, каждый со своим изолированным контекстом, инструментами и условиями завершения. Sub-agents работают параллельно, возвращают структурированные результаты, а lead agent собирает всё в единый итог.
-
-Вот как DeerFlow справляется с задачами на минуты и часы: research-задача разветвляется в дюжину sub-agents, каждый копает свой угол, потом всё сходится в один отчёт, или сайт, или слайддек со сгенерированными визуалами. Один harness, много рук.
-
-### Sandbox & файловая система
-
-DeerFlow не просто *говорит* о том, что умеет что-то делать. У него есть собственный компьютер.
-
-Каждая задача выполняется внутри изолированного Docker-контейнера с полной файловой системой: skills, workspace, uploads, outputs. Агент читает, пишет и редактирует файлы. Выполняет bash-команды и пишет код. Смотрит на изображения. Всё изолировано, всё прозрачно, никакого пересечения между сессиями.
-
-Это разница между чатботом с доступом к инструментам и агентом с реальной средой выполнения.
-
-```
-# Пути внутри контейнера sandbox
-/mnt/user-data/
-├── uploads/          ← ваши файлы
-├── workspace/        ← рабочая директория агентов
-└── outputs/          ← результаты
-```
-
-### Context Engineering
-
-**Изолированный контекст**: каждый sub-agent работает в своём контексте и не видит контекст главного агента или других sub-agents. Агент фокусируется на своей задаче.
-
-**Управление контекстом**: внутри сессии DeerFlow агрессивно сжимает контекст и суммирует завершённые подзадачи, выгружает промежуточные результаты в файловую систему, сжимает то, что уже не актуально. На длинных многошаговых задачах контекстное окно не переполняется.
-
-### Long-Term Memory
-
-Большинство агентов забывают всё, когда диалог заканчивается. DeerFlow помнит.
-
-DeerFlow сохраняет ваш профиль, предпочтения и накопленные знания между сессиями. Чем больше используете, тем лучше он вас знает: стиль, технологический стек, повторяющиеся воркфлоу. Всё хранится локально и остаётся под вашим контролем.
-
-## Рекомендуемые модели
-
-DeerFlow работает с любым LLM через OpenAI-совместимый API. Лучше всего — с моделями, которые поддерживают:
-
-- **Большое контекстное окно** (100k+ токенов) — для deep research и многошаговых задач
-- **Reasoning capabilities** — для адаптивного планирования и сложной декомпозиции
-- **Multimodal inputs** — для работы с изображениями и видео
-- **Strong tool-use** — для надёжного вызова функций и структурированных ответов
-
-## Встроенный Python-клиент
-
-DeerFlow можно использовать как Python-библиотеку прямо в коде — без запуска HTTP-сервисов. `DeerFlowClient` даёт доступ ко всем возможностям агента и Gateway, возвращает те же схемы ответов, что и HTTP Gateway API:
-
-```python
-from deerflow.client import DeerFlowClient
-
-client = DeerFlowClient()
-
-# Chat
-response = client.chat("Analyze this paper for me", thread_id="my-thread")
-
-# Streaming (LangGraph SSE protocol: values, messages-tuple, end)
-for event in client.stream("hello"):
-    if event.type == "messages-tuple" and event.data.get("type") == "ai":
-        print(event.data["content"])
-
-# Configuration & management — returns Gateway-aligned dicts
-models = client.list_models()        # {"models": [...]}
-skills = client.list_skills()        # {"skills": [...]}
-client.update_skill("web-search", enabled=True)
-client.upload_files("thread-1", ["./report.pdf"])  # {"success": True, "files": [...]}
-```
-
-## Документация
-
-- [Руководство по участию](CONTRIBUTING.md) — настройка среды разработки, воркфлоу и гайдлайны
-- [Руководство по конфигурации](backend/docs/CONFIGURATION.md) — инструкции по настройке
-- [Обзор архитектуры](backend/CLAUDE.md) — технические детали
-- [Архитектура бэкенда](backend/README.md) — бэкенд и справочник API
-
-## ⚠️ Безопасность
-
-### Неправильное развёртывание может привести к угрозам безопасности
-
-DeerFlow обладает ключевыми высокопривилегированными возможностями, включая **выполнение системных команд, операции с ресурсами и вызов бизнес-логики**. По умолчанию он рассчитан на **развёртывание в локальной доверенной среде (доступ только через loopback-адрес 127.0.0.1)**. Если вы разворачиваете агент в недоверенных средах — локальных сетях, публичных облачных серверах или других окружениях, доступных с нескольких устройств — без строгих мер безопасности, это может привести к следующим угрозам:
-
-- **Несанкционированные вызовы**: функциональность агента может быть обнаружена неавторизованными третьими лицами или вредоносными сканерами, что приведёт к массовым несанкционированным запросам с выполнением высокорисковых операций (системные команды, чтение/запись файлов) и серьёзным последствиям для безопасности.
-- **Юридические и compliance-риски**: если агент будет незаконно использован для кибератак, кражи данных или других противоправных действий, это может повлечь юридическую ответственность и compliance-риски.
-
-### Рекомендации по безопасности
-
-**Примечание: настоятельно рекомендуем развёртывать DeerFlow только в локальной доверенной сети.** Если вам необходимо развёртывание через несколько устройств или сетей, обязательно реализуйте строгие меры безопасности, например:
-
-- **Белый список IP-адресов**: используйте `iptables` или аппаратные межсетевые экраны / коммутаторы с ACL, чтобы **настроить правила белого списка IP** и заблокировать доступ со всех остальных адресов.
-- **Шлюз аутентификации**: настройте обратный прокси (nginx и др.) и **включите строгую предварительную аутентификацию**, запрещающую любой доступ без авторизации.
-- **Сетевая изоляция**: по возможности разместите агент и доверенные устройства в **одном выделенном VLAN**, изолированном от остальной сети.
-- **Следите за обновлениями**: регулярно отслеживайте обновления безопасности проекта DeerFlow.
-
-## Участие в разработке
-
-Приветствуем контрибьюторов! Настройка среды разработки, воркфлоу и гайдлайны — в [CONTRIBUTING.md](CONTRIBUTING.md).
-
-## Лицензия
-
-Проект распространяется под [лицензией MIT](./LICENSE).
-
-## Благодарности
-
-DeerFlow стоит на плечах open-source сообщества. Спасибо всем проектам и разработчикам, чья работа сделала его возможным.
-
-Отдельная благодарность:
-
-- **[LangChain](https://github.com/langchain-ai/langchain)** — фреймворк для взаимодействия с LLM и построения цепочек.
-- **[LangGraph](https://github.com/langchain-ai/langgraph)** — многоагентная оркестрация, на которой держатся сложные воркфлоу DeerFlow.
-
-### Ключевые контрибьюторы
-
-Авторы DeerFlow, без которых проекта бы не было:
-
-- **[Daniel Walnut](https://github.com/hetaoBackend/)**
-- **[Henry Li](https://github.com/magiccube/)**
-
-## История звёзд
-
-[![Star History Chart](https://api.star-history.com/svg?repos=bytedance/deer-flow&type=Date)](https://star-history.com/#bytedance/deer-flow&Date)

README_zh.md

@@ -1,551 +0,0 @@
-# 🦌 DeerFlow - 2.0
-
-[English](./README.md) | 中文 | [日本語](./README_ja.md) | [Français](./README_fr.md) | [Русский](./README_ru.md)
-
-[![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)](./backend/pyproject.toml)
-[![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?logo=node.js&logoColor=white)](./Makefile)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-
-<a href="https://trendshift.io/repositories/14699" target="_blank"><img src="https://trendshift.io/api/badge/repositories/14699" alt="bytedance%2Fdeer-flow | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
-> 2026 年 2 月 28 日，DeerFlow 2 发布后登上 GitHub Trending 第 1 名。非常感谢社区的支持，这是大家一起做到的。
-
-DeerFlow（**D**eep **E**xploration and **E**fficient **R**esearch **Flow**）是一个开源的 **super agent harness**。它把 **sub-agents**、**memory** 和 **sandbox** 组织在一起，再配合可扩展的 **skills**，让 agent 可以完成几乎任何事情。
-
-https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18
-
-> [!NOTE]
-> **DeerFlow 2.0 是一次彻底重写。** 它和 v1 没有共用代码。如果你要找的是最初的 Deep Research 框架，可以前往 [`1.x` 分支](https://github.com/bytedance/deer-flow/tree/main-1.x)。那里仍然欢迎贡献；当前的主要开发已经转向 2.0。
-
-## 官网
-
-[<img width="2880" height="1600" alt="image" src="https://github.com/user-attachments/assets/a598c49f-3b2f-41ea-a052-05e21349188a" />](https://deerflow.tech)
-
-想了解更多，或者直接看**真实演示**，可以访问[**官网**](https://deerflow.tech)。
-
-## 字节跳动火山引擎方舟 Coding Plan
-
-[<img width="4808" height="2400" alt="codingplan -banner 素材" src="https://github.com/user-attachments/assets/d30dae52-84f2-4021-b32f-6d281252b9ea" />](https://www.volcengine.com/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
-
-- 我们推荐使用 Doubao-Seed-2.0-Code、DeepSeek v3.2 和 Kimi 2.5 运行 DeerFlow
-- [现在就加入 Coding Plan](https://www.volcengine.com/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
-- [海外地区的开发者请点击这里](https://www.byteplus.com/en/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
-
-## 目录
-
-- [🦌 DeerFlow - 2.0](#-deerflow---20)
-  - [官网](#官网)
-  - [InfoQuest](#infoquest)
-  - [目录](#目录)
-  - [一句话交给 Coding Agent 安装](#一句话交给-coding-agent-安装)
-  - [快速开始](#快速开始)
-    - [配置](#配置)
-    - [运行应用](#运行应用)
-      - [方式一：Docker（推荐）](#方式一docker推荐)
-      - [方式二：本地开发](#方式二本地开发)
-    - [进阶配置](#进阶配置)
-      - [Sandbox 模式](#sandbox-模式)
-      - [MCP Server](#mcp-server)
-      - [IM 渠道](#im-渠道)
-      - [LangSmith 链路追踪](#langsmith-链路追踪)
-  - [从 Deep Research 到 Super Agent Harness](#从-deep-research-到-super-agent-harness)
-  - [核心特性](#核心特性)
-    - [Skills 与 Tools](#skills-与-tools)
-      - [Claude Code 集成](#claude-code-集成)
-    - [Sub-Agents](#sub-agents)
-    - [Sandbox 与文件系统](#sandbox-与文件系统)
-    - [Context Engineering](#context-engineering)
-    - [长期记忆](#长期记忆)
-  - [推荐模型](#推荐模型)
-  - [内嵌 Python Client](#内嵌-python-client)
-  - [文档](#文档)
-  - [⚠️ 安全使用](#️-安全使用)
-  - [参与贡献](#参与贡献)
-  - [许可证](#许可证)
-  - [致谢](#致谢)
-    - [核心贡献者](#核心贡献者)
-  - [Star History](#star-history)
-
-## 一句话交给 Coding Agent 安装
-
-如果你在用 Claude Code、Codex、Cursor、Windsurf 或其他 coding agent，可以直接把下面这句话发给它：
-
-```text
-如果还没 clone DeerFlow，就先 clone，然后按照 https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md 把它的本地开发环境初始化好
-```
-
-这条提示词是给 coding agent 用的。它会在需要时先 clone 仓库，优先选择 Docker，完成初始化，并在结束时告诉你下一条启动命令，以及还缺哪些配置需要你补充。
-
-## 快速开始
-
-### 配置
-
-1. **克隆 DeerFlow 仓库**
-
-   ```bash
-   git clone https://github.com/bytedance/deer-flow.git
-   cd deer-flow
-   ```
-
-2. **生成本地配置文件**
-
-   在项目根目录（`deer-flow/`）执行：
-
-   ```bash
-   make config
-   ```
-
-   这个命令会基于示例模板生成本地配置文件。
-
-3. **配置你要使用的模型**
-
-   编辑 `config.yaml`，至少定义一个模型：
-
-   ```yaml
-   models:
-     - name: gpt-4                       # 内部标识
-       display_name: GPT-4               # 展示名称
-       use: langchain_openai:ChatOpenAI  # LangChain 类路径
-       model: gpt-4                      # API 使用的模型标识
-       api_key: $OPENAI_API_KEY          # API key（推荐使用环境变量）
-       max_tokens: 4096                  # 单次请求最大 tokens
-       temperature: 0.7                  # 采样温度
-
-     - 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: $OPENAI_API_KEY          # 这里 OpenRouter 依然沿用 OpenAI 兼容字段名
-       base_url: https://openrouter.ai/api/v1
-   ```
-
-   OpenRouter 以及类似的 OpenAI 兼容网关，建议通过 `langchain_openai:ChatOpenAI` 配合 `base_url` 来配置。如果你更想用 provider 自己的环境变量名，也可以直接把 `api_key` 指向对应变量，例如 `api_key: $OPENROUTER_API_KEY`。
-
-4. **为已配置的模型设置 API key**
-
-   可任选以下一种方式：
-
-- 方式 A：编辑项目根目录下的 `.env` 文件（推荐）
-
-   ```bash
-   TAVILY_API_KEY=your-tavily-api-key
-   OPENAI_API_KEY=your-openai-api-key
-   # 如果配置使用的是 langchain_openai:ChatOpenAI + base_url，OpenRouter 也会读取 OPENAI_API_KEY
-   # 其他 provider 的 key 按需补充
-   INFOQUEST_API_KEY=your-infoquest-api-key
-   ```
-
-- 方式 B：在 shell 中导出环境变量
-
-   ```bash
-   export OPENAI_API_KEY=your-openai-api-key
-   ```
-
-- 方式 C：直接编辑 `config.yaml`（不建议用于生产环境）
-
-   ```yaml
-   models:
-     - name: gpt-4
-       api_key: your-actual-api-key-here  # 替换为真实 key
-   ```
-
-### 运行应用
-
-#### 方式一：Docker（推荐）
-
-**开发模式**（支持热更新，挂载源码）：
-
-```bash
-make docker-init    # 拉取 sandbox 镜像（首次运行或镜像更新时执行）
-make docker-start   # 启动服务（会根据 config.yaml 自动判断 sandbox 模式）
-```
-
-如果 `config.yaml` 使用的是 provisioner 模式（`sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider` 且配置了 `provisioner_url`），`make docker-start` 才会启动 `provisioner`。
-
-**生产模式**（本地构建镜像，并挂载运行期配置与数据）：
-
-```bash
-make up     # 构建镜像并启动全部生产服务
-make down   # 停止并移除容器
-```
-
-> [!NOTE]
-> 当前 LangGraph agent server 通过开源 CLI 服务 `langgraph dev` 运行。
-
-访问地址：http://localhost:2026
-
-更完整的 Docker 开发说明见 [CONTRIBUTING.md](CONTRIBUTING.md)。
-
-#### 方式二：本地开发
-
-如果你更希望直接在本地启动各个服务：
-
-前提：先完成上面的“配置”步骤（`make config` 和模型 API key 配置）。`make dev` 需要有效配置文件，默认读取项目根目录下的 `config.yaml`，也可以通过 `DEER_FLOW_CONFIG_PATH` 覆盖。
-
-1. **检查依赖环境**：
-   ```bash
-   make check  # 校验 Node.js 22+、pnpm、uv、nginx
-   ```
-
-2. **安装依赖**：
-   ```bash
-   make install  # 安装 backend + frontend 依赖
-   ```
-
-3. **（可选）预拉取 sandbox 镜像**：
-   ```bash
-   # 如果使用 Docker / Container sandbox，建议先执行
-   make setup-sandbox
-   ```
-
-4. **启动服务**：
-   ```bash
-   make dev
-   ```
-
-5. **访问地址**：http://localhost:2026
-
-### 进阶配置
-#### Sandbox 模式
-
-DeerFlow 支持多种 sandbox 执行方式：
-- **本地执行**（直接在宿主机上运行 sandbox 代码）
-- **Docker 执行**（在隔离的 Docker 容器里运行 sandbox 代码）
-- **Docker + Kubernetes 执行**（通过 provisioner 服务在 Kubernetes Pod 中运行 sandbox 代码）
-
-Docker 开发时，服务启动行为会遵循 `config.yaml` 里的 sandbox 模式。在 Local / Docker 模式下，不会启动 `provisioner`。
-
-如果要配置你自己的模式，参见 [Sandbox 配置指南](backend/docs/CONFIGURATION.md#sandbox)。
-
-#### MCP Server
-
-DeerFlow 支持可配置的 MCP Server 和 skills，用来扩展能力。
-对于 HTTP/SSE MCP Server，还支持 OAuth token 流程（`client_credentials`、`refresh_token`）。
-详细说明见 [MCP Server 指南](backend/docs/MCP_SERVER.md)。
-
-#### IM 渠道
-
-DeerFlow 支持从即时通讯应用接收任务。只要配置完成，对应渠道会自动启动，而且都不需要公网 IP。
-
-| 渠道 | 传输方式 | 上手难度 |
-|---------|-----------|------------|
-| Telegram | Bot API（long-polling） | 简单 |
-| Slack | Socket Mode | 中等 |
-| Feishu / Lark | WebSocket | 中等 |
-
-**`config.yaml` 中的配置示例：**
-
-```yaml
-channels:
-  # LangGraph Server URL（默认：http://localhost:2024）
-  langgraph_url: http://localhost:2024
-  # Gateway API URL（默认：http://localhost:8001）
-  gateway_url: http://localhost:8001
-
-  # 可选：所有移动端渠道共用的全局 session 默认值
-  session:
-    assistant_id: lead_agent  # 也可以填自定义 agent 名；渠道层会自动转换为 lead_agent + agent_name
-    config:
-      recursion_limit: 100
-    context:
-      thinking_enabled: true
-      is_plan_mode: false
-      subagent_enabled: false
-
-  feishu:
-    enabled: true
-    app_id: $FEISHU_APP_ID
-    app_secret: $FEISHU_APP_SECRET
-    # domain: https://open.feishu.cn       # 国内版（默认）
-    # domain: https://open.larksuite.com   # 国际版
-
-  slack:
-    enabled: true
-    bot_token: $SLACK_BOT_TOKEN     # xoxb-...
-    app_token: $SLACK_APP_TOKEN     # xapp-...（Socket Mode）
-    allowed_users: []               # 留空表示允许所有人
-
-  telegram:
-    enabled: true
-    bot_token: $TELEGRAM_BOT_TOKEN
-    allowed_users: []               # 留空表示允许所有人
-
-    # 可选：按渠道 / 按用户单独覆盖 session 配置
-    session:
-      assistant_id: mobile-agent  # 这里同样支持自定义 agent 名
-      context:
-        thinking_enabled: false
-      users:
-        "123456789":
-          assistant_id: vip-agent
-          config:
-            recursion_limit: 150
-          context:
-            thinking_enabled: true
-            subagent_enabled: true
-```
-
-说明：
-- `assistant_id: lead_agent` 会直接调用默认的 LangGraph assistant。
-- 如果 `assistant_id` 填的是自定义 agent 名，DeerFlow 仍然会走 `lead_agent`，同时把该值注入为 `agent_name`，这样 IM 渠道也会生效对应 agent 的 SOUL 和配置。
-
-在 `.env` 里设置对应的 API key：
-
-```bash
-# Telegram
-TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
-
-# Slack
-SLACK_BOT_TOKEN=xoxb-...
-SLACK_APP_TOKEN=xapp-...
-
-# Feishu / Lark
-FEISHU_APP_ID=cli_xxxx
-FEISHU_APP_SECRET=your_app_secret
-```
-
-**Telegram 配置**
-
-1. 打开 [@BotFather](https://t.me/BotFather)，发送 `/newbot`，复制生成的 HTTP API token。
-2. 在 `.env` 中设置 `TELEGRAM_BOT_TOKEN`，并在 `config.yaml` 里启用该渠道。
-
-**Slack 配置**
-
-1. 前往 [api.slack.com/apps](https://api.slack.com/apps) 创建 Slack App：Create New App → From scratch。
-2. 在 **OAuth & Permissions** 中添加 Bot Token Scopes：`app_mentions:read`、`chat:write`、`im:history`、`im:read`、`im:write`、`files:write`。
-3. 启用 **Socket Mode**，生成带 `connections:write` 权限的 App-Level Token（`xapp-...`）。
-4. 在 **Event Subscriptions** 中订阅 bot events：`app_mention`、`message.im`。
-5. 在 `.env` 中设置 `SLACK_BOT_TOKEN` 和 `SLACK_APP_TOKEN`，并在 `config.yaml` 中启用该渠道。
-
-**Feishu / Lark 配置**
-
-1. 在 [飞书开放平台](https://open.feishu.cn/) 创建应用，并启用 **Bot** 能力。
-2. 添加权限：`im:message`、`im:message.p2p_msg:readonly`、`im:resource`。
-3. 在 **事件订阅** 中订阅 `im.message.receive_v1`，连接方式选择 **长连接**。
-4. 复制 App ID 和 App Secret，在 `.env` 中设置 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET`，并在 `config.yaml` 中启用该渠道。
-
-**命令**
-
-渠道连接完成后，你可以直接在聊天窗口里和 DeerFlow 交互：
-
-| 命令 | 说明 |
-|---------|-------------|
-| `/new` | 开启新对话 |
-| `/status` | 查看当前 thread 信息 |
-| `/models` | 列出可用模型 |
-| `/memory` | 查看 memory |
-| `/help` | 查看帮助 |
-
-> 没有命令前缀的消息会被当作普通聊天处理。DeerFlow 会自动创建 thread，并以对话方式回复。
-
-#### LangSmith 链路追踪
-
-DeerFlow 内置了 [LangSmith](https://smith.langchain.com) 集成，用于可观测性。启用后，所有 LLM 调用、agent 运行和工具执行都会被追踪，并在 LangSmith 仪表盘中展示。
-
-在 `.env` 文件中添加以下配置：
-
-```bash
-LANGSMITH_TRACING=true
-LANGSMITH_ENDPOINT=https://api.smith.langchain.com
-LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
-LANGSMITH_PROJECT=xxx
-```
-
-Docker 部署时，追踪默认关闭。在 `.env` 中设置 `LANGSMITH_TRACING=true` 和 `LANGSMITH_API_KEY` 即可启用。
-
-## 从 Deep Research 到 Super Agent Harness
-
-DeerFlow 最初是一个 Deep Research 框架，后来社区把它一路推到了更远的地方。上线之后，开发者拿它去做的事情早就不止研究：搭数据流水线、生成演示文稿、快速起 dashboard、自动化内容流程，很多方向一开始连我们自己都没想到。
-
-这让我们意识到一件事：DeerFlow 不只是一个研究工具。它更像一个 **harness**，一个真正让 agents 把事情做完的运行时基础设施。
-
-所以我们把它从头重做了一遍。
-
-DeerFlow 2.0 不再是一个需要你自己拼装的 framework。它是一个开箱即用、同时又足够可扩展的 super agent harness。基于 LangGraph 和 LangChain 构建，默认就带上了 agent 真正会用到的关键能力：文件系统、memory、skills、sandbox 执行环境，以及为复杂多步骤任务做规划、拉起 sub-agents 的能力。
-
-你可以直接拿来用，也可以拆开重组，改成你自己的样子。
-
-## 核心特性
-
-### Skills 与 Tools
-
-Skills 是 DeerFlow 能做“几乎任何事”的关键。
-
-标准的 Agent Skill 是一种结构化能力模块，通常就是一个 Markdown 文件，里面定义了工作流、最佳实践，以及相关的参考资源。DeerFlow 自带一批内置 skills，覆盖研究、报告生成、演示文稿制作、网页生成、图像和视频生成等场景。真正有意思的地方在于它的扩展性：你可以加自己的 skills，替换内置 skills，或者把多个 skills 组合成复合工作流。
-
-Skills 采用按需渐进加载，不会一次性把所有内容都塞进上下文。只有任务确实需要时才加载，这样能把上下文窗口控制得更干净，也更适合对 token 比较敏感的模型。
-
-通过 Gateway 安装 `.skill` 压缩包时，DeerFlow 会接受标准的可选 frontmatter 元数据，比如 `version`、`author`、`compatibility`，不会把本来合法的外部 skill 拒之门外。
-
-Tools 也是同样的思路。DeerFlow 自带一组核心工具：网页搜索、网页抓取、文件操作、bash 执行；同时也支持通过 MCP Server 和 Python 函数扩展自定义工具。你可以替换任何一项，也可以继续往里加。
-
-Gateway 生成后续建议时，现在会先把普通字符串输出和 block/list 风格的富文本内容统一归一化，再去解析 JSON 数组响应，因此不同 provider 的内容包装方式不会再悄悄把建议吞掉。
-
-```text
-# sandbox 容器内的路径
-/mnt/skills/public
-├── research/SKILL.md
-├── report-generation/SKILL.md
-├── slide-creation/SKILL.md
-├── web-page/SKILL.md
-└── image-generation/SKILL.md
-
-/mnt/skills/custom
-└── your-custom-skill/SKILL.md      ← 你的 skill
-```
-
-#### Claude Code 集成
-
-借助 `claude-to-deerflow` skill，你可以直接在 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 里和正在运行的 DeerFlow 实例交互。不用离开终端，就能下发研究任务、查看状态、管理 threads。
-
-**安装这个 skill：**
-
-```bash
-npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow
-```
-
-然后确认 DeerFlow 已经启动（默认地址是 `http://localhost:2026`），在 Claude Code 里使用 `/claude-to-deerflow` 命令即可。
-
-**你可以做的事情包括：**
-- 给 DeerFlow 发送消息，并接收流式响应
-- 选择执行模式：flash（更快）、standard、pro（规划模式）、ultra（sub-agents 模式）
-- 检查 DeerFlow 健康状态，列出 models / skills / agents
-- 管理 threads 和会话历史
-- 上传文件做分析
-
-**环境变量**（可选，用于自定义端点）：
-
-```bash
-DEERFLOW_URL=http://localhost:2026            # 统一代理基地址
-DEERFLOW_GATEWAY_URL=http://localhost:2026    # Gateway API
-DEERFLOW_LANGGRAPH_URL=http://localhost:2026/api/langgraph  # LangGraph API
-```
-
-完整 API 说明见 [`skills/public/claude-to-deerflow/SKILL.md`](skills/public/claude-to-deerflow/SKILL.md)。
-
-### Sub-Agents
-
-复杂任务通常不可能一次完成，DeerFlow 会先拆解，再执行。
-
-lead agent 可以按需动态拉起 sub-agents。每个 sub-agent 都有自己独立的上下文、工具和终止条件。只要条件允许，它们就会并行运行，返回结构化结果，最后再由 lead agent 汇总成一份完整输出。
-
-这也是 DeerFlow 能处理从几分钟到几小时任务的原因。比如一个研究任务，可以拆成十几个 sub-agents，分别探索不同方向，最后合并成一份报告，或者一个网站，或者一套带生成视觉内容的演示文稿。一个 harness，多路并行。
-
-### Sandbox 与文件系统
-
-DeerFlow 不只是“会说它能做”，它是真的有一台自己的“电脑”。
-
-每个任务都运行在隔离的 Docker 容器里，里面有完整的文件系统，包括 skills、workspace、uploads、outputs。agent 可以读写和编辑文件，可以执行 bash 命令和代码，也可以查看图片。整个过程都在 sandbox 内完成，可审计、会隔离，不会在不同 session 之间互相污染。
-
-这就是“带工具的聊天机器人”和“真正有执行环境的 agent”之间的差别。
-
-```text
-# sandbox 容器内的路径
-/mnt/user-data/
-├── uploads/          ← 你的文件
-├── workspace/        ← agents 的工作目录
-└── outputs/          ← 最终交付物
-```
-
-### Context Engineering
-
-**隔离的 Sub-Agent Context**：每个 sub-agent 都在自己独立的上下文里运行。它看不到主 agent 的上下文，也看不到其他 sub-agents 的上下文。这样做的目的很直接，就是让它只聚焦当前任务，不被无关信息干扰。
-
-**摘要压缩**：在单个 session 内，DeerFlow 会比较积极地管理上下文，包括总结已完成的子任务、把中间结果转存到文件系统、压缩暂时不重要的信息。这样在长链路、多步骤任务里，它也能保持聚焦，而不会轻易把上下文窗口打爆。
-
-### 长期记忆
-
-大多数 agents 会在对话结束后把一切都忘掉，DeerFlow 不一样。
-
-跨 session 使用时，DeerFlow 会逐步积累关于你的持久 memory，包括你的个人偏好、知识背景，以及长期沉淀下来的工作习惯。你用得越多，它越了解你的写作风格、技术栈和重复出现的工作流。memory 保存在本地，控制权也始终在你手里。
-
-## 推荐模型
-
-DeerFlow 对模型没有强绑定，只要实现了 OpenAI 兼容 API 的 LLM，理论上都可以接入。不过在下面这些能力上表现更强的模型，通常会更适合 DeerFlow：
-
-- **长上下文窗口**（100k+ tokens），适合深度研究和多步骤任务
-- **推理能力**，适合自适应规划和复杂拆解
-- **多模态输入**，适合理解图片和视频
-- **稳定的 tool use 能力**，适合可靠的函数调用和结构化输出
-
-## 内嵌 Python Client
-
-DeerFlow 也可以作为内嵌的 Python 库使用，不必启动完整的 HTTP 服务。`DeerFlowClient` 提供了进程内的直接访问方式，覆盖所有 agent 和 Gateway 能力，返回的数据结构与 HTTP Gateway API 保持一致：
-
-```python
-from deerflow.client import DeerFlowClient
-
-client = DeerFlowClient()
-
-# Chat
-response = client.chat("Analyze this paper for me", thread_id="my-thread")
-
-# Streaming（LangGraph SSE 协议：values、messages-tuple、end）
-for event in client.stream("hello"):
-    if event.type == "messages-tuple" and event.data.get("type") == "ai":
-        print(event.data["content"])
-
-# 配置与管理：返回值与 Gateway 对齐的 dict
-models = client.list_models()        # {"models": [...]}
-skills = client.list_skills()        # {"skills": [...]}
-client.update_skill("web-search", enabled=True)
-client.upload_files("thread-1", ["./report.pdf"])  # {"success": True, "files": [...]}
-```
-
-所有返回 dict 的方法都会在 CI 中通过 Gateway 的 Pydantic 响应模型校验（`TestGatewayConformance`），以确保内嵌 client 始终和 HTTP API schema 保持同步。完整 API 说明见 `backend/packages/harness/deerflow/client.py`。
-
-## 文档
-
-- [贡献指南](CONTRIBUTING.md) - 开发环境搭建与协作流程
-- [配置指南](backend/docs/CONFIGURATION.md) - 安装与配置说明
-- [架构概览](backend/CLAUDE.md) - 技术架构说明
-- [后端架构](backend/README.md) - 后端架构与 API 参考
-
-## ⚠️ 安全使用
-
-### 不恰当的部署可能导致安全风险
-
-DeerFlow 具备**系统指令执行、资源操作、业务逻辑调用**等关键高权限能力，默认设计为**部署在本地可信环境（仅本机 127.0.0.1 回环访问）**。若您将 agent 部署至不可信局域网、公网云服务器等可被多终端访问的网络环境，且未采取严格的安全防护措施，可能导致安全风险，例如：
-
-- **未授权的非法调用**：agent 功能被未授权的第三方、公网恶意扫描程序探测到，进而发起批量非法调用请求，执行系统命令、文件读写等高危操作，可能导致安全后果。
-- **合规与法律风险**：若 agent 被非法调用用于实施网络攻击、信息窃取等违法违规行为，可能产生法律责任与合规风险。
-
-### 安全使用建议
-
-**注意：建议您将 DeerFlow 部署在本地可信的网络环境下。** 若您有跨设备、跨网络的部署需求，必须加入严格的安全措施。例如，采取如下手段：
-
-- **设置访问 IP 白名单**：使用 `iptables`，或部署硬件防火墙 / 带访问控制（ACL）功能的交换机等，**配置规则设置 IP 白名单**，拒绝其他所有 IP 进行访问。
-- **前置身份验证**：配置反向代理（nginx 等），并**开启高强度的前置身份验证功能**，禁止无任何身份验证的访问。
-- **网络隔离**：若有可能，建议将 agent 和可信设备划分到**同一个专用 VLAN**，与其他网络设备做隔离。
-- **持续关注项目更新**：请持续关注 DeerFlow 项目的安全功能更新。
-
-## 参与贡献
-
-欢迎参与贡献。开发环境、工作流和相关规范见 [CONTRIBUTING.md](CONTRIBUTING.md)。
-
-目前回归测试已经覆盖 Docker sandbox 模式识别，以及 `backend/tests/` 中 provisioner kubeconfig-path 处理相关测试。
-
-## 许可证
-
-本项目采用 [MIT License](./LICENSE) 开源发布。
-
-## 致谢
-
-DeerFlow 建立在开源社区大量优秀工作的基础上。所有让 DeerFlow 成为可能的项目和贡献者，我们都心怀感谢。毫不夸张地说，我们是站在巨人的肩膀上继续往前走。
-
-特别感谢以下项目带来的关键支持：
-
-- **[LangChain](https://github.com/langchain-ai/langchain)**：它们提供的优秀框架支撑了我们的 LLM 交互与 chains，让整体集成和能力编排顺畅可用。
-- **[LangGraph](https://github.com/langchain-ai/langgraph)**：它们在多 agent 编排上的创新方式，是 DeerFlow 复杂工作流得以成立的重要基础。
-
-这些项目体现了开源协作真正的力量，我们也很高兴能继续建立在这些基础之上。
-
-### 核心贡献者
-
-感谢 `DeerFlow` 的核心作者，是他们的判断、投入和持续推进，才让这个项目真正落地：
-
-- **[Daniel Walnut](https://github.com/hetaoBackend/)**
-- **[Henry Li](https://github.com/magiccube/)**
-
-## Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=bytedance/deer-flow&type=Date)](https://star-history.com/#bytedance/deer-flow&Date)

SECURITY.md

@@ -2,8 +2,8 @@
 
 ## Supported Versions
 
-As deer-flow doesn't provide an official release yet, please use the latest version for the security updates.
-Currently, we have two branches to maintain:
+As deer-flow doesn't provide an offical release yet, please use the latest version for the security updates.
+Current we have two branches to maintain: 
 * main branch for deer-flow 2.x
 * main-1.x branch for deer-flow 1.x 
 

backend/AGENTS.md

@@ -1,2 +1,2 @@
-For the backend architecture and design patterns:
+For the backend architeture and design patterns:
 @./CLAUDE.md

backend/CLAUDE.md

@@ -8,7 +8,7 @@ DeerFlow is a LangGraph-based AI super agent system with a full-stack architectu
 
 **Architecture**:
 - **LangGraph Server** (port 2024): Agent runtime and workflow execution
-- **Gateway API** (port 8001): REST API for models, MCP, skills, memory, artifacts, uploads, and local thread cleanup
+- **Gateway API** (port 8001): REST API for models, MCP, skills, memory, artifacts, and uploads
 - **Frontend** (port 3000): Next.js web interface
 - **Nginx** (port 2026): Unified reverse proxy entry point
 - **Provisioner** (port 8002, optional in Docker dev): Started only when sandbox is configured for provisioner/Kubernetes mode
@@ -22,38 +22,33 @@ deer-flow/
 ├── backend/                    # Backend application (this directory)
 │   ├── Makefile               # Backend-only commands (dev, gateway, lint)
 │   ├── langgraph.json         # LangGraph server configuration
-│   ├── packages/
-│   │   └── harness/           # deerflow-harness package (import: deerflow.*)
-│   │       ├── pyproject.toml
-│   │       └── deerflow/
-│   │           ├── agents/            # LangGraph agent system
-│   │           │   ├── lead_agent/    # Main agent (factory + system prompt)
-│   │           │   ├── middlewares/   # 10 middleware components
-│   │           │   ├── memory/        # Memory extraction, queue, prompts
-│   │           │   └── thread_state.py # ThreadState schema
-│   │           ├── sandbox/           # Sandbox execution system
-│   │           │   ├── local/         # Local filesystem provider
-│   │           │   ├── sandbox.py     # Abstract Sandbox interface
-│   │           │   ├── tools.py       # bash, ls, read/write/str_replace
-│   │           │   └── middleware.py  # Sandbox lifecycle management
-│   │           ├── subagents/         # Subagent delegation system
-│   │           │   ├── builtins/      # general-purpose, bash agents
-│   │           │   ├── executor.py    # Background execution engine
-│   │           │   └── registry.py    # Agent registry
-│   │           ├── tools/builtins/    # Built-in tools (present_files, ask_clarification, view_image)
-│   │           ├── mcp/               # MCP integration (tools, cache, client)
-│   │           ├── models/            # Model factory with thinking/vision support
-│   │           ├── skills/            # Skills discovery, loading, parsing
-│   │           ├── config/            # Configuration system (app, model, sandbox, tool, etc.)
-│   │           ├── community/         # Community tools (tavily, jina_ai, firecrawl, image_search, aio_sandbox)
-│   │           ├── reflection/        # Dynamic module loading (resolve_variable, resolve_class)
-│   │           ├── utils/             # Utilities (network, readability)
-│   │           └── client.py          # Embedded Python client (DeerFlowClient)
-│   ├── app/                   # Application layer (import: app.*)
+│   ├── src/
+│   │   ├── agents/            # LangGraph agent system
+│   │   │   ├── lead_agent/    # Main agent (factory + system prompt)
+│   │   │   ├── middlewares/   # 10 middleware components
+│   │   │   ├── memory/        # Memory extraction, queue, prompts
+│   │   │   └── thread_state.py # ThreadState schema
 │   │   ├── gateway/           # FastAPI Gateway API
 │   │   │   ├── app.py         # FastAPI application
-│   │   │   └── routers/       # FastAPI route modules (models, mcp, memory, skills, uploads, threads, artifacts, agents, suggestions, channels)
-│   │   └── channels/          # IM platform integrations
+│   │   │   └── routers/       # 6 route modules
+│   │   ├── sandbox/           # Sandbox execution system
+│   │   │   ├── local/         # Local filesystem provider
+│   │   │   ├── sandbox.py     # Abstract Sandbox interface
+│   │   │   ├── tools.py       # bash, ls, read/write/str_replace
+│   │   │   └── middleware.py  # Sandbox lifecycle management
+│   │   ├── subagents/         # Subagent delegation system
+│   │   │   ├── builtins/      # general-purpose, bash agents
+│   │   │   ├── executor.py    # Background execution engine
+│   │   │   └── registry.py    # Agent registry
+│   │   ├── tools/builtins/    # Built-in tools (present_files, ask_clarification, view_image)
+│   │   ├── mcp/               # MCP integration (tools, cache, client)
+│   │   ├── models/            # Model factory with thinking/vision support
+│   │   ├── skills/            # Skills discovery, loading, parsing
+│   │   ├── config/            # Configuration system (app, model, sandbox, tool, etc.)
+│   │   ├── community/         # Community tools (tavily, jina_ai, firecrawl, image_search, aio_sandbox)
+│   │   ├── reflection/        # Dynamic module loading (resolve_variable, resolve_class)
+│   │   ├── utils/             # Utilities (network, readability)
+│   │   └── client.py          # Embedded Python client (DeerFlowClient)
 │   ├── tests/                 # Test suite
 │   └── docs/                  # Documentation
 ├── frontend/                   # Next.js frontend application
@@ -79,7 +74,7 @@ When making code changes, you MUST update the relevant documentation:
 ```bash
 make check      # Check system requirements
 make install    # Install all dependencies (frontend + backend)
-make dev        # Start all services (LangGraph + Gateway + Frontend + Nginx), with config.yaml preflight
+make dev        # Start all services (LangGraph + Gateway + Frontend + Nginx)
 make stop       # Stop all services
 ```
 
@@ -97,48 +92,19 @@ Regression tests related to Docker/provisioner behavior:
 - `tests/test_docker_sandbox_mode_detection.py` (mode detection from `config.yaml`)
 - `tests/test_provisioner_kubeconfig.py` (kubeconfig file/directory handling)
 
-Boundary check (harness → app import firewall):
-- `tests/test_harness_boundary.py` — ensures `packages/harness/deerflow/` never imports from `app.*`
-
 CI runs these regression tests for every pull request via [.github/workflows/backend-unit-tests.yml](../.github/workflows/backend-unit-tests.yml).
 
 ## Architecture
 
-### Harness / App Split
-
-The backend is split into two layers with a strict dependency direction:
-
-- **Harness** (`packages/harness/deerflow/`): Publishable agent framework package (`deerflow-harness`). Import prefix: `deerflow.*`. Contains agent orchestration, tools, sandbox, models, MCP, skills, config — everything needed to build and run agents.
-- **App** (`app/`): Unpublished application code. Import prefix: `app.*`. Contains the FastAPI Gateway API and IM channel integrations (Feishu, Slack, Telegram).
-
-**Dependency rule**: App imports deerflow, but deerflow never imports app. This boundary is enforced by `tests/test_harness_boundary.py` which runs in CI.
-
-**Import conventions**:
-```python
-# Harness internal
-from deerflow.agents import make_lead_agent
-from deerflow.models import create_chat_model
-
-# App internal
-from app.gateway.app import app
-from app.channels.service import start_channel_service
-
-# App → Harness (allowed)
-from deerflow.config import get_app_config
-
-# Harness → App (FORBIDDEN — enforced by test_harness_boundary.py)
-# from app.gateway.routers.uploads import ...  # ← will fail CI
-```
-
 ### Agent System
 
-**Lead Agent** (`packages/harness/deerflow/agents/lead_agent/agent.py`):
+**Lead Agent** (`src/agents/lead_agent/agent.py`):
 - Entry point: `make_lead_agent(config: RunnableConfig)` registered in `langgraph.json`
 - Dynamic model selection via `create_chat_model()` with thinking/vision support
 - Tools loaded via `get_available_tools()` - combines sandbox, built-in, MCP, community, and subagent tools
 - System prompt generated by `apply_prompt_template()` with skills, memory, and subagent instructions
 
-**ThreadState** (`packages/harness/deerflow/agents/thread_state.py`):
+**ThreadState** (`src/agents/thread_state.py`):
 - Extends `AgentState` with: `sandbox`, `thread_data`, `title`, `artifacts`, `todos`, `uploaded_files`, `viewed_images`
 - Uses custom reducers: `merge_artifacts` (deduplicate), `merge_viewed_images` (merge/clear)
 
@@ -150,20 +116,19 @@ from deerflow.config import get_app_config
 
 ### Middleware Chain
 
-Middlewares execute in strict order in `packages/harness/deerflow/agents/lead_agent/agent.py`:
+Middlewares execute in strict order in `src/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
+1. **ThreadDataMiddleware** - Creates per-thread directories (`backend/.deer-flow/threads/{thread_id}/user-data/{workspace,uploads,outputs}`)
 2. **UploadsMiddleware** - Tracks and injects newly uploaded files into conversation
 3. **SandboxMiddleware** - Acquires sandbox, stores `sandbox_id` in state
 4. **DanglingToolCallMiddleware** - Injects placeholder ToolMessages for AIMessage tool_calls that lack responses (e.g., due to user interruption)
-5. **GuardrailMiddleware** - Pre-tool-call authorization via pluggable `GuardrailProvider` protocol (optional, if `guardrails.enabled` in config). Evaluates each tool call and returns error ToolMessage on deny. Three provider options: built-in `AllowlistProvider` (zero deps), OAP policy providers (e.g. `aport-agent-guardrails`), or custom providers. See [docs/GUARDRAILS.md](docs/GUARDRAILS.md) for setup, usage, and how to implement a provider.
-6. **SummarizationMiddleware** - Context reduction when approaching token limits (optional, if enabled)
-7. **TodoListMiddleware** - Task tracking with `write_todos` tool (optional, if plan_mode)
-8. **TitleMiddleware** - Auto-generates thread title after first complete exchange and normalizes structured message content before prompting the title model
-9. **MemoryMiddleware** - Queues conversations for async memory update (filters to user + final AI responses)
-10. **ViewImageMiddleware** - Injects base64 image data before LLM call (conditional on vision support)
-11. **SubagentLimitMiddleware** - Truncates excess `task` tool calls from model response to enforce `MAX_CONCURRENT_SUBAGENTS` limit (optional, if subagent_enabled)
-12. **ClarificationMiddleware** - Intercepts `ask_clarification` tool calls, interrupts via `Command(goto=END)` (must be last)
+5. **SummarizationMiddleware** - Context reduction when approaching token limits (optional, if enabled)
+6. **TodoListMiddleware** - Task tracking with `write_todos` tool (optional, if plan_mode)
+7. **TitleMiddleware** - Auto-generates thread title after first complete exchange
+8. **MemoryMiddleware** - Queues conversations for async memory update (filters to user + final AI responses)
+9. **ViewImageMiddleware** - Injects base64 image data before LLM call (conditional on vision support)
+10. **SubagentLimitMiddleware** - Truncates excess `task` tool calls from model response to enforce `MAX_CONCURRENT_SUBAGENTS` limit (optional, if subagent_enabled)
+11. **ClarificationMiddleware** - Intercepts `ask_clarification` tool calls, interrupts via `Command(goto=END)` (must be last)
 
 ### Configuration System
 
@@ -171,10 +136,6 @@ Middlewares execute in strict order in `packages/harness/deerflow/agents/lead_ag
 
 Setup: Copy `config.example.yaml` to `config.yaml` in the **project root** directory.
 
-**Config Versioning**: `config.example.yaml` has a `config_version` field. On startup, `AppConfig.from_file()` compares user version vs example version and emits a warning if outdated. Missing `config_version` = version 0. Run `make config-upgrade` to auto-merge missing fields. When changing the config schema, bump `config_version` in `config.example.yaml`.
-
-**Config Caching**: `get_app_config()` caches the parsed config, but automatically reloads it when the resolved config path changes or the file's mtime increases. This keeps Gateway and LangGraph reads aligned with `config.yaml` edits without requiring a manual process restart.
-
 Configuration priority:
 1. Explicit `config_path` argument
 2. `DEER_FLOW_CONFIG_PATH` environment variable
@@ -182,7 +143,6 @@ Configuration priority:
 4. `config.yaml` in parent directory (project root - **recommended location**)
 
 Config values starting with `$` are resolved as environment variables (e.g., `$OPENAI_API_KEY`).
-`ModelConfig` also declares `use_responses_api` and `output_version` so OpenAI `/v1/responses` can be enabled explicitly while still using `langchain_openai:ChatOpenAI`.
 
 **Extensions Configuration** (`extensions_config.json`):
 
@@ -194,7 +154,7 @@ Configuration priority:
 3. `extensions_config.json` in current directory (backend/)
 4. `extensions_config.json` in parent directory (project root - **recommended location**)
 
-### Gateway API (`app/gateway/`)
+### Gateway API (`src/gateway/`)
 
 FastAPI application on port 8001 with health check at `GET /health`.
 
@@ -204,22 +164,20 @@ FastAPI application on port 8001 with health check at `GET /health`.
 |--------|-----------|
 | **Models** (`/api/models`) | `GET /` - list models; `GET /{name}` - model details |
 | **MCP** (`/api/mcp`) | `GET /config` - get config; `PUT /config` - update config (saves to extensions_config.json) |
-| **Skills** (`/api/skills`) | `GET /` - list skills; `GET /{name}` - details; `PUT /{name}` - update enabled; `POST /install` - install from .skill archive (accepts standard optional frontmatter like `version`, `author`, `compatibility`) |
+| **Skills** (`/api/skills`) | `GET /` - list skills; `GET /{name}` - details; `PUT /{name}` - update enabled; `POST /install` - install from .skill archive |
 | **Memory** (`/api/memory`) | `GET /` - memory data; `POST /reload` - force reload; `GET /config` - config; `GET /status` - config + data |
 | **Uploads** (`/api/threads/{id}/uploads`) | `POST /` - upload files (auto-converts PDF/PPT/Excel/Word); `GET /list` - list; `DELETE /{filename}` - delete |
-| **Threads** (`/api/threads/{id}`) | `DELETE /` - remove DeerFlow-managed local thread data after LangGraph thread deletion; unexpected failures are logged server-side and return a generic 500 detail |
-| **Artifacts** (`/api/threads/{id}/artifacts`) | `GET /{path}` - serve artifacts; active content types (`text/html`, `application/xhtml+xml`, `image/svg+xml`) are always forced as download attachments to reduce XSS risk; `?download=true` still forces download for other file types |
-| **Suggestions** (`/api/threads/{id}/suggestions`) | `POST /` - generate follow-up questions; rich list/block model content is normalized before JSON parsing |
+| **Artifacts** (`/api/threads/{id}/artifacts`) | `GET /{path}` - serve artifacts; `?download=true` for file download |
 
 Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` → Gateway.
 
-### Sandbox System (`packages/harness/deerflow/sandbox/`)
+### Sandbox System (`src/sandbox/`)
 
 **Interface**: Abstract `Sandbox` with `execute_command`, `read_file`, `write_file`, `list_dir`
 **Provider Pattern**: `SandboxProvider` with `acquire`, `get`, `release` lifecycle
 **Implementations**:
 - `LocalSandboxProvider` - Singleton local filesystem execution with path mappings
-- `AioSandboxProvider` (`packages/harness/deerflow/community/`) - Docker-based isolation
+- `AioSandboxProvider` (`src/community/`) - Docker-based isolation
 
 **Virtual Path System**:
 - Agent sees: `/mnt/user-data/{workspace,uploads,outputs}`, `/mnt/skills`
@@ -227,14 +185,14 @@ Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` →
 - Translation: `replace_virtual_path()` / `replace_virtual_paths_in_command()`
 - Detection: `is_local_sandbox()` checks `sandbox_id == "local"`
 
-**Sandbox Tools** (in `packages/harness/deerflow/sandbox/tools.py`):
+**Sandbox Tools** (in `src/sandbox/tools.py`):
 - `bash` - Execute commands with path translation and error handling
 - `ls` - Directory listing (tree format, max 2 levels)
 - `read_file` - Read file contents with optional line range
 - `write_file` - Write/append to files, creates directories
 - `str_replace` - Substring replacement (single or all occurrences)
 
-### Subagent System (`packages/harness/deerflow/subagents/`)
+### Subagent System (`src/subagents/`)
 
 **Built-in Agents**: `general-purpose` (all tools except `task`) and `bash` (command specialist)
 **Execution**: Dual thread pool - `_scheduler_pool` (3 workers) + `_execution_pool` (3 workers)
@@ -242,7 +200,7 @@ Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` →
 **Flow**: `task()` tool → `SubagentExecutor` → background thread → poll 5s → SSE events → result
 **Events**: `task_started`, `task_running`, `task_completed`/`task_failed`/`task_timed_out`
 
-### Tool System (`packages/harness/deerflow/tools/`)
+### Tool System (`src/tools/`)
 
 `get_available_tools(groups, include_mcp, model_name, subagent_enabled)` assembles:
 1. **Config-defined tools** - Resolved from `config.yaml` via `resolve_variable()`
@@ -254,19 +212,13 @@ Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` →
 4. **Subagent tool** (if enabled):
    - `task` - Delegate to subagent (description, prompt, subagent_type, max_turns)
 
-**Community tools** (`packages/harness/deerflow/community/`):
+**Community tools** (`src/community/`):
 - `tavily/` - Web search (5 results default) and web fetch (4KB limit)
 - `jina_ai/` - Web fetch via Jina reader API with readability extraction
 - `firecrawl/` - Web scraping via Firecrawl API
-
-**ACP agent tools**:
-- `invoke_acp_agent` - Invokes external ACP-compatible agents from `config.yaml`
-- ACP launchers must be real ACP adapters. The standard `codex` CLI is not ACP-compatible by itself; configure a wrapper such as `npx -y @zed-industries/codex-acp` or an installed `codex-acp` binary
-- Missing ACP executables now return an actionable error message instead of a raw `[Errno 2]`
-- Each ACP agent uses a per-thread workspace at `{base_dir}/threads/{thread_id}/acp-workspace/`. The workspace is accessible to the lead agent via the virtual path `/mnt/acp-workspace/` (read-only). In docker sandbox mode, the directory is volume-mounted into the container at `/mnt/acp-workspace` (read-only); in local sandbox mode, path translation is handled by `tools.py`
 - `image_search/` - Image search via DuckDuckGo
 
-### MCP System (`packages/harness/deerflow/mcp/`)
+### MCP System (`src/mcp/`)
 
 - Uses `langchain-mcp-adapters` `MultiServerMCPClient` for multi-server management
 - **Lazy initialization**: Tools loaded on first use via `get_cached_mcp_tools()`
@@ -275,7 +227,7 @@ Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` →
 - **OAuth (HTTP/SSE)**: Supports token endpoint flows (`client_credentials`, `refresh_token`) with automatic token refresh + Authorization header injection
 - **Runtime updates**: Gateway API saves to extensions_config.json; LangGraph detects via mtime
 
-### Skills System (`packages/harness/deerflow/skills/`)
+### Skills System (`src/skills/`)
 
 - **Location**: `deer-flow/skills/{public,custom}/`
 - **Format**: Directory with `SKILL.md` (YAML frontmatter: name, description, license, allowed-tools)
@@ -283,7 +235,7 @@ Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` →
 - **Injection**: Enabled skills listed in agent system prompt with container paths
 - **Installation**: `POST /api/skills/install` extracts .skill ZIP archive to custom/ directory
 
-### Model Factory (`packages/harness/deerflow/models/factory.py`)
+### Model Factory (`src/models/factory.py`)
 
 - `create_chat_model(name, thinking_enabled)` instantiates LLM from config via reflection
 - Supports `thinking_enabled` flag with per-model `when_thinking_enabled` overrides
@@ -291,40 +243,10 @@ Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` →
 - Config values starting with `$` resolved as environment variables
 - Missing provider modules surface actionable install hints from reflection resolvers (for example `uv add langchain-google-genai`)
 
-### IM Channels System (`app/channels/`)
-
-Bridges external messaging platforms (Feishu, Slack, Telegram) to the DeerFlow agent via the LangGraph Server.
-
-**Architecture**: Channels communicate with the LangGraph Server through `langgraph-sdk` HTTP client (same as the frontend), ensuring threads are created and managed server-side.
+### Memory System (`src/agents/memory/`)
 
 **Components**:
-- `message_bus.py` - Async pub/sub hub (`InboundMessage` → queue → dispatcher; `OutboundMessage` → callbacks → channels)
-- `store.py` - JSON-file persistence mapping `channel_name:chat_id[:topic_id]` → `thread_id` (keys are `channel:chat` for root conversations and `channel:chat:topic` for threaded conversations)
-- `manager.py` - Core dispatcher: creates threads via `client.threads.create()`, routes commands, keeps Slack/Telegram on `client.runs.wait()`, and uses `client.runs.stream(["messages-tuple", "values"])` for Feishu incremental outbound updates
-- `base.py` - Abstract `Channel` base class (start/stop/send lifecycle)
-- `service.py` - Manages lifecycle of all configured channels from `config.yaml`
-- `slack.py` / `feishu.py` / `telegram.py` - Platform-specific implementations (`feishu.py` tracks the running card `message_id` in memory and patches the same card in place)
-
-**Message Flow**:
-1. External platform -> Channel impl -> `MessageBus.publish_inbound()`
-2. `ChannelManager._dispatch_loop()` consumes from queue
-3. For chat: look up/create thread on LangGraph Server
-4. Feishu chat: `runs.stream()` → accumulate AI text → publish multiple outbound updates (`is_final=False`) → publish final outbound (`is_final=True`)
-5. Slack/Telegram chat: `runs.wait()` → extract final response → publish outbound
-6. Feishu channel sends one running reply card up front, then patches the same card for each outbound update (card JSON sets `config.update_multi=true` for Feishu's patch API requirement)
-7. For commands (`/new`, `/status`, `/models`, `/memory`, `/help`): handle locally or query Gateway API
-8. Outbound → channel callbacks → platform reply
-
-**Configuration** (`config.yaml` -> `channels`):
-- `langgraph_url` - LangGraph Server URL (default: `http://localhost:2024`)
-- `gateway_url` - Gateway API URL for auxiliary commands (default: `http://localhost:8001`)
-- In Docker Compose, IM channels run inside the `gateway` container, so `localhost` points back to that container. Use `http://langgraph:2024` / `http://gateway:8001`, or set `DEER_FLOW_CHANNELS_LANGGRAPH_URL` / `DEER_FLOW_CHANNELS_GATEWAY_URL`.
-- Per-channel configs: `feishu` (app_id, app_secret), `slack` (bot_token, app_token), `telegram` (bot_token)
-
-### Memory System (`packages/harness/deerflow/agents/memory/`)
-
-**Components**:
-- `updater.py` - LLM-based memory updates with fact extraction, whitespace-normalized fact deduplication (trims leading/trailing whitespace before comparing), and atomic file I/O
+- `updater.py` - LLM-based memory updates with fact extraction and atomic file I/O
 - `queue.py` - Debounced update queue (per-thread deduplication, configurable wait time)
 - `prompt.py` - Prompt templates for memory updates
 
@@ -337,11 +259,9 @@ Bridges external messaging platforms (Feishu, Slack, Telegram) to the DeerFlow a
 1. `MemoryMiddleware` filters messages (user inputs + final AI responses) and queues conversation
 2. Queue debounces (30s default), batches updates, deduplicates per-thread
 3. Background thread invokes LLM to extract context updates and facts
-4. Applies updates atomically (temp file + rename) with cache invalidation, skipping duplicate fact content before append
+4. Applies updates atomically (temp file + rename) with cache invalidation
 5. Next interaction injects top 15 facts + context into `<memory>` tags in system prompt
 
-Focused regression coverage for the updater lives in `backend/tests/test_memory_updater.py`.
-
 **Configuration** (`config.yaml` → `memory`):
 - `enabled` / `injection_enabled` - Master switches
 - `storage_path` - Path to memory.json
@@ -350,7 +270,7 @@ Focused regression coverage for the updater lives in `backend/tests/test_memory_
 - `max_facts` / `fact_confidence_threshold` - Fact storage limits (100 / 0.7)
 - `max_injection_tokens` - Token limit for prompt injection (2000)
 
-### Reflection System (`packages/harness/deerflow/reflection/`)
+### Reflection System (`src/reflection/`)
 
 - `resolve_variable(path)` - Import module and return variable (e.g., `module.path:variable_name`)
 - `resolve_class(path, base_class)` - Import and validate class against base class
@@ -374,11 +294,11 @@ Focused regression coverage for the updater lives in `backend/tests/test_memory_
 
 Both can be modified at runtime via Gateway API endpoints or `DeerFlowClient` methods.
 
-### Embedded Client (`packages/harness/deerflow/client.py`)
+### Embedded Client (`src/client.py`)
 
 `DeerFlowClient` provides direct in-process access to all DeerFlow capabilities without HTTP services. All return types align with the Gateway API response schemas, so consumer code works identically in HTTP and embedded modes.
 
-**Architecture**: Imports the same `deerflow` modules that LangGraph Server and Gateway API use. Shares the same config files and data directories. No FastAPI dependency.
+**Architecture**: Imports the same `src/` 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, returns final text
@@ -401,7 +321,7 @@ Both can be modified at runtime via Gateway API endpoints or `DeerFlowClient` me
 | Uploads | `upload_files(thread_id, files)`, `list_uploads(thread_id)`, `delete_upload(thread_id, filename)` | `{"success": true, "files": [...]}`, `{"files": [...], "count": N}` |
 | Artifacts | `get_artifact(thread_id, path)` → `(bytes, mime_type)` | tuple |
 
-**Key difference from Gateway**: Upload accepts local `Path` objects instead of HTTP `UploadFile`, rejects directory paths before copying, and reuses a single worker when document conversion must run inside an active event loop. Artifact returns `(bytes, mime_type)` instead of HTTP Response. The new Gateway-only thread cleanup route deletes `.deer-flow/threads/{thread_id}` after LangGraph thread deletion; there is no matching `DeerFlowClient` method yet. `update_mcp_config()` and `update_skill()` automatically invalidate the cached agent.
+**Key difference from Gateway**: Upload accepts local `Path` objects instead of HTTP `UploadFile`. Artifact returns `(bytes, mime_type)` instead of HTTP Response. `update_mcp_config()` and `update_skill()` automatically invalidate the cached agent.
 
 **Tests**: `tests/test_client.py` (77 unit tests including `TestGatewayConformance`), `tests/test_client_live.py` (live integration tests, requires config.yaml)
 
@@ -417,7 +337,7 @@ Both can be modified at runtime via Gateway API endpoints or `DeerFlowClient` me
 - Run the full suite before and after your change: `make test`
 - Tests must pass before a feature is considered complete
 - For lightweight config/utility modules, prefer pure unit tests with no external dependencies
-- If a module causes circular import issues in tests, add a `sys.modules` mock in `tests/conftest.py` (see existing example for `deerflow.subagents.executor`)
+- If a module causes circular import issues in tests, add a `sys.modules` mock in `tests/conftest.py` (see existing example for `src.subagents.executor`)
 
 ```bash
 # Run all tests
@@ -472,8 +392,6 @@ When using `make dev` from root, the frontend automatically connects through ngi
 Multi-file upload with automatic document conversion:
 - Endpoint: `POST /api/threads/{thread_id}/uploads`
 - Supports: PDF, PPT, Excel, Word documents (converted via `markitdown`)
-- Rejects directory inputs before copying so uploads stay all-or-nothing
-- Reuses one conversion worker per request when called from an active event loop
 - Files stored in thread-isolated directories
 - Agent receives uploaded file list via `UploadsMiddleware`
 

backend/CONTRIBUTING.md

@@ -227,7 +227,7 @@ Example test:
 
 ```python
 import pytest
-from deerflow.models.factory import create_chat_model
+from src.models.factory import create_chat_model
 
 def test_create_chat_model_with_valid_name():
     """Test that a valid model name creates a model instance."""
@@ -269,10 +269,10 @@ Include in your PR description:
 
 ### Adding New Tools
 
-1. Create tool in `packages/harness/deerflow/tools/builtins/` or `packages/harness/deerflow/community/`:
+1. Create tool in `src/tools/builtins/` or `src/community/`:
 
 ```python
-# packages/harness/deerflow/tools/builtins/my_tool.py
+# src/tools/builtins/my_tool.py
 from langchain_core.tools import tool
 
 @tool
@@ -294,15 +294,15 @@ def my_tool(param: str) -> str:
 tools:
   - name: my_tool
     group: my_group
-    use: deerflow.tools.builtins.my_tool:my_tool
+    use: src.tools.builtins.my_tool:my_tool
 ```
 
 ### Adding New Middleware
 
-1. Create middleware in `packages/harness/deerflow/agents/middlewares/`:
+1. Create middleware in `src/agents/middlewares/`:
 
 ```python
-# packages/harness/deerflow/agents/middlewares/my_middleware.py
+# src/agents/middlewares/my_middleware.py
 from langchain.agents.middleware import BaseMiddleware
 from langchain_core.runnables import RunnableConfig
 
@@ -315,7 +315,7 @@ class MyMiddleware(BaseMiddleware):
         return state
 ```
 
-2. Register in `packages/harness/deerflow/agents/lead_agent/agent.py`:
+2. Register in `src/agents/lead_agent/agent.py`:
 
 ```python
 middlewares = [
@@ -329,10 +329,10 @@ middlewares = [
 
 ### Adding New API Endpoints
 
-1. Create router in `app/gateway/routers/`:
+1. Create router in `src/gateway/routers/`:
 
 ```python
-# app/gateway/routers/my_router.py
+# src/gateway/routers/my_router.py
 from fastapi import APIRouter
 
 router = APIRouter(prefix="/my-endpoint", tags=["my-endpoint"])
@@ -348,10 +348,10 @@ async def create_item(data: dict):
     return {"created": data}
 ```
 
-2. Register in `app/gateway/app.py`:
+2. Register in `src/gateway/app.py`:
 
 ```python
-from app.gateway.routers import my_router
+from src.gateway.routers import my_router
 
 app.include_router(my_router.router)
 ```
@@ -360,7 +360,7 @@ app.include_router(my_router.router)
 
 When adding new configuration options:
 
-1. Update `packages/harness/deerflow/config/app_config.py` with new fields
+1. Update `src/config/app_config.py` with new fields
 2. Add default values in `config.example.yaml`
 3. Document in `docs/CONFIGURATION.md`
 

backend/Dockerfile

@@ -1,39 +1,15 @@
 # Backend Development Dockerfile
+FROM python:3.12-slim
 
-# UV source image (override for restricted networks that cannot reach ghcr.io)
-ARG UV_IMAGE=ghcr.io/astral-sh/uv:0.7.20
-FROM ${UV_IMAGE} AS uv-source
-
-FROM python:3.12-slim-bookworm
-
-ARG NODE_MAJOR=22
-ARG APT_MIRROR
-ARG UV_INDEX_URL
-
-# Optionally override apt mirror for restricted networks (e.g. APT_MIRROR=mirrors.aliyun.com)
-RUN if [ -n "${APT_MIRROR}" ]; then \
-      sed -i "s|deb.debian.org|${APT_MIRROR}|g" /etc/apt/sources.list.d/debian.sources 2>/dev/null || true; \
-      sed -i "s|deb.debian.org|${APT_MIRROR}|g" /etc/apt/sources.list 2>/dev/null || true; \
-    fi
-
-# Install system dependencies + Node.js (provides npx for MCP servers)
+# Install system dependencies
 RUN apt-get update && apt-get install -y \
     curl \
     build-essential \
-    gnupg \
-    ca-certificates \
-    && mkdir -p /etc/apt/keyrings \
-    && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
-    && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_${NODE_MAJOR}.x nodistro main" > /etc/apt/sources.list.d/nodesource.list \
-    && apt-get update \
-    && apt-get install -y nodejs \
     && rm -rf /var/lib/apt/lists/*
 
-# Install Docker CLI (for DooD: allows starting sandbox containers via host Docker socket)
-COPY --from=docker:cli /usr/local/bin/docker /usr/local/bin/docker
-
-# Install uv (source image overridable via UV_IMAGE build arg)
-COPY --from=uv-source /uv /uvx /usr/local/bin/
+# Install uv
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.local/bin:$PATH"
 
 # Set working directory
 WORKDIR /app
@@ -43,10 +19,10 @@ COPY backend ./backend
 
 # Install dependencies with cache mount
 RUN --mount=type=cache,target=/root/.cache/uv \
-    sh -c "cd backend && UV_INDEX_URL=${UV_INDEX_URL:-https://pypi.org/simple} uv sync"
+    sh -c "cd backend && uv sync"
 
 # Expose ports (gateway: 8001, langgraph: 2024)
 EXPOSE 8001 2024
 
 # Default command (can be overridden in docker-compose)
-CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]
+CMD ["sh", "-c", "uv run uvicorn src.gateway.app:app --host 0.0.0.0 --port 8001"]

backend/Makefile

@@ -5,14 +5,13 @@ dev:
 	uv run langgraph dev --no-browser --allow-blocking --no-reload
 
 gateway:
-	PYTHONPATH=. uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
+	uv run uvicorn src.gateway.app:app --host 0.0.0.0 --port 8001
 
 test:
 	PYTHONPATH=. uv run pytest tests/ -v
 
 lint:
 	uvx ruff check .
-	uvx ruff format --check .
 
 format:
 	uvx ruff check . --fix && uvx ruff format .

backend/README.md

@@ -36,7 +36,7 @@ DeerFlow is a LangGraph-based AI super agent with sandbox execution, persistent
 
 **Request Routing** (via Nginx):
 - `/api/langgraph/*` → LangGraph Server - agent interactions, threads, streaming
-- `/api/*` (other) → Gateway API - models, MCP, skills, memory, artifacts, uploads, thread-local cleanup
+- `/api/*` (other) → Gateway API - models, MCP, skills, memory, artifacts, uploads
 - `/` (non-API) → Frontend - Next.js web interface
 
 ---
@@ -78,13 +78,13 @@ Per-thread isolated execution with virtual path translation:
 - **Virtual paths**: `/mnt/user-data/{workspace,uploads,outputs}` → thread-specific physical directories
 - **Skills path**: `/mnt/skills` → `deer-flow/skills/` directory
 - **Skills loading**: Recursively discovers nested `SKILL.md` files under `skills/{public,custom}` and preserves nested container paths
-- **Tools**: `bash`, `ls`, `read_file`, `write_file`, `str_replace` (`bash` is disabled by default when using `LocalSandboxProvider`; use `AioSandboxProvider` for isolated shell access)
+- **Tools**: `bash`, `ls`, `read_file`, `write_file`, `str_replace`
 
 ### Subagent System
 
 Async task delegation with concurrent execution:
 
-- **Built-in agents**: `general-purpose` (full toolset) and `bash` (command specialist, exposed only when shell access is available)
+- **Built-in agents**: `general-purpose` (full toolset) and `bash` (command specialist)
 - **Concurrency**: Max 3 subagents per turn, 15-minute timeout
 - **Execution**: Background thread pools with status tracking and SSE events
 - **Flow**: Agent calls `task()` tool → executor runs subagent in background → polls for completion → returns result
@@ -123,17 +123,10 @@ FastAPI application providing REST endpoints for frontend integration:
 | `POST /api/memory/reload` | Force memory reload |
 | `GET /api/memory/config` | Memory configuration |
 | `GET /api/memory/status` | Combined config + data |
-| `POST /api/threads/{id}/uploads` | Upload files (auto-converts PDF/PPT/Excel/Word to Markdown, rejects directory paths) |
+| `POST /api/threads/{id}/uploads` | Upload files (auto-converts PDF/PPT/Excel/Word to Markdown) |
 | `GET /api/threads/{id}/uploads/list` | List uploaded files |
-| `DELETE /api/threads/{id}` | Delete DeerFlow-managed local thread data after LangGraph thread deletion; unexpected failures are logged server-side and return a generic 500 detail |
 | `GET /api/threads/{id}/artifacts/{path}` | Serve generated artifacts |
 
-### IM Channels
-
-The IM bridge supports Feishu, Slack, and Telegram. Slack and Telegram still use the final `runs.wait()` response path, while Feishu now streams through `runs.stream(["messages-tuple", "values"])` and updates a single in-thread card in place.
-
-For Feishu card updates, DeerFlow stores the running card's `message_id` per inbound message and patches that same card until the run finishes, preserving the existing `OK` / `DONE` reaction flow.
-
 ---
 
 ## Quick Start
@@ -170,15 +163,6 @@ models:
     api_key: $OPENAI_API_KEY
     supports_thinking: false
     supports_vision: true
-
-  - name: gpt-5-responses
-    display_name: GPT-5 (Responses API)
-    use: langchain_openai:ChatOpenAI
-    model: gpt-5
-    api_key: $OPENAI_API_KEY
-    use_responses_api: true
-    output_version: responses/v1
-    supports_vision: true
 ```
 
 Set your API keys:
@@ -312,26 +296,6 @@ MCP servers and skill states in a single file:
 - Model API keys: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, etc.
 - Tool API keys: `TAVILY_API_KEY`, `GITHUB_TOKEN`, etc.
 
-### LangSmith Tracing
-
-DeerFlow has built-in [LangSmith](https://smith.langchain.com) integration for observability. When enabled, all LLM calls, agent runs, tool executions, and middleware processing are traced and visible in the LangSmith dashboard.
-
-**Setup:**
-
-1. Sign up at [smith.langchain.com](https://smith.langchain.com) and create a project.
-2. Add the following to your `.env` file in the project root:
-
-```bash
-LANGSMITH_TRACING=true
-LANGSMITH_ENDPOINT=https://api.smith.langchain.com
-LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
-LANGSMITH_PROJECT=xxx
-```
-
-**Legacy variables:** The `LANGCHAIN_TRACING_V2`, `LANGCHAIN_API_KEY`, `LANGCHAIN_PROJECT`, and `LANGCHAIN_ENDPOINT` variables are also supported for backward compatibility. `LANGSMITH_*` variables take precedence when both are set.
-
-**Docker:** In `docker-compose.yaml`, tracing is disabled by default (`LANGSMITH_TRACING=false`). Set `LANGSMITH_TRACING=true` and provide `LANGSMITH_API_KEY` in your `.env` to enable it in containerized deployments.
-
 ---
 
 ## Development

backend/app/channels/__init__.py

@@ -1,16 +0,0 @@
-"""IM Channel integration for DeerFlow.
-
-Provides a pluggable channel system that connects external messaging platforms
-(Feishu/Lark, Slack, Telegram) to the DeerFlow agent via the ChannelManager,
-which uses ``langgraph-sdk`` to communicate with the underlying LangGraph Server.
-"""
-
-from app.channels.base import Channel
-from app.channels.message_bus import InboundMessage, MessageBus, OutboundMessage
-
-__all__ = [
-    "Channel",
-    "InboundMessage",
-    "MessageBus",
-    "OutboundMessage",
-]

backend/app/channels/base.py

@@ -1,108 +0,0 @@
-"""Abstract base class for IM channels."""
-
-from __future__ import annotations
-
-import logging
-from abc import ABC, abstractmethod
-from typing import Any
-
-from app.channels.message_bus import InboundMessage, InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
-
-logger = logging.getLogger(__name__)
-
-
-class Channel(ABC):
-    """Base class for all IM channel implementations.
-
-    Each channel connects to an external messaging platform and:
-    1. Receives messages, wraps them as InboundMessage, publishes to the bus.
-    2. Subscribes to outbound messages and sends replies back to the platform.
-
-    Subclasses must implement ``start``, ``stop``, and ``send``.
-    """
-
-    def __init__(self, name: str, bus: MessageBus, config: dict[str, Any]) -> None:
-        self.name = name
-        self.bus = bus
-        self.config = config
-        self._running = False
-
-    @property
-    def is_running(self) -> bool:
-        return self._running
-
-    # -- lifecycle ---------------------------------------------------------
-
-    @abstractmethod
-    async def start(self) -> None:
-        """Start listening for messages from the external platform."""
-
-    @abstractmethod
-    async def stop(self) -> None:
-        """Gracefully stop the channel."""
-
-    # -- outbound ----------------------------------------------------------
-
-    @abstractmethod
-    async def send(self, msg: OutboundMessage) -> None:
-        """Send a message back to the external platform.
-
-        The implementation should use ``msg.chat_id`` and ``msg.thread_ts``
-        to route the reply to the correct conversation/thread.
-        """
-
-    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
-        """Upload a single file attachment to the platform.
-
-        Returns True if the upload succeeded, False otherwise.
-        Default implementation returns False (no file upload support).
-        """
-        return False
-
-    # -- helpers -----------------------------------------------------------
-
-    def _make_inbound(
-        self,
-        chat_id: str,
-        user_id: str,
-        text: str,
-        *,
-        msg_type: InboundMessageType = InboundMessageType.CHAT,
-        thread_ts: str | None = None,
-        files: list[dict[str, Any]] | None = None,
-        metadata: dict[str, Any] | None = None,
-    ) -> InboundMessage:
-        """Convenience factory for creating InboundMessage instances."""
-        return InboundMessage(
-            channel_name=self.name,
-            chat_id=chat_id,
-            user_id=user_id,
-            text=text,
-            msg_type=msg_type,
-            thread_ts=thread_ts,
-            files=files or [],
-            metadata=metadata or {},
-        )
-
-    async def _on_outbound(self, msg: OutboundMessage) -> None:
-        """Outbound callback registered with the bus.
-
-        Only forwards messages targeted at this channel.
-        Sends the text message first, then uploads any file attachments.
-        File uploads are skipped entirely when the text send fails to avoid
-        partial deliveries (files without accompanying text).
-        """
-        if msg.channel_name == self.name:
-            try:
-                await self.send(msg)
-            except Exception:
-                logger.exception("Failed to send outbound message on channel %s", self.name)
-                return  # Do not attempt file uploads when the text message failed
-
-            for attachment in msg.attachments:
-                try:
-                    success = await self.send_file(msg, attachment)
-                    if not success:
-                        logger.warning("[%s] file upload skipped for %s", self.name, attachment.filename)
-                except Exception:
-                    logger.exception("[%s] failed to upload file %s", self.name, attachment.filename)

backend/app/channels/feishu.py

@@ -1,539 +0,0 @@
-"""Feishu/Lark channel — connects to Feishu via WebSocket (no public IP needed)."""
-
-from __future__ import annotations
-
-import asyncio
-import json
-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__)
-
-
-class FeishuChannel(Channel):
-    """Feishu/Lark IM channel using the ``lark-oapi`` WebSocket client.
-
-    Configuration keys (in ``config.yaml`` under ``channels.feishu``):
-        - ``app_id``: Feishu app ID.
-        - ``app_secret``: Feishu app secret.
-        - ``verification_token``: (optional) Event verification token.
-
-    The channel uses WebSocket long-connection mode so no public IP is required.
-
-    Message flow:
-        1. User sends a message → bot adds "OK" emoji reaction
-        2. Bot replies in thread: "Working on it......"
-        3. Agent processes the message and returns a result
-        4. Bot replies in thread with the result
-        5. Bot adds "DONE" emoji reaction to the original message
-    """
-
-    def __init__(self, bus: MessageBus, config: dict[str, Any]) -> None:
-        super().__init__(name="feishu", bus=bus, config=config)
-        self._thread: threading.Thread | None = None
-        self._main_loop: asyncio.AbstractEventLoop | None = None
-        self._api_client = None
-        self._CreateMessageReactionRequest = None
-        self._CreateMessageReactionRequestBody = None
-        self._Emoji = None
-        self._PatchMessageRequest = None
-        self._PatchMessageRequestBody = None
-        self._background_tasks: set[asyncio.Task] = set()
-        self._running_card_ids: dict[str, str] = {}
-        self._running_card_tasks: dict[str, asyncio.Task] = {}
-        self._CreateFileRequest = None
-        self._CreateFileRequestBody = None
-        self._CreateImageRequest = None
-        self._CreateImageRequestBody = None
-
-    async def start(self) -> None:
-        if self._running:
-            return
-
-        try:
-            import lark_oapi as lark
-            from lark_oapi.api.im.v1 import (
-                CreateFileRequest,
-                CreateFileRequestBody,
-                CreateImageRequest,
-                CreateImageRequestBody,
-                CreateMessageReactionRequest,
-                CreateMessageReactionRequestBody,
-                CreateMessageRequest,
-                CreateMessageRequestBody,
-                Emoji,
-                PatchMessageRequest,
-                PatchMessageRequestBody,
-                ReplyMessageRequest,
-                ReplyMessageRequestBody,
-            )
-        except ImportError:
-            logger.error("lark-oapi is not installed. Install it with: uv add lark-oapi")
-            return
-
-        self._lark = lark
-        self._CreateMessageRequest = CreateMessageRequest
-        self._CreateMessageRequestBody = CreateMessageRequestBody
-        self._ReplyMessageRequest = ReplyMessageRequest
-        self._ReplyMessageRequestBody = ReplyMessageRequestBody
-        self._CreateMessageReactionRequest = CreateMessageReactionRequest
-        self._CreateMessageReactionRequestBody = CreateMessageReactionRequestBody
-        self._Emoji = Emoji
-        self._PatchMessageRequest = PatchMessageRequest
-        self._PatchMessageRequestBody = PatchMessageRequestBody
-        self._CreateFileRequest = CreateFileRequest
-        self._CreateFileRequestBody = CreateFileRequestBody
-        self._CreateImageRequest = CreateImageRequest
-        self._CreateImageRequestBody = CreateImageRequestBody
-
-        app_id = self.config.get("app_id", "")
-        app_secret = self.config.get("app_secret", "")
-        domain = self.config.get("domain", "https://open.feishu.cn")
-
-        if not app_id or not app_secret:
-            logger.error("Feishu channel requires app_id and app_secret")
-            return
-
-        self._api_client = lark.Client.builder().app_id(app_id).app_secret(app_secret).domain(domain).build()
-        logger.info("[Feishu] using domain: %s", domain)
-        self._main_loop = asyncio.get_event_loop()
-
-        self._running = True
-        self.bus.subscribe_outbound(self._on_outbound)
-
-        # Both ws.Client construction and start() must happen in a dedicated
-        # thread with its own event loop.  lark-oapi caches the running loop
-        # at construction time and later calls loop.run_until_complete(),
-        # which conflicts with an already-running uvloop.
-        self._thread = threading.Thread(
-            target=self._run_ws,
-            args=(app_id, app_secret, domain),
-            daemon=True,
-        )
-        self._thread.start()
-        logger.info("Feishu channel started")
-
-    def _run_ws(self, app_id: str, app_secret: str, domain: str) -> None:
-        """Construct and run the lark WS client in a thread with a fresh event loop.
-
-        The lark-oapi SDK captures a module-level event loop at import time
-        (``lark_oapi.ws.client.loop``).  When uvicorn uses uvloop, that
-        captured loop is the *main* thread's uvloop — which is already
-        running, so ``loop.run_until_complete()`` inside ``Client.start()``
-        raises ``RuntimeError``.
-
-        We work around this by creating a plain asyncio event loop for this
-        thread and patching the SDK's module-level reference before calling
-        ``start()``.
-        """
-        loop = asyncio.new_event_loop()
-        asyncio.set_event_loop(loop)
-        try:
-            import lark_oapi as lark
-            import lark_oapi.ws.client as _ws_client_mod
-
-            # Replace the SDK's module-level loop so Client.start() uses
-            # this thread's (non-running) event loop instead of the main
-            # thread's uvloop.
-            _ws_client_mod.loop = loop
-
-            event_handler = lark.EventDispatcherHandler.builder("", "").register_p2_im_message_receive_v1(self._on_message).build()
-            ws_client = lark.ws.Client(
-                app_id=app_id,
-                app_secret=app_secret,
-                event_handler=event_handler,
-                log_level=lark.LogLevel.INFO,
-                domain=domain,
-            )
-            ws_client.start()
-        except Exception:
-            if self._running:
-                logger.exception("Feishu WebSocket error")
-
-    async def stop(self) -> None:
-        self._running = False
-        self.bus.unsubscribe_outbound(self._on_outbound)
-        for task in list(self._background_tasks):
-            task.cancel()
-        self._background_tasks.clear()
-        for task in list(self._running_card_tasks.values()):
-            task.cancel()
-        self._running_card_tasks.clear()
-        if self._thread:
-            self._thread.join(timeout=5)
-            self._thread = None
-        logger.info("Feishu channel stopped")
-
-    async def send(self, msg: OutboundMessage, *, _max_retries: int = 3) -> None:
-        if not self._api_client:
-            logger.warning("[Feishu] send called but no api_client available")
-            return
-
-        logger.info(
-            "[Feishu] sending reply: chat_id=%s, thread_ts=%s, text_len=%d",
-            msg.chat_id,
-            msg.thread_ts,
-            len(msg.text),
-        )
-
-        last_exc: Exception | None = None
-        for attempt in range(_max_retries):
-            try:
-                await self._send_card_message(msg)
-                return  # success
-            except Exception as exc:
-                last_exc = exc
-                if attempt < _max_retries - 1:
-                    delay = 2**attempt  # 1s, 2s
-                    logger.warning(
-                        "[Feishu] send failed (attempt %d/%d), retrying in %ds: %s",
-                        attempt + 1,
-                        _max_retries,
-                        delay,
-                        exc,
-                    )
-                    await asyncio.sleep(delay)
-
-        logger.error("[Feishu] send failed after %d attempts: %s", _max_retries, last_exc)
-        raise last_exc  # type: ignore[misc]
-
-    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
-        if not self._api_client:
-            return False
-
-        # Check size limits (image: 10MB, file: 30MB)
-        if attachment.is_image and attachment.size > 10 * 1024 * 1024:
-            logger.warning("[Feishu] image too large (%d bytes), skipping: %s", attachment.size, attachment.filename)
-            return False
-        if not attachment.is_image and attachment.size > 30 * 1024 * 1024:
-            logger.warning("[Feishu] file too large (%d bytes), skipping: %s", attachment.size, attachment.filename)
-            return False
-
-        try:
-            if attachment.is_image:
-                file_key = await self._upload_image(attachment.actual_path)
-                msg_type = "image"
-                content = json.dumps({"image_key": file_key})
-            else:
-                file_key = await self._upload_file(attachment.actual_path, attachment.filename)
-                msg_type = "file"
-                content = json.dumps({"file_key": file_key})
-
-            if msg.thread_ts:
-                request = self._ReplyMessageRequest.builder().message_id(msg.thread_ts).request_body(self._ReplyMessageRequestBody.builder().msg_type(msg_type).content(content).reply_in_thread(True).build()).build()
-                await asyncio.to_thread(self._api_client.im.v1.message.reply, request)
-            else:
-                request = self._CreateMessageRequest.builder().receive_id_type("chat_id").request_body(self._CreateMessageRequestBody.builder().receive_id(msg.chat_id).msg_type(msg_type).content(content).build()).build()
-                await asyncio.to_thread(self._api_client.im.v1.message.create, request)
-
-            logger.info("[Feishu] file sent: %s (type=%s)", attachment.filename, msg_type)
-            return True
-        except Exception:
-            logger.exception("[Feishu] failed to upload/send file: %s", attachment.filename)
-            return False
-
-    async def _upload_image(self, path) -> str:
-        """Upload an image to Feishu and return the image_key."""
-        with open(str(path), "rb") as f:
-            request = self._CreateImageRequest.builder().request_body(self._CreateImageRequestBody.builder().image_type("message").image(f).build()).build()
-            response = await asyncio.to_thread(self._api_client.im.v1.image.create, request)
-        if not response.success():
-            raise RuntimeError(f"Feishu image upload failed: code={response.code}, msg={response.msg}")
-        return response.data.image_key
-
-    async def _upload_file(self, path, filename: str) -> str:
-        """Upload a file to Feishu and return the file_key."""
-        suffix = path.suffix.lower() if hasattr(path, "suffix") else ""
-        if suffix in (".xls", ".xlsx", ".csv"):
-            file_type = "xls"
-        elif suffix in (".ppt", ".pptx"):
-            file_type = "ppt"
-        elif suffix == ".pdf":
-            file_type = "pdf"
-        elif suffix in (".doc", ".docx"):
-            file_type = "doc"
-        else:
-            file_type = "stream"
-
-        with open(str(path), "rb") as f:
-            request = self._CreateFileRequest.builder().request_body(self._CreateFileRequestBody.builder().file_type(file_type).file_name(filename).file(f).build()).build()
-            response = await asyncio.to_thread(self._api_client.im.v1.file.create, request)
-        if not response.success():
-            raise RuntimeError(f"Feishu file upload failed: code={response.code}, msg={response.msg}")
-        return response.data.file_key
-
-    # -- message formatting ------------------------------------------------
-
-    @staticmethod
-    def _build_card_content(text: str) -> str:
-        """Build a Feishu interactive card with markdown content.
-
-        Feishu's interactive card format natively renders markdown, including
-        headers, bold/italic, code blocks, lists, and links.
-        """
-        card = {
-            "config": {"wide_screen_mode": True, "update_multi": True},
-            "elements": [{"tag": "markdown", "content": text}],
-        }
-        return json.dumps(card)
-
-    # -- reaction helpers --------------------------------------------------
-
-    async def _add_reaction(self, message_id: str, emoji_type: str = "THUMBSUP") -> None:
-        """Add an emoji reaction to a message."""
-        if not self._api_client or not self._CreateMessageReactionRequest:
-            return
-        try:
-            request = self._CreateMessageReactionRequest.builder().message_id(message_id).request_body(self._CreateMessageReactionRequestBody.builder().reaction_type(self._Emoji.builder().emoji_type(emoji_type).build()).build()).build()
-            await asyncio.to_thread(self._api_client.im.v1.message_reaction.create, request)
-            logger.info("[Feishu] reaction '%s' added to message %s", emoji_type, message_id)
-        except Exception:
-            logger.exception("[Feishu] failed to add reaction '%s' to message %s", emoji_type, message_id)
-
-    async def _reply_card(self, message_id: str, text: str) -> str | None:
-        """Reply with an interactive card and return the created card message ID."""
-        if not self._api_client:
-            return None
-
-        content = self._build_card_content(text)
-        request = self._ReplyMessageRequest.builder().message_id(message_id).request_body(self._ReplyMessageRequestBody.builder().msg_type("interactive").content(content).reply_in_thread(True).build()).build()
-        response = await asyncio.to_thread(self._api_client.im.v1.message.reply, request)
-        response_data = getattr(response, "data", None)
-        return getattr(response_data, "message_id", None)
-
-    async def _create_card(self, chat_id: str, text: str) -> None:
-        """Create a new card message in the target chat."""
-        if not self._api_client:
-            return
-
-        content = self._build_card_content(text)
-        request = self._CreateMessageRequest.builder().receive_id_type("chat_id").request_body(self._CreateMessageRequestBody.builder().receive_id(chat_id).msg_type("interactive").content(content).build()).build()
-        await asyncio.to_thread(self._api_client.im.v1.message.create, request)
-
-    async def _update_card(self, message_id: str, text: str) -> None:
-        """Patch an existing card message in place."""
-        if not self._api_client or not self._PatchMessageRequest:
-            return
-
-        content = self._build_card_content(text)
-        request = self._PatchMessageRequest.builder().message_id(message_id).request_body(self._PatchMessageRequestBody.builder().content(content).build()).build()
-        await asyncio.to_thread(self._api_client.im.v1.message.patch, request)
-
-    def _track_background_task(self, task: asyncio.Task, *, name: str, msg_id: str) -> None:
-        """Keep a strong reference to fire-and-forget tasks and surface errors."""
-        self._background_tasks.add(task)
-        task.add_done_callback(lambda done_task, task_name=name, mid=msg_id: self._finalize_background_task(done_task, task_name, mid))
-
-    def _finalize_background_task(self, task: asyncio.Task, name: str, msg_id: str) -> None:
-        self._background_tasks.discard(task)
-        self._log_task_error(task, name, msg_id)
-
-    async def _create_running_card(self, source_message_id: str, text: str) -> str | None:
-        """Create the running card and cache its message ID when available."""
-        running_card_id = await self._reply_card(source_message_id, text)
-        if running_card_id:
-            self._running_card_ids[source_message_id] = running_card_id
-            logger.info("[Feishu] running card created: source=%s card=%s", source_message_id, running_card_id)
-        else:
-            logger.warning("[Feishu] running card creation returned no message_id for source=%s, subsequent updates will fall back to new replies", source_message_id)
-        return running_card_id
-
-    def _ensure_running_card_started(self, source_message_id: str, text: str = "Working on it...") -> asyncio.Task | None:
-        """Start running-card creation once per source message."""
-        running_card_id = self._running_card_ids.get(source_message_id)
-        if running_card_id:
-            return None
-
-        running_card_task = self._running_card_tasks.get(source_message_id)
-        if running_card_task:
-            return running_card_task
-
-        running_card_task = asyncio.create_task(self._create_running_card(source_message_id, text))
-        self._running_card_tasks[source_message_id] = running_card_task
-        running_card_task.add_done_callback(lambda done_task, mid=source_message_id: self._finalize_running_card_task(mid, done_task))
-        return running_card_task
-
-    def _finalize_running_card_task(self, source_message_id: str, task: asyncio.Task) -> None:
-        if self._running_card_tasks.get(source_message_id) is task:
-            self._running_card_tasks.pop(source_message_id, None)
-        self._log_task_error(task, "create_running_card", source_message_id)
-
-    async def _ensure_running_card(self, source_message_id: str, text: str = "Working on it...") -> str | None:
-        """Ensure the in-thread running card exists and track its message ID."""
-        running_card_id = self._running_card_ids.get(source_message_id)
-        if running_card_id:
-            return running_card_id
-
-        running_card_task = self._ensure_running_card_started(source_message_id, text)
-        if running_card_task is None:
-            return self._running_card_ids.get(source_message_id)
-        return await running_card_task
-
-    async def _send_running_reply(self, message_id: str) -> None:
-        """Reply to a message in-thread with a running card."""
-        try:
-            await self._ensure_running_card(message_id)
-        except Exception:
-            logger.exception("[Feishu] failed to send running reply for message %s", message_id)
-
-    async def _send_card_message(self, msg: OutboundMessage) -> None:
-        """Send or update the Feishu card tied to the current request."""
-        source_message_id = msg.thread_ts
-        if source_message_id:
-            running_card_id = self._running_card_ids.get(source_message_id)
-            awaited_running_card_task = False
-
-            if not running_card_id:
-                running_card_task = self._running_card_tasks.get(source_message_id)
-                if running_card_task:
-                    awaited_running_card_task = True
-                    running_card_id = await running_card_task
-
-            if running_card_id:
-                try:
-                    await self._update_card(running_card_id, msg.text)
-                except Exception:
-                    if not msg.is_final:
-                        raise
-                    logger.exception(
-                        "[Feishu] failed to patch running card %s, falling back to final reply",
-                        running_card_id,
-                    )
-                    await self._reply_card(source_message_id, msg.text)
-                else:
-                    logger.info("[Feishu] running card updated: source=%s card=%s", source_message_id, running_card_id)
-            elif msg.is_final:
-                await self._reply_card(source_message_id, msg.text)
-            elif awaited_running_card_task:
-                logger.warning(
-                    "[Feishu] running card task finished without message_id for source=%s, skipping duplicate non-final creation",
-                    source_message_id,
-                )
-            else:
-                await self._ensure_running_card(source_message_id, msg.text)
-
-            if msg.is_final:
-                self._running_card_ids.pop(source_message_id, None)
-                await self._add_reaction(source_message_id, "DONE")
-            return
-
-        await self._create_card(msg.chat_id, msg.text)
-
-    # -- internal ----------------------------------------------------------
-
-    @staticmethod
-    def _log_future_error(fut, name: str, msg_id: str) -> None:
-        """Callback for run_coroutine_threadsafe futures to surface errors."""
-        try:
-            exc = fut.exception()
-            if exc:
-                logger.error("[Feishu] %s failed for msg_id=%s: %s", name, msg_id, exc)
-        except Exception:
-            pass
-
-    @staticmethod
-    def _log_task_error(task: asyncio.Task, name: str, msg_id: str) -> None:
-        """Callback for background asyncio tasks to surface errors."""
-        try:
-            exc = task.exception()
-            if exc:
-                logger.error("[Feishu] %s failed for msg_id=%s: %s", name, msg_id, exc)
-        except asyncio.CancelledError:
-            logger.info("[Feishu] %s cancelled for msg_id=%s", name, msg_id)
-        except Exception:
-            pass
-
-    async def _prepare_inbound(self, msg_id: str, inbound) -> None:
-        """Kick off Feishu side effects without delaying inbound dispatch."""
-        reaction_task = asyncio.create_task(self._add_reaction(msg_id, "OK"))
-        self._track_background_task(reaction_task, name="add_reaction", msg_id=msg_id)
-        self._ensure_running_card_started(msg_id)
-        await self.bus.publish_inbound(inbound)
-
-    def _on_message(self, event) -> None:
-        """Called by lark-oapi when a message is received (runs in lark thread)."""
-        try:
-            logger.info("[Feishu] raw event received: type=%s", type(event).__name__)
-            message = event.event.message
-            chat_id = message.chat_id
-            msg_id = message.message_id
-            sender_id = event.event.sender.sender_id.open_id
-
-            # root_id is set when the message is a reply within a Feishu thread.
-            # Use it as topic_id so all replies share the same DeerFlow thread.
-            root_id = getattr(message, "root_id", None) or None
-
-            # Parse message content
-            content = json.loads(message.content)
-
-            if "text" in content:
-                # Handle plain text messages
-                text = content["text"]
-            elif "content" in content and isinstance(content["content"], list):
-                # Handle rich-text messages with a top-level "content" list (e.g., topic groups/posts)
-                text_paragraphs: list[str] = []
-                for paragraph in content["content"]:
-                    if isinstance(paragraph, list):
-                        paragraph_text_parts: list[str] = []
-                        for element in paragraph:
-                            if isinstance(element, dict):
-                                # Include both normal text and @ mentions
-                                if element.get("tag") in ("text", "at"):
-                                    text_value = element.get("text", "")
-                                    if text_value:
-                                        paragraph_text_parts.append(text_value)
-                        if paragraph_text_parts:
-                            # Join text segments within a paragraph with spaces to avoid "helloworld"
-                            text_paragraphs.append(" ".join(paragraph_text_parts))
-
-                # Join paragraphs with blank lines to preserve paragraph boundaries
-                text = "\n\n".join(text_paragraphs)
-            else:
-                text = ""
-            text = text.strip()
-
-            logger.info(
-                "[Feishu] parsed message: chat_id=%s, msg_id=%s, root_id=%s, sender=%s, text=%r",
-                chat_id,
-                msg_id,
-                root_id,
-                sender_id,
-                text[:100] if text else "",
-            )
-
-            if not text:
-                logger.info("[Feishu] empty text, ignoring message")
-                return
-
-            # Check if it's a command
-            if text.startswith("/"):
-                msg_type = InboundMessageType.COMMAND
-            else:
-                msg_type = InboundMessageType.CHAT
-
-            # topic_id: use root_id for replies (same topic), msg_id for new messages (new topic)
-            topic_id = root_id or msg_id
-
-            inbound = self._make_inbound(
-                chat_id=chat_id,
-                user_id=sender_id,
-                text=text,
-                msg_type=msg_type,
-                thread_ts=msg_id,
-                metadata={"message_id": msg_id, "root_id": root_id},
-            )
-            inbound.topic_id = topic_id
-
-            # Schedule on the async event loop
-            if self._main_loop and self._main_loop.is_running():
-                logger.info("[Feishu] publishing inbound message to bus (type=%s, msg_id=%s)", msg_type.value, msg_id)
-                fut = asyncio.run_coroutine_threadsafe(self._prepare_inbound(msg_id, inbound), self._main_loop)
-                fut.add_done_callback(lambda f, mid=msg_id: self._log_future_error(f, "prepare_inbound", mid))
-            else:
-                logger.warning("[Feishu] main loop not running, cannot publish inbound message")
-        except Exception:
-            logger.exception("[Feishu] error processing message")

backend/app/channels/manager.py

@@ -1,780 +0,0 @@
-"""ChannelManager — consumes inbound messages and dispatches them to the DeerFlow agent via LangGraph Server."""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-import mimetypes
-import re
-import time
-from collections.abc import Mapping
-from typing import Any
-
-from langgraph_sdk.errors import ConflictError
-
-from app.channels.message_bus import InboundMessage, InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
-from app.channels.store import ChannelStore
-
-logger = logging.getLogger(__name__)
-
-DEFAULT_LANGGRAPH_URL = "http://localhost:2024"
-DEFAULT_GATEWAY_URL = "http://localhost:8001"
-DEFAULT_ASSISTANT_ID = "lead_agent"
-CUSTOM_AGENT_NAME_PATTERN = re.compile(r"^[A-Za-z0-9-]+$")
-
-DEFAULT_RUN_CONFIG: dict[str, Any] = {"recursion_limit": 100}
-DEFAULT_RUN_CONTEXT: dict[str, Any] = {
-    "thinking_enabled": True,
-    "is_plan_mode": False,
-    "subagent_enabled": False,
-}
-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 = {
-    "feishu": {"supports_streaming": True},
-    "slack": {"supports_streaming": False},
-    "telegram": {"supports_streaming": False},
-}
-
-
-class InvalidChannelSessionConfigError(ValueError):
-    """Raised when IM channel session overrides contain invalid agent config."""
-
-
-def _is_thread_busy_error(exc: BaseException | None) -> bool:
-    if exc is None:
-        return False
-    if isinstance(exc, ConflictError):
-        return True
-    return "already running a task" in str(exc)
-
-
-def _as_dict(value: Any) -> dict[str, Any]:
-    return dict(value) if isinstance(value, Mapping) else {}
-
-
-def _merge_dicts(*layers: Any) -> dict[str, Any]:
-    merged: dict[str, Any] = {}
-    for layer in layers:
-        if isinstance(layer, Mapping):
-            merged.update(layer)
-    return merged
-
-
-def _normalize_custom_agent_name(raw_value: str) -> str:
-    """Normalize legacy channel assistant IDs into valid custom agent names."""
-    normalized = raw_value.strip().lower().replace("_", "-")
-    if not normalized:
-        raise InvalidChannelSessionConfigError("Channel session assistant_id is empty. Use 'lead_agent' or a valid custom agent name.")
-    if not CUSTOM_AGENT_NAME_PATTERN.fullmatch(normalized):
-        raise InvalidChannelSessionConfigError(f"Invalid channel session assistant_id {raw_value!r}. Use 'lead_agent' or a custom agent name containing only letters, digits, and hyphens.")
-    return normalized
-
-
-def _extract_response_text(result: dict | list) -> str:
-    """Extract the last AI message text from a LangGraph runs.wait result.
-
-    ``runs.wait`` returns the final state dict which contains a ``messages``
-    list.  Each message is a dict with at least ``type`` and ``content``.
-
-    Handles special cases:
-    - Regular AI text responses
-    - Clarification interrupts (``ask_clarification`` tool messages)
-    - AI messages with tool_calls but no text content
-    """
-    if isinstance(result, list):
-        messages = result
-    elif isinstance(result, dict):
-        messages = result.get("messages", [])
-    else:
-        return ""
-
-    # Walk backwards to find usable response text, but stop at the last
-    # human message to avoid returning text from a previous turn.
-    for msg in reversed(messages):
-        if not isinstance(msg, dict):
-            continue
-
-        msg_type = msg.get("type")
-
-        # Stop at the last human message — anything before it is a previous turn
-        if msg_type == "human":
-            break
-
-        # Check for tool messages from ask_clarification (interrupt case)
-        if msg_type == "tool" and msg.get("name") == "ask_clarification":
-            content = msg.get("content", "")
-            if isinstance(content, str) and content:
-                return content
-
-        # Regular AI message with text content
-        if msg_type == "ai":
-            content = msg.get("content", "")
-            if isinstance(content, str) and content:
-                return content
-            # content can be a list of content blocks
-            if isinstance(content, list):
-                parts = []
-                for block in content:
-                    if isinstance(block, dict) and block.get("type") == "text":
-                        parts.append(block.get("text", ""))
-                    elif isinstance(block, str):
-                        parts.append(block)
-                text = "".join(parts)
-                if text:
-                    return text
-    return ""
-
-
-def _extract_text_content(content: Any) -> str:
-    """Extract text from a streaming payload content field."""
-    if isinstance(content, str):
-        return content
-    if isinstance(content, list):
-        parts: list[str] = []
-        for block in content:
-            if isinstance(block, str):
-                parts.append(block)
-            elif isinstance(block, Mapping):
-                text = block.get("text")
-                if isinstance(text, str):
-                    parts.append(text)
-                else:
-                    nested = block.get("content")
-                    if isinstance(nested, str):
-                        parts.append(nested)
-        return "".join(parts)
-    if isinstance(content, Mapping):
-        for key in ("text", "content"):
-            value = content.get(key)
-            if isinstance(value, str):
-                return value
-    return ""
-
-
-def _merge_stream_text(existing: str, chunk: str) -> str:
-    """Merge either delta text or cumulative text into a single snapshot."""
-    if not chunk:
-        return existing
-    if not existing or chunk == existing:
-        return chunk or existing
-    if chunk.startswith(existing):
-        return chunk
-    if existing.endswith(chunk):
-        return existing
-    return existing + chunk
-
-
-def _extract_stream_message_id(payload: Any, metadata: Any) -> str | None:
-    """Best-effort extraction of the streamed AI message identifier."""
-    candidates = [payload, metadata]
-    if isinstance(payload, Mapping):
-        candidates.append(payload.get("kwargs"))
-
-    for candidate in candidates:
-        if not isinstance(candidate, Mapping):
-            continue
-        for key in ("id", "message_id"):
-            value = candidate.get(key)
-            if isinstance(value, str) and value:
-                return value
-    return None
-
-
-def _accumulate_stream_text(
-    buffers: dict[str, str],
-    current_message_id: str | None,
-    event_data: Any,
-) -> tuple[str | None, str | None]:
-    """Convert a ``messages-tuple`` event into the latest displayable AI text."""
-    payload = event_data
-    metadata: Any = None
-    if isinstance(event_data, (list, tuple)):
-        if event_data:
-            payload = event_data[0]
-        if len(event_data) > 1:
-            metadata = event_data[1]
-
-    if isinstance(payload, str):
-        message_id = current_message_id or "__default__"
-        buffers[message_id] = _merge_stream_text(buffers.get(message_id, ""), payload)
-        return buffers[message_id], message_id
-
-    if not isinstance(payload, Mapping):
-        return None, current_message_id
-
-    payload_type = str(payload.get("type", "")).lower()
-    if "tool" in payload_type:
-        return None, current_message_id
-
-    text = _extract_text_content(payload.get("content"))
-    if not text and isinstance(payload.get("kwargs"), Mapping):
-        text = _extract_text_content(payload["kwargs"].get("content"))
-    if not text:
-        return None, current_message_id
-
-    message_id = _extract_stream_message_id(payload, metadata) or current_message_id or "__default__"
-    buffers[message_id] = _merge_stream_text(buffers.get(message_id, ""), text)
-    return buffers[message_id], message_id
-
-
-def _extract_artifacts(result: dict | list) -> list[str]:
-    """Extract artifact paths from the last AI response cycle only.
-
-    Instead of reading the full accumulated ``artifacts`` state (which contains
-    all artifacts ever produced in the thread), this inspects the messages after
-    the last human message and collects file paths from ``present_files`` tool
-    calls.  This ensures only newly-produced artifacts are returned.
-    """
-    if isinstance(result, list):
-        messages = result
-    elif isinstance(result, dict):
-        messages = result.get("messages", [])
-    else:
-        return []
-
-    artifacts: list[str] = []
-    for msg in reversed(messages):
-        if not isinstance(msg, dict):
-            continue
-        # Stop at the last human message — anything before it is a previous turn
-        if msg.get("type") == "human":
-            break
-        # Look for AI messages with present_files tool calls
-        if msg.get("type") == "ai":
-            for tc in msg.get("tool_calls", []):
-                if isinstance(tc, dict) and tc.get("name") == "present_files":
-                    args = tc.get("args", {})
-                    paths = args.get("filepaths", [])
-                    if isinstance(paths, list):
-                        artifacts.extend(p for p in paths if isinstance(p, str))
-    return artifacts
-
-
-def _format_artifact_text(artifacts: list[str]) -> str:
-    """Format artifact paths into a human-readable text block listing filenames."""
-    import posixpath
-
-    filenames = [posixpath.basename(p) for p in artifacts]
-    if len(filenames) == 1:
-        return f"Created File: 📎 {filenames[0]}"
-    return "Created Files: 📎 " + "、".join(filenames)
-
-
-_OUTPUTS_VIRTUAL_PREFIX = "/mnt/user-data/outputs/"
-
-
-def _resolve_attachments(thread_id: str, artifacts: list[str]) -> list[ResolvedAttachment]:
-    """Resolve virtual artifact paths to host filesystem paths with metadata.
-
-    Only paths under ``/mnt/user-data/outputs/`` are accepted; any other
-    virtual path is rejected with a warning to prevent exfiltrating uploads
-    or workspace files via IM channels.
-
-    Skips artifacts that cannot be resolved (missing files, invalid paths)
-    and logs warnings for them.
-    """
-    from deerflow.config.paths import get_paths
-
-    attachments: list[ResolvedAttachment] = []
-    paths = get_paths()
-    outputs_dir = paths.sandbox_outputs_dir(thread_id).resolve()
-    for virtual_path in artifacts:
-        # Security: only allow files from the agent outputs directory
-        if not virtual_path.startswith(_OUTPUTS_VIRTUAL_PREFIX):
-            logger.warning("[Manager] rejected non-outputs artifact path: %s", virtual_path)
-            continue
-        try:
-            actual = paths.resolve_virtual_path(thread_id, virtual_path)
-            # Verify the resolved path is actually under the outputs directory
-            # (guards against path-traversal even after prefix check)
-            try:
-                actual.resolve().relative_to(outputs_dir)
-            except ValueError:
-                logger.warning("[Manager] artifact path escapes outputs dir: %s -> %s", virtual_path, actual)
-                continue
-            if not actual.is_file():
-                logger.warning("[Manager] artifact not found on disk: %s -> %s", virtual_path, actual)
-                continue
-            mime, _ = mimetypes.guess_type(str(actual))
-            mime = mime or "application/octet-stream"
-            attachments.append(
-                ResolvedAttachment(
-                    virtual_path=virtual_path,
-                    actual_path=actual,
-                    filename=actual.name,
-                    mime_type=mime,
-                    size=actual.stat().st_size,
-                    is_image=mime.startswith("image/"),
-                )
-            )
-        except (ValueError, OSError) as exc:
-            logger.warning("[Manager] failed to resolve artifact %s: %s", virtual_path, exc)
-    return attachments
-
-
-def _prepare_artifact_delivery(
-    thread_id: str,
-    response_text: str,
-    artifacts: list[str],
-) -> tuple[str, list[ResolvedAttachment]]:
-    """Resolve attachments and append filename fallbacks to the text response."""
-    attachments: list[ResolvedAttachment] = []
-    if not artifacts:
-        return response_text, attachments
-
-    attachments = _resolve_attachments(thread_id, artifacts)
-    resolved_virtuals = {attachment.virtual_path for attachment in attachments}
-    unresolved = [path for path in artifacts if path not in resolved_virtuals]
-
-    if unresolved:
-        artifact_text = _format_artifact_text(unresolved)
-        response_text = (response_text + "\n\n" + artifact_text) if response_text else artifact_text
-
-    # Always include resolved attachment filenames as a text fallback so files
-    # remain discoverable even when the upload is skipped or fails.
-    if attachments:
-        resolved_text = _format_artifact_text([attachment.virtual_path for attachment in attachments])
-        response_text = (response_text + "\n\n" + resolved_text) if response_text else resolved_text
-
-    return response_text, attachments
-
-
-class ChannelManager:
-    """Core dispatcher that bridges IM channels to the DeerFlow agent.
-
-    It reads from the MessageBus inbound queue, creates/reuses threads on
-    the LangGraph Server, sends messages via ``runs.wait``, and publishes
-    outbound responses back through the bus.
-    """
-
-    def __init__(
-        self,
-        bus: MessageBus,
-        store: ChannelStore,
-        *,
-        max_concurrency: int = 5,
-        langgraph_url: str = DEFAULT_LANGGRAPH_URL,
-        gateway_url: str = DEFAULT_GATEWAY_URL,
-        assistant_id: str = DEFAULT_ASSISTANT_ID,
-        default_session: dict[str, Any] | None = None,
-        channel_sessions: dict[str, Any] | None = None,
-    ) -> None:
-        self.bus = bus
-        self.store = store
-        self._max_concurrency = max_concurrency
-        self._langgraph_url = langgraph_url
-        self._gateway_url = gateway_url
-        self._assistant_id = assistant_id
-        self._default_session = _as_dict(default_session)
-        self._channel_sessions = dict(channel_sessions or {})
-        self._client = None  # lazy init — langgraph_sdk async client
-        self._semaphore: asyncio.Semaphore | None = None
-        self._running = False
-        self._task: asyncio.Task | None = None
-
-    @staticmethod
-    def _channel_supports_streaming(channel_name: str) -> bool:
-        return CHANNEL_CAPABILITIES.get(channel_name, {}).get("supports_streaming", False)
-
-    def _resolve_session_layer(self, msg: InboundMessage) -> tuple[dict[str, Any], dict[str, Any]]:
-        channel_layer = _as_dict(self._channel_sessions.get(msg.channel_name))
-        users_layer = _as_dict(channel_layer.get("users"))
-        user_layer = _as_dict(users_layer.get(msg.user_id))
-        return channel_layer, user_layer
-
-    def _resolve_run_params(self, msg: InboundMessage, thread_id: str) -> tuple[str, dict[str, Any], dict[str, Any]]:
-        channel_layer, user_layer = self._resolve_session_layer(msg)
-
-        assistant_id = user_layer.get("assistant_id") or channel_layer.get("assistant_id") or self._default_session.get("assistant_id") or self._assistant_id
-        if not isinstance(assistant_id, str) or not assistant_id.strip():
-            assistant_id = self._assistant_id
-
-        run_config = _merge_dicts(
-            DEFAULT_RUN_CONFIG,
-            self._default_session.get("config"),
-            channel_layer.get("config"),
-            user_layer.get("config"),
-        )
-
-        run_context = _merge_dicts(
-            DEFAULT_RUN_CONTEXT,
-            self._default_session.get("context"),
-            channel_layer.get("context"),
-            user_layer.get("context"),
-            {"thread_id": thread_id},
-        )
-
-        # Custom agents are implemented as lead_agent + agent_name context.
-        # Keep backward compatibility for channel configs that set
-        # assistant_id: <custom-agent-name> by routing through lead_agent.
-        if assistant_id != DEFAULT_ASSISTANT_ID:
-            run_context.setdefault("agent_name", _normalize_custom_agent_name(assistant_id))
-            assistant_id = DEFAULT_ASSISTANT_ID
-
-        return assistant_id, run_config, run_context
-
-    # -- LangGraph SDK client (lazy) ----------------------------------------
-
-    def _get_client(self):
-        """Return the ``langgraph_sdk`` async client, creating it on first use."""
-        if self._client is None:
-            from langgraph_sdk import get_client
-
-            self._client = get_client(url=self._langgraph_url)
-        return self._client
-
-    # -- lifecycle ---------------------------------------------------------
-
-    async def start(self) -> None:
-        """Start the dispatch loop."""
-        if self._running:
-            return
-        self._running = True
-        self._semaphore = asyncio.Semaphore(self._max_concurrency)
-        self._task = asyncio.create_task(self._dispatch_loop())
-        logger.info("ChannelManager started (max_concurrency=%d)", self._max_concurrency)
-
-    async def stop(self) -> None:
-        """Stop the dispatch loop."""
-        self._running = False
-        if self._task:
-            self._task.cancel()
-            try:
-                await self._task
-            except asyncio.CancelledError:
-                pass
-            self._task = None
-        logger.info("ChannelManager stopped")
-
-    # -- dispatch loop -----------------------------------------------------
-
-    async def _dispatch_loop(self) -> None:
-        logger.info("[Manager] dispatch loop started, waiting for inbound messages")
-        while self._running:
-            try:
-                msg = await asyncio.wait_for(self.bus.get_inbound(), timeout=1.0)
-            except TimeoutError:
-                continue
-            except asyncio.CancelledError:
-                break
-
-            logger.info(
-                "[Manager] received inbound: channel=%s, chat_id=%s, type=%s, text=%r",
-                msg.channel_name,
-                msg.chat_id,
-                msg.msg_type.value,
-                msg.text[:100] if msg.text else "",
-            )
-            task = asyncio.create_task(self._handle_message(msg))
-            task.add_done_callback(self._log_task_error)
-
-    @staticmethod
-    def _log_task_error(task: asyncio.Task) -> None:
-        """Surface unhandled exceptions from background tasks."""
-        if task.cancelled():
-            return
-        exc = task.exception()
-        if exc:
-            logger.error("[Manager] unhandled error in message task: %s", exc, exc_info=exc)
-
-    async def _handle_message(self, msg: InboundMessage) -> None:
-        async with self._semaphore:
-            try:
-                if msg.msg_type == InboundMessageType.COMMAND:
-                    await self._handle_command(msg)
-                else:
-                    await self._handle_chat(msg)
-            except InvalidChannelSessionConfigError as exc:
-                logger.warning(
-                    "Invalid channel session config for %s (chat=%s): %s",
-                    msg.channel_name,
-                    msg.chat_id,
-                    exc,
-                )
-                await self._send_error(msg, str(exc))
-            except Exception:
-                logger.exception(
-                    "Error handling message from %s (chat=%s)",
-                    msg.channel_name,
-                    msg.chat_id,
-                )
-                await self._send_error(msg, "An internal error occurred. Please try again.")
-
-    # -- chat handling -----------------------------------------------------
-
-    async def _create_thread(self, client, msg: InboundMessage) -> str:
-        """Create a new thread on the LangGraph Server and store the mapping."""
-        thread = await client.threads.create()
-        thread_id = thread["thread_id"]
-        self.store.set_thread_id(
-            msg.channel_name,
-            msg.chat_id,
-            thread_id,
-            topic_id=msg.topic_id,
-            user_id=msg.user_id,
-        )
-        logger.info("[Manager] new thread created on LangGraph Server: thread_id=%s for chat_id=%s topic_id=%s", thread_id, msg.chat_id, msg.topic_id)
-        return thread_id
-
-    async def _handle_chat(self, msg: InboundMessage, extra_context: dict[str, Any] | None = None) -> None:
-        client = self._get_client()
-
-        # Look up existing DeerFlow thread.
-        # topic_id may be None (e.g. Telegram private chats) — the store
-        # handles this by using the "channel:chat_id" key without a topic suffix.
-        thread_id = self.store.get_thread_id(msg.channel_name, msg.chat_id, topic_id=msg.topic_id)
-        if thread_id:
-            logger.info("[Manager] reusing thread: thread_id=%s for topic_id=%s", thread_id, msg.topic_id)
-
-        # No existing thread found — create a new one
-        if thread_id is None:
-            thread_id = await self._create_thread(client, msg)
-
-        assistant_id, run_config, run_context = self._resolve_run_params(msg, thread_id)
-        if extra_context:
-            run_context.update(extra_context)
-        if self._channel_supports_streaming(msg.channel_name):
-            await self._handle_streaming_chat(
-                client,
-                msg,
-                thread_id,
-                assistant_id,
-                run_config,
-                run_context,
-            )
-            return
-
-        logger.info("[Manager] invoking runs.wait(thread_id=%s, text=%r)", thread_id, msg.text[:100])
-        result = await client.runs.wait(
-            thread_id,
-            assistant_id,
-            input={"messages": [{"role": "human", "content": msg.text}]},
-            config=run_config,
-            context=run_context,
-        )
-
-        response_text = _extract_response_text(result)
-        artifacts = _extract_artifacts(result)
-
-        logger.info(
-            "[Manager] agent response received: thread_id=%s, response_len=%d, artifacts=%d",
-            thread_id,
-            len(response_text) if response_text else 0,
-            len(artifacts),
-        )
-
-        response_text, attachments = _prepare_artifact_delivery(thread_id, response_text, artifacts)
-
-        if not response_text:
-            if attachments:
-                response_text = _format_artifact_text([a.virtual_path for a in attachments])
-            else:
-                response_text = "(No response from agent)"
-
-        outbound = OutboundMessage(
-            channel_name=msg.channel_name,
-            chat_id=msg.chat_id,
-            thread_id=thread_id,
-            text=response_text,
-            artifacts=artifacts,
-            attachments=attachments,
-            thread_ts=msg.thread_ts,
-        )
-        logger.info("[Manager] publishing outbound message to bus: channel=%s, chat_id=%s", msg.channel_name, msg.chat_id)
-        await self.bus.publish_outbound(outbound)
-
-    async def _handle_streaming_chat(
-        self,
-        client,
-        msg: InboundMessage,
-        thread_id: str,
-        assistant_id: str,
-        run_config: dict[str, Any],
-        run_context: dict[str, Any],
-    ) -> None:
-        logger.info("[Manager] invoking runs.stream(thread_id=%s, text=%r)", thread_id, msg.text[:100])
-
-        last_values: dict[str, Any] | list | None = None
-        streamed_buffers: dict[str, str] = {}
-        current_message_id: str | None = None
-        latest_text = ""
-        last_published_text = ""
-        last_publish_at = 0.0
-        stream_error: BaseException | None = None
-
-        try:
-            async for chunk in client.runs.stream(
-                thread_id,
-                assistant_id,
-                input={"messages": [{"role": "human", "content": msg.text}]},
-                config=run_config,
-                context=run_context,
-                stream_mode=["messages-tuple", "values"],
-                multitask_strategy="reject",
-            ):
-                event = getattr(chunk, "event", "")
-                data = getattr(chunk, "data", None)
-
-                if event == "messages-tuple":
-                    accumulated_text, current_message_id = _accumulate_stream_text(streamed_buffers, current_message_id, data)
-                    if accumulated_text:
-                        latest_text = accumulated_text
-                elif event == "values" and isinstance(data, (dict, list)):
-                    last_values = data
-                    snapshot_text = _extract_response_text(data)
-                    if snapshot_text:
-                        latest_text = snapshot_text
-
-                if not latest_text or latest_text == last_published_text:
-                    continue
-
-                now = time.monotonic()
-                if last_published_text and now - last_publish_at < STREAM_UPDATE_MIN_INTERVAL_SECONDS:
-                    continue
-
-                await self.bus.publish_outbound(
-                    OutboundMessage(
-                        channel_name=msg.channel_name,
-                        chat_id=msg.chat_id,
-                        thread_id=thread_id,
-                        text=latest_text,
-                        is_final=False,
-                        thread_ts=msg.thread_ts,
-                    )
-                )
-                last_published_text = latest_text
-                last_publish_at = now
-        except Exception as exc:
-            stream_error = exc
-            if _is_thread_busy_error(exc):
-                logger.warning("[Manager] thread busy (concurrent run rejected): thread_id=%s", thread_id)
-            else:
-                logger.exception("[Manager] streaming error: thread_id=%s", thread_id)
-        finally:
-            result = last_values if last_values is not None else {"messages": [{"type": "ai", "content": latest_text}]}
-            response_text = _extract_response_text(result)
-            artifacts = _extract_artifacts(result)
-            response_text, attachments = _prepare_artifact_delivery(thread_id, response_text, artifacts)
-
-            if not response_text:
-                if attachments:
-                    response_text = _format_artifact_text([attachment.virtual_path for attachment in attachments])
-                elif stream_error:
-                    if _is_thread_busy_error(stream_error):
-                        response_text = THREAD_BUSY_MESSAGE
-                    else:
-                        response_text = "An error occurred while processing your request. Please try again."
-                else:
-                    response_text = latest_text or "(No response from agent)"
-
-            logger.info(
-                "[Manager] streaming response completed: thread_id=%s, response_len=%d, artifacts=%d, error=%s",
-                thread_id,
-                len(response_text),
-                len(artifacts),
-                stream_error,
-            )
-            await self.bus.publish_outbound(
-                OutboundMessage(
-                    channel_name=msg.channel_name,
-                    chat_id=msg.chat_id,
-                    thread_id=thread_id,
-                    text=response_text,
-                    artifacts=artifacts,
-                    attachments=attachments,
-                    is_final=True,
-                    thread_ts=msg.thread_ts,
-                )
-            )
-
-    # -- command handling --------------------------------------------------
-
-    async def _handle_command(self, msg: InboundMessage) -> None:
-        text = msg.text.strip()
-        parts = text.split(maxsplit=1)
-        command = parts[0].lower().lstrip("/")
-
-        if command == "bootstrap":
-            from dataclasses import replace as _dc_replace
-
-            chat_text = parts[1] if len(parts) > 1 else "Initialize workspace"
-            chat_msg = _dc_replace(msg, text=chat_text, msg_type=InboundMessageType.CHAT)
-            await self._handle_chat(chat_msg, extra_context={"is_bootstrap": True})
-            return
-
-        if command == "new":
-            # Create a new thread on the LangGraph Server
-            client = self._get_client()
-            thread = await client.threads.create()
-            new_thread_id = thread["thread_id"]
-            self.store.set_thread_id(
-                msg.channel_name,
-                msg.chat_id,
-                new_thread_id,
-                topic_id=msg.topic_id,
-                user_id=msg.user_id,
-            )
-            reply = "New conversation started."
-        elif command == "status":
-            thread_id = self.store.get_thread_id(msg.channel_name, msg.chat_id, topic_id=msg.topic_id)
-            reply = f"Active thread: {thread_id}" if thread_id else "No active conversation."
-        elif command == "models":
-            reply = await self._fetch_gateway("/api/models", "models")
-        elif command == "memory":
-            reply = await self._fetch_gateway("/api/memory", "memory")
-        elif command == "help":
-            reply = (
-                "Available commands:\n"
-                "/bootstrap — Start a bootstrap session (enables agent setup)\n"
-                "/new — Start a new conversation\n"
-                "/status — Show current thread info\n"
-                "/models — List available models\n"
-                "/memory — Show memory status\n"
-                "/help — Show this help"
-            )
-        else:
-            reply = f"Unknown command: /{command}. Type /help for available commands."
-
-        outbound = OutboundMessage(
-            channel_name=msg.channel_name,
-            chat_id=msg.chat_id,
-            thread_id=self.store.get_thread_id(msg.channel_name, msg.chat_id) or "",
-            text=reply,
-            thread_ts=msg.thread_ts,
-        )
-        await self.bus.publish_outbound(outbound)
-
-    async def _fetch_gateway(self, path: str, kind: str) -> str:
-        """Fetch data from the Gateway API for command responses."""
-        import httpx
-
-        try:
-            async with httpx.AsyncClient() as http:
-                resp = await http.get(f"{self._gateway_url}{path}", timeout=10)
-                resp.raise_for_status()
-                data = resp.json()
-        except Exception:
-            logger.exception("Failed to fetch %s from gateway", kind)
-            return f"Failed to fetch {kind} information."
-
-        if kind == "models":
-            names = [m["name"] for m in data.get("models", [])]
-            return ("Available models:\n" + "\n".join(f"• {n}" for n in names)) if names else "No models configured."
-        elif kind == "memory":
-            facts = data.get("facts", [])
-            return f"Memory contains {len(facts)} fact(s)."
-        return str(data)
-
-    # -- error helper ------------------------------------------------------
-
-    async def _send_error(self, msg: InboundMessage, error_text: str) -> None:
-        outbound = OutboundMessage(
-            channel_name=msg.channel_name,
-            chat_id=msg.chat_id,
-            thread_id=self.store.get_thread_id(msg.channel_name, msg.chat_id) or "",
-            text=error_text,
-            thread_ts=msg.thread_ts,
-        )
-        await self.bus.publish_outbound(outbound)

backend/app/channels/message_bus.py

@@ -1,173 +0,0 @@
-"""MessageBus — async pub/sub hub that decouples channels from the agent dispatcher."""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-import time
-from collections.abc import Callable, Coroutine
-from dataclasses import dataclass, field
-from enum import StrEnum
-from pathlib import Path
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# Message types
-# ---------------------------------------------------------------------------
-
-
-class InboundMessageType(StrEnum):
-    """Types of messages arriving from IM channels."""
-
-    CHAT = "chat"
-    COMMAND = "command"
-
-
-@dataclass
-class InboundMessage:
-    """A message arriving from an IM channel toward the agent dispatcher.
-
-    Attributes:
-        channel_name: Name of the source channel (e.g. "feishu", "slack").
-        chat_id: Platform-specific chat/conversation identifier.
-        user_id: Platform-specific user identifier.
-        text: The message text.
-        msg_type: Whether this is a regular chat message or a command.
-        thread_ts: Optional platform thread identifier (for threaded replies).
-        topic_id: Conversation topic identifier used to map to a DeerFlow thread.
-            Messages sharing the same ``topic_id`` within a ``chat_id`` will
-            reuse the same DeerFlow thread.  When ``None``, each message
-            creates a new thread (one-shot Q&A).
-        files: Optional list of file attachments (platform-specific dicts).
-        metadata: Arbitrary extra data from the channel.
-        created_at: Unix timestamp when the message was created.
-    """
-
-    channel_name: str
-    chat_id: str
-    user_id: str
-    text: str
-    msg_type: InboundMessageType = InboundMessageType.CHAT
-    thread_ts: str | None = None
-    topic_id: str | None = None
-    files: list[dict[str, Any]] = field(default_factory=list)
-    metadata: dict[str, Any] = field(default_factory=dict)
-    created_at: float = field(default_factory=time.time)
-
-
-@dataclass
-class ResolvedAttachment:
-    """A file attachment resolved to a host filesystem path, ready for upload.
-
-    Attributes:
-        virtual_path: Original virtual path (e.g. /mnt/user-data/outputs/report.pdf).
-        actual_path: Resolved host filesystem path.
-        filename: Basename of the file.
-        mime_type: MIME type (e.g. "application/pdf").
-        size: File size in bytes.
-        is_image: True for image/* MIME types (platforms may handle images differently).
-    """
-
-    virtual_path: str
-    actual_path: Path
-    filename: str
-    mime_type: str
-    size: int
-    is_image: bool
-
-
-@dataclass
-class OutboundMessage:
-    """A message from the agent dispatcher back to a channel.
-
-    Attributes:
-        channel_name: Target channel name (used for routing).
-        chat_id: Target chat/conversation identifier.
-        thread_id: DeerFlow thread ID that produced this response.
-        text: The response text.
-        artifacts: List of artifact paths produced by the agent.
-        is_final: Whether this is the final message in the response stream.
-        thread_ts: Optional platform thread identifier for threaded replies.
-        metadata: Arbitrary extra data.
-        created_at: Unix timestamp.
-    """
-
-    channel_name: str
-    chat_id: str
-    thread_id: str
-    text: str
-    artifacts: list[str] = field(default_factory=list)
-    attachments: list[ResolvedAttachment] = field(default_factory=list)
-    is_final: bool = True
-    thread_ts: str | None = None
-    metadata: dict[str, Any] = field(default_factory=dict)
-    created_at: float = field(default_factory=time.time)
-
-
-# ---------------------------------------------------------------------------
-# MessageBus
-# ---------------------------------------------------------------------------
-
-OutboundCallback = Callable[[OutboundMessage], Coroutine[Any, Any, None]]
-
-
-class MessageBus:
-    """Async pub/sub hub connecting channels and the agent dispatcher.
-
-    Channels publish inbound messages; the dispatcher consumes them.
-    The dispatcher publishes outbound messages; channels receive them
-    via registered callbacks.
-    """
-
-    def __init__(self) -> None:
-        self._inbound_queue: asyncio.Queue[InboundMessage] = asyncio.Queue()
-        self._outbound_listeners: list[OutboundCallback] = []
-
-    # -- inbound -----------------------------------------------------------
-
-    async def publish_inbound(self, msg: InboundMessage) -> None:
-        """Enqueue an inbound message from a channel."""
-        await self._inbound_queue.put(msg)
-        logger.info(
-            "[Bus] inbound enqueued: channel=%s, chat_id=%s, type=%s, queue_size=%d",
-            msg.channel_name,
-            msg.chat_id,
-            msg.msg_type.value,
-            self._inbound_queue.qsize(),
-        )
-
-    async def get_inbound(self) -> InboundMessage:
-        """Block until the next inbound message is available."""
-        return await self._inbound_queue.get()
-
-    @property
-    def inbound_queue(self) -> asyncio.Queue[InboundMessage]:
-        return self._inbound_queue
-
-    # -- outbound ----------------------------------------------------------
-
-    def subscribe_outbound(self, callback: OutboundCallback) -> None:
-        """Register an async callback for outbound messages."""
-        self._outbound_listeners.append(callback)
-
-    def unsubscribe_outbound(self, callback: OutboundCallback) -> None:
-        """Remove a previously registered outbound callback."""
-        self._outbound_listeners = [cb for cb in self._outbound_listeners if cb is not callback]
-
-    async def publish_outbound(self, msg: OutboundMessage) -> None:
-        """Dispatch an outbound message to all registered listeners."""
-        logger.info(
-            "[Bus] outbound dispatching: channel=%s, chat_id=%s, listeners=%d, text_len=%d",
-            msg.channel_name,
-            msg.chat_id,
-            len(self._outbound_listeners),
-            len(msg.text),
-        )
-        for callback in self._outbound_listeners:
-            try:
-                await callback(msg)
-            except Exception:
-                logger.exception("Error in outbound callback for channel=%s", msg.channel_name)

backend/app/channels/service.py

@@ -1,192 +0,0 @@
-"""ChannelService — manages the lifecycle of all IM channels."""
-
-from __future__ import annotations
-
-import logging
-import os
-from typing import Any
-
-from app.channels.manager import DEFAULT_GATEWAY_URL, DEFAULT_LANGGRAPH_URL, ChannelManager
-from app.channels.message_bus import MessageBus
-from app.channels.store import ChannelStore
-
-logger = logging.getLogger(__name__)
-
-# Channel name → import path for lazy loading
-_CHANNEL_REGISTRY: dict[str, str] = {
-    "feishu": "app.channels.feishu:FeishuChannel",
-    "slack": "app.channels.slack:SlackChannel",
-    "telegram": "app.channels.telegram:TelegramChannel",
-}
-
-_CHANNELS_LANGGRAPH_URL_ENV = "DEER_FLOW_CHANNELS_LANGGRAPH_URL"
-_CHANNELS_GATEWAY_URL_ENV = "DEER_FLOW_CHANNELS_GATEWAY_URL"
-
-
-def _resolve_service_url(config: dict[str, Any], config_key: str, env_key: str, default: str) -> str:
-    value = config.pop(config_key, None)
-    if isinstance(value, str) and value.strip():
-        return value
-    env_value = os.getenv(env_key, "").strip()
-    if env_value:
-        return env_value
-    return default
-
-
-class ChannelService:
-    """Manages the lifecycle of all configured IM channels.
-
-    Reads configuration from ``config.yaml`` under the ``channels`` key,
-    instantiates enabled channels, and starts the ChannelManager dispatcher.
-    """
-
-    def __init__(self, channels_config: dict[str, Any] | None = None) -> None:
-        self.bus = MessageBus()
-        self.store = ChannelStore()
-        config = dict(channels_config or {})
-        langgraph_url = _resolve_service_url(config, "langgraph_url", _CHANNELS_LANGGRAPH_URL_ENV, DEFAULT_LANGGRAPH_URL)
-        gateway_url = _resolve_service_url(config, "gateway_url", _CHANNELS_GATEWAY_URL_ENV, DEFAULT_GATEWAY_URL)
-        default_session = config.pop("session", None)
-        channel_sessions = {name: channel_config.get("session") for name, channel_config in config.items() if isinstance(channel_config, dict)}
-        self.manager = ChannelManager(
-            bus=self.bus,
-            store=self.store,
-            langgraph_url=langgraph_url,
-            gateway_url=gateway_url,
-            default_session=default_session if isinstance(default_session, dict) else None,
-            channel_sessions=channel_sessions,
-        )
-        self._channels: dict[str, Any] = {}  # name -> Channel instance
-        self._config = config
-        self._running = False
-
-    @classmethod
-    def from_app_config(cls) -> ChannelService:
-        """Create a ChannelService from the application config."""
-        from deerflow.config.app_config import get_app_config
-
-        config = get_app_config()
-        channels_config = {}
-        # extra fields are allowed by AppConfig (extra="allow")
-        extra = config.model_extra or {}
-        if "channels" in extra:
-            channels_config = extra["channels"]
-        return cls(channels_config=channels_config)
-
-    async def start(self) -> None:
-        """Start the manager and all enabled channels."""
-        if self._running:
-            return
-
-        await self.manager.start()
-
-        for name, channel_config in self._config.items():
-            if not isinstance(channel_config, dict):
-                continue
-            if not channel_config.get("enabled", False):
-                logger.info("Channel %s is disabled, skipping", name)
-                continue
-
-            await self._start_channel(name, channel_config)
-
-        self._running = True
-        logger.info("ChannelService started with channels: %s", list(self._channels.keys()))
-
-    async def stop(self) -> None:
-        """Stop all channels and the manager."""
-        for name, channel in list(self._channels.items()):
-            try:
-                await channel.stop()
-                logger.info("Channel %s stopped", name)
-            except Exception:
-                logger.exception("Error stopping channel %s", name)
-        self._channels.clear()
-
-        await self.manager.stop()
-        self._running = False
-        logger.info("ChannelService stopped")
-
-    async def restart_channel(self, name: str) -> bool:
-        """Restart a specific channel. Returns True if successful."""
-        if name in self._channels:
-            try:
-                await self._channels[name].stop()
-            except Exception:
-                logger.exception("Error stopping channel %s for restart", name)
-            del self._channels[name]
-
-        config = self._config.get(name)
-        if not config or not isinstance(config, dict):
-            logger.warning("No config for channel %s", name)
-            return False
-
-        return await self._start_channel(name, config)
-
-    async def _start_channel(self, name: str, config: dict[str, Any]) -> bool:
-        """Instantiate and start a single channel."""
-        import_path = _CHANNEL_REGISTRY.get(name)
-        if not import_path:
-            logger.warning("Unknown channel type: %s", name)
-            return False
-
-        try:
-            from deerflow.reflection import resolve_class
-
-            channel_cls = resolve_class(import_path, base_class=None)
-        except Exception:
-            logger.exception("Failed to import channel class for %s", name)
-            return False
-
-        try:
-            channel = channel_cls(bus=self.bus, config=config)
-            await channel.start()
-            self._channels[name] = channel
-            logger.info("Channel %s started", name)
-            return True
-        except Exception:
-            logger.exception("Failed to start channel %s", name)
-            return False
-
-    def get_status(self) -> dict[str, Any]:
-        """Return status information for all channels."""
-        channels_status = {}
-        for name in _CHANNEL_REGISTRY:
-            config = self._config.get(name, {})
-            enabled = isinstance(config, dict) and config.get("enabled", False)
-            running = name in self._channels and self._channels[name].is_running
-            channels_status[name] = {
-                "enabled": enabled,
-                "running": running,
-            }
-        return {
-            "service_running": self._running,
-            "channels": channels_status,
-        }
-
-
-# -- singleton access -------------------------------------------------------
-
-_channel_service: ChannelService | None = None
-
-
-def get_channel_service() -> ChannelService | None:
-    """Get the singleton ChannelService instance (if started)."""
-    return _channel_service
-
-
-async def start_channel_service() -> ChannelService:
-    """Create and start the global ChannelService from app config."""
-    global _channel_service
-    if _channel_service is not None:
-        return _channel_service
-    _channel_service = ChannelService.from_app_config()
-    await _channel_service.start()
-    return _channel_service
-
-
-async def stop_channel_service() -> None:
-    """Stop the global ChannelService."""
-    global _channel_service
-    if _channel_service is not None:
-        await _channel_service.stop()
-        _channel_service = None

backend/app/channels/slack.py

@@ -1,244 +0,0 @@
-"""Slack channel — connects via Socket Mode (no public IP needed)."""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-from typing import Any
-
-from markdown_to_mrkdwn import SlackMarkdownConverter
-
-from app.channels.base import Channel
-from app.channels.message_bus import InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
-
-logger = logging.getLogger(__name__)
-
-_slack_md_converter = SlackMarkdownConverter()
-
-
-class SlackChannel(Channel):
-    """Slack IM channel using Socket Mode (WebSocket, no public IP).
-
-    Configuration keys (in ``config.yaml`` under ``channels.slack``):
-        - ``bot_token``: Slack Bot User OAuth Token (xoxb-...).
-        - ``app_token``: Slack App-Level Token (xapp-...) for Socket Mode.
-        - ``allowed_users``: (optional) List of allowed Slack user IDs. Empty = allow all.
-    """
-
-    def __init__(self, bus: MessageBus, config: dict[str, Any]) -> None:
-        super().__init__(name="slack", bus=bus, config=config)
-        self._socket_client = None
-        self._web_client = None
-        self._loop: asyncio.AbstractEventLoop | None = None
-        self._allowed_users: set[str] = set(config.get("allowed_users", []))
-
-    async def start(self) -> None:
-        if self._running:
-            return
-
-        try:
-            from slack_sdk import WebClient
-            from slack_sdk.socket_mode import SocketModeClient
-            from slack_sdk.socket_mode.response import SocketModeResponse
-        except ImportError:
-            logger.error("slack-sdk is not installed. Install it with: uv add slack-sdk")
-            return
-
-        self._SocketModeResponse = SocketModeResponse
-
-        bot_token = self.config.get("bot_token", "")
-        app_token = self.config.get("app_token", "")
-
-        if not bot_token or not app_token:
-            logger.error("Slack channel requires bot_token and app_token")
-            return
-
-        self._web_client = WebClient(token=bot_token)
-        self._socket_client = SocketModeClient(
-            app_token=app_token,
-            web_client=self._web_client,
-        )
-        self._loop = asyncio.get_event_loop()
-
-        self._socket_client.socket_mode_request_listeners.append(self._on_socket_event)
-
-        self._running = True
-        self.bus.subscribe_outbound(self._on_outbound)
-
-        # Start socket mode in background thread
-        asyncio.get_event_loop().run_in_executor(None, self._socket_client.connect)
-        logger.info("Slack channel started")
-
-    async def stop(self) -> None:
-        self._running = False
-        self.bus.unsubscribe_outbound(self._on_outbound)
-        if self._socket_client:
-            self._socket_client.close()
-            self._socket_client = None
-        logger.info("Slack channel stopped")
-
-    async def send(self, msg: OutboundMessage, *, _max_retries: int = 3) -> None:
-        if not self._web_client:
-            return
-
-        kwargs: dict[str, Any] = {
-            "channel": msg.chat_id,
-            "text": _slack_md_converter.convert(msg.text),
-        }
-        if msg.thread_ts:
-            kwargs["thread_ts"] = msg.thread_ts
-
-        last_exc: Exception | None = None
-        for attempt in range(_max_retries):
-            try:
-                await asyncio.to_thread(self._web_client.chat_postMessage, **kwargs)
-                # Add a completion reaction to the thread root
-                if msg.thread_ts:
-                    await asyncio.to_thread(
-                        self._add_reaction,
-                        msg.chat_id,
-                        msg.thread_ts,
-                        "white_check_mark",
-                    )
-                return
-            except Exception as exc:
-                last_exc = exc
-                if attempt < _max_retries - 1:
-                    delay = 2**attempt  # 1s, 2s
-                    logger.warning(
-                        "[Slack] send failed (attempt %d/%d), retrying in %ds: %s",
-                        attempt + 1,
-                        _max_retries,
-                        delay,
-                        exc,
-                    )
-                    await asyncio.sleep(delay)
-
-        logger.error("[Slack] send failed after %d attempts: %s", _max_retries, last_exc)
-        # Add failure reaction on error
-        if msg.thread_ts:
-            try:
-                await asyncio.to_thread(
-                    self._add_reaction,
-                    msg.chat_id,
-                    msg.thread_ts,
-                    "x",
-                )
-            except Exception:
-                pass
-        raise last_exc  # type: ignore[misc]
-
-    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
-        if not self._web_client:
-            return False
-
-        try:
-            kwargs: dict[str, Any] = {
-                "channel": msg.chat_id,
-                "file": str(attachment.actual_path),
-                "filename": attachment.filename,
-                "title": attachment.filename,
-            }
-            if msg.thread_ts:
-                kwargs["thread_ts"] = msg.thread_ts
-
-            await asyncio.to_thread(self._web_client.files_upload_v2, **kwargs)
-            logger.info("[Slack] file uploaded: %s to channel=%s", attachment.filename, msg.chat_id)
-            return True
-        except Exception:
-            logger.exception("[Slack] failed to upload file: %s", attachment.filename)
-            return False
-
-    # -- internal ----------------------------------------------------------
-
-    def _add_reaction(self, channel_id: str, timestamp: str, emoji: str) -> None:
-        """Add an emoji reaction to a message (best-effort, non-blocking)."""
-        if not self._web_client:
-            return
-        try:
-            self._web_client.reactions_add(
-                channel=channel_id,
-                timestamp=timestamp,
-                name=emoji,
-            )
-        except Exception as exc:
-            if "already_reacted" not in str(exc):
-                logger.warning("[Slack] failed to add reaction %s: %s", emoji, exc)
-
-    def _send_running_reply(self, channel_id: str, thread_ts: str) -> None:
-        """Send a 'Working on it......' reply in the thread (called from SDK thread)."""
-        if not self._web_client:
-            return
-        try:
-            self._web_client.chat_postMessage(
-                channel=channel_id,
-                text=":hourglass_flowing_sand: Working on it...",
-                thread_ts=thread_ts,
-            )
-            logger.info("[Slack] 'Working on it...' reply sent in channel=%s, thread_ts=%s", channel_id, thread_ts)
-        except Exception:
-            logger.exception("[Slack] failed to send running reply in channel=%s", channel_id)
-
-    def _on_socket_event(self, client, req) -> None:
-        """Called by slack-sdk for each Socket Mode event."""
-        try:
-            # Acknowledge the event
-            response = self._SocketModeResponse(envelope_id=req.envelope_id)
-            client.send_socket_mode_response(response)
-
-            event_type = req.type
-            if event_type != "events_api":
-                return
-
-            event = req.payload.get("event", {})
-            etype = event.get("type", "")
-
-            # Handle message events (DM or @mention)
-            if etype in ("message", "app_mention"):
-                self._handle_message_event(event)
-
-        except Exception:
-            logger.exception("Error processing Slack event")
-
-    def _handle_message_event(self, event: dict) -> None:
-        # Ignore bot messages
-        if event.get("bot_id") or event.get("subtype"):
-            return
-
-        user_id = event.get("user", "")
-
-        # Check allowed users
-        if self._allowed_users and user_id not in self._allowed_users:
-            logger.debug("Ignoring message from non-allowed user: %s", user_id)
-            return
-
-        text = event.get("text", "").strip()
-        if not text:
-            return
-
-        channel_id = event.get("channel", "")
-        thread_ts = event.get("thread_ts") or event.get("ts", "")
-
-        if text.startswith("/"):
-            msg_type = InboundMessageType.COMMAND
-        else:
-            msg_type = InboundMessageType.CHAT
-
-        # topic_id: use thread_ts as the topic identifier.
-        # For threaded messages, thread_ts is the root message ts (shared topic).
-        # For non-threaded messages, thread_ts is the message's own ts (new topic).
-        inbound = self._make_inbound(
-            chat_id=channel_id,
-            user_id=user_id,
-            text=text,
-            msg_type=msg_type,
-            thread_ts=thread_ts,
-        )
-        inbound.topic_id = thread_ts
-
-        if self._loop and self._loop.is_running():
-            # Acknowledge with an eyes reaction
-            self._add_reaction(channel_id, event.get("ts", thread_ts), "eyes")
-            # Send "running" reply first (fire-and-forget from SDK thread)
-            self._send_running_reply(channel_id, thread_ts)
-            asyncio.run_coroutine_threadsafe(self.bus.publish_inbound(inbound), self._loop)

backend/app/channels/store.py

@@ -1,153 +0,0 @@
-"""ChannelStore — persists IM chat-to-DeerFlow thread mappings."""
-
-from __future__ import annotations
-
-import json
-import logging
-import tempfile
-import threading
-import time
-from pathlib import Path
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-
-class ChannelStore:
-    """JSON-file-backed store that maps IM conversations to DeerFlow threads.
-
-    Data layout (on disk)::
-
-        {
-            "<channel_name>:<chat_id>": {
-                "thread_id": "<uuid>",
-                "user_id": "<platform_user>",
-                "created_at": 1700000000.0,
-                "updated_at": 1700000000.0
-            },
-            ...
-        }
-
-    The store is intentionally simple — a single JSON file that is atomically
-    rewritten on every mutation. For production workloads with high concurrency,
-    this can be swapped for a proper database backend.
-    """
-
-    def __init__(self, path: str | Path | None = None) -> None:
-        if path is None:
-            from deerflow.config.paths import get_paths
-
-            path = Path(get_paths().base_dir) / "channels" / "store.json"
-        self._path = Path(path)
-        self._path.parent.mkdir(parents=True, exist_ok=True)
-        self._data: dict[str, dict[str, Any]] = self._load()
-        self._lock = threading.Lock()
-
-    # -- persistence -------------------------------------------------------
-
-    def _load(self) -> dict[str, dict[str, Any]]:
-        if self._path.exists():
-            try:
-                return json.loads(self._path.read_text(encoding="utf-8"))
-            except (json.JSONDecodeError, OSError):
-                logger.warning("Corrupt channel store at %s, starting fresh", self._path)
-        return {}
-
-    def _save(self) -> None:
-        fd = tempfile.NamedTemporaryFile(
-            mode="w",
-            dir=self._path.parent,
-            suffix=".tmp",
-            delete=False,
-        )
-        try:
-            json.dump(self._data, fd, indent=2)
-            fd.close()
-            Path(fd.name).replace(self._path)
-        except BaseException:
-            fd.close()
-            Path(fd.name).unlink(missing_ok=True)
-            raise
-
-    # -- key helpers -------------------------------------------------------
-
-    @staticmethod
-    def _key(channel_name: str, chat_id: str, topic_id: str | None = None) -> str:
-        if topic_id:
-            return f"{channel_name}:{chat_id}:{topic_id}"
-        return f"{channel_name}:{chat_id}"
-
-    # -- public API --------------------------------------------------------
-
-    def get_thread_id(self, channel_name: str, chat_id: str, topic_id: str | None = None) -> str | None:
-        """Look up the DeerFlow thread_id for a given IM conversation/topic."""
-        entry = self._data.get(self._key(channel_name, chat_id, topic_id))
-        return entry["thread_id"] if entry else None
-
-    def set_thread_id(
-        self,
-        channel_name: str,
-        chat_id: str,
-        thread_id: str,
-        *,
-        topic_id: str | None = None,
-        user_id: str = "",
-    ) -> None:
-        """Create or update the mapping for an IM conversation/topic."""
-        with self._lock:
-            key = self._key(channel_name, chat_id, topic_id)
-            now = time.time()
-            existing = self._data.get(key)
-            self._data[key] = {
-                "thread_id": thread_id,
-                "user_id": user_id,
-                "created_at": existing["created_at"] if existing else now,
-                "updated_at": now,
-            }
-            self._save()
-
-    def remove(self, channel_name: str, chat_id: str, topic_id: str | None = None) -> bool:
-        """Remove a mapping.
-
-        If ``topic_id`` is provided, only that specific conversation/topic mapping is removed.
-        If ``topic_id`` is omitted, all mappings whose key starts with
-        ``"<channel_name>:<chat_id>"`` (including topic-specific ones) are removed.
-
-        Returns True if at least one mapping was removed.
-        """
-        with self._lock:
-            # Remove a specific conversation/topic mapping.
-            if topic_id is not None:
-                key = self._key(channel_name, chat_id, topic_id)
-                if key in self._data:
-                    del self._data[key]
-                    self._save()
-                    return True
-                return False
-
-            # Remove all mappings for this channel/chat_id (base and any topic-specific keys).
-            prefix = self._key(channel_name, chat_id)
-            keys_to_delete = [k for k in self._data if k == prefix or k.startswith(prefix + ":")]
-            if not keys_to_delete:
-                return False
-
-            for k in keys_to_delete:
-                del self._data[k]
-            self._save()
-            return True
-
-    def list_entries(self, channel_name: str | None = None) -> list[dict[str, Any]]:
-        """List all stored mappings, optionally filtered by channel."""
-        results = []
-        for key, entry in self._data.items():
-            parts = key.split(":", 2)
-            ch = parts[0]
-            chat = parts[1] if len(parts) > 1 else ""
-            topic = parts[2] if len(parts) > 2 else None
-            if channel_name and ch != channel_name:
-                continue
-            item: dict[str, Any] = {"channel_name": ch, "chat_id": chat, **entry}
-            if topic is not None:
-                item["topic_id"] = topic
-            results.append(item)
-        return results

backend/app/channels/telegram.py

@@ -1,315 +0,0 @@
-"""Telegram channel — connects via long-polling (no public IP needed)."""
-
-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 InboundMessage, InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
-
-logger = logging.getLogger(__name__)
-
-
-class TelegramChannel(Channel):
-    """Telegram bot channel using long-polling.
-
-    Configuration keys (in ``config.yaml`` under ``channels.telegram``):
-        - ``bot_token``: Telegram Bot API token (from @BotFather).
-        - ``allowed_users``: (optional) List of allowed Telegram user IDs. Empty = allow all.
-    """
-
-    def __init__(self, bus: MessageBus, config: dict[str, Any]) -> None:
-        super().__init__(name="telegram", bus=bus, config=config)
-        self._application = None
-        self._thread: threading.Thread | None = None
-        self._tg_loop: asyncio.AbstractEventLoop | None = None
-        self._main_loop: asyncio.AbstractEventLoop | None = None
-        self._allowed_users: set[int] = set()
-        for uid in config.get("allowed_users", []):
-            try:
-                self._allowed_users.add(int(uid))
-            except (ValueError, TypeError):
-                pass
-        # chat_id -> last sent message_id for threaded replies
-        self._last_bot_message: dict[str, int] = {}
-
-    async def start(self) -> None:
-        if self._running:
-            return
-
-        try:
-            from telegram.ext import ApplicationBuilder, CommandHandler, MessageHandler, filters
-        except ImportError:
-            logger.error("python-telegram-bot is not installed. Install it with: uv add python-telegram-bot")
-            return
-
-        bot_token = self.config.get("bot_token", "")
-        if not bot_token:
-            logger.error("Telegram channel requires bot_token")
-            return
-
-        self._main_loop = asyncio.get_event_loop()
-        self._running = True
-        self.bus.subscribe_outbound(self._on_outbound)
-
-        # Build the application
-        app = ApplicationBuilder().token(bot_token).build()
-
-        # Command handlers
-        app.add_handler(CommandHandler("start", self._cmd_start))
-        app.add_handler(CommandHandler("new", self._cmd_generic))
-        app.add_handler(CommandHandler("status", self._cmd_generic))
-        app.add_handler(CommandHandler("models", self._cmd_generic))
-        app.add_handler(CommandHandler("memory", self._cmd_generic))
-        app.add_handler(CommandHandler("help", self._cmd_generic))
-
-        # General message handler
-        app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, self._on_text))
-
-        self._application = app
-
-        # Run polling in a dedicated thread with its own event loop
-        self._thread = threading.Thread(target=self._run_polling, daemon=True)
-        self._thread.start()
-        logger.info("Telegram channel started")
-
-    async def stop(self) -> None:
-        self._running = False
-        self.bus.unsubscribe_outbound(self._on_outbound)
-        if self._tg_loop and self._tg_loop.is_running():
-            self._tg_loop.call_soon_threadsafe(self._tg_loop.stop)
-        if self._thread:
-            self._thread.join(timeout=10)
-            self._thread = None
-        self._application = None
-        logger.info("Telegram channel stopped")
-
-    async def send(self, msg: OutboundMessage, *, _max_retries: int = 3) -> None:
-        if not self._application:
-            return
-
-        try:
-            chat_id = int(msg.chat_id)
-        except (ValueError, TypeError):
-            logger.error("Invalid Telegram chat_id: %s", msg.chat_id)
-            return
-
-        kwargs: dict[str, Any] = {"chat_id": chat_id, "text": msg.text}
-
-        # Reply to the last bot message in this chat for threading
-        reply_to = self._last_bot_message.get(msg.chat_id)
-        if reply_to:
-            kwargs["reply_to_message_id"] = reply_to
-
-        bot = self._application.bot
-        last_exc: Exception | None = None
-        for attempt in range(_max_retries):
-            try:
-                sent = await bot.send_message(**kwargs)
-                self._last_bot_message[msg.chat_id] = sent.message_id
-                return
-            except Exception as exc:
-                last_exc = exc
-                if attempt < _max_retries - 1:
-                    delay = 2**attempt  # 1s, 2s
-                    logger.warning(
-                        "[Telegram] send failed (attempt %d/%d), retrying in %ds: %s",
-                        attempt + 1,
-                        _max_retries,
-                        delay,
-                        exc,
-                    )
-                    await asyncio.sleep(delay)
-
-        logger.error("[Telegram] send failed after %d attempts: %s", _max_retries, last_exc)
-        raise last_exc  # type: ignore[misc]
-
-    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
-        if not self._application:
-            return False
-
-        try:
-            chat_id = int(msg.chat_id)
-        except (ValueError, TypeError):
-            logger.error("[Telegram] Invalid chat_id: %s", msg.chat_id)
-            return False
-
-        # Telegram limits: 10MB for photos, 50MB for documents
-        if attachment.size > 50 * 1024 * 1024:
-            logger.warning("[Telegram] file too large (%d bytes), skipping: %s", attachment.size, attachment.filename)
-            return False
-
-        bot = self._application.bot
-        reply_to = self._last_bot_message.get(msg.chat_id)
-
-        try:
-            if attachment.is_image and attachment.size <= 10 * 1024 * 1024:
-                with open(attachment.actual_path, "rb") as f:
-                    kwargs: dict[str, Any] = {"chat_id": chat_id, "photo": f}
-                    if reply_to:
-                        kwargs["reply_to_message_id"] = reply_to
-                    sent = await bot.send_photo(**kwargs)
-            else:
-                from telegram import InputFile
-
-                with open(attachment.actual_path, "rb") as f:
-                    input_file = InputFile(f, filename=attachment.filename)
-                    kwargs = {"chat_id": chat_id, "document": input_file}
-                    if reply_to:
-                        kwargs["reply_to_message_id"] = reply_to
-                    sent = await bot.send_document(**kwargs)
-
-            self._last_bot_message[msg.chat_id] = sent.message_id
-            logger.info("[Telegram] file sent: %s to chat=%s", attachment.filename, msg.chat_id)
-            return True
-        except Exception:
-            logger.exception("[Telegram] failed to send file: %s", attachment.filename)
-            return False
-
-    # -- helpers -----------------------------------------------------------
-
-    async def _send_running_reply(self, chat_id: str, reply_to_message_id: int) -> None:
-        """Send a 'Working on it...' reply to the user's message."""
-        if not self._application:
-            return
-        try:
-            bot = self._application.bot
-            await bot.send_message(
-                chat_id=int(chat_id),
-                text="Working on it...",
-                reply_to_message_id=reply_to_message_id,
-            )
-            logger.info("[Telegram] 'Working on it...' reply sent in chat=%s", chat_id)
-        except Exception:
-            logger.exception("[Telegram] failed to send running reply in chat=%s", chat_id)
-
-    # -- internal ----------------------------------------------------------
-    @staticmethod
-    def _log_future_error(fut, name: str, msg_id: str):
-        try:
-            exc = fut.exception()
-            if exc:
-                logger.error("[Telegram] %s failed for msg_id=%s: %s", name, msg_id, exc)
-        except Exception:
-            logger.exception("[Telegram] Failed to inspect future for %s (msg_id=%s)", name, msg_id)
-
-    def _run_polling(self) -> None:
-        """Run telegram polling in a dedicated thread."""
-        self._tg_loop = asyncio.new_event_loop()
-        asyncio.set_event_loop(self._tg_loop)
-        try:
-            # Cannot use run_polling() because it calls add_signal_handler(),
-            # which only works in the main thread.  Instead, manually
-            # initialize the application and start the updater.
-            self._tg_loop.run_until_complete(self._application.initialize())
-            self._tg_loop.run_until_complete(self._application.start())
-            self._tg_loop.run_until_complete(self._application.updater.start_polling())
-            self._tg_loop.run_forever()
-        except Exception:
-            if self._running:
-                logger.exception("Telegram polling error")
-        finally:
-            # Graceful shutdown
-            try:
-                if self._application.updater.running:
-                    self._tg_loop.run_until_complete(self._application.updater.stop())
-                self._tg_loop.run_until_complete(self._application.stop())
-                self._tg_loop.run_until_complete(self._application.shutdown())
-            except Exception:
-                logger.exception("Error during Telegram shutdown")
-
-    def _check_user(self, user_id: int) -> bool:
-        if not self._allowed_users:
-            return True
-        return user_id in self._allowed_users
-
-    async def _cmd_start(self, update, context) -> None:
-        """Handle /start command."""
-        if not self._check_user(update.effective_user.id):
-            return
-        await update.message.reply_text("Welcome to DeerFlow! Send me a message to start a conversation.\nType /help for available commands.")
-
-    async def _process_incoming_with_reply(self, chat_id: str, msg_id: int, inbound: InboundMessage) -> None:
-        await self._send_running_reply(chat_id, msg_id)
-        await self.bus.publish_inbound(inbound)
-
-    async def _cmd_generic(self, update, context) -> None:
-        """Forward slash commands to the channel manager."""
-        if not self._check_user(update.effective_user.id):
-            return
-
-        text = update.message.text
-        chat_id = str(update.effective_chat.id)
-        user_id = str(update.effective_user.id)
-        msg_id = str(update.message.message_id)
-
-        # Use the same topic_id logic as _on_text so that commands
-        # like /new target the correct thread mapping.
-        if update.effective_chat.type == "private":
-            topic_id = None
-        else:
-            reply_to = update.message.reply_to_message
-            if reply_to:
-                topic_id = str(reply_to.message_id)
-            else:
-                topic_id = msg_id
-
-        inbound = self._make_inbound(
-            chat_id=chat_id,
-            user_id=user_id,
-            text=text,
-            msg_type=InboundMessageType.COMMAND,
-            thread_ts=msg_id,
-        )
-        inbound.topic_id = topic_id
-
-        if self._main_loop and self._main_loop.is_running():
-            fut = asyncio.run_coroutine_threadsafe(self._process_incoming_with_reply(chat_id, update.message.message_id, inbound), self._main_loop)
-            fut.add_done_callback(lambda f: self._log_future_error(f, "process_incoming_with_reply", update.message.message_id))
-        else:
-            logger.warning("[Telegram] Main loop not running. Cannot publish inbound message.")
-
-    async def _on_text(self, update, context) -> None:
-        """Handle regular text messages."""
-        if not self._check_user(update.effective_user.id):
-            return
-
-        text = update.message.text.strip()
-        if not text:
-            return
-
-        chat_id = str(update.effective_chat.id)
-        user_id = str(update.effective_user.id)
-        msg_id = str(update.message.message_id)
-
-        # topic_id determines which DeerFlow thread the message maps to.
-        # In private chats, use None so that all messages share a single
-        # thread (the store key becomes "channel:chat_id").
-        # In group chats, use the reply-to message id or the current
-        # message id to keep separate conversation threads.
-        if update.effective_chat.type == "private":
-            topic_id = None
-        else:
-            reply_to = update.message.reply_to_message
-            if reply_to:
-                topic_id = str(reply_to.message_id)
-            else:
-                topic_id = msg_id
-
-        inbound = self._make_inbound(
-            chat_id=chat_id,
-            user_id=user_id,
-            text=text,
-            msg_type=InboundMessageType.CHAT,
-            thread_ts=msg_id,
-        )
-        inbound.topic_id = topic_id
-
-        if self._main_loop and self._main_loop.is_running():
-            fut = asyncio.run_coroutine_threadsafe(self._process_incoming_with_reply(chat_id, update.message.message_id, inbound), self._main_loop)
-            fut.add_done_callback(lambda f: self._log_future_error(f, "process_incoming_with_reply", update.message.message_id))
-        else:
-            logger.warning("[Telegram] Main loop not running. Cannot publish inbound message.")

backend/app/gateway/deps.py

@@ -1,70 +0,0 @@
-"""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``.
-
-Initialization is handled directly in ``app.py`` via :class:`AsyncExitStack`.
-"""
-
-from __future__ import annotations
-
-from collections.abc import AsyncGenerator
-from contextlib import AsyncExitStack, asynccontextmanager
-
-from fastapi import FastAPI, HTTPException, Request
-
-from deerflow.runtime import RunManager, StreamBridge
-
-
-@asynccontextmanager
-async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
-    """Bootstrap and tear down all LangGraph runtime singletons.
-
-    Usage in ``app.py``::
-
-        async with langgraph_runtime(app):
-            yield
-    """
-    from deerflow.agents.checkpointer.async_provider import make_checkpointer
-    from deerflow.runtime import make_store, make_stream_bridge
-
-    async with AsyncExitStack() as stack:
-        app.state.stream_bridge = await stack.enter_async_context(make_stream_bridge())
-        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
-
-
-# ---------------------------------------------------------------------------
-# 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 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
-
-
-def get_store(request: Request):
-    """Return the global store (may be ``None`` if not configured)."""
-    return getattr(request.app.state, "store", None)

backend/app/gateway/routers/__init__.py

@@ -1,3 +0,0 @@
-from . import artifacts, assistants_compat, mcp, models, skills, suggestions, thread_runs, threads, uploads
-
-__all__ = ["artifacts", "assistants_compat", "mcp", "models", "skills", "suggestions", "threads", "thread_runs", "uploads"]

backend/app/gateway/routers/assistants_compat.py

@@ -1,149 +0,0 @@
-"""Assistants compatibility endpoints.
-
-Provides LangGraph Platform-compatible assistants API backed by the
-``langgraph.json`` graph registry and ``config.yaml`` agent definitions.
-
-This is a minimal stub that satisfies the ``useStream`` React hook's
-initialization requirements (``assistants.search()`` and ``assistants.get()``).
-"""
-
-from __future__ import annotations
-
-import logging
-from datetime import UTC, datetime
-from typing import Any
-
-from fastapi import APIRouter, HTTPException
-from pydantic import BaseModel, Field
-
-logger = logging.getLogger(__name__)
-router = APIRouter(prefix="/api/assistants", tags=["assistants-compat"])
-
-
-class AssistantResponse(BaseModel):
-    assistant_id: str
-    graph_id: str
-    name: str
-    config: dict[str, Any] = Field(default_factory=dict)
-    metadata: dict[str, Any] = Field(default_factory=dict)
-    description: str | None = None
-    created_at: str = ""
-    updated_at: str = ""
-    version: int = 1
-
-
-class AssistantSearchRequest(BaseModel):
-    graph_id: str | None = None
-    name: str | None = None
-    metadata: dict[str, Any] | None = None
-    limit: int = 10
-    offset: int = 0
-
-
-def _get_default_assistant() -> AssistantResponse:
-    """Return the default lead_agent assistant."""
-    now = datetime.now(UTC).isoformat()
-    return AssistantResponse(
-        assistant_id="lead_agent",
-        graph_id="lead_agent",
-        name="lead_agent",
-        config={},
-        metadata={"created_by": "system"},
-        description="DeerFlow lead agent",
-        created_at=now,
-        updated_at=now,
-        version=1,
-    )
-
-
-def _list_assistants() -> list[AssistantResponse]:
-    """List all available assistants from config."""
-    assistants = [_get_default_assistant()]
-
-    # Also include custom agents from config.yaml agents directory
-    try:
-        from deerflow.config.agents_config import list_custom_agents
-
-        for agent_cfg in list_custom_agents():
-            now = datetime.now(UTC).isoformat()
-            assistants.append(
-                AssistantResponse(
-                    assistant_id=agent_cfg.name,
-                    graph_id="lead_agent",  # All agents use the same graph
-                    name=agent_cfg.name,
-                    config={},
-                    metadata={"created_by": "user"},
-                    description=agent_cfg.description or "",
-                    created_at=now,
-                    updated_at=now,
-                    version=1,
-                )
-            )
-    except Exception:
-        logger.debug("Could not load custom agents for assistants list")
-
-    return assistants
-
-
-@router.post("/search", response_model=list[AssistantResponse])
-async def search_assistants(body: AssistantSearchRequest | None = None) -> list[AssistantResponse]:
-    """Search assistants.
-
-    Returns all registered assistants (lead_agent + custom agents from config).
-    """
-    assistants = _list_assistants()
-
-    if body and body.graph_id:
-        assistants = [a for a in assistants if a.graph_id == body.graph_id]
-    if body and body.name:
-        assistants = [a for a in assistants if body.name.lower() in a.name.lower()]
-
-    offset = body.offset if body else 0
-    limit = body.limit if body else 10
-    return assistants[offset : offset + limit]
-
-
-@router.get("/{assistant_id}", response_model=AssistantResponse)
-async def get_assistant_compat(assistant_id: str) -> AssistantResponse:
-    """Get an assistant by ID."""
-    for a in _list_assistants():
-        if a.assistant_id == assistant_id:
-            return a
-    raise HTTPException(status_code=404, detail=f"Assistant {assistant_id} not found")
-
-
-@router.get("/{assistant_id}/graph")
-async def get_assistant_graph(assistant_id: str) -> dict:
-    """Get the graph structure for an assistant.
-
-    Returns a minimal graph description. Full graph introspection is
-    not supported in the Gateway — this stub satisfies SDK validation.
-    """
-    found = any(a.assistant_id == assistant_id for a in _list_assistants())
-    if not found:
-        raise HTTPException(status_code=404, detail=f"Assistant {assistant_id} not found")
-
-    return {
-        "graph_id": "lead_agent",
-        "nodes": [],
-        "edges": [],
-    }
-
-
-@router.get("/{assistant_id}/schemas")
-async def get_assistant_schemas(assistant_id: str) -> dict:
-    """Get JSON schemas for an assistant's input/output/state.
-
-    Returns empty schemas — full introspection not supported in Gateway.
-    """
-    found = any(a.assistant_id == assistant_id for a in _list_assistants())
-    if not found:
-        raise HTTPException(status_code=404, detail=f"Assistant {assistant_id} not found")
-
-    return {
-        "graph_id": "lead_agent",
-        "input_schema": {},
-        "output_schema": {},
-        "state_schema": {},
-        "config_schema": {},
-    }

backend/app/gateway/routers/channels.py

@@ -1,52 +0,0 @@
-"""Gateway router for IM channel management."""
-
-from __future__ import annotations
-
-import logging
-
-from fastapi import APIRouter, HTTPException
-from pydantic import BaseModel
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(prefix="/api/channels", tags=["channels"])
-
-
-class ChannelStatusResponse(BaseModel):
-    service_running: bool
-    channels: dict[str, dict]
-
-
-class ChannelRestartResponse(BaseModel):
-    success: bool
-    message: str
-
-
-@router.get("/", response_model=ChannelStatusResponse)
-async def get_channels_status() -> ChannelStatusResponse:
-    """Get the status of all IM channels."""
-    from app.channels.service import get_channel_service
-
-    service = get_channel_service()
-    if service is None:
-        return ChannelStatusResponse(service_running=False, channels={})
-    status = service.get_status()
-    return ChannelStatusResponse(**status)
-
-
-@router.post("/{name}/restart", response_model=ChannelRestartResponse)
-async def restart_channel(name: str) -> ChannelRestartResponse:
-    """Restart a specific IM channel."""
-    from app.channels.service import get_channel_service
-
-    service = get_channel_service()
-    if service is None:
-        raise HTTPException(status_code=503, detail="Channel service is not running")
-
-    success = await service.restart_channel(name)
-    if success:
-        logger.info("Channel %s restarted successfully", name)
-        return ChannelRestartResponse(success=True, message=f"Channel {name} restarted successfully")
-    else:
-        logger.warning("Failed to restart channel %s", name)
-        return ChannelRestartResponse(success=False, message=f"Failed to restart channel {name}")

backend/app/gateway/routers/runs.py

@@ -1,86 +0,0 @@
-"""Stateless runs endpoints -- stream and wait without a pre-existing thread.
-
-These endpoints auto-create a temporary thread when no ``thread_id`` is
-supplied in the request body.  When a ``thread_id`` **is** provided, it
-is reused so that conversation history is preserved across calls.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-import uuid
-
-from fastapi import APIRouter, Request
-from fastapi.responses import StreamingResponse
-
-from app.gateway.deps import get_checkpointer, get_run_manager, get_stream_bridge
-from app.gateway.routers.thread_runs import RunCreateRequest
-from app.gateway.services import sse_consumer, start_run
-from deerflow.runtime import serialize_channel_values
-
-logger = logging.getLogger(__name__)
-router = APIRouter(prefix="/api/runs", tags=["runs"])
-
-
-def _resolve_thread_id(body: RunCreateRequest) -> str:
-    """Return the thread_id from the request body, or generate a new one."""
-    thread_id = (body.config or {}).get("configurable", {}).get("thread_id")
-    if thread_id:
-        return str(thread_id)
-    return str(uuid.uuid4())
-
-
-@router.post("/stream")
-async def stateless_stream(body: RunCreateRequest, request: Request) -> StreamingResponse:
-    """Create a run and stream events via SSE.
-
-    If ``config.configurable.thread_id`` is provided, the run is created
-    on the given thread so that conversation history is preserved.
-    Otherwise a new temporary thread is created.
-    """
-    thread_id = _resolve_thread_id(body)
-    bridge = get_stream_bridge(request)
-    run_mgr = get_run_manager(request)
-    record = await start_run(body, thread_id, request)
-
-    return StreamingResponse(
-        sse_consumer(bridge, record, request, run_mgr),
-        media_type="text/event-stream",
-        headers={
-            "Cache-Control": "no-cache",
-            "Connection": "keep-alive",
-            "X-Accel-Buffering": "no",
-        },
-    )
-
-
-@router.post("/wait", response_model=dict)
-async def stateless_wait(body: RunCreateRequest, request: Request) -> dict:
-    """Create a run and block until completion.
-
-    If ``config.configurable.thread_id`` is provided, the run is created
-    on the given thread so that conversation history is preserved.
-    Otherwise a new temporary thread is created.
-    """
-    thread_id = _resolve_thread_id(body)
-    record = await start_run(body, thread_id, request)
-
-    if record.task is not None:
-        try:
-            await record.task
-        except asyncio.CancelledError:
-            pass
-
-    checkpointer = get_checkpointer(request)
-    config = {"configurable": {"thread_id": thread_id}}
-    try:
-        checkpoint_tuple = await checkpointer.aget_tuple(config)
-        if checkpoint_tuple is not None:
-            checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
-            channel_values = checkpoint.get("channel_values", {})
-            return serialize_channel_values(channel_values)
-    except Exception:
-        logger.exception("Failed to fetch final state for run %s", record.run_id)
-
-    return {"status": record.status.value, "error": record.error}

backend/app/gateway/routers/skills.py

@@ -1,173 +0,0 @@
-import json
-import logging
-from pathlib import Path
-
-from fastapi import APIRouter, HTTPException
-from pydantic import BaseModel, Field
-
-from app.gateway.path_utils import resolve_thread_virtual_path
-from deerflow.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
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(prefix="/api", tags=["skills"])
-
-
-class SkillResponse(BaseModel):
-    """Response model for skill information."""
-
-    name: str = Field(..., description="Name of the skill")
-    description: str = Field(..., description="Description of what the skill does")
-    license: str | None = Field(None, description="License information")
-    category: str = Field(..., description="Category of the skill (public or custom)")
-    enabled: bool = Field(default=True, description="Whether this skill is enabled")
-
-
-class SkillsListResponse(BaseModel):
-    """Response model for listing all skills."""
-
-    skills: list[SkillResponse]
-
-
-class SkillUpdateRequest(BaseModel):
-    """Request model for updating a skill."""
-
-    enabled: bool = Field(..., description="Whether to enable or disable the skill")
-
-
-class SkillInstallRequest(BaseModel):
-    """Request model for installing a skill from a .skill file."""
-
-    thread_id: str = Field(..., description="The thread ID where the .skill file is located")
-    path: str = Field(..., description="Virtual path to the .skill file (e.g., mnt/user-data/outputs/my-skill.skill)")
-
-
-class SkillInstallResponse(BaseModel):
-    """Response model for skill installation."""
-
-    success: bool = Field(..., description="Whether the installation was successful")
-    skill_name: str = Field(..., description="Name of the installed skill")
-    message: str = Field(..., description="Installation result message")
-
-
-def _skill_to_response(skill: Skill) -> SkillResponse:
-    """Convert a Skill object to a SkillResponse."""
-    return SkillResponse(
-        name=skill.name,
-        description=skill.description,
-        license=skill.license,
-        category=skill.category,
-        enabled=skill.enabled,
-    )
-
-
-@router.get(
-    "/skills",
-    response_model=SkillsListResponse,
-    summary="List All Skills",
-    description="Retrieve a list of all available skills from both public and custom directories.",
-)
-async def list_skills() -> SkillsListResponse:
-    try:
-        skills = load_skills(enabled_only=False)
-        return SkillsListResponse(skills=[_skill_to_response(skill) for skill in skills])
-    except Exception as e:
-        logger.error(f"Failed to load skills: {e}", exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to load skills: {str(e)}")
-
-
-@router.get(
-    "/skills/{skill_name}",
-    response_model=SkillResponse,
-    summary="Get Skill Details",
-    description="Retrieve detailed information about a specific skill by its name.",
-)
-async def get_skill(skill_name: str) -> SkillResponse:
-    try:
-        skills = load_skills(enabled_only=False)
-        skill = next((s for s in skills if s.name == skill_name), None)
-
-        if skill is None:
-            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
-
-        return _skill_to_response(skill)
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error(f"Failed to get skill {skill_name}: {e}", exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to get skill: {str(e)}")
-
-
-@router.put(
-    "/skills/{skill_name}",
-    response_model=SkillResponse,
-    summary="Update Skill",
-    description="Update a skill's enabled status by modifying the extensions_config.json file.",
-)
-async def update_skill(skill_name: str, request: SkillUpdateRequest) -> SkillResponse:
-    try:
-        skills = load_skills(enabled_only=False)
-        skill = next((s for s in skills if s.name == skill_name), None)
-
-        if skill is None:
-            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
-
-        config_path = ExtensionsConfig.resolve_config_path()
-        if config_path is None:
-            config_path = Path.cwd().parent / "extensions_config.json"
-            logger.info(f"No existing extensions config found. Creating new config at: {config_path}")
-
-        extensions_config = get_extensions_config()
-        extensions_config.skills[skill_name] = SkillStateConfig(enabled=request.enabled)
-
-        config_data = {
-            "mcpServers": {name: server.model_dump() for name, server in extensions_config.mcp_servers.items()},
-            "skills": {name: {"enabled": skill_config.enabled} for name, skill_config in extensions_config.skills.items()},
-        }
-
-        with open(config_path, "w", encoding="utf-8") as f:
-            json.dump(config_data, f, indent=2)
-
-        logger.info(f"Skills configuration updated and saved to: {config_path}")
-        reload_extensions_config()
-
-        skills = load_skills(enabled_only=False)
-        updated_skill = next((s for s in skills if s.name == skill_name), None)
-
-        if updated_skill is None:
-            raise HTTPException(status_code=500, detail=f"Failed to reload skill '{skill_name}' after update")
-
-        logger.info(f"Skill '{skill_name}' enabled status updated to {request.enabled}")
-        return _skill_to_response(updated_skill)
-
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error(f"Failed to update skill {skill_name}: {e}", exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to update skill: {str(e)}")
-
-
-@router.post(
-    "/skills/install",
-    response_model=SkillInstallResponse,
-    summary="Install Skill",
-    description="Install a skill from a .skill file (ZIP archive) located in the thread's user-data directory.",
-)
-async def install_skill(request: SkillInstallRequest) -> SkillInstallResponse:
-    try:
-        skill_file_path = resolve_thread_virtual_path(request.thread_id, request.path)
-        result = install_skill_from_archive(skill_file_path)
-        return SkillInstallResponse(**result)
-    except FileNotFoundError as e:
-        raise HTTPException(status_code=404, detail=str(e))
-    except SkillAlreadyExistsError as e:
-        raise HTTPException(status_code=409, detail=str(e))
-    except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error(f"Failed to install skill: {e}", exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to install skill: {str(e)}")

backend/app/gateway/routers/suggestions.py

@@ -1,132 +0,0 @@
-import json
-import logging
-
-from fastapi import APIRouter
-from pydantic import BaseModel, Field
-
-from deerflow.models import create_chat_model
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(prefix="/api", tags=["suggestions"])
-
-
-class SuggestionMessage(BaseModel):
-    role: str = Field(..., description="Message role: user|assistant")
-    content: str = Field(..., description="Message content as plain text")
-
-
-class SuggestionsRequest(BaseModel):
-    messages: list[SuggestionMessage] = Field(..., description="Recent conversation messages")
-    n: int = Field(default=3, ge=1, le=5, description="Number of suggestions to generate")
-    model_name: str | None = Field(default=None, description="Optional model override")
-
-
-class SuggestionsResponse(BaseModel):
-    suggestions: list[str] = Field(default_factory=list, description="Suggested follow-up questions")
-
-
-def _strip_markdown_code_fence(text: str) -> str:
-    stripped = text.strip()
-    if not stripped.startswith("```"):
-        return stripped
-    lines = stripped.splitlines()
-    if len(lines) >= 3 and lines[0].startswith("```") and lines[-1].startswith("```"):
-        return "\n".join(lines[1:-1]).strip()
-    return stripped
-
-
-def _parse_json_string_list(text: str) -> list[str] | None:
-    candidate = _strip_markdown_code_fence(text)
-    start = candidate.find("[")
-    end = candidate.rfind("]")
-    if start == -1 or end == -1 or end <= start:
-        return None
-    candidate = candidate[start : end + 1]
-    try:
-        data = json.loads(candidate)
-    except Exception:
-        return None
-    if not isinstance(data, list):
-        return None
-    out: list[str] = []
-    for item in data:
-        if not isinstance(item, str):
-            continue
-        s = item.strip()
-        if not s:
-            continue
-        out.append(s)
-    return out
-
-
-def _extract_response_text(content: object) -> str:
-    if isinstance(content, str):
-        return content
-    if isinstance(content, list):
-        parts: list[str] = []
-        for block in content:
-            if isinstance(block, str):
-                parts.append(block)
-            elif isinstance(block, dict) and block.get("type") in {"text", "output_text"}:
-                text = block.get("text")
-                if isinstance(text, str):
-                    parts.append(text)
-        return "\n".join(parts) if parts else ""
-    if content is None:
-        return ""
-    return str(content)
-
-
-def _format_conversation(messages: list[SuggestionMessage]) -> str:
-    parts: list[str] = []
-    for m in messages:
-        role = m.role.strip().lower()
-        if role in ("user", "human"):
-            parts.append(f"User: {m.content.strip()}")
-        elif role in ("assistant", "ai"):
-            parts.append(f"Assistant: {m.content.strip()}")
-        else:
-            parts.append(f"{m.role}: {m.content.strip()}")
-    return "\n".join(parts).strip()
-
-
-@router.post(
-    "/threads/{thread_id}/suggestions",
-    response_model=SuggestionsResponse,
-    summary="Generate Follow-up Questions",
-    description="Generate short follow-up questions a user might ask next, based on recent conversation context.",
-)
-async def generate_suggestions(thread_id: str, request: SuggestionsRequest) -> SuggestionsResponse:
-    if not request.messages:
-        return SuggestionsResponse(suggestions=[])
-
-    n = request.n
-    conversation = _format_conversation(request.messages)
-    if not conversation:
-        return SuggestionsResponse(suggestions=[])
-
-    prompt = (
-        "You are generating follow-up questions to help the user continue the conversation.\n"
-        f"Based on the conversation below, produce EXACTLY {n} short questions the user might ask next.\n"
-        "Requirements:\n"
-        "- Questions must be relevant to the conversation.\n"
-        "- Questions must be written in the same language as the user.\n"
-        "- Keep each question concise (ideally <= 20 words / <= 40 Chinese characters).\n"
-        "- Do NOT include numbering, markdown, or any extra text.\n"
-        "- Output MUST be a JSON array of strings only.\n\n"
-        "Conversation:\n"
-        f"{conversation}\n"
-    )
-
-    try:
-        model = create_chat_model(name=request.model_name, thinking_enabled=False)
-        response = model.invoke(prompt)
-        raw = _extract_response_text(response.content)
-        suggestions = _parse_json_string_list(raw) or []
-        cleaned = [s.replace("\n", " ").strip() for s in suggestions if s.strip()]
-        cleaned = cleaned[:n]
-        return SuggestionsResponse(suggestions=cleaned)
-    except Exception as exc:
-        logger.exception("Failed to generate suggestions: thread_id=%s err=%s", thread_id, exc)
-        return SuggestionsResponse(suggestions=[])

backend/app/gateway/routers/thread_runs.py

@@ -1,266 +0,0 @@
-"""Runs endpoints — create, stream, wait, cancel.
-
-Implements the LangGraph Platform runs API on top of
-:class:`deerflow.agents.runs.RunManager` and
-:class:`deerflow.agents.stream_bridge.StreamBridge`.
-
-SSE format is aligned with the LangGraph Platform protocol so that
-the ``useStream`` React hook from ``@langchain/langgraph-sdk/react``
-works without modification.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-from typing import Any, Literal
-
-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.services import sse_consumer, start_run
-from deerflow.runtime import RunRecord, serialize_channel_values
-
-logger = logging.getLogger(__name__)
-router = APIRouter(prefix="/api/threads", tags=["runs"])
-
-
-# ---------------------------------------------------------------------------
-# Request / response models
-# ---------------------------------------------------------------------------
-
-
-class RunCreateRequest(BaseModel):
-    assistant_id: str | None = Field(default=None, description="Agent / assistant to use")
-    input: dict[str, Any] | None = Field(default=None, description="Graph input (e.g. {messages: [...]})")
-    command: dict[str, Any] | None = Field(default=None, description="LangGraph Command")
-    metadata: dict[str, Any] | None = Field(default=None, description="Run metadata")
-    config: dict[str, Any] | None = Field(default=None, description="RunnableConfig overrides")
-    context: dict[str, Any] | None = Field(default=None, description="DeerFlow context overrides (model_name, thinking_enabled, etc.)")
-    webhook: str | None = Field(default=None, description="Completion callback URL")
-    checkpoint_id: str | None = Field(default=None, description="Resume from checkpoint")
-    checkpoint: dict[str, Any] | None = Field(default=None, description="Full checkpoint object")
-    interrupt_before: list[str] | Literal["*"] | None = Field(default=None, description="Nodes to interrupt before")
-    interrupt_after: list[str] | Literal["*"] | None = Field(default=None, description="Nodes to interrupt after")
-    stream_mode: list[str] | str | None = Field(default=None, description="Stream mode(s)")
-    stream_subgraphs: bool = Field(default=False, description="Include subgraph events")
-    stream_resumable: bool | None = Field(default=None, description="SSE resumable mode")
-    on_disconnect: Literal["cancel", "continue"] = Field(default="cancel", description="Behaviour on SSE disconnect")
-    on_completion: Literal["delete", "keep"] = Field(default="keep", description="Delete temp thread on completion")
-    multitask_strategy: Literal["reject", "rollback", "interrupt", "enqueue"] = Field(default="reject", description="Concurrency strategy")
-    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")
-
-
-class RunResponse(BaseModel):
-    run_id: str
-    thread_id: str
-    assistant_id: str | None = None
-    status: str
-    metadata: dict[str, Any] = Field(default_factory=dict)
-    kwargs: dict[str, Any] = Field(default_factory=dict)
-    multitask_strategy: str = "reject"
-    created_at: str = ""
-    updated_at: str = ""
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-
-def _record_to_response(record: RunRecord) -> RunResponse:
-    return RunResponse(
-        run_id=record.run_id,
-        thread_id=record.thread_id,
-        assistant_id=record.assistant_id,
-        status=record.status.value,
-        metadata=record.metadata,
-        kwargs=record.kwargs,
-        multitask_strategy=record.multitask_strategy,
-        created_at=record.created_at,
-        updated_at=record.updated_at,
-    )
-
-
-# ---------------------------------------------------------------------------
-# Endpoints
-# ---------------------------------------------------------------------------
-
-
-@router.post("/{thread_id}/runs", response_model=RunResponse)
-async def create_run(thread_id: str, body: RunCreateRequest, request: Request) -> RunResponse:
-    """Create a background run (returns immediately)."""
-    record = await start_run(body, thread_id, request)
-    return _record_to_response(record)
-
-
-@router.post("/{thread_id}/runs/stream")
-async def stream_run(thread_id: str, body: RunCreateRequest, request: Request) -> StreamingResponse:
-    """Create a run and stream events via SSE.
-
-    The response includes a ``Content-Location`` header with the run's
-    resource URL, matching the LangGraph Platform protocol.  The
-    ``useStream`` React hook uses this to extract run metadata.
-    """
-    bridge = get_stream_bridge(request)
-    run_mgr = get_run_manager(request)
-    record = await start_run(body, thread_id, request)
-
-    return StreamingResponse(
-        sse_consumer(bridge, record, request, run_mgr),
-        media_type="text/event-stream",
-        headers={
-            "Cache-Control": "no-cache",
-            "Connection": "keep-alive",
-            "X-Accel-Buffering": "no",
-            # LangGraph Platform includes run metadata in this header.
-            # The SDK's _get_run_metadata_from_response() parses it.
-            "Content-Location": (f"/api/threads/{thread_id}/runs/{record.run_id}/stream?thread_id={thread_id}&run_id={record.run_id}"),
-        },
-    )
-
-
-@router.post("/{thread_id}/runs/wait", response_model=dict)
-async def wait_run(thread_id: str, body: RunCreateRequest, request: Request) -> dict:
-    """Create a run and block until it completes, returning the final state."""
-    record = await start_run(body, thread_id, request)
-
-    if record.task is not None:
-        try:
-            await record.task
-        except asyncio.CancelledError:
-            pass
-
-    checkpointer = get_checkpointer(request)
-    config = {"configurable": {"thread_id": thread_id}}
-    try:
-        checkpoint_tuple = await checkpointer.aget_tuple(config)
-        if checkpoint_tuple is not None:
-            checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
-            channel_values = checkpoint.get("channel_values", {})
-            return serialize_channel_values(channel_values)
-    except Exception:
-        logger.exception("Failed to fetch final state for run %s", record.run_id)
-
-    return {"status": record.status.value, "error": record.error}
-
-
-@router.get("/{thread_id}/runs", response_model=list[RunResponse])
-async def list_runs(thread_id: str, request: Request) -> list[RunResponse]:
-    """List all runs for a thread."""
-    run_mgr = get_run_manager(request)
-    records = await run_mgr.list_by_thread(thread_id)
-    return [_record_to_response(r) for r in records]
-
-
-@router.get("/{thread_id}/runs/{run_id}", response_model=RunResponse)
-async def get_run(thread_id: str, run_id: str, request: Request) -> RunResponse:
-    """Get details of a specific run."""
-    run_mgr = get_run_manager(request)
-    record = run_mgr.get(run_id)
-    if record is None or record.thread_id != thread_id:
-        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
-    return _record_to_response(record)
-
-
-@router.post("/{thread_id}/runs/{run_id}/cancel")
-async def cancel_run(
-    thread_id: str,
-    run_id: str,
-    request: Request,
-    wait: bool = Query(default=False, description="Block until run completes after cancel"),
-    action: Literal["interrupt", "rollback"] = Query(default="interrupt", description="Cancel action"),
-) -> Response:
-    """Cancel a running or pending run.
-
-    - action=interrupt: Stop execution, keep current checkpoint (can be resumed)
-    - action=rollback: Stop execution, revert to pre-run checkpoint state
-    - wait=true: Block until the run fully stops, return 204
-    - wait=false: Return immediately with 202
-    """
-    run_mgr = get_run_manager(request)
-    record = run_mgr.get(run_id)
-    if record is None or record.thread_id != thread_id:
-        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
-
-    cancelled = await run_mgr.cancel(run_id, action=action)
-    if not cancelled:
-        raise HTTPException(
-            status_code=409,
-            detail=f"Run {run_id} is not cancellable (status: {record.status.value})",
-        )
-
-    if wait and record.task is not None:
-        try:
-            await record.task
-        except asyncio.CancelledError:
-            pass
-        return Response(status_code=204)
-
-    return Response(status_code=202)
-
-
-@router.get("/{thread_id}/runs/{run_id}/join")
-async def join_run(thread_id: str, run_id: str, request: Request) -> StreamingResponse:
-    """Join an existing run's SSE stream."""
-    bridge = get_stream_bridge(request)
-    run_mgr = get_run_manager(request)
-    record = run_mgr.get(run_id)
-    if record is None or record.thread_id != thread_id:
-        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
-
-    return StreamingResponse(
-        sse_consumer(bridge, record, request, run_mgr),
-        media_type="text/event-stream",
-        headers={
-            "Cache-Control": "no-cache",
-            "Connection": "keep-alive",
-            "X-Accel-Buffering": "no",
-        },
-    )
-
-
-@router.api_route("/{thread_id}/runs/{run_id}/stream", methods=["GET", "POST"], response_model=None)
-async def stream_existing_run(
-    thread_id: str,
-    run_id: str,
-    request: Request,
-    action: Literal["interrupt", "rollback"] | None = Query(default=None, description="Cancel action"),
-    wait: int = Query(default=0, description="Block until cancelled (1) or return immediately (0)"),
-):
-    """Join an existing run's SSE stream (GET), or cancel-then-stream (POST).
-
-    The LangGraph SDK's ``joinStream`` and ``useStream`` stop button both use
-    ``POST`` to this endpoint.  When ``action=interrupt`` or ``action=rollback``
-    is present the run is cancelled first; the response then streams any
-    remaining buffered events so the client observes a clean shutdown.
-    """
-    run_mgr = get_run_manager(request)
-    record = run_mgr.get(run_id)
-    if record is None or record.thread_id != thread_id:
-        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
-
-    # Cancel if an action was requested (stop-button / interrupt flow)
-    if action is not None:
-        cancelled = await run_mgr.cancel(run_id, action=action)
-        if cancelled and wait and record.task is not None:
-            try:
-                await record.task
-            except (asyncio.CancelledError, Exception):
-                pass
-            return Response(status_code=204)
-
-    bridge = get_stream_bridge(request)
-    return StreamingResponse(
-        sse_consumer(bridge, record, request, run_mgr),
-        media_type="text/event-stream",
-        headers={
-            "Cache-Control": "no-cache",
-            "Connection": "keep-alive",
-            "X-Accel-Buffering": "no",
-        },
-    )

backend/app/gateway/routers/threads.py

@@ -1,679 +0,0 @@
-"""Thread CRUD, state, and history endpoints.
-
-Combines the existing thread-local filesystem cleanup with LangGraph
-Platform-compatible thread management backed by the checkpointer.
-
-Channel values returned in state responses are serialized through
-:func:`deerflow.runtime.serialization.serialize_channel_values` to
-ensure LangChain message objects are converted to JSON-safe dicts
-matching the LangGraph Platform wire format expected by the
-``useStream`` React hook.
-"""
-
-from __future__ import annotations
-
-import logging
-import time
-import uuid
-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 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"])
-
-
-# ---------------------------------------------------------------------------
-# Response / request models
-# ---------------------------------------------------------------------------
-
-
-class ThreadDeleteResponse(BaseModel):
-    """Response model for thread cleanup."""
-
-    success: bool
-    message: str
-
-
-class ThreadResponse(BaseModel):
-    """Response model for a single thread."""
-
-    thread_id: str = Field(description="Unique thread identifier")
-    status: str = Field(default="idle", description="Thread status: idle, busy, interrupted, error")
-    created_at: str = Field(default="", description="ISO timestamp")
-    updated_at: str = Field(default="", description="ISO timestamp")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Thread metadata")
-    values: dict[str, Any] = Field(default_factory=dict, description="Current state channel values")
-    interrupts: dict[str, Any] = Field(default_factory=dict, description="Pending interrupts")
-
-
-class ThreadCreateRequest(BaseModel):
-    """Request body for creating a thread."""
-
-    thread_id: str | None = Field(default=None, description="Optional thread ID (auto-generated if omitted)")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Initial metadata")
-
-
-class ThreadSearchRequest(BaseModel):
-    """Request body for searching threads."""
-
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Metadata filter (exact match)")
-    limit: int = Field(default=100, ge=1, le=1000, description="Maximum results")
-    offset: int = Field(default=0, ge=0, description="Pagination offset")
-    status: str | None = Field(default=None, description="Filter by thread status")
-
-
-class ThreadStateResponse(BaseModel):
-    """Response model for thread state."""
-
-    values: dict[str, Any] = Field(default_factory=dict, description="Current channel values")
-    next: list[str] = Field(default_factory=list, description="Next tasks to execute")
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Checkpoint metadata")
-    checkpoint: dict[str, Any] = Field(default_factory=dict, description="Checkpoint info")
-    checkpoint_id: str | None = Field(default=None, description="Current checkpoint ID")
-    parent_checkpoint_id: str | None = Field(default=None, description="Parent checkpoint ID")
-    created_at: str | None = Field(default=None, description="Checkpoint timestamp")
-    tasks: list[dict[str, Any]] = Field(default_factory=list, description="Interrupted task details")
-
-
-class ThreadPatchRequest(BaseModel):
-    """Request body for patching thread metadata."""
-
-    metadata: dict[str, Any] = Field(default_factory=dict, description="Metadata to merge")
-
-
-class ThreadStateUpdateRequest(BaseModel):
-    """Request body for updating thread state (human-in-the-loop resume)."""
-
-    values: dict[str, Any] | None = Field(default=None, description="Channel values to merge")
-    checkpoint_id: str | None = Field(default=None, description="Checkpoint to branch from")
-    checkpoint: dict[str, Any] | None = Field(default=None, description="Full checkpoint object")
-    as_node: str | None = Field(default=None, description="Node identity for the update")
-
-
-class HistoryEntry(BaseModel):
-    """Single checkpoint history entry."""
-
-    checkpoint_id: str
-    parent_checkpoint_id: str | None = None
-    metadata: dict[str, Any] = Field(default_factory=dict)
-    values: dict[str, Any] = Field(default_factory=dict)
-    created_at: str | None = None
-    next: list[str] = Field(default_factory=list)
-
-
-class ThreadHistoryRequest(BaseModel):
-    """Request body for checkpoint history."""
-
-    limit: int = Field(default=10, ge=1, le=100, description="Maximum entries")
-    before: str | None = Field(default=None, description="Cursor for pagination")
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-
-def _delete_thread_data(thread_id: str, paths: Paths | None = None) -> ThreadDeleteResponse:
-    """Delete local persisted filesystem data for a thread."""
-    path_manager = paths or get_paths()
-    try:
-        path_manager.delete_thread_dir(thread_id)
-    except ValueError as exc:
-        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)
-        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)
-        raise HTTPException(status_code=500, detail="Failed to delete local thread data.") from exc
-
-    logger.info("Deleted local thread data for %s", 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:
-        return "idle"
-    pending_writes = getattr(checkpoint_tuple, "pending_writes", None) or []
-
-    # Check for error in pending writes
-    for pw in pending_writes:
-        if len(pw) >= 2 and pw[1] == "__error__":
-            return "error"
-
-    # Check for pending next tasks (indicates interrupt)
-    tasks = getattr(checkpoint_tuple, "tasks", None)
-    if tasks:
-        return "interrupted"
-
-    return "idle"
-
-
-# ---------------------------------------------------------------------------
-# Endpoints
-# ---------------------------------------------------------------------------
-
-
-@router.delete("/{thread_id}", response_model=ThreadDeleteResponse)
-async def delete_thread_data(thread_id: str, request: Request) -> ThreadDeleteResponse:
-    """Delete local persisted filesystem data for a thread.
-
-    Cleans DeerFlow-managed thread directories, removes checkpoint data,
-    and removes the thread record from the Store.
-    """
-    # 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:
-        try:
-            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)
-
-    return response
-
-
-@router.post("", response_model=ThreadResponse)
-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).
-    Idempotent: returns the existing record when ``thread_id`` already exists.
-    """
-    store = get_store(request)
-    checkpointer = get_checkpointer(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", {}),
-            )
-
-    # 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 an empty checkpoint so state endpoints work immediately
-    config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
-    try:
-        from langgraph.checkpoint.base import empty_checkpoint
-
-        ckpt_metadata = {
-            "step": -1,
-            "source": "input",
-            "writes": None,
-            "parents": {},
-            **body.metadata,
-            "created_at": now,
-        }
-        await checkpointer.aput(config, empty_checkpoint(), ckpt_metadata, {})
-    except Exception:
-        logger.exception("Failed to create checkpoint for thread %s", thread_id)
-        raise HTTPException(status_code=500, detail="Failed to create thread")
-
-    logger.info("Thread created: %s", thread_id)
-    return ThreadResponse(
-        thread_id=thread_id,
-        status="idle",
-        created_at=str(now),
-        updated_at=str(now),
-        metadata=body.metadata,
-    )
-
-
-@router.post("/search", response_model=list[ThreadResponse])
-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.
-    """
-    store = get_store(request)
-    checkpointer = get_checkpointer(request)
-
-    # -----------------------------------------------------------------------
-    # 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]
-
-
-@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")
-
-    record = await _store_get(store, 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)
-    except Exception:
-        logger.exception("Failed to patch thread %s", thread_id)
-        raise HTTPException(status_code=500, detail="Failed to update thread")
-
-    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", {}),
-    )
-
-
-@router.get("/{thread_id}", response_model=ThreadResponse)
-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).
-    """
-    store = get_store(request)
-    checkpointer = get_checkpointer(request)
-
-    record: dict | None = None
-    if store is not None:
-        record = await _store_get(store, 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)
-        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 record is None and checkpoint_tuple is not None:
-        ckpt_meta = getattr(checkpoint_tuple, "metadata", {}) or {}
-        record = {
-            "thread_id": thread_id,
-            "status": "idle",
-            "created_at": ckpt_meta.get("created_at", ""),
-            "updated_at": ckpt_meta.get("updated_at", ckpt_meta.get("created_at", "")),
-            "metadata": {k: v for k, v in ckpt_meta.items() if k not in ("created_at", "updated_at", "step", "source", "writes", "parents")},
-        }
-
-    status = _derive_thread_status(checkpoint_tuple) if checkpoint_tuple is not None else record.get("status", "idle")  # type: ignore[union-attr]
-    checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {} if checkpoint_tuple is not None else {}
-    channel_values = checkpoint.get("channel_values", {})
-
-    return ThreadResponse(
-        thread_id=thread_id,
-        status=status,
-        created_at=str(record.get("created_at", "")),  # type: ignore[union-attr]
-        updated_at=str(record.get("updated_at", "")),  # type: ignore[union-attr]
-        metadata=record.get("metadata", {}),  # type: ignore[union-attr]
-        values=serialize_channel_values(channel_values),
-    )
-
-
-@router.get("/{thread_id}/state", response_model=ThreadStateResponse)
-async def get_thread_state(thread_id: str, request: Request) -> ThreadStateResponse:
-    """Get the latest state snapshot for a thread.
-
-    Channel values are serialized to ensure LangChain message objects
-    are converted to JSON-safe dicts.
-    """
-    checkpointer = get_checkpointer(request)
-
-    config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
-    try:
-        checkpoint_tuple = await checkpointer.aget_tuple(config)
-    except Exception:
-        logger.exception("Failed to get state for thread %s", thread_id)
-        raise HTTPException(status_code=500, detail="Failed to get thread state")
-
-    if checkpoint_tuple is None:
-        raise HTTPException(status_code=404, detail=f"Thread {thread_id} not found")
-
-    checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
-    metadata = getattr(checkpoint_tuple, "metadata", {}) or {}
-    checkpoint_id = None
-    ckpt_config = getattr(checkpoint_tuple, "config", {})
-    if ckpt_config:
-        checkpoint_id = ckpt_config.get("configurable", {}).get("checkpoint_id")
-
-    channel_values = checkpoint.get("channel_values", {})
-
-    parent_config = getattr(checkpoint_tuple, "parent_config", None)
-    parent_checkpoint_id = None
-    if parent_config:
-        parent_checkpoint_id = parent_config.get("configurable", {}).get("checkpoint_id")
-
-    tasks_raw = getattr(checkpoint_tuple, "tasks", []) or []
-    next_tasks = [t.name for t in tasks_raw if hasattr(t, "name")]
-    tasks = [{"id": getattr(t, "id", ""), "name": getattr(t, "name", "")} for t in tasks_raw]
-
-    return ThreadStateResponse(
-        values=serialize_channel_values(channel_values),
-        next=next_tasks,
-        metadata=metadata,
-        checkpoint={"id": checkpoint_id, "ts": str(metadata.get("created_at", ""))},
-        checkpoint_id=checkpoint_id,
-        parent_checkpoint_id=parent_checkpoint_id,
-        created_at=str(metadata.get("created_at", "")),
-        tasks=tasks,
-    )
-
-
-@router.post("/{thread_id}/state", response_model=ThreadStateResponse)
-async def update_thread_state(thread_id: str, body: ThreadStateUpdateRequest, request: Request) -> ThreadStateResponse:
-    """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.
-    """
-    checkpointer = get_checkpointer(request)
-    store = get_store(request)
-
-    # checkpoint_ns must be present in the config for aput — default to ""
-    # (the root graph namespace).  checkpoint_id is optional; omitting it
-    # fetches the latest checkpoint for the thread.
-    read_config: dict[str, Any] = {
-        "configurable": {
-            "thread_id": thread_id,
-            "checkpoint_ns": "",
-        }
-    }
-    if body.checkpoint_id:
-        read_config["configurable"]["checkpoint_id"] = body.checkpoint_id
-
-    try:
-        checkpoint_tuple = await checkpointer.aget_tuple(read_config)
-    except Exception:
-        logger.exception("Failed to get state for thread %s", thread_id)
-        raise HTTPException(status_code=500, detail="Failed to get thread state")
-
-    if checkpoint_tuple is None:
-        raise HTTPException(status_code=404, detail=f"Thread {thread_id} not found")
-
-    # Work on mutable copies so we don't accidentally mutate cached objects.
-    checkpoint: dict[str, Any] = dict(getattr(checkpoint_tuple, "checkpoint", {}) or {})
-    metadata: dict[str, Any] = dict(getattr(checkpoint_tuple, "metadata", {}) or {})
-    channel_values: dict[str, Any] = dict(checkpoint.get("channel_values", {}))
-
-    if body.values:
-        channel_values.update(body.values)
-
-    checkpoint["channel_values"] = channel_values
-    metadata["updated_at"] = time.time()
-
-    if body.as_node:
-        metadata["source"] = "update"
-        metadata["step"] = metadata.get("step", 0) + 1
-        metadata["writes"] = {body.as_node: body.values}
-
-    # aput requires checkpoint_ns in the config — use the same config used for the
-    # read (which always includes checkpoint_ns="").  Do NOT include checkpoint_id
-    # so that aput generates a fresh checkpoint ID for the new snapshot.
-    write_config: dict[str, Any] = {
-        "configurable": {
-            "thread_id": thread_id,
-            "checkpoint_ns": "",
-        }
-    }
-    try:
-        new_config = await checkpointer.aput(write_config, checkpoint, metadata, {})
-    except Exception:
-        logger.exception("Failed to update state for thread %s", 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)
-
-    return ThreadStateResponse(
-        values=serialize_channel_values(channel_values),
-        next=[],
-        metadata=metadata,
-        checkpoint_id=new_checkpoint_id,
-        created_at=str(metadata.get("created_at", "")),
-    )
-
-
-@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."""
-    checkpointer = get_checkpointer(request)
-
-    config: dict[str, Any] = {"configurable": {"thread_id": thread_id}}
-    if body.before:
-        config["configurable"]["checkpoint_id"] = body.before
-
-    entries: list[HistoryEntry] = []
-    try:
-        async for checkpoint_tuple in checkpointer.alist(config, limit=body.limit):
-            ckpt_config = getattr(checkpoint_tuple, "config", {})
-            parent_config = getattr(checkpoint_tuple, "parent_config", None)
-            metadata = getattr(checkpoint_tuple, "metadata", {}) or {}
-            checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
-
-            checkpoint_id = ckpt_config.get("configurable", {}).get("checkpoint_id", "")
-            parent_id = None
-            if parent_config:
-                parent_id = parent_config.get("configurable", {}).get("checkpoint_id")
-
-            channel_values = checkpoint.get("channel_values", {})
-
-            # Derive next tasks
-            tasks_raw = getattr(checkpoint_tuple, "tasks", []) or []
-            next_tasks = [t.name for t in tasks_raw if hasattr(t, "name")]
-
-            entries.append(
-                HistoryEntry(
-                    checkpoint_id=checkpoint_id,
-                    parent_checkpoint_id=parent_id,
-                    metadata=metadata,
-                    values=serialize_channel_values(channel_values),
-                    created_at=str(metadata.get("created_at", "")),
-                    next=next_tasks,
-                )
-            )
-    except Exception:
-        logger.exception("Failed to get history for thread %s", thread_id)
-        raise HTTPException(status_code=500, detail="Failed to get thread history")
-
-    return entries

backend/app/gateway/routers/uploads.py

@@ -1,168 +0,0 @@
-"""Upload router for handling file uploads."""
-
-import logging
-import os
-import stat
-
-from fastapi import APIRouter, File, HTTPException, UploadFile
-from pydantic import BaseModel
-
-from deerflow.config.paths import get_paths
-from deerflow.sandbox.sandbox_provider import get_sandbox_provider
-from deerflow.uploads.manager import (
-    PathTraversalError,
-    delete_file_safe,
-    enrich_file_listing,
-    ensure_uploads_dir,
-    get_uploads_dir,
-    list_files_in_dir,
-    normalize_filename,
-    upload_artifact_url,
-    upload_virtual_path,
-)
-from deerflow.utils.file_conversion import CONVERTIBLE_EXTENSIONS, convert_file_to_markdown
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(prefix="/api/threads/{thread_id}/uploads", tags=["uploads"])
-
-
-class UploadResponse(BaseModel):
-    """Response model for file upload."""
-
-    success: bool
-    files: list[dict[str, str]]
-    message: str
-
-
-def _make_file_sandbox_writable(file_path: os.PathLike[str] | str) -> None:
-    """Ensure uploaded files remain writable when mounted into non-local sandboxes.
-
-    In AIO sandbox mode, the gateway writes the authoritative host-side file
-    first, then the sandbox runtime may rewrite the same mounted path. Granting
-    world-writable access here prevents permission mismatches between the
-    gateway user and the sandbox runtime user.
-    """
-    file_stat = os.lstat(file_path)
-    if stat.S_ISLNK(file_stat.st_mode):
-        logger.warning("Skipping sandbox chmod for symlinked upload path: %s", file_path)
-        return
-
-    writable_mode = stat.S_IMODE(file_stat.st_mode) | stat.S_IWUSR | stat.S_IWGRP | stat.S_IWOTH
-    chmod_kwargs = {"follow_symlinks": False} if os.chmod in os.supports_follow_symlinks else {}
-    os.chmod(file_path, writable_mode, **chmod_kwargs)
-
-
-@router.post("", response_model=UploadResponse)
-async def upload_files(
-    thread_id: str,
-    files: list[UploadFile] = File(...),
-) -> UploadResponse:
-    """Upload multiple files to a thread's uploads directory."""
-    if not files:
-        raise HTTPException(status_code=400, detail="No files provided")
-
-    try:
-        uploads_dir = ensure_uploads_dir(thread_id)
-    except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))
-    sandbox_uploads = get_paths().sandbox_uploads_dir(thread_id)
-    uploaded_files = []
-
-    sandbox_provider = get_sandbox_provider()
-    sandbox_id = sandbox_provider.acquire(thread_id)
-    sandbox = sandbox_provider.get(sandbox_id)
-
-    for file in files:
-        if not file.filename:
-            continue
-
-        try:
-            safe_filename = normalize_filename(file.filename)
-        except ValueError:
-            logger.warning(f"Skipping file with unsafe filename: {file.filename!r}")
-            continue
-
-        try:
-            content = await file.read()
-            file_path = uploads_dir / safe_filename
-            file_path.write_bytes(content)
-
-            virtual_path = upload_virtual_path(safe_filename)
-
-            if sandbox_id != "local":
-                _make_file_sandbox_writable(file_path)
-                sandbox.update_file(virtual_path, content)
-
-            file_info = {
-                "filename": safe_filename,
-                "size": str(len(content)),
-                "path": str(sandbox_uploads / safe_filename),
-                "virtual_path": virtual_path,
-                "artifact_url": upload_artifact_url(thread_id, safe_filename),
-            }
-
-            logger.info(f"Saved file: {safe_filename} ({len(content)} bytes) to {file_info['path']}")
-
-            file_ext = file_path.suffix.lower()
-            if file_ext in CONVERTIBLE_EXTENSIONS:
-                md_path = await convert_file_to_markdown(file_path)
-                if md_path:
-                    md_virtual_path = upload_virtual_path(md_path.name)
-
-                    if sandbox_id != "local":
-                        _make_file_sandbox_writable(md_path)
-                        sandbox.update_file(md_virtual_path, md_path.read_bytes())
-
-                    file_info["markdown_file"] = md_path.name
-                    file_info["markdown_path"] = str(sandbox_uploads / md_path.name)
-                    file_info["markdown_virtual_path"] = md_virtual_path
-                    file_info["markdown_artifact_url"] = upload_artifact_url(thread_id, md_path.name)
-
-            uploaded_files.append(file_info)
-
-        except Exception as e:
-            logger.error(f"Failed to upload {file.filename}: {e}")
-            raise HTTPException(status_code=500, detail=f"Failed to upload {file.filename}: {str(e)}")
-
-    return UploadResponse(
-        success=True,
-        files=uploaded_files,
-        message=f"Successfully uploaded {len(uploaded_files)} file(s)",
-    )
-
-
-@router.get("/list", response_model=dict)
-async def list_uploaded_files(thread_id: str) -> dict:
-    """List all files in a thread's uploads directory."""
-    try:
-        uploads_dir = get_uploads_dir(thread_id)
-    except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))
-    result = list_files_in_dir(uploads_dir)
-    enrich_file_listing(result, thread_id)
-
-    # Gateway additionally includes the sandbox-relative path.
-    sandbox_uploads = get_paths().sandbox_uploads_dir(thread_id)
-    for f in result["files"]:
-        f["path"] = str(sandbox_uploads / f["filename"])
-
-    return result
-
-
-@router.delete("/{filename}")
-async def delete_uploaded_file(thread_id: str, filename: str) -> dict:
-    """Delete a file from a thread's uploads directory."""
-    try:
-        uploads_dir = get_uploads_dir(thread_id)
-    except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))
-    try:
-        return delete_file_safe(uploads_dir, filename, convertible_extensions=CONVERTIBLE_EXTENSIONS)
-    except FileNotFoundError:
-        raise HTTPException(status_code=404, detail=f"File not found: {filename}")
-    except PathTraversalError:
-        raise HTTPException(status_code=400, detail="Invalid path")
-    except Exception as e:
-        logger.error(f"Failed to delete {filename}: {e}")
-        raise HTTPException(status_code=500, detail=f"Failed to delete {filename}: {str(e)}")

backend/app/gateway/services.py

@@ -1,354 +0,0 @@
-"""Run lifecycle service layer.
-
-Centralizes the business logic for creating runs, formatting SSE
-frames, and consuming stream bridge events.  Router modules
-(``thread_runs``, ``runs``) are thin HTTP handlers that delegate here.
-"""
-
-from __future__ import annotations
-
-import asyncio
-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 deerflow.runtime import (
-    END_SENTINEL,
-    HEARTBEAT_SENTINEL,
-    ConflictError,
-    DisconnectMode,
-    RunManager,
-    RunRecord,
-    RunStatus,
-    StreamBridge,
-    UnsupportedStrategyError,
-    run_agent,
-)
-
-logger = logging.getLogger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# SSE formatting
-# ---------------------------------------------------------------------------
-
-
-def format_sse(event: str, data: Any, *, event_id: str | None = None) -> str:
-    """Format a single SSE frame.
-
-    Field order: ``event:`` -> ``data:`` -> ``id:`` (optional) -> blank line.
-    This matches the LangGraph Platform wire format consumed by the
-    ``useStream`` React hook and the Python ``langgraph-sdk`` SSE decoder.
-    """
-    payload = json.dumps(data, default=str, ensure_ascii=False)
-    parts = [f"event: {event}", f"data: {payload}"]
-    if event_id:
-        parts.append(f"id: {event_id}")
-    parts.append("")
-    parts.append("")
-    return "\n".join(parts)
-
-
-# ---------------------------------------------------------------------------
-# Input / config helpers
-# ---------------------------------------------------------------------------
-
-
-def normalize_stream_modes(raw: list[str] | str | None) -> list[str]:
-    """Normalize the stream_mode parameter to a list.
-
-    Default matches what ``useStream`` expects: values + messages-tuple.
-    """
-    if raw is None:
-        return ["values"]
-    if isinstance(raw, str):
-        return [raw]
-    return raw if raw else ["values"]
-
-
-def normalize_input(raw_input: dict[str, Any] | None) -> dict[str, Any]:
-    """Convert LangGraph Platform input format to LangChain state dict."""
-    if raw_input is None:
-        return {}
-    messages = raw_input.get("messages")
-    if messages and isinstance(messages, list):
-        converted = []
-        for msg in messages:
-            if isinstance(msg, dict):
-                role = msg.get("role", msg.get("type", "user"))
-                content = msg.get("content", "")
-                if role in ("user", "human"):
-                    converted.append(HumanMessage(content=content))
-                else:
-                    # TODO: handle other message types (system, ai, tool)
-                    converted.append(HumanMessage(content=content))
-            else:
-                converted.append(msg)
-        return {**raw_input, "messages": converted}
-    return raw_input
-
-
-_DEFAULT_ASSISTANT_ID = "lead_agent"
-
-
-def resolve_agent_factory(assistant_id: str | None):
-    """Resolve the agent factory callable from config.
-
-    Custom agents are implemented as ``lead_agent`` + an ``agent_name``
-    injected into ``configurable`` — see :func:`build_run_config`.  All
-    ``assistant_id`` values therefore map to the same factory; the routing
-    happens inside ``make_lead_agent`` when it reads ``cfg["agent_name"]``.
-    """
-    from deerflow.agents.lead_agent.agent import make_lead_agent
-
-    return make_lead_agent
-
-
-def build_run_config(
-    thread_id: str,
-    request_config: dict[str, Any] | None,
-    metadata: dict[str, Any] | None,
-    *,
-    assistant_id: str | None = None,
-) -> dict[str, Any]:
-    """Build a RunnableConfig dict for the agent.
-
-    When *assistant_id* refers to a custom agent (anything other than
-    ``"lead_agent"`` / ``None``), the name is forwarded as
-    ``configurable["agent_name"]``.  ``make_lead_agent`` reads this key to
-    load the matching ``agents/<name>/SOUL.md`` and per-agent config —
-    without it the agent silently runs as the default lead agent.
-
-    This mirrors the channel manager's ``_resolve_run_params`` logic so that
-    the LangGraph Platform-compatible HTTP API and the IM channel path behave
-    identically.
-    """
-    configurable: dict[str, Any] = {"thread_id": thread_id}
-    if request_config:
-        configurable.update(request_config.get("configurable", {}))
-
-    # Inject custom agent name when the caller specified a non-default assistant.
-    # Honour an explicit configurable["agent_name"] in the request if already set.
-    if assistant_id and assistant_id != _DEFAULT_ASSISTANT_ID and "agent_name" not in configurable:
-        # Normalize the same way ChannelManager does: strip, lowercase,
-        # replace underscores with hyphens, then validate to prevent path
-        # traversal and invalid agent directory lookups.
-        normalized = assistant_id.strip().lower().replace("_", "-")
-        if not normalized or not re.fullmatch(r"[a-z0-9-]+", normalized):
-            raise ValueError(f"Invalid assistant_id {assistant_id!r}: must contain only letters, digits, and hyphens after normalization.")
-        configurable["agent_name"] = normalized
-
-    config: dict[str, Any] = {"configurable": configurable, "recursion_limit": 100}
-    if request_config:
-        for k, v in request_config.items():
-            if k != "configurable":
-                config[k] = v
-    if metadata:
-        config.setdefault("metadata", {}).update(metadata)
-    return config
-
-
-# ---------------------------------------------------------------------------
-# Run lifecycle
-# ---------------------------------------------------------------------------
-
-
-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,
-    request: Request,
-) -> RunRecord:
-    """Create a RunRecord and launch the background agent task.
-
-    Parameters
-    ----------
-    body : RunCreateRequest
-        The validated request body (typed as Any to avoid circular import
-        with the router module that defines the Pydantic model).
-    thread_id : str
-        Target thread.
-    request : Request
-        FastAPI request — used to retrieve singletons from ``app.state``.
-    """
-    bridge = get_stream_bridge(request)
-    run_mgr = get_run_manager(request)
-    checkpointer = get_checkpointer(request)
-    store = get_store(request)
-
-    disconnect = DisconnectMode.cancel if body.on_disconnect == "cancel" else DisconnectMode.continue_
-
-    try:
-        record = await run_mgr.create_or_reject(
-            thread_id,
-            body.assistant_id,
-            on_disconnect=disconnect,
-            metadata=body.metadata or {},
-            kwargs={"input": body.input, "config": body.config},
-            multitask_strategy=body.multitask_strategy,
-        )
-    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)
-
-    agent_factory = resolve_agent_factory(body.assistant_id)
-    graph_input = normalize_input(body.input)
-    config = build_run_config(thread_id, body.config, body.metadata, assistant_id=body.assistant_id)
-
-    # Merge DeerFlow-specific context overrides into configurable.
-    # The ``context`` field is a custom extension for the langgraph-compat layer
-    # that carries agent configuration (model_name, thinking_enabled, etc.).
-    # Only agent-relevant keys are forwarded; unknown keys (e.g. thread_id) are ignored.
-    context = getattr(body, "context", None)
-    if context:
-        _CONTEXT_CONFIGURABLE_KEYS = {
-            "model_name",
-            "mode",
-            "thinking_enabled",
-            "reasoning_effort",
-            "is_plan_mode",
-            "subagent_enabled",
-            "max_concurrent_subagents",
-        }
-        configurable = config.setdefault("configurable", {})
-        for key in _CONTEXT_CONFIGURABLE_KEYS:
-            if key in context:
-                configurable.setdefault(key, context[key])
-
-    stream_modes = normalize_stream_modes(body.stream_mode)
-
-    task = asyncio.create_task(
-        run_agent(
-            bridge,
-            run_mgr,
-            record,
-            checkpointer=checkpointer,
-            store=store,
-            agent_factory=agent_factory,
-            graph_input=graph_input,
-            config=config,
-            stream_modes=stream_modes,
-            stream_subgraphs=body.stream_subgraphs,
-            interrupt_before=body.interrupt_before,
-            interrupt_after=body.interrupt_after,
-        )
-    )
-    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))
-
-    return record
-
-
-async def sse_consumer(
-    bridge: StreamBridge,
-    record: RunRecord,
-    request: Request,
-    run_mgr: RunManager,
-):
-    """Async generator that yields SSE frames from the bridge.
-
-    The ``finally`` block implements ``on_disconnect`` semantics:
-    - ``cancel``: abort the background task on client disconnect.
-    - ``continue``: let the task run; events are discarded.
-    """
-    try:
-        async for entry in bridge.subscribe(record.run_id):
-            if await request.is_disconnected():
-                break
-
-            if entry is HEARTBEAT_SENTINEL:
-                yield ": heartbeat\n\n"
-                continue
-
-            if entry is END_SENTINEL:
-                yield format_sse("end", None, event_id=entry.id or None)
-                return
-
-            yield format_sse(entry.event, entry.data, event_id=entry.id or None)
-
-    finally:
-        if record.status in (RunStatus.pending, RunStatus.running):
-            if record.on_disconnect == DisconnectMode.cancel:
-                await run_mgr.cancel(record.run_id)

backend/debug.py

@@ -3,12 +3,6 @@
 Debug script for lead_agent.
 Run this file directly in VS Code with breakpoints.
 
-Requirements:
-    Run with `uv run` from the backend/ directory so that the uv workspace
-    resolves deerflow-harness and app packages correctly:
-
-        cd backend && PYTHONPATH=. uv run python debug.py
-
 Usage:
     1. Set breakpoints in agent.py or other files
     2. Press F5 or use "Run and Debug" panel
@@ -17,14 +11,21 @@ Usage:
 
 import asyncio
 import logging
+import os
+import sys
 
+# Ensure we can import from src
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+# Load environment variables
 from dotenv import load_dotenv
 from langchain_core.messages import HumanMessage
 
-from deerflow.agents import make_lead_agent
+from src.agents import make_lead_agent
 
 load_dotenv()
 
+# Configure logging
 logging.basicConfig(
     level=logging.INFO,
     format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
@@ -35,7 +36,7 @@ logging.basicConfig(
 async def main():
     # Initialize MCP tools at startup
     try:
-        from deerflow.mcp import initialize_mcp_tools
+        from src.mcp import initialize_mcp_tools
 
         await initialize_mcp_tools()
     except Exception as e:

backend/docs/API.md

@@ -92,14 +92,10 @@ Content-Type: application/json
       "is_plan_mode": false
     }
   },
-  "stream_mode": ["values", "messages-tuple", "custom"]
+  "stream_mode": ["values", "messages"]
 }
 ```
 
-**Stream Mode Compatibility:**
-- 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)
-
 **Configurable Options:**
 - `model_name` (string): Override the default model
 - `thinking_enabled` (boolean): Enable extended thinking for supported models
@@ -464,26 +460,6 @@ DELETE /api/threads/{thread_id}/uploads/{filename}
 }
 ```
 
-### Thread Cleanup
-
-Remove DeerFlow-managed local thread files under `.deer-flow/threads/{thread_id}` after the LangGraph thread itself has been deleted.
-
-```http
-DELETE /api/threads/{thread_id}
-```
-
-**Response:**
-```json
-{
-  "success": true,
-  "message": "Deleted local thread data for abc123"
-}
-```
-
-**Error behavior:**
-- `422` for invalid thread IDs
-- `500` returns a generic `{"detail": "Failed to delete local thread data."}` response while full exception details stay in server logs
-
 ### Artifacts
 
 #### Get Artifact
@@ -579,7 +555,7 @@ async for event in client.runs.stream(
     "lead_agent",
     input={"messages": [{"role": "user", "content": "Hello"}]},
     config={"configurable": {"model_name": "gpt-4"}},
-    stream_mode=["values", "messages-tuple", "custom"],
+    stream_mode=["values", "messages"],
 ):
     print(event)
 ```

backend/docs/APPLE_CONTAINER.md

@@ -80,7 +80,7 @@ docker stop <id>     # Auto-removes due to --rm
 
 ### Implementation Details
 
-The implementation is in `backend/packages/harness/deerflow/community/aio_sandbox/aio_sandbox_provider.py`:
+The implementation is in `backend/src/community/aio_sandbox/aio_sandbox_provider.py`:
 
 - `_detect_container_runtime()`: Detects available runtime at startup
 - `_start_container()`: Uses detected runtime, skips Docker-specific options for Apple Container
@@ -93,14 +93,14 @@ No configuration changes are needed! The system works automatically.
 However, you can verify the runtime in use by checking the logs:
 
 ```
-INFO:deerflow.community.aio_sandbox.aio_sandbox_provider:Detected Apple Container: container version 0.1.0
-INFO:deerflow.community.aio_sandbox.aio_sandbox_provider:Starting sandbox container using container: ...
+INFO:src.community.aio_sandbox.aio_sandbox_provider:Detected Apple Container: container version 0.1.0
+INFO:src.community.aio_sandbox.aio_sandbox_provider:Starting sandbox container using container: ...
 ```
 
 Or for Docker:
 ```
-INFO:deerflow.community.aio_sandbox.aio_sandbox_provider:Apple Container not available, falling back to Docker
-INFO:deerflow.community.aio_sandbox.aio_sandbox_provider:Starting sandbox container using docker: ...
+INFO:src.community.aio_sandbox.aio_sandbox_provider:Apple Container not available, falling back to Docker
+INFO:src.community.aio_sandbox.aio_sandbox_provider:Starting sandbox container using docker: ...
 ```
 
 ## Container Images
@@ -109,7 +109,7 @@ Both runtimes use OCI-compatible images. The default image works with both:
 
 ```yaml
 sandbox:
-  use: deerflow.community.aio_sandbox:AioSandboxProvider
+  use: src.community.aio_sandbox:AioSandboxProvider
   image: enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest  # Default image
 ```
 
@@ -139,7 +139,7 @@ This command will:
 
 ```bash
 # Using Apple Container
-container image pull enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
+container pull enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
 
 # Using Docker
 docker pull enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

backend/docs/ARCHITECTURE.md

@@ -31,7 +31,6 @@ This document provides a comprehensive overview of the DeerFlow backend architec
 │  - Thread Mgmt      │ │  - MCP Config       │ │  - React UI         │
 │  - SSE Streaming    │ │  - Skills Mgmt      │ │  - Chat Interface   │
 │  - Checkpointing    │ │  - File Uploads     │ │                     │
-│                     │ │  - Thread Cleanup   │ │                     │
 │                     │ │  - Artifacts        │ │                     │
 └─────────────────────┘ └─────────────────────┘ └─────────────────────┘
           │                       │
@@ -56,7 +55,7 @@ This document provides a comprehensive overview of the DeerFlow backend architec
 
 The LangGraph server is the core agent runtime, built on LangGraph for robust multi-agent workflow orchestration.
 
-**Entry Point**: `packages/harness/deerflow/agents/lead_agent/agent.py:make_lead_agent`
+**Entry Point**: `src/agents/lead_agent/agent.py:make_lead_agent`
 
 **Key Responsibilities**:
 - Agent creation and configuration
@@ -71,7 +70,7 @@ The LangGraph server is the core agent runtime, built on LangGraph for robust mu
 {
   "agent": {
     "type": "agent",
-    "path": "deerflow.agents:make_lead_agent"
+    "path": "src.agents:make_lead_agent"
   }
 }
 ```
@@ -80,18 +79,14 @@ The LangGraph server is the core agent runtime, built on LangGraph for robust mu
 
 FastAPI application providing REST endpoints for non-agent operations.
 
-**Entry Point**: `app/gateway/app.py`
+**Entry Point**: `src/gateway/app.py`
 
 **Routers**:
 - `models.py` - `/api/models` - Model listing and details
 - `mcp.py` - `/api/mcp` - MCP server configuration
 - `skills.py` - `/api/skills` - Skills management
 - `uploads.py` - `/api/threads/{id}/uploads` - File upload
-- `threads.py` - `/api/threads/{id}` - Local DeerFlow thread data cleanup after LangGraph deletion
 - `artifacts.py` - `/api/threads/{id}/artifacts` - Artifact serving
-- `suggestions.py` - `/api/threads/{id}/suggestions` - Follow-up suggestion generation
-
-The web conversation delete flow is now split across both backend surfaces: LangGraph handles `DELETE /api/langgraph/threads/{thread_id}` for thread state, then the Gateway `threads.py` router removes DeerFlow-managed filesystem data via `Paths.delete_thread_dir()`.
 
 ### Agent Architecture
 
@@ -163,7 +158,7 @@ class ThreadState(AgentState):
               ▼                                         ▼
 ┌─────────────────────────┐              ┌─────────────────────────┐
 │  LocalSandboxProvider   │              │  AioSandboxProvider     │
-│  (packages/harness/deerflow/sandbox/local.py) │              │  (packages/harness/deerflow/community/)       │
+│  (src/sandbox/local.py) │              │  (src/community/)       │
 │                         │              │                         │
 │  - Singleton instance   │              │  - Docker-based         │
 │  - Direct execution     │              │  - Isolated containers  │
@@ -197,7 +192,7 @@ class ThreadState(AgentState):
 
 ┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐
 │   Built-in Tools    │  │  Configured Tools   │  │     MCP Tools       │
-│  (packages/harness/deerflow/tools/)       │  │  (config.yaml)      │  │  (extensions.json)  │
+│  (src/tools/)       │  │  (config.yaml)      │  │  (extensions.json)  │
 ├─────────────────────┤  ├─────────────────────┤  ├─────────────────────┤
 │ - present_file      │  │ - web_search        │  │ - github            │
 │ - ask_clarification │  │ - web_fetch         │  │ - filesystem        │
@@ -213,7 +208,7 @@ class ThreadState(AgentState):
                                    ▼
                       ┌─────────────────────────┐
                       │   get_available_tools() │
-                      │   (packages/harness/deerflow/tools/__init__)  │
+                      │   (src/tools/__init__)  │
                       └─────────────────────────┘
 ```
 
@@ -222,7 +217,7 @@ class ThreadState(AgentState):
 ```
 ┌─────────────────────────────────────────────────────────────────────────┐
 │                          Model Factory                                   │
-│                     (packages/harness/deerflow/models/factory.py)                              │
+│                     (src/models/factory.py)                              │
 └─────────────────────────────────────────────────────────────────────────┘
 
 config.yaml:
@@ -269,7 +264,7 @@ config.yaml:
 ```
 ┌─────────────────────────────────────────────────────────────────────────┐
 │                          MCP Integration                                 │
-│                        (packages/harness/deerflow/mcp/manager.py)                              │
+│                        (src/mcp/manager.py)                              │
 └─────────────────────────────────────────────────────────────────────────┘
 
 extensions_config.json:
@@ -307,7 +302,7 @@ extensions_config.json:
 ```
 ┌─────────────────────────────────────────────────────────────────────────┐
 │                          Skills System                                   │
-│                       (packages/harness/deerflow/skills/loader.py)                             │
+│                       (src/skills/loader.py)                             │
 └─────────────────────────────────────────────────────────────────────────┘
 
 Directory Structure:
@@ -409,21 +404,6 @@ SKILL.md Format:
    - Agent can access via virtual_path
 ```
 
-### Thread Cleanup Flow
-
-```
-1. Client deletes conversation via LangGraph
-   DELETE /api/langgraph/threads/{thread_id}
-
-2. Web UI follows up with Gateway cleanup
-   DELETE /api/threads/{thread_id}
-
-3. Gateway removes local DeerFlow-managed files
-   - Deletes .deer-flow/threads/{thread_id}/ recursively
-   - Missing directories are treated as a no-op
-   - Invalid thread IDs are rejected before filesystem access
-```
-
 ### Configuration Reload
 
 ```

backend/docs/AUTO_TITLE_GENERATION.md

@@ -6,14 +6,12 @@
 
 ## 实现方式
 
-使用 `TitleMiddleware` 在 `after_model` 钩子中：
+使用 `TitleMiddleware` 在 `after_agent` 钩子中：
 1. 检测是否是首次对话（1个用户消息 + 1个助手回复）
 2. 检查 state 是否已有 title
 3. 调用 LLM 生成简洁的标题（默认最多6个词）
 4. 将 title 存储到 `ThreadState` 中（会被 checkpointer 持久化）
 
-TitleMiddleware 会先把 LangChain message content 里的结构化 block/list 内容归一化为纯文本，再拼到 title prompt 里，避免把 Python/JSON 的原始 repr 泄漏到标题生成模型。
-
 ## ⚠️ 重要：存储机制
 
 ### Title 存储位置
@@ -52,7 +50,7 @@ checkpointer = PostgresSaver.from_conn_string(
 ```json
 {
   "graphs": {
-    "lead_agent": "deerflow.agents:lead_agent"
+    "lead_agent": "src.agents:lead_agent"
   },
   "checkpointer": "checkpointer:checkpointer"
 }
@@ -73,7 +71,7 @@ title:
 或在代码中配置：
 
 ```python
-from deerflow.config.title_config import TitleConfig, set_title_config
+from src.config.title_config import TitleConfig, set_title_config
 
 set_title_config(TitleConfig(
     enabled=True,
@@ -187,7 +185,7 @@ sequenceDiagram
 ```python
 # 测试 title 生成
 import pytest
-from deerflow.agents.title_middleware import TitleMiddleware
+from src.agents.title_middleware import TitleMiddleware
 
 def test_title_generation():
     # TODO: 添加单元测试
@@ -245,11 +243,11 @@ def after_agent(self, state: TitleMiddlewareState, runtime: Runtime) -> dict | N
 
 ## 相关文件
 
-- [`packages/harness/deerflow/agents/thread_state.py`](../packages/harness/deerflow/agents/thread_state.py) - ThreadState 定义
-- [`packages/harness/deerflow/agents/middlewares/title_middleware.py`](../packages/harness/deerflow/agents/middlewares/title_middleware.py) - TitleMiddleware 实现
-- [`packages/harness/deerflow/config/title_config.py`](../packages/harness/deerflow/config/title_config.py) - 配置管理
+- [`src/agents/thread_state.py`](../src/agents/thread_state.py) - ThreadState 定义
+- [`src/agents/title_middleware.py`](../src/agents/title_middleware.py) - TitleMiddleware 实现
+- [`src/config/title_config.py`](../src/config/title_config.py) - 配置管理
 - [`config.yaml`](../config.yaml) - 配置文件
-- [`packages/harness/deerflow/agents/lead_agent/agent.py`](../packages/harness/deerflow/agents/lead_agent/agent.py) - Middleware 注册
+- [`src/agents/lead_agent/agent.py`](../src/agents/lead_agent/agent.py) - Middleware 注册
 
 ## 参考资料
 

backend/docs/CONFIGURATION.md

@@ -2,19 +2,6 @@
 
 This guide explains how to configure DeerFlow for your environment.
 
-## Config Versioning
-
-`config.example.yaml` contains a `config_version` field that tracks schema changes. When the example version is higher than your local `config.yaml`, the application emits a startup warning:
-
-```
-WARNING - Your config.yaml (version 0) is outdated — the latest version is 1.
-Run `make config-upgrade` to merge new fields into your config.
-```
-
-- **Missing `config_version`** in your config is treated as version 0.
-- Run `make config-upgrade` to auto-merge missing fields (your existing values are preserved, a `.bak` backup is created).
-- When changing the config schema, bump `config_version` in `config.example.yaml`.
-
 ## Configuration Sections
 
 ### Models
@@ -36,49 +23,9 @@ models:
 - OpenAI (`langchain_openai:ChatOpenAI`)
 - Anthropic (`langchain_anthropic:ChatAnthropic`)
 - DeepSeek (`langchain_deepseek:ChatDeepSeek`)
-- Claude Code OAuth (`deerflow.models.claude_provider:ClaudeChatModel`)
-- Codex CLI (`deerflow.models.openai_codex_provider:CodexChatModel`)
 - Any LangChain-compatible provider
 
-CLI-backed provider examples:
-
-```yaml
-models:
-  - name: gpt-5.4
-    display_name: GPT-5.4 (Codex CLI)
-    use: deerflow.models.openai_codex_provider:CodexChatModel
-    model: gpt-5.4
-    supports_thinking: true
-    supports_reasoning_effort: true
-
-  - name: claude-sonnet-4.6
-    display_name: Claude Sonnet 4.6 (Claude Code OAuth)
-    use: deerflow.models.claude_provider:ClaudeChatModel
-    model: claude-sonnet-4-6
-    max_tokens: 4096
-    supports_thinking: true
-```
-
-**Auth behavior for CLI-backed providers**:
-- `CodexChatModel` loads Codex CLI auth from `~/.codex/auth.json`
-- The Codex Responses endpoint currently rejects `max_tokens` and `max_output_tokens`, so `CodexChatModel` does not expose a request-level token cap
-- `ClaudeChatModel` accepts `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR`, `CLAUDE_CODE_CREDENTIALS_PATH`, or plaintext `~/.claude/.credentials.json`
-- On macOS, DeerFlow does not probe Keychain automatically. Use `scripts/export_claude_code_oauth.py` to export Claude Code auth explicitly when needed
-
-To use OpenAI's `/v1/responses` endpoint with LangChain, keep using `langchain_openai:ChatOpenAI` and set:
-
-```yaml
-models:
-  - name: gpt-5-responses
-    display_name: GPT-5 (Responses API)
-    use: langchain_openai:ChatOpenAI
-    model: gpt-5
-    api_key: $OPENAI_API_KEY
-    use_responses_api: true
-    output_version: responses/v1
-```
-
-For OpenAI-compatible gateways (for example Novita or OpenRouter), keep using `langchain_openai:ChatOpenAI` and set `base_url`:
+For OpenAI-compatible gateways (for example Novita), keep using `langchain_openai:ChatOpenAI` and set `base_url`:
 
 ```yaml
 models:
@@ -93,36 +40,8 @@ models:
       extra_body:
         thinking:
           type: enabled
-
-  - name: minimax-m2.5
-    display_name: MiniMax M2.5
-    use: langchain_openai:ChatOpenAI
-    model: MiniMax-M2.5
-    api_key: $MINIMAX_API_KEY
-    base_url: https://api.minimax.io/v1
-    max_tokens: 4096
-    temperature: 1.0  # MiniMax requires temperature in (0.0, 1.0]
-    supports_vision: true
-
-  - name: minimax-m2.5-highspeed
-    display_name: MiniMax M2.5 Highspeed
-    use: langchain_openai:ChatOpenAI
-    model: MiniMax-M2.5-highspeed
-    api_key: $MINIMAX_API_KEY
-    base_url: https://api.minimax.io/v1
-    max_tokens: 4096
-    temperature: 1.0  # MiniMax requires temperature in (0.0, 1.0]
-    supports_vision: true
-  - 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: $OPENAI_API_KEY
-    base_url: https://openrouter.ai/api/v1
 ```
 
-If your OpenRouter key lives in a different environment variable name, point `api_key` at that variable explicitly (for example `api_key: $OPENROUTER_API_KEY`).
-
 **Thinking Models**:
 Some models support "thinking" mode for complex reasoning:
 
@@ -136,36 +55,6 @@ models:
           type: enabled
 ```
 
-**Gemini with thinking via OpenAI-compatible gateway**:
-
-When routing Gemini through an OpenAI-compatible proxy (Vertex AI OpenAI compat endpoint, AI Studio, or third-party gateways) with thinking enabled, the API attaches a `thought_signature` to each tool-call object returned in the response.  Every subsequent request that replays those assistant messages **must** echo those signatures back on the tool-call entries or the API returns:
-
-```
-HTTP 400 INVALID_ARGUMENT: function call `<tool>` in the N. content block is
-missing a `thought_signature`.
-```
-
-Standard `langchain_openai:ChatOpenAI` silently drops `thought_signature` when serialising messages.  Use `deerflow.models.patched_openai:PatchedChatOpenAI` instead — it re-injects the tool-call signatures (sourced from `AIMessage.additional_kwargs["tool_calls"]`) into every outgoing payload:
-
-```yaml
-models:
-  - name: gemini-2.5-pro-thinking
-    display_name: Gemini 2.5 Pro (Thinking)
-    use: deerflow.models.patched_openai:PatchedChatOpenAI
-    model: google/gemini-2.5-pro-preview   # model name as expected by your gateway
-    api_key: $GEMINI_API_KEY
-    base_url: https://<your-openai-compat-gateway>/v1
-    max_tokens: 16384
-    supports_thinking: true
-    supports_vision: true
-    when_thinking_enabled:
-      extra_body:
-        thinking:
-          type: enabled
-```
-
-For Gemini accessed **without** thinking (e.g. via OpenRouter where thinking is not activated), the plain `langchain_openai:ChatOpenAI` with `supports_thinking: false` is sufficient and no patch is needed.
-
 ### Tool Groups
 
 Organize tools into logical groups:
@@ -186,7 +75,7 @@ Configure specific tools available to the agent:
 tools:
   - name: web_search
     group: web
-    use: deerflow.community.tavily.tools:web_search_tool
+    use: src.community.tavily.tools:web_search_tool
     max_results: 5
     # api_key: $TAVILY_API_KEY  # Optional
 ```
@@ -207,14 +96,13 @@ DeerFlow supports multiple sandbox execution modes. Configure your preferred mod
 **Local Execution** (runs sandbox code directly on the host machine):
 ```yaml
 sandbox:
-   use: deerflow.sandbox.local:LocalSandboxProvider # Local execution
-   allow_host_bash: false # default; host bash is disabled unless explicitly re-enabled
+   use: src.sandbox.local:LocalSandboxProvider # Local execution
 ```
 
 **Docker Execution** (runs sandbox code in isolated Docker containers):
 ```yaml
 sandbox:
-   use: deerflow.community.aio_sandbox:AioSandboxProvider # Docker-based sandbox
+   use: src.community.aio_sandbox:AioSandboxProvider # Docker-based sandbox
 ```
 
 **Docker Execution with Kubernetes** (runs sandbox code in Kubernetes pods via provisioner service):
@@ -223,29 +111,26 @@ This mode runs each sandbox in an isolated Kubernetes Pod on your **host machine
 
 ```yaml
 sandbox:
-   use: deerflow.community.aio_sandbox:AioSandboxProvider
+   use: src.community.aio_sandbox:AioSandboxProvider
    provisioner_url: http://provisioner:8002
 ```
 
 When using Docker development (`make docker-start`), DeerFlow starts the `provisioner` service only if this provisioner mode is configured. In local or plain Docker sandbox modes, `provisioner` is skipped.
 
-See [Provisioner Setup Guide](../../docker/provisioner/README.md) for detailed configuration, prerequisites, and troubleshooting.
+See [Provisioner Setup Guide](docker/provisioner/README.md) for detailed configuration, prerequisites, and troubleshooting.
 
 Choose between local execution or Docker-based isolation:
 
 **Option 1: Local Sandbox** (default, simpler setup):
 ```yaml
 sandbox:
-  use: deerflow.sandbox.local:LocalSandboxProvider
-  allow_host_bash: false
+  use: src.sandbox.local:LocalSandboxProvider
 ```
 
-`allow_host_bash` is intentionally `false` by default. DeerFlow's local sandbox is a host-side convenience mode, not a secure shell isolation boundary. If you need `bash`, prefer `AioSandboxProvider`. Only set `allow_host_bash: true` for fully trusted single-user local workflows.
-
 **Option 2: Docker Sandbox** (isolated, more secure):
 ```yaml
 sandbox:
-  use: deerflow.community.aio_sandbox:AioSandboxProvider
+  use: src.community.aio_sandbox:AioSandboxProvider
   port: 8080
   auto_start: true
   container_prefix: deer-flow-sandbox
@@ -257,8 +142,6 @@ sandbox:
       read_only: false
 ```
 
-When you configure `sandbox.mounts`, DeerFlow exposes those `container_path` values in the agent prompt so the agent can discover and operate on mounted directories directly instead of assuming everything must live under `/mnt/user-data`.
-
 ### Skills
 
 Configure the skills directory for specialized workflows:
@@ -290,14 +173,6 @@ title:
   model_name: null  # Use first model in list
 ```
 
-### GitHub API Token (Optional for GitHub Deep Research Skill)
-
-The default GitHub API rate limits are quite restrictive. For frequent project research, we recommend configuring a personal access token (PAT) with read-only permissions.
-
-**Configuration Steps**:
-1. Uncomment the `GITHUB_TOKEN` line in the `.env` file and add your personal access token
-2. Restart the DeerFlow service to apply changes
-
 ## Environment Variables
 
 DeerFlow supports environment variable substitution using the `$` prefix:

backend/docs/FILE_UPLOAD.md

@@ -212,11 +212,11 @@ backend/.deer-flow/threads/
 
 ### 组件
 
-1. **Upload Router** (`app/gateway/routers/uploads.py`)
+1. **Upload Router** (`src/gateway/routers/uploads.py`)
    - 处理文件上传、列表、删除请求
    - 使用 markitdown 转换文档
 
-2. **Uploads Middleware** (`packages/harness/deerflow/agents/middlewares/uploads_middleware.py`)
+2. **Uploads Middleware** (`src/agents/middlewares/uploads_middleware.py`)
    - 在每次 Agent 请求前注入文件列表
    - 自动生成格式化的文件列表消息
 

backend/docs/GUARDRAILS.md

@@ -1,385 +0,0 @@
-# Guardrails: Pre-Tool-Call Authorization
-
-> **Context:** [Issue #1213](https://github.com/bytedance/deer-flow/issues/1213) — DeerFlow has Docker sandboxing and human approval via `ask_clarification`, but no deterministic, policy-driven authorization layer for tool calls. An agent running autonomous multi-step tasks can execute any loaded tool with any arguments. Guardrails add a middleware that evaluates every tool call against a policy **before** execution.
-
-## Why Guardrails
-
-```
-Without guardrails:                      With guardrails:
-
-  Agent                                    Agent
-    │                                        │
-    ▼                                        ▼
-  ┌──────────┐                             ┌──────────┐
-  │ bash     │──▶ executes immediately     │ bash     │──▶ GuardrailMiddleware
-  │ rm -rf / │                             │ rm -rf / │        │
-  └──────────┘                             └──────────┘        ▼
-                                                         ┌──────────────┐
-                                                         │  Provider    │
-                                                         │  evaluates   │
-                                                         │  against     │
-                                                         │  policy      │
-                                                         └──────┬───────┘
-                                                                │
-                                                          ┌─────┴─────┐
-                                                          │           │
-                                                        ALLOW       DENY
-                                                          │           │
-                                                          ▼           ▼
-                                                      Tool runs   Agent sees:
-                                                      normally    "Guardrail denied:
-                                                                   rm -rf blocked"
-```
-
-- **Sandboxing** provides process isolation but not semantic authorization. A sandboxed `bash` can still `curl` data out.
-- **Human approval** (`ask_clarification`) requires a human in the loop for every action. Not viable for autonomous workflows.
-- **Guardrails** provide deterministic, policy-driven authorization that works without human intervention.
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                        Middleware Chain                               │
-│                                                                      │
-│  1. ThreadDataMiddleware     ─── per-thread dirs                     │
-│  2. UploadsMiddleware        ─── file upload tracking                │
-│  3. SandboxMiddleware        ─── sandbox acquisition                 │
-│  4. DanglingToolCallMiddleware ── fix incomplete tool calls           │
-│  5. GuardrailMiddleware ◄──── EVALUATES EVERY TOOL CALL             │
-│  6. ToolErrorHandlingMiddleware ── convert exceptions to messages     │
-│  7-12. (Summarization, Title, Memory, Vision, Subagent, Clarify)    │
-│                                                                      │
-└─────────────────────────────────────────────────────────────────────┘
-                         │
-                         ▼
-           ┌──────────────────────────┐
-           │    GuardrailProvider     │  ◄── pluggable: any class
-           │    (configured in YAML)  │      with evaluate/aevaluate
-           └────────────┬─────────────┘
-                        │
-              ┌─────────┼──────────────┐
-              │         │              │
-              ▼         ▼              ▼
-         Built-in   OAP Passport    Custom
-         Allowlist  Provider        Provider
-         (zero dep) (open standard) (your code)
-                        │
-                  Any implementation
-                  (e.g. APort, or
-                   your own evaluator)
-```
-
-The `GuardrailMiddleware` implements `wrap_tool_call` / `awrap_tool_call` (the same `AgentMiddleware` pattern used by `ToolErrorHandlingMiddleware`). It:
-
-1. Builds a `GuardrailRequest` with tool name, arguments, and passport reference
-2. Calls `provider.evaluate(request)` on whatever provider is configured
-3. If **deny**: returns `ToolMessage(status="error")` with the reason -- agent sees the denial and adapts
-4. If **allow**: passes through to the actual tool handler
-5. If **provider error** and `fail_closed=true` (default): blocks the call
-6. `GraphBubbleUp` exceptions (LangGraph control signals) are always propagated, never caught
-
-## Three Provider Options
-
-### Option 1: Built-in AllowlistProvider (Zero Dependencies)
-
-The simplest option. Ships with DeerFlow. Block or allow tools by name. No external packages, no passport, no network.
-
-**config.yaml:**
-```yaml
-guardrails:
-  enabled: true
-  provider:
-    use: deerflow.guardrails.builtin:AllowlistProvider
-    config:
-      denied_tools: ["bash", "write_file"]
-```
-
-This blocks `bash` and `write_file` for all requests. All other tools pass through.
-
-You can also use an allowlist (only these tools are permitted):
-```yaml
-guardrails:
-  enabled: true
-  provider:
-    use: deerflow.guardrails.builtin:AllowlistProvider
-    config:
-      allowed_tools: ["web_search", "read_file", "ls"]
-```
-
-**Try it:**
-1. Add the config above to your `config.yaml`
-2. Start DeerFlow: `make dev`
-3. Ask the agent: "Use bash to run echo hello"
-4. The agent sees: `Guardrail denied: tool 'bash' was blocked (oap.tool_not_allowed)`
-
-### Option 2: OAP Passport Provider (Policy-Based)
-
-For policy enforcement based on the [Open Agent Passport (OAP)](https://github.com/aporthq/aport-spec) open standard. An OAP passport is a JSON document that declares an agent's identity, capabilities, and operational limits. Any provider that reads an OAP passport and returns OAP-compliant decisions works with DeerFlow.
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    OAP Passport (JSON)                        │
-│                   (open standard, any provider)              │
-│  {                                                           │
-│    "spec_version": "oap/1.0",                                │
-│    "status": "active",                                       │
-│    "capabilities": [                                         │
-│      {"id": "system.command.execute"},                       │
-│      {"id": "data.file.read"},                               │
-│      {"id": "data.file.write"},                              │
-│      {"id": "web.fetch"},                                    │
-│      {"id": "mcp.tool.execute"}                              │
-│    ],                                                        │
-│    "limits": {                                               │
-│      "system.command.execute": {                             │
-│        "allowed_commands": ["git", "npm", "node", "ls"],     │
-│        "blocked_patterns": ["rm -rf", "sudo", "chmod 777"]   │
-│      }                                                       │
-│    }                                                         │
-│  }                                                           │
-└──────────────────────────┬──────────────────────────────────┘
-                           │
-               Any OAP-compliant provider
-          ┌────────────────┼────────────────┐
-          │                │                │
-     Your own         APort (ref.      Other future
-     evaluator        implementation)  implementations
-```
-
-**Creating a passport manually:**
-
-An OAP passport is just a JSON file. You can create one by hand following the [OAP specification](https://github.com/aporthq/aport-spec/blob/main/oap/oap-spec.md) and validate it against the [JSON schema](https://github.com/aporthq/aport-spec/blob/main/oap/passport-schema.json). See the [examples](https://github.com/aporthq/aport-spec/tree/main/oap/examples) directory for templates.
-
-**Using APort as a reference implementation:**
-
-[APort Agent Guardrails](https://github.com/aporthq/aport-agent-guardrails) is one open-source (Apache 2.0) implementation of an OAP provider. It handles passport creation, local evaluation, and optional hosted API evaluation.
-
-```bash
-pip install aport-agent-guardrails
-aport setup --framework deerflow
-```
-
-This creates:
-- `~/.aport/deerflow/config.yaml` -- evaluator config (local or API mode)
-- `~/.aport/deerflow/aport/passport.json` -- OAP passport with capabilities and limits
-
-**config.yaml (using APort as the provider):**
-```yaml
-guardrails:
-  enabled: true
-  provider:
-    use: aport_guardrails.providers.generic:OAPGuardrailProvider
-```
-
-**config.yaml (using your own OAP provider):**
-```yaml
-guardrails:
-  enabled: true
-  provider:
-    use: my_oap_provider:MyOAPProvider
-    config:
-      passport_path: ./my-passport.json
-```
-
-Any provider that accepts `framework` as a kwarg and implements `evaluate`/`aevaluate` works. The OAP standard defines the passport format and decision codes; DeerFlow doesn't care which provider reads them.
-
-**What the passport controls:**
-
-| Passport field | What it does | Example |
-|---|---|---|
-| `capabilities[].id` | Which tool categories the agent can use | `system.command.execute`, `data.file.write` |
-| `limits.*.allowed_commands` | Which commands are allowed | `["git", "npm", "node"]` or `["*"]` for all |
-| `limits.*.blocked_patterns` | Patterns always denied | `["rm -rf", "sudo", "chmod 777"]` |
-| `status` | Kill switch | `active`, `suspended`, `revoked` |
-
-**Evaluation modes (provider-dependent):**
-
-OAP providers may support different evaluation modes. For example, the APort reference implementation supports:
-
-| Mode | How it works | Network | Latency |
-|---|---|---|---|
-| **Local** | Evaluates passport locally (bash script). | None | ~300ms |
-| **API** | Sends passport + context to a hosted evaluator. Signed decisions. | Yes | ~65ms |
-
-A custom OAP provider can implement any evaluation strategy -- the DeerFlow middleware doesn't care how the provider reaches its decision.
-
-**Try it:**
-1. Install and set up as above
-2. Start DeerFlow and ask: "Create a file called test.txt with content hello"
-3. Then ask: "Now delete it using bash rm -rf"
-4. Guardrail blocks it: `oap.blocked_pattern: Command contains blocked pattern: rm -rf`
-
-### Option 3: Custom Provider (Bring Your Own)
-
-Any Python class with `evaluate(request)` and `aevaluate(request)` methods works. No base class or inheritance needed -- it's a structural protocol.
-
-```python
-# my_guardrail.py
-
-class MyGuardrailProvider:
-    name = "my-company"
-
-    def evaluate(self, request):
-        from deerflow.guardrails.provider import GuardrailDecision, GuardrailReason
-
-        # Example: block any bash command containing "delete"
-        if request.tool_name == "bash" and "delete" in str(request.tool_input):
-            return GuardrailDecision(
-                allow=False,
-                reasons=[GuardrailReason(code="custom.blocked", message="delete not allowed")],
-                policy_id="custom.v1",
-            )
-        return GuardrailDecision(allow=True, reasons=[GuardrailReason(code="oap.allowed")])
-
-    async def aevaluate(self, request):
-        return self.evaluate(request)
-```
-
-**config.yaml:**
-```yaml
-guardrails:
-  enabled: true
-  provider:
-    use: my_guardrail:MyGuardrailProvider
-```
-
-Make sure `my_guardrail.py` is on the Python path (e.g. in the backend directory or installed as a package).
-
-**Try it:**
-1. Create `my_guardrail.py` in the backend directory
-2. Add the config
-3. Start DeerFlow and ask: "Use bash to delete test.txt"
-4. Your provider blocks it
-
-## Implementing a Provider
-
-### Required Interface
-
-```
-┌──────────────────────────────────────────────────┐
-│              GuardrailProvider Protocol            │
-│                                                   │
-│  name: str                                        │
-│                                                   │
-│  evaluate(request: GuardrailRequest)              │
-│      -> GuardrailDecision                         │
-│                                                   │
-│  aevaluate(request: GuardrailRequest)   (async)   │
-│      -> GuardrailDecision                         │
-└──────────────────────────────────────────────────┘
-
-┌──────────────────────────┐    ┌──────────────────────────┐
-│     GuardrailRequest      │    │    GuardrailDecision      │
-│                           │    │                           │
-│  tool_name: str           │    │  allow: bool              │
-│  tool_input: dict         │    │  reasons: [GuardrailReason]│
-│  agent_id: str | None     │    │  policy_id: str | None    │
-│  thread_id: str | None    │    │  metadata: dict           │
-│  is_subagent: bool        │    │                           │
-│  timestamp: str           │    │  GuardrailReason:         │
-│                           │    │    code: str              │
-└──────────────────────────┘    │    message: str           │
-                                └──────────────────────────┘
-```
-
-### DeerFlow Tool Names
-
-These are the tool names your provider will see in `request.tool_name`:
-
-| Tool | What it does |
-|---|---|
-| `bash` | Shell command execution |
-| `write_file` | Create/overwrite a file |
-| `str_replace` | Edit a file (find and replace) |
-| `read_file` | Read file content |
-| `ls` | List directory |
-| `web_search` | Web search query |
-| `web_fetch` | Fetch URL content |
-| `image_search` | Image search |
-| `present_file` | Present file to user |
-| `view_image` | Display image |
-| `ask_clarification` | Ask user a question |
-| `task` | Delegate to subagent |
-| `mcp__*` | MCP tools (dynamic) |
-
-### OAP Reason Codes
-
-Standard codes used by the [OAP specification](https://github.com/aporthq/aport-spec):
-
-| Code | Meaning |
-|---|---|
-| `oap.allowed` | Tool call authorized |
-| `oap.tool_not_allowed` | Tool not in allowlist |
-| `oap.command_not_allowed` | Command not in allowed_commands |
-| `oap.blocked_pattern` | Command matches a blocked pattern |
-| `oap.limit_exceeded` | Operation exceeds a limit |
-| `oap.passport_suspended` | Passport status is suspended/revoked |
-| `oap.evaluator_error` | Provider crashed (fail-closed) |
-
-### Provider Loading
-
-DeerFlow loads providers via `resolve_variable()` -- the same mechanism used for models, tools, and sandbox providers. The `use:` field is a Python class path: `package.module:ClassName`.
-
-The provider is instantiated with `**config` kwargs if `config:` is set, plus `framework="deerflow"` is always injected. Accept `**kwargs` to stay forward-compatible:
-
-```python
-class YourProvider:
-    def __init__(self, framework: str = "generic", **kwargs):
-        # framework="deerflow" tells you which config dir to use
-        ...
-```
-
-## Configuration Reference
-
-```yaml
-guardrails:
-  # Enable/disable guardrail middleware (default: false)
-  enabled: true
-
-  # Block tool calls if provider raises an exception (default: true)
-  fail_closed: true
-
-  # Passport reference -- passed as request.agent_id to the provider.
-  # File path, hosted agent ID, or null (provider resolves from its config).
-  passport: null
-
-  # Provider: loaded by class path via resolve_variable
-  provider:
-    use: deerflow.guardrails.builtin:AllowlistProvider
-    config:  # optional kwargs passed to provider.__init__
-      denied_tools: ["bash"]
-```
-
-## Testing
-
-```bash
-cd backend
-uv run python -m pytest tests/test_guardrail_middleware.py -v
-```
-
-25 tests covering:
-- AllowlistProvider: allow, deny, both allowlist+denylist, async
-- GuardrailMiddleware: allow passthrough, deny with OAP codes, fail-closed, fail-open, passport forwarding, empty reasons fallback, empty tool name, protocol isinstance check
-- Async paths: awrap_tool_call for allow, deny, fail-closed, fail-open
-- GraphBubbleUp: LangGraph control signals propagate through (not caught)
-- Config: defaults, from_dict, singleton load/reset
-
-## Files
-
-```
-packages/harness/deerflow/guardrails/
-    __init__.py              # Public exports
-    provider.py              # GuardrailProvider protocol, GuardrailRequest, GuardrailDecision
-    middleware.py             # GuardrailMiddleware (AgentMiddleware subclass)
-    builtin.py               # AllowlistProvider (zero deps)
-
-packages/harness/deerflow/config/
-    guardrails_config.py     # GuardrailsConfig Pydantic model + singleton
-
-packages/harness/deerflow/agents/middlewares/
-    tool_error_handling_middleware.py  # Registers GuardrailMiddleware in chain
-
-config.example.yaml          # Three provider options documented
-tests/test_guardrail_middleware.py  # 25 tests
-docs/GUARDRAILS.md           # This file
-```

backend/docs/HARNESS_APP_SPLIT.md

@@ -1,343 +0,0 @@
-# DeerFlow 后端拆分设计文档：Harness + App
-
-> 状态：Draft
-> 作者：DeerFlow Team
-> 日期：2026-03-13
-
-## 1. 背景与动机
-
-DeerFlow 后端当前是一个单一 Python 包（`src.*`），包含了从底层 agent 编排到上层用户产品的所有代码。随着项目发展，这种结构带来了几个问题：
-
-- **复用困难**：其他产品（CLI 工具、Slack bot、第三方集成）想用 agent 能力，必须依赖整个后端，包括 FastAPI、IM SDK 等不需要的依赖
-- **职责模糊**：agent 编排逻辑和用户产品逻辑混在同一个 `src/` 下，边界不清晰
-- **依赖膨胀**：LangGraph Server 运行时不需要 FastAPI/uvicorn/Slack SDK，但当前必须安装全部依赖
-
-本文档提出将后端拆分为两部分：**deerflow-harness**（可发布的 agent 框架包）和 **app**（不打包的用户产品代码）。
-
-## 2. 核心概念
-
-### 2.1 Harness（线束/框架层）
-
-Harness 是 agent 的构建与编排框架，回答 **"如何构建和运行 agent"** 的问题：
-
-- Agent 工厂与生命周期管理
-- Middleware pipeline
-- 工具系统（内置工具 + MCP + 社区工具）
-- 沙箱执行环境
-- 子 agent 委派
-- 记忆系统
-- 技能加载与注入
-- 模型工厂
-- 配置系统
-
-**Harness 是一个可发布的 Python 包**（`deerflow-harness`），可以独立安装和使用。
-
-**Harness 的设计原则**：对上层应用完全无感知。它不知道也不关心谁在调用它——可以是 Web App、CLI、Slack Bot、或者一个单元测试。
-
-### 2.2 App（应用层）
-
-App 是面向用户的产品代码，回答 **"如何将 agent 呈现给用户"** 的问题：
-
-- Gateway API（FastAPI REST 接口）
-- IM Channels（飞书、Slack、Telegram 集成）
-- Custom Agent 的 CRUD 管理
-- 文件上传/下载的 HTTP 接口
-
-**App 不打包、不发布**，它是 DeerFlow 项目内部的应用代码，直接运行。
-
-**App 依赖 Harness，但 Harness 不依赖 App。**
-
-### 2.3 边界划分
-
-| 模块 | 归属 | 说明 |
-|------|------|------|
-| `config/` | Harness | 配置系统是基础设施 |
-| `reflection/` | Harness | 动态模块加载工具 |
-| `utils/` | Harness | 通用工具函数 |
-| `agents/` | Harness | Agent 工厂、middleware、state、memory |
-| `subagents/` | Harness | 子 agent 委派系统 |
-| `sandbox/` | Harness | 沙箱执行环境 |
-| `tools/` | Harness | 工具注册与发现 |
-| `mcp/` | Harness | MCP 协议集成 |
-| `skills/` | Harness | 技能加载、解析、定义 schema |
-| `models/` | Harness | LLM 模型工厂 |
-| `community/` | Harness | 社区工具（tavily、jina 等） |
-| `client.py` | Harness | 嵌入式 Python 客户端 |
-| `gateway/` | App | FastAPI REST API |
-| `channels/` | App | IM 平台集成 |
-
-**关于 Custom Agents**：agent 定义格式（`config.yaml` + `SOUL.md` schema）由 Harness 层的 `config/agents_config.py` 定义，但文件的存储、CRUD、发现机制由 App 层的 `gateway/routers/agents.py` 负责。
-
-## 3. 目标架构
-
-### 3.1 目录结构
-
-```
-backend/
-├── packages/
-│   └── harness/
-│       ├── pyproject.toml          # deerflow-harness 包定义
-│       └── deerflow/               # Python 包根（import 前缀: deerflow.*）
-│           ├── __init__.py
-│           ├── config/
-│           ├── reflection/
-│           ├── utils/
-│           ├── agents/
-│           │   ├── lead_agent/
-│           │   ├── middlewares/
-│           │   ├── memory/
-│           │   ├── checkpointer/
-│           │   └── thread_state.py
-│           ├── subagents/
-│           ├── sandbox/
-│           ├── tools/
-│           ├── mcp/
-│           ├── skills/
-│           ├── models/
-│           ├── community/
-│           └── client.py
-├── app/                            # 不打包（import 前缀: app.*）
-│   ├── __init__.py
-│   ├── gateway/
-│   │   ├── __init__.py
-│   │   ├── app.py
-│   │   ├── config.py
-│   │   ├── path_utils.py
-│   │   └── routers/
-│   └── channels/
-│       ├── __init__.py
-│       ├── base.py
-│       ├── manager.py
-│       ├── service.py
-│       ├── store.py
-│       ├── message_bus.py
-│       ├── feishu.py
-│       ├── slack.py
-│       └── telegram.py
-├── pyproject.toml                  # uv workspace root
-├── langgraph.json
-├── tests/
-├── docs/
-└── Makefile
-```
-
-### 3.2 Import 规则
-
-两个层使用不同的 import 前缀，职责边界一目了然：
-
-```python
-# ---------------------------------------------------------------
-# Harness 内部互相引用（deerflow.* 前缀）
-# ---------------------------------------------------------------
-from deerflow.agents import make_lead_agent
-from deerflow.models import create_chat_model
-from deerflow.config import get_app_config
-from deerflow.tools import get_available_tools
-
-# ---------------------------------------------------------------
-# App 内部互相引用（app.* 前缀）
-# ---------------------------------------------------------------
-from app.gateway.app import app
-from app.gateway.routers.uploads import upload_files
-from app.channels.service import start_channel_service
-
-# ---------------------------------------------------------------
-# App 调用 Harness（单向依赖，Harness 永远不 import app）
-# ---------------------------------------------------------------
-from deerflow.agents import make_lead_agent
-from deerflow.models import create_chat_model
-from deerflow.skills import load_skills
-from deerflow.config.extensions_config import get_extensions_config
-```
-
-**App 调用 Harness 示例 — Gateway 中启动 agent**：
-
-```python
-# app/gateway/routers/chat.py
-from deerflow.agents.lead_agent.agent import make_lead_agent
-from deerflow.models import create_chat_model
-from deerflow.config import get_app_config
-
-async def create_chat_session(thread_id: str, model_name: str):
-    config = get_app_config()
-    model = create_chat_model(name=model_name)
-    agent = make_lead_agent(config=...)
-    # ... 使用 agent 处理用户消息
-```
-
-**App 调用 Harness 示例 — Channel 中查询 skills**：
-
-```python
-# app/channels/manager.py
-from deerflow.skills import load_skills
-from deerflow.agents.memory.updater import get_memory_data
-
-def handle_status_command():
-    skills = load_skills(enabled_only=True)
-    memory = get_memory_data()
-    return f"Skills: {len(skills)}, Memory facts: {len(memory.get('facts', []))}"
-```
-
-**禁止方向**：Harness 代码中绝不能出现 `from app.` 或 `import app.`。
-
-### 3.3 为什么 App 不打包
-
-| 方面 | 打包（放 packages/ 下） | 不打包（放 backend/app/） |
-|------|------------------------|--------------------------|
-| 命名空间 | 需要 pkgutil `extend_path` 合并，或独立前缀 | 天然独立，`app.*` vs `deerflow.*` |
-| 发布需求 | 没有——App 是项目内部代码 | 不需要 pyproject.toml |
-| 复杂度 | 需要管理两个包的构建、版本、依赖声明 | 直接运行，零额外配置 |
-| 运行方式 | `pip install deerflow-app` | `PYTHONPATH=. uvicorn app.gateway.app:app` |
-
-App 的唯一消费者是 DeerFlow 项目自身，没有独立发布的需求。放在 `backend/app/` 下作为普通 Python 包，通过 `PYTHONPATH` 或 editable install 让 Python 找到即可。
-
-### 3.4 依赖关系
-
-```
-┌─────────────────────────────────────┐
-│  app/  (不打包，直接运行)             │
-│  ├── fastapi, uvicorn               │
-│  ├── slack-sdk, lark-oapi, ...      │
-│  └── import deerflow.*              │
-└──────────────┬──────────────────────┘
-               │
-               ▼
-┌─────────────────────────────────────┐
-│  deerflow-harness  (可发布的包)       │
-│  ├── langgraph, langchain           │
-│  ├── markitdown, pydantic, ...      │
-│  └── 零 app 依赖                     │
-└─────────────────────────────────────┘
-```
-
-**依赖分类**：
-
-| 分类 | 依赖包 |
-|------|--------|
-| Harness only | agent-sandbox, langchain*, langgraph*, markdownify, markitdown, pydantic, pyyaml, readabilipy, tavily-python, firecrawl-py, tiktoken, ddgs, duckdb, httpx, kubernetes, dotenv |
-| App only | fastapi, uvicorn, sse-starlette, python-multipart, lark-oapi, slack-sdk, python-telegram-bot, markdown-to-mrkdwn |
-| Shared | langgraph-sdk（channels 用 HTTP client）, pydantic, httpx |
-
-### 3.5 Workspace 配置
-
-`backend/pyproject.toml`（workspace root）：
-
-```toml
-[project]
-name = "deer-flow"
-version = "0.1.0"
-requires-python = ">=3.12"
-dependencies = ["deerflow-harness"]
-
-[dependency-groups]
-dev = ["pytest>=8.0.0", "ruff>=0.14.11"]
-# App 的额外依赖（fastapi 等）也声明在 workspace root，因为 app 不打包
-app = ["fastapi", "uvicorn", "sse-starlette", "python-multipart"]
-channels = ["lark-oapi", "slack-sdk", "python-telegram-bot"]
-
-[tool.uv.workspace]
-members = ["packages/harness"]
-
-[tool.uv.sources]
-deerflow-harness = { workspace = true }
-```
-
-## 4. 当前的跨层依赖问题
-
-在拆分之前，需要先解决 `client.py` 中两处从 harness 到 app 的反向依赖：
-
-### 4.1 `_validate_skill_frontmatter`
-
-```python
-# client.py — harness 导入了 app 层代码
-from src.gateway.routers.skills import _validate_skill_frontmatter
-```
-
-**解决方案**：将该函数提取到 `deerflow/skills/validation.py`。这是一个纯逻辑函数（解析 YAML frontmatter、校验字段），与 FastAPI 无关。
-
-### 4.2 `CONVERTIBLE_EXTENSIONS` + `convert_file_to_markdown`
-
-```python
-# client.py — harness 导入了 app 层代码
-from src.gateway.routers.uploads import CONVERTIBLE_EXTENSIONS, convert_file_to_markdown
-```
-
-**解决方案**：将它们提取到 `deerflow/utils/file_conversion.py`。仅依赖 `markitdown` + `pathlib`，是通用工具函数。
-
-## 5. 基础设施变更
-
-### 5.1 LangGraph Server
-
-LangGraph Server 只需要 harness 包。`langgraph.json` 更新：
-
-```json
-{
-  "dependencies": ["./packages/harness"],
-  "graphs": {
-    "lead_agent": "deerflow.agents:make_lead_agent"
-  },
-  "checkpointer": {
-    "path": "./packages/harness/deerflow/agents/checkpointer/async_provider.py:make_checkpointer"
-  }
-}
-```
-
-### 5.2 Gateway API
-
-```bash
-# serve.sh / Makefile
-# PYTHONPATH 包含 backend/ 根目录，使 app.* 和 deerflow.* 都能被找到
-PYTHONPATH=. uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
-```
-
-### 5.3 Nginx
-
-无需变更（只做 URL 路由，不涉及 Python 模块路径）。
-
-### 5.4 Docker
-
-Dockerfile 中的 module 引用从 `src.` 改为 `deerflow.` / `app.`，`COPY` 命令需覆盖 `packages/` 和 `app/` 目录。
-
-## 6. 实施计划
-
-分 3 个 PR 递进执行：
-
-### PR 1：提取共享工具函数（Low Risk）
-
-1. 创建 `src/skills/validation.py`，从 `gateway/routers/skills.py` 提取 `_validate_skill_frontmatter`
-2. 创建 `src/utils/file_conversion.py`，从 `gateway/routers/uploads.py` 提取文件转换逻辑
-3. 更新 `client.py`、`gateway/routers/skills.py`、`gateway/routers/uploads.py` 的 import
-4. 运行全部测试确认无回归
-
-### PR 2：Rename + 物理拆分（High Risk，原子操作）
-
-1. 创建 `packages/harness/` 目录，创建 `pyproject.toml`
-2. `git mv` 将 harness 相关模块从 `src/` 移入 `packages/harness/deerflow/`
-3. `git mv` 将 app 相关模块从 `src/` 移入 `app/`
-4. 全局替换 import：
-   - harness 模块：`src.*` → `deerflow.*`（所有 `.py` 文件、`langgraph.json`、测试、文档）
-   - app 模块：`src.gateway.*` → `app.gateway.*`、`src.channels.*` → `app.channels.*`
-5. 更新 workspace root `pyproject.toml`
-6. 更新 `langgraph.json`、`Makefile`、`Dockerfile`
-7. `uv sync` + 全部测试 + 手动验证服务启动
-
-### PR 3：边界检查 + 文档（Low Risk）
-
-1. 添加 lint 规则：检查 harness 不 import app 模块
-2. 更新 `CLAUDE.md`、`README.md`
-
-## 7. 风险与缓解
-
-| 风险 | 影响 | 缓解措施 |
-|------|------|----------|
-| 全局 rename 误伤 | 字符串中的 `src` 被错误替换 | 正则精确匹配 `\bsrc\.`，review diff |
-| LangGraph Server 找不到模块 | 服务启动失败 | `langgraph.json` 的 `dependencies` 指向正确的 harness 包路径 |
-| App 的 `PYTHONPATH` 缺失 | Gateway/Channel 启动 import 报错 | Makefile/Docker 统一设置 `PYTHONPATH=.` |
-| `config.yaml` 中的 `use` 字段引用旧路径 | 运行时模块解析失败 | `config.yaml` 中的 `use` 字段同步更新为 `deerflow.*` |
-| 测试中 `sys.path` 混乱 | 测试失败 | 用 editable install（`uv sync`）确保 deerflow 可导入，`conftest.py` 中添加 `app/` 到 `sys.path` |
-
-## 8. 未来演进
-
-- **独立发布**：harness 可以发布到内部 PyPI，让其他项目直接 `pip install deerflow-harness`
-- **插件化 App**：不同的 app（web、CLI、bot）可以各自独立，都依赖同一个 harness
-- **更细粒度拆分**：如果 harness 内部模块继续增长，可以进一步拆分（如 `deerflow-sandbox`、`deerflow-mcp`）

backend/docs/MEMORY_IMPROVEMENTS.md

@@ -1,65 +1,281 @@
 # Memory System Improvements
 
-This document tracks memory injection behavior and roadmap status.
+This document describes recent improvements to the memory system's fact injection mechanism.
 
-## Status (As Of 2026-03-10)
+## Overview
 
-Implemented in `main`:
-- Accurate token counting via `tiktoken` in `format_memory_for_injection`.
-- Facts are injected into prompt memory context.
-- Facts are ranked by confidence (descending).
-- Injection respects `max_injection_tokens` budget.
+Two major improvements have been made to the `format_memory_for_injection` function:
 
-Planned / not yet merged:
-- TF-IDF similarity-based fact retrieval.
-- `current_context` input for context-aware scoring.
-- Configurable similarity/confidence weights (`similarity_weight`, `confidence_weight`).
-- Middleware/runtime wiring for context-aware retrieval before each model call.
+1. **Similarity-Based Fact Retrieval**: Uses TF-IDF to select facts most relevant to current conversation context
+2. **Accurate Token Counting**: Uses tiktoken for precise token estimation instead of rough character-based approximation
 
-## Current Behavior
+## 1. Similarity-Based Fact Retrieval
 
-Function today:
+### Problem
+The original implementation selected facts based solely on confidence scores, taking the top 15 highest-confidence facts regardless of their relevance to the current conversation. This could result in injecting irrelevant facts while omitting contextually important ones.
+
+### Solution
+The new implementation uses **TF-IDF (Term Frequency-Inverse Document Frequency)** vectorization with cosine similarity to measure how relevant each fact is to the current conversation context.
+
+**Scoring Formula**:
+```
+final_score = (similarity × 0.6) + (confidence × 0.4)
+```
+
+- **Similarity (60% weight)**: Cosine similarity between fact content and current context
+- **Confidence (40% weight)**: LLM-assigned confidence score (0-1)
+
+### Benefits
+- **Context-Aware**: Prioritizes facts relevant to what the user is currently discussing
+- **Dynamic**: Different facts surface based on conversation topic
+- **Balanced**: Considers both relevance and reliability
+- **Fallback**: Gracefully degrades to confidence-only ranking if context is unavailable
+
+### Example
+Given facts about Python, React, and Docker:
+- User asks: *"How should I write Python tests?"*
+  - Prioritizes: Python testing, type hints, pytest
+- User asks: *"How to optimize my Next.js app?"*
+  - Prioritizes: React/Next.js experience, performance optimization
+
+### Configuration
+Customize weights in `config.yaml` (optional):
+```yaml
+memory:
+  similarity_weight: 0.6  # Weight for TF-IDF similarity (0-1)
+  confidence_weight: 0.4  # Weight for confidence score (0-1)
+```
+
+**Note**: Weights should sum to 1.0 for best results.
+
+## 2. Accurate Token Counting
+
+### Problem
+The original implementation estimated tokens using a simple formula:
+```python
+max_chars = max_tokens * 4
+```
+
+This assumes ~4 characters per token, which is:
+- Inaccurate for many languages and content types
+- Can lead to over-injection (exceeding token limits)
+- Can lead to under-injection (wasting available budget)
+
+### Solution
+The new implementation uses **tiktoken**, OpenAI's official tokenizer library, to count tokens accurately:
 
 ```python
-def format_memory_for_injection(memory_data: dict[str, Any], max_tokens: int = 2000) -> str:
+import tiktoken
+
+def _count_tokens(text: str, encoding_name: str = "cl100k_base") -> int:
+    encoding = tiktoken.get_encoding(encoding_name)
+    return len(encoding.encode(text))
 ```
 
-Current injection format:
-- `User Context` section from `user.*.summary`
-- `History` section from `history.*.summary`
-- `Facts` section from `facts[]`, sorted by confidence, appended until token budget is reached
+- Uses `cl100k_base` encoding (GPT-4, GPT-3.5, text-embedding-ada-002)
+- Provides exact token counts for budget management
+- Falls back to character-based estimation if tiktoken fails
 
-Token counting:
-- Uses `tiktoken` (`cl100k_base`) when available
-- Falls back to `len(text) // 4` if tokenizer import fails
+### Benefits
+- **Precision**: Exact token counts match what the model sees
+- **Budget Optimization**: Maximizes use of available token budget
+- **No Overflows**: Prevents exceeding `max_injection_tokens` limit
+- **Better Planning**: Each section's token cost is known precisely
 
-## Known Gap
+### Example
+```python
+text = "This is a test string to count tokens accurately using tiktoken."
 
-Previous versions of this document described TF-IDF/context-aware retrieval as if it were already shipped.
-That was not accurate for `main` and caused confusion.
+# Old method
+char_count = len(text)  # 64 characters
+old_estimate = char_count // 4  # 16 tokens (overestimate)
 
-Issue reference: `#1059`
-
-## Roadmap (Planned)
-
-Planned scoring strategy:
-
-```text
-final_score = (similarity * 0.6) + (confidence * 0.4)
+# New method
+accurate_count = _count_tokens(text)  # 13 tokens (exact)
 ```
 
-Planned integration shape:
-1. Extract recent conversational context from filtered user/final-assistant turns.
-2. Compute TF-IDF cosine similarity between each fact and current context.
-3. Rank by weighted score and inject under token budget.
-4. Fall back to confidence-only ranking if context is unavailable.
+**Result**: 3-token difference (18.75% error rate)
 
-## Validation
+In production, errors can be much larger for:
+- Code snippets (more tokens per character)
+- Non-English text (variable token ratios)
+- Technical jargon (often multi-token words)
 
-Current regression coverage includes:
-- facts inclusion in memory injection output
-- confidence ordering
-- token-budget-limited fact inclusion
+## Implementation Details
 
-Tests:
-- `backend/tests/test_memory_prompt_injection.py`
+### Function Signature
+```python
+def format_memory_for_injection(
+    memory_data: dict[str, Any],
+    max_tokens: int = 2000,
+    current_context: str | None = None,
+) -> str:
+```
+
+**New Parameter**:
+- `current_context`: Optional string containing recent conversation messages for similarity calculation
+
+### Backward Compatibility
+The function remains **100% backward compatible**:
+- If `current_context` is `None` or empty, falls back to confidence-only ranking
+- Existing callers without the parameter work exactly as before
+- Token counting is always accurate (transparent improvement)
+
+### Integration Point
+Memory is **dynamically injected** via `MemoryMiddleware.before_model()`:
+
+```python
+# src/agents/middlewares/memory_middleware.py
+
+def _extract_conversation_context(messages: list, max_turns: int = 3) -> str:
+    """Extract recent conversation (user input + final responses only)."""
+    context_parts = []
+    turn_count = 0
+
+    for msg in reversed(messages):
+        if msg.type == "human":
+            # Always include user messages
+            context_parts.append(extract_text(msg))
+            turn_count += 1
+            if turn_count >= max_turns:
+                break
+
+        elif msg.type == "ai" and not msg.tool_calls:
+            # Only include final AI responses (no tool_calls)
+            context_parts.append(extract_text(msg))
+
+        # Skip tool messages and AI messages with tool_calls
+
+    return " ".join(reversed(context_parts))
+
+
+class MemoryMiddleware:
+    def before_model(self, state, runtime):
+        """Inject memory before EACH LLM call (not just before_agent)."""
+
+        # Get recent conversation context (filtered)
+        conversation_context = _extract_conversation_context(
+            state["messages"],
+            max_turns=3
+        )
+
+        # Load memory with context-aware fact selection
+        memory_data = get_memory_data()
+        memory_content = format_memory_for_injection(
+            memory_data,
+            max_tokens=config.max_injection_tokens,
+            current_context=conversation_context,  # ✅ Clean conversation only
+        )
+
+        # Inject as system message
+        memory_message = SystemMessage(
+            content=f"<memory>\n{memory_content}\n</memory>",
+            name="memory_context",
+        )
+
+        return {"messages": [memory_message] + state["messages"]}
+```
+
+### How It Works
+
+1. **User continues conversation**:
+   ```
+   Turn 1: "I'm working on a Python project"
+   Turn 2: "It uses FastAPI and SQLAlchemy"
+   Turn 3: "How do I write tests?"  ← Current query
+   ```
+
+2. **Extract recent context**: Last 3 turns combined:
+   ```
+   "I'm working on a Python project. It uses FastAPI and SQLAlchemy. How do I write tests?"
+   ```
+
+3. **TF-IDF scoring**: Ranks facts by relevance to this context
+   - High score: "Prefers pytest for testing" (testing + Python)
+   - High score: "Likes type hints in Python" (Python related)
+   - High score: "Expert in Python and FastAPI" (Python + FastAPI)
+   - Low score: "Uses Docker for containerization" (less relevant)
+
+4. **Injection**: Top-ranked facts injected into system prompt's `<memory>` section
+
+5. **Agent sees**: Full system prompt with relevant memory context
+
+### Benefits of Dynamic System Prompt
+
+- **Multi-Turn Context**: Uses last 3 turns, not just current question
+  - Captures ongoing conversation flow
+  - Better understanding of user's current focus
+- **Query-Specific Facts**: Different facts surface based on conversation topic
+- **Clean Architecture**: No middleware message manipulation
+- **LangChain Native**: Uses built-in dynamic system prompt support
+- **Runtime Flexibility**: Memory regenerated for each agent invocation
+
+## Dependencies
+
+New dependencies added to `pyproject.toml`:
+```toml
+dependencies = [
+    # ... existing dependencies ...
+    "tiktoken>=0.8.0",      # Accurate token counting
+    "scikit-learn>=1.6.1",  # TF-IDF vectorization
+]
+```
+
+Install with:
+```bash
+cd backend
+uv sync
+```
+
+## Testing
+
+Run the test script to verify improvements:
+```bash
+cd backend
+python test_memory_improvement.py
+```
+
+Expected output shows:
+- Different fact ordering based on context
+- Accurate token counts vs old estimates
+- Budget-respecting fact selection
+
+## Performance Impact
+
+### Computational Cost
+- **TF-IDF Calculation**: O(n × m) where n=facts, m=vocabulary
+  - Negligible for typical fact counts (10-100 facts)
+  - Caching opportunities if context doesn't change
+- **Token Counting**: ~10-100µs per call
+  - Faster than the old character-counting approach
+  - Minimal overhead compared to LLM inference
+
+### Memory Usage
+- **TF-IDF Vectorizer**: ~1-5MB for typical vocabulary
+  - Instantiated once per injection call
+  - Garbage collected after use
+- **Tiktoken Encoding**: ~1MB (cached singleton)
+  - Loaded once per process lifetime
+
+### Recommendations
+- Current implementation is optimized for accuracy over caching
+- For high-throughput scenarios, consider:
+  - Pre-computing fact embeddings (store in memory.json)
+  - Caching TF-IDF vectorizer between calls
+  - Using approximate nearest neighbor search for >1000 facts
+
+## Summary
+
+| Aspect | Before | After |
+|--------|--------|-------|
+| Fact Selection | Top 15 by confidence only | Relevance-based (similarity + confidence) |
+| Token Counting | `len(text) // 4` | `tiktoken.encode(text)` |
+| Context Awareness | None | TF-IDF cosine similarity |
+| Accuracy | ±25% token estimate | Exact token count |
+| Configuration | Fixed weights | Customizable similarity/confidence weights |
+
+These improvements result in:
+- **More relevant** facts injected into context
+- **Better utilization** of available token budget
+- **Fewer hallucinations** due to focused context
+- **Higher quality** agent responses

backend/docs/MEMORY_IMPROVEMENTS_SUMMARY.md

@@ -1,38 +1,260 @@
 # Memory System Improvements - Summary
 
-## Sync Note (2026-03-10)
+## 改进概述
 
-This summary is synchronized with the `main` branch implementation.
-TF-IDF/context-aware retrieval is **planned**, not merged yet.
+针对你提出的两个问题进行了优化：
+1. ✅ **粗糙的 token 计算**（`字符数 * 4`）→ 使用 tiktoken 精确计算
+2. ✅ **缺乏相似度召回** → 使用 TF-IDF + 最近对话上下文
 
-## Implemented
+## 核心改进
 
-- Accurate token counting with `tiktoken` in memory injection.
-- Facts are injected into `<memory>` prompt content.
-- Facts are ordered by confidence and bounded by `max_injection_tokens`.
+### 1. 基于对话上下文的智能 Facts 召回
 
-## Planned (Not Yet Merged)
+**之前**：
+- 只按 confidence 排序取前 15 个
+- 无论用户在讨论什么都注入相同的 facts
 
-- TF-IDF cosine similarity recall based on recent conversation context.
-- `current_context` parameter for `format_memory_for_injection`.
-- Weighted ranking (`similarity` + `confidence`).
-- Runtime extraction/injection flow for context-aware fact selection.
+**现在**：
+- 提取最近 **3 轮对话**（human + AI 消息）作为上下文
+- 使用 **TF-IDF 余弦相似度**计算每个 fact 与对话的相关性
+- 综合评分：`相似度(60%) + 置信度(40%)`
+- 动态选择最相关的 facts
 
-## Why This Sync Was Needed
+**示例**：
+```
+对话历史：
+Turn 1: "我在做一个 Python 项目"
+Turn 2: "使用 FastAPI 和 SQLAlchemy"
+Turn 3: "怎么写测试？"
 
-Earlier docs described TF-IDF behavior as already implemented, which did not match code in `main`.
-This mismatch is tracked in issue `#1059`.
+上下文: "我在做一个 Python 项目 使用 FastAPI 和 SQLAlchemy 怎么写测试？"
 
-## Current API Shape
+相关度高的 facts:
+✓ "Prefers pytest for testing" (Python + 测试)
+✓ "Expert in Python and FastAPI" (Python + FastAPI)
+✓ "Likes type hints in Python" (Python)
 
-```python
-def format_memory_for_injection(memory_data: dict[str, Any], max_tokens: int = 2000) -> str:
+相关度低的 facts:
+✗ "Uses Docker for containerization" (不相关)
 ```
 
-No `current_context` argument is currently available in `main`.
+### 2. 精确的 Token 计算
 
-## Verification Pointers
+**之前**：
+```python
+max_chars = max_tokens * 4  # 粗糙估算
+```
 
-- Implementation: `packages/harness/deerflow/agents/memory/prompt.py`
-- Prompt assembly: `packages/harness/deerflow/agents/lead_agent/prompt.py`
-- Regression tests: `backend/tests/test_memory_prompt_injection.py`
+**现在**：
+```python
+import tiktoken
+
+def _count_tokens(text: str) -> int:
+    encoding = tiktoken.get_encoding("cl100k_base")  # GPT-4/3.5
+    return len(encoding.encode(text))
+```
+
+**效果对比**：
+```python
+text = "This is a test string to count tokens accurately."
+旧方法: len(text) // 4 = 12 tokens (估算)
+新方法: tiktoken.encode = 10 tokens (精确)
+误差: 20%
+```
+
+### 3. 多轮对话上下文
+
+**之前的担心**：
+> "只传最近一条 human message 会不会上下文不太够？"
+
+**现在的解决方案**：
+- 提取最近 **3 轮对话**（可配置）
+- 包括 human 和 AI 消息
+- 更完整的对话上下文
+
+**示例**：
+```
+单条消息: "怎么写测试？"
+→ 缺少上下文，不知道是什么项目
+
+3轮对话: "Python 项目 + FastAPI + 怎么写测试？"
+→ 完整上下文，能选择更相关的 facts
+```
+
+## 实现方式
+
+### Middleware 动态注入
+
+使用 `before_model` 钩子在**每次 LLM 调用前**注入 memory：
+
+```python
+# src/agents/middlewares/memory_middleware.py
+
+def _extract_conversation_context(messages: list, max_turns: int = 3) -> str:
+    """提取最近 3 轮对话（只包含用户输入和最终回复）"""
+    context_parts = []
+    turn_count = 0
+
+    for msg in reversed(messages):
+        msg_type = getattr(msg, "type", None)
+
+        if msg_type == "human":
+            # ✅ 总是包含用户消息
+            content = extract_text(msg)
+            if content:
+                context_parts.append(content)
+                turn_count += 1
+                if turn_count >= max_turns:
+                    break
+
+        elif msg_type == "ai":
+            # ✅ 只包含没有 tool_calls 的 AI 消息（最终回复）
+            tool_calls = getattr(msg, "tool_calls", None)
+            if not tool_calls:
+                content = extract_text(msg)
+                if content:
+                    context_parts.append(content)
+
+        # ✅ 跳过 tool messages 和带 tool_calls 的 AI 消息
+
+    return " ".join(reversed(context_parts))
+
+
+class MemoryMiddleware:
+    def before_model(self, state, runtime):
+        """在每次 LLM 调用前注入 memory（不是 before_agent）"""
+
+        # 1. 提取最近 3 轮对话（过滤掉 tool calls）
+        messages = state["messages"]
+        conversation_context = _extract_conversation_context(messages, max_turns=3)
+
+        # 2. 使用干净的对话上下文选择相关 facts
+        memory_data = get_memory_data()
+        memory_content = format_memory_for_injection(
+            memory_data,
+            max_tokens=config.max_injection_tokens,
+            current_context=conversation_context,  # ✅ 只包含真实对话内容
+        )
+
+        # 3. 作为 system message 注入到消息列表开头
+        memory_message = SystemMessage(
+            content=f"<memory>\n{memory_content}\n</memory>",
+            name="memory_context",  # 用于去重检测
+        )
+
+        # 4. 插入到消息列表开头
+        updated_messages = [memory_message] + messages
+        return {"messages": updated_messages}
+```
+
+### 为什么这样设计？
+
+基于你的三个重要观察：
+
+1. **应该用 `before_model` 而不是 `before_agent`**
+   - ✅ `before_agent`: 只在整个 agent 开始时调用一次
+   - ✅ `before_model`: 在**每次 LLM 调用前**都会调用
+   - ✅ 这样每次 LLM 推理都能看到最新的相关 memory
+
+2. **messages 数组里只有 human/ai/tool，没有 system**
+   - ✅ 虽然不常见，但 LangChain 允许在对话中插入 system message
+   - ✅ Middleware 可以修改 messages 数组
+   - ✅ 使用 `name="memory_context"` 防止重复注入
+
+3. **应该剔除 tool call 的 AI messages，只传用户输入和最终输出**
+   - ✅ 过滤掉带 `tool_calls` 的 AI 消息（中间步骤）
+   - ✅ 只保留：     - Human 消息（用户输入）
+     - AI 消息但无 tool_calls（最终回复）
+   - ✅ 上下文更干净，TF-IDF 相似度计算更准确
+
+## 配置选项
+
+在 `config.yaml` 中可以调整：
+
+```yaml
+memory:
+  enabled: true
+  max_injection_tokens: 2000  # ✅ 使用精确 token 计数
+
+  # 高级设置（可选）
+  # max_context_turns: 3  # 对话轮数（默认 3）
+  # similarity_weight: 0.6  # 相似度权重
+  # confidence_weight: 0.4  # 置信度权重
+```
+
+## 依赖变更
+
+新增依赖：
+```toml
+dependencies = [
+    "tiktoken>=0.8.0",      # 精确 token 计数
+    "scikit-learn>=1.6.1",  # TF-IDF 向量化
+]
+```
+
+安装：
+```bash
+cd backend
+uv sync
+```
+
+## 性能影响
+
+- **TF-IDF 计算**：O(n × m)，n=facts 数量，m=词汇表大小
+  - 典型场景（10-100 facts）：< 10ms
+- **Token 计数**：~100µs per call
+  - 比字符计数还快
+- **总开销**：可忽略（相比 LLM 推理）
+
+## 向后兼容性
+
+✅ 完全向后兼容：
+- 如果没有 `current_context`，退化为按 confidence 排序
+- 所有现有配置继续工作
+- 不影响其他功能
+
+## 文件变更清单
+
+1. **核心功能**
+   - `src/agents/memory/prompt.py` - 添加 TF-IDF 召回和精确 token 计数
+   - `src/agents/lead_agent/prompt.py` - 动态系统提示
+   - `src/agents/lead_agent/agent.py` - 传入函数而非字符串
+
+2. **依赖**
+   - `pyproject.toml` - 添加 tiktoken 和 scikit-learn
+
+3. **文档**
+   - `docs/MEMORY_IMPROVEMENTS.md` - 详细技术文档
+   - `docs/MEMORY_IMPROVEMENTS_SUMMARY.md` - 改进总结（本文件）
+   - `CLAUDE.md` - 更新架构说明
+   - `config.example.yaml` - 添加配置说明
+
+## 测试验证
+
+运行项目验证：
+```bash
+cd backend
+make dev
+```
+
+在对话中测试：
+1. 讨论不同主题（Python、React、Docker 等）
+2. 观察不同对话注入的 facts 是否不同
+3. 检查 token 预算是否被准确控制
+
+## 总结
+
+| 问题 | 之前 | 现在 |
+|------|------|------|
+| Token 计算 | `len(text) // 4` (±25% 误差) | `tiktoken.encode()` (精确) |
+| Facts 选择 | 按 confidence 固定排序 | TF-IDF 相似度 + confidence |
+| 上下文 | 无 | 最近 3 轮对话 |
+| 实现方式 | 静态系统提示 | 动态系统提示函数 |
+| 配置灵活性 | 有限 | 可调轮数和权重 |
+
+所有改进都实现了，并且：
+- ✅ 不修改 messages 数组
+- ✅ 使用多轮对话上下文
+- ✅ 精确 token 计数
+- ✅ 智能相似度召回
+- ✅ 完全向后兼容

backend/docs/MEMORY_SETTINGS_REVIEW.md

@@ -1,63 +0,0 @@
-# Memory Settings Review
-
-Use this when reviewing the Memory Settings add/edit flow locally with the fewest possible manual steps.
-
-## Quick Review
-
-1. Start DeerFlow locally using any working development setup you already use.
-
-   Examples:
-
-   ```bash
-   make dev
-   ```
-
-   or
-
-   ```bash
-   make docker-start
-   ```
-
-   If you already have DeerFlow running locally, you can reuse that existing setup.
-
-2. Load the sample memory fixture.
-
-   ```bash
-   python scripts/load_memory_sample.py
-   ```
-
-3. Open `Settings > Memory`.
-
-   Default local URLs:
-   - App: `http://localhost:2026`
-   - Local frontend-only fallback: `http://localhost:3000`
-
-## Minimal Manual Test
-
-1. Click `Add fact`.
-2. Create a new fact with:
-   - Content: `Reviewer-added memory fact`
-   - Category: `testing`
-   - Confidence: `0.88`
-3. Confirm the new fact appears immediately and shows `Manual` as the source.
-4. Edit the sample fact `This sample fact is intended for edit testing.` and change it to:
-   - Content: `This sample fact was edited during manual review.`
-   - Category: `testing`
-   - Confidence: `0.91`
-5. Confirm the edited fact updates immediately.
-6. Refresh the page and confirm both the newly added fact and the edited fact still persist.
-
-## Optional Sanity Checks
-
-- Search `Reviewer-added` and confirm the new fact is matched.
-- Search `workflow` and confirm category text is searchable.
-- Switch between `All`, `Facts`, and `Summaries`.
-- Delete the disposable sample fact `Delete fact testing can target this disposable sample entry.` and confirm the list updates immediately.
-- Clear all memory and confirm the page enters the empty state.
-
-## Fixture Files
-
-- Sample fixture: `backend/docs/memory-settings-sample.json`
-- Default local runtime target: `backend/.deer-flow/memory.json`
-
-The loader script creates a timestamped backup automatically before overwriting an existing runtime memory file.

backend/docs/PATH_EXAMPLES.md

@@ -144,7 +144,7 @@ async function uploadAndProcess(threadId: string, file: File) {
 
 ```python
 from pathlib import Path
-from deerflow.agents.middlewares.thread_data_middleware import THREAD_DATA_BASE_DIR
+from src.agents.middlewares.thread_data_middleware import THREAD_DATA_BASE_DIR
 
 def process_uploaded_file(thread_id: str, filename: str):
     # 使用实际路径

backend/docs/SETUP.md

@@ -30,7 +30,7 @@ DeerFlow uses a YAML configuration file that should be placed in the **project r
 4. **Verify configuration**:
    ```bash
    cd backend
-   python -c "from deerflow.config import get_app_config; print('✓ Config loaded:', get_app_config().models[0].name)"
+   python -c "from src.config import get_app_config; print('✓ Config loaded:', get_app_config().models[0].name)"
    ```
 
 ## Important Notes
@@ -51,7 +51,7 @@ The backend searches for `config.yaml` in this order:
 
 ## Sandbox Setup (Optional but Recommended)
 
-If you plan to use Docker/Container-based sandbox (configured in `config.yaml` under `sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider`), it's highly recommended to pre-pull the container image:
+If you plan to use Docker/Container-based sandbox (configured in `config.yaml` under `sandbox.use: src.community.aio_sandbox:AioSandboxProvider`), it's highly recommended to pre-pull the container image:
 
 ```bash
 # From project root
@@ -72,7 +72,7 @@ If you skip this step, the image will be automatically pulled on first agent exe
 ```bash
 # Check where the backend is looking
 cd deer-flow/backend
-python -c "from deerflow.config.app_config import AppConfig; print(AppConfig.resolve_config_path())"
+python -c "from src.config.app_config import AppConfig; print(AppConfig.resolve_config_path())"
 ```
 
 If it can't find the config:
@@ -88,5 +88,5 @@ chmod 600 ../config.yaml  # Protect sensitive configuration
 
 ## See Also
 
-- [Configuration Guide](CONFIGURATION.md) - Detailed configuration options
-- [Architecture Overview](../CLAUDE.md) - System architecture
+- [Configuration Guide](docs/CONFIGURATION.md) - Detailed configuration options
+- [Architecture Overview](CLAUDE.md) - System architecture

backend/docs/TITLE_GENERATION_IMPLEMENTATION.md

@@ -4,27 +4,27 @@
 
 ### 1. 核心实现文件
 
-#### [`packages/harness/deerflow/agents/thread_state.py`](../packages/harness/deerflow/agents/thread_state.py)
+#### [`src/agents/thread_state.py`](../src/agents/thread_state.py)
 - ✅ 添加 `title: str | None = None` 字段到 `ThreadState`
 
-#### [`packages/harness/deerflow/config/title_config.py`](../packages/harness/deerflow/config/title_config.py) (新建)
+#### [`src/config/title_config.py`](../src/config/title_config.py) (新建)
 - ✅ 创建 `TitleConfig` 配置类
 - ✅ 支持配置：enabled, max_words, max_chars, model_name, prompt_template
 - ✅ 提供 `get_title_config()` 和 `set_title_config()` 函数
 - ✅ 提供 `load_title_config_from_dict()` 从配置文件加载
 
-#### [`packages/harness/deerflow/agents/middlewares/title_middleware.py`](../packages/harness/deerflow/agents/middlewares/title_middleware.py) (新建)
+#### [`src/agents/title_middleware.py`](../src/agents/title_middleware.py) (新建)
 - ✅ 创建 `TitleMiddleware` 类
 - ✅ 实现 `_should_generate_title()` 检查是否需要生成
 - ✅ 实现 `_generate_title()` 调用 LLM 生成标题
 - ✅ 实现 `after_agent()` 钩子，在首次对话后自动触发
 - ✅ 包含 fallback 策略（LLM 失败时使用用户消息前几个词）
 
-#### [`packages/harness/deerflow/config/app_config.py`](../packages/harness/deerflow/config/app_config.py)
+#### [`src/config/app_config.py`](../src/config/app_config.py)
 - ✅ 导入 `load_title_config_from_dict`
 - ✅ 在 `from_file()` 中加载 title 配置
 
-#### [`packages/harness/deerflow/agents/lead_agent/agent.py`](../packages/harness/deerflow/agents/lead_agent/agent.py)
+#### [`src/agents/lead_agent/agent.py`](../src/agents/lead_agent/agent.py)
 - ✅ 导入 `TitleMiddleware`
 - ✅ 注册到 `middleware` 列表：`[SandboxMiddleware(), TitleMiddleware()]`
 
@@ -131,7 +131,7 @@ checkpointer = SqliteSaver.from_conn_string("checkpoints.db")
 // langgraph.json
 {
   "graphs": {
-    "lead_agent": "deerflow.agents:lead_agent"
+    "lead_agent": "src.agents:lead_agent"
   },
   "checkpointer": "checkpointer:checkpointer"
 }

backend/docs/TODO.md

@@ -20,13 +20,6 @@
 - [ ] Add metrics and monitoring
 - [ ] 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 `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)
-  - 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)
 
 ## Resolved Issues
 

backend/docs/memory-settings-sample.json

@@ -1,114 +0,0 @@
-{
-  "version": "1.0",
-  "lastUpdated": "2026-03-28T10:30:00Z",
-  "user": {
-    "workContext": {
-      "summary": "Working on DeerFlow memory management UX, including local search, local filters, clear-all, and single-fact deletion in Settings > Memory.",
-      "updatedAt": "2026-03-28T10:30:00Z"
-    },
-    "personalContext": {
-      "summary": "Prefers Chinese during collaboration, but wants GitHub PR titles and bodies written in English with a Chinese translation provided alongside them.",
-      "updatedAt": "2026-03-28T10:28:00Z"
-    },
-    "topOfMind": {
-      "summary": "Wants reviewers to be able to reproduce the memory search and filter flow quickly with pre-populated sample data.",
-      "updatedAt": "2026-03-28T10:26:00Z"
-    }
-  },
-  "history": {
-    "recentMonths": {
-      "summary": "Recently contributed multiple DeerFlow pull requests covering memory, uploads, and compatibility fixes.",
-      "updatedAt": "2026-03-28T10:24:00Z"
-    },
-    "earlierContext": {
-      "summary": "Often prefers shipping smaller, reviewable changes with explicit validation notes.",
-      "updatedAt": "2026-03-28T10:22:00Z"
-    },
-    "longTermBackground": {
-      "summary": "Actively building open-source contribution experience and improving end-to-end delivery quality.",
-      "updatedAt": "2026-03-28T10:20:00Z"
-    }
-  },
-  "facts": [
-    {
-      "id": "fact_review_001",
-      "content": "User prefers Chinese for day-to-day collaboration.",
-      "category": "preference",
-      "confidence": 0.95,
-      "createdAt": "2026-03-28T09:50:00Z",
-      "source": "thread_pref_cn"
-    },
-    {
-      "id": "fact_review_002",
-      "content": "PR titles and bodies should be drafted in English and accompanied by a Chinese translation.",
-      "category": "workflow",
-      "confidence": 0.93,
-      "createdAt": "2026-03-28T09:52:00Z",
-      "source": "thread_pr_style"
-    },
-    {
-      "id": "fact_review_003",
-      "content": "User implemented memory search and filter improvements in the DeerFlow settings page.",
-      "category": "project",
-      "confidence": 0.91,
-      "createdAt": "2026-03-28T09:54:00Z",
-      "source": "thread_memory_filters"
-    },
-    {
-      "id": "fact_review_004",
-      "content": "User added clear-all memory support through the gateway memory API.",
-      "category": "project",
-      "confidence": 0.89,
-      "createdAt": "2026-03-28T09:56:00Z",
-      "source": "thread_memory_clear"
-    },
-    {
-      "id": "fact_review_005",
-      "content": "User added single-fact deletion support for persisted memory entries.",
-      "category": "project",
-      "confidence": 0.9,
-      "createdAt": "2026-03-28T09:58:00Z",
-      "source": "thread_memory_delete"
-    },
-    {
-      "id": "fact_review_006",
-      "content": "Reviewer can search for keyword memory to see multiple matching facts.",
-      "category": "testing",
-      "confidence": 0.84,
-      "createdAt": "2026-03-28T10:00:00Z",
-      "source": "thread_review_demo"
-    },
-    {
-      "id": "fact_review_007",
-      "content": "Reviewer can search for keyword Chinese to verify cross-category matching.",
-      "category": "testing",
-      "confidence": 0.82,
-      "createdAt": "2026-03-28T10:02:00Z",
-      "source": "thread_review_demo"
-    },
-    {
-      "id": "fact_review_008",
-      "content": "Reviewer can search for workflow to verify category text is included in local filtering.",
-      "category": "testing",
-      "confidence": 0.81,
-      "createdAt": "2026-03-28T10:04:00Z",
-      "source": "thread_review_demo"
-    },
-    {
-      "id": "fact_review_009",
-      "content": "Delete fact testing can target this disposable sample entry.",
-      "category": "testing",
-      "confidence": 0.78,
-      "createdAt": "2026-03-28T10:06:00Z",
-      "source": "thread_delete_demo"
-    },
-    {
-      "id": "fact_review_010",
-      "content": "This sample fact is intended for edit testing.",
-      "category": "testing",
-      "confidence": 0.8,
-      "createdAt": "2026-03-28T10:08:00Z",
-      "source": "manual"
-    }
-  ]
-}

backend/docs/middleware-execution-flow.md

@@ -1,291 +0,0 @@
-# Middleware 执行流程
-
-## Middleware 列表
-
-`create_deerflow_agent` 通过 `RuntimeFeatures` 组装的完整 middleware 链（默认全开时）：
-
-| # | Middleware | `before_agent` | `before_model` | `after_model` | `after_agent` | `wrap_tool_call` | 主 Agent | Subagent | 来源 |
-|---|-----------|:-:|:-:|:-:|:-:|:-:|:-:|:-:|------|
-| 0 | ThreadDataMiddleware | ✓ | | | | | ✓ | ✓ | `sandbox` |
-| 1 | UploadsMiddleware | ✓ | | | | | ✓ | ✗ | `sandbox` |
-| 2 | SandboxMiddleware | ✓ | | | ✓ | | ✓ | ✓ | `sandbox` |
-| 3 | DanglingToolCallMiddleware | | | ✓ | | | ✓ | ✗ | 始终开启 |
-| 4 | GuardrailMiddleware | | | | | ✓ | ✓ | ✓ | *Phase 2 纳入* |
-| 5 | ToolErrorHandlingMiddleware | | | | | ✓ | ✓ | ✓ | 始终开启 |
-| 6 | SummarizationMiddleware | | | ✓ | | | ✓ | ✗ | `summarization` |
-| 7 | TodoMiddleware | | | ✓ | | | ✓ | ✗ | `plan_mode` 参数 |
-| 8 | TitleMiddleware | | | ✓ | | | ✓ | ✗ | `auto_title` |
-| 9 | MemoryMiddleware | | | | ✓ | | ✓ | ✗ | `memory` |
-| 10 | ViewImageMiddleware | | ✓ | | | | ✓ | ✗ | `vision` |
-| 11 | SubagentLimitMiddleware | | | ✓ | | | ✓ | ✗ | `subagent` |
-| 12 | LoopDetectionMiddleware | | | ✓ | | | ✓ | ✗ | 始终开启 |
-| 13 | ClarificationMiddleware | | | ✓ | | | ✓ | ✗ | 始终最后 |
-
-主 agent **14 个** middleware（`make_lead_agent`），subagent **4 个**（ThreadData、Sandbox、Guardrail、ToolErrorHandling）。`create_deerflow_agent` Phase 1 实现 **13 个**（Guardrail 仅支持自定义实例，无内置默认）。
-
-## 执行流程
-
-LangChain `create_agent` 的规则：
-- **`before_*` 正序执行**（列表位置 0 → N）
-- **`after_*` 反序执行**（列表位置 N → 0）
-
-```mermaid
-graph TB
-    START(["invoke"]) --> TD
-
-    subgraph BA ["<b>before_agent</b> 正序 0→N"]
-        direction TB
-        TD["[0] ThreadData<br/>创建线程目录"] --> UL["[1] Uploads<br/>扫描上传文件"] --> SB["[2] Sandbox<br/>获取沙箱"]
-    end
-
-    subgraph BM ["<b>before_model</b> 正序 0→N"]
-        direction TB
-        VI["[10] ViewImage<br/>注入图片 base64"]
-    end
-
-    SB --> VI
-    VI --> M["<b>MODEL</b>"]
-
-    subgraph AM ["<b>after_model</b> 反序 N→0"]
-        direction TB
-        CL["[13] Clarification<br/>拦截 ask_clarification"] --> LD["[12] LoopDetection<br/>检测循环"] --> SL["[11] SubagentLimit<br/>截断多余 task"] --> TI["[8] Title<br/>生成标题"] --> SM["[6] Summarization<br/>上下文压缩"] --> DTC["[3] DanglingToolCall<br/>补缺失 ToolMessage"]
-    end
-
-    M --> CL
-
-    subgraph AA ["<b>after_agent</b> 反序 N→0"]
-        direction TB
-        SBR["[2] Sandbox<br/>释放沙箱"] --> MEM["[9] Memory<br/>入队记忆"]
-    end
-
-    DTC --> SBR
-    MEM --> END(["response"])
-
-    classDef beforeNode fill:#a0a8b5,stroke:#636b7a,color:#2d3239
-    classDef modelNode fill:#b5a8a0,stroke:#7a6b63,color:#2d3239
-    classDef afterModelNode fill:#b5a0a8,stroke:#7a636b,color:#2d3239
-    classDef afterAgentNode fill:#a0b5a8,stroke:#637a6b,color:#2d3239
-    classDef terminalNode fill:#a8b5a0,stroke:#6b7a63,color:#2d3239
-
-    class TD,UL,SB,VI beforeNode
-    class M modelNode
-    class CL,LD,SL,TI,SM,DTC afterModelNode
-    class SBR,MEM afterAgentNode
-    class START,END terminalNode
-```
-
-## 时序图
-
-```mermaid
-sequenceDiagram
-    participant U as User
-    participant TD as ThreadDataMiddleware
-    participant UL as UploadsMiddleware
-    participant SB as SandboxMiddleware
-    participant VI as ViewImageMiddleware
-    participant M as MODEL
-    participant CL as ClarificationMiddleware
-    participant SL as SubagentLimitMiddleware
-    participant TI as TitleMiddleware
-    participant SM as SummarizationMiddleware
-    participant DTC as DanglingToolCallMiddleware
-    participant MEM as MemoryMiddleware
-
-    U ->> TD: invoke
-    activate TD
-    Note right of TD: before_agent 创建目录
-
-    TD ->> UL: before_agent
-    activate UL
-    Note right of UL: before_agent 扫描上传文件
-
-    UL ->> SB: before_agent
-    activate SB
-    Note right of SB: before_agent 获取沙箱
-
-    SB ->> VI: before_model
-    activate VI
-    Note right of VI: before_model 注入图片 base64
-
-    VI ->> M: messages + tools
-    activate M
-    M -->> CL: AI response
-    deactivate M
-
-    activate CL
-    Note right of CL: after_model 拦截 ask_clarification
-    CL -->> SL: after_model
-    deactivate CL
-
-    activate SL
-    Note right of SL: after_model 截断多余 task
-    SL -->> TI: after_model
-    deactivate SL
-
-    activate TI
-    Note right of TI: after_model 生成标题
-    TI -->> SM: after_model
-    deactivate TI
-
-    activate SM
-    Note right of SM: after_model 上下文压缩
-    SM -->> DTC: after_model
-    deactivate SM
-
-    activate DTC
-    Note right of DTC: after_model 补缺失 ToolMessage
-    DTC -->> VI: done
-    deactivate DTC
-
-    VI -->> SB: done
-    deactivate VI
-
-    Note right of SB: after_agent 释放沙箱
-    SB -->> UL: done
-    deactivate SB
-
-    UL -->> TD: done
-    deactivate UL
-
-    Note right of MEM: after_agent 入队记忆
-
-    TD -->> U: response
-    deactivate TD
-```
-
-## 洋葱模型
-
-列表位置决定在洋葱中的层级 — 位置 0 最外层，位置 N 最内层：
-
-```
-进入 before_*：   [0] → [1] → [2] → ... → [10] → MODEL
-退出 after_*：    MODEL → [13] → [11] → ... → [6] → [3] → [2] → [0]
-                          ↑ 最内层最先执行
-```
-
-> [!important] 核心规则
-> 列表最后的 middleware，其 `after_model` **最先执行**。
-> ClarificationMiddleware 在列表末尾，所以它第一个拦截 model 输出。
-
-## 对比：真正的洋葱 vs DeerFlow 的实际情况
-
-### 真正的洋葱（如 Koa/Express）
-
-每个 middleware 同时负责 before 和 after，形成对称嵌套：
-
-```mermaid
-sequenceDiagram
-    participant U as User
-    participant A as AuthMiddleware
-    participant L as LogMiddleware
-    participant R as RateLimitMiddleware
-    participant H as Handler
-
-    U ->> A: request
-    activate A
-    Note right of A: before: 校验 token
-
-    A ->> L: next()
-    activate L
-    Note right of L: before: 记录请求时间
-
-    L ->> R: next()
-    activate R
-    Note right of R: before: 检查频率
-
-    R ->> H: next()
-    activate H
-    H -->> R: result
-    deactivate H
-
-    Note right of R: after: 更新计数器
-    R -->> L: result
-    deactivate R
-
-    Note right of L: after: 记录耗时
-    L -->> A: result
-    deactivate L
-
-    Note right of A: after: 清理上下文
-    A -->> U: response
-    deactivate A
-```
-
-> [!tip] 洋葱特征
-> 每个 middleware 都有 before/after 对称操作，`activate` 跨越整个内层执行，形成完美嵌套。
-
-### DeerFlow 的实际情况
-
-不是洋葱，是管道。大部分 middleware 只用一个钩子，不存在对称嵌套。多轮对话时 before_model / after_model 循环执行：
-
-```mermaid
-sequenceDiagram
-    participant U as User
-    participant TD as ThreadData
-    participant UL as Uploads
-    participant SB as Sandbox
-    participant VI as ViewImage
-    participant M as MODEL
-    participant CL as Clarification
-    participant SL as SubagentLimit
-    participant TI as Title
-    participant SM as Summarization
-    participant MEM as Memory
-
-    U ->> TD: invoke
-    Note right of TD: before_agent 创建目录
-    TD ->> UL: .
-    Note right of UL: before_agent 扫描文件
-    UL ->> SB: .
-    Note right of SB: before_agent 获取沙箱
-
-    loop 每轮对话（tool call 循环）
-        SB ->> VI: .
-        Note right of VI: before_model 注入图片
-        VI ->> M: messages + tools
-        M -->> CL: AI response
-        Note right of CL: after_model 拦截 ask_clarification
-        CL -->> SL: .
-        Note right of SL: after_model 截断多余 task
-        SL -->> TI: .
-        Note right of TI: after_model 生成标题
-        TI -->> SM: .
-        Note right of SM: after_model 上下文压缩
-    end
-
-    Note right of SB: after_agent 释放沙箱
-    SB -->> MEM: .
-    Note right of MEM: after_agent 入队记忆
-    MEM -->> U: response
-```
-
-> [!warning] 不是洋葱
-> 14 个 middleware 中只有 SandboxMiddleware 有 before/after 对称（获取/释放）。其余都是单向的：要么只在 `before_*` 做事，要么只在 `after_*` 做事。`before_agent` / `after_agent` 只跑一次，`before_model` / `after_model` 每轮循环都跑。
-
-硬依赖只有 2 处：
-
-1. **ThreadData 在 Sandbox 之前** — sandbox 需要线程目录
-2. **Clarification 在列表最后** — `after_model` 反序时最先执行，第一个拦截 `ask_clarification`
-
-### 结论
-
-| | 真正的洋葱 | DeerFlow 实际 |
-|---|---|---|
-| 每个 middleware | before + after 对称 | 大多只用一个钩子 |
-| 激活条 | 嵌套（外长内短） | 不嵌套（串行） |
-| 反序的意义 | 清理与初始化配对 | 仅影响 after_model 的执行优先级 |
-| 典型例子 | Auth: 校验 token / 清理上下文 | ThreadData: 只创建目录，没有清理 |
-
-## 关键设计点
-
-### ClarificationMiddleware 为什么在列表最后？
-
-位置最后 = `after_model` 最先执行。它需要**第一个**看到 model 输出，检查是否有 `ask_clarification` tool call。如果有，立即中断（`Command(goto=END)`），后续 middleware 的 `after_model` 不再执行。
-
-### SandboxMiddleware 的对称性
-
-`before_agent`（正序第 3 个）获取沙箱，`after_agent`（反序第 1 个）释放沙箱。外层进入 → 外层退出，天然的洋葱对称。
-
-### 大部分 middleware 只用一个钩子
-
-14 个 middleware 中，只有 SandboxMiddleware 同时用了 `before_agent` + `after_agent`（获取/释放）。其余都只在一个阶段执行。洋葱模型的反序特性主要影响 `after_model` 阶段的执行顺序。

backend/docs/plan_mode_usage.md

@@ -19,7 +19,7 @@ Plan mode is controlled via **runtime configuration** through the `is_plan_mode`
 
 ```python
 from langchain_core.runnables import RunnableConfig
-from deerflow.agents.lead_agent.agent import make_lead_agent
+from src.agents.lead_agent.agent import make_lead_agent
 
 # Enable plan mode via runtime configuration
 config = RunnableConfig(
@@ -72,7 +72,7 @@ The agent will skip using the todo list for:
 
 ```python
 from langchain_core.runnables import RunnableConfig
-from deerflow.agents.lead_agent.agent import make_lead_agent
+from src.agents.lead_agent.agent import make_lead_agent
 
 # Create agent with plan mode ENABLED
 config_with_plan_mode = RunnableConfig(
@@ -101,7 +101,7 @@ You can enable/disable plan mode dynamically for different conversations or task
 
 ```python
 from langchain_core.runnables import RunnableConfig
-from deerflow.agents.lead_agent.agent import make_lead_agent
+from src.agents.lead_agent.agent import make_lead_agent
 
 def create_agent_for_task(task_complexity: str):
     """Create agent with plan mode based on task complexity."""
@@ -154,7 +154,7 @@ make_lead_agent(config)
 ## Implementation Details
 
 ### Agent Module
-- **Location**: `packages/harness/deerflow/agents/lead_agent/agent.py`
+- **Location**: `src/agents/lead_agent/agent.py`
 - **Function**: `_create_todo_list_middleware(is_plan_mode: bool)` - Creates TodoListMiddleware if plan mode is enabled
 - **Function**: `_build_middlewares(config: RunnableConfig)` - Builds middleware chain based on runtime config
 - **Function**: `make_lead_agent(config: RunnableConfig)` - Creates agent with appropriate middlewares
@@ -194,7 +194,7 @@ DeerFlow uses custom `system_prompt` and `tool_description` for the TodoListMidd
 - Comprehensive best practices section
 - Task completion requirements to prevent premature marking
 
-The custom prompts are defined in `_create_todo_list_middleware()` in `/Users/hetao/workspace/deer-flow/backend/packages/harness/deerflow/agents/lead_agent/agent.py:57`.
+The custom prompts are defined in `_create_todo_list_middleware()` in `/Users/hetao/workspace/deer-flow/backend/src/agents/lead_agent/agent.py:57`.
 
 ## Notes
 

backend/docs/rfc-create-deerflow-agent.md

@@ -1,503 +0,0 @@
-# RFC: `create_deerflow_agent` — 纯参数的 SDK 工厂 API
-
-## 1. 问题
-
-当前 harness 的唯一公开入口是 `make_lead_agent(config: RunnableConfig)`。它内部：
-
-```
-make_lead_agent
-  ├─ get_app_config()          ← 读 config.yaml
-  ├─ _resolve_model_name()     ← 读 config.yaml
-  ├─ load_agent_config()       ← 读 agents/{name}/config.yaml
-  ├─ create_chat_model(name)   ← 读 config.yaml（反射加载 model class）
-  ├─ get_available_tools()     ← 读 config.yaml + extensions_config.json
-  ├─ apply_prompt_template()   ← 读 skills 目录 + memory.json
-  └─ _build_middlewares()      ← 读 config.yaml（summarization、model vision）
-```
-
-**6 处隐式 I/O** — 全部依赖文件系统。如果你想把 `deerflow-harness` 当 Python 库嵌入自己的应用，你必须准备 `config.yaml` + `extensions_config.json` + skills 目录。这对 SDK 用户是不可接受的。
-
-### 对比
-
-| | `langchain.create_agent` | `make_lead_agent` | `DeerFlowClient`（增强后） |
-|---|---|---|---|
-| 定位 | 底层原语 | 内部工厂 | **唯一公开 API** |
-| 配置来源 | 纯参数 | YAML 文件 | **参数优先，config fallback** |
-| 内置能力 | 无 | Sandbox/Memory/Skills/Subagent/... | **按需组合 + 管理 API** |
-| 用户接口 | `graph.invoke(state)` | 内部使用 | **`client.chat("hello")`** |
-| 适合谁 | 写 LangChain 的人 | 内部使用 | **所有 DeerFlow 用户** |
-
-## 2. 设计原则
-
-### Python 中的 DI 最佳实践
-
-1. **函数参数即注入** — 不读全局状态，所有依赖通过参数传入
-2. **Protocol 定义契约** — 不依赖具体类，依赖行为接口
-3. **合理默认值** — `sandbox=True` 等价于 `sandbox=LocalSandboxProvider()`
-4. **分层 API** — 简单用法一行搞定，复杂用法有逃生舱
-
-### 分层架构
-
-```
-    ┌──────────────────────┐
-    │   DeerFlowClient     │  ← 唯一公开 API（chat/stream + 管理）
-    └──────────┬───────────┘
-    ┌──────────▼───────────┐
-    │   make_lead_agent    │  ← 内部：配置驱动工厂
-    └──────────┬───────────┘
-    ┌──────────▼───────────┐
-    │  create_deerflow_agent   │  ← 内部：纯参数工厂
-    └──────────┬───────────┘
-    ┌──────────▼───────────┐
-    │ langchain.create_agent│  ← 底层原语
-    └──────────────────────┘
-```
-
-`DeerFlowClient` 是唯一公开 API。`create_deerflow_agent` 和 `make_lead_agent` 都是内部实现。
-
-用户通过 `DeerFlowClient` 三个参数控制行为：
-
-| 参数 | 类型 | 职责 |
-|------|------|------|
-| `config` | `dict` | 覆盖 config.yaml 的任意配置项 |
-| `features` | `RuntimeFeatures` | 替换内置 middleware 实现 |
-| `extra_middleware` | `list[AgentMiddleware]` | 新增用户 middleware |
-
-不传参数 → 读 config.yaml（现有行为，完全兼容）。
-
-### 核心约束
-
-- **配置覆盖** — `config` dict > config.yaml > 默认值
-- **三层不重叠** — config 传参数，features 传实例，extra_middleware 传新增
-- **向前兼容** — 现有 `DeerFlowClient()` 无参构造行为不变
-- **harness 边界合规** — 不 import `app.*`（`test_harness_boundary.py` 强制）
-
-## 3. API 设计
-
-### 3.1 `DeerFlowClient` — 唯一公开 API
-
-在现有构造函数上增加三个可选参数：
-
-```python
-from deerflow.client import DeerFlowClient
-from deerflow.agents.features import RuntimeFeatures
-
-client = DeerFlowClient(
-    # 1. config — 覆盖 config.yaml 的任意 key（结构和 yaml 一致）
-    config={
-        "models": [{"name": "gpt-4o", "use": "langchain_openai:ChatOpenAI", "model": "gpt-4o", "api_key": "sk-..."}],
-        "memory": {"max_facts": 50, "enabled": True},
-        "title": {"enabled": False},
-        "summarization": {"enabled": True, "trigger": [{"type": "tokens", "value": 10000}]},
-        "sandbox": {"use": "deerflow.sandbox.local:LocalSandboxProvider"},
-    },
-
-    # 2. features — 替换内置 middleware 实现
-    features=RuntimeFeatures(
-        memory=MyMemoryMiddleware(),
-        auto_title=MyTitleMiddleware(),
-    ),
-
-    # 3. extra_middleware — 新增用户 middleware
-    extra_middleware=[
-        MyAuditMiddleware(),       # @Next(SandboxMiddleware)
-        MyFilterMiddleware(),      # @Prev(ClarificationMiddleware)
-    ],
-)
-```
-
-三种典型用法：
-
-```python
-# 用法 1：全读 config.yaml（现有行为，不变）
-client = DeerFlowClient()
-
-# 用法 2：只改参数，不换实现
-client = DeerFlowClient(config={"memory": {"max_facts": 50}})
-
-# 用法 3：替换 middleware 实现
-client = DeerFlowClient(features=RuntimeFeatures(auto_title=MyTitleMiddleware()))
-
-# 用法 4：添加自定义 middleware
-client = DeerFlowClient(extra_middleware=[MyAuditMiddleware()])
-
-# 用法 5：纯 SDK（无 config.yaml）
-client = DeerFlowClient(config={
-    "models": [{"name": "gpt-4o", "use": "langchain_openai:ChatOpenAI", ...}],
-    "tools": [{"name": "bash", "use": "deerflow.sandbox.tools:bash_tool", "group": "bash"}],
-    "memory": {"enabled": True},
-})
-```
-
-内部实现：`final_config = deep_merge(file_config, code_config)`
-
-### 3.2 `create_deerflow_agent` — 内部工厂（不公开）
-
-```python
-def create_deerflow_agent(
-    model: BaseChatModel,
-    tools: list[BaseTool] | None = None,
-    *,
-    system_prompt: str | None = None,
-    middleware: list[AgentMiddleware] | None = None,
-    features: RuntimeFeatures | None = None,
-    state_schema: type | None = None,
-    checkpointer: BaseCheckpointSaver | None = None,
-    name: str = "default",
-) -> CompiledStateGraph:
-    ...
-```
-
-`DeerFlowClient` 内部调用此函数。
-
-### 3.3 `RuntimeFeatures` — 内置 Middleware 替换
-
-只做一件事：用自定义实例替换内置 middleware。不管配置参数（参数走 `config` dict）。
-
-```python
-@dataclass
-class RuntimeFeatures:
-    sandbox: bool | AgentMiddleware = True
-    memory: bool | AgentMiddleware = False
-    summarization: bool | AgentMiddleware = False
-    subagent: bool | AgentMiddleware = False
-    vision: bool | AgentMiddleware = False
-    auto_title: bool | AgentMiddleware = False
-```
-
-| 值 | 含义 |
-|---|---|
-| `True` | 使用默认 middleware（参数从 config 读） |
-| `False` | 关闭该功能 |
-| `AgentMiddleware` 实例 | 替换整个实现 |
-
-不再有 `MemoryOptions`、`TitleOptions` 等。参数调整走 `config` dict：
-
-```python
-# 改 memory 参数 → config
-client = DeerFlowClient(config={"memory": {"max_facts": 50}})
-
-# 换 memory 实现 → features
-client = DeerFlowClient(features=RuntimeFeatures(memory=MyMemoryMiddleware()))
-
-# 两者组合 — config 参数给默认 middleware，但 title 换实现
-client = DeerFlowClient(
-    config={"memory": {"max_facts": 50}},
-    features=RuntimeFeatures(auto_title=MyTitleMiddleware()),
-)
-```
-
-### 3.4 Middleware 链组装
-
-不使用 priority 数字排序。按固定顺序 append 构建列表：
-
-```python
-def _resolve(spec, default_cls):
-    """bool → 默认实现 / AgentMiddleware → 替换"""
-    if isinstance(spec, AgentMiddleware):
-        return spec
-    return default_cls()
-
-def _assemble_from_features(feat: RuntimeFeatures, config: AppConfig) -> tuple[list, list]:
-    chain = []
-    extra_tools = []
-
-    if feat.sandbox:
-        chain.append(_resolve(feat.sandbox, ThreadDataMiddleware))
-        chain.append(UploadsMiddleware())
-        chain.append(_resolve(feat.sandbox, SandboxMiddleware))
-
-    chain.append(DanglingToolCallMiddleware())
-    chain.append(ToolErrorHandlingMiddleware())
-
-    if feat.summarization:
-        chain.append(_resolve(feat.summarization, SummarizationMiddleware))
-    if config.title.enabled and feat.auto_title is not False:
-        chain.append(_resolve(feat.auto_title, TitleMiddleware))
-    if feat.memory:
-        chain.append(_resolve(feat.memory, MemoryMiddleware))
-    if feat.vision:
-        chain.append(ViewImageMiddleware())
-        extra_tools.append(view_image_tool)
-    if feat.subagent:
-        chain.append(_resolve(feat.subagent, SubagentLimitMiddleware))
-        extra_tools.append(task_tool)
-    if feat.loop_detection:
-        chain.append(_resolve(feat.loop_detection, LoopDetectionMiddleware))
-
-    # 插入 extra_middleware（按 @Next/@Prev 声明定位）
-    _insert_extra(chain, extra_middleware)
-
-    # Clarification 永远最后
-    chain.append(ClarificationMiddleware())
-    extra_tools.append(ask_clarification_tool)
-
-    return chain, extra_tools
-```
-
-### 3.6 Middleware 排序策略
-
-**两阶段排序：内置固定 + 外置插入**
-
-1. **内置链固定顺序** — 按代码中的 append 顺序确定，不参与 @Next/@Prev
-2. **外置 middleware 插入** — `extra_middleware` 中的 middleware 通过 @Next/@Prev 声明锚点，自由锚定任意 middleware（内置或其他外置均可）
-3. **冲突检测** — 两个外置 middleware 如果 @Next 或 @Prev 同一个目标 → `ValueError`
-
-**这不是全排序。** 内置链的顺序在代码中已确定，外置 middleware 只做插入操作。这样可以避免内置和外置同时竞争同一个位置的问题。
-
-### 3.7 `@Next` / `@Prev` 装饰器
-
-用户自定义 middleware 通过装饰器声明在链中的位置，类型安全：
-
-```python
-from deerflow.agents import Next, Prev
-
-@Next(SandboxMiddleware)
-class MyAuditMiddleware(AgentMiddleware):
-    """排在 SandboxMiddleware 后面"""
-    def before_agent(self, state, runtime):
-        ...
-
-@Prev(ClarificationMiddleware)
-class MyFilterMiddleware(AgentMiddleware):
-    """排在 ClarificationMiddleware 前面"""
-    def after_model(self, state, runtime):
-        ...
-```
-
-实现：
-
-```python
-def Next(anchor: type[AgentMiddleware]):
-    """装饰器：声明本 middleware 排在 anchor 的下一个位置。"""
-    def decorator(cls: type[AgentMiddleware]) -> type[AgentMiddleware]:
-        cls._next_anchor = anchor
-        return cls
-    return decorator
-
-def Prev(anchor: type[AgentMiddleware]):
-    """装饰器：声明本 middleware 排在 anchor 的前一个位置。"""
-    def decorator(cls: type[AgentMiddleware]) -> type[AgentMiddleware]:
-        cls._prev_anchor = anchor
-        return cls
-    return decorator
-```
-
-`_insert_extra` 算法：
-
-1. 遍历 `extra_middleware`，读取每个 middleware 的 `_next_anchor` / `_prev_anchor`
-2. **冲突检测**：如果两个外置 middleware 的锚点相同（同方向同目标），抛出 `ValueError`
-3. 有锚点的 middleware 插入到目标位置（@Next → 目标之后，@Prev → 目标之前）
-4. 无声明的 middleware 追加到 Clarification 之前
-
-## 4. Middleware 执行模型
-
-### LangChain 的执行规则
-
-```
-before_agent 正序 →  [0] → [1] → ... → [N]
-before_model 正序 →  [0] → [1] → ... → [N]  ← 每轮循环
-         MODEL
-after_model 反序 ←   [N] → [N-1] → ... → [0]  ← 每轮循环
-after_agent 反序 ←   [N] → [N-1] → ... → [0]
-```
-
-`before_agent` / `after_agent` 只跑一次。`before_model` / `after_model` 每轮 tool call 循环都跑。
-
-### DeerFlow 的实际情况
-
-**不是洋葱，是管道。** 11 个 middleware 中只有 SandboxMiddleware 有 before/after 对称（获取/释放），其余只用一个钩子。
-
-硬依赖只有 2 处：
-1. **ThreadData 在 Sandbox 之前** — sandbox 需要线程目录
-2. **Clarification 在列表最后** — after_model 反序时最先执行，第一个拦截 `ask_clarification`
-
-详见 [middleware-execution-flow.md](middleware-execution-flow.md)。
-
-## 5. 使用示例
-
-### 5.1 全读 config.yaml（现有行为不变）
-
-```python
-from deerflow.client import DeerFlowClient
-
-client = DeerFlowClient()
-response = client.chat("Hello")
-```
-
-### 5.2 覆盖配置参数
-
-```python
-client = DeerFlowClient(config={
-    "memory": {"max_facts": 50},
-    "title": {"enabled": False},
-    "summarization": {"trigger": [{"type": "tokens", "value": 10000}]},
-})
-```
-
-### 5.3 纯 SDK（无 config.yaml）
-
-```python
-client = DeerFlowClient(config={
-    "models": [{"name": "gpt-4o", "use": "langchain_openai:ChatOpenAI", "model": "gpt-4o", "api_key": "sk-..."}],
-    "tools": [
-        {"name": "bash", "group": "bash", "use": "deerflow.sandbox.tools:bash_tool"},
-        {"name": "web_search", "group": "web", "use": "deerflow.community.tavily.tools:web_search_tool"},
-    ],
-    "memory": {"enabled": True, "max_facts": 50},
-    "sandbox": {"use": "deerflow.sandbox.local:LocalSandboxProvider"},
-})
-```
-
-### 5.4 替换内置 middleware
-
-```python
-from deerflow.agents.features import RuntimeFeatures
-
-client = DeerFlowClient(
-    features=RuntimeFeatures(
-        memory=MyMemoryMiddleware(),       # 替换
-        auto_title=MyTitleMiddleware(),    # 替换
-        vision=False,                      # 关闭
-    ),
-)
-```
-
-### 5.5 插入自定义 middleware
-
-```python
-from deerflow.agents import Next, Prev
-from deerflow.sandbox.middleware import SandboxMiddleware
-from deerflow.agents.middlewares.clarification_middleware import ClarificationMiddleware
-
-@Next(SandboxMiddleware)
-class MyAuditMiddleware(AgentMiddleware):
-    def before_agent(self, state, runtime):
-        log_sandbox_acquired(state)
-
-@Prev(ClarificationMiddleware)
-class MyFilterMiddleware(AgentMiddleware):
-    def after_model(self, state, runtime):
-        filter_sensitive_output(state)
-
-client = DeerFlowClient(
-    extra_middleware=[MyAuditMiddleware(), MyFilterMiddleware()],
-)
-```
-
-## 6. Phase 1 限制
-
-当前实现中以下 middleware 内部仍读 `config.yaml`，SDK 用户需注意：
-
-| Middleware | 读取内容 | Phase 2 解决方案 |
-|------------|---------|-----------------|
-| TitleMiddleware | `get_title_config()` + `create_chat_model()` | `TitleOptions(model=...)` 参数覆盖 |
-| MemoryMiddleware | `get_memory_config()` | `MemoryOptions(...)` 参数覆盖 |
-| SandboxMiddleware | `get_sandbox_provider()` | `SandboxProvider` 实例直传 |
-
-Phase 1 中 `auto_title` 默认为 `False` 以避免无 config 时崩溃。其他有 config 依赖的 feature 默认也为 `False`。
-
-## 7. 迁移路径
-
-```
-Phase 1（当前 PR #1203）:
-  ✓ 新增 create_deerflow_agent + RuntimeFeatures（内部 API）
-  ✓ 不改 DeerFlowClient 和 make_lead_agent
-  ✗ middleware 内部仍读 config（已知限制）
-
-Phase 2（#1380）:
-  - DeerFlowClient 构造函数增加可选参数（model, tools, features, system_prompt）
-  - Options 参数覆盖 config（MemoryOptions, TitleOptions 等）
-  - @Next/@Prev 装饰器
-  - 补缺失 middleware（Guardrail, TokenUsage, DeferredToolFilter）
-  - make_lead_agent 改为薄壳调 create_deerflow_agent
-
-Phase 3:
-  - SDK 文档和示例
-  - deerflow.client 稳定 API
-```
-
-## 8. 设计决议
-
-| 问题 | 决议 | 理由 |
-|------|------|------|
-| 公开 API | `DeerFlowClient` 唯一入口 | 自顶向下，先改现有 API 再抽底层 |
-| create_deerflow_agent | 内部实现，不公开 | 用户不需要接触 CompiledStateGraph |
-| 配置覆盖 | `config` dict，和 config.yaml 结构一致 | 无新概念，deep merge 覆盖 |
-| middleware 替换 | `features=RuntimeFeatures(memory=MyMW())` | bool 开关 + 实例替换 |
-| middleware 扩展 | `extra_middleware` 独立参数 | 和内置 features 分开 |
-| middleware 定位 | `@Next/@Prev` 装饰器 | 类型安全，不暴露排序细节 |
-| 排序机制 | 顺序 append + @Next/@Prev | priority 数字无功能意义 |
-| 运行时开关 | 保留 `RunnableConfig` | plan_mode、thread_id 等按请求切换 |
-
-## 9. 附录：Middleware 链
-
-```mermaid
-graph TB
-    subgraph BA ["before_agent 正序"]
-        direction TB
-        TD["ThreadData<br/>创建目录"] --> UL["Uploads<br/>扫描文件"] --> SB["Sandbox<br/>获取沙箱"]
-    end
-
-    subgraph BM ["before_model 正序 每轮"]
-        direction TB
-        VI["ViewImage<br/>注入图片"]
-    end
-
-    SB --> VI
-    VI --> M["MODEL"]
-
-    subgraph AM ["after_model 反序 每轮"]
-        direction TB
-        CL["Clarification<br/>拦截中断"] --> LD["LoopDetection<br/>检测循环"] --> SL["SubagentLimit<br/>截断 task"] --> TI["Title<br/>生成标题"] --> DTC["DanglingToolCall<br/>补缺失消息"]
-    end
-
-    M --> CL
-
-    subgraph AA ["after_agent 反序"]
-        direction TB
-        SBR["Sandbox<br/>释放沙箱"] --> MEM["Memory<br/>入队记忆"]
-    end
-
-    DTC --> SBR
-
-    classDef beforeNode fill:#a0a8b5,stroke:#636b7a,color:#2d3239
-    classDef modelNode fill:#b5a8a0,stroke:#7a6b63,color:#2d3239
-    classDef afterModelNode fill:#b5a0a8,stroke:#7a636b,color:#2d3239
-    classDef afterAgentNode fill:#a0b5a8,stroke:#637a6b,color:#2d3239
-
-    class TD,UL,SB,VI beforeNode
-    class M modelNode
-    class CL,LD,SL,TI,DTC afterModelNode
-    class SBR,MEM afterAgentNode
-```
-
-硬依赖：
-- ThreadData → Uploads → Sandbox（before_agent 阶段）
-- Clarification 必须在列表最后（after_model 反序时最先执行）
-
-## 10. 主 Agent 与 Subagent 的 Middleware 差异
-
-主 agent 和 subagent 共享基础 middleware 链（`_build_runtime_middlewares`），subagent 在此基础上做精简：
-
-| Middleware | 主 Agent | Subagent | 说明 |
-|------------|:-------:|:--------:|------|
-| ThreadDataMiddleware | ✓ | ✓ | 共享：创建线程目录 |
-| UploadsMiddleware | ✓ | ✗ | 主 agent 独有：扫描上传文件 |
-| SandboxMiddleware | ✓ | ✓ | 共享：获取/释放沙箱 |
-| DanglingToolCallMiddleware | ✓ | ✗ | 主 agent 独有：补缺失 ToolMessage |
-| GuardrailMiddleware | ✓ | ✓ | 共享：工具调用授权（可选） |
-| ToolErrorHandlingMiddleware | ✓ | ✓ | 共享：工具异常处理 |
-| SummarizationMiddleware | ✓ | ✗ | |
-| TodoMiddleware | ✓ | ✗ | |
-| TitleMiddleware | ✓ | ✗ | |
-| MemoryMiddleware | ✓ | ✗ | |
-| ViewImageMiddleware | ✓ | ✗ | |
-| SubagentLimitMiddleware | ✓ | ✗ | |
-| LoopDetectionMiddleware | ✓ | ✗ | |
-| ClarificationMiddleware | ✓ | ✗ | |
-
-**设计原则**：
-- `RuntimeFeatures`、`@Next/@Prev`、排序机制只作用于**主 agent**
-- Subagent 链短且固定（4 个），不需要动态组装
-- `extra_middleware` 当前只影响主 agent，不传递给 subagent

backend/docs/rfc-extract-shared-modules.md

@@ -1,190 +0,0 @@
-# RFC: Extract Shared Skill Installer and Upload Manager into Harness
-
-## 1. Problem
-
-Gateway (`app/gateway/routers/skills.py`, `uploads.py`) and Client (`deerflow/client.py`) each independently implement the same business logic:
-
-### Skill Installation
-
-| Logic | Gateway (`skills.py`) | Client (`client.py`) |
-|-------|----------------------|---------------------|
-| Zip safety check | `_is_unsafe_zip_member()` | Inline `Path(info.filename).is_absolute()` |
-| Symlink filtering | `_is_symlink_member()` | `p.is_symlink()` post-extraction delete |
-| Zip bomb defence | `total_size += info.file_size` (declared) | `total_size > 100MB` (declared) |
-| macOS metadata filter | `_should_ignore_archive_entry()` | None |
-| Frontmatter validation | `_validate_skill_frontmatter()` | `_validate_skill_frontmatter()` |
-| Duplicate detection | `HTTPException(409)` | `ValueError` |
-
-**Two implementations, inconsistent behaviour**: Gateway streams writes and tracks real decompressed size; Client sums declared `file_size`. Gateway skips symlinks during extraction; Client extracts everything then walks and deletes symlinks.
-
-### Upload Management
-
-| Logic | Gateway (`uploads.py`) | Client (`client.py`) |
-|-------|----------------------|---------------------|
-| Directory access | `get_uploads_dir()` + `mkdir` | `_get_uploads_dir()` + `mkdir` |
-| Filename safety | Inline `Path(f).name` + manual checks | No checks, uses `src_path.name` directly |
-| Duplicate handling | None (overwrites) | None (overwrites) |
-| Listing | Inline `iterdir()` | Inline `os.scandir()` |
-| Deletion | Inline `unlink()` + traversal check | Inline `unlink()` + traversal check |
-| Path traversal | `resolve().relative_to()` | `resolve().relative_to()` |
-
-**The same traversal check is written twice** — any security fix must be applied to both locations.
-
-## 2. Design Principles
-
-### Dependency Direction
-
-```
-app.gateway.routers.skills  ──┐
-app.gateway.routers.uploads ──┤── calls ──→  deerflow.skills.installer
-deerflow.client             ──┘              deerflow.uploads.manager
-```
-
-- Shared modules live in the harness layer (`deerflow.*`), pure business logic, no FastAPI dependency
-- Gateway handles HTTP adaptation (`UploadFile` → bytes, exceptions → `HTTPException`)
-- Client handles local adaptation (`Path` → copy, exceptions → Python exceptions)
-- Satisfies `test_harness_boundary.py` constraint: harness never imports app
-
-### Exception Strategy
-
-| Shared Layer Exception | Gateway Maps To | Client |
-|----------------------|-----------------|--------|
-| `FileNotFoundError` | `HTTPException(404)` | Propagates |
-| `ValueError` | `HTTPException(400)` | Propagates |
-| `SkillAlreadyExistsError` | `HTTPException(409)` | Propagates |
-| `PermissionError` | `HTTPException(403)` | Propagates |
-
-Replaces stringly-typed routing (`"already exists" in str(e)`) with typed exception matching (`SkillAlreadyExistsError`).
-
-## 3. New Modules
-
-### 3.1 `deerflow.skills.installer`
-
-```python
-# Safety checks
-is_unsafe_zip_member(info: ZipInfo) -> bool     # Absolute path / .. traversal
-is_symlink_member(info: ZipInfo) -> bool         # Unix symlink detection
-should_ignore_archive_entry(path: Path) -> bool  # __MACOSX / dotfiles
-
-# Extraction
-safe_extract_skill_archive(zip_ref, dest_path, max_total_size=512MB)
-  # Streaming write, accumulates real bytes (vs declared file_size)
-  # Dual traversal check: member-level + resolve-level
-
-# Directory resolution
-resolve_skill_dir_from_archive(temp_path: Path) -> Path
-  # Auto-enters single directory, filters macOS metadata
-
-# Install entry point
-install_skill_from_archive(zip_path, *, skills_root=None) -> dict
-  # is_file() pre-check before extension validation
-  # SkillAlreadyExistsError replaces ValueError
-
-# Exception
-class SkillAlreadyExistsError(ValueError)
-```
-
-### 3.2 `deerflow.uploads.manager`
-
-```python
-# Directory management
-get_uploads_dir(thread_id: str) -> Path      # Pure path, no side effects
-ensure_uploads_dir(thread_id: str) -> Path   # Creates directory (for write paths)
-
-# Filename safety
-normalize_filename(filename: str) -> str
-  # Path.name extraction + rejects ".." / "." / backslash / >255 bytes
-deduplicate_filename(name: str, seen: set) -> str
-  # _N suffix increment for dedup, mutates seen in place
-
-# Path safety
-validate_path_traversal(path: Path, base: Path) -> None
-  # resolve().relative_to(), raises PermissionError on failure
-
-# File operations
-list_files_in_dir(directory: Path) -> dict
-  # scandir with stat inside context (no re-stat)
-  # follow_symlinks=False to prevent metadata leakage
-  # Non-existent directory returns empty list
-delete_file_safe(base_dir: Path, filename: str) -> dict
-  # Validates traversal first, then unlinks
-
-# URL helpers
-upload_artifact_url(thread_id, filename) -> str   # Percent-encoded for HTTP safety
-upload_virtual_path(filename) -> str               # Sandbox-internal path
-enrich_file_listing(result, thread_id) -> dict     # Adds URLs, stringifies sizes
-```
-
-## 4. Changes
-
-### 4.1 Gateway Slimming
-
-**`app/gateway/routers/skills.py`**:
-- Remove `_is_unsafe_zip_member`, `_is_symlink_member`, `_safe_extract_skill_archive`, `_should_ignore_archive_entry`, `_resolve_skill_dir_from_archive_root` (~80 lines)
-- `install_skill` route becomes a single call to `install_skill_from_archive(path)`
-- Exception mapping: `SkillAlreadyExistsError → 409`, `ValueError → 400`, `FileNotFoundError → 404`
-
-**`app/gateway/routers/uploads.py`**:
-- Remove inline `get_uploads_dir` (replaced by `ensure_uploads_dir`/`get_uploads_dir`)
-- `upload_files` uses `normalize_filename()` instead of inline safety checks
-- `list_uploaded_files` uses `list_files_in_dir()` + enrichment
-- `delete_uploaded_file` uses `delete_file_safe()` + companion markdown cleanup
-
-### 4.2 Client Slimming
-
-**`deerflow/client.py`**:
-- Remove `_get_uploads_dir` static method
-- Remove ~50 lines of inline zip handling in `install_skill`
-- `install_skill` delegates to `install_skill_from_archive()`
-- `upload_files` uses `deduplicate_filename()` + `ensure_uploads_dir()`
-- `list_uploads` uses `get_uploads_dir()` + `list_files_in_dir()`
-- `delete_upload` uses `get_uploads_dir()` + `delete_file_safe()`
-- `update_mcp_config` / `update_skill` now reset `_agent_config_key = None`
-
-### 4.3 Read/Write Path Separation
-
-| Operation | Function | Creates dir? |
-|-----------|----------|:------------:|
-| upload (write) | `ensure_uploads_dir()` | Yes |
-| list (read) | `get_uploads_dir()` | No |
-| delete (read) | `get_uploads_dir()` | No |
-
-Read paths no longer have `mkdir` side effects — non-existent directories return empty lists.
-
-## 5. Security Improvements
-
-| Improvement | Before | After |
-|-------------|--------|-------|
-| Zip bomb detection | Sum of declared `file_size` | Streaming write, accumulates real bytes |
-| Symlink handling | Gateway skips / Client deletes post-extract | Unified skip + log |
-| Traversal check | Member-level only | Member-level + `resolve().is_relative_to()` |
-| Filename backslash | Gateway checks / Client doesn't | Unified rejection |
-| Filename length | No check | Reject > 255 bytes (OS limit) |
-| thread_id validation | None | Reject unsafe filesystem characters |
-| Listing symlink leak | `follow_symlinks=True` (default) | `follow_symlinks=False` |
-| 409 status routing | `"already exists" in str(e)` | `SkillAlreadyExistsError` type match |
-| Artifact URL encoding | Raw filename in URL | `urllib.parse.quote()` |
-
-## 6. Alternatives Considered
-
-| Alternative | Why Not |
-|-------------|---------|
-| Keep logic in Gateway, Client calls Gateway via HTTP | Adds network dependency to embedded Client; defeats the purpose of `DeerFlowClient` as an in-process API |
-| Abstract base class with Gateway/Client subclasses | Over-engineered for what are pure functions; no polymorphism needed |
-| Move everything into `client.py` and have Gateway import it | Violates harness/app boundary — Client is in harness, but Gateway-specific models (Pydantic response types) should stay in app layer |
-| Merge Gateway and Client into one module | They serve different consumers (HTTP vs in-process) with different adaptation needs |
-
-## 7. Breaking Changes
-
-**None.** All public APIs (Gateway HTTP endpoints, `DeerFlowClient` methods) retain their existing signatures and return formats. The `SkillAlreadyExistsError` is a subclass of `ValueError`, so existing `except ValueError` handlers still catch it.
-
-## 8. Tests
-
-| Module | Test File | Count |
-|--------|-----------|:-----:|
-| `skills.installer` | `tests/test_skills_installer.py` | 22 |
-| `uploads.manager` | `tests/test_uploads_manager.py` | 20 |
-| `client` hardening | `tests/test_client.py` (new cases) | ~40 |
-| `client` e2e | `tests/test_client_e2e.py` (new file) | ~20 |
-
-Coverage: unsafe zip / symlink / zip bomb / frontmatter / duplicate / extension / macOS filter / normalize / deduplicate / traversal / list / delete / agent invalidation / upload lifecycle / thread isolation / URL encoding / config pollution.

backend/docs/summarization.md

@@ -269,8 +269,8 @@ The middleware intelligently preserves message context:
 
 ### Code Structure
 
-- **Configuration**: `packages/harness/deerflow/config/summarization_config.py`
-- **Integration**: `packages/harness/deerflow/agents/lead_agent/agent.py`
+- **Configuration**: `src/config/summarization_config.py`
+- **Integration**: `src/agents/lead_agent/agent.py`
 - **Middleware**: Uses `langchain.agents.middleware.SummarizationMiddleware`
 
 ### Middleware Order

backend/docs/task_tool_improvements.md

@@ -65,7 +65,7 @@ The `task_status_tool` is no longer exposed to the LLM. It's kept in the codebas
 
 ### Polling Logic
 
-Located in `packages/harness/deerflow/tools/builtins/task_tool.py`:
+Located in `src/tools/builtins/task_tool.py`:
 
 ```python
 # Start background execution
@@ -93,7 +93,7 @@ while True:
 
 In addition to polling timeout, subagent execution now has a built-in timeout mechanism:
 
-**Configuration** (`packages/harness/deerflow/subagents/config.py`):
+**Configuration** (`src/subagents/config.py`):
 ```python
 @dataclass
 class SubagentConfig:

backend/langgraph.json

@@ -1,14 +1,10 @@
 {
   "$schema": "https://langgra.ph/schema.json",
-  "python_version": "3.12",
   "dependencies": [
     "."
   ],
   "env": ".env",
   "graphs": {
-    "lead_agent": "deerflow.agents:make_lead_agent"
-  },
-  "checkpointer": {
-    "path": "./packages/harness/deerflow/agents/checkpointer/async_provider.py:make_checkpointer"
+    "lead_agent": "src.agents:make_lead_agent"
   }
-}
+}

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

@@ -1,18 +0,0 @@
-from .checkpointer import get_checkpointer, make_checkpointer, reset_checkpointer
-from .factory import create_deerflow_agent
-from .features import Next, Prev, RuntimeFeatures
-from .lead_agent import make_lead_agent
-from .thread_state import SandboxState, ThreadState
-
-__all__ = [
-    "create_deerflow_agent",
-    "RuntimeFeatures",
-    "Next",
-    "Prev",
-    "make_lead_agent",
-    "SandboxState",
-    "ThreadState",
-    "get_checkpointer",
-    "reset_checkpointer",
-    "make_checkpointer",
-]

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

@@ -1,9 +0,0 @@
-from .async_provider import make_checkpointer
-from .provider import checkpointer_context, get_checkpointer, reset_checkpointer
-
-__all__ = [
-    "get_checkpointer",
-    "reset_checkpointer",
-    "checkpointer_context",
-    "make_checkpointer",
-]

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

@@ -1,105 +0,0 @@
-"""Async checkpointer factory.
-
-Provides an **async context manager** for long-running async servers that need
-proper resource cleanup.
-
-Supported backends: memory, sqlite, postgres.
-
-Usage (e.g. FastAPI lifespan)::
-
-    from deerflow.agents.checkpointer.async_provider import make_checkpointer
-
-    async with make_checkpointer() as checkpointer:
-        app.state.checkpointer = checkpointer  # InMemorySaver if not configured
-
-For sync usage see :mod:`deerflow.agents.checkpointer.provider`.
-"""
-
-from __future__ import annotations
-
-import contextlib
-import logging
-from collections.abc import AsyncIterator
-
-from langgraph.types import Checkpointer
-
-from deerflow.agents.checkpointer.provider import (
-    POSTGRES_CONN_REQUIRED,
-    POSTGRES_INSTALL,
-    SQLITE_INSTALL,
-)
-from deerflow.config.app_config import get_app_config
-from deerflow.runtime.store._sqlite_utils import ensure_sqlite_parent_dir, resolve_sqlite_conn_str
-
-logger = logging.getLogger(__name__)
-
-# ---------------------------------------------------------------------------
-# Async factory
-# ---------------------------------------------------------------------------
-
-
-@contextlib.asynccontextmanager
-async def _async_checkpointer(config) -> AsyncIterator[Checkpointer]:
-    """Async context manager that constructs and tears down a checkpointer."""
-    if config.type == "memory":
-        from langgraph.checkpoint.memory import InMemorySaver
-
-        yield InMemorySaver()
-        return
-
-    if config.type == "sqlite":
-        try:
-            from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
-        except ImportError as exc:
-            raise ImportError(SQLITE_INSTALL) from exc
-
-        conn_str = resolve_sqlite_conn_str(config.connection_string or "store.db")
-        ensure_sqlite_parent_dir(conn_str)
-        async with AsyncSqliteSaver.from_conn_string(conn_str) as saver:
-            await saver.setup()
-            yield saver
-        return
-
-    if config.type == "postgres":
-        try:
-            from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
-        except ImportError as exc:
-            raise ImportError(POSTGRES_INSTALL) from exc
-
-        if not config.connection_string:
-            raise ValueError(POSTGRES_CONN_REQUIRED)
-
-        async with AsyncPostgresSaver.from_conn_string(config.connection_string) as saver:
-            await saver.setup()
-            yield saver
-        return
-
-    raise ValueError(f"Unknown checkpointer type: {config.type!r}")
-
-
-# ---------------------------------------------------------------------------
-# Public async context manager
-# ---------------------------------------------------------------------------
-
-
-@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:
-        from langgraph.checkpoint.memory import InMemorySaver
-
-        yield InMemorySaver()
-        return
-
-    async with _async_checkpointer(config.checkpointer) as saver:
-        yield saver

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

@@ -1,191 +0,0 @@
-"""Sync checkpointer factory.
-
-Provides a **sync singleton** and a **sync context manager** for LangGraph
-graph compilation and CLI tools.
-
-Supported backends: memory, sqlite, postgres.
-
-Usage::
-
-    from deerflow.agents.checkpointer.provider import get_checkpointer, checkpointer_context
-
-    # Singleton — reused across calls, closed on process exit
-    cp = get_checkpointer()
-
-    # One-shot — fresh connection, closed on block exit
-    with checkpointer_context() as cp:
-        graph.invoke(input, config={"configurable": {"thread_id": "1"}})
-"""
-
-from __future__ import annotations
-
-import contextlib
-import logging
-from collections.abc import Iterator
-
-from langgraph.types import Checkpointer
-
-from deerflow.config.app_config import get_app_config
-from deerflow.config.checkpointer_config import CheckpointerConfig
-from deerflow.runtime.store._sqlite_utils import resolve_sqlite_conn_str
-
-logger = logging.getLogger(__name__)
-
-# ---------------------------------------------------------------------------
-# Error message constants — imported by aio.provider too
-# ---------------------------------------------------------------------------
-
-SQLITE_INSTALL = "langgraph-checkpoint-sqlite is required for the SQLite checkpointer. Install it with: uv add langgraph-checkpoint-sqlite"
-POSTGRES_INSTALL = "langgraph-checkpoint-postgres is required for the PostgreSQL checkpointer. Install it with: uv add langgraph-checkpoint-postgres psycopg[binary] psycopg-pool"
-POSTGRES_CONN_REQUIRED = "checkpointer.connection_string is required for the postgres backend"
-
-# ---------------------------------------------------------------------------
-# Sync factory
-# ---------------------------------------------------------------------------
-
-
-@contextlib.contextmanager
-def _sync_checkpointer_cm(config: CheckpointerConfig) -> Iterator[Checkpointer]:
-    """Context manager that creates and tears down a sync checkpointer.
-
-    Returns a configured ``Checkpointer`` instance. Resource cleanup for any
-    underlying connections or pools is handled by higher-level helpers in
-    this module (such as the singleton factory or context manager); this
-    function does not return a separate cleanup callback.
-    """
-    if config.type == "memory":
-        from langgraph.checkpoint.memory import InMemorySaver
-
-        logger.info("Checkpointer: using InMemorySaver (in-process, not persistent)")
-        yield InMemorySaver()
-        return
-
-    if config.type == "sqlite":
-        try:
-            from langgraph.checkpoint.sqlite import SqliteSaver
-        except ImportError as exc:
-            raise ImportError(SQLITE_INSTALL) from exc
-
-        conn_str = resolve_sqlite_conn_str(config.connection_string or "store.db")
-        with SqliteSaver.from_conn_string(conn_str) as saver:
-            saver.setup()
-            logger.info("Checkpointer: using SqliteSaver (%s)", conn_str)
-            yield saver
-        return
-
-    if config.type == "postgres":
-        try:
-            from langgraph.checkpoint.postgres import PostgresSaver
-        except ImportError as exc:
-            raise ImportError(POSTGRES_INSTALL) from exc
-
-        if not config.connection_string:
-            raise ValueError(POSTGRES_CONN_REQUIRED)
-
-        with PostgresSaver.from_conn_string(config.connection_string) as saver:
-            saver.setup()
-            logger.info("Checkpointer: using PostgresSaver")
-            yield saver
-        return
-
-    raise ValueError(f"Unknown checkpointer type: {config.type!r}")
-
-
-# ---------------------------------------------------------------------------
-# Sync singleton
-# ---------------------------------------------------------------------------
-
-_checkpointer: Checkpointer | None = None
-_checkpointer_ctx = None  # open context manager keeping the connection alive
-
-
-def get_checkpointer() -> Checkpointer:
-    """Return the global sync checkpointer singleton, creating it on first call.
-
-    Returns an ``InMemorySaver`` when no checkpointer is configured in *config.yaml*.
-
-    Raises:
-        ImportError: If the required package for the configured backend is not installed.
-        ValueError: If ``connection_string`` is missing for a backend that requires it.
-    """
-    global _checkpointer, _checkpointer_ctx
-
-    if _checkpointer is not None:
-        return _checkpointer
-
-    # Ensure app config is loaded before checking checkpointer config
-    # This prevents returning InMemorySaver when config.yaml actually has a checkpointer section
-    # but hasn't been loaded yet
-    from deerflow.config.app_config import _app_config
-    from deerflow.config.checkpointer_config import get_checkpointer_config
-
-    config = get_checkpointer_config()
-
-    if config is None and _app_config is None:
-        # Only load app config lazily when neither the app config nor an explicit
-        # checkpointer config has been initialized yet. This keeps tests that
-        # intentionally set the global checkpointer config isolated from any
-        # ambient config.yaml on disk.
-        try:
-            get_app_config()
-        except FileNotFoundError:
-            # In test environments without config.yaml, this is expected.
-            pass
-        config = get_checkpointer_config()
-    if config is None:
-        from langgraph.checkpoint.memory import InMemorySaver
-
-        logger.info("Checkpointer: using InMemorySaver (in-process, not persistent)")
-        _checkpointer = InMemorySaver()
-        return _checkpointer
-
-    _checkpointer_ctx = _sync_checkpointer_cm(config)
-    _checkpointer = _checkpointer_ctx.__enter__()
-
-    return _checkpointer
-
-
-def reset_checkpointer() -> None:
-    """Reset the sync singleton, forcing recreation on the next call.
-
-    Closes any open backend connections and clears the cached instance.
-    Useful in tests or after a configuration change.
-    """
-    global _checkpointer, _checkpointer_ctx
-    if _checkpointer_ctx is not None:
-        try:
-            _checkpointer_ctx.__exit__(None, None, None)
-        except Exception:
-            logger.warning("Error during checkpointer cleanup", exc_info=True)
-        _checkpointer_ctx = None
-    _checkpointer = None
-
-
-# ---------------------------------------------------------------------------
-# Sync context manager
-# ---------------------------------------------------------------------------
-
-
-@contextlib.contextmanager
-def checkpointer_context() -> Iterator[Checkpointer]:
-    """Sync context manager that yields a checkpointer and cleans up on exit.
-
-    Unlike :func:`get_checkpointer`, this does **not** cache the instance —
-    each ``with`` block creates and destroys its own connection.  Use it in
-    CLI scripts or tests where you want deterministic cleanup::
-
-        with checkpointer_context() as cp:
-            graph.invoke(input, config={"configurable": {"thread_id": "1"}})
-
-    Yields an ``InMemorySaver`` when no checkpointer is configured in *config.yaml*.
-    """
-
-    config = get_app_config()
-    if config.checkpointer is None:
-        from langgraph.checkpoint.memory import InMemorySaver
-
-        yield InMemorySaver()
-        return
-
-    with _sync_checkpointer_cm(config.checkpointer) as saver:
-        yield saver

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

@@ -1,372 +0,0 @@
-"""Pure-argument factory for DeerFlow agents.
-
-``create_deerflow_agent`` accepts plain Python arguments — no YAML files, no
-global singletons.  It is the SDK-level entry point sitting between the raw
-``langchain.agents.create_agent`` primitive and the config-driven
-``make_lead_agent`` application factory.
-
-Note: the factory assembly itself is config-free, but some injected runtime
-components (e.g. ``task_tool`` for subagent) may still read global config at
-invocation time.  Full config-free runtime is a Phase 2 goal.
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import TYPE_CHECKING
-
-from langchain.agents import create_agent
-from langchain.agents.middleware import AgentMiddleware
-
-from deerflow.agents.features import RuntimeFeatures
-from deerflow.agents.middlewares.clarification_middleware import ClarificationMiddleware
-from deerflow.agents.middlewares.dangling_tool_call_middleware import DanglingToolCallMiddleware
-from deerflow.agents.middlewares.tool_error_handling_middleware import ToolErrorHandlingMiddleware
-from deerflow.agents.thread_state import ThreadState
-from deerflow.tools.builtins import ask_clarification_tool
-
-if TYPE_CHECKING:
-    from langchain_core.language_models import BaseChatModel
-    from langchain_core.tools import BaseTool
-    from langgraph.checkpoint.base import BaseCheckpointSaver
-    from langgraph.graph.state import CompiledStateGraph
-
-logger = logging.getLogger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# TodoMiddleware prompts (minimal SDK version)
-# ---------------------------------------------------------------------------
-
-_TODO_SYSTEM_PROMPT = """
-<todo_list_system>
-You have access to the `write_todos` tool to help you manage and track complex multi-step objectives.
-
-**CRITICAL RULES:**
-- Mark todos as completed IMMEDIATELY after finishing each step - do NOT batch completions
-- Keep EXACTLY ONE task as `in_progress` at any time (unless tasks can run in parallel)
-- Update the todo list in REAL-TIME as you work - this gives users visibility into your progress
-- DO NOT use this tool for simple tasks (< 3 steps) - just complete them directly
-</todo_list_system>
-"""
-
-_TODO_TOOL_DESCRIPTION = "Use this tool to create and manage a structured task list for complex work sessions.  Only use for complex tasks (3+ steps)."
-
-
-# ---------------------------------------------------------------------------
-# Public API
-# ---------------------------------------------------------------------------
-
-
-def create_deerflow_agent(
-    model: BaseChatModel,
-    tools: list[BaseTool] | None = None,
-    *,
-    system_prompt: str | None = None,
-    middleware: list[AgentMiddleware] | None = None,
-    features: RuntimeFeatures | None = None,
-    extra_middleware: list[AgentMiddleware] | None = None,
-    plan_mode: bool = False,
-    state_schema: type | None = None,
-    checkpointer: BaseCheckpointSaver | None = None,
-    name: str = "default",
-) -> CompiledStateGraph:
-    """Create a DeerFlow agent from plain Python arguments.
-
-    The factory assembly itself reads no config files.  Some injected runtime
-    components (e.g. ``task_tool``) may still depend on global config at
-    invocation time — see Phase 2 roadmap for full config-free runtime.
-
-    Parameters
-    ----------
-    model:
-        Chat model instance.
-    tools:
-        User-provided tools.  Feature-injected tools are appended automatically.
-    system_prompt:
-        System message.  ``None`` uses a minimal default.
-    middleware:
-        **Full takeover** — if provided, this exact list is used.
-        Cannot be combined with *features* or *extra_middleware*.
-    features:
-        Declarative feature flags.  Cannot be combined with *middleware*.
-    extra_middleware:
-        Additional middlewares inserted into the auto-assembled chain via
-        ``@Next``/``@Prev`` positioning.  Cannot be used with *middleware*.
-    plan_mode:
-        Enable TodoMiddleware for task tracking.
-    state_schema:
-        LangGraph state type.  Defaults to ``ThreadState``.
-    checkpointer:
-        Optional persistence backend.
-    name:
-        Agent name (passed to middleware that cares, e.g. ``MemoryMiddleware``).
-
-    Raises
-    ------
-    ValueError
-        If both *middleware* and *features*/*extra_middleware* are provided.
-    """
-    if middleware is not None and features is not None:
-        raise ValueError("Cannot specify both 'middleware' and 'features'.  Use one or the other.")
-    if middleware is not None and extra_middleware:
-        raise ValueError("Cannot use 'extra_middleware' with 'middleware' (full takeover).")
-    if extra_middleware:
-        for mw in extra_middleware:
-            if not isinstance(mw, AgentMiddleware):
-                raise TypeError(f"extra_middleware items must be AgentMiddleware instances, got {type(mw).__name__}")
-
-    effective_tools: list[BaseTool] = list(tools or [])
-    effective_state = state_schema or ThreadState
-
-    if middleware is not None:
-        effective_middleware = list(middleware)
-    else:
-        feat = features or RuntimeFeatures()
-        effective_middleware, extra_tools = _assemble_from_features(
-            feat,
-            name=name,
-            plan_mode=plan_mode,
-            extra_middleware=extra_middleware or [],
-        )
-        # Deduplicate by tool name — user-provided tools take priority.
-        existing_names = {t.name for t in effective_tools}
-        for t in extra_tools:
-            if t.name not in existing_names:
-                effective_tools.append(t)
-                existing_names.add(t.name)
-
-    return create_agent(
-        model=model,
-        tools=effective_tools or None,
-        middleware=effective_middleware,
-        system_prompt=system_prompt,
-        state_schema=effective_state,
-        checkpointer=checkpointer,
-        name=name,
-    )
-
-
-# ---------------------------------------------------------------------------
-# Internal: feature-driven middleware assembly
-# ---------------------------------------------------------------------------
-
-
-def _assemble_from_features(
-    feat: RuntimeFeatures,
-    *,
-    name: str = "default",
-    plan_mode: bool = False,
-    extra_middleware: list[AgentMiddleware] | None = None,
-) -> tuple[list[AgentMiddleware], list[BaseTool]]:
-    """Build an ordered middleware chain + extra tools from *feat*.
-
-    Middleware order matches ``make_lead_agent`` (14 middlewares):
-
-      0-2. Sandbox infrastructure (ThreadData → Uploads → Sandbox)
-      3.   DanglingToolCallMiddleware (always)
-      4.   GuardrailMiddleware (guardrail feature)
-      5.   ToolErrorHandlingMiddleware (always)
-      6.   SummarizationMiddleware (summarization feature)
-      7.   TodoMiddleware (plan_mode parameter)
-      8.   TitleMiddleware (auto_title feature)
-      9.   MemoryMiddleware (memory feature)
-      10.  ViewImageMiddleware (vision feature)
-      11.  SubagentLimitMiddleware (subagent feature)
-      12.  LoopDetectionMiddleware (always)
-      13.  ClarificationMiddleware (always last)
-
-    Two-phase ordering:
-      1. Built-in chain — fixed sequential append.
-      2. Extra middleware — inserted via @Next/@Prev.
-
-    Each feature value is handled as:
-      - ``False``: skip
-      - ``True``: create the built-in default middleware (not available for
-        ``summarization`` and ``guardrail`` — these require a custom instance)
-      - ``AgentMiddleware`` instance: use directly (custom replacement)
-    """
-    chain: list[AgentMiddleware] = []
-    extra_tools: list[BaseTool] = []
-
-    # --- [0-2] Sandbox infrastructure ---
-    if feat.sandbox is not False:
-        if isinstance(feat.sandbox, AgentMiddleware):
-            chain.append(feat.sandbox)
-        else:
-            from deerflow.agents.middlewares.thread_data_middleware import ThreadDataMiddleware
-            from deerflow.agents.middlewares.uploads_middleware import UploadsMiddleware
-            from deerflow.sandbox.middleware import SandboxMiddleware
-
-            chain.append(ThreadDataMiddleware(lazy_init=True))
-            chain.append(UploadsMiddleware())
-            chain.append(SandboxMiddleware(lazy_init=True))
-
-    # --- [3] DanglingToolCall (always) ---
-    chain.append(DanglingToolCallMiddleware())
-
-    # --- [4] Guardrail ---
-    if feat.guardrail is not False:
-        if isinstance(feat.guardrail, AgentMiddleware):
-            chain.append(feat.guardrail)
-        else:
-            raise ValueError("guardrail=True requires a custom AgentMiddleware instance (no built-in GuardrailMiddleware yet)")
-
-    # --- [5] ToolErrorHandling (always) ---
-    chain.append(ToolErrorHandlingMiddleware())
-
-    # --- [6] Summarization ---
-    if feat.summarization is not False:
-        if isinstance(feat.summarization, AgentMiddleware):
-            chain.append(feat.summarization)
-        else:
-            raise ValueError("summarization=True requires a custom AgentMiddleware instance (SummarizationMiddleware needs a model argument)")
-
-    # --- [7] TodoMiddleware (plan_mode) ---
-    if plan_mode:
-        from deerflow.agents.middlewares.todo_middleware import TodoMiddleware
-
-        chain.append(TodoMiddleware(system_prompt=_TODO_SYSTEM_PROMPT, tool_description=_TODO_TOOL_DESCRIPTION))
-
-    # --- [8] Auto Title ---
-    if feat.auto_title is not False:
-        if isinstance(feat.auto_title, AgentMiddleware):
-            chain.append(feat.auto_title)
-        else:
-            from deerflow.agents.middlewares.title_middleware import TitleMiddleware
-
-            chain.append(TitleMiddleware())
-
-    # --- [9] Memory ---
-    if feat.memory is not False:
-        if isinstance(feat.memory, AgentMiddleware):
-            chain.append(feat.memory)
-        else:
-            from deerflow.agents.middlewares.memory_middleware import MemoryMiddleware
-
-            chain.append(MemoryMiddleware(agent_name=name))
-
-    # --- [10] Vision ---
-    if feat.vision is not False:
-        if isinstance(feat.vision, AgentMiddleware):
-            chain.append(feat.vision)
-        else:
-            from deerflow.agents.middlewares.view_image_middleware import ViewImageMiddleware
-
-            chain.append(ViewImageMiddleware())
-        from deerflow.tools.builtins import view_image_tool
-
-        extra_tools.append(view_image_tool)
-
-    # --- [11] Subagent ---
-    if feat.subagent is not False:
-        if isinstance(feat.subagent, AgentMiddleware):
-            chain.append(feat.subagent)
-        else:
-            from deerflow.agents.middlewares.subagent_limit_middleware import SubagentLimitMiddleware
-
-            chain.append(SubagentLimitMiddleware())
-        from deerflow.tools.builtins import task_tool
-
-        extra_tools.append(task_tool)
-
-    # --- [12] LoopDetection (always) ---
-    from deerflow.agents.middlewares.loop_detection_middleware import LoopDetectionMiddleware
-
-    chain.append(LoopDetectionMiddleware())
-
-    # --- [13] Clarification (always last among built-ins) ---
-    chain.append(ClarificationMiddleware())
-    extra_tools.append(ask_clarification_tool)
-
-    # --- Insert extra_middleware via @Next/@Prev ---
-    if extra_middleware:
-        _insert_extra(chain, extra_middleware)
-        # Invariant: ClarificationMiddleware must always be last.
-        # @Next(ClarificationMiddleware) could push it off the tail.
-        clar_idx = next(i for i, m in enumerate(chain) if isinstance(m, ClarificationMiddleware))
-        if clar_idx != len(chain) - 1:
-            chain.append(chain.pop(clar_idx))
-
-    return chain, extra_tools
-
-
-# ---------------------------------------------------------------------------
-# Internal: extra middleware insertion with @Next/@Prev
-# ---------------------------------------------------------------------------
-
-
-def _insert_extra(chain: list[AgentMiddleware], extras: list[AgentMiddleware]) -> None:
-    """Insert extra middlewares into *chain* using ``@Next``/``@Prev`` anchors.
-
-    Algorithm:
-      1. Validate: no middleware has both @Next and @Prev.
-      2. Conflict detection: two extras targeting same anchor (same or opposite direction) → error.
-      3. Insert unanchored extras before ClarificationMiddleware.
-      4. Insert anchored extras iteratively (supports cross-external anchoring).
-      5. If an anchor cannot be resolved after all rounds → error.
-    """
-    next_targets: dict[type, type] = {}
-    prev_targets: dict[type, type] = {}
-
-    anchored: list[tuple[AgentMiddleware, str, type]] = []
-    unanchored: list[AgentMiddleware] = []
-
-    for mw in extras:
-        next_anchor = getattr(type(mw), "_next_anchor", None)
-        prev_anchor = getattr(type(mw), "_prev_anchor", None)
-
-        if next_anchor and prev_anchor:
-            raise ValueError(f"{type(mw).__name__} cannot have both @Next and @Prev")
-
-        if next_anchor:
-            if next_anchor in next_targets:
-                raise ValueError(f"Conflict: {type(mw).__name__} and {next_targets[next_anchor].__name__} both @Next({next_anchor.__name__})")
-            if next_anchor in prev_targets:
-                raise ValueError(f"Conflict: {type(mw).__name__} @Next({next_anchor.__name__}) and {prev_targets[next_anchor].__name__} @Prev({next_anchor.__name__}) — use cross-anchoring between extras instead")
-            next_targets[next_anchor] = type(mw)
-            anchored.append((mw, "next", next_anchor))
-        elif prev_anchor:
-            if prev_anchor in prev_targets:
-                raise ValueError(f"Conflict: {type(mw).__name__} and {prev_targets[prev_anchor].__name__} both @Prev({prev_anchor.__name__})")
-            if prev_anchor in next_targets:
-                raise ValueError(f"Conflict: {type(mw).__name__} @Prev({prev_anchor.__name__}) and {next_targets[prev_anchor].__name__} @Next({prev_anchor.__name__}) — use cross-anchoring between extras instead")
-            prev_targets[prev_anchor] = type(mw)
-            anchored.append((mw, "prev", prev_anchor))
-        else:
-            unanchored.append(mw)
-
-    # Unanchored → before ClarificationMiddleware
-    clarification_idx = next(i for i, m in enumerate(chain) if isinstance(m, ClarificationMiddleware))
-    for mw in unanchored:
-        chain.insert(clarification_idx, mw)
-        clarification_idx += 1
-
-    # Anchored → iterative insertion (supports external-to-external anchoring)
-    pending = list(anchored)
-    max_rounds = len(pending) + 1
-    for _ in range(max_rounds):
-        if not pending:
-            break
-        remaining = []
-        for mw, direction, anchor in pending:
-            idx = next(
-                (i for i, m in enumerate(chain) if isinstance(m, anchor)),
-                None,
-            )
-            if idx is None:
-                remaining.append((mw, direction, anchor))
-                continue
-            if direction == "next":
-                chain.insert(idx + 1, mw)
-            else:
-                chain.insert(idx, mw)
-        if len(remaining) == len(pending):
-            names = [type(m).__name__ for m, _, _ in remaining]
-            anchor_types = {a for _, _, a in remaining}
-            remaining_types = {type(m) for m, _, _ in remaining}
-            circular = anchor_types & remaining_types
-            if circular:
-                raise ValueError(f"Circular dependency among extra middlewares: {', '.join(t.__name__ for t in circular)}")
-            raise ValueError(f"Cannot resolve positions for {', '.join(names)} — anchors {', '.join(a.__name__ for _, _, a in remaining)} not found in chain")
-        pending = remaining

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

@@ -1,62 +0,0 @@
-"""Declarative feature flags and middleware positioning for create_deerflow_agent.
-
-Pure data classes and decorators — no I/O, no side effects.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Literal
-
-from langchain.agents.middleware import AgentMiddleware
-
-
-@dataclass
-class RuntimeFeatures:
-    """Declarative feature flags for ``create_deerflow_agent``.
-
-    Most features accept:
-    - ``True``: use the built-in default middleware
-    - ``False``: disable
-    - An ``AgentMiddleware`` instance: use this custom implementation instead
-
-    ``summarization`` and ``guardrail`` have no built-in default — they only
-    accept ``False`` (disable) or an ``AgentMiddleware`` instance (custom).
-    """
-
-    sandbox: bool | AgentMiddleware = True
-    memory: bool | AgentMiddleware = False
-    summarization: Literal[False] | AgentMiddleware = False
-    subagent: bool | AgentMiddleware = False
-    vision: bool | AgentMiddleware = False
-    auto_title: bool | AgentMiddleware = False
-    guardrail: Literal[False] | AgentMiddleware = False
-
-
-# ---------------------------------------------------------------------------
-# Middleware positioning decorators
-# ---------------------------------------------------------------------------
-
-
-def Next(anchor: type[AgentMiddleware]):
-    """Declare this middleware should be placed after *anchor* in the chain."""
-    if not (isinstance(anchor, type) and issubclass(anchor, AgentMiddleware)):
-        raise TypeError(f"@Next expects an AgentMiddleware subclass, got {anchor!r}")
-
-    def decorator(cls: type[AgentMiddleware]) -> type[AgentMiddleware]:
-        cls._next_anchor = anchor  # type: ignore[attr-defined]
-        return cls
-
-    return decorator
-
-
-def Prev(anchor: type[AgentMiddleware]):
-    """Declare this middleware should be placed before *anchor* in the chain."""
-    if not (isinstance(anchor, type) and issubclass(anchor, AgentMiddleware)):
-        raise TypeError(f"@Prev expects an AgentMiddleware subclass, got {anchor!r}")
-
-    def decorator(cls: type[AgentMiddleware]) -> type[AgentMiddleware]:
-        cls._prev_anchor = anchor  # type: ignore[attr-defined]
-        return cls
-
-    return decorator

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

@@ -1,200 +0,0 @@
-"""Memory storage providers."""
-
-import abc
-import json
-import logging
-import threading
-from datetime import datetime
-from pathlib import Path
-from typing import Any
-
-from deerflow.config.agents_config import AGENT_NAME_PATTERN
-from deerflow.config.memory_config import get_memory_config
-from deerflow.config.paths import get_paths
-
-logger = logging.getLogger(__name__)
-
-
-def create_empty_memory() -> dict[str, Any]:
-    """Create an empty memory structure."""
-    return {
-        "version": "1.0",
-        "lastUpdated": datetime.utcnow().isoformat() + "Z",
-        "user": {
-            "workContext": {"summary": "", "updatedAt": ""},
-            "personalContext": {"summary": "", "updatedAt": ""},
-            "topOfMind": {"summary": "", "updatedAt": ""},
-        },
-        "history": {
-            "recentMonths": {"summary": "", "updatedAt": ""},
-            "earlierContext": {"summary": "", "updatedAt": ""},
-            "longTermBackground": {"summary": "", "updatedAt": ""},
-        },
-        "facts": [],
-    }
-
-
-class MemoryStorage(abc.ABC):
-    """Abstract base class for memory storage providers."""
-
-    @abc.abstractmethod
-    def load(self, agent_name: str | None = None) -> dict[str, Any]:
-        """Load memory data for the given agent."""
-        pass
-
-    @abc.abstractmethod
-    def reload(self, agent_name: str | None = None) -> dict[str, Any]:
-        """Force reload memory data for the given agent."""
-        pass
-
-    @abc.abstractmethod
-    def save(self, memory_data: dict[str, Any], agent_name: str | None = None) -> bool:
-        """Save memory data for the given agent."""
-        pass
-
-
-class FileMemoryStorage(MemoryStorage):
-    """File-based memory storage provider."""
-
-    def __init__(self):
-        """Initialize the file memory storage."""
-        # 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]] = {}
-
-    def _validate_agent_name(self, agent_name: str) -> None:
-        """Validate that the agent name is safe to use in filesystem paths.
-
-        Uses the repository's established AGENT_NAME_PATTERN to ensure consistency
-        across the codebase and prevent path traversal or other problematic characters.
-        """
-        if not agent_name:
-            raise ValueError("Agent name must be a non-empty string.")
-        if not AGENT_NAME_PATTERN.match(agent_name):
-            raise ValueError(f"Invalid agent name {agent_name!r}: names must match {AGENT_NAME_PATTERN.pattern}")
-
-    def _get_memory_file_path(self, agent_name: str | None = None) -> Path:
-        """Get the path to the memory file."""
-        if agent_name is not None:
-            self._validate_agent_name(agent_name)
-            return get_paths().agent_memory_file(agent_name)
-
-        config = get_memory_config()
-        if config.storage_path:
-            p = Path(config.storage_path)
-            return p if p.is_absolute() else get_paths().base_dir / p
-        return get_paths().memory_file
-
-    def _load_memory_from_file(self, agent_name: str | None = None) -> dict[str, Any]:
-        """Load memory data from file."""
-        file_path = self._get_memory_file_path(agent_name)
-
-        if not file_path.exists():
-            return create_empty_memory()
-
-        try:
-            with open(file_path, encoding="utf-8") as f:
-                data = json.load(f)
-            return data
-        except (json.JSONDecodeError, OSError) as e:
-            logger.warning("Failed to load memory file: %s", e)
-            return create_empty_memory()
-
-    def load(self, agent_name: str | None = None) -> dict[str, Any]:
-        """Load memory data (cached with file modification time check)."""
-        file_path = self._get_memory_file_path(agent_name)
-
-        try:
-            current_mtime = file_path.stat().st_mtime if file_path.exists() else None
-        except OSError:
-            current_mtime = None
-
-        cached = self._memory_cache.get(agent_name)
-
-        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 cached[0]
-
-    def reload(self, agent_name: str | None = None) -> dict[str, Any]:
-        """Reload memory data from file, forcing cache invalidation."""
-        file_path = self._get_memory_file_path(agent_name)
-        memory_data = self._load_memory_from_file(agent_name)
-
-        try:
-            mtime = file_path.stat().st_mtime if file_path.exists() else None
-        except OSError:
-            mtime = None
-
-        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:
-        """Save memory data to file and update cache."""
-        file_path = self._get_memory_file_path(agent_name)
-
-        try:
-            file_path.parent.mkdir(parents=True, exist_ok=True)
-            memory_data["lastUpdated"] = datetime.utcnow().isoformat() + "Z"
-
-            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)
-
-            temp_path.replace(file_path)
-
-            try:
-                mtime = file_path.stat().st_mtime
-            except OSError:
-                mtime = None
-
-            self._memory_cache[agent_name] = (memory_data, mtime)
-            logger.info("Memory saved to %s", file_path)
-            return True
-        except OSError as e:
-            logger.error("Failed to save memory file: %s", e)
-            return False
-
-
-_storage_instance: MemoryStorage | None = None
-_storage_lock = threading.Lock()
-
-
-def get_memory_storage() -> MemoryStorage:
-    """Get the configured memory storage instance."""
-    global _storage_instance
-    if _storage_instance is not None:
-        return _storage_instance
-
-    with _storage_lock:
-        if _storage_instance is not None:
-            return _storage_instance
-
-        config = get_memory_config()
-        storage_class_path = config.storage_class
-
-        try:
-            module_path, class_name = storage_class_path.rsplit(".", 1)
-            import importlib
-
-            module = importlib.import_module(module_path)
-            storage_class = getattr(module, class_name)
-
-            # Validate that the configured storage is a MemoryStorage implementation
-            if not isinstance(storage_class, type):
-                raise TypeError(f"Configured memory storage '{storage_class_path}' is not a class: {storage_class!r}")
-            if not issubclass(storage_class, MemoryStorage):
-                raise TypeError(f"Configured memory storage '{storage_class_path}' is not a subclass of MemoryStorage")
-
-            _storage_instance = storage_class()
-        except Exception as e:
-            logger.error(
-                "Failed to load memory storage %s, falling back to FileMemoryStorage: %s",
-                storage_class_path,
-                e,
-            )
-            _storage_instance = FileMemoryStorage()
-
-    return _storage_instance

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

@@ -1 +0,0 @@
-

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

@@ -1,60 +0,0 @@
-"""Middleware to filter deferred tool schemas from model binding.
-
-When tool_search is enabled, MCP tools are registered in the DeferredToolRegistry
-and passed to ToolNode for execution, but their schemas should NOT be sent to the
-LLM via bind_tools (that's the whole point of deferral — saving context tokens).
-
-This middleware intercepts wrap_model_call and removes deferred tools from
-request.tools so that model.bind_tools only receives active tool schemas.
-The agent discovers deferred tools at runtime via the tool_search tool.
-"""
-
-import logging
-from collections.abc import Awaitable, Callable
-from typing import override
-
-from langchain.agents import AgentState
-from langchain.agents.middleware import AgentMiddleware
-from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
-
-logger = logging.getLogger(__name__)
-
-
-class DeferredToolFilterMiddleware(AgentMiddleware[AgentState]):
-    """Remove deferred tools from request.tools before model binding.
-
-    ToolNode still holds all tools (including deferred) for execution routing,
-    but the LLM only sees active tool schemas — deferred tools are discoverable
-    via tool_search at runtime.
-    """
-
-    def _filter_tools(self, request: ModelRequest) -> ModelRequest:
-        from deerflow.tools.builtins.tool_search import get_deferred_registry
-
-        registry = get_deferred_registry()
-        if not registry:
-            return request
-
-        deferred_names = {e.name for e in registry.entries}
-        active_tools = [t for t in request.tools if getattr(t, "name", None) not in deferred_names]
-
-        if len(active_tools) < len(request.tools):
-            logger.debug(f"Filtered {len(request.tools) - len(active_tools)} deferred tool schema(s) from model binding")
-
-        return request.override(tools=active_tools)
-
-    @override
-    def wrap_model_call(
-        self,
-        request: ModelRequest,
-        handler: Callable[[ModelRequest], ModelResponse],
-    ) -> ModelCallResult:
-        return handler(self._filter_tools(request))
-
-    @override
-    async def awrap_model_call(
-        self,
-        request: ModelRequest,
-        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
-    ) -> ModelCallResult:
-        return await handler(self._filter_tools(request))

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

@@ -1,227 +0,0 @@
-"""Middleware to detect and break repetitive tool call loops.
-
-P0 safety: prevents the agent from calling the same tool with the same
-arguments indefinitely until the recursion limit kills the run.
-
-Detection strategy:
-  1. After each model response, hash the tool calls (name + args).
-  2. Track recent hashes in a sliding window.
-  3. If the same hash appears >= warn_threshold times, inject a
-     "you are repeating yourself — wrap up" system message (once per hash).
-  4. If it appears >= hard_limit times, strip all tool_calls from the
-     response so the agent is forced to produce a final text answer.
-"""
-
-import hashlib
-import json
-import logging
-import threading
-from collections import OrderedDict, defaultdict
-from typing import override
-
-from langchain.agents import AgentState
-from langchain.agents.middleware import AgentMiddleware
-from langchain_core.messages import HumanMessage
-from langgraph.runtime import Runtime
-
-logger = logging.getLogger(__name__)
-
-# Defaults — can be overridden via constructor
-_DEFAULT_WARN_THRESHOLD = 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
-
-
-def _hash_tool_calls(tool_calls: list[dict]) -> str:
-    """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.
-    """
-    # First normalize each tool call to a minimal (name, args) structure.
-    normalized: list[dict] = []
-    for tc in tool_calls:
-        normalized.append(
-            {
-                "name": tc.get("name", ""),
-                "args": tc.get("args", {}),
-            }
-        )
-
-    # 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."
-
-_HARD_STOP_MSG = "[FORCED STOP] Repeated tool calls exceeded the safety limit. Producing final answer with results collected so far."
-
-
-class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
-    """Detects and breaks repetitive tool call loops.
-
-    Args:
-        warn_threshold: Number of identical tool call sets before injecting
-            a warning message. Default: 3.
-        hard_limit: Number of identical tool call sets before stripping
-            tool_calls entirely. Default: 5.
-        window_size: Size of the sliding window for tracking calls.
-            Default: 20.
-        max_tracked_threads: Maximum number of threads to track before
-            evicting the least recently used. Default: 100.
-    """
-
-    def __init__(
-        self,
-        warn_threshold: int = _DEFAULT_WARN_THRESHOLD,
-        hard_limit: int = _DEFAULT_HARD_LIMIT,
-        window_size: int = _DEFAULT_WINDOW_SIZE,
-        max_tracked_threads: int = _DEFAULT_MAX_TRACKED_THREADS,
-    ):
-        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._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)
-
-    def _get_thread_id(self, runtime: Runtime) -> str:
-        """Extract thread_id from runtime context for per-thread tracking."""
-        thread_id = runtime.context.get("thread_id") if runtime.context else None
-        if thread_id:
-            return thread_id
-        return "default"
-
-    def _evict_if_needed(self) -> None:
-        """Evict least recently used threads if over the limit.
-
-        Must be called while holding self._lock.
-        """
-        while len(self._history) > self.max_tracked_threads:
-            evicted_id, _ = self._history.popitem(last=False)
-            self._warned.pop(evicted_id, None)
-            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.
-
-        Returns:
-            (warning_message_or_none, should_hard_stop)
-        """
-        messages = state.get("messages", [])
-        if not messages:
-            return None, False
-
-        last_msg = messages[-1]
-        if getattr(last_msg, "type", None) != "ai":
-            return None, False
-
-        tool_calls = getattr(last_msg, "tool_calls", None)
-        if not tool_calls:
-            return None, False
-
-        thread_id = self._get_thread_id(runtime)
-        call_hash = _hash_tool_calls(tool_calls)
-
-        with self._lock:
-            # Touch / create entry (move to end for LRU)
-            if thread_id in self._history:
-                self._history.move_to_end(thread_id)
-            else:
-                self._history[thread_id] = []
-                self._evict_if_needed()
-
-            history = self._history[thread_id]
-            history.append(call_hash)
-            if len(history) > self.window_size:
-                history[:] = history[-self.window_size :]
-
-            count = history.count(call_hash)
-            tool_names = [tc.get("name", "?") for tc in tool_calls]
-
-            if count >= self.hard_limit:
-                logger.error(
-                    "Loop hard limit reached — forcing stop",
-                    extra={
-                        "thread_id": thread_id,
-                        "call_hash": call_hash,
-                        "count": count,
-                        "tools": tool_names,
-                    },
-                )
-                return _HARD_STOP_MSG, True
-
-            if count >= self.warn_threshold:
-                warned = self._warned[thread_id]
-                if call_hash not in warned:
-                    warned.add(call_hash)
-                    logger.warning(
-                        "Repetitive tool calls detected — injecting warning",
-                        extra={
-                            "thread_id": thread_id,
-                            "call_hash": call_hash,
-                            "count": count,
-                            "tools": tool_names,
-                        },
-                    )
-                    return _WARNING_MSG, False
-                # Warning already injected for this hash — suppress
-                return None, False
-
-        return None, False
-
-    def _apply(self, state: AgentState, runtime: Runtime) -> dict | None:
-        warning, hard_stop = self._track_and_check(state, runtime)
-
-        if hard_stop:
-            # Strip tool_calls from the last AIMessage to force text output
-            messages = state.get("messages", [])
-            last_msg = messages[-1]
-            stripped_msg = last_msg.model_copy(
-                update={
-                    "tool_calls": [],
-                    "content": (last_msg.content or "") + f"\n\n{_HARD_STOP_MSG}",
-                }
-            )
-            return {"messages": [stripped_msg]}
-
-        if warning:
-            # Inject as HumanMessage instead of SystemMessage to avoid
-            # Anthropic's "multiple non-consecutive system messages" error.
-            # Anthropic models require system messages only at the start of
-            # the conversation; injecting one mid-conversation crashes
-            # langchain_anthropic's _format_messages(). HumanMessage works
-            # with all providers. See #1299.
-            return {"messages": [HumanMessage(content=warning)]}
-
-        return None
-
-    @override
-    def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
-        return self._apply(state, runtime)
-
-    @override
-    async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict | None:
-        return self._apply(state, runtime)
-
-    def reset(self, thread_id: str | None = None) -> None:
-        """Clear tracking state. If thread_id given, clear only that thread."""
-        with self._lock:
-            if thread_id:
-                self._history.pop(thread_id, None)
-                self._warned.pop(thread_id, None)
-            else:
-                self._history.clear()
-                self._warned.clear()

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

@@ -1,204 +0,0 @@
-"""SandboxAuditMiddleware - bash command security auditing."""
-
-import json
-import logging
-import re
-import shlex
-from collections.abc import Awaitable, Callable
-from datetime import UTC, datetime
-from typing import override
-
-from langchain.agents.middleware import AgentMiddleware
-from langchain_core.messages import ToolMessage
-from langgraph.prebuilt.tool_node import ToolCallRequest
-from langgraph.types import Command
-
-from deerflow.agents.thread_state import ThreadState
-
-logger = logging.getLogger(__name__)
-
-# ---------------------------------------------------------------------------
-# Command classification rules
-# ---------------------------------------------------------------------------
-
-# Each pattern is compiled once at import time.
-_HIGH_RISK_PATTERNS: list[re.Pattern[str]] = [
-    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/"),  # overwrite /etc/ files
-]
-
-_MEDIUM_RISK_PATTERNS: list[re.Pattern[str]] = [
-    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"),
-]
-
-
-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:
-        if pattern.search(normalized):
-            return "block"
-
-    # Also try shlex-parsed tokens for high-risk detection
-    try:
-        tokens = shlex.split(command)
-        joined = " ".join(tokens)
-        for pattern in _HIGH_RISK_PATTERNS:
-            if pattern.search(joined):
-                return "block"
-    except ValueError:
-        # shlex.split fails on unclosed quotes — treat as suspicious
-        return "block"
-
-    for pattern in _MEDIUM_RISK_PATTERNS:
-        if pattern.search(normalized):
-            return "warn"
-
-    return "pass"
-
-
-# ---------------------------------------------------------------------------
-# Middleware
-# ---------------------------------------------------------------------------
-
-
-class SandboxAuditMiddleware(AgentMiddleware[ThreadState]):
-    """Bash command security auditing middleware.
-
-    For every ``bash`` tool call:
-    1. **Command classification**: regex + shlex analysis grades commands as
-       high-risk (block), medium-risk (warn), or safe (pass).
-    2. **Audit log**: every bash call is recorded as a structured JSON entry
-       via the standard logger (visible in langgraph.log).
-
-    High-risk commands (e.g. ``rm -rf /``, ``curl url | bash``) are blocked:
-    the handler is not called and an error ``ToolMessage`` is returned so the
-    agent loop can continue gracefully.
-
-    Medium-risk commands (e.g. ``pip install``, ``chmod 777``) are executed
-    normally; a warning is appended to the tool result so the LLM is aware.
-    """
-
-    state_schema = ThreadState
-
-    # ------------------------------------------------------------------
-    # Helpers
-    # ------------------------------------------------------------------
-
-    def _get_thread_id(self, request: ToolCallRequest) -> str | None:
-        runtime = request.runtime  # ToolRuntime; may be None-like in tests
-        if runtime is None:
-            return None
-        ctx = getattr(runtime, "context", None) or {}
-        thread_id = ctx.get("thread_id") if isinstance(ctx, dict) else None
-        if thread_id is None:
-            cfg = getattr(runtime, "config", None) or {}
-            thread_id = cfg.get("configurable", {}).get("thread_id")
-        return thread_id
-
-    def _write_audit(self, thread_id: str | None, command: str, verdict: str) -> None:
-        record = {
-            "timestamp": datetime.now(UTC).isoformat(),
-            "thread_id": thread_id or "unknown",
-            "command": command,
-            "verdict": verdict,
-        }
-        logger.info("[SandboxAudit] %s", json.dumps(record, ensure_ascii=False))
-
-    def _build_block_message(self, request: ToolCallRequest, reason: str) -> ToolMessage:
-        tool_call_id = str(request.tool_call.get("id") or "missing_id")
-        return ToolMessage(
-            content=f"Command blocked: {reason}. Please use a safer alternative approach.",
-            tool_call_id=tool_call_id,
-            name="bash",
-            status="error",
-        )
-
-    def _append_warn_to_result(self, result: ToolMessage | Command, command: str) -> ToolMessage | Command:
-        """Append a warning note to the tool result for medium-risk commands."""
-        if not isinstance(result, ToolMessage):
-            return result
-        warning = f"\n\n⚠️ Warning: `{command}` is a medium-risk command that may modify the runtime environment."
-        if isinstance(result.content, list):
-            new_content = list(result.content) + [{"type": "text", "text": warning}]
-        else:
-            new_content = str(result.content) + warning
-        return ToolMessage(
-            content=new_content,
-            tool_call_id=result.tool_call_id,
-            name=result.name,
-            status=result.status,
-        )
-
-    # ------------------------------------------------------------------
-    # Core logic (shared between sync and async paths)
-    # ------------------------------------------------------------------
-
-    def _pre_process(self, request: ToolCallRequest) -> tuple[str, str | None, str]:
-        """
-        Returns (command, thread_id, verdict).
-        verdict is 'block', 'warn', or 'pass'.
-        """
-        args = request.tool_call.get("args", {})
-        command: str = args.get("command", "")
-        thread_id = self._get_thread_id(request)
-
-        # ① classify command
-        verdict = _classify_command(command)
-
-        # ② audit log
-        self._write_audit(thread_id, command, verdict)
-
-        if verdict == "block":
-            logger.warning("[SandboxAudit] BLOCKED thread=%s cmd=%r", thread_id, command)
-        elif verdict == "warn":
-            logger.warning("[SandboxAudit] WARN (medium-risk) thread=%s cmd=%r", thread_id, command)
-
-        return command, thread_id, verdict
-
-    # ------------------------------------------------------------------
-    # wrap_tool_call hooks
-    # ------------------------------------------------------------------
-
-    @override
-    def wrap_tool_call(
-        self,
-        request: ToolCallRequest,
-        handler: Callable[[ToolCallRequest], ToolMessage | Command],
-    ) -> ToolMessage | Command:
-        if request.tool_call.get("name") != "bash":
-            return handler(request)
-
-        command, _, verdict = self._pre_process(request)
-        if verdict == "block":
-            return self._build_block_message(request, "security violation detected")
-        result = handler(request)
-        if verdict == "warn":
-            result = self._append_warn_to_result(result, command)
-        return result
-
-    @override
-    async def awrap_tool_call(
-        self,
-        request: ToolCallRequest,
-        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
-    ) -> ToolMessage | Command:
-        if request.tool_call.get("name") != "bash":
-            return await handler(request)
-
-        command, _, verdict = self._pre_process(request)
-        if verdict == "block":
-            return self._build_block_message(request, "security violation detected")
-        result = await handler(request)
-        if verdict == "warn":
-            result = self._append_warn_to_result(result, command)
-        return result

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

@@ -1,149 +0,0 @@
-"""Middleware for automatic thread title generation."""
-
-import logging
-from typing import NotRequired, override
-
-from langchain.agents import AgentState
-from langchain.agents.middleware import AgentMiddleware
-from langgraph.runtime import Runtime
-
-from deerflow.config.title_config import get_title_config
-from deerflow.models import create_chat_model
-
-logger = logging.getLogger(__name__)
-
-
-class TitleMiddlewareState(AgentState):
-    """Compatible with the `ThreadState` schema."""
-
-    title: NotRequired[str | None]
-
-
-class TitleMiddleware(AgentMiddleware[TitleMiddlewareState]):
-    """Automatically generate a title for the thread after the first user message."""
-
-    state_schema = TitleMiddlewareState
-
-    def _normalize_content(self, content: object) -> str:
-        if isinstance(content, str):
-            return content
-
-        if isinstance(content, list):
-            parts = [self._normalize_content(item) for item in content]
-            return "\n".join(part for part in parts if part)
-
-        if isinstance(content, dict):
-            text_value = content.get("text")
-            if isinstance(text_value, str):
-                return text_value
-
-            nested_content = content.get("content")
-            if nested_content is not None:
-                return self._normalize_content(nested_content)
-
-        return ""
-
-    def _should_generate_title(self, state: TitleMiddlewareState) -> bool:
-        """Check if we should generate a title for this thread."""
-        config = get_title_config()
-        if not config.enabled:
-            return False
-
-        # Check if thread already has a title in state
-        if state.get("title"):
-            return False
-
-        # Check if this is the first turn (has at least one user message and one assistant response)
-        messages = state.get("messages", [])
-        if len(messages) < 2:
-            return False
-
-        # Count user and assistant messages
-        user_messages = [m for m in messages if m.type == "human"]
-        assistant_messages = [m for m in messages if m.type == "ai"]
-
-        # Generate title after first complete exchange
-        return len(user_messages) == 1 and len(assistant_messages) >= 1
-
-    def _build_title_prompt(self, state: TitleMiddlewareState) -> tuple[str, str]:
-        """Extract user/assistant messages and build the title prompt.
-
-        Returns (prompt_string, user_msg) so callers can use user_msg as fallback.
-        """
-        config = get_title_config()
-        messages = state.get("messages", [])
-
-        user_msg_content = next((m.content for m in messages if m.type == "human"), "")
-        assistant_msg_content = next((m.content for m in messages if m.type == "ai"), "")
-
-        user_msg = self._normalize_content(user_msg_content)
-        assistant_msg = self._normalize_content(assistant_msg_content)
-
-        prompt = config.prompt_template.format(
-            max_words=config.max_words,
-            user_msg=user_msg[:500],
-            assistant_msg=assistant_msg[:500],
-        )
-        return prompt, user_msg
-
-    def _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 = title_content.strip().strip('"').strip("'")
-        return title[: config.max_chars] if len(title) > config.max_chars else title
-
-    def _fallback_title(self, user_msg: str) -> str:
-        config = get_title_config()
-        fallback_chars = min(config.max_chars, 50)
-        if len(user_msg) > fallback_chars:
-            return user_msg[:fallback_chars].rstrip() + "..."
-        return user_msg if user_msg else "New Conversation"
-
-    def _generate_title_result(self, state: TitleMiddlewareState) -> dict | None:
-        """Synchronously generate a title. Returns state update or None."""
-        if not self._should_generate_title(state):
-            return None
-
-        prompt, user_msg = self._build_title_prompt(state)
-        config = get_title_config()
-        model = create_chat_model(name=config.model_name, thinking_enabled=False)
-
-        try:
-            response = model.invoke(prompt)
-            title = self._parse_title(response.content)
-            if not title:
-                title = self._fallback_title(user_msg)
-        except Exception:
-            logger.exception("Failed to generate title (sync)")
-            title = self._fallback_title(user_msg)
-
-        return {"title": title}
-
-    async def _agenerate_title_result(self, state: TitleMiddlewareState) -> dict | None:
-        """Asynchronously generate a title. Returns state update or None."""
-        if not self._should_generate_title(state):
-            return None
-
-        prompt, user_msg = self._build_title_prompt(state)
-        config = get_title_config()
-        model = create_chat_model(name=config.model_name, thinking_enabled=False)
-
-        try:
-            response = await model.ainvoke(prompt)
-            title = self._parse_title(response.content)
-            if not title:
-                title = self._fallback_title(user_msg)
-        except Exception:
-            logger.exception("Failed to generate title (async)")
-            title = self._fallback_title(user_msg)
-
-        return {"title": title}
-
-    @override
-    def after_model(self, state: TitleMiddlewareState, runtime: Runtime) -> dict | None:
-        return self._generate_title_result(state)
-
-    @override
-    async def aafter_model(self, state: TitleMiddlewareState, runtime: Runtime) -> dict | None:
-        return await self._agenerate_title_result(state)

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

@@ -1,100 +0,0 @@
-"""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.
-"""
-
-from __future__ import annotations
-
-from typing import Any, override
-
-from langchain.agents.middleware import TodoListMiddleware
-from langchain.agents.middleware.todo import PlanningState, Todo
-from langchain_core.messages import AIMessage, HumanMessage
-from langgraph.runtime import Runtime
-
-
-def _todos_in_messages(messages: list[Any]) -> bool:
-    """Return True if any AIMessage in *messages* contains a write_todos tool call."""
-    for msg in messages:
-        if isinstance(msg, AIMessage) and msg.tool_calls:
-            for tc in msg.tool_calls:
-                if tc.get("name") == "write_todos":
-                    return True
-    return False
-
-
-def _reminder_in_messages(messages: list[Any]) -> bool:
-    """Return True if a todo_reminder HumanMessage is already present in *messages*."""
-    for msg in messages:
-        if isinstance(msg, HumanMessage) and getattr(msg, "name", None) == "todo_reminder":
-            return True
-    return False
-
-
-def _format_todos(todos: list[Todo]) -> str:
-    """Format a list of Todo items into a human-readable string."""
-    lines: list[str] = []
-    for todo in todos:
-        status = todo.get("status", "pending")
-        content = todo.get("content", "")
-        lines.append(f"- [{status}] {content}")
-    return "\n".join(lines)
-
-
-class TodoMiddleware(TodoListMiddleware):
-    """Extends TodoListMiddleware with `write_todos` context-loss detection.
-
-    When the original `write_todos` tool call has been truncated from the message
-    history (e.g., after summarization), the model loses awareness of the current
-    todo list. This middleware detects that gap in `before_model` / `abefore_model`
-    and injects a reminder message so the model can continue tracking progress.
-    """
-
-    @override
-    def before_model(
-        self,
-        state: PlanningState,
-        runtime: Runtime,  # 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]
-        if not todos:
-            return None
-
-        messages = state.get("messages") or []
-        if _todos_in_messages(messages):
-            # write_todos is still visible in context — nothing to do.
-            return None
-
-        if _reminder_in_messages(messages):
-            # A reminder was already injected and hasn't been truncated yet.
-            return None
-
-        # The todo list exists in state but the original write_todos call is gone.
-        # Inject a reminder as a HumanMessage so the model stays aware.
-        formatted = _format_todos(todos)
-        reminder = HumanMessage(
-            name="todo_reminder",
-            content=(
-                "<system_reminder>\n"
-                "Your todo list from earlier is no longer visible in the current context window, "
-                "but it is still active. Here is the current state:\n\n"
-                f"{formatted}\n\n"
-                "Continue tracking and updating this todo list as you work. "
-                "Call `write_todos` whenever the status of any item changes.\n"
-                "</system_reminder>"
-            ),
-        )
-        return {"messages": [reminder]}
-
-    @override
-    async def abefore_model(
-        self,
-        state: PlanningState,
-        runtime: Runtime,
-    ) -> dict[str, Any] | None:
-        """Async version of before_model."""
-        return self.before_model(state, runtime)

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

@@ -1,37 +0,0 @@
-"""Middleware for logging LLM token usage."""
-
-import logging
-from typing import override
-
-from langchain.agents import AgentState
-from langchain.agents.middleware import AgentMiddleware
-from langgraph.runtime import Runtime
-
-logger = logging.getLogger(__name__)
-
-
-class TokenUsageMiddleware(AgentMiddleware):
-    """Logs token usage from model response usage_metadata."""
-
-    @override
-    def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
-        return self._log_usage(state)
-
-    @override
-    async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict | None:
-        return self._log_usage(state)
-
-    def _log_usage(self, state: AgentState) -> None:
-        messages = state.get("messages", [])
-        if not messages:
-            return None
-        last = messages[-1]
-        usage = getattr(last, "usage_metadata", None)
-        if usage:
-            logger.info(
-                "LLM token usage: input=%s output=%s total=%s",
-                usage.get("input_tokens", "?"),
-                usage.get("output_tokens", "?"),
-                usage.get("total_tokens", "?"),
-            )
-        return None

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

@@ -1,140 +0,0 @@
-"""Tool error handling middleware and shared runtime middleware builders."""
-
-import logging
-from collections.abc import Awaitable, Callable
-from typing import override
-
-from langchain.agents import AgentState
-from langchain.agents.middleware import AgentMiddleware
-from langchain_core.messages import ToolMessage
-from langgraph.errors import GraphBubbleUp
-from langgraph.prebuilt.tool_node import ToolCallRequest
-from langgraph.types import Command
-
-logger = logging.getLogger(__name__)
-
-_MISSING_TOOL_CALL_ID = "missing_tool_call_id"
-
-
-class ToolErrorHandlingMiddleware(AgentMiddleware[AgentState]):
-    """Convert tool exceptions into error ToolMessages so the run can continue."""
-
-    def _build_error_message(self, request: ToolCallRequest, exc: Exception) -> ToolMessage:
-        tool_name = str(request.tool_call.get("name") or "unknown_tool")
-        tool_call_id = str(request.tool_call.get("id") or _MISSING_TOOL_CALL_ID)
-        detail = str(exc).strip() or exc.__class__.__name__
-        if len(detail) > 500:
-            detail = detail[:497] + "..."
-
-        content = f"Error: Tool '{tool_name}' failed with {exc.__class__.__name__}: {detail}. Continue with available context, or choose an alternative tool."
-        return ToolMessage(
-            content=content,
-            tool_call_id=tool_call_id,
-            name=tool_name,
-            status="error",
-        )
-
-    @override
-    def wrap_tool_call(
-        self,
-        request: ToolCallRequest,
-        handler: Callable[[ToolCallRequest], ToolMessage | Command],
-    ) -> ToolMessage | Command:
-        try:
-            return handler(request)
-        except GraphBubbleUp:
-            # Preserve LangGraph control-flow signals (interrupt/pause/resume).
-            raise
-        except Exception as exc:
-            logger.exception("Tool execution failed (sync): name=%s id=%s", request.tool_call.get("name"), request.tool_call.get("id"))
-            return self._build_error_message(request, exc)
-
-    @override
-    async def awrap_tool_call(
-        self,
-        request: ToolCallRequest,
-        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
-    ) -> ToolMessage | Command:
-        try:
-            return await handler(request)
-        except GraphBubbleUp:
-            # Preserve LangGraph control-flow signals (interrupt/pause/resume).
-            raise
-        except Exception as exc:
-            logger.exception("Tool execution failed (async): name=%s id=%s", request.tool_call.get("name"), request.tool_call.get("id"))
-            return self._build_error_message(request, exc)
-
-
-def _build_runtime_middlewares(
-    *,
-    include_uploads: bool,
-    include_dangling_tool_call_patch: bool,
-    lazy_init: bool = True,
-) -> list[AgentMiddleware]:
-    """Build shared base middlewares for agent execution."""
-    from deerflow.agents.middlewares.thread_data_middleware import ThreadDataMiddleware
-    from deerflow.sandbox.middleware import SandboxMiddleware
-
-    middlewares: list[AgentMiddleware] = [
-        ThreadDataMiddleware(lazy_init=lazy_init),
-        SandboxMiddleware(lazy_init=lazy_init),
-    ]
-
-    if include_uploads:
-        from deerflow.agents.middlewares.uploads_middleware import UploadsMiddleware
-
-        middlewares.insert(1, UploadsMiddleware())
-
-    if include_dangling_tool_call_patch:
-        from deerflow.agents.middlewares.dangling_tool_call_middleware import DanglingToolCallMiddleware
-
-        middlewares.append(DanglingToolCallMiddleware())
-
-    # Guardrail middleware (if configured)
-    from deerflow.config.guardrails_config import get_guardrails_config
-
-    guardrails_config = get_guardrails_config()
-    if guardrails_config.enabled and guardrails_config.provider:
-        import inspect
-
-        from deerflow.guardrails.middleware import GuardrailMiddleware
-        from deerflow.reflection import resolve_variable
-
-        provider_cls = resolve_variable(guardrails_config.provider.use)
-        provider_kwargs = dict(guardrails_config.provider.config) if guardrails_config.provider.config else {}
-        # Pass framework hint if the provider accepts it (e.g. for config discovery).
-        # Built-in providers like AllowlistProvider don't need it, so only inject
-        # when the constructor accepts 'framework' or '**kwargs'.
-        if "framework" not in provider_kwargs:
-            try:
-                sig = inspect.signature(provider_cls.__init__)
-                if "framework" in sig.parameters or any(p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()):
-                    provider_kwargs["framework"] = "deerflow"
-            except (ValueError, TypeError):
-                pass
-        provider = provider_cls(**provider_kwargs)
-        middlewares.append(GuardrailMiddleware(provider, fail_closed=guardrails_config.fail_closed, passport=guardrails_config.passport))
-
-    from deerflow.agents.middlewares.sandbox_audit_middleware import SandboxAuditMiddleware
-
-    middlewares.append(SandboxAuditMiddleware())
-    middlewares.append(ToolErrorHandlingMiddleware())
-    return middlewares
-
-
-def build_lead_runtime_middlewares(*, lazy_init: bool = True) -> list[AgentMiddleware]:
-    """Middlewares shared by lead agent runtime before lead-only middlewares."""
-    return _build_runtime_middlewares(
-        include_uploads=True,
-        include_dangling_tool_call_patch=True,
-        lazy_init=lazy_init,
-    )
-
-
-def build_subagent_runtime_middlewares(*, lazy_init: bool = True) -> list[AgentMiddleware]:
-    """Middlewares shared by subagent runtime before subagent-only middlewares."""
-    return _build_runtime_middlewares(
-        include_uploads=False,
-        include_dangling_tool_call_patch=False,
-        lazy_init=lazy_init,
-    )

backend/packages/harness/deerflow/community/ddg_search/__init__.py

@@ -1,3 +0,0 @@
-from .tools import web_search_tool
-
-__all__ = ["web_search_tool"]

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

@@ -1,95 +0,0 @@
-"""
-Web Search Tool - Search the web using DuckDuckGo (no API key required).
-"""
-
-import json
-import logging
-
-from langchain.tools import tool
-
-from deerflow.config import get_app_config
-
-logger = logging.getLogger(__name__)
-
-
-def _search_text(
-    query: str,
-    max_results: int = 5,
-    region: str = "wt-wt",
-    safesearch: str = "moderate",
-) -> list[dict]:
-    """
-    Execute text search using DuckDuckGo.
-
-    Args:
-        query: Search keywords
-        max_results: Maximum number of results
-        region: Search region
-        safesearch: Safe search level
-
-    Returns:
-        List of search results
-    """
-    try:
-        from ddgs import DDGS
-    except ImportError:
-        logger.error("ddgs library not installed. Run: pip install ddgs")
-        return []
-
-    ddgs = DDGS(timeout=30)
-
-    try:
-        results = ddgs.text(
-            query,
-            region=region,
-            safesearch=safesearch,
-            max_results=max_results,
-        )
-        return list(results) if results else []
-
-    except Exception as e:
-        logger.error(f"Failed to search web: {e}")
-        return []
-
-
-@tool("web_search", parse_docstring=True)
-def web_search_tool(
-    query: str,
-    max_results: int = 5,
-) -> str:
-    """Search the web for information. Use this tool to find current information, news, articles, and facts from the internet.
-
-    Args:
-        query: Search keywords describing what you want to find. Be specific for better results.
-        max_results: Maximum number of results to return. Default is 5.
-    """
-    config = get_app_config().get_tool_config("web_search")
-
-    # Override max_results from config if set
-    if config is not None and "max_results" in config.model_extra:
-        max_results = config.model_extra.get("max_results", max_results)
-
-    results = _search_text(
-        query=query,
-        max_results=max_results,
-    )
-
-    if not results:
-        return json.dumps({"error": "No results found", "query": query}, ensure_ascii=False)
-
-    normalized_results = [
-        {
-            "title": r.get("title", ""),
-            "url": r.get("href", r.get("link", "")),
-            "content": r.get("body", r.get("snippet", "")),
-        }
-        for r in results
-    ]
-
-    output = {
-        "query": query,
-        "total_results": len(normalized_results),
-        "results": normalized_results,
-    }
-
-    return json.dumps(output, indent=2, ensure_ascii=False)

backend/packages/harness/deerflow/community/infoquest/infoquest_client.py

@@ -1,404 +0,0 @@
-"""Util that calls InfoQuest Search And Fetch API.
-
-In order to set this up, follow instructions at:
-https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest
-"""
-
-import json
-import logging
-import os
-from typing import Any
-
-import requests
-
-logger = logging.getLogger(__name__)
-
-
-class InfoQuestClient:
-    """Client for interacting with the InfoQuest web search and fetch API."""
-
-    def __init__(self, fetch_time: int = -1, fetch_timeout: int = -1, fetch_navigation_timeout: int = -1, search_time_range: int = -1, image_search_time_range: int = -1, image_size: str = "i"):
-        logger.info("\n============================================\n🚀 BytePlus InfoQuest Client Initialization 🚀\n============================================")
-
-        self.fetch_time = fetch_time
-        self.fetch_timeout = fetch_timeout
-        self.fetch_navigation_timeout = fetch_navigation_timeout
-        self.search_time_range = search_time_range
-        self.image_search_time_range = image_search_time_range
-        self.image_size = image_size
-        self.api_key_set = bool(os.getenv("INFOQUEST_API_KEY"))
-        if logger.isEnabledFor(logging.DEBUG):
-            config_details = (
-                f"\n📋 Configuration Details:\n"
-                f"├── Fetch time: {fetch_time} {'(Default: No fetch time)' if fetch_time == -1 else '(Custom)'}\n"
-                f"├── Fetch Timeout: {fetch_timeout} {'(Default: No fetch timeout)' if fetch_timeout == -1 else '(Custom)'}\n"
-                f"├── Navigation Timeout: {fetch_navigation_timeout} {'(Default: No Navigation Timeout)' if fetch_navigation_timeout == -1 else '(Custom)'}\n"
-                f"├── Search Time Range: {search_time_range} {'(Default: No Search Time Range)' if search_time_range == -1 else '(Custom)'}\n"
-                f"├── Image Search Time Range: {image_search_time_range} {'(Default: No Image Search Time Range)' if image_search_time_range == -1 else '(Custom)'}\n"
-                f"├── Image Size: {image_size} {'(Default: Medium)' if image_size == 'm' else '(Custom)'}\n"
-                f"└── API Key: {'✅ Configured' if self.api_key_set else '❌ Not set'}"
-            )
-
-            logger.debug(config_details)
-            logger.debug("\n" + "*" * 70 + "\n")
-
-    def fetch(self, url: str, return_format: str = "html") -> str:
-        if logger.isEnabledFor(logging.DEBUG):
-            url_truncated = url[:50] + "..." if len(url) > 50 else url
-            logger.debug(
-                f"InfoQuest - Fetch API request initiated | "
-                f"operation=crawl url | "
-                f"url_truncated={url_truncated} | "
-                f"has_timeout_filter={self.fetch_timeout > 0} | timeout_filter={self.fetch_timeout} | "
-                f"has_fetch_time_filter={self.fetch_time > 0} | fetch_time_filter={self.fetch_time} | "
-                f"has_navigation_timeout_filter={self.fetch_navigation_timeout > 0} | navi_timeout_filter={self.fetch_navigation_timeout} | "
-                f"request_type=sync"
-            )
-
-        # Prepare headers
-        headers = self._prepare_headers()
-
-        # Prepare request data
-        data = self._prepare_crawl_request_data(url, return_format)
-
-        logger.debug("Sending crawl request to InfoQuest API")
-        try:
-            response = requests.post("https://reader.infoquest.bytepluses.com", headers=headers, json=data)
-
-            # Check if status code is not 200
-            if response.status_code != 200:
-                error_message = f"fetch API returned status {response.status_code}: {response.text}"
-                logger.debug("InfoQuest Crawler fetch API return status %d: %s for URL: %s", response.status_code, response.text, url)
-                return f"Error: {error_message}"
-
-            # Check for empty response
-            if not response.text or not response.text.strip():
-                error_message = "no result found"
-                logger.debug("InfoQuest Crawler returned empty response for URL: %s", url)
-                return f"Error: {error_message}"
-
-            # Try to parse response as JSON and extract reader_result
-            try:
-                response_data = json.loads(response.text)
-                # Extract reader_result if it exists
-                if "reader_result" in response_data:
-                    logger.debug("Successfully extracted reader_result from JSON response")
-                    return response_data["reader_result"]
-                elif "content" in response_data:
-                    # Fallback to content field if reader_result is not available
-                    logger.debug("reader_result missing in JSON response, falling back to content field: %s", response_data["content"])
-                    return response_data["content"]
-                else:
-                    # If neither field exists, return the original response
-                    logger.warning("Neither reader_result nor content field found in JSON response")
-            except json.JSONDecodeError:
-                # If response is not JSON, return the original text
-                logger.debug("Response is not in JSON format, returning as-is")
-                return response.text
-
-            # Print partial response for debugging
-            if logger.isEnabledFor(logging.DEBUG):
-                response_sample = response.text[:200] + ("..." if len(response.text) > 200 else "")
-                logger.debug("Successfully received response, content length: %d bytes, first 200 chars: %s", len(response.text), response_sample)
-            return response.text
-        except Exception as e:
-            error_message = f"fetch API failed: {str(e)}"
-            logger.error(error_message)
-            return f"Error: {error_message}"
-
-    @staticmethod
-    def _prepare_headers() -> dict[str, str]:
-        """Prepare request headers."""
-        headers = {
-            "Content-Type": "application/json",
-        }
-
-        # Add API key if available
-        if os.getenv("INFOQUEST_API_KEY"):
-            headers["Authorization"] = f"Bearer {os.getenv('INFOQUEST_API_KEY')}"
-            logger.debug("API key added to request headers")
-        else:
-            logger.warning("InfoQuest API key is not set. Provide your own key for authentication.")
-
-        return headers
-
-    def _prepare_crawl_request_data(self, url: str, return_format: str) -> dict[str, Any]:
-        """Prepare request data with formatted parameters."""
-        # Normalize return_format
-        if return_format and return_format.lower() == "html":
-            normalized_format = "HTML"
-        else:
-            normalized_format = return_format
-
-        data = {"url": url, "format": normalized_format}
-
-        # Add timeout parameters if set to positive values
-        timeout_params = {}
-        if self.fetch_time > 0:
-            timeout_params["fetch_time"] = self.fetch_time
-        if self.fetch_timeout > 0:
-            timeout_params["timeout"] = self.fetch_timeout
-        if self.fetch_navigation_timeout > 0:
-            timeout_params["navi_timeout"] = self.fetch_navigation_timeout
-
-        # Log applied timeout parameters
-        if timeout_params:
-            logger.debug("Applying timeout parameters: %s", timeout_params)
-            data.update(timeout_params)
-
-        return data
-
-    def web_search_raw_results(
-        self,
-        query: str,
-        site: str,
-        output_format: str = "JSON",
-    ) -> dict:
-        """Get results from the InfoQuest Web-Search API synchronously."""
-        headers = self._prepare_headers()
-
-        params = {"format": output_format, "query": query}
-        if self.search_time_range > 0:
-            params["time_range"] = self.search_time_range
-
-        if site != "":
-            params["site"] = site
-
-        response = requests.post("https://search.infoquest.bytepluses.com", headers=headers, json=params)
-        response.raise_for_status()
-
-        # Print partial response for debugging
-        response_json = response.json()
-        if logger.isEnabledFor(logging.DEBUG):
-            response_sample = json.dumps(response_json)[:200] + ("..." if len(json.dumps(response_json)) > 200 else "")
-            logger.debug(f"Search API request completed successfully | service=InfoQuest | status=success | response_sample={response_sample}")
-
-        return response_json
-
-    @staticmethod
-    def clean_results(raw_results: list[dict[str, dict[str, dict[str, Any]]]]) -> list[dict]:
-        """Clean results from InfoQuest Web-Search API."""
-        logger.debug("Processing web-search results")
-
-        seen_urls = set()
-        clean_results = []
-        counts = {"pages": 0, "news": 0}
-
-        for content_list in raw_results:
-            content = content_list["content"]
-            results = content["results"]
-
-            if results.get("organic"):
-                organic_results = results["organic"]
-                for result in organic_results:
-                    clean_result = {
-                        "type": "page",
-                    }
-                    if "title" in result:
-                        clean_result["title"] = result["title"]
-                    if "desc" in result:
-                        clean_result["desc"] = result["desc"]
-                        clean_result["snippet"] = result["desc"]
-                    if "url" in result:
-                        clean_result["url"] = result["url"]
-                        url = clean_result["url"]
-                        if isinstance(url, str) and url and url not in seen_urls:
-                            seen_urls.add(url)
-                            clean_results.append(clean_result)
-                            counts["pages"] += 1
-
-            if results.get("top_stories"):
-                news = results["top_stories"]
-                for obj in news["items"]:
-                    clean_result = {
-                        "type": "news",
-                    }
-                    if "time_frame" in obj:
-                        clean_result["time_frame"] = obj["time_frame"]
-                    if "source" in obj:
-                        clean_result["source"] = obj["source"]
-                    title = obj.get("title")
-                    url = obj.get("url")
-                    if title:
-                        clean_result["title"] = title
-                    if url:
-                        clean_result["url"] = url
-                    if title and isinstance(url, str) and url and url not in seen_urls:
-                        seen_urls.add(url)
-                        clean_results.append(clean_result)
-                        counts["news"] += 1
-        logger.debug(f"Results processing completed | total_results={len(clean_results)} | pages={counts['pages']} | news_items={counts['news']} | unique_urls={len(seen_urls)}")
-
-        return clean_results
-
-    def web_search(
-        self,
-        query: str,
-        site: str = "",
-        output_format: str = "JSON",
-    ) -> str:
-        if logger.isEnabledFor(logging.DEBUG):
-            query_truncated = query[:50] + "..." if len(query) > 50 else query
-            logger.debug(
-                f"InfoQuest - Search API request initiated | "
-                f"operation=search webs | "
-                f"query_truncated={query_truncated} | "
-                f"has_time_filter={self.search_time_range > 0} | time_filter={self.search_time_range} | "
-                f"has_site_filter={bool(site)} | site={site} | "
-                f"request_type=sync"
-            )
-
-        try:
-            logger.debug("InfoQuest Web-Search - Executing search with parameters")
-            raw_results = self.web_search_raw_results(
-                query,
-                site,
-                output_format,
-            )
-            if "search_result" in raw_results:
-                logger.debug("InfoQuest Web-Search - Successfully extracted search_result from JSON response")
-                results = raw_results["search_result"]
-
-                logger.debug("InfoQuest Web-Search - Processing raw search results")
-                cleaned_results = self.clean_results(results["results"])
-
-                result_json = json.dumps(cleaned_results, indent=2, ensure_ascii=False)
-
-                logger.debug(f"InfoQuest Web-Search - Search tool execution completed | mode=synchronous | results_count={len(cleaned_results)}")
-                return result_json
-
-            elif "content" in raw_results:
-                # Fallback to content field if search_result is not available
-                error_message = "web search API return wrong format"
-                logger.error("web search API return wrong format, no search_result nor content field found in JSON response, content: %s", raw_results["content"])
-                return f"Error: {error_message}"
-            else:
-                # If neither field exists, return the original response
-                logger.warning("InfoQuest Web-Search - Neither search_result nor content field found in JSON response")
-                return json.dumps(raw_results, indent=2, ensure_ascii=False)
-
-        except Exception as e:
-            error_message = f"InfoQuest Web-Search - Search tool execution failed | mode=synchronous | error={str(e)}"
-            logger.error(error_message)
-            return f"Error: {error_message}"
-
-    @staticmethod
-    def clean_results_with_image_search(raw_results: list[dict[str, dict[str, dict[str, Any]]]]) -> list[dict]:
-        """Clean results from InfoQuest Web-Search API."""
-        logger.debug("Processing web-search results")
-
-        seen_urls = set()
-        clean_results = []
-        counts = {"images": 0}
-
-        for content_list in raw_results:
-            content = content_list["content"]
-            results = content["results"]
-
-            if results.get("images_results"):
-                images_results = results["images_results"]
-                for result in images_results:
-                    clean_result = {}
-                    if "original" in result:
-                        clean_result["image_url"] = result["original"]
-                        url = clean_result["image_url"]
-                        if isinstance(url, str) and url and url not in seen_urls:
-                            seen_urls.add(url)
-                            clean_results.append(clean_result)
-                            counts["images"] += 1
-                    if "title" in result:
-                        clean_result["title"] = result["title"]
-        logger.debug(f"Results processing completed | total_results={len(clean_results)} | images={counts['images']} | unique_urls={len(seen_urls)}")
-
-        return clean_results
-
-    def image_search_raw_results(
-        self,
-        query: str,
-        site: str = "",
-        output_format: str = "JSON",
-    ) -> dict:
-        """Get image search results from the InfoQuest Web-Search API synchronously."""
-        headers = self._prepare_headers()
-
-        params = {"format": output_format, "query": query, "search_type": "Images"}
-
-        # Add time_range filter if specified (1-365)
-        if 1 <= self.image_search_time_range <= 365:
-            params["time_range"] = self.image_search_time_range
-        elif self.image_search_time_range > 0:
-            logger.warning(f"time_range {self.image_search_time_range} is out of valid range (1-365), ignoring")
-
-        # Add site filter if specified
-        if site:
-            params["site"] = site
-
-        # Add image_size filter if specified
-        if self.image_size and self.image_size in ["l", "m", "i"]:
-            params["image_size"] = self.image_size
-        elif self.image_size:
-            logger.warning(f"image_size {self.image_size} is not valid, must be 'l', 'm', or 'i'")
-
-        response = requests.post("https://search.infoquest.bytepluses.com", headers=headers, json=params)
-        response.raise_for_status()
-
-        # Print partial response for debugging
-        response_json = response.json()
-        if logger.isEnabledFor(logging.DEBUG):
-            response_sample = json.dumps(response_json)[:200] + ("..." if len(json.dumps(response_json)) > 200 else "")
-            logger.debug(f"Image Search API request completed successfully | service=InfoQuest | status=success | response_sample={response_sample}")
-
-        return response_json
-
-    def image_search(
-        self,
-        query: str,
-        site: str = "",
-        output_format: str = "JSON",
-    ) -> str:
-        if logger.isEnabledFor(logging.DEBUG):
-            query_truncated = query[:50] + "..." if len(query) > 50 else query
-            logger.debug(
-                f"InfoQuest - Image Search API request initiated | "
-                f"operation=search images | "
-                f"query_truncated={query_truncated} | "
-                f"has_site_filter={bool(site)} | site={site} | "
-                f"image_search_time_range={self.image_search_time_range if self.image_search_time_range >= 1 and self.image_search_time_range <= 365 else 'default'} | "
-                f"image_size={self.image_size} |"
-                f"request_type=sync"
-            )
-
-        try:
-            logger.info("InfoQuest Image Search - Executing search with parameters")
-            raw_results = self.image_search_raw_results(
-                query,
-                site,
-                output_format,
-            )
-
-            if "search_result" in raw_results:
-                logger.debug("InfoQuest Image Search - Successfully extracted search_result from JSON response")
-                results = raw_results["search_result"]
-
-                logger.debug(f"InfoQuest Image Search - Processing raw image search results: {results}")
-                cleaned_results = self.clean_results_with_image_search(results["results"])
-
-                result_json = json.dumps(cleaned_results, indent=2, ensure_ascii=False)
-
-                logger.debug(f"InfoQuest Image Search - Image search tool execution completed | mode=synchronous | results_count={len(cleaned_results)}")
-                return result_json
-
-            elif "content" in raw_results:
-                # Fallback to content field if search_result is not available
-                error_message = "image search API return wrong format"
-                logger.error("image search API return wrong format, no search_result nor content field found in JSON response, content: %s", raw_results["content"])
-                return f"Error: {error_message}"
-            else:
-                # If neither field exists, return the original response
-                logger.warning("InfoQuest Image Search - Neither search_result nor content field found in JSON response")
-                return json.dumps(raw_results, indent=2, ensure_ascii=False)
-
-        except Exception as e:
-            error_message = f"InfoQuest Image Search - Image search tool execution failed | mode=synchronous | error={str(e)}"
-            logger.error(error_message)
-            return f"Error: {error_message}"

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

@@ -1,93 +0,0 @@
-from langchain.tools import tool
-
-from deerflow.config import get_app_config
-from deerflow.utils.readability import ReadabilityExtractor
-
-from .infoquest_client import InfoQuestClient
-
-readability_extractor = ReadabilityExtractor()
-
-
-def _get_infoquest_client() -> InfoQuestClient:
-    search_config = get_app_config().get_tool_config("web_search")
-    search_time_range = -1
-    if search_config is not None and "search_time_range" in search_config.model_extra:
-        search_time_range = search_config.model_extra.get("search_time_range")
-
-    fetch_config = get_app_config().get_tool_config("web_fetch")
-    fetch_time = -1
-    if fetch_config is not None and "fetch_time" in fetch_config.model_extra:
-        fetch_time = fetch_config.model_extra.get("fetch_time")
-    fetch_timeout = -1
-    if fetch_config is not None and "timeout" in fetch_config.model_extra:
-        fetch_timeout = fetch_config.model_extra.get("timeout")
-    navigation_timeout = -1
-    if fetch_config is not None and "navigation_timeout" in fetch_config.model_extra:
-        navigation_timeout = fetch_config.model_extra.get("navigation_timeout")
-
-    image_search_config = get_app_config().get_tool_config("image_search")
-    image_search_time_range = -1
-    if image_search_config is not None and "image_search_time_range" in image_search_config.model_extra:
-        image_search_time_range = image_search_config.model_extra.get("image_search_time_range")
-    image_size = "i"
-    if image_search_config is not None and "image_size" in image_search_config.model_extra:
-        image_size = image_search_config.model_extra.get("image_size")
-
-    return InfoQuestClient(
-        search_time_range=search_time_range,
-        fetch_timeout=fetch_timeout,
-        fetch_navigation_timeout=navigation_timeout,
-        fetch_time=fetch_time,
-        image_search_time_range=image_search_time_range,
-        image_size=image_size,
-    )
-
-
-@tool("web_search", parse_docstring=True)
-def web_search_tool(query: str) -> str:
-    """Search the web.
-
-    Args:
-        query: The query to search for.
-    """
-
-    client = _get_infoquest_client()
-    return client.web_search(query)
-
-
-@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.
-    """
-    client = _get_infoquest_client()
-    result = client.fetch(url)
-    if result.startswith("Error: "):
-        return result
-    article = readability_extractor.extract_article(result)
-    return article.to_markdown()[:4096]
-
-
-@tool("image_search", parse_docstring=True)
-def image_search_tool(query: str) -> str:
-    """Search for images online. Use this tool BEFORE image generation to find reference images for characters, portraits, objects, scenes, or any content requiring visual accuracy.
-
-    **When to use:**
-    - Before generating character/portrait images: search for similar poses, expressions, styles
-    - Before generating specific objects/products: search for accurate visual references
-    - Before generating scenes/locations: search for architectural or environmental references
-    - Before generating fashion/clothing: search for style and detail references
-
-    The returned image URLs can be used as reference images in image generation to significantly improve quality.
-
-    Args:
-        query: The query to search for images.
-    """
-    client = _get_infoquest_client()
-    return client.image_search(query)

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

@@ -1,51 +0,0 @@
-"""ACP (Agent Client Protocol) agent configuration loaded from config.yaml."""
-
-import logging
-from collections.abc import Mapping
-
-from pydantic import BaseModel, Field
-
-logger = logging.getLogger(__name__)
-
-
-class ACPAgentConfig(BaseModel):
-    """Configuration for a single ACP-compatible agent."""
-
-    command: str = Field(description="Command to launch the ACP agent subprocess")
-    args: list[str] = Field(default_factory=list, description="Additional command arguments")
-    env: dict[str, str] = Field(default_factory=dict, description="Environment variables to inject into the agent subprocess. Values starting with $ are resolved from host environment variables.")
-    description: str = Field(description="Description of the agent's capabilities (shown in tool description)")
-    model: str | None = Field(default=None, description="Model hint passed to the agent (optional)")
-    auto_approve_permissions: bool = Field(
-        default=False,
-        description=(
-            "When True, DeerFlow automatically approves all ACP permission requests from this agent "
-            "(allow_once preferred over allow_always). When False (default), all permission requests "
-            "are denied — the agent must be configured to operate without requesting permissions."
-        ),
-    )
-
-
-_acp_agents: dict[str, ACPAgentConfig] = {}
-
-
-def get_acp_agents() -> dict[str, ACPAgentConfig]:
-    """Get the currently configured ACP agents.
-
-    Returns:
-        Mapping of agent name -> ACPAgentConfig.  Empty dict if no ACP agents are configured.
-    """
-    return _acp_agents
-
-
-def load_acp_config_from_dict(config_dict: Mapping[str, Mapping[str, object]] | None) -> None:
-    """Load ACP agent configuration from a dictionary (typically from config.yaml).
-
-    Args:
-        config_dict: Mapping of agent name -> config fields.
-    """
-    global _acp_agents
-    if config_dict is None:
-        config_dict = {}
-    _acp_agents = {name: ACPAgentConfig(**cfg) for name, cfg in config_dict.items()}
-    logger.info("ACP config loaded: %d agent(s): %s", len(_acp_agents), list(_acp_agents.keys()))

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

@@ -1,46 +0,0 @@
-"""Configuration for LangGraph checkpointer."""
-
-from typing import Literal
-
-from pydantic import BaseModel, Field
-
-CheckpointerType = Literal["memory", "sqlite", "postgres"]
-
-
-class CheckpointerConfig(BaseModel):
-    """Configuration for LangGraph state persistence checkpointer."""
-
-    type: CheckpointerType = Field(
-        description="Checkpointer backend type. "
-        "'memory' is in-process only (lost on restart). "
-        "'sqlite' persists to a local file (requires langgraph-checkpoint-sqlite). "
-        "'postgres' persists to PostgreSQL (requires langgraph-checkpoint-postgres)."
-    )
-    connection_string: str | None = Field(
-        default=None,
-        description="Connection string for sqlite (file path) or postgres (DSN). "
-        "Required for sqlite and postgres types. "
-        "For sqlite, use a file path like '.deer-flow/checkpoints.db' or ':memory:' for in-memory. "
-        "For postgres, use a DSN like 'postgresql://user:pass@localhost:5432/db'.",
-    )
-
-
-# Global configuration instance — None means no checkpointer is configured.
-_checkpointer_config: CheckpointerConfig | None = None
-
-
-def get_checkpointer_config() -> CheckpointerConfig | None:
-    """Get the current checkpointer configuration, or None if not configured."""
-    return _checkpointer_config
-
-
-def set_checkpointer_config(config: CheckpointerConfig | None) -> None:
-    """Set the checkpointer configuration."""
-    global _checkpointer_config
-    _checkpointer_config = config
-
-
-def load_checkpointer_config_from_dict(config_dict: dict) -> None:
-    """Load checkpointer configuration from a dictionary."""
-    global _checkpointer_config
-    _checkpointer_config = CheckpointerConfig(**config_dict)

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

@@ -1,48 +0,0 @@
-"""Configuration for pre-tool-call authorization."""
-
-from pydantic import BaseModel, Field
-
-
-class GuardrailProviderConfig(BaseModel):
-    """Configuration for a guardrail provider."""
-
-    use: str = Field(description="Class path (e.g. 'deerflow.guardrails.builtin:AllowlistProvider')")
-    config: dict = Field(default_factory=dict, description="Provider-specific settings passed as kwargs")
-
-
-class GuardrailsConfig(BaseModel):
-    """Configuration for pre-tool-call authorization.
-
-    When enabled, every tool call passes through the configured provider
-    before execution. The provider receives tool name, arguments, and the
-    agent's passport reference, and returns an allow/deny decision.
-    """
-
-    enabled: bool = Field(default=False, description="Enable guardrail middleware")
-    fail_closed: bool = Field(default=True, description="Block tool calls if provider errors")
-    passport: str | None = Field(default=None, description="OAP passport path or hosted agent ID")
-    provider: GuardrailProviderConfig | None = Field(default=None, description="Guardrail provider configuration")
-
-
-_guardrails_config: GuardrailsConfig | None = None
-
-
-def get_guardrails_config() -> GuardrailsConfig:
-    """Get the guardrails config, returning defaults if not loaded."""
-    global _guardrails_config
-    if _guardrails_config is None:
-        _guardrails_config = GuardrailsConfig()
-    return _guardrails_config
-
-
-def load_guardrails_config_from_dict(data: dict) -> GuardrailsConfig:
-    """Load guardrails config from a dict (called during AppConfig loading)."""
-    global _guardrails_config
-    _guardrails_config = GuardrailsConfig.model_validate(data)
-    return _guardrails_config
-
-
-def reset_guardrails_config() -> None:
-    """Reset the cached config instance. Used in tests to prevent singleton leaks."""
-    global _guardrails_config
-    _guardrails_config = None

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

@@ -1,46 +0,0 @@
-"""Configuration for stream bridge."""
-
-from typing import Literal
-
-from pydantic import BaseModel, Field
-
-StreamBridgeType = Literal["memory", "redis"]
-
-
-class StreamBridgeConfig(BaseModel):
-    """Configuration for the stream bridge that connects agent workers to SSE endpoints."""
-
-    type: StreamBridgeType = Field(
-        default="memory",
-        description="Stream bridge backend type. 'memory' uses in-process asyncio.Queue (single-process only). 'redis' uses Redis Streams (planned for Phase 2, not yet implemented).",
-    )
-    redis_url: str | None = Field(
-        default=None,
-        description="Redis URL for the redis stream bridge type. Example: 'redis://localhost:6379/0'.",
-    )
-    queue_maxsize: int = Field(
-        default=256,
-        description="Maximum number of events buffered per run in the memory bridge.",
-    )
-
-
-# Global configuration instance — None means no stream bridge is configured
-# (falls back to memory with defaults).
-_stream_bridge_config: StreamBridgeConfig | None = None
-
-
-def get_stream_bridge_config() -> StreamBridgeConfig | None:
-    """Get the current stream bridge configuration, or None if not configured."""
-    return _stream_bridge_config
-
-
-def set_stream_bridge_config(config: StreamBridgeConfig | None) -> None:
-    """Set the stream bridge configuration."""
-    global _stream_bridge_config
-    _stream_bridge_config = config
-
-
-def load_stream_bridge_config_from_dict(config_dict: dict) -> None:
-    """Load stream bridge configuration from a dictionary."""
-    global _stream_bridge_config
-    _stream_bridge_config = StreamBridgeConfig(**config_dict)

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

@@ -1,7 +0,0 @@
-from pydantic import BaseModel, Field
-
-
-class TokenUsageConfig(BaseModel):
-    """Configuration for token usage tracking."""
-
-    enabled: bool = Field(default=False, description="Enable token usage tracking middleware")

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

@@ -1,35 +0,0 @@
-"""Configuration for deferred tool loading via tool_search."""
-
-from pydantic import BaseModel, Field
-
-
-class ToolSearchConfig(BaseModel):
-    """Configuration for deferred tool loading via tool_search.
-
-    When enabled, MCP tools are not loaded into the agent's context directly.
-    Instead, they are listed by name in the system prompt and discoverable
-    via the tool_search tool at runtime.
-    """
-
-    enabled: bool = Field(
-        default=False,
-        description="Defer tools and enable tool_search",
-    )
-
-
-_tool_search_config: ToolSearchConfig | None = None
-
-
-def get_tool_search_config() -> ToolSearchConfig:
-    """Get the tool search config, loading from AppConfig if needed."""
-    global _tool_search_config
-    if _tool_search_config is None:
-        _tool_search_config = ToolSearchConfig()
-    return _tool_search_config
-
-
-def load_tool_search_config_from_dict(data: dict) -> ToolSearchConfig:
-    """Load tool search config from a dict (called during AppConfig loading)."""
-    global _tool_search_config
-    _tool_search_config = ToolSearchConfig.model_validate(data)
-    return _tool_search_config

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

@@ -1,94 +0,0 @@
-import logging
-import os
-import threading
-
-from pydantic import BaseModel, Field
-
-logger = logging.getLogger(__name__)
-_config_lock = threading.Lock()
-
-
-class TracingConfig(BaseModel):
-    """Configuration for LangSmith tracing."""
-
-    enabled: bool = Field(...)
-    api_key: str | None = Field(...)
-    project: str = Field(...)
-    endpoint: str = Field(...)
-
-    @property
-    def is_configured(self) -> bool:
-        """Check if tracing is fully configured (enabled and has API key)."""
-        return self.enabled and bool(self.api_key)
-
-
-_tracing_config: TracingConfig | None = None
-
-
-_TRUTHY_VALUES = {"1", "true", "yes", "on"}
-
-
-def _env_flag_preferred(*names: str) -> bool:
-    """Return the boolean value of the first env var that is present and non-empty.
-
-    Accepted truthy values (case-insensitive): ``1``, ``true``, ``yes``, ``on``.
-    Any other non-empty value is treated as falsy.  If none of the named
-    variables is set, returns ``False``.
-    """
-    for name in names:
-        value = os.environ.get(name)
-        if value is not None and value.strip():
-            return value.strip().lower() in _TRUTHY_VALUES
-    return False
-
-
-def _first_env_value(*names: str) -> str | None:
-    """Return the first non-empty environment value from candidate names."""
-    for name in names:
-        value = os.environ.get(name)
-        if value and value.strip():
-            return value.strip()
-    return None
-
-
-def get_tracing_config() -> TracingConfig:
-    """Get the current tracing configuration from environment variables.
-
-    ``LANGSMITH_*`` variables take precedence over their legacy ``LANGCHAIN_*``
-    counterparts.  For boolean flags (``enabled``), the *first* variable that is
-    present and non-empty in the priority list is the sole authority – its value
-    is parsed and returned without consulting the remaining candidates.  Accepted
-    truthy values are ``1``, ``true``, ``yes``, and ``on`` (case-insensitive);
-    any other non-empty value is treated as falsy.
-
-    Priority order:
-        enabled  : LANGSMITH_TRACING > LANGCHAIN_TRACING_V2 > LANGCHAIN_TRACING
-        api_key  : LANGSMITH_API_KEY  > LANGCHAIN_API_KEY
-        project  : LANGSMITH_PROJECT  > LANGCHAIN_PROJECT   (default: "deer-flow")
-        endpoint : LANGSMITH_ENDPOINT > LANGCHAIN_ENDPOINT  (default: https://api.smith.langchain.com)
-
-    Returns:
-        TracingConfig with current settings.
-    """
-    global _tracing_config
-    if _tracing_config is not None:
-        return _tracing_config
-    with _config_lock:
-        if _tracing_config is not None:  # Double-check after acquiring lock
-            return _tracing_config
-        _tracing_config = TracingConfig(
-            # Keep compatibility with both legacy LANGCHAIN_* and newer LANGSMITH_* variables.
-            enabled=_env_flag_preferred("LANGSMITH_TRACING", "LANGCHAIN_TRACING_V2", "LANGCHAIN_TRACING"),
-            api_key=_first_env_value("LANGSMITH_API_KEY", "LANGCHAIN_API_KEY"),
-            project=_first_env_value("LANGSMITH_PROJECT", "LANGCHAIN_PROJECT") or "deer-flow",
-            endpoint=_first_env_value("LANGSMITH_ENDPOINT", "LANGCHAIN_ENDPOINT") or "https://api.smith.langchain.com",
-        )
-        return _tracing_config
-
-
-def is_tracing_enabled() -> bool:
-    """Check if LangSmith tracing is enabled and configured.
-    Returns:
-        True if tracing is enabled and has an API key.
-    """
-    return get_tracing_config().is_configured

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

@@ -1,14 +0,0 @@
-"""Pre-tool-call authorization middleware."""
-
-from deerflow.guardrails.builtin import AllowlistProvider
-from deerflow.guardrails.middleware import GuardrailMiddleware
-from deerflow.guardrails.provider import GuardrailDecision, GuardrailProvider, GuardrailReason, GuardrailRequest
-
-__all__ = [
-    "AllowlistProvider",
-    "GuardrailDecision",
-    "GuardrailMiddleware",
-    "GuardrailProvider",
-    "GuardrailReason",
-    "GuardrailRequest",
-]

backend/packages/harness/deerflow/guardrails/builtin.py

@@ -1,23 +0,0 @@
-"""Built-in guardrail providers that ship with DeerFlow."""
-
-from deerflow.guardrails.provider import GuardrailDecision, GuardrailReason, GuardrailRequest
-
-
-class AllowlistProvider:
-    """Simple allowlist/denylist provider. No external dependencies."""
-
-    name = "allowlist"
-
-    def __init__(self, *, allowed_tools: list[str] | None = None, denied_tools: list[str] | None = None):
-        self._allowed = set(allowed_tools) if allowed_tools else None
-        self._denied = set(denied_tools) if denied_tools else set()
-
-    def evaluate(self, request: GuardrailRequest) -> GuardrailDecision:
-        if self._allowed is not None and request.tool_name not in self._allowed:
-            return GuardrailDecision(allow=False, reasons=[GuardrailReason(code="oap.tool_not_allowed", message=f"tool '{request.tool_name}' not in allowlist")])
-        if request.tool_name in self._denied:
-            return GuardrailDecision(allow=False, reasons=[GuardrailReason(code="oap.tool_not_allowed", message=f"tool '{request.tool_name}' is denied")])
-        return GuardrailDecision(allow=True, reasons=[GuardrailReason(code="oap.allowed")])
-
-    async def aevaluate(self, request: GuardrailRequest) -> GuardrailDecision:
-        return self.evaluate(request)

backend/packages/harness/deerflow/guardrails/middleware.py

@@ -1,98 +0,0 @@
-"""GuardrailMiddleware - evaluates tool calls against a GuardrailProvider before execution."""
-
-import logging
-from collections.abc import Awaitable, Callable
-from datetime import UTC, datetime
-from typing import override
-
-from langchain.agents import AgentState
-from langchain.agents.middleware import AgentMiddleware
-from langchain_core.messages import ToolMessage
-from langgraph.errors import GraphBubbleUp
-from langgraph.prebuilt.tool_node import ToolCallRequest
-from langgraph.types import Command
-
-from deerflow.guardrails.provider import GuardrailDecision, GuardrailProvider, GuardrailReason, GuardrailRequest
-
-logger = logging.getLogger(__name__)
-
-
-class GuardrailMiddleware(AgentMiddleware[AgentState]):
-    """Evaluate tool calls against a GuardrailProvider before execution.
-
-    Denied calls return an error ToolMessage so the agent can adapt.
-    If the provider raises, behavior depends on fail_closed:
-      - True (default): block the call
-      - False: allow it through with a warning
-    """
-
-    def __init__(self, provider: GuardrailProvider, *, fail_closed: bool = True, passport: str | None = None):
-        self.provider = provider
-        self.fail_closed = fail_closed
-        self.passport = passport
-
-    def _build_request(self, request: ToolCallRequest) -> GuardrailRequest:
-        return GuardrailRequest(
-            tool_name=str(request.tool_call.get("name", "")),
-            tool_input=request.tool_call.get("args", {}),
-            agent_id=self.passport,
-            timestamp=datetime.now(UTC).isoformat(),
-        )
-
-    def _build_denied_message(self, request: ToolCallRequest, decision: GuardrailDecision) -> ToolMessage:
-        tool_name = str(request.tool_call.get("name", "unknown_tool"))
-        tool_call_id = str(request.tool_call.get("id", "missing_id"))
-        reason_text = decision.reasons[0].message if decision.reasons else "blocked by guardrail policy"
-        reason_code = decision.reasons[0].code if decision.reasons else "oap.denied"
-        return ToolMessage(
-            content=f"Guardrail denied: tool '{tool_name}' was blocked ({reason_code}). Reason: {reason_text}. Choose an alternative approach.",
-            tool_call_id=tool_call_id,
-            name=tool_name,
-            status="error",
-        )
-
-    @override
-    def wrap_tool_call(
-        self,
-        request: ToolCallRequest,
-        handler: Callable[[ToolCallRequest], ToolMessage | Command],
-    ) -> ToolMessage | Command:
-        gr = self._build_request(request)
-        try:
-            decision = self.provider.evaluate(gr)
-        except GraphBubbleUp:
-            # Preserve LangGraph control-flow signals (interrupt/pause/resume).
-            raise
-        except Exception:
-            logger.exception("Guardrail provider error (sync)")
-            if self.fail_closed:
-                decision = GuardrailDecision(allow=False, reasons=[GuardrailReason(code="oap.evaluator_error", message="guardrail provider error (fail-closed)")])
-            else:
-                return handler(request)
-        if not decision.allow:
-            logger.warning("Guardrail denied: tool=%s policy=%s code=%s", gr.tool_name, decision.policy_id, decision.reasons[0].code if decision.reasons else "unknown")
-            return self._build_denied_message(request, decision)
-        return handler(request)
-
-    @override
-    async def awrap_tool_call(
-        self,
-        request: ToolCallRequest,
-        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
-    ) -> ToolMessage | Command:
-        gr = self._build_request(request)
-        try:
-            decision = await self.provider.aevaluate(gr)
-        except GraphBubbleUp:
-            # Preserve LangGraph control-flow signals (interrupt/pause/resume).
-            raise
-        except Exception:
-            logger.exception("Guardrail provider error (async)")
-            if self.fail_closed:
-                decision = GuardrailDecision(allow=False, reasons=[GuardrailReason(code="oap.evaluator_error", message="guardrail provider error (fail-closed)")])
-            else:
-                return await handler(request)
-        if not decision.allow:
-            logger.warning("Guardrail denied: tool=%s policy=%s code=%s", gr.tool_name, decision.policy_id, decision.reasons[0].code if decision.reasons else "unknown")
-            return self._build_denied_message(request, decision)
-        return await handler(request)

backend/packages/harness/deerflow/guardrails/provider.py

@@ -1,56 +0,0 @@
-"""GuardrailProvider protocol and data structures for pre-tool-call authorization."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import Any, Protocol, runtime_checkable
-
-
-@dataclass
-class GuardrailRequest:
-    """Context passed to the provider for each tool call."""
-
-    tool_name: str
-    tool_input: dict[str, Any]
-    agent_id: str | None = None
-    thread_id: str | None = None
-    is_subagent: bool = False
-    timestamp: str = ""
-
-
-@dataclass
-class GuardrailReason:
-    """Structured reason for an allow/deny decision (OAP reason object)."""
-
-    code: str
-    message: str = ""
-
-
-@dataclass
-class GuardrailDecision:
-    """Provider's allow/deny verdict (aligned with OAP Decision object)."""
-
-    allow: bool
-    reasons: list[GuardrailReason] = field(default_factory=list)
-    policy_id: str | None = None
-    metadata: dict[str, Any] = field(default_factory=dict)
-
-
-@runtime_checkable
-class GuardrailProvider(Protocol):
-    """Contract for pluggable tool-call authorization.
-
-    Any class with these methods works - no base class required.
-    Providers are loaded by class path via resolve_variable(),
-    the same mechanism DeerFlow uses for models, tools, and sandbox.
-    """
-
-    name: str
-
-    def evaluate(self, request: GuardrailRequest) -> GuardrailDecision:
-        """Evaluate whether a tool call should proceed."""
-        ...
-
-    async def aevaluate(self, request: GuardrailRequest) -> GuardrailDecision:
-        """Async variant."""
-        ...

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

@@ -1,348 +0,0 @@
-"""Custom Claude provider with OAuth Bearer auth, prompt caching, and smart thinking.
-
-Supports two authentication modes:
-  1. Standard API key (x-api-key header) — default ChatAnthropic behavior
-  2. Claude Code OAuth token (Authorization: Bearer header)
-     - Detected by sk-ant-oat prefix
-     - Requires anthropic-beta: oauth-2025-04-20,claude-code-20250219
-     - Requires billing header in system prompt for all OAuth requests
-
-Auto-loads credentials from explicit runtime handoff:
-  - $ANTHROPIC_API_KEY environment variable
-  - $CLAUDE_CODE_OAUTH_TOKEN or $ANTHROPIC_AUTH_TOKEN
-  - $CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR
-  - $CLAUDE_CODE_CREDENTIALS_PATH
-  - ~/.claude/.credentials.json
-"""
-
-import hashlib
-import json
-import logging
-import os
-import socket
-import time
-import uuid
-from typing import Any
-
-import anthropic
-from langchain_anthropic import ChatAnthropic
-from langchain_core.messages import BaseMessage
-from pydantic import PrivateAttr
-
-logger = logging.getLogger(__name__)
-
-MAX_RETRIES = 3
-THINKING_BUDGET_RATIO = 0.8
-
-# Billing header required by Anthropic API for OAuth token access.
-# Must be the first system prompt block. Format mirrors Claude Code CLI.
-# Override with ANTHROPIC_BILLING_HEADER env var if the hardcoded version drifts.
-_DEFAULT_BILLING_HEADER = "x-anthropic-billing-header: cc_version=2.1.85.351; cc_entrypoint=cli; cch=6c6d5;"
-OAUTH_BILLING_HEADER = os.environ.get("ANTHROPIC_BILLING_HEADER", _DEFAULT_BILLING_HEADER)
-
-
-class ClaudeChatModel(ChatAnthropic):
-    """ChatAnthropic with OAuth Bearer auth, prompt caching, and smart thinking.
-
-    Config example:
-        - name: claude-sonnet-4.6
-          use: deerflow.models.claude_provider:ClaudeChatModel
-          model: claude-sonnet-4-6
-          max_tokens: 16384
-          enable_prompt_caching: true
-    """
-
-    # Custom fields
-    enable_prompt_caching: bool = True
-    prompt_cache_size: int = 3
-    auto_thinking_budget: bool = True
-    retry_max_attempts: int = MAX_RETRIES
-    _is_oauth: bool = PrivateAttr(default=False)
-    _oauth_access_token: str = PrivateAttr(default="")
-
-    model_config = {"arbitrary_types_allowed": True}
-
-    def _validate_retry_config(self) -> None:
-        if self.retry_max_attempts < 1:
-            raise ValueError("retry_max_attempts must be >= 1")
-
-    def model_post_init(self, __context: Any) -> None:
-        """Auto-load credentials and configure OAuth if needed."""
-        from pydantic import SecretStr
-
-        from deerflow.models.credential_loader import (
-            OAUTH_ANTHROPIC_BETAS,
-            is_oauth_token,
-            load_claude_code_credential,
-        )
-
-        self._validate_retry_config()
-
-        # Extract actual key value (SecretStr.str() returns '**********')
-        current_key = ""
-        if self.anthropic_api_key:
-            if hasattr(self.anthropic_api_key, "get_secret_value"):
-                current_key = self.anthropic_api_key.get_secret_value()
-            else:
-                current_key = str(self.anthropic_api_key)
-
-        # Try the explicit Claude Code OAuth handoff sources if no valid key.
-        if not current_key or current_key in ("your-anthropic-api-key",):
-            cred = load_claude_code_credential()
-            if cred:
-                current_key = cred.access_token
-                logger.info(f"Using Claude Code CLI credential (source: {cred.source})")
-            else:
-                logger.warning("No Anthropic API key or explicit Claude Code OAuth credential found.")
-
-        # Detect OAuth token and configure Bearer auth
-        if is_oauth_token(current_key):
-            self._is_oauth = True
-            self._oauth_access_token = current_key
-            # Set the token as api_key temporarily (will be swapped to auth_token on client)
-            self.anthropic_api_key = SecretStr(current_key)
-            # Add required beta headers for OAuth
-            self.default_headers = {
-                **(self.default_headers or {}),
-                "anthropic-beta": OAUTH_ANTHROPIC_BETAS,
-            }
-            # OAuth tokens have a limit of 4 cache_control blocks — disable prompt caching
-            self.enable_prompt_caching = False
-            logger.info("OAuth token detected — will use Authorization: Bearer header")
-        else:
-            if current_key:
-                self.anthropic_api_key = SecretStr(current_key)
-
-        # Ensure api_key is SecretStr
-        if isinstance(self.anthropic_api_key, str):
-            self.anthropic_api_key = SecretStr(self.anthropic_api_key)
-
-        super().model_post_init(__context)
-
-        # Patch clients immediately after creation for OAuth Bearer auth.
-        # This must happen after super() because clients are lazily created.
-        if self._is_oauth:
-            self._patch_client_oauth(self._client)
-            self._patch_client_oauth(self._async_client)
-
-    def _patch_client_oauth(self, client: Any) -> None:
-        """Swap api_key → auth_token on an Anthropic SDK client for OAuth Bearer auth."""
-        if hasattr(client, "api_key") and hasattr(client, "auth_token"):
-            client.api_key = None
-            client.auth_token = self._oauth_access_token
-
-    def _get_request_payload(
-        self,
-        input_: Any,
-        *,
-        stop: list[str] | None = None,
-        **kwargs: Any,
-    ) -> dict:
-        """Override to inject prompt caching, thinking budget, and OAuth billing."""
-        payload = super()._get_request_payload(input_, stop=stop, **kwargs)
-
-        if self._is_oauth:
-            self._apply_oauth_billing(payload)
-
-        if self.enable_prompt_caching:
-            self._apply_prompt_caching(payload)
-
-        if self.auto_thinking_budget:
-            self._apply_thinking_budget(payload)
-
-        return payload
-
-    def _apply_oauth_billing(self, payload: dict) -> None:
-        """Inject the billing header block required for all OAuth requests.
-
-        The billing block is always placed first in the system list, removing any
-        existing occurrence to avoid duplication or out-of-order positioning.
-        """
-        billing_block = {"type": "text", "text": OAUTH_BILLING_HEADER}
-
-        system = payload.get("system")
-        if isinstance(system, list):
-            # Remove any existing billing blocks, then insert a single one at index 0.
-            filtered = [b for b in system if not (isinstance(b, dict) and OAUTH_BILLING_HEADER in b.get("text", ""))]
-            payload["system"] = [billing_block] + filtered
-        elif isinstance(system, str):
-            if OAUTH_BILLING_HEADER in system:
-                payload["system"] = [billing_block]
-            else:
-                payload["system"] = [billing_block, {"type": "text", "text": system}]
-        else:
-            payload["system"] = [billing_block]
-
-        # Add metadata.user_id required by the API for OAuth billing validation
-        if not isinstance(payload.get("metadata"), dict):
-            payload["metadata"] = {}
-        if "user_id" not in payload["metadata"]:
-            # Generate a stable device_id from the machine's hostname
-            hostname = socket.gethostname()
-            device_id = hashlib.sha256(f"deerflow-{hostname}".encode()).hexdigest()
-            session_id = str(uuid.uuid4())
-            payload["metadata"]["user_id"] = json.dumps(
-                {
-                    "device_id": device_id,
-                    "account_uuid": "deerflow",
-                    "session_id": session_id,
-                }
-            )
-
-    def _apply_prompt_caching(self, payload: dict) -> None:
-        """Apply ephemeral cache_control to system and recent messages."""
-        # Cache system messages
-        system = payload.get("system")
-        if system and isinstance(system, list):
-            for block in system:
-                if isinstance(block, dict) and block.get("type") == "text":
-                    block["cache_control"] = {"type": "ephemeral"}
-        elif system and isinstance(system, str):
-            payload["system"] = [
-                {
-                    "type": "text",
-                    "text": system,
-                    "cache_control": {"type": "ephemeral"},
-                }
-            ]
-
-        # Cache recent messages
-        messages = payload.get("messages", [])
-        cache_start = max(0, len(messages) - self.prompt_cache_size)
-        for i in range(cache_start, len(messages)):
-            msg = messages[i]
-            if not isinstance(msg, dict):
-                continue
-            content = msg.get("content")
-            if isinstance(content, list):
-                for block in content:
-                    if isinstance(block, dict):
-                        block["cache_control"] = {"type": "ephemeral"}
-            elif isinstance(content, str) and content:
-                msg["content"] = [
-                    {
-                        "type": "text",
-                        "text": content,
-                        "cache_control": {"type": "ephemeral"},
-                    }
-                ]
-
-        # Cache the last tool definition
-        tools = payload.get("tools", [])
-        if tools and isinstance(tools[-1], dict):
-            tools[-1]["cache_control"] = {"type": "ephemeral"}
-
-    def _apply_thinking_budget(self, payload: dict) -> None:
-        """Auto-allocate thinking budget (80% of max_tokens)."""
-        thinking = payload.get("thinking")
-        if not thinking or not isinstance(thinking, dict):
-            return
-        if thinking.get("type") != "enabled":
-            return
-        if thinking.get("budget_tokens"):
-            return
-
-        max_tokens = payload.get("max_tokens", 8192)
-        thinking["budget_tokens"] = int(max_tokens * THINKING_BUDGET_RATIO)
-
-    @staticmethod
-    def _strip_cache_control(payload: dict) -> None:
-        """Remove cache_control markers before OAuth requests reach Anthropic."""
-        for section in ("system", "messages"):
-            items = payload.get(section)
-            if not isinstance(items, list):
-                continue
-            for item in items:
-                if not isinstance(item, dict):
-                    continue
-                item.pop("cache_control", None)
-                content = item.get("content")
-                if isinstance(content, list):
-                    for block in content:
-                        if isinstance(block, dict):
-                            block.pop("cache_control", None)
-
-        tools = payload.get("tools")
-        if isinstance(tools, list):
-            for tool in tools:
-                if isinstance(tool, dict):
-                    tool.pop("cache_control", None)
-
-    def _create(self, payload: dict) -> Any:
-        if self._is_oauth:
-            self._strip_cache_control(payload)
-        return super()._create(payload)
-
-    async def _acreate(self, payload: dict) -> Any:
-        if self._is_oauth:
-            self._strip_cache_control(payload)
-        return await super()._acreate(payload)
-
-    def _generate(self, messages: list[BaseMessage], stop: list[str] | None = None, **kwargs: Any) -> Any:
-        """Override with OAuth patching and retry logic."""
-        if self._is_oauth:
-            self._patch_client_oauth(self._client)
-
-        last_error = None
-        for attempt in range(1, self.retry_max_attempts + 1):
-            try:
-                return super()._generate(messages, stop=stop, **kwargs)
-            except anthropic.RateLimitError as e:
-                last_error = e
-                if attempt >= self.retry_max_attempts:
-                    raise
-                wait_ms = self._calc_backoff_ms(attempt, e)
-                logger.warning(f"Rate limited, retrying attempt {attempt}/{self.retry_max_attempts} after {wait_ms}ms")
-                time.sleep(wait_ms / 1000)
-            except anthropic.InternalServerError as e:
-                last_error = e
-                if attempt >= self.retry_max_attempts:
-                    raise
-                wait_ms = self._calc_backoff_ms(attempt, e)
-                logger.warning(f"Server error, retrying attempt {attempt}/{self.retry_max_attempts} after {wait_ms}ms")
-                time.sleep(wait_ms / 1000)
-        raise last_error
-
-    async def _agenerate(self, messages: list[BaseMessage], stop: list[str] | None = None, **kwargs: Any) -> Any:
-        """Async override with OAuth patching and retry logic."""
-        import asyncio
-
-        if self._is_oauth:
-            self._patch_client_oauth(self._async_client)
-
-        last_error = None
-        for attempt in range(1, self.retry_max_attempts + 1):
-            try:
-                return await super()._agenerate(messages, stop=stop, **kwargs)
-            except anthropic.RateLimitError as e:
-                last_error = e
-                if attempt >= self.retry_max_attempts:
-                    raise
-                wait_ms = self._calc_backoff_ms(attempt, e)
-                logger.warning(f"Rate limited, retrying attempt {attempt}/{self.retry_max_attempts} after {wait_ms}ms")
-                await asyncio.sleep(wait_ms / 1000)
-            except anthropic.InternalServerError as e:
-                last_error = e
-                if attempt >= self.retry_max_attempts:
-                    raise
-                wait_ms = self._calc_backoff_ms(attempt, e)
-                logger.warning(f"Server error, retrying attempt {attempt}/{self.retry_max_attempts} after {wait_ms}ms")
-                await asyncio.sleep(wait_ms / 1000)
-        raise last_error
-
-    @staticmethod
-    def _calc_backoff_ms(attempt: int, error: Exception) -> int:
-        """Exponential backoff with a fixed 20% buffer."""
-        backoff_ms = 2000 * (1 << (attempt - 1))
-        jitter_ms = int(backoff_ms * 0.2)
-        total_ms = backoff_ms + jitter_ms
-
-        if hasattr(error, "response") and error.response is not None:
-            retry_after = error.response.headers.get("Retry-After")
-            if retry_after:
-                try:
-                    total_ms = int(retry_after) * 1000
-                except (ValueError, TypeError):
-                    pass
-
-        return total_ms

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

@@ -1,219 +0,0 @@
-"""Auto-load credentials from Claude Code CLI and Codex CLI.
-
-Implements two credential strategies:
-  1. Claude Code OAuth token from explicit env vars or an exported credentials file
-     - Uses Authorization: Bearer header (NOT x-api-key)
-     - Requires anthropic-beta: oauth-2025-04-20,claude-code-20250219
-     - Supports $CLAUDE_CODE_OAUTH_TOKEN, $CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR, and $ANTHROPIC_AUTH_TOKEN
-     - Override path with $CLAUDE_CODE_CREDENTIALS_PATH
-  2. Codex CLI token from ~/.codex/auth.json
-     - Uses chatgpt.com/backend-api/codex/responses endpoint
-     - Supports both legacy top-level tokens and current nested tokens shape
-     - Override path with $CODEX_AUTH_PATH
-"""
-
-import json
-import logging
-import os
-import time
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-# Required beta headers for Claude Code OAuth tokens
-OAUTH_ANTHROPIC_BETAS = "oauth-2025-04-20,claude-code-20250219,interleaved-thinking-2025-05-14"
-
-
-def is_oauth_token(token: str) -> bool:
-    """Check if a token is a Claude Code OAuth token (not a standard API key)."""
-    return isinstance(token, str) and "sk-ant-oat" in token
-
-
-@dataclass
-class ClaudeCodeCredential:
-    """Claude Code CLI OAuth credential."""
-
-    access_token: str
-    refresh_token: str = ""
-    expires_at: int = 0
-    source: str = ""
-
-    @property
-    def is_expired(self) -> bool:
-        if self.expires_at <= 0:
-            return False
-        return time.time() * 1000 > self.expires_at - 60_000  # 1 min buffer
-
-
-@dataclass
-class CodexCliCredential:
-    """Codex CLI credential."""
-
-    access_token: str
-    account_id: str = ""
-    source: str = ""
-
-
-def _resolve_credential_path(env_var: str, default_relative_path: str) -> Path:
-    configured_path = os.getenv(env_var)
-    if configured_path:
-        return Path(configured_path).expanduser()
-    return _home_dir() / default_relative_path
-
-
-def _home_dir() -> Path:
-    home = os.getenv("HOME")
-    if home:
-        return Path(home).expanduser()
-    return Path.home()
-
-
-def _load_json_file(path: Path, label: str) -> dict[str, Any] | None:
-    if not path.exists():
-        logger.debug(f"{label} not found: {path}")
-        return None
-    if path.is_dir():
-        logger.warning(f"{label} path is a directory, expected a file: {path}")
-        return None
-
-    try:
-        return json.loads(path.read_text())
-    except (json.JSONDecodeError, OSError) as e:
-        logger.warning(f"Failed to read {label}: {e}")
-        return None
-
-
-def _read_secret_from_file_descriptor(env_var: str) -> str | None:
-    fd_value = os.getenv(env_var)
-    if not fd_value:
-        return None
-
-    try:
-        fd = int(fd_value)
-    except ValueError:
-        logger.warning(f"{env_var} must be an integer file descriptor, got: {fd_value}")
-        return None
-
-    try:
-        secret = os.read(fd, 1024 * 1024).decode().strip()
-    except OSError as e:
-        logger.warning(f"Failed to read {env_var}: {e}")
-        return None
-
-    return secret or None
-
-
-def _credential_from_direct_token(access_token: str, source: str) -> ClaudeCodeCredential | None:
-    token = access_token.strip()
-    if not token:
-        return None
-    return ClaudeCodeCredential(access_token=token, source=source)
-
-
-def _iter_claude_code_credential_paths() -> list[Path]:
-    paths: list[Path] = []
-    override_path = os.getenv("CLAUDE_CODE_CREDENTIALS_PATH")
-    if override_path:
-        paths.append(Path(override_path).expanduser())
-
-    default_path = _home_dir() / ".claude/.credentials.json"
-    if not paths or paths[-1] != default_path:
-        paths.append(default_path)
-
-    return paths
-
-
-def _extract_claude_code_credential(data: dict[str, Any], source: str) -> ClaudeCodeCredential | None:
-    oauth = data.get("claudeAiOauth", {})
-    access_token = oauth.get("accessToken", "")
-    if not access_token:
-        logger.debug("Claude Code credentials container exists but no accessToken found")
-        return None
-
-    cred = ClaudeCodeCredential(
-        access_token=access_token,
-        refresh_token=oauth.get("refreshToken", ""),
-        expires_at=oauth.get("expiresAt", 0),
-        source=source,
-    )
-
-    if cred.is_expired:
-        logger.warning("Claude Code OAuth token is expired. Run 'claude' to refresh.")
-        return None
-
-    return cred
-
-
-def load_claude_code_credential() -> ClaudeCodeCredential | None:
-    """Load OAuth credential from explicit Claude Code handoff sources.
-
-    Lookup order:
-      1. $CLAUDE_CODE_OAUTH_TOKEN or $ANTHROPIC_AUTH_TOKEN
-      2. $CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR
-      3. $CLAUDE_CODE_CREDENTIALS_PATH
-      4. ~/.claude/.credentials.json
-
-    Exported credentials files contain:
-    {
-      "claudeAiOauth": {
-        "accessToken": "sk-ant-oat01-...",
-        "refreshToken": "sk-ant-ort01-...",
-        "expiresAt": 1773430695128,
-        "scopes": ["user:inference", ...],
-        ...
-      }
-    }
-    """
-    direct_token = os.getenv("CLAUDE_CODE_OAUTH_TOKEN") or os.getenv("ANTHROPIC_AUTH_TOKEN")
-    if direct_token:
-        cred = _credential_from_direct_token(direct_token, "claude-cli-env")
-        if cred:
-            logger.info("Loaded Claude Code OAuth credential from environment")
-        return cred
-
-    fd_token = _read_secret_from_file_descriptor("CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR")
-    if fd_token:
-        cred = _credential_from_direct_token(fd_token, "claude-cli-fd")
-        if cred:
-            logger.info("Loaded Claude Code OAuth credential from file descriptor")
-        return cred
-
-    override_path = os.getenv("CLAUDE_CODE_CREDENTIALS_PATH")
-    override_path_obj = Path(override_path).expanduser() if override_path else None
-    for cred_path in _iter_claude_code_credential_paths():
-        data = _load_json_file(cred_path, "Claude Code credentials")
-        if data is None:
-            continue
-        cred = _extract_claude_code_credential(data, "claude-cli-file")
-        if cred:
-            source_label = "override path" if override_path_obj is not None and cred_path == override_path_obj else "plaintext file"
-            logger.info(f"Loaded Claude Code OAuth credential from {source_label} (expires_at={cred.expires_at})")
-            return cred
-
-    return None
-
-
-def load_codex_cli_credential() -> CodexCliCredential | None:
-    """Load credential from Codex CLI (~/.codex/auth.json)."""
-    cred_path = _resolve_credential_path("CODEX_AUTH_PATH", ".codex/auth.json")
-    data = _load_json_file(cred_path, "Codex CLI credentials")
-    if data is None:
-        return None
-    tokens = data.get("tokens", {})
-    if not isinstance(tokens, dict):
-        tokens = {}
-
-    access_token = data.get("access_token") or data.get("token") or tokens.get("access_token", "")
-    account_id = data.get("account_id") or tokens.get("account_id", "")
-    if not access_token:
-        logger.debug("Codex CLI credentials file exists but no token found")
-        return None
-
-    logger.info("Loaded Codex CLI credential")
-    return CodexCliCredential(
-        access_token=access_token,
-        account_id=account_id,
-        source="codex-cli",
-    )

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

@@ -1,95 +0,0 @@
-import logging
-
-from langchain.chat_models import BaseChatModel
-
-from deerflow.config import get_app_config, get_tracing_config, is_tracing_enabled
-from deerflow.reflection import resolve_class
-
-logger = logging.getLogger(__name__)
-
-
-def create_chat_model(name: str | None = None, thinking_enabled: bool = False, **kwargs) -> BaseChatModel:
-    """Create a chat model instance from the config.
-
-    Args:
-        name: The name of the model to create. If None, the first model in the config will be used.
-
-    Returns:
-        A chat model instance.
-    """
-    config = get_app_config()
-    if name is None:
-        name = config.models[0].name
-    model_config = config.get_model_config(name)
-    if model_config is None:
-        raise ValueError(f"Model {name} not found in config") from None
-    model_class = resolve_class(model_config.use, BaseChatModel)
-    model_settings_from_config = model_config.model_dump(
-        exclude_none=True,
-        exclude={
-            "use",
-            "name",
-            "display_name",
-            "description",
-            "supports_thinking",
-            "supports_reasoning_effort",
-            "when_thinking_enabled",
-            "thinking",
-            "supports_vision",
-        },
-    )
-    # Compute effective when_thinking_enabled by merging in the `thinking` shortcut field.
-    # The `thinking` shortcut is equivalent to setting when_thinking_enabled["thinking"].
-    has_thinking_settings = (model_config.when_thinking_enabled is not None) or (model_config.thinking is not None)
-    effective_wte: dict = dict(model_config.when_thinking_enabled) if model_config.when_thinking_enabled else {}
-    if model_config.thinking is not None:
-        merged_thinking = {**(effective_wte.get("thinking") or {}), **model_config.thinking}
-        effective_wte = {**effective_wte, "thinking": merged_thinking}
-    if thinking_enabled and has_thinking_settings:
-        if not model_config.supports_thinking:
-            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 and has_thinking_settings:
-        if effective_wte.get("extra_body", {}).get("thinking", {}).get("type"):
-            # OpenAI-compatible gateway: thinking is nested under extra_body
-            kwargs.update({"extra_body": {"thinking": {"type": "disabled"}}})
-            kwargs.update({"reasoning_effort": "minimal"})
-        elif effective_wte.get("thinking", {}).get("type"):
-            # Native langchain_anthropic: thinking is a direct constructor parameter
-            kwargs.update({"thinking": {"type": "disabled"}})
-    if not model_config.supports_reasoning_effort and "reasoning_effort" in kwargs:
-        del kwargs["reasoning_effort"]
-
-    # For Codex Responses API models: map thinking mode to reasoning_effort
-    from deerflow.models.openai_codex_provider import CodexChatModel
-
-    if issubclass(model_class, CodexChatModel):
-        # The ChatGPT Codex endpoint currently rejects max_tokens/max_output_tokens.
-        model_settings_from_config.pop("max_tokens", None)
-
-        # Use explicit reasoning_effort from frontend if provided (low/medium/high)
-        explicit_effort = kwargs.pop("reasoning_effort", None)
-        if not thinking_enabled:
-            model_settings_from_config["reasoning_effort"] = "none"
-        elif explicit_effort and explicit_effort in ("low", "medium", "high", "xhigh"):
-            model_settings_from_config["reasoning_effort"] = explicit_effort
-        elif "reasoning_effort" not in model_settings_from_config:
-            model_settings_from_config["reasoning_effort"] = "medium"
-
-    model_instance = model_class(**kwargs, **model_settings_from_config)
-
-    if is_tracing_enabled():
-        try:
-            from langchain_core.tracers.langchain import LangChainTracer
-
-            tracing_config = get_tracing_config()
-            tracer = LangChainTracer(
-                project_name=tracing_config.project,
-            )
-            existing_callbacks = model_instance.callbacks or []
-            model_instance.callbacks = [*existing_callbacks, tracer]
-            logger.debug(f"LangSmith tracing attached to model '{name}' (project='{tracing_config.project}')")
-        except Exception as e:
-            logger.warning(f"Failed to attach LangSmith tracing to model '{name}': {e}")
-    return model_instance

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

@@ -1,396 +0,0 @@
-"""Custom OpenAI Codex provider using ChatGPT Codex Responses API.
-
-Uses Codex CLI OAuth tokens with chatgpt.com/backend-api/codex/responses endpoint.
-This is the same endpoint that the Codex CLI uses internally.
-
-Supports:
-- Auto-load credentials from ~/.codex/auth.json
-- Responses API format (not Chat Completions)
-- Tool calling
-- Streaming (required by the endpoint)
-- Retry with exponential backoff
-"""
-
-import json
-import logging
-import time
-from typing import Any
-
-import httpx
-from langchain_core.callbacks import CallbackManagerForLLMRun
-from langchain_core.language_models.chat_models import BaseChatModel
-from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, SystemMessage, ToolMessage
-from langchain_core.outputs import ChatGeneration, ChatResult
-
-from deerflow.models.credential_loader import CodexCliCredential, load_codex_cli_credential
-
-logger = logging.getLogger(__name__)
-
-CODEX_BASE_URL = "https://chatgpt.com/backend-api/codex"
-MAX_RETRIES = 3
-
-
-class CodexChatModel(BaseChatModel):
-    """LangChain chat model using ChatGPT Codex Responses API.
-
-    Config example:
-        - name: gpt-5.4
-          use: deerflow.models.openai_codex_provider:CodexChatModel
-          model: gpt-5.4
-          reasoning_effort: medium
-    """
-
-    model: str = "gpt-5.4"
-    reasoning_effort: str = "medium"
-    retry_max_attempts: int = MAX_RETRIES
-    _access_token: str = ""
-    _account_id: str = ""
-
-    model_config = {"arbitrary_types_allowed": True}
-
-    @property
-    def _llm_type(self) -> str:
-        return "codex-responses"
-
-    def _validate_retry_config(self) -> None:
-        if self.retry_max_attempts < 1:
-            raise ValueError("retry_max_attempts must be >= 1")
-
-    def model_post_init(self, __context: Any) -> None:
-        """Auto-load Codex CLI credentials."""
-        self._validate_retry_config()
-
-        cred = self._load_codex_auth()
-        if cred:
-            self._access_token = cred.access_token
-            self._account_id = cred.account_id
-            logger.info(f"Using Codex CLI credential (account: {self._account_id[:8]}...)")
-        else:
-            raise ValueError("Codex CLI credential not found. Expected ~/.codex/auth.json or CODEX_AUTH_PATH.")
-
-        super().model_post_init(__context)
-
-    def _load_codex_auth(self) -> CodexCliCredential | None:
-        """Load access_token and account_id from Codex CLI auth."""
-        return load_codex_cli_credential()
-
-    @classmethod
-    def _normalize_content(cls, content: Any) -> str:
-        """Flatten LangChain content blocks into plain text for Codex."""
-        if isinstance(content, str):
-            return content
-
-        if isinstance(content, list):
-            parts = [cls._normalize_content(item) for item in content]
-            return "\n".join(part for part in parts if part)
-
-        if isinstance(content, dict):
-            for key in ("text", "output"):
-                value = content.get(key)
-                if isinstance(value, str):
-                    return value
-            nested_content = content.get("content")
-            if nested_content is not None:
-                return cls._normalize_content(nested_content)
-            try:
-                return json.dumps(content, ensure_ascii=False)
-            except TypeError:
-                return str(content)
-
-        try:
-            return json.dumps(content, ensure_ascii=False)
-        except TypeError:
-            return str(content)
-
-    def _convert_messages(self, messages: list[BaseMessage]) -> tuple[str, list[dict]]:
-        """Convert LangChain messages to Responses API format.
-
-        Returns (instructions, input_items).
-        """
-        instructions_parts: list[str] = []
-        input_items = []
-
-        for msg in messages:
-            if isinstance(msg, SystemMessage):
-                content = self._normalize_content(msg.content)
-                if content:
-                    instructions_parts.append(content)
-            elif isinstance(msg, HumanMessage):
-                content = self._normalize_content(msg.content)
-                input_items.append({"role": "user", "content": content})
-            elif isinstance(msg, AIMessage):
-                if msg.content:
-                    content = self._normalize_content(msg.content)
-                    input_items.append({"role": "assistant", "content": content})
-                if msg.tool_calls:
-                    for tc in msg.tool_calls:
-                        input_items.append(
-                            {
-                                "type": "function_call",
-                                "name": tc["name"],
-                                "arguments": json.dumps(tc["args"]) if isinstance(tc["args"], dict) else tc["args"],
-                                "call_id": tc["id"],
-                            }
-                        )
-            elif isinstance(msg, ToolMessage):
-                input_items.append(
-                    {
-                        "type": "function_call_output",
-                        "call_id": msg.tool_call_id,
-                        "output": self._normalize_content(msg.content),
-                    }
-                )
-
-        instructions = "\n\n".join(instructions_parts) or "You are a helpful assistant."
-
-        return instructions, input_items
-
-    def _convert_tools(self, tools: list[dict]) -> list[dict]:
-        """Convert LangChain tool format to Responses API format."""
-        responses_tools = []
-        for tool in tools:
-            if tool.get("type") == "function" and "function" in tool:
-                fn = tool["function"]
-                responses_tools.append(
-                    {
-                        "type": "function",
-                        "name": fn["name"],
-                        "description": fn.get("description", ""),
-                        "parameters": fn.get("parameters", {}),
-                    }
-                )
-            elif "name" in tool:
-                responses_tools.append(
-                    {
-                        "type": "function",
-                        "name": tool["name"],
-                        "description": tool.get("description", ""),
-                        "parameters": tool.get("parameters", {}),
-                    }
-                )
-        return responses_tools
-
-    def _call_codex_api(self, messages: list[BaseMessage], tools: list[dict] | None = None) -> dict:
-        """Call the Codex Responses API and return the completed response."""
-        instructions, input_items = self._convert_messages(messages)
-
-        payload = {
-            "model": self.model,
-            "instructions": instructions,
-            "input": input_items,
-            "store": False,
-            "stream": True,
-            "reasoning": {"effort": self.reasoning_effort, "summary": "detailed"} if self.reasoning_effort != "none" else {"effort": "none"},
-        }
-
-        if tools:
-            payload["tools"] = self._convert_tools(tools)
-
-        headers = {
-            "Authorization": f"Bearer {self._access_token}",
-            "ChatGPT-Account-ID": self._account_id,
-            "Content-Type": "application/json",
-            "Accept": "text/event-stream",
-            "originator": "codex_cli_rs",
-        }
-
-        last_error = None
-        for attempt in range(1, self.retry_max_attempts + 1):
-            try:
-                return self._stream_response(headers, payload)
-            except httpx.HTTPStatusError as e:
-                last_error = e
-                if e.response.status_code in (429, 500, 529):
-                    if attempt >= self.retry_max_attempts:
-                        raise
-                    wait_ms = 2000 * (1 << (attempt - 1))
-                    logger.warning(f"Codex API error {e.response.status_code}, retrying {attempt}/{self.retry_max_attempts} after {wait_ms}ms")
-                    time.sleep(wait_ms / 1000)
-                else:
-                    raise
-            except Exception:
-                raise
-
-        raise last_error
-
-    def _stream_response(self, headers: dict, payload: dict) -> dict:
-        """Stream SSE from Codex API and collect the final response."""
-        completed_response = None
-
-        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 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")
-
-        return completed_response
-
-    @staticmethod
-    def _parse_sse_data_line(line: str) -> dict[str, Any] | None:
-        """Parse a data line from the SSE stream, skipping terminal markers."""
-        if not line.startswith("data:"):
-            return None
-
-        raw_data = line[5:].strip()
-        if not raw_data or raw_data == "[DONE]":
-            return None
-
-        try:
-            data = json.loads(raw_data)
-        except json.JSONDecodeError:
-            logger.debug(f"Skipping non-JSON Codex SSE frame: {raw_data}")
-            return None
-
-        return data if isinstance(data, dict) else None
-
-    def _parse_tool_call_arguments(self, output_item: dict[str, Any]) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
-        """Parse function-call arguments, surfacing malformed payloads safely."""
-        raw_arguments = output_item.get("arguments", "{}")
-        if isinstance(raw_arguments, dict):
-            return raw_arguments, None
-
-        normalized_arguments = raw_arguments or "{}"
-        try:
-            parsed_arguments = json.loads(normalized_arguments)
-        except (TypeError, json.JSONDecodeError) as exc:
-            return None, {
-                "type": "invalid_tool_call",
-                "name": output_item.get("name"),
-                "args": str(raw_arguments),
-                "id": output_item.get("call_id"),
-                "error": f"Failed to parse tool arguments: {exc}",
-            }
-
-        if not isinstance(parsed_arguments, dict):
-            return None, {
-                "type": "invalid_tool_call",
-                "name": output_item.get("name"),
-                "args": str(raw_arguments),
-                "id": output_item.get("call_id"),
-                "error": "Tool arguments must decode to a JSON object.",
-            }
-
-        return parsed_arguments, None
-
-    def _parse_response(self, response: dict) -> ChatResult:
-        """Parse Codex Responses API response into LangChain ChatResult."""
-        content = ""
-        tool_calls = []
-        invalid_tool_calls = []
-        reasoning_content = ""
-
-        for output_item in response.get("output", []):
-            if output_item.get("type") == "reasoning":
-                # Extract reasoning summary text
-                for summary_item in output_item.get("summary", []):
-                    if isinstance(summary_item, dict) and summary_item.get("type") == "summary_text":
-                        reasoning_content += summary_item.get("text", "")
-                    elif isinstance(summary_item, str):
-                        reasoning_content += summary_item
-            elif output_item.get("type") == "message":
-                for part in output_item.get("content", []):
-                    if part.get("type") == "output_text":
-                        content += part.get("text", "")
-            elif output_item.get("type") == "function_call":
-                parsed_arguments, invalid_tool_call = self._parse_tool_call_arguments(output_item)
-                if invalid_tool_call:
-                    invalid_tool_calls.append(invalid_tool_call)
-                    continue
-
-                tool_calls.append(
-                    {
-                        "name": output_item["name"],
-                        "args": parsed_arguments or {},
-                        "id": output_item.get("call_id", ""),
-                        "type": "tool_call",
-                    }
-                )
-
-        usage = response.get("usage", {})
-        additional_kwargs = {}
-        if reasoning_content:
-            additional_kwargs["reasoning_content"] = reasoning_content
-
-        message = AIMessage(
-            content=content,
-            tool_calls=tool_calls if tool_calls else [],
-            invalid_tool_calls=invalid_tool_calls,
-            additional_kwargs=additional_kwargs,
-            response_metadata={
-                "model": response.get("model", self.model),
-                "usage": usage,
-            },
-        )
-
-        return ChatResult(
-            generations=[ChatGeneration(message=message)],
-            llm_output={
-                "token_usage": {
-                    "prompt_tokens": usage.get("input_tokens", 0),
-                    "completion_tokens": usage.get("output_tokens", 0),
-                    "total_tokens": usage.get("total_tokens", 0),
-                },
-                "model_name": response.get("model", self.model),
-            },
-        )
-
-    def _generate(
-        self,
-        messages: list[BaseMessage],
-        stop: list[str] | None = None,
-        run_manager: CallbackManagerForLLMRun | None = None,
-        **kwargs: Any,
-    ) -> ChatResult:
-        """Generate a response using Codex Responses API."""
-        tools = kwargs.get("tools", None)
-        response = self._call_codex_api(messages, tools=tools)
-        return self._parse_response(response)
-
-    def bind_tools(self, tools: list, **kwargs: Any) -> Any:
-        """Bind tools for function calling."""
-        from langchain_core.runnables import RunnableBinding
-        from langchain_core.tools import BaseTool
-        from langchain_core.utils.function_calling import convert_to_openai_function
-
-        formatted_tools = []
-        for tool in tools:
-            if isinstance(tool, BaseTool):
-                try:
-                    fn = convert_to_openai_function(tool)
-                    formatted_tools.append(
-                        {
-                            "type": "function",
-                            "name": fn["name"],
-                            "description": fn.get("description", ""),
-                            "parameters": fn.get("parameters", {}),
-                        }
-                    )
-                except Exception:
-                    formatted_tools.append(
-                        {
-                            "type": "function",
-                            "name": tool.name,
-                            "description": tool.description,
-                            "parameters": {"type": "object", "properties": {}},
-                        }
-                    )
-            elif isinstance(tool, dict):
-                if "function" in tool:
-                    fn = tool["function"]
-                    formatted_tools.append(
-                        {
-                            "type": "function",
-                            "name": fn["name"],
-                            "description": fn.get("description", ""),
-                            "parameters": fn.get("parameters", {}),
-                        }
-                    )
-                else:
-                    formatted_tools.append(tool)
-
-        return RunnableBinding(bound=self, kwargs={"tools": formatted_tools}, **kwargs)