update github action

Import the committed KnowledgeFS snapshot dc4072ee302317145612087ce7440851dc329fd0 under knowledge-fs/ without its Git history, local IDE settings, or build artifacts.

.agents/skills/frontend-testing/SKILL.md

@@ -9,12 +9,11 @@ Use this skill for Vitest work under `web/` and `packages/dify-ui/`. Do not use
 
 ## Required Source
 
-Before writing, changing, or reviewing frontend tests, read `web/docs/test.md` completely. It is the single source of truth. This skill defines the execution workflow and must not add requirements that conflict with or duplicate that guide.
+Before writing, changing, or reviewing frontend tests, read `web/docs/test.md` completely. It is the single source of truth. This skill provides an execution checklist and must not redefine or extend that policy.
 
 ## Workflow
 
 1. Read the source, its behavior owner, nearby specs, and relevant public dependencies.
-1. Identify whether the contract belongs in `web/`, Dify UI Browser Mode, or a styled Storybook test.
 1. Apply the canonical guide to decide whether a test is needed and choose its boundary.
 1. For a behavior change or bug fix, write or identify the failing scenario first when practical.
 1. Implement one coherent scenario at a time and run the focused spec before expanding scope.
@@ -33,4 +32,4 @@ vp test run path/to/spec-or-directory
 vp test run --project unit src/path/to/spec
 ```
 
-For styled Dify UI behavior, run `vp test --project storybook --run`. Run broader checks only after the focused behavior passes.
+Run Dify UI Storybook tests with `vp test --project storybook --run`. Run broader checks only after the focused behavior passes.

.codex/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y block-no-verify@1.1.1"
+          }
+        ]
+      }
+    ]
+  }
+}

.dockerignore

@@ -8,6 +8,7 @@
 **/*.pyc
 **/.mypy_cache
 **/.ruff_cache
+knowledge-fs/
 .git
 .github
 *.md

.github/dependabot.yml

@@ -1,6 +1,15 @@
 version: 2
 
 updates:
+  - package-ecosystem: "npm"
+    directory: "/knowledge-fs"
+    open-pull-requests-limit: 10
+    schedule:
+      interval: "weekly"
+    groups:
+      knowledge-fs-dependencies:
+        patterns:
+          - "*"
   - package-ecosystem: "uv"
     directory: "/api"
     open-pull-requests-limit: 10

.github/workflows/api-tests.yml

@@ -16,7 +16,7 @@ concurrency:
 jobs:
   api-unit:
     name: API Unit Tests
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     env:
       COVERAGE_FILE: coverage-unit
     defaults:
@@ -75,7 +75,7 @@ jobs:
 
   api-integration:
     name: API Integration Tests
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     env:
       COVERAGE_FILE: coverage-integration
       STORAGE_TYPE: opendal
@@ -129,7 +129,7 @@ jobs:
 
   api-coverage:
     name: API Coverage
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     needs:
       - api-unit
       - api-integration

.github/workflows/build-push.yml

@@ -173,7 +173,7 @@ jobs:
 
   create-manifest:
     needs: build
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     if: github.repository == 'langgenius/dify'
     strategy:
       matrix:

.github/workflows/cli-release.yml

@@ -23,7 +23,7 @@ concurrency:
 jobs:
   validate:
     name: validate manifest + resolve target Dify release
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     if: github.repository == 'langgenius/dify'
     permissions:
       contents: read
@@ -87,7 +87,7 @@ jobs:
   release:
     name: build + attach standalone binaries (all targets)
     needs: validate
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     permissions:
       contents: write
     defaults:

.github/workflows/db-migration-test.yml

@@ -9,7 +9,7 @@ concurrency:
 
 jobs:
   db-migration-test-postgres:
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
 
     steps:
       - name: Checkout code
@@ -59,7 +59,7 @@ jobs:
         run: uv run --directory api flask upgrade-db
 
   db-migration-test-mysql:
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
 
     steps:
       - name: Checkout code

.github/workflows/deploy-agent.yml

@@ -13,7 +13,7 @@ on:
 
 jobs:
   deploy:
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     if: |
       github.event.workflow_run.conclusion == 'success' &&
       github.event.workflow_run.head_branch == 'deploy/agent'

.github/workflows/deploy-dev.yml

@@ -10,7 +10,7 @@ on:
 
 jobs:
   deploy:
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     if: |
       github.event.workflow_run.conclusion == 'success' &&
       github.event.workflow_run.head_branch == 'deploy/dev'

.github/workflows/deploy-enterprise.yml

@@ -13,7 +13,7 @@ on:
 
 jobs:
   deploy:
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     if: |
       github.event.workflow_run.conclusion == 'success' &&
       github.event.workflow_run.head_branch == 'deploy/enterprise'

.github/workflows/deploy-saas.yml

@@ -13,7 +13,7 @@ on:
 
 jobs:
   deploy:
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     if: |
       github.event.workflow_run.conclusion == 'success' &&
       github.event.workflow_run.head_branch == 'deploy/saas'

.github/workflows/hotfix-cherry-pick.yml

@@ -22,7 +22,7 @@ concurrency:
 jobs:
   check-cherry-pick-provenance:
     name: Require cherry-pick provenance
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:

.github/workflows/knowledge-fs-ci.yml

@@ -0,0 +1,504 @@
+name: KnowledgeFS CI
+
+on:
+  pull_request:
+    branches: ["main"]
+  merge_group:
+    branches: ["main"]
+    types: [checks_requested]
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: read
+
+concurrency:
+  group: knowledge-fs-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  CI: true
+  DIFY_KNOWLEDGE_FS_API_IMAGE_NAME: >-
+    ${{ vars.DIFY_KNOWLEDGE_FS_API_IMAGE_NAME || 'langgenius/dify-knowledge-fs-api' }}
+
+jobs:
+  check-changes:
+    name: Check KnowledgeFS changes
+    runs-on: depot-ubuntu-24.04-4
+    outputs:
+      knowledge-fs: ${{ steps.changes.outputs.knowledge-fs }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Detect KnowledgeFS changes
+        id: changes
+        uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
+        with:
+          filters: |
+            knowledge-fs:
+              - 'knowledge-fs/**'
+              - 'knowledge-fs/packages/api/src/dify-capability-v2.ts'
+              - 'knowledge-fs/packages/api/src/knowledge-space-routes.ts'
+              - 'knowledge-fs/packages/api/src/upload-session-routes.ts'
+              - 'knowledge-fs/scripts/export-capability-v2-operations.mjs'
+              - 'knowledge-fs/scripts/export-openapi.mjs'
+              - 'api/dev/generate_knowledge_fs_contract.py'
+              - 'api/dev/knowledge_fs_product_contract.py'
+              - 'api/knowledge-fs-contract.lock.json'
+              - 'api/knowledge-fs-product-operation-gaps.json'
+              - 'api/knowledge-fs-product-operations.json'
+              - 'api/**/knowledge_fs/**'
+              - 'api/**/*knowledge_fs*'
+              - 'api/**/*knowledge-fs*'
+              - 'api/.env.example'
+              - 'api/app_factory.py'
+              - 'api/commands/__init__.py'
+              - 'api/controllers/console/__init__.py'
+              - 'api/controllers/console/workspace/rbac.py'
+              - 'api/controllers/service_api/__init__.py'
+              - 'api/core/agent/base_agent_runner.py'
+              - 'api/core/app/apps/agent_app/runtime_request_builder.py'
+              - 'api/core/rbac/entities.py'
+              - 'api/core/tools/__base/tool_runtime.py'
+              - 'api/core/tools/builtin_tool/_position.yaml'
+              - 'api/core/workflow/node_runtime.py'
+              - 'api/core/workflow/nodes/agent_v2/runtime_request_builder.py'
+              - 'api/extensions/ext_celery.py'
+              - 'api/extensions/ext_commands.py'
+              - 'api/models/__init__.py'
+              - 'api/services/account_service.py'
+              - 'api/services/agent_tool_inner_service.py'
+              - 'api/services/enterprise/rbac_service.py'
+              - 'api/services/entities/agent_tool_inner.py'
+              - 'api/services/knowledge_fs/**'
+              - 'api/services/knowledge_fs_capability.py'
+              - 'api/tests/unit_tests/dev/test_generate_knowledge_fs_contract.py'
+              - 'api/tests/unit_tests/controllers/console/workspace/test_rbac.py'
+              - 'api/tests/unit_tests/core/agent/test_base_agent_runner.py'
+              - 'api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.py'
+              - 'api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.py'
+              - 'api/tests/unit_tests/core/workflow/nodes/tool/test_tool_node_runtime.py'
+              - 'api/tests/unit_tests/core/workflow/test_node_runtime.py'
+              - 'api/tests/unit_tests/services/enterprise/test_rbac_service.py'
+              - 'api/tests/unit_tests/services/test_account_service.py'
+              - 'api/tests/unit_tests/services/test_agent_tool_inner_service.py'
+              - 'api/tests/unit_tests/services/test_knowledge_fs_capability.py'
+              - 'api/tests/unit_tests/services/test_knowledge_fs_product_operations.py'
+              - 'api/pyproject.toml'
+              - 'api/uv.lock'
+              - 'dify-agent/src/dify_agent/layers/dify_core_tools/client.py'
+              - 'dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_client.py'
+              - 'packages/contracts/generated/api/console/**'
+              - 'packages/contracts/generated/api/service/**'
+              - 'docker/.env.example'
+              - 'docker/README.md'
+              - 'docker/dify-env-sync.py'
+              - 'docker/dify-env-sync.sh'
+              - 'docker/docker-compose-template.yaml'
+              - 'docker/docker-compose.yaml'
+              - 'docker/envs/core-services/api.env.example'
+              - 'docker/envs/core-services/knowledge-fs.env.example'
+              - 'docker/generate_docker_compose'
+              - 'docs/design/knowledge-fs*'
+              - '.github/dependabot.yml'
+              - '.github/workflows/knowledge-fs-ci.yml'
+
+  build:
+    name: Build KnowledgeFS API production image
+    needs: check-changes
+    if: needs.check-changes.outputs.knowledge-fs == 'true' || github.event_name == 'workflow_dispatch'
+    runs-on: depot-ubuntu-24.04-4
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+
+      - name: Login to Docker Hub
+        if: github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/main')
+        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
+        with:
+          username: ${{ secrets.DOCKERHUB_USER }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract KnowledgeFS image metadata
+        id: meta
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
+        with:
+          images: ${{ env.DIFY_KNOWLEDGE_FS_API_IMAGE_NAME }}
+          tags: |
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+            type=ref,event=branch
+            type=sha,format=long
+
+      - name: Build KnowledgeFS API image
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        with:
+          context: ./knowledge-fs
+          file: ./knowledge-fs/apps/api/Dockerfile
+          labels: ${{ steps.meta.outputs.labels }}
+          platforms: linux/amd64
+          push: ${{ github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/main') }}
+          tags: ${{ steps.meta.outputs.tags }}
+
+  quality:
+    name: Run KnowledgeFS quality and contract gates
+    needs: check-changes
+    if: needs.check-changes.outputs.knowledge-fs == 'true' || github.event_name == 'workflow_dispatch'
+    runs-on: depot-ubuntu-24.04-4
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./knowledge-fs
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+        with:
+          package_json_file: knowledge-fs/package.json
+          run_install: false
+
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: knowledge-fs/pnpm-lock.yaml
+
+      - name: Install KnowledgeFS dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Scan KnowledgeFS secrets
+        run: pnpm security:secrets
+
+      - name: Audit KnowledgeFS production dependencies
+        run: pnpm security:dependencies
+
+      - name: Run KnowledgeFS checks
+        run: pnpm check
+
+      - name: Build KnowledgeFS
+        run: pnpm build
+
+      - name: Lint KnowledgeFS
+        run: pnpm lint
+
+      - name: Setup UV and Python
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          enable-cache: true
+          python-version: "3.12"
+          cache-dependency-glob: |
+            api/uv.lock
+            dify-agent/uv.lock
+
+      - name: Verify Dify dependency lock
+        working-directory: .
+        run: uv lock --project api --check
+
+      - name: Install Dify contract dependencies
+        working-directory: .
+        run: uv sync --project api --locked --dev
+
+      - name: Collect Dify KnowledgeFS gate targets
+        working-directory: .
+        run: |
+          set -euo pipefail
+
+          target_dir="${RUNNER_TEMP:?}/knowledge-fs-ci-targets"
+          mkdir -p "$target_dir"
+
+          production_targets=()
+          add_production_target() {
+            local path="$1"
+            if [[ ! -f "$path" ]]; then
+              echo "required Dify KnowledgeFS production target is missing: $path" >&2
+              exit 1
+            fi
+            production_targets+=("$path")
+          }
+
+          while IFS= read -r -d '' path; do
+            if [[ "$path" == *knowledge_fs* ]]; then
+              add_production_target "$path"
+            fi
+          done < <(
+            find api \
+              \( -path 'api/.venv' -o -path 'api/tests' -o -path 'api/storage' \) -prune \
+              -o -type f -name '*.py' -print0
+          )
+
+          production_touchpoints=(
+            api/app_factory.py
+            api/commands/__init__.py
+            api/controllers/console/__init__.py
+            api/controllers/console/workspace/rbac.py
+            api/controllers/service_api/__init__.py
+            api/core/agent/base_agent_runner.py
+            api/core/app/apps/agent_app/runtime_request_builder.py
+            api/core/rbac/entities.py
+            api/core/tools/__base/tool_runtime.py
+            api/core/workflow/node_runtime.py
+            api/core/workflow/nodes/agent_v2/runtime_request_builder.py
+            api/extensions/ext_celery.py
+            api/extensions/ext_commands.py
+            api/models/__init__.py
+            api/services/account_service.py
+            api/services/agent_tool_inner_service.py
+            api/services/enterprise/rbac_service.py
+            api/services/entities/agent_tool_inner.py
+          )
+          for path in "${production_touchpoints[@]}"; do
+            add_production_target "$path"
+          done
+          printf '%s\0' "${production_touchpoints[@]}" > "$target_dir/glue-files"
+
+          if ((${#production_targets[@]} == 0)); then
+            echo "Dify KnowledgeFS production target set is empty" >&2
+            exit 1
+          fi
+          printf '%s\0' "${production_targets[@]}" > "$target_dir/production-files"
+
+          test_targets=()
+          add_test_target() {
+            local path="$1"
+            if [[ ! -f "$path" ]]; then
+              echo "required Dify KnowledgeFS unit test is missing: $path" >&2
+              exit 1
+            fi
+            test_targets+=("$path")
+          }
+
+          while IFS= read -r -d '' path; do
+            if [[ "$path" == *knowledge_fs* ]]; then
+              add_test_target "$path"
+            fi
+          done < <(find api/tests/unit_tests -type f -name '*.py' -print0)
+
+          test_touchpoints=(
+            api/tests/unit_tests/controllers/console/workspace/test_rbac.py
+            api/tests/unit_tests/core/agent/test_base_agent_runner.py
+            api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.py
+            api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.py
+            api/tests/unit_tests/core/workflow/nodes/tool/test_tool_node_runtime.py
+            api/tests/unit_tests/core/workflow/test_node_runtime.py
+            api/tests/unit_tests/services/enterprise/test_rbac_service.py
+            api/tests/unit_tests/services/test_account_service.py
+            api/tests/unit_tests/services/test_agent_tool_inner_service.py
+          )
+          for path in "${test_touchpoints[@]}"; do
+            add_test_target "$path"
+          done
+
+          required_test_scopes=(
+            /commands/
+            /configs/
+            /controllers/
+            /core/agent/
+            /core/app/apps/agent_app/
+            /core/tools/builtin_tool/providers/knowledge_fs/
+            /core/workflow/
+            /dev/
+            /extensions/
+            /migrations/
+            /models/
+            /repositories/
+            /services/
+            /tasks/
+          )
+          for required_scope in "${required_test_scopes[@]}"; do
+            scope_found=false
+            for path in "${test_targets[@]}"; do
+              if [[ "$path" == *"$required_scope"* ]]; then
+                scope_found=true
+                break
+              fi
+            done
+            if [[ "$scope_found" != true ]]; then
+              echo "required Dify KnowledgeFS test scope is empty: $required_scope" >&2
+              exit 1
+            fi
+          done
+
+          if ((${#test_targets[@]} == 0)); then
+            echo "Dify KnowledgeFS unit test target set is empty" >&2
+            exit 1
+          fi
+          printf '%s\0' "${test_targets[@]}" > "$target_dir/unit-test-files"
+
+      - name: Lint Dify KnowledgeFS integration
+        working-directory: .
+        run: |
+          set -euo pipefail
+          targets=()
+          while IFS= read -r -d '' path; do
+            targets+=("$path")
+          done < "${RUNNER_TEMP:?}/knowledge-fs-ci-targets/production-files"
+          if ((${#targets[@]} == 0)); then
+            echo "Dify KnowledgeFS production target manifest is empty" >&2
+            exit 1
+          fi
+          uv run --project api --dev ruff format --check "${targets[@]}"
+          uv run --project api --dev ruff check "${targets[@]}"
+
+      - name: Type-check Dify KnowledgeFS integration
+        working-directory: .
+        run: |
+          set -euo pipefail
+          targets=()
+          while IFS= read -r -d '' path; do
+            targets+=("$path")
+          done < "${RUNNER_TEMP:?}/knowledge-fs-ci-targets/production-files"
+          if ((${#targets[@]} == 0)); then
+            echo "Dify KnowledgeFS production target manifest is empty" >&2
+            exit 1
+          fi
+          PYREFLY_OUTPUT_FORMAT=github ./dev/pyrefly-check-local "${targets[@]}"
+
+          mypy_targets=()
+          for path in "${targets[@]}"; do
+            if [[ "$path" != api/migrations/* ]]; then
+              mypy_targets+=("${path#api/}")
+            fi
+          done
+          if ((${#mypy_targets[@]} == 0)); then
+            echo "Dify KnowledgeFS Mypy target set is empty" >&2
+            exit 1
+          fi
+          uv run --directory api --dev mypy \
+            --explicit-package-bases \
+            --exclude-gitignore \
+            --exclude '(^|/)conftest\.py$' \
+            --exclude 'tests/' \
+            --exclude 'migrations/' \
+            --check-untyped-defs \
+            --disable-error-code=import-untyped \
+            "${mypy_targets[@]}"
+
+      - name: Test Dify KnowledgeFS unit surface
+        working-directory: .
+        env:
+          COVERAGE_FILE: ${{ runner.temp }}/dify-knowledge-fs.coverage
+        run: |
+          set -euo pipefail
+          targets=()
+          while IFS= read -r -d '' path; do
+            targets+=("$path")
+          done < "${RUNNER_TEMP:?}/knowledge-fs-ci-targets/unit-test-files"
+          if ((${#targets[@]} == 0)); then
+            echo "Dify KnowledgeFS unit test target manifest is empty" >&2
+            exit 1
+          fi
+          uv run --project api --dev coverage run --branch --source=api -m pytest "${targets[@]}" --no-cov -q
+
+      - name: Enforce Dify KnowledgeFS focused coverage
+        working-directory: .
+        env:
+          COVERAGE_FILE: ${{ runner.temp }}/dify-knowledge-fs.coverage
+          KNOWLEDGE_FS_COVERAGE_BASE: >-
+            ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha || github.event.before || '' }}
+        run: |
+          set -euo pipefail
+          report="${RUNNER_TEMP:?}/dify-knowledge-fs-coverage.json"
+          uv run --project api --dev coverage json --show-contexts -o "$report"
+          uv run --project api --dev python api/dev/check_knowledge_fs_coverage.py \
+            --coverage-json "$report" \
+            --glue-manifest "${RUNNER_TEMP:?}/knowledge-fs-ci-targets/glue-files" \
+            --base "$KNOWLEDGE_FS_COVERAGE_BASE" \
+            --minimum 90 \
+            --glue-minimum 90
+
+      - name: Verify Dify KnowledgeFS contract
+        working-directory: .
+        run: uv run --project api python api/dev/generate_knowledge_fs_contract.py --check
+
+      - name: Verify Dify Agent dependency lock
+        working-directory: .
+        run: uv lock --project dify-agent --check
+
+      - name: Install Dify Agent gate dependencies
+        working-directory: .
+        run: uv sync --project dify-agent --locked --dev
+
+      - name: Lint Dify Agent KnowledgeFS integration
+        working-directory: ./dify-agent
+        run: |
+          uv run --project . --dev ruff format --check \
+            src/dify_agent/layers/dify_core_tools/client.py \
+            tests/local/dify_agent/layers/dify_core_tools/test_client.py
+          uv run --project . --dev ruff check \
+            src/dify_agent/layers/dify_core_tools/client.py \
+            tests/local/dify_agent/layers/dify_core_tools/test_client.py
+
+      - name: Type-check Dify Agent KnowledgeFS integration
+        working-directory: ./dify-agent
+        run: >-
+          uv run --project . --dev basedpyright --level error
+          src/dify_agent/layers/dify_core_tools/client.py
+          tests/local/dify_agent/layers/dify_core_tools/test_client.py
+
+      - name: Test Dify Agent KnowledgeFS integration
+        working-directory: ./dify-agent
+        run: >-
+          uv run --project . --dev python -m pytest
+          tests/local/dify_agent/layers/dify_core_tools/test_client.py
+          -q
+
+  skip:
+    name: Skip KnowledgeFS quality and contract gates
+    needs: check-changes
+    if: needs.check-changes.outputs.knowledge-fs != 'true' && github.event_name != 'workflow_dispatch'
+    runs-on: depot-ubuntu-24.04-4
+    steps:
+      - name: Report skipped KnowledgeFS checks
+        run: echo "No KnowledgeFS-related changes detected; skipping KnowledgeFS checks."
+
+  final:
+    name: KnowledgeFS CI
+    if: ${{ always() }}
+    needs:
+      - check-changes
+      - build
+      - quality
+      - skip
+    runs-on: depot-ubuntu-24.04-4
+    steps:
+      - name: Finalize KnowledgeFS CI status
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BUILD_RESULT: ${{ needs.build.result }}
+          KNOWLEDGE_FS_CHANGED: ${{ needs.check-changes.outputs.knowledge-fs }}
+          QUALITY_RESULT: ${{ needs.quality.result }}
+          SKIP_RESULT: ${{ needs.skip.result }}
+        run: |
+          if [[ "$EVENT_NAME" == 'workflow_dispatch' || "$KNOWLEDGE_FS_CHANGED" == 'true' ]]; then
+            if [[ "$BUILD_RESULT" == 'success' && "$QUALITY_RESULT" == 'success' ]]; then
+              echo "KnowledgeFS build and checks ran successfully."
+              exit 0
+            fi
+
+            echo "KnowledgeFS build or checks failed: build=$BUILD_RESULT quality=$QUALITY_RESULT" >&2
+            exit 1
+          fi
+
+          if [[ "$SKIP_RESULT" == 'success' ]]; then
+            echo "KnowledgeFS checks were skipped because no related files changed."
+            exit 0
+          fi
+
+          echo "KnowledgeFS change detection or skip reporting failed with result: $SKIP_RESULT" >&2
+          exit 1

.github/workflows/labeler.yml

@@ -7,7 +7,7 @@ jobs:
     permissions:
       contents: read
       pull-requests: write
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - uses: actions/labeler@b8dd2d9be0f68b860e7dae5dae7d772984eacd6d # v6.2.0
         with:

.github/workflows/main-ci.yml

@@ -21,13 +21,13 @@ concurrency:
 jobs:
   pre_job:
     name: Skip Duplicate Checks
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     outputs:
       should_skip: ${{ steps.skip_check.outputs.should_skip || 'false' }}
     steps:
       - id: skip_check
         continue-on-error: true
-        uses: fkirc/skip-duplicate-actions@f75f66ce1886f00957d99748a42c724f4330bdcf # v5.3.1
+        uses: fkirc/skip-duplicate-actions@b974a9395958c231af965b70070979a577efa578 # v5.3.2
         with:
           cancel_others: 'true'
           concurrent_skipping: same_content_newer
@@ -37,7 +37,7 @@ jobs:
     name: Check Changed Files
     needs: pre_job
     if: needs.pre_job.outputs.should_skip != 'true'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     outputs:
       api-changed: ${{ steps.changes.outputs.api }}
       cli-changed: ${{ steps.changes.outputs.cli }}
@@ -164,7 +164,7 @@ jobs:
       - pre_job
       - check-changes
     if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.api-changed != 'true'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Report skipped API tests
         run: echo "No API-related changes detected; skipping API tests."
@@ -177,7 +177,7 @@ jobs:
       - check-changes
       - api-tests-run
       - api-tests-skip
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Finalize API Tests status
         env:
@@ -224,7 +224,7 @@ jobs:
       - pre_job
       - check-changes
     if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.cli-changed != 'true'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Report skipped CLI tests
         run: echo "No CLI-related changes detected; skipping CLI tests."
@@ -237,7 +237,7 @@ jobs:
       - check-changes
       - cli-tests-run
       - cli-tests-skip
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Finalize CLI Tests status
         env:
@@ -284,7 +284,7 @@ jobs:
       - pre_job
       - check-changes
     if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.web-changed != 'true'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Report skipped web tests
         run: echo "No web-related changes detected; skipping web tests."
@@ -297,7 +297,7 @@ jobs:
       - check-changes
       - web-tests-run
       - web-tests-skip
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Finalize Web Tests status
         env:
@@ -344,7 +344,7 @@ jobs:
       - pre_job
       - check-changes
     if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.e2e-changed != 'true'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Report skipped web full-stack e2e
         run: echo "No E2E-related changes detected; skipping web full-stack E2E."
@@ -357,7 +357,7 @@ jobs:
       - check-changes
       - web-e2e-run
       - web-e2e-skip
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Finalize Web Full-Stack E2E status
         env:
@@ -411,7 +411,7 @@ jobs:
       - pre_job
       - check-changes
     if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.vdb-changed != 'true'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Report skipped VDB tests
         run: echo "No VDB-related changes detected; skipping VDB tests."
@@ -424,7 +424,7 @@ jobs:
       - check-changes
       - vdb-tests-run
       - vdb-tests-skip
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Finalize VDB Tests status
         env:
@@ -470,7 +470,7 @@ jobs:
       - pre_job
       - check-changes
     if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.migration-changed != 'true'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Report skipped DB migration tests
         run: echo "No migration-related changes detected; skipping DB migration tests."
@@ -483,7 +483,7 @@ jobs:
       - check-changes
       - db-migration-test-run
       - db-migration-test-skip
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Finalize DB Migration Test status
         env:
@@ -530,7 +530,7 @@ jobs:
       - pre_job
       - check-changes
     if: needs.pre_job.outputs.should_skip != 'true' && needs.check-changes.outputs.sandbox-runtime-changed != 'true'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Report skipped sandbox runtime tests
         run: echo "No sandbox-runtime-related changes detected; skipping sandbox runtime tests."
@@ -543,7 +543,7 @@ jobs:
       - check-changes
       - sandbox-runtime-tests-run
       - sandbox-runtime-tests-skip
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Finalize Sandbox Runtime Tests status
         env:

.github/workflows/post-merge.yml

@@ -14,7 +14,7 @@ concurrency:
 jobs:
   check-changes:
     name: Check Changed Files
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     outputs:
       external-e2e-changed: ${{ steps.changes.outputs.external_e2e }}
     steps:

.github/workflows/pyrefly-diff-comment.yml

@@ -12,7 +12,7 @@ permissions: {}
 jobs:
   comment:
     name: Comment PR with pyrefly diff
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     permissions:
       actions: read
       contents: read

.github/workflows/pyrefly-diff.yml

@@ -10,7 +10,7 @@ permissions:
 
 jobs:
   pyrefly-diff:
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     permissions:
       contents: read
       issues: write

.github/workflows/pyrefly-type-coverage-comment.yml

@@ -12,7 +12,7 @@ permissions: {}
 jobs:
   comment:
     name: Comment PR with type coverage
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     permissions:
       actions: read
       contents: read

.github/workflows/pyrefly-type-coverage.yml

@@ -10,7 +10,7 @@ permissions:
 
 jobs:
   pyrefly-type-coverage:
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     permissions:
       contents: read
       issues: write

.github/workflows/sandbox-runtime-tests.yml

@@ -13,7 +13,7 @@ concurrency:
 jobs:
   sandbox-runtime-unit:
     name: Sandbox Runtime Unit Tests
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     defaults:
       run:
         shell: bash
@@ -27,7 +27,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup Go
-        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: dify-agent-runtime/go.mod
           cache-dependency-path: dify-agent-runtime/go.sum
@@ -37,7 +37,7 @@ jobs:
 
   sandbox-runtime-lint:
     name: Sandbox Runtime Lint
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     defaults:
       run:
         shell: bash
@@ -51,20 +51,20 @@ jobs:
           persist-credentials: false
 
       - name: Setup Go
-        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: dify-agent-runtime/go.mod
           cache-dependency-path: dify-agent-runtime/go.sum
 
       - name: Run golangci-lint
-        uses: golangci/golangci-lint-action@4afd733a84b1f43292c63897423277bb7f4313a9 # v6.5.0
+        uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v6.5.0
         with:
           working-directory: dify-agent-runtime
           version: latest
 
   sandbox-runtime-integration:
     name: Sandbox Runtime Integration Tests
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     defaults:
       run:
         shell: bash
@@ -78,7 +78,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup Go
-        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: dify-agent-runtime/go.mod
           cache-dependency-path: dify-agent-runtime/go.sum

.github/workflows/semantic-pull-request.yml

@@ -16,7 +16,7 @@ jobs:
     name: Validate PR title
     permissions:
       pull-requests: read
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     steps:
       - name: Complete merge group check
         if: github.event_name == 'merge_group'

.github/workflows/stale.yml

@@ -12,7 +12,7 @@ on:
 jobs:
   stale:
 
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     permissions:
       issues: write
       pull-requests: write

.github/workflows/style.yml

@@ -19,7 +19,7 @@ permissions:
 jobs:
   python-style:
     name: Python Style
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
 
     steps:
       - name: Checkout code
@@ -83,7 +83,7 @@ jobs:
 
   web-style:
     name: Web Style
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     defaults:
       run:
         working-directory: ./web
@@ -182,7 +182,7 @@ jobs:
 
   superlinter:
     name: SuperLinter
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
 
     steps:
       - name: Checkout code

.github/workflows/tool-test-sdks.yaml

@@ -17,7 +17,7 @@ concurrency:
 jobs:
   build:
     name: unit test for Node.js SDK
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
 
     defaults:
       run:
@@ -29,7 +29,7 @@ jobs:
           persist-credentials: false
 
       - name: Use Node.js
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 22
           cache: ''

.github/workflows/translate-i18n-claude.yml

@@ -35,7 +35,7 @@ concurrency:
 jobs:
   translate:
     if: github.repository == 'langgenius/dify'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     timeout-minutes: 120
 
     steps:
@@ -158,7 +158,7 @@ jobs:
 
       - name: Run Claude Code for Translation Sync
         if: steps.context.outputs.CHANGED_FILES != ''
-        uses: anthropics/claude-code-action@e90deca47693f9457b72f2b53c17d7c445a87342 # v1.0.171
+        uses: anthropics/claude-code-action@af0559ee4f514d1ef21826982bed13f7edc3c35e # v1.0.178
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/trigger-i18n-sync.yml

@@ -16,7 +16,7 @@ concurrency:
 jobs:
   trigger:
     if: github.repository == 'langgenius/dify'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     timeout-minutes: 5
 
     steps:

.github/workflows/vdb-tests-full.yml

@@ -16,7 +16,7 @@ jobs:
   test:
     name: Full VDB Tests
     if: github.repository == 'langgenius/dify'
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     strategy:
       matrix:
         python-version:

.github/workflows/vdb-tests.yml

@@ -13,7 +13,7 @@ concurrency:
 jobs:
   test:
     name: VDB Smoke Tests
-    runs-on: depot-ubuntu-24.04
+    runs-on: depot-ubuntu-24.04-4
     strategy:
       matrix:
         python-version:

.gitignore

@@ -30,6 +30,11 @@ share/python-wheels/
 *.egg
 MANIFEST
 
+# KnowledgeFS is an independently rooted TypeScript workspace. Its admin `lib`
+# directory contains source files rather than Python build output.
+!/knowledge-fs/apps/admin/lib/
+!/knowledge-fs/apps/admin/lib/**
+
 # PyInstaller
 #  Usually these files are written by a python script from a template
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.

.vscode/launch.json.template

@@ -5,7 +5,9 @@
             "name": "Python: API (gevent)",
             "type": "debugpy",
             "request": "launch",
-            "program": "${workspaceFolder}/api/app.py",
+            "module": "gevent.monkey",
+            "args": ["--module", "app"],
+            "gevent": true,
             "jinja": true,
             "justMyCode": true,
             "cwd": "${workspaceFolder}/api",
@@ -33,22 +35,6 @@
             "justMyCode": false,
             "cwd": "${workspaceFolder}/api",
             "python": "${workspaceFolder}/api/.venv/bin/python"
-        },
-        {
-            "name": "Next.js: debug full stack",
-            "type": "node",
-            "request": "launch",
-            "program": "${workspaceFolder}/web/node_modules/next/dist/bin/next",
-            "runtimeArgs": ["--inspect"],
-            "skipFiles": ["<node_internals>/**"],
-            "serverReadyAction": {
-              "action": "debugWithChrome",
-              "killOnServerStop": true,
-              "pattern": "- Local:.+(https?://.+)",
-              "uriFormat": "%s",
-              "webRoot": "${workspaceFolder}/web"
-            },
-            "cwd": "${workspaceFolder}/web"
-          }
+        }
     ]
 }

api/.env.example

@@ -561,6 +561,8 @@ WORKFLOW_MAX_EXECUTION_STEPS=500
 WORKFLOW_MAX_EXECUTION_TIME=1200
 WORKFLOW_CALL_MAX_DEPTH=5
 MAX_VARIABLE_SIZE=204800
+# Maximum concurrent node-builder LLM calls per workflow generation request
+WORKFLOW_GENERATOR_NODE_BUILDER_MAX_WORKERS=6
 
 # GraphEngine Worker Pool Configuration
 # Minimum number of workers per GraphEngine instance (default: 1)
@@ -665,10 +667,44 @@ PLUGIN_REMOTE_INSTALL_HOST=localhost
 PLUGIN_MAX_PACKAGE_SIZE=15728640
 PLUGIN_MODEL_SCHEMA_CACHE_TTL=3600
 PLUGIN_MODEL_PROVIDERS_CACHE_TTL=86400
+# Comma-separated marketplace plugin IDs whose latest versions are installed for newly registered users.
+# Example: langgenius/openai,langgenius/gemini
+NEW_USER_DEFAULT_PLUGIN_IDS=
+# Comma-separated model_type:provider:model entries assigned after default plugins finish installing.
+# Example: llm:langgenius/openai/openai:gpt-4o-mini,text-embedding:langgenius/openai/openai:text-embedding-3-small
+NEW_USER_DEFAULT_MODELS=
 INNER_API_KEY_FOR_PLUGIN=QaHbTe77CtuXmsfyhR7+vRjI/+XbV1AaFy691iy+kGDv2Jvy0/eAh8Y1
 
 # Dify Agent backend
 AGENT_BACKEND_BASE_URL=http://localhost:5050
+AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS=30
+AGENT_BACKEND_STREAM_MAX_RECONNECTS=3
+AGENT_BACKEND_RUN_TIMEOUT_SECONDS=1200
+
+# KnowledgeFS (Dataset 2.0)
+KNOWLEDGE_FS_ENABLED=false
+# Production deployments require HTTPS; plain HTTP is limited to non-production or loopback.
+KNOWLEDGE_FS_BASE_URL=
+KNOWLEDGE_FS_DIRECT_ORIGIN=
+KNOWLEDGE_FS_LIFECYCLE_WORKER_ENABLED=false
+KNOWLEDGE_FS_INTEGRATED_PROVISION_READY=false
+KNOWLEDGE_FS_LEGACY_ACL_FREEZE_READY=false
+KNOWLEDGE_FS_LIFECYCLE_POLL_INTERVAL_SECONDS=15
+KNOWLEDGE_FS_LIFECYCLE_LEASE_SECONDS=60
+KNOWLEDGE_FS_LIFECYCLE_BATCH_SIZE=25
+# Legacy rollback-only HMAC; Capability v2 deployments leave this blank.
+KNOWLEDGE_FS_JWT_SECRET=
+KNOWLEDGE_FS_CAPABILITY_V2_ENABLED=false
+KNOWLEDGE_FS_CAPABILITY_V2_SIGNING_KID=
+KNOWLEDGE_FS_CAPABILITY_V2_PRIVATE_KEY_PEM=
+KNOWLEDGE_FS_CAPABILITY_V2_PREVIOUS_PUBLIC_JWKS=
+KNOWLEDGE_FS_CAPABILITY_V2_ISSUER=dify-control-plane
+KNOWLEDGE_FS_CAPABILITY_V2_AUDIENCE=knowledge-fs
+KNOWLEDGE_FS_CAPABILITY_V2_MAX_TTL_SECONDS=60
+KNOWLEDGE_FS_SSE_READ_TIMEOUT_SECONDS=300
+KNOWLEDGE_FS_TIMEOUT_SECONDS=10
+KNOWLEDGE_FS_JWKS_CACHE_MAX_AGE_SECONDS=300
+KNOWLEDGE_FS_PRODUCT_MAX_RESPONSE_BYTES=4194304
 
 # Marketplace configuration
 MARKETPLACE_ENABLED=true

api/app.py

@@ -1,5 +1,24 @@
 from __future__ import annotations
 
+# ``python -m app`` (docker DEBUG=true, or IDE debugging) serves through the
+# gevent pywsgi server at the bottom of this file, so the stdlib must be
+# monkey-patched BEFORE any other import pulls in sockets or locks. Without
+# this, every request runs as a greenlet on one OS thread while blocking
+# calls (LLM invokes, ``Future.result`` waits, DB I/O) pin that thread — the
+# whole process freezes until the call returns. Gunicorn and Celery apply
+# their own patching (see gunicorn.conf.py / celery_entrypoint.py), and
+# ``flask run`` uses real Werkzeug threads, so both skip this branch.
+if __name__ == "__main__":
+    from gevent import monkey
+
+    monkey.patch_all()
+
+    import psycogreen.gevent as psycogreen_gevent
+    from grpc.experimental import gevent as grpc_gevent
+
+    grpc_gevent.init_gevent()
+    psycogreen_gevent.patch_psycopg()
+
 import logging
 import sys
 from typing import TYPE_CHECKING, cast

api/app_factory.py

@@ -154,6 +154,7 @@ def initialize_extensions(app: DifyApp):
         ext_forward_refs,
         ext_hosting_provider,
         ext_import_modules,
+        ext_knowledge_fs_observability,
         ext_logging,
         ext_login,
         ext_logstore,
@@ -204,6 +205,7 @@ def initialize_extensions(app: DifyApp):
         ext_enterprise_telemetry,
         ext_request_logging,
         ext_session_factory,
+        ext_knowledge_fs_observability,
         ext_oauth_bearer,
     ]
     for ext in extensions:

api/clients/agent_backend/client.py

@@ -8,7 +8,7 @@ creating another wire contract.
 
 from __future__ import annotations
 
-from collections.abc import Iterator
+from collections.abc import Callable, Iterator
 from typing import Protocol
 
 from dify_agent.client import (
@@ -45,7 +45,13 @@ class AgentBackendRunClient(Protocol):
     def cancel_run(self, run_id: str, request: CancelRunRequest | None = None) -> CancelRunResponse:
         """Request explicit cancellation for one Agent backend run."""
 
-    def stream_events(self, run_id: str, *, after: str | None = None) -> Iterator[RunEvent]:
+    def stream_events(
+        self,
+        run_id: str,
+        *,
+        after: str | None = None,
+        should_stop: Callable[[], bool] | None = None,
+    ) -> Iterator[RunEvent]:
         """Yield public ``dify-agent`` run events in stream order."""
 
     def wait_run(self, run_id: str, *, timeout_seconds: float | None = None) -> RunStatusResponse:
@@ -61,7 +67,15 @@ class _DifyAgentSyncClient(Protocol):
     def cancel_run_sync(self, run_id: str, request: CancelRunRequest | None = None) -> CancelRunResponse:
         """Cancel one run synchronously."""
 
-    def stream_events_sync(self, run_id: str, *, after: str | None = None) -> Iterator[RunEvent]:
+    def stream_events_sync(
+        self,
+        run_id: str,
+        *,
+        after: str | None = None,
+        max_reconnects: int | None = None,
+        timeout_seconds: float | None = None,
+        should_stop: Callable[[], bool] | None = None,
+    ) -> Iterator[RunEvent]:
         """Stream run events synchronously."""
 
     def wait_run_sync(self, run_id: str, *, timeout_seconds: float | None = None) -> RunStatusResponse:
@@ -73,8 +87,16 @@ class DifyAgentBackendRunClient:
 
     client: _DifyAgentSyncClient
 
-    def __init__(self, client: _DifyAgentSyncClient) -> None:
+    def __init__(
+        self,
+        client: _DifyAgentSyncClient,
+        *,
+        stream_max_reconnects: int = 3,
+        stream_timeout_seconds: float = 1200,
+    ) -> None:
         self.client = client
+        self._stream_max_reconnects = stream_max_reconnects
+        self._stream_timeout_seconds = stream_timeout_seconds
 
     def create_run(self, request: CreateRunRequest) -> CreateRunResponse:
         """Create one run through ``POST /runs`` and normalize client exceptions."""
@@ -90,10 +112,22 @@ class DifyAgentBackendRunClient:
         except Exception as exc:
             raise _normalize_dify_agent_error(exc) from exc
 
-    def stream_events(self, run_id: str, *, after: str | None = None) -> Iterator[RunEvent]:
+    def stream_events(
+        self,
+        run_id: str,
+        *,
+        after: str | None = None,
+        should_stop: Callable[[], bool] | None = None,
+    ) -> Iterator[RunEvent]:
         """Stream run events from ``/events/sse`` with the wrapped client's reconnect policy."""
         try:
-            yield from self.client.stream_events_sync(run_id, after=after)
+            yield from self.client.stream_events_sync(
+                run_id,
+                after=after,
+                max_reconnects=self._stream_max_reconnects,
+                timeout_seconds=self._stream_timeout_seconds,
+                should_stop=should_stop,
+            )
         except Exception as exc:
             raise _normalize_dify_agent_error(exc) from exc
 

api/clients/agent_backend/factory.py

@@ -13,10 +13,17 @@ def create_agent_backend_run_client(
     base_url: str | None = None,
     use_fake: bool = False,
     fake_scenario: str | FakeAgentBackendScenario = FakeAgentBackendScenario.SUCCESS,
+    stream_read_timeout_seconds: float = 30,
+    stream_max_reconnects: int = 3,
+    stream_run_timeout_seconds: float = 1200,
 ) -> AgentBackendRunClient:
     """Create the API-side run client without hiding the ``dify-agent`` protocol."""
     if use_fake:
         return FakeAgentBackendRunClient(scenario=FakeAgentBackendScenario(fake_scenario))
     if base_url is None:
         raise ValueError("base_url is required when creating a real Agent backend client")
-    return DifyAgentBackendRunClient(Client(base_url=base_url))
+    return DifyAgentBackendRunClient(
+        Client(base_url=base_url, stream_timeout=stream_read_timeout_seconds),
+        stream_max_reconnects=stream_max_reconnects,
+        stream_timeout_seconds=stream_run_timeout_seconds,
+    )

api/clients/agent_backend/fake_client.py

@@ -7,7 +7,7 @@ separate ``agent-backend.v1`` event stream.
 
 from __future__ import annotations
 
-from collections.abc import Iterator
+from collections.abc import Callable, Iterator
 from datetime import UTC, datetime
 from enum import StrEnum
 
@@ -69,9 +69,17 @@ class FakeAgentBackendRunClient:
         del request
         return CancelRunResponse(run_id=run_id, status="cancelled")
 
-    def stream_events(self, run_id: str, *, after: str | None = None) -> Iterator[RunEvent]:
+    def stream_events(
+        self,
+        run_id: str,
+        *,
+        after: str | None = None,
+        should_stop: Callable[[], bool] | None = None,
+    ) -> Iterator[RunEvent]:
         """Yield the deterministic public ``RunEvent`` sequence for ``run_id``."""
         for event in self._events(run_id):
+            if should_stop is not None and should_stop():
+                return
             if after is not None and event.id is not None and event.id <= after:
                 continue
             yield event

api/commands/__init__.py

@@ -10,6 +10,7 @@ from .data_migration import (
     import_migration_data,
     migration_data_wizard,
 )
+from .knowledge_fs import knowledge_fs_control_space
 from .plugin import (
     backfill_plugin_auto_upgrade,
     extract_plugins,
@@ -75,6 +76,7 @@ __all__ = [
     "import_migration_data",
     "install_plugins",
     "install_rag_pipeline_plugins",
+    "knowledge_fs_control_space",
     "legacy_model_types",
     "migrate_annotation_vector_database",
     "migrate_data_for_plugin",

api/commands/knowledge_fs.py

@@ -0,0 +1,604 @@
+"""Operator commands for the independent KnowledgeFS control-plane."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from datetime import datetime
+from functools import partial
+from pathlib import Path
+
+import click
+from pydantic import BaseModel, ValidationError
+
+from core.db.session_factory import session_factory
+from services.knowledge_fs.cleanup import (
+    CleanupApprovalInput,
+    CleanupCompletionEvidenceInput,
+    CleanupReadinessEvidenceInput,
+    CleanupStartInput,
+    KnowledgeFSCleanupError,
+    KnowledgeFSCleanupService,
+)
+from services.knowledge_fs.control_space_commands import KnowledgeFSControlSpaceCommandService
+from services.knowledge_fs.control_space_lifecycle import KnowledgeFSControlSpaceLifecycleError
+from services.knowledge_fs.control_space_management import (
+    KnowledgeFSControlSpaceManagementService,
+    KnowledgeFSControlSpaceRegistration,
+)
+from services.knowledge_fs.cutover import (
+    CutoverSmokeResultsInput,
+    FinalDeltaInput,
+    KnowledgeFSCutoverError,
+    KnowledgeFSWorkspaceCutoverService,
+    LegacyDependencyInput,
+    QuarantineResolutionInput,
+    ShadowAuthorizationObservationInput,
+    ShadowCompletionInput,
+    WorkspaceInventoryInput,
+)
+from services.knowledge_fs.orphan_reconciler import KnowledgeFSOrphanReconciler
+from services.knowledge_fs.remote_registry import get_knowledge_fs_lifecycle_remote
+
+
+@click.group("knowledge-fs-control-space")
+def knowledge_fs_control_space() -> None:
+    """Inspect and repair Dify-owned KnowledgeFS control-space state."""
+
+
+@knowledge_fs_control_space.command("dry-run")
+@click.option("--tenant-id", default=None)
+def dry_run(tenant_id: str | None) -> None:
+    report = _management_service().dry_run(tenant_id=tenant_id)
+    click.echo(json.dumps(report._asdict(), sort_keys=True))
+
+
+@knowledge_fs_control_space.command("inventory")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Create ledgers; omitted means read-only inventory.")
+def inventory(input_path: Path, apply: bool) -> None:
+    """Validate strict Workspace inventory JSONL and optionally create ledgers."""
+
+    service = _cutover_service()
+    for payload in _read_jsonl(input_path, WorkspaceInventoryInput):
+        report = _operator_call(partial(service.inventory, payload, apply=apply))
+        _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("register")
+@click.option("--tenant-id", required=True)
+@click.option("--owner-account-id", required=True)
+@click.option("--provisioning-key", required=True)
+@click.option("--knowledge-space-id", required=True)
+@click.option("--knowledge-space-revision", type=click.IntRange(min=0), required=True)
+def register(
+    tenant_id: str,
+    owner_account_id: str,
+    provisioning_key: str,
+    knowledge_space_id: str,
+    knowledge_space_revision: int,
+) -> None:
+    control_space, replayed = _management_service().register(
+        KnowledgeFSControlSpaceRegistration(
+            tenant_id,
+            owner_account_id,
+            provisioning_key,
+            knowledge_space_id,
+            knowledge_space_revision,
+        )
+    )
+    click.echo(json.dumps({"control_space_id": control_space.id, "replayed": replayed}, sort_keys=True))
+
+
+@knowledge_fs_control_space.command("backfill")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist registrations; omitted means dry-run.")
+def backfill(input_path: Path, apply: bool) -> None:
+    """Backfill strict Workspace inventory JSONL; dry-run unless --apply is explicit."""
+
+    service = _cutover_service()
+    for payload in _read_jsonl(input_path, WorkspaceInventoryInput):
+        report = _operator_call(partial(service.backfill, payload, apply=apply))
+        _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("quarantine-resolve")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist resolutions; omitted means dry-run.")
+def quarantine_resolve(input_path: Path, apply: bool) -> None:
+    """Resolve strict tenant-scoped quarantine JSONL with immutable operator evidence."""
+
+    service = _cutover_service()
+    for payload in _read_jsonl(input_path, QuarantineResolutionInput):
+        report = _operator_call(partial(service.resolve_quarantine, payload, apply=apply))
+        _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("shadow-start")
+@click.option("--tenant-id", required=True)
+@click.option("--expected-cas-version", type=click.IntRange(min=0), required=True)
+@click.option("--at", "started_at", default=None, help="Optional explicit timezone-aware shadow start.")
+def shadow_start(tenant_id: str, expected_cas_version: int, started_at: str | None) -> None:
+    service = _cutover_service()
+    _operator_call(
+        lambda: service.begin_shadow(
+            tenant_id=tenant_id,
+            expected_cas_version=expected_cas_version,
+            started_at=_parse_timestamp(started_at) if started_at is not None else None,
+        )
+    )
+    _echo_json(service.status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("shadow-report")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist observations; omitted means dry-run.")
+def shadow_report(input_path: Path, apply: bool) -> None:
+    observations = _read_jsonl(input_path, ShadowAuthorizationObservationInput)
+    report = _operator_call(lambda: _cutover_service().record_shadow_report(observations, apply=apply))
+    _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("shadow-complete")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist completion; omitted means dry-run.")
+def shadow_complete(input_path: Path, apply: bool) -> None:
+    payload = _read_one_jsonl(input_path, ShadowCompletionInput)
+    report = _operator_call(lambda: _cutover_service().complete_shadow(payload, apply=apply))
+    _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("issue-approve")
+@click.option("--tenant-id", required=True)
+@click.option("--issue-key", required=True)
+@click.option("--account-id", required=True)
+@click.option("--at", "approved_at", required=True)
+def issue_approve(tenant_id: str, issue_key: str, account_id: str, approved_at: str) -> None:
+    _operator_call(
+        lambda: _cutover_service().approve_issue_fail_closed(
+            tenant_id=tenant_id,
+            issue_key=issue_key,
+            account_id=account_id,
+            approved_at=_parse_timestamp(approved_at),
+        )
+    )
+    _echo_json(_cutover_service().status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("issue-resolve")
+@click.option("--tenant-id", required=True)
+@click.option("--issue-key", required=True)
+@click.option("--account-id", required=True)
+@click.option("--at", "resolved_at", required=True)
+def issue_resolve(tenant_id: str, issue_key: str, account_id: str, resolved_at: str) -> None:
+    _operator_call(
+        lambda: _cutover_service().resolve_issue(
+            tenant_id=tenant_id,
+            issue_key=issue_key,
+            account_id=account_id,
+            resolved_at=_parse_timestamp(resolved_at),
+        )
+    )
+    _echo_json(_cutover_service().status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("shadow-approve")
+@click.option("--tenant-id", required=True)
+@click.option("--diff-key", required=True)
+@click.option("--account-id", required=True)
+@click.option("--at", "approved_at", required=True)
+def shadow_approve(tenant_id: str, diff_key: str, account_id: str, approved_at: str) -> None:
+    _operator_call(
+        lambda: _cutover_service().approve_shadow_diff(
+            tenant_id=tenant_id,
+            diff_key=diff_key,
+            account_id=account_id,
+            approved_at=_parse_timestamp(approved_at),
+        )
+    )
+    _echo_json(_cutover_service().status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("shadow-resolve")
+@click.option("--tenant-id", required=True)
+@click.option("--diff-key", required=True)
+@click.option("--account-id", required=True)
+@click.option("--at", "resolved_at", required=True)
+def shadow_resolve(tenant_id: str, diff_key: str, account_id: str, resolved_at: str) -> None:
+    _operator_call(
+        lambda: _cutover_service().resolve_shadow_diff(
+            tenant_id=tenant_id,
+            diff_key=diff_key,
+            account_id=account_id,
+            resolved_at=_parse_timestamp(resolved_at),
+        )
+    )
+    _echo_json(_cutover_service().status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("legacy-dashboard")
+@click.option("--tenant-id", required=True)
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--checked-at", required=True)
+@click.option("--expected-cas-version", type=click.IntRange(min=0), default=None)
+@click.option("--apply", is_flag=True, default=False, help="Persist gate evidence; omitted means read-only report.")
+def legacy_dashboard(
+    tenant_id: str,
+    input_path: Path,
+    checked_at: str,
+    expected_cas_version: int | None,
+    apply: bool,
+) -> None:
+    dependencies = _read_jsonl(input_path, LegacyDependencyInput, allow_empty=True)
+    report = _operator_call(
+        lambda: _cutover_service().legacy_dependency_dashboard(
+            tenant_id=tenant_id,
+            dependencies=dependencies,
+            expected_cas_version=expected_cas_version,
+            checked_at=_parse_timestamp(checked_at),
+            apply=apply,
+        )
+    )
+    _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("legacy-check")
+@click.option("--tenant-id", required=True)
+def legacy_check(tenant_id: str) -> None:
+    status_report = _operator_call(lambda: _cutover_service().status(tenant_id=tenant_id))
+    passed = (
+        bool(status_report["legacy_dependency_ready"])
+        and status_report["open_issues"] == 0
+        and status_report["unresolved_cutover_quarantine"] == 0
+    )
+    _echo_json({"tenant_id": tenant_id, "passed": passed, "status": status_report})
+    if not passed:
+        raise click.exceptions.Exit(1)
+
+
+@knowledge_fs_control_space.command("freeze")
+@click.option("--tenant-id", required=True)
+@click.option("--expected-cas-version", type=click.IntRange(min=0), required=True)
+@click.option("--at", "freeze_at", required=True)
+def freeze(tenant_id: str, expected_cas_version: int, freeze_at: str) -> None:
+    service = _cutover_service()
+    _operator_call(
+        lambda: service.freeze(
+            tenant_id=tenant_id,
+            expected_cas_version=expected_cas_version,
+            freeze_at=_parse_timestamp(freeze_at),
+        )
+    )
+    _echo_json(service.status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("final-delta")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+def final_delta(input_path: Path) -> None:
+    payload = _read_one_jsonl(input_path, FinalDeltaInput)
+    service = _cutover_service()
+    _operator_call(lambda: service.apply_final_delta(payload))
+    _echo_json(service.status(tenant_id=str(payload.tenant_id)))
+
+
+@knowledge_fs_control_space.command("cutover")
+@click.option("--tenant-id", required=True)
+@click.option("--expected-cas-version", type=click.IntRange(min=0), required=True)
+@click.option("--at", "cutover_at", required=True)
+@click.option("--rollback-cutoff-at", required=True)
+def cutover(tenant_id: str, expected_cas_version: int, cutover_at: str, rollback_cutoff_at: str) -> None:
+    service = _cutover_service()
+    _operator_call(
+        lambda: service.cutover(
+            tenant_id=tenant_id,
+            expected_cas_version=expected_cas_version,
+            cutover_at=_parse_timestamp(cutover_at),
+            rollback_cutoff_at=_parse_timestamp(rollback_cutoff_at),
+        )
+    )
+    _echo_json(service.status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("smoke")
+@click.option("--tenant-id", required=True)
+@click.option("--expected-cas-version", type=click.IntRange(min=0), required=True)
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+def smoke(tenant_id: str, expected_cas_version: int, input_path: Path) -> None:
+    results = _read_one_jsonl(input_path, CutoverSmokeResultsInput)
+    service = _cutover_service()
+    _operator_call(
+        lambda: service.record_smoke_results(
+            tenant_id=tenant_id,
+            expected_cas_version=expected_cas_version,
+            results=results,
+        )
+    )
+    _echo_json(service.status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("observe")
+@click.option("--tenant-id", required=True)
+@click.option("--expected-cas-version", type=click.IntRange(min=0), required=True)
+@click.option("--started-at", default=None)
+@click.option("--window-ends-at", default=None)
+@click.option("--maximum-task-expires-at", default=None)
+@click.option("--observed-at", default=None)
+def observe(
+    tenant_id: str,
+    expected_cas_version: int,
+    started_at: str | None,
+    window_ends_at: str | None,
+    maximum_task_expires_at: str | None,
+    observed_at: str | None,
+) -> None:
+    service = _cutover_service()
+    if observed_at is not None:
+        if any(value is not None for value in (started_at, window_ends_at, maximum_task_expires_at)):
+            raise click.UsageError("--observed-at cannot be combined with observation start options")
+        _operator_call(
+            lambda: service.complete_observation(
+                tenant_id=tenant_id,
+                expected_cas_version=expected_cas_version,
+                observed_at=_parse_timestamp(observed_at),
+            )
+        )
+    else:
+        if started_at is None or window_ends_at is None or maximum_task_expires_at is None:
+            raise click.UsageError(
+                "observation start requires --started-at, --window-ends-at, and --maximum-task-expires-at"
+            )
+        _operator_call(
+            lambda: service.begin_observation(
+                tenant_id=tenant_id,
+                expected_cas_version=expected_cas_version,
+                started_at=_parse_timestamp(started_at),
+                window_ends_at=_parse_timestamp(window_ends_at),
+                maximum_task_expires_at=_parse_timestamp(maximum_task_expires_at),
+            )
+        )
+    _echo_json(service.status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("rollback")
+@click.option("--tenant-id", required=True)
+@click.option("--expected-cas-version", type=click.IntRange(min=0), required=True)
+@click.option("--at", "rolled_back_at", required=True)
+def rollback(tenant_id: str, expected_cas_version: int, rolled_back_at: str) -> None:
+    service = _cutover_service()
+    _operator_call(
+        lambda: service.rollback(
+            tenant_id=tenant_id,
+            expected_cas_version=expected_cas_version,
+            rolled_back_at=_parse_timestamp(rolled_back_at),
+        )
+    )
+    _echo_json(service.status(tenant_id=tenant_id))
+
+
+@knowledge_fs_control_space.command("status")
+@click.option("--tenant-id", required=True)
+def status(tenant_id: str) -> None:
+    _echo_json(_operator_call(lambda: _cutover_service().status(tenant_id=tenant_id)))
+
+
+@knowledge_fs_control_space.command("cleanup-request")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist readiness evidence; omitted means dry-run.")
+def cleanup_request(input_path: Path, apply: bool) -> None:
+    payload = _read_one_jsonl(input_path, CleanupReadinessEvidenceInput)
+    report = _cleanup_call(lambda: _cleanup_service().request_cleanup(payload, apply=apply))
+    _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("cleanup-approve")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist four-eyes approval; omitted means dry-run.")
+def cleanup_approve(input_path: Path, apply: bool) -> None:
+    payload = _read_one_jsonl(input_path, CleanupApprovalInput)
+    report = _cleanup_call(lambda: _cleanup_service().approve_cleanup(payload, apply=apply))
+    _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("cleanup-start")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist the irreversible fence; never runs deletion.")
+@click.option(
+    "--acknowledge-irreversible",
+    is_flag=True,
+    default=False,
+    help="Required with --apply; confirms rollback will be permanently closed.",
+)
+def cleanup_start(input_path: Path, apply: bool, acknowledge_irreversible: bool) -> None:
+    payload = _read_one_jsonl(input_path, CleanupStartInput)
+    if apply and not acknowledge_irreversible:
+        raise click.UsageError("--apply requires --acknowledge-irreversible")
+    report = _cleanup_call(lambda: _cleanup_service().start_cleanup(payload, apply=apply))
+    _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("cleanup-complete")
+@click.option("--input", "input_path", type=click.Path(path_type=Path, exists=True, dir_okay=False), required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist externally verified cleanup completion.")
+@click.option(
+    "--acknowledge-executed",
+    is_flag=True,
+    default=False,
+    help="Required with --apply; confirms the reviewed destructive bundle already executed.",
+)
+def cleanup_complete(input_path: Path, apply: bool, acknowledge_executed: bool) -> None:
+    payload = _read_one_jsonl(input_path, CleanupCompletionEvidenceInput)
+    if apply and not acknowledge_executed:
+        raise click.UsageError("--apply requires --acknowledge-executed")
+    report = _cleanup_call(lambda: _cleanup_service().complete_cleanup(payload, apply=apply))
+    _echo_json(report._asdict())
+
+
+@knowledge_fs_control_space.command("cleanup-status")
+@click.option("--tenant-id", required=True)
+@click.option("--request-id", required=True)
+def cleanup_status(tenant_id: str, request_id: str) -> None:
+    _echo_json(_cleanup_call(lambda: _cleanup_service().status(tenant_id=tenant_id, request_id=request_id)))
+
+
+@knowledge_fs_control_space.command("repair")
+@click.option("--tenant-id", required=True)
+@click.option("--control-space-id", required=True)
+@click.option("--expected-resource-version", type=click.IntRange(min=0), required=True)
+@click.option("--knowledge-space-id", required=True)
+@click.option("--knowledge-space-revision", type=click.IntRange(min=0), required=True)
+def repair(
+    tenant_id: str,
+    control_space_id: str,
+    expected_resource_version: int,
+    knowledge_space_id: str,
+    knowledge_space_revision: int,
+) -> None:
+    control_space = _management_service().repair_registration(
+        tenant_id=tenant_id,
+        control_space_id=control_space_id,
+        expected_resource_version=expected_resource_version,
+        knowledge_space_id=knowledge_space_id,
+        knowledge_space_revision=knowledge_space_revision,
+    )
+    click.echo(json.dumps({"control_space_id": control_space.id, "state": control_space.state.value}, sort_keys=True))
+
+
+@knowledge_fs_control_space.command("orphan-report")
+@click.option("--limit", type=click.IntRange(min=1, max=10_000), default=500, show_default=True)
+def orphan_report(limit: int) -> None:
+    report = KnowledgeFSOrphanReconciler(
+        session_factory.get_session_maker(),
+        get_knowledge_fs_lifecycle_remote(),
+    ).reconcile(limit=limit, apply_repairs=False)
+    click.echo(json.dumps(report._asdict(), sort_keys=True))
+
+
+@knowledge_fs_control_space.command("workspace-delete-request")
+@click.option("--tenant-id", required=True)
+@click.option("--apply", is_flag=True, default=False, help="Persist durable deletion intents; omitted means dry-run.")
+def workspace_delete_request(tenant_id: str, apply: bool) -> None:
+    """Route every KnowledgeFS Space through the canonical lifecycle deletion path."""
+
+    if not apply:
+        report = _management_service().dry_run(tenant_id=tenant_id)
+        _echo_json(
+            {
+                "apply": False,
+                "by_state": report.by_state,
+                "tenant_id": tenant_id,
+                "total": report.total,
+            }
+        )
+        return
+    results = _lifecycle_call(lambda: _lifecycle_service().request_workspace_cleanup(tenant_id=tenant_id))
+    _echo_json(
+        {
+            "apply": True,
+            "control_space_ids": [result.control_space.id for result in results],
+            "operation_ids": [result.outbox.operation_id for result in results if result.outbox is not None],
+            "tenant_id": tenant_id,
+        }
+    )
+
+
+@knowledge_fs_control_space.command("workspace-delete-finalize")
+@click.option("--tenant-id", required=True)
+@click.option("--apply", is_flag=True, default=False, help="Purge terminal local control-plane rows.")
+@click.option(
+    "--acknowledge-control-plane-purge",
+    is_flag=True,
+    default=False,
+    help="Required with --apply after every remote Space has reached deleted.",
+)
+def workspace_delete_finalize(tenant_id: str, apply: bool, acknowledge_control_plane_purge: bool) -> None:
+    """Release the Workspace FK only after all remote deletions are terminal."""
+
+    service = _lifecycle_service()
+    if not apply:
+        _lifecycle_call(lambda: service.assert_workspace_deletion_allowed(tenant_id=tenant_id))
+        _echo_json({"apply": False, "ready": True, "tenant_id": tenant_id})
+        return
+    if not acknowledge_control_plane_purge:
+        raise click.UsageError("--apply requires --acknowledge-control-plane-purge")
+    deleted = _lifecycle_call(lambda: service.finalize_workspace_deletion(tenant_id=tenant_id))
+    _echo_json({"apply": True, "purged_control_spaces": deleted, "tenant_id": tenant_id})
+
+
+def _read_jsonl[InputT: BaseModel](
+    input_path: Path, input_type: type[InputT], *, allow_empty: bool = False
+) -> tuple[InputT, ...]:
+    records: list[InputT] = []
+    for line_number, line in enumerate(input_path.read_text(encoding="utf-8").splitlines(), start=1):
+        if not line.strip():
+            continue
+        try:
+            records.append(input_type.model_validate_json(line))
+        except ValidationError as exc:
+            raise click.ClickException(f"invalid strict JSONL at line {line_number}: {exc}") from exc
+    if not records and not allow_empty:
+        raise click.ClickException("strict JSONL input must contain at least one record")
+    return tuple(records)
+
+
+def _read_one_jsonl[InputT: BaseModel](input_path: Path, input_type: type[InputT]) -> InputT:
+    records = _read_jsonl(input_path, input_type)
+    if len(records) != 1:
+        raise click.ClickException("this command requires exactly one JSONL record")
+    return records[0]
+
+
+def _parse_timestamp(value: str) -> datetime:
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError as exc:
+        raise click.ClickException(f"invalid ISO-8601 timestamp: {value}") from exc
+    if parsed.tzinfo is None:
+        raise click.ClickException("operator timestamps must include an explicit timezone")
+    return parsed
+
+
+def _operator_call[ResultT](operation: Callable[[], ResultT]) -> ResultT:
+    try:
+        return operation()
+    except KnowledgeFSCutoverError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+def _cleanup_call[ResultT](operation: Callable[[], ResultT]) -> ResultT:
+    try:
+        return operation()
+    except KnowledgeFSCleanupError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+def _lifecycle_call[ResultT](operation: Callable[[], ResultT]) -> ResultT:
+    try:
+        return operation()
+    except KnowledgeFSControlSpaceLifecycleError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+def _echo_json(payload: object) -> None:
+    click.echo(json.dumps(payload, default=str, sort_keys=True))
+
+
+def _management_service() -> KnowledgeFSControlSpaceManagementService:
+    return KnowledgeFSControlSpaceManagementService(session_factory.get_session_maker())
+
+
+def _cutover_service() -> KnowledgeFSWorkspaceCutoverService:
+    return KnowledgeFSWorkspaceCutoverService(
+        session_factory.get_session_maker(),
+        remote_factory=get_knowledge_fs_lifecycle_remote,
+    )
+
+
+def _cleanup_service() -> KnowledgeFSCleanupService:
+    return KnowledgeFSCleanupService(session_factory.get_session_maker())
+
+
+def _lifecycle_service() -> KnowledgeFSControlSpaceCommandService:
+    return KnowledgeFSControlSpaceCommandService(session_factory.get_session_maker())
+
+
+__all__ = ["knowledge_fs_control_space"]

api/commands/retention.py

@@ -1,6 +1,8 @@
 import datetime
 import logging
+import re
 import time
+import uuid
 from collections.abc import Callable
 from typing import TypedDict
 
@@ -21,6 +23,7 @@ from tasks.remove_app_and_related_data_task import delete_draft_variables_batch
 logger = logging.getLogger(__name__)
 
 _HEX_PREFIXES = tuple("0123456789abcdef")
+_TARGET_MONTH_PATTERN = re.compile(r"^\d{4}-(0[1-9]|1[0-2])$")
 
 
 class WorkflowRunArchivePlanRow(TypedDict):
@@ -66,6 +69,7 @@ def _parse_tenant_prefixes(prefixes: str | None) -> list[str]:
 
 
 def _parse_comma_separated_ids(raw_ids: str | None, *, param_name: str) -> list[str] | None:
+    """Keep an omitted scope unset while rejecting an explicitly empty scope."""
     if raw_ids is None:
         return None
     parsed = sorted({raw_id.strip() for raw_id in raw_ids.split(",") if raw_id.strip()})
@@ -74,6 +78,27 @@ def _parse_comma_separated_ids(raw_ids: str | None, *, param_name: str) -> list[
     return parsed
 
 
+def _parse_archive_target_month(target_month: str) -> tuple[int, int]:
+    """Validate the V2 catalog month selector and return its numeric components."""
+    if not _TARGET_MONTH_PATTERN.fullmatch(target_month):
+        raise click.BadParameter("target-month must use YYYY-MM format", param_hint="--target-month")
+    year_text, month_text = target_month.split("-", maxsplit=1)
+    return int(year_text), int(month_text)
+
+
+def _parse_archive_catalog_cursor(after_catalog_id: str | None) -> str | None:
+    """Normalize the exclusive V2 catalog keyset cursor when one is provided."""
+    if after_catalog_id is None:
+        return None
+    try:
+        return str(uuid.UUID(after_catalog_id))
+    except ValueError as exc:
+        raise click.BadParameter(
+            "after-catalog-id must be a UUID returned by the same V2 operation and scope",
+            param_hint="--after-catalog-id",
+        ) from exc
+
+
 def _get_archive_candidate_tenant_ids_by_prefix(
     session: Session,
     prefix: str,
@@ -810,9 +835,11 @@ def backfill_workflow_run_archive_bundles(
         click.echo(click.style(f"  ... and {len(summary.errors) - 10} more failures", fg="red"))
 
 
-def _echo_bundle_archive_operation_summary(summary) -> None:
+def _echo_bundle_archive_operation_summary(summary, *, dry_run: bool) -> None:
     status = "completed successfully" if summary.bundles_failed == 0 else "completed with failures"
     fg = "green" if summary.bundles_failed == 0 else "red"
+    cursor_label = "preview_next_catalog_id" if dry_run else "next_catalog_id"
+    cursor_value = summary.preview_next_catalog_id if dry_run else summary.next_catalog_id
     click.echo(
         click.style(
             f"{summary.operation} {status}. "
@@ -821,10 +848,12 @@ def _echo_bundle_archive_operation_summary(summary) -> None:
             f"archive_bytes={summary.archive_bytes} duration={summary.elapsed_time:.2f}s "
             f"validation_time={summary.validation_time:.2f}s "
             f"runs_per_second={summary.runs_per_second:.2f} rows_per_second={summary.rows_per_second:.2f} "
-            f"bytes_per_second={summary.bytes_per_second:.2f}",
+            f"bytes_per_second={summary.bytes_per_second:.2f} {cursor_label}={cursor_value or 'none'}",
             fg=fg,
         )
     )
+    if dry_run:
+        click.echo(click.style("Dry-run cursor is preview-only; do not persist it for a destructive run.", fg="yellow"))
     click.echo(click.style("table,row_count", fg="white"))
     for table_name in [
         "workflow_runs",
@@ -842,7 +871,8 @@ def _echo_bundle_archive_operation_summary(summary) -> None:
                 click.style(
                     f"  bundle={result.bundle_id} tenant={result.tenant_id} runs={result.run_count} "
                     f"rows={result.row_count} archive_bytes={result.archive_bytes} "
-                    f"time={result.elapsed_time:.2f}s validation={result.validation_time:.2f}s",
+                    f"catalog_id={result.catalog_id} time={result.elapsed_time:.2f}s "
+                    f"validation={result.validation_time:.2f}s",
                     fg="white",
                 )
             )
@@ -850,7 +880,7 @@ def _echo_bundle_archive_operation_summary(summary) -> None:
             click.echo(
                 click.style(
                     f"  failed bundle={result.bundle_id} tenant={result.tenant_id} "
-                    f"object_prefix={result.object_prefix} error={result.error}",
+                    f"catalog_id={result.catalog_id} object_prefix={result.object_prefix} error={result.error}",
                     fg="red",
                 )
             )
@@ -867,25 +897,24 @@ def _echo_bundle_archive_operation_summary(summary) -> None:
 )
 @click.option("--run-id", required=False, help="Workflow run ID to restore.")
 @click.option(
-    "--start-from",
-    type=click.DateTime(formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"]),
+    "--target-month",
+    metavar="YYYY-MM",
     default=None,
-    help="Optional lower bound (inclusive) for created_at; must be paired with --end-before.",
+    help="V2 catalog month to restore; required unless --run-id is used.",
 )
 @click.option(
-    "--end-before",
-    type=click.DateTime(formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"]),
+    "--after-catalog-id",
     default=None,
-    help="Optional upper bound (exclusive) for created_at; must be paired with --start-from.",
+    help="Exclusive V2 cursor from the same restore month and tenant scope.",
 )
 @click.option("--workers", default=1, show_default=True, type=int, help="V1 --run-id compatibility only.")
-@click.option("--limit", type=int, default=100, show_default=True, help="Maximum number of V2 bundles to restore.")
+@click.option("--limit", type=click.IntRange(min=1), default=100, show_default=True, help="Maximum V2 catalog rows.")
 @click.option("--dry-run", is_flag=True, help="Preview without restoring.")
 def restore_workflow_runs(
     tenant_ids: str | None,
     run_id: str | None,
-    start_from: datetime.datetime | None,
-    end_before: datetime.datetime | None,
+    target_month: str | None,
+    after_catalog_id: str | None,
     workers: int,
     limit: int,
     dry_run: bool,
@@ -905,23 +934,20 @@ def restore_workflow_runs(
     from services.retention.workflow_run.bundle_archive_maintenance import WorkflowRunBundleArchiveMaintenance
     from services.retention.workflow_run.restore_archived_workflow_run import WorkflowRunRestore
 
-    parsed_tenant_ids = None
-    if tenant_ids:
-        parsed_tenant_ids = [tid.strip() for tid in tenant_ids.split(",") if tid.strip()]
-        if not parsed_tenant_ids:
-            raise click.BadParameter("tenant-ids must not be empty")
+    parsed_tenant_ids = _parse_comma_separated_ids(tenant_ids, param_name="tenant-ids")
 
-    if (start_from is None) ^ (end_before is None):
-        raise click.UsageError("--start-from and --end-before must be provided together.")
-    if run_id is None and (start_from is None or end_before is None):
-        raise click.UsageError("--start-from and --end-before are required for batch restore.")
     if workers < 1:
         raise click.BadParameter("workers must be at least 1")
+    if run_id is not None and (target_month is not None or after_catalog_id is not None):
+        raise click.UsageError("--target-month and --after-catalog-id are only valid for V2 batch restore.")
+    if run_id is None and target_month is None:
+        raise click.UsageError("--target-month is required for V2 batch restore.")
 
     start_time = datetime.datetime.now(datetime.UTC)
+    target_desc = f"workflow run {run_id}" if run_id else f"workflow archive catalog month {target_month}"
     click.echo(
         click.style(
-            f"Starting restore of workflow run {run_id} at {start_time.isoformat()}.",
+            f"Starting restore of {target_desc} at {start_time.isoformat()}.",
             fg="white",
         )
     )
@@ -955,17 +981,20 @@ def restore_workflow_runs(
         click.echo(
             click.style("--workers is ignored for V2 bundle restore; bundles are processed serially.", fg="yellow")
         )
-    assert start_from is not None
-    assert end_before is not None
+    assert target_month is not None
+    target_year, target_month_number = _parse_archive_target_month(target_month)
+    catalog_cursor = _parse_archive_catalog_cursor(after_catalog_id)
     bundle_restorer = WorkflowRunBundleArchiveMaintenance(dry_run=dry_run, strict_content_validation=True)
     summary = bundle_restorer.restore_batch(
         tenant_ids=parsed_tenant_ids,
-        start_date=start_from,
-        end_date=end_before,
+        target_year=target_year,
+        target_month=target_month_number,
+        after_catalog_id=catalog_cursor,
         limit=limit,
     )
-    _echo_bundle_archive_operation_summary(summary)
-    return
+    _echo_bundle_archive_operation_summary(summary, dry_run=dry_run)
+    if summary.bundles_failed:
+        raise click.exceptions.Exit(1)
 
 
 @click.command(
@@ -979,23 +1008,41 @@ def restore_workflow_runs(
 )
 @click.option("--run-id", required=False, help="Workflow run ID to delete.")
 @click.option(
-    "--start-from",
-    type=click.DateTime(formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"]),
+    "--target-month",
+    metavar="YYYY-MM",
     default=None,
-    help="Optional lower bound (inclusive) for created_at; must be paired with --end-before.",
+    help="V2 catalog month to delete; required unless --run-id is used.",
 )
 @click.option(
-    "--end-before",
-    type=click.DateTime(formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"]),
+    "--after-catalog-id",
     default=None,
-    help="Optional upper bound (exclusive) for created_at; must be paired with --start-from.",
+    help="Exclusive V2 cursor from the same delete month and tenant scope.",
+)
+@click.option(
+    "--run-shard-index",
+    default=None,
+    type=click.IntRange(min=0),
+    help="Zero-based archive shard index. Must be paired with --run-shard-total.",
+)
+@click.option(
+    "--run-shard-total",
+    default=None,
+    type=click.IntRange(min=1, max=16),
+    help="Total archive shard count. Must be paired with --run-shard-index.",
+)
+@click.option("--all-pages", is_flag=True, help="Process catalog pages until an empty page is reached.")
+@click.option(
+    "--limit",
+    type=click.IntRange(min=1),
+    default=100,
+    show_default=True,
+    help="Maximum V2 catalog rows per page.",
 )
-@click.option("--limit", type=int, default=100, show_default=True, help="Maximum number of V2 bundles to delete.")
 @click.option("--dry-run", is_flag=True, help="Preview without deleting.")
 @click.option(
     "--skip-bad-archives",
     is_flag=True,
-    help="Continue batch deletion when one archive object fails validation.",
+    help="V1 --run-id only: continue when one archive object fails validation.",
 )
 @click.option(
     "--restore-sample-interval",
@@ -1007,8 +1054,11 @@ def restore_workflow_runs(
 def delete_archived_workflow_runs(
     tenant_ids: str | None,
     run_id: str | None,
-    start_from: datetime.datetime | None,
-    end_before: datetime.datetime | None,
+    target_month: str | None,
+    after_catalog_id: str | None,
+    run_shard_index: int | None,
+    run_shard_total: int | None,
+    all_pages: bool,
     limit: int,
     dry_run: bool,
     skip_bad_archives: bool,
@@ -1018,26 +1068,38 @@ def delete_archived_workflow_runs(
     Delete archived workflow runs from the database.
 
     Batch delete uses V2 bundle metadata and validates object existence, manifest schema, object size, checksum, row
-    counts, and source/archive content checksums before deleting source rows. `--run-id` keeps the V1 per-run path.
+    counts, and source/archive content checksums before deleting source rows. Parallel workers may select one exact
+    archive shard; all-pages mode keeps only the current bounded page in memory. `--run-id` keeps the V1 per-run path.
     """
     from services.retention.workflow_run.bundle_archive_maintenance import WorkflowRunBundleArchiveMaintenance
     from services.retention.workflow_run.delete_archived_workflow_run import ArchivedWorkflowRunDeletion
 
-    parsed_tenant_ids = None
-    if tenant_ids:
-        parsed_tenant_ids = [tid.strip() for tid in tenant_ids.split(",") if tid.strip()]
-        if not parsed_tenant_ids:
-            raise click.BadParameter("tenant-ids must not be empty")
+    parsed_tenant_ids = _parse_comma_separated_ids(tenant_ids, param_name="tenant-ids")
 
-    if (start_from is None) ^ (end_before is None):
-        raise click.UsageError("--start-from and --end-before must be provided together.")
-    if run_id is None and (start_from is None or end_before is None):
-        raise click.UsageError("--start-from and --end-before are required for batch delete.")
     if restore_sample_interval < 0:
         raise click.BadParameter("restore-sample-interval must be >= 0")
+    if run_id is not None and (
+        target_month is not None
+        or after_catalog_id is not None
+        or run_shard_index is not None
+        or run_shard_total is not None
+        or all_pages
+    ):
+        raise click.UsageError(
+            "--target-month, --after-catalog-id, --run-shard-index, --run-shard-total, and --all-pages "
+            "are only valid for V2 batch delete."
+        )
+    if run_id is None and target_month is None:
+        raise click.UsageError("--target-month is required for V2 batch delete.")
+    if run_id is None and skip_bad_archives:
+        raise click.UsageError("--skip-bad-archives is not supported for V2 catalog batches; they fail fast.")
+    if (run_shard_index is None) ^ (run_shard_total is None):
+        raise click.UsageError("--run-shard-index and --run-shard-total must be provided together.")
+    if run_shard_index is not None and run_shard_total is not None and run_shard_index >= run_shard_total:
+        raise click.UsageError("--run-shard-index must be less than --run-shard-total.")
 
     start_time = datetime.datetime.now(datetime.UTC)
-    target_desc = f"workflow run {run_id}" if run_id else "workflow runs"
+    target_desc = f"workflow run {run_id}" if run_id else f"workflow archive catalog month {target_month}"
     click.echo(
         click.style(
             f"Starting delete of {target_desc} at {start_time.isoformat()}.",
@@ -1110,20 +1172,104 @@ def delete_archived_workflow_runs(
 
     if restore_sample_interval:
         click.echo(click.style("--restore-sample-interval is ignored for V2 bundle delete.", fg="yellow"))
-    assert start_from is not None
-    assert end_before is not None
-    bundle_deleter = WorkflowRunBundleArchiveMaintenance(
-        dry_run=dry_run,
-        strict_content_validation=True,
-        stop_on_error=not skip_bad_archives,
+    assert target_month is not None
+    target_year, target_month_number = _parse_archive_target_month(target_month)
+    catalog_cursor = _parse_archive_catalog_cursor(after_catalog_id)
+    shard = (
+        f"{run_shard_index:02d}-of-{run_shard_total:02d}"
+        if run_shard_index is not None and run_shard_total is not None
+        else None
     )
-    summary = bundle_deleter.delete_batch(
-        tenant_ids=parsed_tenant_ids,
-        start_date=start_from,
-        end_date=end_before,
-        limit=limit,
-    )
-    _echo_bundle_archive_operation_summary(summary)
+    bundle_deleter = WorkflowRunBundleArchiveMaintenance(dry_run=dry_run, strict_content_validation=True)
+    if run_shard_total is not None:
+        try:
+            bundle_deleter.validate_catalog_shards(
+                target_year=target_year,
+                target_month=target_month_number,
+                shard_total=run_shard_total,
+                tenant_ids=parsed_tenant_ids,
+            )
+        except ValueError as exc:
+            logger.exception(
+                "Archive catalog shard preflight failed: target_month=%s shard=%s",
+                target_month,
+                shard,
+            )
+            raise click.ClickException(
+                f"Archive catalog shard preflight failed for target_month={target_month} shard={shard}: {exc}"
+            ) from exc
+
+    initial_catalog_cursor = catalog_cursor
+    pages_processed = 0
+    bundles_succeeded = 0
+    runs_processed = 0
+    rows_processed = 0
+    archive_bytes = 0
+    while True:
+        summary = bundle_deleter.delete_batch(
+            tenant_ids=parsed_tenant_ids,
+            target_year=target_year,
+            target_month=target_month_number,
+            after_catalog_id=catalog_cursor,
+            limit=limit,
+            shard=shard,
+        )
+        _echo_bundle_archive_operation_summary(summary, dry_run=dry_run)
+        if summary.bundles_failed:
+            failed_result = next((result for result in summary.results if not result.success), None)
+            failed_catalog_id = failed_result.catalog_id if failed_result is not None else "unknown"
+            page_resume_cursor = summary.preview_next_catalog_id if dry_run else summary.next_catalog_id
+            resume_cursor = page_resume_cursor or catalog_cursor
+            if dry_run:
+                cursor_details = (
+                    f"preview_after_catalog_id={resume_cursor or 'none'} "
+                    f"destructive_retry_after_catalog_id={initial_catalog_cursor or 'none'}"
+                )
+            else:
+                cursor_details = f"resume_after_catalog_id={resume_cursor or 'none'}"
+            click.echo(
+                click.style(
+                    f"Delete stopped: target_month={target_month} shard={shard or 'all'} "
+                    f"failed_catalog_id={failed_catalog_id} "
+                    f"{cursor_details}",
+                    fg="red",
+                )
+            )
+            raise click.exceptions.Exit(1)
+
+        if not all_pages:
+            break
+        if summary.bundles_processed == 0:
+            break
+
+        pages_processed += 1
+        bundles_succeeded += summary.bundles_succeeded
+        runs_processed += summary.runs_processed
+        rows_processed += summary.rows_processed
+        archive_bytes += summary.archive_bytes
+        next_catalog_id = summary.preview_next_catalog_id if dry_run else summary.next_catalog_id
+        if next_catalog_id is None or (catalog_cursor is not None and next_catalog_id <= catalog_cursor):
+            click.echo(
+                click.style(
+                    f"Delete cursor did not advance: target_month={target_month} shard={shard or 'all'} "
+                    f"after_catalog_id={catalog_cursor or 'none'} next_catalog_id={next_catalog_id or 'none'}",
+                    fg="red",
+                )
+            )
+            raise click.exceptions.Exit(1)
+        catalog_cursor = next_catalog_id
+
+    if all_pages:
+        final_cursor_label = "preview_final_catalog_id" if dry_run else "final_catalog_id"
+        click.echo(
+            click.style(
+                f"Delete all-pages completed successfully. target_month={target_month} shard={shard or 'all'} "
+                f"pages={pages_processed} bundles_success={bundles_succeeded} runs={runs_processed} "
+                f"rows={rows_processed} archive_bytes={archive_bytes} "
+                f"{final_cursor_label}={catalog_cursor or 'none'}",
+                fg="green",
+            )
+        )
 
 
 def _find_orphaned_draft_variables(batch_size: int = 1000) -> list[str]:

api/configs/extra/__init__.py

@@ -1,5 +1,6 @@
 from configs.extra.agent_backend_config import AgentBackendConfig
 from configs.extra.archive_config import ArchiveStorageConfig
+from configs.extra.knowledge_fs_config import KnowledgeFSConfig
 from configs.extra.notion_config import NotionConfig
 from configs.extra.sentry_config import SentryConfig
 
@@ -8,6 +9,7 @@ class ExtraServiceConfig(
     # place the configs in alphabet order
     AgentBackendConfig,
     ArchiveStorageConfig,
+    KnowledgeFSConfig,
     NotionConfig,
     SentryConfig,
 ):

api/configs/extra/agent_backend_config.py

@@ -1,4 +1,4 @@
-from pydantic import Field, NonNegativeFloat
+from pydantic import Field, NonNegativeFloat, NonNegativeInt, PositiveFloat
 from pydantic_settings import BaseSettings
 
 
@@ -22,6 +22,21 @@ class AgentBackendConfig(BaseSettings):
         default="success",
     )
 
+    AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS: PositiveFloat = Field(
+        description="Read timeout for one Agent backend SSE connection.",
+        default=30,
+    )
+
+    AGENT_BACKEND_STREAM_MAX_RECONNECTS: NonNegativeInt = Field(
+        description="Maximum Agent backend SSE reconnects before failing the run.",
+        default=3,
+    )
+
+    AGENT_BACKEND_RUN_TIMEOUT_SECONDS: PositiveFloat = Field(
+        description="Total deadline for one Agent backend run event stream.",
+        default=1200,
+    )
+
     AGENT_SHELL_ENABLED: bool = Field(
         description=(
             "Inject the dify.shell layer (sandboxed bash workspace) into Agent runs. "

api/configs/extra/knowledge_fs_config.py

@@ -0,0 +1,134 @@
+"""Configuration for the optional KnowledgeFS control-plane integration."""
+
+from ipaddress import ip_address
+from urllib.parse import urlsplit
+
+from pydantic import Field, PositiveFloat, PositiveInt, SecretStr, field_validator, model_validator
+from pydantic_settings import BaseSettings
+
+
+class KnowledgeFSConfig(BaseSettings):
+    """Server-only KnowledgeFS connection and rollout settings."""
+
+    KNOWLEDGE_FS_ENABLED: bool = Field(
+        default=False,
+        description="Enable the private KnowledgeFS Console bridge.",
+    )
+    KNOWLEDGE_FS_LIFECYCLE_WORKER_ENABLED: bool = Field(
+        default=False,
+        description="Enable delivery of durable KnowledgeFS lifecycle commands after every rollout gate is ready.",
+    )
+    KNOWLEDGE_FS_INTEGRATED_PROVISION_READY: bool = Field(
+        default=False,
+        description="Confirm that the Capability-v2 integrated provision route is deployed and verified.",
+    )
+    KNOWLEDGE_FS_LEGACY_ACL_FREEZE_READY: bool = Field(
+        default=False,
+        description="Confirm that legacy KFS ACL mutation is frozen for integrated mode.",
+    )
+    KNOWLEDGE_FS_LIFECYCLE_POLL_INTERVAL_SECONDS: PositiveInt = Field(default=15, le=300)
+    KNOWLEDGE_FS_LIFECYCLE_LEASE_SECONDS: PositiveInt = Field(default=60, le=600)
+    KNOWLEDGE_FS_LIFECYCLE_BATCH_SIZE: PositiveInt = Field(default=25, le=1_000)
+    KNOWLEDGE_FS_BASE_URL: str | None = Field(default=None, description="KnowledgeFS gateway base URL.")
+    KNOWLEDGE_FS_DIRECT_ORIGIN: str | None = Field(
+        default=None,
+        description="Public KnowledgeFS origin returned with direct upload capabilities.",
+    )
+    KNOWLEDGE_FS_CAPABILITY_V2_ENABLED: bool = Field(
+        default=False,
+        description="Prepare resource-scoped Capability v2 issuance; disabled until rollout approval.",
+    )
+    KNOWLEDGE_FS_CAPABILITY_V2_SIGNING_KID: str | None = Field(
+        default=None,
+        description="Identifier for the current asymmetric Capability v2 signing key.",
+    )
+    KNOWLEDGE_FS_CAPABILITY_V2_PRIVATE_KEY_PEM: SecretStr | None = Field(
+        default=None,
+        description="Server-only PEM for the current Capability v2 RSA signing key.",
+    )
+    KNOWLEDGE_FS_CAPABILITY_V2_PREVIOUS_PUBLIC_JWKS: str | None = Field(
+        default=None,
+        description="Optional public-only JWKS JSON retained during key rotation overlap.",
+    )
+    KNOWLEDGE_FS_CAPABILITY_V2_ISSUER: str = Field(default="dify-control-plane", min_length=1)
+    KNOWLEDGE_FS_CAPABILITY_V2_AUDIENCE: str = Field(default="knowledge-fs", min_length=1)
+    KNOWLEDGE_FS_CAPABILITY_V2_MAX_TTL_SECONDS: PositiveInt = Field(default=60, le=60)
+    KNOWLEDGE_FS_JWKS_CACHE_MAX_AGE_SECONDS: PositiveInt = Field(default=300, le=86_400)
+    KNOWLEDGE_FS_PRODUCT_MAX_RESPONSE_BYTES: PositiveInt = Field(default=4 * 1024 * 1024, le=16 * 1024 * 1024)
+    KNOWLEDGE_FS_TIMEOUT_SECONDS: PositiveFloat = Field(default=10.0, le=60.0, allow_inf_nan=False)
+
+    @field_validator(
+        "KNOWLEDGE_FS_BASE_URL",
+        "KNOWLEDGE_FS_DIRECT_ORIGIN",
+        "KNOWLEDGE_FS_CAPABILITY_V2_SIGNING_KID",
+        "KNOWLEDGE_FS_CAPABILITY_V2_PRIVATE_KEY_PEM",
+        "KNOWLEDGE_FS_CAPABILITY_V2_PREVIOUS_PUBLIC_JWKS",
+        mode="before",
+    )
+    @classmethod
+    def normalize_optional_string(cls, value: object) -> object:
+        if isinstance(value, SecretStr):
+            normalized = value.get_secret_value().strip()
+            return SecretStr(normalized) if normalized else None
+        if isinstance(value, str):
+            normalized = value.strip()
+            return normalized or None
+        return value
+
+    @field_validator("KNOWLEDGE_FS_BASE_URL")
+    @classmethod
+    def validate_base_url(cls, value: str | None) -> str | None:
+        return cls._validate_origin(value, name="KNOWLEDGE_FS_BASE_URL")
+
+    @field_validator("KNOWLEDGE_FS_DIRECT_ORIGIN")
+    @classmethod
+    def validate_direct_origin(cls, value: str | None) -> str | None:
+        return cls._validate_origin(value, name="KNOWLEDGE_FS_DIRECT_ORIGIN")
+
+    @classmethod
+    def _validate_origin(cls, value: str | None, *, name: str) -> str | None:
+        if value is None:
+            return None
+        parsed = urlsplit(value)
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+            raise ValueError(f"{name} must be an absolute HTTP(S) URL")
+        try:
+            _ = parsed.port
+        except ValueError as exc:
+            raise ValueError(f"{name} must include a valid port") from exc
+        if parsed.username or parsed.password or parsed.query or parsed.fragment or parsed.path not in {"", "/"}:
+            raise ValueError(f"{name} must be an origin without credentials, path, query, or fragment")
+        return value.rstrip("/")
+
+    @model_validator(mode="after")
+    def validate_enabled_connection(self) -> "KnowledgeFSConfig":
+        if str(getattr(self, "DEPLOY_ENV", "")).strip().upper() == "PRODUCTION":
+            for name, value in (
+                ("KNOWLEDGE_FS_BASE_URL", self.KNOWLEDGE_FS_BASE_URL),
+                ("KNOWLEDGE_FS_DIRECT_ORIGIN", self.KNOWLEDGE_FS_DIRECT_ORIGIN),
+            ):
+                if value and not self._is_secure_or_loopback_origin(value):
+                    raise ValueError(f"{name} must use HTTPS in production unless it targets loopback")
+        if self.KNOWLEDGE_FS_ENABLED:
+            if not self.KNOWLEDGE_FS_BASE_URL:
+                raise ValueError("KnowledgeFS base URL is required when the integration is enabled")
+            if not self.KNOWLEDGE_FS_CAPABILITY_V2_ENABLED:
+                raise ValueError("KnowledgeFS product routes require Capability v2 when enabled")
+        if self.KNOWLEDGE_FS_CAPABILITY_V2_ENABLED and not (
+            self.KNOWLEDGE_FS_CAPABILITY_V2_SIGNING_KID and self.KNOWLEDGE_FS_CAPABILITY_V2_PRIVATE_KEY_PEM
+        ):
+            raise ValueError("Capability v2 signing kid and private key are required when issuance is enabled")
+        return self
+
+    @staticmethod
+    def _is_secure_or_loopback_origin(value: str) -> bool:
+        parsed = urlsplit(value)
+        if parsed.scheme == "https":
+            return True
+        hostname = (parsed.hostname or "").rstrip(".").lower()
+        if hostname == "localhost":
+            return True
+        try:
+            return ip_address(hostname).is_loopback
+        except ValueError:
+            return False

api/configs/feature/__init__.py

@@ -275,6 +275,42 @@ class PluginConfig(BaseSettings):
         default=50 * 1024 * 1024,
     )
 
+    NEW_USER_DEFAULT_PLUGIN_IDS: str = Field(
+        description="Comma-separated marketplace plugin IDs whose latest versions are installed for new users",
+        default="",
+    )
+
+    @property
+    def NEW_USER_DEFAULT_PLUGIN_ID_LIST(self) -> list[str]:
+        return [item.strip() for item in self.NEW_USER_DEFAULT_PLUGIN_IDS.split(",") if item.strip()]
+
+    NEW_USER_DEFAULT_MODELS: str = Field(
+        description=("Comma-separated default models for new users in 'model_type:provider:model' format"),
+        default="",
+    )
+
+    @property
+    def NEW_USER_DEFAULT_MODEL_LIST(self) -> list[tuple[str, str, str]]:
+        default_models: list[tuple[str, str, str]] = []
+        configured_model_types: set[str] = set()
+
+        for item in self.NEW_USER_DEFAULT_MODELS.split(","):
+            if not item.strip():
+                continue
+
+            parts = tuple(part.strip() for part in item.split(":", 2))
+            if len(parts) != 3 or not all(parts):
+                raise ValueError("NEW_USER_DEFAULT_MODELS entries must use 'model_type:provider:model' format")
+
+            model_type, provider, model = parts
+            if model_type in configured_model_types:
+                raise ValueError(f"NEW_USER_DEFAULT_MODELS contains duplicate model type: {model_type}")
+
+            configured_model_types.add(model_type)
+            default_models.append((model_type, provider, model))
+
+        return default_models
+
 
 class MarketplaceConfig(BaseSettings):
     """
@@ -784,6 +820,11 @@ class WorkflowConfig(BaseSettings):
         default=500,
     )
 
+    WORKFLOW_GENERATOR_NODE_BUILDER_MAX_WORKERS: PositiveInt = Field(
+        description="Maximum concurrent node-builder LLM calls per workflow generation request",
+        default=6,
+    )
+
     WORKFLOW_MAX_EXECUTION_TIME: PositiveInt = Field(
         description="Maximum execution time in seconds for a single workflow",
         default=1200,

api/controllers/console/__init__.py

@@ -125,6 +125,7 @@ from .explore import (
     saved_message,
     trial,
 )
+from .knowledge_fs import resources as knowledge_fs_resources
 from .snippets import snippet_workflow, snippet_workflow_draft_variable
 from .socketio import workflow as socketio_workflow
 
@@ -195,6 +196,7 @@ __all__ = [
     "human_input_form",
     "init_validate",
     "installed_app",
+    "knowledge_fs_resources",
     "load_balancing_config",
     "login",
     "mcp_server",

api/controllers/console/app/workflow.py

@@ -105,6 +105,7 @@ class SyncDraftWorkflowPayload(BaseModel):
     graph: dict[str, Any]
     features: dict[str, Any]
     hash: str | None = None
+    is_collaborative: bool = Field(default=False, alias="_is_collaborative")
     environment_variables: list[dict[str, Any]] = Field(
         default_factory=list,
     )
@@ -610,6 +611,7 @@ class DraftWorkflowApi(Resource):
                 environment_variables=environment_variables,
                 conversation_variables=conversation_variables,
                 session=db.session(),
+                graph_only=args["is_collaborative"],
             )
         except WorkflowHashNotEqualError:
             raise DraftWorkflowNotSync()

api/controllers/console/explore/trial.py

@@ -47,7 +47,9 @@ from controllers.console.explore.error import (
     NotWorkflowAppError,
 )
 from controllers.console.explore.wraps import TrialAppResource, trial_feature_enable
-from controllers.console.wraps import with_current_user
+from controllers.console.files import FILE_UPLOAD_PARAMS, upload_file_from_request
+from controllers.console.remote_files import RemoteFileUploadPayload, upload_remote_file_from_request
+from controllers.console.wraps import cloud_edition_billing_resource_check, with_current_user
 from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
 from core.app.app_config.common.parameters_mapping import get_parameters_from_feature_dict
 from core.app.apps.base_app_queue_manager import AppQueueManager
@@ -61,12 +63,13 @@ from extensions.ext_database import db
 from extensions.ext_redis import redis_client
 from fields.base import ResponseModel
 from fields.conversation_variable_fields import WorkflowConversationVariableResponse
+from fields.file_fields import FileResponse, FileWithSignedUrl
 from fields.message_fields import SuggestedQuestionsResponse
 from graphon.graph_engine.manager import GraphEngineManager
 from graphon.model_runtime.errors.invoke import InvokeError
 from libs import helper
 from libs.helper import dump_response, to_timestamp, uuid_value
-from models import Account
+from models import Account, App
 from models.account import TenantStatus
 from models.model import AppMode, Site, load_annotation_reply_config
 from models.workflow import Workflow
@@ -428,6 +431,36 @@ register_response_schema_models(
 simple_account_model = console_ns.models[TrialSimpleAccount.__name__]
 
 
+class TrialAppFileUploadApi(TrialAppResource):
+    @trial_feature_enable
+    @cloud_edition_billing_resource_check("documents")
+    @console_ns.doc(consumes=["multipart/form-data"], params=FILE_UPLOAD_PARAMS)
+    @console_ns.response(201, "File uploaded successfully", console_ns.models[FileResponse.__name__])
+    @with_current_user
+    def post(self, current_user: Account, app_model: App):
+        """Upload a file into the tenant that owns the trial app."""
+        upload_file = upload_file_from_request(
+            current_user=current_user,
+            resource_tenant_id=app_model.tenant_id,
+        )
+        return dump_response(FileResponse, upload_file), 201
+
+
+class TrialAppRemoteFileUploadApi(TrialAppResource):
+    @trial_feature_enable
+    @cloud_edition_billing_resource_check("documents")
+    @console_ns.expect(console_ns.models[RemoteFileUploadPayload.__name__])
+    @console_ns.response(201, "File uploaded successfully", console_ns.models[FileWithSignedUrl.__name__])
+    @with_current_user
+    def post(self, current_user: Account, app_model: App):
+        """Upload a remote file into the tenant that owns the trial app."""
+        remote_file = upload_remote_file_from_request(
+            current_user=current_user,
+            resource_tenant_id=app_model.tenant_id,
+        )
+        return remote_file.model_dump(mode="json"), 201
+
+
 class TrialAppWorkflowRunApi(TrialAppResource):
     @trial_feature_enable
     @console_ns.expect(console_ns.models[WorkflowRunRequest.__name__])
@@ -887,6 +920,18 @@ class DatasetListApi(Resource):
 
 console_ns.add_resource(TrialChatApi, "/trial-apps/<uuid:app_id>/chat-messages", endpoint="trial_app_chat_completion")
 
+console_ns.add_resource(
+    TrialAppFileUploadApi,
+    "/trial-apps/<uuid:app_id>/files/upload",
+    endpoint="trial_app_file_upload",
+)
+
+console_ns.add_resource(
+    TrialAppRemoteFileUploadApi,
+    "/trial-apps/<uuid:app_id>/remote-files/upload",
+    endpoint="trial_app_remote_file_upload",
+)
+
 console_ns.add_resource(
     TrialMessageSuggestedQuestionApi,
     "/trial-apps/<uuid:app_id>/messages/<uuid:message_id>/suggested-questions",

api/controllers/console/files.py

@@ -29,7 +29,7 @@ from extensions.ext_database import db
 from fields.file_fields import FileResponse, UploadConfig
 from libs.helper import dump_response
 from libs.login import login_required
-from models import Account
+from models import Account, UploadFile
 from services.file_service import FileService
 
 from . import console_ns
@@ -39,7 +39,7 @@ register_response_schema_models(console_ns, AllowedExtensionsResponse, TextConte
 
 PREVIEW_WORDS_LIMIT = 3000
 
-_FILE_UPLOAD_PARAMS = {
+FILE_UPLOAD_PARAMS = {
     "file": {
         "description": "File to upload",
         "in": "formData",
@@ -56,6 +56,43 @@ _FILE_UPLOAD_PARAMS = {
 }
 
 
+def upload_file_from_request(*, current_user: Account, resource_tenant_id: str | None = None) -> UploadFile:
+    """Validate the multipart request and persist the file under the requested resource tenant."""
+    source_str = request.form.get("source")
+    source: Literal["datasets"] | None = "datasets" if source_str == "datasets" else None
+
+    if "file" not in request.files:
+        raise NoFileUploadedError()
+
+    if len(request.files) > 1:
+        raise TooManyFilesError()
+    file = request.files["file"]
+
+    if not file.filename:
+        raise FilenameNotExistsError
+    if source == "datasets" and not current_user.is_dataset_editor:
+        raise Forbidden()
+
+    if source not in ("datasets", None):
+        source = None
+
+    try:
+        return FileService(db.engine).upload_file(
+            filename=file.filename,
+            content=file.stream.read(),
+            mimetype=file.mimetype,
+            user=current_user,
+            tenant_id=resource_tenant_id,
+            source=source,
+        )
+    except services.errors.file.FileTooLargeError as file_too_large_error:
+        raise FileTooLargeError(file_too_large_error.description)
+    except services.errors.file.UnsupportedFileTypeError:
+        raise UnsupportedFileTypeError()
+    except services.errors.file.BlockedFileExtensionError as blocked_extension_error:
+        raise BlockedFileExtensionError(blocked_extension_error.description)
+
+
 @console_ns.route("/files/upload")
 class FileApi(Resource):
     @setup_required
@@ -81,42 +118,11 @@ class FileApi(Resource):
     @login_required
     @account_initialization_required
     @cloud_edition_billing_resource_check("documents")
-    @console_ns.doc(consumes=["multipart/form-data"], params=_FILE_UPLOAD_PARAMS)
+    @console_ns.doc(consumes=["multipart/form-data"], params=FILE_UPLOAD_PARAMS)
     @console_ns.response(201, "File uploaded successfully", console_ns.models[FileResponse.__name__])
     @with_current_user
     def post(self, current_user: Account):
-        source_str = request.form.get("source")
-        source: Literal["datasets"] | None = "datasets" if source_str == "datasets" else None
-
-        if "file" not in request.files:
-            raise NoFileUploadedError()
-
-        if len(request.files) > 1:
-            raise TooManyFilesError()
-        file = request.files["file"]
-
-        if not file.filename:
-            raise FilenameNotExistsError
-        if source == "datasets" and not current_user.is_dataset_editor:
-            raise Forbidden()
-
-        if source not in ("datasets", None):
-            source = None
-
-        try:
-            upload_file = FileService(db.engine).upload_file(
-                filename=file.filename,
-                content=file.stream.read(),
-                mimetype=file.mimetype,
-                user=current_user,
-                source=source,
-            )
-        except services.errors.file.FileTooLargeError as file_too_large_error:
-            raise FileTooLargeError(file_too_large_error.description)
-        except services.errors.file.UnsupportedFileTypeError:
-            raise UnsupportedFileTypeError()
-        except services.errors.file.BlockedFileExtensionError as blocked_extension_error:
-            raise BlockedFileExtensionError(blocked_extension_error.description)
+        upload_file = upload_file_from_request(current_user=current_user)
 
         return dump_response(FileResponse, upload_file), 201
 

api/controllers/console/knowledge_fs/__init__.py

@@ -0,0 +1,5 @@
+"""Typed Dify-owned KnowledgeFS Console product API."""
+
+from . import resources
+
+__all__ = ["resources"]

api/controllers/console/knowledge_fs/error.py

@@ -0,0 +1,56 @@
+"""Stable, non-enumerating Console error contract for KnowledgeFS."""
+
+from libs.exception import BaseHTTPException
+
+
+class KnowledgeFSSpaceNotFoundHTTPError(BaseHTTPException):
+    error_code = "knowledge_fs_space_not_found"
+    description = "KnowledgeFS space was not found."
+    code = 404
+
+
+class KnowledgeFSOperationUnavailableHTTPError(BaseHTTPException):
+    error_code = "knowledge_fs_operation_unavailable"
+    description = "KnowledgeFS operation is not available."
+    code = 503
+
+
+class KnowledgeFSUpstreamUnavailableHTTPError(BaseHTTPException):
+    error_code = "knowledge_fs_upstream_unavailable"
+    description = "KnowledgeFS is unavailable."
+    code = 502
+
+
+class KnowledgeFSInvalidRequestHTTPError(BaseHTTPException):
+    error_code = "knowledge_fs_invalid_request"
+    description = "KnowledgeFS request is invalid."
+    code = 400
+
+
+class KnowledgeFSAccessDeniedHTTPError(BaseHTTPException):
+    error_code = "knowledge_fs_access_denied"
+    description = "KnowledgeFS operation is not allowed."
+    code = 403
+
+
+class KnowledgeFSRateLimitHTTPError(BaseHTTPException):
+    error_code = "knowledge_fs_rate_limit_exceeded"
+    description = "KnowledgeFS operation rate limit exceeded."
+    code = 429
+
+
+class KnowledgeFSQuotaExceededHTTPError(BaseHTTPException):
+    error_code = "knowledge_fs_quota_exceeded"
+    description = "KnowledgeFS operation quota exceeded."
+    code = 403
+
+
+__all__ = [
+    "KnowledgeFSAccessDeniedHTTPError",
+    "KnowledgeFSInvalidRequestHTTPError",
+    "KnowledgeFSOperationUnavailableHTTPError",
+    "KnowledgeFSQuotaExceededHTTPError",
+    "KnowledgeFSRateLimitHTTPError",
+    "KnowledgeFSSpaceNotFoundHTTPError",
+    "KnowledgeFSUpstreamUnavailableHTTPError",
+]

api/controllers/console/remote_files.py

@@ -46,6 +46,61 @@ class GetRemoteFileInfo(Resource):
         ).model_dump(mode="json")
 
 
+def upload_remote_file_from_request(
+    *,
+    current_user: Account,
+    resource_tenant_id: str | None = None,
+) -> FileWithSignedUrl:
+    """Validate the JSON request, fetch its remote file, and persist it under the requested tenant."""
+    payload = RemoteFileUploadPayload.model_validate(console_ns.payload)
+    url = payload.url
+
+    # Try to fetch remote file metadata/content first
+    try:
+        resp = remote_fetcher.make_request("HEAD", url=url)
+        if resp.status_code != httpx.codes.OK:
+            resp = remote_fetcher.make_request("GET", url=url, timeout=3, follow_redirects=True)
+        if resp.status_code != httpx.codes.OK:
+            # Normalize into a user-friendly error message expected by tests
+            raise RemoteFileUploadError(f"Failed to fetch file from {url}: {resp.text}")
+    except httpx.RequestError as e:
+        raise RemoteFileUploadError(f"Failed to fetch file from {url}: {str(e)}")
+
+    file_info = helpers.guess_file_info_from_response(resp)
+
+    # Enforce file size limit with 400 (Bad Request) per tests' expectation
+    if not FileService.is_file_size_within_limit(extension=file_info.extension, file_size=file_info.size):
+        raise FileTooLargeError()
+
+    # Load content if needed
+    content = resp.content if resp.request.method == "GET" else remote_fetcher.make_request("GET", url).content
+
+    try:
+        upload_file = FileService(db.engine).upload_file(
+            filename=file_info.filename,
+            content=content,
+            mimetype=file_info.mimetype,
+            user=current_user,
+            tenant_id=resource_tenant_id,
+            source_url=url,
+        )
+    except services.errors.file.FileTooLargeError as file_too_large_error:
+        raise FileTooLargeError(file_too_large_error.description)
+    except services.errors.file.UnsupportedFileTypeError:
+        raise UnsupportedFileTypeError()
+
+    return FileWithSignedUrl(
+        id=upload_file.id,
+        name=upload_file.name,
+        size=upload_file.size,
+        extension=upload_file.extension,
+        url=file_helpers.get_signed_file_url(upload_file_id=upload_file.id),
+        mime_type=upload_file.mime_type,
+        created_by=upload_file.created_by,
+        created_at=int(upload_file.created_at.timestamp()),
+    )
+
+
 @console_ns.route("/remote-files/upload")
 class RemoteFileUpload(Resource):
     @console_ns.expect(console_ns.models[RemoteFileUploadPayload.__name__])
@@ -53,53 +108,8 @@ class RemoteFileUpload(Resource):
     @login_required
     @with_current_user
     def post(self, current_user: Account):
-        payload = RemoteFileUploadPayload.model_validate(console_ns.payload)
-        url = payload.url
-
-        # Try to fetch remote file metadata/content first
-        try:
-            resp = remote_fetcher.make_request("HEAD", url=url)
-            if resp.status_code != httpx.codes.OK:
-                resp = remote_fetcher.make_request("GET", url=url, timeout=3, follow_redirects=True)
-            if resp.status_code != httpx.codes.OK:
-                # Normalize into a user-friendly error message expected by tests
-                raise RemoteFileUploadError(f"Failed to fetch file from {url}: {resp.text}")
-        except httpx.RequestError as e:
-            raise RemoteFileUploadError(f"Failed to fetch file from {url}: {str(e)}")
-
-        file_info = helpers.guess_file_info_from_response(resp)
-
-        # Enforce file size limit with 400 (Bad Request) per tests' expectation
-        if not FileService.is_file_size_within_limit(extension=file_info.extension, file_size=file_info.size):
-            raise FileTooLargeError()
-
-        # Load content if needed
-        content = resp.content if resp.request.method == "GET" else remote_fetcher.make_request("GET", url).content
-
-        try:
-            upload_file = FileService(db.engine).upload_file(
-                filename=file_info.filename,
-                content=content,
-                mimetype=file_info.mimetype,
-                user=current_user,
-                source_url=url,
-            )
-        except services.errors.file.FileTooLargeError as file_too_large_error:
-            raise FileTooLargeError(file_too_large_error.description)
-        except services.errors.file.UnsupportedFileTypeError:
-            raise UnsupportedFileTypeError()
-
-        # Success: return created resource with 201 status
+        remote_file = upload_remote_file_from_request(current_user=current_user)
         return (
-            FileWithSignedUrl(
-                id=upload_file.id,
-                name=upload_file.name,
-                size=upload_file.size,
-                extension=upload_file.extension,
-                url=file_helpers.get_signed_file_url(upload_file_id=upload_file.id),
-                mime_type=upload_file.mime_type,
-                created_by=upload_file.created_by,
-                created_at=int(upload_file.created_at.timestamp()),
-            ).model_dump(mode="json"),
+            remote_file.model_dump(mode="json"),
             201,
         )

api/controllers/console/socketio/workflow.py

@@ -98,6 +98,7 @@ def handle_collaboration_event(sid, data):
     6. workflow_update
     7. comments_update
     8. node_panel_presence
+    9. graph_view_state (session reports tab visibility; drives leader election)
     """
     return collaboration_service.relay_collaboration_event(sid, data)
 

api/controllers/console/workspace/rbac.py

@@ -346,7 +346,13 @@ class RBACRoleItemApi(Resource):
     def put(self, role_id):
         tenant_id, account_id = _current_ids()
         request = _payload(_RoleUpsertRequest)
-        role = svc.RBACService.Roles.update(tenant_id, account_id, str(role_id), request.to_mutation())
+        role = svc.RBACService.KnowledgeFSRoleMutations.update_role(
+            tenant_id,
+            account_id,
+            str(role_id),
+            request.to_mutation(),
+            session=db.session(),
+        )
         return _dump(role)
 
     @login_required
@@ -356,7 +362,12 @@ class RBACRoleItemApi(Resource):
     @console_ns.response(200, "Success", console_ns.models[svc.RBACRole.__name__])
     def delete(self, role_id):
         tenant_id, account_id = _current_ids()
-        svc.RBACService.Roles.delete(tenant_id, account_id, str(role_id))
+        svc.RBACService.KnowledgeFSRoleMutations.delete_role(
+            tenant_id,
+            account_id,
+            str(role_id),
+            session=db.session(),
+        )
         return {"result": "success"}
 
 
@@ -915,7 +926,7 @@ class RBACMemberRolesApi(Resource):
         tenant_id, account_id = _current_ids()
         request = _payload(_ReplaceMemberRolesRequest)
         return _dump(
-            svc.RBACService.MemberRoles.replace(
+            svc.RBACService.KnowledgeFSRoleMutations.replace_member_roles(
                 tenant_id,
                 account_id,
                 str(member_id),

api/controllers/inner_api/plugin/plugin.py

@@ -8,6 +8,7 @@ from controllers.inner_api.plugin.wraps import get_user_tenant, plugin_data
 from controllers.inner_api.wraps import plugin_inner_api_only
 from core.plugin.backwards_invocation.app import PluginAppBackwardsInvocation
 from core.plugin.backwards_invocation.base import BaseBackwardsInvocationResponse
+from core.plugin.backwards_invocation.datasource import PluginDatasourceBackwardsInvocation
 from core.plugin.backwards_invocation.encrypt import PluginEncrypter
 from core.plugin.backwards_invocation.model import PluginModelBackwardsInvocation
 from core.plugin.backwards_invocation.node import PluginNodeBackwardsInvocation
@@ -15,10 +16,12 @@ from core.plugin.backwards_invocation.tool import PluginToolBackwardsInvocation
 from core.plugin.entities.request import (
     RequestFetchAppInfo,
     RequestInvokeApp,
+    RequestInvokeDatasource,
     RequestInvokeEncrypt,
     RequestInvokeLLM,
     RequestInvokeLLMWithStructuredOutput,
     RequestInvokeModeration,
+    RequestInvokeMultimodalEmbedding,
     RequestInvokeParameterExtractorNode,
     RequestInvokeQuestionClassifierNode,
     RequestInvokeRerank,
@@ -27,6 +30,7 @@ from core.plugin.entities.request import (
     RequestInvokeTextEmbedding,
     RequestInvokeTool,
     RequestInvokeTTS,
+    RequestListModels,
     RequestRequestDownloadFile,
     RequestRequestUploadFile,
 )
@@ -118,6 +122,36 @@ class PluginInvokeTextEmbeddingApi(Resource):
             return jsonable_encoder(BaseBackwardsInvocationResponse(error=str(e)))
 
 
+@inner_api_ns.route("/invoke/multimodal-embedding")
+class PluginInvokeMultimodalEmbeddingApi(Resource):
+    @get_user_tenant
+    @setup_required
+    @plugin_inner_api_only
+    @plugin_data(payload_type=RequestInvokeMultimodalEmbedding)
+    @inner_api_ns.doc("plugin_invoke_multimodal_embedding")
+    @inner_api_ns.doc(description="Invoke multimodal embedding models through Dify model management")
+    @inner_api_ns.doc(
+        responses={
+            200: "Multimodal embedding successful",
+            401: "Unauthorized - invalid API key",
+            404: "Service not available",
+        }
+    )
+    def post(self, user_model: Account | EndUser, tenant_model: Tenant, payload: RequestInvokeMultimodalEmbedding):
+        try:
+            return jsonable_encoder(
+                BaseBackwardsInvocationResponse(
+                    data=PluginModelBackwardsInvocation.invoke_multimodal_embedding(
+                        user_id=user_model.id,
+                        tenant=tenant_model,
+                        payload=payload,
+                    )
+                )
+            )
+        except Exception as e:
+            return jsonable_encoder(BaseBackwardsInvocationResponse(error=str(e)))
+
+
 @inner_api_ns.route("/invoke/rerank")
 class PluginInvokeRerankApi(Resource):
     @get_user_tenant
@@ -144,6 +178,70 @@ class PluginInvokeRerankApi(Resource):
             return jsonable_encoder(BaseBackwardsInvocationResponse(error=str(e)))
 
 
+@inner_api_ns.route("/invoke/model-catalog")
+class PluginModelCatalogApi(Resource):
+    @get_user_tenant
+    @setup_required
+    @plugin_inner_api_only
+    @plugin_data(payload_type=RequestListModels)
+    @inner_api_ns.doc("plugin_model_catalog")
+    @inner_api_ns.doc(description="List tenant-active models managed by Dify")
+    @inner_api_ns.doc(
+        responses={
+            200: "Model catalog lookup successful",
+            401: "Unauthorized - invalid API key",
+            404: "Service not available",
+        }
+    )
+    def post(self, user_model: Account | EndUser, tenant_model: Tenant, payload: RequestListModels):
+        try:
+            return jsonable_encoder(
+                BaseBackwardsInvocationResponse(
+                    data=PluginModelBackwardsInvocation.list_models(
+                        tenant_id=tenant_model.id,
+                        user_id=user_model.id,
+                        payload=payload,
+                    )
+                )
+            )
+        except Exception as e:
+            return jsonable_encoder(BaseBackwardsInvocationResponse(error=str(e)))
+
+
+@inner_api_ns.route("/invoke/datasource")
+class PluginInvokeDatasourceApi(Resource):
+    """Invoke an installed datasource with credentials resolved inside Dify."""
+
+    @get_user_tenant
+    @setup_required
+    @plugin_inner_api_only
+    @plugin_data(payload_type=RequestInvokeDatasource)
+    @inner_api_ns.doc("plugin_invoke_datasource")
+    @inner_api_ns.doc(description="Invoke datasource plugins through Dify credential management")
+    @inner_api_ns.doc(
+        responses={
+            200: "Datasource invocation successful (streaming response)",
+            401: "Unauthorized - invalid API key",
+            404: "Datasource provider, datasource, or credential not found",
+        }
+    )
+    def post(
+        self,
+        user_model: Account | EndUser,
+        tenant_model: Tenant,
+        payload: RequestInvokeDatasource,
+    ):
+        response = PluginDatasourceBackwardsInvocation.invoke(
+            user_id=user_model.id,
+            tenant=tenant_model,
+            payload=payload,
+        )
+        return length_prefixed_response(
+            0xF,
+            PluginDatasourceBackwardsInvocation.convert_to_event_stream(response),
+        )
+
+
 @inner_api_ns.route("/invoke/tts")
 class PluginInvokeTTSApi(Resource):
     @get_user_tenant

api/controllers/service_api/__init__.py

@@ -38,6 +38,7 @@ from .dataset import (
 )
 from .dataset.rag_pipeline import rag_pipeline_workflow
 from .end_user import end_user
+from .knowledge_fs import resources as knowledge_fs_resources
 from .workspace import models
 
 __all__ = [
@@ -54,6 +55,7 @@ __all__ = [
     "hit_testing",
     "human_input_form",
     "index",
+    "knowledge_fs_resources",
     "message",
     "metadata",
     "models",

api/controllers/service_api/knowledge_fs/__init__.py

@@ -0,0 +1,5 @@
+"""KnowledgeFS-specific Service API authenticated by resource credentials."""
+
+from . import resources
+
+__all__ = ["resources"]

api/controllers/service_api/knowledge_fs/error.py

@@ -0,0 +1,49 @@
+"""Stable KnowledgeFS Service API error contract."""
+
+from libs.exception import BaseHTTPException
+
+
+class KnowledgeFSInvalidCredentialHTTPError(BaseHTTPException):
+    error_code = "knowledge_fs_invalid_credential"
+    description = "Invalid KnowledgeFS service credential."
+    code = 401
+
+
+class KnowledgeFSServiceOperationUnavailableHTTPError(BaseHTTPException):
+    error_code = "knowledge_fs_operation_unavailable"
+    description = "KnowledgeFS operation is not available."
+    code = 503
+
+
+class KnowledgeFSServiceUpstreamUnavailableHTTPError(BaseHTTPException):
+    error_code = "knowledge_fs_upstream_unavailable"
+    description = "KnowledgeFS is unavailable."
+    code = 502
+
+
+class KnowledgeFSServiceInvalidRequestHTTPError(BaseHTTPException):
+    error_code = "knowledge_fs_invalid_request"
+    description = "KnowledgeFS request is invalid."
+    code = 400
+
+
+class KnowledgeFSServiceRateLimitHTTPError(BaseHTTPException):
+    error_code = "knowledge_fs_rate_limit_exceeded"
+    description = "KnowledgeFS operation rate limit exceeded."
+    code = 429
+
+
+class KnowledgeFSServiceQuotaExceededHTTPError(BaseHTTPException):
+    error_code = "knowledge_fs_quota_exceeded"
+    description = "KnowledgeFS operation quota exceeded."
+    code = 403
+
+
+__all__ = [
+    "KnowledgeFSInvalidCredentialHTTPError",
+    "KnowledgeFSServiceInvalidRequestHTTPError",
+    "KnowledgeFSServiceOperationUnavailableHTTPError",
+    "KnowledgeFSServiceQuotaExceededHTTPError",
+    "KnowledgeFSServiceRateLimitHTTPError",
+    "KnowledgeFSServiceUpstreamUnavailableHTTPError",
+]

api/core/agent/base_agent_runner.py

@@ -14,7 +14,10 @@ from core.app.apps.base_app_queue_manager import AppQueueManager
 from core.app.apps.base_app_runner import AppRunner
 from core.app.entities.app_invoke_entities import (
     AgentChatAppGenerateEntity,
+    DifyRunContext,
+    InvokeFrom,
     ModelConfigWithCredentialsEntity,
+    UserFrom,
 )
 from core.app.file_access import DatabaseFileAccessController
 from core.callback_handler.agent_tool_callback_handler import DifyAgentCallbackHandler
@@ -148,6 +151,15 @@ class BaseAgentRunner(AppRunner):
             user_id=self.user_id,
             invoke_from=self.application_generate_entity.invoke_from,
         )
+        invoke_from = self.application_generate_entity.invoke_from
+        if isinstance(invoke_from, InvokeFrom):
+            tool_entity.runtime.dify_run_context = DifyRunContext(
+                tenant_id=self.tenant_id,
+                app_id=self.app_config.app_id,
+                user_id=self.user_id,
+                user_from=(UserFrom.ACCOUNT if invoke_from.runs_as_account() else UserFrom.END_USER),
+                invoke_from=invoke_from,
+            )
         assert tool_entity.entity.description
         message_tool = PromptMessageTool(
             name=tool.tool_name,

api/core/app/apps/agent_app/app_generator.py

@@ -540,6 +540,9 @@ class AgentAppGenerator(MessageBasedAppGenerator):
                 base_url=dify_config.AGENT_BACKEND_BASE_URL,
                 use_fake=dify_config.AGENT_BACKEND_USE_FAKE,
                 fake_scenario=dify_config.AGENT_BACKEND_FAKE_SCENARIO,
+                stream_read_timeout_seconds=dify_config.AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS,
+                stream_max_reconnects=dify_config.AGENT_BACKEND_STREAM_MAX_RECONNECTS,
+                stream_run_timeout_seconds=dify_config.AGENT_BACKEND_RUN_TIMEOUT_SECONDS,
             ),
             event_adapter=AgentBackendRunEventAdapter(),
             session_store=AgentAppRuntimeSessionStore(),

api/core/app/apps/agent_app/app_runner.py

@@ -941,48 +941,64 @@ class AgentAppRunner:
             if pending_text:
                 persist_answer_text(pending_text)
 
-        for public_event in self._agent_backend_client.stream_events(run_id):
-            if queue_manager.is_stopped():
-                flush_pending_agent_message_text()
-                self._cancel_run(run_id)
-                raise GenerateTaskStoppedError()
-            for internal_event in self._event_adapter.adapt(public_event):
+        try:
+            public_events = self._agent_backend_client.stream_events(
+                run_id,
+                should_stop=queue_manager.is_stopped,
+            )
+            for public_event in public_events:
                 if queue_manager.is_stopped():
                     flush_pending_agent_message_text()
                     self._cancel_run(run_id)
                     raise GenerateTaskStoppedError()
-                if internal_event.type in (
-                    AgentBackendInternalEventType.RUN_STARTED,
-                    AgentBackendInternalEventType.STREAM_EVENT,
-                    AgentBackendInternalEventType.AGENT_MESSAGE_DELTA,
-                ):
-                    if isinstance(internal_event, AgentBackendAgentMessageDeltaInternalEvent):
-                        debounced_delta = text_delta_debouncer.push(internal_event.delta)
-                        if debounced_delta:
-                            persist_answer_text(debounced_delta)
-                        continue
-
-                    if isinstance(internal_event, AgentBackendStreamInternalEvent):
+                for internal_event in self._event_adapter.adapt(public_event):
+                    if queue_manager.is_stopped():
                         flush_pending_agent_message_text()
-                        try:
-                            process_recorder.handle_stream_event(internal_event)
-                        except Exception:
-                            db.session.rollback()
-                            logger.warning(
-                                "Failed to persist Agent App process event: run_id=%s message_id=%s event_kind=%s",
-                                run_id,
-                                message_id,
-                                internal_event.event_kind,
-                                exc_info=True,
-                            )
+                        self._cancel_run(run_id)
+                        raise GenerateTaskStoppedError()
+                    if internal_event.type in (
+                        AgentBackendInternalEventType.RUN_STARTED,
+                        AgentBackendInternalEventType.STREAM_EVENT,
+                        AgentBackendInternalEventType.AGENT_MESSAGE_DELTA,
+                    ):
+                        if isinstance(internal_event, AgentBackendAgentMessageDeltaInternalEvent):
+                            debounced_delta = text_delta_debouncer.push(internal_event.delta)
+                            if debounced_delta:
+                                persist_answer_text(debounced_delta)
+                            continue
+
+                        if isinstance(internal_event, AgentBackendStreamInternalEvent):
+                            flush_pending_agent_message_text()
+                            try:
+                                process_recorder.handle_stream_event(internal_event)
+                            except Exception:
+                                db.session.rollback()
+                                logger.warning(
+                                    "Failed to persist Agent App process event: run_id=%s message_id=%s event_kind=%s",
+                                    run_id,
+                                    message_id,
+                                    internal_event.event_kind,
+                                    exc_info=True,
+                                )
+                            continue
                         continue
-                    continue
-                flush_pending_agent_message_text()
-                terminal = internal_event
-                break
-            if terminal is not None:
-                break
+                    flush_pending_agent_message_text()
+                    terminal = internal_event
+                    break
+                if terminal is not None:
+                    break
+        except GenerateTaskStoppedError:
+            raise
+        except Exception as error:
+            flush_pending_agent_message_text()
+            self._cancel_run(run_id)
+            if queue_manager.is_stopped():
+                raise GenerateTaskStoppedError() from error
+            raise
         flush_pending_agent_message_text()
+        if queue_manager.is_stopped():
+            self._cancel_run(run_id)
+            raise GenerateTaskStoppedError()
         return terminal, process_recorder
 
     def _cancel_run(self, run_id: str) -> None:

api/core/app/apps/agent_app/runtime_request_builder.py

@@ -159,6 +159,7 @@ class AgentAppRuntimeRequestBuilder:
                     user_from=cast(DifyExecutionContextUserFrom, context.dify_context.user_from.value),
                     invoke_from=cast(DifyExecutionContextInvokeFrom, context.dify_context.invoke_from.value),
                     agent_mode="agent_app",
+                    trace_id=context.dify_context.trace_session_id,
                 ),
                 # ENG-616: expand slash-menu mention tokens to canonical names so
                 # no frontend-internal {{#…#}} marker ever reaches the model.

api/core/app/apps/base_app_queue_manager.py

@@ -21,6 +21,7 @@ from core.app.entities.queue_entities import (
     WorkflowQueueMessage,
 )
 from extensions.ext_redis import redis_client
+from graphon.graph_engine.manager import GraphEngineManager
 from graphon.runtime import GraphRuntimeState
 
 logger = logging.getLogger(__name__)
@@ -51,6 +52,9 @@ class AppQueueManager(ABC):
         self._graph_runtime_state: GraphRuntimeState | None = None
         self._stopped_cache: TTLCache[tuple, bool] = TTLCache(maxsize=1, ttl=1)
         self._cache_lock = threading.Lock()
+        self._execution_terminal = threading.Event()
+        self._abort_sent = threading.Event()
+        self._lifecycle_lock = threading.Lock()
 
     def listen(self):
         """
@@ -59,7 +63,7 @@ class AppQueueManager(ABC):
         """
         # wait for APP_MAX_EXECUTION_TIME seconds to stop listen
         listen_timeout = dify_config.APP_MAX_EXECUTION_TIME
-        start_time = time.time()
+        start_time = time.monotonic()
         last_ping_time: int | float = 0
         try:
             while True:
@@ -72,8 +76,14 @@ class AppQueueManager(ABC):
                 except queue.Empty:
                     continue
                 finally:
-                    elapsed_time = time.time() - start_time
-                    if elapsed_time >= listen_timeout or self._is_stopped():
+                    elapsed_time = time.monotonic() - start_time
+                    timed_out = elapsed_time >= listen_timeout
+                    manually_stopped = self._is_stopped()
+                    if not self._execution_terminal.is_set() and (timed_out or manually_stopped):
+                        reason = (
+                            f"App execution exceeded {listen_timeout} seconds" if timed_out else "App task was stopped"
+                        )
+                        self._abort_execution(reason)
                         # publish two messages to make sure the client can receive the stop signal
                         # and stop listening after the stop signal processed
                         self.publish(
@@ -84,16 +94,33 @@ class AppQueueManager(ABC):
                         self.publish(QueuePingEvent(), PublishFrom.TASK_PIPELINE)
                         last_ping_time = elapsed_time // 10
         finally:
+            if not self._execution_terminal.is_set():
+                self._abort_execution("Client response stream closed before app execution completed")
             self._graph_runtime_state = None  # Release reference once consumers finish or close the generator.
 
-    def stop_listen(self):
+    def stop_listen(self, *, execution_terminal: bool = False):
         """
         Stop listen to queue
         :return:
         """
+        if execution_terminal:
+            self._execution_terminal.set()
         self._clear_task_belong_cache()
         self._q.put(None)
 
+    def _abort_execution(self, reason: str) -> None:
+        """Propagate response timeout/disconnect to legacy and GraphEngine runners."""
+        with self._lifecycle_lock:
+            if self._execution_terminal.is_set() or self._abort_sent.is_set():
+                return
+            self._abort_sent.set()
+
+        try:
+            self.set_stop_flag_no_user_check(self._task_id)
+            GraphEngineManager(redis_client).send_stop_command(self._task_id, reason=reason)
+        except Exception:
+            logger.exception("Failed to abort app execution for task %s", self._task_id)
+
     def _clear_task_belong_cache(self) -> None:
         """
         Remove the task belong cache key once listening is finished.

api/core/app/apps/message_based_app_queue_manager.py

@@ -45,7 +45,7 @@ class MessageBasedAppQueueManager(AppQueueManager):
         if isinstance(
             event, QueueStopEvent | QueueErrorEvent | QueueMessageEndEvent | QueueAdvancedChatMessageEndEvent
         ):
-            self.stop_listen()
+            self.stop_listen(execution_terminal=True)
 
         if pub_from == PublishFrom.APPLICATION_MANAGER and self._is_stopped():
             if self._app_mode == AppMode.ADVANCED_CHAT.value:

api/core/app/apps/pipeline/pipeline_queue_manager.py

@@ -42,7 +42,7 @@ class PipelineQueueManager(AppQueueManager):
             | QueueWorkflowFailedEvent
             | QueueWorkflowPartialSuccessEvent,
         ):
-            self.stop_listen()
+            self.stop_listen(execution_terminal=True)
 
         if pub_from == PublishFrom.APPLICATION_MANAGER and self._is_stopped():
             raise GenerateTaskStoppedError()

api/core/app/apps/workflow/app_queue_manager.py

@@ -41,4 +41,4 @@ class WorkflowAppQueueManager(AppQueueManager):
             | QueueWorkflowFailedEvent
             | QueueWorkflowPartialSuccessEvent,
         ):
-            self.stop_listen()
+            self.stop_listen(execution_terminal=True)

api/core/app/apps/workflow_app_runner.py

@@ -26,6 +26,7 @@ from core.app.entities.queue_entities import (
     QueueNodeSucceededEvent,
     QueueReasoningChunkEvent,
     QueueRetrieverResourcesEvent,
+    QueueStopEvent,
     QueueTextChunkEvent,
     QueueWorkflowFailedEvent,
     QueueWorkflowPartialSuccessEvent,
@@ -424,7 +425,12 @@ class WorkflowBasedAppRunner:
                     QueueWorkflowFailedEvent(error=event.error, exceptions_count=event.exceptions_count)
                 )
             case GraphRunAbortedEvent():
-                self._publish_event(QueueWorkflowFailedEvent(error=event.reason or "Unknown error", exceptions_count=0))
+                self._publish_event(
+                    QueueStopEvent(
+                        stopped_by=QueueStopEvent.StopBy.USER_MANUAL,
+                        reason=event.reason or "Workflow execution aborted",
+                    )
+                )
             case GraphRunPausedEvent():
                 runtime_state = workflow_entry.graph_engine.graph_runtime_state
                 paused_nodes = runtime_state.get_paused_nodes()

api/core/app/entities/queue_entities.py

@@ -500,11 +500,15 @@ class QueueStopEvent(AppQueueEvent):
 
     event: QueueEvent = QueueEvent.STOP
     stopped_by: StopBy
+    reason: str | None = None
 
     def get_stop_reason(self) -> str:
         """
         To stop reason
         """
+        if self.reason:
+            return self.reason
+
         reason_mapping = {
             QueueStopEvent.StopBy.USER_MANUAL: "Stopped by user.",
             QueueStopEvent.StopBy.ANNOTATION_REPLY: "Stopped by annotation reply.",

api/core/datasource/__base/datasource_provider.py

@@ -38,6 +38,11 @@ class DatasourcePluginProviderController(ABC):
         ):
             raise ToolProviderCredentialValidationError("Invalid credentials")
 
+    def validate_credentials(self, user_id: str, credentials: dict[str, Any]) -> None:
+        """Validate credential shape and value against this installed provider declaration."""
+        self.validate_credentials_format(credentials)
+        self._validate_credentials(user_id, credentials)
+
     @property
     def provider_type(self) -> DatasourceProviderType:
         """

api/core/helper/ssrf_proxy.py

@@ -47,6 +47,24 @@ class MaxRetriesExceededError(ValueError):
     pass
 
 
+class ResponseLimitError(ValueError):
+    """Base error for responses that cannot be safely bounded."""
+
+    pass
+
+
+class ResponseTooLargeError(ResponseLimitError):
+    """Raised when an identity response exceeds the configured byte limit."""
+
+    pass
+
+
+class UnsupportedResponseEncodingError(ResponseLimitError):
+    """Raised when response encoding prevents safe decoded-size enforcement."""
+
+    pass
+
+
 request_error = httpx.RequestError
 max_retries_exceeded_error = MaxRetriesExceededError
 
@@ -142,7 +160,31 @@ def _inject_trace_headers(headers: Headers | None) -> Headers:
     return headers
 
 
-def make_request(method: str, url: str, max_retries: int = SSRF_DEFAULT_MAX_RETRIES, **kwargs: Any) -> httpx.Response:
+def make_request(
+    method: str,
+    url: str,
+    max_retries: int = SSRF_DEFAULT_MAX_RETRIES,
+    stream_response: bool = False,
+    **kwargs: Any,
+) -> httpx.Response:
+    """Send one SSRF-protected request with optional streaming.
+
+    Args:
+        method: HTTP method sent through the configured SSRF client.
+        url: Absolute request URL.
+        max_retries: Number of retry attempts after the initial request.
+        stream_response: Return an open streaming response that the caller must close.
+        **kwargs: Additional keyword arguments forwarded to ``httpx.Client``.
+
+    Returns:
+        A buffered response, or an open response when ``stream_response`` is true.
+
+    Raises:
+        ToolSSRFError: The configured SSRF proxy rejects the destination.
+        MaxRetriesExceededError: All configured request attempts fail.
+        httpx.RequestError: A request fails while retries are disabled.
+        ValueError: The SSL verification option or request headers are invalid.
+    """
     # Convert requests-style allow_redirects to httpx-style follow_redirects
     if "allow_redirects" in kwargs:
         allow_redirects = kwargs.pop("allow_redirects")
@@ -175,6 +217,11 @@ def make_request(method: str, url: str, max_retries: int = SSRF_DEFAULT_MAX_RETR
     # When using a forward proxy, httpx may override the Host header based on the URL.
     # We extract and preserve any explicitly set Host header to support virtual hosting.
     user_provided_host = _get_user_provided_host_header(headers)
+    send_kwargs: dict[str, Any] = {}
+    if "auth" in kwargs:
+        send_kwargs["auth"] = kwargs.pop("auth")
+    if "follow_redirects" in kwargs:
+        send_kwargs["follow_redirects"] = kwargs.pop("follow_redirects")
 
     retries = 0
     while retries <= max_retries:
@@ -185,7 +232,11 @@ def make_request(method: str, url: str, max_retries: int = SSRF_DEFAULT_MAX_RETR
             if user_provided_host is not None:
                 headers["host"] = user_provided_host
             kwargs["headers"] = headers
-            response = client.request(method=method, url=url, **kwargs)
+            request = client.build_request(method=method, url=url, **kwargs)
+            if stream_response:
+                response = client.send(request, stream=True, **send_kwargs)
+            else:
+                response = client.send(request, **send_kwargs)
 
             # Check for SSRF protection by Squid proxy
             if response.status_code in (401, 403):
@@ -195,6 +246,7 @@ def make_request(method: str, url: str, max_retries: int = SSRF_DEFAULT_MAX_RETR
 
                 # Squid typically identifies itself in Server or Via headers
                 if "squid" in server_header or "squid" in via_header:
+                    response.close()
                     raise ToolSSRFError(
                         f"Access to '{url}' was blocked by SSRF protection. "
                         f"The URL may point to a private or local network address. "
@@ -208,6 +260,7 @@ def make_request(method: str, url: str, max_retries: int = SSRF_DEFAULT_MAX_RETR
                     response.status_code,
                     url,
                 )
+                response.close()
 
         except httpx.RequestError as e:
             logger.warning("Request to URL %s failed on attempt %s: %s", url, retries + 1, e)
@@ -220,6 +273,42 @@ def make_request(method: str, url: str, max_retries: int = SSRF_DEFAULT_MAX_RETR
     raise MaxRetriesExceededError(f"Reached maximum retries ({max_retries}) for URL {url}")
 
 
+def buffer_response(response: httpx.Response, *, max_response_bytes: int) -> httpx.Response:
+    """Consume one open identity response under a decoded byte limit and close its stream."""
+    if max_response_bytes <= 0:
+        raise ValueError("max_response_bytes must be positive")
+
+    try:
+        content_encoding = response.headers.get("content-encoding", "identity").strip().lower()
+        if content_encoding not in {"", "identity"}:
+            raise UnsupportedResponseEncodingError(f"content encoding {content_encoding} cannot be safely bounded")
+        content = bytearray()
+        for chunk in response.iter_bytes():
+            if len(content) + len(chunk) > max_response_bytes:
+                raise ResponseTooLargeError(f"response exceeded {max_response_bytes} bytes")
+            content.extend(chunk)
+        decoded_headers = {
+            name: value
+            for name, value in response.headers.items()
+            if name.lower() not in {"content-encoding", "content-length", "transfer-encoding"}
+        }
+        try:
+            request = response.request
+        except RuntimeError:
+            request = None
+        return httpx.Response(
+            response.status_code,
+            headers=decoded_headers,
+            content=bytes(content),
+            request=request,
+            extensions=response.extensions,
+            history=response.history,
+            default_encoding=response.default_encoding,
+        )
+    finally:
+        response.close()
+
+
 def get(url: str, max_retries: int = SSRF_DEFAULT_MAX_RETRIES, **kwargs: Any) -> httpx.Response:
     return make_request("GET", url, max_retries=max_retries, **kwargs)
 

api/core/llm_generator/llm_generator.py

@@ -403,55 +403,6 @@ class LLMGenerator:
             return ""
         return "\n\n".join(sections) + "\n\n"
 
-    @classmethod
-    def classify_workflow_mode(
-        cls,
-        tenant_id: str,
-        instruction: str,
-        model_config: ModelConfig,
-    ) -> Literal["workflow", "advanced-chat"]:
-        """Classify a free-text instruction into a concrete app mode.
-
-        One tiny LLM call using the model the user already picked (so no extra
-        provider setup is needed). Parsed leniently; defaults to
-        ``advanced-chat`` on anything unexpected or any error, so a
-        ``mode="auto"`` request never blocks generation. NEVER raises.
-        """
-        default_mode: Literal["workflow", "advanced-chat"] = "advanced-chat"
-        try:
-            model_instance = ModelManager.for_tenant(tenant_id=tenant_id).get_model_instance(
-                tenant_id=tenant_id,
-                model_type=ModelType.LLM,
-                provider=model_config.provider,
-                model=model_config.name,
-            )
-            prompt_messages: list[PromptMessage] = [
-                UserPromptMessage(
-                    content=(
-                        "Reply with exactly one word: 'workflow' (one-shot automation, no chat) "
-                        "or 'advanced-chat' (conversational multi-turn). "
-                        f"Instruction: {instruction.strip()}"
-                    )
-                ),
-            ]
-            response: LLMResult = model_instance.invoke_llm(
-                prompt_messages=prompt_messages,
-                model_parameters={"max_tokens": 4, "temperature": 0},
-                stream=False,
-            )
-            text = (response.message.get_text_content() or "").strip().lower()
-        except Exception:
-            logger.info("Workflow mode classification failed; defaulting to %s", default_mode, exc_info=True)
-            return default_mode
-
-        # Lenient parse: an affirmative "workflow" wins; everything else
-        # (including a truncated / empty / garbled reply) falls back to the
-        # conversational default. "advanced-chat" needs no positive match
-        # because it IS the default.
-        if "workflow" in text:
-            return "workflow"
-        return default_mode
-
     @classmethod
     def generate_rule_config(cls, tenant_id: str, args: RuleGeneratePayload):
         output_parser = RuleConfigGeneratorOutputParser()

api/core/plugin/backwards_invocation/datasource.py

@@ -0,0 +1,110 @@
+"""Datasource backward invocation through Dify's tenant-bound runtime.
+
+This module is the internal service boundary used by trusted callers such as
+KnowledgeFS. It resolves installed provider declarations and Dify-owned
+credential references before reaching ``PluginDatasourceManager``; callers
+must never provide raw datasource credentials or a plugin-daemon API key.
+"""
+
+from collections.abc import Generator
+from typing import Any, cast
+
+from pydantic import BaseModel
+
+from core.datasource.datasource_manager import DatasourceManager
+from core.datasource.entities.datasource_entities import (
+    OnlineDriveBrowseFilesRequest,
+    OnlineDriveDownloadFileRequest,
+)
+from core.datasource.online_document.online_document_plugin import OnlineDocumentDatasourcePlugin
+from core.datasource.online_drive.online_drive_plugin import OnlineDriveDatasourcePlugin
+from core.datasource.website_crawl.website_crawl_plugin import WebsiteCrawlDatasourcePlugin
+from core.plugin.backwards_invocation.base import BaseBackwardsInvocation
+from core.plugin.entities.request import RequestInvokeDatasource
+from models.account import Tenant
+from models.provider_ids import DatasourceProviderID
+from services.datasource_provider_service import DatasourceProviderService
+
+
+class PluginDatasourceBackwardsInvocation(BaseBackwardsInvocation):
+    """Resolve and invoke a datasource without exposing credential material to the caller."""
+
+    @classmethod
+    def invoke(
+        cls,
+        *,
+        user_id: str,
+        tenant: Tenant,
+        payload: RequestInvokeDatasource,
+    ) -> Generator[BaseModel | dict[str, Any], None, None]:
+        """Yield datasource messages for one validated inner-runtime request."""
+        provider_id = DatasourceProviderID(payload.provider)
+        canonical_provider_id = str(provider_id)
+        controller = DatasourceManager.get_datasource_plugin_provider(
+            provider_id=canonical_provider_id,
+            tenant_id=tenant.id,
+            datasource_type=payload.datasource_type,
+        )
+        if controller.entity.provider_type != payload.datasource_type:
+            raise ValueError("Datasource provider type mismatch")
+
+        # Resolving the datasource from the installed declaration prevents a caller
+        # from dispatching an arbitrary datasource name under a valid plugin ID.
+        runtime = controller.get_datasource(payload.datasource)
+        credentials = DatasourceProviderService().get_datasource_credentials(
+            tenant_id=tenant.id,
+            provider=provider_id.provider_name,
+            plugin_id=provider_id.plugin_id,
+            credential_id=payload.credential_id,
+        )
+        if controller.need_credentials and not credentials:
+            raise ValueError("Datasource credential not found")
+
+        if payload.operation == "validate_credentials":
+            controller.validate_credentials(user_id=user_id, credentials=credentials)
+            yield {"result": True}
+            return
+
+        runtime.runtime.credentials = credentials
+        provider_type = runtime.datasource_provider_type()
+
+        match payload.operation:
+            case "get_website_crawl":
+                website = cast(WebsiteCrawlDatasourcePlugin, runtime)
+                yield from website.get_website_crawl(
+                    user_id=user_id,
+                    datasource_parameters=payload.datasource_parameters,
+                    provider_type=provider_type,
+                )
+            case "get_online_document_pages":
+                document = cast(OnlineDocumentDatasourcePlugin, runtime)
+                yield from document.get_online_document_pages(
+                    user_id=user_id,
+                    datasource_parameters=payload.datasource_parameters,
+                    provider_type=provider_type,
+                )
+            case "get_online_document_page_content":
+                if payload.page is None:
+                    raise ValueError("Online-document page input is required")
+                document = cast(OnlineDocumentDatasourcePlugin, runtime)
+                yield from document.get_online_document_page_content(
+                    user_id=user_id,
+                    datasource_parameters=payload.page,
+                    provider_type=provider_type,
+                )
+            case "online_drive_browse_files":
+                drive = cast(OnlineDriveDatasourcePlugin, runtime)
+                yield from drive.online_drive_browse_files(
+                    user_id=user_id,
+                    request=OnlineDriveBrowseFilesRequest.model_validate(payload.request),
+                    provider_type=provider_type,
+                )
+            case "online_drive_download_file":
+                drive = cast(OnlineDriveDatasourcePlugin, runtime)
+                yield from drive.online_drive_download_file(
+                    user_id=user_id,
+                    request=OnlineDriveDownloadFileRequest.model_validate(payload.request),
+                    provider_type=provider_type,
+                )
+            case _:
+                raise ValueError(f"Unsupported datasource operation: {payload.operation}")

api/core/plugin/backwards_invocation/model.py

@@ -1,22 +1,31 @@
 import tempfile
 from binascii import hexlify, unhexlify
-from collections.abc import Generator
+from collections.abc import Generator, Mapping
+from enum import Enum
 from typing import Any
 
+from pydantic import BaseModel
+
 from core.app.llm import deduct_llm_quota
 from core.llm_generator.output_parser.structured_output import invoke_llm_with_structured_output
 from core.model_manager import ModelManager
 from core.plugin.backwards_invocation.base import BaseBackwardsInvocation
 from core.plugin.entities.request import (
+    InvokableModelCatalogItem,
+    InvokableModelCatalogPage,
     RequestInvokeLLM,
     RequestInvokeLLMWithStructuredOutput,
     RequestInvokeModeration,
+    RequestInvokeMultimodalEmbedding,
     RequestInvokeRerank,
     RequestInvokeSpeech2Text,
     RequestInvokeSummary,
     RequestInvokeTextEmbedding,
     RequestInvokeTTS,
+    RequestListModels,
 )
+from core.plugin.impl.model_runtime_factory import create_plugin_provider_manager
+from core.plugin.plugin_service import PluginService
 from core.tools.entities.tool_entities import ToolProviderType
 from core.tools.utils.model_invocation_utils import ModelInvocationUtils
 from graphon.model_runtime.entities.llm_entities import (
@@ -33,6 +42,20 @@ from graphon.model_runtime.entities.message_entities import (
 )
 from graphon.model_runtime.entities.model_entities import ModelType
 from models.account import Tenant
+from models.provider_ids import ModelProviderID
+
+
+def _json_compatible(value: Any) -> Any:
+    """Convert model-runtime metadata into stable JSON-compatible values."""
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Mapping):
+        return {str(_json_compatible(key)): _json_compatible(child) for key, child in value.items()}
+    if isinstance(value, list | tuple | set):
+        return [_json_compatible(child) for child in value]
+    return value
 
 
 class PluginModelBackwardsInvocation(BaseBackwardsInvocation):
@@ -183,7 +206,30 @@ class PluginModelBackwardsInvocation(BaseBackwardsInvocation):
         )
 
         # invoke model
-        response = model_instance.invoke_text_embedding(texts=payload.texts)
+        response = model_instance.invoke_text_embedding(texts=payload.texts, input_type=payload.input_type)
+
+        return response
+
+    @classmethod
+    def invoke_multimodal_embedding(
+        cls,
+        user_id: str,
+        tenant: Tenant,
+        payload: RequestInvokeMultimodalEmbedding,
+    ):
+        """Invoke multimodal embedding through the tenant-bound model instance."""
+        model_instance = cls._get_bound_model_instance(
+            tenant_id=tenant.id,
+            user_id=user_id,
+            provider=payload.provider,
+            model_type=payload.model_type,
+            model=payload.model,
+        )
+
+        response = model_instance.invoke_multimodal_embedding(
+            multimodel_documents=[document.model_dump(exclude_none=True) for document in payload.documents],
+            input_type=payload.input_type,
+        )
 
         return response
 
@@ -210,6 +256,67 @@ class PluginModelBackwardsInvocation(BaseBackwardsInvocation):
 
         return response
 
+    @classmethod
+    def list_models(
+        cls,
+        tenant_id: str,
+        user_id: str,
+        payload: RequestListModels,
+    ) -> InvokableModelCatalogPage:
+        """List only models that are active for the tenant's Dify configuration."""
+        provider_manager = create_plugin_provider_manager(tenant_id=tenant_id, user_id=user_id)
+        active_models = provider_manager.get_configurations(tenant_id).get_models(
+            model_type=payload.model_type,
+            only_active=True,
+        )
+
+        installed_identities: dict[str, str] = {}
+        for plugin in PluginService.list(tenant_id):
+            existing = installed_identities.get(plugin.plugin_id)
+            if existing is not None and existing != plugin.plugin_unique_identifier:
+                raise ValueError(f"Ambiguous installed identity for model plugin {plugin.plugin_id}")
+            installed_identities[plugin.plugin_id] = plugin.plugin_unique_identifier
+
+        requested_provider = str(ModelProviderID(payload.provider)) if payload.provider else None
+        matched_models = [
+            model
+            for model in active_models
+            if (requested_provider is None or model.provider.provider == requested_provider)
+            and (payload.model is None or model.model == payload.model)
+        ]
+        matched_models.sort(key=lambda model: (model.provider.provider, model.model))
+
+        page_models = matched_models[payload.offset : payload.offset + payload.limit]
+        items: list[InvokableModelCatalogItem] = []
+        for model in page_models:
+            provider_id = ModelProviderID(model.provider.provider)
+            unique_identifier = installed_identities.get(provider_id.plugin_id)
+            if unique_identifier is None:
+                raise ValueError(f"Installed identity not found for active model plugin {provider_id.plugin_id}")
+            items.append(
+                InvokableModelCatalogItem(
+                    plugin_id=provider_id.plugin_id,
+                    plugin_unique_identifier=unique_identifier,
+                    provider=provider_id.provider_name,
+                    model=model.model,
+                    model_type=model.model_type,
+                    capabilities={
+                        "deprecated": model.deprecated,
+                        "features": _json_compatible(model.features or []),
+                        "fetchFrom": _json_compatible(model.fetch_from),
+                        "modelProperties": _json_compatible(model.model_properties),
+                        "modelType": model.model_type.value,
+                        "status": _json_compatible(model.status),
+                    },
+                )
+            )
+
+        next_offset = payload.offset + len(page_models)
+        return InvokableModelCatalogPage(
+            items=items,
+            next_offset=next_offset if next_offset < len(matched_models) else None,
+        )
+
     @classmethod
     def invoke_tts(cls, user_id: str, tenant: Tenant, payload: RequestInvokeTTS):
         """

api/core/plugin/entities/request.py

@@ -6,6 +6,11 @@ from typing import Any, Literal
 from flask import Response
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
+from core.datasource.entities.datasource_entities import (
+    DatasourceProviderType,
+    GetOnlineDocumentPageContentRequest,
+)
+from core.entities.embedding_type import EmbeddingInputType
 from core.entities.provider_entities import BasicProviderConfig
 from core.plugin.utils.http_parser import deserialize_response
 from core.workflow.file_reference import is_canonical_file_reference
@@ -54,6 +59,61 @@ class RequestInvokeTool(BaseModel):
     credential_id: str | None = None
 
 
+DatasourceInvocationOperation = Literal[
+    "get_online_document_page_content",
+    "get_online_document_pages",
+    "get_website_crawl",
+    "online_drive_browse_files",
+    "online_drive_download_file",
+    "validate_credentials",
+]
+
+
+class RequestInvokeDatasource(BaseModel):
+    """Invoke one installed datasource using a Dify-owned credential reference.
+
+    Raw credentials are intentionally not part of this contract. ``tenant_id`` and
+    ``user_id`` are consumed by the inner-API request context, while the remaining
+    fields select an installed provider declaration and an operation-specific input.
+    """
+
+    tenant_id: str = Field(min_length=1, max_length=512)
+    user_id: str = Field(min_length=1, max_length=512)
+    provider: str = Field(min_length=1, max_length=768)
+    datasource: str = Field(min_length=1, max_length=256)
+    datasource_type: DatasourceProviderType
+    credential_id: str = Field(min_length=1, max_length=512)
+    operation: DatasourceInvocationOperation
+    datasource_parameters: dict[str, Any] = Field(default_factory=dict)
+    page: GetOnlineDocumentPageContentRequest | None = None
+    request: dict[str, Any] | None = None
+
+    model_config = ConfigDict(extra="forbid")
+
+    @model_validator(mode="after")
+    def validate_operation_payload(self) -> "RequestInvokeDatasource":
+        expected_type = {
+            "get_online_document_page_content": DatasourceProviderType.ONLINE_DOCUMENT,
+            "get_online_document_pages": DatasourceProviderType.ONLINE_DOCUMENT,
+            "get_website_crawl": DatasourceProviderType.WEBSITE_CRAWL,
+            "online_drive_browse_files": DatasourceProviderType.ONLINE_DRIVE,
+            "online_drive_download_file": DatasourceProviderType.ONLINE_DRIVE,
+            "validate_credentials": self.datasource_type,
+        }[self.operation]
+        if self.datasource_type != expected_type:
+            raise ValueError(f"{self.operation} requires datasource_type {expected_type.value}")
+
+        page_required = self.operation == "get_online_document_page_content"
+        if page_required != (self.page is not None):
+            raise ValueError("page is required only for get_online_document_page_content")
+
+        request_required = self.operation in {"online_drive_browse_files", "online_drive_download_file"}
+        if request_required != (self.request is not None):
+            raise ValueError("request is required only for online-drive operations")
+
+        return self
+
+
 class BaseRequestInvokeModel(BaseModel):
     provider: str
     model: str
@@ -115,6 +175,25 @@ class RequestInvokeTextEmbedding(BaseRequestInvokeModel):
 
     model_type: ModelType = ModelType.TEXT_EMBEDDING
     texts: list[str]
+    input_type: EmbeddingInputType = EmbeddingInputType.DOCUMENT
+
+
+class MultimodalEmbeddingDocument(BaseModel):
+    """A document accepted by a multimodal text-embedding model."""
+
+    content: str
+    content_type: str
+    file_id: str | None = None
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class RequestInvokeMultimodalEmbedding(BaseRequestInvokeModel):
+    """Request to invoke a multimodal text-embedding model."""
+
+    model_type: ModelType = ModelType.TEXT_EMBEDDING
+    documents: list[MultimodalEmbeddingDocument] = Field(min_length=1)
+    input_type: EmbeddingInputType = EmbeddingInputType.DOCUMENT
 
 
 class RequestInvokeRerank(BaseRequestInvokeModel):
@@ -125,8 +204,40 @@ class RequestInvokeRerank(BaseRequestInvokeModel):
     model_type: ModelType = ModelType.RERANK
     query: str
     docs: list[str]
-    score_threshold: float
-    top_n: int
+    score_threshold: float | None = None
+    top_n: int | None = None
+
+
+class RequestListModels(BaseModel):
+    """Tenant-scoped query for models that Dify can invoke."""
+
+    model_type: Literal[ModelType.LLM, ModelType.TEXT_EMBEDDING, ModelType.RERANK]
+    provider: str | None = None
+    model: str | None = None
+    offset: int = Field(default=0, ge=0)
+    limit: int = Field(default=50, ge=1, le=100)
+
+    model_config = ConfigDict(protected_namespaces=())
+
+
+class InvokableModelCatalogItem(BaseModel):
+    """Installed identity and active Dify capability metadata for one model."""
+
+    plugin_id: str
+    plugin_unique_identifier: str
+    provider: str
+    model: str
+    model_type: ModelType
+    capabilities: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = ConfigDict(protected_namespaces=())
+
+
+class InvokableModelCatalogPage(BaseModel):
+    """Offset page returned by the internal model catalog endpoint."""
+
+    items: list[InvokableModelCatalogItem] = Field(default_factory=list)
+    next_offset: int | None = None
 
 
 class RequestInvokeTTS(BaseRequestInvokeModel):

api/core/rbac/entities.py

@@ -10,6 +10,7 @@ class RBACResourceScope(StrEnum):
 
     APP = "app"
     DATASET = "dataset"
+    KNOWLEDGE_FS = "knowledge_space"
     WORKSPACE = "workspace"
 
 
@@ -57,6 +58,15 @@ class RBACPermission(StrEnum):
     DATASET_EXTERNAL_CONNECT = "dataset_external_connect"
     DATASET_IMPORT_EXPORT_DSL = "dataset_import_export_dsl"
 
+    KNOWLEDGE_FS_READ = "knowledge_space_read"
+    KNOWLEDGE_FS_CREATE = "knowledge_space_create"
+    KNOWLEDGE_FS_EDIT = "knowledge_space_edit"
+    KNOWLEDGE_FS_DELETE = "knowledge_space_delete"
+    KNOWLEDGE_FS_ACCESS_CONFIG = "knowledge_space_access_config"
+    KNOWLEDGE_FS_API_KEY_MANAGE = "knowledge_space_api_key_manage"
+    KNOWLEDGE_FS_DOCUMENT_WRITE = "knowledge_space_document_write"
+    KNOWLEDGE_FS_QUERY = "knowledge_space_query"
+
     WORKSPACE_MEMBER_MANAGE = "workspace_member_manage"
     WORKSPACE_ROLE_MANAGE = "workspace_role_manage"
     API_EXTENSION_MANAGE = "api_extension_manage"

api/core/tools/__base/tool_runtime.py

@@ -2,7 +2,7 @@ from typing import Any
 
 from pydantic import BaseModel, Field
 
-from core.app.entities.app_invoke_entities import InvokeFrom
+from core.app.entities.app_invoke_entities import DifyRunContext, InvokeFrom
 from core.plugin.entities.plugin_daemon import CredentialType
 from core.tools.entities.tool_entities import ToolInvokeFrom
 
@@ -20,6 +20,7 @@ class ToolRuntime(BaseModel):
     tool_id: str | None = None
     invoke_from: InvokeFrom | None = None
     tool_invoke_from: ToolInvokeFrom | None = None
+    dify_run_context: DifyRunContext | None = Field(default=None, exclude=True, repr=False)
     credentials: dict[str, Any] = Field(default_factory=dict)
     credential_type: CredentialType = Field(default=CredentialType.API_KEY)
     runtime_parameters: dict[str, Any] = Field(default_factory=dict)

api/core/tools/builtin_tool/_position.yaml

@@ -1,4 +1,5 @@
 - audio
 - code
+- knowledge_fs
 - time
 - webscraper

api/core/tools/builtin_tool/providers/knowledge_fs/_assets/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
+  <rect width="64" height="64" rx="14" fill="#155EEF"/>
+  <path d="M17 17h20c5.5 0 10 4.5 10 10v20H27c-5.5 0-10-4.5-10-10V17Z" fill="white" fill-opacity=".96"/>
+  <path d="M26 27h12M26 34h12M26 41h7" stroke="#155EEF" stroke-width="4" stroke-linecap="round"/>
+</svg>
+

api/core/tools/builtin_tool/providers/knowledge_fs/knowledge_fs.py

@@ -0,0 +1,9 @@
+from typing import Any, override
+
+from core.tools.builtin_tool.provider import BuiltinToolProviderController
+
+
+class KnowledgeFSProvider(BuiltinToolProviderController):
+    @override
+    def _validate_credentials(self, user_id: str, credentials: dict[str, Any]) -> None:
+        _ = (user_id, credentials)

api/core/tools/builtin_tool/providers/knowledge_fs/knowledge_fs.yaml

@@ -0,0 +1,13 @@
+identity:
+  author: Dify
+  name: knowledge_fs
+  label:
+    en_US: KnowledgeFS
+    zh_Hans: KnowledgeFS
+  description:
+    en_US: Run explicitly bound KnowledgeFS operations from an Agent or Workflow.
+    zh_Hans: 从 Agent 或 Workflow 执行显式绑定的 KnowledgeFS 操作。
+  icon: icon.svg
+  tags:
+    - rag
+

api/core/tools/builtin_tool/providers/knowledge_fs/tools/create_research_task.py

@@ -0,0 +1,60 @@
+from collections.abc import Generator
+from typing import Any, override
+
+from pydantic import ValidationError
+from sqlalchemy.orm import Session, sessionmaker
+
+from core.tools.builtin_tool.tool import BuiltinTool
+from core.tools.entities.tool_entities import ToolInvokeFrom, ToolInvokeMessage
+from core.tools.errors import ToolInvokeError
+from models.knowledge_fs import KnowledgeFSAppSpaceJoinType
+from services.knowledge_fs.app_execution_capability import KnowledgeResourceRef
+from services.knowledge_fs.product_dto import KnowledgeFSResearchTaskCreatePayload
+from services.knowledge_fs.runtime import create_knowledge_fs_runtime
+
+
+class KnowledgeFSCreateResearchTaskTool(BuiltinTool):
+    @override
+    def _invoke(
+        self,
+        session: Session,
+        user_id: str,
+        tool_parameters: dict[str, Any],
+        conversation_id: str | None = None,
+        app_id: str | None = None,
+        message_id: str | None = None,
+    ) -> Generator[ToolInvokeMessage, None, None]:
+        _ = (user_id, conversation_id, app_id, message_id)
+        run_context = self.runtime.dify_run_context
+        if run_context is None or self.runtime.tenant_id != run_context.tenant_id:
+            raise ToolInvokeError("KnowledgeFS requires a trusted Dify run context")
+        match self.runtime.tool_invoke_from:
+            case ToolInvokeFrom.AGENT:
+                caller_kind = KnowledgeFSAppSpaceJoinType.AGENT
+            case ToolInvokeFrom.WORKFLOW:
+                caller_kind = KnowledgeFSAppSpaceJoinType.WORKFLOW
+            case _:
+                raise ToolInvokeError("KnowledgeFS is only available to Agent and Workflow callers")
+
+        try:
+            resource = KnowledgeResourceRef.model_validate(tool_parameters.get("resource"))
+            payload_data: dict[str, object] = {
+                "query": tool_parameters.get("query"),
+            }
+            mode = tool_parameters.get("mode")
+            if mode:
+                payload_data["mode"] = mode
+            payload = KnowledgeFSResearchTaskCreatePayload.model_validate(payload_data)
+            runtime = create_knowledge_fs_runtime(sessionmaker(bind=session.get_bind(), expire_on_commit=False))
+            response = runtime.app_capabilities.create_research_task(
+                run_context=run_context,
+                caller_kind=caller_kind,
+                resource=resource,
+                payload=payload,
+            )
+        except ToolInvokeError:
+            raise
+        except (ValidationError, RuntimeError, ValueError) as exc:
+            raise ToolInvokeError(str(exc)) from exc
+
+        yield self.create_json_message(response.model_dump(mode="json", by_alias=True))

api/core/tools/builtin_tool/providers/knowledge_fs/tools/create_research_task.yaml

@@ -0,0 +1,75 @@
+identity:
+  name: create_research_task
+  author: Dify
+  label:
+    en_US: Create KnowledgeFS Research Task
+    zh_Hans: 创建 KnowledgeFS Research 任务
+description:
+  human:
+    en_US: Create a Research task in an explicitly bound KnowledgeFS space.
+    zh_Hans: 在显式绑定的 KnowledgeFS 空间中创建 Research 任务。
+  llm: Create a durable research task using an explicitly configured KnowledgeFS resource.
+parameters:
+  - name: resource
+    type: object
+    required: true
+    label:
+      en_US: KnowledgeFS resource
+      zh_Hans: KnowledgeFS 资源
+    human_description:
+      en_US: A typed KnowledgeFS control-space reference configured by the app author.
+      zh_Hans: 由应用作者配置的类型化 KnowledgeFS control-space 引用。
+    form: form
+    input_schema:
+      type: object
+      additionalProperties: false
+      properties:
+        kind:
+          type: string
+          const: knowledge_fs
+        control_space_id:
+          type: string
+          minLength: 1
+      required:
+        - kind
+        - control_space_id
+  - name: query
+    type: string
+    required: true
+    label:
+      en_US: Research query
+      zh_Hans: Research 查询
+    human_description:
+      en_US: The question the Research task should investigate.
+      zh_Hans: Research 任务需要调查的问题。
+    llm_description: The question to investigate with KnowledgeFS.
+    form: llm
+  - name: mode
+    type: select
+    required: false
+    label:
+      en_US: Mode
+      zh_Hans: 模式
+    human_description:
+      en_US: Optional KnowledgeFS retrieval mode.
+      zh_Hans: 可选的 KnowledgeFS 检索模式。
+    llm_description: Optional retrieval mode. Use auto unless the task needs a specific mode.
+    form: llm
+    options:
+      - value: auto
+        label:
+          en_US: Auto
+          zh_Hans: 自动
+      - value: fast
+        label:
+          en_US: Fast
+          zh_Hans: 快速
+      - value: deep
+        label:
+          en_US: Deep
+          zh_Hans: 深度
+      - value: research
+        label:
+          en_US: Research
+          zh_Hans: Research
+

api/core/workflow/generator/__init__.py

@@ -4,12 +4,12 @@ Workflow generator package.
 Generates a Dify workflow graph (nodes, edges, viewport) from a natural-language
 instruction. Intended for the cmd+k `/create` slash command's preview/apply flow.
 
-Pipeline (slim, single-shot variant):
+Pipeline:
 
     runner.WorkflowGenerator.generate_workflow_graph(...)
-        ├── planner_prompts: short LLM call → high-level node plan
-        └── builder_prompts: structured-output LLM call → full graph JSON
-            └── postprocess: fill defaults, auto-layout viewport, sanity-check edges
+        ├── planner_prompts: short LLM call → node and edge plan
+        ├── node_builder_prompts: bounded parallel calls → semantic node configs
+        └── postprocess: assemble wrappers, auto-layout, validate graph
 
 The runner is pure domain logic; ``WorkflowGeneratorService`` (in ``services/``)
 owns the model-manager dependency and is what controllers call.

api/core/workflow/generator/prompts/builder_prompts.py

@@ -1,19 +1,4 @@
-"""
-Builder prompts.
-
-The builder is the second step of the slim planner→builder pipeline. It takes
-the planner's high-level node list and emits the *full* graph JSON consumed by
-``WorkflowService.sync_draft_workflow``.
-
-The builder owns: node configuration (prompts, code, headers, etc.), edge wiring,
-handle ids ("source"/"target"), positions, and the viewport. It is the only
-prompt that needs to know the concrete shape of each node type — keep its
-examples accurate or the LLM will invent fields.
-"""
-
-import json
-from collections.abc import Iterable
-from typing import Any
+"""Compact semantic configuration references for workflow node builders."""
 
 # Per-node-type configuration cheatsheet.
 #
@@ -23,50 +8,9 @@ from typing import Any
 # both ``WorkflowService.sync_draft_workflow``'s structural checks and the
 # runtime entity validation each node performs when the workflow runs.
 #
-# The cheatsheet is assembled DYNAMICALLY per request: the planner decides
-# which node types the workflow needs, and ``build_node_config_cheatsheet``
-# stitches together only the snippets for those types (plus the always-needed
-# wrapper / shared-field / edge-handle preamble, and the containers section
-# when an iteration / loop is planned). This keeps the builder prompt tight —
-# a 3-node summariser no longer carries the schema for 12 unrelated node
-# types — and lets each snippet document its FULL schema (e.g. a "file" start
-# variable's required ``allowed_file_types``) without bloating every prompt.
-#
-# The postprocessor in ``runner.py`` fills missing wrapper fields (``type``,
-# ``positionAbsolute``, ``width``, ``height``, ``sourcePosition`` /
-# ``targetPosition``, edge ``data.sourceType`` / ``data.targetType``), so the
-# LLM only needs to emit semantically meaningful fields.
-
-# Always-included preamble: the node/edge wrapper shape and the shared
-# ``data`` fields that apply to every node type, plus the "## Per type" header
-# the per-type snippets slot under.
-_CHEATSHEET_PREAMBLE = """\
-## Node wrapper (every node, top-level)
-
-    {"id": "node1" (digits + letters only — see "Node IDs" below),
-     "type": "custom",                # ReactFlow renderer key. Iteration/loop
-                                      # *start* children use special types
-                                      # (see Containers below).
-     "position": {"x": <number>, "y": <number>},
-     "data": { ... per-type fields ... }}
-
-Children of iteration / loop containers additionally need
-``parentId``, ``zIndex: 1002`` and ``extent: "parent"`` — see Containers.
-
-## Shared "data" fields (every node)
-
-    {"type": "<node-type>",          # e.g. "llm", "start", "if-else"
-     "title": "<short label>",
-     "desc": "<one-liner>",
-     "selected": false}
-
-## Per type — additional "data" fields (only the node types in your plan are shown)"""
-
-
-# node_type → its per-type schema snippet. Keyed by the exact ``node_type``
-# string the planner emits so ``build_node_config_cheatsheet`` can look each
-# one up directly. Iteration / loop are documented in the Containers section
-# (they are subgraphs, not leaf nodes) rather than here.
+# Each snippet mirrors the production node default closely enough for one
+# model call to emit only meaningful ``data`` fields. The runner owns wrappers,
+# topology, container metadata, layout, and validation.
 _NODE_SNIPPETS: dict[str, str] = {
     "start": """\
 - start:
@@ -248,484 +192,30 @@ _NODE_SNIPPETS: dict[str, str] = {
     Enable only the sub-features you need; ``conditions`` reuse the if-else
     condition shape (key / comparison_operator / value). Outputs: ``result``
     (the processed array), ``first_record``, ``last_record``.""",
+    "assigner": """\
+- assigner  (write to an existing conversation / loop variable):
+    {"version": "2",
+     "items": [{"variable_selector": ["<target-node>", "<target-var>"],
+                "input_type": "variable",
+                "operation": "over-write",
+                "value": ["<source-node>", "<source-var>"]}]}
+    ``input_type`` is "variable" (value is a selector) or "constant".
+    Operations: over-write | clear | append | extend | set | += | -= | *= |
+    /= | remove-first | remove-last.""",
+    "human-input": """\
+- human-input  (pause for a person; use webapp delivery by default):
+    {"delivery_methods": [{"id": "webapp", "type": "webapp", "enabled": true}],
+     "form_content": "<short review / approval instructions>",
+     "inputs": [{"type": "paragraph", "output_variable_name": "comment",
+                 "default": {"type": "constant", "selector": [], "value": ""}}],
+     "user_actions": [{"id": "approve", "title": "Approve",
+                       "button_style": "primary"}],
+     "timeout": 3, "timeout_unit": "day"}
+    Each ``inputs[].output_variable_name`` is an output variable. Outgoing
+    edges use the matching user-action id as ``sourceHandle``.""",
 }
 
 
-# Pulled into the cheatsheet only when an iteration / loop appears in the plan.
-_CONTAINERS_SECTION = """\
-## Containers — iteration / loop
-
-These are SUBGRAPH nodes. To use one you MUST emit, in order:
-
-1. The container node itself, e.g. for iteration:
-       id: "nodeK"
-       type: "custom"
-       data: {"type": "iteration",
-              "title": "<label>",
-              "desc": "",
-              "selected": false,
-              "start_node_id": "nodeKstart",
-              "iterator_selector": ["<src>", "<list-var>"],
-              "output_selector": ["<inner-last-node>", "<out-var>"],
-              "is_parallel": false,
-              "parallel_nums": 10,
-              "error_handle_mode": "terminated",
-              "flatten_output": true}
-       width: 808
-       height: 204
-       zIndex: 1
-
-   For loop, swap "iteration" → "loop" and use:
-       data: {"type": "loop", "title": "...", "desc": "",
-              "selected": false, "start_node_id": "nodeKstart",
-              "break_conditions": [], "loop_count": 10,
-              "logical_operator": "and"}
-
-2. The auto-start child (one per container):
-       id: "nodeKstart"
-       type: "custom-iteration-start"          # loop → "custom-loop-start"
-       parentId: "nodeK"
-       extent: "parent"
-       draggable: false
-       selectable: false
-       zIndex: 1002
-       position: {"x": 60, "y": 78}            # relative to parent
-       data: {"type": "iteration-start",       # loop → "loop-start"
-              "title": "", "desc": "",
-              "isInIteration": true,           # loop → "isInLoop": true
-              "selected": false}
-
-3. Each inner-pipeline node (any node type, follows normal data rules) MUST add:
-       parentId: "nodeK"
-       extent: "parent"
-       zIndex: 1002
-       position: {x, y}                         # relative to parent
-       data: {..., "isInIteration": true,       # loop → "isInLoop": true
-              "iteration_id": "nodeK"}         # loop → "loop_id"
-
-4. Edges INSIDE a container must add to ``data``:
-       "isInIteration": true                    # loop → "isInLoop": true
-       "iteration_id": "nodeK"                 # loop → "loop_id"
-   and use ``zIndex: 1002``. Edges OUTSIDE containers use the default
-   ``isInIteration: false`` / ``isInLoop: false``.
-
-5. The container's incoming/outgoing edges connect to the container's id
-   (``nodeK``), NOT to inner nodes. The first inner edge connects from
-   ``nodeKstart``."""
-
-
-# Always-included trailer: edge handle conventions for every graph.
-_EDGE_HANDLES_SECTION = """\
-## Edge handles
-
-- Most nodes:           sourceHandle "source", targetHandle "target".
-- if-else cases:        sourceHandle is the case_id ("true" / "false" / ...).
-- question-classifier:  sourceHandle is the class_id ("1" / "2" / ...).
-- iteration-start /     sourceHandle "source"; the edge from the *start node
-  loop-start:           is what kicks off the first inner step."""
-
-
-# Container node types are described in ``_CONTAINERS_SECTION`` rather than as
-# leaf snippets; their presence in a plan pulls that section in.
-_CONTAINER_NODE_TYPES = frozenset({"iteration", "loop"})
-
-
-def build_node_config_cheatsheet(node_types: Iterable[str] | None = None) -> str:
-    """
-    Assemble the builder cheatsheet for exactly the node types in the plan.
-
-    ``node_types`` is the set of ``node_type`` strings the planner chose. We
-    emit the always-on preamble (wrapper / shared fields), then only the
-    per-type snippets for the requested types (``start`` is always included —
-    every graph has one), the Containers section when an iteration / loop is
-    planned, and the edge-handles trailer. Unknown / unrecognised type strings
-    are ignored (the runtime / structural validator catches genuinely bogus
-    types).
-
-    ``None`` returns the FULL cheatsheet (every snippet + containers) — used to
-    build the static back-compat constants below and as a safe fallback.
-    """
-    if node_types is None:
-        requested: set[str] = set(_NODE_SNIPPETS) | set(_CONTAINER_NODE_TYPES)
-    else:
-        requested = {str(t).strip() for t in node_types if str(t).strip()}
-        requested.add("start")  # every workflow has exactly one start node
-
-    parts: list[str] = [_CHEATSHEET_PREAMBLE]
-    # Iterate _NODE_SNIPPETS (not ``requested``) to keep a stable, readable order.
-    parts.extend(snippet for node_type, snippet in _NODE_SNIPPETS.items() if node_type in requested)
-    if requested & _CONTAINER_NODE_TYPES:
-        parts.append(_CONTAINERS_SECTION)
-    parts.append(_EDGE_HANDLES_SECTION)
-    return "\n\n".join(parts) + "\n"
-
-
-# Full cheatsheet (all node types) — retained as a module constant so callers
-# and tests that want the complete reference can import it directly. The
-# dynamic per-request prompt is built by ``get_builder_system_prompt``.
-NODE_CONFIG_CHEATSHEET = build_node_config_cheatsheet()
-
-
-_BASE_SYSTEM_PROMPT_HEAD = """You are a Dify workflow builder.
-
-You are given:
-  1. A user instruction (what the workflow should do).
-  2. A node plan from the planner (which nodes to use, in execution order).
-
-Your job: emit a complete Dify workflow graph as JSON. The graph will be written
-directly into a Studio draft, so it must be syntactically valid and structurally
-correct.
-
-# Hard rules
-
-1. The output is a single JSON object — no prose, no Markdown, no code fences.
-2. NODE IDs MUST USE ONLY ALPHANUMERICS + UNDERSCORES — never hyphens.
-   Dify's run-time placeholder regex (see ``variable_pool.VARIABLE_PATTERN``)
-   is ``\\{\\{#([a-zA-Z0-9_]{1,50}(?:\\.[a-zA-Z_][a-zA-Z0-9_]{0,29}){1,10})#\\}\\}``,
-   so any placeholder pointing at a hyphenated id (e.g. ``{{#node-1.text#}}``)
-   silently fails to match at run time and the literal string survives into
-   the prompt — the user then sees ``{{#node-1.text#}}`` in their output.
-   Use the EXACT ids from the plan, formatted as ``node1``, ``node2``, ... in
-   plan order. Edge ``source`` / ``target`` must reference these ids.
-3. Every node has top-level fields: id, type, position, data.
-   - "type" is always "custom" (ReactFlow node renderer).
-   - "data.type" is the actual node type ("llm", "start", etc.).
-4. Every edge has top-level fields: id, source, target, type, sourceHandle, targetHandle.
-   - "type" is always "custom".
-   - "sourceHandle"/"targetHandle" follow the cheatsheet (default: "source"/"target").
-   - Edge id format: "<source>-<sourceHandle>-<target>-<targetHandle>".
-5. Use the model from the planner context for ALL "llm" / "question-classifier" /
-   "parameter-extractor" nodes (provider, name, mode, completion_params).
-6. Reference upstream outputs with the literal placeholder syntax
-   ``{{#<node-id>.<output-var>#}}`` — that's DOUBLE curly braces with ``#``
-   markers inside (matching Dify's runtime placeholder regex
-   ``\\{\\{#[^#]+#\\}\\}``). NEVER emit single-brace ``{#…#}`` — Dify will
-   not interpolate it, so the LLM at run time would see the literal
-   placeholder string in its prompt and echo it back as output. Use
-   ``["<node-id>", "<output-var>"]`` for ``value_selector`` /
-   ``query_variable_selector`` / etc.
-7. The "start" node owns input variables; downstream nodes reference them as
-   ``["<start-node-id>", "<var-name>"]`` for selectors or
-   ``{{#<start-node-id>.<var-name>#}}`` inside prompt strings.
-8. NEVER emit "code" or "http-request" nodes if a tool from the "Available tools"
-   section below covers the same task — replace them with a "tool" node referencing
-   the exact provider/tool identifier from the catalogue. "code" / "http-request"
-   are last-resort escape hatches for arbitrary transformations and APIs that no
-   installed tool can express.
-9. EVERY variable reference MUST resolve to a real, declared variable on the
-   source node — never invent a variable name. Specifically:
-   - ``{{#<node-id>.<var>#}}`` inside a prompt / ``answer`` / ``template-transform``
-     template (DOUBLE braces — single ``{#…#}`` is NOT a Dify placeholder
-     and will NOT be substituted), AND ``["<node-id>", "<var>"]`` inside a
-     ``value_selector`` /
-     ``query_variable_selector`` / ``iterator_selector`` / ``output_selector`` /
-     ``tool_parameters[*].value`` (when ``type: "variable"``), MUST point at a
-     value that the source node actually exposes:
-       * ``start``  → one of the ``data.variables[*].variable`` entries you
-         declared on the start node. Add an entry if you need a new input.
-       * ``llm``    → ``text`` (the default LLM output) or, when structured
-         output is enabled, a key from its schema.
-       * ``code``   → a key in ``data.outputs``.
-       * ``knowledge-retrieval`` → ``result`` (the standard array output).
-       * ``parameter-extractor`` → one of the ``data.parameters[*].name``.
-       * ``document-extractor`` → ``text`` (extracted file text; an array of
-         strings when ``is_array_file`` is true).
-       * ``variable-aggregator`` → ``output``.
-       * ``list-operator`` → ``result`` (array), ``first_record``,
-         ``last_record``.
-       * ``tool``   → any parameter declared by the tool — the run time
-         validates these, so you can name them freely, but pick from the
-         documented provider/tool.
-     If the planner's "Start inputs" list (see user prompt) is non-empty,
-     copy each entry verbatim into ``start.data.variables`` so the
-     downstream references resolve.
-   - In Advanced-Chat mode you may also reference ``sys.query`` and
-     ``sys.files`` without declaring them. In selector fields, spell these as
-     exactly ``["sys", "query"]`` and ``["sys", "files"]`` — never as a
-     one-item array such as ``["sys,query"]`` or ``["sys.query"]``.
-10. MULTIPLE KNOWLEDGE-RETRIEVAL INPUTS TO ONE LLM require a template fan-in.
-    ``context.variable_selector accepts only one selector`` and therefore
-    cannot carry two retrieval outputs. When an LLM must synthesize two or
-    more retrieval results:
-    - Run the retrieval nodes as parallel siblings from the same query input.
-    - Add one ``template-transform`` node after them. Give it one variable per
-      retrieval, such as ``value_selector: ["node2", "result"]`` and
-      ``value_selector: ["node3", "result"]``, and render every source's
-      content into one labelled text output.
-    - Add an edge from EACH retrieval node to the template, then one edge from
-      the template to the LLM. The LLM must NOT receive direct retrieval edges.
-    - Enable the LLM's context, set ``context.variable_selector`` to the
-      template's ``["<template-node-id>", "output"]``, and put
-      ``{{#context#}}`` in its prompt.
-    - Do not use ``variable-aggregator`` for this: it selects the first value
-      produced by mutually exclusive branches; it does not concatenate two
-      retrieval results that both ran.
-
-"""
-
-
-_BASE_SYSTEM_PROMPT_TAIL = """\
-
-# Layout
-
-- Place nodes left-to-right with x=80 + 320 * index, y=280.
-- Viewport: {"x": 0, "y": 0, "zoom": 0.7}.
-
-"""
-
-
-_BASE_SYSTEM_PROMPT_FOOTER = """
-
-# Output schema
-
-{
-  "nodes": [...],
-  "edges": [...],
-  "viewport": {"x": 0, "y": 0, "zoom": 0.7}
-}
-"""
-
-
-_WORKFLOW_MODE_RULES = """# Mode-specific rules — Workflow
-
-- The graph MUST start with exactly one "start" node and end with exactly one "end" node.
-- Do NOT use "answer" nodes (those are for Advanced Chat only).
-- The "end" node's outputs[].value_selector must point at a real upstream output.
-"""
-
-
-_ADVANCED_CHAT_MODE_RULES = """# Mode-specific rules — Advanced Chat (Chatflow)
-
-- The graph MUST start with exactly one "start" node and end with exactly one "answer" node.
-- Do NOT use "end" nodes (those are for plain Workflow apps).
-- The "start" node should expose "sys.query" / "sys.files" automatically; user-defined
-  variables go in start.data.variables.
-- The "answer" node's "answer" field references upstream outputs as
-  {{#<node-id>.<var>#}} and is what the user sees in chat.
-"""
-
-
-def _assemble_builder_system_prompt(mode: str, node_types: Iterable[str] | None) -> str:
-    """Stitch the builder system prompt for ``mode`` around a cheatsheet built
-    for ``node_types`` (``None`` → full cheatsheet)."""
-    mode_rules = _ADVANCED_CHAT_MODE_RULES if mode == "advanced-chat" else _WORKFLOW_MODE_RULES
-    return (
-        _BASE_SYSTEM_PROMPT_HEAD
-        + mode_rules
-        + _BASE_SYSTEM_PROMPT_TAIL
-        + build_node_config_cheatsheet(node_types)
-        + _BASE_SYSTEM_PROMPT_FOOTER
-    )
-
-
-# Static full-cheatsheet prompts — the back-compat default returned by
-# ``get_builder_system_prompt`` when the caller doesn't pin a node-type set.
-BUILDER_SYSTEM_PROMPT_WORKFLOW = _assemble_builder_system_prompt("workflow", None)
-
-BUILDER_SYSTEM_PROMPT_ADVANCED_CHAT = _assemble_builder_system_prompt("advanced-chat", None)
-
-
-BUILDER_USER_PROMPT = """# User instruction
-
-{instruction}
-
-{ideal_output_section}\
-{existing_graph_section}\
-# Selected model (use for all LLM-based nodes)
-
-provider={provider}, name={name}, mode={mode_label}
-
-{tool_catalogue_section}\
-{start_inputs_section}\
-# Node plan (from planner — use these labels and node_types in this order)
-
-{plan_block}
-
-Now emit the complete workflow graph JSON.
-"""
-
-
-# Node wrapper fields that carry no meaning the builder needs: pure canvas /
-# selection state, plus geometry the runner's postprocess recomputes anyway.
-# Stripping them out of the refine prompt cuts its size roughly in half on
-# hand-edited graphs — fewer tokens in, and (because the builder echoes
-# untouched nodes verbatim) far fewer tokens out, which is where the latency
-# lives.
-_PRUNED_NODE_KEYS = frozenset(
-    {
-        "positionAbsolute",
-        "sourcePosition",
-        "targetPosition",
-        "selected",
-        "dragging",
-        "measured",
-    }
-)
-
-# Additionally pruned from TOP-LEVEL nodes only: the layered auto-layout
-# recomputes their position and size defaults, so the builder never needs to
-# reproduce them. Container children keep ``position`` (relative to the
-# parent, which we cannot recompute) and containers keep ``width`` /
-# ``height`` (their canvas size is real config, not a default).
-_PRUNED_TOP_LEVEL_NODE_KEYS = _PRUNED_NODE_KEYS | {"position", "width", "height"}
-
-_CONTAINER_DATA_TYPES = frozenset({"iteration", "loop"})
-
-# Edge fields the builder must echo; everything else (ids, zIndex,
-# sourceType / targetType, isInIteration / isInLoop markers) is recomputed
-# by the runner's postprocess from the node topology.
-_KEPT_EDGE_KEYS = ("source", "target", "sourceHandle", "targetHandle")
-
-
-def compact_graph_for_builder(current_graph: dict) -> dict:
-    """
-    Strip canvas noise out of a draft graph before prompt injection.
-
-    Keeps everything semantically meaningful — ids, wrapper ``type``,
-    ``parentId``, the full ``data`` config, child positions, container
-    sizes — and drops geometry / selection state the postprocess pass
-    recomputes. The builder echoes untouched nodes verbatim, so every byte
-    removed here is removed twice (prompt AND completion).
-    """
-    nodes_out: list[dict] = []
-    for node in current_graph.get("nodes") or []:
-        if not isinstance(node, dict):
-            continue
-        is_child = bool(node.get("parentId"))
-        is_container = isinstance(node.get("data"), dict) and node["data"].get("type") in _CONTAINER_DATA_TYPES
-        pruned = _PRUNED_NODE_KEYS if (is_child or is_container) else _PRUNED_TOP_LEVEL_NODE_KEYS
-        compact = {k: v for k, v in node.items() if k not in pruned}
-        if is_container:
-            # Container position is still recomputed by the layout pass.
-            compact.pop("position", None)
-        nodes_out.append(compact)
-    edges_out = [
-        {k: edge[k] for k in _KEPT_EDGE_KEYS if k in edge}
-        for edge in (current_graph.get("edges") or [])
-        if isinstance(edge, dict)
-    ]
-    return {"nodes": nodes_out, "edges": edges_out}
-
-
-def format_builder_existing_graph_section(current_graph: dict | None) -> str:
-    """
-    Refine mode: give the builder the existing graph JSON so it can keep
-    every node and edge the user's change does not touch byte-for-byte — same
-    ids, same config, same prompt templates. Without the full config the
-    builder would regenerate untouched nodes from scratch and silently drop
-    the user's hand-tuned settings. Canvas-only fields are stripped first
-    (see ``compact_graph_for_builder``) — they're recomputed in postprocess,
-    so carrying them only slows the call down.
-
-    Returns an empty string in create mode (no ``current_graph``); the builder
-    then behaves exactly as before, constructing the graph purely from the
-    planner's node plan.
-    """
-    if not current_graph:
-        return ""
-    graph_json = json.dumps(compact_graph_for_builder(current_graph), ensure_ascii=False, separators=(",", ":"))
-    return (
-        "# Existing graph to refine (JSON)\n\n"
-        "You are REFINING this existing graph, NOT building from scratch. Apply "
-        "ONLY the change the user instruction describes. Every node and edge the "
-        "change does not affect MUST be preserved verbatim — keep the same node "
-        "ids, the same `data` config, and the same prompt templates. The node "
-        "plan below is the target node set after your change; use the existing "
-        "graph as the source of truth for the config of nodes that carry over.\n\n"
-        f"```json\n{graph_json}\n```\n\n"
-    )
-
-
-def format_start_inputs_section(start_inputs: list[dict[str, Any]]) -> str:
-    """
-    Surface the planner's ``start_inputs`` list to the builder so it can
-    populate ``start.data.variables`` with the exact set of inputs every
-    downstream variable reference will need. Empty list → empty section,
-    because the builder may then declare no input variables (e.g. an
-    Advanced-Chat workflow that only consumes ``sys.query``).
-    """
-    if not start_inputs:
-        return ""
-    lines = ["# Start inputs (copy each entry verbatim into start.data.variables)"]
-    lines.append("")
-    for inp in start_inputs:
-        variable = str(inp.get("variable") or "").strip()
-        label = str(inp.get("label") or "").strip()
-        type_ = str(inp.get("type") or "paragraph").strip()
-        if not variable:
-            continue
-        lines.append(f"- variable={variable!r}  label={label!r}  type={type_!r}")
-    lines.append("")
-    return "\n".join(lines) + "\n"
-
-
-def format_builder_tool_catalogue_section(catalogue_text: str) -> str:
-    """
-    Builder-facing catalogue block. The builder needs the same identifiers
-    the planner saw, plus a stern reminder that ``tool`` nodes MUST set
-    ``provider_id`` / ``provider_name`` / ``tool_name`` to entries that
-    actually exist in this list — hallucinated tools fail at draft sync.
-    """
-    if not catalogue_text.strip():
-        return ""
-    return (
-        "# Available tools (use these exact provider/tool identifiers — "
-        "for each 'tool' node, set provider_id and provider_name to the "
-        "provider portion and tool_name to the tool portion)\n\n"
-        f"{catalogue_text}\n\n"
-    )
-
-
-def format_plan_block(plan_nodes: list[dict[str, Any]]) -> str:
-    """
-    Render the planner output as a numbered list the builder can quote.
-
-    Node IDs use no separator (``node1``, ``node2``, ...) because Dify's
-    run-time placeholder regex requires ``[a-zA-Z0-9_]`` in the node-id
-    slot — a hyphenated id like ``node-1`` would silently fail to match
-    at run time and the literal ``{{#node-1.var#}}`` survives into the
-    LLM prompt.
-
-    For container children (planner emitted a ``"parent": "<label>"`` key),
-    we resolve the parent label to its ``nodeN`` id and surface it on the
-    same line so the builder knows to set ``parentId`` and the
-    ``isInIteration`` / ``isInLoop`` markers on inner nodes.
-    """
-    # First pass: label → node-id so we can resolve "parent" hints.
-    label_to_id: dict[str, str] = {}
-    for idx, node in enumerate(plan_nodes, start=1):
-        label = str(node.get("label") or "")
-        if label and label not in label_to_id:
-            label_to_id[label] = f"node{idx}"
-
-    lines = []
-    for idx, node in enumerate(plan_nodes, start=1):
-        node_id = f"node{idx}"
-        label = node.get("label", "")
-        node_type = node.get("node_type", "")
-        purpose = node.get("purpose", "")
-        parent_label = str(node.get("parent") or "")
-        parent_clause = ""
-        if parent_label:
-            parent_id = label_to_id.get(parent_label, "")
-            if parent_id:
-                parent_clause = f"  parent={parent_id}"
-            else:
-                parent_clause = f"  parent={parent_label!r}"
-        lines.append(f"{idx}. id={node_id}  type={node_type}  label={label!r}{parent_clause}\n   purpose: {purpose}")
-    return "\n".join(lines)
-
-
-def get_builder_system_prompt(mode: str, node_types: Iterable[str] | None = None) -> str:
-    """
-    Build the builder system prompt for ``mode``, with a cheatsheet scoped to
-    ``node_types`` (the planner's chosen node types).
-
-    When ``node_types`` is ``None`` we return the cached full-cheatsheet
-    constant (back-compat default). When the runner passes the plan's node-type
-    set we assemble a fresh prompt carrying only the relevant per-type schemas,
-    so the builder isn't handed config for node types the workflow never uses.
-    """
-    if node_types is None:
-        return BUILDER_SYSTEM_PROMPT_ADVANCED_CHAT if mode == "advanced-chat" else BUILDER_SYSTEM_PROMPT_WORKFLOW
-    return _assemble_builder_system_prompt(mode, node_types)
+def get_node_config_snippet(node_type: str) -> str:
+    """Return the semantic config reference for one leaf node type."""
+    return _NODE_SNIPPETS.get(node_type, "")

api/core/workflow/generator/prompts/node_builder_prompts.py

@@ -0,0 +1,138 @@
+"""Compact prompts for parallel, per-node workflow configuration.
+
+Each call produces only the semantic ``data`` fields for one planned node.
+Canvas wrappers, shared labels, topology, layout, and edge defaults are owned
+by ``WorkflowGenerator`` so completion length scales with node configuration
+rather than with the full ReactFlow graph.
+"""
+
+import json
+from typing import Any
+
+from core.workflow.generator.prompts.builder_prompts import get_node_config_snippet
+
+_CONTAINER_CONFIG_SNIPPETS = {
+    "iteration": """- iteration:
+    {"iterator_selector": ["<src>", "<list-var>"],
+     "output_selector": ["<last-child>", "<out-var>"],
+     "is_parallel": false, "parallel_nums": 10,
+     "error_handle_mode": "terminated", "flatten_output": true}
+    The runner supplies start_node_id, child wrappers, and the synthetic start node.""",
+    "loop": """- loop:
+    {"break_conditions": [{"id": "c1",
+                            "variable_selector": ["<child>", "<var>"],
+                            "comparison_operator": "is",
+                            "value": "<value>"}],
+     "loop_count": 10, "logical_operator": "and"}
+    The runner supplies start_node_id, child wrappers, and the synthetic start node.""",
+}
+
+_NODE_BUILDER_HEAD = """You configure exactly ONE node in a Dify workflow.
+
+Return one JSON object with exactly this shape: {"config": {...}}.
+``config`` contains only node-type-specific ``data`` fields. Do NOT repeat id,
+type, title, desc, selected, position, wrapper fields, edges, or viewport.
+
+Rules:
+- Use only ids from the supplied normalized plan.
+- Placeholder strings use ``{{#node_id.variable#}}``; selector fields use
+  ``["node_id", "variable"]``. Never invent an upstream output.
+- Use the selected model verbatim for llm, question-classifier, and
+  parameter-extractor nodes.
+- Keep prompts/code concise but complete for the user's requested behavior.
+- Emit strict JSON only: no prose, Markdown, comments, or trailing commas.
+
+# Target node schema
+
+"""
+
+
+NODE_BUILDER_USER_PROMPT = """# Target node
+
+id={node_id}, type={node_type}, label={label!r}
+purpose={purpose}
+
+# User instruction
+
+{instruction}
+
+{ideal_output_section}{mode_section}{model_section}{tool_catalogue_section}{start_inputs_section}{existing_config_section}\
+# Normalized plan and topology
+
+{plan_json}
+
+Return {{"config": {{...}}}} for target node {node_id} now.
+"""
+
+
+def get_node_builder_system_prompt(node_type: str) -> str:
+    """Build a one-node prompt containing only that node's semantic schema."""
+    snippet = _CONTAINER_CONFIG_SNIPPETS.get(node_type) or get_node_config_snippet(node_type)
+    return _NODE_BUILDER_HEAD + (snippet or f"- {node_type}: emit the minimum valid config fields.")
+
+
+def format_parallel_plan(
+    plan_nodes: list[dict[str, Any]],
+    plan_edges: list[dict[str, Any]],
+    start_inputs: list[dict[str, Any]] | None = None,
+) -> str:
+    """Serialize the shared plan compactly so every node call has graph context.
+
+    ``start_inputs`` rides along so downstream builders reference the declared
+    ``{{#<start-id>.<variable>#}}`` names instead of guessing them from prose
+    — a guessed name gets auto-injected as a spurious form input later.
+    """
+    payload: dict[str, Any] = {"nodes": plan_nodes, "edges": plan_edges}
+    if start_inputs:
+        payload["start_inputs"] = start_inputs
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+
+
+def format_mode_section(mode: str) -> str:
+    """Tell each builder which app mode it is configuring for.
+
+    Matters most in advanced-chat, where ``sys.query`` / ``sys.files`` are the
+    sanctioned way to reference the user's message — without this the model
+    invents start-node variables that postprocess then materializes as
+    spurious form inputs.
+    """
+    if mode == "advanced-chat":
+        return (
+            "# App mode\n\n"
+            "advanced-chat: the user's chat message is available as sys.query and uploaded files "
+            'as sys.files — placeholder {{#sys.query#}}, selector ["sys", "query"]. Reference them '
+            "directly; do NOT invent start-node variables for the chat message.\n\n"
+        )
+    return (
+        "# App mode\n\n"
+        "workflow: there are NO automatic system variables; reference user input only through "
+        "the start node's declared variables.\n\n"
+    )
+
+
+def format_start_inputs_section(start_inputs: list[dict[str, Any]]) -> str:
+    """Render planner-declared inputs for the start-node builder only."""
+    if not start_inputs:
+        return ""
+    lines = ["# Start inputs (copy each entry verbatim into start.data.variables)", ""]
+    for input_ in start_inputs:
+        variable = str(input_.get("variable") or "").strip()
+        if not variable:
+            continue
+        label = str(input_.get("label") or "").strip()
+        type_ = str(input_.get("type") or "paragraph").strip()
+        lines.append(f"- variable={variable!r}  label={label!r}  type={type_!r}")
+    lines.append("")
+    return "\n".join(lines) + "\n"
+
+
+def format_tool_catalogue_section(catalogue_text: str) -> str:
+    """Render exact tool identifiers for a tool-node builder only."""
+    if not catalogue_text.strip():
+        return ""
+    return (
+        "# Available tools (use these exact provider/tool identifiers — "
+        "set provider_id and provider_name to the provider portion and "
+        "tool_name to the tool portion)\n\n"
+        f"{catalogue_text}\n\n"
+    )

api/core/workflow/generator/prompts/planner_prompts.py

@@ -1,13 +1,14 @@
 """
 Planner prompts.
 
-The planner is the lightweight first step in the slim planner→builder pipeline.
+The planner is the lightweight first step in the slim planner→node-builders pipeline.
 It receives the user's natural-language instruction and emits a high-level
-node plan in JSON. The builder later turns that plan into the final graph.
+node and edge plan in JSON. Node builders later produce configs that the runner
+assembles into the final graph.
 
 We keep the planner deliberately short — the heavy lifting (config schemas,
-edge wiring, default values) belongs in the builder. The planner only commits
-to the *which-node-types* decision so the builder gets a tight scaffold.
+default values) belongs in the builders. The planner commits to the minimum
+topology and node types so every builder gets a tight scaffold.
 """
 
 PLANNER_SYSTEM_PROMPT = """You are a Dify workflow planner.
@@ -39,6 +40,8 @@ minimum set of Dify workflow nodes needed to fulfil it, in execution order.
                           mutually-exclusive paths before "end" / "answer".
 - "list-operator"       — filter / sort / slice an array variable (e.g. the items
                           fed into or produced by an "iteration").
+- "assigner"            — update an existing conversation or loop variable.
+- "human-input"         — pause for a person to review, approve, or enter data.
 
 # Rules
 
@@ -97,22 +100,45 @@ minimum set of Dify workflow nodes needed to fulfil it, in execution order.
     variables are automatic — downstream nodes may reference them without
     a ``start_inputs`` entry. In Workflow mode there is NO automatic
     variable; everything the user supplies must be in ``start_inputs``.
-11. Output strictly the JSON object — no prose, no Markdown, no code fences.
+11. Give every node a unique runtime-safe ``id`` using only letters, digits,
+    and underscores. In create mode use ``node1``, ``node2``, ... in node-list
+    order. In refine mode preserve the existing id for every retained node.
+12. Emit the target graph's edges in ``edges``. Each edge is
+    ``{"source": "<id>", "target": "<id>"}``; add ``source_handle`` only
+    for branch nodes: if-else case id, question-classifier class id, or
+    human-input action id. Container children reference the container id in
+    their ``parent`` field; do not emit the synthetic iteration/loop start node.
+13. In refine mode add ``action`` to every retained target node:
+    ``"keep"`` when its data config is unchanged, ``"update"`` when the user
+    asked to change its config, and ``"add"`` for a new node. Removed nodes are
+    omitted. Edge-only rewiring does not require changing a node's action.
+14. Output strictly the JSON object — no prose, no Markdown, no code fences.
+15. Echo the app mode in the ``mode`` output field — exactly "workflow" or
+    "advanced-chat". When the ``# Mode`` section says auto, YOU decide:
+    "workflow" for one-shot automations (run once with form inputs, return a
+    result), "advanced-chat" for conversational multi-turn assistants. The
+    terminal node must match the chosen mode (rule 2): "end" for workflow,
+    "answer" for advanced-chat.
 
 # Output schema
 
 {
   "title": "<≤ 40-char title of the workflow>",
   "description": "<one-sentence summary>",
+  "mode": "workflow | advanced-chat",
   "app_name": "<≤ 30-char product-style name, e.g. 'URL Summarizer'>",
   "icon": "<single emoji that captures the workflow's purpose, e.g. '📰'>",
   "start_inputs": [
     {"variable": "url", "label": "URL", "type": "text-input"}
   ],
   "nodes": [
-    {"label": "Start",      "node_type": "start", "purpose": "..."},
-    {"label": "Summarize",  "node_type": "llm",   "purpose": "..."},
-    {"label": "End",        "node_type": "end",   "purpose": "..."}
+    {"id": "node1", "label": "Start",     "node_type": "start", "purpose": "..."},
+    {"id": "node2", "label": "Summarize", "node_type": "llm",   "purpose": "..."},
+    {"id": "node3", "label": "End",       "node_type": "end",   "purpose": "..."}
+  ],
+  "edges": [
+    {"source": "node1", "target": "node2"},
+    {"source": "node2", "target": "node3"}
   ]
 }
 """
@@ -140,7 +166,8 @@ def format_existing_graph_section(current_graph: dict | None) -> str:
 
     We pass only ids / node-types / titles + edge endpoints here — the planner
     decides *which nodes* exist, so it needs the shape, not the per-node config.
-    The builder gets the full graph JSON to preserve untouched node config.
+    Node builders receive only the config of a node marked ``update``;
+    configs marked ``keep`` are reused directly.
     """
     if not current_graph:
         return ""
@@ -156,7 +183,13 @@ def format_existing_graph_section(current_graph: dict | None) -> str:
     for edge in edges:
         if not isinstance(edge, dict):
             continue
-        edge_lines.append(f"- {edge.get('source', '')} -> {edge.get('target', '')}")
+        # Branch wiring (if-else case ids, classifier class ids, human-input
+        # action ids) lives in ``sourceHandle``. The planner is the only
+        # source of edges for the rebuilt graph, so the real handle must be
+        # surfaced here or refine silently rewires branches.
+        handle = str(edge.get("sourceHandle") or "")
+        handle_suffix = f" (source_handle={handle!r})" if handle and handle != "source" else ""
+        edge_lines.append(f"- {edge.get('source', '')} -> {edge.get('target', '')}{handle_suffix}")
     nodes_block = "\n".join(node_lines) or "(none)"
     edges_block = "\n".join(edge_lines) or "(none)"
     return (
@@ -166,7 +199,9 @@ def format_existing_graph_section(current_graph: dict | None) -> str:
         "node list to reflect that change while keeping everything the "
         "instruction does not mention — preserve existing nodes, their order, "
         "and their labels wherever the change leaves them untouched. Only add, "
-        "remove, or rename nodes the requested change actually requires.\n\n"
+        "remove, or rename nodes the requested change actually requires. "
+        "For every retained edge, copy its source_handle verbatim from the "
+        "list below — branch wiring must survive the refine unchanged.\n\n"
         f"Current nodes:\n{nodes_block}\n\n"
         f"Current edges:\n{edges_block}\n\n"
     )

api/core/workflow/generator/runner.py

@@ -1,14 +1,14 @@
 """
 Workflow generator runner.
 
-Slim planner→builder pipeline. Pure domain logic; the model instance is
+Slim planner→parallel-node-builder pipeline. Pure domain logic; the model instance is
 injected by ``WorkflowGeneratorService`` so this module stays cleanly
 separated from the infrastructure layer.
 
 Pipeline:
 
     1. PLANNER  — short LLM call producing a high-level node list.
-    2. BUILDER  — structured-output LLM call producing the full graph JSON.
+    2. BUILDERS — bounded concurrent LLM calls producing compact node configs.
     3. POSTPROC — fill safe defaults, lay nodes out left-to-right, dedupe
                   edge ids, and run a final structural sanity check.
 
@@ -20,7 +20,8 @@ Intentionally NOT here (deferred to a future iteration):
     - Tool / model catalogue filtering
 
 If quality regresses below product threshold we add those back; for now the
-single planner+builder pair shipped behind cmd+k `/create` is enough.
+planner and bounded parallel node builders shipped behind cmd+k `/create` are
+enough.
 """
 
 import json
@@ -28,17 +29,22 @@ import logging
 import re
 import time
 from collections.abc import Iterator
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from copy import deepcopy
 from typing import Any, ClassVar, cast
 
 import json_repair
 
-from core.workflow.generator.prompts.builder_prompts import (
-    BUILDER_USER_PROMPT,
-    format_builder_existing_graph_section,
-    format_builder_tool_catalogue_section,
-    format_plan_block,
+from configs import dify_config
+from core.workflow.generator.prompts.node_builder_prompts import (
+    NODE_BUILDER_USER_PROMPT,
+    format_mode_section,
+    format_parallel_plan,
     format_start_inputs_section,
-    get_builder_system_prompt,
+    get_node_builder_system_prompt,
+)
+from core.workflow.generator.prompts.node_builder_prompts import (
+    format_tool_catalogue_section as format_node_tool_catalogue_section,
 )
 from core.workflow.generator.prompts.planner_prompts import (
     PLANNER_SYSTEM_PROMPT,
@@ -55,6 +61,7 @@ from core.workflow.generator.types import (
     WorkflowGenerateErrorDict,
     WorkflowGenerateResultDict,
     WorkflowGenerationMode,
+    WorkflowGenerationModeRequest,
 )
 from graphon.enums import BuiltinNodeTypes
 from graphon.model_runtime.entities.llm_entities import LLMResult
@@ -96,11 +103,31 @@ _DEFAULT_FILE_UPLOAD_METHODS = ("local_file", "remote_url")
 
 # Token ceiling for the planner call when the caller didn't pin one. The plan
 # is a short JSON node list (a handful of nodes with labels/purposes), so this
-# is generous headroom while still bounding a runaway response. The builder is
-# left on the caller's budget — it emits the full graph and genuinely needs it.
+# is generous headroom while still bounding a runaway response. Builder calls
+# keep the caller's budget so complex node configs are not truncated.
 _PLANNER_DEFAULT_MAX_TOKENS = 4096
 
 
+# Per-node calls trade a larger request count for a shorter critical path.
+# The cap comes from ``WORKFLOW_GENERATOR_NODE_BUILDER_MAX_WORKERS`` (default 6,
+# enough to run the planner's recommended 3–6-node plans as a single wave);
+# provider rate-limit bursts are absorbed by ``_invoke_with_retry``'s bounded
+# backoff, and operators can dial the env var back down if their provider is
+# stricter. Read at call time so tests (and live config reloads) can adjust it
+# without re-importing.
+def _node_builder_max_workers() -> int:
+    return dify_config.WORKFLOW_GENERATOR_NODE_BUILDER_MAX_WORKERS
+
+
+_MODEL_NODE_TYPES = frozenset(
+    {
+        BuiltinNodeTypes.LLM,
+        BuiltinNodeTypes.QUESTION_CLASSIFIER,
+        BuiltinNodeTypes.PARAMETER_EXTRACTOR,
+    }
+)
+
+
 # Appended as a trailing user message on the SECOND (and only) attempt when
 # the first response wasn't parseable as JSON. Keep this terse — the model
 # already has its full instructions in the original system message; this is
@@ -110,6 +137,12 @@ _JSON_RETRY_HINT = (
     "Do not include any prose, markdown code fences, comments, or trailing commas."
 )
 
+_PLANNER_SCHEMA_RETRY_HINT = (
+    "Your plan did not match the required topology schema. Return the complete plan again with "
+    "a unique non-empty id on every node and a non-empty edges array whose source and target "
+    "reference those ids. Return ONLY the JSON object."
+)
+
 
 # Provider hiccups we retry: a dropped connection, a 5xx, or a rate-limit are
 # all transient — the same request usually succeeds moments later. We do NOT
@@ -189,14 +222,58 @@ def _result_with_errors(
 def _with_mode(result: WorkflowGenerateResultDict, mode: WorkflowGenerationMode) -> WorkflowGenerateResultDict:
     """Stamp the resolved concrete ``mode`` onto a result envelope.
 
-    ``mode="auto"`` requests are resolved to a concrete mode before planning;
-    echoing it back lets the frontend pick the right app type to create. It's
-    present for explicit modes too so the response shape stays uniform.
+    ``mode="auto"`` requests are resolved to a concrete mode from the planner
+    output; echoing it back lets the frontend pick the right app type to
+    create. It's present for explicit modes too so the response shape stays
+    uniform.
     """
     result["mode"] = mode
     return result
 
 
+def _fallback_mode(mode: WorkflowGenerationModeRequest) -> WorkflowGenerationMode:
+    """Concrete mode for envelopes emitted before the planner resolved one.
+
+    ``auto`` maps to the conversational default — the same never-fail fallback
+    the old standalone classifier used — so ``result.mode`` never leaks the
+    ``auto`` sentinel to the frontend.
+    """
+    return "advanced-chat" if mode == "auto" else mode
+
+
+def _planner_prompt_mode(mode: WorkflowGenerationModeRequest) -> str:
+    """Mode string interpolated into the planner user prompt.
+
+    For ``auto`` the value is self-describing so the planner knows the choice
+    is delegated to it (system-prompt rule 15).
+    """
+    return "auto (choose workflow or advanced-chat)" if mode == "auto" else mode
+
+
+def _resolve_generation_mode(
+    requested: WorkflowGenerationModeRequest, plan: PlannerResultDict
+) -> WorkflowGenerationMode:
+    """Resolve the request mode into the concrete generation mode.
+
+    An explicit request always wins — a contradictory planner ``mode`` field is
+    ignored. For ``auto``: trust the planner's echoed ``mode``, else infer from
+    the plan's terminal node type (the structural source of truth the graph is
+    validated against), else fall back to the conversational default. Lenient
+    on purpose — a bad ``mode`` value must never fail the plan.
+    """
+    if requested != "auto":
+        return requested
+    planner_mode = str(plan.get("mode") or "").strip().lower()
+    if planner_mode in ("workflow", "advanced-chat"):
+        return cast(WorkflowGenerationMode, planner_mode)
+    node_types = {str(node.get("node_type") or "") for node in plan.get("nodes") or [] if isinstance(node, dict)}
+    if BuiltinNodeTypes.ANSWER in node_types:
+        return "advanced-chat"
+    if BuiltinNodeTypes.END in node_types:
+        return "workflow"
+    return "advanced-chat"
+
+
 def _build_plan_event(
     *,
     plan: PlannerResultDict,
@@ -255,7 +332,7 @@ class WorkflowGenerator:
         provider: str,
         model_name: str,
         model_mode: str,
-        mode: WorkflowGenerationMode,
+        mode: WorkflowGenerationModeRequest,
         instruction: str,
         ideal_output: str = "",
         tool_catalogue_text: str = "",
@@ -263,20 +340,26 @@ class WorkflowGenerator:
         current_graph: dict[str, Any] | None = None,
     ) -> WorkflowGenerateResultDict:
         """
-        Run planner → builder → postprocess and return a graph payload.
+        Run planner → node builders → postprocess and return a graph payload.
+
+        ``mode`` accepts the ``"auto"`` sentinel — the planner then chooses the
+        concrete mode itself (echoed in its ``mode`` output field) so no extra
+        classification call is needed; the resolution is stamped onto the
+        result envelope.
 
         ``current_graph`` switches the pipeline from create mode to REFINE
-        mode: the existing draft graph is injected into both the planner
-        (compact node/edge summary) and the builder (full JSON) so the LLM
-        amends the graph the user is editing instead of inventing a new one.
-        ``None`` (the default) is plain create-from-scratch behaviour.
+        mode: the existing draft graph is summarized for the planner. Node
+        builders receive only the config of the node they update, while configs
+        marked ``keep`` are reused without an LLM call. ``None`` (the default)
+        is plain create-from-scratch behaviour.
 
         ``tool_catalogue_text`` is the formatted list of installed tools for
         the calling tenant (see ``tool_catalogue.build_tool_catalogue`` /
         ``format_tool_catalogue``). It's injected into both the planner and
         builder prompts so the LLM can pick concrete ``provider/tool``
-        identifiers instead of inventing names; an empty string skips the
-        section entirely (useful for unit tests).
+        identifiers instead of inventing names; node builders receive it
+        only for tool nodes. An empty string skips the section entirely (useful
+        for unit tests).
 
         ``installed_tools`` is the structural sibling — a set of
         ``(provider_name, tool_name)`` pairs the validator consults to reject
@@ -316,7 +399,7 @@ class WorkflowGenerator:
         # The event generator always emits exactly one result envelope; this
         # fallback only guards against a future refactor that forgets to.
         if result is None:
-            result = _with_mode(_empty_result(), mode)
+            result = _with_mode(_empty_result(), _fallback_mode(mode))
         return result
 
     @classmethod
@@ -328,7 +411,7 @@ class WorkflowGenerator:
         provider: str,
         model_name: str,
         model_mode: str,
-        mode: WorkflowGenerationMode,
+        mode: WorkflowGenerationModeRequest,
         instruction: str,
         ideal_output: str = "",
         tool_catalogue_text: str = "",
@@ -368,7 +451,7 @@ class WorkflowGenerator:
         provider: str,
         model_name: str,
         model_mode: str,
-        mode: WorkflowGenerationMode,
+        mode: WorkflowGenerationModeRequest,
         instruction: str,
         ideal_output: str = "",
         tool_catalogue_text: str = "",
@@ -376,7 +459,7 @@ class WorkflowGenerator:
         current_graph: dict[str, Any] | None = None,
     ) -> Iterator[tuple[str, dict[str, Any]]]:
         """
-        Drive planner → builder → postprocess and yield generation events.
+        Drive planner → node builders → postprocess and yield generation events.
 
         Shared core for both ``generate_workflow_graph`` (keeps only the final
         ``result``) and ``generate_workflow_graph_stream`` (streams every
@@ -402,11 +485,16 @@ class WorkflowGenerator:
             ),
         )
         if plan_err is not None:
-            yield "result", cast(dict[str, Any], _with_mode(_result_with_errors(_empty_result(), [plan_err]), mode))
+            failed = _with_mode(_result_with_errors(_empty_result(), [plan_err]), _fallback_mode(mode))
+            yield "result", cast(dict[str, Any], failed)
             return
 
         # The lambda return is non-None when no error fired — narrow it for type-checkers.
         plan = cast(PlannerResultDict, plan)
+        # ``auto`` requests resolve here — the planner echoed its mode choice
+        # (or we infer it from the plan's terminal node). Explicit modes pass
+        # through unchanged. Everything downstream uses the concrete mode.
+        resolved_mode = _resolve_generation_mode(mode, plan)
         plan_nodes: list[dict[str, Any]] = cast(list[dict[str, Any]], plan.get("nodes", []))
         if not plan_nodes:
             empty_plan = _with_mode(
@@ -414,15 +502,12 @@ class WorkflowGenerator:
                     _empty_result(),
                     [_err(WorkflowGenerateErrorCode.EMPTY_PLAN, "Planner returned no nodes")],
                 ),
-                mode,
+                resolved_mode,
             )
             yield "result", cast(dict[str, Any], empty_plan)
             return
 
-        # A single LLM cannot select multiple retrieval outputs as context.
-        # Make the required template fan-in explicit in the plan so the
-        # builder receives its schema and assigns stable sequential ids.
-        cls._insert_multi_retrieval_template_plan(plan_nodes)
+        plan_edges = [cast(dict[str, Any], edge) for edge in (plan.get("edges") or []) if isinstance(edge, dict)]
 
         # Planner-supplied user-input declarations. The builder uses these to
         # populate ``start.data.variables`` so downstream ``{#start.<var>#}``
@@ -436,34 +521,48 @@ class WorkflowGenerator:
 
         # First event the stream sees: the high-level plan, before the slower
         # builder call. Non-streaming callers ignore it.
-        yield "plan", _build_plan_event(plan=plan, plan_nodes=plan_nodes, start_inputs=start_inputs, mode=mode)
+        yield "plan", _build_plan_event(plan=plan, plan_nodes=plan_nodes, start_inputs=start_inputs, mode=resolved_mode)
 
         # ── 2. BUILDER ────────────────────────────────────────────────────
-        graph, build_err = cls._run_stage(
-            stage="Builder",
-            failure_fallback_message="Failed to build workflow graph",
-            run=lambda: cls._run_builder(
+        builder_started_at = time.monotonic()
+
+        def build_graph() -> GraphDict:
+            return cls._run_parallel_node_builders(
                 model_instance=model_instance,
                 model_parameters=model_parameters,
                 provider=provider,
                 model_name=model_name,
                 model_mode=model_mode,
-                mode=mode,
+                mode=resolved_mode,
                 instruction=instruction,
                 ideal_output=ideal_output,
                 plan_nodes=plan_nodes,
+                plan_edges=plan_edges,
                 tool_catalogue_text=tool_catalogue_text,
                 start_inputs=start_inputs,
                 current_graph=current_graph,
-            ),
+            )
+
+        graph, build_err = cls._run_stage(
+            stage="Builder",
+            failure_fallback_message="Failed to build workflow graph",
+            run=build_graph,
+        )
+        logger.info(
+            "Workflow generator: node builders completed nodes=%s elapsed_ms=%.1f",
+            len(plan_nodes),
+            (time.monotonic() - builder_started_at) * 1000,
         )
         if build_err is not None:
-            yield "result", cast(dict[str, Any], _with_mode(_result_with_errors(_empty_result(), [build_err]), mode))
+            yield (
+                "result",
+                cast(dict[str, Any], _with_mode(_result_with_errors(_empty_result(), [build_err]), resolved_mode)),
+            )
             return
         graph = cast(GraphDict, graph)
 
         # ── 3. POSTPROC + VALIDATE ────────────────────────────────────────
-        graph = cls._postprocess_graph(graph=graph, mode=mode)
+        graph = cls._postprocess_graph(graph=graph, mode=resolved_mode)
 
         # ``app_name`` / ``icon`` are planner display metadata; both default
         # to "" when the LLM omits them — the FE owns the fallback.
@@ -475,13 +574,13 @@ class WorkflowGenerator:
             "error": "",
             "errors": [],
         }
-        _with_mode(result, mode)
+        _with_mode(result, resolved_mode)
 
         # Final structural sanity check — fail closed if start/end shape is
         # wrong, container topology is broken, a tool was hallucinated, or a
         # variable reference points at a node that won't expose it. We still
         # return the partial graph so the caller can debug or salvage it.
-        structural_errors = cls._validate_structure(graph=graph, mode=mode, installed_tools=installed_tools)
+        structural_errors = cls._validate_structure(graph=graph, mode=resolved_mode, installed_tools=installed_tools)
         if structural_errors:
             logger.warning("Workflow generator: structural validation failed: %s", structural_errors)
             yield "result", cast(dict[str, Any], _result_with_errors(result, structural_errors))
@@ -622,14 +721,14 @@ class WorkflowGenerator:
         *,
         model_instance,
         model_parameters: dict[str, Any],
-        mode: WorkflowGenerationMode,
+        mode: WorkflowGenerationModeRequest,
         instruction: str,
         ideal_output: str,
         tool_catalogue_text: str,
         current_graph: dict[str, Any] | None = None,
     ) -> PlannerResultDict:
         user_prompt = PLANNER_USER_PROMPT.format(
-            mode=mode,
+            mode=_planner_prompt_mode(mode),
             instruction=instruction.strip(),
             existing_graph_section=format_existing_graph_section(current_graph),
             ideal_output_section=format_ideal_output_section(ideal_output),
@@ -639,59 +738,65 @@ class WorkflowGenerator:
             SystemPromptMessage(content=PLANNER_SYSTEM_PROMPT),
             UserPromptMessage(content=user_prompt),
         ]
+        clamped_parameters = _clamp_for_planner(model_parameters)
         parsed = cls._invoke_and_parse_json(
             model_instance=model_instance,
             messages=messages,
-            model_parameters=_clamp_for_planner(model_parameters),
+            model_parameters=clamped_parameters,
             stage="Planner",
         )
+        try:
+            return cls._validate_planner_schema(parsed)
+        except _StageSchemaError:
+            logger.info("Workflow generator: planner schema invalid; retrying once")
+        parsed = cls._invoke_and_parse_json(
+            model_instance=model_instance,
+            messages=[*messages, UserPromptMessage(content=_PLANNER_SCHEMA_RETRY_HINT)],
+            model_parameters=clamped_parameters,
+            stage="Planner",
+        )
+        return cls._validate_planner_schema(parsed)
 
+    @staticmethod
+    def _validate_planner_schema(parsed: dict[str, Any]) -> PlannerResultDict:
+        """Require the single planner contract consumed by node builders."""
         nodes = parsed.get("nodes")
         if not isinstance(nodes, list):
             raise _StageSchemaError("Planner", "missing 'nodes' array")
+        if not nodes:
+            return cast(PlannerResultDict, parsed)
+
+        node_ids: set[str] = set()
         for node in nodes:
-            if not isinstance(node, dict) or "node_type" not in node:
+            if not isinstance(node, dict) or not node.get("node_type"):
                 raise _StageSchemaError("Planner", f"malformed node entry: {node!r}")
+            node_id = node.get("id")
+            if not isinstance(node_id, str) or not node_id.strip():
+                raise _StageSchemaError("Planner", f"node missing non-empty id: {node!r}")
+            if node_id in node_ids:
+                raise _StageSchemaError("Planner", f"duplicate node id: {node_id!r}")
+            node_ids.add(node_id)
+
+        edges = parsed.get("edges")
+        if not isinstance(edges, list) or not edges:
+            raise _StageSchemaError("Planner", "missing non-empty 'edges' array")
+        for edge in edges:
+            if not isinstance(edge, dict):
+                raise _StageSchemaError("Planner", f"malformed edge entry: {edge!r}")
+            source = edge.get("source")
+            target = edge.get("target")
+            if not isinstance(source, str) or not isinstance(target, str):
+                raise _StageSchemaError("Planner", f"edge missing source or target: {edge!r}")
+            if source not in node_ids or target not in node_ids:
+                raise _StageSchemaError("Planner", f"edge references unknown node: {edge!r}")
 
         return cast(PlannerResultDict, parsed)
 
-    # ------------------------------------------------------------------
-    # Plan normalization
-    # ------------------------------------------------------------------
-    @staticmethod
-    def _insert_multi_retrieval_template_plan(plan_nodes: list[dict[str, Any]]) -> None:
-        """Insert the unambiguous multi-retrieval template step when omitted.
-
-        Multiple LLM nodes make ownership ambiguous, so that case remains in
-        the planner's hands. With exactly one LLM, every independent retrieval
-        result can safely fan into one template immediately before that LLM.
-        """
-        node_types = [str(node.get("node_type") or "") for node in plan_nodes]
-        if node_types.count(BuiltinNodeTypes.KNOWLEDGE_RETRIEVAL) < 2:
-            return
-        if node_types.count(BuiltinNodeTypes.LLM) != 1:
-            return
-        if BuiltinNodeTypes.TEMPLATE_TRANSFORM in node_types:
-            return
-
-        llm_index = node_types.index(BuiltinNodeTypes.LLM)
-        retrievals_before_llm = node_types[:llm_index].count(BuiltinNodeTypes.KNOWLEDGE_RETRIEVAL)
-        if retrievals_before_llm < 2:
-            return
-        plan_nodes.insert(
-            llm_index,
-            {
-                "label": "Combine Knowledge",
-                "node_type": BuiltinNodeTypes.TEMPLATE_TRANSFORM,
-                "purpose": "Combine every knowledge retrieval result into one labelled context for the LLM.",
-            },
-        )
-
     # ------------------------------------------------------------------
     # Builder
     # ------------------------------------------------------------------
     @classmethod
-    def _run_builder(
+    def _run_parallel_node_builders(
         cls,
         *,
         model_instance,
@@ -703,53 +808,275 @@ class WorkflowGenerator:
         instruction: str,
         ideal_output: str,
         plan_nodes: list[dict[str, Any]],
+        plan_edges: list[dict[str, Any]],
         tool_catalogue_text: str,
-        start_inputs: list[dict[str, Any]] | None = None,
-        current_graph: dict[str, Any] | None = None,
+        start_inputs: list[dict[str, Any]],
+        current_graph: dict[str, Any] | None,
     ) -> GraphDict:
-        user_prompt = BUILDER_USER_PROMPT.format(
+        """Build changed node configs concurrently and expand them into a graph.
+
+        Refine plans can mark existing nodes as ``keep``; those nodes bypass
+        the model entirely and retain their full data config. Every other node
+        gets one compact call, with at most ``_node_builder_max_workers()``
+        calls in flight. Any fragment failure aborts the graph, preserving the
+        generator's existing fail-closed contract.
+        """
+        existing_by_id = {
+            str(node.get("id")): node
+            for node in ((current_graph or {}).get("nodes") or [])
+            if isinstance(node, dict) and node.get("id")
+        }
+        existing_edges = [edge for edge in ((current_graph or {}).get("edges") or []) if isinstance(edge, dict)]
+        nodes_to_build = [
+            node for node in plan_nodes if not (node.get("action") == "keep" and str(node.get("id")) in existing_by_id)
+        ]
+
+        # Shared across every builder call in this request — compute once.
+        plan_json = format_parallel_plan(plan_nodes, plan_edges, start_inputs)
+        mode_section = format_mode_section(mode)
+
+        configs_by_id: dict[str, dict[str, Any]] = {}
+        if nodes_to_build:
+            max_workers = min(_node_builder_max_workers(), len(nodes_to_build))
+            with ThreadPoolExecutor(max_workers=max_workers, thread_name_prefix="workflow-node-builder") as executor:
+                futures = {
+                    executor.submit(
+                        cls._run_node_builder,
+                        model_instance=model_instance,
+                        model_parameters=model_parameters,
+                        provider=provider,
+                        model_name=model_name,
+                        model_mode=model_mode,
+                        mode_section=mode_section,
+                        instruction=instruction,
+                        ideal_output=ideal_output,
+                        target_node=node,
+                        plan_json=plan_json,
+                        tool_catalogue_text=tool_catalogue_text,
+                        start_inputs=start_inputs,
+                        existing_node=existing_by_id.get(str(node.get("id"))),
+                    ): str(node.get("id"))
+                    for node in nodes_to_build
+                }
+                try:
+                    for future in as_completed(futures):
+                        node_id = futures[future]
+                        configs_by_id[node_id] = future.result()
+                except BaseException:
+                    # Fail fast: one failed fragment aborts the whole graph, so
+                    # queued builder calls would only burn quota and delay the
+                    # error envelope. In-flight calls cannot be interrupted;
+                    # they finish while the pool shuts down.
+                    for pending in futures:
+                        pending.cancel()
+                    raise
+
+        return cls._assemble_parallel_graph(
+            plan_nodes=plan_nodes,
+            plan_edges=plan_edges,
+            configs_by_id=configs_by_id,
+            existing_by_id=existing_by_id,
+            existing_edges=existing_edges,
+        )
+
+    @classmethod
+    def _run_node_builder(
+        cls,
+        *,
+        model_instance,
+        model_parameters: dict[str, Any],
+        provider: str,
+        model_name: str,
+        model_mode: str,
+        mode_section: str,
+        instruction: str,
+        ideal_output: str,
+        target_node: dict[str, Any],
+        plan_json: str,
+        tool_catalogue_text: str,
+        start_inputs: list[dict[str, Any]],
+        existing_node: dict[str, Any] | None,
+    ) -> dict[str, Any]:
+        """Generate only the semantic config for one normalized plan node."""
+        node_id = str(target_node.get("id") or "")
+        node_type = str(target_node.get("node_type") or "")
+        model_section = ""
+        if node_type in _MODEL_NODE_TYPES:
+            model_section = (
+                f"# Selected model (copy verbatim)\n\nprovider={provider}, name={model_name}, mode={model_mode}\n\n"
+            )
+        existing_config_section = ""
+        if existing_node:
+            existing_data = existing_node.get("data") if isinstance(existing_node.get("data"), dict) else {}
+            existing_config_section = (
+                "# Existing config to preserve unless the instruction changes it\n\n"
+                f"{json.dumps(existing_data, ensure_ascii=False, separators=(',', ':'))}\n\n"
+            )
+        user_prompt = NODE_BUILDER_USER_PROMPT.format(
+            node_id=node_id,
+            node_type=node_type,
+            label=str(target_node.get("label") or ""),
+            purpose=str(target_node.get("purpose") or ""),
             instruction=instruction.strip(),
             ideal_output_section=format_ideal_output_section(ideal_output),
-            existing_graph_section=format_builder_existing_graph_section(current_graph),
-            provider=provider,
-            name=model_name,
-            mode_label=model_mode,
-            plan_block=format_plan_block(plan_nodes),
-            tool_catalogue_section=format_builder_tool_catalogue_section(tool_catalogue_text),
-            start_inputs_section=format_start_inputs_section(start_inputs or []),
+            mode_section=mode_section,
+            model_section=model_section,
+            tool_catalogue_section=(
+                format_node_tool_catalogue_section(tool_catalogue_text) if node_type == BuiltinNodeTypes.TOOL else ""
+            ),
+            start_inputs_section=(
+                format_start_inputs_section(start_inputs) if node_type == BuiltinNodeTypes.START else ""
+            ),
+            existing_config_section=existing_config_section,
+            plan_json=plan_json,
         )
-        # Scope the builder cheatsheet to exactly the node types the planner
-        # chose, so the prompt carries each type's FULL schema (e.g. a file
-        # start variable's required ``allowed_file_types``) without dragging in
-        # config for unrelated node types.
-        plan_node_types = {
-            str(node.get("node_type") or "").strip() for node in plan_nodes if str(node.get("node_type") or "").strip()
-        }
-        messages = [
-            SystemPromptMessage(content=get_builder_system_prompt(mode, plan_node_types)),
-            UserPromptMessage(content=user_prompt),
-        ]
         parsed = cls._invoke_and_parse_json(
             model_instance=model_instance,
-            messages=messages,
+            messages=[
+                SystemPromptMessage(content=get_node_builder_system_prompt(node_type)),
+                UserPromptMessage(content=user_prompt),
+            ],
             model_parameters=model_parameters,
-            stage="Builder",
+            stage=f"Builder {node_id}",
         )
+        config = parsed.get("config")
+        if not isinstance(config, dict):
+            raise _StageSchemaError(f"Builder {node_id}", "missing 'config' object")
+        return cast(dict[str, Any], config)
 
-        nodes = parsed.get("nodes")
-        edges = parsed.get("edges")
-        if not isinstance(nodes, list) or not isinstance(edges, list):
-            raise _StageSchemaError("Builder", "graph missing 'nodes' or 'edges' arrays")
+    @classmethod
+    def _assemble_parallel_graph(
+        cls,
+        *,
+        plan_nodes: list[dict[str, Any]],
+        plan_edges: list[dict[str, Any]],
+        configs_by_id: dict[str, dict[str, Any]],
+        existing_by_id: dict[str, dict[str, Any]],
+        existing_edges: list[dict[str, Any]] | None = None,
+    ) -> GraphDict:
+        """Expand compact node configs and planner topology into graph JSON.
 
-        viewport = parsed.get("viewport") or _DEFAULT_VIEWPORT
-        return cast(
-            GraphDict,
-            {
-                "nodes": nodes,
-                "edges": edges,
-                "viewport": viewport,
-            },
-        )
+        ``existing_edges`` (refine only) preserves wiring the planner cannot
+        express: the synthetic ``<container>start`` entry edge keeps its
+        existing target instead of being re-pointed at whichever child the
+        planner happened to list first.
+        """
+        label_to_id = {
+            str(node.get("label")): str(node.get("id")) for node in plan_nodes if node.get("label") and node.get("id")
+        }
+        type_by_id = {str(node.get("id")): str(node.get("node_type") or "") for node in plan_nodes}
+        children_by_parent: dict[str, list[str]] = {}
+        nodes: list[dict[str, Any]] = []
+
+        for planned in plan_nodes:
+            node_id = str(planned.get("id") or "")
+            node_type = str(planned.get("node_type") or "")
+            existing = existing_by_id.get(node_id)
+            node: dict[str, Any]
+            if planned.get("action") == "keep" and existing is not None:
+                node = deepcopy(existing)
+            else:
+                config = dict(configs_by_id.get(node_id) or {})
+                for shared_key in ("type", "title", "desc", "selected"):
+                    config.pop(shared_key, None)
+                data: dict[str, Any] = {
+                    "type": node_type,
+                    "title": str(planned.get("label") or node_id),
+                    "desc": str(planned.get("purpose") or ""),
+                    **config,
+                }
+                node = deepcopy(existing) if existing is not None else {"id": node_id}
+                node["id"] = node_id
+                node["data"] = data
+
+            parent_ref = str(planned.get("parent") or "")
+            parent_id = label_to_id.get(parent_ref, parent_ref)
+            if not parent_id and str(node.get("parentId") or "") in type_by_id:
+                # Kept nodes rarely re-state containment — recover the parent
+                # from the deepcopied wrapper so entry-edge synthesis still
+                # counts this child.
+                parent_id = str(node["parentId"])
+            if parent_id:
+                child_index = len(children_by_parent.get(parent_id, []))
+                node["parentId"] = parent_id
+                node.setdefault("position", {"x": 240 + 260 * child_index, "y": 60})
+                node.setdefault("data", {})
+                parent_type = type_by_id.get(parent_id)
+                if parent_type == BuiltinNodeTypes.ITERATION:
+                    node["data"].setdefault("isInIteration", True)
+                    node["data"].setdefault("iteration_id", parent_id)
+                elif parent_type == BuiltinNodeTypes.LOOP:
+                    node["data"].setdefault("isInLoop", True)
+                    node["data"].setdefault("loop_id", parent_id)
+                children_by_parent.setdefault(parent_id, []).append(node_id)
+            elif node.get("parentId"):
+                # The container was dropped from the plan: strip the stale
+                # containment markers so the kept node rejoins the top level
+                # (and its auto-layout) instead of pointing at a deleted parent.
+                for wrapper_key in ("parentId", "extent", "zIndex", "position", "positionAbsolute"):
+                    node.pop(wrapper_key, None)
+                if isinstance(node.get("data"), dict):
+                    for marker_key in ("isInIteration", "iteration_id", "isInLoop", "loop_id"):
+                        node["data"].pop(marker_key, None)
+
+            nodes.append(node)
+            if node_type in cls._CONTAINER_TYPES:
+                start_id = f"{node_id}start"
+                node.setdefault("data", {})["start_node_id"] = start_id
+                node.setdefault("width", 808)
+                node.setdefault("height", 204)
+                node.setdefault("zIndex", 1)
+                is_iteration = node_type == BuiltinNodeTypes.ITERATION
+                nodes.append(
+                    {
+                        "id": start_id,
+                        "type": "custom-iteration-start" if is_iteration else "custom-loop-start",
+                        "parentId": node_id,
+                        "extent": "parent",
+                        "draggable": False,
+                        "selectable": False,
+                        "zIndex": 1002,
+                        "position": {"x": 60, "y": 78},
+                        "data": {
+                            "type": "iteration-start" if is_iteration else "loop-start",
+                            "title": "",
+                            "desc": "",
+                            "selected": False,
+                            "isInIteration" if is_iteration else "isInLoop": True,
+                        },
+                    }
+                )
+
+        edges: list[dict[str, Any]] = []
+        for planned_edge in plan_edges:
+            edge: dict[str, Any] = {
+                "source": str(planned_edge.get("source") or ""),
+                "target": str(planned_edge.get("target") or ""),
+            }
+            source_handle = planned_edge.get("source_handle") or planned_edge.get("sourceHandle")
+            target_handle = planned_edge.get("target_handle") or planned_edge.get("targetHandle")
+            if source_handle:
+                edge["sourceHandle"] = str(source_handle)
+            if target_handle:
+                edge["targetHandle"] = str(target_handle)
+            edges.append(edge)
+
+        # Synthesize each container's entry edge. Refine keeps the existing
+        # entry target when it is still a child — the planner's node listing
+        # order says nothing about execution order inside a kept container.
+        planned_sources = {str(edge.get("source") or "") for edge in edges}
+        existing_entry_targets = {
+            str(edge.get("source") or ""): str(edge.get("target") or "") for edge in (existing_edges or [])
+        }
+        for parent_id, child_ids in children_by_parent.items():
+            start_id = f"{parent_id}start"
+            if not child_ids or start_id in planned_sources:
+                continue
+            preferred = existing_entry_targets.get(start_id, "")
+            entry_target = preferred if preferred in child_ids else child_ids[0]
+            edges.append({"source": start_id, "target": entry_target})
+
+        return cast(GraphDict, {"nodes": nodes, "edges": edges, "viewport": _DEFAULT_VIEWPORT})
 
     # ------------------------------------------------------------------
     # Postprocessing
@@ -1225,6 +1552,11 @@ class WorkflowGenerator:
             return var == "output"
         if node_type == BuiltinNodeTypes.LIST_OPERATOR:
             return var in {"result", "first_record", "last_record"}
+        if node_type == BuiltinNodeTypes.HUMAN_INPUT:
+            return any(
+                isinstance(item, dict) and item.get("output_variable_name") == var
+                for item in (data.get("inputs") or [])
+            )
         # Other node types (if-else, iteration-start, loop-start, ...) don't
         # produce outputs of their own.
         return False
@@ -1247,6 +1579,15 @@ class WorkflowGenerator:
                 if isinstance(parameter, dict) and isinstance(parameter.get("name"), str)
             ]
             return parameters[0] if len(parameters) == 1 else None
+        if node_type == BuiltinNodeTypes.HUMAN_INPUT:
+            human_outputs: list[str] = []
+            for item in data.get("inputs") or []:
+                if not isinstance(item, dict):
+                    continue
+                output_name = item.get("output_variable_name")
+                if isinstance(output_name, str):
+                    human_outputs.append(output_name)
+            return human_outputs[0] if len(human_outputs) == 1 else None
         if not isinstance(node_type, str):
             return None
         single_output_by_type: dict[str, str] = {
@@ -1533,6 +1874,12 @@ class WorkflowGenerator:
                     for klass in (data.get("classes") or [])
                     if isinstance(klass, dict) and klass.get("id")
                 ]
+            elif node_type == BuiltinNodeTypes.HUMAN_INPUT:
+                branch_handles = [
+                    str(action["id"])
+                    for action in (data.get("user_actions") or [])
+                    if isinstance(action, dict) and action.get("id")
+                ]
             else:
                 continue
 
@@ -1941,8 +2288,8 @@ class WorkflowGenerator:
         """
         Validate iteration / loop topology:
 
-          * every container has at least one child whose ``parentId``
-            points at it;
+          * every container has at least one executable child whose
+            ``parentId`` points at it;
           * every non-container node with a ``parentId`` points at a real
             container, not at a non-container node;
           * no cycles in the parent chain (a node cannot be its own
@@ -1959,7 +2306,9 @@ class WorkflowGenerator:
             if not isinstance(parent, str) or not parent:
                 continue
             if parent in container_ids:
-                children_by_parent.setdefault(parent, []).append(n.get("id", ""))
+                node_type = (n.get("data") or {}).get("type")
+                if node_type not in {"iteration-start", "loop-start"}:
+                    children_by_parent.setdefault(parent, []).append(n.get("id", ""))
             elif parent in by_id:
                 # Parent exists but isn't a container — that's a topology bug.
                 out.append(

api/core/workflow/generator/types.py

@@ -1,10 +1,10 @@
 """
 Typed payloads for workflow generation.
 
-These TypedDicts describe the shape that the planner and builder LLM calls are
-required to return after ``json_repair`` parsing. They mirror the runtime
-``graph`` shape consumed by ``WorkflowService.sync_draft_workflow`` so the output
-can be written straight into a draft workflow without further translation.
+These TypedDicts describe the planner payload and the runtime graph assembled
+from builder LLM responses after ``json_repair`` parsing. The graph types mirror
+the shape consumed by ``WorkflowService.sync_draft_workflow`` so the output can
+be written straight into a draft workflow.
 """
 
 from enum import StrEnum
@@ -12,11 +12,10 @@ from typing import Literal, NotRequired, TypedDict
 
 WorkflowGenerationMode = Literal["workflow", "advanced-chat"]
 
-# The mode accepted at the API boundary. ``auto`` is a sentinel that asks the
-# service to classify the instruction into a concrete ``WorkflowGenerationMode``
-# (one tiny LLM call) BEFORE planning — see
-# ``WorkflowGeneratorService._resolve_mode`` and
-# ``LLMGenerator.classify_workflow_mode``.
+# The mode accepted at the API boundary. ``auto`` is a sentinel that delegates
+# the choice to the planner: it echoes a concrete mode in its ``mode`` output
+# field (falling back to terminal-node inference, then ``advanced-chat``) —
+# see ``runner._resolve_generation_mode``. No extra LLM call is involved.
 WorkflowGenerationModeRequest = Literal["workflow", "advanced-chat", "auto"]
 
 
@@ -58,9 +57,21 @@ class WorkflowGenerateErrorDict(TypedDict):
 class PlannerNodeDict(TypedDict):
     """One node from the planner's high-level plan."""
 
+    id: NotRequired[str]
     label: str
     node_type: str
     purpose: str
+    parent: NotRequired[str]
+    action: NotRequired[Literal["keep", "update", "add"]]
+
+
+class PlannerEdgeDict(TypedDict):
+    """Compact topology emitted by the planner for parallel node building."""
+
+    source: str
+    target: str
+    source_handle: NotRequired[str]
+    target_handle: NotRequired[str]
 
 
 class PlannerStartInputDict(TypedDict):
@@ -82,10 +93,15 @@ class PlannerResultDict(TypedDict):
 
     title: str
     description: str
+    # Concrete mode the planner chose ("workflow" / "advanced-chat"). Parsed
+    # leniently — an ``auto`` request infers the mode from the terminal node
+    # when this is missing or invalid, so a bad value never fails the plan.
+    mode: NotRequired[str]
     app_name: NotRequired[str]
     icon: NotRequired[str]
     start_inputs: NotRequired[list[PlannerStartInputDict]]
     nodes: list[PlannerNodeDict]
+    edges: NotRequired[list[PlannerEdgeDict]]
 
 
 class GraphNodePositionDict(TypedDict):

api/core/workflow/node_factory.py

@@ -499,6 +499,9 @@ class DifyNodeFactory(NodeFactory):
                     base_url=dify_config.AGENT_BACKEND_BASE_URL,
                     use_fake=dify_config.AGENT_BACKEND_USE_FAKE,
                     fake_scenario=dify_config.AGENT_BACKEND_FAKE_SCENARIO,
+                    stream_read_timeout_seconds=dify_config.AGENT_BACKEND_STREAM_READ_TIMEOUT_SECONDS,
+                    stream_max_reconnects=dify_config.AGENT_BACKEND_STREAM_MAX_RECONNECTS,
+                    stream_run_timeout_seconds=dify_config.AGENT_BACKEND_RUN_TIMEOUT_SECONDS,
                 ),
                 "event_adapter": AgentBackendRunEventAdapter(),
                 # Agent Files §4.6: reback file outputs from the ToolFile row so

api/core/workflow/node_runtime.py

@@ -493,6 +493,7 @@ class DifyToolNodeRuntime(ToolNodeRuntimeProtocol):
                 self._run_context.invoke_from,
                 variable_pool,
             )
+            tool_runtime.runtime.dify_run_context = self._run_context
         except ToolNodeError:
             raise
         except Exception as exc:

api/core/workflow/nodes/agent_v2/agent_node.py

@@ -5,6 +5,7 @@ from collections.abc import Generator, Mapping, Sequence
 from typing import TYPE_CHECKING, Any, override
 
 from agenton.compositor import CompositorSessionSnapshot
+from dify_agent.protocol import CancelRunRequest
 
 from clients.agent_backend import (
     AgentBackendAgentMessageDeltaInternalEvent,
@@ -473,7 +474,10 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
         """
         stream_event_count = 0
         try:
-            for public_event in self._agent_backend_client.stream_events(run_id):
+            for public_event in self._agent_backend_client.stream_events(
+                run_id,
+                should_stop=self._is_graph_aborted,
+            ):
                 stream_event_count += 1
                 for internal_event in self._event_adapter.adapt(public_event):
                     if internal_event.type == AgentBackendInternalEventType.RUN_STARTED:
@@ -501,6 +505,7 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
                         | AgentBackendDeferredToolCallInternalEvent,
                     ):
                         return internal_event, None
+                    self._cancel_backend_run(run_id, reason="unexpected_event")
                     return None, self._failure_event(
                         inputs={},
                         process_data={},
@@ -509,6 +514,7 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
                         error_type="agent_backend_stream_error",
                     )
         except AgentBackendError as error:
+            self._cancel_backend_run(run_id, reason=self._stream_stop_reason())
             return None, self._failure_event(
                 inputs={},
                 process_data={},
@@ -517,6 +523,7 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
                 error_type=self._agent_backend_error_type(error),
             )
         except Exception as error:
+            self._cancel_backend_run(run_id, reason=self._stream_stop_reason())
             return None, self._failure_event(
                 inputs={},
                 process_data={},
@@ -525,8 +532,28 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
                 error_type="agent_backend_stream_error",
             )
 
+        self._cancel_backend_run(run_id, reason="stream_ended_without_terminal_event")
         return None, None
 
+    def _is_graph_aborted(self) -> bool:
+        """Let Agent SSE consumption observe GraphEngine's cooperative abort state."""
+        try:
+            return self.graph_runtime_state.graph_execution.aborted
+        except (AttributeError, RuntimeError):
+            return False
+
+    def _stream_stop_reason(self) -> str:
+        return "workflow_graph_aborted" if self._is_graph_aborted() else "event_stream_failed"
+
+    def _cancel_backend_run(self, run_id: str, *, reason: str) -> None:
+        try:
+            self._agent_backend_client.cancel_run(
+                run_id,
+                CancelRunRequest(reason=reason, message="Workflow Agent event consumption stopped"),
+            )
+        except Exception:
+            logger.warning("Failed to cancel Workflow Agent backend run: run_id=%s", run_id, exc_info=True)
+
     @staticmethod
     def _record_type_check_metadata(metadata: dict[str, Any], outcome: OutputTypeCheckOutcome) -> None:
         # Surface enough detail in metadata for Inspector / debug logs without

api/core/workflow/nodes/agent_v2/runtime_request_builder.py

@@ -250,6 +250,7 @@ class WorkflowAgentRuntimeRequestBuilder:
                     agent_config_version_kind="snapshot",
                     agent_mode=self._agent_backend_agent_mode(context.dify_context.invoke_from),
                     invoke_from=cast(DifyExecutionContextInvokeFrom, context.dify_context.invoke_from.value),
+                    trace_id=context.dify_context.trace_session_id,
                 ),
                 agent_soul_prompt=soul_prompt or None,
                 workflow_node_job_prompt=workflow_job_prompt,

api/core/workflow/nodes/agent_v2/validators.py

@@ -61,16 +61,33 @@ class WorkflowAgentNodeValidator:
 
     @classmethod
     def validate_draft_workflow(cls, *, session: Session, workflow: Workflow) -> None:
-        cls._validate_workflow(session=session, workflow=workflow, require_binding=False)
+        cls._validate_workflow(
+            session=session,
+            workflow=workflow,
+            require_binding=False,
+            validate_previous_node_topology=False,
+        )
 
     @classmethod
     def validate_published_workflow(cls, *, session: Session, workflow: Workflow) -> None:
-        cls._validate_workflow(session=session, workflow=workflow, require_binding=True)
+        cls._validate_workflow(
+            session=session,
+            workflow=workflow,
+            require_binding=True,
+            validate_previous_node_topology=True,
+        )
 
     @classmethod
-    def _validate_workflow(cls, *, session: Session, workflow: Workflow, require_binding: bool) -> None:
+    def _validate_workflow(
+        cls,
+        *,
+        session: Session,
+        workflow: Workflow,
+        require_binding: bool,
+        validate_previous_node_topology: bool,
+    ) -> None:
         graph = workflow.graph_dict
-        topology = _WorkflowGraphTopology.from_graph(graph)
+        topology = _WorkflowGraphTopology.from_graph(graph) if validate_previous_node_topology else None
         for node_id, node_data in cls.iter_agent_v2_nodes(graph):
             cls._validate_node_schema(node_id=node_id, node_data=node_data)
             binding = cls._find_binding(
@@ -185,12 +202,12 @@ class WorkflowAgentNodeValidator:
                 raise WorkflowAgentNodeValidationError(
                     f"Workflow Agent node {binding.node_id} has invalid previous node output ref."
                 )
-            if topology is None:
-                continue
             if len(selector) < 2:
                 raise WorkflowAgentNodeValidationError(
                     f"Workflow Agent node {binding.node_id} has incomplete previous node output ref."
                 )
+            if topology is None:
+                continue
             source_node_id = selector[0]
             if not topology.has_node(source_node_id):
                 raise WorkflowAgentNodeValidationError(

api/dev/check_knowledge_fs_coverage.py

@@ -0,0 +1,346 @@
+"""Enforce focused KnowledgeFS coverage without hiding integration-critical glue.
+
+The primary threshold aggregates statement and branch coverage for every Dify
+module owned by the KnowledgeFS integration. Large pre-existing Dify modules
+that only contain narrow integration hooks are checked with changed-line
+coverage instead, so unrelated legacy code cannot dilute or inflate the gate.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TypedDict, cast
+
+WORKSPACE_ROOT = Path(__file__).resolve().parents[2]
+NON_CORE_COVERAGE_ALLOWLIST = frozenset(
+    {
+        "api/dev/check_knowledge_fs_coverage.py",
+        "api/dev/generate_knowledge_fs_contract.py",
+        "api/dev/knowledge_fs_product_contract.py",
+        "api/migrations/versions/2026_07_21_1200-a4e7c2f91b30_add_knowledge_fs_control_plane.py",
+        "api/migrations/versions/2026_07_21_1300-b7f2a9d41c60_add_knowledge_fs_cutover.py",
+        "api/migrations/versions/2026_07_21_1400-c8e31b7d52a4_add_knowledge_fs_cleanup_authorization.py",
+    }
+)
+HUNK_HEADER = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@")
+logger = logging.getLogger(__name__)
+
+
+class CoverageSummary(TypedDict):
+    """Coverage.py counts required by the aggregate gate."""
+
+    covered_lines: int
+    num_statements: int
+    covered_branches: int
+    num_branches: int
+
+
+class CoverageFile(TypedDict):
+    """Per-file coverage data emitted by ``coverage json``."""
+
+    executed_lines: list[int]
+    missing_lines: list[int]
+    summary: CoverageSummary
+
+
+class CoverageReport(TypedDict):
+    """Relevant top-level shape of a coverage.py JSON report."""
+
+    files: dict[str, CoverageFile]
+
+
+@dataclass(frozen=True, slots=True)
+class CoverageTotals:
+    """Covered and measurable units for one gate surface."""
+
+    covered: int
+    total: int
+
+    @property
+    def percent(self) -> float:
+        return 100.0 if self.total == 0 else self.covered * 100 / self.total
+
+
+class CoverageGateError(RuntimeError):
+    """Raised when coverage input is incomplete or below its threshold."""
+
+
+def main() -> None:
+    """Validate focused module coverage and changed integration glue."""
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--coverage-json", type=Path, required=True)
+    parser.add_argument("--glue-manifest", type=Path, required=True)
+    parser.add_argument("--workspace-root", type=Path, default=WORKSPACE_ROOT)
+    parser.add_argument("--base", default="")
+    parser.add_argument("--minimum", type=float, default=90.0)
+    parser.add_argument("--glue-minimum", type=float, default=90.0)
+    args = parser.parse_args()
+
+    workspace_root = args.workspace_root.resolve()
+    report = load_coverage_report(args.coverage_json)
+    core_totals = validate_core_coverage(report, workspace_root=workspace_root, minimum=args.minimum)
+    base = resolve_diff_base(workspace_root, args.base)
+    glue_paths = load_glue_coverage_paths(args.glue_manifest, workspace_root=workspace_root)
+    changed_lines = collect_changed_glue_lines(workspace_root, base, glue_paths=glue_paths)
+    glue_totals = validate_changed_glue_coverage(
+        report,
+        changed_lines=changed_lines,
+        minimum=args.glue_minimum,
+    )
+    logger.info(
+        "Dify KnowledgeFS coverage passed: core lines+branches %.2f%% (%d/%d); changed glue lines %.2f%% (%d/%d)",
+        core_totals.percent,
+        core_totals.covered,
+        core_totals.total,
+        glue_totals.percent,
+        glue_totals.covered,
+        glue_totals.total,
+    )
+
+
+def load_coverage_report(path: Path) -> CoverageReport:
+    """Load the detailed JSON report used by both coverage checks."""
+    if not path.is_file():
+        raise CoverageGateError(f"coverage JSON does not exist: {path}")
+    document = json.loads(path.read_text())
+    if not isinstance(document, dict) or not isinstance(document.get("files"), dict):
+        raise CoverageGateError(f"coverage JSON has no files object: {path}")
+    return cast(CoverageReport, document)
+
+
+def load_glue_coverage_paths(path: Path, *, workspace_root: Path) -> tuple[str, ...]:
+    """Load the workflow's authoritative NUL-delimited integration touchpoints."""
+    if not path.is_file():
+        raise CoverageGateError(f"KnowledgeFS glue manifest does not exist: {path}")
+    try:
+        paths = tuple(item.decode() for item in path.read_bytes().split(b"\0") if item)
+    except UnicodeDecodeError as error:
+        raise CoverageGateError(f"KnowledgeFS glue manifest is not UTF-8: {path}") from error
+    if not paths:
+        raise CoverageGateError("Dify KnowledgeFS glue coverage target set is empty")
+    if len(paths) != len(set(paths)):
+        raise CoverageGateError("Dify KnowledgeFS glue coverage manifest contains duplicate paths")
+    invalid_paths = [
+        candidate
+        for candidate in paths
+        if not candidate.startswith("api/")
+        or not candidate.endswith(".py")
+        or not (workspace_root / candidate).is_file()
+    ]
+    if invalid_paths:
+        raise CoverageGateError(f"Dify KnowledgeFS glue coverage paths are invalid: {', '.join(invalid_paths)}")
+    return paths
+
+
+def is_core_coverage_path(path: str) -> bool:
+    """Return whether a repository-relative path belongs to the focused aggregate."""
+    if not path.endswith(".py"):
+        return False
+    if path in {
+        "api/commands/knowledge_fs.py",
+        "api/configs/extra/knowledge_fs_config.py",
+        "api/extensions/ext_knowledge_fs_observability.py",
+        "api/services/knowledge_fs_capability.py",
+    }:
+        return True
+    if path.startswith(
+        (
+            "api/controllers/console/knowledge_fs/",
+            "api/controllers/service_api/knowledge_fs/",
+            "api/core/tools/builtin_tool/providers/knowledge_fs/",
+            "api/services/knowledge_fs/",
+        )
+    ):
+        return True
+    filename = path.rsplit("/", maxsplit=1)[-1]
+    return (
+        path.startswith("api/models/")
+        and filename.startswith("knowledge_fs")
+        or path.startswith("api/repositories/")
+        and "knowledge_fs" in filename
+        or path.startswith("api/tasks/")
+        and "knowledge_fs" in filename
+    )
+
+
+def discover_core_coverage_paths(workspace_root: Path) -> tuple[str, ...]:
+    """Classify every KnowledgeFS-named production file or fail closed."""
+    named_paths = discover_knowledge_fs_production_paths(workspace_root)
+    core_paths = {path for path in named_paths if is_core_coverage_path(path)}
+    unclassified_paths = set(named_paths) - core_paths - NON_CORE_COVERAGE_ALLOWLIST
+    if unclassified_paths:
+        raise CoverageGateError(
+            "unclassified Dify KnowledgeFS production files must join the core coverage scope or explicit allowlist: "
+            + ", ".join(sorted(unclassified_paths))
+        )
+    if not core_paths:
+        raise CoverageGateError("Dify KnowledgeFS core coverage target set is empty")
+    return tuple(sorted(core_paths))
+
+
+def discover_knowledge_fs_production_paths(workspace_root: Path) -> tuple[str, ...]:
+    """Mirror the workflow's dynamic KnowledgeFS filename discovery."""
+    api_root = workspace_root / "api"
+    if not api_root.is_dir():
+        raise CoverageGateError(f"Dify API directory does not exist: {api_root}")
+    paths: set[str] = set()
+    for directory, child_directories, filenames in os.walk(api_root):
+        current_directory = Path(directory)
+        if current_directory == api_root:
+            child_directories[:] = [name for name in child_directories if name not in {".venv", "storage", "tests"}]
+        child_directories[:] = [name for name in child_directories if name != "__pycache__"]
+        for filename in filenames:
+            path = (current_directory / filename).relative_to(workspace_root).as_posix()
+            if filename.endswith(".py") and "knowledge_fs" in path:
+                paths.add(path)
+    if not paths:
+        raise CoverageGateError("Dify KnowledgeFS production target set is empty")
+    return tuple(sorted(paths))
+
+
+def validate_core_coverage(
+    report: CoverageReport,
+    *,
+    workspace_root: Path,
+    minimum: float,
+) -> CoverageTotals:
+    """Require the exact combined line-and-branch percentage for all core files."""
+    paths = discover_core_coverage_paths(workspace_root)
+    missing_paths = [path for path in paths if path not in report["files"]]
+    if missing_paths:
+        raise CoverageGateError(f"coverage report is missing core files: {', '.join(missing_paths)}")
+
+    covered = 0
+    total = 0
+    for path in paths:
+        summary = report["files"][path]["summary"]
+        covered += summary["covered_lines"] + summary["covered_branches"]
+        total += summary["num_statements"] + summary["num_branches"]
+    if total == 0:
+        raise CoverageGateError("Dify KnowledgeFS core coverage has no measurable statements or branches")
+
+    totals = CoverageTotals(covered=covered, total=total)
+    _require_minimum(totals, minimum=minimum, label="Dify KnowledgeFS core line-and-branch coverage")
+    return totals
+
+
+def resolve_diff_base(workspace_root: Path, preferred: str) -> str:
+    """Resolve an explicit event base, falling back to the previous commit for manual runs."""
+    base = preferred.strip()
+    if not base or set(base) == {"0"}:
+        base = "HEAD^"
+    result = subprocess.run(
+        ["git", "cat-file", "-e", f"{base}^{{commit}}"],
+        cwd=workspace_root,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        detail = result.stderr.strip() or "commit is unavailable"
+        raise CoverageGateError(f"cannot resolve coverage diff base {base}: {detail}")
+    return base
+
+
+def collect_changed_glue_lines(
+    workspace_root: Path,
+    base: str,
+    *,
+    glue_paths: tuple[str, ...],
+) -> dict[str, set[int]]:
+    """Return added line numbers in the narrow Dify modules touched by this integration."""
+    result = subprocess.run(
+        [
+            "git",
+            "diff",
+            "--no-ext-diff",
+            "--no-color",
+            "--unified=0",
+            base,
+            "--",
+            *glue_paths,
+        ],
+        cwd=workspace_root,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        detail = result.stderr.strip() or "git diff failed"
+        raise CoverageGateError(f"cannot collect KnowledgeFS glue diff from {base}: {detail}")
+    return parse_added_lines(result.stdout)
+
+
+def parse_added_lines(diff: str) -> dict[str, set[int]]:
+    """Parse repository paths and added-side line numbers from a zero-context Git diff."""
+    changed_lines: dict[str, set[int]] = {}
+    current_path: str | None = None
+    current_line: int | None = None
+    for raw_line in diff.splitlines():
+        if raw_line.startswith("diff --git "):
+            current_line = None
+            continue
+        if raw_line.startswith("+++ "):
+            candidate = raw_line[4:]
+            current_path = candidate[2:] if candidate.startswith("b/") else None
+            if current_path is not None:
+                changed_lines.setdefault(current_path, set())
+            current_line = None
+            continue
+        if raw_line.startswith("@@ "):
+            match = HUNK_HEADER.match(raw_line)
+            current_line = int(match.group(1)) if match is not None else None
+            continue
+        if current_path is None or current_line is None:
+            continue
+        if raw_line.startswith("+"):
+            changed_lines[current_path].add(current_line)
+            current_line += 1
+        elif raw_line.startswith("-") or raw_line.startswith("\\"):
+            continue
+        else:
+            current_line += 1
+    return changed_lines
+
+
+def validate_changed_glue_coverage(
+    report: CoverageReport,
+    *,
+    changed_lines: dict[str, set[int]],
+    minimum: float,
+) -> CoverageTotals:
+    """Require added executable glue lines to be exercised by the focused unit suite."""
+    covered = 0
+    total = 0
+    for path, lines in sorted(changed_lines.items()):
+        if not lines:
+            continue
+        file_coverage = report["files"].get(path)
+        if file_coverage is None:
+            raise CoverageGateError(f"coverage report is missing changed glue file: {path}")
+        executed_lines = set(file_coverage["executed_lines"])
+        executable_lines = executed_lines | set(file_coverage["missing_lines"])
+        changed_executable_lines = lines & executable_lines
+        covered += len(changed_executable_lines & executed_lines)
+        total += len(changed_executable_lines)
+
+    totals = CoverageTotals(covered=covered, total=total)
+    _require_minimum(totals, minimum=minimum, label="Dify KnowledgeFS changed-glue line coverage")
+    return totals
+
+
+def _require_minimum(totals: CoverageTotals, *, minimum: float, label: str) -> None:
+    if totals.percent + 1e-12 < minimum:
+        raise CoverageGateError(f"{label} is {totals.percent:.2f}%; minimum {minimum:.2f}%")
+
+
+if __name__ == "__main__":
+    main()

api/dev/generate_knowledge_fs_contract.py

@@ -0,0 +1,732 @@
+"""Pin the in-repository KnowledgeFS contract and validate every Dify product operation.
+
+The lock is intentionally independent of the enclosing Dify commit: it records the staged ``knowledge-fs/`` tree,
+the complete generated OpenAPI document, both explicit product-operation manifests, and the active Capability v2
+profile and deterministic public-key vector. The full OpenAPI hash
+covers request/response schemas, status codes, security, deprecation, and stream metadata. Field-level validation
+cross-checks the Dify product registry, Python Capability issuer, TypeScript request guard, and exported OpenAPI;
+each product operation must be ready or an explicit gap, and KFS-only activation remains explicitly internal.
+
+Contract export reads the working tree only after proving it matches the staged KnowledgeFS index. This keeps the
+OpenAPI bytes and auth manifest aligned with the exact subtree tree ID that will be reviewed and committed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any, Literal, TypedDict, cast
+
+import jwt
+from cryptography.hazmat.primitives.asymmetric.rsa import RSAPublicKey
+from jwt.algorithms import RSAAlgorithm
+
+API_ROOT = Path(__file__).resolve().parents[1]
+if str(API_ROOT) not in sys.path:
+    sys.path.insert(0, str(API_ROOT))
+
+from dev.knowledge_fs_product_contract import (
+    capability_operation_runtime_contracts,
+    parse_capability_operation_policy,
+    parse_product_operation_gap_manifest,
+    parse_product_operation_manifest,
+    product_operation_runtime_contracts,
+    validate_product_operation_contracts,
+)
+
+WORKSPACE_ROOT = API_ROOT.parent
+KNOWLEDGE_FS_DIRECTORY = "knowledge-fs"
+CAPABILITY_V2_AUTH_MANIFEST_RELATIVE_PATH = Path("contracts/dify-capability-v2-auth-profile.json")
+CAPABILITY_V2_AUTH_TEST_VECTOR_RELATIVE_PATH = Path("contracts/dify-capability-v2-test-vector.json")
+UPSTREAM_PROVENANCE_RELATIVE_PATH = Path("upstream-provenance.json")
+LOCK_RELATIVE_PATH = Path("api/knowledge-fs-contract.lock.json")
+PRODUCT_OPERATIONS_RELATIVE_PATH = Path("api/knowledge-fs-product-operations.json")
+PRODUCT_OPERATION_GAPS_RELATIVE_PATH = Path("api/knowledge-fs-product-operation-gaps.json")
+OPENAPI_METHODS = ("delete", "get", "head", "options", "patch", "post", "put", "trace")
+PROXY_METHODS = frozenset({"delete", "get", "patch", "post", "put"})
+LOCK_SCHEMA_VERSION = 5
+
+
+class ContractDeclaration(TypedDict):
+    """KnowledgeFS transport contract declared by one Dify Console registry entry."""
+
+    operation_id: str
+    method: str
+    path: str
+    required_scope: str | None
+    response_kind: str
+    max_response_bytes: int
+    request_headers: tuple[str, ...]
+    response_headers: tuple[str, ...]
+    response_media_types: tuple[str, ...]
+
+
+class ContractLock(TypedDict):
+    """Content-addressed contract inputs that must move together."""
+
+    schemaVersion: int
+    subtreeTree: str
+    openapiSha256: str
+    capabilityV2AuthManifestSha256: str
+    capabilityV2AuthTestVectorSha256: str
+    productOperationManifestSha256: str
+    productOperationGapManifestSha256: str
+
+
+type DeclarationField = Literal[
+    "method",
+    "path",
+    "required_scope",
+    "response_kind",
+    "max_response_bytes",
+    "request_headers",
+    "response_headers",
+    "response_media_types",
+]
+
+DECLARATION_FIELDS: tuple[DeclarationField, ...] = (
+    "method",
+    "path",
+    "required_scope",
+    "response_kind",
+    "max_response_bytes",
+    "request_headers",
+    "response_headers",
+    "response_media_types",
+)
+
+
+def main() -> None:
+    """Update or verify the monorepo pin and validate Dify product declarations."""
+    parser = argparse.ArgumentParser()
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--check", action="store_true")
+    mode.add_argument("--update-lock", action="store_true")
+    parser.add_argument("--workspace-root", type=Path, default=WORKSPACE_ROOT)
+    args = parser.parse_args()
+
+    workspace_root = args.workspace_root.resolve()
+    knowledge_fs_root = workspace_root / KNOWLEDGE_FS_DIRECTORY
+    lock_path = workspace_root / LOCK_RELATIVE_PATH
+    capability_v2_auth_manifest_path = knowledge_fs_root / CAPABILITY_V2_AUTH_MANIFEST_RELATIVE_PATH
+    capability_v2_auth_test_vector_path = knowledge_fs_root / CAPABILITY_V2_AUTH_TEST_VECTOR_RELATIVE_PATH
+    product_operations_path = workspace_root / PRODUCT_OPERATIONS_RELATIVE_PATH
+    product_operation_gaps_path = workspace_root / PRODUCT_OPERATION_GAPS_RELATIVE_PATH
+    upstream_provenance_path = knowledge_fs_root / UPSTREAM_PROVENANCE_RELATIVE_PATH
+    ensure_clean_knowledge_fs_worktree(workspace_root)
+    ensure_contract_inputs_exist(
+        knowledge_fs_root=knowledge_fs_root,
+        capability_v2_auth_manifest_path=capability_v2_auth_manifest_path,
+        capability_v2_auth_test_vector_path=capability_v2_auth_test_vector_path,
+        product_operations_path=product_operations_path,
+        product_operation_gaps_path=product_operation_gaps_path,
+        upstream_provenance_path=upstream_provenance_path,
+    )
+
+    subtree_tree = staged_subtree_tree(workspace_root)
+    capability_v2_auth_manifest_content = capability_v2_auth_manifest_path.read_bytes()
+    capability_v2_auth_test_vector_content = capability_v2_auth_test_vector_path.read_bytes()
+    product_operation_manifest_content = product_operations_path.read_bytes()
+    product_operation_gap_manifest_content = product_operation_gaps_path.read_bytes()
+    capability_v2_auth_manifest = load_json_object(capability_v2_auth_manifest_path)
+    validate_capability_v2_auth_manifest(capability_v2_auth_manifest)
+    validate_capability_v2_auth_test_vector(
+        load_json_object(capability_v2_auth_test_vector_path),
+        capability_v2_auth_manifest,
+    )
+    validate_upstream_provenance(load_json_object(upstream_provenance_path))
+    product_manifest = parse_product_operation_manifest(load_json_object(product_operations_path))
+    product_gap_manifest = parse_product_operation_gap_manifest(load_json_object(product_operation_gaps_path))
+    product_runtime_operations = product_operation_runtime_contracts()
+    capability_runtime_operations = capability_operation_runtime_contracts()
+    declarations = console_contract_declarations()
+
+    with tempfile.TemporaryDirectory(prefix="dify-knowledge-fs-contract-") as directory:
+        openapi_path = Path(directory) / "knowledge-fs.openapi.json"
+        capability_policy_path = Path(directory) / "dify-capability-v2-operations.json"
+        subprocess.run(
+            ["pnpm", "openapi:export", "--", "--output", str(openapi_path)],
+            cwd=knowledge_fs_root,
+            check=True,
+        )
+        subprocess.run(
+            ["pnpm", "capability:export", "--", "--output", str(capability_policy_path)],
+            cwd=knowledge_fs_root,
+            check=True,
+        )
+        openapi_content = openapi_path.read_bytes()
+        capability_policy = parse_capability_operation_policy(load_json_object(capability_policy_path))
+
+    document: dict[str, Any] = json.loads(openapi_content)
+    validate_product_operation_contracts(
+        capability_operations=capability_runtime_operations,
+        capability_policy=capability_policy,
+        document=document,
+        gap_manifest=product_gap_manifest,
+        manifest=product_manifest,
+        product_operations=product_runtime_operations,
+    )
+    validate_declarations(document, declarations)
+
+    expected_lock: ContractLock = {
+        "schemaVersion": LOCK_SCHEMA_VERSION,
+        "subtreeTree": subtree_tree,
+        "openapiSha256": sha256(openapi_content),
+        "capabilityV2AuthManifestSha256": sha256(capability_v2_auth_manifest_content),
+        "capabilityV2AuthTestVectorSha256": sha256(capability_v2_auth_test_vector_content),
+        "productOperationManifestSha256": sha256(product_operation_manifest_content),
+        "productOperationGapManifestSha256": sha256(product_operation_gap_manifest_content),
+    }
+
+    if args.update_lock:
+        lock_path.write_text(json.dumps(expected_lock, indent=2) + "\n")
+        return
+
+    received_lock = parse_contract_lock(load_json_object(lock_path))
+    lock_fields = (
+        (
+            "capabilityV2AuthManifestSha256",
+            received_lock["capabilityV2AuthManifestSha256"],
+            expected_lock["capabilityV2AuthManifestSha256"],
+        ),
+        (
+            "capabilityV2AuthTestVectorSha256",
+            received_lock["capabilityV2AuthTestVectorSha256"],
+            expected_lock["capabilityV2AuthTestVectorSha256"],
+        ),
+        (
+            "productOperationManifestSha256",
+            received_lock["productOperationManifestSha256"],
+            expected_lock["productOperationManifestSha256"],
+        ),
+        (
+            "productOperationGapManifestSha256",
+            received_lock["productOperationGapManifestSha256"],
+            expected_lock["productOperationGapManifestSha256"],
+        ),
+        ("schemaVersion", received_lock["schemaVersion"], expected_lock["schemaVersion"]),
+        ("subtreeTree", received_lock["subtreeTree"], expected_lock["subtreeTree"]),
+        ("openapiSha256", received_lock["openapiSha256"], expected_lock["openapiSha256"]),
+    )
+    for field, received_value, expected_value in lock_fields:
+        if received_value != expected_value:
+            raise RuntimeError(
+                f"KnowledgeFS contract lock field {field} drifted: "
+                f"expected {expected_value!r}, received {received_value!r}. "
+                "Run --update-lock intentionally after reviewing the staged subtree and contract changes."
+            )
+
+
+def ensure_contract_inputs_exist(
+    *,
+    knowledge_fs_root: Path,
+    capability_v2_auth_manifest_path: Path,
+    capability_v2_auth_test_vector_path: Path,
+    product_operations_path: Path,
+    product_operation_gaps_path: Path,
+    upstream_provenance_path: Path,
+) -> None:
+    """Fail with a stable error before invoking package tooling when a contract input is absent."""
+    required_paths = (
+        knowledge_fs_root / "package.json",
+        capability_v2_auth_manifest_path,
+        capability_v2_auth_test_vector_path,
+        product_operations_path,
+        product_operation_gaps_path,
+        upstream_provenance_path,
+    )
+    missing_paths = [path for path in required_paths if not path.is_file()]
+    if missing_paths:
+        missing = ", ".join(str(path) for path in missing_paths)
+        raise RuntimeError(f"KnowledgeFS contract input is missing: {missing}")
+
+
+def ensure_clean_knowledge_fs_worktree(workspace_root: Path) -> None:
+    """Require exported KnowledgeFS files to exactly match the staged index tree.
+
+    Staged changes are expected during intentional lock updates. Unstaged tracked changes and untracked files are
+    rejected because the export process reads the working tree while the tree ID is calculated from the index.
+    """
+    subtree_path = f"{KNOWLEDGE_FS_DIRECTORY}/"
+    unstaged = subprocess.run(
+        ["git", "diff", "--quiet", "--", subtree_path],
+        cwd=workspace_root,
+        check=False,
+    )
+    if unstaged.returncode > 1:
+        raise RuntimeError("git diff failed while validating the staged KnowledgeFS subtree")
+    untracked = run(
+        "git",
+        "ls-files",
+        "--others",
+        "--exclude-standard",
+        "--",
+        subtree_path,
+        cwd=workspace_root,
+    ).strip()
+    if unstaged.returncode != 0 or untracked:
+        raise RuntimeError(
+            "knowledge-fs/ contains unstaged or untracked changes; stage or remove them before contract export"
+        )
+
+
+def staged_subtree_tree(workspace_root: Path) -> str:
+    """Return the Git tree object for the staged ``knowledge-fs/`` subtree."""
+    return run("git", "write-tree", f"--prefix={KNOWLEDGE_FS_DIRECTORY}/", cwd=workspace_root).strip()
+
+
+def load_json_object(path: Path) -> dict[str, Any]:
+    """Load a JSON object and reject arrays/scalars at contract boundaries."""
+    value = json.loads(path.read_text())
+    if not isinstance(value, dict):
+        raise ValueError(f"KnowledgeFS contract file must contain a JSON object: {path}")
+    return cast(dict[str, Any], value)
+
+
+def parse_contract_lock(value: dict[str, Any]) -> ContractLock:
+    """Validate the compact, non-self-referential contract lock schema."""
+    expected_fields = {
+        "capabilityV2AuthManifestSha256",
+        "capabilityV2AuthTestVectorSha256",
+        "openapiSha256",
+        "productOperationGapManifestSha256",
+        "productOperationManifestSha256",
+        "schemaVersion",
+        "subtreeTree",
+    }
+    if set(value) != expected_fields:
+        raise ValueError(f"KnowledgeFS contract lock fields must be exactly {sorted(expected_fields)}")
+    if value.get("schemaVersion") != LOCK_SCHEMA_VERSION:
+        raise ValueError(f"KnowledgeFS contract lock schemaVersion must be {LOCK_SCHEMA_VERSION}")
+    for field in (
+        "capabilityV2AuthManifestSha256",
+        "capabilityV2AuthTestVectorSha256",
+        "openapiSha256",
+        "productOperationGapManifestSha256",
+        "productOperationManifestSha256",
+        "subtreeTree",
+    ):
+        field_value = value.get(field)
+        expected_length = 40 if field == "subtreeTree" else 64
+        if (
+            not isinstance(field_value, str)
+            or len(field_value) != expected_length
+            or any(character not in "0123456789abcdef" for character in field_value)
+        ):
+            raise ValueError(f"KnowledgeFS contract lock field {field} has an invalid digest")
+    return cast(ContractLock, value)
+
+
+def validate_required_product_operations(document: dict[str, Any], required_operation_ids: list[str]) -> None:
+    """Fail when the pinned KFS OpenAPI omits an operation required by the Dify product."""
+    available_operation_ids = [
+        operation_id
+        for path_item in document.get("paths", {}).values()
+        for method in OPENAPI_METHODS
+        if isinstance(path_item, dict)
+        for operation in (path_item.get(method),)
+        if isinstance(operation, dict)
+        for operation_id in (operation.get("operationId"),)
+        if isinstance(operation_id, str) and operation_id
+    ]
+    for operation_id in required_operation_ids:
+        count = available_operation_ids.count(operation_id)
+        if count != 1:
+            raise ValueError(
+                f"KnowledgeFS OpenAPI required product operation {operation_id} must occur exactly once; found {count}"
+            )
+
+
+def validate_capability_v2_auth_manifest(value: dict[str, Any]) -> None:
+    """Validate the active production RS256 profile consumed by both Dify and KnowledgeFS."""
+    expected_fields = {
+        "active",
+        "audience",
+        "callerProfiles",
+        "claimBindings",
+        "issuer",
+        "lifecycle",
+        "maxTtlSeconds",
+        "productionReady",
+        "profileId",
+        "protectedHeader",
+        "requiredClaims",
+        "resourceContract",
+        "runtimeAssembly",
+        "schemaVersion",
+        "signatureAlgorithms",
+        "tokenKind",
+    }
+    if set(value) != expected_fields:
+        raise ValueError(f"KnowledgeFS Capability v2 auth manifest fields must be exactly {sorted(expected_fields)}")
+    fixed_values = {
+        "active": True,
+        "audience": "knowledge-fs",
+        "issuer": "dify-control-plane",
+        "lifecycle": "active",
+        "maxTtlSeconds": 60,
+        "productionReady": True,
+        "profileId": "dify-capability-v2",
+        "schemaVersion": 3,
+        "signatureAlgorithms": ["RS256"],
+        "tokenKind": "jwt",
+    }
+    for field, expected in fixed_values.items():
+        if value.get(field) != expected:
+            raise ValueError(f"KnowledgeFS Capability v2 auth manifest field {field} must be {expected!r}")
+    if value.get("protectedHeader") != {
+        "algorithm": "RS256",
+        "keyIdClaim": "kid",
+        "keyIdRequired": True,
+        "type": "JWT",
+    }:
+        raise ValueError("KnowledgeFS Capability v2 protected header contract is invalid")
+    required_claims = [
+        "action",
+        "actor",
+        "aud",
+        "authz_revision",
+        "azp",
+        "caller_kind",
+        "cap_ver",
+        "content_policy_revision",
+        "content_scope_ids",
+        "control_space_id",
+        "exp",
+        "grant_id",
+        "iat",
+        "iss",
+        "jti",
+        "namespace_id",
+        "nbf",
+        "resource",
+        "sub",
+        "trace_id",
+    ]
+    if value.get("requiredClaims") != required_claims:
+        raise ValueError("KnowledgeFS Capability v2 required claims are invalid")
+    if value.get("claimBindings") != {
+        "action": "action",
+        "callerKind": "caller_kind",
+        "controlSpace": "control_space_id",
+        "namespace": "namespace_id",
+        "resource": "resource",
+        "resourceParent": "resource.parent_id",
+        "subject": "sub",
+    }:
+        raise ValueError("KnowledgeFS Capability v2 claim bindings are invalid")
+    if value.get("resourceContract") != {
+        "fields": ["id", "parent_id", "type"],
+        "parentForbiddenFor": ["namespace", "knowledge_space"],
+        "parentRequiredFor": ["document", "job", "query", "research_task", "source", "upload_session"],
+    }:
+        raise ValueError("KnowledgeFS Capability v2 resource contract is invalid")
+    if value.get("callerProfiles") != {
+        "agent": {"authorizedParty": "dify-agent", "subjectPrefix": "dify-app:"},
+        "interactive": {"authorizedParty": "dify-console", "subjectPrefix": "dify-account:"},
+        "internal_worker": {"authorizedParty": "dify-worker", "subjectPrefix": "dify-worker:"},
+        "mcp": {"authorizedParty": "dify-mcp", "subjectPrefix": "dify-mcp-session:"},
+        "service": {"authorizedParty": "dify-service-api", "subjectPrefix": "dify-kfs-credential:"},
+        "workflow": {"authorizedParty": "dify-workflow", "subjectPrefix": "dify-app:"},
+    }:
+        raise ValueError("KnowledgeFS Capability v2 caller profiles are invalid")
+    if value.get("runtimeAssembly") != {
+        "failClosed": True,
+        "keySelection": "kid",
+        "maximumPublishedKeys": 3,
+        "verificationKeySource": "jwks",
+    }:
+        raise ValueError("KnowledgeFS Capability v2 runtime assembly is invalid")
+
+
+def validate_capability_v2_auth_test_vector(
+    value: dict[str, Any],
+    manifest: dict[str, Any],
+) -> None:
+    """Verify the deterministic public-key vector and every security-sensitive binding."""
+    expected_fields = {
+        "algorithm",
+        "audience",
+        "expectedClaims",
+        "expectedPrincipal",
+        "issuer",
+        "operation",
+        "profileId",
+        "protectedHeader",
+        "publicJwk",
+        "schemaVersion",
+        "testOnly",
+        "token",
+        "ttlSeconds",
+    }
+    if set(value) != expected_fields:
+        raise ValueError(f"KnowledgeFS Capability v2 test vector fields must be exactly {sorted(expected_fields)}")
+    if (
+        value.get("schemaVersion") != 2
+        or value.get("profileId") != manifest.get("profileId")
+        or value.get("testOnly") is not True
+        or value.get("algorithm") != "RS256"
+        or value.get("issuer") != manifest.get("issuer")
+        or value.get("audience") != manifest.get("audience")
+        or value.get("ttlSeconds") != manifest.get("maxTtlSeconds")
+    ):
+        raise ValueError("KnowledgeFS Capability v2 test vector does not match the active profile")
+    protected_header = value.get("protectedHeader")
+    if not isinstance(protected_header, dict) or set(protected_header) != {"alg", "kid", "typ"}:
+        raise ValueError("KnowledgeFS Capability v2 test vector protected header is invalid")
+    kid = protected_header.get("kid")
+    if protected_header.get("alg") != "RS256" or protected_header.get("typ") != "JWT" or not _is_non_blank(kid):
+        raise ValueError("KnowledgeFS Capability v2 test vector protected header is invalid")
+    public_jwk = value.get("publicJwk")
+    if not isinstance(public_jwk, dict) or set(public_jwk) != {"alg", "e", "kid", "kty", "n", "use"}:
+        raise ValueError("KnowledgeFS Capability v2 test vector public JWK is invalid")
+    if (
+        public_jwk.get("alg") != "RS256"
+        or public_jwk.get("kid") != kid
+        or public_jwk.get("kty") != "RSA"
+        or public_jwk.get("use") != "sig"
+        or not _is_non_blank(public_jwk.get("e"))
+        or not _is_non_blank(public_jwk.get("n"))
+    ):
+        raise ValueError("KnowledgeFS Capability v2 test vector public JWK is invalid")
+
+    claims = value.get("expectedClaims")
+    required_claims = manifest.get("requiredClaims")
+    if not isinstance(claims, dict) or not isinstance(required_claims, list) or set(claims) != set(required_claims):
+        raise ValueError("KnowledgeFS Capability v2 test vector claims do not match the active profile")
+    operation = value.get("operation")
+    if not isinstance(operation, dict) or set(operation) != {"action", "method", "operationId", "requestPath"}:
+        raise ValueError("KnowledgeFS Capability v2 test vector operation is invalid")
+    resource = claims.get("resource")
+    if not isinstance(resource, dict) or set(resource) != {"id", "parent_id", "type"}:
+        raise ValueError("KnowledgeFS Capability v2 test vector resource is invalid")
+    expected_operation = {
+        "action": "documents.read",
+        "method": "GET",
+        "operationId": "getDocument",
+        "requestPath": "/knowledge-spaces/space-contract-vector/documents/document-contract-vector",
+    }
+    if operation != expected_operation:
+        raise ValueError("KnowledgeFS Capability v2 test vector operation binding is invalid")
+    exact_claims = {
+        "action": operation["action"],
+        "aud": value["audience"],
+        "caller_kind": "interactive",
+        "cap_ver": 2,
+        "control_space_id": "control-space-contract-vector",
+        "iss": value["issuer"],
+        "namespace_id": "workspace-contract-vector",
+        "resource": {
+            "id": "document-contract-vector",
+            "parent_id": "space-contract-vector",
+            "type": "document",
+        },
+        "sub": "dify-account:account-contract-vector",
+    }
+    for field, expected in exact_claims.items():
+        if claims.get(field) != expected:
+            raise ValueError(f"KnowledgeFS Capability v2 test vector claim {field} is invalid")
+    if claims.get("actor") != claims["sub"] or claims.get("azp") != "dify-console":
+        raise ValueError("KnowledgeFS Capability v2 test vector caller binding is invalid")
+    issued_at = claims.get("iat")
+    not_before = claims.get("nbf")
+    expires_at = claims.get("exp")
+    if (
+        not isinstance(issued_at, int)
+        or isinstance(issued_at, bool)
+        or not_before != issued_at
+        or not isinstance(expires_at, int)
+        or isinstance(expires_at, bool)
+        or expires_at - issued_at != value["ttlSeconds"]
+    ):
+        raise ValueError("KnowledgeFS Capability v2 test vector TTL is invalid")
+    expected_principal = {
+        "callerKind": claims["caller_kind"],
+        "subject": {
+            "scopes": ["knowledge-spaces:read"],
+            "subjectId": claims["sub"],
+            "tenantId": claims["namespace_id"],
+        },
+    }
+    if value.get("expectedPrincipal") != expected_principal:
+        raise ValueError("KnowledgeFS Capability v2 test vector principal is invalid")
+
+    token = value.get("token")
+    if not isinstance(token, str) or not _is_non_blank(token):
+        raise ValueError("KnowledgeFS Capability v2 test vector token is invalid")
+    try:
+        verification_key = RSAAlgorithm.from_jwk(public_jwk)
+        if not isinstance(verification_key, RSAPublicKey):
+            raise ValueError("Capability vector verification key is not RSA public material")
+        header = jwt.get_unverified_header(token)
+        decoded_claims = jwt.decode(
+            token,
+            verification_key,
+            algorithms=["RS256"],
+            audience=cast(str, value["audience"]),
+            issuer=cast(str, value["issuer"]),
+            options={"verify_exp": False, "verify_iat": False, "verify_nbf": False},
+        )
+    except (jwt.PyJWTError, TypeError, ValueError) as exc:
+        raise ValueError("KnowledgeFS Capability v2 test vector signature is invalid") from exc
+    if header != protected_header or decoded_claims != claims:
+        raise ValueError("KnowledgeFS Capability v2 test vector token content drifted")
+
+
+def _is_non_blank(value: object) -> bool:
+    return isinstance(value, str) and bool(value.strip()) and value == value.strip()
+
+
+def validate_upstream_provenance(value: dict[str, Any]) -> None:
+    """Validate the imported-source provenance that is itself covered by the subtree tree ID."""
+    expected_fields = {"commit", "release", "repository", "schemaVersion"}
+    if set(value) != expected_fields:
+        raise ValueError(f"KnowledgeFS upstream provenance fields must be exactly {sorted(expected_fields)}")
+    if value.get("schemaVersion") != 1:
+        raise ValueError("KnowledgeFS upstream provenance must use schemaVersion 1")
+    repository = value.get("repository")
+    commit = value.get("commit")
+    if not isinstance(repository, str) or not repository.startswith("https://"):
+        raise ValueError("KnowledgeFS upstream provenance repository must be an HTTPS URL")
+    if (
+        not isinstance(commit, str)
+        or len(commit) != 40
+        or any(character not in "0123456789abcdef" for character in commit)
+    ):
+        raise ValueError("KnowledgeFS upstream provenance commit must be a lowercase full Git SHA")
+    if value.get("release") is not None and not isinstance(value["release"], str):
+        raise ValueError("KnowledgeFS upstream provenance release must be null or a string")
+
+
+def validate_declarations(document: dict[str, Any], declarations: tuple[ContractDeclaration, ...]) -> None:
+    """Validate Dify Console declarations against matching pinned OpenAPI operations."""
+    operations_by_id: dict[str, list[tuple[str, str, dict[str, Any], dict[str, Any]]]] = {}
+    for path, path_item in document.get("paths", {}).items():
+        for method in OPENAPI_METHODS:
+            operation = path_item.get(method)
+            if operation is None:
+                continue
+            operation_id = operation.get("operationId")
+            if isinstance(operation_id, str) and operation_id:
+                operations_by_id.setdefault(operation_id, []).append((method, path, path_item, operation))
+
+    declared_ids: set[str] = set()
+    for declaration in declarations:
+        operation_id = declaration["operation_id"]
+        if operation_id in declared_ids:
+            raise ValueError(f"Dify Console registry has duplicate operationId: {operation_id}")
+        declared_ids.add(operation_id)
+
+        matches = operations_by_id.get(operation_id, [])
+        if not matches:
+            raise ValueError(f"KnowledgeFS OpenAPI has no operationId: {operation_id}")
+        if len(matches) > 1:
+            raise ValueError(f"KnowledgeFS OpenAPI has duplicate operationId: {operation_id}")
+
+        method, path, path_item, operation = matches[0]
+        if not path.startswith("/"):
+            raise ValueError(f"KnowledgeFS OpenAPI path must be absolute: {path}")
+        if method not in PROXY_METHODS:
+            raise ValueError(f"KnowledgeFS proxy does not support {method.upper()} {path}")
+        expected: ContractDeclaration = {
+            "operation_id": operation_id,
+            "method": method.upper(),
+            "path": path[1:],
+            "required_scope": required_scope(document, operation),
+            "response_kind": response_kind(operation),
+            "max_response_bytes": required_max_response_bytes(operation),
+            "request_headers": request_header_names(path_item, operation),
+            "response_headers": response_header_names(operation),
+            "response_media_types": response_media_types(operation),
+        }
+        for field in DECLARATION_FIELDS:
+            expected_value = expected[field]
+            received_value = declaration[field]
+            if received_value != expected_value:
+                raise ValueError(
+                    f"KnowledgeFS operation {operation_id} field {field} drifted: "
+                    f"expected {expected_value!r}, received {received_value!r}"
+                )
+
+
+def console_contract_declarations() -> tuple[ContractDeclaration, ...]:
+    """The P9 backend exposes only typed product controllers; the raw Console proxy is removed."""
+
+    return ()
+
+
+def response_kind(operation: dict[str, Any]) -> str:
+    media_types = response_media_types(operation)
+    if "text/event-stream" in media_types:
+        return "stream"
+    if "application/octet-stream" in media_types:
+        return "binary"
+    return "buffered"
+
+
+def response_media_types(operation: dict[str, Any]) -> tuple[str, ...]:
+    media_types: set[str] = set()
+    for status, response in operation.get("responses", {}).items():
+        if status == "2XX" or (len(status) == 3 and status.startswith("2") and status.isdigit()):
+            media_types.update(response.get("content", {}))
+    return tuple(sorted(media_types))
+
+
+def required_scope(document: dict[str, Any], operation: dict[str, Any]) -> str | None:
+    scope = operation.get("x-knowledge-fs-required-scope")
+    security = operation["security"] if "security" in operation else document.get("security")
+    if security == []:
+        if scope is not None:
+            raise ValueError(f"KnowledgeFS public operation must not declare a required scope: {scope}")
+        return None
+    if security != [{"bearerAuth": []}]:
+        raise ValueError(f"KnowledgeFS operation effective security must be exactly bearerAuth: {security}")
+    if scope in ("knowledge-spaces:read", "knowledge-spaces:write"):
+        return scope
+    raise ValueError(f"KnowledgeFS operation has no supported required scope: {scope}")
+
+
+def required_max_response_bytes(operation: dict[str, Any]) -> int:
+    value = operation.get("x-knowledge-fs-max-response-bytes")
+    if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+        raise ValueError(f"KnowledgeFS operation has no valid response byte limit: {value}")
+    return value
+
+
+def request_header_names(path_item: dict[str, Any], operation: dict[str, Any]) -> tuple[str, ...]:
+    names: set[str] = set()
+    for parameter in [*path_item.get("parameters", []), *operation.get("parameters", [])]:
+        if "$ref" in parameter:
+            raise ValueError(f"KnowledgeFS request header references are not supported: {parameter['$ref']}")
+        if parameter.get("in") == "header":
+            names.add(parameter["name"].lower())
+    return tuple(sorted(names))
+
+
+def response_header_names(operation: dict[str, Any]) -> tuple[str, ...]:
+    return tuple(
+        sorted(
+            {
+                name.lower()
+                for response in operation.get("responses", {}).values()
+                for name in response.get("headers", {})
+            }
+        )
+    )
+
+
+def sha256(content: bytes) -> str:
+    return hashlib.sha256(content).hexdigest()
+
+
+def run(*command: str, cwd: Path) -> str:
+    return subprocess.run(command, cwd=cwd, check=True, capture_output=True, text=True).stdout
+
+
+if __name__ == "__main__":
+    main()

api/dev/knowledge_fs_product_contract.py

@@ -0,0 +1,494 @@
+"""Cross-service KnowledgeFS product-operation contract validation.
+
+The checked product manifest is the reviewable boundary, while the Dify product registry, Dify
+Capability issuer registry, exported KnowledgeFS OpenAPI, and exported TypeScript request-guard
+policy remain executable sources of truth. A product operation must appear exactly once as ready
+or as an explicit gap; internal KFS-only operations require a named exclusion.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any, Literal, NamedTuple, TypedDict, cast
+
+
+class ProductOperationLimits(TypedDict):
+    kfsMaxResponseBytes: int
+    productMaxRequestBytes: int
+    productMaxResponseBytes: int
+
+
+class ProductOperationStream(TypedDict):
+    kfsResponseKind: str
+    productKind: str
+
+
+class ProductOperationManifestEntry(TypedDict):
+    action: str
+    kfsOperationId: str
+    limits: ProductOperationLimits
+    method: str
+    path: str
+    productOperationId: str
+    resource: str
+    stream: ProductOperationStream
+    transport: str
+
+
+type ProductOperationManifestField = Literal[
+    "action",
+    "kfsOperationId",
+    "limits",
+    "method",
+    "path",
+    "productOperationId",
+    "resource",
+    "stream",
+    "transport",
+]
+
+PRODUCT_OPERATION_MANIFEST_FIELDS: tuple[ProductOperationManifestField, ...] = (
+    "action",
+    "kfsOperationId",
+    "limits",
+    "method",
+    "path",
+    "productOperationId",
+    "resource",
+    "stream",
+    "transport",
+)
+
+
+class ProductOperationManifest(TypedDict):
+    operations: list[ProductOperationManifestEntry]
+    schemaVersion: int
+
+
+class ProductOperationGapEntry(ProductOperationManifestEntry):
+    reason: str
+    reasonCode: str
+    replacementProductOperationIds: list[str]
+
+
+class InternalKfsOperationExclusion(TypedDict):
+    kfsOperationId: str
+    reason: str
+    reasonCode: str
+
+
+class ProductOperationGapManifest(TypedDict):
+    gaps: list[ProductOperationGapEntry]
+    internalKfsOperationExclusions: list[InternalKfsOperationExclusion]
+    schemaVersion: int
+
+
+class ProductOperationRuntimeContract(NamedTuple):
+    action: str
+    kfs_operation_id: str
+    max_request_bytes: int
+    max_response_bytes: int
+    method: str
+    path: str
+    product_operation_id: str
+    ready: bool
+    resource: str
+    stream_kind: str
+    transport: str
+
+
+class CapabilityOperationRuntimeContract(NamedTuple):
+    action: str
+    allowed_caller_kinds: tuple[str, ...]
+    method: str
+    operation_id: str
+    path: str
+    resource: str
+
+
+class CapabilityOperationPolicy(NamedTuple):
+    action: str
+    allowed_caller_kinds: tuple[str, ...]
+    method: str
+    operation_id: str
+    parent_resource_binding: dict[str, object] | None
+    path: str
+    resource: str
+    resource_binding: dict[str, object]
+
+
+def product_operation_runtime_contracts() -> tuple[ProductOperationRuntimeContract, ...]:
+    """Read the complete typed Dify product registry without normalizing away gaps."""
+    from services.knowledge_fs.product_operations import (
+        KNOWLEDGE_FS_PRODUCT_OPERATIONS,
+        is_product_operation_ready,
+    )
+
+    contracts: list[ProductOperationRuntimeContract] = []
+    for product_operation_id, operation in KNOWLEDGE_FS_PRODUCT_OPERATIONS.items():
+        if operation.capability_operation_id is None or operation.kfs_path is None or operation.action is None:
+            raise ValueError(f"Dify product operation {product_operation_id} has no Capability contract")
+        contracts.append(
+            ProductOperationRuntimeContract(
+                action=operation.action,
+                kfs_operation_id=operation.capability_operation_id,
+                max_request_bytes=operation.max_request_bytes,
+                max_response_bytes=operation.max_response_bytes,
+                method=operation.method,
+                path=operation.kfs_path,
+                product_operation_id=product_operation_id,
+                ready=is_product_operation_ready(product_operation_id),
+                resource=operation.resource_resolver,
+                stream_kind=operation.stream_kind,
+                transport=operation.transport,
+            )
+        )
+    return tuple(contracts)
+
+
+def capability_operation_runtime_contracts() -> tuple[CapabilityOperationRuntimeContract, ...]:
+    """Read the Python issuer policy used to mint each operation Capability."""
+    from services.knowledge_fs_capability import KNOWLEDGE_FS_CAPABILITY_OPERATIONS
+
+    return tuple(
+        CapabilityOperationRuntimeContract(
+            action=operation.action,
+            allowed_caller_kinds=operation.allowed_caller_kinds,
+            method=operation.method,
+            operation_id=operation_id,
+            path=operation.path,
+            resource=operation.resource_type,
+        )
+        for operation_id, operation in KNOWLEDGE_FS_CAPABILITY_OPERATIONS.items()
+    )
+
+
+def parse_product_operation_manifest(value: dict[str, Any]) -> ProductOperationManifest:
+    """Parse the ready product-operation inventory with a closed schema."""
+    if set(value) != {"operations", "schemaVersion"} or value.get("schemaVersion") != 2:
+        raise ValueError("KnowledgeFS product operation manifest must use schemaVersion 2")
+    operations = value.get("operations")
+    if not isinstance(operations, list) or not operations:
+        raise ValueError("KnowledgeFS product operation manifest operations must be a non-empty list")
+    return {
+        "operations": [_parse_product_entry(entry, gap=False) for entry in operations],
+        "schemaVersion": 2,
+    }
+
+
+def parse_product_operation_gap_manifest(value: dict[str, Any]) -> ProductOperationGapManifest:
+    """Parse explicit product gaps and KFS-only operation exclusions with a closed schema."""
+    expected_fields = {"gaps", "internalKfsOperationExclusions", "schemaVersion"}
+    if set(value) != expected_fields or value.get("schemaVersion") != 2:
+        raise ValueError("KnowledgeFS product operation gap manifest must use schemaVersion 2")
+    gaps = value.get("gaps")
+    exclusions = value.get("internalKfsOperationExclusions")
+    if not isinstance(gaps, list) or not gaps or not isinstance(exclusions, list):
+        raise ValueError("KnowledgeFS product operation gap manifest lists are invalid")
+    parsed_exclusions: list[InternalKfsOperationExclusion] = []
+    for raw in exclusions:
+        if not isinstance(raw, dict) or set(raw) != {"kfsOperationId", "reason", "reasonCode"}:
+            raise ValueError("KnowledgeFS internal KFS operation exclusion fields are invalid")
+        for field in ("kfsOperationId", "reason", "reasonCode"):
+            _required_string(raw.get(field), f"internal exclusion {field}")
+        parsed_exclusions.append(cast(InternalKfsOperationExclusion, raw))
+    return {
+        "gaps": [cast(ProductOperationGapEntry, _parse_product_entry(entry, gap=True)) for entry in gaps],
+        "internalKfsOperationExclusions": parsed_exclusions,
+        "schemaVersion": 2,
+    }
+
+
+def parse_capability_operation_policy(value: dict[str, Any]) -> tuple[CapabilityOperationPolicy, ...]:
+    """Parse the runtime-exported TypeScript request-guard registry."""
+    if set(value) != {"operations", "schemaVersion"} or value.get("schemaVersion") != 1:
+        raise ValueError("KnowledgeFS Capability operation policy must use schemaVersion 1")
+    operations = value.get("operations")
+    if not isinstance(operations, list) or not operations:
+        raise ValueError("KnowledgeFS Capability operation policy must contain operations")
+    parsed: list[CapabilityOperationPolicy] = []
+    for raw in operations:
+        expected_fields = {
+            "action",
+            "allowedCallerKinds",
+            "method",
+            "operationId",
+            "parentResourceBinding",
+            "path",
+            "resourceBinding",
+            "resourceType",
+        }
+        if not isinstance(raw, dict) or set(raw) != expected_fields:
+            raise ValueError("KnowledgeFS Capability operation policy fields are invalid")
+        callers = raw.get("allowedCallerKinds")
+        resource_binding = raw.get("resourceBinding")
+        parent_binding = raw.get("parentResourceBinding")
+        if (
+            not isinstance(callers, list)
+            or not callers
+            or not all(isinstance(caller, str) and caller for caller in callers)
+            or not isinstance(resource_binding, dict)
+            or not resource_binding
+            or (parent_binding is not None and not isinstance(parent_binding, dict))
+        ):
+            raise ValueError("KnowledgeFS Capability operation request binding is invalid")
+        for field in ("action", "method", "operationId", "path", "resourceType"):
+            _required_string(raw.get(field), f"Capability operation {field}")
+        parsed.append(
+            CapabilityOperationPolicy(
+                action=cast(str, raw["action"]),
+                allowed_caller_kinds=tuple(callers),
+                method=cast(str, raw["method"]),
+                operation_id=cast(str, raw["operationId"]),
+                parent_resource_binding=cast(dict[str, object] | None, parent_binding),
+                path=cast(str, raw["path"]),
+                resource=cast(str, raw["resourceType"]),
+                resource_binding=cast(dict[str, object], resource_binding),
+            )
+        )
+    _unique((operation.operation_id for operation in parsed), "Capability operation policy")
+    return tuple(parsed)
+
+
+def validate_product_operation_contracts(
+    *,
+    capability_operations: tuple[CapabilityOperationRuntimeContract, ...],
+    capability_policy: tuple[CapabilityOperationPolicy, ...],
+    document: dict[str, Any],
+    gap_manifest: ProductOperationGapManifest,
+    manifest: ProductOperationManifest,
+    product_operations: tuple[ProductOperationRuntimeContract, ...],
+) -> None:
+    """Require exact agreement across manifests, Dify registries, KFS guard policy, and OpenAPI."""
+    ready_entries = {entry["productOperationId"]: entry for entry in manifest["operations"]}
+    gap_entries = {entry["productOperationId"]: entry for entry in gap_manifest["gaps"]}
+    if len(ready_entries) != len(manifest["operations"]):
+        raise ValueError("KnowledgeFS product operation manifest contains duplicate product ids")
+    if len(gap_entries) != len(gap_manifest["gaps"]):
+        raise ValueError("KnowledgeFS product operation gap manifest contains duplicate product ids")
+    if set(ready_entries) & set(gap_entries):
+        raise ValueError("KnowledgeFS product operation cannot be both ready and a gap")
+    runtime_by_product = {operation.product_operation_id: operation for operation in product_operations}
+    if set(ready_entries) | set(gap_entries) != set(runtime_by_product):
+        missing = sorted(set(runtime_by_product) - set(ready_entries) - set(gap_entries))
+        extra = sorted((set(ready_entries) | set(gap_entries)) - set(runtime_by_product))
+        raise ValueError(f"KnowledgeFS product operation completeness drifted: missing={missing}, extra={extra}")
+
+    python_capabilities = {operation.operation_id: operation for operation in capability_operations}
+    guard_capabilities = {operation.operation_id: operation for operation in capability_policy}
+    openapi_operations = _openapi_operations(document)
+    for product_operation_id, runtime in runtime_by_product.items():
+        entry = ready_entries.get(product_operation_id) or gap_entries[product_operation_id]
+        if runtime.ready != (product_operation_id in ready_entries):
+            state = "ready" if runtime.ready else "gap"
+            raise ValueError(f"Dify product operation {product_operation_id} must be declared as {state}")
+        _validate_product_entry(entry, runtime, openapi_operations, python_capabilities, guard_capabilities)
+        if product_operation_id in gap_entries:
+            _required_string(gap_entries[product_operation_id]["reason"], "product gap reason")
+            _required_string(gap_entries[product_operation_id]["reasonCode"], "product gap reasonCode")
+            replacements = gap_entries[product_operation_id]["replacementProductOperationIds"]
+            if not replacements or any(replacement not in ready_entries for replacement in replacements):
+                raise ValueError(f"KnowledgeFS product gap {product_operation_id} has invalid replacements")
+
+    exclusions = gap_manifest["internalKfsOperationExclusions"]
+    exclusion_by_id = {entry["kfsOperationId"]: entry for entry in exclusions}
+    if len(exclusion_by_id) != len(exclusions):
+        raise ValueError("KnowledgeFS internal KFS operation exclusions contain duplicate ids")
+    lifecycle_operation_ids = {
+        "activateDifyWorkspaceIntegration",
+        "freezeDifyWorkspaceIntegration",
+    }
+    if set(exclusion_by_id) != lifecycle_operation_ids:
+        raise ValueError("KnowledgeFS Dify integration lifecycle operations must be explicit internal exclusions")
+    product_capability_ids = {operation.kfs_operation_id for operation in product_operations}
+    for operation_id in exclusion_by_id:
+        if operation_id in product_capability_ids:
+            raise ValueError(f"Internal KFS operation {operation_id} cannot also be a product operation")
+        _validate_capability_alignment(
+            operation_id,
+            openapi_operations,
+            python_capabilities,
+            guard_capabilities,
+        )
+        python_operation = python_capabilities[operation_id]
+        if python_operation.allowed_caller_kinds != ("internal_worker",) or python_operation.resource != "namespace":
+            raise ValueError("Dify integration lifecycle operations must remain internal-worker namespace-only")
+
+
+def _parse_product_entry(raw: object, *, gap: bool) -> ProductOperationManifestEntry:
+    base_fields = {
+        "action",
+        "kfsOperationId",
+        "limits",
+        "method",
+        "path",
+        "productOperationId",
+        "resource",
+        "stream",
+        "transport",
+    }
+    expected_fields = base_fields | ({"reason", "reasonCode", "replacementProductOperationIds"} if gap else set())
+    if not isinstance(raw, dict) or set(raw) != expected_fields:
+        raise ValueError("KnowledgeFS product operation entry fields are invalid")
+    for field in ("action", "kfsOperationId", "method", "path", "productOperationId", "resource", "transport"):
+        _required_string(raw.get(field), f"product operation {field}")
+    limits = raw.get("limits")
+    stream = raw.get("stream")
+    if not isinstance(limits, dict) or set(limits) != {
+        "kfsMaxResponseBytes",
+        "productMaxRequestBytes",
+        "productMaxResponseBytes",
+    }:
+        raise ValueError("KnowledgeFS product operation limits are invalid")
+    if not all(isinstance(limit, int) and not isinstance(limit, bool) and limit >= 0 for limit in limits.values()):
+        raise ValueError("KnowledgeFS product operation limits must be nonnegative integers")
+    if not isinstance(stream, dict) or set(stream) != {"kfsResponseKind", "productKind"}:
+        raise ValueError("KnowledgeFS product operation stream contract is invalid")
+    _required_string(stream.get("kfsResponseKind"), "KFS response kind")
+    _required_string(stream.get("productKind"), "product stream kind")
+    if gap:
+        _required_string(raw.get("reason"), "product gap reason")
+        _required_string(raw.get("reasonCode"), "product gap reasonCode")
+        replacements = raw.get("replacementProductOperationIds")
+        if not isinstance(replacements, list) or not all(isinstance(item, str) and item for item in replacements):
+            raise ValueError("KnowledgeFS product operation gap replacements are invalid")
+    return cast(ProductOperationManifestEntry, raw)
+
+
+def _validate_product_entry(
+    entry: ProductOperationManifestEntry,
+    runtime: ProductOperationRuntimeContract,
+    openapi_operations: Mapping[str, tuple[str, str, dict[str, Any]]],
+    python_capabilities: Mapping[str, CapabilityOperationRuntimeContract],
+    guard_capabilities: Mapping[str, CapabilityOperationPolicy],
+) -> None:
+    _validate_capability_alignment(
+        runtime.kfs_operation_id,
+        openapi_operations,
+        python_capabilities,
+        guard_capabilities,
+    )
+    _, _, openapi_operation = openapi_operations[runtime.kfs_operation_id]
+    expected: ProductOperationManifestEntry = {
+        "action": runtime.action,
+        "kfsOperationId": runtime.kfs_operation_id,
+        "limits": {
+            "kfsMaxResponseBytes": _openapi_max_response_bytes(openapi_operation),
+            "productMaxRequestBytes": runtime.max_request_bytes,
+            "productMaxResponseBytes": runtime.max_response_bytes,
+        },
+        "method": runtime.method,
+        "path": runtime.path,
+        "productOperationId": runtime.product_operation_id,
+        "resource": runtime.resource,
+        "stream": {
+            "kfsResponseKind": _openapi_response_kind(openapi_operation),
+            "productKind": runtime.stream_kind,
+        },
+        "transport": runtime.transport,
+    }
+    for field in PRODUCT_OPERATION_MANIFEST_FIELDS:
+        expected_value = expected[field]
+        if entry[field] != expected_value:
+            raise ValueError(
+                f"KnowledgeFS product operation {runtime.product_operation_id} field {field} drifted: "
+                f"expected {expected_value!r}, received {entry[field]!r}"
+            )
+
+
+def _validate_capability_alignment(
+    operation_id: str,
+    openapi_operations: Mapping[str, tuple[str, str, dict[str, Any]]],
+    python_capabilities: Mapping[str, CapabilityOperationRuntimeContract],
+    guard_capabilities: Mapping[str, CapabilityOperationPolicy],
+) -> None:
+    python_operation = python_capabilities.get(operation_id)
+    guard_operation = guard_capabilities.get(operation_id)
+    openapi_operation = openapi_operations.get(operation_id)
+    if python_operation is None or guard_operation is None or openapi_operation is None:
+        raise ValueError(
+            f"KnowledgeFS operation {operation_id} must exist in Python issuer, TypeScript guard, and OpenAPI"
+        )
+    method, path, _ = openapi_operation
+    expected = (
+        python_operation.action,
+        python_operation.method,
+        python_operation.path,
+        python_operation.resource,
+    )
+    received_guard = (guard_operation.action, guard_operation.method, guard_operation.path, guard_operation.resource)
+    if received_guard != expected:
+        raise ValueError(f"KnowledgeFS operation {operation_id} TypeScript guard drifted")
+    if (method, path) != (python_operation.method, python_operation.path):
+        raise ValueError(f"KnowledgeFS operation {operation_id} OpenAPI method/path drifted")
+    if guard_operation.allowed_caller_kinds != python_operation.allowed_caller_kinds:
+        raise ValueError(f"KnowledgeFS operation {operation_id} caller policy drifted")
+
+
+def _openapi_operations(document: dict[str, Any]) -> dict[str, tuple[str, str, dict[str, Any]]]:
+    operations: dict[str, tuple[str, str, dict[str, Any]]] = {}
+    duplicates: set[str] = set()
+    for path, path_item in document.get("paths", {}).items():
+        if not isinstance(path, str) or not isinstance(path_item, dict):
+            continue
+        for method in ("delete", "get", "patch", "post", "put"):
+            operation = path_item.get(method)
+            if not isinstance(operation, dict):
+                continue
+            operation_id = operation.get("operationId")
+            if not isinstance(operation_id, str) or not operation_id:
+                continue
+            if operation_id in operations:
+                duplicates.add(operation_id)
+            operations[operation_id] = (method.upper(), path, operation)
+    if duplicates:
+        raise ValueError(f"KnowledgeFS OpenAPI contains duplicate operation ids: {sorted(duplicates)}")
+    return operations
+
+
+def _openapi_response_kind(operation: dict[str, Any]) -> Literal["binary", "buffered", "stream"]:
+    media_types = {
+        media_type
+        for status, response in operation.get("responses", {}).items()
+        if status == "2XX" or (len(status) == 3 and status.startswith("2") and status.isdigit())
+        for media_type in response.get("content", {})
+    }
+    if "text/event-stream" in media_types:
+        return "stream"
+    if "application/octet-stream" in media_types:
+        return "binary"
+    return "buffered"
+
+
+def _openapi_max_response_bytes(operation: dict[str, Any]) -> int:
+    value = operation.get("x-knowledge-fs-max-response-bytes")
+    if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+        raise ValueError("KnowledgeFS product OpenAPI operation has no positive response byte limit")
+    return value
+
+
+def _required_string(value: object, field: str) -> str:
+    if not isinstance(value, str) or not value.strip() or value != value.strip():
+        raise ValueError(f"KnowledgeFS {field} must be a non-empty trimmed string")
+    return value
+
+
+def _unique(values: Iterable[str], label: str) -> None:
+    sequence = tuple(values)
+    if len(sequence) != len(set(sequence)):
+        raise ValueError(f"KnowledgeFS {label} contains duplicate ids")
+
+
+__all__ = [
+    "CapabilityOperationPolicy",
+    "CapabilityOperationRuntimeContract",
+    "ProductOperationGapManifest",
+    "ProductOperationManifest",
+    "ProductOperationRuntimeContract",
+    "capability_operation_runtime_contracts",
+    "parse_capability_operation_policy",
+    "parse_product_operation_gap_manifest",
+    "parse_product_operation_manifest",
+    "product_operation_runtime_contracts",
+    "validate_product_operation_contracts",
+]

api/events/event_handlers/__init__.py

@@ -7,6 +7,9 @@ from .delete_tool_parameters_cache_when_sync_draft_workflow import (
     handle as handle_delete_tool_parameters_cache_when_sync_draft_workflow,
 )
 from .queue_credential_sync_when_tenant_created import handle as handle_queue_credential_sync_when_tenant_created
+from .queue_default_plugin_install_when_tenant_created import (
+    handle as handle_queue_default_plugin_install_when_tenant_created,
+)
 from .sync_plugin_trigger_when_app_created import handle as handle_sync_plugin_trigger_when_app_created
 from .sync_webhook_when_app_created import handle as handle_sync_webhook_when_app_created
 from .sync_workflow_schedule_when_app_published import handle as handle_sync_workflow_schedule_when_app_published
@@ -32,6 +35,7 @@ __all__ = [
     "handle_create_site_record_when_app_created",
     "handle_delete_tool_parameters_cache_when_sync_draft_workflow",
     "handle_queue_credential_sync_when_tenant_created",
+    "handle_queue_default_plugin_install_when_tenant_created",
     "handle_sync_plugin_trigger_when_app_created",
     "handle_sync_webhook_when_app_created",
     "handle_sync_workflow_schedule_when_app_published",

api/events/event_handlers/queue_default_plugin_install_when_tenant_created.py

@@ -0,0 +1,22 @@
+"""Queue default marketplace plugin installation after tenant creation."""
+
+import logging
+
+from configs import dify_config
+from events.tenant_event import tenant_was_created
+from tasks.install_default_plugins_task import install_default_plugins_task
+
+logger = logging.getLogger(__name__)
+
+
+@tenant_was_created.connect
+def handle(sender, **kwargs) -> None:
+    """Keep tenant creation non-blocking while installing configured plugins asynchronously."""
+    plugin_ids = dify_config.NEW_USER_DEFAULT_PLUGIN_ID_LIST
+    if not plugin_ids:
+        return
+
+    try:
+        install_default_plugins_task.delay(sender.id, plugin_ids)
+    except Exception:
+        logger.exception("Failed to queue default plugin installation for tenant %s", sender.id)