fix(task): tolerate invalid default config in usage cache

Merge branch 'main' of https://github.com/bytedance/deer-flow into rayhpeng/storage-package-base
fix(runtime): avoid postgres aggregate row lock (#2962 )
2026-05-15 16:52:11 +08:00 · 2026-05-15 16:41:34 +08:00 · 2026-05-15 10:32:09 +08:00 · 2026-05-15 10:26:35 +08:00 · 2026-05-14 11:27:55 +08:00 · 2026-05-14 11:02:58 +08:00
463 changed files with 35157 additions and 9827 deletions
@@ -1,3 +1,6 @@
+# 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

@@ -6,8 +9,9 @@ JINA_API_KEY=your-jina-api-key

 # InfoQuest API Key
 INFOQUEST_API_KEY=your-infoquest-api-key
-# CORS Origins (comma-separated) - e.g., http://localhost:3000,http://localhost:3001
-# CORS_ORIGINS=http://localhost:3000
+# Browser CORS allowlist for split-origin or port-forwarded deployments (comma-separated exact origins).
+# Leave unset when using the unified nginx endpoint, e.g. http://localhost:2026.
+# GATEWAY_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

 # Optional:
 # FIRECRAWL_API_KEY=your-firecrawl-api-key
@@ -40,3 +44,19 @@ 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
@@ -0,0 +1,101 @@
+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
@@ -46,12 +46,12 @@ Docker provides a consistent, isolated environment with all dependencies pre-con
   All services will start with hot-reload enabled:
   - Frontend changes are automatically reloaded
   - Backend changes trigger automatic restart
-   - LangGraph server supports hot-reload
+   - Gateway-hosted LangGraph-compatible runtime supports hot-reload

 4. **Access the application**:
   - Web Interface: http://localhost:2026
   - API Gateway: http://localhost:2026/api/*
-   - LangGraph: http://localhost:2026/api/langgraph/*
+   - LangGraph-compatible API: http://localhost:2026/api/langgraph/*

 #### Docker Commands

@@ -94,7 +94,7 @@ Use these as practical starting points for development and review environments:
 If `make docker-init`, `make docker-start`, or `make docker-stop` fails on Linux with an error like below, your current user likely does not have permission to access the Docker daemon socket:

 ```text
-unable to get image 'deer-flow-dev-langgraph': permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock
+unable to get image 'deer-flow-gateway': permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock
 ```

 Recommended fix: add your current user to the `docker` group so Docker commands work without `sudo`.
@@ -131,9 +131,8 @@ Host Machine
 Docker Compose (deer-flow-dev)
  ├→ nginx (port 2026) ← Reverse proxy
  ├→ web (port 3000) ← Frontend with hot-reload
-  ├→ api (port 8001) ← Gateway API with hot-reload
-   ├→ langgraph (port 2024) ← LangGraph server with hot-reload
-   └→ provisioner (optional, port 8002) ← Started only in provisioner/K8s sandbox mode
+  ├→ gateway (port 8001) ← Gateway API + LangGraph-compatible runtime with hot-reload
+  └→ provisioner (optional, port 8002) ← Started only in provisioner/K8s sandbox mode
 ```

 **Benefits of Docker Development**:
@@ -184,17 +183,13 @@ Required tools:

 If you need to start services individually:

-1. **Start backend services**:
+1. **Start backend service**:
   ```bash
-   # Terminal 1: Start LangGraph Server (port 2024)
+   # Terminal 1: Start Gateway API + embedded agent runtime (port 8001)
   cd backend
   make dev

-   # Terminal 2: Start Gateway API (port 8001)
-   cd backend
-   make gateway
-
-   # Terminal 3: Start Frontend (port 3000)
+   # Terminal 2: Start Frontend (port 3000)
   cd frontend
   pnpm dev
   ```
@@ -212,10 +207,10 @@ If you need to start services individually:

 The nginx configuration provides:
 - Unified entry point on port 2026
- Routes `/api/langgraph/*` to LangGraph Server (2024)
+- Rewrites `/api/langgraph/*` to Gateway's LangGraph-compatible API (8001)
 - Routes other `/api/*` endpoints to Gateway API (8001)
 - Routes non-API requests to Frontend (3000)
- Centralized CORS handling
+- Same-origin API routing; split-origin or port-forwarded browser clients should use the Gateway `GATEWAY_CORS_ORIGINS` allowlist
 - SSE/streaming support for real-time agent responses
 - Optimized timeouts for long-running operations

@@ -235,8 +230,8 @@ deer-flow/
 │       └── nginx.local.conf # Nginx config for local dev
 ├── backend/                 # Backend application
 │   ├── src/
-│   │   ├── gateway/        # Gateway API (port 8001)
-│   │   ├── agents/         # LangGraph agents (port 2024)
+│   │   ├── gateway/        # Gateway API and LangGraph-compatible runtime (port 8001)
+│   │   ├── agents/         # LangGraph agent runtime used by Gateway
 │   │   ├── mcp/            # Model Context Protocol integration
 │   │   ├── skills/         # Skills system
 │   │   └── sandbox/        # Sandbox execution
@@ -256,8 +251,7 @@ Browser
  ↓
 Nginx (port 2026) ← Unified entry point
  ├→ Frontend (port 3000) ← / (non-API requests)
-  ├→ Gateway API (port 8001) ← /api/models, /api/mcp, /api/skills, /api/threads/*/artifacts
-  └→ LangGraph Server (port 2024) ← /api/langgraph/* (agent interactions)
+  └→ Gateway API (port 8001) ← /api/* and /api/langgraph/* (LangGraph-compatible agent interactions)
 ```

 ## Development Workflow
@@ -245,13 +245,15 @@ make down   # Stop and remove containers

 Access: http://localhost:2026

+The unified nginx endpoint is same-origin by default and does not emit browser CORS headers. If you run a split-origin or port-forwarded browser client, set `GATEWAY_CORS_ORIGINS` to comma-separated exact origins such as `http://localhost:3000`; the Gateway then applies the CORS allowlist and matching CSRF origin checks.
+
 See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed Docker development guide.

 #### Option 2: Local Development

 If you prefer running services locally:

-Prerequisite: complete the "Configuration" steps above first (`make setup`). `make dev` requires a valid `config.yaml` in the project root (can be overridden via `DEER_FLOW_CONFIG_PATH`). Run `make doctor` to verify your setup before starting.
+Prerequisite: complete the "Configuration" steps above first (`make 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.
 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**:
@@ -345,6 +347,7 @@ 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`:**

@@ -414,6 +417,13 @@ 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:
@@ -442,6 +452,10 @@ 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**
@@ -480,6 +494,14 @@ WECOM_BOT_SECRET=your_bot_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**
+
+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**
@@ -606,7 +628,7 @@ See [`skills/public/claude-to-deerflow/SKILL.md`](skills/public/claude-to-deerfl

 Complex tasks rarely fit in a single pass. DeerFlow decomposes them.

-The lead agent can spawn sub-agents on the fly — each with its own scoped context, tools, and termination conditions. Sub-agents run in parallel when possible, report back structured results, and the lead agent synthesizes everything into a coherent output.
+The lead agent can spawn sub-agents on the fly — each with its own scoped context, tools, and termination conditions. Sub-agents run in parallel when possible, report back structured results, and the lead agent synthesizes everything into a coherent output. When token usage tracking is enabled, completed sub-agent usage is attributed back to the dispatching step.

 This is how DeerFlow handles tasks that take minutes to hours: a research task might fan out into a dozen sub-agents, each exploring a different angle, then converge into a single report — or a website — or a slide deck with generated visuals. One harness, many hands.

@@ -228,7 +228,7 @@ make down   # Stop and remove containers
 ```

 > [!NOTE]
-> Le serveur d'agents LangGraph fonctionne actuellement via `langgraph dev` (le serveur CLI open source).
+> Le runtime d'agent s'exécute actuellement dans la Gateway. nginx réécrit `/api/langgraph/*` vers l'API compatible LangGraph servie par la Gateway.

 Accès : http://localhost:2026

@@ -290,13 +290,14 @@ 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` :**

 ```yaml
 channels:
-  # LangGraph Server URL (default: http://localhost:2024)
-  langgraph_url: http://localhost:2024
+  # LangGraph-compatible Gateway API base URL (default: http://localhost:8001/api)
+  langgraph_url: http://localhost:8001/api
  # Gateway API URL (default: http://localhost:8001)
  gateway_url: http://localhost:8001

@@ -341,6 +342,13 @@ 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` :
@@ -356,6 +364,10 @@ 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**
@@ -378,6 +390,13 @@ FEISHU_APP_SECRET=your_app_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 :
@@ -181,7 +181,7 @@ make down   # コンテナを停止して削除
 ```

 > [!NOTE]
-> LangGraphエージェントサーバーは現在`langgraph dev`（オープンソースCLIサーバー）経由で実行されます。
+> Agentランタイムは現在Gateway内で実行されます。`/api/langgraph/*`はnginxによってGatewayのLangGraph-compatible APIへ書き換えられます。

 アクセス: http://localhost:2026

@@ -243,13 +243,14 @@ DeerFlowはメッセージングアプリからのタスク受信をサポート
 | Telegram | Bot API（ロングポーリング） | 簡単 |
 | Slack | Socket Mode | 中程度 |
 | Feishu / Lark | WebSocket | 中程度 |
+| DingTalk | Stream Push（WebSocket） | 中程度 |

 **`config.yaml`での設定：**

 ```yaml
 channels:
-  # LangGraphサーバーURL（デフォルト: http://localhost:2024）
-  langgraph_url: http://localhost:2024
+  # LangGraph-compatible Gateway API base URL（デフォルト: http://localhost:8001/api）
+  langgraph_url: http://localhost:8001/api
  # Gateway API URL（デフォルト: http://localhost:8001）
  gateway_url: http://localhost:8001

@@ -294,6 +295,13 @@ 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`ファイルに設定します：
@@ -309,6 +317,10 @@ 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のセットアップ**
@@ -331,6 +343,13 @@ FEISHU_APP_SECRET=your_app_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と対話できます：
@@ -256,6 +256,7 @@ DeerFlow принимает задачи прямо из мессенджеро
 | Telegram | Bot API (long-polling) | Просто |
 | Slack | Socket Mode | Средне |
 | Feishu / Lark | WebSocket | Средне |
+| DingTalk | Stream Push (WebSocket) | Средне |

 **Конфигурация в `config.yaml`:**

@@ -278,6 +279,13 @@ 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**
@@ -285,6 +293,13 @@ 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`.
+
 **Доступные команды**

 | Команда | Описание |
@@ -184,7 +184,7 @@ make down   # 停止并移除容器
 ```

 > [!NOTE]
-> 当前 LangGraph agent server 通过开源 CLI 服务 `langgraph dev` 运行。
+> 当前 Agent 运行时嵌入在 Gateway 中运行，`/api/langgraph/*` 会由 nginx 重写到 Gateway 的 LangGraph-compatible API。

 访问地址：http://localhost:2026

@@ -194,7 +194,7 @@ make down   # 停止并移除容器

 如果你更希望直接在本地启动各个服务：

-前提：先完成上面的“配置”步骤（`make config` 和模型 API key 配置）。`make dev` 需要有效配置文件，默认读取项目根目录下的 `config.yaml`，也可以通过 `DEER_FLOW_CONFIG_PATH` 覆盖。
+前提：先完成上面的“配置”步骤（`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` 覆盖。
 在 Windows 上，请使用 Git Bash 运行本地开发流程。基于 bash 的服务脚本不支持直接在原生 `cmd.exe` 或 PowerShell 中执行，且 WSL 也不保证可用，因为部分脚本依赖 Git for Windows 的 `cygpath` 等工具。

 1. **检查依赖环境**：
@@ -248,13 +248,14 @@ DeerFlow 支持从即时通讯应用接收任务。只要配置完成，对应
 | Slack | Socket Mode | 中等 |
 | Feishu / Lark | WebSocket | 中等 |
 | 企业微信智能机器人 | WebSocket | 中等 |
+| 钉钉 | Stream Push（WebSocket） | 中等 |

 **`config.yaml` 中的配置示例：**

 ```yaml
 channels:
-  # LangGraph Server URL（默认：http://localhost:2024）
-  langgraph_url: http://localhost:2024
+  # LangGraph-compatible Gateway API base URL（默认：http://localhost:8001/api）
+  langgraph_url: http://localhost:8001/api
  # Gateway API URL（默认：http://localhost:8001）
  gateway_url: http://localhost:8001

@@ -304,6 +305,13 @@ 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，用于流式打字机效果
 ```

 说明：
@@ -327,6 +335,10 @@ 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 配置**
@@ -357,6 +369,13 @@ WECOM_BOT_SECRET=your_bot_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 交互：
@@ -112,7 +112,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).
+- **App** (`app/`): Unpublished application code. Import prefix: `app.*`. Contains the FastAPI Gateway API and IM channel integrations (Feishu, Slack, Telegram, DingTalk).

 **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 +127,7 @@ from app.gateway.app import app
 from app.channels.service import start_channel_service

 # App → Harness (allowed)
-from deerflow.config.app_config import AppConfig
+from deerflow.config import get_app_config

 # Harness → App (FORBIDDEN — enforced by test_harness_boundary.py)
 # from app.gateway.routers.uploads import ...  # ← will fail CI
@@ -165,7 +165,7 @@ Lead-agent middlewares are assembled in strict append order across `packages/har
 8. **ToolErrorHandlingMiddleware** - Converts tool exceptions into error `ToolMessage`s so the run can continue instead of aborting
 9. **SummarizationMiddleware** - Context reduction when approaching token limits (optional, if enabled)
 10. **TodoListMiddleware** - Task tracking with `write_todos` tool (optional, if plan_mode)
-11. **TokenUsageMiddleware** - Records token usage metrics when token tracking is enabled (optional)
+11. **TokenUsageMiddleware** - Records token usage metrics when token tracking is enabled (optional); subagent usage is cached by `tool_call_id` only while token usage is enabled and merged back into the dispatching AIMessage by message position rather than message id
 12. **TitleMiddleware** - Auto-generates thread title after first complete exchange and normalizes structured message content before prompting the title model
 13. **MemoryMiddleware** - Queues conversations for async memory update (filters to user + final AI responses)
 14. **ViewImageMiddleware** - Injects base64 image data before LLM call (conditional on vision support)
@@ -182,16 +182,7 @@ 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 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.
+**Config Caching**: `get_app_config()` caches the parsed config, but automatically reloads it when the resolved config path changes or the file's mtime increases. This keeps Gateway and LangGraph reads aligned with `config.yaml` edits without requiring a manual process restart.

 Configuration priority:
 1. Explicit `config_path` argument
@@ -214,7 +205,9 @@ Configuration priority:

 ### Gateway API (`app/gateway/`)

-FastAPI application on port 8001 with health check at `GET /health`.
+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).
+
+CORS is same-origin by default when requests enter through nginx on port 2026. Split-origin or port-forwarded browser clients must opt in with `GATEWAY_CORS_ORIGINS` (comma-separated exact origins); Gateway `CORSMiddleware` and `CSRFMiddleware` both read that variable so browser CORS and auth-origin checks stay aligned.

 **Routers**:

@@ -232,7 +225,7 @@ FastAPI application on port 8001 with health check at `GET /health`.
 | **Feedback** (`/api/threads/{id}/runs/{rid}/feedback`) | `PUT /` - upsert feedback; `DELETE /` - delete user feedback; `POST /` - create feedback; `GET /` - list feedback; `GET /stats` - aggregate stats; `DELETE /{fid}` - delete specific |
 | **Runs** (`/api/runs`) | `POST /stream` - stateless run + SSE; `POST /wait` - stateless run + block; `GET /{rid}/messages` - paginated messages by run_id `{data, has_more}` (cursor: `after_seq`/`before_seq`); `GET /{rid}/feedback` - list feedback by run_id |

-Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` → Gateway.
+Proxied through nginx: `/api/langgraph/*` → Gateway LangGraph-compatible runtime, all other `/api/*` → Gateway REST APIs.

 ### Sandbox System (`packages/harness/deerflow/sandbox/`)

@@ -252,7 +245,7 @@ Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` →
 - `bash` - Execute commands with path translation and error handling
 - `ls` - Directory listing (tree format, max 2 levels)
 - `read_file` - Read file contents with optional line range
- `write_file` - Write/append to files, creates directories
+- `write_file` - Write/append to files, creates directories; overwrites by default and exposes the `append` argument in the model-facing schema for end-of-file writes
 - `str_replace` - Substring replacement (single or all occurrences); same-path serialization is scoped to `(sandbox.id, path)` so isolated sandboxes do not contend on identical virtual paths inside one process

 ### Subagent System (`packages/harness/deerflow/subagents/`)
@@ -272,8 +265,10 @@ 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, max_turns)
+   - `task` - Delegate to subagent (description, prompt, subagent_type)

 **Community tools** (`packages/harness/deerflow/community/`):
 - `tavily/` - Web search (5 results default) and web fetch (4KB limit)
@@ -321,7 +316,8 @@ Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` →

 ### IM Channels System (`app/channels/`)

-Bridges external messaging platforms (Feishu, Slack, Telegram) to the DeerFlow agent via Gateway's LangGraph-compatible API.
+Bridges external messaging platforms (Feishu, Slack, Telegram, DingTalk) to the DeerFlow agent via the LangGraph Server.
+

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

@@ -331,7 +327,7 @@ Bridges external messaging platforms (Feishu, Slack, Telegram) to the DeerFlow a
 - `manager.py` - Core dispatcher: creates threads via `client.threads.create()`, routes commands, keeps Slack/Telegram on `client.runs.wait()`, and uses `client.runs.stream(["messages-tuple", "values"])` for Feishu incremental outbound updates
 - `base.py` - Abstract `Channel` base class (start/stop/send lifecycle)
 - `service.py` - Manages lifecycle of all configured channels from `config.yaml`
- `slack.py` / `feishu.py` / `telegram.py` - Platform-specific implementations (`feishu.py` tracks the running card `message_id` in memory and patches the same card in place)
+- `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)

 **Message Flow**:
 1. External platform -> Channel impl -> `MessageBus.publish_inbound()`
@@ -340,14 +336,16 @@ Bridges external messaging platforms (Feishu, Slack, Telegram) to the DeerFlow a
 4. Feishu chat: `runs.stream()` → accumulate AI text → publish multiple outbound updates (`is_final=False`) → publish final outbound (`is_final=True`)
 5. Slack/Telegram chat: `runs.wait()` → extract final response → publish outbound
 6. Feishu channel sends one running reply card up front, then patches the same card for each outbound update (card JSON sets `config.update_multi=true` for Feishu's patch API requirement)
-7. For commands (`/new`, `/status`, `/models`, `/memory`, `/help`): handle locally or query Gateway API
-8. Outbound → channel callbacks → platform reply
+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
+8. For commands (`/new`, `/status`, `/models`, `/memory`, `/help`): handle locally or query Gateway API
+9. Outbound → channel callbacks → platform reply

 **Configuration** (`config.yaml` -> `channels`):
 - `langgraph_url` - LangGraph-compatible Gateway API base URL (default: `http://localhost:8001/api`)
 - `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`.
- Per-channel configs: `feishu` (app_id, app_secret), `slack` (bot_token, app_token), `telegram` (bot_token)
+- 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)
+

 ### Memory System (`packages/harness/deerflow/agents/memory/`)

@@ -360,10 +358,11 @@ Bridges external messaging platforms (Feishu, Slack, Telegram) to the DeerFlow a
 **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` and `threads/` into per-user layout; supports `--dry-run`
+- **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`).

 **Data Structure** (stored in `{base_dir}/users/{user_id}/memory.json`):
 - **User Context**: `workContext`, `personalContext`, `topOfMind` (1-3 sentence summaries)
@@ -523,6 +522,7 @@ 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.
@@ -56,11 +56,8 @@ export OPENAI_API_KEY="your-api-key"
 ### Run the Development Server

 ```bash
-# Terminal 1: LangGraph server
+# Gateway API + embedded agent runtime
 make dev
-
-# Terminal 2: Gateway API
-make gateway
 ```

 ## Project Structure
@@ -50,6 +50,12 @@ 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.
@@ -66,6 +72,10 @@ 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
@@ -11,31 +11,26 @@ DeerFlow is a LangGraph-based AI super agent with sandbox execution, persistent
                        │          Nginx (Port 2026)           │
                        │      Unified reverse proxy           │
                        └───────┬──────────────────┬───────────┘
-                                │                  │
-              /api/langgraph/*  │                  │  /api/* (other)
-                                ▼                  ▼
-               ┌────────────────────┐  ┌────────────────────────┐
-               │ LangGraph Server   │  │   Gateway API (8001)   │
-               │    (Port 2024)     │  │   FastAPI REST         │
-               │                    │  │                        │
-               │ ┌────────────────┐ │  │ Models, MCP, Skills,   │
-               │ │  Lead Agent    │ │  │ Memory, Uploads,       │
-               │ │  ┌──────────┐  │ │  │ Artifacts              │
-               │ │  │Middleware│  │ │  └────────────────────────┘
-               │ │  │  Chain   │  │ │
-               │ │  └──────────┘  │ │
-               │ │  ┌──────────┐  │ │
-               │ │  │  Tools   │  │ │
-               │ │  └──────────┘  │ │
-               │ │  ┌──────────┐  │ │
-               │ │  │Subagents │  │ │
-               │ │  └──────────┘  │ │
-               │ └────────────────┘ │
-               └────────────────────┘
+                                │
+            /api/langgraph/*    │    /api/* (other)
+            rewritten to /api/* │
+                                ▼
+               ┌────────────────────────────────────────┐
+               │        Gateway API (8001)              │
+               │        FastAPI REST + agent runtime    │
+               │                                        │
+               │ Models, MCP, Skills, Memory, Uploads,  │
+               │ Artifacts, Threads, Runs, Streaming    │
+               │                                        │
+               │ ┌────────────────────────────────────┐ │
+               │ │ Lead Agent                         │ │
+               │ │ Middleware Chain, Tools, Subagents │ │
+               │ └────────────────────────────────────┘ │
+               └────────────────────────────────────────┘
 ```

 **Request Routing** (via Nginx):
- `/api/langgraph/*` → LangGraph Server - agent interactions, threads, streaming
+- `/api/langgraph/*` → Gateway LangGraph-compatible API - agent interactions, threads, streaming
 - `/api/*` (other) → Gateway API - models, MCP, skills, memory, artifacts, uploads, thread-local cleanup
 - `/` (non-API) → Frontend - Next.js web interface

@@ -79,7 +74,7 @@ Per-thread isolated execution with virtual path translation:
 - **Skills path**: `/mnt/skills` → `deer-flow/skills/` directory
 - **Skills loading**: Recursively discovers nested `SKILL.md` files under `skills/{public,custom}` and preserves nested container paths
 - **File-write safety**: `str_replace` serializes read-modify-write per `(sandbox.id, path)` so isolated sandboxes keep concurrency even when virtual paths match
- **Tools**: `bash`, `ls`, `read_file`, `write_file`, `str_replace` (`bash` is disabled by default when using `LocalSandboxProvider`; use `AioSandboxProvider` for isolated shell access)
+- **Tools**: `bash`, `ls`, `read_file`, `write_file`, `str_replace` (`write_file` overwrites by default and exposes `append` for end-of-file writes; `bash` is disabled by default when using `LocalSandboxProvider`; use `AioSandboxProvider` for isolated shell access)

 ### Subagent System

@@ -124,7 +119,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) |
+| `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) |
 | `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 |
@@ -193,7 +188,7 @@ export OPENAI_API_KEY="your-api-key-here"
 **Full Application** (from project root):

 ```bash
-make dev  # Starts LangGraph + Gateway + Frontend + Nginx
+make dev  # Starts Gateway + Frontend + Nginx
 ```

 Access at: http://localhost:2026
@@ -201,14 +196,11 @@ Access at: http://localhost:2026
 **Backend Only** (from backend directory):

 ```bash
-# Terminal 1: LangGraph server
+# Gateway API + embedded agent runtime
 make dev
-
-# Terminal 2: Gateway API
-make gateway
 ```

-Direct access: LangGraph at http://localhost:2024, Gateway at http://localhost:8001
+Direct access: Gateway at http://localhost:8001

 ---

@@ -244,12 +236,16 @@ backend/
 │   └── utils/                  # Utilities
 ├── docs/                       # Documentation
 ├── tests/                      # Test suite
-├── langgraph.json              # LangGraph server configuration
+├── langgraph.json              # LangGraph graph registry for tooling/Studio compatibility
 ├── pyproject.toml              # Python dependencies
 ├── Makefile                    # Development commands
 └── Dockerfile                  # Container build
 ```

+`langgraph.json` is not the default service entrypoint.  The scripts and Docker
+deployments run the Gateway embedded runtime; the file is kept for LangGraph
+tooling, Studio, or direct LangGraph Server compatibility.
+
 ---

 ## Configuration
@@ -362,8 +358,8 @@ If a provider is explicitly enabled but required credentials are missing, or the

 ```bash
 make install    # Install dependencies
-make dev        # Run LangGraph server (port 2024)
-make gateway    # Run Gateway API (port 8001)
+make dev        # Run Gateway API + embedded agent runtime (port 8001)
+make gateway    # Run Gateway API without reload (port 8001)
 make lint       # Run linter (ruff)
 make format     # Format code (ruff)
 ```
@@ -31,6 +31,10 @@ class Channel(ABC):
    def is_running(self) -> bool:
        return self._running

+    @property
+    def supports_streaming(self) -> bool:
+        return False
+
    # -- lifecycle ---------------------------------------------------------

    @abstractmethod
@@ -0,0 +1,740 @@
+"""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"
@@ -63,6 +63,10 @@ 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
@@ -375,9 +379,7 @@ class FeishuChannel(Channel):
        virtual_path = f"{VIRTUAL_PATH_PREFIX}/uploads/{resolved_target.name}"

        try:
-            from deerflow.config.app_config import AppConfig
-
-            sandbox_provider = get_sandbox_provider(AppConfig.from_file())
+            sandbox_provider = get_sandbox_provider()
            sandbox_id = sandbox_provider.acquire(thread_id)
            if sandbox_id != "local":
                sandbox = sandbox_provider.get(sandbox_id)
@@ -17,6 +17,8 @@ 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__)
@@ -36,6 +38,7 @@ 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},
@@ -46,6 +49,13 @@ 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] = {}

@@ -136,6 +146,13 @@ 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.

@@ -145,7 +162,7 @@ def _extract_response_text(result: dict | list) -> str:
    Handles special cases:
    - Regular AI text responses
    - Clarification interrupts (``ask_clarification`` tool messages)
-    - AI messages with tool_calls but no text content
+    - Strips loop-detection warnings attached to tool-call AI messages
    """
    if isinstance(result, list):
        messages = result
@@ -175,7 +192,12 @@ 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):
@@ -186,6 +208,8 @@ 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 ""
@@ -410,7 +434,13 @@ async def _ingest_inbound_files(thread_id: str, msg: InboundMessage) -> list[dic
    if not msg.files:
        return []

-    from deerflow.uploads.manager import claim_unique_filename, ensure_uploads_dir, normalize_filename
+    from deerflow.uploads.manager import (
+        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()}
@@ -461,7 +491,10 @@ async def _ingest_inbound_files(thread_id: str, msg: InboundMessage) -> list[dic

            dest = uploads_dir / safe_name
            try:
-                dest.write_bytes(data)
+                dest = write_upload_file_no_symlink(uploads_dir, safe_name, 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
@@ -541,6 +574,13 @@ class ChannelManager:

    @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]]:
@@ -563,6 +603,17 @@ 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"),
@@ -770,6 +821,7 @@ 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)
@@ -831,6 +883,7 @@ class ChannelManager:
                        text=latest_text,
                        is_final=False,
                        thread_ts=msg.thread_ts,
+                        metadata=_slim_metadata(msg.metadata),
                    )
                )
                last_published_text = latest_text
@@ -875,6 +928,7 @@ class ChannelManager:
                    attachments=attachments,
                    is_final=True,
                    thread_ts=msg.thread_ts,
+                    metadata=_slim_metadata(msg.metadata),
                )
            )

@@ -933,6 +987,7 @@ 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)

@@ -942,7 +997,11 @@ class ChannelManager:

        try:
            async with httpx.AsyncClient() as http:
-                resp = await http.get(f"{self._gateway_url}{path}", timeout=10)
+                resp = await http.get(
+                    f"{self._gateway_url}{path}",
+                    timeout=10,
+                    headers=create_internal_auth_headers(),
+                )
                resp.raise_for_status()
                data = resp.json()
        except Exception:
@@ -966,5 +1025,6 @@ 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)
@@ -11,13 +11,14 @@ 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",
@@ -28,6 +29,7 @@ _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"],
@@ -78,8 +80,12 @@ class ChannelService:
        self._running = False

    @classmethod
-    def from_app_config(cls, app_config: AppConfig) -> ChannelService:
-        """Create a ChannelService from an explicit application config."""
+    def from_app_config(cls, app_config: AppConfig | None = None) -> ChannelService:
+        """Create a ChannelService from the 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 {}
@@ -162,11 +168,16 @@ class ChannelService:

        try:
            channel = channel_cls(bus=self.bus, config=config)
-            await channel.start()
            self._channels[name] = channel
+            await channel.start()
+            if not channel.is_running:
+                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

@@ -201,7 +212,7 @@ def get_channel_service() -> ChannelService | None:
    return _channel_service


-async def start_channel_service(app_config: AppConfig) -> ChannelService:
+async def start_channel_service(app_config: AppConfig | None = None) -> ChannelService:
    """Create and start the global ChannelService from app config."""
    global _channel_service
    if _channel_service is not None:
@@ -29,6 +29,10 @@ 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
@@ -1,6 +1,5 @@
 import asyncio
 import logging
-import os
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager

@@ -9,7 +8,7 @@ from fastapi.middleware.cors import CORSMiddleware

 from app.gateway.auth_middleware import AuthMiddleware
 from app.gateway.config import get_gateway_config
-from app.gateway.csrf_middleware import CSRFMiddleware
+from app.gateway.csrf_middleware import CSRFMiddleware, get_configured_cors_origins
 from app.gateway.deps import langgraph_runtime
 from app.gateway.routers import (
    agents,
@@ -28,9 +27,13 @@ from app.gateway.routers import (
    threads,
    uploads,
 )
-from deerflow.config.app_config import AppConfig
+from deerflow.config import app_config as deerflow_app_config
+from deerflow.config.app_config import apply_logging_level

-# Configure logging
+AppConfig = deerflow_app_config.AppConfig
+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",
@@ -59,7 +62,7 @@ async def _ensure_admin_user(app: FastAPI) -> None:

    Subsequent boots (admin already exists):
      - Runs the one-time "no-auth → with-auth" orphan thread migration for
-        existing LangGraph thread metadata that has no owner_id.
+        existing LangGraph thread metadata that has no user_id.

    No SQL persistence migration is needed: the four user_id columns
    (threads_meta, runs, run_events, feedback) only come into existence
@@ -72,7 +75,18 @@ async def _ensure_admin_user(app: FastAPI) -> None:
    from deerflow.persistence.engine import get_session_factory
    from deerflow.persistence.user.model import UserRow

-    provider = get_local_provider()
+    try:
+        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:
@@ -84,10 +98,6 @@ 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()
@@ -151,11 +161,10 @@ 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`` is the sole source of truth for
-        # ``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()
+        app.state.config = get_app_config()
+        apply_logging_level(app.state.config.log_level)
        logger.info("Configuration loaded successfully")
    except Exception as e:
        error_msg = f"Failed to load configuration during gateway startup: {e}"
@@ -168,7 +177,7 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
    async with langgraph_runtime(app):
        logger.info("LangGraph runtime initialised")

-        # Ensure admin user exists (auto-create on first boot)
+        # Check admin bootstrap state and migrate orphan threads after admin exists.
        # Must run AFTER langgraph_runtime so app.state.store is available for thread migration
        await _ensure_admin_user(app)

@@ -208,6 +217,10 @@ def create_app() -> FastAPI:
    Returns:
        Configured FastAPI application instance.
    """
+    config = get_gateway_config()
+    docs_url = "/docs" if config.enable_docs else None
+    redoc_url = "/redoc" if config.enable_docs else None
+    openapi_url = "/openapi.json" if config.enable_docs else None

    app = FastAPI(
        title="DeerFlow API Gateway",
@@ -227,14 +240,14 @@ API Gateway for DeerFlow - A LangGraph-based AI agent backend with sandbox execu

 ### Architecture

-LangGraph requests are handled by nginx reverse proxy.
-This gateway provides custom endpoints for models, MCP configuration, skills, and artifacts.
+LangGraph-compatible requests are routed through nginx to this gateway.
+This gateway provides runtime endpoints for agent runs plus custom endpoints for models, MCP configuration, skills, and artifacts.
        """,
        version="0.1.0",
        lifespan=lifespan,
-        docs_url="/docs",
-        redoc_url="/redoc",
-        openapi_url="/openapi.json",
+        docs_url=docs_url,
+        redoc_url=redoc_url,
+        openapi_url=openapi_url,
        openapi_tags=[
            {
                "name": "models",
@@ -297,25 +310,18 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
    # CSRF: Double Submit Cookie pattern for state-changing requests
    app.add_middleware(CSRFMiddleware)

-    # CORS: when GATEWAY_CORS_ORIGINS is set (dev without nginx), add CORS middleware.
-    # In production, nginx handles CORS and no middleware is needed.
-    cors_origins_env = os.environ.get("GATEWAY_CORS_ORIGINS", "")
-    if cors_origins_env:
-        cors_origins = [o.strip() for o in cors_origins_env.split(",") if o.strip()]
-        # Validate: wildcard origin with credentials is a security misconfiguration
-        for origin in cors_origins:
-            if origin == "*":
-                logger.error("GATEWAY_CORS_ORIGINS contains wildcard '*' with allow_credentials=True. This is a security misconfiguration — browsers will reject the response. Use explicit scheme://host:port origins instead.")
-                cors_origins = [o for o in cors_origins if o != "*"]
-                break
-        if cors_origins:
-            app.add_middleware(
-                CORSMiddleware,
-                allow_origins=cors_origins,
-                allow_credentials=True,
-                allow_methods=["*"],
-                allow_headers=["*"],
-            )
+    # CORS: the unified nginx endpoint is same-origin by default. Split-origin
+    # browser clients must opt in with this explicit Gateway allowlist so CORS
+    # and CSRF origin checks share the same source of truth.
+    cors_origins = sorted(get_configured_cors_origins())
+    if cors_origins:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=cors_origins,
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )

    # Include routers
    # Models API is mounted at /api/models
@@ -364,7 +370,7 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
    app.include_router(runs.router)

    @app.get("/health", tags=["health"])
-    async def health_check() -> dict:
+    async def health_check() -> dict[str, str]:
        """Health check endpoint.

        Returns:
@@ -4,11 +4,8 @@ import logging
 import os
 import secrets

-from dotenv import load_dotenv
 from pydantic import BaseModel, Field

-load_dotenv()
-
 logger = logging.getLogger(__name__)


@@ -37,6 +34,9 @@ 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)
@@ -1,10 +1,14 @@
 """Local email/password authentication provider."""

+import logging
+
 from app.gateway.auth.models import User
-from app.gateway.auth.password import hash_password_async, verify_password_async
+from app.gateway.auth.password import hash_password_async, needs_rehash, 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."""
@@ -43,6 +47,15 @@ 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:
@@ -28,7 +28,7 @@ class User(BaseModel):
    oauth_id: str | None = Field(None, description="User ID from OAuth provider")

    # Auth lifecycle
-    needs_setup: bool = Field(default=False, description="True for auto-created admin until setup completes")
+    needs_setup: bool = Field(default=False, description="True when a reset account must complete setup")
    token_version: int = Field(default=0, description="Incremented on password change to invalidate old JWTs")


@@ -1,18 +1,66 @@
-"""Password hashing utilities using bcrypt directly."""
+"""Password hashing utilities with versioned hash format.
+
+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 using bcrypt."""
-    return bcrypt.hashpw(password.encode("utf-8"), bcrypt.gensalt()).decode("utf-8")
+    """Hash a password (current version: v2 — SHA-256 + bcrypt)."""
+    raw = bcrypt.hashpw(_pre_hash_v2(password), bcrypt.gensalt()).decode("utf-8")
+    return f"{_PREFIX_V2}{raw}"


 def verify_password(plain_password: str, hashed_password: str) -> bool:
-    """Verify a password against its hash."""
-    return bcrypt.checkpw(plain_password.encode("utf-8"), hashed_password.encode("utf-8"))
+    """Verify a password, auto-detecting the hash version.
+
+    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:
@@ -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
@@ -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
@@ -25,15 +25,14 @@ from deerflow.persistence.user.model import UserRow


 async def _run(email: str | None) -> int:
-    from deerflow.config import AppConfig
+    from deerflow.config import get_app_config
    from deerflow.persistence.engine import (
        close_engine,
        get_session_factory,
        init_engine_from_config,
    )

-    # CLI entry: load config explicitly at the top, pass down through the closure.
-    config = AppConfig.from_file()
+    config = get_app_config()
    await init_engine_from_config(config.database)
    try:
        sf = get_session_factory()
@@ -18,6 +18,7 @@ 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.
@@ -75,8 +76,12 @@ 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 not request.cookies.get("access_token"):
+        if internal_user is None and not request.cookies.get("access_token"):
            return JSONResponse(
                status_code=401,
                content={
@@ -100,10 +105,13 @@ class AuthMiddleware(BaseHTTPMiddleware):
        # bubble up, so we catch and render it as JSONResponse here.
        from app.gateway.deps import get_current_user_from_request

-        try:
-            user = await get_current_user_from_request(request)
-        except HTTPException as exc:
-            return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
+        if internal_user is not None:
+            user = internal_user
+        else:
+            try:
+                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
@@ -30,7 +30,9 @@ 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
@@ -117,6 +119,15 @@ _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.

@@ -134,7 +145,11 @@ async def _authenticate(request: Request) -> AuthContext:


 def require_auth[**P, T](func: Callable[P, T]) -> Callable[P, T]:
-    """Decorator that authenticates the request and sets AuthContext.
+    """Decorator that authenticates the request and enforces authentication.
+
+    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).

@@ -147,19 +162,33 @@ def require_auth[**P, T](func: Callable[P, T]) -> Callable[P, T]:
            ...

    Raises:
-        ValueError: If 'request' parameter is missing
+        HTTPException: 401 if the request is unauthenticated.
+        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:
-            raise ValueError("require_auth decorator requires 'request' parameter")
+            # Unit tests may call decorated handlers directly without a
+            # 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
@@ -210,7 +239,17 @@ def require_permission(
        async def wrapper(*args: Any, **kwargs: Any) -> Any:
            request = kwargs.get("request")
            if request is None:
-                raise ValueError("require_permission decorator requires 'request' parameter")
+                # Unit tests may call decorated route handlers directly without
+                # 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:
@@ -8,7 +8,7 @@ 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
@@ -18,10 +18,9 @@ def get_gateway_config() -> GatewayConfig:
    """Get gateway config, loading from environment if available."""
    global _gateway_config
    if _gateway_config is None:
-        cors_origins_str = os.getenv("CORS_ORIGINS", "http://localhost:3000")
        _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
@@ -4,8 +4,10 @@ Per RFC-001:
 State-changing operations require CSRF protection.
 """

+import os
 import secrets
-from collections.abc import Callable
+from collections.abc import Awaitable, Callable
+from urllib.parse import urlsplit

 from fastapi import Request, Response
 from starlette.middleware.base import BaseHTTPMiddleware
@@ -19,7 +21,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.headers.get("x-forwarded-proto", request.url.scheme) == "https"
+    return _request_scheme(request) == "https"


 def generate_csrf_token() -> str:
@@ -61,15 +63,129 @@ 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 get_configured_cors_origins() -> set[str]:
+    """Return normalized explicit browser origins from GATEWAY_CORS_ORIGINS."""
+    return _configured_cors_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."""

    def __init__(self, app: ASGIApp) -> None:
        super().__init__(app)

-    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+    async def dispatch(self, request: Request, call_next: Callable[[Request], Awaitable[Response]]) -> 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)
@@ -10,13 +10,16 @@ from __future__ import annotations

 from collections.abc import AsyncGenerator, Callable
 from contextlib import AsyncExitStack, asynccontextmanager
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, TypeVar, cast

 from fastapi import FastAPI, HTTPException, Request
 from langgraph.types import Checkpointer

 from deerflow.config.app_config import AppConfig
-from deerflow.runtime import RunContext, RunManager
+from deerflow.persistence.feedback import FeedbackRepository
+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
@@ -24,17 +27,15 @@ if TYPE_CHECKING:
    from deerflow.persistence.thread_meta.base import ThreadMetaStore


-def get_config(request: Request) -> AppConfig:
-    """FastAPI dependency returning the app-scoped ``AppConfig``.
+T = TypeVar("T")

-    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:
+
+def get_config(request: Request) -> AppConfig:
+    """Return the app-scoped ``AppConfig`` stored on ``app.state``."""
+    config = getattr(request.app.state, "config", None)
+    if config is None:
        raise HTTPException(status_code=503, detail="Configuration not available")
-    return cfg
+    return config


@asynccontextmanager
@@ -52,9 +53,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:
-        # app.state.config is populated earlier in lifespan(); thread it
-        # explicitly into every provider below.
-        config = app.state.config
+        config = getattr(app.state, "config", None)
+        if config is None:
+            raise RuntimeError("langgraph_runtime() requires app.state.config to be initialized")

        app.state.stream_bridge = await stack.enter_async_context(make_stream_bridge(config))

@@ -101,25 +102,25 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
 # ---------------------------------------------------------------------------


-def _require(attr: str, label: str):
+def _require(attr: str, label: str) -> Callable[[Request], T]:
    """Create a FastAPI dependency that returns ``app.state.<attr>`` or 503."""

-    def dep(request: Request):
+    def dep(request: Request) -> T:
        val = getattr(request.app.state, attr, None)
        if val is None:
            raise HTTPException(status_code=503, detail=f"{label} not available")
-        return val
+        return cast(T, val)

    dep.__name__ = dep.__qualname__ = f"get_{attr}"
    return dep


-get_stream_bridge = _require("stream_bridge", "Stream bridge")
-get_run_manager = _require("run_manager", "Run manager")
-get_checkpointer = _require("checkpointer", "Checkpointer")
-get_run_event_store = _require("run_event_store", "Run event store")
-get_feedback_repo = _require("feedback_repo", "Feedback")
-get_run_store = _require("run_store", "Run store")
+get_stream_bridge: Callable[[Request], StreamBridge] = _require("stream_bridge", "Stream bridge")
+get_run_manager: Callable[[Request], RunManager] = _require("run_manager", "Run manager")
+get_checkpointer: Callable[[Request], Checkpointer] = _require("checkpointer", "Checkpointer")
+get_run_event_store: Callable[[Request], RunEventStore] = _require("run_event_store", "Run event store")
+get_feedback_repo: Callable[[Request], FeedbackRepository] = _require("feedback_repo", "Feedback")
+get_run_store: Callable[[Request], RunStore] = _require("run_store", "Run store")


 def get_store(request: Request):
@@ -138,10 +139,7 @@ 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.  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`.
+    Returns a *base* context with infrastructure dependencies.
    """
    config = get_config(request)
    return RunContext(
@@ -154,7 +152,6 @@ def get_run_context(request: Request) -> RunContext:
    )


-
 # ---------------------------------------------------------------------------
 # Auth helpers (used by authz.py and auth middleware)
 # ---------------------------------------------------------------------------
@@ -1,8 +1,12 @@
-"""LangGraph Server auth handler — shares JWT logic with Gateway.
+"""LangGraph compatibility auth handler — shares JWT logic with Gateway.

-Loaded by LangGraph Server via langgraph.json ``auth.path``.
-Reuses the same ``decode_token`` / ``get_auth_config`` as Gateway,
-so both modes validate tokens with the same secret and rules.
+The default DeerFlow runtime is embedded in the FastAPI Gateway; scripts and
+Docker deployments do not load this module.  It is retained for LangGraph
+tooling, Studio, or direct LangGraph Server compatibility through
+``langgraph.json``'s ``auth.path``.
+
+When that compatibility path is used, this module reuses the same JWT and CSRF
+rules as Gateway so both modes validate sessions consistently.

 Two layers:
  1. @auth.authenticate — validates JWT cookie, extracts user_id,
@@ -73,7 +77,7 @@ async def authenticate(request):
    if isinstance(payload, TokenError):
        raise Auth.exceptions.HTTPException(
            status_code=401,
-            detail=f"Token error: {payload.value}",
+            detail="Invalid token",
        )

    user = await get_local_provider().get_user(payload.sub)
@@ -5,13 +5,13 @@ import re
 import shutil

 import yaml
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel, Field

-from app.gateway.deps import get_config
+from deerflow.config.agents_api_config import get_agents_api_config
 from deerflow.config.agents_config import AgentConfig, list_custom_agents, load_agent_config, load_agent_soul
-from deerflow.config.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(app_config: AppConfig) -> None:
+def _require_agents_api_enabled() -> None:
    """Reject access unless the custom-agent management API is explicitly enabled."""
-    if not app_config.agents_api.enabled:
+    if not get_agents_api_config().enabled:
        raise HTTPException(
            status_code=403,
            detail=("Custom-agent management API is disabled. Set agents_api.enabled=true to expose agent and user-profile routes over HTTP."),
        )


-def _agent_config_to_response(agent_cfg: AgentConfig, include_soul: bool = False) -> AgentResponse:
+def _agent_config_to_response(agent_cfg: AgentConfig, include_soul: bool = False, *, user_id: str | None = None) -> AgentResponse:
    """Convert AgentConfig to AgentResponse."""
    soul: str | None = None
    if include_soul:
-        soul = load_agent_soul(agent_cfg.name) or ""
+        soul = load_agent_soul(agent_cfg.name, user_id=user_id) or ""

    return AgentResponse(
        name=agent_cfg.name,
@@ -109,17 +109,18 @@ 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(app_config: AppConfig = Depends(get_config)) -> AgentsListResponse:
+async def list_agents() -> AgentsListResponse:
    """List all custom agents.

    Returns:
        List of all custom agents with their metadata and soul content.
    """
-    _require_agents_api_enabled(app_config)
+    _require_agents_api_enabled()

+    user_id = get_effective_user_id()
    try:
-        agents = list_custom_agents()
-        return AgentsListResponse(agents=[_agent_config_to_response(a, include_soul=True) for a in agents])
+        agents = list_custom_agents(user_id=user_id)
+        return AgentsListResponse(agents=[_agent_config_to_response(a, include_soul=True, user_id=user_id) 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)}")
@@ -142,10 +143,15 @@ async def check_agent_name(name: str) -> dict:
    Raises:
        HTTPException: 422 if the name is invalid.
    """
-    _require_agents_api_enabled(app_config)
+    _require_agents_api_enabled()
    _validate_agent_name(name)
    normalized = _normalize_agent_name(name)
-    available = not get_paths().agent_dir(normalized).exists()
+    user_id = get_effective_user_id()
+    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}


@@ -155,7 +161,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, app_config: AppConfig = Depends(get_config)) -> AgentResponse:
+async def get_agent(name: str) -> AgentResponse:
    """Get a specific custom agent by name.

    Args:
@@ -167,13 +173,14 @@ async def get_agent(name: str, app_config: AppConfig = Depends(get_config)) -> A
    Raises:
        HTTPException: 404 if agent not found.
    """
-    _require_agents_api_enabled(app_config)
+    _require_agents_api_enabled()
    _validate_agent_name(name)
    name = _normalize_agent_name(name)
+    user_id = get_effective_user_id()

    try:
-        agent_cfg = load_agent_config(name)
-        return _agent_config_to_response(agent_cfg, include_soul=True)
+        agent_cfg = load_agent_config(name, user_id=user_id)
+        return _agent_config_to_response(agent_cfg, include_soul=True, user_id=user_id)
    except FileNotFoundError:
        raise HTTPException(status_code=404, detail=f"Agent '{name}' not found")
    except Exception as e:
@@ -188,7 +195,7 @@ async def get_agent(name: str, app_config: AppConfig = Depends(get_config)) -> A
    summary="Create Custom Agent",
    description="Create a new custom agent with its config and SOUL.md.",
 )
-async def create_agent_endpoint(request: AgentCreateRequest, app_config: AppConfig = Depends(get_config)) -> AgentResponse:
+async def create_agent_endpoint(request: AgentCreateRequest) -> AgentResponse:
    """Create a new custom agent.

    Args:
@@ -200,13 +207,16 @@ async def create_agent_endpoint(request: AgentCreateRequest, app_config: AppConf
    Raises:
        HTTPException: 409 if agent already exists, 422 if name is invalid.
    """
-    _require_agents_api_enabled(app_config)
+    _require_agents_api_enabled()
    _validate_agent_name(request.name)
    normalized_name = _normalize_agent_name(request.name)
+    user_id = get_effective_user_id()
+    paths = get_paths()

-    agent_dir = get_paths().agent_dir(normalized_name)
+    agent_dir = paths.user_agent_dir(user_id, normalized_name)
+    legacy_dir = paths.agent_dir(normalized_name)

-    if agent_dir.exists():
+    if agent_dir.exists() or legacy_dir.exists():
        raise HTTPException(status_code=409, detail=f"Agent '{normalized_name}' already exists")

    try:
@@ -233,8 +243,8 @@ async def create_agent_endpoint(request: AgentCreateRequest, app_config: AppConf

        logger.info(f"Created agent '{normalized_name}' at {agent_dir}")

-        agent_cfg = load_agent_config(normalized_name)
-        return _agent_config_to_response(agent_cfg, include_soul=True)
+        agent_cfg = load_agent_config(normalized_name, user_id=user_id)
+        return _agent_config_to_response(agent_cfg, include_soul=True, user_id=user_id)

    except HTTPException:
        raise
@@ -252,7 +262,7 @@ async def create_agent_endpoint(request: AgentCreateRequest, app_config: AppConf
    summary="Update Custom Agent",
    description="Update an existing custom agent's config and/or SOUL.md.",
 )
-async def update_agent(name: str, request: AgentUpdateRequest, app_config: AppConfig = Depends(get_config)) -> AgentResponse:
+async def update_agent(name: str, request: AgentUpdateRequest) -> AgentResponse:
    """Update an existing custom agent.

    Args:
@@ -265,16 +275,23 @@ async def update_agent(name: str, request: AgentUpdateRequest, app_config: AppCo
    Raises:
        HTTPException: 404 if agent not found.
    """
-    _require_agents_api_enabled(app_config)
+    _require_agents_api_enabled()
    _validate_agent_name(name)
    name = _normalize_agent_name(name)
+    user_id = get_effective_user_id()

    try:
-        agent_cfg = load_agent_config(name)
+        agent_cfg = load_agent_config(name, user_id=user_id)
    except FileNotFoundError:
        raise HTTPException(status_code=404, detail=f"Agent '{name}' not found")

-    agent_dir = get_paths().agent_dir(name)
+    paths = get_paths()
+    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
@@ -315,8 +332,8 @@ async def update_agent(name: str, request: AgentUpdateRequest, app_config: AppCo

        logger.info(f"Updated agent '{name}'")

-        refreshed_cfg = load_agent_config(name)
-        return _agent_config_to_response(refreshed_cfg, include_soul=True)
+        refreshed_cfg = load_agent_config(name, user_id=user_id)
+        return _agent_config_to_response(refreshed_cfg, include_soul=True, user_id=user_id)

    except HTTPException:
        raise
@@ -343,13 +360,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(app_config: AppConfig = Depends(get_config)) -> UserProfileResponse:
+async def get_user_profile() -> UserProfileResponse:
    """Return the current USER.md content.

    Returns:
        UserProfileResponse with content=None if USER.md does not exist yet.
    """
-    _require_agents_api_enabled(app_config)
+    _require_agents_api_enabled()

    try:
        user_md_path = get_paths().user_md_file
@@ -368,7 +385,7 @@ async def get_user_profile(app_config: AppConfig = Depends(get_config)) -> UserP
    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, app_config: AppConfig = Depends(get_config)) -> UserProfileResponse:
+async def update_user_profile(request: UserProfileUpdateRequest) -> UserProfileResponse:
    """Create or overwrite the global USER.md.

    Args:
@@ -377,7 +394,7 @@ async def update_user_profile(request: UserProfileUpdateRequest, app_config: App
    Returns:
        UserProfileResponse with the saved content.
    """
-    _require_agents_api_enabled(app_config)
+    _require_agents_api_enabled()

    try:
        paths = get_paths()
@@ -396,22 +413,29 @@ async def update_user_profile(request: UserProfileUpdateRequest, app_config: App
    summary="Delete Custom Agent",
    description="Delete a custom agent and all its files (config, SOUL.md, memory).",
 )
-async def delete_agent(name: str, app_config: AppConfig = Depends(get_config)) -> None:
+async def delete_agent(name: str) -> None:
    """Delete a custom agent.

    Args:
        name: The agent name.

    Raises:
-        HTTPException: 404 if agent not found.
+        HTTPException: 404 if no per-user copy exists; 409 if only a legacy
+            shared copy exists (suggesting the migration script).
    """
-    _require_agents_api_enabled(app_config)
+    _require_agents_api_enabled()
    _validate_agent_name(name)
    name = _normalize_agent_name(name)
-
-    agent_dir = get_paths().agent_dir(name)
+    user_id = get_effective_user_id()
+    paths = get_paths()
+    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:
@@ -146,7 +146,13 @@ def _set_session_cookie(response: Response, token: str, request: Request) -> Non


 # ── Rate Limiting ────────────────────────────────────────────────────────
-# In-process dict — not shared across workers. Sufficient for single-worker deployments.
+# In-process dict — not shared across workers.
+#
+# **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
@@ -299,7 +305,7 @@ async def login_local(
 async def register(request: Request, response: Response, body: RegisterRequest):
    """Register a new user account (always 'user' role).

-    Admin is auto-created on first boot. This endpoint creates regular users.
+    The first admin is created explicitly through /initialize. This endpoint creates regular users.
    Auto-login by setting the session cookie.
    """
    try:
@@ -376,9 +382,37 @@ 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():
+async def setup_status(request: Request):
    """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}

@@ -3,12 +3,10 @@ import logging
 from pathlib import Path
 from typing import Literal

-from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel, Field

-from app.gateway.deps import get_config
-from deerflow.config.app_config import AppConfig
-from deerflow.config.extensions_config import ExtensionsConfig
+from deerflow.config.extensions_config import ExtensionsConfig, get_extensions_config, reload_extensions_config

 logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api", tags=["mcp"])
@@ -71,7 +69,7 @@ class McpConfigUpdateRequest(BaseModel):
    summary="Get MCP Configuration",
    description="Retrieve the current Model Context Protocol (MCP) server configurations.",
 )
-async def get_mcp_configuration(config: AppConfig = Depends(get_config)) -> McpConfigResponse:
+async def get_mcp_configuration() -> McpConfigResponse:
    """Get the current MCP configuration.

    Returns:
@@ -92,9 +90,9 @@ async def get_mcp_configuration(config: AppConfig = Depends(get_config)) -> McpC
        }
        ```
    """
-    ext = config.extensions
+    config = get_extensions_config()

-    return McpConfigResponse(mcp_servers={name: McpServerConfigResponse(**server.model_dump()) for name, server in ext.mcp_servers.items()})
+    return McpConfigResponse(mcp_servers={name: McpServerConfigResponse(**server.model_dump()) for name, server in config.mcp_servers.items()})


@router.put(
@@ -103,11 +101,7 @@ async def get_mcp_configuration(config: AppConfig = Depends(get_config)) -> McpC
    summary="Update MCP Configuration",
    description="Update Model Context Protocol (MCP) server configurations and save to file.",
 )
-async def update_mcp_configuration(
-    request: McpConfigUpdateRequest,
-    http_request: Request,
-    config: AppConfig = Depends(get_config),
-) -> McpConfigResponse:
+async def update_mcp_configuration(request: McpConfigUpdateRequest) -> McpConfigResponse:
    """Update the MCP configuration.

    This will:
@@ -148,13 +142,13 @@ async def update_mcp_configuration(
            config_path = Path.cwd().parent / "extensions_config.json"
            logger.info(f"No existing extensions config found. Creating new config at: {config_path}")

-        # Use injected config to preserve skills configuration
-        current_ext = config.extensions
+        # Load current config to preserve skills configuration
+        current_config = get_extensions_config()

        # 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_ext.skills.items()},
+            "skills": {name: {"enabled": skill.enabled} for name, skill in current_config.skills.items()},
        }

        # Write the configuration to file
@@ -166,11 +160,9 @@ async def update_mcp_configuration(
        # 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 swap ``app.state.config`` so subsequent
-        # ``Depends(get_config)`` calls see the refreshed value.
-        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()})
+        # Reload the configuration and update the global cache
+        reloaded_config = reload_extensions_config()
+        return McpConfigResponse(mcp_servers={name: McpServerConfigResponse(**server.model_dump()) for name, server in reloaded_config.mcp_servers.items()})

    except Exception as e:
        logger.error(f"Failed to update MCP configuration: {e}", exc_info=True)
@@ -1,9 +1,8 @@
 """Memory API router for retrieving and managing global memory data."""

-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, 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,
@@ -13,7 +12,7 @@ from deerflow.agents.memory.updater import (
    reload_memory_data,
    update_memory_fact,
 )
-from deerflow.config.app_config import AppConfig
+from deerflow.config.memory_config import get_memory_config
 from deerflow.runtime.user_context import get_effective_user_id

 router = APIRouter(prefix="/api", tags=["memory"])
@@ -115,7 +114,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(app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
+async def get_memory() -> MemoryResponse:
    """Get the current global memory data.

    Returns:
@@ -149,7 +148,7 @@ async def get_memory(app_config: AppConfig = Depends(get_config)) -> MemoryRespo
        }
        ```
    """
-    memory_data = get_memory_data(app_config.memory, user_id=get_effective_user_id())
+    memory_data = get_memory_data(user_id=get_effective_user_id())
    return MemoryResponse(**memory_data)


@@ -160,7 +159,7 @@ async def get_memory(app_config: AppConfig = Depends(get_config)) -> MemoryRespo
    summary="Reload Memory Data",
    description="Reload memory data from the storage file, refreshing the in-memory cache.",
 )
-async def reload_memory(app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
+async def reload_memory() -> MemoryResponse:
    """Reload memory data from file.

    This forces a reload of the memory data from the storage file,
@@ -169,7 +168,7 @@ async def reload_memory(app_config: AppConfig = Depends(get_config)) -> MemoryRe
    Returns:
        The reloaded memory data.
    """
-    memory_data = reload_memory_data(app_config.memory, user_id=get_effective_user_id())
+    memory_data = reload_memory_data(user_id=get_effective_user_id())
    return MemoryResponse(**memory_data)


@@ -180,10 +179,10 @@ async def reload_memory(app_config: AppConfig = Depends(get_config)) -> MemoryRe
    summary="Clear All Memory Data",
    description="Delete all saved memory data and reset the memory structure to an empty state.",
 )
-async def clear_memory(app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
+async def clear_memory() -> MemoryResponse:
    """Clear all persisted memory data."""
    try:
-        memory_data = clear_memory_data(app_config.memory, user_id=get_effective_user_id())
+        memory_data = clear_memory_data(user_id=get_effective_user_id())
    except OSError as exc:
        raise HTTPException(status_code=500, detail="Failed to clear memory data.") from exc

@@ -197,11 +196,10 @@ async def clear_memory(app_config: AppConfig = Depends(get_config)) -> MemoryRes
    summary="Create Memory Fact",
    description="Create a single saved memory fact manually.",
 )
-async def create_memory_fact_endpoint(request: FactCreateRequest, app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
+async def create_memory_fact_endpoint(request: FactCreateRequest) -> MemoryResponse:
    """Create a single fact manually."""
    try:
        memory_data = create_memory_fact(
-            app_config.memory,
            content=request.content,
            category=request.category,
            confidence=request.confidence,
@@ -222,10 +220,10 @@ async def create_memory_fact_endpoint(request: FactCreateRequest, app_config: Ap
    summary="Delete Memory Fact",
    description="Delete a single saved memory fact by its fact id.",
 )
-async def delete_memory_fact_endpoint(fact_id: str, app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
+async def delete_memory_fact_endpoint(fact_id: str) -> MemoryResponse:
    """Delete a single fact from memory by fact id."""
    try:
-        memory_data = delete_memory_fact(app_config.memory, fact_id, user_id=get_effective_user_id())
+        memory_data = delete_memory_fact(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:
@@ -241,11 +239,10 @@ async def delete_memory_fact_endpoint(fact_id: str, app_config: AppConfig = Depe
    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, app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
+async def update_memory_fact_endpoint(fact_id: str, request: FactPatchRequest) -> 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,
@@ -269,9 +266,9 @@ async def update_memory_fact_endpoint(fact_id: str, request: FactPatchRequest, a
    summary="Export Memory Data",
    description="Export the current global memory data as JSON for backup or transfer.",
 )
-async def export_memory(app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
+async def export_memory() -> MemoryResponse:
    """Export the current memory data."""
-    memory_data = get_memory_data(app_config.memory, user_id=get_effective_user_id())
+    memory_data = get_memory_data(user_id=get_effective_user_id())
    return MemoryResponse(**memory_data)


@@ -282,10 +279,10 @@ async def export_memory(app_config: AppConfig = Depends(get_config)) -> MemoryRe
    summary="Import Memory Data",
    description="Import and overwrite the current global memory data from a JSON payload.",
 )
-async def import_memory(request: MemoryResponse, app_config: AppConfig = Depends(get_config)) -> MemoryResponse:
+async def import_memory(request: MemoryResponse) -> MemoryResponse:
    """Import and persist memory data."""
    try:
-        memory_data = import_memory_data(app_config.memory, request.model_dump(), user_id=get_effective_user_id())
+        memory_data = import_memory_data(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

@@ -298,9 +295,7 @@ async def import_memory(request: MemoryResponse, app_config: AppConfig = Depends
    summary="Get Memory Configuration",
    description="Retrieve the current memory system configuration.",
 )
-async def get_memory_config_endpoint(
-    app_config: AppConfig = Depends(get_config),
-) -> MemoryConfigResponse:
+async def get_memory_config_endpoint() -> MemoryConfigResponse:
    """Get the memory system configuration.

    Returns:
@@ -319,7 +314,7 @@ async def get_memory_config_endpoint(
        }
        ```
    """
-    config = app_config.memory
+    config = get_memory_config()
    return MemoryConfigResponse(
        enabled=config.enabled,
        storage_path=config.storage_path,
@@ -338,16 +333,14 @@ async def get_memory_config_endpoint(
    summary="Get Memory Status",
    description="Retrieve both memory configuration and current data in a single request.",
 )
-async def get_memory_status(
-    app_config: AppConfig = Depends(get_config),
-) -> MemoryStatusResponse:
+async def get_memory_status() -> MemoryStatusResponse:
    """Get the memory system status including configuration and data.

    Returns:
        Combined memory configuration and current data.
    """
-    config = app_config.memory
-    memory_data = get_memory_data(config, user_id=get_effective_user_id())
+    config = get_memory_config()
+    memory_data = get_memory_data(user_id=get_effective_user_id())

    return MemoryStatusResponse(
        config=MemoryConfigResponse(
@@ -123,7 +123,8 @@ 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_id,
+        run["thread_id"],
+        run_id,
        limit=limit + 1,
        before_seq=before_seq,
        after_seq=after_seq,
@@ -1,32 +1,20 @@
-import errno
 import json
 import logging
-import shutil
 from pathlib import Path

-from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi import APIRouter, Depends, HTTPException
 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
-from deerflow.skills import Skill, load_skills
-from deerflow.skills.installer import SkillAlreadyExistsError, install_skill_from_archive
-from deerflow.skills.manager import (
-    append_history,
-    atomic_write,
-    custom_skill_exists,
-    ensure_custom_skill_is_editable,
-    get_custom_skill_dir,
-    get_custom_skill_file,
-    get_skill_history_file,
-    read_custom_skill_content,
-    read_history,
-    validate_skill_markdown_content,
-)
+from deerflow.config.extensions_config import ExtensionsConfig, SkillStateConfig, get_extensions_config, reload_extensions_config
+from deerflow.skills import Skill
+from deerflow.skills.installer import SkillAlreadyExistsError
 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__)

@@ -39,7 +27,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: str = Field(..., description="Category of the skill (public or custom)")
+    category: SkillCategory = Field(..., description="Category of the skill (public or custom)")
    enabled: bool = Field(default=True, description="Whether this skill is enabled")


@@ -103,9 +91,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(app_config: AppConfig = Depends(get_config)) -> SkillsListResponse:
+async def list_skills(config: AppConfig = Depends(get_config)) -> SkillsListResponse:
    try:
-        skills = load_skills(app_config, enabled_only=False)
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
        return SkillsListResponse(skills=[_skill_to_response(skill) for skill in skills])
    except Exception as e:
        logger.error(f"Failed to load skills: {e}", exc_info=True)
@@ -118,11 +106,11 @@ async def list_skills(app_config: AppConfig = Depends(get_config)) -> SkillsList
    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, app_config: AppConfig = Depends(get_config)) -> SkillInstallResponse:
+async def install_skill(request: SkillInstallRequest, config: AppConfig = Depends(get_config)) -> SkillInstallResponse:
    try:
        skill_file_path = resolve_thread_virtual_path(request.thread_id, request.path)
-        result = install_skill_from_archive(skill_file_path)
-        await refresh_skills_system_prompt_cache_async(app_config)
+        result = await get_or_new_skill_storage(app_config=config).ainstall_skill_from_archive(skill_file_path)
+        await refresh_skills_system_prompt_cache_async()
        return SkillInstallResponse(**result)
    except FileNotFoundError as e:
        raise HTTPException(status_code=404, detail=str(e))
@@ -138,9 +126,9 @@ async def install_skill(request: SkillInstallRequest, app_config: AppConfig = De


@router.get("/skills/custom", response_model=SkillsListResponse, summary="List Custom Skills")
-async def list_custom_skills(app_config: AppConfig = Depends(get_config)) -> SkillsListResponse:
+async def list_custom_skills(config: AppConfig = Depends(get_config)) -> SkillsListResponse:
    try:
-        skills = [skill for skill in load_skills(app_config, enabled_only=False) if skill.category == "custom"]
+        skills = [skill for skill in get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False) if skill.category == SkillCategory.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)
@@ -148,13 +136,14 @@ async def list_custom_skills(app_config: AppConfig = Depends(get_config)) -> Ski


@router.get("/skills/custom/{skill_name}", response_model=CustomSkillContentResponse, summary="Get Custom Skill Content")
-async def get_custom_skill(skill_name: str, app_config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
+async def get_custom_skill(skill_name: str, config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
    try:
-        skills = load_skills(app_config, enabled_only=False)
-        skill = next((s for s in skills if s.name == skill_name and s.category == "custom"), None)
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        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 == 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=read_custom_skill_content(skill_name, app_config))
+        return CustomSkillContentResponse(**_skill_to_response(skill).model_dump(), content=get_or_new_skill_storage(app_config=config).read_custom_skill(skill_name))
    except HTTPException:
        raise
    except Exception as e:
@@ -163,35 +152,31 @@ async def get_custom_skill(skill_name: str, app_config: AppConfig = Depends(get_


@router.put("/skills/custom/{skill_name}", response_model=CustomSkillContentResponse, summary="Edit Custom Skill")
-async def update_custom_skill(
-    skill_name: str,
-    request: CustomSkillUpdateRequest,
-    app_config: AppConfig = Depends(get_config),
-) -> CustomSkillContentResponse:
+async def update_custom_skill(skill_name: str, request: CustomSkillUpdateRequest, config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
    try:
-        ensure_custom_skill_is_editable(skill_name, app_config)
-        validate_skill_markdown_content(skill_name, request.content)
-        scan = await scan_skill_content(app_config, request.content, executable=False, location=f"{skill_name}/SKILL.md")
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        storage = get_or_new_skill_storage(app_config=config)
+        storage.ensure_custom_skill_is_editable(skill_name)
+        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}")
-        skill_file = get_custom_skill_dir(skill_name, app_config) / "SKILL.md"
-        prev_content = skill_file.read_text(encoding="utf-8")
-        atomic_write(skill_file, request.content)
-        append_history(
+        prev_content = storage.read_custom_skill(skill_name)
+        storage.write_custom_skill(skill_name, SKILL_MD_FILE, request.content)
+        storage.append_history(
            skill_name,
            {
                "action": "human_edit",
                "author": "human",
                "thread_id": None,
-                "file_path": "SKILL.md",
+                "file_path": SKILL_MD_FILE,
                "prev_content": prev_content,
                "new_content": request.content,
                "scanner": {"decision": scan.decision, "reason": scan.reason},
            },
-            app_config,
        )
-        await refresh_skills_system_prompt_cache_async(app_config)
-        return await get_custom_skill(skill_name, app_config)
+        await refresh_skills_system_prompt_cache_async()
+        return await get_custom_skill(skill_name, config)
    except HTTPException:
        raise
    except FileNotFoundError as e:
@@ -204,31 +189,23 @@ async def update_custom_skill(


@router.delete("/skills/custom/{skill_name}", summary="Delete Custom Skill")
-async def delete_custom_skill(skill_name: str, app_config: AppConfig = Depends(get_config)) -> dict[str, bool]:
+async def delete_custom_skill(skill_name: str, config: AppConfig = Depends(get_config)) -> dict[str, bool]:
    try:
-        ensure_custom_skill_is_editable(skill_name, app_config)
-        skill_dir = get_custom_skill_dir(skill_name, app_config)
-        prev_content = read_custom_skill_content(skill_name, app_config)
-        try:
-            append_history(
-                skill_name,
-                {
-                    "action": "human_delete",
-                    "author": "human",
-                    "thread_id": None,
-                    "file_path": "SKILL.md",
-                    "prev_content": prev_content,
-                    "new_content": None,
-                    "scanner": {"decision": "allow", "reason": "Deletion requested."},
-                },
-                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)
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        storage = get_or_new_skill_storage(app_config=config)
+        storage.delete_custom_skill(
+            skill_name,
+            history_meta={
+                "action": "human_delete",
+                "author": "human",
+                "thread_id": None,
+                "file_path": SKILL_MD_FILE,
+                "prev_content": None,
+                "new_content": None,
+                "scanner": {"decision": "allow", "reason": "Deletion requested."},
+            },
+        )
+        await refresh_skills_system_prompt_cache_async()
        return {"success": True}
    except FileNotFoundError as e:
        raise HTTPException(status_code=404, detail=str(e))
@@ -240,11 +217,13 @@ async def delete_custom_skill(skill_name: str, app_config: AppConfig = Depends(g


@router.get("/skills/custom/{skill_name}/history", response_model=CustomSkillHistoryResponse, summary="Get Custom Skill History")
-async def get_custom_skill_history(skill_name: str, app_config: AppConfig = Depends(get_config)) -> CustomSkillHistoryResponse:
+async def get_custom_skill_history(skill_name: str, config: AppConfig = Depends(get_config)) -> CustomSkillHistoryResponse:
    try:
-        if not custom_skill_exists(skill_name, app_config) and not get_skill_history_file(skill_name, app_config).exists():
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        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=read_history(skill_name, app_config))
+        return CustomSkillHistoryResponse(history=storage.read_history(skill_name))
    except HTTPException:
        raise
    except Exception as e:
@@ -253,42 +232,39 @@ async def get_custom_skill_history(skill_name: str, app_config: AppConfig = Depe


@router.post("/skills/custom/{skill_name}/rollback", response_model=CustomSkillContentResponse, summary="Rollback Custom Skill")
-async def rollback_custom_skill(
-    skill_name: str,
-    request: SkillRollbackRequest,
-    app_config: AppConfig = Depends(get_config),
-) -> CustomSkillContentResponse:
+async def rollback_custom_skill(skill_name: str, request: SkillRollbackRequest, config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
    try:
-        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")
-        history = read_history(skill_name, app_config)
+        history = storage.read_history(skill_name)
        if not history:
            raise HTTPException(status_code=400, detail=f"Custom skill '{skill_name}' has no history")
        record = history[request.history_index]
        target_content = record.get("prev_content")
        if target_content is None:
            raise HTTPException(status_code=400, detail="Selected history entry has no previous content to roll back to")
-        validate_skill_markdown_content(skill_name, target_content)
-        scan = await scan_skill_content(app_config, target_content, executable=False, location=f"{skill_name}/SKILL.md")
-        skill_file = get_custom_skill_file(skill_name, app_config)
+        storage.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)
+        skill_file = storage.get_custom_skill_file(skill_name)
        current_content = skill_file.read_text(encoding="utf-8") if skill_file.exists() else None
        history_entry = {
            "action": "rollback",
            "author": "human",
            "thread_id": None,
-            "file_path": "SKILL.md",
+            "file_path": SKILL_MD_FILE,
            "prev_content": current_content,
            "new_content": target_content,
            "rollback_from_ts": record.get("ts"),
            "scanner": {"decision": scan.decision, "reason": scan.reason},
        }
        if scan.decision == "block":
-            append_history(skill_name, history_entry, app_config)
+            storage.append_history(skill_name, history_entry)
            raise HTTPException(status_code=400, detail=f"Rollback blocked by security scanner: {scan.reason}")
-        atomic_write(skill_file, target_content)
-        append_history(skill_name, history_entry, app_config)
-        await refresh_skills_system_prompt_cache_async(app_config)
-        return await get_custom_skill(skill_name, app_config)
+        storage.write_custom_skill(skill_name, SKILL_MD_FILE, target_content)
+        storage.append_history(skill_name, history_entry)
+        await refresh_skills_system_prompt_cache_async()
+        return await get_custom_skill(skill_name, config)
    except HTTPException:
        raise
    except IndexError:
@@ -308,9 +284,10 @@ async def rollback_custom_skill(
    summary="Get Skill Details",
    description="Retrieve detailed information about a specific skill by its name.",
 )
-async def get_skill(skill_name: str, app_config: AppConfig = Depends(get_config)) -> SkillResponse:
+async def get_skill(skill_name: str, config: AppConfig = Depends(get_config)) -> SkillResponse:
    try:
-        skills = load_skills(app_config, enabled_only=False)
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        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:
@@ -330,14 +307,10 @@ async def get_skill(skill_name: str, app_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,
-    http_request: Request,
-    app_config: AppConfig = Depends(get_config),
-) -> SkillResponse:
+async def update_skill(skill_name: str, request: SkillUpdateRequest, config: AppConfig = Depends(get_config)) -> SkillResponse:
    try:
-        skills = load_skills(app_config, enabled_only=False)
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        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:
@@ -348,29 +321,22 @@ async def update_skill(
            config_path = Path.cwd().parent / "extensions_config.json"
            logger.info(f"No existing extensions config found. Creating new config at: {config_path}")

-        # Do not mutate the frozen AppConfig in place. Compose the new skills
-        # 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}
+        extensions_config = get_extensions_config()
+        extensions_config.skills[skill_name] = SkillStateConfig(enabled=request.enabled)

        config_data = {
-            "mcpServers": {name: server.model_dump() for name, server in ext.mcp_servers.items()},
-            "skills": updated_skills,
+            "mcpServers": {name: server.model_dump() for name, server in extensions_config.mcp_servers.items()},
+            "skills": {name: {"enabled": skill_config.enabled} for name, skill_config in extensions_config.skills.items()},
        }

        with open(config_path, "w", encoding="utf-8") as f:
            json.dump(config_data, f, indent=2)

        logger.info(f"Skills configuration updated and saved to: {config_path}")
-        # Reload AppConfig and swap ``app.state.config`` so subsequent
-        # ``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)
+        reload_extensions_config()
+        await refresh_skills_system_prompt_cache_async()

-        skills = load_skills(reloaded, enabled_only=False)
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
        updated_skill = next((s for s in skills if s.name == skill_name), None)

        if updated_skill is None:
@@ -102,7 +102,12 @@ 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(thread_id: str, body: SuggestionsRequest, request: Request, app_config: AppConfig = Depends(get_config)) -> SuggestionsResponse:
+async def generate_suggestions(
+    thread_id: str,
+    body: SuggestionsRequest,
+    request: Request,
+    config: AppConfig = Depends(get_config),
+) -> SuggestionsResponse:
    if not body.messages:
        return SuggestionsResponse(suggestions=[])

@@ -124,7 +129,7 @@ async def generate_suggestions(thread_id: str, body: SuggestionsRequest, request
    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=app_config)
+        model = create_chat_model(name=body.model_name, thinking_enabled=False, app_config=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 []
@@ -54,7 +54,6 @@ 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):
@@ -69,6 +68,27 @@ 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
 # ---------------------------------------------------------------------------
@@ -312,11 +332,15 @@ async def list_thread_messages(
        if i in last_ai_indices:
            run_id = msg["run_id"]
            fb = feedback_map.get(run_id)
-            msg["feedback"] = {
-                "feedback_id": fb["feedback_id"],
-                "rating": fb["rating"],
-                "comment": fb.get("comment"),
-            } if fb else None
+            msg["feedback"] = (
+                {
+                    "feedback_id": fb["feedback_id"],
+                    "rating": fb["rating"],
+                    "comment": fb.get("comment"),
+                }
+                if fb
+                else None
+            )
        else:
            msg["feedback"] = None

@@ -339,7 +363,8 @@ async def list_run_messages(
    """
    event_store = get_run_event_store(request)
    rows = await event_store.list_messages_by_run(
-        thread_id, run_id,
+        thread_id,
+        run_id,
        limit=limit + 1,
        before_seq=before_seq,
        after_seq=after_seq,
@@ -364,10 +389,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")
+@router.get("/{thread_id}/token-usage", response_model=ThreadTokenUsageResponse)
@require_permission("threads", "read", owner_check=True)
-async def thread_token_usage(thread_id: str, request: Request) -> dict:
+async def thread_token_usage(thread_id: str, request: Request) -> ThreadTokenUsageResponse:
    """Thread-level token usage aggregation."""
    run_store = get_run_store(request)
    agg = await run_store.aggregate_tokens_by_thread(thread_id)
-    return {"thread_id": thread_id, **agg}
+    return ThreadTokenUsageResponse(thread_id=thread_id, **agg)
@@ -13,12 +13,11 @@ 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
@@ -27,6 +26,7 @@ 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"])
@@ -90,6 +90,28 @@ class ThreadSearchRequest(BaseModel):
    offset: int = Field(default=0, ge=0, description="Pagination offset")
    status: str | None = Field(default=None, description="Filter by thread status")

+    @field_validator("metadata")
+    @classmethod
+    def _validate_metadata_filters(cls, v: dict[str, Any]) -> dict[str, Any]:
+        """Reject filter entries the SQL backend cannot compile.
+
+        Enforces consistent behaviour across SQL and memory backends.
+        See ``deerflow.persistence.json_compat`` for the shared validators.
+        """
+        if not v:
+            return v
+        from deerflow.persistence.json_compat import validate_metadata_filter_key, validate_metadata_filter_value
+
+        bad_entries: list[str] = []
+        for key, value in v.items():
+            if not validate_metadata_filter_key(key):
+                bad_entries.append(f"{key!r} (unsafe key)")
+            elif not validate_metadata_filter_value(value):
+                bad_entries.append(f"{key!r} (unsupported value type {type(value).__name__})")
+        if bad_entries:
+            raise ValueError(f"Invalid metadata filter entries: {', '.join(bad_entries)}")
+        return v
+

 class ThreadStateResponse(BaseModel):
    """Response model for thread state."""
@@ -234,7 +256,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 = time.time()
+    now = now_iso()
    # ``body.metadata`` is already stripped of server-reserved keys by
    # ``ThreadCreateRequest._strip_reserved`` — see the model definition.

@@ -244,8 +266,8 @@ async def create_thread(body: ThreadCreateRequest, request: Request) -> ThreadRe
        return ThreadResponse(
            thread_id=thread_id,
            status=existing_record.get("status", "idle"),
-            created_at=str(existing_record.get("created_at", "")),
-            updated_at=str(existing_record.get("updated_at", "")),
+            created_at=coerce_iso(existing_record.get("created_at", "")),
+            updated_at=coerce_iso(existing_record.get("updated_at", "")),
            metadata=existing_record.get("metadata", {}),
        )

@@ -263,8 +285,6 @@ 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",
@@ -282,8 +302,8 @@ async def create_thread(body: ThreadCreateRequest, request: Request) -> ThreadRe
    return ThreadResponse(
        thread_id=thread_id,
        status="idle",
-        created_at=str(now),
-        updated_at=str(now),
+        created_at=now,
+        updated_at=now,
        metadata=body.metadata,
    )

@@ -296,20 +316,27 @@ async def search_threads(body: ThreadSearchRequest, request: Request) -> list[Th
    (SQL-backed for sqlite/postgres, Store-backed for memory mode).
    """
    from app.gateway.deps import get_thread_store
+    from deerflow.persistence.thread_meta import InvalidMetadataFilterError

    repo = get_thread_store(request)
-    rows = await repo.search(
-        metadata=body.metadata or None,
-        status=body.status,
-        limit=body.limit,
-        offset=body.offset,
-    )
+    try:
+        rows = await repo.search(
+            metadata=body.metadata or None,
+            status=body.status,
+            limit=body.limit,
+            offset=body.offset,
+        )
+    except InvalidMetadataFilterError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
    return [
        ThreadResponse(
            thread_id=r["thread_id"],
            status=r.get("status", "idle"),
-            created_at=r.get("created_at", ""),
-            updated_at=r.get("updated_at", ""),
+            # ``coerce_iso`` heals legacy unix-second values that
+            # ``MemoryThreadMetaStore`` historically wrote with ``time.time()``;
+            # 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={},
@@ -341,8 +368,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=str(record.get("created_at", "")),
-        updated_at=str(record.get("updated_at", "")),
+        created_at=coerce_iso(record.get("created_at", "")),
+        updated_at=coerce_iso(record.get("updated_at", "")),
        metadata=record.get("metadata", {}),
    )

@@ -382,8 +409,8 @@ async def get_thread(thread_id: str, request: Request) -> ThreadResponse:
        record = {
            "thread_id": thread_id,
            "status": "idle",
-            "created_at": ckpt_meta.get("created_at", ""),
-            "updated_at": ckpt_meta.get("updated_at", ckpt_meta.get("created_at", "")),
+            "created_at": coerce_iso(ckpt_meta.get("created_at", "")),
+            "updated_at": coerce_iso(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")},
        }

@@ -397,8 +424,8 @@ async def get_thread(thread_id: str, request: Request) -> ThreadResponse:
    return ThreadResponse(
        thread_id=thread_id,
        status=status,
-        created_at=str(record.get("created_at", "")),
-        updated_at=str(record.get("updated_at", "")),
+        created_at=coerce_iso(record.get("created_at", "")),
+        updated_at=coerce_iso(record.get("updated_at", "")),
        metadata=record.get("metadata", {}),
        values=serialize_channel_values(channel_values),
    )
@@ -449,10 +476,10 @@ async def get_thread_state(thread_id: str, request: Request) -> ThreadStateRespo
        values=values,
        next=next_tasks,
        metadata=metadata,
-        checkpoint={"id": checkpoint_id, "ts": str(metadata.get("created_at", ""))},
+        checkpoint={"id": checkpoint_id, "ts": coerce_iso(metadata.get("created_at", ""))},
        checkpoint_id=checkpoint_id,
        parent_checkpoint_id=parent_checkpoint_id,
-        created_at=str(metadata.get("created_at", "")),
+        created_at=coerce_iso(metadata.get("created_at", "")),
        tasks=tasks,
    )

@@ -502,7 +529,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"] = time.time()
+    metadata["updated_at"] = now_iso()

    if body.as_node:
        metadata["source"] = "update"
@@ -543,7 +570,7 @@ async def update_thread_state(thread_id: str, body: ThreadStateUpdateRequest, re
        next=[],
        metadata=metadata,
        checkpoint_id=new_checkpoint_id,
-        created_at=str(metadata.get("created_at", "")),
+        created_at=coerce_iso(metadata.get("created_at", "")),
    )


@@ -610,7 +637,7 @@ async def get_thread_history(thread_id: str, body: ThreadHistoryRequest, request
                    parent_checkpoint_id=parent_id,
                    metadata=user_meta,
                    values=values,
-                    created_at=str(metadata.get("created_at", "")),
+                    created_at=coerce_iso(metadata.get("created_at", "")),
                    next=next_tasks,
                )
            )
@@ -5,7 +5,7 @@ import os
 import stat

 from fastapi import APIRouter, Depends, File, HTTPException, Request, UploadFile
-from pydantic import BaseModel
+from pydantic import BaseModel, Field

 from app.gateway.authz import require_permission
 from app.gateway.deps import get_config
@@ -15,12 +15,15 @@ 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,
 )
@@ -30,6 +33,11 @@ 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."""
@@ -37,6 +45,15 @@ 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:
@@ -69,6 +86,72 @@ 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.

@@ -85,72 +168,94 @@ def _auto_convert_documents_enabled(app_config: AppConfig) -> bool:


@router.post("", response_model=UploadResponse)
-@require_permission("threads", "write", owner_check=True, require_existing=True)
+@require_permission("threads", "write", owner_check=True, require_existing=False)
 async def upload_files(
    thread_id: str,
    request: Request,
    files: list[UploadFile] = File(...),
-    app_config: AppConfig = Depends(get_config),
+    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(app_config)
+    sandbox_provider = get_sandbox_provider()
    sync_to_sandbox = not _uses_thread_data_mounts(sandbox_provider)
    sandbox = None
    if sync_to_sandbox:
        sandbox_id = sandbox_provider.acquire(thread_id)
        sandbox = sandbox_provider.get(sandbox_id)
-    auto_convert_documents = _auto_convert_documents_enabled(app_config)
+        if sandbox is None:
+            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:
-            safe_filename = normalize_filename(file.filename)
+            original_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:
-            content = await file.read()
-            file_path = uploads_dir / safe_filename
-            file_path.write_bytes(content)
+            file_path, file_size, total_size = await _write_upload_file_with_limits(
+                file,
+                uploads_dir=uploads_dir,
+                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 and sandbox is not None:
-                _make_file_sandbox_writable(file_path)
-                sandbox.update_file(virtual_path, content)
+            if sync_to_sandbox:
+                sandbox_sync_targets.append((file_path, virtual_path))

            file_info = {
                "filename": safe_filename,
-                "size": str(len(content)),
+                "size": str(file_size),
                "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} ({len(content)} bytes) to {file_info['path']}")
+            logger.info(f"Saved file: {safe_filename} ({file_size} 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 and sandbox is not None:
-                        _make_file_sandbox_writable(md_path)
-                        sandbox.update_file(md_virtual_path, md_path.read_bytes())
+                    if sync_to_sandbox:
+                        sandbox_sync_targets.append((md_path, md_virtual_path))

                    file_info["markdown_file"] = md_path.name
                    file_info["markdown_path"] = str(sandbox_uploads / md_path.name)
@@ -159,17 +264,46 @@ 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=True,
+        success=not skipped_files,
        files=uploaded_files,
-        message=f"Successfully uploaded {len(uploaded_files)} file(s)",
+        message=message,
+        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:
@@ -8,7 +8,6 @@ frames, and consuming stream bridge events.  Router modules
 from __future__ import annotations

 import asyncio
-import dataclasses
 import json
 import logging
 import re
@@ -18,8 +17,9 @@ 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_run_store, get_stream_bridge
+from app.gateway.deps import get_run_context, get_run_manager, get_stream_bridge
 from app.gateway.utils import sanitize_log_param
+from deerflow.config.app_config import get_app_config
 from deerflow.runtime import (
    END_SENTINEL,
    HEARTBEAT_SENTINEL,
@@ -99,6 +99,62 @@ 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.

@@ -212,20 +268,22 @@ 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
+    body_context = getattr(body, "context", None) or {}
+    model_name = body_context.get("model_name")

-    # 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)
+    # Coerce non-string model_name values to str before truncation.
+    if model_name is not None and not isinstance(model_name, str):
+        model_name = str(model_name)
+
+    # Validate model against the allowlist when a model_name is provided.
+    if model_name:
+        app_config = get_app_config()
+        resolved = app_config.get_model_config(model_name)
+        if resolved is None:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Model {model_name!r} is not in the configured model allowlist",
+            )

    try:
        record = await run_mgr.create_or_reject(
@@ -235,7 +293,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,
+            model_name=model_name,
        )
    except ConflictError as exc:
        raise HTTPException(status_code=409, detail=str(exc)) from exc
@@ -262,27 +320,12 @@ 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 configurable.
+    # Merge DeerFlow-specific context overrides into both ``configurable`` and ``context``.
    # The ``context`` field is a custom extension for the langgraph-compat layer
    # that carries agent configuration (model_name, thinking_enabled, etc.).
    # Only agent-relevant keys are forwarded; unknown keys (e.g. thread_id) are ignored.
-    context = getattr(body, "context", None)
-    if context:
-        _CONTEXT_CONFIGURABLE_KEYS = {
-            "model_name",
-            "mode",
-            "thinking_enabled",
-            "reasoning_effort",
-            "is_plan_mode",
-            "subagent_enabled",
-            "max_concurrent_subagents",
-            "agent_name",
-            "is_bootstrap",
-        }
-        configurable = config.setdefault("configurable", {})
-        for key in _CONTEXT_CONFIGURABLE_KEYS:
-            if key in context:
-                configurable.setdefault(key, context[key])
+    merge_run_context_overrides(config, getattr(body, "context", None))
+    inject_authenticated_user_context(config, request)

    stream_modes = normalize_stream_modes(body.stream_mode)

@@ -34,50 +34,42 @@ _LOG_FMT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
 _LOG_DATEFMT = "%Y-%m-%d %H:%M:%S"


-def _logging_level_from_config(name: str) -> int:
-    """Map ``config.yaml`` ``log_level`` string to a ``logging`` level constant."""
-    mapping = logging.getLevelNamesMapping()
-    return mapping.get((name or "info").strip().upper(), logging.INFO)
+def _setup_logging(log_level: int = logging.INFO) -> None:
+    """Route logs to ``debug.log`` using *log_level* for the initial root/file setup.

+    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``.

-def _setup_logging(log_level: str) -> None:
-    """Send application logs to ``debug.log`` at *log_level*; do not print them on the console.
-
-    Idempotent: any pre-existing handlers on the root logger (e.g. installed by
-    ``logging.basicConfig`` in transitively imported modules) are removed so the
-    debug session output only lands in ``debug.log``.
+    Note: later config-driven logging adjustments may change named logger
+    verbosity without raising the root logger or file-handler thresholds set
+    here, so the eventual contents of ``debug.log`` may not be filtered solely by
+    this function's ``log_level`` argument.
    """
-    level = _logging_level_from_config(log_level)
    root = logging.root
    for h in list(root.handlers):
        root.removeHandler(h)
        h.close()
-    root.setLevel(level)
+    root.setLevel(log_level)

    file_handler = logging.FileHandler("debug.log", mode="a", encoding="utf-8")
-    file_handler.setLevel(level)
+    file_handler.setLevel(log_level)
    file_handler.setFormatter(logging.Formatter(_LOG_FMT, datefmt=_LOG_DATEFMT))
    root.addHandler(file_handler)


-def _update_logging_level(log_level: str) -> None:
-    """Update the root logger and existing handlers to *log_level*."""
-    level = _logging_level_from_config(log_level)
-    root = logging.root
-    root.setLevel(level)
-    for handler in root.handlers:
-        handler.setLevel(level)
-
-
 async def main():
    # Install file logging first so warnings emitted while loading config do not
    # leak onto the interactive terminal via Python's lastResort handler.
-    _setup_logging("info")
+    _setup_logging()

    from deerflow.config import get_app_config
+    from deerflow.config.app_config import apply_logging_level

    app_config = get_app_config()
-    _update_logging_level(app_config.log_level)
+    apply_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
@@ -87,7 +79,9 @@ 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:
@@ -121,6 +115,8 @@ 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:
@@ -142,6 +138,22 @@ 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
@@ -6,16 +6,16 @@ This document provides a complete reference for the DeerFlow backend APIs.

 DeerFlow backend exposes two sets of APIs:

-1. **LangGraph API** - Agent interactions, threads, and streaming (`/api/langgraph/*`)
+1. **LangGraph-compatible API** - Agent interactions, threads, and streaming (`/api/langgraph/*`)
 2. **Gateway API** - Models, MCP, skills, uploads, and artifacts (`/api/*`)

 All APIs are accessed through the Nginx reverse proxy at port 2026.

-## LangGraph API
+## LangGraph-compatible API

 Base URL: `/api/langgraph`

-The LangGraph API is provided by the LangGraph server and follows the LangGraph SDK conventions.
+The public LangGraph-compatible API follows LangGraph SDK conventions. In the unified nginx deployment, Gateway owns `/api/langgraph/*` and translates those paths to its native `/api/*` run, thread, and streaming routers.

 ### Threads

@@ -104,17 +104,11 @@ Content-Type: application/json
 **Recursion Limit:**

 `config.recursion_limit` caps the number of graph steps LangGraph will execute
-in a single run. The `/api/langgraph/*` endpoints go straight to the LangGraph
-server and therefore inherit LangGraph's native default of **25**, which is
-too low for plan-mode or subagent-heavy runs — the agent typically errors out
-with `GraphRecursionError` after the first round of subagent results comes
-back, before the lead agent can synthesize the final answer.
-
-DeerFlow's own Gateway and IM-channel paths mitigate this by defaulting to
-`100` in `build_run_config` (see `backend/app/gateway/services.py`), but
-clients calling the LangGraph API directly must set `recursion_limit`
-explicitly in the request body. `100` matches the Gateway default and is a
-safe starting point; increase it if you run deeply nested subagent graphs.
+in a single run. The unified Gateway path defaults to `100` in
+`build_run_config` (see `backend/app/gateway/services.py`), which is a safer
+starting point for plan-mode or subagent-heavy runs. Clients can still set
+`recursion_limit` explicitly in the request body; increase it if you run deeply
+nested subagent graphs.

 **Configurable Options:**
 - `model_name` (string): Override the default model
@@ -541,14 +535,28 @@ All APIs return errors in a consistent format:

 ## Authentication

-Currently, DeerFlow does not implement authentication. All APIs are accessible without credentials.
+DeerFlow enforces authentication for all non-public HTTP routes. Public routes are limited to health/docs metadata and these public auth endpoints:

-Note: This is about DeerFlow API authentication. MCP outbound connections can still use OAuth for configured HTTP/SSE MCP servers.
+- `POST /api/v1/auth/initialize` creates the first admin account when no admin exists.
+- `POST /api/v1/auth/login/local` logs in with email/password and sets an HttpOnly `access_token` cookie.
+- `POST /api/v1/auth/register` creates a regular `user` account and sets the session cookie.
+- `POST /api/v1/auth/logout` clears the session cookie.
+- `GET /api/v1/auth/setup-status` reports whether the first admin still needs to be created.

-For production deployments, it is recommended to:
-1. Use Nginx for basic auth or OAuth integration
-2. Deploy behind a VPN or private network
-3. Implement custom authentication middleware
+The authenticated auth endpoints are:
+
+- `GET /api/v1/auth/me` returns the current user.
+- `POST /api/v1/auth/change-password` changes password, optionally changes email during setup, increments `token_version`, and reissues the cookie.
+
+Protected state-changing requests also require the CSRF double-submit token: send the `csrf_token` cookie value as the `X-CSRF-Token` header. Login/register/initialize/logout are bootstrap auth endpoints: they are exempt from the double-submit token but still reject hostile browser `Origin` headers.
+
+User isolation is enforced from the authenticated user context:
+
+- Thread metadata is scoped by `threads_meta.user_id`; search/read/write/delete APIs only expose the current user's threads.
+- Thread files live under `{base_dir}/users/{user_id}/threads/{thread_id}/user-data/` and are exposed inside the sandbox as `/mnt/user-data/`.
+- Memory and custom agents are stored under `{base_dir}/users/{user_id}/...`.
+
+Note: MCP outbound connections can still use OAuth for configured HTTP/SSE MCP servers; that is separate from DeerFlow API authentication.

 ---

@@ -567,12 +575,13 @@ location /api/ {

 ---

-## WebSocket Support
+## Streaming Support

-The LangGraph server supports WebSocket connections for real-time streaming. Connect to:
+Gateway's LangGraph-compatible API streams run events with Server-Sent Events (SSE):

-```
-ws://localhost:2026/api/langgraph/threads/{thread_id}/runs/stream
+```http
+POST /api/langgraph/threads/{thread_id}/runs/stream
+Accept: text/event-stream
 ```

 ---
@@ -608,13 +617,21 @@ const response = await fetch('/api/models');
 const data = await response.json();
 console.log(data.models);

-// Using EventSource for streaming
-const eventSource = new EventSource(
-  `/api/langgraph/threads/${threadId}/runs/stream`
-);
-eventSource.onmessage = (event) => {
-  console.log(JSON.parse(event.data));
-};
+// Create a run and stream SSE events
+const streamResponse = await fetch(`/api/langgraph/threads/${threadId}/runs/stream`, {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    Accept: "text/event-stream",
+  },
+  body: JSON.stringify({
+    input: { messages: [{ role: "user", content: "Hello" }] },
+    stream_mode: ["values", "messages-tuple", "custom"],
+  }),
+});
+
+const reader = streamResponse.body?.getReader();
+// Decode and parse SSE frames from reader in your client code.
 ```

 ### cURL Examples
@@ -649,7 +666,7 @@ curl -X POST http://localhost:2026/api/langgraph/threads/abc123/runs \
  }'
 ```

-> The `/api/langgraph/*` endpoints bypass DeerFlow's Gateway and inherit
-> LangGraph's native `recursion_limit` default of 25, which is too low for
-> plan-mode or subagent runs. Set `config.recursion_limit` explicitly — see
-> the [Create Run](#create-run) section for details.
+> The unified Gateway path defaults `config.recursion_limit` to 100 for
+> plan-mode and subagent-heavy runs. Clients may still set
+> `config.recursion_limit` explicitly — see the [Create Run](#create-run)
+> section for details.
@@ -14,30 +14,28 @@ This document provides a comprehensive overview of the DeerFlow backend architec
 │                          Nginx (Port 2026)                               │
 │                    Unified Reverse Proxy Entry Point                      │
 │  ┌────────────────────────────────────────────────────────────────────┐  │
-│  │  /api/langgraph/*  →  LangGraph Server (2024)                      │  │
-│  │  /api/*            →  Gateway API (8001)                           │  │
+│  │  /api/langgraph/*  →  Gateway LangGraph-compatible runtime (8001)  │  │
+│  │  /api/*            →  Gateway REST APIs (8001)                     │  │
 │  │  /*                →  Frontend (3000)                               │  │
 │  └────────────────────────────────────────────────────────────────────┘  │
 └─────────────────────────────────┬────────────────────────────────────────┘
                                  │
-          ┌───────────────────────┼───────────────────────┐
-          │                       │                       │
-          ▼                       ▼                       ▼
-┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
-│   LangGraph Server  │ │    Gateway API      │ │     Frontend        │
-│     (Port 2024)     │ │    (Port 8001)      │ │    (Port 3000)      │
-│                     │ │                     │ │                     │
-│  - Agent Runtime    │ │  - Models API       │ │  - Next.js App      │
-│  - Thread Mgmt      │ │  - MCP Config       │ │  - React UI         │
-│  - SSE Streaming    │ │  - Skills Mgmt      │ │  - Chat Interface   │
-│  - Checkpointing    │ │  - File Uploads     │ │                     │
-│                     │ │  - Thread Cleanup   │ │                     │
-│                     │ │  - Artifacts        │ │                     │
-└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
-          │                       │
-          │     ┌─────────────────┘
-          │     │
-          ▼     ▼
+          ┌───────────────────────┴───────────────────────┐
+          │                                               │
+          ▼                                               ▼
+┌─────────────────────────────────────────────┐ ┌─────────────────────┐
+│              Gateway API                    │ │     Frontend        │
+│              (Port 8001)                    │ │    (Port 3000)      │
+│                                             │ │                     │
+│  - LangGraph-compatible runs/threads API    │ │  - Next.js App      │
+│  - Embedded Agent Runtime                   │ │  - React UI         │
+│  - SSE Streaming                            │ │  - Chat Interface   │
+│  - Checkpointing                            │ │                     │
+│  - Models, MCP, Skills, Uploads, Artifacts  │ │                     │
+│  - Thread Cleanup                           │ │                     │
+└─────────────────────────────────────────────┘ └─────────────────────┘
+          │
+          ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │                         Shared Configuration                              │
 │  ┌─────────────────────────┐  ┌────────────────────────────────────────┐ │
@@ -52,9 +50,9 @@ This document provides a comprehensive overview of the DeerFlow backend architec

 ## Component Details

-### LangGraph Server
+### Gateway Embedded Agent Runtime

-The LangGraph server is the core agent runtime, built on LangGraph for robust multi-agent workflow orchestration.
+The agent runtime is embedded in the FastAPI Gateway and built on LangGraph for robust multi-agent workflow orchestration. Nginx rewrites `/api/langgraph/*` to Gateway's native `/api/*` routes, so the public API remains compatible with LangGraph SDK clients without running a separate LangGraph server.

 **Entry Point**: `packages/harness/deerflow/agents/lead_agent/agent.py:make_lead_agent`

@@ -65,7 +63,8 @@ The LangGraph server is the core agent runtime, built on LangGraph for robust mu
 - Tool execution orchestration
 - SSE streaming for real-time responses

-**Configuration**: `langgraph.json`
+**Graph registry**: `langgraph.json` remains available for tooling, Studio, or direct LangGraph Server compatibility.
+It is not the default service entrypoint; scripts and Docker deployments run the Gateway embedded runtime.

 ```json
 {
@@ -78,12 +77,13 @@ The LangGraph server is the core agent runtime, built on LangGraph for robust mu

 ### Gateway API

-FastAPI application providing REST endpoints for non-agent operations.
+FastAPI application providing REST endpoints plus the public LangGraph-compatible `/api/langgraph/*` runtime routes.

 **Entry Point**: `app/gateway/app.py`

 **Routers**:
 - `models.py` - `/api/models` - Model listing and details
+- `thread_runs.py` / `runs.py` - `/api/threads/{id}/runs`, `/api/runs/*` - LangGraph-compatible runs and streaming
 - `mcp.py` - `/api/mcp` - MCP server configuration
 - `skills.py` - `/api/skills` - Skills management
 - `uploads.py` - `/api/threads/{id}/uploads` - File upload
@@ -91,7 +91,7 @@ FastAPI application providing REST endpoints for non-agent operations.
 - `artifacts.py` - `/api/threads/{id}/artifacts` - Artifact serving
 - `suggestions.py` - `/api/threads/{id}/suggestions` - Follow-up suggestion generation

-The web conversation delete flow is now split across both backend surfaces: LangGraph handles `DELETE /api/langgraph/threads/{thread_id}` for thread state, then the Gateway `threads.py` router removes DeerFlow-managed filesystem data via `Paths.delete_thread_dir()`.
+The web conversation delete flow first deletes Gateway-managed thread state through the LangGraph-compatible route, then the Gateway `threads.py` router removes DeerFlow-managed filesystem data via `Paths.delete_thread_dir()`.

 ### Agent Architecture

@@ -353,10 +353,10 @@ SKILL.md Format:
   POST /api/langgraph/threads/{thread_id}/runs
   {"input": {"messages": [{"role": "user", "content": "Hello"}]}}

-2. Nginx → LangGraph Server (2024)
-   Proxied to LangGraph server
+2. Nginx → Gateway API (8001)
+   `/api/langgraph/*` is rewritten to Gateway's LangGraph-compatible `/api/*` routes

-3. LangGraph Server
+3. Gateway embedded runtime
   a. Load/create thread state
   b. Execute middleware chain:
      - ThreadDataMiddleware: Set up paths
@@ -412,7 +412,7 @@ SKILL.md Format:
 ### Thread Cleanup Flow

 ```
-1. Client deletes conversation via LangGraph
+1. Client deletes conversation via the LangGraph-compatible Gateway route
   DELETE /api/langgraph/threads/{thread_id}

 2. Web UI follows up with Gateway cleanup
@@ -0,0 +1,331 @@
+# 用户认证与隔离设计
+
+本文档描述 DeerFlow 当前内置认证模块的设计，而不是历史 RFC。它覆盖浏览器登录、API 认证、CSRF、用户隔离、首次初始化、密码重置、内部调用和升级迁移。
+
+## 设计目标
+
+认证模块的核心目标是把 DeerFlow 从“本地单用户工具”提升为“可多用户部署的 agent runtime”，并让用户身份贯穿 HTTP API、LangGraph-compatible runtime、文件系统、memory、自定义 agent 和反馈数据。
+
+设计约束：
+
+- 默认强制认证：除健康检查、文档和 auth bootstrap 端点外，HTTP 路由都必须有有效 session。
+- 服务端持有所有权：客户端 metadata 不能声明 `user_id` 或 `owner_id`。
+- 隔离默认开启：repository（仓储）、文件路径、memory、agent 配置默认按当前用户解析。
+- 旧数据可升级：无认证版本留下的 thread 可以在 admin 存在后迁移到 admin。
+- 密码不进日志：首次初始化由操作者设置密码；`reset_admin` 只写 0600 凭据文件。
+
+非目标：
+
+- 当前 OAuth 端点只是占位，尚未实现第三方登录。
+- 当前用户角色只有 `admin` 和 `user`，尚未实现细粒度 RBAC。
+- 当前登录限速是进程内字典，多 worker 下不是全局精确限速。
+
+## 核心模型
+
+```mermaid
+graph TB
+  classDef actor fill:#D8CFC4,stroke:#6E6259,color:#2F2A26;
+  classDef api fill:#C9D7D2,stroke:#5D706A,color:#21302C;
+  classDef state fill:#D7D3E8,stroke:#6B6680,color:#29263A;
+  classDef data fill:#E5D2C4,stroke:#806A5B,color:#30251E;
+
+  Browser["Browser — access_token cookie and csrf_token cookie"]:::actor
+  AuthMiddleware["AuthMiddleware — strict session gate"]:::api
+  CSRFMiddleware["CSRFMiddleware — double-submit token and Origin check"]:::api
+  AuthRoutes["Auth routes — initialize login register logout me change-password"]:::api
+  UserContext["Current user ContextVar — request-scoped identity"]:::state
+  Repositories["Repositories — AUTO resolves user_id from context"]:::state
+  Files["Filesystem — users/{user_id}/threads/{thread_id}/user-data"]:::data
+  Memory["Memory and agents — users/{user_id}/memory.json and agents"]:::data
+
+  Browser --> AuthMiddleware
+  Browser --> CSRFMiddleware
+  AuthMiddleware --> AuthRoutes
+  AuthMiddleware --> UserContext
+  UserContext --> Repositories
+  UserContext --> Files
+  UserContext --> Memory
+```
+
+### 用户表
+
+用户记录定义在 `app.gateway.auth.models.User`，持久化到 `users` 表。关键字段：
+
+| 字段 | 语义 |
+|---|---|
+| `id` | 用户主键，JWT `sub` 使用该值 |
+| `email` | 唯一登录名 |
+| `password_hash` | bcrypt hash，OAuth 用户可为空 |
+| `system_role` | `admin` 或 `user` |
+| `needs_setup` | reset 后要求用户完成邮箱 / 密码设置 |
+| `token_version` | 改密码或 reset 时递增，用于废弃旧 JWT |
+
+### 运行时身份
+
+认证成功后，`AuthMiddleware` 把用户同时写入：
+
+- `request.state.user`
+- `request.state.auth`
+- `deerflow.runtime.user_context` 的 `ContextVar`
+
+`ContextVar` 是这里的核心边界。上层 Gateway 负责写入身份，下层 persistence / file path 只读取结构化的当前用户，不反向依赖 `app.gateway.auth` 具体类型。
+
+可以把 repository 调用的用户参数理解成一个三态 ADT：
+
+```scala
+enum UserScope:
+  case AutoFromContext
+  case Explicit(userId: String)
+  case BypassForMigration
+```
+
+对应 Python 实现是 `AUTO | str | None`：
+
+- `AUTO`：从 `ContextVar` 解析当前用户；没有上下文则抛错。
+- `str`：显式指定用户，主要用于测试或管理脚本。
+- `None`：跳过用户过滤，只允许迁移脚本或 admin CLI 使用。
+
+## 登录与初始化流程
+
+### 首次初始化
+
+首次启动时，如果没有 admin，服务不会自动创建账号，只记录日志提示访问 `/setup`。
+
+流程：
+
+1. 用户访问 `/setup`。
+2. 前端调用 `GET /api/v1/auth/setup-status`。
+3. 如果返回 `{"needs_setup": true}`，前端展示创建 admin 表单。
+4. 表单提交 `POST /api/v1/auth/initialize`。
+5. 服务端确认当前没有 admin，创建 `system_role="admin"`、`needs_setup=false` 的用户。
+6. 服务端设置 `access_token` HttpOnly cookie，用户进入 workspace。
+
+`/api/v1/auth/initialize` 只在没有 admin 时可用。并发初始化由数据库唯一约束兜底，失败方返回 409。
+
+### 普通登录
+
+`POST /api/v1/auth/login/local` 使用 `OAuth2PasswordRequestForm`：
+
+- `username` 是邮箱。
+- `password` 是密码。
+- 成功后签发 JWT，放入 `access_token` HttpOnly cookie。
+- 响应体只返回 `expires_in` 和 `needs_setup`，不返回 token。
+
+登录失败会按客户端 IP 计数。IP 解析只在 TCP peer 属于 `AUTH_TRUSTED_PROXIES` 时信任 `X-Real-IP`，不使用 `X-Forwarded-For`。
+
+### 注册
+
+`POST /api/v1/auth/register` 创建普通 `user`，并自动登录。
+
+当前实现允许在没有 admin 时注册普通用户，但 `setup-status` 仍会返回 `needs_setup=true`，因为 admin 仍不存在。这是当前产品策略边界：如果后续要求“必须先初始化 admin 才能注册普通用户”，需要在 `/register` 增加 admin-exists gate。
+
+### 改密码与 reset setup
+
+`POST /api/v1/auth/change-password` 需要当前密码和新密码：
+
+- 校验当前密码。
+- 更新 bcrypt hash。
+- `token_version += 1`，使旧 JWT 立即失效。
+- 重新签发 cookie。
+- 如果 `needs_setup=true` 且传了 `new_email`，则更新邮箱并清除 `needs_setup`。
+
+`python -m app.gateway.auth.reset_admin` 会：
+
+- 找到 admin 或指定邮箱用户。
+- 生成随机密码。
+- 更新密码 hash。
+- `token_version += 1`。
+- 设置 `needs_setup=true`。
+- 写入 `.deer-flow/admin_initial_credentials.txt`，权限 `0600`。
+
+命令行只输出凭据文件路径，不输出明文密码。
+
+## HTTP 认证边界
+
+`AuthMiddleware` 是 fail-closed（默认拒绝）的全局认证门。
+
+公开路径：
+
+- `/health`
+- `/docs`
+- `/redoc`
+- `/openapi.json`
+- `/api/v1/auth/login/local`
+- `/api/v1/auth/register`
+- `/api/v1/auth/logout`
+- `/api/v1/auth/setup-status`
+- `/api/v1/auth/initialize`
+
+其余路径都要求有效 `access_token` cookie。存在 cookie 但 JWT 无效、过期、用户不存在或 `token_version` 不匹配时，直接返回 401，而不是让请求穿透到业务路由。
+
+路由级别的 owner check 由 `require_permission(..., owner_check=True)` 完成：
+
+- 读类请求允许旧的未追踪 legacy thread 兼容读取。
+- 写 / 删除类请求使用 `require_existing=True`，要求 thread row 存在且属于当前用户，避免删除后缺 row 导致其他用户误通过。
+
+## CSRF 设计
+
+DeerFlow 使用 Double Submit Cookie：
+
+- 服务端设置 `csrf_token` cookie。
+- 前端 state-changing 请求发送同值 `X-CSRF-Token` header。
+- 服务端用 `secrets.compare_digest` 比较 cookie/header。
+
+需要 CSRF 的方法：
+
+- `POST`
+- `PUT`
+- `DELETE`
+- `PATCH`
+
+auth bootstrap 端点（login/register/initialize/logout）不要求 double-submit token，因为首次调用时浏览器还没有 token；但这些端点会校验 browser `Origin`，拒绝 hostile Origin，避免 login CSRF / session fixation。
+
+## 用户隔离
+
+### Thread metadata
+
+Thread metadata 存在 `threads_meta`，关键隔离字段是 `user_id`。
+
+创建 thread 时：
+
+- 客户端传入的 `metadata.user_id` 和 `metadata.owner_id` 会被剥离。
+- `ThreadMetaRepository.create(..., user_id=AUTO)` 从 `ContextVar` 解析真实用户。
+- `/api/threads/search` 默认只返回当前用户的 thread。
+
+读取 / 修改 / 删除时：
+
+- `get()` 默认按当前用户过滤。
+- `check_access()` 用于路由 owner check。
+- 对其他用户的 thread 返回 404，避免泄露资源存在性。
+
+### 文件系统
+
+当前线程文件布局：
+
+```text
+{base_dir}/users/{user_id}/threads/{thread_id}/user-data/
+├── workspace/
+├── uploads/
+└── outputs/
+```
+
+agent 在 sandbox 内看到统一虚拟路径：
+
+```text
+/mnt/user-data/workspace
+/mnt/user-data/uploads
+/mnt/user-data/outputs
+```
+
+`ThreadDataMiddleware` 使用 `get_effective_user_id()` 解析当前用户并生成线程路径。没有认证上下文时会落到 `default` 用户桶，主要用于内部调用、嵌入式 client 或无 HTTP 的本地执行路径。
+
+### Memory
+
+默认 memory 存储：
+
+```text
+{base_dir}/users/{user_id}/memory.json
+{base_dir}/users/{user_id}/agents/{agent_name}/memory.json
+```
+
+有用户上下文时，空或相对 `memory.storage_path` 都使用上述 per-user 默认路径；只有绝对 `memory.storage_path` 会视为显式 opt-out（退出） per-user isolation，所有用户共享该路径。无用户上下文的 legacy 路径仍会把相对 `storage_path` 解析到 `Paths.base_dir` 下。
+
+### 自定义 agent
+
+用户自定义 agent 写入：
+
+```text
+{base_dir}/users/{user_id}/agents/{agent_name}/
+├── config.yaml
+├── SOUL.md
+└── memory.json
+```
+
+旧布局 `{base_dir}/agents/{agent_name}/` 只作为只读兼容回退。更新或删除旧共享 agent 会要求先运行迁移脚本。
+
+## 内部调用与 IM 渠道
+
+IM channel worker 不是浏览器用户，不持有浏览器 cookie。它们通过 Gateway 内部认证：
+
+- 请求带 `X-DeerFlow-Internal-Token`。
+- 同时带匹配的 CSRF cookie/header。
+- 服务端识别为内部用户，`id="default"`、`system_role="internal"`。
+
+这意味着 channel 产生的数据默认进入 `default` 用户桶。这个选择适合“平台级 bot 身份”，但不是“每个 IM 用户单独隔离”。如果后续要做到外部 IM 用户隔离，需要把外部 platform user 映射到 DeerFlow user，并让 channel manager 设置对应的 scoped identity。
+
+## LangGraph-compatible 认证
+
+Gateway 内嵌 runtime 路径由 `AuthMiddleware` 和 `CSRFMiddleware` 保护。
+
+仓库仍保留 `app.gateway.langgraph_auth`，用于 LangGraph Server 直连模式：
+
+- `@auth.authenticate` 校验 JWT cookie、CSRF、用户存在性和 `token_version`。
+- `@auth.on` 在写入 metadata 时注入 `user_id`，并在读路径返回 `{"user_id": current_user}` 过滤条件。
+
+这保证 Gateway 路由和 LangGraph-compatible 直连模式使用同一 JWT 语义。
+
+## 升级与迁移
+
+从无认证版本升级时，可能存在没有 `user_id` 的历史 thread。
+
+当前策略：
+
+1. 首次启动如果没有 admin，只提示访问 `/setup`，不迁移。
+2. 操作者创建 admin。
+3. 后续启动时，`_ensure_admin_user()` 找到 admin，并把 LangGraph store 中缺少 `metadata.user_id` 的 thread 迁移到 admin。
+
+文件系统旧布局迁移由脚本处理：
+
+```bash
+cd backend
+PYTHONPATH=. python scripts/migrate_user_isolation.py --dry-run
+PYTHONPATH=. python scripts/migrate_user_isolation.py --user-id <target-user-id>
+```
+
+迁移脚本覆盖 legacy `memory.json`、`threads/` 和 `agents/` 到 per-user layout。
+
+## 安全不变量
+
+必须长期保持的不变量：
+
+- JWT 只在 HttpOnly cookie 中传输，不出现在响应 JSON。
+- 任何非 public HTTP 路由都不能只靠“cookie 存在”放行，必须严格验证 JWT。
+- `token_version` 不匹配必须拒绝，保证改密码 / reset 后旧 session 失效。
+- 客户端 metadata 中的 `user_id` / `owner_id` 必须剥离。
+- repository 默认 `AUTO` 必须从当前用户上下文解析，不能静默退化成全局查询。
+- 只有迁移脚本和 admin CLI 可以显式传 `user_id=None` 绕过隔离。
+- 本地文件路径必须通过 `Paths` 和 sandbox path validation 解析，不能拼接未校验的用户输入。
+- 捕获认证、迁移、后台任务异常必须记录日志；不能空 catch。
+
+## 已知边界
+
+| 边界 | 当前行为 | 后续方向 |
+|---|---|---|
+| 无 admin 时注册普通用户 | 允许注册普通 `user` | 如产品要求先初始化 admin，给 `/register` 加 gate |
+| 登录限速 | 进程内 dict，单 worker 精确，多 worker 近似 | Redis / DB-backed rate limiter |
+| OAuth | 端点占位，未实现 | 接入 provider 并统一 `token_version` / role 语义 |
+| IM 用户隔离 | channel 使用 `default` 内部用户 | 建立外部用户到 DeerFlow user 的映射 |
+| 绝对 memory path | 显式共享 memory | UI / docs 明确提示 opt-out 风险 |
+
+## 相关文件
+
+| 文件 | 职责 |
+|---|---|
+| `app/gateway/auth_middleware.py` | 全局认证门、JWT 严格验证、写入 user context |
+| `app/gateway/csrf_middleware.py` | CSRF double-submit 和 auth Origin 校验 |
+| `app/gateway/routers/auth.py` | initialize/login/register/logout/me/change-password |
+| `app/gateway/auth/jwt.py` | JWT 创建与解析 |
+| `app/gateway/auth/reset_admin.py` | 密码 reset CLI |
+| `app/gateway/auth/credential_file.py` | 0600 凭据文件写入 |
+| `app/gateway/authz.py` | 路由权限与 owner check |
+| `deerflow/runtime/user_context.py` | 当前用户 ContextVar 与 `AUTO` sentinel |
+| `deerflow/persistence/thread_meta/` | thread metadata owner filter |
+| `deerflow/config/paths.py` | per-user filesystem layout |
+| `deerflow/agents/middlewares/thread_data_middleware.py` | run 时解析用户线程目录 |
+| `deerflow/agents/memory/storage.py` | per-user memory storage |
+| `deerflow/config/agents_config.py` | per-user custom agents |
+| `app/channels/manager.py` | IM channel 内部认证调用 |
+| `scripts/migrate_user_isolation.py` | legacy 数据迁移到 per-user layout |
+| `.deer-flow/data/deerflow.db` | 统一 SQLite 数据库，包含 users / threads_meta / runs / feedback 等表 |
+| `.deer-flow/users/{user_id}/agents/{agent_name}/` | 用户自定义 agent 配置、SOUL 和 agent memory |
+| `.deer-flow/admin_initial_credentials.txt` | `reset_admin` 生成的新凭据文件（0600，读完应删除） |
@@ -24,11 +24,11 @@ All other test plan sections were executed against either:

 | Case | Title | What it covers | Why not run |
 |---|---|---|---|
-| TC-DOCKER-01 | `users.db` volume persistence | Verify the `DEER_FLOW_HOME` bind mount survives container restart | needs `docker compose up` |
+| TC-DOCKER-01 | `deerflow.db` volume persistence | Verify the `DEER_FLOW_HOME` bind mount survives container restart | needs `docker compose up` |
 | TC-DOCKER-02 | Session persistence across container restart | `AUTH_JWT_SECRET` env var keeps cookies valid after `docker compose down && up` | needs `docker compose down/up` |
 | TC-DOCKER-03 | Per-worker rate limiter divergence | Confirms in-process `_login_attempts` dict doesn't share state across `gunicorn` workers (4 by default in the compose file); known limitation, documented | needs multi-worker container |
-| TC-DOCKER-04 | IM channels skip AuthMiddleware | Verify Feishu/Slack/Telegram dispatchers run in-container against `http://langgraph:2024` without going through nginx | needs `docker logs` |
-| TC-DOCKER-05 | Admin credentials surfacing | **Updated post-simplify** — was "log scrape", now "0600 credential file in `DEER_FLOW_HOME`". The file-based behavior is already validated by TC-1.1 + TC-UPG-13 on sg_dev (non-Docker), so the only Docker-specific gap is verifying the volume mount carries the file out to the host | needs container + host volume |
+| TC-DOCKER-04 | IM channels use internal Gateway auth | Verify Feishu/Slack/Telegram dispatchers attach the process-local internal auth header plus CSRF cookie/header when calling Gateway-compatible LangGraph APIs | needs `docker logs` |
+| TC-DOCKER-05 | Reset credentials surfacing | `reset_admin` writes a 0600 credential file in `DEER_FLOW_HOME` instead of logging plaintext. The file-based behavior is validated by non-Docker reset tests, so the only Docker-specific gap is verifying the volume mount carries the file out to the host | needs container + host volume |
 | TC-DOCKER-06 | Gateway-mode Docker deploy | `./scripts/deploy.sh --gateway` produces a 3-container topology (no `langgraph` container); same auth flow as standard mode | needs `docker compose --profile gateway` |

 ## Coverage already provided by non-Docker tests
@@ -41,8 +41,8 @@ the test cases that ran on sg_dev or local:
 | TC-DOCKER-01 (volume persistence) | TC-REENT-01 on sg_dev (admin row survives gateway restart) — same SQLite file, just no container layer between |
 | TC-DOCKER-02 (session persistence) | TC-API-02/03/06 (cookie roundtrip), plus TC-REENT-04 (multi-cookie) — JWT verification is process-state-free, container restart is equivalent to `pkill uvicorn && uv run uvicorn` |
 | TC-DOCKER-03 (per-worker rate limit) | TC-GW-04 + TC-REENT-09 (single-worker rate limit + 5min expiry). The cross-worker divergence is an architectural property of the in-memory dict; no auth code path differs |
-| TC-DOCKER-04 (IM channels skip auth) | Code-level only: `app/channels/manager.py` uses `langgraph_sdk` directly with no cookie handling. The langgraph_auth handler is bypassed by going through SDK, not HTTP |
-| TC-DOCKER-05 (credential surfacing) | TC-1.1 on sg_dev (file at `~/deer-flow/backend/.deer-flow/admin_initial_credentials.txt`, mode 0600, password 22 chars) — the only Docker-unique step is whether the bind mount projects this path onto the host, which is a `docker compose` config check, not a runtime behavior change |
+| TC-DOCKER-04 (IM channels use internal auth) | Code-level: `app/channels/manager.py` creates the `langgraph_sdk` client with `create_internal_auth_headers()` plus CSRF cookie/header, so channel workers do not rely on browser cookies |
+| TC-DOCKER-05 (credential surfacing) | `reset_admin` writes `.deer-flow/admin_initial_credentials.txt` with mode 0600 and logs only the path — the only Docker-unique step is whether the bind mount projects this path onto the host, which is a `docker compose` config check, not a runtime behavior change |
 | TC-DOCKER-06 (gateway-mode container) | Section 七 7.2 covered by TC-GW-01..05 + Section 二 (gateway-mode auth flow on sg_dev) — same Gateway code, container is just a packaging change |

 ## Reproduction steps when Docker becomes available
@@ -72,6 +72,6 @@ Then run TC-DOCKER-01..06 from the test plan as written.
  about *container packaging* details (bind mounts, multi-worker, log
  collection), not about whether the auth code paths work.
 - **TC-DOCKER-05 was updated in place** in `AUTH_TEST_PLAN.md` to reflect
-  the post-simplify reality (credentials file → 0600 file, no log leak).
+  the current reset flow (`reset_admin` → 0600 credentials file, no log leak).
  The old "grep 'Password:' in docker logs" expectation would have failed
  silently and given a false sense of coverage.
@@ -19,7 +19,7 @@

 ```bash
 # 清除已有数据
-rm -f backend/.deer-flow/users.db
+rm -f backend/.deer-flow/data/deerflow.db

 # 选择模式启动
 make dev          # 标准模式
@@ -28,10 +28,11 @@ make dev-pro      # Gateway 模式
 ```

 **验证点：**
- [ ] 控制台输出 admin 邮箱和随机密码
- [ ] 密码格式为 `secrets.token_urlsafe(16)` 的 22 字符字符串
- [ ] 邮箱为 `admin@deerflow.dev`
- [ ] 提示 `Change it after login: Settings -> Account`
+- [ ] 控制台不输出 admin 邮箱或明文密码
+- [ ] 控制台提示 `First boot detected — no admin account exists.`
+- [ ] 控制台提示访问 `/setup` 完成 admin 创建
+- [ ] `GET /api/v1/auth/setup-status` 返回 `{"needs_setup": true}`
+- [ ] 前端访问 `/login` 会跳转 `/setup`

 ### 1.2 非首次启动

@@ -42,7 +43,8 @@ make dev

 **验证点：**
 - [ ] 控制台不输出密码
- [ ] 如果 admin 仍 `needs_setup=True`，控制台有 warning 提示
+- [ ] `GET /api/v1/auth/setup-status` 返回 `{"needs_setup": false}`
+- [ ] 已登录用户如果 `needs_setup=True`，访问 workspace 会被引导到 `/setup` 完成改邮箱 / 改密码流程

 ### 1.3 环境变量配置

@@ -76,19 +78,22 @@ make dev
 curl -s $BASE/api/v1/auth/setup-status | jq .
 ```

-**预期：** 返回 `{"needs_setup": false}`（admin 在启动时已自动创建，`count_users() > 0`）。仅在启动完成前的极短窗口内可能返回 `true`。
+**预期：**
+- 干净数据库且尚未初始化 admin：返回 `{"needs_setup": true}`
+- 已存在 admin：返回 `{"needs_setup": false}`

-#### TC-API-02: Admin 首次登录
+#### TC-API-02: 首次初始化 Admin

 ```bash
-curl -s -X POST $BASE/api/v1/auth/login/local \
-  -d "username=admin@deerflow.dev&password=<控制台密码>" \
+curl -s -X POST $BASE/api/v1/auth/initialize \
+  -H "Content-Type: application/json" \
+  -d '{"email":"admin@example.com","password":"AdminPass1!"}' \
  -c cookies.txt | jq .
 ```

 **预期：**
- 状态码 200
- Body: `{"expires_in": 604800, "needs_setup": true}`
+- 状态码 201
+- Body: `{"id": "...", "email": "admin@example.com", "system_role": "admin", "needs_setup": false}`
 - `cookies.txt` 包含 `access_token`（HttpOnly）和 `csrf_token`（非 HttpOnly）

 #### TC-API-03: 获取当前用户
@@ -97,9 +102,9 @@ curl -s -X POST $BASE/api/v1/auth/login/local \
 curl -s $BASE/api/v1/auth/me -b cookies.txt | jq .
 ```

-**预期：** `{"id": "...", "email": "admin@deerflow.dev", "system_role": "admin", "needs_setup": true}`
+**预期：** `{"id": "...", "email": "admin@example.com", "system_role": "admin", "needs_setup": false}`

-#### TC-API-04: Setup 流程（改邮箱 + 改密码）
+#### TC-API-04: 改密码流程

 ```bash
 CSRF=$(grep csrf_token cookies.txt | awk '{print $NF}')
@@ -107,13 +112,36 @@ curl -s -X POST $BASE/api/v1/auth/change-password \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
-  -d '{"current_password":"<控制台密码>","new_password":"NewPass123!","new_email":"admin@example.com"}' | jq .
+  -d '{"current_password":"AdminPass1!","new_password":"NewPass123!"}' | jq .
 ```

 **预期：**
 - 状态码 200
 - `{"message": "Password changed successfully"}`
- 再调 `/auth/me` 邮箱变为 `admin@example.com`，`needs_setup` 变为 `false`
+- 再调 `/auth/me` 仍为 `admin@example.com`，`needs_setup` 仍为 `false`
+
+#### TC-API-04a: reset_admin 后的 Setup 流程（改邮箱 + 改密码）
+
+```bash
+cd backend
+python -m app.gateway.auth.reset_admin --email admin@example.com
+# 从 .deer-flow/admin_initial_credentials.txt 读取 reset 后密码
+
+curl -s -X POST $BASE/api/v1/auth/login/local \
+  -d "username=admin@example.com&password=<凭据文件密码>" \
+  -c cookies.txt | jq .
+
+CSRF=$(grep csrf_token cookies.txt | awk '{print $NF}')
+curl -s -X POST $BASE/api/v1/auth/change-password \
+  -b cookies.txt \
+  -H "Content-Type: application/json" \
+  -H "X-CSRF-Token: $CSRF" \
+  -d '{"current_password":"<凭据文件密码>","new_password":"AdminPass2!","new_email":"admin2@example.com"}' | jq .
+```
+
+**预期：**
+- 登录返回 `{"expires_in": 604800, "needs_setup": true}`
+- `change-password` 后 `/auth/me` 邮箱变为 `admin2@example.com`，`needs_setup` 变为 `false`

 #### TC-API-05: 普通用户注册

@@ -493,7 +521,7 @@ curl -s -X POST $BASE/api/v1/auth/register \

 ```bash
 # 检查数据库
-sqlite3 backend/.deer-flow/users.db "SELECT email, password_hash FROM users LIMIT 3;"
+sqlite3 backend/.deer-flow/data/deerflow.db "SELECT email, password_hash FROM users LIMIT 3;"
 ```

 **预期：** `password_hash` 以 `$2b$` 开头（bcrypt 格式）
@@ -506,24 +534,25 @@ sqlite3 backend/.deer-flow/users.db "SELECT email, password_hash FROM users LIMI

 ### 4.1 首次登录流程

-#### TC-UI-01: 访问首页跳转登录
+#### TC-UI-01: 无 admin 时访问 workspace 跳转 setup

 1. 打开 `http://localhost:2026/workspace`
-2. **预期：** 自动跳转到 `/login`
+2. **预期：** 自动跳转到 `/setup`

-#### TC-UI-02: Login 页面
+#### TC-UI-02: Setup 页面创建 admin

-1. 输入 admin 邮箱和控制台密码
-2. 点击 Login
-3. **预期：** 跳转到 `/setup`（因为 `needs_setup=true`）
-
-#### TC-UI-03: Setup 页面
-
-1. 输入新邮箱、控制台密码（current）、新密码、确认密码
-2. 点击 Complete Setup
+1. 输入 admin 邮箱、密码、确认密码
+2. 点击 Create Admin Account
 3. **预期：** 跳转到 `/workspace`
 4. 刷新页面不跳回 `/setup`

+#### TC-UI-03: 已初始化后 Login 页面
+
+1. 退出登录后访问 `/login`
+2. 输入 admin 邮箱和密码
+3. 点击 Login
+4. **预期：** 跳转到 `/workspace`
+
 #### TC-UI-04: Setup 密码不匹配

 1. 新密码和确认密码不一致
@@ -602,7 +631,7 @@ sqlite3 backend/.deer-flow/users.db "SELECT email, password_hash FROM users LIMI
 #### TC-UI-15: reset_admin 后重新登录

 1. 执行 `cd backend && python -m app.gateway.auth.reset_admin`
-2. 使用新密码登录
+2. 从 `.deer-flow/admin_initial_credentials.txt` 读取新密码并登录
 3. **预期：** 跳转到 `/setup` 页面（`needs_setup` 被重置为 true）
 4. 旧 session 已失效

@@ -645,18 +674,28 @@ make install
 make dev
 ```

-#### TC-UPG-01: 首次启动创建 admin
+#### TC-UPG-01: 首次启动等待 admin 初始化

 **预期：**
- [ ] 控制台输出 admin 邮箱（`admin@deerflow.dev`）和随机密码
+- [ ] 控制台不输出 admin 邮箱或随机密码
+- [ ] 访问 `/setup` 可创建第一个 admin
 - [ ] 无报错，正常启动

 #### TC-UPG-02: 旧 Thread 迁移到 admin

 ```bash
+# 创建第一个 admin
+curl -s -X POST http://localhost:2026/api/v1/auth/initialize \
+  -H "Content-Type: application/json" \
+  -d '{"email":"admin@example.com","password":"AdminPass1!"}' \
+  -c cookies.txt
+
+# 重启一次：启动迁移只在已有 admin 的启动路径执行
+make stop && make dev
+
 # 登录 admin
 curl -s -X POST http://localhost:2026/api/v1/auth/login/local \
-  -d "username=admin@deerflow.dev&password=<控制台密码>" \
+  -d "username=admin@example.com&password=AdminPass1!" \
  -c cookies.txt

 # 查看 thread 列表
@@ -670,8 +709,8 @@ curl -s -X POST http://localhost:2026/api/threads/search \

 **预期：**
 - [ ] 返回的 thread 数量 ≥ 旧版创建的数量
- [ ] 控制台日志有 `Migrated N orphaned thread(s) to admin`
- [ ] 每个 thread 的 `metadata.owner_id` 都已被设为 admin 的 ID
+- [ ] 控制台日志有 `Migrated N orphan LangGraph thread(s) to admin`
+- [ ] 旧 thread 只对 admin 可见

 #### TC-UPG-03: 旧 Thread 内容完整

@@ -683,7 +722,7 @@ curl -s http://localhost:2026/api/threads/<old-thread-id> \

 **预期：**
 - [ ] `metadata.title` 保留原值（如 `old-thread-1`）
- [ ] `metadata.owner_id` 已填充
+- [ ] 响应不回显服务端保留的 `user_id` / `owner_id`

 #### TC-UPG-04: 新用户看不到旧 Thread

@@ -706,18 +745,19 @@ curl -s -X POST http://localhost:2026/api/threads/search \

 ### 5.3 数据库 Schema 兼容

-#### TC-UPG-05: 无 users.db 时自动创建
+#### TC-UPG-05: 无 deerflow.db 时创建 schema 但不创建默认用户

 ```bash
-ls -la backend/.deer-flow/users.db
+ls -la backend/.deer-flow/data/deerflow.db
+sqlite3 backend/.deer-flow/data/deerflow.db "SELECT COUNT(*) FROM users;"
 ```

-**预期：** 文件存在，`sqlite3` 可查到 `users` 表含 `needs_setup`、`token_version` 列
+**预期：** 文件存在，`sqlite3` 可查到 `users` 表含 `needs_setup`、`token_version` 列；未调用 `/initialize` 前用户数为 0

-#### TC-UPG-06: users.db WAL 模式
+#### TC-UPG-06: deerflow.db WAL 模式

 ```bash
-sqlite3 backend/.deer-flow/users.db "PRAGMA journal_mode;"
+sqlite3 backend/.deer-flow/data/deerflow.db "PRAGMA journal_mode;"
 ```

 **预期：** 返回 `wal`
@@ -768,9 +808,9 @@ make dev
 ```

 **预期：**
- [ ] 服务正常启动（忽略 `users.db`，无 auth 相关代码不报错）
+- [ ] 服务正常启动（忽略 `deerflow.db`，无 auth 相关代码不报错）
 - [ ] 旧对话数据仍然可访问
- [ ] `users.db` 文件残留但不影响运行
+- [ ] `deerflow.db` 文件残留但不影响运行

 #### TC-UPG-12: 再次升级到 auth 分支

@@ -781,51 +821,47 @@ make dev
 ```

 **预期：**
- [ ] 识别已有 `users.db`，不重新创建 admin
- [ ] 旧的 admin 账号仍可登录（如果回退期间未删 `users.db`）
+- [ ] 识别已有 `deerflow.db`，不重新创建 admin
+- [ ] 旧的 admin 账号仍可登录（如果回退期间未删 `deerflow.db`）

-### 5.7 休眠 Admin（初始密码未使用/未更改）
+### 5.7 Admin 初始化与 reset_admin

-> 首次启动生成 admin + 随机密码，但运维未登录、未改密码。
-> 密码只在首次启动的控制台闪过一次，后续启动不再显示。
+> 首次启动不生成默认 admin，也不在日志输出密码。忘记密码时走 `reset_admin`，新密码写入 0600 凭据文件。

-#### TC-UPG-13: 重启后自动重置密码并打印
+#### TC-UPG-13: 未初始化 admin 时重启不创建默认账号

 ```bash
-# 首次启动，记录密码
-rm -f backend/.deer-flow/users.db
+rm -f backend/.deer-flow/data/deerflow.db
 make dev
-# 控制台输出密码 P0，不登录
 make stop

-# 隔了几天，再次启动
 make dev
-# 控制台输出新密码 P1
+curl -s $BASE/api/v1/auth/setup-status | jq .
 ```

 **预期：**
- [ ] 控制台输出 `Admin account setup incomplete — password reset`
- [ ] 输出新密码 P1（P0 已失效）
- [ ] 用 P1 可以登录，P0 不可以
- [ ] 登录后 `needs_setup=true`，跳转 `/setup`
- [ ] `token_version` 递增（旧 session 如有也失效）
+- [ ] 控制台不输出密码
+- [ ] `setup-status` 仍为 `{"needs_setup": true}`
+- [ ] 访问 `/setup` 仍可创建第一个 admin

-#### TC-UPG-14: 密码丢失 — 无需 CLI，重启即可
+#### TC-UPG-14: 密码丢失 — reset_admin 写入凭据文件

 ```bash
-# 忘记了控制台密码 → 直接重启服务
-make stop && make dev
-# 控制台自动输出新密码
+python -m app.gateway.auth.reset_admin --email admin@example.com
+ls -la backend/.deer-flow/admin_initial_credentials.txt
+cat backend/.deer-flow/admin_initial_credentials.txt
 ```

 **预期：**
- [ ] 无需 `reset_admin`，重启服务即可拿到新密码
- [ ] `reset_admin` CLI 仍然可用作手动备选方案
+- [ ] 命令行只输出凭据文件路径，不输出明文密码
+- [ ] 凭据文件权限为 `0600`
+- [ ] 凭据文件包含 email + password 行
+- [ ] 该用户下次登录返回 `needs_setup=true`

-#### TC-UPG-15: 休眠 admin 期间普通用户注册
+#### TC-UPG-15: 未初始化 admin 期间普通用户注册策略边界

 ```bash
-# admin 存在但从未登录，普通用户先注册
+# admin 尚不存在，普通用户尝试注册
 curl -s -X POST $BASE/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"earlybird@example.com","password":"EarlyPass1!"}' \
@@ -833,11 +869,11 @@ curl -s -X POST $BASE/api/v1/auth/register \
 ```

 **预期：**
- [ ] 注册成功（201），角色为 `user`
- [ ] 无法提权为 admin
- [ ] 普通用户的数据与 admin 隔离
+- [ ] 当前代码允许注册普通用户并自动登录（201，角色为 `user`）
+- [ ] 但 `setup-status` 仍为 `{"needs_setup": true}`，因为 admin 仍不存在
+- [ ] 这是一个产品策略边界：若要求“必须先有 admin”，需要在 `/register` 增加 admin-exists gate

-#### TC-UPG-16: 休眠 admin 不影响后续操作
+#### TC-UPG-16: 普通用户数据与后续 admin 隔离

 ```bash
 # 普通用户正常创建 thread、发消息
@@ -849,14 +885,13 @@ curl -s -X POST $BASE/api/threads \
  -d '{"metadata":{}}' | jq .thread_id
 ```

-**预期：** 正常创建，不受休眠 admin 影响
+**预期：** 普通用户正常创建 thread；后续 admin 创建后，搜索不到该普通用户 thread

-#### TC-UPG-17: 休眠 admin 最终完成 Setup
+#### TC-UPG-17: reset_admin 后完成 Setup

 ```bash
-# 运维终于登录
 curl -s -X POST $BASE/api/v1/auth/login/local \
-  -d "username=admin@deerflow.dev&password=<P0或P1>" \
+  -d "username=admin@example.com&password=<凭据文件密码>" \
  -c admin.txt | jq .needs_setup
 # 预期: true

@@ -866,7 +901,7 @@ curl -s -X POST $BASE/api/v1/auth/change-password \
  -b admin.txt \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
-  -d '{"current_password":"<密码>","new_password":"AdminFinal1!","new_email":"admin@real.com"}' \
+  -d '{"current_password":"<凭据文件密码>","new_password":"AdminFinal1!","new_email":"admin@real.com"}' \
  -c admin.txt

 # 验证
@@ -876,7 +911,7 @@ curl -s $BASE/api/v1/auth/me -b admin.txt | jq '{email, needs_setup}'
 **预期：**
 - [ ] `email` 变为 `admin@real.com`
 - [ ] `needs_setup` 变为 `false`
- [ ] 后续重启控制台不再有 warning
+- [ ] 后续登录使用新密码

 #### TC-UPG-18: 长期未用后 JWT 密钥轮换

@@ -890,8 +925,8 @@ make stop && make dev

 **预期：**
 - [ ] 服务正常启动
- [ ] 旧密码仍可登录（密码存在 DB，与 JWT 密钥无关）
- [ ] 旧的 JWT token 失效（密钥变了签名不匹配）— 但因为从未登录过也没有旧 token
+- [ ] 账号密码仍可登录（密码存在 DB，与 JWT 密钥无关）
+- [ ] 旧的 JWT token 失效（密钥变了签名不匹配）

 ---

@@ -910,7 +945,7 @@ for i in 1 2 3; do
 done

 # 检查 admin 数量
-sqlite3 backend/.deer-flow/users.db \
+sqlite3 backend/.deer-flow/data/deerflow.db \
  "SELECT COUNT(*) FROM users WHERE system_role='admin';"
 ```

@@ -1055,7 +1090,7 @@ curl -s -X POST $BASE/api/v1/auth/register \
 wait

 # 检查用户数
-sqlite3 backend/.deer-flow/users.db \
+sqlite3 backend/.deer-flow/data/deerflow.db \
  "SELECT COUNT(*) FROM users WHERE email='race@example.com';"
 ```

@@ -1165,13 +1200,16 @@ curl -s -w "%{http_code}" -X DELETE "$BASE/api/threads/$TID" \
 ```bash
 cd backend
 python -m app.gateway.auth.reset_admin
-# 记录密码 P1
+cp .deer-flow/admin_initial_credentials.txt /tmp/deerflow-reset-p1.txt
+P1=$(awk -F': ' '/^password:/ {print $2}' /tmp/deerflow-reset-p1.txt)

 python -m app.gateway.auth.reset_admin
-# 记录密码 P2
+cp .deer-flow/admin_initial_credentials.txt /tmp/deerflow-reset-p2.txt
+P2=$(awk -F': ' '/^password:/ {print $2}' /tmp/deerflow-reset-p2.txt)
 ```

 **预期：**
+- [ ] `.deer-flow/admin_initial_credentials.txt` 每次都会被重写，文件权限为 `0600`
 - [ ] P1 ≠ P2（每次生成新随机密码）
 - [ ] P1 不可用，只有 P2 有效
 - [ ] `token_version` 递增了 2
@@ -1324,7 +1362,8 @@ done
 ```bash
 GW=http://localhost:8001

-for path in /health /api/v1/auth/setup-status /api/v1/auth/login/local /api/v1/auth/register; do
+for path in /health /api/v1/auth/setup-status /api/v1/auth/login/local \
+            /api/v1/auth/register /api/v1/auth/initialize /api/v1/auth/logout; do
  echo "$path: $(curl -s -w '%{http_code}' -o /dev/null $GW$path)"
 done
 # 预期: 200 或 405/422（方法不对但不是 401）
@@ -1399,9 +1438,9 @@ done
 >
 > 前置条件：
 > - `.env` 中设置 `AUTH_JWT_SECRET`（否则每次容器重启 session 全部失效）
-> - `DEER_FLOW_HOME` 挂载到宿主机目录（持久化 `users.db`）
+> - `DEER_FLOW_HOME` 挂载到宿主机目录（持久化 `deerflow.db`）

-#### TC-DOCKER-01: users.db 通过 volume 持久化
+#### TC-DOCKER-01: deerflow.db 通过 volume 持久化

 ```bash
 # 启动容器
@@ -1416,13 +1455,13 @@ curl -s -X POST $BASE/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"docker-test@example.com","password":"DockerTest1!"}' -w "\nHTTP %{http_code}"

-# 检查宿主机上的 users.db
-ls -la ${DEER_FLOW_HOME:-backend/.deer-flow}/users.db
-sqlite3 ${DEER_FLOW_HOME:-backend/.deer-flow}/users.db \
+# 检查宿主机上的 deerflow.db
+ls -la ${DEER_FLOW_HOME:-backend/.deer-flow}/data/deerflow.db
+sqlite3 ${DEER_FLOW_HOME:-backend/.deer-flow}/data/deerflow.db \
  "SELECT email FROM users WHERE email='docker-test@example.com';"
 ```

-**预期：** users.db 在宿主机 `DEER_FLOW_HOME` 目录中，查询可见刚注册的用户。
+**预期：** deerflow.db 在宿主机 `DEER_FLOW_HOME` 目录中，查询可见刚注册的用户。

 #### TC-DOCKER-02: 重启容器后 session 保持

@@ -1466,22 +1505,24 @@ done

 **已知限制：** In-process rate limiter 不跨 worker 共享。生产环境如需精确限速，需要 Redis 等外部存储。

-#### TC-DOCKER-04: IM 渠道不经过 auth
+#### TC-DOCKER-04: IM 渠道使用内部认证

 ```bash
-# IM 渠道（Feishu/Slack/Telegram）在 gateway 容器内部通过 LangGraph SDK 通信
-# 不走 nginx，不经过 AuthMiddleware
+# IM 渠道（Feishu/Slack/Telegram）在 gateway 容器内部通过 LangGraph SDK 调 Gateway
+# 请求携带 process-local internal auth header，并带匹配的 CSRF cookie/header

 # 验证方式：检查 gateway 日志中 channel manager 的请求不包含 auth 错误
 docker logs deer-flow-gateway 2>&1 | grep -E "ChannelManager|channel" | head -10
 ```

-**预期：** 无 auth 相关错误。渠道通过 `langgraph-sdk` 直连 LangGraph Server（`http://langgraph:2024`），不走 auth 层。
+**预期：** 无 auth 相关错误。渠道不依赖浏览器 cookie；服务端通过内部认证头把请求归入 `default` 用户桶。

-#### TC-DOCKER-05: admin 密码写入 0600 凭证文件（不再走日志）
+#### TC-DOCKER-05: reset_admin 密码写入 0600 凭证文件（不再走日志）

 ```bash
-# 凭证文件写在挂载到宿主机的 DEER_FLOW_HOME 下
+# 首次启动不会自动生成 admin 密码。先重置已有 admin，凭据文件写在挂载到宿主机的 DEER_FLOW_HOME 下。
+docker exec deer-flow-gateway python -m app.gateway.auth.reset_admin --email docker-test@example.com
+
 ls -la ${DEER_FLOW_HOME:-backend/.deer-flow}/admin_initial_credentials.txt
 # 预期文件权限: -rw------- (0600)

@@ -1512,14 +1553,15 @@ sleep 15
 docker ps --filter name=deer-flow-langgraph --format '{{.Names}}' | wc -l
 # 预期: 0

-# auth 流程正常
+# auth 流程正常：未登录受保护接口返回 401
 curl -s -w "%{http_code}" -o /dev/null $BASE/api/models
 # 预期: 401

-curl -s -X POST $BASE/api/v1/auth/login/local \
-  -d "username=admin@deerflow.dev&password=<日志密码>" \
+curl -s -X POST $BASE/api/v1/auth/initialize \
+  -H "Content-Type: application/json" \
+  -d '{"email":"admin@example.com","password":"AdminPass1!"}' \
  -c cookies.txt -w "\nHTTP %{http_code}"
-# 预期: 200
+# 预期: 201
 ```

 ### 7.4 补充边界用例
@@ -1587,13 +1629,15 @@ curl -s -D - -X POST $BASE/api/v1/auth/login/local \
 #### TC-EDGE-05: HTTP 无 max_age / HTTPS 有 max_age

 ```bash
+GW=http://localhost:8001
+
 # HTTP
-curl -s -D - -X POST $BASE/api/v1/auth/login/local \
+curl -s -D - -X POST $GW/api/v1/auth/login/local \
  -d "username=admin@example.com&password=正确密码" 2>/dev/null \
  | grep "access_token=" | grep -oi "max-age=[0-9]*" || echo "NO max-age (HTTP session cookie)"

-# HTTPS
-curl -s -D - -X POST $BASE/api/v1/auth/login/local \
+# HTTPS：直连 Gateway 才能用 X-Forwarded-Proto 模拟 HTTPS；nginx 会覆盖该 header
+curl -s -D - -X POST $GW/api/v1/auth/login/local \
  -H "X-Forwarded-Proto: https" \
  -d "username=admin@example.com&password=正确密码" 2>/dev/null \
  | grep "access_token=" | grep -oi "max-age=[0-9]*"
@@ -1712,10 +1756,10 @@ curl -s -X POST $BASE/api/threads \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
-  -d '{"metadata":{"owner_id":"victim-user-id"}}' | jq .metadata.owner_id
+  -d '{"metadata":{"owner_id":"victim-user-id","user_id":"victim-user-id"}}' | jq .metadata
 ```

-**预期：** 返回的 `metadata.owner_id` 应为当前登录用户的 ID，不是请求中注入的 `victim-user-id`。服务端应覆盖客户端提供的 `user_id`。
+**预期：** 返回的 `metadata` 不包含 `owner_id` 或 `user_id`。真实所有权写入 `threads_meta.user_id`，不从客户端 metadata 接收，也不通过 metadata 回显。

 #### 7.5.6 HTTP Method 探测

@@ -1796,6 +1840,6 @@ cd backend && PYTHONPATH=. uv run pytest \
 # 核心接口冒烟
 curl -s $BASE/health                              # 200
 curl -s $BASE/api/models                          # 401 (无 cookie)
-curl -s -X POST $BASE/api/v1/auth/setup-status    # 200
+curl -s $BASE/api/v1/auth/setup-status            # 200
 curl -s $BASE/api/v1/auth/me -b cookies.txt       # 200 (有 cookie)
 ```
@@ -2,13 +2,16 @@

 DeerFlow 内置了认证模块。本文档面向从无认证版本升级的用户。

+完整设计见 [AUTH_DESIGN.md](AUTH_DESIGN.md)。
+
 ## 核心概念

 认证模块采用**始终强制**策略：

- 首次启动时自动创建 admin 账号，随机密码打印到控制台日志
+- 首次启动时不会自动创建账号；首次访问 `/setup` 时由操作者创建第一个 admin 账号
 - 认证从一开始就是强制的，无竞争窗口
- 历史对话（升级前创建的 thread）自动迁移到 admin 名下
+- 已有 admin 后，服务启动时会把历史对话（升级前创建且缺少 `user_id` 的 thread）迁移到 admin 名下
+- 新数据按用户隔离：thread、workspace/uploads/outputs、memory、自定义 agent 都归属当前用户

 ## 升级步骤

@@ -25,39 +28,41 @@ cd backend && make install
 make dev
 ```

-控制台会输出：
+如果没有 admin 账号，控制台只会提示：

 ```
 ============================================================
-  Admin account created on first boot
-  Email:    admin@deerflow.dev
-  Password: aB3xK9mN_pQ7rT2w
-  Change it after login: Settings → Account
+  First boot detected — no admin account exists.
+  Visit /setup to complete admin account creation.
 ============================================================
 ```

-如果未登录就重启了服务，不用担心——只要 setup 未完成，每次启动都会重置密码并重新打印到控制台。
+首次启动不会在日志里打印随机密码，也不会写入默认 admin。这样避免启动日志泄露凭据，也避免在操作者创建账号前出现可被猜测的默认身份。

-### 3. 登录
+### 3. 创建 admin

-访问 `http://localhost:2026/login`，使用控制台输出的邮箱和密码登录。
+访问 `http://localhost:2026/setup`，填写邮箱和密码创建第一个 admin 账号。创建成功后会自动登录并进入 workspace。

-### 4. 修改密码
+如果这是从无认证版本升级，创建 admin 后重启一次服务，让启动迁移把缺少 `user_id` 的历史 thread 归属到 admin。

-登录后进入 Settings → Account → Change Password。
+### 4. 登录
+
+后续访问 `http://localhost:2026/login`，使用已创建的邮箱和密码登录。

 ### 5. 添加用户（可选）

-其他用户通过 `/login` 页面注册，自动获得 **user** 角色。每个用户只能看到自己的对话。
+其他用户通过 `/login` 页面注册，自动获得 **user** 角色。每个用户只能看到自己的对话、上传文件、输出文件、memory 和自定义 agent。

 ## 安全机制

 | 机制 | 说明 |
 |------|------|
 | JWT HttpOnly Cookie | Token 不暴露给 JavaScript，防止 XSS 窃取 |
-| CSRF Double Submit Cookie | 所有 POST/PUT/DELETE 请求需携带 `X-CSRF-Token` |
+| CSRF Double Submit Cookie | 受保护的 POST/PUT/PATCH/DELETE 请求需携带 `X-CSRF-Token`；登录/注册/初始化/登出走 auth 端点 Origin 校验 |
 | bcrypt 密码哈希 | 密码不以明文存储 |
-| 多租户隔离 | 用户只能访问自己的 thread |
+| Thread owner filter | `threads_meta.user_id` 由服务端认证上下文写入，搜索、读取、更新、删除默认按当前用户过滤 |
+| 文件系统隔离 | 线程数据写入 `{base_dir}/users/{user_id}/threads/{thread_id}/user-data/`，sandbox 内统一映射为 `/mnt/user-data/` |
+| Memory / agent 隔离 | 用户 memory 和自定义 agent 写入 `{base_dir}/users/{user_id}/...`；旧共享 agent 只作为只读兼容回退 |
 | HTTPS 自适应 | 检测 `x-forwarded-proto`，自动设置 `Secure` cookie 标志 |

 ## 常见操作
@@ -74,22 +79,26 @@ python -m app.gateway.auth.reset_admin
 python -m app.gateway.auth.reset_admin --email user@example.com
 ```

-会输出新的随机密码。
+会把新的随机密码写入 `.deer-flow/admin_initial_credentials.txt`，文件权限为 `0600`。命令行只输出文件路径，不输出明文密码。

 ### 完全重置

-删除用户数据库，重启后自动创建新 admin：
+删除统一 SQLite 数据库，重启后重新访问 `/setup` 创建新 admin：

 ```bash
-rm -f backend/.deer-flow/users.db
-# 重启服务，控制台输出新密码
+rm -f backend/.deer-flow/data/deerflow.db
+# 重启服务后访问 http://localhost:2026/setup
 ```

 ## 数据存储

 | 文件 | 内容 |
 |------|------|
-| `.deer-flow/users.db` | SQLite 用户数据库（密码哈希、角色） |
+| `.deer-flow/data/deerflow.db` | 统一 SQLite 数据库（users、threads_meta、runs、feedback 等应用数据） |
+| `.deer-flow/users/{user_id}/threads/{thread_id}/user-data/` | 用户线程的 workspace、uploads、outputs |
+| `.deer-flow/users/{user_id}/memory.json` | 用户级 memory |
+| `.deer-flow/users/{user_id}/agents/{agent_name}/` | 用户自定义 agent 配置、SOUL 和 agent memory |
+| `.deer-flow/admin_initial_credentials.txt` | `reset_admin` 生成的新凭据文件（0600，读完应删除） |
 | `.env` 中的 `AUTH_JWT_SECRET` | JWT 签名密钥（未设置时自动生成临时密钥，重启后 session 失效） |

 ### 生产环境建议
@@ -111,19 +120,21 @@ python -c "import secrets; print(secrets.token_urlsafe(32))"
 | `/api/v1/auth/me` | GET | 获取当前用户信息 |
 | `/api/v1/auth/change-password` | POST | 修改密码 |
 | `/api/v1/auth/setup-status` | GET | 检查 admin 是否存在 |
+| `/api/v1/auth/initialize` | POST | 首次初始化第一个 admin（仅无 admin 时可调用） |

 ## 兼容性

- **标准模式**（`make dev`）：完全兼容，admin 自动创建
+- **标准模式**（`make dev`）：完全兼容；无 admin 时访问 `/setup` 初始化
 - **Gateway 模式**（`make dev-pro`）：完全兼容
- **Docker 部署**：完全兼容，`.deer-flow/users.db` 需持久化卷挂载
- **IM 渠道**（Feishu/Slack/Telegram）：通过 LangGraph SDK 通信，不经过认证层
+- **Docker 部署**：完全兼容，`.deer-flow/data/deerflow.db` 需持久化卷挂载
+- **IM 渠道**（Feishu/Slack/Telegram）：通过 Gateway 内部认证通信，使用 `default` 用户桶
 - **DeerFlowClient**（嵌入式）：不经过 HTTP，不受认证影响

 ## 故障排查

 | 症状 | 原因 | 解决 |
 |------|------|------|
-| 启动后没看到密码 | admin 已存在（非首次启动） | 用 `reset_admin` 重置，或删 `users.db` |
+| 启动后没看到密码 | 当前实现不在启动日志输出密码 | 首次安装访问 `/setup`；忘记密码用 `reset_admin` |
+| `/login` 自动跳到 `/setup` | 系统还没有 admin | 在 `/setup` 创建第一个 admin |
 | 登录后 POST 返回 403 | CSRF token 缺失 | 确认前端已更新 |
 | 重启后需要重新登录 | `AUTH_JWT_SECRET` 未持久化 | 在 `.env` 中设置固定密钥 |
@@ -259,6 +259,8 @@ 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:
@@ -319,11 +321,16 @@ 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`), not in the backend directory.
+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.

 ## Configuration Priority

@@ -331,12 +338,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` in current working directory (typically `backend/` when running)
-4. `config.yaml` in parent directory (project root: `deer-flow/`)
+3. `config.yaml` under `DEER_FLOW_PROJECT_ROOT`, or under the current working directory when `DEER_FLOW_PROJECT_ROOT` is unset
+4. Legacy backend/repository-root locations for monorepo compatibility

 ## Best Practices

-1. **Place `config.yaml` in project root** - Not in `backend/` directory
+1. **Place `config.yaml` in project root** - Set `DEER_FLOW_PROJECT_ROOT` if the runtime starts elsewhere
 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
@@ -347,7 +354,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`)
- The backend searches parent directory by default, so root location is preferred
+- If the runtime starts outside the project root, set `DEER_FLOW_PROJECT_ROOT`
 - Alternatively, set `DEER_FLOW_CONFIG_PATH` environment variable to custom location

 ### "Invalid API key"
@@ -357,7 +364,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` configuration if using custom path
+- Check `skills.path` or `DEER_FLOW_SKILLS_PATH` if using a custom path

 ### "Docker sandbox fails to start"
 - Ensure Docker is running
@@ -22,6 +22,8 @@ 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
 {
@@ -48,7 +50,23 @@ 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
 ```
@@ -71,7 +89,7 @@ GET /api/threads/{thread_id}/uploads/list
 }
 ```

-### 3. 删除文件
+### 4. 删除文件
 ```
 DELETE /api/threads/{thread_id}/uploads/{filename}
 ```
@@ -1,343 +0,0 @@
-# DeerFlow 后端拆分设计文档：Harness + App
-
-> 状态：Draft
-> 作者：DeerFlow Team
-> 日期：2026-03-13
-
-## 1. 背景与动机
-
-DeerFlow 后端当前是一个单一 Python 包（`src.*`），包含了从底层 agent 编排到上层用户产品的所有代码。随着项目发展，这种结构带来了几个问题：
-
- **复用困难**：其他产品（CLI 工具、Slack bot、第三方集成）想用 agent 能力，必须依赖整个后端，包括 FastAPI、IM SDK 等不需要的依赖
- **职责模糊**：agent 编排逻辑和用户产品逻辑混在同一个 `src/` 下，边界不清晰
- **依赖膨胀**：LangGraph Server 运行时不需要 FastAPI/uvicorn/Slack SDK，但当前必须安装全部依赖
-
-本文档提出将后端拆分为两部分：**deerflow-harness**（可发布的 agent 框架包）和 **app**（不打包的用户产品代码）。
-
-## 2. 核心概念
-
-### 2.1 Harness（线束/框架层）
-
-Harness 是 agent 的构建与编排框架，回答 **"如何构建和运行 agent"** 的问题：
-
- Agent 工厂与生命周期管理
- Middleware pipeline
- 工具系统（内置工具 + MCP + 社区工具）
- 沙箱执行环境
- 子 agent 委派
- 记忆系统
- 技能加载与注入
- 模型工厂
- 配置系统
-
-**Harness 是一个可发布的 Python 包**（`deerflow-harness`），可以独立安装和使用。
-
-**Harness 的设计原则**：对上层应用完全无感知。它不知道也不关心谁在调用它——可以是 Web App、CLI、Slack Bot、或者一个单元测试。
-
-### 2.2 App（应用层）
-
-App 是面向用户的产品代码，回答 **"如何将 agent 呈现给用户"** 的问题：
-
- Gateway API（FastAPI REST 接口）
- IM Channels（飞书、Slack、Telegram 集成）
- Custom Agent 的 CRUD 管理
- 文件上传/下载的 HTTP 接口
-
-**App 不打包、不发布**，它是 DeerFlow 项目内部的应用代码，直接运行。
-
-**App 依赖 Harness，但 Harness 不依赖 App。**
-
-### 2.3 边界划分
-
-| 模块 | 归属 | 说明 |
-|------|------|------|
-| `config/` | Harness | 配置系统是基础设施 |
-| `reflection/` | Harness | 动态模块加载工具 |
-| `utils/` | Harness | 通用工具函数 |
-| `agents/` | Harness | Agent 工厂、middleware、state、memory |
-| `subagents/` | Harness | 子 agent 委派系统 |
-| `sandbox/` | Harness | 沙箱执行环境 |
-| `tools/` | Harness | 工具注册与发现 |
-| `mcp/` | Harness | MCP 协议集成 |
-| `skills/` | Harness | 技能加载、解析、定义 schema |
-| `models/` | Harness | LLM 模型工厂 |
-| `community/` | Harness | 社区工具（tavily、jina 等） |
-| `client.py` | Harness | 嵌入式 Python 客户端 |
-| `gateway/` | App | FastAPI REST API |
-| `channels/` | App | IM 平台集成 |
-
-**关于 Custom Agents**：agent 定义格式（`config.yaml` + `SOUL.md` schema）由 Harness 层的 `config/agents_config.py` 定义，但文件的存储、CRUD、发现机制由 App 层的 `gateway/routers/agents.py` 负责。
-
-## 3. 目标架构
-
-### 3.1 目录结构
-
-```
-backend/
-├── packages/
-│   └── harness/
-│       ├── pyproject.toml          # deerflow-harness 包定义
-│       └── deerflow/               # Python 包根（import 前缀: deerflow.*）
-│           ├── __init__.py
-│           ├── config/
-│           ├── reflection/
-│           ├── utils/
-│           ├── agents/
-│           │   ├── lead_agent/
-│           │   ├── middlewares/
-│           │   ├── memory/
-│           │   ├── checkpointer/
-│           │   └── thread_state.py
-│           ├── subagents/
-│           ├── sandbox/
-│           ├── tools/
-│           ├── mcp/
-│           ├── skills/
-│           ├── models/
-│           ├── community/
-│           └── client.py
-├── app/                            # 不打包（import 前缀: app.*）
-│   ├── __init__.py
-│   ├── gateway/
-│   │   ├── __init__.py
-│   │   ├── app.py
-│   │   ├── config.py
-│   │   ├── path_utils.py
-│   │   └── routers/
-│   └── channels/
-│       ├── __init__.py
-│       ├── base.py
-│       ├── manager.py
-│       ├── service.py
-│       ├── store.py
-│       ├── message_bus.py
-│       ├── feishu.py
-│       ├── slack.py
-│       └── telegram.py
-├── pyproject.toml                  # uv workspace root
-├── langgraph.json
-├── tests/
-├── docs/
-└── Makefile
-```
-
-### 3.2 Import 规则
-
-两个层使用不同的 import 前缀，职责边界一目了然：
-
-```python
-# ---------------------------------------------------------------
-# Harness 内部互相引用（deerflow.* 前缀）
-# ---------------------------------------------------------------
-from deerflow.agents import make_lead_agent
-from deerflow.models import create_chat_model
-from deerflow.config import get_app_config
-from deerflow.tools import get_available_tools
-
-# ---------------------------------------------------------------
-# App 内部互相引用（app.* 前缀）
-# ---------------------------------------------------------------
-from app.gateway.app import app
-from app.gateway.routers.uploads import upload_files
-from app.channels.service import start_channel_service
-
-# ---------------------------------------------------------------
-# App 调用 Harness（单向依赖，Harness 永远不 import app）
-# ---------------------------------------------------------------
-from deerflow.agents import make_lead_agent
-from deerflow.models import create_chat_model
-from deerflow.skills import load_skills
-from deerflow.config.extensions_config import get_extensions_config
-```
-
-**App 调用 Harness 示例 — Gateway 中启动 agent**：
-
-```python
-# app/gateway/routers/chat.py
-from deerflow.agents.lead_agent.agent import make_lead_agent
-from deerflow.models import create_chat_model
-from deerflow.config import get_app_config
-
-async def create_chat_session(thread_id: str, model_name: str):
-    config = get_app_config()
-    model = create_chat_model(name=model_name)
-    agent = make_lead_agent(config=...)
-    # ... 使用 agent 处理用户消息
-```
-
-**App 调用 Harness 示例 — Channel 中查询 skills**：
-
-```python
-# app/channels/manager.py
-from deerflow.skills import load_skills
-from deerflow.agents.memory.updater import get_memory_data
-
-def handle_status_command():
-    skills = load_skills(enabled_only=True)
-    memory = get_memory_data()
-    return f"Skills: {len(skills)}, Memory facts: {len(memory.get('facts', []))}"
-```
-
-**禁止方向**：Harness 代码中绝不能出现 `from app.` 或 `import app.`。
-
-### 3.3 为什么 App 不打包
-
-| 方面 | 打包（放 packages/ 下） | 不打包（放 backend/app/） |
-|------|------------------------|--------------------------|
-| 命名空间 | 需要 pkgutil `extend_path` 合并，或独立前缀 | 天然独立，`app.*` vs `deerflow.*` |
-| 发布需求 | 没有——App 是项目内部代码 | 不需要 pyproject.toml |
-| 复杂度 | 需要管理两个包的构建、版本、依赖声明 | 直接运行，零额外配置 |
-| 运行方式 | `pip install deerflow-app` | `PYTHONPATH=. uvicorn app.gateway.app:app` |
-
-App 的唯一消费者是 DeerFlow 项目自身，没有独立发布的需求。放在 `backend/app/` 下作为普通 Python 包，通过 `PYTHONPATH` 或 editable install 让 Python 找到即可。
-
-### 3.4 依赖关系
-
-```
-┌─────────────────────────────────────┐
-│  app/  (不打包，直接运行)             │
-│  ├── fastapi, uvicorn               │
-│  ├── slack-sdk, lark-oapi, ...      │
-│  └── import deerflow.*              │
-└──────────────┬──────────────────────┘
-               │
-               ▼
-┌─────────────────────────────────────┐
-│  deerflow-harness  (可发布的包)       │
-│  ├── langgraph, langchain           │
-│  ├── markitdown, pydantic, ...      │
-│  └── 零 app 依赖                     │
-└─────────────────────────────────────┘
-```
-
-**依赖分类**：
-
-| 分类 | 依赖包 |
-|------|--------|
-| Harness only | agent-sandbox, langchain*, langgraph*, markdownify, markitdown, pydantic, pyyaml, readabilipy, tavily-python, firecrawl-py, tiktoken, ddgs, duckdb, httpx, kubernetes, dotenv |
-| App only | fastapi, uvicorn, sse-starlette, python-multipart, lark-oapi, slack-sdk, python-telegram-bot, markdown-to-mrkdwn |
-| Shared | langgraph-sdk（channels 用 HTTP client）, pydantic, httpx |
-
-### 3.5 Workspace 配置
-
-`backend/pyproject.toml`（workspace root）：
-
-```toml
-[project]
-name = "deer-flow"
-version = "0.1.0"
-requires-python = ">=3.12"
-dependencies = ["deerflow-harness"]
-
-[dependency-groups]
-dev = ["pytest>=8.0.0", "ruff>=0.14.11"]
-# App 的额外依赖（fastapi 等）也声明在 workspace root，因为 app 不打包
-app = ["fastapi", "uvicorn", "sse-starlette", "python-multipart"]
-channels = ["lark-oapi", "slack-sdk", "python-telegram-bot"]
-
-[tool.uv.workspace]
-members = ["packages/harness"]
-
-[tool.uv.sources]
-deerflow-harness = { workspace = true }
-```
-
-## 4. 当前的跨层依赖问题
-
-在拆分之前，需要先解决 `client.py` 中两处从 harness 到 app 的反向依赖：
-
-### 4.1 `_validate_skill_frontmatter`
-
-```python
-# client.py — harness 导入了 app 层代码
-from src.gateway.routers.skills import _validate_skill_frontmatter
-```
-
-**解决方案**：将该函数提取到 `deerflow/skills/validation.py`。这是一个纯逻辑函数（解析 YAML frontmatter、校验字段），与 FastAPI 无关。
-
-### 4.2 `CONVERTIBLE_EXTENSIONS` + `convert_file_to_markdown`
-
-```python
-# client.py — harness 导入了 app 层代码
-from src.gateway.routers.uploads import CONVERTIBLE_EXTENSIONS, convert_file_to_markdown
-```
-
-**解决方案**：将它们提取到 `deerflow/utils/file_conversion.py`。仅依赖 `markitdown` + `pathlib`，是通用工具函数。
-
-## 5. 基础设施变更
-
-### 5.1 LangGraph Server
-
-LangGraph Server 只需要 harness 包。`langgraph.json` 更新：
-
-```json
-{
-  "dependencies": ["./packages/harness"],
-  "graphs": {
-    "lead_agent": "deerflow.agents:make_lead_agent"
-  },
-  "checkpointer": {
-    "path": "./packages/harness/deerflow/runtime/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`）
@@ -8,6 +8,7 @@ This directory contains detailed documentation for the DeerFlow backend.
 |----------|-------------|
 | [ARCHITECTURE.md](ARCHITECTURE.md) | System architecture overview |
 | [API.md](API.md) | Complete API reference |
+| [AUTH_DESIGN.md](AUTH_DESIGN.md) | User authentication, CSRF, and per-user isolation design |
 | [CONFIGURATION.md](CONFIGURATION.md) | Configuration options |
 | [SETUP.md](SETUP.md) | Quick setup guide |

@@ -42,6 +43,7 @@ docs/
 ├── README.md                  # This file
 ├── ARCHITECTURE.md            # System architecture
 ├── API.md                     # API reference
+├── AUTH_DESIGN.md             # User authentication and isolation design
 ├── CONFIGURATION.md           # Configuration guide
 ├── SETUP.md                   # Setup instructions
 ├── FILE_UPLOAD.md             # File upload feature
@@ -23,6 +23,9 @@ 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
   ```
@@ -35,17 +38,20 @@ 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), not `deer-flow/backend/`
+- **Location**: `config.yaml` should be in `deer-flow/` (project root)
 - **Git**: `config.yaml` is automatically ignored by git (contains secrets)
- **Priority**: If both `backend/config.yaml` and `../config.yaml` exist, backend version takes precedence
+- **Runtime root**: Set `DEER_FLOW_PROJECT_ROOT` if DeerFlow may start from outside the project root
+- **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. `DEER_FLOW_CONFIG_PATH` environment variable (if set)
-2. `backend/config.yaml` (current directory when running from backend/)
-3. `deer-flow/config.yaml` (parent directory - **recommended location**)
+1. Explicit `config_path` argument from code
+2. `DEER_FLOW_CONFIG_PATH` environment variable (if set)
+3. `config.yaml` under `DEER_FLOW_PROJECT_ROOT`, or the current working directory when `DEER_FLOW_PROJECT_ROOT` is unset
+4. Legacy backend/repository-root locations for monorepo compatibility

 **Recommended**: Place `config.yaml` in project root (`deer-flow/config.yaml`).

@@ -77,8 +83,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 correct directory
-3. Check the file exists: `ls -la ../config.yaml`
+2. Verify you're in the project root, or set `DEER_FLOW_PROJECT_ROOT`
+3. Check the file exists: `ls -la config.yaml`

 ### Permission denied

@@ -89,4 +95,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
@@ -0,0 +1,401 @@
+# Storage Package Design
+
+## Background
+
+DeerFlow currently has several persistence responsibilities spread across app, gateway, runtime, and legacy persistence modules. This makes the persistence boundary difficult to reason about and creates several migration risks:
+
+- Routers and runtime services can accidentally depend on concrete persistence implementations instead of stable contracts.
+- User/auth, run metadata, thread metadata, feedback, run events, and checkpointer setup are initialized through different paths.
+- Some persistence behavior is duplicated between memory, SQLite, and PostgreSQL-oriented code paths.
+- Incremental migration is hard because app-level code and storage-level code are coupled.
+- Adding or validating another SQL backend requires touching app/runtime code instead of a storage-owned package.
+
+The storage package is introduced to make application data persistence a package-level capability with explicit contracts, a clear boundary, and SQL backend compatibility.
+
+## Goals
+
+- Provide a standalone `packages/storage` package for durable application data.
+- Support SQLite, PostgreSQL, and MySQL through a shared persistence construction flow.
+- Keep LangGraph checkpointer initialization compatible with the same database backend.
+- Expose repository contracts as the only package-level data access boundary.
+- Let the app layer depend on app-owned adapters under `app.infra.storage`, not on storage DB implementation classes.
+- Allow the app/gateway migration to happen in small steps without forcing a large rewrite.
+
+## Non-Goals
+
+- This design does not remove legacy persistence in the first PR.
+- This design does not move routers directly onto storage package models.
+- This design does not make app routers own SQLAlchemy sessions.
+- Cron persistence is intentionally out of scope for the storage package foundation.
+- Memory backend is not part of the durable storage package. Memory compatibility, if still needed by app runtime, belongs outside `packages/storage`.
+
+## Storage Design Principles
+
+### Package-Owned Durable Storage
+
+`packages/storage` owns durable application data persistence. It defines:
+
+- configuration shape for storage-backed persistence
+- SQLAlchemy models
+- repository contracts and DTOs
+- SQL repository implementations
+- persistence factory functions
+- compatibility helpers for config-driven initialization
+
+The package should be usable without importing `app.gateway`, routers, auth providers, or runtime-specific gateway objects.
+
+### SQL Backend Compatibility
+
+The package supports three SQL backends:
+
+- SQLite for local/single-node deployments
+- PostgreSQL for production multi-node deployments
+- MySQL for deployments that standardize on MySQL
+
+Backend-specific differences are handled inside the storage package:
+
+- SQLAlchemy async engine URL construction
+- LangGraph checkpointer connection-string compatibility
+- JSON metadata filtering across SQLite/PostgreSQL/MySQL
+- SQL dialect behavior around locking, aggregation, and JSON type semantics
+
+### Unified Persistence Bundle
+
+Storage initialization returns an `AppPersistence` bundle:
+
+```python
+@dataclass(slots=True)
+class AppPersistence:
+    checkpointer: Checkpointer
+    engine: AsyncEngine
+    session_factory: async_sessionmaker[AsyncSession]
+    setup: Callable[[], Awaitable[None]]
+    aclose: Callable[[], Awaitable[None]]
+```
+
+The app runtime can initialize persistence once, call `setup()`, and then inject:
+
+- `checkpointer`
+- `session_factory`
+- repository adapters
+
+This keeps checkpointer and application data aligned to the same backend without requiring routers to understand database configuration.
+
+## Package Layout
+
+```text
+backend/packages/storage/
+  store/
+    config/
+      storage_config.py
+      app_config.py
+    persistence/
+      factory.py
+      types.py
+      base_model.py
+      json_compat.py
+      drivers/
+        sqlite.py
+        postgres.py
+        mysql.py
+    repositories/
+      contracts/
+        user.py
+        run.py
+        thread_meta.py
+        feedback.py
+        run_event.py
+      models/
+        user.py
+        run.py
+        thread_meta.py
+        feedback.py
+        run_event.py
+      db/
+        user.py
+        run.py
+        thread_meta.py
+        feedback.py
+        run_event.py
+      factory.py
+```
+
+## Persistence Construction
+
+The primary storage entrypoint is:
+
+```python
+from store.persistence import create_persistence_from_storage_config
+
+persistence = await create_persistence_from_storage_config(storage_config)
+await persistence.setup()
+```
+
+For app-level compatibility with existing database config shape:
+
+```python
+from store.persistence import create_persistence_from_database_config
+
+persistence = await create_persistence_from_database_config(config.database)
+await persistence.setup()
+```
+
+Expected app startup flow:
+
+```python
+persistence = await create_persistence_from_database_config(config.database)
+await persistence.setup()
+
+app.state.persistence = persistence
+app.state.checkpointer = persistence.checkpointer
+app.state.session_factory = persistence.session_factory
+```
+
+Expected app shutdown flow:
+
+```python
+await app.state.persistence.aclose()
+```
+
+## Repository Contract Design
+
+Repository contracts are the storage package's public data access boundary. They live under `store.repositories.contracts` and are re-exported from `store.repositories`.
+
+The key contract groups are:
+
+- `UserRepositoryProtocol`
+- `RunRepositoryProtocol`
+- `ThreadMetaRepositoryProtocol`
+- `FeedbackRepositoryProtocol`
+- `RunEventRepositoryProtocol`
+
+Each contract owns:
+
+- input DTOs, such as `UserCreate`, `RunCreate`, `ThreadMetaCreate`
+- output DTOs, such as `User`, `Run`, `ThreadMeta`
+- repository protocol methods
+- domain-specific exceptions when needed, such as `InvalidMetadataFilterError`
+
+Repository construction is session-based:
+
+```python
+from store.repositories import build_run_repository
+
+async with persistence.session_factory() as session:
+    repo = build_run_repository(session)
+    run = await repo.get_run(run_id)
+```
+
+This keeps transaction ownership explicit. The storage package does not hide commits or session lifecycle inside global singletons.
+
+## App/Infra Calling Contract
+
+The app layer should not call `store.repositories.db.*` directly. The intended app boundary is `app.infra.storage`.
+
+`app.infra.storage` is responsible for:
+
+- receiving `session_factory` from FastAPI runtime initialization
+- owning session lifecycle for app-facing repository methods
+- translating storage DTOs to app/gateway DTOs only when needed
+- preserving the existing app-facing names during migration
+- depending on storage repository protocols, not concrete DB classes
+
+Expected adapter pattern:
+
+```python
+class StorageRunRepository(RunRepositoryProtocol):
+    def __init__(self, session_factory):
+        self._session_factory = session_factory
+
+    async def get_run(self, run_id: str):
+        async with self._session_factory() as session:
+            repo = build_run_repository(session)
+            return await repo.get_run(run_id)
+```
+
+For gateway compatibility, app state can keep existing names while the implementation changes:
+
+```python
+app.state.run_store = StorageRunStore(run_repository)
+app.state.feedback_repo = StorageFeedbackStore(feedback_repository)
+app.state.thread_store = StorageThreadMetaStore(thread_meta_repository)
+app.state.run_event_store = StorageRunEventStore(run_event_repository)
+app.state.checkpointer = persistence.checkpointer
+app.state.session_factory = persistence.session_factory
+```
+
+The app-facing objects may expose legacy method names during migration, but their internal data access should go through storage contracts.
+
+## Boundary Rules
+
+### Allowed Calls
+
+Storage package callers may use:
+
+```python
+from store.persistence import create_persistence_from_database_config
+from store.persistence import create_persistence_from_storage_config
+from store.repositories import build_run_repository
+from store.repositories import build_user_repository
+from store.repositories import build_thread_meta_repository
+from store.repositories import build_feedback_repository
+from store.repositories import build_run_event_repository
+from store.repositories import RunRepositoryProtocol
+from store.repositories import UserRepositoryProtocol
+```
+
+App layer callers should use:
+
+```python
+from app.infra.storage import StorageRunRepository
+from app.infra.storage import StorageUserDataRepository
+from app.infra.storage import StorageThreadMetaRepository
+from app.infra.storage import StorageFeedbackRepository
+from app.infra.storage import StorageRunEventRepository
+```
+
+### Prohibited Calls
+
+App/gateway/router/auth code must not import:
+
+```python
+from store.repositories.db import DbRunRepository
+from store.repositories.models import Run
+from store.persistence.base_model import MappedBase
+```
+
+Routers must not:
+
+- create SQLAlchemy engines
+- create SQLAlchemy sessions directly
+- call storage DB repository classes directly
+- commit/rollback storage transactions directly unless explicitly scoped by an infra adapter
+- depend on storage SQLAlchemy model classes
+
+Storage package code must not import:
+
+```python
+import app.gateway
+import app.infra
+import deerflow.runtime
+```
+
+The dependency direction is:
+
+```text
+app/gateway -> app.infra.storage -> packages/storage contracts/factories -> packages/storage db implementations
+```
+
+The reverse direction is forbidden.
+
+## Checkpointer Compatibility
+
+The storage persistence bundle initializes the LangGraph checkpointer alongside application data persistence.
+
+Backend-specific notes:
+
+- SQLite uses `langgraph-checkpoint-sqlite`.
+- PostgreSQL uses `langgraph-checkpoint-postgres` and requires a string `postgresql://...` connection URL.
+- MySQL uses `langgraph-checkpoint-mysql` and requires a string MySQL connection URL.
+
+SQLAlchemy may use async driver URLs such as `postgresql+asyncpg://...` or `mysql+aiomysql://...`, but LangGraph checkpointer constructors expect plain string connection URLs. This conversion belongs inside the storage driver implementation.
+
+## JSON Metadata Filtering
+
+Thread metadata search supports dialect-aware JSON filtering through `store.persistence.json_compat`.
+
+The matcher supports:
+
+- `None`
+- `bool`
+- `int`
+- `float`
+- `str`
+
+It rejects:
+
+- unsafe keys
+- nested JSON path expressions
+- dict/list values
+- integers outside signed 64-bit range
+
+This prevents SQL/JSON path injection, avoids compiled-cache type drift, and preserves type semantics such as `True != 1` and explicit JSON `null` not matching a missing key.
+
+## Step-by-Step Implementation Plan
+
+### Step 1: Introduce Storage Package Foundation
+
+- Add `backend/packages/storage`.
+- Add storage config models.
+- Add `AppPersistence`.
+- Add SQLite/PostgreSQL/MySQL persistence drivers.
+- Add repository contracts, models, DB implementations, and factory helpers.
+- Add package dependency wiring.
+- Exclude cron persistence.
+
+### Step 2: Harden Storage Backend Compatibility
+
+- Validate SQLite setup and repository behavior.
+- Validate PostgreSQL and MySQL with local E2E tests.
+- Fix checkpointer connection-string compatibility.
+- Fix PostgreSQL locking and aggregation differences.
+- Add dialect-aware JSON metadata filtering.
+
+### Step 3: Add App Infra Adapters
+
+- Add `backend/app/infra/storage`.
+- Implement app-facing repositories that own session lifecycle.
+- Keep storage contracts as the only data access boundary.
+- Add legacy compatibility adapters for existing app/gateway method shapes.
+- Keep app/gateway imports out of `packages/storage`.
+
+### Step 4: Switch FastAPI Runtime Injection
+
+- Initialize storage persistence in FastAPI startup/lifespan.
+- Attach `persistence`, `checkpointer`, and `session_factory` to `app.state`.
+- Preserve existing external state names:
+  - `run_store`
+  - `feedback_repo`
+  - `thread_store`
+  - `run_event_store`
+  - `checkpointer`
+  - `session_factory`
+- Start with user/auth provider construction, then migrate run/thread/feedback/run_event.
+
+### Step 5: Router and Auth Compatibility
+
+- Ensure routers consume app-facing adapters, not storage DB classes.
+- Ensure auth providers depend on user repository contracts.
+- Keep router response shapes unchanged.
+- Add focused auth/admin/router regression tests.
+
+### Step 6: Cleanup Legacy Persistence
+
+- Compare old persistence usage after app/gateway migration.
+- Remove unused old repository implementations only after all call sites move.
+- Keep compatibility shims only where needed for a transition window.
+- Delete memory backend paths from storage-owned durable persistence.
+
+## Testing Strategy
+
+Unit tests should cover:
+
+- config parsing
+- persistence setup
+- table creation
+- repository CRUD/query behavior
+- typed JSON metadata filtering
+- dialect SQL compilation
+- cron exclusion
+
+E2E tests should cover:
+
+- SQLite persistence setup
+- PostgreSQL temporary database setup
+- MySQL temporary database setup
+- repository contract behavior across all supported SQL backends
+- JSON/Unicode round trip
+- rollback behavior
+- persistence close/cleanup
+
+E2E tests may remain local-only if CI does not provide PostgreSQL/MySQL services.
@@ -0,0 +1,401 @@
+# Storage Package 设计文档
+
+## 背景
+
+DeerFlow 当前有多类持久化职责分散在 app、gateway、runtime 和旧 persistence 模块中。这会带来几个问题：
+
+- routers 和 runtime services 容易依赖具体 persistence 实现，而不是稳定契约。
+- user/auth、run metadata、thread metadata、feedback、run events、checkpointer setup 的初始化路径不统一。
+- memory、SQLite、PostgreSQL 相关路径中存在部分重复逻辑。
+- app 层代码和 storage 层代码耦合，导致增量迁移困难。
+- 增加或验证新的 SQL backend 时，需要改动 app/runtime，而不是只改 storage package。
+
+引入 storage package 的目标，是把应用数据持久化抽象成 package 级能力，并提供明确契约、清晰边界和 SQL backend 兼容性。
+
+## 目标
+
+- 新增独立的 `packages/storage`，负责 durable application data。
+- 通过统一 persistence 构造流程支持 SQLite、PostgreSQL、MySQL。
+- 保持 LangGraph checkpointer 与同一个数据库 backend 兼容。
+- 将 repository contracts 作为 package 对外唯一数据访问边界。
+- app 层通过 `app.infra.storage` 适配 storage，而不是直接依赖 storage DB 实现类。
+- 支持 app/gateway 后续小步迁移，避免一次性大重构。
+
+## 非目标
+
+- 第一阶段不删除旧 persistence。
+- 不让 routers 直接依赖 storage package models。
+- 不让 app routers 管理 SQLAlchemy sessions。
+- cron persistence 不属于 storage package 基础迁移范围。
+- memory backend 不属于 durable storage package。若 app runtime 仍需要 memory 兼容，应放在 `packages/storage` 之外。
+
+## Storage 设计理念
+
+### Package 自己负责 Durable Storage
+
+`packages/storage` 负责应用数据的 durable persistence，包括：
+
+- storage 持久化配置
+- SQLAlchemy models
+- repository contracts 和 DTOs
+- SQL repository 实现
+- persistence factory functions
+- 面向现有 config 的兼容初始化入口
+
+该 package 不应该 import `app.gateway`、routers、auth providers 或 runtime 中的 gateway 对象。
+
+### SQL Backend 兼容
+
+该 package 支持三种 SQL backend：
+
+- SQLite：本地或单节点部署
+- PostgreSQL：生产多节点部署
+- MySQL：使用 MySQL 作为标准数据库的部署
+
+backend 差异在 storage package 内部处理：
+
+- SQLAlchemy async engine URL 构造
+- LangGraph checkpointer 连接串兼容
+- SQLite/PostgreSQL/MySQL 的 JSON metadata filter
+- 不同 SQL 方言在 locking、aggregation、JSON 类型语义上的差异
+
+### 统一 Persistence Bundle
+
+Storage 初始化返回 `AppPersistence` bundle：
+
+```python
+@dataclass(slots=True)
+class AppPersistence:
+    checkpointer: Checkpointer
+    engine: AsyncEngine
+    session_factory: async_sessionmaker[AsyncSession]
+    setup: Callable[[], Awaitable[None]]
+    aclose: Callable[[], Awaitable[None]]
+```
+
+app runtime 只需要初始化一次 persistence，调用 `setup()`，然后注入：
+
+- `checkpointer`
+- `session_factory`
+- repository adapters
+
+这样 checkpointer 和应用数据可以对齐到同一个 backend，同时 routers 不需要理解数据库配置。
+
+## Package 结构
+
+```text
+backend/packages/storage/
+  store/
+    config/
+      storage_config.py
+      app_config.py
+    persistence/
+      factory.py
+      types.py
+      base_model.py
+      json_compat.py
+      drivers/
+        sqlite.py
+        postgres.py
+        mysql.py
+    repositories/
+      contracts/
+        user.py
+        run.py
+        thread_meta.py
+        feedback.py
+        run_event.py
+      models/
+        user.py
+        run.py
+        thread_meta.py
+        feedback.py
+        run_event.py
+      db/
+        user.py
+        run.py
+        thread_meta.py
+        feedback.py
+        run_event.py
+      factory.py
+```
+
+## Persistence 构造
+
+storage 的主要入口：
+
+```python
+from store.persistence import create_persistence_from_storage_config
+
+persistence = await create_persistence_from_storage_config(storage_config)
+await persistence.setup()
+```
+
+为了兼容现有 app database config，也提供：
+
+```python
+from store.persistence import create_persistence_from_database_config
+
+persistence = await create_persistence_from_database_config(config.database)
+await persistence.setup()
+```
+
+预期 app startup 流程：
+
+```python
+persistence = await create_persistence_from_database_config(config.database)
+await persistence.setup()
+
+app.state.persistence = persistence
+app.state.checkpointer = persistence.checkpointer
+app.state.session_factory = persistence.session_factory
+```
+
+预期 app shutdown 流程：
+
+```python
+await app.state.persistence.aclose()
+```
+
+## Repository 契约设计
+
+Repository contracts 是 storage package 对外公开的数据访问边界。它们位于 `store.repositories.contracts`，并通过 `store.repositories` re-export。
+
+主要契约包括：
+
+- `UserRepositoryProtocol`
+- `RunRepositoryProtocol`
+- `ThreadMetaRepositoryProtocol`
+- `FeedbackRepositoryProtocol`
+- `RunEventRepositoryProtocol`
+
+每组契约包含：
+
+- 输入 DTO，例如 `UserCreate`、`RunCreate`、`ThreadMetaCreate`
+- 输出 DTO，例如 `User`、`Run`、`ThreadMeta`
+- repository protocol methods
+- 必要的领域异常，例如 `InvalidMetadataFilterError`
+
+Repository 通过 session 构造：
+
+```python
+from store.repositories import build_run_repository
+
+async with persistence.session_factory() as session:
+    repo = build_run_repository(session)
+    run = await repo.get_run(run_id)
+```
+
+这样可以让 transaction ownership 保持明确。storage package 不通过全局 singleton 隐式隐藏 commit 或 session 生命周期。
+
+## App/Infra 调用契约
+
+app 层不应该直接调用 `store.repositories.db.*`。预期的 app 边界是 `app.infra.storage`。
+
+`app.infra.storage` 负责：
+
+- 从 FastAPI runtime 初始化中接收 `session_factory`
+- 为 app-facing repository methods 管理 session 生命周期
+- 在必要时将 storage DTOs 转成 app/gateway DTOs
+- 迁移期间保留现有 app-facing 名称
+- 依赖 storage repository protocols，而不是具体 DB classes
+
+预期 adapter 模式：
+
+```python
+class StorageRunRepository(RunRepositoryProtocol):
+    def __init__(self, session_factory):
+        self._session_factory = session_factory
+
+    async def get_run(self, run_id: str):
+        async with self._session_factory() as session:
+            repo = build_run_repository(session)
+            return await repo.get_run(run_id)
+```
+
+为了兼容 gateway，app state 可以暂时保持现有名字，只替换内部实现：
+
+```python
+app.state.run_store = StorageRunStore(run_repository)
+app.state.feedback_repo = StorageFeedbackStore(feedback_repository)
+app.state.thread_store = StorageThreadMetaStore(thread_meta_repository)
+app.state.run_event_store = StorageRunEventStore(run_event_repository)
+app.state.checkpointer = persistence.checkpointer
+app.state.session_factory = persistence.session_factory
+```
+
+app-facing objects 可以在迁移期间保留旧方法名，但内部数据访问必须经过 storage contracts。
+
+## 边界规则
+
+### 允许调用的范围
+
+storage package 调用方可以使用：
+
+```python
+from store.persistence import create_persistence_from_database_config
+from store.persistence import create_persistence_from_storage_config
+from store.repositories import build_run_repository
+from store.repositories import build_user_repository
+from store.repositories import build_thread_meta_repository
+from store.repositories import build_feedback_repository
+from store.repositories import build_run_event_repository
+from store.repositories import RunRepositoryProtocol
+from store.repositories import UserRepositoryProtocol
+```
+
+app 层应该使用：
+
+```python
+from app.infra.storage import StorageRunRepository
+from app.infra.storage import StorageUserDataRepository
+from app.infra.storage import StorageThreadMetaRepository
+from app.infra.storage import StorageFeedbackRepository
+from app.infra.storage import StorageRunEventRepository
+```
+
+### 禁止调用的范围
+
+app/gateway/router/auth 代码不应该 import：
+
+```python
+from store.repositories.db import DbRunRepository
+from store.repositories.models import Run
+from store.persistence.base_model import MappedBase
+```
+
+routers 禁止：
+
+- 创建 SQLAlchemy engines
+- 直接创建 SQLAlchemy sessions
+- 直接调用 storage DB repository classes
+- 直接 commit/rollback storage transactions，除非这是 infra adapter 明确管理的范围
+- 依赖 storage SQLAlchemy model classes
+
+storage package 禁止 import：
+
+```python
+import app.gateway
+import app.infra
+import deerflow.runtime
+```
+
+依赖方向必须是：
+
+```text
+app/gateway -> app.infra.storage -> packages/storage contracts/factories -> packages/storage db implementations
+```
+
+禁止反向依赖。
+
+## Checkpointer 兼容
+
+storage persistence bundle 会同时初始化 LangGraph checkpointer 和应用数据持久化。
+
+backend 说明：
+
+- SQLite 使用 `langgraph-checkpoint-sqlite`。
+- PostgreSQL 使用 `langgraph-checkpoint-postgres`，需要字符串形式的 `postgresql://...` 连接串。
+- MySQL 使用 `langgraph-checkpoint-mysql`，需要字符串形式的 MySQL 连接串。
+
+SQLAlchemy 可以使用 `postgresql+asyncpg://...` 或 `mysql+aiomysql://...` 这类 async driver URL，但 LangGraph checkpointer 构造函数需要普通字符串连接串。这个转换应该封装在 storage driver implementation 内部。
+
+## JSON Metadata Filtering
+
+Thread metadata search 通过 `store.persistence.json_compat` 支持跨方言 JSON filtering。
+
+支持的 filter value 类型：
+
+- `None`
+- `bool`
+- `int`
+- `float`
+- `str`
+
+拒绝：
+
+- unsafe keys
+- nested JSON path expressions
+- dict/list values
+- 超出 signed 64-bit 范围的整数
+
+这样可以避免 SQL/JSON path injection，避免 compiled-cache 类型漂移，并保留类型语义，例如 `True != 1`，显式 JSON `null` 不等于 missing key。
+
+## 分步实现方案
+
+### 第 1 步：新增 Storage Package 基础
+
+- 新增 `backend/packages/storage`。
+- 增加 storage config models。
+- 增加 `AppPersistence`。
+- 增加 SQLite/PostgreSQL/MySQL persistence drivers。
+- 增加 repository contracts、models、DB implementations 和 factory helpers。
+- 接入 package dependency。
+- 排除 cron persistence。
+
+### 第 2 步：补齐 Storage Backend 兼容性
+
+- 验证 SQLite setup 和 repository 行为。
+- 使用本地 E2E 验证 PostgreSQL 和 MySQL。
+- 修复 checkpointer 连接串兼容。
+- 修复 PostgreSQL locking 和 aggregation 差异。
+- 增加跨方言 JSON metadata filtering。
+
+### 第 3 步：新增 App Infra Adapters
+
+- 新增 `backend/app/infra/storage`。
+- 实现 app-facing repositories，由它们管理 session 生命周期。
+- 保持 storage contracts 作为唯一数据访问边界。
+- 为现有 app/gateway method shape 增加兼容 adapters。
+- 避免 `packages/storage` import app/gateway。
+
+### 第 4 步：切换 FastAPI Runtime 注入
+
+- 在 FastAPI startup/lifespan 中初始化 storage persistence。
+- 将 `persistence`、`checkpointer`、`session_factory` 注入 `app.state`。
+- 暂时保留现有对外 state 名称：
+  - `run_store`
+  - `feedback_repo`
+  - `thread_store`
+  - `run_event_store`
+  - `checkpointer`
+  - `session_factory`
+- 先切 user/auth provider 构造，再逐步迁移 run/thread/feedback/run_event。
+
+### 第 5 步：Router 和 Auth 兼容
+
+- 确保 routers 消费 app-facing adapters，而不是 storage DB classes。
+- 确保 auth providers 依赖 user repository contracts。
+- 保持 router response shapes 不变。
+- 增加 auth/admin/router regression tests。
+
+### 第 6 步：清理旧 Persistence
+
+- app/gateway 迁移完成后，再比较旧 persistence usage。
+- 所有 call sites 迁移完成后，再删除未使用的旧 repository implementations。
+- 只在必要时保留短期 compatibility shims。
+- 从 storage-owned durable persistence 中移除 memory backend 路径。
+
+## 测试策略
+
+单测应覆盖：
+
+- config parsing
+- persistence setup
+- table creation
+- repository CRUD/query behavior
+- typed JSON metadata filtering
+- dialect SQL compilation
+- cron exclusion
+
+E2E 应覆盖：
+
+- SQLite persistence setup
+- PostgreSQL temporary database setup
+- MySQL temporary database setup
+- 所有支持 SQL backend 下的 repository contract 行为
+- JSON/Unicode round trip
+- rollback behavior
+- persistence close/cleanup
+
+如果 CI 暂时没有 PostgreSQL/MySQL services，E2E 可以先作为 local-only 验证保留。
@@ -173,7 +173,7 @@ def _assemble_from_features(
      9.   MemoryMiddleware (memory feature)
      10.  ViewImageMiddleware (vision feature)
      11.  SubagentLimitMiddleware (subagent feature)
-      12.  LoopDetectionMiddleware (always)
+      12.  LoopDetectionMiddleware (loop_detection feature)
      13.  ClarificationMiddleware (always last)

    Two-phase ordering:
@@ -254,9 +254,11 @@ def _assemble_from_features(
            from deerflow.agents.middlewares.view_image_middleware import ViewImageMiddleware

            chain.append(ViewImageMiddleware())
-        from deerflow.tools.builtins import view_image_tool

-        extra_tools.append(view_image_tool)
+        if feat.sandbox is not False:
+            from deerflow.tools.builtins import view_image_tool
+
+            extra_tools.append(view_image_tool)

    # --- [11] Subagent ---
    if feat.subagent is not False:
@@ -270,10 +272,15 @@ def _assemble_from_features(

        extra_tools.append(task_tool)

-    # --- [12] LoopDetection (always) ---
-    from deerflow.agents.middlewares.loop_detection_middleware import LoopDetectionMiddleware
+    # --- [12] LoopDetection ---
+    if feat.loop_detection is not False:
+        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())
+            chain.append(LoopDetectionMiddleware.from_config(LoopDetectionConfig()))

    # --- [13] Clarification (always last among built-ins) ---
    chain.append(ClarificationMiddleware())
@@ -31,6 +31,7 @@ class RuntimeFeatures:
    vision: bool | AgentMiddleware = False
    auto_title: bool | AgentMiddleware = False
    guardrail: Literal[False] | AgentMiddleware = False
+    loop_detection: bool | AgentMiddleware = True


 # ---------------------------------------------------------------------------
@@ -3,7 +3,6 @@ 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
@@ -19,9 +18,10 @@ 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
-from deerflow.config.deer_flow_context import DeerFlowContext
+from deerflow.config.app_config import AppConfig, get_app_config
 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,8 +35,9 @@ def _get_runtime_config(config: RunnableConfig) -> dict:
    return cfg


-def _resolve_model_name(app_config: AppConfig, requested_model_name: str | None = None) -> str:
+def _resolve_model_name(requested_model_name: str | None = None, *, app_config: AppConfig | 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.")
@@ -49,9 +50,10 @@ def _resolve_model_name(app_config: AppConfig, requested_model_name: str | None
    return default_model_name


-def _create_summarization_middleware(app_config: AppConfig) -> DeerFlowSummarizationMiddleware | None:
+def _create_summarization_middleware(*, app_config: AppConfig | None = None) -> DeerFlowSummarizationMiddleware | None:
    """Create and configure the summarization middleware from config."""
-    config = app_config.summarization
+    resolved_app_config = app_config or get_app_config()
+    config = resolved_app_config.summarization

    if not config.enabled:
        return None
@@ -72,9 +74,9 @@ def _create_summarization_middleware(app_config: AppConfig) -> DeerFlowSummariza
    # 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=app_config)
+        model = create_chat_model(name=config.model_name, thinking_enabled=False, app_config=resolved_app_config)
    else:
-        model = create_chat_model(thinking_enabled=False, app_config=app_config)
+        model = create_chat_model(thinking_enabled=False, app_config=resolved_app_config)
    model = model.with_config(tags=["middleware:summarize"])

    # Prepare kwargs
@@ -91,17 +93,13 @@ def _create_summarization_middleware(app_config: AppConfig) -> DeerFlowSummariza
        kwargs["summary_prompt"] = config.summary_prompt

    hooks: list[BeforeSummarizationHook] = []
-    if app_config.memory.enabled:
+    if resolved_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.
-    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"
+    skills_container_path = resolved_app_config.skills.container_path or "/mnt/skills"

    return DeerFlowSummarizationMiddleware(
        **kwargs,
@@ -240,17 +238,16 @@ 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.
@@ -258,10 +255,17 @@ def _build_middlewares(
    Returns:
        List of middleware instances.
    """
-    middlewares = build_lead_runtime_middlewares(app_config=app_config, lazy_init=True)
+    resolved_app_config = app_config or get_app_config()
+    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)
+    summarization_middleware = _create_summarization_middleware(app_config=resolved_app_config)
    if summarization_middleware is not None:
        middlewares.append(summarization_middleware)

@@ -273,23 +277,23 @@ def _build_middlewares(
        middlewares.append(todo_list_middleware)

    # Add TokenUsageMiddleware when token_usage tracking is enabled
-    if app_config.token_usage.enabled:
+    if resolved_app_config.token_usage.enabled:
        middlewares.append(TokenUsageMiddleware())

    # Add TitleMiddleware
-    middlewares.append(TitleMiddleware())
+    middlewares.append(TitleMiddleware(app_config=resolved_app_config))

    # Add MemoryMiddleware (after TitleMiddleware)
-    middlewares.append(MemoryMiddleware(agent_name=agent_name))
+    middlewares.append(MemoryMiddleware(agent_name=agent_name, memory_config=resolved_app_config.memory))

    # 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 = app_config.get_model_config(model_name) if model_name else None
+    model_config = resolved_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 app_config.tool_search.enabled:
+    if resolved_app_config.tool_search.enabled:
        from deerflow.agents.middlewares.deferred_tool_filter_middleware import DeferredToolFilterMiddleware

        middlewares.append(DeferredToolFilterMiddleware())
@@ -301,7 +305,9 @@ def _build_middlewares(
        middlewares.append(SubagentLimitMiddleware(max_concurrent=max_concurrent_subagents))

    # LoopDetectionMiddleware — detect and break repetitive tool call loops
-    middlewares.append(LoopDetectionMiddleware())
+    loop_detection_config = resolved_app_config.loop_detection
+    if loop_detection_config.enabled:
+        middlewares.append(LoopDetectionMiddleware.from_config(loop_detection_config))

    # Inject custom middlewares before ClarificationMiddleware
    if custom_middlewares:
@@ -312,33 +318,42 @@ def _build_middlewares(
    return middlewares


-def make_lead_agent(
-    config: RunnableConfig,
-    app_config: AppConfig | None = None,
-) -> CompiledStateGraph:
-    """Build the lead agent from runtime config.
+def _available_skill_names(agent_config, is_bootstrap: bool) -> set[str] | None:
+    if is_bootstrap:
+        return {"bootstrap"}
+    if agent_config and agent_config.skills is not None:
+        return set(agent_config.skills)
+    return None

-    Args:
-        config: LangGraph ``RunnableConfig`` carrying per-invocation options
-            (``thinking_enabled``, ``model_name``, ``is_plan_mode``, etc.).
-        app_config: Resolved application config. Required for in-process
-            entry points (DeerFlowClient, Gateway Worker). When omitted we
-            are being called via ``langgraph.json`` registration and reload
-            from disk — the LangGraph Server bootstrap path has no other
-            way to thread the value.
-    """
+
+def _load_enabled_skills_for_tool_policy(available_skills: set[str] | None, *, app_config: AppConfig) -> list[Skill]:
+    try:
+        from deerflow.agents.lead_agent.prompt import get_enabled_skills_for_config
+
+        skills = get_enabled_skills_for_config(app_config)
+    except Exception:
+        logger.exception("Failed to load skills for allowed-tools policy")
+        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
-
-    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()
+    from deerflow.tools.builtins import setup_agent, update_agent

    cfg = _get_runtime_config(config)
+    resolved_app_config = app_config

    thinking_enabled = cfg.get("thinking_enabled", True)
    reasoning_effort = cfg.get("reasoning_effort", None)
@@ -350,13 +365,14 @@ def make_lead_agent(
    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(app_config, requested_model_name or agent_model_name)
+    model_name = _resolve_model_name(requested_model_name or agent_model_name, app_config=resolved_app_config)

-    model_config = app_config.get_model_config(model_name)
+    model_config = resolved_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.")
@@ -388,29 +404,43 @@ def make_lead_agent(
            "is_plan_mode": is_plan_mode,
            "subagent_enabled": subagent_enabled,
            "tool_groups": agent_config.tool_groups if agent_config else None,
-            "available_skills": ["bootstrap"] if is_bootstrap else (agent_config.skills if agent_config and agent_config.skills is not None else None),
+            "available_skills": sorted(available_skills) if available_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=app_config),
-            tools=get_available_tools(model_name=model_name, subagent_enabled=subagent_enabled, app_config=app_config) + [setup_agent],
-            middleware=_build_middlewares(app_config, config, model_name=model_name),
-            system_prompt=apply_prompt_template(app_config, subagent_enabled=subagent_enabled, max_concurrent_subagents=max_concurrent_subagents, available_skills=set(["bootstrap"])),
+            model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, app_config=resolved_app_config),
+            tools=filter_tools_by_skill_allowed_tools(tools, skills_for_tool_policy),
+            middleware=_build_middlewares(config, model_name=model_name, app_config=resolved_app_config),
+            system_prompt=apply_prompt_template(
+                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=app_config),
-        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(app_config, config, model_name=model_name, agent_name=agent_name),
+        model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, reasoning_effort=reasoning_effort, app_config=resolved_app_config),
+        tools=filter_tools_by_skill_allowed_tools(tools + extra_tools, skills_for_tool_policy),
+        middleware=_build_middlewares(config, model_name=model_name, agent_name=agent_name, app_config=resolved_app_config),
        system_prompt=apply_prompt_template(
-            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
+            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,
+            app_config=resolved_app_config,
        ),
        state_schema=ThreadState,
-        context_schema=DeerFlowContext,
    )
@@ -1,39 +1,43 @@
+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.config.app_config import AppConfig
-from deerflow.skills import load_skills
-from deerflow.skills.types import Skill
+from deerflow.skills.storage import get_or_new_skill_storage
+from deerflow.skills.types import Skill, SkillCategory
 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(app_config: AppConfig | None) -> list[Skill]:
-    return list(load_skills(app_config, enabled_only=True))
+def _load_enabled_skills_sync() -> list[Skill]:
+    return list(get_or_new_skill_storage().load_skills(enabled_only=True))


-def _start_enabled_skills_refresh_thread(app_config: AppConfig | None) -> None:
+def _start_enabled_skills_refresh_thread() -> 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(app_config: AppConfig | None) -> None:
+def _refresh_enabled_skills_cache_worker() -> None:
    global _enabled_skills_cache, _enabled_skills_refresh_active

    while True:
@@ -41,8 +45,8 @@ def _refresh_enabled_skills_cache_worker(app_config: AppConfig | None) -> None:
            target_version = _enabled_skills_refresh_version

        try:
-            skills = _load_enabled_skills_sync(app_config)
-        except (OSError, ImportError):
+            skills = _load_enabled_skills_sync()
+        except Exception:
            logger.exception("Failed to load enabled skills for prompt injection")
            skills = []

@@ -58,7 +62,7 @@ def _refresh_enabled_skills_cache_worker(app_config: AppConfig | None) -> None:
            _enabled_skills_cache = None


-def _ensure_enabled_skills_cache(app_config: AppConfig | None) -> threading.Event:
+def _ensure_enabled_skills_cache() -> threading.Event:
    global _enabled_skills_refresh_active

    with _enabled_skills_lock:
@@ -70,84 +74,94 @@ def _ensure_enabled_skills_cache(app_config: AppConfig | None) -> threading.Even
        _enabled_skills_refresh_active = True
        _enabled_skills_refresh_event.clear()

-    _start_enabled_skills_refresh_thread(app_config)
+    _start_enabled_skills_refresh_thread()
    return _enabled_skills_refresh_event


-def _invalidate_enabled_skills_cache(app_config: AppConfig | None) -> threading.Event:
+def _invalidate_enabled_skills_cache() -> threading.Event:
    global _enabled_skills_cache, _enabled_skills_refresh_active, _enabled_skills_refresh_version

    _get_cached_skills_prompt_section.cache_clear()
    with _enabled_skills_lock:
        _enabled_skills_cache = None
+        _enabled_skills_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(app_config)
+    _start_enabled_skills_refresh_thread()
    return _enabled_skills_refresh_event


-def prime_enabled_skills_cache(app_config: AppConfig | None = None) -> None:
-    _ensure_enabled_skills_cache(app_config)
+def prime_enabled_skills_cache() -> None:
+    _ensure_enabled_skills_cache()


-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(app_config).wait(timeout=timeout_seconds):
+def warm_enabled_skills_cache(timeout_seconds: float = _ENABLED_SKILLS_REFRESH_WAIT_TIMEOUT_SECONDS) -> bool:
+    if _ensure_enabled_skills_cache().wait(timeout=timeout_seconds):
        return True

    logger.warning("Timed out waiting %.1fs for enabled skills cache warm-up", timeout_seconds)
    return False


-def _get_enabled_skills(app_config: AppConfig | None = None):
+def _get_enabled_skills():
+    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(app_config)
+    _ensure_enabled_skills_cache()
    return []


-def _skill_mutability_label(category: str) -> str:
-    return "[custom, editable]" if category == "custom" else "[built-in]"
+def get_enabled_skills_for_config(app_config: AppConfig | None = None) -> list[Skill]:
+    """Return enabled skills using the caller's config source.

+    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()

-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()
+    cache_key = id(app_config)
    with _enabled_skills_lock:
-        _enabled_skills_cache = None
-        _enabled_skills_refresh_active = False
-        _enabled_skills_refresh_version = 0
-        _enabled_skills_refresh_event.clear()
-
-
-def _refresh_enabled_skills_cache(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 = []
+        cached = _enabled_skills_by_config_cache.get(cache_key)
+        if cached is not None:
+            cached_config, cached_skills = cached
+            if cached_config is app_config:
+                return list(cached_skills)

+    skills = list(get_or_new_skill_storage(app_config=app_config).load_skills(enabled_only=True))
    with _enabled_skills_lock:
-        _enabled_skills_cache = skills
-        _enabled_skills_refresh_active = False
-        _enabled_skills_refresh_event.set()
+        _enabled_skills_by_config_cache[cache_key] = (app_config, skills)
+    return list(skills)
+
+
+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:
@@ -166,7 +180,7 @@ Skip simple one-off tasks.
 """


-def _build_available_subagents_description(available_names: list[str], bash_available: bool, app_config: AppConfig) -> str:
+def _build_available_subagents_description(available_names: list[str], bash_available: bool, *, app_config: AppConfig | None = None) -> str:
    """Dynamically build subagent type descriptions from registry.

    Mirrors Codex's pattern where agent_type_description is dynamically generated
@@ -188,7 +202,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)
+            config = get_subagent_config(name, app_config=app_config)
            if config is not None:
                desc = config.description.split("\n")[0].strip()  # First line only for brevity
                lines.append(f"- **{name}**: {desc}")
@@ -196,23 +210,22 @@ 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) -> str:
+def _build_subagent_section(max_concurrent: int, *, app_config: AppConfig | None = None) -> 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)
+    available_names = get_available_subagent_names(app_config=app_config) if app_config is not None else get_available_subagent_names()
    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)
+    available_subagents = _build_available_subagents_description(available_names, bash_available, app_config=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()'
@@ -353,8 +366,7 @@ You are {agent_name}, an open-source super agent.
 </role>

 {soul}
-{memory_context}
-
+{self_update_section}
 <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?
@@ -539,34 +551,44 @@ combined with a FastAPI gateway for REST API access [citation:FastAPI](https://f
 """


-def _get_memory_context(app_config: AppConfig, agent_name: str | None = None) -> str:
+def _get_memory_context(agent_name: str | None = None, *, app_config: AppConfig | None = None) -> str:
    """Get memory context for injection into system prompt.

-    Returns an empty string when memory is disabled or the stored memory file
-    cannot be read/parsed. A corrupt memory.json degrades the prompt to
-    no-memory; it never kills the agent.
+    Args:
+        agent_name: If provided, loads per-agent memory. If None, loads global memory.
+        app_config: Explicit application config. When provided, memory options
+            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:
-        memory_data = get_memory_data(memory_config, agent_name, user_id=get_effective_user_id())
-    except (OSError, ValueError, UnicodeDecodeError):
-        logger.exception("Failed to load memory data for prompt injection")
-        return ""
+        from deerflow.agents.memory import format_memory_for_injection, get_memory_data
+        from deerflow.runtime.user_context import get_effective_user_id

-    memory_content = format_memory_for_injection(memory_data, max_tokens=memory_config.max_injection_tokens)
-    if not memory_content.strip():
-        return ""
+        if app_config is None:
+            from deerflow.config.memory_config import get_memory_config

-    return f"""<memory>
+            config = get_memory_config()
+        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)
@@ -601,12 +623,24 @@ You have access to skills that provide optimized workflows for specific tasks. E
 </skill_system>"""


-def get_skills_prompt_section(app_config: AppConfig, available_skills: set[str] | None = None) -> str:
+def get_skills_prompt_section(available_skills: set[str] | None = None, *, app_config: AppConfig | None = None) -> str:
    """Generate the skills prompt section with available skills list."""
-    skills = _get_enabled_skills(app_config)
+    skills = get_enabled_skills_for_config(app_config)

-    container_base_path = app_config.skills.container_path
-    skill_evolution_enabled = app_config.skill_evolution.enabled
+    if app_config is None:
+        try:
+            from deerflow.config import get_app_config
+
+            config = get_app_config()
+            container_base_path = config.skills.container_path
+            skill_evolution_enabled = config.skill_evolution.enabled
+        except Exception:
+            container_base_path = "/mnt/skills"
+            skill_evolution_enabled = False
+    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 ""
@@ -630,7 +664,27 @@ def get_agent_soul(agent_name: str | None) -> str:
    return ""


-def get_deferred_tools_prompt_section(app_config: AppConfig) -> str:
+def _build_self_update_section(agent_name: str | None) -> 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
@@ -639,7 +693,17 @@ def get_deferred_tools_prompt_section(app_config: AppConfig) -> str:
    """
    from deerflow.tools.builtins.tool_search import get_deferred_registry

-    if not app_config.tool_search.enabled:
+    if app_config is None:
+        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()
@@ -650,9 +714,19 @@ def get_deferred_tools_prompt_section(app_config: AppConfig) -> str:
    return f"<available-deferred-tools>\n{names}\n</available-deferred-tools>"


-def _build_acp_section(app_config: AppConfig) -> str:
+def _build_acp_section(*, app_config: AppConfig | None = None) -> str:
    """Build the ACP agent prompt section, only if ACP agents are configured."""
-    if not app_config.acp_agents:
+    if app_config is None:
+        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 (
@@ -664,9 +738,20 @@ def _build_acp_section(app_config: AppConfig) -> str:
    )


-def _build_custom_mounts_section(app_config: AppConfig) -> str:
+def _build_custom_mounts_section(*, app_config: AppConfig | None = None) -> str:
    """Build a prompt section for explicitly configured sandbox mounts."""
-    mounts = app_config.sandbox.mounts or []
+    if app_config is None:
+        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 ""
@@ -681,19 +766,16 @@ def _build_custom_mounts_section(app_config: AppConfig) -> 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) if subagent_enabled else ""
+    subagent_section = _build_subagent_section(n, app_config=app_config) if subagent_enabled else ""

    # Add subagent reminder to critical_reminders if enabled
    subagent_reminder = (
@@ -714,27 +796,28 @@ def apply_prompt_template(
    )

    # Get skills section
-    skills_section = get_skills_prompt_section(app_config, available_skills)
+    skills_section = get_skills_prompt_section(available_skills, app_config=app_config)

    # Get deferred tools section (tool_search)
-    deferred_tools_section = get_deferred_tools_prompt_section(app_config)
+    deferred_tools_section = get_deferred_tools_prompt_section(app_config=app_config)

    # Build ACP agent section only if ACP agents are configured
-    acp_section = _build_acp_section(app_config)
-    custom_mounts_section = _build_custom_mounts_section(app_config)
+    acp_section = _build_acp_section(app_config=app_config)
+    custom_mounts_section = _build_custom_mounts_section(app_config=app_config)
    acp_and_mounts_section = "\n".join(section for section in (acp_section, custom_mounts_section) if section)

-    # Format the prompt with dynamic skills and memory
-    prompt = SYSTEM_PROMPT_TEMPLATE.format(
+    # Build and return the fully static system prompt.
+    # Memory and current date are injected per-turn via DynamicContextMiddleware
+    # 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>"
@@ -7,17 +7,11 @@ from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from typing import Any

-from deerflow.config.app_config import AppConfig
+from deerflow.config.memory_config import get_memory_config

 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."""
@@ -37,26 +31,24 @@ 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, app_config: AppConfig):
-        """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
+    def __init__(self):
+        """Initialize the memory update queue."""
        self._queue: list[ConversationContext] = []
        self._lock = threading.Lock()
        self._timer: threading.Timer | None = None
        self._processing = False

+    @staticmethod
+    def _queue_key(
+        thread_id: str,
+        user_id: str | None,
+        agent_name: str | None,
+    ) -> tuple[str, str | None, str | None]:
+        """Return the debounce identity for a memory update target."""
+        return (thread_id, user_id, agent_name)
+
    def add(
        self,
        thread_id: str,
@@ -66,8 +58,19 @@ class MemoryUpdateQueue:
        correction_detected: bool = False,
        reinforcement_detected: bool = False,
    ) -> None:
-        """Add a conversation to the update queue."""
-        config = self._app_config.memory
+        """Add a conversation to the update queue.
+
+        Args:
+            thread_id: The thread ID.
+            messages: The conversation messages.
+            agent_name: If provided, memory is stored per-agent. If None, uses global memory.
+            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

@@ -94,7 +97,7 @@ class MemoryUpdateQueue:
        reinforcement_detected: bool = False,
    ) -> None:
        """Add a conversation and start processing immediately in the background."""
-        config = self._app_config.memory
+        config = get_memory_config()
        if not config.enabled:
            return

@@ -117,12 +120,13 @@ class MemoryUpdateQueue:
        thread_id: str,
        messages: list[Any],
        agent_name: str | None,
-        user_id: str | None = None,
+        user_id: str | None,
        correction_detected: bool,
        reinforcement_detected: bool,
    ) -> None:
+        queue_key = self._queue_key(thread_id, user_id, agent_name)
        existing_context = next(
-            (context for context in self._queue if context.thread_id == thread_id),
+            (context for context in self._queue if self._queue_key(context.thread_id, context.user_id, context.agent_name) == queue_key),
            None,
        )
        merged_correction_detected = correction_detected or (existing_context.correction_detected if existing_context is not None else False)
@@ -136,12 +140,12 @@ class MemoryUpdateQueue:
            reinforcement_detected=merged_reinforcement_detected,
        )

-        self._queue = [c for c in self._queue if c.thread_id != thread_id]
+        self._queue = [context for context in self._queue if self._queue_key(context.thread_id, context.user_id, context.agent_name) != queue_key]
        self._queue.append(context)

    def _reset_timer(self) -> None:
        """Reset the debounce timer."""
-        config = self._app_config.memory
+        config = get_memory_config()
        self._schedule_timer(config.debounce_seconds)

        logger.debug("Memory update timer set for %ss", config.debounce_seconds)
@@ -181,7 +185,7 @@ class MemoryUpdateQueue:
        logger.info("Processing %d queued memory updates", len(contexts_to_process))

        try:
-            updater = MemoryUpdater(self._app_config)
+            updater = MemoryUpdater()

            for context in contexts_to_process:
                try:
@@ -253,35 +257,31 @@ class MemoryUpdateQueue:
            return self._processing


-# Queues keyed by ``id(AppConfig)`` so tests and multi-client setups with
-# distinct configs do not share a debounce queue.
-_memory_queues: dict[int, MemoryUpdateQueue] = {}
+# Global singleton instance
+_memory_queue: MemoryUpdateQueue | None = None
 _queue_lock = threading.Lock()


-def get_memory_queue(app_config: AppConfig) -> MemoryUpdateQueue:
-    """Get or create the memory update queue for the given app config."""
-    key = id(app_config)
-    with _queue_lock:
-        queue = _memory_queues.get(key)
-        if queue is None:
-            queue = MemoryUpdateQueue(app_config)
-            _memory_queues[key] = queue
-        return queue
+def get_memory_queue() -> MemoryUpdateQueue:
+    """Get the global memory update queue singleton.

-
-def reset_memory_queue(app_config: AppConfig | None = None) -> None:
-    """Reset memory queue(s).
-
-    Pass an ``app_config`` to reset only its queue, or omit to reset all
-    (useful at test teardown).
+    Returns:
+        The memory update queue instance.
    """
+    global _memory_queue
    with _queue_lock:
-        if app_config is not None:
-            queue = _memory_queues.pop(id(app_config), None)
-            if queue is not None:
-                queue.clear()
-            return
-        for queue in _memory_queues.values():
-            queue.clear()
-        _memory_queues.clear()
+        if _memory_queue is None:
+            _memory_queue = MemoryUpdateQueue()
+        return _memory_queue
+
+
+def reset_memory_queue() -> None:
+    """Reset the global memory queue.
+
+    This is useful for testing.
+    """
+    global _memory_queue
+    with _queue_lock:
+        if _memory_queue is not None:
+            _memory_queue.clear()
+        _memory_queue = None
@@ -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 MemoryConfig
+from deerflow.config.memory_config import get_memory_config
 from deerflow.config.paths import get_paths

 logger = logging.getLogger(__name__)
@@ -62,15 +62,8 @@ class MemoryStorage(abc.ABC):
 class FileMemoryStorage(MemoryStorage):
    """File-based memory storage provider."""

-    def __init__(self, memory_config: MemoryConfig):
-        """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
+    def __init__(self):
+        """Initialize the file memory storage."""
        # 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]] = {}
@@ -90,11 +83,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)
@@ -102,6 +95,7 @@ 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
@@ -122,16 +116,20 @@ 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:
@@ -148,13 +146,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
@@ -162,6 +160,7 @@ 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)
@@ -181,7 +180,6 @@ 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)
@@ -191,31 +189,23 @@ class FileMemoryStorage(MemoryStorage):
            return False


-# 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_instance: MemoryStorage | None = None
 _storage_lock = threading.Lock()


-def get_memory_storage(memory_config: MemoryConfig) -> MemoryStorage:
-    """Get the configured memory storage instance.
-
-    Caches one instance per ``(storage_class, memory_config)`` pair. In
-    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
+def get_memory_storage() -> MemoryStorage:
+    """Get the configured memory storage instance."""
+    global _storage_instance
+    if _storage_instance is not None:
+        return _storage_instance

    with _storage_lock:
-        existing = _storage_instances.get(key)
-        if existing is not None:
-            return existing
+        if _storage_instance is not None:
+            return _storage_instance
+
+        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
@@ -229,14 +219,13 @@ def get_memory_storage(memory_config: MemoryConfig) -> MemoryStorage:
            if not issubclass(storage_class, MemoryStorage):
                raise TypeError(f"Configured memory storage '{storage_class_path}' is not a subclass of MemoryStorage")

-            instance = storage_class(memory_config)
+            _storage_instance = storage_class()
        except Exception as e:
            logger.error(
                "Failed to load memory storage %s, falling back to FileMemoryStorage: %s",
                storage_class_path,
                e,
            )
-            instance = FileMemoryStorage(memory_config)
+            _storage_instance = FileMemoryStorage()

-        _storage_instances[key] = instance
-        return instance
+    return _storage_instance
@@ -5,19 +5,13 @@ 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.app_config import AppConfig
+from deerflow.config.memory_config import get_memory_config
+from deerflow.runtime.user_context import resolve_runtime_user_id


 def memory_flush_hook(event: SummarizationEvent) -> None:
-    """Flush messages about to be summarized into the memory queue.
-
-    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:
+    """Flush messages about to be summarized into the memory queue."""
+    if not get_memory_config().enabled or not event.thread_id:
        return

    filtered_messages = filter_messages_for_memory(list(event.messages_to_summarize))
@@ -28,11 +22,13 @@ 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(app_config)
+    user_id = resolve_runtime_user_id(event.runtime)
+    queue = get_memory_queue()
    queue.add_nowait(
        thread_id=event.thread_id,
        messages=filtered_messages,
        agent_name=event.agent_name,
+        user_id=user_id,
        correction_detected=correction_detected,
        reinforcement_detected=reinforcement_detected,
    )
@@ -9,7 +9,6 @@ import logging
 import math
 import re
 import uuid
-from collections.abc import Awaitable
 from typing import Any

 from deerflow.agents.memory.prompt import (
@@ -21,12 +20,17 @@ from deerflow.agents.memory.storage import (
    get_memory_storage,
    utc_now_iso_z,
 )
-from deerflow.config.app_config import AppConfig
-from deerflow.config.memory_config import MemoryConfig
+from deerflow.config.memory_config import get_memory_config
 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",
@@ -39,33 +43,45 @@ def _create_empty_memory() -> dict[str, Any]:
    return create_empty_memory()


-def _save_memory_to_file(memory_config: MemoryConfig, memory_data: dict[str, Any], agent_name: str | None = None, *, user_id: str | None = None) -> bool:
-    """Save via the configured memory storage."""
-    return get_memory_storage(memory_config).save(memory_data, agent_name, user_id=user_id)
+def _save_memory_to_file(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."""
+    return get_memory_storage().save(memory_data, agent_name, user_id=user_id)


-def get_memory_data(memory_config: MemoryConfig, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
+def get_memory_data(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(memory_config).load(agent_name, user_id=user_id)
+    return get_memory_storage().load(agent_name, user_id=user_id)


-def reload_memory_data(memory_config: MemoryConfig, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
+def reload_memory_data(agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
    """Reload memory data via storage provider."""
-    return get_memory_storage(memory_config).reload(agent_name, user_id=user_id)
+    return get_memory_storage().reload(agent_name, user_id=user_id)


-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."""
-    storage = get_memory_storage(memory_config)
+def import_memory_data(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.
+
+    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(memory_config: MemoryConfig, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
+def clear_memory_data(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(memory_config, cleared_memory, agent_name, user_id=user_id):
+    if not _save_memory_to_file(cleared_memory, agent_name, user_id=user_id):
        raise OSError("Failed to save cleared memory data")
    return cleared_memory

@@ -78,7 +94,6 @@ def _validate_confidence(confidence: float) -> float:


 def create_memory_fact(
-    memory_config: MemoryConfig,
    content: str,
    category: str = "context",
    confidence: float = 0.5,
@@ -94,7 +109,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(memory_config, agent_name, user_id=user_id)
+    memory_data = get_memory_data(agent_name, user_id=user_id)
    updated_memory = dict(memory_data)
    facts = list(memory_data.get("facts", []))
    facts.append(
@@ -109,15 +124,15 @@ def create_memory_fact(
    )
    updated_memory["facts"] = facts

-    if not _save_memory_to_file(memory_config, updated_memory, agent_name, user_id=user_id):
+    if not _save_memory_to_file(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(memory_config: MemoryConfig, fact_id: str, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
+def delete_memory_fact(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(memory_config, agent_name, user_id=user_id)
+    memory_data = get_memory_data(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):
@@ -126,14 +141,13 @@ def delete_memory_fact(memory_config: MemoryConfig, fact_id: str, agent_name: st
    updated_memory = dict(memory_data)
    updated_memory["facts"] = updated_facts

-    if not _save_memory_to_file(memory_config, updated_memory, agent_name, user_id=user_id):
+    if not _save_memory_to_file(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,
@@ -143,7 +157,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(memory_config, agent_name, user_id=user_id)
+    memory_data = get_memory_data(agent_name, user_id=user_id)
    updated_memory = dict(memory_data)
    updated_facts: list[dict[str, Any]] = []
    found = False
@@ -170,7 +184,7 @@ def update_memory_fact(

    updated_memory["facts"] = updated_facts

-    if not _save_memory_to_file(memory_config, updated_memory, agent_name, user_id=user_id):
+    if not _save_memory_to_file(updated_memory, agent_name, user_id=user_id):
        raise OSError(f"Failed to save memory data after updating fact '{fact_id}'")

    return updated_memory
@@ -213,39 +227,6 @@ def _extract_text(content: Any) -> str:
    return str(content)


-def _run_async_update_sync(coro: Awaitable[bool]) -> bool:
-    """Run an async memory update from sync code, including nested-loop contexts."""
-    handed_off = False
-
-    try:
-        try:
-            loop = asyncio.get_running_loop()
-        except RuntimeError:
-            loop = None
-
-        if loop is not None and loop.is_running():
-            future = _SYNC_MEMORY_UPDATER_EXECUTOR.submit(asyncio.run, coro)
-            handed_off = True
-            return future.result()
-
-        handed_off = True
-        return asyncio.run(coro)
-    except Exception:
-        if not handed_off:
-            close = getattr(coro, "close", None)
-            if callable(close):
-                try:
-                    close()
-                except Exception:
-                    logger.debug(
-                        "Failed to close un-awaited memory update coroutine",
-                        exc_info=True,
-                    )
-
-        logger.exception("Failed to run async memory update from sync context")
-        return False
-
-
 # Matches sentences that describe a file-upload *event* rather than general
 # file-related work.  Deliberately narrow to avoid removing legitimate facts
 # such as "User works with CSV files" or "prefers PDF export".
@@ -295,25 +276,19 @@ def _fact_content_key(content: Any) -> str | None:
 class MemoryUpdater:
    """Updates memory using LLM based on conversation context."""

-    def __init__(self, app_config: AppConfig, model_name: str | None = None):
+    def __init__(self, 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."""
-        model_name = self._model_name or self._memory_config.model_name
-        return create_chat_model(name=model_name, thinking_enabled=False, app_config=self._app_config)
+        config = get_memory_config()
+        model_name = self._model_name or config.model_name
+        return create_chat_model(name=model_name, thinking_enabled=False)

    def _build_correction_hint(
        self,
@@ -349,11 +324,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 = self._memory_config
+        config = get_memory_config()
        if not config.enabled or not messages:
            return None

-        current_memory = get_memory_data(config, agent_name, user_id=user_id)
+        current_memory = get_memory_data(agent_name, user_id=user_id)
        conversation_text = format_conversation_for_update(messages)
        if not conversation_text.strip():
            return None
@@ -389,7 +364,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(self._memory_config).save(updated_memory, agent_name, user_id=user_id)
+        return get_memory_storage().save(updated_memory, agent_name, user_id=user_id)

    async def aupdate_memory(
        self,
@@ -400,10 +375,43 @@ class MemoryUpdater:
        reinforcement_detected: bool = False,
        user_id: str | None = None,
    ) -> bool:
-        """Update memory asynchronously based on conversation messages."""
+        """Update memory asynchronously by delegating to the sync path.
+
+        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 = await asyncio.to_thread(
-                self._prepare_update_prompt,
+            prepared = self._prepare_update_prompt(
                messages=messages,
                agent_name=agent_name,
                correction_detected=correction_detected,
@@ -415,9 +423,8 @@ class MemoryUpdater:

            current_memory, prompt = prepared
            model = self._get_model()
-            response = await model.ainvoke(prompt, config={"run_name": "memory_agent"})
-            return await asyncio.to_thread(
-                self._finalize_update,
+            response = model.invoke(prompt, config={"run_name": "memory_agent"})
+            return self._finalize_update(
                current_memory=current_memory,
                response_content=response.content,
                thread_id=thread_id,
@@ -440,7 +447,16 @@ class MemoryUpdater:
        reinforcement_detected: bool = False,
        user_id: str | None = None,
    ) -> bool:
-        """Synchronously update memory via the async updater path.
+        """Synchronously update memory using the sync LLM 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.
@@ -453,78 +469,35 @@ class MemoryUpdater:
        Returns:
            True if update was successful, False otherwise.
        """
-        config = self._memory_config
-        if not config.enabled:
-            return False
-
-        if not messages:
-            return False
-
        try:
-            # Get current memory
-            current_memory = get_memory_data(config, agent_name, user_id=user_id)
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None

-            # Format conversation for prompt
-            conversation_text = format_conversation_for_update(messages)
-
-            if not conversation_text.strip():
+        if loop is not None and loop.is_running():
+            try:
+                future = _SYNC_MEMORY_UPDATER_EXECUTOR.submit(
+                    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,
+                )
+                return future.result()
+            except Exception:
+                logger.exception("Failed to offload memory update to executor")
                return False

-            # Build prompt
-            correction_hint = ""
-            if correction_detected:
-                correction_hint = (
-                    "IMPORTANT: Explicit correction signals were detected in this conversation. "
-                    "Pay special attention to what the agent got wrong, what the user corrected, "
-                    "and record the correct approach as a fact with category "
-                    '"correction" and confidence >= 0.95 when appropriate.'
-                )
-            if reinforcement_detected:
-                reinforcement_hint = (
-                    "IMPORTANT: Positive reinforcement signals were detected in this conversation. "
-                    "The user explicitly confirmed the agent's approach was correct or helpful. "
-                    "Record the confirmed approach, style, or preference as a fact with category "
-                    '"preference" or "behavior" and confidence >= 0.9 when appropriate.'
-                )
-                correction_hint = (correction_hint + "\n" + reinforcement_hint).strip() if correction_hint else reinforcement_hint
-
-            prompt = MEMORY_UPDATE_PROMPT.format(
-                current_memory=json.dumps(current_memory, indent=2),
-                conversation=conversation_text,
-                correction_hint=correction_hint,
-            )
-
-            # Call LLM
-            model = self._get_model()
-            response = model.invoke(prompt)
-            response_text = _extract_text(response.content).strip()
-
-            # Parse response
-            # Remove markdown code blocks if present
-            if response_text.startswith("```"):
-                lines = response_text.split("\n")
-                response_text = "\n".join(lines[1:-1] if lines[-1] == "```" else lines[1:])
-
-            update_data = json.loads(response_text)
-
-            # Apply updates
-            updated_memory = self._apply_updates(current_memory, update_data, thread_id)
-
-            # Strip file-upload mentions from all summaries before saving.
-            # Uploaded files are session-scoped and won't exist in future sessions,
-            # so recording upload events in long-term memory causes the agent to
-            # try (and fail) to locate those files in subsequent conversations.
-            updated_memory = _strip_upload_mentions_from_memory(updated_memory)
-
-            # Save
-            return get_memory_storage(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
+        return 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 _apply_updates(
        self,
@@ -542,7 +515,7 @@ class MemoryUpdater:
        Returns:
            Updated memory data.
        """
-        config = self._memory_config
+        config = get_memory_config()
        now = utc_now_iso_z()

        # Update user sections
@@ -36,42 +36,73 @@ class DanglingToolCallMiddleware(AgentMiddleware[AgentState]):

    @staticmethod
    def _message_tool_calls(msg) -> list[dict]:
-        """Return normalized tool calls from structured fields or raw provider payloads."""
+        """Return normalized tool calls from structured fields or raw provider payloads.
+
+        LangChain stores malformed provider function calls in ``invalid_tool_calls``.
+        They do not execute, but provider adapters may still serialize enough of
+        the call id/name back into the next request that strict OpenAI-compatible
+        validators expect a matching ToolMessage. Treat them as dangling calls so
+        the next model request stays well-formed and the model sees a recoverable
+        tool error instead of another provider 400.
+        """
+        normalized: list[dict] = []
+
        tool_calls = getattr(msg, "tool_calls", None) or []
-        if tool_calls:
-            return list(tool_calls)
+        normalized.extend(list(tool_calls))

        raw_tool_calls = (getattr(msg, "additional_kwargs", None) or {}).get("tool_calls") or []
-        normalized: list[dict] = []
-        for raw_tc in raw_tool_calls:
-            if not isinstance(raw_tc, dict):
+        if not tool_calls:
+            for raw_tc in raw_tool_calls:
+                if not isinstance(raw_tc, dict):
+                    continue
+
+                function = raw_tc.get("function")
+                name = raw_tc.get("name")
+                if not name and isinstance(function, dict):
+                    name = function.get("name")
+
+                args = raw_tc.get("args", {})
+                if not args and isinstance(function, dict):
+                    raw_args = function.get("arguments")
+                    if isinstance(raw_args, str):
+                        try:
+                            parsed_args = json.loads(raw_args)
+                        except (TypeError, ValueError, json.JSONDecodeError):
+                            parsed_args = {}
+                        args = parsed_args if isinstance(parsed_args, dict) else {}
+
+                normalized.append(
+                    {
+                        "id": raw_tc.get("id"),
+                        "name": name or "unknown",
+                        "args": args if isinstance(args, dict) else {},
+                    }
+                )
+
+        for invalid_tc in getattr(msg, "invalid_tool_calls", None) or []:
+            if not isinstance(invalid_tc, dict):
                continue
-
-            function = raw_tc.get("function")
-            name = raw_tc.get("name")
-            if not name and isinstance(function, dict):
-                name = function.get("name")
-
-            args = raw_tc.get("args", {})
-            if not args and isinstance(function, dict):
-                raw_args = function.get("arguments")
-                if isinstance(raw_args, str):
-                    try:
-                        parsed_args = json.loads(raw_args)
-                    except (TypeError, ValueError, json.JSONDecodeError):
-                        parsed_args = {}
-                    args = parsed_args if isinstance(parsed_args, dict) else {}
-
            normalized.append(
                {
-                    "id": raw_tc.get("id"),
-                    "name": name or "unknown",
-                    "args": args if isinstance(args, dict) else {},
+                    "id": invalid_tc.get("id"),
+                    "name": invalid_tc.get("name") or "unknown",
+                    "args": {},
+                    "invalid": True,
+                    "error": invalid_tc.get("error"),
                }
            )

        return normalized

+    @staticmethod
+    def _synthetic_tool_message_content(tool_call: dict) -> str:
+        if tool_call.get("invalid"):
+            error = tool_call.get("error")
+            if isinstance(error, str) and error:
+                return f"[Tool call could not be executed because its arguments were invalid: {error}]"
+            return "[Tool call could not be executed because its arguments were invalid.]"
+        return "[Tool call was interrupted and did not return a result.]"
+
    def _build_patched_messages(self, messages: list) -> list | None:
        """Return a new message list with patches inserted at the correct positions.

@@ -114,7 +145,7 @@ class DanglingToolCallMiddleware(AgentMiddleware[AgentState]):
                if tc_id and tc_id not in existing_tool_msg_ids and tc_id not in patched_ids:
                    patched.append(
                        ToolMessage(
-                            content="[Tool call was interrupted and did not return a result.]",
+                            content=self._synthetic_tool_message_content(tc),
                            tool_call_id=tc_id,
                            name=tc.get("name", "unknown"),
                            status="error",
@@ -0,0 +1,204 @@
+"""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)
@@ -70,20 +70,11 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
    retry_base_delay_ms: int = 1000
    retry_cap_delay_ms: int = 8000

-    circuit_failure_threshold: int = 5
-    circuit_recovery_timeout_sec: int = 60
-
-    def __init__(self, **kwargs: Any) -> None:
+    def __init__(self, *, app_config: AppConfig, **kwargs: Any) -> None:
        super().__init__(**kwargs)

-        # Load Circuit Breaker configs from app config if available, fall back to defaults
-        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
+        self.circuit_failure_threshold = app_config.circuit_breaker.failure_threshold
+        self.circuit_recovery_timeout_sec = app_config.circuit_breaker.recovery_timeout_sec

        # Circuit Breaker state
        self._circuit_lock = threading.Lock()
@@ -12,20 +12,22 @@ 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 override
+from typing import TYPE_CHECKING, override

 from langchain.agents import AgentState
 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
+if TYPE_CHECKING:
+    from deerflow.config.loop_detection_config import LoopDetectionConfig

 logger = logging.getLogger(__name__)

@@ -142,6 +144,9 @@ _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.
@@ -157,6 +162,14 @@ 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__(
@@ -167,6 +180,7 @@ 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
@@ -175,17 +189,32 @@ 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)

-    def _get_thread_id(self, runtime: Runtime[DeerFlowContext]) -> str:
+    @classmethod
+    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."""
-        return runtime.context.thread_id or "default"
+        thread_id = runtime.context.get("thread_id") if runtime.context else None
+        if thread_id:
+            return thread_id
+        return "default"

    def _evict_if_needed(self) -> None:
        """Evict least recently used threads if over the limit.
@@ -279,7 +308,12 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
                freq[name] += 1
                tc_count = freq[name]

-                if tc_count >= self.tool_freq_hard_limit:
+                if name in self._tool_freq_overrides:
+                    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={
@@ -290,7 +324,7 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
                    )
                    return _TOOL_FREQ_HARD_STOP_MSG.format(tool_name=name, count=tc_count), True

-                if tc_count >= self.tool_freq_warn:
+                if tc_count >= eff_warn:
                    warned = self._tool_freq_warned[thread_id]
                    if name not in warned:
                        warned.add(name)
@@ -355,22 +389,39 @@ class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
            return {"messages": [stripped_msg]}

        if warning:
-            # Inject as HumanMessage instead of SystemMessage to avoid
-            # Anthropic's "multiple non-consecutive system messages" error.
-            # Anthropic models require system messages only at the start of
-            # the conversation; injecting one mid-conversation crashes
-            # langchain_anthropic's _format_messages(). HumanMessage works
-            # with all providers. See #1299.
-            return {"messages": [HumanMessage(content=warning, name="loop_warning")]}
+            # WORKAROUND for v2.0-m1 — see #2724.
+            #
+            # Append the warning to the AIMessage content instead of
+            # injecting a separate HumanMessage. Inserting any non-tool
+            # message between an AIMessage(tool_calls=...) and its
+            # ToolMessage responses breaks OpenAI/Moonshot strict pairing
+            # validation ("tool_call_ids did not have response messages")
+            # 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[DeerFlowContext]) -> dict | None:
+    def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
        return self._apply(state, runtime)

    @override
-    async def aafter_model(self, state: AgentState, runtime: Runtime[DeerFlowContext]) -> dict | None:
+    async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict | None:
        return self._apply(state, runtime)

    def reset(self, thread_id: str | None = None) -> None:
@@ -1,17 +1,21 @@
 """Middleware for memory mechanism."""

 import logging
-from typing import override
+from typing import TYPE_CHECKING, 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.deer_flow_context import DeerFlowContext
+from deerflow.config.memory_config import get_memory_config
 from deerflow.runtime.user_context import get_effective_user_id

+if TYPE_CHECKING:
+    from deerflow.config.memory_config import MemoryConfig
+
 logger = logging.getLogger(__name__)


@@ -33,17 +37,20 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):

    state_schema = MemoryMiddlewareState

-    def __init__(self, agent_name: str | None = None):
+    def __init__(self, agent_name: str | None = None, *, memory_config: "MemoryConfig | 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[DeerFlowContext]) -> dict | None:
+    def after_agent(self, state: MemoryMiddlewareState, runtime: Runtime) -> dict | None:
        """Queue conversation for memory update after agent completes.

        Args:
@@ -53,11 +60,15 @@ class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
        Returns:
            None (no state changes needed from this middleware).
        """
-        memory_config = runtime.context.app_config.memory
-        if not memory_config.enabled:
+        config = self._memory_config or get_memory_config()
+        if not config.enabled:
            return None

-        thread_id = runtime.context.thread_id
+        # Get thread ID from runtime context first, then fall back to LangGraph's configurable metadata
+        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
@@ -86,7 +97,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(runtime.context.app_config)
+        queue = get_memory_queue()
        queue.add(
            thread_id=thread_id,
            messages=filtered_messages,
@@ -7,6 +7,7 @@ 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__)
@@ -63,7 +64,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 = last_msg.model_copy(update={"tool_calls": truncated_tool_calls})
+        updated_msg = clone_ai_message_with_tool_calls(last_msg, truncated_tool_calls)
        return {"messages": [updated_msg]}

    @override
@@ -14,6 +14,9 @@ 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__)


@@ -78,10 +81,7 @@ def _clone_ai_message(
    content: Any | None = None,
 ) -> AIMessage:
    """Clone an AIMessage while replacing its tool_calls list and optional content."""
-    update: dict[str, Any] = {"tool_calls": tool_calls}
-    if content is not None:
-        update["content"] = content
-    return message.model_copy(update=update)
+    return clone_ai_message_with_tool_calls(message, tool_calls, content=content)


@dataclass
@@ -136,6 +136,7 @@ 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)
@@ -161,6 +162,7 @@ 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)
@@ -180,6 +182,24 @@ class DeerFlowSummarizationMiddleware(SummarizationMiddleware):
        """
        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],
@@ -4,10 +4,11 @@ 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

@@ -78,10 +79,14 @@ class ThreadDataMiddleware(AgentMiddleware[ThreadDataMiddlewareState]):
        return self._get_thread_paths(thread_id, user_id=user_id)

    @override
-    def before_agent(self, state: ThreadDataMiddlewareState, runtime: Runtime[DeerFlowContext]) -> dict | None:
-        thread_id = runtime.context.thread_id
+    def before_agent(self, state: ThreadDataMiddlewareState, runtime: Runtime) -> dict | None:
+        context = runtime.context or {}
+        thread_id = context.get("thread_id")
+        if thread_id is None:
+            config = get_config()
+            thread_id = config.get("configurable", {}).get("thread_id")

-        if not thread_id:
+        if thread_id is None:
            raise ValueError("Thread ID is required in runtime context or config.configurable")

        user_id = get_effective_user_id()
@@ -2,18 +2,21 @@

 import logging
 import re
-from typing import Any, NotRequired, override
+from typing import TYPE_CHECKING, Any, NotRequired, override

 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
 from langgraph.config import get_config
 from langgraph.runtime import Runtime

-from deerflow.config.app_config import AppConfig
-from deerflow.config.deer_flow_context import DeerFlowContext
-from deerflow.config.title_config import TitleConfig
+from deerflow.agents.middlewares.dynamic_context_middleware import is_dynamic_context_reminder
+from deerflow.config.title_config import get_title_config
 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__)


@@ -28,6 +31,18 @@ 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
@@ -47,9 +62,14 @@ class TitleMiddleware(AgentMiddleware[TitleMiddlewareState]):

        return ""

-    def _should_generate_title(self, state: TitleMiddlewareState, title_config: TitleConfig) -> bool:
+    @staticmethod
+    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."""
-        if not title_config.enabled:
+        config = self._get_title_config()
+        if not config.enabled:
            return False

        # Check if thread already has a title in state
@@ -62,27 +82,28 @@ class TitleMiddleware(AgentMiddleware[TitleMiddlewareState]):
            return False

        # Count user and assistant messages
-        user_messages = [m for m in messages if m.type == "human"]
+        user_messages = [m for m in messages if self._is_user_message_for_title(m)]
        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, title_config: TitleConfig) -> tuple[str, str]:
+    def _build_title_prompt(self, state: TitleMiddlewareState) -> tuple[str, str]:
        """Extract user/assistant messages and build the title prompt.

        Returns (prompt_string, user_msg) so callers can use user_msg as fallback.
        """
+        config = self._get_title_config()
        messages = state.get("messages", [])

-        user_msg_content = next((m.content for m in messages if m.type == "human"), "")
+        user_msg_content = next((m.content for m in messages if self._is_user_message_for_title(m)), "")
        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 = title_config.prompt_template.format(
-            max_words=title_config.max_words,
+        prompt = config.prompt_template.format(
+            max_words=config.max_words,
            user_msg=user_msg[:500],
            assistant_msg=assistant_msg[:500],
        )
@@ -92,15 +113,17 @@ 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, title_config: TitleConfig) -> str:
+    def _parse_title(self, content: object) -> 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[: title_config.max_chars] if len(title) > title_config.max_chars else title
+        return title[: config.max_chars] if len(title) > config.max_chars else title

-    def _fallback_title(self, user_msg: str, title_config: TitleConfig) -> str:
-        fallback_chars = min(title_config.max_chars, 50)
+    def _fallback_title(self, user_msg: str) -> str:
+        config = self._get_title_config()
+        fallback_chars = min(config.max_chars, 50)
        if len(user_msg) > fallback_chars:
            return user_msg[:fallback_chars].rstrip() + "..."
        return user_msg if user_msg else "New Conversation"
@@ -116,42 +139,46 @@ 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, title_config: TitleConfig) -> dict | None:
+    def _generate_title_result(self, state: TitleMiddlewareState) -> dict | None:
        """Generate a local fallback title without blocking on an LLM call."""
-        if not self._should_generate_title(state, title_config):
+        if not self._should_generate_title(state):
            return None

-        _, user_msg = self._build_title_prompt(state, title_config)
-        return {"title": self._fallback_title(user_msg, title_config)}
+        _, user_msg = self._build_title_prompt(state)
+        return {"title": self._fallback_title(user_msg)}

-    async def _agenerate_title_result(self, state: TitleMiddlewareState, app_config: AppConfig) -> dict | None:
+    async def _agenerate_title_result(self, state: TitleMiddlewareState) -> dict | None:
        """Generate a title asynchronously and fall back locally on failure."""
-        title_config = app_config.title
-        if not self._should_generate_title(state, title_config):
+        if not self._should_generate_title(state):
            return None

-        prompt, user_msg = self._build_title_prompt(state, title_config)
+        config = self._get_title_config()
+        prompt, user_msg = self._build_title_prompt(state)

        try:
-            if title_config.model_name:
-                model = create_chat_model(name=title_config.model_name, thinking_enabled=False, app_config=app_config)
+            model_kwargs = {"thinking_enabled": False}
+            if self._app_config is not None:
+                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(thinking_enabled=False, app_config=app_config)
+                model = create_chat_model(**model_kwargs)
            response = await model.ainvoke(prompt, config=self._get_runnable_config())
-            title = self._parse_title(response.content, title_config)
+            title = self._parse_title(response.content)
            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, title_config)}
+        return {"title": self._fallback_title(user_msg)}

    @override
-    def after_model(self, state: TitleMiddlewareState, runtime: Runtime[DeerFlowContext]) -> dict | None:
-        return self._generate_title_result(state, runtime.context.app_config.title)
+    def after_model(self, state: TitleMiddlewareState, runtime: Runtime) -> dict | None:
+        return self._generate_title_result(state)

    @override
-    async def aafter_model(self, state: TitleMiddlewareState, runtime: Runtime[DeerFlowContext]) -> dict | None:
-        return await self._agenerate_title_result(state, runtime.context.app_config)
+    async def aafter_model(self, state: TitleMiddlewareState, runtime: Runtime) -> dict | None:
+        return await self._agenerate_title_result(state)
@@ -1,37 +1,358 @@
-"""Middleware for logging LLM token usage."""
+"""Middleware for logging token usage and annotating step attribution."""
+
+from __future__ import annotations

 import logging
-from typing import override
+from collections import defaultdict
+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, ToolMessage
 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 _has_tool_call(message: AIMessage, tool_call_id: str) -> bool:
+    """Return True if the AIMessage contains a tool_call with the given id."""
+    for tc in message.tool_calls or []:
+        if isinstance(tc, dict):
+            if tc.get("id") == tool_call_id:
+                return True
+        elif hasattr(tc, "id") and tc.id == tool_call_id:
+            return True
+    return False
+
+
+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 response usage_metadata."""
+    """Logs token usage from model responses and annotates the AI step."""

-    @override
-    def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
-        return self._log_usage(state)
-
-    @override
-    async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict | None:
-        return self._log_usage(state)
-
-    def _log_usage(self, state: AgentState) -> None:
+    def _apply(self, state: AgentState) -> dict | None:
        messages = state.get("messages", [])
        if not messages:
            return None
+
+        # Annotate subagent token usage onto the AIMessage that dispatched it.
+        # When a task tool completes, its usage is cached by tool_call_id.  Detect
+        # the ToolMessage → search backward for the corresponding AIMessage → merge.
+        # Walk backward through consecutive ToolMessages before the new AIMessage
+        # so that multiple concurrent task tool calls all get their subagent tokens
+        # written back to the same dispatch message (merging into one update).
+        state_updates: dict[int, AIMessage] = {}
+        if len(messages) >= 2:
+            from deerflow.tools.builtins.task_tool import pop_cached_subagent_usage
+
+            idx = len(messages) - 2
+            while idx >= 0:
+                tool_msg = messages[idx]
+                if not isinstance(tool_msg, ToolMessage) or not tool_msg.tool_call_id:
+                    break
+
+                subagent_usage = pop_cached_subagent_usage(tool_msg.tool_call_id)
+                if subagent_usage:
+                    # Search backward from the ToolMessage to find the AIMessage
+                    # that dispatched it.  A single model response can dispatch
+                    # multiple task tool calls, so we can't assume a fixed offset.
+                    dispatch_idx = idx - 1
+                    while dispatch_idx >= 0:
+                        candidate = messages[dispatch_idx]
+                        if isinstance(candidate, AIMessage) and _has_tool_call(candidate, tool_msg.tool_call_id):
+                            # Accumulate into an existing update for the same
+                            # AIMessage (multiple task calls in one response),
+                            # or merge fresh from the original message.
+                            existing_update = state_updates.get(dispatch_idx)
+                            prev = existing_update.usage_metadata if existing_update else (getattr(candidate, "usage_metadata", None) or {})
+                            merged = {
+                                **prev,
+                                "input_tokens": prev.get("input_tokens", 0) + subagent_usage["input_tokens"],
+                                "output_tokens": prev.get("output_tokens", 0) + subagent_usage["output_tokens"],
+                                "total_tokens": prev.get("total_tokens", 0) + subagent_usage["total_tokens"],
+                            }
+                            state_updates[dispatch_idx] = candidate.model_copy(update={"usage_metadata": merged})
+                            break
+                        dispatch_idx -= 1
+                idx -= 1
+
        last = messages[-1]
+        if not isinstance(last, AIMessage):
+            if state_updates:
+                return {"messages": [state_updates[idx] for idx in sorted(state_updates)]}
+            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",
+                "LLM token usage: input=%s output=%s total=%s%s",
                usage.get("input_tokens", "?"),
                usage.get("output_tokens", "?"),
                usage.get("total_tokens", "?"),
+                detail_suffix,
            )
-        return None
+
+        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 {"messages": [state_updates[idx] for idx in sorted(state_updates)]} if state_updates else None
+
+        additional_kwargs[TOKEN_USAGE_ATTRIBUTION_KEY] = attribution
+        updated_msg = last.model_copy(update={"additional_kwargs": additional_kwargs})
+        state_updates[len(messages) - 1] = updated_msg
+        return {"messages": [state_updates[idx] for idx in sorted(state_updates)]}
+
+    @override
+    def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
+        return self._apply(state)
+
+    @override
+    async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict | None:
+        return self._apply(state)
@@ -0,0 +1,50 @@
+"""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)
@@ -1,10 +1,8 @@
 """Tool error handling middleware and shared runtime middleware builders."""

-from __future__ import annotations
-
 import logging
 from collections.abc import Awaitable, Callable
-from typing import TYPE_CHECKING, override
+from typing import override

 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
@@ -13,8 +11,7 @@ from langgraph.errors import GraphBubbleUp
 from langgraph.prebuilt.tool_node import ToolCallRequest
 from langgraph.types import Command

-if TYPE_CHECKING:
-    from deerflow.config.app_config import AppConfig
+from deerflow.config.app_config import AppConfig

 logger = logging.getLogger(__name__)

@@ -72,7 +69,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,
@@ -97,7 +94,7 @@ def _build_runtime_middlewares(

        middlewares.append(DanglingToolCallMiddleware())

-    middlewares.append(LLMErrorHandlingMiddleware())
+    middlewares.append(LLMErrorHandlingMiddleware(app_config=app_config))

    # Guardrail middleware (if configured)
    guardrails_config = app_config.guardrails
@@ -129,7 +126,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,
@@ -139,10 +136,32 @@ def build_lead_runtime_middlewares(*, app_config: "AppConfig", lazy_init: bool =
    )


-def build_subagent_runtime_middlewares(*, lazy_init: bool = True) -> list[AgentMiddleware]:
+def build_subagent_runtime_middlewares(
+    *,
+    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."""
-    return _build_runtime_middlewares(
+    if app_config is None:
+        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
@@ -9,7 +9,6 @@ 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
@@ -186,7 +185,7 @@ class UploadsMiddleware(AgentMiddleware[UploadsMiddlewareState]):
        return files if files else None

    @override
-    def before_agent(self, state: UploadsMiddlewareState, runtime: Runtime[DeerFlowContext]) -> dict | None:
+    def before_agent(self, state: UploadsMiddlewareState, runtime: Runtime) -> dict | None:
        """Inject uploaded files information before agent execution.

        New files come from the current message's additional_kwargs.files.
@@ -215,7 +214,14 @@ class UploadsMiddleware(AgentMiddleware[UploadsMiddlewareState]):
            return None

        # Resolve uploads directory for existence checks
-        thread_id = runtime.context.thread_id
+        thread_id = (runtime.context or {}).get("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
@@ -36,13 +36,12 @@ 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 AppConfig
-from deerflow.config.deer_flow_context import DeerFlowContext
-from deerflow.config.extensions_config import ExtensionsConfig
+from deerflow.config.app_config import get_app_config, reload_app_config
+from deerflow.config.extensions_config import ExtensionsConfig, SkillStateConfig, get_extensions_config, reload_extensions_config
 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.installer import install_skill_from_archive
+from deerflow.skills.storage import get_or_new_skill_storage
 from deerflow.uploads.manager import (
    claim_unique_filename,
    delete_file_safe,
@@ -117,7 +116,6 @@ 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,
@@ -132,14 +130,9 @@ 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.
@@ -148,18 +141,9 @@ 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.
        """
-        # Constructor-captured config: the client owns its AppConfig for its lifetime.
-        # Multiple clients with different configs do not contend.
-        #
-        # 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 config_path is not None:
+            reload_app_config(config_path)
+        self._app_config = get_app_config()

        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}")
@@ -187,15 +171,6 @@ 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
    # ------------------------------------------------------------------
@@ -253,11 +228,10 @@ 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, app_config=self._app_config),
+            "model": create_chat_model(name=model_name, thinking_enabled=thinking_enabled),
            "tools": self._get_tools(model_name=model_name, subagent_enabled=subagent_enabled),
-            "middleware": _build_middlewares(self._app_config, config, model_name=model_name, agent_name=self._agent_name, custom_middlewares=self._middlewares),
+            "middleware": _build_middlewares(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,
@@ -269,7 +243,7 @@ class DeerFlowClient:
        if checkpointer is None:
            from deerflow.runtime.checkpointer import get_checkpointer

-            checkpointer = get_checkpointer(self._app_config)
+            checkpointer = get_checkpointer()
        if checkpointer is not None:
            kwargs["checkpointer"] = checkpointer

@@ -277,11 +251,12 @@ 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)

-    def _get_tools(self, *, model_name: str | None, subagent_enabled: bool):
+    @staticmethod
+    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, app_config=self._app_config)
+        return get_available_tools(model_name=model_name, subagent_enabled=subagent_enabled)

    @staticmethod
    def _serialize_tool_calls(tool_calls) -> list[dict]:
@@ -289,25 +264,35 @@ class DeerFlowClient:
        return [{"name": tc["name"], "args": tc["args"], "id": tc.get("id")} for tc in tool_calls]

    @staticmethod
-    def _ai_text_event(msg_id: str | None, text: str, usage: dict | None) -> "StreamEvent":
-        """Build a ``messages-tuple`` AI text event, attaching usage when present."""
+    def _serialize_additional_kwargs(msg) -> dict[str, Any] | None:
+        """Copy message additional_kwargs 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) -> "StreamEvent":
+    def _ai_tool_calls_event(msg_id: str | None, tool_calls, additional_kwargs: dict[str, Any] | None = None) -> "StreamEvent":
        """Build a ``messages-tuple`` AI tool-calls event."""
-        return StreamEvent(
-            type="messages-tuple",
-            data={
-                "type": "ai",
-                "content": "",
-                "id": msg_id,
-                "tool_calls": DeerFlowClient._serialize_tool_calls(tool_calls),
-            },
-        )
+        data: dict[str, Any] = {
+            "type": "ai",
+            "content": "",
+            "id": msg_id,
+            "tool_calls": DeerFlowClient._serialize_tool_calls(tool_calls),
+        }
+        if additional_kwargs:
+            data["additional_kwargs"] = additional_kwargs
+        return StreamEvent(type="messages-tuple", data=data)

    @staticmethod
    def _tool_message_event(msg: ToolMessage) -> "StreamEvent":
@@ -332,19 +317,30 @@ 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):
-            return {
+            d = {
                "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):
-            return {"type": "human", "content": msg.content, "id": getattr(msg, "id", None)}
+            d = {"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):
-            return {"type": "system", "content": msg.content, "id": getattr(msg, "id", None)}
+            d = {"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
@@ -402,7 +398,7 @@ class DeerFlowClient:
        if checkpointer is None:
            from deerflow.runtime.checkpointer.provider import get_checkpointer

-            checkpointer = get_checkpointer(self._app_config)
+            checkpointer = get_checkpointer()

        thread_info_map = {}

@@ -457,7 +453,7 @@ class DeerFlowClient:
        if checkpointer is None:
            from deerflow.runtime.checkpointer.provider import get_checkpointer

-            checkpointer = get_checkpointer(self._app_config)
+            checkpointer = get_checkpointer()

        config = {"configurable": {"thread_id": thread_id}}
        checkpoints = []
@@ -567,6 +563,7 @@ 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}}
        """
@@ -577,7 +574,9 @@ class DeerFlowClient:
        self._ensure_agent(config)

        state: dict[str, Any] = {"messages": [HumanMessage(content=message)]}
-        context = DeerFlowContext(app_config=self._app_config, thread_id=thread_id, agent_name=self._agent_name)
+        context = {"thread_id": thread_id}
+        if self._agent_name:
+            context["agent_name"] = self._agent_name

        seen_ids: set[str] = set()
        # Cross-mode handoff: ids already streamed via LangGraph ``messages``
@@ -587,6 +586,7 @@ 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,6 +616,20 @@ 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,
@@ -643,17 +657,31 @@ 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)
-                        yield self._ai_text_event(msg_id, text, counted_usage)
+                        additional_kwargs_delta = _unsent_additional_kwargs(msg_id, additional_kwargs)
+                        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)
-                        yield self._ai_tool_calls_event(msg_id, msg_chunk.tool_calls)
+                        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,
+                            additional_kwargs_delta,
+                        )

                elif isinstance(msg_chunk, ToolMessage):
                    if msg_id:
@@ -676,17 +704,45 @@ 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:
-                        yield self._ai_tool_calls_event(msg_id, msg.tool_calls)
+                        additional_kwargs_delta = _unsent_additional_kwargs(msg_id, additional_kwargs)
+                        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:
-                        yield self._ai_text_event(msg_id, text, counted_usage)
+                        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,
+                            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)
@@ -775,8 +831,6 @@ 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": [
                {
@@ -786,7 +840,7 @@ class DeerFlowClient:
                    "category": s.category,
                    "enabled": s.enabled,
                }
-                for s in load_skills(self._app_config, enabled_only=enabled_only)
+                for s in get_or_new_skill_storage().load_skills(enabled_only=enabled_only)
            ]
        }

@@ -798,19 +852,19 @@ class DeerFlowClient:
        """
        from deerflow.agents.memory.updater import get_memory_data

-        return get_memory_data(self._app_config.memory, user_id=get_effective_user_id())
+        return get_memory_data(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(self._app_config.memory, user_id=get_effective_user_id())
+        return get_memory_data(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(self._app_config.memory, memory_data, user_id=get_effective_user_id())
+        return import_memory_data(memory_data, user_id=get_effective_user_id())

    def get_model(self, name: str) -> dict | None:
        """Get a specific model's configuration by name.
@@ -845,8 +899,8 @@ class DeerFlowClient:
            Dict with "mcp_servers" key mapping server name to config,
            matching the Gateway API ``McpConfigResponse`` schema.
        """
-        ext = self._app_config.extensions
-        return {"mcp_servers": {name: server.model_dump() for name, server in ext.mcp_servers.items()}}
+        config = get_extensions_config()
+        return {"mcp_servers": {name: server.model_dump() for name, server in config.mcp_servers.items()}}

    def update_mcp_config(self, mcp_servers: dict[str, dict]) -> dict:
        """Update MCP server configurations.
@@ -868,19 +922,18 @@ 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_ext = self._app_config.extensions
+        current_config = get_extensions_config()

        config_data = {
            "mcpServers": mcp_servers,
-            "skills": {name: {"enabled": skill.enabled} for name, skill in current_ext.skills.items()},
+            "skills": {name: {"enabled": skill.enabled} for name, skill in current_config.skills.items()},
        }

        self._atomic_write_json(config_path, config_data)

        self._agent = None
        self._agent_config_key = None
-        self._reload_config()
-        reloaded = self._app_config.extensions
+        reloaded = reload_extensions_config()
        return {"mcp_servers": {name: server.model_dump() for name, server in reloaded.mcp_servers.items()}}

    # ------------------------------------------------------------------
@@ -896,9 +949,9 @@ class DeerFlowClient:
        Returns:
            Skill info dict, or None if not found.
        """
-        from deerflow.skills.loader import load_skills
+        from deerflow.skills.storage import get_or_new_skill_storage

-        skill = next((s for s in load_skills(self._app_config, enabled_only=False) if s.name == name), None)
+        skill = next((s for s in get_or_new_skill_storage().load_skills(enabled_only=False) if s.name == name), None)
        if skill is None:
            return None
        return {
@@ -923,9 +976,9 @@ class DeerFlowClient:
            ValueError: If the skill is not found.
            OSError: If the config file cannot be written.
        """
-        from deerflow.skills.loader import load_skills
+        from deerflow.skills.storage import get_or_new_skill_storage

-        skills = load_skills(self._app_config, enabled_only=False)
+        skills = get_or_new_skill_storage().load_skills(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")
@@ -934,25 +987,21 @@ 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.")

-        # Do not mutate self._app_config (frozen value). Compose the new
-        # 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}
+        extensions_config = get_extensions_config()
+        extensions_config.skills[name] = SkillStateConfig(enabled=enabled)

        config_data = {
-            "mcpServers": {n: s.model_dump() for n, s in ext.mcp_servers.items()},
-            "skills": new_skills,
+            "mcpServers": {n: s.model_dump() for n, s in extensions_config.mcp_servers.items()},
+            "skills": {n: {"enabled": sc.enabled} for n, sc in extensions_config.skills.items()},
        }

        self._atomic_write_json(config_path, config_data)

        self._agent = None
        self._agent_config_key = None
-        self._reload_config()
+        reload_extensions_config()

-        updated = next((s for s in load_skills(self._app_config, enabled_only=False) if s.name == name), None)
+        updated = next((s for s in get_or_new_skill_storage().load_skills(enabled_only=False) if s.name == name), None)
        if updated is None:
            raise RuntimeError(f"Skill '{name}' disappeared after update")
        return {
@@ -976,7 +1025,7 @@ class DeerFlowClient:
            FileNotFoundError: If the file does not exist.
            ValueError: If the file is invalid.
        """
-        return install_skill_from_archive(skill_path)
+        return get_or_new_skill_storage().install_skill_from_archive(skill_path)

    # ------------------------------------------------------------------
    # Public API — memory management
@@ -990,25 +1039,25 @@ class DeerFlowClient:
        """
        from deerflow.agents.memory.updater import reload_memory_data

-        return reload_memory_data(self._app_config.memory, user_id=get_effective_user_id())
+        return reload_memory_data(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(self._app_config.memory, user_id=get_effective_user_id())
+        return clear_memory_data(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(self._app_config.memory, content=content, category=category, confidence=confidence)
+        return create_memory_fact(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(self._app_config.memory, fact_id)
+        return delete_memory_fact(fact_id)

    def update_memory_fact(
        self,
@@ -1021,7 +1070,6 @@ 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,
@@ -1034,7 +1082,9 @@ class DeerFlowClient:
        Returns:
            Memory config dict.
        """
-        config = self._app_config.memory
+        from deerflow.config.memory_config import get_memory_config
+
+        config = get_memory_config()
        return {
            "enabled": config.enabled,
            "storage_path": config.storage_path,
@@ -48,6 +48,12 @@ 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.

@@ -66,13 +72,13 @@ class AioSandbox(Sandbox):
        """
        with self._lock:
            try:
-                result = self._client.shell.exec_command(command=command)
+                result = self._client.shell.exec_command(command=command, no_change_timeout=self._DEFAULT_NO_CHANGE_TIMEOUT)
                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)
+                    result = self._client.shell.exec_command(command=command, id=fresh_id, no_change_timeout=self._DEFAULT_NO_CHANGE_TIMEOUT)
                    output = result.data.output if result.data else ""

                return output if output else "(no output)"
@@ -108,7 +114,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")
+                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)
                output = result.data.output if result.data else ""
                if output:
                    return [line.strip() for line in output.strip().split("\n") if line.strip()]
@@ -25,7 +25,7 @@ except ImportError:  # pragma: no cover - Windows fallback
    fcntl = None  # type: ignore[assignment]
    import msvcrt

-from deerflow.config.app_config import AppConfig
+from deerflow.config import get_app_config
 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
@@ -90,8 +90,7 @@ class AioSandboxProvider(SandboxProvider):
          API_KEY: $MY_API_KEY
    """

-    def __init__(self, app_config: "AppConfig"):
-        self._app_config = app_config
+    def __init__(self):
        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,7 +159,8 @@ class AioSandboxProvider(SandboxProvider):

    def _load_config(self) -> dict:
        """Load sandbox configuration from app config."""
-        sandbox_config = self._app_config.sandbox
+        config = get_app_config()
+        sandbox_config = config.sandbox

        idle_timeout = getattr(sandbox_config, "idle_timeout", None)
        replicas = getattr(sandbox_config, "replicas", None)
@@ -283,15 +283,17 @@ class AioSandboxProvider(SandboxProvider):
            (paths.host_acp_workspace_dir(thread_id, user_id=user_id), "/mnt/acp-workspace", True),
        ]

-    def _get_skills_mount(self) -> tuple[str, str, bool] | None:
+    @staticmethod
+    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:
-            skills_path = self._app_config.skills.get_skills_path()
-            container_path = self._app_config.skills.container_path
+            config = get_app_config()
+            skills_path = config.skills.get_skills_path()
+            container_path = config.skills.container_path

            if skills_path.exists():
                # When running inside Docker with DooD, use host-side skills path.
@@ -9,6 +9,7 @@ from __future__ import annotations
 import json
 import logging
 import os
+import shlex
 import subprocess
 from datetime import datetime

@@ -86,6 +87,88 @@ 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.

@@ -424,12 +507,17 @@ 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",
-                f"{port}:8080",
+                port_mapping,
                "--name",
                container_name,
            ]
@@ -464,7 +552,8 @@ class LocalContainerBackend(SandboxBackend):

        cmd.append(self._image)

-        logger.info(f"Starting container using {self._runtime}: {' '.join(cmd)}")
+        log_cmd = _format_container_command_for_log(_redact_container_command_for_log(cmd))
+        logger.info(f"Starting container using {self._runtime}: {log_cmd}")

        try:
            result = subprocess.run(cmd, capture_output=True, text=True, check=True)
@@ -84,8 +84,52 @@ 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:
@@ -5,9 +5,9 @@ Web Search Tool - Search the web using DuckDuckGo (no API key required).
 import json
 import logging

-from langchain.tools import ToolRuntime, tool
+from langchain.tools import tool

-from deerflow.config.deer_flow_context import resolve_context
+from deerflow.config import get_app_config

 logger = logging.getLogger(__name__)

@@ -55,7 +55,6 @@ 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.
@@ -64,11 +63,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.
    """
-    tool_config = resolve_context(runtime).app_config.get_tool_config("web_search")
+    config = get_app_config().get_tool_config("web_search")

    # Override max_results from config if set
-    if tool_config is not None and "max_results" in tool_config.model_extra:
-        max_results = tool_config.model_extra.get("max_results", max_results)
+    if config is not None and "max_results" in config.model_extra:
+        max_results = config.model_extra.get("max_results", max_results)

    results = _search_text(
        query=query,
@@ -1,39 +1,37 @@
 import json

 from exa_py import Exa
-from langchain.tools import ToolRuntime, tool
+from langchain.tools import tool

-from deerflow.config.app_config import AppConfig
-from deerflow.config.deer_flow_context import resolve_context
+from deerflow.config import get_app_config


-def _get_exa_client(app_config: AppConfig, tool_name: str = "web_search") -> Exa:
-    tool_config = app_config.get_tool_config(tool_name)
+def _get_exa_client(tool_name: str = "web_search") -> Exa:
+    config = get_app_config().get_tool_config(tool_name)
    api_key = None
-    if tool_config is not None and "api_key" in tool_config.model_extra:
-        api_key = tool_config.model_extra.get("api_key")
+    if config is not None and "api_key" in config.model_extra:
+        api_key = config.model_extra.get("api_key")
    return Exa(api_key=api_key)


@tool("web_search", parse_docstring=True)
-def web_search_tool(query: str, runtime: ToolRuntime) -> str:
+def web_search_tool(query: str) -> str:
    """Search the web.

    Args:
        query: The query to search for.
    """
    try:
-        app_config = resolve_context(runtime).app_config
-        tool_config = app_config.get_tool_config("web_search")
+        config = get_app_config().get_tool_config("web_search")
        max_results = 5
        search_type = "auto"
        contents_max_characters = 1000
-        if tool_config is not None:
-            max_results = tool_config.model_extra.get("max_results", max_results)
-            search_type = tool_config.model_extra.get("search_type", search_type)
-            contents_max_characters = tool_config.model_extra.get("contents_max_characters", contents_max_characters)
+        if config is not None:
+            max_results = config.model_extra.get("max_results", max_results)
+            search_type = config.model_extra.get("search_type", search_type)
+            contents_max_characters = config.model_extra.get("contents_max_characters", contents_max_characters)

-        client = _get_exa_client(app_config)
+        client = _get_exa_client()
        res = client.search(
            query,
            type=search_type,
@@ -56,7 +54,7 @@ def web_search_tool(query: str, runtime: ToolRuntime) -> str:


@tool("web_fetch", parse_docstring=True)
-def web_fetch_tool(url: str, runtime: ToolRuntime) -> str:
+def web_fetch_tool(url: str) -> str:
    """Fetch the contents of a web page at a given URL.
    Only fetch EXACT URLs that have been provided directly by the user or have been returned in results from the web_search and web_fetch tools.
    This tool can NOT access content that requires authentication, such as private Google Docs or pages behind login walls.
@@ -67,7 +65,7 @@ def web_fetch_tool(url: str, runtime: ToolRuntime) -> str:
        url: The URL to fetch the contents of.
    """
    try:
-        client = _get_exa_client(resolve_context(runtime).app_config, "web_fetch")
+        client = _get_exa_client("web_fetch")
        res = client.get_contents([url], text={"max_characters": 4096})

        if res.results:
@@ -1,35 +1,33 @@
 import json

 from firecrawl import FirecrawlApp
-from langchain.tools import ToolRuntime, tool
+from langchain.tools import tool

-from deerflow.config.app_config import AppConfig
-from deerflow.config.deer_flow_context import resolve_context
+from deerflow.config import get_app_config


-def _get_firecrawl_client(app_config: AppConfig, tool_name: str = "web_search") -> FirecrawlApp:
-    tool_config = app_config.get_tool_config(tool_name)
+def _get_firecrawl_client(tool_name: str = "web_search") -> FirecrawlApp:
+    config = get_app_config().get_tool_config(tool_name)
    api_key = None
-    if tool_config is not None and "api_key" in tool_config.model_extra:
-        api_key = tool_config.model_extra.get("api_key")
+    if config is not None and "api_key" in config.model_extra:
+        api_key = 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, runtime: ToolRuntime) -> str:
+def web_search_tool(query: str) -> str:
    """Search the web.

    Args:
        query: The query to search for.
    """
    try:
-        app_config = resolve_context(runtime).app_config
-        tool_config = app_config.get_tool_config("web_search")
+        config = get_app_config().get_tool_config("web_search")
        max_results = 5
-        if tool_config is not None:
-            max_results = tool_config.model_extra.get("max_results", max_results)
+        if config is not None:
+            max_results = config.model_extra.get("max_results", max_results)

-        client = _get_firecrawl_client(app_config, "web_search")
+        client = _get_firecrawl_client("web_search")
        result = client.search(query, limit=max_results)

        # result.web contains list of SearchResultWeb objects
@@ -49,7 +47,7 @@ def web_search_tool(query: str, runtime: ToolRuntime) -> str:


@tool("web_fetch", parse_docstring=True)
-def web_fetch_tool(url: str, runtime: ToolRuntime) -> str:
+def web_fetch_tool(url: str) -> str:
    """Fetch the contents of a web page at a given URL.
    Only fetch EXACT URLs that have been provided directly by the user or have been returned in results from the web_search and web_fetch tools.
    This tool can NOT access content that requires authentication, such as private Google Docs or pages behind login walls.
@@ -60,8 +58,7 @@ def web_fetch_tool(url: str, runtime: ToolRuntime) -> str:
        url: The URL to fetch the contents of.
    """
    try:
-        app_config = resolve_context(runtime).app_config
-        client = _get_firecrawl_client(app_config, "web_fetch")
+        client = _get_firecrawl_client("web_fetch")
        result = client.scrape(url, formats=["markdown"])

        markdown_content = result.markdown or ""
@@ -5,9 +5,9 @@ Image Search Tool - Search images using DuckDuckGo for reference in image genera
 import json
 import logging

-from langchain.tools import ToolRuntime, tool
+from langchain.tools import tool

-from deerflow.config.deer_flow_context import resolve_context
+from deerflow.config import get_app_config

 logger = logging.getLogger(__name__)

@@ -77,7 +77,6 @@ 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,
@@ -100,11 +99,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.
    """
-    tool_config = resolve_context(runtime).app_config.get_tool_config("image_search")
+    config = get_app_config().get_tool_config("image_search")

    # Override max_results from config if set
-    if tool_config is not None and "max_results" in tool_config.model_extra:
-        max_results = tool_config.model_extra.get("max_results", max_results)
+    if config is not None and "max_results" in config.model_extra:
+        max_results = config.model_extra.get("max_results", max_results)

    results = _search_images(
        query=query,
@@ -1,7 +1,6 @@
-from langchain.tools import ToolRuntime, tool
+from langchain.tools import tool

-from deerflow.config.app_config import AppConfig
-from deerflow.config.deer_flow_context import resolve_context
+from deerflow.config import get_app_config
 from deerflow.utils.readability import ReadabilityExtractor

 from .infoquest_client import InfoQuestClient
@@ -9,13 +8,13 @@ from .infoquest_client import InfoQuestClient
 readability_extractor = ReadabilityExtractor()


-def _get_infoquest_client(app_config: AppConfig) -> InfoQuestClient:
-    search_config = app_config.get_tool_config("web_search")
+def _get_infoquest_client() -> InfoQuestClient:
+    search_config = get_app_config().get_tool_config("web_search")
    search_time_range = -1
    if search_config is not None and "search_time_range" in search_config.model_extra:
        search_time_range = search_config.model_extra.get("search_time_range")

-    fetch_config = app_config.get_tool_config("web_fetch")
+    fetch_config = get_app_config().get_tool_config("web_fetch")
    fetch_time = -1
    if fetch_config is not None and "fetch_time" in fetch_config.model_extra:
        fetch_time = fetch_config.model_extra.get("fetch_time")
@@ -26,7 +25,7 @@ def _get_infoquest_client(app_config: AppConfig) -> 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 = app_config.get_tool_config("image_search")
+    image_search_config = get_app_config().get_tool_config("image_search")
    image_search_time_range = -1
    if image_search_config is not None and "image_search_time_range" in image_search_config.model_extra:
        image_search_time_range = image_search_config.model_extra.get("image_search_time_range")
@@ -45,18 +44,19 @@ def _get_infoquest_client(app_config: AppConfig) -> InfoQuestClient:


@tool("web_search", parse_docstring=True)
-def web_search_tool(query: str, runtime: ToolRuntime) -> str:
+def web_search_tool(query: str) -> 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, runtime: ToolRuntime) -> str:
+def web_fetch_tool(url: str) -> str:
    """Fetch the contents of a web page at a given URL.
    Only fetch EXACT URLs that have been provided directly by the user or have been returned in results from the web_search and web_fetch tools.
    This tool can NOT access content that requires authentication, such as private Google Docs or pages behind login walls.
@@ -66,7 +66,7 @@ def web_fetch_tool(url: str, runtime: ToolRuntime) -> str:
    Args:
        url: The URL to fetch the contents of.
    """
-    client = _get_infoquest_client(resolve_context(runtime).app_config)
+    client = _get_infoquest_client()
    result = client.fetch(url)
    if result.startswith("Error: "):
        return result
@@ -75,7 +75,7 @@ def web_fetch_tool(url: str, runtime: ToolRuntime) -> str:


@tool("image_search", parse_docstring=True)
-def image_search_tool(query: str, runtime: ToolRuntime) -> str:
+def image_search_tool(query: str) -> str:
    """Search for images online. Use this tool BEFORE image generation to find reference images for characters, portraits, objects, scenes, or any content requiring visual accuracy.

    **When to use:**
@@ -89,5 +89,5 @@ def image_search_tool(query: str, runtime: ToolRuntime) -> str:
    Args:
        query: The query to search for images.
    """
-    client = _get_infoquest_client(resolve_context(runtime).app_config)
+    client = _get_infoquest_client()
    return client.image_search(query)
@@ -1,16 +1,16 @@
 import asyncio

-from langchain.tools import ToolRuntime, tool
+from langchain.tools import tool

 from deerflow.community.jina_ai.jina_client import JinaClient
-from deerflow.config.deer_flow_context import resolve_context
+from deerflow.config import get_app_config
 from deerflow.utils.readability import ReadabilityExtractor

 readability_extractor = ReadabilityExtractor()


@tool("web_fetch", parse_docstring=True)
-async def web_fetch_tool(url: str, runtime: ToolRuntime) -> str:
+async def web_fetch_tool(url: str) -> str:
    """Fetch the contents of a web page at a given URL.
    Only fetch EXACT URLs that have been provided directly by the user or have been returned in results from the web_search and web_fetch tools.
    This tool can NOT access content that requires authentication, such as private Google Docs or pages behind login walls.
@@ -22,9 +22,9 @@ async def web_fetch_tool(url: str, runtime: ToolRuntime) -> str:
    """
    jina_client = JinaClient()
    timeout = 10
-    tool_config = resolve_context(runtime).app_config.get_tool_config("web_fetch")
-    if tool_config is not None and "timeout" in tool_config.model_extra:
-        timeout = tool_config.model_extra.get("timeout")
+    config = get_app_config().get_tool_config("web_fetch")
+    if config is not None and "timeout" in config.model_extra:
+        timeout = 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
@@ -0,0 +1,3 @@
+from .tools import web_search_tool
+
+__all__ = ["web_search_tool"]
@@ -0,0 +1,95 @@
+"""
+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)
@@ -1,34 +1,32 @@
 import json

-from langchain.tools import ToolRuntime, tool
+from langchain.tools import tool
 from tavily import TavilyClient

-from deerflow.config.app_config import AppConfig
-from deerflow.config.deer_flow_context import resolve_context
+from deerflow.config import get_app_config


-def _get_tavily_client(app_config: AppConfig) -> TavilyClient:
-    tool_config = app_config.get_tool_config("web_search")
+def _get_tavily_client() -> TavilyClient:
+    config = get_app_config().get_tool_config("web_search")
    api_key = None
-    if tool_config is not None and "api_key" in tool_config.model_extra:
-        api_key = tool_config.model_extra.get("api_key")
+    if config is not None and "api_key" in config.model_extra:
+        api_key = config.model_extra.get("api_key")
    return TavilyClient(api_key=api_key)


@tool("web_search", parse_docstring=True)
-def web_search_tool(query: str, runtime: ToolRuntime) -> str:
+def web_search_tool(query: str) -> str:
    """Search the web.

    Args:
        query: The query to search for.
    """
-    app_config = resolve_context(runtime).app_config
-    tool_config = app_config.get_tool_config("web_search")
+    config = get_app_config().get_tool_config("web_search")
    max_results = 5
-    if tool_config is not None and "max_results" in tool_config.model_extra:
-        max_results = tool_config.model_extra.get("max_results")
+    if config is not None and "max_results" in config.model_extra:
+        max_results = config.model_extra.get("max_results")

-    client = _get_tavily_client(app_config)
+    client = _get_tavily_client()
    res = client.search(query, max_results=max_results)
    normalized_results = [
        {
@@ -43,7 +41,7 @@ def web_search_tool(query: str, runtime: ToolRuntime) -> str:


@tool("web_fetch", parse_docstring=True)
-def web_fetch_tool(url: str, runtime: ToolRuntime) -> str:
+def web_fetch_tool(url: str) -> str:
    """Fetch the contents of a web page at a given URL.
    Only fetch EXACT URLs that have been provided directly by the user or have been returned in results from the web_search and web_fetch tools.
    This tool can NOT access content that requires authentication, such as private Google Docs or pages behind login walls.
@@ -53,8 +51,7 @@ def web_fetch_tool(url: str, runtime: ToolRuntime) -> str:
    Args:
        url: The URL to fetch the contents of.
    """
-    app_config = resolve_context(runtime).app_config
-    client = _get_tavily_client(app_config)
+    client = _get_tavily_client()
    res = client.extract([url])
    if "failed_results" in res and len(res["failed_results"]) > 0:
        return f"Error: {res['failed_results'][0]['error']}"
@@ -1,6 +1,7 @@
-from .app_config import AppConfig
-from .extensions_config import ExtensionsConfig
-from .memory_config import MemoryConfig
+from .app_config import get_app_config
+from .extensions_config import ExtensionsConfig, get_extensions_config
+from .loop_detection_config import LoopDetectionConfig
+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
@@ -13,16 +14,19 @@ from .tracing_config import (
 )

 __all__ = [
-    "AppConfig",
-    "ExtensionsConfig",
-    "MemoryConfig",
-    "Paths",
+    "get_app_config",
    "SkillEvolutionConfig",
-    "SkillsConfig",
-    "get_enabled_tracing_providers",
-    "get_explicitly_enabled_tracing_providers",
+    "Paths",
    "get_paths",
+    "SkillsConfig",
+    "ExtensionsConfig",
+    "get_extensions_config",
+    "LoopDetectionConfig",
+    "MemoryConfig",
+    "get_memory_config",
    "get_tracing_config",
+    "get_explicitly_enabled_tracing_providers",
+    "get_enabled_tracing_providers",
    "is_tracing_enabled",
    "validate_enabled_tracing_providers",
 ]
@@ -1,13 +1,16 @@
 """ACP (Agent Client Protocol) agent configuration loaded from config.yaml."""

-from pydantic import BaseModel, ConfigDict, Field
+import logging
+from collections.abc import Mapping
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)


 class ACPAgentConfig(BaseModel):
    """Configuration for a single ACP-compatible agent."""

-    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.")
@@ -21,3 +24,28 @@ 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()))
@@ -1,14 +1,32 @@
 """Configuration for the custom agents management API."""

-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, 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)
@@ -1,13 +1,22 @@
-"""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, ConfigDict
+from pydantic import BaseModel

 from deerflow.config.paths import get_paths
+from deerflow.runtime.user_context import get_effective_user_id

 logger = logging.getLogger(__name__)

@@ -29,8 +38,6 @@ 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
@@ -42,14 +49,47 @@ class AgentConfig(BaseModel):
    skills: list[str] | None = None


-def load_agent_config(name: str | None) -> AgentConfig | None:
+def resolve_agent_dir(name: str, *, user_id: str | None = None) -> Path:
+    """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.
+        AgentConfig instance, or ``None`` if ``name`` is ``None``.

    Raises:
        FileNotFoundError: If the agent directory or config.yaml does not exist.
@@ -60,7 +100,7 @@ def load_agent_config(name: str | None) -> AgentConfig | None:
        return None

    name = validate_agent_name(name)
-    agent_dir = get_paths().agent_dir(name)
+    agent_dir = resolve_agent_dir(name, user_id=user_id)
    config_file = agent_dir / "config.yaml"

    if not agent_dir.exists():
@@ -86,7 +126,7 @@ def load_agent_config(name: str | None) -> AgentConfig | None:
    return AgentConfig(**data)


-def load_agent_soul(agent_name: str | None) -> str | None:
+def load_agent_soul(agent_name: str | None, *, user_id: str | None = 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.
@@ -94,11 +134,16 @@ def load_agent_soul(agent_name: str | None) -> str | None:

    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.
    """
-    agent_dir = get_paths().agent_dir(agent_name) if agent_name else get_paths().base_dir
+    if agent_name:
+        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
@@ -106,32 +151,50 @@ def load_agent_soul(agent_name: str | None) -> str | None:
    return content or None


-def list_custom_agents() -> list[AgentConfig]:
+def list_custom_agents(*, user_id: str | None = None) -> 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.
    """
-    agents_dir = get_paths().agents_dir
-
-    if not agents_dir.exists():
-        return []
+    paths = get_paths()
+    effective_user = user_id or get_effective_user_id()

+    seen: set[str] = set()
    agents: list[AgentConfig] = []

-    for entry in sorted(agents_dir.iterdir()):
-        if not entry.is_dir():
+    user_root = paths.user_agents_dir(effective_user)
+    legacy_root = paths.agents_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

-        config_file = entry / "config.yaml"
-        if not config_file.exists():
-            logger.debug(f"Skipping {entry.name}: no config.yaml")
-            continue
-
-        try:
-            agent_cfg = load_agent_config(entry.name)
-            agents.append(agent_cfg)
-        except Exception as e:
-            logger.warning(f"Skipping agent '{entry.name}': {e}")
+            try:
+                agent_cfg = load_agent_config(entry.name, user_id=effective_user)
+                if agent_cfg is None:
+                    continue
+                agents.append(agent_cfg)
+                seen.add(entry.name)
+            except Exception as e:
+                logger.warning(f"Skipping agent '{entry.name}': {e}")

+    agents.sort(key=lambda a: a.name)
    return agents
@@ -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,25 +9,27 @@ import yaml
 from dotenv import load_dotenv
 from pydantic import BaseModel, ConfigDict, Field

-from deerflow.config.acp_config import ACPAgentConfig
-from deerflow.config.agents_api_config import AgentsApiConfig
-from deerflow.config.checkpointer_config import CheckpointerConfig
+from deerflow.config.acp_config import ACPAgentConfig, load_acp_config_from_dict
+from deerflow.config.agents_api_config import AgentsApiConfig, load_agents_api_config_from_dict
+from deerflow.config.checkpointer_config import CheckpointerConfig, load_checkpointer_config_from_dict
 from deerflow.config.database_config import DatabaseConfig
 from deerflow.config.extensions_config import ExtensionsConfig
-from deerflow.config.guardrails_config import GuardrailsConfig
-from deerflow.config.memory_config import MemoryConfig
+from deerflow.config.guardrails_config import GuardrailsConfig, load_guardrails_config_from_dict
+from deerflow.config.loop_detection_config import LoopDetectionConfig
+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
-from deerflow.config.subagents_config import SubagentsAppConfig
-from deerflow.config.summarization_config import SummarizationConfig
-from deerflow.config.title_config import TitleConfig
+from deerflow.config.stream_bridge_config import StreamBridgeConfig, load_stream_bridge_config_from_dict
+from deerflow.config.subagents_config import SubagentsAppConfig, load_subagents_config_from_dict
+from deerflow.config.summarization_config import SummarizationConfig, load_summarization_config_from_dict
+from deerflow.config.title_config import TitleConfig, load_title_config_from_dict
 from deerflow.config.token_usage_config import TokenUsageConfig
 from deerflow.config.tool_config import ToolConfig, ToolGroupConfig
-from deerflow.config.tool_search_config import ToolSearchConfig
+from deerflow.config.tool_search_config import ToolSearchConfig, load_tool_search_config_from_dict

 load_dotenv()

@@ -47,17 +49,41 @@ class CircuitBreakerConfig(BaseModel):
    recovery_timeout_sec: int = Field(default=60, description="Time in seconds before attempting to recover the circuit")


-def _default_config_candidates() -> tuple[Path, ...]:
-    """Return deterministic config.yaml locations without relying on cwd."""
+def _legacy_config_candidates() -> tuple[Path, ...]:
+    """Return source-tree config.yaml locations for monorepo compatibility."""
    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 modules (debug/info/warning/error)")
+    log_level: str = Field(default="info", description="Logging level for deerflow and app modules (debug/info/warning/error); third-party libraries are not affected")
    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")
@@ -71,15 +97,16 @@ 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:
@@ -88,7 +115,8 @@ 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 deterministic backend/repository-root defaults from `_default_config_candidates()`.
+        3. Otherwise, search the caller project root.
+        4. Finally, search legacy backend/repository-root defaults for monorepo compatibility.
        """
        if config_path:
            path = Path(config_path)
@@ -101,10 +129,14 @@ class AppConfig(BaseModel):
                raise FileNotFoundError(f"Config file specified by environment variable `DEER_FLOW_CONFIG_PATH` not found at {path}")
            return path
        else:
-            for path in _default_config_candidates():
+            project_config = existing_project_file(("config.yaml",))
+            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 at the default backend or repository root locations")
+            raise FileNotFoundError("`config.yaml` file not found in the project root or legacy backend/repository root locations")

    @classmethod
    def from_file(cls, config_path: str | None = None) -> Self:
@@ -128,13 +160,54 @@ class AppConfig(BaseModel):
        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."""
@@ -250,8 +323,133 @@ 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.
-    # Composition roots that hold the resolved instance:
-    #   - Gateway:   ``app.state.config`` via ``Depends(get_config)``
-    #   - Client:    ``DeerFlowClient._app_config``
-    #   - Agent run: ``Runtime[DeerFlowContext].context.app_config``
+
+# Compatibility singleton layer for code paths that have not yet been
+# migrated to explicit ``AppConfig`` threading. New composition roots should
+# prefer constructing ``AppConfig`` once and passing it down directly.
+_app_config: AppConfig | None = None
+_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)
@@ -2,7 +2,7 @@

 from typing import Literal

-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, Field

 CheckpointerType = Literal["memory", "sqlite", "postgres"]

@@ -10,18 +10,41 @@ 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 (requires langgraph-checkpoint-postgres)."
+        "'postgres' persists to PostgreSQL (install with deerflow-harness[postgres])."
    )
    connection_string: str | None = Field(
        default=None,
        description="Connection string for sqlite (file path) or postgres (DSN). "
-        "Required for sqlite and postgres types. "
+        "Optional for sqlite and defaults to 'store.db' when omitted. "
+        "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)
@@ -34,11 +34,10 @@ from __future__ import annotations
 import os
 from typing import Literal

-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, 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."),
@@ -1,55 +0,0 @@
-"""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__
-    )
--- a/Show More
+++ b/Show More