feat(subagents): extend deferred MCP tool loading to subagents (#3432 )

* feat(subagents): extend deferred MCP tool loading to subagents (#3341) Subagents now reuse the lead agent's deferred-tool path: when tool_search.enabled, MCP tool schemas are withheld from the model and surfaced by name in <available-deferred-tools>, fetched on demand via the generated tool_search helper. DeferredToolFilterMiddleware deterministically rewrites request.tools to hide the deferred schemas (the prompt section is discovery only, not enforcement). Consolidates the assembly into deerflow.tools.builtins.tool_search, now the single home for both assemble_deferred_tools (centralized fail-closed guard, replacing the lead-only private _assemble_deferred) and the relocated get_deferred_tools_prompt_section. Shared by every build path: lead agent, embedded client, and subagent executor. tool_search is appended after the subagent's name-level tool policy and is treated as infrastructure: its catalog is built from the already policy-filtered list, so it can never surface a tool the policy denied. Follow-up to #3370. Fixes #3341. * test(subagents): assert the real middleware builder emits a working deferred filter (#3341) The existing recipe test hand-constructs DeferredToolFilterMiddleware, so it cannot catch a regression in how build_subagent_runtime_middlewares (the call executor._create_agent actually makes) wires the deferred setup into the filter. Add a test that sources the filter from the real builder given a real setup and runs it through a graph: a wrong catalog hash would silently stop promotion, a dropped filter would stop hiding — both now caught. Running the full real middleware stack is intentionally avoided (the other runtime middlewares need sandbox/thread infra to execute, which would make the test flaky); their attachment + ordering before Safety stays locked in test_tool_error_handling_middleware.py. * test(subagents): keep executor tests config-free in CI * chore: trigger ci * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Willem Jiang <willem.jiang@gmail.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
fix(threads): assign new checkpoint ID in update_thread_state (#2391 )
2026-06-10 17:35:57 +00:00 · 2026-06-08 23:17:22 +08:00 · 2026-06-08 23:12:25 +08:00 · 2026-06-08 22:54:23 +08:00 · 2026-06-08 22:04:38 +08:00 · 2026-06-08 19:17:14 +08:00
208 changed files with 17024 additions and 3306 deletions
@@ -0,0 +1,159 @@
 name: 🐛 Bug report
 description: Report something that isn't working so maintainers can reproduce and fix it.
 title: "[bug] "
 labels: ["bug"]
 body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to file a bug. A clear, reproducible report is the
        single biggest factor in how fast it gets fixed.
        Please fill in every required field — especially **reproduction steps** and **logs**.
  - type: checkboxes
    id: preflight
    attributes:
      label: Before you start
      options:
        - label: I searched [existing issues](https://github.com/bytedance/deer-flow/issues?q=is%3Aissue) and this is not a duplicate.
          required: true
        - label: I can reproduce this on the latest `main`.
          required: false
  - type: input
    id: summary
    attributes:
      label: Problem summary
      description: One sentence describing the bug.
      placeholder: e.g. make dev fails to start the gateway service
    validations:
      required: true
  - type: dropdown
    id: areas
    attributes:
      label: Affected area(s)
      description: Which part of DeerFlow does this touch? Select all that apply.
      multiple: true
      options:
        - Frontend (UI / Next.js)
        - Backend API (gateway / endpoints / SSE)
        - Agents / LangGraph (graph, prompts, langgraph.json)
        - Sandbox / Docker
        - Skills
        - MCP
        - Config / setup (make, config.yaml, env)
        - Docs
        - Not sure
    validations:
      required: true
  - type: textarea
    id: actual
    attributes:
      label: What happened?
      description: The actual behavior. Include the key error lines verbatim.
      placeholder: When I do X, I expected Y but I got Z.
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: Expected behavior
      placeholder: What did you expect to happen instead?
    validations:
      required: true
  - type: textarea
    id: reproduce
    attributes:
      label: Steps to reproduce
      description: Exact commands and sequence. Minimal steps that reliably reproduce the problem.
      placeholder: |
        1. make check
        2. make install
        3. make dev
        4. ...
    validations:
      required: true
  - type: textarea
    id: logs
    attributes:
      label: Relevant logs
      description: Paste key lines from logs (for example `logs/gateway.log`, `logs/frontend.log`). Redact secrets.
      render: shell
    validations:
      required: true
  - type: dropdown
    id: run_mode
    attributes:
      label: How are you running DeerFlow?
      options:
        - Local (make dev)
        - Docker (make docker-start)
        - CI
        - Other
    validations:
      required: true
  - type: dropdown
    id: os
    attributes:
      label: Operating system
      options:
        - macOS
        - Linux
        - Windows
        - Other
    validations:
      required: true
  - type: input
    id: platform_details
    attributes:
      label: Platform details
      description: Architecture and shell, if relevant.
      placeholder: e.g. arm64, zsh
  - type: input
    id: python_version
    attributes:
      label: Python version
      placeholder: e.g. Python 3.12.9
  - type: input
    id: node_version
    attributes:
      label: Node.js version
      placeholder: e.g. v22.11.0
  - type: input
    id: pnpm_version
    attributes:
      label: pnpm version
      placeholder: e.g. 10.26.2
  - type: input
    id: uv_version
    attributes:
      label: uv version
      placeholder: e.g. 0.7.20
  - type: textarea
    id: git_info
    attributes:
      label: Git state
      description: Output of `git branch --show-current` and the latest commit SHA.
      placeholder: |
        branch: feature/my-branch
        commit: abcdef1
  - type: textarea
    id: additional
    attributes:
      label: Additional context
      description: Screenshots, related issues, config snippets (redacted), or anything else that helps triage.
@@ -0,0 +1,11 @@
 blank_issues_enabled: false
 contact_links:
  - name: 💬 Questions & usage help
    url: https://github.com/bytedance/deer-flow/discussions/categories/q-a
    about: "How do I use X? Why does Y behave like that? Ask in Discussions — it gets answered faster and stays searchable."
  - name: 💡 Ideas & proposals
    url: https://github.com/bytedance/deer-flow/discussions/categories/ideas
    about: Have a half-formed idea? Float it in Discussions before opening a formal feature request.
  - name: 🔒 Report a security vulnerability
    url: https://github.com/bytedance/deer-flow/security/policy
    about: Do not open a public issue for security problems. Follow the security policy instead.
@@ -0,0 +1,67 @@
 name: 💡 Feature request
 description: Propose a new capability or an improvement to an existing one.
 title: "[feat] "
 labels: ["enhancement"]
 body:
  - type: markdown
    attributes:
      value: |
        Thanks for the suggestion. For non-trivial features, please open a
        [Discussion](https://github.com/bytedance/deer-flow/discussions/categories/ideas)
        first to align on scope before writing code.
  - type: checkboxes
    id: preflight
    attributes:
      label: Before you start
      options:
        - label: I searched [existing issues](https://github.com/bytedance/deer-flow/issues?q=is%3Aissue) and this is not a duplicate.
          required: true
  - type: textarea
    id: problem
    attributes:
      label: Problem / motivation
      description: What problem does this solve? What is painful today, or what does it unblock?
      placeholder: "I'm always frustrated when ..."
    validations:
      required: true
  - type: textarea
    id: solution
    attributes:
      label: Proposed solution
      description: Describe the change from a user's / caller's perspective.
    validations:
      required: true
  - type: dropdown
    id: areas
    attributes:
      label: Affected area(s)
      description: Which part of DeerFlow would this touch? Select all that apply.
      multiple: true
      options:
        - Frontend (UI / Next.js)
        - Backend API (gateway / endpoints / SSE)
        - Agents / LangGraph (graph, prompts, langgraph.json)
        - Sandbox / Docker
        - Skills
        - MCP
        - Config / setup
        - Docs
        - Not sure
    validations:
      required: true
  - type: textarea
    id: alternatives
    attributes:
      label: Alternatives considered
      description: Other approaches you weighed and why you discarded them.
  - type: textarea
    id: additional
    attributes:
      label: Additional context
      description: Mockups, links, related issues, or anything else that helps.
@@ -1,128 +0,0 @@
 name: Runtime Information
 description: Report runtime/environment details to help reproduce an issue.
 title: "[runtime] "
 labels:
  - needs-triage
 body:
  - type: markdown
    attributes:
      value: |
        Thanks for sharing runtime details.
        Complete this form so maintainers can quickly reproduce and diagnose the problem.
  - type: input
    id: summary
    attributes:
      label: Problem summary
      description: Short summary of the issue.
      placeholder: e.g. make dev fails to start gateway service
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: Expected behavior
      placeholder: What did you expect to happen?
    validations:
      required: true
  - type: textarea
    id: actual
    attributes:
      label: Actual behavior
      placeholder: What happened instead? Include key error lines.
    validations:
      required: true
  - type: dropdown
    id: os
    attributes:
      label: Operating system
      options:
        - macOS
        - Linux
        - Windows
        - Other
    validations:
      required: true
  - type: input
    id: platform_details
    attributes:
      label: Platform details
      description: Add architecture and shell if relevant.
      placeholder: e.g. arm64, zsh
  - type: input
    id: python_version
    attributes:
      label: Python version
      placeholder: e.g. Python 3.12.9
  - type: input
    id: node_version
    attributes:
      label: Node.js version
      placeholder: e.g. v23.11.0
  - type: input
    id: pnpm_version
    attributes:
      label: pnpm version
      placeholder: e.g. 10.26.2
  - type: input
    id: uv_version
    attributes:
      label: uv version
      placeholder: e.g. 0.7.20
  - type: dropdown
    id: run_mode
    attributes:
      label: How are you running DeerFlow?
      options:
        - Local (make dev)
        - Docker (make docker-dev)
        - CI
        - Other
    validations:
      required: true
  - type: textarea
    id: reproduce
    attributes:
      label: Reproduction steps
      description: Provide exact commands and sequence.
      placeholder: |
        1. make check
        2. make install
        3. make dev
        4. ...
    validations:
      required: true
  - type: textarea
    id: logs
    attributes:
      label: Relevant logs
      description: Paste key lines from logs (for example logs/gateway.log, logs/frontend.log).
      render: shell
    validations:
      required: true
  - type: textarea
    id: git_info
    attributes:
      label: Git state
      description: Share output of git branch and latest commit SHA.
      placeholder: |
        branch: feature/my-branch
        commit: abcdef1
  - type: textarea
    id: additional
    attributes:
      label: Additional context
      description: Add anything else that might help triage.
@@ -0,0 +1,72 @@
 # Path-based PR auto-labeling config for actions/labeler@v5.
 # Each key is a label (must exist — see .github/labels.yml); the globs decide
 # when it is applied. A PR can match several areas, which is expected.
 "area:frontend":
  - changed-files:
      - any-glob-to-any-file:
          - "frontend/**"
 "area:backend":
  - changed-files:
      - any-glob-to-any-file:
          - "backend/app/**"
          - "backend/packages/harness/deerflow/runtime/**"
          - "backend/packages/harness/deerflow/persistence/**"
          - "backend/packages/harness/deerflow/config/**"
          - "backend/packages/harness/deerflow/tools/**"
          - "backend/packages/harness/deerflow/guardrails/**"
          - "backend/packages/harness/deerflow/tracing/**"
          - "backend/packages/harness/deerflow/models/**"
          - "backend/packages/harness/deerflow/utils/**"
          - "backend/packages/harness/deerflow/uploads/**"
 "area:agents":
  - changed-files:
      - any-glob-to-any-file:
          - "backend/packages/harness/deerflow/agents/**"
          - "backend/packages/harness/deerflow/subagents/**"
          - "backend/packages/harness/deerflow/reflection/**"
          - "backend/langgraph.json"
          - "backend/**/prompts/**"
 "area:sandbox":
  - changed-files:
      - any-glob-to-any-file:
          - "docker/**"
          - "backend/packages/harness/deerflow/sandbox/**"
          - "backend/Dockerfile"
          - "frontend/Dockerfile"
 "area:skills":
  - changed-files:
      - any-glob-to-any-file:
          - "skills/**"
          - "backend/packages/harness/deerflow/skills/**"
          - "frontend/src/core/skills/**"
 "area:mcp":
  - changed-files:
      - any-glob-to-any-file:
          - "backend/packages/harness/deerflow/mcp/**"
          - "frontend/src/core/mcp/**"
 "area:ci":
  - changed-files:
      - any-glob-to-any-file:
          - ".github/**"
          - "scripts/**"
 "area:docs":
  - changed-files:
      - any-glob-to-any-file:
          - "docs/**"
          - "**/*.md"
 "area:deps":
  - changed-files:
      - any-glob-to-any-file:
          - "backend/pyproject.toml"
          - "backend/uv.lock"
          - "frontend/package.json"
          - "frontend/pnpm-lock.yaml"
@@ -0,0 +1,119 @@
 # Declarative label source of truth for DeerFlow.
 #
 # This file is the single source of truth for repository labels used by the
 # auto-labeling workflows (.github/workflows/pr-labeler.yml, pr-triage.yml,
 # issue-triage.yml). Auto-labelers can only apply labels that already exist,
 # so every label referenced by a workflow MUST be declared here.
 #
 # Apply with:  uv run --with pyyaml python scripts/sync_labels.py [--repo OWNER/NAME]
 # CI keeps it in sync via .github/workflows/label-sync.yml (runs on changes here).
 #
 # Sync is additive/update-only: it creates or updates the labels listed below
 # and never deletes labels that are not listed.
 #
 # Color = 6-digit hex without the leading '#'.
 labels:
  # ── Type ─────────────────────────────────────────────────────────────────
  # Mostly GitHub defaults; declared here so colors/descriptions stay stable
  # and so issue templates can rely on them existing.
  - name: bug
    color: d73a4a
    description: Something isn't working
  - name: enhancement
    color: a2eeef
    description: New feature or request
  - name: documentation
    color: 0075ca
    description: Improvements or additions to documentation
  - name: question
    color: d876e3
    description: Further information is requested
  # ── Area (auto, by changed paths — see .github/labeler.yml) ───────────────
  # Mirrors the "Surface area" section of the pull request template.
  - name: "area:frontend"
    color: c5def5
    description: Next.js frontend under frontend/
  - name: "area:backend"
    color: c5def5
    description: Gateway / runtime / core backend under backend/
  - name: "area:agents"
    color: c5def5
    description: Agents, subagents, graph wiring, prompts, langgraph.json
  - name: "area:sandbox"
    color: c5def5
    description: Sandboxed execution and docker/
  - name: "area:skills"
    color: c5def5
    description: Skills under skills/ or the skills harness
  - name: "area:mcp"
    color: c5def5
    description: Model Context Protocol integration
  - name: "area:ci"
    color: c5def5
    description: GitHub Actions, CI config, repo tooling
  - name: "area:docs"
    color: c5def5
    description: Documentation and Markdown only
  - name: "area:deps"
    color: c5def5
    description: Dependency manifests / lockfiles
  # ── Size (auto, by additions + deletions — see pr-triage.yml) ─────────────
  - name: "size/XS"
    color: "009900"
    description: PR changes < 20 lines
  - name: "size/S"
    color: 77bb00
    description: PR changes 20-100 lines
  - name: "size/M"
    color: eebb00
    description: PR changes 100-300 lines
  - name: "size/L"
    color: ee9900
    description: PR changes 300-700 lines
  - name: "size/XL"
    color: ee5500
    description: PR changes 700+ lines
  # ── Risk (auto, by changed paths — see pr-triage.yml) ─────────────────────
  - name: "risk:low"
    color: 0e8a16
    description: "Low risk: docs / i18n / assets only"
  - name: "risk:medium"
    color: fbca04
    description: "Medium risk: regular code changes"
  - name: "risk:high"
    color: b60205
    description: "High risk: backend API, agents, sandbox, auth, deps, CI"
  # ── Priority (manual) ─────────────────────────────────────────────────────
  - name: P0
    color: b60205
    description: Critical priority
  - name: P1
    color: d93f0b
    description: Major priority
  - name: P2
    color: e99695
    description: Normal priority
  # ── Status (auto + manual) ────────────────────────────────────────────────
  - name: needs-triage
    color: fef2c0
    description: Awaiting maintainer triage
  - name: needs-validation
    color: d4c5f9
    description: Touches front/back contract surface; needs real-path validation
  - name: skip-validation
    color: cccccc
    description: "Maintainer override: do not auto-add needs-validation on this PR"
  - name: reviewing
    color: 5319e7
    description: A maintainer is reviewing this PR
  # ── Contributor ───────────────────────────────────────────────────────────
  - name: first-time-contributor
    color: c2e0c6
    description: First contribution to this repository — be welcoming
@@ -59,3 +59,17 @@ Fixes #
       Frontend:  cd frontend && pnpm format && pnpm lint && pnpm typecheck && BETTER_AUTH_SECRET=local-dev-secret pnpm build && make test
       Frontend E2E (if you touched frontend/): cd frontend && make test-e2e -->
 ## AI assistance
 <!-- DeerFlow is an AI project — most PRs here use AI coding tools, and that's
     welcome. Disclosing it just helps reviewers calibrate how closely to read the
     diff. Please fill all three; don't delete the section. -->
 **Tool(s) used:** <!-- e.g. Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, or "none" -->
 **How you used it:** <!-- e.g. "generated the module from a spec", "autocomplete only",
     "AI wrote tests, I wrote the impl". A prompt or conversation link is great too. -->
 - [ ] I've read and understand every line of this change and take responsibility for it — it's not unreviewed AI output.
@@ -0,0 +1,44 @@
 name: Issue Triage
 # Ensures every newly opened issue carries `needs-triage`, even blank or
 # API-created ones that bypass the issue templates. Creates the label if it is
 # somehow missing, so the workflow is self-healing.
 on:
  issues:
    types: [opened]
 permissions:
  issues: write
 jobs:
  needs-triage:
    runs-on: ubuntu-latest
    steps:
      - name: Add needs-triage label
        uses: actions/github-script@v7
        with:
          script: |
            const { owner, repo } = context.repo;
            const issue_number = context.payload.issue.number;
            const current = (context.payload.issue.labels || []).map(l => l.name);
            if (current.includes('needs-triage')) {
              core.info('Issue already has needs-triage; nothing to do.');
              return;
            }
            // Self-heal: create the label if it does not exist yet.
            try {
              await github.rest.issues.createLabel({
                owner, repo, name: 'needs-triage', color: 'fef2c0',
                description: 'Awaiting maintainer triage',
              });
            } catch (e) {
              if (e.status !== 422) throw e; // 422 = already exists
            }
            await github.rest.issues.addLabels({
              owner, repo, issue_number, labels: ['needs-triage'],
            });
            core.info(`Added needs-triage to #${issue_number}.`);
@@ -0,0 +1,38 @@
 name: Label Sync
 # Keeps repository labels in sync with the declarative source of truth
 # (.github/labels.yml). Runs whenever that file changes on main, and can be
 # triggered manually. Additive/update-only — never deletes labels.
 on:
  push:
    branches: [main]
    paths:
      - ".github/labels.yml"
      - "scripts/sync_labels.py"
      - ".github/workflows/label-sync.yml"
  workflow_dispatch:
 permissions:
  contents: read
  issues: write
 concurrency:
  group: label-sync
  cancel-in-progress: false
 jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Install uv
        uses: astral-sh/setup-uv@v7
      - name: Sync labels
        run: uv run --with pyyaml python scripts/sync_labels.py
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GH_REPO: ${{ github.repository }}
@@ -0,0 +1,28 @@
 name: PR Labeler
 # Applies area:* labels based on which files a PR changes (see .github/labeler.yml).
 # Uses pull_request_target so it also works on fork PRs. SAFE: actions/labeler
 # only reads the changed-file list via the API — it never checks out or runs PR code.
 on:
  pull_request_target:
    types: [opened, synchronize, reopened, ready_for_review]
 permissions:
  contents: read
  pull-requests: write
 concurrency:
  group: pr-labeler-${{ github.event.pull_request.number }}
  cancel-in-progress: true
 jobs:
  label:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    steps:
      - name: Apply area labels
        uses: actions/labeler@v5
        with:
          configuration-path: .github/labeler.yml
          sync-labels: true
@@ -0,0 +1,164 @@
 name: PR Triage
 # Two responsibilities, both pure-metadata (no PR code is checked out or run):
 #   1. On open/sync: apply size/* + risk:* labels, and needs-validation when the
 #      PR touches the front/back contract surface (backend API, SSE, agents, or
 #      the frontend streaming client). A `skip-validation` label opts out.
 #   2. On maintainer review: apply the `reviewing` label.
 #
 # All labels are managed within their own namespace — labels outside size/*,
 # risk:*, needs-validation and reviewing are never touched here.
 on:
  pull_request_target:
    types: [opened, synchronize, reopened, ready_for_review]
  pull_request_review:
    types: [submitted]
 permissions:
  contents: read
  pull-requests: write
 concurrency:
  group: pr-triage-${{ github.event.pull_request.number }}
  cancel-in-progress: false
 jobs:
  size-and-risk:
    if: github.event_name == 'pull_request_target' && github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    steps:
      - name: Label size, risk and validation need
        uses: actions/github-script@v7
        with:
          script: |
            const pr = context.payload.pull_request;
            const { owner, repo } = context.repo;
            const prNumber = pr.number;
            // ---- size, from additions + deletions ----
            const churn = (pr.additions || 0) + (pr.deletions || 0);
            const sizeLabel =
              churn < 20 ? 'size/XS' :
              churn < 100 ? 'size/S' :
              churn < 300 ? 'size/M' :
              churn < 700 ? 'size/L' : 'size/XL';
            // ---- changed paths ----
            const files = await github.paginate(github.rest.pulls.listFiles, {
              owner, repo, pull_number: prNumber, per_page: 100,
            });
            const paths = files.map(f => f.filename);
            const matches = (re) => paths.some(p => re.test(p));
            const docsOnly = paths.length > 0 && paths.every(p =>
              /\.(md|mdx|txt)$/i.test(p) || p.startsWith('docs/') ||
              /\.(png|jpe?g|gif|svg|webp|ico)$/i.test(p));
            const highRisk = matches(
              /^backend\/app\/gateway\//) || matches(
              /^backend\/packages\/harness\/deerflow\/(agents|subagents|sandbox)\//) || matches(
              /(^|\/)langgraph\.json$/) || matches(
              /(^|\/)(auth|authz|security)/i) || matches(
              /(pyproject\.toml|uv\.lock|package\.json|pnpm-lock\.yaml)$/) || matches(
              /^docker\//) || matches(
              /^\.github\/workflows\//);
            const riskLabel = docsOnly ? 'risk:low' : (highRisk ? 'risk:high' : 'risk:medium');
            // needs-validation: front/back contract surface
            const contractSurface =
              matches(/^backend\/app\/gateway\//) ||
              matches(/^backend\/packages\/harness\/deerflow\/(agents|subagents)\//) ||
              matches(/(^|\/)langgraph\.json$/) ||
              matches(/^frontend\/src\/core\/(api|threads|messages)\//);
            const current = (pr.labels || []).map(l => l.name);
            const hasSkip = current.includes('skip-validation');
            const desired = [sizeLabel, riskLabel];
            if (contractSurface && !hasSkip) desired.push('needs-validation');
            const managed = (name) =>
              name.startsWith('size/') || name.startsWith('risk:') || name === 'needs-validation';
            const toRemove = current.filter(l => managed(l) && !desired.includes(l));
            const toAdd = desired.filter(l => !current.includes(l));
            for (const name of toRemove) {
              try {
                await github.rest.issues.removeLabel({ owner, repo, issue_number: prNumber, name });
              } catch (e) {
                if (e.status !== 404) throw e;
              }
            }
            if (toAdd.length) {
              await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: toAdd });
            }
            core.info(`size=${sizeLabel} risk=${riskLabel} churn=${churn} ` +
              `validation=${desired.includes('needs-validation')} ` +
              `(+${toAdd.join(',') || '-'} / -${toRemove.join(',') || '-'})`);
  first-time:
    if: github.event_name == 'pull_request_target' && github.event.action == 'opened'
    runs-on: ubuntu-latest
    steps:
      - name: Label first-time contributors
        uses: actions/github-script@v7
        with:
          script: |
            const pr = context.payload.pull_request;
            const { owner, repo } = context.repo;
            const assoc = pr.author_association;
            const isBot = pr.user.type === 'Bot';
            core.info(`author=${pr.user.login} association=${assoc} bot=${isBot}`);
            // FIRST_TIME_CONTRIBUTOR = no prior merged commit to this repo;
            // FIRST_TIMER = no prior commit anywhere on GitHub. Either counts.
            if (isBot || !['FIRST_TIME_CONTRIBUTOR', 'FIRST_TIMER'].includes(assoc)) {
              core.info('Not a first-time contributor; skipping.');
              return;
            }
            await github.rest.issues.addLabels({
              owner, repo, issue_number: pr.number, labels: ['first-time-contributor'],
            });
            core.info(`Added first-time-contributor to #${pr.number}.`);
  reviewing:
    if: github.event_name == 'pull_request_review'
    runs-on: ubuntu-latest
    steps:
      - name: Add reviewing label for maintainer reviews
        uses: actions/github-script@v7
        with:
          script: |
            const { owner, repo } = context.repo;
            const prNumber = context.payload.pull_request.number;
            const reviewer = context.payload.review.user.login;
            const { data: perm } = await github.rest.repos.getCollaboratorPermissionLevel({
              owner, repo, username: reviewer,
            });
            if (!['admin', 'write', 'maintain'].includes(perm.permission)) {
              core.info(`Reviewer ${reviewer} (${perm.permission}) is not a maintainer; skipping.`);
              return;
            }
            const { data: labels } = await github.rest.issues.listLabelsOnIssue({
              owner, repo, issue_number: prNumber,
            });
            if (labels.some(l => l.name === 'reviewing')) {
              core.info('Already labeled reviewing; skipping.');
              return;
            }
            try {
              await github.rest.issues.addLabels({
                owner, repo, issue_number: prNumber, labels: ['reviewing'],
              });
              core.info(`Added "reviewing" (reviewer ${reviewer}).`);
            } catch (e) {
              // 403 is expected for review events on some fork PR contexts.
              if (e.status === 403) core.info('No permission to label (expected on some fork PRs).');
              else throw e;
            }
@@ -0,0 +1,108 @@
 name: Replay E2E (front-back contract)
 # Guards the front-back contract via record/replay (no API key in CI):
 #   Layer 1 — backend golden: replay a recorded trace through the real gateway,
 #             assert the SSE event sequence matches the committed golden.
 #   Layer 2 — full-stack render: real Next.js frontend + real gateway (replay
 #             model) + Chromium; assert the replayed turns render in the browser.
 # Triggered by changes on EITHER side of the contract so a backend change can no
 # longer pass without the frontend-facing checks running.
 on:
  push:
    branches: ["main"]
    paths:
      - "frontend/**"
      - "backend/app/gateway/**"
      - "backend/packages/harness/**"
      - "backend/tests/fixtures/replay/**"
      - "backend/tests/replay_provider.py"
      - "backend/tests/_replay_fixture.py"
      - "backend/tests/seed_runs_router.py"
      - "backend/tests/test_replay_golden.py"
      - "backend/scripts/run_replay_gateway.py"
      - ".github/workflows/replay-e2e.yml"
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
    paths:
      - "frontend/**"
      - "backend/app/gateway/**"
      - "backend/packages/harness/**"
      - "backend/tests/fixtures/replay/**"
      - "backend/tests/replay_provider.py"
      - "backend/tests/_replay_fixture.py"
      - "backend/tests/seed_runs_router.py"
      - "backend/tests/test_replay_golden.py"
      - "backend/scripts/run_replay_gateway.py"
      - ".github/workflows/replay-e2e.yml"
 concurrency:
  group: replay-e2e-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true
 permissions:
  contents: read
 jobs:
  backend-replay-golden:
    name: Layer 1 — backend golden (no API key)
    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v6
      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"
      - name: Install uv
        uses: astral-sh/setup-uv@v7
      - name: Install backend dependencies
        working-directory: backend
        run: uv sync --group dev
      - name: Replay golden (backend SSE contract)
        working-directory: backend
        run: PYTHONPATH=. uv run pytest tests/test_replay_golden.py -v
  fullstack-replay-render:
    name: Layer 2 — full-stack render (no API key)
    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    timeout-minutes: 25
    steps:
      - uses: actions/checkout@v6
      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"
      - name: Install uv
        uses: astral-sh/setup-uv@v7
      - name: Install backend dependencies (replay gateway)
        working-directory: backend
        run: uv sync --group dev
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "22"
      - name: Enable Corepack
        run: corepack enable
      - name: Use pinned pnpm version
        run: corepack prepare pnpm@10.26.2 --activate
      - name: Install frontend dependencies
        working-directory: frontend
        run: pnpm install --frozen-lockfile
      - name: Install Playwright Chromium
        working-directory: frontend
        run: npx playwright install chromium --with-deps
      - name: Full-stack replay render (DOM assertions are the gate)
        working-directory: frontend
        run: pnpm exec playwright test -c playwright.real-backend.config.ts
      - name: Upload report + render artifact
        uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: replay-render
          path: |
            frontend/playwright-report/
            frontend/test-results/
          retention-days: 7
@@ -287,6 +287,21 @@ Nginx (port 2026) ← Unified entry point
   git push origin feature/your-feature-name
   ```
 ## AI assistance disclosure
 DeerFlow is an AI project and we welcome AI-assisted contributions. To help
 reviewers calibrate how closely to read a change, **every pull request must
 complete the "AI assistance" section of the
 [PR template](.github/pull_request_template.md)**:
 - which tool(s) you used (or `none`),
 - how you used them, and
 - a confirmation that a human has read, understands, and takes responsibility
  for the change.
 Please don't delete the section. PRs that ignore it may be asked to fill it in
 before review.
 ## Testing
 ```bash
@@ -89,36 +89,7 @@ install:
 # Pre-pull sandbox Docker image (optional but recommended)
 setup-sandbox:
-	@echo "=========================================="
+	@$(RUN_WITH_GIT_BASH) ./scripts/setup-sandbox.sh
 	@echo "  Pre-pulling Sandbox Container Image"
 	@echo "=========================================="
 	@echo ""
 	@IMAGE=$$(grep -A 20 "# sandbox:" config.yaml 2>/dev/null | grep "image:" | awk '{print $$2}' | head -1); \
 	if [ -z "$$IMAGE" ]; then \
 		IMAGE="enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest"; \
 		echo "Using default image: $$IMAGE"; \
 	else \
 		echo "Using configured image: $$IMAGE"; \
 	fi; \
 	echo ""; \
 	if command -v container >/dev/null 2>&1 && [ "$$(uname)" = "Darwin" ]; then \
 		echo "Detected Apple Container on macOS, pulling image..."; \
 		container image pull "$$IMAGE" || echo "⚠ Apple Container pull failed, will try Docker"; \
 	fi; \
 	if command -v docker >/dev/null 2>&1; then \
 		echo "Pulling image using Docker..."; \
 		if docker pull "$$IMAGE"; then \
 			echo ""; \
 			echo "✓ Sandbox image pulled successfully"; \
 		else \
 			echo ""; \
 			echo "⚠ Failed to pull sandbox image (this is OK for local sandbox mode)"; \
 		fi; \
 	else \
 		echo "✗ Neither Docker nor Apple Container is available"; \
 		echo "  Please install Docker: https://docs.docker.com/get-docker/"; \
 		exit 1; \
 	fi
 # Start all services in development mode (with hot-reloading)
 dev:
@@ -148,7 +119,6 @@ stop:
 clean: stop
 	@echo "Cleaning up..."
 	@-rm -rf backend/.deer-flow 2>/dev/null || true
 	@-rm -rf backend/.langgraph_api 2>/dev/null || true
 	@-rm -rf logs/*.log 2>/dev/null || true
 	@echo "✓ Cleanup complete"
@@ -208,7 +208,7 @@ Lead-agent middlewares are assembled in strict append order across `packages/har
 12. **TitleMiddleware** - Auto-generates thread title after first complete exchange and normalizes structured message content before prompting the title model
 13. **MemoryMiddleware** - Queues conversations for async memory update (filters to user + final AI responses)
 14. **ViewImageMiddleware** - Injects base64 image data before LLM call (conditional on vision support)
-15. **DeferredToolFilterMiddleware** - Hides deferred tool schemas from the bound model until tool search is enabled (optional)
+15. **DeferredToolFilterMiddleware** - Hides deferred (MCP) tool schemas from the bound model using a build-time deferred-name set + catalog hash, reading per-thread promotions from `ThreadState.promoted` (hash-scoped, no ContextVar); a tool becomes bound on subsequent turns after `tool_search` returns its schema (optional, if `tool_search.enabled`)
 16. **SubagentLimitMiddleware** - Truncates excess `task` tool calls from model response to enforce `MAX_CONCURRENT_SUBAGENTS` limit (optional, if `subagent_enabled`)
 17. **LoopDetectionMiddleware** - Detects repeated tool-call loops; hard-stop responses clear both structured `tool_calls` and raw provider tool-call metadata before forcing a final text answer
 18. **ClarificationMiddleware** - Intercepts `ask_clarification` tool calls, interrupts via `Command(goto=END)` (must be last)
@@ -223,17 +223,9 @@ Setup: Copy `config.example.yaml` to `config.yaml` in the **project root** direc
 **Config Caching**: `get_app_config()` caches the parsed config, but automatically reloads it when the resolved config path changes or the file's mtime increases. This keeps Gateway and LangGraph reads aligned with `config.yaml` edits without requiring a manual process restart.
-**Config Hot-Reload Boundary**: Gateway dependencies route through `get_app_config()` on every request, so per-run fields like `models[*].max_tokens`, `summarization.*`, `title.*`, `memory.*`, `subagents.*`, `tools[*]`, and the agent system prompt pick up `config.yaml` edits on the next message. `AppConfig` is intentionally **not** cached on `app.state` — `lifespan()` keeps a local `startup_config` variable for one-shot bootstrap work (logging level, channels, `langgraph_runtime` engines) and passes it explicitly to `langgraph_runtime(app, startup_config)`. Infrastructure fields are **restart-required**:
+**Config Hot-Reload Boundary**: Gateway dependencies route through `get_app_config()` on every request, so per-run fields like `models[*].max_tokens`, `summarization.*`, `title.*`, `memory.*`, `subagents.*`, `tools[*]`, and the agent system prompt pick up `config.yaml` edits on the next message. `AppConfig` is intentionally **not** cached on `app.state` — `lifespan()` keeps a local `startup_config` variable for one-shot bootstrap work and passes it to `langgraph_runtime(app, startup_config)`.
-| Field | Why a restart is required |
+Infrastructure fields are **restart-required**. The authoritative list lives in `packages/harness/deerflow/config/reload_boundary.py::STARTUP_ONLY_FIELDS` and is mirrored by the standardised `"startup-only:"` prefix on the corresponding `Field(description=...)` in `AppConfig`, so IDE hover on those fields surfaces the reason inline (no need to context-switch into this table). Currently registered: `database`, `checkpointer`, `run_events`, `stream_bridge`, `sandbox`, `log_level`, `channels`. Adding a new restart-required field requires updating the registry; drift is pinned by `tests/test_reload_boundary.py`.
 |---|---|
 | `database.*` | `init_engine_from_config()` runs once during `langgraph_runtime()` startup; the SQLAlchemy engine holds the connection pool. |
 | `checkpointer.*` (including SQLite WAL/journal settings) | `make_checkpointer()` binds the persistent checkpointer once at startup. |
 | `run_events.*` | `make_run_event_store()` selects memory- vs. SQL-backed implementation at startup. |
 | `stream_bridge.*` | `make_stream_bridge()` constructs the bridge object once. |
 | `sandbox.use` | `get_sandbox_provider()` caches the provider singleton (`_default_sandbox_provider`); a new class path takes effect only on next process start. |
 | `log_level` | `apply_logging_level()` is called only in `app.py` startup; it mutates the root logger's level, and `get_app_config()` returning a fresh `AppConfig` does not retrigger it. |
 | `channels.*` IM platform credentials | `start_channel_service()` is invoked once during startup; live channels are not rebuilt on config change. |
 Configuration priority:
 1. Explicit `config_path` argument
@@ -271,7 +263,7 @@ CORS is same-origin by default when requests enter through nginx on port 2026. S
 | **Uploads** (`/api/threads/{id}/uploads`) | `POST /` - upload files (auto-converts PDF/PPT/Excel/Word); `GET /list` - list; `DELETE /{filename}` - delete |
 | **Threads** (`/api/threads/{id}`) | `DELETE /` - remove DeerFlow-managed local thread data after LangGraph thread deletion; unexpected failures are logged server-side and return a generic 500 detail |
 | **Artifacts** (`/api/threads/{id}/artifacts`) | `GET /{path}` - serve artifacts; active content types (`text/html`, `application/xhtml+xml`, `image/svg+xml`) are always forced as download attachments to reduce XSS risk; `?download=true` still forces download for other file types |
-| **Suggestions** (`/api/threads/{id}/suggestions`) | `POST /` - generate follow-up questions; rich list/block model content is normalized before JSON parsing |
+| **Suggestions** (`/api/threads/{id}/suggestions`) | `POST /` - generate follow-up questions; rich list/block model content is normalized and inline reasoning (`<think>...</think>`, including unclosed/truncated blocks from reasoning models like MiniMax-M3) is stripped before JSON parsing |
 | **Thread Runs** (`/api/threads/{id}/runs`) | `POST /` - create background run; `POST /stream` - create + SSE stream; `POST /wait` - create + block; `GET /` - list runs; `GET /{rid}` - run details; `POST /{rid}/cancel` - cancel; `GET /{rid}/join` - join SSE; `GET /{rid}/messages` - paginated messages `{data, has_more}`; `GET /{rid}/events` - full event stream; `GET /../messages` - thread messages with feedback; `GET /../token-usage` - aggregate tokens |
 | **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 |
@@ -313,6 +305,7 @@ Proxied through nginx: `/api/langgraph/*` → Gateway LangGraph-compatible runti
 **Concurrency**: `MAX_CONCURRENT_SUBAGENTS = 3` enforced by `SubagentLimitMiddleware` (truncates excess tool calls in `after_model`), 15-minute timeout
 **Flow**: `task()` tool → `SubagentExecutor` → background thread → poll 5s → SSE events → result
 **Events**: `task_started`, `task_running`, `task_completed`/`task_failed`/`task_timed_out`
 **Deferred MCP tools** (if `tool_search.enabled`): `SubagentExecutor._build_initial_state` assembles deferral after policy filtering via the shared `assemble_deferred_tools` (fail-closed), appends the `tool_search` tool, injects the `<available-deferred-tools>` section into the subagent's `SystemMessage`, and threads the setup to `_create_agent`, which attaches `DeferredToolFilterMiddleware` through `build_subagent_runtime_middlewares(deferred_setup=...)`. Subagents thus withhold full MCP schemas until promotion, same as the lead agent; each task run gets a fresh `ThreadState` so promotion is isolated per run
 ### Tool System (`packages/harness/deerflow/tools/`)
@@ -64,7 +64,7 @@ FROM builder AS dev
 # Install Docker CLI (for DooD: allows starting sandbox containers via host Docker socket)
 COPY --from=docker:cli /usr/local/bin/docker /usr/local/bin/docker
-EXPOSE 8001 2024
+EXPOSE 8001
 CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]
@@ -94,8 +94,8 @@ WORKDIR /app
 # Copy backend with pre-built virtualenv from builder
 COPY --from=builder /app/backend ./backend
-# Expose ports (gateway: 8001, langgraph: 2024)
+# Expose Gateway API port.
-EXPOSE 8001 2024
+EXPOSE 8001
 # Default command (can be overridden in docker-compose)
 CMD ["sh", "-c", "cd backend && PYTHONPATH=. uv run --no-sync uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001"]
@@ -7,16 +7,26 @@ import json
 import logging
 import re
 import threading
 import time
 from typing import Any, Literal
 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
+from app.channels.message_bus import (
    PENDING_CLARIFICATION_METADATA_KEY,
    RESOLVED_FROM_PENDING_CLARIFICATION_METADATA_KEY,
    InboundMessage,
    InboundMessageType,
    MessageBus,
    OutboundMessage,
    ResolvedAttachment,
 )
 from deerflow.config.paths import VIRTUAL_PATH_PREFIX, get_paths
 from deerflow.runtime.user_context import get_effective_user_id
 from deerflow.sandbox.sandbox_provider import get_sandbox_provider
 logger = logging.getLogger(__name__)
 PENDING_CLARIFICATION_TTL_SECONDS = 30 * 60
 def _is_feishu_command(text: str) -> bool:
@@ -56,6 +66,7 @@ class FeishuChannel(Channel):
        self._background_tasks: set[asyncio.Task] = set()
        self._running_card_ids: dict[str, str] = {}
        self._running_card_tasks: dict[str, asyncio.Task] = {}
        self._pending_clarifications: dict[tuple[str, str], list[dict[str, Any]]] = {}
        self._CreateFileRequest = None
        self._CreateFileRequestBody = None
        self._CreateImageRequest = None
@@ -63,6 +74,16 @@ class FeishuChannel(Channel):
        self._GetMessageResourceRequest = None
        self._thread_lock = threading.Lock()
    @staticmethod
    def _non_empty_str(value: Any) -> str | None:
        if isinstance(value, str) and value.strip():
            return value.strip()
        return None
    @staticmethod
    def _pending_key(chat_id: str, user_id: str) -> tuple[str, str]:
        return (chat_id, user_id)
    @property
    def supports_streaming(self) -> bool:
        return True
@@ -531,18 +552,25 @@ class FeishuChannel(Channel):
                        "[Feishu] failed to patch running card %s, falling back to final reply",
                        running_card_id,
                    )
-                    await self._reply_card(source_message_id, msg.text)
+                    fallback_card_id = await self._reply_card(source_message_id, msg.text)
                    self._remember_thread_mapping(msg, source_message_id, fallback_card_id)
                    self._remember_pending_clarification(msg, fallback_card_id)
                else:
                    self._remember_thread_mapping(msg, source_message_id, running_card_id)
                    self._remember_pending_clarification(msg, running_card_id)
                    logger.info("[Feishu] running card updated: source=%s card=%s", source_message_id, running_card_id)
            elif msg.is_final:
-                await self._reply_card(source_message_id, msg.text)
+                final_card_id = await self._reply_card(source_message_id, msg.text)
                self._remember_thread_mapping(msg, source_message_id, final_card_id)
                self._remember_pending_clarification(msg, final_card_id)
            elif awaited_running_card_task:
                logger.warning(
                    "[Feishu] running card task finished without message_id for source=%s, skipping duplicate non-final creation",
                    source_message_id,
                )
            else:
-                await self._ensure_running_card(source_message_id, msg.text)
+                created_card_id = await self._ensure_running_card(source_message_id, msg.text)
                self._remember_thread_mapping(msg, source_message_id, created_card_id)
            if msg.is_final:
                self._running_card_ids.pop(source_message_id, None)
@@ -553,6 +581,129 @@ class FeishuChannel(Channel):
    # -- internal ----------------------------------------------------------
    def _remember_thread_mapping(self, msg: OutboundMessage, *topic_ids: str | None) -> None:
        store = self.config.get("channel_store")
        if store is None or not msg.thread_id:
            return
        metadata_topic_ids = [
            msg.metadata.get("message_id"),
            msg.metadata.get("root_id"),
            msg.metadata.get("parent_id"),
            msg.metadata.get("thread_id"),
            msg.metadata.get("topic_id"),
        ]
        user_id = ""
        raw_user_id = msg.metadata.get("user_id")
        if isinstance(raw_user_id, str):
            user_id = raw_user_id
        seen: set[str] = set()
        for topic_id in [*topic_ids, *metadata_topic_ids]:
            topic_id = self._non_empty_str(topic_id)
            if not topic_id or topic_id in seen:
                continue
            seen.add(topic_id)
            try:
                store.set_thread_id(
                    self.name,
                    msg.chat_id,
                    msg.thread_id,
                    topic_id=topic_id,
                    user_id=user_id,
                )
            except Exception:
                logger.exception("[Feishu] failed to remember thread mapping for topic_id=%s", topic_id)
    def _remember_pending_clarification(self, msg: OutboundMessage, card_message_id: str | None) -> None:
        if not msg.is_final or msg.metadata.get(PENDING_CLARIFICATION_METADATA_KEY) is not True:
            return
        user_id = self._non_empty_str(msg.metadata.get("user_id"))
        topic_id = self._non_empty_str(msg.metadata.get("topic_id"))
        source_message_id = self._non_empty_str(msg.thread_ts) or self._non_empty_str(msg.metadata.get("message_id"))
        if not (user_id and topic_id and msg.thread_id and source_message_id and card_message_id):
            return
        key = self._pending_key(msg.chat_id, user_id)
        pending = {
            "thread_id": msg.thread_id,
            "topic_id": topic_id,
            "source_message_id": source_message_id,
            "card_message_id": card_message_id,
            "created_at": time.time(),
        }
        with self._thread_lock:
            # Plain-message clarification continuity is a short-lived in-memory
            # hint; explicit Feishu replies are still covered by persisted
            # message-id mappings.
            self._pending_clarifications.setdefault(key, []).append(pending)
        logger.info(
            "[Feishu] pending clarification remembered: chat_id=%s user_id=%s topic_id=%s thread_id=%s",
            msg.chat_id,
            user_id,
            topic_id,
            msg.thread_id,
        )
    def _consume_pending_clarification(self, chat_id: str, user_id: str) -> dict[str, Any] | None:
        key = self._pending_key(chat_id, user_id)
        with self._thread_lock:
            pending_items = self._pending_clarifications.get(key)
            if not pending_items:
                return None
            now = time.time()
            while pending_items:
                pending = pending_items.pop(0)
                created_at = pending.get("created_at")
                if isinstance(created_at, (int, float)) and now - created_at <= PENDING_CLARIFICATION_TTL_SECONDS:
                    if pending_items:
                        self._pending_clarifications[key] = pending_items
                    else:
                        self._pending_clarifications.pop(key, None)
                    return pending
                logger.info("[Feishu] pending clarification expired: chat_id=%s user_id=%s", chat_id, user_id)
            self._pending_clarifications.pop(key, None)
            return None
    def _ensure_pending_thread_mapping(self, chat_id: str, user_id: str, pending: dict[str, Any]) -> None:
        store = self.config.get("channel_store")
        topic_id = self._non_empty_str(pending.get("topic_id"))
        thread_id = self._non_empty_str(pending.get("thread_id"))
        if store is None or not topic_id or not thread_id:
            return
        try:
            store.set_thread_id(self.name, chat_id, thread_id, topic_id=topic_id, user_id=user_id)
        except Exception:
            logger.exception("[Feishu] failed to restore pending clarification mapping for topic_id=%s", topic_id)
    def _resolve_topic_id(
        self,
        chat_id: str,
        msg_id: str,
        *,
        root_id: str | None,
        parent_id: str | None,
        thread_id: str | None,
    ) -> tuple[str, bool]:
        store = self.config.get("channel_store")
        candidates = [root_id, parent_id, thread_id]
        if store is not None:
            for candidate in candidates:
                candidate = self._non_empty_str(candidate)
                if not candidate:
                    continue
                try:
                    if store.get_thread_id(self.name, chat_id, topic_id=candidate):
                        return candidate, True
                except Exception:
                    logger.exception("[Feishu] failed to resolve stored topic mapping for topic_id=%s", candidate)
        return root_id or msg_id, False
    @staticmethod
    def _log_future_error(fut, name: str, msg_id: str) -> None:
        """Callback for run_coroutine_threadsafe futures to surface errors."""
@@ -593,7 +744,9 @@ class FeishuChannel(Channel):
            # root_id is set when the message is a reply within a Feishu thread.
            # Use it as topic_id so all replies share the same DeerFlow thread.
-            root_id = getattr(message, "root_id", None) or None
+            root_id = self._non_empty_str(getattr(message, "root_id", None))
            parent_id = self._non_empty_str(getattr(message, "parent_id", None))
            feishu_thread_id = self._non_empty_str(getattr(message, "thread_id", None))
            # Parse message content
            content = json.loads(message.content)
@@ -654,10 +807,12 @@ class FeishuChannel(Channel):
            text = text.strip()
            logger.info(
-                "[Feishu] parsed message: chat_id=%s, msg_id=%s, root_id=%s, sender=%s, text=%r",
+                "[Feishu] parsed message: chat_id=%s, msg_id=%s, root_id=%s, parent_id=%s, thread_id=%s, sender=%s, text=%r",
                chat_id,
                msg_id,
                root_id,
                parent_id,
                feishu_thread_id,
                sender_id,
                text[:100] if text else "",
            )
@@ -673,8 +828,24 @@ class FeishuChannel(Channel):
            else:
                msg_type = InboundMessageType.CHAT
-            # topic_id: use root_id for replies (same topic), msg_id for new messages (new topic)
+            # Prefer any platform message id that already maps to a DeerFlow
-            topic_id = root_id or msg_id
+            # thread. This keeps replies to bot clarification cards in the
            # original conversation even when Feishu reports the card as root.
            topic_id, resolved_from_stored_mapping = self._resolve_topic_id(
                chat_id,
                msg_id,
                root_id=root_id,
                parent_id=parent_id,
                thread_id=feishu_thread_id,
            )
            resolved_from_pending = False
            if msg_type == InboundMessageType.CHAT and not resolved_from_stored_mapping:
                pending = self._consume_pending_clarification(chat_id, sender_id)
                pending_topic_id = self._non_empty_str(pending.get("topic_id")) if pending else None
                if pending_topic_id:
                    topic_id = pending_topic_id
                    self._ensure_pending_thread_mapping(chat_id, sender_id, pending)
                    resolved_from_pending = True
            inbound = self._make_inbound(
                chat_id=chat_id,
@@ -683,7 +854,15 @@ class FeishuChannel(Channel):
                msg_type=msg_type,
                thread_ts=msg_id,
                files=files_list,
-                metadata={"message_id": msg_id, "root_id": root_id},
+                metadata={
                    "message_id": msg_id,
                    "root_id": root_id,
                    "parent_id": parent_id,
                    "thread_id": feishu_thread_id,
                    "topic_id": topic_id,
                    "user_id": sender_id,
                    RESOLVED_FROM_PENDING_CLARIFICATION_METADATA_KEY: resolved_from_pending,
                },
            )
            inbound.topic_id = topic_id
@@ -15,10 +15,18 @@ import httpx
 from langgraph_sdk.errors import ConflictError
 from app.channels.commands import KNOWN_CHANNEL_COMMANDS
-from app.channels.message_bus import InboundMessage, InboundMessageType, MessageBus, OutboundMessage, ResolvedAttachment
+from app.channels.message_bus import (
    PENDING_CLARIFICATION_METADATA_KEY,
    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.config.paths import make_safe_user_id
 from deerflow.runtime.user_context import get_effective_user_id
 logger = logging.getLogger(__name__)
@@ -202,6 +210,54 @@ def _extract_response_text(result: dict | list) -> str:
    return ""
 def _messages_from_result(result: dict | list) -> list[Any]:
    if isinstance(result, list):
        return result
    if isinstance(result, dict):
        messages = result.get("messages", [])
        if isinstance(messages, list):
            return messages
    return []
 def _current_turn_messages(result: dict | list) -> list[dict[str, Any]]:
    messages = _messages_from_result(result)
    current_turn: list[dict[str, Any]] = []
    for msg in reversed(messages):
        if not isinstance(msg, dict):
            continue
        if msg.get("type") == "human":
            break
        current_turn.append(msg)
    current_turn.reverse()
    return current_turn
 def _has_current_turn_clarification(result: dict | list) -> bool:
    """Return True only when the current turn's final result is clarification."""
    for msg in reversed(_current_turn_messages(result)):
        msg_type = msg.get("type")
        if msg_type == "tool":
            return msg.get("name") == "ask_clarification"
        if msg_type == "ai":
            content = msg.get("content")
            if isinstance(content, str):
                if content:
                    return False
            elif content:
                return False
            if msg.get("tool_calls"):
                return False
    return False
 def _response_metadata(base_metadata: dict[str, Any], *, pending_clarification: bool = False) -> dict[str, Any]:
    metadata = _slim_metadata(base_metadata)
    if pending_clarification:
        metadata[PENDING_CLARIFICATION_METADATA_KEY] = True
    return metadata
 def _extract_text_content(content: Any) -> str:
    """Extract text from a streaming payload content field."""
    if isinstance(content, str):
@@ -615,12 +671,20 @@ class ChannelManager:
        configurable["checkpoint_ns"] = ""
        configurable["thread_id"] = thread_id
        # ``user_id`` drives user-scoped filesystem buckets that only accept
        # ``[A-Za-z0-9_-]``, so normalize the channel id and keep the raw value
        # under ``channel_user_id`` for platform-facing lookups.
        run_context_identity: dict[str, Any] = {"thread_id": thread_id}
        if msg.user_id:
            run_context_identity["user_id"] = make_safe_user_id(msg.user_id)
            run_context_identity["channel_user_id"] = msg.user_id
        run_context = _merge_dicts(
            DEFAULT_RUN_CONTEXT,
            self._default_session.get("context"),
            channel_layer.get("context"),
            user_layer.get("context"),
-            {"thread_id": thread_id},
+            run_context_identity,
        )
        # Custom agents are implemented as lead_agent + agent_name context.
@@ -806,6 +870,7 @@ class ChannelManager:
                raise
        response_text = _extract_response_text(result)
        pending_clarification = _has_current_turn_clarification(result)
        artifacts = _extract_artifacts(result)
        logger.info(
@@ -831,7 +896,7 @@ class ChannelManager:
            artifacts=artifacts,
            attachments=attachments,
            thread_ts=msg.thread_ts,
-            metadata=_slim_metadata(msg.metadata),
+            metadata=_response_metadata(msg.metadata, pending_clarification=pending_clarification),
        )
        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)
@@ -893,7 +958,7 @@ class ChannelManager:
                        text=latest_text,
                        is_final=False,
                        thread_ts=msg.thread_ts,
-                        metadata=_slim_metadata(msg.metadata),
+                        metadata=_response_metadata(msg.metadata),
                    )
                )
                last_published_text = latest_text
@@ -907,6 +972,7 @@ class ChannelManager:
        finally:
            result = last_values if last_values is not None else {"messages": [{"type": "ai", "content": latest_text}]}
            response_text = _extract_response_text(result)
            pending_clarification = _has_current_turn_clarification(result)
            artifacts = _extract_artifacts(result)
            response_text, attachments = _prepare_artifact_delivery(thread_id, response_text, artifacts)
@@ -938,7 +1004,7 @@ class ChannelManager:
                    attachments=attachments,
                    is_final=True,
                    thread_ts=msg.thread_ts,
-                    metadata=_slim_metadata(msg.metadata),
+                    metadata=_response_metadata(msg.metadata, pending_clarification=pending_clarification),
                )
            )
@@ -13,6 +13,9 @@ from typing import Any
 logger = logging.getLogger(__name__)
 PENDING_CLARIFICATION_METADATA_KEY = "pending_clarification"
 RESOLVED_FROM_PENDING_CLARIFICATION_METADATA_KEY = "resolved_from_pending_clarification"
 # ---------------------------------------------------------------------------
 # Message types
@@ -179,6 +179,25 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
    config = get_gateway_config()
    logger.info(f"Starting API Gateway on {config.host}:{config.port}")
    # Pre-warm tiktoken encoding cache so the first memory-injection request
    # never blocks on the BPE data download (which hits an OpenAI/Azure URL
    # that may be unreachable in restricted networks — see issue #3402).
    try:
        from deerflow.agents.memory.prompt import warm_tiktoken_cache
        warmed = await asyncio.wait_for(
            asyncio.to_thread(warm_tiktoken_cache),
            timeout=5,
        )
        if warmed:
            logger.info("tiktoken encoding cache warmed successfully")
        else:
            logger.warning("tiktoken encoding cache warm-up failed; token counting will use character-based fallback")
    except TimeoutError:
        logger.warning("tiktoken encoding cache warm-up timed out; token counting will use character-based fallback")
    except Exception:
        logger.warning("tiktoken warm-up skipped", exc_info=True)
    # Initialize LangGraph runtime components (StreamBridge, RunManager, checkpointer, store)
    async with langgraph_runtime(app, startup_config):
        logger.info("LangGraph runtime initialised")
@@ -17,6 +17,7 @@ Initialization is handled directly in ``app.py`` via :class:`AsyncExitStack`.
 from __future__ import annotations
 import asyncio
 import logging
 from collections.abc import AsyncGenerator, Callable
 from contextlib import AsyncExitStack, asynccontextmanager
@@ -33,6 +34,43 @@ from deerflow.runtime.runs.store.base import RunStore
 logger = logging.getLogger(__name__)
 # Upper bound (seconds) for draining in-flight runs during shutdown, before the
 # AsyncExitStack tears down the checkpointer (and its connection pool). Kept
 # local to avoid an app -> deps -> app import cycle. This is a *separate* budget
 # from ``app.gateway.app._SHUTDOWN_HOOK_TIMEOUT_SECONDS`` (currently also 5.0s,
 # which bounds channel-service stop): the two govern independent teardown steps
 # and may diverge, but both count toward the lifespan shutdown window — revisit
 # them together if their sum must stay within the server's graceful-shutdown
 # timeout.
 _RUN_DRAIN_TIMEOUT_SECONDS = 5.0
 async def _drain_inflight_runs(run_manager: RunManager) -> None:
    """Drain in-flight runs before the checkpointer is torn down (issue #3373).
    Shields the (internally-bounded) drain so that even if the lifespan
    coroutine is itself cancelled mid-shutdown — a second SIGINT or the server's
    graceful-shutdown timeout, i.e. the same signal storm behind #3373 — the
    checkpointer pool is not closed while run tasks are still writing
    checkpoints. On such a cancellation we let the already-running drain finish
    (it is bounded by ``RunManager.shutdown``'s own timeout) and then propagate
    the cancellation.
    """
    drain = asyncio.create_task(run_manager.shutdown(timeout=_RUN_DRAIN_TIMEOUT_SECONDS))
    try:
        await asyncio.shield(drain)
    except asyncio.CancelledError:
        # Re-shield so this second wait does not abandon the in-flight drain;
        # it is bounded, so this cannot hang. Then re-raise to honour shutdown.
        try:
            await asyncio.shield(drain)
        except Exception:
            logger.exception("In-flight run drain failed after shutdown cancellation")
        raise
    except Exception:
        logger.exception("Failed to drain in-flight runs during shutdown")
 if TYPE_CHECKING:
    from app.gateway.auth.local_provider import LocalAuthProvider
    from app.gateway.auth.repositories.sqlite import SQLiteUserRepository
@@ -81,6 +119,16 @@ def get_config() -> AppConfig:
    split-brain where the worker / lead-agent thread saw a stale startup
    snapshot.
    Hot-reload boundary: fields backed by startup-time singletons
    (engines, sandbox provider, IM channels, logging handler) require a
    process restart to change at runtime. The authoritative list lives in
    :mod:`deerflow.config.reload_boundary` and is mirrored by the
    standardised ``"startup-only:"`` prefix on the matching
    ``Field(description=...)`` in :class:`AppConfig` — IDE hover on those
    fields will surface the boundary inline. See
    ``backend/CLAUDE.md`` "Config Hot-Reload Boundary" for the operator
    summary.
    Any failure to materialise the config (missing file, permission denied,
    YAML parse error, validation error) is reported as 503 — semantically
    "the gateway cannot serve requests without a usable configuration" — and
@@ -177,6 +225,14 @@ async def langgraph_runtime(app: FastAPI, startup_config: AppConfig) -> AsyncGen
        try:
            yield
        finally:
            # Drain in-flight run tasks BEFORE the AsyncExitStack tears down the
            # checkpointer (and its connection pool). A run still mid-graph would
            # otherwise leak into asyncio.run() shutdown, where langgraph's
            # _checkpointer_put_after_previous aput races the closed pool and
            # raises PoolClosed (issue #3373).
            run_manager = getattr(app.state, "run_manager", None)
            if run_manager is not None:
                await _drain_inflight_runs(run_manager)
            await close_engine()
@@ -10,6 +10,7 @@ from deerflow.runtime.user_context import DEFAULT_USER_ID
 INTERNAL_AUTH_HEADER_NAME = "X-DeerFlow-Internal-Token"
 INTERNAL_AUTH_ENV_VAR = "DEER_FLOW_INTERNAL_AUTH_TOKEN"
 INTERNAL_SYSTEM_ROLE = "internal"
 def _load_internal_auth_token() -> str:
@@ -34,4 +35,4 @@ def is_valid_internal_auth_token(token: str | None) -> bool:
 def get_internal_user():
    """Return the synthetic user used for trusted internal channel calls."""
-    return SimpleNamespace(id=DEFAULT_USER_ID, system_role="internal")
+    return SimpleNamespace(id=DEFAULT_USER_ID, system_role=INTERNAL_SYSTEM_ROLE)
@@ -0,0 +1,15 @@
 """Shared pagination helpers for gateway routers."""
 from __future__ import annotations
 def trim_run_message_page(rows: list[dict], *, limit: int, after_seq: int | None) -> tuple[list[dict], bool]:
    """Trim a ``limit + 1`` run-message page while preserving page boundaries."""
    has_more = len(rows) > limit
    if not has_more:
        return rows, False
    if after_seq is not None:
        return rows[:limit], True
    return rows[-limit:], True
@@ -1,9 +1,10 @@
 import json
 import logging
 import os
 from pathlib import Path
 from typing import Literal
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, HTTPException, Request, status
 from pydantic import BaseModel, Field
 from deerflow.config.extensions_config import ExtensionsConfig, get_extensions_config, reload_extensions_config
@@ -12,6 +13,11 @@ logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api", tags=["mcp"])
 _MCP_STDIO_COMMAND_ALLOWLIST_ENV = "DEER_FLOW_MCP_STDIO_COMMAND_ALLOWLIST"
 _DEFAULT_MCP_STDIO_COMMAND_ALLOWLIST = frozenset({"npx", "uvx"})
 _SHELL_METACHARS = frozenset(";|&`$<>\n\r")
 class McpOAuthConfigResponse(BaseModel):
    """OAuth configuration for an MCP server."""
@@ -66,6 +72,78 @@ class McpConfigUpdateRequest(BaseModel):
 _MASKED_VALUE = "***"
 async def _require_admin_user(request: Request) -> None:
    """Require the authenticated caller to be an admin user.
    ``AuthMiddleware`` normally stamps ``request.state.user`` before the
    request reaches this router. Falling back to the strict dependency keeps
    this route safe even in tests or alternative ASGI compositions that mount
    the router without the global middleware.
    """
    user = getattr(request.state, "user", None)
    if user is None:
        from app.gateway.deps import get_current_user_from_request
        user = await get_current_user_from_request(request)
    if getattr(user, "system_role", None) != "admin":
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Admin privileges required to manage MCP configuration.",
        )
 def _allowed_stdio_commands() -> set[str]:
    """Return executable names allowed for API-managed stdio MCP servers."""
    raw = os.environ.get(_MCP_STDIO_COMMAND_ALLOWLIST_ENV)
    base = set(_DEFAULT_MCP_STDIO_COMMAND_ALLOWLIST)
    if raw is None:
        return base
    extra = {item.strip() for item in raw.split(",") if item.strip()}
    return base | extra
 def _stdio_command_name(command: str | None, *, server_name: str) -> str:
    """Normalize and validate a stdio command field from the API boundary."""
    if command is None or not command.strip():
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail=f"MCP server '{server_name}' with stdio transport requires a command.",
        )
    stripped = command.strip()
    has_path_separator = "/" in stripped or "\\" in stripped
    if stripped != command or has_path_separator or any(ch.isspace() for ch in stripped) or any(ch in stripped for ch in _SHELL_METACHARS):
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail=(f"MCP server '{server_name}' command must be a single executable name; put parameters in args instead."),
        )
    return stripped
 def _validate_mcp_update_request(request: McpConfigUpdateRequest) -> None:
    """Validate API-submitted MCP config before it is persisted.
    Local config files can still express arbitrary advanced setups, but the
    HTTP API is an untrusted boundary. Restricting stdio commands here reduces
    the blast radius of a compromised authenticated browser session.
    """
    allowed_commands = _allowed_stdio_commands()
    for name, server in request.mcp_servers.items():
        transport_type = (server.type or "stdio").lower()
        if transport_type != "stdio":
            continue
        command_name = _stdio_command_name(server.command, server_name=name)
        if command_name not in allowed_commands:
            allowed = ", ".join(sorted(allowed_commands)) or "<none>"
            raise HTTPException(
                status_code=status.HTTP_400_BAD_REQUEST,
                detail=(f"MCP server '{name}' uses disallowed stdio command '{command_name}'. Allowed commands: {allowed}. Configure {_MCP_STDIO_COMMAND_ALLOWLIST_ENV} to extend this list."),
            )
 def _mask_server_config(server: McpServerConfigResponse) -> McpServerConfigResponse:
    """Return a copy of server config with sensitive fields masked.
@@ -162,7 +240,7 @@ def _merge_preserving_secrets(
    summary="Get MCP Configuration",
    description="Retrieve the current Model Context Protocol (MCP) server configurations.",
 )
-async def get_mcp_configuration() -> McpConfigResponse:
+async def get_mcp_configuration(request: Request) -> McpConfigResponse:
    """Get the current MCP configuration.
    Returns:
@@ -183,6 +261,8 @@ async def get_mcp_configuration() -> McpConfigResponse:
        }
        ```
    """
    await _require_admin_user(request)
    config = get_extensions_config()
    servers = {name: _mask_server_config(McpServerConfigResponse(**server.model_dump())) for name, server in config.mcp_servers.items()}
@@ -195,7 +275,7 @@ async def get_mcp_configuration() -> McpConfigResponse:
    summary="Update MCP Configuration",
    description="Update Model Context Protocol (MCP) server configurations and save to file.",
 )
-async def update_mcp_configuration(request: McpConfigUpdateRequest) -> McpConfigResponse:
+async def update_mcp_configuration(request: Request, body: McpConfigUpdateRequest) -> McpConfigResponse:
    """Update the MCP configuration.
    This will:
@@ -228,6 +308,9 @@ async def update_mcp_configuration(request: McpConfigUpdateRequest) -> McpConfig
        ```
    """
    try:
        await _require_admin_user(request)
        _validate_mcp_update_request(body)
        # Get the current config path (or determine where to save it)
        config_path = ExtensionsConfig.resolve_config_path()
@@ -255,7 +338,7 @@ async def update_mcp_configuration(request: McpConfigUpdateRequest) -> McpConfig
        # Merge incoming server configs with raw on-disk secrets
        merged_servers: dict[str, McpServerConfigResponse] = {}
-        for name, incoming in request.mcp_servers.items():
+        for name, incoming in body.mcp_servers.items():
            raw_server = raw_servers.get(name)
            if raw_server is not None:
                merged_servers[name] = _merge_preserving_secrets(
@@ -283,6 +366,8 @@ async def update_mcp_configuration(request: McpConfigUpdateRequest) -> McpConfig
        servers = {name: _mask_server_config(McpServerConfigResponse(**server.model_dump())) for name, server in reloaded_config.mcp_servers.items()}
        return McpConfigResponse(mcp_servers=servers)
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Failed to update MCP configuration: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to update MCP configuration: {str(e)}")
@@ -15,6 +15,7 @@ from fastapi.responses import StreamingResponse
 from app.gateway.authz import require_permission
 from app.gateway.deps import get_checkpointer, get_feedback_repo, get_run_event_store, get_run_manager, get_run_store, get_stream_bridge
 from app.gateway.pagination import trim_run_message_page
 from app.gateway.routers.thread_runs import RunCreateRequest
 from app.gateway.services import sse_consumer, start_run, wait_for_run_completion
 from deerflow.runtime import serialize_channel_values
@@ -129,8 +130,7 @@ async def run_messages(
        before_seq=before_seq,
        after_seq=after_seq,
    )
-    has_more = len(rows) > limit
+    data, has_more = trim_run_message_page(rows, limit=limit, after_seq=after_seq)
    data = rows[:limit] if has_more else rows
    return {"data": data, "has_more": has_more}
@@ -1,5 +1,6 @@
 import json
 import logging
 import re
 from fastapi import APIRouter, Depends, Request
 from langchain_core.messages import HumanMessage, SystemMessage
@@ -30,6 +31,31 @@ class SuggestionsResponse(BaseModel):
    suggestions: list[str] = Field(default_factory=list, description="Suggested follow-up questions")
 # Matches a complete <think>...</think> block (case-insensitive, spans newlines).
 _THINK_BLOCK_RE = re.compile(r"<think\b[^>]*>.*?</think\s*>", re.IGNORECASE | re.DOTALL)
 # Matches a dangling, unclosed <think> (model truncated at max_tokens mid-thought).
 _OPEN_THINK_RE = re.compile(r"<think\b[^>]*>", re.IGNORECASE)
 def _strip_think_blocks(text: str) -> str:
    """Remove reasoning-model ``<think>...</think>`` blocks from the response.
    Reasoning models such as MiniMax-M3 inline their chain-of-thought into the
    message ``content`` wrapped in ``<think>...</think>`` (``reasoning_split``
    defaults to false), rather than exposing a separate ``reasoning_content``
    field. The thinking text frequently contains ``[`` / ``]`` characters, which
    corrupted the downstream ``find('[')`` / ``rfind(']')`` JSON extraction and
    produced empty suggestions. We strip the reasoning before parsing so only
    the actual answer remains.
    """
    text = _THINK_BLOCK_RE.sub("", text)
    # Drop any unclosed <think> (and everything after it) left by truncation.
    open_match = _OPEN_THINK_RE.search(text)
    if open_match:
        text = text[: open_match.start()]
    return text.strip()
 def _strip_markdown_code_fence(text: str) -> str:
    stripped = text.strip()
    if not stripped.startswith("```"):
@@ -41,7 +67,8 @@ def _strip_markdown_code_fence(text: str) -> str:
 def _parse_json_string_list(text: str) -> list[str] | None:
-    candidate = _strip_markdown_code_fence(text)
+    candidate = _strip_think_blocks(text)
    candidate = _strip_markdown_code_fence(candidate)
    start = candidate.find("[")
    end = candidate.rfind("]")
    if start == -1 or end == -1 or end <= start:
@@ -21,6 +21,7 @@ from pydantic import BaseModel, Field
 from app.gateway.authz import require_permission
 from app.gateway.deps import get_checkpointer, get_current_user, get_feedback_repo, get_run_event_store, get_run_manager, get_run_store, get_stream_bridge
 from app.gateway.pagination import trim_run_message_page
 from app.gateway.services import sse_consumer, start_run, wait_for_run_completion
 from deerflow.runtime import RunRecord, RunStatus, serialize_channel_values
@@ -402,8 +403,7 @@ async def list_run_messages(
        before_seq=before_seq,
        after_seq=after_seq,
    )
-    has_more = len(rows) > limit
+    data, has_more = trim_run_message_page(rows, limit=limit, after_seq=after_seq)
    data = rows[:limit] if has_more else rows
    return {"data": data, "has_more": has_more}
@@ -17,7 +17,7 @@ import uuid
 from typing import Any
 from fastapi import APIRouter, HTTPException, Request
-from langgraph.checkpoint.base import empty_checkpoint
+from langgraph.checkpoint.base import empty_checkpoint, uuid6
 from pydantic import BaseModel, Field, field_validator
 from app.gateway.authz import require_permission
@@ -536,9 +536,21 @@ async def update_thread_state(thread_id: str, body: ThreadStateUpdateRequest, re
        metadata["step"] = metadata.get("step", 0) + 1
        metadata["writes"] = {body.as_node: body.values}
    # Assign a new checkpoint ID so aput performs an INSERT rather than an
    # in-place REPLACE of the existing row.  Use uuid6 (time-ordered) rather
    # than uuid4 (random) so the new ID is always lexicographically greater
    # than the previous one — LangGraph's checkpointers determine the "latest"
    # checkpoint by max(checkpoint_ids) string order, matching the uuid6 epoch.
    checkpoint["id"] = str(uuid6())
    # aput requires checkpoint_ns in the config — use the same config used for the
-    # read (which always includes checkpoint_ns="").  Do NOT include checkpoint_id
+    # read (which always includes checkpoint_ns=""). The fresh checkpoint ID is
-    # so that aput generates a fresh checkpoint ID for the new snapshot.
+    # assigned above via checkpoint["id"]; keep checkpoint_id out of the config so
    # the write is keyed by the new checkpoint payload rather than the prior read.
    # All supported savers (InMemorySaver, AsyncSqliteSaver, AsyncPostgresSaver)
    # persist and echo back checkpoint["id"] verbatim — none mint their own — so
    # the new_config below carries the uuid6 we assigned here. (Regression-locked
    # by test_update_thread_state_inserts_new_checkpoint_each_call.)
    write_config: dict[str, Any] = {
        "configurable": {
            "thread_id": thread_id,
@@ -557,7 +569,7 @@ async def update_thread_state(thread_id: str, body: ThreadStateUpdateRequest, re
    # Sync title changes through the ThreadMetaStore abstraction so /threads/search
    # reflects them immediately in both sqlite and memory backends.
-    if body.values and "title" in body.values:
+    if thread_store and body.values and "title" in body.values:
        new_title = body.values["title"]
        if new_title:  # Skip empty strings and None
            try:
@@ -39,15 +39,39 @@ DEFAULT_MAX_FILE_SIZE = 50 * 1024 * 1024
 DEFAULT_MAX_TOTAL_SIZE = 100 * 1024 * 1024
 class UploadedFileInfo(BaseModel):
    """Uploaded file metadata exposed by upload and list APIs."""
    filename: str
    size: int
    path: str
    virtual_path: str
    artifact_url: str
    extension: str | None = None
    modified: float | None = None
    original_filename: str | None = None
    markdown_file: str | None = None
    markdown_path: str | None = None
    markdown_virtual_path: str | None = None
    markdown_artifact_url: str | None = None
 class UploadResponse(BaseModel):
    """Response model for file upload."""
    success: bool
-    files: list[dict[str, str]]
+    files: list[UploadedFileInfo]
    message: str
    skipped_files: list[str] = Field(default_factory=list)
 class UploadListResponse(BaseModel):
    """Response model for uploaded file listing."""
    files: list[UploadedFileInfo]
    count: int
 class UploadLimits(BaseModel):
    """Application-level upload limits exposed to clients."""
@@ -256,7 +280,7 @@ async def upload_files(
            file_info = {
                "filename": safe_filename,
-                "size": str(file_size),
+                "size": file_size,
                "path": str(sandbox_uploads / safe_filename),
                "virtual_path": virtual_path,
                "artifact_url": upload_artifact_url(thread_id, safe_filename),
@@ -333,9 +357,9 @@ async def get_upload_limits(
    return _get_upload_limits(config)
-@router.get("/list", response_model=dict)
+@router.get("/list", response_model=UploadListResponse)
@require_permission("threads", "read", owner_check=True)
-async def list_uploaded_files(thread_id: str, request: Request) -> dict:
+async def list_uploaded_files(thread_id: str, request: Request) -> UploadListResponse:
    """List all files in a thread's uploads directory."""
    try:
        uploads_dir = get_uploads_dir(thread_id)
@@ -349,7 +373,7 @@ async def list_uploaded_files(thread_id: str, request: Request) -> dict:
    for f in result["files"]:
        f["path"] = str(sandbox_uploads / f["filename"])
-    return result
+    return UploadListResponse(**result)
@router.delete("/{filename}")
@@ -19,6 +19,7 @@ from langchain_core.messages import BaseMessage
 from langchain_core.messages.utils import convert_to_messages
 from app.gateway.deps import get_run_context, get_run_manager, get_stream_bridge
 from app.gateway.internal_auth import INTERNAL_SYSTEM_ROLE
 from app.gateway.utils import sanitize_log_param
 from deerflow.config.app_config import get_app_config
 from deerflow.runtime import (
@@ -140,7 +141,14 @@ def merge_run_context_overrides(config: dict[str, Any], context: Mapping[str, An
    """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)."""
+    see issue #2677).
    ``user_id`` is intentionally propagated into ``config['context']`` in addition to
    the whitelisted keys, so non-web callers (e.g. IM channels) that supply identity in
    ``body.context`` keep it on ``ToolRuntime.context``. It is merged with
    ``setdefault`` so a server-authenticated id stamped by
    :func:`inject_authenticated_user_context` always wins over the client-supplied one.
    """
    if not context:
        return
    configurable = config.setdefault("configurable", {})
@@ -151,6 +159,8 @@ def merge_run_context_overrides(config: dict[str, Any], context: Mapping[str, An
                configurable.setdefault(key, context[key])
            if isinstance(runtime_context, dict):
                runtime_context.setdefault(key, context[key])
    if "user_id" in context and isinstance(runtime_context, dict):
        runtime_context.setdefault("user_id", context["user_id"])
 def inject_authenticated_user_context(config: dict[str, Any], request: Request) -> None:
@@ -166,6 +176,9 @@ def inject_authenticated_user_context(config: dict[str, Any], request: Request)
    if user_id is None:
        return
    if getattr(user, "system_role", None) == INTERNAL_SYSTEM_ROLE:
        return
    runtime_context = config.setdefault("context", {})
    if isinstance(runtime_context, dict):
        runtime_context["user_id"] = str(user_id)
@@ -228,10 +228,13 @@ Get current MCP server configurations.
 GET /api/mcp/config
 ```
 Requires an authenticated admin session. Sensitive env/header/OAuth secret
 values are masked in the response.
 **Response:**
 ```json
 {
-  "mcpServers": {
+  "mcp_servers": {
    "github": {
      "enabled": true,
      "type": "stdio",
@@ -255,10 +258,15 @@ PUT /api/mcp/config
 Content-Type: application/json
 ```
 Requires an authenticated admin session. API-managed `stdio` MCP servers may
 only use allowed executable names for `command` (default: `npx`, `uvx`). Set
 `DEER_FLOW_MCP_STDIO_COMMAND_ALLOWLIST` to a comma-separated list when a
 deployment needs additional trusted launchers.
 **Request Body:**
 ```json
 {
-  "mcpServers": {
+  "mcp_servers": {
    "github": {
      "enabled": true,
      "type": "stdio",
@@ -276,8 +284,18 @@ Content-Type: application/json
 **Response:**
 ```json
 {
-  "success": true,
+  "mcp_servers": {
-  "message": "MCP configuration updated"
+    "github": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "***"
      },
      "description": "GitHub operations"
    }
  }
 }
 ```
@@ -29,7 +29,7 @@ All other test plan sections were executed against either:
 | 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 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` |
+| TC-DOCKER-06 | Docker deploy uses Gateway embedded runtime | `./scripts/deploy.sh` produces a Gateway + frontend + nginx topology (no `langgraph` container); same auth flow as local `make dev` | needs `docker compose up` |
 ## Coverage already provided by non-Docker tests
@@ -43,7 +43,7 @@ the test cases that ran on sg_dev or local:
 | 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 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 |
+| TC-DOCKER-06 (Gateway embedded runtime container) | Section 七 7.2 covered by TC-GW-01..05 + Section 二 (Gateway auth flow on sg_dev) — same Gateway code, container is just a packaging change |
 ## Reproduction steps when Docker becomes available
@@ -124,8 +124,8 @@ python -c "import secrets; print(secrets.token_urlsafe(32))"
 ## 兼容性
- **标准模式**（`make dev`）：完全兼容；无 admin 时访问 `/setup` 初始化
+- **本地开发**（`make dev`）：Gateway embedded runtime 完全兼容；无 admin 时访问 `/setup` 初始化
- **Gateway 模式**（`make dev-pro`）：完全兼容
+- **Gateway embedded runtime**：标准脚本、Docker dev 和生产部署均通过 Gateway 提供认证与 LangGraph-compatible API
 - **Docker 部署**：完全兼容，`.deer-flow/data/deerflow.db` 需持久化卷挂载
 - **IM 渠道**（Feishu/Slack/Telegram）：通过 Gateway 内部认证通信，使用 `default` 用户桶
 - **DeerFlowClient**（嵌入式）：不经过 HTTP，不受认证影响
@@ -95,25 +95,35 @@ models:
        thinking:
          type: enabled
-  - name: minimax-m2.5
+  - name: minimax-m3
-    display_name: MiniMax M2.5
+    display_name: MiniMax M3
    use: langchain_openai:ChatOpenAI
-    model: MiniMax-M2.5
+    model: MiniMax-M3
    api_key: $MINIMAX_API_KEY
    base_url: https://api.minimax.io/v1
    max_tokens: 4096
    temperature: 1.0  # MiniMax requires temperature in (0.0, 1.0]
    supports_vision: true
-  - name: minimax-m2.5-highspeed
+  - name: minimax-m2.7
-    display_name: MiniMax M2.5 Highspeed
+    display_name: MiniMax M2.7
    use: langchain_openai:ChatOpenAI
-    model: MiniMax-M2.5-highspeed
+    model: MiniMax-M2.7
    api_key: $MINIMAX_API_KEY
    base_url: https://api.minimax.io/v1
    max_tokens: 4096
    temperature: 1.0  # MiniMax requires temperature in (0.0, 1.0]
-    supports_vision: true
+    supports_vision: false  # M2.7 is text-only; M3 supports vision
  - name: minimax-m2.7-highspeed
    display_name: MiniMax M2.7 Highspeed
    use: langchain_openai:ChatOpenAI
    model: MiniMax-M2.7-highspeed
    api_key: $MINIMAX_API_KEY
    base_url: https://api.minimax.io/v1
    max_tokens: 4096
    temperature: 1.0  # MiniMax requires temperature in (0.0, 1.0]
    supports_vision: false  # M2.7 is text-only; M3 supports vision
  - name: openrouter-gemini-2.5-flash
    display_name: Gemini 2.5 Flash (OpenRouter)
    use: langchain_openai:ChatOpenAI
@@ -19,6 +19,7 @@ This directory contains detailed documentation for the DeerFlow backend.
 | [STREAMING.md](STREAMING.md) | Token-level streaming design: Gateway vs DeerFlowClient paths, `stream_mode` semantics, per-id dedup |
 | [FILE_UPLOAD.md](FILE_UPLOAD.md) | File upload functionality |
 | [PATH_EXAMPLES.md](PATH_EXAMPLES.md) | Path types and usage examples |
 | [SANDBOX_MEMORY_PROFILING.md](SANDBOX_MEMORY_PROFILING.md) | Sandbox memory baseline and runtime comparison guide |
 | [summarization.md](summarization.md) | Context summarization feature |
 | [plan_mode_usage.md](plan_mode_usage.md) | Plan mode with TodoList |
 | [AUTO_TITLE_GENERATION.md](AUTO_TITLE_GENERATION.md) | Automatic title generation |
@@ -0,0 +1,116 @@
 # Record/Replay E2E — front-back contract verification
 Deterministic, **key-free** end-to-end checks that a backend change can't
 silently break the frontend (and vice-versa). Two complementary layers, fed by a
 single recording.
 ## Why
 The mock-based frontend e2e hand-writes the backend's JSON/SSE, so a backend
 schema or SSE change passes green ("fake green"). These layers replay a recorded
 **real** run against the **real** backend (and, for Layer 2, the real frontend),
 so contract drift turns the build red instead.
 ## The two layers
 - **Layer 1 — backend golden** (`tests/test_replay_golden.py`): replays a fixture
  through the real FastAPI gateway with `ReplayChatModel` and asserts the streamed
  SSE event sequence equals a committed golden. Fast, no browser. Guards protocol
  *shape*.
 - **Layer 2 — full-stack render** (`frontend/tests/e2e-real-backend/`): real
  Next.js + real gateway (replay model) + Chromium; asserts the replayed
  auto-title and a follow-up suggestion render in the browser. Guards semantic
  *render*. (Complementary to Layer 1 — neither subsumes the other.)
 Layer 2 also hosts **cross-stack contract scenarios** — the dangerous class
 where a backend change silently breaks a frontend assumption and *both sides'
 unit tests stay green*. See below.
 ## Cross-stack scenario: multi-run render order (`multi-run-order.spec.ts`)
 Regression guard for issue **#3352** (after context compression, refreshing a
 thread rendered history out of order). Root cause was a front-back desync:
 backend `RunManager.list_by_thread` returns runs **newest-first** (PR #2932),
 while the frontend (`core/threads/hooks.ts`) iterated runs and **prepended** each
 loaded page — inverting chronological order once the checkpoint no longer held
 the older messages. The backend ordering test was green throughout, and the
 frontend regression unit test hardcodes "backend returns newest-first" in a mock,
 so only a *real frontend against a real backend* catches the desync.
 This scenario does **not** record a conversation. It uses a **test-only seeder**
 (`tests/seed_runs_router.py`, mounted on the replay gateway only when
 `DEERFLOW_ENABLE_TEST_SEED=1`) to stand up a thread with ≥2 runs and per-run
 message events — and deliberately **no checkpoint**, which is the #3352
 precondition: it forces the frontend's per-run reload path to be the sole source
 of truth so the ordering bug becomes observable. The seeder writes through the
 gateway's own run/event stores using the request's auth context, so the real
 `list_by_thread` → `/runs/{id}/messages` → prepend path runs live. Reverting the
 #3354 frontend fix turns this spec red.
 ## How replay works
 `tests/replay_provider.py::ReplayChatModel` returns recorded assistant turns keyed
 by a **normalized hash of the conversation** (human / ai / tool messages — role,
 text, tool-call name+args; with `<system-reminder>`, dates, UUIDs, tmp paths
 stripped). A miss raises loudly rather than passing silently.
 **The system prompt is excluded from the match key.** The lead-agent system
 prompt is a living, frequently-edited implementation detail — its wording changes
 across PRs (e.g. #3195 added a "File Editing Workflow" section). Hashing it would
 make every fixture go stale and red-fail unrelated PRs the moment anyone edits the
 prompt. The conversation flow (user input → tool calls → results → answer) is the
 stable contract that identifies a recorded turn. (This mirrors how open-design's
 mock picker keys on the user prompt, not the system internals.) Combined with
 pinning skills + extensions empty and disabling memory/summarization
 (`tests/_replay_fixture.py::build_config_yaml`), a fixture replays the same across
 machines, days, prompt edits, and CI. Replaying needs **no API key**.
 A swallowed hash-miss keeps the SSE *event shapes* identical (the gateway wraps it
 into a normal assistant error message), so the Layer-1 golden can't catch a miss
 by shape alone — it inspects `replay_provider.replay_misses()` and fails loud
 instead. Layer-2 already fails on a miss (the recorded turns never render).
 ## Record a new scenario (needs a real key — dev machine only)
 Recording drives the **real frontend** so captured inputs match exactly what the
 browser sends; fixtures contain no API key.
 ```bash
 # 1. drive the real frontend against a real-model gateway, capturing model calls
 OPENAI_API_KEY=... OPENAI_API_BASE=<openai-compatible-endpoint>/v1 \
  DEERFLOW_RECORD_OUT=/tmp/rec/turns.jsonl RECORD_MODEL=<model> \
  bash -c 'cd frontend && pnpm exec playwright test -c playwright.record.config.ts'
 # 2. stitch the capture into a fixture
 cd backend && uv run python scripts/build_fixture_from_jsonl.py \
  --jsonl /tmp/rec/turns.jsonl --meta /tmp/rec/turns.jsonl.meta.json \
  --out tests/fixtures/replay/<scenario>.<mode>.json --model <model>
 # 3. regenerate the committed golden
 DEERFLOW_WRITE_GOLDEN=1 PYTHONPATH=. uv run pytest tests/test_replay_golden.py
 ```
 ## Run (no key)
 ```bash
 cd backend  && PYTHONPATH=. uv run pytest tests/test_replay_golden.py          # Layer 1
 cd frontend && pnpm exec playwright test -c playwright.real-backend.config.ts  # Layer 2
 ```
 ## CI
 `.github/workflows/replay-e2e.yml` runs both layers on changes to **either** side
 of the contract (`frontend/**`, `backend/app/gateway/**`,
 `backend/packages/harness/**`, fixtures). DOM assertions are the gate; the rendered
 screenshot + Playwright HTML report are uploaded as a CI artifact.
 ## Known limitations
 - Visual regression baselines are OS-specific, so they are a **local dev gate
  only** (gitignored); CI uploads the render as an artifact for human review
  instead of hard-asserting a cross-OS baseline.
 - Fixtures are coupled to the recording-time prompt; if new
  environment-dependent content enters the system prompt, extend the
  normalization in `replay_provider.py` (or pin it in `build_config_yaml`).
 - Re-record a scenario if the agent graph changes how many model calls it makes
  — the replay raises loudly on a hash miss pointing at the divergence.
@@ -0,0 +1,81 @@
 # Sandbox Memory Profiling
 This guide records a repeatable baseline before changing the sandbox runtime.
 Issue #3213 reports per-sandbox memory near 1 GiB in Kubernetes. Before adding
 or recommending a new provider, capture the current AIO sandbox baseline and
 compare candidates with the same DeerFlow workload.
 ## What to Measure
 Measure at least these samples:
 1. Empty sandbox after it becomes ready.
 2. After a simple bash command.
 3. After a Python task that imports common packages.
 4. After a Node task when Node-based workloads are expected.
 5. After generating files under `/mnt/user-data/outputs`.
 6. After release and warm reuse.
 7. At the target concurrency level, for example 10, 50, or 100 sandboxes.
 `kubectl top` reports Kubernetes/container working set memory. Treat it as a
 capacity signal, not exclusive RSS/PSS. Pod-level memory includes every
 container in the Pod and may include cache charged to the cgroup. If a result
 looks surprising, inspect the sandbox processes and cgroup metrics on the node
 before drawing conclusions.
 ## Capture a Snapshot
 Run this from the repository root:
 ```bash
 python scripts/sandbox_memory_profile.py \
  --namespace deer-flow \
  --selector app=deer-flow-sandbox \
  --sample empty \
  --include-processes \
  --format markdown
 ```
 Use a descriptive `--sample` value for each phase:
 ```bash
 python scripts/sandbox_memory_profile.py --sample after-bash --format json
 python scripts/sandbox_memory_profile.py --sample after-python --format json
 python scripts/sandbox_memory_profile.py --sample after-artifact --format json
 ```
 `--include-processes` runs `kubectl exec ... ps` in each sandbox Pod and adds
 the highest-RSS processes to the report. This helps distinguish Pod-level cgroup
 memory from process RSS. The two numbers will not match exactly because cgroup
 memory can include cache and other kernel-accounted memory.
 Save the raw JSON when comparing backends so totals, pod names, images,
 requests, limits, and timestamps can be audited later.
 ## Candidate Runtime Matrix
 For AIO, CubeSandbox, OpenSandbox, gVisor, Kata, or another candidate, compare
 the same workload and record:
 | Area | Required Evidence |
 | --- | --- |
 | Capacity | Pod or instance count, total memory, average memory, max memory |
 | Startup | Ready latency at 1, 10, 50, and 100 concurrent sandboxes |
 | Commands | Bash output, timeout behavior, failure shape |
 | Files | `read_file`, `write_file`, binary `update_file`, `list_dir`, `glob`, `grep` |
 | Uploads | Files uploaded by the gateway are visible inside the sandbox |
 | Artifacts | Files written to `/mnt/user-data/outputs` are readable by the backend artifact API |
 | Paths | `/mnt/user-data/workspace`, `/mnt/user-data/uploads`, `/mnt/user-data/outputs`, `/mnt/acp-workspace`, and skills paths keep their expected semantics |
 | Isolation | Different users and threads cannot read each other's data |
 | Cleanup | Release, idle timeout, process restart, and orphan cleanup free resources |
 | Operations | Deployment prerequisites, privileged components, networking, storage, and upgrade path |
 ## PR Guidance
 Do not claim that a new provider fixes high-concurrency memory usage until the
 same DeerFlow workload has been measured on both the current AIO sandbox and the
 candidate backend.
 For an experimental provider PR, prefer `Related to #3213` unless the PR also
 includes reproducible DeerFlow workload data that demonstrates the target memory
 reduction and preserves uploads, outputs, artifacts, and isolation behavior.
@@ -18,6 +18,8 @@ middleware, and the async path inside ``TitleMiddleware``. Any new in-graph
 ``create_chat_model`` call must add to this list and pass the flag.
 """
 from __future__ import annotations
 import logging
 from langchain.agents import create_agent
@@ -270,6 +272,7 @@ def _build_middlewares(
    custom_middlewares: list[AgentMiddleware] | None = None,
    *,
    app_config: AppConfig | None = None,
    deferred_setup=None,
 ):
    """Build middleware chain based on runtime configuration.
@@ -318,11 +321,13 @@ def _build_middlewares(
    if model_config is not None and model_config.supports_vision:
        middlewares.append(ViewImageMiddleware())
-    # Add DeferredToolFilterMiddleware to hide deferred tool schemas from model binding
+    # Hide deferred tool schemas from model binding until tool_search promotes them.
-    if resolved_app_config.tool_search.enabled:
+    # The deferred set + catalog hash come from the build-time setup (assembled
    # after tool-policy filtering); promotion is read from graph state.
    if deferred_setup is not None and deferred_setup.deferred_names:
        from deerflow.agents.middlewares.deferred_tool_filter_middleware import DeferredToolFilterMiddleware
-        middlewares.append(DeferredToolFilterMiddleware())
+        middlewares.append(DeferredToolFilterMiddleware(deferred_setup.deferred_names, deferred_setup.catalog_hash))
    # Add SubagentLimitMiddleware to truncate excess parallel task calls
    subagent_enabled = cfg.get("subagent_enabled", False)
@@ -386,6 +391,7 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
    # Lazy import to avoid circular dependency
    from deerflow.tools import get_available_tools
    from deerflow.tools.builtins import setup_agent, update_agent
    from deerflow.tools.builtins.tool_search import assemble_deferred_tools
    cfg = _get_runtime_config(config)
    resolved_app_config = app_config
@@ -460,16 +466,19 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
    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]
+        raw_tools = get_available_tools(model_name=model_name, subagent_enabled=subagent_enabled, app_config=resolved_app_config) + [setup_agent]
        filtered = filter_tools_by_skill_allowed_tools(raw_tools, skills_for_tool_policy)
        final_tools, setup = assemble_deferred_tools(filtered, enabled=resolved_app_config.tool_search.enabled)
        return create_agent(
            model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, app_config=resolved_app_config, attach_tracing=False),
-            tools=filter_tools_by_skill_allowed_tools(tools, skills_for_tool_policy),
+            tools=final_tools,
-            middleware=_build_middlewares(config, model_name=model_name, app_config=resolved_app_config),
+            middleware=_build_middlewares(config, model_name=model_name, app_config=resolved_app_config, deferred_setup=setup),
            system_prompt=apply_prompt_template(
                subagent_enabled=subagent_enabled,
                max_concurrent_subagents=max_concurrent_subagents,
                available_skills=set(["bootstrap"]),
                app_config=resolved_app_config,
                deferred_names=setup.deferred_names,
            ),
            state_schema=ThreadState,
        )
@@ -478,17 +487,20 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
    # 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)
+    raw_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)
    filtered = filter_tools_by_skill_allowed_tools(raw_tools + extra_tools, skills_for_tool_policy)
    final_tools, setup = assemble_deferred_tools(filtered, enabled=resolved_app_config.tool_search.enabled)
    return create_agent(
        model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, reasoning_effort=reasoning_effort, app_config=resolved_app_config, attach_tracing=False),
-        tools=filter_tools_by_skill_allowed_tools(tools + extra_tools, skills_for_tool_policy),
+        tools=final_tools,
-        middleware=_build_middlewares(config, model_name=model_name, agent_name=agent_name, app_config=resolved_app_config),
+        middleware=_build_middlewares(config, model_name=model_name, agent_name=agent_name, app_config=resolved_app_config, deferred_setup=setup),
        system_prompt=apply_prompt_template(
            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,
            deferred_names=setup.deferred_names,
        ),
        state_schema=ThreadState,
    )
@@ -10,6 +10,7 @@ from deerflow.config.agents_config import load_agent_soul
 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
 from deerflow.tools.builtins.tool_search import get_deferred_tools_prompt_section
 if TYPE_CHECKING:
    from deerflow.config.app_config import AppConfig
@@ -542,6 +543,14 @@ combined with a FastAPI gateway for REST API access [citation:FastAPI](https://f
 {subagent_reminder}- Skill First: Always load the relevant skill before starting **complex** tasks.
 - Progressive Loading: Load resources incrementally as referenced in skills
 - Output Files: Final deliverables must be in `/mnt/user-data/outputs`
 - File Editing Workflow: When revising an existing file, prefer
  `str_replace` over `write_file` — it sends only the diff and avoids
  re-emitting the whole file (mirrors Claude Code's Edit and Codex's
  apply_patch). When writing long new content from scratch, split it
  into sections: the first `write_file` call creates the file, then use
  `write_file` with append=True to extend it section by section. This
  keeps each tool call small and avoids mid-stream chunk-gap timeouts
  on oversized single-shot writes. (See issue #3189.)  
 - Clarity: Be direct and helpful, avoid unnecessary meta-commentary
 - Including Images and Mermaid: Images and Mermaid diagrams are always welcomed in the Markdown format, and you're encouraged to use `![Image Description](image_path)\n\n` or "```mermaid" to display images in response or Markdown files
 - Multi-task: Better utilize parallel tool calling to call multiple tools at one time for better performance
@@ -678,42 +687,13 @@ SOUL.md or config.yaml — those write into a temporary sandbox/tool workspace a
 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.
 - Never pass literal strings like `"null"`, `"none"`, or `"undefined"` for unchanged fields.
 - 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
    and can use tool_search to load them.
    Returns empty string when tool_search is disabled or no tools are deferred.
    """
    from deerflow.tools.builtins.tool_search import get_deferred_registry
    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()
    if not registry:
        return ""
    names = "\n".join(e.name for e in registry.entries)
    return f"<available-deferred-tools>\n{names}\n</available-deferred-tools>"
 def _build_acp_section(*, app_config: AppConfig | None = None) -> str:
    """Build the ACP agent prompt section, only if ACP agents are configured."""
    if app_config is None:
@@ -772,6 +752,7 @@ def apply_prompt_template(
    agent_name: str | None = None,
    available_skills: set[str] | None = None,
    app_config: AppConfig | None = None,
    deferred_names: frozenset[str] = frozenset(),
 ) -> str:
    # Include subagent section only if enabled (from runtime parameter)
    n = max_concurrent_subagents
@@ -799,7 +780,7 @@ def apply_prompt_template(
    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=app_config)
+    deferred_tools_section = get_deferred_tools_prompt_section(deferred_names=deferred_names)
    # Build ACP agent section only if ACP agents are configured
    acp_section = _build_acp_section(app_config=app_config)
@@ -1,9 +1,14 @@
 """Prompt templates for memory update and injection."""
 from __future__ import annotations
 import logging
 import math
 import re
 from typing import Any
 logger = logging.getLogger(__name__)
 try:
    import tiktoken
@@ -160,6 +165,39 @@ Rules:
 Return ONLY valid JSON."""
 # Module-level tiktoken encoding cache.  Populated lazily on first use;
 # subsequent calls are a dict lookup (no network I/O).  Pre-warming at
 # startup via :func:`warm_tiktoken_cache` avoids blocking a request on the
 # (potentially slow) first ``get_encoding`` call.
 _tiktoken_encoding_cache: dict[str, tiktoken.Encoding] = {}
 def _get_tiktoken_encoding(encoding_name: str = "cl100k_base") -> tiktoken.Encoding | None:
    """Return a cached tiktoken encoding, or ``None`` on failure / unavailability.
    On the very first call for a given *encoding_name*, tiktoken may need to
    download the BPE data from ``openaipublic.blob.core.windows.net``.  In
    network-restricted environments (e.g. deployments behind the GFW) this
    download can block for tens of minutes before the OS TCP timeout kicks in.
    The caller must therefore be prepared for this to block and should run it
    off the event loop (e.g. via ``asyncio.to_thread``).
    """
    if not TIKTOKEN_AVAILABLE:
        return None
    cached = _tiktoken_encoding_cache.get(encoding_name)
    if cached is not None:
        return cached
    try:
        encoding = tiktoken.get_encoding(encoding_name)
        _tiktoken_encoding_cache[encoding_name] = encoding
        return encoding
    except Exception:
        logger.warning("Failed to load tiktoken encoding %r; falling back to char-based estimation", encoding_name, exc_info=True)
        return None
 def _count_tokens(text: str, encoding_name: str = "cl100k_base") -> int:
    """Count tokens in text using tiktoken.
@@ -170,18 +208,30 @@ def _count_tokens(text: str, encoding_name: str = "cl100k_base") -> int:
    Returns:
        The number of tokens in the text.
    """
-    if not TIKTOKEN_AVAILABLE:
+    encoding = _get_tiktoken_encoding(encoding_name)
    if encoding is None:
        # Fallback to character-based estimation if tiktoken is not available
        # or the encoding failed to load.
        return len(text) // 4
    try:
        encoding = tiktoken.get_encoding(encoding_name)
        return len(encoding.encode(text))
    except Exception:
        # Fallback to character-based estimation on error
        return len(text) // 4
 def warm_tiktoken_cache() -> bool:
    """Pre-warm the tiktoken encoding cache.
    Call at startup (off the event loop) so the first request never blocks
    on the BPE download.  Returns ``True`` if the encoding was loaded
    successfully (or was already cached), ``False`` if tiktoken is
    unavailable or the download failed.
    """
    return _get_tiktoken_encoding("cl100k_base") is not None
 def _coerce_confidence(value: Any, default: float = 0.0) -> float:
    """Coerce a confidence-like value to a bounded float in [0, 1].
@@ -1,12 +1,15 @@
 """Middleware to filter deferred tool schemas from model binding.
-When tool_search is enabled, MCP tools are registered in the DeferredToolRegistry
+When tool_search is enabled, MCP tools are still passed to ToolNode for
-and passed to ToolNode for execution, but their schemas should NOT be sent to the
+execution, but their schemas must NOT be sent to the LLM via bind_tools until
-LLM via bind_tools (that's the whole point of deferral — saving context tokens).
+the model has discovered them via tool_search. This middleware removes the
 still-deferred tools from request.tools before model binding, and blocks tool
 calls to tools that have not been promoted yet.
-This middleware intercepts wrap_model_call and removes deferred tools from
+The deferred name set and the catalog hash are injected at construction time
-request.tools so that model.bind_tools only receives active tool schemas.
+(no ContextVar). Promotion state is read from graph state (``state["promoted"]``),
-The agent discovers deferred tools at runtime via the tool_search tool.
+scoped by catalog hash so a stale persisted promotion cannot expose a renamed
 or drifted tool.
 """
 import logging
@@ -24,47 +27,49 @@ logger = logging.getLogger(__name__)
 class DeferredToolFilterMiddleware(AgentMiddleware[AgentState]):
-    """Remove deferred tools from request.tools before model binding.
+    """Hide deferred tool schemas from the bound model until promoted.
    ToolNode still holds all tools (including deferred) for execution routing,
-    but the LLM only sees active tool schemas — deferred tools are discoverable
+    but the LLM only sees active tool schemas plus tools that have already been
-    via tool_search at runtime.
+    promoted (recorded in ``state["promoted"]`` under the current catalog hash).
    """
    def __init__(self, deferred_names: frozenset[str], catalog_hash: str | None):
        super().__init__()
        self._deferred = deferred_names
        self._catalog_hash = catalog_hash
    def _promoted(self, state) -> set[str]:
        promoted = (state or {}).get("promoted")
        if promoted and promoted.get("catalog_hash") == self._catalog_hash:
            return set(promoted.get("names") or [])
        return set()
    def _hidden(self, state) -> set[str]:
        return set(self._deferred) - self._promoted(state)
    def _filter_tools(self, request: ModelRequest) -> ModelRequest:
-        from deerflow.tools.builtins.tool_search import get_deferred_registry
+        if not self._deferred:
        registry = get_deferred_registry()
        if not registry:
            return request
-
+        hide = self._hidden(request.state)
-        deferred_names = registry.deferred_names
+        if not hide:
-        active_tools = [t for t in request.tools if getattr(t, "name", None) not in deferred_names]
+            return request
-
+        active = [t for t in request.tools if getattr(t, "name", None) not in hide]
-        if len(active_tools) < len(request.tools):
+        if len(active) < len(request.tools):
-            logger.debug(f"Filtered {len(request.tools) - len(active_tools)} deferred tool schema(s) from model binding")
+            logger.debug("Filtered %d deferred tool schema(s) from model binding", len(request.tools) - len(active))
-
+        return request.override(tools=active)
        return request.override(tools=active_tools)
    def _blocked_tool_message(self, request: ToolCallRequest) -> ToolMessage | None:
-        from deerflow.tools.builtins.tool_search import get_deferred_registry
+        if not self._deferred:
        registry = get_deferred_registry()
        if not registry:
            return None
-
+        name = str(request.tool_call.get("name") or "")
-        tool_name = str(request.tool_call.get("name") or "")
+        if not name or name not in self._hidden(request.state):
        if not tool_name:
            return None
        if not registry.contains(tool_name):
            return None
        tool_call_id = str(request.tool_call.get("id") or "missing_tool_call_id")
        return ToolMessage(
-            content=(f"Error: Tool '{tool_name}' is deferred and has not been promoted yet. Call tool_search first to expose and promote this tool's schema, then retry."),
+            content=(f"Error: Tool '{name}' is deferred and has not been promoted yet. Call tool_search first to expose and promote this tool's schema, then retry."),
            tool_call_id=tool_call_id,
-            name=tool_name,
+            name=name,
            status="error",
        )
@@ -28,6 +28,7 @@ Date-update format:
 from __future__ import annotations
 import asyncio
 import logging
 import re
 import uuid
@@ -43,6 +44,12 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 # Upper bound (seconds) for a single _inject() offload.  If the warm-up at
 # gateway startup failed silently, the first request may still hit a cold
 # tiktoken BPE download that blocks until the OS TCP timeout (~26 min).
 # This cap ensures the request degrades gracefully instead of hanging.
 _INJECT_TIMEOUT_SECONDS = 5.0
 _DATE_RE = re.compile(r"<current_date>([^<]+)</current_date>")
 _DYNAMIC_CONTEXT_REMINDER_KEY = "dynamic_context_reminder"
 _SUMMARY_MESSAGE_NAME = "summary"
@@ -201,4 +208,25 @@ class DynamicContextMiddleware(AgentMiddleware):
    @override
    async def abefore_agent(self, state, runtime: Runtime) -> dict | None:
-        return self._inject(state)
+        # _inject() performs synchronous file I/O (memory JSON loading) and
        # potentially blocking network calls (tiktoken encoding download on
        # first use).  Offload to a thread so the event loop is never blocked
        # — a blocking call here starves all concurrent HTTP handlers (auth,
        # SSE heartbeats, etc.).  See issue #3402.
        #
        # Bounded timeout: if startup warm-up failed silently (e.g. network
        # blip during deploy), the first request's cold tiktoken download can
        # block for tens of minutes (OS TCP timeout).  Time-box injection so
        # the request degrades gracefully (no memory context) rather than
        # hanging.
        try:
            return await asyncio.wait_for(
                asyncio.to_thread(self._inject, state),
                timeout=_INJECT_TIMEOUT_SECONDS,
            )
        except TimeoutError:
            logger.warning(
                "DynamicContextMiddleware: injection timed out (%.1fs); skipping memory/date injection for this turn",
                _INJECT_TIMEOUT_SECONDS,
            )
            return None
@@ -62,6 +62,41 @@ _AUTH_PATTERNS = (
    "未授权",
 )
 # Per-exception retry budget overrides.
 #
 # Some transient errors are retriable in principle but expensive to retry at
 # the default budget. StreamChunkTimeoutError in particular fires after the
 # upstream provider has already stalled for `stream_chunk_timeout` seconds
 # (typically 120-240s); a full 3-attempt loop can therefore stack 6-12 minutes
 # of dead air before surfacing the failure to the user. We keep exactly one
 # retry (cheap reconnect that catches genuine transient TCP blips) and then
 # fail fast — the same buffered payload is overwhelmingly likely to fail
 # again at the upstream provider for the same reason.
 #
 # Keys are exception class *names* (not classes) so we don't introduce
 # import-time coupling on optional dependencies like langchain-openai. The
 # value is the absolute max attempt count, NOT additional retries — so a
 # value of 2 means "1 first attempt + 1 retry" (the CR-requested
 # "keep one retry" behavior).
 _RETRY_BUDGET_OVERRIDES: dict[str, int] = {
    "StreamChunkTimeoutError": 2,
 }
 # Exception class names that indicate the upstream stream-chunk watchdog
 # fired because the model stalled mid-flight. These deserve a more specific
 # user-facing message than the generic "temporarily unavailable" copy,
 # because the typical root cause is a long tool-call serialization stalling
 # the upstream stream — and the most actionable advice we can give the user
 # is "ask for a shorter / split output" rather than "wait and retry".
 # Generic connection drops (httpx RemoteProtocolError / ReadError) are
 # intentionally excluded: they routinely fire on transient network blips
 # with normal payloads, where the "split the work" guidance is misleading.
 _STREAM_DROP_EXCEPTIONS: frozenset[str] = frozenset(
    {
        "StreamChunkTimeoutError",
    }
 )
 class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
    """Retry transient LLM errors and surface graceful assistant messages."""
@@ -83,6 +118,18 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
        self._circuit_state = "closed"
        self._circuit_probe_in_flight = False
    def _max_attempts_for(self, exc: BaseException) -> int:
        """Return the effective max attempt count for this exception.
        Falls back to `self.retry_max_attempts` unless the exception class name
        appears in the per-exception override table.
        """
        override = _RETRY_BUDGET_OVERRIDES.get(type(exc).__name__)
        if override is None:
            return self.retry_max_attempts
        return min(override, self.retry_max_attempts)
    def _check_circuit(self) -> bool:
        """Returns True if circuit is OPEN (fast fail), False otherwise."""
        with self._circuit_lock:
@@ -153,6 +200,7 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
            "InternalServerError",
            "ReadError",  # httpx.ReadError: connection dropped mid-stream
            "RemoteProtocolError",  # httpx: server closed connection unexpectedly
            "StreamChunkTimeoutError",  # langchain-openai: chunk gap exceeded stream_chunk_timeout
        }:
            return True, "transient"
        if status_code in _RETRIABLE_STATUS_CODES:
@@ -177,6 +225,24 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
    def _build_circuit_breaker_message(self) -> str:
        return "The configured LLM provider is currently unavailable due to continuous failures. Circuit breaker is engaged to protect the system. Please wait a moment before trying again."
    def _build_error_fallback_message(
        self,
        content: str,
        *,
        error_type: str,
        reason: str,
        detail: str,
    ) -> AIMessage:
        return AIMessage(
            content=content,
            additional_kwargs={
                "deerflow_error_fallback": True,
                "error_type": error_type,
                "error_reason": reason,
                "error_detail": detail,
            },
        )
    def _build_user_message(self, exc: BaseException, reason: str) -> str:
        detail = _extract_error_detail(exc)
        if reason == "quota":
@@ -184,9 +250,31 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
        if reason == "auth":
            return "The configured LLM provider rejected the request because authentication or access is invalid. Please check the provider credentials and try again."
        if reason in {"busy", "transient"}:
            # Stream-drop failures (chunk-gap timeout, peer-closed connection,
            # raw read error) almost always point at a single oversized
            # tool-call payload — the model spent so long serializing JSON
            # arguments that the upstream provider buffered and the stream
            # gap exceeded `stream_chunk_timeout`. Surfacing this distinct
            # cause lets the user split or shorten their next request
            # instead of helplessly retrying the same prompt.
            if type(exc).__name__ in _STREAM_DROP_EXCEPTIONS:
                return (
                    "The model's streaming response was interrupted before it could "
                    "finish. This usually happens when a single response or tool call "
                    "is very large — please ask the assistant to split the work into "
                    "smaller steps, or shorten the requested output, and try again."
                )
            return "The configured LLM provider is temporarily unavailable after multiple retries. Please wait a moment and continue the conversation."
        return f"LLM request failed: {detail}"
    def _build_user_fallback_message(self, exc: BaseException, reason: str) -> AIMessage:
        return self._build_error_fallback_message(
            self._build_user_message(exc, reason),
            error_type=type(exc).__name__,
            reason=reason,
            detail=_extract_error_detail(exc),
        )
    def _emit_retry_event(self, attempt: int, wait_ms: int, reason: str) -> None:
        try:
            from langgraph.config import get_stream_writer
@@ -212,7 +300,12 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
        handler: Callable[[ModelRequest], ModelResponse],
    ) -> ModelCallResult:
        if self._check_circuit():
-            return AIMessage(content=self._build_circuit_breaker_message())
+            return self._build_error_fallback_message(
                self._build_circuit_breaker_message(),
                error_type="CircuitBreakerOpen",
                reason="circuit_open",
                detail="LLM circuit breaker is open",
            )
        attempt = 1
        while True:
@@ -228,7 +321,8 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
                raise
            except Exception as exc:
                retriable, reason = self._classify_error(exc)
-                if retriable and attempt < self.retry_max_attempts:
+                max_attempts = self._max_attempts_for(exc)
                if retriable and attempt < max_attempts:
                    wait_ms = self._build_retry_delay_ms(attempt, exc)
                    logger.warning(
                        "Transient LLM error on attempt %d/%d; retrying in %dms: %s",
@@ -249,7 +343,7 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
                )
                if retriable:
                    self._record_failure()
-                return AIMessage(content=self._build_user_message(exc, reason))
+                return self._build_user_fallback_message(exc, reason)
    @override
    async def awrap_model_call(
@@ -258,7 +352,12 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
    ) -> ModelCallResult:
        if self._check_circuit():
-            return AIMessage(content=self._build_circuit_breaker_message())
+            return self._build_error_fallback_message(
                self._build_circuit_breaker_message(),
                error_type="CircuitBreakerOpen",
                reason="circuit_open",
                detail="LLM circuit breaker is open",
            )
        attempt = 1
        while True:
@@ -274,7 +373,8 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
                raise
            except Exception as exc:
                retriable, reason = self._classify_error(exc)
-                if retriable and attempt < self.retry_max_attempts:
+                max_attempts = self._max_attempts_for(exc)
                if retriable and attempt < max_attempts:
                    wait_ms = self._build_retry_delay_ms(attempt, exc)
                    logger.warning(
                        "Transient LLM error on attempt %d/%d; retrying in %dms: %s",
@@ -295,7 +395,7 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
                )
                if retriable:
                    self._record_failure()
-                return AIMessage(content=self._build_user_message(exc, reason))
+                return self._build_user_fallback_message(exc, reason)
 def _matches_any(detail: str, patterns: tuple[str, ...]) -> bool:
@@ -9,8 +9,9 @@ from typing import Any, Protocol, override, runtime_checkable
 from langchain.agents import AgentState
 from langchain.agents.middleware import SummarizationMiddleware
-from langchain_core.messages import AIMessage, AnyMessage, HumanMessage, RemoveMessage, ToolMessage
+from langchain_core.messages import AIMessage, AnyMessage, HumanMessage, RemoveMessage, ToolMessage, get_buffer_string
 from langgraph.config import get_config
 from langgraph.constants import TAG_NOSTREAM
 from langgraph.graph.message import REMOVE_ALL_MESSAGES
 from langgraph.runtime import Runtime
@@ -116,6 +117,74 @@ class DeerFlowSummarizationMiddleware(SummarizationMiddleware):
        self._preserve_recent_skill_count = max(0, preserve_recent_skill_count)
        self._preserve_recent_skill_tokens = max(0, preserve_recent_skill_tokens)
        self._preserve_recent_skill_tokens_per_skill = max(0, preserve_recent_skill_tokens_per_skill)
        # The summary LLM call runs inside a LangGraph middleware hook, so its token
        # stream would otherwise be captured by the messages-tuple stream callback and
        # broadcast to the frontend as a phantom AI message. Tag a dedicated model copy
        # with TAG_NOSTREAM so the streaming handler skips it.
        # Keep self.model untagged so the parent's profile / ls_params inspection still works.
        #
        # Preserve any tags already bound on the model (e.g. "middleware:summarize" set in
        # lead_agent/agent.py for RunJournal attribution): RunnableBinding.with_config does a
        # shallow merge that would otherwise overwrite the existing tags list entirely.
        existing_tags = list((getattr(self.model, "config", None) or {}).get("tags") or [])
        merged_tags = [*existing_tags, TAG_NOSTREAM] if TAG_NOSTREAM not in existing_tags else existing_tags
        self._summary_model = self.model.with_config(tags=merged_tags)
    @override
    def _create_summary(self, messages_to_summarize: list[AnyMessage]) -> str:
        return self._summarize_with(messages_to_summarize)
    @override
    async def _acreate_summary(self, messages_to_summarize: list[AnyMessage]) -> str:
        return await self._asummarize_with(messages_to_summarize)
    def _summarize_with(self, messages_to_summarize: list[AnyMessage]) -> str:
        """Mirror the parent ``_create_summary`` but invoke the nostream-tagged model.
        We do not swap ``self.model`` at the instance level: the agent/middleware is
        cached and reused across concurrent runs, so a temporary swap would leak the
        ``RunnableBinding`` to other coroutines during ``await`` and break parent logic
        that inspects the raw model (``profile`` / ``_get_ls_params``).
        """
        if not messages_to_summarize:
            return "No previous conversation history."
        prompt = self._build_summary_prompt(messages_to_summarize)
        if prompt is None:
            return "Previous conversation was too long to summarize."
        try:
            response = self._summary_model.invoke(
                prompt,
                config={"metadata": {"lc_source": "summarization"}},
            )
            return response.text.strip()
        except Exception as e:
            return f"Error generating summary: {e!s}"
    async def _asummarize_with(self, messages_to_summarize: list[AnyMessage]) -> str:
        """Async counterpart of :meth:`_summarize_with` using the nostream model."""
        if not messages_to_summarize:
            return "No previous conversation history."
        prompt = self._build_summary_prompt(messages_to_summarize)
        if prompt is None:
            return "Previous conversation was too long to summarize."
        try:
            response = await self._summary_model.ainvoke(
                prompt,
                config={"metadata": {"lc_source": "summarization"}},
            )
            return response.text.strip()
        except Exception as e:
            return f"Error generating summary: {e!s}"
    def _build_summary_prompt(self, messages_to_summarize: list[AnyMessage]) -> str | None:
        """Build the summary prompt, returning ``None`` when trimming leaves nothing."""
        trimmed_messages = self._trim_messages_for_summary(messages_to_summarize)
        if not trimmed_messages:
            return None
        # Format messages to avoid token inflation from metadata when str() is called on
        # message objects.
        formatted_messages = get_buffer_string(trimmed_messages)
        return self.summary_prompt.format(messages=formatted_messages).rstrip()
    def before_model(self, state: AgentState, runtime: Runtime) -> dict | None:
        return self._maybe_summarize(state, runtime)
@@ -2,7 +2,7 @@
 import logging
 from collections.abc import Awaitable, Callable
-from typing import override
+from typing import TYPE_CHECKING, override
 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
@@ -12,10 +12,48 @@ from langgraph.prebuilt.tool_node import ToolCallRequest
 from langgraph.types import Command
 from deerflow.config.app_config import AppConfig
 from deerflow.subagents.status_contract import (
    extract_subagent_status,
    make_subagent_additional_kwargs,
 )
 if TYPE_CHECKING:
    from deerflow.tools.builtins.tool_search import DeferredToolSetup
 logger = logging.getLogger(__name__)
 _MISSING_TOOL_CALL_ID = "missing_tool_call_id"
 _TASK_TOOL_NAME = "task"
 def _stamp_task_subagent_status(message: ToolMessage, *, tool_name: str, error: str | None = None) -> ToolMessage:
    """Centralised stamping of ``additional_kwargs.subagent_status``.
    Bytedance/deer-flow issue #3146: the frontend now reads the subagent
    status from a structured field instead of parsing the leading text of
    the task tool's return string. That contract is enforced here, in the
    one place every task tool result flows through, rather than at the 5
    normal-return + 3 ``Error:`` pre-execution branches inside
    ``task_tool.py``. Centralisation prevents the "added a new return
    path, forgot the stamp" drift mode.
    For non-``task`` tools this is a no-op so other tools' additional_kwargs
    conventions are untouched.
    """
    if tool_name != _TASK_TOOL_NAME:
        return message
    content = message.content if isinstance(message.content, str) else ""
    status = extract_subagent_status(content)
    if status is None:
        # Non-terminal streaming chunks or unrecognised shapes leave the
        # field unset so the frontend can keep the card on its in-progress
        # placeholder until a real terminal frame arrives.
        return message
    stamp = make_subagent_additional_kwargs(status, error=error)
    existing = dict(message.additional_kwargs or {})
    existing.update(stamp)
    message.additional_kwargs = existing
    return message
 class ToolErrorHandlingMiddleware(AgentMiddleware[AgentState]):
@@ -29,12 +67,31 @@ class ToolErrorHandlingMiddleware(AgentMiddleware[AgentState]):
            detail = detail[:497] + "..."
        content = f"Error: Tool '{tool_name}' failed with {exc.__class__.__name__}: {detail}. Continue with available context, or choose an alternative tool."
-        return ToolMessage(
+        message = ToolMessage(
            content=content,
            tool_call_id=tool_call_id,
            name=tool_name,
            status="error",
        )
        # Stamp the structured subagent status on the wrapper too: the
        # frontend would otherwise have to fall back to prefix-matching
        # ``Error: Tool 'task' failed ...`` on the wire. The ``subagent_error``
        # carries the same ``ExcClass: detail`` shape the wrapper string
        # uses so debugging artifacts stay aligned.
        structured_error = f"{exc.__class__.__name__}: {detail}"
        return _stamp_task_subagent_status(message, tool_name=tool_name, error=structured_error)
    @staticmethod
    def _maybe_stamp(result: ToolMessage | Command, request: ToolCallRequest) -> ToolMessage | Command:
        """Apply the subagent stamp to successful task tool returns.
        ``Command`` results bypass the stamp — they encode LangGraph
        control flow rather than user-facing tool output.
        """
        if not isinstance(result, ToolMessage):
            return result
        tool_name = str(request.tool_call.get("name") or "")
        return _stamp_task_subagent_status(result, tool_name=tool_name)
    @override
    def wrap_tool_call(
@@ -43,13 +100,14 @@ class ToolErrorHandlingMiddleware(AgentMiddleware[AgentState]):
        handler: Callable[[ToolCallRequest], ToolMessage | Command],
    ) -> ToolMessage | Command:
        try:
-            return handler(request)
+            result = handler(request)
        except GraphBubbleUp:
            # Preserve LangGraph control-flow signals (interrupt/pause/resume).
            raise
        except Exception as exc:
            logger.exception("Tool execution failed (sync): name=%s id=%s", request.tool_call.get("name"), request.tool_call.get("id"))
            return self._build_error_message(request, exc)
        return self._maybe_stamp(result, request)
    @override
    async def awrap_tool_call(
@@ -58,13 +116,14 @@ class ToolErrorHandlingMiddleware(AgentMiddleware[AgentState]):
        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
    ) -> ToolMessage | Command:
        try:
-            return await handler(request)
+            result = await handler(request)
        except GraphBubbleUp:
            # Preserve LangGraph control-flow signals (interrupt/pause/resume).
            raise
        except Exception as exc:
            logger.exception("Tool execution failed (async): name=%s id=%s", request.tool_call.get("name"), request.tool_call.get("id"))
            return self._build_error_message(request, exc)
        return self._maybe_stamp(result, request)
 def _build_runtime_middlewares(
@@ -143,6 +202,7 @@ def build_subagent_runtime_middlewares(
    app_config: AppConfig | None = None,
    model_name: str | None = None,
    lazy_init: bool = True,
    deferred_setup: "DeferredToolSetup | None" = None,
 ) -> list[AgentMiddleware]:
    """Middlewares shared by subagent runtime before subagent-only middlewares."""
    if app_config is None:
@@ -166,6 +226,16 @@ def build_subagent_runtime_middlewares(
        middlewares.append(ViewImageMiddleware())
    # Hide deferred (MCP) tool schemas from the subagent's model binding until
    # tool_search promotes them. This is the same wiring the lead agent gets. The deferred
    # set + catalog hash come from the build-time setup (assembled after
    # tool-policy filtering); promotion is read from graph state. Empty/None
    # setup (deferral disabled or no MCP tool survived) is a pure no-op.
    if deferred_setup is not None and deferred_setup.deferred_names:
        from deerflow.agents.middlewares.deferred_tool_filter_middleware import DeferredToolFilterMiddleware
        middlewares.append(DeferredToolFilterMiddleware(deferred_setup.deferred_names, deferred_setup.catalog_hash))
    # Same provider safety-termination guard the lead agent uses — subagents
    # are equally exposed to truncated tool_calls returned with
    # finish_reason=content_filter (and friends), and the bad call would then
@@ -11,10 +11,11 @@ from __future__ import annotations
 import asyncio
 import logging
 import os
 import shlex
 import uuid
 from collections.abc import Awaitable, Callable
 from dataclasses import replace as dc_replace
-from typing import Any, override
+from typing import TYPE_CHECKING, Any, override
 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware
@@ -24,9 +25,19 @@ from langgraph.prebuilt.tool_node import ToolCallRequest
 from langgraph.types import Command
 from deerflow.config.tool_output_config import ToolOutputConfig
 from deerflow.sandbox.sandbox_provider import get_sandbox_provider
 if TYPE_CHECKING:
    from deerflow.sandbox.sandbox import Sandbox
 logger = logging.getLogger(__name__)
 # Virtual outputs root inside the sandbox. Host-mounted sandboxes map this to
 # the thread outputs dir on the host; for non-mounted (remote) sandboxes the
 # same path is written directly into the sandbox filesystem so the model's
 # ``read_file`` tool can read it back (issue #3416).
 _VIRTUAL_OUTPUTS_BASE = "/mnt/user-data/outputs"
 def _default_config() -> ToolOutputConfig:
    return ToolOutputConfig()
@@ -94,6 +105,18 @@ def _sanitize_tool_name(name: str) -> str:
    return safe or "unknown"
 def _build_externalized_filename(*, tool_name: str, tool_call_id: str) -> str:
    """Build the on-disk filename for an externalized tool output.
    Shared by the host-disk and sandbox externalization paths so both
    produce the identical naming scheme.
    """
    safe_name = _sanitize_tool_name(tool_name)
    ext = _EXT_MAP.get(tool_name, "txt")
    short_id = uuid.uuid4().hex[:12]
    return f"{safe_name}-{short_id}.{ext}"
 def _externalize(
    content: str,
    *,
@@ -111,10 +134,7 @@ def _externalize(
    except OSError:
        return None
-    safe_name = _sanitize_tool_name(tool_name)
+    filename = _build_externalized_filename(tool_name=tool_name, tool_call_id=tool_call_id)
    ext = _EXT_MAP.get(tool_name, "txt")
    short_id = uuid.uuid4().hex[:12]
    filename = f"{safe_name}-{short_id}.{ext}"
    filepath = os.path.join(storage_dir, filename)
    if not os.path.abspath(filepath).startswith(os.path.abspath(storage_dir)):
@@ -126,8 +146,56 @@ def _externalize(
    except OSError:
        return None
-    virtual_base = "/mnt/user-data/outputs"
+    return f"{_VIRTUAL_OUTPUTS_BASE}/{storage_subdir}/{filename}"
-    return f"{virtual_base}/{storage_subdir}/{filename}"
+
 def _externalize_to_sandbox(
    content: str,
    *,
    tool_name: str,
    tool_call_id: str,
    storage_subdir: str,
    sandbox: Sandbox,
 ) -> str | None:
    """Write *content* into the sandbox filesystem and return the virtual path.
    Used when the sandbox does not use thread-data mounts (e.g. a remote AIO
    sandbox): the host-side :func:`_externalize` virtual path would not exist
    inside the sandbox, so the model's ``read_file`` tool could not read it
    back (issue #3416). Returns the same virtual-path contract on success, or
    ``None`` to signal the caller to fall back to inline truncation.
    """
    if os.path.isabs(storage_subdir) or ".." in storage_subdir:
        return None
    filename = _build_externalized_filename(tool_name=tool_name, tool_call_id=tool_call_id)
    virtual_dir = f"{_VIRTUAL_OUTPUTS_BASE}/{storage_subdir}"
    virtual_path = f"{virtual_dir}/{filename}"
    try:
        # AIO sandbox write_file does NOT create parent directories, so create
        # them explicitly before writing. execute_command returns its stdout
        # verbatim (including an "Error: ..." string on failure) rather than
        # raising, so we cannot rely on exception propagation here.
        sandbox.execute_command(f"mkdir -p {shlex.quote(virtual_dir)}")
        sandbox.write_file(virtual_path, content)
        # Validate the file landed: execute_command may have silently failed
        # to create the directory, and write_file backends differ. Refuse to
        # hand the model an unreadable read_file path.
        check = sandbox.execute_command(f"test -s {shlex.quote(virtual_path)} && echo OK || echo MISSING")
        if not isinstance(check, str) or check.strip() != "OK":
            logger.warning(
                "Sandbox externalize validation failed: path=%s, check=%r",
                virtual_path,
                check,
            )
            return None
    except Exception:
        logger.exception(
            "Failed to externalize %s output to sandbox (call_id=%s)",
            tool_name,
            tool_call_id,
        )
        return None
    return virtual_path
 # ---------------------------------------------------------------------------
@@ -227,6 +295,33 @@ def _resolve_outputs_path(request: ToolCallRequest) -> str | None:
    return outputs_path if isinstance(outputs_path, str) else None
 def _resolve_sandbox(request: ToolCallRequest) -> Sandbox | None:
    """Resolve the active sandbox for the current tool call, or ``None``.
    Reads the sandbox_id that ``SandboxMiddleware`` (and the sandbox tools
    themselves) write into ``runtime.state["sandbox"]``. We intentionally do
    NOT call ``provider.acquire`` here: acquiring a sandbox can trigger
    blocking remote I/O, and this resolver runs on every tool call. Tools
    that do not use a sandbox (``web_search``, MCP, ...) will return ``None``
    here, which is fine -- the caller falls back to inline truncation.
    """
    runtime = getattr(request, "runtime", None)
    state = getattr(runtime, "state", None)
    if not isinstance(state, dict):
        return None
    sandbox_state = state.get("sandbox")
    if not isinstance(sandbox_state, dict):
        return None
    sandbox_id = sandbox_state.get("sandbox_id")
    if not sandbox_id:
        return None
    try:
        return get_sandbox_provider().get(sandbox_id)
    except Exception:
        logger.exception("Failed to look up sandbox %s for tool-output externalization", sandbox_id)
        return None
 def _budget_content(
    content: str,
    *,
@@ -234,6 +329,7 @@ def _budget_content(
    tool_call_id: str,
    outputs_path: str | None,
    config: ToolOutputConfig,
    sandbox: Sandbox | None = None,
 ) -> str | None:
    """Apply budget to *content*. Returns ``None`` if no change needed."""
    threshold = config.tool_overrides.get(tool_name, config.externalize_min_chars)
@@ -242,14 +338,50 @@ def _budget_content(
    if len(content) <= threshold and len(content) <= config.fallback_max_chars:
        return None
-    if threshold > 0 and len(content) > threshold and outputs_path:
+    if threshold > 0 and len(content) > threshold:
-        virtual_path = _externalize(
+        virtual_path: str | None = None
-            content,
+        # Decide persistence target based on what's available, without touching
-            tool_name=tool_name,
+        # the sandbox provider unless a sandbox was actually resolved for this
-            tool_call_id=tool_call_id,
+        # call. This keeps the legacy host-disk path provider-free, so callers
-            outputs_path=outputs_path,
+        # without a configured sandbox (and CI environments without a
-            storage_subdir=config.storage_subdir,
+        # config.yaml) continue to externalize to the host as before.
-        )
+        if sandbox is not None:
            provider = None
            try:
                provider = get_sandbox_provider()
            except Exception:
                logger.exception("Failed to get sandbox provider for tool-output externalization; falling back to inline truncation")
            if provider is not None and getattr(provider, "uses_thread_data_mounts", False):
                # Host-mounted sandbox: host outputs path is bind-mounted into
                # the sandbox at the same virtual path, so writing host-side is
                # equivalent. Preserve the original behavior to avoid extra
                # sandbox round-trips.
                if outputs_path:
                    virtual_path = _externalize(
                        content,
                        tool_name=tool_name,
                        tool_call_id=tool_call_id,
                        outputs_path=outputs_path,
                        storage_subdir=config.storage_subdir,
                    )
            else:
                virtual_path = _externalize_to_sandbox(
                    content,
                    tool_name=tool_name,
                    tool_call_id=tool_call_id,
                    storage_subdir=config.storage_subdir,
                    sandbox=sandbox,
                )
        elif outputs_path:
            # No sandbox in this call (legacy / non-sandbox tools): write to
            # host outputs path directly, no provider needed.
            virtual_path = _externalize(
                content,
                tool_name=tool_name,
                tool_call_id=tool_call_id,
                outputs_path=outputs_path,
                storage_subdir=config.storage_subdir,
            )
        if virtual_path is not None:
            logger.info(
                "Externalized %s output (%d chars) to %s",
@@ -288,7 +420,12 @@ def _budget_content(
 # ---------------------------------------------------------------------------
-def _patch_tool_message(msg: ToolMessage, config: ToolOutputConfig, outputs_path: str | None) -> ToolMessage:
+def _patch_tool_message(
    msg: ToolMessage,
    config: ToolOutputConfig,
    outputs_path: str | None,
    sandbox: Sandbox | None = None,
 ) -> ToolMessage:
    """Apply budget to a single ToolMessage. Returns the original if unchanged."""
    tool_name = msg.name or "unknown"
    if tool_name in config.exempt_tools:
@@ -304,6 +441,7 @@ def _patch_tool_message(msg: ToolMessage, config: ToolOutputConfig, outputs_path
        tool_call_id=msg.tool_call_id or "",
        outputs_path=outputs_path,
        config=config,
        sandbox=sandbox,
    )
    if replacement is None:
        return msg
@@ -355,10 +493,15 @@ def _needs_budget(result: ToolMessage | Command, config: ToolOutputConfig) -> bo
    return False
-def _patch_result(result: ToolMessage | Command, config: ToolOutputConfig, outputs_path: str | None) -> ToolMessage | Command:
+def _patch_result(
    result: ToolMessage | Command,
    config: ToolOutputConfig,
    outputs_path: str | None,
    sandbox: Sandbox | None = None,
 ) -> ToolMessage | Command:
    """Apply budget to a tool call result (ToolMessage or Command)."""
    if isinstance(result, ToolMessage):
-        return _patch_tool_message(result, config, outputs_path)
+        return _patch_tool_message(result, config, outputs_path, sandbox)
    update = getattr(result, "update", None)
    if not isinstance(update, dict):
@@ -372,7 +515,7 @@ def _patch_result(result: ToolMessage | Command, config: ToolOutputConfig, outpu
    changed = False
    for msg in messages:
        if isinstance(msg, ToolMessage):
-            patched = _patch_tool_message(msg, config, outputs_path)
+            patched = _patch_tool_message(msg, config, outputs_path, sandbox)
            if patched is not msg:
                changed = True
            new_messages.append(patched)
@@ -392,6 +535,11 @@ def _patch_model_messages(messages: list[Any], config: ToolOutputConfig) -> list
    ToolMessage exceeds the budget — the common case once every result has
    already been budgeted at tool-call time, so a long history is not rebuilt
    on every model call.
    Historical messages do not get a ``sandbox`` argument: any oversized tool
    message in history was already budgeted (and possibly externalized) at
    tool-call time, so the only thing left for the history path to do is
    inline fallback truncation, which needs no sandbox.
    """
    if not any(isinstance(msg, ToolMessage) and _tool_message_over_budget(msg, config) for msg in messages):
        return None
@@ -442,7 +590,8 @@ class ToolOutputBudgetMiddleware(AgentMiddleware[AgentState]):
        if not _needs_budget(result, self._config):
            return result
        outputs_path = _resolve_outputs_path(request)
-        return _patch_result(result, self._config, outputs_path)
+        sandbox = _resolve_sandbox(request)
        return _patch_result(result, self._config, outputs_path, sandbox)
    @override
    async def awrap_tool_call(
@@ -456,7 +605,12 @@ class ToolOutputBudgetMiddleware(AgentMiddleware[AgentState]):
        if not _needs_budget(result, self._config):
            return result
        outputs_path = _resolve_outputs_path(request)
-        return await asyncio.to_thread(_patch_result, result, self._config, outputs_path)
+        # _resolve_sandbox only touches runtime.state and the provider's
        # in-memory sandbox registry, so it is safe to call on the event
        # loop. The actual sandbox I/O (mkdir/write/test) happens inside
        # _patch_result, which is offloaded to a worker thread below.
        sandbox = _resolve_sandbox(request)
        return await asyncio.to_thread(_patch_result, result, self._config, outputs_path, sandbox)
    # -- model call hooks (historical message truncation) ------------------
@@ -179,8 +179,10 @@ class ViewImageMiddleware(AgentMiddleware[ViewImageMiddlewareState]):
        # Create the image details message with text and image content
        image_content = self._create_image_details_message(state)
-        # Create a new human message with mixed content (text + images)
+        # Create a new human message with mixed content (text + images). This is
-        human_msg = HumanMessage(content=image_content)
+        # internal context for the model only, so hide it from the chat UI and IM
        # channels (matches the other middleware-injected context messages).
        human_msg = HumanMessage(content=image_content, additional_kwargs={"hide_from_ui": True})
        logger.debug("Injecting image details message with images before LLM call")
@@ -58,6 +58,32 @@ def merge_todos(existing: list | None, new: list | None) -> list | None:
    return new
 class PromotedTools(TypedDict):
    catalog_hash: str
    names: list[str]
 def merge_promoted(existing: PromotedTools | None, new: PromotedTools | None) -> PromotedTools | None:
    """Reducer for deferred-tool promotions, scoped by catalog hash.
    - new None/empty -> preserve existing (node didn't touch promotions).
    - catalog_hash changed -> replace wholesale, dropping stale names (prevents a
      persisted bare name from exposing a different tool after catalog drift).
    - same catalog_hash -> union names, dedupe, preserve order.
    """
    if not new:
        return existing
    if existing is None or existing.get("catalog_hash") != new["catalog_hash"]:
        return {
            "catalog_hash": new["catalog_hash"],
            "names": list(dict.fromkeys(new["names"])),
        }
    return {
        "catalog_hash": existing["catalog_hash"],
        "names": list(dict.fromkeys(existing["names"] + new["names"])),
    }
 class ThreadState(AgentState):
    sandbox: NotRequired[SandboxState | None]
    thread_data: NotRequired[ThreadDataState | None]
@@ -66,3 +92,4 @@ class ThreadState(AgentState):
    todos: Annotated[list | None, merge_todos]
    uploaded_files: NotRequired[list[dict] | None]
    viewed_images: Annotated[dict[str, ViewedImageData], merge_viewed_images]  # image_path -> {base64, mime_type}
    promoted: Annotated[PromotedTools | None, merge_promoted]
@@ -43,6 +43,7 @@ from deerflow.config.paths import get_paths
 from deerflow.models import create_chat_model
 from deerflow.runtime.user_context import get_effective_user_id
 from deerflow.skills.storage import get_or_new_skill_storage
 from deerflow.tools.builtins.tool_search import assemble_deferred_tools
 from deerflow.tracing import build_tracing_callbacks, inject_langfuse_metadata
 from deerflow.uploads.manager import (
    claim_unique_filename,
@@ -237,19 +238,22 @@ class DeerFlowClient:
        subagent_enabled = cfg.get("subagent_enabled", False)
        max_concurrent_subagents = cfg.get("max_concurrent_subagents", 3)
        tools = self._get_tools(model_name=model_name, subagent_enabled=subagent_enabled)
        final_tools, deferred_setup = assemble_deferred_tools(tools, enabled=self._app_config.tool_search.enabled)
        kwargs: dict[str, Any] = {
            # attach_tracing=False because ``stream()`` injects tracing
            # callbacks at the graph invocation root so a single embedded run
            # produces one trace with correct session_id / user_id propagation.
            # Attaching them again on the model would emit duplicate spans.
            "model": create_chat_model(name=model_name, thinking_enabled=thinking_enabled, attach_tracing=False),
-            "tools": self._get_tools(model_name=model_name, subagent_enabled=subagent_enabled),
+            "tools": final_tools,
-            "middleware": _build_middlewares(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, deferred_setup=deferred_setup),
            "system_prompt": apply_prompt_template(
                subagent_enabled=subagent_enabled,
                max_concurrent_subagents=max_concurrent_subagents,
                agent_name=self._agent_name,
                available_skills=self._available_skills,
                deferred_names=deferred_setup.deferred_names,
            ),
            "state_schema": ThreadState,
        }
@@ -1206,7 +1210,7 @@ class DeerFlowClient:
                info: dict[str, Any] = {
                    "filename": dest_name,
-                    "size": str(dest.stat().st_size),
+                    "size": dest.stat().st_size,
                    "path": str(dest),
                    "virtual_path": upload_virtual_path(dest_name),
                    "artifact_url": upload_artifact_url(thread_id, dest_name),
@@ -39,11 +39,63 @@ class AioSandbox(Sandbox):
        self._client = AioSandboxClient(base_url=base_url, timeout=600)
        self._home_dir = home_dir
        self._lock = threading.Lock()
        self._closed = False
    @property
    def base_url(self) -> str:
        return self._base_url
    def close(self) -> None:
        """Best-effort close of the host-side HTTP client owned by this sandbox.
        The agent_sandbox SDK is Fern-generated and exposes no ``close()`` /
        ``__exit__``, so we reach the socket-owning ``httpx.Client`` explicitly
        through its attribute chain::
            Sandbox._client_wrapper        -> SyncClientWrapper
                .httpx_client              -> Fern HttpClient (a wrapper, NOT httpx.Client)
                    .httpx_client          -> httpx.Client     <- the real socket owner
        Closing it releases pooled sockets so long-running provider lifecycles
        do not accumulate unreclaimed host-side resources (#2872).
        Resolution is most-specific-first with graceful degradation: if a future
        SDK adds a top-level ``Sandbox.close()`` it is picked up automatically
        without changing this code. Idempotent, thread-safe, and non-fatal:
        failures during teardown are logged and swallowed so provider/backend
        cleanup is never blocked.
        """
        with self._lock:
            if self._closed:
                return
            self._closed = True
            client = self._client
            # Drop the reference under the lock for use-after-close safety: any
            # later command on this instance fails loudly instead of reusing a
            # half-closed client.
            self._client = None
        if client is None:
            return
        # Walk from the real httpx.Client up to the top-level client, picking the
        # first object that actually exposes close().
        wrapper = getattr(client, "_client_wrapper", None)
        fern_http = getattr(wrapper, "httpx_client", None)
        real_httpx = getattr(fern_http, "httpx_client", None)
        target = next(
            (c for c in (real_httpx, fern_http, client) if c is not None and hasattr(c, "close")),
            None,
        )
        if target is None:
            logger.debug("AioSandbox %s: no closable client found, nothing to release", self.id)
            return
        try:
            target.close()
        except Exception as e:
            logger.warning(f"Error closing AioSandbox client for {self.id}: {e}")
    @property
    def home_dir(self) -> str:
        """Get the home directory inside the sandbox."""
@@ -790,14 +790,20 @@ class AioSandboxProvider(SandboxProvider):
        thread on its next turn without a cold-start.  The container will only be
        stopped when the replicas limit forces eviction or during shutdown.
        The host-side HTTP client owned by the cached ``AioSandbox`` instance is
        closed before the instance is dropped (#2872). The warm-pool entry only
        stores ``SandboxInfo``, so a fresh ``AioSandbox`` (and a fresh client)
        is constructed if the container is later reclaimed.
        Args:
            sandbox_id: The ID of the sandbox to release.
        """
        info = None
        sandbox = None
        thread_ids_to_remove: list[str] = []
        with self._lock:
-            self._sandboxes.pop(sandbox_id, None)
+            sandbox = self._sandboxes.pop(sandbox_id, None)
            info = self._sandbox_infos.pop(sandbox_id, None)
            thread_ids_to_remove = [tid for tid, sid in self._thread_sandboxes.items() if sid == sandbox_id]
            for tid in thread_ids_to_remove:
@@ -807,6 +813,15 @@ class AioSandboxProvider(SandboxProvider):
            if info and sandbox_id not in self._warm_pool:
                self._warm_pool[sandbox_id] = (info, time.time())
        if sandbox is not None:
            # Defense-in-depth: close() already swallows its own errors; this
            # guard only protects against a future close() that misbehaves, so
            # host-side client cleanup can never block parking in the warm pool.
            try:
                sandbox.close()
            except Exception as e:
                logger.warning(f"Error closing sandbox {sandbox_id} during release: {e}")
        logger.info(f"Released sandbox {sandbox_id} to warm pool (container still running)")
    def destroy(self, sandbox_id: str) -> None:
@@ -815,14 +830,19 @@ class AioSandboxProvider(SandboxProvider):
        Unlike release(), this actually stops the container.  Use this for
        explicit cleanup, capacity-driven eviction, or shutdown.
        The host-side HTTP client owned by the cached ``AioSandbox`` instance is
        closed alongside backend/container destruction so no client/socket
        resources leak (#2872).
        Args:
            sandbox_id: The ID of the sandbox to destroy.
        """
        info = None
        sandbox = None
        thread_ids_to_remove: list[str] = []
        with self._lock:
-            self._sandboxes.pop(sandbox_id, None)
+            sandbox = self._sandboxes.pop(sandbox_id, None)
            info = self._sandbox_infos.pop(sandbox_id, None)
            thread_ids_to_remove = [tid for tid, sid in self._thread_sandboxes.items() if sid == sandbox_id]
            for tid in thread_ids_to_remove:
@@ -834,6 +854,15 @@ class AioSandboxProvider(SandboxProvider):
            else:
                self._warm_pool.pop(sandbox_id, None)
        if sandbox is not None:
            # Defense-in-depth: close() already swallows its own errors; this
            # guard only protects against a future close() that misbehaves, so
            # host-side client cleanup can never block container destruction.
            try:
                sandbox.close()
            except Exception as e:
                logger.warning(f"Error closing sandbox {sandbox_id} during destroy: {e}")
        if info:
            self._backend.destroy(info)
            logger.info(f"Destroyed sandbox {sandbox_id}")
@@ -11,12 +11,85 @@ from deerflow.config import get_app_config
 logger = logging.getLogger(__name__)
 DEFAULT_BACKEND = "auto"
 DEFAULT_REGION = "wt-wt"
 DEFAULT_SAFESEARCH = "moderate"
 DEFAULT_WIKIPEDIA_REGION = "us-en"
 WIKIPEDIA_BACKENDS = {"auto", "all", "wikipedia"}
 WIKIPEDIA_LANGUAGE_ALIASES = {
    "jp": "ja",
    "kr": "ko",
    "tzh": "zh",
    "wt": "en",
 }
 def _normalize_backend(backend: str | list[str] | tuple[str, ...] | None) -> str:
    if backend is None:
        return DEFAULT_BACKEND
    if isinstance(backend, (list, tuple)):
        return ",".join(str(part).strip() for part in backend if str(part).strip()) or DEFAULT_BACKEND
    return str(backend).strip() or DEFAULT_BACKEND
 def _normalize_setting(value: str | None, default: str) -> str:
    return str(value).strip() if value else default
 def _backend_includes_wikipedia(backend: str | list[str] | tuple[str, ...] | None) -> bool:
    backend = _normalize_backend(backend)
    return any(part.strip().lower() in WIKIPEDIA_BACKENDS for part in backend.split(","))
 def _contains_codepoint(query: str, ranges: tuple[tuple[int, int], ...]) -> bool:
    return any(start <= ord(char) <= end for char in query for start, end in ranges)
 def _infer_wikipedia_region(query: str) -> str:
    """Pick a valid Wikipedia language region when DDGS' worldwide region is used."""
    if _contains_codepoint(query, ((0x3040, 0x30FF), (0x31F0, 0x31FF))):
        return "jp-ja"
    if _contains_codepoint(query, ((0xAC00, 0xD7AF), (0x1100, 0x11FF), (0x3130, 0x318F))):
        return "kr-ko"
    if _contains_codepoint(query, ((0x3400, 0x9FFF),)):
        return "cn-zh"
    if _contains_codepoint(query, ((0x0400, 0x04FF),)):
        return "ru-ru"
    if _contains_codepoint(query, ((0x0370, 0x03FF),)):
        return "gr-el"
    if _contains_codepoint(query, ((0x0590, 0x05FF),)):
        return "il-he"
    if _contains_codepoint(query, ((0x0600, 0x06FF),)):
        return "xa-ar"
    return DEFAULT_WIKIPEDIA_REGION
 def _resolve_ddgs_region(query: str, region: str | None, backend: str | list[str] | tuple[str, ...] | None) -> str:
    """
    DDGS' wikipedia engine treats the second part of region as a Wikipedia
    subdomain. Its default worldwide region, wt-wt, becomes wt.wikipedia.org.
    """
    normalized_region = _normalize_setting(region, DEFAULT_REGION).lower()
    if not _backend_includes_wikipedia(backend):
        return normalized_region
    if normalized_region == DEFAULT_REGION:
        return _infer_wikipedia_region(query)
    if "-" not in normalized_region:
        return DEFAULT_WIKIPEDIA_REGION
    country, language = normalized_region.split("-", 1)
    return f"{country}-{WIKIPEDIA_LANGUAGE_ALIASES.get(language, language)}"
 def _search_text(
    query: str,
    max_results: int = 5,
-    region: str = "wt-wt",
+    region: str | None = DEFAULT_REGION,
-    safesearch: str = "moderate",
+    safesearch: str | None = DEFAULT_SAFESEARCH,
    backend: str | list[str] | tuple[str, ...] | None = DEFAULT_BACKEND,
 ) -> list[dict]:
    """
    Execute text search using DuckDuckGo.
@@ -26,6 +99,7 @@ def _search_text(
        max_results: Maximum number of results
        region: Search region
        safesearch: Safe search level
        backend: DDGS backend(s), e.g. "auto", "duckduckgo", or "duckduckgo,brave"
    Returns:
        List of search results
@@ -39,11 +113,15 @@ def _search_text(
    ddgs = DDGS(timeout=30)
    try:
        backend = _normalize_backend(backend)
        safesearch = _normalize_setting(safesearch, DEFAULT_SAFESEARCH)
        effective_region = _resolve_ddgs_region(query, region, backend)
        results = ddgs.text(
            query,
-            region=region,
+            region=effective_region,
            safesearch=safesearch,
            max_results=max_results,
            backend=backend,
        )
        return list(results) if results else []
@@ -64,14 +142,23 @@ def web_search_tool(
        max_results: Maximum number of results to return. Default is 5.
    """
    config = get_app_config().get_tool_config("web_search")
    region = DEFAULT_REGION
    safesearch = DEFAULT_SAFESEARCH
    backend = DEFAULT_BACKEND
-    # Override max_results from config if set
+    if config is not None:
-    if config is not None and "max_results" in config.model_extra:
+        # Override tool call defaults from config if set.
        max_results = config.model_extra.get("max_results", max_results)
        region = config.model_extra.get("region", region)
        safesearch = config.model_extra.get("safesearch", safesearch)
        backend = config.model_extra.get("backend", backend)
    results = _search_text(
        query=query,
        max_results=max_results,
        region=region,
        safesearch=safesearch,
        backend=backend,
    )
    if not results:
@@ -18,6 +18,7 @@ from deerflow.config.guardrails_config import GuardrailsConfig, load_guardrails_
 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.reload_boundary import format_field_description
 from deerflow.config.run_events_config import RunEventsConfig
 from deerflow.config.runtime_paths import existing_project_file
 from deerflow.config.safety_finish_reason_config import SafetyFinishReasonConfig
@@ -85,10 +86,21 @@ def apply_logging_level(name: str | None) -> None:
 class AppConfig(BaseModel):
    """Config for the DeerFlow application"""
-    log_level: str = Field(default="info", description="Logging level for deerflow and app modules (debug/info/warning/error); third-party libraries are not affected")
+    log_level: str = Field(
        default="info",
        description=format_field_description(
            "log_level",
            field_doc="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")
+    sandbox: SandboxConfig = Field(
        description=format_field_description(
            "sandbox",
            field_doc="Sandbox provider configuration (local filesystem or Docker-based aio sandbox).",
        ),
    )
    tools: list[ToolConfig] = Field(default_factory=list, description="Available tools")
    tool_groups: list[ToolGroupConfig] = Field(default_factory=list, description="Available tool groups")
    skills: SkillsConfig = Field(default_factory=SkillsConfig, description="Skills configuration")
@@ -107,10 +119,34 @@ class AppConfig(BaseModel):
    loop_detection: LoopDetectionConfig = Field(default_factory=LoopDetectionConfig, description="Loop detection middleware configuration")
    safety_finish_reason: SafetyFinishReasonConfig = Field(default_factory=SafetyFinishReasonConfig, description="Provider safety-filter finish_reason interception middleware configuration")
    model_config = ConfigDict(extra="allow")
-    database: DatabaseConfig = Field(default_factory=DatabaseConfig, description="Unified database backend configuration")
+    database: DatabaseConfig = Field(
-    run_events: RunEventsConfig = Field(default_factory=RunEventsConfig, description="Run event storage configuration")
+        default_factory=DatabaseConfig,
-    checkpointer: CheckpointerConfig | None = Field(default=None, description="Checkpointer configuration")
+        description=format_field_description(
-    stream_bridge: StreamBridgeConfig | None = Field(default=None, description="Stream bridge configuration")
+            "database",
            field_doc="Unified database backend for run/feedback metadata (memory, sqlite, or postgres).",
        ),
    )
    run_events: RunEventsConfig = Field(
        default_factory=RunEventsConfig,
        description=format_field_description(
            "run_events",
            field_doc="Run-event store backend (memory for dev, db for production queries, jsonl for lightweight single-node persistence).",
        ),
    )
    checkpointer: CheckpointerConfig | None = Field(
        default=None,
        description=format_field_description(
            "checkpointer",
            field_doc="LangGraph state-persistence checkpointer configuration.",
        ),
    )
    stream_bridge: StreamBridgeConfig | None = Field(
        default=None,
        description=format_field_description(
            "stream_bridge",
            field_doc="Stream bridge connecting agent workers to SSE endpoints.",
        ),
    )
    @classmethod
    def resolve_config_path(cls, config_path: str | None = None) -> Path:
@@ -41,6 +41,20 @@ def set_checkpointer_config(config: CheckpointerConfig | None) -> None:
    _checkpointer_config = config
 def ensure_config_loaded() -> None:
    """Lazily load app config when checkpointer config has not been initialized."""
    from deerflow.config.app_config import _app_config, get_app_config
    config = get_checkpointer_config()
    if config is not None or _app_config is not None:
        return
    try:
        get_app_config()
    except FileNotFoundError:
        pass
 def load_checkpointer_config_from_dict(config_dict: dict | None) -> None:
    """Load checkpointer configuration from a dictionary."""
    global _checkpointer_config
@@ -5,7 +5,7 @@ import os
 from pathlib import Path
 from typing import Any, Literal
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 from deerflow.config.runtime_paths import existing_project_file
@@ -47,6 +47,24 @@ class McpServerConfig(BaseModel):
    description: str = Field(default="", description="Human-readable description of what this MCP server provides")
    model_config = ConfigDict(extra="allow")
    @model_validator(mode="before")
    @classmethod
    def _accept_transport_alias(cls, data: Any) -> Any:
        """Accept the MCP-spec ``transport`` field as an alias for ``type``.
        The official MCP configuration schema uses ``transport`` to indicate
        the transport mechanism (``stdio``/``sse``/``http``). Earlier versions
        of this project only honored ``type``, which caused remote SSE/HTTP
        servers configured with just ``transport`` to be incorrectly treated as
        ``stdio`` (the default). This validator normalizes the two so either
        spelling works, with ``type`` taking precedence when both are provided.
        """
        if isinstance(data, dict):
            transport = data.get("transport")
            if transport and not data.get("type"):
                data = {**data, "type": transport}
        return data
 class SkillStateConfig(BaseModel):
    """Configuration for a single skill's state."""
@@ -32,6 +32,16 @@ class ModelConfig(BaseModel):
        description="Extra settings to be passed to the model when thinking is disabled",
    )
    supports_vision: bool = Field(default_factory=lambda: False, description="Whether the model supports vision/image inputs")
    stream_chunk_timeout: float | None = Field(
        default=None,
        description=(
            "Maximum seconds to wait between successive streaming chunks before "
            "langchain-openai raises StreamChunkTimeoutError. None means use the "
            "factory default (240s for OpenAI-compatible clients). Tune higher for "
            "reasoning models with long thinking pauses; lower for latency-sensitive "
            "interactive endpoints. Has no effect on non-OpenAI-compatible providers."
        ),
    )
    thinking: dict | None = Field(
        default_factory=lambda: None,
        description=(
@@ -1,3 +1,4 @@
 import hashlib
 import os
 import re
 import shutil
@@ -10,6 +11,8 @@ VIRTUAL_PATH_PREFIX = "/mnt/user-data"
 _SAFE_THREAD_ID_RE = re.compile(r"^[A-Za-z0-9_\-]+$")
 _SAFE_USER_ID_RE = re.compile(r"^[A-Za-z0-9_\-]+$")
 _UNSAFE_USER_ID_CHAR_RE = re.compile(r"[^A-Za-z0-9_\-]")
 _SAFE_USER_ID_DIGEST_HEX_LEN = 16
 def _default_local_base_dir() -> Path:
@@ -31,6 +34,23 @@ def _validate_user_id(user_id: str) -> str:
    return user_id
 def make_safe_user_id(raw: str) -> str:
    """Normalize an external identity into the user-id charset (``[A-Za-z0-9_-]``).
    IM channel ids (Feishu/Slack/Telegram) may contain characters that
    :func:`_validate_user_id` rejects. Already-safe ids pass through unchanged;
    lossy ones get a short digest suffix so two distinct inputs never share a
    storage bucket.
    """
    if not raw:
        raise ValueError("user_id must be a non-empty string.")
    sanitized = _UNSAFE_USER_ID_CHAR_RE.sub("-", raw)
    if sanitized == raw:
        return raw
    digest = hashlib.sha1(raw.encode("utf-8")).hexdigest()[:_SAFE_USER_ID_DIGEST_HEX_LEN]
    return f"{sanitized}-{digest}"
 def _join_host_path(base: str, *parts: str) -> str:
    """Join host filesystem path segments while preserving native style.
@@ -0,0 +1,104 @@
 """Single source of truth for the config hot-reload boundary.
 Bytedance/deer-flow issue #3144: gateway request dependencies resolve
 ``AppConfig`` through ``get_app_config()`` on every request, so per-run
 fields take effect on the next message without restarting the gateway.
 The fields listed in this module are the **infrastructure** subset that
 the gateway captures once at startup — engines, singletons, IM clients,
 the logging handler — and that therefore require a process restart to
 change at runtime.
 The registry covers two kinds of entries:
 - Top-level ``AppConfig`` fields (``database``, ``checkpointer``,
  ``run_events``, ``stream_bridge``, ``sandbox``, ``log_level``). For
  these, :func:`format_field_description` produces the standardised
  ``"startup-only: ..."`` prefix that the matching Pydantic
  ``Field(description=...)`` carries, so the boundary surfaces in IDE
  hover next to the field itself.
 - Top-level ``config.yaml`` sections that are not part of the
  ``AppConfig`` schema (``channels``). These cannot be standardised at
  the schema level, so the registry is their only canonical location.
 Any future "needs restart" scanner — operator tooling, lint hooks, doc
 generators — should drive off this registry rather than re-parsing
 prose.
 """
 from __future__ import annotations
 from collections.abc import Iterator
 #: The standardised prefix every restart-required field description starts
 #: with. ``test_reload_boundary`` enforces both directions: registered
 #: fields must use this prefix in the schema, and any schema field using
 #: this prefix must be in the registry.
 STARTUP_ONLY_PREFIX = "startup-only:"
 #: Restart-required field paths mapped to the human-readable reason.
 #:
 #: The reason text is what surfaces in ``Field(description=...)``, so it
 #: must explain *what* code captures the snapshot — not just that the
 #: field is restart-required — so an operator changing the value knows
 #: which subsystem to restart.
 STARTUP_ONLY_FIELDS: dict[str, str] = {
    "database": ("init_engine_from_config() runs once during langgraph_runtime() startup; the SQLAlchemy engine holds the connection pool and is not rebuilt on config.yaml edits."),
    "checkpointer": ("make_checkpointer() binds the persistent checkpointer once at startup, including SQLite WAL / busy_timeout settings."),
    "run_events": ("make_run_event_store() picks the memory- vs SQL-backed implementation at startup and is frozen onto app.state.run_events_config to stay paired with the underlying event store."),
    "stream_bridge": ("make_stream_bridge() constructs the stream-bridge singleton once during startup."),
    "sandbox": ("get_sandbox_provider() caches the provider singleton (``_default_sandbox_provider``); a different ``sandbox.use`` class path only takes effect on next process start."),
    "log_level": (
        "apply_logging_level() runs only during app.py startup; it sets the deerflow/app logger levels and may lower root handler thresholds so configured messages can propagate. A freshly reloaded AppConfig does not retrigger it."
    ),
    # Not part of the AppConfig Pydantic schema — channel credentials are
    # consumed directly by ``start_channel_service()`` once at lifespan
    # startup and the live channel clients are not rebuilt on
    # config.yaml edits.
    "channels": ("start_channel_service() is invoked once during startup; the live IM channel clients (Feishu, Slack, Telegram, DingTalk) are not rebuilt when channels.* changes."),
 }
 def iter_startup_only_field_paths() -> Iterator[str]:
    """Yield every registered restart-required field path."""
    return iter(STARTUP_ONLY_FIELDS)
 def is_startup_only_field(field_path: str) -> bool:
    """Return ``True`` when *field_path* is registered as restart-required.
    Accepts only top-level paths (``"database"``, ``"sandbox"`` etc.);
    nested keys like ``"database.url"`` are not modelled here because the
    boundary is per-section, not per-leaf.
    """
    return field_path in STARTUP_ONLY_FIELDS
 def format_field_description(field_path: str, *, field_doc: str | None = None) -> str:
    """Build the standardised description for a registered field.
    Used inside ``AppConfig`` ``Field(description=...)`` so the hover
    text in IDEs matches the registry and the drift tests can pin one
    side against the other.
    Args:
        field_path: A registered top-level field path (e.g. ``"log_level"``).
        field_doc: Optional human-facing description for the field itself
            (allowed values, semantics, etc.). When supplied, it is
            appended after the ``startup-only:`` marker block separated by
            a blank line so IDE hover shows both the restart-required
            reason *and* the field's normal documentation. Composition
            keeps the marker as the leading token machine-readable tooling
            pivots on while restoring the prose that ``Field(description=)``
            used to carry before the registry took over.
    Raises:
        KeyError: when *field_path* is not registered. This is deliberate
            — silently returning a placeholder would let a typo bypass
            the drift coverage.
    """
    reason = STARTUP_ONLY_FIELDS[field_path]
    header = f"{STARTUP_ONLY_PREFIX} {reason}"
    if field_doc is None:
        return header
    return f"{header}\n\n{field_doc.strip()}"
@@ -1,6 +1,10 @@
 """MCP (Model Context Protocol) integration using langchain-mcp-adapters."""
-from .cache import get_cached_mcp_tools, initialize_mcp_tools, reset_mcp_tools_cache
+from .cache import (
    get_cached_mcp_tools,
    initialize_mcp_tools,
    reset_mcp_tools_cache,
 )
 from .client import build_server_params, build_servers_config
 from .tools import get_mcp_tools
@@ -143,11 +143,20 @@ def reset_mcp_tools_cache() -> None:
    # Close persistent sessions – they will be recreated by the next
    # get_mcp_tools() call with the (possibly updated) connection config.
    #
    # close_all_sync() already picks the correct strategy per owning loop:
    #   * sessions owned by the *current* running loop are only *signalled*
    #     (their owner task runs __aexit__ once the loop regains control –
    #     this is correct and leak-free, since the loop keeps the task alive),
    #   * sessions on other threads' loops are torn down deterministically,
    #   * idle/closed loops are handled or skipped.
    # We deliberately do NOT try to synchronously wait for the current running
    # loop to finish teardown here: that is a self-deadlock (the loop can only
    # run the teardown after this synchronous call returns control to it).
    try:
        from deerflow.mcp.session_pool import get_session_pool
-        pool = get_session_pool()
+        get_session_pool().close_all_sync()
        pool.close_all_sync()
    except Exception:
        logger.debug("Could not close MCP session pool on cache reset", exc_info=True)
@@ -8,6 +8,27 @@ This module provides a session pool that maintains persistent MCP sessions,
 scoped by ``(server_name, scope_key)`` — typically scope_key is the thread_id —
 so that consecutive tool calls share the same session and server-side state.
 Sessions are evicted in LRU order when the pool reaches capacity.
 Lifecycle model (owner task)
 ----------------------------
 An MCP ``ClientSession`` is implemented on top of an ``anyio`` task group, and
 anyio enforces that a cancel scope must be exited from the *same task* that
 entered it. Calling ``cm.__aexit__`` from any task other than the one that ran
 ``cm.__aenter__`` raises::
    RuntimeError: Attempted to exit cancel scope in a different task than it
    was entered in
 The sync-tool path (``make_sync_tool_wrapper``) drives each call through a fresh
 ``asyncio.run`` event loop, so a session entered while answering one call would
 otherwise be exited while answering another — from a different task — and crash
 (GitHub issue #3379).
 To make this impossible, every pooled session is owned by a dedicated
 ``_run_session`` task. That task enters the context manager, hands the live
 session back to the caller, and then *waits* on a close event. All shutdown
 paths only ever **signal** that event; the owner task performs ``__aexit__``
 itself, guaranteeing enter and exit always happen in the same task.
 """
 from __future__ import annotations
@@ -27,18 +48,81 @@ class MCPSessionPool:
    """Manages persistent MCP sessions scoped by ``(server_name, scope_key)``."""
    MAX_SESSIONS = 256
-    SESSION_CLOSE_TIMEOUT = 5.0  # seconds to wait when closing a session via run_coroutine_threadsafe
+    SESSION_CLOSE_TIMEOUT = 5.0  # seconds to wait when closing a session on a foreign loop
    def __init__(self) -> None:
        # Each entry: (session, owning_loop, owner_task, close_event).
        self._entries: OrderedDict[
            tuple[str, str],
-            tuple[ClientSession, asyncio.AbstractEventLoop],
+            tuple[
                ClientSession,
                asyncio.AbstractEventLoop,
                asyncio.Task[Any],
                asyncio.Event,
            ],
        ] = OrderedDict()
-        self._context_managers: dict[tuple[str, str], Any] = {}
+        # In-flight creations, keyed by (server, scope). Lets concurrent callers
        # on the same loop share a single creation instead of each spawning a
        # duplicate session. Value: (loop, ready_future, owner_task, close_event).
        self._inflight: dict[
            tuple[str, str],
            tuple[
                asyncio.AbstractEventLoop,
                asyncio.Future[ClientSession],
                asyncio.Task[Any],
                asyncio.Event,
            ],
        ] = {}
        # threading.Lock is not bound to any event loop, so it is safe to
        # acquire from both async paths and sync/worker-thread paths.
        self._lock = threading.Lock()
    # ------------------------------------------------------------------
    # Session owner task
    # ------------------------------------------------------------------
    async def _run_session(
        self,
        connection: dict[str, Any],
        ready: asyncio.Future[ClientSession],
        close_evt: asyncio.Event,
    ) -> None:
        """Own a single MCP session for its entire lifetime.
        Enters the session context manager, initializes it, publishes the live
        session via ``ready``, then blocks until ``close_evt`` is set. The
        context manager is *always* exited from this task, satisfying anyio's
        cancel-scope same-task requirement.
        """
        from langchain_mcp_adapters.sessions import create_session
        cm = create_session(connection)
        try:
            session = await cm.__aenter__()
        except BaseException as e:
            # Never entered the cancel scope, so there is nothing to exit.
            if not ready.done():
                ready.set_exception(e)
            return
        # The context manager is now entered. From here on __aexit__ MUST run in
        # this task — on init failure, on cancellation, or on the close signal —
        # to satisfy anyio's same-task cancel-scope requirement and to avoid
        # leaking the session/subprocess.
        try:
            await session.initialize()
            if not ready.done():
                ready.set_result(session)
            await close_evt.wait()
        except BaseException as e:
            if not ready.done():
                ready.set_exception(e)
        finally:
            try:
                await cm.__aexit__(None, None, None)
            except Exception:
                logger.warning("Error closing MCP session", exc_info=True)
    async def get_session(
        self,
        server_name: str,
@@ -47,9 +131,9 @@ class MCPSessionPool:
    ) -> ClientSession:
        """Get or create a persistent MCP session.
-        If an existing session was created in a different event loop (e.g.
+        If an existing session was created in a different (or closed) event
-        the sync-wrapper path), it is closed and replaced with a fresh one
+        loop, it is evicted and replaced with a fresh one owned by a task on
-        in the current loop.
+        the current loop.
        Args:
            server_name: MCP server name.
@@ -63,44 +147,118 @@ class MCPSessionPool:
        current_loop = asyncio.get_running_loop()
        # Phase 1: inspect/mutate the registry under the thread lock (no awaits).
-        cms_to_close: list[tuple[tuple[str, str], Any]] = []
+        # Decide one of three outcomes atomically: return an existing session,
        # join an in-flight creation, or become the creator for this key.
        # Each item: (loop, owner_task, close_event, cancel). ``cancel`` is True
        # for in-flight creations, whose owner may be blocked inside
        # ``initialize()`` where close_evt cannot wake it — it must be cancelled.
        evicted: list[tuple[asyncio.AbstractEventLoop, asyncio.Task[Any], asyncio.Event, bool]] = []
        join: asyncio.Future[ClientSession] | None = None
        ready: asyncio.Future[ClientSession] | None = None
        close_evt: asyncio.Event | None = None
        task: asyncio.Task[Any] | None = None
        with self._lock:
            if key in self._entries:
-                session, loop = self._entries[key]
+                session, loop, ent_task, ent_close = self._entries[key]
-                if loop is current_loop:
+                if loop is current_loop and not loop.is_closed():
                    self._entries.move_to_end(key)
                    return session
-                # Session belongs to a different event loop – evict it.
+                # Session belongs to a different/closed event loop – evict it.
                cm = self._context_managers.pop(key, None)
                self._entries.pop(key)
-                if cm is not None:
+                evicted.append((loop, ent_task, ent_close, False))
-                    cms_to_close.append((key, cm))
+
            inflight = self._inflight.get(key)
            if inflight is not None and inflight[0] is current_loop and not inflight[0].is_closed():
                # Another caller on this loop is already creating the session;
                # wait for the same result instead of building a duplicate.
                join = inflight[1]
            else:
                if inflight is not None:
                    # Stale in-flight creation owned by a different/closed loop.
                    # Drop the record and tear its owner down; because that owner
                    # may be blocked inside initialize() (where close_evt cannot
                    # wake it), it must be cancelled. We then create a fresh
                    # session here.
                    self._inflight.pop(key)
                    evicted.append((inflight[0], inflight[2], inflight[3], True))
                # Become the creator: publish an in-flight record before any
                # await so concurrent callers join us instead of racing.
                ready = current_loop.create_future()
                close_evt = asyncio.Event()
                task = current_loop.create_task(self._run_session(connection, ready, close_evt))
                self._inflight[key] = (current_loop, ready, task, close_evt)
            # Evict LRU entries when at capacity.
            while len(self._entries) >= self.MAX_SESSIONS:
-                oldest_key = next(iter(self._entries))
+                oldest_key, (_, loop, ent_task, ent_close) = next(iter(self._entries.items()))
                cm = self._context_managers.pop(oldest_key, None)
                self._entries.pop(oldest_key)
-                if cm is not None:
+                evicted.append((loop, ent_task, ent_close, False))
                    cms_to_close.append((oldest_key, cm))
-        # Phase 2: async cleanup outside the lock so we never await while holding it.
+        # Phase 2: shut down evicted sessions/creations. Same-loop owners are
-        for close_key, cm in cms_to_close:
+        # awaited so they finish deterministically; foreign-loop owners are
        # routed to their own loop. In every case the owner task — never this
        # one — runs __aexit__. In-flight owners are cancelled (cancel=True) so a
        # blocking initialize() cannot leave them hung.
        for loop, ent_task, ent_close, cancel in evicted:
            if loop is current_loop and not loop.is_closed():
                await self._shutdown(ent_close, ent_task, cancel)
            elif cancel:
                await self._shutdown_entry(loop, ent_task, ent_close, cancel=True)
            else:
                self._signal_close(loop, ent_close)
        # Phase 2b: a concurrent creation for this key is already in progress on
        # this loop — share its result rather than create a duplicate session.
        if join is not None:
            return await asyncio.shield(join)
        assert ready is not None and close_evt is not None and task is not None
        # Phase 3: wait for our owner task to publish the initialized session.
        try:
            session = await asyncio.shield(ready)
        except BaseException:
            # Two distinct cases reach here:
            #
            # 1. The owner task failed (e.g. connect/initialize error) and
            #    reported it via ready.set_exception(). It is *already* in its
            #    finally block running cm.__aexit__ in its own task, so we must
            #    NOT cancel it — doing so would interrupt that cleanup. We only
            #    wait for it to finish unwinding.
            # 2. This call itself was cancelled (CancelledError). Because of the
            #    shield, `ready` is still pending and the owner task is alive and
            #    blocked. We signal close and cancel it so it exits the cancel
            #    scope in its own task, then wait for it to finish.
            #
            # The session is never registered yet, so nobody else can close it;
            # waiting here guarantees we never leak a session or owner task.
            owner_already_failed = ready.done() and not ready.cancelled() and ready.exception() is not None
            if not owner_already_failed:
                close_evt.set()
                task.cancel()
            try:
-                await cm.__aexit__(None, None, None)
+                await asyncio.shield(task)
-            except Exception:
+            except BaseException:
-                logger.warning("Error closing MCP session %s", close_key, exc_info=True)
+                logger.debug("Owner task ended during get_session unwind", exc_info=True)
            with self._lock:
                if self._inflight.get(key) == (current_loop, ready, task, close_evt):
                    self._inflight.pop(key)
            raise
-        from langchain_mcp_adapters.sessions import create_session
+        # Phase 4: promote the in-flight creation to a registered entry — but
-
+        # only if our in-flight record is still the live one. A concurrent
-        cm = create_session(connection)
+        # close_* / close_all may have removed it while we were initializing; in
-        session = await cm.__aenter__()
+        # that case we must NOT resurrect the session into _entries. Instead we
-        await session.initialize()
+        # own the teardown: signal our owner task and wait for it to run
-
+        # __aexit__ in its own task, then surface the cancellation.
        # Phase 3: register the new session under the lock.
        with self._lock:
-            self._entries[key] = (session, current_loop)
+            still_ours = self._inflight.get(key) == (current_loop, ready, task, close_evt)
-            self._context_managers[key] = cm
+            if still_ours:
                self._inflight.pop(key)
                self._entries[key] = (session, current_loop, task, close_evt)
        if not still_ours:
            await self._shutdown(close_evt, task)
            raise asyncio.CancelledError("MCP session pool was closed while the session was being created")
        logger.info("Created persistent MCP session for %s/%s", server_name, scope_key)
        return session
@@ -108,70 +266,169 @@ class MCPSessionPool:
    # Cleanup helpers
    # ------------------------------------------------------------------
-    async def _close_cm(self, key: tuple[str, str], cm: Any) -> None:
+    @staticmethod
-        """Close a single context manager (must be called WITHOUT the lock)."""
+    def _signal_close(loop: asyncio.AbstractEventLoop, close_evt: asyncio.Event) -> None:
        """Ask an owner task to shut down without waiting.
        ``asyncio.Event.set`` is not thread-safe, so it is scheduled on the
        owning loop. A closed loop means the owner task is already gone.
        """
        if loop.is_closed():
            return
        try:
-            await cm.__aexit__(None, None, None)
+            loop.call_soon_threadsafe(close_evt.set)
-        except Exception:
+        except RuntimeError:
-            logger.warning("Error closing MCP session %s", key, exc_info=True)
+            # Loop was closed between the is_closed() check and now.
            pass
    async def _shutdown(
        self,
        close_evt: asyncio.Event,
        task: asyncio.Task[Any],
        cancel: bool = False,
    ) -> None:
        """Signal an owner task and wait for it to finish (runs on its loop).
        ``cancel=True`` is used for in-flight creations: the owner task may be
        blocked inside ``initialize()`` where ``close_evt`` cannot wake it, so it
        must be cancelled. Its ``finally`` block still runs ``__aexit__`` in its
        own task, satisfying anyio's same-task cancel-scope requirement.
        """
        close_evt.set()
        if cancel:
            task.cancel()
        try:
            await task
        except (Exception, asyncio.CancelledError):
            logger.debug("Owner task ended during shutdown", exc_info=True)
    async def _shutdown_entry(
        self,
        loop: asyncio.AbstractEventLoop,
        task: asyncio.Task[Any],
        close_evt: asyncio.Event,
        cancel: bool = False,
    ) -> None:
        """Shut down one entry, routing the close to its owning loop."""
        if loop.is_closed():
            return
        current_loop = asyncio.get_running_loop()
        if loop is current_loop:
            await self._shutdown(close_evt, task, cancel)
        elif loop.is_running():
            future = asyncio.run_coroutine_threadsafe(self._shutdown(close_evt, task, cancel), loop)
            try:
                await asyncio.wrap_future(future)
            except Exception:
                logger.warning("Error closing MCP session on owning loop", exc_info=True)
        else:
            # Owning loop exists but is neither the current loop nor running.
            # We are inside an async context here, so run_until_complete() would
            # raise "Cannot run the event loop while another loop is running";
            # and the loop may belong to another thread, where driving it from
            # here is unsafe. This branch is not expected in practice — a
            # session's owning loop is either the long-lived gateway loop (which
            # is running) or a short-lived asyncio.run loop (which is closed and
            # caught above). Fall back to a best-effort thread-safe signal so the
            # owner task tears down if/when its loop runs again.
            logger.warning("Owning loop for MCP session is idle; signalling close best-effort. Session may leak until the loop runs again.")
            self._signal_close(loop, close_evt)
            if cancel:
                try:
                    loop.call_soon_threadsafe(task.cancel)
                except RuntimeError:
                    pass
    async def close_scope(self, scope_key: str) -> None:
        """Close all sessions for a given scope (e.g. thread_id)."""
        with self._lock:
            keys = [k for k in self._entries if k[1] == scope_key]
-            cms = [(k, self._context_managers.pop(k, None)) for k in keys]
+            entries = [(self._entries.pop(k)) for k in keys]
-            for k in keys:
+            inflight_keys = [k for k in self._inflight if k[1] == scope_key]
-                self._entries.pop(k, None)
+            inflight = [self._inflight.pop(k) for k in inflight_keys]
-        for key, cm in cms:
+        for _session, loop, task, close_evt in entries:
-            if cm is not None:
+            await self._shutdown_entry(loop, task, close_evt)
-                await self._close_cm(key, cm)
+        for loop, _ready, task, close_evt in inflight:
            await self._shutdown_entry(loop, task, close_evt, cancel=True)
    async def close_server(self, server_name: str) -> None:
        """Close all sessions for a given server."""
        with self._lock:
            keys = [k for k in self._entries if k[0] == server_name]
-            cms = [(k, self._context_managers.pop(k, None)) for k in keys]
+            entries = [(self._entries.pop(k)) for k in keys]
-            for k in keys:
+            inflight_keys = [k for k in self._inflight if k[0] == server_name]
-                self._entries.pop(k, None)
+            inflight = [self._inflight.pop(k) for k in inflight_keys]
-        for key, cm in cms:
+        for _session, loop, task, close_evt in entries:
-            if cm is not None:
+            await self._shutdown_entry(loop, task, close_evt)
-                await self._close_cm(key, cm)
+        for loop, _ready, task, close_evt in inflight:
            await self._shutdown_entry(loop, task, close_evt, cancel=True)
    async def close_all(self) -> None:
        """Close every managed session."""
        with self._lock:
-            cms = list(self._context_managers.items())
+            entries = list(self._entries.values())
            self._context_managers.clear()
            self._entries.clear()
-        for key, cm in cms:
+            inflight = list(self._inflight.values())
-            await self._close_cm(key, cm)
+            self._inflight.clear()
        for _session, loop, task, close_evt in entries:
            await self._shutdown_entry(loop, task, close_evt)
        for loop, _ready, task, close_evt in inflight:
            await self._shutdown_entry(loop, task, close_evt, cancel=True)
    def close_all_sync(self) -> None:
-        """Close all sessions using their owning event loops (synchronous).
+        """Close all sessions on their owning event loops (synchronous).
-        Each session is closed on the loop it was created in, avoiding
+        Each session is closed by its owner task on the loop it was created in,
-        cross-loop resource leaks.  Safe to call from any thread without an
+        avoiding cross-loop and cross-task errors. Safe to call from any thread
-        active event loop.
+        without an active event loop.
        Closing semantics differ by where the owning loop runs:
        * Owning loop is idle, or running on another thread — this call blocks
          until teardown completes (or ``SESSION_CLOSE_TIMEOUT`` elapses).
        * Owning loop is the one currently running on *this* thread — we cannot
          block on it without deadlocking, so teardown is only *signalled* here
          and completes asynchronously once control returns to that loop. The
          caller must therefore keep that loop running afterwards; if it stops
          the loop immediately, the owner task's ``__aexit__`` may not run. When
          a deterministic close is required from inside a running loop, ``await
          close_all()`` instead.
        """
        with self._lock:
-            entries = list(self._entries.items())
+            entries = list(self._entries.values())
            cms = dict(self._context_managers)
            self._entries.clear()
-            self._context_managers.clear()
+            inflight = list(self._inflight.values())
            self._inflight.clear()
-        for key, (_, loop) in entries:
+        # Entries are initialized (gentle close_evt path). In-flight creations
-            cm = cms.get(key)
+        # may be blocked mid-init, so they are cancelled to unblock teardown.
-            if cm is None or loop.is_closed():
+        owners = [(loop, task, close_evt, False) for _s, loop, task, close_evt in entries]
        owners += [(loop, task, close_evt, True) for loop, _r, task, close_evt in inflight]
        try:
            current_running_loop = asyncio.get_running_loop()
        except RuntimeError:
            current_running_loop = None
        for loop, task, close_evt, cancel in owners:
            if loop.is_closed():
                continue
            try:
-                if loop.is_running():
+                if loop is current_running_loop:
-                    # Schedule on the owning loop from this (different) thread.
+                    # We are executing inside this loop's thread, so synchronously
-                    future = asyncio.run_coroutine_threadsafe(cm.__aexit__(None, None, None), loop)
+                    # waiting on run_coroutine_threadsafe(...).result() would
                    # deadlock until timeout. Signal the owner task directly and
                    # let it finish once this synchronous call returns control to
                    # the running loop.
                    close_evt.set()
                    if cancel:
                        task.cancel()
                elif loop.is_running():
                    # Schedule the shutdown on the owning loop from this thread.
                    future = asyncio.run_coroutine_threadsafe(self._shutdown(close_evt, task, cancel), loop)
                    future.result(timeout=self.SESSION_CLOSE_TIMEOUT)
                else:
-                    loop.run_until_complete(cm.__aexit__(None, None, None))
+                    loop.run_until_complete(self._shutdown(close_evt, task, cancel))
            except Exception:
-                logger.debug("Error closing MCP session %s during sync close", key, exc_info=True)
+                logger.debug("Error closing MCP session during sync close", exc_info=True)
 # ------------------------------------------------------------------
@@ -3,6 +3,7 @@
 from __future__ import annotations
 import logging
 from collections.abc import Mapping
 from typing import Any
 from langchain_core.tools import BaseTool, StructuredTool
@@ -137,7 +138,15 @@ def _make_session_pool_tool(
            from langchain_mcp_adapters.interceptors import MCPToolCallRequest
            async def base_handler(request: MCPToolCallRequest) -> Any:
-                return await session.call_tool(request.name, request.args)
+                # Preserve interceptor-injected headers for stdio MCP calls by
                # forwarding them through MCP call meta.
                call_kwargs: dict[str, Any] = {}
                if request.headers:
                    if isinstance(request.headers, Mapping):
                        call_kwargs["meta"] = {"headers": dict(request.headers)}
                    else:
                        logger.warning("Ignoring MCP interceptor headers with unsupported type: %s", type(request.headers).__name__)
                return await session.call_tool(request.name, request.args, **call_kwargs)
            handler = base_handler
            for interceptor in reversed(tool_interceptors):
@@ -47,6 +47,38 @@ def _enable_stream_usage_by_default(model_use_path: str, model_settings_from_con
        model_settings_from_config["stream_usage"] = True
 # Default chunk-gap budget for OpenAI-compatible streaming responses.
 #
 # langchain-openai raises ``StreamChunkTimeoutError`` after this many seconds
 # without receiving a chunk. Its own default is 60s, which is too aggressive for
 # reasoning models (DeepSeek-R1, Doubao-thinking, GPT-5) whose first chunk can
 # legitimately take 90~150s. We default to 240s so the streaming layer rarely
 # trips on long thinking pauses; the LLMErrorHandlingMiddleware still retries
 # (budget=2) if a real stall happens. Users can override per-model in config.yaml.
 _DEFAULT_STREAM_CHUNK_TIMEOUT_SECONDS: float = 240.0
 def _apply_stream_chunk_timeout_default(model_use_path: str, model_settings_from_config: dict) -> None:
    """Inject a generous ``stream_chunk_timeout`` for OpenAI-compatible clients.
    The ``stream_chunk_timeout`` kwarg is specific to ``langchain_openai:ChatOpenAI``
    and is rejected by other providers' constructors as an unexpected keyword
    argument. Behaviour:
    * OpenAI-compatible path: an explicit value in ``config.yaml`` is preserved.
      An explicit ``null`` is dropped upstream by ``model_dump(exclude_none=True)``
      and therefore treated as "unset", so the default is injected.
    * Non-OpenAI path: drop the key so it is never forwarded to an incompatible
      constructor (which would raise ``TypeError: unexpected keyword argument``).
    """
    if model_use_path != "langchain_openai:ChatOpenAI":
        model_settings_from_config.pop("stream_chunk_timeout", None)
        return
    if "stream_chunk_timeout" in model_settings_from_config:
        return
    model_settings_from_config["stream_chunk_timeout"] = _DEFAULT_STREAM_CHUNK_TIMEOUT_SECONDS
 def create_chat_model(name: str | None = None, thinking_enabled: bool = False, *, app_config: AppConfig | None = None, attach_tracing: bool = True, **kwargs) -> BaseChatModel:
    """Create a chat model instance from the config.
@@ -128,6 +160,7 @@ def create_chat_model(name: str | None = None, thinking_enabled: bool = False, *
        model_settings_from_config.pop("reasoning_effort", None)
    _enable_stream_usage_by_default(model_config.use, model_settings_from_config)
    _apply_stream_chunk_timeout_default(model_config.use, model_settings_from_config)
    # For Codex Responses API models: map thinking mode to reasoning_effort
    from deerflow.models.openai_codex_provider import CodexChatModel
@@ -114,8 +114,27 @@ class PatchedChatMiniMax(ChatOpenAI):
            }
        else:
            payload["extra_body"] = {"reasoning_split": True}
        self._strip_user_message_names(payload)
        return payload
    @staticmethod
    def _strip_user_message_names(payload: dict) -> None:
        """Drop the per-message ``name`` field from user-role messages.
        DeerFlow middlewares tag user messages with internal provenance names
        (``user-input``, ``summary``, ``loop_warning``, ...). ``langchain_openai``
        serializes those into the OpenAI-compatible request, but MiniMax requires
        every user-role ``name`` to be identical and otherwise rejects the request
        with ``invalid params, user name must be consistent (2013)``. MiniMax does
        not use the per-message author name, so strip it.
        """
        messages = payload.get("messages")
        if not isinstance(messages, list):
            return
        for message in messages:
            if isinstance(message, dict) and message.get("role") == "user":
                message.pop("name", None)
    def _convert_chunk_to_generation_chunk(
        self,
        chunk: dict,
@@ -47,6 +47,41 @@ def _prepare_database_sqlite_checkpointer_path(db_config) -> str:
    return conn_str
 def _build_postgres_pool(conn_string: str):
    """Build an AsyncConnectionPool with TCP keepalive and connection checking."""
    from psycopg.rows import dict_row
    from psycopg_pool import AsyncConnectionPool
    return AsyncConnectionPool(
        conn_string,
        kwargs={
            "autocommit": True,
            "prepare_threshold": 0,
            "row_factory": dict_row,
            "keepalives": 1,
            "keepalives_idle": 60,
            "keepalives_interval": 10,
            "keepalives_count": 6,
        },
        check=AsyncConnectionPool.check_connection,
    )
 def _ensure_postgres_imports():
    """Import and return (AsyncPostgresSaver, AsyncConnectionPool), raising ImportError on failure."""
    try:
        from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
    except ImportError as exc:
        raise ImportError(POSTGRES_INSTALL) from exc
    try:
        from psycopg_pool import AsyncConnectionPool
    except ImportError as exc:
        raise ImportError(POSTGRES_INSTALL) from exc
    return AsyncPostgresSaver, AsyncConnectionPool
 # ---------------------------------------------------------------------------
 # Async factory
 # ---------------------------------------------------------------------------
@@ -74,15 +109,13 @@ async def _async_checkpointer(config) -> AsyncIterator[Checkpointer]:
        return
    if config.type == "postgres":
        try:
            from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
        except ImportError as exc:
            raise ImportError(POSTGRES_INSTALL) from exc
        if not config.connection_string:
            raise ValueError(POSTGRES_CONN_REQUIRED)
-        async with AsyncPostgresSaver.from_conn_string(config.connection_string) as saver:
+        AsyncPostgresSaver, _ = _ensure_postgres_imports()
        pool = _build_postgres_pool(config.connection_string)
        async with pool:
            saver = AsyncPostgresSaver(conn=pool)
            await saver.setup()
            yield saver
        return
@@ -117,15 +150,13 @@ async def _async_checkpointer_from_database(db_config) -> AsyncIterator[Checkpoi
        return
    if db_config.backend == "postgres":
        try:
            from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
        except ImportError as exc:
            raise ImportError(POSTGRES_INSTALL) from exc
        if not db_config.postgres_url:
            raise ValueError("database.postgres_url is required for the postgres backend")
-        async with AsyncPostgresSaver.from_conn_string(db_config.postgres_url) as saver:
+        AsyncPostgresSaver, _ = _ensure_postgres_imports()
        pool = _build_postgres_pool(db_config.postgres_url)
        async with pool:
            saver = AsyncPostgresSaver(conn=pool)
            await saver.setup()
            yield saver
        return
@@ -21,12 +21,13 @@ from __future__ import annotations
 import contextlib
 import logging
 import threading
 from collections.abc import Iterator
 from langgraph.types import Checkpointer
 from deerflow.config.app_config import get_app_config
-from deerflow.config.checkpointer_config import CheckpointerConfig
+from deerflow.config.checkpointer_config import CheckpointerConfig, ensure_config_loaded
 from deerflow.runtime.store._sqlite_utils import ensure_sqlite_parent_dir, resolve_sqlite_conn_str
 logger = logging.getLogger(__name__)
@@ -100,6 +101,7 @@ def _sync_checkpointer_cm(config: CheckpointerConfig) -> Iterator[Checkpointer]:
 _checkpointer: Checkpointer | None = None
 _checkpointer_ctx = None  # open context manager keeping the connection alive
 _checkpointer_lock = threading.Lock()
 def get_checkpointer() -> Checkpointer:
@@ -116,34 +118,29 @@ def get_checkpointer() -> Checkpointer:
    if _checkpointer is not None:
        return _checkpointer
-    # Ensure app config is loaded before checking checkpointer config
+    # Config loading can reset both persistence singletons. Keep it outside
-    # This prevents returning InMemorySaver when config.yaml actually has a checkpointer section
+    # this provider lock to avoid cross-provider lock-order inversion.
-    # but hasn't been loaded yet
+    ensure_config_loaded()
    from deerflow.config.app_config import _app_config
    from deerflow.config.checkpointer_config import get_checkpointer_config
-    config = get_checkpointer_config()
+    with _checkpointer_lock:
        if _checkpointer is not None:
            return _checkpointer
        from deerflow.config.checkpointer_config import get_checkpointer_config
    if config is None and _app_config is None:
        # Only load app config lazily when neither the app config nor an explicit
        # checkpointer config has been initialized yet. This keeps tests that
        # intentionally set the global checkpointer config isolated from any
        # ambient config.yaml on disk.
        try:
            get_app_config()
        except FileNotFoundError:
            # In test environments without config.yaml, this is expected.
            pass
        config = get_checkpointer_config()
    if config is None:
        from langgraph.checkpoint.memory import InMemorySaver
-        logger.info("Checkpointer: using InMemorySaver (in-process, not persistent)")
+        if config is None:
-        _checkpointer = InMemorySaver()
+            from langgraph.checkpoint.memory import InMemorySaver
        return _checkpointer
-    _checkpointer_ctx = _sync_checkpointer_cm(config)
+            logger.info("Checkpointer: using InMemorySaver (in-process, not persistent)")
-    _checkpointer = _checkpointer_ctx.__enter__()
+            _checkpointer = InMemorySaver()
            return _checkpointer
        checkpointer_ctx = _sync_checkpointer_cm(config)
        checkpointer = checkpointer_ctx.__enter__()
        _checkpointer_ctx = checkpointer_ctx
        _checkpointer = checkpointer
    return _checkpointer
@@ -155,13 +152,14 @@ def reset_checkpointer() -> None:
    Useful in tests or after a configuration change.
    """
    global _checkpointer, _checkpointer_ctx
-    if _checkpointer_ctx is not None:
+    with _checkpointer_lock:
-        try:
+        if _checkpointer_ctx is not None:
-            _checkpointer_ctx.__exit__(None, None, None)
+            try:
-        except Exception:
+                _checkpointer_ctx.__exit__(None, None, None)
-            logger.warning("Error during checkpointer cleanup", exc_info=True)
+            except Exception:
-        _checkpointer_ctx = None
+                logger.warning("Error during checkpointer cleanup", exc_info=True)
-    _checkpointer = None
+            _checkpointer_ctx = None
        _checkpointer = None
 # ---------------------------------------------------------------------------
@@ -86,6 +86,8 @@ class RunJournal(BaseCallbackHandler):
        self._last_ai_msg: str | None = None
        self._first_human_msg: str | None = None
        self._msg_count = 0
        self._had_llm_error_fallback = False
        self._llm_error_fallback_message: str | None = None
        # Latency tracking
        self._llm_start_times: dict[str, float] = {}  # langchain run_id -> start time
@@ -256,6 +258,18 @@ class RunJournal(BaseCallbackHandler):
            # Token usage from message
            usage = getattr(message, "usage_metadata", None)
            usage_dict = dict(usage) if usage else {}
            additional_kwargs = getattr(message, "additional_kwargs", None) or {}
            if isinstance(additional_kwargs, dict) and additional_kwargs.get("deerflow_error_fallback"):
                self._had_llm_error_fallback = True
                detail = additional_kwargs.get("error_detail")
                reason = additional_kwargs.get("error_reason")
                fallback_text = self._message_text(message).strip()
                if isinstance(detail, str) and detail.strip():
                    self._llm_error_fallback_message = detail.strip()
                elif isinstance(reason, str) and reason.strip():
                    self._llm_error_fallback_message = reason.strip()
                elif fallback_text:
                    self._llm_error_fallback_message = fallback_text[:2000]
            # Resolve call index
            call_index = self._llm_call_index
@@ -569,3 +583,11 @@ class RunJournal(BaseCallbackHandler):
            "last_ai_message": self._last_ai_msg,
            "first_human_message": self._first_human_msg,
        }
    @property
    def had_llm_error_fallback(self) -> bool:
        return self._had_llm_error_fallback
    @property
    def llm_error_fallback_message(self) -> str | None:
        return self._llm_error_fallback_message
@@ -1,39 +1,16 @@
 """Run lifecycle management for LangGraph Platform API compatibility."""
 from .domain import (
    AssistantId,
    CancelAction,
    DisconnectMode,
    EventSeq,
    InvalidRunTransition,
    MultitaskStrategy,
    Run,
    RunId,
    RunScope,
    RunStatus,
    ThreadId,
    UserId,
 )
 from .manager import ConflictError, RunManager, RunRecord, UnsupportedStrategyError
 from .schemas import DisconnectMode, RunStatus
 from .worker import RunContext, run_agent
 __all__ = [
    "AssistantId",
    "CancelAction",
    "ConflictError",
    "DisconnectMode",
    "EventSeq",
    "InvalidRunTransition",
    "MultitaskStrategy",
    "Run",
    "RunContext",
    "RunId",
    "RunManager",
    "RunRecord",
    "RunScope",
    "RunStatus",
    "ThreadId",
    "UnsupportedStrategyError",
    "UserId",
    "run_agent",
 ]
@@ -1,20 +0,0 @@
 """Application-layer DTOs and services for run runtime use cases."""
 from .commands import CancelRunCommand, CreateRunCommand, JoinRunStreamCommand
 from .dto import RunMessageView, RunSnapshot, RunStreamHandle, StoredRunEvent
 from .queries import GetRunQuery, ListRunMessagesQuery, ListRunsQuery
 from .services import RunsApplicationService
 __all__ = [
    "CancelRunCommand",
    "CreateRunCommand",
    "GetRunQuery",
    "JoinRunStreamCommand",
    "ListRunMessagesQuery",
    "ListRunsQuery",
    "RunMessageView",
    "RunSnapshot",
    "RunStreamHandle",
    "RunsApplicationService",
    "StoredRunEvent",
 ]
@@ -1,46 +0,0 @@
 """Application command DTOs for run use cases."""
 from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Any, Literal
 from ..domain import AssistantId, CancelAction, DisconnectMode, MultitaskStrategy, RunId, RunScope, ThreadId
@dataclass(frozen=True)
 class CreateRunCommand:
    thread_id: ThreadId
    assistant_id: AssistantId | None = None
    input: dict[str, Any] | None = None
    command: dict[str, Any] | None = None
    metadata: dict[str, Any] = field(default_factory=dict)
    config: dict[str, Any] = field(default_factory=dict)
    context: dict[str, Any] = field(default_factory=dict)
    scope: RunScope = RunScope.stateful
    on_disconnect: DisconnectMode = DisconnectMode.cancel
    multitask_strategy: MultitaskStrategy = MultitaskStrategy.reject
    stream_mode: list[str] | str | None = None
    stream_subgraphs: bool = False
    interrupt_before: list[str] | Literal["*"] | None = None
    interrupt_after: list[str] | Literal["*"] | None = None
@dataclass(frozen=True)
 class CancelRunCommand:
    run_id: RunId
    action: CancelAction = CancelAction.interrupt
    wait: bool = False
@dataclass(frozen=True)
 class JoinRunStreamCommand:
    run_id: RunId
    last_event_id: str | None = None
 __all__ = [
    "CancelRunCommand",
    "CreateRunCommand",
    "JoinRunStreamCommand",
 ]
@@ -1,76 +0,0 @@
 """Application output DTOs for run use cases."""
 from __future__ import annotations
 from collections.abc import AsyncIterator
 from dataclasses import dataclass, field
 from typing import Any
 from ..domain import AssistantId, EventSeq, Run, RunId, RunStatus, ThreadId
@dataclass(frozen=True)
 class RunSnapshot:
    run_id: RunId
    thread_id: ThreadId
    assistant_id: AssistantId | None = None
    status: RunStatus = RunStatus.pending
    metadata: dict[str, Any] = field(default_factory=dict)
    kwargs: dict[str, Any] = field(default_factory=dict)
    created_at: str = ""
    updated_at: str = ""
    error: str | None = None
    model_name: str | None = None
    @classmethod
    def from_run(cls, run: Run) -> RunSnapshot:
        return cls(
            run_id=run.run_id,
            thread_id=run.thread_id,
            assistant_id=run.assistant_id,
            status=run.status,
            metadata=dict(run.metadata),
            kwargs=dict(run.kwargs),
            created_at=run.created_at,
            updated_at=run.updated_at,
            error=run.error,
            model_name=run.model_name,
        )
@dataclass(frozen=True)
 class RunMessageView:
    thread_id: ThreadId
    run_id: RunId
    seq: EventSeq
    event_type: str
    content: str | dict[str, Any] = ""
    metadata: dict[str, Any] = field(default_factory=dict)
    created_at: str = ""
@dataclass(frozen=True)
 class StoredRunEvent:
    thread_id: ThreadId
    run_id: RunId
    seq: EventSeq
    event_type: str
    category: str
    content: str | dict[str, Any] = ""
    metadata: dict[str, Any] = field(default_factory=dict)
    created_at: str = ""
@dataclass(frozen=True)
 class RunStreamHandle:
    run_id: RunId
    thread_id: ThreadId
    events: AsyncIterator[Any]
 __all__ = [
    "RunMessageView",
    "RunSnapshot",
    "RunStreamHandle",
    "StoredRunEvent",
 ]
@@ -1,37 +0,0 @@
 """Application query DTOs for run use cases."""
 from __future__ import annotations
 from dataclasses import dataclass
 from ..domain import RunId, ThreadId, UserId
@dataclass(frozen=True)
 class GetRunQuery:
    run_id: RunId
    thread_id: ThreadId | None = None
    user_id: UserId | None = None
@dataclass(frozen=True)
 class ListRunsQuery:
    thread_id: ThreadId
    user_id: UserId | None = None
    limit: int = 100
@dataclass(frozen=True)
 class ListRunMessagesQuery:
    thread_id: ThreadId
    run_id: RunId
    limit: int = 50
    before_seq: int | None = None
    after_seq: int | None = None
 __all__ = [
    "GetRunQuery",
    "ListRunMessagesQuery",
    "ListRunsQuery",
 ]
@@ -1,74 +0,0 @@
 """Application service skeleton for run use cases."""
 from __future__ import annotations
 from dataclasses import dataclass
 from ..execution import RunExecutionScheduler, RunSupervisor
 from ..repositories import RunEventLog, RunRepository
 from ..streams import RunStreamBroker
 from .commands import CancelRunCommand, CreateRunCommand, JoinRunStreamCommand
 from .dto import RunMessageView, RunSnapshot, RunStreamHandle
 from .queries import GetRunQuery, ListRunMessagesQuery, ListRunsQuery
@dataclass
 class RunsApplicationService:
    """Use-case orchestration boundary for run runtime operations.
    PR1 only introduces the boundary and dependency shape. Existing Gateway
    handlers continue to call the legacy service functions until later PRs move
    behavior into this class.
    """
    run_repository: RunRepository
    run_event_log: RunEventLog
    stream_broker: RunStreamBroker
    scheduler: RunExecutionScheduler
    supervisor: RunSupervisor
    async def create_background(self, command: CreateRunCommand) -> RunSnapshot:
        # PR1 defines the application boundary; later PRs move Gateway runtime
        # behavior behind this method.
        raise NotImplementedError("RunsApplicationService is not wired in PR1")
    async def create_and_stream(self, command: CreateRunCommand) -> RunStreamHandle:
        raise NotImplementedError("RunsApplicationService is not wired in PR1")
    async def create_and_wait(self, command: CreateRunCommand) -> RunSnapshot:
        raise NotImplementedError("RunsApplicationService is not wired in PR1")
    async def join_stream(self, command: JoinRunStreamCommand) -> RunStreamHandle:
        raise NotImplementedError("RunsApplicationService is not wired in PR1")
    async def cancel(self, command: CancelRunCommand) -> bool:
        return await self.supervisor.cancel(command.run_id, action=command.action)
    async def get_run(self, query: GetRunQuery) -> RunSnapshot | None:
        run = await self.run_repository.get(query.run_id, user_id=query.user_id)
        if run is None:
            return None
        if query.thread_id is not None and run.thread_id != query.thread_id:
            return None
        return RunSnapshot.from_run(run)
    async def list_runs(self, query: ListRunsQuery) -> list[RunSnapshot]:
        return await self.run_repository.list_by_thread(
            query.thread_id,
            user_id=query.user_id,
            limit=query.limit,
        )
    async def list_run_messages(self, query: ListRunMessagesQuery) -> list[RunMessageView]:
        return await self.run_event_log.list_messages_by_run(
            query.thread_id,
            query.run_id,
            limit=query.limit,
            before_seq=query.before_seq,
            after_seq=query.after_seq,
        )
 __all__ = [
    "RunsApplicationService",
 ]
@@ -1,33 +0,0 @@
 """Run runtime domain model."""
 from .errors import InvalidRunTransition, RunDomainError
 from .events import RunCancelled, RunCompleted, RunCreated, RunEvent, RunFailed, RunStarted
 from .identifiers import AssistantId, RunId, ThreadId, UserId
 from .model import Run
 from .policies import CancelPolicy, MultitaskDecision, MultitaskPolicy
 from .value_objects import CancelAction, DisconnectMode, EventSeq, MultitaskStrategy, RunScope, RunStatus
 __all__ = [
    "AssistantId",
    "CancelAction",
    "CancelPolicy",
    "DisconnectMode",
    "EventSeq",
    "InvalidRunTransition",
    "MultitaskDecision",
    "MultitaskPolicy",
    "MultitaskStrategy",
    "Run",
    "RunCancelled",
    "RunCompleted",
    "RunCreated",
    "RunDomainError",
    "RunEvent",
    "RunFailed",
    "RunId",
    "RunScope",
    "RunStarted",
    "RunStatus",
    "ThreadId",
    "UserId",
 ]
@@ -1,24 +0,0 @@
 """Domain-level errors for run lifecycle operations."""
 from __future__ import annotations
 from .value_objects import RunStatus
 class RunDomainError(Exception):
    """Base class for run runtime domain errors."""
 class InvalidRunTransition(RunDomainError):
    """Raised when a run status transition violates lifecycle rules."""
    def __init__(self, current: RunStatus, target: RunStatus) -> None:
        super().__init__(f"Cannot transition run from {current.value!r} to {target.value!r}")
        self.current = current
        self.target = target
 __all__ = [
    "InvalidRunTransition",
    "RunDomainError",
 ]
@@ -1,64 +0,0 @@
 """Domain events emitted by the run aggregate."""
 from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Any
 from deerflow.utils.time import now_iso
 from .identifiers import AssistantId, RunId, ThreadId
 from .value_objects import CancelAction, RunStatus
@dataclass(frozen=True)
 class RunCreated:
    run_id: RunId
    thread_id: ThreadId
    occurred_at: str = field(default_factory=now_iso)
    assistant_id: AssistantId | None = None
    metadata: dict[str, Any] = field(default_factory=dict)
@dataclass(frozen=True)
 class RunStarted:
    run_id: RunId
    thread_id: ThreadId
    occurred_at: str = field(default_factory=now_iso)
@dataclass(frozen=True)
 class RunCompleted:
    run_id: RunId
    thread_id: ThreadId
    occurred_at: str = field(default_factory=now_iso)
@dataclass(frozen=True)
 class RunFailed:
    run_id: RunId
    thread_id: ThreadId
    status: RunStatus
    occurred_at: str = field(default_factory=now_iso)
    error: str | None = None
@dataclass(frozen=True)
 class RunCancelled:
    run_id: RunId
    thread_id: ThreadId
    occurred_at: str = field(default_factory=now_iso)
    action: CancelAction = CancelAction.interrupt
 RunEvent = RunCreated | RunStarted | RunCompleted | RunFailed | RunCancelled
 __all__ = [
    "RunCancelled",
    "RunCompleted",
    "RunCreated",
    "RunEvent",
    "RunFailed",
    "RunStarted",
 ]
@@ -1,27 +0,0 @@
 """Lightweight identifiers for the run runtime domain."""
 from __future__ import annotations
 from typing import NewType
 RunId = NewType("RunId", str)
 ThreadId = NewType("ThreadId", str)
 AssistantId = NewType("AssistantId", str)
 UserId = NewType("UserId", str)
 def require_non_empty(value: str, *, field_name: str) -> str:
    """Return a stripped identifier value, rejecting empty identifiers."""
    normalized = value.strip()
    if not normalized:
        raise ValueError(f"{field_name} must not be empty")
    return normalized
 __all__ = [
    "AssistantId",
    "RunId",
    "ThreadId",
    "UserId",
    "require_non_empty",
 ]
@@ -1,193 +0,0 @@
 """Run aggregate root and lifecycle invariants."""
 from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Any
 from deerflow.utils.time import now_iso
 from .errors import InvalidRunTransition
 from .events import RunCancelled, RunCompleted, RunCreated, RunEvent, RunFailed, RunStarted
 from .identifiers import AssistantId, RunId, ThreadId, require_non_empty
 from .value_objects import CancelAction, MultitaskStrategy, RunScope, RunStatus
 # Keep lifecycle transitions explicit so later application code cannot invent
 # ad hoc status moves outside the aggregate.
 _ALLOWED_TRANSITIONS: dict[RunStatus, frozenset[RunStatus]] = {
    RunStatus.pending: frozenset(
        {
            RunStatus.running,
            RunStatus.error,
            RunStatus.timeout,
            RunStatus.interrupted,
        }
    ),
    RunStatus.running: frozenset(
        {
            RunStatus.success,
            RunStatus.error,
            RunStatus.timeout,
            RunStatus.interrupted,
        }
    ),
    RunStatus.success: frozenset(),
    RunStatus.error: frozenset(),
    RunStatus.timeout: frozenset(),
    RunStatus.interrupted: frozenset(),
 }
@dataclass
 class Run:
    """Run aggregate root.
    The aggregate owns lifecycle invariants only. Infrastructure concerns such
    as SQL sessions, SSE frames, Redis clients, and FastAPI requests stay out of
    this model.
    """
    run_id: RunId
    thread_id: ThreadId
    status: RunStatus
    assistant_id: AssistantId | None = None
    scope: RunScope = RunScope.stateful
    multitask_strategy: MultitaskStrategy = MultitaskStrategy.reject
    metadata: dict[str, Any] = field(default_factory=dict)
    kwargs: dict[str, Any] = field(default_factory=dict)
    created_at: str = field(default_factory=now_iso)
    updated_at: str = field(default_factory=now_iso)
    error: str | None = None
    model_name: str | None = None
    _pending_events: list[RunEvent] = field(default_factory=list, init=False, repr=False)
    def __post_init__(self) -> None:
        self.run_id = RunId(require_non_empty(str(self.run_id), field_name="run_id"))
        self.thread_id = ThreadId(require_non_empty(str(self.thread_id), field_name="thread_id"))
        if self.assistant_id is not None:
            self.assistant_id = AssistantId(require_non_empty(str(self.assistant_id), field_name="assistant_id"))
    @classmethod
    def create(
        cls,
        *,
        run_id: RunId,
        thread_id: ThreadId,
        assistant_id: AssistantId | None = None,
        scope: RunScope = RunScope.stateful,
        multitask_strategy: MultitaskStrategy = MultitaskStrategy.reject,
        metadata: dict[str, Any] | None = None,
        kwargs: dict[str, Any] | None = None,
        model_name: str | None = None,
        created_at: str | None = None,
    ) -> Run:
        timestamp = created_at or now_iso()
        run = cls(
            run_id=run_id,
            thread_id=thread_id,
            assistant_id=assistant_id,
            status=RunStatus.pending,
            scope=scope,
            multitask_strategy=multitask_strategy,
            metadata=metadata or {},
            kwargs=kwargs or {},
            created_at=timestamp,
            updated_at=timestamp,
            model_name=model_name,
        )
        run._record_event(
            RunCreated(
                run_id=run.run_id,
                thread_id=run.thread_id,
                occurred_at=timestamp,
                assistant_id=run.assistant_id,
                metadata=dict(run.metadata),
            )
        )
        return run
    @property
    def is_terminal(self) -> bool:
        return not _ALLOWED_TRANSITIONS[self.status]
    def pull_events(self) -> tuple[RunEvent, ...]:
        # Domain events are drained by the application layer after the aggregate
        # has accepted a state change.
        events = tuple(self._pending_events)
        self._pending_events.clear()
        return events
    def mark_started(self, *, at: str | None = None) -> None:
        self._transition_to(RunStatus.running, at=at)
    def mark_completed(self, *, at: str | None = None) -> None:
        self._transition_to(RunStatus.success, at=at)
    def mark_failed(self, error: str | None = None, *, at: str | None = None) -> None:
        self._transition_to(RunStatus.error, error=error, at=at)
    def mark_timed_out(self, error: str | None = None, *, at: str | None = None) -> None:
        self._transition_to(RunStatus.timeout, error=error, at=at)
    def mark_cancelled(self, *, action: CancelAction = CancelAction.interrupt, at: str | None = None) -> None:
        self._transition_to(RunStatus.interrupted, action=action, at=at)
    def _transition_to(
        self,
        target: RunStatus,
        *,
        error: str | None = None,
        action: CancelAction = CancelAction.interrupt,
        at: str | None = None,
    ) -> None:
        if target == self.status:
            return
        if target not in _ALLOWED_TRANSITIONS[self.status]:
            raise InvalidRunTransition(self.status, target)
        timestamp = at or now_iso()
        self.status = target
        self.updated_at = timestamp
        if error is not None:
            self.error = error
        self._record_event(self._event_for_transition(target, timestamp, error=error, action=action))
    def _event_for_transition(
        self,
        target: RunStatus,
        occurred_at: str,
        *,
        error: str | None,
        action: CancelAction,
    ) -> RunEvent:
        # Keep event construction next to the transition rules so a new status
        # cannot be added without an explicit durable event shape.
        if target == RunStatus.running:
            return RunStarted(run_id=self.run_id, thread_id=self.thread_id, occurred_at=occurred_at)
        if target == RunStatus.success:
            return RunCompleted(run_id=self.run_id, thread_id=self.thread_id, occurred_at=occurred_at)
        if target in (RunStatus.error, RunStatus.timeout):
            return RunFailed(
                run_id=self.run_id,
                thread_id=self.thread_id,
                status=target,
                occurred_at=occurred_at,
                error=error,
            )
        if target == RunStatus.interrupted:
            return RunCancelled(
                run_id=self.run_id,
                thread_id=self.thread_id,
                occurred_at=occurred_at,
                action=action,
            )
        raise InvalidRunTransition(self.status, target)
    def _record_event(self, event: RunEvent) -> None:
        self._pending_events.append(event)
 __all__ = [
    "Run",
    "RunStatus",
 ]
@@ -1,50 +0,0 @@
 """Domain policies for run concurrency and cancellation."""
 from __future__ import annotations
 from collections.abc import Sequence
 from dataclasses import dataclass
 from enum import StrEnum
 from .model import Run
 from .value_objects import CancelAction, MultitaskStrategy, RunStatus
 class MultitaskDecision(StrEnum):
    """Application-level decision produced by a multitask policy."""
    allow = "allow"
    reject = "reject"
    cancel_existing = "cancel_existing"
    enqueue = "enqueue"
@dataclass(frozen=True)
 class MultitaskPolicy:
    strategy: MultitaskStrategy = MultitaskStrategy.reject
    def decide(self, active_runs: Sequence[Run]) -> MultitaskDecision:
        inflight = [run for run in active_runs if run.status in (RunStatus.pending, RunStatus.running)]
        if not inflight:
            return MultitaskDecision.allow
        if self.strategy == MultitaskStrategy.reject:
            return MultitaskDecision.reject
        if self.strategy in (MultitaskStrategy.interrupt, MultitaskStrategy.rollback):
            return MultitaskDecision.cancel_existing
        return MultitaskDecision.enqueue
@dataclass(frozen=True)
 class CancelPolicy:
    action: CancelAction = CancelAction.interrupt
    @property
    def rolls_back_checkpoint(self) -> bool:
        return self.action == CancelAction.rollback
 __all__ = [
    "CancelPolicy",
    "MultitaskDecision",
    "MultitaskPolicy",
 ]
@@ -1,88 +0,0 @@
 """Domain value objects for run lifecycle semantics."""
 from __future__ import annotations
 from dataclasses import dataclass
 from enum import StrEnum
 class RunStatus(StrEnum):
    """Lifecycle status of a single run."""
    pending = "pending"
    running = "running"
    success = "success"
    error = "error"
    timeout = "timeout"
    interrupted = "interrupted"
 class DisconnectMode(StrEnum):
    """Behaviour when the SSE consumer disconnects."""
    cancel = "cancel"
    continue_ = "continue"
 class RunScope(StrEnum):
    """Conversation scope for a run."""
    stateful = "stateful"
    stateless = "stateless"
    temporary_thread = "temporary_thread"
 class MultitaskStrategy(StrEnum):
    """Concurrency strategy for a new run on a thread."""
    reject = "reject"
    interrupt = "interrupt"
    rollback = "rollback"
    enqueue = "enqueue"
 class CancelAction(StrEnum):
    """Cancellation action requested by an API or supervisor."""
    interrupt = "interrupt"
    rollback = "rollback"
 TERMINAL_RUN_STATUSES: frozenset[RunStatus] = frozenset(
    {
        RunStatus.success,
        RunStatus.error,
        RunStatus.timeout,
        RunStatus.interrupted,
    }
 )
 def is_terminal_status(status: RunStatus) -> bool:
    return status in TERMINAL_RUN_STATUSES
@dataclass(frozen=True, order=True)
 class EventSeq:
    """Thread-local event sequence number."""
    value: int
    def __post_init__(self) -> None:
        if self.value < 0:
            raise ValueError("EventSeq must be non-negative")
    def next(self) -> EventSeq:
        return EventSeq(self.value + 1)
 __all__ = [
    "CancelAction",
    "DisconnectMode",
    "EventSeq",
    "MultitaskStrategy",
    "RunScope",
    "RunStatus",
    "TERMINAL_RUN_STATUSES",
    "is_terminal_status",
 ]
@@ -1,12 +0,0 @@
 """Execution contracts for run lifecycle orchestration."""
 from .executor import RunExecutor
 from .scheduler import RunExecutionHandle, RunExecutionScheduler
 from .supervisor import RunSupervisor
 __all__ = [
    "RunExecutionHandle",
    "RunExecutionScheduler",
    "RunExecutor",
    "RunSupervisor",
 ]
@@ -1,19 +0,0 @@
 """Run executor contract."""
 from __future__ import annotations
 from typing import Protocol
 from ..domain import Run
 class RunExecutor(Protocol):
    """Executes one run against the underlying agent or graph runtime."""
    async def execute(self, run: Run) -> None:
        pass
 __all__ = [
    "RunExecutor",
 ]
@@ -1,26 +0,0 @@
 """Run execution scheduler contract."""
 from __future__ import annotations
 from dataclasses import dataclass
 from typing import Protocol
 from ..domain import RunId
@dataclass(frozen=True)
 class RunExecutionHandle:
    run_id: RunId
 class RunExecutionScheduler(Protocol):
    """Starts background execution for an accepted run."""
    async def start(self, run_id: RunId) -> RunExecutionHandle:
        pass
 __all__ = [
    "RunExecutionHandle",
    "RunExecutionScheduler",
 ]
@@ -1,19 +0,0 @@
 """Run execution supervision contract."""
 from __future__ import annotations
 from typing import Protocol
 from ..domain import CancelAction, RunId
 class RunSupervisor(Protocol):
    """Controls lifecycle operations for already scheduled runs."""
    async def cancel(self, run_id: RunId, *, action: CancelAction = CancelAction.interrupt) -> bool:
        pass
 __all__ = [
    "RunSupervisor",
 ]
@@ -645,6 +645,98 @@ class RunManager:
            self._runs.pop(run_id, None)
        logger.debug("Run record %s cleaned up", run_id)
    async def shutdown(self, *, timeout: float = 5.0) -> None:
        """Cancel and bounded-await all in-flight runs on process shutdown.
        Chat runs execute in fire-and-forget background ``asyncio`` tasks that
        write checkpoints through a shared checkpointer. On shutdown the
        checkpointer's resources (e.g. the postgres connection pool owned by the
        gateway's ``AsyncExitStack``) are torn down; if a run task is still
        mid-graph at that point, langgraph's
        ``AsyncPregelLoop._checkpointer_put_after_previous`` runs its
        ``finally: await checkpointer.aput(...)`` against the closed pool. Because
        that put runs in a langgraph-internal task (not on ``run_agent``'s call
        stack), the resulting ``psycopg_pool.PoolClosed`` is not catchable by the
        worker and surfaces as an unhandled exception during ``asyncio.run()``
        shutdown (bytedance/deer-flow issue #3373).
        Draining in-flight runs *before* the checkpointer is closed lets each
        run that settles within ``timeout`` flush its final checkpoint while
        resources are still open. Only runs that do **not** settle on their own
        are marked ``interrupted`` — a run that completes (e.g. ``success``)
        during the drain keeps its real terminal status instead of being
        blanket-overwritten. The whole drain, including the trailing status
        persistence, is bounded by ``timeout`` so a run stuck in cleanup (or a
        slow store under DB pressure) cannot hang worker shutdown — the
        precondition for the signal-reentrancy deadlock guarded by
        ``app.gateway.app._SHUTDOWN_HOOK_TIMEOUT_SECONDS``. Runs still active
        after ``timeout`` are logged and may still race teardown.
        """
        loop = asyncio.get_running_loop()
        deadline = loop.time() + timeout
        async with self._lock:
            inflight = [record for record in self._runs.values() if record.status in (RunStatus.pending, RunStatus.running) and record.task is not None and not record.task.done()]
            for record in inflight:
                record.abort_action = "interrupt"
                record.abort_event.set()
                record.task.cancel()  # type: ignore[union-attr]  # filtered above
                # Status is decided AFTER the drain (below), not here: a run that
                # completes on its own during the drain must keep its real status.
        if not inflight:
            return
        tasks = [record.task for record in inflight]
        _, pending = await asyncio.wait(tasks, timeout=timeout)
        # Only mark/persist ``interrupted`` for runs that did not settle on their
        # own (still pending after the timeout, or ended cancelled). A run that
        # finished normally during the drain keeps the status it set for itself.
        to_persist: list[RunRecord] = []
        async with self._lock:
            for record in inflight:
                task = record.task
                if task not in pending and not task.cancelled():
                    # Completed on its own — retrieve any surfaced exception so it
                    # is not reported as "never retrieved", and keep its status.
                    task.exception()  # type: ignore[union-attr]  # done & not cancelled
                    continue
                if record.status in (RunStatus.pending, RunStatus.running):
                    record.status = RunStatus.interrupted
                    record.updated_at = _now_iso()
                to_persist.append(record)
        # Bound the trailing status persistence within the remaining budget so a
        # slow store (``_call_store_with_retry`` can back off under DB pressure)
        # cannot push shutdown past ``timeout``.
        if to_persist:
            remaining = deadline - loop.time()
            if remaining <= 0:
                logger.warning("Run drain budget exhausted before persisting %d interrupted run(s) on shutdown", len(to_persist))
            else:
                try:
                    results = await asyncio.wait_for(
                        asyncio.gather(*(self._persist_status(record, RunStatus.interrupted) for record in to_persist), return_exceptions=True),
                        timeout=remaining,
                    )
                except TimeoutError:
                    logger.warning("Run drain status persistence exceeded the %.1fs budget; %d record(s) may not be persisted", timeout, len(to_persist))
                else:
                    # ``_persist_status`` is best-effort: it catches and logs its
                    # own failures, returning ``False``. Inspect the aggregate so a
                    # partial failure is surfaced at shutdown level (with the
                    # run_id) instead of being silently swallowed by the gather.
                    for record, result in zip(to_persist, results):
                        if isinstance(result, Exception):
                            logger.warning("Unexpected error persisting interrupted status for run %s during shutdown: %r", record.run_id, result)
                        elif result is False:
                            logger.warning("Could not persist interrupted status for run %s during shutdown", record.run_id)
        if pending:
            logger.warning("Run drain exceeded %.1fs on shutdown; %d run task(s) still active and may race checkpointer teardown", timeout, len(pending))
        logger.info("Drained %d in-flight run(s) on shutdown (%d settled within %.1fs)", len(inflight), len(inflight) - len(pending), timeout)
 class ConflictError(Exception):
    """Raised when multitask_strategy=reject and thread has inflight runs."""
@@ -1,9 +0,0 @@
 """Repository contracts for the run runtime application layer."""
 from .run_event_log import RunEventLog
 from .run_repository import RunRepository
 __all__ = [
    "RunEventLog",
    "RunRepository",
 ]
@@ -1,42 +0,0 @@
 """Durable run event log contract."""
 from __future__ import annotations
 from typing import TYPE_CHECKING, Protocol
 from ..domain import RunEvent, RunId, ThreadId
 if TYPE_CHECKING:
    from ..application.dto import RunMessageView, StoredRunEvent
 class RunEventLog(Protocol):
    """Persistence boundary for run messages and execution trace events."""
    async def append(self, events: list[RunEvent]) -> list[StoredRunEvent]:
        pass
    async def list_messages_by_run(
        self,
        thread_id: ThreadId,
        run_id: RunId,
        *,
        limit: int = 50,
        before_seq: int | None = None,
        after_seq: int | None = None,
    ) -> list[RunMessageView]:
        pass
    async def list_events_by_run(
        self,
        thread_id: ThreadId,
        run_id: RunId,
        *,
        limit: int = 500,
    ) -> list[StoredRunEvent]:
        pass
 __all__ = [
    "RunEventLog",
 ]
@@ -1,37 +0,0 @@
 """Run state repository contract."""
 from __future__ import annotations
 from typing import TYPE_CHECKING, Protocol
 from ..domain import Run, RunId, ThreadId, UserId
 if TYPE_CHECKING:
    from ..application.dto import RunSnapshot
 class RunRepository(Protocol):
    """Persistence boundary for run state snapshots."""
    async def save(self, run: Run) -> None:
        pass
    async def get(self, run_id: RunId, *, user_id: UserId | None = None) -> Run | None:
        pass
    async def list_by_thread(
        self,
        thread_id: ThreadId,
        *,
        user_id: UserId | None = None,
        limit: int = 100,
    ) -> list[RunSnapshot]:
        pass
    async def delete(self, run_id: RunId) -> bool:
        pass
 __all__ = [
    "RunRepository",
 ]
@@ -1,10 +1,21 @@
-"""Compatibility exports for run status and disconnect mode enums."""
+"""Run status and disconnect mode enums."""
-# Existing callers import these enums from ``runs.schemas``. Re-export the
+from enum import StrEnum
 # domain definitions until all imports move to ``runs.domain``.
 from .domain import DisconnectMode, RunStatus
-__all__ = [
+
-    "DisconnectMode",
+class RunStatus(StrEnum):
-    "RunStatus",
+    """Lifecycle status of a single run."""
-]
+
    pending = "pending"
    running = "running"
    success = "success"
    error = "error"
    timeout = "timeout"
    interrupted = "interrupted"
 class DisconnectMode(StrEnum):
    """Behaviour when the SSE consumer disconnects."""
    cancel = "cancel"
    continue_ = "continue"
@@ -1,8 +0,0 @@
 """Realtime stream contracts for run application use cases."""
 from .run_stream_broker import RunStreamBroker, RunStreamEvent
 __all__ = [
    "RunStreamBroker",
    "RunStreamEvent",
 ]
@@ -1,44 +0,0 @@
 """Realtime run stream broker contract."""
 from __future__ import annotations
 from collections.abc import AsyncIterator
 from dataclasses import dataclass
 from typing import Any, Protocol
 from ..domain import RunId
@dataclass(frozen=True)
 class RunStreamEvent:
    id: str
    event: str
    data: Any
 class RunStreamBroker(Protocol):
    """Realtime publish/subscribe boundary for run streams."""
    async def publish(self, run_id: RunId, event: str, data: Any) -> None:
        pass
    async def publish_terminal(self, run_id: RunId, *, event: str = "end", data: Any = None) -> None:
        pass
    def subscribe(
        self,
        run_id: RunId,
        *,
        last_event_id: str | None = None,
        heartbeat_interval: float = 15.0,
    ) -> AsyncIterator[RunStreamEvent]:
        pass
    async def cleanup(self, run_id: RunId, *, delay: float = 0) -> None:
        pass
 __all__ = [
    "RunStreamBroker",
    "RunStreamEvent",
 ]
@@ -150,6 +150,7 @@ async def run_agent(
    pre_run_checkpoint_id: str | None = None
    pre_run_snapshot: dict[str, Any] | None = None
    snapshot_capture_failed = False
    llm_error_fallback_message: str | None = None
    journal = None
@@ -312,6 +313,7 @@ async def run_agent(
                if record.abort_event.is_set():
                    logger.info("Run %s abort requested — stopping", run_id)
                    break
                llm_error_fallback_message = llm_error_fallback_message or _extract_llm_error_fallback_message(chunk)
                sse_event = _lg_mode_to_sse_event(single_mode)
                await bridge.publish(run_id, sse_event, serialize(chunk, mode=single_mode))
        else:
@@ -330,6 +332,7 @@ async def run_agent(
                if mode is None:
                    continue
                llm_error_fallback_message = llm_error_fallback_message or _extract_llm_error_fallback_message(chunk)
                sse_event = _lg_mode_to_sse_event(mode)
                await bridge.publish(run_id, sse_event, serialize(chunk, mode=mode))
@@ -352,6 +355,12 @@ async def run_agent(
                    logger.warning("Failed to rollback checkpoint for run %s", run_id, exc_info=True)
            else:
                await run_manager.set_status(run_id, RunStatus.interrupted)
        elif llm_error_fallback_message or (journal is not None and journal.had_llm_error_fallback):
            error_msg = llm_error_fallback_message
            if error_msg is None and journal is not None:
                error_msg = journal.llm_error_fallback_message
            error_msg = error_msg or "LLM provider failed after retries"
            await run_manager.set_status(run_id, RunStatus.error, error=error_msg)
        else:
            await run_manager.set_status(run_id, RunStatus.success)
@@ -554,6 +563,85 @@ def _lg_mode_to_sse_event(mode: str) -> str:
    return mode
 def _error_fallback_message_from_metadata(metadata: dict[str, Any], content: Any) -> str:
    detail = metadata.get("error_detail")
    if isinstance(detail, str) and detail.strip():
        return detail.strip()
    reason = metadata.get("error_reason")
    if isinstance(reason, str) and reason.strip():
        return reason.strip()
    if isinstance(content, str) and content.strip():
        return content.strip()[:2000]
    return "LLM provider failed after retries"
 def _try_extract_from_message(obj: Any) -> str | None:
    """Try to extract fallback marker from a single message object or dict."""
    additional_kwargs = getattr(obj, "additional_kwargs", None)
    if isinstance(additional_kwargs, dict) and additional_kwargs.get("deerflow_error_fallback"):
        return _error_fallback_message_from_metadata(additional_kwargs, getattr(obj, "content", None))
    if isinstance(obj, dict):
        nested_kwargs = obj.get("additional_kwargs")
        if isinstance(nested_kwargs, dict) and nested_kwargs.get("deerflow_error_fallback"):
            return _error_fallback_message_from_metadata(nested_kwargs, obj.get("content"))
    return None
 def _extract_llm_error_fallback_message(value: Any) -> str | None:
    """Find LLM fallback markers in streamed LangGraph chunks.
    Error fallback messages returned by model-call middleware are not guaranteed
    to pass through LLM end callbacks, but they do appear in graph state chunks.
    """
    # Fast path: large state chunks produced by stream_mode="values" have a
    # top-level "messages" list. Scanning only that list avoids expensive deep
    # recursion into large state dicts.
    if isinstance(value, dict):
        messages = value.get("messages")
        if isinstance(messages, (list, tuple)):
            for msg in messages:
                result = _try_extract_from_message(msg)
                if result is not None:
                    return result
            # Fallback marker is attached to an AI message in the messages
            # channel; it will never appear elsewhere in a values chunk.
            return None
        # No top-level "messages" — this is likely an "updates" chunk (small
        # dict keyed by node name). Fall through to deep walk, which is cheap
        # for these payloads.
    # Deep walk for updates / messages / tuple / list modes. Payloads are
    # small, so full recursion is acceptable here.
    seen: set[int] = set()
    def walk(obj: Any) -> str | None:
        oid = id(obj)
        if oid in seen:
            return None
        seen.add(oid)
        result = _try_extract_from_message(obj)
        if result is not None:
            return result
        if isinstance(obj, dict):
            for item in obj.values():
                result = walk(item)
                if result is not None:
                    return result
            return None
        if isinstance(obj, (list, tuple, set)):
            for item in obj:
                result = walk(item)
                if result is not None:
                    return result
        return None
    return walk(value)
 def _extract_human_message(graph_input: dict) -> HumanMessage | None:
    """Extract or construct a HumanMessage from graph_input for event recording.
@@ -22,11 +22,13 @@ from __future__ import annotations
 import contextlib
 import logging
 import threading
 from collections.abc import Iterator
 from langgraph.store.base import BaseStore
 from deerflow.config.app_config import get_app_config
 from deerflow.config.checkpointer_config import ensure_config_loaded
 from deerflow.runtime.store._sqlite_utils import ensure_sqlite_parent_dir, resolve_sqlite_conn_str
 logger = logging.getLogger(__name__)
@@ -100,6 +102,7 @@ def _sync_store_cm(config) -> Iterator[BaseStore]:
 _store: BaseStore | None = None
 _store_ctx = None  # open context manager keeping the connection alive
 _store_lock = threading.Lock()
 def get_store() -> BaseStore:
@@ -117,29 +120,29 @@ def get_store() -> BaseStore:
    if _store is not None:
        return _store
-    # Lazily load app config, mirroring the checkpointer singleton pattern so
+    # Config loading can reset both persistence singletons. Keep it outside
-    # that tests that set the global checkpointer config explicitly remain isolated.
+    # this provider lock to avoid cross-provider lock-order inversion.
-    from deerflow.config.app_config import _app_config
+    ensure_config_loaded()
    from deerflow.config.checkpointer_config import get_checkpointer_config
-    config = get_checkpointer_config()
+    with _store_lock:
        if _store is not None:
            return _store
        from deerflow.config.checkpointer_config import get_checkpointer_config
    if config is None and _app_config is None:
        try:
            get_app_config()
        except FileNotFoundError:
            pass
        config = get_checkpointer_config()
-    if config is None:
+        if config is None:
-        from langgraph.store.memory import InMemoryStore
+            from langgraph.store.memory import InMemoryStore
-        logger.warning("No 'checkpointer' section in config.yaml — using InMemoryStore for the store. Thread list will be lost on server restart. Configure a sqlite or postgres backend for persistence.")
+            logger.warning("No 'checkpointer' section in config.yaml — using InMemoryStore for the store. Thread list will be lost on server restart. Configure a sqlite or postgres backend for persistence.")
-        _store = InMemoryStore()
+            _store = InMemoryStore()
-        return _store
+            return _store
-    _store_ctx = _sync_store_cm(config)
+        store_ctx = _sync_store_cm(config)
-    _store = _store_ctx.__enter__()
+        store = store_ctx.__enter__()
        _store_ctx = store_ctx
        _store = store
    return _store
@@ -150,13 +153,14 @@ def reset_store() -> None:
    Useful in tests or after a configuration change.
    """
    global _store, _store_ctx
-    if _store_ctx is not None:
+    with _store_lock:
-        try:
+        if _store_ctx is not None:
-            _store_ctx.__exit__(None, None, None)
+            try:
-        except Exception:
+                _store_ctx.__exit__(None, None, None)
-            logger.warning("Error during store cleanup", exc_info=True)
+            except Exception:
-        _store_ctx = None
+                logger.warning("Error during store cleanup", exc_info=True)
-    _store = None
+            _store_ctx = None
        _store = None
 # ---------------------------------------------------------------------------
@@ -1,4 +1,5 @@
 import asyncio
 import os
 import posixpath
 import re
 import shlex
@@ -43,6 +44,16 @@ _MAX_GLOB_MAX_RESULTS = 1000
 _DEFAULT_GREP_MAX_RESULTS = 100
 _MAX_GREP_MAX_RESULTS = 500
 _DEFAULT_WRITE_FILE_ERROR_MAX_CHARS = 2000
 # Maximum bytes accepted in a single non-append write_file call (issue #3189).
 # Oversized single-shot writes correlate with LLM streaming chunk-gap timeouts
 # because the tool-call JSON payload (which the model must emit as one
 # continuous stream) grows past the safe window. 80 KB ≈ 20K tokens, a
 # comfortable headroom under the factory-default 240s stream_chunk_timeout.
 # Deployments can override via env var DEERFLOW_WRITE_FILE_MAX_BYTES; set to
 # 0 (or negative) to disable the guard entirely.
 _WRITE_FILE_CONTENT_MAX_BYTES = 80 * 1024
 _WRITE_FILE_MAX_BYTES_ENV = "DEERFLOW_WRITE_FILE_MAX_BYTES"
 _LOCAL_BASH_CWD_COMMANDS = {"cd", "pushd"}
 _LOCAL_BASH_COMMAND_WRAPPERS = {"command", "builtin"}
 _LOCAL_BASH_COMMAND_PREFIX_KEYWORDS = {"!", "{", "case", "do", "elif", "else", "for", "if", "select", "then", "time", "until", "while"}
@@ -1671,6 +1682,23 @@ async def _read_file_tool_async(
 read_file_tool.coroutine = _read_file_tool_async
 def _effective_write_file_max_bytes() -> int:
    """Return the active size cap for non-append write_file calls.
    Reads ``DEERFLOW_WRITE_FILE_MAX_BYTES`` at call time (not import time)
    so tests and runtime tweaks take effect without restart. Falls back to
    the default on missing/malformed values. A non-positive value disables
    the guard.
    """
    raw = os.environ.get(_WRITE_FILE_MAX_BYTES_ENV)
    if raw is None:
        return _WRITE_FILE_CONTENT_MAX_BYTES
    try:
        return int(raw)
    except ValueError:
        return _WRITE_FILE_CONTENT_MAX_BYTES
@tool("write_file", parse_docstring=True)
 def write_file_tool(
    runtime: Runtime,
@@ -1679,14 +1707,47 @@ def write_file_tool(
    content: str,
    append: bool = False,
 ) -> str:
-    """Write text content to a file. By default this overwrites the target file; set append to true to add content to the end without replacing existing content.
+    """Write text content to a file. By default this overwrites the target file; set append=True to add content to the end without replacing existing content.
    SIZE POLICY (issue #3189):
    A single non-append write_file call must not exceed 80 KB of UTF-8 content.
    Oversized single-shot writes correlate with LLM streaming chunk-gap
    timeouts because the tool-call JSON payload — which the model must emit as
    one continuous stream — grows past the safe window. For larger documents,
    use ONE of these strategies (write_file rejects oversized payloads with an
    actionable error):
      1. INCREMENTAL EDIT (preferred for revisions): after the initial write,
         use `str_replace` to surgically update sections. This is the same
         pattern Claude Code's Write+Edit and OpenAI Codex's apply_patch use,
         and keeps each tool call's payload small.
      2. APPEND-IN-CHUNKS (for new long-form content): split the document into
         sections, each well under 80 KB. First call uses append=False to
         create the file; subsequent calls use append=True. The 80 KB cap does
         NOT apply to append=True calls.
    Operators can override the cap via env var `DEERFLOW_WRITE_FILE_MAX_BYTES`
    (0 disables the guard entirely). Raising it risks streaming timeouts.
    Args:
        description: Explain why you are writing to this file in short words. ALWAYS PROVIDE THIS PARAMETER FIRST.
        path: The **absolute** path to the file to write to. ALWAYS PROVIDE THIS PARAMETER SECOND.
        content: The content to write to the file. ALWAYS PROVIDE THIS PARAMETER THIRD.
-        append: Whether to append content to the end of the file instead of overwriting it. Defaults to false.
+        append: Whether to append content to the end of the file instead of overwriting it. Defaults to False.
    """
    if not append:
        max_bytes = _effective_write_file_max_bytes()
        if max_bytes > 0:
            content_bytes = len(content.encode("utf-8"))
            if content_bytes > max_bytes:
                return (
                    f"Error: write_file content ({content_bytes} bytes) exceeds the "
                    f"{max_bytes}-byte single-call limit. Split the content into smaller "
                    "pieces: either (a) write the first section now, then use `str_replace` "
                    "for further edits, or (b) call write_file again with append=True "
                    "carrying the next section. See SIZE POLICY in the tool docstring "
                    "or issue #3189 for the rationale."
                )
    try:
        requested_path = path
        sandbox = ensure_sandbox_initialized(runtime)
@@ -9,6 +9,37 @@ from .types import SKILL_MD_FILE, Skill, SkillCategory
 logger = logging.getLogger(__name__)
 def _format_yaml_error(skill_file: Path, exc: yaml.YAMLError, source: str) -> str:
    """Render a developer-friendly explanation of a YAML front-matter error."""
    lines = [f"Invalid YAML front-matter in {skill_file}: {exc}"]
    mark = getattr(exc, "problem_mark", None)
    source_lines = source.splitlines()
    if mark is not None and 0 <= mark.line < len(source_lines):
        offending = source_lines[mark.line]
        # mark.line is 0-based within the front-matter body; +1 makes it
        # 1-based, +1 more accounts for the leading `---` fence that the
        # front-matter regex strips before yaml.safe_load sees it. The
        # result matches the line number an author sees in their editor.
        file_line_number = mark.line + 2
        lines.append(f"  line {file_line_number}: {offending}")
        # Targeted hint for the most common authoring mistake: an unquoted
        # scalar value whose body contains ``: ``. We only surface the hint
        # when we are confident it applies, to avoid misleading authors who
        # hit unrelated YAML errors.
        if getattr(exc, "problem", "") == "mapping values are not allowed here" and ":" in offending:
            key, _, value = offending.partition(":")
            value = value.strip()
            if value and value[0] not in {'"', "'", "|", ">", "[", "{"}:
                escaped = value.replace("\\", "\\\\").replace('"', '\\"')
                lines.append(f'  hint: values containing ":" must be quoted, e.g. {key}: "{escaped}"')
    return "\n".join(lines)
 def parse_allowed_tools(raw: object, skill_file: Path) -> list[str] | None:
    """Parse the optional allowed-tools frontmatter field.
@@ -60,7 +91,7 @@ def parse_skill_file(skill_file: Path, category: SkillCategory, relative_path: P
        try:
            metadata = yaml.safe_load(front_matter_text)
        except yaml.YAMLError as exc:
-            logger.error("Invalid YAML front-matter in %s: %s", skill_file, exc)
+            logger.error("%s", _format_yaml_error(skill_file, exc, front_matter_text))
            return None
        if not isinstance(metadata, dict):
@@ -24,6 +24,17 @@ Do NOT use for simple, single-step operations.""",
 - Do NOT ask for clarification - work with the information provided
 </guidelines>
 <file_editing_workflow>
 When revising an existing file, prefer `str_replace` over `write_file` —
 it sends only the diff and avoids re-emitting the whole file (mirrors
 Claude Code's Edit and Codex's apply_patch). When writing long new
 content from scratch, split it into sections: the first `write_file`
 call creates the file, then use `write_file` with append=True to extend
 it section by section. This keeps each tool call small and avoids
 mid-stream chunk-gap timeouts on oversized single-shot writes.
 (See issue #3189.)
 </file_editing_workflow>
 <output_format>
 When you complete the task, provide:
 1. A brief summary of what was accomplished
@@ -12,7 +12,7 @@ from contextvars import Context, copy_context
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
-from typing import Any
+from typing import TYPE_CHECKING, Any
 from langchain.agents import create_agent
 from langchain.tools import BaseTool
@@ -28,6 +28,13 @@ from deerflow.skills.types import Skill
 from deerflow.subagents.config import SubagentConfig, resolve_subagent_model_name
 from deerflow.subagents.token_collector import SubagentTokenCollector
 if TYPE_CHECKING:
    # Imported lazily at runtime inside _build_initial_state: importing
    # tool_search eagerly would run tools/builtins/__init__ -> task_tool ->
    # `from deerflow.subagents import SubagentExecutor`, which re-enters this
    # still-initializing package. Type-only here keeps the annotation precise.
    from deerflow.tools.builtins.tool_search import DeferredToolSetup
 logger = logging.getLogger(__name__)
@@ -319,8 +326,13 @@ class SubagentExecutor:
        logger.info(f"[trace={self.trace_id}] SubagentExecutor initialized: {config.name} with {len(self.tools)} tools")
-    def _create_agent(self, tools: list[BaseTool] | None = None):
+    def _create_agent(self, tools: list[BaseTool] | None = None, *, deferred_setup: "DeferredToolSetup | None" = None):
-        """Create the agent instance."""
+        """Create the agent instance.
        ``deferred_setup`` (assembled in ``_build_initial_state``) carries the
        deferred MCP tool names + catalog hash so the subagent gets the same
        DeferredToolFilterMiddleware the lead agent has. ``None`` is a no-op.
        """
        app_config = self.app_config or get_app_config()
        if self.model_name is None:
            self.model_name = resolve_subagent_model_name(self.config, self.parent_model, app_config=app_config)
@@ -329,7 +341,7 @@ class SubagentExecutor:
        from deerflow.agents.middlewares.tool_error_handling_middleware import build_subagent_runtime_middlewares
        # Reuse shared middleware composition with lead agent.
-        middlewares = build_subagent_runtime_middlewares(app_config=app_config, model_name=self.model_name, lazy_init=True)
+        middlewares = build_subagent_runtime_middlewares(app_config=app_config, model_name=self.model_name, lazy_init=True, deferred_setup=deferred_setup)
        # system_prompt is included in initial state messages (see _build_initial_state)
        # to avoid multiple SystemMessages which some LLM APIs don't support.
@@ -403,19 +415,35 @@ class SubagentExecutor:
        return messages
-    async def _build_initial_state(self, task: str) -> tuple[dict[str, Any], list[BaseTool]]:
+    async def _build_initial_state(self, task: str) -> tuple[dict[str, Any], list[BaseTool], "DeferredToolSetup"]:
        """Build the initial state for agent execution.
        Args:
            task: The task description.
        Returns:
-            Initial state dictionary and tools filtered by loaded skill metadata.
+            ``(state, final_tools, deferred_setup)``. ``final_tools`` is the
            policy-filtered tool list with the ``tool_search`` tool appended when
            deferral applies; ``deferred_setup`` is consumed by ``_create_agent``
            so the agent build and the injected ``<available-deferred-tools>``
            section share one catalog/hash.
        """
        # Lazy import: see the TYPE_CHECKING note at the top of this module -
        # importing tool_search runs tools/builtins/__init__, which would
        # re-enter this package during its own initialization.
        from deerflow.tools.builtins.tool_search import assemble_deferred_tools, get_deferred_tools_prompt_section
        # Load skills as conversation items (Codex pattern)
        skills = await self._load_skills()
        filtered_tools = self._apply_skill_allowed_tools(skills)
        # Assemble deferred tool_search AFTER policy filtering (fail-closed),
        # mirroring the lead path so subagents stop binding full MCP schemas.
        # The generated tool_search helper is intentionally not subject to the
        # subagent's name-level allow/deny (config.tools / disallowed_tools):
        # its catalog is built from the already-filtered list, so it can never
        # surface a tool the policy denied. This matches the lead agent.
        enabled = (self.app_config or get_app_config()).tool_search.enabled
        final_tools, deferred_setup = assemble_deferred_tools(filtered_tools, enabled=enabled)
        skill_messages = await self._load_skill_messages(skills)
        # Combine system_prompt and skills into a single SystemMessage.
@@ -426,6 +454,11 @@ class SubagentExecutor:
            system_parts.append(self.config.system_prompt)
        for skill_msg in skill_messages:
            system_parts.append(skill_msg.content)
        # Name the deferred MCP tools in the prompt; their schemas stay withheld
        # until tool_search promotes them. Empty set -> "" -> appends nothing.
        deferred_section = get_deferred_tools_prompt_section(deferred_names=deferred_setup.deferred_names)
        if deferred_section:
            system_parts.append(deferred_section)
        messages: list[Any] = []
        if system_parts:
@@ -444,7 +477,7 @@ class SubagentExecutor:
        if self.thread_data is not None:
            state["thread_data"] = self.thread_data
-        return state, filtered_tools
+        return state, final_tools, deferred_setup
    async def _aexecute(self, task: str, result_holder: SubagentResult | None = None) -> SubagentResult:
        """Execute a task asynchronously.
@@ -475,8 +508,8 @@ class SubagentExecutor:
        collector: SubagentTokenCollector | None = None
        try:
-            state, filtered_tools = await self._build_initial_state(task)
+            state, final_tools, deferred_setup = await self._build_initial_state(task)
-            agent = self._create_agent(filtered_tools)
+            agent = self._create_agent(final_tools, deferred_setup=deferred_setup)
            # Token collector for subagent LLM calls
            collector_caller = f"subagent:{self.config.name}"
@@ -0,0 +1,102 @@
 """Backend↔frontend contract for the structured subagent status.
 Bytedance/deer-flow issue #3146: the frontend used to derive the
 subtask card state by string-matching the leading text of the
 ``task`` tool's result. That contract was fragile — any rewording on
 the backend silently broke the card lifecycle, and the issue history
 of #3107 BUG-007 / #3131 review showed it repeatedly.
 This module replaces the text-shaped contract with a small structured
 one carried inside ``ToolMessage.additional_kwargs``:
 - ``subagent_status``: one of ``SUBAGENT_STATUS_VALUES``.
 - ``subagent_error`` (optional): the human-readable error blob the
  backend recorded.
 The mapping from "task tool result text" to status is the one piece
 the backend stamper (``ToolErrorHandlingMiddleware``) and the
 frontend fallback parser must agree on. The shared fixture at
 ``contracts/subagent_status_contract.json`` is the single source of
 truth — both sides' tests load it and assert behaviour.
 """
 from __future__ import annotations
 from typing import Literal
 SUBAGENT_STATUS_KEY = "subagent_status"
 SUBAGENT_ERROR_KEY = "subagent_error"
 SubagentStatusValue = Literal[
    "completed",
    "failed",
    "cancelled",
    "timed_out",
    "polling_timed_out",
 ]
 #: Enumeration of every value ``subagent_status`` may take. Mirrors the
 #: ``valid_status_values`` array in the shared fixture; the contract test
 #: pins them against each other.
 SUBAGENT_STATUS_VALUES: tuple[SubagentStatusValue, ...] = (
    "completed",
    "failed",
    "cancelled",
    "timed_out",
    "polling_timed_out",
 )
 # Prefix table — ordered most-specific-first because some prefixes are
 # substrings of others ("Task timed out" vs "Task polling timed out", "Task
 # failed" vs "Task failed. Error: ..."). The "Task " prefixes come from
 # ``task_tool.py``'s 5 normal-return strings; the bare ``Error:`` prefix
 # catches both the 3 ``Error:`` pre-execution returns and the wrapper
 # produced by ``ToolErrorHandlingMiddleware`` for any task tool exception.
 _PREFIX_TO_STATUS: tuple[tuple[str, SubagentStatusValue], ...] = (
    ("Task Succeeded. Result:", "completed"),
    ("Task polling timed out", "polling_timed_out"),
    ("Task timed out", "timed_out"),
    ("Task cancelled by user", "cancelled"),
    ("Task failed.", "failed"),
    ("Error", "failed"),
 )
 def extract_subagent_status(content: str) -> SubagentStatusValue | None:
    """Infer the structured status for a ``task`` tool result string.
    Returns ``None`` when the content does not match any known terminal
    prefix. Non-terminal streaming chunks fall into this branch by
    design — the middleware then leaves ``subagent_status`` unset so
    the frontend keeps the card on its in-progress placeholder until
    the real terminal frame arrives.
    """
    trimmed = content.strip()
    for prefix, status in _PREFIX_TO_STATUS:
        if trimmed.startswith(prefix):
            return status
    return None
 def make_subagent_additional_kwargs(
    status: SubagentStatusValue,
    *,
    error: str | None = None,
 ) -> dict[str, str]:
    """Build the ``additional_kwargs`` payload the middleware stamps.
    Drops the error field when blank so the JSON wire format never carries
    a misleading empty ``subagent_error: ""``.
    Raises:
        ValueError: when ``status`` is not in :data:`SUBAGENT_STATUS_VALUES`.
            We do not accept arbitrary strings: a typo would silently leak
            through to the frontend and degrade to the legacy prefix
            fallback rather than failing loudly.
    """
    if status not in SUBAGENT_STATUS_VALUES:
        raise ValueError(f"invalid subagent status {status!r}; expected one of {SUBAGENT_STATUS_VALUES}")
    payload: dict[str, str] = {SUBAGENT_STATUS_KEY: status}
    if error and error.strip():
        payload[SUBAGENT_ERROR_KEY] = error.strip()
    return payload
@@ -1,202 +1,221 @@
 """Tool search — deferred tool discovery at runtime.
 Contains:
- DeferredToolRegistry: stores deferred tools and handles regex search
+- DeferredToolCatalog: immutable, searchable catalog of deferred tools.
- tool_search: the LangChain tool the agent calls to discover deferred tools
+- build_tool_search_tool: builds the `tool_search` tool as a closure over a
  catalog; it records promotions into graph state via ``Command``.
 - build_deferred_tool_setup: assembles the catalog + tool from a
  policy-filtered tool list (call AFTER tool-policy filtering).
 The agent sees deferred tool names in <available-deferred-tools> but cannot
-call them until it fetches their full schema via the tool_search tool.
+call them until it fetches their full schema via the tool_search tool. The
-Source-agnostic: no mention of MCP or tool origin.
+deferred set rides on a build-time closure and promotion lives in per-thread
 graph state — there is no ContextVar. Source-agnostic: a tool is "deferred"
 when it carries the ``deerflow_mcp`` metadata tag.
 """
-import contextvars
+import hashlib
 import json
 import logging
 import re
 from dataclasses import dataclass
 from functools import cached_property
 from typing import Annotated
 from langchain.tools import BaseTool
-from langchain_core.tools import tool
+from langchain_core.messages import ToolMessage
 from langchain_core.tools import InjectedToolCallId, tool
 from langchain_core.utils.function_calling import convert_to_openai_function
 from langgraph.types import Command
 from deerflow.tools.mcp_metadata import is_mcp_tool
 logger = logging.getLogger(__name__)
 MAX_RESULTS = 5  # Max tools returned per search
-# ── Registry ──
+def _compile_catalog_regex(pattern: str) -> re.Pattern[str]:
    """Compile ``pattern`` case-insensitively, falling back to a literal match.
    Search queries come from the model, so an invalid regex (e.g. an unbalanced
    paren) must degrade to a literal substring match rather than raise.
    """
    try:
        return re.compile(pattern, re.IGNORECASE)
    except re.error:
        return re.compile(re.escape(pattern), re.IGNORECASE)
-@dataclass
+# ── Catalog ──
 class DeferredToolEntry:
    """Lightweight metadata for a deferred tool (no full schema in context)."""
    name: str
    description: str
    tool: BaseTool  # Full tool object, returned only on search match
-class DeferredToolRegistry:
+# NOTE: frozen=True without slots=True keeps __dict__, which is what lets the
-    """Registry of deferred tools, searchable by regex pattern."""
+# @cached_property fields below cache (they write to instance.__dict__, bypassing
 # the frozen __setattr__). Do NOT add slots=True or hash/names break at runtime.
@dataclass(frozen=True)
 class DeferredToolCatalog:
    """Immutable catalog of deferred tools. Pure search, no mutation."""
-    def __init__(self):
+    tools: tuple[BaseTool, ...]
        self._entries: list[DeferredToolEntry] = []
-    def register(self, tool: BaseTool) -> None:
+    @cached_property
-        self._entries.append(
+    def names(self) -> frozenset[str]:
-            DeferredToolEntry(
+        return frozenset(t.name for t in self.tools)
                name=tool.name,
                description=tool.description or "",
                tool=tool,
            )
        )
-    def promote(self, names: set[str]) -> None:
+    @cached_property
-        """Remove tools from the deferred registry so they pass through the filter.
+    def hash(self) -> str:
-
+        canon = [{"name": t.name, "schema": convert_to_openai_function(t)} for t in sorted(self.tools, key=lambda t: t.name)]
-        Called after tool_search returns a tool's schema — the LLM now knows
+        blob = json.dumps(canon, sort_keys=True, ensure_ascii=False, default=str)
-        the full definition, so the DeferredToolFilterMiddleware should stop
+        return hashlib.sha256(blob.encode("utf-8")).hexdigest()[:16]
        stripping it from bind_tools on subsequent calls.
        """
        if not names:
            return
        before = len(self._entries)
        self._entries = [e for e in self._entries if e.name not in names]
        promoted = before - len(self._entries)
        if promoted:
            logger.debug(f"Promoted {promoted} tool(s) from deferred to active: {names}")
    def search(self, query: str) -> list[BaseTool]:
-        """Search deferred tools by regex pattern against name + description.
+        query = query.strip()
        if not query:
            return []
        Supports three query forms (aligned with Claude Code):
          - "select:name1,name2" — exact name match
          - "+keyword rest" — name must contain keyword, rank by rest
          - "keyword query" — regex match against name + description
        Returns:
            List of matched BaseTool objects (up to MAX_RESULTS).
        """
        if query.startswith("select:"):
-            names = {n.strip() for n in query[7:].split(",")}
+            wanted = {n.strip() for n in query[7:].split(",")}
-            return [e.tool for e in self._entries if e.name in names][:MAX_RESULTS]
+            return [t for t in self.tools if t.name in wanted][:MAX_RESULTS]
        if query.startswith("+"):
            parts = query[1:].split(None, 1)
            if not parts:
                return []  # bare "+" with no required token — nothing to require
            required = parts[0].lower()
-            candidates = [e for e in self._entries if required in e.name.lower()]
+            candidates = [t for t in self.tools if required in t.name.lower()]
            if len(parts) > 1:
-                candidates.sort(
+                candidates.sort(key=lambda t: _catalog_regex_score(parts[1], t), reverse=True)
-                    key=lambda e: _regex_score(parts[1], e),
+            return candidates[:MAX_RESULTS]
                    reverse=True,
                )
            return [e.tool for e in candidates][:MAX_RESULTS]
-        # General regex search
+        regex = _compile_catalog_regex(query)
-        try:
+        scored: list[tuple[int, BaseTool]] = []
-            regex = re.compile(query, re.IGNORECASE)
+        for t in self.tools:
-        except re.error:
+            searchable = f"{t.name} {t.description or ''}"
            regex = re.compile(re.escape(query), re.IGNORECASE)
        scored = []
        for entry in self._entries:
            searchable = f"{entry.name} {entry.description}"
            if regex.search(searchable):
-                score = 2 if regex.search(entry.name) else 1
+                scored.append((2 if regex.search(t.name) else 1, t))
                scored.append((score, entry))
        scored.sort(key=lambda x: x[0], reverse=True)
-        return [entry.tool for _, entry in scored][:MAX_RESULTS]
+        return [t for _, t in scored][:MAX_RESULTS]
    @property
    def entries(self) -> list[DeferredToolEntry]:
        return list(self._entries)
    @property
    def deferred_names(self) -> set[str]:
        """Names of tools that are still hidden from model binding."""
        return {entry.name for entry in self._entries}
    def contains(self, name: str) -> bool:
        """Return whether *name* is still deferred."""
        return any(entry.name == name for entry in self._entries)
    def __len__(self) -> int:
        return len(self._entries)
-def _regex_score(pattern: str, entry: DeferredToolEntry) -> int:
+def _catalog_regex_score(pattern: str, t: BaseTool) -> int:
-    try:
+    regex = _compile_catalog_regex(pattern)
-        regex = re.compile(pattern, re.IGNORECASE)
+    return len(regex.findall(f"{t.name} {t.description or ''}"))
    except re.error:
        regex = re.compile(re.escape(pattern), re.IGNORECASE)
    return len(regex.findall(f"{entry.name} {entry.description}"))
-# ── Per-request registry (ContextVar) ──
+# ── Setup / tool ──
 #
 # Using a ContextVar instead of a module-level global prevents concurrent
 # requests from clobbering each other's registry.  In asyncio-based LangGraph
 # each graph run executes in its own async context, so each request gets an
 # independent registry value.  For synchronous tools run via
 # loop.run_in_executor, Python copies the current context to the worker thread,
 # so the ContextVar value is correctly inherited there too.
 _registry_var: contextvars.ContextVar[DeferredToolRegistry | None] = contextvars.ContextVar("deferred_tool_registry", default=None)
-def get_deferred_registry() -> DeferredToolRegistry | None:
+@dataclass(frozen=True)
-    return _registry_var.get()
+class DeferredToolSetup:
    """Result of assembling deferred-tool support for one agent build.
    The three fields move as a unit, so callers branch on ``tool_search_tool``:
-def set_deferred_registry(registry: DeferredToolRegistry) -> None:
+    - **Empty** ``(None, frozenset(), None)``: deferral is disabled, or no MCP
-    _registry_var.set(registry)
+      tool survived policy filtering. Nothing is deferred — bind tools as-is.
    - **Populated**: ``tool_search_tool`` is appended to the agent's tools,
      ``deferred_names`` are withheld from the model until promoted, and
      ``catalog_hash`` scopes those promotions in graph state.
-
+    Invariant: ``tool_search_tool is None`` ⟺ ``deferred_names`` is empty ⟺
-def reset_deferred_registry() -> None:
+    ``catalog_hash is None``.
    """Reset the deferred registry for the current async context."""
    _registry_var.set(None)
 # ── Tool ──
@tool
 def tool_search(query: str) -> str:
    """Fetches full schema definitions for deferred tools so they can be called.
    Deferred tools appear by name in <available-deferred-tools> in the system
    prompt. Until fetched, only the name is known — there is no parameter
    schema, so the tool cannot be invoked. This tool takes a query, matches
    it against the deferred tool list, and returns the matched tools' complete
    definitions. Once a tool's schema appears in that result, it is callable.
    Query forms:
      - "select:Read,Edit,Grep" — fetch these exact tools by name
      - "notebook jupyter" — keyword search, up to max_results best matches
      - "+slack send" — require "slack" in the name, rank by remaining terms
    Args:
        query: Query to find deferred tools. Use "select:<tool_name>" for
               direct selection, or keywords to search.
    Returns:
        Matched tool definitions as JSON array.
    """
    registry = get_deferred_registry()
    if not registry:
        return "No deferred tools available."
-    matched_tools = registry.search(query)
+    tool_search_tool: BaseTool | None
-    if not matched_tools:
+    deferred_names: frozenset[str]
-        return f"No tools found matching: {query}"
+    catalog_hash: str | None
    # Use LangChain's built-in serialization to produce OpenAI function format.
    # This is model-agnostic: all LLMs understand this standard schema.
    tool_defs = [convert_to_openai_function(t) for t in matched_tools[:MAX_RESULTS]]
-    # Promote matched tools so the DeferredToolFilterMiddleware stops filtering
+def build_tool_search_tool(catalog: DeferredToolCatalog) -> BaseTool:
-    # them from bind_tools — the LLM now has the full schema and can invoke them.
+    catalog_hash = catalog.hash
    registry.promote({t.name for t in matched_tools[:MAX_RESULTS]})
-    return json.dumps(tool_defs, indent=2, ensure_ascii=False)
+    @tool
    def tool_search(query: str, tool_call_id: Annotated[str, InjectedToolCallId]) -> Command:
        """Fetches full schema definitions for deferred tools so they can be called.
        Deferred tools appear by name in <available-deferred-tools> in the system
        prompt. Until fetched, only the name is known. This tool matches a query
        against the deferred tools and returns the matched tools complete schemas;
        once returned, a tool becomes callable.
        Query forms:
          - "select:Read,Edit" -- fetch these exact tools by name
          - "notebook jupyter" -- keyword search, up to max_results best matches
          - "+slack send" -- require "slack" in the name, rank by remaining terms
        """
        matched = catalog.search(query)[:MAX_RESULTS]
        if not matched:
            content, names = f"No tools found matching: {query}", []
        else:
            content = json.dumps([convert_to_openai_function(t) for t in matched], indent=2, ensure_ascii=False)
            names = [t.name for t in matched]
        return Command(
            update={
                "promoted": {"catalog_hash": catalog_hash, "names": names},
                "messages": [ToolMessage(content=content, tool_call_id=tool_call_id, name="tool_search")],
            }
        )
    return tool_search
 def build_deferred_tool_setup(filtered_tools: list[BaseTool], *, enabled: bool) -> DeferredToolSetup:
    """Build the deferred-tool setup from a POLICY-FILTERED tool list.
    Must be called after skill/agent tool-policy filtering so the catalog never
    exposes a tool the current agent is not allowed to use.
    Returns an empty setup (see :class:`DeferredToolSetup`) in two distinct
    cases: deferral is disabled, or it is enabled but no MCP tool survived
    filtering.
    """
    if not enabled:
        # Deferral disabled: defer nothing; the model binds every tool as before.
        return DeferredToolSetup(None, frozenset(), None)
    deferred = [t for t in filtered_tools if is_mcp_tool(t)]
    if not deferred:
        # Enabled, but no MCP tool to defer: same empty result, different reason.
        return DeferredToolSetup(None, frozenset(), None)
    catalog = DeferredToolCatalog(tuple(deferred))
    return DeferredToolSetup(build_tool_search_tool(catalog), catalog.names, catalog.hash)
 def assemble_deferred_tools(filtered_tools: list[BaseTool], *, enabled: bool) -> tuple[list[BaseTool], DeferredToolSetup]:
    """Build the final tool list + deferred setup from a POLICY-FILTERED list.
    Call AFTER tool-policy filtering so the deferred catalog never exposes a tool
    the agent is not allowed to use. Fail-closed: if tool_search is enabled and
    MCP tools survived filtering but no deferred set was recovered, raise rather
    than silently binding their full schemas to the model.
    Shared by every agent-build path (lead, embedded client, subagent) so they
    all get the same fail-closed guarantee from one place.
    """
    deferred_setup = build_deferred_tool_setup(filtered_tools, enabled=enabled)
    if enabled and not deferred_setup.deferred_names and any(is_mcp_tool(t) for t in filtered_tools):
        raise RuntimeError("tool_search enabled and MCP tools survived policy filtering, but no deferred set was recovered - refusing to bind MCP schemas (fail-closed).")
    final_tools = list(filtered_tools)
    if deferred_setup.tool_search_tool:
        final_tools.append(deferred_setup.tool_search_tool)
    return final_tools, deferred_setup
 # Prompt rendering
 def get_deferred_tools_prompt_section(*, deferred_names: frozenset[str] = frozenset()) -> str:
    """Generate <available-deferred-tools> from an explicit deferred-name set.
    Lists only names so the agent knows what exists and can use tool_search to
    load them. Returns empty string when there are no deferred tools. The set is
    computed at agent build time (after tool-policy filtering) and passed in.
    Lives here, next to the assembly that produces ``deferred_names``, so every
    agent-build path (lead, embedded client, subagent) renders the section the
    same way without coupling back to ``lead_agent.prompt``.
    """
    if not deferred_names:
        return ""
    names = "\n".join(sorted(deferred_names))
    return f"<available-deferred-tools>\n{names}\n</available-deferred-tools>"
@@ -17,12 +17,13 @@ from __future__ import annotations
 import logging
 import tempfile
 from pathlib import Path
-from typing import Any
+from typing import Annotated, Any
 import yaml
 from langchain_core.messages import ToolMessage
 from langchain_core.tools import tool
 from langgraph.types import Command
 from pydantic import BeforeValidator
 from deerflow.config.agents_config import load_agent_config, validate_agent_name
 from deerflow.config.app_config import get_app_config
@@ -32,6 +33,8 @@ from deerflow.tools.types import Runtime
 logger = logging.getLogger(__name__)
 _NULLISH_STRINGS = frozenset({"null", "none", "undefined"})
 def _stage_temp(path: Path, text: str) -> Path:
    """Write ``text`` into a sibling temp file and return its path.
@@ -67,14 +70,26 @@ def _cleanup_temps(temps: list[Path]) -> None:
            logger.debug("Failed to clean up temp file %s", tmp, exc_info=True)
 def _is_nullish_string(value: object) -> bool:
    return isinstance(value, str) and value.strip().lower() in _NULLISH_STRINGS
 def _normalize_nullish_string(value: object) -> object:
    return None if _is_nullish_string(value) else value
 OptionalText = Annotated[str | None, BeforeValidator(_normalize_nullish_string)]
 OptionalStringList = Annotated[list[str] | None, BeforeValidator(_normalize_nullish_string)]
@tool(parse_docstring=True)
 def update_agent(
    runtime: Runtime,
-    soul: str | None = None,
+    soul: OptionalText = None,
-    description: str | None = None,
+    description: OptionalText = None,
-    skills: list[str] | None = None,
+    skills: OptionalStringList = None,
-    tool_groups: list[str] | None = None,
+    tool_groups: OptionalStringList = None,
-    model: str | None = None,
+    model: OptionalText = None,
 ) -> Command:
    """Persist updates to the current custom agent's SOUL.md and config.yaml.
@@ -86,7 +101,9 @@ def update_agent(
    semantics, so always start from the current SOUL and apply your edits.
    Pass ``skills=[]`` to disable all skills for this agent. Omit ``skills``
-    entirely to keep the existing whitelist.
+    entirely to keep the existing whitelist. Do not pass literal strings like
    ``"null"`` / ``"none"`` / ``"undefined"`` for unchanged fields; omit those
    fields instead.
    Args:
        soul: Optional full replacement SOUL.md content.
@@ -104,10 +121,10 @@ def update_agent(
    agent_name_raw: str | None = runtime.context.get("agent_name") if runtime.context else None
    def _err(message: str) -> Command:
-        return Command(update={"messages": [ToolMessage(content=f"Error: {message}", tool_call_id=tool_call_id)]})
+        return Command(update={"messages": [ToolMessage(content=f"Error: {message}", tool_call_id=tool_call_id, status="error")]})
    if soul is None and description is None and skills is None and tool_groups is None and model is None:
-        return _err("No fields provided. Pass at least one of: soul, description, skills, tool_groups, model.")
+        return _err('No fields provided. Pass at least one of: soul, description, skills, tool_groups, model. Omit unchanged fields instead of passing null-like strings such as "null", "none", or "undefined".')
    try:
        agent_name = validate_agent_name(agent_name_raw)
--- a/Show More
+++ b/Show More