chore: refresh KnowledgeFS contract lock

# Conflicts:
#	api/tests/test_containers_integration_tests/services/test_workspace_service.py
#	api/tests/unit_tests/controllers/web/test_web_login.py
#	api/tests/unit_tests/libs/test_helper.py

.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/deploy-dev.yml

@@ -2,23 +2,70 @@ name: Deploy Dev
 
 on:
   workflow_run:
-    workflows: ["Build and Push API & Web"]
+    workflows: ["KnowledgeFS CI"]
     branches:
-      - "deploy/dev"
+      - "deploy/konwledge"
     types:
       - completed
 
+permissions: {}
+
 jobs:
   deploy:
     runs-on: depot-ubuntu-24.04
+    permissions:
+      actions: read
+      contents: read
     if: |
       github.event.workflow_run.conclusion == 'success' &&
-      github.event.workflow_run.head_branch == 'deploy/dev'
+      github.event.workflow_run.head_branch == 'deploy/konwledge'
     steps:
+      - name: Wait for API and Web image build
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        timeout-minutes: 35
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const workflowId = "build-push.yml";
+            const headBranch = context.payload.workflow_run.head_branch;
+            const headSha = context.payload.workflow_run.head_sha;
+            const deadline = Date.now() + 30 * 60 * 1000;
+            const pollIntervalMs = 15 * 1000;
+
+            while (Date.now() < deadline) {
+              const { data } = await github.rest.actions.listWorkflowRuns({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                workflow_id: workflowId,
+                branch: headBranch,
+                event: "push",
+                head_sha: headSha,
+                per_page: 10,
+              });
+              const run = data.workflow_runs[0];
+
+              if (!run) {
+                core.info(`Waiting for ${workflowId} to start for ${headSha}.`);
+              } else if (run.status !== "completed") {
+                core.info(`Waiting for ${run.html_url}; current status is ${run.status}.`);
+              } else if (run.conclusion !== "success") {
+                throw new Error(
+                  `${workflowId} did not succeed for ${headSha}: ${run.conclusion} (${run.html_url})`,
+                );
+              } else {
+                core.info(`Both image workflows succeeded for ${headSha}: ${run.html_url}`);
+                return;
+              }
+
+              await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+            }
+
+            throw new Error(`Timed out waiting for ${workflowId} to succeed for ${headSha}.`);
+
       - name: Deploy to server
         uses: appleboy/ssh-action@0ff4204d59e8e51228ff73bce53f80d53301dee2 # v1.2.5
         with:
-          host: ${{ secrets.SSH_HOST }}
+          host: ${{ secrets.SSH_NEW_RAG_HOST }}
           username: ${{ secrets.SSH_USER }}
           key: ${{ secrets.SSH_PRIVATE_KEY }}
           script: |

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

@@ -0,0 +1,514 @@
+name: KnowledgeFS CI
+
+on:
+  pull_request:
+    branches: ["main"]
+  merge_group:
+    branches: ["main"]
+    types: [checks_requested]
+  push:
+    branches: ["main", "deploy/konwledge"]
+  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
+      - quality
+    if: >-
+      (needs.check-changes.outputs.knowledge-fs == 'true' || github.event_name == 'workflow_dispatch') &&
+      needs.quality.result == 'success'
+    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' || github.ref == 'refs/heads/deploy/konwledge'))
+        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' || github.ref == 'refs/heads/deploy/konwledge')) }}
+          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:backend
+
+      - 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/web-e2e.yml

@@ -63,7 +63,6 @@ jobs:
           E2E_ADMIN_PASSWORD: E2eAdmin12345
           E2E_FORCE_WEB_BUILD: "1"
           E2E_INIT_PASSWORD: E2eInit12345
-          E2E_START_AGENT_BACKEND: "1"
         run: vp run e2e:full
 
       - name: Preserve Chromium E2E report and logs
@@ -139,6 +138,21 @@ jobs:
             exit 1
           fi
 
+          teardown_external_runtime() {
+            local run_status=$?
+            trap - EXIT
+            if ! vp run e2e:middleware:down; then
+              echo "::error title=E2E teardown failed::External runtime middleware did not shut down cleanly."
+              if [[ "$run_status" -eq 0 ]]; then
+                run_status=1
+              fi
+            fi
+            exit "$run_status"
+          }
+
+          trap teardown_external_runtime EXIT
+          vp run e2e:middleware:up
+          vp run e2e:post-merge:prepare
           vp run e2e:post-merge
 
       - name: Upload Cucumber report

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

api/.env.example

@@ -686,11 +686,25 @@ 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=
-# Shared with KnowledgeFS; use at least 32 random characters.
-KNOWLEDGE_FS_JWT_SECRET=
-KNOWLEDGE_FS_SSE_READ_TIMEOUT_SECONDS=300
+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
+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_TIMEOUT_SECONDS=10
+KNOWLEDGE_FS_JWKS_CACHE_MAX_AGE_SECONDS=300
+KNOWLEDGE_FS_PRODUCT_MAX_RESPONSE_BYTES=4194304
 
 # Marketplace configuration
 MARKETPLACE_ENABLED=true

api/Dockerfile

@@ -99,9 +99,9 @@ ENV VIRTUAL_ENV=/app/api/.venv
 COPY --from=packages --chown=dify:dify ${VIRTUAL_ENV} ${VIRTUAL_ENV}
 ENV PATH="${VIRTUAL_ENV}/bin:${PATH}"
 
+# Download nltk data
 RUN mkdir -p /usr/local/share/nltk_data \
-    && NLTK_DATA=/usr/local/share/nltk_data python -m nltk.downloader punkt_tab averaged_perceptron_tagger_eng stopwords \
-    && NLTK_DATA=/usr/local/share/nltk_data python -c "import nltk; nltk.data.find('tokenizers/punkt_tab'); nltk.data.find('taggers/averaged_perceptron_tagger_eng'); nltk.data.find('corpora/stopwords')" \
+    && NLTK_DATA=/usr/local/share/nltk_data python -c "import nltk; nltk.download('punkt'); nltk.download('averaged_perceptron_tagger'); nltk.download('stopwords')" \
     && chmod -R 755 /usr/local/share/nltk_data
 
 ENV TIKTOKEN_CACHE_DIR=/app/api/.tiktoken_cache

api/README.md

@@ -50,7 +50,9 @@ The scripts resolve paths relative to their location, so you can run them from a
    ./dev/start-worker
    ```
 
-1. Optional: start Celery Beat (scheduled tasks).
+1. Start Celery Beat when scheduled tasks are needed. This is required when
+   `KNOWLEDGE_FS_LIFECYCLE_WORKER_ENABLED=true` so provisioning and deletion
+   outbox commands are dispatched to the lifecycle worker.
 
    ```bash
    ./dev/start-beat

api/app_factory.py

@@ -183,6 +183,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,
@@ -233,6 +234,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/__init__.py

@@ -5,6 +5,8 @@ API adapters: request building from Dify product concepts, a thin client wrapper
 event adaptation for future workflow integration, and deterministic fakes.
 """
 
+from dify_agent.protocol import RuntimeLayerSpec, extract_runtime_layer_specs
+
 from clients.agent_backend.client import AgentBackendRunClient, DifyAgentBackendRunClient
 from clients.agent_backend.errors import (
     AgentBackendError,
@@ -45,6 +47,11 @@ from clients.agent_backend.request_builder import (
     AgentBackendWorkflowNodeRunInput,
     redact_for_agent_backend_log,
 )
+from clients.agent_backend.session_cleanup import (
+    AgentBackendSessionCleanupPayload,
+    AgentBackendSessionCleanupResult,
+    cleanup_agent_backend_session,
+)
 
 __all__ = [
     "AGENT_SOUL_PROMPT_LAYER_ID",
@@ -73,6 +80,8 @@ __all__ = [
     "AgentBackendRunRequestBuilder",
     "AgentBackendRunStartedInternalEvent",
     "AgentBackendRunSucceededInternalEvent",
+    "AgentBackendSessionCleanupPayload",
+    "AgentBackendSessionCleanupResult",
     "AgentBackendStreamError",
     "AgentBackendStreamInternalEvent",
     "AgentBackendTransportError",
@@ -81,6 +90,9 @@ __all__ = [
     "DifyAgentBackendRunClient",
     "FakeAgentBackendRunClient",
     "FakeAgentBackendScenario",
+    "RuntimeLayerSpec",
+    "cleanup_agent_backend_session",
     "create_agent_backend_run_client",
+    "extract_runtime_layer_specs",
     "redact_for_agent_backend_log",
 ]

api/clients/agent_backend/request_builder.py

@@ -16,6 +16,7 @@ from collections.abc import Mapping
 from typing import ClassVar, Literal
 
 from agenton.compositor import CompositorSessionSnapshot
+from agenton.compositor.schemas import LayerSessionSnapshot
 from agenton.layers import ExitIntent
 from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig
 from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID
@@ -36,7 +37,6 @@ from dify_agent.layers.execution_context import (
 )
 from dify_agent.layers.knowledge import DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID, DifyKnowledgeBaseLayerConfig
 from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig
-from dify_agent.layers.runtime import DIFY_RUNTIME_LAYER_TYPE_ID, DifyRuntimeLayerConfig
 from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig
 from dify_agent.protocol import (
     DIFY_AGENT_HISTORY_LAYER_ID,
@@ -47,6 +47,7 @@ from dify_agent.protocol import (
     LayerExitSignals,
     RunComposition,
     RunLayerSpec,
+    RuntimeLayerSpec,
 )
 from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator
 
@@ -55,7 +56,6 @@ WORKFLOW_NODE_JOB_PROMPT_LAYER_ID = "workflow_node_job_prompt"
 WORKFLOW_USER_PROMPT_LAYER_ID = "workflow_user_prompt"
 AGENT_APP_USER_PROMPT_LAYER_ID = "agent_app_user_prompt"
 DIFY_EXECUTION_CONTEXT_LAYER_ID = "execution_context"
-DIFY_RUNTIME_LAYER_ID = "runtime"
 DIFY_CONFIG_LAYER_ID = "config"
 DIFY_DRIVE_LAYER_ID = "drive"
 DIFY_PLUGIN_TOOLS_LAYER_ID = "tools"
@@ -66,11 +66,25 @@ DIFY_SHELL_LAYER_ID = "shell"
 type AgentConfigVersionKind = Literal["snapshot", "draft", "build_draft"]
 
 
+def _filter_snapshot_to_specs(
+    snapshot: CompositorSessionSnapshot,
+    specs: list[RuntimeLayerSpec],
+) -> CompositorSessionSnapshot:
+    """Keep only snapshot layers whose names appear in the cleanup spec list.
+
+    The agenton compositor rejects a snapshot whose layer-name sequence does
+    not match the active composition exactly. Cleanup-replay drops plugin
+    layers, so we must drop the matching snapshot entries here.
+    """
+    kept_names = {spec.name for spec in specs}
+    filtered_layers: list[LayerSessionSnapshot] = [layer for layer in snapshot.layers if layer.name in kept_names]
+    if len(filtered_layers) == len(snapshot.layers):
+        return snapshot
+    return CompositorSessionSnapshot(schema_version=snapshot.schema_version, layers=filtered_layers)
+
+
 def _shell_layer_deps() -> dict[str, str]:
-    return {
-        "execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID,
-        "runtime": DIFY_RUNTIME_LAYER_ID,
-    }
+    return {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}
 
 
 def _drive_layer_deps() -> dict[str, str]:
@@ -200,7 +214,6 @@ class AgentBackendWorkflowNodeRunInput(BaseModel):
 
     model: AgentBackendModelConfig
     execution_context: DifyExecutionContextLayerConfig
-    backend_binding_ref: str = Field(min_length=1)
     workflow_node_job_prompt: str
     user_prompt: str
     agent_soul_prompt: str | None = None
@@ -218,8 +231,8 @@ class AgentBackendWorkflowNodeRunInput(BaseModel):
     # the Agent Soul configures human involvement; a deferred call ends the run and
     # the workflow pauses via the existing HITL form mechanism (ENG-635).
     ask_human_config: DifyAskHumanLayerConfig | None = None
-    # Inject the sandboxed shell graph. Requires a deployment-selected runtime
-    # backend plus the product-resolved persistent Binding.
+    # Inject the sandboxed shell layer (dify.shell). Requires the agent backend
+    # to be wired with a shellctl entrypoint; see configs AGENT_SHELL_ENABLED.
     include_shell: bool = False
     shell_config: DifyShellLayerConfig | None = None
     session_snapshot: CompositorSessionSnapshot | None = None
@@ -227,6 +240,7 @@ class AgentBackendWorkflowNodeRunInput(BaseModel):
     # (ENG-638). Keyed by the original deferred tool_call_id.
     deferred_tool_results: DeferredToolResultsPayload | None = None
     include_history: bool = True
+    suspend_on_exit: bool = True
     metadata: dict[str, JsonValue] = Field(default_factory=dict)
 
     model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
@@ -250,7 +264,6 @@ class AgentBackendAgentAppRunInput(BaseModel):
 
     model: AgentBackendModelConfig
     execution_context: DifyExecutionContextLayerConfig
-    backend_binding_ref: str = Field(min_length=1)
     user_prompt: str
     agent_soul_prompt: str | None = None
     agent_config_version_kind: AgentConfigVersionKind = "snapshot"
@@ -266,8 +279,8 @@ class AgentBackendAgentAppRunInput(BaseModel):
     # Human-in-the-loop ask_human deferred tool (dify.ask_human). Present only when
     # the Agent Soul configures human involvement (ENG-635).
     ask_human_config: DifyAskHumanLayerConfig | None = None
-    # Inject the sandboxed shell graph. Requires a deployment-selected runtime
-    # backend plus the product-resolved persistent Binding.
+    # Inject the sandboxed shell layer (dify.shell). Requires the agent backend
+    # to be wired with a shellctl entrypoint; see configs AGENT_SHELL_ENABLED.
     include_shell: bool = False
     shell_config: DifyShellLayerConfig | None = None
     session_snapshot: CompositorSessionSnapshot | None = None
@@ -275,6 +288,7 @@ class AgentBackendAgentAppRunInput(BaseModel):
     # (ENG-638). Keyed by the original deferred tool_call_id.
     deferred_tool_results: DeferredToolResultsPayload | None = None
     include_history: bool = True
+    suspend_on_exit: bool = True
     metadata: dict[str, JsonValue] = Field(default_factory=dict)
 
     model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
@@ -336,14 +350,6 @@ class AgentBackendRunRequestBuilder:
             run_input.include_shell or run_input.config_layer_config is not None or run_input.drive_config is not None
         )
         if include_shell:
-            layers.append(
-                RunLayerSpec(
-                    name=DIFY_RUNTIME_LAYER_ID,
-                    type=DIFY_RUNTIME_LAYER_TYPE_ID,
-                    metadata=run_input.metadata,
-                    config=DifyRuntimeLayerConfig(backend_binding_ref=run_input.backend_binding_ref),
-                )
-            )
             # Sandboxed bash workspace (dify.shell). It enters before config/drive
             # so eager pulls materialize content in the same filesystem used by
             # model commands.
@@ -475,7 +481,53 @@ class AgentBackendRunRequestBuilder:
             metadata=run_input.metadata,
             session_snapshot=run_input.session_snapshot,
             deferred_tool_results=run_input.deferred_tool_results,
-            on_exit=LayerExitSignals(default=ExitIntent.SUSPEND),
+            on_exit=LayerExitSignals(
+                default=ExitIntent.SUSPEND if run_input.suspend_on_exit else ExitIntent.DELETE,
+            ),
+        )
+
+    def build_cleanup_request(
+        self,
+        *,
+        session_snapshot: CompositorSessionSnapshot,
+        runtime_layer_specs: list[RuntimeLayerSpec],
+        idempotency_key: str | None = None,
+        metadata: dict[str, JsonValue] | None = None,
+    ) -> CreateRunRequest:
+        """Build a lifecycle-only cleanup request that replays the prior layers.
+
+        The agenton compositor enforces that the session snapshot's layer names
+        match the active composition in order, so cleanup must replay the same
+        non-plugin layer graph that produced the snapshot. Plugin layers
+        (``dify.plugin.llm``, ``dify.plugin.tools``) are excluded from both the
+        composition and the snapshot before submission because their configs
+        may carry credentials or runtime-only declarations that are not
+        persisted between runs.
+        """
+        if not runtime_layer_specs:
+            raise ValueError(
+                "build_cleanup_request requires runtime_layer_specs; an empty "
+                "composition would fail the agent backend's snapshot validation."
+            )
+        request_metadata = dict(metadata or {})
+        request_metadata["agent_backend_lifecycle"] = "session_cleanup"
+        layers = [
+            RunLayerSpec(
+                name=spec.name,
+                type=spec.type,
+                deps=dict(spec.deps),
+                metadata=dict(spec.metadata),
+                config=spec.config,
+            )
+            for spec in runtime_layer_specs
+        ]
+        filtered_snapshot = _filter_snapshot_to_specs(session_snapshot, runtime_layer_specs)
+        return CreateRunRequest(
+            composition=RunComposition(layers=layers),
+            idempotency_key=idempotency_key,
+            metadata=request_metadata,
+            session_snapshot=filtered_snapshot,
+            on_exit=LayerExitSignals(default=ExitIntent.DELETE),
         )
 
     def build_for_workflow_node(self, run_input: AgentBackendWorkflowNodeRunInput) -> CreateRunRequest:
@@ -528,14 +580,6 @@ class AgentBackendRunRequestBuilder:
             run_input.include_shell or run_input.config_layer_config is not None or run_input.drive_config is not None
         )
         if include_shell:
-            layers.append(
-                RunLayerSpec(
-                    name=DIFY_RUNTIME_LAYER_ID,
-                    type=DIFY_RUNTIME_LAYER_TYPE_ID,
-                    metadata=run_input.metadata,
-                    config=DifyRuntimeLayerConfig(backend_binding_ref=run_input.backend_binding_ref),
-                )
-            )
             # Sandboxed bash workspace (dify.shell). It enters before drive so
             # drive can materialize mentioned targets with `dify-agent drive pull`
             # in the same shell-visible filesystem used by model commands.
@@ -669,7 +713,9 @@ class AgentBackendRunRequestBuilder:
             metadata=run_input.metadata,
             session_snapshot=run_input.session_snapshot,
             deferred_tool_results=run_input.deferred_tool_results,
-            on_exit=LayerExitSignals(default=ExitIntent.SUSPEND),
+            on_exit=LayerExitSignals(
+                default=ExitIntent.SUSPEND if run_input.suspend_on_exit else ExitIntent.DELETE,
+            ),
         )
 
 

api/clients/agent_backend/session_cleanup.py

@@ -0,0 +1,100 @@
+"""Shared API-side helper for Agent backend lifecycle-only session cleanup.
+
+Product code owns local row retirement and background-task dispatch. This module
+only adapts persisted cleanup inputs into the public ``dify-agent`` run
+protocol, performs the synchronous ``create_run + wait_run`` loop used by Celery
+workers, and reports whether the backend cleanup succeeded, was skipped, or
+failed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import ClassVar, Literal
+
+from agenton.compositor import CompositorSessionSnapshot
+from dify_agent.protocol import RuntimeLayerSpec
+from pydantic import BaseModel, ConfigDict, Field, JsonValue
+
+from clients.agent_backend.client import AgentBackendRunClient
+from clients.agent_backend.errors import AgentBackendError
+from clients.agent_backend.request_builder import AgentBackendRunRequestBuilder
+
+
+class AgentBackendSessionCleanupPayload(BaseModel):
+    """Serialized cleanup inputs preserved across API and Celery boundaries."""
+
+    session_snapshot: CompositorSessionSnapshot | None = None
+    runtime_layer_specs: list[RuntimeLayerSpec] = Field(default_factory=list)
+    idempotency_key: str | None = None
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+    timeout_seconds: float = 30.0
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
+
+
+@dataclass(frozen=True, slots=True)
+class AgentBackendSessionCleanupResult:
+    """Terminal outcome of one backend cleanup attempt."""
+
+    status: Literal["succeeded", "skipped", "failed"]
+    reason: str | None = None
+    cleanup_run_id: str | None = None
+
+    @classmethod
+    def succeeded(cls, cleanup_run_id: str) -> AgentBackendSessionCleanupResult:
+        return cls(status="succeeded", cleanup_run_id=cleanup_run_id)
+
+    @classmethod
+    def skipped(cls, reason: str) -> AgentBackendSessionCleanupResult:
+        return cls(status="skipped", reason=reason)
+
+    @classmethod
+    def failed(cls, reason: str, cleanup_run_id: str | None = None) -> AgentBackendSessionCleanupResult:
+        return cls(status="failed", reason=reason, cleanup_run_id=cleanup_run_id)
+
+
+def cleanup_agent_backend_session(
+    *,
+    payload: AgentBackendSessionCleanupPayload,
+    client: AgentBackendRunClient | None,
+    request_builder: AgentBackendRunRequestBuilder | None = None,
+) -> AgentBackendSessionCleanupResult:
+    """Run lifecycle-only cleanup against the Agent backend and report status."""
+    if client is None:
+        return AgentBackendSessionCleanupResult.skipped("no_agent_backend_client")
+    if payload.session_snapshot is None:
+        return AgentBackendSessionCleanupResult.skipped("missing_session_snapshot")
+    if not payload.runtime_layer_specs:
+        return AgentBackendSessionCleanupResult.skipped("missing_runtime_layer_specs")
+
+    builder = request_builder or AgentBackendRunRequestBuilder()
+    request = builder.build_cleanup_request(
+        session_snapshot=payload.session_snapshot,
+        runtime_layer_specs=payload.runtime_layer_specs,
+        idempotency_key=payload.idempotency_key,
+        metadata=payload.metadata,
+    )
+
+    try:
+        response = client.create_run(request)
+    except AgentBackendError as exc:
+        return AgentBackendSessionCleanupResult.failed(str(exc))
+
+    try:
+        status_response = client.wait_run(response.run_id, timeout_seconds=payload.timeout_seconds)
+    except AgentBackendError as exc:
+        return AgentBackendSessionCleanupResult.failed(str(exc), cleanup_run_id=response.run_id)
+
+    if status_response.status != "succeeded":
+        reason = status_response.error or f"cleanup run ended with status {status_response.status}"
+        return AgentBackendSessionCleanupResult.failed(reason, cleanup_run_id=response.run_id)
+
+    return AgentBackendSessionCleanupResult.succeeded(response.run_id)
+
+
+__all__ = [
+    "AgentBackendSessionCleanupPayload",
+    "AgentBackendSessionCleanupResult",
+    "cleanup_agent_backend_session",
+]

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,621 @@
+"""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.greenfield_initializer import KnowledgeFSWorkspaceGreenfieldInitializer
+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("greenfield-initialize")
+@click.option("--tenant-id", required=True)
+def greenfield_initialize(tenant_id: str) -> None:
+    """Idempotently initialize one Workspace that has no KnowledgeFS state."""
+
+    _operator_call(lambda: _greenfield_initializer().ensure_initialized(tenant_id=tenant_id))
+    _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 _greenfield_initializer() -> KnowledgeFSWorkspaceGreenfieldInitializer:
+    return KnowledgeFSWorkspaceGreenfieldInitializer(
+        session_factory.get_session_maker(),
+        cutover=_cutover_service(),
+    )
+
+
+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/system.py

@@ -6,7 +6,6 @@ from sqlalchemy import delete, select, update
 from sqlalchemy.orm import sessionmaker
 
 from configs import dify_config
-from enums.deployment_edition import DeploymentEdition
 from events.app_event import app_was_created
 from extensions.ext_database import db
 from extensions.ext_redis import redis_client
@@ -43,7 +42,7 @@ def reset_encrypt_key_pair():
     After the reset, all LLM credentials will become invalid, requiring re-entry.
     Only support SELF_HOSTED mode.
     """
-    if dify_config.DEPLOYMENT_EDITION == DeploymentEdition.CLOUD:
+    if dify_config.EDITION != "SELF_HOSTED":
         click.echo(click.style("This command is only for SELF_HOSTED installations.", fg="red"))
         return
     with sessionmaker(db.engine, expire_on_commit=False).begin() as session:

api/configs/extra/agent_backend_config.py

@@ -44,8 +44,9 @@ class AgentBackendConfig(BaseSettings):
 
     AGENT_SHELL_ENABLED: bool = Field(
         description=(
-            "Inject the Home, Workspace, Sandbox, and Shell runtime layers into Agent runs. "
-            "Requires Dify Agent to have a deployment-selected runtime backend."
+            "Inject the dify.shell layer (sandboxed bash workspace) into Agent runs. "
+            "Requires the agent backend to be wired with a shellctl entrypoint before "
+            "shell-using Agent runs are executed."
         ),
         default=True,
     )

api/configs/extra/knowledge_fs_config.py

@@ -1,30 +1,72 @@
-"""Configuration for the optional KnowledgeFS Console bridge."""
+"""Configuration for the optional KnowledgeFS control-plane integration."""
 
+from ipaddress import ip_address
 from urllib.parse import urlsplit
 
-from pydantic import Field, PositiveFloat, SecretStr, field_validator, model_validator
+from pydantic import Field, PositiveFloat, PositiveInt, SecretStr, field_validator, model_validator
 from pydantic_settings import BaseSettings
 
 
 class KnowledgeFSConfig(BaseSettings):
-    """Server-only settings for the KnowledgeFS production connection."""
+    """Server-only KnowledgeFS connection and rollout settings."""
 
     KNOWLEDGE_FS_ENABLED: bool = Field(
         default=False,
-        description="Enable the private KnowledgeFS Console bridge.",
+        description="Enable the KnowledgeFS control-plane product routes.",
     )
