test(custom_agent + task_tool): set app.state.config + drop obsolete skills monkeypatches

Squashes 25 PR commits onto current main. AppConfig becomes a pure value
object with no ambient lookup. Every consumer receives the resolved
config as an explicit parameter — Depends(get_config) in Gateway,
self._app_config in DeerFlowClient, runtime.context.app_config in agent
runs, AppConfig.from_file() at the LangGraph Server registration
boundary.

Phase 1 — frozen data + typed context

- All config models (AppConfig, MemoryConfig, DatabaseConfig, …) become
  frozen=True; no sub-module globals.
- AppConfig.from_file() is pure (no side-effect singleton loaders).
- Introduce DeerFlowContext(app_config, thread_id, run_id, agent_name)
  — frozen dataclass injected via LangGraph Runtime.
- Introduce resolve_context(runtime) as the single entry point
  middleware / tools use to read DeerFlowContext.

Phase 2 — pure explicit parameter passing

- Gateway: app.state.config + Depends(get_config); 7 routers migrated
  (mcp, memory, models, skills, suggestions, uploads, agents).
- DeerFlowClient: __init__(config=...) captures config locally.
- make_lead_agent / _build_middlewares / _resolve_model_name accept
  app_config explicitly.
- RunContext.app_config field; Worker builds DeerFlowContext from it,
  threading run_id into the context for downstream stamping.
- Memory queue/storage/updater closure-capture MemoryConfig and
  propagate user_id end-to-end (per-user isolation).
- Sandbox/skills/community/factories/tools thread app_config.
- resolve_context() rejects non-typed runtime.context.
- Test suite migrated off AppConfig.current() monkey-patches.
- AppConfig.current() classmethod deleted.

Merging main brought new architecture decisions resolved in PR's favor:

- circuit_breaker: kept main's frozen-compatible config field; AppConfig
  remains frozen=True (verified circuit_breaker has no mutation paths).
- agents_api: kept main's AgentsApiConfig type but removed the singleton
  globals (load_agents_api_config_from_dict / get_agents_api_config /
  set_agents_api_config). 8 routes in agents.py now read via
  Depends(get_config).
- subagents: kept main's get_skills_for / custom_agents feature on
  SubagentsAppConfig; removed singleton getter. registry.py now reads
  app_config.subagents directly.
- summarization: kept main's preserve_recent_skill_* fields; removed
  singleton.
- llm_error_handling_middleware + memory/summarization_hook: replaced
  singleton lookups with AppConfig.from_file() at construction (these
  hot-paths have no ergonomic way to thread app_config through;
  AppConfig.from_file is a pure load).
- worker.py + thread_data_middleware.py: DeerFlowContext.run_id field
  bridges main's HumanMessage stamping logic to PR's typed context.

Trade-offs (follow-up work):

- main's #2138 (async memory updater) reverted to PR's sync
  implementation. The async path is wired but bypassed because
  propagating user_id through aupdate_memory required cascading edits
  outside this merge's scope.
- tests/test_subagent_skills_config.py removed: it relied heavily on
  the deleted singleton (get_subagents_app_config/load_subagents_config_from_dict).
  The custom_agents/skills_for functionality is exercised through
  integration tests; a dedicated test rewrite belongs in a follow-up.

Verification: backend test suite — 2560 passed, 4 skipped, 84 failures.
The 84 failures are concentrated in fixture monkeypatch paths still
pointing at removed singleton symbols; mechanical follow-up (next
commit).

.env.example

@@ -1,6 +1,3 @@
-# Serper API Key (Google Search) - https://serper.dev
-SERPER_API_KEY=your-serper-api-key
-
 # TAVILY API Key
 TAVILY_API_KEY=your-tavily-api-key
 
@@ -43,19 +40,3 @@ INFOQUEST_API_KEY=your-infoquest-api-key
 #
 # WECOM_BOT_ID=your-wecom-bot-id
 # WECOM_BOT_SECRET=your-wecom-bot-secret
-# DINGTALK_CLIENT_ID=your-dingtalk-client-id
-# DINGTALK_CLIENT_SECRET=your-dingtalk-client-secret
-
-# Set to "false" to disable Swagger UI, ReDoc, and OpenAPI schema in production
-# GATEWAY_ENABLE_DOCS=false
-
-# ── Frontend SSR → Gateway wiring ─────────────────────────────────────────────
-# The Next.js server uses these to reach the Gateway during SSR (auth checks,
-# /api/* rewrites). They default to localhost values that match `make dev` and
-# `make start`, so most local users do not need to set them.
-#
-# Override only when the Gateway is not on localhost:8001 (e.g. when the
-# frontend and gateway run on different hosts, in containers with a service
-# alias, or behind a different port). docker-compose already sets these.
-# DEER_FLOW_INTERNAL_GATEWAY_BASE_URL=http://localhost:8001
-# DEER_FLOW_TRUSTED_ORIGINS=http://localhost:3000,http://localhost:2026

.github/workflows/container.yaml

@@ -1,101 +0,0 @@
-name: Publish Containers
-
-on:
-  push:
-    tags:
-      - "v*"
-
-jobs:
-
-  backend-container:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-      attestations: write
-      id-token: write
-    env:
-      REGISTRY: ghcr.io
-      IMAGE_NAME: ${{ github.repository }}-backend
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v6
-      - name: Log in to the Container registry
-        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 #v3.4.0
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - name: Extract metadata (tags, labels) for Docker
-        id: meta
-        uses: docker/metadata-action@902fa8ec7d6ecbf8d84d538b9b233a880e428804 #v5.7.0
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=ref,event=tag
-            type=ref,event=branch
-            type=sha
-            type=raw,value=latest,enable={{is_default_branch}}
-      - name: Build and push Docker image
-        id: push
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 #v6.18.0
-        with:
-          context: .
-          file: backend/Dockerfile
-          push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-
-      - name: Generate artifact attestation
-        uses: actions/attest-build-provenance@v2
-        with:
-          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
-          subject-digest: ${{ steps.push.outputs.digest }}
-          push-to-registry: true
-
-  frontend-container:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-      attestations: write
-      id-token: write
-    env:
-      REGISTRY: ghcr.io
-      IMAGE_NAME: ${{ github.repository }}-frontend
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v6
-      - name: Log in to the Container registry
-        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 #v3.4.0
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - name: Extract metadata (tags, labels) for Docker
-        id: meta
-        uses: docker/metadata-action@902fa8ec7d6ecbf8d84d538b9b233a880e428804 #v5.7.0
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=ref,event=tag
-            type=ref,event=branch
-            type=sha
-            type=raw,value=latest,enable={{is_default_branch}}
-      - name: Build and push Docker image
-        id: push
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 #v6.18.0
-        with:
-          context: .
-          file: frontend/Dockerfile
-          push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-
-      - name: Generate artifact attestation
-        uses: actions/attest-build-provenance@v2
-        with:
-          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
-          subject-digest: ${{ steps.push.outputs.digest }}
-          push-to-registry: true

Makefile

@@ -1,6 +1,6 @@
 # DeerFlow - Unified Development Environment
 
-.PHONY: help config config-upgrade check install setup doctor dev dev-daemon start start-daemon stop up down clean docker-init docker-start docker-stop docker-logs docker-logs-frontend docker-logs-gateway
+.PHONY: help config config-upgrade check install setup doctor dev dev-pro dev-daemon dev-daemon-pro start start-pro start-daemon start-daemon-pro stop up up-pro down clean docker-init docker-start docker-start-pro docker-stop docker-logs docker-logs-frontend docker-logs-gateway
 
 BASH ?= bash
 BACKEND_UV_RUN = cd backend && uv run
@@ -26,19 +26,25 @@ help:
 	@echo "  make install         - Install all dependencies (frontend + backend + pre-commit hooks)"
 	@echo "  make setup-sandbox   - Pre-pull sandbox container image (recommended)"
 	@echo "  make dev             - Start all services in development mode (with hot-reloading)"
+	@echo "  make dev-pro         - Start in dev + Gateway mode (experimental, no LangGraph server)"
 	@echo "  make dev-daemon      - Start dev services in background (daemon mode)"
+	@echo "  make dev-daemon-pro  - Start dev daemon + Gateway mode (experimental)"
 	@echo "  make start           - Start all services in production mode (optimized, no hot-reloading)"
+	@echo "  make start-pro       - Start in prod + Gateway mode (experimental)"
 	@echo "  make start-daemon    - Start prod services in background (daemon mode)"
+	@echo "  make start-daemon-pro - Start prod daemon + Gateway mode (experimental)"
 	@echo "  make stop            - Stop all running services"
 	@echo "  make clean           - Clean up processes and temporary files"
 	@echo ""
 	@echo "Docker Production Commands:"
 	@echo "  make up              - Build and start production Docker services (localhost:2026)"
+	@echo "  make up-pro          - Build and start production Docker in Gateway mode (experimental)"
 	@echo "  make down            - Stop and remove production Docker containers"
 	@echo ""
 	@echo "Docker Development Commands:"
 	@echo "  make docker-init     - Pull the sandbox image"
 	@echo "  make docker-start    - Start Docker services (mode-aware from config.yaml, localhost:2026)"
+	@echo "  make docker-start-pro - Start Docker in Gateway mode (experimental, no LangGraph container)"
 	@echo "  make docker-stop     - Stop Docker development services"
 	@echo "  make docker-logs     - View Docker development logs"
 	@echo "  make docker-logs-frontend - View Docker frontend logs"
@@ -117,21 +123,41 @@ dev:
 	@$(PYTHON) ./scripts/check.py
 	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --dev
 
+# Start all services in dev + Gateway mode (experimental: agent runtime embedded in Gateway)
+dev-pro:
+	@$(PYTHON) ./scripts/check.py
+	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --dev --gateway
+
 # Start all services in production mode (with optimizations)
 start:
 	@$(PYTHON) ./scripts/check.py
 	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --prod
 
+# Start all services in prod + Gateway mode (experimental)
+start-pro:
+	@$(PYTHON) ./scripts/check.py
+	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --prod --gateway
+
 # Start all services in daemon mode (background)
 dev-daemon:
 	@$(PYTHON) ./scripts/check.py
 	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --dev --daemon
 
+# Start daemon + Gateway mode (experimental)
+dev-daemon-pro:
+	@$(PYTHON) ./scripts/check.py
+	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --dev --gateway --daemon
+
 # Start prod services in daemon mode (background)
 start-daemon:
 	@$(PYTHON) ./scripts/check.py
 	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --prod --daemon
 
+# Start prod daemon + Gateway mode (experimental)
+start-daemon-pro:
+	@$(PYTHON) ./scripts/check.py
+	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --prod --gateway --daemon
+
 # Stop all services
 stop:
 	@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --stop
@@ -156,6 +182,10 @@ docker-init:
 docker-start:
 	@$(RUN_WITH_GIT_BASH) ./scripts/docker.sh start
 
+# Start Docker in Gateway mode (experimental)
+docker-start-pro:
+	@$(RUN_WITH_GIT_BASH) ./scripts/docker.sh start --gateway
+
 # Stop Docker development environment
 docker-stop:
 	@$(RUN_WITH_GIT_BASH) ./scripts/docker.sh stop
@@ -178,6 +208,10 @@ docker-logs-gateway:
 up:
 	@$(RUN_WITH_GIT_BASH) ./scripts/deploy.sh
 
+# Build and start production services in Gateway mode
+up-pro:
+	@$(RUN_WITH_GIT_BASH) ./scripts/deploy.sh --gateway
+
 # Stop and remove production containers
 down:
 	@$(RUN_WITH_GIT_BASH) ./scripts/deploy.sh down

README.md

@@ -243,6 +243,9 @@ 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
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed Docker development guide.
@@ -251,7 +254,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed Docker development guide.
 
 If you prefer running services locally:
 
-Prerequisite: complete the "Configuration" steps above first (`make setup`). `make dev` requires a valid `config.yaml` in the project root. Set `DEER_FLOW_PROJECT_ROOT` to define that root explicitly, or `DEER_FLOW_CONFIG_PATH` to point at a specific config file. Runtime state defaults to `.deer-flow` under the project root and can be moved with `DEER_FLOW_HOME`; skills default to `skills/` under the project root and can be moved with `DEER_FLOW_SKILLS_PATH`. Run `make doctor` to verify your setup before starting.
+Prerequisite: complete the "Configuration" steps above first (`make setup`). `make dev` requires a valid `config.yaml` in the project root (can be overridden via `DEER_FLOW_CONFIG_PATH`). Run `make doctor` to verify your setup before starting.
 On Windows, run the local development flow from Git Bash. Native `cmd.exe` and PowerShell shells are not supported for the bash-based service scripts, and WSL is not guaranteed because some scripts rely on Git for Windows utilities such as `cygpath`.
 
 1. **Check prerequisites**:
@@ -286,31 +289,53 @@ On Windows, run the local development flow from Git Bash. Native `cmd.exe` and P
 
 #### Startup Modes
 
-DeerFlow runs the agent runtime inside the Gateway API. Development mode enables hot-reload; production mode uses a pre-built frontend.
+DeerFlow supports multiple startup modes across two dimensions:
+
+- **Dev / Prod** — dev enables hot-reload; prod uses pre-built frontend
+- **Standard / Gateway** — standard uses a separate LangGraph server (4 processes); Gateway mode (experimental) embeds the agent runtime in the Gateway API (3 processes)
 
 | | **Local Foreground** | **Local Daemon** | **Docker Dev** | **Docker Prod** |
 |---|---|---|---|---|
 | **Dev** | `./scripts/serve.sh --dev`<br/>`make dev` | `./scripts/serve.sh --dev --daemon`<br/>`make dev-daemon` | `./scripts/docker.sh start`<br/>`make docker-start` | — |
+| **Dev + Gateway** | `./scripts/serve.sh --dev --gateway`<br/>`make dev-pro` | `./scripts/serve.sh --dev --gateway --daemon`<br/>`make dev-daemon-pro` | `./scripts/docker.sh start --gateway`<br/>`make docker-start-pro` | — |
 | **Prod** | `./scripts/serve.sh --prod`<br/>`make start` | `./scripts/serve.sh --prod --daemon`<br/>`make start-daemon` | — | `./scripts/deploy.sh`<br/>`make up` |
+| **Prod + Gateway** | `./scripts/serve.sh --prod --gateway`<br/>`make start-pro` | `./scripts/serve.sh --prod --gateway --daemon`<br/>`make start-daemon-pro` | — | `./scripts/deploy.sh --gateway`<br/>`make up-pro` |
 
 | Action | Local | Docker Dev | Docker Prod |
 |---|---|---|---|
 | **Stop** | `./scripts/serve.sh --stop`<br/>`make stop` | `./scripts/docker.sh stop`<br/>`make docker-stop` | `./scripts/deploy.sh down`<br/>`make down` |
 | **Restart** | `./scripts/serve.sh --restart [flags]` | `./scripts/docker.sh restart` | — |
 
-Gateway owns `/api/langgraph/*` and translates those public LangGraph-compatible paths to its native `/api/*` routers behind nginx.
+> **Gateway mode** eliminates the LangGraph server process — the Gateway API handles agent execution directly via async tasks, managing its own concurrency.
+
+#### Why Gateway Mode?
+
+In standard mode, DeerFlow runs a dedicated [LangGraph Platform](https://langchain-ai.github.io/langgraph/) server alongside the Gateway API. This architecture works well but has trade-offs:
+
+| | Standard Mode | Gateway Mode |
+|---|---|---|
+| **Architecture** | Gateway (REST API) + LangGraph (agent runtime) | Gateway embeds agent runtime |
+| **Concurrency** | `--n-jobs-per-worker` per worker (requires license) | `--workers` × async tasks (no per-worker cap) |
+| **Containers / Processes** | 4 (frontend, gateway, langgraph, nginx) | 3 (frontend, gateway, nginx) |
+| **Resource usage** | Higher (two Python runtimes) | Lower (single Python runtime) |
+| **LangGraph Platform license** | Required for production images | Not required |
+| **Cold start** | Slower (two services to initialize) | Faster |
+
+Both modes are functionally equivalent — the same agents, tools, and skills work in either mode.
 
 #### Docker Production Deployment
 
-`deploy.sh` supports building and starting separately:
+`deploy.sh` supports building and starting separately. Images are mode-agnostic — runtime mode is selected at start time:
 
 ```bash
 # One-step (build + start)
-deploy.sh
+deploy.sh                    # standard mode (default)
+deploy.sh --gateway          # gateway mode
 
-# Two-step (build once, start later)
+# Two-step (build once, start with any mode)
 deploy.sh build              # build all images
-deploy.sh start              # start pre-built images
+deploy.sh start              # start in standard mode
+deploy.sh start --gateway    # start in gateway mode
 
 # Stop
 deploy.sh down
@@ -345,14 +370,13 @@ DeerFlow supports receiving tasks from messaging apps. Channels auto-start when
 | Feishu / Lark | WebSocket | Moderate |
 | WeChat | Tencent iLink (long-polling) | Moderate |
 | WeCom | WebSocket | Moderate |
-| DingTalk | Stream Push (WebSocket) | Moderate |
 
 **Configuration in `config.yaml`:**
 
 ```yaml
 channels:
-  # LangGraph-compatible Gateway API base URL (default: http://localhost:8001/api)
+  # LangGraph Server URL (default: http://localhost:2024)
-  langgraph_url: http://localhost:8001/api
+  langgraph_url: http://localhost:2024
   # Gateway API URL (default: http://localhost:8001)
   gateway_url: http://localhost:8001
 
@@ -415,19 +439,11 @@ channels:
           context:
             thinking_enabled: true
             subagent_enabled: true
-
-  dingtalk:
-    enabled: true
-    client_id: $DINGTALK_CLIENT_ID             # Client ID of your DingTalk application
-    client_secret: $DINGTALK_CLIENT_SECRET     # Client Secret of your DingTalk application
-    allowed_users: []                          # empty = allow all
-    card_template_id: ""                       # Optional: AI Card template ID for streaming typewriter effect
 ```
 
 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.
-- IM channel workers call Gateway's LangGraph-compatible API internally and automatically attach process-local internal auth plus the CSRF cookie/header pair required for thread and run creation.
 
 Set the corresponding API keys in your `.env` file:
 
@@ -450,10 +466,6 @@ WECHAT_ILINK_BOT_ID=your_ilink_bot_id
 # WeCom
 WECOM_BOT_ID=your_bot_id
 WECOM_BOT_SECRET=your_bot_secret
-
-# DingTalk
-DINGTALK_CLIENT_ID=your_client_id
-DINGTALK_CLIENT_SECRET=your_client_secret
 ```
 
 **Telegram Setup**
@@ -492,15 +504,7 @@ DINGTALK_CLIENT_SECRET=your_client_secret
 4. Make sure backend dependencies include `wecom-aibot-python-sdk`. The channel uses a WebSocket long connection and does not require a public callback URL.
 5. The current integration supports inbound text, image, and file messages. Final images/files generated by the agent are also sent back to the WeCom conversation.
 
-**DingTalk Setup**
+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`.
-
-1. Create a DingTalk application in the [DingTalk Developer Console](https://open.dingtalk.com/) and enable **Robot** capability.
-2. Set the message receiving mode to **Stream Mode** in the robot configuration page.
-3. Copy the `Client ID` and `Client Secret`, set `DINGTALK_CLIENT_ID` and `DINGTALK_CLIENT_SECRET` in `.env`, and enable the channel in `config.yaml`.
-4. *(Optional)* To enable streaming AI Card replies (typewriter effect), create an **AI Card** template on the [DingTalk Card Platform](https://open.dingtalk.com/document/dingstart/typewriter-effect-streaming-ai-card), then set `card_template_id` in `config.yaml` to the template ID. You also need to apply for the `Card.Streaming.Write` and `Card.Instance.Write` permissions.
-
-
-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://gateway:8001/api` and `http://gateway:8001`, or set `DEER_FLOW_CHANNELS_LANGGRAPH_URL` and `DEER_FLOW_CHANNELS_GATEWAY_URL`.
 
 **Commands**
 

README_fr.md

@@ -290,7 +290,6 @@ DeerFlow peut recevoir des tâches depuis des applications de messagerie. Les ca
 | Telegram | Bot API (long-polling) | Facile |
 | Slack | Socket Mode | Modérée |
 | Feishu / Lark | WebSocket | Modérée |
-| DingTalk | Stream Push (WebSocket) | Modérée |
 
 **Configuration dans `config.yaml` :**
 
@@ -342,13 +341,6 @@ channels:
           context:
             thinking_enabled: true
             subagent_enabled: true
-
-  dingtalk:
-    enabled: true
-    client_id: $DINGTALK_CLIENT_ID             # ClientId depuis DingTalk Open Platform
-    client_secret: $DINGTALK_CLIENT_SECRET     # ClientSecret depuis DingTalk Open Platform
-    allowed_users: []                          # vide = tout le monde autorisé
-    card_template_id: ""                       # Optionnel : ID de modèle AI Card pour l'effet machine à écrire en streaming
 ```
 
 Définissez les clés API correspondantes dans votre fichier `.env` :
@@ -364,10 +356,6 @@ SLACK_APP_TOKEN=xapp-...
 # Feishu / Lark
 FEISHU_APP_ID=cli_xxxx
 FEISHU_APP_SECRET=your_app_secret
-
-# DingTalk
-DINGTALK_CLIENT_ID=your_client_id
-DINGTALK_CLIENT_SECRET=your_client_secret
 ```
 
 **Configuration Telegram**
@@ -390,13 +378,6 @@ DINGTALK_CLIENT_SECRET=your_client_secret
 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`.
 
-**Configuration DingTalk**
-
-1. Créez une application sur [DingTalk Open Platform](https://open.dingtalk.com/) et activez la capacité **Robot**.
-2. Dans la page de configuration du robot, définissez le mode de réception des messages sur **Stream**.
-3. Copiez le `Client ID` et le `Client Secret`. Définissez `DINGTALK_CLIENT_ID` et `DINGTALK_CLIENT_SECRET` dans `.env` et activez le canal dans `config.yaml`.
-4. *(Optionnel)* Pour activer les réponses en streaming AI Card (effet machine à écrire), créez un modèle **AI Card** sur la [plateforme de cartes DingTalk](https://open.dingtalk.com/document/dingstart/typewriter-effect-streaming-ai-card), puis définissez `card_template_id` dans `config.yaml` avec l'ID du modèle. Vous devez également demander les permissions `Card.Streaming.Write` et `Card.Instance.Write`.
-
 **Commandes**
 
 Une fois un canal connecté, vous pouvez interagir avec DeerFlow directement depuis le chat :

README_ja.md

@@ -243,7 +243,6 @@ DeerFlowはメッセージングアプリからのタスク受信をサポート
 | Telegram | Bot API（ロングポーリング） | 簡単 |
 | Slack | Socket Mode | 中程度 |
 | Feishu / Lark | WebSocket | 中程度 |
-| DingTalk | Stream Push（WebSocket） | 中程度 |
 
 **`config.yaml`での設定：**
 
@@ -295,13 +294,6 @@ channels:
           context:
             thinking_enabled: true
             subagent_enabled: true
-
-  dingtalk:
-    enabled: true
-    client_id: $DINGTALK_CLIENT_ID             # DingTalk Open PlatformのClientId
-    client_secret: $DINGTALK_CLIENT_SECRET     # DingTalk Open PlatformのClientSecret
-    allowed_users: []                          # 空 = 全員許可
-    card_template_id: ""                       # オプション：ストリーミングタイプライター効果用のAIカードテンプレートID
 ```
 
 対応するAPIキーを`.env`ファイルに設定します：
@@ -317,10 +309,6 @@ SLACK_APP_TOKEN=xapp-...
 # Feishu / Lark
 FEISHU_APP_ID=cli_xxxx
 FEISHU_APP_SECRET=your_app_secret
-
-# DingTalk
-DINGTALK_CLIENT_ID=your_client_id
-DINGTALK_CLIENT_SECRET=your_client_secret
 ```
 
 **Telegramのセットアップ**
@@ -343,13 +331,6 @@ DINGTALK_CLIENT_SECRET=your_client_secret
 3. **イベント**で`im.message.receive_v1`を購読し、**ロングコネクション**モードを選択。
 4. App IDとApp Secretをコピー。`.env`に`FEISHU_APP_ID`と`FEISHU_APP_SECRET`を設定し、`config.yaml`でチャネルを有効にします。
 
-**DingTalkのセットアップ**
-
-1. [DingTalk Open Platform](https://open.dingtalk.com/)でアプリを作成し、**ロボット**機能を有効化します。
-2. ロボット設定ページでメッセージ受信モードを**Streamモード**に設定します。
-3. `Client ID`と`Client Secret`をコピー。`.env`に`DINGTALK_CLIENT_ID`と`DINGTALK_CLIENT_SECRET`を設定し、`config.yaml`でチャネルを有効にします。
-4. *（オプション）* ストリーミングAIカード返信（タイプライター効果）を有効にするには、[DingTalkカードプラットフォーム](https://open.dingtalk.com/document/dingstart/typewriter-effect-streaming-ai-card)で**AIカード**テンプレートを作成し、`config.yaml`の`card_template_id`にテンプレートIDを設定します。`Card.Streaming.Write` および `Card.Instance.Write` 権限の申請も必要です。
-
 **コマンド**
 
 チャネル接続後、チャットから直接DeerFlowと対話できます：

README_ru.md

@@ -256,7 +256,6 @@ DeerFlow принимает задачи прямо из мессенджеро
 | Telegram | Bot API (long-polling) | Просто |
 | Slack | Socket Mode | Средне |
 | Feishu / Lark | WebSocket | Средне |
-| DingTalk | Stream Push (WebSocket) | Средне |
 
 **Конфигурация в `config.yaml`:**
 
@@ -279,13 +278,6 @@ channels:
     enabled: true
     bot_token: $TELEGRAM_BOT_TOKEN
     allowed_users: []
-
-  dingtalk:
-    enabled: true
-    client_id: $DINGTALK_CLIENT_ID             # ClientId с DingTalk Open Platform
-    client_secret: $DINGTALK_CLIENT_SECRET     # ClientSecret с DingTalk Open Platform
-    allowed_users: []                          # пусто = разрешить всем
-    card_template_id: ""                       # Опционально: ID шаблона AI Card для потокового эффекта печатной машинки
 ```
 
 **Настройка Telegram**
@@ -293,13 +285,6 @@ channels:
 1. Напишите [@BotFather](https://t.me/BotFather), отправьте `/newbot` и скопируйте HTTP API-токен.
 2. Укажите `TELEGRAM_BOT_TOKEN` в `.env` и включите канал в `config.yaml`.
 
-**Настройка DingTalk**
-
-1. Создайте приложение на [DingTalk Open Platform](https://open.dingtalk.com/) и включите возможность **Робот**.
-2. На странице настроек робота установите режим приёма сообщений на **Stream**.
-3. Скопируйте `Client ID` и `Client Secret`. Укажите `DINGTALK_CLIENT_ID` и `DINGTALK_CLIENT_SECRET` в `.env` и включите канал в `config.yaml`.
-4. *(Опционально)* Для включения потоковых ответов AI Card (эффект печатной машинки) создайте шаблон **AI Card** на [платформе карточек DingTalk](https://open.dingtalk.com/document/dingstart/typewriter-effect-streaming-ai-card), затем укажите `card_template_id` в `config.yaml` с ID шаблона. Также необходимо запросить разрешения `Card.Streaming.Write` и `Card.Instance.Write`.
-
 **Доступные команды**
 
 | Команда | Описание |

README_zh.md

@@ -194,7 +194,7 @@ make down   # 停止并移除容器
 
 如果你更希望直接在本地启动各个服务：
 
-前提：先完成上面的“配置”步骤（`make config` 和模型 API key 配置）。`make dev` 需要有效配置文件，默认读取项目根目录下的 `config.yaml`。可以用 `DEER_FLOW_PROJECT_ROOT` 显式指定项目根目录，也可以用 `DEER_FLOW_CONFIG_PATH` 指向某个具体配置文件。运行期状态默认写到项目根目录下的 `.deer-flow`，可用 `DEER_FLOW_HOME` 覆盖；skills 默认读取项目根目录下的 `skills/`，可用 `DEER_FLOW_SKILLS_PATH` 覆盖。
+前提：先完成上面的“配置”步骤（`make config` 和模型 API key 配置）。`make dev` 需要有效配置文件，默认读取项目根目录下的 `config.yaml`，也可以通过 `DEER_FLOW_CONFIG_PATH` 覆盖。
 在 Windows 上，请使用 Git Bash 运行本地开发流程。基于 bash 的服务脚本不支持直接在原生 `cmd.exe` 或 PowerShell 中执行，且 WSL 也不保证可用，因为部分脚本依赖 Git for Windows 的 `cygpath` 等工具。
 
 1. **检查依赖环境**：
@@ -248,7 +248,6 @@ DeerFlow 支持从即时通讯应用接收任务。只要配置完成，对应
 | Slack | Socket Mode | 中等 |
 | Feishu / Lark | WebSocket | 中等 |
 | 企业微信智能机器人 | WebSocket | 中等 |
-| 钉钉 | Stream Push（WebSocket） | 中等 |
 
 **`config.yaml` 中的配置示例：**
 
@@ -305,13 +304,6 @@ channels:
           context:
             thinking_enabled: true
             subagent_enabled: true
-
-  dingtalk:
-    enabled: true
-    client_id: $DINGTALK_CLIENT_ID             # 钉钉开放平台 ClientId
-    client_secret: $DINGTALK_CLIENT_SECRET     # 钉钉开放平台 ClientSecret
-    allowed_users: []                          # 留空表示允许所有人
-    card_template_id: ""                       # 可选：AI 卡片模板 ID，用于流式打字机效果
 ```
 
 说明：
@@ -335,10 +327,6 @@ FEISHU_APP_SECRET=your_app_secret
 # 企业微信智能机器人
 WECOM_BOT_ID=your_bot_id
 WECOM_BOT_SECRET=your_bot_secret
-
-# 钉钉
-DINGTALK_CLIENT_ID=your_client_id
-DINGTALK_CLIENT_SECRET=your_client_secret
 ```
 
 **Telegram 配置**
@@ -369,13 +357,6 @@ DINGTALK_CLIENT_SECRET=your_client_secret
 4. 安装后端依赖时确保包含 `wecom-aibot-python-sdk`，渠道会通过 WebSocket 长连接接收消息，无需公网回调地址。
 5. 当前支持文本、图片和文件入站消息；agent 生成的最终图片/文件也会回传到企业微信会话中。
 
-**钉钉配置**
-
-1. 在 [钉钉开放平台](https://open.dingtalk.com/) 创建应用，并启用 **机器人** 能力。
-2. 在机器人配置页面设置消息接收模式为 **Stream模式**。
-3. 复制 `Client ID` 和 `Client Secret`，在 `.env` 中设置 `DINGTALK_CLIENT_ID` 和 `DINGTALK_CLIENT_SECRET`，并在 `config.yaml` 中启用该渠道。
-4. *（可选）* 如需开启流式 AI 卡片回复（打字机效果），请在[钉钉卡片平台](https://open.dingtalk.com/document/dingstart/typewriter-effect-streaming-ai-card)创建 **AI 卡片**模板，然后在 `config.yaml` 中将 `card_template_id` 设为该模板 ID。同时需要申请 `Card.Streaming.Write` 和 `Card.Instance.Write` 权限。
-
 **命令**
 
 渠道连接完成后，你可以直接在聊天窗口里和 DeerFlow 交互：

backend/CLAUDE.md

@@ -7,13 +7,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 DeerFlow is a LangGraph-based AI super agent system with a full-stack architecture. The backend provides a "super agent" with sandbox execution, persistent memory, subagent delegation, and extensible tool integration - all operating in per-thread isolated environments.
 
 **Architecture**:
-- **Gateway API** (port 8001): REST API plus embedded LangGraph-compatible agent runtime
+- **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
 - **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
 
-**Runtime**:
+**Runtime Modes**:
-- `make dev`, Docker dev, and production all run the agent runtime in Gateway via `RunManager` + `run_agent()` + `StreamBridge` (`packages/harness/deerflow/runtime/`). Nginx exposes that runtime at `/api/langgraph/*` and rewrites it to Gateway's native `/api/*` routers.
+- **Standard mode** (`make dev`): LangGraph Server handles agent execution as a separate process. 4 processes total.
+- **Gateway mode** (`make dev-pro`, experimental): Agent runtime embedded in Gateway via `RunManager` + `run_agent()` + `StreamBridge` (`packages/harness/deerflow/runtime/`). Service manages its own concurrency via async tasks. 3 processes total, no LangGraph Server.
 
 **Project Structure**:
 ```
@@ -23,7 +25,7 @@ deer-flow/
 ├── extensions_config.json      # MCP servers and skills configuration
 ├── backend/                    # Backend application (this directory)
 │   ├── Makefile               # Backend-only commands (dev, gateway, lint)
-│   ├── langgraph.json         # LangGraph Studio graph configuration
+│   ├── langgraph.json         # LangGraph server configuration
 │   ├── packages/
 │   │   └── harness/           # deerflow-harness package (import: deerflow.*)
 │   │       ├── pyproject.toml
@@ -81,15 +83,16 @@ 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 (Gateway + Frontend + Nginx), with config.yaml preflight
+make dev        # Start all services (LangGraph + Gateway + Frontend + Nginx), with config.yaml preflight
-make start      # Start production services locally
+make dev-pro    # Gateway mode (experimental): skip LangGraph, agent runtime embedded in Gateway
+make start-pro  # Production + Gateway mode (experimental)
 make stop       # Stop all services
 ```
 
 **Backend directory** (for backend development only):
 ```bash
 make install    # Install backend dependencies
-make dev        # Run Gateway API with reload (port 8001)
+make dev        # Run LangGraph server only (port 2024)
 make gateway    # Run Gateway API only (port 8001)
 make test       # Run all backend tests
 make lint       # Lint with ruff
@@ -112,7 +115,7 @@ CI runs these regression tests for every pull request via [.github/workflows/bac
 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, DingTalk).
+- **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.
 
@@ -127,7 +130,7 @@ from app.gateway.app import app
 from app.channels.service import start_channel_service
 
 # App → Harness (allowed)
-from deerflow.config import get_app_config
+from deerflow.config.app_config import AppConfig
 
 # Harness → App (FORBIDDEN — enforced by test_harness_boundary.py)
 # from app.gateway.routers.uploads import ...  # ← will fail CI
@@ -182,7 +185,16 @@ Setup: Copy `config.example.yaml` to `config.yaml` in the **project root** direc
 
 **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.
+**Config Lifecycle**: All config models are `frozen=True` (immutable after construction). `AppConfig.from_file()` is a pure function — no side effects, no process-global state. The resolved `AppConfig` is passed as an explicit parameter down every consumer lane:
+
+- **Gateway**: `app.state.config` populated in lifespan; routers receive it via `Depends(get_config)` from `app/gateway/deps.py`.
+- **Client**: `DeerFlowClient._app_config` captured in the constructor; every method reads `self._app_config`.
+- **Agent run**: wrapped in `DeerFlowContext(app_config=…)` and injected via LangGraph `Runtime[DeerFlowContext].context`. Middleware and tools read `runtime.context.app_config` directly or via `resolve_context(runtime)`.
+- **LangGraph Server bootstrap**: `make_lead_agent` (registered in `langgraph.json`) calls `AppConfig.from_file()` itself — the only place in production that loads from disk at agent-build time.
+
+To update config at runtime (Gateway API mutations for MCP/Skills), write the new file and call `AppConfig.from_file()` to build a fresh snapshot, then swap `app.state.config`. No mtime detection, no auto-reload, no ambient ContextVar lookup (`AppConfig.current()` has been removed).
+
+**DeerFlowContext**: Per-invocation typed context for the agent execution path, injected via LangGraph `Runtime[DeerFlowContext]`. Holds `app_config: AppConfig`, `thread_id: str`, `agent_name: str | None`. Gateway runtime and `DeerFlowClient` construct full `DeerFlowContext` at invoke time; the LangGraph Server boundary builds one inside `make_lead_agent`. Middleware and tools access context through `resolve_context(runtime)` which returns the typed `DeerFlowContext` — legacy dict/None shapes are rejected. Mutable runtime state (`sandbox_id`) flows through `ThreadState.sandbox`, not context.
 
 Configuration priority:
 1. Explicit `config_path` argument
@@ -205,7 +217,7 @@ Configuration priority:
 
 ### Gateway API (`app/gateway/`)
 
-FastAPI application on port 8001 with health check at `GET /health`. Set `GATEWAY_ENABLE_DOCS=false` to disable `/docs`, `/redoc`, and `/openapi.json` in production (default: enabled).
+FastAPI application on port 8001 with health check at `GET /health`.
 
 **Routers**:
 
@@ -263,10 +275,8 @@ Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` →
    - `present_files` - Make output files visible to user (only `/mnt/user-data/outputs`)
    - `ask_clarification` - Request clarification (intercepted by ClarificationMiddleware → interrupts)
    - `view_image` - Read image as base64 (added only if model supports vision)
-   - `setup_agent` - Bootstrap-only: persist a brand-new custom agent's `SOUL.md` and `config.yaml`. Bound only when `is_bootstrap=True`.
-   - `update_agent` - Custom-agent-only: persist self-updates to the current agent's `SOUL.md` / `config.yaml` from inside a normal chat (partial update + atomic write). Bound when `agent_name` is set and `is_bootstrap=False`.
 4. **Subagent tool** (if enabled):
-   - `task` - Delegate to subagent (description, prompt, subagent_type)
+   - `task` - Delegate to subagent (description, prompt, subagent_type, max_turns)
 
 **Community tools** (`packages/harness/deerflow/community/`):
 - `tavily/` - Web search (5 results default) and web fetch (4KB limit)
@@ -314,10 +324,9 @@ Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` →
 
 ### IM Channels System (`app/channels/`)
 
-Bridges external messaging platforms (Feishu, Slack, Telegram, DingTalk) to the DeerFlow agent via the LangGraph Server.
+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.
-**Architecture**: Channels communicate with Gateway through the `langgraph-sdk` HTTP client (same as the frontend), ensuring threads are created and managed server-side. The internal SDK client injects process-local internal auth plus a matching CSRF cookie/header pair so Gateway accepts state-changing thread/run requests from channel workers without relying on browser session cookies.
 
 **Components**:
 - `message_bus.py` - Async pub/sub hub (`InboundMessage` → queue → dispatcher; `OutboundMessage` → callbacks → channels)
@@ -325,25 +334,23 @@ Bridges external messaging platforms (Feishu, Slack, Telegram, DingTalk) to the
 - `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` / `dingtalk.py` - Platform-specific implementations (`feishu.py` tracks the running card `message_id` in memory and patches the same card in place; `dingtalk.py` optionally uses AI Card streaming for in-place updates when `card_template_id` is configured)
+- `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 through Gateway's LangGraph-compatible API
+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. DingTalk AI Card mode (when `card_template_id` configured): `runs.stream()` → create card with initial text → stream updates via `PUT /v1.0/card/streaming` → finalize on `is_final=True`. Falls back to `sampleMarkdown` if card creation or streaming fails
+7. For commands (`/new`, `/status`, `/models`, `/memory`, `/help`): handle locally or query Gateway API
-8. For commands (`/new`, `/status`, `/models`, `/memory`, `/help`): handle locally or query Gateway API
+8. Outbound → channel callbacks → platform reply
-9. Outbound → channel callbacks → platform reply
 
 **Configuration** (`config.yaml` -> `channels`):
-- `langgraph_url` - LangGraph-compatible Gateway API base URL (default: `http://localhost:8001/api`)
+- `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://gateway:8001/api` for `langgraph_url` and `http://gateway:8001` for `gateway_url`, or set `DEER_FLOW_CHANNELS_LANGGRAPH_URL` / `DEER_FLOW_CHANNELS_GATEWAY_URL`.
+- 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), `dingtalk` (client_id, client_secret, optional `card_template_id` for AI Card streaming)
+- Per-channel configs: `feishu` (app_id, app_secret), `slack` (bot_token, app_token), `telegram` (bot_token)
-
 
 ### Memory System (`packages/harness/deerflow/agents/memory/`)
 
@@ -356,11 +363,10 @@ Bridges external messaging platforms (Feishu, Slack, Telegram, DingTalk) to the
 **Per-User Isolation**:
 - Memory is stored per-user at `{base_dir}/users/{user_id}/memory.json`
 - Per-agent per-user memory at `{base_dir}/users/{user_id}/agents/{agent_name}/memory.json`
-- Custom agent definitions (`SOUL.md` + `config.yaml`) are also per-user at `{base_dir}/users/{user_id}/agents/{agent_name}/`. The legacy shared layout `{base_dir}/agents/{agent_name}/` remains read-only fallback for unmigrated installations
 - `user_id` is resolved via `get_effective_user_id()` from `deerflow.runtime.user_context`
 - In no-auth mode, `user_id` defaults to `"default"` (constant `DEFAULT_USER_ID`)
 - Absolute `storage_path` in config opts out of per-user isolation
-- **Migration**: Run `PYTHONPATH=. python scripts/migrate_user_isolation.py` to move legacy `memory.json`, `threads/`, and `agents/` into per-user layout. Supports `--dry-run` (preview changes) and `--user-id USER_ID` (assign unowned legacy data to a user, defaults to `default`).
+- **Migration**: Run `PYTHONPATH=. python scripts/migrate_user_isolation.py` to move legacy `memory.json` and `threads/` into per-user layout; supports `--dry-run`
 
 **Data Structure** (stored in `{base_dir}/users/{user_id}/memory.json`):
 - **User Context**: `workContext`, `personalContext`, `topOfMind` (1-3 sentence summaries)
@@ -413,9 +419,9 @@ Both can be modified at runtime via Gateway API endpoints or `DeerFlowClient` me
 
 `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 Gateway API uses. Shares the same config files and data directories. No FastAPI dependency.
+**Architecture**: Imports the same `deerflow` modules that LangGraph Server and Gateway API use. Shares the same config files and data directories. No FastAPI dependency.
 
-**Agent Conversation**:
+**Agent Conversation** (replaces LangGraph Server):
 - `chat(message, thread_id)` — synchronous, accumulates streaming deltas per message-id and returns the final AI text
 - `stream(message, thread_id)` — subscribes to LangGraph `stream_mode=["values", "messages", "custom"]` and yields `StreamEvent`:
   - `"values"` — full state snapshot (title, messages, artifacts); AI text already delivered via `messages` mode is **not** re-synthesized here to avoid duplicate deliveries
@@ -478,15 +484,20 @@ This starts all services and makes the application available at `http://localhos
 | | **Local Foreground** | **Local Daemon** | **Docker Dev** | **Docker Prod** |
 |---|---|---|---|---|
 | **Dev** | `./scripts/serve.sh --dev`<br/>`make dev` | `./scripts/serve.sh --dev --daemon`<br/>`make dev-daemon` | `./scripts/docker.sh start`<br/>`make docker-start` | — |
+| **Dev + Gateway** | `./scripts/serve.sh --dev --gateway`<br/>`make dev-pro` | `./scripts/serve.sh --dev --gateway --daemon`<br/>`make dev-daemon-pro` | `./scripts/docker.sh start --gateway`<br/>`make docker-start-pro` | — |
 | **Prod** | `./scripts/serve.sh --prod`<br/>`make start` | `./scripts/serve.sh --prod --daemon`<br/>`make start-daemon` | — | `./scripts/deploy.sh`<br/>`make up` |
+| **Prod + Gateway** | `./scripts/serve.sh --prod --gateway`<br/>`make start-pro` | `./scripts/serve.sh --prod --gateway --daemon`<br/>`make start-daemon-pro` | — | `./scripts/deploy.sh --gateway`<br/>`make up-pro` |
 
 | Action | Local | Docker Dev | Docker Prod |
 |---|---|---|---|
 | **Stop** | `./scripts/serve.sh --stop`<br/>`make stop` | `./scripts/docker.sh stop`<br/>`make docker-stop` | `./scripts/deploy.sh down`<br/>`make down` |
 | **Restart** | `./scripts/serve.sh --restart [flags]` | `./scripts/docker.sh restart` | — |
 
+Gateway mode embeds the agent runtime in Gateway, no LangGraph server.
+
 **Nginx routing**:
-- `/api/langgraph/*` → Gateway embedded runtime (8001), rewritten to `/api/*`
+- Standard mode: `/api/langgraph/*` → LangGraph Server (2024)
+- Gateway mode: `/api/langgraph/*` → Gateway embedded runtime (8001) (via envsubst)
 - `/api/*` (other) → Gateway API (8001)
 - `/` (non-API) → Frontend (3000)
 
@@ -495,11 +506,15 @@ This starts all services and makes the application available at `http://localhos
 From the **backend** directory:
 
 ```bash
-# Gateway API
+# Terminal 1: LangGraph server
+make dev
+
+# Terminal 2: Gateway API
 make gateway
 ```
 
 Direct access (without nginx):
+- LangGraph: `http://localhost:2024`
 - Gateway: `http://localhost:8001`
 
 ### Frontend Configuration
@@ -520,7 +535,6 @@ Multi-file upload with automatic document conversion:
 - 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
-- Duplicate filenames in a single upload request are auto-renamed with `_N` suffixes so later files do not truncate earlier files
 - Agent receives uploaded file list via `UploadsMiddleware`
 
 See [docs/FILE_UPLOAD.md](docs/FILE_UPLOAD.md) for details.

backend/Dockerfile

@@ -50,12 +50,6 @@ COPY backend ./backend
 RUN --mount=type=cache,target=/root/.cache/uv \
     sh -c "cd backend && UV_INDEX_URL=${UV_INDEX_URL:-https://pypi.org/simple} uv sync ${UV_EXTRAS:+--extra $UV_EXTRAS}"
 
-# UTF-8 locale prevents UnicodeEncodeError on Chinese/emoji content in minimal
-# containers where locale configuration may be missing and the default encoding is not UTF-8.
-ENV LANG=C.UTF-8
-ENV LC_ALL=C.UTF-8
-ENV PYTHONIOENCODING=utf-8
-
 # ── Stage 2: Dev ──────────────────────────────────────────────────────────────
 # Retains compiler toolchain from builder so startup-time `uv sync` can build
 # source distributions in development containers.
@@ -72,10 +66,6 @@ CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run uvicorn app.gateway.app:app
 # Clean image without build-essential — reduces size (~200 MB) and attack surface.
 FROM python:3.12-slim-bookworm
 
-ENV LANG=C.UTF-8
-ENV LC_ALL=C.UTF-8
-ENV PYTHONIOENCODING=utf-8
-
 # Copy Node.js runtime from builder (provides npx for MCP servers)
 COPY --from=builder /usr/bin/node /usr/bin/node
 COPY --from=builder /usr/lib/node_modules /usr/lib/node_modules

backend/Makefile

@@ -2,7 +2,7 @@ install:
 	uv sync
 
 dev:
-	PYTHONPATH=. uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload
+	uv run langgraph dev --no-browser --no-reload --n-jobs-per-worker 10
 
 gateway:
 	PYTHONPATH=. uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001

backend/README.md

@@ -124,7 +124,7 @@ 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, auto-renames duplicate filenames in one request) |
+| `POST /api/threads/{id}/uploads` | Upload files (auto-converts PDF/PPT/Excel/Word to Markdown, rejects directory paths) |
 | `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 |

backend/app/channels/__init__.py

@@ -2,7 +2,7 @@
 
 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 Gateway's LangGraph-compatible API.
+which uses ``langgraph-sdk`` to communicate with the underlying LangGraph Server.
 """
 
 from app.channels.base import Channel

backend/app/channels/base.py

@@ -31,10 +31,6 @@ class Channel(ABC):
     def is_running(self) -> bool:
         return self._running
 
-    @property
-    def supports_streaming(self) -> bool:
-        return False
-
     # -- lifecycle ---------------------------------------------------------
 
     @abstractmethod

backend/app/channels/dingtalk.py

@@ -1,740 +0,0 @@
-"""DingTalk channel implementation."""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import logging
-import re
-import threading
-import time
-from pathlib import Path
-from typing import Any
-
-import httpx
-
-from app.channels.base import Channel
-from app.channels.commands import KNOWN_CHANNEL_COMMANDS
-from app.channels.message_bus import InboundMessage, InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
-
-logger = logging.getLogger(__name__)
-
-DINGTALK_API_BASE = "https://api.dingtalk.com"
-
-_TOKEN_REFRESH_MARGIN_SECONDS = 300
-
-_CONVERSATION_TYPE_P2P = "1"
-_CONVERSATION_TYPE_GROUP = "2"
-
-_MAX_UPLOAD_SIZE_BYTES = 20 * 1024 * 1024
-
-
-def _normalize_conversation_type(raw: Any) -> str:
-    """Normalize ``conversationType`` to ``"1"`` (P2P) or ``"2"`` (group).
-
-    Stream payloads may send int or string values.
-    """
-    if raw is None:
-        return _CONVERSATION_TYPE_P2P
-    s = str(raw).strip()
-    if s == _CONVERSATION_TYPE_GROUP:
-        return _CONVERSATION_TYPE_GROUP
-    return _CONVERSATION_TYPE_P2P
-
-
-def _normalize_allowed_users(allowed_users: Any) -> set[str]:
-    if allowed_users is None:
-        return set()
-    if isinstance(allowed_users, str):
-        values = [allowed_users]
-    elif isinstance(allowed_users, (list, tuple, set)):
-        values = allowed_users
-    else:
-        logger.warning(
-            "DingTalk allowed_users should be a list of user IDs; treating %s as one string value",
-            type(allowed_users).__name__,
-        )
-        values = [allowed_users]
-    return {str(uid) for uid in values if str(uid)}
-
-
-def _is_dingtalk_command(text: str) -> bool:
-    if not text.startswith("/"):
-        return False
-    return text.split(maxsplit=1)[0].lower() in KNOWN_CHANNEL_COMMANDS
-
-
-def _extract_text_from_rich_text(rich_text_list: list) -> str:
-    parts: list[str] = []
-    for item in rich_text_list:
-        if isinstance(item, dict) and "text" in item:
-            parts.append(item["text"])
-    return " ".join(parts)
-
-
-_FENCED_CODE_BLOCK_RE = re.compile(r"```(\w*)\n(.*?)```", re.DOTALL)
-_INLINE_CODE_RE = re.compile(r"`([^`\n]+)`")
-_HORIZONTAL_RULE_RE = re.compile(r"^-{3,}$", re.MULTILINE)
-_TABLE_SEPARATOR_RE = re.compile(r"^\|[-:| ]+\|$", re.MULTILINE)
-
-
-def _convert_markdown_table(text: str) -> str:
-    # DingTalk sampleMarkdown does not render pipe-delimited tables.
-    lines = text.split("\n")
-    result: list[str] = []
-    i = 0
-    while i < len(lines):
-        line = lines[i]
-        # Detect table: header row followed by separator row
-        if i + 1 < len(lines) and line.strip().startswith("|") and _TABLE_SEPARATOR_RE.match(lines[i + 1].strip()):
-            headers = [h.strip() for h in line.strip().strip("|").split("|")]
-            i += 2  # skip header + separator
-            while i < len(lines) and lines[i].strip().startswith("|"):
-                cells = [c.strip() for c in lines[i].strip().strip("|").split("|")]
-                for h, c in zip(headers, cells):
-                    result.append(f"> **{h}**: {c}")
-                result.append("")
-                i += 1
-        else:
-            result.append(line)
-            i += 1
-    return "\n".join(result)
-
-
-def _adapt_markdown_for_dingtalk(text: str) -> str:
-    """Adapt markdown for DingTalk's limited sampleMarkdown renderer."""
-
-    def _code_block_to_quote(match: re.Match) -> str:
-        lang = match.group(1)
-        code = match.group(2).rstrip("\n")
-        prefix = f"> **{lang}**\n" if lang else ""
-        quoted_lines = "\n".join(f"> {line}" for line in code.split("\n"))
-        return f"{prefix}{quoted_lines}\n"
-
-    text = _FENCED_CODE_BLOCK_RE.sub(_code_block_to_quote, text)
-    text = _INLINE_CODE_RE.sub(r"**\1**", text)
-    text = _convert_markdown_table(text)
-    text = _HORIZONTAL_RULE_RE.sub("───────────", text)
-    return text
-
-
-class DingTalkChannel(Channel):
-    """DingTalk IM channel using Stream Push (WebSocket, no public IP needed)."""
-
-    def __init__(self, bus: MessageBus, config: dict[str, Any]) -> None:
-        super().__init__(name="dingtalk", bus=bus, config=config)
-        self._thread: threading.Thread | None = None
-        self._main_loop: asyncio.AbstractEventLoop | None = None
-        self._client_id: str = ""
-        self._client_secret: str = ""
-        self._allowed_users: set[str] = _normalize_allowed_users(config.get("allowed_users"))
-        self._cached_token: str = ""
-        self._token_expires_at: float = 0.0
-        self._token_lock = asyncio.Lock()
-        self._card_template_id: str = config.get("card_template_id", "")
-        self._card_track_ids: dict[str, str] = {}
-        self._dingtalk_client: Any = None
-        self._stream_client: Any = None
-        self._incoming_messages: dict[str, Any] = {}
-        self._incoming_messages_lock = threading.Lock()
-        self._card_repliers: dict[str, Any] = {}
-
-    @property
-    def supports_streaming(self) -> bool:
-        return bool(self._card_template_id)
-
-    async def start(self) -> None:
-        if self._running:
-            return
-
-        try:
-            import dingtalk_stream  # noqa: F401
-        except ImportError:
-            logger.error("dingtalk-stream is not installed. Install it with: uv add dingtalk-stream")
-            return
-
-        client_id = self.config.get("client_id", "")
-        client_secret = self.config.get("client_secret", "")
-
-        if not client_id or not client_secret:
-            logger.error("DingTalk channel requires client_id and client_secret")
-            return
-
-        self._client_id = client_id
-        self._client_secret = client_secret
-        self._main_loop = asyncio.get_running_loop()
-
-        if self._card_template_id:
-            logger.info("[DingTalk] AI Card mode enabled (template=%s)", self._card_template_id)
-
-        self._running = True
-        self.bus.subscribe_outbound(self._on_outbound)
-
-        self._thread = threading.Thread(
-            target=self._run_stream,
-            args=(client_id, client_secret),
-            daemon=True,
-        )
-        self._thread.start()
-        logger.info("DingTalk channel started")
-
-    async def stop(self) -> None:
-        self._running = False
-        self.bus.unsubscribe_outbound(self._on_outbound)
-
-        stream_client = self._stream_client
-        if stream_client is not None:
-            try:
-                if hasattr(stream_client, "disconnect"):
-                    stream_client.disconnect()
-            except Exception:
-                logger.debug("[DingTalk] error disconnecting stream client", exc_info=True)
-
-        self._dingtalk_client = None
-        self._stream_client = None
-        with self._incoming_messages_lock:
-            self._incoming_messages.clear()
-        self._card_repliers.clear()
-        self._card_track_ids.clear()
-        if self._thread:
-            self._thread.join(timeout=5)
-            self._thread = None
-        logger.info("DingTalk channel stopped")
-
-    def _resolve_routing(self, msg: OutboundMessage) -> tuple[str, str, str]:
-        """Return (conversation_type, sender_staff_id, conversation_id).
-
-        Uses msg.chat_id as the primary routing key; metadata as fallback.
-        """
-        conversation_type = _normalize_conversation_type(msg.metadata.get("conversation_type"))
-        sender_staff_id = msg.metadata.get("sender_staff_id", "")
-        conversation_id = msg.metadata.get("conversation_id", "")
-        if conversation_type == _CONVERSATION_TYPE_GROUP:
-            conversation_id = msg.chat_id or conversation_id
-        else:
-            sender_staff_id = msg.chat_id or sender_staff_id
-        return conversation_type, sender_staff_id, conversation_id
-
-    async def send(self, msg: OutboundMessage, *, _max_retries: int = 3) -> None:
-        conversation_type, sender_staff_id, conversation_id = self._resolve_routing(msg)
-        robot_code = self._client_id
-
-        # Card mode: stream update to existing AI card
-        source_key = self._make_card_source_key_from_outbound(msg)
-        out_track_id = self._card_track_ids.get(source_key)
-
-        # ``card_template_id`` enables ``runs.stream`` (non-final + final outbounds).
-        # If card creation failed, skip non-final chunks to avoid duplicate messages.
-        if self._card_template_id and not out_track_id and not msg.is_final:
-            return
-
-        if out_track_id:
-            try:
-                await self._stream_update_card(
-                    out_track_id,
-                    msg.text,
-                    is_finalize=msg.is_final,
-                )
-            except Exception:
-                logger.warning("[DingTalk] card stream failed, falling back to sampleMarkdown")
-                if msg.is_final:
-                    self._card_track_ids.pop(source_key, None)
-                    self._card_repliers.pop(out_track_id, None)
-                    await self._send_markdown_fallback(robot_code, conversation_type, sender_staff_id, conversation_id, msg.text)
-                    return
-            if msg.is_final:
-                self._card_track_ids.pop(source_key, None)
-                self._card_repliers.pop(out_track_id, None)
-            return
-
-        # Non-card mode: send sampleMarkdown with retry
-        last_exc: Exception | None = None
-        for attempt in range(_max_retries):
-            try:
-                if conversation_type == _CONVERSATION_TYPE_GROUP:
-                    await self._send_group_message(robot_code, conversation_id, msg.text, at_user_ids=[sender_staff_id] if sender_staff_id else None)
-                else:
-                    await self._send_p2p_message(robot_code, sender_staff_id, msg.text)
-                return
-            except Exception as exc:
-                last_exc = exc
-                if attempt < _max_retries - 1:
-                    delay = 2**attempt
-                    logger.warning(
-                        "[DingTalk] send failed (attempt %d/%d), retrying in %ds: %s",
-                        attempt + 1,
-                        _max_retries,
-                        delay,
-                        exc,
-                    )
-                    await asyncio.sleep(delay)
-
-        logger.error("[DingTalk] send failed after %d attempts: %s", _max_retries, last_exc)
-        if last_exc is None:
-            raise RuntimeError("DingTalk send failed without an exception from any attempt")
-        raise last_exc
-
-    async def _send_markdown_fallback(
-        self,
-        robot_code: str,
-        conversation_type: str,
-        sender_staff_id: str,
-        conversation_id: str,
-        text: str,
-    ) -> None:
-        try:
-            if conversation_type == _CONVERSATION_TYPE_GROUP:
-                await self._send_group_message(robot_code, conversation_id, text)
-            else:
-                await self._send_p2p_message(robot_code, sender_staff_id, text)
-        except Exception:
-            logger.exception("[DingTalk] markdown fallback also failed")
-            raise
-
-    async def send_file(self, msg: OutboundMessage, attachment: ResolvedAttachment) -> bool:
-        if attachment.size > _MAX_UPLOAD_SIZE_BYTES:
-            logger.warning("[DingTalk] file too large (%d bytes), skipping: %s", attachment.size, attachment.filename)
-            return False
-
-        conversation_type, sender_staff_id, conversation_id = self._resolve_routing(msg)
-        robot_code = self._client_id
-
-        try:
-            media_id = await self._upload_media(attachment.actual_path, "image" if attachment.is_image else "file")
-            if not media_id:
-                return False
-
-            if attachment.is_image:
-                msg_key = "sampleImageMsg"
-                msg_param = json.dumps({"photoURL": media_id})
-            else:
-                msg_key = "sampleFile"
-                msg_param = json.dumps(
-                    {
-                        "fileUrl": media_id,
-                        "fileName": attachment.filename,
-                        "fileSize": str(attachment.size),
-                    }
-                )
-
-            token = await self._get_access_token()
-            async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
-                if conversation_type == _CONVERSATION_TYPE_GROUP:
-                    response = await client.post(
-                        f"{DINGTALK_API_BASE}/v1.0/robot/groupMessages/send",
-                        headers=self._api_headers(token),
-                        json={
-                            "msgKey": msg_key,
-                            "msgParam": msg_param,
-                            "robotCode": robot_code,
-                            "openConversationId": conversation_id,
-                        },
-                    )
-                else:
-                    response = await client.post(
-                        f"{DINGTALK_API_BASE}/v1.0/robot/oToMessages/batchSend",
-                        headers=self._api_headers(token),
-                        json={
-                            "msgKey": msg_key,
-                            "msgParam": msg_param,
-                            "robotCode": robot_code,
-                            "userIds": [sender_staff_id],
-                        },
-                    )
-                response.raise_for_status()
-
-            logger.info("[DingTalk] file sent: %s", attachment.filename)
-            return True
-        except (httpx.HTTPError, OSError, ValueError, TypeError, AttributeError):
-            logger.exception("[DingTalk] failed to send file: %s", attachment.filename)
-            return False
-
-    # -- stream client (runs in dedicated thread) --------------------------
-
-    def _run_stream(self, client_id: str, client_secret: str) -> None:
-        try:
-            import dingtalk_stream
-
-            credential = dingtalk_stream.Credential(client_id, client_secret)
-            client = dingtalk_stream.DingTalkStreamClient(credential)
-            self._stream_client = client
-            client.register_callback_handler(
-                dingtalk_stream.chatbot.ChatbotMessage.TOPIC,
-                _DingTalkMessageHandler(self),
-            )
-            client.start_forever()
-        except Exception:
-            if self._running:
-                logger.exception("DingTalk Stream Push error")
-        finally:
-            self._stream_client = None
-
-    def _on_chatbot_message(self, message: Any) -> None:
-        if not self._running:
-            return
-        try:
-            sender_staff_id = message.sender_staff_id or ""
-            conversation_type = _normalize_conversation_type(message.conversation_type)
-            conversation_id = message.conversation_id or ""
-            msg_id = message.message_id or ""
-            sender_nick = message.sender_nick or ""
-
-            if self._allowed_users and sender_staff_id not in self._allowed_users:
-                logger.debug("[DingTalk] ignoring message from non-allowed user: %s", sender_staff_id)
-                return
-
-            text = self._extract_text(message)
-            if not text:
-                logger.info("[DingTalk] empty text, ignoring message")
-                return
-
-            logger.info(
-                "[DingTalk] parsed message: conv_type=%s, msg_id=%s, sender=%s(%s), text=%r",
-                conversation_type,
-                msg_id,
-                sender_staff_id,
-                sender_nick,
-                text[:100],
-            )
-
-            if _is_dingtalk_command(text):
-                msg_type = InboundMessageType.COMMAND
-            else:
-                msg_type = InboundMessageType.CHAT
-
-            # P2P: topic_id=None (single thread per user, like Telegram private chat)
-            # Group: topic_id=msg_id (each new message starts a new topic, like Feishu)
-            topic_id: str | None = msg_id if conversation_type == _CONVERSATION_TYPE_GROUP else None
-
-            # chat_id uses conversation_id for groups, sender_staff_id for P2P
-            chat_id = conversation_id if conversation_type == _CONVERSATION_TYPE_GROUP else sender_staff_id
-
-            inbound = self._make_inbound(
-                chat_id=chat_id,
-                user_id=sender_staff_id,
-                text=text,
-                msg_type=msg_type,
-                thread_ts=msg_id,
-                metadata={
-                    "conversation_type": conversation_type,
-                    "conversation_id": conversation_id,
-                    "sender_staff_id": sender_staff_id,
-                    "sender_nick": sender_nick,
-                    "message_id": msg_id,
-                },
-            )
-            inbound.topic_id = topic_id
-
-            if self._card_template_id:
-                source_key = self._make_card_source_key(inbound)
-                with self._incoming_messages_lock:
-                    self._incoming_messages[source_key] = message
-
-            if self._main_loop and self._main_loop.is_running():
-                logger.info("[DingTalk] publishing inbound message to bus (type=%s, msg_id=%s)", msg_type.value, msg_id)
-                fut = asyncio.run_coroutine_threadsafe(
-                    self._prepare_inbound(chat_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("[DingTalk] main loop not running, cannot publish inbound message")
-        except Exception:
-            logger.exception("[DingTalk] error processing chatbot message")
-
-    @staticmethod
-    def _extract_text(message: Any) -> str:
-        msg_type = message.message_type
-        if msg_type == "text" and message.text:
-            return message.text.content.strip()
-        if msg_type == "richText" and message.rich_text_content:
-            return _extract_text_from_rich_text(message.rich_text_content.rich_text_list).strip()
-        return ""
-
-    async def _prepare_inbound(self, chat_id: str, inbound: InboundMessage) -> None:
-        # Running reply must finish before publish_inbound so AI card tracks are
-        # registered before the manager emits streaming outbounds.
-        await self._send_running_reply(chat_id, inbound)
-        await self.bus.publish_inbound(inbound)
-
-    async def _send_running_reply(self, chat_id: str, inbound: InboundMessage) -> None:
-        conversation_type = inbound.metadata.get("conversation_type", _CONVERSATION_TYPE_P2P)
-        sender_staff_id = inbound.metadata.get("sender_staff_id", "")
-        conversation_id = inbound.metadata.get("conversation_id", "")
-        text = "\u23f3 Working on it..."
-
-        try:
-            if self._card_template_id:
-                source_key = self._make_card_source_key(inbound)
-                with self._incoming_messages_lock:
-                    chatbot_message = self._incoming_messages.pop(source_key, None)
-                out_track_id = await self._create_and_deliver_card(
-                    text,
-                    chatbot_message=chatbot_message,
-                )
-                if out_track_id:
-                    self._card_track_ids[source_key] = out_track_id
-                    logger.info("[DingTalk] AI card running reply sent for chat=%s", chat_id)
-                    return
-
-            robot_code = self._client_id
-            if conversation_type == _CONVERSATION_TYPE_GROUP:
-                await self._send_text_message_to_group(robot_code, conversation_id, text)
-            else:
-                await self._send_text_message_to_user(robot_code, sender_staff_id, text)
-            logger.info("[DingTalk] 'Working on it...' reply sent for chat=%s", chat_id)
-        except Exception:
-            logger.exception("[DingTalk] failed to send running reply for chat=%s", chat_id)
-
-    # -- DingTalk API helpers ----------------------------------------------
-
-    async def _get_access_token(self) -> str:
-        if self._cached_token and time.monotonic() < self._token_expires_at:
-            return self._cached_token
-        async with self._token_lock:
-            if self._cached_token and time.monotonic() < self._token_expires_at:
-                return self._cached_token
-            async with httpx.AsyncClient(timeout=httpx.Timeout(10.0)) as client:
-                response = await client.post(
-                    f"{DINGTALK_API_BASE}/v1.0/oauth2/accessToken",
-                    json={"appKey": self._client_id, "appSecret": self._client_secret},  # DingTalk API field names
-                )
-                response.raise_for_status()
-                data = response.json()
-
-                if not isinstance(data, dict):
-                    raise ValueError(f"DingTalk access token response must be a JSON object, got {type(data).__name__}")
-
-                access_token = data.get("accessToken")
-                if not isinstance(access_token, str) or not access_token.strip():
-                    raise ValueError("DingTalk access token response did not contain a usable accessToken")
-
-                raw_expires_in = data.get("expireIn", 7200)
-                try:
-                    expires_in = int(raw_expires_in)
-                except (TypeError, ValueError):
-                    logger.warning("[DingTalk] invalid expireIn value %r, using default 7200s", raw_expires_in)
-                    expires_in = 7200
-
-                self._cached_token = access_token.strip()
-                self._token_expires_at = time.monotonic() + expires_in - _TOKEN_REFRESH_MARGIN_SECONDS
-                return self._cached_token
-
-    @staticmethod
-    def _api_headers(token: str) -> dict[str, str]:
-        return {
-            "x-acs-dingtalk-access-token": token,
-            "Content-Type": "application/json",
-        }
-
-    async def _send_text_message_to_user(self, robot_code: str, user_id: str, text: str) -> None:
-        token = await self._get_access_token()
-        async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
-            response = await client.post(
-                f"{DINGTALK_API_BASE}/v1.0/robot/oToMessages/batchSend",
-                headers=self._api_headers(token),
-                json={
-                    "msgKey": "sampleText",
-                    "msgParam": json.dumps({"content": text}),
-                    "robotCode": robot_code,
-                    "userIds": [user_id],
-                },
-            )
-            response.raise_for_status()
-
-    async def _send_text_message_to_group(self, robot_code: str, conversation_id: str, text: str) -> None:
-        token = await self._get_access_token()
-        async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
-            response = await client.post(
-                f"{DINGTALK_API_BASE}/v1.0/robot/groupMessages/send",
-                headers=self._api_headers(token),
-                json={
-                    "msgKey": "sampleText",
-                    "msgParam": json.dumps({"content": text}),
-                    "robotCode": robot_code,
-                    "openConversationId": conversation_id,
-                },
-            )
-            response.raise_for_status()
-
-    async def _send_p2p_message(self, robot_code: str, user_id: str, text: str) -> None:
-        text = _adapt_markdown_for_dingtalk(text)
-        token = await self._get_access_token()
-        async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
-            response = await client.post(
-                f"{DINGTALK_API_BASE}/v1.0/robot/oToMessages/batchSend",
-                headers=self._api_headers(token),
-                json={
-                    "msgKey": "sampleMarkdown",
-                    "msgParam": json.dumps({"title": "DeerFlow", "text": text}),
-                    "robotCode": robot_code,
-                    "userIds": [user_id],
-                },
-            )
-            response.raise_for_status()
-            data = response.json()
-            if data.get("processQueryKey"):
-                logger.info("[DingTalk] P2P message sent to user=%s", user_id)
-            else:
-                logger.warning("[DingTalk] P2P send response: %s", data)
-
-    async def _send_group_message(
-        self,
-        robot_code: str,
-        conversation_id: str,
-        text: str,
-        *,
-        at_user_ids: list[str] | None = None,  # noqa: ARG002
-    ) -> None:
-        # at_user_ids accepted for call-site compatibility but not passed to the API
-        # (sampleMarkdown does not support @mentions).
-        text = _adapt_markdown_for_dingtalk(text)
-        token = await self._get_access_token()
-
-        async with httpx.AsyncClient(timeout=httpx.Timeout(30.0)) as client:
-            response = await client.post(
-                f"{DINGTALK_API_BASE}/v1.0/robot/groupMessages/send",
-                headers=self._api_headers(token),
-                json={
-                    "msgKey": "sampleMarkdown",
-                    "msgParam": json.dumps({"title": "DeerFlow", "text": text}),
-                    "robotCode": robot_code,
-                    "openConversationId": conversation_id,
-                },
-            )
-            response.raise_for_status()
-            data = response.json()
-            if data.get("processQueryKey"):
-                logger.info("[DingTalk] group message sent to conversation=%s", conversation_id)
-            else:
-                logger.warning("[DingTalk] group send response: %s", data)
-
-    # -- AI Card streaming helpers -------------------------------------------
-
-    def _make_card_source_key(self, inbound: InboundMessage) -> str:
-        m = inbound.metadata
-        return f"{m.get('conversation_type', '')}:{m.get('sender_staff_id', '')}:{m.get('conversation_id', '')}:{m.get('message_id', '')}"
-
-    def _make_card_source_key_from_outbound(self, msg: OutboundMessage) -> str:
-        m = msg.metadata
-        correlation_id = m.get("message_id") or msg.thread_ts or ""
-        return f"{m.get('conversation_type', '')}:{m.get('sender_staff_id', '')}:{m.get('conversation_id', '')}:{correlation_id}"
-
-    async def _create_and_deliver_card(
-        self,
-        initial_text: str,
-        *,
-        chatbot_message: Any = None,
-    ) -> str | None:
-        if self._dingtalk_client is None or chatbot_message is None:
-            logger.warning("[DingTalk] SDK client or chatbot_message unavailable, skipping AI card")
-            return None
-
-        try:
-            from dingtalk_stream.card_replier import AICardReplier
-        except ImportError:
-            logger.warning("[DingTalk] dingtalk-stream card_replier not available")
-            return None
-
-        try:
-            replier = AICardReplier(self._dingtalk_client, chatbot_message)
-            card_instance_id = await replier.async_create_and_deliver_card(
-                card_template_id=self._card_template_id,
-                card_data={"content": initial_text},
-            )
-            if not card_instance_id:
-                return None
-
-            self._card_repliers[card_instance_id] = replier
-            logger.info("[DingTalk] AI card created: outTrackId=%s", card_instance_id)
-            return card_instance_id
-        except Exception:
-            logger.exception("[DingTalk] failed to create AI card")
-            return None
-
-    async def _stream_update_card(
-        self,
-        out_track_id: str,
-        content: str,
-        *,
-        is_finalize: bool = False,
-        is_error: bool = False,
-    ) -> None:
-        replier = self._card_repliers.get(out_track_id)
-        if not replier:
-            raise RuntimeError(f"No AICardReplier found for track ID {out_track_id}")
-
-        await replier.async_streaming(
-            card_instance_id=out_track_id,
-            content_key="content",
-            content_value=content,
-            append=False,
-            finished=is_finalize,
-            failed=is_error,
-        )
-
-    # -- media upload --------------------------------------------------------
-
-    async def _upload_media(self, file_path: str | Path, media_type: str) -> str | None:
-        try:
-            file_bytes = await asyncio.to_thread(Path(file_path).read_bytes)
-            token = await self._get_access_token()
-            async with httpx.AsyncClient(timeout=httpx.Timeout(60.0)) as client:
-                response = await client.post(
-                    f"{DINGTALK_API_BASE}/v1.0/files/upload",
-                    headers={"x-acs-dingtalk-access-token": token},
-                    files={"file": ("upload", file_bytes)},
-                    data={"type": media_type},
-                )
-                response.raise_for_status()
-                try:
-                    payload = response.json()
-                except json.JSONDecodeError:
-                    logger.exception("[DingTalk] failed to decode upload response JSON: %s", file_path)
-                    return None
-                if not isinstance(payload, dict):
-                    logger.warning("[DingTalk] unexpected upload response type %s for %s", type(payload).__name__, file_path)
-                    return None
-                return payload.get("mediaId")
-        except (httpx.HTTPError, OSError):
-            logger.exception("[DingTalk] failed to upload media: %s", file_path)
-            return None
-
-    @staticmethod
-    def _log_future_error(fut: Any, name: str, msg_id: str) -> None:
-        try:
-            exc = fut.exception()
-            if exc:
-                logger.error("[DingTalk] %s failed for msg_id=%s: %s", name, msg_id, exc)
-        except (asyncio.CancelledError, asyncio.InvalidStateError):
-            pass
-
-
-class _DingTalkMessageHandler:
-    """Callback handler registered with dingtalk-stream."""
-
-    def __init__(self, channel: DingTalkChannel) -> None:
-        self._channel = channel
-
-    def pre_start(self) -> None:
-        if hasattr(self, "dingtalk_client") and self.dingtalk_client is not None:
-            self._channel._dingtalk_client = self.dingtalk_client
-
-    async def raw_process(self, callback_message: Any) -> Any:
-        import dingtalk_stream
-        from dingtalk_stream.frames import Headers
-
-        code, message = await self.process(callback_message)
-        ack_message = dingtalk_stream.AckMessage()
-        ack_message.code = code
-        ack_message.headers.message_id = callback_message.headers.message_id
-        ack_message.headers.content_type = Headers.CONTENT_TYPE_APPLICATION_JSON
-        ack_message.data = {"response": message}
-        return ack_message
-
-    async def process(self, callback: Any) -> tuple[int, str]:
-        import dingtalk_stream
-
-        incoming_message = dingtalk_stream.ChatbotMessage.from_dict(callback.data)
-        self._channel._on_chatbot_message(incoming_message)
-        return dingtalk_stream.AckMessage.STATUS_OK, "OK"

backend/app/channels/feishu.py

@@ -63,10 +63,6 @@ class FeishuChannel(Channel):
         self._GetMessageResourceRequest = None
         self._thread_lock = threading.Lock()
 
-    @property
-    def supports_streaming(self) -> bool:
-        return True
-
     async def start(self) -> None:
         if self._running:
             return
@@ -379,7 +375,9 @@ class FeishuChannel(Channel):
         virtual_path = f"{VIRTUAL_PATH_PREFIX}/uploads/{resolved_target.name}"
 
         try:
-            sandbox_provider = get_sandbox_provider()
+            from deerflow.config.app_config import AppConfig
+
+            sandbox_provider = get_sandbox_provider(AppConfig.from_file())
             sandbox_id = sandbox_provider.acquire(thread_id)
             if sandbox_id != "local":
                 sandbox = sandbox_provider.get(sandbox_id)

backend/app/channels/manager.py

@@ -1,4 +1,4 @@
-"""ChannelManager — consumes inbound messages and dispatches them to the DeerFlow agent via Gateway."""
+"""ChannelManager — consumes inbound messages and dispatches them to the DeerFlow agent via LangGraph Server."""
 
 from __future__ import annotations
 
@@ -17,13 +17,11 @@ from langgraph_sdk.errors import ConflictError
 from app.channels.commands import KNOWN_CHANNEL_COMMANDS
 from app.channels.message_bus import InboundMessage, InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
 from app.channels.store import ChannelStore
-from app.gateway.csrf_middleware import CSRF_COOKIE_NAME, CSRF_HEADER_NAME, generate_csrf_token
-from app.gateway.internal_auth import create_internal_auth_headers
 from deerflow.runtime.user_context import get_effective_user_id
 
 logger = logging.getLogger(__name__)
 
-DEFAULT_LANGGRAPH_URL = "http://localhost:8001/api"
+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-]+$")
@@ -38,7 +36,6 @@ 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 = {
-    "dingtalk": {"supports_streaming": False},
     "discord": {"supports_streaming": False},
     "feishu": {"supports_streaming": True},
     "slack": {"supports_streaming": False},
@@ -49,13 +46,6 @@ CHANNEL_CAPABILITIES = {
 
 InboundFileReader = Callable[[dict[str, Any], httpx.AsyncClient], Awaitable[bytes | None]]
 
-_METADATA_DROP_KEYS = frozenset({"raw_message", "ref_msg"})
-
-
-def _slim_metadata(meta: dict[str, Any]) -> dict[str, Any]:
-    """Return a shallow copy of *meta* with known-large keys removed."""
-    return {k: v for k, v in meta.items() if k not in _METADATA_DROP_KEYS}
-
 
 INBOUND_FILE_READERS: dict[str, InboundFileReader] = {}
 
@@ -146,13 +136,6 @@ def _normalize_custom_agent_name(raw_value: str) -> str:
     return normalized
 
 
-def _strip_loop_warning_text(text: str) -> str:
-    """Remove middleware-authored loop warning lines from display text."""
-    if "[LOOP DETECTED]" not in text:
-        return text
-    return "\n".join(line for line in text.splitlines() if "[LOOP DETECTED]" not in line).strip()
-
-
 def _extract_response_text(result: dict | list) -> str:
     """Extract the last AI message text from a LangGraph runs.wait result.
 
@@ -162,7 +145,7 @@ def _extract_response_text(result: dict | list) -> str:
     Handles special cases:
     - Regular AI text responses
     - Clarification interrupts (``ask_clarification`` tool messages)
-    - Strips loop-detection warnings attached to tool-call AI messages
+    - AI messages with tool_calls but no text content
     """
     if isinstance(result, list):
         messages = result
@@ -192,12 +175,7 @@ def _extract_response_text(result: dict | list) -> str:
         # Regular AI message with text content
         if msg_type == "ai":
             content = msg.get("content", "")
-            has_tool_calls = bool(msg.get("tool_calls"))
             if isinstance(content, str) and content:
-                if has_tool_calls:
-                    content = _strip_loop_warning_text(content)
-                    if not content:
-                        continue
                 return content
             # content can be a list of content blocks
             if isinstance(content, list):
@@ -208,8 +186,6 @@ def _extract_response_text(result: dict | list) -> str:
                     elif isinstance(block, str):
                         parts.append(block)
                 text = "".join(parts)
-                if has_tool_calls:
-                    text = _strip_loop_warning_text(text)
                 if text:
                     return text
     return ""
@@ -434,13 +410,7 @@ async def _ingest_inbound_files(thread_id: str, msg: InboundMessage) -> list[dic
     if not msg.files:
         return []
 
-    from deerflow.uploads.manager import (
+    from deerflow.uploads.manager import claim_unique_filename, ensure_uploads_dir, normalize_filename
-        UnsafeUploadPathError,
-        claim_unique_filename,
-        ensure_uploads_dir,
-        normalize_filename,
-        write_upload_file_no_symlink,
-    )
 
     uploads_dir = ensure_uploads_dir(thread_id)
     seen_names = {entry.name for entry in uploads_dir.iterdir() if entry.is_file()}
@@ -491,10 +461,7 @@ async def _ingest_inbound_files(thread_id: str, msg: InboundMessage) -> list[dic
 
             dest = uploads_dir / safe_name
             try:
-                dest = write_upload_file_no_symlink(uploads_dir, safe_name, data)
+                dest.write_bytes(data)
-            except UnsafeUploadPathError:
-                logger.warning("[Manager] skipping inbound file with unsafe destination: %s", safe_name)
-                continue
             except Exception:
                 logger.exception("[Manager] failed to write inbound file: %s", dest)
                 continue
@@ -542,7 +509,7 @@ class ChannelManager:
     """Core dispatcher that bridges IM channels to the DeerFlow agent.
 
     It reads from the MessageBus inbound queue, creates/reuses threads on
-    Gateway's LangGraph-compatible API, sends messages via ``runs.wait``, and publishes
+    the LangGraph Server, sends messages via ``runs.wait``, and publishes
     outbound responses back through the bus.
     """
 
@@ -567,20 +534,12 @@ class ChannelManager:
         self._default_session = _as_dict(default_session)
         self._channel_sessions = dict(channel_sessions or {})
         self._client = None  # lazy init — langgraph_sdk async client
-        self._csrf_token = generate_csrf_token()
         self._semaphore: asyncio.Semaphore | None = None
         self._running = False
         self._task: asyncio.Task | None = None
 
     @staticmethod
     def _channel_supports_streaming(channel_name: str) -> bool:
-        from .service import get_channel_service
-
-        service = get_channel_service()
-        if service:
-            channel = service.get_channel(channel_name)
-            if channel is not None:
-                return channel.supports_streaming
         return CHANNEL_CAPABILITIES.get(channel_name, {}).get("supports_streaming", False)
 
     def _resolve_session_layer(self, msg: InboundMessage) -> tuple[dict[str, Any], dict[str, Any]]:
@@ -603,17 +562,6 @@ class ChannelManager:
             user_layer.get("config"),
         )
 
-        configurable = run_config.get("configurable")
-        if isinstance(configurable, Mapping):
-            configurable = dict(configurable)
-        else:
-            configurable = {}
-        run_config["configurable"] = configurable
-        # Pin channel-triggered runs to the root graph namespace so follow-up
-        # turns continue from the same conversation checkpoint.
-        configurable["checkpoint_ns"] = ""
-        configurable["thread_id"] = thread_id
-
         run_context = _merge_dicts(
             DEFAULT_RUN_CONTEXT,
             self._default_session.get("context"),
@@ -638,14 +586,7 @@ class ChannelManager:
         if self._client is None:
             from langgraph_sdk import get_client
 
-            self._client = get_client(
+            self._client = get_client(url=self._langgraph_url)
-                url=self._langgraph_url,
-                headers={
-                    **create_internal_auth_headers(),
-                    CSRF_HEADER_NAME: self._csrf_token,
-                    "Cookie": f"{CSRF_COOKIE_NAME}={self._csrf_token}",
-                },
-            )
         return self._client
 
     # -- lifecycle ---------------------------------------------------------
@@ -728,7 +669,7 @@ class ChannelManager:
     # -- chat handling -----------------------------------------------------
 
     async def _create_thread(self, client, msg: InboundMessage) -> str:
-        """Create a new thread through Gateway and store the mapping."""
+        """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(
@@ -738,7 +679,7 @@ class ChannelManager:
             topic_id=msg.topic_id,
             user_id=msg.user_id,
         )
-        logger.info("[Manager] new thread created through Gateway: thread_id=%s for chat_id=%s topic_id=%s", thread_id, msg.chat_id, msg.topic_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:
@@ -821,7 +762,6 @@ class ChannelManager:
             artifacts=artifacts,
             attachments=attachments,
             thread_ts=msg.thread_ts,
-            metadata=_slim_metadata(msg.metadata),
         )
         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)
@@ -883,7 +823,6 @@ class ChannelManager:
                         text=latest_text,
                         is_final=False,
                         thread_ts=msg.thread_ts,
-                        metadata=_slim_metadata(msg.metadata),
                     )
                 )
                 last_published_text = latest_text
@@ -928,7 +867,6 @@ class ChannelManager:
                     attachments=attachments,
                     is_final=True,
                     thread_ts=msg.thread_ts,
-                    metadata=_slim_metadata(msg.metadata),
                 )
             )
 
@@ -948,7 +886,7 @@ class ChannelManager:
             return
 
         if command == "new":
-            # Create a new thread through Gateway
+            # Create a new thread on the LangGraph Server
             client = self._get_client()
             thread = await client.threads.create()
             new_thread_id = thread["thread_id"]
@@ -987,7 +925,6 @@ class ChannelManager:
             thread_id=self.store.get_thread_id(msg.channel_name, msg.chat_id) or "",
             text=reply,
             thread_ts=msg.thread_ts,
-            metadata=_slim_metadata(msg.metadata),
         )
         await self.bus.publish_outbound(outbound)
 
@@ -997,11 +934,7 @@ class ChannelManager:
 
         try:
             async with httpx.AsyncClient() as http:
-                resp = await http.get(
+                resp = await http.get(f"{self._gateway_url}{path}", timeout=10)
-                    f"{self._gateway_url}{path}",
-                    timeout=10,
-                    headers=create_internal_auth_headers(),
-                )
                 resp.raise_for_status()
                 data = resp.json()
         except Exception:
@@ -1025,6 +958,5 @@ class ChannelManager:
             thread_id=self.store.get_thread_id(msg.channel_name, msg.chat_id) or "",
             text=error_text,
             thread_ts=msg.thread_ts,
-            metadata=_slim_metadata(msg.metadata),
         )
         await self.bus.publish_outbound(outbound)

backend/app/channels/service.py

@@ -11,14 +11,13 @@ from app.channels.manager import DEFAULT_GATEWAY_URL, DEFAULT_LANGGRAPH_URL, Cha
 from app.channels.message_bus import MessageBus
 from app.channels.store import ChannelStore
 
-logger = logging.getLogger(__name__)
-
 if TYPE_CHECKING:
     from deerflow.config.app_config import AppConfig
 
+logger = logging.getLogger(__name__)
+
 # Channel name → import path for lazy loading
 _CHANNEL_REGISTRY: dict[str, str] = {
-    "dingtalk": "app.channels.dingtalk:DingTalkChannel",
     "discord": "app.channels.discord:DiscordChannel",
     "feishu": "app.channels.feishu:FeishuChannel",
     "slack": "app.channels.slack:SlackChannel",
@@ -29,7 +28,6 @@ _CHANNEL_REGISTRY: dict[str, str] = {
 
 # Keys that indicate a user has configured credentials for a channel.
 _CHANNEL_CREDENTIAL_KEYS: dict[str, list[str]] = {
-    "dingtalk": ["client_id", "client_secret"],
     "discord": ["bot_token"],
     "feishu": ["app_id", "app_secret"],
     "slack": ["bot_token", "app_token"],
@@ -80,12 +78,8 @@ class ChannelService:
         self._running = False
 
     @classmethod
-    def from_app_config(cls, app_config: AppConfig | None = None) -> ChannelService:
+    def from_app_config(cls, app_config: AppConfig) -> ChannelService:
-        """Create a ChannelService from the application config."""
+        """Create a ChannelService from an explicit application config."""
-        if app_config is None:
-            from deerflow.config.app_config import get_app_config
-
-            app_config = get_app_config()
         channels_config = {}
         # extra fields are allowed by AppConfig (extra="allow")
         extra = app_config.model_extra or {}
@@ -168,16 +162,11 @@ class ChannelService:
 
         try:
             channel = channel_cls(bus=self.bus, config=config)
-            self._channels[name] = channel
             await channel.start()
-            if not channel.is_running:
+            self._channels[name] = channel
-                self._channels.pop(name, None)
-                logger.error("Channel %s did not enter a running state after start()", name)
-                return False
             logger.info("Channel %s started", name)
             return True
         except Exception:
-            self._channels.pop(name, None)
             logger.exception("Failed to start channel %s", name)
             return False
 
@@ -212,7 +201,7 @@ def get_channel_service() -> ChannelService | None:
     return _channel_service
 
 
-async def start_channel_service(app_config: AppConfig | None = None) -> ChannelService:
+async def start_channel_service(app_config: AppConfig) -> ChannelService:
     """Create and start the global ChannelService from app config."""
     global _channel_service
     if _channel_service is not None:

backend/app/channels/wecom.py

@@ -29,10 +29,6 @@ class WeComChannel(Channel):
         self._ws_stream_ids: dict[str, str] = {}
         self._working_message = "Working on it..."
 
-    @property
-    def supports_streaming(self) -> bool:
-        return True
-
     def _clear_ws_context(self, thread_ts: str | None) -> None:
         if not thread_ts:
             return

backend/app/gateway/app.py

@@ -28,13 +28,9 @@ from app.gateway.routers import (
     threads,
     uploads,
 )
-from deerflow.config import app_config as deerflow_app_config
+from deerflow.config.app_config import AppConfig
-from deerflow.config.app_config import apply_logging_level
 
-AppConfig = deerflow_app_config.AppConfig
+# Configure logging
-get_app_config = deerflow_app_config.get_app_config
-
-# Default logging; lifespan overrides from config.yaml log_level.
 logging.basicConfig(
     level=logging.INFO,
     format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
@@ -76,18 +72,7 @@ async def _ensure_admin_user(app: FastAPI) -> None:
     from deerflow.persistence.engine import get_session_factory
     from deerflow.persistence.user.model import UserRow
 
-    try:
+    provider = get_local_provider()
-        provider = get_local_provider()
-    except RuntimeError:
-        # Auth persistence may not be initialized in some test/boot paths.
-        # Skip admin migration work rather than failing gateway startup.
-        logger.warning("Auth persistence not ready; skipping admin bootstrap check")
-        return
-
-    sf = get_session_factory()
-    if sf is None:
-        return
-
     admin_count = await provider.count_admin_users()
 
     if admin_count == 0:
@@ -99,6 +84,10 @@ async def _ensure_admin_user(app: FastAPI) -> None:
 
     # Admin already exists — run orphan thread migration for any
     # LangGraph thread metadata that pre-dates the auth module.
+    sf = get_session_factory()
+    if sf is None:
+        return
+
     async with sf() as session:
         stmt = select(UserRow).where(UserRow.system_role == "admin").limit(1)
         row = (await session.execute(stmt)).scalar_one_or_none()
@@ -162,10 +151,11 @@ async def _migrate_orphaned_threads(store, admin_user_id: str) -> int:
 async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
     """Application lifespan handler."""
 
-    # Load config and check necessary environment variables at startup
     try:
-        app.state.config = get_app_config()
+        # ``app.state.config`` is the sole source of truth for
-        apply_logging_level(app.state.config.log_level)
+        # ``Depends(get_config)``. Consumers that want AppConfig must receive
+        # it as an explicit parameter; there is no ambient singleton.
+        app.state.config = AppConfig.from_file()
         logger.info("Configuration loaded successfully")
     except Exception as e:
         error_msg = f"Failed to load configuration during gateway startup: {e}"
@@ -218,8 +208,6 @@ def create_app() -> FastAPI:
     Returns:
         Configured FastAPI application instance.
     """
-    config = get_gateway_config()
-    docs_kwargs = {"docs_url": "/docs", "redoc_url": "/redoc", "openapi_url": "/openapi.json"} if config.enable_docs else {"docs_url": None, "redoc_url": None, "openapi_url": None}
 
     app = FastAPI(
         title="DeerFlow API Gateway",
@@ -244,7 +232,9 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
         """,
         version="0.1.0",
         lifespan=lifespan,
-        **docs_kwargs,
+        docs_url="/docs",
+        redoc_url="/redoc",
+        openapi_url="/openapi.json",
         openapi_tags=[
             {
                 "name": "models",

backend/app/gateway/auth/config.py

@@ -4,8 +4,11 @@ import logging
 import os
 import secrets
 
+from dotenv import load_dotenv
 from pydantic import BaseModel, Field
 
+load_dotenv()
+
 logger = logging.getLogger(__name__)
 
 
@@ -34,9 +37,6 @@ def get_auth_config() -> AuthConfig:
     """Get the global AuthConfig instance. Parses from env on first call."""
     global _auth_config
     if _auth_config is None:
-        from dotenv import load_dotenv
-
-        load_dotenv()
         jwt_secret = os.environ.get("AUTH_JWT_SECRET")
         if not jwt_secret:
             jwt_secret = secrets.token_urlsafe(32)

backend/app/gateway/auth/local_provider.py

@@ -1,14 +1,10 @@
 """Local email/password authentication provider."""
 
-import logging
-
 from app.gateway.auth.models import User
-from app.gateway.auth.password import hash_password_async, needs_rehash, verify_password_async
+from app.gateway.auth.password import hash_password_async, verify_password_async
 from app.gateway.auth.providers import AuthProvider
 from app.gateway.auth.repositories.base import UserRepository
 
-logger = logging.getLogger(__name__)
-
 
 class LocalAuthProvider(AuthProvider):
     """Email/password authentication provider using local database."""
@@ -47,15 +43,6 @@ class LocalAuthProvider(AuthProvider):
         if not await verify_password_async(password, user.password_hash):
             return None
 
-        if needs_rehash(user.password_hash):
-            try:
-                user.password_hash = await hash_password_async(password)
-                await self._repo.update_user(user)
-            except Exception:
-                # Rehash is an opportunistic upgrade; a transient DB error must not
-                # prevent an otherwise-valid login from succeeding.
-                logger.warning("Failed to rehash password for user %s; login will still succeed", user.email, exc_info=True)
-
         return user
 
     async def get_user(self, user_id: str) -> User | None:

backend/app/gateway/auth/password.py

@@ -1,66 +1,18 @@
-"""Password hashing utilities with versioned hash format.
+"""Password hashing utilities using bcrypt directly."""
-
-Hash format: ``$dfv<N>$<bcrypt_hash>`` where ``<N>`` is the version.
-
-- **v1** (legacy): ``bcrypt(password)`` — plain bcrypt, susceptible to
-  72-byte silent truncation.
-- **v2** (current): ``bcrypt(b64(sha256(password)))`` — SHA-256 pre-hash
-  avoids the 72-byte truncation limit so the full password contributes
-  to the hash.
-
-Verification auto-detects the version and falls back to v1 for hashes
-without a prefix, so existing deployments upgrade transparently on next
-login.
-"""
 
 import asyncio
-import base64
-import hashlib
 
 import bcrypt
 
-_CURRENT_VERSION = 2
-_PREFIX_V2 = "$dfv2$"
-_PREFIX_V1 = "$dfv1$"
-
-
-def _pre_hash_v2(password: str) -> bytes:
-    """SHA-256 pre-hash to bypass bcrypt's 72-byte limit."""
-    return base64.b64encode(hashlib.sha256(password.encode("utf-8")).digest())
-
 
 def hash_password(password: str) -> str:
-    """Hash a password (current version: v2 — SHA-256 + bcrypt)."""
+    """Hash a password using bcrypt."""
-    raw = bcrypt.hashpw(_pre_hash_v2(password), bcrypt.gensalt()).decode("utf-8")
+    return bcrypt.hashpw(password.encode("utf-8"), bcrypt.gensalt()).decode("utf-8")
-    return f"{_PREFIX_V2}{raw}"
 
 
 def verify_password(plain_password: str, hashed_password: str) -> bool:
-    """Verify a password, auto-detecting the hash version.
+    """Verify a password against its hash."""
-
+    return bcrypt.checkpw(plain_password.encode("utf-8"), hashed_password.encode("utf-8"))
-    Accepts v2 (``$dfv2$…``), v1 (``$dfv1$…``), and bare bcrypt hashes
-    (treated as v1 for backward compatibility with pre-versioning data).
-    """
-    try:
-        if hashed_password.startswith(_PREFIX_V2):
-            bcrypt_hash = hashed_password[len(_PREFIX_V2) :]
-            return bcrypt.checkpw(_pre_hash_v2(plain_password), bcrypt_hash.encode("utf-8"))
-
-        if hashed_password.startswith(_PREFIX_V1):
-            bcrypt_hash = hashed_password[len(_PREFIX_V1) :]
-        else:
-            bcrypt_hash = hashed_password
-
-        return bcrypt.checkpw(plain_password.encode("utf-8"), bcrypt_hash.encode("utf-8"))
-    except ValueError:
-        # bcrypt raises ValueError for malformed or corrupt hashes (e.g., invalid salt).
-        # Fail closed rather than crashing the request.
-        return False
-
-
-def needs_rehash(hashed_password: str) -> bool:
-    """Return True if the hash uses an older version and should be rehashed."""
-    return not hashed_password.startswith(_PREFIX_V2)
 
 
 async def hash_password_async(password: str) -> str:

backend/app/gateway/auth/providers.py

@@ -12,12 +12,12 @@ class AuthProvider(ABC):
 
         Returns User if authentication succeeds, None otherwise.
         """
-        raise NotImplementedError
+        ...
 
     @abstractmethod
     async def get_user(self, user_id: str) -> "User | None":
         """Retrieve user by ID."""
-        raise NotImplementedError
+        ...
 
 
 # Import User at runtime to avoid circular imports

backend/app/gateway/auth/repositories/base.py

@@ -35,7 +35,7 @@ class UserRepository(ABC):
         Raises:
             ValueError: If email already exists
         """
-        raise NotImplementedError
+        ...
 
     @abstractmethod
     async def get_user_by_id(self, user_id: str) -> User | None:
@@ -47,7 +47,7 @@ class UserRepository(ABC):
         Returns:
             User if found, None otherwise
         """
-        raise NotImplementedError
+        ...
 
     @abstractmethod
     async def get_user_by_email(self, email: str) -> User | None:
@@ -59,7 +59,7 @@ class UserRepository(ABC):
         Returns:
             User if found, None otherwise
         """
-        raise NotImplementedError
+        ...
 
     @abstractmethod
     async def update_user(self, user: User) -> User:
@@ -76,17 +76,17 @@ class UserRepository(ABC):
                 a hard failure (not a no-op) so callers cannot mistake a
                 concurrent-delete race for a successful update.
         """
-        raise NotImplementedError
+        ...
 
     @abstractmethod
     async def count_users(self) -> int:
         """Return total number of registered users."""
-        raise NotImplementedError
+        ...
 
     @abstractmethod
     async def count_admin_users(self) -> int:
         """Return number of users with system_role == 'admin'."""
-        raise NotImplementedError
+        ...
 
     @abstractmethod
     async def get_user_by_oauth(self, provider: str, oauth_id: str) -> User | None:
@@ -99,4 +99,4 @@ class UserRepository(ABC):
         Returns:
             User if found, None otherwise
         """
-        raise NotImplementedError
+        ...

backend/app/gateway/auth/reset_admin.py

@@ -25,14 +25,15 @@ from deerflow.persistence.user.model import UserRow
 
 
 async def _run(email: str | None) -> int:
-    from deerflow.config import get_app_config
+    from deerflow.config import AppConfig
     from deerflow.persistence.engine import (
         close_engine,
         get_session_factory,
         init_engine_from_config,
     )
 
-    config = get_app_config()
+    # CLI entry: load config explicitly at the top, pass down through the closure.
+    config = AppConfig.from_file()
     await init_engine_from_config(config.database)
     try:
         sf = get_session_factory()

backend/app/gateway/auth_middleware.py

@@ -18,7 +18,6 @@ from starlette.types import ASGIApp
 
 from app.gateway.auth.errors import AuthErrorCode, AuthErrorResponse
 from app.gateway.authz import _ALL_PERMISSIONS, AuthContext
-from app.gateway.internal_auth import INTERNAL_AUTH_HEADER_NAME, get_internal_user, is_valid_internal_auth_token
 from deerflow.runtime.user_context import reset_current_user, set_current_user
 
 # Paths that never require authentication.
@@ -76,12 +75,8 @@ class AuthMiddleware(BaseHTTPMiddleware):
         if _is_public(request.url.path):
             return await call_next(request)
 
-        internal_user = None
-        if is_valid_internal_auth_token(request.headers.get(INTERNAL_AUTH_HEADER_NAME)):
-            internal_user = get_internal_user()
-
         # Non-public path: require session cookie
-        if internal_user is None and not request.cookies.get("access_token"):
+        if not request.cookies.get("access_token"):
             return JSONResponse(
                 status_code=401,
                 content={
@@ -105,13 +100,10 @@ class AuthMiddleware(BaseHTTPMiddleware):
         # bubble up, so we catch and render it as JSONResponse here.
         from app.gateway.deps import get_current_user_from_request
 
-        if internal_user is not None:
+        try:
-            user = internal_user
+            user = await get_current_user_from_request(request)
-        else:
+        except HTTPException as exc:
-            try:
+            return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
-                user = await get_current_user_from_request(request)
-            except HTTPException as exc:
-                return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
 
         # Stamp both request.state.user (for the contextvar pattern)
         # and request.state.auth (so @require_permission's "auth is

backend/app/gateway/authz.py

@@ -30,9 +30,7 @@ Inspired by LangGraph Auth system: https://github.com/langchain-ai/langgraph/blo
 from __future__ import annotations
 
 import functools
-import inspect
 from collections.abc import Callable
-from types import SimpleNamespace
 from typing import TYPE_CHECKING, Any, ParamSpec, TypeVar
 
 from fastapi import HTTPException, Request
@@ -119,15 +117,6 @@ _ALL_PERMISSIONS: list[str] = [
 ]
 
 
-def _make_test_request_stub() -> Any:
-    """Create a minimal request-like object for direct unit calls.
-
-    Used when decorated route handlers are invoked without FastAPI's
-    request injection. Includes fields accessed by auth helpers.
-    """
-    return SimpleNamespace(state=SimpleNamespace(), cookies={}, _deerflow_test_bypass_auth=True)
-
-
 async def _authenticate(request: Request) -> AuthContext:
     """Authenticate request and return AuthContext.
 
@@ -145,11 +134,7 @@ async def _authenticate(request: Request) -> AuthContext:
 
 
 def require_auth[**P, T](func: Callable[P, T]) -> Callable[P, T]:
-    """Decorator that authenticates the request and enforces authentication.
+    """Decorator that authenticates the request and sets AuthContext.
-
-    Independently raises HTTP 401 for unauthenticated requests, regardless of
-    whether ``AuthMiddleware`` is present in the ASGI stack. Sets the resolved
-    ``AuthContext`` on ``request.state.auth`` for downstream handlers.
 
     Must be placed ABOVE other decorators (executes after them).
 
@@ -162,33 +147,19 @@ def require_auth[**P, T](func: Callable[P, T]) -> Callable[P, T]:
             ...
 
     Raises:
-        HTTPException: 401 if the request is unauthenticated.
+        ValueError: If 'request' parameter is missing
-        ValueError: If 'request' parameter is missing.
     """
 
     @functools.wraps(func)
     async def wrapper(*args: Any, **kwargs: Any) -> Any:
         request = kwargs.get("request")
         if request is None:
-            # Unit tests may call decorated handlers directly without a
+            raise ValueError("require_auth decorator requires 'request' parameter")
-            # FastAPI Request object. Inject a minimal request stub when
-            # the wrapped function declares `request`.
-            if "request" in inspect.signature(func).parameters:
-                kwargs["request"] = _make_test_request_stub()
-            else:
-                raise ValueError("require_auth decorator requires 'request' parameter")
-            request = kwargs["request"]
-
-        if getattr(request, "_deerflow_test_bypass_auth", False):
-            return await func(*args, **kwargs)
 
         # Authenticate and set context
         auth_context = await _authenticate(request)
         request.state.auth = auth_context
 
-        if not auth_context.is_authenticated:
-            raise HTTPException(status_code=401, detail="Authentication required")
-
         return await func(*args, **kwargs)
 
     return wrapper
@@ -239,17 +210,7 @@ def require_permission(
         async def wrapper(*args: Any, **kwargs: Any) -> Any:
             request = kwargs.get("request")
             if request is None:
-                # Unit tests may call decorated route handlers directly without
+                raise ValueError("require_permission decorator requires 'request' parameter")
-                # constructing a FastAPI Request object. Inject a minimal stub
-                # when the wrapped function declares `request`.
-                if "request" in inspect.signature(func).parameters:
-                    kwargs["request"] = _make_test_request_stub()
-                else:
-                    return await func(*args, **kwargs)
-                request = kwargs["request"]
-
-            if getattr(request, "_deerflow_test_bypass_auth", False):
-                return await func(*args, **kwargs)
 
             auth: AuthContext = getattr(request.state, "auth", None)
             if auth is None:

backend/app/gateway/config.py

@@ -9,7 +9,6 @@ class GatewayConfig(BaseModel):
     host: str = Field(default="0.0.0.0", description="Host to bind the gateway server")
     port: int = Field(default=8001, description="Port to bind the gateway server")
     cors_origins: list[str] = Field(default_factory=lambda: ["http://localhost:3000"], description="Allowed CORS origins")
-    enable_docs: bool = Field(default=True, description="Enable Swagger/ReDoc/OpenAPI endpoints")
 
 
 _gateway_config: GatewayConfig | None = None
@@ -24,6 +23,5 @@ def get_gateway_config() -> GatewayConfig:
             host=os.getenv("GATEWAY_HOST", "0.0.0.0"),
             port=int(os.getenv("GATEWAY_PORT", "8001")),
             cors_origins=cors_origins_str.split(","),
-            enable_docs=os.getenv("GATEWAY_ENABLE_DOCS", "true").lower() == "true",
         )
     return _gateway_config

backend/app/gateway/csrf_middleware.py

@@ -4,10 +4,8 @@ Per RFC-001:
 State-changing operations require CSRF protection.
 """
 
-import os
 import secrets
 from collections.abc import Callable
-from urllib.parse import urlsplit
 
 from fastapi import Request, Response
 from starlette.middleware.base import BaseHTTPMiddleware
@@ -21,7 +19,7 @@ CSRF_TOKEN_LENGTH = 64  # bytes
 
 def is_secure_request(request: Request) -> bool:
     """Detect whether the original client request was made over HTTPS."""
-    return _request_scheme(request) == "https"
+    return request.headers.get("x-forwarded-proto", request.url.scheme) == "https"
 
 
 def generate_csrf_token() -> str:
@@ -63,109 +61,6 @@ def is_auth_endpoint(request: Request) -> bool:
     return request.url.path.rstrip("/") in _AUTH_EXEMPT_PATHS
 
 
-def _host_with_optional_port(hostname: str, port: int | None, scheme: str) -> str:
-    """Return normalized host[:port], omitting default ports."""
-    host = hostname.lower()
-    if ":" in host and not host.startswith("["):
-        host = f"[{host}]"
-
-    if port is None or (scheme == "http" and port == 80) or (scheme == "https" and port == 443):
-        return host
-    return f"{host}:{port}"
-
-
-def _normalize_origin(origin: str) -> str | None:
-    """Return a normalized scheme://host[:port] origin, or None for invalid input."""
-    try:
-        parsed = urlsplit(origin.strip())
-        port = parsed.port
-    except ValueError:
-        return None
-
-    scheme = parsed.scheme.lower()
-    if scheme not in {"http", "https"} or not parsed.hostname:
-        return None
-
-    # Browser Origin is only scheme/host/port. Reject URL-shaped or credentialed values.
-    if parsed.username or parsed.password or parsed.path or parsed.query or parsed.fragment:
-        return None
-
-    return f"{scheme}://{_host_with_optional_port(parsed.hostname, port, scheme)}"
-
-
-def _configured_cors_origins() -> set[str]:
-    """Return explicit configured browser origins that may call auth routes."""
-    origins = set()
-    for raw_origin in os.environ.get("GATEWAY_CORS_ORIGINS", "").split(","):
-        origin = raw_origin.strip()
-        if not origin or origin == "*":
-            continue
-        normalized = _normalize_origin(origin)
-        if normalized:
-            origins.add(normalized)
-    return origins
-
-
-def _first_header_value(value: str | None) -> str | None:
-    """Return the first value from a comma-separated proxy header."""
-    if not value:
-        return None
-    first = value.split(",", 1)[0].strip()
-    return first or None
-
-
-def _forwarded_param(request: Request, name: str) -> str | None:
-    """Extract a parameter from the first RFC 7239 Forwarded header entry."""
-    forwarded = _first_header_value(request.headers.get("forwarded"))
-    if not forwarded:
-        return None
-
-    for part in forwarded.split(";"):
-        key, sep, value = part.strip().partition("=")
-        if sep and key.lower() == name:
-            return value.strip().strip('"') or None
-    return None
-
-
-def _request_scheme(request: Request) -> str:
-    """Resolve the original request scheme from trusted proxy headers."""
-    scheme = _forwarded_param(request, "proto") or _first_header_value(request.headers.get("x-forwarded-proto")) or request.url.scheme
-    return scheme.lower()
-
-
-def _request_origin(request: Request) -> str | None:
-    """Build the origin for the URL the browser is targeting."""
-    scheme = _request_scheme(request)
-    host = _forwarded_param(request, "host") or _first_header_value(request.headers.get("x-forwarded-host")) or request.headers.get("host") or request.url.netloc
-
-    forwarded_port = _first_header_value(request.headers.get("x-forwarded-port"))
-    if forwarded_port and ":" not in host.rsplit("]", 1)[-1]:
-        host = f"{host}:{forwarded_port}"
-
-    return _normalize_origin(f"{scheme}://{host}")
-
-
-def is_allowed_auth_origin(request: Request) -> bool:
-    """Allow auth POSTs only from the same origin or explicit configured origins.
-
-    Login/register/initialize are exempt from the double-submit token because
-    first-time browser clients do not have a CSRF token yet. They still create
-    a session cookie, so browser requests with a hostile Origin header must be
-    rejected to prevent login CSRF / session fixation. Requests without Origin
-    are allowed for non-browser clients such as curl and mobile integrations.
-    """
-    origin = request.headers.get("origin")
-    if not origin:
-        return True
-
-    normalized_origin = _normalize_origin(origin)
-    if normalized_origin is None:
-        return False
-
-    request_origin = _request_origin(request)
-    return normalized_origin in _configured_cors_origins() or (request_origin is not None and normalized_origin == request_origin)
-
-
 class CSRFMiddleware(BaseHTTPMiddleware):
     """Middleware that implements CSRF protection using Double Submit Cookie pattern."""
 
@@ -175,12 +70,6 @@ class CSRFMiddleware(BaseHTTPMiddleware):
     async def dispatch(self, request: Request, call_next: Callable) -> Response:
         _is_auth = is_auth_endpoint(request)
 
-        if should_check_csrf(request) and _is_auth and not is_allowed_auth_origin(request):
-            return JSONResponse(
-                status_code=403,
-                content={"detail": "Cross-site auth request denied."},
-            )
-
         if should_check_csrf(request) and not _is_auth:
             cookie_token = request.cookies.get(CSRF_COOKIE_NAME)
             header_token = request.headers.get(CSRF_HEADER_NAME)

backend/app/gateway/deps.py

@@ -8,18 +8,14 @@ Initialization is handled directly in ``app.py`` via :class:`AsyncExitStack`.
 
 from __future__ import annotations
 
-from collections.abc import AsyncGenerator, Callable
+from collections.abc import AsyncGenerator
 from contextlib import AsyncExitStack, asynccontextmanager
-from typing import TYPE_CHECKING, TypeVar, cast
+from typing import TYPE_CHECKING
 
 from fastapi import FastAPI, HTTPException, Request
-from langgraph.types import Checkpointer
 
 from deerflow.config.app_config import AppConfig
-from deerflow.persistence.feedback import FeedbackRepository
+from deerflow.runtime import RunContext, RunManager
-from deerflow.runtime import RunContext, RunManager, StreamBridge
-from deerflow.runtime.events.store.base import RunEventStore
-from deerflow.runtime.runs.store.base import RunStore
 
 if TYPE_CHECKING:
     from app.gateway.auth.local_provider import LocalAuthProvider
@@ -27,15 +23,17 @@ if TYPE_CHECKING:
     from deerflow.persistence.thread_meta.base import ThreadMetaStore
 
 
-T = TypeVar("T")
-
-
 def get_config(request: Request) -> AppConfig:
-    """Return the app-scoped ``AppConfig`` stored on ``app.state``."""
+    """FastAPI dependency returning the app-scoped ``AppConfig``.
-    config = getattr(request.app.state, "config", None)
+
-    if config is None:
+    Reads from ``request.app.state.config`` which is set at startup
+    (``app.py`` lifespan) and swapped on config reload (``routers/mcp.py``,
+    ``routers/skills.py``).
+    """
+    cfg = getattr(request.app.state, "config", None)
+    if cfg is None:
         raise HTTPException(status_code=503, detail="Configuration not available")
-    return config
+    return cfg
 
 
 @asynccontextmanager
@@ -53,9 +51,9 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
     from deerflow.runtime.events.store import make_run_event_store
 
     async with AsyncExitStack() as stack:
-        config = getattr(app.state, "config", None)
+        # app.state.config is populated earlier in lifespan(); thread it
-        if config is None:
+        # explicitly into every provider below.
-            raise RuntimeError("langgraph_runtime() requires app.state.config to be initialized")
+        config = app.state.config
 
         app.state.stream_bridge = await stack.enter_async_context(make_stream_bridge(config))
 
@@ -102,25 +100,25 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
 # ---------------------------------------------------------------------------
 
 
-def _require(attr: str, label: str) -> Callable[[Request], T]:
+def _require(attr: str, label: str):
     """Create a FastAPI dependency that returns ``app.state.<attr>`` or 503."""
 
-    def dep(request: Request) -> T:
+    def dep(request: Request):
         val = getattr(request.app.state, attr, None)
         if val is None:
             raise HTTPException(status_code=503, detail=f"{label} not available")
-        return cast(T, val)
+        return val
 
     dep.__name__ = dep.__qualname__ = f"get_{attr}"
     return dep
 
 
-get_stream_bridge: Callable[[Request], StreamBridge] = _require("stream_bridge", "Stream bridge")
+get_stream_bridge = _require("stream_bridge", "Stream bridge")
-get_run_manager: Callable[[Request], RunManager] = _require("run_manager", "Run manager")
+get_run_manager = _require("run_manager", "Run manager")
-get_checkpointer: Callable[[Request], Checkpointer] = _require("checkpointer", "Checkpointer")
+get_checkpointer = _require("checkpointer", "Checkpointer")
-get_run_event_store: Callable[[Request], RunEventStore] = _require("run_event_store", "Run event store")
+get_run_event_store = _require("run_event_store", "Run event store")
-get_feedback_repo: Callable[[Request], FeedbackRepository] = _require("feedback_repo", "Feedback")
+get_feedback_repo = _require("feedback_repo", "Feedback")
-get_run_store: Callable[[Request], RunStore] = _require("run_store", "Run store")
+get_run_store = _require("run_store", "Run store")
 
 
 def get_store(request: Request):
@@ -139,7 +137,10 @@ def get_thread_store(request: Request) -> ThreadMetaStore:
 def get_run_context(request: Request) -> RunContext:
     """Build a :class:`RunContext` from ``app.state`` singletons.
 
-    Returns a *base* context with infrastructure dependencies.
+    Returns a *base* context with infrastructure dependencies.  Callers that
+    need per-run fields (e.g. ``follow_up_to_run_id``) should use
+    ``dataclasses.replace(ctx, follow_up_to_run_id=...)`` before passing it
+    to :func:`run_agent`.
     """
     config = get_config(request)
     return RunContext(
@@ -152,6 +153,7 @@ def get_run_context(request: Request) -> RunContext:
     )
 
 
+
 # ---------------------------------------------------------------------------
 # Auth helpers (used by authz.py and auth middleware)
 # ---------------------------------------------------------------------------

backend/app/gateway/internal_auth.py

@@ -1,26 +0,0 @@
-"""Process-local authentication for Gateway internal callers."""
-
-from __future__ import annotations
-
-import secrets
-from types import SimpleNamespace
-
-from deerflow.runtime.user_context import DEFAULT_USER_ID
-
-INTERNAL_AUTH_HEADER_NAME = "X-DeerFlow-Internal-Token"
-_INTERNAL_AUTH_TOKEN = secrets.token_urlsafe(32)
-
-
-def create_internal_auth_headers() -> dict[str, str]:
-    """Return headers that authenticate same-process Gateway internal calls."""
-    return {INTERNAL_AUTH_HEADER_NAME: _INTERNAL_AUTH_TOKEN}
-
-
-def is_valid_internal_auth_token(token: str | None) -> bool:
-    """Return True when *token* matches the process-local internal token."""
-    return bool(token) and secrets.compare_digest(token, _INTERNAL_AUTH_TOKEN)
-
-
-def get_internal_user():
-    """Return the synthetic user used for trusted internal channel calls."""
-    return SimpleNamespace(id=DEFAULT_USER_ID, system_role="internal")

backend/app/gateway/langgraph_auth.py

@@ -73,7 +73,7 @@ async def authenticate(request):
     if isinstance(payload, TokenError):
         raise Auth.exceptions.HTTPException(
             status_code=401,
-            detail="Invalid token",
+            detail=f"Token error: {payload.value}",
         )
 
     user = await get_local_provider().get_user(payload.sub)

backend/app/gateway/routers/agents.py

@@ -5,13 +5,13 @@ import re
 import shutil
 
 import yaml
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel, Field
 
-from deerflow.config.agents_api_config import get_agents_api_config
+from app.gateway.deps import get_config
 from deerflow.config.agents_config import AgentConfig, list_custom_agents, load_agent_config, load_agent_soul
+from deerflow.config.app_config import AppConfig
 from deerflow.config.paths import get_paths
-from deerflow.runtime.user_context import get_effective_user_id
 
 logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api", tags=["agents"])
@@ -78,20 +78,20 @@ def _normalize_agent_name(name: str) -> str:
     return name.lower()
 
 
-def _require_agents_api_enabled() -> None:
+def _require_agents_api_enabled(app_config: AppConfig) -> None:
     """Reject access unless the custom-agent management API is explicitly enabled."""
-    if not get_agents_api_config().enabled:
+    if not app_config.agents_api.enabled:
         raise HTTPException(
             status_code=403,
             detail=("Custom-agent management API is disabled. Set agents_api.enabled=true to expose agent and user-profile routes over HTTP."),
         )
 
 
-def _agent_config_to_response(agent_cfg: AgentConfig, include_soul: bool = False, *, user_id: str | None = None) -> AgentResponse:
+def _agent_config_to_response(agent_cfg: AgentConfig, include_soul: bool = False) -> AgentResponse:
     """Convert AgentConfig to AgentResponse."""
     soul: str | None = None
     if include_soul:
-        soul = load_agent_soul(agent_cfg.name, user_id=user_id) or ""
+        soul = load_agent_soul(agent_cfg.name) or ""
 
     return AgentResponse(
         name=agent_cfg.name,
@@ -109,18 +109,17 @@ def _agent_config_to_response(agent_cfg: AgentConfig, include_soul: bool = False
     summary="List Custom Agents",
     description="List all custom agents available in the agents directory, including their soul content.",
 )
-async def list_agents() -> AgentsListResponse:
+async def list_agents(app_config: AppConfig = Depends(get_config)) -> AgentsListResponse:
     """List all custom agents.
 
     Returns:
         List of all custom agents with their metadata and soul content.
     """
-    _require_agents_api_enabled()
+    _require_agents_api_enabled(app_config)
 
-    user_id = get_effective_user_id()
     try:
-        agents = list_custom_agents(user_id=user_id)
+        agents = list_custom_agents()
-        return AgentsListResponse(agents=[_agent_config_to_response(a, include_soul=True, user_id=user_id) for a in agents])
+        return AgentsListResponse(agents=[_agent_config_to_response(a, include_soul=True) for a in agents])
     except Exception as e:
         logger.error(f"Failed to list agents: {e}", exc_info=True)
         raise HTTPException(status_code=500, detail=f"Failed to list agents: {str(e)}")
@@ -143,15 +142,10 @@ async def check_agent_name(name: str) -> dict:
     Raises:
         HTTPException: 422 if the name is invalid.
     """
-    _require_agents_api_enabled()
+    _require_agents_api_enabled(app_config)
     _validate_agent_name(name)
     normalized = _normalize_agent_name(name)
-    user_id = get_effective_user_id()
+    available = not get_paths().agent_dir(normalized).exists()
-    paths = get_paths()
-    # Treat the name as taken if either the per-user path or the legacy shared
-    # path holds an agent — picking a name that collides with an unmigrated
-    # legacy agent would shadow the legacy entry once migration runs.
-    available = not paths.user_agent_dir(user_id, normalized).exists() and not paths.agent_dir(normalized).exists()
     return {"available": available, "name": normalized}
 
 
@@ -161,7 +155,7 @@ async def check_agent_name(name: str) -> dict:
     summary="Get Custom Agent",
     description="Retrieve details and SOUL.md content for a specific custom agent.",
 )
-async def get_agent(name: str) -> AgentResponse:
+async def get_agent(name: str, app_config: AppConfig = Depends(get_config)) -> AgentResponse:
     """Get a specific custom agent by name.
 
     Args:
@@ -173,14 +167,13 @@ async def get_agent(name: str) -> AgentResponse:
     Raises:
         HTTPException: 404 if agent not found.
     """
-    _require_agents_api_enabled()
+    _require_agents_api_enabled(app_config)
     _validate_agent_name(name)
     name = _normalize_agent_name(name)
-    user_id = get_effective_user_id()
 
     try:
-        agent_cfg = load_agent_config(name, user_id=user_id)
+        agent_cfg = load_agent_config(name)
-        return _agent_config_to_response(agent_cfg, include_soul=True, user_id=user_id)
+        return _agent_config_to_response(agent_cfg, include_soul=True)
     except FileNotFoundError:
         raise HTTPException(status_code=404, detail=f"Agent '{name}' not found")
     except Exception as e:
@@ -195,7 +188,7 @@ async def get_agent(name: str) -> AgentResponse:
     summary="Create Custom Agent",
     description="Create a new custom agent with its config and SOUL.md.",
 )
-async def create_agent_endpoint(request: AgentCreateRequest) -> AgentResponse:
+async def create_agent_endpoint(request: AgentCreateRequest, app_config: AppConfig = Depends(get_config)) -> AgentResponse:
     """Create a new custom agent.
 
     Args:
@@ -207,16 +200,13 @@ async def create_agent_endpoint(request: AgentCreateRequest) -> AgentResponse:
     Raises:
         HTTPException: 409 if agent already exists, 422 if name is invalid.
     """
-    _require_agents_api_enabled()
+    _require_agents_api_enabled(app_config)
     _validate_agent_name(request.name)
     normalized_name = _normalize_agent_name(request.name)
-    user_id = get_effective_user_id()
-    paths = get_paths()
 
-    agent_dir = paths.user_agent_dir(user_id, normalized_name)
+    agent_dir = get_paths().agent_dir(normalized_name)
-    legacy_dir = paths.agent_dir(normalized_name)
 
-    if agent_dir.exists() or legacy_dir.exists():
+    if agent_dir.exists():
         raise HTTPException(status_code=409, detail=f"Agent '{normalized_name}' already exists")
 
     try:
@@ -243,8 +233,8 @@ async def create_agent_endpoint(request: AgentCreateRequest) -> AgentResponse:
 
         logger.info(f"Created agent '{normalized_name}' at {agent_dir}")
 
-        agent_cfg = load_agent_config(normalized_name, user_id=user_id)
+        agent_cfg = load_agent_config(normalized_name)
-        return _agent_config_to_response(agent_cfg, include_soul=True, user_id=user_id)
+        return _agent_config_to_response(agent_cfg, include_soul=True)
 
     except HTTPException:
         raise
@@ -262,7 +252,7 @@ async def create_agent_endpoint(request: AgentCreateRequest) -> AgentResponse:
     summary="Update Custom Agent",
     description="Update an existing custom agent's config and/or SOUL.md.",
 )
-async def update_agent(name: str, request: AgentUpdateRequest) -> AgentResponse:
+async def update_agent(name: str, request: AgentUpdateRequest, app_config: AppConfig = Depends(get_config)) -> AgentResponse:
     """Update an existing custom agent.
 
     Args:
@@ -275,23 +265,16 @@ async def update_agent(name: str, request: AgentUpdateRequest) -> AgentResponse:
     Raises:
         HTTPException: 404 if agent not found.
     """
-    _require_agents_api_enabled()
+    _require_agents_api_enabled(app_config)
     _validate_agent_name(name)
     name = _normalize_agent_name(name)
-    user_id = get_effective_user_id()
 
     try:
-        agent_cfg = load_agent_config(name, user_id=user_id)
+        agent_cfg = load_agent_config(name)
     except FileNotFoundError:
         raise HTTPException(status_code=404, detail=f"Agent '{name}' not found")
 
-    paths = get_paths()
+    agent_dir = get_paths().agent_dir(name)
-    agent_dir = paths.user_agent_dir(user_id, name)
-    if not agent_dir.exists() and paths.agent_dir(name).exists():
-        raise HTTPException(
-            status_code=409,
-            detail=(f"Agent '{name}' only exists in the legacy shared layout and is not scoped to a user. Run scripts/migrate_user_isolation.py to move legacy agents into the per-user layout before updating."),
-        )
 
     try:
         # Update config if any config fields changed
@@ -332,8 +315,8 @@ async def update_agent(name: str, request: AgentUpdateRequest) -> AgentResponse:
 
         logger.info(f"Updated agent '{name}'")
 
-        refreshed_cfg = load_agent_config(name, user_id=user_id)
+        refreshed_cfg = load_agent_config(name)
-        return _agent_config_to_response(refreshed_cfg, include_soul=True, user_id=user_id)
+        return _agent_config_to_response(refreshed_cfg, include_soul=True)
 
     except HTTPException:
         raise
@@ -360,13 +343,13 @@ class UserProfileUpdateRequest(BaseModel):
     summary="Get User Profile",
     description="Read the global USER.md file that is injected into all custom agents.",
 )
-async def get_user_profile() -> UserProfileResponse:
+async def get_user_profile(app_config: AppConfig = Depends(get_config)) -> UserProfileResponse:
     """Return the current USER.md content.
 
     Returns:
         UserProfileResponse with content=None if USER.md does not exist yet.
     """
-    _require_agents_api_enabled()
+    _require_agents_api_enabled(app_config)
 
     try:
         user_md_path = get_paths().user_md_file
@@ -385,7 +368,7 @@ async def get_user_profile() -> UserProfileResponse:
     summary="Update User Profile",
     description="Write the global USER.md file that is injected into all custom agents.",
 )
-async def update_user_profile(request: UserProfileUpdateRequest) -> UserProfileResponse:
+async def update_user_profile(request: UserProfileUpdateRequest, app_config: AppConfig = Depends(get_config)) -> UserProfileResponse:
     """Create or overwrite the global USER.md.
 
     Args:
@@ -394,7 +377,7 @@ async def update_user_profile(request: UserProfileUpdateRequest) -> UserProfileR
     Returns:
         UserProfileResponse with the saved content.
     """
-    _require_agents_api_enabled()
+    _require_agents_api_enabled(app_config)
 
     try:
         paths = get_paths()
@@ -413,29 +396,22 @@ async def update_user_profile(request: UserProfileUpdateRequest) -> UserProfileR
     summary="Delete Custom Agent",
     description="Delete a custom agent and all its files (config, SOUL.md, memory).",
 )
-async def delete_agent(name: str) -> None:
+async def delete_agent(name: str, app_config: AppConfig = Depends(get_config)) -> None:
     """Delete a custom agent.
 
     Args:
         name: The agent name.
 
     Raises:
-        HTTPException: 404 if no per-user copy exists; 409 if only a legacy
+        HTTPException: 404 if agent not found.
-            shared copy exists (suggesting the migration script).
     """
-    _require_agents_api_enabled()
+    _require_agents_api_enabled(app_config)
     _validate_agent_name(name)
     name = _normalize_agent_name(name)
-    user_id = get_effective_user_id()
+
-    paths = get_paths()
+    agent_dir = get_paths().agent_dir(name)
-    agent_dir = paths.user_agent_dir(user_id, name)
 
     if not agent_dir.exists():
-        if paths.agent_dir(name).exists():
-            raise HTTPException(
-                status_code=409,
-                detail=(f"Agent '{name}' only exists in the legacy shared layout and is not scoped to a user. Run scripts/migrate_user_isolation.py to move legacy agents into the per-user layout before deleting."),
-            )
         raise HTTPException(status_code=404, detail=f"Agent '{name}' not found")
 
     try:

backend/app/gateway/routers/auth.py

@@ -146,13 +146,7 @@ def _set_session_cookie(response: Response, token: str, request: Request) -> Non
 
 
 # ── Rate Limiting ────────────────────────────────────────────────────────
-# In-process dict — not shared across workers.
+# In-process dict — not shared across workers. Sufficient for single-worker deployments.
-#
-# **Limitation**: with multi-worker deployments (e.g., gunicorn -w N), each
-# worker maintains its own lockout table, so an attacker effectively gets
-# N × _MAX_LOGIN_ATTEMPTS guesses before being locked out everywhere. For
-# production multi-worker setups, replace this with a shared store (Redis,
-# database-backed counter) to enforce a true per-IP limit.
 
 _MAX_LOGIN_ATTEMPTS = 5
 _LOCKOUT_SECONDS = 300  # 5 minutes
@@ -382,37 +376,9 @@ async def get_me(request: Request):
     return UserResponse(id=str(user.id), email=user.email, system_role=user.system_role, needs_setup=user.needs_setup)
 
 
-_SETUP_STATUS_COOLDOWN: dict[str, float] = {}
-_SETUP_STATUS_COOLDOWN_SECONDS = 60
-_MAX_TRACKED_SETUP_STATUS_IPS = 10000
-
-
 @router.get("/setup-status")
-async def setup_status(request: Request):
+async def setup_status():
     """Check if an admin account exists. Returns needs_setup=True when no admin exists."""
-    client_ip = _get_client_ip(request)
-    now = time.time()
-    last_check = _SETUP_STATUS_COOLDOWN.get(client_ip, 0)
-    elapsed = now - last_check
-    if elapsed < _SETUP_STATUS_COOLDOWN_SECONDS:
-        retry_after = max(1, int(_SETUP_STATUS_COOLDOWN_SECONDS - elapsed))
-        raise HTTPException(
-            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
-            detail="Setup status check is rate limited",
-            headers={"Retry-After": str(retry_after)},
-        )
-    # Evict stale entries when dict grows too large to bound memory usage.
-    if len(_SETUP_STATUS_COOLDOWN) >= _MAX_TRACKED_SETUP_STATUS_IPS:
-        cutoff = now - _SETUP_STATUS_COOLDOWN_SECONDS
-        stale = [k for k, t in _SETUP_STATUS_COOLDOWN.items() if t < cutoff]
-        for k in stale:
-            del _SETUP_STATUS_COOLDOWN[k]
-        # If still too large after evicting expired entries, remove oldest half.
-        if len(_SETUP_STATUS_COOLDOWN) >= _MAX_TRACKED_SETUP_STATUS_IPS:
-            by_time = sorted(_SETUP_STATUS_COOLDOWN.items(), key=lambda kv: kv[1])
-            for k, _ in by_time[: len(by_time) // 2]:
-                del _SETUP_STATUS_COOLDOWN[k]
-    _SETUP_STATUS_COOLDOWN[client_ip] = now
     admin_count = await get_local_provider().count_admin_users()
     return {"needs_setup": admin_count == 0}
 

backend/app/gateway/routers/mcp.py

@@ -3,10 +3,12 @@ import logging
 from pathlib import Path
 from typing import Literal
 
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Request
 from pydantic import BaseModel, Field
 
-from deerflow.config.extensions_config import ExtensionsConfig, get_extensions_config, reload_extensions_config
+from app.gateway.deps import get_config
+from deerflow.config.app_config import AppConfig
+from deerflow.config.extensions_config import ExtensionsConfig
 
 logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api", tags=["mcp"])
@@ -69,7 +71,7 @@ class McpConfigUpdateRequest(BaseModel):
     summary="Get MCP Configuration",
     description="Retrieve the current Model Context Protocol (MCP) server configurations.",
 )
-async def get_mcp_configuration() -> McpConfigResponse:
+async def get_mcp_configuration(config: AppConfig = Depends(get_config)) -> McpConfigResponse:
     """Get the current MCP configuration.
 
     Returns:
@@ -90,9 +92,9 @@ async def get_mcp_configuration() -> McpConfigResponse:
         }
         ```
     """
-    config = get_extensions_config()
+    ext = config.extensions
 
-    return McpConfigResponse(mcp_servers={name: McpServerConfigResponse(**server.model_dump()) for name, server in config.mcp_servers.items()})
+    return McpConfigResponse(mcp_servers={name: McpServerConfigResponse(**server.model_dump()) for name, server in ext.mcp_servers.items()})
 
 
 @router.put(
@@ -101,7 +103,11 @@ async def get_mcp_configuration() -> McpConfigResponse:
     summary="Update MCP Configuration",
     description="Update Model Context Protocol (MCP) server configurations and save to file.",
 )
-async def update_mcp_configuration(request: McpConfigUpdateRequest) -> McpConfigResponse:
+async def update_mcp_configuration(
+    request: McpConfigUpdateRequest,
+    http_request: Request,
+    config: AppConfig = Depends(get_config),
+) -> McpConfigResponse:
     """Update the MCP configuration.
 
     This will:
@@ -142,13 +148,13 @@ async def update_mcp_configuration(request: McpConfigUpdateRequest) -> McpConfig
             config_path = Path.cwd().parent / "extensions_config.json"
             logger.info(f"No existing extensions config found. Creating new config at: {config_path}")
 
-        # Load current config to preserve skills configuration
+        # Use injected config to preserve skills configuration
-        current_config = get_extensions_config()
+        current_ext = config.extensions
 
         # Convert request to dict format for JSON serialization
         config_data = {
             "mcpServers": {name: server.model_dump() for name, server in request.mcp_servers.items()},
-            "skills": {name: {"enabled": skill.enabled} for name, skill in current_config.skills.items()},
+            "skills": {name: {"enabled": skill.enabled} for name, skill in current_ext.skills.items()},
         }
 
         # Write the configuration to file
@@ -160,9 +166,11 @@ async def update_mcp_configuration(request: McpConfigUpdateRequest) -> McpConfig
         # NOTE: No need to reload/reset cache here - LangGraph Server (separate process)
         # will detect config file changes via mtime and reinitialize MCP tools automatically
 
-        # Reload the configuration and update the global cache
+        # Reload the configuration and swap ``app.state.config`` so subsequent
-        reloaded_config = reload_extensions_config()
+        # ``Depends(get_config)`` calls see the refreshed value.
-        return McpConfigResponse(mcp_servers={name: McpServerConfigResponse(**server.model_dump()) for name, server in reloaded_config.mcp_servers.items()})
+        reloaded = AppConfig.from_file()
+        http_request.app.state.config = reloaded
+        return McpConfigResponse(mcp_servers={name: McpServerConfigResponse(**server.model_dump()) for name, server in reloaded.extensions.mcp_servers.items()})
 
     except Exception as e:
         logger.error(f"Failed to update MCP configuration: {e}", exc_info=True)

backend/app/gateway/routers/memory.py

@@ -1,8 +1,9 @@
 """Memory API router for retrieving and managing global memory data."""
 
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel, Field
 
+from app.gateway.deps import get_config
 from deerflow.agents.memory.updater import (
     clear_memory_data,
     create_memory_fact,
@@ -12,7 +13,7 @@ from deerflow.agents.memory.updater import (
     reload_memory_data,
     update_memory_fact,
 )
-from deerflow.config.memory_config import get_memory_config
+from deerflow.config.app_config import AppConfig
 from deerflow.runtime.user_context import get_effective_user_id
 
 router = APIRouter(prefix="/api", tags=["memory"])
@@ -114,7 +115,7 @@ class MemoryStatusResponse(BaseModel):
     summary="Get Memory Data",
     description="Retrieve the current global memory data including user context, history, and facts.",
 )
-async def get_memory() -> MemoryResponse:
+async def get_memory(app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
     """Get the current global memory data.
 
     Returns:
@@ -148,7 +149,7 @@ async def get_memory() -> MemoryResponse:
         }
         ```
     """
-    memory_data = get_memory_data(user_id=get_effective_user_id())
+    memory_data = get_memory_data(app_config.memory, user_id=get_effective_user_id())
     return MemoryResponse(**memory_data)
 
 
@@ -159,7 +160,7 @@ async def get_memory() -> MemoryResponse:
     summary="Reload Memory Data",
     description="Reload memory data from the storage file, refreshing the in-memory cache.",
 )
-async def reload_memory() -> MemoryResponse:
+async def reload_memory(app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
     """Reload memory data from file.
 
     This forces a reload of the memory data from the storage file,
@@ -168,7 +169,7 @@ async def reload_memory() -> MemoryResponse:
     Returns:
         The reloaded memory data.
     """
-    memory_data = reload_memory_data(user_id=get_effective_user_id())
+    memory_data = reload_memory_data(app_config.memory, user_id=get_effective_user_id())
     return MemoryResponse(**memory_data)
 
 
@@ -179,10 +180,10 @@ async def reload_memory() -> MemoryResponse:
     summary="Clear All Memory Data",
     description="Delete all saved memory data and reset the memory structure to an empty state.",
 )
-async def clear_memory() -> MemoryResponse:
+async def clear_memory(app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
     """Clear all persisted memory data."""
     try:
-        memory_data = clear_memory_data(user_id=get_effective_user_id())
+        memory_data = clear_memory_data(app_config.memory, user_id=get_effective_user_id())
     except OSError as exc:
         raise HTTPException(status_code=500, detail="Failed to clear memory data.") from exc
 
@@ -196,10 +197,11 @@ async def clear_memory() -> MemoryResponse:
     summary="Create Memory Fact",
     description="Create a single saved memory fact manually.",
 )
-async def create_memory_fact_endpoint(request: FactCreateRequest) -> MemoryResponse:
+async def create_memory_fact_endpoint(request: FactCreateRequest, app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
     """Create a single fact manually."""
     try:
         memory_data = create_memory_fact(
+            app_config.memory,
             content=request.content,
             category=request.category,
             confidence=request.confidence,
@@ -220,10 +222,10 @@ async def create_memory_fact_endpoint(request: FactCreateRequest) -> MemoryRespo
     summary="Delete Memory Fact",
     description="Delete a single saved memory fact by its fact id.",
 )
-async def delete_memory_fact_endpoint(fact_id: str) -> MemoryResponse:
+async def delete_memory_fact_endpoint(fact_id: str, app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
     """Delete a single fact from memory by fact id."""
     try:
-        memory_data = delete_memory_fact(fact_id, user_id=get_effective_user_id())
+        memory_data = delete_memory_fact(app_config.memory, fact_id, user_id=get_effective_user_id())
     except KeyError as exc:
         raise HTTPException(status_code=404, detail=f"Memory fact '{fact_id}' not found.") from exc
     except OSError as exc:
@@ -239,10 +241,11 @@ async def delete_memory_fact_endpoint(fact_id: str) -> MemoryResponse:
     summary="Patch Memory Fact",
     description="Partially update a single saved memory fact by its fact id while preserving omitted fields.",
 )
-async def update_memory_fact_endpoint(fact_id: str, request: FactPatchRequest) -> MemoryResponse:
+async def update_memory_fact_endpoint(fact_id: str, request: FactPatchRequest, app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
     """Partially update a single fact manually."""
     try:
         memory_data = update_memory_fact(
+            app_config.memory,
             fact_id=fact_id,
             content=request.content,
             category=request.category,
@@ -266,9 +269,9 @@ async def update_memory_fact_endpoint(fact_id: str, request: FactPatchRequest) -
     summary="Export Memory Data",
     description="Export the current global memory data as JSON for backup or transfer.",
 )
-async def export_memory() -> MemoryResponse:
+async def export_memory(app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
     """Export the current memory data."""
-    memory_data = get_memory_data(user_id=get_effective_user_id())
+    memory_data = get_memory_data(app_config.memory, user_id=get_effective_user_id())
     return MemoryResponse(**memory_data)
 
 
@@ -279,10 +282,10 @@ async def export_memory() -> MemoryResponse:
     summary="Import Memory Data",
     description="Import and overwrite the current global memory data from a JSON payload.",
 )
-async def import_memory(request: MemoryResponse) -> MemoryResponse:
+async def import_memory(request: MemoryResponse, app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
     """Import and persist memory data."""
     try:
-        memory_data = import_memory_data(request.model_dump(), user_id=get_effective_user_id())
+        memory_data = import_memory_data(app_config.memory, request.model_dump(), user_id=get_effective_user_id())
     except OSError as exc:
         raise HTTPException(status_code=500, detail="Failed to import memory data.") from exc
 
@@ -295,7 +298,9 @@ async def import_memory(request: MemoryResponse) -> MemoryResponse:
     summary="Get Memory Configuration",
     description="Retrieve the current memory system configuration.",
 )
-async def get_memory_config_endpoint() -> MemoryConfigResponse:
+async def get_memory_config_endpoint(
+    app_config: AppConfig = Depends(get_config),
+) -> MemoryConfigResponse:
     """Get the memory system configuration.
 
     Returns:
@@ -314,7 +319,7 @@ async def get_memory_config_endpoint() -> MemoryConfigResponse:
         }
         ```
     """
-    config = get_memory_config()
+    config = app_config.memory
     return MemoryConfigResponse(
         enabled=config.enabled,
         storage_path=config.storage_path,
@@ -333,14 +338,16 @@ async def get_memory_config_endpoint() -> MemoryConfigResponse:
     summary="Get Memory Status",
     description="Retrieve both memory configuration and current data in a single request.",
 )
-async def get_memory_status() -> MemoryStatusResponse:
+async def get_memory_status(
+    app_config: AppConfig = Depends(get_config),
+) -> MemoryStatusResponse:
     """Get the memory system status including configuration and data.
 
     Returns:
         Combined memory configuration and current data.
     """
-    config = get_memory_config()
+    config = app_config.memory
-    memory_data = get_memory_data(user_id=get_effective_user_id())
+    memory_data = get_memory_data(config, user_id=get_effective_user_id())
 
     return MemoryStatusResponse(
         config=MemoryConfigResponse(

backend/app/gateway/routers/runs.py

@@ -123,8 +123,7 @@ async def run_messages(
     run = await _resolve_run(run_id, request)
     event_store = get_run_event_store(request)
     rows = await event_store.list_messages_by_run(
-        run["thread_id"],
+        run["thread_id"], run_id,
-        run_id,
         limit=limit + 1,
         before_seq=before_seq,
         after_seq=after_seq,

backend/app/gateway/routers/skills.py

@@ -1,20 +1,32 @@
+import errno
 import json
 import logging
+import shutil
 from pathlib import Path
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Request
 from pydantic import BaseModel, Field
 
 from app.gateway.deps import get_config
 from app.gateway.path_utils import resolve_thread_virtual_path
 from deerflow.agents.lead_agent.prompt import refresh_skills_system_prompt_cache_async
 from deerflow.config.app_config import AppConfig
-from deerflow.config.extensions_config import ExtensionsConfig, SkillStateConfig, get_extensions_config, reload_extensions_config
+from deerflow.config.extensions_config import ExtensionsConfig
-from deerflow.skills import Skill
+from deerflow.skills import Skill, load_skills
-from deerflow.skills.installer import SkillAlreadyExistsError
+from deerflow.skills.installer import SkillAlreadyExistsError, install_skill_from_archive
+from deerflow.skills.manager import (
+    append_history,
+    atomic_write,
+    custom_skill_exists,
+    ensure_custom_skill_is_editable,
+    get_custom_skill_dir,
+    get_custom_skill_file,
+    get_skill_history_file,
+    read_custom_skill_content,
+    read_history,
+    validate_skill_markdown_content,
+)
 from deerflow.skills.security_scanner import scan_skill_content
-from deerflow.skills.storage import get_or_new_skill_storage
-from deerflow.skills.types import SKILL_MD_FILE, SkillCategory
 
 logger = logging.getLogger(__name__)
 
@@ -27,7 +39,7 @@ class SkillResponse(BaseModel):
     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: SkillCategory = Field(..., description="Category of the skill (public or custom)")
+    category: str = Field(..., description="Category of the skill (public or custom)")
     enabled: bool = Field(default=True, description="Whether this skill is enabled")
 
 
@@ -91,9 +103,9 @@ def _skill_to_response(skill: Skill) -> SkillResponse:
     summary="List All Skills",
     description="Retrieve a list of all available skills from both public and custom directories.",
 )
-async def list_skills(config: AppConfig = Depends(get_config)) -> SkillsListResponse:
+async def list_skills(app_config: AppConfig = Depends(get_config)) -> SkillsListResponse:
     try:
-        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skills = load_skills(app_config, 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)
@@ -106,11 +118,11 @@ async def list_skills(config: AppConfig = Depends(get_config)) -> SkillsListResp
     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, config: AppConfig = Depends(get_config)) -> SkillInstallResponse:
+async def install_skill(request: SkillInstallRequest, app_config: AppConfig = Depends(get_config)) -> SkillInstallResponse:
     try:
         skill_file_path = resolve_thread_virtual_path(request.thread_id, request.path)
-        result = await get_or_new_skill_storage(app_config=config).ainstall_skill_from_archive(skill_file_path)
+        result = install_skill_from_archive(skill_file_path)
-        await refresh_skills_system_prompt_cache_async()
+        await refresh_skills_system_prompt_cache_async(app_config)
         return SkillInstallResponse(**result)
     except FileNotFoundError as e:
         raise HTTPException(status_code=404, detail=str(e))
@@ -126,9 +138,9 @@ async def install_skill(request: SkillInstallRequest, config: AppConfig = Depend
 
 
 @router.get("/skills/custom", response_model=SkillsListResponse, summary="List Custom Skills")
-async def list_custom_skills(config: AppConfig = Depends(get_config)) -> SkillsListResponse:
+async def list_custom_skills(app_config: AppConfig = Depends(get_config)) -> SkillsListResponse:
     try:
-        skills = [skill for skill in get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False) if skill.category == SkillCategory.CUSTOM]
+        skills = [skill for skill in load_skills(app_config, enabled_only=False) if skill.category == "custom"]
         return SkillsListResponse(skills=[_skill_to_response(skill) for skill in skills])
     except Exception as e:
         logger.error("Failed to list custom skills: %s", e, exc_info=True)
@@ -136,14 +148,13 @@ async def list_custom_skills(config: AppConfig = Depends(get_config)) -> SkillsL
 
 
 @router.get("/skills/custom/{skill_name}", response_model=CustomSkillContentResponse, summary="Get Custom Skill Content")
-async def get_custom_skill(skill_name: str, config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
+async def get_custom_skill(skill_name: str, app_config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
     try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        skills = load_skills(app_config, enabled_only=False)
-        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skill = next((s for s in skills if s.name == skill_name and s.category == "custom"), None)
-        skill = next((s for s in skills if s.name == skill_name and s.category == SkillCategory.CUSTOM), None)
         if skill is None:
             raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
-        return CustomSkillContentResponse(**_skill_to_response(skill).model_dump(), content=get_or_new_skill_storage(app_config=config).read_custom_skill(skill_name))
+        return CustomSkillContentResponse(**_skill_to_response(skill).model_dump(), content=read_custom_skill_content(skill_name, app_config))
     except HTTPException:
         raise
     except Exception as e:
@@ -152,31 +163,35 @@ async def get_custom_skill(skill_name: str, config: AppConfig = Depends(get_conf
 
 
 @router.put("/skills/custom/{skill_name}", response_model=CustomSkillContentResponse, summary="Edit Custom Skill")
-async def update_custom_skill(skill_name: str, request: CustomSkillUpdateRequest, config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
+async def update_custom_skill(
+    skill_name: str,
+    request: CustomSkillUpdateRequest,
+    app_config: AppConfig = Depends(get_config),
+) -> CustomSkillContentResponse:
     try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        ensure_custom_skill_is_editable(skill_name, app_config)
-        storage = get_or_new_skill_storage(app_config=config)
+        validate_skill_markdown_content(skill_name, request.content)
-        storage.ensure_custom_skill_is_editable(skill_name)
+        scan = await scan_skill_content(app_config, request.content, executable=False, location=f"{skill_name}/SKILL.md")
-        storage.validate_skill_markdown_content(skill_name, request.content)
-        scan = await scan_skill_content(request.content, executable=False, location=f"{skill_name}/{SKILL_MD_FILE}", app_config=config)
         if scan.decision == "block":
             raise HTTPException(status_code=400, detail=f"Security scan blocked the edit: {scan.reason}")
-        prev_content = storage.read_custom_skill(skill_name)
+        skill_file = get_custom_skill_dir(skill_name, app_config) / "SKILL.md"
-        storage.write_custom_skill(skill_name, SKILL_MD_FILE, request.content)
+        prev_content = skill_file.read_text(encoding="utf-8")
-        storage.append_history(
+        atomic_write(skill_file, request.content)
+        append_history(
             skill_name,
             {
                 "action": "human_edit",
                 "author": "human",
                 "thread_id": None,
-                "file_path": SKILL_MD_FILE,
+                "file_path": "SKILL.md",
                 "prev_content": prev_content,
                 "new_content": request.content,
                 "scanner": {"decision": scan.decision, "reason": scan.reason},
             },
+            app_config,
         )
-        await refresh_skills_system_prompt_cache_async()
+        await refresh_skills_system_prompt_cache_async(app_config)
-        return await get_custom_skill(skill_name, config)
+        return await get_custom_skill(skill_name, app_config)
     except HTTPException:
         raise
     except FileNotFoundError as e:
@@ -189,23 +204,31 @@ async def update_custom_skill(skill_name: str, request: CustomSkillUpdateRequest
 
 
 @router.delete("/skills/custom/{skill_name}", summary="Delete Custom Skill")
-async def delete_custom_skill(skill_name: str, config: AppConfig = Depends(get_config)) -> dict[str, bool]:
+async def delete_custom_skill(skill_name: str, app_config: AppConfig = Depends(get_config)) -> dict[str, bool]:
     try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        ensure_custom_skill_is_editable(skill_name, app_config)
-        storage = get_or_new_skill_storage(app_config=config)
+        skill_dir = get_custom_skill_dir(skill_name, app_config)
-        storage.delete_custom_skill(
+        prev_content = read_custom_skill_content(skill_name, app_config)
-            skill_name,
+        try:
-            history_meta={
+            append_history(
-                "action": "human_delete",
+                skill_name,
-                "author": "human",
+                {
-                "thread_id": None,
+                    "action": "human_delete",
-                "file_path": SKILL_MD_FILE,
+                    "author": "human",
-                "prev_content": None,
+                    "thread_id": None,
-                "new_content": None,
+                    "file_path": "SKILL.md",
-                "scanner": {"decision": "allow", "reason": "Deletion requested."},
+                    "prev_content": prev_content,
-            },
+                    "new_content": None,
-        )
+                    "scanner": {"decision": "allow", "reason": "Deletion requested."},
-        await refresh_skills_system_prompt_cache_async()
+                },
+                app_config,
+            )
+        except OSError as e:
+            if not isinstance(e, PermissionError) and e.errno not in {errno.EACCES, errno.EPERM, errno.EROFS}:
+                raise
+            logger.warning("Skipping delete history write for custom skill %s due to readonly/permission failure; continuing with skill directory removal: %s", skill_name, e)
+        shutil.rmtree(skill_dir)
+        await refresh_skills_system_prompt_cache_async(app_config)
         return {"success": True}
     except FileNotFoundError as e:
         raise HTTPException(status_code=404, detail=str(e))
@@ -217,13 +240,11 @@ async def delete_custom_skill(skill_name: str, config: AppConfig = Depends(get_c
 
 
 @router.get("/skills/custom/{skill_name}/history", response_model=CustomSkillHistoryResponse, summary="Get Custom Skill History")
-async def get_custom_skill_history(skill_name: str, config: AppConfig = Depends(get_config)) -> CustomSkillHistoryResponse:
+async def get_custom_skill_history(skill_name: str, app_config: AppConfig = Depends(get_config)) -> CustomSkillHistoryResponse:
     try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        if not custom_skill_exists(skill_name, app_config) and not get_skill_history_file(skill_name, app_config).exists():
-        storage = get_or_new_skill_storage(app_config=config)
-        if not storage.custom_skill_exists(skill_name) and not storage.get_skill_history_file(skill_name).exists():
             raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
-        return CustomSkillHistoryResponse(history=storage.read_history(skill_name))
+        return CustomSkillHistoryResponse(history=read_history(skill_name, app_config))
     except HTTPException:
         raise
     except Exception as e:
@@ -232,39 +253,42 @@ async def get_custom_skill_history(skill_name: str, config: AppConfig = Depends(
 
 
 @router.post("/skills/custom/{skill_name}/rollback", response_model=CustomSkillContentResponse, summary="Rollback Custom Skill")
-async def rollback_custom_skill(skill_name: str, request: SkillRollbackRequest, config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
+async def rollback_custom_skill(
+    skill_name: str,
+    request: SkillRollbackRequest,
+    app_config: AppConfig = Depends(get_config),
+) -> CustomSkillContentResponse:
     try:
-        storage = get_or_new_skill_storage(app_config=config)
+        if not custom_skill_exists(skill_name, app_config) and not get_skill_history_file(skill_name, app_config).exists():
-        if not storage.custom_skill_exists(skill_name) and not storage.get_skill_history_file(skill_name).exists():
             raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
-        history = storage.read_history(skill_name)
+        history = read_history(skill_name, app_config)
         if not history:
             raise HTTPException(status_code=400, detail=f"Custom skill '{skill_name}' has no history")
         record = history[request.history_index]
         target_content = record.get("prev_content")
         if target_content is None:
             raise HTTPException(status_code=400, detail="Selected history entry has no previous content to roll back to")
-        storage.validate_skill_markdown_content(skill_name, target_content)
+        validate_skill_markdown_content(skill_name, target_content)
-        scan = await scan_skill_content(target_content, executable=False, location=f"{skill_name}/{SKILL_MD_FILE}", app_config=config)
+        scan = await scan_skill_content(app_config, target_content, executable=False, location=f"{skill_name}/SKILL.md")
-        skill_file = storage.get_custom_skill_file(skill_name)
+        skill_file = get_custom_skill_file(skill_name, app_config)
         current_content = skill_file.read_text(encoding="utf-8") if skill_file.exists() else None
         history_entry = {
             "action": "rollback",
             "author": "human",
             "thread_id": None,
-            "file_path": SKILL_MD_FILE,
+            "file_path": "SKILL.md",
             "prev_content": current_content,
             "new_content": target_content,
             "rollback_from_ts": record.get("ts"),
             "scanner": {"decision": scan.decision, "reason": scan.reason},
         }
         if scan.decision == "block":
-            storage.append_history(skill_name, history_entry)
+            append_history(skill_name, history_entry, app_config)
             raise HTTPException(status_code=400, detail=f"Rollback blocked by security scanner: {scan.reason}")
-        storage.write_custom_skill(skill_name, SKILL_MD_FILE, target_content)
+        atomic_write(skill_file, target_content)
-        storage.append_history(skill_name, history_entry)
+        append_history(skill_name, history_entry, app_config)
-        await refresh_skills_system_prompt_cache_async()
+        await refresh_skills_system_prompt_cache_async(app_config)
-        return await get_custom_skill(skill_name, config)
+        return await get_custom_skill(skill_name, app_config)
     except HTTPException:
         raise
     except IndexError:
@@ -284,10 +308,9 @@ async def rollback_custom_skill(skill_name: str, request: SkillRollbackRequest,
     summary="Get Skill Details",
     description="Retrieve detailed information about a specific skill by its name.",
 )
-async def get_skill(skill_name: str, config: AppConfig = Depends(get_config)) -> SkillResponse:
+async def get_skill(skill_name: str, app_config: AppConfig = Depends(get_config)) -> SkillResponse:
     try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        skills = load_skills(app_config, enabled_only=False)
-        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
         skill = next((s for s in skills if s.name == skill_name), None)
 
         if skill is None:
@@ -307,10 +330,14 @@ async def get_skill(skill_name: str, config: AppConfig = Depends(get_config)) ->
     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, config: AppConfig = Depends(get_config)) -> SkillResponse:
+async def update_skill(
+    skill_name: str,
+    request: SkillUpdateRequest,
+    http_request: Request,
+    app_config: AppConfig = Depends(get_config),
+) -> SkillResponse:
     try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        skills = load_skills(app_config, enabled_only=False)
-        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
         skill = next((s for s in skills if s.name == skill_name), None)
 
         if skill is None:
@@ -321,22 +348,29 @@ async def update_skill(skill_name: str, request: SkillUpdateRequest, config: App
             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()
+        # Do not mutate the frozen AppConfig in place. Compose the new skills
-        extensions_config.skills[skill_name] = SkillStateConfig(enabled=request.enabled)
+        # state in a fresh dict, write to disk, and reload AppConfig below so
+        # every subsequent Depends(get_config) sees the refreshed snapshot.
+        ext = app_config.extensions
+        updated_skills = {name: {"enabled": skill_config.enabled} for name, skill_config in ext.skills.items()}
+        updated_skills[skill_name] = {"enabled": request.enabled}
 
         config_data = {
-            "mcpServers": {name: server.model_dump() for name, server in extensions_config.mcp_servers.items()},
+            "mcpServers": {name: server.model_dump() for name, server in ext.mcp_servers.items()},
-            "skills": {name: {"enabled": skill_config.enabled} for name, skill_config in extensions_config.skills.items()},
+            "skills": updated_skills,
         }
 
         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()
+        # Reload AppConfig and swap ``app.state.config`` so subsequent
-        await refresh_skills_system_prompt_cache_async()
+        # ``Depends(get_config)`` sees the refreshed value.
+        reloaded = AppConfig.from_file()
+        http_request.app.state.config = reloaded
+        await refresh_skills_system_prompt_cache_async(reloaded)
 
-        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skills = load_skills(reloaded, enabled_only=False)
         updated_skill = next((s for s in skills if s.name == skill_name), None)
 
         if updated_skill is None:

backend/app/gateway/routers/suggestions.py

@@ -102,12 +102,7 @@ def _format_conversation(messages: list[SuggestionMessage]) -> str:
     description="Generate short follow-up questions a user might ask next, based on recent conversation context.",
 )
 @require_permission("threads", "read", owner_check=True)
-async def generate_suggestions(
+async def generate_suggestions(thread_id: str, body: SuggestionsRequest, request: Request, app_config: AppConfig = Depends(get_config)) -> SuggestionsResponse:
-    thread_id: str,
-    body: SuggestionsRequest,
-    request: Request,
-    config: AppConfig = Depends(get_config),
-) -> SuggestionsResponse:
     if not body.messages:
         return SuggestionsResponse(suggestions=[])
 
@@ -129,7 +124,7 @@ async def generate_suggestions(
     user_content = f"Conversation Context:\n{conversation}\n\nGenerate {n} follow-up questions"
 
     try:
-        model = create_chat_model(name=body.model_name, thinking_enabled=False, app_config=config)
+        model = create_chat_model(name=body.model_name, thinking_enabled=False, app_config=app_config)
         response = await model.ainvoke([SystemMessage(content=system_instruction), HumanMessage(content=user_content)], config={"run_name": "suggest_agent"})
         raw = _extract_response_text(response.content)
         suggestions = _parse_json_string_list(raw) or []

backend/app/gateway/routers/thread_runs.py

@@ -54,6 +54,7 @@ class RunCreateRequest(BaseModel):
     after_seconds: float | None = Field(default=None, description="Delayed execution")
     if_not_exists: Literal["reject", "create"] = Field(default="create", description="Thread creation policy")
     feedback_keys: list[str] | None = Field(default=None, description="LangSmith feedback keys")
+    follow_up_to_run_id: str | None = Field(default=None, description="Run ID this message follows up on. Auto-detected from latest successful run if not provided.")
 
 
 class RunResponse(BaseModel):
@@ -68,27 +69,6 @@ class RunResponse(BaseModel):
     updated_at: str = ""
 
 
-class ThreadTokenUsageModelBreakdown(BaseModel):
-    tokens: int = 0
-    runs: int = 0
-
-
-class ThreadTokenUsageCallerBreakdown(BaseModel):
-    lead_agent: int = 0
-    subagent: int = 0
-    middleware: int = 0
-
-
-class ThreadTokenUsageResponse(BaseModel):
-    thread_id: str
-    total_tokens: int = 0
-    total_input_tokens: int = 0
-    total_output_tokens: int = 0
-    total_runs: int = 0
-    by_model: dict[str, ThreadTokenUsageModelBreakdown] = Field(default_factory=dict)
-    by_caller: ThreadTokenUsageCallerBreakdown = Field(default_factory=ThreadTokenUsageCallerBreakdown)
-
-
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
@@ -332,15 +312,11 @@ async def list_thread_messages(
         if i in last_ai_indices:
             run_id = msg["run_id"]
             fb = feedback_map.get(run_id)
-            msg["feedback"] = (
+            msg["feedback"] = {
-                {
+                "feedback_id": fb["feedback_id"],
-                    "feedback_id": fb["feedback_id"],
+                "rating": fb["rating"],
-                    "rating": fb["rating"],
+                "comment": fb.get("comment"),
-                    "comment": fb.get("comment"),
+            } if fb else None
-                }
-                if fb
-                else None
-            )
         else:
             msg["feedback"] = None
 
@@ -363,8 +339,7 @@ async def list_run_messages(
     """
     event_store = get_run_event_store(request)
     rows = await event_store.list_messages_by_run(
-        thread_id,
+        thread_id, run_id,
-        run_id,
         limit=limit + 1,
         before_seq=before_seq,
         after_seq=after_seq,
@@ -389,10 +364,10 @@ async def list_run_events(
     return await event_store.list_events(thread_id, run_id, event_types=types, limit=limit)
 
 
-@router.get("/{thread_id}/token-usage", response_model=ThreadTokenUsageResponse)
+@router.get("/{thread_id}/token-usage")
 @require_permission("threads", "read", owner_check=True)
-async def thread_token_usage(thread_id: str, request: Request) -> ThreadTokenUsageResponse:
+async def thread_token_usage(thread_id: str, request: Request) -> dict:
     """Thread-level token usage aggregation."""
     run_store = get_run_store(request)
     agg = await run_store.aggregate_tokens_by_thread(thread_id)
-    return ThreadTokenUsageResponse(thread_id=thread_id, **agg)
+    return {"thread_id": thread_id, **agg}

backend/app/gateway/routers/threads.py

@@ -13,11 +13,12 @@ matching the LangGraph Platform wire format expected by the
 from __future__ import annotations
 
 import logging
+import re
+import time
 import uuid
 from typing import Any
 
 from fastapi import APIRouter, HTTPException, Request
-from langgraph.checkpoint.base import empty_checkpoint
 from pydantic import BaseModel, Field, field_validator
 
 from app.gateway.authz import require_permission
@@ -26,7 +27,6 @@ from app.gateway.utils import sanitize_log_param
 from deerflow.config.paths import Paths, get_paths
 from deerflow.runtime import serialize_channel_values
 from deerflow.runtime.user_context import get_effective_user_id
-from deerflow.utils.time import coerce_iso, now_iso
 
 logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api/threads", tags=["threads"])
@@ -234,7 +234,7 @@ async def create_thread(body: ThreadCreateRequest, request: Request) -> ThreadRe
     checkpointer = get_checkpointer(request)
     thread_store = get_thread_store(request)
     thread_id = body.thread_id or str(uuid.uuid4())
-    now = now_iso()
+    now = time.time()
     # ``body.metadata`` is already stripped of server-reserved keys by
     # ``ThreadCreateRequest._strip_reserved`` — see the model definition.
 
@@ -244,8 +244,8 @@ async def create_thread(body: ThreadCreateRequest, request: Request) -> ThreadRe
         return ThreadResponse(
             thread_id=thread_id,
             status=existing_record.get("status", "idle"),
-            created_at=coerce_iso(existing_record.get("created_at", "")),
+            created_at=str(existing_record.get("created_at", "")),
-            updated_at=coerce_iso(existing_record.get("updated_at", "")),
+            updated_at=str(existing_record.get("updated_at", "")),
             metadata=existing_record.get("metadata", {}),
         )
 
@@ -263,6 +263,8 @@ async def create_thread(body: ThreadCreateRequest, request: Request) -> ThreadRe
     # 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",
@@ -280,8 +282,8 @@ async def create_thread(body: ThreadCreateRequest, request: Request) -> ThreadRe
     return ThreadResponse(
         thread_id=thread_id,
         status="idle",
-        created_at=now,
+        created_at=str(now),
-        updated_at=now,
+        updated_at=str(now),
         metadata=body.metadata,
     )
 
@@ -306,11 +308,8 @@ async def search_threads(body: ThreadSearchRequest, request: Request) -> list[Th
         ThreadResponse(
             thread_id=r["thread_id"],
             status=r.get("status", "idle"),
-            # ``coerce_iso`` heals legacy unix-second values that
+            created_at=r.get("created_at", ""),
-            # ``MemoryThreadMetaStore`` historically wrote with ``time.time()``;
+            updated_at=r.get("updated_at", ""),
-            # SQL-backed rows already arrive as ISO strings and pass through.
-            created_at=coerce_iso(r.get("created_at", "")),
-            updated_at=coerce_iso(r.get("updated_at", "")),
             metadata=r.get("metadata", {}),
             values={"title": r["display_name"]} if r.get("display_name") else {},
             interrupts={},
@@ -342,8 +341,8 @@ async def patch_thread(thread_id: str, body: ThreadPatchRequest, request: Reques
     return ThreadResponse(
         thread_id=thread_id,
         status=record.get("status", "idle"),
-        created_at=coerce_iso(record.get("created_at", "")),
+        created_at=str(record.get("created_at", "")),
-        updated_at=coerce_iso(record.get("updated_at", "")),
+        updated_at=str(record.get("updated_at", "")),
         metadata=record.get("metadata", {}),
     )
 
@@ -383,8 +382,8 @@ async def get_thread(thread_id: str, request: Request) -> ThreadResponse:
         record = {
             "thread_id": thread_id,
             "status": "idle",
-            "created_at": coerce_iso(ckpt_meta.get("created_at", "")),
+            "created_at": ckpt_meta.get("created_at", ""),
-            "updated_at": coerce_iso(ckpt_meta.get("updated_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")},
         }
 
@@ -398,8 +397,8 @@ async def get_thread(thread_id: str, request: Request) -> ThreadResponse:
     return ThreadResponse(
         thread_id=thread_id,
         status=status,
-        created_at=coerce_iso(record.get("created_at", "")),
+        created_at=str(record.get("created_at", "")),
-        updated_at=coerce_iso(record.get("updated_at", "")),
+        updated_at=str(record.get("updated_at", "")),
         metadata=record.get("metadata", {}),
         values=serialize_channel_values(channel_values),
     )
@@ -450,10 +449,10 @@ async def get_thread_state(thread_id: str, request: Request) -> ThreadStateRespo
         values=values,
         next=next_tasks,
         metadata=metadata,
-        checkpoint={"id": checkpoint_id, "ts": coerce_iso(metadata.get("created_at", ""))},
+        checkpoint={"id": checkpoint_id, "ts": str(metadata.get("created_at", ""))},
         checkpoint_id=checkpoint_id,
         parent_checkpoint_id=parent_checkpoint_id,
-        created_at=coerce_iso(metadata.get("created_at", "")),
+        created_at=str(metadata.get("created_at", "")),
         tasks=tasks,
     )
 
@@ -503,7 +502,7 @@ async def update_thread_state(thread_id: str, body: ThreadStateUpdateRequest, re
         channel_values.update(body.values)
 
     checkpoint["channel_values"] = channel_values
-    metadata["updated_at"] = now_iso()
+    metadata["updated_at"] = time.time()
 
     if body.as_node:
         metadata["source"] = "update"
@@ -544,7 +543,7 @@ async def update_thread_state(thread_id: str, body: ThreadStateUpdateRequest, re
         next=[],
         metadata=metadata,
         checkpoint_id=new_checkpoint_id,
-        created_at=coerce_iso(metadata.get("created_at", "")),
+        created_at=str(metadata.get("created_at", "")),
     )
 
 
@@ -611,7 +610,7 @@ async def get_thread_history(thread_id: str, body: ThreadHistoryRequest, request
                     parent_checkpoint_id=parent_id,
                     metadata=user_meta,
                     values=values,
-                    created_at=coerce_iso(metadata.get("created_at", "")),
+                    created_at=str(metadata.get("created_at", "")),
                     next=next_tasks,
                 )
             )

backend/app/gateway/routers/uploads.py

@@ -5,7 +5,7 @@ import os
 import stat
 
 from fastapi import APIRouter, Depends, File, HTTPException, Request, UploadFile
-from pydantic import BaseModel, Field
+from pydantic import BaseModel
 
 from app.gateway.authz import require_permission
 from app.gateway.deps import get_config
@@ -15,15 +15,12 @@ from deerflow.runtime.user_context import get_effective_user_id
 from deerflow.sandbox.sandbox_provider import SandboxProvider, get_sandbox_provider
 from deerflow.uploads.manager import (
     PathTraversalError,
-    UnsafeUploadPathError,
-    claim_unique_filename,
     delete_file_safe,
     enrich_file_listing,
     ensure_uploads_dir,
     get_uploads_dir,
     list_files_in_dir,
     normalize_filename,
-    open_upload_file_no_symlink,
     upload_artifact_url,
     upload_virtual_path,
 )
@@ -33,11 +30,6 @@ logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/api/threads/{thread_id}/uploads", tags=["uploads"])
 
-UPLOAD_CHUNK_SIZE = 8192
-DEFAULT_MAX_FILES = 10
-DEFAULT_MAX_FILE_SIZE = 50 * 1024 * 1024
-DEFAULT_MAX_TOTAL_SIZE = 100 * 1024 * 1024
-
 
 class UploadResponse(BaseModel):
     """Response model for file upload."""
@@ -45,15 +37,6 @@ class UploadResponse(BaseModel):
     success: bool
     files: list[dict[str, str]]
     message: str
-    skipped_files: list[str] = Field(default_factory=list)
-
-
-class UploadLimits(BaseModel):
-    """Application-level upload limits exposed to clients."""
-
-    max_files: int
-    max_file_size: int
-    max_total_size: int
 
 
 def _make_file_sandbox_writable(file_path: os.PathLike[str] | str) -> None:
@@ -86,72 +69,6 @@ def _get_uploads_config_value(app_config: AppConfig, key: str, default: object)
     return getattr(uploads_cfg, key, default)
 
 
-def _get_upload_limit(app_config: AppConfig, key: str, default: int, *, legacy_key: str | None = None) -> int:
-    try:
-        value = _get_uploads_config_value(app_config, key, None)
-        if value is None and legacy_key is not None:
-            value = _get_uploads_config_value(app_config, legacy_key, None)
-        if value is None:
-            value = default
-        limit = int(value)
-        if limit <= 0:
-            raise ValueError
-        return limit
-    except Exception:
-        logger.warning("Invalid uploads.%s value; falling back to %d", key, default)
-        return default
-
-
-def _get_upload_limits(app_config: AppConfig) -> UploadLimits:
-    return UploadLimits(
-        max_files=_get_upload_limit(app_config, "max_files", DEFAULT_MAX_FILES, legacy_key="max_file_count"),
-        max_file_size=_get_upload_limit(app_config, "max_file_size", DEFAULT_MAX_FILE_SIZE, legacy_key="max_single_file_size"),
-        max_total_size=_get_upload_limit(app_config, "max_total_size", DEFAULT_MAX_TOTAL_SIZE),
-    )
-
-
-def _cleanup_uploaded_paths(paths: list[os.PathLike[str] | str]) -> None:
-    for path in reversed(paths):
-        try:
-            os.unlink(path)
-        except FileNotFoundError:
-            pass
-        except Exception:
-            logger.warning("Failed to clean up upload path after rejected request: %s", path, exc_info=True)
-
-
-async def _write_upload_file_with_limits(
-    file: UploadFile,
-    *,
-    uploads_dir: os.PathLike[str] | str,
-    display_filename: str,
-    max_single_file_size: int,
-    max_total_size: int,
-    total_size: int,
-) -> tuple[os.PathLike[str] | str, int, int]:
-    file_size = 0
-    file_path, fh = open_upload_file_no_symlink(uploads_dir, display_filename)
-    try:
-        while chunk := await file.read(UPLOAD_CHUNK_SIZE):
-            file_size += len(chunk)
-            total_size += len(chunk)
-            if file_size > max_single_file_size:
-                raise HTTPException(status_code=413, detail=f"File too large: {display_filename}")
-            if total_size > max_total_size:
-                raise HTTPException(status_code=413, detail="Total upload size too large")
-            fh.write(chunk)
-    except Exception:
-        fh.close()
-        try:
-            os.unlink(file_path)
-        except FileNotFoundError:
-            pass
-        raise
-    else:
-        fh.close()
-    return file_path, file_size, total_size
-
-
 def _auto_convert_documents_enabled(app_config: AppConfig) -> bool:
     """Return whether automatic host-side document conversion is enabled.
 
@@ -168,94 +85,72 @@ def _auto_convert_documents_enabled(app_config: AppConfig) -> bool:
 
 
 @router.post("", response_model=UploadResponse)
-@require_permission("threads", "write", owner_check=True, require_existing=False)
+@require_permission("threads", "write", owner_check=True, require_existing=True)
 async def upload_files(
     thread_id: str,
     request: Request,
     files: list[UploadFile] = File(...),
-    config: AppConfig = Depends(get_config),
+    app_config: AppConfig = Depends(get_config),
 ) -> UploadResponse:
     """Upload multiple files to a thread's uploads directory."""
     if not files:
         raise HTTPException(status_code=400, detail="No files provided")
 
-    limits = _get_upload_limits(config)
-    if len(files) > limits.max_files:
-        raise HTTPException(status_code=413, detail=f"Too many files: maximum is {limits.max_files}")
-
     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, user_id=get_effective_user_id())
     uploaded_files = []
-    written_paths = []
-    sandbox_sync_targets = []
-    skipped_files = []
-    total_size = 0
-    # Track filenames within this request so duplicate form parts do not
-    # silently truncate each other. Existing uploads keep the historical
-    # overwrite behavior for a single replacement upload.
-    seen_filenames: set[str] = set()
 
-    sandbox_provider = get_sandbox_provider()
+    sandbox_provider = get_sandbox_provider(app_config)
     sync_to_sandbox = not _uses_thread_data_mounts(sandbox_provider)
     sandbox = None
     if sync_to_sandbox:
         sandbox_id = sandbox_provider.acquire(thread_id)
         sandbox = sandbox_provider.get(sandbox_id)
-        if sandbox is None:
+    auto_convert_documents = _auto_convert_documents_enabled(app_config)
-            raise HTTPException(status_code=500, detail="Failed to acquire sandbox")
-    auto_convert_documents = _auto_convert_documents_enabled(config)
 
     for file in files:
         if not file.filename:
             continue
 
         try:
-            original_filename = normalize_filename(file.filename)
+            safe_filename = normalize_filename(file.filename)
-            safe_filename = claim_unique_filename(original_filename, seen_filenames)
         except ValueError:
             logger.warning(f"Skipping file with unsafe filename: {file.filename!r}")
             continue
 
         try:
-            file_path, file_size, total_size = await _write_upload_file_with_limits(
+            content = await file.read()
-                file,
+            file_path = uploads_dir / safe_filename
-                uploads_dir=uploads_dir,
+            file_path.write_bytes(content)
-                display_filename=safe_filename,
-                max_single_file_size=limits.max_file_size,
-                max_total_size=limits.max_total_size,
-                total_size=total_size,
-            )
-            written_paths.append(file_path)
 
             virtual_path = upload_virtual_path(safe_filename)
 
-            if sync_to_sandbox:
+            if sync_to_sandbox and sandbox is not None:
-                sandbox_sync_targets.append((file_path, virtual_path))
+                _make_file_sandbox_writable(file_path)
+                sandbox.update_file(virtual_path, content)
 
             file_info = {
                 "filename": safe_filename,
-                "size": str(file_size),
+                "size": str(len(content)),
                 "path": str(sandbox_uploads / safe_filename),
                 "virtual_path": virtual_path,
                 "artifact_url": upload_artifact_url(thread_id, safe_filename),
             }
-            if safe_filename != original_filename:
-                file_info["original_filename"] = original_filename
 
-            logger.info(f"Saved file: {safe_filename} ({file_size} bytes) to {file_info['path']}")
+            logger.info(f"Saved file: {safe_filename} ({len(content)} bytes) to {file_info['path']}")
 
             file_ext = file_path.suffix.lower()
             if auto_convert_documents and file_ext in CONVERTIBLE_EXTENSIONS:
                 md_path = await convert_file_to_markdown(file_path)
                 if md_path:
-                    written_paths.append(md_path)
                     md_virtual_path = upload_virtual_path(md_path.name)
 
-                    if sync_to_sandbox:
+                    if sync_to_sandbox and sandbox is not None:
-                        sandbox_sync_targets.append((md_path, md_virtual_path))
+                        _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)
@@ -264,46 +159,17 @@ async def upload_files(
 
             uploaded_files.append(file_info)
 
-        except HTTPException as e:
-            _cleanup_uploaded_paths(written_paths)
-            raise e
-        except UnsafeUploadPathError as e:
-            logger.warning("Skipping upload with unsafe destination %s: %s", file.filename, e)
-            skipped_files.append(safe_filename)
-            continue
         except Exception as e:
             logger.error(f"Failed to upload {file.filename}: {e}")
-            _cleanup_uploaded_paths(written_paths)
             raise HTTPException(status_code=500, detail=f"Failed to upload {file.filename}: {str(e)}")
 
-    if sync_to_sandbox:
-        for file_path, virtual_path in sandbox_sync_targets:
-            _make_file_sandbox_writable(file_path)
-            sandbox.update_file(virtual_path, file_path.read_bytes())
-
-    message = f"Successfully uploaded {len(uploaded_files)} file(s)"
-    if skipped_files:
-        message += f"; skipped {len(skipped_files)} unsafe file(s)"
-
     return UploadResponse(
-        success=not skipped_files,
+        success=True,
         files=uploaded_files,
-        message=message,
+        message=f"Successfully uploaded {len(uploaded_files)} file(s)",
-        skipped_files=skipped_files,
     )
 
 
-@router.get("/limits", response_model=UploadLimits)
-@require_permission("threads", "read", owner_check=True)
-async def get_upload_limits(
-    thread_id: str,
-    request: Request,
-    config: AppConfig = Depends(get_config),
-) -> UploadLimits:
-    """Return upload limits used by the gateway for this thread."""
-    return _get_upload_limits(config)
-
-
 @router.get("/list", response_model=dict)
 @require_permission("threads", "read", owner_check=True)
 async def list_uploaded_files(thread_id: str, request: Request) -> dict:

backend/app/gateway/services.py

@@ -8,16 +8,18 @@ frames, and consuming stream bridge events.  Router modules
 from __future__ import annotations
 
 import asyncio
+import dataclasses
 import json
 import logging
 import re
+import time
 from collections.abc import Mapping
 from typing import Any
 
 from fastapi import HTTPException, Request
 from langchain_core.messages import HumanMessage
 
-from app.gateway.deps import get_run_context, get_run_manager, get_stream_bridge
+from app.gateway.deps import get_run_context, get_run_manager, get_run_store, get_stream_bridge
 from app.gateway.utils import sanitize_log_param
 from deerflow.runtime import (
     END_SENTINEL,
@@ -98,62 +100,6 @@ def normalize_input(raw_input: dict[str, Any] | None) -> dict[str, Any]:
 _DEFAULT_ASSISTANT_ID = "lead_agent"
 
 
-# Whitelist of run-context keys that the langgraph-compat layer forwards from
-# ``body.context`` into the run config. ``config["context"]`` exists in
-# LangGraph >=0.6, but these values must be written to both ``configurable``
-# (for legacy ``_get_runtime_config`` consumers) and ``context`` because
-# LangGraph >=1.1.9 no longer makes ``ToolRuntime.context`` fall back to
-# ``configurable`` for consumers like ``setup_agent``.
-_CONTEXT_CONFIGURABLE_KEYS: frozenset[str] = frozenset(
-    {
-        "model_name",
-        "mode",
-        "thinking_enabled",
-        "reasoning_effort",
-        "is_plan_mode",
-        "subagent_enabled",
-        "max_concurrent_subagents",
-        "agent_name",
-        "is_bootstrap",
-    }
-)
-
-
-def merge_run_context_overrides(config: dict[str, Any], context: Mapping[str, Any] | None) -> None:
-    """Merge whitelisted keys from ``body.context`` into both ``config['configurable']``
-    and ``config['context']`` so they are visible to legacy configurable readers and
-    to LangGraph ``ToolRuntime.context`` consumers (e.g. the ``setup_agent`` tool —
-    see issue #2677)."""
-    if not context:
-        return
-    configurable = config.setdefault("configurable", {})
-    runtime_context = config.setdefault("context", {})
-    for key in _CONTEXT_CONFIGURABLE_KEYS:
-        if key in context:
-            if isinstance(configurable, dict):
-                configurable.setdefault(key, context[key])
-            if isinstance(runtime_context, dict):
-                runtime_context.setdefault(key, context[key])
-
-
-def inject_authenticated_user_context(config: dict[str, Any], request: Request) -> None:
-    """Stamp the authenticated user into the run context for background tools.
-
-    Tool execution may happen after the request handler has returned, so tools
-    that persist user-scoped files should not rely only on ambient ContextVars.
-    The value comes from server-side auth state, never from client context.
-    """
-
-    user = getattr(request.state, "user", None)
-    user_id = getattr(user, "id", None)
-    if user_id is None:
-        return
-
-    runtime_context = config.setdefault("context", {})
-    if isinstance(runtime_context, dict):
-        runtime_context["user_id"] = str(user_id)
-
-
 def resolve_agent_factory(assistant_id: str | None):
     """Resolve the agent factory callable from config.
 
@@ -267,6 +213,21 @@ async def start_run(
 
     disconnect = DisconnectMode.cancel if body.on_disconnect == "cancel" else DisconnectMode.continue_
 
+    # Resolve follow_up_to_run_id: explicit from request, or auto-detect from latest successful run
+    follow_up_to_run_id = getattr(body, "follow_up_to_run_id", None)
+    if follow_up_to_run_id is None:
+        run_store = get_run_store(request)
+        try:
+            recent_runs = await run_store.list_by_thread(thread_id, limit=1)
+            if recent_runs and recent_runs[0].get("status") == "success":
+                follow_up_to_run_id = recent_runs[0]["run_id"]
+        except Exception:
+            pass  # Don't block run creation
+
+    # Enrich base context with per-run field
+    if follow_up_to_run_id:
+        run_ctx = dataclasses.replace(run_ctx, follow_up_to_run_id=follow_up_to_run_id)
+
     try:
         record = await run_mgr.create_or_reject(
             thread_id,
@@ -275,6 +236,7 @@ async def start_run(
             metadata=body.metadata or {},
             kwargs={"input": body.input, "config": body.config},
             multitask_strategy=body.multitask_strategy,
+            follow_up_to_run_id=follow_up_to_run_id,
         )
     except ConflictError as exc:
         raise HTTPException(status_code=409, detail=str(exc)) from exc
@@ -301,12 +263,27 @@ async def start_run(
     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 both ``configurable`` and ``context``.
+    # 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.
-    merge_run_context_overrides(config, getattr(body, "context", None))
+    context = getattr(body, "context", None)
-    inject_authenticated_user_context(config, request)
+    if context:
+        _CONTEXT_CONFIGURABLE_KEYS = {
+            "model_name",
+            "mode",
+            "thinking_enabled",
+            "reasoning_effort",
+            "is_plan_mode",
+            "subagent_enabled",
+            "max_concurrent_subagents",
+            "agent_name",
+            "is_bootstrap",
+        }
+        configurable = config.setdefault("configurable", {})
+        for key in _CONTEXT_CONFIGURABLE_KEYS:
+            if key in context:
+                configurable.setdefault(key, context[key])
 
     stream_modes = normalize_stream_modes(body.stream_mode)
 

backend/debug.py

@@ -34,42 +34,50 @@ _LOG_FMT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
 _LOG_DATEFMT = "%Y-%m-%d %H:%M:%S"
 
 
-def _setup_logging(log_level: int = logging.INFO) -> None:
+def _logging_level_from_config(name: str) -> int:
-    """Route logs to ``debug.log`` using *log_level* for the initial root/file setup.
+    """Map ``config.yaml`` ``log_level`` string to a ``logging`` level constant."""
+    mapping = logging.getLevelNamesMapping()
+    return mapping.get((name or "info").strip().upper(), logging.INFO)
 
-    This configures the root logger and the ``debug.log`` file handler so logs do
-    not print on the interactive console. It is idempotent: any pre-existing
-    handlers on the root logger (e.g. installed by ``logging.basicConfig`` in
-    transitively imported modules) are removed so the debug session output only
-    lands in ``debug.log``.
 
-    Note: later config-driven logging adjustments may change named logger
+def _setup_logging(log_level: str) -> None:
-    verbosity without raising the root logger or file-handler thresholds set
+    """Send application logs to ``debug.log`` at *log_level*; do not print them on the console.
-    here, so the eventual contents of ``debug.log`` may not be filtered solely by
+
-    this function's ``log_level`` argument.
+    Idempotent: any pre-existing handlers on the root logger (e.g. installed by
+    ``logging.basicConfig`` in transitively imported modules) are removed so the
+    debug session output only lands in ``debug.log``.
     """
+    level = _logging_level_from_config(log_level)
     root = logging.root
     for h in list(root.handlers):
         root.removeHandler(h)
         h.close()
-    root.setLevel(log_level)
+    root.setLevel(level)
 
     file_handler = logging.FileHandler("debug.log", mode="a", encoding="utf-8")
-    file_handler.setLevel(log_level)
+    file_handler.setLevel(level)
     file_handler.setFormatter(logging.Formatter(_LOG_FMT, datefmt=_LOG_DATEFMT))
     root.addHandler(file_handler)
 
 
+def _update_logging_level(log_level: str) -> None:
+    """Update the root logger and existing handlers to *log_level*."""
+    level = _logging_level_from_config(log_level)
+    root = logging.root
+    root.setLevel(level)
+    for handler in root.handlers:
+        handler.setLevel(level)
+
+
 async def main():
     # Install file logging first so warnings emitted while loading config do not
     # leak onto the interactive terminal via Python's lastResort handler.
-    _setup_logging()
+    _setup_logging("info")
 
     from deerflow.config import get_app_config
-    from deerflow.config.app_config import apply_logging_level
 
     app_config = get_app_config()
-    apply_logging_level(app_config.log_level)
+    _update_logging_level(app_config.log_level)
 
     # Delay the rest of the deerflow imports until *after* logging is installed
     # so that any import-time side effects (e.g. deerflow.agents starts a
@@ -79,9 +87,7 @@ async def main():
     from langgraph.runtime import Runtime
 
     from deerflow.agents import make_lead_agent
-    from deerflow.config.paths import get_paths
     from deerflow.mcp import initialize_mcp_tools
-    from deerflow.runtime.user_context import get_effective_user_id
 
     # Initialize MCP tools at startup
     try:
@@ -115,8 +121,6 @@ async def main():
         print("Tip: `uv sync --group dev` to enable arrow-key & history support")
     print("=" * 50)
 
-    seen_artifacts: set[str] = set()
-
     while True:
         try:
             if session:
@@ -138,22 +142,6 @@ async def main():
                 last_message = result["messages"][-1]
                 print(f"\nAgent: {last_message.content}")
 
-            # Show files presented to the user this turn (new artifacts only)
-            artifacts = result.get("artifacts") or []
-            new_artifacts = [p for p in artifacts if p not in seen_artifacts]
-            if new_artifacts:
-                thread_id = config["configurable"]["thread_id"]
-                user_id = get_effective_user_id()
-                paths = get_paths()
-                print("\n[Presented files]")
-                for virtual in new_artifacts:
-                    try:
-                        physical = paths.resolve_virtual_path(thread_id, virtual, user_id=user_id)
-                        print(f"  - {virtual}\n    → {physical}")
-                    except ValueError as exc:
-                        print(f"  - {virtual}    (failed to resolve physical path: {exc})")
-                seen_artifacts.update(new_artifacts)
-
         except (KeyboardInterrupt, EOFError):
             print("\nGoodbye!")
             break

backend/docs/CONFIGURATION.md

@@ -259,8 +259,6 @@ sandbox:
 
 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`.
 
-For bare-metal Docker sandbox runs that use localhost, DeerFlow binds the sandbox HTTP port to `127.0.0.1` by default so it is not exposed on every host interface. Docker-outside-of-Docker deployments that connect through `host.docker.internal` keep the broad legacy bind for compatibility. Set `DEER_FLOW_SANDBOX_BIND_HOST` explicitly if your deployment needs a different bind address.
-
 ### Skills
 
 Configure the skills directory for specialized workflows:
@@ -321,16 +319,11 @@ models:
 - `DEEPSEEK_API_KEY` - DeepSeek API key
 - `NOVITA_API_KEY` - Novita API key (OpenAI-compatible endpoint)
 - `TAVILY_API_KEY` - Tavily search API key
-- `DEER_FLOW_PROJECT_ROOT` - Project root for relative runtime paths
 - `DEER_FLOW_CONFIG_PATH` - Custom config file path
-- `DEER_FLOW_EXTENSIONS_CONFIG_PATH` - Custom extensions config file path
-- `DEER_FLOW_HOME` - Runtime state directory (defaults to `.deer-flow` under the project root)
-- `DEER_FLOW_SKILLS_PATH` - Skills directory when `skills.path` is omitted
-- `GATEWAY_ENABLE_DOCS` - Set to `false` to disable Swagger UI (`/docs`), ReDoc (`/redoc`), and OpenAPI schema (`/openapi.json`) endpoints (default: `true`)
 
 ## Configuration Location
 
-The configuration file should be placed in the **project root directory** (`deer-flow/config.yaml`). Set `DEER_FLOW_PROJECT_ROOT` when the process may start from another working directory, or set `DEER_FLOW_CONFIG_PATH` to point at a specific file.
+The configuration file should be placed in the **project root directory** (`deer-flow/config.yaml`), not in the backend directory.
 
 ## Configuration Priority
 
@@ -338,12 +331,12 @@ DeerFlow searches for configuration in this order:
 
 1. Path specified in code via `config_path` argument
 2. Path from `DEER_FLOW_CONFIG_PATH` environment variable
-3. `config.yaml` under `DEER_FLOW_PROJECT_ROOT`, or under the current working directory when `DEER_FLOW_PROJECT_ROOT` is unset
+3. `config.yaml` in current working directory (typically `backend/` when running)
-4. Legacy backend/repository-root locations for monorepo compatibility
+4. `config.yaml` in parent directory (project root: `deer-flow/`)
 
 ## Best Practices
 
-1. **Place `config.yaml` in project root** - Set `DEER_FLOW_PROJECT_ROOT` if the runtime starts elsewhere
+1. **Place `config.yaml` in project root** - Not in `backend/` directory
 2. **Never commit `config.yaml`** - It's already in `.gitignore`
 3. **Use environment variables for secrets** - Don't hardcode API keys
 4. **Keep `config.example.yaml` updated** - Document all new options
@@ -354,7 +347,7 @@ DeerFlow searches for configuration in this order:
 
 ### "Config file not found"
 - Ensure `config.yaml` exists in the **project root** directory (`deer-flow/config.yaml`)
-- If the runtime starts outside the project root, set `DEER_FLOW_PROJECT_ROOT`
+- The backend searches parent directory by default, so root location is preferred
 - Alternatively, set `DEER_FLOW_CONFIG_PATH` environment variable to custom location
 
 ### "Invalid API key"
@@ -364,7 +357,7 @@ DeerFlow searches for configuration in this order:
 ### "Skills not loading"
 - Check that `deer-flow/skills/` directory exists
 - Verify skills have valid `SKILL.md` files
-- Check `skills.path` or `DEER_FLOW_SKILLS_PATH` if using a custom path
+- Check `skills.path` configuration if using custom path
 
 ### "Docker sandbox fails to start"
 - Ensure Docker is running

backend/docs/FILE_UPLOAD.md

@@ -22,8 +22,6 @@ POST /api/threads/{thread_id}/uploads
 **请求体：** `multipart/form-data`
 - `files`: 一个或多个文件
 
-网关会在应用层限制上传规模，默认最多 10 个文件、单文件 50 MiB、单次请求总计 100 MiB。可通过 `config.yaml` 的 `uploads.max_files`、`uploads.max_file_size`、`uploads.max_total_size` 调整；前端会读取同一组限制并在选择文件时提示，超过限制时后端返回 `413 Payload Too Large`。
-
 **响应：**
 ```json
 {
@@ -50,23 +48,7 @@ POST /api/threads/{thread_id}/uploads
 - `virtual_path`: Agent 在沙箱中使用的虚拟路径
 - `artifact_url`: 前端通过 HTTP 访问文件的 URL
 
-### 2. 查询上传限制
+### 2. 列出已上传文件
-```
-GET /api/threads/{thread_id}/uploads/limits
-```
-
-返回网关当前生效的上传限制，供前端在用户选择文件前提示和拦截。
-
-**响应：**
-```json
-{
-  "max_files": 10,
-  "max_file_size": 52428800,
-  "max_total_size": 104857600
-}
-```
-
-### 3. 列出已上传文件
 ```
 GET /api/threads/{thread_id}/uploads/list
 ```
@@ -89,7 +71,7 @@ GET /api/threads/{thread_id}/uploads/list
 }
 ```
 
-### 4. 删除文件
+### 3. 删除文件
 ```
 DELETE /api/threads/{thread_id}/uploads/{filename}
 ```

backend/docs/HARNESS_APP_SPLIT.md

@@ -0,0 +1,343 @@
+# 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/SETUP.md

@@ -23,9 +23,6 @@ DeerFlow uses a YAML configuration file that should be placed in the **project r
    # Option A: Set environment variables (recommended)
    export OPENAI_API_KEY="your-key-here"
 
-   # Optional: pin the project root when running from another directory
-   export DEER_FLOW_PROJECT_ROOT="/path/to/deer-flow"
-
    # Option B: Edit config.yaml directly
    vim config.yaml  # or your preferred editor
    ```
@@ -38,20 +35,17 @@ DeerFlow uses a YAML configuration file that should be placed in the **project r
 
 ## Important Notes
 
-- **Location**: `config.yaml` should be in `deer-flow/` (project root)
+- **Location**: `config.yaml` should be in `deer-flow/` (project root), not `deer-flow/backend/`
 - **Git**: `config.yaml` is automatically ignored by git (contains secrets)
-- **Runtime root**: Set `DEER_FLOW_PROJECT_ROOT` if DeerFlow may start from outside the project root
+- **Priority**: If both `backend/config.yaml` and `../config.yaml` exist, backend version takes precedence
-- **Runtime data**: State defaults to `.deer-flow` under the project root; set `DEER_FLOW_HOME` to move it
-- **Skills**: Skills default to `skills/` under the project root; set `DEER_FLOW_SKILLS_PATH` or `skills.path` to move them
 
 ## Configuration File Locations
 
 The backend searches for `config.yaml` in this order:
 
-1. Explicit `config_path` argument from code
+1. `DEER_FLOW_CONFIG_PATH` environment variable (if set)
-2. `DEER_FLOW_CONFIG_PATH` environment variable (if set)
+2. `backend/config.yaml` (current directory when running from backend/)
-3. `config.yaml` under `DEER_FLOW_PROJECT_ROOT`, or the current working directory when `DEER_FLOW_PROJECT_ROOT` is unset
+3. `deer-flow/config.yaml` (parent directory - **recommended location**)
-4. Legacy backend/repository-root locations for monorepo compatibility
 
 **Recommended**: Place `config.yaml` in project root (`deer-flow/config.yaml`).
 
@@ -83,8 +77,8 @@ python -c "from deerflow.config.app_config import AppConfig; print(AppConfig.res
 
 If it can't find the config:
 1. Ensure you've copied `config.example.yaml` to `config.yaml`
-2. Verify you're in the project root, or set `DEER_FLOW_PROJECT_ROOT`
+2. Verify you're in the correct directory
-3. Check the file exists: `ls -la config.yaml`
+3. Check the file exists: `ls -la ../config.yaml`
 
 ### Permission denied
 
@@ -95,4 +89,4 @@ chmod 600 ../config.yaml  # Protect sensitive configuration
 ## See Also
 
 - [Configuration Guide](CONFIGURATION.md) - Detailed configuration options
-- [Architecture Overview](../CLAUDE.md) - System architecture
+- [Architecture Overview](../CLAUDE.md) - System architecture

backend/langgraph.json

@@ -12,6 +12,6 @@
     "path": "./app/gateway/langgraph_auth.py:auth"
   },
   "checkpointer": {
-    "path": "./packages/harness/deerflow/runtime/checkpointer/async_provider.py:make_checkpointer"
+    "path": "./packages/harness/deerflow/agents/checkpointer/async_provider.py:make_checkpointer"
   }
 }

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

@@ -173,7 +173,7 @@ def _assemble_from_features(
       9.   MemoryMiddleware (memory feature)
       10.  ViewImageMiddleware (vision feature)
       11.  SubagentLimitMiddleware (subagent feature)
-      12.  LoopDetectionMiddleware (loop_detection feature)
+      12.  LoopDetectionMiddleware (always)
       13.  ClarificationMiddleware (always last)
 
     Two-phase ordering:
@@ -254,11 +254,9 @@ def _assemble_from_features(
             from deerflow.agents.middlewares.view_image_middleware import ViewImageMiddleware
 
             chain.append(ViewImageMiddleware())
+        from deerflow.tools.builtins import view_image_tool
 
-        if feat.sandbox is not False:
+        extra_tools.append(view_image_tool)
-            from deerflow.tools.builtins import view_image_tool
-
-            extra_tools.append(view_image_tool)
 
     # --- [11] Subagent ---
     if feat.subagent is not False:
@@ -272,15 +270,10 @@ def _assemble_from_features(
 
         extra_tools.append(task_tool)
 
-    # --- [12] LoopDetection ---
+    # --- [12] LoopDetection (always) ---
-    if feat.loop_detection is not False:
+    from deerflow.agents.middlewares.loop_detection_middleware import LoopDetectionMiddleware
-        if isinstance(feat.loop_detection, AgentMiddleware):
-            chain.append(feat.loop_detection)
-        else:
-            from deerflow.agents.middlewares.loop_detection_middleware import LoopDetectionMiddleware
-            from deerflow.config.loop_detection_config import LoopDetectionConfig
 
-            chain.append(LoopDetectionMiddleware.from_config(LoopDetectionConfig()))
+    chain.append(LoopDetectionMiddleware())
 
     # --- [13] Clarification (always last among built-ins) ---
     chain.append(ClarificationMiddleware())

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

@@ -31,7 +31,6 @@ class RuntimeFeatures:
     vision: bool | AgentMiddleware = False
     auto_title: bool | AgentMiddleware = False
     guardrail: Literal[False] | AgentMiddleware = False
-    loop_detection: bool | AgentMiddleware = True
 
 
 # ---------------------------------------------------------------------------

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

@@ -3,6 +3,7 @@ import logging
 from langchain.agents import create_agent
 from langchain.agents.middleware import AgentMiddleware
 from langchain_core.runnables import RunnableConfig
+from langgraph.graph.state import CompiledStateGraph
 
 from deerflow.agents.lead_agent.prompt import apply_prompt_template
 from deerflow.agents.memory.summarization_hook import memory_flush_hook
@@ -18,10 +19,9 @@ from deerflow.agents.middlewares.tool_error_handling_middleware import build_lea
 from deerflow.agents.middlewares.view_image_middleware import ViewImageMiddleware
 from deerflow.agents.thread_state import ThreadState
 from deerflow.config.agents_config import load_agent_config, validate_agent_name
-from deerflow.config.app_config import AppConfig, get_app_config
+from deerflow.config.app_config import AppConfig
+from deerflow.config.deer_flow_context import DeerFlowContext
 from deerflow.models import create_chat_model
-from deerflow.skills.tool_policy import filter_tools_by_skill_allowed_tools
-from deerflow.skills.types import Skill
 
 logger = logging.getLogger(__name__)
 
@@ -35,9 +35,8 @@ def _get_runtime_config(config: RunnableConfig) -> dict:
     return cfg
 
 
-def _resolve_model_name(requested_model_name: str | None = None, *, app_config: AppConfig | None = None) -> str:
+def _resolve_model_name(app_config: AppConfig, requested_model_name: str | None = None) -> str:
     """Resolve a runtime model name safely, falling back to default if invalid. Returns None if no models are configured."""
-    app_config = app_config or get_app_config()
     default_model_name = app_config.models[0].name if app_config.models else None
     if default_model_name is None:
         raise ValueError("No chat models are configured. Please configure at least one model in config.yaml.")
@@ -50,10 +49,9 @@ def _resolve_model_name(requested_model_name: str | None = None, *, app_config:
     return default_model_name
 
 
-def _create_summarization_middleware(*, app_config: AppConfig | None = None) -> DeerFlowSummarizationMiddleware | None:
+def _create_summarization_middleware(app_config: AppConfig) -> DeerFlowSummarizationMiddleware | None:
     """Create and configure the summarization middleware from config."""
-    resolved_app_config = app_config or get_app_config()
+    config = app_config.summarization
-    config = resolved_app_config.summarization
 
     if not config.enabled:
         return None
@@ -74,9 +72,9 @@ def _create_summarization_middleware(*, app_config: AppConfig | None = None) ->
     # as middleware rather than lead_agent (SummarizationMiddleware is a
     # LangChain built-in, so we tag the model at creation time).
     if config.model_name:
-        model = create_chat_model(name=config.model_name, thinking_enabled=False, app_config=resolved_app_config)
+        model = create_chat_model(name=config.model_name, thinking_enabled=False, app_config=app_config)
     else:
-        model = create_chat_model(thinking_enabled=False, app_config=resolved_app_config)
+        model = create_chat_model(thinking_enabled=False, app_config=app_config)
     model = model.with_config(tags=["middleware:summarize"])
 
     # Prepare kwargs
@@ -93,13 +91,17 @@ def _create_summarization_middleware(*, app_config: AppConfig | None = None) ->
         kwargs["summary_prompt"] = config.summary_prompt
 
     hooks: list[BeforeSummarizationHook] = []
-    if resolved_app_config.memory.enabled:
+    if app_config.memory.enabled:
         hooks.append(memory_flush_hook)
 
     # The logic below relies on two assumptions holding true: this factory is
     # the sole entry point for DeerFlowSummarizationMiddleware, and the runtime
     # config is not expected to change after startup.
-    skills_container_path = resolved_app_config.skills.container_path or "/mnt/skills"
+    try:
+        skills_container_path = app_config.skills.container_path or "/mnt/skills"
+    except Exception:
+        logger.exception("Failed to resolve skills container path; falling back to default")
+        skills_container_path = "/mnt/skills"
 
     return DeerFlowSummarizationMiddleware(
         **kwargs,
@@ -238,16 +240,17 @@ Being proactive with task management demonstrates thoroughness and ensures all r
 # ToolErrorHandlingMiddleware should be before ClarificationMiddleware to convert tool exceptions to ToolMessages
 # ClarificationMiddleware should be last to intercept clarification requests after model calls
 def _build_middlewares(
+    app_config: AppConfig,
     config: RunnableConfig,
+    *,
     model_name: str | None,
     agent_name: str | None = None,
     custom_middlewares: list[AgentMiddleware] | None = None,
-    *,
-    app_config: AppConfig | None = None,
 ):
     """Build middleware chain based on runtime configuration.
 
     Args:
+        app_config: Resolved application config.
         config: Runtime configuration containing configurable options like is_plan_mode.
         agent_name: If provided, MemoryMiddleware will use per-agent memory storage.
         custom_middlewares: Optional list of custom middlewares to inject into the chain.
@@ -255,17 +258,10 @@ def _build_middlewares(
     Returns:
         List of middleware instances.
     """
-    resolved_app_config = app_config or get_app_config()
+    middlewares = build_lead_runtime_middlewares(app_config=app_config, lazy_init=True)
-    middlewares = build_lead_runtime_middlewares(app_config=resolved_app_config, lazy_init=True)
-
-    # Always inject current date (and optionally memory) as <system-reminder> into the
-    # first HumanMessage to keep the system prompt fully static for prefix-cache reuse.
-    from deerflow.agents.middlewares.dynamic_context_middleware import DynamicContextMiddleware
-
-    middlewares.append(DynamicContextMiddleware(agent_name=agent_name, app_config=resolved_app_config))
 
     # Add summarization middleware if enabled
-    summarization_middleware = _create_summarization_middleware(app_config=resolved_app_config)
+    summarization_middleware = _create_summarization_middleware(app_config)
     if summarization_middleware is not None:
         middlewares.append(summarization_middleware)
 
@@ -277,23 +273,23 @@ def _build_middlewares(
         middlewares.append(todo_list_middleware)
 
     # Add TokenUsageMiddleware when token_usage tracking is enabled
-    if resolved_app_config.token_usage.enabled:
+    if app_config.token_usage.enabled:
         middlewares.append(TokenUsageMiddleware())
 
     # Add TitleMiddleware
-    middlewares.append(TitleMiddleware(app_config=resolved_app_config))
+    middlewares.append(TitleMiddleware())
 
     # Add MemoryMiddleware (after TitleMiddleware)
-    middlewares.append(MemoryMiddleware(agent_name=agent_name, memory_config=resolved_app_config.memory))
+    middlewares.append(MemoryMiddleware(agent_name=agent_name))
 
     # Add ViewImageMiddleware only if the current model supports vision.
     # Use the resolved runtime model_name from make_lead_agent to avoid stale config values.
-    model_config = resolved_app_config.get_model_config(model_name) if model_name else None
+    model_config = app_config.get_model_config(model_name) if model_name else None
     if model_config is not None and model_config.supports_vision:
         middlewares.append(ViewImageMiddleware())
 
     # Add DeferredToolFilterMiddleware to hide deferred tool schemas from model binding
-    if resolved_app_config.tool_search.enabled:
+    if app_config.tool_search.enabled:
         from deerflow.agents.middlewares.deferred_tool_filter_middleware import DeferredToolFilterMiddleware
 
         middlewares.append(DeferredToolFilterMiddleware())
@@ -305,9 +301,7 @@ def _build_middlewares(
         middlewares.append(SubagentLimitMiddleware(max_concurrent=max_concurrent_subagents))
 
     # LoopDetectionMiddleware — detect and break repetitive tool call loops
-    loop_detection_config = resolved_app_config.loop_detection
+    middlewares.append(LoopDetectionMiddleware())
-    if loop_detection_config.enabled:
-        middlewares.append(LoopDetectionMiddleware.from_config(loop_detection_config))
 
     # Inject custom middlewares before ClarificationMiddleware
     if custom_middlewares:
@@ -318,42 +312,33 @@ def _build_middlewares(
     return middlewares
 
 
-def _available_skill_names(agent_config, is_bootstrap: bool) -> set[str] | None:
+def make_lead_agent(
-    if is_bootstrap:
+    config: RunnableConfig,
-        return {"bootstrap"}
+    app_config: AppConfig | None = None,
-    if agent_config and agent_config.skills is not None:
+) -> CompiledStateGraph:
-        return set(agent_config.skills)
+    """Build the lead agent from runtime config.
-    return None
 
-
+    Args:
-def _load_enabled_skills_for_tool_policy(available_skills: set[str] | None, *, app_config: AppConfig) -> list[Skill]:
+        config: LangGraph ``RunnableConfig`` carrying per-invocation options
-    try:
+            (``thinking_enabled``, ``model_name``, ``is_plan_mode``, etc.).
-        from deerflow.agents.lead_agent.prompt import get_enabled_skills_for_config
+        app_config: Resolved application config. Required for in-process
-
+            entry points (DeerFlowClient, Gateway Worker). When omitted we
-        skills = get_enabled_skills_for_config(app_config)
+            are being called via ``langgraph.json`` registration and reload
-    except Exception:
+            from disk — the LangGraph Server bootstrap path has no other
-        logger.exception("Failed to load skills for allowed-tools policy")
+            way to thread the value.
-        raise
+    """
-
-    if available_skills is None:
-        return skills
-    return [skill for skill in skills if skill.name in available_skills]
-
-
-def make_lead_agent(config: RunnableConfig):
-    """LangGraph graph factory; keep the signature compatible with LangGraph Server."""
-    runtime_config = _get_runtime_config(config)
-    runtime_app_config = runtime_config.get("app_config")
-    return _make_lead_agent(config, app_config=runtime_app_config or get_app_config())
-
-
-def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
     # Lazy import to avoid circular dependency
     from deerflow.tools import get_available_tools
-    from deerflow.tools.builtins import setup_agent, update_agent
+    from deerflow.tools.builtins import setup_agent
+
+    if app_config is None:
+        # LangGraph Server registers ``make_lead_agent`` via ``langgraph.json``
+        # and hands us only a ``RunnableConfig``. Reload config from disk
+        # here — it's a pure function, equivalent to the process-global the
+        # old code path would have read.
+        app_config = AppConfig.from_file()
 
     cfg = _get_runtime_config(config)
-    resolved_app_config = app_config
 
     thinking_enabled = cfg.get("thinking_enabled", True)
     reasoning_effort = cfg.get("reasoning_effort", None)
@@ -365,14 +350,13 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
     agent_name = validate_agent_name(cfg.get("agent_name"))
 
     agent_config = load_agent_config(agent_name) if not is_bootstrap else None
-    available_skills = _available_skill_names(agent_config, is_bootstrap)
     # Custom agent model from agent config (if any), or None to let _resolve_model_name pick the default
     agent_model_name = agent_config.model if agent_config and agent_config.model else None
 
     # Final model name resolution: request → agent config → global default, with fallback for unknown names
-    model_name = _resolve_model_name(requested_model_name or agent_model_name, app_config=resolved_app_config)
+    model_name = _resolve_model_name(app_config, requested_model_name or agent_model_name)
 
-    model_config = resolved_app_config.get_model_config(model_name)
+    model_config = app_config.get_model_config(model_name)
 
     if model_config is None:
         raise ValueError("No chat model could be resolved. Please configure at least one model in config.yaml or provide a valid 'model_name'/'model' in the request.")
@@ -404,43 +388,29 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
             "is_plan_mode": is_plan_mode,
             "subagent_enabled": subagent_enabled,
             "tool_groups": agent_config.tool_groups if agent_config else None,
-            "available_skills": sorted(available_skills) if available_skills is not None else None,
+            "available_skills": ["bootstrap"] if is_bootstrap else (agent_config.skills if agent_config and agent_config.skills is not None else None),
         }
     )
 
-    skills_for_tool_policy = _load_enabled_skills_for_tool_policy(available_skills, app_config=resolved_app_config)
-
     if is_bootstrap:
         # Special bootstrap agent with minimal prompt for initial custom agent creation flow
-        tools = get_available_tools(model_name=model_name, subagent_enabled=subagent_enabled, app_config=resolved_app_config) + [setup_agent]
         return create_agent(
-            model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, app_config=resolved_app_config),
+            model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, app_config=app_config),
-            tools=filter_tools_by_skill_allowed_tools(tools, skills_for_tool_policy),
+            tools=get_available_tools(model_name=model_name, subagent_enabled=subagent_enabled, app_config=app_config) + [setup_agent],
-            middleware=_build_middlewares(config, model_name=model_name, app_config=resolved_app_config),
+            middleware=_build_middlewares(app_config, config, model_name=model_name),
-            system_prompt=apply_prompt_template(
+            system_prompt=apply_prompt_template(app_config, subagent_enabled=subagent_enabled, max_concurrent_subagents=max_concurrent_subagents, available_skills=set(["bootstrap"])),
-                subagent_enabled=subagent_enabled,
-                max_concurrent_subagents=max_concurrent_subagents,
-                available_skills=set(["bootstrap"]),
-                app_config=resolved_app_config,
-            ),
             state_schema=ThreadState,
+            context_schema=DeerFlowContext,
         )
 
-    # Custom agents can update their own SOUL.md / config via update_agent.
-    # The default agent (no agent_name) does not see this tool.
-    extra_tools = [update_agent] if agent_name else []
     # Default lead agent (unchanged behavior)
-    tools = get_available_tools(model_name=model_name, groups=agent_config.tool_groups if agent_config else None, subagent_enabled=subagent_enabled, app_config=resolved_app_config)
     return create_agent(
-        model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, reasoning_effort=reasoning_effort, app_config=resolved_app_config),
+        model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, reasoning_effort=reasoning_effort, app_config=app_config),
-        tools=filter_tools_by_skill_allowed_tools(tools + extra_tools, skills_for_tool_policy),
+        tools=get_available_tools(model_name=model_name, groups=agent_config.tool_groups if agent_config else None, subagent_enabled=subagent_enabled, app_config=app_config),
-        middleware=_build_middlewares(config, model_name=model_name, agent_name=agent_name, app_config=resolved_app_config),
+        middleware=_build_middlewares(app_config, config, model_name=model_name, agent_name=agent_name),
         system_prompt=apply_prompt_template(
-            subagent_enabled=subagent_enabled,
+            app_config, subagent_enabled=subagent_enabled, max_concurrent_subagents=max_concurrent_subagents, agent_name=agent_name, available_skills=set(agent_config.skills) if agent_config and agent_config.skills is not None else None
-            max_concurrent_subagents=max_concurrent_subagents,
-            agent_name=agent_name,
-            available_skills=set(agent_config.skills) if agent_config and agent_config.skills is not None else None,
-            app_config=resolved_app_config,
         ),
         state_schema=ThreadState,
+        context_schema=DeerFlowContext,
     )

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

@@ -1,43 +1,39 @@
-from __future__ import annotations
-
 import asyncio
 import logging
 import threading
+from datetime import datetime
 from functools import lru_cache
-from typing import TYPE_CHECKING
 
 from deerflow.config.agents_config import load_agent_soul
-from deerflow.skills.storage import get_or_new_skill_storage
+from deerflow.config.app_config import AppConfig
-from deerflow.skills.types import Skill, SkillCategory
+from deerflow.skills import load_skills
+from deerflow.skills.types import Skill
 from deerflow.subagents import get_available_subagent_names
 
-if TYPE_CHECKING:
-    from deerflow.config.app_config import AppConfig
-
 logger = logging.getLogger(__name__)
 
 _ENABLED_SKILLS_REFRESH_WAIT_TIMEOUT_SECONDS = 5.0
 _enabled_skills_lock = threading.Lock()
 _enabled_skills_cache: list[Skill] | None = None
-_enabled_skills_by_config_cache: dict[int, tuple[object, list[Skill]]] = {}
 _enabled_skills_refresh_active = False
 _enabled_skills_refresh_version = 0
 _enabled_skills_refresh_event = threading.Event()
 
 
-def _load_enabled_skills_sync() -> list[Skill]:
+def _load_enabled_skills_sync(app_config: AppConfig | None) -> list[Skill]:
-    return list(get_or_new_skill_storage().load_skills(enabled_only=True))
+    return list(load_skills(app_config, enabled_only=True))
 
 
-def _start_enabled_skills_refresh_thread() -> None:
+def _start_enabled_skills_refresh_thread(app_config: AppConfig | None) -> None:
     threading.Thread(
         target=_refresh_enabled_skills_cache_worker,
+        args=(app_config,),
         name="deerflow-enabled-skills-loader",
         daemon=True,
     ).start()
 
 
-def _refresh_enabled_skills_cache_worker() -> None:
+def _refresh_enabled_skills_cache_worker(app_config: AppConfig | None) -> None:
     global _enabled_skills_cache, _enabled_skills_refresh_active
 
     while True:
@@ -45,8 +41,8 @@ def _refresh_enabled_skills_cache_worker() -> None:
             target_version = _enabled_skills_refresh_version
 
         try:
-            skills = _load_enabled_skills_sync()
+            skills = _load_enabled_skills_sync(app_config)
-        except Exception:
+        except (OSError, ImportError):
             logger.exception("Failed to load enabled skills for prompt injection")
             skills = []
 
@@ -62,7 +58,7 @@ def _refresh_enabled_skills_cache_worker() -> None:
             _enabled_skills_cache = None
 
 
-def _ensure_enabled_skills_cache() -> threading.Event:
+def _ensure_enabled_skills_cache(app_config: AppConfig | None) -> threading.Event:
     global _enabled_skills_refresh_active
 
     with _enabled_skills_lock:
@@ -74,94 +70,84 @@ def _ensure_enabled_skills_cache() -> threading.Event:
         _enabled_skills_refresh_active = True
         _enabled_skills_refresh_event.clear()
 
-    _start_enabled_skills_refresh_thread()
+    _start_enabled_skills_refresh_thread(app_config)
     return _enabled_skills_refresh_event
 
 
-def _invalidate_enabled_skills_cache() -> threading.Event:
+def _invalidate_enabled_skills_cache(app_config: AppConfig | None) -> threading.Event:
     global _enabled_skills_cache, _enabled_skills_refresh_active, _enabled_skills_refresh_version
 
     _get_cached_skills_prompt_section.cache_clear()
     with _enabled_skills_lock:
         _enabled_skills_cache = None
-        _enabled_skills_by_config_cache.clear()
         _enabled_skills_refresh_version += 1
         _enabled_skills_refresh_event.clear()
         if _enabled_skills_refresh_active:
             return _enabled_skills_refresh_event
         _enabled_skills_refresh_active = True
 
-    _start_enabled_skills_refresh_thread()
+    _start_enabled_skills_refresh_thread(app_config)
     return _enabled_skills_refresh_event
 
 
-def prime_enabled_skills_cache() -> None:
+def prime_enabled_skills_cache(app_config: AppConfig | None = None) -> None:
-    _ensure_enabled_skills_cache()
+    _ensure_enabled_skills_cache(app_config)
 
 
-def warm_enabled_skills_cache(timeout_seconds: float = _ENABLED_SKILLS_REFRESH_WAIT_TIMEOUT_SECONDS) -> bool:
+def warm_enabled_skills_cache(app_config: AppConfig | None = None, timeout_seconds: float = _ENABLED_SKILLS_REFRESH_WAIT_TIMEOUT_SECONDS) -> bool:
-    if _ensure_enabled_skills_cache().wait(timeout=timeout_seconds):
+    if _ensure_enabled_skills_cache(app_config).wait(timeout=timeout_seconds):
         return True
 
     logger.warning("Timed out waiting %.1fs for enabled skills cache warm-up", timeout_seconds)
     return False
 
 
-def _get_enabled_skills():
+def _get_enabled_skills(app_config: AppConfig | None = None):
-    return get_cached_enabled_skills()
-
-
-def get_cached_enabled_skills() -> list[Skill]:
-    """Return the cached enabled-skills list, kicking off a background refresh on miss.
-
-    Safe to call from request paths: never blocks on disk I/O. Returns an empty
-    list on cache miss; the next call will see the warmed result.
-    """
     with _enabled_skills_lock:
         cached = _enabled_skills_cache
 
     if cached is not None:
         return list(cached)
 
-    _ensure_enabled_skills_cache()
+    _ensure_enabled_skills_cache(app_config)
     return []
 
 
-def get_enabled_skills_for_config(app_config: AppConfig | None = None) -> list[Skill]:
+def _skill_mutability_label(category: str) -> str:
-    """Return enabled skills using the caller's config source.
+    return "[custom, editable]" if category == "custom" else "[built-in]"
 
-    When a concrete ``app_config`` is supplied, cache the loaded skills by that
-    config object's identity so request-scoped config injection still resolves
-    skill paths from the matching config without rescanning storage on every
-    agent factory call.
-    """
-    if app_config is None:
-        return _get_enabled_skills()
 
-    cache_key = id(app_config)
+def clear_skills_system_prompt_cache(app_config: AppConfig | None = None) -> None:
+    _invalidate_enabled_skills_cache(app_config)
+
+
+async def refresh_skills_system_prompt_cache_async(app_config: AppConfig | None = None) -> None:
+    await asyncio.to_thread(_invalidate_enabled_skills_cache(app_config).wait)
+
+
+def _reset_skills_system_prompt_cache_state() -> None:
+    global _enabled_skills_cache, _enabled_skills_refresh_active, _enabled_skills_refresh_version
+
+    _get_cached_skills_prompt_section.cache_clear()
     with _enabled_skills_lock:
-        cached = _enabled_skills_by_config_cache.get(cache_key)
+        _enabled_skills_cache = None
-        if cached is not None:
+        _enabled_skills_refresh_active = False
-            cached_config, cached_skills = cached
+        _enabled_skills_refresh_version = 0
-            if cached_config is app_config:
+        _enabled_skills_refresh_event.clear()
-                return list(cached_skills)
+
+
+def _refresh_enabled_skills_cache(app_config: AppConfig | None = None) -> None:
+    """Backward-compatible test helper for direct synchronous reload."""
+    try:
+        skills = _load_enabled_skills_sync(app_config)
+    except Exception:
+        logger.exception("Failed to load enabled skills for prompt injection")
+        skills = []
 
-    skills = list(get_or_new_skill_storage(app_config=app_config).load_skills(enabled_only=True))
     with _enabled_skills_lock:
-        _enabled_skills_by_config_cache[cache_key] = (app_config, skills)
+        _enabled_skills_cache = skills
-    return list(skills)
+        _enabled_skills_refresh_active = False
-
+        _enabled_skills_refresh_event.set()
-
-def _skill_mutability_label(category: SkillCategory | str) -> str:
-    return "[custom, editable]" if category == SkillCategory.CUSTOM else "[built-in]"
-
-
-def clear_skills_system_prompt_cache() -> None:
-    _invalidate_enabled_skills_cache()
-
-
-async def refresh_skills_system_prompt_cache_async() -> None:
-    await asyncio.to_thread(_invalidate_enabled_skills_cache().wait)
 
 
 def _build_skill_evolution_section(skill_evolution_enabled: bool) -> str:
@@ -180,7 +166,7 @@ Skip simple one-off tasks.
 """
 
 
-def _build_available_subagents_description(available_names: list[str], bash_available: bool, *, app_config: AppConfig | None = None) -> str:
+def _build_available_subagents_description(available_names: list[str], bash_available: bool, app_config: AppConfig) -> str:
     """Dynamically build subagent type descriptions from registry.
 
     Mirrors Codex's pattern where agent_type_description is dynamically generated
@@ -202,7 +188,7 @@ def _build_available_subagents_description(available_names: list[str], bash_avai
         if name in builtin_descriptions:
             lines.append(f"- **{name}**: {builtin_descriptions[name]}")
         else:
-            config = get_subagent_config(name, app_config=app_config)
+            config = get_subagent_config(name, app_config)
             if config is not None:
                 desc = config.description.split("\n")[0].strip()  # First line only for brevity
                 lines.append(f"- **{name}**: {desc}")
@@ -210,22 +196,23 @@ def _build_available_subagents_description(available_names: list[str], bash_avai
     return "\n".join(lines)
 
 
-def _build_subagent_section(max_concurrent: int, *, app_config: AppConfig | None = None) -> str:
+def _build_subagent_section(max_concurrent: int, app_config: AppConfig) -> str:
     """Build the subagent system prompt section with dynamic concurrency limit.
 
     Args:
         max_concurrent: Maximum number of concurrent subagent calls allowed per response.
+        app_config: Application config used to gate bash availability.
 
     Returns:
         Formatted subagent section string.
     """
     n = max_concurrent
-    available_names = get_available_subagent_names(app_config=app_config) if app_config is not None else get_available_subagent_names()
+    available_names = get_available_subagent_names(app_config)
     bash_available = "bash" in available_names
 
     # Dynamically build subagent type descriptions from registry (aligned with Codex's
     # agent_type_description pattern where all registered roles are listed in the tool spec).
-    available_subagents = _build_available_subagents_description(available_names, bash_available, app_config=app_config)
+    available_subagents = _build_available_subagents_description(available_names, bash_available, app_config)
     direct_tool_examples = "bash, ls, read_file, web_search, etc." if bash_available else "ls, read_file, web_search, etc."
     direct_execution_example = (
         '# User asks: "Run the tests"\n# Thinking: Cannot decompose into parallel sub-tasks\n# → Execute directly\n\nbash("npm test")  # Direct execution, not task()'
@@ -366,7 +353,8 @@ You are {agent_name}, an open-source super agent.
 </role>
 
 {soul}
-{self_update_section}
+{memory_context}
+
 <thinking_style>
 - Think concisely and strategically about the user's request BEFORE taking action
 - Break down the task: What is clear? What is ambiguous? What is missing?
@@ -551,44 +539,34 @@ combined with a FastAPI gateway for REST API access [citation:FastAPI](https://f
 """
 
 
-def _get_memory_context(agent_name: str | None = None, *, app_config: AppConfig | None = None) -> str:
+def _get_memory_context(app_config: AppConfig, agent_name: str | None = None) -> str:
     """Get memory context for injection into system prompt.
 
-    Args:
+    Returns an empty string when memory is disabled or the stored memory file
-        agent_name: If provided, loads per-agent memory. If None, loads global memory.
+    cannot be read/parsed. A corrupt memory.json degrades the prompt to
-        app_config: Explicit application config. When provided, memory options
+    no-memory; it never kills the agent.
-            are read from this value instead of the global config singleton.
-
-    Returns:
-        Formatted memory context string wrapped in XML tags, or empty string if disabled.
     """
+    from deerflow.agents.memory import format_memory_for_injection, get_memory_data
+    from deerflow.runtime.user_context import get_effective_user_id
+
+    memory_config = app_config.memory
+    if not memory_config.enabled or not memory_config.injection_enabled:
+        return ""
+
     try:
-        from deerflow.agents.memory import format_memory_for_injection, get_memory_data
+        memory_data = get_memory_data(memory_config, agent_name, user_id=get_effective_user_id())
-        from deerflow.runtime.user_context import get_effective_user_id
+    except (OSError, ValueError, UnicodeDecodeError):
+        logger.exception("Failed to load memory data for prompt injection")
+        return ""
 
-        if app_config is None:
+    memory_content = format_memory_for_injection(memory_data, max_tokens=memory_config.max_injection_tokens)
-            from deerflow.config.memory_config import get_memory_config
+    if not memory_content.strip():
+        return ""
 
-            config = get_memory_config()
+    return f"""<memory>
-        else:
-            config = app_config.memory
-
-        if not config.enabled or not config.injection_enabled:
-            return ""
-
-        memory_data = get_memory_data(agent_name, user_id=get_effective_user_id())
-        memory_content = format_memory_for_injection(memory_data, max_tokens=config.max_injection_tokens)
-
-        if not memory_content.strip():
-            return ""
-
-        return f"""<memory>
 {memory_content}
 </memory>
 """
-    except Exception:
-        logger.exception("Failed to load memory context")
-        return ""
 
 
 @lru_cache(maxsize=32)
@@ -623,24 +601,12 @@ You have access to skills that provide optimized workflows for specific tasks. E
 </skill_system>"""
 
 
-def get_skills_prompt_section(available_skills: set[str] | None = None, *, app_config: AppConfig | None = None) -> str:
+def get_skills_prompt_section(app_config: AppConfig, available_skills: set[str] | None = None) -> str:
     """Generate the skills prompt section with available skills list."""
-    skills = get_enabled_skills_for_config(app_config)
+    skills = _get_enabled_skills(app_config)
 
-    if app_config is None:
+    container_base_path = app_config.skills.container_path
-        try:
+    skill_evolution_enabled = app_config.skill_evolution.enabled
-            from deerflow.config import get_app_config
-
-            config = get_app_config()
-            container_base_path = config.skills.container_path
-            skill_evolution_enabled = config.skill_evolution.enabled
-        except Exception:
-            container_base_path = "/mnt/skills"
-            skill_evolution_enabled = False
-    else:
-        config = app_config
-        container_base_path = config.skills.container_path
-        skill_evolution_enabled = config.skill_evolution.enabled
 
     if not skills and not skill_evolution_enabled:
         return ""
@@ -664,27 +630,7 @@ def get_agent_soul(agent_name: str | None) -> str:
     return ""
 
 
-def _build_self_update_section(agent_name: str | None) -> str:
+def get_deferred_tools_prompt_section(app_config: AppConfig) -> str:
-    """Prompt block that teaches the custom agent to persist self-updates via update_agent."""
-    if not agent_name:
-        return ""
-    return f"""<self_update>
-You are running as the custom agent **{agent_name}** with a persisted SOUL.md and config.yaml.
-
-When the user asks you to update your own description, personality, behaviour, skill set, tool groups, or default model,
-you MUST persist the change with the `update_agent` tool. Do NOT use `bash`, `write_file`, or any sandbox tool to edit
-SOUL.md or config.yaml — those write into a temporary sandbox/tool workspace and the changes will be lost on the next turn.
-
-Rules:
-- Always pass the FULL replacement text for `soul` (no patch semantics). Start from your current SOUL above and apply the user's edits.
-- Only pass the fields that should change. Omit the others to preserve them.
-- Pass `skills=[]` to disable all skills, or omit `skills` to keep the existing whitelist.
-- After `update_agent` returns successfully, tell the user the change is persisted and will take effect on the next turn.
-</self_update>
-"""
-
-
-def get_deferred_tools_prompt_section(*, app_config: AppConfig | None = None) -> str:
     """Generate <available-deferred-tools> block for the system prompt.
 
     Lists only deferred tool names so the agent knows what exists
@@ -693,17 +639,7 @@ def get_deferred_tools_prompt_section(*, app_config: AppConfig | None = None) ->
     """
     from deerflow.tools.builtins.tool_search import get_deferred_registry
 
-    if app_config is None:
+    if not app_config.tool_search.enabled:
-        try:
-            from deerflow.config import get_app_config
-
-            config = get_app_config()
-        except Exception:
-            return ""
-    else:
-        config = app_config
-
-    if not config.tool_search.enabled:
         return ""
 
     registry = get_deferred_registry()
@@ -714,19 +650,9 @@ def get_deferred_tools_prompt_section(*, app_config: AppConfig | None = None) ->
     return f"<available-deferred-tools>\n{names}\n</available-deferred-tools>"
 
 
-def _build_acp_section(*, app_config: AppConfig | None = None) -> str:
+def _build_acp_section(app_config: AppConfig) -> str:
     """Build the ACP agent prompt section, only if ACP agents are configured."""
-    if app_config is None:
+    if not app_config.acp_agents:
-        try:
-            from deerflow.config.acp_config import get_acp_agents
-
-            agents = get_acp_agents()
-        except Exception:
-            return ""
-    else:
-        agents = getattr(app_config, "acp_agents", {}) or {}
-
-    if not agents:
         return ""
 
     return (
@@ -738,20 +664,9 @@ def _build_acp_section(*, app_config: AppConfig | None = None) -> str:
     )
 
 
-def _build_custom_mounts_section(*, app_config: AppConfig | None = None) -> str:
+def _build_custom_mounts_section(app_config: AppConfig) -> str:
     """Build a prompt section for explicitly configured sandbox mounts."""
-    if app_config is None:
+    mounts = app_config.sandbox.mounts or []
-        try:
-            from deerflow.config import get_app_config
-
-            config = get_app_config()
-        except Exception:
-            logger.exception("Failed to load configured sandbox mounts for the lead-agent prompt")
-            return ""
-    else:
-        config = app_config
-
-    mounts = config.sandbox.mounts or []
 
     if not mounts:
         return ""
@@ -766,16 +681,19 @@ def _build_custom_mounts_section(*, app_config: AppConfig | None = None) -> str:
 
 
 def apply_prompt_template(
+    app_config: AppConfig,
     subagent_enabled: bool = False,
     max_concurrent_subagents: int = 3,
     *,
     agent_name: str | None = None,
     available_skills: set[str] | None = None,
-    app_config: AppConfig | None = None,
 ) -> str:
+    # Get memory context
+    memory_context = _get_memory_context(app_config, agent_name)
+
     # Include subagent section only if enabled (from runtime parameter)
     n = max_concurrent_subagents
-    subagent_section = _build_subagent_section(n, app_config=app_config) if subagent_enabled else ""
+    subagent_section = _build_subagent_section(n, app_config) if subagent_enabled else ""
 
     # Add subagent reminder to critical_reminders if enabled
     subagent_reminder = (
@@ -796,28 +714,27 @@ def apply_prompt_template(
     )
 
     # Get skills section
-    skills_section = get_skills_prompt_section(available_skills, app_config=app_config)
+    skills_section = get_skills_prompt_section(app_config, available_skills)
 
     # Get deferred tools section (tool_search)
-    deferred_tools_section = get_deferred_tools_prompt_section(app_config=app_config)
+    deferred_tools_section = get_deferred_tools_prompt_section(app_config)
 
     # Build ACP agent section only if ACP agents are configured
-    acp_section = _build_acp_section(app_config=app_config)
+    acp_section = _build_acp_section(app_config)
-    custom_mounts_section = _build_custom_mounts_section(app_config=app_config)
+    custom_mounts_section = _build_custom_mounts_section(app_config)
     acp_and_mounts_section = "\n".join(section for section in (acp_section, custom_mounts_section) if section)
 
-    # Build and return the fully static system prompt.
+    # Format the prompt with dynamic skills and memory
-    # Memory and current date are injected per-turn via DynamicContextMiddleware
+    prompt = SYSTEM_PROMPT_TEMPLATE.format(
-    # as a <system-reminder> in the first HumanMessage, keeping this prompt
-    # identical across users and sessions for maximum prefix-cache reuse.
-    return SYSTEM_PROMPT_TEMPLATE.format(
         agent_name=agent_name or "DeerFlow 2.0",
         soul=get_agent_soul(agent_name),
-        self_update_section=_build_self_update_section(agent_name),
         skills_section=skills_section,
         deferred_tools_section=deferred_tools_section,
+        memory_context=memory_context,
         subagent_section=subagent_section,
         subagent_reminder=subagent_reminder,
         subagent_thinking=subagent_thinking,
         acp_section=acp_and_mounts_section,
     )
+
+    return prompt + f"\n<current_date>{datetime.now().strftime('%Y-%m-%d, %A')}</current_date>"

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

@@ -7,11 +7,17 @@ from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from typing import Any
 
-from deerflow.config.memory_config import get_memory_config
+from deerflow.config.app_config import AppConfig
 
 logger = logging.getLogger(__name__)
 
 
+# Module-level config pointer set by the middleware that owns the queue.
+# The queue runs on a background Timer thread where ``Runtime`` and FastAPI
+# request context are not accessible; the enqueuer (which does have runtime
+# context) is responsible for plumbing ``AppConfig`` through ``add()``.
+
+
 @dataclass
 class ConversationContext:
     """Context for a conversation to be processed for memory update."""
@@ -31,10 +37,21 @@ class MemoryUpdateQueue:
     This queue collects conversation contexts and processes them after
     a configurable debounce period. Multiple conversations received within
     the debounce window are batched together.
+
+    The queue captures an ``AppConfig`` reference at construction time and
+    reuses it for the MemoryUpdater it spawns. Callers must construct a
+    fresh queue when the config changes rather than reaching into a global.
     """
 
-    def __init__(self):
+    def __init__(self, app_config: AppConfig):
-        """Initialize the memory update queue."""
+        """Initialize the memory update queue.
+
+        Args:
+            app_config: Application config. The queue reads its own
+                ``memory`` section for debounce timing and hands the full
+                config to :class:`MemoryUpdater`.
+        """
+        self._app_config = app_config
         self._queue: list[ConversationContext] = []
         self._lock = threading.Lock()
         self._timer: threading.Timer | None = None
@@ -49,19 +66,8 @@ class MemoryUpdateQueue:
         correction_detected: bool = False,
         reinforcement_detected: bool = False,
     ) -> None:
-        """Add a conversation to the update queue.
+        """Add a conversation to the update queue."""
-
+        config = self._app_config.memory
-        Args:
-            thread_id: The thread ID.
-            messages: The conversation messages.
-            agent_name: If provided, memory is stored per-agent. If None, uses global memory.
-            user_id: The user ID captured at enqueue time. Stored in ConversationContext so it
-                survives the threading.Timer boundary (ContextVar does not propagate across
-                raw threads).
-            correction_detected: Whether recent turns include an explicit correction signal.
-            reinforcement_detected: Whether recent turns include a positive reinforcement signal.
-        """
-        config = get_memory_config()
         if not config.enabled:
             return
 
@@ -88,7 +94,7 @@ class MemoryUpdateQueue:
         reinforcement_detected: bool = False,
     ) -> None:
         """Add a conversation and start processing immediately in the background."""
-        config = get_memory_config()
+        config = self._app_config.memory
         if not config.enabled:
             return
 
@@ -111,7 +117,7 @@ class MemoryUpdateQueue:
         thread_id: str,
         messages: list[Any],
         agent_name: str | None,
-        user_id: str | None,
+        user_id: str | None = None,
         correction_detected: bool,
         reinforcement_detected: bool,
     ) -> None:
@@ -135,7 +141,7 @@ class MemoryUpdateQueue:
 
     def _reset_timer(self) -> None:
         """Reset the debounce timer."""
-        config = get_memory_config()
+        config = self._app_config.memory
         self._schedule_timer(config.debounce_seconds)
 
         logger.debug("Memory update timer set for %ss", config.debounce_seconds)
@@ -175,7 +181,7 @@ class MemoryUpdateQueue:
         logger.info("Processing %d queued memory updates", len(contexts_to_process))
 
         try:
-            updater = MemoryUpdater()
+            updater = MemoryUpdater(self._app_config)
 
             for context in contexts_to_process:
                 try:
@@ -247,31 +253,35 @@ class MemoryUpdateQueue:
             return self._processing
 
 
-# Global singleton instance
+# Queues keyed by ``id(AppConfig)`` so tests and multi-client setups with
-_memory_queue: MemoryUpdateQueue | None = None
+# distinct configs do not share a debounce queue.
+_memory_queues: dict[int, MemoryUpdateQueue] = {}
 _queue_lock = threading.Lock()
 
 
-def get_memory_queue() -> MemoryUpdateQueue:
+def get_memory_queue(app_config: AppConfig) -> MemoryUpdateQueue:
-    """Get the global memory update queue singleton.
+    """Get or create the memory update queue for the given app config."""
-
+    key = id(app_config)
-    Returns:
-        The memory update queue instance.
-    """
-    global _memory_queue
     with _queue_lock:
-        if _memory_queue is None:
+        queue = _memory_queues.get(key)
-            _memory_queue = MemoryUpdateQueue()
+        if queue is None:
-        return _memory_queue
+            queue = MemoryUpdateQueue(app_config)
+            _memory_queues[key] = queue
+        return queue
 
 
-def reset_memory_queue() -> None:
+def reset_memory_queue(app_config: AppConfig | None = None) -> None:
-    """Reset the global memory queue.
+    """Reset memory queue(s).
 
-    This is useful for testing.
+    Pass an ``app_config`` to reset only its queue, or omit to reset all
+    (useful at test teardown).
     """
-    global _memory_queue
     with _queue_lock:
-        if _memory_queue is not None:
+        if app_config is not None:
-            _memory_queue.clear()
+            queue = _memory_queues.pop(id(app_config), None)
-        _memory_queue = None
+            if queue is not None:
+                queue.clear()
+            return
+        for queue in _memory_queues.values():
+            queue.clear()
+        _memory_queues.clear()

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

@@ -10,7 +10,7 @@ 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.memory_config import MemoryConfig
 from deerflow.config.paths import get_paths
 
 logger = logging.getLogger(__name__)
@@ -62,8 +62,15 @@ class MemoryStorage(abc.ABC):
 class FileMemoryStorage(MemoryStorage):
     """File-based memory storage provider."""
 
-    def __init__(self):
+    def __init__(self, memory_config: MemoryConfig):
-        """Initialize the file memory storage."""
+        """Initialize the file memory storage.
+
+        Args:
+            memory_config: Memory configuration (storage_path etc.). Stored on
+                the instance so per-request lookups don't need to reach for
+                ambient state.
+        """
+        self._memory_config = memory_config
         # Per-user/agent memory cache: keyed by (user_id, agent_name) tuple (None = global)
         # Value: (memory_data, file_mtime)
         self._memory_cache: dict[tuple[str | None, str | None], tuple[dict[str, Any], float | None]] = {}
@@ -83,11 +90,11 @@ class FileMemoryStorage(MemoryStorage):
 
     def _get_memory_file_path(self, agent_name: str | None = None, *, user_id: str | None = None) -> Path:
         """Get the path to the memory file."""
+        config = self._memory_config
         if user_id is not None:
             if agent_name is not None:
                 self._validate_agent_name(agent_name)
                 return get_paths().user_agent_memory_file(user_id, agent_name)
-            config = get_memory_config()
             if config.storage_path and Path(config.storage_path).is_absolute():
                 return Path(config.storage_path)
             return get_paths().user_memory_file(user_id)
@@ -95,7 +102,6 @@ class FileMemoryStorage(MemoryStorage):
         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
@@ -116,20 +122,16 @@ class FileMemoryStorage(MemoryStorage):
             logger.warning("Failed to load memory file: %s", e)
             return create_empty_memory()
 
-    @staticmethod
-    def _cache_key(agent_name: str | None = None, *, user_id: str | None = None) -> tuple[str | None, str | None]:
-        return (user_id, agent_name)
-
     def load(self, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
         """Load memory data (cached with file modification time check)."""
         file_path = self._get_memory_file_path(agent_name, user_id=user_id)
-        cache_key = self._cache_key(agent_name, user_id=user_id)
 
         try:
             current_mtime = file_path.stat().st_mtime if file_path.exists() else None
         except OSError:
             current_mtime = None
 
+        cache_key = (user_id, agent_name)
         with self._cache_lock:
             cached = self._memory_cache.get(cache_key)
             if cached is not None and cached[1] == current_mtime:
@@ -146,13 +148,13 @@ class FileMemoryStorage(MemoryStorage):
         """Reload memory data from file, forcing cache invalidation."""
         file_path = self._get_memory_file_path(agent_name, user_id=user_id)
         memory_data = self._load_memory_from_file(agent_name, user_id=user_id)
-        cache_key = self._cache_key(agent_name, user_id=user_id)
 
         try:
             mtime = file_path.stat().st_mtime if file_path.exists() else None
         except OSError:
             mtime = None
 
+        cache_key = (user_id, agent_name)
         with self._cache_lock:
             self._memory_cache[cache_key] = (memory_data, mtime)
         return memory_data
@@ -160,7 +162,6 @@ class FileMemoryStorage(MemoryStorage):
     def save(self, memory_data: dict[str, Any], agent_name: str | None = None, *, user_id: str | None = None) -> bool:
         """Save memory data to file and update cache."""
         file_path = self._get_memory_file_path(agent_name, user_id=user_id)
-        cache_key = self._cache_key(agent_name, user_id=user_id)
 
         try:
             file_path.parent.mkdir(parents=True, exist_ok=True)
@@ -180,6 +181,7 @@ class FileMemoryStorage(MemoryStorage):
             except OSError:
                 mtime = None
 
+            cache_key = (user_id, agent_name)
             with self._cache_lock:
                 self._memory_cache[cache_key] = (memory_data, mtime)
             logger.info("Memory saved to %s", file_path)
@@ -189,23 +191,31 @@ class FileMemoryStorage(MemoryStorage):
             return False
 
 
-_storage_instance: MemoryStorage | None = None
+# Instances keyed by (storage_class_path, id(memory_config)) so tests can
+# construct isolated storages and multi-client setups with different configs
+# don't collide on a single process-wide singleton.
+_storage_instances: dict[tuple[str, int], MemoryStorage] = {}
 _storage_lock = threading.Lock()
 
 
-def get_memory_storage() -> MemoryStorage:
+def get_memory_storage(memory_config: MemoryConfig) -> MemoryStorage:
-    """Get the configured memory storage instance."""
+    """Get the configured memory storage instance.
-    global _storage_instance
+
-    if _storage_instance is not None:
+    Caches one instance per ``(storage_class, memory_config)`` pair. In
-        return _storage_instance
+    single-config deployments this collapses to one instance; in multi-client
+    or test scenarios each config gets its own storage.
+    """
+    key = (memory_config.storage_class, id(memory_config))
+    existing = _storage_instances.get(key)
+    if existing is not None:
+        return existing
 
     with _storage_lock:
-        if _storage_instance is not None:
+        existing = _storage_instances.get(key)
-            return _storage_instance
+        if existing is not None:
-
+            return existing
-        config = get_memory_config()
-        storage_class_path = config.storage_class
 
+        storage_class_path = memory_config.storage_class
         try:
             module_path, class_name = storage_class_path.rsplit(".", 1)
             import importlib
@@ -219,13 +229,14 @@ def get_memory_storage() -> MemoryStorage:
             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()
+            instance = storage_class(memory_config)
         except Exception as e:
             logger.error(
                 "Failed to load memory storage %s, falling back to FileMemoryStorage: %s",
                 storage_class_path,
                 e,
             )
-            _storage_instance = FileMemoryStorage()
+            instance = FileMemoryStorage(memory_config)
 
-    return _storage_instance
+        _storage_instances[key] = instance
+        return instance

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

@@ -5,12 +5,19 @@ from __future__ import annotations
 from deerflow.agents.memory.message_processing import detect_correction, detect_reinforcement, filter_messages_for_memory
 from deerflow.agents.memory.queue import get_memory_queue
 from deerflow.agents.middlewares.summarization_middleware import SummarizationEvent
-from deerflow.config.memory_config import get_memory_config
+from deerflow.config.app_config import AppConfig
 
 
 def memory_flush_hook(event: SummarizationEvent) -> None:
-    """Flush messages about to be summarized into the memory queue."""
+    """Flush messages about to be summarized into the memory queue.
-    if not get_memory_config().enabled or not event.thread_id:
+
+    Reads ``AppConfig`` from disk on every invocation. This hook is fired by
+    ``SummarizationMiddleware`` which has no ergonomic way to thread an
+    explicit ``app_config`` through; ``AppConfig.from_file()`` is a pure load
+    so the cost is acceptable for this rare pre-summarization callback.
+    """
+    app_config = AppConfig.from_file()
+    if not app_config.memory.enabled or not event.thread_id:
         return
 
     filtered_messages = filter_messages_for_memory(list(event.messages_to_summarize))
@@ -21,7 +28,7 @@ def memory_flush_hook(event: SummarizationEvent) -> None:
 
     correction_detected = detect_correction(filtered_messages)
     reinforcement_detected = not correction_detected and detect_reinforcement(filtered_messages)
-    queue = get_memory_queue()
+    queue = get_memory_queue(app_config)
     queue.add_nowait(
         thread_id=event.thread_id,
         messages=filtered_messages,

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

@@ -9,6 +9,7 @@ import logging
 import math
 import re
 import uuid
+from collections.abc import Awaitable
 from typing import Any
 
 from deerflow.agents.memory.prompt import (
@@ -20,17 +21,12 @@ from deerflow.agents.memory.storage import (
     get_memory_storage,
     utc_now_iso_z,
 )
-from deerflow.config.memory_config import get_memory_config
+from deerflow.config.app_config import AppConfig
+from deerflow.config.memory_config import MemoryConfig
 from deerflow.models import create_chat_model
 
 logger = logging.getLogger(__name__)
 
-
-# Thread pool for offloading sync memory updates when called from an async
-# context.  Unlike the previous asyncio.run() approach, this runs *sync*
-# model.invoke() calls — no event loop is created, so the langchain async
-# httpx client pool (globally cached via @lru_cache) is never touched and
-# cross-loop connection reuse is impossible.
 _SYNC_MEMORY_UPDATER_EXECUTOR = concurrent.futures.ThreadPoolExecutor(
     max_workers=4,
     thread_name_prefix="memory-updater-sync",
@@ -43,45 +39,33 @@ def _create_empty_memory() -> dict[str, Any]:
     return create_empty_memory()
 
 
-def _save_memory_to_file(memory_data: dict[str, Any], agent_name: str | None = None, *, user_id: str | None = None) -> bool:
+def _save_memory_to_file(memory_config: MemoryConfig, memory_data: dict[str, Any], agent_name: str | None = None, *, user_id: str | None = None) -> bool:
-    """Backward-compatible wrapper around the configured memory storage save path."""
+    """Save via the configured memory storage."""
-    return get_memory_storage().save(memory_data, agent_name, user_id=user_id)
+    return get_memory_storage(memory_config).save(memory_data, agent_name, user_id=user_id)
 
 
-def get_memory_data(agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
+def get_memory_data(memory_config: MemoryConfig, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
     """Get the current memory data via storage provider."""
-    return get_memory_storage().load(agent_name, user_id=user_id)
+    return get_memory_storage(memory_config).load(agent_name, user_id=user_id)
 
 
-def reload_memory_data(agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
+def reload_memory_data(memory_config: MemoryConfig, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
     """Reload memory data via storage provider."""
-    return get_memory_storage().reload(agent_name, user_id=user_id)
+    return get_memory_storage(memory_config).reload(agent_name, user_id=user_id)
 
 
-def import_memory_data(memory_data: dict[str, Any], agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
+def import_memory_data(memory_config: MemoryConfig, memory_data: dict[str, Any], agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
-    """Persist imported memory data via storage provider.
+    """Persist imported memory data via storage provider."""
-
+    storage = get_memory_storage(memory_config)
-    Args:
-        memory_data: Full memory payload to persist.
-        agent_name: If provided, imports into per-agent memory.
-        user_id: If provided, scopes memory to a specific user.
-
-    Returns:
-        The saved memory data after storage normalization.
-
-    Raises:
-        OSError: If persisting the imported memory fails.
-    """
-    storage = get_memory_storage()
     if not storage.save(memory_data, agent_name, user_id=user_id):
         raise OSError("Failed to save imported memory data")
     return storage.load(agent_name, user_id=user_id)
 
 
-def clear_memory_data(agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
+def clear_memory_data(memory_config: MemoryConfig, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
     """Clear all stored memory data and persist an empty structure."""
     cleared_memory = create_empty_memory()
-    if not _save_memory_to_file(cleared_memory, agent_name, user_id=user_id):
+    if not _save_memory_to_file(memory_config, cleared_memory, agent_name, user_id=user_id):
         raise OSError("Failed to save cleared memory data")
     return cleared_memory
 
@@ -94,6 +78,7 @@ def _validate_confidence(confidence: float) -> float:
 
 
 def create_memory_fact(
+    memory_config: MemoryConfig,
     content: str,
     category: str = "context",
     confidence: float = 0.5,
@@ -109,7 +94,7 @@ def create_memory_fact(
     normalized_category = category.strip() or "context"
     validated_confidence = _validate_confidence(confidence)
     now = utc_now_iso_z()
-    memory_data = get_memory_data(agent_name, user_id=user_id)
+    memory_data = get_memory_data(memory_config, agent_name, user_id=user_id)
     updated_memory = dict(memory_data)
     facts = list(memory_data.get("facts", []))
     facts.append(
@@ -124,15 +109,15 @@ def create_memory_fact(
     )
     updated_memory["facts"] = facts
 
-    if not _save_memory_to_file(updated_memory, agent_name, user_id=user_id):
+    if not _save_memory_to_file(memory_config, updated_memory, agent_name, user_id=user_id):
         raise OSError("Failed to save memory data after creating fact")
 
     return updated_memory
 
 
-def delete_memory_fact(fact_id: str, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
+def delete_memory_fact(memory_config: MemoryConfig, fact_id: str, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
     """Delete a fact by its id and persist the updated memory data."""
-    memory_data = get_memory_data(agent_name, user_id=user_id)
+    memory_data = get_memory_data(memory_config, agent_name, user_id=user_id)
     facts = memory_data.get("facts", [])
     updated_facts = [fact for fact in facts if fact.get("id") != fact_id]
     if len(updated_facts) == len(facts):
@@ -141,13 +126,14 @@ def delete_memory_fact(fact_id: str, agent_name: str | None = None, *, user_id:
     updated_memory = dict(memory_data)
     updated_memory["facts"] = updated_facts
 
-    if not _save_memory_to_file(updated_memory, agent_name, user_id=user_id):
+    if not _save_memory_to_file(memory_config, updated_memory, agent_name, user_id=user_id):
         raise OSError(f"Failed to save memory data after deleting fact '{fact_id}'")
 
     return updated_memory
 
 
 def update_memory_fact(
+    memory_config: MemoryConfig,
     fact_id: str,
     content: str | None = None,
     category: str | None = None,
@@ -157,7 +143,7 @@ def update_memory_fact(
     user_id: str | None = None,
 ) -> dict[str, Any]:
     """Update an existing fact and persist the updated memory data."""
-    memory_data = get_memory_data(agent_name, user_id=user_id)
+    memory_data = get_memory_data(memory_config, agent_name, user_id=user_id)
     updated_memory = dict(memory_data)
     updated_facts: list[dict[str, Any]] = []
     found = False
@@ -184,7 +170,7 @@ def update_memory_fact(
 
     updated_memory["facts"] = updated_facts
 
-    if not _save_memory_to_file(updated_memory, agent_name, user_id=user_id):
+    if not _save_memory_to_file(memory_config, updated_memory, agent_name, user_id=user_id):
         raise OSError(f"Failed to save memory data after updating fact '{fact_id}'")
 
     return updated_memory
@@ -227,6 +213,39 @@ def _extract_text(content: Any) -> str:
     return str(content)
 
 
+def _run_async_update_sync(coro: Awaitable[bool]) -> bool:
+    """Run an async memory update from sync code, including nested-loop contexts."""
+    handed_off = False
+
+    try:
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+        if loop is not None and loop.is_running():
+            future = _SYNC_MEMORY_UPDATER_EXECUTOR.submit(asyncio.run, coro)
+            handed_off = True
+            return future.result()
+
+        handed_off = True
+        return asyncio.run(coro)
+    except Exception:
+        if not handed_off:
+            close = getattr(coro, "close", None)
+            if callable(close):
+                try:
+                    close()
+                except Exception:
+                    logger.debug(
+                        "Failed to close un-awaited memory update coroutine",
+                        exc_info=True,
+                    )
+
+        logger.exception("Failed to run async memory update from sync context")
+        return False
+
+
 # Matches sentences that describe a file-upload *event* rather than general
 # file-related work.  Deliberately narrow to avoid removing legitimate facts
 # such as "User works with CSV files" or "prefers PDF export".
@@ -276,19 +295,25 @@ def _fact_content_key(content: Any) -> str | None:
 class MemoryUpdater:
     """Updates memory using LLM based on conversation context."""
 
-    def __init__(self, model_name: str | None = None):
+    def __init__(self, app_config: AppConfig, model_name: str | None = None):
         """Initialize the memory updater.
 
         Args:
+            app_config: Application config (the updater needs both ``memory``
+                section for behavior and the full config for ``create_chat_model``).
             model_name: Optional model name to use. If None, uses config or default.
         """
+        self._app_config = app_config
         self._model_name = model_name
 
+    @property
+    def _memory_config(self) -> MemoryConfig:
+        return self._app_config.memory
+
     def _get_model(self):
         """Get the model for memory updates."""
-        config = get_memory_config()
+        model_name = self._model_name or self._memory_config.model_name
-        model_name = self._model_name or config.model_name
+        return create_chat_model(name=model_name, thinking_enabled=False, app_config=self._app_config)
-        return create_chat_model(name=model_name, thinking_enabled=False)
 
     def _build_correction_hint(
         self,
@@ -324,11 +349,11 @@ class MemoryUpdater:
         user_id: str | None = None,
     ) -> tuple[dict[str, Any], str] | None:
         """Load memory and build the update prompt for a conversation."""
-        config = get_memory_config()
+        config = self._memory_config
         if not config.enabled or not messages:
             return None
 
-        current_memory = get_memory_data(agent_name, user_id=user_id)
+        current_memory = get_memory_data(config, agent_name, user_id=user_id)
         conversation_text = format_conversation_for_update(messages)
         if not conversation_text.strip():
             return None
@@ -364,7 +389,7 @@ class MemoryUpdater:
         # cannot corrupt the still-cached original object reference.
         updated_memory = self._apply_updates(copy.deepcopy(current_memory), update_data, thread_id)
         updated_memory = _strip_upload_mentions_from_memory(updated_memory)
-        return get_memory_storage().save(updated_memory, agent_name, user_id=user_id)
+        return get_memory_storage(self._memory_config).save(updated_memory, agent_name, user_id=user_id)
 
     async def aupdate_memory(
         self,
@@ -375,43 +400,10 @@ class MemoryUpdater:
         reinforcement_detected: bool = False,
         user_id: str | None = None,
     ) -> bool:
-        """Update memory asynchronously by delegating to the sync path.
+        """Update memory asynchronously based on conversation messages."""
-
-        Uses ``asyncio.to_thread`` to run the *sync* ``model.invoke()`` path
-        in a worker thread so no second event loop is created and the
-        langchain async httpx client pool (shared with the lead agent) is
-        never touched.  This eliminates the cross-loop connection-reuse bug
-        described in issue #2615.
-        """
-        return await asyncio.to_thread(
-            self._do_update_memory_sync,
-            messages=messages,
-            thread_id=thread_id,
-            agent_name=agent_name,
-            correction_detected=correction_detected,
-            reinforcement_detected=reinforcement_detected,
-            user_id=user_id,
-        )
-
-    def _do_update_memory_sync(
-        self,
-        messages: list[Any],
-        thread_id: str | None = None,
-        agent_name: str | None = None,
-        correction_detected: bool = False,
-        reinforcement_detected: bool = False,
-        user_id: str | None = None,
-    ) -> bool:
-        """Pure-sync memory update using ``model.invoke()``.
-
-        Uses the *sync* LLM call path so no event loop is created.  This
-        guarantees that the langchain provider's globally cached async
-        httpx ``AsyncClient`` / connection pool (the one shared with the
-        lead agent) is never touched — no cross-loop connection reuse is
-        possible.
-        """
         try:
-            prepared = self._prepare_update_prompt(
+            prepared = await asyncio.to_thread(
+                self._prepare_update_prompt,
                 messages=messages,
                 agent_name=agent_name,
                 correction_detected=correction_detected,
@@ -423,8 +415,9 @@ class MemoryUpdater:
 
             current_memory, prompt = prepared
             model = self._get_model()
-            response = model.invoke(prompt, config={"run_name": "memory_agent"})
+            response = await model.ainvoke(prompt, config={"run_name": "memory_agent"})
-            return self._finalize_update(
+            return await asyncio.to_thread(
+                self._finalize_update,
                 current_memory=current_memory,
                 response_content=response.content,
                 thread_id=thread_id,
@@ -447,16 +440,7 @@ class MemoryUpdater:
         reinforcement_detected: bool = False,
         user_id: str | None = None,
     ) -> bool:
-        """Synchronously update memory using the sync LLM path.
+        """Synchronously update memory via the async updater path.
-
-        Uses ``model.invoke()`` (sync HTTP) which operates on a completely
-        separate connection pool from the async ``AsyncClient`` shared by
-        the lead agent.  This eliminates the cross-loop connection-reuse
-        bug described in issue #2615.
-
-        When called from within a running event loop (e.g. from a LangGraph
-        node), the blocking sync call is offloaded to a thread pool so the
-        caller's loop is not blocked.
 
         Args:
             messages: List of conversation messages.
@@ -469,35 +453,78 @@ class MemoryUpdater:
         Returns:
             True if update was successful, False otherwise.
         """
-        try:
+        config = self._memory_config
-            loop = asyncio.get_running_loop()
+        if not config.enabled:
-        except RuntimeError:
+            return False
-            loop = None
 
-        if loop is not None and loop.is_running():
+        if not messages:
-            try:
+            return False
-                future = _SYNC_MEMORY_UPDATER_EXECUTOR.submit(
+
-                    self._do_update_memory_sync,
+        try:
-                    messages=messages,
+            # Get current memory
-                    thread_id=thread_id,
+            current_memory = get_memory_data(config, agent_name, user_id=user_id)
-                    agent_name=agent_name,
+
-                    correction_detected=correction_detected,
+            # Format conversation for prompt
-                    reinforcement_detected=reinforcement_detected,
+            conversation_text = format_conversation_for_update(messages)
-                    user_id=user_id,
+
-                )
+            if not conversation_text.strip():
-                return future.result()
-            except Exception:
-                logger.exception("Failed to offload memory update to executor")
                 return False
 
-        return self._do_update_memory_sync(
+            # Build prompt
-            messages=messages,
+            correction_hint = ""
-            thread_id=thread_id,
+            if correction_detected:
-            agent_name=agent_name,
+                correction_hint = (
-            correction_detected=correction_detected,
+                    "IMPORTANT: Explicit correction signals were detected in this conversation. "
-            reinforcement_detected=reinforcement_detected,
+                    "Pay special attention to what the agent got wrong, what the user corrected, "
-            user_id=user_id,
+                    "and record the correct approach as a fact with category "
-        )
+                    '"correction" and confidence >= 0.95 when appropriate.'
+                )
+            if reinforcement_detected:
+                reinforcement_hint = (
+                    "IMPORTANT: Positive reinforcement signals were detected in this conversation. "
+                    "The user explicitly confirmed the agent's approach was correct or helpful. "
+                    "Record the confirmed approach, style, or preference as a fact with category "
+                    '"preference" or "behavior" and confidence >= 0.9 when appropriate.'
+                )
+                correction_hint = (correction_hint + "\n" + reinforcement_hint).strip() if correction_hint else reinforcement_hint
+
+            prompt = MEMORY_UPDATE_PROMPT.format(
+                current_memory=json.dumps(current_memory, indent=2),
+                conversation=conversation_text,
+                correction_hint=correction_hint,
+            )
+
+            # Call LLM
+            model = self._get_model()
+            response = model.invoke(prompt)
+            response_text = _extract_text(response.content).strip()
+
+            # Parse response
+            # Remove markdown code blocks if present
+            if response_text.startswith("```"):
+                lines = response_text.split("\n")
+                response_text = "\n".join(lines[1:-1] if lines[-1] == "```" else lines[1:])
+
+            update_data = json.loads(response_text)
+
+            # Apply updates
+            updated_memory = self._apply_updates(current_memory, update_data, thread_id)
+
+            # Strip file-upload mentions from all summaries before saving.
+            # Uploaded files are session-scoped and won't exist in future sessions,
+            # so recording upload events in long-term memory causes the agent to
+            # try (and fail) to locate those files in subsequent conversations.
+            updated_memory = _strip_upload_mentions_from_memory(updated_memory)
+
+            # Save
+            return get_memory_storage(config).save(updated_memory, agent_name, user_id=user_id)
+
+        except json.JSONDecodeError as e:
+            logger.warning("Failed to parse LLM response for memory update: %s", e)
+            return False
+        except Exception as e:
+            logger.exception("Memory update failed: %s", e)
+            return False
 
     def _apply_updates(
         self,
@@ -515,7 +542,7 @@ class MemoryUpdater:
         Returns:
             Updated memory data.
         """
-        config = get_memory_config()
+        config = self._memory_config
         now = utc_now_iso_z()
 
         # Update user sections

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

@@ -1,204 +0,0 @@
-"""Middleware to inject dynamic context (memory, current date) as a system-reminder.
-
-The system prompt is kept fully static for maximum prefix-cache reuse across users
-and sessions.  The current date is always injected.  Per-user memory is also injected
-when ``memory.injection_enabled`` is True in the app config.  Both are delivered once
-per conversation as a dedicated <system-reminder> HumanMessage inserted before the
-first user message (frozen-snapshot pattern).
-
-When a conversation spans midnight the middleware detects the date change and injects
-a lightweight date-update reminder as a separate HumanMessage before the current turn.
-This correction is persisted so subsequent turns on the new day see a consistent history
-and do not re-inject.
-
-Reminder format:
-
-    <system-reminder>
-    <memory>...</memory>
-
-    <current_date>2026-05-08, Friday</current_date>
-    </system-reminder>
-
-Date-update format:
-
-    <system-reminder>
-    <current_date>2026-05-09, Saturday</current_date>
-    </system-reminder>
-"""
-
-from __future__ import annotations
-
-import logging
-import re
-import uuid
-from datetime import datetime
-from typing import TYPE_CHECKING, override
-
-from langchain.agents.middleware import AgentMiddleware
-from langchain_core.messages import HumanMessage
-from langgraph.runtime import Runtime
-
-if TYPE_CHECKING:
-    from deerflow.config.app_config import AppConfig
-
-logger = logging.getLogger(__name__)
-
-_DATE_RE = re.compile(r"<current_date>([^<]+)</current_date>")
-_DYNAMIC_CONTEXT_REMINDER_KEY = "dynamic_context_reminder"
-_SUMMARY_MESSAGE_NAME = "summary"
-
-
-def _extract_date(content: str) -> str | None:
-    """Return the first <current_date> value found in *content*, or None."""
-    m = _DATE_RE.search(content)
-    return m.group(1) if m else None
-
-
-def is_dynamic_context_reminder(message: object) -> bool:
-    """Return whether *message* is a hidden dynamic-context reminder."""
-    return isinstance(message, HumanMessage) and bool(message.additional_kwargs.get(_DYNAMIC_CONTEXT_REMINDER_KEY))
-
-
-def _last_injected_date(messages: list) -> str | None:
-    """Scan messages in reverse and return the most recently injected date.
-
-    Detection uses the ``dynamic_context_reminder`` additional_kwargs flag rather
-    than content substring matching, so user messages containing ``<system-reminder>``
-    are not mistakenly treated as injected reminders.
-    """
-    for msg in reversed(messages):
-        if is_dynamic_context_reminder(msg):
-            content_str = msg.content if isinstance(msg.content, str) else str(msg.content)
-            return _extract_date(content_str)
-    return None
-
-
-def _is_user_injection_target(message: object) -> bool:
-    """Return whether *message* can receive a dynamic-context reminder."""
-    return isinstance(message, HumanMessage) and not is_dynamic_context_reminder(message) and message.name != _SUMMARY_MESSAGE_NAME
-
-
-class DynamicContextMiddleware(AgentMiddleware):
-    """Inject memory and current date into HumanMessages as a <system-reminder>.
-
-    First turn
-    ----------
-    Prepends a full system-reminder (memory + date) to the first HumanMessage and
-    persists it (same message ID).  The first message is then frozen for the whole
-    session — its content never changes again, so the prefix cache can hit on every
-    subsequent turn.
-
-    Midnight crossing
-    -----------------
-    If the conversation spans midnight, the current date differs from the date that
-    was injected earlier.  In that case a lightweight date-update reminder is prepended
-    to the **current** (last) HumanMessage and persisted.  Subsequent turns on the new
-    day see the corrected date in history and skip re-injection.
-    """
-
-    def __init__(self, agent_name: str | None = None, *, app_config: AppConfig | None = None):
-        super().__init__()
-        self._agent_name = agent_name
-        self._app_config = app_config
-
-    def _build_full_reminder(self) -> str:
-        from deerflow.agents.lead_agent.prompt import _get_memory_context
-
-        # Memory injection is gated by injection_enabled; date is always included.
-        injection_enabled = self._app_config.memory.injection_enabled if self._app_config else True
-        memory_context = _get_memory_context(self._agent_name, app_config=self._app_config) if injection_enabled else ""
-        current_date = datetime.now().strftime("%Y-%m-%d, %A")
-
-        lines: list[str] = ["<system-reminder>"]
-        if memory_context:
-            lines.append(memory_context.strip())
-            lines.append("")  # blank line separating memory from date
-        lines.append(f"<current_date>{current_date}</current_date>")
-        lines.append("</system-reminder>")
-
-        return "\n".join(lines)
-
-    def _build_date_update_reminder(self) -> str:
-        current_date = datetime.now().strftime("%Y-%m-%d, %A")
-        return "\n".join(
-            [
-                "<system-reminder>",
-                f"<current_date>{current_date}</current_date>",
-                "</system-reminder>",
-            ]
-        )
-
-    @staticmethod
-    def _make_reminder_and_user_messages(original: HumanMessage, reminder_content: str) -> tuple[HumanMessage, HumanMessage]:
-        """Return (reminder_msg, user_msg) using the ID-swap technique.
-
-        reminder_msg takes the original message's ID so that add_messages replaces it
-        in-place (preserving position).  user_msg carries the original content with a
-        derived ``{id}__user`` ID and is appended immediately after by add_messages.
-
-        If the original message has no ID a stable UUID is generated so the derived
-        ``{id}__user`` ID never collapses to the ambiguous ``None__user`` string.
-        """
-        stable_id = original.id or str(uuid.uuid4())
-        reminder_msg = HumanMessage(
-            content=reminder_content,
-            id=stable_id,
-            additional_kwargs={"hide_from_ui": True, _DYNAMIC_CONTEXT_REMINDER_KEY: True},
-        )
-        user_msg = HumanMessage(
-            content=original.content,
-            id=f"{stable_id}__user",
-            name=original.name,
-            additional_kwargs=original.additional_kwargs,
-        )
-        return reminder_msg, user_msg
-
-    def _inject(self, state) -> dict | None:
-        messages = list(state.get("messages", []))
-        if not messages:
-            return None
-
-        current_date = datetime.now().strftime("%Y-%m-%d, %A")
-        last_date = _last_injected_date(messages)
-        logger.debug(
-            "DynamicContextMiddleware._inject: msg_count=%d last_date=%r current_date=%r",
-            len(messages),
-            last_date,
-            current_date,
-        )
-
-        if last_date is None:
-            # ── First turn: inject full reminder as a separate HumanMessage ─────
-            first_idx = next((i for i, m in enumerate(messages) if _is_user_injection_target(m)), None)
-            if first_idx is None:
-                return None
-            full_reminder = self._build_full_reminder()
-            logger.info(
-                "DynamicContextMiddleware: injecting full reminder (len=%d, has_memory=%s) into first HumanMessage id=%r",
-                len(full_reminder),
-                "<memory>" in full_reminder,
-                messages[first_idx].id,
-            )
-            reminder_msg, user_msg = self._make_reminder_and_user_messages(messages[first_idx], full_reminder)
-            return {"messages": [reminder_msg, user_msg]}
-
-        if last_date == current_date:
-            # ── Same day: nothing to do ──────────────────────────────────────────
-            return None
-
-        # ── Midnight crossed: inject date-update reminder as a separate HumanMessage ──
-        last_human_idx = next((i for i in reversed(range(len(messages))) if _is_user_injection_target(messages[i])), None)
-        if last_human_idx is None:
-            return None
-
-        reminder_msg, user_msg = self._make_reminder_and_user_messages(messages[last_human_idx], self._build_date_update_reminder())
-        logger.info("DynamicContextMiddleware: midnight crossing detected — injected date update before current turn")
-        return {"messages": [reminder_msg, user_msg]}
-
-    @override
-    def before_agent(self, state, runtime: Runtime) -> dict | None:
-        return self._inject(state)
-
-    @override
-    async def abefore_agent(self, state, runtime: Runtime) -> dict | None:
-        return self._inject(state)

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

@@ -70,11 +70,20 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
     retry_base_delay_ms: int = 1000
     retry_cap_delay_ms: int = 8000
 
-    def __init__(self, *, app_config: AppConfig, **kwargs: Any) -> None:
+    circuit_failure_threshold: int = 5
+    circuit_recovery_timeout_sec: int = 60
+
+    def __init__(self, **kwargs: Any) -> None:
         super().__init__(**kwargs)
 
-        self.circuit_failure_threshold = app_config.circuit_breaker.failure_threshold
+        # Load Circuit Breaker configs from app config if available, fall back to defaults
-        self.circuit_recovery_timeout_sec = app_config.circuit_breaker.recovery_timeout_sec
+        try:
+            app_config = AppConfig.from_file()
+            self.circuit_failure_threshold = app_config.circuit_breaker.failure_threshold
+            self.circuit_recovery_timeout_sec = app_config.circuit_breaker.recovery_timeout_sec
+        except (FileNotFoundError, RuntimeError):
+            # Gracefully fall back to class defaults in test environments
+            pass
 
         # Circuit Breaker state
         self._circuit_lock = threading.Lock()

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

@@ -12,22 +12,20 @@ Detection strategy:
      response so the agent is forced to produce a final text answer.
 """
 
-from __future__ import annotations
-
 import hashlib
 import json
 import logging
 import threading
 from collections import OrderedDict, defaultdict
 from copy import deepcopy
-from typing import TYPE_CHECKING, override
+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
 
-if TYPE_CHECKING:
+from deerflow.config.deer_flow_context import DeerFlowContext
-    from deerflow.config.loop_detection_config import LoopDetectionConfig
 
 logger = logging.getLogger(__name__)
 
@@ -144,9 +142,6 @@ _TOOL_FREQ_HARD_STOP_MSG = "[FORCED STOP] Tool {tool_name} called {count} times
 class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
     """Detects and breaks repetitive tool call loops.
 
-    Threshold parameters are validated upstream by :class:`LoopDetectionConfig`;
-    construct via :meth:`from_config` to ensure values pass Pydantic validation.
-
     Args:
         warn_threshold: Number of identical tool call sets before injecting
             a warning message. Default: 3.
@@ -162,14 +157,6 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
             Default: 30.
         tool_freq_hard_limit: Number of calls to the same tool type before
             forcing a stop. Default: 50.
-        tool_freq_overrides: Per-tool overrides for frequency thresholds,
-            keyed by tool name. Each value is a ``(warn, hard_limit)`` tuple
-            that replaces ``tool_freq_warn`` / ``tool_freq_hard_limit`` for
-            that specific tool. Tools not listed here fall back to the global
-            thresholds. Useful for raising limits on intentionally
-            high-frequency tools (e.g. ``bash`` in batch pipelines) without
-            weakening protection on all other tools. Default: ``None``
-            (no overrides).
     """
 
     def __init__(
@@ -180,7 +167,6 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
         max_tracked_threads: int = _DEFAULT_MAX_TRACKED_THREADS,
         tool_freq_warn: int = _DEFAULT_TOOL_FREQ_WARN,
         tool_freq_hard_limit: int = _DEFAULT_TOOL_FREQ_HARD_LIMIT,
-        tool_freq_overrides: dict[str, tuple[int, int]] | None = None,
     ):
         super().__init__()
         self.warn_threshold = warn_threshold
@@ -189,32 +175,17 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
         self.max_tracked_threads = max_tracked_threads
         self.tool_freq_warn = tool_freq_warn
         self.tool_freq_hard_limit = tool_freq_hard_limit
-        self._tool_freq_overrides: dict[str, tuple[int, int]] = tool_freq_overrides or {}
         self._lock = threading.Lock()
+        # Per-thread tracking using OrderedDict for LRU eviction
         self._history: OrderedDict[str, list[str]] = OrderedDict()
         self._warned: dict[str, set[str]] = defaultdict(set)
+        # Per-thread, per-tool-type cumulative call counts
         self._tool_freq: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
         self._tool_freq_warned: dict[str, set[str]] = defaultdict(set)
 
-    @classmethod
+    def _get_thread_id(self, runtime: Runtime[DeerFlowContext]) -> str:
-    def from_config(cls, config: LoopDetectionConfig) -> LoopDetectionMiddleware:
-        """Construct from a Pydantic-validated config, trusting its validation."""
-        return cls(
-            warn_threshold=config.warn_threshold,
-            hard_limit=config.hard_limit,
-            window_size=config.window_size,
-            max_tracked_threads=config.max_tracked_threads,
-            tool_freq_warn=config.tool_freq_warn,
-            tool_freq_hard_limit=config.tool_freq_hard_limit,
-            tool_freq_overrides={name: (o.warn, o.hard_limit) for name, o in config.tool_freq_overrides.items()},
-        )
-
-    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
+        return runtime.context.thread_id or "default"
-        if thread_id:
-            return thread_id
-        return "default"
 
     def _evict_if_needed(self) -> None:
         """Evict least recently used threads if over the limit.
@@ -308,12 +279,7 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
                 freq[name] += 1
                 tc_count = freq[name]
 
-                if name in self._tool_freq_overrides:
+                if tc_count >= self.tool_freq_hard_limit:
-                    eff_warn, eff_hard = self._tool_freq_overrides[name]
-                else:
-                    eff_warn, eff_hard = self.tool_freq_warn, self.tool_freq_hard_limit
-
-                if tc_count >= eff_hard:
                     logger.error(
                         "Tool frequency hard limit reached — forcing stop",
                         extra={
@@ -324,7 +290,7 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
                     )
                     return _TOOL_FREQ_HARD_STOP_MSG.format(tool_name=name, count=tc_count), True
 
-                if tc_count >= eff_warn:
+                if tc_count >= self.tool_freq_warn:
                     warned = self._tool_freq_warned[thread_id]
                     if name not in warned:
                         warned.add(name)
@@ -389,39 +355,22 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
             return {"messages": [stripped_msg]}
 
         if warning:
-            # WORKAROUND for v2.0-m1 — see #2724.
+            # Inject as HumanMessage instead of SystemMessage to avoid
-            #
+            # Anthropic's "multiple non-consecutive system messages" error.
-            # Append the warning to the AIMessage content instead of
+            # Anthropic models require system messages only at the start of
-            # injecting a separate HumanMessage. Inserting any non-tool
+            # the conversation; injecting one mid-conversation crashes
-            # message between an AIMessage(tool_calls=...) and its
+            # langchain_anthropic's _format_messages(). HumanMessage works
-            # ToolMessage responses breaks OpenAI/Moonshot strict pairing
+            # with all providers. See #1299.
-            # validation ("tool_call_ids did not have response messages")
+            return {"messages": [HumanMessage(content=warning)]}
-            # because the tools node has not run yet at after_model time.
-            # tool_calls are preserved so the tools node still executes.
-            #
-            # This is a temporary mitigation: mutating an existing
-            # AIMessage to carry framework-authored text leaks loop-warning
-            # text into downstream consumers (MemoryMiddleware fact
-            # extraction, TitleMiddleware, telemetry, model replay) as if
-            # the model said it. The proper fix is to defer warning
-            # injection from after_model to wrap_model_call so every prior
-            # ToolMessage is already in the request — see RFC #2517 (which
-            # lists "loop intervention does not leave invalid
-            # tool-call/tool-message state" as acceptance criteria) and
-            # the prototype on `fix/loop-detection-tool-call-pairing`.
-            messages = state.get("messages", [])
-            last_msg = messages[-1]
-            patched_msg = last_msg.model_copy(update={"content": self._append_text(last_msg.content, warning)})
-            return {"messages": [patched_msg]}
 
         return None
 
     @override
-    def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
+    def after_model(self, state: AgentState, runtime: Runtime[DeerFlowContext]) -> dict | None:
         return self._apply(state, runtime)
 
     @override
-    async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict | None:
+    async def aafter_model(self, state: AgentState, runtime: Runtime[DeerFlowContext]) -> dict | None:
         return self._apply(state, runtime)
 
     def reset(self, thread_id: str | None = None) -> None:

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

@@ -1,21 +1,17 @@
 """Middleware for memory mechanism."""
 
 import logging
-from typing import TYPE_CHECKING, override
+from typing import override
 
 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
-from langgraph.config import get_config
 from langgraph.runtime import Runtime
 
 from deerflow.agents.memory.message_processing import detect_correction, detect_reinforcement, filter_messages_for_memory
 from deerflow.agents.memory.queue import get_memory_queue
-from deerflow.config.memory_config import get_memory_config
+from deerflow.config.deer_flow_context import DeerFlowContext
 from deerflow.runtime.user_context import get_effective_user_id
 
-if TYPE_CHECKING:
-    from deerflow.config.memory_config import MemoryConfig
-
 logger = logging.getLogger(__name__)
 
 
@@ -37,20 +33,17 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
 
     state_schema = MemoryMiddlewareState
 
-    def __init__(self, agent_name: str | None = None, *, memory_config: "MemoryConfig | None" = None):
+    def __init__(self, agent_name: str | None = None):
         """Initialize the MemoryMiddleware.
 
         Args:
             agent_name: If provided, memory is stored per-agent. If None, uses global memory.
-            memory_config: Explicit memory config. When omitted, legacy global
-                config fallback is used.
         """
         super().__init__()
         self._agent_name = agent_name
-        self._memory_config = memory_config
 
     @override
-    def after_agent(self, state: MemoryMiddlewareState, runtime: Runtime) -> dict | None:
+    def after_agent(self, state: MemoryMiddlewareState, runtime: Runtime[DeerFlowContext]) -> dict | None:
         """Queue conversation for memory update after agent completes.
 
         Args:
@@ -60,15 +53,11 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
         Returns:
             None (no state changes needed from this middleware).
         """
-        config = self._memory_config or get_memory_config()
+        memory_config = runtime.context.app_config.memory
-        if not config.enabled:
+        if not memory_config.enabled:
             return None
 
-        # Get thread ID from runtime context first, then fall back to LangGraph's configurable metadata
+        thread_id = runtime.context.thread_id
-        thread_id = runtime.context.get("thread_id") if runtime.context else None
-        if thread_id is None:
-            config_data = get_config()
-            thread_id = config_data.get("configurable", {}).get("thread_id")
         if not thread_id:
             logger.debug("No thread_id in context, skipping memory update")
             return None
@@ -97,7 +86,7 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
         # threading.Timer fires on a different thread where ContextVar values are not
         # propagated, so we must store user_id explicitly in ConversationContext.
         user_id = get_effective_user_id()
-        queue = get_memory_queue()
+        queue = get_memory_queue(runtime.context.app_config)
         queue.add(
             thread_id=thread_id,
             messages=filtered_messages,

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

@@ -7,7 +7,6 @@ from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
 from langgraph.runtime import Runtime
 
-from deerflow.agents.middlewares.tool_call_metadata import clone_ai_message_with_tool_calls
 from deerflow.subagents.executor import MAX_CONCURRENT_SUBAGENTS
 
 logger = logging.getLogger(__name__)
@@ -64,7 +63,7 @@ class SubagentLimitMiddleware(AgentMiddleware[AgentState]):
         logger.warning(f"Truncated {dropped_count} excess task tool call(s) from model response (limit: {self.max_concurrent})")
 
         # Replace the AIMessage with truncated tool_calls (same id triggers replacement)
-        updated_msg = clone_ai_message_with_tool_calls(last_msg, truncated_tool_calls)
+        updated_msg = last_msg.model_copy(update={"tool_calls": truncated_tool_calls})
         return {"messages": [updated_msg]}
 
     @override

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

@@ -5,18 +5,15 @@ from __future__ import annotations
 import logging
 from collections.abc import Collection
 from dataclasses import dataclass
-from typing import Any, Protocol, override, runtime_checkable
+from typing import Any, Protocol, runtime_checkable
 
 from langchain.agents import AgentState
 from langchain.agents.middleware import SummarizationMiddleware
-from langchain_core.messages import AIMessage, AnyMessage, HumanMessage, RemoveMessage, ToolMessage
+from langchain_core.messages import AIMessage, AnyMessage, RemoveMessage, ToolMessage
 from langgraph.config import get_config
 from langgraph.graph.message import REMOVE_ALL_MESSAGES
 from langgraph.runtime import Runtime
 
-from deerflow.agents.middlewares.dynamic_context_middleware import is_dynamic_context_reminder
-from deerflow.agents.middlewares.tool_call_metadata import clone_ai_message_with_tool_calls
-
 logger = logging.getLogger(__name__)
 
 
@@ -81,7 +78,10 @@ def _clone_ai_message(
     content: Any | None = None,
 ) -> AIMessage:
     """Clone an AIMessage while replacing its tool_calls list and optional content."""
-    return clone_ai_message_with_tool_calls(message, tool_calls, content=content)
+    update: dict[str, Any] = {"tool_calls": tool_calls}
+    if content is not None:
+        update["content"] = content
+    return message.model_copy(update=update)
 
 
 @dataclass
@@ -136,7 +136,6 @@ class DeerFlowSummarizationMiddleware(SummarizationMiddleware):
             return None
 
         messages_to_summarize, preserved_messages = self._partition_with_skill_rescue(messages, cutoff_index)
-        messages_to_summarize, preserved_messages = self._preserve_dynamic_context_reminders(messages_to_summarize, preserved_messages)
         self._fire_hooks(messages_to_summarize, preserved_messages, runtime)
         summary = self._create_summary(messages_to_summarize)
         new_messages = self._build_new_messages(summary)
@@ -162,7 +161,6 @@ class DeerFlowSummarizationMiddleware(SummarizationMiddleware):
             return None
 
         messages_to_summarize, preserved_messages = self._partition_with_skill_rescue(messages, cutoff_index)
-        messages_to_summarize, preserved_messages = self._preserve_dynamic_context_reminders(messages_to_summarize, preserved_messages)
         self._fire_hooks(messages_to_summarize, preserved_messages, runtime)
         summary = await self._acreate_summary(messages_to_summarize)
         new_messages = self._build_new_messages(summary)
@@ -175,31 +173,6 @@ class DeerFlowSummarizationMiddleware(SummarizationMiddleware):
             ]
         }
 
-    @override
-    def _build_new_messages(self, summary: str) -> list[HumanMessage]:
-        """Override the base implementation to let the human message with the special name 'summary'.
-        And this message will be ignored to display in the frontend, but still can be used as context for the model.
-        """
-        return [HumanMessage(content=f"Here is a summary of the conversation to date:\n\n{summary}", name="summary")]
-
-    def _preserve_dynamic_context_reminders(
-        self,
-        messages_to_summarize: list[AnyMessage],
-        preserved_messages: list[AnyMessage],
-    ) -> tuple[list[AnyMessage], list[AnyMessage]]:
-        """Keep hidden dynamic-context reminders out of summary compression.
-
-        These reminders carry the current date and optional memory. If summarization
-        removes them, DynamicContextMiddleware can mistake the summary HumanMessage
-        for the first user message and inject the reminder in the wrong place.
-        """
-        reminders = [msg for msg in messages_to_summarize if is_dynamic_context_reminder(msg)]
-        if not reminders:
-            return messages_to_summarize, preserved_messages
-
-        remaining = [msg for msg in messages_to_summarize if not is_dynamic_context_reminder(msg)]
-        return remaining, reminders + preserved_messages
-
     def _partition_with_skill_rescue(
         self,
         messages: list[AnyMessage],

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

@@ -1,14 +1,12 @@
 import logging
-from datetime import UTC, datetime
 from typing import NotRequired, override
 
 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
-from langchain_core.messages import HumanMessage
-from langgraph.config import get_config
 from langgraph.runtime import Runtime
 
 from deerflow.agents.thread_state import ThreadDataState
+from deerflow.config.deer_flow_context import DeerFlowContext
 from deerflow.config.paths import Paths, get_paths
 from deerflow.runtime.user_context import get_effective_user_id
 
@@ -79,14 +77,10 @@ class ThreadDataMiddleware(AgentMiddleware[ThreadDataMiddlewareState]):
         return self._get_thread_paths(thread_id, user_id=user_id)
 
     @override
-    def before_agent(self, state: ThreadDataMiddlewareState, runtime: Runtime) -> dict | None:
+    def before_agent(self, state: ThreadDataMiddlewareState, runtime: Runtime[DeerFlowContext]) -> dict | None:
-        context = runtime.context or {}
+        thread_id = runtime.context.thread_id
-        thread_id = context.get("thread_id")
-        if thread_id is None:
-            config = get_config()
-            thread_id = config.get("configurable", {}).get("thread_id")
 
-        if thread_id is None:
+        if not thread_id:
             raise ValueError("Thread ID is required in runtime context or config.configurable")
 
         user_id = get_effective_user_id()
@@ -99,20 +93,8 @@ class ThreadDataMiddleware(AgentMiddleware[ThreadDataMiddlewareState]):
             paths = self._create_thread_directories(thread_id, user_id=user_id)
             logger.debug("Created thread data directories for thread %s", thread_id)
 
-        messages = list(state.get("messages", []))
-        last_message = messages[-1] if messages else None
-
-        if last_message and isinstance(last_message, HumanMessage):
-            messages[-1] = HumanMessage(
-                content=last_message.content,
-                id=last_message.id,
-                name=last_message.name or "user-input",
-                additional_kwargs={**last_message.additional_kwargs, "run_id": runtime.context.get("run_id"), "timestamp": datetime.now(UTC).isoformat()},
-            )
-
         return {
             "thread_data": {
                 **paths,
-            },
+            }
-            "messages": messages,
         }

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

@@ -2,21 +2,18 @@
 
 import logging
 import re
-from typing import TYPE_CHECKING, Any, NotRequired, override
+from typing import Any, NotRequired, override
 
 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
 from langgraph.config import get_config
 from langgraph.runtime import Runtime
 
-from deerflow.agents.middlewares.dynamic_context_middleware import is_dynamic_context_reminder
+from deerflow.config.app_config import AppConfig
-from deerflow.config.title_config import get_title_config
+from deerflow.config.deer_flow_context import DeerFlowContext
+from deerflow.config.title_config import TitleConfig
 from deerflow.models import create_chat_model
 
-if TYPE_CHECKING:
-    from deerflow.config.app_config import AppConfig
-    from deerflow.config.title_config import TitleConfig
-
 logger = logging.getLogger(__name__)
 
 
@@ -31,18 +28,6 @@ class TitleMiddleware(AgentMiddleware[TitleMiddlewareState]):
 
     state_schema = TitleMiddlewareState
 
-    def __init__(self, *, app_config: "AppConfig | None" = None, title_config: "TitleConfig | None" = None):
-        super().__init__()
-        self._app_config = app_config
-        self._title_config = title_config
-
-    def _get_title_config(self):
-        if self._title_config is not None:
-            return self._title_config
-        if self._app_config is not None:
-            return self._app_config.title
-        return get_title_config()
-
     def _normalize_content(self, content: object) -> str:
         if isinstance(content, str):
             return content
@@ -62,14 +47,9 @@ class TitleMiddleware(AgentMiddleware[TitleMiddlewareState]):
 
         return ""
 
-    @staticmethod
+    def _should_generate_title(self, state: TitleMiddlewareState, title_config: TitleConfig) -> bool:
-    def _is_user_message_for_title(message: object) -> bool:
-        return getattr(message, "type", None) == "human" and not is_dynamic_context_reminder(message)
-
-    def _should_generate_title(self, state: TitleMiddlewareState) -> bool:
         """Check if we should generate a title for this thread."""
-        config = self._get_title_config()
+        if not title_config.enabled:
-        if not config.enabled:
             return False
 
         # Check if thread already has a title in state
@@ -82,28 +62,27 @@ class TitleMiddleware(AgentMiddleware[TitleMiddlewareState]):
             return False
 
         # Count user and assistant messages
-        user_messages = [m for m in messages if self._is_user_message_for_title(m)]
+        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]:
+    def _build_title_prompt(self, state: TitleMiddlewareState, title_config: TitleConfig) -> tuple[str, str]:
         """Extract user/assistant messages and build the title prompt.
 
         Returns (prompt_string, user_msg) so callers can use user_msg as fallback.
         """
-        config = self._get_title_config()
         messages = state.get("messages", [])
 
-        user_msg_content = next((m.content for m in messages if self._is_user_message_for_title(m)), "")
+        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._strip_think_tags(self._normalize_content(assistant_msg_content))
 
-        prompt = config.prompt_template.format(
+        prompt = title_config.prompt_template.format(
-            max_words=config.max_words,
+            max_words=title_config.max_words,
             user_msg=user_msg[:500],
             assistant_msg=assistant_msg[:500],
         )
@@ -113,17 +92,15 @@ class TitleMiddleware(AgentMiddleware[TitleMiddlewareState]):
         """Remove <think>...</think> blocks emitted by reasoning models (e.g. minimax, DeepSeek-R1)."""
         return re.sub(r"<think>[\s\S]*?</think>", "", text, flags=re.IGNORECASE).strip()
 
-    def _parse_title(self, content: object) -> str:
+    def _parse_title(self, content: object, title_config: TitleConfig) -> str:
         """Normalize model output into a clean title string."""
-        config = self._get_title_config()
         title_content = self._normalize_content(content)
         title_content = self._strip_think_tags(title_content)
         title = title_content.strip().strip('"').strip("'")
-        return title[: config.max_chars] if len(title) > config.max_chars else title
+        return title[: title_config.max_chars] if len(title) > title_config.max_chars else title
 
-    def _fallback_title(self, user_msg: str) -> str:
+    def _fallback_title(self, user_msg: str, title_config: TitleConfig) -> str:
-        config = self._get_title_config()
+        fallback_chars = min(title_config.max_chars, 50)
-        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"
@@ -139,46 +116,42 @@ class TitleMiddleware(AgentMiddleware[TitleMiddlewareState]):
         except Exception:
             parent = {}
         config = {**parent}
-        config["run_name"] = "title_agent"
         config["tags"] = [*(config.get("tags") or []), "middleware:title"]
         return config
 
-    def _generate_title_result(self, state: TitleMiddlewareState) -> dict | None:
+    def _generate_title_result(self, state: TitleMiddlewareState, title_config: TitleConfig) -> dict | None:
         """Generate a local fallback title without blocking on an LLM call."""
-        if not self._should_generate_title(state):
+        if not self._should_generate_title(state, title_config):
             return None
 
-        _, user_msg = self._build_title_prompt(state)
+        _, user_msg = self._build_title_prompt(state, title_config)
-        return {"title": self._fallback_title(user_msg)}
+        return {"title": self._fallback_title(user_msg, title_config)}
 
-    async def _agenerate_title_result(self, state: TitleMiddlewareState) -> dict | None:
+    async def _agenerate_title_result(self, state: TitleMiddlewareState, app_config: AppConfig) -> dict | None:
         """Generate a title asynchronously and fall back locally on failure."""
-        if not self._should_generate_title(state):
+        title_config = app_config.title
+        if not self._should_generate_title(state, title_config):
             return None
 
-        config = self._get_title_config()
+        prompt, user_msg = self._build_title_prompt(state, title_config)
-        prompt, user_msg = self._build_title_prompt(state)
 
         try:
-            model_kwargs = {"thinking_enabled": False}
+            if title_config.model_name:
-            if self._app_config is not None:
+                model = create_chat_model(name=title_config.model_name, thinking_enabled=False, app_config=app_config)
-                model_kwargs["app_config"] = self._app_config
-            if config.model_name:
-                model = create_chat_model(name=config.model_name, **model_kwargs)
             else:
-                model = create_chat_model(**model_kwargs)
+                model = create_chat_model(thinking_enabled=False, app_config=app_config)
             response = await model.ainvoke(prompt, config=self._get_runnable_config())
-            title = self._parse_title(response.content)
+            title = self._parse_title(response.content, title_config)
             if title:
                 return {"title": title}
         except Exception:
             logger.debug("Failed to generate async title; falling back to local title", exc_info=True)
-        return {"title": self._fallback_title(user_msg)}
+        return {"title": self._fallback_title(user_msg, title_config)}
 
     @override
-    def after_model(self, state: TitleMiddlewareState, runtime: Runtime) -> dict | None:
+    def after_model(self, state: TitleMiddlewareState, runtime: Runtime[DeerFlowContext]) -> dict | None:
-        return self._generate_title_result(state)
+        return self._generate_title_result(state, runtime.context.app_config.title)
 
     @override
-    async def aafter_model(self, state: TitleMiddlewareState, runtime: Runtime) -> dict | None:
+    async def aafter_model(self, state: TitleMiddlewareState, runtime: Runtime[DeerFlowContext]) -> dict | None:
-        return await self._agenerate_title_result(state)
+        return await self._agenerate_title_result(state, runtime.context.app_config)

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

@@ -1,303 +1,37 @@
-"""Middleware for logging token usage and annotating step attribution."""
+"""Middleware for logging LLM token usage."""
-
-from __future__ import annotations
 
 import logging
-from collections import defaultdict
+from typing import override
-from typing import Any, override
 
 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
-from langchain.agents.middleware.todo import Todo
-from langchain_core.messages import AIMessage
 from langgraph.runtime import Runtime
 
 logger = logging.getLogger(__name__)
 
-TOKEN_USAGE_ATTRIBUTION_KEY = "token_usage_attribution"
-
-
-def _string_arg(value: Any) -> str | None:
-    if isinstance(value, str):
-        normalized = value.strip()
-        return normalized or None
-    return None
-
-
-def _normalize_todos(value: Any) -> list[Todo]:
-    if not isinstance(value, list):
-        return []
-
-    normalized: list[Todo] = []
-    for item in value:
-        if not isinstance(item, dict):
-            continue
-
-        todo: Todo = {}
-        content = _string_arg(item.get("content"))
-        status = item.get("status")
-
-        if content is not None:
-            todo["content"] = content
-        if status in {"pending", "in_progress", "completed"}:
-            todo["status"] = status
-
-        normalized.append(todo)
-
-    return normalized
-
-
-def _todo_action_kind(previous: Todo | None, current: Todo) -> str:
-    status = current.get("status")
-    previous_content = previous.get("content") if previous else None
-    current_content = current.get("content")
-
-    if previous is None:
-        if status == "completed":
-            return "todo_complete"
-        if status == "in_progress":
-            return "todo_start"
-        return "todo_update"
-
-    if previous_content != current_content:
-        return "todo_update"
-
-    if status == "completed":
-        return "todo_complete"
-    if status == "in_progress":
-        return "todo_start"
-    return "todo_update"
-
-
-def _build_todo_actions(previous_todos: list[Todo], next_todos: list[Todo]) -> list[dict[str, Any]]:
-    # This is the single source of truth for precise write_todos token
-    # attribution. The frontend intentionally falls back to a generic
-    # "Update to-do list" label when this metadata is missing or malformed.
-    previous_by_content: dict[str, list[tuple[int, Todo]]] = defaultdict(list)
-    matched_previous_indices: set[int] = set()
-
-    for index, todo in enumerate(previous_todos):
-        content = todo.get("content")
-        if isinstance(content, str) and content:
-            previous_by_content[content].append((index, todo))
-
-    actions: list[dict[str, Any]] = []
-
-    for index, todo in enumerate(next_todos):
-        content = todo.get("content")
-        if not isinstance(content, str) or not content:
-            continue
-
-        previous_match: Todo | None = None
-        content_matches = previous_by_content.get(content)
-        if content_matches:
-            while content_matches and content_matches[0][0] in matched_previous_indices:
-                content_matches.pop(0)
-            if content_matches:
-                previous_index, previous_match = content_matches.pop(0)
-                matched_previous_indices.add(previous_index)
-
-        if previous_match is None and index < len(previous_todos) and index not in matched_previous_indices:
-            previous_match = previous_todos[index]
-            matched_previous_indices.add(index)
-
-        if previous_match is not None:
-            previous_content = previous_match.get("content")
-            previous_status = previous_match.get("status")
-            if previous_content == content and previous_status == todo.get("status"):
-                continue
-
-        actions.append(
-            {
-                "kind": _todo_action_kind(previous_match, todo),
-                "content": content,
-            }
-        )
-
-    for index, todo in enumerate(previous_todos):
-        if index in matched_previous_indices:
-            continue
-
-        content = todo.get("content")
-        if not isinstance(content, str) or not content:
-            continue
-
-        actions.append(
-            {
-                "kind": "todo_remove",
-                "content": content,
-            }
-        )
-
-    return actions
-
-
-def _describe_tool_call(tool_call: dict[str, Any], todos: list[Todo]) -> list[dict[str, Any]]:
-    name = _string_arg(tool_call.get("name")) or "unknown"
-    args = tool_call.get("args") if isinstance(tool_call.get("args"), dict) else {}
-    tool_call_id = _string_arg(tool_call.get("id"))
-
-    if name == "write_todos":
-        next_todos = _normalize_todos(args.get("todos"))
-        actions = _build_todo_actions(todos, next_todos)
-        if not actions:
-            return [
-                {
-                    "kind": "tool",
-                    "tool_name": name,
-                    "tool_call_id": tool_call_id,
-                }
-            ]
-        return [
-            {
-                **action,
-                "tool_call_id": tool_call_id,
-            }
-            for action in actions
-        ]
-
-    if name == "task":
-        return [
-            {
-                "kind": "subagent",
-                "description": _string_arg(args.get("description")),
-                "subagent_type": _string_arg(args.get("subagent_type")),
-                "tool_call_id": tool_call_id,
-            }
-        ]
-
-    if name in {"web_search", "image_search"}:
-        query = _string_arg(args.get("query"))
-        return [
-            {
-                "kind": "search",
-                "tool_name": name,
-                "query": query,
-                "tool_call_id": tool_call_id,
-            }
-        ]
-
-    if name == "present_files":
-        return [
-            {
-                "kind": "present_files",
-                "tool_call_id": tool_call_id,
-            }
-        ]
-
-    if name == "ask_clarification":
-        return [
-            {
-                "kind": "clarification",
-                "tool_call_id": tool_call_id,
-            }
-        ]
-
-    return [
-        {
-            "kind": "tool",
-            "tool_name": name,
-            "description": _string_arg(args.get("description")),
-            "tool_call_id": tool_call_id,
-        }
-    ]
-
-
-def _infer_step_kind(message: AIMessage, actions: list[dict[str, Any]]) -> str:
-    if actions:
-        first_kind = actions[0].get("kind")
-        if len(actions) == 1 and first_kind in {"todo_start", "todo_complete", "todo_update", "todo_remove"}:
-            return "todo_update"
-        if len(actions) == 1 and first_kind == "subagent":
-            return "subagent_dispatch"
-        return "tool_batch"
-
-    if message.content:
-        return "final_answer"
-    return "thinking"
-
-
-def _build_attribution(message: AIMessage, todos: list[Todo]) -> dict[str, Any]:
-    tool_calls = getattr(message, "tool_calls", None) or []
-    actions: list[dict[str, Any]] = []
-    current_todos = list(todos)
-
-    for raw_tool_call in tool_calls:
-        if not isinstance(raw_tool_call, dict):
-            continue
-
-        described_actions = _describe_tool_call(raw_tool_call, current_todos)
-        actions.extend(described_actions)
-
-        if raw_tool_call.get("name") == "write_todos":
-            args = raw_tool_call.get("args") if isinstance(raw_tool_call.get("args"), dict) else {}
-            current_todos = _normalize_todos(args.get("todos"))
-
-    tool_call_ids: list[str] = []
-    for tool_call in tool_calls:
-        if not isinstance(tool_call, dict):
-            continue
-
-        tool_call_id = _string_arg(tool_call.get("id"))
-        if tool_call_id is not None:
-            tool_call_ids.append(tool_call_id)
-
-    return {
-        # Schema changes should remain additive where possible so older
-        # frontends can ignore unknown fields and fall back safely.
-        "version": 1,
-        "kind": _infer_step_kind(message, actions),
-        "shared_attribution": len(actions) > 1,
-        "tool_call_ids": tool_call_ids,
-        "actions": actions,
-    }
-
 
 class TokenUsageMiddleware(AgentMiddleware):
-    """Logs token usage from model responses and annotates the AI step."""
+    """Logs token usage from model response usage_metadata."""
-
-    def _apply(self, state: AgentState) -> dict | None:
-        messages = state.get("messages", [])
-        if not messages:
-            return None
-
-        last = messages[-1]
-        if not isinstance(last, AIMessage):
-            return None
-
-        usage = getattr(last, "usage_metadata", None)
-        if usage:
-            input_token_details = usage.get("input_token_details") or {}
-            output_token_details = usage.get("output_token_details") or {}
-            detail_parts = []
-            if input_token_details:
-                detail_parts.append(f"input_token_details={input_token_details}")
-            if output_token_details:
-                detail_parts.append(f"output_token_details={output_token_details}")
-            detail_suffix = f" {' '.join(detail_parts)}" if detail_parts else ""
-            logger.info(
-                "LLM token usage: input=%s output=%s total=%s%s",
-                usage.get("input_tokens", "?"),
-                usage.get("output_tokens", "?"),
-                usage.get("total_tokens", "?"),
-                detail_suffix,
-            )
-
-        todos = state.get("todos") or []
-        attribution = _build_attribution(last, todos if isinstance(todos, list) else [])
-        additional_kwargs = dict(getattr(last, "additional_kwargs", {}) or {})
-
-        if additional_kwargs.get(TOKEN_USAGE_ATTRIBUTION_KEY) == attribution:
-            return None
-
-        additional_kwargs[TOKEN_USAGE_ATTRIBUTION_KEY] = attribution
-        updated_msg = last.model_copy(update={"additional_kwargs": additional_kwargs})
-        return {"messages": [updated_msg]}
 
     @override
     def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
-        return self._apply(state)
+        return self._log_usage(state)
 
     @override
     async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict | None:
-        return self._apply(state)
+        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_call_metadata.py

@@ -1,50 +0,0 @@
-"""Helpers for keeping AIMessage tool-call metadata consistent."""
-
-from __future__ import annotations
-
-from typing import Any
-
-from langchain_core.messages import AIMessage
-
-
-def _raw_tool_call_id(raw_tool_call: Any) -> str | None:
-    if not isinstance(raw_tool_call, dict):
-        return None
-
-    raw_id = raw_tool_call.get("id")
-    return raw_id if isinstance(raw_id, str) and raw_id else None
-
-
-def clone_ai_message_with_tool_calls(
-    message: AIMessage,
-    tool_calls: list[dict[str, Any]],
-    *,
-    content: Any | None = None,
-) -> AIMessage:
-    """Clone an AIMessage while keeping raw provider tool-call metadata in sync."""
-    kept_ids = {tc["id"] for tc in tool_calls if isinstance(tc.get("id"), str) and tc["id"]}
-
-    update: dict[str, Any] = {"tool_calls": tool_calls}
-    if content is not None:
-        update["content"] = content
-
-    additional_kwargs = dict(getattr(message, "additional_kwargs", {}) or {})
-    raw_tool_calls = additional_kwargs.get("tool_calls")
-    if isinstance(raw_tool_calls, list):
-        synced_raw_tool_calls = [raw_tc for raw_tc in raw_tool_calls if _raw_tool_call_id(raw_tc) in kept_ids]
-        if synced_raw_tool_calls:
-            additional_kwargs["tool_calls"] = synced_raw_tool_calls
-        else:
-            additional_kwargs.pop("tool_calls", None)
-
-    if not tool_calls:
-        additional_kwargs.pop("function_call", None)
-
-    update["additional_kwargs"] = additional_kwargs
-
-    response_metadata = dict(getattr(message, "response_metadata", {}) or {})
-    if not tool_calls and response_metadata.get("finish_reason") == "tool_calls":
-        response_metadata["finish_reason"] = "stop"
-    update["response_metadata"] = response_metadata
-
-    return message.model_copy(update=update)

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

@@ -1,8 +1,10 @@
 """Tool error handling middleware and shared runtime middleware builders."""
 
+from __future__ import annotations
+
 import logging
 from collections.abc import Awaitable, Callable
-from typing import override
+from typing import TYPE_CHECKING, override
 
 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
@@ -11,7 +13,8 @@ from langgraph.errors import GraphBubbleUp
 from langgraph.prebuilt.tool_node import ToolCallRequest
 from langgraph.types import Command
 
-from deerflow.config.app_config import AppConfig
+if TYPE_CHECKING:
+    from deerflow.config.app_config import AppConfig
 
 logger = logging.getLogger(__name__)
 
@@ -69,7 +72,7 @@ class ToolErrorHandlingMiddleware(AgentMiddleware[AgentState]):
 
 def _build_runtime_middlewares(
     *,
-    app_config: AppConfig,
+    app_config: "AppConfig",
     include_uploads: bool,
     include_dangling_tool_call_patch: bool,
     lazy_init: bool = True,
@@ -94,7 +97,7 @@ def _build_runtime_middlewares(
 
         middlewares.append(DanglingToolCallMiddleware())
 
-    middlewares.append(LLMErrorHandlingMiddleware(app_config=app_config))
+    middlewares.append(LLMErrorHandlingMiddleware())
 
     # Guardrail middleware (if configured)
     guardrails_config = app_config.guardrails
@@ -126,7 +129,7 @@ def _build_runtime_middlewares(
     return middlewares
 
 
-def build_lead_runtime_middlewares(*, app_config: AppConfig, lazy_init: bool = True) -> list[AgentMiddleware]:
+def build_lead_runtime_middlewares(*, app_config: "AppConfig", lazy_init: bool = True) -> list[AgentMiddleware]:
     """Middlewares shared by lead agent runtime before lead-only middlewares."""
     return _build_runtime_middlewares(
         app_config=app_config,
@@ -136,32 +139,10 @@ def build_lead_runtime_middlewares(*, app_config: AppConfig, lazy_init: bool = T
     )
 
 
-def build_subagent_runtime_middlewares(
+def build_subagent_runtime_middlewares(*, lazy_init: bool = True) -> list[AgentMiddleware]:
-    *,
-    app_config: AppConfig | None = None,
-    model_name: str | None = None,
-    lazy_init: bool = True,
-) -> list[AgentMiddleware]:
     """Middlewares shared by subagent runtime before subagent-only middlewares."""
-    if app_config is None:
+    return _build_runtime_middlewares(
-        from deerflow.config import get_app_config
-
-        app_config = get_app_config()
-
-    middlewares = _build_runtime_middlewares(
-        app_config=app_config,
         include_uploads=False,
         include_dangling_tool_call_patch=True,
         lazy_init=lazy_init,
     )
-
-    if model_name is None and app_config.models:
-        model_name = app_config.models[0].name
-
-    model_config = app_config.get_model_config(model_name) if model_name else None
-    if model_config is not None and model_config.supports_vision:
-        from deerflow.agents.middlewares.view_image_middleware import ViewImageMiddleware
-
-        middlewares.append(ViewImageMiddleware())
-
-    return middlewares

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

@@ -9,6 +9,7 @@ from langchain.agents.middleware import AgentMiddleware
 from langchain_core.messages import HumanMessage
 from langgraph.runtime import Runtime
 
+from deerflow.config.deer_flow_context import DeerFlowContext
 from deerflow.config.paths import Paths, get_paths
 from deerflow.runtime.user_context import get_effective_user_id
 from deerflow.utils.file_conversion import extract_outline
@@ -185,7 +186,7 @@ class UploadsMiddleware(AgentMiddleware[UploadsMiddlewareState]):
         return files if files else None
 
     @override
-    def before_agent(self, state: UploadsMiddlewareState, runtime: Runtime) -> dict | None:
+    def before_agent(self, state: UploadsMiddlewareState, runtime: Runtime[DeerFlowContext]) -> dict | None:
         """Inject uploaded files information before agent execution.
 
         New files come from the current message's additional_kwargs.files.
@@ -214,14 +215,7 @@ class UploadsMiddleware(AgentMiddleware[UploadsMiddlewareState]):
             return None
 
         # Resolve uploads directory for existence checks
-        thread_id = (runtime.context or {}).get("thread_id")
+        thread_id = runtime.context.thread_id
-        if thread_id is None:
-            try:
-                from langgraph.config import get_config
-
-                thread_id = get_config().get("configurable", {}).get("thread_id")
-            except RuntimeError:
-                pass  # get_config() raises outside a runnable context (e.g. unit tests)
         uploads_dir = self._paths.sandbox_uploads_dir(thread_id, user_id=get_effective_user_id()) if thread_id else None
 
         # Get newly uploaded files from the current message's additional_kwargs.files
@@ -283,7 +277,6 @@ class UploadsMiddleware(AgentMiddleware[UploadsMiddlewareState]):
         updated_message = HumanMessage(
             content=updated_content,
             id=last_message.id,
-            name=last_message.name,
             additional_kwargs=last_message.additional_kwargs,
         )
 

backend/packages/harness/deerflow/client.py

@@ -36,12 +36,13 @@ from deerflow.agents.lead_agent.agent import _build_middlewares
 from deerflow.agents.lead_agent.prompt import apply_prompt_template
 from deerflow.agents.thread_state import ThreadState
 from deerflow.config.agents_config import AGENT_NAME_PATTERN
-from deerflow.config.app_config import get_app_config, reload_app_config
+from deerflow.config.app_config import AppConfig
-from deerflow.config.extensions_config import ExtensionsConfig, SkillStateConfig, get_extensions_config, reload_extensions_config
+from deerflow.config.deer_flow_context import DeerFlowContext
+from deerflow.config.extensions_config import ExtensionsConfig
 from deerflow.config.paths import get_paths
 from deerflow.models import create_chat_model
 from deerflow.runtime.user_context import get_effective_user_id
-from deerflow.skills.storage import get_or_new_skill_storage
+from deerflow.skills.installer import install_skill_from_archive
 from deerflow.uploads.manager import (
     claim_unique_filename,
     delete_file_safe,
@@ -116,6 +117,7 @@ class DeerFlowClient:
         config_path: str | None = None,
         checkpointer=None,
         *,
+        config: AppConfig | None = None,
         model_name: str | None = None,
         thinking_enabled: bool = True,
         subagent_enabled: bool = False,
@@ -130,9 +132,14 @@ class DeerFlowClient:
 
         Args:
             config_path: Path to config.yaml. Uses default resolution if None.
+                Ignored when ``config`` is provided.
             checkpointer: LangGraph checkpointer instance for state persistence.
                 Required for multi-turn conversations on the same thread_id.
                 Without a checkpointer, each call is stateless.
+            config: Optional pre-constructed AppConfig. When provided, it takes
+                precedence over ``config_path`` and no file is read. Enables
+                multi-client isolation: two clients with different configs can
+                coexist in the same process without touching process-global state.
             model_name: Override the default model name from config.
             thinking_enabled: Enable model's extended thinking.
             subagent_enabled: Enable subagent delegation.
@@ -141,9 +148,18 @@ class DeerFlowClient:
             available_skills: Optional set of skill names to make available. If None (default), all scanned skills are available.
             middlewares: Optional list of custom middlewares to inject into the agent.
         """
-        if config_path is not None:
+        # Constructor-captured config: the client owns its AppConfig for its lifetime.
-            reload_app_config(config_path)
+        # Multiple clients with different configs do not contend.
-        self._app_config = get_app_config()
+        #
+        # Priority: explicit ``config=`` > explicit ``config_path=`` > ``AppConfig.from_file()``
+        # with default path resolution. There is no ambient global fallback; if
+        # config.yaml cannot be located, ``from_file`` raises loudly.
+        if config is not None:
+            self._app_config = config
+        elif config_path is not None:
+            self._app_config = AppConfig.from_file(config_path)
+        else:
+            self._app_config = AppConfig.from_file()
 
         if agent_name is not None and not AGENT_NAME_PATTERN.match(agent_name):
             raise ValueError(f"Invalid agent name '{agent_name}'. Must match pattern: {AGENT_NAME_PATTERN.pattern}")
@@ -171,6 +187,15 @@ class DeerFlowClient:
         self._agent = None
         self._agent_config_key = None
 
+    def _reload_config(self) -> None:
+        """Reload config from file and refresh the cached reference.
+
+        Only the client's own ``_app_config`` is rebuilt. Other clients
+        and the process-global are untouched, so multi-client coexistence
+        survives reload.
+        """
+        self._app_config = AppConfig.from_file()
+
     # ------------------------------------------------------------------
     # Internal helpers
     # ------------------------------------------------------------------
@@ -228,10 +253,11 @@ class DeerFlowClient:
         max_concurrent_subagents = cfg.get("max_concurrent_subagents", 3)
 
         kwargs: dict[str, Any] = {
-            "model": create_chat_model(name=model_name, thinking_enabled=thinking_enabled),
+            "model": create_chat_model(name=model_name, thinking_enabled=thinking_enabled, app_config=self._app_config),
             "tools": self._get_tools(model_name=model_name, subagent_enabled=subagent_enabled),
-            "middleware": _build_middlewares(config, model_name=model_name, agent_name=self._agent_name, custom_middlewares=self._middlewares),
+            "middleware": _build_middlewares(self._app_config, config, model_name=model_name, agent_name=self._agent_name, custom_middlewares=self._middlewares),
             "system_prompt": apply_prompt_template(
+                self._app_config,
                 subagent_enabled=subagent_enabled,
                 max_concurrent_subagents=max_concurrent_subagents,
                 agent_name=self._agent_name,
@@ -243,7 +269,7 @@ class DeerFlowClient:
         if checkpointer is None:
             from deerflow.runtime.checkpointer import get_checkpointer
 
-            checkpointer = get_checkpointer()
+            checkpointer = get_checkpointer(self._app_config)
         if checkpointer is not None:
             kwargs["checkpointer"] = checkpointer
 
@@ -251,12 +277,11 @@ class DeerFlowClient:
         self._agent_config_key = key
         logger.info("Agent created: agent_name=%s, model=%s, thinking=%s", self._agent_name, model_name, thinking_enabled)
 
-    @staticmethod
+    def _get_tools(self, *, model_name: str | None, subagent_enabled: bool):
-    def _get_tools(*, model_name: str | None, subagent_enabled: bool):
         """Lazy import to avoid circular dependency at module level."""
         from deerflow.tools import get_available_tools
 
-        return get_available_tools(model_name=model_name, subagent_enabled=subagent_enabled)
+        return get_available_tools(model_name=model_name, subagent_enabled=subagent_enabled, app_config=self._app_config)
 
     @staticmethod
     def _serialize_tool_calls(tool_calls) -> list[dict]:
@@ -264,35 +289,25 @@ class DeerFlowClient:
         return [{"name": tc["name"], "args": tc["args"], "id": tc.get("id")} for tc in tool_calls]
 
     @staticmethod
-    def _serialize_additional_kwargs(msg) -> dict[str, Any] | None:
+    def _ai_text_event(msg_id: str | None, text: str, usage: dict | None) -> "StreamEvent":
-        """Copy message additional_kwargs when present."""
+        """Build a ``messages-tuple`` AI text event, attaching usage when present."""
-        additional_kwargs = getattr(msg, "additional_kwargs", None)
-        if isinstance(additional_kwargs, dict) and additional_kwargs:
-            return dict(additional_kwargs)
-        return None
-
-    @staticmethod
-    def _ai_text_event(msg_id: str | None, text: str, usage: dict | None, additional_kwargs: dict[str, Any] | None = None) -> "StreamEvent":
-        """Build a ``messages-tuple`` AI text event."""
         data: dict[str, Any] = {"type": "ai", "content": text, "id": msg_id}
         if usage:
             data["usage_metadata"] = usage
-        if additional_kwargs:
-            data["additional_kwargs"] = additional_kwargs
         return StreamEvent(type="messages-tuple", data=data)
 
     @staticmethod
-    def _ai_tool_calls_event(msg_id: str | None, tool_calls, additional_kwargs: dict[str, Any] | None = None) -> "StreamEvent":
+    def _ai_tool_calls_event(msg_id: str | None, tool_calls) -> "StreamEvent":
         """Build a ``messages-tuple`` AI tool-calls event."""
-        data: dict[str, Any] = {
+        return StreamEvent(
-            "type": "ai",
+            type="messages-tuple",
-            "content": "",
+            data={
-            "id": msg_id,
+                "type": "ai",
-            "tool_calls": DeerFlowClient._serialize_tool_calls(tool_calls),
+                "content": "",
-        }
+                "id": msg_id,
-        if additional_kwargs:
+                "tool_calls": DeerFlowClient._serialize_tool_calls(tool_calls),
-            data["additional_kwargs"] = additional_kwargs
+            },
-        return StreamEvent(type="messages-tuple", data=data)
+        )
 
     @staticmethod
     def _tool_message_event(msg: ToolMessage) -> "StreamEvent":
@@ -317,30 +332,19 @@ class DeerFlowClient:
                 d["tool_calls"] = DeerFlowClient._serialize_tool_calls(msg.tool_calls)
             if getattr(msg, "usage_metadata", None):
                 d["usage_metadata"] = msg.usage_metadata
-            if additional_kwargs := DeerFlowClient._serialize_additional_kwargs(msg):
-                d["additional_kwargs"] = additional_kwargs
             return d
         if isinstance(msg, ToolMessage):
-            d = {
+            return {
                 "type": "tool",
                 "content": DeerFlowClient._extract_text(msg.content),
                 "name": getattr(msg, "name", None),
                 "tool_call_id": getattr(msg, "tool_call_id", None),
                 "id": getattr(msg, "id", None),
             }
-            if additional_kwargs := DeerFlowClient._serialize_additional_kwargs(msg):
-                d["additional_kwargs"] = additional_kwargs
-            return d
         if isinstance(msg, HumanMessage):
-            d = {"type": "human", "content": msg.content, "id": getattr(msg, "id", None)}
+            return {"type": "human", "content": msg.content, "id": getattr(msg, "id", None)}
-            if additional_kwargs := DeerFlowClient._serialize_additional_kwargs(msg):
-                d["additional_kwargs"] = additional_kwargs
-            return d
         if isinstance(msg, SystemMessage):
-            d = {"type": "system", "content": msg.content, "id": getattr(msg, "id", None)}
+            return {"type": "system", "content": msg.content, "id": getattr(msg, "id", None)}
-            if additional_kwargs := DeerFlowClient._serialize_additional_kwargs(msg):
-                d["additional_kwargs"] = additional_kwargs
-            return d
         return {"type": "unknown", "content": str(msg), "id": getattr(msg, "id", None)}
 
     @staticmethod
@@ -398,7 +402,7 @@ class DeerFlowClient:
         if checkpointer is None:
             from deerflow.runtime.checkpointer.provider import get_checkpointer
 
-            checkpointer = get_checkpointer()
+            checkpointer = get_checkpointer(self._app_config)
 
         thread_info_map = {}
 
@@ -453,7 +457,7 @@ class DeerFlowClient:
         if checkpointer is None:
             from deerflow.runtime.checkpointer.provider import get_checkpointer
 
-            checkpointer = get_checkpointer()
+            checkpointer = get_checkpointer(self._app_config)
 
         config = {"configurable": {"thread_id": thread_id}}
         checkpoints = []
@@ -563,7 +567,6 @@ class DeerFlowClient:
             - type="messages-tuple"  data={"type": "ai", "content": <delta>, "id": str}
             - type="messages-tuple"  data={"type": "ai", "content": <delta>, "id": str, "usage_metadata": {...}}
             - type="messages-tuple"  data={"type": "ai", "content": "", "id": str, "tool_calls": [...]}
-            - type="messages-tuple"  data={"type": "ai", "content": "", "id": str, "additional_kwargs": {...}}
             - type="messages-tuple"  data={"type": "tool", "content": str, "name": str, "tool_call_id": str, "id": str}
             - type="end"             data={"usage": {"input_tokens": int, "output_tokens": int, "total_tokens": int}}
         """
@@ -574,9 +577,7 @@ class DeerFlowClient:
         self._ensure_agent(config)
 
         state: dict[str, Any] = {"messages": [HumanMessage(content=message)]}
-        context = {"thread_id": thread_id}
+        context = DeerFlowContext(app_config=self._app_config, thread_id=thread_id, agent_name=self._agent_name)
-        if self._agent_name:
-            context["agent_name"] = self._agent_name
 
         seen_ids: set[str] = set()
         # Cross-mode handoff: ids already streamed via LangGraph ``messages``
@@ -586,7 +587,6 @@ class DeerFlowClient:
         # in both the final ``messages`` chunk and the values snapshot —
         # count it only on whichever arrives first.
         counted_usage_ids: set[str] = set()
-        sent_additional_kwargs_by_id: dict[str, dict[str, Any]] = {}
         cumulative_usage: dict[str, int] = {"input_tokens": 0, "output_tokens": 0, "total_tokens": 0}
 
         def _account_usage(msg_id: str | None, usage: Any) -> dict | None:
@@ -616,20 +616,6 @@ class DeerFlowClient:
                 "total_tokens": total_tokens,
             }
 
-        def _unsent_additional_kwargs(msg_id: str | None, additional_kwargs: dict[str, Any] | None) -> dict[str, Any] | None:
-            if not additional_kwargs:
-                return None
-            if not msg_id:
-                return additional_kwargs
-
-            sent = sent_additional_kwargs_by_id.setdefault(msg_id, {})
-            delta = {key: value for key, value in additional_kwargs.items() if sent.get(key) != value}
-            if not delta:
-                return None
-
-            sent.update(delta)
-            return delta
-
         for item in self._agent.stream(
             state,
             config=config,
@@ -657,31 +643,17 @@ class DeerFlowClient:
 
                 if isinstance(msg_chunk, AIMessage):
                     text = self._extract_text(msg_chunk.content)
-                    additional_kwargs = self._serialize_additional_kwargs(msg_chunk)
                     counted_usage = _account_usage(msg_id, msg_chunk.usage_metadata)
-                    sent_additional_kwargs = False
 
                     if text:
                         if msg_id:
                             streamed_ids.add(msg_id)
-                        additional_kwargs_delta = _unsent_additional_kwargs(msg_id, additional_kwargs)
+                        yield self._ai_text_event(msg_id, text, counted_usage)
-                        yield self._ai_text_event(
-                            msg_id,
-                            text,
-                            counted_usage,
-                            additional_kwargs_delta,
-                        )
-                        sent_additional_kwargs = bool(additional_kwargs_delta)
 
                     if msg_chunk.tool_calls:
                         if msg_id:
                             streamed_ids.add(msg_id)
-                        additional_kwargs_delta = None if sent_additional_kwargs else _unsent_additional_kwargs(msg_id, additional_kwargs)
+                        yield self._ai_tool_calls_event(msg_id, msg_chunk.tool_calls)
-                        yield self._ai_tool_calls_event(
-                            msg_id,
-                            msg_chunk.tool_calls,
-                            additional_kwargs_delta,
-                        )
 
                 elif isinstance(msg_chunk, ToolMessage):
                     if msg_id:
@@ -704,45 +676,17 @@ class DeerFlowClient:
                 if msg_id and msg_id in streamed_ids:
                     if isinstance(msg, AIMessage):
                         _account_usage(msg_id, getattr(msg, "usage_metadata", None))
-                        additional_kwargs = self._serialize_additional_kwargs(msg)
-                        additional_kwargs_delta = _unsent_additional_kwargs(msg_id, additional_kwargs)
-                        if additional_kwargs_delta:
-                            # Metadata-only follow-up: ``messages-tuple`` has no
-                            # dedicated attribution event, so clients should
-                            # merge this empty-content AI event by message id
-                            # and ignore it for text rendering.
-                            yield self._ai_text_event(msg_id, "", None, additional_kwargs_delta)
                     continue
 
                 if isinstance(msg, AIMessage):
                     counted_usage = _account_usage(msg_id, msg.usage_metadata)
-                    additional_kwargs = self._serialize_additional_kwargs(msg)
-                    sent_additional_kwargs = False
 
                     if msg.tool_calls:
-                        additional_kwargs_delta = _unsent_additional_kwargs(msg_id, additional_kwargs)
+                        yield self._ai_tool_calls_event(msg_id, msg.tool_calls)
-                        yield self._ai_tool_calls_event(
-                            msg_id,
-                            msg.tool_calls,
-                            additional_kwargs_delta,
-                        )
-                        sent_additional_kwargs = bool(additional_kwargs_delta)
 
                     text = self._extract_text(msg.content)
                     if text:
-                        additional_kwargs_delta = None if sent_additional_kwargs else _unsent_additional_kwargs(msg_id, additional_kwargs)
+                        yield self._ai_text_event(msg_id, text, counted_usage)
-                        yield self._ai_text_event(
-                            msg_id,
-                            text,
-                            counted_usage,
-                            additional_kwargs_delta,
-                        )
-                    elif msg_id:
-                        additional_kwargs_delta = None if sent_additional_kwargs else _unsent_additional_kwargs(msg_id, additional_kwargs)
-                        if not additional_kwargs_delta:
-                            continue
-                        # See the metadata-only follow-up convention above.
-                        yield self._ai_text_event(msg_id, "", None, additional_kwargs_delta)
 
                 elif isinstance(msg, ToolMessage):
                     yield self._tool_message_event(msg)
@@ -831,6 +775,8 @@ class DeerFlowClient:
             Dict with "skills" key containing list of skill info dicts,
             matching the Gateway API ``SkillsListResponse`` schema.
         """
+        from deerflow.skills.loader import load_skills
+
         return {
             "skills": [
                 {
@@ -840,7 +786,7 @@ class DeerFlowClient:
                     "category": s.category,
                     "enabled": s.enabled,
                 }
-                for s in get_or_new_skill_storage().load_skills(enabled_only=enabled_only)
+                for s in load_skills(self._app_config, enabled_only=enabled_only)
             ]
         }
 
@@ -852,19 +798,19 @@ class DeerFlowClient:
         """
         from deerflow.agents.memory.updater import get_memory_data
 
-        return get_memory_data(user_id=get_effective_user_id())
+        return get_memory_data(self._app_config.memory, user_id=get_effective_user_id())
 
     def export_memory(self) -> dict:
         """Export current memory data for backup or transfer."""
         from deerflow.agents.memory.updater import get_memory_data
 
-        return get_memory_data(user_id=get_effective_user_id())
+        return get_memory_data(self._app_config.memory, user_id=get_effective_user_id())
 
     def import_memory(self, memory_data: dict) -> dict:
         """Import and persist full memory data."""
         from deerflow.agents.memory.updater import import_memory_data
 
-        return import_memory_data(memory_data, user_id=get_effective_user_id())
+        return import_memory_data(self._app_config.memory, memory_data, user_id=get_effective_user_id())
 
     def get_model(self, name: str) -> dict | None:
         """Get a specific model's configuration by name.
@@ -899,8 +845,8 @@ class DeerFlowClient:
             Dict with "mcp_servers" key mapping server name to config,
             matching the Gateway API ``McpConfigResponse`` schema.
         """
-        config = get_extensions_config()
+        ext = self._app_config.extensions
-        return {"mcp_servers": {name: server.model_dump() for name, server in config.mcp_servers.items()}}
+        return {"mcp_servers": {name: server.model_dump() for name, server in ext.mcp_servers.items()}}
 
     def update_mcp_config(self, mcp_servers: dict[str, dict]) -> dict:
         """Update MCP server configurations.
@@ -922,18 +868,19 @@ class DeerFlowClient:
         if config_path is None:
             raise FileNotFoundError("Cannot locate extensions_config.json. Set DEER_FLOW_EXTENSIONS_CONFIG_PATH or ensure it exists in the project root.")
 
-        current_config = get_extensions_config()
+        current_ext = self._app_config.extensions
 
         config_data = {
             "mcpServers": mcp_servers,
-            "skills": {name: {"enabled": skill.enabled} for name, skill in current_config.skills.items()},
+            "skills": {name: {"enabled": skill.enabled} for name, skill in current_ext.skills.items()},
         }
 
         self._atomic_write_json(config_path, config_data)
 
         self._agent = None
         self._agent_config_key = None
-        reloaded = reload_extensions_config()
+        self._reload_config()
+        reloaded = self._app_config.extensions
         return {"mcp_servers": {name: server.model_dump() for name, server in reloaded.mcp_servers.items()}}
 
     # ------------------------------------------------------------------
@@ -949,9 +896,9 @@ class DeerFlowClient:
         Returns:
             Skill info dict, or None if not found.
         """
-        from deerflow.skills.storage import get_or_new_skill_storage
+        from deerflow.skills.loader import load_skills
 
-        skill = next((s for s in get_or_new_skill_storage().load_skills(enabled_only=False) if s.name == name), None)
+        skill = next((s for s in load_skills(self._app_config, enabled_only=False) if s.name == name), None)
         if skill is None:
             return None
         return {
@@ -976,9 +923,9 @@ class DeerFlowClient:
             ValueError: If the skill is not found.
             OSError: If the config file cannot be written.
         """
-        from deerflow.skills.storage import get_or_new_skill_storage
+        from deerflow.skills.loader import load_skills
 
-        skills = get_or_new_skill_storage().load_skills(enabled_only=False)
+        skills = load_skills(self._app_config, enabled_only=False)
         skill = next((s for s in skills if s.name == name), None)
         if skill is None:
             raise ValueError(f"Skill '{name}' not found")
@@ -987,21 +934,25 @@ class DeerFlowClient:
         if config_path is None:
             raise FileNotFoundError("Cannot locate extensions_config.json. Set DEER_FLOW_EXTENSIONS_CONFIG_PATH or ensure it exists in the project root.")
 
-        extensions_config = get_extensions_config()
+        # Do not mutate self._app_config (frozen value). Compose the new
-        extensions_config.skills[name] = SkillStateConfig(enabled=enabled)
+        # skills state in a fresh dict, write it to disk, and let _reload_config()
+        # below rebuild AppConfig from the updated file.
+        ext = self._app_config.extensions
+        new_skills = {n: {"enabled": sc.enabled} for n, sc in ext.skills.items()}
+        new_skills[name] = {"enabled": enabled}
 
         config_data = {
-            "mcpServers": {n: s.model_dump() for n, s in extensions_config.mcp_servers.items()},
+            "mcpServers": {n: s.model_dump() for n, s in ext.mcp_servers.items()},
-            "skills": {n: {"enabled": sc.enabled} for n, sc in extensions_config.skills.items()},
+            "skills": new_skills,
         }
 
         self._atomic_write_json(config_path, config_data)
 
         self._agent = None
         self._agent_config_key = None
-        reload_extensions_config()
+        self._reload_config()
 
-        updated = next((s for s in get_or_new_skill_storage().load_skills(enabled_only=False) if s.name == name), None)
+        updated = next((s for s in load_skills(self._app_config, enabled_only=False) if s.name == name), None)
         if updated is None:
             raise RuntimeError(f"Skill '{name}' disappeared after update")
         return {
@@ -1025,7 +976,7 @@ class DeerFlowClient:
             FileNotFoundError: If the file does not exist.
             ValueError: If the file is invalid.
         """
-        return get_or_new_skill_storage().install_skill_from_archive(skill_path)
+        return install_skill_from_archive(skill_path)
 
     # ------------------------------------------------------------------
     # Public API — memory management
@@ -1039,25 +990,25 @@ class DeerFlowClient:
         """
         from deerflow.agents.memory.updater import reload_memory_data
 
-        return reload_memory_data(user_id=get_effective_user_id())
+        return reload_memory_data(self._app_config.memory, user_id=get_effective_user_id())
 
     def clear_memory(self) -> dict:
         """Clear all persisted memory data."""
         from deerflow.agents.memory.updater import clear_memory_data
 
-        return clear_memory_data(user_id=get_effective_user_id())
+        return clear_memory_data(self._app_config.memory, user_id=get_effective_user_id())
 
     def create_memory_fact(self, content: str, category: str = "context", confidence: float = 0.5) -> dict:
         """Create a single fact manually."""
         from deerflow.agents.memory.updater import create_memory_fact
 
-        return create_memory_fact(content=content, category=category, confidence=confidence)
+        return create_memory_fact(self._app_config.memory, content=content, category=category, confidence=confidence)
 
     def delete_memory_fact(self, fact_id: str) -> dict:
         """Delete a single fact from memory by fact id."""
         from deerflow.agents.memory.updater import delete_memory_fact
 
-        return delete_memory_fact(fact_id)
+        return delete_memory_fact(self._app_config.memory, fact_id)
 
     def update_memory_fact(
         self,
@@ -1070,6 +1021,7 @@ class DeerFlowClient:
         from deerflow.agents.memory.updater import update_memory_fact
 
         return update_memory_fact(
+            self._app_config.memory,
             fact_id=fact_id,
             content=content,
             category=category,
@@ -1082,9 +1034,7 @@ class DeerFlowClient:
         Returns:
             Memory config dict.
         """
-        from deerflow.config.memory_config import get_memory_config
+        config = self._app_config.memory
-
-        config = get_memory_config()
         return {
             "enabled": config.enabled,
             "storage_path": config.storage_path,

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

@@ -48,12 +48,6 @@ class AioSandbox(Sandbox):
             self._home_dir = context.home_dir
         return self._home_dir
 
-    # Default no_change_timeout for exec_command (seconds).  Matches the
-    # client-level timeout so that long-running commands which produce no
-    # output are not prematurely terminated by the sandbox's built-in 120 s
-    # default.
-    _DEFAULT_NO_CHANGE_TIMEOUT = 600
-
     def execute_command(self, command: str) -> str:
         """Execute a shell command in the sandbox.
 
@@ -72,13 +66,13 @@ class AioSandbox(Sandbox):
         """
         with self._lock:
             try:
-                result = self._client.shell.exec_command(command=command, no_change_timeout=self._DEFAULT_NO_CHANGE_TIMEOUT)
+                result = self._client.shell.exec_command(command=command)
                 output = result.data.output if result.data else ""
 
                 if output and _ERROR_OBSERVATION_SIGNATURE in output:
                     logger.warning("ErrorObservation detected in sandbox output, retrying with a fresh session")
                     fresh_id = str(uuid.uuid4())
-                    result = self._client.shell.exec_command(command=command, id=fresh_id, no_change_timeout=self._DEFAULT_NO_CHANGE_TIMEOUT)
+                    result = self._client.shell.exec_command(command=command, id=fresh_id)
                     output = result.data.output if result.data else ""
 
                 return output if output else "(no output)"
@@ -114,7 +108,7 @@ class AioSandbox(Sandbox):
         """
         with self._lock:
             try:
-                result = self._client.shell.exec_command(command=f"find {shlex.quote(path)} -maxdepth {max_depth} -type f -o -type d 2>/dev/null | head -500", no_change_timeout=self._DEFAULT_NO_CHANGE_TIMEOUT)
+                result = self._client.shell.exec_command(command=f"find {shlex.quote(path)} -maxdepth {max_depth} -type f -o -type d 2>/dev/null | head -500")
                 output = result.data.output if result.data else ""
                 if output:
                     return [line.strip() for line in output.strip().split("\n") if line.strip()]

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

@@ -25,7 +25,7 @@ except ImportError:  # pragma: no cover - Windows fallback
     fcntl = None  # type: ignore[assignment]
     import msvcrt
 
-from deerflow.config import get_app_config
+from deerflow.config.app_config import AppConfig
 from deerflow.config.paths import VIRTUAL_PATH_PREFIX, get_paths
 from deerflow.runtime.user_context import get_effective_user_id
 from deerflow.sandbox.sandbox import Sandbox
@@ -80,7 +80,6 @@ class AioSandboxProvider(SandboxProvider):
         port: 8080                      # Base port for local containers
         container_prefix: deer-flow-sandbox
         idle_timeout: 600               # Idle timeout in seconds (0 to disable)
-        auto_restart: true              # Restart crashed containers automatically
         replicas: 3                     # Max concurrent sandbox containers (LRU eviction when exceeded)
         mounts:                         # Volume mounts for local containers
           - host_path: /path/on/host
@@ -91,7 +90,8 @@ class AioSandboxProvider(SandboxProvider):
           API_KEY: $MY_API_KEY
     """
 
-    def __init__(self):
+    def __init__(self, app_config: "AppConfig"):
+        self._app_config = app_config
         self._lock = threading.Lock()
         self._sandboxes: dict[str, AioSandbox] = {}  # sandbox_id -> AioSandbox instance
         self._sandbox_infos: dict[str, SandboxInfo] = {}  # sandbox_id -> SandboxInfo (for destroy)
@@ -160,19 +160,16 @@ class AioSandboxProvider(SandboxProvider):
 
     def _load_config(self) -> dict:
         """Load sandbox configuration from app config."""
-        config = get_app_config()
+        sandbox_config = self._app_config.sandbox
-        sandbox_config = config.sandbox
 
         idle_timeout = getattr(sandbox_config, "idle_timeout", None)
         replicas = getattr(sandbox_config, "replicas", None)
-        auto_restart = getattr(sandbox_config, "auto_restart", True)
 
         return {
             "image": sandbox_config.image or DEFAULT_IMAGE,
             "port": sandbox_config.port or DEFAULT_PORT,
             "container_prefix": sandbox_config.container_prefix or DEFAULT_CONTAINER_PREFIX,
             "idle_timeout": idle_timeout if idle_timeout is not None else DEFAULT_IDLE_TIMEOUT,
-            "auto_restart": auto_restart,
             "replicas": replicas if replicas is not None else DEFAULT_REPLICAS,
             "mounts": sandbox_config.mounts or [],
             "environment": self._resolve_env_vars(sandbox_config.environment or {}),
@@ -286,17 +283,15 @@ class AioSandboxProvider(SandboxProvider):
             (paths.host_acp_workspace_dir(thread_id, user_id=user_id), "/mnt/acp-workspace", True),
         ]
 
-    @staticmethod
+    def _get_skills_mount(self) -> tuple[str, str, bool] | None:
-    def _get_skills_mount() -> tuple[str, str, bool] | None:
         """Get the skills directory mount configuration.
 
         Mount source uses DEER_FLOW_HOST_SKILLS_PATH when running inside Docker (DooD)
         so the host Docker daemon can resolve the path.
         """
         try:
-            config = get_app_config()
+            skills_path = self._app_config.skills.get_skills_path()
-            skills_path = config.skills.get_skills_path()
+            container_path = self._app_config.skills.container_path
-            container_path = config.skills.container_path
 
             if skills_path.exists():
                 # When running inside Docker with DooD, use host-side skills path.
@@ -611,57 +606,17 @@ class AioSandboxProvider(SandboxProvider):
     def get(self, sandbox_id: str) -> Sandbox | None:
         """Get a sandbox by ID. Updates last activity timestamp.
 
-        When ``auto_restart`` is enabled (the default), the container's liveness
-        is verified on each lookup.  If the underlying container has crashed, the
-        sandbox is evicted from all caches so that the next ``acquire()`` call will
-        transparently create a fresh container.
-
         Args:
             sandbox_id: The ID of the sandbox.
 
         Returns:
-            The sandbox instance if found and alive, None otherwise.
+            The sandbox instance if found, None otherwise.
         """
         with self._lock:
             sandbox = self._sandboxes.get(sandbox_id)
-            if sandbox is None:
+            if sandbox is not None:
-                return None
-            self._last_activity[sandbox_id] = time.time()
-            auto_restart = self._config.get("auto_restart", True)
-            info = self._sandbox_infos.get(sandbox_id) if auto_restart else None
-
-        if not info:
-            return sandbox
-
-        if self._backend.is_alive(info):
-            return sandbox
-
-        info_to_destroy = None
-        with self._lock:
-            current_sandbox = self._sandboxes.get(sandbox_id)
-            current_info = self._sandbox_infos.get(sandbox_id)
-            if current_sandbox is None:
-                return None
-            if current_info is not info:
                 self._last_activity[sandbox_id] = time.time()
-                return current_sandbox
+            return sandbox
-
-            logger.warning(f"Sandbox {sandbox_id} container is not alive, evicting from cache for auto-restart")
-            self._sandboxes.pop(sandbox_id, None)
-            self._sandbox_infos.pop(sandbox_id, None)
-            self._last_activity.pop(sandbox_id, None)
-            self._warm_pool.pop(sandbox_id, None)
-            thread_ids = [tid for tid, sid in self._thread_sandboxes.items() if sid == sandbox_id]
-            for tid in thread_ids:
-                del self._thread_sandboxes[tid]
-            info_to_destroy = info
-
-        if info_to_destroy:
-            try:
-                self._backend.destroy(info_to_destroy)
-            except Exception as e:
-                logger.warning(f"Failed to cleanup dead sandbox {sandbox_id}: {e}")
-        return None
 
     def release(self, sandbox_id: str) -> None:
         """Release a sandbox from active use into the warm pool.

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

@@ -9,7 +9,6 @@ from __future__ import annotations
 import json
 import logging
 import os
-import shlex
 import subprocess
 from datetime import datetime
 
@@ -87,88 +86,6 @@ def _format_container_mount(runtime: str, host_path: str, container_path: str, r
     return ["-v", mount_spec]
 
 
-def _redact_container_command_for_log(cmd: list[str]) -> list[str]:
-    """Return a Docker/Container command with environment values redacted."""
-    redacted: list[str] = []
-    redact_next_env = False
-
-    for arg in cmd:
-        if redact_next_env:
-            if "=" in arg:
-                key = arg.split("=", 1)[0]
-                redacted.append(f"{key}=<redacted>" if key else "<redacted>")
-            else:
-                redacted.append(arg)
-            redact_next_env = False
-            continue
-
-        if arg in {"-e", "--env"}:
-            redacted.append(arg)
-            redact_next_env = True
-            continue
-
-        if arg.startswith("--env="):
-            value = arg.removeprefix("--env=")
-            if "=" in value:
-                key = value.split("=", 1)[0]
-                redacted.append(f"--env={key}=<redacted>" if key else "--env=<redacted>")
-            else:
-                redacted.append(arg)
-            continue
-
-        redacted.append(arg)
-
-    return redacted
-
-
-def _format_container_command_for_log(cmd: list[str]) -> str:
-    if os.name == "nt":
-        return subprocess.list2cmdline(cmd)
-    return shlex.join(cmd)
-
-
-def _normalize_sandbox_host(host: str) -> str:
-    return host.strip().lower()
-
-
-def _is_ipv6_loopback_sandbox_host(host: str) -> bool:
-    return _normalize_sandbox_host(host) in {"::1", "[::1]"}
-
-
-def _is_loopback_sandbox_host(host: str) -> bool:
-    return _normalize_sandbox_host(host) in {"", "localhost", "127.0.0.1", "::1", "[::1]"}
-
-
-def _resolve_docker_bind_host(sandbox_host: str | None = None, bind_host: str | None = None) -> str:
-    """Choose the host interface for legacy Docker ``-p`` sandbox publishing.
-
-    Bare-metal/local runs talk to sandboxes through localhost and should not
-    expose the sandbox HTTP API on every host interface.  Docker-outside-of-
-    Docker deployments commonly use ``host.docker.internal`` from another
-    container; keep their legacy broad bind unless operators opt into a
-    narrower bind with ``DEER_FLOW_SANDBOX_BIND_HOST``.  When operators choose
-    an IPv6 loopback sandbox host, bind Docker to IPv6 loopback as well so the
-    advertised sandbox URL and published socket use the same address family.
-    """
-    explicit_bind = bind_host if bind_host is not None else os.environ.get("DEER_FLOW_SANDBOX_BIND_HOST")
-    if explicit_bind is not None:
-        explicit_bind = explicit_bind.strip()
-        if explicit_bind:
-            logger.debug("Docker sandbox bind: %s (explicit bind host override)", explicit_bind)
-            return explicit_bind
-
-    host = sandbox_host if sandbox_host is not None else os.environ.get("DEER_FLOW_SANDBOX_HOST", "localhost")
-    if _is_ipv6_loopback_sandbox_host(host):
-        logger.debug("Docker sandbox bind: [::1] (IPv6 loopback sandbox host)")
-        return "[::1]"
-    if _is_loopback_sandbox_host(host):
-        logger.debug("Docker sandbox bind: 127.0.0.1 (loopback default)")
-        return "127.0.0.1"
-
-    logger.debug("Docker sandbox bind: 0.0.0.0 (non-loopback sandbox host compatibility)")
-    return "0.0.0.0"
-
-
 class LocalContainerBackend(SandboxBackend):
     """Backend that manages sandbox containers locally using Docker or Apple Container.
 
@@ -507,17 +424,12 @@ class LocalContainerBackend(SandboxBackend):
         if self._runtime == "docker":
             cmd.extend(["--security-opt", "seccomp=unconfined"])
 
-        if self._runtime == "docker":
-            port_mapping = f"{_resolve_docker_bind_host()}:{port}:8080"
-        else:
-            port_mapping = f"{port}:8080"
-
         cmd.extend(
             [
                 "--rm",
                 "-d",
                 "-p",
-                port_mapping,
+                f"{port}:8080",
                 "--name",
                 container_name,
             ]
@@ -552,8 +464,7 @@ class LocalContainerBackend(SandboxBackend):
 
         cmd.append(self._image)
 
-        log_cmd = _format_container_command_for_log(_redact_container_command_for_log(cmd))
+        logger.info(f"Starting container using {self._runtime}: {' '.join(cmd)}")
-        logger.info(f"Starting container using {self._runtime}: {log_cmd}")
 
         try:
             result = subprocess.run(cmd, capture_output=True, text=True, check=True)

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

@@ -84,52 +84,8 @@ class RemoteSandboxBackend(SandboxBackend):
         """
         return self._provisioner_discover(sandbox_id)
 
-    def list_running(self) -> list[SandboxInfo]:
-        """Return all sandboxes currently managed by the provisioner.
-
-        Calls ``GET /api/sandboxes`` so that ``AioSandboxProvider._reconcile_orphans()``
-        can adopt pods that were created by a previous process and were never
-        explicitly destroyed.
-        Without this, a process restart silently orphans all existing k8s Pods —
-        they stay running forever because the idle checker only
-        tracks in-process state.
-        """
-        return self._provisioner_list()
-
     # ── Provisioner API calls ─────────────────────────────────────────────
 
-    def _provisioner_list(self) -> list[SandboxInfo]:
-        """GET /api/sandboxes → list all running sandboxes."""
-        try:
-            resp = requests.get(f"{self._provisioner_url}/api/sandboxes", timeout=10)
-            resp.raise_for_status()
-            data = resp.json()
-            if not isinstance(data, dict):
-                logger.warning("Provisioner list_running returned non-dict payload: %r", type(data))
-                return []
-
-            sandboxes = data.get("sandboxes", [])
-            if not isinstance(sandboxes, list):
-                logger.warning("Provisioner list_running returned non-list sandboxes: %r", type(sandboxes))
-                return []
-
-            infos: list[SandboxInfo] = []
-            for sandbox in sandboxes:
-                if not isinstance(sandbox, dict):
-                    logger.warning("Provisioner list_running entry is not a dict: %r", type(sandbox))
-                    continue
-
-                sandbox_id = sandbox.get("sandbox_id")
-                sandbox_url = sandbox.get("sandbox_url")
-                if isinstance(sandbox_id, str) and sandbox_id and isinstance(sandbox_url, str) and sandbox_url:
-                    infos.append(SandboxInfo(sandbox_id=sandbox_id, sandbox_url=sandbox_url))
-
-            logger.info("Provisioner list_running: %d sandbox(es) found", len(infos))
-            return infos
-        except requests.RequestException as exc:
-            logger.warning("Provisioner list_running failed: %s", exc)
-            return []
-
     def _provisioner_create(self, thread_id: str, sandbox_id: str, extra_mounts: list[tuple[str, str, bool]] | None = None) -> SandboxInfo:
         """POST /api/sandboxes → create Pod + Service."""
         try:

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

@@ -5,9 +5,9 @@ Web Search Tool - Search the web using DuckDuckGo (no API key required).
 import json
 import logging
 
-from langchain.tools import tool
+from langchain.tools import ToolRuntime, tool
 
-from deerflow.config import get_app_config
+from deerflow.config.deer_flow_context import resolve_context
 
 logger = logging.getLogger(__name__)
 
@@ -55,6 +55,7 @@ def _search_text(
 @tool("web_search", parse_docstring=True)
 def web_search_tool(
     query: str,
+    runtime: ToolRuntime,
     max_results: int = 5,
 ) -> str:
     """Search the web for information. Use this tool to find current information, news, articles, and facts from the internet.
@@ -63,11 +64,11 @@ def web_search_tool(
         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")
+    tool_config = resolve_context(runtime).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:
+    if tool_config is not None and "max_results" in tool_config.model_extra:
-        max_results = config.model_extra.get("max_results", max_results)
+        max_results = tool_config.model_extra.get("max_results", max_results)
 
     results = _search_text(
         query=query,

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

@@ -1,37 +1,39 @@
 import json
 
 from exa_py import Exa
-from langchain.tools import tool
+from langchain.tools import ToolRuntime, tool
 
-from deerflow.config import get_app_config
+from deerflow.config.app_config import AppConfig
+from deerflow.config.deer_flow_context import resolve_context
 
 
-def _get_exa_client(tool_name: str = "web_search") -> Exa:
+def _get_exa_client(app_config: AppConfig, tool_name: str = "web_search") -> Exa:
-    config = get_app_config().get_tool_config(tool_name)
+    tool_config = app_config.get_tool_config(tool_name)
     api_key = None
-    if config is not None and "api_key" in config.model_extra:
+    if tool_config is not None and "api_key" in tool_config.model_extra:
-        api_key = config.model_extra.get("api_key")
+        api_key = tool_config.model_extra.get("api_key")
     return Exa(api_key=api_key)
 
 
 @tool("web_search", parse_docstring=True)
-def web_search_tool(query: str) -> str:
+def web_search_tool(query: str, runtime: ToolRuntime) -> str:
     """Search the web.
 
     Args:
         query: The query to search for.
     """
     try:
-        config = get_app_config().get_tool_config("web_search")
+        app_config = resolve_context(runtime).app_config
+        tool_config = app_config.get_tool_config("web_search")
         max_results = 5
         search_type = "auto"
         contents_max_characters = 1000
-        if config is not None:
+        if tool_config is not None:
-            max_results = config.model_extra.get("max_results", max_results)
+            max_results = tool_config.model_extra.get("max_results", max_results)
-            search_type = config.model_extra.get("search_type", search_type)
+            search_type = tool_config.model_extra.get("search_type", search_type)
-            contents_max_characters = config.model_extra.get("contents_max_characters", contents_max_characters)
+            contents_max_characters = tool_config.model_extra.get("contents_max_characters", contents_max_characters)
 
-        client = _get_exa_client()
+        client = _get_exa_client(app_config)
         res = client.search(
             query,
             type=search_type,
@@ -54,7 +56,7 @@ def web_search_tool(query: str) -> str:
 
 
 @tool("web_fetch", parse_docstring=True)
-def web_fetch_tool(url: str) -> str:
+def web_fetch_tool(url: str, runtime: ToolRuntime) -> 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.
@@ -65,7 +67,7 @@ def web_fetch_tool(url: str) -> str:
         url: The URL to fetch the contents of.
     """
     try:
-        client = _get_exa_client("web_fetch")
+        client = _get_exa_client(resolve_context(runtime).app_config, "web_fetch")
         res = client.get_contents([url], text={"max_characters": 4096})
 
         if res.results:

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

@@ -1,33 +1,35 @@
 import json
 
 from firecrawl import FirecrawlApp
-from langchain.tools import tool
+from langchain.tools import ToolRuntime, tool
 
-from deerflow.config import get_app_config
+from deerflow.config.app_config import AppConfig
+from deerflow.config.deer_flow_context import resolve_context
 
 
-def _get_firecrawl_client(tool_name: str = "web_search") -> FirecrawlApp:
+def _get_firecrawl_client(app_config: AppConfig, tool_name: str = "web_search") -> FirecrawlApp:
-    config = get_app_config().get_tool_config(tool_name)
+    tool_config = app_config.get_tool_config(tool_name)
     api_key = None
-    if config is not None and "api_key" in config.model_extra:
+    if tool_config is not None and "api_key" in tool_config.model_extra:
-        api_key = config.model_extra.get("api_key")
+        api_key = tool_config.model_extra.get("api_key")
     return FirecrawlApp(api_key=api_key)  # type: ignore[arg-type]
 
 
 @tool("web_search", parse_docstring=True)
-def web_search_tool(query: str) -> str:
+def web_search_tool(query: str, runtime: ToolRuntime) -> str:
     """Search the web.
 
     Args:
         query: The query to search for.
     """
     try:
-        config = get_app_config().get_tool_config("web_search")
+        app_config = resolve_context(runtime).app_config
+        tool_config = app_config.get_tool_config("web_search")
         max_results = 5
-        if config is not None:
+        if tool_config is not None:
-            max_results = config.model_extra.get("max_results", max_results)
+            max_results = tool_config.model_extra.get("max_results", max_results)
 
-        client = _get_firecrawl_client("web_search")
+        client = _get_firecrawl_client(app_config, "web_search")
         result = client.search(query, limit=max_results)
 
         # result.web contains list of SearchResultWeb objects
@@ -47,7 +49,7 @@ def web_search_tool(query: str) -> str:
 
 
 @tool("web_fetch", parse_docstring=True)
-def web_fetch_tool(url: str) -> str:
+def web_fetch_tool(url: str, runtime: ToolRuntime) -> 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.
@@ -58,7 +60,8 @@ def web_fetch_tool(url: str) -> str:
         url: The URL to fetch the contents of.
     """
     try:
-        client = _get_firecrawl_client("web_fetch")
+        app_config = resolve_context(runtime).app_config
+        client = _get_firecrawl_client(app_config, "web_fetch")
         result = client.scrape(url, formats=["markdown"])
 
         markdown_content = result.markdown or ""

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

@@ -5,9 +5,9 @@ Image Search Tool - Search images using DuckDuckGo for reference in image genera
 import json
 import logging
 
-from langchain.tools import tool
+from langchain.tools import ToolRuntime, tool
 
-from deerflow.config import get_app_config
+from deerflow.config.deer_flow_context import resolve_context
 
 logger = logging.getLogger(__name__)
 
@@ -77,6 +77,7 @@ def _search_images(
 @tool("image_search", parse_docstring=True)
 def image_search_tool(
     query: str,
+    runtime: ToolRuntime,
     max_results: int = 5,
     size: str | None = None,
     type_image: str | None = None,
@@ -99,11 +100,11 @@ def image_search_tool(
         type_image: Image type filter. Options: "photo", "clipart", "gif", "transparent", "line". Use "photo" for realistic references.
         layout: Layout filter. Options: "Square", "Tall", "Wide". Choose based on your generation needs.
     """
-    config = get_app_config().get_tool_config("image_search")
+    tool_config = resolve_context(runtime).app_config.get_tool_config("image_search")
 
     # Override max_results from config if set
-    if config is not None and "max_results" in config.model_extra:
+    if tool_config is not None and "max_results" in tool_config.model_extra:
-        max_results = config.model_extra.get("max_results", max_results)
+        max_results = tool_config.model_extra.get("max_results", max_results)
 
     results = _search_images(
         query=query,

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

@@ -1,6 +1,7 @@
-from langchain.tools import tool
+from langchain.tools import ToolRuntime, tool
 
-from deerflow.config import get_app_config
+from deerflow.config.app_config import AppConfig
+from deerflow.config.deer_flow_context import resolve_context
 from deerflow.utils.readability import ReadabilityExtractor
 
 from .infoquest_client import InfoQuestClient
@@ -8,13 +9,13 @@ from .infoquest_client import InfoQuestClient
 readability_extractor = ReadabilityExtractor()
 
 
-def _get_infoquest_client() -> InfoQuestClient:
+def _get_infoquest_client(app_config: AppConfig) -> InfoQuestClient:
-    search_config = get_app_config().get_tool_config("web_search")
+    search_config = 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_config = 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")
@@ -25,7 +26,7 @@ def _get_infoquest_client() -> InfoQuestClient:
     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_config = 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")
@@ -44,19 +45,18 @@ def _get_infoquest_client() -> InfoQuestClient:
 
 
 @tool("web_search", parse_docstring=True)
-def web_search_tool(query: str) -> str:
+def web_search_tool(query: str, runtime: ToolRuntime) -> str:
     """Search the web.
 
     Args:
         query: The query to search for.
     """
-
+    client = _get_infoquest_client(resolve_context(runtime).app_config)
-    client = _get_infoquest_client()
     return client.web_search(query)
 
 
 @tool("web_fetch", parse_docstring=True)
-def web_fetch_tool(url: str) -> str:
+def web_fetch_tool(url: str, runtime: ToolRuntime) -> 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.
@@ -66,7 +66,7 @@ def web_fetch_tool(url: str) -> str:
     Args:
         url: The URL to fetch the contents of.
     """
-    client = _get_infoquest_client()
+    client = _get_infoquest_client(resolve_context(runtime).app_config)
     result = client.fetch(url)
     if result.startswith("Error: "):
         return result
@@ -75,7 +75,7 @@ def web_fetch_tool(url: str) -> str:
 
 
 @tool("image_search", parse_docstring=True)
-def image_search_tool(query: str) -> str:
+def image_search_tool(query: str, runtime: ToolRuntime) -> 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:**
@@ -89,5 +89,5 @@ def image_search_tool(query: str) -> str:
     Args:
         query: The query to search for images.
     """
-    client = _get_infoquest_client()
+    client = _get_infoquest_client(resolve_context(runtime).app_config)
     return client.image_search(query)

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

@@ -1,16 +1,16 @@
 import asyncio
 
-from langchain.tools import tool
+from langchain.tools import ToolRuntime, tool
 
 from deerflow.community.jina_ai.jina_client import JinaClient
-from deerflow.config import get_app_config
+from deerflow.config.deer_flow_context import resolve_context
 from deerflow.utils.readability import ReadabilityExtractor
 
 readability_extractor = ReadabilityExtractor()
 
 
 @tool("web_fetch", parse_docstring=True)
-async def web_fetch_tool(url: str) -> str:
+async def web_fetch_tool(url: str, runtime: ToolRuntime) -> 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.
@@ -22,9 +22,9 @@ async def web_fetch_tool(url: str) -> str:
     """
     jina_client = JinaClient()
     timeout = 10
-    config = get_app_config().get_tool_config("web_fetch")
+    tool_config = resolve_context(runtime).app_config.get_tool_config("web_fetch")
-    if config is not None and "timeout" in config.model_extra:
+    if tool_config is not None and "timeout" in tool_config.model_extra:
-        timeout = config.model_extra.get("timeout")
+        timeout = tool_config.model_extra.get("timeout")
     html_content = await jina_client.crawl(url, return_format="html", timeout=timeout)
     if isinstance(html_content, str) and html_content.startswith("Error:"):
         return html_content

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

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

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

@@ -1,95 +0,0 @@
-"""
-Web Search Tool - Search the web using Serper (Google Search API).
-
-Serper provides real-time Google Search results via a JSON API.
-An API key is required. Sign up at https://serper.dev to get one.
-"""
-
-import json
-import logging
-import os
-
-import httpx
-from langchain.tools import tool
-
-from deerflow.config import get_app_config
-
-logger = logging.getLogger(__name__)
-
-_SERPER_ENDPOINT = "https://google.serper.dev/search"
-_api_key_warned = False
-
-
-def _get_api_key() -> str | None:
-    config = get_app_config().get_tool_config("web_search")
-    if config is not None:
-        api_key = config.model_extra.get("api_key")
-        if isinstance(api_key, str) and api_key.strip():
-            return api_key
-    return os.getenv("SERPER_API_KEY")
-
-
-@tool("web_search", parse_docstring=True)
-def web_search_tool(query: str, max_results: int = 5) -> str:
-    """Search the web for information using Google Search via Serper.
-
-    Args:
-        query: Search keywords describing what you want to find. Be specific for better results.
-        max_results: Maximum number of search results to return. Default is 5.
-    """
-    global _api_key_warned
-
-    config = get_app_config().get_tool_config("web_search")
-    if config is not None and "max_results" in config.model_extra:
-        max_results = config.model_extra.get("max_results", max_results)
-
-    api_key = _get_api_key()
-    if not api_key:
-        if not _api_key_warned:
-            _api_key_warned = True
-            logger.warning("Serper API key is not set. Set SERPER_API_KEY in your environment or provide api_key in config.yaml. Sign up at https://serper.dev")
-        return json.dumps(
-            {"error": "SERPER_API_KEY is not configured", "query": query},
-            ensure_ascii=False,
-        )
-
-    headers = {
-        "X-API-KEY": api_key,
-        "Content-Type": "application/json",
-    }
-    payload = {"q": query, "num": max_results}
-
-    try:
-        with httpx.Client(timeout=30) as client:
-            response = client.post(_SERPER_ENDPOINT, headers=headers, json=payload)
-        response.raise_for_status()
-        data = response.json()
-    except httpx.HTTPStatusError as e:
-        logger.error(f"Serper API returned HTTP {e.response.status_code}: {e.response.text}")
-        return json.dumps(
-            {"error": f"Serper API error: HTTP {e.response.status_code}", "query": query},
-            ensure_ascii=False,
-        )
-    except Exception as e:
-        logger.error(f"Serper search failed: {type(e).__name__}: {e}")
-        return json.dumps({"error": str(e), "query": query}, ensure_ascii=False)
-
-    organic = data.get("organic", [])
-    if not organic:
-        return json.dumps({"error": "No results found", "query": query}, ensure_ascii=False)
-
-    normalized_results = [
-        {
-            "title": r.get("title", ""),
-            "url": r.get("link", ""),
-            "content": r.get("snippet", ""),
-        }
-        for r in organic[:max_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/tavily/tools.py

@@ -1,32 +1,34 @@
 import json
 
-from langchain.tools import tool
+from langchain.tools import ToolRuntime, tool
 from tavily import TavilyClient
 
-from deerflow.config import get_app_config
+from deerflow.config.app_config import AppConfig
+from deerflow.config.deer_flow_context import resolve_context
 
 
-def _get_tavily_client() -> TavilyClient:
+def _get_tavily_client(app_config: AppConfig) -> TavilyClient:
-    config = get_app_config().get_tool_config("web_search")
+    tool_config = app_config.get_tool_config("web_search")
     api_key = None
-    if config is not None and "api_key" in config.model_extra:
+    if tool_config is not None and "api_key" in tool_config.model_extra:
-        api_key = config.model_extra.get("api_key")
+        api_key = tool_config.model_extra.get("api_key")
     return TavilyClient(api_key=api_key)
 
 
 @tool("web_search", parse_docstring=True)
-def web_search_tool(query: str) -> str:
+def web_search_tool(query: str, runtime: ToolRuntime) -> str:
     """Search the web.
 
     Args:
         query: The query to search for.
     """
-    config = get_app_config().get_tool_config("web_search")
+    app_config = resolve_context(runtime).app_config
+    tool_config = app_config.get_tool_config("web_search")
     max_results = 5
-    if config is not None and "max_results" in config.model_extra:
+    if tool_config is not None and "max_results" in tool_config.model_extra:
-        max_results = config.model_extra.get("max_results")
+        max_results = tool_config.model_extra.get("max_results")
 
-    client = _get_tavily_client()
+    client = _get_tavily_client(app_config)
     res = client.search(query, max_results=max_results)
     normalized_results = [
         {
@@ -41,7 +43,7 @@ def web_search_tool(query: str) -> str:
 
 
 @tool("web_fetch", parse_docstring=True)
-def web_fetch_tool(url: str) -> str:
+def web_fetch_tool(url: str, runtime: ToolRuntime) -> 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.
@@ -51,7 +53,8 @@ def web_fetch_tool(url: str) -> str:
     Args:
         url: The URL to fetch the contents of.
     """
-    client = _get_tavily_client()
+    app_config = resolve_context(runtime).app_config
+    client = _get_tavily_client(app_config)
     res = client.extract([url])
     if "failed_results" in res and len(res["failed_results"]) > 0:
         return f"Error: {res['failed_results'][0]['error']}"

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

@@ -1,7 +1,6 @@
-from .app_config import get_app_config
+from .app_config import AppConfig
-from .extensions_config import ExtensionsConfig, get_extensions_config
+from .extensions_config import ExtensionsConfig
-from .loop_detection_config import LoopDetectionConfig
+from .memory_config import MemoryConfig
-from .memory_config import MemoryConfig, get_memory_config
 from .paths import Paths, get_paths
 from .skill_evolution_config import SkillEvolutionConfig
 from .skills_config import SkillsConfig
@@ -14,19 +13,16 @@ from .tracing_config import (
 )
 
 __all__ = [
-    "get_app_config",
+    "AppConfig",
-    "SkillEvolutionConfig",
-    "Paths",
-    "get_paths",
-    "SkillsConfig",
     "ExtensionsConfig",
-    "get_extensions_config",
-    "LoopDetectionConfig",
     "MemoryConfig",
-    "get_memory_config",
+    "Paths",
-    "get_tracing_config",
+    "SkillEvolutionConfig",
-    "get_explicitly_enabled_tracing_providers",
+    "SkillsConfig",
     "get_enabled_tracing_providers",
+    "get_explicitly_enabled_tracing_providers",
+    "get_paths",
+    "get_tracing_config",
     "is_tracing_enabled",
     "validate_enabled_tracing_providers",
 ]

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

@@ -1,16 +1,13 @@
 """ACP (Agent Client Protocol) agent configuration loaded from config.yaml."""
 
-import logging
+from pydantic import BaseModel, ConfigDict, Field
-from collections.abc import Mapping
-
-from pydantic import BaseModel, Field
-
-logger = logging.getLogger(__name__)
 
 
 class ACPAgentConfig(BaseModel):
     """Configuration for a single ACP-compatible agent."""
 
+    model_config = ConfigDict(frozen=True)
+
     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.")
@@ -24,28 +21,3 @@ class ACPAgentConfig(BaseModel):
             "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/agents_api_config.py

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

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

@@ -1,22 +1,13 @@
-"""Configuration and loaders for custom agents.
+"""Configuration and loaders for custom agents."""
-
-Custom agents are stored per-user under ``{base_dir}/users/{user_id}/agents/{name}/``.
-A legacy shared layout at ``{base_dir}/agents/{name}/`` is still readable so that
-installations that pre-date user isolation continue to work until they run the
-``scripts/migrate_user_isolation.py`` migration. New writes always target the
-per-user layout.
-"""
 
 import logging
 import re
-from pathlib import Path
 from typing import Any
 
 import yaml
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
 
 from deerflow.config.paths import get_paths
-from deerflow.runtime.user_context import get_effective_user_id
 
 logger = logging.getLogger(__name__)
 
@@ -38,6 +29,8 @@ def validate_agent_name(name: str | None) -> str | None:
 class AgentConfig(BaseModel):
     """Configuration for a custom agent."""
 
+    model_config = ConfigDict(frozen=True)
+
     name: str
     description: str = ""
     model: str | None = None
@@ -49,47 +42,14 @@ class AgentConfig(BaseModel):
     skills: list[str] | None = None
 
 
-def resolve_agent_dir(name: str, *, user_id: str | None = None) -> Path:
+def load_agent_config(name: str | None) -> AgentConfig | None:
-    """Return the on-disk directory for an agent, preferring the per-user layout.
-
-    Resolution order:
-    1. ``{base_dir}/users/{user_id}/agents/{name}/`` (per-user, current layout).
-    2. ``{base_dir}/agents/{name}/`` (legacy shared layout — read-only fallback).
-
-    If neither exists, the per-user path is returned so callers that intend to
-    create the agent write into the new layout.
-
-    Args:
-        name: Validated agent name.
-        user_id: Owner of the agent. Defaults to the effective user from the
-            request context (or ``"default"`` in no-auth mode).
-    """
-    paths = get_paths()
-    effective_user = user_id or get_effective_user_id()
-    user_path = paths.user_agent_dir(effective_user, name)
-    if user_path.exists():
-        return user_path
-
-    legacy_path = paths.agent_dir(name)
-    if legacy_path.exists():
-        return legacy_path
-
-    return user_path
-
-
-def load_agent_config(name: str | None, *, user_id: str | None = None) -> AgentConfig | None:
     """Load the custom or default agent's config from its directory.
 
-    Reads from the per-user layout first; falls back to the legacy shared layout
-    for installations that have not yet been migrated.
-
     Args:
         name: The agent name.
-        user_id: Owner of the agent. Defaults to the effective user from the
-            current request context.
 
     Returns:
-        AgentConfig instance, or ``None`` if ``name`` is ``None``.
+        AgentConfig instance.
 
     Raises:
         FileNotFoundError: If the agent directory or config.yaml does not exist.
@@ -100,7 +60,7 @@ def load_agent_config(name: str | None, *, user_id: str | None = None) -> AgentC
         return None
 
     name = validate_agent_name(name)
-    agent_dir = resolve_agent_dir(name, user_id=user_id)
+    agent_dir = get_paths().agent_dir(name)
     config_file = agent_dir / "config.yaml"
 
     if not agent_dir.exists():
@@ -126,7 +86,7 @@ def load_agent_config(name: str | None, *, user_id: str | None = None) -> AgentC
     return AgentConfig(**data)
 
 
-def load_agent_soul(agent_name: str | None, *, user_id: str | None = None) -> str | None:
+def load_agent_soul(agent_name: str | None) -> str | None:
     """Read the SOUL.md file for a custom agent, if it exists.
 
     SOUL.md defines the agent's personality, values, and behavioral guardrails.
@@ -134,16 +94,11 @@ def load_agent_soul(agent_name: str | None, *, user_id: str | None = None) -> st
 
     Args:
         agent_name: The name of the agent or None for the default agent.
-        user_id: Owner of the agent. Defaults to the effective user from the
-            current request context.
 
     Returns:
         The SOUL.md content as a string, or None if the file does not exist.
     """
-    if agent_name:
+    agent_dir = get_paths().agent_dir(agent_name) if agent_name else get_paths().base_dir
-        agent_dir = resolve_agent_dir(agent_name, user_id=user_id)
-    else:
-        agent_dir = get_paths().base_dir
     soul_path = agent_dir / SOUL_FILENAME
     if not soul_path.exists():
         return None
@@ -151,50 +106,32 @@ def load_agent_soul(agent_name: str | None, *, user_id: str | None = None) -> st
     return content or None
 
 
-def list_custom_agents(*, user_id: str | None = None) -> list[AgentConfig]:
+def list_custom_agents() -> list[AgentConfig]:
     """Scan the agents directory and return all valid custom agents.
 
-    Returns the union of agents in the per-user layout and the legacy shared
-    layout, so that pre-migration installations remain visible until they are
-    migrated. Per-user entries shadow legacy entries with the same name.
-
-    Args:
-        user_id: Owner whose agents to list. Defaults to the effective user
-            from the current request context.
-
     Returns:
         List of AgentConfig for each valid agent directory found.
     """
-    paths = get_paths()
+    agents_dir = get_paths().agents_dir
-    effective_user = user_id or get_effective_user_id()
+
+    if not agents_dir.exists():
+        return []
 
-    seen: set[str] = set()
     agents: list[AgentConfig] = []
 
-    user_root = paths.user_agents_dir(effective_user)
+    for entry in sorted(agents_dir.iterdir()):
-    legacy_root = paths.agents_dir
+        if not entry.is_dir():
-
-    for root in (user_root, legacy_root):
-        if not root.exists():
             continue
-        for entry in sorted(root.iterdir()):
-            if not entry.is_dir():
-                continue
-            if entry.name in seen:
-                continue
-            config_file = entry / "config.yaml"
-            if not config_file.exists():
-                logger.debug(f"Skipping {entry.name}: no config.yaml")
-                continue
 
-            try:
+        config_file = entry / "config.yaml"
-                agent_cfg = load_agent_config(entry.name, user_id=effective_user)
+        if not config_file.exists():
-                if agent_cfg is None:
+            logger.debug(f"Skipping {entry.name}: no config.yaml")
-                    continue
+            continue
-                agents.append(agent_cfg)
+
-                seen.add(entry.name)
+        try:
-            except Exception as e:
+            agent_cfg = load_agent_config(entry.name)
-                logger.warning(f"Skipping agent '{entry.name}': {e}")
+            agents.append(agent_cfg)
+        except Exception as e:
+            logger.warning(f"Skipping agent '{entry.name}': {e}")
 
-    agents.sort(key=lambda a: a.name)
     return agents

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

@@ -1,7 +1,7 @@
+from __future__ import annotations
+
 import logging
 import os
-from collections.abc import Mapping
-from contextvars import ContextVar
 from pathlib import Path
 from typing import Any, Self
 
@@ -9,39 +9,31 @@ import yaml
 from dotenv import load_dotenv
 from pydantic import BaseModel, ConfigDict, Field
 
-from deerflow.config.acp_config import ACPAgentConfig, load_acp_config_from_dict
+from deerflow.config.acp_config import ACPAgentConfig
-from deerflow.config.agents_api_config import AgentsApiConfig, load_agents_api_config_from_dict
+from deerflow.config.agents_api_config import AgentsApiConfig
-from deerflow.config.checkpointer_config import CheckpointerConfig, load_checkpointer_config_from_dict
+from deerflow.config.checkpointer_config import CheckpointerConfig
 from deerflow.config.database_config import DatabaseConfig
 from deerflow.config.extensions_config import ExtensionsConfig
-from deerflow.config.guardrails_config import GuardrailsConfig, load_guardrails_config_from_dict
+from deerflow.config.guardrails_config import GuardrailsConfig
-from deerflow.config.loop_detection_config import LoopDetectionConfig
+from deerflow.config.memory_config import MemoryConfig
-from deerflow.config.memory_config import MemoryConfig, load_memory_config_from_dict
 from deerflow.config.model_config import ModelConfig
 from deerflow.config.run_events_config import RunEventsConfig
-from deerflow.config.runtime_paths import existing_project_file
 from deerflow.config.sandbox_config import SandboxConfig
 from deerflow.config.skill_evolution_config import SkillEvolutionConfig
 from deerflow.config.skills_config import SkillsConfig
-from deerflow.config.stream_bridge_config import StreamBridgeConfig, load_stream_bridge_config_from_dict
+from deerflow.config.stream_bridge_config import StreamBridgeConfig
-from deerflow.config.subagents_config import SubagentsAppConfig, load_subagents_config_from_dict
+from deerflow.config.subagents_config import SubagentsAppConfig
-from deerflow.config.summarization_config import SummarizationConfig, load_summarization_config_from_dict
+from deerflow.config.summarization_config import SummarizationConfig
-from deerflow.config.title_config import TitleConfig, load_title_config_from_dict
+from deerflow.config.title_config import TitleConfig
 from deerflow.config.token_usage_config import TokenUsageConfig
 from deerflow.config.tool_config import ToolConfig, ToolGroupConfig
-from deerflow.config.tool_search_config import ToolSearchConfig, load_tool_search_config_from_dict
+from deerflow.config.tool_search_config import ToolSearchConfig
 
 load_dotenv()
 
 logger = logging.getLogger(__name__)
 
 
-CONFIG_FILE_DATABASE_DEFAULTS = {
-    "backend": "sqlite",
-    "sqlite_dir": ".deer-flow/data",
-}
-
-
 class CircuitBreakerConfig(BaseModel):
     """Configuration for the LLM Circuit Breaker."""
 
@@ -49,41 +41,17 @@ class CircuitBreakerConfig(BaseModel):
     recovery_timeout_sec: int = Field(default=60, description="Time in seconds before attempting to recover the circuit")
 
 
-def _legacy_config_candidates() -> tuple[Path, ...]:
+def _default_config_candidates() -> tuple[Path, ...]:
-    """Return source-tree config.yaml locations for monorepo compatibility."""
+    """Return deterministic config.yaml locations without relying on cwd."""
     backend_dir = Path(__file__).resolve().parents[4]
     repo_root = backend_dir.parent
     return (backend_dir / "config.yaml", repo_root / "config.yaml")
 
 
-def logging_level_from_config(name: str | None) -> int:
-    """Map ``config.yaml`` ``log_level`` string to a :mod:`logging` level constant."""
-    mapping = logging.getLevelNamesMapping()
-    return mapping.get((name or "info").strip().upper(), logging.INFO)
-
-
-def apply_logging_level(name: str | None) -> None:
-    """Resolve *name* to a logging level and apply it to the ``deerflow``/``app`` logger hierarchies.
-
-    Only the ``deerflow`` and ``app`` logger levels are changed so that
-    third-party library verbosity (e.g. uvicorn, sqlalchemy) is not
-    affected. Root handler levels are lowered (never raised) so that
-    messages from the configured loggers can propagate through without
-    being filtered, while preserving handler thresholds that may be
-    intentionally restrictive for third-party log output.
-    """
-    level = logging_level_from_config(name)
-    for logger_name in ("deerflow", "app"):
-        logging.getLogger(logger_name).setLevel(level)
-    for handler in logging.root.handlers:
-        if level < handler.level:
-            handler.setLevel(level)
-
-
 class AppConfig(BaseModel):
     """Config for the DeerFlow application"""
 
-    log_level: str = Field(default="info", description="Logging level for deerflow and app modules (debug/info/warning/error); third-party libraries are not affected")
+    log_level: str = Field(default="info", description="Logging level for deerflow modules (debug/info/warning/error)")
     token_usage: TokenUsageConfig = Field(default_factory=TokenUsageConfig, description="Token usage tracking configuration")
     models: list[ModelConfig] = Field(default_factory=list, description="Available models")
     sandbox: SandboxConfig = Field(description="Sandbox configuration")
@@ -97,16 +65,15 @@ class AppConfig(BaseModel):
     summarization: SummarizationConfig = Field(default_factory=SummarizationConfig, description="Conversation summarization configuration")
     memory: MemoryConfig = Field(default_factory=MemoryConfig, description="Memory subsystem configuration")
     agents_api: AgentsApiConfig = Field(default_factory=AgentsApiConfig, description="Custom-agent management API configuration")
-    acp_agents: dict[str, ACPAgentConfig] = Field(default_factory=dict, description="ACP-compatible agent configuration")
     subagents: SubagentsAppConfig = Field(default_factory=SubagentsAppConfig, description="Subagent runtime configuration")
     guardrails: GuardrailsConfig = Field(default_factory=GuardrailsConfig, description="Guardrail middleware configuration")
     circuit_breaker: CircuitBreakerConfig = Field(default_factory=CircuitBreakerConfig, description="LLM circuit breaker configuration")
-    loop_detection: LoopDetectionConfig = Field(default_factory=LoopDetectionConfig, description="Loop detection middleware configuration")
-    model_config = ConfigDict(extra="allow")
     database: DatabaseConfig = Field(default_factory=DatabaseConfig, description="Unified database backend configuration")
     run_events: RunEventsConfig = Field(default_factory=RunEventsConfig, description="Run event storage configuration")
+    model_config = ConfigDict(extra="allow", frozen=True)
     checkpointer: CheckpointerConfig | None = Field(default=None, description="Checkpointer configuration")
     stream_bridge: StreamBridgeConfig | None = Field(default=None, description="Stream bridge configuration")
+    acp_agents: dict[str, ACPAgentConfig] = Field(default_factory=dict, description="ACP agent configurations keyed by agent name")
 
     @classmethod
     def resolve_config_path(cls, config_path: str | None = None) -> Path:
@@ -115,8 +82,7 @@ class AppConfig(BaseModel):
         Priority:
         1. If provided `config_path` argument, use it.
         2. If provided `DEER_FLOW_CONFIG_PATH` environment variable, use it.
-        3. Otherwise, search the caller project root.
+        3. Otherwise, search deterministic backend/repository-root defaults from `_default_config_candidates()`.
-        4. Finally, search legacy backend/repository-root defaults for monorepo compatibility.
         """
         if config_path:
             path = Path(config_path)
@@ -129,14 +95,10 @@ class AppConfig(BaseModel):
                 raise FileNotFoundError(f"Config file specified by environment variable `DEER_FLOW_CONFIG_PATH` not found at {path}")
             return path
         else:
-            project_config = existing_project_file(("config.yaml",))
+            for path in _default_config_candidates():
-            if project_config is not None:
-                return project_config
-
-            for path in _legacy_config_candidates():
                 if path.exists():
                     return path
-            raise FileNotFoundError("`config.yaml` file not found in the project root or legacy backend/repository root locations")
+            raise FileNotFoundError("`config.yaml` file not found at the default backend or repository root locations")
 
     @classmethod
     def from_file(cls, config_path: str | None = None) -> Self:
@@ -158,68 +120,14 @@ class AppConfig(BaseModel):
         cls._check_config_version(config_data, resolved_path)
 
         config_data = cls.resolve_env_variables(config_data)
-        cls._apply_database_defaults(config_data)
-
-        # Load circuit_breaker config if present
-        if "circuit_breaker" in config_data:
-            config_data["circuit_breaker"] = config_data["circuit_breaker"]
 
         # Load extensions config separately (it's in a different file)
         extensions_config = ExtensionsConfig.from_file()
         config_data["extensions"] = extensions_config.model_dump()
 
         result = cls.model_validate(config_data)
-        acp_agents = cls._validate_acp_agents(config_data.get("acp_agents", {}))
-        cls._apply_singleton_configs(result, acp_agents)
         return result
 
-    @classmethod
-    def _validate_acp_agents(
-        cls,
-        config_data: Mapping[str, Mapping[str, object]] | None,
-    ) -> dict[str, ACPAgentConfig]:
-        if config_data is None:
-            config_data = {}
-        return {name: ACPAgentConfig(**cfg) for name, cfg in config_data.items()}
-
-    @classmethod
-    def _apply_singleton_configs(cls, config: Self, acp_agents: dict[str, ACPAgentConfig]) -> None:
-        from deerflow.config.checkpointer_config import get_checkpointer_config
-
-        previous_checkpointer_config = get_checkpointer_config()
-
-        load_title_config_from_dict(config.title.model_dump())
-        load_summarization_config_from_dict(config.summarization.model_dump())
-        load_memory_config_from_dict(config.memory.model_dump())
-        load_agents_api_config_from_dict(config.agents_api.model_dump())
-        load_subagents_config_from_dict(config.subagents.model_dump())
-        load_tool_search_config_from_dict(config.tool_search.model_dump())
-        load_guardrails_config_from_dict(config.guardrails.model_dump())
-        load_checkpointer_config_from_dict(config.checkpointer.model_dump() if config.checkpointer is not None else None)
-        load_stream_bridge_config_from_dict(config.stream_bridge.model_dump() if config.stream_bridge is not None else None)
-        load_acp_config_from_dict({name: agent.model_dump() for name, agent in acp_agents.items()})
-
-        if previous_checkpointer_config != config.checkpointer:
-            # These runtime singletons derive their backend from checkpointer config.
-            # Keep imports local to avoid cycles: both providers import get_app_config.
-            from deerflow.runtime.checkpointer import reset_checkpointer
-            from deerflow.runtime.store import reset_store
-
-            reset_checkpointer()
-            reset_store()
-
-    @classmethod
-    def _apply_database_defaults(cls, config_data: dict[str, Any]) -> None:
-        """Apply config.yaml defaults for persistence when the section is absent."""
-        database_config = config_data.get("database")
-        if database_config is None:
-            database_config = {}
-            config_data["database"] = database_config
-        if not isinstance(database_config, dict):
-            return
-        for key, value in CONFIG_FILE_DATABASE_DEFAULTS.items():
-            database_config.setdefault(key, value)
-
     @classmethod
     def _check_config_version(cls, config_data: dict, config_path: Path) -> None:
         """Check if the user's config.yaml is outdated compared to config.example.yaml.
@@ -323,133 +231,8 @@ class AppConfig(BaseModel):
         """
         return next((group for group in self.tool_groups if group.name == name), None)
 
-
+    # AppConfig is a pure value object: construct with ``from_file()``, pass around.
-# Compatibility singleton layer for code paths that have not yet been
+    # Composition roots that hold the resolved instance:
-# migrated to explicit ``AppConfig`` threading. New composition roots should
+    #   - Gateway:   ``app.state.config`` via ``Depends(get_config)``
-# prefer constructing ``AppConfig`` once and passing it down directly.
+    #   - Client:    ``DeerFlowClient._app_config``
-_app_config: AppConfig | None = None
+    #   - Agent run: ``Runtime[DeerFlowContext].context.app_config``
-_app_config_path: Path | None = None
-_app_config_mtime: float | None = None
-_app_config_is_custom = False
-_current_app_config: ContextVar[AppConfig | None] = ContextVar("deerflow_current_app_config", default=None)
-_current_app_config_stack: ContextVar[tuple[AppConfig | None, ...]] = ContextVar("deerflow_current_app_config_stack", default=())
-
-
-def _get_config_mtime(config_path: Path) -> float | None:
-    """Get the modification time of a config file if it exists."""
-    try:
-        return config_path.stat().st_mtime
-    except OSError:
-        return None
-
-
-def _load_and_cache_app_config(config_path: str | None = None) -> AppConfig:
-    """Load config from disk and refresh cache metadata."""
-    global _app_config, _app_config_path, _app_config_mtime, _app_config_is_custom
-
-    resolved_path = AppConfig.resolve_config_path(config_path)
-    _app_config = AppConfig.from_file(str(resolved_path))
-    _app_config_path = resolved_path
-    _app_config_mtime = _get_config_mtime(resolved_path)
-    _app_config_is_custom = False
-    return _app_config
-
-
-def get_app_config() -> AppConfig:
-    """Get the DeerFlow config instance.
-
-    Returns a cached singleton instance and automatically reloads it when the
-    underlying config file path or modification time changes. Use
-    `reload_app_config()` to force a reload, or `reset_app_config()` to clear
-    the cache.
-    """
-    global _app_config, _app_config_path, _app_config_mtime
-
-    runtime_override = _current_app_config.get()
-    if runtime_override is not None:
-        return runtime_override
-
-    if _app_config is not None and _app_config_is_custom:
-        return _app_config
-
-    resolved_path = AppConfig.resolve_config_path()
-    current_mtime = _get_config_mtime(resolved_path)
-
-    should_reload = _app_config is None or _app_config_path != resolved_path or _app_config_mtime != current_mtime
-    if should_reload:
-        if _app_config_path == resolved_path and _app_config_mtime is not None and current_mtime is not None and _app_config_mtime != current_mtime:
-            logger.info(
-                "Config file has been modified (mtime: %s -> %s), reloading AppConfig",
-                _app_config_mtime,
-                current_mtime,
-            )
-        _load_and_cache_app_config(str(resolved_path))
-    return _app_config
-
-
-def reload_app_config(config_path: str | None = None) -> AppConfig:
-    """Reload the config from file and update the cached instance.
-
-    This is useful when the config file has been modified and you want
-    to pick up the changes without restarting the application.
-
-    Args:
-        config_path: Optional path to config file. If not provided,
-                     uses the default resolution strategy.
-
-    Returns:
-        The newly loaded AppConfig instance.
-    """
-    return _load_and_cache_app_config(config_path)
-
-
-def reset_app_config() -> None:
-    """Reset the cached config instance.
-
-    This clears the singleton cache, causing the next call to
-    `get_app_config()` to reload from file. Useful for testing
-    or when switching between different configurations.
-    """
-    global _app_config, _app_config_path, _app_config_mtime, _app_config_is_custom
-    _app_config = None
-    _app_config_path = None
-    _app_config_mtime = None
-    _app_config_is_custom = False
-
-
-def set_app_config(config: AppConfig) -> None:
-    """Set a custom config instance.
-
-    This allows injecting a custom or mock config for testing purposes.
-
-    Args:
-        config: The AppConfig instance to use.
-    """
-    global _app_config, _app_config_path, _app_config_mtime, _app_config_is_custom
-    _app_config = config
-    _app_config_path = None
-    _app_config_mtime = None
-    _app_config_is_custom = True
-
-
-def peek_current_app_config() -> AppConfig | None:
-    """Return the runtime-scoped AppConfig override, if one is active."""
-    return _current_app_config.get()
-
-
-def push_current_app_config(config: AppConfig) -> None:
-    """Push a runtime-scoped AppConfig override for the current execution context."""
-    stack = _current_app_config_stack.get()
-    _current_app_config_stack.set(stack + (_current_app_config.get(),))
-    _current_app_config.set(config)
-
-
-def pop_current_app_config() -> None:
-    """Pop the latest runtime-scoped AppConfig override for the current execution context."""
-    stack = _current_app_config_stack.get()
-    if not stack:
-        _current_app_config.set(None)
-        return
-    previous = stack[-1]
-    _current_app_config_stack.set(stack[:-1])
-    _current_app_config.set(previous)

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

@@ -2,7 +2,7 @@
 
 from typing import Literal
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 CheckpointerType = Literal["memory", "sqlite", "postgres"]
 
@@ -10,41 +10,18 @@ CheckpointerType = Literal["memory", "sqlite", "postgres"]
 class CheckpointerConfig(BaseModel):
     """Configuration for LangGraph state persistence checkpointer."""
 
+    model_config = ConfigDict(frozen=True)
+
     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 (install with deerflow-harness[postgres])."
+        "'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). "
-        "Optional for sqlite and defaults to 'store.db' when omitted. "
+        "Required for sqlite and postgres types. "
-        "Required for postgres. "
         "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) -> None:
-    """Load checkpointer configuration from a dictionary."""
-    global _checkpointer_config
-    if config_dict is None:
-        _checkpointer_config = None
-        return
-    _checkpointer_config = CheckpointerConfig(**config_dict)

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

@@ -34,10 +34,11 @@ from __future__ import annotations
 import os
 from typing import Literal
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class DatabaseConfig(BaseModel):
+    model_config = ConfigDict(frozen=True)
     backend: Literal["memory", "sqlite", "postgres"] = Field(
         default="memory",
         description=("Storage backend for both checkpointer and application data. 'memory' for development (no persistence across restarts), 'sqlite' for single-node deployment, 'postgres' for production multi-node deployment."),

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

@@ -0,0 +1,55 @@
+"""Per-invocation context for DeerFlow agent execution.
+
+Injected via LangGraph Runtime. Middleware and tools access this
+via Runtime[DeerFlowContext] parameters, through resolve_context().
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from deerflow.config.app_config import AppConfig
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class DeerFlowContext:
+    """Typed, immutable, per-invocation context injected via LangGraph Runtime.
+
+    Fields are all known at run start and never change during execution.
+    Mutable runtime state (e.g. sandbox_id) flows through ThreadState, not here.
+    """
+
+    app_config: AppConfig
+    thread_id: str
+    agent_name: str | None = None
+
+
+def resolve_context(runtime: Any) -> DeerFlowContext:
+    """Return the typed DeerFlowContext that the runtime carries.
+
+    Gateway mode (``DeerFlowClient``, ``run_agent``) always attaches a typed
+    ``DeerFlowContext`` via ``agent.astream(context=...)``; the LangGraph
+    Server path uses ``langgraph.json`` registration where the top-level
+    ``make_lead_agent`` loads ``AppConfig`` from disk itself, so we still
+    arrive here with a typed context.
+
+    Only the dict/None shapes that legacy tests used to exercise would fall
+    through this function; we now reject them loudly instead of papering
+    over the missing context with an ambient ``AppConfig`` lookup.
+    """
+    ctx = getattr(runtime, "context", None)
+    if isinstance(ctx, DeerFlowContext):
+        return ctx
+
+    raise RuntimeError(
+        "resolve_context: runtime.context is not a DeerFlowContext "
+        "(got type %s). Every entry point must attach one at invoke time — "
+        "Gateway/Client via agent.astream(context=DeerFlowContext(...)), "
+        "LangGraph Server via the make_lead_agent boundary that loads "
+        "AppConfig.from_file()." % type(ctx).__name__
+    )

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

@@ -7,12 +7,12 @@ from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from deerflow.config.runtime_paths import existing_project_file
-
 
 class McpOAuthConfig(BaseModel):
     """OAuth configuration for an MCP server (HTTP/SSE transports)."""
 
+    model_config = ConfigDict(extra="allow", frozen=True)
+
     enabled: bool = Field(default=True, description="Whether OAuth token injection is enabled")
     token_url: str = Field(description="OAuth token endpoint URL")
     grant_type: Literal["client_credentials", "refresh_token"] = Field(
@@ -30,12 +30,13 @@ class McpOAuthConfig(BaseModel):
     default_token_type: str = Field(default="Bearer", description="Default token type when missing in token response")
     refresh_skew_seconds: int = Field(default=60, description="Refresh token this many seconds before expiry")
     extra_token_params: dict[str, str] = Field(default_factory=dict, description="Additional form params sent to token endpoint")
-    model_config = ConfigDict(extra="allow")
 
 
 class McpServerConfig(BaseModel):
     """Configuration for a single MCP server."""
 
+    model_config = ConfigDict(extra="allow", frozen=True)
+
     enabled: bool = Field(default=True, description="Whether this MCP server is enabled")
     type: str = Field(default="stdio", description="Transport type: 'stdio', 'sse', or 'http'")
     command: str | None = Field(default=None, description="Command to execute to start the MCP server (for stdio type)")
@@ -45,12 +46,13 @@ class McpServerConfig(BaseModel):
     headers: dict[str, str] = Field(default_factory=dict, description="HTTP headers to send (for sse or http type)")
     oauth: McpOAuthConfig | None = Field(default=None, description="OAuth configuration (for sse or http type)")
     description: str = Field(default="", description="Human-readable description of what this MCP server provides")
-    model_config = ConfigDict(extra="allow")
 
 
 class SkillStateConfig(BaseModel):
     """Configuration for a single skill's state."""
 
+    model_config = ConfigDict(frozen=True)
+
     enabled: bool = Field(default=True, description="Whether this skill is enabled")
 
 
@@ -66,7 +68,7 @@ class ExtensionsConfig(BaseModel):
         default_factory=dict,
         description="Map of skill name to state configuration",
     )
-    model_config = ConfigDict(extra="allow", populate_by_name=True)
+    model_config = ConfigDict(extra="allow", frozen=True, populate_by_name=True)
 
     @classmethod
     def resolve_config_path(cls, config_path: str | None = None) -> Path | None:
@@ -75,8 +77,8 @@ class ExtensionsConfig(BaseModel):
         Priority:
         1. If provided `config_path` argument, use it.
         2. If provided `DEER_FLOW_EXTENSIONS_CONFIG_PATH` environment variable, use it.
-        3. Otherwise, search the caller project root for `extensions_config.json`, then `mcp_config.json`.
+        3. Otherwise, check for `extensions_config.json` in the current directory, then in the parent directory.
-        4. For backward compatibility, also search legacy backend/repository-root defaults.
+        4. For backward compatibility, also check for `mcp_config.json` if `extensions_config.json` is not found.
         5. If not found, return None (extensions are optional).
 
         Args:
@@ -85,9 +87,8 @@ class ExtensionsConfig(BaseModel):
         Resolution order:
             1. If provided `config_path` argument, use it.
             2. If provided `DEER_FLOW_EXTENSIONS_CONFIG_PATH` environment variable, use it.
-            3. Otherwise, search the caller project root for
+            3. Otherwise, search backend/repository-root defaults for
                `extensions_config.json`, then legacy `mcp_config.json`.
-            4. Finally, search backend/repository-root defaults for monorepo compatibility.
 
         Returns:
             Path to the extensions config file if found, otherwise None.
@@ -103,10 +104,6 @@ class ExtensionsConfig(BaseModel):
                 raise FileNotFoundError(f"Extensions config file specified by environment variable `DEER_FLOW_EXTENSIONS_CONFIG_PATH` not found at {path}")
             return path
         else:
-            project_config = existing_project_file(("extensions_config.json", "mcp_config.json"))
-            if project_config is not None:
-                return project_config
-
             backend_dir = Path(__file__).resolve().parents[4]
             repo_root = backend_dir.parent
             for path in (
@@ -202,62 +199,3 @@ class ExtensionsConfig(BaseModel):
             # Default to enable for public & custom skill
             return skill_category in ("public", "custom")
         return skill_config.enabled
-
-
-_extensions_config: ExtensionsConfig | None = None
-
-
-def get_extensions_config() -> ExtensionsConfig:
-    """Get the extensions config instance.
-
-    Returns a cached singleton instance. Use `reload_extensions_config()` to reload
-    from file, or `reset_extensions_config()` to clear the cache.
-
-    Returns:
-        The cached ExtensionsConfig instance.
-    """
-    global _extensions_config
-    if _extensions_config is None:
-        _extensions_config = ExtensionsConfig.from_file()
-    return _extensions_config
-
-
-def reload_extensions_config(config_path: str | None = None) -> ExtensionsConfig:
-    """Reload the extensions config from file and update the cached instance.
-
-    This is useful when the config file has been modified and you want
-    to pick up the changes without restarting the application.
-
-    Args:
-        config_path: Optional path to extensions config file. If not provided,
-                     uses the default resolution strategy.
-
-    Returns:
-        The newly loaded ExtensionsConfig instance.
-    """
-    global _extensions_config
-    _extensions_config = ExtensionsConfig.from_file(config_path)
-    return _extensions_config
-
-
-def reset_extensions_config() -> None:
-    """Reset the cached extensions config instance.
-
-    This clears the singleton cache, causing the next call to
-    `get_extensions_config()` to reload from file. Useful for testing
-    or when switching between different configurations.
-    """
-    global _extensions_config
-    _extensions_config = None
-
-
-def set_extensions_config(config: ExtensionsConfig) -> None:
-    """Set a custom extensions config instance.
-
-    This allows injecting a custom or mock config for testing purposes.
-
-    Args:
-        config: The ExtensionsConfig instance to use.
-    """
-    global _extensions_config
-    _extensions_config = config

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

@@ -1,11 +1,13 @@
 """Configuration for pre-tool-call authorization."""
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class GuardrailProviderConfig(BaseModel):
     """Configuration for a guardrail provider."""
 
+    model_config = ConfigDict(frozen=True)
+
     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")
 
@@ -18,31 +20,9 @@ class GuardrailsConfig(BaseModel):
     agent's passport reference, and returns an allow/deny decision.
     """
 
+    model_config = ConfigDict(frozen=True)
+
     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/loop_detection_config.py

@@ -1,73 +0,0 @@
-"""Configuration for loop detection middleware."""
-
-from pydantic import BaseModel, Field, model_validator
-
-
-class ToolFreqOverride(BaseModel):
-    """Per-tool frequency threshold override.
-
-    Can be higher or lower than the global defaults. Commonly used to raise
-    thresholds for high-frequency tools like bash in batch workflows (e.g.
-    RNA-seq pipelines) without weakening protection on every other tool.
-    """
-
-    warn: int = Field(ge=1)
-    hard_limit: int = Field(ge=1)
-
-    @model_validator(mode="after")
-    def _validate(self) -> "ToolFreqOverride":
-        if self.hard_limit < self.warn:
-            raise ValueError("hard_limit must be >= warn")
-        return self
-
-
-class LoopDetectionConfig(BaseModel):
-    """Configuration for repetitive tool-call loop detection."""
-
-    enabled: bool = Field(
-        default=True,
-        description="Whether to enable repetitive tool-call loop detection",
-    )
-    warn_threshold: int = Field(
-        default=3,
-        ge=1,
-        description="Number of identical tool-call sets before injecting a warning",
-    )
-    hard_limit: int = Field(
-        default=5,
-        ge=1,
-        description="Number of identical tool-call sets before forcing a stop",
-    )
-    window_size: int = Field(
-        default=20,
-        ge=1,
-        description="Number of recent tool-call sets to track per thread",
-    )
-    max_tracked_threads: int = Field(
-        default=100,
-        ge=1,
-        description="Maximum number of thread histories to keep in memory",
-    )
-    tool_freq_warn: int = Field(
-        default=30,
-        ge=1,
-        description="Number of calls to the same tool type before injecting a frequency warning",
-    )
-    tool_freq_hard_limit: int = Field(
-        default=50,
-        ge=1,
-        description="Number of calls to the same tool type before forcing a stop",
-    )
-    tool_freq_overrides: dict[str, ToolFreqOverride] = Field(
-        default_factory=dict,
-        description=("Per-tool overrides for tool_freq_warn / tool_freq_hard_limit, keyed by tool name. Values can be higher or lower than the global defaults. Commonly used to raise thresholds for high-frequency tools like bash."),
-    )
-
-    @model_validator(mode="after")
-    def validate_thresholds(self) -> "LoopDetectionConfig":
-        """Ensure hard stop cannot happen before the warning threshold."""
-        if self.hard_limit < self.warn_threshold:
-            raise ValueError("hard_limit must be greater than or equal to warn_threshold")
-        if self.tool_freq_hard_limit < self.tool_freq_warn:
-            raise ValueError("tool_freq_hard_limit must be greater than or equal to tool_freq_warn")
-        return self

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

@@ -1,11 +1,13 @@
 """Configuration for memory mechanism."""
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class MemoryConfig(BaseModel):
     """Configuration for global memory mechanism."""
 
+    model_config = ConfigDict(frozen=True)
+
     enabled: bool = Field(
         default=True,
         description="Whether to enable memory mechanism",
@@ -60,24 +62,3 @@ class MemoryConfig(BaseModel):
         le=8000,
         description="Maximum tokens to use for memory injection",
     )
-
-
-# Global configuration instance
-_memory_config: MemoryConfig = MemoryConfig()
-
-
-def get_memory_config() -> MemoryConfig:
-    """Get the current memory configuration."""
-    return _memory_config
-
-
-def set_memory_config(config: MemoryConfig) -> None:
-    """Set the memory configuration."""
-    global _memory_config
-    _memory_config = config
-
-
-def load_memory_config_from_dict(config_dict: dict) -> None:
-    """Load memory configuration from a dictionary."""
-    global _memory_config
-    _memory_config = MemoryConfig(**config_dict)

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

@@ -12,7 +12,7 @@ class ModelConfig(BaseModel):
         description="Class path of the model provider(e.g. langchain_openai.ChatOpenAI)",
     )
     model: str = Field(..., description="Model name")
-    model_config = ConfigDict(extra="allow")
+    model_config = ConfigDict(extra="allow", frozen=True)
     use_responses_api: bool | None = Field(
         default=None,
         description="Whether to route OpenAI ChatOpenAI calls through the /v1/responses API",

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

@@ -3,8 +3,6 @@ import re
 import shutil
 from pathlib import Path, PureWindowsPath
 
-from deerflow.config.runtime_paths import runtime_home
-
 # Virtual path prefix seen by agents inside the sandbox
 VIRTUAL_PATH_PREFIX = "/mnt/user-data"
 
@@ -13,8 +11,9 @@ _SAFE_USER_ID_RE = re.compile(r"^[A-Za-z0-9_\-]+$")
 
 
 def _default_local_base_dir() -> Path:
-    """Return the caller project's writable DeerFlow state directory."""
+    """Return the repo-local DeerFlow state directory without relying on cwd."""
-    return runtime_home()
+    backend_dir = Path(__file__).resolve().parents[4]
+    return backend_dir / ".deer-flow"
 
 
 def _validate_thread_id(thread_id: str) -> str:
@@ -82,7 +81,7 @@ class Paths:
     BaseDir resolution (in priority order):
         1. Constructor argument `base_dir`
         2. DEER_FLOW_HOME environment variable
-        3. Caller project fallback: `{project_root}/.deer-flow`
+        3. Repo-local fallback derived from this module path: `{backend_dir}/.deer-flow`
     """
 
     def __init__(self, base_dir: str | Path | None = None) -> None:
@@ -132,20 +131,15 @@ class Paths:
 
     @property
     def agents_dir(self) -> Path:
-        """Legacy root for shared (pre user-isolation) custom agents: `{base_dir}/agents/`.
+        """Root directory for all custom agents: `{base_dir}/agents/`."""
-
-        New code should use :meth:`user_agents_dir` instead. This property remains
-        only as a read-side fallback for installations that have not yet run the
-        ``migrate_user_isolation.py`` script.
-        """
         return self.base_dir / "agents"
 
     def agent_dir(self, name: str) -> Path:
-        """Legacy per-agent directory (no user isolation): `{base_dir}/agents/{name}/`."""
+        """Directory for a specific agent: `{base_dir}/agents/{name}/`."""
         return self.agents_dir / name.lower()
 
     def agent_memory_file(self, name: str) -> Path:
-        """Legacy per-agent memory file: `{base_dir}/agents/{name}/memory.json`."""
+        """Per-agent memory file: `{base_dir}/agents/{name}/memory.json`."""
         return self.agent_dir(name) / "memory.json"
 
     def user_dir(self, user_id: str) -> Path:
@@ -156,17 +150,9 @@ class Paths:
         """Per-user memory file: `{base_dir}/users/{user_id}/memory.json`."""
         return self.user_dir(user_id) / "memory.json"
 
-    def user_agents_dir(self, user_id: str) -> Path:
-        """Per-user root for that user's custom agents: `{base_dir}/users/{user_id}/agents/`."""
-        return self.user_dir(user_id) / "agents"
-
-    def user_agent_dir(self, user_id: str, agent_name: str) -> Path:
-        """Per-user per-agent directory: `{base_dir}/users/{user_id}/agents/{name}/`."""
-        return self.user_agents_dir(user_id) / agent_name.lower()
-
     def user_agent_memory_file(self, user_id: str, agent_name: str) -> Path:
         """Per-user per-agent memory: `{base_dir}/users/{user_id}/agents/{name}/memory.json`."""
-        return self.user_agent_dir(user_id, agent_name) / "memory.json"
+        return self.user_dir(user_id) / "agents" / agent_name.lower() / "memory.json"
 
     def thread_dir(self, thread_id: str, *, user_id: str | None = None) -> Path:
         """

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

@@ -15,10 +15,11 @@ from __future__ import annotations
 
 from typing import Literal
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class RunEventsConfig(BaseModel):
+    model_config = ConfigDict(frozen=True)
     backend: Literal["memory", "db", "jsonl"] = Field(
         default="memory",
         description="Storage backend for run events. 'memory' for development (no persistence), 'db' for production (SQL queries), 'jsonl' for lightweight single-node persistence.",

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

@@ -1,41 +0,0 @@
-"""Runtime path resolution for standalone harness usage."""
-
-import os
-from pathlib import Path
-
-
-def project_root() -> Path:
-    """Return the caller project root for runtime-owned files."""
-    if env_root := os.getenv("DEER_FLOW_PROJECT_ROOT"):
-        root = Path(env_root).resolve()
-        if not root.exists():
-            raise ValueError(f"DEER_FLOW_PROJECT_ROOT is set to '{env_root}', but the resolved path '{root}' does not exist.")
-        if not root.is_dir():
-            raise ValueError(f"DEER_FLOW_PROJECT_ROOT is set to '{env_root}', but the resolved path '{root}' is not a directory.")
-        return root
-    return Path.cwd().resolve()
-
-
-def runtime_home() -> Path:
-    """Return the writable DeerFlow state directory."""
-    if env_home := os.getenv("DEER_FLOW_HOME"):
-        return Path(env_home).resolve()
-    return project_root() / ".deer-flow"
-
-
-def resolve_path(value: str | os.PathLike[str], *, base: Path | None = None) -> Path:
-    """Resolve absolute paths as-is and relative paths against the project root."""
-    path = Path(value)
-    if not path.is_absolute():
-        path = (base or project_root()) / path
-    return path.resolve()
-
-
-def existing_project_file(names: tuple[str, ...]) -> Path | None:
-    """Return the first existing named file under the project root."""
-    root = project_root()
-    for name in names:
-        candidate = root / name
-        if candidate.is_file():
-            return candidate
-    return None