+    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_JWT_SECRET: SecretStr | None = Field(
+    KNOWLEDGE_FS_DIRECT_ORIGIN: str | None = Field(
         default=None,
-        min_length=32,
-        description="Shared secret used to sign short-lived KnowledgeFS service JWTs.",
+        description="Public KnowledgeFS origin returned with direct upload capabilities.",
     )
-    KNOWLEDGE_FS_SSE_READ_TIMEOUT_SECONDS: PositiveFloat = Field(default=300.0, le=3600.0, allow_inf_nan=False)
+    KNOWLEDGE_FS_DIRECT_UPLOAD_READY: bool = Field(
+        default=False,
+        description="Confirm that KnowledgeFS direct upload and its browser origin policy are deployed and verified.",
+    )
+    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_JWT_SECRET",
+        "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
@@ -40,25 +82,57 @@ class KnowledgeFSConfig(BaseSettings):
     @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("KNOWLEDGE_FS_BASE_URL must be an absolute HTTP(S) URL")
+            raise ValueError(f"{name} must be an absolute HTTP(S) URL")
         try:
             _ = parsed.port
         except ValueError as exc:
-            raise ValueError("KNOWLEDGE_FS_BASE_URL must include a valid port") from exc
-        if parsed.username or parsed.password or parsed.query or parsed.fragment:
-            raise ValueError("KNOWLEDGE_FS_BASE_URL must not include credentials, query, or fragment")
+            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 not self.KNOWLEDGE_FS_ENABLED:
-            return self
-        if bool(self.KNOWLEDGE_FS_BASE_URL) != bool(self.KNOWLEDGE_FS_JWT_SECRET):
-            raise ValueError("KNOWLEDGE_FS_BASE_URL and KNOWLEDGE_FS_JWT_SECRET must be configured together")
-        if not self.KNOWLEDGE_FS_BASE_URL:
-            raise ValueError("KnowledgeFS connection settings are required when the integration is enabled")
+        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/constants/__init__.py

@@ -77,3 +77,5 @@ COOKIE_NAME_PASSPORT = "passport"
 HEADER_NAME_CSRF_TOKEN = "X-CSRF-Token"
 HEADER_NAME_APP_CODE = "X-App-Code"
 HEADER_NAME_PASSPORT = "X-App-Passport"
+HEADER_NAME_IDEMPOTENCY_KEY = "Idempotency-Key"
+HEADER_NAME_REQUEST_ID = "X-Request-ID"

api/controllers/common/session.py

@@ -52,7 +52,7 @@ def with_session[T, **P, R](
                         session.commit()
                         return result
                     except Exception:
-                        session.rollback()  # guard-ignore: no-new-controller-sqlalchemy -- decorator owns rollback
+                        session.rollback()  # noqa: no-new-controller-sqlalchemy decorator owns transaction rollback
                         raise
 
             with session_factory.create_session() as session:

api/controllers/common/wraps.py

@@ -10,7 +10,6 @@ from extensions.ext_database import db
 from libs.login import current_account_with_tenant
 from models.dataset import Dataset
 from models.model import App
-from services.agent.roster_service import AgentRosterService
 from services.enterprise.rbac_service import RBACService
 
 __all__ = ["RBACPermission", "RBACResourceScope", "enforce_rbac_access", "rbac_permission_required"]
@@ -52,7 +51,7 @@ def enforce_rbac_access(
     check_resource_type = None if resource_type == RBACResourceScope.WORKSPACE else resource_type
     resource_id = None
     if resource_required and check_resource_type:
-        resource_id = _extract_resource_id(resource_type, tenant_id, path_args)
+        resource_id = _extract_resource_id(resource_type, path_args)
         if _is_resource_owned_by_current_user(tenant_id, account_id, resource_type, resource_id):
             return
     allowed = RBACService.CheckAccess.check(
@@ -132,14 +131,11 @@ def _is_resource_owned_by_current_user(
     return False
 
 
-def _extract_resource_id(
-    resource_type: RBACResourceScope, tenant_id: str, path_args: dict[str, object] | None = None
-) -> str:
+def _extract_resource_id(resource_type: RBACResourceScope, path_args: dict[str, object] | None = None) -> str:
     """Extract the resource ID from matched path arguments.
 
     Some legacy route classes use neutral names such as ``resource_id`` for
-    app/dataset resources, and Agent routes carry ``agent_id``, which is
-    resolved to the App backing that Agent.
+    app/dataset resources, and Agent App routes use ``agent_id`` as the app id.
     Dataset endpoints behind a rag-pipeline route contain ``pipeline_id``
     instead of ``dataset_id``. In that case we look up the associated
     ``Dataset`` row via ``Dataset.pipeline_id``.
@@ -150,19 +146,10 @@ def _extract_resource_id(
     matched_args = {**view_args, **(path_args or {})}
 
     if resource_type == RBACResourceScope.APP:
-        app_id = matched_args.get("app_id")
-        if app_id:
-            return str(app_id)
-
-        agent_id = matched_args.get("agent_id")
-        if agent_id:
-            authz_app_id = AgentRosterService(db.session).peek_authz_app_id(tenant_id=tenant_id, agent_id=str(agent_id))
-            return authz_app_id or str(agent_id)
-
-        resource_id = matched_args.get("resource_id")
-        if resource_id:
-            return str(resource_id)
-        raise ValueError("Missing app_id in request path")
+        app_id = matched_args.get("app_id") or matched_args.get("agent_id") or matched_args.get("resource_id")
+        if not app_id:
+            raise ValueError("Missing app_id in request path")
+        return str(app_id)
 
     if resource_type == RBACResourceScope.DATASET:
         dataset_id = matched_args.get("dataset_id") or matched_args.get("resource_id")

api/controllers/console/__init__.py

@@ -38,7 +38,6 @@ from . import (
     feature,
     human_input_form,
     init_validate,
-    knowledge_fs_proxy,
     notification,
     onboarding,
     ping,
@@ -127,6 +126,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
 
@@ -197,7 +197,7 @@ __all__ = [
     "human_input_form",
     "init_validate",
     "installed_app",
-    "knowledge_fs_proxy",
+    "knowledge_fs_resources",
     "load_balancing_config",
     "login",
     "mcp_server",

api/controllers/console/agent/composer.py

@@ -230,7 +230,6 @@ class WorkflowAgentComposerSaveToRosterApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user_id
     @with_current_tenant_id
     @with_session
@@ -440,7 +439,6 @@ class SnippetAgentComposerSaveToRosterApi(Resource):
     @rbac_permission_required(
         RBACResourceScope.WORKSPACE, RBACPermission.SNIPPETS_CREATE_AND_MODIFY, resource_required=False
     )
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user_id
     @with_current_tenant_id
     @with_session
@@ -480,7 +478,6 @@ class AgentComposerApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user_id
     @with_current_tenant_id
     @with_session

api/controllers/console/agent/roster.py

@@ -62,7 +62,7 @@ from libs.datetime_utils import parse_time_range
 from libs.helper import dump_response
 from libs.login import login_required
 from models import Account
-from models.agent import Agent, AgentStatus
+from models.agent import Agent, AgentConfigDraftType, AgentStatus
 from models.agent_config_entities import AgentSoulConfig
 from models.enums import ApiTokenType
 from models.model import ApiToken, App, IconType
@@ -265,6 +265,13 @@ class AgentDebugConversationRefreshResponse(BaseModel):
     debug_conversation_message_count: int = 0
 
 
+class AgentDebugConversationRefreshPayload(BaseModel):
+    draft_type: AgentConfigDraftType = Field(
+        default=AgentConfigDraftType.DEBUG_BUILD,
+        description="Agent draft surface whose conversation should be refreshed",
+    )
+
+
 class AgentPublishPayload(BaseModel):
     version_note: str | None = Field(default=None, description="Optional note for this published Agent version")
 
@@ -308,6 +315,7 @@ register_schema_models(
     AgentAppCopyPayload,
     AgentPublishPayload,
     AgentBuildDraftCheckoutPayload,
+    AgentDebugConversationRefreshPayload,
     ComposerSavePayload,
     AgentApiStatusPayload,
     AgentInviteOptionsQuery,
@@ -387,10 +395,11 @@ def _serialize_agent_app_detail(
     payload["backing_app_id"] = roster_service.runtime_backing_app_id(agent)
     payload["hidden_app_backed"] = bool(agent.backing_app_id and agent.backing_app_id != agent.app_id)
     payload["id"] = agent.id
-    debug_conversation_id = roster_service.get_or_create_build_conversation(
+    debug_conversation_id = roster_service.get_or_create_agent_app_debug_conversation_id(
         tenant_id=app_model.tenant_id,
         agent_id=agent.id,
         account_id=current_user.id,
+        draft_type=AgentConfigDraftType.DEBUG_BUILD,
         commit=False,
     )
     message_count = roster_service.count_agent_app_debug_conversation_messages(
@@ -430,10 +439,11 @@ def _serialize_agent_app_pagination(session: Session, app_pagination, *, tenant_
         tenant_id=tenant_id,
         agent_ids=[agent.id for agent in agents_by_app_id.values()],
     )
-    debug_conversation_ids_by_agent_id = roster_service.load_or_create_build_conversation_ids_by_agent_id(
+    debug_conversation_ids_by_agent_id = roster_service.load_or_create_agent_app_debug_conversation_ids_by_agent_id(
         tenant_id=tenant_id,
         agents=list(agents_by_app_id.values()),
         account_id=current_user.id,
+        draft_type=AgentConfigDraftType.DEBUG_BUILD,
     )
     payload = AgentAppPagination.model_validate(
         app_pagination,
@@ -524,23 +534,9 @@ def _parse_observability_time_range(start: str | None, end: str | None, account:
 
 
 def _query_values(name: str, alias_name: str | None = None) -> list[str]:
-    def _get_values(field_name: str) -> list[str]:
-        values = request.args.getlist(field_name)
-        indexed_values: list[tuple[int, list[str]]] = []
-        prefix = f"{field_name}["
-        for key in request.args:
-            if not key.startswith(prefix) or not key.endswith("]"):
-                continue
-            index = key[len(prefix) : -1]
-            if index.isdigit():
-                indexed_values.append((int(index), request.args.getlist(key)))
-        for _, items in sorted(indexed_values):
-            values.extend(items)
-        return values
-
-    values = _get_values(name)
+    values = request.args.getlist(name)
     if alias_name:
-        values.extend(_get_values(alias_name))
+        values.extend(request.args.getlist(alias_name))
     return [value.strip() for value in values if value.strip()]
 
 
@@ -551,7 +547,6 @@ class AgentAppListApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -589,7 +584,6 @@ class AgentAppListApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -631,7 +625,6 @@ class AgentAppApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -657,7 +650,6 @@ class AgentAppApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_tenant_id
     @with_session
     def delete(self, session: Session, tenant_id: str, agent_id: UUID):
@@ -668,6 +660,16 @@ class AgentAppApi(Resource):
 
 @console_ns.route("/agent/<uuid:agent_id>/debug-conversation/refresh")
 class AgentDebugConversationRefreshApi(Resource):
+    @console_ns.expect(console_ns.models[AgentDebugConversationRefreshPayload.__name__])
+    @console_ns.doc(
+        params={
+            "payload": {
+                "in": "body",
+                "required": False,
+                "schema": {"$ref": f"#/components/schemas/{AgentDebugConversationRefreshPayload.__name__}"},
+            }
+        }
+    )
     @console_ns.response(
         200,
         "Agent debug conversation refreshed",
@@ -682,10 +684,12 @@ class AgentDebugConversationRefreshApi(Resource):
     @with_current_tenant_id
     @with_session
     def post(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
-        debug_conversation_id = _agent_roster_service(session).reset_build_conversation(
+        args = AgentDebugConversationRefreshPayload.model_validate(request.get_json(silent=True) or {})
+        debug_conversation_id = _agent_roster_service(session).refresh_agent_app_debug_conversation_id(
             tenant_id=tenant_id,
             agent_id=str(agent_id),
             account_id=current_user.id,
+            draft_type=args.draft_type,
         )
         return AgentDebugConversationRefreshResponse(
             debug_conversation_id=debug_conversation_id,
@@ -703,7 +707,6 @@ class AgentPublishApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -726,10 +729,9 @@ class AgentBuildDraftCheckoutApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user
     @with_current_tenant_id
-    @with_session(write=False)
+    @with_session
     def post(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
         args = AgentBuildDraftCheckoutPayload.model_validate(console_ns.payload or {})
         return AgentComposerService.checkout_agent_app_build_draft(
@@ -786,7 +788,7 @@ class AgentBuildDraftApi(Resource):
     @edit_permission_required
     @with_current_user
     @with_current_tenant_id
-    @with_session(write=False)
+    @with_session
     def delete(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
         return AgentComposerService.discard_agent_app_build_draft(
             session=session,
@@ -803,10 +805,9 @@ class AgentBuildDraftApplyApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user
     @with_current_tenant_id
-    @with_session(write=False)
+    @with_session
     def post(self, session: Session, tenant_id: str, current_user: Account, agent_id: UUID):
         return AgentComposerService.apply_agent_app_build_draft(
             session=session,
@@ -826,7 +827,6 @@ class AgentAppCopyApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user
     @with_current_tenant_id
     @with_session
@@ -852,7 +852,6 @@ class AgentApiAccessApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_tenant_id
     @with_session(write=False)
     def get(self, session: Session, tenant_id: str, agent_id: UUID):
@@ -869,7 +868,6 @@ class AgentApiStatusApi(Resource):
     @login_required
     @is_admin_or_owner_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
     @with_current_tenant_id
     @with_session
@@ -888,7 +886,6 @@ class AgentApiKeyListApi(BaseApiKeyListResource):
     token_prefix = "app-"
 
     @console_ns.response(200, "Agent service API keys", console_ns.models[ApiKeyList.__name__])
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_tenant_id
     @with_session(write=False)
     def get(self, session: Session, tenant_id: str, agent_id: UUID) -> dict[str, object]:
@@ -899,7 +896,6 @@ class AgentApiKeyListApi(BaseApiKeyListResource):
     @console_ns.response(400, "Maximum keys exceeded")
     @with_current_tenant_id
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
     @with_session
     def post(self, session: Session, tenant_id: str, agent_id: UUID) -> tuple[dict[str, object], int]:
@@ -919,7 +915,6 @@ class AgentApiKeyApi(BaseApiKeyResource):
     @console_ns.response(204, "Agent service API key deleted")
     @with_current_user
     @with_current_tenant_id
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
     @with_session
     def delete(
@@ -965,7 +960,6 @@ class AgentLogsApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user
     @with_current_tenant_id
     @with_session(write=False)
@@ -1004,7 +998,6 @@ class AgentLogMessagesApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user
     @with_current_tenant_id
     @with_session(write=False)
@@ -1043,7 +1036,6 @@ class AgentLogSourcesApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user
     @with_current_tenant_id
     @with_session(write=False)
@@ -1064,7 +1056,6 @@ class AgentStatisticsSummaryApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user
     @with_current_tenant_id
     @with_session(write=False)
@@ -1090,7 +1081,6 @@ class AgentRosterVersionsApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_tenant_id
     @with_session(write=False)
     def get(self, session: Session, tenant_id: str, agent_id: UUID):
@@ -1106,7 +1096,6 @@ class AgentRosterVersionDetailApi(Resource):
     @setup_required
     @login_required
     @account_initialization_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_tenant_id
     @with_session(write=False)
     def get(self, session: Session, tenant_id: str, agent_id: UUID, version_id: UUID):
@@ -1127,7 +1116,6 @@ class AgentRosterVersionRestoreApi(Resource):
     @login_required
     @account_initialization_required
     @edit_permission_required
-    @rbac_permission_required(RBACResourceScope.WORKSPACE, RBACPermission.AGENT_MANAGE, resource_required=False)
     @with_current_user
     @with_current_tenant_id
     @with_session

api/controllers/console/apikey.py

@@ -12,7 +12,6 @@ from werkzeug.exceptions import Forbidden
 from configs import dify_config
 from controllers.common.schema import register_response_schema_models
 from controllers.common.session import with_session
-from controllers.console.app.wraps import agent_manage_required_for_agent_app
 from fields.base import ResponseModel
 from libs.helper import dump_response, to_timestamp
 from libs.login import login_required
@@ -195,7 +194,6 @@ class AppApiKeyListResource(BaseApiKeyListResource):
     @console_ns.doc(params={"resource_id": "App ID"})
     @console_ns.response(200, "API keys retrieved successfully", console_ns.models[ApiKeyList.__name__])
     @with_current_tenant_id
-    @agent_manage_required_for_agent_app
     @with_session(write=False)
     def get(self, session: Session, current_tenant_id: str, resource_id: UUID) -> dict[str, object]:
         """Get all API keys for an app"""
@@ -212,7 +210,6 @@ class AppApiKeyListResource(BaseApiKeyListResource):
     @with_current_tenant_id
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
-    @agent_manage_required_for_agent_app
     @with_session
     def post(self, session: Session, current_tenant_id: str, resource_id: UUID) -> tuple[dict[str, object], int]:
         """Create a new API key for an app"""
@@ -236,7 +233,6 @@ class AppApiKeyResource(BaseApiKeyResource):
     @with_current_user
     @with_current_tenant_id
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
-    @agent_manage_required_for_agent_app
     @with_session
     def delete(
         self,

api/controllers/console/app/agent_app_sandbox.py

@@ -1,7 +1,7 @@
 """Console routes for Agent App and workflow Agent sandbox file access.
 
-The API accepts product-facing Conversation, Build Draft, or Workflow Node
-Execution locators and proxies list/read/upload to the agent backend's
+The API keeps product-facing locators (conversation or workflow node identity)
+on this public boundary and proxies list/read/upload to the agent backend's new
 ``/sandbox`` contract.
 """
 
@@ -26,16 +26,10 @@ from controllers.common.session import with_session
 from controllers.console import console_ns
 from controllers.console.agent.app_helpers import resolve_agent_runtime_app_model
 from controllers.console.app.wraps import get_app_model
-from controllers.console.wraps import (
-    account_initialization_required,
-    setup_required,
-    with_current_tenant_id,
-    with_current_user,
-)
+from controllers.console.wraps import account_initialization_required, setup_required, with_current_tenant_id
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.login import login_required
-from models import Account
 from models.model import App, AppMode
 from services.agent_app_sandbox_service import (
     AgentAppSandboxService,
@@ -43,43 +37,52 @@ from services.agent_app_sandbox_service import (
     WorkflowAgentSandboxService,
 )
 
+_NODE_EXECUTION_ID_DESCRIPTION = (
+    "Optional workflow node execution ID. When omitted, the latest active session for the node is used."
+)
+
 
 class AgentSandboxListQuery(BaseModel):
-    caller_type: Literal["conversation", "build_draft"]
-    caller_id: str = Field(min_length=1, description="Agent App caller ID")
+    conversation_id: str = Field(min_length=1, description="Agent App conversation ID")
     path: str = Field(default=".", description="Directory path relative to the sandbox workspace")
 
 
 class AgentSandboxInfoQuery(BaseModel):
-    caller_type: Literal["conversation", "build_draft"]
-    caller_id: str = Field(min_length=1, description="Agent App caller ID")
+    conversation_id: str = Field(min_length=1, description="Agent App conversation ID")
 
 
 class AgentSandboxFileQuery(BaseModel):
-    caller_type: Literal["conversation", "build_draft"]
-    caller_id: str = Field(min_length=1, description="Agent App caller ID")
+    conversation_id: str = Field(min_length=1, description="Agent App conversation ID")
     path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
 
 
 class AgentSandboxUploadPayload(BaseModel):
-    caller_type: Literal["conversation", "build_draft"]
-    caller_id: str = Field(min_length=1, description="Agent App caller ID")
+    conversation_id: str = Field(min_length=1, description="Agent App conversation ID")
     path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
 
 
 class WorkflowAgentSandboxListQuery(BaseModel):
-    node_execution_id: str = Field(min_length=1, description="Workflow node execution ID")
     path: str = Field(default=".", description="Directory path relative to the sandbox workspace")
+    node_execution_id: str | None = Field(
+        default=None,
+        description=_NODE_EXECUTION_ID_DESCRIPTION,
+    )
 
 
 class WorkflowAgentSandboxFileQuery(BaseModel):
-    node_execution_id: str = Field(min_length=1, description="Workflow node execution ID")
     path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
+    node_execution_id: str | None = Field(
+        default=None,
+        description=_NODE_EXECUTION_ID_DESCRIPTION,
+    )
 
 
 class WorkflowAgentSandboxUploadPayload(BaseModel):
-    node_execution_id: str = Field(min_length=1, description="Workflow node execution ID")
     path: str = Field(min_length=1, description="File path relative to the sandbox workspace")
+    node_execution_id: str | None = Field(
+        default=None,
+        description=_NODE_EXECUTION_ID_DESCRIPTION,
+    )
 
 
 class SandboxFileEntryResponse(ResponseModel):
@@ -96,6 +99,7 @@ class SandboxListResponse(ResponseModel):
 
 
 class SandboxInfoResponse(ResponseModel):
+    session_id: str
     workspace_cwd: str
 
 
@@ -151,19 +155,15 @@ class AgentAppSandboxInfoResource(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    @with_current_user
     @with_session(write=False)
-    def get(self, session: Session, current_user: Account, tenant_id: str, agent_id: UUID):
+    def get(self, session: Session, tenant_id: str, agent_id: UUID):
         app_model = resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
         query = query_params_from_request(AgentSandboxInfoQuery)
         try:
             result = AgentAppSandboxService().get_info(
                 tenant_id=tenant_id,
                 app_id=app_model.id,
-                agent_id=str(agent_id),
-                caller_type=query.caller_type,
-                caller_id=query.caller_id,
-                account_id=current_user.id,
+                conversation_id=query.conversation_id,
             )
         except Exception as exc:
             return _handle(exc)
@@ -180,19 +180,15 @@ class AgentAppSandboxListResource(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    @with_current_user
     @with_session(write=False)
-    def get(self, session: Session, current_user: Account, tenant_id: str, agent_id: UUID):
+    def get(self, session: Session, tenant_id: str, agent_id: UUID):
         app_model = resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
         query = query_params_from_request(AgentSandboxListQuery)
         try:
             result = AgentAppSandboxService().list_files(
                 tenant_id=tenant_id,
                 app_id=app_model.id,
-                agent_id=str(agent_id),
-                caller_type=query.caller_type,
-                caller_id=query.caller_id,
-                account_id=current_user.id,
+                conversation_id=query.conversation_id,
                 path=query.path,
             )
         except Exception as exc:
@@ -210,19 +206,15 @@ class AgentAppSandboxReadResource(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    @with_current_user
     @with_session(write=False)
-    def get(self, session: Session, current_user: Account, tenant_id: str, agent_id: UUID):
+    def get(self, session: Session, tenant_id: str, agent_id: UUID):
         app_model = resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
         query = query_params_from_request(AgentSandboxFileQuery)
         try:
             result = AgentAppSandboxService().read_file(
                 tenant_id=tenant_id,
                 app_id=app_model.id,
-                agent_id=str(agent_id),
-                caller_type=query.caller_type,
-                caller_id=query.caller_id,
-                account_id=current_user.id,
+                conversation_id=query.conversation_id,
                 path=query.path,
             )
         except Exception as exc:
@@ -240,19 +232,15 @@ class AgentAppSandboxUploadResource(Resource):
     @login_required
     @account_initialization_required
     @with_current_tenant_id
-    @with_current_user
     @with_session(write=False)
-    def post(self, session: Session, current_user: Account, tenant_id: str, agent_id: UUID):
+    def post(self, session: Session, tenant_id: str, agent_id: UUID):
         app_model = resolve_agent_runtime_app_model(session=session, tenant_id=tenant_id, agent_id=agent_id)
         payload = AgentSandboxUploadPayload.model_validate(request.get_json(silent=True) or {})
         try:
             result = AgentAppSandboxService().upload_file(
                 tenant_id=tenant_id,
                 app_id=app_model.id,
-                agent_id=str(agent_id),
-                caller_type=payload.caller_type,
-                caller_id=payload.caller_id,
-                account_id=current_user.id,
+                conversation_id=payload.conversation_id,
                 path=payload.path,
             )
         except Exception as exc:

api/controllers/console/app/app.py

@@ -9,7 +9,7 @@ from flask_restx import Resource
 from pydantic import AliasChoices, BaseModel, Field, ValidationInfo, computed_field, field_validator, model_validator
 from sqlalchemy import select
 from sqlalchemy.orm import Session
-from werkzeug.exceptions import BadRequest, Forbidden, NotFound
+from werkzeug.exceptions import BadRequest, NotFound
 
 from configs import dify_config
 from controllers.common.app_access import resolve_app_access_filter
@@ -23,7 +23,7 @@ from controllers.common.schema import (
     register_schema_models,
 )
 from controllers.console import console_ns
-from controllers.console.app.wraps import agent_manage_required_for_agent_app, get_app_model, with_session
+from controllers.console.app.wraps import get_app_model, with_session
 from controllers.console.workspace.models import LoadBalancingPayload
 from controllers.console.wraps import (
     RBACPermission,
@@ -76,7 +76,6 @@ from services.entities.knowledge_entities.knowledge_entities import (
     WeightModel,
     WeightVectorSetting,
 )
-from services.errors.account import NoPermissionError
 from services.feature_service import FeatureService
 from tasks.initialize_created_app_rbac_access_task import initialize_created_app_rbac_access_task
 
@@ -905,7 +904,6 @@ class AppApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    @agent_manage_required_for_agent_app
     @with_session
     @get_app_model(mode=None)
     def put(self, session: Session, app_model: App):
@@ -940,7 +938,6 @@ class AppApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_DELETE)
-    @agent_manage_required_for_agent_app
     @with_session
     @get_app_model
     def delete(self, session: Session, app_model: App):
@@ -965,7 +962,6 @@ class AppCopyApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_CREATE_AND_MANAGEMENT)
-    @agent_manage_required_for_agent_app
     @with_current_user
     @with_current_tenant_id
     @get_app_model(mode=None)
@@ -977,19 +973,16 @@ class AppCopyApi(Resource):
         with Session(db.engine, expire_on_commit=False) as session:
             import_service = AppDslService(session)
             yaml_content = import_service.export_dsl(app_model=app_model, session=session, include_secret=True)
-            try:
-                result = import_service.import_app(
-                    account=current_user,
-                    import_mode=ImportMode.YAML_CONTENT,
-                    yaml_content=yaml_content,
-                    name=args.name,
-                    description=args.description,
-                    icon_type=args.icon_type,
-                    icon=args.icon,
-                    icon_background=args.icon_background,
-                )
-            except NoPermissionError as e:
-                raise Forbidden(str(e))
+            result = import_service.import_app(
+                account=current_user,
+                import_mode=ImportMode.YAML_CONTENT,
+                yaml_content=yaml_content,
+                name=args.name,
+                description=args.description,
+                icon_type=args.icon_type,
+                icon=args.icon,
+                icon_background=args.icon_background,
+            )
             if result.status == ImportStatus.FAILED:
                 session.rollback()
                 return dump_response(AppImportResponse, result), 400
@@ -1043,7 +1036,6 @@ class AppExportApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_IMPORT_EXPORT_DSL)
-    @agent_manage_required_for_agent_app
     @get_app_model
     def get(self, app_model: App):
         """Export app"""
@@ -1068,7 +1060,6 @@ class AppPublishToCreatorsPlatformApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_IMPORT_EXPORT_DSL)
-    @agent_manage_required_for_agent_app
     @with_current_user_id
     @get_app_model(mode=None)
     def post(self, current_user_id: str, app_model: App):
@@ -1099,7 +1090,6 @@ class AppNameApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    @agent_manage_required_for_agent_app
     @with_session
     @get_app_model(mode=None)
     def post(self, session: Session, app_model: App):
@@ -1127,7 +1117,6 @@ class AppIconApi(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_EDIT)
-    @agent_manage_required_for_agent_app
     @with_session
     @get_app_model(mode=None)
     def post(self, session: Session, app_model: App):
@@ -1161,7 +1150,6 @@ class AppSiteStatus(Resource):
     @account_initialization_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
-    @agent_manage_required_for_agent_app
     @with_session
     @get_app_model(mode=None)
     def post(self, session: Session, app_model: App):
@@ -1189,7 +1177,6 @@ class AppApiStatus(Resource):
     @is_admin_or_owner_required
     @account_initialization_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
-    @agent_manage_required_for_agent_app
     @with_session
     @get_app_model(mode=None)
     def post(self, session: Session, app_model: App):

api/controllers/console/app/app_import.py

@@ -1,7 +1,6 @@
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session
-from werkzeug.exceptions import Forbidden
 
 from configs import dify_config
 from controllers.common.schema import register_enum_models, register_schema_models
@@ -29,7 +28,6 @@ from services.app_dsl_service import (
 )
 from services.enterprise.enterprise_service import EnterpriseService
 from services.entities.dsl_entities import CheckDependenciesResult, ImportStatus
-from services.errors.account import NoPermissionError
 from services.feature_service import FeatureService
 
 from .. import console_ns
@@ -93,21 +91,18 @@ class AppImportApi(Resource):
             import_service = AppDslService(session)
             # Import app
             account = current_user
-            try:
-                result = import_service.import_app(
-                    account=account,
-                    import_mode=args.mode,
-                    yaml_content=args.yaml_content,
-                    yaml_url=args.yaml_url,
-                    name=args.name,
-                    description=args.description,
-                    icon_type=args.icon_type,
-                    icon=args.icon,
-                    icon_background=args.icon_background,
-                    app_id=args.app_id,
-                )
-            except NoPermissionError as e:
-                raise Forbidden(str(e))
+            result = import_service.import_app(
+                account=account,
+                import_mode=args.mode,
+                yaml_content=args.yaml_content,
+                yaml_url=args.yaml_url,
+                name=args.name,
+                description=args.description,
+                icon_type=args.icon_type,
+                icon=args.icon,
+                icon_background=args.icon_background,
+                app_id=args.app_id,
+            )
             if result.status == ImportStatus.FAILED:
                 session.rollback()
             else:
@@ -162,10 +157,7 @@ class AppImportConfirmApi(Resource):
             import_service = AppDslService(session)
             # Confirm import
             account = current_user
-            try:
-                result = import_service.confirm_import(import_id=import_id, account=account)
-            except NoPermissionError as e:
-                raise Forbidden(str(e))
+            result = import_service.confirm_import(import_id=import_id, account=account)
             if result.status == ImportStatus.FAILED:
                 session.rollback()
             else:

api/controllers/console/app/completion.py

@@ -36,7 +36,7 @@ from controllers.console.wraps import (
     with_current_user_id,
 )
 from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
-from core.app.entities.app_invoke_entities import InvokeFrom
+from core.app.entities.app_invoke_entities import AGENT_RUNTIME_EXIT_INTENT_ARG, InvokeFrom
 from core.app.features.rate_limiting.rate_limit import RateLimitGenerator
 from core.errors.error import (
     ModelCurrentlyNotSupportError,
@@ -351,38 +351,27 @@ def _resolve_current_user_agent_debug_conversation_id(
     app_model: App,
     agent_id: str | None,
     draft_type: AgentConfigDraftType,
-    start_new: bool = False,
 ) -> str:
-    """Resolve the current editor's Build or Preview conversation."""
+    """Resolve the current editor's conversation without crossing draft surfaces."""
 
     roster_service = AgentRosterService(session)
-    resolved_agent_id = agent_id
-    if not resolved_agent_id:
-        agent = roster_service.get_app_backing_agent(tenant_id=current_tenant_id, app_id=str(app_model.id))
-        if agent is None:
-            raise AgentNotFoundError()
-        resolved_agent_id = agent.id
+    if agent_id:
+        return roster_service.get_or_create_agent_app_debug_conversation_id(
+            tenant_id=current_tenant_id,
+            agent_id=agent_id,
+            account_id=current_user.id,
+            draft_type=draft_type,
+        )
 
-    if draft_type == AgentConfigDraftType.DEBUG_BUILD:
-        return roster_service.get_or_create_build_conversation(
-            tenant_id=current_tenant_id,
-            agent_id=resolved_agent_id,
-            account_id=current_user.id,
-        )
-    if start_new:
-        return roster_service.rotate_preview_conversation(
-            tenant_id=current_tenant_id,
-            agent_id=resolved_agent_id,
-            account_id=current_user.id,
-        )
-    conversation_id = roster_service.get_current_preview_conversation(
+    agent = roster_service.get_app_backing_agent(tenant_id=current_tenant_id, app_id=str(app_model.id))
+    if agent is None:
+        raise AgentNotFoundError()
+    return roster_service.get_or_create_agent_app_debug_conversation_id(
         tenant_id=current_tenant_id,
-        agent_id=resolved_agent_id,
+        agent_id=agent.id,
         account_id=current_user.id,
+        draft_type=draft_type,
     )
-    if conversation_id is None:
-        raise NotFound("Conversation Not Exists.")
-    return conversation_id
 
 
 def _create_chat_message(
@@ -398,17 +387,13 @@ def _create_chat_message(
     args = args_model.model_dump(exclude_none=True, by_alias=True)
 
     if AppMode.value_of(app_model.mode) == AppMode.AGENT:
-        draft_type = AgentConfigDraftType(args_model.draft_type)
-        # Preview follows the normal chat contract: an omitted/empty conversation ID starts a new
-        # conversation. Build chat keeps its stable mapping so build drafts and finalization stay continuous.
         debug_conversation_id = _resolve_current_user_agent_debug_conversation_id(
             session=session,
             current_tenant_id=current_tenant_id or app_model.tenant_id,
             current_user=current_user,
             app_model=app_model,
             agent_id=agent_id,
-            draft_type=draft_type,
-            start_new=draft_type == AgentConfigDraftType.DRAFT and not args_model.conversation_id,
+            draft_type=AgentConfigDraftType(args_model.draft_type),
         )
         if args_model.conversation_id and args_model.conversation_id != debug_conversation_id:
             raise NotFound("Conversation Not Exists.")
@@ -454,6 +439,7 @@ def _create_build_chat_finalization_message(
         "draft_type": "debug_build",
         "conversation_id": debug_conversation_id,
         "auto_generate_name": False,
+        AGENT_RUNTIME_EXIT_INTENT_ARG: "delete",
     }
     external_trace_id = get_external_trace_id(request)
     if external_trace_id:

api/controllers/console/app/site.py

@@ -10,7 +10,7 @@ from constants.languages import supported_language
 from controllers.common.schema import register_schema_models
 from controllers.common.session import with_session
 from controllers.console import console_ns
-from controllers.console.app.wraps import agent_manage_required_for_agent_app, get_app_model
+from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
     RBACPermission,
     RBACResourceScope,
@@ -93,7 +93,6 @@ class AppSite(Resource):
     @login_required
     @edit_permission_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
-    @agent_manage_required_for_agent_app
     @account_initialization_required
     @with_current_user
     @with_session
@@ -146,7 +145,6 @@ class AppSiteAccessTokenReset(Resource):
     @login_required
     @is_admin_or_owner_required
     @rbac_permission_required(RBACResourceScope.APP, RBACPermission.APP_RELEASE_AND_VERSION)
-    @agent_manage_required_for_agent_app
     @account_initialization_required
     @with_current_user
     @with_session

api/controllers/console/app/workflow.py

@@ -76,13 +76,11 @@ from models import Account, App
 from models.model import AppMode
 from models.workflow import Workflow
 from repositories.workflow_collaboration_repository import WORKFLOW_ONLINE_USERS_PREFIX
-from services.agent.retirement_service import WorkflowAgentRetirementService
 from services.app_generate_service import AppGenerateService
 from services.errors.app import IsDraftWorkflowError, WorkflowHashNotEqualError, WorkflowNotFoundError
 from services.errors.llm import InvokeRateLimitError
 from services.workflow_ref_service import WorkflowRefService
 from services.workflow_service import DraftWorkflowDeletionError, WorkflowInUseError, WorkflowService
-from tasks.collect_agent_resources_task import enqueue_agent_resource_collection
 
 logger = logging.getLogger(__name__)
 
@@ -319,7 +317,7 @@ class _WorkflowResponseSource:
         self._session = session
 
     def __getattr__(self, name: str) -> object:
-        return getattr(self._workflow, name)  # guard-ignore: no-new-getattr -- delegates model fields
+        return getattr(self._workflow, name)  # noqa: no-new-getattr response adapter delegates model fields
 
     @property
     def created_by_account(self) -> Account | None:
@@ -1247,7 +1245,7 @@ class PublishedWorkflowApi(Resource):
 
         workflow_service = WorkflowService()
         with sessionmaker(db.engine).begin() as session:
-            workflow, retirement_candidates = workflow_service.publish_workflow(
+            workflow = workflow_service.publish_workflow(
                 session=session,
                 app_model=app_model,
                 account=current_user,
@@ -1264,16 +1262,6 @@ class PublishedWorkflowApi(Resource):
 
             workflow_created_at = TimestampField().format(workflow.created_at)
 
-        binding_ids, home_snapshot_ids = WorkflowAgentRetirementService.retire_unowned(
-            tenant_id=app_model.tenant_id,
-            agent_ids=retirement_candidates,
-            account_id=current_user.id,
-        )
-        enqueue_agent_resource_collection(
-            tenant_id=app_model.tenant_id,
-            binding_ids=binding_ids,
-            home_snapshot_ids=home_snapshot_ids,
-        )
         return {
             "result": "success",
             "created_at": workflow_created_at,

api/controllers/console/app/wraps.py

@@ -12,22 +12,14 @@ from typing import cast, overload
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
-from configs import dify_config
 from controllers.common.session import with_session
-from controllers.common.wraps import RBACPermission, RBACResourceScope, enforce_rbac_access
 from controllers.console.app.error import AppNotFoundError
 from extensions.ext_database import db
 from libs.login import current_account_with_tenant
 from models import App, AppMode, TrialApp
-from models.agent import AgentScope
 from services.recommended_app_service import RecommendedAppService
 
-__all__ = [
-    "agent_manage_required_for_agent_app",
-    "get_app_model",
-    "get_app_model_with_trial",
-    "with_session",
-]
+__all__ = ["get_app_model", "get_app_model_with_trial", "with_session"]
 
 
 def _load_app_model(session: Session, app_id: str) -> App | None:
@@ -56,45 +48,6 @@ def _load_app_model_with_trial(session: Session, app_id: str) -> App | None:
     return app_model
 
 
-def agent_manage_required_for_agent_app[**P, R](view: Callable[P, R]) -> Callable[P, R]:
-    """Gate generic app management routes that target an Agent App.
-
-    A hidden workflow-only backing App only reuses the App runtime and is not
-    part of the general app management plane, so generic routes reject it
-    outright. Managing a roster Agent App mutates the roster Agent behind it
-    (rename/icon sync, archive, API enablement), so it additionally requires
-    workspace ``agent.manage`` on top of the route's existing App permission
-    checks when RBAC is enabled. A no-op for non-agent Apps. Must be placed
-    above ``get_app_model`` so the ``app_id`` path parameter is still present.
-    """
-
-    @wraps(view)
-    def decorated(*args: P.args, **kwargs: P.kwargs) -> R:
-        raw_app_id = kwargs.get("app_id") or kwargs.get("resource_id")
-        if raw_app_id is not None:
-            app_model = _load_app_model_from_scoped_session(str(raw_app_id))
-            binding = (
-                app_model.agent_app_binding_with_session(session=db.session(), include_archived=True)
-                if app_model is not None
-                else None
-            )
-            if binding is not None:
-                if binding.scope == AgentScope.WORKFLOW_ONLY:
-                    raise AppNotFoundError()
-                if dify_config.RBAC_ENABLED:
-                    current_user, current_tenant_id = current_account_with_tenant()
-                    enforce_rbac_access(
-                        tenant_id=current_tenant_id,
-                        account_id=current_user.id,
-                        resource_type=RBACResourceScope.WORKSPACE,
-                        scene=RBACPermission.AGENT_MANAGE,
-                        resource_required=False,
-                    )
-        return view(*args, **kwargs)
-
-    return decorated
-
-
 def _get_injected_session(args: tuple[object, ...]) -> Session | None:
     """Return the request session inserted by `with_session`, if this handler has been migrated."""
     if len(args) < 2:

api/controllers/console/auth/activate.py

@@ -7,13 +7,10 @@ from configs import dify_config
 from constants.languages import supported_language
 from controllers.common.schema import query_params_from_model, register_schema_models
 from controllers.console import console_ns
-from controllers.console.auth.error import InvitationAccountMismatchError
 from controllers.console.error import AccountInFreezeError, AlreadyActivateError
 from extensions.ext_database import db
 from libs.datetime_utils import naive_utc_now
 from libs.helper import EmailStr, timezone
-from libs.login import current_account_with_tenant
-from libs.token import extract_access_token
 from models import AccountStatus
 from models.account import TenantAccountJoin, TenantAccountRole
 from services.account_service import RegisterService, TenantService
@@ -139,12 +136,6 @@ class ActivateApi(Resource):
     )
     @console_ns.response(400, "Already activated or invalid token")
     def post(self):
-        """Accept an invitation without letting an existing session act for another account.
-
-        Token-only activation remains available for legacy clients. When the request already
-        carries a console session, that session must belong to the account encoded in the
-        invitation before the token is consumed or tenant membership is changed.
-        """
         args = ActivatePayload.model_validate(console_ns.payload)
 
         normalized_request_email = args.email.lower() if args.email else None
@@ -155,11 +146,6 @@ class ActivateApi(Resource):
             raise AlreadyActivateError()
 
         account = invitation["account"]
-        if extract_access_token(request):
-            current_account, _ = current_account_with_tenant()
-            if current_account.id != account.id:
-                raise InvitationAccountMismatchError()
-
         if dify_config.BILLING_ENABLED and BillingService.is_email_in_freeze(account.email):
             raise AccountInFreezeError()
 

api/controllers/console/auth/error.py

@@ -13,12 +13,6 @@ class InvalidEmailError(BaseHTTPException):
     code = 400
 
 
-class InvitationAccountMismatchError(BaseHTTPException):
-    error_code = "invitation_account_mismatch"
-    description = "This invitation was sent to another account. Please sign in with the invited account."
-    code = 403
-
-
 class PasswordMismatchError(BaseHTTPException):
     error_code = "password_mismatch"
     description = "The passwords do not match."

api/controllers/console/auth/oauth_server.py

@@ -56,7 +56,6 @@ class OAuthProviderTokenResponse(BaseModel):
 
 
 class OAuthProviderAccountResponse(BaseModel):
-    id: str
     name: str
     email: str
     avatar: str | None = None
@@ -252,7 +251,6 @@ class OAuthServerUserAccountApi(Resource):
     def post(self, oauth_provider_app: OAuthProviderApp, account: Account):
         return jsonable_encoder(
             {
-                "id": account.id,
                 "name": account.name,
                 "email": account.email,
                 "avatar": account.avatar,

api/controllers/console/datasets/datasets.py

@@ -218,7 +218,7 @@ class _DatasetQueryResponseSource:
         return self.query.get_queries(session=self.session)
 
     def __getattr__(self, name: str) -> Any:
-        return getattr(self.query, name)  # guard-ignore: no-new-getattr -- delegates model fields
+        return getattr(self.query, name)  # noqa: no-new-getattr response adapter delegates model fields
 
 
 class DatasetQueryListResponse(ResponseModel):
@@ -257,7 +257,7 @@ class _RelatedAppResponseSource:
         return self.app.mode_compatible_with_agent_with_session(session=self.session)
 
     def __getattr__(self, name: str) -> Any:
-        return getattr(self.app, name)  # guard-ignore: no-new-getattr -- delegates model fields
+        return getattr(self.app, name)  # noqa: no-new-getattr response adapter delegates model fields
 
 
 class RelatedAppListResponse(ResponseModel):

api/controllers/console/datasets/external.py

@@ -106,7 +106,7 @@ class ExternalKnowledgeApiResponseSource:
         return self.external_knowledge_api.get_dataset_bindings(session=self.session)
 
     def __getattr__(self, name: str) -> Any:
-        return getattr(self.external_knowledge_api, name)  # guard-ignore: no-new-getattr -- delegates model fields
+        return getattr(self.external_knowledge_api, name)  # noqa: no-new-getattr response adapter delegates model fields
 
 
 def external_knowledge_api_response(

api/controllers/console/explore/trial.py

@@ -404,7 +404,7 @@ class TrialWorkflowResponseSource:
         return self.workflow.get_tool_published(session=self.session)
 
     def __getattr__(self, name: str) -> Any:
-        return getattr(self.workflow, name)  # guard-ignore: no-new-getattr -- delegates model fields
+        return getattr(self.workflow, name)  # noqa: no-new-getattr response adapter delegates model fields
 
 
 register_schema_models(

api/controllers/console/init_validate.py

@@ -8,7 +8,6 @@ from sqlalchemy.orm import Session
 
 from configs import dify_config
 from controllers.fastopenapi import console_router
-from enums.deployment_edition import DeploymentEdition
 from extensions.ext_database import db
 from models.model import DifySetup
 from services.account_service import TenantService
@@ -64,7 +63,7 @@ def validate_init_password(payload: InitValidatePayload) -> InitValidateResponse
 
 
 def get_init_validate_status() -> bool:
-    if dify_config.DEPLOYMENT_EDITION != DeploymentEdition.CLOUD:
+    if dify_config.EDITION == "SELF_HOSTED":
         if os.environ.get("INIT_PASSWORD"):
             if session.get("is_init_validated"):
                 return True

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/knowledge_fs_proxy.py

@@ -1,419 +0,0 @@
-"""Authenticated transport adapter for the Console-to-KnowledgeFS proxy.
-
-These raw Blueprint routes deliberately stay outside Dify's OpenAPI surface:
-KnowledgeFS owns the wire contract consumed by the frontend. The catch-all path
-avoids resource-specific Dify controllers, while the forwarding module consumes
-only the operations explicitly enabled by Dify's product registry. The registry
-can be validated explicitly against the pinned KnowledgeFS contract during development.
-Console auth and contract-specific dataset RBAC run before forwarding. Request
-bodies are capped at 64 MiB, JSON and binary responses have separate bounds,
-SSE responses remain streaming with a bounded idle read timeout, and only safe
-response headers are exposed. Operation-specific upstream error mappings are
-applied before Console JSON error handling; the default maps 401 to 502 so it
-cannot trigger browser-session recovery and preserves resource-level 403.
-"""
-
-from __future__ import annotations
-
-import logging
-from collections.abc import Callable, Iterator
-from functools import wraps
-from http import HTTPStatus
-from typing import NoReturn, cast
-
-import httpx
-from flask import Response, request, stream_with_context
-from flask.typing import ResponseReturnValue
-from werkzeug.exceptions import (
-    BadGateway,
-    Forbidden,
-    GatewayTimeout,
-    HTTPException,
-    NotFound,
-    RequestEntityTooLarge,
-    ServiceUnavailable,
-    default_exceptions,
-)
-
-from configs import dify_config
-from controllers.console import api, bp
-from controllers.console.wraps import (
-    account_initialization_required,
-    cloud_edition_billing_rate_limit_check,
-    setup_required,
-)
-from core.helper import ssrf_proxy
-from libs.login import current_account_with_tenant, login_required
-from services.knowledge_fs_operations import KnowledgeFSMethod
-from services.knowledge_fs_proxy import (
-    KnowledgeFSAccessDeniedError,
-    KnowledgeFSAuthorization,
-    KnowledgeFSConfigurationError,
-    KnowledgeFSRouteNotAllowedError,
-    KnowledgeFSTimeoutError,
-    KnowledgeFSTransportError,
-    KnowledgeFSUpstreamResponse,
-    authorize_knowledge_fs_request,
-    get_knowledge_fs_operation,
-    proxy_authorized_knowledge_fs_request,
-    proxy_knowledge_fs_request,
-)
-
-logger = logging.getLogger(__name__)
-
-type _KnowledgeFSRequestForwarder = Callable[
-    [str | None, str | None, bytes | None, bytes | None],
-    KnowledgeFSUpstreamResponse,
-]
-
-_MAX_PROXY_BODY_BYTES = 64 * 1024 * 1024
-_RESPONSE_HEADER_ALLOWLIST = (
-    "Cache-Control",
-    "Content-Disposition",
-    "Content-Type",
-    "Retry-After",
-    "X-Trace-Id",
-)
-_RESPONSE_HEADER_DENYLIST = frozenset(
-    {
-        "authorization",
-        "connection",
-        "cookie",
-        "keep-alive",
-        "proxy-authenticate",
-        "proxy-authorization",
-        "set-cookie",
-        "te",
-        "trailer",
-        "transfer-encoding",
-        "upgrade",
-    }
-)
-
-
-def _console_api_errors[**P](
-    view: Callable[P, ResponseReturnValue],
-) -> Callable[P, ResponseReturnValue]:
-    """Route raw Blueprint exceptions through the Console API JSON handlers."""
-
-    @wraps(view)
-    def decorated(*args: P.args, **kwargs: P.kwargs) -> ResponseReturnValue:
-        try:
-            return view(*args, **kwargs)
-        except Exception as exc:
-            return api.handle_error(exc)
-
-    return decorated
-
-
-def _knowledge_fs_enabled[**P](
-    view: Callable[P, ResponseReturnValue],
-) -> Callable[P, ResponseReturnValue]:
-    """Hide the complete KnowledgeFS route surface while the bridge is disabled."""
-
-    @wraps(view)
-    def decorated(*args: P.args, **kwargs: P.kwargs) -> ResponseReturnValue:
-        if not dify_config.KNOWLEDGE_FS_ENABLED:
-            raise NotFound()
-        return view(*args, **kwargs)
-
-    return decorated
-
-
-def _translate_proxy_error(exc: Exception, *, tenant_id: str) -> NoReturn:
-    """Map forwarding failures to the stable Console HTTP error surface."""
-    if isinstance(exc, KnowledgeFSRouteNotAllowedError):
-        raise NotFound() from exc
-    if isinstance(exc, KnowledgeFSAccessDeniedError):
-        raise Forbidden() from exc
-    if isinstance(exc, KnowledgeFSConfigurationError):
-        logger.error("KnowledgeFS request was blocked by invalid configuration for tenant_id=%s", tenant_id)
-        raise ServiceUnavailable("KnowledgeFS integration is misconfigured") from exc
-    if isinstance(exc, KnowledgeFSTimeoutError):
-        raise GatewayTimeout("KnowledgeFS request timed out") from exc
-    if isinstance(exc, KnowledgeFSTransportError):
-        logger.warning("KnowledgeFS transport request failed for tenant_id=%s", tenant_id)
-        raise BadGateway("KnowledgeFS is unavailable") from exc
-    raise exc
-
-
-def _knowledge_fs_operation_access_required(
-    view: Callable[[KnowledgeFSAuthorization], ResponseReturnValue],
-) -> Callable[[KnowledgeFSMethod, str], ResponseReturnValue]:
-    """Authorize one declared operation before billing and request-body work."""
-
-    @wraps(view)
-    def decorated(method: KnowledgeFSMethod, upstream_path: str) -> ResponseReturnValue:
-        current_user, tenant_id = current_account_with_tenant()
-        try:
-            authorization = authorize_knowledge_fs_request(
-                account=current_user,
-                tenant_id=tenant_id,
-                method=method,
-                path=upstream_path,
-            )
-        except KnowledgeFSRouteNotAllowedError as exc:
-            raise NotFound() from exc
-        except KnowledgeFSAccessDeniedError as exc:
-            _translate_proxy_error(exc, tenant_id=tenant_id)
-        return view(authorization)
-
-    return decorated
-
-
-def _request_body() -> bytes:
-    """Read the raw body up to the proxy limit or raise RequestEntityTooLarge."""
-    body = request.stream.read(_MAX_PROXY_BODY_BYTES + 1)
-    if len(body) > _MAX_PROXY_BODY_BYTES:
-        raise RequestEntityTooLarge("KnowledgeFS proxy request body is too large")
-    return body
-
-
-def _stream_response_body(
-    upstream: httpx.Response,
-    *,
-    tenant_id: str,
-    max_response_bytes: int,
-) -> Iterator[bytes]:
-    """Yield one bounded SSE response and always release its pooled connection."""
-    total_bytes = 0
-    try:
-        for chunk in upstream.iter_bytes():
-            total_bytes += len(chunk)
-            if total_bytes > max_response_bytes:
-                logger.warning("KnowledgeFS stream exceeded the proxy limit for tenant_id=%s", tenant_id)
-                raise ssrf_proxy.ResponseTooLargeError(f"response exceeded {max_response_bytes} bytes")
-            yield chunk
-    finally:
-        upstream.close()
-
-
-def _proxy_response(
-    upstream_result: KnowledgeFSUpstreamResponse,
-    *,
-    tenant_id: str,
-    contract_response_headers: tuple[str, ...],
-    max_response_bytes: int,
-) -> Response:
-    """Expose raw content, status, and allowlisted headers from KnowledgeFS.
-
-    Raises:
-        HTTPException: KnowledgeFS returns a status normalized by the operation contract.
-    """
-    upstream = upstream_result.response
-    mapped_status = dict(upstream_result.operation.error_status_map).get(upstream.status_code)
-    if mapped_status is not None:
-        upstream.close()
-        description = "KnowledgeFS upstream request failed"
-        if upstream.status_code == HTTPStatus.UNAUTHORIZED:
-            description = "KnowledgeFS authentication failed"
-            logger.error(
-                "KnowledgeFS rejected the Dify server credential with HTTP %s for tenant_id=%s",
-                upstream.status_code,
-                tenant_id,
-            )
-        exception_type = default_exceptions.get(mapped_status)
-        if exception_type is None:
-            exception = HTTPException(description)
-            exception.code = mapped_status
-            raise exception
-        raise exception_type(description)
-
-    allowed_header_names = dict.fromkeys(
-        name.lower() for name in (*_RESPONSE_HEADER_ALLOWLIST, *contract_response_headers)
-    )
-    headers = {
-        name: value
-        for name in allowed_header_names
-        if name not in _RESPONSE_HEADER_DENYLIST
-        if (value := upstream.headers.get(name)) is not None
-    }
-    if upstream_result.response_kind == "stream":
-        response = Response(
-            stream_with_context(  # pyrefly: ignore[no-matching-overload]
-                _stream_response_body(
-                    upstream,
-                    tenant_id=tenant_id,
-                    max_response_bytes=max_response_bytes,
-                )
-            ),
-            status=upstream.status_code,
-            headers=headers,
-        )
-        response.call_on_close(upstream.close)
-        return response
-
-    try:
-        content = upstream.content
-    finally:
-        upstream.close()
-    return Response(content, status=upstream.status_code, headers=headers)
-
-
-def _proxy_current_request(
-    *,
-    method: KnowledgeFSMethod,
-    tenant_id: str,
-    forward: _KnowledgeFSRequestForwarder,
-) -> Response:
-    """Forward the current raw request through one preconfigured service entry."""
-    if not dify_config.KNOWLEDGE_FS_ENABLED:
-        raise NotFound()
-    try:
-        proxy_result = forward(
-            request.headers.get("Accept"),
-            request.content_type,
-            request.query_string or None,
-            _request_body() if method != "GET" else None,
-        )
-    except (
-        KnowledgeFSConfigurationError,
-        KnowledgeFSAccessDeniedError,
-        KnowledgeFSRouteNotAllowedError,
-        KnowledgeFSTimeoutError,
-        KnowledgeFSTransportError,
-    ) as exc:
-        _translate_proxy_error(exc, tenant_id=tenant_id)
-    return _proxy_response(
-        proxy_result,
-        tenant_id=tenant_id,
-        contract_response_headers=proxy_result.operation.response_headers,
-        max_response_bytes=proxy_result.operation.max_response_bytes,
-    )
-
-
-def _proxy_request(
-    method: KnowledgeFSMethod,
-    upstream_path: str,
-) -> Response:
-    """Authorize and forward the current request through the combined service use case."""
-    if not dify_config.KNOWLEDGE_FS_ENABLED:
-        raise NotFound()
-    current_user, tenant_id = current_account_with_tenant()
-
-    def forward(
-        accept: str | None,
-        content_type: str | None,
-        query: bytes | None,
-        body: bytes | None,
-    ) -> KnowledgeFSUpstreamResponse:
-        return proxy_knowledge_fs_request(
-            account=current_user,
-            method=method,
-            path=upstream_path,
-            tenant_id=tenant_id,
-            accept=accept,
-            content_type=content_type,
-            query=query,
-            body=body,
-            request_headers=request.headers,
-        )
-
-    return _proxy_current_request(method=method, tenant_id=tenant_id, forward=forward)
-
-
-def _proxy_authorized_request(authorization: KnowledgeFSAuthorization) -> Response:
-    """Forward the current request using one previously authorized operation capability.
-
-    Args:
-        authorization: Request-scoped capability produced before billing and body parsing.
-
-    Returns:
-        The filtered response returned by KnowledgeFS.
-
-    Raises:
-        HTTPException: The integration is disabled or forwarding fails.
-    """
-    operation = authorization.operation
-    tenant_id = authorization.tenant_id
-
-    def forward(
-        accept: str | None,
-        content_type: str | None,
-        query: bytes | None,
-        body: bytes | None,
-    ) -> KnowledgeFSUpstreamResponse:
-        return proxy_authorized_knowledge_fs_request(
-            authorization=authorization,
-            accept=accept,
-            content_type=content_type,
-            query=query,
-            body=body,
-            request_headers=request.headers,
-        )
-
-    return _proxy_current_request(method=operation.method, tenant_id=tenant_id, forward=forward)
-
-
-@_knowledge_fs_enabled
-@_knowledge_fs_operation_access_required
-@cloud_edition_billing_rate_limit_check("knowledge")
-def _proxy_knowledge_fs_non_get(
-    authorization: KnowledgeFSAuthorization,
-) -> ResponseReturnValue:
-    """Apply knowledge billing checks to one allowlisted non-GET operation."""
-    return _proxy_authorized_request(authorization)
-
-
-@bp.route(
-    "/knowledge-fs/<path:upstream_path>",
-    methods=["OPTIONS"],
-    provide_automatic_options=False,
-)
-@_console_api_errors
-@_knowledge_fs_enabled
-def proxy_knowledge_fs_options(upstream_path: str) -> ResponseReturnValue:
-    """Complete a CORS preflight only for an enabled Console operation."""
-    requested_method = cast(KnowledgeFSMethod, request.headers.get("Access-Control-Request-Method", "").upper())
-    try:
-        get_knowledge_fs_operation(requested_method, upstream_path)
-    except KnowledgeFSRouteNotAllowedError as exc:
-        raise NotFound() from exc
-    return Response(status=HTTPStatus.NO_CONTENT)
-
-
-@bp.route(
-    "/knowledge-fs/<path:upstream_path>",
-    methods=["GET"],
-    provide_automatic_options=False,
-)
-@_console_api_errors
-@_knowledge_fs_enabled
-@setup_required
-@login_required
-@account_initialization_required
-def proxy_knowledge_fs_get(upstream_path: str) -> ResponseReturnValue:
-    """Forward one authenticated, dataset-readable GET request.
-
-    Args:
-        upstream_path: Relative KFS path captured after the Console proxy prefix.
-
-    Returns:
-        The filtered raw KnowledgeFS response or a Console JSON error response.
-    """
-    if request.method != "GET":
-        raise NotFound()
-    return _proxy_request("GET", upstream_path)
-
-
-@bp.route(
-    "/knowledge-fs/<path:upstream_path>",
-    methods=["DELETE", "PATCH", "POST", "PUT"],
-    provide_automatic_options=False,
-)
-@_console_api_errors
-@_knowledge_fs_enabled
-@setup_required
-@login_required
-@account_initialization_required
-def proxy_knowledge_fs_write(upstream_path: str) -> ResponseReturnValue:
-    """Forward one authenticated non-GET request under its contract access policy.
-
-    Args:
-        upstream_path: Relative KFS path captured after the Console proxy prefix.
-
-    Returns:
-        The filtered raw KnowledgeFS response or a Console JSON error response.
-    """
-    method = cast(KnowledgeFSMethod, request.method)
-    return _proxy_knowledge_fs_non_get(method, upstream_path)

api/controllers/console/setup.py

@@ -6,7 +6,6 @@ from sqlalchemy import select
 
 from configs import dify_config
 from controllers.fastopenapi import console_router
-from enums.deployment_edition import DeploymentEdition
 from libs.helper import EmailStr, extract_remote_ip
 from libs.password import valid_password
 from models.model import DifySetup, db
@@ -53,7 +52,7 @@ def get_setup_status_api() -> SetupStatusResponse:
 
     Only bootstrap-safe status information should be returned by this endpoint.
     """
-    if dify_config.DEPLOYMENT_EDITION != DeploymentEdition.CLOUD:
+    if dify_config.EDITION == "SELF_HOSTED":
         setup_status = get_setup_status()
         if setup_status and not isinstance(setup_status, bool):
             return SetupStatusResponse(step="finished", setup_at=setup_status.setup_at.isoformat())
@@ -103,7 +102,7 @@ def setup_system(payload: SetupRequestPayload) -> SetupResponse:
 
 
 def get_setup_status() -> DifySetup | bool | None:
-    if dify_config.DEPLOYMENT_EDITION != DeploymentEdition.CLOUD:
+    if dify_config.EDITION == "SELF_HOSTED":
         return db.session.scalar(select(DifySetup).limit(1))
 
     return True

api/controllers/console/snippets/snippet_workflow.py

@@ -56,12 +56,10 @@ from libs.helper import TimestampField
 from libs.login import current_account_with_tenant, login_required
 from models import Account
 from models.snippet import CustomizedSnippet
-from services.agent.retirement_service import WorkflowAgentRetirementService
 from services.agent.workflow_publish_service import WorkflowAgentPublishService
 from services.errors.app import IsDraftWorkflowError, WorkflowHashNotEqualError, WorkflowNotFoundError
 from services.snippet_generate_service import SnippetGenerateService
 from services.snippet_service import SnippetService
-from tasks.collect_agent_resources_task import enqueue_agent_resource_collection
 
 logger = logging.getLogger(__name__)
 
@@ -297,9 +295,8 @@ class SnippetPublishedWorkflowApi(Resource):
 
         with Session(db.engine) as session:
             snippet = session.merge(snippet)
-            tenant_id = snippet.tenant_id
             try:
-                workflow, retirement_candidates = snippet_service.publish_workflow(
+                workflow = snippet_service.publish_workflow(
                     session=session,
                     snippet=snippet,
                     account=current_user,
@@ -309,16 +306,6 @@ class SnippetPublishedWorkflowApi(Resource):
             except ValueError as e:
                 return {"message": str(e)}, 400
 
-        binding_ids, home_snapshot_ids = WorkflowAgentRetirementService.retire_unowned(
-            tenant_id=tenant_id,
-            agent_ids=retirement_candidates,
-            account_id=current_user.id,
-        )
-        enqueue_agent_resource_collection(
-            tenant_id=tenant_id,
-            binding_ids=binding_ids,
-            home_snapshot_ids=home_snapshot_ids,
-        )
         return {
             "result": "success",
             "created_at": workflow_created_at,

api/controllers/console/workspace/account.py

@@ -46,7 +46,6 @@ from controllers.console.wraps import (
     with_current_tenant_id,
     with_current_user,
 )
-from enums.deployment_edition import DeploymentEdition
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from fields.member_fields import AccountResponse
@@ -263,7 +262,7 @@ class AccountInitApi(Resource):
         payload = console_ns.payload or {}
         args = AccountInitPayload.model_validate(payload)
 
-        if dify_config.DEPLOYMENT_EDITION == DeploymentEdition.CLOUD:
+        if dify_config.EDITION == "CLOUD":
             if not args.invitation_code:
                 raise ValueError("invitation_code is required")
 

api/controllers/console/workspace/plugin.py

@@ -442,10 +442,12 @@ register_enum_models(
 )
 
 
-def _missing_auto_upgrade_settings(tenant_id: str) -> AutoUpgradeSettingsResponse:
-    """Represent a missing persisted strategy as effectively disabled."""
+def _default_auto_upgrade_settings(
+    tenant_id: str,
+    category: TenantPluginAutoUpgradeCategory,
+) -> AutoUpgradeSettingsResponse:
     return {
-        "strategy_setting": TenantPluginAutoUpgradeStrategySetting.DISABLED,
+        "strategy_setting": PluginAutoUpgradeService.default_strategy_setting_for_category(category),
         "upgrade_time_of_day": PluginAutoUpgradeService.default_upgrade_time_of_day(tenant_id),
         "upgrade_mode": TenantPluginAutoUpgradeMode.EXCLUDE,
         "exclude_plugins": [],
@@ -1133,7 +1135,9 @@ class PluginFetchAutoUpgradeApi(Resource):
         args = ParserAutoUpgradeFetch.model_validate(request.args.to_dict(flat=True))
         auto_upgrade = PluginAutoUpgradeService.get_strategy(tenant_id, args.category, session=db.session())
         auto_upgrade_dict = (
-            _auto_upgrade_settings_to_dict(auto_upgrade) if auto_upgrade else _missing_auto_upgrade_settings(tenant_id)
+            _auto_upgrade_settings_to_dict(auto_upgrade)
+            if auto_upgrade
+            else _default_auto_upgrade_settings(tenant_id, args.category)
         )
 
         return jsonable_encoder(

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/console/workspace/workspace.py

@@ -37,7 +37,6 @@ from controllers.console.wraps import (
     with_current_user,
 )
 from enums.cloud_plan import CloudPlan
-from enums.deployment_edition import DeploymentEdition
 from extensions.ext_database import db
 from fields.base import ResponseModel
 from libs.helper import dump_response, to_timestamp
@@ -234,7 +233,7 @@ class TenantListApi(Resource):
         tenants = [tenant for tenant, _ in tenant_rows]
         tenant_dicts = []
         is_enterprise_only = dify_config.ENTERPRISE_ENABLED and not dify_config.BILLING_ENABLED
-        is_saas = dify_config.DEPLOYMENT_EDITION == DeploymentEdition.CLOUD and dify_config.BILLING_ENABLED
+        is_saas = dify_config.EDITION == "CLOUD" and dify_config.BILLING_ENABLED
         tenant_plans: dict[str, SubscriptionPlan] = {}
 
         if is_saas:

api/controllers/console/wraps.py

@@ -20,7 +20,6 @@ from controllers.common.wraps import (
 from controllers.console.auth.error import AuthenticationFailedError, EmailCodeError
 from controllers.console.workspace.error import AccountNotInitializedError
 from enums.cloud_plan import CloudPlan
-from enums.deployment_edition import DeploymentEdition
 from extensions.ext_database import db
 from extensions.ext_redis import redis_client
 from libs.encryption import FieldEncryption
@@ -130,7 +129,7 @@ def account_initialization_required[R](view: Callable[..., R]) -> Callable[...,
 def only_edition_cloud[**P, R](view: Callable[P, R]) -> Callable[P, R]:
     @wraps(view)
     def decorated(*args: P.args, **kwargs: P.kwargs):
-        if dify_config.DEPLOYMENT_EDITION != DeploymentEdition.CLOUD:
+        if dify_config.EDITION != "CLOUD":
             abort(404)
 
         return view(*args, **kwargs)
@@ -152,7 +151,7 @@ def only_edition_enterprise[**P, R](view: Callable[P, R]) -> Callable[P, R]:
 def only_edition_self_hosted[**P, R](view: Callable[P, R]) -> Callable[P, R]:
     @wraps(view)
     def decorated(*args: P.args, **kwargs: P.kwargs):
-        if dify_config.DEPLOYMENT_EDITION == DeploymentEdition.CLOUD:
+        if dify_config.EDITION != "SELF_HOSTED":
             abort(404)
 
         return view(*args, **kwargs)
@@ -328,7 +327,7 @@ def setup_required[R](view: Callable[..., R]) -> Callable[..., R]:
         # The overloads keep Resource methods method-aware for pyrefly while
         # preserving support for plain functions used in tests and utilities.
         # check setup
-        if dify_config.DEPLOYMENT_EDITION != DeploymentEdition.CLOUD and not _is_setup_completed():
+        if dify_config.EDITION == "SELF_HOSTED" and not _is_setup_completed():
             if os.environ.get("INIT_PASSWORD"):
                 raise NotInitValidateError()
             raise NotSetupError()

api/controllers/inner_api/__init__.py

@@ -20,6 +20,7 @@ from . import runtime_credentials as _runtime_credentials
 from .agent import tools as _agent_tools
 from .app import dsl as _app_dsl
 from .knowledge import retrieval as _knowledge_retrieval
+from .knowledge_fs import storage as _knowledge_fs_storage
 from .plugin import agent_config as _agent_config
 from .plugin import agent_drive as _agent_drive
 from .plugin import plugin as _plugin
@@ -32,6 +33,7 @@ __all__ = [
     "_agent_drive",
     "_agent_tools",
     "_app_dsl",
+    "_knowledge_fs_storage",
     "_knowledge_retrieval",
     "_mail",
     "_plugin",

api/controllers/inner_api/knowledge_fs/__init__.py

@@ -0,0 +1 @@
+"""Trusted KnowledgeFS inner API endpoints."""

api/controllers/inner_api/knowledge_fs/storage.py

@@ -0,0 +1,303 @@
+"""Trusted KnowledgeFS gateway to Dify's configured object-storage backend."""
+
+import json
+from base64 import b64decode
+from binascii import Error as BinasciiError
+from http import HTTPStatus
+from typing import NoReturn
+
+from flask import Response, request
+from flask_restx import Resource
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, ValidationError
+from pydantic.alias_generators import to_camel
+
+from controllers.common.schema import query_params_from_model, register_response_schema_models
+from controllers.inner_api import inner_api_ns
+from controllers.inner_api.wraps import knowledge_fs_inner_api_only
+from fields.base import ResponseModel
+from libs.exception import BaseHTTPException
+from libs.helper import dump_response
+from services.knowledge_fs.object_storage import (
+    KNOWLEDGE_FS_OBJECT_MAX_BYTES,
+    KnowledgeFSObjectList,
+    KnowledgeFSObjectMetadata,
+    KnowledgeFSObjectStorageChecksumError,
+    KnowledgeFSObjectStorageCorruptError,
+    KnowledgeFSObjectStorageError,
+    KnowledgeFSObjectStorageInvalidInputError,
+    KnowledgeFSObjectStorageService,
+    KnowledgeFSObjectStorageTooLargeError,
+    KnowledgeFSObjectStorageUnavailableError,
+)
+
+_METADATA_HEADER = "X-Knowledge-FS-Metadata"
+_CHECKSUM_HEADER = "X-Knowledge-FS-Checksum-Sha256"
+_CONTENT_TYPE_HEADER = "X-Knowledge-FS-Content-Type"
+_MAX_ENCODED_METADATA_BYTES = 128 * 1024
+_metadata_adapter = TypeAdapter(dict[str, str])
+
+
+class KnowledgeFSObjectStorageHttpError(BaseHTTPException):
+    """Safe HTTP representation of a KnowledgeFS storage boundary error."""
+
+    error_code = "knowledge_fs_object_storage_failed"
+    description = "KnowledgeFS object storage request failed."
+    code = HTTPStatus.INTERNAL_SERVER_ERROR
+
+    def __init__(self, *, error_code: str, description: str, status_code: HTTPStatus) -> None:
+        self.error_code = error_code
+        self.description = description
+        self.code = status_code
+        super().__init__(description)
+
+
+class _CamelCaseResponse(ResponseModel):
+    model_config = ConfigDict(alias_generator=to_camel)
+
+
+class KnowledgeFSObjectQuery(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    key: str = Field(description="Logical KnowledgeFS object key")
+
+
+class KnowledgeFSObjectListQuery(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    prefix: str = Field(default="", description="Logical object-key prefix")
+    cursor: str | None = Field(default=None, description="Exclusive lexical key cursor")
+    limit: int = Field(default=100, ge=1, le=100, description="Maximum objects to return")
+
+
+class KnowledgeFSObjectMetadataResponse(_CamelCaseResponse):
+    checksum_sha256_base64: str
+    content_type: str | None = None
+    key: str
+    metadata: dict[str, str]
+    size_bytes: int
+
+
+class KnowledgeFSObjectListResponse(_CamelCaseResponse):
+    objects: list[KnowledgeFSObjectMetadataResponse]
+    next_cursor: str | None = None
+
+
+class KnowledgeFSObjectHealthResponse(ResponseModel):
+    ok: bool
+
+
+register_response_schema_models(
+    inner_api_ns,
+    KnowledgeFSObjectMetadataResponse,
+    KnowledgeFSObjectListResponse,
+    KnowledgeFSObjectHealthResponse,
+)
+
+
+@inner_api_ns.route("/knowledge-fs/storage/object")
+class KnowledgeFSObjectApi(Resource):
+    """Read, write, or delete one logical KnowledgeFS object."""
+
+    @knowledge_fs_inner_api_only
+    @inner_api_ns.doc(params=query_params_from_model(KnowledgeFSObjectQuery))
+    @inner_api_ns.response(
+        HTTPStatus.OK,
+        "Object stored",
+        inner_api_ns.models[KnowledgeFSObjectMetadataResponse.__name__],
+    )
+    def put(self) -> dict[str, object]:
+        try:
+            query = KnowledgeFSObjectQuery.model_validate(request.args.to_dict(flat=True))
+            metadata = _decode_metadata_header(request.headers.get(_METADATA_HEADER))
+            body = request.stream.read(KNOWLEDGE_FS_OBJECT_MAX_BYTES + 1)
+            if len(body) > KNOWLEDGE_FS_OBJECT_MAX_BYTES:
+                raise KnowledgeFSObjectStorageTooLargeError(f"object exceeds max bytes {KNOWLEDGE_FS_OBJECT_MAX_BYTES}")
+            result = KnowledgeFSObjectStorageService().put_object(
+                body=body,
+                checksum_sha256_base64=request.headers.get(_CHECKSUM_HEADER),
+                content_type=request.headers.get(_CONTENT_TYPE_HEADER),
+                key=query.key,
+                metadata=metadata,
+            )
+        except ValidationError as exc:
+            raise _invalid_request_error() from exc
+        except KnowledgeFSObjectStorageError as exc:
+            _raise_http_error(exc)
+        return _metadata_response(result)
+
+    @knowledge_fs_inner_api_only
+    @inner_api_ns.doc(params=query_params_from_model(KnowledgeFSObjectQuery))
+    @inner_api_ns.produces(["application/octet-stream"])
+    def get(self) -> Response:
+        try:
+            query = KnowledgeFSObjectQuery.model_validate(request.args.to_dict(flat=True))
+            service = KnowledgeFSObjectStorageService()
+            metadata = service.head_object(key=query.key)
+            if metadata is None:
+                raise _not_found_error()
+            body = service.load_stream(key=query.key)
+            if body is None:
+                raise _not_found_error()
+        except ValidationError as exc:
+            raise _invalid_request_error() from exc
+        except KnowledgeFSObjectStorageError as exc:
+            _raise_http_error(exc)
+
+        response = Response(
+            body,
+            content_type=metadata.content_type or "application/octet-stream",
+        )
+        response.content_length = metadata.size_bytes
+        response.headers[_CHECKSUM_HEADER] = metadata.checksum_sha256_base64
+        return response
+
+    @knowledge_fs_inner_api_only
+    @inner_api_ns.doc(params=query_params_from_model(KnowledgeFSObjectQuery))
+    @inner_api_ns.response(HTTPStatus.NO_CONTENT, "Object deleted")
+    def delete(self) -> tuple[str, int]:
+        try:
+            query = KnowledgeFSObjectQuery.model_validate(request.args.to_dict(flat=True))
+            KnowledgeFSObjectStorageService().delete_object(key=query.key)
+        except ValidationError as exc:
+            raise _invalid_request_error() from exc
+        except KnowledgeFSObjectStorageError as exc:
+            _raise_http_error(exc)
+        return "", HTTPStatus.NO_CONTENT
+
+
+@inner_api_ns.route("/knowledge-fs/storage/object/metadata")
+class KnowledgeFSObjectMetadataApi(Resource):
+    """Read portable metadata for one logical KnowledgeFS object."""
+
+    @knowledge_fs_inner_api_only
+    @inner_api_ns.doc(params=query_params_from_model(KnowledgeFSObjectQuery))
+    @inner_api_ns.response(
+        HTTPStatus.OK,
+        "Object metadata",
+        inner_api_ns.models[KnowledgeFSObjectMetadataResponse.__name__],
+    )
+    def get(self) -> dict[str, object]:
+        try:
+            query = KnowledgeFSObjectQuery.model_validate(request.args.to_dict(flat=True))
+            result = KnowledgeFSObjectStorageService().head_object(key=query.key)
+            if result is None:
+                raise _not_found_error()
+        except ValidationError as exc:
+            raise _invalid_request_error() from exc
+        except KnowledgeFSObjectStorageError as exc:
+            _raise_http_error(exc)
+        return _metadata_response(result)
+
+
+@inner_api_ns.route("/knowledge-fs/storage/objects")
+class KnowledgeFSObjectListApi(Resource):
+    """List logical KnowledgeFS objects with bounded keyset pagination."""
+
+    @knowledge_fs_inner_api_only
+    @inner_api_ns.doc(params=query_params_from_model(KnowledgeFSObjectListQuery))
+    @inner_api_ns.response(
+        HTTPStatus.OK,
+        "Object page",
+        inner_api_ns.models[KnowledgeFSObjectListResponse.__name__],
+    )
+    def get(self) -> dict[str, object]:
+        try:
+            query = KnowledgeFSObjectListQuery.model_validate(request.args.to_dict(flat=True))
+            result = KnowledgeFSObjectStorageService().list_objects(
+                cursor=query.cursor,
+                limit=query.limit,
+                prefix=query.prefix,
+            )
+        except ValidationError as exc:
+            raise _invalid_request_error() from exc
+        except KnowledgeFSObjectStorageError as exc:
+            _raise_http_error(exc)
+        return _list_response(result)
+
+
+@inner_api_ns.route("/knowledge-fs/storage/health")
+class KnowledgeFSObjectHealthApi(Resource):
+    """Report whether Dify storage satisfies KnowledgeFS portable requirements."""
+
+    @knowledge_fs_inner_api_only
+    @inner_api_ns.response(
+        HTTPStatus.OK,
+        "Storage available",
+        inner_api_ns.models[KnowledgeFSObjectHealthResponse.__name__],
+    )
+    @inner_api_ns.response(HTTPStatus.SERVICE_UNAVAILABLE, "Storage unavailable")
+    def get(self) -> dict[str, bool] | tuple[dict[str, bool], int]:
+        if KnowledgeFSObjectStorageService().health():
+            return {"ok": True}
+        return {"ok": False}, HTTPStatus.SERVICE_UNAVAILABLE
+
+
+def _decode_metadata_header(value: str | None) -> dict[str, str]:
+    if value is None:
+        return {}
+    if len(value.encode()) > _MAX_ENCODED_METADATA_BYTES:
+        raise KnowledgeFSObjectStorageInvalidInputError("object metadata header is too large")
+    try:
+        padding = "=" * (-len(value) % 4)
+        decoded = b64decode(value + padding, altchars=b"-_", validate=True)
+        return _metadata_adapter.validate_json(decoded)
+    except (BinasciiError, UnicodeEncodeError, ValidationError, json.JSONDecodeError) as exc:
+        raise KnowledgeFSObjectStorageInvalidInputError("object metadata header is invalid") from exc
+
+
+def _metadata_response(metadata: KnowledgeFSObjectMetadata) -> dict[str, object]:
+    return dump_response(KnowledgeFSObjectMetadataResponse, metadata)
+
+
+def _list_response(result: KnowledgeFSObjectList) -> dict[str, object]:
+    return dump_response(KnowledgeFSObjectListResponse, result)
+
+
+def _raise_http_error(error: KnowledgeFSObjectStorageError) -> NoReturn:
+    if isinstance(error, KnowledgeFSObjectStorageTooLargeError):
+        raise KnowledgeFSObjectStorageHttpError(
+            error_code="knowledge_fs_object_too_large",
+            description="KnowledgeFS object exceeds the configured size limit.",
+            status_code=HTTPStatus.REQUEST_ENTITY_TOO_LARGE,
+        ) from error
+    if isinstance(error, KnowledgeFSObjectStorageChecksumError):
+        raise KnowledgeFSObjectStorageHttpError(
+            error_code="knowledge_fs_object_checksum_mismatch",
+            description="KnowledgeFS object checksum does not match the request body.",
+            status_code=HTTPStatus.UNPROCESSABLE_ENTITY,
+        ) from error
+    if isinstance(error, KnowledgeFSObjectStorageInvalidInputError):
+        raise _invalid_request_error() from error
+    if isinstance(error, KnowledgeFSObjectStorageCorruptError):
+        raise KnowledgeFSObjectStorageHttpError(
+            error_code="knowledge_fs_object_corrupt",
+            description="KnowledgeFS object metadata is inconsistent.",
+            status_code=HTTPStatus.BAD_GATEWAY,
+        ) from error
+    if isinstance(error, KnowledgeFSObjectStorageUnavailableError):
+        raise KnowledgeFSObjectStorageHttpError(
+            error_code="knowledge_fs_object_storage_unavailable",
+            description="Dify object storage is unavailable for KnowledgeFS.",
+            status_code=HTTPStatus.SERVICE_UNAVAILABLE,
+        ) from error
+    raise KnowledgeFSObjectStorageHttpError(
+        error_code="knowledge_fs_object_storage_failed",
+        description="KnowledgeFS object storage request failed.",
+        status_code=HTTPStatus.INTERNAL_SERVER_ERROR,
+    ) from error
+
+
+def _invalid_request_error() -> KnowledgeFSObjectStorageHttpError:
+    return KnowledgeFSObjectStorageHttpError(
+        error_code="knowledge_fs_object_storage_invalid_request",
+        description="KnowledgeFS object storage request is invalid.",
+        status_code=HTTPStatus.BAD_REQUEST,
+    )
+
+
+def _not_found_error() -> KnowledgeFSObjectStorageHttpError:
+    return KnowledgeFSObjectStorageHttpError(
+        error_code="knowledge_fs_object_not_found",
+        description="KnowledgeFS object was not found.",
+        status_code=HTTPStatus.NOT_FOUND,
+    )

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/inner_api/plugin/wraps.py

@@ -1,5 +1,6 @@
 from collections.abc import Callable
 from functools import wraps
+from uuid import UUID
 
 from flask import current_app, request
 from flask_login import user_logged_in
@@ -55,14 +56,15 @@ def get_user(tenant_id: str, user_id: str | None) -> EndUser:
                 # session_id, id is auto-generated) and a fresh EndUser
                 # was created per call, breaking multi-turn chat
                 # continuation (see #36736).
-                user_model = session.scalar(
-                    select(EndUser)
-                    .where(
-                        EndUser.id == user_id,
-                        EndUser.tenant_id == tenant_id,
+                if _is_uuid(user_id):
+                    user_model = session.scalar(
+                        select(EndUser)
+                        .where(
+                            EndUser.id == user_id,
+                            EndUser.tenant_id == tenant_id,
+                        )
+                        .limit(1)
                     )
-                    .limit(1)
-                )
                 if user_model is None:
                     user_model = session.scalar(
                         select(EndUser)
@@ -90,6 +92,14 @@ def get_user(tenant_id: str, user_id: str | None) -> EndUser:
     return user_model
 
 
+def _is_uuid(value: str) -> bool:
+    try:
+        UUID(value)
+    except ValueError:
+        return False
+    return True
+
+
 def get_user_tenant[**P, R](view_func: Callable[P, R]) -> Callable[P, R]:
     @wraps(view_func)
     def decorated_view(*args: P.args, **kwargs: P.kwargs) -> R:

api/controllers/inner_api/wraps.py

@@ -107,3 +107,9 @@ def agent_inner_api_only[**P, R](view: Callable[P, R]) -> Callable[P, R]:
     """
 
     return plugin_inner_api_only(view)
+
+
+def knowledge_fs_inner_api_only[**P, R](view: Callable[P, R]) -> Callable[P, R]:
+    """Authenticate the trusted KnowledgeFS process on the shared inner bridge."""
+
+    return plugin_inner_api_only(view)

api/controllers/openapi/auth/data.py

@@ -8,7 +8,6 @@ from werkzeug.exceptions import InternalServerError
 
 from configs import dify_config
 from core.rbac import RBACPermission, RBACResourceScope
-from enums.deployment_edition import DeploymentEdition
 from libs.oauth_bearer import Scope, TokenType
 from models.account import Account, Tenant, TenantAccountRole
 from models.model import App, EndUser
@@ -27,7 +26,7 @@ class CallerKind(StrEnum):
 
 
 def current_edition() -> Edition:
-    if dify_config.DEPLOYMENT_EDITION == DeploymentEdition.CLOUD:
+    if dify_config.EDITION == "CLOUD":
         return Edition.SAAS
     if dify_config.ENTERPRISE_ENABLED:
         return Edition.EE

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/controllers/web/wraps.py

@@ -11,7 +11,6 @@ from werkzeug.exceptions import BadRequest, NotFound, Unauthorized
 
 from constants import HEADER_NAME_APP_CODE
 from controllers.web.error import WebAppAuthAccessDeniedError, WebAppAuthRequiredError
-from core.logging.context import set_identity_context
 from extensions.ext_database import db
 from libs.passport import PassportService
 from libs.token import extract_webapp_passport
@@ -29,11 +28,6 @@ def validate_jwt_token[**P, R](
         @wraps(view)
         def decorated(*args: P.args, **kwargs: P.kwargs) -> R:
             app_model, end_user = decode_jwt_token()
-            set_identity_context(
-                tenant_id=end_user.tenant_id,
-                user_id=end_user.id,
-                user_type=end_user.type or "end_user",
-            )
             return view(app_model, end_user, *args, **kwargs)
 
         return decorated

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/agent/publish_visibility.py

@@ -1,93 +0,0 @@
-"""Publication visibility rules for calling roster Agents from Workflows.
-
-``Agent.active_config_is_published`` describes whether the editable shared
-draft still matches the active snapshot. It is false both before the first
-publish and after a published Agent receives new draft edits, so it must not be
-used as a runtime availability flag. App-backed Agents are callable from a
-Workflow only when the active snapshot has a revision created by a
-publish-visible operation. Direct roster Agents are publish-visible by
-construction and only need an active snapshot.
-"""
-
-from sqlalchemy import and_, or_, select
-from sqlalchemy.orm import Session
-from sqlalchemy.sql.elements import ColumnElement
-
-from models.agent import Agent, AgentConfigRevision, AgentConfigRevisionOperation, AgentScope, AgentSource
-
-PUBLISH_VISIBLE_APP_BACKED_REVISION_OPERATIONS = frozenset(
-    {
-        AgentConfigRevisionOperation.PUBLISH_DRAFT,
-        AgentConfigRevisionOperation.SAVE_CURRENT_VERSION,
-        AgentConfigRevisionOperation.SAVE_NEW_VERSION,
-        AgentConfigRevisionOperation.SAVE_NEW_AGENT,
-        AgentConfigRevisionOperation.SAVE_TO_ROSTER,
-        AgentConfigRevisionOperation.RESTORE_VERSION,
-    }
-)
-
-
-def workflow_callable_active_snapshot_filter() -> ColumnElement[bool]:
-    """Return the SQL predicate for an Agent with a Workflow-callable active snapshot.
-
-    The caller remains responsible for tenant, roster scope, lifecycle status,
-    and model configuration filters. The correlated revision lookup makes the
-    predicate safe to compose into roster pagination queries.
-    """
-
-    app_backed_agent = or_(
-        Agent.source == AgentSource.AGENT_APP,
-        and_(
-            Agent.source == AgentSource.IMPORTED,
-            Agent.scope == AgentScope.ROSTER,
-            Agent.app_id.is_not(None),
-        ),
-    )
-    publish_visible_revision_exists = (
-        select(AgentConfigRevision.id)
-        .where(
-            AgentConfigRevision.tenant_id == Agent.tenant_id,
-            AgentConfigRevision.agent_id == Agent.id,
-            AgentConfigRevision.current_snapshot_id == Agent.active_config_snapshot_id,
-            AgentConfigRevision.operation.in_(PUBLISH_VISIBLE_APP_BACKED_REVISION_OPERATIONS),
-        )
-        .correlate(Agent)
-        .exists()
-    )
-    return and_(
-        Agent.active_config_snapshot_id.is_not(None),
-        or_(
-            ~app_backed_agent,
-            publish_visible_revision_exists,
-        ),
-    )
-
-
-def agent_has_workflow_callable_active_snapshot(*, session: Session, agent: Agent) -> bool:
-    """Return whether ``agent`` has an active snapshot visible to Workflow.
-
-    This object-level form is useful after ownership and lifecycle checks have
-    already loaded an Agent. It intentionally ignores dirty draft state so a
-    previously published snapshot keeps serving while later edits remain
-    unpublished.
-    """
-
-    if not agent.active_config_snapshot_id:
-        return False
-    is_app_backed = agent.source == AgentSource.AGENT_APP or (
-        agent.source == AgentSource.IMPORTED and agent.scope == AgentScope.ROSTER and agent.app_id is not None
-    )
-    if not is_app_backed:
-        return True
-    return bool(
-        session.scalar(
-            select(AgentConfigRevision.id)
-            .where(
-                AgentConfigRevision.tenant_id == agent.tenant_id,
-                AgentConfigRevision.agent_id == agent.id,
-                AgentConfigRevision.current_snapshot_id == agent.active_config_snapshot_id,
-                AgentConfigRevision.operation.in_(PUBLISH_VISIBLE_APP_BACKED_REVISION_OPERATIONS),
-            )
-            .limit(1)
-        )
-    )

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

@@ -16,7 +16,6 @@ from core.app.apps.workflow_app_runner import WorkflowBasedAppRunner
 from core.app.entities.app_invoke_entities import (
     AdvancedChatAppGenerateEntity,
     AppGenerateEntity,
-    DifyRunContext,
     InvokeFrom,
 )
 from core.app.entities.queue_entities import (
@@ -32,7 +31,7 @@ from core.moderation.base import ModerationError
 from core.moderation.input_moderation import InputModeration
 from core.repositories.factory import WorkflowExecutionRepository, WorkflowNodeExecutionRepository
 from core.workflow.node_factory import get_default_root_node_id
-from core.workflow.nodes.agent_v2.workspace_retirement_layer import build_workflow_agent_workspace_retirement_layer
+from core.workflow.nodes.agent_v2.session_cleanup_layer import build_workflow_agent_session_cleanup_layer
 from core.workflow.system_variables import (
     build_bootstrap_variables,
     build_system_variables,
@@ -268,18 +267,7 @@ class AdvancedChatAppRunner(WorkflowBasedAppRunner):
         )
 
         workflow_entry.graph_engine.layer(persistence_layer)
-        workflow_entry.graph_engine.layer(
-            build_workflow_agent_workspace_retirement_layer(
-                dify_run_context=DifyRunContext(
-                    tenant_id=self._workflow.tenant_id,
-                    app_id=self._workflow.app_id,
-                    user_id=self.application_generate_entity.user_id,
-                    user_from=user_from,
-                    invoke_from=invoke_from,
-                    trace_session_id=self.application_generate_entity.extras.get("trace_session_id"),
-                )
-            )
-        )
+        workflow_entry.graph_engine.layer(build_workflow_agent_session_cleanup_layer())
         conversation_variable_layer = ConversationVariablePersistenceLayer(
             ConversationVariableUpdater(session_factory.get_session_maker())
         )

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

@@ -33,13 +33,15 @@ from core.app.apps.agent_app.app_runner import AgentAppRunner
 from core.app.apps.agent_app.errors import AgentAppGeneratorError, AgentAppNotPublishedError
 from core.app.apps.agent_app.generate_response_converter import AgentAppGenerateResponseConverter
 from core.app.apps.agent_app.runtime_request_builder import AgentAppRuntimeRequestBuilder
-from core.app.apps.agent_app.session_store import AgentAppWorkspaceStore
+from core.app.apps.agent_app.session_store import AgentAppRuntimeSessionStore
 from core.app.apps.base_app_queue_manager import AppQueueManager, PublishFrom
 from core.app.apps.exc import GenerateTaskStoppedError
 from core.app.apps.message_based_app_generator import MessageBasedAppGenerator
 from core.app.apps.message_based_app_queue_manager import MessageBasedAppQueueManager
 from core.app.entities.app_invoke_entities import (
+    AGENT_RUNTIME_EXIT_INTENT_ARG,
     AgentAppGenerateEntity,
+    AgentRuntimeExitIntent,
     DifyRunContext,
     InvokeFrom,
     UserFrom,
@@ -49,24 +51,19 @@ from core.db.session_factory import session_factory
 from core.ops.ops_trace_manager import TraceQueueManager
 from core.workflow.file_reference import build_file_reference, is_canonical_file_reference
 from extensions.ext_database import db
-from models import Account, App, AppModelConfig, Conversation, EndUser, Message, MessageAnnotation
+from models import Account, App, AppModelConfig, EndUser, Message, MessageAnnotation
 from models.agent import (
     APP_BACKED_AGENT_SOURCES,
     Agent,
     AgentConfigDraft,
     AgentConfigDraftType,
     AgentConfigSnapshot,
-    AgentConfigVersionKind,
     AgentScope,
     AgentSource,
     AgentStatus,
-    AgentWorkingResourceStatus,
-    AgentWorkspaceBinding,
-    AgentWorkspaceOwnerType,
 )
 from models.agent_config_entities import AgentSoulConfig
 from models.model import load_annotation_reply_config
-from services.agent.workspace_service import AgentWorkspaceService, WorkspaceOwnerScope
 from services.conversation_service import ConversationService
 
 logger = logging.getLogger(__name__)
@@ -153,28 +150,26 @@ class AgentAppGenerator(MessageBasedAppGenerator):
         inputs = args["inputs"]
         prompt_file_mappings = args.get("files") or []
 
-        conversation = None
-        conversation_id = args.get("conversation_id")
-        if conversation_id:
-            conversation = ConversationService.get_conversation(
-                app_model=app_model, conversation_id=conversation_id, user=user, session=session
-            )
-
-        # New conversations use the current Agent generation. Existing
-        # conversations use the immutable generation named by their Binding.
+        # Resolve the bound roster Agent + its current Agent Soul snapshot.
         agent, agent_config_id, agent_config_version_kind, agent_soul = self._resolve_agent(
             app_model,
             invoke_from=invoke_from,
             draft_type=args.get("draft_type"),
             user=user,
             session=session,
-            conversation=conversation,
         )
-        session_scope_config_version_id = self._session_scope_config_version_id(
+        runtime_session_snapshot_id = self._runtime_session_snapshot_id(
             invoke_from=invoke_from,
-            config_version_id=agent_config_id,
+            snapshot_id=agent_config_id,
         )
 
+        conversation = None
+        conversation_id = args.get("conversation_id")
+        if conversation_id:
+            conversation = ConversationService.get_conversation(
+                app_model=app_model, conversation_id=conversation_id, user=user, session=session
+            )
+
         # Build the EasyUI-shaped config from the Agent Soul so the chat pipeline
         # can persist usage; the answer itself comes from the agent backend.
         app_model_config = (
@@ -191,6 +186,8 @@ class AgentAppGenerator(MessageBasedAppGenerator):
         model_conf = ModelConfigConverter.convert(app_config)
 
         trace_manager = TraceQueueManager(app_model.id, user.id if isinstance(user, Account) else user.session_id)
+        agent_runtime_exit_intent = self._resolve_agent_runtime_exit_intent(args)
+
         application_generate_entity = AgentAppGenerateEntity(
             task_id=str(uuid.uuid4()),
             app_config=app_config,
@@ -218,7 +215,8 @@ class AgentAppGenerator(MessageBasedAppGenerator):
             agent_id=agent.id,
             agent_config_snapshot_id=agent_config_id,
             agent_config_version_kind=agent_config_version_kind,
-            agent_session_scope_config_version_id=session_scope_config_version_id,
+            agent_runtime_session_snapshot_id=runtime_session_snapshot_id,
+            agent_runtime_exit_intent=agent_runtime_exit_intent,
         )
 
         conversation, message = self._init_generate_records(
@@ -267,7 +265,6 @@ class AgentAppGenerator(MessageBasedAppGenerator):
         app_model: App,
         user: Account | EndUser,
         conversation_id: str,
-        form_id: str,
         invoke_from: InvokeFrom,
         session: Session,
     ) -> None:
@@ -282,21 +279,14 @@ class AgentAppGenerator(MessageBasedAppGenerator):
         conversation = ConversationService.get_conversation(
             app_model=app_model, conversation_id=conversation_id, user=user, session=session
         )
-        draft_type, draft_id = self._resolve_resume_draft(
-            app_model=app_model,
-            conversation=conversation,
-            user=user,
-            form_id=form_id,
-            session=session,
-        )
         agent, agent_config_id, agent_config_version_kind, agent_soul = self._resolve_agent(
             app_model,
             invoke_from=invoke_from,
-            draft_type=draft_type,
-            draft_id=draft_id,
+            draft_type=self._resume_draft_type(
+                app_model=app_model, conversation=conversation, user=user, session=session
+            ),
             user=user,
             session=session,
-            conversation=conversation,
         )
 
         app_model_config = (
@@ -394,37 +384,30 @@ class AgentAppGenerator(MessageBasedAppGenerator):
         )
 
     @staticmethod
-    def _resolve_resume_draft(
-        *,
-        app_model: App,
-        conversation: Any,
-        user: Account | EndUser,
-        form_id: str,
-        session: Session,
-    ) -> tuple[str | None, str | None]:
+    def _resume_draft_type(
+        *, app_model: App, conversation: Any, user: Account | EndUser, session: Session
+    ) -> str | None:
         if conversation.invoke_from != InvokeFrom.DEBUGGER:
-            return None, None
-        if not isinstance(user, Account):
-            return AgentConfigDraftType.DRAFT.value, None
-
-        build_draft = session.scalar(
-            select(AgentConfigDraft)
-            .join(
-                AgentWorkspaceBinding,
-                AgentWorkspaceBinding.id == AgentConfigDraft.agent_workspace_binding_id,
-            )
-            .where(
-                AgentConfigDraft.tenant_id == app_model.tenant_id,
-                AgentConfigDraft.draft_type == AgentConfigDraftType.DEBUG_BUILD,
-                AgentConfigDraft.account_id == user.id,
-                AgentWorkspaceBinding.tenant_id == app_model.tenant_id,
-                AgentWorkspaceBinding.status == AgentWorkingResourceStatus.ACTIVE,
-                AgentWorkspaceBinding.pending_form_id == form_id,
-            )
+            return None
+        active_session = AgentAppRuntimeSessionStore().load_active_session_for_conversation(
+            tenant_id=app_model.tenant_id,
+            app_id=app_model.id,
+            conversation_id=conversation.id,
         )
-        if build_draft is not None:
-            return AgentConfigDraftType.DEBUG_BUILD.value, build_draft.id
-        return AgentConfigDraftType.DRAFT.value, None
+        snapshot_id = active_session.scope.agent_config_snapshot_id if active_session is not None else None
+        if snapshot_id and isinstance(user, Account):
+            draft = session.scalar(
+                select(AgentConfigDraft).where(
+                    AgentConfigDraft.tenant_id == app_model.tenant_id,
+                    AgentConfigDraft.id == snapshot_id,
+                )
+            )
+            if draft is not None:
+                if draft.draft_type == AgentConfigDraftType.DEBUG_BUILD and draft.account_id == user.id:
+                    return AgentConfigDraftType.DEBUG_BUILD.value
+                if draft.draft_type == AgentConfigDraftType.DRAFT and draft.account_id is None:
+                    return AgentConfigDraftType.DRAFT.value
+        return AgentConfigDraftType.DRAFT.value
 
     def _generate_worker(
         self,
@@ -499,7 +482,7 @@ class AgentAppGenerator(MessageBasedAppGenerator):
                     invoke_from=application_generate_entity.invoke_from,
                 )
                 with session_factory.create_session() as session:
-                    agent, config_version, agent_soul = self._resolve_agent_by_id(
+                    _, _, agent_soul = self._resolve_agent_by_id(
                         tenant_id=app_config.tenant_id,
                         agent_id=application_generate_entity.agent_id,
                         snapshot_id=application_generate_entity.agent_config_snapshot_id,
@@ -513,18 +496,13 @@ class AgentAppGenerator(MessageBasedAppGenerator):
                     agent_config_snapshot_id=application_generate_entity.agent_config_snapshot_id,
                     agent_config_version_kind=application_generate_entity.agent_config_version_kind,
                     agent_soul=agent_soul,
-                    home_snapshot_id=config_version.home_snapshot_id,
                     conversation_id=conversation.id,
                     query=query,
                     message_id=message.id,
                     model_name=application_generate_entity.model_conf.model,
                     queue_manager=queue_manager,
-                    session_scope_snapshot_id=application_generate_entity.agent_session_scope_config_version_id,
-                    build_draft_id=(
-                        application_generate_entity.agent_config_snapshot_id
-                        if application_generate_entity.agent_config_version_kind == AgentConfigVersionKind.BUILD_DRAFT
-                        else None
-                    ),
+                    session_scope_snapshot_id=application_generate_entity.agent_runtime_session_snapshot_id,
+                    agent_runtime_exit_intent=application_generate_entity.agent_runtime_exit_intent,
                 )
             except GenerateTaskStoppedError:
                 pass
@@ -541,6 +519,18 @@ class AgentAppGenerator(MessageBasedAppGenerator):
             raise AgentAppGeneratorError("query is required")
         return query.replace("\x00", "")
 
+    @staticmethod
+    def _resolve_agent_runtime_exit_intent(args: Mapping[str, Any]) -> AgentRuntimeExitIntent:
+        """Resolve API-internal runtime exit policy from controller-owned args.
+
+        Only the private controller-injected "delete" value changes behavior.
+        Normal chat and resume flows default/fallback to "suspend" so public
+        payloads and invalid internal values preserve existing semantics.
+        """
+        if args.get(AGENT_RUNTIME_EXIT_INTENT_ARG) == "delete":
+            return "delete"
+        return "suspend"
+
     @staticmethod
     def _build_runner(dify_context: DifyRunContext) -> AgentAppRunner:
         credentials_provider, _ = build_dify_model_access(dify_context)
@@ -556,7 +546,7 @@ class AgentAppGenerator(MessageBasedAppGenerator):
                 stream_run_timeout_seconds=dify_config.AGENT_BACKEND_RUN_TIMEOUT_SECONDS,
             ),
             event_adapter=AgentBackendRunEventAdapter(),
-            session_store=AgentAppWorkspaceStore(),
+            session_store=AgentAppRuntimeSessionStore(),
             text_delta_debounce_seconds=dify_config.AGENT_APP_TEXT_DELTA_DEBOUNCE_SECONDS,
         )
 
@@ -620,10 +610,8 @@ class AgentAppGenerator(MessageBasedAppGenerator):
         *,
         invoke_from: InvokeFrom,
         draft_type: Any,
-        draft_id: str | None = None,
         user: Account | EndUser,
         session: Session,
-        conversation: Conversation | None = None,
     ) -> tuple[Agent, str, Literal["snapshot", "draft", "build_draft"], AgentSoulConfig]:
         agent = session.scalar(
             select(Agent)
@@ -655,7 +643,6 @@ class AgentAppGenerator(MessageBasedAppGenerator):
                 tenant_id=app_model.tenant_id,
                 agent=agent,
                 draft_type=draft_type,
-                draft_id=draft_id,
                 account_id=user.id if isinstance(user, Account) else None,
                 session=session,
             )
@@ -668,111 +655,70 @@ class AgentAppGenerator(MessageBasedAppGenerator):
         # Public runtime must keep serving the active snapshot even when unpublished draft edits exist.
         if not agent.active_config_snapshot_id:
             raise AgentAppNotPublishedError("Agent has not been published")
-        conversation_binding = self._resolve_conversation_binding(
-            session=session,
-            tenant_id=app_model.tenant_id,
-            app_id=app_model.id,
-            agent_id=agent.id,
-            conversation=conversation,
-        )
-        snapshot_id = (
-            conversation_binding.agent_config_version_id
-            if conversation_binding is not None
-            else agent.active_config_snapshot_id
-        )
         _, snapshot, agent_soul = self._resolve_agent_by_id(
             tenant_id=app_model.tenant_id,
             agent_id=agent.id,
-            snapshot_id=snapshot_id,
+            snapshot_id=agent.active_config_snapshot_id,
             session=session,
         )
-        if conversation_binding is not None:
-            AgentWorkspaceService.validate_binding_generation(
-                conversation_binding,
-                base_home_snapshot_id=snapshot.home_snapshot_id,
-                agent_config_version_id=snapshot.id,
-                agent_config_version_kind=AgentConfigVersionKind.SNAPSHOT,
-            )
         return agent, snapshot.id, "snapshot", agent_soul
 
     @staticmethod
-    def _resolve_conversation_binding(
-        *,
-        session: Session,
-        tenant_id: str,
-        app_id: str,
-        agent_id: str,
-        conversation: Conversation | None,
-    ) -> AgentWorkspaceBinding | None:
-        """Resolve the exact participant generation owned by an existing conversation."""
-
-        if conversation is None or conversation.agent_workspace_binding_id is None:
-            return None
-        binding = AgentWorkspaceService.get_active_binding(
-            session=session,
-            tenant_id=tenant_id,
-            binding_id=conversation.agent_workspace_binding_id,
-            expected_owner_scope=WorkspaceOwnerScope(
-                tenant_id=tenant_id,
-                app_id=app_id,
-                owner_type=AgentWorkspaceOwnerType.CONVERSATION,
-                owner_id=conversation.id,
-            ),
-        )
-        if binding is None or binding.agent_id != agent_id:
-            raise AgentAppGeneratorError("Conversation participant Binding is unavailable")
-        return binding
-
-    @staticmethod
-    def _session_scope_config_version_id(*, invoke_from: InvokeFrom, config_version_id: str) -> str | None:
-        """Return the config version id that scopes Agent App session reuse.
+    def _runtime_session_snapshot_id(*, invoke_from: InvokeFrom, snapshot_id: str) -> str | None:
+        """Return the session scope snapshot id for Agent App runtime state.
 
         Console preview/debug chat uses a stable Agent draft row id; build mode
         uses the current user's build-draft row id. Published/web/API runs use
-        immutable published snapshot ids. This keeps Workspace Binding continuity
+        immutable published snapshot ids. This keeps runtime session continuity
         inside one editable surface without mixing draft/build/published state.
         """
-        del invoke_from
-        return config_version_id
+        return snapshot_id
 
     @staticmethod
     def _resolve_debug_draft(
-        *,
-        tenant_id: str,
-        agent: Agent,
-        draft_type: Any,
-        account_id: str | None,
-        session: Session,
-        draft_id: str | None = None,
+        *, tenant_id: str, agent: Agent, draft_type: Any, account_id: str | None, session: Session
     ) -> AgentConfigDraft:
         effective_draft_type = (
             AgentConfigDraftType.DEBUG_BUILD
             if draft_type == AgentConfigDraftType.DEBUG_BUILD.value
             else AgentConfigDraftType.DRAFT
         )
-        if effective_draft_type == AgentConfigDraftType.DRAFT:
-            from services.agent.composer_service import AgentComposerService
-
-            return AgentComposerService.get_or_create_normal_agent_draft(
-                session=session,
-                tenant_id=tenant_id,
-                agent=agent,
-                created_by=agent.updated_by or agent.created_by,
-            )
-        if not account_id:
-            raise AgentAppGeneratorError("Build draft requires an account user")
         stmt = select(AgentConfigDraft).where(
             AgentConfigDraft.tenant_id == tenant_id,
             AgentConfigDraft.agent_id == agent.id,
-            AgentConfigDraft.draft_type == AgentConfigDraftType.DEBUG_BUILD,
-            AgentConfigDraft.account_id == account_id,
+            AgentConfigDraft.draft_type == effective_draft_type,
         )
-        if draft_id is not None:
-            stmt = stmt.where(AgentConfigDraft.id == draft_id)
+        if effective_draft_type == AgentConfigDraftType.DEBUG_BUILD:
+            if not account_id:
+                raise AgentAppGeneratorError("Build draft requires an account user")
+            stmt = stmt.where(AgentConfigDraft.account_id == account_id)
+        else:
+            stmt = stmt.where(AgentConfigDraft.account_id.is_(None))
         draft = session.scalar(stmt.order_by(AgentConfigDraft.updated_at.desc()).limit(1))
         if draft is not None:
             return draft
-        raise AgentAppGeneratorError("Agent build draft not found")
+        if effective_draft_type == AgentConfigDraftType.DEBUG_BUILD:
+            raise AgentAppGeneratorError("Agent build draft not found")
+        _, snapshot, agent_soul = AgentAppGenerator._resolve_agent_by_id(
+            tenant_id=tenant_id,
+            agent_id=agent.id,
+            snapshot_id=agent.active_config_snapshot_id,
+            session=session,
+        )
+        draft = AgentConfigDraft(
+            tenant_id=tenant_id,
+            agent_id=agent.id,
+            draft_type=AgentConfigDraftType.DRAFT,
+            account_id=None,
+            draft_owner_key="",
+            base_snapshot_id=snapshot.id,
+            config_snapshot=agent_soul,
+            created_by=agent.created_by,
+            updated_by=agent.updated_by,
+        )
+        session.add(draft)
+        session.flush()
+        return draft
 
     @staticmethod
     def _resolve_agent_by_id(

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

@@ -3,7 +3,8 @@
 Unlike the legacy ``AgentChatAppRunner`` (which runs an in-process ReAct loop),
 this runner delegates to the Agent backend, consumes the streamed event flow,
 republishes the assistant answer through the existing EasyUI chat task
-pipeline, and saves the latest Agenton snapshot on the persistent Binding.
+pipeline, and then either saves or retires the conversation-owned runtime
+session depending on the turn's exit policy.
 """
 
 from __future__ import annotations
@@ -30,20 +31,22 @@ from clients.agent_backend import (
     AgentBackendRunFailedInternalEvent,
     AgentBackendRunSucceededInternalEvent,
     AgentBackendStreamInternalEvent,
+    extract_runtime_layer_specs,
 )
+from clients.agent_backend.session_cleanup import AgentBackendSessionCleanupPayload
 from core.app.apps.agent_app.runtime_request_builder import (
     AgentAppRuntimeBuildContext,
     AgentAppRuntimeRequest,
     AgentAppRuntimeRequestBuilder,
 )
 from core.app.apps.agent_app.session_store import (
+    AgentAppRuntimeSessionStore,
     AgentAppSessionScope,
-    AgentAppWorkspaceStore,
     StoredAgentAppSession,
 )
 from core.app.apps.base_app_queue_manager import AppQueueManager, PublishFrom
 from core.app.apps.exc import GenerateTaskStoppedError
-from core.app.entities.app_invoke_entities import DifyRunContext
+from core.app.entities.app_invoke_entities import AgentRuntimeExitIntent, DifyRunContext
 from core.app.entities.queue_entities import (
     QueueAgentMessageEvent,
     QueueAgentThoughtEvent,
@@ -64,10 +67,10 @@ from graphon.model_runtime.errors.invoke import (
     InvokeRateLimitError,
     InvokeServerUnavailableError,
 )
-from models.agent import AgentConfigVersionKind
 from models.agent_config_entities import AgentSoulConfig
 from models.enums import CreatorUserRole
 from models.model import MessageAgentThought
+from tasks.agent_backend_session_cleanup_task import cleanup_conversation_agent_runtime_session
 
 logger = logging.getLogger(__name__)
 
@@ -617,7 +620,7 @@ class AgentAppRunner:
         request_builder: AgentAppRuntimeRequestBuilder,
         agent_backend_client: AgentBackendRunClient,
         event_adapter: AgentBackendRunEventAdapter,
-        session_store: AgentAppWorkspaceStore,
+        session_store: AgentAppRuntimeSessionStore,
         text_delta_debounce_seconds: float,
     ) -> None:
         self._request_builder = request_builder
@@ -634,41 +637,37 @@ class AgentAppRunner:
         agent_config_snapshot_id: str,
         agent_config_version_kind: Literal["snapshot", "draft", "build_draft"] = "snapshot",
         agent_soul: AgentSoulConfig,
-        home_snapshot_id: str,
         conversation_id: str,
         query: str,
         message_id: str,
         model_name: str,
         queue_manager: AppQueueManager,
         session_scope_snapshot_id: str | None | _DefaultSessionScopeSnapshotId = _DEFAULT_SESSION_SCOPE_SNAPSHOT_ID,
-        build_draft_id: str | None = None,
+        agent_runtime_exit_intent: AgentRuntimeExitIntent = "suspend",
     ) -> None:
+        preserve_session = agent_runtime_exit_intent == "suspend"
         scope = self._build_session_scope(
             dify_context=dify_context,
             agent_id=agent_id,
             agent_config_snapshot_id=agent_config_snapshot_id,
-            home_snapshot_id=home_snapshot_id,
             conversation_id=conversation_id,
             session_scope_snapshot_id=session_scope_snapshot_id,
-            agent_config_version_kind=AgentConfigVersionKind(agent_config_version_kind),
-            build_draft_id=build_draft_id,
         )
         # ENG-638: if a prior turn paused on ask_human and the form is now answered,
         # resume by threading the human's reply into this run as deferred_tool_results.
-        stored = self._session_store.load_or_create(scope)
+        stored = self._session_store.load_active_session(scope)
         runtime = self._build_runtime(
             dify_context=dify_context,
             agent_id=agent_id,
             agent_config_snapshot_id=agent_config_snapshot_id,
             agent_config_version_kind=agent_config_version_kind,
             agent_soul=agent_soul,
-            binding_id=stored.binding_id,
-            backend_binding_ref=stored.backend_binding_ref,
             conversation_id=conversation_id,
             query=query,
             idempotency_key=message_id,
             stored=stored,
             message_id=message_id,
+            suspend_on_exit=preserve_session,
         )
 
         create_response = self._agent_backend_client.create_run(runtime.request)
@@ -682,6 +681,9 @@ class AgentAppRunner:
         )
 
         if isinstance(terminal, AgentBackendDeferredToolCallInternalEvent):
+            if not preserve_session:
+                self._mark_session_cleaned(scope=scope, backend_run_id=terminal.run_id)
+                raise AgentBackendError("Agent App finalization cannot pause for human input.")
             # ENG-635: the agent asked a human. End this turn with the question and
             # a conversation-owned HITL form; a form submission resumes the run.
             self._pause_for_ask_human(
@@ -701,8 +703,8 @@ class AgentAppRunner:
         if not isinstance(terminal, AgentBackendRunSucceededInternalEvent):
             if isinstance(terminal, AgentBackendRunFailedInternalEvent):
                 reason = terminal.reason
-                if reason == "binding_lost":
-                    raise AgentBackendError("The retained agent working environment is no longer available.")
+                if reason == "sandbox_expired":
+                    raise AgentBackendError("The agent session sandbox has expired. Please start a new conversation.")
                 raise _agent_backend_failure_to_exception(terminal)
             raise AgentBackendError("Agent backend run did not complete successfully.")
 
@@ -717,18 +719,38 @@ class AgentAppRunner:
                 message_id,
                 exc_info=True,
             )
-        self._publish_terminal_answer(
-            queue_manager=queue_manager,
-            model_name=model_name,
-            answer=answer,
-            query=query,
-            usage=_llm_usage_from_agent_backend(terminal.usage),
-        )
-        self._save_session(
-            scope=scope,
-            binding_id=runtime.binding_id,
-            snapshot=terminal.session_snapshot,
-        )
+        if preserve_session:
+            superseded_sessions = self._load_superseded_sessions(scope=scope)
+            self._publish_terminal_answer(
+                queue_manager=queue_manager,
+                model_name=model_name,
+                answer=answer,
+                query=query,
+                usage=_llm_usage_from_agent_backend(terminal.usage),
+            )
+            session_saved = self._save_session(
+                scope=scope,
+                backend_run_id=terminal.run_id,
+                snapshot=terminal.session_snapshot,
+                runtime_layer_specs=extract_runtime_layer_specs(runtime.request.composition),
+            )
+            if session_saved:
+                self._cleanup_superseded_sessions(superseded_sessions)
+        else:
+            # The backend has already accepted a terminal success with
+            # delete-on-exit semantics. Local publish/persistence errors must
+            # not keep the API-side session row active, and cleanup failures
+            # must not replace the original publish/error outcome.
+            try:
+                self._publish_terminal_answer(
+                    queue_manager=queue_manager,
+                    model_name=model_name,
+                    answer=answer,
+                    query=query,
+                    usage=_llm_usage_from_agent_backend(terminal.usage),
+                )
+            finally:
+                self._mark_session_cleaned(scope=scope, backend_run_id=terminal.run_id)
 
     def _build_session_scope(
         self,
@@ -736,11 +758,8 @@ class AgentAppRunner:
         dify_context: DifyRunContext,
         agent_id: str,
         agent_config_snapshot_id: str,
-        home_snapshot_id: str,
         conversation_id: str,
         session_scope_snapshot_id: str | None | _DefaultSessionScopeSnapshotId,
-        agent_config_version_kind: AgentConfigVersionKind,
-        build_draft_id: str | None = None,
     ) -> AgentAppSessionScope:
         if isinstance(session_scope_snapshot_id, _DefaultSessionScopeSnapshotId):
             effective_session_scope_snapshot_id: str | None = agent_config_snapshot_id
@@ -751,10 +770,7 @@ class AgentAppRunner:
             app_id=dify_context.app_id,
             conversation_id=conversation_id,
             agent_id=agent_id,
-            agent_config_snapshot_id=effective_session_scope_snapshot_id or agent_config_snapshot_id,
-            home_snapshot_id=home_snapshot_id,
-            agent_config_version_kind=agent_config_version_kind,
-            build_draft_id=build_draft_id,
+            agent_config_snapshot_id=effective_session_scope_snapshot_id,
         )
 
     def _build_runtime(
@@ -765,15 +781,14 @@ class AgentAppRunner:
         agent_config_snapshot_id: str,
         agent_config_version_kind: Literal["snapshot", "draft", "build_draft"],
         agent_soul: AgentSoulConfig,
-        binding_id: str,
-        backend_binding_ref: str,
         conversation_id: str,
         query: str,
         idempotency_key: str,
-        stored: StoredAgentAppSession,
+        stored: StoredAgentAppSession | None,
         message_id: str | None,
+        suspend_on_exit: bool,
     ) -> AgentAppRuntimeRequest:
-        session_snapshot = stored.session_snapshot
+        session_snapshot = stored.session_snapshot if stored is not None else None
         deferred_tool_results = (
             self._resolve_pending_ask_human(stored=stored, dify_context=dify_context, message_id=message_id)
             if message_id is not None
@@ -789,10 +804,9 @@ class AgentAppRunner:
                 conversation_id=conversation_id,
                 user_query=query,
                 idempotency_key=idempotency_key,
-                binding_id=binding_id,
-                backend_binding_ref=backend_binding_ref,
                 session_snapshot=session_snapshot,
                 deferred_tool_results=deferred_tool_results,
+                suspend_on_exit=suspend_on_exit,
             )
         )
 
@@ -829,8 +843,9 @@ class AgentAppRunner:
         # second run with the human's answer (ENG-637/638 columns, conversation owner).
         self._save_session(
             scope=scope,
-            binding_id=runtime.binding_id,
+            backend_run_id=terminal.run_id,
             snapshot=terminal.session_snapshot,
+            runtime_layer_specs=extract_runtime_layer_specs(runtime.request.composition),
             pending_form_id=created.form_id,
             pending_tool_call_id=terminal.deferred_tool_call.tool_call_id,
         )
@@ -847,12 +862,12 @@ class AgentAppRunner:
     def _resolve_pending_ask_human(
         self,
         *,
-        stored: StoredAgentAppSession,
+        stored: StoredAgentAppSession | None,
         dify_context: DifyRunContext,
         message_id: str,
     ) -> DeferredToolResultsPayload | None:
         """Build deferred_tool_results when a pending ask_human form is answered."""
-        if stored.pending_form_id is None or stored.pending_tool_call_id is None:
+        if stored is None or stored.pending_form_id is None or stored.pending_tool_call_id is None:
             return None
         outcome = resolve_ask_human_form(
             form_id=stored.pending_form_id,
@@ -1021,16 +1036,18 @@ class AgentAppRunner:
         self,
         *,
         scope: AgentAppSessionScope,
-        binding_id: str,
+        backend_run_id: str,
         snapshot: Any,
+        runtime_layer_specs: Any,
         pending_form_id: str | None = None,
         pending_tool_call_id: str | None = None,
     ) -> bool:
         try:
             self._session_store.save_active_snapshot(
                 scope=scope,
-                binding_id=binding_id,
+                backend_run_id=backend_run_id,
                 snapshot=snapshot,
+                runtime_layer_specs=runtime_layer_specs,
                 pending_form_id=pending_form_id,
                 pending_tool_call_id=pending_tool_call_id,
             )
@@ -1047,6 +1064,87 @@ class AgentAppRunner:
             )
             return False
 
+    def _load_superseded_sessions(self, *, scope: AgentAppSessionScope) -> list[StoredAgentAppSession]:
+        try:
+            stored_sessions = self._session_store.list_active_sessions_for_conversation(
+                tenant_id=scope.tenant_id,
+                app_id=scope.app_id,
+                conversation_id=scope.conversation_id,
+            )
+        except Exception:
+            logger.warning(
+                "Failed to load existing Agent App conversation sessions before snapshot save: "
+                "tenant_id=%s app_id=%s conversation_id=%s agent_id=%s",
+                scope.tenant_id,
+                scope.app_id,
+                scope.conversation_id,
+                scope.agent_id,
+                exc_info=True,
+            )
+            return []
+
+        return [stored for stored in stored_sessions if stored.scope != scope]
+
+    def _cleanup_superseded_sessions(self, stored_sessions: list[StoredAgentAppSession]) -> None:
+        for stored_session in stored_sessions:
+            try:
+                if stored_session.runtime_layer_specs:
+                    payload = AgentBackendSessionCleanupPayload(
+                        session_snapshot=stored_session.session_snapshot,
+                        runtime_layer_specs=stored_session.runtime_layer_specs,
+                        idempotency_key=(
+                            f"{stored_session.scope.tenant_id}:{stored_session.scope.app_id}:"
+                            f"{stored_session.scope.conversation_id}:{stored_session.scope.agent_id}:"
+                            f"{stored_session.scope.agent_config_snapshot_id or 'no-config'}:"
+                            f"superseded-session-cleanup:{stored_session.backend_run_id or 'no-run'}"
+                        ),
+                        metadata={
+                            "tenant_id": stored_session.scope.tenant_id,
+                            "app_id": stored_session.scope.app_id,
+                            "conversation_id": stored_session.scope.conversation_id,
+                            "agent_id": stored_session.scope.agent_id,
+                            "agent_config_snapshot_id": stored_session.scope.agent_config_snapshot_id,
+                            "previous_agent_backend_run_id": stored_session.backend_run_id,
+                        },
+                    )
+                    cleanup_conversation_agent_runtime_session.delay(payload.model_dump(mode="json"))
+            except Exception:
+                logger.warning(
+                    "Failed to enqueue Agent backend cleanup for superseded Agent App session: "
+                    "tenant_id=%s app_id=%s conversation_id=%s agent_id=%s backend_run_id=%s",
+                    stored_session.scope.tenant_id,
+                    stored_session.scope.app_id,
+                    stored_session.scope.conversation_id,
+                    stored_session.scope.agent_id,
+                    stored_session.backend_run_id,
+                    exc_info=True,
+                )
+
+    def _mark_session_cleaned(
+        self,
+        *,
+        scope: AgentAppSessionScope,
+        backend_run_id: str,
+    ) -> None:
+        """Best-effort delete-on-exit cleanup for the API-side session row.
+
+        Once the Agent backend reaches a terminal event, cleanup persistence
+        must not replace the original publish/error outcome for that turn.
+        """
+        try:
+            self._session_store.mark_cleaned(scope=scope, backend_run_id=backend_run_id)
+        except Exception:
+            logger.warning(
+                "Failed to retire Agent App conversation session after delete-on-exit: "
+                "tenant_id=%s app_id=%s conversation_id=%s agent_id=%s backend_run_id=%s",
+                scope.tenant_id,
+                scope.app_id,
+                scope.conversation_id,
+                scope.agent_id,
+                backend_run_id,
+                exc_info=True,
+            )
+
     @staticmethod
     def _terminal_output_to_answer(output: JsonValue) -> str:
         """Normalize the backend's terminal output to assistant text.

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

@@ -70,12 +70,11 @@ class AgentAppRuntimeBuildContext:
     conversation_id: str
     user_query: str
     idempotency_key: str
-    binding_id: str
-    backend_binding_ref: str
     agent_config_version_kind: Literal["snapshot", "draft", "build_draft"] = "snapshot"
     session_snapshot: CompositorSessionSnapshot | None = None
     # ENG-638: set when resuming a chat turn after a submitted ask_human form.
     deferred_tool_results: DeferredToolResultsPayload | None = None
+    suspend_on_exit: bool = True
 
 
 @dataclass(frozen=True, slots=True)
@@ -83,7 +82,6 @@ class AgentAppRuntimeRequest:
     request: CreateRunRequest
     redacted_request: dict[str, Any]
     metadata: dict[str, Any]
-    binding_id: str
 
 
 class AgentAppRuntimeRequestBuilder:
@@ -161,8 +159,8 @@ 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,
                 ),
-                backend_binding_ref=context.backend_binding_ref,
                 # ENG-616: expand slash-menu mention tokens to canonical names so
                 # no frontend-internal {{#…#}} marker ever reaches the model.
                 agent_soul_prompt=expand_prompt_mentions(agent_soul.prompt.system_prompt, soul_prompt_resolver).strip()
@@ -178,17 +176,13 @@ class AgentAppRuntimeRequestBuilder:
                 shell_config=build_shell_layer_config(agent_soul),
                 session_snapshot=context.session_snapshot,
                 deferred_tool_results=context.deferred_tool_results,
+                suspend_on_exit=context.suspend_on_exit,
                 idempotency_key=context.idempotency_key,
                 metadata=metadata,
             )
         )
         redacted = cast(dict[str, Any], redact_for_agent_backend_log(request))
-        return AgentAppRuntimeRequest(
-            request=request,
-            redacted_request=redacted,
-            metadata=metadata,
-            binding_id=context.binding_id,
-        )
+        return AgentAppRuntimeRequest(request=request, redacted_request=redacted, metadata=metadata)
 
     def _build_tool_layers(
         self,

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

@@ -1,176 +1,255 @@
-"""Persist and resolve the exact participant owned by an Agent App caller."""
+"""Conversation-keyed Agent backend session store for the Agent App type.
+
+Shares the unified ``agent_runtime_sessions`` table with the workflow Agent
+Node store, but owns rows with ``owner_type = conversation``: one Agent App
+conversation maps to one Agent session, so multi-turn chat re-enters the same
+``session_snapshot``. Cross-conversation memory (PRD Global / Per app) is a
+phase-2 concern and not modeled here.
+"""
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 from agenton.compositor import CompositorSessionSnapshot
+from dify_agent.protocol import RuntimeLayerSpec
+from pydantic import TypeAdapter
 from sqlalchemy import select
-from sqlalchemy.orm import Session
 
 from core.db.session_factory import session_factory
+from libs.datetime_utils import naive_utc_now
 from models.agent import (
-    AgentConfigDraft,
-    AgentConfigDraftType,
-    AgentConfigVersionKind,
-    AgentWorkspaceBinding,
-    AgentWorkspaceOwnerType,
-)
-from models.model import App, Conversation
-from services.agent.workspace_service import (
-    AgentWorkspaceNotFoundError,
-    AgentWorkspaceService,
-    WorkspaceOwnerScope,
+    AgentRuntimeSession,
+    AgentRuntimeSessionOwnerType,
+    AgentRuntimeSessionStatus,
 )
 
+_RUNTIME_LAYER_SPECS_ADAPTER: TypeAdapter[list[RuntimeLayerSpec]] = TypeAdapter(list[RuntimeLayerSpec])
+
+
+def _serialize_runtime_layer_specs(specs: list[RuntimeLayerSpec]) -> str:
+    return _RUNTIME_LAYER_SPECS_ADAPTER.dump_json(specs).decode()
+
+
+def _deserialize_runtime_layer_specs(value: str | None) -> list[RuntimeLayerSpec]:
+    if not value:
+        return []
+    return _RUNTIME_LAYER_SPECS_ADAPTER.validate_json(value)
+
 
 @dataclass(frozen=True, slots=True)
 class AgentAppSessionScope:
+    """Identity of one Agent App conversation session."""
+
     tenant_id: str
     app_id: str
     conversation_id: str
     agent_id: str
-    agent_config_snapshot_id: str
-    home_snapshot_id: str
-    agent_config_version_kind: AgentConfigVersionKind = AgentConfigVersionKind.SNAPSHOT
-    build_draft_id: str | None = None
-
-    @property
-    def workspace_owner(self) -> WorkspaceOwnerScope:
-        owner_type = (
-            AgentWorkspaceOwnerType.BUILD_DRAFT if self.build_draft_id else AgentWorkspaceOwnerType.CONVERSATION
-        )
-        return WorkspaceOwnerScope(
-            tenant_id=self.tenant_id,
-            app_id=self.app_id,
-            owner_type=owner_type,
-            owner_id=self.build_draft_id or self.conversation_id,
-        )
+    agent_config_snapshot_id: str | None
 
 
 @dataclass(frozen=True, slots=True)
 class StoredAgentAppSession:
+    """Persisted Agent App conversation session with reusable runtime specs."""
+
     scope: AgentAppSessionScope
-    binding_id: str
-    workspace_id: str
-    backend_binding_ref: str
-    session_snapshot: CompositorSessionSnapshot | None
+    session_snapshot: CompositorSessionSnapshot
+    backend_run_id: str | None
+    runtime_layer_specs: list[RuntimeLayerSpec] = field(default_factory=list)
+    # ENG-635: set while the conversation turn is paused on a dify.ask_human
+    # deferred call, awaiting a HITL form submission.
     pending_form_id: str | None = None
     pending_tool_call_id: str | None = None
 
 
-class AgentAppWorkspaceStore:
-    """Resolve Agent App sessions through a caller-owned Binding pointer."""
+class AgentAppRuntimeSessionStore:
+    """Persists Agent backend session snapshots for Agent App conversations."""
 
-    def load_or_create(self, scope: AgentAppSessionScope) -> StoredAgentAppSession:
+    def load_active_snapshot(self, scope: AgentAppSessionScope) -> CompositorSessionSnapshot | None:
+        stored = self.load_active_session(scope)
+        return stored.session_snapshot if stored is not None else None
+
+    def load_active_session(self, scope: AgentAppSessionScope) -> StoredAgentAppSession | None:
         with session_factory.create_session() as session:
-            caller = self._load_caller(session=session, scope=scope)
-            binding_id = caller.agent_workspace_binding_id
-            if binding_id is None:
-                binding = AgentWorkspaceService.create_binding(
-                    session=session,
-                    scope=scope.workspace_owner,
-                    agent_id=scope.agent_id,
-                    base_home_snapshot_id=scope.home_snapshot_id,
-                    agent_config_version_id=scope.agent_config_snapshot_id,
-                    agent_config_version_kind=scope.agent_config_version_kind,
-                )
-                caller.agent_workspace_binding_id = binding.id
-                session.commit()
-            else:
-                binding = self._get_binding(session=session, scope=scope, binding_id=binding_id)
-            return self._stored(scope, binding)
-
-    @staticmethod
-    def _load_caller(*, session: Session, scope: AgentAppSessionScope) -> Conversation | AgentConfigDraft:
-        if scope.build_draft_id is not None:
-            if scope.agent_config_version_kind != AgentConfigVersionKind.BUILD_DRAFT:
-                raise AgentWorkspaceNotFoundError("Build Draft caller requires build_draft generation")
-            draft = session.scalar(
-                select(AgentConfigDraft).where(
-                    AgentConfigDraft.id == scope.build_draft_id,
-                    AgentConfigDraft.tenant_id == scope.tenant_id,
-                    AgentConfigDraft.agent_id == scope.agent_id,
-                    AgentConfigDraft.draft_type == AgentConfigDraftType.DEBUG_BUILD,
-                )
+            row = session.scalar(self._active_stmt(scope))
+            if row is None:
+                return None
+            return StoredAgentAppSession(
+                scope=scope,
+                session_snapshot=CompositorSessionSnapshot.model_validate_json(row.session_snapshot),
+                backend_run_id=row.backend_run_id,
+                runtime_layer_specs=_deserialize_runtime_layer_specs(row.composition_layer_specs),
+                pending_form_id=row.pending_form_id,
+                pending_tool_call_id=row.pending_tool_call_id,
             )
-            if draft is None:
-                raise AgentWorkspaceNotFoundError("Build Draft caller is unavailable")
-            return draft
-        if scope.agent_config_version_kind == AgentConfigVersionKind.BUILD_DRAFT:
-            raise AgentWorkspaceNotFoundError("Build Draft caller ID is required")
-        conversation = session.scalar(
-            select(Conversation)
-            .join(App, App.id == Conversation.app_id)
+
+    def load_active_session_for_conversation(
+        self, *, tenant_id: str, app_id: str, conversation_id: str
+    ) -> StoredAgentAppSession | None:
+        """Load the latest ACTIVE session for one conversation-level sandbox lookup.
+
+        Sandbox inspection only knows the product locator
+        ``tenant_id + app_id + conversation_id``; it does not know which
+        ``agent_id`` or Agent Soul snapshot produced the active shell session.
+        This method therefore resolves the newest ACTIVE conversation-owned row
+        for that conversation and returns both the resumable snapshot and the
+        persisted non-sensitive runtime layer specs needed to build a
+        ``SandboxLocator``.
+        """
+        stmt = (
+            select(AgentRuntimeSession)
             .where(
-                App.tenant_id == scope.tenant_id,
-                Conversation.id == scope.conversation_id,
-                Conversation.app_id == scope.app_id,
-                Conversation.is_deleted.is_(False),
+                AgentRuntimeSession.owner_type == AgentRuntimeSessionOwnerType.CONVERSATION,
+                AgentRuntimeSession.tenant_id == tenant_id,
+                AgentRuntimeSession.app_id == app_id,
+                AgentRuntimeSession.conversation_id == conversation_id,
+                AgentRuntimeSession.status == AgentRuntimeSessionStatus.ACTIVE,
             )
+            .order_by(AgentRuntimeSession.updated_at.desc())
         )
-        if conversation is None:
-            raise AgentWorkspaceNotFoundError("Conversation caller is unavailable")
-        return conversation
+        with session_factory.create_session() as session:
+            row = session.scalar(stmt)
+            if row is None:
+                return None
+            return StoredAgentAppSession(
+                scope=AgentAppSessionScope(
+                    tenant_id=row.tenant_id,
+                    app_id=row.app_id,
+                    conversation_id=row.conversation_id or "",
+                    agent_id=row.agent_id,
+                    agent_config_snapshot_id=row.agent_config_snapshot_id or "",
+                ),
+                session_snapshot=CompositorSessionSnapshot.model_validate_json(row.session_snapshot),
+                backend_run_id=row.backend_run_id,
+                runtime_layer_specs=_deserialize_runtime_layer_specs(row.composition_layer_specs),
+            )
 
-    @staticmethod
-    def _get_binding(
-        *,
-        session: Session,
-        scope: AgentAppSessionScope,
-        binding_id: str,
-    ) -> AgentWorkspaceBinding:
-        binding = AgentWorkspaceService.get_active_binding(
-            session=session,
-            tenant_id=scope.tenant_id,
-            binding_id=binding_id,
-            expected_owner_scope=scope.workspace_owner,
+    def list_active_sessions_for_conversation(
+        self, *, tenant_id: str, app_id: str, conversation_id: str
+    ) -> list[StoredAgentAppSession]:
+        """List all ACTIVE conversation-owned sessions for lifecycle cleanup."""
+        stmt = (
+            select(AgentRuntimeSession)
+            .where(
+                AgentRuntimeSession.owner_type == AgentRuntimeSessionOwnerType.CONVERSATION,
+                AgentRuntimeSession.tenant_id == tenant_id,
+                AgentRuntimeSession.app_id == app_id,
+                AgentRuntimeSession.conversation_id == conversation_id,
+                AgentRuntimeSession.status == AgentRuntimeSessionStatus.ACTIVE,
+            )
+            .order_by(AgentRuntimeSession.updated_at.desc())
         )
-        if binding is None or binding.agent_id != scope.agent_id:
-            raise AgentWorkspaceNotFoundError("Caller participant Binding is unavailable")
-        AgentWorkspaceService.validate_binding_generation(
-            binding,
-            base_home_snapshot_id=scope.home_snapshot_id,
-            agent_config_version_id=scope.agent_config_snapshot_id,
-            agent_config_version_kind=scope.agent_config_version_kind,
-        )
-        return binding
+        with session_factory.create_session() as session:
+            rows = session.scalars(stmt).all()
+            return [
+                StoredAgentAppSession(
+                    scope=AgentAppSessionScope(
+                        tenant_id=row.tenant_id,
+                        app_id=row.app_id,
+                        conversation_id=row.conversation_id or "",
+                        agent_id=row.agent_id,
+                        agent_config_snapshot_id=row.agent_config_snapshot_id,
+                    ),
+                    session_snapshot=CompositorSessionSnapshot.model_validate_json(row.session_snapshot),
+                    backend_run_id=row.backend_run_id,
+                    runtime_layer_specs=_deserialize_runtime_layer_specs(row.composition_layer_specs),
+                    pending_form_id=row.pending_form_id,
+                    pending_tool_call_id=row.pending_tool_call_id,
+                )
+                for row in rows
+            ]
 
     def save_active_snapshot(
         self,
         *,
         scope: AgentAppSessionScope,
-        binding_id: str,
+        backend_run_id: str,
         snapshot: CompositorSessionSnapshot | None,
+        runtime_layer_specs: list[RuntimeLayerSpec],
         pending_form_id: str | None = None,
         pending_tool_call_id: str | None = None,
     ) -> None:
+        """Persist the current conversation snapshot and enforce one ACTIVE row.
+
+        Agent App chat treats one conversation as one resumable runtime shell.
+        Saving the latest snapshot therefore upserts the scoped row back to
+        ACTIVE and retires any other ACTIVE conversation-owned rows for the
+        same ``tenant_id + app_id + conversation_id`` so later lookups see a
+        single active session.
+        """
         if snapshot is None:
             return
-        AgentWorkspaceService.save_binding_session_snapshot(
-            tenant_id=scope.tenant_id,
-            binding_id=binding_id,
-            session_snapshot=snapshot.model_dump_json(),
-            pending_form_id=pending_form_id,
-            pending_tool_call_id=pending_tool_call_id,
-        )
+        snapshot_json = snapshot.model_dump_json()
+        runtime_layer_specs_json = _serialize_runtime_layer_specs(runtime_layer_specs)
+        with session_factory.create_session() as session:
+            row = session.scalar(self._scope_stmt(scope))
+            if row is None:
+                row = AgentRuntimeSession(
+                    tenant_id=scope.tenant_id,
+                    app_id=scope.app_id,
+                    owner_type=AgentRuntimeSessionOwnerType.CONVERSATION,
+                    agent_id=scope.agent_id,
+                    agent_config_snapshot_id=scope.agent_config_snapshot_id,
+                    conversation_id=scope.conversation_id,
+                    backend_run_id=backend_run_id,
+                    session_snapshot=snapshot_json,
+                    composition_layer_specs=runtime_layer_specs_json,
+                    status=AgentRuntimeSessionStatus.ACTIVE,
+                    pending_form_id=pending_form_id,
+                    pending_tool_call_id=pending_tool_call_id,
+                )
+                session.add(row)
+            else:
+                row.backend_run_id = backend_run_id
+                row.session_snapshot = snapshot_json
+                row.composition_layer_specs = runtime_layer_specs_json
+                row.status = AgentRuntimeSessionStatus.ACTIVE
+                row.cleaned_at = None
+                # Set (or clear, when omitted) the ask_human pause correlation.
+                row.pending_form_id = pending_form_id
+                row.pending_tool_call_id = pending_tool_call_id
+            session.flush()
+            other_rows = session.scalars(
+                select(AgentRuntimeSession).where(
+                    AgentRuntimeSession.owner_type == AgentRuntimeSessionOwnerType.CONVERSATION,
+                    AgentRuntimeSession.tenant_id == scope.tenant_id,
+                    AgentRuntimeSession.app_id == scope.app_id,
+                    AgentRuntimeSession.conversation_id == scope.conversation_id,
+                    AgentRuntimeSession.status == AgentRuntimeSessionStatus.ACTIVE,
+                    AgentRuntimeSession.id != row.id,
+                )
+            ).all()
+            for other_row in other_rows:
+                other_row.status = AgentRuntimeSessionStatus.CLEANED
+                other_row.cleaned_at = naive_utc_now()
+            session.commit()
+
+    def mark_cleaned(self, *, scope: AgentAppSessionScope, backend_run_id: str | None = None) -> None:
+        with session_factory.create_session() as session:
+            row = session.scalar(self._active_stmt(scope))
+            if row is None:
+                return
+            if backend_run_id is not None:
+                row.backend_run_id = backend_run_id
+            row.status = AgentRuntimeSessionStatus.CLEANED
+            row.cleaned_at = naive_utc_now()
+            session.commit()
 
     @staticmethod
-    def _stored(scope: AgentAppSessionScope, binding: AgentWorkspaceBinding) -> StoredAgentAppSession:
-        snapshot = (
-            CompositorSessionSnapshot.model_validate_json(binding.session_snapshot)
-            if binding.session_snapshot
-            else None
-        )
-        return StoredAgentAppSession(
-            scope=scope,
-            binding_id=binding.id,
-            workspace_id=binding.workspace_id,
-            backend_binding_ref=binding.backend_binding_ref,
-            session_snapshot=snapshot,
-            pending_form_id=binding.pending_form_id,
-            pending_tool_call_id=binding.pending_tool_call_id,
+    def _scope_stmt(scope: AgentAppSessionScope):
+        stmt = select(AgentRuntimeSession).where(
+            AgentRuntimeSession.owner_type == AgentRuntimeSessionOwnerType.CONVERSATION,
+            AgentRuntimeSession.tenant_id == scope.tenant_id,
+            AgentRuntimeSession.conversation_id == scope.conversation_id,
+            AgentRuntimeSession.agent_id == scope.agent_id,
         )
+        if scope.agent_config_snapshot_id is None:
+            return stmt.where(AgentRuntimeSession.agent_config_snapshot_id.is_(None))
+        return stmt.where(AgentRuntimeSession.agent_config_snapshot_id == scope.agent_config_snapshot_id)
+
+    @classmethod
+    def _active_stmt(cls, scope: AgentAppSessionScope):
+        return cls._scope_stmt(scope).where(AgentRuntimeSession.status == AgentRuntimeSessionStatus.ACTIVE)
 
 
-__all__ = ["AgentAppSessionScope", "AgentAppWorkspaceStore", "StoredAgentAppSession"]
+__all__ = ["AgentAppRuntimeSessionStore", "AgentAppSessionScope", "StoredAgentAppSession"]

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

@@ -10,11 +10,11 @@ from core.app.apps.workflow.command_channels import (
     CombinedCommandChannel,
 )
 from core.app.apps.workflow_app_runner import WorkflowBasedAppRunner
-from core.app.entities.app_invoke_entities import DifyRunContext, InvokeFrom, WorkflowAppGenerateEntity
+from core.app.entities.app_invoke_entities import InvokeFrom, WorkflowAppGenerateEntity
 from core.app.workflow.layers.persistence import PersistenceWorkflowInfo, WorkflowPersistenceLayer
 from core.repositories.factory import WorkflowExecutionRepository, WorkflowNodeExecutionRepository
 from core.workflow.node_factory import get_default_root_node_id
-from core.workflow.nodes.agent_v2.workspace_retirement_layer import build_workflow_agent_workspace_retirement_layer
+from core.workflow.nodes.agent_v2.session_cleanup_layer import build_workflow_agent_session_cleanup_layer
 from core.workflow.snippet_start import get_compatible_start_aliases
 from core.workflow.system_variables import build_bootstrap_variables, build_system_variables
 from core.workflow.variable_pool_initializer import add_node_inputs_to_pool, add_variables_to_pool
@@ -197,18 +197,7 @@ class WorkflowAppRunner(WorkflowBasedAppRunner):
         )
 
         workflow_entry.graph_engine.layer(persistence_layer)
-        workflow_entry.graph_engine.layer(
-            build_workflow_agent_workspace_retirement_layer(
-                dify_run_context=DifyRunContext(
-                    tenant_id=self._workflow.tenant_id,
-                    app_id=self._workflow.app_id,
-                    user_id=self.application_generate_entity.user_id,
-                    user_from=user_from,
-                    invoke_from=invoke_from,
-                    trace_session_id=self.application_generate_entity.extras.get("trace_session_id"),
-                )
-            )
-        )
+        workflow_entry.graph_engine.layer(build_workflow_agent_session_cleanup_layer())
         for layer in self._graph_engine_layers:
             workflow_entry.graph_engine.layer(layer)
 

api/core/app/entities/app_invoke_entities.py

@@ -15,6 +15,8 @@ if TYPE_CHECKING:
 
 
 DIFY_RUN_CONTEXT_KEY = "_dify"
+AGENT_RUNTIME_EXIT_INTENT_ARG = "_agent_runtime_exit_intent"
+type AgentRuntimeExitIntent = Literal["suspend", "delete"]
 
 
 class UserFrom(StrEnum):
@@ -225,8 +227,12 @@ class AgentAppGenerateEntity(ChatAppGenerateEntity):
     backend should read from: immutable snapshot, shared draft, or per-user
     build draft.
 
-    ``agent_session_scope_config_version_id`` identifies the draft or immutable
-    config version whose Workspace Binding should be reused for this session.
+    ``agent_runtime_session_snapshot_id`` carries the runtime session scope
+    used to resume or suspend within the same editable config surface.
+
+    ``agent_runtime_exit_intent`` is API-internal lifecycle policy for the
+    Agent backend session after this turn finishes. Normal chat/resume turns
+    suspend on exit; build-chat finalization deletes the backend runtime.
 
     ``prompt_file_mappings`` preserves the raw request ``files`` array for the
     Agent backend prompt. These references are appended to the backend prompt
@@ -236,7 +242,8 @@ class AgentAppGenerateEntity(ChatAppGenerateEntity):
     agent_id: str
     agent_config_snapshot_id: str
     agent_config_version_kind: Literal["snapshot", "draft", "build_draft"] = "snapshot"
-    agent_session_scope_config_version_id: str | None = None
+    agent_runtime_session_snapshot_id: str | None = None
+    agent_runtime_exit_intent: AgentRuntimeExitIntent = "suspend"
     prompt_file_mappings: Sequence[JsonValue] = Field(default_factory=list)
 
 

api/core/app/workflow/layers/persistence.py

@@ -20,13 +20,11 @@ from core.helper.trace_id_helper import ParentTraceContext
 from core.ops.entities.trace_entity import TraceTaskName
 from core.ops.ops_trace_manager import TraceQueueManager, TraceTask
 from core.repositories.factory import WorkflowExecutionRepository, WorkflowNodeExecutionRepository
-from core.workflow.node_execution_process_data import preserve_workflow_agent_binding_id
 from core.workflow.system_variables import SystemVariableKey
 from core.workflow.variable_prefixes import SYSTEM_VARIABLE_NODE_ID
 from core.workflow.workflow_run_outputs import project_node_outputs_for_workflow_run
 from graphon.entities import WorkflowExecution, WorkflowNodeExecution
 from graphon.enums import (
-    BuiltinNodeTypes,
     WorkflowExecutionStatus,
     WorkflowNodeExecutionMetadataKey,
     WorkflowNodeExecutionStatus,
@@ -243,10 +241,7 @@ class WorkflowPersistenceLayer(GraphEngineLayer):
         )
 
         self._node_execution_cache[event.id] = domain_execution
-        if event.node_type == BuiltinNodeTypes.AGENT and event.node_version == "2":
-            self._workflow_node_execution_repository.save_synchronously(domain_execution)
-        else:
-            self._workflow_node_execution_repository.save(domain_execution)
+        self._workflow_node_execution_repository.save(domain_execution)
 
         snapshot = _NodeRuntimeSnapshot(
             node_id=event.node_id,
@@ -366,11 +361,7 @@ class WorkflowPersistenceLayer(GraphEngineLayer):
     def _append_retry_history(self, execution: WorkflowNodeExecution, event: NodeRunRetryEvent) -> None:
         """Append a validated full attempt before repository truncation or offload."""
         finished_at = naive_utc_now()
-        process_data = preserve_workflow_agent_binding_id(
-            event.node_run_result.process_data,
-            execution.process_data,
-        )
-        process_data = dict(process_data or {})
+        process_data = dict(execution.process_data or {})
         raw_history = process_data.get(RETRY_HISTORY_PROCESS_DATA_KEY)
         history = list(raw_history) if isinstance(raw_history, list) else []
         projected_outputs = project_node_outputs_for_workflow_run(
@@ -399,12 +390,11 @@ class WorkflowPersistenceLayer(GraphEngineLayer):
         next_process_data: Mapping[str, Any] | None,
     ) -> Mapping[str, Any] | None:
         """Keep internal retry history while replacing node-specific Process Data."""
-        merged_process_data = preserve_workflow_agent_binding_id(existing_process_data, next_process_data)
         raw_history = (existing_process_data or {}).get(RETRY_HISTORY_PROCESS_DATA_KEY)
         if not isinstance(raw_history, list) or not raw_history:
-            return merged_process_data
+            return next_process_data
 
-        merged_process_data = dict(merged_process_data or {})
+        merged_process_data = dict(next_process_data or {})
         merged_process_data[RETRY_HISTORY_PROCESS_DATA_KEY] = raw_history
         return merged_process_data
 
@@ -450,11 +440,6 @@ class WorkflowPersistenceLayer(GraphEngineLayer):
                 outputs=projected_outputs,
                 metadata=node_result.metadata,
             )
-        else:
-            domain_execution.process_data = preserve_workflow_agent_binding_id(
-                node_result.process_data,
-                domain_execution.process_data,
-            )
 
         self._workflow_node_execution_repository.save(domain_execution)
         self._workflow_node_execution_repository.save_execution_data(domain_execution)

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/hosting_configuration.py

@@ -6,7 +6,6 @@ from pydantic import BaseModel
 from configs import dify_config
 from core.entities import DEFAULT_PLUGIN_ID
 from core.entities.provider_entities import ProviderQuotaType, QuotaUnit, RestrictModel
-from enums.deployment_edition import DeploymentEdition
 from graphon.model_runtime.entities.model_entities import ModelType
 
 
@@ -50,7 +49,7 @@ class HostingConfiguration:
         self.moderation_config = None
 
     def init_app(self, app: Flask):
-        if dify_config.DEPLOYMENT_EDITION != DeploymentEdition.CLOUD:
+        if dify_config.EDITION != "CLOUD":
             return
 
         self.provider_map[f"{DEFAULT_PLUGIN_ID}/azure_openai/azure_openai"] = self.init_azure_openai()

api/core/indexing_runner.py

@@ -21,7 +21,6 @@ from core.model_manager import ModelInstance, ModelManager
 from core.rag.cleaner.clean_processor import CleanProcessor
 from core.rag.datasource.keyword.keyword_factory import Keyword
 from core.rag.docstore.dataset_docstore import DatasetDocumentStore
-from core.rag.embedding.token_counter import calculate_segment_token_counts
 from core.rag.extractor.entity.datasource_type import DatasourceType
 from core.rag.extractor.entity.extract_setting import ExtractSetting, NotionInfo, WebsiteInfo
 from core.rag.index_processor.constant.index_type import IndexStructureType, IndexTechniqueType
@@ -114,25 +113,17 @@ class IndexingRunner:
                     current_user=current_user,
                     session=session,
                 )
-                token_counts = calculate_segment_token_counts(dataset=dataset, documents=documents)
-                total_tokens = sum(token_counts)
                 # save segment
-                self._load_segments(
-                    session=session,
-                    dataset=dataset,
-                    dataset_document=requeried_document,
-                    documents=documents,
-                    token_counts=token_counts,
-                )
+                self._load_segments(dataset, requeried_document, documents, session)
                 session.commit()
 
                 # load
                 self._load(
-                    session=session,
+                    index_processor=index_processor,
                     dataset=dataset,
                     dataset_document=requeried_document,
                     documents=documents,
-                    total_tokens=total_tokens,
+                    session=session,
                 )
             except DocumentIsPausedError:
                 raise DocumentIsPausedError(f"Document paused, document id: {document_id}")
@@ -199,25 +190,17 @@ class IndexingRunner:
                 current_user=current_user,
                 session=session,
             )
-            token_counts = calculate_segment_token_counts(dataset=dataset, documents=documents)
-            total_tokens = sum(token_counts)
             # save segment
-            self._load_segments(
-                session=session,
-                dataset=dataset,
-                dataset_document=requeried_document,
-                documents=documents,
-                token_counts=token_counts,
-            )
+            self._load_segments(dataset, requeried_document, documents, session)
             session.commit()
 
             # load
             self._load(
-                session=session,
+                index_processor=index_processor,
                 dataset=dataset,
                 dataset_document=requeried_document,
                 documents=documents,
-                total_tokens=total_tokens,
+                session=session,
             )
         except DocumentIsPausedError:
             raise DocumentIsPausedError(f"Document paused, document id: {document_id}")
@@ -242,7 +225,7 @@ class IndexingRunner:
             if not dataset:
                 raise ValueError("no dataset found")
 
-            # get existing document segments
+            # get exist document_segment list and delete
             document_segments = session.scalars(
                 select(DocumentSegment).where(
                     DocumentSegment.dataset_id == dataset.id,
@@ -281,15 +264,15 @@ class IndexingRunner:
                                     child_documents.append(child_document)
                                 document.children = child_documents
                         documents.append(document)
-            # Preserve the full document total even when only incomplete segments are re-indexed.
-            total_tokens = sum(document_segment.tokens for document_segment in document_segments)
             # build index
+            index_type = requeried_document.doc_form
+            index_processor = IndexProcessorFactory(index_type).init_index_processor()
             self._load(
-                session=session,
+                index_processor=index_processor,
                 dataset=dataset,
                 dataset_document=requeried_document,
                 documents=documents,
-                total_tokens=total_tokens,
+                session=session,
             )
         except DocumentIsPausedError:
             raise DocumentIsPausedError(f"Document paused, document id: {document_id}")
@@ -618,16 +601,28 @@ class IndexingRunner:
 
     def _load(
         self,
-        session: Session,
+        index_processor: BaseIndexProcessor,
         dataset: Dataset,
         dataset_document: DatasetDocument,
         documents: list[Document],
-        total_tokens: int,
-    ) -> None:
-        """Build indexes and mark the document complete using the token total computed before hash sharding."""
+        session: Session,
+    ):
+        """
+        insert index and update document/segment status to completed
+        """
 
-        # Build indexes using the existing hash-based worker groups.
+        embedding_model_instance = None
+        if dataset.indexing_technique == IndexTechniqueType.HIGH_QUALITY:
+            embedding_model_instance = self._get_model_manager(dataset.tenant_id).get_model_instance(
+                tenant_id=dataset.tenant_id,
+                provider=dataset.embedding_model_provider,
+                model_type=ModelType.TEXT_EMBEDDING,
+                model=dataset.embedding_model,
+            )
+
+        # chunk nodes by chunk size
         indexing_start_at = time.perf_counter()
+        tokens = 0
         create_keyword_thread = None
         if (
             dataset_document.doc_form != IndexStructureType.PARENT_CHILD_INDEX
@@ -664,11 +659,12 @@ class IndexingRunner:
                             chunk_documents,
                             dataset.id,
                             dataset_document.id,
+                            embedding_model_instance,
                         )
                     )
 
                 for future in futures:
-                    future.result()
+                    tokens += future.result()
         if (
             dataset_document.doc_form != IndexStructureType.PARENT_CHILD_INDEX
             and dataset.indexing_technique == IndexTechniqueType.ECONOMY
@@ -683,7 +679,7 @@ class IndexingRunner:
             document_id=dataset_document.id,
             after_indexing_status=IndexingStatus.COMPLETED,
             extra_update_params={
-                DatasetDocument.tokens: total_tokens,
+                DatasetDocument.tokens: tokens,
                 DatasetDocument.completed_at: naive_utc_now(),
                 DatasetDocument.indexing_latency: indexing_end_at - indexing_start_at,
                 DatasetDocument.error: None,
@@ -724,7 +720,8 @@ class IndexingRunner:
         chunk_documents: list[Document],
         dataset_id: str,
         dataset_document_id: str,
-    ) -> None:
+        embedding_model_instance: ModelInstance | None,
+    ):
         with flask_app.app_context():
             with session_factory.create_session() as session:
                 dataset = session.get(Dataset, dataset_id)
@@ -738,6 +735,11 @@ class IndexingRunner:
                 # check document is paused
                 self._check_document_paused_status(dataset_document.id)
 
+                tokens = 0
+                if embedding_model_instance:
+                    page_content_list = [document.page_content for document in chunk_documents]
+                    tokens += sum(embedding_model_instance.get_text_embedding_num_tokens(page_content_list))
+
                 multimodal_documents = []
                 for document in chunk_documents:
                     if document.attachments and dataset.is_multimodal:
@@ -771,6 +773,8 @@ class IndexingRunner:
 
                 session.commit()
 
+                return tokens
+
     @staticmethod
     def _check_document_paused_status(document_id: str):
         indexing_cache_key = f"document_{document_id}_is_paused"
@@ -860,14 +864,8 @@ class IndexingRunner:
         return documents
 
     def _load_segments(
-        self,
-        session: Session,
-        dataset: Dataset,
-        dataset_document: DatasetDocument,
-        documents: list[Document],
-        token_counts: list[int],
-    ) -> None:
-        """Persist transformed documents and their precomputed token counts before indexing starts."""
+        self, dataset: Dataset, dataset_document: DatasetDocument, documents: list[Document], session: Session
+    ):
         # save node to document segment
         doc_store = DatasetDocumentStore(
             dataset=dataset, user_id=dataset_document.created_by, document_id=dataset_document.id
@@ -875,10 +873,9 @@ class IndexingRunner:
 
         # add document segments
         doc_store.add_documents(
-            session=session,
             docs=documents,
             save_child=dataset_document.doc_form == IndexStructureType.PARENT_CHILD_INDEX,
-            token_counts=token_counts,
+            session=session,
         )
 
         # update document status to indexing
@@ -903,6 +900,7 @@ class IndexingRunner:
                 DocumentSegment.indexing_at: naive_utc_now(),
             },
         )
+        pass
 
 
 class DocumentIsPausedError(Exception):

api/core/logging/context.py

@@ -6,21 +6,9 @@ using Python's contextvars for thread-safe and async-safe storage.
 
 import uuid
 from contextvars import ContextVar
-from typing import NamedTuple
-
-
-class IdentityContext(NamedTuple):
-    """Immutable identity values captured for logging."""
-
-    tenant_id: str
-    user_id: str
-    user_type: str
-
 
 _request_id: ContextVar[str] = ContextVar("log_request_id", default="")
 _trace_id: ContextVar[str] = ContextVar("log_trace_id", default="")
-_EMPTY_IDENTITY_CONTEXT = IdentityContext(tenant_id="", user_id="", user_type="")
-_identity: ContextVar[IdentityContext] = ContextVar("log_identity", default=_EMPTY_IDENTITY_CONTEXT)
 
 
 def get_request_id() -> str:
@@ -33,35 +21,15 @@ def get_trace_id() -> str:
     return _trace_id.get()
 
 
-def get_identity_context() -> IdentityContext:
-    """Get the immutable tenant, user, and user-type snapshot for logging."""
-    return _identity.get()
-
-
-def set_identity_context(
-    *, tenant_id: str | None = None, user_id: str | None = None, user_type: str | None = None
-) -> None:
-    """Set primitive identity values already resolved by an authentication boundary."""
-    _identity.set(
-        IdentityContext(
-            tenant_id=tenant_id or "",
-            user_id=user_id or "",
-            user_type=user_type or "",
-        )
-    )
-
-
 def init_request_context() -> None:
-    """Initialize request context and discard identity left by earlier work."""
+    """Initialize request context. Call at start of each request."""
     req_id = uuid.uuid4().hex[:10]
     trace_id = uuid.uuid5(uuid.NAMESPACE_DNS, req_id).hex
     _request_id.set(req_id)
     _trace_id.set(trace_id)
-    _identity.set(_EMPTY_IDENTITY_CONTEXT)
 
 
 def clear_request_context() -> None:
-    """Clear request context at a request or task lifecycle boundary."""
+    """Clear request context. Call at end of request (optional)."""
     _request_id.set("")
     _trace_id.set("")
-    _identity.set(_EMPTY_IDENTITY_CONTEXT)

api/core/logging/filters.py

@@ -4,7 +4,10 @@ import contextlib
 import logging
 from typing import override
 
-from core.logging.context import get_identity_context, get_request_id, get_trace_id
+import flask
+
+from core.logging.context import get_request_id, get_trace_id
+from core.logging.structured_formatter import IdentityDict
 
 
 class TraceContextFilter(logging.Filter):
@@ -48,16 +51,49 @@ class TraceContextFilter(logging.Filter):
 
 
 class IdentityContextFilter(logging.Filter):
-    """Add an identity snapshot without invoking authentication or database work.
-
-    Logging can run while other libraries hold internal locks, so this filter must
-    only read primitive ContextVar values populated by authentication boundaries.
+    """
+    Filter that adds user identity context to log records.
+    Extracts tenant_id, user_id, and user_type from Flask-Login current_user.
     """
 
     @override
     def filter(self, record: logging.LogRecord) -> bool:
-        identity = get_identity_context()
-        record.tenant_id = identity.tenant_id
-        record.user_id = identity.user_id
-        record.user_type = identity.user_type
+        identity = self._extract_identity()
+        record.tenant_id = identity.get("tenant_id", "")
+        record.user_id = identity.get("user_id", "")
+        record.user_type = identity.get("user_type", "")
         return True
+
+    def _extract_identity(self) -> IdentityDict:
+        """Extract identity from current_user if in request context."""
+        try:
+            if not flask.has_request_context():
+                return {}
+            from flask_login import current_user
+
+            # Check if user is authenticated using the proxy
+            if not current_user.is_authenticated:
+                return {}
+
+            # Access the underlying user object
+            user = current_user
+
+            from models import Account
+            from models.model import EndUser
+
+            identity: IdentityDict = {}
+
+            match user:
+                case Account():
+                    if user.current_tenant_id:
+                        identity["tenant_id"] = user.current_tenant_id
+                    identity["user_id"] = user.id
+                    identity["user_type"] = "account"
+                case EndUser():
+                    identity["tenant_id"] = user.tenant_id
+                    identity["user_id"] = user.id
+                    identity["user_type"] = user.type or "end_user"
+
+            return identity
+        except Exception:
+            return {}

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/plugin/impl/base.py

@@ -1,7 +1,7 @@
 import inspect
 import json
 import logging
-from collections.abc import Callable, Generator, Mapping
+from collections.abc import Callable, Generator
 from typing import Any, cast
 from urllib.parse import unquote
 
@@ -23,7 +23,6 @@ from core.plugin.impl.exc import (
     PluginLLMPollingUnsupportedError,
     PluginNotFoundError,
     PluginPermissionDeniedError,
-    PluginRuntimeError,
     PluginUniqueIdentifierError,
 )
 from core.trigger.errors import (
@@ -376,18 +375,6 @@ class BasePluginClient:
                     # type `PluginLLMPollingUnsupportedError`.
                     case PluginLLMPollingUnsupportedError.__name__:
                         raise PluginLLMPollingUnsupportedError(description=error_object.get("message"))
-                    case PluginRuntimeError.__name__:
-                        args = error_object.get("args")
-                        lambda_request_id = args.get("request_id") if isinstance(args, Mapping) else None
-                        if not isinstance(lambda_request_id, str):
-                            lambda_request_id = None
-                        runtime_message = error_object.get("message")
-                        if not isinstance(runtime_message, str):
-                            runtime_message = "Plugin runtime request failed"
-                        raise PluginRuntimeError(
-                            description=runtime_message,
-                            lambda_request_id=lambda_request_id,
-                        )
                     case _:
                         raise PluginInvokeError(description=message)
             case PluginDaemonInternalServerError.__name__:

api/core/plugin/impl/exc.py

@@ -49,18 +49,6 @@ class PluginDaemonBadRequestError(PluginDaemonClientSideError):
     description: str = "Bad Request"
 
 
-class PluginRuntimeError(PluginDaemonInternalError):
-    """A plugin runtime failed before it could return a valid plugin response."""
-
-    lambda_request_id: str | None
-
-    def __init__(self, description: str, lambda_request_id: str | None = None) -> None:
-        self.lambda_request_id = lambda_request_id
-        if lambda_request_id:
-            description = description.replace(f"RequestId: {lambda_request_id} Error: ", "", 1)
-        super().__init__(description)
-
-
 class PluginInvokeError(PluginDaemonClientSideError, ValueError):
     description: str = "Invoke Error"
 

api/core/provider_manager.py

@@ -34,7 +34,6 @@ from core.entities.provider_entities import (
 from core.helper import encrypter
 from core.helper.model_provider_cache import ProviderCredentialsCache, ProviderCredentialsCacheType
 from core.helper.position_helper import is_filtered
-from enums.deployment_edition import DeploymentEdition
 from extensions import ext_hosting_provider
 from extensions.ext_database import db
 from extensions.ext_redis import redis_client
@@ -744,7 +743,7 @@ class ProviderManager:
 
             if preferred_provider_type_record:
                 preferred_provider_type = preferred_provider_type_record.preferred_provider_type
-            elif dify_config.DEPLOYMENT_EDITION == DeploymentEdition.CLOUD and system_configuration.enabled:
+            elif dify_config.EDITION == "CLOUD" and system_configuration.enabled:
                 preferred_provider_type = ProviderType.SYSTEM
             elif custom_configuration.provider or custom_configuration.models:
                 preferred_provider_type = ProviderType.CUSTOM
@@ -1539,7 +1538,7 @@ class ProviderManager:
                 quota_type_to_provider_records_dict[provider_record.quota_type] = provider_record  # type: ignore[index]
         quota_configurations = []
 
-        if dify_config.DEPLOYMENT_EDITION == DeploymentEdition.CLOUD:
+        if dify_config.EDITION == "CLOUD":
             from services.credit_pool_service import CreditPoolService
 
             trail_pool = CreditPoolService.get_pool(

api/core/rag/data_post_processor/data_post_processor.py

@@ -10,7 +10,6 @@ from core.rag.rerank.entity.weight import KeywordSetting, VectorSetting, Weights
 from core.rag.rerank.rerank_base import BaseRerankRunner
 from core.rag.rerank.rerank_factory import RerankRunnerFactory
 from core.rag.rerank.rerank_type import RerankMode
-from extensions.otel import trace_span
 from graphon.model_runtime.entities.model_entities import ModelType
 from graphon.model_runtime.errors.invoke import InvokeAuthorizationError
 
@@ -53,7 +52,6 @@ class DataPostProcessor:
         )
         self.reorder_runner = self._get_reorder_runner(reorder_enabled)
 
-    @trace_span()
     def invoke(
         self,
         query: str,

api/core/rag/datasource/retrieval_service.py

@@ -1,10 +1,12 @@
 import concurrent.futures
+import functools
 import logging
-from collections.abc import Sequence
+from collections.abc import Callable, Sequence
 from concurrent.futures import ThreadPoolExecutor
 from typing import Any, NotRequired, TypedDict
 
 from flask import Flask, current_app
+from opentelemetry import context as otel_context
 from sqlalchemy import select
 from sqlalchemy.orm import Session, load_only
 
@@ -24,7 +26,7 @@ from core.rag.rerank.rerank_type import RerankMode
 from core.rag.retrieval.retrieval_methods import RetrievalMethod
 from core.tools.signature import sign_upload_file_preview_url
 from extensions.ext_database import db
-from extensions.otel import propagate_context, trace_span
+from extensions.otel import trace_span
 from graphon.model_runtime.entities.model_entities import ModelType
 from models.dataset import (
     ChildChunk,
@@ -90,6 +92,20 @@ default_retrieval_model: DefaultRetrievalModelDict = {
 logger = logging.getLogger(__name__)
 
 
+def _propagate_otel_context[**P, R](func: Callable[P, R]) -> Callable[P, R]:
+    captured_context = otel_context.get_current()
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        token = otel_context.attach(captured_context)
+        try:
+            return func(*args, **kwargs)
+        finally:
+            otel_context.detach(token)
+
+    return wrapper
+
+
 class RetrievalService:
     # Cache precompiled regular expressions to avoid repeated compilation
     @classmethod
@@ -123,7 +139,7 @@ class RetrievalService:
             if query:
                 futures.append(
                     executor.submit(
-                        propagate_context(retrieval_service._retrieve),
+                        _propagate_otel_context(retrieval_service._retrieve),
                         flask_app=current_app._get_current_object(),  # type: ignore
                         retrieval_method=retrieval_method,
                         dataset=dataset,
@@ -143,7 +159,7 @@ class RetrievalService:
                 for attachment_id in attachment_ids:
                     futures.append(
                         executor.submit(
-                            propagate_context(retrieval_service._retrieve),
+                            _propagate_otel_context(retrieval_service._retrieve),
                             flask_app=current_app._get_current_object(),  # type: ignore
                             retrieval_method=retrieval_method,
                             dataset=dataset,
@@ -804,7 +820,7 @@ class RetrievalService:
                 if retrieval_method == RetrievalMethod.KEYWORD_SEARCH and query:
                     futures.append(
                         executor.submit(
-                            propagate_context(self.keyword_search),
+                            _propagate_otel_context(self.keyword_search),
                             flask_app=current_app._get_current_object(),  # type: ignore
                             dataset_id=dataset.id,
                             query=query,
@@ -818,7 +834,7 @@ class RetrievalService:
                     if query:
                         futures.append(
                             executor.submit(
-                                propagate_context(self.embedding_search),
+                                _propagate_otel_context(self.embedding_search),
                                 flask_app=current_app._get_current_object(),  # type: ignore
                                 dataset_id=dataset.id,
                                 query=query,
@@ -835,7 +851,7 @@ class RetrievalService:
                     if attachment_id:
                         futures.append(
                             executor.submit(
-                                propagate_context(self.embedding_search),
+                                _propagate_otel_context(self.embedding_search),
                                 flask_app=current_app._get_current_object(),  # type: ignore
                                 dataset_id=dataset.id,
                                 query=attachment_id,
@@ -852,7 +868,7 @@ class RetrievalService:
                 if RetrievalMethod.is_support_fulltext_search(retrieval_method) and query:
                     futures.append(
                         executor.submit(
-                            propagate_context(self.full_text_index_search),
+                            _propagate_otel_context(self.full_text_index_search),
                             flask_app=current_app._get_current_object(),  # type: ignore
                             dataset_id=dataset.id,
                             query=query,

api/core/rag/docstore/dataset_docstore.py

@@ -6,7 +6,10 @@ from typing import Any
 from sqlalchemy import delete, func, select
 from sqlalchemy.orm import Session
 
+from core.model_manager import ModelManager
+from core.rag.index_processor.constant.index_type import IndexTechniqueType
 from core.rag.models.document import AttachmentDocument, Document
+from graphon.model_runtime.entities.model_entities import ModelType
 from models.dataset import ChildChunk, Dataset, DocumentSegment, SegmentAttachmentBinding
 from models.enums import SegmentType
 
@@ -66,22 +69,34 @@ class DatasetDocumentStore:
 
     def add_documents(
         self,
-        session: Session,
         docs: Sequence[Document],
-        token_counts: list[int],
+        session: Session,
         allow_update: bool = True,
         save_child: bool = False,
-    ) -> None:
-        document_token_pairs = list(zip(docs, token_counts, strict=True))
-
+    ):
         max_position = session.scalar(
             select(func.max(DocumentSegment.position)).where(DocumentSegment.document_id == self._document_id)
         )
 
         if max_position is None:
             max_position = 0
+        embedding_model = None
+        if self._dataset.indexing_technique == IndexTechniqueType.HIGH_QUALITY:
+            model_manager = ModelManager.for_tenant(tenant_id=self._dataset.tenant_id)
+            embedding_model = model_manager.get_model_instance(
+                tenant_id=self._dataset.tenant_id,
+                provider=self._dataset.embedding_model_provider,
+                model_type=ModelType.TEXT_EMBEDDING,
+                model=self._dataset.embedding_model,
+            )
 
-        for doc, tokens in document_token_pairs:
+        if embedding_model:
+            page_content_list = [doc.page_content for doc in docs]
+            tokens_list = embedding_model.get_text_embedding_num_tokens(page_content_list)
+        else:
+            tokens_list = [0] * len(docs)
+
+        for doc, tokens in zip(docs, tokens_list):
             if not isinstance(doc, Document):
                 raise ValueError("doc must be a Document")
 

api/core/rag/embedding/token_counter.py

@@ -1,25 +0,0 @@
-"""Token counting for document segments."""
-
-from core.model_manager import ModelManager
-from core.rag.index_processor.constant.index_type import IndexTechniqueType
-from core.rag.models.document import Document
-from graphon.model_runtime.entities.model_entities import ModelType
-from models.dataset import Dataset
-
-
-def calculate_segment_token_counts(dataset: Dataset, documents: list[Document]) -> list[int]:
-    """Return one token count per document, invoking the embedding model only for high-quality indexes."""
-    if not documents:
-        return []
-
-    if dataset.indexing_technique != IndexTechniqueType.HIGH_QUALITY:
-        return [0] * len(documents)
-
-    model_manager = ModelManager.for_tenant(tenant_id=dataset.tenant_id)
-    embedding_model = model_manager.get_model_instance(
-        tenant_id=dataset.tenant_id,
-        provider=dataset.embedding_model_provider,
-        model_type=ModelType.TEXT_EMBEDDING,
-        model=dataset.embedding_model,
-    )
-    return embedding_model.get_text_embedding_num_tokens([document.page_content for document in documents])

api/core/rag/index_processor/processor/paragraph_index_processor.py

@@ -19,7 +19,6 @@ from core.rag.cleaner.clean_processor import CleanProcessor
 from core.rag.datasource.keyword.keyword_factory import Keyword
 from core.rag.datasource.vdb.vector_factory import Vector
 from core.rag.docstore.dataset_docstore import DatasetDocumentStore
-from core.rag.embedding.token_counter import calculate_segment_token_counts
 from core.rag.entities import Rule
 from core.rag.extractor.entity.extract_setting import ExtractSetting
 from core.rag.extractor.extract_processor import ExtractProcessor
@@ -245,16 +244,10 @@ class ParagraphIndexProcessor(BaseIndexProcessor):
                         all_multimodal_documents.extend(doc.attachments)
                 documents.append(doc)
         if documents:
-            token_counts = calculate_segment_token_counts(dataset=dataset, documents=documents)
             # save node to document segment
             doc_store = DatasetDocumentStore(dataset=dataset, user_id=document.created_by, document_id=document.id)
             # add document segments
-            doc_store.add_documents(
-                session=session,
-                docs=documents,
-                token_counts=token_counts,
-                save_child=False,
-            )
+            doc_store.add_documents(docs=documents, save_child=False, session=session)
             session.commit()
             if dataset.indexing_technique == IndexTechniqueType.HIGH_QUALITY:
                 vector = Vector(dataset, session=session)

api/core/rag/index_processor/processor/parent_child_index_processor.py

@@ -15,7 +15,6 @@ from core.model_manager import ModelInstance
 from core.rag.cleaner.clean_processor import CleanProcessor
 from core.rag.datasource.vdb.vector_factory import Vector
 from core.rag.docstore.dataset_docstore import DatasetDocumentStore
-from core.rag.embedding.token_counter import calculate_segment_token_counts
 from core.rag.entities import ParentMode, Rule
 from core.rag.extractor.entity.extract_setting import ExtractSetting
 from core.rag.extractor.extract_processor import ExtractProcessor
@@ -305,7 +304,6 @@ class ParentChildIndexProcessor(BaseIndexProcessor):
                 doc.attachments = self._get_content_files(doc, current_user=account, session=session)
             documents.append(doc)
         if documents:
-            token_counts = calculate_segment_token_counts(dataset=dataset, documents=documents)
             # update document parent mode
             dataset_process_rule = DatasetProcessRule(
                 dataset_id=dataset.id,
@@ -323,12 +321,7 @@ class ParentChildIndexProcessor(BaseIndexProcessor):
             # save node to document segment
             doc_store = DatasetDocumentStore(dataset=dataset, user_id=document.created_by, document_id=document.id)
             # add document segments
-            doc_store.add_documents(
-                session=session,
-                docs=documents,
-                token_counts=token_counts,
-                save_child=True,
-            )
+            doc_store.add_documents(docs=documents, save_child=True, session=session)
             session.commit()
             if dataset.indexing_technique == IndexTechniqueType.HIGH_QUALITY:
                 all_child_documents = []

api/core/rag/index_processor/processor/qa_index_processor.py

@@ -17,7 +17,6 @@ from core.llm_generator.llm_generator import LLMGenerator
 from core.rag.cleaner.clean_processor import CleanProcessor
 from core.rag.datasource.vdb.vector_factory import Vector
 from core.rag.docstore.dataset_docstore import DatasetDocumentStore
-from core.rag.embedding.token_counter import calculate_segment_token_counts
 from core.rag.entities import Rule
 from core.rag.extractor.entity.extract_setting import ExtractSetting
 from core.rag.extractor.extract_processor import ExtractProcessor
@@ -206,15 +205,9 @@ class QAIndexProcessor(BaseIndexProcessor):
             doc = Document(page_content=qa_chunk.question, metadata=metadata)
             documents.append(doc)
         if documents:
-            token_counts = calculate_segment_token_counts(dataset=dataset, documents=documents)
             # save node to document segment
             doc_store = DatasetDocumentStore(dataset=dataset, user_id=document.created_by, document_id=document.id)
-            doc_store.add_documents(
-                session=session,
-                docs=documents,
-                token_counts=token_counts,
-                save_child=False,
-            )
+            doc_store.add_documents(docs=documents, save_child=False, session=session)
             session.commit()
             if dataset.indexing_technique == IndexTechniqueType.HIGH_QUALITY:
                 vector = Vector(dataset, session=session)

api/core/rag/rerank/rerank_model.py

@@ -9,7 +9,6 @@ from core.rag.index_processor.constant.query_type import QueryType
 from core.rag.models.document import Document
 from core.rag.rerank.rerank_base import BaseRerankRunner
 from extensions.ext_storage import storage
-from extensions.otel import trace_span
 from graphon.model_runtime.entities.model_entities import ModelType
 from graphon.model_runtime.entities.rerank_entities import MultimodalRerankInput, RerankResult
 from models.model import UploadFile
@@ -23,7 +22,6 @@ class RerankModelRunner(BaseRerankRunner):
         self._session = session
 
     @override
-    @trace_span()
     def run(
         self,
         query: str,

api/core/rag/retrieval/dataset_retrieval.py

@@ -65,7 +65,6 @@ from core.workflow.nodes.knowledge_retrieval.retrieval import (
 )
 from extensions.ext_database import db
 from extensions.ext_redis import redis_client
-from extensions.otel import propagate_context, trace_span
 from graphon.file import File, FileTransferMethod, FileType
 from graphon.model_runtime.entities.llm_entities import LLMMode, LLMResult, LLMUsage
 from graphon.model_runtime.entities.message_entities import PromptMessage, PromptMessageRole, PromptMessageTool
@@ -117,7 +116,6 @@ class DatasetRetrieval:
         else:
             self._llm_usage = self._llm_usage.plus(usage)
 
-    @trace_span()
     def knowledge_retrieval(self, session: Session, request: KnowledgeRetrievalRequest) -> list[Source]:
         self._check_knowledge_rate_limit(request.tenant_id)
         available_datasets = self._get_available_datasets(request.tenant_id, request.dataset_ids)
@@ -601,7 +599,6 @@ class DatasetRetrieval:
             return "\n".join([document_context.content for document_context in document_context_list]), context_files
         return "", context_files
 
-    @trace_span()
     def single_retrieve(
         self,
         session: Session,
@@ -727,7 +724,7 @@ class DatasetRetrieval:
 
                 if results:
                     thread = threading.Thread(
-                        target=propagate_context(self._on_retrieval_end),
+                        target=self._on_retrieval_end,
                         kwargs={
                             "flask_app": current_app._get_current_object(),  # type: ignore
                             "documents": results,
@@ -740,7 +737,6 @@ class DatasetRetrieval:
                 return results
         return []
 
-    @trace_span()
     def multiple_retrieve(
         self,
         app_id: str,
@@ -802,7 +798,7 @@ class DatasetRetrieval:
 
             if query:
                 query_thread = threading.Thread(
-                    target=propagate_context(self._multiple_retrieve_thread_safely),
+                    target=self._multiple_retrieve_thread,
                     kwargs={
                         "flask_app": current_app._get_current_object(),  # type: ignore
                         "available_datasets": available_datasets,
@@ -828,7 +824,7 @@ class DatasetRetrieval:
             if attachment_ids:
                 for attachment_id in attachment_ids:
                     attachment_thread = threading.Thread(
-                        target=propagate_context(self._multiple_retrieve_thread_safely),
+                        target=self._multiple_retrieve_thread,
                         kwargs={
                             "flask_app": current_app._get_current_object(),  # type: ignore
                             "available_datasets": available_datasets,
@@ -869,7 +865,7 @@ class DatasetRetrieval:
         if all_documents:
             # add thread to call _on_retrieval_end
             retrieval_end_thread = threading.Thread(
-                target=propagate_context(self._on_retrieval_end),
+                target=self._on_retrieval_end,
                 kwargs={
                     "flask_app": current_app._get_current_object(),  # type: ignore
                     "documents": all_documents,
@@ -1165,7 +1161,6 @@ class DatasetRetrieval:
 
                         all_documents.extend(documents)
 
-    @trace_span()
     def _run_retriever_thread(
         self,
         *,
@@ -1177,51 +1172,27 @@ class DatasetRetrieval:
         document_ids_filter: list[str] | None,
         metadata_condition: MetadataFilteringCondition | None,
         attachment_ids: list[str] | None,
-    ) -> None:
-        with session_factory.create_session() as session:
-            self._retriever(
-                flask_app=flask_app,
-                session=session,
-                dataset_id=dataset_id,
-                query=query or "",
-                top_k=top_k,
-                all_documents=all_documents,
-                document_ids_filter=document_ids_filter,
-                metadata_condition=metadata_condition,
-                attachment_ids=attachment_ids,
-            )
-
-    def _run_retriever_thread_safely(
-        self,
-        *,
-        flask_app: Flask,
-        dataset_id: str,
-        query: str | None,
-        top_k: int,
-        all_documents: list[Document],
-        document_ids_filter: list[str] | None,
-        metadata_condition: MetadataFilteringCondition | None,
-        attachment_ids: list[str] | None,
         cancel_event: threading.Event | None,
         thread_exceptions: list[Exception] | None,
     ) -> None:
-        """Collect errors only after they pass through the traced retrieval method."""
         try:
-            self._run_retriever_thread(
-                flask_app=flask_app,
-                dataset_id=dataset_id,
-                query=query,
-                top_k=top_k,
-                all_documents=all_documents,
-                document_ids_filter=document_ids_filter,
-                metadata_condition=metadata_condition,
-                attachment_ids=attachment_ids,
-            )
-        except Exception as exc:
+            with session_factory.create_session() as session:
+                self._retriever(
+                    flask_app=flask_app,
+                    session=session,
+                    dataset_id=dataset_id,
+                    query=query or "",
+                    top_k=top_k,
+                    all_documents=all_documents,
+                    document_ids_filter=document_ids_filter,
+                    metadata_condition=metadata_condition,
+                    attachment_ids=attachment_ids,
+                )
+        except Exception as e:
             if cancel_event:
                 cancel_event.set()
             if thread_exceptions is not None:
-                thread_exceptions.append(exc)
+                thread_exceptions.append(e)
 
     def to_dataset_retriever_tool(
         self,
@@ -1824,7 +1795,6 @@ class DatasetRetrieval:
 
         return full_text, usage
 
-    @trace_span()
     def _multiple_retrieve_thread(
         self,
         flask_app: Flask,
@@ -1843,11 +1813,11 @@ class DatasetRetrieval:
         attachment_id: str | None,
         dataset_count: int,
         cancel_event: threading.Event | None = None,
-    ) -> None:
+        thread_exceptions: list[Exception] | None = None,
+    ):
         try:
             with flask_app.app_context():
                 threads = []
-                retrieval_thread_exceptions: list[Exception] = []
                 all_documents_item: list[Document] = []
                 index_type = None
                 for dataset in available_datasets:
@@ -1866,7 +1836,7 @@ class DatasetRetrieval:
                             else:
                                 continue
                     retrieval_thread = threading.Thread(
-                        target=propagate_context(self._run_retriever_thread_safely),
+                        target=self._run_retriever_thread,
                         kwargs={
                             "flask_app": flask_app,
                             "dataset_id": dataset.id,
@@ -1877,7 +1847,7 @@ class DatasetRetrieval:
                             "metadata_condition": metadata_condition,
                             "attachment_ids": [attachment_id] if attachment_id else None,
                             "cancel_event": cancel_event,
-                            "thread_exceptions": retrieval_thread_exceptions,
+                            "thread_exceptions": thread_exceptions,
                         },
                     )
                     threads.append(retrieval_thread)
@@ -1892,9 +1862,6 @@ class DatasetRetrieval:
                     if cancel_event and cancel_event.is_set():
                         break
 
-                if retrieval_thread_exceptions:
-                    raise retrieval_thread_exceptions[0]
-
                 # Skip second reranking when there is only one dataset
                 if reranking_enable and dataset_count > 1:
                     # do rerank for searched documents
@@ -1935,55 +1902,11 @@ class DatasetRetrieval:
                         all_documents_item = all_documents_item[:top_k] if top_k else all_documents_item
                 if all_documents_item:
                     all_documents.extend(all_documents_item)
-        except Exception:
-            raise
-
-    def _multiple_retrieve_thread_safely(
-        self,
-        *,
-        flask_app: Flask,
-        available_datasets: list[Dataset],
-        metadata_condition: MetadataFilteringCondition | None,
-        metadata_filter_document_ids: dict[str, list[str]] | None,
-        all_documents: list[Document],
-        tenant_id: str,
-        reranking_enable: bool,
-        reranking_mode: str,
-        reranking_model: RerankingModelDict | None,
-        weights: WeightsDict | None,
-        top_k: int,
-        score_threshold: float,
-        query: str | None,
-        attachment_id: str | None,
-        dataset_count: int,
-        cancel_event: threading.Event | None = None,
-        thread_exceptions: list[Exception] | None = None,
-    ) -> None:
-        """Collect errors only after they pass through the traced multi-retrieval method."""
-        try:
-            self._multiple_retrieve_thread(
-                flask_app=flask_app,
-                available_datasets=available_datasets,
-                metadata_condition=metadata_condition,
-                metadata_filter_document_ids=metadata_filter_document_ids,
-                all_documents=all_documents,
-                tenant_id=tenant_id,
-                reranking_enable=reranking_enable,
-                reranking_mode=reranking_mode,
-                reranking_model=reranking_model,
-                weights=weights,
-                top_k=top_k,
-                score_threshold=score_threshold,
-                query=query,
-                attachment_id=attachment_id,
-                dataset_count=dataset_count,
-                cancel_event=cancel_event,
-            )
-        except Exception as exc:
+        except Exception as e:
             if cancel_event:
                 cancel_event.set()
             if thread_exceptions is not None:
-                thread_exceptions.append(exc)
+                thread_exceptions.append(e)
 
     def _get_available_datasets(self, tenant_id: str, dataset_ids: list[str]) -> list[Dataset]:
         with session_factory.create_session() as session:

api/core/rbac/entities.py

@@ -10,6 +10,7 @@ class RBACResourceScope(StrEnum):
 
     APP = "app"
     DATASET = "dataset"
+    KNOWLEDGE_FS = "knowledge_space"
     WORKSPACE = "workspace"
 
 
@@ -57,11 +58,19 @@ 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"
     CUSTOMIZATION_MANAGE = "customization_manage"
-    AGENT_MANAGE = "agent_manage"
 
     SNIPPETS_CREATE_AND_MODIFY = "snippets_create_and_modify"
     SNIPPETS_MANAGE = "snippets_management"

api/core/repositories/celery_workflow_node_execution_repository.py

@@ -16,9 +16,6 @@ from core.repositories.factory import (
     OrderConfig,
     WorkflowNodeExecutionRepository,
 )
-from core.repositories.sqlalchemy_workflow_node_execution_repository import (
-    SQLAlchemyWorkflowNodeExecutionRepository,
-)
 from graphon.entities import WorkflowNodeExecution
 from models import Account, CreatorUserRole, EndUser
 from models.workflow import WorkflowNodeExecutionTriggeredFrom
@@ -52,7 +49,6 @@ class CeleryWorkflowNodeExecutionRepository(WorkflowNodeExecutionRepository):
     _creator_user_role: CreatorUserRole
     _execution_cache: dict[str, WorkflowNodeExecution]
     _workflow_execution_mapping: dict[str, list[str]]
-    _sql_repository: SQLAlchemyWorkflowNodeExecutionRepository
 
     def __init__(
         self,
@@ -102,13 +98,6 @@ class CeleryWorkflowNodeExecutionRepository(WorkflowNodeExecutionRepository):
 
         # Cache for mapping workflow_execution_ids to execution IDs for efficient retrieval
         self._workflow_execution_mapping = {}
-        self._sql_repository = SQLAlchemyWorkflowNodeExecutionRepository(
-            session_factory=session_factory,
-            tenant_id=tenant_id,
-            user=user,
-            app_id=app_id,
-            triggered_from=triggered_from,
-        )
 
         logger.info(
             "Initialized CeleryWorkflowNodeExecutionRepository for tenant %s, app %s, triggered_from %s",
@@ -160,17 +149,6 @@ class CeleryWorkflowNodeExecutionRepository(WorkflowNodeExecutionRepository):
             # For now, we'll re-raise the exception
             raise
 
-    @override
-    def save_synchronously(self, execution: WorkflowNodeExecution) -> None:
-        """Create the Agent v2 caller row before runtime participant allocation."""
-
-        self._sql_repository.save_synchronously(execution)
-        self._execution_cache[execution.id] = execution
-        if execution.workflow_execution_id:
-            execution_ids = self._workflow_execution_mapping.setdefault(execution.workflow_execution_id, [])
-            if execution.id not in execution_ids:
-                execution_ids.append(execution.id)
-
     @override
     def get_by_workflow_execution(
         self,

api/core/repositories/factory.py

@@ -35,8 +35,6 @@ class WorkflowExecutionRepository(Protocol):
 class WorkflowNodeExecutionRepository(Protocol):
     def save(self, execution: WorkflowNodeExecution): ...
 
-    def save_synchronously(self, execution: WorkflowNodeExecution) -> None: ...
-
     def save_execution_data(self, execution: WorkflowNodeExecution): ...
 
     def get_by_workflow_execution(

api/core/repositories/sqlalchemy_workflow_node_execution_repository.py

@@ -18,7 +18,6 @@ from tenacity import before_sleep_log, retry, retry_if_exception, stop_after_att
 
 from configs import dify_config
 from core.repositories.factory import OrderConfig, WorkflowNodeExecutionRepository
-from core.workflow.node_execution_process_data import preserve_workflow_agent_binding_id
 from extensions.ext_storage import storage
 from graphon.entities import WorkflowNodeExecution
 from graphon.enums import WorkflowNodeExecutionMetadataKey, WorkflowNodeExecutionStatus
@@ -373,12 +372,6 @@ class SQLAlchemyWorkflowNodeExecutionRepository(WorkflowNodeExecutionRepository)
             logger.exception("Failed to save workflow node execution after all retries")
             raise
 
-    @override
-    def save_synchronously(self, execution: WorkflowNodeExecution) -> None:
-        """Persist a caller row before an Agent v2 participant is materialized."""
-
-        self.save(execution)
-
     def _persist_to_database(self, db_model: WorkflowNodeExecutionModel):
         """
         Persist the database model to the database.
@@ -393,13 +386,6 @@ class SQLAlchemyWorkflowNodeExecutionRepository(WorkflowNodeExecutionRepository)
             existing = session.get(WorkflowNodeExecutionModel, db_model.id)
 
             if existing:
-                merged_process_data = preserve_workflow_agent_binding_id(
-                    existing.process_data_dict,
-                    db_model.process_data_dict,
-                )
-                db_model.process_data = (
-                    _deterministic_json_dump(merged_process_data) if merged_process_data is not None else None
-                )
                 # Update existing record by copying all non-private attributes
                 for key, value in db_model.__dict__.items():
                     if not key.startswith("_"):
@@ -456,25 +442,18 @@ class SQLAlchemyWorkflowNodeExecutionRepository(WorkflowNodeExecutionRepository)
             else:
                 db_model.outputs = self._json_encode(domain_model.outputs)
 
-        process_data = preserve_workflow_agent_binding_id(db_model.process_data_dict, domain_model.process_data)
-        if process_data is not None:
+        if domain_model.process_data is not None:
             result = self._truncate_and_upload(
-                process_data,
+                domain_model.process_data,
                 domain_model.id,
                 ExecutionOffLoadType.PROCESS_DATA,
             )
             if result is not None:
-                truncated_process_data = preserve_workflow_agent_binding_id(
-                    process_data,
-                    result.truncated_value,
-                )
-                if truncated_process_data is None:
-                    raise ValueError("truncated process data is unavailable")
-                db_model.process_data = self._json_encode(truncated_process_data)
-                domain_model.set_truncated_process_data(truncated_process_data)
+                db_model.process_data = self._json_encode(result.truncated_value)
+                domain_model.set_truncated_process_data(result.truncated_value)
                 offload_data = _replace_or_append_offload(offload_data, result.offload)
             else:
-                db_model.process_data = self._json_encode(process_data)
+                db_model.process_data = self._json_encode(domain_model.process_data)
 
         db_model.offload_data = offload_data
         with self._session_factory() as session, session.begin():

api/core/tools/__base/tool.py

@@ -58,6 +58,7 @@ class Tool(ABC):
         if self.runtime and self.runtime.runtime_parameters:
             tool_parameters.update(self.runtime.runtime_parameters)
 
+        # try parse tool parameters into the correct type
         tool_parameters = self._transform_tool_parameters_type(tool_parameters)
 
         result = self._invoke(
@@ -86,14 +87,14 @@ class Tool(ABC):
                 return result
 
     def _transform_tool_parameters_type(self, tool_parameters: dict[str, Any]) -> dict[str, Any]:
-        """Transform declared tool parameter values without resolving runtime schemas."""
+        """
+        Transform tool parameters type
+        """
+        # Temp fix for the issue that the tool parameters will be converted to empty while validating the credentials
         result = deepcopy(tool_parameters)
         for parameter in self.entity.parameters or []:
             if parameter.name in tool_parameters:
-                if parameter.multiple:
-                    result[parameter.name] = parameter.init_frontend_parameter(result.get(parameter.name))
-                else:
-                    result[parameter.name] = parameter.type.cast_value(tool_parameters[parameter.name])
+                result[parameter.name] = parameter.type.cast_value(tool_parameters[parameter.name])
 
         return result
 
@@ -195,31 +196,17 @@ class Tool(ABC):
             }:
                 continue
 
-            is_multiple_select = parameter.multiple and parameter.type in {
-                ToolParameter.ToolParameterType.SELECT,
-                ToolParameter.ToolParameterType.DYNAMIC_SELECT,
-            }
-            if is_multiple_select:
-                item_schema: dict[str, Any] = {"type": "string"}
-                if parameter.type == ToolParameter.ToolParameterType.SELECT and parameter.options:
-                    item_schema["enum"] = [option.value for option in parameter.options]
-                parameter_schema: dict[str, Any] = {"type": "array", "items": item_schema}
-            else:
-                parameter_schema = (
-                    {
-                        "type": parameter.type.as_normal_type(),
-                        "description": parameter.llm_description or "",
-                    }
-                    if parameter.input_schema is None
-                    else deepcopy(parameter.input_schema)
-                )
+            parameter_schema: dict[str, Any] = (
+                {
+                    "type": parameter.type.as_normal_type(),
+                    "description": parameter.llm_description or "",
+                }
+                if parameter.input_schema is None
+                else deepcopy(parameter.input_schema)
+            )
             parameter_schema.setdefault("description", parameter.llm_description or "")
 
-            if (
-                not is_multiple_select
-                and parameter.type == ToolParameter.ToolParameterType.SELECT
-                and parameter.options
-            ):
+            if parameter.type == ToolParameter.ToolParameterType.SELECT and parameter.options:
                 parameter_schema["enum"] = [option.value for option in parameter.options]
 
             schema["properties"][parameter.name] = parameter_schema

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